Give Cursor, Claude Code, and Codex the project facts they need before editing.
中文 · Live demo · Introduction · Usage guide · Commands
Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable .Knowledge/ knowledge base, installs agent-specific f2s-* skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository.
npx @double-coding/flow2spec@latest initWithout a maintained, routable project memory, an agent has to rediscover the same constraints on every request. Flow2Spec keeps those facts in compact topic shards and routes each request to the topics it needs.
| Without Flow2Spec | With Flow2Spec |
|---|---|
| “Which module owns this table?” | [matcher hit] m-product-review-template-library |
| “Is batchReScore sync or async?” | [loading deps] 4 topics · ~300 lines |
| “Is there a lock? What is the idempotency key?” | Redis lock ... TTL 10 min |
| Agent searches 416 APIs, 796 files, and 4.7 MB of source before editing. | Agent reads the verified constraints first and opens the relevant files. |
Flow2Spec does not add documentation for its own sake. It keeps a small, machine-readable knowledge layer alongside the code, and lets the same skills update it when verified facts change.
| Layer | What it does | Files |
|---|---|---|
| Knowledge routing | Maps a request to the few topics the agent needs to read. | .Knowledge/manifest-routing.json, .Knowledge/matchers/*.json |
| Topic shards | Stores project facts such as APIs, limits, locks, data rules, and workflows. | .Knowledge/topics/*.md |
| Agent entrypoints | Installs rules and skills for Cursor, Claude Code, and Codex. | .cursor/, .claude/, .codex/, AGENTS.md |
| Skill workflows | Clarifies requirements, writes specs, implements, fixes, syncs knowledge, and commits. | f2s-* skills |
| Team collaboration | Keeps each developer's task state local while merging reviewed knowledge through structured deltas and topic revisions. | .task/<developerId>/, .Knowledge/ |
Flow2Spec separates collaboration state by ownership. Checklists, session context, and user todos stay under each developer's local TASK_ROOT and do not enter Git. Confirmed project knowledge remains shared in .Knowledge/.
Knowledge-producing skills write a structured kb-delta.json instead of editing topic files directly. Before apply, the CLI compares the delta's baseRevisions with the topic revisions on disk. Different topics can merge independently; concurrent changes to the same topic stop for a semantic review after the latest branch state is pulled.
Read the full model in Team Collaboration.
After initialization, you do not need to document the whole project upfront. Start with the change you actually need. The agent reads the relevant code and existing docs while it works, then saves confirmed project facts back into the knowledge base.
For an existing project, you can ask the agent to draft the project structure first:
/f2s-doc-arch
This helps the agent understand the main directories, module boundaries, and existing conventions. It is optional. For a small change, you can start directly from the request.
Most of the time, describe the task in natural language:
Add batch recalculation. It should retry failed items and avoid running the same batch twice.
The agent should look for relevant project knowledge first. If something is missing, it should explain the gap, then read the necessary code or ask you a follow-up question. Confirmed facts such as APIs, limits, locks, data rules, and workflows can be synced back into .Knowledge.
A larger change usually follows this path:
describe the requirement
→ agent fills in missing details
→ generate or review the technical spec
→ implement / fix
→ sync verified project facts
→ check knowledge coverage before commit
If you already know which workflow you want, use one of the explicit entrypoints below.
Flow2Spec's knowledge base is not meant to be finished in one pass. It grows with development:
initcreates the base skeleton.- The first time a module matters, the agent reads the relevant code and docs.
- Confirmed facts from the development process become routable topics.
- Later similar requests can hit those topics directly instead of searching the whole repository again.
The directories can be read this way:
req-docs/: technical specs and implementation plans for concrete changes.stock-docs/: stable project background, architecture notes, and imported source material.topics/: compact facts the agent should actually load.matchers/: rules that route a user request to the right topics.
Natural-language requests can select these workflows automatically when intent recognition is enabled. Use the entrypoints below when you want to choose one directly.
| Command | Purpose |
|---|---|
/f2s-req-clarify |
Clarify missing requirements until the change is unambiguous. |
/f2s-req-tech |
Turn confirmed requirements into an implementation-ready technical proposal. |
/f2s-kb-feat |
Add a capability and update project knowledge. |
/f2s-kb-fix |
Fix behavior and correct the matching knowledge. |
/f2s-kb-sync |
Sync already implemented facts into .Knowledge/. |
/f2s-kb-add <path> |
Import an existing module or document set. |
/f2s-git-commit |
Check changed files and knowledge coverage before committing. |
Full references:
- Usage guide
- Commands reference
- Directory conventions
- Architecture and principles
- Team collaboration
- Design principles
- Project milestones
Flow2Spec is useful when context drift is expensive. It may be unnecessary for:
- throwaway one-off scripts;
- tiny solo projects where one
CLAUDE.mdis enough; - teams that will not keep
.Knowledge/aligned with the code.
- Flow2Spec Introduction — product narrative, diagrams, and comparison with ordinary project memory.
- Flow2Spec 基础介绍 — Chinese long-form introduction.
- Product website — a website-style guide to Flow2Spec's core capabilities and workflow.