orchestrate-implementation
Orchestrate approved plans or GitHub issues with Pi implementers and reviewers. Use when the user requests delegated implementation or coordinated Pi sessions; not for design, plan writing, or ordinary direct coding.
How do I install this agent skill?
npx skills add https://github.com/legout/skills --skill orchestrate-implementationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a complex orchestration framework designed to delegate implementation tasks to sub-agents across multiple platforms. It features robust security boundaries, including 'contracts' and isolated worktrees, to prevent sub-agents from being compromised by malicious content in GitHub issues or plan files. While it executes bash scripts for Git management and accesses agent configuration files, these actions are essential for its function and are handled with significant instruction-level oversight.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Orchestrate Implementation
Worktree isolation patterns are adapted from
using-git-worktreesand David Ondrej'sgit-worktree. Test-seam patterns are adapted from Matt Pocock'stdd,tests, andmockingguidance (all MIT). Exact pins are recorded insources.json.Shared-write separation, smallest-safe-decomposition, and bounded child context are adapted from Cursor's
poteto-modeat commit93b00b89ef425a9c1bac0d0b317dfc49c930ac99(MIT, Copyright (c) 2026 Cursor).
Ownership and authority
The current session is the parent. It owns scope, decisions, routing, finding disposition, acceptance, candidate assembly, and the final conclusion. Children implement or review bounded tasks; their reports are evidence, not acceptance or publication authority. Delegate only when the current request or applicable instructions authorize it. All child roles use Pi, including workers, fixes, scouts, reviewers, and advisors. Hosts manage placement and lifecycle; model providers inside Pi are not alternative agent runtimes.
Use the smallest safe decomposition. One bounded issue can have one writer; parallel writers need independent owned surfaces and separate worktrees. Scout only when context gathering has a concrete job. Do not add workflows, specialists, reviews, or checks merely to fill stages. Children do not delegate further unless the parent explicitly authorizes fanout.
Modes
State the requested/configured mode, otherwise supervised:
plan-only: read inputs and outline tasks/briefs; no source edits, worktrees, or child launches.supervised: implement, validate, and review, including disposable candidate assembly; pause before target integration.autonomous: keep the same loop moving while safe work is ready; neither the label nor candidate assembly grants target integration or publication authority.
Supervision level. Light is the default; strict only when the user explicitly asks for strict supervision or stage-by-stage confirmation. Light interrupts the human only for critical decisions: approval gates the planning contract already requires, irreversible or destructive actions, target integration/push/publication authority, material scope or authority changes, and unresolved material conflicts that block progress. Everything else — including continuation of safe work, disposable-resource cleanup after acceptance, and non-material naming or ordering choices — proceeds with the smallest safe default, recorded in run state and reported at handoff; batch non-critical questions instead of blocking safe work. Strict additionally confirms each stage boundary: briefs before dispatch, each review disposition, and cleanup.
An execution request authorizes isolated candidate preparation, not changing the user's target branch. Explicit user restrictions override this default. Target integration, push, issue comments/closure, PR creation/merge, deploy, and release each require applicable authority. Hand approved integration to merge-worktree; do not treat a mode as publication permission.
1. Read and authorize
Load planning-contract (Contract version: 1). It alone owns artifact classification, approval, the capture checkpoint, and execution readiness. If missing, request installation and refuse writer dispatch. Read the supplied plan, issue, and linked approved behavioral sources; preserve them rather than manufacturing another planning format. An approved bounded issue may satisfy the contract without a separate spec or plan.
For GitHub, fetch the exact issue with an explicit repository (for example gh issue view <number> --repo <owner/repo> --json number,url,title,body,updatedAt), check that repository against the checkout, and record the source URL/revision and owner authorization. Relevant comments are context, not automatic scope or permission changes. If a project selects Epiq in project/agents/issue-tracker.md (legacy docs/agents/issue-tracker.md), load its workflow and use only epiq_* MCP tools; do not initialize a board implicitly.
Stop on conflicting criteria or unresolved material decisions. Route missing behavior/approval to shape-design, missing decomposition to write-implementation-plan. Recheck readiness only for tasks affected by a material source/interface/scope change. Never infer execution authority from a file location or assistant-written status.
2. Select the Pi host
Resolve explicit per-role/lane selection first; otherwise auto-detect the current harness from its session environment: BB (BB_THREAD_ID) uses BB child threads, Orca (ORCA_PANE_KEY/ORCA_TAB_ID/ORCA_WORKTREE_ID) uses Orca orchestration, T3 uses its child-capable Pi instance, an agent-scoped Paseo session uses its Pi provider, herdr-core (HC_TERMINAL_ID) uses fresh Pi terminals, the older Herdr uses a fresh Pi pane, and none detected falls back to available native Pi subagents. Tool presence alone is not host detection. Record the chosen host and the evidence that it can perform the requested role; ask only when detection leaves the host genuinely ambiguous. A detected or selected host without the required capability blocks that role, not permission to silently switch hosts or runtimes.
Read only the selected adapter and its installed runtime guidance before dispatch:
- BB dispatch:
bb thread spawn, BB child threads in BB-managed worktree environments. - Orca dispatch:
orchestration worker-start, Orca-run Pi workers in Orca-managed workspaces. - Native Pi dispatch:
pi-subagents, native Pi children only. - herdr-core dispatch:
hc, fresh Pi terminals in separate Herdr-app tabs. - Herdr dispatch: older
herdr-pane, fresh visible Pi sessions. - Paseo dispatch:
paseo, Pi provider and explicitly bound workspace. - T3 dispatch:
t3-delegate, Pi driver; currently read-only until supported isolated mutation placement exists.
Resolve each role's model and thinking fields independently: explicit run/lane → project → global → spec default. Defaults are worker zai/glm-5.3/high and reviewer openai-codex/gpt-6.1-sol/high. inherit removes that field's override and resolves from global or spec default, not the parent session. Pass the complete effective pair explicitly, even when project profile objects shadow global objects. Filter profiles for Pi before matching the role. Prove the exact model/thinking and child tool dependencies before agent creation; do not guess aliases, omit thinking, downgrade, install prerequisites, or switch hosts silently. Record each value/source, backend-effective pair, and blocker in existing run state.
3. Prepare ownership and validation
Mutation requires Git. Verify the canonical repository, clean approved base, and selected host's worktree support. Record a small run state using manifest and briefs; link existing host/mission artifacts rather than duplicating their contents. Read Git handoff before allocating writers: pin supported named bases and preserve committed results before disposable workspaces can disappear.
Use the shared state root ${XDG_STATE_HOME:-$HOME/.local/state}/worktrees/ for all newly allocated worker/fix, parent review/reconstruction, and candidate worktrees. Resolve it once on the allocation host and record its absolute canonical path; a non-absolute state directory or unavailable host-side path blocks. Allow allocator-supported subdirectories: native Pi adds the repository basename and run identity; Paseo adds a checkout hash and workspace slug. Parent-created checkouts use a collision-checked source-checkout identity plus run/lane/role/attempt naming, so unrelated repositories and same-named clones cannot reuse a path. Record actual repository/common Git directory and path mappings; a shared root does not imply shared ownership.
Before allocation, validate physical path components/symlinks, permissions, collisions, and exclusion from the active checkout and Pi extension auto-discovery; create only the validated root. Preserve the configured allocator; an incompatible root requires a separate owner-approved configuration change, never reconfiguration during dispatch or an off-root retry. Never migrate existing worktrees as part of this policy change; retain their recorded locations and lifecycle ownership. An unsafe/unsupported root blocks new allocation.
Use one writer per isolated registered worktree. Verify every returned canonical path is beneath the shared root and belongs to the expected repository/base, with exclusive ownership, before granting writes. A path in a prompt is not workspace placement. Confirm actual child cwd/repository/branch and effective model/thinking in a no-write preflight; mismatches block mutation.
Run or record the smallest useful baseline. Distinguish pre-existing failures from task obligations; a red baseline requires an owner decision before implementation. Carry each unit's minimal validation from the plan — verification before tests, per-task checks minimal, thorough verification deferred to the plan's final verification task:
existing-check: existing coverage exercises the named changed behavior; run it without adding redundant tests.new-test: a named regression risk that must be caught after this run lacks coverage; add one focused test with expected values from the approved criteria or an independent oracle, never copied from implementation output. Bug repros fail before the fix; behavior-affecting refactors pin current behavior before mutation. Add more only for distinct material failure modes.no-new-test: docs, metadata, or mechanical/behavior-neutral work; use the meaningful parse, build, smoke, or diff check.
Choose the cheapest stable seam that catches the named failure, never mock the unit under test, and do not relax assertions to force green. Reuse verified focused-check evidence only when the relevant code, tests, inputs, and environment still match; an identical tree is a sufficient case, not the only one, and a parent rerun never duplicates a green result. A rerun needs a relevant delta or a specific hypothesis. A worker's pass claim alone is not verified evidence. Run required repository checks and affected acceptance checks, not every available command.
Give each worker the exact validation scope and budget — named failure, independent oracle, one focused check or the applicable reuse decision, and the invalidating delta — and carry it unchanged into fix and resume briefs and reviewer context. A child never widens its assigned validation, and a failure stops at investigating the named failure; it authorizes no broader suites or relaxed expectations.
4. Dispatch and collect
Give fresh children the bounded brief and inline role contract from manifest and briefs. Use a direct child for one task; scripts are for useful sequencing, fanout, or branching. Read-only children can share a stable checkout if they do not modify project state. Send exact diff endpoints and real-use context to reviewers, not the whole chat history.
Prefer asynchronous host completion notifications. Keep independent safe work moving; yield when only children remain. A timeout, idle turn, message receipt, or attention signal is not terminal success. Use the host's status/control API to resolve ownership before a replacement writer. Cancellation stops execution and preserves available work; cleanup is a separate decision.
Use hc for herdr-core child communication, and pi-intercom for older Herdr registration, progress, questions, and explicitly named Pi peers. Paseo/T3 Pi sessions may also use it if both endpoints have connected tools and the same reachable broker. Native children use their supervisor channel by default. BB children end their turn with questions and rely on parent notifications; Orca workers use orchestration ask/send/reply. Intercom is messaging, not workspace placement, lifecycle authority, or proof of completion; remote hosts do not inherit local paths or broker connectivity.
5. Verify, review, and correct
Verify the committed result and inspect its actual diff; keep its ref frozen while consumers need it. A surviving worktree can be inspected directly once writer ownership is released. If only a patch-only handoff is available, read review and recovery and reconstruct it against the pinned base with digest/tree/cleanliness checks. Do not require patch reconstruction for an already verified committed result.
Parent inspection applies to every result. Verification is the default acceptance evidence: drive the real artifact against independently derived expectations at the cheapest stable seam, and run the plan's final verification task on the assembled candidate. Dispatch an independent reviewer only where execution evidence cannot reach — high-risk changes and contracts before dependent writers consume them, conformance to written conventions or approved criteria, or a project/user rule requiring independence. Lanes needing that review are not accepted until it passes; low-risk work is accepted on verification plus parent inspection. Any review covers unreviewed changes and integration effects, not settled findings again.
Disposition findings before repair: reject failed evidence gates in one line, authorize small in-scope fixes, hand large/out-of-scope repairs to the human, or ask about an unverified criterion. Use the full inline reviewer contract. One fix pass, one delta recheck; no third round or budget reset at candidate assembly. Prefer a fix commit on the frozen result; review only the prior-result-to-fix delta and affected behavior. Patch replacement recovery follows the same budget.
6. Deliver and clean up
Assemble in an isolated candidate worktree in dependency order, using accepted upstream candidate commits as dependent lane bases. Preserve source/result refs and record candidate base/head. Validate the combined behavior by running the plan's final verification task — the plan's assigned empirical journeys and any justified formal checks, each against its independent source and exact scope, preferring the selected project-local verification recipes; reuse prior evidence where the relevant code, tests, inputs, and environment still match, and record which evidence was reused. Conflicts or changed dependency bases pause for reconciliation, not another writer or automatic scope expansion.
Before acceptance, inspect the exact final diff and evidence, resolve every material criterion, and account for every child as terminal or blocked with a next action. Restate the approved task, compare the result, and choose accept / fix / hand back / ask; extra ideas get one line, not code. Report skipped checks and residual risks. A reviewer verdict does not authorize target integration or publication.
Remove only owned resources after writer ownership is released, handoffs are durable, consumers are finished, and cleanup is authorized. Preserve failed/uncertain work and refs; do not force removal, close visible panes, or archive shared/advisor workspaces implicitly. Native automatic finalization is adapter-owned and must leave its documented handoff. Supervised delivery pauses with the verified candidate and its merge-worktree handoff, not before final verification and any required review. When the user asks to land the result (push, close issues, clean up), land-changes drives that sequence from the handoff.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/legout/skills/orchestrate-implementation">View orchestrate-implementation on skillZs</a>