code-as-plan 2.0.0

package/commands/cap/scan.md

@@ -0,0 +1,249 @@
+---
+name: cap:scan
+description: "Scan codebase for @cap-feature and @cap-todo tags with monorepo support. Traverses all workspace packages, updates Feature Map, reports coverage gaps."
+argument-hint: "[--features NAME] [--json] [--monorepo]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<!-- @gsd-context CAP v2.0 scan command (final pass) -- adds monorepo workspace traversal and cross-package file references to the base scan flow. -->
+<!-- @gsd-decision Monorepo detection is automatic -- checks package.json workspaces field and lerna.json. No --monorepo flag required (AC-80). -->
+<!-- @gsd-decision Cross-package file references use full relative paths from project root (e.g., packages/core/src/auth.ts) to avoid ambiguity (AC-79). -->
+<!-- @gsd-constraint Works seamlessly with normal single-repo projects -- monorepo features are additive, not blocking (AC-80). -->
+
+<!-- @gsd-todo(ref:AC-78) /cap:scan shall traverse all packages in a monorepo -->
+<!-- @gsd-todo(ref:AC-79) Feature Map entries shall support cross-package file references -->
+<!-- @gsd-todo(ref:AC-80) CAP shall work seamlessly with normal single-repo projects with no monorepo-specific configuration required -->
+
+<objective>
+Scans the codebase for @cap-feature and @cap-todo tags. In monorepo projects, automatically detects and traverses all workspace packages. Cross-references against FEATURE-MAP.md, flags orphan tags, and auto-enriches Feature Map with discovered file references.
+
+**Monorepo support:**
+- Automatically detects npm/yarn/pnpm workspaces from package.json `workspaces` field
+- Detects Lerna monorepos from lerna.json
+- Traverses all workspace packages independently
+- File references use full paths from project root (e.g., `packages/core/src/auth.ts`)
+
+**Arguments:**
+- `--features NAME` -- scope scan to specific Feature Map entries (comma-separated)
+- `--json` -- output raw scan results as JSON instead of formatted report
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--features NAME` -- if present, store as `feature_filter`
+- `--json` -- if present, set `json_output = true`
+
+## Step 1: Detect monorepo configuration
+
+<!-- @gsd-decision Monorepo detection reads package.json workspaces and lerna.json. Supports npm, yarn, pnpm workspace patterns. Glob expansion uses Bash for simplicity. -->
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const pkgPath = path.join(process.cwd(), 'package.json');
+const lernaPath = path.join(process.cwd(), 'lerna.json');
+const result = { isMonorepo: false, workspaces: [], packages: [] };
+
+// Check package.json workspaces
+if (fs.existsSync(pkgPath)) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (pkg.workspaces) {
+      result.isMonorepo = true;
+      result.workspaces = Array.isArray(pkg.workspaces)
+        ? pkg.workspaces
+        : (pkg.workspaces.packages || []);
+    }
+  } catch (_e) {}
+}
+
+// Check lerna.json
+if (!result.isMonorepo && fs.existsSync(lernaPath)) {
+  try {
+    const lerna = JSON.parse(fs.readFileSync(lernaPath, 'utf8'));
+    result.isMonorepo = true;
+    result.workspaces = lerna.packages || ['packages/*'];
+  } catch (_e) {}
+}
+
+// Resolve workspace globs to actual package directories
+if (result.isMonorepo) {
+  for (const ws of result.workspaces) {
+    const wsBase = ws.replace('/*', '').replace('/**', '');
+    const wsDir = path.join(process.cwd(), wsBase);
+    if (fs.existsSync(wsDir) && fs.statSync(wsDir).isDirectory()) {
+      const entries = fs.readdirSync(wsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const pkgJsonPath = path.join(wsDir, entry.name, 'package.json');
+          if (fs.existsSync(pkgJsonPath)) {
+            result.packages.push(path.join(wsBase, entry.name));
+          }
+        }
+      }
+    }
+  }
+}
+
+console.log(JSON.stringify(result, null, 2));
+"
+```
+
+Store as `monorepo_info`. Log project type:
+- Monorepo: "Detected monorepo with {N} workspace packages: {list}"
+- Single repo: "Single repository project detected."
+
+## Step 2: Run tag scanner (with monorepo awareness)
+
+If monorepo detected, scan each workspace package independently AND the root:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const monorepoInfo = JSON.parse(process.argv[1]);
+const projectRoot = process.cwd();
+
+if (monorepoInfo.isMonorepo) {
+  // Scan root first
+  const rootTags = scanner.scanDirectory(projectRoot, { projectRoot });
+  const allTags = [...rootTags];
+
+  // Scan each workspace package
+  for (const pkg of monorepoInfo.packages) {
+    const pkgDir = path.join(projectRoot, pkg);
+    if (fs.existsSync(pkgDir)) {
+      const pkgTags = scanner.scanDirectory(pkgDir, { projectRoot });
+      allTags.push(...pkgTags);
+    }
+  }
+
+  // Deduplicate by file+line
+  const seen = new Set();
+  const deduped = allTags.filter(t => {
+    const key = t.file + ':' + t.line;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  console.log(JSON.stringify(deduped, null, 2));
+} else {
+  const tags = scanner.scanDirectory(projectRoot);
+  console.log(JSON.stringify(tags, null, 2));
+}
+" '<MONOREPO_INFO_JSON>'
+```
+
+Store as `all_tags`.
+
+## Step 3: Group tags by feature and by package
+
+```bash
+node -e "
+const tags = JSON.parse(process.argv[1]);
+const groups = {};
+const packageGroups = {};
+
+for (const tag of tags) {
+  // Group by feature
+  const fid = (tag.metadata && tag.metadata.feature) || '(unassigned)';
+  if (!groups[fid]) groups[fid] = [];
+  groups[fid].push(tag);
+
+  // Group by package (first path segment if monorepo)
+  const parts = tag.file.split('/');
+  const pkg = parts.length > 2 && parts[0] === 'packages' ? parts[0] + '/' + parts[1] : '(root)';
+  if (!packageGroups[pkg]) packageGroups[pkg] = [];
+  packageGroups[pkg].push(tag);
+}
+
+console.log(JSON.stringify({ byFeature: groups, byPackage: packageGroups }, null, 2));
+" '<ALL_TAGS_JSON>'
+```
+
+## Step 4: Cross-reference and detect orphans
+
+Same as base scan -- run orphan detection against FEATURE-MAP.md.
+
+## Step 5: Auto-enrich Feature Map with cross-package file references
+
+<!-- @gsd-decision Cross-package file refs are stored as full relative paths from project root. This means packages/core/src/auth.ts, not just src/auth.ts. Feature Map readers can identify the package from the path prefix. -->
+
+```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({
+  features_enriched: updated.features.filter(f => f.files.length > 0).length,
+  total_file_refs: updated.features.reduce((sum, f) => sum + f.files.length, 0),
+  cross_package_refs: updated.features.reduce((sum, f) =>
+    sum + f.files.filter(fp => fp.startsWith('packages/')).length, 0)
+}));
+"
+```
+
+## Step 6: Output results
+
+**Formatted report (default):**
+
+```
+cap:scan complete.
+
+{If monorepo:}
+Monorepo: {workspace_count} packages scanned
+  {For each package:}
+  - {package_name}: {tag_count} tags
+
+Tags found: {total_tags}
+  @cap-feature: {count}
+  @cap-todo:    {count}
+  @cap-risk:    {count}
+  @cap-decision:{count}
+
+Coverage: {files_with_tags} of {total_source_files} source files ({percentage}%)
+
+Feature Map enrichment:
+  Features with file refs: {N}
+  Total file references:   {N}
+  {If monorepo:} Cross-package refs: {N}
+
+{Orphan section same as base scan}
+
+Feature breakdown:
+{For each feature group:}
+  {feature_id}: {count} tags ({type breakdown})
+```
+
+## Step 7: Update session
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:scan',
+  lastCommandTimestamp: new Date().toISOString()
+});
+"
+```
+
+</process>

package/commands/cap/start.md

@@ -0,0 +1,234 @@
+---
+name: cap:start
+description: Initialize a CAP session -- restore previous session state, detect project context, and get working immediately.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+---
+
+<!-- @gsd-context CAP v2.0 start command -- session initialization at the start of a new conversation. Restores .cap/SESSION.json state, detects workspace type, and presents current Feature Map status. -->
+<!-- @gsd-decision Start reads SESSION.json to restore context from previous conversation. This is critical for cross-conversation continuity since Claude Code conversations are stateless. -->
+<!-- @gsd-decision Start auto-runs /cap:init if .cap/ directory does not exist -- first-time users get bootstrapped automatically. -->
+
+<objective>
+Initialize a CAP session at the start of a new conversation:
+1. Check if .cap/ exists -- if not, auto-initialize
+2. Auto-detect project info from package.json and directory structure
+3. Load .cap/SESSION.json for previous session state
+4. List features from FEATURE-MAP.md for user selection
+5. Present current status and suggest next action
+
+No arguments needed -- always runs the same flow.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@.cap/SESSION.json
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 1: Check for .cap/ directory and auto-initialize
+
+<!-- @gsd-todo(ref:AC-34) /cap:start shall initialize a session by setting the active feature in SESSION.json and restoring context from the Feature Map. -->
+
+```bash
+test -d .cap && echo "initialized" || echo "not_initialized"
+```
+
+**If not initialized:**
+
+Log: "First run detected. Initializing .cap/ directory..."
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.initCapDirectory(process.cwd());
+console.log('initialized');
+"
+```
+
+Check if FEATURE-MAP.md exists:
+
+```bash
+test -f FEATURE-MAP.md && echo "exists" || echo "missing"
+```
+
+If FEATURE-MAP.md does not exist, generate the template:
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const template = fm.generateTemplate();
+fs.writeFileSync(path.join(process.cwd(), 'FEATURE-MAP.md'), template, 'utf8');
+console.log('FEATURE-MAP.md created');
+"
+```
+
+Log: "Created .cap/ directory and FEATURE-MAP.md"
+
+## Step 2: Auto-detect project context
+
+<!-- @gsd-todo(ref:AC-35) /cap:start shall auto-scope to the project by deriving project information from actual code (package.json, directory structure) rather than asking questions. -->
+
+Detect project info from the filesystem -- no questions asked:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const path = require('node:path');
+const cwd = process.cwd();
+const info = { name: path.basename(cwd), language: 'unknown', framework: 'unknown', testFramework: 'unknown' };
+
+// Read package.json if available
+const pkgPath = path.join(cwd, 'package.json');
+if (fs.existsSync(pkgPath)) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    info.name = pkg.name || info.name;
+    info.language = 'javascript';
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (allDeps.typescript) info.language = 'typescript';
+    if (allDeps.react) info.framework = 'react';
+    if (allDeps.next) info.framework = 'next.js';
+    if (allDeps.express) info.framework = 'express';
+    if (allDeps.vitest) info.testFramework = 'vitest';
+    else if (allDeps.jest) info.testFramework = 'jest';
+    else if (pkg.scripts && pkg.scripts.test && pkg.scripts.test.includes('node --test')) info.testFramework = 'node:test';
+  } catch (e) {}
+}
+
+// Check for Python
+if (fs.existsSync(path.join(cwd, 'requirements.txt')) || fs.existsSync(path.join(cwd, 'pyproject.toml'))) {
+  info.language = 'python';
+  if (fs.existsSync(path.join(cwd, 'pyproject.toml'))) {
+    const content = fs.readFileSync(path.join(cwd, 'pyproject.toml'), 'utf8');
+    if (content.includes('django')) info.framework = 'django';
+    if (content.includes('fastapi')) info.framework = 'fastapi';
+    if (content.includes('pytest')) info.testFramework = 'pytest';
+  }
+}
+
+// Check for Go
+if (fs.existsSync(path.join(cwd, 'go.mod'))) {
+  info.language = 'go';
+  info.testFramework = 'go test';
+}
+
+// Check for Rust
+if (fs.existsSync(path.join(cwd, 'Cargo.toml'))) {
+  info.language = 'rust';
+  info.testFramework = 'cargo test';
+}
+
+console.log(JSON.stringify(info));
+"
+```
+
+Store as `project_info`.
+
+## Step 3: Load session state
+
+```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`.
+
+## Step 4: Load Feature Map and present features
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const featureMap = fm.readFeatureMap(process.cwd());
+const status = fm.getStatus(featureMap);
+console.log(JSON.stringify({
+  features: featureMap.features.map(f => ({ id: f.id, title: f.title, state: f.state, acCount: f.acs.length })),
+  ...status
+}));
+"
+```
+
+Store as `fm_data`.
+
+## Step 5: Present session context and select active feature
+
+Display session restoration:
+
+```
+=== CAP Session Start ===
+
+Project: {project_info.name} ({project_info.language} / {project_info.framework})
+Test framework: {project_info.testFramework}
+
+{If session.activeFeature:}
+Previous session:
+  Active feature: {session.activeFeature}
+  Last step:      {session.step}
+  Last command:   {session.lastCommand}
+
+{End if}
+
+Features ({fm_data.totalFeatures} total):
+  planned:    {count}
+  prototyped: {count}
+  tested:     {count}
+  shipped:    {count}
+```
+
+**If features exist, list them and ask user to select:**
+
+```
+Available features:
+{For each feature:}
+  {feature.id}: {feature.title} [{feature.state}] ({feature.acCount} ACs)
+```
+
+If `session.activeFeature` is set, offer to continue:
+
+Use AskUserQuestion:
+> "Continue working on {session.activeFeature} ({title})? Or enter a feature ID to switch (e.g., F-001). Type 'none' to work without a focused feature."
+
+If no active feature:
+
+Use AskUserQuestion:
+> "Select a feature to focus on (enter feature ID, e.g., F-001), or type 'none' to skip."
+
+**Process user response:**
+- If a valid feature ID: set as active feature
+- If `none` or `skip`: proceed without active feature
+- If continuing previous: keep existing active feature
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.startSession(process.cwd(), '{selected_feature_id}', 'start');
+console.log('Session updated');
+"
+```
+
+## Step 6: Suggest next action
+
+Based on current state, suggest:
+
+- If no features: "No features found. Run /cap:brainstorm to discover features."
+- If active feature is `planned`: "Run /cap:prototype to build initial code for {feature}."
+- If active feature is `prototyped`: "Run /cap:iterate to refine, or /cap:test to write tests."
+- If active feature is `tested`: "Run /cap:review to verify {feature}."
+- If active feature is `shipped`: "All done with {feature}. Select a different feature or run /cap:brainstorm."
+
+```
+Session started. Suggested next: {action}
+```
+
+</process>

package/commands/cap/status.md

@@ -0,0 +1,189 @@
+---
+name: cap:status
+description: Show project status derived from Feature Map -- feature completion, test coverage, open risks, and next actions.
+argument-hint: "[--features NAME] [--verbose]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+<!-- @gsd-context CAP v2.0 status command -- reads FEATURE-MAP.md and .cap/SESSION.json to present a compact project status dashboard. No agent spawning, no file writes. -->
+<!-- @gsd-decision Status is read-only -- it presents information but never modifies Feature Map or session state. Safe to run at any time. -->
+<!-- @gsd-decision Status derives from Feature Map, session state, AND live tag scan -- gives a complete picture without requiring a separate /cap:scan first. -->
+
+<objective>
+Presents a compact project status dashboard derived from FEATURE-MAP.md, SESSION.json, and a live tag count:
+- Current session state (active feature, step, duration)
+- Feature completion by state (planned, prototyped, tested, shipped)
+- Tag coverage statistics (files with tags vs total source files)
+
+**Arguments:**
+- `--features NAME` -- show status for specific features only
+- `--verbose` -- include per-AC breakdown
+</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)
+- `--verbose` -- if present, set `verbose = true`
+
+## Step 1: Read session state
+
+<!-- @gsd-todo(ref:AC-31) /cap:status shall display the current session state from SESSION.json (active feature, current step, session duration). -->
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+const duration = s.startedAt ? Math.round((Date.now() - new Date(s.startedAt).getTime()) / 60000) : null;
+console.log(JSON.stringify({
+  activeFeature: s.activeFeature,
+  step: s.step,
+  startedAt: s.startedAt,
+  durationMinutes: duration,
+  lastCommand: s.lastCommand,
+  lastCommandTimestamp: s.lastCommandTimestamp,
+  activeDebugSession: s.activeDebugSession
+}));
+"
+```
+
+Store as `session_state`.
+
+## Step 2: Read Feature Map status
+
+<!-- @gsd-todo(ref:AC-32) /cap:status shall display a summary of FEATURE-MAP.md (count of features per state: planned, prototyped, tested, shipped). -->
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const featureMap = fm.readFeatureMap(process.cwd());
+const status = fm.getStatus(featureMap);
+const byState = { planned: 0, prototyped: 0, tested: 0, shipped: 0 };
+for (const f of featureMap.features) {
+  byState[f.state] = (byState[f.state] || 0) + 1;
+}
+console.log(JSON.stringify({
+  ...status,
+  byState,
+  features: featureMap.features.map(f => ({
+    id: f.id,
+    title: f.title,
+    state: f.state,
+    acCount: f.acs.length,
+    acsImplemented: f.acs.filter(a => a.status === 'implemented').length,
+    acsTested: f.acs.filter(a => a.status === 'tested').length,
+    acsReviewed: f.acs.filter(a => a.status === 'reviewed').length,
+    fileCount: f.files.length,
+    dependencies: f.dependencies
+  })),
+  lastScan: featureMap.lastScan
+}));
+"
+```
+
+Store as `fm_status`. If `feature_filter` is set, filter `fm_status.features` to matching IDs.
+
+## Step 3: Compute tag coverage
+
+<!-- @gsd-todo(ref:AC-33) /cap:status shall display tag coverage statistics (files with tags vs. total source files). -->
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const tags = scanner.scanDirectory(process.cwd());
+const filesWithTags = new Set(tags.map(t => t.file));
+let totalFiles = 0;
+function walk(dir, exclude) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory() && !exclude.includes(e.name)) walk(path.join(dir, e.name), exclude);
+    else if (e.isFile() && scanner.SUPPORTED_EXTENSIONS.includes(path.extname(e.name))) totalFiles++;
+  }
+}
+walk(process.cwd(), scanner.DEFAULT_EXCLUDE);
+const byType = {};
+for (const t of tags) { byType[t.type] = (byType[t.type] || 0) + 1; }
+console.log(JSON.stringify({ filesWithTags: filesWithTags.size, totalFiles, totalTags: tags.length, byType }));
+"
+```
+
+Store as `tag_stats`.
+
+## Step 4: Present formatted dashboard
+
+Display:
+
+```
+=== CAP Status ===
+
+Session:
+  Active feature: {session_state.activeFeature or "none"}
+  Current step:   {session_state.step or "none"}
+  Session duration: {session_state.durationMinutes} minutes {or "no active session"}
+  Last command:   {session_state.lastCommand} ({session_state.lastCommandTimestamp})
+
+Features ({fm_status.totalFeatures} total):
+  planned:    {byState.planned}
+  prototyped: {byState.prototyped}
+  tested:     {byState.tested}
+  shipped:    {byState.shipped}
+
+Acceptance Criteria:
+  Total:       {fm_status.totalACs}
+  Implemented: {fm_status.implementedACs}
+  Tested:      {fm_status.testedACs}
+  Reviewed:    {fm_status.reviewedACs}
+
+Tag Coverage:
+  Source files with @cap-* tags: {tag_stats.filesWithTags} of {tag_stats.totalFiles} ({percentage}%)
+  Total tags: {tag_stats.totalTags}
+    @cap-feature:  {byType.feature or 0}
+    @cap-todo:     {byType.todo or 0}
+    @cap-risk:     {byType.risk or 0}
+    @cap-decision: {byType.decision or 0}
+
+Last scan: {fm_status.lastScan or "never"}
+```
+
+**If `verbose` is true:**
+
+For each feature in scope, display:
+
+```
+  {feature.id}: {feature.title} [{feature.state}]
+    ACs: {feature.acCount} total, {feature.acsImplemented} implemented, {feature.acsTested} tested
+    Files: {feature.fileCount}
+    Dependencies: {feature.dependencies.join(', ') or 'none'}
+```
+
+## Step 5: Suggest next action
+
+Based on current state, suggest the most useful next command:
+
+- If no features exist: "Run /cap:brainstorm to discover features."
+- If all features are `planned`: "Run /cap:prototype to build initial scaffolds."
+- If active feature is `prototyped`: "Run /cap:test to write tests for {activeFeature}."
+- If active feature is `tested`: "Run /cap:review to verify {activeFeature}."
+- If tag coverage < 50%: "Run /cap:scan or /cap:annotate to improve tag coverage."
+- Otherwise: "Run /cap:iterate to continue development."
+
+```
+Suggested next: {action}
+```
+
+</process>