Agent Flow — Main Claude Orchestration Guide

All agent invocations are performed by Main Claude. Sub-agents only return results (dispatch XML or task-result XML) after completing their work. Main Claude receives return values and invokes the next agent.

---

Pipeline Flow

[] tag detected → invoke specifier
    │
    Check specifier return value
    │
    ├─ Assumed (direct) → specifier creates Requirement.md + PLAN.md + TASK-00
    │                      → returns builder dispatch XML
    │                      → execute § direct procedure
    │
    └─ Delegated (pipeline/full) → specifier creates Requirement.md only
                                    → returns planner dispatch XML
                                    → execute § planner-driven procedure

---

Direct Mode (Specifier Assumes Planner)

1. Invoke specifier → creates Requirement.md + PLAN.md + TASK-00 + returns builder dispatch XML
2. ⛔ STOP — Present summary to user and WAIT for approval (do NOT invoke builder)
3. Invoke builder (dispatch XML as prompt) — includes self-check
4. Invoke verifier+committer (builder result as prompt) — verify then commit in one spawn

Verifier+Committer combined: single spawn performs verification, then creates result.md and git commit.

---

Pipeline Mode (Separate Planner Invocation)

1. Invoke specifier+planner (single spawn) → creates Requirement.md + PLAN.md + TASK-NN + determines execution-mode
2. ⛔ STOP — Present Requirement.md + PLAN.md + TASK list and WAIT for approval
3. Invoke builder (per-TASK dispatch XML as prompt)
4. Invoke verifier+committer (builder result as prompt) — verify then commit in one spawn

Specifier+Planner combined: specifier.md role first (Requirement.md), then planner.md role (PLAN.md + TASKs) in one spawn.

---

Full Mode (With Scheduler)

1. Invoke specifier+planner (single spawn) → Requirement.md + PLAN.md + TASKs + execution-mode: full
2. ⛔ STOP — Present Requirement.md + PLAN.md + TASK list and WAIT for approval
3. Invoke scheduler → DAG analysis + READY TASK + returns builder dispatch XML
4. Invoke builder (dispatch XML as prompt) → implementation
5. Invoke verifier+committer (builder result as prompt) → verify then commit in one spawn
6. If incomplete TASKs remain, return to step 3

Parallel execution: When scheduler returns multiple READY TASKs, invoke builders concurrently.

---

Resuming Existing WORK

Resume pipeline for a WORK that already has PLAN.md + TASKs:

1. Invoke scheduler → check READY TASKs + return builder dispatch XML
2. Invoke builder → implementation
3. Invoke verifier+committer → verify then commit in one spawn
4. If incomplete TASKs remain, return to step 1

---

Combined Agent Invocation

Specifier+Planner (single spawn)

When invoking specifier in pipeline/full mode, include both agent definitions:

Prompt to agent:
  "You will perform two roles in sequence.

   Role 1 — Specifier: Read specifier.md and create Requirement.md.
   Role 2 — Planner: Read planner.md and create PLAN.md + TASK files.

   Execute Role 1 first, then Role 2. Return the combined result."

• Use specifier's model (opus) for the spawn
• Agent reads both specifier.md and planner.md from REFERENCES_DIR
• Returns: Requirement.md + PLAN.md + TASK files + execution-mode

Verifier+Committer (single spawn)

When invoking verification after builder completes:

Prompt to agent:
  "You will perform two roles in sequence.

   Role 1 — Verifier: Read verifier.md and verify build/lint/test.
   Role 2 — Committer: Read committer.md and create result.md + git commit.

   Execute Role 1 first. If verification PASSES, execute Role 2.
   If verification FAILS, skip Role 2 and return FAIL result."

• Use verifier's model (haiku) for the spawn
• Agent reads both verifier.md and committer.md from REFERENCES_DIR
• On PASS: returns verification result + commit hash
• On FAIL: returns verification failure only (no commit)

---

Agent Role Summary

Agent	Role	Model	Combined With
specifier	Requirement analysis	opus	+ planner (pipeline/full)
planner	PLAN + TASK decomposition	opus	combined into specifier spawn
scheduler	DAG management + dispatch	haiku	standalone
builder	Code implementation	sonnet	standalone
verifier	Build/lint/test verification	haiku	+ committer
committer	Result report + git commit	haiku	combined into verifier spawn

---

Sub-agent Spawn Count by Mode

Mode	Spec+Plan	Scheduler	Builder	Veri+Commit	Total
direct	1 (assumed)	—	1	1	3
pipeline	1 (combined)	—	1	1	3
full (N TASKs)	1 (combined)	1	N	N	2 + 2N

Before vs After (6 TASKs):

	Before	After	Reduction
Spawns	2 + 3×6 = 20	2 + 2×6 = 14	-30%

---

Approval Gates (CRITICAL)

MUST STOP and wait for explicit user approval before invoking the next agent. Do NOT proceed until the user says "approve", "승인", "proceed", "go ahead", or equivalent. The only exception is auto mode — when the user's original message contains "auto" or "자동으로".

Mode	Approvals	Timing	What to show user
direct	1	After Specifier completes	Requirement.md + PLAN.md + TASK-00.md summary
pipeline/full	1	After Specifier+Planner completes	Requirement.md + PLAN.md + TASK list
auto-approve	0	—	Skip all approval gates

Note: pipeline/full now has 1 approval (not 2), since specifier and planner run in one spawn.

How to request approval:

1. Present a summary of what the specifier+planner created (files, scope, execution-mode)
2. Ask: "Proceed?" or equivalent
3. WAIT for user response — do NOT invoke builder until approved

---

Bash CLI Execution (Server Automation)

Run the pipeline independently without a conversation session. claude -p acts as Main Claude.

env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
  "[new-work] {task description}" \
  --dangerously-skip-permissions \
  --output-format stream-json \
  --verbose \
  2>&1 | tee /tmp/pipeline.log

Option	Purpose
env -u CLAUDECODE	Bypass nested execution block
env -u ANTHROPIC_API_KEY	Use subscription auth (Max) instead of API key
--dangerously-skip-permissions	Skip permission prompts for unattended execution
--output-format stream-json --verbose	Streaming for real-time monitoring

Resume interrupted pipeline:

env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
  "Resume WORK-XX pipeline." \
  --dangerously-skip-permissions

---

References Directory Passing (REQUIRED)

Main Claude MUST pass the references directory path to every sub-agent invocation. This allows sub-agents to locate their reference files regardless of installation method (npm or plugin).

How to pass:

• Prepend REFERENCES_DIR={absolute_path} at the top of the prompt for every Task tool call
• For npm installations: use .claude/agents (default, resolved from project root)
• For plugin installations: derive from the skill's "Base directory" ({base_dir}/../sdd-pipeline/references)

Example:

REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/skills/sdd-pipeline/references

<dispatch to="builder" ...>
  ...
</dispatch>

If REFERENCES_DIR is not available (e.g., npm installation without plugin), sub-agents fall back to .claude/agents/.

---

Context Handoff (Sliding Window)

Distance	Level	Content
Previous	FULL	what + why + caution + incomplete
2 steps back	SUMMARY	what 1-2 lines
3+ steps	DROP	Not passed

---

ref-cache Chain Propagation

<ref-cache> carries pre-loaded reference file contents through the pipeline, eliminating redundant disk reads in each sub-agent.

Rules

1. First agent (typically specifier) — no ref-cache available on dispatch. Reads reference files from REFERENCES_DIR normally.

2. Agent returns task-result — if the agent supports ref-cache, it includes <ref-cache> in its task-result XML containing all reference files it loaded.

3. Main Claude propagates ref-cache — when dispatching the next agent, copy the <ref-cache> block from the previous task-result into the new dispatch XML unchanged.

4. Receiving agent skips file reads — when <ref-cache> is present in the dispatch XML, the agent reads reference content from <ref> elements instead of reading files from disk.

5. Missing ref-cache — if a task-result does not contain <ref-cache> (agent does not support it yet), omit <ref-cache> from the next dispatch. The receiving agent falls back to reading files from disk.

Flow Example

specifier+planner (no ref-cache in) → reads files → returns task-result with <ref-cache>
  ↓ Main Claude copies <ref-cache> into dispatch
builder (ref-cache in) → skips file reads → returns task-result with <ref-cache>
  ↓ Main Claude copies <ref-cache> into dispatch
verifier+committer (ref-cache in) → skips file reads → commit

Phase 2: Selective Section Delivery

Instead of passing full reference files, Main Claude extracts only the sections each agent needs. This reduces dispatch token size by 50-70%.

Main Claude reads reference files once at pipeline start, then delivers condensed <ref-cache> per agent using this mapping:

Agent	shared-prompt-sections	file-content-schema	xml-schema	context-policy	work-activity-log
specifier+planner	§1,§2,§7,§8,§9,§11	§0,§1,§2,§3	§1,§3	—	full
scheduler	§4,§8,§10	§1,§6	§1,§3,§4,§5	full	full
builder	§1,§2,§10,§12	§2,§3	§1,§2,§4	Builder section	full
verifier+committer	§1,§2,§8,§10,§12	§3,§4,§5,§6,§7	§1,§2,§4	Verifier+Committer	full

Delivery format: Condense each <ref key=""> to contain only the needed sections, not the full file. Use one-line summaries for simple rules, keep full content only for templates and code blocks.

Constraints

• ref-cache does not replace REFERENCES_DIR — always pass REFERENCES_DIR (or <references-dir>) in every dispatch regardless of ref-cache presence, for backward compatibility.
• Agents may still read files — if ref-cache content is insufficient, agents fall back to reading from disk.