delegation-check

Invoked when user requests "check delegation", "delegation conflict", "prompt vs role check", or when reviewing workflow skill quality.

<required_reading>

• @.claude/skills/delegation-check/specs/separation-rules.md </required_reading>

1. Determine Scan Scope

Parse $ARGUMENTS to identify what to check.

Signal	Scope
File path to command .md	Single command + its agents
File path to agent .md	Single agent + commands that spawn it
Directory path (e.g., .claude/skills/team-*/)	All commands + agents in that skill
"all" or no args	Scan all .claude/commands/, .claude/skills/*/, .claude/agents/

If ambiguous, ask:

AskUserQuestion(
  header: "Scan Scope",
  question: "What should I check for delegation conflicts?",
  options: [
    { label: "Specific skill", description: "Check one skill directory" },
    { label: "Specific command+agent pair", description: "Check one command and its spawned agents" },
    { label: "Full scan", description: "Scan all commands, skills, and agents" }
  ]
)

2. Discover Command-Agent Pairs

For each command file in scope:

2a. Extract Agent() calls from commands:

# Search both Agent() (current) and Task() (legacy GSD) patterns
grep -n "Agent(\|Task(" "$COMMAND_FILE"
grep -n "subagent_type" "$COMMAND_FILE"

For each Agent() call, extract:

• subagent_type → agent name
• Full prompt content between the prompt markers (the string passed as prompt=)
• Line range of the delegation prompt

2b. Locate agent definitions:

For each subagent_type found:

# Check standard locations
ls .claude/agents/${AGENT_NAME}.md 2>/dev/null
ls .claude/skills/*/agents/${AGENT_NAME}.md 2>/dev/null

2c. Build pair map:

$PAIRS = [
  {
    command: { path, agent_calls: [{ line, subagent_type, prompt_content }] },
    agent: { path, role, sections, quality_gate, output_contract }
  }
]

If an agent file cannot be found, record as MISSING_AGENT — this is itself a finding.

3. Parse Delegation Prompts

For each Agent() call, extract structured blocks from the prompt content:

Block	What It Contains
<objective>	What to accomplish
<files_to_read>	Input file paths
<additional_context> / <planning_context> / <verification_context>	Runtime parameters
<output> / <expected_output>	Output format/location expectations
<quality_gate>	Per-invocation quality checklist
<deep_work_rules> / <instructions>	Cross-cutting policy or revision instructions
<downstream_consumer>	Who consumes the output
<success_criteria>	Success conditions
Free-form text	Unstructured instructions

Also detect ANTI-PATTERNS in prompt content:

• Role identity statements ("You are a...", "Your role is...")
• Domain expertise (decision tables, heuristics, comparison examples)
• Process definitions (numbered steps, step-by-step instructions beyond scope)
• Philosophy statements ("always prefer...", "never do...")
• Anti-pattern lists that belong in agent definition

4. Parse Agent Definitions

For each agent file, extract:

Section	Key Content
<role>	Identity, spawner, responsibilities, mandatory read
<philosophy>	Guiding principles
<upstream_input>	How agent interprets input
<output_contract>	Return markers (COMPLETE/BLOCKED/CHECKPOINT)
<quality_gate>	Self-check criteria
Domain sections	All <section_name> tags with their content
YAML frontmatter	name, description, tools

5. Run Conflict Checks (7 Dimensions)

Dimension 1: Role Re-definition

Question: Does the delegation prompt redefine the agent's identity?

Check: Scan prompt content for:

• "You are a..." / "You are the..." / "Your role is..."
• "Your job is to..." / "Your responsibility is..."
• "Core responsibilities:" lists
• Any content that contradicts agent's <role> section

Allowed: References to mode ("standard mode", "revision mode") that the agent's <role> already lists in "Spawned by:".

Severity: error if prompt redefines role; warning if prompt adds responsibilities not in agent's <role>.

Dimension 2: Domain Expertise Leak

Question: Does the delegation prompt embed domain knowledge that belongs in the agent?

Check: Scan prompt content for:

• Decision/routing tables (| Condition | Action |)
• Good-vs-bad comparison examples (| TOO VAGUE | JUST RIGHT |)
• Heuristic rules ("If X then Y", "Always prefer Z")
• Anti-pattern lists ("DO NOT...", "NEVER...")
• Detailed process steps beyond task scope

Exception: <deep_work_rules> is an acceptable cross-cutting policy pattern from GSD — flag as info only.

Severity: error if prompt contains domain tables/examples that duplicate agent content; warning if prompt contains heuristics not in agent.

Dimension 3: Quality Gate Duplication

Question: Do the prompt's quality checks overlap or conflict with the agent's own <quality_gate>?

Check: Compare prompt <quality_gate> / <success_criteria> items against agent's <quality_gate> items:

• Duplicate: Same check appears in both → warning (redundant, may diverge)
• Conflict: Contradictory criteria (e.g., prompt says "max 3 tasks", agent says "max 5 tasks") → error
• Missing: Prompt expects quality checks agent doesn't have → info

Severity: error for contradictions; warning for duplicates; info for gaps.

Dimension 4: Output Format Conflict

Question: Does the prompt's expected output format conflict with the agent's <output_contract>?

Check:

• Prompt <expected_output> markers vs agent's <output_contract> return markers
• Prompt expects specific format agent doesn't define
• Prompt expects file output but agent's contract only defines markers (or vice versa)
• Return marker names differ (prompt expects ## DONE, agent returns ## TASK COMPLETE)

Severity: error if return markers conflict; warning if format expectations unspecified on either side.

Dimension 5: Process Override

Question: Does the delegation prompt dictate HOW the agent should work?

Check: Scan prompt for:

• Numbered step-by-step instructions ("Step 1:", "First..., Then..., Finally...")
• Process flow definitions beyond <objective> scope
• Tool usage instructions ("Use grep to...", "Run bash command...")
• Execution ordering that conflicts with agent's own execution flow

Allowed: <instructions> block for revision mode (telling agent what changed, not how to work).

Severity: error if prompt overrides agent's process; warning if prompt suggests process hints.

Dimension 6: Scope Authority Conflict

Question: Does the prompt make decisions that belong to the agent's domain?

Check:

• Prompt specifies implementation choices (library selection, architecture patterns) when agent's <philosophy> or domain sections own these decisions
• Prompt overrides agent's discretion areas
• Prompt locks decisions that agent's <context_fidelity> says are "Claude's Discretion"

Allowed: Passing through user-locked decisions from CONTEXT.md — this is proper delegation, not authority conflict.

Severity: error if prompt makes domain decisions agent should own; info if prompt passes through user decisions (correct behavior).

Dimension 7: Missing Contracts

Question: Are the delegation handoff points properly defined?

Check:

• Agent has <output_contract> with return markers → command handles all markers?
• Command's return handling covers COMPLETE, BLOCKED, CHECKPOINT
• Agent lists "Spawned by:" — does command actually spawn it?
• Agent expects <files_to_read> — does prompt provide it?
• Agent has <upstream_input> — does prompt provide matching input structure?

Severity: error if return marker handling is missing; warning if agent expects input the prompt doesn't provide.

6. Aggregate and Report

6a. Per-pair summary

For each command-agent pair, aggregate findings:

{command_path} → {agent_name}
  Agent() at line {N}:
    D1 (Role Re-def):      {PASS|WARN|ERROR} — {detail}
    D2 (Domain Leak):       {PASS|WARN|ERROR} — {detail}
    D3 (Quality Gate):      {PASS|WARN|ERROR} — {detail}
    D4 (Output Format):     {PASS|WARN|ERROR} — {detail}
    D5 (Process Override):  {PASS|WARN|ERROR} — {detail}
    D6 (Scope Authority):   {PASS|WARN|ERROR} — {detail}
    D7 (Missing Contract):  {PASS|WARN|ERROR} — {detail}

6b. Overall verdict

Verdict	Condition
CLEAN	0 errors, 0-2 warnings
REVIEW	0 errors, 3+ warnings
CONFLICT	1+ errors

6c. Fix recommendations

For each finding, provide:

• Location: file:line
• What's wrong: concrete description
• Fix: move content to correct owner (command or agent)
• Example: before/after snippet if applicable

7. Present Results

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 DELEGATION-CHECK ► SCAN COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scope: {description}
Pairs checked: {N} command-agent pairs
Findings: {E} errors, {W} warnings, {I} info

Verdict: {CLEAN | REVIEW | CONFLICT}

| Pair | D1 | D2 | D3 | D4 | D5 | D6 | D7 |
|------|----|----|----|----|----|----|-----|
| {cmd} → {agent} | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ | ✅ |
| ... | | | | | | | |

{If CONFLICT: detailed findings with fix recommendations}

───────────────────────────────────────────────────────

## Fix Priority

1. {Highest severity fix}
2. {Next fix}
...

───────────────────────────────────────────────────────

<success_criteria>

• Scan scope determined and all files discovered
• All Agent() calls extracted from commands with full prompt content
• All corresponding agent definitions located and parsed
• 7 conflict dimensions checked for each command-agent pair
• No false positives on legitimate patterns (mode references, user decision passthrough, <deep_work_rules>)
• Fix recommendations provided for every error/warning
• Summary table with per-pair dimension results displayed
• Overall verdict determined (CLEAN/REVIEW/CONFLICT) </success_criteria>