.md` - use `AskUserQuestion` only when the user provided neither a spec path nor an inline prompt - invalid spec path must route to `BLOCK` ## Workflow by modifier (authoritative) `GATHER` is the mux-ospec name for `RESEARCH`. - `full`: `CREATE (optional) -> GATHER -> CONSOLIDATE -> SUCCESS_CRITERIA -> CONFIRM_SC -> PLAN -> IMPLEMENT -> REVIEW -> FIX -> TEST -> DOCUMENT -> SENTINEL` - `lean`: `CREATE (optional) -> CONFIRM_SC -> PLAN -> IMPLEMENT -> REVIEW -> FIX -> TEST -> DOCUMENT -> SELF_VALIDATION` - `leanest`: `CREATE (optional) -> CONFIRM_SC -> PLAN -> IMPLEMENT -> REVIEW -> FIX -> TEST -> SELF_VALIDATION` ## Gate and pacing rules - `SUCCESS_CRITERIA` content is required before `CONFIRM_SC` - `CONFIRM_SC` is a mandatory user gate before `PLAN` - only `PASS` advances through `REVIEW`, `TEST`, `SENTINEL`, and `SELF_VALIDATION` - `WARN`/`FAIL` route to `FIX`; retry exhaustion escalates to user - child bridge notifications are delivered automatically; default pacing is notify-first - do not poll pimux or use Bash sleep/wait loops; if you are about to inspect routine progress, stop and wait for delivered child activity instead - after spawn, do not call `status`, `capture`, `tree`, `list`, or `open` on the happy path - terminal settlement re-arms exactly one final `pimux status` verification before advancing - optional watchdog is inactivity-only and concise - default blocked/stuck behavior escalates to user unless explicit override exists ## Stage commit contract (mandatory) Every authoritative stage child MUST commit all changed repos. Signal/report metadata must include: - `repo_scope`: `spec-only` | `root-only` | `root+spec` - `root_commit`: short hash or `N/A` - `spec_commit`: short hash or `N/A` When both repos changed, commit root first, then commit spec through the resolver. ## Child stage contract Each authoritative stage-owning `pimux` child must: - read `../../assets/agents/spec/` stage references needed for that stage - read `../../assets/mux/protocol/foundation.md` and `../../assets/mux/protocol/subagent.md` - read `../../extensions/pimux/docs/patterns.md` - execute only assigned stage scope - preserve evidence-gated reporting with repo-scoped commit metadata - use `pimux report_parent` exactly once for terminal settlement - for same-session parent input needed before continuing, use `report_parent(progress, requiresResponse=true)`; `question` is terminal waiting-on-parent settlement - exit promptly after terminal report Local helpers under the stage child are data-plane only and must not call `pimux` / `report_parent`. ## Completion A stage is complete only after terminal report + child exit. Cross-stage parent advances only after verifying settlement via `pimux status`.

--- name: ac-workflow-mux-ospec description: "pi-adapted mux spec orchestrator. Uses pimux as the authoritative stage runtime while preserving mux-ospec semantics." project-agnostic: true allowed-tools: - pimux - AskUserQuestion - say argument-hint: '[modifier] [spec_path|inline_prompt]' --- # MUX Spec Orchestrator - pi adaptation (pimux runtime) Use this skill to execute explicit spec stages through `pimux` while preserving mux-ospec semantics. ## Binding activation If the user explicitly invokes `mux-ospec` / `ac-workflow-mux-ospec`, or embeds this skill text as the runtime for the task, treat this document as a binding runtime contract, not as optional guidance, commentary, or a planning reference. ## Absolute compliance rule For explicit `mux-ospec` requests in pi, the current session is a `pimux`-only cross-stage orchestrator. - FIRST after spawn: do not poll pimux or use Bash sleep/wait loops; wait for delivered child bridge activity. - The authoritative `pimux` extension applies a fail-closed parent control-plane lock for explicit `mux-ospec` execution. - Before the first child exists, the parent must not call `Read`, `Bash`, `Edit`, `Write`, `NotebookEdit`, `Grep`, `Glob`, `web_search`, `subagent`, or any other non-`pimux` tool for substantive repo work. - Do not execute substantive stage work directly in the parent. - Do not read, grep, or inspect repo files in the parent to figure out implementation details. - The first real move is to spawn the authoritative stage-owning `pimux` child. - The first observable parent tool call must be `pimux spawn`. - If the parent does substantive inspection before spawn, stop, acknowledge protocol violation, discard parent-side conclusions, and restart from `pimux spawn`. ## Parent tool surface While this skill is active, the parent is runtime-locked to `pimux`, `AskUserQuestion`, and `say` only: - before first child: `pimux spawn` only - `AskUserQuestion` is allowed only when the user has not provided an explicit spec path or inline prompt, or when a later required user gate is reached - after spawn: notify-first, not poll-first; wait for delivered child bridge activity instead of inspecting live state - do not poll pimux or use Bash sleep/wait loops; if you are about to inspect routine progress, stop and wait for delivered child activity instead - happy path after spawn forbids `status`, `capture`, `tree`, `list`, and `open`; those are recovery-only tools for explicit live inspection, suspected stall/protocol violation/failure, or the inactivity watchdog - after a child progress report arrives, use at most one `send_message` when the child needs input; then wait for closeout or another child report - `say` is allowed only for short user-attention prompts ## Locked stage model - no-spec invocation starts at Stage `000 CREATE` - then execute explicit named stages by modifier (below) - exactly one direct stage-owning `pimux` child at a time - explicit spec paths pass through unchanged; if the canonical target is missing, the authoritative `pimux` runtime creates it before spawn - when the user provides an inline prompt without a spec path, the authoritative `pimux` runtime auto-derives and creates the next current-branch spec path by following recent current-branch spec-path patterns and the spec-skill convention `.specs/specs////-.md` - use `AskUserQuestion` only when the user provided neither a spec path nor an inline prompt - invalid spec path must route to `BLOCK` ## Workflow by modifier (authoritative) `GATHER` is the mux-ospec name for `RESEARCH`. - `full`: `CREATE (optional) -> GATHER -> CONSOLIDATE -> SUCCESS_CRITERIA -> CONFIRM_SC -> PLAN -> IMPLEMENT -> REVIEW -> FIX -> TEST -> DOCUMENT -> SENTINEL` - `lean`: `CREATE (optional) -> CONFIRM_SC -> PLAN -> IMPLEMENT -> REVIEW -> FIX -> TEST -> DOCUMENT -> SELF_VALIDATION` - `leanest`: `CREATE (optional) -> CONFIRM_SC -> PLAN -> IMPLEMENT -> REVIEW -> FIX -> TEST -> SELF_VALIDATION` ## Gate and pacing rules - `SUCCESS_CRITERIA` content is required before `CONFIRM_SC` - `CONFIRM_SC` is a mandatory user gate before `PLAN` - only `PASS` advances through `REVIEW`, `TEST`, `SENTINEL`, and `SELF_VALIDATION` - `WARN`/`FAIL` route to `FIX`; retry exhaustion escalates to user - child bridge notifications are delivered automatically; default pacing is notify-first - do not poll pimux or use Bash sleep/wait loops; if you are about to inspect routine progress, stop and wait for delivered child activity instead - after spawn, do not call `status`, `capture`, `tree`, `list`, or `open` on the happy path - terminal settlement re-arms exactly one final `pimux status` verification before advancing - optional watchdog is inactivity-only and concise - default blocked/stuck behavior escalates to user unless explicit override exists ## Stage commit contract (mandatory) Every authoritative stage child MUST commit all changed repos. Signal/report metadata must include: - `repo_scope`: `spec-only` | `root-only` | `root+spec` - `root_commit`: short hash or `N/A` - `spec_commit`: short hash or `N/A` When both repos changed, commit root first, then commit spec through the resolver. ## Child stage contract Each authoritative stage-owning `pimux` child must: - read `../../assets/agents/spec/` stage references needed for that stage - read `../../assets/mux/protocol/foundation.md` and `../../assets/mux/protocol/subagent.md` - read `../../extensions/pimux/docs/patterns.md` - execute only assigned stage scope - preserve evidence-gated reporting with repo-scoped commit metadata - use `pimux report_parent` exactly once for terminal settlement - for same-session parent input needed before continuing, use `report_parent(progress, requiresResponse=true)`; `question` is terminal waiting-on-parent settlement - exit promptly after terminal report Local helpers under the stage child are data-plane only and must not call `pimux` / `report_parent`. ## Completion A stage is complete only after terminal report + child exit. Cross-stage parent advances only after verifying settlement via `pimux status`.