ai-spector 0.4.2 → 0.4.4

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

@@ -4,6 +4,13 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 
 **User runs this command;** the agent runs CLI. On CLI failure: [cli-failures.md](../../ai-spector/references/cli-failures.md).
 
+## Context hygiene
+
+For runs of 5+ screens, follow [context-management.md](../../ai-spector/references/context-management.md):
+- **Sub-agent per screen** — delegate graph queries + screen doc reads for each screen; receive a ≤400-word summary (fields, flows, roles, errors); main agent writes from the summary.
+- **Compact every 5 screens** — after writing and validating a batch of 5, `/compact` with the plan summary (remaining screens, written paths) before continuing.
+- After writing a screen HTML file, discard its content from context — record only the path.
+
 ## Philosophy
 
 - **Screen design is source of truth** — `docs/basic-design/list-screens.md` + `docs/basic-design/screens/<slug>.md`
@@ -46,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.
 
@@ -87,11 +96,25 @@ ai-spector prototype manifest --dry-run
 
 Read each target’s `docs/basic-design/screens/<slug>.md` — wireframe (§1.1), layout (§1.2), interactions. Read `prototype/DESIGN.md` for colors, type, spacing.
 
+### 2b. Load graph context per screen
+
+**Required before writing each screen’s HTML.** Run the queries in [prototype-graph-context.md](./prototype-graph-context.md) for the screen being generated.
+
+This step pulls:
+- The F-xx / UC-xx the screen satisfies → business rules, required fields, flow steps, error states
+- The API endpoints the screen depends on → exact form fields, response columns, error codes
+- Actor roles → role-based UI sections
+
+Do not skip this step. Screen detail docs summarize the spec; the graph has the authoritative detail. Any form field, table column, button, or error state **must be traceable to graph data** before you write it into the HTML.
+
 ### 3. Generate HTML
 
 For each screen in scope:
 
 - Write `prototype/src/<prototypeStem>.html` (self-contained or with sibling `.css`/`.js` in `prototype/src/`)
+- All content derived from graph context (step 2b) + screen detail doc — no invented fields or labels
+- Include error states and empty states for every exception flow found in the graph
+- Render role-specific sections when multiple actors satisfy the screen
 - Link navigation using relative paths between screens when `list-screens.md` §2 defines flow
 - Do **not** edit `docs/**`
 
@@ -125,6 +148,12 @@ git commit -m "chore(prototype): add HTML screens (<theme>)"
 - [ ] If no stored basic auth: [auth picker](auth-picker.md) run — username/password collected, `prototype auth` executed, `prototype/htpasswd` present
 - [ ] If no stored theme: [theme picker](theme-picker.md) run — 3 recommendations, previews opened, user confirmed
 - [ ] `prototype setup` run with resolved theme
+- [ ] Graph context queries run per screen ([prototype-graph-context.md](./prototype-graph-context.md)) before writing HTML
+- [ ] Every form field traces to an API request field or F-xx/UC-xx field definition
+- [ ] Every table column traces to an API response field or data entity
+- [ ] Every button/action label matches the spec's verb (not generic copy)
+- [ ] Error states and empty states included for all UC exception flows + API error codes
+- [ ] Role-based sections rendered when multiple actors satisfy the screen
 - [ ] Every generated file name matches `prototypeStem` in manifest
 - [ ] Wireframe/layout from screen detail doc reflected in HTML
 - [ ] Tokens from `prototype/DESIGN.md` only (no random CDN)

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,33 +4,35 @@ 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/**"
 ---
 
-# AI Spector — Generate SRS
+# Generate SRS
 
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
+## Load at start
+1. [references/runbook.md](references/runbook.md)
+2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md)
 
-## Required reading
+## Load when needed
 
-1. [references/runbook.md](references/runbook.md) — SRS-specific DAG, waves, finish
-2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md) — scope, confirm, per-wave checklist
-3. [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) — query, merge, ingest
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| Writing §1 Introduction | [references/srs-context/introduction.md](references/srs-context/introduction.md) |
+| Writing §2 Overall Description | [references/srs-context/overall-description.md](references/srs-context/overall-description.md) |
+| Writing §3 UC list or UC-xx detail | [references/srs-context/use-case-detail.md](references/srs-context/use-case-detail.md) |
+| Writing §4 feature list or F-xx detail | [references/srs-context/feature-detail.md](references/srs-context/feature-detail.md) |
+| Writing §5 Data Requirements | [references/srs-context/data-requirements.md](references/srs-context/data-requirements.md) |
+| Writing §6 External Interfaces | [references/srs-context/external-interfaces.md](references/srs-context/external-interfaces.md) |
+| Writing §7 Quality Attributes | [references/srs-context/quality-attributes.md](references/srs-context/quality-attributes.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) |
 
-## Checklist
+## On CLI failure
+Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-```
-- [ ] language confirmed (language-picker.md — check before first write)
-- [ ] graph validate
-- [ ] runbook + generate-workflow followed
-- [ ] templates from .ai-spector/templates/srs/
-- [ ] merge + validate each wave
-- [ ] ai-spector index when runbook says so
-```
-
-## Natural language
-
-“generate SRS”, “write requirements”, “use case chapter”, “feature list” → this skill.
+"generate SRS", "write requirements", "use case chapter", "feature list" → this skill.

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

@@ -8,6 +8,7 @@ Generate SRS markdown **from the traceability graph** in DAG order.
 |-----------------|----------|
 | Scope cases, waves, merge, finish, guardrails | [generate-workflow.md](../../ai-spector/references/generate-workflow.md) |
 | Graph query, ingest patch, parallelism | [generate-graph.md](../../ai-spector/references/generate-graph.md) |
+| **Graph → template section mapping** | **[srs-context/](./srs-context/) — load the matching section file before writing each doc type** |
 
 ## Intent → DAG hints
 
@@ -46,6 +47,22 @@ Templates: `.ai-spector/templates/srs/`
 
 Follow [generate-workflow.md](../../ai-spector/references/generate-workflow.md) for planning and per-wave execution.
 
+## Graph context (required before writing each file)
+
+After running queries ([generate-graph.md](../../ai-spector/references/generate-graph.md) § C), load the matching file from `srs-context/` for the doc type being written:
+
+| Writing | Load |
+|---|---|
+| §1 Introduction | `srs-context/introduction.md` |
+| §2 Overall Description | `srs-context/overall-description.md` |
+| §3 UC list or UC-xx detail | `srs-context/use-case-detail.md` |
+| §4 feature list or F-xx detail | `srs-context/feature-detail.md` |
+| §5 Data Requirements | `srs-context/data-requirements.md` |
+| §6 External Interfaces | `srs-context/external-interfaces.md` |
+| §7 Quality Attributes | `srs-context/quality-attributes.md` |
+
+Every UC-xx, F-xx, and actor in output must exist as a graph node. No invented identifiers.
+
 ## SRS-specific ingest notes
 
 - List chapters need `rendersTo` from template `doc.srs.*` nodes.

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/data-requirements.md

@@ -0,0 +1,10 @@
+# Graph → §5 Data Requirements
+
+Query: `doc.srs.5-data-requirements` DEPS depth 2, then each `dataEntity` node CONTEXT depth 3.
+
+| Template section | Graph source |
+|---|---|
+| **Entity list** | All `dataEntity` nodes → name, description, linked F-xx via `satisfies` / `partOf` |
+| **Entity fields** | `dataEntity.fields` array → name, type, required, constraints |
+| **Relationships** | `relatesTo` / `dependsOn` edges between entities → cardinality from edge properties |
+| **Retention rules** | Entity `retention` property or NFR nodes referencing entities |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/external-interfaces.md

@@ -0,0 +1,10 @@
+# Graph → §6 External Interfaces
+
+Query: `doc.srs.6-external-interfaces` DEPS depth 2, then each `api` / `externalSystem` node.
+
+| Template section | Graph source |
+|---|---|
+| **6.1 User Interfaces** | Screen nodes → names, purposes; actor nodes → which screens they use |
+| **6.2 Software Interfaces** | API / `externalSystem` nodes → name, protocol, purpose; `dependsOn` from F-xx |
+| **6.3 Hardware Interfaces** | NFR nodes tagged `hardware` |
+| **6.4 Communication Interfaces** | Protocol / integration nodes; NFR nodes tagged `communication` |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/feature-detail.md

@@ -0,0 +1,20 @@
+# Graph → §4 Feature detail (per F-xx)
+
+Query: `F-xx` CONTEXT depth 4.
+
+| Template section | Graph source |
+|---|---|
+| **Name / Priority / Description** | F-xx node `name`, `priority`, `description` |
+| **User Story** | F-xx `userStory`; or derive from actor + description |
+| **In / Out of Scope** | F-xx `scope.in`, `scope.out` arrays |
+| **Related Use Cases** | UC nodes via `satisfies` inbound → UC-xx ids and names |
+| **§2 Stimulus/Response** | UC `mainFlow` steps for linked UCs; actor name from actor node |
+| **§2 Error Handling** | UC `exceptionFlows` + F-xx `errorHandling` array |
+| **§3 Functional Requirements** | F-xx `requirements` → FR-xx-nn ids, descriptions, priority, acceptance criteria |
+| **§3 Input Data** | F-xx `inputData` or entity nodes via `dependsOn` |
+| **§3 Output Data** | F-xx `outputData` or entity response fields |
+| **§3 UI — Screens** | Screen nodes linked via `satisfies` |
+| **§3 Dependencies** | `dependsOn` edges → other F-xx or external system nodes |
+| **§3 Assumptions** | F-xx `assumptions` array |
+
+For the **§4 list chapter**: query `doc.srs.4-system-features-list` CONTEXT depth 2 → extract all `feature` nodes sorted by id; include linked UC ids.

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/introduction.md

@@ -0,0 +1,12 @@
+# Graph → §1 Introduction
+
+Query: `doc.srs.1-introduction` CONTEXT depth 2 + system root node.
+
+| Template section | Graph source |
+|---|---|
+| **1.1 Product Name** | System node `name` |
+| **1.1 Intended Audience** | All `actor` nodes → roles |
+| **1.3 Major Features** | All `feature` nodes → F-xx names (graph only, no invented) |
+| **1.3 Scope / Purpose** | System node `description` or data-source summary |
+| **1.3 Out of Scope** | Nodes marked `outOfScope: true`; explicit exclusions in data-source |
+| **1.4 References** | `rendersTo` / `definedIn` edges → data-source files |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/overall-description.md

@@ -0,0 +1,11 @@
+# Graph → §2 Overall Description
+
+Query: `doc.srs.2-overall-description` CONTEXT depth 3.
+
+| Template section | Graph source |
+|---|---|
+| **Product perspective** | System node; `relatesTo` external systems |
+| **User classes / actors** | All `actor` nodes → name, role, permissions |
+| **Operating environment** | NFR nodes tagged `environment` or `infrastructure` |
+| **Constraints** | NFR nodes tagged `constraint` |
+| **Assumptions** | Nodes or edges tagged `assumption` |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/quality-attributes.md

@@ -0,0 +1,11 @@
+# Graph → §7 Quality Attributes / NFR
+
+Query: `ai-spector graph query nfr --direction both --depth 2 --json` (or NFR bundle node).
+
+| Template section | Graph source |
+|---|---|
+| **Performance** | NFR `category: performance` → thresholds, response time, throughput |
+| **Security** | NFR `category: security` |
+| **Reliability / Availability** | NFR `category: reliability` or `availability` |
+| **Scalability** | NFR `category: scalability` |
+| **Maintainability** | NFR `category: maintainability` |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/use-case-detail.md

@@ -0,0 +1,26 @@
+# Graph → §3 Use Case detail (per UC-xx)
+
+Query: `UC-xx` CONTEXT depth 4.
+
+| Template section | Graph source |
+|---|---|
+| **Name / Description** | UC node `name`, `description` |
+| **Primary Actor** | Actor linked via `satisfies` or `partOf` inbound |
+| **Secondary Actors** | Additional actor nodes in neighbourhood |
+| **Priority** | UC node `priority` |
+| **Preconditions** | UC `preconditions` array; or `dependsOn` UCs that must complete first |
+| **Postconditions** | UC `postconditions` array |
+| **Trigger** | UC `trigger` property |
+| **§2 Main Flow** | UC `mainFlow` steps → one numbered row per step |
+| **§3 Alternative Flows** | UC `alternativeFlows` → one subsection per entry |
+| **§4 Exception Flows** | UC `exceptionFlows` / `errorFlows` + F-xx `errorHandling` for linked features |
+| **§5 Business Rules** | F-xx `businessRules` via `satisfies` outbound → BR-xx-nn ids |
+| **§6 Functional Requirements** | F-xx FR list via `satisfies` → FR-xx-nn ids |
+| **§7 Input Data** | F-xx `inputData` + `dataEntity` nodes via `dependsOn` |
+| **§7 Output Data** | F-xx `outputData` + `dataEntity` nodes reachable from UC |
+| **§8 UI Requirements** | Screen nodes linked via `satisfies` → screen names and ids |
+| **§9 Related Use Cases** | UC nodes via `relatesTo`, `includes`, `extends` edges |
+
+For the **§3 list chapter** (not per-file): query `doc.srs.3-use-cases` CONTEXT depth 2 → extract all `useCase` nodes, sorted by id.
+
+**Rule:** Every UC and F-xx in output must exist as a graph node. Missing node → `<!-- TODO: node missing in graph -->`.

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,33 +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/**"
----
-
-# AI Spector — Generate detail 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)
-
-## Checklist
-
-```
-- [ ] language confirmed (language-picker.md — check before first write)
-- [ ] graph validate; SRS + basic design present
-- [ ] generate-workflow waves + merge per target
-```
-
-## Natural language
-
-“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`**.