Getting Started

Context Repository

Learn how Buildforce's persistent context repository accumulates project knowledge over time.

The context repository is Buildforce's persistent memory—a version-controlled directory containing YAML files that capture your project's accumulated knowledge.

What Lives in the Context Repository

.buildforce/
├── context/
│   ├── _index.yaml              # Context catalog
│   ├── authentication.yaml      # Module context
│   ├── error-handling.yaml      # Pattern context
│   ├── api-conventions.yaml     # Design decisions
│   └── database-schema.yaml     # Data model context
└── specs/
    └── [feature-folders]/       # Feature specs and plans

Context Files Capture

Architectural Decisions

Why this pattern was chosen
What alternatives were considered
Trade-offs and constraints

Design Patterns

How the pattern is implemented
Where it's used in the codebase
Examples and usage guidelines

Module Documentation

What the module does
Key files and their purposes
Dependencies and relationships
Edge cases and gotchas

Implementation Knowledge

Lessons learned from past features
Solutions to common problems
Performance optimizations
Security considerations

Context File Structure

Each context file follows a structured format:

version: "0.0.29"
id: "authentication-module"
name: "Authentication Module"
type: module              # module | feature | component | pattern
description: "JWT-based authentication with OAuth2 support"

# What this context is about
overview: |
  The authentication system uses JWT tokens with 15-minute expiration
  and refresh tokens for extended sessions. Supports email/password
  and OAuth2 (Google, GitHub).

# Key implementation decisions
key_decisions:
  - decision: "Use bcrypt for password hashing"
    rationale: "Better salt handling and security than crypto module"
  
  - decision: "15-minute JWT expiration with refresh tokens"
    rationale: "Balance between security and UX"

# Important files
file_paths:
  primary:
    - path: "src/auth/middleware.ts"
      purpose: "JWT validation middleware"
    - path: "src/auth/service.ts"
      purpose: "Authentication business logic"

# Relationships to other contexts
related_context:
  - user-management
  - api-security
  - session-handling

# Searchable tags
tags:
  - authentication
  - jwt
  - oauth2
  - security

How Context is Created

Automatic Creation via `/complete`

When you finish a feature with /complete, Buildforce:

Analyzes the completed work
- Reviews spec requirements
- Examines plan decisions
- Studies deviation log
Extracts key knowledge
- Architectural decisions
- Implementation patterns
- File relationships
- Lessons learned
Generates context files
- Creates YAML files in .buildforce/context/
- Updates _index.yaml catalog
- Adds cross-references to related contexts

Manual Creation via `/document`

For existing code or tribal knowledge:

/research [topic to understand]
/document [what to document]

Example:

/research authentication patterns in this codebase
/document authentication module

Buildforce creates context files based on conversation history and code exploration.

How Context is Searched

Via `/research` Command

/research authentication patterns in this codebase

What happens:

Searches context repository - Queries _index.yaml for relevant context files
Loads matching contexts - Reads full YAML files with decisions and patterns
Explores codebase - Discovers additional files and relationships
Fetches current info - Web search for best practices if needed
Produces report - Structured findings with file paths, diagrams, recommendations

Search matches:

Context IDs and names
Descriptions
Tags
Related contexts
File paths

Context Index (`_index.yaml`)

The index tracks all context files for fast searching:

version: 1.0

contexts:
  - id: "authentication-module"
    file: "authentication.yaml"
    type: module
    description: "JWT-based authentication with OAuth2 support"
    tags: [auth, jwt, oauth2, security]
    related_context: [user-management, api-security]

  - id: "error-handling-patterns"
    file: "error-handling.yaml"
    type: pattern
    description: "Centralized error handling with typed errors"
    tags: [errors, patterns, typescript]
    related_context: [api-conventions]

Context Grows With Your Project

Week 1: First Feature

.buildforce/context/
└── _index.yaml (1 context)
└── authentication.yaml

Month 1: Multiple Features

.buildforce/context/
├── _index.yaml (8 contexts)
├── authentication.yaml
├── authorization.yaml
├── user-management.yaml
├── api-conventions.yaml
├── error-handling.yaml
├── database-schema.yaml
├── caching-strategy.yaml
└── deployment-process.yaml

Year 1: Comprehensive Knowledge Base

.buildforce/context/
├── _index.yaml (50+ contexts)
├── modules/
│   ├── authentication.yaml
│   ├── authorization.yaml
│   └── ... (20+ modules)
├── patterns/
│   ├── error-handling.yaml
│   ├── caching-strategy.yaml
│   └── ... (15+ patterns)
└── features/
    ├── oauth2-integration.yaml
    ├── rate-limiting.yaml
    └── ... (15+ features)

Compounding KnowledgeA project with 50 context files has accumulated wisdom from dozens of features. New developers can understand architectural decisions by reading context files. AI agents can maintain consistency by loading relevant context before implementation.

Version Controlled Knowledge

Context files are plain text YAML—commit them with your code:

git add .buildforce/context/
git commit -m "Add authentication context"
git push

Benefits:

Team shared - Everyone has access to same context
History tracked - See how decisions evolved
Branched naturally - Context follows your git branches
Reviewed in PRs - Context changes reviewed alongside code
No vendor lock-in - Pure text files, works forever

Context Best Practices

Do:

✅ Create context after completing features
✅ Document important architectural decisions
✅ Use descriptive tags for searchability
✅ Link related contexts with related_context
✅ Update context when decisions change

Don't:

❌ Document trivial implementation details
❌ Duplicate information across contexts
❌ Create context for temporary code
❌ Let context files become stale

Context is DocumentationThink of context files as living documentation. They capture why decisions were made, not just what was implemented. Future you (and your team) will thank you.

Next Steps

Commands Reference - Learn all Buildforce commands
/research Command - Master context searching
/complete Command - Learn how context is generated
/document Command - Manually create context files

Command Orchestration

Learn how Buildforce commands feed context forward to create compounding knowledge.

Commands Overview

Learn about all Buildforce slash commands and when to use them.