flow-plan

FLOW Plan — Phase 2: Plan

Usage

/flow:flow-plan
/flow:flow-plan --auto
/flow:flow-plan --manual
/flow:flow-plan --continue-step

• /flow:flow-plan — uses configured mode from the state file (default: manual)
• /flow:flow-plan --auto — auto-advance to Code without asking
• /flow:flow-plan --manual — requires explicit approval before advancing
• /flow:flow-plan --continue-step — self-invocation: skip Announce and Update State, dispatch via Resume Check

The plan-extract command handles the phase entry gate check (flow-start must be complete), phase enter, issue fetch, and fast-path extraction for pre-decomposed issues. It is called as the first action after the Announce banner. See the Plan Extract section below.

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.

Mode Resolution

1. If --auto was passed → continue=auto
2. If --manual was passed → continue=manual
3. Otherwise, read the state file at <project_root>/.flow-states/<branch>/state.json. Use skills.flow-plan.continue.
4. If the state file has no skills key → use built-in default: continue=manual

DAG Mode Resolution

1. Read skills.flow-plan.dag from the state file.
2. Valid values: "auto" (default), "always", "never".
3. If the key does not exist → use built-in default: "auto".

Self-Invocation Check

If --continue-step was passed, this is a self-invocation from Step 2 after the decompose plugin returned. Skip the Announce banner and the Update State section (do not call phase-transition --action enter again). 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 v1.1.0 — Phase 2: Plan — STARTING
──────────────────────────────────────────────────
```

Plan Extract

Run plan-extract as the first action. This command handles the phase entry gate check, phase enter, issue fetch, decomposed label detection, and plan extraction for pre-decomposed issues — all in a single process call.

${CLAUDE_PLUGIN_ROOT}/bin/flow plan-extract

Parse the JSON output. Branch on the path field:

If path is "extracted" or "resumed" — the plan phase is already complete. The response contains plan_content, plan_file, formatted_time, and continue_action. Skip directly to the "Fast Path Done" section below.

If path is "standard" — the command entered the phase and fetched issue context. The response contains issue_body (may be null), issue_number (may be null), and dag_mode. Note these values and continue to the Resume Check below.

If status is "error" — show the error message and stop.

Do NOT proceed past Plan Extract if it returns an error status. The command checks `phases.flow-start.status` is complete internally. Show the error message and stop.

Logging

After every Bash command in Steps 2–4, 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.

---

Fast Path Done

When plan-extract returns "extracted" or "resumed", the phase is already complete. Render the plan and transition.

Use the plan_content from the plan-extract response. Render it inline in your response — the complete Context, Exploration, Risks, Approach, Dependency Graph, and Tasks sections. Run DAG Freshness Check, Script Behavior Verification, Target Path Validation, and Risk Verification Enforcement on the plan content (see Step 3 for definitions). Use Glob and Read to verify files referenced in the Tasks section exist.

Then skip to "Done — Banner and transition", using formatted_time and continue_action from the plan-extract response.

---

Resume Check

Establish context for the standard path: run git worktree list --porcelain. Note the path on the first worktree line (this is the project root). Find the worktree entry whose path matches your current working directory — the branch refs/heads/<name> line in that entry is the current branch (strip the refs/heads/ prefix). Then read the state file at <project_root>/.flow-states/<branch>/state.json. Note pr_number, prompt, and branch from the state file — you will need them for Steps 2–4. Keep the project root, branch, state data, and pr_number in context.

• If files.dag is set (not null) but files.plan is null, the DAG was produced but the plan was not yet written (dag_file resume). Read the DAG output file at files.dag path. Skip to Step 3 (Explore and write plan).

• If both are null, proceed to Step 2 using issue_body and dag_mode from the plan-extract response.

---

Step 2 — DAG decomposition

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set plan_step=2

Pre-decomposed issue skip

If the plan-extract response returned a non-null issue_body and the issue has the "decomposed" label (plan-extract detected this internally), the DAG file and plan file were already created by plan-extract — and the "extracted" path was returned. This Step 2 section only runs for the "standard" path, meaning the issue was NOT decomposed or had no ## Implementation Plan section.

If the issue_body from plan-extract is non-null and represents an older-format decomposed issue (no Implementation Plan section), wrap the issue body with a markdown heading and route it through bin/flow write-rule so Claude Code's Write-tool preflight cannot fire on a pre-existing DAG file (see .claude/rules/file-tool-preflights.md).

Write the wrapped content to .flow-states/<branch>/dag-content.md using the Write tool:

# Pre-Decomposed Analysis: <feature description>

<issue body>

Then route it to the final DAG path via bin/flow write-rule:

${CLAUDE_PLUGIN_ROOT}/bin/flow write-rule --path <project_root>/.flow-states/<branch>/dag.md --content-file .flow-states/<branch>/dag-content.md

Store the path in the state file:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set files.dag=<dag_file_path>

Replace <dag_file_path> with the relative path .flow-states/<branch>/dag.md.

Proceed directly to Step 3. Do not set _continue_pending or _continue_context. Do not self-invoke. Execution continues in the same turn.

Standard DAG decomposition

If the issue is not decomposed, check the dag_mode from the plan-extract response:

• If dag_mode is "never" → skip to Step 3.
• If dag_mode is "auto" or "always" → invoke the decompose plugin.

Before invoking the decompose plugin, set the continuation flags so the stop-continue hook forces continuation after decompose returns:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set "_continue_context=Decompose returned. Save the complete DAG output verbatim to the DAG file, store the path in state, clear _continue_pending, then self-invoke flow:flow-plan --continue-step."

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

Invoke /decompose:decompose using the Skill tool. Pass the feature description (the prompt from the state file, plus the issue_body from plan-extract if non-null) as the task argument.

The decompose plugin will produce structured DAG output: an impact preview, an XML DAG plan with nodes and dependencies, node-by-node reasoning, and a synthesis.

After the decompose plugin returns, save the complete decompose output. The DAG file at .flow-states/<branch>/dag.md may pre-exist from a prior attempt, context compaction, or --continue-step re-entry, which would trip Claude Code's Write-tool preflight ("if this is an existing file, you MUST use the Read tool first"). Route the write through bin/flow write-rule — it does fs::write unconditionally in Rust so the preflight cannot fire. See .claude/rules/file-tool-preflights.md.

Build the full content to write — the XML DAG plan, all node executions with quality scores, and the synthesis block exactly as the plugin produced it. Do not summarize, condense, reorganize, or rewrite any part of the decompose output. Wrap with a markdown heading:

# DAG Analysis: <feature description>

<complete output from decompose plugin>

Write the content to .flow-states/<branch>/dag-content.md using the Write tool.

Apply the write to the final DAG path via bin/flow write-rule:

${CLAUDE_PLUGIN_ROOT}/bin/flow write-rule --path <project_root>/.flow-states/<branch>/dag.md --content-file .flow-states/<branch>/dag-content.md

Store the path in the state file:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set files.dag=<dag_file_path>

Replace <dag_file_path> with the relative path .flow-states/<branch>/dag.md.

Self-invoke flow:flow-plan --continue-step using the Skill tool as your final action. Do not output anything else after this invocation.

---

Step 3 — Explore and write the plan

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set plan_step=3

Pre-Planned Issue Extraction

If the DAG file (from Step 2) contains an ## Implementation Plan section, the issue was filed by /flow:flow-create-issue and already contains a complete plan. Extract it instead of re-deriving.

Detection. Use the Read tool to read the DAG file at <project_root>/<files.dag path>. Search for ## Implementation Plan in the content.

If found — extract and validate:

• Extract all content between ## Implementation Plan and the next ##-level heading (typically ## Files to Investigate).

• Promote all headings by one level: ### becomes ##, #### becomes ###. This converts the issue's nested headings into the plan file's top-level structure.

• Write the promoted content to .flow-states/<branch>/plan-content.md using the Write tool, then route it to the final plan path via bin/flow write-rule so the Write-tool preflight cannot fire on a pre-existing plan file (see .claude/rules/file-tool-preflights.md):

  ${CLAUDE_PLUGIN_ROOT}/bin/flow write-rule --path <project_root>/.flow-states/<branch>/plan.md --content-file .flow-states/<branch>/plan-content.md
  

• Light validation: use Glob and Read to verify that files referenced in the Tasks section exist. Note any missing files (they may need to be created by the implementation) but do not block or re-derive the plan.

• Run DAG Freshness Check, Script Behavior Verification, Target Path Validation, and Risk Verification Enforcement (below) on the extracted plan content, then proceed to Step 4.

If not found — the issue is an older-format decomposed issue without a plan. Use the issue body content from the DAG file as a head start for plan writing:

• Acceptance criteria inform task definitions — each criterion maps to one or more implementation tasks
• Files-to-investigate inform exploration starting points — read those files first
• Out-of-scope boundaries constrain the plan — do not add tasks outside the stated scope
• The issue body has already been validated by the user — do not re-evaluate the problem statement

Continue with the standard exploration and plan-writing flow below.

DAG Freshness Check

When to run: The DAG comes from a pre-produced source — plan-extract wrote it from a pre-planned or pre-decomposed issue, the "if found" extraction path above used a pre-existing Implementation Plan, or the Resume Check dispatched here from a dag_file resume. In all these cases, main may have advanced since the analysis was produced, changing files the DAG references.

When to skip: Step 2 decompose just ran in the current session. The DAG explored the worktree minutes ago and is fresh.

For pre-produced DAGs, verify the DAG's assumptions against reality:

• Read the DAG file and identify all file paths mentioned in backticks
• For each referenced file, use the Read tool to read the current version in the worktree
• Compare the DAG's characterization of each file (language, structure, content assumptions) against its current state
• If any file contradicts the DAG's assumptions — rewritten in a different language, deleted, or completely restructured — note the discrepancy in the plan's Risks section and adjust plan tasks to target the current implementation, not the DAG's stale description
• If no discrepancies are found, proceed normally

Script Behavior Verification

When an issue body or extracted plan asserts specific script behavior (e.g. "field X is populated after Step Y", "script A reads B from C"), verify each assertion by reading or grepping the relevant script source before building the plan on that assumption. Issue authors — including Claude in prior sessions — can be wrong about what a script does internally. A single grep of the script for the claimed field or function catches false assumptions before they become bugs in the implementation.

For each behavioral assertion found in the issue body or plan:

• Identify the script and field or function referenced
• Use the Read or Grep tool to check the actual source
• If the claim is accurate, proceed with it in the plan
• If the claim is false, note the discrepancy in the Risks section and adjust the plan accordingly

Target Path Validation

During exploration or extraction, verify that each file target identified for editing is inside the repo working tree. Files outside the repo — such as paths starting with ~/, /Users/, or any absolute path not under the working directory — are not tracked by git. Changes to those files will not appear in git status or the PR diff.

Hard rule for .claude/rules/ and CLAUDE.md: These paths are ALWAYS repo-level during any FLOW phase. If a target resolves to ~/.claude/rules/ or ~/.claude/CLAUDE.md, override it to the repo-local equivalent (.claude/rules/ or CLAUDE.md in the working tree). There is no "may be intentional" exception — user-level paths are never valid write targets during FLOW phases.

For other out-of-repo paths: if the prompt or issue body contains keywords like "repo", "version-controlled", "shared", "committed", or "tracked", default to the repo-local equivalent. Otherwise, note the out-of-repo path in the plan's Risks section so the user is aware.

Risk Verification Enforcement

After writing the plan (or extracting a pre-planned plan), scan the Risks section for any risk containing "Must verify" or "Must confirm" language. For each such risk:

Identify. Extract the specific claim or behavior that must be verified.

Search. Check the Tasks section for a task that addresses this verification — either directly (a dedicated verification task) or indirectly (a test task whose TDD notes cover the claim).

Add if missing. If no corresponding task exists, add a verification task to the Tasks section and update the Dependency Graph. The verification task should produce evidence that the risk has been checked — a test, a manual check, or a targeted exploration.

A plan with unaddressed verification risks is incomplete. Every risk that says something must be verified needs at least one task that produces evidence the verification happened.

External-Input Audit for Panic/Assert Tightenings

When a plan proposes adding a panic!, assert!, assert_eq!, assert_ne!, or constructor-level invariant check on a function parameter, the plan must include a callsite source-classification audit table. The rule exists because PR #1054 tightened FlowPaths::new to panic on slash-containing branches under a false "upstream sanitization" assumption — five hooks and format-status crashed for every user on a feature/foo or dependabot/* branch. Force-functioning the audit at Plan time catches the assumption while it is still cheap to fix.

The audit table has four columns:

Caller	Source	Classification	Handling
current_branch() (src/git.rs)	git subprocess output	Trusted-but-external	try_new, treat None as no-active-flow
state["branch"] (src/start_init.rs)	state file written by branch_name()	Guaranteed valid	new directly

Place the table within a few lines of the trigger prose (above or below). The header may use the aliases caller/callsite, classif*/class, handling/disposition. The gate validates table presence, not row content — but row content is the rule's authority, so reviewers will catch placeholder rows.

If the prose is discussing assertions rather than proposing new ones, add the opt-out comment <!-- external-input-audit: not-a-tightening --> on the trigger line itself, on the line directly above, or two lines above with a single blank line in between (no chaining across more than one blank line).

See .claude/rules/external-input-audit-gate.md for the full trigger vocabulary, the table-detection heuristic, and the enforcement topology (bin/flow plan-check plus both src/plan_extract.rs callsites).

Extract-Helper Branch Enumeration

When a plan task extracts a block of code into a new helper function, the new helper introduces its own internal branches that the plan must enumerate at Plan time — before the Code phase runs into them. Without up-front enumeration, the Code phase discovers the new branches only after the extraction lands, and the branch-level test strategy ends up decided ad hoc instead of by design.

When the plan proposes extracting a block into a new function, helper, or seam — or lifts, hoists, factors out, or pulls out an existing block — the plan's Exploration or Approach section must include a Branch Enumeration Table near the task description. The table has four columns:

Branch	Condition	Classification	Test
A	tree_changed == true	Testable directly	production_ci_decider_tree_changed_returns_not_skipped
B	tree_changed == false ∧ sentinel matches	Testable directly	production_ci_decider_sentinel_hit_returns_skipped
C	CI dirty-check dispatches to ci::run_impl	Testable via seam	(lift ci::run_impl into an injectable parameter and test via a mock)

Column definitions:

• Branch — a letter or number label identifying the branch
• Condition — the guard expression or prose condition
• Classification — one of the three values below
• Test — the named test function that will exercise this branch

The three classifications:

• Testable via seam — an injected closure, trait object, or Command parameter; branches exercised by passing mock implementations. Reference pattern: run_impl_inner(args, root, runner, ci_decider) in src/complete_fast.rs.
• Testable directly — a unit test with a self-contained fixture (TempDir, prepared state file, in-memory value). Reference pattern: production_ci_decider_tree_changed_returns_not_skipped.
• Testable via subprocess — spawn the compiled binary through tests/main_dispatch.rs; cargo-llvm-cov instruments subprocess calls when they spawn the same binary. Reference pattern: check_phase_first_phase_exits_0.

If a branch cannot be classified under one of the three, the extraction design is wrong — refactor further (push the untested surface behind a seam, fold the branch into the caller, or delete the branch entirely) until every branch lands in one of the three classifications.

If the plan prose mentions extraction in discussion rather than as a proposal, add the opt-out comment <!-- extract-helper-refactor: not-an-extraction --> on the trigger line itself, on the line directly above, or two lines above with a single blank line in between (no chaining across more than one blank line).

See .claude/rules/extract-helper-refactor.md for the full trigger vocabulary and the motivating PR #1155 incident.

Duplicate Test Coverage Check

Plans that name a test function matching an existing test in the suite typically waste a Code Review cycle — the duplicate is caught by the reviewer agent and one of the two tests is deleted, work that could have been prevented at Plan time. This subsection gates Plan-phase completion on a mechanical scanner so the duplication is surfaced before the Code phase writes the second test. Violations carry existing_test and existing_file fields so the author can see both sides of the collision inline.

When a plan names a new test function whose normalized form (strip test_ prefix, lowercase) matches an existing test in the repo's corpus, the duplicate-test-coverage scanner flags the proposal so the plan author either renames the test, strengthens the existing one, or adds an opt-out confirming the duplication is intentional. Issue #1175 / PR #1173 motivated the gate: Task 7 of that PR named stop_continue_qa_pending_fallback_blocks as a new subprocess test, a pre-existing identically-named test (modulo the test_ prefix) already exercised the same production path, and Code Review deleted the older twin — a full review cycle that the plan-time gate would have prevented.

The scanner extracts two kinds of candidate names from plan prose: fn <name>( declarations inside fenced Rust blocks, and backtick-quoted identifiers ≥ 10 characters in surrounding prose. Matches are symmetric — test_foo_bar_quux and foo_bar_quux normalize to the same key. Violations carry existing_test and existing_file so the author can see both sides of the collision.

Two line-level HTML comment opt-outs suppress a trigger, following the same walk-back-one-blank-line grammar as the sibling scanners (same line, next non-blank line, or two lines below with a single blank line between — no chaining):

• <!-- duplicate-test-coverage: not-a-new-test --> — plan prose discusses or cites an existing test by name rather than proposing one. Use in Exploration sections that reference prior art.
• <!-- duplicate-test-coverage: intentional-duplicate --> — the author is knowingly adding a parallel test per the Named Tests After Refactor pattern in .claude/rules/docs-with-behavior.md.

See .claude/rules/duplicate-test-coverage.md for the full rationale and the three-callsite enforcement topology (src/plan_check.rs::run_impl, src/plan_extract.rs extracted path, and src/plan_extract.rs resume path).

Supersession Enumeration

.claude/rules/supersession.md requires plans that add replacements, backstops, guards, or unified handlers to enumerate the code they will supersede. Catching supersession during planning is cheaper than catching it during Code Review — the exploration budget is already spent, and deletion is a mechanical task no different from the implementation itself.

When the plan introduces any of these shapes, enumerate superseded code:

• Authoritative replacement — a new correct implementation of a behavior previously attempted by broken or best-effort code elsewhere
• Deterministic guard — a new check at an entry point that makes downstream defensive handling of the same invalid state impossible to trigger
• Unified handler — a new code path that replaces multiple specialized code paths
• Deprecated API — a new API that supersedes an old API once the switchover lands in the same PR

For each shape recognized, apply the supersession test: if deleting the code leaves the PR's behavior unchanged, the code is superseded.

Three obligations follow:

• List superseded files in the Exploration section alongside newly-authored files
• Include deletion tasks in the Tasks section for every file containing superseded code
• A plan that describes a new implementation without listing the code it makes redundant is incomplete

Standard Exploration

Explore the codebase, validate the DAG against reality (if DAG was produced), and write the implementation plan to a plan file.

If a DAG was produced in Step 2, use it as the foundation:

• Validate that the files and patterns the DAG references actually exist
• Check whether the dependencies the DAG identified make sense
• Look for patterns or constraints the DAG missed

Project Conventions

Read the project's CLAUDE.md for project-specific conventions (architecture patterns, test conventions, CI fix order). Each project owns its own toolchain inside the bin/{format,lint,build,test} scripts, so the plan should refer to those scripts (and the conventions documented in CLAUDE.md) when describing how to run tests or builds.

Always include TDD order — test task before every implementation task.

Plan file structure

Write the plan to .flow-states/<branch>/plan-content.md using the Write tool, then route it to the final plan path at <project_root>/.flow-states/<branch>/plan.md via bin/flow write-rule so Claude Code's Write-tool preflight cannot fire on a pre-existing plan file (see .claude/rules/file-tool-preflights.md):

${CLAUDE_PLUGIN_ROOT}/bin/flow write-rule --path <project_root>/.flow-states/<branch>/plan.md --content-file .flow-states/<branch>/plan-content.md

<branch> is the feature branch name. This keeps the plan alongside other feature artifacts in .flow-states/.

The plan file should include these sections:

• Context — what the user wants to build and why
• Exploration — what exists in the codebase, affected files, patterns discovered
• Risks — what could go wrong, edge cases, constraints
• Approach — the chosen approach and rationale
• Dependency Graph (if DAG was produced) — table of tasks with types and dependencies:

| Task | Type | Depends On |
|------|------|------------|
| 1. Write conftest fixtures | design | — |
| 2. Write parser tests | test | 1 |
| 3. Implement parser | implement | 2 |

• Tasks — ordered implementation tasks derived from the dependency graph, each with:
  • Description of what to build
  • Files to create or modify
  • TDD notes (what the test should verify)

Proceed to Step 4.

---

Step 4 — Store plan file and complete phase

Store the plan file path in the state file BEFORE running the plan-check gate below — bin/flow plan-check resolves the plan file from files.plan, so the state pointer must be populated first:

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set plan_step=4

${CLAUDE_PLUGIN_ROOT}/bin/flow set-timestamp --set files.plan=<plan_file_path>

Replace <plan_file_path> with the relative path .flow-states/<branch>/plan.md.

Plan-check gate

Gate phase completion with a single bin/flow plan-check invocation that runs both Plan-phase scanners (scope-enumeration and external-input-audit) and aggregates all violations into one unified response. There is only one command to run — do not invoke the scanners separately. Each violation in the response carries a rule field naming which scanner fired, so the repair loop below can point the author at the right rule file per violation.

The scope-enumeration scanner flags universal-coverage language (quantifier-plus-code-family-noun phrasings) that lacks a named list of the concrete siblings nearby — see .claude/rules/scope-enumeration.md for the trigger vocabulary, the opt-out comment grammar, and the motivating incidents.

The external-input-audit scanner flags proposals to add a panic!/assert!/invariant check on a function parameter without a paired callsite source-classification audit table — see .claude/rules/external-input-audit-gate.md for the trigger vocabulary, the required four-column table format, the not-a-tightening opt-out grammar, and the motivating PR #1054 incident.

${CLAUDE_PLUGIN_ROOT}/bin/flow plan-check

Parse the JSON output:

• If "status": "ok" — the plan satisfies both scanners. Proceed to the task-count and PR-render steps below.

• If "status": "error" — the response contains a violations array with file, line, phrase, context, and rule fields. Render the violations inline in your response so the user can see each flagged phrase and which rule fired. Use the Read tool on the plan file at .flow-states/<branch>/plan.md first to satisfy Claude Code's Edit-tool preflight ("You must use your Read tool at least once in the conversation before editing" — see .claude/rules/file-tool-preflights.md), then use the Edit tool on the plan file to fix each violation according to the cited rule:

  • rule: "scope-enumeration" — add a named list (inline parenthetical with backtick-quoted identifiers, or a bullet list with backtick-quoted identifiers immediately before or after the phrase) next to the flagged phrase, OR add a line-level opt-out comment from .claude/rules/scope-enumeration.md if the phrase is genuinely open-ended or purely instructional.
  • rule: "external-input-audit" — add a four-column audit table (Caller, Source, Classification, Handling) within a few lines of the trigger, OR add the <!-- external-input-audit: not-a-tightening --> opt-out comment if the prose is discussion rather than a proposal.
  • rule: "duplicate-test-coverage" — the violation's existing_test and existing_file fields name the pre-existing test. Either rename the proposed test so the normalized form differs (e.g. pick a more specific name), delete the new-test proposal entirely in favor of strengthening the existing test, OR add the <!-- duplicate-test-coverage: not-a-new-test --> opt-out when the prose references an existing test rather than proposing one, or the <!-- duplicate-test-coverage: intentional-duplicate --> opt-out when the duplication is intentional per the Named-Tests-After-Refactor pattern.

  Re-run bin/flow plan-check and loop until the response is "status": "ok". Only then proceed to the task-count and PR-render steps.

Enforcement topology

The gate is enforced at three independent callsites, each running both src/scope_enumeration.rs::scan and src/external_input_audit.rs::scan — so the model cannot bypass either rule by choosing a different plan path:

• Standard plan path — the bin/flow plan-check block above is the gate. This is the only call that runs for plans the model writes from scratch.
• Pre-decomposed extracted path — src/plan_extract.rs runs both scanners on the promoted plan content before complete_plan_phase. If violations are found from either rule, the phase is not completed and the plan file is left on disk for the user to edit.
• Resume path — when files.plan is already set, plan_extract.rs re-runs both scanners on the existing file before re-entering the phase. A plan that was edited to fix violations passes the gate here and the phase completes; a plan still in violation fails again with the same message.

All three callsites return the same JSON error shape (status, violations[] with per-entry rule tags, message) so the repair loop is identical regardless of which path or which rule triggered the failure.

Count the total number of implementation tasks in the Tasks section of the plan file and store the count for TUI progress display:

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

Replace <n> with the total task count from the plan.

Render the complete PR body (artifacts, plan, DAG, timings, and state are all derived from the state file automatically):

${CLAUDE_PLUGIN_ROOT}/bin/flow render-pr-body --pr <pr_number>

Complete the phase:

${CLAUDE_PLUGIN_ROOT}/bin/flow phase-transition --phase flow-plan --action complete

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.

---

Done — Banner and transition

Render Plan

Use the Read tool to read the plan file at <project_root>/.flow-states/<branch>/plan.md. Render the full plan content inline in your response text — the complete Context, Exploration, Risks, Approach, Dependency Graph, and Tasks sections. Do not summarize or truncate. The user must be able to review the plan before the phase completes.

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

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v1.1.0 — Phase 2: Plan — COMPLETE (<formatted_time>)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Slack Notification

Read slack_thread_ts from the state file. If present, post a thread reply. Best-effort — skip silently on failure.

${CLAUDE_PLUGIN_ROOT}/bin/flow notify-slack --phase flow-plan --message "<message_text>" --thread-ts <thread_ts>

If "status": "ok", record the notification:

${CLAUDE_PLUGIN_ROOT}/bin/flow add-notification --phase flow-plan --ts <ts> --thread-ts <thread_ts> --message "<message_text>"

If "status": "skipped" or "status": "error", continue without error.

STOP. Parse `continue_action` from the `phase-transition --action complete` output above to determine how to advance.

1. If --auto was passed to this skill invocation → continue=auto. If --manual was passed → continue=manual. Otherwise, use continue_action from the phase-transition output. If continue_action is "invoke" → continue=auto. If continue_action is "ask" → continue=manual.
2. If continue=auto → invoke flow:flow-code directly using the Skill tool. Do NOT invoke flow: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. Invoke flow:flow-status b. Use AskUserQuestion: "Phase 2: Plan is complete. Ready to begin Phase 3: Code?" 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-code using the Skill tool e. If Not yet → print the paused banner below f. Do NOT invoke flow:flow-code until the user responds

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

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

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

---

Hard Rules

• Never write implementation code during Plan — task descriptions only
• The plan file lives in .flow-states/<branch>/plan.md alongside other feature artifacts
• Store the plan file path in state before completing the phase
• 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