Keywords match the task in
todo.json,
AI reads out the
remaining steps,
auto-loads skill rules, and resumes from the last breakpoint.
Flow2Spec · Keep Your AI Always in Context
An AI collaboration framework · Memory Coding
Real ask, spanning Repo B (API) + Repo C (admin) — "merge the image material library with the image model management into one." Touches DDL, service extraction, admin menu merge, legacy compatibility.
> Merge image material library and image model management into one library AI: Which repos are these two modules in? AI: Separate tables? Any data migration needed? AI: Is the old templateUuid field still referenced anywhere? AI: Which endpoint stays? What's the naming prefix? AI: Admin menu — merge or keep both entries? AI: (Digging through DB / service / handler / menu across 3 repos...)
> Merge image material library and image model management into one library [matcher hit] m-image-model-dispatcher [cross-repo deps] Repo B · Repo C · 4 topics AI: Known — B: image_model / image_material tables to merge C: admin menu "Model Mgr" + "Material Mgr" collapse into one Legacy: templateUuid field goes nullable (see §3.2) Naming: keep imageMaterial* endpoints · retain provider param AI: Start · 5 edits on B · 3 on C · one topic chain.
Four real production repos · scale spans 40× · all on the same Flow2Spec stack. Still only ~300 lines of matched topics loaded per turn.
Five same-lane alternatives × five real pain points. Each cell describes what actually happens — no checkmarks. Match your pain to the tool that catches it, including where Flow2Spec doesn't.
kb-feat/fix ties code to the knowledge base
kb-sync manual full resync anytime
kb-add ingest any module on demand
topic / stock-doc / codeRules + knowledge + skillsnatively load in each client (incl. DeepSeek Harness).task/ keyword hit → resume checklist 80 archived tasks.Knowledge/ all in-repo full team reviewKnowledge 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
Topic match ≠ read every doc · docs ≠ skip code. AI judges if context is enough for this step; expand one precise layer on gap — minimal load, not open everything.
Metadata has primary, optional tags, and confidence; it supports inventory, audits, and reading expectations, not execution force.
.Knowledge/ · task .task/ · rules ring · skills ring (separate rules vs skills)User says "modify the batch rescore for the review template library" — four steps: check the index first, then open the book:
Two reads on the knowledge ring: horizontal L0→L3 via
match → expand → verify → act; vertical
topicDependencies stacks conventions to domain rules.
One matcher shard per utterance — no whole-repo grep; clarify when unsure.
You only said "product review" — manifest stacks four topic layers:
topicDependencies expands four topic layersAnother 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 mistakeA 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 disk
Repo A · 27 authors · 2786 commits in 3 months. Task lists split
by developerId; .Knowledge/ remains a single shared source.
{ "subAgent": true, "switchAgentVerification": true, "intentRecognition": true, "changeTracking": { "feat": true, "implement": true }, "collaboration": { "enabled": true } }
.task/ ├── alice/ │ ├── todo.json │ ├── active/backfill_topics_for_reservation.../ │ └── completed/ ← 12 items ├── bob/ │ ├── todo.json │ └── completed/ ← 8 items └── charlie/ └── completed/ ← 5 items .Knowledge/ stays a shared team source
developerId isolates
.task/ so concurrent revs never clash;
shared topic single-source, private tasks stay separate.
collaboration.enabled=true + developerId isolates .task/switchAgentVerification=true — cross-agent validationFrom 3K-line C-side app to 129K-line frontend main — topic count grows roughly linearly. Not just for big projects.
The minimum viable set is 1 manifest entry + 1 matcher + 1 topic — the rest **grows with your requirements**.
# Generate .Knowledge/ + tool configs $ npx @double-coding/flow2spec@latest init
# 1. Whole-repo view /f2s-doc-arch # 2. Pre-ingest the modules you'll touch /f2s-kb-add src/services/product-review
# 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
4 daily drivers cover ~80% ·
the rest fire on demand. flow2spec init lays scaffolding; with
intentRecognition on, these triggers don't need a manual /f2s-* — plain natural language routes automatically.
changeTracking.feat auto-opens .task/.
add -A, no hook-skip, no auto-push.
implement-tech-design.
flow2spec init new repo scaffold · f2s-kb-upgrade align legacy routes & matchers
f2s-doc-pdf PDF→MD · f2s-doc-final finalize ·
f2s-doc-arch architecture · f2s-doc-milestone milestone
f2s-kb-addRules capture rules · f2s-kb-build finals→routing ·
f2s-kb-merge merge conflicts · f2s-kb-rm remove topic ·
f2s-req-plan task plan fallback
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-tech: four-layer deps + tech doc + 5 DDL filesf2s-kb-feat / ⑤ f2s-kb-fix: code + topics stay alignedf2s-git-commit: three checks; no auto pushFlow2Spec 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-coding/flow2spec@latest initf2s-kb-upgrade for template alignment — init is not upgrade