Skip to content
SPEED

Getting Started with SPEED

SPEED turns markdown specs into implemented, reviewed, and integrated code. This walkthrough follows the core workflow on a real project so you can see what each command does and what to expect.

Prerequisites

Section titled “Prerequisites”
  1. SPEED installed and available in your PATH.
  2. Claude CLI or another supported agent provider installed.
  3. Git initialized in your project.

1. Initialize the Project

Section titled “1. Initialize the Project”
Terminal window
speed init

SPEED creates a .speed/ runtime directory, scaffolds a speed.toml configuration file, a CLAUDE.md for agent instructions, and a product vision template at specs/product/overview.md if one doesn’t already exist.

2. Write a Spec

Section titled “2. Write a Spec”

Create a tech spec at specs/tech/search-endpoint.md:

---
title: Search Endpoint
related:
  - specs/product/overview.md
---


## Goal
Add a `searchBooks` query that returns matching books by title.


## Data Model
| Entity | Field | Type | Constraints |
|--------|-------|------|-------------|
| books  | title | TEXT | NOT NULL, indexed |


## Acceptance Criteria
- AC1: Query returns books whose title contains the search string.
- AC2: Search strings shorter than 3 characters return a validation error.


## Out of Scope
- Full-text search ranking or relevance scoring.

3. Audit and Plan

Section titled “3. Audit and Plan”
Terminal window
# Structural audit — checks sizing, required sections, vision alignment
speed audit specs/tech/search-endpoint.md


# Generate the task DAG — builds the codebase index (Layer 1), runs
# the Guardian gate, then decomposes the spec into parallel tasks
speed plan specs/tech/search-endpoint.md

The Architect identifies files to modify, draws task boundaries along domain cluster lines, and produces a DAG of tasks with acceptance criteria, file lists, and a data model contract.

4. Verify the Plan

Section titled “4. Verify the Plan”
Terminal window
speed verify

An independent Verifier reads the spec without seeing the Architect’s reasoning and checks whether the task plan actually delivers every requirement. Missing requirements surface here before any code runs.

5. Run the Agents

Section titled “5. Run the Agents”
Terminal window
speed run

SPEED spawns developer agents in isolated git worktrees, one per task. Each agent receives pre-computed context (the right source files, skeletons, and spec references) and writes code from turn one. Quality gates (syntax, lint, test) run inside each worktree as agents complete.

Check progress at any point:

Terminal window
speed status

The status output shows task progress, active agents, security findings, failure classifications, and supervisor analysis if any tasks have failed.

6. Review, Coherence, and Integrate

Section titled “6. Review, Coherence, and Integrate”
Terminal window
# Trigger code review against the original spec
speed review


# Check that independently built branches compose correctly
speed coherence


# Merge validated branches in dependency order
speed integrate

Integration runs regression tests after each merge and performs a final contract check to verify the implementation matches the Architect’s data model.

7. Security Audit

Section titled “7. Security Audit”
Terminal window
speed security

Runs Semgrep SAST, dependency SCA, and secrets scanning against the feature branch. Findings are mapped to OWASP categories with severity-based priority (critical=P0 through low=P3). Use --create-defects to automatically generate defect specs for findings above the configured threshold.

What You Learned

Section titled “What You Learned”
  • Spec-Driven Development: You controlled the codebase by editing a markdown table, not writing code.
  • High-Fidelity Context: SPEED delivered exact signatures and file references to agents, preventing hallucinations.
  • Parallelism: Independent tasks run simultaneously on separate branches with automated coherence checking.

Next Steps

Section titled “Next Steps”