Buildforce Logo
Commands

/spec Command

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

The /spec command materializes user intent into structured specifications defining WHAT needs to be built and HOW to build it.

Purpose

Convert feature descriptions into structured spec.yaml (requirements) and plan.yaml (implementation approach) files.

Usage

/spec <feature-description>

Examples

# New feature
/spec Add JWT-based authentication with email/password login and token refresh

# Bug fix
/spec Fix pagination bug where last page returns empty results

# Refactoring
/spec Refactor user service to use repository pattern with dependency injection

# Performance optimization
/spec Optimize API response time by adding Redis caching layer

# Documentation
/spec Update API documentation to include new authentication endpoints

What It Does

When you run /spec, Buildforce:

  1. Analyzes your description
    • Extracts intent and scope
    • Identifies functional and non-functional requirements
    • Determines architectural needs
  2. Checks for existing spec
    • CREATE mode: Generates new spec folder with timestamp
    • UPDATE mode: Loads existing spec for iteration
  3. Materializes research (if exists)
    • Converts research findings into research.yaml
    • Preserves diagrams, data models, and code snippets
    • Links research context to spec
  4. Creates spec.yaml (WHAT to build)
    • Problem statement and motivation
    • Functional requirements (FR1, FR2, ...)
    • Non-functional requirements (NFR1, NFR2, ...)
    • Acceptance criteria (AC1, AC2, ...)
    • Scope boundaries (in/out of scope)
    • Design principles
    • Open questions
  5. Creates plan.yaml (HOW to build)
    • Architecture overview
    • Technology stack and decisions
    • File structure (create/modify)
    • Implementation phases with tasks
    • Testing guidance
    • Validation criteria
  6. Asks clarifying questions
    • Identifies ambiguities
    • Presents structured questions with options
    • Waits for answers before presenting plan

Spec Structure

spec.yaml - Requirements (WHAT)

id: "add-auth-jwt-20250105120000"
name: "Add JWT Authentication"
type: feature
status: draft

# WHAT problem are we solving?
problem: |
  Users cannot securely authenticate. Need JWT-based auth.

# WHY build this?
motivation: |
  Enable secure API access with stateless authentication.

# REQUIREMENTS
functional_requirements:
  - FR1: "Email/password login returns JWT token"
  - FR2: "Token refresh endpoint for expired tokens"
  - FR3: "Middleware validates JWT on protected routes"

non_functional_requirements:
  - NFR1: "Tokens expire after 15 minutes"
  - NFR2: "Password hashing uses bcrypt with salt rounds ≥ 10"

# HOW will we measure success?
acceptance_criteria:
  - AC1: "User can login with valid credentials and receive JWT"
  - AC2: "Invalid credentials return 401 Unauthorized"
  - AC3: "Expired tokens are rejected by middleware"

# WHAT is in/out of scope?
in_scope:
  - Email/password authentication
  - JWT token generation and validation
  - Token refresh mechanism

out_of_scope:
  - OAuth2 third-party login (future work)
  - Two-factor authentication
  - Password reset flow

plan.yaml - Implementation (HOW)

id: "add-auth-jwt-20250105120000-plan"
spec_id: "add-auth-jwt-20250105120000"

# HOW will we implement this?
approach: |
  Create authentication middleware using jsonwebtoken library.
  Store password hashes with bcrypt. Implement token refresh endpoint.

technology_stack:
  - "jsonwebtoken - JWT generation and validation"
  - "bcrypt - Password hashing"
  - "express-jwt - Express middleware integration"

# WHAT are the key decisions?
decisions:
  - decision: "Use jsonwebtoken library"
    rationale: "Industry standard, well maintained, 18M weekly downloads"

# WHAT files will we touch?
files_to_create:
  - src/auth/middleware.ts
  - src/auth/service.ts
  - src/auth/routes.ts

# HOW will we build this in phases?
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]

phase_2:
  name: "JWT Integration"
  tasks:
    - [ ] Create JWT middleware
      spec_refs: [FR3]
      files: [src/auth/middleware.ts]

CREATE vs UPDATE Mode

CREATE Mode (New Spec)

First time running /spec:

/spec Add authentication system

Result:

  • Creates timestamped folder: add-authentication-20250105120000/
  • Generates spec.yaml and plan.yaml
  • Sets status to "draft"

UPDATE Mode (Iterate on Existing)

Subsequent /spec calls:

/spec Add OAuth2 Google login to authentication

Result:

  • Loads existing spec from folder
  • Updates spec.yaml with new requirements (FR5, FR6, ...)
  • Updates plan.yaml with new phases/tasks
  • Reports what changed
Iterate FreelyRun /spec multiple times to refine requirements. Each iteration updates both files without losing previous work.

Clarifying Questions

If your description is ambiguous, Buildforce asks structured questions:

/spec Add caching to improve performance

Buildforce responds:

1. What should be cached? A. Database query results B. API responses C. Computed values X. Other (please specify)

2. Which caching technology? A. Redis B. Memcached C. In-memory (node-cache) X. Other (please specify)

3. What should be the cache expiration time? A. 5 minutes B. 1 hour C. 24 hours X. Other (please specify)

After answering, Buildforce updates the spec and presents the implementation plan.

Pro Tips

Be Specific

# ❌ Vague
/spec Add authentication

# ✅ Specific
/spec Add JWT-based authentication with email/password login, 15-minute token expiration, and refresh token support

Include Non-Functional Requirements

# ✅ Includes performance and security needs
/spec Add user search endpoint with pagination, max 50 results per page, response time < 200ms, and SQL injection protection

Run /research First

# Load context before defining requirements
/research authentication patterns in this codebase
/spec Add OAuth2 login following existing JWT pattern

Iterate Multiple Times

# First iteration
/spec Add user registration

# Review spec, then refine
/spec Add email verification to registration flow

# Review again, then refine
/spec Add rate limiting to registration endpoint (5 attempts per hour)

Spec Folder Structure

After running /spec:

.buildforce/specs/add-auth-jwt-20250105120000/
├── research.yaml   # Research findings (if /research was run)
├── spec.yaml       # Requirements (WHAT to build)
└── plan.yaml       # Implementation plan (HOW to build)

Next Steps

/research Command

Gather context before defining requirements by searching your context repository and exploring your codebase.

/build Command

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