@rasensio/aidlc-content 0.7.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "0.7.0",
+  "version": "1.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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,30 @@ 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.
 
 ## Context and Guidance
 

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.