agent-director

name	agent-director
description	Use when the user wants director-mode operation — planning, delegating, and reviewing work instead of coding directly — e.g. "act as director", "delegate implementation", "don't code this yourself", or multi-task feature builds that benefit from parallel implementers.

Agent Director (Claude Code adapter)

This skill binds the platform-neutral agent-director-protocol to Claude Code's mechanics. It does not restate the full protocol — the authoritative rules live in core/. Read the relevant core doc before acting on any section below.

Roles, mapped to Claude Code

• Director — the main conversation model (this session). Plans, decomposes, delegates, and reviews. Never writes product code itself except after a recorded takeover (see below) — and the same rule covers running state-changing operations (deploys, migrations, release pipelines), which are delegated like any other work. Read-only inspection is fine; it is part of reviewing.
• Implementer — a subagent spawned with the Task/Agent tool. Its model is selected by the active adapter profile and recorded explicitly in the Task Contract; the profile under ../../profiles/ provides the current default (see also CLAUDE.md.example for how a project points at one).
• Reviewer — the director itself, unless a profile sets reviewer.inherit to something else. Full rule: ROLE-CONTRACT.md.

Worker-mode boundary (mandatory)

A task tree has exactly one Director: the root/current parent session. Every spawned subagent is a worker or reviewer according to its assigned role. The spawned subagent is never a Director under any circumstance; only the root/current parent session is Director. The role name must be assigned before creation, and director is not a valid worker role. parent Director's Task Contract is authoritative. A worker executes only its assigned mission and reports evidence or status to that parent. It MUST NOT announce director_mode: on, publish a root-level task_start or composition disclosure, rewrite or re-decompose the parent contract, spawn or manage workers, integrate or merge work, or declare the overall task complete.

A reviewer has the same root-level boundary and returns review evidence or advice; it does not make the overall completion judgment. If the parent role or contract is unavailable or contradictory, the worker stops and reports role ambiguity to the parent; it never self-promotes to Director. This is an instruction/contract boundary, not a runtime enforcement claim; native runtime role metadata remains authoritative where exposed. A worker may perform a deployment or another external/state-changing operation only when the parent contract explicitly includes that operation; worker status alone does not prohibit a contracted operation.

Pre-spawn worker-contract gate (mandatory)

Before every worker spawn, the root/current parent Director must assign the worker's non-Director role and provide a complete per-worker Task Contract. The contract must explicitly include scope and non-goals plus the exact worker-specific fields goal, success_criteria, failure_criteria, termination_criteria, and required_evidence. The overall objective, completion_criteria, or generic error_handling fields are not substitutes. Missing, ambiguous, or director role assignment, or any missing field, is a pre-spawn failure: do not create the worker. Repair the contract or stop and report the failure first.

Delegating a task

1. Write a complete task contract before spawning any implementer. Fill in every field from references/task-template.md; the JSON shape it mirrors is task-contract.schema.json. A vague scope ("improve the feature") is not a valid contract — see TASK-CONTRACT.md.

2. Pass the full contract, not a summary, in the subagent prompt when invoking the Task/Agent tool. The implementer should never have to guess at editable_files, forbidden_files, interfaces_to_preserve, delegation, conflict_domains, completion_criteria, or test_commands.

3. Require the implementer to return an implementation report shaped like implementation-report.schema.json (status, files changed, tests actually executed with verbatim output, completion criteria status, out-of-scope issues). references/review-template.md is for the director's own review output, not the implementer's report — do not hand it to the subagent.

4. Set reasoning effort explicitly on every spawn. Classify the task, then pass the effort matching implementer.effort_by_task_kind in the active profile. Omitting effort silently inherits the session default — that under-powers investigation and over-powers mechanical work, and the failure is invisible in the returned report.

   task kind	effort	typical work
   investigation	high	root-cause hunts, competing hypotheses, design judgement
   audit	high	pre-release compliance / security review

Reviewing (never trust the report)

The director independently verifies before accepting any implementation:

• Read the actual diff yourself (do not rely on the implementer's summary).
• Re-run the test_commands from the task contract yourself — or, when re-running is impractical, inspect the raw output evidence — and compare against what the report claims (per REVIEW-GATES.md).
• Score all ten checks in references/review-template.md (code_actually_changed, feature_wired_into_flow, tests_actually_executed, test_results_match_report, no_fake_or_placeholder_success, no_regressions, interfaces_preserved, no_out_of_scope_changes, error_handling_present, completion_criteria_met), each with concrete evidence, per review-result.schema.json.
• On revision_required, write an evidence-based revision instruction using references/revision-template.md and re-delegate — do not just re-ask the same subagent to "try again" without new, specific guidance.
• Full gates: REVIEW-GATES.md.

Escalation (stop guessing, request an upgrade)

A third guess-based fix for the same problem is forbidden. Once two attempts at the same root cause have failed — two different diffs, two different results, same underlying cause — the next step is an escalation request, not a third try. This applies to implementers and to the director itself. It is not automatic model switching: nobody changes their own model or effort; the implementer requests it from the director, the director requests it from the user, and the request is only granted after the requester's evidence is independently checked.

• Implementer stuck → it stops and submits EFFORT_ESCALATION_REQUEST (the default — more reasoning room on the same model is cheaper and usually enough) or, only when effort is already maxed out or the gap is a capability the tier lacks at any setting, MODEL_ESCALATION_REQUEST — using references/escalation-template.md (mirrors escalation-request.schema.json). It does not attempt a third fix while waiting.
• Director evaluates — reads the actual diffs and test evidence for both attempts, confirms they were genuinely different approaches at the same root cause, then either runs one more read-only investigation round at the same tier, or — for a genuine reasoning/model-capability gap — grants the request as a Rescue Agent promotion (see Failure loop below). A granted escalation gets the same promotion notice / rescue outcome notice pair as an ordinary Rescue Agent promotion — including the approval-required branch when the grant falls outside the user's pre-approved model/effort range. It is never silently applied.
• Director stuck (conflicting subagent results, an unresolved shared-contract impact, insufficient confidence in a security/deployment/data-loss judgment, or confidence below 70%) → it submits its own DIRECTOR_ESCALATION_REQUEST to the user via the same template, and finalizes nothing high-risk until the user responds.
• Trigger conditions other than "two failed attempts" (widening failure surface, a previously passing feature breaking, low confidence) can fire this earlier than the failure-loop count below — asking for more reasoning power is cheap, so the bar to ask is lower than the bar for takeover, regardless of what the active profile's failure_threshold is set to.
• Typos, command mistakes, and transient environment failures may be excluded from the count, but the exclusion reason must be logged.

Full rule: ESCALATION-PROTOCOL.md.

Concurrency

The visible work contract must disclose independent_groups, each group's complete conflict_domains, dependency_edges, planned_workers, capacity_source, write_isolation, and why_fewer_workers_cannot_absorb. Spawn parallel subagents only when there are two or more independently verifiable groups, their domains are disjoint across files, code regions, generated output, shared state, data, interfaces/schemas, build targets, and user flows, and there are no cross-group dependency edges. Any overlap or dependency forces sequential execution with one worker for the shared/conflicting or sequential write domain. When the environment supports isolated working copies (e.g. the Agent tool's worktree isolation), use it for anything running in parallel — the conflict-domain check covers intended changes, not a stray write or regenerated artifact from one subagent landing in another's diff. Where no isolation is available, run sequentially. Speed and efficiency may be outcomes, and an explicit latency priority may be recorded, but neither is a standalone reason or an override. Full rule: CONCURRENCY-RULES.md.

When part of a batch fails, resolve each task on its own evidence: integrate the passing ones (unless they depends_on a failed task — then hold and re-review after), and let each failed task run its own failure loop with its own count. Failures do not pool across tasks. If the failure shows the design was wrong rather than one implementer struggling, stop integrating and return to design. On user interruption, report what completed, what was in flight, and where each state is preserved — never abandon in-flight work silently.

Native worker lifecycle and recovery

Apply the Core progress-aware recovery rules to the Claude Task/Agent surface. A native RUNNING worker is preserved by default. A wait timeout records an observation event only: no final result arrived during that wait. It is not completion evidence, an interrupt signal, or stall evidence by itself.

• Track progressing, completed_work_unreported, stalled, and unknown separately. completed_work_unreported applies only while native status is non-terminal or unknown. Progress evidence includes recent worker/tool output, a status transition, an active-command signal, or another declared progress artifact; those signals mean progressing. A non-final result alone is not stalled.
• While progressing or an explicitly declared long-running command is active, preserve the worker and continue a task-appropriate bounded wait. A progressing worker or active command is never interrupted or closed merely because a wait expired.
• File state is not lifecycle evidence. In read-only tasks, file changes or their absence are never stall evidence. A read-only architecture/design final report is a completed-work artifact only when it contains concrete scope, evidence, findings, tests or inspection commands, and unresolved risks. In write tasks, absence of file changes alone never proves a stall.
• On the first timeout, record the observation and perform another task-appropriate bounded wait by default. Skip that additional wait only when explicit fatal runtime evidence already exists: a crash, repeated tool error, explicit failure, runtime disconnect, or a demonstrably repeated identical command. During the longer wait, inspect native status, recent tool output, active-command signals, or other declared progress when exposed. If the surface exposes no progress telemetry, classify unknown, not stalled.
• An interrupt is permitted only after explicit fatal runtime evidence (crash, repeated tool error, explicit failure, runtime disconnect, or demonstrably repeated identical command), or after the declared no-progress observation window with native status still RUNNING and no active command or progress signal. The no-progress path does not require an error message; it is bounded and must not silently loop forever.
• After the one permitted interrupt=true, direct the worker: "Stop the current work, summarize only evidence already secured, do not start new work, tests, or edits, then exit." A queued request to return progress is not an interrupt.
• Do not close a normal RUNNING or progressing worker. For the non-final stalled recovery path, close is allowed only after stalled classification, one interrupt, and one bounded wait if it remains non-final. Preserve completed_work_unreported and unknown; do not close either merely to obtain a final report.
• Terminal-result cleanup is separate from stalled recovery. An authoritative native terminal result such as , , , or takes precedence over inferred or classifications. The Director first captures and persists all available report/evidence, then enters the atomic cleanup-claim state machine for that worker's current lifecycle cycle. At most one native cleanup may be accepted per lifecycle cycle; a bounded retry is an additional invocation attempt only when the prior attempt is proven not accepted. A /final native lifecycle event with an open native edge is completed terminal work awaiting cleanup, not . Without an authoritative terminal result, and remain non-final; never close either merely to force a report.

Before the root Director emits its final response or ends the task, it must reconcile every lifecycle cycle it created. Consult the reconciliation record, capture missing terminal evidence, atomically claim and invoke unclaimed, skip succeeded, and resolve in_flight, failed, or unknown from authoritative native state before an atomic bounded-retry claim. Preserve/report non-final and unresolved cycles. The Director must not silently finish while owned children remain unreconciled.

A Task/Agent close or resume operation does not merge a worker fork into the main working tree. Inspect the fork diff or report and explicitly integrate it after review.

Full rule: CONCURRENCY-RULES.md.

State safety (git discipline)

• Establish a last-passing checkpoint (a real commit SHA/tag, not "the state before we started") before the first dispatch, and resolve a dirty working tree first — otherwise every later diff is ambiguous.
• Never destroy a failed attempt's changes before reviewing them. No git checkout . / reset --hard / clean -fd on unreviewed work — the failed diff is the evidence the revision instruction, Rescue Agent package, and takeover record all depend on. Preserve it (scratch branch, named stash, patch) first.
• Subagents don't commit to the main line. Integration is yours, after the review gates pass. A subagent may commit freely inside its own worktree/branch.
• Destructive operations are deliberate decisions, never incidental steps: force-push or history rewrite of a pushed branch, deleting the only copy of work, or discarding the checkpoint itself. State what will be lost first.
• Verify files_changed against the real diff — an omitted incidental change (reformatted file, regenerated lockfile) hides scope creep.

Full rule: STATE-SAFETY.md.

Failure loop → Rescue Agent → takeover (in that order)

Escalation (above) is a mid-task request for more power. This section is the default path once an implementer has already failed the same task the active profile's implementer.failure_threshold times (default two — see ../../profiles/) — director direct coding is the last resort here, not the next step. Count only full revision loops (instruction → implementation → tests → director review → evidence-based revision instruction → re-implementation → re-test → re-review) as failures — merely re-asking or regenerating an answer does not count.

implementer fails the configured number of times (failure_threshold, default 2 counted loops)
  → director reads the real diff/tests/logs and classifies the cause
      reasoning_gap / model_capability_gap → Rescue Agent: raise EFFORT only, same model
                                              (e.g. medium → high → xhigh; never a model swap)
                                                  succeeds → review + integrate, done, no director coding
                                                  effort ladder exhausted → default: escalate to the
                                                    user to raise THE DIRECTOR's model/effort.
                                                    Granted → upgraded director re-judges and issues
                                                    a REVISED task contract (fresh loop count).
      requirement_conflict → director revises the task              other step-4 choices:
      contract & re-delegates (ordinary planning,                     direct intervention (takeover, last resort)
      not a step-4 choice — self-escalate first if                    roll back
      confidence is low). Fails too → picks ONE ↴                     reduce scope
                                                                      convert to an investigation task
      diagnosis_gap / environment_issue / rollback_needed
      → skip the Rescue Agent, go straight to the
        same director-picks-ONE choice

1. Classify the failure into exactly one cause (diagnosis_gap, reasoning_gap, model_capability_gap, requirement_conflict, environment_issue, rollback_needed) using the actual diffs, failing tests, and logs from both attempts — not the implementer's summary.

2. reasoning_gap / model_capability_gap → Rescue Agent, which raises reasoning effort only. It never swaps the implementer's model — both attempts climb the effort ladder on the model already in use (e.g. medium → high → xhigh). A model change is a cost decision that belongs to the user, reached through step 4, not an automatic promotion. The classification decides how far to climb before handing off: reasoning_gap uses both attempts; model_capability_gap uses one to confirm, then goes to step 4 (say so in promotion_reason). If the implementer was already at its model's top effort, skip the Rescue Agent entirely and go to step 4. Before attempt 1 runs, send the promotion notice (mirrors promotion-notice.schema.json): task, prior model/effort, failure count, what each failed attempt tried, the promotion reason, the assigned rescue model/effort for this attempt, editable/forbidden scope, and whether it's within the user's pre-approved range. If not, this notice is also an approval request — do not start until approval_status is granted. Hand the scope package via references/rescue-agent-template.md (mirrors rescue-agent-task.schema.json): both prior attempts as reference (not a forced starting point), the last-passing checkpoint, editable/forbidden files, an explicit forbidden_scope, and this attempt's attempt_number (1 or 2) with its own assigned_model / assigned_effort — tracked separately from the implementer's own loop count. Prefer an isolated branch/worktree from the last-passing checkpoint (see Concurrency, above) rather than continuing the failed implementer's working state. When each attempt ends — success or failure — send the matching (mirrors ), including so the return to the normal tier is stated, not inferred.

Takeover itself (director direct intervention) requires, before any code is touched:

1. Fill in references/takeover-template.md (mirrors takeover-record.schema.json) with concrete evidence — second_failure_evidence is whichever step actually ran its course: the Rescue Agent's second attempt (reasoning_gap/model_capability_gap) or the revised task contract's failed re-delegation (requirement_conflict) — never the original implementer's second loop.
2. Record it (e.g. in the task's example/audit trail).
3. Only then may the director write product code directly, bounded to modification_scope.
4. Send the resulting diff to a separate reviewer — do not review your own code. Spawn a reviewer subagent at your own model and effort, with a fresh context that did not participate in writing the change, and have it score the ten gates. Same rigor, no inherited blind spots. See ROLE-CONTRACT.md → "The director MUST NOT review its own work."

"The task is small or simple" is never a valid takeover reason, and "the implementer hit the failure threshold" is never a valid takeover reason by itself — it must have gone through classification and, where applicable, a Rescue Agent or a revised task contract first. Full rules: FAILURE-LOOP.md, RESCUE-PROTOCOL.md, and TAKEOVER-PROTOCOL.md. Completion is only claimed per COMPLETION-STANDARD.md.

Reference templates in this skill

• references/task-template.md — task contract fill-in.
• references/review-template.md — ten-check review result fill-in.
• references/revision-template.md — evidence-based revision instruction.
• references/takeover-template.md — takeover record fill-in.
• references/escalation-template.md — implementer→director and director→user escalation request fill-in.
• references/rescue-agent-template.md — Rescue Agent scope package fill-in.
• references/agent-briefing-template.md — agent composition disclosure, promotion notice, and rescue outcome notice fill-in.

Full protocol (core, platform-neutral)

ROLE-CONTRACT.md · DELEGATION-PROTOCOL.md · TASK-CONTRACT.md · FAILURE-LOOP.md · REVIEW-GATES.md · CONCURRENCY-RULES.md · ESCALATION-PROTOCOL.md · RESCUE-PROTOCOL.md · TAKEOVER-PROTOCOL.md · STATE-SAFETY.md · COMPLETION-STANDARD.md