# Build Agent Skill

> Orchestrates the Build phase: UI first, logic second, with human approval gates.

## Overview

The Build Agent coordinates the development of products using:
- **Claude Code** for coding (with Figma MCP for design context)
- **Browser automation** for QA testing
- **Caddy** for dev URL deployment
- **GitHub** for version control

## Build Flow

```
Design Approved
      ↓
┌─────────────────────────────────────────┐
│  STAGE 1: UI/UX ONLY                    │
├─────────────────────────────────────────┤
│  1. Create repo + Caddy dev URL         │
│  2. Spawn coding sub-agent              │
│  3. Build all screens (UI only)         │
│  4. Checkpoint screenshots              │
│  5. Browser QA (flow testing)           │
│  6. Git commit                          │
│  7. Request human review                │
│  8. ← Feedback loop until approved →    │
└─────────────────────────────────────────┘
      ↓ (Human approves UI)
┌─────────────────────────────────────────┐
│  STAGE 2: LOGIC                         │
├─────────────────────────────────────────┤
│  1. Create test account                 │
│  2. Build business logic                │
│  3. Checkpoint screenshots              │
│  4. Browser QA (full flow + logic)      │
│  5. Git commit                          │
│  6. Request human review                │
│  7. ← Feedback loop until approved →    │
└─────────────────────────────────────────┘
      ↓ (Human approves)
Phase Complete → Market Phase
```

## Prerequisites

### From Previous Phases
- PRD + User Stories (Discovery)
- Figma URL OR AI-generated screenshots (Design)

### Infrastructure
- Claude Code with Figma MCP configured
- Caddy skill for dev URLs
- GitHub CLI authenticated
- Browser automation available

## Usage

### Start Build Phase
```bash
# Load product context
product="<product-name>"

# Check prerequisites
cat "agency/products/$product/discovery/prd.md"
cat "agency/products/$product/design/workflow.json"

# Initialize build progress
cp agency/templates/build-progress.yaml "agency/products/$product/build/progress.yaml"

# Update progress with product info
# Then spawn build orchestration
```

### Spawn Coding Sub-Agent
The coding work is long-running — always use a sub-agent:

```
Use sessions_spawn to start a coding sub-agent with task:
"Build the UI for [product] following the PRD and Figma designs.
Focus ONLY on UI/UX - no business logic yet.
Update progress.yaml at each checkpoint.
Take screenshots at milestones.
Report back when ready for QA."
```

### Figma MCP Context
Claude Code connects to Figma MCP automatically (configured in project).
The coding agent can use these MCP tools:
- `get_file` — Get Figma file structure
- `get_node` — Get specific frame/component
- `get_styles` — Get design tokens
- `download_figma_images` — Export assets

### QA Testing
Use browser automation to test the flow:
```
1. Navigate to dev URL
2. Take snapshot
3. Walk through each screen
4. Verify UI matches design
5. Check responsive behavior
6. Document issues
```

### Human Review Request
When ready for review:
1. Update progress.yaml with `status: review_pending`
2. Notify on Discord with:
   - Dev URL
   - Summary of what's built
   - Screenshots of key screens
   - Any known issues

## Progress Tracking

The `progress.yaml` file tracks:
- Current status (ui_building, ui_review, logic_building, etc.)
- Module completion
- QA results
- Human feedback
- Checkpoint history with screenshots

### Update Progress Example
```yaml
stages:
  ui:
    status: in_progress
    screens_built: 5
    screens_total: 12
    
checkpoints:
  - timestamp: "2026-02-02T17:30:00Z"
    stage: ui
    message: "Completed authentication screens"
    screenshot: "artifacts/build/checkpoints/auth-screens.png"
```

## Tech Stack

All builds use:
- **Next.js 14** (App Router) — Fullstack framework
- **Tailwind CSS** — Styling
- **shadcn/ui** — Component library
- **TypeScript** — Type safety

## Key Principles

1. **UI First, Logic Second** — Get visual approval before coding logic
2. **Checkpoint Screenshots** — Document progress visually
3. **Human Gates** — Never auto-advance without approval
4. **Feedback Loops** — Iterate based on human input
5. **Test Everything** — Browser QA before human review

## Related Skills

- `coding-agent` — Claude Code integration
- `web-app-builder` — Next.js scaffolding
- `caddy-manager` — Dev URL management
- `github` — Repository management
- `nano-banana-pro` — Screen generation (if skip_figma)

## Files

- `references/build-flow.md` — Detailed build workflow
- `references/qa-checklist.md` — QA testing checklist
- `references/figma-mcp.md` — Figma MCP usage guide
