auto-build/plugin/commands/build.md

description, argument-hint

description	argument-hint
Orchestrate feature implementation from specification	<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:

   # 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

{
  "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}"