ai-spector 0.8.30 → 0.8.32

package/package.json

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

package/scaffold/claude/.claude/skills/ai-spector-resolve-task/skill.md

@@ -0,0 +1,43 @@
+---
+name: ai-spector-resolve-task
+description: >-
+  Conversational task workflow (create task, resolve task): clarify intent, build
+  GoalSpec + TaskPlan, get approval, then execute via resolve_task MCP or CLI.
+  Use for create task, add/update requirements, doc edits, prototype changes, or
+  any multi-step change described in natural language.
+---
+
+# AI Spector — Resolve Task
+
+## When to use
+
+- "create task", "create a task", "new task", "resolve task"
+- "add requirement", "update docs", "change prototype", "I want to…", "we need to…"
+- Any open-ended doc/graph change that is not a full generate-from-scratch workflow
+
+## Workflow
+
+```
+1. Receive user intent (do not act yet)
+2. Ask ≤3 clarifying questions → build GoalSpec
+3. Show GoalSpec + TaskPlan → wait for approval
+4. Execute: direct edits + resolve_task MCP (or CLI)
+5. Report state update
+```
+
+Full runbook: `.cursor/skills/ai-spector-resolve-task/references/runbook.md` (same content after init/sync-cursor).
+
+## Checklist
+
+```
+- [ ] Clarified intent → GoalSpec (domain, scope, criteria)
+- [ ] Showed plan and got user approval
+- [ ] Executed steps (edits + resolve_task for index/graph steps)
+- [ ] Reported results + state update
+```
+
+## MCP
+
+`resolve_task({ intent, goalSpec, plan, dryRun? })` — only after user approves the plan.
+
+CLI fallback: `npx ai-spector resolve-task plan.json`

package/scaffold/claude/CLAUDE.md

@@ -90,6 +90,7 @@ Skip impact/index only when the user explicitly says it was a typo-only fix with
 | Translation status | `ai-spector-lang-status` |
 | Resolve translations | `ai-spector-resolve-translation` |
 | Resolve comments | `ai-spector-resolve-comments` |
+| Create task / open-ended doc change | `ai-spector-resolve-task` |
 
 ## Quick reference
 
@@ -111,6 +112,7 @@ Skip impact/index only when the user explicitly says it was a typo-only fix with
 | `cocoindex_index({})` | Rebuild semantic embeddings |
 | `docs_search({ query })` | Semantic doc search (CocoIndex) |
 | `graph_query_fuzzy({ query })` | Natural language graph lookup (CocoIndex) |
+| `resolve_task({ intent, goalSpec, plan })` | Execute an approved task plan (index, graph_merge, etc.) |
 
 ### CLI (fallback / MCP-unavailable or no tool equivalent)
 
@@ -124,6 +126,7 @@ npx ai-spector template list        # list installed packs + active
 npx ai-spector template scan <path> # scan a template folder → scan-result.json
 npx ai-spector template install     # install pack from staging (AI writes manifest first)
 npx ai-spector template use <name>  # switch active pack (use "builtin" to revert)
+npx ai-spector resolve-task plan.json   # execute approved task plan
 
 # CocoIndex (opt-in — requires Python 3.11+)
 npx ai-spector cocoindex setup      # scaffold pipeline into project

package/scaffold/cursor/WORKFLOW.md

@@ -38,6 +38,7 @@ Then: add files under `docs/data-source/`, enable **all** skills under `.cursor/
 | Translation status | “what’s stale in JP”, “pending translations” | `ai-spector-lang-status` | `lang_queue({})` MCP |
 | Sync translations | “resolve translations”, “update JP from EN” | `ai-spector-resolve-translation` | read queue → translate → `index({ cocoindexSync: true })` |
 | Review comments | “resolve comments”, “fix C-001” | `ai-spector-resolve-comments` | inbox → plan → edit → commit |
+| Create task / change docs | “create a task”, “add requirement”, “update SRS section”, “I want to…” | `ai-spector-resolve-task` | clarify → show GoalSpec + TaskPlan → approve → `resolve_task` MCP or direct edits |
 | Explore graph | “show the graph” | `ai-spector-graph` | `npx ai-spector graph visualize --open` (no MCP equivalent) |
 
 Unsure? The agent uses [skills/_skill-router.md](./skills/_skill-router.md) or asks one clarifying question.

package/scaffold/cursor/skills/README.md

@@ -17,6 +17,7 @@ Enable **every** folder under `.cursor/skills/` in Cursor (Settings → Rules
 | Screens, APIs, DB basic design | `ai-spector-generate-basic-design` |
 | HTML prototype | `ai-spector-generate-prototype` |
 | Review comments | `ai-spector-resolve-comments` |
+| Create task / open-ended doc change | `ai-spector-resolve-task` |
 | Translation status (read-only) | `ai-spector-lang-status` |
 | Resolve / sync translations | `ai-spector-resolve-translation` |
 | Unsure | `ai-spector` (core) |

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

@@ -28,6 +28,7 @@ Agents use this when intent is ambiguous.
 | screens, APIs, wireframes, basic design | `ai-spector-generate` | `SKILL.md` (checks `packs.basicDesign`, then routes) |
 | HTML prototype | `ai-spector-generate-prototype` | `references/runbook.md` |
 | set up template pack, import template, custom template, install template | `ai-spector-template-import` | `references/runbook.md` |
+| create task, new task, resolve task, add requirement, update docs, change prototype, new section, "I want to…", "we need to…" | `ai-spector-resolve-task` | `references/runbook.md` |
 | review comments, C-001, inbox | `ai-spector-resolve-comments` | `references/runbook.md` |
 | translation status, stale langs | `ai-spector-lang-status` | `SKILL.md` |
 | resolve translations, sync JP/VI | `ai-spector-resolve-translation` | `references/runbook.md` |

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

@@ -5,7 +5,8 @@ description: >-
   and routing to task skills. Use when the user mentions ai-spector, docflow, or .npx ai-spector but the
   task is unclear, or for init and project layout. Do not use when the user clearly wants SRS,
   basic design, HTML prototype, graph operations, or comment resolution — use the
-  matching task skill instead.
+  matching task skill instead. For open-ended doc/graph changes or "create task",
+  use ai-spector-resolve-task.
 ---
 
 # AI Spector (core)
@@ -33,6 +34,7 @@ When the `ai-spector` MCP server is enabled (`.cursor/mcp.json` or `.mcp.json` l
 | Rebuild semantic embeddings | `cocoindex_index({})` | `npx ai-spector cocoindex index` |
 | Semantic doc search | `docs_search({ query })` | `npx ai-spector cocoindex search --query …` |
 | Natural language graph lookup | `graph_query_fuzzy({ query })` | *(no CLI equivalent)* |
+| Execute approved task plan | `resolve_task({ intent, goalSpec, plan })` | `npx ai-spector resolve-task plan.json` |
 | **Visualize graph** | *(no MCP tool)* | `npx ai-spector graph visualize --open` |
 
 Use CLI **only** when: MCP server is not configured, the tool errors, or no MCP equivalent exists (visualize, `lang add`, template mutations).
@@ -84,6 +86,7 @@ When `npx ai-spector` exits non-zero, required `--json` is invalid, or a require
 | Comments | `ai-spector-resolve-comments` |
 | Translation status / stale languages | `ai-spector-lang-status` |
 | Resolve / sync translations | `ai-spector-resolve-translation` |
+| Create task, open-ended doc/graph change | `ai-spector-resolve-task` |
 | “Generate docs” (vague) | `ai-spector-generate` |
 
 When a task skill applies, read its `references/` runbook fully before acting.

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

@@ -0,0 +1,38 @@
+---
+name: ai-spector-resolve-task
+description: >-
+  Conversational task workflow (create task, resolve task): agent clarifies user
+  intent, builds a GoalSpec + TaskPlan, shows it for approval, then executes via
+  the resolve_task MCP tool or CLI. Use when the user wants to create a task,
+  add/update a requirement, change a prototype, update docs, regenerate
+  sections, or any multi-step doc/graph change described in natural language.
+paths:
+  - "docs/**"
+  - "prototype/**"
+  - ".ai-spector/**"
+---
+
+# AI Spector — Resolve Task
+
+**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
+
+## Required reading
+
+[references/runbook.md](references/runbook.md) — follow phases in order.
+
+## Checklist
+
+```
+- [ ] Receive user intent (free-form)
+- [ ] Ask ≤3 clarifying questions → build GoalSpec
+- [ ] Show GoalSpec + TaskPlan → wait for approval
+- [ ] Execute via resolve_task MCP tool (or CLI)
+- [ ] Report results + state update
+```
+
+## Natural language triggers → this skill
+
+"create task", "create a task", "new task", "resolve task", "run a task",
+"add requirement", "update docs", "change prototype", "new feature section",
+"update SRS", "regenerate screens", "I want to…", "we need to…",
+any open-ended change request that is not a full generate-from-scratch workflow.

package/scaffold/cursor/skills/ai-spector-resolve-task/references/runbook.md

@@ -0,0 +1,177 @@
+# Resolve Task — conversational runbook
+
+Chat-first workflow for any multi-step doc/graph change. User describes intent in plain language; agent clarifies, plans, gets approval, then executes.
+
+---
+
+## Phase 1 — Receive intent
+
+User sends a free-form message. **Do not act yet.** Just read and move to Phase 2.
+
+Examples:
+- "create a task to add authentication to the SRS"
+- "add an authentication requirement to the SRS"
+- "change the prototype theme to dark"
+- "we need a new API section in basic design"
+
+---
+
+## Phase 2 — Clarify (≤ 3 questions)
+
+Ask only what is needed to fill `GoalSpec`. Stop when you can answer all four fields.
+
+| Field | What to clarify |
+|-------|----------------|
+| `domain` | Which area: docs / prototype / graph / template / lang? |
+| `scope` | Which specific files or sections change? |
+| `criteria` | What does "done" look like? |
+| `notes` | Any constraints, tone, related nodes? |
+
+**Rules:**
+- Ask at most 3 questions per round; batch them in one message.
+- If the intent is already specific enough, skip to Phase 3.
+- Do not propose edits or generate content yet.
+
+**Example clarification message:**
+> To make sure I plan this correctly:
+> 1. Should this go in the main SRS (`docs/srs/`) or a language variant?
+> 2. Is there an existing section to extend, or does this need a new one?
+> 3. What does "done" look like — e.g. the section exists + graph reindexed?
+
+---
+
+## Phase 3 — Build and show the plan
+
+Once you have enough to fill `GoalSpec`, construct the plan and **show it in chat** before doing anything.
+
+### GoalSpec format (show this)
+
+```
+Domain : docs
+Scope  : docs/srs/02-features.md
+Criteria:
+  - FR-AUTH section present with at least 3 requirements
+  - graph reindexed successfully
+Notes  : keep consistent with existing FR-PAY section style
+```
+
+### TaskPlan format (show this)
+
+| # | Step | Tool |
+|---|------|------|
+| s1 | Edit docs/srs/02-features.md — add FR-AUTH section | (direct edit) |
+| s2 | Re-index project | `index` |
+| s3 | Merge knowledge | `graph_merge` |
+
+**Risk level:** low / medium / high / critical (from impact analysis)
+
+**Then ask:** "Does this plan look right? Reply **yes** to execute, or tell me what to change."
+
+Do not proceed until the user confirms.
+
+---
+
+## Phase 4 — Execute
+
+After approval, run each step in order.
+
+### Steps that are direct edits
+Use the Edit / Write tools directly. Report each file changed.
+
+### Steps that call MCP tools
+Use the `resolve_task` MCP tool with the approved plan:
+
+```json
+{
+  "intent": "<original user message>",
+  "goalSpec": {
+    "trigger": "<original user message>",
+    "domain": "docs",
+    "scope": ["docs/srs/02-features.md"],
+    "criteria": ["FR-AUTH section present", "graph reindexed"]
+  },
+  "plan": {
+    "goal": { "...same as goalSpec..." },
+    "steps": [
+      { "id": "s2", "description": "Re-index project", "tool": "index", "args": {} },
+      { "id": "s3", "description": "Merge knowledge",  "tool": "graph_merge", "args": {} }
+    ]
+  }
+}
+```
+
+Or via CLI if MCP is unavailable:
+
+```bash
+# write plan.json, then:
+npx ai-spector resolve-task plan.json
+```
+
+### If a step is blocked
+Report the blocker in chat. Ask the user: "Step **sN** is blocked: `<reason>`. Should I skip it, retry, or stop?"
+
+---
+
+## Phase 5 — Report state update
+
+After execution, show a summary:
+
+```
+✓ Task task-abc123 — COMPLETE
+  domain: docs  risk: low
+
+Steps:
+  ✓ [s1] Edit docs/srs/02-features.md
+  ✓ [s2] Re-index project
+  ✓ [s3] Merge knowledge
+
+State update:
+  reindexed: 1 file(s)
+  graph diff: +2 -0 ~1
+  3 file(s) changed across 3 steps
+```
+
+Then ask if there is anything else to adjust.
+
+---
+
+## Replanning
+
+If the user changes their mind after seeing the plan (Phase 3), go back to Phase 2 — update `GoalSpec` + `TaskPlan` and show the revised plan again.
+
+If a step fails mid-execution, either:
+- Replan without that step and continue, or
+- Stop and report the full blocker to the user
+
+---
+
+## Guardrails
+
+- **Never start editing** before the user approves the plan.
+- **Never skip the clarify phase** — even one ambiguous word can target the wrong file.
+- **Never run `resolve_task` with an unapproved plan.**
+- Ask for approval once, clearly. Don't loop approval prompts.
+
+---
+
+## CLI reference
+
+| Command | Purpose |
+|---------|---------|
+| `npx ai-spector resolve-task plan.json` | Execute a pre-built plan JSON |
+| `npx ai-spector resolve-task plan.json --dry-run` | Validate without writing |
+| `npx ai-spector resolve-task plan.json --json` | Machine-readable output |
+
+MCP tool: `resolve_task` (schema: `ResolveTaskSchema`)
+
+---
+
+## If blocked
+
+See [cli-failures.md](../../ai-spector/references/cli-failures.md).
+
+| Issue | Fix |
+|-------|-----|
+| `No executor registered for tool "X"` | Use a supported tool: `index`, `graph_merge`, `graph_report`, `graph_impact` |
+| Plan JSON parse error | Validate JSON with `node -e "JSON.parse(require('fs').readFileSync('plan.json','utf8'))"` |
+| Reindex fails | Check `npx ai-spector setup --check` first |