Utility Pm Workflow Orchestrator

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->

PM Workflow Orchestrator (Dispatch Skill)

Cross-client dispatch wrapper for the pm-workflow-orchestrator sub-agent. Detects the runtime; dispatches to the native sub-agent on Claude Code; reads agents/pm-workflow-orchestrator.md and walks the run loop inline on non-Claude clients via the "reference + execute inline" pattern. The orchestrator runs an ordered sequence of pm-skills from a saved prioritized-action-plan (Mode A) or a user-named chain (Mode B), pausing for go/no-go by default and stopping on a failed or empty step.

Status summary (updated v2.26.0): smoke-tested on the native Claude Code path; EXPERIMENTAL elsewhere.

- Claude Code (native): Mode B chains SMOKE-TESTED PASS (2026-06-10, installed plugin). The live run confirmed the engine invokes downstream skills via the Skill tool and that they execute INLINE in the engine's context (the Skill tool injects the target SKILL.md into the caller's context; no sub-agent is spawned), with real artifacts produced and the checkpoint pause honored. Mode A native runs and a single continuous interactive engine instance across multiple checkpoints have not yet been exercised; details and caveats in the compatibility matrix's v2.26.0 smoke-gate record.

- All non-Claude clients (Codex CLI, Cursor, Windsurf, Copilot CLI, Gemini CLI): EXPERIMENTAL until a dedicated maintainer-gate test exercises a real multi-artifact inline WRITE run. The orchestrator writes up to three full PM artifacts and may thread state; this is strictly harder than the conductor's inline path and has never been live-validated off Claude Code.

>

On ANY client, run --dry-run FIRST as the readiness check (it exercises parsing, checkpointing, stop-on-fail, and the tool-capability pre-flight without invoking consequential skills). See the Sub-Agent Compatibility Matrix for the canonical safe-usage matrix.

When to Use

• You produced a foundation-prioritized-action-plan and want to run its runnable Section 7 prompts in order, pausing for go/no-go (Mode A).
• You want to run an ad-hoc, user-named chain of pm-skills against shared context (Mode B), for example deliver-prd then deliver-user-stories. On Claude Code, the /chain command is the terse front door for this mode.
• You want a generic runner for a dynamic chain that is NOT a pre-curated workflow-* command.

Run modes (orthogonal to client):

• CHECKPOINTED (default): pause after each OK step for approve / edit / skip / redo.
• GUARDED AUTO (`--auto`, opt-in): run without pausing on clean steps; still stop on failed, pause on empty, and stay checkpointed for Complex / Chaotic plans unless --force-auto.

--thread declares a linear dependency so each step receives the prior step's confirmed artifact; see the Mode B Chain Expression Contract in references/PARSE-CONTRACT.md.

When NOT to Use

• You want a fixed, curated, named chain that an author maintains by hand (for example a full Foundation Sprint or Customer Discovery) -> use the existing workflow-* command (workflow-foundation-sprint, workflow-customer-discovery, ...). The orchestrator does NOT supersede those and surfaces a workflow step as MANUAL rather than nesting it.
• You only need to PRODUCE a prioritized action plan (not run it) -> use foundation-prioritized-action-plan (which can then offer to hand its plan here).
• You only need to review one artifact -> use utility-pm-critic.
• You want to run library-maintenance machinery as if it were PM work -> the orchestrator refuses Tier-3 maintenance skills.

Instructions

Runtime detection step. Determine which AI client is invoking this skill. Run mode (checkpointed vs auto) comes from the user's flags and is independent of the client.

If you are running in Claude Code with the pm-skills plugin installed

Invoke @agent-pm-skills:pm-workflow-orchestrator with the user's input plus any flags from $ARGUMENTS (--auto, --force-auto, --dry-run). The native sub-agent parses the input, builds the step list, and delegates each step via the Skill tool to the real downstream skill, running its own per-step loop with confirmation pauses. Relay the engine's per-step output blocks and the terminal output to the user.

This path is EXPERIMENTAL at v2.24.0 (see Status summary). Instruct the user to run --dry-run first.

If you are running in any other AI client

Codex CLI, Cursor, Windsurf, Copilot CLI, Gemini CLI, or any client without native pm-skills plugin sub-agent support:

1. Tool-capability pre-flight (FIRST action, before parsing or step 1). Verify the client can (a) write a file under _pm-skills/plan-orchestrator/<run>/ and (b) run any Bash a downstream skill needs.

• If file write is unavailable: degrade explicitly to CHAT-ONLY mode (warn that multi-step reliability drops and context budget rises because full artifacts must stay in-window) for short runs, or refuse a long run with a clear message. Do not fail mid-chain.
• If Bash is unavailable for a step that needs it: surface that step as blocked at its boundary.
• Record the detected capabilities; they govern disk-write below.

2. Read the canonical sub-agent definition at agents/pm-workflow-orchestrator.md. 3. Read the shared parse and step-status contract at references/PARSE-CONTRACT.md (the engine reads the same file; this is what keeps the inline branch and the engine from drifting). 4. Execute the engine body as your operating instructions: run the pre-flight refusals, build the ordered step list (Mode A parse or Mode B named chain), then walk the per-step loop. 5. At each step, read the downstream skill's SKILL.md and execute its method inline in this window; classify the return PRODUCED / EMPTY / FAILED with the rubric in references/PARSE-CONTRACT.md; write NN-<skill-name>.md to the run directory when disk-write is on. 6. Honor the run mode: pause at each OK step in CHECKPOINTED; auto-advance only unambiguously-PRODUCED steps in GUARDED AUTO; a FAILED step STOPS the run; an EMPTY or ambiguous step always pauses for confirmation (a forced checkpoint pause the user can clear), regardless of --force-auto. 7. Emit the terminal output (run complete or halted) per the engine's section 4.5.

The "reference + execute inline" pattern is what enables cross-client compatibility. It is EXPERIMENTAL here until the maintainer-gate WRITE harness validates a real multi-artifact run on each client.

--dry-run (readiness probe; run this FIRST on any client)

--dry-run walks the full step list and exercises parsing, checkpointing, stop-on-fail, and the tool-capability pre-flight, but does NOT invoke any consequential downstream skill. Each step emits "NOT EXECUTED - dry run" plus what WOULD happen (which skill, which mode, whether disk-write would engage). Use it to confirm the plan parses, the chain resolves, and the client has the tool access the live run needs, before spending tokens on real delegation.

Cross-Client Notes

Because non-Claude clients run the loop and every step inline in ONE context window:

1. Context budget. The combined budget (engine body + per-step downstream skill reads + produced artifacts) can approach context limits on multi-step runs. The engine auto-enables disk-write for 2+ step runs and keeps only a one-line summary per completed step in context; CHAT-ONLY mode loses that mitigation, so prefer a write-capable client for long chains. 2. Tool authorization. Inline execution must have file-write and Bash access (not Read-only). The pre-flight (step 1 above) checks this. Codex may need its sandbox write flag enabled; Cursor and Gemini may interpose approval gates per step. 3. No native chaining. This is why the engine delegates by Skill (Claude Code) or inline read-and-execute (non-Claude), never by spawning a sub-agent. A Mode A step that resolves to a dispatch skill which would fan out to a sub-agent (only utility-pm-critic) is handled by inlining the leaf agent, never by chaining (engine section 7.2).

Reference Files

• Canonical sub-agent definition: `agents/pm-workflow-orchestrator.md`
• Shared parse and step-status contract: references/PARSE-CONTRACT.md
• Output template: references/TEMPLATE.md
• Worked example: references/EXAMPLE.md
• Producer (hands plans here in HANDOFF mode): `skills/foundation-prioritized-action-plan/SKILL.md`
• Sub-agent compatibility matrix: `docs/reference/sub-agent-compatibility.md`
• Runtime components catalog: `docs/reference/runtime-components.md`
• Library sample (single checkpointed run): `library/sub-agent-samples/pm-workflow-orchestrator/`

utility-pm-workflow-orchestrator - Version History

1.1.0 (2026-06-10)

• Documented the Mode B chain expression grammar (references/PARSE-CONTRACT.md) and the /chain command front door.
• Named the user-declared dependency flag --thread.
• Completion output now suggests promoting a reusable 2+ step chain to utility-pm-workflow-builder.
• Description rewritten to lead with triggers and boundaries; client-routing mechanics stay in the body.

1.0.0 (2026-06-01)

• Initial release with v2.24.0: cross-client dispatch for Mode A (saved prioritized action plan) and Mode B (user-named chain) runs.

Example: pm-workflow-orchestrator Dispatch on Claude Code (Mode A, checkpointed)

This example shows utility-pm-workflow-orchestrator running a saved foundation-prioritized-action-plan (Mode A) on Claude Code, where the skill dispatches to the native @agent-pm-skills:pm-workflow-orchestrator sub-agent. The run is CHECKPOINTED (the default): the orchestrator pauses after each OK step and the user approves before it advances. It ends in a clean "Plan run complete" block.

This is the same worked run carried by the library sample at library/sub-agent-samples/pm-workflow-orchestrator/. Because a FAILED step HALTS the run and an EMPTY step pauses rather than silently advancing, neither can appear in a run that ends in "Plan run complete." A FAILED or EMPTY demonstration is a SEPARATE halted-run sample; this example is the clean approve-all path only.

Invocation

> /utility-pm-workflow-orchestrator _pm-skills/plans/storevine-q3-action-plan.md

Skill behavior

1. Runtime detection. Detects Claude Code with the pm-skills plugin installed; takes the native-dispatch branch. 2. Native dispatch. Invokes @agent-pm-skills:pm-workflow-orchestrator with the plan path and no flags (so the default CHECKPOINTED run mode applies). 3. Engine parses + walks the loop. The sub-agent parses Section 7 of the plan into an ordered step list per references/PARSE-CONTRACT.md, delegates each runnable step via the Skill tool, surfaces one MANUAL block, and pauses at each OK boundary for the user's go/no-go. The dispatch skill relays the engine's per-step blocks and the terminal block to the main chat.

Output (relayed verbatim from the engine)

Plan run: storevine-q3-action-plan

Input mode: A (saved prioritized-action-plan) Client + mechanism: Claude Code, native sub-agent Run mode: CHECKPOINTED (default) Disk-write: on (_pm-skills/plan-orchestrator/2026-06-01-storevine-q3/) Steps resolved: 3 runnable, 1 manual Cynefin domain: Complicated Overall plan confidence: Medium-High - converging interview and analytics signal on the activation gap, thinner data on pricing sensitivity.

---

Step 1 of 3: deliver-prd (Considered effort)

Delegation: Skill tool Result: PRODUCED Drafted a PRD for the guided-onboarding revamp: problem framing, two in-scope flows, success metrics tied to the activation gap, explicit out-of-scope list. Written to _pm-skills/plan-orchestrator/2026-06-01-storevine-q3/01-deliver-prd.md.

Step status: OK

Approve, edit, skip, or redo? Reply to advance to Step 2.

User: approve

---

Step 2 of 3: deliver-user-stories (Standard effort)

Delegation: Skill tool Result: PRODUCED Generated 9 user stories with acceptance criteria from the PRD scope, grouped by the two onboarding flows, each with a happy-path plus at least one error-state criterion. Written to 02-deliver-user-stories.md.

Step status: OK

Approve, edit, skip, or redo? Reply to advance to Step 3.

User: approve

---

Step (manual): workflow-customer-discovery

Delegation: manual (no skill) Result: SKIPPED-MANUAL The plan named a full Customer Discovery workflow as a prompt. The orchestrator does NOT nest curated workflow-* commands; it surfaces this as a manual step for the user to run directly. This manual block does NOT consume a top-3 runnable-cap slot.

Step status: OK (surfaced; nothing executed)

Noting and continuing to the next runnable step.

---

Step 3 of 3: deliver-launch-checklist (Considered effort)

Delegation: Skill tool Result: PRODUCED Produced a pre-launch checklist across engineering, design, support, and marketing readiness for the onboarding revamp, with owners and open-items flagged. Written to 03-deliver-launch-checklist.md.

Step status: OK

Approve, edit, skip, or redo? Reply to finish the run.

User: approve

---

Plan run complete: 3 of 3 steps

Manual steps (surfaced, not run):

• workflow-customer-discovery: run the curated workflow command directly when ready.

Next steps:

• Deferred P4-P5 actions from the source plan (not in the top-3 cap): pricing-sensitivity experiment, beta-cohort recruiting.
• Optional: run utility-pm-critic on any produced artifact to review it.

Notes on This Example

This is the canonical clean-path narrative for the orchestrator: a single-thread CHECKPOINTED Mode A run that the user approves at every step.

1. Three runnable steps, one manual. The cap counts only the three skill-bearing blocks; the workflow-customer-discovery manual block is surfaced and skipped, not nested, and does not occupy a cap slot. 2. Confirmation pauses. The engine pauses after each OK step and only advances on the user's reply. In GUARDED AUTO (--auto) it would advance clean steps without pausing, but would still stop on an EMPTY or FAILED step. 3. Disk-write engaged. Because the run has 2+ steps, disk-write auto-enabled and each artifact landed under the run directory; only a one-line summary per step stays in context. 4. Ends in "Plan run complete." No step was EMPTY or FAILED, so the run reached the run-complete terminal block. Any failure or empty result would have produced the separate "Plan run halted" block instead.

At v2.24.0 this native path is EXPERIMENTAL until the Skill-from-sub-agent smoke test closes; run --dry-run first as the readiness check.

Related Files

• Canonical sub-agent: `agents/pm-workflow-orchestrator.md`
• Skill manifest: SKILL.md
• Output template: TEMPLATE.md
• Shared parse + step-status contract: PARSE-CONTRACT.md
• Producer: `skills/foundation-prioritized-action-plan/SKILL.md`
• Library sample (same run): `library/sub-agent-samples/pm-workflow-orchestrator/`

Parse + Step-Status Contract

This is the shared contract that BOTH the pm-workflow-orchestrator sub-agent (agents/pm-workflow-orchestrator.md) and the dispatch skill's non-Claude inline branch (skills/utility-pm-workflow-orchestrator/SKILL.md) read at runtime. It exists so the parse rules and the step-status rubric live in exactly ONE place. Neither the engine prompt nor the inline branch restates these rules; both link here. The file is authored under this skill's references/ tree but is owned conceptually by the engine.

The rules below are grounded against three real files already on main, cited inline so they can be re-verified:

• skills/foundation-prioritized-action-plan/examples/02-interview-transcript.md (a real compound heading #### To execute P1 and P2: design the probes as experiments).
• skills/foundation-prioritized-action-plan/examples/03-executive-ask.md (two P1 sibling prompts under a Complex domain rendered **Domain:** Complex. **Source:** S2, S3, S6, S7.).
• skills/foundation-prioritized-action-plan/references/EXAMPLE.md (Complicated domain, Overall plan confidence: Medium-High, #### To execute P1 then #### To execute P3 with no P2).

Mode A Section 7 Parse Contract

Section 7 of a foundation-prioritized-action-plan is the runnable prompt list. Parse it as follows:

• Anchor on the prefix `#### To execute ` (trailing space), NOT on #### To execute P<n>:. The text after the prefix varies (a P-token set, then a colon and a human title), so anchoring on the full P<n>: form misses compound and titled headings.
• Capture the block as everything from the anchor heading to the next #### or ## heading (whichever comes first).
• Parse the P-token as a SET, not a single token. Use the regex P\d+(?:\s+and\s+P\d+)*. A heading like #### To execute P1 and P2: design the probes as experiments yields the set {P1, P2} for ONE block. Sibling prompts that each carry the same token (two separate P1 headings) are TWO separate blocks, never threaded together.
• Treat Section 7 as an ORDERED LIST of prompt blocks, in document order. It is never a P-keyed map: P-tokens can repeat, can be compound, and can skip numbers (P1 then P3 with no P2). Order on the page is the order of execution.
• Classify each block:
• RUNNABLE: the block names a real pm-skill the orchestrator can delegate to or inline.
• MANUAL: the block names no skill, or names a curated workflow-* command (which the orchestrator surfaces as manual rather than nesting). Manual blocks are listed and skipped, never executed.
• PARSE ERROR: the block cannot be classified (malformed heading, missing prompt body). Report it; do not guess.
• Capture the prompt body as everything after **Prompt:**, stripping a single leading > from each quoted line.

Top-3 Runnable Cap

• The cap counts RUNNABLE blocks in document order. The first three RUNNABLE blocks are in scope; later runnable blocks are deferred (P4-P5) and reported in the terminal output, not run.
• MANUAL blocks are listed separately and do NOT consume a cap slot. A run can surface any number of manual blocks plus up to three runnable steps.
• The cap is an UPPER BOUND, not a target. A plan with one runnable block runs one step; the orchestrator does not pad to three.

Cynefin Domain Extraction (Mode A)

• Match **Domain:** on the Section 2 line. Scan the remainder of that line for the FIRST whole-word enum token: Clear, Complicated, Complex, or Chaotic, case-insensitive.
• Tolerate a trailing period and an inline **Source:** clause: from **Domain:** Complex. **Source:** S2, S3, S6, S7. the extracted token is exactly Complex (not Complex.).
• Fallback: if Section 2 has no usable **Domain:** line, read the Section 0 **Situation classification:** bullet.
• Zero or ambiguous match: report it and default the run to CHECKPOINTED. Never guess a domain.
• The domain is SURFACED in the run header. In v2.24.0 it informs the GUARDED AUTO guardrail (Complex / Chaotic plans stay checkpointed unless --force-auto) but does not otherwise gate the run.

Overall Plan Confidence Extraction (Mode A)

• Parse the Overall plan confidence value tolerantly. Accept single tokens (High, Medium, Low) and hyphenated compounds (Medium-High, Medium-Low, Low-Medium), optionally followed by - <reasoning>.
• Capture the reasoning clause after - when present, for the run header.
• Confidence is SURFACED in the run header only. It does NOT gate autonomy in v2.24.0.

Step-Status Rubric

Classify every executed step into exactly one of three states. This rubric is what the inline branch and the engine both apply, so a step is judged identically regardless of mechanism.

• PRODUCED: a non-trivial artifact that populates the expected structure of the target skill's output. This is the only PASS state.
• EMPTY: no artifact, OR a bare stub where the target skill's references/TEMPLATE.md ## sections appear only as unfilled [ bracketed guidance ]. EMPTY is NEVER a PASS; an EMPTY step pauses for confirmation - a forced checkpoint pause in CHECKPOINTED, and likewise a forced checkpoint pause (never an auto-advance, never a hard halt; the user can clear it) in GUARDED AUTO - and never silently advances to completion.
• FAILED: the step errored, the target skill refused, or the return carries an explicit error string. A FAILED step HALTS the run; it never advances.

A SKIPPED-MANUAL block is not an executed step and is not run through this rubric: it is surfaced, listed, and the loop continues to the next runnable step.

Self-Reference Refusal

A Mode A plan or a Mode B chain that names utility-pm-workflow-orchestrator or foundation-prioritized-action-plan as a step is REFUSED. The orchestrator does not run itself, and it does not run its own producer as a step (the producer hands plans IN; it is not a step the orchestrator runs OUT). Report the refusal at the offending step's boundary; do not silently drop the step.

Mode B Chain Expression Contract

A Mode B chain may arrive as prose ("run deliver-prd then deliver-user-stories") or as a chain expression (the /chain command's input form). The expression grammar:

• Steps: an ordered list of skill names separated by , or ->. The two separators are

equivalent and may be mixed. Order on the line is execution order.

• Boundary (separator-driven): the chain expression is exactly the separator-joined list:

it ends after the first step token that is NOT followed by a separator. Everything after that is the shared context, even when the context words look like skill names (the boundary comes from separators, never from token shape). A separator PROMISES another step: a trailing separator with nothing resolvable after it is a parse refusal, surfaced plainly, never guessed around.

• Flags: --auto, --force-auto, --dry-run, and --thread may appear anywhere in the

input; extract them before parsing steps and apply them per the engine's run-mode rules.

• Context: everything after the chain expression (per the boundary rule above) is the shared context handed to every step.
• Name resolution: each step must exactly match an installed skill

(skills/<name>/SKILL.md). Name-safety applies: never approximate or auto-correct. On any miss, refuse the WHOLE run pre-flight and OFFER the closest real names (for example prd -> "did you mean deliver-prd?"). A suggestion is an offer, never a substitution.

• `--thread` (user-declared linear dependency): opt-in. With --thread, step N+1 receives a

reference to step N's confirmed artifact, per the engine's user-declared dependency rule. Without it, every step is self-sufficient given the shared context. --thread covers the whole chain; per-step threading granularity does not exist in v1.

• Unchanged rules (cross-references, not duplicates): the self-reference refusal above and

the engine's Tier-3 maintenance refusal; Mode B skill resolution and the Category 1/2/3 routing rule in agents/pm-workflow-orchestrator.md; no top-3 cap in Mode B, with the context-budget warning past 3 steps; GUARDED AUTO degrades to CHECKPOINTED for Mode B unless --force-auto.

Reference Files

• Canonical sub-agent: `agents/pm-workflow-orchestrator.md`
• Output template: TEMPLATE.md
• Worked example: EXAMPLE.md
• Producer + parse fixtures: `skills/foundation-prioritized-action-plan/`

Output Template

utility-pm-workflow-orchestrator streams output as it walks the step list: a run header first, then one per-step block per step (with a confirmation pause between OK steps in CHECKPOINTED mode), then exactly one terminal block. Dry-run mode replaces step execution with a readiness summary. Authoring notes in [ brackets ] are guidance: fill them in or delete them, and do not ship bracketed placeholders in a real run.

Run Header

````markdown

Plan run: {Mode A: <plan name> | Mode B: <named chain>}

Input mode: A (saved prioritized-action-plan) | B (user-named chain) Client + mechanism: {Claude Code, native sub-agent | <client>, inline execution} Run mode: CHECKPOINTED (default) | GUARDED AUTO Disk-write: on (_pm-skills/plan-orchestrator/<run>/) | off (CHAT-ONLY) Steps resolved: {N} runnable, {M} manual

{Mode A only, surfaced not gating:} Cynefin domain: {Clear | Complicated | Complex | Chaotic | undetermined -> CHECKPOINTED} Overall plan confidence: {High | Medium-High | Medium | Medium-Low | Low | Low-Medium - <reasoning>} ````

Per-Step Output

The section 4.2 block, emitted once per step:

````markdown

Step {i} of {N}: {skill-name or "manual"} ({effort name})

Delegation: {Skill tool | inline execution | manual (no skill)} Result: PRODUCED / EMPTY / FAILED / SKIPPED-MANUAL {one-line summary of the artifact, or the failure/refusal narrative}

Step status: OK / STOP / WAITING-FOR-CONFIRMATION

{If OK + checkpointed:} Approve, edit, skip, or redo? Reply to advance to Step {i+1}. {If STOP:} Halting. Resolve before re-invoking:

• {blocker}

````

A MANUAL step is surfaced as its own block (Delegation: manual (no skill), Result: SKIPPED-MANUAL) and does NOT consume a top-3 runnable-cap slot.

Terminal Output - Run Complete

````markdown

Plan run complete: {N} of {N} steps

Manual steps (surfaced, not run):

• Step {k}: {what the user runs by hand, e.g. a workflow-* command}

Next steps:

• Deferred P4-P5 actions from the source plan (not in the top-3 cap): {list or "none"}
• Optional: run utility-pm-critic on any produced artifact to review it.

````

Terminal Output - Run Halted

````markdown

Plan run halted at Step {i} of {N}

Stop reason: {EMPTY step | FAILED step | refusal | tool-capability blocker} Detail: {the failure / refusal narrative}

Completed steps:

• Step 1: {skill-name} PRODUCED -> {path or in-chat}
• ... (through Step {i-1})

Resume guidance: there is no auto-resume in v1. Resolve the blocker, then re-invoke the skill to restart the run. Persisted artifacts under _pm-skills/plan-orchestrator/<run>/ are for manual reference only. ````

Dry-Run Output

````markdown

Dry run: {Mode A: <plan name> | Mode B: <named chain>}

Per step:

• Step {i} of {N}: {skill-name or "manual"} - NOT EXECUTED - dry run

WOULD: delegate via {Skill tool | inline}; run mode {checkpointed | auto}; disk-write {would engage | CHAT-ONLY}.

Readiness summary:

• Parse: OK | {parse error detail}
• Chain resolved: {N} runnable, {M} manual | {unresolved skill name}
• Tool-capability: file-write {available | unavailable}, Bash {available | unavailable}

Recommended next step: if readiness is clean, re-invoke without --dry-run to run live. ````

Reference Files

• Canonical sub-agent: `agents/pm-workflow-orchestrator.md`
• Shared parse + step-status contract: PARSE-CONTRACT.md
• Worked example: EXAMPLE.md