feat(pipeline): add Brainstorm phase and /flow-code:go entry point (v0.1.33)

- Add Brainstorm as first phase in pipeline state machine
  (Brainstorm → Plan → PlanReview → Work → ImplReview → Close)
- Make /flow-code:go the sole user-facing entry point
- Demote /flow-code:run to internal skill
- Brainstorm auto-skips for existing flow IDs and spec files
- Update all docs, agents, and skills to reference new pipeline

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

.claude-plugin/flowctl-version

@@ -1 +1 @@
-v0.1.29
+v0.1.33

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-code",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default — AI decides from context, zero questions. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR. Auto-detected stack profiles with one-command guard (test/lint/typecheck). Enhanced agent definitions with permissionMode/maxTurns/effort. Lifecycle hooks with state preservation (PreCompact injects .flow state into compaction, TaskCompleted auto-unlocks files, SubagentStart context injection). Memory v2 with atomic entries, dedup, and progressive disclosure. TDD enforcement mode. Multi-epic queue with dependency visualization. Includes 20 subagents, 25+ commands, 23 skills.",
   "author": {
     "name": "z23cc",

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What Is This
 
-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.
+Flow-Code is a Claude Code plugin for structured, plan-first development. The primary entry point is `/flow-code:go` (full autopilot: brainstorm → 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.
 
 ## Core Architecture
 
@@ -31,9 +31,7 @@ $FLOWCTL <command>
 
 ## Primary Workflow
 
-`/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.
-
-`/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.
+`/flow-code:go "idea"` — full autopilot from raw idea to PR. Runs brainstorm (AI self-interview) → plan → plan-review → work → impl-review → close via `flowctl phase next/done`. Zero human input. For existing epics or spec files, brainstorm is auto-skipped.
 
 Ralph (`/flow-code:ralph-init`) is the autonomous harness that runs this loop unattended.
 
@@ -133,17 +131,17 @@ Rust: clippy for linting, cargo test for tests. No TypeScript, no npm. Skills an
 - **Task duration**: `flowctl done` auto-tracks `duration_seconds` from start to completion, rendered in evidence
 - **File ownership**: `flowctl task create --files <paths>` declares owned files; `flowctl files <id>` shows ownership map + conflict detection
 - **File locking (Teams)**: `flowctl lock --task <id> --files <paths>` acquires runtime file locks; `flowctl unlock --task <id>` releases on completion; `flowctl lock-check --file <path>` inspects lock state; `flowctl unlock --all` clears all locks between waves
-- **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
+- **Agent Teams mode**: `/flow-code:go` (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
 - **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
-- **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.
+- **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:go` 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.
 - **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
 - **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
 - **Auto-improve analysis-driven**: generates custom program.md from codebase analysis (hotspots, lint, coverage, memory) with Action Catalog ranked by impact — not static templates
 - **Auto-improve quantitative**: captures before/after metrics per experiment, commit messages include delta `[lint:23→21]`
 - **Worker self-review**: Phase 6 runs guard + structured diff review (correctness, quality, performance, testing) before commit
-- **Plan auto-execute**: `/flow-code:run` (or legacy `/flow-code:plan`) defaults to auto-execute work after planning (Teams mode handles any task count); `--plan-only` to opt out
+- **Plan auto-execute**: `/flow-code:go` (or legacy `/flow-code:plan`) defaults to auto-execute work after planning (Teams mode handles any task count); `--plan-only` to opt out
 - **Goal-backward verification**: worker Phase 10 re-reads acceptance criteria and verifies each is actually satisfied before completing
-- **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)
+- **Full-auto by default**: `/flow-code:go` 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)
 - **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)
 - **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
 - **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

agents/worker.md

@@ -1,6 +1,6 @@
 ---
 name: worker
-description: Task implementation worker. Spawned by flow-code-run during the work phase. Do not invoke directly - use /flow-code:run instead.
+description: Task implementation worker. Spawned by flow-code-run during the work phase. Do not invoke directly - use /flow-code:go instead.
 model: inherit
 disallowedTools: Task
 color: "#3B82F6"
@@ -45,7 +45,7 @@ Do NOT skip phases. Do NOT execute phases out of order. The gate enforces sequen
 The project has two phase models that operate at different levels:
 
 **Epic-level phases** (managed by `flowctl phase next/done`):
-Plan → PlanReview → Work → ImplReview → Close
+Brainstorm → Plan → PlanReview → Work → ImplReview → Close
 
 **Worker-level phases** (managed by `flowctl worker-phase next/done`):
 Phases 1-12 execute WITHIN the epic "Work" phase. Each worker processes one task through all 12 phases while the epic remains in "Work" phase.

commands/flow-code/go.md

@@ -1,13 +1,13 @@
 ---
 name: flow-code:go
-description: "Full autopilot: brainstorm → plan → work → review → close. Zero human input."
+description: "Full autopilot: brainstorm, plan, work, review, close. Zero human input from idea to PR."
 argument-hint: "<idea or problem description>"
 ---
 
-# IMPORTANT: This command MUST invoke the skill `flow-code-go`
+# IMPORTANT: This command MUST invoke the skill flow-code-run
 
-The ONLY purpose of this command is to call the `flow-code-go` skill. You MUST use that skill now.
+The ONLY purpose of this command is to call the flow-code-run skill. You MUST use that skill now.
 
 **User request:** $ARGUMENTS
 
-Pass the user request to the skill. The skill handles the full autonomous pipeline.
+Pass the user request to the skill with GO_MODE=true. The skill handles all pipeline logic including the brainstorm phase.

commands/flow-code/run.md

@@ -1,11 +1,15 @@
 ---
-name: run
-description: Unified pipeline entry point for plan-first development
+name: flow-code:run
+description: "Internal pipeline entry point. Use /flow-code:go instead."
 ---
 
-# IMPORTANT: This command MUST invoke the skill flow-code-run
+# This command redirects to /flow-code:go
 
-The ONLY purpose of this command is to call the flow-code-run skill. You MUST use that skill now.
+`/flow-code:run` is now internal. The user-facing entry point is `/flow-code:go`.
+
+Tell the user: "Use `/flow-code:go` instead. It runs the full pipeline: brainstorm, plan, work, review, close."
+
+If the user provided arguments, invoke the flow-code-run skill directly:
 
 **User request:** $ARGUMENTS
 

docs/CODEBASE_MAP.md

@@ -241,8 +241,8 @@ sequenceDiagram
     User->>Interview: /flow-code:interview
     Interview->>flowctl: epic set-plan (refined spec)
 
-    Note over User,flowctl: Preferred: /flow-code:run fn-N (unified pipeline)
-    User->>Run: /flow-code:run "description"
+    Note over User,flowctl: Preferred: /flow-code:go fn-N (unified pipeline)
+    User->>Run: /flow-code:go "description"
     loop flowctl phase next/done
         Run->>flowctl: phase next --epic fn-N --json
         flowctl-->>Run: {phase, prompt, all_done}
@@ -272,13 +272,13 @@ sequenceDiagram
 
     alt status = plan
         ralph.sh->>Claude: prompt_plan.md (new process)
-        Claude->>Claude: /flow-code:run (plan phase)
+        Claude->>Claude: /flow-code:go (plan phase)
     else status = work
         ralph.sh->>Claude: prompt_work.md (new process)
-        Claude->>Claude: /flow-code:run (work phase)
+        Claude->>Claude: /flow-code:go (work phase)
     else status = completion_review
         ralph.sh->>Claude: prompt_completion.md (new process)
-        Claude->>Claude: /flow-code:run (close phase)
+        Claude->>Claude: /flow-code:go (close phase)
     end
 
     Claude-->>ralph.sh: exit (verdict in log)

docs/skills.md

@@ -8,8 +8,8 @@ These skills form the primary workflow. They ship with the plugin.
 
 | Skill | Command | Purpose | Location |
 |-------|---------|---------|----------|
-| `flow-code-go` | `/flow-code:go` | **Full autopilot** — brainstorm → plan → work → review → close → PR | `skills/` |
-| `flow-code-run` | `/flow-code:run` | Unified phase loop (plan → review → work → close) | `skills/` |
+| `flow-code-go` | `/flow-code:go` | **Full autopilot** — brainstorm → plan → work → review → close → PR (sole user-facing entry point) | `skills/` |
+| `flow-code-run` | Internal | Internal pipeline engine, invoked by `/flow-code:go` | `skills/` |
 | `flow-code-plan` | `/flow-code:plan` | Research codebase and create epic with tasks | `codex/skills/` |
 | `flow-code-work` | `/flow-code:work` | Execute tasks with re-anchoring, reviews, wave checkpoints | `codex/skills/` |
 | `flow-code` | `/flow-code` | Task/epic management entry point (list, create, status) | `skills/` |
@@ -82,7 +82,7 @@ Or for more control:
 2. `/flow-code:plan .flow/specs/<slug>-requirements.md` — research + create tasks
 3. `/flow-code:work fn-N` — execute tasks
 
-`/flow-code:run` handles plan → work → close (skips brainstorm).
+`/flow-code:go fn-N` resumes an existing epic (brainstorm auto-skipped).
 
 ## Tier Classification
 

docs/superpowers/specs/2026-04-08-flow-code-go-design.md

@@ -0,0 +1,131 @@
+# Design: `/flow-code:go` — Unified Entry Point with Brainstorm Phase
+
+## Problem
+
+Flow-Code's pipeline starts at Plan, but raw ideas need refinement before planning. `/flow-code:go` was documented as the full-autopilot entry point (brainstorm → plan → work → review → close) but never implemented. Meanwhile `/flow-code:run` serves as the primary user-facing command — this creates confusion.
+
+## Solution
+
+1. Add `Brainstorm` as the first phase in flowctl's pipeline state machine
+2. Make `/flow-code:go` the sole user-facing entry point
+3. Demote `/flow-code:run` to an internal skill
+
+## Architecture
+
+### State Machine (flowctl-core)
+
+```
+Brainstorm → Plan → PlanReview → Work → ImplReview → Close
+```
+
+All epics initialize at `Brainstorm`. The phase is either executed (new idea) or skipped (existing flow ID / spec file).
+
+### Phase Behavior
+
+| Input Type | Brainstorm Phase |
+|------------|-----------------|
+| Natural language idea | Execute: auto brainstorm (AI self-interview → requirements doc) |
+| Flow ID (`fn-N`) | Skip: `flowctl phase done --phase brainstorm` |
+| Spec file path | Skip: `flowctl phase done --phase brainstorm` |
+| `--plan-only` | Skip brainstorm, stop after Plan |
+
+### Command & Skill Mapping
+
+| Layer | File | Change |
+|-------|------|--------|
+| Command (user-facing) | `commands/flow-code/go.md` | New — routes to `flow-code-run` skill |
+| Command (removed) | `commands/flow-code/run.md` | Delete or redirect to `go` |
+| Skill | `skills/flow-code-run/SKILL.md` | Add brainstorm phase handling, set `user-invocable: false` |
+| Skill trigger | skill frontmatter | Update trigger list: `/flow-code:go` replaces `/flow-code:run` |
+
+## Rust Changes
+
+### `flowctl-core/src/pipeline.rs`
+
+```rust
+pub enum PipelinePhase {
+    Brainstorm,  // NEW
+    Plan,
+    PlanReview,
+    Work,
+    ImplReview,
+    Close,
+}
+```
+
+- `ALL_PHASES`: 6 elements, `Brainstorm` first
+- `Brainstorm.next()` → `Some(Plan)`
+- `Brainstorm.as_str()` → `"brainstorm"`
+- `Brainstorm.prompt_template()` → `"Explore and pressure-test the idea before planning"`
+- `Brainstorm.is_terminal()` → `false`
+- `PipelinePhase::parse("brainstorm")` → `Some(Brainstorm)`
+
+### `flowctl-cli/src/commands/workflow/pipeline_phase.rs`
+
+- `get_or_init_phase`: default init changes from `Plan` to `Brainstorm`
+
+### Tests
+
+- `test_phase_sequence`: starts from `Brainstorm`, expected array gains `Plan` at front
+- `test_all_phases`: `len()` assertion 5 → 6
+- `test_serde_roundtrip`: auto-covered
+- `test_display`: add `Brainstorm` case
+- `test_parse_roundtrip`: auto-covered
+- `test_invalid_transition_rejection`: update examples if needed
+
+## Skill Changes
+
+### `skills/flow-code-run/SKILL.md`
+
+Phase loop gains brainstorm handling:
+
+```
+when phase == "brainstorm":
+  if input is natural language (not flow ID, not spec file):
+    1. Gather codebase context (grep, git log, existing specs)
+    2. Classify complexity (trivial/medium/large)
+    3. Self-interview: 6-10 Q&A pairs grounded in code evidence
+    4. Generate 2-3 approaches, auto-select best
+    5. Write requirements doc to .flow/specs/<slug>-requirements.md
+    6. flowctl phase done --phase brainstorm
+  else:
+    flowctl phase done --phase brainstorm (skip)
+```
+
+The brainstorm logic is inlined from the existing `flow-code-brainstorm` SKILL.md auto mode — not delegated via skill invocation.
+
+### `commands/flow-code/go.md`
+
+```yaml
+---
+name: go
+description: "Full autopilot: brainstorm → plan → work → review → close"
+---
+# IMPORTANT: This command MUST invoke the skill flow-code-run
+Pass $ARGUMENTS to the skill with GO_MODE=true.
+```
+
+### Flags (inherited from current `/flow-code:run`)
+
+| Flag | Effect |
+|------|--------|
+| `--plan-only` | Skip brainstorm, stop after Plan |
+| `--no-pr` | Skip PR creation at close |
+| `--tdd` | Force test-first in worker |
+| `--review=rp\|codex\|none` | Override review backend |
+
+## Documentation Updates
+
+| File | Change |
+|------|--------|
+| `CLAUDE.md` | Pipeline sequence: add Brainstorm. Entry points: `/flow-code:go` replaces `/flow-code:run` |
+| `docs/skills.md` | Core Skills: replace `flow-code-run` with `flow-code-go`. Mark `flow-code-run` internal |
+| `docs/flowctl.md` | Phase command docs: add `brainstorm` phase |
+| `README.md` | Update pipeline diagram and usage examples |
+| `README_CN.md` | Same as README.md |
+
+## Non-Goals
+
+- Interactive brainstorm mode (always auto, zero human input)
+- Separate `flow-code-go` skill directory (reuses `flow-code-run`)
+- Backward compatibility with old `.flow/` state files