One Shot Subagent Prompts

One-Shot Subagent Task Specification Protocol

Overview

When a primary orchestrator agent delegates work to a child subagent (e.g., spawning an autonomous research subagent or browser subagent), providing a vague, underspecified prompt ("Look into why database connections are failing") triggers a high-cost Clarification Ping-Pong Loop.

The child subagent spends 4 to 8 turns asking for workspace paths, exploring irrelevant folders, asking for permission, and returning conversational status updates - burning 20,000+ tokens across both agent transcripts.

The One-Shot Subagent Task Specification Protocol packages Context Scope, Deterministic Actions, Hard Boundaries, and a Return Contract into the initial invocation prompt, enabling the subagent to complete the task autonomously in a single execution trajectory.

Underspecified Delegation vs. One-Shot Specification

┌─────────────────────────────────────────────────────────────┐
│                 Subagent Delegation Trajectory              │
│                                                             │
│  Underspecified Prompt ("Fix auth bugs" - 6 Turns):         │
│  • Subagent Turn 1: "Where are the auth files located?"     │
│  • Parent Turn 2: "In `src/services/auth.ts`"               │
│  • Subagent Turn 3: Explores `routes/`, gets stuck in tests │
│  • Subagent Turn 4: "Should I edit the database schema too?"│
│  ↳ 6 Roundtrips, 22,000 tokens billed across 2 agents       │
│                                                             │
│  One-Shot Task Specification Protocol (1 Trajectory):       │
│  • Parent invokes Subagent with 4-Component Blueprint:      │
│    [Context: `src/auth.ts` | Goal: Add Redis blocklist |    │
│     Boundaries: Zero DB schema edits | Return: JSON diff]   │
│  ↳ Subagent executes directly, returns clean JSON in 1 turn │
│  ↳ 75% Token Reduction ($0.66 $\rightarrow$ $0.16)          │
└─────────────────────────────────────────────────────────────┘

The 4-Component One-Shot Blueprint

Every delegated subagent task prompt MUST contain these 4 explicit sections:

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. 🎯 EXACT CONTEXT & TARGETS: Specific filepaths, line ranges, symbols   │
│ 2. ⚡ DETERMINISTIC ACTION: Exact step-by-step logic to implement        │
│ 3. 🛑 HARD BOUNDARIES: Files forbidden from mutation, max step ceilings   │
│ 4. 📋 FINAL RETURN CONTRACT: Structured JSON schema or diff to return     │
└───────────────────────────────────────────────────────────────────────────┘

Master One-Shot Subagent Task Prompt Template

When calling invoke_subagent or configuring subagent dispatchers:

### 🎯 Context & Target:
- Target File: `src/services/auth.ts` (lines 40-80)
- Related Types: `src/types/auth.d.ts`
- Environment: Redis client available via `import { redis } from '@/lib/redis'`

### ⚡ Deterministic Task:
1. In `verifySessionToken(token: string)`:
  - Extract JWT `jti` claim.
  - Query Redis: `await redis.get(`revoked:${jti}`)`.
  - If key exists, return `null` (unauthorized).
2. Run test verification: `npm test tests/auth.test.ts`.

### 🛑 Hard Execution Boundaries:
- Do NOT modify `prisma/schema.prisma` or database migrations.
- Do NOT install new npm packages.
- Maximum subagent action steps: 6 steps.

### 📋 Final Return Contract:
Return strictly a single JSON object upon completion:
{
  "status": "SUCCESS" | "FAILED",
  "files_modified": ["src/services/auth.ts"],
  "tests_passed": boolean,
  "summary": "1-sentence summary of the fix"
}

Benchmark Comparison

Delegating 25 backend microservice bug-fix tasks to child subagents:

Agent Operational Directive

MANDATORY: When spawning child subagents or browser subagents, orchestrators must never emit 1-line generic prompts. Always provide the full 4-Component Specification (Target, Action, Boundaries, and Return Contract) to ensure zero-clarification autonomous execution.