Build App

Step 1: Initialize State

1A: Check for Existing State

Read plans/build-state.json. If it exists and status is "complete", report completion and stop.

If it exists and status is "failed", report the failure details and stop (user should run /build-app resume to continue).

If it exists and status is "in_progress", skip to Step 2 (resume building).

1B: Bootstrap State (First Run)

If plans/build-state.json does not exist:

1. Scan plans/active/ for files matching stage-*.md
2. Sort by stage number (extract N from stage-N-...)
3. Read the project name from CLAUDE.md (first heading or project description)
4. Read team info from CLAUDE.md (Agent Team section)
5. Create plans/build-state.json:

{
  "version": 1,
  "project": "[project-name]",
  "team": "[team-preset]",
  "status": "in_progress",
  "current_stage": 0,
  "total_stages": N,
  "iteration_count": 0,
  "started_at": "[ISO timestamp]",
  "updated_at": "[ISO timestamp]",
  "stages": [
    {
      "stage": 0,
      "title": "[from stage plan frontmatter]",
      "file": "plans/active/stage-0-[title].md",
      "status": "pending",
      "started_at": null,
      "completed_at": null,
      "tasks": {},
      "verification": {},
      "retries": 0,
      "error": null,
      "preview_url": null
    }
  ]
}

6. Send Slack notification: build started

Step 2: Find Next Stage

1. Read plans/build-state.json
2. Increment iteration_count
3. Find the first stage where status is not "complete"
4. If no such stage exists → mark build "complete", send Slack notification, stop (exit 0)
5. Set current_stage to that stage's number
6. Update plans/build-state.json

Step 3: Prepare Stage

If the current stage's status is "pending":

1. Refresh the plan — Invoke /plan-next-stage [stage-file] to update the stage plan against the actual codebase state. This ensures file paths, imports, and interfaces match what prior stages actually built.

2. Mark stage as in_progress — Update the stage entry in plans/build-state.json:

   {
     "status": "in_progress",
     "started_at": "[ISO timestamp]"
   }
   

3. Send Slack notification — Stage starting (use temp file to avoid Windows Git Bash quote issues):

   if [ -n "$SLACK_WEBHOOK_URL" ]; then
     tmpfile=$(mktemp)
     cat > "$tmpfile" <<EOFSLACK
   {"text":"Building *[project]*: Stage [N]: [Title] starting ([M] tasks)"}
   EOFSLACK
     curl -s -X POST "$SLACK_WEBHOOK_URL" \
       -H "Content-type: application/json" \
       --data-binary @"$tmpfile" 2>/dev/null || true
     rm -f "$tmpfile"
   fi
   

If the stage is already "in_progress" (resuming), skip the refresh and notification — just continue from the next incomplete task.

Step 4: Execute Tasks

Read the stage plan file to get the task list. Parse the task sections (Task NA, NB, NC, etc.).

4A: Determine Task Order

Read the Parallelization section of the stage plan to understand dependencies:

• Tasks marked as parallel can be executed in any order (but sequentially — true parallelism not supported)
• Tasks with dependencies must wait for their dependencies to complete

Build an ordered list of tasks respecting dependencies.

4B: Skip Completed Tasks

Check plans/build-state.json for tasks already marked "complete" in this stage. Skip those.

Also cross-reference with git history — if a task's expected commit message exists in git log --oneline, mark it as complete in state even if state says otherwise (drift correction).

4C: Execute Each Task

For each pending task in order:

1. Read the task section from the stage plan — get Steps, Files, and Verify sections
2. Execute the steps — Follow the numbered steps exactly as written in the plan. This means:
   • Create files listed as new
   • Modify files listed as modify or extend
   • Run any setup commands specified in the steps
   • Write the actual implementation code following the code snippets and interfaces in the plan
3. Run Tier 1 verification (Compiles):
   • Execute the Tier 1 command from the task's Verify section
   • If it fails: fix the error and retry (up to 3 attempts)
4. Run Tier 2 verification (Unit/Integration) if specified:
   • Execute the Tier 2 command
   • If it fails: fix the failing tests and retry (up to 3 attempts)
5. Commit the task:

   git add -A
   git commit -m "$(cat <<'EOF'
   [commit message from stage plan's Commits section]
   
   Co-Authored-By: Claude Opus 4.6 <[email protected]>
   EOF
   )"
   

6. Update state — Mark the task complete in plans/build-state.json:

   {
     "status": "complete",
     "commit": "[short hash from git log -1 --format=%h]"
   }
   

7. Write state to disk immediately — Do not batch state updates

4D: Handle Task Failures

If a task fails verification after 3 retry attempts:

1. Record the error in the task state:

   { "status": "failed", "error": "[error description]" }
   

2. Increment the stage's retries counter
3. If retries >= 3:
   • Mark the stage as "failed" with error details
   • Send Slack notification: stage failed
   • Update plans/build-state.json
   • Stop (exit 1)
4. If retries < 3:
   • Log the failure, attempt to fix the underlying issue
   • Retry the task from scratch

Step 5: Complete Stage

After all tasks in the stage are complete:

5A: Stage Checkpoint Verification

Read the Stage Checkpoint: Success Criteria section from the stage plan. Run each criterion:

• Execute the verification commands listed in the checkpoint table
• Check each threshold against actual results
• If any criterion fails: attempt to fix, retry once. If still failing, mark stage failed.

5B: Quality Gate

Run /verify-work to check for security vulnerabilities, code quality issues, and convention adherence. Auto-fix what can be fixed, commit fixes.

5C: Finalize Stage

1. Update stage status in plans/build-state.json:

   {
     "status": "complete",
     "completed_at": "[ISO timestamp]",
     "verification": {
       "tier1": true,
       "tier2": true,
       "checkpoint": true
     }
   }
   

2. Move the stage plan to archive:

   mkdir -p plans/archive
   mv "plans/active/[stage-file].md" "plans/archive/[stage-file].md"
   

3. Update the stage plan frontmatter:

   status: completed
   completed: [YYYY-MM-DD]
   

4. Deploy preview (if Netlify CLI is available):

   if command -v netlify &> /dev/null; then
     # Deploy a draft/preview build
     DEPLOY_OUTPUT=$(netlify deploy --dir=. --message="Stage [N]: [Title] complete" 2>&1)
     PREVIEW_URL=$(echo "$DEPLOY_OUTPUT" | grep -o 'https://[^ ]*\.netlify\.app' | head -1)
   
     # Update state with preview URL
     # Add "preview_url": "$PREVIEW_URL" to the stage entry in build-state.json
   
     # If this is the final stage, deploy to production
     if [[ no more stages remain ]]; then
       netlify deploy --prod --dir=. --message="Build complete: [project]"
       PROD_URL=$(echo "$DEPLOY_OUTPUT" | grep -o 'https://[^ ]*\.netlify\.app' | head -1)
     fi
   fi
   

   Note: The deploy directory should match the project's build output (e.g., .next, dist, build, out). Read the project's framework config to determine the correct directory. Run the build command first if needed (e.g., npm run build).

5. Send Slack notification: stage complete with preview URL (use temp file pattern as shown in Step 3)

   • Include the preview URL in the message if a deploy was made: "Stage [N]: [Title] complete — Preview: [PREVIEW_URL]"

Step 6: Continue or Exit

After completing a stage:

1. Check if more stages remain (any stage with status != "complete")
2. If no more stages:
   • Mark build as "complete" in plans/build-state.json
   • Send Slack notification: build complete
   • Stop (exit 0)
3. If more stages remain:
   • Loop back to Step 2 to start the next stage
   • The runner script will re-invoke this skill if the context window is exhausted mid-stage

Slack Notifications

All Slack notifications are optional — they only fire if $SLACK_WEBHOOK_URL is set.

Use this pattern for all notifications (temp file avoids Windows Git Bash quote mangling):

if [ -n "$SLACK_WEBHOOK_URL" ]; then
  tmpfile=$(mktemp)
  cat > "$tmpfile" <<EOFSLACK
{"text":"[MESSAGE]"}
EOFSLACK
  curl -s -X POST "$SLACK_WEBHOOK_URL" \
    -H "Content-type: application/json" \
    --data-binary @"$tmpfile" 2>/dev/null || true
  rm -f "$tmpfile"
fi

State File Reference

The state file lives at plans/build-state.json. It is the single source of truth for build progress. The runner script reads it between iterations to decide whether to continue, and the skill reads it on startup to know where to resume.

Key invariants:

• State is written to disk after every task completion (not batched)
• Git history is used as secondary validation (drift correction on resume)
• The file is committed along with source code changes
• iteration_count is incremented once per skill invocation (tracked by runner)

Error Recovery

Usage Examples

Local (interactive)

/build-app              # Start or continue building
/build-app status       # Show progress
/build-app resume       # Resume after failure
/build-app reset        # Clear state and start over

Unattended (via runner script)

# Run locally, get Slack updates on your phone
./scripts/build-app-runner.sh --slack-webhook $SLACK_WEBHOOK_URL ../my-app

# Run via GitHub Actions (trigger from GitHub UI)
# See .github/workflows/build-app.yml

Full Pipeline

1. /launch-app "expense tracker SaaS"    # Creates project with stage plans
2. cd ../expense-tracker
3. /build-app                             # Builds it autonomously