orchestrate

Files (16)

• SKILL.md
• openai.yaml · agents/
• IMPLEMENTER.md · references/
• RECOVERY.md · references/
• REVIEW.md · references/
• REVIEWER.md · references/
• RUNTIME.md · references/
• conductor-state.mjs · scripts/
• conductor-state.test.mjs · scripts/
• liveness-contract.test.mjs · scripts/
• render-graph.mjs · scripts/
• render-graph.test.mjs · scripts/
• upsert-graph.mjs · scripts/
• upsert-graph.test.mjs · scripts/
• validate-graph.mjs · scripts/
• validate-graph.test.mjs · scripts/

SKILL.md (first lines)

# Orchestrate

Act as a **conductor**. The spec and implementation tickets already exist. This
task proves their graph, opens one launch gate, publishes the accepted graph,
then starts exactly one lifecycle actor.

Accept `spec <issue-ref>` plus an optional
`owner/repo:final-branch:integration-branch`. `#1234` uses the current GitHub
repository; a full issue URL resolves its repository. A named profile is a
recommendation and never skips the launch gate.

## Profile

The launch profile has two orthogonal axes:

- `review=lean`: required validation plus local CodeRabbit light review.
- `review=deep`: required validation plus full local CodeRabbit and one
  independent adversarial reviewer.
- `supervision=supervised`: integration pauses for SHA-bound user approval.
- `supervision=unsupervised`: a ready SHA integrates automatically.

Repository-required checks are always additive. Delivery is automatic: an
exclusive writable lane may integrate without a PR; parallel work or repository
policy uses PRs. Worker execution permission is not a supervision axis: every
profile requires writable actor worktrees and non-interactive execution.

Keep preflight read-only. The accepted launch gate authorizes publication of the
managed graph section, lifecycle actors, assignments, branches, PRs, comments,
admitted integration, issue closure, and exact cleanup. Unsupervised acceptance
also authorizes corrective implementation tickets, blocker edges, and PATCH
releases required to satisfy the accepted spec. It does not authorize changed
acceptance criteria, a MINOR or MAJOR release, new external side effects, or an
irreversible destructive choice.

## 1. Establish the score

1. Treat the issue repository as the ledger repository. Read its instructions
   and resolve its local checkout and Codex project.
2. Fetch the full spec body and comments. Resolve the assignee from an explicit
   invocation override or the authenticated GitHub viewer.
3. Build the complete implementation-ticket inventory from derivation links,
   comments, every issue whose `Parent` names the spec, and native sub-issues.
   Fetch native sub-issues independently; neither source alone is the inventory.
   Fetch every expected ticket's body, comments, state, and linked PRs. Precursors
   and decision issues do not enter the implementation manifest.
4. Require every expected implementation ticket to be a native sub-issue. List
   every missing relationship and stop before rendering when any is absent.
5. Classify a ticket as `HITL` when its labels, metadata, or body explicitly say
   `HITL`, `HILT`, or human-in-the-loop; otherwise classify it as `AFK`.
6. Resolve `Blocked by` edges from native relationships, then ticket text.
   Record repository-qualified external blockers separately.
7. For each ticket, distinguish its ledger repository from its implementation
   target. Resolve an explicitly named target repository from ticket metadata,
   body, or accepted spec evidence; otherwise use the ledger repository. Record
   its target branch, whether it has any refs, local checkout and Codex project
   when available, and target-specific validation command. Never infer that a
   native sub-issue implements in its ledger repository.
8. Resolve final and integration branches per implementation target from ticket
   evidence, invocation, an unambiguous target convention, then its default
   branch. Resolve whether target rules or PR-only checks require PR delivery.
9. Prove the current trusted runtime can create writable isolated worktrees and
   perform required git and GitHub operations without operational approval.
   A runtime that would prompt during implementation is not launchable.
10. Find existing conductors and live work for this spec. Record their profile,
   target branch, ticket, PR, head, and state without resuming them. A legacy
   conductor without a profile is `deep + supervised`.

Completion criterion: at least one implementation ticket exists; each has a
title, state, mode, native parent, resolved blockers, and implementation target;
the ledger repository, assignee, target branches, validation commands, PR
requirements, and every live actor are known.

## 2. Prove the frontier

Build the manifest from live GitHub state:

```json
{"spec":"1234","ledgerRepository":"owner/ledger","tickets":[{"id":"10","parent":"1234","nativeSubIssue":true,"title":"...","state":"open","mode":"hitl","blockedBy":["other/repo#7"],"targetRepository":"owner/code"}],"externalBlockers":[{"id":"other/repo#7","state":"closed"}]}
```

Resolve `scripts/validate-graph.mjs` beside this file and run it with `node`,
passing the manifest on stdin. A nonzero exit stops preflight. Repair discovery
from authoritative state; if it remains invalid, report the diagnostic and end.

Run `scripts/render-graph.mjs` with the same manifest. Keep its Mermaid stdout,
`launchable` AFK frontier, and `hitlFrontier` pauses. Mark the current frontier
`direct-eligible` only when it contains one AFK ticket, no other live writer
targets integration, direct pushes are allowed, and complete validation runs
before integration. Uncertain or PR-only validation makes it `pr-required`.

Completion criterion: validation proves a complete acyclic graph and the
renderer emits one node per ticket and external blocker; current delivery
eligibility has evidence.

## 3. Open the launch gate

Show the Mermaid graph and say arrows point from blocker to unlocked ticket.
List every open HITL ticket, or `HITL pauses: none`. Show current delivery
eligibility and any existing conductor beside the graph.

Ask exactly: "Which orchestration profile should I launch? Choosing one accepts
this graph, its listed HITL pauses, and the repair authority described above."

1. `lean + supervised`
2. `lean + unsupervised`
3. `deep + supervised`
4. `deep + unsupervised`

If a live conductor differs, state that selection authorizes replacement only
after exact cleanup proves no unmerged work will be lost. Create nothing and
write nothing before the answer.

Completion criterion: the user selected one profile and accepted the graph and
HITL pauses in the same answer.

## 4. Publish the accepted graph

Refresh the spec, tickets, blockers, implementation targets, branches, and
repository rules. Rebuild, validate, and render the manifest. Structural or

From giacomoguidotto/skills, MIT.

More from giacomoguidotto/skills