Workflow Overview

Buildforce uses slash commands inside AI assistant conversations to orchestrate a structured workflow. Unlike typical CLI tools executed in your terminal, Buildforce commands run within your AI chat to guide development phases.

Workflow Visualization

                     ┌─────────────────────┐
                     │ Context Repository  │
                     └─────────────────────┘
                              ↓           ↑
                        reads │           │ writes
                              │           │
    /research ────────────────┘           │
         ↓                                │
    /spec (creates spec and plan files)   |
         ↓                                │
    /build (follows the plan and builds)  │
         ↓                                │
    /complete ────────────────────────────┘

What Happens at Each Command

/research - Gather Context

Searches .buildforce/context/ for accumulated knowledge, explores codebase patterns, and searches web if needed.

Output:

• Structured report with key findings
• File paths and their relevance
• Architecture diagrams
• Data models
• Recommendations

Purpose: Load context before defining requirements.

/spec - Define Requirements

Materializes user intent into structured requirements saved as spec.yaml and actionable plan saved as plan.yaml.

Output:

• spec.yaml - Functional requirements, acceptance criteria, scope boundaries
• plan.yaml - Architecture decisions, phases, tasks
• Clarifying questions if anything is ambiguous

Purpose: Capture WHAT needs to be built and HOW to build it.

/build - Execute Implementation

Executes plan phases sequentially, updates progress, logs deviations from the plan on multiple iterations.

Output:

• Implementation following the plan
• Progress tracking (checkboxes)
• Deviation log (what changed and why)
• Testing guidance

Purpose: Build the feature with full transparency.

/complete - Finalize and Validate

Validates all requirements met, generates context files from spec+plan+implementation, updates context repository.

Output:

• Completion validation report
• New context files in .buildforce/context/
• Updated context index

Purpose: Save knowledge for future work.

/document - Create Context Files

Standalone utility for documenting existing code without full spec-driven cycle.

Output:

• Context YAML files capturing module/feature knowledge
• Updated context index

Purpose: Manual context contribution.

Three Workflow Scenarios

1. Basic Workflow (Simple Updates)

/spec → /build

When to use:

• Small bug fixes
• Simple feature additions
• Refactoring with clear scope

Skip /research when you don't need existing context.
Skip /complete when the change doesn't add significant knowledge.

2. Full Workflow (New Features & Bug Fixes)

/research → /spec → /build → /complete

When to use:

• New features with architectural decisions
• Complex bug fixes requiring investigation
• Changes that affect multiple modules
• Work that should be documented for the team

Recommended for most feature development.

3. Documentation Workflow (Manual Context)

/research [topic] → /document [module]

When to use:

• Documenting existing code
• Capturing tribal knowledge
• Creating context for legacy systems
• Building context repository for new team members

No spec or build - just exploring and documenting.

Command Orchestration

The key insight: Commands feed context forward.

1. Research informs spec - Context findings guide requirement definitions
2. Spec guides plan - Requirements determine implementation approach
3. Plan drives build - Structured tasks with progress tracking
4. Build enriches context - Implementation decisions captured for future work

This orchestration prevents context loss and creates knowledge that compounds over time.

Where Files Live

project-root/
├── .buildforce/
│   ├── context/              # Context repository
│   │   ├── _index.yaml       # Context catalog
│   │   ├── auth-module.yaml  # Module contexts
│   │   └── api-patterns.yaml # Pattern contexts
│   ├── specs/                # Feature specs and plans
│   │   └── add-auth-jwt-20250105120000/
│   │       ├── spec.yaml     # Requirements
│   │       ├── plan.yaml     # Implementation plan
│   │       └── research.yaml # Research findings (optional)
│   └── buildforce.json       # Configuration
└── [your code]

Next Steps

• Command Orchestration - Deep dive into how commands feed context forward
• Context Repository - Learn how persistent context works
• Commands Reference - Detailed documentation for each command