Task Spec Template

Reusable templates for delegating work to AI sub-agents. Includes the universal template and four specialized variations for code, research, content creation, and debugging tasks. Born from a 78K token delegation failure that produced zero useful output.

Universal Task Spec Template

This template works for any delegation. Every section answers one of the five critical questions: What do you want? Where does it go? What does "done" look like? What does the agent need to know? What should it do if stuck?

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

### Environment Context
- OS: [Windows 11 / macOS / Ubuntu] + version
- Shell: [PowerShell / bash / zsh] + known quirks
- Runtime: Node.js [version], Python [version], etc.
- Working directory: /home/user/project-name
- Known quirks: [anything that tripped you up]
- Available tools: [git, npm, curl, docker, 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 section alone prevents the majority of delegation failures. Create a reusable block for your specific environment and paste it into every 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 remote
- Working directory: C:\Users\dev\project-name
- Deploy CLI: available (deploy --prod)

Why this matters: Without environment context, agents guess. They try bash syntax on Windows, use unavailable tools, and burn tokens in retry loops. A 5-line environment block saves thousands of tokens downstream.

Variation: Code Task

For coding tasks, add build/test commands, target files, and code style constraints:

## Task: Migrate API client from REST to GraphQL

### Environment Context
[paste your reusable block here]
- Build: `npm run build` (must pass with zero errors)
- Test: `npm test` (must pass with zero failures)
- Lint: `npm run lint` (should pass, warnings OK)

### Objective
Replace all REST API calls with GraphQL queries.
The app currently uses fetch() for REST calls in 6 files.
Migrate to the new GraphQL client without breaking any
existing functionality.

### Target Files
- `src/lib/api-client.ts` — current REST client (replace)
- `src/lib/graphql-client.ts` — new client (already exists)
- `src/hooks/use-projects.ts` — uses old client
- `src/hooks/use-users.ts` — uses old client
- `src/app/api/sync/route.ts` — uses old client
- `src/app/api/export/route.ts` — uses old client

### Code Style Constraints
- Use TypeScript strict mode (no `any` types)
- Preserve existing error handling patterns
- Keep function signatures backward-compatible
- Add JSDoc comments to new public functions

### Success Criteria
- [ ] `npm run build` passes with zero errors
- [ ] `npm test` passes with zero failures
- [ ] All 6 files migrated to GraphQL client
- [ ] No remaining imports from `api-client.ts`
- [ ] Types are strict (no `any`)

### Verification
```bash
# Build check
npm run build

# Test check
npm test

# Verify no old imports remain
grep -r "api-client" src/ --include="*.ts" --include="*.tsx"
# Should return zero results
```

### Failure Protocol
If a test fails after migration:
1. Document which test failed and why
2. Revert that specific file to original
3. Report the issue — do not guess at fixes

Variation: Research Task

For research tasks, add scope boundaries, source preferences, and depth/breadth tradeoffs:

## Task: Research current state of AI agent frameworks

### Environment Context
[paste your reusable block here]
- Web search: available
- File write: available

### Objective
Survey the current landscape of AI agent frameworks
(as of January 2026). Focus on production-ready tools,
not academic prototypes. The output will inform our
architecture decision for a new agent system.

### Scope
- IN SCOPE: Frameworks with >1000 GitHub stars, active
  maintenance, and documentation
- IN SCOPE: Pricing, licensing, and hosting requirements
- OUT OF SCOPE: Academic papers, unreleased tools
- OUT OF SCOPE: Comparison with non-agent LLM libraries

### Source Preferences
1. Official documentation (highest weight)
2. GitHub repositories (star count, recent commits)
3. Recent blog posts (2025-2026 only)
4. Avoid: marketing pages, sponsored reviews

### Expected Output
- **File:** `research/agent-frameworks-survey.md`
- **Structure:**
  - Executive summary (3-5 sentences)
  - Comparison table (framework × criteria)
  - Detailed sections per framework
  - Recommendation with reasoning
- **Length:** 2000-4000 words
- **Tone:** Technical, objective, no hype

### Depth vs Breadth
- Cover 5-7 frameworks at medium depth
- Rather than 15 frameworks at shallow depth
- Go deeper on top 3 most relevant to our use case

### Success Criteria
- [ ] Covers at least 5 major frameworks
- [ ] Each framework has: description, pros, cons, pricing
- [ ] Comparison table is complete and accurate
- [ ] Recommendation is justified with specific criteria
- [ ] All claims are sourced (URLs included)

Variation: Content Creation Task

For content tasks, add tone, audience, SEO requirements, and example content to match:

## Task: Write documentation for the authentication module

### Environment Context
[paste your reusable block here]

### Objective
Create developer documentation for the auth module.
Target audience: mid-level developers integrating our
auth system for the first time.

### Style Guide
- Tone: Technical but approachable (not academic)
- Voice: Second person ("you") — guiding the reader
- Code examples: TypeScript, with inline comments
- NO jargon without explanation
- NO assumptions about prior auth knowledge

### Content Structure
- **File:** `docs/auth/getting-started.md`
- **Sections:**
  1. Overview (what it does, when to use it)
  2. Quick start (working example in <5 minutes)
  3. Configuration options (table format)
  4. Common patterns (3-4 real use cases)
  5. Troubleshooting (5 most common issues)
  6. API reference (auto-linked from code)

### SEO Requirements
- Primary keyword: "authentication module setup"
- Include in: title, first paragraph, one H2
- Meta description: 150-160 characters
- Alt text on any diagrams

### Reference Content
Match the style of `docs/database/getting-started.md`
(already exists — read it for tone and format reference).

### Success Criteria
- [ ] Quick start example actually works (tested)
- [ ] All configuration options documented
- [ ] At least 3 code examples with output shown
- [ ] Troubleshooting covers the 5 most common errors
- [ ] Word count: 1500-2500 words

Variation: Debugging Task

For debugging tasks, the key additions are: symptom description, reproduction steps, what you've already tried, and relevant logs:

## Task: Debug intermittent 500 errors on /api/projects endpoint

### Environment Context
[paste your reusable block here]
- Error tracking: check `logs/error.log` for stack traces
- Database: PostgreSQL 16, connection pool max 20

### Symptom
The /api/projects endpoint returns HTTP 500 approximately
20% of the time. No pattern by time of day or user. The
error is: "connection terminated unexpectedly".

### Reproduction Steps
1. Start the dev server: `npm run dev`
2. Send 10 rapid requests: `for i in {1..10}; do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/projects; done`
3. Expect: ~2 of 10 requests return 500

### What I've Already Tried
- Restarted the database — no change
- Increased connection pool to 50 — slightly worse
- Checked database logs — "too many connections" warnings
- Confirmed other endpoints work fine

### Relevant Log Excerpts
```
[ERROR] 2026-01-29T10:15:23Z - /api/projects
  Error: connection terminated unexpectedly
  at Pool.query (node_modules/pg/lib/pool.js:45:11)
  at getProjects (src/app/api/projects/route.ts:23:18)

[WARN] 2026-01-29T10:15:23Z - PostgreSQL
  FATAL: too many connections for role "app_user"
```

### Hypothesis (Optional)
Likely a connection leak — queries not releasing connections
back to the pool. Check for missing `client.release()` calls
or unhandled promise rejections in database query functions.

### Expected Output
1. Root cause identified with evidence
2. Fix implemented and tested
3. Brief write-up: what was wrong, what changed, how to verify

### Success Criteria
- [ ] 100 rapid requests return zero 500 errors
- [ ] Connection pool stays within limits under load
- [ ] Fix doesn't break other endpoints
- [ ] Root cause documented in commit message

### Failure Protocol
If you can't reproduce the error:
1. Document your reproduction attempts
2. Check if it's environment-specific
3. Add logging to narrow down the issue
4. Report findings — don't guess at fixes

When to Use Which Variation

FAQ

What is a task spec for AI agent delegation?

A task spec is a structured document that defines the contract between an orchestrator and a sub-agent. It specifies the objective, environment context, input files, expected output format, success criteria, constraints, and failure protocols. Good task specs answer five questions: What do you want? Where does it go? What does "done" look like? What does the agent need to know? What should it do if stuck?

How detailed should a task spec be?

Match detail to risk and novelty. High-risk or first-time tasks need comprehensive specs with full environment context, constraints, failure protocols, and verification steps. Routine tasks with proven patterns can use minimal specs — objective, expected output, and key constraints. The environment context block is always worth including. When in doubt, add more context; an agent can ignore extras but can't invent what's missing.

Should I paste file contents into the task spec?

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

What task spec variations exist for different task types?

Four common variations: code tasks (add build/test commands, target files, code style constraints), research tasks (add scope boundaries, source preferences, depth/breadth tradeoffs), content tasks (add style guide, audience, SEO requirements, reference content), and debugging tasks (add symptom description, reproduction steps, what was already tried, relevant logs). Each extends the universal template with domain-specific sections.