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>
|
||||
Reference in New Issue
Block a user