@rasensio/aidlc-content 0.6.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rasensio/aidlc-content",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "templates/",
+    "guidance/",
+    "capabilities/",
+    "phases/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "fast-check": "^3.23.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}

package/skills/00-overview.md

@@ -0,0 +1,74 @@
+---
+name: aidlc-overview
+description: Framework overview and state protocol for the AI Development Lifecycle
+phase: ideation
+priority: 100
+---
+# AIDLC Framework Overview
+
+You are operating within the AI Development Lifecycle (AIDLC) framework. This skill defines how you interact with lifecycle state and follow phase-driven development.
+
+## Lifecycle Phases
+
+The AIDLC defines seven ordered phases. Not all apply to every task:
+
+1. **Ideation** — Problem exploration, goals, constraints
+2. **Requirements** — Acceptance criteria, user stories, scope
+3. **Design** — Architecture, interfaces, data flow
+4. **Implementation** — Code production following the design
+5. **Testing** — Verification against requirements
+6. **Deployment** — Release preparation and execution
+7. **Maintenance** — Monitoring, iteration, documentation updates
+
+## Cycle Scopes
+
+| Scope | Starting Phase | Applicable Phases |
+|-------|---------------|-------------------|
+| Full | Ideation | All seven phases |
+| Standard | Requirements | Requirements through Deployment |
+| Micro | Implementation | Implementation and Testing only |
+
+## State Protocol
+
+All state lives in `.aidlc/state/<instance-name>/`. Read and write state as follows:
+
+### Reading State
+
+1. Read `instance.yaml` to determine: current phase, template, scope, owner, claim
+2. Read `phase-<name>.yaml` for per-phase status and artifact completion
+3. Read `transitions.log` (NDJSON) for history — one JSON object per line
+
+### Writing State
+
+1. **Before mutating state**, check for an existing Instance_Claim in `instance.yaml`. If another session holds the claim and it is not stale, warn and request override confirmation.
+2. Record your session identifier in the claim fields when you begin work.
+3. Update phase state files as you produce artifacts.
+4. Append a transition record to `transitions.log` only on successful phase transitions.
+
+### Transition Records
+
+Each line in `transitions.log` is a JSON object:
+```json
+{"timestamp":"<ISO 8601 UTC>","author":"<session-id>","from":"<phase>","to":"<phase>","type":"normal|skip|upgrade","criteria":["..."]}
+```
+
+## Context and Guidance
+
+- Project context lives in `.aidlc/context/` (style-guide.md, architecture.md)
+- Guidance layers live in `.aidlc/guidance/` — load only those listed in `index.yaml`
+- Load context relevant to the current phase; avoid re-reading unchanged files
+
+## Security
+
+Before executing any sensitive operation (infrastructure changes, permission modifications, file deletions), you MUST:
+1. Describe the operation and its impact to the user
+2. Wait for explicit confirmation
+3. If cancelled, halt and log the cancellation
+
+Never store credentials, tokens, or secrets in state files or artifacts.
+
+## Token Efficiency
+
+- Read compact state files, not full artifacts, to determine progress
+- Use Artifact_Summaries (`<artifact>.summary.md`) when available
+- Load only the skill for the current phase, not all skills at once

package/skills/01-getting-started.md

@@ -0,0 +1,131 @@
+---
+name: aidlc-getting-started
+description: Helps users get started with AIDLC — responds to onboarding questions, suggests templates, and guides first steps
+phase: ideation
+priority: 95
+trigger: When the user asks how to get started, how to use the framework, or asks about fixing bugs, adding features, or beginning work
+---
+# Getting Started with AIDLC
+
+## Pre-condition: First Activation
+
+Before responding with this skill, check whether `.aidlc/context/` exists and contains at least one `.md` file. If it does NOT, defer to the **aidlc-first-activation** skill instead — it will scan the project, build context docs, and then hand control back to the user's original request. Do not proceed with getting-started guidance until first-activation has completed.
+
+## When to Activate
+
+Respond using this skill when the user asks any of the following:
+- "How do I get started?"
+- "How do I fix a bug?"
+- "How do I add a feature?"
+- "What should I do first?"
+- "How does this lifecycle thing work?"
+- "What template should I use?"
+- "Help me start working on X"
+
+## Quick Answers
+
+### "How do I fix a bug?"
+
+1. Start a bugfix lifecycle instance:
+   ```
+   aidlc start bugfix --name <short-description>
+   ```
+2. This creates a focused workflow: reproduce the bug → fix it → test it → deploy.
+3. Run `aidlc continue <name>` to see what step to do next.
+4. The bugfix template skips the design phase and requires a `reproduction.md` artifact first.
+
+### "How do I add a feature?"
+
+For a small, well-defined feature:
+```
+aidlc start quick-feature --name <feature-name>
+```
+
+For a larger feature needing design and review:
+```
+aidlc start full-feature --name <feature-name>
+```
+
+For something tiny (just code + test):
+```
+aidlc start micro-task --name <task-name>
+```
+
+### "How do I explore an idea or do research?"
+
+```
+aidlc start spike --name <research-topic>
+```
+This gives you Ideation + Requirements phases only — no implementation pressure.
+
+### "What should I do next?"
+
+Run:
+```
+aidlc continue
+```
+This tells you exactly which artifact to produce or which phase to enter next.
+
+### "How do I check progress?"
+
+```
+aidlc status
+```
+Shows all active lifecycle instances with completion %, current phase, and stall detection.
+
+### "How does the lifecycle work?"
+
+AIDLC guides your work through phases:
+
+1. **Ideation** — What are we building and why?
+2. **Requirements** — What are the acceptance criteria?
+3. **Design** — How will we build it?
+4. **Implementation** — Write the code
+5. **Testing** — Verify it works
+6. **Deployment** — Ship it
+7. **Maintenance** — Keep it running
+
+Not every task needs all phases. The templates handle this:
+- **micro-task** → Implementation + Testing only
+- **quick-feature** → Requirements through Deployment
+- **full-feature** → All 7 phases with review gates
+- **bugfix** → Requirements (reproduction) + Implementation + Testing + Deployment
+- **spike** → Ideation + Requirements (research) only
+
+### "How do I set up AIDLC in this project?"
+
+If AIDLC is already installed (you can see `.aidlc/skills/` in the project), just start using it:
+```
+aidlc start <template>
+```
+
+If not installed yet:
+```
+aidlc setup
+```
+This runs an interactive wizard that configures the framework for your project.
+
+## Choosing the Right Template
+
+| You want to... | Use this template | Scope |
+|---------------|-------------------|-------|
+| Fix a bug | `bugfix` | Standard (no design) |
+| Add a small feature | `quick-feature` | Standard |
+| Build something complex | `full-feature` | Full (with review gates) |
+| Just write code + test | `micro-task` | Micro |
+| Research / explore | `spike` | Ideation + Requirements |
+
+## After Starting
+
+Once you've started an instance, the framework tracks your progress. At any point:
+- `aidlc continue` — what to do next
+- `aidlc status` — overall progress
+- `aidlc gate <instance> <phase>` — check if a phase is complete
+- `aidlc transition <instance>` — advance to the next phase
+
+## State Location
+
+All lifecycle state lives in `.aidlc/state/<instance-name>/`. It's just YAML files — you can read them directly if needed. The key files are:
+- `instance.yaml` — which template, scope, and current phase
+- `phase-<name>.yaml` — artifact completion for each phase
+- `transitions.log` — history of phase transitions

package/skills/02-first-activation.md

@@ -0,0 +1,158 @@
+---
+name: aidlc-first-activation
+description: Auto-discovers a brownfield project on first activation — scans codebase, asks about extra context folders, writes context docs
+phase: ideation
+priority: 98
+trigger: When AIDLC is installed but `.aidlc/context/` does not exist or contains no files
+---
+# First Activation — Project Discovery
+
+## Purpose
+
+When AIDLC is freshly installed in an existing (brownfield) project, this skill runs once to build project context automatically. It replaces the need for the user to run `aidlc discover` from the terminal.
+
+## Activation Condition
+
+Activate this skill **before any other AIDLC skill** when ALL of the following are true:
+
+1. AIDLC skills are installed (`.aidlc/skills/` exists)
+2. The context directory is missing or empty (`.aidlc/context/` does not exist, or contains no `.md` files)
+3. The user has just sent a message (any message — they may be asking to fix a bug, add a feature, etc.)
+
+If `.aidlc/context/` already contains at least one `.md` file, skip this skill entirely and proceed with the user's request using the appropriate skill.
+
+## Behavior
+
+### Step 1: Acknowledge and Scan
+
+Tell the user briefly that you're indexing the project for the first time. Keep it short — don't block them with a wall of text.
+
+Example: *"First time here — let me scan the project quickly so I have context."*
+
+Then perform a lightweight scan:
+
+1. **Read manifest files** at the project root: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `Gemfile`, or equivalent.
+2. **List top-level directories** to understand the project structure.
+3. **Sample 3-5 source files** from the primary source directory to detect:
+   - Indentation style (tabs, 2-space, 4-space)
+   - Naming convention (camelCase, snake_case, PascalCase)
+   - Import style (grouped vs ungrouped)
+4. **Identify the tech stack**: language(s), frameworks, test runner, build tool, linter.
+
+### Step 2: Ask About Extra Context Folders
+
+After scanning, ask the user:
+
+> "I've got the basics — [summarize: language, framework, structure in one line].
+>
+> Beyond the source code, are there any folders I should be aware of for ongoing context? For example: specs, roadmap, architecture decisions, API schemas, design docs, etc."
+
+Wait for the user's answer. Common examples:
+- `specs/`, `docs/`, `roadmap/`, `architecture/`, `adr/`, `design/`, `api/`
+- The user might also point to specific files like `ARCHITECTURE.md` or `openapi.yaml`
+
+If the user says "no" or "that's it," proceed without extra folders.
+
+### Step 3: Read Extra Context
+
+For each folder or file the user mentions:
+1. List its contents (non-recursive, top level only for folders)
+2. Read key files (prefer: index files, READMEs, YAML/JSON schemas, markdown docs)
+3. Summarize what you found — don't copy entire documents verbatim
+
+Cap this step: read at most 10 files total from extra context folders. If there's more, note what was skipped and tell the user they can point you at specific files later.
+
+### Step 4: Write Context Documents
+
+Create `.aidlc/context/` and write:
+
+#### `style-guide.md`
+```markdown
+---
+generated_by: aidlc-first-activation
+generated_at: <ISO 8601 UTC>
+---
+# Style Guide
+
+## Languages
+<table of languages with approximate file counts>
+
+## Conventions
+- Indentation: <detected>
+- Naming: <detected>
+- Import style: <detected>
+
+## Frameworks & Tools
+<list of detected frameworks, test runners, build tools>
+```
+
+#### `architecture.md`
+```markdown
+---
+generated_by: aidlc-first-activation
+generated_at: <ISO 8601 UTC>
+---
+# Architecture Overview
+
+## Tech Stack
+<primary languages and frameworks>
+
+## Directory Structure
+<role mapping of top-level directories>
+
+## Entry Points
+<detected entry points>
+
+## Configuration
+<config approach: env vars, YAML, etc.>
+```
+
+#### `project-knowledge.md` (only if the user provided extra folders)
+```markdown
+---
+generated_by: aidlc-first-activation
+generated_at: <ISO 8601 UTC>
+source_paths:
+  - <path1>
+  - <path2>
+---
+# Project Knowledge
+
+## Sources
+<list of folders/files the user pointed to>
+
+## Summary
+
+### <Folder/File 1 Name>
+<2-5 sentence summary of what's in there and what's relevant>
+
+### <Folder/File 2 Name>
+<2-5 sentence summary>
+
+## Key References
+<specific files worth reading in full when working on related areas>
+```
+
+### Step 5: Confirm and Continue
+
+After writing the context docs, briefly confirm:
+
+> "Done — indexed the project. Context saved to `.aidlc/context/`. Now, back to your request..."
+
+Then **immediately proceed** with whatever the user originally asked. Do not make them repeat themselves. Their original message is still the active task — discovery was a transparent preamble.
+
+## Important Notes
+
+- **This skill runs exactly once per project.** After context docs are written, it never triggers again.
+- **Don't over-scan.** This is a lightweight pass, not a full AST analysis. 3-5 sampled files is enough for style detection.
+- **Don't block the user.** The scan should feel like a 10-second preamble, not a separate workflow. If the project is huge, just scan what you can quickly and note gaps.
+- **Respect .gitignore patterns.** Don't scan `node_modules/`, `dist/`, `build/`, `.git/`, etc.
+- **Extra context is optional.** If the user says "nah, just the code" — that's fine. Skip `project-knowledge.md`.
+- **The user's original request takes priority.** Discovery enables better answers but must not derail the conversation.
+
+## Exit Criteria
+
+- `.aidlc/context/style-guide.md` exists with detected conventions
+- `.aidlc/context/architecture.md` exists with structure overview
+- `.aidlc/context/project-knowledge.md` exists (if extra folders were provided)
+- The user's original request is being addressed (not abandoned)

package/skills/10-ideation.md

@@ -0,0 +1,45 @@
+---
+name: aidlc-ideation
+description: Guides the Ideation phase — exploring the problem space, defining goals and constraints
+phase: ideation
+priority: 50
+---
+# Ideation Phase
+
+## Purpose
+
+Explore the problem space before committing to a solution. Define what we are building, why, and what constraints exist.
+
+## Entry Criteria
+
+- A lifecycle instance has been created with a Full scope
+- The instance is claimed by this session
+
+## Required Artifacts
+
+- `ideation.md` — Problem statement, goals, constraints, initial ideas, and open questions
+
+## Instructions
+
+1. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
+2. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
+3. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).
+4. **Identify unknowns.** List open questions that need answers before requirements can be written.
+5. **Summarize.** Write `ideation.md` with sections: Problem Statement, Goals, Constraints, Explored Options, Open Questions.
+
+## Exit Criteria
+
+- `ideation.md` exists and contains at minimum a problem statement and one defined goal
+- The user has confirmed the direction (which option to pursue or a synthesis)
+
+## Guidance
+
+{{guidance:secure-defaults}}
+
+## Security Confirmation
+
+If any ideation option involves sensitive operations (new credentials, infrastructure provisioning, access control changes), flag it explicitly and note that confirmation will be required before execution in later phases.
+
+## Completion
+
+When exit criteria are met, update `phase-ideation.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/20-requirements.md

@@ -0,0 +1,54 @@
+---
+name: aidlc-requirements
+description: Guides the Requirements phase — defining acceptance criteria and user stories
+phase: requirements
+priority: 50
+---
+# Requirements Phase
+
+## Purpose
+
+Translate the ideation output (or the user's direct request) into precise, testable acceptance criteria.
+
+## Entry Criteria
+
+- Ideation phase complete (Full scope) OR instance created with Standard scope
+- The instance is claimed by this session
+
+## Required Artifacts
+
+- `requirements.md` — User stories, acceptance criteria, scope boundaries, non-functional requirements
+
+## Instructions
+
+1. **Gather requirements.** If a Full scope, read `ideation.md` for context. Otherwise, ask the user to describe desired behavior.
+2. **Write user stories.** Use the format: "As a [role], I want [capability], so that [benefit]."
+3. **Define acceptance criteria.** Each criterion must be:
+   - Specific and unambiguous
+   - Testable (an observable outcome)
+   - Independent (not relying on unstated assumptions)
+4. **Set scope boundaries.** Explicitly state what is NOT included.
+5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
+6. **For complex input**: If requirements are extensive, create an Input_File at `.aidlc/inbox/requirements-input.md` with structured sections for the user to fill in, rather than asking many sequential questions.
+
+## Exit Criteria
+
+- `requirements.md` exists with at least one user story and corresponding acceptance criteria
+- Each acceptance criterion is testable (has an observable pass/fail condition)
+- The user has confirmed the requirements are complete for the chosen scope
+
+## Guidance
+
+{{context:style-guide}}
+{{guidance:secure-defaults}}
+
+## Security Confirmation
+
+If requirements reference sensitive data handling, authentication flows, or access control:
+1. Explicitly document the security requirements as acceptance criteria
+2. Flag that a security review will be needed before deployment
+3. Never embed credentials or secrets in requirement examples
+
+## Completion
+
+When exit criteria are met, update `phase-requirements.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/30-design.md

@@ -0,0 +1,57 @@
+---
+name: aidlc-design
+description: Guides the Design phase — architecture decisions, interfaces, and data flow
+phase: design
+priority: 50
+---
+# Design Phase
+
+## Purpose
+
+Produce a technical design that satisfies the requirements. Define architecture, interfaces, data models, and integration points before writing code.
+
+## Entry Criteria
+
+- Requirements phase complete
+- The instance is claimed by this session
+
+## Required Artifacts
+
+- `design.md` — Architecture overview, component design, interfaces, data flow, and design decisions with rationale
+
+## Instructions
+
+1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges.
+2. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
+3. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
+4. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
+5. **Design decisions.** Record each significant decision with rationale and alternatives considered.
+6. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
+7. **Identify risks.** Note technical risks and mitigation strategies.
+
+## Exit Criteria
+
+- `design.md` exists with architecture, interfaces, and at least one design decision with rationale
+- The design addresses all acceptance criteria from `requirements.md`
+- The user has confirmed the design direction
+
+## Guidance
+
+{{context:architecture}}
+{{context:style-guide}}
+{{guidance:secure-defaults}}
+{{guidance:accessibility}}
+
+## Security Confirmation
+
+If the design involves:
+- New authentication or authorization flows
+- Data storage of sensitive information
+- External service integrations with credentials
+- Infrastructure provisioning
+
+You MUST flag these explicitly in the design document and note that implementation will require security confirmation before proceeding.
+
+## Completion
+
+When exit criteria are met, update `phase-design.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/40-implementation.md

@@ -0,0 +1,64 @@
+---
+name: aidlc-implementation
+description: Guides the Implementation phase — writing code following the design and project conventions
+phase: implementation
+priority: 50
+---
+# Implementation Phase
+
+## Purpose
+
+Produce working code that satisfies the design and requirements. Follow project conventions discovered in context docs.
+
+## Entry Criteria
+
+- Design phase complete (Full/Standard scope) OR instance created with Micro scope (task description + criteria exist)
+- The instance is claimed by this session
+
+## Required Artifacts
+
+- Source code changes implementing the feature or fix
+- Updated or new tests (handed off to Testing phase for verification)
+
+## Instructions
+
+1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns.
+2. **Load guidance.** Read all active Guidance_Layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
+3. **Plan the work.** Break the implementation into discrete steps. For Micro scope, reference the task description and acceptance criteria directly.
+4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
+5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation:
+   - File deletions or destructive operations
+   - Infrastructure changes (provisioning, configuration)
+   - Permission or access control modifications
+   - Credential or secret handling
+6. **Commit incrementally.** Produce working code at each step; avoid large uncommittable diffs.
+7. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
+
+## Exit Criteria
+
+- All acceptance criteria from requirements are addressed in code
+- Code follows project style (naming, formatting, patterns from context docs)
+- No unresolved TODOs or placeholder implementations remain for required functionality
+- Guidance layer rules have been applied (security defaults, accessibility, API conventions)
+
+## Guidance
+
+{{context:style-guide}}
+{{context:architecture}}
+{{guidance:secure-defaults}}
+{{guidance:accessibility}}
+{{guidance:api-conventions}}
+
+## Security Confirmation
+
+Before proceeding with any sensitive operation during implementation:
+1. Describe what the operation does and what it affects
+2. State whether it is reversible
+3. Wait for explicit user acknowledgment
+4. If the user cancels, halt execution and log the cancellation with a timestamp in state
+
+Never store credentials, API keys, tokens, or passwords in source code or state files. Use placeholder syntax for secrets (e.g., `${SECRET_NAME}`).
+
+## Completion
+
+When exit criteria are met, update `phase-implementation.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/50-testing.md

@@ -0,0 +1,60 @@
+---
+name: aidlc-testing
+description: Guides the Testing phase — verifying implementation against requirements
+phase: testing
+priority: 50
+---
+# Testing Phase
+
+## Purpose
+
+Verify that the implementation satisfies all acceptance criteria. Produce evidence of correctness through automated tests and manual verification where needed.
+
+## Entry Criteria
+
+- Implementation phase complete
+- The instance is claimed by this session
+
+## Required Artifacts
+
+- Test files covering acceptance criteria
+- `testing.md` — Test plan, results summary, and coverage notes
+
+## Instructions
+
+1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test.
+2. **Write automated tests.** Follow the project's existing test patterns:
+   - Unit tests for pure logic and edge cases
+   - Integration tests for component interactions
+   - Property-based tests where inputs have broad domains
+3. **Run tests.** Execute the project's test suite. All new tests must pass.
+4. **Document results.** Write `testing.md` with:
+   - Test plan (what was tested and why)
+   - Results (pass/fail counts, any notable findings)
+   - Coverage notes (which criteria are covered, any gaps)
+5. **Address failures.** If tests reveal bugs, fix the implementation. Do not skip or weaken tests to force a pass.
+
+## Exit Criteria
+
+- All acceptance criteria have corresponding test coverage
+- All tests pass
+- `testing.md` exists with results summary
+- No critical bugs remain open
+
+## Guidance
+
+{{context:style-guide}}
+{{guidance:secure-defaults}}
+
+## Security Confirmation
+
+If testing requires:
+- Access to production-like environments
+- Use of real credentials or sensitive data
+- Execution of destructive operations (even in test environments)
+
+You MUST describe the action, confirm it targets a safe environment, and wait for user acknowledgment before proceeding.
+
+## Completion
+
+When exit criteria are met, update `phase-testing.yaml` status to `complete` and append a transition record to `transitions.log`.