flow-comet 1.5.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/.flow-comet/rules/flow-comet-orchestration.md +13 -0
  2. package/.flow-comet/skills/flow-comet/GUIDANCE.md +196 -0
  3. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -0
  4. package/.flow-comet/skills/flow-comet/SKILL.md +196 -0
  5. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +19 -0
  6. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +115 -0
  7. package/.flow-comet/skills/flow-comet/reference/authoring-lanes.json +33 -0
  8. package/.flow-comet/skills/flow-comet/reference/composition-report.md +65 -0
  9. package/.flow-comet/skills/flow-comet/reference/decision-points.md +64 -0
  10. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +30 -0
  11. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +169 -0
  12. package/.flow-comet/skills/flow-comet/reference/init-detection.md +58 -0
  13. package/.flow-comet/skills/flow-comet/reference/recovery.md +20 -0
  14. package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +661 -0
  15. package/.flow-comet/skills/flow-comet/reference/skill-review.md +13 -0
  16. package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +7 -0
  17. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +681 -0
  18. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +52 -0
  19. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +61 -0
  20. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +909 -0
  21. package/.flow-comet/skills/flow-comet/scripts/comet-plan.mjs +2 -0
  22. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +312 -0
  23. package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +136 -0
  24. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +7331 -0
  25. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +376 -0
  26. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +230 -0
  27. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +99 -0
  28. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +4017 -0
  29. package/.flow-comet/skills/flow-comet/scripts/task-parsing.mjs +28 -0
  30. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +2396 -0
  31. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +378 -0
  32. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +1263 -0
  33. package/.flow-comet/skills/flow-comet-archive/SKILL.md +195 -0
  34. package/.flow-comet/skills/flow-comet-change/SKILL.md +29 -0
  35. package/.flow-comet/skills/flow-comet-compose/SKILL.md +249 -0
  36. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +23 -0
  37. package/.flow-comet/skills/flow-comet-design/SKILL.md +161 -0
  38. package/.flow-comet/skills/flow-comet-dev/SKILL.md +51 -0
  39. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +26 -0
  40. package/.flow-comet/skills/flow-comet-execute/SKILL.md +182 -0
  41. package/.flow-comet/skills/flow-comet-health/SKILL.md +31 -0
  42. package/.flow-comet/skills/flow-comet-integration/SKILL.md +45 -0
  43. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +36 -0
  44. package/.flow-comet/skills/flow-comet-open/SKILL.md +161 -0
  45. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +33 -0
  46. package/.flow-comet/skills/flow-comet-plan/SKILL.md +169 -0
  47. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +27 -0
  48. package/.flow-comet/skills/flow-comet-review/SKILL.md +204 -0
  49. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +29 -0
  50. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +214 -0
  51. package/.flow-comet/skills/flow-comet-task/SKILL.md +33 -0
  52. package/.flow-comet/skills/flow-comet-test/SKILL.md +41 -0
  53. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +26 -0
  54. package/.flow-comet/skills/flow-comet-verify/SKILL.md +164 -0
  55. package/LICENSE +21 -0
  56. package/README.md +255 -0
  57. package/package.json +27 -0
  58. package/scripts/dsh-bridge.mjs +461 -0
  59. package/scripts/prepare-env.mjs +1526 -0
package/README.md ADDED
@@ -0,0 +1,255 @@
1
+ <div align="right">
2
+
3
+ [English](README.md) · [中文](README-zh.md)
4
+
5
+ </div>
6
+
7
+ <h1 align="center">flow-comet</h1>
8
+
9
+ <p align="center">
10
+ <strong>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.</strong>
11
+ <br />
12
+ <em>For AI coding workflows — deterministic state machine · protocol-driven · guard-validated · subagent-isolated</em>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="#quick-start"><img src="https://img.shields.io/badge/Quick_Start-4CAF50?style=for-the-badge" alt="Quick Start" /></a>
17
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License" /></a>
18
+ </p>
19
+
20
+ <p align="center">
21
+ <a href="https://claude.ai/code"><img src="https://img.shields.io/badge/Claude_Code-D97757?style=flat&logo=claude&logoColor=white" alt="Claude Code" /></a>
22
+ <a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/Codex-10A37F?style=flat&logoColor=white" alt="Codex" /></a>
23
+ <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek_Harness-4D6BFE?style=flat&logoColor=white" alt="DeepSeek Harness" /></a>
24
+ <a href="https://github.com/rihebty/flow-kit"><img src="https://img.shields.io/badge/flow--kit-4CAF50?style=flat" alt="flow-kit" /></a>
25
+ <a href="https://github.com/rpamis/comet"><img src="https://img.shields.io/badge/comet-4CAF50?style=flat" alt="comet" /></a>
26
+ </p>
27
+
28
+ <p align="center">
29
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
30
+ <a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
31
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.5.0--rc.3-blue.svg" alt="Version" /></a>
32
+ </p>
33
+
34
+ ---
35
+
36
+ ## Why
37
+
38
+ If you use skill-based disciplines like [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), or [GSD](https://github.com/open-gsd/gsd-core), 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**:
39
+
40
+ - **Automated routing** — scripts manage stage transitions, guard validations, and hook-based write interception
41
+ - **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](docs/PROTOCOL.md))
42
+ - **Three defense layers** — physical write interception (hook), coordinator prohibition, and exit takeover detection
43
+ - **Subagent-isolated execution** — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
44
+ - **File-as-truth recovery** — state is derived from `.specs/` artifacts, so recovery never depends on conversation history
45
+
46
+ ## Quick Start
47
+
48
+ Requires [Claude Code](https://claude.ai/code), [Codex](https://github.com/openai/codex), or [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) and [flow-kit](https://github.com/rihebty/flow-kit) in the target project (see [Installation](docs/INSTALLATION.md)).
49
+
50
+ ```bash
51
+ # 1. Install the CLI globally (Node.js 18+)
52
+ npm install -g flow-comet
53
+
54
+ # 2. Install flow-comet into your project, from the project directory
55
+ cd <your project>
56
+ fcomet init
57
+ ```
58
+
59
+ The package ships two command names pointing at the same installer — `fcomet` (primary) and `flow-comet` (alias). The `init` token is optional (a bare `fcomet` is equivalent) and `--target <dir>` is optional too (default: the current working directory). Re-running the same command updates an existing install and is idempotent.
60
+
61
+ On an interactive terminal, the first run prompts for the platform with a direction-key multi-select (arrow keys + space to toggle, Enter to confirm; the default is Claude Code) — `@clack/prompts` is the primary path, with an automatic readline number/comma multi-select fallback when the dependency is not installed, offline, or stdin has no raw mode (`FLOW_COMET_FORCE_READLINE=1` forces the fallback for testing); for a non-interactive pick, add `--platform codex` / `--platform dsh` / `--platform claude-code,dsh` (comma-separated) / `--platform all`.
62
+
63
+ **Updating**: a global package upgrade does not touch projects that are already installed — re-run `fcomet init` in each project to pick up the new files. And because an npm install has no git history to derive a development marker from, the version marker it writes (`<project>/.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/…` for Codex, `.dsh/skills/…` for dsh) is the release version shipped inside the package; the `<release>-<n>-g<hash>` form appears only for installs run from a repository clone that has git and tags.
64
+
65
+ By default the installer targets Claude Code (unchanged behavior). For Codex: `fcomet init --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: `fcomet init --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 D](docs/INSTALLATION.md#option-d--deepseek-harness-dsh-platform)). 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.
66
+
67
+ The installer also ensures `flow-kit` in the target project: when missing it clones the upstream and checks out the locked snapshot `9b5dda7`; an existing upstream clone is only inspected (current HEAD vs the locked snapshot is reported, read-only); a same-name non-clone directory is skipped with guidance; a network failure warns and continues; purge never touches it.
68
+
69
+ The same installer also runs straight from a repository clone, with no global package — that is the path this repository's own workflow and its distribution to other projects use (Option B in the installation guide):
70
+
71
+ ```bash
72
+ cd <flow-comet repo>
73
+ node scripts/prepare-env.mjs --target <absolute path to your project>
74
+ ```
75
+
76
+ For DeepSeek Harness (dsh), install through the same installer — a dedicated dsh platform descriptor, with no separate plugin bundle:
77
+
78
+ ```bash
79
+ cd <your project>
80
+ fcomet init --platform dsh
81
+ ```
82
+
83
+ 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. Interception only applies while a flow is running — in an idle session, writes outside the project root are not interrupted. Each install reports the dsh loader version transition (upgrade / downgrade / consistent) by comparing the embedded version stamp with the previously installed loader, and `workflow-state.mjs bridge-check` is a read-only health check with six states (healthy / file missing / not mounted / version skew / duplicate registration / not applicable). Minimum dsh `0.1.0-rc.6`. See [Installation → Option D](docs/INSTALLATION.md#option-d--deepseek-harness-dsh-platform) for the full dsh platform section.
84
+
85
+ ```bash
86
+ # 3. Open your project in a new Claude Code session and run:
87
+ /flow-comet
88
+ # (Codex: invoke the skill in a Codex session — `/use flow-comet` or natural language;
89
+ # same workflow, see Installation → "Using flow-comet on Codex")
90
+ ```
91
+
92
+ 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).
93
+
94
+ 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.
95
+
96
+ ## Usage
97
+
98
+ - **[8-node workflow](docs/USAGE.md)** — node-by-node responsibilities, branch mode, execution modes, decision points
99
+ - **[Custom protocols](docs/PROTOCOL.md)** — compose any installed skill into a custom workflow via `/flow-comet-compose`
100
+ - **[Core mechanisms](docs/MECHANISM.md)** — state machine, three defense layers, guard validation, execution model
101
+ - **[Troubleshooting](docs/TROUBLESHOOTING.md)** — BLOCKED/WARN messages and their fixes
102
+
103
+ 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](docs/INSTALLATION.md)):
104
+
105
+ ```bash
106
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs status # current change + node
107
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs next # next node + skill
108
+ ```
109
+
110
+ ## Architecture
111
+
112
+ ```mermaid
113
+ graph LR
114
+ O[open] --> D[design] --> P[plan] --> E[execute]
115
+ E <--> SE[subagent-execute]
116
+ E --> R[review] --> V[verify] --> A[archive]
117
+ style O fill:#e8f5e9
118
+ style D fill:#e3f2fd
119
+ style P fill:#fff3e0
120
+ style E fill:#fce4ec
121
+ style SE fill:#f3e5f5
122
+ style R fill:#e8eaf6
123
+ style V fill:#e0f7fa
124
+ style A fill:#f1f8e9
125
+ ```
126
+
127
+ The engine routes between nodes by deriving state from `.specs/` artifacts (determineNode), gated by guard exit validations.
128
+
129
+ ## What is flow-kit
130
+
131
+ [flow-kit](https://github.com/rihebty/flow-kit) is a pure-Markdown development methodology that fuses mainstream AI coding workflows — [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [spec-kit](https://github.com/github/spec-kit), [GSD](https://github.com/open-gsd/gsd-core), [gstack](https://github.com/garrytan/gstack), [claude-task-master](https://github.com/eyaltoledano/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.
132
+
133
+ ## Why flow-comet
134
+
135
+ ### Horizontal comparison
136
+
137
+ | Project | Positioning | Mechanism | Relationship to flow-comet |
138
+ |---------|-------------|-----------|---------------------------|
139
+ | **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 |
140
+ | **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) |
141
+ | **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 |
142
+ | **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 |
143
+ | **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 |
144
+ | **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 |
145
+ | **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 |
146
+
147
+ ### Vertical comparison: manual flow-kit → flow-comet
148
+
149
+ | Dimension | Manual flow-kit (discipline) | flow-comet (automated) |
150
+ |-----------|------------------------------|------------------------|
151
+ | 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 |
152
+ | 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 |
153
+ | 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 |
154
+ | 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 |
155
+ | 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) |
156
+ | 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) |
157
+
158
+ ### Why pick flow-comet
159
+
160
+ 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.
161
+ 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.
162
+ 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.
163
+ 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.
164
+ 5. **Protocol-driven, minimal dependency, install-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+; the only third-party dependency is `@clack/prompts`, used exclusively by the installer's TTY multi-select (with an automatic readline fallback otherwise); one command installs it.
165
+
166
+ **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](docs/INSTALLATION.md#platforms)), other platforms (Gemini / Cursor) are not guaranteed.
167
+
168
+ ## Real-run artifacts
169
+
170
+ A complete 8-node run produces the full artifact trail shown in [docs/examples/processor-pipeline](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.
171
+
172
+ ```
173
+ processor-pipeline/ (archived change, full artifact set)
174
+ ├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
175
+ ├── T01~T06-SUMMARY.md (six-section summaries)
176
+ ├── REVIEW.md (findings with disposition markers)
177
+ ├── TEST.md / UAT.md (verify actually executes the test command)
178
+ ├── KNOWN-ISSUES.md
179
+ └── .skill-loads/ (11 skill-load declaration markers)
180
+ ```
181
+
182
+ **Stable skill triggering** — workflow skills keep loading correctly through a 4h+ session:
183
+
184
+ ![Skill triggering](images/long-run-4h-and-skill-triggering.png)
185
+
186
+ **5-hour verification run** — full validation and UAT at the end of a 5h14m session (↓399k tokens):
187
+
188
+ ![Verification run](images/long-run-5h.png)
189
+
190
+ ## Ecosystem
191
+
192
+ | Project | Role | Relationship to flow-comet |
193
+ |---------|------|---------------------------|
194
+ | [flow-kit](https://github.com/rihebty/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 |
195
+ | [Comet](https://github.com/rpamis/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](docs/ECOSYSTEM.md) |
196
+ | **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 `.flow-comet/flow-comet-state.json` + file-derived routing) |
197
+
198
+ ## Directory Structure
199
+
200
+ ```
201
+ flow-comet/
202
+ ├── .flow-comet/ ★ authoritative source (skills/ + rules/)
203
+ ├── scripts/ prepare-env installer (npm bin: fcomet / flow-comet)
204
+ ├── docs/
205
+ │ ├── examples/ workflow artifact examples
206
+ │ ├── ECOSYSTEM.md roles of flow-kit & Comet, borrowing boundaries
207
+ │ ├── INSTALLATION.md installation guide
208
+ │ ├── USAGE.md usage guide
209
+ │ ├── PROTOCOL.md custom protocol guide
210
+ │ ├── MECHANISM.md core mechanisms (behavior layer)
211
+ │ ├── TROUBLESHOOTING.md failure diagnosis
212
+ │ └── VERSIONS.md versioning & compatibility
213
+ └── CHANGELOG.md Keep a Changelog style
214
+ ```
215
+
216
+ ## Tech Stack
217
+
218
+ | Layer | Technology |
219
+ |-------|------------|
220
+ | Runtime | Node.js ≥ 18 (ESM); third-party dependency: `@clack/prompts` (pinned exact version, installer TTY multi-select only — automatic readline fallback when unavailable) |
221
+ | 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) |
222
+ | Methodology | [flow-kit](https://github.com/rihebty/flow-kit) (artifacts, rules, templates) |
223
+
224
+ ## Documentation
225
+
226
+ | Document | Description |
227
+ |----------|-------------|
228
+ | [Ecosystem](docs/ECOSYSTEM.md) | Roles of flow-kit & Comet, what flow-comet borrows and deliberately does not |
229
+ | [Installation](docs/INSTALLATION.md) | Prerequisites, install options A–D (npm / prepare-env / manual copy / dsh), installation verification |
230
+ | [Usage](docs/USAGE.md) | 8-node workflow, branch mode, execution modes, decision points |
231
+ | [Custom Protocols](docs/PROTOCOL.md) | Compose skills into custom workflows |
232
+ | [Core Mechanisms](docs/MECHANISM.md) | State machine, defense layers, guard validation |
233
+ | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common errors and fixes |
234
+ | [Versions](docs/VERSIONS.md) | SemVer policy, compatibility |
235
+ | [Examples](docs/examples/) | Full workflow artifact examples |
236
+ | [Changelog](CHANGELOG.md) | Version history (Keep a Changelog) |
237
+ | [Security](SECURITY.md) | How to report vulnerabilities |
238
+ | [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines |
239
+
240
+ ## Contributing
241
+
242
+ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature → dev → main`), PR workflow, merge rules, and commit convention. In short:
243
+
244
+ 1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
245
+ 2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
246
+ 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 241 SCENARIOS PASSED`
247
+ 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)
248
+
249
+ 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](CONTRIBUTING.md) for the full guide.
250
+
251
+ ## License
252
+
253
+ [MIT](LICENSE) © 2026 baobaolaodie
254
+
255
+ flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT) and [Comet](https://github.com/rpamis/comet) (MIT).
package/package.json ADDED
@@ -0,0 +1,27 @@
1
+ {
2
+ "name": "flow-comet",
3
+ "version": "1.5.0-rc.3",
4
+ "description": "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.",
5
+ "type": "module",
6
+ "files": [
7
+ ".flow-comet/skills",
8
+ ".flow-comet/rules",
9
+ "scripts/prepare-env.mjs",
10
+ "scripts/dsh-bridge.mjs"
11
+ ],
12
+ "bin": {
13
+ "fcomet": "scripts/prepare-env.mjs",
14
+ "flow-comet": "scripts/prepare-env.mjs"
15
+ },
16
+ "engines": {
17
+ "node": ">=18"
18
+ },
19
+ "license": "MIT",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/baobaolaodie/flow-comet.git"
23
+ },
24
+ "dependencies": {
25
+ "@clack/prompts": "1.7.0"
26
+ }
27
+ }