ai-spector 0.4.3 → 0.4.4

package/package.json

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

package/scaffold/cursor/skills/README.md

@@ -14,7 +14,6 @@ Enable **every** folder under `.cursor/skills/` in Cursor (Settings → Rules
 | Analyze, index, validate graph, impact, visualize | `ai-spector-graph` |
 | SRS / requirements | `ai-spector-generate-srs` |
 | Screens, APIs, DB basic design | `ai-spector-generate-basic-design` |
-| Detail / implementation design | `ai-spector-generate-detail-design` |
 | HTML prototype | `ai-spector-generate-prototype` |
 | Review comments | `ai-spector-resolve-comments` |
 | Unsure | `ai-spector` (core) |

package/scaffold/cursor/skills/_skill-router.md

@@ -6,7 +6,7 @@ Agents use this when intent is ambiguous.
 
 1. **File context** — `paths` in skill frontmatter (e.g. `prototype/**` → prototype skill).
 2. **Natural language** — match skill `description`; then read that skill’s `references/` runbook.
-3. **Still unclear** — `ai-spector` core + one question (graph vs SRS vs basic design vs detail vs prototype vs comments).
+3. **Still unclear** — `ai-spector` core + one question (graph vs SRS vs basic design vs prototype vs comments).
 
 ## Task → skill → runbook
 
@@ -22,8 +22,7 @@ Agents use this when intent is ambiguous.
 | doc summaries | `ai-spector-graph` | `references/summary.md` |
 | SRS, use cases, features, requirements | `ai-spector-generate-srs` | `references/runbook.md` |
 | screens, APIs, wireframes, basic design | `ai-spector-generate-basic-design` | `references/runbook.md` |
-| detail design, implementation spec | `ai-spector-generate-detail-design` | `references/runbook.md` |
-| HTML prototype | “HTML prototype”, “mockup screens”, “prototype with stripe theme” | `ai-spector-generate-prototype` | `references/runbook.md`, `references/theme-picker.md` |
+| HTML prototype | `ai-spector-generate-prototype` | `references/runbook.md` |
 | review comments, C-001, inbox | `ai-spector-resolve-comments` | `references/runbook.md` |
 | “generate docs” (no layer named) | `ai-spector-generate` | route to one skill above |
 
@@ -34,7 +33,6 @@ Shared: [ai-spector/references/cli-failures.md](./ai-spector/references/cli-fail
 ```text
 analyze → validate graph → generate SRS → index
   → generate basic design → index
-  → generate detail design
   → prototype setup → generate HTML screens
 ```
 

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

@@ -4,7 +4,7 @@ description: >-
   Provides shared rules for AI Spector docflow projects: CLI failure handling, traceability graph path,
   and routing to task skills. Use when the user mentions ai-spector, docflow, or .ai-spector but the
   task is unclear, or for init and project layout. Do not use when the user clearly wants SRS,
-  basic design, detail design, HTML prototype, graph operations, or comment resolution — use the
+  basic design, HTML prototype, graph operations, or comment resolution — use the
   matching task skill instead.
 ---
 
@@ -36,7 +36,6 @@ When `ai-spector` exits non-zero, required `--json` is invalid, or a required MC
 | Analyze, index, validate, impact, visualize | `ai-spector-graph` |
 | SRS | `ai-spector-generate-srs` |
 | Basic design | `ai-spector-generate-basic-design` |
-| Detail design | `ai-spector-generate-detail-design` |
 | Prototype | `ai-spector-generate-prototype` |
 | Comments | `ai-spector-resolve-comments` |
 | “Generate docs” (vague) | `ai-spector-generate` |

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

@@ -1,6 +1,6 @@
 # Graph-first generation (shared)
 
-Used by **SRS**, **basic design**, and **detail design** generation skills.
+Used by **SRS** and **basic 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` |
@@ -71,9 +71,9 @@ 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)
+- **Before filling the template**, load the matching context section for this doc type:
+  - SRS targets → `srs-context/<section>.md` (see SRS runbook for the table)
+  - Basic design targets → `bd-context/<doc-type>.md` (see BD runbook for the table)
   - 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.

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

@@ -1,6 +1,6 @@
 # Document generation workflow
 
-Used by SRS, basic design, and detail design skills.
+Used by SRS and basic design skills.
 
 **References (load when needed):**
 - Graph queries / merge / ingest → [generate-graph.md](./generate-graph.md)

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

@@ -16,7 +16,6 @@ Missing templates → `npx ai-spector init --force`.
 | Source input | `docs/data-source/` |
 | SRS | `docs/srs/` |
 | Basic design | `docs/basic-design/` |
-| Detail design | `docs/detail-design/` |
 | HTML prototype | `prototype/src/` |
 
 ## Document language

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

@@ -2,20 +2,16 @@
 name: ai-spector-generate
 description: >-
   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.
+  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, or prototype HTML.
 ---
 
 # AI Spector — Generate (router)
 
-Ask one question or infer from context, then **switch skill** and read that skill’s runbook:
+Ask one question or infer from context, then **switch skill** and read that skill's runbook:
 
 | 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` |
-
-**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

@@ -4,7 +4,7 @@ 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.
+  use for SRS-only work, HTML prototype, or graph analyze/index without doc generation.
 paths:
   - "docs/basic-design/**"
   - ".ai-spector/templates/basic_design/**"

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

@@ -89,7 +89,7 @@ Execution checklist: [generate-workflow.md](../../ai-spector/references/generate
 ## Finish
 
 - Last wave already ran validate + index → final validate only; else run both again.
-- Suggest **`/summary basic-design`** (required before detail design per workflow).
+- Suggest **`/summary basic-design`** when workflow lists it.
 
 Log: `.ai-spector/.docflow/logs/generate-basic-design.log`.
 

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

@@ -5,7 +5,7 @@ description: >-
   Use when the user asks for HTML prototype, screen mockups, or prototype/src files. When no theme is
   stored, recommends 3 best-fit themes from project context, opens preview samples in the browser,
   and waits for the user to choose before setup. Uses stored preference on subsequent runs. Do not use
-  for markdown SRS/basic/detail design only, or graph operations without HTML output.
+  for markdown SRS/basic design only, or graph operations without HTML output.
 paths:
   - "prototype/**"
 ---
@@ -20,7 +20,7 @@ paths:
 | Situation | Load |
 |---|---|
 | Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
-| No theme stored | [references/theme-picker.md](references/theme-picker.md) |
+| No theme stored — **must confirm before setup** | [references/theme-picker.md](references/theme-picker.md) |
 | No basic auth stored | [references/auth-picker.md](references/auth-picker.md) |
 | Before writing each screen HTML | [references/prototype-graph-context.md](references/prototype-graph-context.md) |
 | Run of 5+ screens | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |

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

@@ -36,7 +36,7 @@ ai-spector graph query F-<n> --direction both --depth 3 --edges CONTEXT --json
 
 Extract:
 - **Functional requirements** listed under the feature → must-have UI behaviours
-- **Field definitions** (`rendersTo` → detail design docs if present)
+- **Field definitions** (`rendersTo` → docs if present)
 - **Business rules** (validation, conditional visibility, permissions)
 - **Actor** that performs / views this feature → drives role-based UI variants
 

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

@@ -53,14 +53,16 @@ ai-spector prototype auth --from-config
 3. `prototype/manifest.json` → `themeName` (non-empty)
 4. `.ai-spector/.docflow/config/prototype.config.json` → `defaultTheme`
 
-**If no stored theme is found** and the user did **not** name one in this request, run the **[theme picker](theme-picker.md)** — do **not** ask a bare “which theme?” without recommendations.
+**If no stored theme is found** and the user did **not** name one in this request, run the **[theme picker](theme-picker.md)**.
+
+> **Do not auto-select.** Using project context to guess a theme and proceeding without a user reply is wrong — even if the rationale seems obvious. The agent's job is to recommend, not decide.
 
 Summary of the picker:
 
 1. Read project context (SRS, list-screens §1, knowledge, data-source).
 2. `ai-spector prototype themes --json` — pick **3 best-fit** themes with one-line rationale each.
 3. `ai-spector prototype preview <name> --open` for all 3 — user compares in the browser.
-4. Post a numbered table; **wait for user to choose** before setup.
+4. Post a numbered table; **stop and wait for user reply** — a number, a name, or “use that one” — before running any further command.
 
 Once the user confirms (or named a theme upfront), proceed with setup; the choice is persisted and will not be asked again.
 

package/scaffold/cursor/skills/ai-spector-generate-prototype/references/theme-picker.md

@@ -1,5 +1,7 @@
 # Theme picker — recommend, preview, confirm
 
+> **Hard rule: never auto-select a theme.** Inferring from project context is allowed only to produce 3 *recommendations*. The user must explicitly choose (by number, name, or "use that one") before `prototype setup` runs. Auto-picking and explaining the choice afterward is not acceptable.
+
 When **no theme is stored** and the user did **not** name one in this request, run this flow **before** `prototype setup`. Do not generate HTML until the user confirms a theme.
 
 Skip this flow when:

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

@@ -4,7 +4,7 @@ description: >-
   Generates or updates the System Requirements Specification from the traceability graph and
   docs/data-source context. Use when the user asks to generate or update SRS, requirements, use cases
   (UC-xx), features (F-xx), or files under docs/srs/. Do not use for basic design screens/APIs,
-  detail design, HTML prototype, or graph-only analyze/index tasks.
+  HTML prototype, or graph-only analyze/index tasks.
 paths:
   - "docs/srs/**"
   - ".ai-spector/templates/srs/**"

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

@@ -4,8 +4,7 @@ description: >-
   Runs AI Spector traceability graph operations: analyze data-source, index refresh, graph validate,
   impact and regen scope, visualize, semantic link-graph, knowledge.json. Use when
   the user asks to analyze sources, refresh or validate the graph, see impact of changes, visualize
-  traceability, or re-index after edits. Do not use for writing SRS, basic design, detail design, or
-  HTML prototype content.
+  traceability, or re-index after edits. Do not use for writing SRS, basic design, or HTML prototype content.
 paths:
   - ".ai-spector/graph/**"
   - ".ai-spector/.docflow/**"

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

@@ -1,31 +0,0 @@
----
-name: ai-spector-generate-detail-design
-description: >-
-  Generates or updates detail design and implementation specification documents under
-  docs/detail-design/ from the traceability graph, SRS, and basic design. Use when the user asks for
-  detail design, feature detail docs, or implementation specs. Do not use for SRS, basic design screens,
-  or HTML prototype.
-paths:
-  - "docs/detail-design/**"
-  - ".ai-spector/templates/detail_design/**"
----
-
-# Generate Detail Design
-
-## Load at start
-1. [references/runbook.md](references/runbook.md)
-2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md)
-
-## Load when needed
-
-| Situation | Load |
-|---|---|
-| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.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) |
-
-## On CLI failure
-Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
-
-"detail design", "implementation spec", "feature detail for F-03" → this skill.

package/scaffold/cursor/skills/ai-spector-generate-detail-design/references/runbook.md

@@ -1,60 +0,0 @@
-# Generate detail design
-
-Generate detail design markdown **from the traceability graph**, SRS, and basic design.
-
-**User runs this command;** the agent runs CLI.
-
-| Shared workflow | Document |
-|-----------------|----------|
-| Scope cases, waves, merge, guardrails | [generate-workflow.md](../../ai-spector/references/generate-workflow.md) |
-| Graph query + ingest | [generate-graph.md](../../ai-spector/references/generate-graph.md) |
-
-## Prerequisites
-
-- `ai-spector graph validate` passes
-- SRS + basic design minimum on disk (`workflow.dependencies.json` → `generate-detail-design`)
-
-## Config
-
-- `dag.detail-design.json`
-- `dag.detail-design.graph-seeds.json` (if present)
-- `completeness-rules.detail-design.json`
-
-Templates: `.ai-spector/templates/detail_design/`
-
-## Intent → DAG hints
-
-Use `dag.detail-design.json` + graph `feature` nodes. Common phrases:
-
-| User phrase | Typical outputs |
-|-------------|-----------------|
-| feature detail, implementation spec | per-feature files under `docs/detail-design/` |
-| architecture overview, deployment, error handling | shared chapters per DAG |
-| one feature, checkout | that feature’s detail doc only — case 2 |
-
-Case 3 confirmation: [generate-workflow.md](../../ai-spector/references/generate-workflow.md) § Case 3.
-
-## Required behavior
-
-Follow [generate-workflow.md](../../ai-spector/references/generate-workflow.md) (plan → waves → per-target query/write/merge/validate).
-
-1. **Gate** — `ai-spector graph validate`
-2. **Plan** — load `dag.detail-design.json`; build waves; map seeds from graph-seeds config
-3. **Per target** — seed = `feature` id or detail `document` node:
-
-```bash
-ai-spector graph query <seed> --direction both --depth 3 --json
-```
-
-4. Load SRS + basic-design paths from `projectionPaths` only (no full `docs/` glob)
-5. Read template; write; merge `rendersTo` + `dependsOn`; validate per wave
-6. **Finish** — `ai-spector index` if command scope touched many files; suggest `/summary` when workflow lists it
-
-## Guardrails
-
-- Same wave / merge / validate rules as [generate-workflow.md](../../ai-spector/references/generate-workflow.md)
-- Do not read all of `docs/` manually when CLI failed — [cli-failures.md](../../ai-spector/references/cli-failures.md)
-
-## If blocked
-
-Fix validate/query errors; ensure basic design exists. Re-run **`/generate-detail-design`**.