auto-build/plugin/commands/build.md

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

# Build Feature from Specification

Orchestrate the complete implementation of a feature using its specification.

## IMPORTANT: Execute This Workflow Step-by-Step

When this command is invoked, you MUST follow each step in order. After each task completion, you MUST update both status.json AND plan.md before proceeding.

## Input

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

## Step 1: Load and Validate

Execute immediately:

1. Read the spec file:
   ```
   .auto-build/specs/{feature-name}/spec.md
   ```

2. Read the status file:
   ```
   .auto-build/specs/{feature-name}/status.json
   ```

3. Read the plan file (if exists):
   ```
   .auto-build/specs/{feature-name}/plan.md
   ```

4. Check status and determine next action:
   - If `SPEC_COMPLETE` → Go to Step 2 (Worktree offer) then Step 3 (Planning)
   - If `PLANNING_COMPLETE` → Go to Step 4 (Implementation)
   - If `IMPLEMENTING` → Resume from `currentTask` in status.json

## Step 2: Offer Worktree (Only if SPEC_COMPLETE)

Ask the user:
```
This feature may modify multiple files.
Create an isolated git worktree? (recommended for larger features)
[Yes] [No]
```

If **Yes**:
1. Run: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-create.sh {feature-name}`
2. Update status.json with worktree path
3. Display:
```
════════════════════════════════════════════════════════════════
  WORKTREE CREATED - ACTION REQUIRED
════════════════════════════════════════════════════════════════

✅ Worktree: ../ab-worktrees/{project}-{feature-name}/
✅ Branch: feature/ab-{feature-name}

⚠️  YOU MUST NOW:

1. Open NEW VSCode window:
   code ../ab-worktrees/{project}-{feature-name}/

2. In the NEW window, run:
   /ab:build {feature-name}

════════════════════════════════════════════════════════════════
```
4. **STOP** - Do not continue. Wait for user to switch directories.

If **No**: Continue to Step 3.

## Step 3: Create Plan (Only if SPEC_COMPLETE)

1. Update status.json:
   ```json
   {
     "status": "PLANNING",
     "updated": "{ISO timestamp}"
   }
   ```

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

3. Create plan.md with this structure:
   ```markdown
   # Implementation Plan: {feature-name}

   ## Progress Tracker

   | Task | Status | Completed |
   |------|--------|-----------|
   | Task 1: {title} | ⬜ Pending | |
   | Task 2: {title} | ⬜ Pending | |
   | ... | | |

   ## Tasks

   ### Task 1: {Title}
   - **Status**: ⬜ Pending
   - **Files**: file1.ts, file2.ts
   - **Description**: What to do
   - **Dependencies**: None

   ### Task 2: {Title}
   - **Status**: ⬜ Pending
   - **Files**: file3.ts
   - **Description**: What to do
   - **Dependencies**: Task 1

   ...
   ```

4. Update status.json:
   ```json
   {
     "status": "PLANNING_COMPLETE",
     "totalTasks": {number of tasks},
     "currentTask": 1,
     "updated": "{ISO timestamp}",
     "history": [..., {"status": "PLANNING_COMPLETE", "at": "{timestamp}"}]
   }
   ```

5. Continue to Step 4.

## Step 4: Implementation Loop

**FOR EACH TASK, execute these sub-steps in order:**

### 4a. Display Task Banner

```
════════════════════════════════════════════════════════════════
  TASK {N}/{TOTAL}: {Task Title}
════════════════════════════════════════════════════════════════
Status: Starting...
Files: {list of files}
────────────────────────────────────────────────────────────────
```

### 4b. Update Status to In-Progress

Write to `.auto-build/specs/{feature-name}/status.json`:
```json
{
  "feature": "{feature-name}",
  "status": "IMPLEMENTING",
  "currentTask": {N},
  "totalTasks": {TOTAL},
  "updated": "{ISO timestamp}",
  "history": [
    ...existing...,
    {"status": "IMPLEMENTING", "at": "{timestamp}", "task": {N}, "started": true}
  ]
}
```

### 4c. Execute Task

Implement the task according to plan.md specifications.

### 4d. MANDATORY: Update Progress Files

**After completing each task, you MUST execute these updates before doing anything else:**

**Update 1 - status.json:**
Write to `.auto-build/specs/{feature-name}/status.json`:
```json
{
  "feature": "{feature-name}",
  "status": "IMPLEMENTING",
  "currentTask": {N+1},
  "totalTasks": {TOTAL},
  "updated": "{ISO timestamp}",
  "tasksCompleted": {N},
  "history": [
    ...existing...,
    {"status": "IMPLEMENTING", "at": "{timestamp}", "task": {N}, "title": "{title}", "completed": true}
  ]
}
```

**Update 2 - plan.md Progress Tracker:**
Edit the plan.md file to update the task status:
- Change `⬜ Pending` to `✅ Done` for the completed task
- Add completion timestamp

Example edit in plan.md:
```markdown
## Progress Tracker

| Task | Status | Completed |
|------|--------|-----------|
| Task 1: Setup | ✅ Done | 2025-01-15 14:30 |
| Task 2: API | ⬜ Pending | |
```

And in the task section:
```markdown
### Task 1: Setup
- **Status**: ✅ Done (2025-01-15 14:30)
```

### 4e. Display Completion and Confirm

```
════════════════════════════════════════════════════════════════
✅ TASK {N}/{TOTAL} COMPLETED: {Task Title}
════════════════════════════════════════════════════════════════

Progress: {N}/{TOTAL} tasks done ({percentage}%)
Next task: {N+1}. {Next Task Title}

Continue to next task? [Yes] [No] [Skip]
```

Wait for user confirmation before proceeding to next task.

### 4f. Repeat

Go back to 4a for the next task until all tasks are complete.

## Step 5: Build Complete

When all tasks are done:

1. Update status.json:
   ```json
   {
     "status": "IMPLEMENTATION_COMPLETE",
     "currentTask": {TOTAL},
     "totalTasks": {TOTAL},
     "tasksCompleted": {TOTAL},
     "updated": "{ISO timestamp}",
     "history": [..., {"status": "IMPLEMENTATION_COMPLETE", "at": "{timestamp}"}]
   }
   ```

2. Update plan.md header:
   ```markdown
   # Implementation Plan: {feature-name}

   **Status**: ✅ COMPLETE
   **Completed**: {timestamp}
   ```

3. Display summary:
   ```
   ════════════════════════════════════════════════════════════════
     BUILD COMPLETE: {feature-name}
   ════════════════════════════════════════════════════════════════

   ✅ Tasks completed: {TOTAL}/{TOTAL}
   📁 Files modified: {count}
   ⏱️  Duration: {time}

   NEXT STEPS:
   1. Test the implementation
   2. Run QA review: /ab:qa-review
   3. Save learnings: /ab:memory-save

   ════════════════════════════════════════════════════════════════
   ```

## Resume Logic

If status is `IMPLEMENTING` with `currentTask > 1`:

1. Display:
   ```
   ════════════════════════════════════════════════════════════════
     RESUMING BUILD: {feature-name}
   ════════════════════════════════════════════════════════════════

   Previous progress: {tasksCompleted}/{TOTAL} tasks completed
   Resume from: Task {currentTask}

   [Resume] [Restart from Task 1] [Cancel]
   ```

2. If Resume: Continue from Step 4 at task {currentTask}
3. If Restart: Reset currentTask to 1, continue from Step 4

## Why Progress Tracking Matters

- **Team collaboration**: Other developers can see progress and continue your work
- **Resume capability**: If interrupted, you can pick up where you left off
- **Visibility**: Users can check /ab:status to see current progress
- **History**: Complete audit trail of implementation

## Error Handling

- **Task fails**: Mark task as failed in history, ask user to fix manually or skip
- **Spec not found**: Display "Spec not found. Create with: /ab:spec {name}"
- **Plan not found but PLANNING_COMPLETE**: Re-run planning phase