Project Milestones

Scope: whole project
Updated: 2026-08-04

Overview

M27 · npm Org Rename Typo Fix & Migration

• Discovered a typo in the legacy org name @double-codeing (extra e); migrated to @double-coding
• Repo-wide rewrite of @double-codeing/flow2spec → @double-coding/flow2spec across templates, config roots, .Knowledge, docs, README, lib, presentations, hero SVG — 38 files
• Main branch removed dual-repo sync discipline while keeping write-boundary and distribution-mouthpiece guards
• Legacy farewell release: branched from v3.2.8 as release/legacy-3.2.9-farewell, first published 3.2.9 then 3.2.10 with bilingual migration notice
  • README top gained a prominent migration notice (Chinese + English side by side)
  • cli.js prints a red warning box when the legacy package name is detected
  • f2s-kb-upgrade Step -1 added a new branch D: when the legacy package name is detected, dispatches an independent sub-agent to silently run npm uninstall -g @double-codeing/flow2spec + npm install -g @double-coding/flow2spec@latest in order
• New package first release: main branch bumped from 3.2.8 to 3.2.11 to avoid version-number collisions with the legacy package
• npm registry farewell: npm deprecate @double-codeing/flow2spec@"*" with a bilingual deprecate message

M26 · Automated Knowledge Merge Engine and Collaboration Hardening

• Added flow2spec kb status / check / plan / apply / build for health checks, merge previews, controlled writes, and routing normalization
• Added the structured kb-delta.json protocol with four change types: append body, replace body, update frontmatter, and create topic
• Added integer topic revisions as optimistic disk locks; stale baseRevisions block writes before apply
• Knowledge-producing skills form deltas first; the commit skill can run check, plan, apply, build, and recheck when the current task and delta are unambiguous
• Added kb build --fix-topics for migrating legacy topics without revisions
• Invalid explicit developerIds now fail clearly; non-normalizable Git identities receive a stable hash id and warning instead of silently sharing the legacy root
• Blank or missing append/replace content is rejected during parsing; damaged deltas appear as structured status errors
• Project version reached 3.2.8

M25 · Per-Developer Task Isolation

• Added collaboration.enabled and collaboration.developerId
• Resolves developerId from explicit configuration, Git email, then Git name; retains the legacy root when no identity exists
• Places each developer’s todo.json, active/, and completed/ under an independent task root and scopes continuation to that root
• Keeps .Knowledge/ as the shared team layer while personal task state remains local

M24 · Codex Rule Mirror Fix + Upgrade Step -1 Smart Preflight + Repo-local Dev Discipline

• Fixed writeCodexTopicMirrors filter: the original endsWith(".mdc") skipped every .md rule file, leaving .codex/topics/ empty after flow2spec init codex; extended to match both .md and .mdc and unify output to .codex/topics/*.md
• f2s-kb-upgrade Step -1 rewritten from “unconditionally dispatch a sub-agent to run npm i -g” to probe first, upgrade on demand: the main agent runs flow2spec --version + npm view ... version + command -v npx in the foreground and branches A/B/C:
  • A: installed and on latest → skip upgrade entirely; Step 2 defaults to flow2spec init
  • B: installed but behind → dispatch an independent sub-agent to run npm i -g ...@latest in the background (fire-and-forget); Step 2 uses npx @latest init
  • C: missing / latest unknown → same as B; if all probes fail, Step -1 can be skipped entirely
• Step 2 command list default form is now driven by the Step -1 branch; added “manual override” clause and a “helper commands” note (flow2spec --version / flow2spec update)
• Added f2s-dev-workflow-constraints rule long text (Cursor / Claude / Codex, three ends): writes only to templates/, never to the config root; user drives distribution; dual repos stay in sync — this rule lives only inside this repo, not in templates/, so downstream projects never receive it
• Added repo-dev-check self-check skill: on this repo, before committing, walks every pending change through the “templates vs config-root” decision table + dual-repo diff + distribution guidance; trigger words include “dual-repo drift”, “write boundary”, “templates vs config root”
• .Knowledge/topics/f2s-dev-workflow-constraints.md thinned to a routing summary pointing to the config-root long text; matcher added new trigger words (sync:agents, 写盘边界, 双仓漂移); index.md topic table updated with related-doc column
• Dual-repo sync for repo-local rule / skill: content contains the dual-repo package-name cross-reference table (@double-coding / @ctrip), so we sync byte-for-byte across repos without rewriting package names

M23 · f2s-kb-distill Auto Tier Judgment + f2s-kb-upgrade Step -1

• f2s-kb-distill removed the --fast parameter; built-in “light tier / strict tier” auto judgment based on 4 dimensions: upstream case, business source files Read, function/class references, user rejection signal
• Light tier skips drill-down quantitative scoring, existing-topic description-depth evaluation, decision matrix, and style alignment; Step 5 routing / Step 6 write-to-disk are never skipped
• f2s-kb-upgrade adds Step -1: before entering Step 0, dispatch an independent sub-agent in background to run npm i -g <pkg>@latest, not awaited, main flow continues immediately; not bound by subAgent config
• Step -1 complements cli.js maybeAutoUpdateGlobalInstall: skill-side proactive trigger + init-tail fallback trigger
• feedback-closing case 1/2/3 closing blocks reverted to single-command suggestion (no --fast hint)
• Command docs and commands-reference added “Execution Tiers” section explaining light/strict trigger conditions

M22 · pkgRev Top-Level Write + Init Auto-Upgrade Global cli

• lib/init.js added finalizePkgRev: writes package-template projectRev to project-side manifest top-level pkgRev, overwritten on every init
• init also overwrites manifest.version to current package version, keeping project manifest in sync with the CLI version used
• cli.js added maybeAutoUpdateGlobalInstall: at init tail, if globally installed and npm latest is higher, auto-runs npm i -g <pkg>; silently skipped for npx-only users
• f2s-kb-upgrade Step 2c now reads pkgRev directly from manifest top-level, no fallback scanning
• Terminology unified to projectRev (package-template side) / pkgRev (project-landed side)

M21 · f2s-kb-upgrade templateRevision Fast Path and Self-Update Loop

• f2s-kb-upgrade introduced templateRevision (later renamed projectRev) fast path: when project revision equals package-template revision, skip steps 3, 3a, 3b
• Self-update loop fix: after init, on re-reading SKILL.md with a version change, rerun from step 2c per the new literal text, no second flow2spec init
• f2s-kb-feedback-closing refactored: removed the blanket “no closing block inside any KB skill” rule; replaced with distill self-prohibition + other KB skills still judge per the 4 cases
• feedback-closing landed “summary requirement”: cases 1~3 must state in one line what distill would actually ingest
• topicMetadata guideline clarified: inferred writes directly without prior user consent, correcting the “must manually confirm” misread

M20 · Init Defaults Flipped

• flow2spec.config.json three boolean fields’ defaults flipped to true: subAgent / switchAgentVerification / intentRecognition
• New projects running flow2spec init now have these enabled by default: sub-agent orchestration, cross-agent disk-write verification, intent-recognition auto-routing
• Old projects that explicitly wrote these fields are unaffected; on upgrade, old projects still missing these fields are filled with the new true default
• With defaults flipped, the f2s-* skill sub-agent prerequisite and cross-agent verification switch from “opt-in” to “opt-out”

M19 · .task/ Adds acceptance.md Acceptance Checklist

• .task/active/<task>/ adds acceptance.md, separated in duty from user-todos.md: the former manages “user acceptance”, the latter manages “user todos”
• New archive gate: after task.md is fully [x], before moving the directory to completed/, acceptance.md must be written; if still a placeholder or missing, archiving is forbidden
• Task-creation step 3.e also creates an acceptance.md placeholder; not written during execution; after task.md completes, the agent organizes it into a formal acceptance checklist
• Archive directory naming unified to <YYYYMMDD>-<task-name> (local 8-digit date prefix), enabling chronological sorting
• f2s-task rule, f2s-req-plan skill, and change-tracking steps inside f2s-kb-* skills updated accordingly
• Version bumped to 3.2.1

M18 · f2s-kb-distill and Rule Refactor

• Added f2s-kb-distill skill: extracts reusable knowledge facts from Q&A, auto-decides new topic or append to existing
• Refactored f2s-kb-feedback-closing: unified suggestion entry to f2s-kb-distill, replacing f2s-kb-add/f2s-kb-sync dual entry
• Codex root AGENTS.md slimmed: removed embedded rules, replaced with “do these two things first” short guide
• Codex hooks landed: .codex/hooks.json adds SessionStart config-summary and version-check dual scripts
• CLI cross-platform extension handling: Cursor rules keep .mdc, Claude/Codex rules switch to .md, codexAgentsAdapter handles .mdc reading
• intentRecognition enabled by default in internal repo

M17 · Locale-Aware Template Initialization

• templates/ split into zh-CN/ and en-US/ directories
• flow2spec init supports single-choice locale initialization, defaults to Chinese
• English templates cover rules, skills, knowledge, AGENTS.md and flow2spec.config.json with English filenames
• Public README defaults to English; Chinese moved to README.zh-CN.md; README.en.md kept for compatibility

M16 · Intent Recognition Routing

• flow2spec.config.json adds intentRecognition boolean field
• Added f2s-intent-routing rules: high-confidence operation intent routes to matching f2s skill automatically
• Discussion, evaluation, low-confidence, or incomplete-requirement inputs stay in normal conversation or clarification
• Skill routing is blocked when intentRecognition is not read or set to false

M15 · General Technical Proposal and Q&A Closing

• f2s-req-backend renamed to f2s-req-tech
• Technical proposal template upgraded from backend-only to frontend/backend/fullstack general purpose
• Added f2s-kb-feedback-closing rules: four-case knowledge-backfill suggestion closing for source-code Q&A
• Reduced unnecessary f2s-kb-add/sync prompts in ordinary Q&A flows

M14 · f2s-git-commit Quick Commit

• f2s-git-commit supports quick commit mode, skips knowledge coverage check
• Retains diff reading, conflict checking, precise add, git hooks, and commit headline display
• Auto push/pull disabled; user confirmation preserved

M13 · Update Checks and Startup Reminders

• flow2spec.config.json adds updateCheck.enabled config
• Version-check hook: manifest version vs npm latest; daily cache to .Knowledge/update-check.json
• Claude: writes SessionStart version-check script to .claude/settings.json
• Cursor: writes SessionStart version-check script to .cursor/hooks.json
• Codex: writes SessionStart config-summary and version-check dual scripts to .codex/hooks.json
• Rule-layer fallback: script cache and rule-layer updateCheck serve as mutual backup

M12 · Topic Metadata and Init Merge Checks

• manifest-routing.json adds topicMetadata with primary/tags/confidence fields
• f2s-topic-authoring rules add topicMetadata classification criteria (4 primary types, confidence rules)
• init copySkills auto-removes old skill directories without deleting user-custom skills
• init supports template-priority overwrite and merge validation
• 6 skills renamed to kb-/doc- prefix convention
• Redundant skills (f2s-coding-guide, f2s-doc-routing) removed

M11 · Knowledge Engineering Rules and Skill Skeletons

• Added skill-authoring topic + matcher: unified SKILL.md skeleton, naming, and section order for templates/skills/f2s-*
• Added f2s-kb-addRules skill (renamed from f2s-kb-capture): verbal rule capture, auto-decides new topic or merge into existing
• Added f2s-topic-authoring rules: topic authoring guidelines covering naming, skeleton, topicDependencies, and large-feature split
• Large-feature split strategy: main topic + sub-topic structure recommendation with split thresholds and exclusion rules

M10 · Documentation Capture Rules

• f2s-doc-add (predecessor of f2s-kb-add) added multi-module detection to prevent merging unrelated modules into single output
• Dual-repo milestone stock-doc added package naming rules (public @double-coding/flow2spec vs internal path)
• Global rules added negation-style constraint: use affirmative statements instead of “not X / non-X”

M9 · README and Task Capability Exposure

• README added usage flow and command quick reference
• README added task checklist capability and daily workflow description
• English README synced with capability descriptions; removed misleading f2s-req-plan reference

M8 · Document Pipeline and Directory Boundaries

• Docs directory reorganized, removed product-repo docs path coupling
• Established doc-arch → doc-final → kb-build pipeline; drafts must not drive kb-build directly
• Updated new-requirement skill chain; clarified each skill’s role in the requirements→implementation→knowledge loop
• .Knowledge/stock-docs and req-docs directory conventions de-coupled from product-specific paths

M7 · Four-Source Milestone Generation

• Added f2s-doc-milestone skill: generates milestones from req-docs, git log, .task, and knowledge topics
• Added project milestone template: defines stage structure, field conventions, and no-testing/acceptance constraint
• Milestone stages record only feature/capability changes; engineering changes merged into feature stages

M6 · Codex Root AGENTS.md Discovery

• flow2spec init codex writes complete rules to root AGENTS.md
• .codex/AGENTS.md becomes a pointer, reducing risk of Codex missing rules
• Established unified pattern: Claude/Cursor/Codex each write rules to their own config root

M5 · CLI Operations and Task Routing

• CLI added version command: reads package.json and outputs current version
• CLI added update command: self-update
• Package template manifest includes f2s-task and f2s-req-plan routing entries and topicDependencies

M4 · Public Demo and Bilingual Materials

• Added presentations/flow2spec-intro-public source files
• Added sync-gh-pages.sh and GitHub Pages deployment
• Added English slides and 6 English docs
• README added bilingual entry points and demo links

M3 · .Knowledge Machine-Readable Routing

• Introduced .Knowledge/ directory: manifest-routing.json, topics/, matchers/ structure
• Established match→expand→verify→act knowledge consumption chain
• Added f2s-knowledge-preflight rules: mandatory first-read of manifest-routing.json with gap-gate constraints
• Added f2s-config-check rules: f2s-* skills must read flow2spec.config.json first
• Added Karpathy full-platform coding behavior guidelines (f2s-karpathy-guidelines)

M2 · OpenSpec Removal and f2s Skills

• Removed OpenSpec/opsx dependencies and change-flow organization
• Fully converted to f2s self-owned skill workflow (skills/ directory structure established)
• f2s-req-clarify and f2s-req-tech skills initialized
• f2s-* skills established as the base execution units for knowledge and requirement pipelines

M1 · CLI Bootstrap and OpenSpec Workflow

• Flow2Spec initialized as an installable CLI tool
• Early AI collaboration organized around OpenSpec/opsx change flows
• Basic init command supports Cursor/Claude/Codex config root writing

Pending

• None