Flow2Spec Usage Guide

1. What init Does

Execute in the project root:

flow2spec init [cursor|claude|codex ...]
# To force reset .Knowledge from template:
flow2spec init [cursor|claude|codex ...] --reset-knowledge

init and “knowledge base upgrade” are two different things: init only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like f2s-kb-add, f2s-kb-fix, f2s-kb-feat, f2s-kb-sync, f2s-kb-build, etc. For cross-version upgrades, use f2s-kb-upgrade. Do not treat a standalone init as an upgrade command.

f2s-* and flow2spec.config.json: Multi-Client, Multi-Layered Reminders (Authority Remains the Disk JSON)

Before executing any f2s-* skill, the Agent needs to obtain the actual values of subAgent / switchAgentVerification / changeTracking, etc. Flow2Spec enforces this via different mechanisms on different clients; they complement each other and do not replace one another. Authority always resides in the project root flow2spec.config.json (call Read to verify against disk before proceeding into skill body).

For field semantics and default value rules, see Commands Reference § 6) Sub-Agent Configuration. For the design perspective, see Design Principles § 4.5.1.

2. Directory Conventions

Core distinction: stock-docs/ holds solidified documents (driving knowledge routing), req-docs/ holds technical designs (driving coding implementation); they are not interchangeable.

See Directory Conventions for the full directory description.

3. Typical Workflows

Change Tracking and Cross-Session Continuation (Recommended)

Enable changeTracking per skill in flow2spec.config.json (each sub-field is independent):

{
  "changeTracking": {
    "feat": true,
    "fix": true,
    "implement": true
  }
}

When enabled, f2s-kb-feat / f2s-kb-fix / f2s-implement-tech-design automatically create a checklist under TASK_ROOT/active/ (see multi-developer below), check off steps, and archive on completion. In later sessions, the f2s-task rule matches related wording and resumes the remaining steps — no need to re-explain context.

If changeTracking is off but you still need a task checklist temporarily, call f2s-req-plan explicitly (always creates a checklist, ignores config) — a fallback, not the default path. See Commands Reference § f2s-req-plan.

Team Collaboration

Flow2Spec separates personal execution state from team knowledge:

• .task/ is local and ignored by Git. With collaboration enabled it is partitioned into .task/<developerId>/; continuation logic reads only the current TASK_ROOT.
• .Knowledge/ is shared through Git. Knowledge skills produce a structured kb-delta.json, and the CLI checks topic revisions before merging it.

developerId resolution follows explicit collaboration.developerId -> Git email prefix -> Git user name -> legacy .task/. Invalid explicit ids fail instead of silently changing identity. Non-ASCII Git identities use a stable dev-xxxxxxxx hash fallback with a warning. Setting collaboration.enabled: false always selects the legacy root.

The knowledge merge commands are:

flow2spec kb status
flow2spec kb check --strict
flow2spec kb plan  .task/<id>/active/<task>/kb-delta.json
flow2spec kb apply .task/<id>/active/<task>/kb-delta.json
flow2spec kb build

In normal work, f2s-git-commit runs the relevant check -> status -> plan -> apply -> build -> check sequence. The shell commands are useful for diagnosis and CI. When baseRevisions no longer matches disk, pull the latest topic, reread its meaning, and rewrite the delta; changing only the number is not a semantic merge.

Existing topics without revisions require a one-time migration with flow2spec kb build --fix-topics, followed by review and flow2spec kb check --strict. The full model, same-topic conflict handling, and manager visibility are covered in Team Collaboration.

New Feature Development

f2s-req-clarify (one-line requirement or doc) → f2s-req-tech → implement <technical design> (strictly follows implement-tech-design rule)
After implementation, new capability → f2s-kb-feat
After implementation, bug fix → f2s-kb-fix
After debugging → f2s-kb-sync
Finally → f2s-git-commit

When requirements are already clear, f2s-req-clarify can be skipped, starting directly from f2s-req-tech. After the technical design is written into req-docs/, the implement-tech-design rule drives coding.

Document Ingestion

New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-kb-build
PDF/draft ingestion:               f2s-doc-final → f2s-kb-build

Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use f2s-doc-final then f2s-kb-build. f2s-doc-pdf only converts a PDF to Markdown under req-docs/ for editing; it is not the recommended path for “PDF straight to coding.”

Backfilling Existing Capabilities

f2s-kb-add      # Aggregate multiple files, extract from source code / documents
f2s-kb-sync      # Infer already-implemented capabilities from current session

Use these when code has already been shipped but the knowledge base has no record. f2s-kb-add is suitable for batch imports; f2s-kb-sync is suitable for real-time consolidation at the end of a session.

Routine Maintenance

f2s-kb-fix       # Fix implementation or rule errors, auto-sync knowledge base
f2s-kb-feat      # Add new capabilities, auto-sync knowledge base
f2s-kb-sync      # Periodic sync or backfill
f2s-kb-merge     # Resolve context conflicts after Git merges

Cross-Version Knowledge Base Upgrade

f2s-kb-migrate (Legacy V1: old knowledge base) → f2s-kb-upgrade
f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0)

In interactive terminals, the Flow2Spec CLI checks the latest npm version with a cache when running flow2spec version / flow2spec init. If a newer version exists, it prompts you to run flow2spec update, then execute f2s-kb-upgrade in the Agent conversation to align the project knowledge templates, manifest/matchers, and agent config roots. Failed update checks are skipped silently and do not affect the current command; checks are disabled in CI, non-TTY sessions, or when FLOW2SPEC_SKIP_UPDATE_CHECK=1 is set.

After flow2spec init codex, Codex projects include .codex/hooks.json, .codex/hooks/f2s-config-session.js, and .codex/hooks/f2s-update-check.js. On Codex SessionStart for startup|resume, the first script injects one configuration summary and the second checks the knowledge-base version automatically. When the hook is first generated or changed, trust it through /hooks in Codex. Set updateCheck.enabled=false in flow2spec.config.json to skip only the version check.

After flow2spec init cursor, Cursor projects include .cursor/hooks.json and .cursor/hooks/f2s-update-check.js. The hook runs on Cursor sessionStart and injects upgrade reminders through additional_context. Set updateCheck.enabled=false in flow2spec.config.json to skip the check.

After flow2spec init claude, Claude projects include .claude/settings.json, .claude/hooks/f2s-config-session.js, .claude/hooks/f2s-config-inject.js, and .claude/hooks/f2s-update-check.js: SessionStart injects the configuration summary and checks the knowledge-base version, while PreToolUse Skill only guards f2s-* Skill calls. The version-check script injects an agent-instruction notice through additional_context, requiring the agent to relay the message verbatim to the user. The notice format is: “Current project <project> knowledge-base version v, lower than latest package version v. Run the f2s-kb-upgrade skill to align templates and routing.” If today’s cache still flags a needed upgrade, every new session re-injects the reminder; after a successful upgrade, f2s-kb-upgrade clears .Knowledge/update-check.json so stale reminders disappear.

4. Agent Execution Configuration

Controlled via the project root flow2spec.config.json. For complete field rules, see Commands Reference § 6) Sub-Agent Configuration. How each client is reminded to read the config, and why Read remains authoritative — see § 1 (this § only explains when to toggle each switch).

When to enable subAgent: true: When the task is large (multi-module parallel implementation, batch document ingestion, large-scale migration). When enabled, each skill decides whether to actually split based on its own size threshold; tasks below the threshold are still completed within the main agent.

When to enable switchAgentVerification: true: When higher write consistency is needed (large-scale migration, critical design implementation). The trade-off is increased execution rounds; for routine maintenance, the default false is sufficient. Requires subAgent: true to trigger the “main-writes, sub-verifies” cross-check direction.

When to enable changeTracking.*: When you want each skill execution to automatically leave a resumable task checklist. Each skill sub-item is independently configurable without mutual interference:

{
  "changeTracking": {
    "feat": true,
    "fix": false,
    "implement": true
  }
}

Use f2s-req-plan only when all changeTracking sub-fields are off and you still need a checklist (see § 3 footnote).

5. Customization Suggestions

• When customizing the “implement from technical design” logic for your project, prioritize adjusting f2s-implement-tech-design: Cursor .cursor/rules/f2s-implement-tech-design.mdc, Claude .claude/rules/f2s-implement-tech-design.md; Codex uses .codex/AGENTS.md and associated skills/ as the source of truth.
• Running init again by default only fills in missing templates and performs package-level structural alignment — it does not replace f2s-* skills for maintaining business content. To reset .Knowledge from the template, add --reset-knowledge.

6. Skill Identification

Skills are triggered by matching name and description. Files are located under config-root/skills/*/SKILL.md.

7. Related Documents

• Flow2Spec Introduction
• Commands Reference
• Directory Conventions
• Architecture
• Usage Scenarios
• Team Collaboration
• Project Milestones