flow-orchestrate

FLOW Orchestrate

Fetch all open issues labeled "Decomposed", filter out issues already in progress, and process each sequentially via flow-start --auto. Each invocation runs the full Start-Plan-Code-Review-Learn-Complete lifecycle. After all issues are processed, generate a summary report.

Usage

/flow:flow-orchestrate
/flow:flow-orchestrate --continue-step

• /flow:flow-orchestrate — start a new orchestration run
• /flow:flow-orchestrate --continue-step — resume after processing an issue (self-invocation)

Concurrency

Only one orchestration runs per machine at a time. The state file (.flow-states/orchestrate.json) acts as a lock — if it exists without completed_at, another orchestration is in progress.

Individual features within the orchestration use the standard FLOW concurrency model: branch-scoped worktrees and state files, GitHub for shared state coordination.

Self-Invocation Check

If --continue-step was passed, skip the Announce banner and Steps 1-2. 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 — flow:flow-orchestrate — STARTING
──────────────────────────────────────────────────
```

---

Step 1 — Fetch decomposed issues

gh issue list --state open --label Decomposed --json number,title,labels,body,url --limit 100

Parse the JSON output. Filter out any issues that have the "Flow In-Progress" label — these are already being worked by another FLOW feature.

If no issues remain after filtering, output:

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v1.1.0 — flow:flow-orchestrate — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  No decomposed issues to process.
```

Stop.

Step 2 — Initialize orchestration state

Build the queue from the filtered issues. Sort by issue number ascending. .flow-states/orchestrate-queue.json is a machine-level singleton that may pre-exist from a prior orchestration; route the write through bin/flow write-rule so Claude Code's Write-tool preflight cannot fire (see .claude/rules/file-tool-preflights.md). Each item must have issue_number (integer) and title (string) fields.

Write the queue JSON to .flow-states/orchestrate-queue-content.json using the Write tool, then apply the write:

${CLAUDE_PLUGIN_ROOT}/bin/flow write-rule --path .flow-states/orchestrate-queue.json --content-file .flow-states/orchestrate-queue-content.json

${CLAUDE_PLUGIN_ROOT}/bin/flow orchestrate-state --create --queue-file .flow-states/orchestrate-queue.json --state-dir .flow-states

If the response indicates an orchestration is already in progress, stop and report.

Log the queue:

${CLAUDE_PLUGIN_ROOT}/bin/flow log orchestrate "[Orchestrate] Started — N issues queued"

Display the queue as a rich markdown table matching the flow-issues format. Use the body and labels fields from Step 1 to categorize, assess impact, and prioritize each issue using the same logic as flow-issues:

• Categorize by label (Rule, Flow, Flaky Test, Tech Debt, Documentation Drift) with content-based fallback (Bug, Enhancement, Other)
• Impact from cross-area scope, force-multiplier keywords, acceptance criteria density, and dependency count (High/Medium/Low)
• Priority from category defaults with impact and blocking modifiers
• Sort by priority (High first), then decomposed before non-decomposed, then oldest first

Output the table inline with columns: Order, Priority, Impact, Labels, #, Title, Rationale. The # column uses a markdown link [#N](issue_url).

---

Resume Check

Read the orchestration state to find the next pending issue:

${CLAUDE_PLUGIN_ROOT}/bin/flow orchestrate-state --next --state-file .flow-states/orchestrate.json

• If "status": "done" — all issues processed. Skip to Done.
• If "status": "ok" — process this issue. Continue to Step 3.
• If "status": "error" — report and stop.

---

Step 3 — Process next issue

The --next response includes index, issue_number, and title.

Mark issue as started:

${CLAUDE_PLUGIN_ROOT}/bin/flow orchestrate-state --start-issue <index> --state-file .flow-states/orchestrate.json

Log it:

${CLAUDE_PLUGIN_ROOT}/bin/flow log orchestrate "[Orchestrate] Starting #<issue_number> — <title>"

Invoke flow-start:

Invoke flow:flow-start --auto <title> #<issue_number> using the Skill tool.

This runs the full lifecycle: Start, Plan, Code, Code Review, Learn, Complete.

Detect outcome:

After flow-start --auto returns, determine the outcome by checking GitHub state.

Check the PR state for the branch. Use gh pr view with the branch name:

gh pr view <branch> --json number,state,mergedAt,url

Where <branch> is derived from the issue title (the same branch name flow-start would create).

Determine outcome:

• Command succeeds and mergedAt is not null → completed
• Command succeeds and state is "CLOSED" → failed
• Command fails (no PR for that branch) → check if a .flow-states/<branch>/state.json exists using the Glob tool. If it does, the feature is stuck — record as failed with reason "Feature did not complete"

Record outcome:

${CLAUDE_PLUGIN_ROOT}/bin/flow orchestrate-state --record-outcome <index> --outcome <completed|failed> --pr-url <pr_url> --branch <branch> --state-file .flow-states/orchestrate.json

For failed outcomes, add --reason "<reason>".

Clean up stuck features:

If the outcome is failed and a state file still exists for the branch, invoke flow:flow-abort --auto to clean up the worktree, close the PR, and remove the state file.

Log and continue:

${CLAUDE_PLUGIN_ROOT}/bin/flow log orchestrate "[Orchestrate] #<issue_number> — <outcome>"

Self-invoke to process the next issue. Invoke flow:flow-orchestrate --continue-step using the Skill tool as your final action. Do not output anything else after this invocation.

---

Done

All issues have been processed.

Mark complete

${CLAUDE_PLUGIN_ROOT}/bin/flow orchestrate-state --complete --state-file .flow-states/orchestrate.json

Generate report

${CLAUDE_PLUGIN_ROOT}/bin/flow orchestrate-report --state-file .flow-states/orchestrate.json --output-dir .flow-states

Present report

Read .flow-states/orchestrate-summary.md using the Read tool and render the full content inline in your response.

Output the completion banner:

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v1.1.0 — flow:flow-orchestrate — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

Hard Rules

• Never process issues in parallel — one at a time, sequentially
• Never retry failed issues — log them and move on
• Never modify the decomposed label on issues — completed issues are closed by flow-complete, failed issues retain the label for the next run
• Never skip flow-start — the orchestrator delegates all phase execution
• 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