Command Orchestration

Buildforce isn't just about individual commands—it's about how commands feed context forward to create knowledge that compounds over time.

The Context Flow

Each command in the workflow builds on the output of previous commands:

graph LR
    A[Context Repository] --> B[/research]
    B --> C[/spec]
    C --> D[/build]
    D --> E[/complete]
    E --> A
    
    style A fill:#4ade80
    style B fill:#60a5fa
    style C fill:#a78bfa
    style D fill:#f472b6
    style E fill:#fb923c

How Commands Feed Forward

1. Research → Spec

Research Output:

• File paths and architecture diagrams
• Existing patterns and conventions
• Related features and implementations
• Current best practices

Spec Input: Research findings inform requirement definitions:

• Requirements reference existing patterns
• Scope boundaries consider related features
• Design principles align with documented conventions
• Open questions address discovered ambiguities

Example:

# Research finds authentication uses JWT pattern
# Spec requirement references this:
functional_requirements:
  - FR1: "Implement OAuth2 login following existing JWT auth pattern"

2. Spec → Plan

Spec Output:

• Functional requirements (WHAT to build)
• Non-functional requirements (performance, security, etc.)
• Acceptance criteria (how success is measured)
• Scope boundaries (what's in/out)

Plan Input: Requirements guide implementation approach:

• Architecture decisions support requirements
• Phases break down requirements into tasks
• Each task links back to spec requirements via spec_refs
• Validation criteria map to acceptance criteria

Example:

# Spec defines FR1: "Add user authentication"
# Plan task references it:
tasks:
  - [ ] Create authentication middleware
    spec_refs: [FR1]
    files: [src/middleware/auth.ts]

3. Plan → Build

Plan Output:

• Architecture overview and technical decisions
• Phased implementation tasks
• File structure (create/modify lists)
• Testing guidance

Build Input: Plan guides systematic implementation:

• Tasks executed in phase order
• Progress tracked with checkboxes
• Deviations logged when approach changes
• Validation ensures plan requirements met

Example:

# Plan defines Phase 1: Setup middleware
# Build checks off tasks:
phase_1:
  tasks:
    - [x] Create authentication middleware  # ✓ Completed
    - [x] Add JWT token validation         # ✓ Completed

4. Build → Complete

Build Output:

• Implemented code following plan
• Progress tracking (completed tasks)
• Deviation log (what changed and why)
• Testing results

Complete Input: Build output validates completeness:

• Verify all requirements met
• Review deviation log for insights
• Extract architectural decisions
• Generate context files

Example:

# Build logged deviation
deviations:
  - phase: "phase_1"
    task: "Use bcrypt for hashing"
    original: "Use crypto module"
    actual: "Used bcrypt library"
    reason: "Better security and salt handling"

# Complete captures this as context
architectural_decisions:
  - pattern: "Password Hashing with bcrypt"
    rationale: "Chose bcrypt over crypto for better salt handling"

5. Complete → Context Repository

Complete Output:

• Validation report
• Context files capturing decisions
• Updated context index

Context Repository Input: Knowledge saved for future work:

• Architectural decisions become searchable
• Implementation patterns documented
• Edge cases and solutions captured
• Cross-references to related contexts

Example:

# Context file created in .buildforce/context/
id: authentication-module
type: module
description: "JWT-based authentication with OAuth2 support"

key_decisions:
  - "Use bcrypt for password hashing (better salt handling)"
  - "JWT tokens expire after 15 minutes with refresh tokens"

related_context:
  - user-management
  - api-security

Context Compounding

The magic happens when you complete multiple features:

Feature 1: Add Authentication

• Research: Limited context, explores codebase
• Complete: Saves auth patterns to context

Feature 2: Add Authorization

• Research: Finds auth patterns from Feature 1
• Spec: References existing JWT approach
• Complete: Saves authorization patterns

Feature 3: Add User Roles

• Research: Finds auth + authorization patterns
• Spec: Builds on established patterns
• Complete: Enriches context with role management

Result: Each feature builds on accumulated knowledge. By Feature 3, your context repository knows:

• How authentication works
• Where authorization logic lives
• Conventions for security-related features
• Edge cases already solved

Preventing Context Loss

Without orchestration, context evaporates:

Session 1: Build auth → Context lost
Session 2: Build authorization → Rediscover auth patterns
Session 3: Add roles → Rediscover both again

With orchestration, context persists:

Session 1: /research → /spec → /build → /complete (saves auth context)
Session 2: /research (loads auth context) → /spec → /build → /complete (saves authorization context)
Session 3: /research (loads both contexts) → /spec → /build → /complete (saves roles context)

Breaking the Chain (When to Skip Commands)

The full workflow is recommended but not required:

Skip /research when:

• No existing context is relevant
• Small bug fix with clear scope
• You already understand the context

Skip /complete when:

• Change doesn't add significant knowledge
• Temporary fix or experiment
• Documentation burden exceeds value

Always run /spec and /build for:

• Feature development
• Non-trivial bug fixes
• Refactoring with architectural impact

Next Steps

• Context Repository - Deep dive into how context is stored and searched
• Commands Reference - Learn each command in detail
• /research Command - Master context gathering