You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 11, 2026. It is now read-only.
Copy file name to clipboardExpand all lines: CLAUDE.md
+59-5Lines changed: 59 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,20 +4,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
4
4
5
5
## What Is This
6
6
7
-
Flow-Code is a Claude Code plugin for structured, plan-first development. It provides a unified entry point (`/flow-code:run`) plus individual slash commands, skills, and agents that orchestrate task tracking via a `.flow/` directory. Core engine is a Rust binary (`flowctl`) with file-based JSON storage and MCP server support.
7
+
Flow-Code is a Claude Code plugin for structured, plan-first development. It provides two main entry points — `/flow-code:go` (full autopilot: brainstorm → plan → work → review → close) and `/flow-code:run` (plan → work → review → close) — plus individual slash commands, skills, and agents that orchestrate task tracking via a `.flow/` directory. Core engine is a Rust binary (`flowctl`) with file-based JSON storage and MCP server support.
hooks/hooks.json → Ralph workflow guards (active when FLOW_RALPH=1)
18
19
docs/ → Architecture docs, CI examples
19
20
```
20
21
22
+
**Skill directories**: Both `skills/` and `codex/skills/` are scanned. Core workflow skills (plan, work, reviews) live in `codex/skills/` for Codex sync compatibility. Both directories are authoritative.
23
+
21
24
**Skills**: See `docs/skills.md` for the full classification. Core workflow: `flow-code-run` (unified phase loop via `flowctl phase next/done`).
22
25
23
26
**Key invariant**: The `bin/flowctl` Rust binary is the single source of truth for `.flow/` state. Always invoke as:
@@ -28,10 +31,52 @@ $FLOWCTL <command>
28
31
29
32
## Primary Workflow
30
33
31
-
`/flow-code:run "description"` — drives the entire pipeline (plan → plan-review → work → impl-review → close) via `flowctl phase next/done`. One command, zero manual phase transitions.
34
+
`/flow-code:go "idea"` — full autopilot from raw idea to PR. Runs auto-brainstorm (AI self-interview) → plan → plan-review → work → impl-review → close. Zero human input.
35
+
36
+
`/flow-code:run "description"` — drives the pipeline (plan → plan-review → work → impl-review → close) via `flowctl phase next/done`. Skips brainstorm — use when requirements are already clear.
32
37
33
38
Ralph (`/flow-code:ralph-init`) is the autonomous harness that runs this loop unattended.
34
39
40
+
## Quality Gates (Three Layers)
41
+
42
+
Every epic passes through three independent, non-overlapping review gates:
43
+
44
+
| Layer | Tool | When | What it catches |
45
+
|-------|------|------|-----------------|
46
+
|**1. Guard**|`flowctl guard`| Worker Phase 6, wave checkpoint, close phase | Lint, type errors, test failures |
47
+
|**2. RP Plan-Review**| RP context_builder or Codex | Plan phase | Spec-code misalignment, missing requirements |
All three must pass (or be skipped via `flowctl config set review.backend none`). Layers are complementary — guard catches syntax, RP catches spec drift, Codex catches blind spots.
51
+
52
+
## Command Flags
53
+
54
+
| Flag | Accepted by | Effect |
55
+
|------|-------------|--------|
56
+
|`--auto`| brainstorm | AI self-interview, zero human input |
57
+
|`--plan-only`| go, plan, run | Stop after plan phase |
58
+
|`--no-pr`| go, run | Skip draft PR creation at close |
59
+
|`--tdd`| work, run | Force test-first development (worker Phase 4) |
60
+
|`--interactive`| plan | Opt-in interview before planning |
61
+
|`--no-capability-scan`| plan | Skip capability-scout |
62
+
|`--research=rp\|grep`| plan | Override research backend |
63
+
|`--depth=short\|standard\|deep`| plan | Override plan depth |
64
+
|`--review=rp\|codex\|none`| plan, run | Override review backend |
65
+
66
+
## Worker Protocol (Teams Mode)
67
+
68
+
Workers communicate with the coordinator via SendMessage with summary prefixes:
-**Agent Teams mode**: `/flow-code:run` (or legacy `/flow-code:work`) spawns workers as Agent Team teammates with plain-text protocol messages (summary-prefix routing: "Task complete:", "Spec conflict:", "Blocked:", "Need file access:", "New task:", "Access granted/denied:", native `shutdown_request`) and file lock enforcement
89
137
-**Adversarial review**: `flowctl codex adversarial --base main [--focus "area"]` runs Codex in adversarial mode — tries to break the code, not validate it. Returns SHIP/NEEDS_WORK with grounded findings
90
-
-**Three-layer quality system**: Layer 1: `flowctl guard` (deterministic lint/type/test, every commit). Layer 2: RP plan-review (code-aware spec validation, invoked via `/flow-code:run` plan-review phase — RP sees full codebase via context_builder). Layer 3: `flowctl codex adversarial` (cross-model adversarial, epic completion — different model family catches blind spots). Spec conflicts and blockers forwarded to Codex for autonomous decision-making.
-**Three-layer quality system**: Layer 1: `flowctl guard` (deterministic lint/type/test — runs at Worker Phase 6, wave checkpoint, and close phase). Layer 2: RP plan-review (code-aware spec validation, invoked via `/flow-code:run` plan-review phase — RP sees full codebase via context_builder). Layer 3: `flowctl codex adversarial` (cross-model adversarial, epic completion — different model family catches blind spots). Spec conflicts and blockers forwarded to Codex for autonomous decision-making.
139
+
-**Review circuit breaker**: Plan review max 2 iterations, impl review max 3, epic review max 2 — prevents infinite NEEDS_WORK cycles. After max iterations, pipeline proceeds with warning
140
+
-**Review backend resolution**: All review phases use the same priority chain: `--review` flag > `FLOW_REVIEW_BACKEND` env > `.flow/config.json` > default `none`. The `--no-review` flag is equivalent to `--review=none` and always wins
92
141
-**Auto-improve analysis-driven**: generates custom program.md from codebase analysis (hotspots, lint, coverage, memory) with Action Catalog ranked by impact — not static templates
93
142
-**Auto-improve quantitative**: captures before/after metrics per experiment, commit messages include delta `[lint:23→21]`
@@ -97,6 +146,11 @@ Rust: clippy for linting, cargo test for tests. No TypeScript, no npm. Skills an
97
146
-**Full-auto by default**: `/flow-code:run` requires zero interactive questions — AI reads git state, `.flow/` config, and request context to make branch, review, and research decisions autonomously. Default mode is Worktree + Teams + Phase-Gate (all three active). Work resumes from `.flow/` state on every startup (not a special "resume mode"). All tasks done → auto push + draft PR (`--no-pr` to skip)
98
147
-**Cross-platform**: flowctl is a single Rust binary (macOS/Linux). RP plan-review auto-degrades to Codex on platforms where rp-cli is unavailable. Bash hooks degrade gracefully on Windows (skip, don't block)
99
148
-**Session start**: CLAUDE.md instruction (not an enforced hook) — if `.flow/` exists, run `flowctl status --interrupted` to check for unfinished work from a previous session and resume with the suggested `/flow-code:work <id>` command
149
+
-**DAG cycle detection**: `flowctl dep add` validates that adding a dependency does not create a cycle in the task dependency graph. If a cycle would be created, the command fails with an error. The DAG is validated using topological sort via the `petgraph` crate
150
+
-**Concurrency-safe state**: All read-modify-write operations on shared JSON state files (pipeline, phases, locks) use advisory file locks via `fs2` to prevent lost updates under concurrent access (e.g., Ralph daemon)
151
+
-**Worker timeout**: Workers have a 30-minute default timeout per task (configurable via `worker.timeout_minutes`). On timeout: task marked failed, file locks released, wave continues
152
+
-**Stale lock recovery**: Runs at wave start AND on worker completion — detects locks held by done/failed/blocked tasks and releases them to prevent deadlocks
153
+
-**Worker phase mapping**: Workers execute 12 internal phases (via `flowctl worker-phase next/done`) within the epic "Work" phase. Epic phases and worker phases are independent systems operating at different levels
@@ -66,7 +66,8 @@ A **harness** wraps around an AI coding agent to handle everything the model can
66
66
Flow-Code is a **harness engineering framework** for Claude Code. One command goes from idea to draft PR — planning, parallel implementation, three-layer quality gates, and cross-model adversarial review, all fully automated.
67
67
68
68
```
69
-
/flow-code:plan "Add OAuth login"
69
+
/flow-code:go "Add OAuth login"
70
+
→ AI self-interview (auto-brainstorm)
70
71
→ AI research (adaptive scouts)
71
72
→ RP plan-review (code-aware)
72
73
→ Teams parallel workers (file locking)
@@ -113,11 +114,14 @@ Rationale: keeps the system simple, improves re-anchoring, makes automation (Ral
113
114
Say one sentence. Flow-Code plans, implements, tests, commits, and opens a draft PR — zero questions asked. AI reads git state and `.flow/` config to make all decisions (branch, review backend, research depth) autonomously.
114
115
115
116
```bash
116
-
# Full auto: plan → implement → test → commit → draft PR
117
-
/flow-code:plan "add OAuth support"
117
+
# Full autopilot: brainstorm → plan → implement → test → commit → draft PR
118
+
/flow-code:go "add OAuth support"
119
+
120
+
# Skip brainstorm: plan → implement → review → close
121
+
/flow-code:run "add OAuth support"
118
122
119
123
# Resume anytime — reads .flow state and continues from where it left off
120
-
/flow-code:work fn-1
124
+
/flow-code:run fn-1
121
125
122
126
# One task at a time for maximum control
123
127
/flow-code:work fn-1.1
@@ -165,6 +169,12 @@ Guard is deterministic. RP validates against existing code. Codex (GPT) tries to
|`--plan-only`| Skip brainstorm, plan only, stop after planning |
1363
+
|`--no-pr`| Skip draft PR creation at close |
1364
+
1365
+
Full autopilot: auto-brainstorm (AI self-interview) → plan → plan-review → work → impl-review → close → push + draft PR. Zero human input. Use `/flow-code:run fn-N` to resume an interrupted epic.
1366
+
1367
+
#### `/flow-code:brainstorm`
1368
+
1369
+
```
1370
+
/flow-code:brainstorm [--auto] <idea>
1371
+
```
1372
+
1373
+
| Input | Description |
1374
+
|-------|-------------|
1375
+
|`<idea>`| Feature or problem description |
1376
+
|`--auto`| AI self-interview mode — no human questions, all answers derived from codebase analysis |
1377
+
1378
+
Produces `.flow/specs/<slug>-requirements.md`. Next step: `/flow-code:plan .flow/specs/<slug>-requirements.md`.
0 commit comments