Why specaflow exists

Managed development instead of an opaque chat

See the problem SF solves and the principles the work is built on.

When one chat is no longer enough

A model writes fast, but a conversation holds no project structure, no dependencies and no history of decisions. specaflow turns the talking into sequential work: every result stays in files, is checked on its own and becomes the ground for the next step.

💬

AI without a process

✖ Requirements live in chats — and die with the session.
✖ The model produces a giant PR nobody can read.
✖ Contradictions in the requirements surface in the code — the most expensive place to fix them.
✖ Change the model or the developer and the whole context is gone.
✖ Why it was built this way — nobody remembers any more.

📋

specaflow

✔ Requirements live in files and git: they outlive any session and any change of model.
✔ You review a small, readable set of changes after every phase.
✔ The analyze phase cross-checks the spec, the plan and the tasks — contradictions are caught on paper.
✔ Another person or another model picks up from the same place — the context is in specs/.
✔ The history of decisions is in the plan, the constitution and the retros, not in somebody’s memory.

Before the first prompt

An idea becomes the project’s context

A new project does not start from an empty chat. The intake survey walks through the product, the infrastructure, the backend, the design and the frontend — it draws out the decisions people usually remember halfway through the implementation, and hands them to drafts as structured context.

specaflow · the project intake survey

The specaflow intake survey: choosing the product type, progress through 21 questions and the Infrastructure, Backend, Design and Frontend stages

The questions depend on the kind of product. The answers, the assumptions and the deferred decisions are saved and become the starting context for everything that follows.

The full cycle on one example

A “Habit Tracker” app — from the idea to committed code. Frames advance on their own; use the dots to step manually.

the current stepthe path already walked

Draft chat · whiteboard mode

You and the AI at one whiteboard

An idea is easier to draw than to describe. A shared canvas opens beside the draft chat — and it is drawn on by both sides. You sketch a diagram or paste an annotated screenshot; when you send a message the AI receives both the structure of the board and a picture of it (vision). And it answers in kind: “sketched the architecture on the board — take a look”.

drafts · Habit Tracker — board and chat

The specaflow draft chat with the shared board: an architecture diagram React PWA → Go API → SQLite drawn by the AI, with the conversation below it

✏️

The AI draws structurally

The model does not move pixels — it sends operations: add_node, connect, insert_between, group… The server works out the coordinates; the model refers to elements by their label. After each batch it gets a fresh projection of the board and the lint findings: the model checks for itself that it drew what it meant to.

🤝

Your elements are untouchable

The courtesy is built into the tool: the AI moves its own nodes freely, and touches what you drew only after explicit permission, asked through a clarifying question. A shared board does not turn into “the AI redid everything”.

📄

The board is a file too

The scene is an ordinary excalidraw file beside the draft, saved automatically. So is the whole draft chat: the “## You / ## specaflow” transcript is markdown and lives in git with the project.

Control without micromanagement

The AI does the work, you take the decisions. No result becomes part of the project without your review.

🚦

A review after every phase

A phase has produced its result and the work stops. You look at the changes file by file: accept them into Git, or send them back for another pass with your reasons.

📁

Files are the source of truth

No database: the status of every feature is recomputed from specs/ on every request. Edit the specs with any editor or agent — the dashboard follows the files.

🔒

The code never leaves the machine

The server runs locally, and with a local model it is fully offline. Suitable for closed environments: not a line goes out unless you connect a cloud API yourself.

🌿

Git discipline

Every feature grows in its own branch. Only what you accepted reaches the Git history: no hidden commits, and everything the model did is visible and reversible.

When reality does not match the plan

The main disease of AI coding is silent drift: the plan says one thing, the code does another, and within a week the documents are lying. In specaflow a departure from the plan is a protocol, not an accident. No deviation appears without your approval, and no approved one is ever lost.

implement hits reality

The package version does not exist, the command fails, the approach in the plan does not work. The rule is hard: a deviation is never the model’s to decide. Stop, and ask the developer with options: “apply the fix (recommended)” / “skip the task” / “stop the run”.

The harness will not let it “fix it quietly”

Weak models like to “fix it and document it” without asking. So there is a hard layer above the prompt: edits to plan.md are refused until you have answered at least one question in this run.

Approved goes to disk at once

Before the coding continues: the tag [deviation] on the task in tasks.md and a line in the plan’s “## Deviations” — “plan: what was expected → fact: what was done; reason”. If the run dies, the approval is already on disk.

verify tells a deviation from drift

Code that matches a recorded deviation is normal and must not be “fixed back to the plan”. An unrecorded divergence between the code and the documents is exactly the silent drift verify exists to catch.

↻

reconcile restores agreement

The dashboard counts the unpropagated deviations and offers to run reconcile: every entry in “## Deviations” is carried into the plan’s prose, into the wording of the tasks and — if the visible behaviour changed — into the spec, and is then marked [synced]. The entries are never deleted: they are the history of the decisions. The documents tell the truth again, and the next phase starts from a state that agrees with itself.

This is what it looks like

Real screenshots from a project that went through specaflow end to end: the infrastructure, the backend and the design layer are delivered, the frontend is next in line. The numbers on the screens were computed by the tool itself. In the header is the project manager: switch between projects and connect new ones without leaving specaflow.

The project manager — this is where the work begins

specaflow — the project library

The specaflow project manager: a library of three projects, creating a new one and connecting an existing one

One running specaflow drives all your projects: switch from the header, connect an existing folder without overwriting anything, or create a new project.

Features — features by layer, with the status derived from the files

specaflow · habit-tracker — localhost:4820

The specaflow feature board: groups by the Frontend/Backend/Infrastructure layers, each feature with its strip of phases

Each card is a feature with its strip of phases: green is done, amber is in progress. Layers collapse; the current one is always on top.

The feature card — its whole path and what each phase settled

specaflow — the feature card

The card of a delivered feature: the feature passport with its lessons, the phase chips, the retro phase passport with its decisions and stumbles, and the feature’s documents

An expanded card holds the whole cycle. At the top, the feature’s passport: what was done and what lessons it left the project. Below it, the passport of the selected phase: what it settled, by what means, what it stumbled over and what it left for the next one, with the price of the run in tokens and minutes beside it. A passport outlives its run — transcripts are evicted, the record stays.

What each layer guarantees — and what proves it

specaflow — briefs and layer guarantees

The layer guarantees panel: each layer with numbers derived from run receipts — the environment, requirements with proof, mockups, states, tokens

Every layer reports numbers the tool derived from receipts, not from promises. Nothing to count is written “not proven”, never zero. The design layer has metrics of its own: how many mockups, how many states are drawn at the addresses the specification fixed, how many values are held by the token contract.

The design layer starts with a choice, not with a description

specaflow — choosing the visual direction

Choosing the visual direction: three finished samples side by side, each with a light and a dark theme on the project’s real data, and an explanation of what each will cost in the work

Almost nobody can describe a look in words — everybody recognises one. So the tool builds two or three finished samples on the project’s real data and asks you to point at yours; under each one it says what that choice will cost in the work. A free-text answer is taken as an amendment: “the second one, but darker and without shadows”. The chosen sample stays as the reference, and its values are the seed of the token contract the whole visual system grows from.

Always at hand

Specky knows the product and understands the current screen

The built-in assistant answers quick questions, explains how specaflow is put together and helps you work out what is happening to the project right now. The “+” button attaches the current tab, the open feature, the state of a run or the log of recent runs to your question.

Specky

blinks, watches the runs and changes posture with the state

Specky · a question with a web search

The Specky assistant answers a question about current Python versions using data from the web

context · what is on the screen now

Specky explains the current run: the feature, the tasks phase, the model and the files the agent is reading right now

Context on request

“What is happening right now?” — without retelling it by hand

You switch on the “what is on the screen now” chip and Specky receives a snapshot of the working state. In the example it sees that 105-analyzer-agent is in the phase tasks, knows which model was chosen, and explains which files the agent has already read.

✓the context is attached explicitly and shows as a chip of its own;
✓the answer rests on the live state of the run, not on a guess;
✓the chip comes off in one click — the next question is general again.

↔️

The conversation moves both ways

A quick question can be opened in drafts and grown into a full discussion. And the other way round: a conversation from drafts continues in the compact assistant — neither the history nor the context is lost on the way.

📎

You attach the context

With nothing attached, Specky answers as an ordinary adviser. One press shows it the current screen, the active feature, a phase’s question, the run log or a file — no hidden giant prompt.

🛡️

An adviser, not a co-pilot

The assistant is read-only: it starts no phases, creates no documents and changes no files behind your back. It can be given a model of its own or use the main profile.

Under the hood

Its own AI harness, not a wrapper

Inside specaflow is an agent harness written from scratch in Go (the standard library only, not one third-party package). It leads the model through the phases with a fixed set of a dozen tools and takes on everything that makes “just plug in an LLM” fail in production.

The tools are a fixed set

No “give the model everything and hope”: the set is small, known in advance, and the rights depend on the phase.

read_file list_files grep write_artifact edit_file ask_clarification board_apply write_file · implement run_shell · implement web_search / web_fetch search_project · RAG

ask_clarification — the clarification tool: one question, 2–5 clickable mutually exclusive options, exactly one marked “recommended”, and a free-text field always beside them. A per-phase limit keeps the model from turning the work into a questionnaire. An agent leaves a dead end with a question, not with an invention.
board_apply — eight structural drawing operations on the shared board; the server lays out the geometry itself and returns the model a projection with the lint findings.
run_shell — a whitelist of commands; anything outside it waits for your permission, and commands have a hard timeout.
search_project — search by meaning across every document of the project: one call instead of a chain of grep → read_file. How it works is below.

Protection against real LLM diseases

Every mechanism here came out of a real failure — and after it, that class of failure stopped killing runs.

⚡Circuit breaker: the same call has failed several times in a row — the harness stops executing it and demands a different approach or a question to the developer.
⚡Loop detector: the generation has degenerated into repetition — the stream is cut, the model gets a hard correction “one concrete action right now”; after N corrections the run fails honestly.
⚡The stream watchdog and round retries on network drops — an implement that runs for hours does not die of one blinking connection.
⚡History compaction: older bulky tool results are folded up — long runs fit into the context of local models.
⚡Rescuing truncated answers: a tool call cut off by the token limit is repaired rather than thrown away — the artifact that was written is not lost.
⚡The provider test: “test the connection” sends a probe tool call and tells you in advance whether this model can carry the work: native tools, separated reasoning, the model catalogue.

Plus a journal of every run on disk, limits on rounds and web requests, and a watch on how full the context window is with a warning to the agent — the boring plumbing without which agents do not survive to the end of a phase.

Built-in RAG

The project in context from the first token

An ordinary agent starts a phase blind and spends dozens of rounds leafing through files, filling the context with whatever it managed to find. specaflow has a hybrid search across the whole corpus of the project built in — specifications, plans, briefs, the constitution, the documentation: BM25 + vectors + Reciprocal Rank Fusion, written from scratch on the Go standard library. No vector database and no external services: the index is a cache in .specaflow/index/, derived entirely from the files, with changes picked up by an sha256 comparison — including after a git branch switch.

🎯

Phases start well-read

Before a phase starts, the harness pulls the relevant slice of the corpus itself and puts it in the opening prompt (a budget of about 3000 tokens). Fewer “let me read one more file” rounds, fewer tokens spent re-reading the same thing — and analyze sees cross-feature links that are not in its own feature’s artifacts.

🔍

Search by meaning — and by the letter

The tool search_project understands both “how our token rotation works” and an exact identifier like T029: the vectors look for the meaning, BM25 for the letter, and RRF merges both result sets. Every snippet is labelled with its path, heading and lines — the model must re-read the source before leaning on it.

🔌

Optional and offline

Embeddings come from any OpenAI-compatible endpoint, including a local Ollama / LM Studio / llama.cpp: the project never leaves the machine. If the embedder is unavailable, the index works lexically and finishes vectorising when it returns. With the toggle off, specaflow works exactly as before: RAG cannot break a single phase.

[index] 94 files · 739 chunks · bge-m3 · sha comparison 40 ms
[plan] pre-seed: 11 chunks · 2,987 tokens → <retrieved_context>
[agent] search_project("refresh token rotation")
[hits] specs/210-auth/plan.md · «Token rotation» · lines 84–112 · +7

Why paper comes before code

The later a defect is found, the more it costs to fix. specaflow shifts the search for defects left — into the specification and the plan, where a correction costs minutes — and cuts the review into portions somebody can actually read.

The cost of fixing a defect

relative to a correction at the specification stage*

* the classic industry estimate (Boehm; IBM Systems Sciences Institute)

What you read at review

lines in one sitting, a typical feature

specaflow splits the same feature into small portions of change you can review attentively

Flexible configuration

One model can do everything. Or each can do what it is good at

SF does not split mandatory connections — it splits three clear roles. You can give the same model every role, or pick a combination by quality, speed and cost.

Planning

Takes requirements apart, asks questions, builds decisions and checks that the documents agree. Quality of reasoning matters most here.

Producing the result

Carries the decisions taken into documents, checks and code. Precision, speed and the ability to follow a settled plan are what help here.

Assistant

Explains the current state of the project and the next actions it allows. Read-only: it changes nothing behind your back.

Every role receives the same confirmed context from the project’s files. That is why changing the model does not wipe the history of decisions.

Zero Dependencies

One binary. One command.

specaflow is a single Go executable with no external dependencies: no Docker, no Node, no Python. Download it, run it, and a window opens with the project manager built in. Connect an existing folder without overwriting anything, or create a new project right there.

$ ./specaflow
[web] http://localhost:4820 — the window is open
[projects] 3 projects · active: habit-tracker
[run] plan → artifact written
[review] waiting for your decision · 2 files changed

Any OpenAI-compatible model

Local inference or a cloud API, your choice. The built-in connection test checks that the provider really supports tool calls.

llama.cpp Ollama vLLM LM Studio OpenAI Anthropic Gemini GLM OpenRouter DeepSeek

🧠 Separate models

The clever one thinks — plans, the constitution, analysis. The fast one writes — specs, tasks and code from settled material. Savings without losing quality.

🛡 Control over execution

Shell commands outside the whitelist need your permission. Departures from the plan are recorded only after you approve them.

Metrics

What the development costs, in numbers

Every phase run leaves a trace in a journal that is never trimmed: the model, the tokens, the rounds, the retries, the machine time and how long the run waited for your answers. The “stats” tab builds a live dashboard out of it — tiles, bars by phase, a token doughnut by model, feature cycle times — in plain SVG, without a single external library, with a period filter and real-time updates at every gate.

⏱

Machine time is not calendar time

Waiting for the developer — answers to clarifications, the pause before a decision at a gate — is counted separately and subtracted. You see the honest speed: how long the model worked and how long the task sat with you. A night before a morning approval does not spoil the metric.

🧪

How the models perform

Every run is attributed to a model. The table gathers the criteria together: average rounds, retries, the share of rejects at gates, tokens, time per phase — you see which model gets the work to approval more cheaply and reliably, and which one drives its tools in circles.

🕰

The past is reconstructed from git

Projects that started earlier lose nothing: every approval has always been a commit specaflow: <phase> <feature> — the phase times, the finalizations and the age of the project are restored from the history. No database: an append-only journal plus git.

specaflow · habit-tracker — stats

effort statistics 7d 30d all time

18dproject age28.06.2026

46phase runs41 ✓ · 5 ✕

14h 20mmachine timethe model working, waiting excluded

6h 05mwaiting for the developerclarifications + gates

18.4Mtokens16.9M in · 1.5M out

machine time by phase

implement6h 40m ×9

plan2h 10m ×8

specify1h 50m ×8

verify1h 05m ×7

analyze48m ×11

reconcile40m ×9

tasks25m ×8

tokens by model

glm-5.211.1M · 60%

qwen3-coder-30b4.6M · 25%

deepseek-v3.22.7M · 15%

007-swagger2d 4h ✓

008-eng-rules13h in progress

The period filter recomputes everything instantly — the data is already on the client. Close a gate and the numbers update themselves over SSE.