| name | prd-agent-brief |
| description | Generate a sub-agent invocation brief from the standard template before spawning any impl, validator, or learner sub-agent in the build loop. The brief bakes in runaway mitigations, file-ownership contracts, role-typed permissions, token budgets, and a structured report format. Use this skill whenever the orchestrator is about to spawn a sub-agent, or when `prd-validator` or `prd-learner` is preparing an agent invocation. Trigger when the user says things like "brief a sub-agent", "spawn an impl agent", "fan out", or "draft a brief". The orchestrator never writes prose briefs by hand once this skill exists; it fills slots. |
Skill: prd-agent-brief
Purpose: Compose a sub-agent invocation brief by filling a template. The brief is the contract between the orchestrator and the sub-agent. Every safety property the build relies on (file-ownership, runaway mitigation, honest degradation, role permissions) lives in this brief, not in scattered conversation prose.
When to Use
| Trigger | What happens |
|---|
| The orchestrator is about to spawn a sub-agent | Generate the brief, return the full prompt string |
prd-validator or prd-learner needs an agent invocation | Compose the brief with role = validator or learner |
| The user says "brief X for Y task" | Ask for the missing slots, then compose |
Step 1: Collect Slots
Required:
| Slot | Description |
|---|
task | One-line description of what the agent does |
role | impl | validator | learner (drives the agent definition and permission envelope) |
project_scope | Path to the project's working directory |
may_write | Explicit list of files or globs the agent is allowed to write |
may_not_touch | Explicit list of files or globs the agent must not modify (shared coordination files, frozen contracts, files owned by parallel agents) |
token_budget | Hard ceiling, e.g. 40000 |
context_pack | Path to the current CONTEXT-PACK.md (generated by prd-context-pack). The agent reads this instead of the full corpus |
success_criteria | What "done" looks like — acceptance criteria, file deliverables, test pass conditions |
Optional:
| Slot | Description |
|---|
required_reading | Files beyond the context pack the agent must read (keep small) |
parallel_with | Names of other agents running concurrently. Drives the file-ownership cross-check |
prior_attempts | Notes from prior failed attempts on the same task |
If any required slot is missing, ask the orchestrator before composing.
Step 2: Run the File-Ownership Cross-Check
If parallel_with is set, read the current Fan-out registry via the prd-loop skill. Verify:
- No overlap between this agent's
may_write and any active agent's may_write.
- Any shared file appears in this agent's
may_not_touch and is delimited by markers (e.g., # AGENT-X SECTION START / END) inside the shared file, or is append-only.
If overlap is detected, halt and report. Do not compose a brief that allows a collision.
Step 3: Compose the Brief
Fill this template literally. Do not add prose outside the slots.
# Sub-Agent Brief — <task>
**Role:** <role>
**Project:** <project_scope>
**Token budget:** <token_budget> (hard stop; report and halt if approached)
**Spawned by:** orchestrator
---
## Required reading (in this order)
1. `<project_scope>/CONTEXT-PACK.md` — current frozen contracts, active ADR rules, schema digest, phase map. **Read this first.**
2. <each required_reading entry>
Do not re-read the full PRD, full ADR set, or full build-docs corpus. The context pack is the curated subset.
---
## Task
<task — expanded to one paragraph if needed, no more>
## Success criteria
<success_criteria as a checklist>
---
## File-ownership contract
**MAY-WRITE:**
<may_write as a bulleted list>
**MAY-NOT-TOUCH:**
<may_not_touch as a bulleted list>
Shared files use delimited blocks. Append-only coordination files split into `<file>-PHASE-X.md` if you encounter 3 merge conflicts. If you need to write a file not in MAY-WRITE, halt and report — do not write it.
## Parallel agents
<parallel_with — names + their may_write lists for awareness, or "none">
---
## Runaway mitigations
- Write a heartbeat line to `<project_scope>/HEARTBEAT-<agent-name>.log` after every meaningful step (file written, test run, decision made).
- Prefer pre-installed local binaries over network-fetching runners (e.g. avoid `npx <pkg>` when the local binary exists).
- Hard 5-minute budget per debug issue. If exceeded, mark blocked, move on. Do not loop.
- If a single operation will take more than 60s, stream progress lines.
## Build / verification protocol
<role-specific — see Step 4 for the defaults>
## Honest degradation
If you hit a seam you cannot cross (auth boundary, frozen migration, missing infra), build the surface, wire it to a documented contract, degrade visibly. Document the partial-by-design AC explicitly in the report. **Never** fake success, **never** silently skip state, **never** invent architecture to pass a check.
If a genuine architectural fork appears, halt and surface to the orchestrator. Do not guess past it.
## Report format
Return a structured report:
status: done | blocked | partial
summary: <2-3 lines>
files_written:
files_modified:
tests_passing: /
partials_by_design:
escalations: <decisions to surface to the human, if any>
notes_for_learner:
heartbeat_log:
If `status = blocked` or there are escalations, write the report and stop. Do not retry without orchestrator direction.
The notes_for_learner field is the pipe that feeds prd-learner and build-learner. Sub-agents that observe a pattern or apply a workaround record it there; the learning skills consume it after validation.
Step 4: Apply Role Defaults
The Build / verification protocol block fills based on role:
impl:
- After every file write, run the project's typecheck and any directly affected tests.
- After the task, run the full test suite for the touched scope.
- Commit nothing. The orchestrator commits at checkpoint boundaries.
validator:
- Read-only against source. May execute build, typecheck, and test commands.
- Run the acceptance criteria checklist literally. For each AC:
pass | fail | partial-by-design | not-applicable plus a one-line citation.
- A dishonest fallback in the impl output is a hard fail, not a partial.
- Output the validation report. Do not edit source files. Do not propose fixes (that is the learner's job).
learner:
- Read-only. No file writes during the run except the LEARNINGS proposal file.
- Output proposals only: PRD amendments, ADR amendments, rule generalizations, workaround signatures to record.
- Reference exact current text and proposed replacement for every amendment, so the orchestrator can apply mechanically after human approval.
Step 5: Return the Brief
Return the composed brief as a string the orchestrator passes verbatim into the Agent tool with subagent_type: <role> (which maps to .claude/agents/<role>.md — these agent definitions ship with this repo).
Also update the loop state via the prd-loop skill:
- Append a row to the Fan-out registry with agent name, role, phase, may_write summary, status
running, started timestamp.
Edge Cases
- No context pack exists yet. Run the
prd-context-pack skill first. Do not spawn an agent that has to read the full corpus.
- Slot list looks wrong. If
may_write is suspiciously broad ("the whole repo") or success_criteria is vague ("make it work"), refuse to compose and ask for tighter slots.
- Three-way fan-out or more. Run the file-ownership cross-check against every active agent in the registry, not just the most recent. The cost of a missed overlap compounds.
- Validator without an executable build. If the validator role needs to run tests but the agent definition does not grant Bash, halt. A validator that cannot execute is not actually validating.
- Re-brief after a blocked agent. If a sub-agent returned
blocked, do not re-brief identically. Either narrow the task, change the role, or surface to the human as a decision.
