orchestrate

Launch and monitor detached headless pipeline orchestrators for GitHub issues.

Updated Sep 1, 2026
One-click install
npx skills add https://github.com/jpmoya/claude-agents --skill orchestrate-jpmoya
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: orchestrate
Source: https://github.com/jpmoya/claude-agents/tree/main/skills/orchestrate
Command: npx skills add https://github.com/jpmoya/claude-agents --skill orchestrate-jpmoya

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Long-running pipeline orchestrators die when the interactive Claude session that spawned them compacts or exits, leaving GitHub issues half-processed with no recovery. This Skill launches the orchestrator as its own detached claude -p process so it outlives the session, and provides status, restart, and stop controls. ## Core Features & Use Cases - Detached headless launch: Starts the orchestrator via orchestrate.sh with nohup, enforcing one orchestrator per issue and a max of 3 concurrent runs with a memory floor; excess launches are queued automatically. - Supervisor-driven recovery: A cron-ticked supervisor restarts crashed orchestrators with backoff, drains the queue, manages agent-go/agent-in-progress labels, reconciles orphaned labels, and dispatches shared work across machines with a claim protocol. - Status and control: status, tail, stop, and queue subcommands report run state (running, restarting, held, done) from local pid files and issue markers, plus a heartbeat push to a shared status board. - Use Case: Ask to "run the pipeline on issue 547" and the Skill launches a detached orchestrator for that repo and issue, reports the PID and log path, and lets you check progress later without keeping the session alive. ## Quick Start Ask the assistant to orchestrate a specific GitHub issue by number, for example "orchestrate #547 in the scheduler repo", and it will launch the detached pipeline run and report its status.

Frequently Asked Questions about orchestrate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a pipeline orchestrator on a GitHub issue?

Run orchestrate.sh with the repo path and issue number, for example `orchestrate.sh ~/dev/scheduler 547`. The script launches a detached headless claude process, prints the PID and log path, and queues the run automatically if all concurrency slots are full.

How do I check the status of a running pipeline orchestrator?

Run `orchestrate.sh status` to list every recorded orchestrator with its state and latest issue marker, or `orchestrate.sh status 547` for one issue. Use `orchestrate.sh tail 547 40` to view the last 40 lines of its log.

What happens if a headless orchestrator crashes or exits early?

The supervisor cron tick detects the dead process, checks the issue's latest marker, and requeues it with exponential backoff. After 3 restarts without marker progress or 6 total, it posts a note on the issue and parks the run as held for manual intervention.

Can two machines run the orchestrator for the same issue?

No. Launching sets the agent-in-progress label, and the launcher refuses issues carrying that label that it does not own locally. Shared dispatch uses a claim comment with a 15-second settle window so only the earliest claiming machine launches the issue.

Why should the orchestrator not be launched with the Agent tool?

Subagents run inside the parent session and die when it compacts, restarts, or exits, killing the pipeline mid-run. The orchestrate.sh script instead starts the orchestrator as the main agent of its own detached claude -p process, and a hook blocks Agent-tool launches.

How do I stop a running orchestrator and prevent auto-restart?

Run `orchestrate.sh stop <issue>`, which kills the orchestrator process and its claude child, then writes a tombstone file. The supervisor sees the tombstone and will not auto-restart that issue until you relaunch it manually.