code-as-plan 2.0.0

package/commands/cap/prototype.md

@@ -0,0 +1,281 @@
+---
+name: cap:prototype
+description: Feature Map-driven prototype pipeline -- reads FEATURE-MAP.md, confirms ACs with user, spawns cap-prototyper to build annotated code scaffold. Supports --architecture and --annotate modes.
+argument-hint: "[path] [--features NAME] [--architecture] [--annotate] [--interactive] [--non-interactive]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @gsd-context CAP v2.0 prototype command -- reads Feature Map as primary input (not PRD). Spawns cap-prototyper in one of 4 modes. Auto-runs /cap:scan on completion. -->
+<!-- @gsd-decision Feature Map replaces PRD as prototype input. Feature Map ACs become @cap-todo(ac:FEATURE/AC-N) tags in generated code. -->
+<!-- @gsd-decision Auto-chains to /cap:scan on completion -- keeps Feature Map status in sync after code generation. -->
+<!-- @gsd-pattern --features flag scopes prototype to specific Feature Map entries (replaces --phases scoping from GSD) -->
+
+<objective>
+<!-- @gsd-todo(ref:AC-41) /cap:prototype shall invoke the cap-prototyper agent which operates in four modes: prototype, iterate, architecture, and annotate. -->
+
+Reads FEATURE-MAP.md, confirms acceptance criteria with the user, then spawns cap-prototyper in the appropriate mode to build annotated code. Each AC becomes a @cap-todo tag in the prototype.
+
+On completion, automatically runs `/cap:scan` to update Feature Map status.
+
+**Arguments:**
+- `path` -- target directory for prototype output (defaults to project root)
+- `--features NAME` -- scope prototype to specific Feature Map entries (comma-separated)
+- `--architecture` -- skeleton-only mode (folders, interfaces, config, module boundaries)
+- `--annotate` -- retroactively annotate existing code with @cap-feature tags
+- `--interactive` -- pause after each iteration
+- `--non-interactive` -- skip AC confirmation gate (for CI)
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--features NAME` -- if present, store as `feature_filter` (comma-separated)
+- `--architecture` -- if present, set `mode = "ARCHITECTURE"`
+- `--annotate` -- if present, set `mode = "ANNOTATE"`
+- `--interactive` -- if present, set `interactive_mode = true`
+- `--non-interactive` -- if present, set `non_interactive = true`
+- `path` -- target directory (defaults to `.`)
+
+If neither `--architecture` nor `--annotate`: set `mode = "PROTOTYPE"`
+
+Log: "cap:prototype | mode: {mode} | features: {feature_filter or 'all'} | interactive: {interactive_mode}"
+
+## Step 1: Read Feature Map and load 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 featureMap = fm.readFeatureMap(process.cwd());
+const s = session.loadSession(process.cwd());
+console.log(JSON.stringify({
+  activeFeature: s.activeFeature,
+  features: featureMap.features.map(f => ({
+    id: f.id, title: f.title, state: f.state,
+    acs: f.acs, files: f.files, dependencies: f.dependencies
+  }))
+}));
+"
+```
+
+Store as `fm_data`.
+
+**Scope features:**
+- If `feature_filter` is set: filter to matching feature IDs
+- Else if `fm_data.activeFeature` is set: use only that feature
+- Else: use all features with state `planned` or `prototyped`
+
+Store filtered list as `target_features`.
+
+If `target_features` is empty: STOP and report:
+> "No features in scope. Run /cap:brainstorm to discover features, or specify --features."
+
+## Step 2: Present ACs for confirmation
+
+**Skip if `non_interactive` or `mode == "ANNOTATE"`.**
+
+<!-- @gsd-todo(ref:AC-42) In prototype mode, the agent shall build a working prototype for a feature, annotating code with @cap-feature and @cap-todo tags as it builds. -->
+<!-- @gsd-todo(ref:AC-44) In architecture mode, the agent shall analyze and refactor system-level structure without changing feature behavior. -->
+<!-- @gsd-todo(ref:AC-45) In annotate mode, the agent shall retroactively annotate existing code with @cap-feature and @cap-todo tags. -->
+
+Collect all ACs from target_features:
+
+```
+Features to prototype ({target_features.length}):
+
+{For each feature:}
+  {feature.id}: {feature.title} [{feature.state}]
+  {For each AC:}
+    {ac.id}: {ac.description} [{ac.status}]
+  {End for}
+{End for}
+
+Total ACs: {total_ac_count}
+```
+
+Use AskUserQuestion:
+> "Review the {total_ac_count} acceptance criteria above. Proceed with {mode} mode? [yes / provide corrections]"
+
+- If `yes`: proceed to Step 3
+- If corrections: incorporate and re-display
+
+## Step 3: Derive project context and spawn cap-prototyper
+
+<!-- @gsd-todo(ref:AC-47) cap-prototyper shall derive project context (language, framework, conventions) from actual code on first invocation. -->
+<!-- @gsd-todo(ref:AC-48) cap-prototyper shall follow deviation rules via a shared reference document. -->
+
+Detect project conventions:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const cwd = process.cwd();
+const conventions = {};
+
+// Package.json conventions
+if (fs.existsSync(path.join(cwd, 'package.json'))) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+  conventions.type = pkg.type || 'commonjs';
+  conventions.scripts = Object.keys(pkg.scripts || {});
+}
+
+// Check for config files
+conventions.hasEslint = fs.existsSync(path.join(cwd, '.eslintrc.json')) || fs.existsSync(path.join(cwd, '.eslintrc.js'));
+conventions.hasPrettier = fs.existsSync(path.join(cwd, '.prettierrc'));
+conventions.hasTsconfig = fs.existsSync(path.join(cwd, 'tsconfig.json'));
+
+// Detect naming patterns from existing files
+const entries = fs.readdirSync(path.join(cwd, 'cap/bin/lib')).filter(f => f.endsWith('.cjs'));
+conventions.namingPattern = entries.length > 0 ? 'kebab-case.cjs' : 'unknown';
+
+console.log(JSON.stringify(conventions));
+"
+```
+
+Store as `conventions`.
+
+Load .cap/stack-docs/ if available:
+
+```bash
+ls .cap/stack-docs/*.md 2>/dev/null | head -10 || echo "no stack docs"
+```
+
+Spawn `cap-prototyper` via Task tool:
+
+**MODE: PROTOTYPE prompt:**
+```
+$ARGUMENTS
+
+**MODE: {mode}**
+
+**Target features:**
+{For each target_feature:}
+Feature: {feature.id} - {feature.title} [{feature.state}]
+Dependencies: {feature.dependencies.join(', ') or 'none'}
+{For each AC:}
+  {ac.id}: {ac.description}
+{End for}
+{End for}
+
+**Project conventions:**
+{JSON.stringify(conventions)}
+
+**Tag obligations:**
+- Every significant function/class/module gets @cap-feature(feature:{ID}) linking to FEATURE-MAP.md
+- Every AC gets @cap-todo(ac:{FEATURE-ID}/AC-N) placed where the implementation happens
+- Risk areas get @cap-risk tags
+- Design decisions get @cap-decision tags
+
+**Deviation rules:**
+If you need to deviate from the Feature Map specification (e.g., an AC is impractical, dependencies changed), document the deviation with:
+// @cap-decision Deviated from {FEATURE-ID}/AC-N: {reason}
+Do not silently skip ACs. Every AC must have either an implementation tag or a deviation tag.
+
+{If mode == "ARCHITECTURE":}
+Generate ONLY structural artifacts:
+1. Folder structure with index/barrel files at module boundaries
+2. Config files matching existing project conventions
+3. Typed interfaces and type definitions for module boundaries
+4. Entry point stubs
+5. @cap-decision tags at every module boundary
+ZERO feature implementation code.
+{End if}
+
+{If mode == "ANNOTATE":}
+Do NOT create new files. Only EDIT existing files to add @cap-feature and @cap-todo tags.
+Scan the target directory for source files, read each, and add appropriate tags.
+{End if}
+
+{If stack docs available:}
+**Stack documentation available in .cap/stack-docs/:**
+{list of available docs}
+Read these before generating code that uses those libraries.
+{End if}
+```
+
+Wait for cap-prototyper to complete.
+
+## Step 4: Update Feature Map state
+
+<!-- @gsd-todo(ref:AC-46) cap-prototyper shall update the feature state in FEATURE-MAP.md from planned to prototyped upon completing a prototype. -->
+
+If `mode == "PROTOTYPE"`:
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const targetIds = {JSON.stringify(target_feature_ids)};
+for (const id of targetIds) {
+  const result = fm.updateFeatureState(process.cwd(), id, 'prototyped');
+  console.log(id + ': ' + (result ? 'updated to prototyped' : 'state unchanged'));
+}
+"
+```
+
+## Step 5: Auto-run /cap:scan
+
+<!-- @gsd-todo(ref:AC-43) In iterate mode, the agent shall refine an existing prototype based on feedback, updating tags and Feature Map state. -->
+
+```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);
+const groups = scanner.groupByFeature(tags);
+console.log(JSON.stringify({
+  totalTags: tags.length,
+  featuresEnriched: updated.features.filter(f => f.files.length > 0).length,
+  featureGroups: Object.keys(groups).length
+}));
+"
+```
+
+## Step 6: Update session and report
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:prototype',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'prototype-complete'
+});
+"
+```
+
+```
+cap:prototype complete ({mode} mode).
+
+Features processed: {target_features.length}
+{For each feature: feature.id: feature.title -> {new_state}}
+
+Tag scan results:
+  Total @cap-* tags: {scan_result.totalTags}
+  Features with file refs: {scan_result.featuresEnriched}
+
+Next steps:
+  - Run /cap:iterate to refine the prototype
+  - Run /cap:test to write tests against the ACs
+  - Run /cap:scan for detailed tag report
+```
+
+</process>

package/commands/cap/refresh-docs.md

@@ -0,0 +1,37 @@
+---
+name: cap:refresh-docs
+description: Fetch or refresh library documentation via Context7 and store in .cap/stack-docs/ for agent context injection.
+argument-hint: "<library-name> [--query \"question\"]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<!-- @gsd-context CAP v2.0 refresh-docs command -- fetches library documentation via Context7 CLI and caches it in .cap/stack-docs/. Agents read these docs for library-specific context without burning tokens on web searches. -->
+<!-- @gsd-decision Uses Context7 CLI (npx ctx7@latest) -- the user's CLAUDE.md already mandates Context7 for library docs. This command makes it a first-class workflow step. -->
+<!-- @gsd-decision Docs cached in .cap/stack-docs/ -- persists across conversations, can be committed for offline use. -->
+<!-- @gsd-pattern Each library gets its own file: .cap/stack-docs/{library-name}.md -->
+
+<objective>
+Fetches library documentation via Context7 and stores it in .cap/stack-docs/ for agent context injection.
+
+**Arguments:**
+- `library-name` -- the library to fetch docs for (e.g., "react", "express", "prisma")
+- `--query "question"` -- specific question to focus the documentation fetch
+</objective>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+
+<!-- @gsd-todo Implement Step 1: Parse library name and optional query -->
+<!-- @gsd-todo Implement Step 2: Run npx ctx7@latest library <name> to find library ID -->
+<!-- @gsd-todo Implement Step 3: Run npx ctx7@latest docs <id> to fetch documentation -->
+<!-- @gsd-todo Implement Step 4: Write fetched docs to .cap/stack-docs/{library-name}.md -->
+<!-- @gsd-todo Implement Step 5: Report what was cached and how agents can use it -->
+
+</process>

package/commands/cap/review.md

@@ -0,0 +1,272 @@
+---
+name: cap:review
+description: Two-stage code review -- Stage 1 checks Feature Map AC compliance, Stage 2 checks code quality. Stage 2 only runs if Stage 1 passes.
+argument-hint: "[--features NAME] [--stage2-only]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @gsd-context CAP v2.0 review command -- orchestrates two-stage code review. Collects test results, reads Feature Map ACs, spawns cap-reviewer agent. -->
+<!-- @gsd-decision Stage 2 only runs if Stage 1 passes -- prevents wasted review cycles on code that does not meet spec. -->
+<!-- @gsd-decision Review output goes to .cap/REVIEW.md -- centralized under .cap/ runtime directory. -->
+
+<objective>
+<!-- @gsd-todo(ref:AC-58) /cap:review shall invoke the cap-reviewer agent for two-stage review. -->
+
+Runs two-stage code review:
+1. Stage 1: Check Feature Map AC compliance (does the code implement what was promised?)
+2. Stage 2: Check code quality (security, maintainability, error handling)
+
+Stage 2 only runs if Stage 1 passes.
+
+**Arguments:**
+- `--features NAME` -- scope review to specific Feature Map entries
+- `--stage2-only` -- skip Stage 1, run only code quality review
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--features NAME` -- if present, store as `feature_filter`
+- `--stage2-only` -- if present, set `stage2_only = true`
+
+## Step 1: Collect test results
+
+Run existing tests to get current pass/fail state:
+
+```bash
+node --test tests/*.test.cjs 2>&1 | tail -30
+```
+
+Store output as `test_output` and exit code as `test_exit_code`.
+
+## Step 2: Read Feature Map ACs for review scope
+
+<!-- @gsd-todo(ref:AC-59) Stage 1: cap-reviewer shall verify that the implementation satisfies all acceptance criteria listed in the Feature Map entry. -->
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const session = require('./cap/bin/lib/cap-session.cjs');
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const featureMap = fm.readFeatureMap(process.cwd());
+const s = session.loadSession(process.cwd());
+const tags = scanner.scanDirectory(process.cwd());
+const groups = scanner.groupByFeature(tags);
+
+console.log(JSON.stringify({
+  activeFeature: s.activeFeature,
+  features: featureMap.features.map(f => ({
+    id: f.id, title: f.title, state: f.state,
+    acs: f.acs, files: f.files
+  })),
+  tagGroups: Object.fromEntries(
+    Object.entries(groups).map(([k, v]) => [k, v.map(t => ({ type: t.type, file: t.file, line: t.line, description: t.description }))])
+  )
+}));
+"
+```
+
+**Scope features:**
+- If `feature_filter`: filter to matching IDs
+- Else if active feature: use only that feature
+- Else: use all features with state `tested`
+
+Store as `review_features`.
+
+## Step 3: Spawn cap-reviewer for Stage 1 (AC compliance)
+
+<!-- @gsd-todo(ref:AC-61) cap-reviewer shall check that all code implementing the feature has appropriate @cap-feature annotations. -->
+
+**Skip Stage 1 if `stage2_only`.**
+
+Spawn `cap-reviewer` via Task tool:
+
+```
+**STAGE 1: ACCEPTANCE CRITERIA COMPLIANCE**
+
+**Features under review:**
+{For each review_feature:}
+Feature: {feature.id} - {feature.title} [{feature.state}]
+Implementation files: {feature.files.join(', ')}
+Acceptance criteria:
+{For each AC:}
+  {ac.id}: {ac.description} [{ac.status}]
+{End for}
+{End for}
+
+**Tag evidence:**
+{For each feature in tagGroups:}
+  {feature_id}: {tags.length} tags across {unique files}
+{End for}
+
+**Test results:**
+{test_output}
+Test exit code: {test_exit_code}
+
+**Stage 1 checklist:**
+For each AC in each feature under review:
+1. Is there code that implements this AC?
+2. Is the implementing code annotated with @cap-feature(feature:{ID})?
+3. Is there a test that verifies this AC?
+4. Does the test pass?
+
+**Return format:**
+=== STAGE 1 RESULTS ===
+VERDICT: PASS | FAIL
+{For each feature:}
+FEATURE: {id}
+{For each AC:}
+  {ac.id}: PASS | FAIL | PARTIAL -- {evidence or reason}
+{End for}
+{End for}
+MISSING_ANNOTATIONS: [list of files implementing features without @cap-feature tags]
+=== END STAGE 1 RESULTS ===
+```
+
+Parse the Stage 1 results.
+
+**If Stage 1 VERDICT is FAIL and NOT `stage2_only`:**
+
+Display Stage 1 failures and STOP:
+
+```
+cap:review Stage 1 FAILED.
+
+{For each failing AC:}
+  {feature.id}/{ac.id}: FAIL -- {reason}
+{End for}
+
+{If missing annotations:}
+Missing @cap-feature annotations:
+  {For each file: - file}
+{End if}
+
+Stage 2 (code quality) skipped -- fix Stage 1 issues first.
+Run /cap:iterate to address gaps, then re-run /cap:review.
+```
+
+## Step 4: Spawn cap-reviewer for Stage 2 (code quality)
+
+<!-- @gsd-todo(ref:AC-60) Stage 2: cap-reviewer shall perform code quality review (naming, structure, complexity, test coverage, tag completeness). -->
+
+Spawn `cap-reviewer` via Task tool:
+
+```
+**STAGE 2: CODE QUALITY REVIEW**
+
+{If not stage2_only:}
+Stage 1 passed. All ACs verified.
+{End if}
+
+**Features under review:**
+{For each review_feature:}
+Feature: {feature.id} - {feature.title}
+Implementation files: {feature.files.join(', ')}
+{End for}
+
+**Review checklist:**
+1. **Naming:** Are function/variable/file names clear and consistent with project conventions?
+2. **Structure:** Is the code organized logically? Are modules appropriately sized?
+3. **Complexity:** Are there functions > 50 lines? Deep nesting > 3 levels? Cyclomatic complexity concerns?
+4. **Error handling:** Are errors handled gracefully? Are edge cases covered?
+5. **Security:** Any hardcoded credentials, SQL injection vectors, XSS risks, path traversal?
+6. **Test coverage:** Are critical paths tested? Are error paths tested?
+7. **Tag completeness:** Does every significant function have @cap-feature annotation?
+8. **Dependencies:** Are there unnecessary imports or tight coupling between modules?
+
+**Return format:**
+=== STAGE 2 RESULTS ===
+VERDICT: PASS | PASS_WITH_NOTES | FAIL
+FINDINGS:
+{numbered list of findings with severity: critical/warning/note}
+TOP_5_ACTIONS:
+1. {actionable improvement}
+2. ...
+=== END STAGE 2 RESULTS ===
+```
+
+Parse Stage 2 results.
+
+## Step 5: Update Feature Map status
+
+<!-- @gsd-todo(ref:AC-62) cap-reviewer shall update the feature state in FEATURE-MAP.md from tested to shipped upon passing both review stages. -->
+
+If both stages pass (or Stage 1 skipped with `stage2_only` and Stage 2 passes):
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const targetIds = {JSON.stringify(target_feature_ids)};
+for (const id of targetIds) {
+  const result = fm.updateFeatureState(process.cwd(), id, 'shipped');
+  console.log(id + ': ' + (result ? 'updated to shipped' : 'state unchanged'));
+}
+"
+```
+
+Write review report:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const capDir = path.join(process.cwd(), '.cap');
+if (!fs.existsSync(capDir)) fs.mkdirSync(capDir, { recursive: true });
+// Write review file (content constructed by command layer from parsed results)
+"
+```
+
+Write `.cap/REVIEW.md` using the Write tool with the combined Stage 1 + Stage 2 findings.
+
+Update session:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:review',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'review-complete'
+});
+"
+```
+
+## Step 6: Final report
+
+```
+cap:review complete.
+
+Stage 1 (AC compliance): {PASS or FAIL or SKIPPED}
+Stage 2 (Code quality):  {PASS or PASS_WITH_NOTES or FAIL}
+
+{If both pass:}
+Feature state updated: {feature_ids} -> shipped
+Review report: .cap/REVIEW.md
+
+Top 5 actions:
+{top_5_actions}
+{End if}
+
+{If stage 2 has notes:}
+Review passed with notes. See .cap/REVIEW.md for details.
+{End if}
+```
+
+</process>