@rasensio/aidlc-content 0.7.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "0.7.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,10 @@
     "capabilities/",
     "phases/"
   ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
@@ -31,9 +35,5 @@
     "fast-check": "^3.23.2",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run"
   }
-}
+}

package/skills/00-overview.md

@@ -44,6 +44,7 @@ All state lives in `.aidlc/state/<instance-name>/`. Read and write state as foll
 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.
+5. After a successful phase transition, fire lifecycle actions: `on-phase-exit` for the phase you left, then `on-phase-enter` for the phase you entered (see **Lifecycle Actions**).
 
 ### Transition Records
 
@@ -83,7 +84,34 @@ The `aidlc start` CLI automates this; when it is not available, create the insta
        status: not-started
    metrics: { elapsed_seconds: 0, artifact_count: 0 }
    ```
-5. Report the instance name, phases, and state path, then begin the initial phase with its skill.
+5. Fire the `on-instance-start` lifecycle actions (see **Lifecycle Actions**). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it.
+6. Report the instance name, phases, state path, and any actions that fired, then begin the initial phase with its skill.
+
+## Lifecycle Actions
+
+`.aidlc/actions.yaml` declares automation the user wants to run on lifecycle events. The `aidlc` CLI fires these automatically; **when you manage state directly (without the CLI), you are the event dispatcher** and must fire them yourself.
+
+On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exit`, `on-instance-complete`, `on-artifact-created`:
+
+1. Read `.aidlc/actions.yaml` (if absent, skip this protocol).
+2. Select actions where `enabled: true`, `event` matches, and any `phase` filter matches the current phase.
+3. For each matched action with a `run` script: execute it as a shell command with these environment variables set: `AIDLC_EVENT`, `AIDLC_INSTANCE`, `AIDLC_PHASE`, `AIDLC_TEMPLATE`.
+4. Actions marked `use` (built-ins) require the CLI — run `aidlc transition`/`aidlc start` for those, or tell the user the action needs the CLI.
+5. If an action fails and it is `blocking: true`, stop and report the failure to the user before continuing the lifecycle. If `blocking: false`, report and continue.
+6. Report every action you ran and its outcome — never run configured automation silently.
+
+## User Input Protocol (Inbox)
+
+When a phase needs substantial input from the user — open decisions, structured requirements, extensive details — write an Input_File to `.aidlc/inbox/` instead of asking many sequential chat questions or scattering files in ad-hoc locations (`temp/`, project root):
+
+1. Name the file `<instance>-<topic>.md` (e.g. `local-knowledge-graph-open-decisions.md`).
+2. Give each question its own section: plain-language background first (assume the user has not read the underlying spec), then the options as `- [ ]` checkboxes with trade-offs spelled out. Mark your recommendation.
+3. Tell the user the file path and wait for their edits — do not proceed on unanswered questions.
+4. When the user has answered, fold the outcomes into the phase artifact and state records. The inbox file is scratch input, not an artifact — offer to delete it once its content has landed.
+
+## Idea Capture
+
+When the user shares an idea tangential to the current work, offer to record it in `.aidlc/ideas/` (see **aidlc-idea**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.
 
 ## Context and Guidance
 

package/skills/03-entry-point.md

@@ -23,6 +23,7 @@ If `.aidlc/context/` does not exist or contains no `.md` files, defer to the **a
 1. List the directories under `.aidlc/state/`. Each directory is a lifecycle instance.
 2. For each instance, read `instance.yaml` (current phase, template, scope, claim) and the `phase-<name>.yaml` files to compute completion (complete artifacts ÷ total required artifacts).
 3. Read `.aidlc/config.yaml` for project defaults (scope, template) if present.
+4. Count ideas in `.aidlc/ideas/` by status — read only the frontmatter (and title line if needed), never idea bodies.
 
 Do not read artifact bodies or transition history to build the menu — the compact state files are enough.
 
@@ -32,13 +33,15 @@ Compose a short menu from the state. Include only the options that make sense:
 
 - **Continue `<instance>`** — one entry per incomplete instance, showing current phase and completion percentage. Most recently updated first.
 - **Start something new** — always.
+- **Capture an idea** — always.
+- **Browse / promote ideas** — when `.aidlc/ideas/` contains at least one non-dropped idea; show the raw count (e.g. "4 raw ideas").
 - **Show status** — when at least one instance exists.
 - **Review an artifact** — when at least one instance has a completed artifact.
 - **Help / getting started** — always.
 
 Present the options as a numbered list (or the platform's native selection prompt) and wait for a choice. If the user's message already states what they want (e.g. "continue my-feature"), skip the menu and route directly.
 
-If `.aidlc/state/` is empty or missing, offer just two options: start something new, or help.
+If `.aidlc/state/` is empty or missing, offer just three options: start something new, capture an idea, or help.
 
 ## Step 3 — Route
 
@@ -46,7 +49,9 @@ If `.aidlc/state/` is empty or missing, offer just two options: start something
 |--------|--------|
 | Continue an instance | Follow the **aidlc-continue** skill |
 | Start something new | Ask what they are building, pick a template (see **aidlc-getting-started**), then create the instance per "Creating an Instance" in **aidlc-overview** |
-| Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled |
+| Capture an idea | Follow the **aidlc-idea** skill (capture flow) |
+| Browse / promote ideas | Follow the **aidlc-idea** skill (browse/promote flow) |
+| Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the backlog is non-empty, append the idea count (e.g. "4 ideas in backlog, 3 raw") |
 | Review an artifact | Follow the **aidlc-review** skill |
 | Help / getting started | Follow the **aidlc-getting-started** skill |
 

package/skills/04-idea-capture.md

@@ -0,0 +1,57 @@
+---
+name: aidlc-idea
+description: Captures ideas into the .aidlc/ideas/ backlog at any moment — no instance, claim, or phase required — and browses or promotes backlog ideas into lifecycle instances
+phase: ideation
+priority: 90
+trigger: When the user says "idea:", asks to capture/record an idea, wants to browse the idea backlog, or wants to promote an idea into an instance
+native_mode_hint:
+  claude-code: >-
+    This skill is an interactive inbox, not a phase artifact. Do not enter
+    plan mode. Capture is a single write-and-confirm; never touch instance
+    state while capturing.
+---
+# Idea Capture and Backlog
+
+`.aidlc/ideas/` is a first-class inbox, independent of every lifecycle phase. Ideas are captured cheaply now and converted into instances later. Capture is legal at any moment: mid-implementation on another instance, from a second session, or with no instance at all.
+
+## Idea File Format
+
+One file per idea: `.aidlc/ideas/YYYYMMDD-<slug>.md`, beginning with exactly this frontmatter:
+
+```yaml
+---
+status: raw          # raw | promoted | dropped
+promoted_to: null    # instance name once promoted, else null
+---
+```
+
+Ideas never silently vanish — they are `raw`, `promoted`, or explicitly `dropped` (the file stays in place). `status: promoted` always carries a non-null `promoted_to` naming an existing instance.
+
+## Capture
+
+1. **Resolve the backlog root.** Always write to the **primary checkout's** `.aidlc/ideas/`, never a worktree's copy: resolve via `git rev-parse --git-common-dir` (the directory containing that path is the primary checkout). Outside a git repo, use the current project root. Create `.aidlc/ideas/` if missing.
+2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug derived from the idea.
+3. **Handle collisions.** If the filename already exists, ask one question — extend `<existing>` or new idea? On extend, append a dated `## Update (YYYY-MM-DD)` section; on new, suffix the slug (`-2`). Never silently overwrite.
+4. **Write the file.** Frontmatter (`status: raw`, `promoted_to: null`), then `# Idea: <title>`, `**Date:**`, and the braindump organized lightly (a Use Case section plus whatever structure the content suggests). Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
+5. **Confirm and return.** Report the file path and return to whatever was happening.
+
+**Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
+
+If the user includes credentials, tokens, or secrets in a braindump, flag it and omit them from the file.
+
+## Browse
+
+List `.aidlc/ideas/*.md` reading only frontmatter and the `# Idea:` title line — not the bodies. Show each idea's date, title, and status. Offer to open, promote, or drop.
+
+## Promote
+
+Promotion is where the backlog meets the lifecycle:
+
+1. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
+2. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.
+3. Seed the instance with the idea file: Full scope → the idea is raw material the Ideation phase refines into `ideation.md`; Standard scope → the idea is input context for Requirements.
+4. Update the idea's frontmatter: `status: promoted`, `promoted_to: <instance-name>`.
+
+## Drop
+
+Set `status: dropped` in the frontmatter and leave the file in place. Dropping is an explicit act — never delete or overwrite an idea to get rid of it.

package/skills/10-ideation.md

@@ -21,16 +21,19 @@ Explore the problem space before committing to a solution. Define what we are bu
 
 ## 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.
+1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — the graph is the first source of understanding; re-explore only what it doesn't cover.
+2. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
+3. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
+4. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).
+5. **Identify unknowns.** List open questions that need answers before requirements can be written.
+6. **Record discoveries in the knowledge graph.** Persist what you learned about the codebase with `aidlc knowledge add` / `relate` (modules, services, conventions, debt). On a brownfield project, seed the graph first with `aidlc discover`. The phase gate requires at least 3 module entities, 2 depends-on relationships, and 1 convention entity.
+7. **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)
+- When the project uses the knowledge graph: it contains ≥3 module entities, ≥2 depends-on relationships, and ≥1 convention entity (checked automatically by `aidlc gate` / `aidlc transition`)
 
 ## Guidance
 

package/skills/20-requirements.md

@@ -29,7 +29,7 @@ Translate the ideation output (or the user's direct request) into precise, testa
    - 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.
+6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an Input_File in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.
 
 ## Exit Criteria
 

package/skills/30-design.md

@@ -22,12 +22,13 @@ Produce a technical design that satisfies the requirements. Define architecture,
 ## 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.
+2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code.
+3. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
+4. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
+5. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
+6. **Design decisions.** Record each significant decision with rationale and alternatives considered. Persist accepted decisions as `decision` entities: `aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>"`.
+7. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
+8. **Identify risks.** Note technical risks and mitigation strategies.
 
 ## Exit Criteria
 

package/skills/40-implementation.md

@@ -22,7 +22,7 @@ Produce working code that satisfies the design and requirements. Follow project
 
 ## Instructions
 
-1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns.
+1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes.
 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).
@@ -32,7 +32,8 @@ Produce working code that satisfies the design and requirements. Follow project
    - 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`.
+7. **Update the knowledge graph.** After modifying code, record what changed with `aidlc knowledge add` / `relate` / `update`: new or restructured modules, decisions taken, debt introduced or paid down. Keep the graph in sync with the code you just changed.
+8. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
 
 ## Exit Criteria
 

package/skills/70-maintenance.md

@@ -27,7 +27,7 @@ Ensure the deployed feature remains healthy. Update documentation, address feedb
    - Architecture docs updated if new components were added
    - API docs updated if endpoints changed
 3. **Gather feedback.** Collect user/team feedback on the delivered feature.
-4. **Record known issues.** Document any edge cases, limitations, or technical debt introduced.
+4. **Record known issues.** Document any edge cases, limitations, or technical debt introduced. If the project has a knowledge graph, record debt as entities (`aidlc knowledge add --type debt …`) and update facts invalidated by code changes (`aidlc knowledge update` / `verify`); list candidates with `aidlc knowledge stale --check-git`.
 5. **Plan follow-up.** If feedback or monitoring reveals needed improvements, document them as potential future lifecycle instances.
 6. **Close the instance.** When maintenance tasks are complete, mark the lifecycle instance as done.
 

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Rodrigo Asensio
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.