Consistent, reliable and efficient framework for AI-assisted engineering
Buildforce brings engineering discipline to AI-assisted development through CLI initialization and slash commands for AI coding agents.
It materializes user intent into structured specifications, generates actionable plans, and tracks execution with full traceability. By creating a persistent context repository that accumulates important context across sessions, it enables AI agents to make reliable decisions and maintain architectural consistency as your project grows.
Instead of re-explaining architectural decisions every time you start a new feature, Buildforce preserves them within your repository where they are automatically referenced by your AI agent.
AI agents typically start fresh with each session, often leading to inconsistent implementations or "amnesic" behavior where past decisions are forgotten. Buildforce solves this by anchoring your AI assistant to your project's accumulated history.
This approach ensures:
- Consistency: New features align with existing patterns and architecture.
- Reliability: Requirements are captured and validated before code is written.
- Efficiency: Less time spent re-explaining context, more time building.
Context persists in version-controlled YAML files alongside your code, so your project's context repository grows smarter with every feature you complete.
| AI Assistant only | AI Assistant + Buildforce |
|---|---|
| Context lost after each session | Context persists in .buildforce/context/ |
| No workflow structure | Flexible but structured workflows |
| Requirements exist only in conversation | User intent captured in spec.yaml with acceptance criteria |
| Plans exist only in specific modes | The captured intent is automatically converted into a plan for iteration |
| Implementation deviations go untracked | Deviations logged with rationale (Original → Actual → Reason) |
| Architectural decisions forgotten | Decisions preserved, searchable, and enforced via _guidelines.yaml |
| Knowledge lives in individual developer heads | Shared context repository for team-wide knowledge |
| Each feature starts from scratch | Each feature builds on accumulated project context |
Install the @buildforce/cli package globally:
npm install -g @buildforce/cliThen initialize in a project:
buildforce init .Initialize a new project:
buildforce init my-projectOr with npx:
npx @buildforce/cli init .
To upgrade an existing Buildforce project to the latest version:
buildforce upgradeThe upgrade command will:
- Interactively prompt you to select or modify your AI assistants (matching the init experience)
- Update slash command templates to the latest versions
- Preserve your existing configuration while allowing you to modify it
- Pre-select your currently configured AI assistants for easy modification
Options:
# Skip the interactive prompt and merge specific AI assistant(s)
buildforce upgrade --ai claude
# Specify script type (sh/bash/ps/cmd)
buildforce upgrade --script sh
# Debug mode for troubleshooting
buildforce upgrade --debugOpen your AI assistant (Claude Code, Cursor, etc.) in any existing project and run:
/buildforce.research the architecture and structure of this codebase
/buildforce.plan Update README.md to fix any inconsistencies with actual project structure and features
/buildforce.build
/buildforce.complete
This workflow works on any codebase! Buildforce will analyze your project, identify inconsistencies, and fix them systematically. Context from /buildforce.research informs your spec. Spec requirements guide the plan. Build executes with deviation tracking. Completion validates everything and saves knowledge to your context repository for future work.
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
│ │
/buildforce.research ─────┘ │
↓ │
/buildforce.plan (creates artifacts) |
↓ │
/buildforce.build (implements plan) │
↓ │
/buildforce.complete ─────────────────┘
What happens at each command:
/buildforce.research: Searches.buildforce/context/for accumulated knowledge, explores codebase patterns, and fetches external info if needed./buildforce.plan: Materializes user intent into structured requirements (functional, non-functional, acceptance criteria) saved asspec.yamland actionable plan saved asplan.yaml. Loads_guidelines.yamlas highest-priority context./buildforce.build: Executes plan phases sequentially, updates progress, and logs deviations from the plan. Validates code compliance against guidelines if_guidelines.yamlexists./buildforce.complete: Validates that all requirements are met, generates context files from the work done, and updates the context repository./buildforce.document: Standalone utility for documenting existing code. Use/buildforce.document guidelinesto capture project conventions.
Workflow scenarios:
-
Basic workflow (recommended for simple updates):
/buildforce.plan → /buildforce.build -
Full workflow (recommended for new features and bug fixes):
/buildforce.research → /buildforce.plan → /buildforce.build → /buildforce.complete -
Documentation workflow (manual context contribution):
/buildforce.research [topic] → /buildforce.document [module] -
Guidelines workflow (capture and enforce conventions):
/buildforce.document guidelines → /buildforce.plan [feature] → /buildforce.build → /buildforce.complete -
Standalone workflow (quick ad-hoc changes without session):
/buildforce.build [describe your change]When no active session exists,
/buildforce.buildenters standalone mode—exploring the codebase, presenting a quick plan, asking for confirmation, and optionally creating context files for significant changes.
The key insight: Buildforce isn't just about individual commands. It's about how commands feed context forward (research informs planning, planning guides build, build enriches context). This orchestration prevents context loss and creates knowledge that compounds over time.
Purpose: Search accumulated project context, explore codebase patterns, and fetch current information.
Usage:
/buildforce.research <your-query>
Examples:
/buildforce.research authentication patterns in this codebase
/buildforce.research current best practices for error handling in Express.js 2025
/buildforce.research how pagination is implemented in our API
What it does:
Searches your project's accumulated context repository first, then explores your codebase and fetches current information from the web when needed. Produces a structured report with file paths, architecture diagrams, data models, and actionable recommendations. Research findings persist in conversation history and can be materialized into structured artifacts during planning, ensuring your work is always informed by existing patterns and best practices.
Pro tip: Run /buildforce.research before /buildforce.plan to ensure plans are informed by existing patterns.
Purpose: Materialize user intent into a structured specification defining WHAT needs to be built and HOW to build it.
Usage:
/buildforce.plan <feature-description>
Examples:
/buildforce.plan Add JWT-based authentication with email/password login and token refresh
/buildforce.plan Fix pagination bug where last page returns empty results
/buildforce.plan Refactor user service to use repository pattern with dependency injection
What it does:
Converts your feature description into a structured specification with clear requirements, acceptance criteria, and scope boundaries. Creates both a spec.yaml (defining WHAT to build) and plan.yaml (defining HOW to build it) in a timestamped folder. If you've done research beforehand, it intelligently materializes those findings into a structured file. When requirements are unclear, it asks clarifying questions to ensure everyone's aligned before implementation begins.
Pro tip: Run /buildforce.plan multiple times to refine requirements. Since artifacts are persisted, you can perform intentional compaction: clear your context window or start a fresh session, then run /buildforce.plan again to resume with a clean slate.
Purpose: Execute implementation with automatic mode detection—follows an established plan when a session exists, or provides a lightweight standalone flow for quick ad-hoc changes.
Usage:
/buildforce.build [instructions]
Dual-mode behavior:
- With active session (after
/buildforce.plan): Executes the plan with progress tracking, deviation logging, and validation against spec requirements. - Without active session (standalone mode): Explores the codebase, presents a quick plan, asks for confirmation, implements, and optionally creates context files for significant changes.
Examples (with session):
/buildforce.build
/buildforce.build Change axios to fetch for HTTP requests
/buildforce.build Add validation for empty email field
Examples (standalone mode):
/buildforce.build Add retry logic to API calls
/buildforce.build Fix the null check in user validation
/buildforce.build Add logging to the init command
What it does:
When a session exists, executes your implementation following the spec and plan, checking off tasks as work progresses and logging any deviations from the original approach. Validates the work against both requirements and plan steps, runs tests, and provides clear guidance on what still needs verification.
When no session exists, enters standalone mode: explores affected files, presents a simple plan (goal, files, approach, risks), asks for confirmation before implementing, and creates context files for significant changes. This preserves buildforce's intelligent approach for quick tasks without the ceremony of a full spec-driven workflow.
Pro tip: Use standalone mode for quick fixes, small features, or targeted improvements. For complex changes affecting multiple files or architectural decisions, the full workflow (/buildforce.plan → /buildforce.build) provides better traceability.
Purpose: Finalize feature by validating requirements, generating context files, and clearing active session state.
Usage:
/buildforce.complete [optional-final-notes]
What it does:
Validates that all requirements are met, reviews the deviation log, and generates a comprehensive completion report. Captures the knowledge from your feature (design decisions, key files, implementation choices) into structured context files that live in your project's context repository. Updates cross-references and clears the active session state. Once complete, this feature's knowledge becomes searchable for future work.
Pro tip: Don't rush to /buildforce.complete. Validate thoroughly first. Once complete, the feature knowledge enters your context repository and will inform future /buildforce.research queries.
Purpose: Document existing functionality without a full workflow cycle.
Usage:
/buildforce.document <topic-or-module>
Examples:
/buildforce.document authentication module
/buildforce.document error handling patterns
/buildforce.document database connection pooling strategy
What it does:
Creates or updates structured context files in your project's knowledge repository by analyzing conversation history. Works independently of the main workflow—perfect for documenting existing code, architectural patterns, or legacy components. Intelligently determines whether to create new files or update existing ones, automatically resolves naming conflicts, and maintains cross-references.
Pro tip: Prepare context window first (read files, discuss architecture) before running /buildforce.document. The command analyzes conversation history to extract documentation.
Guidelines Mode: Capture project-wide conventions and coding standards using /buildforce.document guidelines. Creates or updates _guidelines.yaml with architectural patterns, naming conventions, and code standards that AI agents enforce during /buildforce.build. Three workflows available:
/buildforce.document guidelines
Creates or updates guidelines from conversation (manual mode). Discuss conventions in chat, then run command to capture them.
/buildforce.document scan guidelines
Bootstrap initial guidelines by analyzing existing codebase patterns (scan mode). Detects consistent patterns across 5+ files with 95%+ consistency.
Enforcement levels:
- strict: Build fails on violation (use for critical conventions)
- recommended: Logs warnings only (use for best practices)
- reference: Context only, no validation (use for informational patterns)
Guidelines are loaded during /buildforce.plan (as planning context), validated during /buildforce.build (code compliance check), and can auto-evolve via /buildforce.complete (pattern detection).
Buildforce supports managing multiple development sessions simultaneously. Each session tracks a distinct feature or task with its own spec, plan, and research artifacts. Use the buildforce session CLI command to switch between active sessions:
buildforce sessionWhat it does:
Opens an interactive picker displaying all active development sessions (draft or in-progress status). Navigate with arrow keys, press Enter to switch to the selected session. The currently active session is marked with a green indicator.
Example workflow:
# Start multiple features
/buildforce.plan Add user authentication with JWT
# Switch to work on something else
/buildforce.plan Implement caching layer for API responses
# Switch back to first feature
buildforce session
# (Select "Add user authentication with JWT" from picker)
/buildforce.build
# Continues work on authentication featureWhen to use:
- You need to pause one feature to handle urgent work on another
- You're maintaining multiple features in parallel (development, bugfix, refactor)
- You want to resume work on a previously paused session
Note: Only sessions with status draft or in-progress appear in the picker. Completed sessions are automatically filtered out.
Buildforce works with 11 AI coding agents: Claude Code, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, Windsurf, Kilo Code, Roo Code and Auggie CLI.
However, at the moment, not all of them are fully tested. That's why we recommend using Claude Code or Cursor if you are just getting started.
But if you prefer some of the other supported agents, please give it a try and submit an issue if you see something that doesn't work as expected. Open a new issue if you want to add a new agent to the list.
How configuration works:
Buildforce installs slash command files (research.md, plan.md, build.md, complete.md, document.md) into your chosen assistant's configuration folder during initialization. Commands become available in your AI chat via /buildforce.research, /buildforce.plan, etc. All templates and scripts are copied to .buildforce/ in your project directory. You can switch assistants later by manually copying command files between folders.
Buildforce is open source and welcomes contributions! We're building the future of AI-assisted development together.
git clone https://github.com/berserkdisruptors/buildforce-cli.git
cd buildforce-cli
npm install
npm run build
npm link- Check existing issues - View open issues
- Create an issue - Describe the problem or feature request
- Fork & branch - Create a feature branch following our naming convention
- Use Buildforce for development - Follow the structured workflow
- Test locally -
npm linkand test your changes - Submit PR - Describe your changes and link related issues
- Website: https://buildforce.dev - Learn more about Buildforce
- GitHub Repository: https://github.com/berserkdisruptors/buildforce-cli
- npm Package: https://www.npmjs.com/package/@buildforce/cli
- GitHub Issues: Report bugs or request features
- Discussions: Ask questions or share ideas
Apache License 2.0 License - see LICENSE for details.
If Buildforce helps you build better software with AI assistants, please star the project on GitHub. It helps us reach more developers and build a stronger community.
Made with 💪 by Berserk Disruptors
Building the future of AI-assisted development, one context file at a time.