Claude-Code-Workflow/.claude/skills/delegation-check/specs/separation-rules.md

GSD Content Separation Rules

Rules for validating the boundary between command delegation prompts (Agent() calls) and agent role definitions (agent .md files). Derived from analysis of GSD's plan-phase.md, execute-phase.md, research-phase.md and their corresponding agents (gsd-planner, gsd-plan-checker, gsd-executor, gsd-phase-researcher, gsd-verifier).

Core Principle

Commands own WHEN and WHERE. Agents own WHO and HOW.

A delegation prompt tells the agent what to do this time. The agent definition tells the agent who it always is.

Ownership Matrix

Command Delegation Prompt Owns

Concern	XML Block	Example
What to accomplish	<objective>	"Execute plan 3 of phase 2"
Input file paths	<files_to_read>	"- {state_path} (Project State)"
Runtime parameters	<additional_context>	"Phase: 5, Mode: revision"
Output location	<output>	"Write to: {phase_dir}/RESEARCH.md"
Expected return format	<expected_output>	"## VERIFICATION PASSED or ## ISSUES FOUND"
Who consumes output	<downstream_consumer>	"Output consumed by /gsd:execute-phase"
Revision context	<instructions>	"Make targeted updates to address checker issues"
Cross-cutting policy	<deep_work_rules>	Anti-shallow execution rules (applies to all agents)
Per-invocation quality	<quality_gate> (in prompt)	Invocation-specific checks (e.g., "every task has <read_first>")
Flow control	Revision loops, return routing	"If TASK COMPLETE → step 13. If BLOCKED → offer options"
User interaction	AskUserQuestion	"Provide context / Skip / Abort"
Banners	Status display	"━━━ GSD ► PLANNING PHASE {X} ━━━"

Agent Role Definition Owns

Concern	XML Section	Example
Identity	<role>	"You are a GSD planner"
Spawner list	<role> → Spawned by	"/gsd:plan-phase orchestrator"
Responsibilities	<role> → Core responsibilities	"Decompose phases into parallel-optimized plans"
Mandatory read protocol	<role> → Mandatory Initial Read	"MUST use Read tool to load every file in <files_to_read>"
Project discovery	<project_context>	"Read CLAUDE.md, check .claude/skills/"
Guiding principles	<philosophy>	Quality degradation curve by context usage
Input interpretation	<upstream_input>	"Decisions → LOCKED, Discretion → freedom"
Decision honoring	<context_fidelity>	"Locked decisions are NON-NEGOTIABLE"
Core insight	<core_principle>	"Plan completeness ≠ Goal achievement"
Domain expertise	Named domain sections	<verification_dimensions>, <task_breakdown>, <dependency_graph>
Return protocol	<output_contract>	TASK COMPLETE / TASK BLOCKED / CHECKPOINT REACHED
Self-check	<quality_gate> (in agent)	Permanent checks for every invocation
Anti-patterns	<anti_patterns>	"DO NOT check code existence"
Examples	<examples>	Scope exceeded analysis example

Conflict Patterns

Pattern 1: Role Re-definition

Symptom: Delegation prompt contains identity language.

# BAD — prompt redefines role
Agent({
  subagent_type: "gsd-plan-checker",
  prompt: "You are a code quality expert. Your job is to review plans...
    <objective>Verify phase 5 plans</objective>"
})

# GOOD — prompt states objective only
Agent({
  subagent_type: "gsd-plan-checker",
  prompt: "<verification_context>
    <files_to_read>...</files_to_read>
  </verification_context>
  <expected_output>## VERIFICATION PASSED or ## ISSUES FOUND</expected_output>"
})

Why it's wrong: The agent's <role> section already defines identity. Re-definition in prompt can contradict, confuse, or override the agent's self-understanding.

Detection: Regex for You are a|Your role is|Your job is to|Your responsibility is|Core responsibilities: in prompt content.

Pattern 2: Domain Expertise Leak

Symptom: Delegation prompt contains decision tables, heuristics, or examples.

# BAD — prompt embeds domain knowledge
Agent({
  subagent_type: "gsd-planner",
  prompt: "<objective>Create plans for phase 3</objective>
    Remember: tasks should have 2-3 items max.
    | TOO VAGUE | JUST RIGHT |
    | 'Add auth' | 'Add JWT auth with refresh rotation' |"
})

# GOOD — agent's own <task_breakdown> section owns this knowledge
Agent({
  subagent_type: "gsd-planner",
  prompt: "<planning_context>
    <files_to_read>...</files_to_read>
  </planning_context>"
})

Why it's wrong: Domain knowledge in prompts duplicates agent content. When agent evolves, prompt doesn't update — they diverge. Agent's domain sections are the single source of truth.

Exception — <deep_work_rules>: GSD uses this as a cross-cutting policy block (not domain expertise per se) that applies anti-shallow-execution rules across all agents. This is acceptable because:

1. It's structural policy, not domain knowledge
2. It applies uniformly to all planning agents
3. It supplements (not duplicates) agent's own quality gate

Detection:

• Tables with | in prompt content (excluding <files_to_read> path tables)
• "Good:" / "Bad:" / "Example:" comparison pairs
• "Always..." / "Never..." / "Prefer..." heuristic statements
• Numbered rules lists (>3 items) that aren't revision instructions

Pattern 3: Quality Gate Duplication

Symptom: Same quality check appears in both prompt and agent definition.

# PROMPT quality_gate
- [ ] Every task has `<read_first>`
- [ ] Every task has `<acceptance_criteria>`
- [ ] Dependencies correctly identified

# AGENT quality_gate
- [ ] Every task has `<read_first>` with at least the file being modified
- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
- [ ] Dependencies correctly identified

Analysis:

• "Dependencies correctly identified" → duplicate (exact match)
• "<read_first>" in both → overlap (prompt is less specific than agent)
• "<acceptance_criteria>" → overlap (same check, different specificity)

When duplication is OK: Prompt's <quality_gate> adds invocation-specific checks not in agent's permanent gate (e.g., "Phase requirement IDs all covered" is specific to this phase, not general).

Detection: Fuzzy match quality gate items between prompt and agent (>60% token overlap).

Pattern 4: Output Format Conflict

Symptom: Command expects return markers the agent doesn't define.

# COMMAND handles:
- "## VERIFICATION PASSED" → continue
- "## ISSUES FOUND" → revision loop

# AGENT <output_contract> defines:
- "## TASK COMPLETE"
- "## TASK BLOCKED"

Why it's wrong: Command routes on markers. If markers don't match, routing breaks silently — command may hang or misinterpret results.

Detection: Extract return marker strings from both sides, compare sets.

Pattern 5: Process Override

Symptom: Prompt dictates step-by-step process.

# BAD — prompt overrides agent's process
Agent({
  subagent_type: "gsd-planner",
  prompt: "Step 1: Read the roadmap. Step 2: Extract requirements.
    Step 3: Create task breakdown. Step 4: Assign waves..."
})

# GOOD — prompt states objective, agent decides process
Agent({
  subagent_type: "gsd-planner",
  prompt: "<objective>Create plans for phase 5</objective>
    <files_to_read>...</files_to_read>"
})

Exception — Revision instructions: <instructions> block in revision prompts is acceptable because it tells the agent what changed (checker issues), not how to work.

# OK — revision context, not process override
<instructions>
Make targeted updates to address checker issues.
Do NOT replan from scratch unless issues are fundamental.
Return what changed.
</instructions>

Detection: "Step N:" / "First..." / "Then..." / "Finally..." patterns in prompt content outside <instructions> blocks.

Pattern 6: Scope Authority Conflict

Symptom: Prompt makes domain decisions the agent should own.

# BAD — prompt decides implementation details
Agent({
  subagent_type: "gsd-planner",
  prompt: "Use React Query for data fetching. Use Zustand for state management.
    <objective>Plan the frontend architecture</objective>"
})

# GOOD — user decisions passed through from CONTEXT.md
Agent({
  subagent_type: "gsd-planner",
  prompt: "<planning_context>
    <files_to_read>
    - {context_path} (USER DECISIONS - locked: React Query, Zustand)
    </files_to_read>
  </planning_context>"
})

Key distinction:

• Prompt making decisions = conflict (command shouldn't have domain opinion)
• Prompt passing through user decisions = correct (user decisions flow through command to agent)
• Agent interpreting user decisions = correct (agent's <context_fidelity> handles locked/deferred/discretion)

Detection: Technical nouns (library names, architecture patterns) in prompt free text (not inside <files_to_read> path descriptions).

Pattern 7: Missing Contracts

Symptom: Handoff points between command and agent are incomplete.

Missing Element	Impact
Agent has no <output_contract>	Command can't route on return markers
Command doesn't handle all agent return markers	BLOCKED/CHECKPOINT silently ignored
Agent expects <files_to_read> but prompt doesn't provide it	Agent starts without context
Agent's "Spawned by:" doesn't list this command	Agent may not expect this invocation pattern
Agent has <upstream_input> but prompt doesn't match structure	Agent misinterprets input

Detection: Cross-reference both sides for completeness.

The <deep_work_rules> Exception

GSD's plan-phase uses <deep_work_rules> in delegation prompts. This is a deliberate design choice, not a violation:

1. It's cross-cutting policy: applies to ALL planning agents equally
2. It's structural: defines required fields (<read_first>, <acceptance_criteria>, <action> concreteness) — not domain expertise
3. It supplements agent quality: agent's own <quality_gate> is self-check; deep_work_rules is command-imposed minimum standard
4. It's invocation-specific context: different commands might impose different work rules

Rule: <deep_work_rules> in a delegation prompt is info level, not error. Flag only if its content duplicates agent's domain sections verbatim.

Severity Classification

Severity	When	Action Required
error	Actual conflict: contradictory content between prompt and agent	Must fix — move content to correct owner
warning	Duplication or boundary blur without contradiction	Should fix — consolidate to single source of truth
info	Acceptable pattern that looks like violation but isn't	No action — document why it's OK

Quick Reference: Is This Content in the Right Place?

Content	In Prompt?	In Agent?
"You are a..."	❌ Never	✅ Always
File paths for this invocation	✅ Yes	❌ No
Phase number, mode	✅ Yes	❌ No
Decision tables	❌ Never	✅ Always
Good/bad examples	❌ Never	✅ Always
"Write to: {path}"	✅ Yes	❌ No
Return markers handling	✅ Yes (routing)	✅ Yes (definition)
Quality gate	✅ Per-invocation	✅ Permanent self-check
"MUST read files first"	❌ Agent's <role> owns this	✅ Always
Anti-shallow rules	⚠️ OK as cross-cutting policy	✅ Preferred
Revision instructions	✅ Yes (what changed)	❌ No
Heuristics / philosophy	❌ Never	✅ Always
Banner display	✅ Yes	❌ Never
AskUserQuestion	✅ Yes	❌ Never