FIRE Quick Start

Ship your first feature in under an hour with FIRE flow

Prerequisites

• Node.js 18+ installed
• An AI coding tool (Claude Code, Cursor, GitHub Copilot, etc.)
• A project to work on (greenfield or brownfield)

Installation

1. Install specs.md

   npx specsmd@latest install
   
2. Select FIRE flow

   When prompted, select FIRE as your development flow:

   ? Select a development flow:
     AI-DLC - Full methodology with DDD
   ❯ FIRE - Adaptive execution, brownfield & monorepo ready
     Simple - Spec generation only
   
3. Choose your AI tool

   Select your preferred AI coding tool for agent configuration

Your First Intent

1. Start the Planner Agent

In your AI coding tool, invoke the FIRE Planner:

Claude Code

/specsmd-fire-planner

Cursor

/specsmd-fire-planner

Or use the @ prefix:

@fire-planner

GitHub Copilot

@fire-planner

2. Describe Your Intent

Tell the Planner what you want to build:

I want to add user authentication with email/password login,
password reset, and session management.

The Planner will:

1. Ask clarifying questions if needed
2. Create an intent document
3. Decompose it into work items

3. Review Work Items

The Planner generates work items with recommended execution modes:

work_items:
  - id: user-schema
    title: Create user database schema
    complexity: low
    mode: autopilot      # AI executes directly

  - id: login-endpoint
    title: Implement login API endpoint
    complexity: medium
    mode: confirm        # Human confirms plan first

  - id: session-management
    title: Add session management
    complexity: high
    mode: validate       # Full review before execution

Execute Work Items

1. Start the Builder Agent

Claude Code

/specsmd-fire-builder

Cursor

/specsmd-fire-builder

Or use the @ prefix:

@fire-builder

GitHub Copilot

@fire-builder

2. Builder Picks Next Work Item

The Builder automatically selects the next work item based on dependencies:

Starting work item: user-schema
Mode: Autopilot (0 checkpoints)

Executing...

3. Execution by Mode

Autopilot Mode (0 checkpoints)

AI executes directly and generates a walkthrough:

✓ Created migration file: 20240115_create_users.sql
✓ Added User model: src/models/user.ts
✓ Updated schema exports

Walkthrough generated: walkthroughs/run-fabriqa-2026-001-user-schema.md

Confirm Mode (1 checkpoint)

AI presents plan, waits for confirmation:

Plan for: login-endpoint

1. Create POST /auth/login endpoint
2. Add password hashing with bcrypt
3. Generate JWT tokens
4. Add rate limiting

[Confirm to proceed? y/n]

Validate Mode (2 checkpoints)

AI generates design doc, waits for review, then confirmation:

Design document generated: intents/auth/work-items/session-management.md

Please review the design before proceeding.
[Review complete? y/n]

---

Implementation plan:
1. Add Redis session store
2. Implement session middleware
3. Add logout endpoint

[Approve implementation? y/n]

4. Review Walkthroughs

After each run, review the generated walkthrough:

# Run 001: user-schema

## Summary
Created user database schema with email/password authentication fields.

## Files Changed
- `migrations/20240115_create_users.sql` (created)
- `src/models/user.ts` (created)
- `src/models/index.ts` (modified)

## Key Decisions
- Used UUID for user IDs (portable across databases)
- Added soft delete with deleted_at column
- Indexed email for fast lookups

## Verification Steps
1. Run `npm run migrate` to apply schema
2. Verify table created: `SELECT * FROM users LIMIT 1`

## Test Coverage
- Unit test added: `tests/models/user.test.ts`

State Tracking

FIRE maintains state in .specs-fire/state.yaml:

project:
  name: my-project
  framework: fire-v1

workspace:
  type: brownfield
  structure: monolith
  default_mode: confirm

intents:
  - id: auth-system
    title: User Authentication
    status: in_progress
    work_items:
      - id: user-schema
        status: done
        completed_in_run: 1
      - id: login-endpoint
        status: in_progress
        started_in_run: 2
      - id: session-management
        status: pending

runs:
  last_completed: 1
  active: 2

Brownfield Projects

For existing codebases, FIRE auto-detects:

1. Quick Scan (2-5 min)

   Pattern-based detection of language, framework, and structure

2. Standards Generation

   AI generates standards matching your existing patterns:

   • Tech stack (detected frameworks, libraries)
   • Coding standards (existing conventions)
   • Folder structure (current layout)
3. Review and Confirm

   Review generated standards and adjust if needed

FIRE follows brownfield rules: search before create, respect patterns, minimal changes.

Monorepo Projects

For monorepos, FIRE supports hierarchical standards:

project/
├── .specs-fire/
│   └── standards/
│       ├── constitution.md      # Universal (always inherited)
│       └── tech-stack.md        # Default stack
│
├── packages/api/
│   └── .specs-fire/
│       └── standards/
│           └── tech-stack.md    # Override: Go, Echo
│
└── packages/web/
    └── .specs-fire/
        └── standards/
            └── tech-stack.md    # Override: React, TypeScript

Learn more in Monorepo Support.

Command Reference

Command	Description
/specsmd-fire	Entry point, routes to appropriate agent
/specsmd-fire-planner	Capture intents, decompose work items
/specsmd-fire-builder	Execute work items, generate walkthroughs

Troubleshooting

Agent doesn't remember context

Agents are stateless—they read state.yaml and artifacts at startup. Ensure files are saved after each step.

Work item stuck

Check .specs-fire/state.yaml to see work item status. If blocked, the Builder will explain what’s needed.

Want to change execution mode

You can override the suggested mode during execution. Say “Override to Confirm” or “Override to Validate”.

Brownfield detection wrong

Review generated standards in .specs-fire/standards/ and edit as needed. The Planner respects your overrides.

Multiple intents exist

Run /specsmd-fire to see all intents and their status, then specify which to work on.

Next Steps

Execution Modes

Master Autopilot, Confirm, and Validate modes

Work Items

Deep dive into work item structure

Monorepo Support

Hierarchical standards for multi-module projects

FIRE Agents

Orchestrator, Planner, and Builder details