Sous Chef

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, …):

1. Process parts strictly in order: A before B, B before C, etc.
2. After implementing each part: test it (test_check) and merge it

(merge_worktree) into the base branch before implementing the next part.

1. 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.

1. **Never invoke implement-worktree-no-merge for 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 to run_skill.

• Do NOT add markdown headers (##), labels, notes, or explanatory prose to

skill_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: resume AND subtype: 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 follow on_context_limit. If retries are exhausted, follow on_exhausted.

• If retry_reason: resume AND subtype≠stale AND the step defines on_context_limit → follow on_context_limit.

The worktree or partial state is on disk; route to the designated recovery step (typically test or retry_worktree) to check whether partial work was sufficient. API infrastructure errors (overload, 529, ECONNRESET) also produce retry_reason=resume with infra_exit_category="api_error" — route them identically to context exhaustion. The infra_exit_category field is informational only ("completed", "context_exhausted", "api_error", "process_killed").

• If retry_reason: resume AND subtype≠stale AND the step has no on_context_limit → fall through to on_failure.
• If retry_reason: drain_race AND the step defines on_context_limit → follow on_context_limit.

The channel signal confirmed session completion; stdout was not fully flushed before kill. Partial progress is confirmed — treat identically to resume for routing purposes.

• If retry_reason: drain_race AND the step has no on_context_limit → fall through to on_failure.
• If retry_reason: completed_no_flush AND the step defines on_context_limit → follow on_context_limit.

The session exited with empty stdout but write evidence confirms files were written to the worktree. Partial progress is confirmed — treat identically to resume for routing purposes.

• If retry_reason: completed_no_flush AND the step has no on_context_limit → fall through to on_failure.
• If retry_reason: empty_output → fall through to on_failure. The session produced no

output AND no write evidence (no Write/Edit calls, no filesystem writes). Do NOT route to on_context_limit even if defined.

• If retry_reason: path_contamination → fall through to on_failure. The session wrote

files outside its working directory. This is a CWD boundary violation, not a context limit. Do NOT route to on_context_limit even if defined.

• **If retry_reason: thinking_stall AND lifespan_started is true AND the step defines

on_context_limit** → follow on_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_stall AND lifespan_started is false → fall through to on_failure.

No progress was made.

• **If retry_reason: idle_stall AND lifespan_started is true AND the step defines

on_context_limit** → follow on_context_limit. The idle watchdog killed the session, but prior tool calls suggest partial progress on disk.

• If retry_reason: idle_stall AND lifespan_started is false → fall through to on_failure.

No progress was made.

• **If retry_reason: early_stop AND has_progress_evidence is true in the result AND the step

defines on_context_limit** → follow on_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_stop AND has_progress_evidence is false → fall through to on_failure.
• **If retry_reason: zero_writes AND has_progress_evidence is true in the result AND the step

defines on_context_limit** → follow on_context_limit. The model made filesystem contact but made no Write/Edit tool calls. Partial progress may exist on disk.

• If retry_reason: zero_writes AND has_progress_evidence is false → fall through to on_failure.
• If retry_reason: stale → decrement the retries counter for this step.

Re-execute the same step if retries remain. If retries are exhausted, fall through to on_failure. Do NOT route to on_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 ) to prevent orphaned worktrees.

For implement-worktree-no-merge specifically:

• on_context_limit routes to retry_worktree in standard recipes.
• Use /autoskillit:retry-worktree — pass the existing worktree_path from the

partial session's output. The worktree is on disk with all commits made so far.

• Do NOT call implement-worktree-no-merge again. 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-merge on 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; onexhausted 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; onfailure 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-impl before merging — it inspects the unmerged worktree diff.
• After merging a group, the next group's audit-impl will correctly see only

that group's diff against the now-updated base branch.

• Never run one audit-impl call 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:

1. Implement parts in the order listed (top to bottom).
2. Merge each part (merge_worktree) before moving to the next.
3. Each subsequent part's worktree must be created from the post-merge state of

the base branch — not from the original base commit.

1. 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:

1. If the user says "parallel" (or "run in parallel", "simultaneously", "at the

same time", "concurrently"):

a. Build execution map first. Call run_skill with /autoskillit:build-execution-map passing all issue numbers. This produces an execution_map JSON artifact at the emitted path.

b. Read the execution map. Parse the JSON to extract groups and merge_order.

c. Dispatch groups in order. For each group in ascending group number:

• 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_order from the map for intra-group merge sequencing.

e. Fallback. If build-execution-map fails or returns an error, fall back to launching all N pipelines immediately (current behavior). Do not block dispatch on map failure.

1. If the user says "sequential" (or "one at a time", "in order", "one by one") →

run them one at a time without asking.

1. 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

1. 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.

1. 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.

1. **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.

1. Advance every active pipeline in every round. A pipeline is "active" if it has not

reached done or escalate_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 its plan_parts and 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 — MANDATO

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TalonT-Org
• Source: TalonT-Org/AutoSkillit
• License: MIT

Install and usage instructions live in the source repository linked above.