mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-18 18:48:48 +08:00
Refactor agent spawning and delegation check mechanisms
- Updated agent spawning from `Task()` to `Agent()` across various files to align with new standards. - Enhanced the `code-developer` agent description to clarify its invocation context and responsibilities. - Introduced a new `delegation-check` skill to validate command delegation prompts against agent role definitions, ensuring content separation and conflict detection. - Established comprehensive separation rules for command delegation prompts and agent definitions, detailing ownership and conflict patterns. - Improved documentation for command and agent design specifications to reflect the updated spawning patterns and validation processes.
This commit is contained in:
catlog22
290
.claude/skills/delegation-check/SKILL.md
Normal file
290
.claude/skills/delegation-check/SKILL.md
Normal file
@@ -0,0 +1,290 @@
|
||||
---
|
||||
name: delegation-check
|
||||
description: Check workflow delegation prompts against agent role definitions for content separation violations. Detects conflicts, duplication, boundary leaks, and missing contracts. Triggers on "check delegation", "delegation conflict", "prompt vs role check".
|
||||
allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Validate that command delegation prompts (Agent() calls) and agent role definitions respect GSD content separation boundaries. Detects 7 conflict dimensions: role re-definition, domain expertise leaking into prompts, quality gate duplication, output format conflicts, process override, scope authority conflicts, and missing contracts.
|
||||
|
||||
Invoked when user requests "check delegation", "delegation conflict", "prompt vs role check", or when reviewing workflow skill quality.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
- @.claude/skills/delegation-check/specs/separation-rules.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 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:**
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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}
|
||||
...
|
||||
|
||||
───────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<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>
|
||||
269
.claude/skills/delegation-check/specs/separation-rules.md
Normal file
269
.claude/skills/delegation-check/specs/separation-rules.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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 |
|
||||
@@ -165,14 +165,14 @@ Generate a complete command file with:
|
||||
3. **`<process>`** — numbered steps (GSD workflow style):
|
||||
- Step 1: Initialize / parse arguments
|
||||
- Steps 2-N: Domain-specific orchestration logic
|
||||
- Each step: banner display, validation, agent spawning via `Task()`, error handling
|
||||
- Each step: banner display, validation, agent spawning via `Agent()`, error handling
|
||||
- Final step: status display + `<offer_next>` with next actions
|
||||
4. **`<success_criteria>`** — checkbox list of verifiable conditions
|
||||
|
||||
**Command writing rules:**
|
||||
- Steps are **numbered** (`## 1.`, `## 2.`) — follow `plan-phase.md` and `new-project.md` style
|
||||
- Use banners for phase transitions: `━━━ SKILL ► ACTION ━━━`
|
||||
- Agent spawning uses `Task(prompt, subagent_type, description)` pattern
|
||||
- Agent spawning uses `Agent({ subagent_type, prompt, description, run_in_background })` pattern
|
||||
- Prompt to agents uses `<objective>`, `<files_to_read>`, `<output>` blocks
|
||||
- Include `<offer_next>` block with formatted completion status
|
||||
- Handle agent return markers: `## TASK COMPLETE`, `## TASK BLOCKED`, `## CHECKPOINT REACHED`
|
||||
@@ -286,7 +286,7 @@ Set `$TARGET_PATH = $SOURCE_PATH` (in-place conversion) unless user specifies ou
|
||||
| `<process>` with numbered steps | At least 3 `## N.` headers |
|
||||
| Step 1 is initialization | Parses args or loads context |
|
||||
| Last step is status/report | Displays results or routes to `<offer_next>` |
|
||||
| Agent spawning (if complex) | `Task(` call with `subagent_type` |
|
||||
| Agent spawning (if complex) | `Agent({` call with `subagent_type` |
|
||||
| Agent prompt structure | `<files_to_read>` + `<objective>` or `<output>` blocks |
|
||||
| Return handling | Routes on `## TASK COMPLETE` / `## TASK BLOCKED` markers |
|
||||
| `<offer_next>` | Banner + summary + next command suggestion |
|
||||
|
||||
@@ -4,7 +4,7 @@ Guidelines for Claude Code **agent definition files** (role + domain expertise).
|
||||
|
||||
## Content Separation Principle
|
||||
|
||||
Agents are spawned by commands via `Task()`. The agent file defines WHO the agent is and WHAT it knows. It does NOT define WHEN or HOW it gets invoked.
|
||||
Agents are spawned by commands via `Agent()`. The agent file defines WHO the agent is and WHAT it knows. It does NOT define WHEN or HOW it gets invoked.
|
||||
|
||||
| Concern | Belongs in Agent | Belongs in Command |
|
||||
|---------|-----------------|-------------------|
|
||||
|
||||
@@ -153,15 +153,15 @@ Display banners before major phase transitions (agent spawning, user decisions,
|
||||
|
||||
## Agent Spawning Pattern
|
||||
|
||||
Commands spawn agents via `Task()` with structured prompts:
|
||||
Commands spawn agents via `Agent()` with structured prompts:
|
||||
|
||||
```markdown
|
||||
Task(
|
||||
prompt=filled_prompt,
|
||||
subagent_type="agent-name",
|
||||
model="{model}",
|
||||
description="Verb Phase {X}"
|
||||
)
|
||||
```javascript
|
||||
Agent({
|
||||
subagent_type: "agent-name",
|
||||
prompt: filled_prompt,
|
||||
description: "Verb Phase {X}",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
### Prompt Structure for Agents
|
||||
|
||||
@@ -49,7 +49,7 @@ Conversion Summary:
|
||||
| `## Auto Mode` / `## Auto Mode Defaults` | `<auto_mode>` section |
|
||||
| `## Quick Reference` | Preserve as-is within appropriate section |
|
||||
| Inline `AskUserQuestion` calls | Preserve verbatim — these belong in commands |
|
||||
| `Task()` / agent spawning calls | Preserve verbatim within process steps |
|
||||
| `Agent()` / agent spawning calls | Preserve verbatim within process steps |
|
||||
| Banner displays (`━━━`) | Preserve verbatim |
|
||||
| Code blocks (```bash, ```javascript, etc.) | **Preserve exactly** — never modify code content |
|
||||
| Tables | **Preserve exactly** — never reformat table content |
|
||||
|
||||
@@ -49,12 +49,13 @@ allowed-tools: {tools} # omit if unrestricted
|
||||
|
||||
{Construct prompt with <files_to_read>, <objective>, <output> blocks.}
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=filled_prompt,
|
||||
subagent_type="{agent-name}",
|
||||
description="{Verb} {target}"
|
||||
)
|
||||
```javascript
|
||||
Agent({
|
||||
subagent_type: "{agent-name}",
|
||||
prompt: filled_prompt,
|
||||
description: "{Verb} {target}",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
## 4. Handle Result
|
||||
|
||||
Reference in New Issue
Block a user