q2wxec delegation-rules
Generates a delegation rules document grounded in Claude Code's agent orchestration design — where the orchestrator retains understanding, sub-agents protect the main context window, and every delegation brief is self-contained.
Source-grounded principles
From src/constants/prompts.ts (lines 316-320) and the Agent tool design:
Never duplicate what sub-agents do — "Avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself."
If you are the fork — execute directly — "If you ARE the fork — execute directly; do not re-delegate." Sub-agents must not spawn further sub-agents for the same task.
Sub-agents protect the main context window — Agent tool runs in fork mode: tool output stays out of the orchestrator's context unless the orchestrator explicitly reads the result. This is the core reason to delegate.
Brief like a smart colleague — "Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried." Every sub-agent prompt must be fully self-contained.
Synthesize before delegating downstream — The orchestrator synthesizes findings. It never hands raw sub-agent output to another sub-agent and asks it to "figure out what this means."
What to keep at orchestrator level
Never delegate these:
| Work type | Why it stays with the orchestrator |
|---|---|
| Synthesis of multiple agent results | Only the orchestrator has all results in context |
| Final decision between options | Requires full picture; sub-agents see only their slice |
| User communication about progress | Requires awareness of overall state |
| Understanding of the overall goal | Cannot be re-derived by a sub-agent from a brief |
| Context that spans multiple delegations | Sub-agents are stateless; the orchestrator is the thread |
What can be delegated
Safe to delegate (sub-agents do one of these):
| Delegation type | Example prompt shape |
|---|---|
| Research with clear output format | "Find all usages of function X in this codebase. Return a list of file:line pairs. Cap at 50 results." |
| Implementation with clear spec | "Implement function parseConfig(input: string): Config in src/config.ts. Inputs/outputs defined below. Return the final file content." |
| Verification with binary verdict | "Run these specific checks: [list]. Return PASS / FAIL / PARTIAL with evidence for each." |
| Exploration with structured output | "List all files matching **/*.test.ts. Return file paths, one per line." |
| Targeted analysis | "Read src/auth/session.ts and list every place user input touches the database without parameterization. Return file:line + code snippet." |
Delegation anti-patterns
| Anti-pattern | Problem | Fix |
|---|---|---|
| "Based on your findings, now..." | Sub-agent has no prior findings | Include the findings explicitly in the prompt |
| "As we discussed earlier..." | Sub-agents don't see conversation history | Paste the relevant excerpt |
| "Investigate the auth module" | No deliverable specified | Specify: what to look for, what format to return |
| No file paths, only vague descriptions | Agent must re-discover what orchestrator already knows | Include exact paths, function names, line numbers |
| No output format | Orchestrator can't parse the result reliably | Specify format and length cap |
| "Look into this, use your judgment" | No context for judgment calls | State the goal, constraints, and what "good" looks like |
| Re-delegating within a sub-agent | Infinite fork chains, context explosion | Sub-agents execute; only orchestrator delegates |
Prompt quality checklist
Before sending a prompt to a sub-agent:
- The agent has no conversation history — tell it everything it needs
- State what you've already tried or ruled out
- Specify the output format exactly (list, JSON, markdown table, verdict line)
- Set a length cap ("cap at N results", "max 500 words")
- Include the reason this matters (enables judgment calls)
- Use file paths and function names — never vague descriptions
- No "based on previous research" — paste the research
Design process
Step 1 — Identify workflow type
Ask the user or infer from context:
- Code review — orchestrator coordinates read-only reviewers
- Feature development — orchestrator coordinates planner / implementer / verifier
- Debugging — orchestrator coordinates log-reader / reproducer / fixer
- Data analysis — orchestrator coordinates data-fetcher / transformer / summarizer
Step 2 — Map the work
For the workflow, list every distinct work unit. Then classify each:
Stays at orchestrator: synthesis, decisions, user communication Delegates: bounded tasks with clear inputs, outputs, and success criteria
Step 3 — Draft delegation briefs
For each delegated task, produce a brief template:
GOAL: [one sentence — what this agent must produce]
CONTEXT: [what the orchestrator already knows that's relevant]
ALREADY TRIED: [what's been ruled out]
SCOPE: [exact files / functions / data ranges to look at]
OUTPUT FORMAT: [exact structure]
LENGTH CAP: [max N results / words]
JUDGMENT GUIDE: [what "good enough" means for this task]
Step 4 — Output
Produce a delegation rules document containing:
- Orchestrator responsibilities — what it never delegates
- Delegation map — work type → sub-agent type → brief template
- Prompt quality checklist — customized to the workflow
- Anti-patterns for this workflow — specific failure modes to avoid
- Example before/after — one bad prompt rewritten as a good one
Before/after example
Bad prompt (code review workflow):
Review the authentication code and check for security issues.
Based on what you find, also look at how sessions are managed.
Issues: vague scope, no output format, chained delegation, no context.
Good prompt:
GOAL: Identify SQL injection risks in the user authentication path.
SCOPE: Read these files only: src/auth/login.ts, src/db/userQueries.ts
CONTEXT: We use raw string concatenation in queryUser() — confirmed at line 47 of userQueries.ts.
We want to know if this pattern appears elsewhere in the auth path.
ALREADY RULED OUT: src/auth/oauth.ts uses parameterized queries throughout — skip it.
OUTPUT FORMAT: List of file:line + code snippet for each risk found. Max 20 results.
End with: VERDICT: CRITICAL / HIGH / NONE
JUDGMENT GUIDE: Flag anything where user-controlled input reaches a DB query without
explicit parameterization or escaping.
Workflow-specific templates
Use scripts/delegation_audit.py --generate-template <workflow-type> to generate
a ready-to-fill delegation brief template for:
code-review— coordinating read-only security and quality reviewersfeature-dev— planner / implementer / verifier chaindebugging— reproducer / root-cause / fixer chaindata-analysis— fetcher / transformer / summarizer chain