benkruger/flow-code

FLOW Code — Phase 2: Code

Usage

/flow:flow-code
/flow:flow-code --continue-step

• /flow:flow-code — uses the configured mode from the state file's skills.flow-code config
• /flow:flow-code --continue-step — self-invocation: skip Announce and Update State, dispatch to the next task via Resume Check

<HARD-GATE> Run `phase-enter` as your very first action. If it returns an error, stop immediately and show the error to the user.

${CLAUDE_PLUGIN_ROOT}/bin/flow phase-enter --phase flow-code

Parse the JSON output. If "status": "error", STOP and show the error.

If "status": "ok", capture the returned fields: project_root, branch, worktree_path, worktree_cwd, relative_cwd, pr_number, pr_url, feature, slack_thread_ts, and plan_file. The autonomy mode is resolved separately in the Mode Resolution section below via resolve-skill-mode.

</HARD-GATE>

Use the returned fields for all downstream references. Do not re-read the state file or re-run git commands to gather the same information. Do not cd to the project root — bin/flow commands find paths internally.

Re-anchor cwd

Mono-repo flows started inside a subdirectory (e.g. api/) capture that path as relative_cwd and rely on cwd staying at <worktree>/<relative_cwd> so subsequent bin/flow calls pass the cwd-drift guard. Context loss between skill invocations can reset cwd to the main repo root; the bash block below re-anchors regardless of how the session got here. Substitute the worktree_cwd value from the phase-enter response — a no-op for root-level flows (where it equals worktree_path) and a real re-anchor for mono-repo flows.

cd "<worktree_cwd>"

Concurrency

This flow is one of potentially many running simultaneously — on this machine (multiple worktrees) and across machines (multiple engineers). Your state file (.flow-states/<branch>/state.json) is yours alone. Never read or write another branch's state. All local artifacts (logs, plan files, temp files) are scoped by branch name. GitHub state (PRs, issues, labels) is shared across all engineers — operations that create or modify shared state must be idempotent.

Mode Resolution

Resolve commit and continue on every entry — fresh invocation and --continue-step self-invocation alike — from the state file's skills.flow-code config via resolve-skill-mode. The state file is the single source of truth for skill autonomy; there are no --auto/--manual flags.

On a --continue-step self-invocation, recover the worktree directory before resolving the branch. The resume path skips phase-enter (which normally cds into the worktree), and the branch resolution just below is cwd-dependent — so a session whose cwd reset to the main-repo root would otherwise resolve the integration branch instead of the feature branch. bin/flow resume-anchor reads the session-keyed phase-anchor marker and returns the recovered worktree_cwd:

${CLAUDE_PLUGIN_ROOT}/bin/flow resume-anchor

Parse the JSON output and branch on status:

• "ok" — cd into the returned worktree_cwd, then resolve the branch below from the recovered directory.
• "no_marker" — no marker to recover; proceed with the cwd-based branch detection below as-is.
• "error" — the marker was corrupt; do NOT cd to any returned path. Treat it exactly like no_marker and proceed with the cwd-based detection below.

Resolve the current branch first: run git worktree list --porcelain, note the project root (the path on the first worktree line), find the worktree entry whose path matches the current working directory, and take the branch refs/heads/<name> line from that entry (strip the refs/heads/ prefix). Call this <branch>. Then run the resolver:

${CLAUDE_PLUGIN_ROOT}/bin/flow resolve-skill-mode --skill flow-code --branch <branch>

Parse the JSON output. commit and continue are each "auto" or "manual":

• commit=auto — streamline mode active from task 1 (skip per-task approval, still show diffs).
• commit=manual — require explicit approval for each task.
• continue=auto — auto-advance to Review once all tasks are committed.
• continue=manual — prompt before advancing to Review.

Self-Invocation Check

If --continue-step was passed, this is a self-invocation from a previous task's commit. Skip the Announce banner and the phase-enter call (do not enter the phase again). Run ## Mode Resolution above (it runs on every entry), then proceed directly to the Resume Check section.

Announce

At the very start, output the following banner in your response (not via Bash) inside a fenced code block:

```text
──────────────────────────────────────────────────
  FLOW v2.6.1 — Phase 2: Code — STARTING
──────────────────────────────────────────────────
```

Project Conventions

Read the project's CLAUDE.md for project-specific conventions. Each project owns its own toolchain via bin/{format,lint,build,test} and documents its conventions in CLAUDE.md. Follow those conventions for:

• Architecture checks — what to read before writing code
• Test patterns — existing fixtures, helpers, and test conventions
• Targeted test command — how to run a single test file (typically bin/test --file <path>)
• CI failure fix order — how to diagnose and fix CI failures
• Hard rules — project-specific constraints

Logging

After every Bash command completes, log it to .flow-states/<branch>/log using bin/flow log.

Run the command first, then log the result. Pipeline the log call with the next command where possible (run both in parallel in one response).

${CLAUDE_PLUGIN_ROOT}/bin/flow log <branch> "[Phase 2] Step X — desc (exit EC)"

Get <branch> from the state file.

---

Resume Check

Read files.plan from the state file to get the plan file path. Use the Read tool to read the plan file at <project_root>/<files.plan path> — the .flow-states/ tree lives at the project root, not inside the worktree, so the <project_root>/ prefix is required (a raw relative read resolves under the worktree and the validate-worktree-paths hook blocks it). Identify the Tasks section — this is the ordered list of implementation tasks to execute.

Read code_task from the state file (default 0 if absent).

• If code_task > 0 and code_task < total tasks: skip to task code_task + 1. Output in your response (not via Bash) inside a fenced code block:

```text
──────────────────────────────────────────────────
  FLOW — Resuming Code
──────────────────────────────────────────────────
  Resuming at: <task description>
  Tasks complete: <code_task> of <total>
──────────────────────────────────────────────────
```

• If code_task >= total tasks: skip to All Tasks Complete.

• If code_task is 0 and this is a resume (re-entering the phase after a session restart), determine progress by comparing the plan to committed work.

Resolve the integration branch. Run the bin/flow base-branch command shown below (it uses the plugin root prefix) to retrieve the base branch the flow coordinates against. Capture its stdout — call the value <base_branch> — and substitute it into the git log command below. A repo whose default branch is staging produces <base_branch> = staging; a standard repo produces <base_branch> = main.

${CLAUDE_PLUGIN_ROOT}/bin/flow base-branch

Get the commit log. Substitute <base_branch> with the value you just captured.

git log --oneline origin/<base_branch>..HEAD

Compare commit messages to the tasks in the plan file. Continue from the first task that doesn't have a matching commit.

---

Execute Next Task

From the plan file, identify the next task to work on (task number code_task + 1). Execute only this single task — do not look ahead to subsequent tasks. After committing, self-invoke to handle the next task in a fresh skill invocation.

Atomic Task Group

When the plan marks a set of tasks as an atomic group (typically because they form a circular CI dependency — no intermediate state can pass bin/flow ci independently), handle them as a single commit boundary.

Detect the group. When you reach a task that the plan marks as part of an atomic group, switch to the atomic flow below instead of the standard single-task flow. The plan will annotate which tasks belong to the group and explain why they cannot be committed individually (e.g., "Tasks 3-6 form an atomic group — adding a CI check requires fixing violations in the same commit").

Show a group banner. Output in your response (not via Bash):

```text
  ── Atomic Group: Tasks <first>-<last> of <total> ──
  Reason: <why these tasks cannot pass CI independently>
```

Execute all tasks in the group sequentially. Run the full TDD cycle (write failing test, implement, refactor, run targeted tests) and the Architecture Check independently. After completing each task's TDD cycle, record it and persist the task name for TUI display. Both updates can go in a single call:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set code_task=<n> --set code_task_name="<description>"

For atomic groups with multiple tasks, batch all counter advances in one call. apply_updates processes --set arguments sequentially against mutating in-memory state, so each +1 step is validated in order. Example for tasks 3-5:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set code_task=3 --set code_task=4 --set code_task=5 --set code_task_name="<description>"

Do NOT run bin/flow ci and do NOT commit after intermediate tasks. Proceed directly to the next task in the group.

Combined review after the last task. Show the combined diff covering all tasks in the group. Run git status and git diff HEAD as two separate commands, then render the output inline following the same format as the ### Review section. If commit=auto, skip the AskUserQuestion and proceed to Plan Test Verification. Otherwise, ask for review of the combined diff.

CI gate routes through /flow:flow-commit. As with single-task commits, the group's CI gate runs inside finalize-commit (ci::run_impl() Rust call). A failed internal CI returns the error to the model, which fixes and retries. Do NOT invoke bin/flow ci directly between tasks in the group — Layer 11 of validate-pretool blocks it.

Plan Test Verification. Run the Plan Test Verification check (see the section below) for ALL tasks in the group — not just the last one. Verify that every test function named in any task's plan description exists in the codebase.

Single commit. Use the standard Commit section flow: set the continuation context and _continue_pending, then invoke /flow:flow-commit. The commit message should reference the group:

Add <what the group accomplished> — Tasks <first>-<last> of <total>

Self-invoke as usual after the group commit to continue with the next task after the group.

Measurement-Only Tasks

Some plan tasks produce no file changes — a final coverage TOTAL capture for the PR body, a threshold verification re-run, or a final regression re-run that the plan explicitly names as a task. These tasks still route through the standard Commit flow below so every task honors CLAUDE.md's "All commits via /flow:flow-commit" convention and never invents a shortcut.

Skip the TDD Cycle (there is no test or implementation to write for a task that produces no file changes) and perform the task's measurement action as the task body — for example, bin/flow log to record a TOTAL into the session log. Do NOT invoke bin/flow ci directly: Layer 11 of validate-pretool blocks it during Code phase (the --clean carve-out is the only allowed form). Then follow the Commit section exactly as a file-changing task would: advance code_task via set-timestamp, set _continue_context and _continue_pending=commit, and invoke /flow:flow-commit. The commit skill stages all changes via git add -A in Round 3, then runs git diff --cached in Round 4; when the staged diff is empty it prints "Nothing to commit", prints its COMPLETE banner, and returns to the caller without calling finalize-commit. The self-invocation at the end of the Commit section then fires unchanged — it runs after /flow:flow-commit returns, independent of whether a commit was actually produced. Do not skip /flow:flow-commit even when you already know the diff will be empty.

Discovery output handling

Some discovery commands during Code phase produce output longer than the Bash tool's display buffer can return inline. bin/flow ci --lint after a wide ignore-list removal can emit ~50 violation lines; a plain git grep over a deletion target can return hundreds of matches. When the buffer is exceeded the tool truncates the middle, so any violation enumeration based on the inline output silently misses entries. Bash redirection to a temp file would be the natural workaround, but validate-pretool Layer 2 blocks bare > redirects under the FLOW permission model, so the discipline below uses existing artifacts and dedicated tools instead.

Apply this when a discovery command's output is enumerable (lint violations, grep hits, file lists) AND the rough output size could exceed a screen of text. Skip it for short queries (one-line counts, single-file reads) where inline output is sufficient.

For bin/flow ci and its single-phase variants (--format, --lint, --build, --test): the runner already writes the full unabridged stdout-plus-stderr stream to a log file. The path appears in the runner's footer (Full log: …-ci-last.log) and is also predictable: <project_root>/.flow-states/<branch>-ci-last.log. Use the Read tool on that path to see every violation line — the Read tool is unaffected by the Bash tool's display-buffer cap.

For grep-style enumeration (line-by-line file searches): use the Grep tool directly. Grep returns matches in a structured form that bypasses the Bash display buffer; pass output_mode: "content" with -n for line-numbered hits, or output_mode: "files_with_matches" when only the file list matters.

For arbitrary commands without a built-in log file: the FLOW permission model does not allow ad-hoc shell redirection to /tmp/, so enumeration must come from a tool that returns structured output. Glob and Grep cover most cases; for richer output, prefer running the command in narrower passes (e.g., one directory at a time) so each pass fits inline.

Before Starting a Task

Persist the task name to the state file for TUI display:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set code_task_name="<description>"

Output in your response (not via Bash) inside a fenced code block:

```text
  ── Task <n> of <total> ───────────────────────
  <description>
  Files: <files>
```

Architecture Check

Follow the Architecture Check from the project CLAUDE.md. Check based on task type as described there before writing any code.

---

TDD Cycle

For every implementation task, there is a paired test task that runs first.

Step A — Write the failing test

Write the test file. Follow the test task description exactly.

Run the Targeted Test Command from the project CLAUDE.md to confirm it fails.

The test MUST fail before proceeding. If it passes immediately, the test is not testing the right thing — rewrite it until it fails for the right reason.

Step B — Write minimal implementation

Write only what is needed to make the test pass. No over-engineering.

Run the Targeted Test Command again to confirm it passes.

Step C — Refactor

Clean up without changing behaviour. Run the test again to confirm it still passes.

---

Review

After the TDD cycle passes, show the diff for this task and ask for review before committing.

Run git status and git diff HEAD as two separate commands, then render the output inline:

Status

modified:   <path/to/implementation_file>
new file:   <path/to/test_file>

Diff

+ added lines
- removed lines

If commit=auto, streamline is active from task 1 — skip the AskUserQuestion and proceed directly to Plan Test Verification.

If streamline mode is active (opted in during a previous task), skip the AskUserQuestion and proceed directly to Plan Test Verification.

Otherwise, use AskUserQuestion:

"Task <n>: <description> — does this look right?"

• Yes, commit
• Needs changes — describe what to fix
• Streamline remaining tasks — (only shown from the second task onward)

If "Needs changes" — fix the issue, re-run the test, show the diff again. Loop until approved.

If "Streamline remaining tasks" — set a session-only flag (not persisted to state). For all remaining tasks, still show the diff for user visibility, but skip the AskUserQuestion and proceed directly to Plan Test Verification and commit.

---

CI gate routes through /flow:flow-commit

The per-task CI gate runs inside /flow:flow-commit's finalize-commit call as a Rust function (ci::run_impl()), not as a separate Bash invocation. Each TDD task's per-file test verifies the file under change; cross-file regressions are caught when the commit's internal CI runs. A failed internal CI returns the error to the model, which fixes and retries. Do NOT invoke bin/flow ci directly during Code phase — Layer 11 of validate-pretool blocks it per .claude/rules/per-file-coverage-iteration.md "Enforcement".

The --clean carve-out is available when phantom-misses symptoms appear (see the rule). Reach for it only when the diagnostic signals match.

---

Plan Test Verification

The plan decomposes work into specific test functions. This step verifies that every test the plan promised was actually written during the TDD cycle — CI proves tests pass, but cannot prove missing tests exist.

After CI passes and before committing, verify that every test function the plan explicitly names for this task exists in the codebase.

Re-read the current task's description from the plan file. Look for explicitly named test functions. These appear as comma-separated lists, under headings like "Rust tests:" or "Tests:", or inline in the task description. Test naming conventions vary by language:

• Rust — test_ prefix (e.g., test_parser_handles_empty_input)
• Python — test_ prefix (e.g., test_login_timeout)
• Go — Test prefix with capital T (e.g., TestParseConfig)
• Swift — test prefix in camelCase (e.g., testLoginTimeout)
• Ruby — test_ prefix for minitest; it or describe blocks for RSpec

If the task description names specific test functions, use the Grep tool to verify each one exists as a function or method definition in the codebase. Match the language convention: fn <name> for Rust, def <name> for Python/Ruby, func <name> for Go/Swift.

• If all named tests are found → proceed to Commit
• If the task does not name specific test functions → proceed to Commit
• If any named test is missing → list the missing tests, write them, re-run CI, and only proceed to Commit once all named tests exist and CI is green

---

Commit

Record the completed task number:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set code_task=<n>

Set the continuation context and flag before committing. The self-invocation carries no mode flag — the resumed run re-resolves commit/continue from the state file via ## Mode Resolution:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set "_continue_context=Self-invoke flow:flow-code --continue-step."

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set _continue_pending=commit

Invoke /flow:flow-commit.

The commit message subject should reference the task:

Add <what was built> — Task <n> of <total>

To continue to the next task, invoke flow:flow-code --continue-step using the Skill tool as your final action. Do not output anything else after this invocation.

---

All Tasks Complete

Once every task from the plan file is complete, proceed directly to the Done section below.

Every commit during Code phase routed through /flow:flow-commit → finalize-commit, which runs the full CI gate (ci::run_impl()) and enforces the 100/100/100 coverage threshold before the commit lands. The last task's commit verified the same invariants the final sweep would have measured, so no explicit bin/flow ci is needed before transitioning to Review. Layer 11 of validate-pretool blocks bin/flow ci during Code phase to protect against the single-file-iteration misuse pattern; the per-task per-file gate (bin/test tests/<name>.rs) plus the commit-time internal CI cover the same surface at lower cost.

<HARD-GATE> Do NOT transition to Review until every plan task is committed. 100% coverage is enforced by each commit's internal CI gate; post-commit re-verification is not required. </HARD-GATE>

Done — Update state and complete phase

Finalize the phase (complete + Slack notification in one call):

${CLAUDE_PLUGIN_ROOT}/bin/flow phase-finalize --phase flow-code --branch <branch> --thread-ts <slack_thread_ts>

Omit --thread-ts if slack_thread_ts was not returned by phase-enter.

Parse the JSON output. If "status": "error", report the error and stop. Use the formatted_time field in the COMPLETE banner below. Do not print the timing calculation.

Output in your response (not via Bash) inside a fenced code block:

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v2.6.1 — Phase 2: Code — COMPLETE (<formatted_time>)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

<HARD-GATE> STOP. Parse `continue_action` from the `phase-finalize` output above to determine how to advance.

1. Use continue_action from the phase-finalize output — phase-finalize computes it from the state file's skills.flow-code.continue config. If continue_action is "invoke" → continue=auto. If continue_action is "ask" → continue=manual.

2. If continue=auto → invoke flow:flow-review directly using the Skill tool. Do NOT run bin/flow status. Do NOT use AskUserQuestion. This is the FINAL action in this response — nothing else follows.

3. If continue=manual → you MUST do all of the following before proceeding: a. Run bin/flow status via Bash and print its stdout in your response inside a fenced code block:

   ${CLAUDE_PLUGIN_ROOT}/bin/flow status
   

   b. Use AskUserQuestion: "Phase 2: Code is complete. Ready to begin Phase 3: Review?" Options: "Yes, start Phase 3 now", "Not yet", "I have a correction or learning to capture" c. If "I have a correction or learning to capture": ask what to capture, invoke /flow:flow-note, then re-ask with only "Yes, start Phase 3 now" and "Not yet" d. If Yes → invoke flow:flow-review using the Skill tool e. If Not yet → print the paused banner below f. Do NOT invoke flow:flow-review until the user responds

Do NOT skip this check. Do NOT auto-advance when the mode is manual.

</HARD-GATE>

If Not yet, output in your response (not via Bash) inside a fenced code block:

```text
══════════════════════════════════════════════════
  ◆ FLOW — Paused
  Run /flow:flow-review when ready.
══════════════════════════════════════════════════
```

---

Hard Rules

• Never skip the TDD cycle — test must fail before code is written
• Always show the diff for every task — when commit=manual, the first task requires explicit approval; when commit=auto, streamline is active from task 1
• Never invoke bin/flow ci directly during Code phase — Layer 11 of validate-pretool blocks it. The per-task targeted test command (see the project CLAUDE.md) plus /flow:flow-commit's internal ci::run_impl() cover the same surface. The --clean carve-out is for the documented phantom-misses recovery path only.
• Never move to the next task until the current task is committed
• Never rebase — always merge
• Plus the Project-Specific Hard Rules from the project CLAUDE.md
• Never use Bash to print banners — output them as text in your response
• Never use Bash for file reads — use Glob, Read, and Grep tools instead of ls, cat, head, tail, find, or grep
• Never use cd <path> && git — use git -C <path> for git commands in other directories
• Never cd before running bin/flow — it detects the project root internally
• When in autonomous mode, classify tool failures per .claude/rules/autonomous-flow-self-recovery.md — mechanical fixes are in-flow, substantive failures prompt the user