| name | orchestration-playbook |
| description | Codify command essentials into a delegation protocol. Centered on grasp and intent, standardize formats for orders and reports, the control envelope, and stop conditions. |
| compatibility | opencode |
Orchestration Playbook
Operational standard for an orchestrator to guide a set of subagents to mission success.
Do not constrain with prose. Align by templates.
Definitions
Command essentials are expressed as two pillars:
- Maintain reliable grasp
- Under clear intent, issue timely and appropriate orders, and discipline execution
Supporting principles:
- Keep control minimal and leave room for initiative
- For grasp, prioritize alignment, situational awareness, and execution supervision
When to use
- The number of subagents increases and decisions collide or state becomes inconsistent
- Variation in delegation instructions and reports causes rework
- Parallelization causes conflicts or duplicate work
- Ask-first boundaries or quality gates are violated
What it provides
- Intent template
- Envelope template
- Mission-type order template
- Situation report template
- Postmortem template
- Work Order v1+ template
- Subagent reply template
- Integration memo template
- Acceptance checklist
- Failure mode mitigations
Grasp
Grasp is the prerequisite for keeping control light.
- People
- Capability
- Trust level
- Work speed
- Expected quality
- Work
- Goal
- Deadline
- Importance
- Dependencies
- Means
- Tools
- Budget
- Permissions
- Constraints
If grasp is vague and you increase control, error grows. The stronger the grasp, the lighter the control can be.
Intent
Intent pins the higher-level purpose and the end state in short sentences.
- Clear intent
- Frees choice of means
- Keeps decisions moving even when surprises happen
- Stabilizes priorities
- Vague intent
- Orders drift into details
- Supervision collapses into step-by-step instruction
- Initiative oscillates between runaway and paralysis
Orders
Write orders around outcomes. Keep procedures to the minimum needed.
- Too-early orders constrain with insufficient information
- Too-late orders miss opportunities
- Too-long orders create interpretation forks
Discipline
Discipline is not step-by-step instruction. It is behavior templates.
- Priority templates
- Reporting templates
- Exception handling templates
- Delegation scope templates
When discipline is in place, supervision decreases. When discipline breaks, orders increase.
Control and initiative
Control is a safety device. Do not treat it as the steering wheel.
- What to forbid
- What to delegate
- Where to stop
Initiative is creativity within the intent boundary.
- Delegate choice of means
- Allow proposing alternatives
- Allow local optimization within bounds
Functional requirements:
- Intent is short
- Boundaries are explicit
- Reporting is fast
- Supervision is result-focused
Three elements that support grasp
Alignment
Alignment is the force that points movement in the same direction.
- Values
- Discipline
- Trust
- Role understanding
- Shared terminology
Situational awareness
Situational awareness is the mechanism to learn the present state quickly.
- Progress
- Location
- Remaining capacity
- Change
- Risk
Execution supervision
Supervision is not doing the work for them.
- Verify results
- Stop deviations
- Preserve learning
Translation to an agent organization
Vocabulary mapping
| Source term | Meaning in agent organization | Implementation unit |
|---|
| Commander | Orchestrator | Command process |
| Subordinate units | Subagents | Worker pool |
| Mission | Goal | Requirements spec |
| Intent | Intent | Intent document |
| Order | Task assignment | Instruction message |
| Control | Guardrails | Permission constraints |
| Initiative | Autonomous execution | Discretion envelope |
| Alignment | Alignment and trust | Shared norms |
| Situational awareness | State observation | Telemetry |
| Execution supervision | Evaluation and stop | Review and interrupt |
Aim
- Fix direction via intent
- Keep control light while stopping deviation
- Accelerate correction via situational awareness and supervision
Command cycle
The orchestrator runs a loop:
- Observe
- State
- Reports
- External environment
- Orient
- Align to intent
- Update priorities
- Assess risk
- Decide
- Issue additional orders
- Reallocate
- Stop
- Act
- Send instructions
- Adjust envelope
- Set supervision
The shorter the loop, the more timely the orders can be.
Implementation patterns
Pin intent first
Create an intent document first and share it with everyone.
Keep it short.
Use mission-type orders
Write outcomes, not procedures.
Avoid enumerating branching paths.
Use the envelope for control
Define the allowed operating range via an envelope:
- Allowed tools
- Whether external writes are allowed
- Money limit
- Time limit
- Iteration limit
- Ask-first boundaries
- Stop conditions
Use standard reporting for situational awareness
Avoid free-form reports.
Use short fixed formats.
Supervision in two layers
- Automated supervision
- Constraint violations
- Budget and time overruns
- Dependency breakage
- Human supervision
- Important decisions
- Destructive changes
- External exposure
Pair supervision with explicit stop authority.
Adoption steps
Stage 0: Organization design
- Define roles
- Register capabilities
- Define responsibility boundaries for failure modes
Stage 1: Standardize intent
- Intent template
- Acceptance criteria
- Prohibitions
Stage 2: Standardize order format
- Mission-type instruction
- Deadlines and deliverables
- Explicit envelope
- Explicit stop conditions
Stage 3: Instrument situational awareness
- State store
- Progress events
- Metrics
Stage 4: Operate supervision
- Automatic stops
- Human review
- Postmortems
Evidence discipline
- Attach evidence to each important claim
- Separate observation from inference
- If it cannot be observed, stop and report
- Completion is never inferred from intent, task labels, checkbox state, scenario ID strings, helper presence, import presence, or a delegate's
DONE claim
- Completion requires both positive evidence and negative evidence; if either side is missing, return
NEEDS_FIX and request the missing evidence from the responsible subordinate agent
Examples of evidence:
- File path and line number
- Summary of commands run
- Explanation of diffs
Evidence-gated completion protocol
Use this protocol for every task that can be accepted, checked off, approved, or reported as complete.
- Positive evidence proves the required implementation now exists, is wired into production callers, and is covered by commands or tests
- Negative evidence proves prohibited states are absent, such as old owners, forbidden imports, stale callers, generated hand edits, secret leakage, bypasses, or route contamination
- Reviewer evidence proves the responsible reviewer inspected both positive and negative evidence and returned
Approve
- Command evidence proves repository-approved commands ran through the allowed scripts and did not use direct tools or bypasses
- A completion report is perfect only when it includes positive evidence, negative evidence, reviewer evidence, command evidence, residual risks, and open items
- If the report is incomplete, contradictory, unsupported by
path:line, or missing a required negative check, return NEEDS_FIX; keep returning NEEDS_FIX to the responsible subordinate agent until the report is complete
- Treat missing evidence, unchecked constraints, skipped negative checks, premature
DONE, or task-order drift as a subordinate instruction violation, not as a neutral blocker
- When a subordinate agent violates an order, explicitly call out the violation, name the agent role, cite the violated instruction, and issue a corrective order; do not soften it into a risk or optional follow-up
- If a task includes removal, migration, deduplication, security, dependency boundary, generated artifact, or storage/secret claims, negative evidence is mandatory
- If the old implementation can still be found but is claimed to be non-production, require caller/callee evidence showing every production caller moved away
- If the evidence only proves helper/type/import/test-name existence, reject completion unless it also proves ownership, caller wiring, and old-state absence
Correction and stop conditions
- NEEDS_FIX
- Missing positive evidence from a subordinate report
- Missing negative evidence from a subordinate report
- Missing reviewer approval for a review-gated task
- Incomplete or contradictory completion report
- Premature
DONE, premature checkbox update, skipped dependency gate, or task-order drift
- Any fixable implementation or report defect owned by a subordinate agent
- ASK_FIRST_REQUIRED
- Dependency additions/updates
- Permission boundaries
- Destructive changes
- External side effects
- Secrets
- Legal and licensing
- BLOCKED
- Missing external information not owned by a subordinate agent
- No access
- Spec contradictions
- Required external decision
- Required agent/tool is not allowed by permissions
- Ask-first item cannot proceed without user approval
- CONFLICT
- Areas likely to conflict with parallel tasks
Guardrails
- Project-specific rules have highest priority
- Do not execute Ask-first items; stop and report
- Do not bypass lint or format
- Do not hand-edit generated artifacts
- Avoid cyclic delegation
Included assets
- This skill is documentation-first
- Scripts and assets are omitted
- Reference:
references/shiki-no-yoketsu.ja.md
Operations
Templates are parts.
Operations are the sequence.
Preparation
- Read project-specific rules
- Pin Ask-first boundaries
- Pin generated artifacts and required quality gates
- Pin allowed and disallowed tools
Mission start
1 Create a grasp card
- One card per delegatee
- Fill speed, quality, and boundaries
2 Create an intent brief
- Fill MISSION and END_STATE first
- Fill INVARIANTS and NON_GOALS
- Fill ACCEPTANCE
3 Draw the envelope
- Fill TOOLS and OWNERSHIP_BOUNDARIES
- Fill ASK_FIRST and STOP_CONDITIONS
- Fill TIME_LIMIT and ITERATION_LIMIT
Decomposition and allocation
4 Split tasks
- Keep between 3 and 9
- List dependencies
- Do not parallelize tasks that touch the same area
5 Issue Work Order v1+
- One message per task
- Align Goal to END_STATE
- Copy Invariants from the intent brief
- Copy Envelope from the envelope
- State the evidence policy
Situational awareness and supervision
6 Receive replies
- Accept only the reply format
- For each claim, inspect PATH and LINE
- Reject replies that do not include both Positive evidence and Negative evidence when completion is claimed
- Return
NEEDS_FIX to the responsible subordinate until the report is complete; do not downgrade missing evidence to a risk or follow-up
- Name the subordinate instruction violation when a required check or evidence class is omitted
7 Accept or request changes
- Accept if ACCEPTANCE is met
- Request changes if implementation is wrong but evidence is sufficient to diagnose it
- Return
NEEDS_FIX if evidence is thin, missing, contradictory, or lacks required negative checks
- Return
BLOCKED only for missing external decisions, no access, permission/tool impossibility, or true spec contradictions
- Stop on boundary violations
8 Integrate
- Record into the integration memo
- Keep Decisions and Next actions in short sentences
- Update the risk log
Stop and approval
When ASK_FIRST_REQUIRED is raised, stop.
After you receive an approval decision, update the envelope and orders.
Lock in learning
After the mission, record a postmortem.
Reflect changes into the next envelope and ACCEPTANCE.
Parallel operations
- Partition parallel work by area
- If shared files are likely, remove them from parallelization
- Stop on CONFLICT and return to reallocation
Templates
Replacement targets use the __NAME__ form.
Replace values wrapped with __.
Grasp card
AGENT: __AGENT__
ROLE: __ROLE__
STRENGTHS:
- __STRENGTH_1__
- __STRENGTH_2__
- __STRENGTH_3__
WEAKNESSES:
- __WEAKNESS_1__
- __WEAKNESS_2__
- __WEAKNESS_3__
SPEED: __SPEED__
EXPECTED_QUALITY: __EXPECTED_QUALITY__
TRUST: __TRUST__
ALLOWED_TOOLS:
- __TOOL_1__
- __TOOL_2__
HARD_BOUNDARIES:
- __BOUNDARY_1__
- __BOUNDARY_2__
NOTES: __NOTES__
Intent brief
MISSION: __MISSION__
END_STATE: __END_STATE__
PRIORITY_ORDER:
- __PRIORITY_1__
- __PRIORITY_2__
- __PRIORITY_3__
INVARIANTS:
- __INVARIANT_1__
- __INVARIANT_2__
NON_GOALS:
- __NON_GOAL_1__
- __NON_GOAL_2__
TIMEBOX: __TIMEBOX__
ASK_FIRST:
- __ASK_FIRST_1__
- __ASK_FIRST_2__
ACCEPTANCE:
- __ACCEPTANCE_1__
- __ACCEPTANCE_2__
REPORTING_RHYTHM: __REPORTING_RHYTHM__
Envelope
TOOLS:
- __TOOL_1__
- __TOOL_2__
EXTERNAL_WRITES: __EXTERNAL_WRITES__
MONEY_LIMIT: __MONEY_LIMIT__
TIME_LIMIT: __TIME_LIMIT__
ITERATION_LIMIT: __ITERATION_LIMIT__
OWNERSHIP_BOUNDARIES:
- __OWNERSHIP_BOUNDARY_1__
- __OWNERSHIP_BOUNDARY_2__
ASK_FIRST:
- __ASK_FIRST_1__
- __ASK_FIRST_2__
STOP_CONDITIONS:
- NEEDS_FIX
- ASK_FIRST_REQUIRED
- BLOCKED
- CONFLICT
Mission-type order
TASK: __TASK__
DELIVERABLES:
- __DELIVERABLE_1__
- __DELIVERABLE_2__
DUE: __DUE__
SCOPE: __SCOPE__
CONSTRAINTS:
- __CONSTRAINT_1__
- __CONSTRAINT_2__
EVIDENCE:
- __EVIDENCE_1__
- __EVIDENCE_2__
REPORTING: __REPORTING__
STOP:
- __STOP_1__
- __STOP_2__
Situation report
STATUS: __STATUS__
INTENT_ECHO: __INTENT_ECHO__
PROGRESS: __PROGRESS__
DELIVERED:
- __DELIVERED_1__
NEXT:
- __NEXT_1__
BLOCKERS:
- __BLOCKER_1__
DECISIONS_NEEDED:
- __DECISION_1__
RISKS:
- __RISK_1__
EVIDENCE:
- __EVIDENCE_1__
COMMANDS:
- __COMMAND_1__
Acceptance memo
RESULT: __RESULT__
EVIDENCE_INDEX:
- __EVIDENCE_INDEX_1__
RISKS:
- __RISK_1__
OPEN_ITEMS:
- __OPEN_ITEM_1__
NEXT_ACTIONS:
- __NEXT_ACTION_1__
Postmortem
ACHIEVED:
- __ACHIEVED_1__
NOT_ACHIEVED:
- __NOT_ACHIEVED_1__
CAUSES:
- __CAUSE_1__
CONTROLS_THAT_HELPED:
- __CONTROL_HELPED_1__
CONTROLS_THAT_DID_NOT_HELP:
- __CONTROL_DID_NOT_HELP_1__
CHANGES_FOR_NEXT_TIME:
- __CHANGE_NEXT_TIME_1__
Work Order v1+ orchestrator to subagent
Work Order v1+
- Target agent: __AGENT__
- Goal: __END_STATE__
- Background: __BACKGROUND__
- Commander intent:
- Priority: __PRIORITY__
- Invariants:
- __INVARIANT_1__
- __INVARIANT_2__
- Timebox: __TIME_LIMIT__
- Success criteria:
- __ACCEPTANCE_1__
- __ACCEPTANCE_2__
- Non-goals:
- __NON_GOAL_1__
- Constraints / Guardrails:
- Envelope:
- Tools: __TOOLS__
- External writes: __EXTERNAL_WRITES__
- Ownership boundaries: __OWNERSHIP_BOUNDARIES__
- Iteration limit: __ITERATION_LIMIT__
- Ask first: __ASK_FIRST__
- Stop conditions: __STOP_CONDITIONS__
- No generated hand-edits; no lint or format bypass.
- No cyclic delegation.
- Context to read:
- __PATH_1__
- Searches to run:
- glob: __GLOB_1__
- grep: __REGEX_1__ include __PATTERN_1__
- Steps:
1. Observe
- How: __HOW__
- Expected: __EXPECTED__
- If fail: __TRIAGE__
2. Decide
3. Act
4. Verify
- Commands to run:
- __COMMAND_1__
- Evidence required in your reply:
- __EVIDENCE_POLICY__
- Completion gate:
- Positive evidence: __POSITIVE_EVIDENCE_REQUIRED__
- Negative evidence: __NEGATIVE_EVIDENCE_REQUIRED__
- Reviewer evidence: __REVIEWER_EVIDENCE_REQUIRED__
- Command evidence: __COMMAND_EVIDENCE_REQUIRED__
- If any item is missing or contradictory, return `NEEDS_FIX` instead of `DONE`.
- Correction or stop conditions return immediately:
- NEEDS_FIX: __REASON_NEEDS_FIX__
- ASK_FIRST_REQUIRED: __REASON_ASK_FIRST__
- BLOCKED: __REASON_BLOCKED__
- CONFLICT: __REASON_CONFLICT__
- Response format strict:
- Status: __STATUS__
- What I did: __WHAT_I_DID__
- Evidence: __EVIDENCE__
- Commands: __COMMANDS__
- Notes/Risks: __NOTES_RISKS__
Reply format subagent to orchestrator
Status: __STATUS__
Intent echo:
- __INTENT_ECHO__
What I did:
- __WHAT_I_DID_1__
Delivered:
- __DELIVERED_1__
Positive evidence:
- __PATH_1__:__LINE_1__ __REQUIRED_STATE_NOW_EXISTS__
Negative evidence:
- __PATH_OR_SEARCH_1__ __PROHIBITED_STATE_IS_ABSENT__
Reviewer evidence:
- __REVIEWER_VERDICT__ __REVIEWER_REFERENCE__
Instruction violations:
- __AGENT_ROLE__ violated __INSTRUCTION__ by __VIOLATION__; corrective order: __ORDER__
Next:
- __NEXT_1__
Blockers:
- __BLOCKER_1__
Decisions needed:
- __DECISION_1__
Risks:
- __RISK_1__
Evidence:
- __PATH_1__:__LINE_1__ __CLAIM_1__
Commands:
- __COMMAND_1__: __RESULT_1__
Integration memo
Plan:
- __TASK_1__: __AGENT_1__ __DOD_1__
Decisions:
- __DECISION_1__ __REASON_1__
Next actions:
- __ACTION_1__
Evidence index:
- __PATH_1__:__LINE_1__
Risk log:
- __RISK_1__: __MITIGATION_1__
Acceptance checklist
Orchestrator:
- END_STATE is observable
- ACCEPTANCE is met
- Each claim has evidence
- Positive evidence and negative evidence are both present for every completion claim
- Reviewer evidence is present when a review gate applies
- Completion reports with missing evidence are returned as
NEEDS_FIX, not accepted as partial success
- NON_GOALS are not violated
- Ask-first boundaries are not crossed
- No hand-edits to generated artifacts
- No lint/format bypass
Subagent:
- INTENT_ECHO is short
- Stays within envelope boundaries
- Reporting is short and templated
- Can propose alternatives
- Stops before Ask-first boundaries
Failure mode mitigations
- Intent becomes long
- Orders drift into procedures
- Move TASK, DELIVERABLES, and DUE back to the top
- Control keeps growing
- Reports scatter
- Standardize on situation report
- Supervision collapses into doing the work
- Shift to acceptance and stop authority
- Evidence is thin
- Require PATH:LINE and request changes
Troubleshooting
If this skill does not appear in the list:
- Ensure the file is named
SKILL.md (uppercase)
- Ensure the YAML frontmatter contains
name and description
- Ensure the directory name matches
name
- Ensure the name is unique
- Ensure
permission.skill is not deny
