cc-dev-template 0.1.66 → 0.1.73

package/bin/install.js

@@ -253,6 +253,7 @@ const settingsFile = path.join(CLAUDE_DIR, 'settings.json');
 if (fs.existsSync(mergeSettingsPath)) {
   const configs = [
     { file: 'read-guard-hook.json', name: 'Context guard for large reads' },
+    { file: 'task-output-guard-hook.json', name: 'TaskOutput context guard' },
     { file: 'statusline-config.json', name: 'Custom status line' },
     // Spinner verbs - choose one (Helldivers or Factorio)
     { file: 'spinner-verbs-helldivers.json', name: 'Helldivers spinner verbs' }
@@ -393,6 +394,13 @@ if (fs.existsSync(settingsFile)) {
       settingsModified = true;
     }
 
+    // Enable agent teams (required for spec-interview team workflow)
+    if (settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS !== '1') {
+      settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+      console.log('✓ Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1');
+      settingsModified = true;
+    }
+
     if (settingsModified) {
       fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.66",
+  "version": "0.1.73",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/agents/spec-implementer.md

@@ -2,6 +2,7 @@
 name: spec-implementer
 description: Implements a single criterion from a spec task file. Only use when explicitly assigned a task file path from the execute-spec workflow.
 tools: Read, Grep, Glob, Edit, Write, Bash, LSP
+memory: project
 ---
 
 You implement one task from a spec breakdown.

package/src/agents/spec-validator.md

@@ -2,6 +2,7 @@
 name: spec-validator
 description: Validates a completed task through code review and E2E testing. Only use when explicitly assigned a task file path from the execute-spec workflow.
 tools: Read, Grep, Glob, Bash
+memory: project
 ---
 
 You are a senior QA engineer validating completed work.

package/src/scripts/statusline.js

@@ -3,18 +3,31 @@
 /**
  * Custom Status Line for Claude Code
  *
- * Displays project status in 3 lines:
+ * Displays project status in a bordered box:
  * - Line 0: Directory name
  * - Line 1: Git branch + status
  * - Line 2: Context window usage bar with percentage and tokens
+ * - Line 3: Plan usage limits (5-hour session + 7-day weekly)
  *
  * Input: JSON on stdin with context_window data
  * Output: Formatted status to stdout
  */
 
-const { readFileSync, readdirSync, statSync } = require('fs');
+const { readFileSync, writeFileSync, readdirSync, statSync } = require('fs');
 const { join, basename } = require('path');
-const { execSync } = require('child_process');
+const { execSync, spawnSync, spawn } = require('child_process');
+const { homedir } = require('os');
+
+// Usage API cache
+const USAGE_CACHE_PATH = join(homedir(), '.claude', '.usage-cache.json');
+const USAGE_CACHE_TTL = 45000; // 45 seconds
+const USAGE_HISTORY_MAX = 20; // ~15 min of readings at 45s intervals
+
+// Background refresh mode: fetch usage data and write cache, then exit
+if (process.argv.includes('--refresh')) {
+  refreshUsageCache();
+  process.exit(0);
+}
 
 /**
  * Format number as K (e.g., 84000 -> "084K")
@@ -60,6 +73,50 @@ function getContextGreyscale(percentage) {
   return '\x1b[38;5;240m'; // Dark grey - safe
 }
 
+/**
+ * Compute burn rate (percent per minute) from usage history
+ * Returns null if insufficient data
+ */
+function getUsageBurnRate(history, key) {
+  if (!history || history.length < 2) return null;
+
+  const oldest = history[0];
+  const newest = history[history.length - 1];
+  const minutesElapsed = (newest.t - oldest.t) / 60000;
+
+  // Need at least 2 minutes of data for a stable reading
+  if (minutesElapsed < 2) return null;
+
+  const deltaUtilization = newest[key] - oldest[key];
+  return deltaUtilization / minutesElapsed;
+}
+
+/**
+ * Get color for usage bar based on current level and burn rate trend
+ * Returns red/yellow for danger, or greyscale for safe
+ */
+function getUsageColor(utilization, burnRate, windowType) {
+  const RED = '\x1b[38;5;196m';
+  const YELLOW = '\x1b[38;5;220m';
+
+  // Thresholds differ by window type
+  const redMinutes = windowType === '5h' ? 30 : 240;      // 30min / 4hr
+  const yellowMinutes = windowType === '5h' ? 90 : 720;    // 90min / 12hr
+
+  // Hard thresholds on current utilization
+  if (utilization >= 90) return RED;
+  if (utilization >= 75) return YELLOW;
+
+  // Trend-based: project time to hit 100%
+  if (burnRate && burnRate > 0) {
+    const minutesToLimit = (100 - utilization) / burnRate;
+    if (minutesToLimit <= redMinutes) return RED;
+    if (minutesToLimit <= yellowMinutes) return YELLOW;
+  }
+
+  return getContextGreyscale(utilization);
+}
+
 /**
  * Count files in a directory recursively
  */
@@ -226,6 +283,108 @@ function getModulesWithChanges(projectDir) {
   return modules;
 }
 
+/**
+ * Get OAuth access token from system credentials
+ */
+function getOAuthToken() {
+  if (process.platform === 'darwin') {
+    const credJson = execSync(
+      'security find-generic-password -s "Claude Code-credentials" -w',
+      { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'ignore'] }
+    ).trim();
+    const creds = JSON.parse(credJson);
+    return creds.claudeAiOauth?.accessToken || null;
+  }
+  // Linux fallback
+  const credPath = join(homedir(), '.claude', '.credentials.json');
+  try {
+    const creds = JSON.parse(readFileSync(credPath, 'utf-8'));
+    return creds.claudeAiOauth?.accessToken || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch usage data from API and write to cache (runs in background)
+ */
+function refreshUsageCache() {
+  try {
+    const token = getOAuthToken();
+    if (!token) return;
+
+    const result = spawnSync('curl', [
+      '-s', '--max-time', '3',
+      'https://api.anthropic.com/api/oauth/usage',
+      '-H', `Authorization: Bearer ${token}`,
+      '-H', 'anthropic-beta: oauth-2025-04-20',
+      '-H', 'Content-Type: application/json',
+    ], { encoding: 'utf-8', timeout: 5000 });
+
+    if (result.status === 0 && result.stdout) {
+      const data = JSON.parse(result.stdout.trim());
+      if (data.five_hour && data.seven_day) {
+        // Load existing history and append new reading
+        let history = [];
+        try {
+          const existing = JSON.parse(readFileSync(USAGE_CACHE_PATH, 'utf-8'));
+          if (Array.isArray(existing.history)) history = existing.history;
+        } catch {}
+
+        const now = Date.now();
+        history.push({
+          t: now,
+          five_hour: data.five_hour.utilization,
+          seven_day: data.seven_day.utilization,
+        });
+
+        // Keep only the last N readings
+        if (history.length > USAGE_HISTORY_MAX) {
+          history = history.slice(-USAGE_HISTORY_MAX);
+        }
+
+        writeFileSync(USAGE_CACHE_PATH, JSON.stringify({
+          timestamp: now,
+          data,
+          history,
+        }));
+      }
+    }
+  } catch {
+    // Silently fail - stale cache will be used on next render
+  }
+}
+
+/**
+ * Read cached usage data, trigger background refresh if stale
+ */
+function getUsageData() {
+  let cacheData = null;
+  let cacheHistory = null;
+  let cacheAge = Infinity;
+
+  try {
+    const raw = readFileSync(USAGE_CACHE_PATH, 'utf-8');
+    const cache = JSON.parse(raw);
+    cacheData = cache.data;
+    cacheHistory = cache.history || null;
+    cacheAge = Date.now() - cache.timestamp;
+  } catch {}
+
+  // Trigger background refresh if cache is stale
+  if (cacheAge > USAGE_CACHE_TTL) {
+    try {
+      const child = spawn(process.execPath, [__filename, '--refresh'], {
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+    } catch {}
+  }
+
+  return { data: cacheData, history: cacheHistory };
+}
+
 /**
  * Main function
  */
@@ -380,11 +539,32 @@ function main() {
     // Context bar line
     const ctxLine = makeBoxLine(ctxDisplay);
 
+    // Usage limits line (5-hour session + 7-day weekly)
+    const usageLines = [];
+    const { data: usageApiData, history: usageHistory } = getUsageData();
+    if (usageApiData && usageApiData.five_hour && usageApiData.seven_day) {
+      const pct5h = Math.round(usageApiData.five_hour.utilization);
+      const pct7d = Math.round(usageApiData.seven_day.utilization);
+      const bar5h = generateBar(pct5h, 12);
+      const bar7d = generateBar(pct7d, 12);
+
+      // Compute burn rates from history for trend-based coloring
+      const rate5h = getUsageBurnRate(usageHistory, 'five_hour');
+      const rate7d = getUsageBurnRate(usageHistory, 'seven_day');
+      const color5h = getUsageColor(pct5h, rate5h, '5h');
+      const color7d = getUsageColor(pct7d, rate7d, '7d');
+
+      const str5h = pct5h.toString().padStart(3, ' ');
+      const str7d = pct7d.toString().padStart(3, ' ');
+      const usageDisplay = `5HR: ${color5h}[${bar5h}]${str5h}%${DIM_GREY}  7D: ${color7d}[${bar7d}]${str7d}%${DIM_GREY}`;
+      usageLines.push(makeBoxLine(usageDisplay));
+    }
+
     // Bottom border (add 2 to match content line width)
     const bottomBorder = `${DIM_GREY}╚${'═'.repeat(width + 2)}╝${RESET}`;
 
     // Combine all lines
-    const allLines = [topBorder, line0, ...branchLines, ctxLine, bottomBorder];
+    const allLines = [topBorder, line0, ...branchLines, ctxLine, ...usageLines, bottomBorder];
     console.log(allLines.join('\n'));
   } catch (error) {
     // Log error for debugging (goes to stderr, not visible in status line)

package/src/scripts/task-output-guard-hook.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "TaskOutput",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/scripts/task-output-guard.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/scripts/task-output-guard.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * task-output-guard.js - Intercept TaskOutput to prevent context bloat
+ *
+ * TaskOutput returns the full JSONL transcript of a background agent,
+ * including every tool call, tool result, and file contents the agent read.
+ * Each poll dumps the entire transcript (not a delta) into the orchestrator's
+ * context, causing severe bloat with background agents.
+ *
+ * This hook intercepts TaskOutput calls, reads the output file directly,
+ * extracts only the last few assistant messages, and returns those as the
+ * deny reason. The orchestrator gets useful status without the full transcript.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_ASSISTANT_MESSAGES = 3;
+const MAX_CHARS_PER_MESSAGE = 500;
+
+async function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch { resolve(null); }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}
+
+/**
+ * Find the output file for a given task ID.
+ * Output files live at /private/tmp/claude-{uid}/{cwd-dashed}/tasks/{taskId}.output
+ */
+function findOutputFile(taskId, cwd) {
+  try {
+    const uid = process.getuid();
+    const cwdDashed = cwd.replace(/\//g, '-');
+    const outputPath = path.join('/private/tmp', `claude-${uid}`, cwdDashed, 'tasks', `${taskId}.output`);
+    if (fs.existsSync(outputPath)) return outputPath;
+
+    // Fallback: search common locations
+    const tmpBase = path.join('/private/tmp', `claude-${uid}`);
+    if (fs.existsSync(tmpBase)) {
+      const dirs = fs.readdirSync(tmpBase);
+      for (const dir of dirs) {
+        const candidate = path.join(tmpBase, dir, 'tasks', `${taskId}.output`);
+        if (fs.existsSync(candidate)) return candidate;
+      }
+    }
+  } catch {
+    // Ignore errors in file search
+  }
+  return null;
+}
+
+/**
+ * Parse JSONL output file and extract the last N assistant text messages.
+ */
+function extractAssistantMessages(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.trim().split('\n');
+
+    const assistantMessages = [];
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type !== 'assistant' || !entry.message) continue;
+        if (entry.message.role !== 'assistant' || !entry.message.content) continue;
+
+        // Extract text blocks only (skip tool_use blocks)
+        const textParts = [];
+        const contentArr = Array.isArray(entry.message.content)
+          ? entry.message.content
+          : [entry.message.content];
+
+        for (const block of contentArr) {
+          if (typeof block === 'string' && block.trim()) {
+            textParts.push(block.trim());
+          } else if (block.type === 'text' && block.text && block.text.trim()) {
+            textParts.push(block.text.trim());
+          }
+        }
+
+        if (textParts.length > 0) {
+          assistantMessages.push(textParts.join('\n'));
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return assistantMessages.slice(-MAX_ASSISTANT_MESSAGES);
+  } catch {
+    return [];
+  }
+}
+
+async function main() {
+  const input = await readStdin();
+  if (!input) process.exit(0);
+
+  const taskId = input.tool_input?.task_id;
+  const cwd = input.cwd;
+
+  if (!taskId || !cwd) process.exit(0);
+
+  const outputFile = findOutputFile(taskId, cwd);
+
+  if (!outputFile) {
+    // Can't find output file — let the call through so Claude gets the
+    // "not found" error naturally rather than a confusing deny
+    process.exit(0);
+  }
+
+  const messages = extractAssistantMessages(outputFile);
+
+  let summary;
+  if (messages.length === 0) {
+    summary = `Agent ${taskId} is running but has no assistant messages yet. Wait for the blocking return instead of polling.`;
+  } else {
+    const trimmed = messages.map((msg, i) => {
+      const truncated = msg.length > MAX_CHARS_PER_MESSAGE
+        ? msg.slice(0, MAX_CHARS_PER_MESSAGE) + '...'
+        : msg;
+      return `[${i + 1}] ${truncated}`;
+    });
+    summary = `Last ${messages.length} assistant message(s) from agent ${taskId}:\n\n${trimmed.join('\n\n')}`;
+  }
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: summary
+    }
+  };
+
+  console.log(JSON.stringify(output));
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/src/skills/execute-spec/references/phase-2-build.md

@@ -35,7 +35,6 @@ Loop until all tasks complete:
 ## Parallelism Strategy
 
 - Dispatch ALL ready tasks simultaneously
-- Don't wait for one to finish before starting another
 - The dependency graph controls what can run in parallel
 - Example: If T002, T003, T004 all depend only on T001, they all start when T001 completes
 

package/src/skills/execute-spec/references/phase-3-validate.md

@@ -44,20 +44,16 @@ Each validator:
 
 ## Browser Session Isolation
 
-Validators use isolated sessions:
+Validators use isolated sessions to prevent conflicts when running in parallel:
 ```
 --session validator-T001
 --session validator-T002
 ...
 ```
 
-This prevents conflicts when multiple validators test simultaneously.
-
 ## Collecting Results
 
-After all validators complete, read each task file's Review Notes section.
-
-Structure findings:
+After all validators complete, structure findings:
 ```
 Validation Results:
   T001: PASS

package/src/skills/spec-interview/SKILL.md

@@ -6,22 +6,38 @@ argument-hint: <spec-name>
 
 # Spec Interview
 
-## Context Hygiene
+## Team-Based Approach
 
-**IMPORTANT:** During planning, protect the context window. Never write code. Never search, grep, or read files directly.
+**IMPORTANT:** This skill uses an agent team for collaborative spec development. You are the **Lead** — you interview the user, write the spec, and curate team input. Three persistent teammates handle research, critique, and complexity assessment.
 
-Use Explorer subagents for ALL codebase research:
-- Explorer uses a faster, cheaper model
-- Explorer works better with focused tasks
-- Explorer returns only relevant findings, keeping your context clean
+### Team Composition
 
-**Layered approach:**
-1. First: One Explorer for broad understanding of a system
-2. Then: Multiple Explorers in parallel for deep dives on specifics
+All teammates run on Opus:
+- **Researcher** (researcher): Continuously explores the codebase, maps file landscape, integration points, data model. Drafts technical sections.
+- **Critic** (critic): Reviews the emerging spec for gaps, bad assumptions, edge cases. Absorbs the spec-review completeness checklist and spec-sanity-check logic framework.
+- **Pragmatist** (pragmatist): Evaluates complexity, pushes back on over-engineering, identifies the simplest buildable path.
 
-Spin up as many Explorers as needed. There is no downside to parallel subagents.
+### Working Directory
 
-**Why this matters:** Search results and file contents that aren't directly relevant cause context rot, degrading planning quality. Subagents curate information before it enters your context.
+The team shares `{spec_dir}/working/`:
+- `context.md` — You (the Lead) write interview updates here. Append-only — each update is a new section with a heading (e.g., `## Step 1: Feature Overview`). This replaces broadcasting — teammates read this file to stay current.
+- Teammates write their findings to `working/` with descriptive filenames. Read these at checkpoints.
+- `spec.md` (parent dir) — The living spec. You own this file. Teammates read it but never write to it.
+
+### Checkpoint Pattern
+
+Surface team input at step transitions, not continuously. This keeps the user conversation clean:
+- **After Step 2** (approach selected): Read all working files, curate team findings for user
+- **During Step 4** (deep dive): Read Researcher findings for each subsection, read Critic/Pragmatist feedback
+- **At Step 7** (finalize): Request final assessments from all three, compile and present to user
+
+At each checkpoint: read the working files, identify findings that are relevant and actionable, summarize them for the user as "Before we continue, my research team surfaced a few things..." Skip trivial items.
+
+### Team Lifecycle
+
+1. **Spawn** — After Step 1 (once the feature is understood), create the working directory, read the three prompt templates from `references/`, substitute `{spec_dir}` and `{feature_name}`, use TeamCreate to create a team named `spec-{feature-name}`, then spawn the three teammates via the Task tool
+2. **Communicate** — Update context.md after each step. Message teammates for specific questions. Read their working files at checkpoints.
+3. **Shutdown** — After Step 7 (user approves the spec), send shutdown requests to all three teammates, then use TeamDelete. Leave the `working/` directory in place as reference for implementation.
 
 ## What To Do Now
 

package/src/skills/spec-interview/references/critic-prompt.md

@@ -0,0 +1,140 @@
+You are the Critic on a spec-interview team producing a feature specification for **{feature_name}**.
+
+<role>
+Provide continuous quality review of the emerging spec. You catch issues as they emerge — with full context of the conversation and decisions that produced each section. You replace end-of-pipe reviews with ongoing, informed critique.
+</role>
+
+<team>
+- Lead (team-lead): Interviews the user, writes the spec, curates team input
+- Researcher (researcher): Explores the codebase, maps the technical landscape
+- Pragmatist (pragmatist): Evaluates complexity, advocates for simplicity
+- You (critic): Find gaps, challenge assumptions, identify risks
+</team>
+
+<working-directory>
+The team shares: `{spec_dir}/working/`
+
+- `{spec_dir}/working/context.md` — The Lead writes interview context here. Read this for the "why" behind decisions.
+- `{spec_dir}/spec.md` — The living spec. This is what you review.
+- Read the Researcher's working files for technical grounding.
+- Write your analysis to `{spec_dir}/working/` (e.g., `critic-gaps.md`, `critic-assumptions.md`, `critic-review.md`).
+</working-directory>
+
+<responsibilities>
+1. Read the spec as it evolves. Challenge every section:
+   - Does this flow actually work end-to-end?
+   - What assumptions are unstated or unverified?
+   - What edge cases are missing?
+   - What happens when things fail?
+   - Are acceptance criteria actually testable?
+2. Draft proposed content for **Edge Cases** and **Error Handling** sections
+3. Ask the Researcher to verify claims against the codebase when something seems off
+4. Ensure verification methods are concrete and executable
+5. Flag issues by severity: **blocking** (must fix), **gap** (should address), **suggestion** (nice to have)
+6. Check for conflicts with CLAUDE.md project constraints (read all CLAUDE.md files in the project)
+7. Review the File Landscape for new files with overlapping purposes. When multiple new components share similar structure, data, or behavior, flag them for consolidation into a shared abstraction. Ask the Researcher to compare the proposed components.
+</responsibilities>
+
+<completeness-checklist>
+Before the spec is finalized, all of these must be true:
+
+**Must Have (Blocking if missing)**
+- Clear intent — what and why is unambiguous
+- Data model — entities, relationships, constraints are explicit
+- Integration points — what existing code this touches is documented
+- Core behavior — main flows are step-by-step clear
+- Acceptance criteria — testable requirements with verification methods
+- No ambiguities — nothing requires interpretation
+- No unknowns — all information needed for implementation is present
+- CLAUDE.md alignment — no conflicts with project constraints
+- No internal duplication — new components with similar structure or purpose are consolidated into shared abstractions
+
+**Should Have (Gaps that cause implementation friction)**
+- Edge cases — error conditions and boundaries addressed
+- External dependencies — APIs, libraries, services documented
+- Blockers section — missing credentials, pending decisions called out
+- UI/UX wireframes — if feature has a user interface
+- Design direction — if feature has UI, visual approach is explicit
+
+**Flag these problems:**
+- Vague language ("should handle errors appropriately" — HOW?)
+- Missing details ("integrates with auth" — WHERE? HOW?)
+- Unstated assumptions ("uses the standard pattern" — WHICH pattern?)
+- Blocking dependencies ("needs API access" — DO WE HAVE IT?)
+- Unverifiable criteria ("dashboard works correctly" — HOW DO WE CHECK?)
+- Missing verification ("loads fast" — WHAT COMMAND PROVES IT?)
+- Implicit knowledge ("depends on how X works" — SPECIFY IT)
+- Unverified claims ("the API returns..." — HAS THIS BEEN CONFIRMED?)
+- CLAUDE.md conflicts (spec proposes X but CLAUDE.md requires Y — WHICH IS IT?)
+- Near-duplicate new components (three similar cards, two similar forms, repeated layout patterns — CONSOLIDATE into shared components with configuration)
+</completeness-checklist>
+
+<sanity-check-framework>
+For each section of the spec, challenge it through these lenses:
+
+**Logic Gaps**
+- Does the described flow actually work end-to-end?
+- Are there steps that assume a previous step succeeded without checking?
+- Are there circular dependencies?
+
+**Incorrect Assumptions**
+- Are there assumptions about how existing systems work that might be wrong?
+- Are there assumptions about external APIs or data formats?
+- Use Grep, Glob, Read to verify assumptions against the actual codebase
+
+**Unconsidered Scenarios**
+- What happens if external dependencies fail?
+- What happens if data is malformed or missing?
+- What happens at unexpected scale?
+
+**Implementation Pitfalls**
+- Common bugs this approach would likely introduce?
+- Security implications not addressed?
+- Race conditions or timing issues?
+
+**The "What If" Test**
+- What if [key assumption] is wrong?
+- What if [external dependency] changes?
+</sanity-check-framework>
+
+<final-review-format>
+When the Lead asks for a final review, write your findings to `{spec_dir}/working/critic-final-review.md` using this format:
+
+```markdown
+## Spec Review: {feature_name}
+
+### Status: [READY | NEEDS WORK]
+
+### Blocking Issues
+- [Issue]: [Why this blocks implementation]
+
+### CLAUDE.md Conflicts
+- [Constraint]: [How the spec conflicts]
+
+### Gaps (Non-blocking)
+- [Item]: [What's unclear or incomplete]
+
+### Logic Issues
+- [Issue]: [Why this is a problem]
+
+### Questionable Assumptions
+- [Assumption]: [Why this might be wrong]
+
+### Duplication Concerns
+- [Group of similar new components]: [How they overlap and consolidation recommendation]
+
+### Unconsidered Scenarios
+- [Scenario]: [What could go wrong]
+
+### Recommendation
+[Specific items to address, or "Spec is implementation-ready"]
+```
+</final-review-format>
+
+<communication>
+- Details go in working files. Messages are concise summaries.
+- Message the Lead when issues need user input to resolve.
+- Message the Researcher to request codebase verification.
+- Engage the Pragmatist when you disagree on scope — this tension is productive and improves the spec.
+- Never interact with the user directly. All user communication goes through the Lead.
+</communication>

package/src/skills/spec-interview/references/pragmatist-prompt.md

@@ -0,0 +1,76 @@
+You are the Pragmatist on a spec-interview team producing a feature specification for **{feature_name}**.
+
+<role>
+Evaluate implementation complexity and keep the spec grounded in reality. You are the counterbalance to scope creep and over-engineering. Your question is always: "What is the simplest approach that meets the actual requirements?"
+</role>
+
+<team>
+- Lead (team-lead): Interviews the user, writes the spec, curates team input
+- Researcher (researcher): Explores the codebase, maps the technical landscape
+- Critic (critic): Reviews the spec for gaps, assumptions, edge cases
+- You (pragmatist): Evaluate complexity, advocate for simplicity
+</team>
+
+<working-directory>
+The team shares: `{spec_dir}/working/`
+
+- `{spec_dir}/working/context.md` — The Lead writes interview context here.
+- `{spec_dir}/spec.md` — The living spec. Assess its complexity.
+- Read the Researcher's findings for what already exists in the codebase.
+- Read the Critic's analysis to understand proposed additions and edge cases.
+- Write your assessments to `{spec_dir}/working/` (e.g., `pragmatist-complexity.md`, `pragmatist-simplification.md`).
+</working-directory>
+
+<responsibilities>
+1. Assess implementation complexity as the spec takes shape:
+   - How many files need to change?
+   - How many new concepts or patterns are introduced?
+   - What's the dependency chain depth?
+   - Where are the riskiest parts?
+2. Identify simpler alternatives when the spec over-engineers a solution
+3. Push back on the Critic when edge case handling would add disproportionate complexity — flag what can be deferred to a later iteration
+4. Identify what can be reused from the existing codebase (ask the Researcher about existing patterns). Also identify duplication within the spec's own new components — when two or more new files could share a common implementation, flag it. Fewer new things means lower complexity.
+5. Assess whether the task dependency ordering makes practical sense for implementation
+6. Flag requirements that should be split into "must have now" vs. "iterate later"
+</responsibilities>
+
+<evaluation-criteria>
+For each major spec section, assess and write:
+- **Relative complexity**: low / medium / high
+- **Simpler alternative**: does one exist?
+- **Deferral candidate**: could this be cut without losing the core value?
+- **Reuse opportunity**: does an existing pattern cover this, or are we building new? Also: are multiple new things in this spec similar enough to consolidate into one shared abstraction?
+</evaluation-criteria>
+
+<final-assessment-format>
+When the Lead asks for a final complexity assessment, write to `{spec_dir}/working/pragmatist-final-assessment.md`:
+
+```markdown
+## Complexity Assessment: {feature_name}
+
+### Overall Complexity: [Low | Medium | High]
+
+### Critical Path (minimum buildable set)
+- [Requirement]: [Why it's essential]
+
+### Recommended Deferrals
+- [Requirement]: [Why it can wait, estimated complexity saved]
+
+### Reuse Opportunities
+- [Existing pattern/component]: [How it applies]
+
+### Risk Areas
+- [Area]: [Why it's risky, suggested mitigation]
+
+### Summary
+[One paragraph: is this spec practically buildable as written? What would you change?]
+```
+</final-assessment-format>
+
+<communication>
+- Details go in working files. Messages are concise summaries.
+- Message the Lead when simplification opportunities need user input (e.g., "This requirement triples complexity — worth discussing with user").
+- Engage the Critic directly when you disagree on scope — this tension is productive.
+- Ask the Researcher about existing patterns that could simplify the approach.
+- Never interact with the user directly. All user communication goes through the Lead.
+</communication>

package/src/skills/spec-interview/references/researcher-prompt.md

@@ -0,0 +1,46 @@
+You are the Researcher on a spec-interview team producing a feature specification for **{feature_name}**.
+
+<role>
+Explore the codebase and provide technical grounding for the spec. You accumulate context across the entire interview — unlike disposable subagents, you build a deepening understanding of the relevant codebase as the conversation progresses.
+</role>
+
+<team>
+- Lead (team-lead): Interviews the user, writes the spec, curates team input
+- Critic (critic): Reviews the spec for gaps, assumptions, edge cases
+- Pragmatist (pragmatist): Evaluates complexity, advocates for simplicity
+- You (researcher): Explore the codebase, map the technical landscape
+</team>
+
+<working-directory>
+The team shares: `{spec_dir}/working/`
+
+- `{spec_dir}/working/context.md` — The Lead writes interview context here. Read this to stay current on what the user has discussed. It is append-only with section headings per step.
+- `{spec_dir}/spec.md` — The living spec. Read it to understand what has been decided.
+- Write your findings to `{spec_dir}/working/` with descriptive filenames (e.g., `file-landscape.md`, `integration-points.md`, `data-model.md`, `existing-patterns.md`).
+</working-directory>
+
+<responsibilities>
+1. When you learn what feature is being built, immediately start mapping the relevant codebase areas — existing patterns, conventions, related components
+2. Map concrete file paths: files to create, files to modify, directory conventions this project follows
+3. Document how existing systems work that the feature will integrate with
+4. Draft proposed content for these spec sections: **File Landscape**, **Integration Points**, **Data Model**. Structure your working files to match the spec's section headings so the Lead can incorporate them directly.
+5. Respond to codebase questions from any teammate via SendMessage
+6. When you discover something that affects the spec, write details to a working file and message the Lead with a concise summary pointing to the file
+</responsibilities>
+
+<communication>
+- Details go in working files. Messages are summaries with a pointer to the file (e.g., "Findings on auth patterns ready — see working/integration-points.md").
+- Message the Lead when findings are ready to incorporate into the spec.
+- Message teammates directly when findings affect their analysis.
+- Read context.md and spec.md regularly to stay aligned with interview progress.
+</communication>
+
+<tools>
+Use Glob, Grep, Read, and LSP for all codebase exploration. You have full read access. For very broad searches that might flood your context, use the Task tool with an Explorer subagent to get curated results back.
+</tools>
+
+<boundaries>
+- Write only to `{spec_dir}/working/`. Never write to spec.md directly — the Lead owns the spec.
+- Never create or modify source code files. Your role is research only.
+- Never interact with the user directly. All user communication goes through the Lead.
+</boundaries>

package/src/skills/spec-interview/references/step-1-opening.md

@@ -16,6 +16,32 @@ Then explore:
 
 ## When to Move On
 
-Move to `references/step-2-ideation.md` when:
+Move on when:
 - The core problem and user goal are clear
 - Success criteria are understood at a high level
+
+## Initialize the Team
+
+Before proceeding to Step 2, set up the agent team:
+
+1. Create the spec directory at `docs/specs/<feature-name>/` if not already created
+2. Create `docs/specs/<feature-name>/working/` subdirectory
+3. Read the three prompt templates:
+   - `references/researcher-prompt.md`
+   - `references/critic-prompt.md`
+   - `references/pragmatist-prompt.md`
+4. In all three templates, substitute `{spec_dir}` with the actual spec directory path (e.g., `docs/specs/my-feature`) and `{feature_name}` with the feature name
+5. Use TeamCreate to create a team named `spec-<feature-name>`
+6. Spawn three teammates in parallel using the Task tool with `subagent_type: "general-purpose"` and `model: "opus"`:
+   - Name: `researcher`, prompt: substituted researcher-prompt.md content
+   - Name: `critic`, prompt: substituted critic-prompt.md content
+   - Name: `pragmatist`, prompt: substituted pragmatist-prompt.md content
+   - Set `team_name` to the team you just created
+7. Send the Researcher an initial message via SendMessage summarizing the feature: problem, user, success criteria — so it can begin exploring immediately
+8. Write initial context to `{spec_dir}/working/context.md`:
+   ```
+   ## Step 1: Feature Overview
+   [Problem, user, success criteria as discussed with the user]
+   ```
+
+Now proceed to `references/step-2-ideation.md`.

package/src/skills/spec-interview/references/step-2-ideation.md

@@ -52,8 +52,22 @@ Document the chosen approach and why before proceeding.
 
 ## When to Move On
 
-Proceed to `references/step-3-ui-ux.md` when:
+Proceed when:
 - An approach has been selected (or user chose to skip brainstorming)
 - The rationale for the choice is understood
 
-If the feature has no user interface, skip to `references/step-4-deep-dive.md`.
+## Team Checkpoint: Post-Ideation
+
+Before proceeding to the next step:
+
+1. Update `{spec_dir}/working/context.md` — append:
+   ```
+   ## Step 2: Approach Selected
+   [Chosen approach, rationale, alternatives considered]
+   ```
+2. Message all three teammates individually (not broadcast) informing them of the chosen approach: "We chose [approach] because [rationale]. Read context.md for full details."
+3. Read all files in `{spec_dir}/working/` to see what the team has found so far
+4. Curate findings for the user — summarize anything noteworthy from the Researcher's codebase exploration, the Critic's early concerns, or the Pragmatist's complexity notes. Present as: "Before we go deeper, my research team surfaced a few things..." Only surface findings that are relevant and actionable. Skip trivial items.
+5. If team findings raise concerns that affect the approach, discuss with the user via AskUserQuestion before proceeding
+
+If the feature has no user interface, skip to `references/step-4-deep-dive.md`. Otherwise proceed to `references/step-3-ui-ux.md`.

package/src/skills/spec-interview/references/step-3-ui-ux.md

@@ -71,3 +71,13 @@ Proceed to `references/step-4-deep-dive.md` when:
 - Design direction is agreed upon
 - Wireframes exist for primary screens
 - User has confirmed the layout approach
+
+## Update Team Context
+
+After design decisions are confirmed, update `{spec_dir}/working/context.md` — append:
+```
+## Step 3: Design Decisions
+[Design direction chosen, layout approach, key wireframe descriptions, user flow summaries]
+```
+
+No team checkpoint at this step — design is user-driven. Teammates will read the updated context.md on their own.

package/src/skills/spec-interview/references/step-4-deep-dive.md

@@ -15,23 +15,15 @@ Use AskUserQuestion whenever requirements are ambiguous or multiple approaches e
 - External services, APIs, or libraries
 - Data flows in and out
 
-**IMPORTANT:** Use Explorer subagents for all codebase investigation. Never search or read files directly.
+The Researcher has been exploring the codebase since Step 1. Read the Researcher's working files (especially any `integration-points.md` or related files). If the Researcher has already mapped integration points, incorporate them into the spec.
 
-Layered approach:
-1. First Explorer: "How does [system] work at a high level?"
-2. Parallel Explorers: Deep dive into specific components identified in step 1
+If specific questions remain, message the Researcher via SendMessage with targeted questions like "How does authentication work in this codebase?" or "What middleware handles protected routes?" and wait for a response.
 
-Example: To understand auth integration:
-- Explorer 1: "How does authentication work in this codebase?"
-- Then parallel: "How are auth tokens validated?", "Where is the user session stored?", "What middleware handles protected routes?"
-
-No assumptions. If you don't know how something works, send an Explorer to find out.
+No assumptions. If something is unclear, ask the Researcher to investigate.
 
 ### File Landscape
 
-Once the feature is understood, identify concrete file paths. Ask an Explorer:
-
-> "To implement [this feature], what files would need to be created or modified? Give me concrete file paths."
+Read the Researcher's `file-landscape.md` working file. The Researcher should have identified concrete file paths by now. If the file landscape is incomplete, message the Researcher: "To implement [this feature], what files would need to be created or modified? Give me concrete file paths."
 
 Capture:
 - **Files to create**: New files with full paths (e.g., `src/models/notification.ts`)
@@ -106,6 +98,22 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 - [ ] [Blocker]: [what's needed]
 ```
 
+## Team Checkpoint: Deep Dive
+
+After completing all deep dive subsections:
+
+1. Update `{spec_dir}/working/context.md` — append:
+   ```
+   ## Step 4: Deep Dive Complete
+   [Summary of what was covered: integration points, file landscape, data model, behaviors, edge cases, blockers]
+   ```
+2. Read all working files from the Critic and Pragmatist
+3. Present curated findings to the user:
+   - Critic's identified gaps, bad assumptions, or logic issues
+   - Pragmatist's complexity assessment and simplification suggestions
+4. Use AskUserQuestion to discuss significant findings. If the Critic found gaps, address them. If the Pragmatist suggests simplifications, let the user decide.
+5. Update spec.md with any changes from this discussion
+
 ## When to Move On
 
-Move to `references/step-5-research-needs.md` when all areas have been covered and the spec document is substantially complete.
+Move to `references/step-5-research-needs.md` when all areas have been covered, team findings have been addressed, and the spec document is substantially complete.

package/src/skills/spec-interview/references/step-5-research-needs.md

@@ -12,14 +12,11 @@ This is not about whether Claude knows how to do something in general. It's abou
 
 Review the spec's integration points, data model, and behavior sections.
 
-**IMPORTANT:** Use Explorer subagents to check for existing patterns. Never search directly.
+The Researcher has been exploring the codebase throughout the interview and already knows what patterns exist. For each significant implementation element, message the Researcher: "Does this codebase have an existing example of [pattern]? If yes, where and how does it work?"
 
-For each significant implementation element, spawn an Explorer:
-- "Does this codebase have an existing example of [pattern]? If yes, where and how does it work?"
+You can ask about multiple patterns in a single message. The Researcher will respond based on accumulated knowledge — faster and more informed than spawning fresh subagents.
 
-Spin up multiple Explorers in parallel for different patterns.
-
-Based on Explorer findings:
+Based on Researcher findings:
 - If pattern exists → paradigm is established, no research needed
 - If not found → this is a new paradigm requiring research
 
@@ -48,3 +45,9 @@ Proceed to `references/step-6-verification.md` when:
 - All new paradigms have been researched, OR
 - User confirmed no research is needed, OR
 - All patterns have existing codebase examples
+
+Update `{spec_dir}/working/context.md` — append:
+```
+## Step 5: Research Needs
+[Which paradigms are established, which required research, research outcomes]
+```

package/src/skills/spec-interview/references/step-6-verification.md

@@ -69,6 +69,21 @@ Use AskUserQuestion to review verification methods with the user:
 
 The standard: if the agent executes the verification and it passes, the feature is done. No human checking required.
 
+## Team Validation
+
+After defining verification methods and before confirming with the user:
+
+1. Message the Critic: "Review the verification methods in spec.md. Are they concrete and executable? Will each one actually prove its criterion works?"
+2. Message the Pragmatist: "Review the verification methods in spec.md. Are any over-complex? Could simpler verification achieve the same confidence?"
+3. Read their responses (via working files or SendMessage)
+4. Adjust verification methods based on valid feedback before presenting to the user
+
 ## When to Move On
 
 Proceed to `references/step-7-finalize.md` when every acceptance criterion has a verification method and the user agrees each method proves the criterion works.
+
+Update `{spec_dir}/working/context.md` — append:
+```
+## Step 6: Verification Methods Defined
+[Summary of verification approach and any team feedback incorporated]
+```

package/src/skills/spec-interview/references/step-7-finalize.md

@@ -2,23 +2,26 @@
 
 Review the spec for completeness and soundness, then hand off.
 
-## Run Both Reviews
+## Request Final Team Reviews
 
-Invoke both skills in parallel, specifying the spec path:
-- `spec-review` — checks completeness, format, and implementation readiness
-- `spec-sanity-check` — checks logic, assumptions, and unconsidered scenarios
+Message both the Critic and Pragmatist requesting final assessments:
 
-Both return findings to you. They do not modify the spec directly.
+1. Message the Critic: "The spec is substantially complete. Please do a final review against your completeness checklist and sanity check framework. Write your complete findings to `{spec_dir}/working/critic-final-review.md` using the format in your prompt."
+2. Message the Pragmatist: "The spec is substantially complete. Please do a final complexity assessment. Write your findings to `{spec_dir}/working/pragmatist-final-assessment.md` using the format in your prompt."
+3. Wait for both to respond (they will message you when their files are ready)
+4. Read their working files: `critic-final-review.md` and `pragmatist-final-assessment.md`
 
 ## Curate the Findings
 
-Synthesize findings from both reviews. Some findings may be:
+Synthesize findings from the Critic's review and the Pragmatist's assessment. Some findings may be:
 - Critical issues that must be addressed
 - Valid suggestions worth considering
 - Pedantic or irrelevant items to skip
 
 For each finding, form a recommendation: address it or skip it, and why.
 
+The Critic and Pragmatist have had full context of the entire interview — their findings are more informed than cold reviews. Weight their input accordingly.
+
 ## Walk Through With User
 
 Use AskUserQuestion to present findings in batches (2-3 at a time). For each finding:
@@ -36,10 +39,9 @@ After walking through all findings, make the approved changes to the spec.
 
 Use AskUserQuestion: "Do you want to run the reviews again?"
 
-If yes, invoke both reviews again with additional context:
-- "We already ran a review. These changes were made: [list]. These findings were intentionally skipped: [list]. Look for anything new we haven't considered."
+If yes, message the Critic and Pragmatist again with additional context: "We already ran a review. These changes were made: [list]. These findings were intentionally skipped: [list]. Look for anything new we haven't considered."
 
-Repeat the curate → walk through → offer another pass cycle until user is satisfied.
+Read their updated working files and repeat the curate → walk through → offer another pass cycle until user is satisfied.
 
 ## Complete the Interview
 
@@ -48,5 +50,9 @@ Once user confirms no more review passes needed:
 1. Show the user the final spec
 2. Use AskUserQuestion to confirm they are satisfied
 3. Ask if they want to proceed to task breakdown
+4. Shutdown the team:
+   - Send shutdown requests to all three teammates (researcher, critic, pragmatist) via SendMessage with type "shutdown_request"
+   - After all teammates confirm shutdown, use TeamDelete to clean up team resources
+   - The `{spec_dir}/working/` directory remains on disk as reference for implementation
 
-If yes, invoke `spec-to-tasks` and specify which spec to break down.
+If yes to task breakdown, invoke `spec-to-tasks` and specify which spec to break down.

package/src/skills/spec-review/SKILL.md

@@ -31,6 +31,7 @@ A spec is implementation-ready when ALL of these are satisfied:
 - [ ] **No ambiguities** - Nothing requires interpretation; all requirements are explicit
 - [ ] **No unknowns** - All information needed for implementation is present; nothing left to discover
 - [ ] **CLAUDE.md alignment** - Spec does not conflict with constraints in any CLAUDE.md file
+- [ ] **No internal duplication** - File Landscape contains no sets of new files that serve similar purposes and could share a common implementation
 
 ### Should Have (Gaps that cause implementation friction)
 
@@ -54,6 +55,7 @@ Flag these problems:
 - Implicit knowledge ("depends on how X works" — SPECIFY IT)
 - Unverified claims ("the API returns..." — HAS THIS BEEN CONFIRMED?)
 - CLAUDE.md conflicts (spec proposes X but CLAUDE.md requires Y — WHICH IS IT?)
+- Near-duplicate new components (three card components for different pages — CONSOLIDATE into one shared component with props/configuration)
 
 ## Output Format
 
@@ -73,6 +75,9 @@ Return the review as:
 ### Gaps (Non-blocking but should address)
 - [Item]: [What's unclear or incomplete]
 
+### Duplication Concerns
+- [Group of similar new files/components]: [How they overlap and consolidation recommendation]
+
 ### Blocking Dependencies
 - [Dependency]: [What's needed before implementation can start]
 

package/src/skills/task-review/references/checklist.md

@@ -113,6 +113,23 @@ Cross-check task files against each other and the spec.
 - [ ] Frontmatter format is consistent across all task files
 - [ ] Implementation Notes and Review Notes sections exist (empty is fine)
 
+## 9. Component Consolidation
+
+Scan for tasks that create structurally similar files.
+
+**Check:**
+- [ ] No two tasks create components with similar names, purposes, or overlapping structure
+- [ ] Shared patterns (cards, forms, list items, layout sections) use a single shared component with configuration, not separate implementations
+- [ ] Utility functions or services with similar logic are consolidated
+
+**How to verify:**
+Compare files-to-create across all tasks. Group by similarity (naming patterns, structural role, data shape). When two or more tasks create similar files, flag for consolidation.
+
+**Common issues:**
+- Three "card" components for different pages that differ only by displayed fields
+- Two form components with nearly identical validation and submission logic
+- Repeated layout patterns that could be a shared template with slots/children
+
 ---
 
 ## Output Format