ai-spector 0.3.5 → 0.3.7

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

@@ -0,0 +1,185 @@
+# CLI and tool failures (mandatory agent behavior)
+
+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):
+
+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).
+
+**Default:** fix and retry. **Workarounds** are allowed only with explicit user approval and the guardrails in [Workaround catalog](#workaround-catalog-user-approval-required).
+
+---
+
+## 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.
+
+---
+
+## 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)
+
+**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.
+
+---
+
+## 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`.
+
+---
+
+## Agent may fix without asking (small, local)
+
+- 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.
+
+## Agent must ask user before
+
+- 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.

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

@@ -0,0 +1,130 @@
+# Graph-first generation (shared)
+
+Used by **SRS**, **basic design**, and **detail design** generation skills.
+
+| Orchestration (scope, confirm, wave checklist, finish) | [generate-workflow.md](./generate-workflow.md) |
+| Per-command DAG + intent tables | each skill's `references/runbook.md` |
+
+**Principle:** Accuracy over speed. The graph is the planner, context loader, and registry of what was written.
+
+**Parallelism:** Allowed **only inside a DAG wave**. Never across waves.
+
+## Edge presets (use these in queries — don't copy-paste long lists)
+
+| Preset name | Edges | Use for |
+|-------------|-------|---------|
+| `CONTEXT` | `listedIn,definedIn,describedIn,satisfies,dependsOn,rendersTo,partOf,contains` | Target neighborhood — what exists and where it lives |
+| `DEPS` | `rendersTo,dependsOn,listedIn,satisfies,partOf,contains` | Dependency context — what upstream docs look like |
+| `IMPACT` | `satisfies,tracesTo,dependsOn,references,relatesTo` | What a change would affect |
+
+## Agent rules
+
+1. **Plan from DAG** — build waves from `dag.*.json`; map each DAG node → graph seed via `dag.*.graph-seeds.json`.
+2. **Context before write** — for **every** target run the CONTEXT query; read `projectionPaths`. No invented UC/F text.
+3. **Merge once per wave, not per file** — write all files in a wave, then do one batch merge + one validate. Do not merge after every file.
+4. **No shortcuts** — no glob `docs/srs/**`, no skipping validate, no batching targets that have a DAG dependency on each other.
+
+## CLI workflow
+
+### A. Gate (once per command)
+
+```bash
+ai-spector graph validate
+```
+
+### B. Plan — waves
+
+Assign each DAG node to wave `0`, `1`, `2`, …:
+
+- **Wave 0:** nodes with empty `dependsOn`
+- **Wave k:** nodes whose `dependsOn` are all in waves `< k`
+
+**Same wave = parallel OK.** Example: after `srs.feature-details`, both `srs.data-requirements` and `srs.external-interfaces` are in the same wave → generate both in one batch.
+
+Present plan as:
+
+| Wave | DAG ids (parallel OK) | Seeds | Blocked until |
+|------|----------------------|-------|---------------|
+| 0 | … | … | — |
+| 1 | … | … | wave 0 merged + validate |
+
+### C. Before writing each target
+
+**Dependency context** (once per wave, for each DAG `dependsOn`):
+
+```bash
+ai-spector graph query <depSeedId> --direction both --depth 2 --edges DEPS --json
+```
+
+**Target neighborhood:**
+
+```bash
+ai-spector graph query <targetSeedId> --direction both --depth 4 --edges CONTEXT --json
+```
+
+**When regenerating** (unsure what changed):
+
+```bash
+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`.
+- 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.
+
+### E. Ingest (once per wave — not per file)
+
+After **all files in a wave** are written, write a single patch covering the whole wave:
+
+```json
+{
+  "version": 1,
+  "nodes": [],
+  "edges": [
+    { "type": "rendersTo", "from": "doc.srs.3-use-cases", "to": "docs/srs/3-use-cases.md" },
+    { "type": "dependsOn", "from": "doc.srs.3-use-cases", "to": "doc.srs.1-introduction" }
+  ]
+}
+```
+
+```bash
+ai-spector graph merge .ai-spector/.docflow/extract/projection-patch.json
+ai-spector graph validate
+```
+
+Then — for SRS and basic-design waves — run index before starting the next wave:
+
+```bash
+ai-spector index
+```
+
+**Exception:** if a file within the wave is a dependency for another file in the **same** wave (unusual — check the DAG), merge that file's `rendersTo` before writing the dependent. For standard DAGs this never happens within a wave.
+
+### F. Per-domain detail files
+
+For `mode: perFeature` / `perDomain` (SRS):
+
+- Seed = domain id (`UC-01`, `F-01`), not only chapter document.
+- Query with `--depth 4` + CONTEXT edges; include inbound `satisfies`.
+- Batch all per-domain files in their wave; merge all `rendersTo` once at wave end.
+
+For `mode: perEndpoint` / `perScreen` (basic design):
+
+- **perEndpoint:** read `docs/basic-design/api-list.md` §3; one file per row under `docs/basic-design/api/<slug>.md`.
+- **perScreen:** read `docs/basic-design/list-screens.md` §4; one file per screen under `docs/basic-design/screens/<slug>.md`.
+- Ingest `doc.bd.api-*` / `doc.bd.screen-*` with `contains` from list chapter in the wave-end merge.
+
+## Accuracy checklist
+
+- [ ] `graph query` run for target and every DAG dependency with existing files
+- [ ] All UC/F ids in markdown exist as graph nodes
+- [ ] Wave-end `rendersTo` + `dependsOn` merged in one patch
+- [ ] `graph validate` passes before next wave
+- [ ] No placeholder lorem / empty tables unless marked TBD in `gaps.json`
+
+## On CLI failure
+
+[cli-failures.md](./cli-failures.md) — pause; offer fix / workaround / pause; do not generate from memory.

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

@@ -0,0 +1,120 @@
+# Document generation workflow (shared)
+
+Used by **SRS**, **basic design**, and **detail design** generation 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` |
+
+**Not used by** HTML prototype generation (`ai-spector-generate-prototype` runbook).
+
+## Philosophy
+
+- **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).
+
+## 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.).
+
+## 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
+
+For **each wave** in order:
+
+### Wave checklist
+
+```
+- [ ] All targets in this wave identified (parallel OK within wave only)
+- [ ] For each target: graph query deps + target (_generate-graph § C)
+- [ ] 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)
+```
+
+### 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.
+
+## 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.
+
+## If blocked
+
+[cli-failures.md](./cli-failures.md). Re-run the same task after fixes. Common upstream fix: **analyze** first, or generate SRS before basic design.

package/scaffold/cursor/{commands/_graph.md → skills/ai-spector/references/graph.md}

@@ -1,20 +1,19 @@
 # Graph CLI (for agents)
 
-**Users do not run these.** Slash commands invoke CLI. Workflow: [_workflow.md](./_workflow.md). **On failure:** [_cli-failures.md](./_cli-failures.md).
+**Users do not run these.** Slash commands invoke CLI. Workflow: [_workflow.md](./_workflow.md). **On failure:** [cli-failures.md](./cli-failures.md).
 
 Run from project root: `npx ai-spector …` if needed.
 
 ## Every CLI invocation
 
 1. Run the command; capture **exit code**, **stdout**, **stderr**.
-2. If non-zero or `--json` is unparseable → **stop**; report per `_cli-failures.md`.
+2. If non-zero or `--json` is unparseable → **pause**; report and offer fix / workaround / pause per `cli-failures.md`.
 3. On success, use CLI output only — do not re-derive graph state in the agent.
 
 ## Commands
 
 ```bash
 ai-spector analyze
-ai-spector graphify update
 ai-spector graph merge --from-knowledge
 ai-spector graph validate
 ai-spector graph visualize [--open]
@@ -32,7 +31,7 @@ ai-spector graph query <depDocId> --edges rendersTo,dependsOn,listedIn,satisfies
 ai-spector graph impact <seedId> --change content_change --json
 ```
 
-**Generate:** query **before** write; **`graph merge`** projection patch **after** each file (`rendersTo` + `dependsOn`). See `_generate-graph.md`.
+**Generate:** query **before** write; **`graph merge`** projection patch **after** each file (`rendersTo` + `dependsOn`). See `generate-graph.md`.
 
 Use `projectionPaths`, `nodes`, `edges` from JSON. **If command fails or JSON invalid:** stop — do not glob `docs/srs/**`.
 

package/scaffold/cursor/{commands/_prerequisites.md → skills/ai-spector/references/prerequisites.md}

@@ -1,13 +1,13 @@
 # Workflow prerequisites (shared)
 
-User workflow: [**_workflow.md**](./_workflow.md). **CLI failures:** [**_cli-failures.md**](./_cli-failures.md). Agent CLI: [**_graph.md**](./_graph.md).
+User workflow: [**_workflow.md**](./_workflow.md). **CLI failures:** [**cli-failures.md**](./cli-failures.md). Agent CLI: [**_graph.md**](./_graph.md).
 
 Load `.ai-spector/.docflow/config/workflow.dependencies.json` for the active step.
 
 ## When checks fail
 
 1. **Stop immediately** — do not read `.ai-spector/templates/`, spawn subagents, or write outputs.
-2. Reply with the **Blocked** format in [_cli-failures.md](./_cli-failures.md) (include full CLI output).
+2. Reply with the **Blocked** format in [cli-failures.md](./cli-failures.md) (include full CLI output; offer fix / workaround / pause).
 3. Help the user fix the issue; re-run the failed CLI; then continue the slash command.
 
 ## Graph context (only after CLI succeeds)
@@ -16,7 +16,7 @@ Load `.ai-spector/.docflow/config/workflow.dependencies.json` for the active ste
 2. Per target: **`ai-spector graph query <seedId> --json`** — parse JSON; use `projectionPaths` and `nodes`.
 3. Open **only** those paths (+ targeted `docs/data-source/**` if still insufficient).
 
-**If validate or query fails:** follow [_cli-failures.md](./_cli-failures.md) — do **not** fall back to index or full-tree reads.
+**If validate or query fails:** follow [cli-failures.md](./cli-failures.md) — do **not** fall back to index or full-tree reads unless the user approves a listed workaround.
 
 **If query succeeds but has no domain nodes:** tell the user; suggest **`/analyze`** — still no `docs/srs/**` glob.
 

package/scaffold/cursor/skills/ai-spector/references/project-conventions.md

@@ -0,0 +1,27 @@
+# AI Spector project conventions
+
+## Init and upgrades
+
+```bash
+npx ai-spector init          # first time
+npx ai-spector sync-cursor   # refresh commands/skills after package upgrade
+```
+
+Missing templates → `npx ai-spector init --force`.
+
+## Document layers
+
+| Layer | Directory |
+|-------|-----------|
+| Source input | `docs/data-source/` |
+| SRS | `docs/srs/` |
+| Basic design | `docs/basic-design/` |
+| Detail design | `docs/detail-design/` |
+| HTML prototype | `prototype/src/` |
+
+## Generation discipline (all layers)
+
+1. Read template from `.ai-spector/templates/` — never invent section structure.
+2. Query graph before writing (`ai-spector graph query`).
+3. Merge projection patches after each wave (`graph merge`).
+4. Validate when the command doc requires it.

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

@@ -1,41 +1,21 @@
 ---
 name: ai-spector-generate
 description: >-
-  AI Spector document generation — SRS, basic design, detail design from traceability graph.
-  Use for /generate-srs, /generate-basic-design, /generate-detail-design, or when user asks to
-  generate, write, or update requirements specs, SRS chapters, basic design, detail design, or docs under docs/srs docs/basic-design.
+  Routes ambiguous document-generation requests to the correct AI Spector layer skill (SRS, basic
+  design, detail design, or HTML prototype). Use only when the user says generate docs or generate
+  requirements without naming a layer. Do not use when the request clearly targets SRS, screens, APIs,
+  detail design, or prototype HTML.
 ---
 
-# AI Spector — Generate
+# AI Spector — Generate (router)
 
-**Core rules:** `.cursor/skills/ai-spector/SKILL.md`
-**Graph context:** `.cursor/commands/_generate-graph.md`, `_graph.md`
+Ask one question or infer from context, then **switch skill** and read that skill’s runbook:
 
-## Route to command doc
+| Layer | Skill |
+|-------|-------|
+| Requirements / SRS | `ai-spector-generate-srs` |
+| Screens, APIs, DB | `ai-spector-generate-basic-design` |
+| Implementation detail | `ai-spector-generate-detail-design` |
+| HTML mockups | `ai-spector-generate-prototype` |
 
-| Trigger | Read first | Notes |
-|---------|------------|-------|
-| `/generate-srs`, SRS, requirements spec | `commands/generate-srs.md` | DAG waves, `graph query`, templates in `.ai-spector/templates/srs/` |
-| `/generate-basic-design`, screens, APIs, DB design | `commands/generate-basic-design.md` | `templates/basic_design/` |
-| `/generate-detail-design` | `commands/generate-detail-design.md` | `templates/detail_design/` |
-
-## Before generating
-
-1. **`ai-spector graph validate`** should pass (or run `/validate-graph` first).
-2. **Read the template** from `.ai-spector/templates/` — never guess structure.
-3. After each wave: **`graph merge`** projection patch with `rendersTo` + `dependsOn`.
-4. After SRS generation: recommend **`/index`**.
-
-## Natural language → command
-
-| User says | Action |
-|-----------|--------|
-| "generate SRS", "write requirements", "create use case docs" | `generate-srs.md` |
-| "basic design", "screen list", "API design doc" | `generate-basic-design.md` |
-| "detail design", "feature detail doc" | `generate-detail-design.md` |
-
-Confirm scope when user describes generation in natural language (not explicit paths).
-
-## Generate discipline
-
-Accuracy over speed — batch only same-wave independent targets; merge + validate after each wave.
+**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md) · **Pipeline:** [../../WORKFLOW.md](../../WORKFLOW.md)

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

@@ -0,0 +1,33 @@
+---
+name: ai-spector-generate-basic-design
+description: >-
+  Generates or updates basic design documents from the traceability graph and SRS: screen list and
+  screen details, API list and endpoint details, database design under docs/basic-design/. Use when
+  the user asks for basic design, wireframes, screen map, API design, ERD, or list-screens.md. Do not
+  use for SRS-only work, detail design, HTML prototype, or graph analyze/index without doc generation.
+paths:
+  - "docs/basic-design/**"
+  - ".ai-spector/templates/basic_design/**"
+---
+
+# AI Spector — Generate basic design
+
+**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
+
+## Required reading
+
+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
+
+```
+- [ ] graph validate; SRS on disk
+- [ ] index after every wave (mandatory)
+- [ ] one file per endpoint row / Screen Index row — not per F-xx
+```
+
+## Natural language
+
+“basic design”, “screen list”, “API list”, “wireframe for login” → this skill.