Agent Task Specification

A task spec is the contract between an orchestrator and a sub-agent. Good specs prevent the #1 delegation failure: agents wasting tokens rediscovering what the orchestrator already knew.

The Task Spec Template

This template has been validated through hundreds of delegations. Copy it, fill it in, and delegate with confidence.

## Task: [Verb] + [Object] — One-Line Summary

### Environment Context
- OS: [Windows/macOS/Linux] + version
- Shell: [PowerShell/bash/zsh] + known quirks
- Runtime: Node.js [version], Python [version], etc.
- Working directory: /path/to/project
- Known quirks: [anything that tripped you up]
- Available tools: [git, npm, curl, etc.]

### Objective
What to accomplish, in 1-3 sentences.
Include WHY if it helps the agent make judgment calls.

### Input Files
- `path/to/file1.ts` — What's in it, what to look for
- `path/to/file2.ts` — Relevant context
<!-- KEY: If you already read these files, paste the
     relevant excerpts. Don't force the agent to re-read
     what you already know. -->

### Expected Output
- **File:** `path/to/output.md`
- **Format:** Markdown / JSON / TypeScript / etc.
- **Structure:** Describe headings, schema, or skeleton
- **Length:** Approximate ("~500 lines", "2000-4000 words")

### Success Criteria
- [ ] Criterion 1 (observable, verifiable)
- [ ] Criterion 2
- [ ] Criterion 3

### Constraints
- DO NOT: [explicit boundaries]
- MUST: [non-negotiable requirements]
- MAY: [optional/nice-to-have]

### Failure Protocol
If stuck for >5 minutes or >3 retries:
1. Report what you tried
2. Report what failed and why
3. Suggest what the orchestrator could do
4. Do NOT loop — exit gracefully

### Verification
How to check if the work is correct:
- "Run \`npm run build\` — zero errors"
- "File should import from \`@/lib/api-client\`"
- "All 15 endpoints should be documented"

The Environment Context Block

This is the single most impactful section. 78% of delegation failures in our logs trace back to missing environment context. The agent doesn't know:

• What operating system it's running on
• Shell-specific quirks (PowerShell vs bash syntax)
• Which tools and versions are available
• Where the project lives on disk
• Known gotchas the orchestrator already discovered

Create a reusable environment block and paste it into every task spec:

### Environment Context
- OS: Windows 11 (PowerShell 5.1 — NOT bash)
- Shell quirks: Get-Content -Raw does NOT work.
  Use [System.IO.File]::ReadAllText() instead.
- Use semicolons (;) not && to chain commands
- Node.js: v22.20.0 | npm: 10.9.3
- Git: available, authenticated to GitHub
- Working directory: C:\Users\Dev\project-name
- Vercel CLI: available (vercel --prod for deploy)

The Delegation Decision Tree

Before spawning a sub-agent, walk through this decision tree:

1. Have I already loaded the relevant context?
   • Yes → Context transfer cost is high. Lean toward doing it yourself.
   • No → Delegation might save total tokens.
2. Is the task larger than my comfortable execution scope?
   • Yes → Delegate (break into pieces if needed).
   • No → Just do it.
3. Does it require different capabilities?
   • Yes → Delegate to a specialized agent.
   • No → No reason to split.
4. Can I run it in parallel with other work?
   • Yes → Delegate for parallelism benefit.
   • No → Sequential advantage is limited.
5. Will I delegate this type of task again?
   • Yes → Invest in a thorough spec (pays dividends).
   • No → Minimal spec is fine.

Optional Sections (Add When Relevant)

Prior Art / Examples

Links or excerpts showing what similar output looks like. Especially valuable for research, writing, or style-sensitive tasks. Reduces ambiguity dramatically.

Idempotency Note

What should the agent do if the work appears already done?

• "If imports already point to the new client, report completion and skip"
• "Always regenerate from scratch regardless of current state"
• "Check git status first; if files modified in last commit, verify rather than redo"

FAQ

How detailed should a task spec be?

Match detail to risk and novelty. High-risk or first-time tasks need comprehensive specs (environment context, constraints, failure protocols, verification steps). Routine tasks with proven patterns can use minimal specs. When in doubt, err on the side of more context — an agent can ignore extra information but can't invent missing context.

Should I paste file contents into the task spec?

Yes, for key excerpts. If you've already read a file and extracted the relevant sections, paste them directly. This eliminates the agent's need to re-read and re-parse, saving both tokens and time. Don't paste entire large files — just the relevant interfaces, function signatures, or configuration blocks.