Spec-Flow coordinates multiple coding tools through a single shared canon. Every agent must read the same rules, reuse the same artifacts, and only write in its designated areas.
.spec-flow/holds the canonical workflow docs, repo map, state schemas, memory, and automation scripts.- In consumer projects,
epics/<slug>/state.yamlis the single source of truth for epic phase progress; feature-levelspecs/<feature>/state.yamlis optional and must mirror the epic. - Roadmaps, specs, plans, tasks, and ship notes all inherit the phase order:
spec → clarify → plan → tasks → implement → optimize → preview → ship → finalize.
.claude/— Claude Code-only prompts, commands, and hooks. Readable by other tools, but only Claude edits this tree..codex/— Codex CLI-specific prompts, commands, adapters, and skills. Codex writes here; other tools leave it alone.- Additional tool adapters must be labeled explicitly until their source-repo surfaces exist.
- Shared assets may live elsewhere in active repo surfaces such as
docs/,bin/,.github/, and.spec-flow/, but every tool must honor.spec-flow/repo-map.yamland.spec-flow/domains/*.yamlwhen deciding where to add code.
- Never fork new “top-level religions.” Add new integrations under their dedicated folder and mirror the shared canon from
.spec-flow/. - All tools may read
.claude/**for reference, yet non-Claude edits are prohibited. - In consumer projects, epic work begins under
epics/<slug>/; features live inspecs/<feature>/and must link back to their parent epic insidestate.yaml. - When progressing any phase, update the relevant
state.yamland stop at the documented review boundaries (no macro “run everything” flows). - Persistent learnings or roadmap shifts belong in
.spec-flow/memory/and should be reflected in the shared docs before modifying tool-specific trees.
Follow these rules and every agent—Claude, Codex, Cursor, or future additions—will operate from the same source of truth.