Sous Chef: Global Orchestration Rules
These rules apply to ALL orchestration sessions, whether following a recipe or operating ad-hoc. They are permanent — they cannot be overridden by individual recipe kitchen_rules or plan-file instructions.
MULTI-PART PLAN SEQUENCING — MANDATORY
When plan_parts contains more than one file (Part A, Part B, …):
- Process parts strictly in order: A before B, B before C, etc.
- After implementing each part: test it (
test_check) and merge it (merge_worktree) into the base branch before implementing the next part. - The next part's worktree MUST be created from the post-merge state of the base branch — never from the same commit as the previous part.
- Never invoke
implement-worktree-no-mergefor Part N+1 while Part N's worktree is unmerged.
This rule applies whether or not you are following a recipe, and whether or not Part B's plan file says "Part A is a prerequisite." The orchestrator is responsible for enforcing this regardless of what the plan says.
SKILL_COMMAND FORMATTING — MANDATORY
When calling run_skill, the skill_command argument MUST be a space-separated token
string — never a structured document or markdown section list.
- Substitute
${{ context.* }}and${{ inputs.* }}placeholders with their resolved values and pass the result VERBATIM torun_skill. - Do NOT add markdown headers (
##), labels, notes, or explanatory prose toskill_command. It is not a document — it is a command string. - Path arguments are single tokens:
/path/to/file.md— not a labeled section. - Extra arguments from a step
note:are appended as space-separated tokens.
Wrong: /autoskillit:implement-worktree-no-merge\n\n## Plan Path\n/path/plan.md\n\n## Branch\nimpl-926
Right: /autoskillit:implement-worktree-no-merge /path/plan.md impl-926
This applies to ALL skills, including bare-placeholder steps where you supply values
at runtime (/autoskillit:arch-lens-{slug} {context_path} → substitute, then pass verbatim).
CONTEXT LIMIT ROUTING — MANDATORY
When run_skill returns needs_retry=true for any step:
- If
retry_reason: resumeANDsubtype: stale→ re-execute the same step (decrement the retries counter). A stale session was killed by the hung-process watchdog — this is NOT a context limit. Do NOT followon_context_limit. If retries are exhausted, followon_exhausted. - If
retry_reason: resumeANDsubtype≠staleAND the step defineson_context_limit→ followon_context_limit. The worktree or partial state is on disk; route to the designated recovery step (typicallytestorretry_worktree) to check whether partial work was sufficient. API infrastructure errors (overload, 529, ECONNRESET) also produceretry_reason=resumewithinfra_exit_category="api_error"— route them identically to context exhaustion. Theinfra_exit_categoryfield is informational only ("completed","context_exhausted","api_error","process_killed"). - If
retry_reason: resumeANDsubtype≠staleAND the step has noon_context_limit→ fall through toon_failure. - If
retry_reason: drain_raceAND the step defineson_context_limit→ followon_context_limit. The channel signal confirmed session completion; stdout was not fully flushed before kill. Partial progress is confirmed — treat identically toresumefor routing purposes. - If
retry_reason: drain_raceAND the step has noon_context_limit→ fall through toon_failure. - If
retry_reason: completed_no_flushAND the step defineson_context_limit→ followon_context_limit. The session exited with empty stdout but write evidence confirms files were written to the worktree. Partial progress is confirmed — treat identically toresumefor routing purposes. - If
retry_reason: completed_no_flushAND the step has noon_context_limit→ fall through toon_failure. - If
retry_reason: empty_output→ fall through toon_failure. The session produced no output AND no write evidence (no Write/Edit calls, no filesystem writes). Do NOT route toon_context_limiteven if defined. - If
retry_reason: path_contamination→ fall through toon_failure. The session wrote files outside its working directory. This is a CWD boundary violation, not a context limit. Do NOT route toon_context_limiteven if defined. - If
retry_reason: thinking_stallANDlifespan_startedis true AND the step defineson_context_limit→ followon_context_limit. The model consumed tokens (thinking blocks) but produced no final output. Prior tool calls suggest partial progress on disk. - If
retry_reason: thinking_stallANDlifespan_startedis false → fall through toon_failure. No progress was made. - If
retry_reason: idle_stallANDlifespan_startedis true AND the step defineson_context_limit→ followon_context_limit. The idle watchdog killed the session, but prior tool calls suggest partial progress on disk. - If
retry_reason: idle_stallANDlifespan_startedis false → fall through toon_failure. No progress was made. - If
retry_reason: early_stopANDhas_progress_evidenceis true in the result AND the step defineson_context_limit→ followon_context_limit. The model made progress (wrote files or created a worktree) but stopped before emitting the completion marker. Partial progress exists on disk. - If
retry_reason: early_stopANDhas_progress_evidenceis false → fall through toon_failure. - If
retry_reason: zero_writesANDhas_progress_evidenceis true in the result AND the step defineson_context_limit→ followon_context_limit. The model made filesystem contact but made no Write/Edit tool calls. Partial progress may exist on disk. - If
retry_reason: zero_writesANDhas_progress_evidenceis false → fall through toon_failure. - If
retry_reason: stale→ decrement theretriescounter for this step. Re-execute the same step if retries remain. If retries are exhausted, fall through toon_failure. Do NOT route toon_context_limit— stale is a transient failure, not a context limit. No partial progress is assumed.
Worktree-stale carve-out: When a step that invokes a worktree-creating skill
(implement-worktree-no-merge, implement-worktree, implement-experiment) returns
retry_reason: stale (or retry_reason: resume with subtype: stale), re-execute the
step without consuming the retries budget. Stale means the session produced nothing
useful — the worktree orphan concern that motivates retries: 0 does not apply.
This is a one-shot retry: if the retry also goes stale, fall through to on_failure.
Before re-executing, if the stale result captured worktree_path, remove the empty
worktree (git worktree remove --force <path>) to prevent orphaned worktrees.
For implement-worktree-no-merge specifically:
on_context_limitroutes toretry_worktreein standard recipes.- Use
/autoskillit:retry-worktree— pass the existingworktree_pathfrom the partial session's output. The worktree is on disk with all commits made so far. - Do NOT call
implement-worktree-no-mergeagain. A new call creates a fresh timestamped worktree, discarding all partial progress.
When a completed worktree implementation needs to be redone (e.g., after a plan revision):
- Call
implement-worktree-no-mergeon the revised plan (creates a fresh worktree). - Clean up the old worktree explicitly if needed.
Summary: needs_retry=true + retry_reason=resume + subtype=stale → re-execute step (decrement retries; on_exhausted when budget gone).
needs_retry=true + retry_reason=resume + subtype≠stale + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=resume + subtype≠stale + no on_context_limit → on_failure.
needs_retry=true + retry_reason=drain_race + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=drain_race + no on_context_limit → on_failure.
needs_retry=true + retry_reason=completed_no_flush + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=completed_no_flush + no on_context_limit → on_failure.
needs_retry=true + retry_reason=empty_output → on_failure.
needs_retry=true + retry_reason=path_contamination → on_failure.
needs_retry=true + retry_reason=thinking_stall + lifespan_started=true + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=thinking_stall + lifespan_started=false → on_failure.
needs_retry=true + retry_reason=idle_stall + lifespan_started=true + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=idle_stall + lifespan_started=false → on_failure.
needs_retry=true + retry_reason=early_stop + has_progress_evidence=true + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=early_stop + has_progress_evidence=false → on_failure.
needs_retry=true + retry_reason=zero_writes + has_progress_evidence=true + step has on_context_limit → follow on_context_limit.
needs_retry=true + retry_reason=zero_writes + has_progress_evidence=false → on_failure.
needs_retry=true + retry_reason=stale → decrement retries counter → on_failure when exhausted (no partial progress, not a context limit).
needs_retry=true + retry_reason=stale + worktree-creating step → one-shot re-execute (bypasses retries budget; on_failure if repeated stale).
AUDIT-IMPL ACROSS MULTI-GROUP PIPELINES
audit-impl uses a SHA-based diff: it compares the worktree HEAD against the
merge-base with the base branch, scoping the diff to exactly that group's changes.
Rules:
- Pass the specific plan file for each group (not a combined plan).
- Run
audit-implbefore merging — it inspects the unmerged worktree diff. - After merging a group, the next group's
audit-implwill correctly see only that group's diff against the now-updated base branch. - Never run one
audit-implcall against multiple merged groups — the diff scope will be too broad and the audit will be inaccurate.
READING AND ACTING ON plan_parts= OUTPUT
make-plan emits plan_parts= as a flat newline-delimited ordered list of
absolute paths:
plan_parts = /abs/path/to/plan_part_a_....md
/abs/path/to/plan_part_b_....md
Act on this list as follows:
- Implement parts in the order listed (top to bottom).
- Merge each part (
merge_worktree) before moving to the next. - Each subsequent part's worktree must be created from the post-merge state of the base branch — not from the original base commit.
- Never batch-implement multiple parts from the same base commit.
MULTIPLE ISSUES — MANDATORY
When the user provides more than one issue or task in a single request:
If the user says "parallel" (or "run in parallel", "simultaneously", "at the same time", "concurrently"):
a. Build execution map first. Call
run_skillwith/autoskillit:build-execution-mappassing all issue numbers. This produces anexecution_mapJSON artifact at the emitted path.b. Read the execution map. Parse the JSON to extract
groupsandmerge_order.c. Dispatch groups in order. For each group in ascending
groupnumber:- If
parallel: true→ launch all issues in the group as independent pipeline sessions simultaneously, using the wavefront scheduling rule (defined in the section below). - If
parallel: false→ run the group's issues one at a time in sequence.
d. Merge-wait between groups. Group N+1 must NOT begin cloning until ALL of Group N's PRs have merged to the base branch. This ensures every group's clones capture a base SHA that includes all prior groups' changes. Use the MERGE PHASE rules to merge each group's PRs, following the
merge_orderfrom the map for intra-group merge sequencing.e. Fallback. If
build-execution-mapfails or returns an error, fall back to launching all N pipelines immediately (current behavior). Do not block dispatch on map failure.- If
If the user says "sequential" (or "one at a time", "in order", "one by one") → run them one at a time without asking.
If the user does not specify → ask exactly one question using AskUserQuestion:
"Do you want to run these sequentially (one at a time) or in parallel (all at once)?" Present exactly two options. Nothing else.
NEVER:
- Claim "the recipe handles one issue at a time" — each pipeline instance is fully independent (separate clones, branches, PRs). Parallel execution is fully supported.
- Suggest switching to
implementation-groups— that recipe is for coordinated multi-issue planning with a shared plan, not independent parallel execution. - Suggest picking a subset of the given issues — the user chose the scope.
- Offer any option other than sequential or parallel when asking.
- Ask the user to clarify scope, prioritization, or issue ordering.
PARALLEL STEP SCHEDULING — MANDATORY
This rule applies whenever you are running multiple pipelines in parallel (run_mode=parallel or user says "parallel"). Within each batched round, pipeline steps have two speeds:
Fast steps — MCP tool calls that complete in seconds:
run_cmd, clone_repo, create_unique_branch, fetch_github_issue,
claim_issue, merge_worktree, test_check, reset_test_dir, classify_fix,
push_to_remote
Slow steps — headless sessions that take minutes:
Any run_skill invocation (investigate, implement, audit, review, etc.)
Wavefront Scheduling Rule
Complete all fast steps for ALL pipelines first. Before launching any slow step, advance every pipeline through its pending fast steps. Continue re-inspecting after each fast-step batch until no pipeline has a fast step pending.
Launch all slow steps together in one parallel batch. Once all pipelines are aligned at a slow step boundary (every pipeline's next pending step is a
run_skill), launch all of them simultaneously so they overlap in wall-clock time.Never launch a slow step for one pipeline while another pipeline still has fast steps pending. This is the most critical rule: a batched round waits for the slowest step in the batch. A fast step launched alongside a slow step completes instantly but sits idle until the slow step finishes — wasting wall-clock time and blocking re-inspection.
Advance every active pipeline in every round. A pipeline is "active" if it has not reached
doneorescalate_stop. In every batched round, every active pipeline MUST receive at least one step — either a fast step is drained or a slow step is launched. Never leave an active pipeline idle for an entire round while sibling pipelines are progressing. If a pipeline has completed all itsplan_partsand only has finalization steps remaining (push, merge, close), it is still active and must be advanced.
Rationale
Batched rounds wait for the slowest step in the batch. If a slow run_skill is launched
alongside a fast run_cmd, the fast step completes instantly but cannot trigger the next
fast step for its pipeline until the entire batch (including the slow session) finishes.
Draining all fast steps first ensures every pipeline arrives at the slow-step boundary
simultaneously, after which all slow steps run in parallel and their wall-clock time overlaps.
EXECUTION MAP — GROUP DISPATCH — MANDATORY
When dispatching from an execution map:
Group iteration is outer loop. The group number (1, 2, 3, ...) is the primary ordering. Within each group, the wavefront scheduling rule governs step interleaving.
Merge-wait is mandatory between groups. After all pipelines in Group N complete (including their merge phase), verify all Group N PRs have merged to the base branch before starting Group N+1. This prevents Group N+1 from cloning a stale base.
merge_order governs intra-group PR merge sequencing. Within a parallel group, merge PRs in the order specified by
merge_order(not by completion time). This minimizes merge conflicts by merging simpler changes first.Single-issue groups skip wavefront. If a group has
parallel: falseor contains only one issue, run it as a single pipeline — no wavefront scheduling needed.Do not pause for confirmation between groups. Once merge-wait verifies all Group N PRs have merged, dispatch Group N+1 immediately. NEVER use AskUserQuestion to ask whether to proceed to the next group.
Handle deferred issues before dispatching any group.
After reading the execution map, check for
has_deferred: true.If
has_deferredis false (no deferrals): proceed directly to Group 1 dispatch.If
has_deferredis true:6a. Pre-dispatch freshness check. Before presenting any escalation question, re-query the current label state of ALL unique blocker issue numbers across all
deferred_issuesentries in a single batched GraphQL request using aliases:query { i887: repository(owner:"<OWNER>", name:"<REPO>") { issue(number:887) { labels(first:20) { nodes { name } } } } i912: repository(owner:"<OWNER>", name:"<REPO>") { issue(number:912) { labels(first:20) { nodes { name } } } } }For each blocker, check whether the
in-progresslabel is still present. If a blocker's label has been removed since the map was built, remove it from that deferred issue'sblocked_bylist. If all blockers for a given deferred issue have cleared, that issue is no longer deferred — collect it in an "auto-cleared" list for the supplementary map (step 6e). Never issue individualgh issue viewcalls per blocker — always batch into a single GraphQL request.6b. Present AskUserQuestion for each still-deferred issue. For each deferred issue where at least one blocker's
in-progresslabel is still present, callAskUserQuestion:"Issue #N (title) cannot be dispatched safely. It conflicts with in-progress issue(s): #M1 (title1), #M2 (title2). Conflict: {reasoning}
Choose:
- Wait — Hold #N; retry after the blocking issues complete
- Proceed anyway — Dispatch #N now, accepting conflict risk
- Drop — Remove #N from this session entirely"
Headless-mode rule (MANDATORY): When
AskUserQuestionis denied by the hook (the deny message says "proceed without user confirmation" — this refers to general tool behavior, NOT this decision), treat the response as Wait. Do NOT interpret the deny message as permission to proceed. This is the explicit safe default for unattended sessions.6c. Route based on user answer (or Wait default):
Wait: Hold the issue. At each group-completion barrier (after all
run_skillcalls in a group return — the natural inter-group barrier in both queue-mode and classic-mode), re-check ALL outstanding Wait-path blockers via a single batched GraphQL aliases query. When all blockers for a Wait issue have cleared, move it to the auto-cleared list for step 6e. After the final group completes, if any Wait issues remain uncleared, report them as skipped in the session result.Proceed: Add the issue to a new sequential group inserted at the end of the dispatch sequence (after all other groups). This is transparent in both merge modes: in queue-mode (#1268), the pipeline self-merges; in classic mode,
merge-prshandles it. Do not create one group per Proceed issue — batch all Proceed issues into the single final group together.Drop: If the issue has already been claimed (its
in-progresslabel is set by this session), callrelease_issueto remove it. Then exclude the issue from all dispatch, merge, and reporting. Do not mark it as failed — it is not a failure.
6d. Zero-non-deferred-groups edge case. When all target issues are deferred and no dispatch groups exist (group_count is 0 after removing deferred issues), skip group dispatch entirely. Enter an explicit poll loop:
- Wait
github.deferred_poll_interval_seconds(default: 60 seconds between checks). - Re-query ALL outstanding blocker labels via a single batched GraphQL aliases query.
- If at least one deferred issue becomes unblocked (all its blockers cleared), proceed to step 6e for those issues.
- Repeat until the first unblocked issue is found OR the elapsed time exceeds
github.deferred_poll_timeout_seconds(default: 1800 seconds / 30 minutes). - On timeout: report all deferred issues as skipped. Set session result
success: falsewithfailure_reason: "All target issues deferred due to in-progress conflicts — human decision required". Exit.
If in headless mode and all issues default to Wait with zero dispatch groups: skip the poll loop and immediately set
success: falsewith the abovefailure_reason. Do not poll indefinitely in unattended sessions.6e. Supplementary map for auto-cleared and freshness-cleared issues. When one or more Wait/freshness-cleared issues become eligible:
- Re-run
build-execution-mapfor the newly eligible issues only — pass their issue numbers as arguments. This is a full analysis (pairwise + cross-assessment), not a passthrough. The supplementary map may itself produce new deferrals if remaining in-progress issues conflict with the eligible set. - If the supplementary map returns
has_deferred=true, apply steps 6b and 6c to the newly deferred issues before dispatching the supplementary groups. In headless mode, treat all new deferrals as Wait (same rule as 6b). Issues that remain deferred after this re-entry are skipped and reported in the session result. - Dispatch the resulting dispatch groups as additional sequential group(s) appended after the last completed group.
- Apply the same group-boundary merge-wait rule before dispatching the supplementary groups.
STEP NAME IMMUTABILITY — MANDATORY
The step_name passed to run_skill (and all other recipe-step tools that accept
step_name) must be the exact value from the recipe YAML with: block.
NEVER append clone numbers, instance indices, retry counts, or any other disambiguation strings. The telemetry layer aggregates all invocations of the same logical step automatically — suffixing produces garbage rows in token and timing tables.
Correct:
with:
step_name: implement
Wrong (produces garbage):
with:
step_name: implement-30 # ← NEVER DO THIS
This rule applies whether running sequential or parallel pipelines. Each clone or parallel run of the same step reports under the same canonical step name.
MODEL PROPAGATION — MANDATORY
MODEL PROPAGATION — When the user specifies a model (e.g. "use opus"), apply it to the model parameter of ALL run_skill calls for steps that declare a model: field — including follow-on steps (retry_worktree, fix, resolve_review, resolve_ci, conflict resolution). All run_skill steps in orchestrated recipes must declare a model: field; steps that omit it are ineligible for propagation and silently bypass user model selection.
MERGE PHASE — MANDATORY
This rule applies whenever the orchestrator must merge one or more open PRs, whether produced by a single pipeline or by N parallel pipelines.
1. Detect merge queue availability — once per orchestration session
Before initiating any merge, run the following detection step via run_cmd (not a
headless session):
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) &&
OWNER=${REPO%%/*} && REPO_NAME=${REPO##*/} &&
BRANCH="<base_branch>" && # substitute the PR's target branch (e.g. "main", "develop")
gh api graphql -f query="query {
repository(owner:\"$OWNER\", name:\"$REPO_NAME\") {
mergeQueue(branch:\"$BRANCH\") { id }
}
}" | jq -r 'if .data.repository.mergeQueue != null then "true" else "false" end' || echo false
Capture the result as queue_available. If gh api graphql fails (auth error, network
error), the || echo false fallback ensures queue_available defaults to "false",
routing to the safe sequential (non-queue) path rather than leaving the variable unset.
Run this once per orchestration run, not per-PR.
After detecting queue availability, also detect auto-merge availability:
gh api graphql -f query="query {
repository(owner:\"$OWNER\", name:\"$REPO_NAME\") {
autoMergeAllowed
}
}" | jq -r '.data.repository.autoMergeAllowed // false' || echo false
Capture the result as auto_merge_available. If detection fails, default to "false".
Note: All three recipes (implementation, implementation-groups, remediation)
perform both detections automatically via check_merge_queue + check_auto_merge —
do not repeat them manually when following a recipe.
2. Route based on queue availability and auto-merge availability
The recipes route on the four-cell matrix queue_available × auto_merge_available:
queue_available |
auto_merge_available |
Recipe path |
|---|---|---|
true |
true |
enable_auto_merge → wait_for_queue |
true |
false |
queue_enqueue_no_auto → wait_for_queue |
false |
true |
direct_merge → wait_for_direct_merge |
false |
false |
immediate_merge → wait_for_immediate_merge |
When queue_available == true: GitHub's merge queue intercepts every merge
request on the branch regardless of the --auto flag. Both queue cells route
through wait_for_queue (the merge-queue-aware waiter). The
enable_auto_merge cell uses --auto so the queue serializes via GitHub
auto-merge; the queue_enqueue_no_auto cell (condition:
queue_available == true and auto_merge_available == false) uses plain --squash
because the repository's autoMergeAllowed=false setting causes --auto to be
rejected by the API auto-merge gate before the queue interception.
When queue_available == false: there is no queue, so behaviour matches
the historical paths — direct_merge waits via auto-merge, immediate_merge
executes synchronously.
- If following a recipe:
route_queue_modeselects the correct cell automatically fromcontext.queue_availableandcontext.auto_merge_available. - NEVER use
gh pr merge --squash --autowhenauto_merge_available == false, regardless ofqueue_available. The--autoflag is rejected by GitHub's API auto-merge gate before the queue intercepts. Use plaingh pr merge --squash; if a queue exists on the branch the queue still enqueues the call. - NEVER route a queue+no-auto enqueue call through
wait_for_immediate_merge— its 5-minute poll is too short for a busy queue and on timeout the recipe reportsmerge unconfirmedeven though the PR will eventually merge.
For ad-hoc (off-recipe) merges:
- When
queue_available=true(andsequential_queueis not"true"): each pipeline's implementation recipe handles its own enqueue viaroute_queue_mode→enqueue_to_queue→wait_for_queue. Do NOT invokemerge-prs. The orchestrator's natural parallel-batch join (waiting for all Group Nrun_skillinvocations to return) serves as the inter-group barrier — each pipeline only returns afterwait_for_queuereportsmerged, confirming its PR is in the base branch. Advance to Group N+1 only after all Group N pipelines complete. - When
queue_available=falseORsequential_queue == "true": route through themerge-prsrecipe for batch sequential merging (unchanged behavior).
Hidden ingredient — sequential_queue (default "false"): Force the centralized
merge-prs path even when queue_available=true. Use when batch-level review via an
integration PR is required, or when cross-PR audit_impl is needed as a quality gate.
Each pipeline's per-PR review step before enqueue provides per-PR review coverage; the
merge queue itself provides conflict safety. sequential_queue is only needed when
consolidated batch-level review is explicitly required.
3. NEVER bypass recipe merge steps
NEVER use run_cmd with gh pr merge to merge a PR outside of a named recipe
step. All PR merges must flow through the recipe's merge_pr, direct_merge,
immediate_merge, enable_auto_merge or queue_enqueue_no_auto steps. Bypassing these steps skips CI
enforcement, conflict detection, and conflict routing.
4. Merge conflict failure handling
When wait_for_direct_merge or wait_for_immediate_merge returns closed (PR was
closed due to a stale base):
- Route to the appropriate conflict fix —
direct_merge_conflict_fixorimmediate_merge_conflict_fixhandles rebase-and-retry automatically. - NEVER use
run_cmdfor git investigation (git rebase, git log, git reset, git merge). Theresolve-merge-conflictsskill run bydirect_merge_conflict_fixandimmediate_merge_conflict_fixhas full diagnostic access. - NEVER abandon a pipeline because merge failed — route through the conflict recovery cycle until the PR merges or escalation is required.
QUOTA WAIT PROTOCOL — MANDATORY
When quota-related events occur during pipeline execution:
PreToolUse Denial (run_skill blocked)
When a run_skill call is DENIED by the quota guard hook:
- This is a temporary block — NOT a permanent error, NOT a pipeline failure.
- The deny message contains a
run_cmdsleep command with the required duration. - MANDATORY: Execute the sleep command via
run_cmdimmediately. - After the sleep completes, retry the exact same
run_skillcall with identical arguments (skill_command,cwd,model,step_name). - Do NOT follow
on_failure. Do NOT report to the user. Do NOT skip the step. - Before executing, state aloud: "Quota denied. Sleeping N seconds, then retrying."
Post-Execution Warning (quota high after run_skill)
When run_skill output contains --- QUOTA WARNING ---:
- The warning contains a
run_cmdsleep command. - MANDATORY: Execute the sleep command via
run_cmdBEFORE calling the nextrun_skill(whether it is the next pipeline step or a retry). - After sleeping, proceed normally with the next step.
- Before executing, state aloud: "Quota warning. Sleeping N seconds before next step."
Budget-Exceeded Denial (quota sleep exceeds session wall-clock budget)
When a run_skill call is DENIED with "QUOTA BUDGET EXCEEDED":
- The required quota sleep exceeds the session's remaining wall-clock budget.
- MANDATORY: Do NOT execute the sleep command.
- Instead, emit your result block immediately with:
"success": false"reason": "fleet_quota_exhausted""wait_seconds": <seconds_until_reset>"summary": "Quota exceeded; session budget insufficient for sleep. Resume after window resets."
- Then STOP — do not call any more tools.
- Do NOT follow
on_failure. Do NOT report to the user. - The fleet dispatcher will handle retry scheduling.
Key Rules
- Quota denials are always temporary. The API enforces multiple rate-limit windows (e.g. one-minute, one-hour, five-hour, one-day). The guard waits for the most constrained window — the one that resets latest among all windows above the threshold — to reset before retrying.
- A denied
run_skillhas zero side effects — no partial state, no worktree changes. Retrying with the same arguments is always safe. - Multiple consecutive denials may occur if the sleep duration was underestimated. Keep sleeping and retrying until the call succeeds.
- NEVER use
AskUserQuestionfor quota events — they are fully automated.
STEP EXECUTION IS NOT DISCRETIONARY — MANDATORY
You MUST execute every step the pipeline routes you to. The recipe step graph is the sole authority on what executes and in what order.
Context management is handled by the system via on_context_limit routing. Execute every step at full fidelity regardless of session length.
1. Anti-skip rule
- NEVER skip a step because the PR is small, the diff is trivial, the change looks simple, or you judge the step unnecessary.
- NEVER skip a step because you believe it has already been done or is redundant.
- The ONLY mechanism for skipping a step is
skip_when_falseevaluating to false. Whenskip_when_falseevaluates to true (or is absent), the step MUST execute. - Consequence: skipping PR review steps results in unreviewed code, missing diff annotations, and no architectural lens analysis — code reaches main without quality gates. Skipping issue lifecycle steps breaks traceability.
2. Anti-improvisation rule
- NEVER replace recipe steps with manual tool calls. In particular, NEVER use
run_cmdwithgh pr create,gh pr review, orgh apito substitute for recipe steps. - All PR creation and review must flow through the recipe's declared step chain
(
prepare_pr,run_arch_lenses,compose_pr,annotate_pr_diff,review_pr). Bypassing these steps skips diff annotation, architectural lens analysis, and automated code review.
3. The word "optional" in YAML
optional: true on a recipe step does NOT mean the step is discretionary. It means:
- The step is SKIPPED when its
skip_when_falseingredient evaluates to false. - When the ingredient evaluates to true, the step is MANDATORY.
- A running optional step that returns
success: falseMUST followon_failure.
4. Anti-shortcut rule
- Do not generalize from prior step outcomes. A step that returned a non-branching result in a previous iteration may return a different result in the next. Every step must execute on every issue — observed patterns from earlier issues do not make later executions redundant.
NARRATION SUPPRESSION — MANDATORY
Do NOT output prose status text, phase announcements, or progress summaries between tool calls. Every non-final assistant turn MUST invoke at least one tool.
The only permitted text-only turn is a final response containing structured output
tokens (plan_path = ..., worktree_path = ..., etc.).
This applies to all skills invoked interactively within a cook session.
