~/flow2spec · zsh · 01:00:00

whoami

Has Your AI
Lost Its Memory?

Flow2Spec · Keep Your AI Always in Context

An AI collaboration framework · Memory Coding (knowledge ring is one of four)

  • Cross-device sessions remember project context
  • Internal routing manifest — AI fetches only what it needs
  • f2s-* skills update knowledge as you code, always fresh
Lan Tao·2026.05·Frontend Team
  • Opening: Has your AI lost its memory?
  • Memory Coding: encode memory in the repo; four rings (knowledge / task / rules / skills) — do not collapse to three
  • The KB is only the knowledge ring; Flow2Spec three product things: resume context, routed reads, f2s keeps code + KB in sync (do not mix counts with four rings)
  • Slide 5: two-layer architecture
session · diff · product-review / batch-rescore

compare before-after

Same Request, Two Conversations

Real scenario: a major internet company's backend service trn-fe-ops-commerce-api · 796 files / 4.7 MB · 416 endpoints

Without Flow2Spec
> 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...)
Repeated explanations · Repeated code scanning · Repeated pitfalls
With Flow2Spec
> 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.
4.7 MB → 300 lines · Instant access to hard constraints
  • Same ask: product-review template library · batch re-score
  • Left: no framework → table? sync? locks? often scans the whole API surface
  • Right: matcher hit → Redis keys, error codes, limits already in topics
  • Line: not a smarter model — better context
stats · trn-fe-ops-commerce-api · 2026-05-13

du -sh . && cat .Knowledge/manifest-routing.json

Not a Concept — It's Daily Reality

In a real production repo deeply using Flow2Spec, these numbers grow every day.

Public Endpoints
416
Functions registered in serverless.yml · Traditional approach requires AI to read the entire repo
src Files / Size / Lines
796 · 4.7 MB · 100K lines
Flow2Spec loads only ~300 lines of matched topics each time · 99% noise eliminated
Topics / Matchers / Docs
12 / 11 / 28
Topic shards · keyword shards · dual-track documentation for existing and requirement docs
Endpoints / Layers / Task Lists
17/3/14
4 days intermittent work · across B-side · C-side · API layer three repos · review template library / tags / article revamp / AI review / agent scoring system / frontend custom scoring
  • 416 APIs · 796 files · ~100k LOC — real scale
  • ~300 lines of matched topics per turn, most noise cut
  • Last ~4 days: 17 APIs, 14 archived tasks, three repos in parallel
  • Hard to sustain this pace without a KB backbone
why not · openspec · superpowers · rag-kb · ohmyclaude · spec-kit

diff market.md

No Hard Sell — Judge for Yourself

Top half: what five market players do and don't do. Bottom half: Flow2Spec's 5 capabilities mapped to each gap.

OpenSpec
Strictest spec format
× One-way — code drifts, never feeds back
Superpowers/ ohMyClaude
Plug-and-play skills
× Locked to Claude · No project knowledge
RAG Vector DB
Full-text indexing · similarity search
× Probabilistic hits · Can't enforce hard constraints
Spec Kit/ Kiro / BMAD
PM-friendly · requirements straight to spec
× One-shot · Falls apart on iteration
Claude Memory
No repeated introductions
× Model-locked · Not Memory Coding (not in repo)
Flow2Spec · 5 Capabilities
Multi-Platform
One .Knowledge/ · Cursor / Claude / Codex natively coexist
Route Narrowing
Matcher hit + dependency chain + gap gate forces clarification
Two-Way Sync
f2s-kb-feat/fix updates knowledge when code changes — not one-shot generation
Native Agent
Only rules + knowledge + skills · no wrapper · new models just work
Change Tracking + Commit Gate
.task/ cross-session resume · f2s-git-commit enforces KB coverage before commit
// honest note Stop using f2s-kb-feat / fix and knowledge still decays — the difference is the gap gate calls it out instead of silent drift.
  • Top row: five alternatives — what each does / does not do (quick scan)
  • OpenSpec one-way; Superpowers tool-bound; RAG probabilistic; Spec Kit one-shot; Claude Memory not in your repo
  • Bottom: Flow2Spec five capabilities (multi-IDE, routing, two-way sync, native agents, traceability)
  • Honest: KB still rots without f2s — but gap gates surface it
architecture · two-layer · one-arrow

tree -L 1 -d

One Diagram · Two Layers · One Arrow

Knowledge layer follows the project · Rules layer follows the tool · Different lifecycles, keeping them separate is the most fundamental decision.

Memory Coding Encode what must be remembered into the committed repo — not the model or chat. In the diagram below, .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
KNOWLEDGE LAYER · Memory Coding · Knowledge ring
.Knowledge/
Routing + topics + stock/req docs — the knowledge ring of Memory Coding, not the whole story.
manifest-routing.json matchers/*.json topics/*.md stock-docs/*.md req-docs/*.md
Knowledge ring · multi-layer memory
L0 manifest L1 matchers L2 topics L3 stock / req
Horizontal: match → expand → verify → act (slide 6) · Vertical: topicDependencies (slide 7)
RULES LAYER · Rules ring + Skills ring
.cursor/ · .claude/ · .codex/
Rules ring — how to read & act; Skills ring (f2s-*) — maintain KB & trigger flows; Task ring .task/ alongside in the repo.
.cursor/rules/*.mdc .claude/rules/*.md .codex/AGENTS.md skills/*/SKILL.md
  • Memory Coding: durable, reviewable memory in git
  • Four rings: knowledge .Knowledge/ · task .task/ · rules ring · skills ring (separate rules vs skills)
  • Two layers: knowledge follows the project · rules follow the tool; arrow: skills maintain ↑ · rules read/act ↓
  • L0→L3 horizontal; topicDependencies vertical (slide 7)
  • Flow2Spec ≠ RAG-only product
feature · 01 / 03 · progressive load

cat match && expand && verify && act

Progressive Loading · Check the Index First, Then Open the Book

Horizontal narrowing on the knowledge ring: user says "modify the batch rescore for the review template library" — four steps:

match
m-product-review-
template-library
Hits the matcher, reads only this one shard
expand
+3 dependency topics
common / platform / toClient auto-resolved
verify
Gap check
Low confidence → clarify with user first
act
Start coding
Estimated 3 files · with hard constraints
What you load is what you don't load — 4.7 MB source → 300 lines of topics. It's not about making AI smarter — it's about cutting the noise.
  • Horizontal read on knowledge ring: match → expand → verify → act
  • One matcher shard at a time — no whole-repo grep by default
  • Clarify when confidence is low
  • Line: MB-scale repo → hundreds of lines of topics — cut noise, not magic IQ
feature · 02 / 03 · topicDependencies

resolve topicDependencies('product-review-template-library')

One Sentence · 4-Layer Dependencies Auto-Expanded

Knowledge ring L2 vertical chain: you only said "product review" — topicDependencies already pulls common conventions → subdomain boundaries → C-side whitelist → domain rules.

└─
common-modules-context ctx · responseData · QMQ · getDb · DB field conventions 79 lines
  └─
social-media-platform-context Business B-side subdomain · 3-repo split · @sm/* aliases 79 lines
    └─
social-media-toclient-whitelist C-side checkUidAndWhiteList · UID isolation · error codes 39 lines
      └─
product-review-template-library Domain rules · Redis lock · AI scoring · domain exceptions 67 lines
Dependencies are attached at the topic level, not the task level — new tasks don't need to re-declare prerequisites, and missing ones won't silently fail.
  • Vertical chain: topicDependencies expands four topic layers
  • Dependencies at topic level: declare once, every task inherits
  • No silent failure when a dependency is missing
case · groupon × coupon · hard-constraints

cat .Knowledge/topics/{groupon,coupon}-context.md | grep "MUST\|NEVER"

Every Topic Is a Guardrail Against AI Mistakes

Another storyline: group buying + general coupons. These constraints can never be guessed by AI "reading code" — written in topics, they block errors directly.

groupon · 01

joinGroupon · Same-Transaction Dual Write

Group join record + user stats table MUST be committed within the same sequelize.transaction().
NEVER write the join record first then open another transaction for stats — under concurrency, maxUserJoins will drift.
groupon · 02

maxUserTeamLeader · Isolated by Type

Team leader cap only counts groups of the current activity type,
cross-type counts do NOT accumulate; source of truth is QConfig groupon-setting.json · validField / maxUserJoins / needNewGuest must be read before any changes.
coupon · 03

Frontend Only Passes activityCode

Public API does not accept promotionId; backend resolves promotionId + couponConfigId via activityCode, all changes must go through @/utils/couponHelper.js.
Leaking promotionId allows unpublished campaigns to be enumerated.
coupon · 04

status Priority 0 > 1 > 2

Coupon claim status semantics: 0=failed · 1=success · 2=already claimed · 3=sold out · 4=not eligible.
When merging multi-source statuses, MUST follow priority 0>1>2>3>4 — not max, not min.
  • Last slide: breadth; this slide: density
  • Groupon dual-write throttling, coupon status priority — not guessable from code
  • Pitfall → f2s-kb-fix → topic → block the next mistake
  • KB grows with delivery, not a two-week doc dump upfront
feature · 03 / 03 · resume-across-sessions

cat .task/completed/20260511-product_review_review_publish_flow/task.md

Session Dropped · AI Picks Up Where It Left Off

A real task spanning three layers, 9 steps, completed across multiple sessions — shut down anytime, next time just say "continue."

.task/completed/20260511-product_review_review_publish_flow/task.md
# product_review_review_publish_flow
  • Step 1: Generate technical spec (API layer + B-side)
  • Step 2: API layer · Add 5 fields to article table
  • Step 3: Modify article creation endpoint
  • Step 4: Modify review endpoint (state transition: approved → pending publish)
  • Step 5: New article publish endpoint (backfill post link + partner code)
  • Step 6: B-side · Modify list/detail endpoints
  • Step 7: B-side · Modify edit endpoint
  • Step 8: Sync knowledge base
  • Step 9: Commit code

// Resume Experience

Next session, just say "help me continue the article publish flow"
Keywords match the task in todo.json, AI reads out the remaining steps, auto-loads skill rules, and resumes from the last breakpoint.
LLMs have no cross-session memory · We use a .task/todo.json to explicitly bring it back.
user-todos.md also persists things only the user can do offline (run DDL, flip switches, deploy).
// .task/ · task ring
.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
  • Real task: three repos · 9 steps · multiple sessions
  • Say “continue” → todo.json match → resume task.md
  • user-todos.md for DDL, flags, release — human-only items on disk
  • Task ring is part of Memory Coding
skills · command-map

f2s skills --list

Command map

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.

① Bootstrap Scaffold & migrate flow2spec init · f2s-kb-migrate · f2s-kb-upgrade Align new repos; one-shot legacy KB → .Knowledge
② Requirements clarify → tech spec f2s-req-clarify · f2s-req-backend PRD Q&A and tech docs — no req-plan required
③ Docs in spec / final / arch / milestone f2s-doc-pdf · f2s-doc-final · f2s-doc-arch · f2s-doc-milestone Specs & stock-docs; milestones generated from four sources
④ Iterate plan (opt.) · ship · sync f2s-req-plan · f2s-kb-feat · f2s-kb-fix · f2s-kb-sync req-plan optional; feat/fix from tech design (may use .task); sync KB
⑤ Wrap-up Commit & merge f2s-git-commit · f2s-kb-merge Commit with KB checks; post-merge context conflicts
⑥ Knowledge upkeep routing & existing code f2s-ctx-build · f2s-ctx-rm · f2s-doc-add stock-docs ↔ topics/manifest; multi-file KB ingest

Implement from tech design via rule implement-tech-design (not an f2s-* skill name); bulk existing capabilities → f2s-doc-add.

  • Command map — remember stages, not twenty skill names
  • ① Onboard: init / migrate / upgrade
  • ② Requirements: clarify / backend (req-plan optional)
  • ③ Docs: pdf / final / arch / milestone
  • ④ Iterate: req-plan + feat / fix / sync; implement via implement-tech-design
  • ⑤ Ship: git-commit / kb-merge · ⑥ Maintain: ctx-build / ctx-rm / doc-add
  • init lays scaffolding; business KB grows through f2s flows
onboarding · progressive-kb

f2s progressive --no-upfront-cost

Build as You Go · No Need to Finish First

The minimum viable set is 1 manifest entry + 1 matcher + 1 topic — the rest **grows with your requirements**.

init1 minute
Scaffold the Skeleton
# Generate .Knowledge/ + tool configs
$ npx @double-codeing/flow2spec@latest init
Empty manifest-routing.json
Ready to run — zero knowledge written
First UseOne requirement
Seed Your First Knowledge
# Feed an architecture doc
/f2s-doc-arch
/f2s-doc-add
AI reads existing docs
→ Generates first topic + matcher
DailyCode → Record → Commit
Development Loop
# 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, record knowledge, commit check — all in one flow
Knowledge base **grows with the business**, never decays
MaintenanceAs needed
Health Check · Alignment
# 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
kb-sync: backfill KB after implementation lands
kb-merge: resolve knowledge conflicts after branch merges
// Knowledge Base + Project Config + Built-in Rule Topics
.Knowledge/ + Config
.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
.claude/rules/ · .cursor/rules/ (mirror synced)
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
"Do I need to write all docs before I can use it?"→ init runs on day one — zero docs, no blockers
"How much is enough?"→ Start with 1 topic + 1 matcher — the gap gate will tell you
"Steep learning curve for the format?"→ No manual writing — f2s-* skills write, edit, and verify for you
"What if I write it but it doesn't work?"→ Add one, test one — matcher hit = verified
"Do I need to migrate the whole legacy project?"Nope. init the skeleton → next requirement hits a module, write that module
  • You do not need two weeks of docs first
  • Minimum: one route + one matcher + one topic
  • init in ~1 min; feat/fix daily; commit checks KB coverage
  • Write the slice you hit next — no big-bang migration
live · demo · routemap

./demo.sh --case product-review-template-library

Real Case · 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.

1
/f2s-req-clarify "Build a template library for AI-polished user articles, with AI scoring for both templates and articles, readable from both B-side and C-side"
Clarification is "batch questions → you answer → AI cross-checks KB for gaps → another batch" iterative, not one-question-one-answer:
Round 1 · 12 questions at once
AI: Scope (ops-only editing? C-side template selection for posts? Version history? Dedup?) · Data shape (tags in separate table or inline? Many-to-many? Plain text or rich text? 3000 chars by character count? Image array — how many? Placeholders?) · Matching (U⊆L full coverage vs max intersection? When does weight +1? Can offline/deleted items be matched?)
Me: Answer all at once.
↓ AI self-check · Cross-references answers against 4-layer topics + stock-docs
Cross-checks 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.
Round 2 · 4 follow-up questions targeting gaps
AI: Should 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)?
Me: No backfill, return as-is · Break ties by usage weight · Reuse admin utils · Both B/C from scratch.
→ AI cross-checks KB again, no gaps remaining → finalized as 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)
2
/f2s-req-backend matcher hit m-product-review-template-library
Auto-loads 4-layer topic dependencies (common-modules → social-media → product-review → template-library), produces req-docs/product-review_template-library_tech-spec.md + 5 DDLs (template library / tags / relations / scoring rules / agent prompt).
3
Once the spec is finalized, just say "implement this tech spec" or "continue" · Creates .task/active/template_ai_score/
No commands to memorize — reads the tech spec from 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.
4
/f2s-kb-feat Describe the need = Implementation + Auto KB entry
c1d2e3f · Add rpAiForPeta
Me: Format is field mapping; model, endpoint, and apiKey are passed from the client — server only forwards + validates format
AI: Implement 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
→ topic "rpAiForPeta" mapping rules / client params / whitelist / timeout constraints
f4a5b6c · C-side: Add image upload method
Me: Upload images before posting to get CDN URLs, max 10MB per image, max 9 per upload
AI: POST /api/c/upload/image · Restrict formats to jpg/png/webp · Auth reuses posting token · base64 direct upload forbidden
→ topic "C-side image upload" endpoint path / limits / auth
a7b8c9d · User-uploaded articles also need scoring
Me: Not just the template library — user-uploaded articles need AI scoring too
AI: scoreContent is already generic → add scoring call to posting endpoint · results go to new user_article_score table, not the template library table
→ topic "scoring system" addendum: user article scoring → separate table
5
/f2s-kb-fix 3 iterations all through the same entry · each time updating the topic
c8d9e0f1 · Scoring missed the title field
Me: Ops complained that scores fluctuate wildly for same content — I checked and scoreContent was only passing content to the Agent, title was completely missing
AI: Update to scoreContent(title, content, model?), include title as separate context in the prompt. Patch all six handler call sites. Update topic?
→ topic "scoring input structure" adds new row: title: string · required · used by Agent to understand topic intent
2a3b4c5d · scoreContentBatch: sequential → concurrent
Me: Batch rescore for 10 items takes 90 seconds — this method shouldn't wait one by one
AI: 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.
→ topic "batch rescore timing" changed from "sequential" to "concurrent" + added Redis mutex lock section (prevents concurrent avalanche)
6e7f8a9b · Tag soft-delete → hard-delete
Me: After soft-deleting tags, the relation table still has stale data — queries occasionally return deleted tags. Switching to hard-delete.
AI: Changed tag deletion to hard-delete + transactional cleanup of commerce_review_template_library_tag_rel. Topic "tag lifecycle" previously said "soft-delete retained 180 days" — updated to "hard-delete + transactional relation cleanup."
→ topic corrected: delete semantics = hard-delete + transactional relation cleanup (old soft-delete description deprecated)
6
/f2s-git-commit Commit gate · conflict scan / KB coverage check / emoji + Conventional
Pre-commit enforces three checks: ① Conflict marker scan ② Topic covers new fields ✓ ③ First line 🚀 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.
One main line, 6 steps end-to-end · with 10+ micro-iterations all growing on the same knowledge chain.
  • Case: review template library → 17 APIs / ~4 days (scroll; pick highlights)
  • f2s-req-clarify: batch Q → answers → gap check → second round
  • f2s-req-backend: four-layer deps + tech doc + 5 DDL files
  • ③ Implement: “continue” → implement-tech-design + 8-step checklist
  • f2s-kb-feat / ⑤ f2s-kb-fix: code + topics stay aligned
  • f2s-git-commit: three checks; no auto push
honest · dont-use-when

echo "not a silver bullet"

Honest Talk · When NOT to Use It

Flow2Spec trades structural investment for long-term compound returns. In these three scenarios, the investment doesn't pay off — don't force it.

×
Throwaway Scripts · Temp Tools
For things you'll delete after writing, just toss a few Markdown files at AI — that's faster. Knowledge base maintenance is pure overhead.
×
Solo Small Projects · No Multi-Platform Needs
Just you, one AI, one machine — a single CLAUDE.md is enough. Routing and sharding overhead outweighs the benefit.
×
Team Won't Sync .Knowledge/
If code changes without syncing skills, the knowledge base decays anyway. Tools can't replace discipline — f2s-* only lowers the "cost of syncing."
  • Saying when not to use it builds trust
  • ① One-off scripts
  • ② Solo tiny repo — one CLAUDE.md may be enough
  • ③ Team will not maintain .Knowledge/ — discipline beats tooling
~/flow2spec · end · 02:00:00
// the takeaway

It's not about making AI smarter,
it's about keeping AI always aware of what you're working on

repo·github.com/Lands-1203/Flow2Spec
install·npx @double-codeing/flow2spec@latest init
upgrade·say f2s-kb-upgrade in chat (KB template upgrade, not init alone)
contact·Lan Tao
  • Close: context, not a smarter model
  • github.com/Lands-1203/Flow2Spec · npx @double-codeing/flow2spec@latest init
  • Existing projects: f2s-kb-upgrade for template alignment — init is not upgrade
  • Try it · issues · chat after the talk