---
description: Orchestrate feature implementation from specification
argument-hint: <feature-name>
---

# Build Feature from Specification

Orchestrate the complete implementation of a feature using its specification. This is the core command that coordinates planning, coding, and progress tracking.

## Input

- **Feature name**: $ARGUMENTS (required, must match existing spec)

## Prerequisites

- Spec must exist at `.auto-build-data/specs/{feature-name}/spec.md`
- Status must be `SPEC_COMPLETE` or `PLANNING_COMPLETE` or `IMPLEMENTING`

## Workflow

### 1. Load Specification

- Read `.auto-build-data/specs/{feature-name}/spec.md`
- Read `.auto-build-data/specs/{feature-name}/status.json`
- Validate spec exists and is complete
- If status is `IMPLEMENTING`, resume from current task

### 2. Offer Worktree (for new builds)

If status is `SPEC_COMPLETE`:
```
This feature may modify multiple files.
Create an isolated git worktree? (recommended for larger features)
[Yes] [No]
```

If yes:
- Run: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-create.sh {feature-name}`
- Update status.json with worktree path
- **IMPORTANT**: After worktree creation and planning, display clear next steps:

```
════════════════════════════════════════════════════════════════
  WORKTREE CREATED - ACTION REQUIRED
════════════════════════════════════════════════════════════════

✅ Worktree created at: ../ab-worktrees/{project}-{feature-name}/
✅ Branch: feature/ab-{feature-name}
✅ Plan created: .auto-build-data/specs/{feature-name}/plan.md

⚠️  NEXT STEPS (you must do this to continue):

1. Open a NEW VSCode window in the worktree:

   code ../ab-worktrees/{project}-{feature-name}/

2. In the NEW window, continue the build:

   /ab:build {feature-name}

   (It will detect the plan and start implementation)

────────────────────────────────────────────────────────────────
Why? Claude Code sessions are tied to the current directory.
To work in the isolated worktree, you need a new session there.
════════════════════════════════════════════════════════════════
```

- **STOP HERE** - Do not proceed with implementation in the current directory
- The user must switch to the worktree directory first

### 3. Planning Phase

**If status is `PLANNING_COMPLETE`** (plan already exists):
- Skip directly to Implementation Loop (step 4)
- This happens when resuming in a worktree after plan was created in main repo

**If status is `SPEC_COMPLETE`**:

1. Load memory context (if exists):
   - Read `.auto-build-data/memory/patterns.json`
   - Read `.auto-build-data/memory/gotchas.json`

2. Launch **planner** agent with:
   - The complete spec.md content
   - Relevant patterns from memory
   - Instruction to create ordered implementation tasks

3. The planner creates `.auto-build-data/specs/{feature-name}/plan.md`:
   ```markdown
   # Implementation Plan: {feature-name}

   ## Tasks

   ### Task 1: [Title]
   **Files**: file1.ts, file2.ts
   **Description**: What to do
   **Dependencies**: None

   ### Task 2: [Title]
   **Files**: file3.ts
   **Description**: What to do
   **Dependencies**: Task 1

   ...
   ```

4. Update status to `PLANNING_COMPLETE`

### 4. Implementation Loop

For each task in plan.md:

1. Update status to `IMPLEMENTING`, set `currentTask`

2. Display task info:
   ```
   Task 3/7: Add API endpoint for user stats
   Files: src/api/users.ts, src/types/user.ts
   ```

3. Launch **coder** agent with:
   - Current task details
   - Spec context
   - Relevant patterns from memory
   - Files to modify

4. After coder completes:
   - Update status.json with task progress
   - Ask: "Continue to next task? [Yes] [No] [Skip]"

5. Repeat until all tasks complete

### 5. Completion

When all tasks done:
- Update status to `IMPLEMENTATION_COMPLETE`
- Display summary:
  ```
  Build complete: {feature-name}

  Tasks completed: 7/7
  Files modified: 12

  Next steps:
  - Run QA review: /ab:qa-review
  - Or test manually and save learnings: /ab:memory-save
  ```

## State Machine

```
SPEC_COMPLETE
     |
     v
PLANNING (planner agent running)
     |
     v
PLANNING_COMPLETE
     |
     v
IMPLEMENTING (coder agent loop)
     |
     +---> [user skips/aborts] ---> PAUSED
     |
     v
IMPLEMENTATION_COMPLETE
     |
     v
[/ab:qa-review] ---> QA_REVIEW ---> COMPLETE
```

## Resume Logic

If status is already `IMPLEMENTING`:
- Read `currentTask` from status.json
- Ask: "Resume from task {n}/{total}? [Yes] [Restart] [Cancel]"
- If yes: Continue from that task
- If restart: Reset to task 1

## Status JSON During Build

```json
{
  "feature": "user-dashboard",
  "status": "IMPLEMENTING",
  "currentTask": 3,
  "totalTasks": 7,
  "worktree": "../ab-worktrees/project-user-dashboard/",
  "created": "2025-01-15T10:00:00Z",
  "updated": "2025-01-15T14:30:00Z",
  "history": [
    {"status": "SPEC_COMPLETE", "at": "..."},
    {"status": "PLANNING_COMPLETE", "at": "..."},
    {"status": "IMPLEMENTING", "at": "...", "task": 1},
    {"status": "IMPLEMENTING", "at": "...", "task": 2},
    {"status": "IMPLEMENTING", "at": "...", "task": 3}
  ]
}
```

## Error Handling

- If coder fails on a task: Mark task as failed, ask user to continue or fix manually
- If worktree creation fails: Continue without worktree, warn user
- If spec not found: "Spec not found. Create with: /ab:spec {name}"