metaproc

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

1. 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.
2. 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.
3. 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.
4. 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.