Orchestrate a ticket end to end

Drive ONE unit of work through the full pipeline. This is the same flow as the Claude Code /orchestrate command, reached by natural language. If the user named a ticket, that is the target; otherwise treat their description as the spec.

First read .orchestration/config.yaml and validate it with orchestration-engine.py validate-config. For schema_version: 2, branch roles, transition guards, CI categories, approvals, ticket adapters, and target branches come from the configured workflow; use orchestration-engine.py adapter-plan --host codex <transition> when the repo declares the ticket flow as explicit transitions. For legacy configs, keep the existing implement -> review -> security -> verify -> merge-on-green flow below.

Before every design-reviewer, implementer, code-reviewer, security-reviewer, or visual-qa launch, resolve the role with scripts/context_pipeline.py route --config .orchestration/config.yaml --role <role>. A desktop route uses the existing native agent. An api route builds its provider request with context_pipeline.py payload --config ... --role <role> and pipes it to scripts/api_agent.py run --request - --config .orchestration/config.yaml --role <role>, including ticket, sprint, and stable run identifiers when available. Before each API reviewer run, issue a phase permit with review-ledger.py permit-review <pr-or-design-id> --role <role> --head <full-exact-head> and pass it to run --review-pr <pr-or-design-id> --review-authorization <token>. The runner enforces role tools and USD/token ceilings. Use desktop fallback only after proving the API request failed before any provider/run id existed. Submitted, timed-out, or uncertain API work remains reserved for reconciliation and must never be duplicated.

For a model-less OpenAI desktop route, use Codex's ChatGPT subscription login and configured default model; do not add an API credential, base URL, or model override. These turns have no API usage receipt, but every non-spend workflow gate remains mandatory. Model-less Claude routes are unsupported because their subscription authentication cannot be proven mechanically.

Relaying information (do not hand down stale facts)

You are a lossy relay. Every hop -- an agent's report into your brief, a brief into a durable doc -- can drop the uncertainty marker and turn a "maybe" into an asserted fact. These rules keep drift out of what you hand down. Each costs one grep; skipping one costs review rounds.

• Grep targets, not line numbers. Never put a file:line in a brief. Give the symbol name or the exact string to grep for. Line numbers drift the moment a branch moves; a grep target is self-verifying. (A test file:line a reviewer produced in its own fresh checkout is fine for that reviewer; do not copy it forward into a brief or a doc.)
• Never hand over code you did not run. No selector, snippet, or query written from memory. Describe the intent and the constraint and let the implementer write the code and confirm it resolves to what you meant. An unexecuted snippet is a guess in the costume of a fact -- and a wrong selector manufactures a false green.
• Label provenance on every claim you pass down. Mark each as verified by me just now, reported by <agent>, unverified, or from the ticket, unverified, and tell the receiver to verify every claim and report what they had to drop. Where you label, receivers catch your errors; where you assert, they propagate.
• Agreement is not verification. Two agents concurring is independent confirmation only if the second names the evidence it actually looked at. A reviewer who read the implementer's report and agreed has verified nothing -- that is transitive trust, not a second opinion.
• Re-derive before any durable write. A brief is cheap to correct mid-flight; CLAUDE.md, a ticket, a PR body are read months later by someone who cannot tell which sentences you checked. The bar for a durable artifact is: I opened the file, just now, on this branch, and re-read the fact -- not "an agent told me hours ago."
• A merge invalidates everything before it. Any fact you learned before a merge you performed (migration maxes, "current" state, line ranges) is stale by default. Re-derive after every merge.

Plugin paths

The role briefs and scripts below live in this plugin, not necessarily in the target repository. Resolve these paths from this skill file before executing or reading them:

• ../../agents/orchestration-implementer.md
• ../../agents/orchestration-design-reviewer.md
• ../../agents/orchestration-code-reviewer.md
• ../../agents/orchestration-security-reviewer.md
• ../../agents/orchestration-visual-qa.md
• ../../scripts/merge-guard.sh
• ../../scripts/merge-on-green.sh
• ../../scripts/cleanup-worktree.sh
• ../../scripts/context_pipeline.py
• ../../scripts/api_agent.py
• ../../scripts/orchestration-engine.py
• ../../scripts/review-ledger.py
• ../../scripts/run-verification.sh
• ../../scripts/run-visual-qa.sh

Execute scripts by absolute path while keeping the target repository as the working directory.

Steps

1. Scope check. If the ticket system is a real tracker, confirm the ticket is Ready: a description you could write a failing test from. If it is too thin, scope it (see the scope-ticket skill) or push back BEFORE cutting a branch. With no tracker, treat the request as the spec.

   Resolve worker_trust_profile now. It applies only to orchestration workers versus the host; it never narrows the application threat model. Do not let a later reviewer silently substitute a stronger profile.

2. Pre-implementation gates. Before cutting a branch or editing production code, build an adversarial test matrix from the acceptance criteria and the existing system. Each row names the attack/failure mode, setup/input, expected invariant, test layer, and the assertion that would fail. Include relevant parser/interpreter forms (shell wrappers, quoting, substitutions, heredocs, redirections and pipelines), ignored/untracked files, failed Git or other inspection commands, partial execution, cleanup/recovery, permissions, concurrency, retries, and hostile inputs; mark a category N/A only with a reason. Perform an architecture-feasibility check before implementation: name which repository or operating boundary can enforce every promised invariant. If success requires a root-owned installation, distinct UID, daemon, container, cloud resource, or rollout outside the authorized scope, split or defer that work instead of approving an in-repository approximation. If the planned change touches security-sensitive infrastructure or crosses one of those external boundaries, run a fresh pre-code design review with orchestration-design-reviewer.md. Open its durable counter with review-ledger.py design-open <ticket-or-change> and record FAIL with design-record --verdict FAIL --evidence <artifact>. A PASS must use design-record --result <json> with schema version 1, gate design-review, verdict, full exact source_sha, named repository artifact, its SHA-256 digest, the consumed phase_permit, and non-empty pass/fail checks. A generic completed message cannot authorize code. It must define the trust boundary and impossible guarantees, reject fragile designs, audit the matrix, and end VERDICT: PASS. A FAIL returns to design until max_design_rounds; then stop with design-handoff. Pass the approved artifacts to the implementer.
3. Implement. Run the implementer role from orchestration-implementer.md, passing the ticket body and the click-path. If the host supports subagents, launch a fresh implementer with isolation: "worktree"; otherwise perform that role as a distinct pass in an isolated git worktree. Use configured branch roles. In legacy configs, this remains one agent-role, one ticket, one worktree, one branch off the legacy configured source branch, one PR to the legacy configured target branch. Wait for its structured report (PR number, branch, worktree, SELF_CHECK).

4. Gate. Run the review gates on the PR concurrently against one exact head: first run version_policy.py --plugin-root <resolved-plugin-root> --config .orchestration/config.yaml and stop unless it reports status: compatible. The permit and merge scripts repeat this minimum-version check mechanically. a fresh code-review role using orchestration-code-reviewer.md (no implementer context), and a fresh security-review role using orchestration-security-reviewer.md when the shared orchestration-engine.py security-gate decision requires it from the raw diff or authoritative PR source/target branches. Bind every decision to the review generation with review-ledger.py record-security-gate <pr> --head <full-exact-head> --decision <security-gate-output.json>; without it the ledger keeps a configured security review required. A failed decision is a fail-closed stop, never permission to skip security. Both must return validated structured PASS results with no blocking findings. On each pass, supply the raw unified base-to-head git diff as the default code input, never a full-codebase index; expand only for a named verification or regression check. On any structured FAIL result, require the reviewer to finish its full checklist and adversarial sweep and return all findings together. A blocking finding must identify a concrete failing input/precondition, production path, wrong outcome/impact, and reproduction or exact falsifying assertion under the configured threat profile. Hypothetical stronger-profile concerns are advisory and must not expand the ticket into infrastructure.

   The durable failure ledger owns this loop; do not track it in your own context, which compacts. Open it once with the immutable ticket binding (review-ledger.py open <pr> --work-kind jira --work-id <ticket>), paste review-ledger.py brief <pr> into every reviewer brief, and record every completed gate with review-ledger.py record <pr> --gate <gate> --result .orchestration/.review-results/<gate>.json --head <exact-sha> --phase-permit <token>. Native reviewers first call complete-review on that permit after writing the structured result. It normalizes each finding's bare <path>:<symbol> component key so a repeated defect actually accumulates strikes, freezes blocking scope after round 1, and returns next_action:

   If a non-findings commit moves the PR head after a complete generation, run review-ledger.py rebind-generation <pr> --head <full-exact-head> --reason "<auditable reason>" before requesting new review permits. It preserves the prior history, findings, strikes, and repair-cycle count and is refused while blockers or permits remain open. A findings repair must still use record-repair.

   • review -- after all gates record, generate one repair-brief; return its deduplicated stable IDs to a fresh implementer on the same branch. Require root cause, change, affected boundaries, closure condition, and verification for every ID. Record the strict report with record-repair, concurrently re-run code and required security review on that exact head, then call record ... --head <exact-sha> for each result and complete-repair-review. Advisory findings never enter the repair brief.
   • redesign -- a component survived a completed repair. Return to the design gate for a root-cause redesign scoped to that component with a revised adversarial matrix before any more code is changed; do not authorize another narrow patch. Record its PASS with review-ledger.py redesign <pr> --key <key> --verdict PASS.
   • escalate-human -- the configured round cap is spent with blocking findings still open. STOP: do not merge and do not run another round. Hand the user review-ledger.py handoff <pr> with the PR link.
   • gates-clear -- necessary, not sufficient; confirm the security gate ran if the diff triggers it.

   On later rounds, code review covers the repair delta and affected boundaries; security still audits every relevant trust boundary. Never merge on a FAIL.

5. Verify (when configured). For each verification: entry whose when: matches the configured target, run the resolved run-verification.sh <name> on the rebased branch (GREEN writes a sha-stamped result file; RED = no merge). If the change has a user-visible surface, run the visual-QA role from orchestration-visual-qa.md against the click-path; it must end VERDICT: PASS.
6. Merge on green. Only after every gate PASSES, every required verification is GREEN, and the configured target CI checks are green: record the marker (merge-guard.sh --record-green <pr> [result_file]), then merge with merge-on-green.sh <pr> <branch> all-green <verify_path>. That script validates the marker, plugin version, PR head/branch, target base/sha, and freshness itself, so correctness never depends on either host registering a hook. A trusted Claude Code or Codex hook is defense in depth; branch protection remains the out-of-band enforcement layer.
7. Close the loop. Transition the ticket if there is a configured tracker or ticket adapter. Confirm the work landed on the configured target branch. Read worktree_cleanup (default manual). When it is auto, run cleanup-worktree.sh <WORKTREE> explicitly after the verified merge; this is the host-neutral cleanup path and still refuses dirty worktrees. When it is manual, preserve the worktree and report its path. Report what merged and the click path. Do not assume a lifecycle hook ran.

Respect concurrency_max for ticket lanes and max_heavy_processes for local build/test/browser chains. When the API ledger shows sustained rate-limit wait, stop admitting work to that provider until it recovers; preserve reservations and let safe work routed elsewhere continue. Dual gates on ONE PR run concurrently against one immutable head. CI-green alone is NOT the gate; the independent VERDICTs are mandatory.