flow-plan

# Flow Plan

Produce a structured implementation plan and attach it to a
GitHub issue. The skill holds a Tech-Lead-default planning
conversation, runs `decompose:decompose` against the agreed
approach, transforms the synthesis into an Implementation Plan
section wrapped in FLOW-PLAN sentinels, and either edits an
existing issue in place (issue-input mode) or files a new
decomposed issue (bare-prompt mode).

The output is an issue ready for `/flow:flow-start #N` (re-planned
issue) or `/flow:flow-start #M` (new decomposed issue). The
issue body carries the implementation plan that
`bin/flow plan-from-issue` extracts at flow-start.

## Usage

```text
/flow:flow-plan #N
/flow:flow-plan <topic>
```

The skill accepts two argument shapes:

- **`#N`** — a literal `#` followed by a positive integer. Plans
  against existing issue #N: Step 2 fetches the body. When the
  DAG partitions cleanly into ≥ 2 disconnected components,
  Step 6 runs multi-track filing — one child issue per
  component with cross-component blocked-by links, leaving the
  source issue as a plain problem statement (per AC#4 of issue
  #1590). Otherwise Step 6 edits the issue in place,
  preserving every byte above the opening FLOW-PLAN sentinel.
- **`<topic>`** — any non-empty string that does not match the
  `#N` regex. Seeds discussion in Step 4; Step 6 synthesizes a
  brief `## What` / `## Why` / `## Acceptance Criteria` from the
  conversation and files one new decomposed issue. Bare-prompt
  mode is always single-track per AC#8 — even when the DAG
  partitions, exactly one issue is filed.

The skill takes no flags. A missing argument is rejected at
Step 1.

## Concurrency

The skill mutates shared GitHub state only at the very end of
Step 6, on explicit user approval. In bare-prompt mode it files
one new decomposed issue (creation is idempotent by title — warn
the user before filing a duplicate). In issue-input single-track
mode it edits the existing issue's body and re-applies the
`decomposed` label (the `gh issue edit --add-label` call is
idempotent). In issue-input multi-track mode it files one new
decomposed issue per component AND encodes blocked-by edges via
`bin/flow link-blocked-by` (the dependency endpoint is
idempotent — re-applying the same edge is a no-op on GitHub's
side).

The intermediate side effect is the per-session
utility-in-progress marker (scoped to the user's Claude home, not
the project), which lets the Stop hook refuse turn-end while the
discussion-mode skill is running.

Multiple `/flow:flow-plan` sessions on the same machine in
different terminal windows are independent — each has its own
session id, its own conversation context.

## Announce

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

````markdown
```text
──────────────────────────────────────────────────
  FLOW v2.6.0 — flow:flow-plan — STARTING
──────────────────────────────────────────────────
```
````

Immediately after the banner, write the per-session "utility skill
in progress" marker so the Stop hook refuses turn-end while this
skill is running. Without the marker the model returns control to
the user when a planning sub-agent Skill tool returns mid-pipeline
at Step 5 (Persona Dispatch) or when `decompose:decompose` returns
mid-pipeline at Step 6 (Wrap-up), breaking the unattended-flow
contract this skill promises.

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow set-utility-in-progress --skill flow:flow-plan
```

If the marker-write call returns `status: error` with
`no session_id available`, the skill proceeds without the marker.
The Stop hook treats a missing marker as a non-block, so the skill
runs without protection but does not break.

The marker is held across the entire pipeline. Every skill-exit
boundary clears the marker so the Stop hook releases turn-end
after the skill completes: the Step 1 Conversation Gate when no
argument is provided, the Step 6 validator-max-retries halt, and
the Step 6 success path after the issue has been filed or
edited.
---

## Step 1 — Conversation Gate

`/flow:flow-plan` accepts either of two argument shapes — `#N`
(issue-input mode, which plans against an existing problem
statement and edits that same issue in place) or a bare non-empty
prompt (bare-prompt mode, which synthesizes a brief What/Why/AC
from the conversation and files one new decomposed issue). The
gate routes between the two modes; it does not redirect users to
another skill.

If the argument matches the regex `^#[1-9][0-9]*$` after stripping
whitespace, set the working mode to **issue-input** and proceed
to Step 2. Step 2 fetches the parent issue body and applies the
remaining open-state gate.

If the argument starts with a `#` character but does NOT match
the `^#[1-9][0-9]*$` regex (e.g., a lone `#`, `#0`, `#-1`,
`#1234abc`, `#1.5`), the leading `#` is a strong signal of
intended issue-input mode but the trailing characters are invalid.
Routing such an argument to bare-prompt mode would silently file
a new decomposed issue with the malformed token as the seeding
topic — almost certainly a typo. Clear the utility-in-progress
marker and reject with usage guidance:

> "Argument starts with `#` but does not match `^#[1-9][0-9]*$`.
> To plan against an existing issue, pass a valid number like
> `#1234`. To plan from a bare prompt, drop the leading `#`."

If the argument is a non-empty string that contains no leading
`#` (a bare prompt such as `/flow:flow-plan add a budget cap`),
set the working mode to **bare-prompt** and skip Step 2 entirely.
The prompt seeds the planning discussion at Step 4 — there is no
GitHub issue to fetch in this mode, so Step 2's fetch and gates
do not apply. Continue at Step 3.

<HARD-GATE>

If no argument was provided at all, clear the utility-in-progress
marker so the Stop hook does not refuse turn-end after the
rejection, then output the usage guidance and stop:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow clear-utility-in-progress --skill flow:flow-plan
```

> "Argument required. Usage: `/flow:flow-plan #N` to plan against
> issue N in place, or `/flow:flow-plan <topic>` to synthesize a
> brief problem statement and file a new decomposed issue."

Do not proceed without an argument. Do not propose direct edits,
commit changes, or take any action outside this skill without
either an `#N` argument or a bare-prompt argument.

</HARD-GATE>

---

## Step 2 — Fetch Issue (issue-input mode only)

Only when Step 1 resolved to **issue-input** mode. In bare-prompt
mode there is no GitHub issue to fetch; skip to Step 3.

Read the issue's title, body, number, labels, and state via the
`gh` CLI. The body becomes the input the Tech Lead reads to
ground the planning conversation; the state gates against closed
issues (planning into a closed problem statement requires the
user to reopen it explicitly, because `bin/flow plan-from-issue`
refuses closed issues at flow-start and the resulting plan would
be unusable). The `state` field is load-bearing — without it,
the closed-issue gate below silently bypasses for every issue
because `state == "closed"` evaluates against an absent field that
is never equal to `"closed"`.

```bash
gh issue view <issue_number> --json title,body,number,labels,state,url
```

Parse the JSON output. Extract `title`, `body`, `number`, `url`,
and the labels array. The `url` field is consumed by Step 6's
`bin/flow add-issue` call so the recorded URL points at the same
issue the user passed.

<HARD-GATE>

Verify the fetched issue is in a state this skill can plan against:

- The issue MUST exist. If `gh issue view` returns a non-zero exit
  status or an error JSON, clear the marker and report the error
  to the user. Do not proceed.
- The issue's state MUST be open. Closed issues represent
  abandoned or completed work and must not be planned against
  without the user explicitly reopening them. `bin/flow
  plan-from-issue` rejects closed issues at flow-start with
  `reason: issue_closed`, so a plan written into a closed issue
  is unusable downstream. If the issue is closed, clear the
  marker and report:

  > "Issue #N is closed. Re-open it via `gh issue reopen N`
  > before planning, or pick a different issue."

The issue's `decomposed` label is NOT a rejection criterion. An
issue that already carries `decomposed` is a candidate for
in-place re-planning — Step 6 issue-input mode preserves the
content above the FLOW-PLAN sentinel and swaps the
sentinel-delimited plan block, leaving the original problem
statement intact.

Do not proceed to Step 3, propose direct edits, commit changes,
or take any action outside this skill until the fetch succeeds
and the gate passes.

</HARD-GATE>

---

## Step 3 — Role Read

Resolve the project root and read `.flow.json` from it. The file
is gitignored and lives only at the main repo root — never in a
linked worktree — so the read must target the main repo path
regardless of whether the skill was invoked outside a worktree or
from inside one.

Run `git worktree list --porcelain`. The path on the first
`worktree` line is the main repo root. Read `<project_root>/.flow.json`
via the Read tool.

The file is written by `/flow:flow-prime` and stores per-user
preferences, including the optional `role` field that records the
user's primary working role.

Extract the `role` field from the JSON. The field is optional —
older `.flow.json` files written before the role-selection step
omit it. Treat absence, an unknown value, or a read failure as "no
preferred default" and proceed silently — never block on a missing
role.

The default voice for `/flow:flow-plan` is the **Tech Lead**. The
skill's purpose — turning a problem statement into an
implementation plan with a Dependency Graph, Tasks, and
file-target callouts — is the Tech Lead's natural domain. Map the
user's `role` field to a complementary suggestion only:

| `.flow.json` role value | Conversation note |
|---|---|
| `"pm"` | The user is a PM — note once that this skill plans implementation (Tech Lead voice); the PM's natural collaborator on this is the Tech Lead. |
| `"tech-lead"` | The user IS a Tech Lead — proceed straight into Tech-Lead-voice discussion without a role-suggestion preamble. |
| `"founder-solo"` | The user wears multiple hats — proceed into Tech-Lead-voice discussion; offer to invite the PM voice via Step 5 if the conversation drifts into user-visible behavior questions. |
| Absent / unknown / read failure | Default to Tech Lead voice silently. |

The note is conversational, not gated. The discussion-mode entry
in Step 4 runs the same way for every role, and any sub-agent
dispatch in Step 5 still requires an explicit user request.

---

## Step 4 — Discussion Mode

The planning room exists so the user can think out loud against a
collaborator who reads the code, asks clarifying questions about
constraints and edge cases, and helps shape the implementation
approach. Discussion mode is the default posture — the skill stays
here until the user explicitly asks for a persona dispatch (Step 5)
or signals that the implementation plan is ready to file (Step 6).

In this step, the skill:

- Surfaces clarifying questions about the implementation approach
  — what files are affected, what existing patterns apply, what
  edge cases need testing, what constraints the parent issue
  doesn't yet name.
- Explores the codebase via the Read tool, the Glob tool, and the
  Grep tool to ground the conversation in current code. Cite file
  paths and line numbers when naming what exists today. (Unlike
  `/flow:flow-explore`, source-code reads ARE permitted here —
  the Tech Lead role requires them.)
- Identifies risks, edge cases, prior approaches the user may not
  have considered, architectural concerns, and dependencies on
  other in-flight work.
- Iterates with the user across multiple turns — challenging the
  proposed direction, summarizing what has been agreed, asking
  what comes next.

<HARD-GATE>

Discussion mode forbids action. While in this step, the skill must
NOT:

- Propose direct edits to source files, configuration, or rules —
  this is a planning room, not a coding room.
- Commit changes or invoke `/flow:flow-commit`.
- File issues or invoke any filing skill — the wrap-up belongs in
  Step 6 and is gated on an explicit user signal.
- Compose draft Implementation Plan sections inline. Discussion
  produces context for Step 6's decompose pass; rendering a
  markdown-block draft with formal `## Implementation Plan` /
  `### Context` / `### Tasks` headings during discussion mode
  would short-circuit the decompose-driven structure that the
  wrap-up step builds. Naming files, citing line numbers, and
  summarizing the agreed approach in conversational prose is
  fine; rendering a sentinel-wrapped or heading-structured draft
  is not.
- Use `AskUserQuestion` to manufacture a checkpoint the user did
  not ask for. The discussion is conversational; the user drives
  the cadence by sending messages. Per
  `.claude/rules/autonomous-phase-discipline.md`, never
  self-impose a pause via `AskUserQuestion`.
- Auto-dispatch to a planning sub-agent on inferred scope.
  Persona dispatch (Step 5) requires the user to type the request
  in plain English.

Stay in discussion mode until the user types one of: a persona
request (then proceed to Step 5 for the named persona), a
hand-off signal ("ready", "file it", "let's go") (then proceed to
Step 6), or any other prose (then continue the conversation in
discussion mode).

</HARD-GATE>

---

## Step 5 — Persona Dispatch

When the user explicitly asks for a planning persona's view ("PM
view?", "What does Tech Lead think?", "CTO take?"), summarize the
discussion so far and dispatch to the named sub-agent. The skill
remains the orchestrator; the sub-agent returns a structured
analysis or a refusal block, and the skill renders the result.

### Summarize for the agent prompt

Build the agent prompt with three labeled sections:

- **PARENT_ISSUE** — the title and body of the vanilla
  problem-statement issue the user is planning against. The
  agent reads this to ground its analysis in the user-visible
  problem.
- **CONVERSATION_SUMMARY** — a synthesis of the planning
  discussion so far. Name the constraints surfaced, the files
  explored, and the direction the user has indicated.
- **PROPOSED_APPROACH** — the concrete implementation approach
  being evaluated. Name the files that would be touched, the
  behavior change at issue, and the user-visible outcome.

### Invoke the named agent via the Skill tool

| User request | Sub-agent to invoke |
|---|---|
| PM view | `flow:pm` |
| Tech Lead view | `flow:tech-lead` |
| CTO view | `flow:cto` |

Pass the agent prompt above as the Skill tool's input.

<HARD-GATE>

When the sub-agent returns, render its response verbatim in the
conversation. If the response is a `## SCOPE REFUSAL` block, the
skill MUST surface it as-is and wait for explicit user direction.
The refusal is the agent's signal that the proposed change exceeds
its authority and a different tier should evaluate it.

When a `## SCOPE REFUSAL` block returns, the skill must NOT:

- Auto-escalate to the next tier (PM → Tech Lead, Tech Lead → CTO)
  without the user's explicit go-ahead. The escalation is the
  user's call, not the skill's.
- Re-invoke the same agent with softer framing, narrower scope, or
  any reworded prompt designed to elicit a non-refusal. The agent
  refused on principle, not on framing.
- Perform the refused analysis personally. The orchestrating model
  is not authorized to step into the role the agent declined; the
  refusal exists precisely because the change deserves a different
  level of judgment.

Present the refusal block to the user and ask them how to proceed.
If the user says "escalate to Tech Lead" or "ask the CTO", the
next persona dispatch fires in a fresh Step 5 invocation. If the
user wants to discuss the refusal in plain language, return to
Step 4.

</HARD-GATE>

When the agent returns an in-scope analysis (not a refusal), render
it verbatim and return to Step 4 so the user can react, ask
follow-ups, or request another persona's view. Do not assume the
agent's recommendation is the user's decision.

---

## Step 6 — Wrap-up: Decompose, Transform, Validate, File or Edit

When the user signals readiness — "ready", "file it", "let's go",
"create the issue", or any equivalent phrasing — run the
decompose-and-file pipeline. The output shape depends on the
Step 1 mode:

- **Issue-input mode** edits the existing issue #N in place: the
  content above the opening FLOW-PLAN sentinel is preserved
  verbatim (the original problem statement); any existing
  sentinel-delimited plan block is replaced; the fresh
  sentinel-wrapped `## Implementation Plan` is appended. The
  parent issue stays open; the assignee is not changed.
- **Bare-prompt mode** files one new decomposed issue: the model
  synthesizes a brief `## What` / `## Why` / `## Acceptance
  Criteria` from the conversation, appends the
  sentinel-wrapped plan, and files via `bin/flow issue` with
  `--label decomposed --assignee @me`. There is no parent to
  close.

### Generate session ID

Generate a short session ID using the Bash tool:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow generate-id
```

This ID scopes the body file path (`.flow-issue-body-<id>`) so
concurrent `/flow:flow-plan` invocations cannot collide on the
same temp file.

### Decompose

Invoke `decompose:decompose` via the Skill tool with an
implementation-focused prompt. The prompt must make clear that
the problem statement is already agreed; decompose should
structure the implementation into tasks, not re-analyze the
problem.

The prompt's problem-statement input depends on the Step 1 mode:

- **Issue-input mode** — pass the parent issue body fetched at
  Step 2 (the `## What` / `## Why` / `## Acceptance Criteria` the
  user filed).
- **Bare-prompt mode** — pass a brief What/Why/AC synthesized
  from the planning conversation (the bare prompt itself, plus
  any clarification the user added during Step 4 discussion).

Example prompt structure:

> "Given the following problem statement and the agreed
> implementation approach, decompose the work into ordered tasks
> with dependencies, approach, and file targets. The problem is
> already understood — focus on structuring the implementation.
>
> [Problem statement — `## What` / `## Why` / `## Acceptance
> Criteria` — either from the parent issue body (issue-input
> mode) or synthesized from the conversation (bare-prompt mode)]
>
> [Summary of the agreed approach from the conversation]
>
> [Key files and patterns identified during discussion]"

The decompose output produces a structured DAG with nodes,
dependencies, and a synthesis — this becomes the foundation for
the Implementation Plan.

<HARD-GATE>

When the Skill tool returns from the `decompose:decompose`
invocation, you are still inside flow-plan. The Skill tool's
return is NOT a stopping point — it is a mid-skill handoff. Do
not stop, do not summarize, do not ask the user "want me to
continue?", do not return control to the user. Proceed
immediately to Multi-Track Detection below using the decompose
output you just received.

If you stop here, the user must prompt you again to continue,
which breaks the unattended flow that flow-plan promises to its
consumers.

</HARD-GATE>

### Multi-Track Detection

Per AC#4 of issue #1590, after `decompose:decompose` returns,
inspect the DAG before drafting the Implementation Plan. When
the DAG partitions into two or more disconnected components
(groups of nodes with zero cross-group dependency edges) AND
the skill ran in issue-input mode, the work belongs in two or
more separate issues — one child per component — rather than
in a single combined plan. The multi-track branch is restricted
to issue-input mode by design: bare-prompt mode is always
single-track per AC#8 (a bare-prompt invocation must file
exactly one issue, never multiple).

**Detection algorithm.** Walk the DAG's `nodes` and `edges`
fields from the decompose synthesis. Treat the edges as
undirected and partition the node set into connected
components via union-find or BFS. Count the distinct
component IDs. When the count is ≥ 2 AND Step 1 recorded the
issue-input mode, the run is multi-track. Otherwise the run is
single-track and the rest of Step 6 continues unchanged from
`### Transform + Draft` onward.

**Render the proposed split inline.** Before any filing, output
the proposed split to the user inside a fenced code block so
the user sees the structural decision before any side effect:

```text
Multi-Track Filing — proposed split for source issue #N

Component A (root: <node-id>):
  - <task or node summary>
  - <task or node summary>

Component B (root: <node-id>):
  - <task or node summary>

Cross-component edges (will become blocked-by links between
children): Component B blocked-by Component A.

Source issue #N will receive blocked-by links from each root
child and will stay a plain problem statement (no
Implementation Plan block, no `decomposed` label, not closed).
```

The user may intervene to collapse the split back to
single-track by typing a message before the multi-track filing
pipeline runs. The flow halts on any real user turn; when the
user collapses to single-track, re-route to **Transform + Draft**
below and continue as if the DAG had a single component. When
no override arrives, proceed to **Multi-Track Filing Pipeline**
(later in this Step 6) and SKIP the single-track Transform +
Draft / Plan Review / Validate / File-or-Edit chain entirely.

### Transform + Draft

Take the decompose synthesis and transform it into an
Implementation Plan section. The Implementation Plan must contain
these subsections:

- **Context** — Restate what the parent issue's `## What` / `## Why`
  established, in implementation terms. This is the bridge from
  the user-visible problem statement to the implementation plan.
- **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** — Table of tasks with types and dependencies:

```markdown
| Task | Type | Depends On |
|------|------|------------|
| 1. Write tests | test | — |
| 2. Implement feature | implement | 1 |
```

- **Tasks** — Ordered implementation tasks, each with:
  - Description of what to build
  - Files to create or modify
  - TDD notes (what the test should verify)

Tasks must use `#### Task N:` heading format.

### Title Authoring

The title flows downstream into the branch name (via
`branch_name`), the PR title, the commit subject, and every
user-visible surface.

- **Issue-input mode** — the existing issue's title is what
  flow-start reads; this skill does not rewrite it. The title
  fetched in Step 2 is the title that downstream consumers will
  see.
- **Bare-prompt mode** — synthesize a title from the bare prompt
  and the planning conversation. It must pass the plain-English
  test applied at `/flow:flow-explore` filing time.

**Required.** Subject + verb + object as a stakeholder would say
it out loud. A non-contributor reading the title in a release-notes
feed should understand what the change is for without consulting
the codebase.

**Forbidden.** Code symbols, function names, file paths, line
numbers, internal acronyms without expansion, one-letter shorthand,
repo-specific jargon.

### Reconstruct Issue Body

Build the issue body in working memory. The reconstruction is
mode-dependent.

- **Issue-input mode** — start from the issue body fetched at
  Step 2. Split the body into three pieces using the FLOW-PLAN
  sentinel pair (refer to them by paraphrase here — the literal
  HTML-comment marker strings live only at their canonical
  positions inside the issue body, per the discipline below):
  1. **Prefix** — everything above the first opening FLOW-PLAN
     sentinel (or the whole body if the body contains no
     sentinel). The user's `## What` / `## Why` /
     `## Acceptance Criteria` (or whatever shape the issue body
     had) lives here.
  2. **Old plan block** — the content between the first opening
     sentinel and the matching closing sentinel. Discard this
     entire block; it is the prior implementation plan that the
     fresh decompose output replaces.
  3. **Suffix** — anything below the closing FLOW-PLAN sentinel
     (if present). Preserve verbatim. Engineers and PMs
     sometimes add post-plan notes ("## Discussion Notes",
     "## Open Questions", "## Acceptance Updates") below the
     plan block; those additions must survive re-planning.

  Reassemble the body as `<prefix>` + fresh sentinel-wrapped
  `## Implementation Plan` block + `<suffix>` (concatenated with
  blank-line separators so each section's `## ` heading begins on
  its own line). Do NOT rewrite or summarize the preserved
  pieces; only the sentinel-delimited plan block changes. Re-
  planning is idempotent by construction: every re-plan preserves
  the same prefix AND the same suffix while swapping only the
  plan block.
- **Bare-prompt mode** — synthesize a brief `## What` / `## Why`
  / `## Acceptance Criteria` from the planning conversation (the
  bare prompt the user typed plus any clarification surfaced
  during Step 4 discussion). Append the freshly-decomposed
  sentinel-wrapped `## Implementation Plan` after the Acceptance
  Criteria section. There is no prior body to preserve.

Each top-level section uses `##` headings. The Implementation
Plan's subsections use `###` headings. Task entries within the
Tasks subsection use `####` headings.

**Wrap the Implementation Plan in FLOW-PLAN sentinels.** Place
the literal HTML comment `<!-- FLOW-PLAN-BEGIN -->` on its own
line immediately before the `## Implementation Plan` heading,
and the literal HTML comment `<!-- FLOW-PLAN-END -->` on its own
line immediately after the last Task entry (before the next
`## ` heading). The sentinels delimit the bytes that
`bin/flow plan-from-issue` will extract verbatim and write to
`.flow-states/<branch>/plan.md` when the issue is later picked up
via `/flow:flow-start #M`. Without the sentinel pair,
plan-from-issue rejects the issue with `plan_markers_missing`
and the flow halts.

**Paraphrase every prose reference to the plan-sentinel pair.**
The literal HTML-comment marker strings only appear in the body
at two positions — the opening sentinel and the closing sentinel.
They must never appear inside prose, headings, code blocks,
examples, or any other surface of the body. `bin/flow
plan-from-issue` extracts the slice between the FIRST occurrence
of each marker, so a literal marker mid-prose silently redirects
the extraction to the wrong slice. Whenever the body needs to
reference the marker pair, paraphrase: "the FLOW-PLAN sentinel
pair", "the plan-extraction markers", "the canonical sentinels
delimiting the plan block".

### Pre-Draft Backwards-Reasoning Scan

Before presenting the draft, scan the body — including the
Implementation Plan subsections — for the following forbidden
phrasings, which ground the current decision in a historical
artifact rather than the code's current merits:

- `"PR #<N> decided"`, `"the prior PR chose"`, `"the previous
  commit"` — historical decision cited as authority
- `"kept for backward compatibility"`, `"compat shim"`, `"legacy
  alias for older"` — preservation justified by inherited
  reasoning rather than a current consumer
- `"older plugin versions"`, `"prior plugin"` —
  plugin-version-compat reasoning
- `"as PR #<N> chose to"`, `"following the prior PR"` —
  deferring to past decisions

Evaluate matches in context: a bare `PR #<N>` reference used for
forensic detection (linking blocked-by, naming a specific merge)
is fine; a `PR #<N>` reference used to justify the present design
is forbidden. If any match is justifying-shape rather than
identifier-shape, revise the draft. See
`.claude/rules/no-backwards-reasoning.md`.

### Pre-Draft Include-Bias Scan

Before presenting the draft, scan the body — including the
Implementation Plan subsections — for the following forbidden
phrasings, which signal defensive scope shrinkage rather than
genuine exclusion grounded in a concrete blocker:

- `"Out of scope"` — defensive enumeration of exclusions written
  before concrete blockers have surfaced; the scan reads
  case-flexibly, so common section-heading title-case forms in
  issue bodies are also flagged
- `"Non-goals"` — same defensive-enumeration shape under a
  different heading
- `"would expand scope"` — reflexive scope shrinkage that
  bypasses the three-condition gate in
  `.claude/rules/scope-expansion.md`
- `"separate code surface"` — code-shape framing used as an
  exclusion criterion

Evaluate matches in context: a passing mention that names a
concern is fine; an enumerated section or bulleted list of
exclusions is forbidden. If any match is exclusion-shape rather
than identifier-shape, revise the draft. See
`.claude/rules/include-bias-in-issues.md`.

### Draft Presentation

Present the full draft inline in the response — both title and
body. Do not tell the user to look at a file. Render it as a
formatted markdown block so the user can review every detail.

### Plan Review

The drafted Implementation Plan has been transformed, combined,
and pre-scanned by the orchestrating model — every check so far
has run *on the orchestrating model's own output*. This subsection
adds a cognitively isolated rule-adherence review before the issue
is filed or edited. The reviewer audits the drafted plan against
the `.claude/rules/` corpus; on `re-decompose` the plan is re-derived
through `decompose:decompose` (never hand-patched) and re-reviewed,
capped at 3 attempts.

Invoke `flow:plan-reviewer` via the **Agent tool** with
`subagent_type: "flow:plan-reviewer"` (the canonical sub-agent
dispatch shape — matching the flow-review and flow-learn agent
invocations; the Skill tool is reserved for skill-to-skill
dispatch, not sub-agent dispatch). The prompt is a three-block
payload: the drafted Implementation Plan body verbatim, the
parent vanilla issue's Acceptance Criteria verbatim, and an
absolute path to the `.claude/rules/` directory. Explicitly
state that no conversation context is provided — the agent must
reason from the artifacts alone.

Substitute `<project_root>` with the absolute path returned by
`pwd` at session start; the bare relative `.claude/rules/` would
resolve against the sub-agent's cwd, which is not guaranteed to
equal the project root.

The prompt structure:

```text
You are reviewing a drafted Implementation Plan for rule
adherence. No conversation context is provided.

DRAFTED_PLAN:
<the full drafted Implementation Plan body verbatim, in full —
copy every line including Context, Exploration, Risks, Approach,
Dependency Graph, and Tasks; do NOT summarize or paraphrase>

ACCEPTANCE_CRITERIA:
<the parent vanilla issue's Acceptance Criteria section, verbatim>

RULES_DIR: <project_root>/.claude/rules/
```

Parse the agent's response. First check for the literal
`## END-OF-FINDINGS` marker as the final structural element. If
the marker is ABSENT, the agent was truncated by `maxTurns`
exhaustion (per `.claude/rules/cognitive-isolation.md` "Context
Budget + Truncation Recovery"). Re-invoke the agent with a
narrower scope partitioned by rule-family (e.g., split
`.claude/rules/` into `architecture/` + `correctness/` + the
rest, one re-invocation per partition), then combine findings
across runs. If a re-invocation itself returns without the
marker, that is double-truncation — record the truncation in
the final user-visible violations block rather than splitting
infinitely.

When the marker is present, parse `VERDICT:` from the response.
The reviewer classifies each violation per-finding (carried on a
`Remediation:` line) and the aggregate verdict is the routing
signal. Branch three ways:

- **`VERDICT: pass`** → the plan satisfies the project rules. Fall
  through to `Validate the Body` unchanged.
- **`VERDICT: revise-transform`** → at least one applicable rule
  is violated AND every violation is a Transform-step prose
  artifact (table placement, a missing required table, doc-surface
  enumeration, prose wording). Capture the `Violations:` block and
  run the revise-transform branch of the loop below — apply the
  reviewer's named prose fixes directly to the drafted body
  **without re-running decompose**.
- **`VERDICT: re-decompose`** → at least one violation requires a
  task-DAG change (an unmotivated component, a missing task, wrong
  ordering, a missing gate-consumer task). Capture the
  `Violations:` block from the agent's output and run the
  re-decompose branch of the loop below.

<HARD-GATE>
Do NOT proceed to `Validate the Body` when the verdict is
`re-decompose` or `revise-transform` until the matching loop
branch below has run.

For `re-decompose`: do NOT hand-patch the plan. The plan must be
re-derived through `decompose:decompose` with the violations fed
back as input. Hand-patching a re-decompose-class finding defeats
the cognitive-isolation contract — the orchestrating model would
be editing its own output to satisfy the reviewer, reintroducing
the bias the gate exists to break.

For `revise-transform`: applying the reviewer's named prose fix
in the Transform step IS the **sanctioned remediation** — not a
hand-patch the orchestrator self-authorized. The cognitively
isolated reviewer has already classified the fix as a mechanical
prose correction with no design judgment; the orchestrator
executes the reviewer's named instruction, it does not re-judge
the plan's substance. Hand-patching a `re-decompose`-class finding
remains forbidden in every context.
</HARD-GATE>

#### Plan-Reviewer Loop (max 3 attempts)

When the verdict is `re-decompose` or `revise-transform`, run a
bounded retry loop mirroring the Validator Auto-Fix Loop shape
below. A single cap of **3 attempts** (including the first failed
review) is shared across both remediation branches — they never
have separate budgets.

For each retry attempt, run the remediation step matching the
verdict the most recent review returned:

- **`re-decompose` remediation** — the fix needs a task-DAG
  change:
  1. Construct a fresh `decompose:decompose` prompt that includes
     the parent vanilla issue context, the prior plan synthesis,
     and the `Violations:` block returned by the reviewer.
  2. Invoke `decompose:decompose` via the Skill tool and wait for
     the new synthesis.
  3. Re-run `Transform + Draft` on the new synthesis to produce a
     revised Implementation Plan.
- **`revise-transform` remediation** — every violation is a
  Transform-step prose artifact, so the fix is in-place prose
  correction **without re-running decompose**:
  1. Apply the reviewer's named prose fixes directly to the
     already-drafted plan body (move the table to the Tasks
     section, add the missing required table, fix the wording).
     Do NOT invoke `decompose:decompose` — the task DAG is
     already correct.
  2. The prior synthesis carries forward unchanged; only the
     orchestrator-authored prose is corrected.

Then, regardless of which remediation branch ran:

3. Re-run the Pre-Draft scans on the revised body.
4. Re-validate readiness of the revised plan.
5. Re-invoke `flow:plan-reviewer` against the revised plan via
   the Agent tool with `subagent_type: "flow:plan-reviewer"`.
6. Check for the `## END-OF-FINDINGS` marker. If absent, re-invoke
   with narrower scope per the truncation-recovery path above
   before parsing `VERDICT:`.
7. Parse `VERDICT:` again. On `pass` exit the loop and fall
   through to `Validate the Body`. On `re-decompose` or
   `revise-transform` increment the shared attempt counter and
   continue with the matching remediation branch.

After 3 failed reviews, do NOT loop further. The plan-reviewer
advises — it never blocks filing. The issue is then
filed with the last drafted plan; the final `Violations:` block
is surfaced as a non-blocking advisory warning rather than a
halt.

Print the advisory preface, then render the agent's final
`Violations:` block verbatim:

````markdown
```text
⚠ Plan Review advisory — the plan-reviewer returned a non-pass
  verdict (`re-decompose` or `revise-transform`) on all 3
  attempts. The issue is being filed with the last drafted plan;
  the violations below are surfaced for the user, not a block on
  filing.
```
````

The user sees which rules the plan repeatedly violated and can
decide whether to address them — by invoking `/flow:flow-plan #N`
again with additional discussion-mode context, or by escalating
the rule design if a rule itself is at fault — before the issue
reaches `/flow:flow-start`.

Then fall through to `Validate the Body` → `File or Edit` →
`Finish` with the last drafted plan. The utility-in-progress
marker clears at the normal `Finish` step.

### Validate the Body

Write the reconstructed body to `.flow-issue-body-<id>` using the
Write tool. Per `.claude/rules/filing-issues.md` "The Pattern":
when invoked inside an active FLOW worktree, prepend the worktree
absolute path so the `validate-worktree-paths` hook allows the
Write. When invoked outside a worktree, the relative form
resolves cleanly because Write and `bin/flow issue` both target
the same project root.

Validate the body file through the pre-filing validator with
`--mode decomposed` before either filing the new issue or editing
the existing one. The validator runs the same sentinel-extraction
logic that `bin/flow plan-from-issue` applies at flow-start; any
body that fails this gate is unconsumable downstream and must NOT
be sent to GitHub:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow validate-issue-body --mode decomposed --body-file .flow-issue-body-<id>
```

Parse the JSON output. If `status` is `ok`, proceed to the
mode-specific filing branch below. If `status` is `error`, run
the bounded auto-fix loop:

#### Validator Auto-Fix Loop (max 5 attempts)

When the validator returns `status: error`, the skill must NOT
prompt the user. The validator's `message` names a concrete defect
(missing FLOW-PLAN sentinel pair, missing required subsection,
`## Implementation Plan` heading on the wrong nesting level, etc.).
Apply a mechanical fix that addresses the named defect — adjust
the sentinel placement, add the missing subsection, normalize the
heading — rewrite the body file with the Write tool, and re-run
the validator. Track the attempt count mentally — the cap is
**5 attempts** including the first failure.

After 5 failed validator runs, clear the utility-in-progress
marker, halt the skill with the structured error envelope, and
print the COMPLETE-FAILED banner. Do NOT file the issue. Do NOT
edit any issue. Do NOT loop further.

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow clear-utility-in-progress --skill flow:flow-plan
```

````markdown
```json
{"status":"error","reason":"validator_max_retries","attempts":5}
```
````

````markdown
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✗ FLOW v2.6.0 — flow:flow-plan — COMPLETE-FAILED
  Validator rejected the body 5 times. Issue not filed.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
````

### File or Edit (branch on Step 1 mode)

Once the validator returns `ok`, branch on the Step 1 mode.

**Issue-input mode — edit #N in place.** Push the rebuilt body
into the same issue, re-applying the `decomposed` label (the
label may already be present; `--add-label` is idempotent).
Substitute the issue number (the `#N` the user passed at Step 1)
for `<N>`:

```bash
gh issue edit <N> --body-file .flow-issue-body-<id> --add-label decomposed
```

When `gh issue edit` returns a non-zero exit status (transient
network failure, auth scope mismatch, the issue closed between
Step 2 and now, etc.), the body update may have partially landed
— gh writes the body before applying labels, so a mid-call
failure can leave the issue with the new body but the
`decomposed` label still missing, making it invisible to
`flow-issues` / `flow-orchestrate`. Surface the gh exit status
and stderr inline to the user with a concrete recovery command,
then clear the utility-in-progress marker and stop. Do NOT
retry the edit silently. The recovery command shape:

> "`gh issue edit <N>` failed. Inspect via
> `gh issue view <N> --json body,labels`. If the body landed but
> `decomposed` is missing, run
> `gh issue edit <N> --add-label decomposed`. If the body did not
> land, the `.flow-issue-body-<id>` file is still on disk —
> re-run `gh issue edit <N> --body-file
> .flow-issue-body-<id> --add-label decomposed`."

`gh issue edit` does not auto-delete the body file. Delete the
temp file explicitly via the Write tool by writing an empty
string to `.flow-issue-body-<id>`, then ignore the empty file —
the worktree cleanup at Phase 5 Complete handles disposal. (The
Bash permission allow-list refuses ad-hoc `rm` calls during a
flow per `.claude/rules/permissions.md`; rewriting to empty is
the sanctioned alternative.) Skip this empty-write step when
`gh issue edit` failed — preserving the body file on disk gives
the user a concrete artifact to retry the edit against.

Capture the issue's URL from the `gh issue view` JSON fetched at
Step 2 (the `url` field), then record the issue in the state file
(no-op if no FLOW feature is active):

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow add-issue --label decomposed --title "<issue_title>" --url "<issue_url>" --phase flow-plan
```

**Bare-prompt mode — file a new issue.** File against the
current repo (no `--repo` flag — `flow-plan` always files where
the user is) WITH the `decomposed` label so `flow-issues` and
`flow-orchestrate` recognize it as ready-for-flow-start work,
and WITH `--assignee @me` so the new decomposed issue is
assigned to the planner who ran `flow-plan`:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow issue --title "<issue_title>" --body-file .flow-issue-body-<id> --label decomposed --assignee @me
```

Capture both the new issue's URL and number from the filer's
output. `bin/flow issue` returns a JSON envelope including the
full GitHub URL of the issue it created; the trailing
`/issues/M` segment of that URL gives the **decomposed issue
number M**. Keep both the full URL (as `<issue_url>`) and the
number for the recording call below — bare-prompt mode has no
Step 2 fetch to pull these from.

Record the issue in the state file (no-op if no FLOW feature is
active):

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow add-issue --label decomposed --title "<issue_title>" --url "<issue_url>" --phase flow-plan
```

### Multi-Track Filing Pipeline

Runs only when **Multi-Track Detection** routed here — the DAG
had ≥ 2 disconnected components AND the run is in issue-input
mode (per AC#4 + AC#8). When the run is single-track, this
subsection is skipped entirely; the single-track flow above
(Transform + Draft through File or Edit) has already filed or
edited the issue and the model falls through to **Finish**
below.

For each component in the detected partition, build, validate,
plan-review, and file ONE child issue. After every child is
filed, link the children together via `bin/flow link-blocked-by`
to encode the cross-component edges, and link the source issue
blocked-by each root child so the AC#5 cascade can close the
source naturally when the children eventually close.

**Per-child sub-flow.** Repeat the following for each component:

1. Synthesize a child What/Why/Acceptance-Criteria header from
   the component's nodes — the planning conversation already
   established the parent's `## What` / `## Why`; the child
   header narrows it to this component's scope only.
2. Run the same Transform + Draft / Title Authoring /
   Reconstruct Issue Body / Pre-Draft scans pipeline that the
   single-track subsections describe, but constrained to THIS
   component's nodes and dependency subgraph. Produce a
   per-child issue body with the FLOW-PLAN sentinel pair and
   the `## Implementation Plan` block covering only this
   component's tasks.
3. Write the child body to
   `.flow-issue-body-multi-<id>-<component>` via the Write
   tool. The unique suffix prevents collisions with the
   single-track body file and with sibling children.
4. Validate the child body BEFORE filing:

   ```bash
   ${CLAUDE_PLUGIN_ROOT}/bin/flow validate-issue-body --mode decomposed --body-file .flow-issue-body-multi-<id>-<component>
   ```

   The same Validator Auto-Fix Loop (max 5 attempts) applies
   per child — when the validator returns `status: error`,
   apply a mechanical fix and retry up to 5 times for this
   child before halting.
5. Review the child plan via `flow:plan-reviewer` (one Agent
   tool invocation per child) BEFORE filing. The review
   contract mirrors the single-track Plan Review subsection
   above: the agent receives the DRAFTED_PLAN verbatim and the
   absolute `<project_root>/.claude/rules/` corpus. Cap the
   reviewer loop at 3 attempts per child; on cap exhaustion
   file the child with the last drafted plan and surface the
   violations as a non-blocking advisory warning, identical to
   the single-track cap-exhausted behavior.
6. File the child issue with the `decomposed` label and
   `--assignee @me`:

   ```bash
   ${CLAUDE_PLUGIN_ROOT}/bin/flow issue --title "<child_title>" --body-file .flow-issue-body-multi-<id>-<component> --label decomposed --assignee @me
   ```

   Capture the new child's URL and issue number from the
   filer's JSON output — both are needed for the linking step
   below and for the recording call.
7. Record the child in the state file (no-op outside an active
   flow):

   ```bash
   ${CLAUDE_PLUGIN_ROOT}/bin/flow add-issue --label decomposed --title "<child_title>" --url "<child_url>" --phase flow-plan
   ```

**Detect the repo.** `bin/flow link-blocked-by` requires
`--repo <owner/name>`. Resolve it once from the worktree's
git origin before any linking call:

```bash
git remote get-url origin
```

Parse the stdout — both SSH (`git@github.com:owner/name.git`)
and HTTPS (`https://github.com/owner/name.git`) forms appear in
practice. Strip the protocol/host prefix and the trailing `.git`
to produce `owner/name`. Capture this value as `<repo>` and
substitute it into every `link-blocked-by` invocation below.

**Link the children to each other.** For every cross-component
dependency edge `B → A` in the original DAG (component B's
root depends on component A's root), link the two child
issues so GitHub's native blocked-by graph reflects the
structural relationship:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow link-blocked-by --repo <repo> --blocked-number <child_B> --blocking-number <child_A>
```

**Link the source issue to its root children.** Cap the
dependency graph by linking the source issue blocked-by every
root child (a "root child" is a component whose root has no
incoming cross-component edges). The source issue then awaits
its children's closures:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow link-blocked-by --repo <repo> --blocked-number <source_issue> --blocking-number <root_child>
```

When every child has been filed and every blocked-by edge is
encoded, the AC#5 cascade handles the eventual closure of the
source issue: as each child PR merges and closes its child
issue, `bin/flow auto-close-parent` walks the dependency
graph; once every blocker of the source is closed, the cascade
closes the source. No `--state-file` mutation is required at
this skill — the cascade is wired in from
`complete-post-merge` of each child's flow.

**Source-issue treatment.** Multi-track leaves the source
issue as a plain problem statement throughout filing:

- The source issue body is NOT modified — it stays a plain
  problem statement (no Implementation Plan block).
- NO `decomposed` label is applied to the source issue —
  only the children receive that label. `flow-issues` filters
  the source as Vanilla (ready for re-planning) until the
  cascade closes it.
- The source issue is NOT closed by multi-track filing —
  closure comes via the AC#5 blocked-by cascade only, after
  every child PR merges.

When the per-child loop is complete and every blocked-by edge
is encoded, fall through to **Finish** below. SKIP the
single-track **File or Edit** subsection — the children have
already been filed and linked. The Finish banner and
post-flow instruction text below render the same way; only
the message text changes to name the multi-track outcome
(filed children + linked source) instead of a single
issue-edit or new-issue result.

### Finish

Clear the utility-in-progress marker:

```bash
${CLAUDE_PLUGIN_ROOT}/bin/flow clear-utility-in-progress --skill flow:flow-plan
```

Display the issue URL to the user, then output the COMPLETE
banner in your response (not via Bash) inside a fenced code
block:

````markdown
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v2.6.0 — flow:flow-plan — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
````

Then instruct the user. The message names the same issue number
the next phase will pick up.

- **Issue-input mode:** "Re-planned issue #N in place. To start
  implementing, run `/flow:flow-start #N`."
- **Bare-prompt mode:** "Filed decomposed issue #M. To start
  implementing, run `/flow:flow-start #M`."

Do not invoke `/flow:flow-start` yourself — the user types the
slash command directly.

---

## Hard Rules

- **Accept `#N` or a bare prompt.** Step 1 routes `#N` to
  issue-input mode (Step 2 fetches the issue and Step 6 edits it
  in place) and bare non-empty prompts to bare-prompt mode (Step 2
  is skipped; Step 6 synthesizes a brief What/Why/AC and files
  one new decomposed issue).
- **Issue-input mode edits #N in place OR files one issue per
  disconnected component; bare-prompt mode files one new
  issue; never close a parent issue.** Issue-input single-track
  preserves every byte above the opening FLOW-PLAN sentinel
  (including the original `## What` / `## Why` /
  `## Acceptance Criteria`) and swaps the sentinel-delimited
  plan block. Issue-input multi-track (AC#4) files one child
  per disconnected DAG component and leaves the source issue
  as a plain problem statement (no Implementation Plan block,
  no `decomposed` label, not closed) — closure of the source
  comes via the AC#5 blocked-by cascade. Bare-prompt mode
  files one new decomposed issue with `--label decomposed
  --assignee @me` and is always single-track per AC#8. There
  is no parent-closure step in any mode.
- **Always file with `--label decomposed`.** Without the label,
  `flow-issues` and `flow-orchestrate` won't recognize the issue
  as ready-for-flow-start work.
- **Always validate with `--mode decomposed`** before filing.
  Vanilla bodies and decomposed bodies have different shapes; the
  wrong mode silently passes a body that `bin/flow plan-from-issue`
  will later reject.
- Never propose direct edits, commit changes, or file issues
  outside the explicit Step 6 wrap-up.
- Never present draft Implementation Plan sections inline before
  reaching Step 6 Wrap-up. Discussion produces context for the
  decompose pass; rendering a sentinel-wrapped or
  heading-structured draft during discussion is forbidden.
- Never use `AskUserQuestion` during discussion mode. The
  discussion is conversational; the user drives the cadence.
- Never auto-dispatch to a planning sub-agent on inferred scope.
  Persona dispatch requires the user to type the request in plain
  English.
- Never auto-escalate, re-invoke with softer framing, or perform
  the refused analysis personally when a sub-agent returns a
  `## SCOPE REFUSAL` block. Render the refusal verbatim and wait
  for explicit user direction on the next move.
- Never use `AskUserQuestion` in the Step 6 wrap-up. The user's
  readiness signal from the discussion phase is the single
  authorization to file; a second confirmation gate would break
  the single-signal contract that drives the unattended-flow
  promise.
- Never tell the user to "look at" a file — render all content
  inline.
- Never use Bash to print banners — output them as text in your
  response.
- Always use the Write tool to create body files
  (`.flow-issue-body-<id>`) — never pass body text as a CLI
  argument.
- Never delete the body file — the `bin/flow issue` script
  handles cleanup.
- Treat absence or unknown values of the `.flow.json` `role`
  field as "no preferred default" and proceed silently. Never
  block on a missing field.
- All `bin/flow` calls in skill bash blocks use the plugin root
  prefix — bare `bin/flow` only resolves inside the FLOW repo
  itself, not in target projects.