# Escotilha Claude Kit Autonomous Dev

> Autonomous Coding Agent

- Skill: `tomevault-io/escotilha-claude-kit-autonomous-dev` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/escotilha-claude-kit-autonomous-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/escotilha-claude-kit-autonomous-dev/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/escotilha-claude-kit-autonomous-dev

---


# Autonomous Coding Agent

An autonomous workflow that breaks features into small, testable user stories and implements them one at a time with fresh context per iteration.

## Core Architecture

**Memory persists across iterations via:**

- `prd.json` - Task list with completion status
- `progress.md` - Learnings and implementation notes
- `AGENTS.md` - Long-term patterns for the repository
- Git history - All code changes
- **Memory MCP** - Cross-codebase learnings (patterns, mistakes, preferences)

**Each iteration is stateless** - read these files to understand context.

---

## Memory Integration (Cross-Codebase Learning)

The agent uses the Memory MCP server to learn across different projects. This enables:

- Remembering patterns that work well
- Avoiding mistakes made in other codebases
- Applying user preferences consistently

### Memory Entity Types

| Type                    | Purpose                      | Example                              |
| ----------------------- | ---------------------------- | ------------------------------------ |
| `pattern`               | Reusable solutions           | `pattern:early-returns`              |
| `mistake`               | Things to avoid              | `mistake:env-in-repo`                |
| `preference`            | User's preferred approaches  | `preference:package-manager`         |
| `tech-insight`          | Framework-specific knowledge | `tech-insight:supabase-rls`          |
| `architecture-decision` | High-level design choices    | `architecture-decision:multi-tenant` |

### When to Query Memory

1. **Phase 1 Start** - Query preferences and patterns before asking clarifying questions
2. **Phase 3 Start** - Load relevant tech-insights for the detected stack
3. **Before Implementation** - Check for related mistakes/patterns

### When to Save to Memory

1. **After successful story** - Extract reusable patterns
2. **After fixing a bug** - Save as mistake to avoid
3. **When discovering codebase convention** - Save if broadly applicable

---

## Entry Point Detection

When this skill activates, determine which phase to enter:

| Condition                              | Action                                     |
| -------------------------------------- | ------------------------------------------ |
| No `prd.json` exists                   | Start Phase 1 (PRD Generation)             |
| `prd.json` exists but no markdown PRD  | Start Phase 2 (JSON Conversion)            |
| `prd.json` exists with pending stories | Start Phase 3 (Autonomous Loop)            |
| All stories `passes: true`             | Report completion, ask if more work needed |

**First Action:** Check for existing files:

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

---

## Phase 1: PRD Generation

**Goal:** Create a Product Requirements Document from a feature idea.

### Step 1.0: Load User Preferences from Memory

**First action:** Query the Memory MCP for user preferences and patterns:

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

**Apply learned preferences:**

- Package manager preference (pnpm vs npm vs yarn)
- Deployment targets (Railway, Vercel, Cloudflare)
- Code organization patterns (feature folders, etc.)
- Testing preferences

These preferences inform your clarifying questions and PRD structure.

### Step 1.1: Codebase Discovery

Before asking questions, understand the existing codebase:

```
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
```

**Query stack-specific learnings:**

```
# 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" })
```

### Step 1.2: Clarifying Questions

Ask 3-5 essential questions with lettered options:

```
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)
```

### Step 1.3: Generate PRD

Create `tasks/prd-[feature-name].md`:

```markdown
# 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 Scoring:**

Assign each story a complexity score (1-10) during PRD creation:

| Score | Description | Example |
|-------|-------------|---------|
| 1-3 | Simple, single-file change | Add a config option, fix a typo |
| 4-6 | Moderate, 2-4 files, clear path | Add API endpoint, create component |
| 7-8 | Complex, multiple concerns | Database + API + UI changes |
| 9-10 | Very complex, consider splitting | Full authentication system |

**Scoring factors:**
- Number of files likely touched
- Number of systems involved (DB, API, UI, etc.)
- Unfamiliarity with the area
- External dependencies or integrations
- Risk of breaking existing functionality

**Story Sizing Rules:**

| Right-sized (1 iteration)         | Too big (split)             |
| --------------------------------- | --------------------------- |
| Add a database column             | Build entire dashboard      |
| Create single API endpoint        | Add authentication system   |
| Add UI component to existing page | Refactor the API            |
| Add filter dropdown               | Complete feature end-to-end |

**Rule:** If you can't describe the change in 2-3 sentences, split it.

### Step 1.4: Generate Complexity Report

After creating the PRD, generate a complexity report to identify potential issues early:

```
## 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)
```

**When to flag for splitting:**
- Any story with complexity ≥ 8
- More than 3 stories with complexity ≥ 7
- Total complexity points > (story count × 5)

### Step 1.5: Get Approval

```
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
```

---

## Phase 2: JSON Conversion

**Goal:** Convert approved PRD to machine-readable `prd.json`.

### Step 2.1: Archive Previous Run (if needed)

```bash
# 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
```

### Step 2.2: Create Feature Branch

```bash
git checkout -b feature/[feature-name]
```

### Step 2.2a: Create Feature Worktree (Optional)

If `.worktree-scaffold.json` exists in the project root, create an isolated worktree for this feature. This keeps development separate from the main working directory.

**When to use worktrees:**
- Large features with many stories
- Features that need isolation from other work
- Parallel feature development

**How to create:**

```bash
# 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
```

**Store worktree info in prd.json:**

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

### Step 2.3: Generate prd.json

```json
{
  "project": "[Project Name]",
  "branchName": "feature/[feature-name]",
  "description": "[Feature description]",
  "createdAt": "2024-01-15T10:00:00Z",
  "delegation": {
    "enabled": false,
    "fallbackToDirect": true
  },
  "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
    }
  ]
}
```

**Story Fields:**

- `complexity`: Score 1-10 indicating implementation difficulty
- `complexityFactors`: Brief list of what makes it complex (for context)
- `status`: One of `pending`, `blocked`, `in_progress`, `completed`, `skipped`
- `dependsOn`: Array of story IDs that must complete first

**Status Values:**

| Status | Meaning |
|--------|---------|
| `pending` | Ready to start (no blockers) |
| `blocked` | Waiting on dependencies |
| `in_progress` | Currently being implemented |
| `completed` | Passed all verification |
| `skipped` | Manually skipped by user |

**Blocked Detection:**

A story is blocked when any story in its `dependsOn` array has `passes: false`:

```javascript
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
- `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)

**Delegation Metrics:**

Automatically tracked performance metrics:

- `totalStories`: Total number of stories completed
- `delegatedCount`: Number of stories delegated to agents
- `directCount`: Number of stories implemented directly
- `successRate`: Percentage of stories that passed on first attempt (0-100)
- `avgAttempts`: Average number of attempts per story
- `byAgent`: Breakdown by agent type:
  ```json
  {
    "frontend-agent": { "count": 3, "successRate": 100, "avgAttempts": 1.0 },
    "api-agent": { "count": 2, "successRate": 50, "avgAttempts": 1.5 },
    "direct": { "count": 1, "successRate": 100, "avgAttempts": 1.0 }
  }
  ```
- `byType`: Breakdown by detected story type:
  ```json
  {
    "frontend": 3,
    "api": 2,
    "database": 1,
    "general": 1
  }
  ```
- `detectionAccuracy`: Manual validation results (optional, set by user review)

**Optimization Configuration:**

Token optimization settings for reducing context size:

- `optimization.progressSummary.enabled`: Enable progress.md summarization (default: `true`)
- `optimization.progressSummary.recentStoriesCount`: How many recent stories to include in full detail (default: `3`)
- `optimization.progressSummary.maxLearnings`: Maximum extracted learnings to include (default: `15`)
- `optimization.progressSummary.autoGenerate`: Auto-regenerate summary after each story (default: `true`)

**Disable Progress Summarization:**

To load full progress.md instead of summary:

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

**Updating Metrics:**

After each story completion, update delegationMetrics:

```javascript
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;
}
```

**Querying Metrics with jq:**

```bash
# 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
```

### Step 2.4: Initialize Progress File

Create `progress.md`:

```markdown
# Progress Log: [Feature Name]

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

---
```

### Step 2.5: Detect Verification Commands

Scan the codebase to find the right commands:

```bash
# 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
```

Store in prd.json:

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

---

## Phase 3: Autonomous Loop

**Goal:** Implement one story per iteration until complete.

### Step 3.0: Load Context (with Token Optimization)

At the start of EVERY iteration, load context efficiently:

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

# Use optimized progress loading (see below)
```

**Optimized Progress Loading:**

To reduce token usage, prefer `progress-summary.md` over full `progress.md`:

```javascript
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);
}
```

**Token Savings:**

| Stories | Full progress.md | progress-summary.md | Savings |
|---------|------------------|---------------------|---------|
| 5 | ~1,500 tokens | ~500 tokens | 67% |
| 10 | ~3,000 tokens | ~700 tokens | 77% |
| 20 | ~6,000 tokens | ~900 tokens | 85% |

The summary grows logarithmically (learnings deduplicate) while full log grows linearly.

**Load cross-codebase learnings:**

```
# 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
```

**Stack detection -> memory queries:**

| Detected Stack | Memory Queries                         |
| -------------- | -------------------------------------- |
| Next.js        | `nextjs`, `react`, `server-components` |
| Supabase       | `supabase`, `rls`, `postgres`          |
| FastAPI        | `fastapi`, `python`, `api`             |
| React          | `react`, `hooks`, `state-management`   |

**Find the next story** using proper dependency and blocking logic:

```javascript
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(', ')}`);
    });
  }
}
```

**Blocked story output:**
```
⚠ 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)
```

### Step 3.0a: Analyze Story Type (Smart Delegation)

Before implementing, detect the story type to enable smart delegation.

**Story Type Detection:**

Analyze the story to determine its primary type:

```javascript
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';
}
```

**Detection Implementation:**

When Step 3.0a runs during autonomous loop execution:

1. **Run Detection:**
   ```javascript
   const detectedType = detectStoryType(currentStory);
   ```

2. **Log to Console:**
   ```
   Story type detected: api
   Detection signals: { api: 3, backend: 3, frontend: 0, database: 0, devops: 0 }
   ```

3. **Store in prd.json:**
   ```javascript
   currentStory.detectedType = detectedType;
   savePRD(prd);
   ```

4. **Update progress.md:**
   ```markdown
   ## Story Analysis

   - Detected type: api
   - Confidence signals: { api: 3, backend: 3, frontend: 0 }
   ```

**Important:** Detection runs automatically but does **NOT** trigger delegation unless `delegation.enabled = true` in prd.json. This allows testing detection accuracy before enabling delegation.

**Example Output:**

```
## 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...
```

### Step 3.1: Announce Task

```
## 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]
```

### Step 3.2: Implement Code (with Smart Delegation)

**Check Delegation Status:**

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

**Option A: Delegation Enabled**

If `delegationEnabled === true`:

1. **Select Specialized Agent:**

   ```javascript
   // Agent type mapping: story type → specialized agent skill
   const AGENT_MAP = {
     'frontend': 'frontend-agent',      // UI/component work
     'backend': 'backend-agent',        // Server-side logic (alias for api)
     'api': 'api-agent',                // REST/GraphQL endpoints
     'database': 'database-agent',      // Schema, migrations, queries
     'devops': 'devops-agent',          // CI/CD, deployment, infrastructure
     'fullstack': 'orchestrator-fullstack', // Multi-layer features
     'general': 'general-purpose'       // Catch-all for unclear stories
   };

   const storyType = detectStoryType(story); // From Step 3.0a
   const agentType = AGENT_MAP[storyType] || 'general-purpose';

   // Note: Agent availability is checked when Task tool is invoked
   // If agent skill is not installed, Task will fail and trigger fallback
   ```

   **Log agent selection:**
   ```
   Detected story type: ${storyType}
   Selected agent: ${agentType}

   Delegating to ${agentType}...
   ```

2. **Generate Subagent Context:**

   Create a detailed prompt for the subagent:

   ```markdown
   # Story Implementation Task

   You are implementing a single user story for the autonomous-dev orchestrator.

   ## Scope Constraints
   **ONLY implement this specific story.** Do not:
   - Implement other stories from the PRD
   - Refactor unrelated code
   - Add features beyond acceptance criteria
   - Create unnecessary abstractions
   - Create documentation unless explicitly required by acceptance criteria

   ## Story Details
   **ID:** ${story.id}
   **Title:** ${story.title}
   **Priority:** ${story.priority}

   **Description:**
   ${story.description}

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

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

   **Verification Commands:**
   ${Object.entries(prd.verification || {})
     .map(([type, cmd]) => `- ${type}: \`${cmd}\``)
     .join('\n')}

   ## Repository Patterns
   ${readFile('AGENTS.md') || 'No documented patterns yet'}

   ## Recent Implementation Context
   ${extractRecentProgress(3)} // Last 3 entries from progress.md

   ## Memory Insights
   Patterns to apply:
   ${queryMemoryPatterns(detectStack())}

   Mistakes to avoid:
   ${queryMemoryMistakes()}

   ## Dependencies from Previous Stories
   ${story.dependsOn.map(id => `- ${id}: ${getPreviousStoryNotes(id)}`).join('\n')}

   ## Your Task
   1. Read relevant existing code
   2. Implement ONLY what's needed for this story
   3. Run verification commands
   4. Report structured results

   ## Required Output Format
   ```
   RESULT: [SUCCESS|FAILURE]

   Files changed:
   - path/to/file1.ts (new/modified)
   - path/to/file2.ts (modified)

   Verification:
   - Typecheck: [PASS|FAIL]
   - Tests: [PASS|FAIL - X/Y passed]
   - Lint: [PASS|FAIL]

   Implementation notes:
   [2-3 sentences describing key decisions]

   Learnings:
   [Patterns discovered or issues encountered]
   ```
   ```

3. **Invoke Subagent:**

   ```javascript
   const result = await Task({
     subagent_type: agentType,
     description: `Implement ${story.id}: ${story.title}`,
     prompt: subagentPrompt
   });
   ```

4. **Parse Subagent Result:**

   ```javascript
   function parseSubagentResult(output) {
     // Extract RESULT line
     const resultMatch = output.match(/RESULT:\s*(SUCCESS|FAILURE)/i);

     // Extract files changed
     const filesMatch = output.match(/Files changed:\n((?:- .+\n?)+)/);
     const filesChanged = filesMatch?.[1]
       ?.split('\n')
       .filter(l => l.trim())
       .map(l => l.replace(/^- /, '').trim()) || [];

     // Extract verification results
     const verificationMatch = output.match(/Verification:\n((?:- .+\n?)+)/);
     const verification = {};
     if (verificationMatch) {
       verificationMatch[1].split('\n').forEach(line => {
         const match = line.match(/- (\w+): (PASS|FAIL)/i);
         if (match) verification[match[1].toLowerCase()] = match[2].toUpperCase();
       });
     }

     // Extract notes
     const notesMatch = output.match(/Implementation notes:\n(.+?)(?=\n\n|Learnings:|$)/s);
     const notes = notesMatch?.[1]?.trim() || '';

     const learningsMatch = output.match(/Learnings:\n(.+?)$/s);
     const learnings = learningsMatch?.[1]?.trim() || '';

     return {
       success: resultMatch?.[1]?.toUpperCase() === 'SUCCESS',
       filesChanged,
       verification,
       notes,
       learnings
     };
   }

   const parsed = parseSubagentResult(result);
   ```

   **Validate Parsed Result:**

   ```javascript
   function validateSubagentResult(parsed, story) {
     const errors = [];

     // 1. Check required fields present
     if (parsed.success === undefined) {
       errors.push('Missing RESULT status');
     }

     if (!parsed.filesChanged || parsed.filesChanged.length === 0) {
       errors.push('No files changed reported');
     }

     if (!parsed.verification || Object.keys(parsed.verification).length === 0) {
       errors.push('No verification results reported');
     }

     // 2. Validate verification results format
     for (const [key, value] of Object.entries(parsed.verification)) {
       if (value !== 'PASS' && value !== 'FAIL') {
         errors.push(`Invalid verification status for ${key}: ${value}`);
       }
     }

     // 3. Check files changed are reasonable
     const suspiciousFiles = parsed.filesChanged.filter(file =>
       file.includes('node_modules/') ||
       file.includes('.git/') ||
       file.includes('package-lock.json') ||
       file.match(/\.(env|secret|key)$/)
     );

     if (suspiciousFiles.length > 0) {
       errors.push(`Suspicious files modified: ${suspiciousFiles.join(', ')}`);
     }

     // 4. Validate file paths exist or are new
     for (const file of parsed.filesChanged) {
       const isNew = file.includes('(new)');
       const filePath = file.replace(/\s*\(new\|modified\)/, '').trim();
       // Note: File existence check would happen here
       // if (!isNew && !fileExists(filePath)) {
       //   errors.push(`File not found: ${filePath}`);
       // }
     }

     return {
       valid: errors.length === 0,
       errors
     };
   }

   function allVerificationsPassed(verification) {
     return Object.values(verification).every(status => status === 'PASS');
   }

   // Validate result
   const validation = validateSubagentResult(parsed, story);

   if (!validation.valid) {
     console.error('⚠ Subagent result validation failed:');
     validation.errors.forEach(err => console.error(`  - ${err}`));
     // Treat as delegation failure
     parsed.success = false;
   }
   ```

   **Error Handling for Malformed Output:**

   ```javascript
   try {
     const parsed = parseSubagentResult(result);
     const validation = validateSubagentResult(parsed, story);

     if (!validation.valid) {
       throw new Error(`Validation failed: ${validation.errors.join('; ')}`);
     }
   } catch (error) {
     console.error(`✗ Failed to parse subagent output: ${error.message}`);

     // Log raw output for debugging
     console.log('Raw subagent output:');
     console.log(result.substring(0, 500)); // First 500 chars

     // Trigger fallback
     if (fallbackToDirect) {
       console.log('⚠ Falling back to direct implementation...');
       // Proceed to Option B
     } else {
       throw error;
     }
   }
   ```

5. **Handle Delegation Result:**

   If delegation **succeeds**:
   ```javascript
   if (parsed.success && allVerificationsPassed(parsed.verification)) {
     // Update story in prd.json
     story.passes = true;
     story.delegatedTo = agentType;
     story.completedAt = new Date().toISOString();

     // Log success
     console.log(`✓ ${story.id} completed via ${agentType}`);

     // Continue to Step 3.3 (verification)
   }
   ```

   If delegation **fails** and `fallbackToDirect === true`:

   **Common failure reasons:**
   - Agent skill not installed/available
   - Agent returned FAILURE result
   - Verification commands failed
   - Task tool error

   ```
   ⚠ Delegation to ${agentType} failed.
   Reason: ${getFailureReason(result)}

   Falling back to direct implementation...
   ```
   → Proceed to Option B (Direct Implementation)

   **Note:** The fallback mechanism provides automatic recovery when:
   - Selected agent is not installed (`general-purpose` always available as ultimate fallback)
   - Agent fails to implement the story correctly
   - Verification fails after delegation

   If delegation **fails** and `fallbackToDirect === false`:
   ```
   ✗ Delegation failed and fallback is disabled.

   Options:
   1. Enable fallback: Set delegation.fallbackToDirect = true
   2. Try different agent (manual override)
   3. Skip this story
   4. Pause autonomous mode

   What would you like to do?
   ```

   **Fallback Tracking:**

   When fallback occurs, story metadata reflects direct implementation:
   ```json
   {
     "id": "US-007",
     "delegatedTo": null,
     "notes": "Delegation to api-agent failed: agent not available. Fell back to direct implementation."
   }
   ```

   **Error Scenario Examples:**

   **Scenario 1: Agent Not Available**
   ```
   ## Starting: US-002 - Add user profile endpoint

   Story type detected: api
   Selected agent: api-agent

   Delegating to api-agent...
   ✗ Error: Skill 'api-agent' not found
   ⚠ Delegation to api-agent failed.
   Reason: Agent skill not installed

   Falling back to direct implementation...
   ```

   **Scenario 2: Agent Returns FAILURE**
   ```
   ## Starting: US-003 - Add email column to users table

   Delegating to database-agent...

   RESULT: FAILURE

   Verification:
   - Migration up: FAIL - Syntax error on line 12

   ⚠ Delegation to database-agent failed.
   Reason: Agent returned FAILURE result

   Falling back to direct implementation...
   ```

   **Scenario 3: Verification Fails**
   ```
   ## Starting: US-001 - Add dark mode toggle

   Delegating to frontend-agent...

   RESULT: SUCCESS

   Verification:
   - Typecheck: FAIL - Type error in ThemeToggle.tsx

   ⚠ Delegation to frontend-agent failed.
   Reason: Verification commands failed (typecheck: FAIL)

   Falling back to direct implementation...
   ```

   **Scenario 4: Malformed Output**
   ```
   ## Starting: US-005 - Set up CI/CD

   Delegating to devops-agent...

   [Agent output doesn't match expected format]

   ✗ Failed to parse subagent output: Missing RESULT status
   Raw subagent output:
   [First 500 characters shown...]

   ⚠ Falling back to direct implementation...
   ```

**Option B: Direct Implementation (Default)**

If `delegationEnabled === false` OR delegation failed with fallback:

1. Read relevant existing files first
2. Follow patterns from `AGENTS.md` and existing code
3. Write code for ONLY this user story
4. Keep changes minimal and focused

**Implementation Checklist:**

- [ ] Read existing code patterns first
- [ ] Make minimal necessary changes
- [ ] Add tests if acceptance criteria requires them
- [ ] Don't refactor unrelated code

### Step 3.3: Run Verification

Execute verification commands from prd.json:

```bash
# Run typecheck
npm run typecheck

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

# Run lint (optional but recommended)
npm run lint
```

### Step 3.4: Handle Results

**If verification passes:**

1. Update `prd.json`:

   ```json
   {
     "passes": true,
     "attempts": 1,
     "completedAt": "2024-01-15T11:30:00Z"
   }
   ```

2. Commit the work:

   ```bash
   git add -A
   git commit -m "feat(US-XXX): [Title]

   - [What was implemented]
   - [Key decisions made]"
   ```

3. Update `progress.md`:

   ```markdown
   ## [Timestamp] - US-XXX: [Title]

   **Implementation:**

   - [What was done]
   - [Files changed]

   **Learnings:**

   - [Patterns discovered]
   - [Gotchas encountered]

   ---
   ```

4. **Generate progress-summary.md** (Token Optimization):

   After updating progress.md, regenerate the compact summary:

   ```javascript
   function generateProgressSummary(prd, progressMd) {
     const optimization = prd.optimization?.progressSummary ?? { enabled: true };
     if (!optimization.enabled) return;

     const recentCount = optimization.recentStoriesCount || 3;
     const maxLearnings = optimization.maxLearnings || 15;

     const summary = `# Progress Summary: ${prd.project}

Branch: \`${prd.branchName}\`
Started: ${prd.createdAt?.split('T')[0] || 'Unknown'}
Last updated: ${new Date().toISOString().split('T')[0]}

## Completion Status

${generateCompletionStatus(prd)}

## Story Status

${generateStoryTable(prd)}

## Key Learnings (Extracted)

${extractKeyLearnings(progressMd, maxLearnings)}

## Recent Context (Last ${recentCount} Stories)

${extractRecentEntries(progressMd, recentCount)}

---

*Auto-generated from progress.md. Full history preserved in progress.md.*
`;

     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 = progre

…(truncated)