SpecFlow

Quick Start

If you used the installer, init has already run. After manual setup, once the binaries are in place and specflow/ is in your repository, run from the project root:

<specflow-binary> init

<specflow-binary> means the platform-matching specflowctl executable under specflow/tooling/bin/. See tooling/README.md for exact filenames.

init installs the basic structure:

• AGENTS.md, GEMINI.md, and CLAUDE.md
• docs/specs/
• other workflow support files

After this step, choose an Adoption Mode. init prepares the shared skeleton; it does not require you to run the whole lifecycle immediately.

For daily work, use standard commands with the module name you want to work on:

unit_new:{module_name}
unit_check:{module_name}
unit_fork:{module_name}
unit_verify:{module_name}

When unsure, fall back to natural language:

I want to add rate limiting to auth, but I am not sure what should move first. Read current project truth and tell me the next step.

The agent reads the installed entry files and current repository truth, then decides which command to enter, whether to write Spec truth, check a boundary, or ask a required clarification.

Advanced Usage

Adoption Modes

You can start small. Installing specFlow does not commit a project to promotion, stable verification, governance review, or full lifecycle use.

The formal contract is specflow/framework/core/adoption_modes.md. These modes are entry choices, not new lifecycle states, process schema, or CLI mode switches. Promotion, stable verification, and governance review remain explicit later choices, not default requirements for these starts.

Example reader-only start:

<specflow-reader-binary> --repo-root . --addr 127.0.0.1:17863

Example implementation-only request:

Make the existing retry test less flaky without changing the documented behavior. If this needs truth changes, stop and tell me the smallest specFlow step.

Example single-unit trial:

Use specFlow only for the payment_retry unit for now. Do not promote or enter governance review unless I ask.

Example unit-check-only request:

Run unit_check:payment_retry and stop after the check result. Do not plan or implement yet.

Development Workflow