# Plan Orchestrator

> This skill should be used when the user asks to "generate an ORCHESTRATE file", "turn a spec into a plan", "scaffold a feature breakdown", "scaffold a sprint backlog", "plan a sprint" (when a committed backlog/artifact is wanted, not just strategy advice), "generate roadmap artifacts", "create an implementation plan from SPEC", or needs to produce concrete planning artifacts (ORCHESTRATE-*.md, feature breakdowns with task estimates, sprint backlogs, milestone roadmaps). Differs from `project-planner` (high-level strategy/advice) by producing committed, actionable artifacts tied to specs and worktrees.

- Skill: `data-wise/plan-orchestrator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add data-wise/plan-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/data-wise/plan-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Data-Wise (https://skillmd.com/u/data-wise)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/data-wise/plan-orchestrator

---


# Plan Orchestrator Skill

Produces **concrete planning artifacts** from specs and feature requests. Where `project-planner` advises on strategy ("how should we estimate?"), this skill emits files and structured backlogs ready to drive implementation: `ORCHESTRATE-<topic>.md`, feature task trees, sprint commitments, and visual roadmaps.

## When to Use

Activate when the user wants a **deliverable** (file, backlog, milestone list), not just guidance:

- "Generate ORCHESTRATE from `docs/specs/SPEC-auth-*.md`"
- "Break this feature into tasks with estimates"
- "Plan next sprint, 80 hours capacity"
- "Generate a 6-month roadmap as mermaid"
- "Turn this brainstorm into a planning doc"

Do **not** use for: routing a single task to a command (use `task-analyzer`), saving session state (use `session-state`), or general "how do I plan?" advice (use `project-planner`).

## Differentiation Map

| Need | Skill |
|------|-------|
| "What command should I run for X?" | `task-analyzer` |
| "Save / resume my orchestrator session" | `session-state` |
| "Coach me on estimation / agile practices" | `project-planner` |
| "**Generate the actual plan file**" | **`plan-orchestrator`** (this) |

## Four Planning Modes

This skill consolidates four commands. The user's phrasing selects the mode:

### 1. Spec → ORCHESTRATE (`orchestrate:plan`)

**Trigger:** spec file mentioned, or "implementation plan from SPEC".

**Flow:**

1. Discover specs in `docs/specs/SPEC-*.md` (and `BRAINSTORM-*.md` lacking specs).
2. Parse selected spec: title, phases/increments, acceptance criteria, key files, cross-repo references.
3. Detect cross-repo work (paths under `~/projects/<other>/`); enforce same branch name across repos.
4. Confirm plan with user (ORCHESTRATE+worktree / ORCHESTRATE-only / modify / cancel).
5. Generate `ORCHESTRATE-<topic>.md` with sections: Objective, Phase Overview, Phase 1..N, Friction Prevention, Acceptance Criteria, Commit Strategy, Verification, Session Instructions.
6. Create worktree at `~/.git-worktrees/<project>/feature-<topic>` from `dev` if selected.
7. Update `.STATUS` and `.gitignore`.
8. Branch on `output`:
   - `orchestrate-worktree` (default) or `orchestrate-only` → instruct the user to `cd` into the
     worktree and start a new session — do NOT begin implementation (STOP-new-session mode).
   - `orchestrate-dispatch` → skip the STOP instruction; instead run the confirm-before-dispatch
     gate (below), then dispatch a background `Agent` call from this same live session. See
     "`orchestrate-dispatch` mode" below for the full flow.

**Key constraint:** ORCHESTRATE file lives in the **worktree root**, never the main repo.

### `orchestrate-dispatch` mode

A third `output` value. Same self-containment guarantee as STOP-new-session mode, but execution
happens via a background `Agent` call dispatched from the live planning session instead of a
fresh human session opening a new terminal. Use this when the token/attention cost of a
cold-started human session outweighs the extra safety mechanisms below (see "When to use which"
in the pipeline-orchestrate guide).

**GRILL-file precondition (warn-only, not a hard block):** if no `GRILL-*.md` exists for the
spec's topic, print an advisory warning and proceed anyway — grilling resolves judgment calls
before dispatch, but a well-scoped, low-ambiguity spec doesn't strictly require it. The backstop
below (ungrilled-ambiguity handling) covers the case where it turns out an unresolved judgment
call was needed after all.

**Confirm-before-dispatch gate:** after the ORCHESTRATE file and worktree are generated
(steps 5-7), before calling `Agent`, run an `AskUserQuestion` gate — not a suppressible prompt.
Show the generated ORCHESTRATE summary (Phase Overview table) and the worktree path. Options:

- **dispatch-now** — call `Agent` immediately with the self-containment prompt (below).
- **review-first** — pause; let the user inspect/edit the ORCHESTRATE file before dispatching.
- **cancel** — stop; ORCHESTRATE file and worktree remain, no dispatch.

This gate fires unconditionally. `--yes` auto-accepts other prompts in this skill but does **not**
suppress this one — it is a design requirement, not a prompt-refiner echo, because dispatch hands
off execution to an unsupervised agent and deserves an explicit human checkpoint every time.

**Self-containment prompt shape:** the dispatched `Agent`'s entire prompt is exactly:

> "Working directory: `<absolute worktree path>`. Read `ORCHESTRATE-<topic>.md` in full from that
> directory, then execute it."

The path is a **structural requirement, not context** — the `Agent` tool has no `cwd` parameter
(confirmed: `~/projects/dev-tools/CLAUDE.md` — "There is no `cwd` parameter on the Agent tool"), so
without it the dispatched agent has no way to locate the worktree or the ORCHESTRATE file itself.
Beyond the path, no other context is passed — no summary, no paraphrase, no conversation history,
and no confinement instruction (a legitimate cross-repo dispatch, per Cross-Repo Detection above,
is expected to touch a second repo's paired worktree — don't contradict that here). This is the
same durable artifact a fresh human session would read under STOP-new-session mode;
self-containment becomes structural (inherited from the ORCHESTRATE file's own required
completeness) rather than a discipline checklist.

**Ungrilled-ambiguity backstop:** if the dispatched agent hits genuine unresolved ambiguity
(whether or not a GRILL file existed), it must leave that phase's checkbox unchecked, add a
one-line blocker note directly in the ORCHESTRATE file, and stop — never guess.

**Concurrency cap (scoped to `orchestrate-dispatch` only):** soft cap of 2 concurrent
`orchestrate-dispatch` dispatches per session. A 3rd+ concurrent dispatch requires an explicit
`AskUserQuestion` confirmation before calling `Agent`. **Scoping rule (the part most likely to be
silently gotten wrong):** the counter tracks ONLY background `Agent` calls made via this
`orchestrate-dispatch` flow — it does NOT count unrelated background `Agent` calls the session may
also have running for other purposes (research agents, doc agents, etc.). Maintain the count as an
explicit running tally of dispatches labeled `orchestrate-dispatch` (e.g. tag each dispatch's
`description` so it's identifiable), not a raw count of "all currently-running background agents."
This is not a hard block — a deliberate larger fan-out is still possible, just confirmed.

**Failure/hang detection:** never trust the `Agent` tool's completion notification alone — cross-
check it against the dispatched ORCHESTRATE file's own checkboxes and Phase Overview status
column.

- Notification fires, but re-reading the ORCHESTRATE file shows no checkboxes moved since dispatch
  → flag as a suspected silent failure. Do not offer merge. Surface this to the user explicitly.
- No completion notification within the hang-detection window (below) → surface the crash/hang
  case explicitly. Do not wait silently past the window.

**Hang-detection window formula:** `2 × the dispatched ORCHESTRATE file's own stated phase-effort
estimate` — not a fixed wall-clock constant. The effort estimate comes from the Phase Overview
table's `Effort` column, which Mode 1's existing template already requires for every phase. Example:
a phase overview row stating `Effort: Med` for the currently-dispatched phase sets the flag-as-hung
threshold at 2× whatever wall-clock duration this session maps `Med` effort to for this project —
reuse the same effort→duration mapping the session already uses elsewhere, don't invent a new one
here.

**Confirmed-failure disposition:** on a confirmed silent-failure or hang (per the detection rule
above), never auto-delete the worktree or branch — leave both in place for inspection. Add a
`.STATUS` note in the same HELD style already used for prior held work in this repo (factual: what
was dispatched, what was observed, that it's paused pending manual inspection — not narrative
guesswork about the cause).

**Resumability:** re-dispatching against the SAME ORCHESTRATE file must be idempotent. Before
dispatch, read the file's Phase Overview status column and per-phase checkboxes (the same
tracking this mode already requires agents to maintain). If any phases are already checked, the
self-containment prompt is **identical between the initial and a resumed dispatch** (same
worktree, so the same path) — resumption is driven by the file's own content (an agent reading a
file with Phase 1 fully checked off naturally continues from the first unchecked phase), not by a
modified or parameterized prompt. Never restart from Phase 1 on a resume; never invent a second
tracking mechanism alongside the checkboxes.

**`.STATUS` auto-write scoping:** at dispatch time, auto-write only the factual fields to the
Active Worktrees entry — branch name, worktree path, and PR link once one is opened. All of that
data already exists at dispatch time; no new logic is needed to produce it. The narrative/purpose
prose column stays manual — do not attempt to auto-generate it (auto-generated prose reads worse
than hand-written, per this skill's own `.STATUS` history).

**Model selection for the dispatch (distinct from `workflow-engine`'s per-stage routing):**
default to omitting `model` — the dispatched agent inherits the session's default tier, correct
for a fully-specified, mechanical ORCHESTRATE file. This is a **whole-dispatch** choice, not the
same knob as `skills/orchestration/workflow-engine/SKILL.md`'s "Model Routing (Haiku for cheap
stages)" section, which governs individual reasoning *stages* inside a multi-stage run and says to
omit `model` for architecture/cross-file-reasoning stages specifically — that rule is about
per-stage cost tuning within an already-running pipeline, not about this one-shot dispatch prompt.
Pin `model: "opus"` here only when the ORCHESTRATE file's own Phase notes flag an unresolved
design judgment call for the dispatch as a whole (e.g. a Phase scoped as "pick the lower-friction
option, document the choice") — not as a blanket default for `orchestrate-dispatch`.

### 2. Feature Plan (`plan:feature`)

**Trigger:** "plan feature", "break down", "scope this feature".

**Output:** user stories → task tree grouped by layer (backend/frontend/infra) → time estimates → dependencies → risks → acceptance criteria → total estimate.

**Options:** `--scope mvp|full|enterprise`, `--format markdown|jira|github`, `--include-tests`, `--output <file>`.

### 3. Sprint Plan (`plan:sprint`)

**Trigger:** "plan sprint", "next sprint", capacity/duration mentions.

**Flow:** gather backlog → prioritize → fit to capacity → name sprint goal → commit + stretch items → highlight dependencies and risks.

**Options:** `--duration <days>` (default 14), `--capacity <hours>`, `--goal <text>`, `--from github|jira`.

### 4. Roadmap (`plan:roadmap`)

**Trigger:** "roadmap", "quarterly plan", "milestone view".

**Output:** phased milestones with progress bars, dependency callouts, timeline gantt-style strip.

**Options:** `--horizon <months>` (default 6), `--format mermaid|markdown|html`, `--output <file>`, `--update` to refresh existing roadmap.

## ORCHESTRATE Template (Canonical)

```markdown
# <Topic> — Orchestration Plan

> **Branch:** `feature/<topic>`
> **Base:** `dev`
> **Worktree:** `~/.git-worktrees/<project>/feature-<topic>`
> **Spec:** `<spec-path>`

## Objective
<1-2 sentences from spec>

## Phase Overview
| Phase | Increment | Priority | Effort | Status |

## Phase 1..N: <Name>
**Scope:** ...
- [ ] 1.1 <task>
**Key files:** `<file>` (NEW or update)

## Friction Prevention
- Context first, verify CWD, no autonomous starts, test per phase.

## Acceptance Criteria
- [ ] <from spec>

## Commit Strategy
Conventional commits per phase.

## Verification
<auto-detected test command>

## Session Instructions
cd <worktree-path> && claude
> "Read ORCHESTRATE-<topic>.md and start Phase 1."

(Desktop app, no persistent shell: `EnterWorktree({ path: "<worktree-path>" })` switches the
session's cwd directly instead of opening a new terminal — the worktree already appears in
`git worktree list` since this skill created it.)
```

## Auto-Detection

See [`../references/verify-gate-detection.md`](../references/verify-gate-detection.md) for the
full detection table and how to use it.

### Rebase Strategy (Spec → ORCHESTRATE mode)

Before finalizing the worktree, check whether the base branch (`dev`) has recent automated
commits:

- If the last 5 commits on `dev` include `chore:` or bot commits → suggest a rebase before PR.
- If the history is clean → standard merge workflow, no rebase suggestion needed.

## Cross-Repo Detection

Scan spec for paths under `~/projects/dev-tools/<other>/`. If detected:

- Primary repo + secondary repo(s) listed.
- Same branch name (`feature/<topic>`) enforced across all worktrees.
- Generate paired worktrees on confirmation.

## ADHD-Friendly Outputs

- Visual hierarchy: headers, tables, progress bars, checkboxes.
- Quick-wins vs long-term clearly labeled.
- Numbered next steps at end of every artifact.
- Total estimate always surfaced (no "TBD" without a placeholder).

## Integration

| With | How |
|------|-----|
| `task-analyzer` | Receives a routed task that needs a plan artifact. |
| `session-state` | Plans persist into orchestrator session state. |
| `project-planner` | Strategic advice upstream; this skill writes the file. |
| `dev/git` skill | Creates the worktree for ORCHESTRATE mode (ask naturally, e.g. "create a worktree for feature-x"). |
| `/craft:orch` | Launches orchestrator after plan exists. |
| `/folio:docs:sync` | Refreshes roadmap docs on `--update` (moved to folio). |

## Test-plan scaffolding (default-on)

When this skill emits an ORCHESTRATE artifact, it also emits a test-plan scaffold **by default**. Pass `--no-tests` to suppress the section.

### Tier-inference rule

Infer tiers from the shape of the artifact/change being planned:

| Change shape | Tiers to emit |
|---|---|
| Flag / frontmatter / prose only | `e2e` + `dogfood` |
| + new parser or script | + `unit` |
| + cross-command data flow | + `integration` |
| + external dependency change | + `dependency` |
| + new command / skill / agent | + `count-cascade` dogfood |

Unselected tiers print as `N/A — <reason>` (never empty stubs).

### Emission rules

- Emit test stubs **red-first** (failing placeholder, not passing no-op).
- Each stub carries `# TODO(author): delete if not contract-bearing` until the author confirms the contract.
- Scaffold templates live in [`../../workflow/brainstorm-insights/references/scaffold-templates.md`](../../workflow/brainstorm-insights/references/scaffold-templates.md); point to that file — do not duplicate templates inline.

### `--yes` non-suppression

`--yes` auto-accepts prompts only; the test-plan and Documentation sections are CONTENT and are still emitted under `--yes`. Only `--no-tests`/`--no-docs` remove them.

### Opt-out

`--no-tests` suppresses the entire test-plan section. Default is **on**.

## Documentation scaffolding (default-on)

When this skill emits an ORCHESTRATE artifact, it also emits a Documentation section **by default**. Pass `--no-docs` to suppress the section.

### Which docs to emit

Derive which documentation artifacts are needed by running the existing doc-scorer rubric from [`skills/orchestration/references/doc-impact-rubric.md`](../references/doc-impact-rubric.md) (tiered thresholds — see that file for the current type list, per-type weights, and threshold rule). Do **not** invent a new rubric, and do **not** hardcode a parallel type list here — always defer to that file as the single source of truth for which types exist and what their thresholds are.

For each doc type the scorer evaluates, pre-check (`[x]`) boxes that meet that type's threshold, and mark the rest `N/A — score <N>`. The template for the Documentation section — including the Site Consistency checklist — lives in [`../../workflow/brainstorm-insights/references/scaffold-templates.md`](../../workflow/brainstorm-insights/references/scaffold-templates.md).

### Lifecycle split

| Phase | Action |
|-------|--------|
| **Spec-time** | Read-only emit + pre-derive: render the Documentation section with pre-checked boxes. No file edits. |
| **Impl/post-merge** | Real edits via `/craft:docs:update --post-merge`. Diff-confirm gated before applying. |

### Count-cascade exclusion

Auto-docs emission touches **only semantic docs** — CHANGELOG `[Unreleased]` ×2 mirror, guide/refcard/tutorial prose. It **never** touches version or count lines. Version/count updates stay in `bump-version.sh`.

### Opt-out

`--no-docs` suppresses the entire Documentation section. Default is **on**.

## Common Pitfalls

- **Writing ORCHESTRATE to the main repo** — always worktree root.
- **Auto-starting implementation** after generating ORCHESTRATE — STOP; new session required.
- **Generating spec from brainstorm silently** — offer `/brainstorm s` instead; let user capture spec interactively.
- **Overwriting existing ORCHESTRATE without confirmation** — detect and ask before regenerating.
- **Cross-repo branch name drift** — enforce identical `feature/<topic>` across paired worktrees.

## Example Invocations

```
"Generate ORCHESTRATE from docs/specs/SPEC-auth-2026-02-15.md"
"Break down 'avatar upload' as MVP-scope feature plan"
"Plan a 7-day sprint, 40 hours capacity, goal: ship OAuth"
"Generate quarterly roadmap as mermaid, save to ROADMAP.md"
```