| name | orchestrate-issue |
| description | Orchestrate a substantial Cratedigger issue through scoped PRs, independent review, final validation, merge, deployment, live verification, and closure. Use for whole-issue delivery, especially when several workstreams can run concurrently. Do not use for a small patch, diagnosis-only request, or ordinary review. |
Orchestrate Issue
Own the outcome, not every keystroke. Keep scope and architecture coherent while
agents implement and review bounded pieces. Repository instructions remain the
authority; load the deploy skill when it is time to ship instead of repeating
its runbook here.
Shape the work
Read the issue and comments, inspect the relevant code and live state, then make
a compact coverage ledger: requested outcome, PR, dependency, and evidence.
Use it to prevent forgotten edge items, not to rewrite the issue as bureaucracy.
Prefer small, coherent PRs in isolated worktrees. Use available agent slots for
independent work when it shortens the critical path; an idle slot is cheaper
than a duplicate agent. Serialize only for a concrete dependency, overlapping
ownership, or required merge order. Independent PRs may start from the same
current main; refresh it before final review.
Implement and review
Compose agents around bounded jobs, not a fixed per-PR template. Implementation
may stay local, be delegated, or be split across disjoint surfaces. Review may
be broad or specialist, but must be independent of the code it assesses. Use
the fewest agents that give real coverage. Do not spend tokens on duplicate
generalist reviews or send several agents to answer the same question.
Treat tokens and context length as budgets. Brief agents with the issue slice,
worktree, exact SHA, and only the relevant rules; point to durable files instead
of pasting conversation history. Keep handoffs compact. Replace an agent whose
context is getting long at a coherent boundary. Never carry a subagent into the
next PR.
Let useful implementations and reviews overlap when safe. Agents should run
autonomously without reassurance pings or routine polling.
Keep work local through review. Implementers use focused tests while converging
and follow the repository's rules for tests, docs, and generated properties.
The orchestrator understands the diff and scope before handing the exact signed
local SHA over for independent review.
Review returns either one consolidated finding batch or CLEAN. Fix findings
locally and repeat on the new SHA. An independent CLEAN verdict is final. If
current main changes the reviewed tree, integrate it and review the new SHA.
On the reviewed committed SHA, run the check skill once: whole-repo threaded
Pyright followed by the full suite. Push that validated SHA with one ordinary
branch push, then open the PR. If final validation requires a code change,
reconverge with focused tests and review the new SHA before restarting the final
validation sequence. Do not add post-push review, duplicate suites, Nix replays,
or post-merge code audits.
Merge and advance
Confirm the PR head is the reviewed SHA and the coverage ledger is satisfied.
The PR body and every branch commit message must use canonical Refs #N or a
plain issue URL, never an auto-closing keyword; audit both with
python3 scripts/audit_issue_references.py.
Use the repository's merge method and expected-head guard. Confirm the merge
tree equals the reviewed PR-head tree, update the ledger, and keep independent
work moving. Do not rerun code gates after an unchanged reviewed tree merges.
Ship
When the ledger is complete, use the deploy skill. Verify the exact deployed
source and the real user-facing behavior, including the post-switch successor
cycle where the service lifecycle requires it. Screenshots or live data should
prove the reported symptom, not merely that deployment commands succeeded.
Record the PR, review, deploy, and live evidence. Only after the coverage ledger
is complete and live verification succeeds, close the issue deliberately.
Keep perspective
The orchestrator owns scope, architectural judgment, merge authority, and live
evidence. Agents own bounded execution and independent challenge. Keep useful
slots busy, communicate only material milestones or blockers, and lead the
handoff with what shipped and how it was proven.
