cap-pro 1.0.0

package/commands/cap/init.md

@@ -0,0 +1,354 @@
+---
+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
+---
+
+<!-- @cap-context CAP v2.0 init command (final pass) -- adds mandatory Context7 integration and brownfield detection on top of the base init flow. -->
+<!-- @cap-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. -->
+<!-- @cap-decision Brownfield analysis is ephemeral -- results are used as context for /cap:annotate suggestion, NOT persisted as a separate document (AC-87). -->
+<!-- @cap-decision No /cap:map command exists. Codebase analysis is part of /cap:init only (AC-90). -->
+<!-- @cap-constraint No prompts, wizards, or configuration forms. Init completes in a single invocation (AC-4, AC-5). -->
+
+<!-- @cap-todo(ref:AC-81) Detect all dependencies from package.json / requirements.txt / Cargo.toml / go.mod and fetch docs via Context7 -->
+<!-- @cap-todo(ref:AC-82) Store fetched stack docs in .cap/stack-docs/{library-name}.md compressed to API surface, config, breaking changes -->
+<!-- @cap-todo(ref:AC-83) Agents receive .cap/stack-docs/ as context input on every invocation -->
+<!-- @cap-todo(ref:AC-84) Stack-docs carry freshness marker (fetch date). Docs older than 7 days auto-refreshed. Manual refresh: see docs/setup-and-upgrade.md (`npx ctx7@latest docs ...`) -->
+<!-- @cap-todo(ref:AC-85) Context7 fetching is MANDATORY at init. If unreachable, warning emitted and init continues with explicit marker -->
+<!-- @cap-todo(ref:AC-86) Brownfield init performs one-time codebase analysis: architecture detection, convention detection, test setup detection -->
+<!-- @cap-todo(ref:AC-87) Brownfield analysis result NOT persisted as separate document -- used as init context for /cap:annotate suggestion -->
+<!-- @cap-todo(ref:AC-88) After brownfield init, suggest /cap:annotate to retroactively annotate existing code -->
+<!-- @cap-todo(ref:AC-90) No /cap:map command. Codebase analysis is part of /cap:init -->
+<!-- @cap-todo(ref:AC-91) To refresh codebase information: /cap:annotate; for library docs see docs/setup-and-upgrade.md -->
+<!-- @cap-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 5b: Detect monorepo and create per-app FEATURE-MAP.md files
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const projectRoot = process.cwd();
+const mono = session.listApps(projectRoot);
+
+if (!mono.isMonorepo) {
+  console.log(JSON.stringify({ isMonorepo: false, created: 0, apps: [] }));
+} else {
+  let created = 0;
+  const createdApps = [];
+  for (const app of mono.apps) {
+    // Only create FEATURE-MAP.md for apps that have source files
+    const appDir = path.join(projectRoot, app);
+    if (!fs.existsSync(appDir)) continue;
+    const entries = fs.readdirSync(appDir, { withFileTypes: true });
+    const hasSrc = entries.some(e =>
+      (e.isDirectory() && (e.name === 'src' || e.name === 'lib' || e.name === 'app')) ||
+      (e.isFile() && /\.(js|ts|py|go|rs|java|rb)$/.test(e.name))
+    );
+    if (hasSrc) {
+      const wasCreated = fm.initAppFeatureMap(projectRoot, app);
+      if (wasCreated) {
+        created++;
+        createdApps.push(app);
+      }
+    }
+  }
+  console.log(JSON.stringify({ isMonorepo: true, created, apps: createdApps, totalApps: mono.apps.length }));
+}
+"
+```
+
+Store as `monorepo_init`.
+
+**If monorepo detected:**
+Log: "Monorepo detected with {totalApps} workspace packages."
+If `created > 0`: Log: "Created FEATURE-MAP.md for {created} apps: {apps list}"
+If `created === 0`: Log: "All apps already have FEATURE-MAP.md (or no source files detected)."
+
+## Step 6: Mandatory Context7 dependency fetch
+
+<!-- @cap-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. Re-fetch via `npx ctx7@latest` when network is available (see docs/setup-and-upgrade.md).
+   ```
+
+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
+
+<!-- @cap-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 7f: Build memory graph
+
+**MANDATORY** — always run this step. The script auto-detects whether data exists.
+
+```bash
+node -e "const fs=require('fs'),p=require('path'),c=process.cwd(),md=p.join(c,'.cap','memory');if(fs.existsSync(p.join(c,'FEATURE-MAP.md'))||fs.existsSync(p.join(md,'decisions.md'))){const g=require('./cap/bin/lib/cap-memory-graph.cjs'),gr=g.buildFromMemory(c);g.saveGraph(c,gr);console.log(JSON.stringify({built:true,nodes:Object.keys(gr.nodes).length,edges:gr.edges.length}))}else{console.log(JSON.stringify({built:false}))}"
+```
+
+Log the result. If `built: true`: "Memory graph built: {nodes} nodes, {edges} edges"
+
+## Step 7g: Migrate brainstorm sessions to conversation threads
+
+**MANDATORY** — always run this step. The script auto-detects whether migration is needed and handles re-migration of metadata-only threads.
+
+```bash
+node -e "const m=require('./cap/bin/lib/cap-thread-migrator.cjs');console.log(JSON.stringify(m.migrateBrainstormSessions(process.cwd())))"
+```
+
+Log the result. If `migrated > 0`: "Migrated {migrated} brainstorm session(s) to conversation threads."
+
+## 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}
+{If graph_result.built:}Memory graph: {graph_result.nodes} nodes, {graph_result.edges} edges{End if}
+{If thread_migration.migrated > 0:}Threads: {thread_migration.migrated} brainstorm session(s) migrated{End if}
+
+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
+
+To refresh stack documentation later, run `npx ctx7@latest` directly (see docs/setup-and-upgrade.md).
+```
+
+## Step 8b: Lightweight doctor check
+
+Run a quick check for optional tool availability (especially ctx7 since init depends on it):
+
+```bash
+node -e "
+const doctor = require('./cap/bin/lib/cap-doctor.cjs');
+const report = doctor.runDoctor();
+const missing = report.tools.filter(t => !t.ok && !t.required);
+if (missing.length > 0) {
+  console.log('Optional tools not found:');
+  for (const t of missing) {
+    console.log('  - ' + t.name + ': ' + t.purpose);
+    console.log('    Install: ' + t.installHint);
+  }
+  console.log('\nFor a full environment check, see docs/setup-and-upgrade.md.');
+} else {
+  console.log('All optional tools available.');
+}
+"
+```
+
+If missing tools are reported, display the output as an informational note (not a blocking error).
+
+## 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,249 @@
+---
+name: cap:iterate
+description: Refine an already-prototyped feature to close remaining `@cap-todo` tags or address feedback. TRIGGER when after a feature has been prototyped there are still pending @cap-todo tags in code, when the user says "iterate on X / this isn't quite right / refine F-XXX / let's keep going", or after a `/cap:scan` reveals open gaps for the active feature. Auto-loops scan→build→rescan until ACs satisfied (--max N for safety, --auto to skip per-iteration approval). DO NOT trigger when the feature has no prototype yet (use cap:prototype), when only minor edits are needed (just edit directly), or when the user is in a **Frontend Sprint** loop on UI files (visual tweaks on .tsx/.jsx/.css — handle directly, run cap:annotate + cap:test only at sprint end).
+argument-hint: "[--features NAME] [--max N] [--auto]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @cap-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. -->
+<!-- @cap-decision Iteration loop is scan-driven: /cap:scan output determines what to build next. No upfront planning step. -->
+<!-- @cap-decision Human approval gate between iterations by default. --auto flag enables autonomous loop with --max N safety limit. -->
+<!-- @cap-constraint --auto mode requires --max N to prevent runaway loops. Default max is 5 if --auto specified without --max. -->
+
+<objective>
+<!-- @cap-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
+
+<!-- @cap-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
+
+<!-- @cap-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());
+// @cap-todo(ac:F-081/AC-4 iter:2) Migrated to {safe: true} opt-in to preserve CLI on duplicate-ID FEATURE-MAP.
+// @cap-decision(F-081/iter2) Warn on parseError; continue with partial map for read-only display.
+const featureMap = fm.readFeatureMap(process.cwd(), undefined, { safe: true });
+if (featureMap && featureMap.parseError) {
+  console.warn('cap: iterate — duplicate feature ID detected, target list uses partial map: ' + String(featureMap.parseError.message).trim());
+}
+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());
+// @cap-todo(ac:F-081/AC-4 iter:2) Migrated to {safe: true} opt-in to preserve CLI on duplicate-ID FEATURE-MAP.
+// @cap-decision(F-081/iter2) Warn on parseError; continue with partial map for read-only display.
+const featureMap = fm.readFeatureMap(process.cwd(), undefined, { safe: true });
+if (featureMap && featureMap.parseError) {
+  console.warn('cap: iterate scan — duplicate feature ID detected, gap report uses partial map: ' + String(featureMap.parseError.message).trim());
+}
+
+// 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);
+// @cap-todo(ac:F-081/AC-4 iter:2) Migrated to {safe: true} opt-in to preserve CLI on duplicate-ID FEATURE-MAP.
+// @cap-decision(F-081/iter2) Warn on parseError; continue with partial map for read-only display.
+const featureMap = fm.readFeatureMap(process.cwd(), undefined, { safe: true });
+if (featureMap && featureMap.parseError) {
+  console.warn('cap: iterate re-scan — duplicate feature ID detected, remaining count uses partial map: ' + String(featureMap.parseError.message).trim());
+}
+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>