Keywords match the task in
todo.json,
AI reads out the
remaining steps,
auto-loads skill rules, and resumes from the last breakpoint.
whoami
Flow2Spec · Keep Your AI Always in Context
An AI collaboration framework · Memory Coding (knowledge ring is one of four)
compare before-after
Real scenario: a major internet company's backend service trn-fe-ops-commerce-api · 796 files / 4.7 MB · 416 endpoints
> Modify the batch rescore for the review template library AI: Where's the table for this module? 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: (Scanning all 416 endpoints, 796 files, 4.7 MB of source code...)
> Modify the batch rescore for the review template library [matcher hit] m-product-review-template-library [loading deps] 4 topics · ~300 lines AI: Already 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 changes, estimated 3 files.
du -sh . && cat .Knowledge/manifest-routing.json
In a real production repo deeply using Flow2Spec, these numbers grow every day.
diff market.md
Top half: what five market players do and don't do. Bottom half: Flow2Spec's 5 capabilities mapped to each gap.
.Knowledge/ · Cursor / Claude / Codex
natively coexist
f2s-kb-feat/fix updates knowledge when code changes — not one-shot generation
.task/ cross-session resume · f2s-git-commit
enforces KB coverage before commit
f2s-kb-feat / fix and knowledge still decays — the difference is the
gap gate calls it out
instead of silent drift.
tree -L 1 -d
Knowledge layer follows the project · Rules layer follows the tool · Different lifecycles, keeping them separate is the most fundamental decision.
.Knowledge/
is the knowledge ring; the task ring, rules ring, and skills ring share the rest.
Knowledge ring .Knowledge/ · manifest
Task ring .task/ · resume
Rules ring rules · read · act
Skills ring f2s-* · maintain & trigger
≠ model Memory · ≠ bare RAG · Flow2Spec ≠ KB-only
.task/ alongside in the repo.
.Knowledge/ · task .task/ · rules ring · skills ring (separate rules vs skills)topicDependencies vertical (slide 7)cat match && expand && verify && act
Horizontal narrowing on the knowledge ring: user says "modify the batch rescore for the review template library" — four steps:
resolve topicDependencies('product-review-template-library')
Knowledge ring L2 vertical chain: you only said "product review" — topicDependencies already pulls common conventions → subdomain boundaries → C-side whitelist → domain rules.
topicDependencies expands four topic layerscat .Knowledge/topics/{groupon,coupon}-context.md | grep "MUST\|NEVER"
Another storyline: group buying + general coupons. These constraints can never be guessed by AI "reading code" — written in topics, they block errors directly.
groupon-setting.json ·
validField / maxUserJoins / needNewGuest
must be read before any changes.
promotionId + couponConfigId via
activityCode, all changes must go through
@/utils/couponHelper.js.status semantics: 0=failed
· 1=success · 2=already claimed ·
3=sold out · 4=not eligible.f2s-kb-fix → topic → block the next mistakecat .task/completed/20260511-product_review_review_publish_flow/task.md
A real task spanning three layers, 9 steps, completed across multiple sessions — shut down anytime, next time just say "continue."
todo.json,
AI reads out the
remaining steps,
auto-loads skill rules, and resumes from the last breakpoint.
.task/ ├── todo.json ← Task index · keyword match to resume ├── active/ │ └── template_ai_score/ │ ├── task.md ← Checklist ([x] = progress) │ ├── context.md ← Files involved · reference links │ └── user-todos.md ← User offline tasks (DDL · deploy) └── completed/ └── 20260511-product_review_review_publish_flow/ ├── task.md ← All ✅ ├── context.md └── user-todos.md
todo.json → Keyword match
→ Read task.md remaining steps
→ Resume from breakpoint
todo.json match → resume task.mduser-todos.md for DDL, flags, release — human-only items on diskf2s skills --list
Pick f2s-* by lifecycle stage — not from a flat cheat sheet.
flow2spec init lays down templates and routing; day to day, name the skill in chat.
Implement from tech design via rule
implement-tech-design (not an f2s-* skill name); bulk existing
capabilities → f2s-doc-add.
f2s progressive --no-upfront-cost
The minimum viable set is 1 manifest entry + 1 matcher + 1 topic — the rest **grows with your requirements**.
# Generate .Knowledge/ + tool configs $ npx @double-codeing/flow2spec@latest init
# Feed an architecture doc /f2s-doc-arch /f2s-doc-add
# One command for the full loop: code + record + commit check /f2s-kb-feat # New feature → code + topic synced to KB /f2s-kb-fix # Bug fix → update topic to prevent recurrence /f2s-git-commit # Pre-commit check: topic coverage + commit format
# Code got ahead / merge conflict /f2s-kb-sync # Sync capabilities to KB — outline first, then persist /f2s-kb-merge # Handle context conflicts after rebase/merge
.Knowledge/ ├── manifest-routing.json ← Routing table ├── matchers/ │ └── *.json ← Keyword shards ├── topics/ │ └── <topic>.md ← Topic knowledge ├── stock-docs/ │ └── *.md ← Existing docs └── req-docs/ └── *.md ← Requirements + specs flow2spec.config.json ├── subAgent: true/false ← Sub-agent toggle └── switchAgentVerification ← Cross-verification changeTracking.feat/fix/implement ← Change tracking
f2s-* Built-in Rule Topics (package template → init persists) ├── f2s-config-check.md ← Skill pre-flight mandatory step ├── f2s-knowledge-preflight.md ← KB-first read constraint ├── f2s-karpathy-guidelines.md ← Karpathy coding guidelines ├── f2s-task.md ← Change tracking spec └── f2s-flow2spec-unified-entry.md ← Knowledge read order init scaffolds → f2s-* skills grow with requirements → gap gate prevents silent drift
f2s-* skills write, edit, and verify for you
./demo.sh --case product-review-template-library
One main line, 6 steps end-to-end · with 10+ feat/fix micro-iterations along the way, all growing on the same knowledge chain.
product-review /
common-modules /
social-media-platform existing facts: discovers
(a)
batch method doesn't say whether to backfill on short count,
(b)
tie-breaking not specified,
(c)
image upload utility not named,
(d)
new endpoint or reuse existing not confirmed → follows up.
needCount backfill when short? When |L|
is minimum-equal, what's the tiebreaker? Image upload — reuse admin
utils or new? B/C endpoints from scratch (currently 0)?
req-docs/product-review_template-library_req-clarify.md (10 sections
· U⊆L three-tier rules) + companion
product-review_article-publish-flow_tech-spec.md (postType /
imageUrls / publishStatus transitions)
req-docs/product-review_template-library_tech-spec.md + 5
DDLs (template library / tags / relations / scoring rules / agent prompt).
.task/active/template_ai_score/
req-docs/, AI triggers
f2s-implement-tech-design, auto-splits into 8-step
checklist: create scoring rules table → model → aiScoreHelper (mock first) → 4
CRUDs + serverless registration → fire-and-forget scoring on insert →
batch rescore endpoint → list/detail pass-through aiScore → KB
sync. Each step checked off, interruption-safe.
c1d2e3f · Add
rpAiForPeta
rpAiForPeta(fields, model, apiKey, endpoint) ·
Extract fields by mapping → build prompt → call specified model ·
model whitelist gpt-4o-mini / deepseek-chat · endpoint
must be whitelisted domain · timeout 30s
f4a5b6c ·
C-side: Add image upload method
POST /api/c/upload/image
· Restrict formats to jpg/png/webp · Auth reuses posting token ·
base64 direct upload forbidden
a7b8c9d ·
User-uploaded articles also need scoring
scoreContent
is already generic → add scoring call to posting endpoint ·
results go to new user_article_score table, not the template library table
c8d9e0f1 · Scoring missed the title field
scoreContent was only passing content to the
Agent, title was completely missing
scoreContent(title, content, model?), include
title as separate context in the prompt. Patch all six handler call sites. Update
topic?
title: string · required · used by Agent to understand topic intent
2a3b4c5d · scoreContentBatch: sequential → concurrent
for-await
changed to Promise.all for concurrent execution, tested 10 items in 9
seconds. Also extracted AI_BUSY error code from literal to
_enum — prevents future scattering.
6e7f8a9b · Tag soft-delete → hard-delete
commerce_review_template_library_tag_rel.
Topic "tag lifecycle" previously said "soft-delete retained 180
days" — updated to "hard-delete + transactional relation cleanup."
🚀 feat(product-review): template library + AI scoring · No
add -A · No skipping hooks · No auto-push. B-side admin UI
in a separate repo follows the same workflow.
f2s-req-clarify: batch Q → answers → gap check → second roundf2s-req-backend: four-layer deps + tech doc + 5 DDL filesf2s-kb-feat / ⑤ f2s-kb-fix: code + topics stay alignedf2s-git-commit: three checks; no auto pushecho "not a silver bullet"
Flow2Spec trades structural investment for long-term compound returns. In these three scenarios, the investment doesn't pay off — don't force it.
.Knowledge/ — discipline beats toolingf2s-kb-upgrade in chat (KB template upgrade, not init alone)
npx @double-codeing/flow2spec@latest initf2s-kb-upgrade for template alignment — init is not upgrade