diff --git a/CLAUDE.md b/CLAUDE.md index 3e370627..69f24821 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ hooks/hooks.json → Ralph workflow guards (active when FLOW_RALPH=1) docs/ → Architecture docs, CI examples ``` -**Skills**: 9 core + 22 extensions. See `docs/skills.md` for the full classification. Core workflow: `flow-code-run` (unified phase loop). Legacy individual skills (plan, plan-review, work, impl-review, epic-review) are deprecated but still functional as thin redirects. +**Skills**: See `docs/skills.md` for the full classification. Core workflow: `flow-code-run` (unified phase loop via `flowctl phase next/done`). **Key invariant**: The `bin/flowctl` Rust binary is the single source of truth for `.flow/` state. Always invoke as: ```bash @@ -28,14 +28,7 @@ $FLOWCTL ## Primary Workflow -**Unified entry point** (preferred): `/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. - -Individual phase commands (deprecated, still functional): -1. `/flow-code:plan "description"` → creates epic + tasks in `.flow/` -2. `/flow-code:plan-review` → Carmack-level review via RepoPrompt or Codex -3. `/flow-code:work ` → executes tasks with Teams mode (auto-parallel with file locking) -4. `/flow-code:impl-review` → post-implementation review -5. `/flow-code:epic-review` → final review before closing +`/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. Ralph (`/flow-code:ralph-init`) is the autonomous harness that runs this loop unattended. diff --git a/agents/worker.md b/agents/worker.md index 21698d58..7a0ffa87 100644 --- a/agents/worker.md +++ b/agents/worker.md @@ -1,6 +1,6 @@ --- name: worker -description: Task implementation worker. Spawned by flow-code-work to implement a single task with fresh context. Do not invoke directly - use /flow-code:work instead. +description: Task implementation worker. Spawned by flow-code-run during the work phase. Do not invoke directly - use /flow-code:run instead. model: inherit disallowedTools: Task color: "#3B82F6" diff --git a/docs/CODEBASE_MAP.md b/docs/CODEBASE_MAP.md index 32639b7c..95ebb13f 100644 --- a/docs/CODEBASE_MAP.md +++ b/docs/CODEBASE_MAP.md @@ -110,13 +110,9 @@ flow-code/ │ ├── setup.md, sync.md, uninstall.md ├── skills/ # 18 skill implementations │ ├── flow-code/ # Task CRUD via flowctl -│ ├── flow-code-plan/ # SKILL.md + steps.md + examples.md -│ ├── flow-code-work/ # SKILL.md + phases.md +│ ├── flow-code-run/ # Unified pipeline entry point (phase loop) │ ├── flow-code-interview/ # SKILL.md + questions.md │ ├── flow-code-prime/ # SKILL.md + workflow.md + pillars.md + remediation.md -│ ├── flow-code-impl-review/ # SKILL.md + workflow.md + flowctl-reference.md -│ ├── flow-code-plan-review/ # SKILL.md + workflow.md + flowctl-reference.md -│ ├── flow-code-epic-review/ # SKILL.md + workflow.md + flowctl-reference.md │ ├── flow-code-ralph-init/ # SKILL.md + templates/ (ralph.sh, config.env, prompts) │ ├── flow-code-auto-improve/ # SKILL.md + templates/ (auto-improve.sh, programs/) │ ├── flow-code-map/ # SKILL.md + scripts/scan-codebase.py @@ -246,24 +242,21 @@ sequenceDiagram Interview->>flowctl: epic set-plan (refined spec) Note over User,flowctl: Preferred: /flow-code:run fn-N (unified pipeline) - Note over User,flowctl: Legacy individual commands (deprecated, still functional): - User->>Plan: /flow-code:plan fn-N - Plan->>Scouts: 7 scouts in parallel - Scouts-->>Plan: patterns, docs, gaps, deps - Plan->>flowctl: epic create + task create (with deps) - - User->>Work: /flow-code:work fn-N - loop Each ready task - Work->>flowctl: start task - Work->>Worker: spawn (fresh context) - Worker->>flowctl: show + cat (re-anchor) - Worker->>Worker: implement + test + commit - Worker->>Review: impl-review (if enabled) - Review-->>Worker: SHIP / NEEDS_WORK (fix loop) - Worker->>flowctl: done (summary + evidence) + User->>Run: /flow-code:run "description" + loop flowctl phase next/done + Run->>flowctl: phase next --epic fn-N --json + flowctl-->>Run: {phase, prompt, all_done} + alt phase = plan + Run->>Scouts: research scouts in parallel + Scouts-->>Run: patterns, docs, gaps + Run->>flowctl: epic plan + task create + else phase = work + Run->>Worker: spawn workers (Teams + worktree) + Worker->>flowctl: worker-phase next/done loop + Worker->>flowctl: done (summary + evidence) + end + Run->>flowctl: phase done --epic fn-N --phase X end - Work->>Review: epic-review (completion gate) - Review-->>Work: SHIP ``` ### Ralph Autonomous Loop @@ -279,13 +272,13 @@ sequenceDiagram alt status = plan ralph.sh->>Claude: prompt_plan.md (new process) - Claude->>Claude: /flow-code:plan-review (deprecated, handled by run pipeline) + Claude->>Claude: /flow-code:run (plan phase) else status = work ralph.sh->>Claude: prompt_work.md (new process) - Claude->>Claude: /flow-code:work + impl-review (deprecated, handled by run pipeline) + Claude->>Claude: /flow-code:run (work phase) else status = completion_review ralph.sh->>Claude: prompt_completion.md (new process) - Claude->>Claude: /flow-code:epic-review (deprecated, handled by run pipeline) + Claude->>Claude: /flow-code:run (close phase) end Claude-->>ralph.sh: exit (verdict in log) @@ -342,9 +335,9 @@ sequenceDiagram **To add a new command**: Create `commands/flow-code/.md` (thin stub) + `skills/flow-code-/SKILL.md` **To add a new agent**: Create `agents/.md` with frontmatter (name, description, model, disallowedTools) -**To add a new scout to planning**: Add to the parallel scout list in `skills/flow-code-plan/steps.md` Step 1 +**To add a new scout to planning**: Add to the scout dispatch in `skills/flow-code-run/SKILL.md` plan phase **To add a new prime pillar**: Add criteria to `skills/flow-code-prime/pillars.md`, remediation to `remediation.md` **To modify Ralph loop**: Edit `skills/flow-code-ralph-init/templates/ralph.sh` (canonical source) **To modify auto-improve loop**: Edit `skills/flow-code-auto-improve/templates/auto-improve.sh` -**To add a review backend**: Add to impl-review, plan-review, and epic-review workflow.md files -**To change task state machine**: Modify `scripts/flowctl/commands/workflow.py` (state transitions) or `scripts/flowctl/core/state.py` (state storage) +**To add a review backend**: Add to `flowctl review-backend` and the review phase in `skills/flow-code-run/SKILL.md` +**To change task state machine**: Modify `flowctl/crates/flowctl-core/src/state_machine.rs` diff --git a/docs/skills.md b/docs/skills.md index 4df7b2b3..0aa538cb 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -2,19 +2,14 @@ Skills are organized into **core** (essential workflow) and **extensions** (optional capabilities). -## Core Skills (9) +## Core Skills (4) -These skills form the primary plan-execute-review workflow. They ship with the plugin. +These skills form the primary workflow. They ship with the plugin. | Skill | Command | Purpose | |-------|---------|---------| | `flow-code-run` | `/flow-code:run` | **Primary entry point** — unified phase loop (plan → review → work → close) | | `flow-code` | `/flow-code` | Task/epic management entry point (list, create, status) | -| `flow-code-plan` | `/flow-code:plan` | Create structured build plans (deprecated — use `run`) | -| `flow-code-work` | `/flow-code:work` | Execute plans with Teams mode (deprecated — use `run`) | -| `flow-code-plan-review` | `/flow-code:plan-review` | Carmack-level plan review (deprecated — use `run`) | -| `flow-code-impl-review` | `/flow-code:impl-review` | Post-implementation code review (deprecated — use `run`) | -| `flow-code-epic-review` | `/flow-code:epic-review` | Final review before closing (deprecated — use `run`) | | `flow-code-setup` | `/flow-code:setup` | Install flowctl CLI and configure project | | `flow-code-map` | `/flow-code:map` | Generate codebase architecture maps | @@ -67,5 +62,4 @@ For a new project: 2. `/flow-code:prime` — assess codebase readiness 3. `/flow-code:run "description"` — plan, review, execute, and close (all-in-one) -Legacy individual commands (deprecated, still functional): -3a. `/flow-code:plan "description"` → 4. `/flow-code:plan-review` → 5. `/flow-code:work ` → 6. `/flow-code:impl-review` → 7. `/flow-code:epic-review` +That's it — `/flow-code:run` handles the full plan → review → work → review → close pipeline.