cc-dev-template 0.1.61 → 0.1.63

package/bin/install.js

@@ -71,7 +71,24 @@ console.log(agentCount ? `✓ ${agentCount} agents installed` : '  No agents to
 console.log('\nScripts:');
 const scriptCount = copyFiles('scripts', 'scripts', '.js');
 const jsonCount = copyFiles('scripts', 'scripts', '.json');
-console.log(scriptCount || jsonCount ? `✓ ${scriptCount + jsonCount} scripts installed` : '  No scripts to install');
+
+// Copy shell scripts and make executable
+const scriptsDir = path.join(SRC_DIR, 'scripts');
+let shellCount = 0;
+if (fs.existsSync(scriptsDir)) {
+  const shellScripts = fs.readdirSync(scriptsDir).filter(f => f.endsWith('.sh'));
+  shellScripts.forEach(file => {
+    const src = path.join(scriptsDir, file);
+    const dest = path.join(CLAUDE_DIR, 'scripts', file);
+    fs.copyFileSync(src, dest);
+    fs.chmodSync(dest, 0o755);
+    console.log(`  ${file}`);
+    shellCount++;
+  });
+}
+
+const totalScripts = scriptCount + jsonCount + shellCount;
+console.log(totalScripts ? `✓ ${totalScripts} scripts installed` : '  No scripts to install');
 
 // Copy skills (entire directories)
 console.log('\nSkills:');
@@ -238,7 +255,10 @@ if (fs.existsSync(mergeSettingsPath)) {
     { file: 'read-guard-hook.json', name: 'Context guard for large reads' },
     { file: 'statusline-config.json', name: 'Custom status line' },
     { file: 'bash-overflow-hook.json', name: 'Bash overflow guard hook' },
-    { file: 'env-config.json', name: 'Environment variables' }
+    { file: 'env-config.json', name: 'Environment variables' },
+    // Spinner verbs - choose one (Helldivers or Factorio)
+    { file: 'spinner-verbs-helldivers.json', name: 'Helldivers spinner verbs' }
+    // { file: 'spinner-verbs-factorio.json', name: 'Factorio spinner verbs' }
   ];
 
   configs.forEach(({ file, name }) => {

package/package.json

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

package/src/agents/spec-implementer.md

@@ -6,11 +6,46 @@ tools: Read, Grep, Glob, Edit, Write, Bash, LSP
 
 You implement one task from a spec breakdown.
 
+## Process
+
 When given a task file path:
 
 1. Read the task file at that path
 2. Read the spec file in the parent directory (`../spec.md`)
-3. Understand the **Criterion** section—this defines success
-4. Implement the criterion, touching only files listed in the **Files** section
-5. Write a brief summary of what you did to the **Implementation Notes** section of the task file
-6. Mark the task complete
+3. Check the **Review Notes** section of the task file:
+   - **If issues exist**: Address those specific issues (fix mode)
+   - **If empty**: Implement from scratch per the Criterion (initial mode)
+4. Implement the work, touching only files listed in the **Files** section
+5. Append your work summary to **Implementation Notes** (see format below)
+6. Return minimal status (see Output section)
+
+## Implementation Notes Format
+
+Append a new section with timestamp:
+
+```markdown
+### Pass N (YYYY-MM-DD HH:MM)
+
+[Brief summary of what you implemented or fixed]
+
+Files modified:
+- path/to/file.ts - [what changed]
+```
+
+Do NOT overwrite previous passes. The log provides debugging context.
+
+## Output (Critical)
+
+Return ONLY a minimal status message. All details go in the task file.
+
+**Success:**
+```
+Task complete: T005-variant-selection.md
+```
+
+**Blocked:**
+```
+Blocked: T005 - [one-line reason why you cannot proceed]
+```
+
+Do NOT return tables, code snippets, file listings, or detailed explanations. The orchestrator only needs pass/fail status. All details belong in the task file's Implementation Notes section.

package/src/agents/spec-validator.md

@@ -6,18 +6,23 @@ tools: Read, Grep, Glob, Bash
 
 You are a senior QA engineer validating completed work.
 
+## Process
+
 When given a task file path:
 
 1. Read the task file and parent spec (`../spec.md`)
 2. Read the **Implementation Notes** to understand what was built
+3. Perform validation (see steps below)
+4. Append findings to **Review Notes** (see format below)
+5. Return minimal status (see Output section)
 
 ## Step 1: Code Review + Automated Tests
 
 - Run automated tests if they exist (look for test files, run with appropriate test runner)
 - Check for code smells:
-  - Files over 300 lines: Can this logically split into multiple files, or does it need to be one file? Note your assessment.
+  - Files over 300 lines: Can this logically split into multiple files, or does it need to be one file?
   - Missing error handling, unclear naming, other quality issues
-- Note any concerns
+- Note concerns for Review Notes
 
 ## Step 2: E2E Testing with agent-browser
 
@@ -32,11 +37,43 @@ Run `agent-browser --help` if you need to understand its capabilities.
   - Does the feature work as a user would expect?
 - Close your session when finished: `agent-browser close --session validator-{task-id}`
 
-## Output
+## Review Notes Format
+
+Append a new section with timestamp:
+
+```markdown
+### Pass N (YYYY-MM-DD HH:MM)
+
+**Result**: PASS | FAIL
+
+**Issues** (if any):
+- [critical] one-line description
+- [warning] one-line description
+- [suggestion] one-line description
+
+**E2E Tests**:
+- [pass/fail] Test description
+
+**Notes**: [Any additional context needed for fix]
+```
+
+Do NOT overwrite previous passes. The log provides debugging context.
+
+## Output (Critical)
+
+Return ONLY a minimal status message. All details go in the task file.
+
+**Pass:**
+```
+Pass: T005
+```
 
-Write findings to the **Review Notes** section of the task file:
+**Issues found:**
+```
+Issues: T005
+- [critical] one-line summary
+- [warning] one-line summary
+Details in Review Notes.
+```
 
-- Issues found (with severity: critical, warning, suggestion)
-- Files that may need refactoring (with reasoning)
-- E2E test results (what worked, what didn't)
-- Overall pass/fail assessment
+Do NOT return tables, code snippets, detailed logs, or lengthy explanations. The orchestrator only needs pass/fail to decide next action. All details belong in the task file's Review Notes section.

package/src/scripts/block-task-files.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# PreToolUse hook for execute-spec skill
+# Blocks the orchestrator from reading task files directly
+# Task files should only be read by implementer/validator agents
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Check if this is a task file (pattern: */tasks/T*.md)
+if [[ "$FILE_PATH" =~ /tasks/T[0-9]+.*\.md$ ]]; then
+  jq -n '{
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "permissionDecision": "deny",
+      "permissionDecisionReason": "Task files should be read by spec-implementer/spec-validator agents, not the orchestrator. Pass the file path to agents and let them read it."
+    }
+  }'
+  exit 0
+fi
+
+# Allow all other reads
+exit 0

package/src/scripts/parse-task-files.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Parses task files from a spec directory and returns structured JSON.
+ * Used by execute-spec orchestrator to hydrate tasks without reading full file contents.
+ *
+ * Usage: node parse-task-files.js <spec-path>
+ * Example: node parse-task-files.js docs/specs/kiosk-storefront
+ *
+ * Output: JSON with task metadata (id, title, depends_on, path)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function parseYamlFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const yaml = match[1];
+  const result = {};
+
+  // Simple YAML parsing for our known fields
+  const lines = yaml.split('\n');
+  for (const line of lines) {
+    const idMatch = line.match(/^id:\s*(.+)/);
+    if (idMatch) result.id = idMatch[1].trim();
+
+    const titleMatch = line.match(/^title:\s*(.+)/);
+    if (titleMatch) result.title = titleMatch[1].trim();
+
+    const statusMatch = line.match(/^status:\s*(.+)/);
+    if (statusMatch) result.status = statusMatch[1].trim();
+
+    const dependsMatch = line.match(/^depends_on:\s*\[(.*)\]/);
+    if (dependsMatch) {
+      const deps = dependsMatch[1].trim();
+      result.depends_on = deps ? deps.split(',').map(d => d.trim()) : [];
+    }
+  }
+
+  // Handle multi-line depends_on
+  if (!result.depends_on) {
+    const depsSection = yaml.match(/depends_on:\s*\n((?:\s+-\s*.+\n?)*)/);
+    if (depsSection) {
+      result.depends_on = depsSection[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*-\s*/, '').trim())
+        .filter(Boolean);
+    } else {
+      result.depends_on = [];
+    }
+  }
+
+  return result;
+}
+
+function main() {
+  const specPath = process.argv[2];
+
+  if (!specPath) {
+    console.error(JSON.stringify({ error: 'Usage: parse-task-files.js <spec-path>' }));
+    process.exit(1);
+  }
+
+  const tasksDir = path.join(specPath, 'tasks');
+  const specFile = path.join(specPath, 'spec.md');
+
+  // Validate spec structure
+  if (!fs.existsSync(specFile)) {
+    console.error(JSON.stringify({ error: `Spec file not found: ${specFile}` }));
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(tasksDir)) {
+    console.error(JSON.stringify({ error: `Tasks directory not found: ${tasksDir}` }));
+    process.exit(1);
+  }
+
+  // Find and parse task files
+  const taskFiles = fs.readdirSync(tasksDir)
+    .filter(f => f.match(/^T\d+.*\.md$/))
+    .sort();
+
+  if (taskFiles.length === 0) {
+    console.error(JSON.stringify({ error: 'No task files found (expected T*.md)' }));
+    process.exit(1);
+  }
+
+  const tasks = [];
+
+  for (const file of taskFiles) {
+    const filePath = path.join(tasksDir, file);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const frontmatter = parseYamlFrontmatter(content);
+
+    if (!frontmatter || !frontmatter.id) {
+      console.error(JSON.stringify({ error: `Invalid frontmatter in ${file}` }));
+      process.exit(1);
+    }
+
+    tasks.push({
+      id: frontmatter.id,
+      title: frontmatter.title || file.replace('.md', ''),
+      status: frontmatter.status || 'pending',
+      depends_on: frontmatter.depends_on || [],
+      path: filePath
+    });
+  }
+
+  // Output structured JSON
+  console.log(JSON.stringify({
+    specPath: specPath,
+    specFile: specFile,
+    taskCount: tasks.length,
+    tasks: tasks
+  }, null, 2));
+}
+
+main();

package/src/scripts/spinner-verbs-factorio.json

@@ -0,0 +1,27 @@
+{
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": [
+      "Optimizing ratios",
+      "Expanding the factory",
+      "Researching technology",
+      "Balancing belts",
+      "Routing logistics",
+      "Smelting ore",
+      "Automating production",
+      "Deploying blueprints",
+      "Scaling throughput",
+      "Refining petroleum",
+      "Extending rail network",
+      "Calculating ratios",
+      "Processing resources",
+      "Assembling components",
+      "Constructing outpost",
+      "Launching rockets",
+      "Clearing biters",
+      "Inserting inserters",
+      "Growing the factory",
+      "The factory must grow"
+    ]
+  }
+}

package/src/scripts/spinner-verbs-helldivers.json

@@ -0,0 +1,27 @@
+{
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": [
+      "Spreading democracy",
+      "Liberating",
+      "Deploying stratagems",
+      "Calling in reinforcements",
+      "Eliminating hostiles",
+      "Securing perimeter",
+      "Extracting intel",
+      "Suppressing resistance",
+      "Dispensing freedom",
+      "Neutralizing threats",
+      "Conducting reconnaissance",
+      "Mobilizing forces",
+      "Purging enemies",
+      "Defending liberty",
+      "Executing orbital strike",
+      "Requesting extraction",
+      "Fortifying position",
+      "Engaging targets",
+      "Invoking Super Earth",
+      "Upholding managed democracy"
+    ]
+  }
+}

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

@@ -1,12 +1,18 @@
 ---
-allowed-tools: Read, Grep, Glob, Task, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion, Bash
+allowed-tools: Grep, Glob, Task, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion, Bash
+hooks:
+  PreToolUse:
+    - matcher: "Read"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/block-task-files.sh"
 ---
 
 # Execute Spec
 
 Orchestrates the implementation and validation of a spec's task breakdown.
 
-**Important**: This skill is an orchestrator. It reads task files and dispatches agents to do the work. It does NOT edit files directly - that's the job of the spec-implementer agents it spawns.
+**Important**: This skill is an orchestrator only. It does NOT read task files or edit code directly. It dispatches agents and receives minimal status responses. All detailed work happens in the agents; all detailed findings live in the task files.
 
 ## When to Use
 
@@ -23,10 +29,16 @@ Read `references/workflow.md` for the full orchestration flow.
 
 ## Phases
 
-1. **Hydrate** - Load task files into the task system with dependencies
-2. **Build** - Dispatch spec-implementer agents for each task (parallel, respecting dependencies)
-3. **Validate** - Dispatch spec-validator agents for each completed task
-4. **Triage** - Collect feedback, dispatch fixes or escalate to user
+1. **Hydrate** - Run parse script, create tasks with dependencies (NO file reading)
+2. **Build** - Dispatch spec-implementer agents, receive minimal status
+3. **Validate** - Dispatch spec-validator agents, receive pass/fail
+4. **Triage** - Re-dispatch implementers for failed tasks, loop until clean
+
+## Key Principles
+
+- **Never read task files** - Use the parse script for hydration, pass paths to agents
+- **Minimal context** - Agent returns are pass/fail only, details in task files
+- **Delegate everything** - Fixes go to spec-implementer, not done by orchestrator
 
 ## Requirements
 

package/src/skills/execute-spec/references/phase-1-hydrate.md

@@ -1,65 +1,71 @@
 # Phase 1: Hydrate Tasks
 
-Load task files from the spec into the Claude Code task system.
+Load task metadata into the Claude Code task system using the parse script.
 
-## Input
+## Important: No File Reading
 
-Spec path argument, e.g., `docs/specs/kiosk-storefront`
+The orchestrator does NOT read task files directly. Use the parse script.
 
 ## Process
 
+```bash
+# Run the parse script
+node ~/.claude/scripts/parse-task-files.js {spec-path}
 ```
-1. Validate spec structure:
-   - {spec-path}/spec.md exists
-   - {spec-path}/tasks/ directory exists
-   - tasks/ contains T*.md files
-
-2. For each task file (sorted by ID):
-   - Read file content
-   - Parse YAML frontmatter:
-     - id: T001, T002, etc.
-     - title: Human-readable title
-     - status: pending (should be pending at start)
-     - depends_on: [T001, T002] array of task IDs
-
-3. Create tasks in Claude Code task system:
-   TaskCreate(
-     subject: "{id}: {title}",
-     description: "Implement task file: {full-path-to-task-file}",
-     activeForm: "Implementing {title}"
-   )
-
-4. After all tasks created, set up dependencies:
-   For each task with depends_on:
-     TaskUpdate(
-       taskId: {claude-task-id},
-       addBlockedBy: [mapped-claude-task-ids]
-     )
+
+This outputs JSON:
+```json
+{
+  "specPath": "docs/specs/kiosk-storefront",
+  "specFile": "docs/specs/kiosk-storefront/spec.md",
+  "taskCount": 15,
+  "tasks": [
+    {
+      "id": "T001",
+      "title": "Public API endpoints",
+      "status": "pending",
+      "depends_on": [],
+      "path": "docs/specs/kiosk-storefront/tasks/T001-public-api-endpoints.md"
+    },
+    {
+      "id": "T002",
+      "title": "Kiosk routing",
+      "depends_on": ["T001"],
+      "path": "..."
+    }
+  ]
+}
 ```
 
-## Mapping Task IDs
+## Create Tasks
 
-The task files use IDs like T001, T002. The Claude Code task system assigns its own IDs.
+For each task in the JSON:
 
-Maintain a mapping:
 ```
-{
-  "T001": "claude-task-id-1",
-  "T002": "claude-task-id-2",
-  ...
-}
+TaskCreate(
+  subject: "{id}: {title}",
+  description: "{path}",
+  activeForm: "Implementing {title}"
+)
 ```
 
-Use this mapping when setting up blockedBy relationships.
+The description is JUST the path. Agents read the file themselves.
 
-## Output
+## Set Dependencies
 
-- All tasks loaded into Claude Code task system
-- Dependencies correctly configured
-- Ready for Phase 2: Build
+After creating all tasks, set up blockedBy relationships:
 
-## Error Handling
+```
+TaskUpdate(
+  taskId: {claude-task-id},
+  addBlockedBy: [mapped IDs from depends_on]
+)
+```
+
+Maintain a mapping of task IDs (T001, T002) to Claude task system IDs.
+
+## Output
 
-- If spec.md missing: Stop and report error
-- If tasks/ empty: Stop and report "No tasks to execute"
-- If task file has invalid frontmatter: Report which file and what's wrong
+- All tasks in Claude Code task system
+- Dependencies configured
+- Ready for Phase 2

package/src/skills/execute-spec/references/phase-4-triage.md

@@ -1,103 +1,75 @@
 # Phase 4: Triage
 
-Process validation findings, fix issues, and iterate until clean.
+Process validation results and iterate until all tasks pass.
 
 ## Process
 
 ```
-1. Collect all issues from validator Review Notes
-
-2. Categorize issues:
-
-   EASY FIXES (dispatch automatically):
-   - Missing import
-   - Typo in text
-   - Small styling fix
-   - Test assertion needs update
-   - File exists but missing export
-
-   COMPLEX ISSUES (ask user):
-   - Architectural concerns
-   - "Should we refactor X into Y?"
-   - Unclear requirements
-   - Trade-off decisions
-   - Performance concerns with multiple valid approaches
-
-3. For easy fixes:
-   - Dispatch fix agent with specific instructions
-   - Agent makes the fix
-   - Re-run validator for affected task
-
-4. For complex issues:
-   - Use AskUserQuestion to discuss with user
-   - Present the issue and options
-   - Implement based on user decision
-   - Or user may defer ("not now, add to backlog")
-
-5. Repeat until:
-   - No issues remain, OR
-   - All remaining issues are deferred by user
-```
+1. Collect failed task IDs from validator returns
+   (Returns are minimal: "Issues: T005 - [brief list]")
 
-## Issue Severity Guide
+2. For each failed task:
+   - Re-dispatch spec-implementer with the task path
+   - Implementer reads Review Notes and addresses issues
+   - Returns: "Task complete: T005"
 
-**Critical** - Must fix before considering complete
-- Feature doesn't work
-- UI is broken
-- Test failures
+3. Re-run spec-validator on fixed tasks
+   - Returns: "Pass: T005" or "Issues: T005 - ..."
 
-**Warning** - Should fix, but not blocking
-- Code smells (large files, unclear naming)
-- Minor UI issues
-- Missing edge case handling
+4. Repeat until:
+   - All tasks pass, OR
+   - User defers remaining issues
+```
 
-**Suggestion** - Nice to have
-- Refactoring opportunities
-- Performance optimizations
-- Style improvements
+## No Separate Fixer Agent
 
-## Dispatching Fix Agents
+The spec-implementer handles fixes. When it reads the task file:
+- If Review Notes has issues → fix mode (address those issues)
+- If Review Notes is empty → initial mode (implement from scratch)
 
-For easy fixes, dispatch a general-purpose agent:
-```
-Task(
-  subagent_type: "general-purpose",
-  prompt: "Fix this issue in {file}:
-    Problem: {issue description}
-    Expected: {what it should be}
-
-    Make the minimal fix needed.",
-  run_in_background: true
-)
-```
+The task file's Review Notes section IS the feedback mechanism.
 
-## Asking User About Complex Issues
+## When to Escalate to User
+
+Use AskUserQuestion when:
+- Same issue persists after 2+ fix attempts
+- Issue is architectural or unclear how to resolve
+- Trade-off decision needed (performance vs simplicity, etc.)
 
 ```
 AskUserQuestion(
   questions: [{
-    header: "Refactor?",
-    question: "ProductCard.tsx is 342 lines. Should we split it into smaller components?",
+    header: "Fix approach",
+    question: "T005 failed twice with: [issue]. How should we proceed?",
     options: [
-      { label: "Yes, split it", description: "Create ProductImage, ProductInfo, ProductActions components" },
-      { label: "No, keep as-is", description: "It's complex but cohesive, splitting would add indirection" },
-      { label: "Defer", description: "Add to backlog, not blocking for this milestone" }
+      { label: "Try approach A", description: "..." },
+      { label: "Try approach B", description: "..." },
+      { label: "Defer", description: "Skip for now, add to backlog" }
     ]
   }]
 )
 ```
 
-## Re-validation Loop
+## Log-Based History
+
+Each pass appends to the task file:
+- Implementer appends to Implementation Notes
+- Validator appends to Review Notes
 
-After fixes:
-1. Re-run validators ONLY on affected tasks
-2. Check if new issues introduced
-3. Repeat triage for new issues
-4. Continue until stable
+This creates a debugging trail:
+```
+Implementation Notes:
+  Pass 1: Initial implementation...
+  Pass 2: Fixed idle timer issue...
+
+Review Notes:
+  Pass 1: [critical] Timer doesn't pause...
+  Pass 2: [pass] All issues resolved
+```
 
-## Output
+## Exit Conditions
 
-- All critical issues resolved
-- Warnings addressed or deferred
-- Final validation passes
-- Spec implementation complete
+Phase completes when:
+1. All validators return "Pass: TXXX"
+2. User explicitly defers remaining issues
+3. Max retry limit reached (suggest user intervention)

package/src/skills/execute-spec/references/workflow.md

@@ -4,89 +4,71 @@
 
 ```
 PHASE 1: HYDRATE
-  Read task files → TaskCreate with dependencies
+  Run parse script → TaskCreate with dependencies
+  (NO file reading by orchestrator)
 
 PHASE 2: BUILD
-  Loop: find unblocked tasks → dispatch spec-implementer → wait for completion
+  Loop: find unblocked tasks → dispatch spec-implementer → receive minimal status
   Continue until all tasks built
 
 PHASE 3: VALIDATE
   Dispatch spec-validator for each task (all in parallel)
-  Collect findings
+  Receive pass/fail status only
 
 PHASE 4: TRIAGE
-  Group issues: easy fixes vs complex
-  Easy → dispatch fix agents
-  Complex → AskUserQuestion, discuss with user
-  Re-validate affected tasks
+  For failed tasks: re-dispatch spec-implementer
+  Re-validate
   Loop until clean or user defers
 ```
 
+## Critical: Minimal Context
+
+**Agent returns are pass/fail only.** All details go in task files.
+
+- Implementer returns: `Task complete: T005` or `Blocked: T005 - reason`
+- Validator returns: `Pass: T005` or `Issues: T005 - [brief list]`
+
+The orchestrator never reads task files. It dispatches paths and receives status.
+
 ## Phase 1: Hydrate
 
 Read `phase-1-hydrate.md` for details.
 
-1. Parse the spec path argument to find the tasks directory
-2. Read all `T*.md` files from `{spec-path}/tasks/`
-3. For each task file:
-   - Parse YAML frontmatter (id, title, status, depends_on)
-   - Create a task in the Claude Code task system using TaskCreate
-   - Set dependencies using the `depends_on` array (map to task IDs)
-4. Output: All tasks loaded into the task system with proper dependency graph
+Use the parse script to get task metadata:
+```bash
+node ~/.claude/scripts/parse-task-files.js {spec-path}
+```
+
+This returns JSON with task IDs, titles, dependencies, and paths. Create tasks from this output without reading any files.
 
 ## Phase 2: Build
 
 Read `phase-2-build.md` for details.
 
-1. Call TaskList to find pending tasks with no blockers
-2. For each unblocked task:
-   - Dispatch a `spec-implementer` agent in background:
-     ```
-     Task(
-       subagent_type: "spec-implementer",
-       prompt: "{full-path-to-task-file}",
-       run_in_background: true
-     )
-     ```
-3. Monitor for completions (agents will mark tasks complete)
-4. As tasks complete, check for newly unblocked tasks
-5. Repeat until all build tasks are complete
+1. Find unblocked tasks via TaskList
+2. Dispatch spec-implementer with just the file path
+3. Receive minimal status (pass/fail)
+4. Repeat until all built
 
 ## Phase 3: Validate
 
 Read `phase-3-validate.md` for details.
 
-1. Once all build tasks complete, dispatch validators
-2. For each task:
-   - Dispatch a `spec-validator` agent in background:
-     ```
-     Task(
-       subagent_type: "spec-validator",
-       prompt: "{full-path-to-task-file}",
-       run_in_background: true
-     )
-     ```
-3. Validators run in parallel (they create isolated browser sessions)
-4. Wait for all validators to complete
-5. Collect findings from Review Notes sections
+1. Dispatch spec-validator for each task (parallel)
+2. Receive pass/fail status
+3. Collect list of failed task IDs
 
 ## Phase 4: Triage
 
 Read `phase-4-triage.md` for details.
 
-1. Read all task files and collect Review Notes
-2. Parse issues by severity (critical, warning, suggestion)
-3. Group issues:
-   - **Easy fixes**: Clear problem, obvious solution → dispatch fix agent
-   - **Complex issues**: Ambiguous, architectural, needs discussion → AskUserQuestion
-4. After fixes, re-run validation on affected tasks
-5. Loop until:
-   - No issues remain, OR
-   - User explicitly defers remaining issues
+1. For failed tasks: re-dispatch spec-implementer (it reads Review Notes and fixes)
+2. Re-run spec-validator on fixed tasks
+3. Loop until all pass or user defers remaining issues
 
 ## Key Principles
 
-- **Parallelism**: Use `run_in_background: true` to maximize throughput
-- **Dependency respect**: Only dispatch tasks whose dependencies are complete
-- **Isolation**: Each validator gets its own browser session
-- **Full paths**: Always use full relative paths to task files so agents know exactly which spec they're implementing
+- **No file reading by orchestrator** - Hook blocks task file reads
+- **Minimal returns** - Agents return status only, details in task files
+- **Task file is source of truth** - Implementation Notes and Review Notes track all history
+- **Parallelism** - Use `run_in_background: true` where possible