@rasensio/aidlc-content 1.15.1 → 1.16.0

package/package.json

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

package/skills/10-ideation.md

@@ -30,7 +30,7 @@ and open questions.
 
 > {{glossary:artifact}}
 
-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. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+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 — it is the cheapest way to find where in the code to look, and re-exploring what it already covers wastes the phase. It is an index, not an authority: a specific symbol it names may have been renamed or deleted by a later instance, so open the source before treating any named component, table, or registry as real. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
 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).

package/skills/30-design.md

@@ -26,14 +26,15 @@ Produce a technical design that satisfies the requirements. Define architecture,
 > {{glossary:gate}}
 
 1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges. When requirements carry `AC-n` IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
-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. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
-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.
-9. **Produce the task breakdown.** For templates that require it (full-feature, quick-feature), write `tasks.md` in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
+2. **Consult the knowledge graph, then check it against the source.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions. The graph is an index into the code, not an authority over it: an entry naming a component, table, column, function, or registry is a pointer to open, and an entry written by an earlier instance may name something a later one renamed or deleted. Confirm a named symbol exists in the source before designing against it — `aidlc knowledge verify <id>` records that you did, and `aidlc knowledge update <id>` corrects an entry that no longer matches. A design built on a symbol that is not there produces code against an API nobody has, and nothing downstream catches it until implementation. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+3. **Find the seams before proposing structure.** A project is brownfield from its second instance onwards, so start from the assumption that something in the codebase already does part of what the requirements ask for. For each capability in `requirements.md`, locate and read the existing code that carries any of it — the scheduler that already fires, the settings shape that already persists, the registry that already dispatches — and name those files in `design.md` before describing a single new component. Keep it narrow: the seams the requirements actually touch, a handful of files, not a survey. When nothing exists, write that down — "no existing seam" is a finding, and stating it is what separates a genuinely new component from one designed alongside the code that should have absorbed it.
+4. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate. Say for each one whether it extends a seam found in step 3 or is new.
+5. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
+6. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
+7. **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>"`.
+8. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
+9. **Identify risks.** Note technical risks and mitigation strategies.
+10. **Produce the task breakdown.** For templates that require it (full-feature, quick-feature), write `tasks.md` in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
 
    ```
    - [ ] T<n>: <title>
@@ -47,6 +48,8 @@ Produce a technical design that satisfies the requirements. Define architecture,
 ## Exit Criteria
 
 - `design.md` exists with architecture, interfaces, and at least one design decision with rationale
+- `design.md` names the existing code the change extends, or states that no such code exists
+- Every knowledge-graph symbol the design builds on was checked against the source
 - The design addresses all acceptance criteria from `requirements.md`
 - For templates requiring it: `tasks.md` exists and every active acceptance criterion is claimed by at least one task, or the gap is deliberate
 - The user has confirmed the design direction

package/skills/40-implementation.md

@@ -26,7 +26,7 @@ Produce working code that satisfies the design and requirements. Follow project
 
 > {{glossary:gate}}
 
-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.
+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 — as an index into the source, never a substitute for reading it. Open the file before calling anything the graph names; an entry can outlive the symbol it describes.
 2. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
 3. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).