code-as-plan 2.0.0

package/commands/cap/annotate.md

@@ -0,0 +1,165 @@
+---
+name: cap:annotate
+description: "Retroactively annotate existing code with @cap-feature and @cap-todo tags. Invokes cap-prototyper in ANNOTATE mode."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<!-- @gsd-context CAP v2.0 annotate command -- invokes cap-prototyper in annotate mode to add @cap-feature tags to existing unannotated code. Primary entry point after brownfield init. -->
+<!-- @gsd-decision Annotate is a thin command wrapper over cap-prototyper ANNOTATE mode. This avoids a separate agent and keeps all code generation/modification in one agent with mode dispatch. -->
+<!-- @gsd-decision Annotate targets a specific directory or defaults to project root src/. Scoped annotation prevents overwhelming the user with changes across the entire codebase at once. -->
+
+<!-- @gsd-todo(ref:AC-89) /cap:annotate shall invoke cap-prototyper in annotate mode -->
+
+<objective>
+Add @cap-feature and @cap-todo tags to existing unannotated code by invoking cap-prototyper in ANNOTATE mode. This is the recommended next step after brownfield /cap:init.
+
+**Arguments:**
+- `[path]` -- directory or file to annotate (defaults to `src/` or project root)
+- `--feature F-NNN` -- scope annotation to a specific Feature Map entry
+- `--dry-run` -- preview annotations without writing files
+
+**Requires:** FEATURE-MAP.md must exist (run /cap:init first).
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 1: Validate prerequisites
+
+Check that CAP is initialized:
+
+```bash
+test -d .cap && echo "CAP_INITIALIZED" || echo "NOT_INITIALIZED"
+test -f FEATURE-MAP.md && echo "FEATURE_MAP_EXISTS" || echo "NO_FEATURE_MAP"
+```
+
+If not initialized, abort with: "CAP is not initialized. Run /cap:init first."
+
+## Step 2: Parse arguments
+
+- Extract `path` from positional argument (default: `src/` if exists, else `.`)
+- Extract `--feature` flag if present
+- Extract `--dry-run` flag if present
+
+## Step 3: Load context for annotate mode
+
+Read FEATURE-MAP.md to understand available features and ACs.
+
+Check for existing tags in target path:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const tags = scanner.scanDirectory(process.cwd());
+const groups = scanner.groupByFeature(tags);
+console.log(JSON.stringify({
+  totalTags: tags.length,
+  features: Object.keys(groups),
+  filesWithTags: new Set(tags.map(t => t.file)).size
+}));
+"
+```
+
+Load stack docs if available:
+
+```bash
+ls .cap/stack-docs/*.md 2>/dev/null | head -10 || echo "no stack docs"
+```
+
+## Step 4: Invoke cap-prototyper in ANNOTATE mode
+
+Use the Task tool to spawn cap-prototyper with ANNOTATE mode:
+
+```
+Task("cap-prototyper", "
+**MODE: ANNOTATE**
+
+**Target path:** {resolved_path}
+**Feature scope:** {feature_id or 'all'}
+**Dry run:** {dry_run}
+
+**FEATURE-MAP.md content:**
+{feature_map_content}
+
+**Existing tags found:**
+{existing_tag_summary}
+
+**Stack docs available:**
+{stack_docs_list}
+
+**Instructions:**
+1. Scan {target_path} for source files without @cap-feature tags
+2. Read each unannotated file and identify significant functions, classes, modules
+3. Match code to Feature Map entries based on purpose and file paths
+4. Use the Edit tool to add @cap-feature tags WITHOUT changing code logic
+5. Add @cap-todo tags for any unfinished work discovered during annotation
+6. {If dry_run: 'OUTPUT the proposed changes but do NOT write files'}
+")
+```
+
+## Step 5: Run scan after annotation
+
+After the prototyper completes, run a scan to update Feature Map:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const tags = scanner.scanDirectory(process.cwd());
+const updated = fm.enrichFromTags(process.cwd(), tags);
+console.log(JSON.stringify({
+  totalTags: tags.length,
+  featuresWithFiles: updated.features.filter(f => f.files.length > 0).length,
+  totalFileRefs: updated.features.reduce((sum, f) => sum + f.files.length, 0)
+}));
+"
+```
+
+## Step 6: Report results
+
+```
+cap:annotate complete.
+
+Files annotated: {N}
+Tags added: {N}
+  @cap-feature: {N}
+  @cap-todo:    {N}
+  @cap-risk:    {N}
+  @cap-decision:{N}
+
+Feature Map updated:
+  Features with file refs: {N}
+  Total file references:   {N}
+
+Next steps:
+  /cap:scan      -- verify tag coverage
+  /cap:prototype -- build out features that need implementation
+  /cap:status    -- view project dashboard
+```
+
+## Step 7: Update session
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:annotate',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'annotated'
+});
+"
+```
+
+</process>

package/commands/cap/brainstorm.md

@@ -0,0 +1,238 @@
+---
+name: cap:brainstorm
+description: Interactive feature discovery conversation that produces Feature Map entries with acceptance criteria, feature grouping, and dependency analysis. Spawns cap-brainstormer agent.
+argument-hint: "[--resume] [--multi]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @gsd-context CAP v2.0 brainstorm command -- orchestrates conversational feature discovery. Spawns cap-brainstormer agent, receives structured Feature Map entries, writes to FEATURE-MAP.md after user approval. -->
+<!-- @gsd-decision Writes directly to FEATURE-MAP.md (not PRD files). Feature Map is the single source of truth in CAP. PRDs are an intermediate artifact that CAP eliminates. -->
+<!-- @gsd-decision Command layer owns all file I/O -- agent is stateless. Proven pattern from GSD brainstorm.md. -->
+<!-- @gsd-constraint No Feature Map entries are written without explicit user approval -- confirmation gate is mandatory -->
+
+<objective>
+Spawns the `cap-brainstormer` agent to have a structured conversation about what needs to be built. The agent returns structured Feature Map entries. This command presents the entries for user confirmation, then writes to FEATURE-MAP.md.
+
+<!-- @gsd-todo(ref:AC-36) /cap:brainstorm shall invoke the cap-brainstormer agent for conversational feature discovery. -->
+
+**Arguments:**
+- `--resume` -- resume a previous brainstorm session using .cap/SESSION.json context
+- `--multi` -- hint that the project has multiple independent feature areas
+
+**Key guarantee:** No Feature Map entries are written until the user explicitly approves.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--resume` -- if present, set `resume_mode = true`
+- `--multi` -- if present, set `multi_mode = true`
+
+Log: "cap:brainstorm | resume: {resume_mode} | multi: {multi_mode}"
+
+## Step 1: Load existing Feature Map and session state
+
+Read FEATURE-MAP.md:
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const featureMap = fm.readFeatureMap(process.cwd());
+console.log(JSON.stringify({
+  featureCount: featureMap.features.length,
+  existingIds: featureMap.features.map(f => f.id),
+  existingTitles: featureMap.features.map(f => f.title)
+}));
+"
+```
+
+Store as `existing_features`.
+
+If `resume_mode`:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+console.log(JSON.stringify(s));
+"
+```
+
+Store as `session_context`.
+
+## Step 2: Spawn cap-brainstormer agent
+
+<!-- @gsd-todo(ref:AC-37) cap-brainstormer shall produce structured PRD output with numbered acceptance criteria. -->
+<!-- @gsd-todo(ref:AC-39) cap-brainstormer shall assign feature IDs in sequential format (F-001, F-002, ...). -->
+
+Spawn `cap-brainstormer` via the Task tool with the following context:
+
+```
+$ARGUMENTS
+
+**Session context:**
+Resume mode: {resume_mode}
+Multi-feature hint: {multi_mode}
+Existing features: {existing_features.featureCount} features already in FEATURE-MAP.md
+Existing IDs: {existing_features.existingIds}
+Next available ID: F-{padded next number}
+
+{If resume_mode and session_context:}
+**Previous session context:**
+Active feature: {session_context.activeFeature}
+Last step: {session_context.step}
+Last command: {session_context.lastCommand}
+{End if}
+
+**Instructions:**
+1. Have a conversational exchange with the user to understand what needs to be built
+2. Ask targeted questions ONE AT A TIME -- do not present a list of questions
+3. After sufficient understanding, cluster features into logical groups
+4. Surface dependencies between feature groups
+5. For each feature, draft numbered acceptance criteria in imperative form
+6. Assign feature IDs starting from {next available ID}
+7. Return the feature entries in the exact structured format below
+
+**Return format (delimited):**
+
+=== BRAINSTORM OUTPUT ===
+FEATURE_COUNT: N
+
+=== FEATURE: F-NNN ===
+TITLE: {verb+object title}
+GROUP: {logical group name}
+DEPENDS_ON: {comma-separated F-IDs or "none"}
+AC-1: {imperative description}
+AC-2: {imperative description}
+...
+=== END FEATURE ===
+
+{Repeat for each feature}
+
+=== DECISIONS ===
+- {decision 1}
+- {decision 2}
+=== END DECISIONS ===
+
+=== END BRAINSTORM OUTPUT ===
+
+Do NOT write any files -- return structured output only.
+```
+
+Wait for `cap-brainstormer` to complete.
+
+**Parse the agent output:**
+
+1. Extract between `=== BRAINSTORM OUTPUT ===` and `=== END BRAINSTORM OUTPUT ===`
+2. Parse `FEATURE_COUNT:` line
+3. For each `=== FEATURE: F-NNN ===` block, extract: TITLE, GROUP, DEPENDS_ON, and all AC-N lines
+4. Extract decisions from `=== DECISIONS ===` block
+5. Build Feature objects:
+
+```javascript
+{
+  id: "F-NNN",
+  title: "extracted title",
+  state: "planned",
+  acs: [{ id: "AC-1", description: "...", status: "pending" }, ...],
+  files: [],
+  dependencies: ["F-NNN", ...],
+  metadata: { group: "group name" }
+}
+```
+
+## Step 3: Present features for user approval
+
+<!-- @gsd-todo(ref:AC-38) cap-brainstormer shall write discovered features directly to FEATURE-MAP.md with state planned. -->
+<!-- @gsd-todo(ref:AC-40) cap-brainstormer output shall be directly consumable by /cap:prototype without manual translation. -->
+
+Display the parsed features:
+
+```
+Brainstorm complete. {feature_count} features discovered:
+
+{For each feature:}
+  {feature.id}: {feature.title} [{feature.state}]
+    Group: {group}
+    Dependencies: {deps or "none"}
+    Acceptance criteria:
+      AC-1: {description}
+      AC-2: {description}
+      ...
+{End for}
+
+Decisions made:
+{For each decision:}
+  - {decision}
+{End for}
+```
+
+Use AskUserQuestion:
+> "Review the {feature_count} features above. Approve writing to FEATURE-MAP.md? [yes / provide corrections / restart]"
+
+- If `yes`, `y`, or `approve`: proceed to Step 4
+- If corrections: Re-spawn `cap-brainstormer` with original context + `**Corrections from user:** {user text}`. Re-parse and re-display. Loop back to approval gate.
+- If `restart`: Clear all parsed data. Go back to Step 2 with fresh Task() call.
+
+**IMPORTANT:** No code path reaches Step 4 without explicit user approval.
+
+## Step 4: Write approved features to FEATURE-MAP.md
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const featureMap = fm.readFeatureMap(process.cwd());
+const newFeatures = {JSON.stringify(parsed_features)};
+const updated = fm.addFeatures(featureMap, newFeatures);
+fm.writeFeatureMap(process.cwd(), updated);
+console.log('Written ' + newFeatures.length + ' features to FEATURE-MAP.md');
+"
+```
+
+## Step 5: Update session state
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:brainstorm',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'brainstorm-complete'
+});
+"
+```
+
+## Step 6: Final report
+
+```
+cap:brainstorm complete.
+
+Features written to FEATURE-MAP.md: {feature_count}
+  {For each feature: feature.id: feature.title}
+
+Decisions recorded: {decision_count}
+
+Next steps:
+  - Run /cap:start to select a feature to work on
+  - Run /cap:prototype --features {first_feature_id} to build initial code
+  - Run /cap:brainstorm --resume to continue discovery later
+```
+
+</process>

package/commands/cap/debug.md

@@ -0,0 +1,297 @@
+---
+name: cap:debug
+description: Systematic debugging with persistent state across context resets. Spawns cap-debugger agent using scientific method.
+argument-hint: "[issue description]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<!-- @gsd-context CAP v2.0 debug command -- orchestrates scientific debugging. Gathers symptoms, spawns cap-debugger agent, handles checkpoints and continuations. Debug state persists in .cap/debug/. -->
+<!-- @gsd-decision Debug state in .cap/debug/ (not .planning/debug/) -- CAP centralizes all runtime state under .cap/ -->
+<!-- @gsd-pattern Orchestrator gathers symptoms and spawns agent. Fresh context per investigation to avoid context exhaustion. -->
+
+<objective>
+<!-- @gsd-todo(ref:AC-63) /cap:debug shall invoke the cap-debugger agent using a scientific method approach. -->
+
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn cap-debugger agent, handle checkpoints, spawn continuations.
+
+**Why subagent:** Investigation burns context fast. Fresh context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active sessions:
+```bash
+ls .cap/debug/*.md 2>/dev/null | head -5
+```
+</context>
+
+<process>
+
+## Step 0: Load session and project context
+
+<!-- @gsd-todo(ref:AC-64) cap-debugger shall maintain persistent debug state across the debug session. -->
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const s = session.loadSession(process.cwd());
+const debugDir = path.join(process.cwd(), '.cap', 'debug');
+let activeSessions = [];
+if (fs.existsSync(debugDir)) {
+  activeSessions = fs.readdirSync(debugDir)
+    .filter(f => f.startsWith('SESSION-') && f.endsWith('.md'))
+    .map(f => {
+      const content = fs.readFileSync(path.join(debugDir, f), 'utf8');
+      const statusMatch = content.match(/^## Status: (.+)$/m);
+      return { file: f, status: statusMatch ? statusMatch[1] : 'unknown' };
+    });
+}
+console.log(JSON.stringify({
+  activeFeature: s.activeFeature,
+  activeDebugSession: s.activeDebugSession,
+  existingSessions: activeSessions
+}));
+"
+```
+
+Store as `debug_context`.
+
+## Step 1: Check for active or resumable debug sessions
+
+If `debug_context.activeDebugSession` is set:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const sessionFile = path.join(process.cwd(), '.cap', 'debug', 'SESSION-{debug_context.activeDebugSession}.md');
+if (fs.existsSync(sessionFile)) {
+  console.log(fs.readFileSync(sessionFile, 'utf8'));
+} else {
+  console.log('NOT_FOUND');
+}
+"
+```
+
+If active session found, display:
+
+```
+Active debug session found: SESSION-{id}
+Status: {status}
+```
+
+Use AskUserQuestion:
+> "Resume existing debug session SESSION-{id}, or start a new investigation? [resume / new]"
+
+- If `resume`: load existing session content, proceed to Step 3 with session context
+- If `new`: generate new session ID, proceed to Step 2
+
+If no active session: proceed to Step 2.
+
+## Step 2: Gather symptoms
+
+If `$ARGUMENTS` contains an issue description, use it as initial symptoms.
+
+If `$ARGUMENTS` is empty, use AskUserQuestion:
+> "Describe the issue you are investigating. Include: what you expected, what actually happened, any error messages, and when this started."
+
+Store as `symptoms`.
+
+Generate a new debug session ID:
+
+```bash
+node -e "
+const crypto = require('node:crypto');
+const id = crypto.randomBytes(4).toString('hex');
+console.log(id);
+"
+```
+
+Store as `session_id`.
+
+Create the debug session file:
+
+Write `.cap/debug/SESSION-{session_id}.md` using the Write tool:
+
+```markdown
+# Debug Session: {session_id}
+
+## Status: investigating
+
+## Symptoms
+{symptoms}
+
+## Context
+- Active feature: {debug_context.activeFeature or 'none'}
+- Timestamp: {ISO timestamp}
+
+## Hypotheses
+<!-- Cap-debugger will populate this section -->
+
+## Tests Performed
+<!-- Cap-debugger will populate this section -->
+
+## Findings
+<!-- Cap-debugger will populate this section -->
+
+## Resolution
+<!-- Populated when root cause is found and fix is applied -->
+```
+
+Update session:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  activeDebugSession: '{session_id}',
+  lastCommand: '/cap:debug',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'debug-investigating'
+});
+"
+```
+
+## Step 3: Spawn cap-debugger agent
+
+<!-- @gsd-todo(ref:AC-65) cap-debugger shall follow a hypothesis -> test -> verify loop, documenting each step. -->
+<!-- @gsd-todo(ref:AC-66) cap-debugger shall not modify production code without explicit developer approval. -->
+
+Identify relevant files from the active feature:
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+const featureMap = fm.readFeatureMap(process.cwd());
+const feature = s.activeFeature ? featureMap.features.find(f => f.id === s.activeFeature) : null;
+console.log(JSON.stringify({
+  files: feature ? feature.files : [],
+  title: feature ? feature.title : 'unknown'
+}));
+"
+```
+
+Spawn `cap-debugger` via Task tool:
+
+```
+**DEBUG SESSION: {session_id}**
+
+**Symptoms:**
+{symptoms}
+
+{If resuming:}
+**Previous session state:**
+{existing session file content}
+{End if}
+
+**Active feature:** {feature.title or 'none'}
+
+<files_to_read>
+{For each file in feature.files: - file}
+- .cap/debug/SESSION-{session_id}.md
+</files_to_read>
+
+**Instructions:**
+1. Read all files listed above
+2. Analyze symptoms and form ranked hypotheses
+3. Test each hypothesis through code reading and execution
+4. Document each step in the debug session file
+5. DO NOT modify production code -- only observe and test
+6. When root cause is found, propose a fix and wait for approval
+
+**Return format:**
+=== DEBUG RESULT ===
+STATUS: ROOT_CAUSE_FOUND | CHECKPOINT_REACHED | DEBUG_COMPLETE
+SESSION_ID: {session_id}
+{If ROOT_CAUSE_FOUND:}
+ROOT_CAUSE: {description}
+PROPOSED_FIX: {description}
+FILES_TO_MODIFY: [list]
+{End if}
+{If CHECKPOINT_REACHED:}
+CHECKPOINT_REASON: {what user input is needed}
+NEXT_STEPS: {what to investigate next}
+{End if}
+=== END DEBUG RESULT ===
+```
+
+Wait for cap-debugger to complete. Parse the result.
+
+## Step 4: Handle agent result
+
+**If STATUS == ROOT_CAUSE_FOUND:**
+
+Display:
+```
+Root cause found:
+{root_cause}
+
+Proposed fix:
+{proposed_fix}
+
+Files to modify:
+{files_to_modify}
+```
+
+Use AskUserQuestion:
+> "Apply the proposed fix? [yes / no / modify: instructions]"
+
+- If `yes`: Spawn cap-debugger again with `**MODE: APPLY_FIX**` and the proposed fix details. The agent applies the fix and runs verification.
+- If `no`: Update session file status to `root_cause_found_pending`, end debug session.
+- If `modify: <instructions>`: Spawn cap-debugger again with modified fix instructions.
+
+**If STATUS == CHECKPOINT_REACHED:**
+
+Display checkpoint reason and next steps.
+
+Use AskUserQuestion:
+> "{checkpoint_reason}. Provide the requested information, or type 'stop' to pause the session."
+
+- If user provides info: Re-spawn cap-debugger with the new information added to context.
+- If `stop`: Update session file, end session. User can resume later with `/cap:debug`.
+
+**If STATUS == DEBUG_COMPLETE:**
+
+Log: "Debug session {session_id} complete."
+
+## Step 5: Update session and report
+
+Update debug session file with resolution (via Write tool).
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  activeDebugSession: null,
+  lastCommand: '/cap:debug',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'debug-complete'
+});
+"
+```
+
+```
+cap:debug complete.
+
+Session: {session_id}
+Status: {final_status}
+Debug log: .cap/debug/SESSION-{session_id}.md
+
+{If fix applied:}
+Fix applied and verified. Run /cap:test to confirm no regressions.
+{End if}
+```
+
+</process>