orchestrating

name	orchestrating
description	Parallel task execution via subagents.

Orchestrating

Dispatch one fresh subagent per plan task. After each: spec compliance review, then code quality review. Track progress with Tasks.

Why fresh subagents: Isolated context prevents cross-task confusion. You craft exactly the context each agent needs — never pass your full session history. This preserves your own context for coordination.

When to Use

• Have an implementation plan with mostly independent tasks
• Want to stay in one session (vs. arsyn:executing for parallel sessions)
• Need structured quality gates between tasks

Not for: tightly coupled tasks with heavy shared state, or plans requiring human decisions between steps.

Process

1. Read plan, extract all tasks with full text and context
2. Create Tasks (TaskCreate) for each — tracks status, dependencies, progress
3. For each task:
   a. Dispatch implementer subagent (references/implementer-prompt.md)
   b. Handle implementer status (see below)
   c. Dispatch spec reviewer (references/spec-reviewer-prompt.md)
   d. If spec issues: implementer fixes, re-review until clean
   e. Dispatch code quality reviewer (references/code-quality-reviewer-prompt.md)
   f. If quality issues: implementer fixes, re-review until clean
   g. TaskUpdate — mark complete
4. Dispatch final cross-task reviewer for entire implementation
5. arsyn:finalizing

Task Coordination

Use TaskCreate/TaskUpdate to track subagent progress:

• Create one Task per plan task at the start
• Update status as subagents complete work (pending -> in_progress -> done)
• Record blockers, dependencies, and findings in task metadata

Sharing state between subagents: When subagents produce findings other agents need, write to files in the working directory. Later agents can Grep/Read those files. Avoid passing large blobs through the orchestrator — the file system is the shared bus.

Example: implementer writes task-1-api-endpoints.md with discovered API shapes. Task 2's implementer Greps for it.

Model Selection

Match model capability to task complexity:

Signal	Model tier	Examples
1-2 files, complete spec, mechanical	Fast/cheap	Isolated functions, config changes, boilerplate
Multi-file, integration concerns	Standard	Cross-module wiring, pattern matching
Design judgment, broad codebase knowledge	Most capable	Architecture decisions, complex reviews

Default to standard. Downgrade only when the spec is unambiguous and scope is narrow.

Handling Implementer Status

DONE: Proceed to spec review.

DONE_WITH_CONCERNS: Read concerns first. Correctness/scope concerns must be addressed before review. Observational concerns (e.g., "file getting large") — note and proceed.

NEEDS_CONTEXT: Provide missing info, re-dispatch.

BLOCKED: Assess the blocker:

1. Context problem — provide more context, re-dispatch same model
2. Reasoning limit — re-dispatch with more capable model
3. Task too large — break into subtasks
4. Plan wrong — escalate to user

Never retry without changing something.

Tool Restrictions by Role

Role	Tools	Access
Implementer	Read, Edit, Write, Bash, Grep, Glob	Full
Spec reviewer	Read, Grep, Glob	Read-only
Code quality reviewer	Read, Grep, Glob	Read-only
Test runner	Bash, Read, Grep	Execute + analyze

Enforce via tools in agent definition. Prevents accidental modifications by reviewers.

Prompt Templates

• references/implementer-prompt.md — implementer subagent instructions
• references/spec-reviewer-prompt.md — spec compliance review
• references/code-quality-reviewer-prompt.md — code quality review
• references/agent-sdk-patterns.md — SDK patterns for tool restriction and model selection

Condensed Example

[Read plan: docs/plans/feature.md — extract 3 tasks]
[TaskCreate for each task]

--- Task 1: Auth middleware ---
[TaskUpdate: in_progress]
[Dispatch implementer — fast model, clear spec]
Implementer: DONE — implemented, 5/5 tests pass, committed
[Dispatch spec reviewer]
Spec reviewer: PASS
[Dispatch quality reviewer]
Quality reviewer: PASS
[TaskUpdate: done]

--- Task 2: Rate limiter ---
[TaskUpdate: in_progress]
[Dispatch implementer — standard model, multi-file]
Implementer: DONE_WITH_CONCERNS — "rate limit config should be env var"
[Note concern, dispatch spec reviewer]
Spec reviewer: FAIL — missing per-route config from spec
[Implementer fixes, spec re-review: PASS]
[Dispatch quality reviewer: PASS]
[Write task-2-rate-config.md with config shape for Task 3]
[TaskUpdate: done]

--- Task 3: Integration tests ---
[TaskUpdate: in_progress]
[Dispatch implementer — reads task-2-rate-config.md for setup]
Implementer: DONE
[Reviews: PASS/PASS]
[TaskUpdate: done]

[Dispatch final cross-task reviewer]
[arsyn:finalizing]

Integration

• arsyn:isolating — set up isolated workspace before starting
• arsyn:planning — creates the plan this skill executes
• arsyn:tdd — subagents follow TDD for each task
• arsyn:requesting-review — review template for reviewer subagents
• arsyn:finalizing — complete development after all tasks
• arsyn:executing — alternative: parallel sessions instead of same-session subagents

Gotchas

• Trusting agent success reports — Agents claim "done" without proof. Always check VCS diff and run tests independently after each subagent.
• Passing full session context — Subagents get precisely crafted task context, not your conversation history. Bloated context degrades quality.
• Skipping reviews to save time — The two-stage gate (spec then quality) catches different failure modes. Skipping either accumulates hidden debt.
• Retrying without changes — When a subagent fails, something must change: more context, better model, smaller scope, or different approach.
• Parallel implementation dispatch — Multiple implementers on the same codebase cause merge conflicts. Sequential dispatch only.
• Starting quality review before spec passes — Wrong order. Spec compliance first, always. Quality review on non-compliant code wastes cycles.
• Tasks with shared mutable state — If two tasks modify the same files or depend on each other's output ordering, they cannot be safely dispatched to separate subagents. Merge them or sequence explicitly.
• Forgetting TaskUpdate — Stale task status breaks coordination. Update immediately on completion or blocker.