specflo

Good engineering practice, built into your coding agent.

specflo takes each feature through brainstorm, research, spec, plan and execute. Your agent asks the questions a good engineer would ask, checks the facts, writes testable requirements, and builds one verified task at a time. You get the feature you specified, not a vibe-coded guess.

pip install specflo
Start your first project View on GitHub

Free and open source (GPL-3.0). Python 3.12 or later. Works with Claude Code and pi. opencode and Hermes get the skills.

Clear context any time. The plan stays. Example
You, in a fresh session

Continue the specflo project.

  1. $ specflo status
  2. Project: Payment retries (payment-retries)
  3. Dir: docs/projects/payment-retries
  4. Phase: execute
  5. Execution: linear
  6. Level: full
  7. Tasks: 2/4 done | next: T-03, T-04
  8. Next: Work the next task: T-03, T-04 (`specflo task show`).
  9. Resume: specflo checkpoint
  10. $ specflo task show
  11. T-03 - Send the order id as the idempotency key on every retry [pending]
  12. Acceptance: Two retries of one order send the same key.
  13. Verify: pytest tests/test_charge.py -k idempotency
  14. Implements: REQ-03

specflo saves a checkpoint after every step. A fresh session reads the phase, the next task and the check that proves it, and carries on.

How it works

Each feature moves through four phases. The CLI checks each phase's document before the work moves on, so a gap in the thinking shows up before the code. Small changes take a shorter path: a quick project is one goal and one check, and a fast project is 3 to 7 tasks.

The pipeline
  1. 1
    Brainstorm

    The agent researches what already exists, then asks you one question at a time, each with a recommended answer. It records each answer as a decision (D-NN).

  2. 2
    Spec

    The decisions become testable requirements (REQ-NN), each traced to the decision behind it.

  3. 3
    Plan

    The requirements become dependency-ordered tasks (T-NN), each with an acceptance criterion and a verify step.

  4. 4
    Execute

    The agent builds one task at a time, runs its verify step and commits. The project completes only after a final review in a fresh context passes.

Research before decisions

Every brainstorm starts with a scan of the tools, libraries and earlier work that already exist. Before a decision that depends on a fact, the agent checks it. A research subagent does the searching, so the noise stays out of your conversation.

Automatic checkpoints

specflo rewrites checkpoint.md after every state change, so you can clear context at any point. The Claude Code hook puts a fresh session back on the plan. Once context use passes your threshold, the pi extension offers a clear at the next finished task or phase. In an auto run it clears by itself.

Gates stop the line early

specflo advance validates the current phase's document before it moves on. A hole in the spec stops the work before execute, not in the middle of it.

Small steps, smaller models

The agent only has to reason about the next small, checked step. That makes real work practical with smaller local models such as Qwen3.6 27B.

Review rounds that track findings

The reviewer records each finding as a blocker, should-fix or nit. Each blocker and should-fix item gets a fix task, and the next round checks that the fix holds.

Every step is a markdown file

Projects live under docs/projects/<slug>/ in your repo. You can read them, diff them and review them in a pull request. The agent writes them through the CLI, so the IDs stay stable and the format stays valid.

docs/projects/payment-retries/plan.md
---
project: payment-retries
phase: plan
status: complete
created: 2026-10-11
---

# Plan: Payment retries

## Approach

Schedule first, then the backoff and the limit, then the
idempotency key on the charge call.

## Tasks

### T-02 — Back off 1 h, 6 h, 24 h and stop after the third retry
- Acceptance: Three failed retries end with the order payment_failed and no fourth retry.
- Verify: pytest tests/test_retries.py -k backoff
- Implements: REQ-02
- Depends on: T-01
- Progress: done

### T-03 — Send the order id as the idempotency key on every retry
- Acceptance: Two retries of one order send the same key.
- Verify: pytest tests/test_charge.py -k idempotency
- Implements: REQ-03
- Depends on: T-01
- Progress: pending

Get started

Install the CLI, set up your repo, and start a project. Then start your agent: with the hook installed, it reads the new project and asks whether to continue.

Terminal 
pip install specflo
specflo init
specflo skills install
specflo hook install
specflo new "my first project"
Or let your agent do the setup. Point it at the repo and ask:

Set up specflo from https://github.com/TacoTakumi/specflo in this repo.

Not on Claude Code?

For pi, run specflo extension install in place of specflo hook install. opencode and Hermes get the skills, and any other harness can drive the plain CLI.

Small change?

Use specflo new "fix" --level quick for one goal and one check, or --level fast for 3 to 7 tasks.

Something not working?

specflo doctor checks the setup and names the command that fixes each problem it finds.

Then tell your agent:

We use specflo here. Run specflo guide and add its note to my memory file.

Pairs with Agent Wiki

Agent Wiki is a markdown vault your coding agents search before they go to the web. specflo uses it as its research memory: research reads what the wiki already knows and saves what it finds back, so each project starts from what the last one learned.

Visit the Agent Wiki site Agent Wiki on GitHub
Where specflo uses the wiki
  • Brainstorm specflo-brainstorm

    Every brainstorm starts with a research scan, and that scan reads the wiki first. Earlier decisions and findings are in front of the agent before its first question. Each fact check before a decision starts from the wiki too.

  • Research specflo-research

    Starts from the wiki, checks it against the web, and saves the findings back with their sources and dates.

  • No wiki?

    The wiki is optional. Without it, research uses the web only.