ai-spector 0.3.1 → 0.3.2

package/scaffold/cursor/commands/resolve-comments.md

@@ -0,0 +1,145 @@
+# /resolve-comments
+
+IDE-first workflow (Cursor) for **git-backed review comments** under `comments/`. Web reviewers create threads; you resolve locally: inbox in chat → pick thread → impact → propose edit → apply → commit (doc + resolve meta) → push.
+
+No Writer API — storage is git-only (`meta_data.json` + `events.jsonl`).
+
+## Usage
+
+| You say | Agent does |
+|---------|------------|
+| `/resolve-comments` | Inbox table in chat → wait for your pick |
+| `/resolve-comments C-001` | Plan + impact for pick **C-001** |
+| `/resolve-comments srs/01-overview` | Inbox filtered to that file |
+
+## IDE workflow (agent — follow in order)
+
+### Phase 0 — Sync
+
+```bash
+git pull
+```
+
+### Phase 1 — Show thread pick list in chat (user selects)
+
+```bash
+ai-spector comments inbox --json
+```
+
+**IDE presentation (required):**
+
+1. Read `idePresentation.markdown` from JSON — render **only that markdown table** in chat.
+2. Follow `idePresentation.rules`: **one row per open thread**, not per reply; **no raw JSON**; **no thread uuids** in user-facing text.
+3. Use **pick ids** (`C-001`, `C-002`, …) for selection.
+
+Example table (from CLI):
+
+| Pick | Document | Lines | Lang | Reviewer ask |
+|------|----------|-------|------|--------------|
+| **C-001** | `docs/srs/01-overview.md` | 12-14 | EN | Please clarify… |
+
+**Stop and ask:** “Which thread should we resolve? Reply with **C-00N**.”
+
+Do not start editing until the user picks (unless they already passed `C-001` in the slash command).
+
+**Do not use** `comments list` for user selection — use **`comments inbox`** only.
+
+### Phase 2 — Plan + impact (after pick)
+
+```bash
+ai-spector comments plan C-001 --json
+```
+
+**Show in chat:** full thread comments, anchored doc text, impact summary, regen targets.
+
+### Phase 3 — Propose edit (user approval required)
+
+1. Quote anchored lines + reviewer ask
+2. Propose concrete markdown change
+3. Ask: **“Apply this edit?”** — wait for explicit approval
+
+### Phase 4 — Apply edit
+
+Edit `anchor.docPath` at lines `startLine`–`endLine`. Show diff summary in chat.
+
+### Phase 5 — Resolve status + single git commit (doc + comment meta)
+
+Each resolve must land in git with **both** the **document fix** and **comment thread metadata** — never commit only `comments/` without the changed doc file.
+
+**Steps:**
+
+```bash
+# 1) Stage and commit doc fix first (establishes resolvedInCommitSha target)
+git add docs/srs/....md
+git commit -m "fix(docs): address comment C-001 on srs/01-overview lines 12-14"
+
+# 2) Write resolve meta pointing at that doc commit
+ai-spector comments resolve <threadId> --file srs/01-overview \
+  --expected-version <v from plan> --json
+
+# 3) Stage comment meta AND re-include doc in the same final commit
+git add comments/srs/01-overview/<threadId>/ docs/srs/....md
+git commit --amend -m "fix(docs): address comment C-001 on srs/01-overview lines 12-14
+
+Resolved thread <threadId>. Pick C-001."
+
+git push
+```
+
+**Why amend:** `comments resolve` needs HEAD after the doc commit for `resolvedInCommitSha`. Amending folds `meta_data.json` + `events.jsonl` into the **same commit** as the doc change so one push contains the full resolve.
+
+**Commit must include:**
+
+| Path | Content |
+|------|---------|
+| `docs/…` | Edited document (the fix) |
+| `comments/…/{thread_id}/meta_data.json` | `status: resolved`, `resolvedInCommitSha`, … |
+| `comments/…/{thread_id}/events.jsonl` | append `resolved` event |
+
+**Never:** `git add` only `comments/` while doc changes stay unstaged or uncommitted.
+
+If HEAD moved before resolve, pass `--commit-sha <doc-fix-sha>` explicitly.
+
+### Phase 6 — Optional follow-up
+
+```bash
+ai-spector index
+```
+
+Or targeted `/generate-srs` / `/generate-basic-design` when plan lists regen targets.
+
+## Multi-thread session
+
+Re-run `comments inbox --json` → show `idePresentation.markdown` → ask for next pick.
+
+## Chat presentation rules
+
+- Inbox: **`idePresentation.markdown` table only** (threads, not replies)
+- Plan/impact: full detail after pick
+- Commits: **doc file + comment meta together** (amend pattern above)
+- Pick ids in chat; thread ids only in CLI args
+
+## CLI reference
+
+| Command | Purpose |
+|---------|---------|
+| `comments inbox [--json]` | Thread pick list + `idePresentation` for chat |
+| `comments plan C-001 [--json]` | Anchor excerpt + graph impact |
+| `comments resolve <threadId> --file <path> [--expected-version]` | Update meta before final amend commit |
+
+## Guardrails
+
+- No Writer API
+- No resolve before doc edit is applied
+- No commit with only metadata — **always include changed doc file**
+- No push until amend commit contains doc + `comments/…/thread/`
+
+## If blocked
+
+See [_cli-failures.md](./_cli-failures.md).
+
+| Issue | Fix |
+|-------|-----|
+| Unknown C-00N | Re-run `comments inbox --json` |
+| Stale version | Re-run `comments plan`, refresh `--expected-version` |
+| Doc missing from commit | `git status` — stage `docs/…` before amend |

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

@@ -0,0 +1,22 @@
+# AI Spector skill router
+
+Cursor loads skills by **description** when the user does not use a slash command. Enable **all** skills under `.cursor/skills/` after `init`.
+
+## Skills
+
+| Skill folder | When Cursor should use it |
+|--------------|---------------------------|
+| `ai-spector` | Any ai-spector / docflow / `.ai-spector` project work; shared CLI rules |
+| `ai-spector-graph` | Analyze, index, validate, impact, visualize, Graphify, knowledge.json, regen scope |
+| `ai-spector-generate` | Generate or update SRS, basic design, detail design under `docs/` |
+| `ai-spector-resolve-comments` | Review comments in `comments/`, resolve threads, C-001 pick list |
+
+## Slash commands (explicit)
+
+When the user runs `/analyze`, `/generate-srs`, `/resolve-comments`, etc., read the matching file in `.cursor/commands/` — skills and commands share the same rules.
+
+## Priority
+
+1. Explicit slash command → `commands/<name>.md`
+2. Natural language → task skill above + same command doc when one exists
+3. Ambiguous → `ai-spector` core + ask which task (graph vs generate vs comments)

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

@@ -0,0 +1,47 @@
+---
+name: ai-spector
+description: >-
+  AI Spector docflow core — traceability graph, .ai-spector project, CLI failure rules, templates.
+  Use when working in an ai-spector project but task is unclear; read _skill-router.md to pick a task skill.
+---
+
+# AI Spector (core)
+
+Shared rules for **all** ai-spector work. For a specific task, also load the matching task skill (see router below).
+
+**Workflow index:** `.cursor/commands/_workflow.md`
+**Skill router:** `.cursor/skills/_skill-router.md`
+
+## CLI failure rule (non-negotiable)
+
+When `ai-spector` exits non-zero or required `--json` is missing/invalid:
+
+1. **Stop** — no generate, no bulk `docs/srs/**` reads, no hand-editing the whole graph.
+2. **Report** per `.cursor/commands/_cli-failures.md` (verbatim CLI output + fix steps).
+3. **Fix**, then **re-run the same CLI**.
+
+Never bypass CLI with manual graph edits or invented content.
+
+## Graphify MCP
+
+`init` writes `.cursor/mcp.json` → graph at `.ai-spector/.docflow/graph/graphify-out/graph.json`.
+
+## Heart of the system
+
+`.ai-spector/graph/traceability.graph.json` — context via `ai-spector graph query <id> --json`.
+
+Run CLI from project root; prefer `npx ai-spector` if not on PATH.
+
+## Task skills (auto-routing)
+
+| User intent | Skill | Command doc |
+|-------------|-------|---------------|
+| Analyze, index, validate, impact, visualize graph | `ai-spector-graph` | `commands/analyze.md`, `index.md`, `impact.md`, … |
+| Generate SRS / basic design / detail design | `ai-spector-generate` | `commands/generate-*.md` |
+| Resolve review comments under `comments/` | `ai-spector-resolve-comments` | `commands/resolve-comments.md` |
+
+When the user uses a **slash command** (`/analyze`, `/generate-srs`, `/resolve-comments`), follow that command file directly — skills reinforce the same rules.
+
+## Templates
+
+Read from `.ai-spector/templates/` before any generation. Missing templates → `npx ai-spector init --force`.

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

@@ -0,0 +1,41 @@
+---
+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.
+---
+
+# AI Spector — Generate
+
+**Core rules:** `.cursor/skills/ai-spector/SKILL.md`
+**Graph context:** `.cursor/commands/_generate-graph.md`, `_graph.md`
+
+## Route to command doc
+
+| 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.

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

@@ -0,0 +1,39 @@
+---
+name: ai-spector-graph
+description: >-
+  AI Spector graph operations — analyze docs/data-source, index refresh, validate traceability graph,
+  impact/regen scope, visualize graph, link semantic edges. Use for /analyze, /index, /validate-graph,
+  /impact, /visualize-graph, or when user asks about traceability graph, knowledge.json, Graphify, or what to regenerate.
+---
+
+# AI Spector — Graph
+
+**Core rules:** `.cursor/skills/ai-spector/SKILL.md` (CLI failure, graph path).
+
+## Route to command doc
+
+| Trigger | Read first | CLI |
+|---------|------------|-----|
+| `/analyze`, ingest data-source, extract knowledge | `commands/analyze.md` | `ai-spector analyze` → graphify → merge → validate |
+| `/index`, refresh graph after edits | `commands/index.md` | `ai-spector index` |
+| `/validate-graph`, graph errors | `commands/validate-graph.md` | `ai-spector graph validate` |
+| `/impact`, what breaks, regen scope, git diff impact | `commands/impact.md` | `ai-spector graph impact … --json` |
+| `/visualize-graph`, explore graph in browser | `commands/visualize-graph.md` | `ai-spector graph visualize --open` |
+| `/link-graph`, semantic relatesTo edges | `commands/link-graph.md` | `graph merge --semantic` |
+| `/sync-graph` | `commands/sync-graph.md` | per command |
+| `/summary` (index summaries only) | `commands/summary.md` | index build under `.ai-spector/index/` |
+
+## Natural language → command
+
+| User says | Action |
+|-----------|--------|
+| "analyze my data source", "run analyze" | `/analyze` flow → `analyze.md` |
+| "refresh the graph", "re-index" | `/index` → `index.md` |
+| "validate graph", "graph has errors" | `/validate-graph` |
+| "what's the impact", "what do I need to regenerate" | `/impact` → `impact.md` |
+| "show the graph", "visualize traceability" | `/visualize-graph` |
+
+## References
+
+- Graph CLI details: `commands/_graph.md`
+- Generate graph patches: `commands/_generate-graph.md`

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

@@ -0,0 +1,42 @@
+---
+name: ai-spector-resolve-comments
+description: >-
+  AI Spector git-backed review comment resolve — list open threads, pick C-001, plan with impact,
+  propose doc fix, commit doc + comment meta. Use for /resolve-comments, comments/ folder,
+  meta_data.json, reviewer comments on SRS/basic design, or "resolve this comment thread".
+---
+
+# AI Spector — Resolve comments
+
+**Core rules:** `.cursor/skills/ai-spector/SKILL.md`
+**Full workflow:** `.cursor/commands/resolve-comments.md` (follow step-by-step)
+
+## Quick flow
+
+1. `git pull`
+2. `ai-spector comments inbox --json` → show **`idePresentation.markdown`** only (thread table, pick ids)
+3. User picks **C-00N** → `ai-spector comments plan C-00N --json` (impact + anchor)
+4. Propose edit → user approves → apply to `docs/…`
+5. Commit doc → `comments resolve` → amend commit with **doc + `comments/…/thread/`** → push
+
+## CLI
+
+| Step | Command |
+|------|---------|
+| Inbox | `ai-spector comments inbox --json` |
+| Plan | `ai-spector comments plan C-001 --json` |
+| Resolve meta | `ai-spector comments resolve <threadId> --file <logical_path> --expected-version <v>` |
+
+## Natural language → this skill
+
+| User says | Action |
+|-----------|--------|
+| "resolve comments", "fix review comments", "open comment threads" | Start inbox flow |
+| "address C-001", "resolve thread on srs/…" | `plan` then edit + commit |
+| "comments under comments/" | Git-only F-05 flow — no Writer API |
+
+## Guardrails
+
+- Inbox: thread table only — no raw JSON or thread uuids in chat
+- Commit must include **changed doc file** and comment meta (amend pattern in `resolve-comments.md`)
+- No resolve before doc fix is applied

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

@@ -1,62 +0,0 @@
----
-name: ai-spector
-description: "Cursor-first docs: user runs slash commands; agent runs CLI; on CLI failure stop and help fix — no manual bypass."
----
-
-# AI Spector Skill
-
-**Workflow:** `.cursor/commands/_workflow.md` — user only runs `npx ai-spector init` once, then slash commands.
-
-**Graphify MCP:** `init` configures `.cursor/mcp.json` → graph file at `.ai-spector/.docflow/graph/graphify-out/graph.json` (not `docs/data-source/graphify-out/`).
-
-## CLI failure rule (non-negotiable)
-
-When `ai-spector` exits non-zero or required `--json` is missing/invalid:
-
-1. **Stop** — no generate, no bulk `docs/srs/**` reads, no hand-editing the whole graph.
-2. **Report** using the format in `.cursor/commands/_cli-failures.md` (verbatim CLI output + plain fix steps).
-3. **Fix** the root cause, then **re-run the same CLI** and continue the slash command.
-
-Never ignore CLI errors and “work around” with index files, manual BFS, or inventing graph content. See `_cli-failures.md` for forbidden fallbacks.
-
-## Slash commands (user)
-
-| Command | Agent runs CLI |
-|---------|----------------|
-| `/analyze` | `analyze` → `graphify update` → Graphify MCP extract → `graph merge` → `graph validate` |
-| `/index` | `ai-spector index` — rebuild graph structure, re-merge knowledge, Graphify storage, doc indexes |
-| `/summary` | Build `.ai-spector/index/*.md` summaries (optional; graph is primary for generation) |
-| `/validate-graph` | `graph validate` |
-| `/visualize-graph` | `graph visualize --open` |
-| `/generate-srs` | All DAG, explicit paths, or natural-language scope (confirm before gen) → waves → query → write → merge |
-| `/impact` | Empty args → git diff + seeds; else resolve → `graph impact <id> --json` (optional `--git` / `--file` / `--heading`) |
-| `/generate-basic-design` | Same as SRS: all / paths / request (**confirm**) → waves → query → merge (`dag.basic-design.*`) |
-| `/generate-detail-design` | `graph query` per target |
-
-Run CLI from **project workspace root**; prefer `npx ai-spector` if the binary is not on PATH.
-
-## Heart of the system
-
-`.ai-spector/graph/traceability.graph.json`
-
-Context: **`ai-spector graph query <seedId> --json`** — depth 4 for targets, depth 2 for DAG deps; use `projectionPaths`. After each generated file: **`graph merge`** projection patch with `rendersTo` + `dependsOn`. Details: `_generate-graph.md`, `_graph.md`.
-
-**Generate:** accuracy over speed — batch only same-wave independent targets; merge + validate after each wave.
-
-## Templates (mandatory path)
-
-`npx ai-spector init` copies bundled templates to **`.ai-spector/templates/`** (see `docflow.config.json` → `paths.templates`).
-
-Before `/generate-srs`, `/generate-basic-design`, or `/generate-detail-design`:
-
-1. **Read** the template file from `.ai-spector/templates/` (DAG `template` field is relative to that root, e.g. `srs/1-introduction.md`, `basic_design/list-screen-template.md`).
-2. **Preserve** the template’s headings and section order in the output under `docs/`.
-3. If `.ai-spector/templates/` is missing, tell the user to run **`npx ai-spector init`** (or `init --force` to refresh) — do not guess structure from memory or search `node_modules`.
-
-| Kind | Directory |
-|------|-----------|
-| SRS | `.ai-spector/templates/srs/` |
-| Basic design | `.ai-spector/templates/basic_design/` |
-| Detail design | `.ai-spector/templates/detail_design/` |
-
-Optional index: `.ai-spector/templates/README.md`.