orchestrator

Files (4)

• SKILL.md
• claude-code.md · references/
• generic-harness.md · references/
• pi.md · references/

SKILL.md (first lines)

Use this skill when repository work should advance through explicit stages with checkable boundaries.

## Parent boundary

The parent plans and coordinates; it never performs repository work.

The parent may only:

- Define and amend the task contract, stages, and success criteria.
- Resolve the commit policy and role models with the user.
- Launch, resume, and coordinate subagents.
- Relay structured reports and request decisions.
- Decide whether to continue, repair, block, or complete the run.

The parent does not read repository files, inspect Git state or diffs, run commands or tests, edit files, stage changes, commit, or push. It works from user input, structured subagent reports, and recorded decisions.

## Load the harness branch

Before the first subagent launch, identify the active agent harness and read exactly the matching reference:

- **Pi with `pi-subagents`:** [`references/pi.md`](references/pi.md)
- **Claude Code with the `Agent` tool:** [`references/claude-code.md`](references/claude-code.md)
- **Any other agent facility or harness:** [`references/generic-harness.md`](references/generic-harness.md)

Do not load references for inactive harnesses. The selected reference is authoritative for tool names, agent discovery, model syntax, context isolation, async behavior, child handles, and lifecycle operations. This file remains authoritative for stage semantics and safety.

Completion criterion: one harness reference is loaded, every required role can be represented in that harness, and unresolved model or lifecycle choices have been raised to the user.

## Run preflight

Before Stage 1, resolve the commit policy unless the user already stated it. General permission to implement is not permission to commit.

Use exactly one policy:

- `all_stage_commits_authorized`
- `ask_before_each_stage_commit`
- `no_commits`

Delegate preflight as the first repository-touching action. For a commit-capable policy on the default branch, the preflight child creates a dedicated local branch before any implementation mutation. Require it to report:

- A short run ID, repository root, original branch, active run branch, default branch, and `run_base_sha`.
- Initial staged, unstaged, and untracked paths.
- A sanitized run-base evidence bundle: initial patches, untracked manifest, stage-relevant hashes or snapshots, and a state fingerprint.
- **Protected dirty paths**: every path dirty before the run.
- The run artifact directory, ledger path, and retention policy.
- Resolved role models, commit policy, and `no_push: true`.

Protected dirty paths must not be edited, staged, restored, or otherwise altered. If one overlaps a possible stage write scope, stop before implementation and ask the user how to proceed.

Branch creation authorizes neither commit nor push.

Never push, force-push, amend, hard reset, clean, stash, or discard user changes unless the user separately requests that exact action.

Completion criterion: sanitized evidence can identify the initial state and distinguish later run changes without exposing protected content; protected paths are known; the commit policy and active run branch are explicit; and no unresolved protected-path overlap remains.

## Run ledger

Keep one run-scoped artifact directory containing the narrative ledger and sanitized state evidence. Prefer a harness-shared directory outside the repository. If none exists, use a clearly identified repository-local fallback and exclude it from staging, commits, changed-file accounting, and hygiene findings except to verify that exclusion.

The narrative ledger records:

- Run metadata, original task contract, whole-task criteria, and amendments.
- User decisions, accepted risks, and commit policy.
- Stage contracts, attempts, verdicts, lessons, and commit records.
- Closure reports and final outcome.

Validators never read the narrative ledger. They may read only exact, named sanitized evidence artifacts containing factual state, never implementation rationale or conclusions. Do not copy secrets or full protected-file contents into evidence; prefer paths, metadata, hashes, and minimal safe snapshots.

Use stable IDs for stages, criteria, validation attempts, findings, decisions, and lessons. Fingerprint findings from criterion, location, and normalized cause. Append amendments and attempts; never rewrite history. Give each child only the contract, verified lessons, reports, and evidence it needs.

Keep artifacts while the run is active or blocked. Do not remove them before the final user report; repository-local cleanup requires prior authorization.

## Stage contract

Define every stage before implementation:

- Stable stage ID, title, goal, user-visible outcome, and dependencies.
- `stage_base_sha`; if the baseline is uncommitted, a sanitized stage-base evidence bundle sufficient to identify the baseline and distinguish the stage delta. Include exact content only for safe, stage-relevant files.
- Expected write scope, explicit exclusions, and protected paths.
- Acceptance criteria with stable criterion IDs.
- Required checks and evidence.
- Commit intent under the run policy.
- Conditions requiring user input.

A repair that only satisfies the current contract remains in the same stage and resumes the same implementation context. A changed goal, scope, architecture, dependency, or criterion requires an appended contract amendment or a coherent repair stage.

Completion criterion: every intended change and required check maps to a criterion, exclusions are explicit, and the baseline can be independently identified well enough to compute the stage delta without exposing protected content.

## Stage loop

1. Launch one implementation child using the selected harness reference. It is the sole product-code writer for the stage. Give it the current contract and only relevant verified lessons.
2. Require the implementation report to include changed files and behavior, commands and observed results, failed approaches worth preserving, remaining risks, current head, and repository-state evidence.
3. After implementation finishes, launch a brand-new validation child in independent context. Give it the task and stage contracts, baseline SHA and named sanitized evidence, expected scope, exclusions, and protected paths. Do not provide the narrative ledger, implementation report, rationale, or conclusions.
4. The validator independently computes repository state and the stage delta, runs relevant checks, and returns the report below.
5. Delegate evidence review and lesson synthesis after both reports exist. The ledger child may question completed children only as the selected harness allows; it never changes product code or negotiates findings.
6. A changed verdict must come from the validator as an amended report. Record the amendment before acting.
7. Apply the verdict rules, obtain user decisions for risks and INFO findings, and apply commit policy. A `NOT_READY` stage retains the implementation context for repair and returns to step 2.
8. After an accepted stage's risk, INFO, and commit decisions finish, delegate a final ledger update and compact the stage record.
9. Retire accepted-stage children according to the harness reference and never reuse a released validator.

Completion criterion: the stage has a final independent verdict; every finding, user decision, lesson, and commit result is recorded; product state matches the validated fingerprint; and every accepted-stage child is retired while a `NOT_READY` implementation child remains available for same-stage repair.

### Stage validation report

```md
## Stage Validation Report

### Identity
- run_id:
- stage_id:
- contract_version:
- attempt:
- validator_handle:
- model:
- stage_base_sha:

### Observed Repository State
- branch:
- head_sha:

From EATSTEAK/skills, MIT.

More from EATSTEAK/skills