code-as-plan 2.0.0

package/commands/cap/init.md

@@ -0,0 +1,262 @@
+---
+name: cap:init
+description: "Initialize CAP project -- creates .cap/, FEATURE-MAP.md, detects dependencies via Context7, performs brownfield analysis on existing codebases."
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<!-- @gsd-context CAP v2.0 init command (final pass) -- adds mandatory Context7 integration and brownfield detection on top of the base init flow. -->
+<!-- @gsd-decision Context7 fetch is mandatory at init time per AC-81. If unreachable, warning is emitted but init continues with explicit marker in SESSION.json. -->
+<!-- @gsd-decision Brownfield analysis is ephemeral -- results are used as context for /cap:annotate suggestion, NOT persisted as a separate document (AC-87). -->
+<!-- @gsd-decision No /cap:map command exists. Codebase analysis is part of /cap:init only (AC-90). -->
+<!-- @gsd-constraint No prompts, wizards, or configuration forms. Init completes in a single invocation (AC-4, AC-5). -->
+
+<!-- @gsd-todo(ref:AC-81) Detect all dependencies from package.json / requirements.txt / Cargo.toml / go.mod and fetch docs via Context7 -->
+<!-- @gsd-todo(ref:AC-82) Store fetched stack docs in .cap/stack-docs/{library-name}.md compressed to API surface, config, breaking changes -->
+<!-- @gsd-todo(ref:AC-83) Agents receive .cap/stack-docs/ as context input on every invocation -->
+<!-- @gsd-todo(ref:AC-84) Stack-docs carry freshness marker (fetch date). Docs older than 7 days auto-refreshed. Manual refresh via /cap:refresh-docs -->
+<!-- @gsd-todo(ref:AC-85) Context7 fetching is MANDATORY at init. If unreachable, warning emitted and init continues with explicit marker -->
+<!-- @gsd-todo(ref:AC-86) Brownfield init performs one-time codebase analysis: architecture detection, convention detection, test setup detection -->
+<!-- @gsd-todo(ref:AC-87) Brownfield analysis result NOT persisted as separate document -- used as init context for /cap:annotate suggestion -->
+<!-- @gsd-todo(ref:AC-88) After brownfield init, suggest /cap:annotate to retroactively annotate existing code -->
+<!-- @gsd-todo(ref:AC-90) No /cap:map command. Codebase analysis is part of /cap:init -->
+<!-- @gsd-todo(ref:AC-91) To refresh codebase information: /cap:annotate + /cap:refresh-docs -->
+<!-- @gsd-todo(ref:AC-92) The 7 documents from .planning/codebase/ shall NOT be generated in v2.0 -->
+
+<objective>
+Initialize the CAP project structure with mandatory Context7 stack documentation fetch and brownfield codebase analysis. This command:
+
+1. Creates `.cap/` directory with subdirectories (stack-docs, debug)
+2. Creates `.cap/.gitignore` (ignores SESSION.json and debug/)
+3. Creates `.cap/SESSION.json` with default session state
+4. Creates `FEATURE-MAP.md` at project root (ONLY if it does not already exist)
+5. **Detects project dependencies** from manifest files (package.json, requirements.txt, Cargo.toml, go.mod)
+6. **Fetches stack documentation via Context7** for all detected dependencies
+7. **Performs brownfield analysis** if existing source code is detected
+8. Suggests `/cap:annotate` if brownfield code is found
+
+**Idempotent:** Safe to run multiple times. Never overwrites existing FEATURE-MAP.md.
+**Non-interactive:** No prompts, no wizards, no configuration forms.
+**Context7 is MANDATORY:** If unreachable, warning emitted and init continues with explicit marker.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 1: Detect project root and check initialization state
+
+Use Bash to check current state:
+
+```bash
+ls -la .cap/ 2>/dev/null && echo "ALREADY_INITIALIZED" || echo "FRESH_PROJECT"
+test -f FEATURE-MAP.md && echo "FEATURE_MAP_EXISTS" || echo "NO_FEATURE_MAP"
+```
+
+## Step 2: Create .cap/ directory structure
+
+```bash
+mkdir -p .cap/stack-docs .cap/debug
+```
+
+## Step 3: Write .cap/.gitignore
+
+Use the Write tool to create `.cap/.gitignore`:
+
+```
+# CAP ephemeral state -- do not commit
+SESSION.json
+debug/
+```
+
+## Step 4: Write .cap/SESSION.json (only if not exists)
+
+Check if SESSION.json exists first. If not, write default session:
+
+```json
+{
+  "version": "2.0.0",
+  "lastCommand": "/cap:init",
+  "lastCommandTimestamp": "<ISO_NOW>",
+  "activeFeature": null,
+  "step": "init",
+  "startedAt": "<ISO_NOW>",
+  "activeDebugSession": null,
+  "context7Available": null,
+  "metadata": {}
+}
+```
+
+Note the `context7Available` field -- this gets set in Step 6 to indicate whether Context7 was reachable.
+
+## Step 5: Write FEATURE-MAP.md (only if not exists)
+
+**CRITICAL: Skip this step if FEATURE-MAP.md already exists.**
+
+If FEATURE-MAP.md does NOT exist, write the empty template.
+
+## Step 6: Mandatory Context7 dependency fetch
+
+<!-- @gsd-decision Multi-language dependency detection runs in priority order: package.json first, then requirements.txt, then Cargo.toml, then go.mod. First match sets project type. -->
+
+### 6a: Detect dependencies
+
+Run dependency detection for all supported manifest files:
+
+```bash
+node -e "
+const stackDocs = require('./cap/bin/lib/cap-stack-docs.cjs');
+const result = stackDocs.detectDependencies(process.cwd());
+console.log(JSON.stringify(result, null, 2));
+"
+```
+
+Store the result as `dep_info`. Log: "Detected {dep_info.type} project with {dep_info.dependencies.length} dependencies."
+
+### 6b: Fetch stack docs via Context7
+
+For each dependency in `dep_info.dependencies` (limit to top 10 most important -- skip internal/scoped packages that start with `@company/`):
+
+```bash
+node -e "
+const stackDocs = require('./cap/bin/lib/cap-stack-docs.cjs');
+const depName = process.argv[1];
+const lib = stackDocs.resolveLibrary(depName, 'API surface and configuration');
+if (lib) {
+  const result = stackDocs.fetchDocs(process.cwd(), lib.id, 'API surface, configuration, breaking changes');
+  console.log(JSON.stringify({ library: depName, ...result }));
+} else {
+  console.log(JSON.stringify({ library: depName, success: false, error: 'Library not found in Context7' }));
+}
+" "<DEP_NAME>"
+```
+
+Track results:
+- `fetched_count` -- number of successfully fetched docs
+- `failed_count` -- number of failed fetches
+- `context7_available` -- true if at least one fetch succeeded
+
+### 6c: Handle Context7 unreachable
+
+If ALL fetches fail (context7_available = false):
+
+1. Update SESSION.json to set `context7Available: false`
+2. Emit warning:
+   ```
+   WARNING: Context7 is unreachable. Stack documentation could not be fetched.
+   Init continues without stack docs. Run /cap:refresh-docs when network is available.
+   ```
+
+If some fetches succeeded:
+1. Update SESSION.json to set `context7Available: true`
+2. Log summary: "Fetched docs for {fetched_count} of {total} dependencies."
+
+## Step 7: Brownfield codebase analysis
+
+<!-- @gsd-decision Brownfield analysis detects 3 things: (1) architecture pattern, (2) coding conventions, (3) test setup. Results are ephemeral -- used only for the /cap:annotate suggestion. -->
+
+### 7a: Check for existing source code
+
+```bash
+# Count source files by language
+find . -maxdepth 4 -not -path './node_modules/*' -not -path './.git/*' -not -path './.cap/*' \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \) | head -50
+```
+
+If NO source files are found, this is a greenfield project. Skip to Step 8.
+
+### 7b: Architecture detection (ephemeral)
+
+If source files exist, analyze the codebase structure:
+
+```bash
+# Detect directory structure pattern
+ls -d */ 2>/dev/null | head -20
+# Check for common framework indicators
+test -f tsconfig.json && echo "TYPESCRIPT"
+test -f next.config.js -o -f next.config.mjs && echo "NEXTJS"
+test -f vite.config.ts -o -f vite.config.js && echo "VITE"
+test -f Dockerfile && echo "DOCKER"
+test -d src && echo "SRC_DIR"
+test -d lib && echo "LIB_DIR"
+test -d packages && echo "MONOREPO"
+```
+
+### 7c: Convention detection (ephemeral)
+
+```bash
+# Check for linting/formatting config
+test -f .eslintrc.json -o -f .eslintrc.js -o -f eslint.config.js && echo "ESLINT"
+test -f .prettierrc -o -f .prettierrc.json && echo "PRETTIER"
+test -f .editorconfig && echo "EDITORCONFIG"
+```
+
+### 7d: Test setup detection (ephemeral)
+
+```bash
+# Check for test frameworks
+test -f jest.config.js -o -f jest.config.ts && echo "JEST"
+test -f vitest.config.ts -o -f vitest.config.js && echo "VITEST"
+test -d __tests__ -o -d tests -o -d test && echo "TEST_DIR_EXISTS"
+```
+
+### 7e: Suggest /cap:annotate
+
+If brownfield code was detected, output:
+
+```
+Existing codebase detected:
+  Source files: ~{count} files ({languages})
+  Architecture: {detected patterns}
+  Test setup: {detected test frameworks}
+
+Recommended: Run /cap:annotate to add @cap-feature tags to your existing code.
+This helps CAP track your features across the codebase.
+```
+
+**Do NOT persist the brownfield analysis as a separate document** (AC-87).
+
+## Step 8: Report results
+
+```
+CAP initialized.
+
+Created:
+  .cap/                   -- runtime directory
+  .cap/.gitignore         -- excludes SESSION.json from git
+  .cap/SESSION.json       -- ephemeral workflow state
+  .cap/stack-docs/        -- cached documentation ({fetched_count} docs fetched)
+  .cap/debug/             -- debug session logs
+  FEATURE-MAP.md          -- feature source of truth (or: already existed, preserved)
+
+Stack docs: {fetched_count} fetched, {failed_count} failed{context7_warning}
+
+Next steps:
+  /cap:brainstorm    -- generate features from conversation
+  /cap:annotate      -- add @cap-feature tags to existing code
+  /cap:prototype     -- build features from Feature Map
+  /cap:status        -- view project dashboard
+  /cap:refresh-docs  -- manually refresh stack documentation
+```
+
+## Step 9: Update session
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:init',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'initialized'
+});
+"
+```
+
+</process>

package/commands/cap/iterate.md

@@ -0,0 +1,234 @@
+---
+name: cap:iterate
+description: Code-first iteration loop -- runs scan, identifies Feature Map gaps, spawns cap-prototyper in ITERATE mode, re-scans, repeats until ACs are satisfied or user stops.
+argument-hint: "[--features NAME] [--max N] [--auto]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @gsd-context CAP v2.0 iterate command -- the flagship code-first loop. Scan -> identify gaps -> generate code -> re-scan -> repeat. Human approval gate between each iteration unless --auto is specified. -->
+<!-- @gsd-decision Iteration loop is scan-driven: /cap:scan output determines what to build next. No upfront planning step. -->
+<!-- @gsd-decision Human approval gate between iterations by default. --auto flag enables autonomous loop with --max N safety limit. -->
+<!-- @gsd-constraint --auto mode requires --max N to prevent runaway loops. Default max is 5 if --auto specified without --max. -->
+
+<objective>
+<!-- @gsd-todo(ref:AC-49) /cap:iterate shall invoke cap-prototyper in iterate mode. -->
+
+The core code-first iteration loop:
+1. Run /cap:scan to assess current Feature Map status
+2. Identify incomplete ACs and unimplemented features
+3. Spawn cap-prototyper in ITERATE mode to address gaps
+4. Re-scan to verify progress
+5. Present results to user, ask to continue or stop
+
+**Arguments:**
+- `--features NAME` -- scope iteration to specific Feature Map entries
+- `--max N` -- maximum number of iterations (default 5 with --auto)
+- `--auto` -- autonomous mode, no approval gate between iterations
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+<!-- @gsd-todo(ref:AC-50) /cap:iterate shall support a --auto flag for multi-iteration autonomous loops. -->
+
+Check `$ARGUMENTS` for:
+- `--features NAME` -- if present, store as `feature_filter`
+- `--max N` -- if present, store as `max_iterations` (default: 5)
+- `--auto` -- if present, set `auto_mode = true`
+
+If `auto_mode` is true and `max_iterations` is not set: `max_iterations = 5`
+
+Log: "cap:iterate | mode: {auto or manual} | max: {max_iterations} | features: {feature_filter or 'all'}"
+
+## Step 1: Load active feature from session
+
+<!-- @gsd-todo(ref:AC-51) /cap:iterate shall read the current feature from SESSION.json and refine the associated prototype. -->
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const s = session.loadSession(process.cwd());
+const featureMap = fm.readFeatureMap(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
+  }))
+}));
+"
+```
+
+**Scope features:**
+- If `feature_filter` is set: filter to matching IDs
+- Else if active feature is set: use only that feature
+- Else: use all features not in `shipped` state
+
+Store as `target_features`.
+
+Initialize: `ITERATION = 0`
+
+## Step 2: Run scan and identify gaps (loop start)
+
+```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 featureMap = fm.readFeatureMap(process.cwd());
+
+// Identify ACs that are still pending
+const gaps = [];
+const targetIds = new Set({JSON.stringify(target_feature_ids)});
+for (const f of featureMap.features) {
+  if (!targetIds.has(f.id)) continue;
+  for (const ac of f.acs) {
+    if (ac.status === 'pending') {
+      gaps.push({ featureId: f.id, featureTitle: f.title, acId: ac.id, acDesc: ac.description });
+    }
+  }
+}
+
+// Count @cap-todo tags
+const todoTags = tags.filter(t => t.type === 'todo');
+
+console.log(JSON.stringify({
+  totalTags: tags.length,
+  todoCount: todoTags.length,
+  gapCount: gaps.length,
+  gaps: gaps
+}));
+"
+```
+
+Store as `scan_result`.
+
+**If `scan_result.gapCount == 0`:**
+Log: "All acceptance criteria resolved after {ITERATION} iteration(s)."
+Proceed to Step 6.
+
+**If `ITERATION == max_iterations`:**
+Log: "Iteration cap ({max_iterations}) reached. {scan_result.gapCount} ACs remain unresolved."
+Proceed to Step 6.
+
+## Step 3: Spawn cap-prototyper in ITERATE mode
+
+Increment `ITERATION`.
+
+Log: "--- Iteration {ITERATION}/{max_iterations} --- ({scan_result.gapCount} ACs remaining)"
+
+Spawn `cap-prototyper` via Task tool:
+
+```
+$ARGUMENTS
+
+**MODE: ITERATE**
+
+**Iteration {ITERATION} of {max_iterations}**
+
+**Gaps to address (unresolved ACs):**
+{For each gap:}
+  {gap.featureId}/{gap.acId}: {gap.acDesc}
+{End for}
+
+**Target features:**
+{For each target_feature:}
+Feature: {feature.id} - {feature.title} [{feature.state}]
+Files: {feature.files.join(', ') or 'none yet'}
+{For each AC:}
+  {ac.id}: {ac.description} [{ac.status}]
+{End for}
+{End for}
+
+**Instructions:**
+1. Read the existing code files listed under each feature
+2. Address the unresolved ACs by implementing or refining code
+3. Add @cap-feature(feature:{ID}) tags to new code
+4. Add @cap-todo(ac:{FEATURE-ID}/AC-N) tags where ACs are implemented
+5. Update existing @cap-todo tags that are now resolved
+6. Do NOT break existing passing tests
+
+**ALWAYS use the Write tool to create files** -- never use heredoc commands.
+```
+
+Wait for cap-prototyper to complete.
+
+## Step 4: Re-scan after iteration
+
+```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());
+fm.enrichFromTags(process.cwd(), tags);
+const featureMap = fm.readFeatureMap(process.cwd());
+const targetIds = new Set({JSON.stringify(target_feature_ids)});
+let remaining = 0;
+for (const f of featureMap.features) {
+  if (!targetIds.has(f.id)) continue;
+  remaining += f.acs.filter(a => a.status === 'pending').length;
+}
+console.log(JSON.stringify({ totalTags: tags.length, acsRemaining: remaining }));
+"
+```
+
+Log: "Iteration {ITERATION} complete. ACs remaining: {acsRemaining}"
+
+## Step 5: Approval gate or auto-continue
+
+**If `auto_mode`:** Loop back to Step 2.
+
+**If NOT `auto_mode`:**
+
+Use AskUserQuestion:
+> "Iteration {ITERATION} complete. {acsRemaining} ACs remaining. Continue to next iteration? [yes / stop / redirect: instructions]"
+
+- If `yes`: Loop back to Step 2
+- If `stop`: Proceed to Step 6
+- If `redirect: <instructions>`: Store instructions as additional context for next iteration, loop back to Step 2
+
+## Step 6: Final report
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:iterate',
+  lastCommandTimestamp: new Date().toISOString(),
+  step: 'iterate-complete'
+});
+"
+```
+
+```
+cap:iterate complete.
+
+Mode: {auto or manual}
+Iterations used: {ITERATION} of {max_iterations}
+ACs remaining: {acsRemaining}
+
+{If acsRemaining > 0:}
+Run /cap:iterate to continue, or /cap:iterate --auto for autonomous mode.
+{Else:}
+All ACs resolved. Run /cap:test to write tests, or /cap:review to verify.
+{End if}
+```
+
+</process>