Buildforce Logo
Commands

/build Command

Execute implementation following the spec and plan with progress tracking and deviation logging.

The /build command executes implementation following the spec and plan, with progress tracking and deviation logging for full transparency.

Purpose

Execute implementation following spec and plan, checking off tasks as work progresses and logging any deviations from the original approach.

Usage

/build [optional-iteration-instructions]

Examples

# First build
/build

# Iterative refinements
/build Change axios to fetch for HTTP requests

/build Add validation for empty email field

/build Use argon2 instead of bcrypt for password hashing

/build Fix failing test in auth.test.ts

What It Does

When you run /build, Buildforce:

  1. Loads context
    • Reads spec.yaml for requirements
    • Reads plan.yaml for implementation steps
    • Reads research.yaml (if exists) for patterns and context
  2. Executes implementation
    • Follows phases sequentially (phase_1, phase_2, ...)
    • Checks off tasks as work completes
    • Creates/modifies files according to plan
  3. Tracks progress
    • Updates checkboxes: [ ] → [x]
    • Updates overall progress counters
    • Records current status
  4. Logs deviations
    • When implementation differs from plan
    • Captures: Original → Actual → Reason
    • Maintains full deviation history across iterations
  5. Validates work
    • Confirms code compiles without errors
    • Runs tests if specified
    • Checks requirements are met
  6. Provides testing guidance
    • What to test (features/scenarios)
    • How to test (steps to verify)
    • Test results (if automated tests ran)

Build Execution Example

Before Build

phase_1:
  name: "Authentication Core"
  tasks:
    - [ ] Create authentication service
      spec_refs: [FR1]
      files: [src/auth/service.ts]
    
    - [ ] Implement password hashing with bcrypt
      spec_refs: [NFR2]
      files: [src/auth/service.ts]

After First Build

phase_1:
  name: "Authentication Core"
  tasks:
    - [x] Create authentication service
      spec_refs: [FR1]
      files: [src/auth/service.ts]
    
    - [x] Implement password hashing with bcrypt
      spec_refs: [NFR2]
      files: [src/auth/service.ts]

overall_progress:
  phase_1: "2/2 tasks completed ✓"

current_status: |
  Phase 1 complete. Authentication service created with bcrypt password hashing.
  Moving to Phase 2: JWT integration.

After Iteration (Deviation Logged)

/build Use argon2 instead of bcrypt

Deviation logged:

deviations:
  - phase: "phase_1"
    task: "Implement password hashing with bcrypt"
    original: "Use bcrypt for password hashing"
    actual: "Used argon2 for password hashing"
    reason: "User requested argon2 for better security against GPU attacks"

Iterative Refinement

Build supports multiple iterations with feedback:

# Iteration 1: Initial implementation
/build

# Review output, provide feedback
/build Add error handling for database connection failures

# Review again, refine further
/build Add retry logic with exponential backoff

# Final refinement
/build Add logging for all retry attempts

Each iteration:

  • Builds on previous work
  • Logs deviations from plan
  • Updates progress tracking
  • Maintains full history
Don't Do Everything in One BuildRun /build, review output, then run /build [feedback] to iterate. Multiple iterations with small refinements produce better results than trying to do everything at once.

Progress Tracking

Task Checkboxes

tasks:
  - [ ] Pending task
  - [x] Completed task
  - [ ] Another pending task

Phase Progress

overall_progress:
  phase_1: "2/2 tasks completed ✓"
  phase_2: "1/3 tasks completed"
  phase_3: "0/2 tasks completed"

Current Status

current_status: |
  Phase 1 complete. Phase 2 in progress: JWT middleware created,
  working on token refresh endpoint. Phase 3 not started.

Deviation Logging

Deviations capture why implementation differs from plan:

Deviation Example 1: Technical Decision

deviations:
  - phase: "phase_2"
    task: "Create JWT middleware"
    original: "Use express-jwt middleware"
    actual: "Created custom middleware"
    reason: "express-jwt doesn't support custom token extraction from cookies"

Deviation Example 2: User Feedback

deviations:
  - phase: "phase_1"
    task: "Implement login endpoint"
    original: "Return JWT in response body"
    actual: "Return JWT in httpOnly cookie"
    reason: "User requested cookie-based auth for better XSS protection"

Deviation Example 3: Discovered Issue

deviations:
  - phase: "phase_3"
    task: "Add token refresh endpoint"
    original: "Store refresh tokens in Redis"
    actual: "Store refresh tokens in PostgreSQL"
    reason: "Redis not configured in production environment, using main database"

Validation

After implementation, /build validates:

Code Quality:

  • ✅ Code compiles without errors
  • ✅ Linter passes (if configured)
  • ✅ No obvious missing pieces

Spec Requirements:

  • ✅ All functional requirements addressed
  • ✅ Non-functional requirements met
  • ✅ Acceptance criteria satisfied

Plan Adherence:

  • ✅ All tasks completed or deviations logged
  • ✅ File structure matches plan
  • ✅ Architecture decisions followed

Testing Guidance

After building, Buildforce provides:

What to Test:

  • Specific features to verify
  • Edge cases to check
  • Error scenarios to validate

How to Test:

  • Manual testing steps
  • Automated test commands
  • Expected results

Test Results:

  • Automated test output (if tests ran)
  • Pass/fail status
  • Coverage information

Example Testing Guidance

## Testing Guidance

### Automated Tests
Run: `npm test src/auth/`

Expected: All tests pass
- ✅ login endpoint returns JWT for valid credentials
- ✅ login endpoint returns 401 for invalid credentials
- ✅ middleware rejects expired tokens

### Manual Testing
1. POST /auth/login with valid credentials
   → Should receive JWT token
2. Use JWT token in Authorization header
   → Should access protected routes
3. Wait 16 minutes (token expiration)
   → Should be rejected with 401

Pro Tips

Start Clean

# First build: no arguments, just execute the plan
/build

Iterate with Specific Feedback

# Be specific about what to change
/build Add input validation to check email format before database query

Let Deviations Accumulate

Don't reset or hide deviations—they tell the story of how implementation evolved:

deviations:
  - # First iteration: changed library
  - # Second iteration: added error handling
  - # Third iteration: optimized performance

Validate Before Complete

Don't rush to /complete. Run tests, verify features, ensure quality:

/build              # Implement
# Test manually
/build Fix bug X    # Refine
# Test again
/build Optimize Y   # Polish
# Validate thoroughly
/complete          # Only when confident

When Build Fails

If implementation fails (compile errors, test failures), provide diagnostic info:

/build Fix TypeScript error: Property 'email' does not exist on type 'User'

Buildforce will:

  1. Analyze the error
  2. Locate the issue
  3. Fix the code
  4. Log the deviation
  5. Re-validate

Next Steps

/spec Command

Define requirements by materializing user intent into structured specifications and implementation plans.

/complete Command

Finalize features by validating requirements, generating context files, and saving knowledge to the context repository.