Content
85%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, highly actionable orchestrator body with excellent workflow sequencing, validation gates, and progressive disclosure that loads detail one level deep. Its one weakness is conciseness: binding contracts and the 18 invariants are restated across multiple sections and duplicated in the reference file, adding tokens that could be trimmed.
Suggestions
Trim the inline 18-invariant list to the few that change behavior per phase and rely on references/invariants.md for the rest, keeping only the 'load before Phase 0' pointer — the full set is already duplicated there.
State each cross-cutting contract (worktree isolation, lint-as-push-gate, probe-for-shepherd-driver) once at first use and reference it later instead of restating it in the Composition, invariant, phase, and operating-contract sections.
Replace ALL-CAPS emphasis ('WILL', 'NEVER', 'MUST', 'NOT') with short imperative sentences; the caps add visual weight without adding information Claude needs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense with no beginner-concept padding, but the 18 invariants are summarized inline AND fully duplicated in references/invariants.md, and contracts (worktree isolation, lint-as-push-gate, probe-for-shepherd-driver) are restated across the Composition, invariant, phase, and operating-contract sections, so there is more than minor tightening opportunity — fitting score 3 over 4. | 3 / 5 |
Actionability | Provides copy-paste-ready, executable commands — 'gh issue list --label bug --state open --json ...', 'git worktree add <path> origin/main', the 'uv run python <row-worktree>/.agents/skills/shepherd-driver/scripts/owner_touch_gate.py verify --base $BASE_SHA --head ...' block, and the test-ff probe snippet — plus concrete schemas and status enums, matching the fully-executable score-5 anchor. | 5 / 5 |
Workflow Clarity | Phases 0-6 are clearly sequenced with explicit validation checkpoints (schema-validate every return with retry-once, mutation-break gate, owner_touch_gate parent re-probe, mergeability re-probe, lint-as-push-gate) and error-recovery feedback loops; the batch/destructive cap does not apply because validation is robust, matching the score-5 anchor. | 5 / 5 |
Progressive Disclosure | The body is an overview that points one level deep to real, well-signaled references — 'Load references/invariants.md before planning Phase 0', 'Load references/strategic-alignment-gate.md when entering this phase', '../shepherd-driver/references/mergeability-gate.md' — and appropriately delegates PR-drive detail to the sibling skill rather than duplicating it; all referenced bundle files exist, matching the score-5 anchor. | 5 / 5 |
Total | 18 / 20 Passed |