apxm-workflows

name	apxm-workflows
description	Use when work is multi-step, long-running, side-effecting, approval-gated, or must survive a coding-host session and remain observable through APXM.

APXM Workflows

Use APXM when the work needs durable execution, typed admission, resumable events, explicit approvals, or a run that remains alive after the coding host disconnects. Keep quick, read-only reasoning in the current session.

Start

1. Resolve PLUGIN_ROOT as the directory two levels above this skill.
2. Run the readiness check:

python3 "$PLUGIN_ROOT/scripts/apxm_doctor.py"

3. Confirm that the apxm MCP server advertises the operation needed for the run. Missing tools are unavailable; do not substitute shell backgrounding or a second client-owned scheduler.
4. Read references/operations-and-tools.md for the generated catalog snapshot.

Route work to APXM

Choose APXM when at least one of these is true:

• the work spans dependent steps or repositories;
• execution must continue after the current host session ends;
• a tool call requires an APXM capability grant or signed approval;
• the caller needs cancellation, retained events, replay, or a stable run id;
• the workflow must be compiled and admitted before side effects.

Keep the work in-session when it is a bounded read or a small edit whose lifetime and verification fit entirely inside the current coding-host turn.

Execution flow

1. Author with the supported Python or TypeScript frontend, a workflow draft lowered by a frontend, canonical AIR, or an existing .apxmw manifest.
2. Validate before execution. Compile when the selected surface requires an artifact.
3. Start the admitted run once. Record the returned execution and session ids.
4. Follow retained events or task status. Do not create a second polling loop that owns APXM state.
5. Route side-effecting permission prompts through APXM consent. A coding-host confirmation does not replace the APXM approval record.
6. On interruption, reattach by the returned id and resume through the public status/event surface.
7. Report the run id, trace id, validation result, approval outcome, artifacts, final status, and any replay gap.

Safety and ownership

• APXM Server owns admission, execution state, session state, and retained run events.
• APXM OS owns external delivery, retries, and dead letters.
• Auth owns credentials; plugin configuration contains environment-variable names only, never token values.
• This skill is a client. It must not duplicate runtime ledgers, capability policy, scheduler state, or transport-specific admission rules.
• If the required MCP tool or process is unavailable, return setup_required or unavailable with the failed check. Never report a synthetic success.

Result

Return: status, validated, admitted, execution_id, session_id, trace_id, approval, artifacts, event_cursor, replay_status, verification, warnings, and next_action.