ai-spector 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
   "type": "module",
   "license": "MIT",

package/scaffold/cursor/skills/ai-spector/references/cli-failures.md

@@ -1,185 +1,61 @@
-# CLI and tool failures (mandatory agent behavior)
+# CLI failures
 
-When any `ai-spector` command **fails** (non-zero exit, throws, or empty/invalid JSON when `--json` was required), or a **required tool** fails unexpectedly (MCP, terminal, network):
+**Load this file only when a CLI command fails.** Do not pre-load.
 
-1. **Pause** the current step — no templates, no subagents, no writing `docs/srs/**`, no silent fallbacks.
-2. **Report** using the response format below (verbatim CLI/tool output).
-3. **Offer recovery** — always present **fix and retry** (recommended) and, when safe, a **bounded workaround** the agent can execute if the user approves.
-4. **Wait for the user** (or apply [auto-fix without asking](#agent-may-fix-without-asking-small-local) only for trivial local fixes).
-5. After fix or approved workaround, **continue the same task** from the failed step (re-run the same CLI when possible).
+When any `ai-spector` command exits non-zero or returns invalid JSON:
 
-**Default:** fix and retry. **Workarounds** are allowed only with explicit user approval and the guardrails in [Workaround catalog](#workaround-catalog-user-approval-required).
+1. **Pause** — no writing, no silent fallbacks.
+2. **Report** with the format below.
+3. **Offer recovery** — fix + retry (default), or bounded workaround if approved.
+4. **Wait** — then continue the same task from the failed step.
 
----
-
-## Recovery flow
-
-```text
-Tool/CLI fails
-  → pause + report (Blocked format)
-  → propose Option 1 (fix & retry) + Option 2 (workaround, if any) + Option 3 (pause)
-  → user picks (or auto-fix for trivial cases)
-  → execute choice → re-run same CLI at next checkpoint when possible
-```
-
-| User says | Agent does |
-|-----------|------------|
-| **1**, “fix”, “retry”, “yes fix” | Apply fix steps (or ask for one missing input), re-run **the same** failed command/step |
-| **2**, “workaround”, “continue anyway” | Follow [Workaround catalog](#workaround-catalog-user-approval-required); state trade-offs; merge/validate when writing docs |
-| **3**, “pause”, “stop”, no reply yet | Stop; do not generate or bulk-read docs; user re-runs the task later |
-| “you figure it out” / “use your judgment” | Prefer **fix and retry** first; if blocked after one retry, propose the **smallest** approved workaround and ask once |
-
-Do **not** leave the user stuck with only “run `/analyze` again” when you can propose a concrete fix **or** a bounded workaround.
+Auto-fix without asking: typo in seed id, missing parent dir, wrong cwd — fix and retry once.
+Must ask user: deleting graph files, large manual edits, any workaround not listed below.
 
 ---
 
-## Forbidden (unless user explicitly approves a workaround)
-
-| Do not | Why |
-|--------|-----|
-| Hand-edit `traceability.graph.json` at scale | Bypasses merge/validate; drifts from `knowledge.json` |
-| Implement graph BFS/search in the agent | Duplicates `graph query` / `graph impact` |
-| Glob or read all of `docs/srs/**` because query failed | Hides missing graph or bad seed id |
-| Use `.ai-spector/index/*.md` as **primary** context when validate/query failed | Index is fallback only after **successful** CLI with thin graph |
-| Skip `graph merge` and “fill SRS from memory” | Breaks traceability |
-| Silently continue after `graph validate` errors | Generation will be wrong or inconsistent |
-| Tell the user “run this CLI yourself” without offering to run it | Agent owns CLI in this workflow |
-| Continue generation after CLI failure **without** user choosing fix, workaround, or pause | User must not be blocked silently or bypassed silently |
-
-**Allowed after successful CLI:** If `graph query --json` succeeds but `nodes` has no domain entries, say so and suggest **analyze** — still do not bulk-read `docs/srs/**`.
-
----
-
-## Response format (copy this structure)
-
-```markdown
-## Blocked: <task or slash-command> — <CLI | tool> failed
-
-**Command / tool:** `ai-spector <subcommand> …` or `<MCP tool name>`
-**Exit code:** <n> (if applicable)
+## Report format
 
-**Output:**
-\`\`\`
-<paste full stdout/stderr or tool error>
-\`\`\`
-
-**What this means:** <one or two sentences>
-
-**How to fix (recommended):**
-1. <step agent or user can take>
-2. <step>
-3. Re-run the same step: `<exact command>` or **/<slash-command>**
-
-**Workaround (optional):** <only if bounded and useful — e.g. “read these 2 projection paths and draft section X; merge after index recovers”>
-**Trade-off if workaround:** <traceability / staleness risk in plain language>
-
-**What would you like to do?**
-1. **Fix and retry** (recommended) — <one-line summary of fix path>
-2. **Workaround** — <one-line summary; skip only if none applies>
-3. **Pause** — stop here; you fix environment and say “retry” or re-run the task
-
-Reply with **1**, **2**, **3**, or tell me your preference.
 ```
-
-For **optional** steps (e.g. `graph visualize --open`), you may use a shorter **Interrupted** header but still offer fix vs skip.
-
----
-
-## Workaround catalog (user approval required)
-
-Use only when the user chooses **2** or explicitly accepts the trade-off. Prefer the **smallest** scope that unblocks the task; return to CLI as soon as it works.
-
-| Situation | Workaround | Guardrails | Restore traceability |
-|-----------|------------|------------|----------------------|
-| `graph query` fails once (cwd, typo) | Fix cwd/seed id; one retry | No doc writes until query succeeds | Re-run query before write |
-| `graph query` OK but thin `nodes` | Read only `projectionPaths` + cited `docs/data-source/**` | Named paths only; no `docs/srs/**` glob | `graph merge` + `validate` after draft |
-| `graph validate` — one bad id/edge | Patch **single** node/edge; re-validate | No mass graph surgery | `validate` must pass before next wave |
-| `graph merge` — one bad `listedInSection` | Fix id in `knowledge.json`; re-merge | No hand-merge of full graph | Same |
-| `index` fails on one path | Skip that path if command allows; fix path and re-index | Do not skip required wave index without user OK | Re-run **index** for skipped paths |
-| Optional visualize fails | Skip open; continue pipeline | User chose workaround | None |
-| Terminal/env (not git, missing `uv`) | Agent runs install/init steps user approves | No destructive deletes without ask | Re-run failed CLI |
-| Generation blocked only by **upstream** missing SRS | User approves generating prerequisite layer first | Run prerequisite wave with normal merge/validate | Full pipeline order |
-
-After any workaround that wrote docs or graph patches: **`graph validate`** (and **`index`** when the command doc requires) before the next wave.
+## Blocked: <command> failed
+**Command:** `ai-spector <subcommand>`  **Exit:** <n>
+**Output:** <paste stdout/stderr>
+**Means:** <one sentence>
+**Fix:** <steps> then re-run `<same command>`
+**Workaround (if any):** <bounded scope + trade-off>
+
+Reply: 1 Fix & retry  2 Workaround  3 Pause
+```
 
 ---
 
-## Common failures → fixes
-
-### `ai-spector: command not found`
-
-- **Means:** Package not installed or not on PATH.
-- **Fix:** `npm install ai-spector` in the project; agent uses `npx ai-spector …` from project root.
-
-### `Could not find project root` / missing `docflow.config.json`
-
-- **Means:** `init` not run or wrong working directory.
-- **Fix:** Run `npx ai-spector init` from project root; agent `cd`s to workspace root before CLI.
-
-### `ai-spector analyze` fails
-
-- **Means:** Registry/templates or graph bootstrap broke.
-- **Fix:** Show full error; check `.ai-spector/registry/section-registry.json` exists; re-run `init` if config is corrupt; do not proceed to merge.
-
-### `graph merge` — `No domain entries in knowledge.json`
-
-- **Means:** Analyze extract did not populate staging.
-- **Fix:** Re-run `/analyze`; ensure `docs/data-source/` has real markdown files with UC/F/actor content; fill `knowledge.json` with at least one `useCase` or `feature`.
-- **Workaround (user OK):** Manually add minimal entries to `knowledge.json` then re-merge.
-
-### `graph merge` — `Merge edge missing target node` / section id
-
-- **Means:** `listedInSection` points to a section id not in the graph.
-- **Fix:** Use a section id from `section-registry.json` (e.g. `sec.srs.3-use-cases.l3.3.32-list-use-case`) or omit `listedInSection` for defaults; re-run merge.
-
-### `graph validate` — `DOC-SECTION-COVERAGE` on `doc.bd.list-api` / `doc.bd.list-screen` / `doc.bd.db-design`
-
-- **Means:** Basic-design **list chapter** documents exist in the graph without child `section` nodes (common after a projection-only `graph merge` before bootstrap/index).
-- **Fix:** From project root run **`npx ai-spector index`** (or ask to **refresh index**). Ensure `.ai-spector/templates/basic_design/` exists (`npx ai-spector init`). Then re-run **`graph merge`** for your patch and **`graph validate`**.
-
-### `graph validate` — `DOMAIN-ANCHORED` / `SECTION-TREE` / `SCHEMA`
-
-- **Means:** Graph inconsistent with rules.
-- **Fix:** Paste each `[ERROR]` line; prefer re-run **analyze** (merge) over manual JSON surgery; for one bad id, agent may patch **only** that node/edge then re-validate.
-
-### `graph query <id>` — seed missing or empty subgraph
-
-- **Means:** Wrong id, or domain not merged.
-- **Fix:** Run **visualize-graph** or `graph query` with a known id from `knowledge.json`; run **analyze** if no `useCase`/`feature` nodes.
-
-### `graph query` — invalid JSON / parse error
-
-- **Means:** CLI crashed or wrong cwd.
-- **Fix:** Re-run from project root; if repeat, report as tool bug with full stderr.
-
-### `graph impact --git` — not a git repository / no changes
-
-- **Means:** `--git` needs a git working tree with staged or unstaged diffs.
-- **Fix:** Initialize git (`git init`) and make edits, or use **impact** with a short description, editor selection, or `--file` / `--heading` instead of `--git`.
-
-### `graph impact --git` — could not map diff to graph seeds
-
-- **Means:** Changed paths are not linked to `document` / `section` nodes (e.g. only `README.md` or `src/`).
-- **Fix:** Run impact on doc paths under `docs/` or `.ai-spector/`; or **impact** with a short description of the traceability change.
-
-### Stale graph or indexes after manual edits or generate SRS
-
-- **Means:** User changed `docs/data-source/`, SRS outputs, or templates without re-running ingest; graph still shows template-only domain nodes.
-- **Fix:** Run **`ai-spector index`**. For fully stale domain detail, re-run **`/analyze`** → fresh `knowledge.json`.
+## Common fixes
+
+| Error | Fix |
+|---|---|
+| `command not found` | `npm install ai-spector`; use `npx ai-spector` |
+| `Could not find project root` | Run `npx ai-spector init`; check cwd |
+| `analyze` fails | Show full error; check registry exists; re-run init if corrupt |
+| `merge` — no domain entries | Re-run `/analyze`; ensure data-source has UC/F/actor content |
+| `merge` — missing target node | Fix section id from `section-registry.json`; re-merge |
+| `validate` — DOC-SECTION-COVERAGE | Run `ai-spector index` then re-merge and re-validate |
+| `validate` — DOMAIN-ANCHORED / SCHEMA | Re-run analyze; patch only the single bad node/edge |
+| `graph query` — empty subgraph | Wrong id or domain not merged; run analyze first |
+| `graph query` — invalid JSON | Re-run from project root; report as bug if repeats |
+| `index` fails on one path | Fix the path; re-index; do not skip required wave index without user OK |
+| Stale graph after manual edits | `ai-spector index`; re-run `/analyze` for fully stale domain |
 
 ---
 
-## Agent may fix without asking (small, local)
+## Workarounds (user approval required)
 
-- Create missing parent dirs under `.ai-spector/` if `init` was incomplete.
-- Correct a **single** typo in `knowledge.json` id or `listedInSection` then re-run `graph merge`.
-- Re-run the **same** failed command once after an obvious fix (e.g. `cd` to project root).
-- Wrong CLI flags the agent introduced — fix and retry immediately.
+| Situation | Workaround | Restore |
+|---|---|---|
+| `graph query` thin nodes | Read `projectionPaths` + cited data-source files only (no `docs/srs/**` glob) | `graph merge` + validate after draft |
+| `validate` — one bad id/edge | Patch single node/edge; re-validate | Must pass before next wave |
+| `index` fails one path | Skip that path if allowed; re-index after fix | Re-run index |
+| Upstream SRS missing | Generate SRS prerequisite first (user approves) | Full pipeline order |
 
-## Agent must ask user before
+After any workaround that wrote docs: `graph validate` (+ `index` if required) before next wave.
 
-- Deleting `traceability.graph.json` or re-running `init --force`.
-- Large manual edits to graph or generated SRS.
-- Changing bundled templates or `workflow.dependencies.json`.
-- Any [workaround](#workaround-catalog-user-approval-required) not listed above or that skips **validate** before the next generation wave.
-- Bulk reads under `docs/srs/**` or `docs/basic-design/**` as primary context.
+**Forbidden without user approval:** hand-edit graph at scale · glob `docs/srs/**` as primary context · skip `graph merge` · continue generation after validate errors.

package/scaffold/cursor/skills/ai-spector/references/context-management.md

@@ -0,0 +1,157 @@
+# Context management during generation
+
+Long generation runs (full SRS, full basic design) accumulate raw graph JSON, template content, data-source files, and previous wave outputs in the context window. Past a certain size, this degrades accuracy — the model starts blending data from earlier targets into the current one.
+
+Two tools prevent this: **compaction checkpoints** and **sub-agent delegation**.
+
+---
+
+## Rule 1 — Compact at wave boundaries (mandatory)
+
+After every wave completes (merge + validate pass), compact the context **before starting the next wave**:
+
+```
+/compact
+```
+
+What to retain across the compaction (summarise into the compact prompt if the tool asks):
+- The generation plan: wave table, remaining targets, current wave number
+- Completed outputs: list of written file paths + validate OK (not their content)
+- Language setting and theme (if prototype)
+- Any open blockers or deferred items
+
+What to discard (do not try to retain):
+- Raw graph query JSON from completed targets
+- File content of already-written docs
+- Template content (re-read from `.ai-spector/templates/` when needed)
+- Data-source file content read in earlier waves
+
+**Trigger compact also when:**
+- Writing more than 5 per-domain files in a single wave (compact after every 5th file)
+- Switching document types mid-wave (e.g., UC files → feature files)
+- Context feels noisy — re-reads of the same data, earlier target data bleeding in
+
+---
+
+## Rule 2 — Sub-agent for graph context gathering
+
+Do **not** run graph queries + file reads + synthesis all inline in the main agent turn. This fills the context with raw data that is only useful for 30 seconds.
+
+Instead, delegate context gathering to a sub-task and receive only the distilled result.
+
+### Sub-agent pattern
+
+**Delegate:** "Gather context for `<target>`"
+
+**Prompt to sub-agent (adapt per target type):**
+
+```
+Query the graph and read relevant files for <target id / type>.
+Return ONLY a structured summary — do not return raw JSON or full file content.
+
+Required output shape:
+- Target: <id>, <name>
+- Actors: list of actor names and roles
+- Flow steps: numbered main flow (max 10 steps); exception flows (list conditions only)
+- Data fields: input fields (name, type, required, validation); output fields (name, type)
+- Related nodes: UC/F/API/screen ids that this target depends on or satisfies
+- Gaps: any required graph node that is missing or empty
+
+Queries to run:
+  ai-spector graph query <seedId> --direction both --depth 4 --edges CONTEXT --json
+  ai-spector graph query <depId> --direction both --depth 2 --edges DEPS --json
+  [read projectionPaths files listed in query result]
+
+Max summary length: 400 words. No raw JSON in the response.
+```
+
+**Main agent receives:** The 400-word summary — not the raw query output.
+
+**Main agent writes:** The document file using the summary + template.
+
+### When to use sub-agents
+
+| Task | Use sub-agent? |
+|---|---|
+| Graph query + extraction for a single UC/F/screen | **Yes** |
+| Reading multiple data-source files to find relevant domain info | **Yes** |
+| Impact analysis before regenerating a file | **Yes** |
+| Checking whether a UC node exists | No — simple CLI call inline |
+| Writing the file itself | No — main agent writes |
+| Running `graph validate` / `graph merge` | No — CLI inline |
+
+---
+
+## Rule 3 — Read discipline (no speculative reads)
+
+Only read a file if the graph query result references it in `projectionPaths` or the DAG explicitly lists it as a dependency. Never read:
+
+- `docs/**` as a glob
+- The entire `docs/data-source/` directory upfront
+- Previously generated docs "for context" unless they are a direct DAG dependency of the current target
+
+After a file is read and its relevant data extracted, treat it as consumed. Do not re-read it for a later target unless that target also has it in `projectionPaths`.
+
+---
+
+## Rule 4 — Context budget per target
+
+Before writing each target, the context should hold **only**:
+
+| Item | Max size |
+|---|---|
+| Generation plan (wave table, remaining targets) | ~200 tokens |
+| Extracted context for current target (from sub-agent or compact summary) | ~400 tokens |
+| Template structure (section headings only, not full template) | ~200 tokens |
+| Language setting | 1 line |
+| Current target output (while writing) | as needed |
+
+If the active context clearly exceeds this (raw JSON visible, previous target data visible, multiple template files loaded), compact before writing.
+
+---
+
+## Rule 5 — After writing, let it go
+
+Once a file is written and `rendersTo` is logged for the wave-end merge:
+- Do not re-read the file
+- Do not summarise its content into memory
+- Record only: path + validate status
+
+The graph is the persistent record. The context window is scratch space per target.
+
+---
+
+## Compaction prompt template
+
+When compacting mid-run, include this summary so the next turn has enough to continue:
+
+```
+Continuing generation of <layer> (e.g., SRS / basic design).
+
+Plan:
+- Wave <N> of <total> — COMPLETED
+- Wave <N+1> targets: <list of DAG ids and output paths>
+- Remaining waves: <list>
+
+Completed files:
+<path> — validate OK
+<path> — validate OK
+
+Settings:
+- Language: <language>
+- Graph validated: YES
+
+Resume at: wave <N+1>, target <first target id>.
+```
+
+---
+
+## Summary
+
+| Checkpoint | Action |
+|---|---|
+| End of every wave | `/compact` with plan summary |
+| Every 5 per-domain files | `/compact` with plan summary |
+| Before each target | Delegate graph query + extraction to sub-agent |
+| After reading data-source files | Extract what's needed; discard the raw read |
+| After writing a file | Record path + status only; discard file content |

package/scaffold/cursor/skills/ai-spector/references/generate-graph.md

@@ -71,9 +71,14 @@ ai-spector graph impact <targetSeedId> --change content_change --json
 ### D. Write
 
 - Read template from `.ai-spector/templates/` (DAG `template` field). If missing → stop and ask user to run `npx ai-spector init`.
+- **Before filling the template**, apply the layer-specific graph extraction map:
+  - SRS targets → [srs-graph-context.md](../../ai-spector-generate-srs/references/srs-graph-context.md)
+  - Basic design targets → [basic-design-graph-context.md](../../ai-spector-generate-basic-design/references/basic-design-graph-context.md)
+  - Prototype screens → [prototype-graph-context.md](../../ai-spector-generate-prototype/references/prototype-graph-context.md)
 - Fill for this target only; keep all required headings; replace placeholders with graph-backed content.
 - Cross-check every UC/F reference against `nodes` from query JSON.
 - Add section anchors `<!-- section:sec.... -->` where templates expect them.
+- **Never invent** field names, endpoint paths, table names, actor roles, or business rules not present in the query results.
 
 ### E. Ingest (once per wave — not per file)
 

package/scaffold/cursor/skills/ai-spector/references/generate-workflow.md

@@ -1,128 +1,68 @@
-# Document generation workflow (shared)
+# Document generation workflow
 
-Used by **SRS**, **basic design**, and **detail design** generation skills.
+Used by SRS, basic design, and detail design skills.
 
-| Topic | Document |
-|-------|----------|
-| Graph query, merge patch shape, waves algorithm | [generate-graph.md](./generate-graph.md) |
-| CLI failure recovery (fix / workaround / pause) | [cli-failures.md](./cli-failures.md) |
-| Layer-specific DAG, intent tables, waves | each skill’s `references/runbook.md` |
+**References (load when needed):**
+- Graph queries / merge / ingest → [generate-graph.md](./generate-graph.md)
+- Context compaction / sub-agents → [context-management.md](./context-management.md)
+- CLI failures → [cli-failures.md](./cli-failures.md)
 
-**Not used by** HTML prototype generation (`ai-spector-generate-prototype` runbook).
+## Language check (before first write)
 
-## Language — check before any write
+Read `.ai-spector/.docflow/config/language.json`. If `documentLanguage` is empty or missing, load [language-picker.md](./language-picker.md) and run the picker. All content in the chosen language; IDs, paths, code never translated.
 
-**Read [language-picker.md](./language-picker.md) before generating any document content.**
+## Context hygiene (always)
 
-1. Check `.ai-spector/.docflow/config/language.json` for `documentLanguage`.
-2. If missing, run the language-picker flow (ask → persist → continue). Do not write until confirmed.
-3. Apply the enforcement rules in language-picker.md to every file written: all content in the target language, IDs/paths/code never translated, no mixing.
+1. Only read files listed in `projectionPaths` — no `docs/**` glob.
+2. Raw graph JSON stays in the sub-agent, not main context.
+3. After writing a file, record path + status only; discard content.
+4. For runs of 5+ files: compact after every wave + every 5 per-domain files. Load [context-management.md](./context-management.md) for the sub-agent pattern.
 
-## Philosophy
+## Scope
 
-- **Accuracy over speed** — full graph context before every write; ingest before the next wave.
-- **Graph in, graph out** — query neighbors + dependencies before; `rendersTo` + `dependsOn` after ([generate-graph.md](./generate-graph.md) § E).
-- **Parallel when safe** — only targets in the **same DAG wave** with dependencies already merged + validated (and **indexed** when the command doc requires it).
+| Case | User input | Behavior |
+|---|---|---|
+| **1 — All** | "generate all SRS" | Every DAG node. Skip `good` files unless user asked to regenerate. |
+| **2 — Explicit** | file paths in chat | Map → DAG nodes → dependency closure. Same wave only. |
+| **3 — Words** | "API list and screens" | Scope table → user confirms → generate. No write before yes. |
 
-## Scope — three ways to choose targets
-
-Each generate command defines its DAG and intent hints. The pattern is always:
-
-| Case | User input | Agent behavior |
-|------|------------|----------------|
-| **1 — All** | “generate all SRS” / full layer | Plan every DAG node (+ per-domain expansions). Respect `good` on disk unless user asked to regenerate. |
-| **2 — Explicit paths** | paths in chat (`docs/…/file.md`) | Map paths → DAG nodes → seeds. Include **dependency closure**. Batch only within the same wave. |
-| **3 — Words** | “API list and screens” | Proposed scope table → **user confirms** → generate. **Do not write until approved.** |
-
-Paths are repo-relative. Mixed args: treat paths as case 2, free text as case 3.
-
-## Case 3 — confirm before write (mandatory)
-
-1. Parse the request against that command’s `dag.*.json`, `dag.*.graph-seeds.json`, and graph domain nodes.
-2. Build a **proposed scope** table (columns: DAG id, output path, seed, reason, prerequisites / deps).
-3. Include **dependency closure** — ancestors that are `missing_file` / `missing_content` run in earlier waves unless the user skips deps.
-4. Ask:
-
-```text
-I plan to generate the following (N items, waves X–Y). Prerequisites run first.
-Reply **yes** to proceed, **no** to cancel, or edit the list.
-```
-
-5. **Stop** without explicit **yes**. Do not write on assumption.
-6. If ambiguous (e.g. “features” = list vs all detail files), ask **one** clarifying question before the table.
-
-Command-specific phrase → DAG mappings live in each `generate-*.md` (not here).
-
-## Prerequisites (all DAG generate commands)
-
-1. Merged graph — normally after **analyze** (data-source ingest).
-2. Gate:
-
-```bash
-ai-spector graph validate
-```
-
-On errors, pause and follow recovery in [cli-failures.md](./cli-failures.md).
-
-3. `workflow.dependencies.json` entry for that command (SRS minimum, etc.).
+Case 3: build scope table (DAG id, output path, seed, reason, deps) → ask → stop until confirmed.
 
 ## Plan (once per invocation)
 
-1. **Select targets** (case 1 / 2 / 3; case 3 = confirm first).
-2. Topological sort selected nodes + required dependency ancestors.
-3. Map each node via `dag.*.graph-seeds.json` → query seeds + ingest document ids.
-4. Classify disk per output: `good` | `missing_content` | `missing_file` — do not overwrite `good` without user intent.
-5. Assign **waves** ([generate-graph.md](./generate-graph.md) § Waves). Present wave table (brief for cases 1–2; case 3 table already confirmed).
-
-## Per wave, then per target
+1. Select targets (case 1/2/3).
+2. Topological sort + dependency closure.
+3. Map DAG nodes → seeds via `dag.*.graph-seeds.json`.
+4. Classify disk: `good` | `missing_content` | `missing_file`.
+5. Assign waves; present wave table.
 
-For **each wave** in order:
-
-### Wave checklist
+## Wave checklist
 
 ```
-- [ ] All targets in this wave identified (parallel OK within wave only)
-- [ ] For each target: graph query deps + target (_generate-graph § C)
+- [ ] Targets for this wave identified (parallel OK within wave only)
+- [ ] Per target: delegate graph queries to sub-agent; receive ≤400-word summary
+- [ ] Load matching srs-context/ or bd-context/ section for this doc type
 - [ ] Read template from .ai-spector/templates/ — never invent structure
-- [ ] Write file(s)
-- [ ] Merge projection patch (rendersTo + dependsOn) for this wave
-- [ ] ai-spector graph validate — pass before next wave
-- [ ] ai-spector index when command doc requires (basic design: every wave; SRS: see generate-srs.md)
+- [ ] Write file from summary + template
+- [ ] Merge projection patch (rendersTo + dependsOn) for the wave
+- [ ] ai-spector graph validate
+- [ ] ai-spector index (basic design: every wave; SRS: see runbook)
+- [ ] /compact with plan summary before next wave
 ```
 
-### Per target (summary)
-
-Details: [generate-graph.md](./generate-graph.md) § C–E.
-
-1. **Query** — dependency seeds (depth 2) + target seed (depth 4); `graph impact` when regenerating.
-2. **Read** — `projectionPaths` and cited `docs/data-source/**` only; no glob of entire `docs/`.
-3. **Write** — from DAG template; graph-backed UC/F/API/screen names only.
-4. **Ingest** — merge patch; validate before leaving the wave.
-
-**Forbidden:** targets from different waves in one batch; next wave before merge + validate; skipping `rendersTo` on generated docs.
-
-### Log (optional)
-
-Append one line per target to `.ai-spector/.docflow/logs/generate-<layer>.log` (create dir if needed): timestamp, seed, path, validate OK.
-
-## Finish (end of command)
-
-1. `ai-spector graph validate`
-2. `ai-spector index` if not already run after the last wave (required for SRS — see `generate-srs.md`)
-3. Suggest the command doc’s summary command (`/summary srs`, `/summary basic-design`, …) when listed there
-4. Optional: `/visualize-graph` for review
-
-Index flags: `--skip-doc-semantics` to skip UC/F body parsing; `--graph-only` for structure + merge only.
+Per target: Delegate → Receive summary → Write → Log path/status → Ingest.
 
 ## Guardrails
 
-- **Parallel only within a wave** — never across waves; never when A `dependsOn` B in the DAG.
-- **Every target** gets its own `graph query` + dependency queries before write.
-- **Every wave** ends with merge + validate (and **index** when the command doc says so) before the next wave.
-- **Case 3** requires explicit user **yes** before any write.
-- On `graph query` / `merge` / `validate` / `index` failure → pause and recover per [cli-failures.md](./cli-failures.md).
-- Prefer graph `nodes`/`edges` over stale `knowledge.json` for generation text.
+- Parallel only within a wave.
+- Sub-agent per target — never reuse a previous target's summary.
+- No raw graph JSON in main context.
+- No speculative reads — projectionPaths only.
+- Case 3 requires explicit yes before any write.
+- On CLI failure → load [cli-failures.md](./cli-failures.md).
 
-## If blocked
+## Finish
 
-[cli-failures.md](./cli-failures.md). Re-run the same task after fixes. Common upstream fix: **analyze** first, or generate SRS before basic design.
+1. `ai-spector graph validate`
+2. `ai-spector index` if not already run after last wave
+3. Suggest summary command when runbook lists one

package/scaffold/cursor/skills/ai-spector-generate-basic-design/SKILL.md

@@ -10,25 +10,27 @@ paths:
   - ".ai-spector/templates/basic_design/**"
 ---
 
-# AI Spector — Generate basic design
-
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
-
-## Required reading
+# Generate Basic Design
 
+## Load at start
 1. [references/runbook.md](references/runbook.md)
 2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md)
-3. [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) § perEndpoint / perScreen
 
-## Checklist
+## Load when needed
 
-```
-- [ ] language confirmed (language-picker.md — check before first write)
-- [ ] graph validate; SRS on disk
-- [ ] index after every wave (mandatory)
-- [ ] one file per endpoint row / Screen Index row — not per F-xx
-```
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| Writing DB design | [references/bd-context/db-design.md](references/bd-context/db-design.md) |
+| Writing API list | [references/bd-context/api-list.md](references/bd-context/api-list.md) |
+| Writing API detail (per endpoint) | [references/bd-context/api-detail.md](references/bd-context/api-detail.md) |
+| Writing screen list | [references/bd-context/screen-list.md](references/bd-context/screen-list.md) |
+| Writing screen detail (per screen) | [references/bd-context/screen-detail.md](references/bd-context/screen-detail.md) |
+| Graph queries / merge | [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) |
+| CLI fails | [../ai-spector/references/cli-failures.md](../ai-spector/references/cli-failures.md) |
+| Run of 5+ files | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |
 
-## Natural language
+## On CLI failure
+Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-“basic design”, “screen list”, “API list”, “wireframe for login” → this skill.
+"basic design", "screen list", "API list", "wireframe for login" → this skill.