fix(pipeline): close 3 doc/code gaps — GO_MODE, dual-phase clarity, Phase 3 PhaseDef (v0.1.37)

1. GO_MODE: remove phantom flag from go.md, document actual input-type
   detection behavior (natural language / Flow ID / spec file / --plan-only)
2. Dual-phase system: add explicit table in flow-code-run and worker.md
   distinguishing epic-level (6 phases) vs worker-level (12 phases)
3. Phase 3 PhaseDef: add missing Investigation phase definition to
   PHASE_DEFS so `flowctl worker-phase next` returns instructions for
   Phase 3 — consistent with all other phases instead of inline-only
4. Update work section to reference all domain skills, not just frontend

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

Author: z23cc

agents/worker.md

@@ -12,7 +12,9 @@ effort: high
 <!-- section:core -->
 # Task Implementation Worker
 
-You implement a single flow-code task. Your prompt contains configuration values - use them exactly as provided.
+You implement a single flow-code task within the epic's "work" phase. You operate at the **worker-level** (12 phases via `flowctl worker-phase next/done`), which is independent from the **epic-level** phases (brainstorm→plan→work→review→close via `flowctl phase next/done`). Multiple workers run their phases in parallel — one per task.
+
+Your prompt contains configuration values - use them exactly as provided.
 
 **Configuration from prompt:**
 - `TASK_ID` - the task to implement (e.g., fn-1.2)

bin/flowctl

@@ -10,4 +10,8 @@ The ONLY purpose of this command is to call the flow-code-run skill. You MUST us
 
 **User request:** $ARGUMENTS
 
-Pass the user request to the skill with GO_MODE=true. The skill handles all pipeline logic including the brainstorm phase.
+Pass the user request to the skill. The skill auto-detects mode from input type:
+- Natural language → full pipeline (brainstorm → plan → work → review → close)
+- Flow ID (fn-N-*) → resume existing epic from current phase
+- Spec file path → plan from spec (skip brainstorm)
+- `--plan-only` → stop after planning

commands/flow-code/go.md

@@ -1,6 +1,6 @@
 [package]
 name = "flowctl-cli"
-version = "0.1.36"
+version = "0.1.37"
 description = "CLI entry point for flowctl"
 edition.workspace = true
 rust-version.workspace = true

flowctl/crates/flowctl-cli/Cargo.toml

@@ -64,6 +64,7 @@ struct PhaseDef {
 const PHASE_DEFS: &[PhaseDef] = &[
     PhaseDef { id: "1",   title: "Verify Configuration",  done_condition: "OWNED_FILES verified and configuration validated",            instructions: "Validate OWNED_FILES list and confirm task configuration matches the epic spec." },
     PhaseDef { id: "2",   title: "Re-anchor",             done_condition: "Run flowctl show <task> and verify spec was read",            instructions: "Read the task spec via flowctl show and re-anchor on acceptance criteria before coding." },
+    PhaseDef { id: "3",   title: "Investigation",         done_condition: "Target files read and related patterns identified",           instructions: "Read investigation targets from the task spec. If targets exist, follow them. If not, do a lightweight scan: read files listed in **Files:** and grep for 2-3 related patterns. If RP_CONTEXT is available, use context_builder for deep context. Skip only for trivial one-line config changes." },
     PhaseDef { id: "4",   title: "TDD Red-Green",         done_condition: "Failing tests written and confirmed to fail",                 instructions: "Write failing tests that encode the acceptance criteria, then confirm they fail." },
     PhaseDef { id: "5",   title: "Implement",             done_condition: "Feature implemented and code compiles",                       instructions: "Implement the feature to satisfy the spec and ensure the code compiles cleanly." },
     PhaseDef { id: "6",   title: "Verify & Fix",          done_condition: "flowctl guard passes and diff reviewed",                      instructions: "Run flowctl guard (lint, type-check, tests) and review the diff for correctness." },

flowctl/crates/flowctl-cli/src/commands/workflow/phase.rs

@@ -26,6 +26,17 @@ Accepts:
 - Flow epic ID: fn-1-add-oauth (resume existing epic)
 - --plan-only flag to stop after planning
 
+## Two-Level Phase System
+
+This plugin has TWO independent phase systems operating at different levels:
+
+| Level | Phases | Managed by | Scope |
+|-------|--------|-----------|-------|
+| **Epic-level** | brainstorm → plan → plan_review → work → impl_review → close (6 phases) | `flowctl phase next/done` | One epic's lifecycle |
+| **Worker-level** | 1→2→3→5→6→7→10→12 (up to 12 phases, varies by size/flags) | `flowctl worker-phase next/done` | One task within the Work epic-phase |
+
+Epic phases are sequential. Worker phases run INSIDE the epic "work" phase — multiple workers execute their 12 phases in parallel (one per task).
+
 ## Phase Loop
 
 Claude is the outer loop; flowctl provides phase content.
@@ -86,7 +97,7 @@ Detect input type to decide whether to execute or skip:
 3. Lock files: `$FLOWCTL lock --task <task-id> --files "file1,file2" --json`
 4. Spawn ALL ready workers in ONE parallel Agent call with isolation worktree and team_name
    - Include task domain in worker prompt (from task JSON `domain` field)
-   - Frontend-domain tasks: worker auto-loads `flow-code-frontend-ui` skill
+   - Workers auto-load domain-specific skills (frontend→UI engineering, backend→API design, etc.)
 5. Wait for workers, merge worktree branches back
 6. Mark tasks complete: `$FLOWCTL done <task-id> --summary "what was done" --json`
 7. Wave checkpoint: verify done, run guards