flow-comet

An automated execution engine that turns AI coding discipline into a verifiable state machine — for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.
For AI coding workflows — deterministic state machine · protocol-driven · guard-validated · subagent-isolated

---

Why

If you use skill-based disciplines like superpowers, OpenSpec, or GSD, you know the pain: discipline relies on the model's compliance, and progress lives in chat history. flow-comet turns the flow-kit 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) from a discipline-dependent manual flow into a verifiable deterministic state machine:

• Automated routing — scripts manage stage transitions, guard validations, and hook-based write interception
• Protocol-driven — the built-in 8-node protocol is the default workflow; custom protocols composed from any installed skill run on the same engine (see Custom Protocols)
• Three defense layers — physical write interception (hook), coordinator prohibition, and exit takeover detection
• Subagent-isolated execution — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
• File-as-truth recovery — state is derived from .specs/ artifacts, so recovery never depends on conversation history

Quick Start

Requires Claude Code, Codex, or DeepSeek Harness (dsh) and flow-kit in the target project (see Installation).

# 1. Install from this repository (option A: prepare-env installer)
cd <flow-comet repo>
node scripts/prepare-env.mjs --target <absolute path to your project>

On an interactive terminal, the first run prompts for the platform with a multi-select (arrow keys + space to toggle, Enter to confirm; the default is Claude Code); for a non-interactive pick, add --platform codex / --platform dsh / --platform claude-code,dsh (comma-separated) / --platform all.

By default the installer targets Claude Code (unchanged behavior). For Codex: node scripts/prepare-env.mjs --target <path> --platform codex — skills install to .agents/skills/ (auto-discovered), orchestration rules are injected into an AGENTS.md managed block, and the write-guard hook intercepts Bash write commands via Codex's PreToolUse (trust the hook on first use: /hooks). For DeepSeek Harness: node scripts/prepare-env.mjs --target <path> --platform dsh — skills install to .dsh/skills/flow-comet (auto-discovered at rank 100, no restart), orchestration rules are injected into an AGENTS.md managed block, and a thin bridge loader is mounted globally in $DSH_HOME (see Installation → Option C). When run on an interactive terminal (TTY) without --platform, the installer prompts for the target platform with a multi-select (pre-checked from existing traces — default Claude Code — press Enter to accept); without a TTY (CI/scripts) existing .claude/ / .codex/ / .dsh/ in the target project is detected, falling back to Claude Code.

For DeepSeek Harness (dsh), install through the same installer — no plugin bundle or npm package is involved:

node scripts/prepare-env.mjs --target <absolute path to your project> --platform dsh

This installs the skill tree project-locally at <project>/.dsh/skills/flow-comet (dsh auto-discovers skills there at rank 100 without a restart — projects without that directory cannot see the skill, which makes activation naturally project-level), injects the orchestration rules into an AGENTS.md managed block (non-destructive merge), and mounts a thin bridge loader globally at $DSH_HOME/plugins/dsh-flow-comet-bridge.mjs with a managed block in $DSH_HOME/cordis.patch.yml (read-merge-write, preserves existing blocks such as dsh-skin, effective for all profiles). The bridge intercepts write tools via dsh's tools/pre-execute event. Minimum dsh 0.1.0-rc.6; the npm package is not published yet (planned for 1.5.0). See Installation → Option C for the full dsh platform section.

# 2. Open your project in a new Claude Code session and run:
/flow-comet
#    (Codex: invoke the skill in a Codex session — `/use flow-comet` or natural language;
#     same workflow, see Installation → "Using flow-comet on Codex")

The first call confirms scope, then automatically creates the change/<id> branch, initializes state, enters the open node, and produces CHANGE.md / REQUIREMENT.md. Every subsequent stage is routed automatically — you only answer decision points (scope, tech stack, destructive changes, review findings, archive confirmation).

On first use in a project, the workflow automatically detects whether a project context (CONTEXT.md) exists and prompts to initialize it when missing — existing AI-context documents (such as CLAUDE.md / AGENTS.md) are read and integrated with source attribution, and existing files are never modified. Projects with a fresh context run silently. No separate command to remember.

Usage

• 8-node workflow — node-by-node responsibilities, branch mode, execution modes, decision points
• Custom protocols — compose any installed skill into a custom workflow via /flow-comet-compose
• Core mechanisms — state machine, three defense layers, guard validation, execution model
• Troubleshooting — BLOCKED/WARN messages and their fixes

The entry point is the /flow-comet command; state is inspected and advanced from the command line (paths below assume the Claude Code install .claude/skills/; Codex installs to .agents/skills/, dsh to .dsh/skills/ — see Installation):

node .claude/skills/flow-comet/scripts/workflow-state.mjs status   # current change + node
node .claude/skills/flow-comet/scripts/workflow-state.mjs next     # next node + skill

Architecture

graph LR
    O[open] --> D[design] --> P[plan] --> E[execute]
    E <--> SE[subagent-execute]
    E --> R[review] --> V[verify] --> A[archive]
    style O fill:#e8f5e9
    style D fill:#e3f2fd
    style P fill:#fff3e0
    style E fill:#fce4ec
    style SE fill:#f3e5f5
    style R fill:#e8eaf6
    style V fill:#e0f7fa
    style A fill:#f1f8e9

The engine routes between nodes by deriving state from .specs/ artifacts (determineNode), gated by guard exit validations.

What is flow-kit

flow-kit is a pure-Markdown development methodology that fuses mainstream AI coding workflows — superpowers, OpenSpec, spec-kit, GSD, gstack, claude-task-master — into its own 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) with .specs/ artifact templates and R1-R8 behavior rules. No runtime, no CLI — clone it into a project and it defines what to produce and what rules to follow, but progress relies on human (and AI) discipline.

Why flow-comet

Horizontal comparison

Project	Positioning	Mechanism	Relationship to flow-comet
flow-kit	Pure-Markdown methodology pack: 9-stage process + .specs/ templates + R1-R8 rules, zero runtime	Humans load prompt files stage by stage; state flows through .md artifacts	Dependency / base — flow-comet is its automation layer; artifacts and rules fully inherited
OpenSpec (Fission-AI)	Spec-driven development framework: a lightweight spec layer before coding	openspec/ directory, one proposal/specs/design/tasks per change, propose→apply→verify→archive	Idea source + lighter alternative — spec-first thinking fused into flow-kit; standalone use is lighter (no state machine, no stage gates)
Superpowers (obra)	Claude Code skill set + full dev methodology	Composable skills (brainstorm/plan/TDD/debug/review), triggered by context, enforced by instructions	Idea source + partial overlap — skill-based discipline relies on model compliance; flow-comet scripts and machine-verifies the same discipline
comet (rpamis)	Resumable long-task workflows + skill platform: protocol state machine, guard gates, hook interception	/comet routes by config; Classic = OpenSpec + Superpowers 5-stage state machine	Mechanism source — flow-comet borrows its mechanism shapes (protocol-as-truth, script-owned state, guard gates, hook whitelist) and drops its platform facilities (eval/publish); state does not interoperate with Comet Classic
GSD	Spec-driven development meta-prompt / context-engineering workflow	Milestones → slices → tasks; fresh context per stage with pre-inlined context; worktree isolation + UAT	Idea source (same lane) — fresh-context execution and stage gates align; no script state-machine routing, relies on prompt discipline
spec-kit (GitHub)	SDD toolkit: Spec → Plan → Tasks → Implement	Each stage feeds markdown artifacts to the next; task format with order IDs, parallel [P] markers, file paths	Idea source (same lane) — task-with-file-paths/parallel-marker shape is same-origin with flow-kit TASK; no stage-transition enforcement
claude-task-master	AI-driven task management (MCP + CLI)	PRD parsing → task decomposition → dependency graph → next-task orchestration	Complement — manages the task layer only (decomposition/ordering/dependencies), not stage gates, artifact validation, or write permissions

Vertical comparison: manual flow-kit → flow-comet

Dimension	Manual flow-kit (discipline)	flow-comet (automated)
Stage routing	Humans remember the flow and load prompts manually; skipping stages is on you	Scripts derive the current node from .specs/ artifacts and route automatically; order violations are blocked
Validation	Humans eyeball artifacts against the rules; TEST.md commands "should" run	Guards enforce required artifacts/sections at every node entry/exit; verify actually executes the TEST.md commands and counts failures
Discipline enforcement	Rules are markdown text the model may ignore	Three defense layers: write whitelist physically blocks out-of-scope writes / coordinator prohibition / exit takeover detection
Recovery	Depends on conversation memory; progress is lost across sessions	File-as-truth: re-derive the node from .specs/ and auto-correct state; any session resumes correctly
Parallel implementation	Humans coordinate multiple windows, easy to overstep	Subagents implement in isolated worktrees (coordinators cannot write source) and must return a verified contract (commit hash + evidence)
Decision burden	A confirmation point at every stage, humans answer everything	Decisions are classified (user-decided / auto-handled / stop conditions / manual handover); humans only intervene at key points (scope, tech stack, breaking changes, review findings, archive)

Why pick flow-comet

1. Discipline goes from "self-discipline" to "machine-checked" — every stage entry/exit has script validation: artifacts complete, sections filled, verify commands actually run, tasks stay in bounds.
2. No lost progress across sessions — where you are is always derived from .specs/ artifacts, never from conversation memory; reopen and continue from the right node.
3. Implementation and coordination are physically separated — implementation runs in fresh-context subagents inside isolated worktrees and must return a verified contract; the coordinator is banned from writing source, and the write whitelist blocks violations at the physical layer.
4. The native automation layer for flow-kit — not a re-invention: artifact formats, rules, and stages are identical to flow-kit; a flow-kit project upgrades to a machine-driven flow by installing flow-comet, no migration needed.
5. Protocol-driven, zero dependencies, copy-and-run — the built-in 8-node flow works out of the box; any installed skill can be composed into a custom protocol on the same engine; Node.js 18+, no third-party dependencies, one command installs it.

Fit: flow-comet is built for long-running, multi-session development changes on Claude Code — the discipline it automates pays off when a change spans hours and multiple sessions. It is not a general CI/CD or project-management tool; Codex and DeepSeek Harness are supported (see Installation), other platforms (Gemini / Cursor) are not guaranteed.

Real-run artifacts

A complete 8-node run produces the full artifact trail shown in docs/examples/processor-pipeline — a real archived change (end-to-end test project, 2026-08-13): CHANGE / REQUIREMENT / DESIGN / TASK / six-section summaries / REVIEW with disposition markers / TEST / UAT / KNOWN-ISSUES / skill-load declaration markers.

processor-pipeline/            (archived change, full artifact set)
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
├── T01~T06-SUMMARY.md          (six-section summaries)
├── REVIEW.md                   (findings with disposition markers)
├── TEST.md / UAT.md            (verify actually executes the test command)
├── KNOWN-ISSUES.md
└── .skill-loads/               (11 skill-load declaration markers)

Stable skill triggering — workflow skills keep loading correctly through a 4h+ session:

5-hour verification run — full validation and UAT at the end of a 5h14m session (↓399k tokens):

Ecosystem

Project	Role	Relationship to flow-comet
flow-kit	Methodology & artifact system (9-stage flow, .specs/ templates, R1-R8 rules)	Dependency — flow-comet is its automation layer; artifacts and rules come from flow-kit
Comet	Skill Creator ecosystem (bundle authoring, hook-guard pattern, state machine)	Mechanism source — flow-comet borrows Comet's mechanism patterns extensively (workflow-protocol as source of truth, script-owned state, guard gates, hook interception); runtime optional (copy install needs no Comet CLI). Details in Ecosystem
Comet Classic	Comet's classic workflow (OpenSpec + Superpowers)	Not a dependency — flow-comet is an independent workflow-kernel; state does not interoperate with classic (own .comet/flow-comet-state.json + file-derived routing)

Directory Structure

flow-comet/
├── .comet/bundle-drafts/   ★ authoritative source (19 skills + scripts)
├── scripts/                prepare-env installer
├── docs/
│   ├── examples/           workflow artifact examples
│   ├── ECOSYSTEM.md        roles of flow-kit & Comet, borrowing boundaries
│   ├── INSTALLATION.md     installation guide
│   ├── USAGE.md            usage guide
│   ├── PROTOCOL.md         custom protocol guide
│   ├── MECHANISM.md        core mechanisms (behavior layer)
│   ├── TROUBLESHOOTING.md  failure diagnosis
│   └── VERSIONS.md         versioning & compatibility
└── CHANGELOG.md            Keep a Changelog style

Tech Stack

Layer	Technology
Runtime	Node.js ≥ 18 (ESM, zero third-party dependencies)
Platform	Claude Code (default — skills, .claude/ installation, hooks); Codex (.agents/skills/, AGENTS.md managed rules, PreToolUse write interception); DeepSeek Harness (.dsh/skills/flow-comet project-level skill, AGENTS.md managed rules, bridge loader + tools/pre-execute interception)
Methodology	flow-kit (artifacts, rules, templates)

Documentation

Document	Description
Ecosystem	Roles of flow-kit & Comet, what flow-comet borrows and deliberately does not
Installation	Prerequisites, prepare-env options A/B/C, installation verification
Usage	8-node workflow, branch mode, execution modes, decision points
Custom Protocols	Compose skills into custom workflows
Core Mechanisms	State machine, defense layers, guard validation
Troubleshooting	Common errors and fixes
Versions	SemVer policy, compatibility
Examples	Full workflow artifact examples
Changelog	Version history (Keep a Changelog)
Security	How to report vulnerabilities
Code of Conduct	Community guidelines

Contributing

Full guide in CONTRIBUTING.md — branch model (feature → dev → main), PR workflow, merge rules, and commit convention. In short:

1. Branch from dev: git checkout dev && git checkout -b feat/<description>
2. Edit skills/scripts under .comet/bundle-drafts/flow-comet/skills/ (authoritative source); TDD with RED scenario first
3. Run regression: node .comet/bundle-drafts/flow-comet/skills/flow-comet/scripts/guard-self-test.mjs → ALL 144 SCENARIOS PASSED
4. Open a PR into dev (squash — one change-level commit); release PR dev → main (merge — dev's change-level commits enter main, and dev stops leading after each release)

CI enforces the repository conventions automatically on every PR and push (regression, PR discipline, version consistency, dead links). Local hooks (commit/push message checks) install with node scripts/install-commit-hook.mjs — see CONTRIBUTING.md for the full guide.

License

MIT © 2026 baobaolaodie

flow-comet depends on flow-kit (MIT) and Comet (MIT).