Write a subagent brief
Turns a task into a self-contained brief for a subagent or parallel agent, with the goal, context, scope, constraints, return format and definition of done. Use before delegating to another agent.
A subagent starts with an empty context. It cannot see this conversation, does not know what you already tried, and will fill gaps with plausible guesses. Most failed delegations come from three gaps: the goal is a topic instead of an outcome, the boundaries are unstated so the agent edits things it should not, and the return format is undefined so the result cannot be checked or merged. Parallel agents fail in one more way: overlapping scope, where two agents edit the same files.
Write brief(s) for this task:
- Gather what the subagent needs and cannot see: relevant file paths, commands, decisions already made, approaches already rejected and why, and the user's standing instructions. Read the files you reference so the paths are right.
- State the goal as an outcome with a definition of done that can be checked ("the three failing tests in
tests/api/pass and no other test fails"), not as an activity ("look into the API tests"). - Set the scope: the files or areas it may change, the ones it must not touch, and the actions that need approval or are forbidden (pushing, deleting, installing dependencies, network calls).
- Define the return format: what to report and in which structure, including evidence (commands run and their real output) and anything it could not do.
- If more than one agent: split the work so no two briefs share files or decisions, say what each agent can assume about the others, and say how the results will be combined.
- Size each brief so it can finish in one session. If the task is too big or too vague to delegate safely, say so and list what must be decided first.
- Each brief must be self-contained: no "as above", "the issue we discussed" or references to this conversation.
- Include only context that changes what the subagent does. Do not paste whole files; give paths and the lines that matter.
- Never put secrets, tokens or personal data in a brief.
- Do not delegate decisions that belong to the user; list them as open questions instead.
For each brief, a fenced markdown block ready to paste, containing these headings: Goal, Context, Scope (may change / must not change), Constraints, Steps (only if the order matters), Return format, Done when.
After the briefs: how the results will be checked and combined, and any open questions for the user.
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Coding-agent operations
- level
- Intermediate
- made for
- Software engineer, Tech lead / staff engineer
- needs
- repo-read
- risk
- read-only
- version
- v1.0.0 · experimental
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install write-subagent-brief --target claude-codenpx skills add hermes-hq/hodios-dist --skill write-subagent-brief -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of Coding-agent operationsWrite an agent handoff
Writes a self-contained handoff note so a fresh agent or a teammate can continue the current task without the conversation history. Use before ending a long session, switching tools or delegating.
write-agent-handoffReview a coding agent transcript
Reviews a coding agent session transcript for where it went wrong (bad assumptions, skipped verification, scope creep, looping) and turns each failure into an instruction-file or prompt change.
review-agent-transcriptWrite an agent skill
Writes a reusable agent skill (SKILL.md with frontmatter, steps, scripts and references) from a repeated task, with a trigger description models can match and a test plan. Use to package a workflow.
write-agent-skillWrite an AGENTS.md
Writes or updates a repository's AGENTS.md with the verified commands, layout, conventions and boundaries a coding agent needs, and nothing generic. Use when setting up a repo for coding agents.
write-agents-mdAudit a coding agent's permissions
Reviews a coding agent's tool, permission and sandbox configuration for shell, network, secrets and write-scope risk, and proposes least privilege. Use before giving an agent more autonomy.
audit-agent-permissions