Bug: Generated orchestrator reads code directly instead of dispatching specialist subagents

[Cpicon]

Summary

The project-debugger agent generated by /generate-debugger is designed to orchestrate specialist subagents. When run via claude --agent project-debugger, it consistently reads source code directly using Read/Grep tools instead of dispatching specialists via the Agent tool.

Root Cause (Three Contributing Factors)

1. tools field doesn't restrict base tools in --agent mode

The tools field in agent frontmatter only controls which subagents can be spawned (via Agent(name1, name2) syntax). It does NOT restrict base tools (Read, Write, Grep, Glob, Bash, Edit) when the agent runs as the main thread via --agent.

This means removing Read/Grep from the tools list to "force delegation" has zero effect. The model always has access to all base tools in --agent mode.

2. Negative instructions are deprioritized by the model

System prompt instructions like "NEVER investigate source code yourself", "Coordinate, not implement", and "You do NOT read .py files" were consistently ignored across multiple attempts. The model optimizes for efficiency and takes the shortest path (reading files directly).

3. Missing Agent in original tools list

The generated orchestrator did not include Agent(specialist1, specialist2, ...) in its tools field, making subagent dispatching impossible.

What Failed (Chronological)

Attempt	Change	Result
1	Added "CRITICAL: NEVER investigate source code yourself"	Ignored — model still used Read/Grep
2	Removed Glob/Grep from tools field	No effect — --agent mode has all base tools
3	Rewrote Core Rule #1 as "ALWAYS dispatch specialists"	Ignored — negative/imperative framing deprioritized

What Works

Restructuring the system prompt as a mandatory 4-step procedural workflow where dispatching is a prerequisite for analysis:

## MANDATORY WORKFLOW

You MUST follow these 4 steps in order. You CANNOT skip or reorder steps.
You CANNOT proceed to Step 3 without completing Step 2.

### Step 1: Understand the Problem
Read the user's message and any referenced reports.

### Step 2: Dispatch Specialists (REQUIRED -- DO NOT SKIP)
You MUST use the Agent tool to dispatch at least one specialist
BEFORE you write any analysis. If you find yourself about to
write "Root Cause" or "Analysis" without having dispatched an
Agent, STOP and dispatch one first.

### Step 3: Synthesize
AFTER all dispatched specialists return, combine their findings.

### Step 4: Report and Save
Write the debugging report and save it.

Key insight: procedural gates ("you must do Y before Z") work far better than negative instructions ("don't do X") for controlling model behavior.

Recommended Fix for Plugin

1. Add Agent(specialist1, specialist2, ...) to the orchestrator's tools list in the generation template
2. Replace the "Core Rules" style system prompt with the mandatory workflow structure above
3. Include a concrete Agent tool call example in the system prompt showing subagent_type and a detailed prompt string
4. Do NOT rely on tools-field restrictions to control behavior — they don't work for base tools in --agent mode

Impact

The orchestrator does all investigation itself, defeating the purpose of having specialist subagents. The multi-agent architecture collapses into a single-agent architecture.

Environment: Claude Code v2.1.79, macOS
Related: Split from #8