orchestrating

Files (5)

• SKILL.md
• agent-sdk-patterns.md · references/
• code-quality-reviewer-prompt.md · references/
• implementer-prompt.md · references/
• spec-reviewer-prompt.md · references/

SKILL.md (first lines)

# 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

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn