orchestrate
Coordinate issues, a specification, or a multi-PR plan to merged pull requests from one chat: dispatch Agent mode workers in worktrees, verify each PR in independent lanes, merge or stack in dependency order, keep the program's memory in files, and report through ketchup. Use for /orchestrate, 'orchestrate', 'deliver these issues', 'take #3 to #12 to main', or resuming or checking on a running program.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- orchestrate
- description
- Coordinate issues, a specification, or a multi-PR plan to merged pull requests from one chat: dispatch Agent mode workers in worktrees, verify each PR in independent lanes, merge or stack in dependency order, keep the program's memory in files, and report through ketchup. Use for /orchestrate, 'orchestrate', 'deliver these issues', 'take #3 to #12 to main', or resuming or checking on a running program.
02 资源文件 6
- 参考文档references/slicing.md2.3 KB
- 参考文档references/stacks.md2.4 KB
- 参考文档references/verification.md9.3 KB
- 参考文档references/worker-brief.md3.6 KB
- 脚本scripts/program.py11.5 KB
- 脚本scripts/test_program.py8.2 KB
03 SKILL.md 正文
Orchestrate
You run the program, never the code. The user talks only to you. You split the work, start workers, check what each one produces, merge, and remember. Workers write the code. Adapted from the pstack Orchestrate and Autopilot-full playbooks for a single local coordinator on a bounded usage plan.
This skill is part of the Agent mode workflow. When the host refuses a skill it names because that skill is user-invoked only, such as ketchup, read its SKILL.md and follow it, per the Skills section of HOST-COMPATIBILITY.md.
A program is one goal and its tasks. Its memory is the program directory, .orchestrate/<slug>/ at the repository root. Your context window compacts and the chat may end, so anything you would need to remember goes into the program directory before you act on it.
.orchestrate/<slug>/
program.md goal, task sources, done predicates, merge policy, the user's rules, gates
tasks.tsv one row per task, owned by scripts/program.py
decisions.tsv the show-me-your-work trail, one row per decision
findings.md problems found on the way and candidate new issues
screenshots/<task-id>/
worktrees/<task-id>/
You are the single writer of program.md, tasks.tsv, decisions.tsv, and findings.md. Workers return facts in their reports and write only their own branch and their own screenshots/<task-id>/ folder (the separate-before-serializing-shared-state principle). Change tasks.tsv only through python3 <skill dir>/scripts/program.py (written program.py below), whose transitions are the task state machine:
queued -> building -> verifying -> merging -> merged
building, verifying, merging -> back to an earlier state for a fix round
any open state -> parked -> queued once the user unblocks it
building refuses a task whose dependencies have not merged, except the one it stacks on. merging refuses a task until every dependency has merged, so stacks merge bottom-up.
Authority
Invoking this skill with a delivery goal ("merged on main") is the user's explicit request for every PR and merge inside the program's task list. program.md records the merge policy the user chose: merge (default) or stop-at-verified, where you hand over verified green PRs and the user merges. The request covers nothing outside the task list.
Stop and ask only at a gate: a schema migration, a public contract change, authentication or permissions, a product call the specification does not settle, an irreversible action, a task parked after two failed attempts, or a task parked with its fix budget spent. program.md lists any extra gates the user named. Rebases, retries, flaky CI, review fixes, and "should I continue" are yours to settle (the never-block-on-the-human principle).
1. Open or resume the program
Restate the user's goal in your own words.
- Resume when
.orchestrate/<slug>/exists. Readprogram.md, runprogram.py show, read the last rows ofdecisions.tsv. Reconcile every open task with live state:gh pr viewandgh pr checksfor its PR,git branch -rfor its branch. Live state wins over the file. Record each correction as a decision row. Then continue at step 4. - Create otherwise. Add
.orchestrate/to.git/info/excludewhen it is missing there. Writeprogram.mdfrom the request: the goal, the main SHA the program starts from, each task's source (issue number or spec section), each task's done predicate taken from its acceptance criteria, the merge policy, the user's rules (skills to use, screenshots, areas to avoid, verification rules, review skills the audit lane runs), and extra gates. Inventory the repository's verification skills perreferences/verification.md. Startdecisions.tsvfrom the header in the show-me-your-work skill'sreferences/decision-log-template.tsv.
The step is complete when the program directory exists and every open task's row matches its live PR and branch.
2. Build the task graph
The input is a list of issues, a specification, or a multi-phase plan. For a specification or a plan, cut the tasks per references/slicing.md first. For issues, read each one through the tracker that docs/agents/issue-tracker.md names, such as GitHub, GitLab, or Linear through its connector. Without that file, use gh issue view when the remote is GitHub, and otherwise ask the user where the issues live. Take dependencies from explicit links ("blocked by #3", "depends on", a spec's ordering). Infer a dependency only from a concrete shared surface, such as a migration another task reads or an API another task calls, and mark it inferred in program.md.
Create the rows with program.py init <program-dir> 'id|title|dep,dep' .... It rejects unknown dependencies and cycles. Give each task a verification level per references/verification.md.
Show the user the graph, the start order, each task's level, and the verification gaps, and wait for their go. A task without a checkable done predicate is not ready. Ask for its predicate in the same message.
3. Arm delegation
Emit the Agent mode preflight per HOST-COMPATIBILITY.md. Workers implement as the feature role, or bug-fix for a defect issue. Verification lanes run as verify-gates, verify-live, and verify-audit. Security tasks add the interrogate skill on interrogate-reviewers. The worker limit is the profile's concurrency limit, delegation.max-concurrent-workers: the most subagents that may run at the same time in this task, lanes and nested children included. The user's explicit number for this program overrides it. Record the limit in program.md. Pass each worker the credits you reserve for it per the delegation rules in that file, and count its children against the same limit. When the profile authorizes no workers, report it and stop.
4. Run the loop
Each wake (a worker report, a lane verdict, a user message) runs the same reconcile. Read the state, act on the difference, record it. The loop is idempotent, so a repeated wake finds nothing left to do (the make-operations-idempotent principle).
Start with one task. Take the first ready task all the way to merged before you fill the other slots. A flaw in the brief then costs one worker.
Fill slots. Run program.py ready <program-dir> --limit <limit>. For each start: line, move the task to building and create its worktree yourself with git worktree add <program-dir>/worktrees/<task-id> -b orch/<slug>/<task-id> <base>, so every host works the same way. A retry or fix round reuses the existing worktree and branch. Then start a worker in the background through the host's native delegation per HOST-COMPATIBILITY.md, with the brief from references/worker-brief.md naming that worktree. On Claude Code that is the Agent tool with run_in_background: true and no isolation, because the worktree already exists. On Codex, use the subagent tool its live schema exposes. A host without background delegation runs one task at a time. Record the worker in a decision row. A can-stack: or restack: line follows references/stacks.md.
On a worker report. Read the diff, the PR, and the checks yourself. The summary is a claim, the diff is the evidence.
PASSwith an open PR and green checks at a named head: setprandhead, move toverifying, and start the lanes the task's level requires at that head SHA, with the briefs inreferences/verification.md.ISSUESorBLOCKED: retry by cause with a fresh worker carrying the consolidated scope (original brief, the report, the branch). Use a smaller scope after a context limit, the same brief after a dropped run, and thehardest-tasksrole after a capability failure. After two failed attempts, move the task toparkedand raise it at the next user message.
On lane verdicts. Wait for every lane of the task. A verdict covers one head SHA.
- Every lane
PASSat the same head: record each verdict inverdict, then move tomerging. - Any
ISSUES: triage perreferences/verification.mdfirst. Non-blocking findings go tofindings.md. With blocking findings left, move tobuildingand start a fresh worker with the fix-round brief fromreferences/worker-brief.md, then verify the fix with the fix-round lanes. Whenprogram.pyrefuses the move because the fix budget is spent, park the task instead. STALE: the head moved. Reconcile the task with its live PR, then rerun the lanes at the new head.
Merge one PR at a time. Merges are the one serialized step. Under stop-at-verified, stop at merging and list the PR for the user. Under merge:
- Fetch main. Ask whether what landed since the PR's base can affect it: a conflict, a file both sides changed, or changed code the PR calls. When it can, send a fresh worker to rebase and get checks green, then rerun the lanes the rebase rule in
references/verification.mdnames. When it cannot, merge without a rebase. - Merge through the merge-when-ci-passes skill at the verified head. A code repair it would make goes to a fresh worker on that branch instead, so you never edit code.
- Move the task to
mergedand remove its worktree withgit worktree remove. Runprogram.py readyagain, because a merge can unblock dependents and leaves stacked children to restack.
Record every event as one decision row: what happened, why, evidence (PR, SHA, path), result. Copy each worker's out-of-scope problems into findings.md with the task that found it. Judge a worker by its pushes and PR activity, not its status text.
5. Talk to the user
The user may write at any time while workers run. Answer from the program directory and live PR state.
- Status ("co się dzieje", "catch me up"): follow the ketchup skill with the program directory as its record of what changed. Embed the task's screenshots from
screenshots/<task-id>/. - New rule ("use skill X for the frontend"): add it to
program.md. It applies to every brief started after it. - Hold or stop: stop every running worker, record each one's last pushed SHA, and start no new work until the user releases the hold.
6. Close the program
The program is settled when program.py show prints program: settled. When at least one task merged, run the thermo-nuclear-code-quality-review skill once, as one verify-audit unit, over the range from main at program start to the current main. Its findings never start a fix round. Add them to findings.md as candidate refactoring issues. Then follow the ketchup skill for the final report. It covers what merged with links, what is parked and why, problems found and how each was solved, the screenshots, and findings.md as proposed new issues, with the thermo-nuclear findings grouped as refactoring candidates. Create an issue only on the user's yes, through the tracker in docs/agents/issue-tracker.md.
Reply
Restate the goal, then per task its live state, verdict, and PR link, what merged, what is parked and its reason, open gates waiting on the user, and the follow-ups proposed from findings.md.
04 同仓库更多 Skills
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Searches available evidence sources and returns a cited account of decisions and tradeoffs. Use how for runtime behavior.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
unslop
Cut AI tells from prose. Use before writing or revising any reply, doc, PR description, commit message, or skill text another reader will see, or for /unslop.
typescript-best-practices
TypeScript best practices. Use when reading or editing any .ts or .tsx file.