@double-codeing/flow2spec

Flow2Spec — Let AI Always Know What You're Doing

Cures the "amnesia" of Cursor / Claude Code — with one init command, AI remembers project context across sessions. No more re-explaining every time.

🌐 中文 · EN / 中

🎬 Live Demo (13-slide HTML PPT, ← → to navigate, S for presenter mode)

📖 Flow2Spec Introduction · 基础介绍（中文） — long-form article: why Flow2Spec, knowledge graph vs project memory, with diagrams

🔧 Quick start:

npx @double-codeing/flow2spec@latest init

Before / After

The exact same request, two conversations:

> Update the batch re-scoring of the review template library

Without Flow2Spec:

AI: Which module has this table?
AI: Is batchReScore sync or async?
AI: Is there a lock? What's the idempotency key?
AI: What's the response format? What's the error code?
AI: (Digging through 416 APIs, 796 files, 4.7 MB of source code…)

Repeated introductions · Repeated code searches · Repeated mistakes

With Flow2Spec:

[matcher hit] m-product-review-template-library
[loading deps] 4 topics · ~300 lines
AI: Known — fire-and-forget
     Redis lock smp:product-review:template-library:batch-rescore:lock (TTL 10 min)
     Max 100 items per batch · error code 101
AI: Starting implementation, 3 files affected.

4.7 MB → 300 lines · Pinpoint accuracy in seconds

What Flow2Spec Does

① Remembers project context across sessions .Knowledge/ structured knowledge base: routing manifest (manifest-routing.json) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant — 4.7 MB of source code compressed to ~300 lines of precise context.

② Routing manifest means AI doesn't dig through your repo Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock keys, error codes, batch limits — are all in the topics. AI doesn't have to guess from source code.

③ f2s- skills update knowledge as you code* /f2s-kb-feat writes topics while writing features, /f2s-kb-fix corrects topics while fixing bugs, /f2s-git-commit checks topic coverage before committing. Changing code == updating knowledge. No separate "documentation maintenance."

④ Full pipeline from requirements to code /f2s-req-clarify asks questions until requirements are unambiguous. /f2s-req-tech generates a ready-to-implement technical proposal into req-docs/. AI implements from the proposal — no relying on verbal agreements.

⑤ Task checklists track progress across sessions When changeTracking is enabled, skills like f2s-kb-feat / f2s-kb-fix automatically create a task.md with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into user-todos.md, separate from AI steps.

⑥ Document-driven: PDF / MD straight into the knowledge base /f2s-kb-add aggregates source files into draft → final → topics. /f2s-doc-final converts any PDF or MD into the canonical final-draft format. External docs and legacy proposals all become routable knowledge.

Getting Started

Minimum viable setup is an empty skeleton.

npx @double-codeing/flow2spec@latest init

1 minute generates the directory structure + routing config. Empty, ready to use. Next requirement hits whichever area → you document that area. No upfront investment needed.

Real data from a production repo running for 3 months:

Metric	Value
Public APIs	416
Source code	796 files / 4.7 MB / ~100K lines
Flow2Spec per-task load	≈ 300 lines (99% noise removed)

Usage Flow

Step 1: Initialize (one-time)

npx @double-codeing/flow2spec@latest init

Follow the prompts to completion — generates the .Knowledge/ directory structure and routing config skeleton.

Step 2: Build the Knowledge Base (one-time)

In your Agent tool (Cursor / Claude Code):

• /f2s-doc-arch — Scan your project architecture, generate an architecture draft, and follow the flow until topics are created

This step is done once. You won't need to repeat it for daily development.

• /f2s-kb-add <folder path> — Import any feature modules that haven't been added yet

Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.

Step 3: Daily Development (every feature or fix)

Large features:

/f2s-req-clarify  one-line description or paste PRD    ← clarify requirements
/f2s-req-tech                                       ← generate technical proposal
natural language: implement the proposal above         ← AI starts coding (task checklist auto-created when changeTracking is on)
(debug and verify)
/f2s-kb-feat  add xxx capability                       ← if something's missing
/f2s-kb-fix   fix xxx                                  ← if there's a bug
/f2s-kb-sync                                           ← sync knowledge base
/f2s-git-commit                                        ← check and commit

Small changes / quick fixes:

/f2s-kb-feat  add xxx capability                       ← missing feature
/f2s-kb-fix   fix xxx                                  ← bug fix

Quick Command Reference

Command	Purpose
/f2s-req-clarify	Clarify requirements
/f2s-req-tech	Generate technical proposal
/f2s-kb-feat	Add a new capability
/f2s-kb-fix	Fix a bug
/f2s-kb-sync	Sync knowledge base
/f2s-git-commit	Commit code; "quick commit" skips KB coverage check
/f2s-kb-add <path>	Import API module into knowledge base

For the full command list, see Usage Guide · Commands Reference

When NOT to Use

• One-off scripts — throwaway code is faster with a few Markdown files for AI context
• Solo small projects — a single CLAUDE.md is enough; routing overhead > benefits
• Team won't maintain .Knowledge/ — tools can't replace discipline

Documentation

Start here — product narrative and diagrams:

• Flow2Spec Introduction (EN)
• Flow2Spec 基础介绍 (中文)

Hands-on guides

English

• Usage Guide — skill chains, config details
• Commands Reference — all f2s-* command reference
• Directory Conventions
• Architecture & Principles
• Usage Scenarios
• Design Principles
• Project Milestones

中文

• 使用说明
• 命令说明
• 目录与路径约定
• 体系与原理
• 使用案例·模拟对话
• 设计说明
• 项目里程碑

License

MIT. Copyright © 2026 兰涛