Orchestrate

Orchestrate

Keep architecture, acceptance, and integration local. Delegate bounded work only.

Read the right reference

• Read references/orchestration.md for task decomposition, delegation rules, parallelism, context isolation, review loops, and evaluation.
• Read references/claude-cli.md for the current claude CLI surface: -p, structured output, permission modes, worktrees, and custom agents.

Lead versus worker

• Lead (Codex): architecture, task graph, owned-file boundaries, acceptance criteria, integration, and final verification.
• Worker (Claude): bounded research, boilerplate, repetitive refactors, first-pass implementation, docs, and mechanical edits.

Do not hand off the part where a wrong decision would invalidate the rest of the work.

When to use this skill

• the task is larger than one coherent edit
• multiple sub-tasks can run independently
• a repetitive or high-volume slice can be delegated
• you want Claude to work in an isolated worktree or with restricted tools
• you need a repeatable orchestration pattern, not just a single prompt

When not to use it

• the next step is urgent and tightly coupled to your own reasoning
• the change is trivial enough to do directly
• the repo or task should not leave the current agent boundary
• overlapping write scopes would make parallel work risky

Default workflow

1. Define success, stop rules, and what stays local. 2. Break the task into atomic units with clear ownership. 3. Choose execution mode per unit:

• read-only research or planning
• bounded edit in current tree
• isolated edit in a worktree

4. Build a short handoff with:

• one concrete goal
• files to read first
• owned files and forbidden files
• exact verification commands
• return format

5. Run independent workers in parallel only when their write scopes do not overlap. 6. Review Claude’s output or diff before integrating. 7. Run local verification yourself. 8. If the pattern repeats, promote it into .claude/agents, hooks, or project settings.

Core rules

• Fresh Claude session by default for each delegated unit.
• Use --continue only when continuity matters more than clean context.
• Prefer structured output for plans, task maps, and review summaries.
• Prefer tool and permission restrictions over prompt-only restrictions.
• Use worktrees for risky or concurrent edit tasks.
• Move deterministic enforcement into hooks, not repeated prose reminders.
• Record what Claude owned, what you owned, and what was verified.

Claude CLI

Current local verification snapshot:

• CLI: Claude Code 2.1.74
• verified working:
• claude -p ... --permission-mode plan --output-format text
• claude -p ... --permission-mode plan --output-format json --json-schema ...

Relevant current docs:

• Claude Code CLI reference
• Run Claude Code programmatically
• Claude Code subagents
• Claude Code hooks and settings

Non-interactive mode

Use claude -p for scripted or delegated runs.

Examples:

claude -p "Summarize this module" --permission-mode plan

claude -p "Return a task map" \
  --permission-mode plan \
  --output-format json \
  --json-schema '{"type":"object","properties":{"tasks":{"type":"array"}},"required":["tasks"],"additionalProperties":false}'

Recommended execution modes

Read-only planning or research

Use:

claude -p "$PROMPT" --permission-mode plan

Use this for:

• task decomposition
• file discovery
• design comparison
• review and research

Bounded edit task in current tree

Use:

claude -p "$PROMPT" --permission-mode acceptEdits

Use this when:

• Claude may edit files
• you still want command-side effects guarded

Normal interactive delegation

Use:

claude -p "$PROMPT" --permission-mode default

Use this when the worker may legitimately need approval decisions during execution.

Do not default to

• --dangerously-skip-permissions
• --allow-dangerously-skip-permissions

Only use those in externally sandboxed environments you explicitly control.

Structured output

Prefer structured output for machine-consumed returns:

• --output-format json
• --json-schema ...

Use text output when the return artifact is intended for human review.

Tool shaping

Constrain workers with:

• --allowedTools
• --disallowedTools
• --tools

Best practice:

• use the narrowest tool set that still lets the worker succeed
• do not make “stay read-only” a prompt-only instruction when the CLI can enforce it

Custom agents and subagents

Claude CLI supports:

• --agent <agent>
• --agents <json>
• reusable project or user agents under .claude/agents/

Use custom agents when a role recurs:

• code-reviewer
• migration-worker
• docs-writer
• test-fixer

Write clear descriptions so Claude knows when to route to them.

Worktrees

Use --worktree when a delegated task needs isolation from the current branch or when multiple implementation tracks may run concurrently.

Relevant flags available locally:

• --worktree [name]
• --tmux

Good use cases:

• risky refactors
• independent feature spikes
• parallel edit tasks with disjoint ownership

Session handling

Fresh session by default.

Use:

• --no-session-persistence for ephemeral scripted work if you do not want saved session state
• -c/--continue only when the same delegated unit genuinely benefits from continuity

Hooks and settings

When a rule should always apply, move it into Claude infrastructure:

• hooks for deterministic pre/post tool checks
• project settings for team-shared behavior
• local settings for machine-specific overrides

Do not keep re-explaining deterministic rules in every delegated prompt if hooks or settings can enforce them once.

Orchestration Patterns

Source snapshot: refreshed 2026-03-12 from official Anthropic and OpenAI material

• Claude Code best practices
• Claude Code subagents docs
• Claude Code hooks docs
• Claude prompt engineering best practices
• OpenAI multi-agent orchestration and eval best practices

Core principles

Keep the critical path local

Do locally:

• architecture and sequencing decisions
• acceptance criteria
• integration and merge decisions
• final verification

Delegate:

• research that can be summarized
• repetitive mechanical edits
• bounded implementation slices
• first-pass docs and boilerplate

Bound every delegated task

Each worker should have:

• one objective
• a clear owned write scope
• files to avoid
• exact verification commands
• a strict return format

If the task cannot be described that way, it is not ready to delegate.

Context isolation beats giant prompts

Modern Claude and Codex guidance converges on the same point: large contexts rot. Keep main-thread context focused and let delegated workers rebuild only the context they need.

Practical rules:

• delegate file exploration and implementation separately when possible
• do not dump massive repo summaries into every worker prompt
• point workers to files and commands, not long narrative history
• prefer fresh sessions for new sub-tasks

Parallelize only independent work

Run workers in parallel only if:

• the next local step does not depend on them immediately
• their outputs do not race on the same files
• their verification can run independently

Good parallel pairs:

• codebase exploration in separate areas
• docs plus tests
• two implementation slices with disjoint ownership

Bad parallel pairs:

• two workers editing the same module
• one worker producing an interface while another consumes the unsettled design

Give workers a way to verify themselves

Verification is the highest-leverage accelerant in agentic coding workflows.

Always include one or more of:

• unit or integration test commands
• lint or typecheck commands
• expected output or behavior
• screenshot or UI expectations
• explicit “done means” criteria

Use deterministic infrastructure for deterministic rules

If something should always happen, do not rely on the worker to remember it.

Promote repeated rules into:

• .claude/agents/ for reusable specialized workers
• project or local .claude settings for shared configuration
• hooks for formatting, notifications, command blocking, or post-edit checks

Evaluate the orchestration, not just the result

Modern skill and eval guidance is clear: measure process, not vibes.

For an orchestration pattern, success includes:

• did the lead delegate the right slices?
• did workers stay within scope?
• did they return the requested format?
• did the lead verify before accepting?
• did the workflow avoid unnecessary thrash?

Delegation rubric

Delegate when the task is:

• repetitive
• local in scope
• easy to verify
• separable from architectural choices

Keep local when the task is:

• ambiguous
• architecture-defining
• safety-critical
• hard to verify automatically
• needed immediately for the next decision

Handoff template

Use a short, explicit brief:

You are working as a bounded implementation worker.

Goal:
- [single concrete outcome]

Read first:
- [file paths]

Ownership:
- edit: [files or directories]
- avoid: [files or directories]

Constraints:
- [repo rules, language rules, no-go areas]

Verification:
- run: [commands]
- done means: [observable result]

Return:
- [diff summary | JSON | patch | checklist]

Add examples only when the format is strict enough to warrant them.

Review loop

Do not accept delegated work blindly.

Review in this order:

1. Did the worker stay in scope? 2. Did it satisfy the contract? 3. Are there obvious logic or edge-case failures? 4. Did verification actually run and pass? 5. Does the change still make sense in the broader architecture?

If not, send a targeted revision request instead of a full restatement.