prd-agent-brief

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.