pm-workflow-orchestrator

agents/pm-workflow-orchestrator.md

Status summary (v2.24.0): EXPERIMENTAL on every client at ship.

• Claude Code (native): EXPERIMENTAL until a live smoke test confirms the engine can invoke a downstream skill via the

  Skill

  tool in the installed plugin, and whether that skill runs inline in the engine context or isolated (see the v2.24.0 residual questions). The conductor is the model only for the run-loop / checkpoint / refusal SHAPE; no repo agent has ever declared

  Skill

  , so the mechanism is unproven.
• 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.

• 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

  .
• You want a generic runner for a dynamic chain that is NOT a pre-curated

  workflow-*

  command.

• 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

  .

• 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.

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.

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).

• 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/