| name | metaproc |
| description | Route Metaproc process launches, resumes, monitoring, and supervision through its CLI and bundled manuals. Use when running `metaproc run-process` or `metaproc run-step`, supervising a run, or deciding whether orchestration belongs in Metaproc. Read `metaproc help operator` before operating a run. |
| allowed-tools | Bash(metaproc:*) Read |
Metaproc Orchestration Patterns
This skill routes orchestration work to Metaproc’s bundled manuals and CLI. It does not
restate the manuals.
Before you run, monitor, resume, or debug a Metaproc process, read the operator manual:
metaproc help operator
The operator manual covers how to start, monitor, resume, and stop runs; the status,
trace, pool, tail, and stats commands; the runtime layout; and the operating
rules. If you do not know how to do something with metaproc, the answer is in
metaproc help operator or metaproc <command> --help. Check those sources before
improvising.
metaproc help developer covers extending metaproc and the “metaproc is the
wrapper” policy; metaproc help concepts covers the process model (composite mode,
fan-out, step fingerprints, the resume model).
The full topic list is at the end of this skill.
Do Not Improvise Around Metaproc
The most common failure mode is an agent that skipped the operator manual and hand-rolls
what metaproc already does:
- Do not inspect a run with ad hoc shell commands such as
ls, tail, find,
grep, or jq over the run directory, .state/, or .logs/. Use metaproc status,
wait, tail, pool, trace, stats, auth usage, or gcp. The operator
manual’s Monitoring Commands table maps every question to its command (Operating
Rule 1). A monitoring question that seems to need raw bash is the signal to add or fix
a metaproc command, not to write a script.
- Do not wrap metaproc in a Python or shell orchestrator.
A multi-step flow is a
*.process.md; a new run-state view is a metaproc
subcommand. See metaproc help developer.
- Env hygiene for long runs (
env -u ANTHROPIC_API_KEY; wrapper log on persistent
storage, never /tmp/; caffeinate): see metaproc help operator and the
repository’s docs/conventions.md.
When to Invoke
- Launching or resuming a
metaproc run-process (a composite-parent batch or any
process)
- Running a single step in isolation via
metaproc run-step
- Arming autonomous supervision with
metaproc pulse
- Deciding whether new functionality belongs in metaproc, a workflow helper, or a skill
Workflow-specific skills (such as the large workflow-batch skill) delegate here for the
kickoff sequence and defer to the metaproc CLI for execution.
Kickoff Sequence: Preflight → Confirm → Launch → Supervise
- Preflight. Run the workflow’s preflight step alone to surface a GO/WARN/NO-GO
before committing the full batch:
metaproc run-step <process.md> --step <preflight-step> --wait --var RUN_ID=<id> ....
The non-obvious part this sequence relies on: the completed step is recorded in the
run dir, so the later metaproc run-process (same RUN_ID) sees it done via its
fingerprint and resumes past it (resume model: metaproc help concepts). The
preflight step’s probes and verdict live in the workflow package, not in metaproc.
- Confirm. Present the preflight verdict and kickoff summary through the agent
environment’s user-confirmation mechanism.
Use one gate with no follow-up prompts.
The workflow skill composes the confirmation payload.
- Launch.
metaproc run-process <process.md> --variant <profile> --var ... resumes
past the completed preflight step.
Flags: metaproc run-process --help. Launch each execution profile as a separate
background process; the launch-command shape (env hygiene, wrapper-log piping) is
the workflow playbook’s § Launch Command.
- Supervise. Use the agent environment’s monitoring or scheduling mechanism to run
metaproc pulse <run-dir> and notify you of completion, stalls, or failures without
manual polling. Use the operator manual’s Monitoring Commands for anything pulse
does not cover.
Help Topics
Available via metaproc help <topic>, in recommended reading order:
- concepts (~7.7k words): Start here. Vocabulary, ownership boundaries, step modes, optimization loops.
- design (~17.4k words): How Metaproc is built: spec format, runtime artifacts, adapters, robustness.
- framework (~7.3k words): Background theory: the general model beneath any process framework, and Metaproc's mapping.
- operator (~5.9k words): Runtime CLI reference: running, monitoring, and resuming processes.
- developer (~1.4k words): Extending Metaproc and the 'Metaproc is the right wrapper' policy.
- conventions (~4.6k words): Framework-level naming, structure, and file-format rules.
- artifacts (~1.4k words): Every runtime artifact Metaproc writes or reads: format, schema, lifecycle.
- execution-contracts (~1.9k words): The durable contracts under task-level scheduling, and their rationale.
- credentials (~2.4k words): Configuring credentials for each adapter: Claude, Codex, Gemini, pi, GCP.
- cloud-dispatch (~1.5k words): Preparing, submitting, monitoring, and recovering GCP Batch workloads.
- arch-auth (~8.9k words): Architecture: credential pools, adapter auth modes, and secret handling.
- arch-cloud (~5.5k words): Architecture: GCP Batch dispatch, orchestrator and worker placement.
- arch-runpool (~3.8k words): Architecture: local process manager, adaptive concurrency, memory pressure.
- arch-harness (~2.9k words): Architecture: the Claude Code adapter harness and its wire format.
- arch-execution (~2.6k words): Architecture: the executable reference model for scheduling, as implemented.
- arch-testing (~1.1k words): Architecture: the test tiers, when to use each, and per-adapter credentials.
- arch-file-io (~1.0k words): Architecture: the curated metaproc.io surface and frontmatter gotchas.
