function selectExecutionMode(prd) {
  const { swarm, delegation } = prd;

  if (swarm?.enabled) return 'swarm';
  if (delegation?.parallel?.enabled) return 'parallel';
  if (delegation?.enabled) return 'delegation';
  return 'sequential';
}

┌─────────────────────────────────────────────────────────────┐
│                     CORE MEMORY                              │
│  ~/.claude/memory/core-memory.json                          │
│  - Stable preferences, beliefs, patterns                     │
│  - Loaded at session start, rarely changes                   │
│  - Highest priority, always applied                          │
└─────────────────────────────────────────────────────────────┘
                              ▲
                              │ Promotion (high usage + effectiveness)
                              │
┌─────────────────────────────────────────────────────────────┐
│                   LONG-TERM MEMORY                           │
│  Memory MCP (patterns, mistakes, tech-insights)             │
│  - Cross-project learnings                                   │
│  - Subject to decay and consolidation                        │
│  - Filtered by Sensory Gate (relevance >= 5)                │
└─────────────────────────────────────────────────────────────┘
                              ▲
                              │ Sensory Filter
                              │
┌─────────────────────────────────────────────────────────────┐
│                  SHORT-TERM / SESSION                        │
│  progress.md, progress-summary.md, prd.json                 │
│  - Project-specific learnings                                │
│  - Evaluated for long-term storage at story completion      │
└─────────────────────────────────────────────────────────────┘

// First action in any phase
const coreMemory = JSON.parse(
  await readFile('~/.claude/memory/core-memory.json')
);

// Apply without asking:
// - coreMemory.preferences.packageManager → use pnpm
// - coreMemory.preferences.styling → use Tailwind + shadcn
// - coreMemory.stablePatterns → apply known patterns
// - coreMemory.beliefs → guide decision-making

function calculateRelevance(learning, existingMemories, coreMemory) {
  let score = 0;
  const reasons = [];

  // 1. NOVELTY CHECK - Duplicate? Skip entirely
  const similar = findSimilarMemories(learning, existingMemories);
  if (similar.length > 0 && similar[0].similarity > 0.85) {
    return { score: 0, reasons: ["Duplicate"], save: false };
  }
  if (similar.length > 0 && similar[0].similarity > 0.6) {
    score -= 2; // Similar exists, penalty
    reasons.push("Similar memory exists (-2)");
  }

  // 2. GENERALITY - Applies to multiple projects/frameworks?
  if (learning.appliesTo?.length > 2) {
    score += 3;
    reasons.push("Broadly applicable (+3)");
  } else if (learning.appliesTo?.length > 1) {
    score += 2;
    reasons.push("Multiple contexts (+2)");
  }

  // 3. SEVERITY - How important?
  const severityScores = { critical: 5, high: 3, medium: 2, low: 1 };
  if (learning.severity) {
    score += severityScores[learning.severity] || 1;
    reasons.push(`Severity: ${learning.severity} (+${severityScores[learning.severity]})`);
  }

  // 4. SOURCE - Learned from failure = more memorable
  if (learning.source === 'mistake' || learning.source === 'failure') {
    score += 2;
    reasons.push("Learned from failure (+2)");
  }
  if (learning.source === 'explicit_user_feedback') {
    score += 3;
    reasons.push("User explicitly shared (+3)");
  }

  // 5. FREQUENCY - Will encounter often?
  if (learning.frequencyHint === 'common') {
    score += 2;
    reasons.push("Common scenario (+2)");
  }

  const threshold = coreMemory.memoryConfig?.relevanceThreshold || 5;
  return { score, reasons, save: score >= threshold, threshold };
}

// In Step 3.4 after successful story
if (discoveredLearning) {
  const learning = {
    name: `pattern:${kebabCase(title)}`,
    entityType: 'pattern',
    observations: [details],
    appliesTo: [detectedStack], // e.g., ['nextjs', 'supabase']
    severity: 'medium',
    source: 'implementation', // or 'mistake', 'explicit_user_feedback'
    frequencyHint: 'common'   // or 'rare', 'occasional'
  };

  const relevance = calculateRelevance(learning, existingMemories, coreMemory);

  if (relevance.save) {
    // Add tracking metadata
    learning.observations.push(
      `Discovered: ${new Date().toISOString().split('T')[0]}`,
      `Relevance score: ${relevance.score}`,
      `Source: ${learning.source}`
    );

    await mcp__memory__create_entities({ entities: [learning] });

    // Create relationships to related memories
    await mcp__memory__create_relations({
      relations: [{
        from: learning.name,
        relationType: 'applies_to',
        to: `tech-insight:${detectedStack}`
      }]
    });

    console.log(`✓ Memory saved: ${learning.name} (score: ${relevance.score})`);
  } else {
    console.log(`⊘ Memory filtered: ${learning.name} (score: ${relevance.score} < ${relevance.threshold})`);
    // Consider saving to AGENTS.md instead for project-specific patterns
  }
}

// After applying a pattern from memory
await mcp__memory__add_observations({
  observations: [{
    entityName: 'pattern:early-returns',
    contents: [
      `Applied in ${storyId}: ${wasHelpful ? 'HELPFUL' : 'NOT HELPFUL'}`,
      `Context: ${storyTitle}`,
      `Last used: ${new Date().toISOString().split('T')[0]}`
    ]
  }]
});

// Session context file: ~/.claude/memory/session-context.json
{
  "currentFocus": {
    "topic": "authentication",
    "since": "2026-01-27T10:15:00Z",
    "relatedFiles": ["src/auth/*"],
    "memoriesApplied": ["pattern:supabase-rls"]
  },
  "attentionWeights": {
    "authentication": 0.95,  // Current focus = high weight
    "security": 0.70,        // Related topic
    "database": 0.40,        // Recent context
    "ui-components": 0.10    // Low relevance now
  }
}

// Update focus when starting a story
await updateFocus(story.detectedType, inferRelatedFiles(story));

// Query memories with attention weighting
const relevantMemories = await queryMemoriesWithAttention(
  `${story.title} ${story.description}`,
  sessionContext
);

// High-attention memories surface first
// Low-attention memories suppressed (reduces noise)

// After applying a memory during implementation
await trackMemoryApplication('pattern:early-returns', story.id, 'Refactoring validation logic');

// After story completion, evaluate helpfulness
await evaluateMemoryHelpfulness(story.id, {
  passed: true,
  attempts: 1,
  notes: 'Used early returns pattern, clean result'
});

// Memory gets observation: "Applied in US-005: HELPFUL"

/consolidate

ls -la prd.json progress.md tasks/*.md 2>/dev/null

mcp__memory__search_nodes({ query: "preference" })
mcp__memory__search_nodes({ query: "pattern" })
mcp__memory__search_nodes({ query: "architecture-decision" })

1. Detect stack: package.json, requirements.txt, go.mod, etc.
2. Find existing patterns: src/ structure, component patterns, API conventions
3. Check for AGENTS.md for documented patterns
4. Identify test patterns and frameworks
5. Cross-reference with memory: tech-insights for detected stack

# If Next.js detected:
mcp__memory__search_nodes({ query: "nextjs" })

# If Supabase detected:
mcp__memory__search_nodes({ query: "supabase" })

# General mistakes to avoid:
mcp__memory__search_nodes({ query: "mistake" })

I'll help you build [feature]. First, a few quick questions:

1. What's the primary goal?
   A. [Goal 1]  B. [Goal 2]  C. [Goal 3]  D. Other

2. Who's the target user?
   A. [User type 1]  B. [User type 2]  C. All users  D. Other

3. What's the scope?
   A. MVP only  B. Full-featured  C. Backend only  D. Frontend only

Reply with: "1A, 2C, 3B" (or type your own answers)

# PRD: [Feature Name]

## Overview

Brief description of the feature and its value.

## Goals

- Specific, measurable objective 1
- Specific, measurable objective 2

## Non-Goals

- Explicitly what this feature will NOT do
- Scope boundaries

## User Stories

### US-001: [Title]

**Description:** As a [user type], I want [capability] so that [benefit].

**Acceptance Criteria:**

- [ ] Specific, verifiable criterion
- [ ] Another testable criterion
- [ ] Typecheck passes
- [ ] Tests pass (if applicable)

### US-002: [Title]

...

## Technical Approach

- Key architectural decisions
- Integration points with existing code
- Dependencies between stories

## Success Metrics

How we'll know this feature is working correctly.

## Complexity Report

**Total stories:** [N]
**Total complexity points:** [sum of all scores]

### Distribution
- Simple (1-3):  [X] stories
- Moderate (4-6): [Y] stories
- Complex (7-10): [Z] stories

### High-Risk Stories (complexity ≥ 7)
| ID | Title | Score | Risk Factors |
|----|-------|-------|--------------|
| US-005 | Add OAuth login | 8 | External API, security, multi-layer |
| US-008 | Database migration | 7 | Data integrity, downtime risk |

### Recommendations
- **US-005:** Consider splitting into: token handling, UI flow, callback endpoint
- **US-008:** Add rollback plan to acceptance criteria

### Estimated Iterations
Based on complexity: [N-M] iterations (assuming ~1 iteration per 3-4 complexity points)

I've created the PRD at `tasks/prd-[feature-name].md`.

Summary:
- [N] user stories identified
- Total complexity: [X] points ([Low/Medium/High] average)
- High-risk stories: [list any ≥7]
- Key dependencies: [list]

Please review the PRD. Reply with:
- "approved" - Convert to prd.json and begin implementation
- "edit [story]" - Modify a specific story
- "add [story]" - Add a new story
- "expand [story]" - Break a complex story into smaller pieces
- "questions" - Ask me anything about the approach

# If prd.json exists with different branch
if [ -f prd.json ]; then
  BRANCH=$(jq -r '.branchName' prd.json)
  if [ "$BRANCH" != "current-branch-name" ]; then
    mkdir -p archive/$(date +%Y-%m-%d)-$BRANCH
    mv prd.json progress.md archive/$(date +%Y-%m-%d)-$BRANCH/
  fi
fi

git checkout -b feature/[feature-name]

# Check if worktree-scaffold config exists
if [ -f .worktree-scaffold.json ]; then
  # Read config
  WORKTREE_DIR=$(jq -r '.worktreeDir // "../"' .worktree-scaffold.json)
  BRANCH_PREFIX=$(jq -r '.branchPrefix // "feature/"' .worktree-scaffold.json)

  # Feature name without prefix
  FEATURE_NAME="${BRANCH_NAME#${BRANCH_PREFIX}}"
  WORKTREE_PATH="${WORKTREE_DIR}${FEATURE_NAME}"

  # Create worktree
  git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

  # Run scaffolding if configured
  SCAFFOLD_TYPE=$(jq -r '.defaultScaffold // "default"' .worktree-scaffold.json)
  # Generate scaffold files based on config templates

  echo "Worktree created at: $WORKTREE_PATH"
  echo "Continuing autonomous loop in worktree..."
  cd "$WORKTREE_PATH"
fi

{
  "worktree": {
    "enabled": true,
    "path": "../feature-name",
    "mainRepoPath": "/original/repo/path"
  }
}

{
  "project": "[Project Name]",
  "branchName": "feature/[feature-name]",
  "description": "[Feature description]",
  "createdAt": "2024-01-15T10:00:00Z",
  "delegation": {
    "enabled": false,
    "fallbackToDirect": true,
    "parallel": {
      "enabled": false,
      "maxConcurrent": 3,
      "conflictResolution": "sequential"
    }
  },
  "delegationMetrics": {
    "totalStories": 0,
    "delegatedCount": 0,
    "directCount": 0,
    "successRate": 0,
    "avgAttempts": 0,
    "byAgent": {},
    "byType": {},
    "detectionAccuracy": null
  },
  "optimization": {
    "progressSummary": {
      "enabled": true,
      "recentStoriesCount": 3,
      "maxLearnings": 15,
      "autoGenerate": true
    }
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "[Title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Specific criterion 1",
        "Typecheck passes",
        "Tests pass"
      ],
      "priority": 1,
      "complexity": 4,
      "complexityFactors": ["API endpoint", "database query"],
      "dependsOn": [],
      "status": "pending",
      "passes": false,
      "attempts": 0,
      "notes": "",
      "detectedType": null,
      "delegatedTo": null
    }
  ]
}

function isBlocked(story, allStories) {
  if (!story.dependsOn || story.dependsOn.length === 0) return false;
  return story.dependsOn.some(depId => {
    const dep = allStories.find(s => s.id === depId);
    return dep && !dep.passes;
  });
}

**Delegation Configuration:**

- `delegation.enabled`: Set to `true` to enable smart delegation to specialized agents
- `delegation.fallbackToDirect`: If `true`, falls back to direct implementation when delegation fails
- `delegation.parallel.enabled`: Set to `true` to enable parallel execution of independent stories
- `delegation.parallel.maxConcurrent`: Maximum number of agents to run concurrently (default: 3)
- `delegation.parallel.conflictResolution`: How to handle file conflicts - `"sequential"` (safe) or `"optimistic"` (faster)
- `detectedType`: Automatically populated with story type (frontend, api, database, devops, fullstack, general)
- `delegatedTo`: Records which agent implemented the story (e.g., "frontend-agent", "api-agent", or null for direct implementation)

**Swarm Configuration (Advanced):**

Add swarm configuration for TeammateTool-based multi-agent orchestration:

```json
{
  "swarm": {
    "enabled": false,
    "teamName": "feature-{branchName}",
    "workers": {
      "autoSpawn": true,
      "types": ["frontend", "api", "database"],
      "maxWorkers": 5,
      "workerTimeout": 300000
    },
    "coordination": {
      "useSharedTaskBoard": true,
      "inboxPollingInterval": 5000,
      "idleTimeout": 60000
    },
    "spawnBackend": "auto"
  },
  "swarmMetrics": {
    "totalBatches": 0,
    "workerSpawns": 0,
    "messagesExchanged": 0,
    "avgBatchDuration": 0,
    "speedupVsSequential": 0,
    "workerStats": {}
  }
}

{
  "optimization": {
    "progressSummary": {
      "enabled": false
    }
  }
}

function updateDelegationMetrics(prd, story) {
  const metrics = prd.delegationMetrics || {
    totalStories: 0, delegatedCount: 0, directCount: 0,
    successRate: 0, avgAttempts: 0, byAgent: {}, byType: {}
  };

  // Update totals
  metrics.totalStories++;
  if (story.delegatedTo) {
    metrics.delegatedCount++;
  } else {
    metrics.directCount++;
  }

  // Update by-agent breakdown
  const agentKey = story.delegatedTo || 'direct';
  if (!metrics.byAgent[agentKey]) {
    metrics.byAgent[agentKey] = { count: 0, successRate: 0, avgAttempts: 0 };
  }
  metrics.byAgent[agentKey].count++;

  // Update by-type breakdown
  if (story.detectedType) {
    metrics.byType[story.detectedType] = (metrics.byType[story.detectedType] || 0) + 1;
  }

  // Calculate overall success rate (first attempt pass)
  const allStories = prd.userStories.filter(s => s.passes);
  const firstAttemptSuccess = allStories.filter(s => s.attempts === 1).length;
  metrics.successRate = Math.round((firstAttemptSuccess / allStories.length) * 100);

  // Calculate average attempts
  const totalAttempts = allStories.reduce((sum, s) => sum + s.attempts, 0);
  metrics.avgAttempts = (totalAttempts / allStories.length).toFixed(2);

  prd.delegationMetrics = metrics;
}

# Overall delegation rate
jq '.delegationMetrics | "Delegation: \(.delegatedCount)/\(.totalStories) (\((.delegatedCount/.totalStories*100)|round)%)"' prd.json

# Agent performance
jq '.delegationMetrics.byAgent | to_entries | .[] | "\(.key): \(.value.count) stories, \(.value.successRate)% success"' prd.json

# Most common story types
jq '.delegationMetrics.byType | to_entries | sort_by(-.value) | .[] | "\(.key): \(.value)"' prd.json

# Success rate trend
jq '.delegationMetrics | "Success rate: \(.successRate)% | Avg attempts: \(.avgAttempts)"' prd.json

# Progress Log: [Feature Name]

Branch: `feature/[feature-name]`
Started: [Date]

---

# Check for common patterns
grep -l "typecheck\|tsc\|type-check" package.json 2>/dev/null
grep -l "test\|jest\|vitest\|pytest" package.json pyproject.toml 2>/dev/null
grep -l "lint\|eslint" package.json 2>/dev/null

{
  "verification": {
    "typecheck": "npm run typecheck",
    "test": "npm run test",
    "lint": "npm run lint",
    "build": "npm run build"
  }
}

# Read current state
cat prd.json
cat AGENTS.md 2>/dev/null

# Use optimized progress loading (see below)

function loadProgressContext(prd) {
  const optimization = prd.optimization?.progressSummary ?? { enabled: true };

  // 1. Check if summary exists and optimization is enabled
  if (optimization.enabled && fileExists('progress-summary.md')) {
    const summaryMtime = getModifiedTime('progress-summary.md');
    const progressMtime = getModifiedTime('progress.md');

    // Use summary if it's fresh (newer than progress.md)
    if (summaryMtime >= progressMtime) {
      return readFile('progress-summary.md');  // ~400-800 tokens
    }
  }

  // 2. Fallback: Extract recent entries from progress.md
  const recentCount = optimization.recentStoriesCount || 3;
  return extractRecentEntries(readFile('progress.md'), recentCount);
}

# Query memory for relevant insights based on detected tech stack
mcp__memory__search_nodes({ query: "[detected-framework]" })  # e.g., "nextjs", "fastapi"
mcp__memory__search_nodes({ query: "mistake" })               # Avoid past mistakes
mcp__memory__search_nodes({ query: "pattern" })               # Apply known patterns

function getNextStory(prd) {
  const stories = prd.userStories;

  // Update blocked status for all stories
  stories.forEach(story => {
    if (story.passes || story.status === 'skipped') return;

    const blocked = story.dependsOn?.some(depId => {
      const dep = stories.find(s => s.id === depId);
      return dep && !dep.passes;
    });

    story.status = blocked ? 'blocked' : 'pending';
  });

  // Find first non-blocked, non-completed story by priority
  return stories
    .filter(s => !s.passes && s.status !== 'blocked' && s.status !== 'skipped')
    .sort((a, b) => a.priority - b.priority)[0] || null;
}

const nextStory = getNextStory(prd);

if (!nextStory) {
  const blocked = prd.userStories.filter(s => s.status === 'blocked');
  if (blocked.length > 0) {
    console.log(`⚠ ${blocked.length} stories are blocked:`);
    blocked.forEach(s => {
      const deps = s.dependsOn.filter(id =>
        !prd.userStories.find(x => x.id === id)?.passes
      );
      console.log(`  - ${s.id}: waiting on ${deps.join(', ')}`);
    });
  }
}

⚠ 2 stories are blocked:
  - US-004: waiting on US-002, US-003
  - US-006: waiting on US-005

Next available: US-002 (priority 2, complexity 5)

function detectStoryType(story) {
  const fullText = [
    story.title,
    story.description,
    ...story.acceptanceCriteria,
    story.notes || ''
  ].join(' ').toLowerCase();

  const signals = {
    frontend: 0,
    backend: 0,
    api: 0,
    database: 0,
    devops: 0,
    fullstack: 0
  };

  // Frontend patterns
  const frontendPatterns = [
    /\b(component|ui|page|form|button|modal|dropdown|layout|widget)\b/,
    /\b(react|vue|angular|svelte|next\.js|nuxt)\b/,
    /\b(css|style|theme|responsive|mobile|desktop)\b/,
    /\b(click|hover|animation|transition|render)\b/,
    /\/(components|pages|app|views|layouts)\//,
    /\.(tsx|jsx|vue|svelte)$/
  ];

  // API patterns
  const apiPatterns = [
    /\b(endpoint|route|api|rest|graphql)\b/,
    /\b(get|post|put|delete|patch)\s+(request|endpoint)/,
    /\b(middleware|authentication|authorization)\b/,
    /\b(controller|service|handler)\b/,
    /\/(api|routes|controllers|services)\//,
    /\b(express|fastapi|flask|django|nestjs)\b/
  ];

  // Database patterns
  const databasePatterns = [
    /\b(database|schema|migration|table|column|index)\b/,
    /\b(query|sql|postgres|mysql|mongodb|supabase)\b/,
    /\b(orm|prisma|drizzle|sequelize|mongoose)\b/,
    /\b(rls|row level security|foreign key|constraint)\b/,
    /\/(migrations|schema|models|entities)\//,
    /\b(create table|alter table|add column)\b/
  ];

  // DevOps patterns
  const devopsPatterns = [
    /\b(deploy|deployment|ci\/cd|docker|kubernetes|container)\b/,
    /\b(github actions|gitlab ci|jenkins|vercel|railway)\b/,
    /\b(environment variable|config|secrets|env)\b/,
    /\b(build|bundle|webpack|vite|rollup)\b/,
    /\.(dockerfile|yaml|yml|\.github\/workflows)$/,
    /\b(nginx|apache|load balancer|cdn)\b/
  ];

  // Fullstack patterns (touches multiple layers)
  const fullstackPatterns = [
    /\b(end.to.end|e2e|full.stack|complete feature)\b/,
    /\b(authentication system|oauth flow|signup flow)\b/,
    /\b(frontend.*backend|backend.*frontend)\b/,
    /\b(database.*ui|ui.*database)\b/
  ];

  // Score each category
  frontendPatterns.forEach(p => { if (p.test(fullText)) signals.frontend++; });
  apiPatterns.forEach(p => { if (p.test(fullText)) signals.api++; });
  databasePatterns.forEach(p => { if (p.test(fullText)) signals.database++; });
  devopsPatterns.forEach(p => { if (p.test(fullText)) signals.devops++; });
  fullstackPatterns.forEach(p => { if (p.test(fullText)) signals.fullstack++; });

  // API is subset of backend
  if (signals.api > 0) signals.backend = signals.api;

  // Determine primary type
  const maxScore = Math.max(...Object.values(signals));

  if (signals.fullstack >= 2) return 'fullstack';
  if (maxScore === 0) return 'general'; // No clear signals

  // Return highest scoring type (priority order if tied)
  const priority = ['database', 'api', 'backend', 'frontend', 'devops'];
  for (const type of priority) {
    if (signals[type] === maxScore) {
      return type;
    }
  }

  return 'general';
}

## Starting: US-003 - Add user profile API endpoint

Story type detected: api
Detection signals: { api: 3, backend: 3, frontend: 0, database: 0, devops: 0 }

**Goal:** Create GET /api/users/:id endpoint

**Acceptance Criteria:**
- [ ] Returns user object with id, name, email
- [ ] Returns 404 if not found
- [ ] Returns 401 if not authenticated
- [ ] Typecheck passes
- [ ] Tests pass

**Approach:** Create new API route handler in app/api/users/[id]/route.ts...

function getIndependentStories(prd) {
  const allStories = prd.userStories;

  return allStories.filter(story => {
    // Skip completed or in-progress stories
    if (story.passes || story.status === 'in_progress') return false;

    // Skip blocked stories
    if (story.status === 'blocked') return false;

    // Check dependencies are all complete
    if (story.dependsOn && story.dependsOn.length > 0) {
      const hasUncompletedDeps = story.dependsOn.some(depId => {
        const dep = allStories.find(s => s.id === depId);
        return dep && !dep.passes;
      });
      if (hasUncompletedDeps) return false;
    }

    return true;
  });
}

const readyStories = getIndependentStories(prd);
console.log(`Found ${readyStories.length} independent stories`);

function detectPotentialConflicts(stories) {
  const conflicts = [];

  // Infer likely file paths from story content
  const storyFiles = stories.map(story => ({
    id: story.id,
    files: inferAffectedFiles(story)
  }));

  // Check for overlapping files
  for (let i = 0; i < storyFiles.length; i++) {
    for (let j = i + 1; j < storyFiles.length; j++) {
      const overlap = storyFiles[i].files.filter(f =>
        storyFiles[j].files.some(f2 => filesOverlap(f, f2))
      );

      if (overlap.length > 0) {
        conflicts.push({
          stories: [storyFiles[i].id, storyFiles[j].id],
          files: overlap
        });
      }
    }
  }

  return conflicts;
}

function selectParallelBatch(readyStories, conflicts, maxConcurrent) {
  const batch = [];
  const usedFiles = new Set();

  for (const story of readyStories) {
    if (batch.length >= maxConcurrent) break;

    // Check if this story conflicts with already-selected stories
    const storyFiles = inferAffectedFiles(story);
    const hasConflict = storyFiles.some(f =>
      [...usedFiles].some(uf => filesOverlap(f, uf))
    );

    if (!hasConflict) {
      batch.push(story);
      storyFiles.forEach(f => usedFiles.add(f));
    }
  }

  return batch;
}

const parallelBatch = selectParallelBatch(
  readyStories,
  conflicts,
  prd.delegation.parallel.maxConcurrent || 3
);

if (parallelBatch.length > 1) {
  // Proceed to Step 3.1-parallel (Parallel Execution)
  console.log(`Parallel execution: ${parallelBatch.length} stories`);
} else {
  // Proceed to Step 3.1 (Sequential Execution)
  console.log(`Sequential execution: 1 story`);
}

## Parallel Execution: Starting ${parallelBatch.length} stories

| ID | Title | Type | Agent |
|----|-------|------|-------|
| US-003 | Add dark mode toggle | frontend | frontend-agent |
| US-004 | Create profile API | api | api-agent |
| US-005 | Add email column | database | database-agent |

Potential conflicts: None
Max concurrent: 3

Launching agents...

const prompts = parallelBatch.map(story => ({
  story,
  type: detectStoryType(story),
  agent: selectAgent(detectStoryType(story)),
  prompt: generateSubagentPrompt(story, prd, progress, agentsMd, memoryInsights)
}));

// CRITICAL: All Task calls must be in a SINGLE message for true parallelism
// The orchestrator sends one message with multiple Task tool invocations

const taskCalls = prompts.map(({ story, agent, prompt }) => ({
  tool: 'Task',
  params: {
    subagent_type: agent,
    description: `Implement ${story.id}: ${story.title}`,
    prompt: prompt
  }
}));

// These execute concurrently because they're in the same message
const results = await executeAllTasks(taskCalls);

const outcomes = results.map((result, i) => {
  const story = prompts[i].story;
  const parsed = parseSubagentResult(result);
  const validation = validateSubagentResult(parsed, story);

  return {
    story,
    agent: prompts[i].agent,
    result: parsed,
    success: validation.valid && parsed.success
  };
});

const successes = outcomes.filter(o => o.success);
const failures = outcomes.filter(o => !o.success);

console.log(`Results: ${successes.length} succeeded, ${failures.length} failed`);

# Typecheck covers all parallel changes
npm run typecheck

# Run full test suite
npm run test

for (const outcome of successes) {
  // Stage only this story's files
  git.add(outcome.result.filesChanged);

  // Atomic commit per story
  git.commit(`feat(${outcome.story.id}): ${outcome.story.title}

  - Implemented by: ${outcome.agent}
  - Parallel batch: ${parallelBatch.map(s => s.id).join(', ')}
  `);

  // Update prd.json
  updateStory(outcome.story.id, {
    passes: true,
    attempts: outcome.story.attempts + 1,
    completedAt: new Date().toISOString(),
    delegatedTo: outcome.agent
  });
}

for (const outcome of failures) {
  console.log(`⚠ ${outcome.story.id} failed`);

  // Revert partial changes
  git.checkout(outcome.result.filesChanged);

  // Queue for retry
  updateStory(outcome.story.id, {
    attempts: outcome.story.attempts + 1,
    lastError: outcome.result.notes
  });
}

## Parallel Batch Complete

**Duration:** 2m 34s (vs ~7m sequential)
**Successes:** US-003, US-004, US-005
**Failures:** None

### US-003: Add dark mode toggle (frontend-agent)
- Files: components/ThemeToggle.tsx, app/settings/page.tsx
- Notes: Used existing ThemeProvider pattern

### US-004: Create profile API (api-agent)
- Files: app/api/users/[id]/route.ts
- Notes: Added auth middleware

### US-005: Add email column (database-agent)
- Files: db/migrations/20260125_add_email.sql
- Notes: Included rollback migration

// Check if more stories are ready
const remainingStories = prd.userStories.filter(s => !s.passes);

if (remainingStories.length === 0) {
  console.log('===== FEATURE COMPLETE =====');
} else {
  // Next iteration will re-evaluate parallel candidates
  console.log(`${remainingStories.length} stories remaining. Continuing...`);
}

// Create team infrastructure
const teamName = prd.swarm.teamName.replace('{branchName}', prd.branchName);

await TeammateTool({
  operation: 'spawnTeam',
  team_name: teamName
});

console.log(`Team created: ${teamName}`);

~/.claude/teams/{teamName}/
├── inboxes/
│   ├── leader.json        # Leader's inbox
│   ├── frontend-worker.json
│   ├── api-worker.json
│   └── database-worker.json
└── state.json             # Team state

// Create tasks for all pending stories
for (const story of prd.userStories.filter(s => !s.passes)) {
  await TaskCreate({
    subject: `${story.id}: ${story.title}`,
    description: generateTaskDescription(story),
    activeForm: `Implementing ${story.id}`,
    metadata: {
      storyId: story.id,
      type: story.detectedType || detectStoryType(story),
      complexity: story.complexity,
      acceptanceCriteria: story.acceptanceCriteria,
      verification: prd.verification
    }
  });
}

// Set up dependencies
for (const story of prd.userStories) {
  if (story.dependsOn?.length > 0) {
    const taskId = getTaskIdForStory(story.id);
    const blockedByIds = story.dependsOn.map(id => getTaskIdForStory(id));

    await TaskUpdate({
      taskId,
      addBlockedBy: blockedByIds
    });
  }
}

console.log(`Created ${prd.userStories.length} tasks on shared board`);

function generateTaskDescription(story) {
  return `
## Story: ${story.title}

${story.description}

## Acceptance Criteria
${story.acceptanceCriteria.map(c => `- [ ] ${c}`).join('\n')}

## Instructions
1. Read relevant existing code first
2. Implement ONLY this story - do not touch other stories
3. Run verification commands
4. Report results via Teammate.write() to leader

## Verification Commands
- Typecheck: \`${prd.verification?.typecheck || 'npm run typecheck'}\`
- Test: \`${prd.verification?.test || 'npm run test'}\`
- Lint: \`${prd.verification?.lint || 'npm run lint'}\`

## Required Output Format
Send to leader via TeammateTool.write():
\`\`\`json
{
  "type": "task_completed",
  "taskId": "${story.id}",
  "result": "SUCCESS|FAILURE",
  "filesChanged": ["path/to/file.ts"],
  "verification": {
    "typecheck": "PASS|FAIL",
    "test": "PASS|FAIL",
    "lint": "PASS|FAIL"
  },
  "notes": "Implementation summary",
  "learnings": "Patterns discovered"
}
\`\`\`
`;
}

// Determine which worker types are needed
const storyTypes = [...new Set(
  prd.userStories
    .filter(s => !s.passes)
    .map(s => s.detectedType || detectStoryType(s))
)];

const workersToSpawn = storyTypes
  .filter(type => prd.swarm.workers.types.includes(type))
  .slice(0, prd.swarm.workers.maxWorkers);

console.log(`Spawning ${workersToSpawn.length} specialist workers: ${workersToSpawn.join(', ')}`);

// Spawn each worker as a persistent teammate
for (const workerType of workersToSpawn) {
  await Task({
    team_name: teamName,
    name: `${workerType}-worker`,
    subagent_type: getAgentType(workerType),
    run_in_background: true,
    prompt: generateWorkerPrompt(workerType, teamName, prd)
  });
}

function generateWorkerPrompt(workerType, teamName, prd) {
  return `
# ${workerType.toUpperCase()} Worker Agent

You are a specialist ${workerType} worker in team "${teamName}".

## Your Role
Implement ${workerType}-related tasks from the shared task board.

## Your Specialty
${getWorkerSpecialty(workerType)}

## Workflow Loop

Repeat until no matching tasks remain:

1. **Check for tasks:**
   \`\`\`
   TaskList()
   \`\`\`

2. **Find a task matching your specialty:**
   - Look for tasks with type "${workerType}" in metadata
   - Task must be status "pending" with no owner
   - Task must not be blocked (blockedBy is empty or all resolved)

3. **Claim the task:**
   \`\`\`
   TaskUpdate({
     taskId: "X",
     status: "in_progress",
     owner: "${workerType}-worker"
   })
   \`\`\`

4. **Implement the story:**
   - Read the task description for acceptance criteria
   - Read relevant existing code
   - Make minimal, focused changes
   - Run verification commands

5. **Report completion:**
   \`\`\`
   TaskUpdate({ taskId: "X", status: "completed" })

   TeammateTool({
     operation: "write",
     team_name: "${teamName}",
     target: "leader",
     message: {
       type: "task_completed",
       taskId: "X",
       result: "SUCCESS",
       filesChanged: [...],
       verification: {...},
       notes: "..."
     }
   })
   \`\`\`

6. **Commit the work:**
   \`\`\`bash
   git add -A
   git commit -m "feat(STORY-ID): Title"
   \`\`\`

7. **Continue to next task** or signal idle if none available:
   \`\`\`
   TeammateTool({
     operation: "write",
     team_name: "${teamName}",
     target: "leader",
     message: { type: "idle_notification", worker: "${workerType}-worker" }
   })
   \`\`\`

## Project Context

**Tech Stack:** ${detectStack()}
**Branch:** ${prd.branchName}
**Working Directory:** ${process.cwd()}

## Repository Patterns
${readFile('AGENTS.md') || 'Follow existing code patterns'}

## Important Rules
- ONLY work on tasks matching your specialty (${workerType})
- NEVER implement tasks assigned to other workers
- ALWAYS run verification before reporting completion
- ALWAYS commit after successful implementation
- If stuck for 2+ attempts, message leader for help
`;
}

function getWorkerSpecialty(type) {
  const specialties = {
    frontend: `
- React/Vue/Svelte components
- CSS/Tailwind styling
- Client-side state management
- UI interactions and animations
- Pages and layouts`,
    api: `
- REST/GraphQL endpoints
- Request/response handling
- Authentication middleware
- Input validation
- Error handling`,
    database: `
- Schema migrations
- Database queries
- ORM models (Prisma/Drizzle/SQLAlchemy)
- Indexes and constraints
- Data integrity`,
    backend: `
- Server-side logic
- Background jobs
- External API integrations
- Business logic
- Services and utilities`,
    devops: `
- CI/CD pipelines
- Docker configuration
- Deployment scripts
- Environment variables
- Infrastructure as code`
  };
  return specialties[type] || 'General development tasks';
}

async function leaderMonitoringLoop(teamName, prd) {
  const startTime = Date.now();
  const idleWorkers = new Set();
  const completedTasks = new Set();

  while (true) {
    // 1. Check task board status
    const tasks = await TaskList();
    const pending = tasks.filter(t => t.status === 'pending' && !t.owner);
    const inProgress = tasks.filter(t => t.status === 'in_progress');
    const completed = tasks.filter(t => t.status === 'completed');

    console.log(`Tasks: ${completed.length}/${tasks.length} complete, ${inProgress.length} in progress`);

    // 2. Check inbox for worker messages
    const messages = await checkLeaderInbox(teamName);

    for (const msg of messages) {
      switch (msg.type) {
        case 'task_completed':
          await handleTaskCompletion(msg, prd);
          completedTasks.add(msg.taskId);
          idleWorkers.delete(msg.from);
          break;

        case 'task_failed':
          await handleTaskFailure(msg, prd);
          break;

        case 'idle_notification':
          idleWorkers.add(msg.worker);
          break;

        case 'help_request':
          await handleHelpRequest(msg, prd);
          break;
      }
    }

    // 3. Check for completion
    if (pending.length === 0 && inProgress.length === 0) {
      console.log('All tasks complete!');
      break;
    }

    // 4. Check for stalled workers
    if (idleWorkers.size === workersToSpawn.length && pending.length > 0) {
      console.log('All workers idle but tasks remain - rebalancing...');
      await rebalanceWorkers(teamName, pending);
    }

    // 5. Timeout check
    if (Date.now() - startTime > prd.swarm.workers.workerTimeout * 2) {
      console.log('Swarm timeout reached - shutting down');
      break;
    }

    // 6. Wait before next poll
    await sleep(prd.swarm.coordination.inboxPollingInterval);
  }

  // Update metrics
  prd.swarmMetrics.totalBatches++;
  prd.swarmMetrics.avgBatchDuration = calculateAvgDuration(prd);

  return { completed: completedTasks.size, total: tasks.length };
}

async function handleTaskCompletion(msg, prd) {
  // Update prd.json
  const story = prd.userStories.find(s => s.id === msg.taskId);
  if (story) {
    story.passes = msg.result === 'SUCCESS';
    story.completedAt = new Date().toISOString();
    story.attempts = (story.attempts || 0) + 1;
    story.delegatedTo = msg.from;
    story.notes = msg.notes;
  }

  // Update progress.md
  await appendToProgress(`
## ${new Date().toISOString()} - ${msg.taskId}: Completed by ${msg.from}

**Result:** ${msg.result}
**Files:** ${msg.filesChanged?.join(', ') || 'None reported'}
**Verification:** ${JSON.stringify(msg.verification)}

**Notes:** ${msg.notes}
**Learnings:** ${msg.learnings || 'None'}

---
`);

  // Update swarm metrics
  prd.swarmMetrics.messagesExchanged++;
  if (!prd.swarmMetrics.workerStats[msg.from]) {
    prd.swarmMetrics.workerStats[msg.from] = { completed: 0, failed: 0 };
  }
  prd.swarmMetrics.workerStats[msg.from].completed++;

  console.log(`✓ ${msg.taskId} completed by ${msg.from}`);
}

async function shutdownSwarm(teamName, prd) {
  console.log('Initiating swarm shutdown...');

  // 1. Request shutdown from all workers
  const workers = Object.keys(prd.swarmMetrics.workerStats);

  for (const worker of workers) {
    await TeammateTool({
      operation: 'requestShutdown',
      team_name: teamName,
      target: worker
    });
  }

  // 2. Wait for acknowledgments (with timeout)
  const shutdownTimeout = 30000;
  const startTime = Date.now();
  const acknowledged = new Set();

  while (acknowledged.size < workers.length) {
    if (Date.now() - startTime > shutdownTimeout) {
      console.log('Shutdown timeout - forcing cleanup');
      break;
    }

    const messages = await checkLeaderInbox(teamName);
    for (const msg of messages) {
      if (msg.type === 'shutdown_approved') {
        acknowledged.add(msg.from);
        console.log(`${msg.from} acknowledged shutdown`);
      }
    }

    await sleep(1000);
  }

  // 3. Cleanup team resources
  await TeammateTool({
    operation: 'cleanup',
    team_name: teamName
  });

  // 4. Calculate final metrics
  const totalStories = prd.userStories.length;
  const completedStories = prd.userStories.filter(s => s.passes).length;
  const sequentialEstimate = totalStories * 3; // ~3 min per story
  const actualDuration = (Date.now() - prd.swarmMetrics.startTime) / 60000;

  prd.swarmMetrics.speedupVsSequential = (sequentialEstimate / actualDuration).toFixed(2);

  console.log(`
===== SWARM COMPLETE =====

Team: ${teamName}
Stories: ${completedStories}/${totalStories} complete
Duration: ${actualDuration.toFixed(1)} min
Speedup: ${prd.swarmMetrics.speedupVsSequential}x vs sequential

Worker Stats:
${Object.entries(prd.swarmMetrics.workerStats)
  .map(([w, s]) => `  ${w}: ${s.completed} completed, ${s.failed} failed`)
  .join('\n')}
`);

  return {
    success: completedStories === totalStories,
    completed: completedStories,
    total: totalStories,
    speedup: prd.swarmMetrics.speedupVsSequential
  };
}

async function handleWorkerCrash(workerName, teamName, prd) {
  console.log(`Worker ${workerName} appears to have crashed`);

  // 1. Find tasks owned by this worker
  const tasks = await TaskList();
  const orphanedTasks = tasks.filter(t =>
    t.owner === workerName && t.status === 'in_progress'
  );

  // 2. Release orphaned tasks
  for (const task of orphanedTasks) {
    await TaskUpdate({
      taskId: task.id,
      status: 'pending',
      owner: null
    });
    console.log(`Released task ${task.id} back to pool`);
  }

  // 3. Optionally respawn the worker
  if (prd.swarm.workers.autoSpawn) {
    const workerType = workerName.replace('-worker', '');
    await Task({
      team_name: teamName,
      name: workerName,
      subagent_type: getAgentType(workerType),
      run_in_background: true,
      prompt: generateWorkerPrompt(workerType, teamName, prd)
    });

    prd.swarmMetrics.workerSpawns++;
    console.log(`Respawned ${workerName}`);
  }
}

async function handleTaskFailure(msg, prd) {
  const story = prd.userStories.find(s => s.id === msg.taskId);
  if (!story) return;

  story.attempts = (story.attempts || 0) + 1;
  story.lastError = msg.error;

  // Record failure in metrics
  if (!prd.swarmMetrics.workerStats[msg.from]) {
    prd.swarmMetrics.workerStats[msg.from] = { completed: 0, failed: 0 };
  }
  prd.swarmMetrics.workerStats[msg.from].failed++;

  if (story.attempts >= 3) {
    // Escalate to leader
    console.log(`Task ${msg.taskId} failed 3 times - escalating to leader`);

    // Mark as needs-help
    await TaskUpdate({
      taskId: msg.taskId,
      status: 'pending',
      owner: null,
      metadata: { needsHelp: true, lastError: msg.error }
    });

    // Leader will handle directly or ask user
  } else {
    // Release back to pool for retry
    await TaskUpdate({
      taskId: msg.taskId,
      status: 'pending',
      owner: null
    });
    console.log(`Task ${msg.taskId} released for retry (attempt ${story.attempts})`);
  }
}

## Starting: US-[XXX] - [Title]

**Goal:** [One-line description]

**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Typecheck passes

**Approach:** [2-3 sentences on how you'll implement this]

const delegationEnabled = prd.delegation?.enabled === true;
const fallbackToDirect = prd.delegation?.fallbackToDirect !== false;

# Run typecheck
npm run typecheck

# Run tests (if applicable to this story)
npm run test

# Run lint (optional but recommended)
npm run lint

 writeFile('progress-summary.md', summary);

**Helper Functions:**

```javascript
function generateCompletionStatus(prd) {
  const total = prd.userStories.length;
  const complete = prd.userStories.filter(s => s.passes).length;
  const inProgress = prd.userStories.find(s => !s.passes && s.attempts > 0);
  const pct = Math.round((complete / total) * 100);

  return `Stories: ${complete}/${total} complete (${pct}%)
Current: ${inProgress ? `${inProgress.id} (attempt ${inProgress.attempts})` : 'None'}
Blocked: None`;
}

function generateStoryTable(prd) {
  const header = '| ID | Title | C | Status | Attempts |\n|----|-------|---|--------|----------|';
  const rows = prd.userStories.map(s => {
    const statusIcon = s.passes ? '✓' :
                       s.status === 'blocked' ? '⊘' :
                       s.status === 'expanded' ? '↳' :
                       s.attempts > 0 ? '→' : '○';
    const complexity = s.complexity || '-';
    const title = s.title.length > 25 ? s.title.slice(0, 22) + '...' : s.title;
    return `| ${s.id} | ${title} | ${complexity} | ${statusIcon} | ${s.attempts} |`;
  });
  return [header, ...rows].join('\n') + '\n\nLegend: ✓ done, → active, ○ pending, ⊘ blocked, ↳ expanded\nC = Complexity (1-10)';
}

function extractKeyLearnings(progressMd, maxLearnings) {
  const learnings = { patterns: [], gotchas: [], dependencies: [] };

  // Extract from **Learnings:** sections
  const learningBlocks = progressMd.match(/\*\*Learnings:\*\*\n((?:- .+\n?)+)/g) || [];
  learningBlocks.forEach(block => {
    const lines = block.match(/- .+/g) || [];
    lines.forEach(line => {
      const text = line.replace(/^- /, '').trim();
      if (/gotcha|warning|careful|must|don't|avoid/i.test(text)) {
        learnings.gotchas.push(text);
      } else {
        learnings.patterns.push(text);
      }
    });
  });

  // Deduplicate and limit
  const uniquePatterns = [...new Set(learnings.patterns)].slice(0, maxLearnings);
  const uniqueGotchas = [...new Set(learnings.gotchas)].slice(0, 5);

  let output = '### Repository Patterns\n';
  output += uniquePatterns.map(p => `- ${p}`).join('\n') || '- No patterns extracted yet';
  output += '\n\n### Gotchas & Warnings\n';
  output += uniqueGotchas.map(g => `- ${g}`).join('\n') || '- No gotchas recorded';

  return output;
}

function extractRecentEntries(progressMd, count) {
  // Split by story headers (## YYYY-MM-DD or ## timestamp)
  const entries = progressMd.split(/(?=^## \d{4}-\d{2}-\d{2}|\n---\n\n## )/m);

  // Take last N entries (skip header)
  const recent = entries.filter(e => e.match(/^## \d/)).slice(-count);

  if (recent.length === 0) return 'No completed stories yet.';

  // Compress each entry (keep first 10 lines max)
  return recent.map(entry => {
    const lines = entry.trim().split('\n');
    if (lines.length <= 12) return entry.trim();
    return lines.slice(0, 12).join('\n') + '\n[...]';
  }).join('\n\n');
}

const remaining = stories.filter((s) => !s.passes);
if (remaining.length === 0) {
  // All done!
  output("COMPLETE");
} else {
  // Continue to next story
  continueLoop();
}

===== FEATURE COMPLETE =====

Branch: feature/[name]
Stories completed: [N]
Total commits: [M]

Summary:
- [Key accomplishments]
- [Files changed]

Next steps:
1. Review the changes: git log --oneline feature/[name]
2. Run full test suite: npm test
3. Create PR when ready: gh pr create

Would you like me to:
A. Create a pull request
B. Show a detailed summary
C. Continue with more features
D. Clean up worktree (if used)

# Check if worktree was used
if [ -n "$(jq -r '.worktree.path // empty' prd.json)" ]; then
  WORKTREE_PATH=$(jq -r '.worktree.path' prd.json)
  MAIN_REPO=$(jq -r '.worktree.mainRepoPath' prd.json)

  echo "Feature developed in worktree: $WORKTREE_PATH"
  echo ""
  echo "Cleanup options:"
  echo "1. Keep worktree (for future reference)"
  echo "2. Remove worktree, keep branch"
  echo "3. Remove worktree and merge branch to main"
fi

# From main repo
cd "$MAIN_REPO"
git worktree remove "$WORKTREE_PATH"
git worktree prune

Detected: Tests that passed before are now failing.

Affected tests: [list]

Options:
1. Rollback this story: git reset --hard HEAD~1
2. Fix the regression before continuing
3. Mark as known issue and continue

# Repository Patterns

## API Conventions

- All endpoints use REST conventions
- Error responses follow format: { error: string, code: number }

## Component Patterns

- UI components in src/components/
- Server actions in src/actions/

## Database

- Migrations in db/migrations/
- Schema in db/schema.ts

## Testing

- Unit tests alongside source files
- Integration tests in tests/

## Gotchas

- Must run db:generate after schema changes
- Server actions need revalidatePath for cache

> status

## Progress: User Settings Feature

Branch: feature/user-settings
Stories: 4/8 complete (50%)

| ID      | Title                    | C | Status | Attempts |
|---------|--------------------------|---|--------|----------|
| US-001  | Create settings page     | 3 | ✓      | 1        |
| US-002  | Add profile form         | 4 | ✓      | 1        |
| US-003  | Add avatar upload        | 5 | ✓      | 2        |
| US-004  | Connect to API           | 4 | ✓      | 1        |
| US-005  | Add email preferences    | 3 | →      | 1        |
| US-006  | Add notification settings| 6 | ○      | 0        |
| US-007  | Add OAuth connections    | 8 | ⊘      | 0        |
| US-008  | Add delete account       | 5 | ○      | 0        |

Legend: ✓ done, → active, ○ pending, ⊘ blocked
C = Complexity (1-10)

**Blocked stories:**
- US-007: waiting on US-005, US-006

**Complexity summary:**
- Remaining: 22 points across 4 stories
- Avg complexity: 5.5
- High-risk: US-007 (8) - consider `expand US-007`

**Next:** US-005 - Add email preferences (complexity: 3)

**Parallel execution:** Enabled (max 3 concurrent)
**Independent stories:** US-005, US-006, US-008 (can run in parallel)

> expand US-005

Analyzing US-005: "Add OAuth login flow" (complexity: 8)

Complexity factors:
- External API integration (Google OAuth)
- Multiple routes (callback, logout)
- Session management
- UI components (login button, user menu)

Expanding into 4 stories...

## Proposed Expansion

**US-005.1: Add OAuth callback endpoint** (complexity: 3)
- Create /api/auth/callback route
- Handle token exchange
- Store session in cookie
- Acceptance: Returns user data on success, 401 on failure

**US-005.2: Add OAuth initiation endpoint** (complexity: 2)
- Create /api/auth/login route
- Redirect to Google OAuth URL
- Include proper scopes and state
- Acceptance: Redirects to Google, state validated on return

**US-005.3: Add login button component** (complexity: 3)
- Create LoginButton component
- Handle loading/error states
- Redirect to OAuth initiation
- Acceptance: Button visible when logged out, triggers OAuth flow

**US-005.4: Add user session context** (complexity: 4)
- Create AuthContext provider
- Add useAuth hook
- Fetch session on app load
- Acceptance: Components can access user state, logout works

**Dependencies:** US-005.1 → US-005.2 → US-005.3, US-005.4

Original complexity: 8 → Expanded total: 12 (but each piece is manageable)

Apply this expansion? (yes/no/edit)

// Original story marked as expanded
{
  "id": "US-005",
  "status": "expanded",
  "expandedInto": ["US-005.1", "US-005.2", "US-005.3", "US-005.4"]
}

// New stories added to prd.json
{
  "id": "US-005.1",
  "title": "Add OAuth callback endpoint",
  "complexity": 3,
  "dependsOn": [],
  "expandedFrom": "US-005"
}

> summarize

Regenerating progress-summary.md...

Summary generated:
- Stories: 12/14 complete (86%)
- Learnings extracted: 15 patterns, 4 gotchas
- Recent context: Last 3 stories included
- Token savings: ~3,200 tokens (78% reduction)

Summary written to progress-summary.md

## Starting: US-003 - Add dark mode toggle

Story type detected: frontend
Selected agent: frontend-agent

Delegating to frontend-agent...

✓ Created app/components/ThemeToggle.tsx
✓ Typecheck passed
✓ Tests passed (2/2)

RESULT: SUCCESS

✓ US-003 complete (attempt 1)
  Implemented by: frontend-agent

{
  "delegation": {
    "enabled": false
  }
}

## Phase 3: Autonomous Loop

Analyzing stories...
- US-001: Add users table (database) - READY
- US-002: Create login endpoint (api) - READY
- US-003: Add login button (frontend) - depends on US-002, BLOCKED
- US-004: Add logout endpoint (api) - READY

Independent stories: 3 (US-001, US-002, US-004)
Conflict check: US-002 & US-004 may touch app/api/* → run sequentially

## Parallel Execution: 2 stories

| ID | Title | Type | Agent |
|----|-------|------|-------|
| US-001 | Add users table | database | database-agent |
| US-002 | Create login endpoint | api | api-agent |

Launching 2 agents in parallel...

[Both agents working concurrently...]

Results:
✓ US-001 (database-agent): SUCCESS in 1m 42s
✓ US-002 (api-agent): SUCCESS in 2m 15s

2 stories completed in 2m 15s (vs ~4m sequential)
Speedup: 1.8x

> swarm status

## Swarm Status: feature-auth-system

**Team:** feature-auth-system
**Started:** 2026-01-27T10:30:00Z
**Duration:** 4m 32s

### Task Board

| ID | Title | Type | Status | Owner |
|----|-------|------|--------|-------|
| 1 | Add users table | database | ✓ completed | database-worker |
| 2 | Create login endpoint | api | ✓ completed | api-worker |
| 3 | Add login button | frontend | → in_progress | frontend-worker |
| 4 | Add logout endpoint | api | ○ pending | - |
| 5 | Add session context | frontend | ⊘ blocked | - |

### Workers

| Worker | Status | Current Task | Completed | Failed |
|--------|--------|--------------|-----------|--------|
| frontend-worker | active | Task 3 | 0 | 0 |
| api-worker | idle | - | 1 | 0 |
| database-worker | idle | - | 1 | 0 |

### Metrics

- Messages exchanged: 12
- Avg task duration: 1m 45s
- Estimated speedup: 2.8x

### Recent Messages

- [10:32:15] database-worker → leader: task_completed (Task 1)
- [10:33:42] api-worker → leader: task_completed (Task 2)
- [10:34:01] frontend-worker → leader: claimed Task 3

┌──────────────────────────────────────────────────────────────────┐
│                        SWARM ORCHESTRATOR                         │
│                                                                   │
│  ┌───────────────────────────────────────────────────────────┐   │
│  │                      LEADER AGENT                          │   │
│  │  - Creates team and task board                             │   │
│  │  - Spawns specialist workers                               │   │
│  │  - Monitors inboxes for completion/failure                 │   │
│  │  - Updates prd.json and progress.md                        │   │
│  │  - Handles escalations and shutdown                        │   │
│  └───────────────────────────────────────────────────────────┘   │
│                              │                                    │
│                    TeammateTool.write()                          │
│                              │                                    │
│         ┌────────────────────┼────────────────────┐              │
│         │                    │                    │              │
│         ▼                    ▼                    ▼              │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐        │
│  │  FRONTEND   │     │    API      │     │  DATABASE   │        │
│  │   WORKER    │     │   WORKER    │     │   WORKER    │        │
│  │             │     │             │     │             │        │
│  │ TaskList()  │     │ TaskList()  │     │ TaskList()  │        │
│  │ → Claim     │     │ → Claim     │     │ → Claim     │        │
│  │ → Implement │     │ → Implement │     │ → Implement │        │
│  │ → Verify    │     │ → Verify    │     │ → Verify    │        │
│  │ → Report    │     │ → Report    │     │ → Report    │        │
│  └─────────────┘     └─────────────┘     └─────────────┘        │
│         │                    │                    │              │
│         └────────────────────┼────────────────────┘              │
│                              │                                    │
│                     Shared Task Board                            │
│                    (~/.claude/tasks/)                            │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘