Subagent Templates
How scaffolded specialists inherit pack guidance, ownership, and boundaries
Subagent templates follow the project shape.
They are generated from selected packs, so a repo with Next.js surfaces gets Next.js-aware worker contracts, and a repo with Effect backend surfaces gets Effect-aware worker contracts. The template starts from detected scope, not from an imaginary org chart.
A useful template replaces job-title prompting with repository facts: which backend or frontend work exists, which scope the worker owns, which skills it must use, and what evidence should guide its output.
Generated From Project Evidence
punks scaffold setup builds subagent guidance from the same evidence used by pack selection:
- selected packs
- detected dependencies and file extensions
- scoped prompt guidance
- owned paths
- required skills
- scope boundaries
The conceptual boundary is simple: templates are generated from repo evidence, while resolver mechanics belong in CLI docs. Once generated, the template should make that evidence actionable for the worker.
Template Contract
A subagent template should make the worker contract explicit:
| Field | Purpose |
|---|---|
| Scope | The product or code surface the worker is allowed to reason about. |
| Ownership | The paths it may edit, or the readonly research boundary it must stay inside. |
| Skills | The required skills inherited from the selected packs. |
| Evidence | The files, examples, specs, or logs it should inspect before acting. |
| Output | The handoff shape: findings, changed paths, checks run, or remaining blockers. |
For readonly work, templates can support aggressive parallel research because the output is evidence and findings. For write work, ownership must be narrow enough that two workers cannot silently edit the same surface from different assumptions.
Specialists Follow Surfaces
Repo facts determine the actual specialist set. Some repositories need Next.js UI workers, Effect backend workers, docs maintenance workers, review workers, data-layer workers, or validation support. Other repositories should leave those templates out.
Expertise has to be backed by context. "Next.js worker" is useful only when it carries Next.js skills, owned Next.js paths, and relevant source examples. Without that context it collapses back into persona prompting.
The baseline code-review specialist is readonly for the same reason. It can range across changed code because it produces findings, risks, missing tests, and scoped-guidance violations, not edits.
Root prompt guidance also routes split-friendly readonly orientation through parallel-research. Use it when independent evidence sources, subsystems, docs, backlog items, or hypotheses can be inspected in parallel. Keep code-writing and tightly coupled debugging in the main thread unless ownership can be split cleanly.
Default Workflow Archetypes
Some templates are distributed by default because they support repeated inner steps of Harness skills rather than repo-specific implementation surfaces. These archetypes keep the parent thread small while preserving parent ownership of decisions, user interaction, artifact writes, and external provider sync.
| Archetype | Used for |
|---|---|
planning-discovery | Readonly orientation before spec or plan writing. |
requirements-synthesizer | Readonly compression of grill status/log artifacts into accepted and unresolved choices. |
backlog-shaper | Draft-only module, epic, and story shaping from closed requirements. |
spec-reviewer | Readonly review of drafted specs before user review. |
plan-reviewer | Readonly review of plan dependencies, task shape, validation, and assigned skills. |
These archetypes are not substitutes for phase skills. swarm-planner remains a planner skill run by the parent orchestrator, not a subagent template. UX research is not a default archetype; design/product research belongs to the relevant frontend or product-specific pack when a repo actually has that surface.
Drift And Safety
Template drift is visible when workers overlap in write ownership, stop citing evidence, ignore required skills, or receive specialists that do not match the repository. The fix is usually to update the selected packs, scoped guidance, or generated templates through the scaffold flow.
Spawn fewer, better-scoped workers. Each one should carry the right local context before it starts.