Background knowledge for writing and launching subagent prompts. Covers prompt file conventions, worker identity declarations, batch dispatch patterns, and parallel swarm safety. Auto-invocable when dispatching agents.
disable-model-invocation
false
Subagent Protocol
Use when: launching delegated work — claude agents via the Task tool, or CLI agents (Codex/Gemini) directly.
Subagents come in two kinds
Claude agents — dispatched via the Task tool. Most of this skill is
about these.
CLI agents — Codex, Gemini, and other external reviewer/agent CLIs.
Dispatched by running their CLI directly (e.g.
codex exec --dangerously-bypass-approvals-and-sandbox "..."), NOT via the
Task tool. See the external-agents skill for invocation details.
A CLI agent IS a subagent. Running its CLI is the dispatch act — the shell
equivalent of the Task tool. NEVER wrap a CLI agent inside a Task subagent
(spawning a claude agent just to type the CLI command). That is
double-dispatch: wasted wall-clock and tokens, and it buries the external
agent's independent judgement behind a claude proxy. Run the CLI directly.
The prompt-file conventions in this skill (physical prompt file, single
deliverable, exact paths, report location) apply to BOTH kinds — a CLI agent
reads the same kind of prompt file. The worker-identity declaration and the
agent-type rule (see "CRITICAL: Agent Type") apply ONLY to claude Task agents.
CRITICAL: Agent Type
Dispatch a write-capable agent type. This plugin ships four tool-scoped role agents — subagent_type: scout, coder, analyst, verifier — that each have Write and are built to produce reports; use them for their gauntlet roles. Use subagent_type: general-purpose for work that doesn't fit a role.
NEVER use READ-ONLY agent types (Explore, Plan, or similar) as workers, even in planning mode — they cannot write report files to ./reports/ and will fail. Since subagents must write reports, the type you pick MUST be write-capable.
The Problem
Subagents start fresh. They don't know directory structure, file paths, common workarounds, or project conventions. Inline prompts get long, lose context, and you forget critical info.
Solution: Physical Prompt Files
Always write prompts to files. This provides:
Context preservation (subagent gets full instructions)
Before launching any subagent, ensure both directories exist.
CRITICAL: Worker Identity Declaration
Every subagent prompt MUST start with this line before anything else:
You are a WORKER agent launched via the Task tool. Execute this task directly. Do NOT read foreman.md. Do NOT coordinate — DO the work yourself.
This goes at the very top of every prompt file AND in the Task tool's prompt parameter. Non-negotiable.
Prompt File Template
Write to ./prompts/{task-name}.md:
**You are a WORKER agent launched via the Task tool. Execute this task directly. Do NOT read foreman.md. Do NOT coordinate — DO the work yourself.**# Task: [Clear Title]## Context
[What the subagent needs to know about the project state]
## Objective
[Single, specific deliverable]
## Files to Read-`exact/path/to/file.py` - why relevant
## Files to Modify-`exact/path/to/file.py` - what to change
## Test Command` ``bash
[exact command to verify success]
` ``
## Output
Write findings/status to `./reports/{task-name}-report.md`## CRITICAL: File Modified Error Workaround
If Edit/Write fails with "file unexpectedly modified":
1. Read the file again with Read tool
2. Retry the Edit
3. Try path formats: `./relative`, `C:/forward/slashes`, `C:\back\slashes`4. NEVER use cat, sed, echo - always Read/Edit/Write
5. If all formats fail, STOP and report - do not use bash workarounds
Launching
In Task tool message:
@prompts/{task-name}.md
Execute this task. Write your report to ./reports/{task-name}-report.md when done.
If prompt has multiple verbs (run, compare, analyze, fix, document), you're asking too much.
Prompt Length Matches Task Size
One-sentence task = one-sentence prompt. State the goal, not the process. Agents are competent — don't hand-hold. A 50-line prompt for "download a screenshot" is you wasting everyone's time. If you can say it in one sentence, the prompt IS one sentence.
Batch Dispatch — One Template, Many Agents
When dispatching N subagents doing the same task on different inputs (e.g., processing 7 papers, fixing 5 files), write ONE template prompt file. Each agent references the same @prompts/batch-taskname.md with only the varying parameter (URL, path, title) in the Task tool's prompt field. Do NOT write N near-identical prompt files.
CRITICAL: Scout Prompts — Verify, Don't Speculate
Every scout prompt MUST include this constraint:
Do not speculate. Every claim in your report must be verified by reading source code or observing test output. If you cannot verify something, say "I did not verify this" — do not use words like "may", "possibly", "might", "could be", or "likely". If you don't know, say you don't know. Trace the actual code path. Read the actual source. An unverified theory presented as a finding is worse than no finding at all.
This is not optional. This goes in every scout prompt. Every single one.
Checklist Before Dispatch
Worker identity declaration at top of prompt (both file AND Task tool prompt param)
Prompt written to physical file
Single clear deliverable
Exact file paths included
Test/verification command included
File-modified workaround included
Output location specified
NO-ONELINERS rule restated verbatim and prominently in the prompt — workers do NOT auto-load this skill, so the dispatcher must copy it into every coder/worker prompt
"No skipped tests" stated explicitly (if testing)
If scout: "verify, don't speculate" constraint included (see above)
Every factual claim about code cites a source (scout report file:line, or code you read yourself)
If foreman mode: prompt contains NO implementation details — only objective, file, constraints, and a reference to the scout report
No "Root Cause", "Fix Required", "Key Insight", or "Context" sections that describe code behavior without a citation
If the task is an experiment, benchmark, performance optimization,
solver comparison, or routing trial: the worker prompt explicitly forbids
switching to, merging into, rebasing, cherry-picking onto, pushing, or
otherwise moving the integration branch. Worker may recommend promotion
only; a separate verifier/foreman/parent must independently verify and
promote. The prompt must also instruct the worker to run
ward set experiment-worker right after creating the experiment branch,
so the integration-branch ban is mechanically enforced by the
experiment-gate ward rule, not merely stated in prose.
CRITICAL: Parallel Swarm Awareness
You may be running alongside other agents in parallel.
FORBIDDEN GIT COMMANDS - NEVER USE THESE:
git stash - DESTROYS uncommitted work across the entire repo
git restore - overwrites files
git checkout - overwrites files
git reset - destroys commits/changes
git clean - deletes untracked files
If you mess up a file beyond repair: STOP, write what happened to your report, exit.
Foreman will decide what to do.
Do NOT try to "fix" or "clean up" - you'll destroy other agents' work.
CRITICAL: Never Overwrite Existing Prompts
Prompt files are an audit trail. If prompts/scout-foo.md already exists from a previous session, do NOT overwrite it. Pick a new name: prompts/scout-foo-v2.md, prompts/scout-foo-format.md, or any descriptive variant. Filenames are not a scarce resource. Overwriting destroys the record of what was dispatched before.
CRITICAL: No Oneliners
Never write python -c "..." or uv run python -c "...". Not even for "quick" checks. Write a .py file, then run it.
Why: A python -c oneliner evaporates after one use. The next agent that needs the same data must regenerate the entire thing from scratch. A script file is a reusable artifact: write once, run forever, zero marginal token cost.
Write to scripts/something.py first, then uv run python scripts/something.py. No exceptions.
Workers do not auto-load this skill. The dispatcher MUST restate this rule, in full and prominently, in every coder/worker prompt file — otherwise the worker has no source for it and will reach for oneliners. See the dispatch checklist.
Rules
ALWAYS write prompt to physical file first
ALWAYS reference with @prompts/filename.md
ALWAYS specify output location in ./reports/
NEVER write multi-paragraph inline prompts
NEVER let subagent ask questions - give everything upfront
ALWAYS include parallel swarm warning in prompts
NEVER overwrite an existing prompt file - use a new name instead
NEVER write python -c oneliners - always write to a .py file first
