Subagent First

Subagent-First Workflow

Intent Gate: Already Running

Intent Gate is now auto-injected via SOUL.md (slot #1 in system prompt).

You do NOT need to re-run intent classification here — SOUL.md already enforced:

• Step 0: Verbalize Intent
• Step 1: Classify Request Type
• Step 1.5: Turn-Local Intent Reset
• Step 2: Check for Ambiguity
• Step 2.5: Context-Completion Gate
• Step 3: Validate Before Acting (Delegation Check)

This skill applies AFTER Intent Gate decides: DELEGATE.

When Intent Gate's Step 3 returns "delegate", use this skill's execution protocols.

Spend Sanity Check Before Dispatch

Even when SOUL.md has already decided a task is non-trivial enough to delegate, do one more short check before spawning children:

• What concrete value does this create for the core customer?
• What is the lightest viable dispatch shape?
• Is a heavier wave plan buying real marginal value, or just process?
• Would the user actually miss any of these steps if they disappeared?

If the answers are weak, reframe or shrink the dispatch instead of sending more children.

Core Principle

Default to subagents. Only execute directly when the cost of delegation exceeds the benefit.

The Intent Gate Delegation Check already made the decision. Now execute it properly.

Quick Reference: When Direct Execution is Acceptable

Intent Gate already filtered these. Direct execution is acceptable ONLY when Intent Gate classified as:

• Trivial: 1-2 tool calls, zero branching, predictable output
• Explicit: Specific file/line, clear command, single action

All other classifications → use subagent (per Intent Gate Step 3).

When Intent Gate Says DELEGATE (Execution Protocols)

Intent Gate's Step 3 (Delegation Check) returns DELEGATE for:

• Exploratory tasks
• Open-ended tasks
• Multi-file changes
• Research/Synthesis
• Investigation/Diagnosis
• Parallelizable work
• Unknown scope tasks

When you receive DELEGATE decision from Intent Gate, follow the phases below.

Dispatch Disclosure (User-Facing, Concise)

For coding tasks delegated to subagents, tell the user before dispatch in 1-3 short bullets:

• Backend: e.g. OpenCode ACP (opencode acp, non-pure mode)
• Agent choice: e.g. Sisyphus - Ultraworker for general coding, Hephaestus - Deep Agent for deeper implementation
• Dispatch shape: e.g. single implementer, Wave 1 parallel investigation x2, controller verifies after child completes

Default disclosure pattern:

Subagent plan:
- Backend: OpenCode ACP (opencode acp, non-pure mode)
- Agent: Sisyphus - Ultraworker
- Dispatch: 1 coding subagent + controller verification

If using more than one child, disclose wave shape briefly:

Subagent plan:
- Backend: OpenCode ACP (opencode acp, non-pure OMO)
- Agents: Wave 1 Sisyphus x2, Wave 2 Hephaestus x1
- Dispatch: parallel investigation first, then single implementation, then controller verification

Do this concisely; do NOT dump the full 6-section prompt to the user unless asked.

Phase 0: Wisdom Retrieval

Before partitioning tasks, query prior learnings.

1. Identify task type: {domain}-{action-type}
   Examples: auth-test-fixing, api-refactoring, db-debugging

2. Query hindsight_recall:
   prior_wisdom = hindsight_recall(query="{task_type}")

3. If wisdom exists → inject into Phase 2 CONTEXT section
   If no wisdom → proceed without prior context

Phase 1: Task Partitioning & Wave Planning

Map dependencies and plan wave dispatch.

Step 1.1: Decompose Task

Can this task be decomposed into independent subtasks?
├── YES → What are the dependencies between subtasks?
│         ├── No dependencies → Wave 1 (parallel)
│         ├── Some dependencies → Wave 1 + Wave 2 pattern
│         └── Heavy dependencies → Sequential execution
│
└── NO → Single subagent task, skip wave planning

Step 1.2: Dependency Analysis

Step 1.3: Wave Plan Output

Wave Plan:
├── Wave 1: [Task A, Task B] (parallel, max 3)
├── Wave 2: [Task C] (depends on Wave 1)
├── Wave 3: [Task D] (depends on Wave 2)
│
└── Total waves: N
└── Estimated iterations per subagent: 15-50

Step 1.4: User Confirmation Checkpoint ⚠️

Before dispatching 3+ waves or 5+ subagents, MUST confirm with user:

Wave Plan Summary:
- Wave 1: 3 subagents (auth, api, db investigation)
- Wave 2: 1 subagent (integration design)
- Wave 3: 1 subagent (implementation)
- Total: 5 subagents, ~150 iterations

Proceed with dispatch? [YES/NO]

If user says NO → Adjust plan, reduce scope, or cancel.

This checkpoint prevents:

• Token cost explosion from runaway parallel dispatch
• User surprise from unexpected agent activity
• Premature execution before plan validation

Phase 2: Subagent Dispatch

Construct 6-Section context and dispatch.

Step 2.1: Build 6-Section Context

Use the template for each subagent:

context = """
TASK:
[One clear sentence]

OUTCOME:
- [Deliverable 1]
- [Deliverable 2]
- [Verification criteria]

TOOLS:
- [Toolset]: [specific instructions]

MUST:
- [Required action]
- [Required verification]

MUST NOT:
- [Prohibition 1] (catch AI slop)
- [Prohibition 2] (prevent scope creep)

CONTEXT:
[Prior wisdom from Phase 0]
[Project conventions]
[Related files/code snippets]
"""

Step 2.2: Dispatch Waves

# Wave 1
wave1_results = delegate_task(
    tasks=[
        {"goal": "...", "context": "...", "toolsets": [...], "max_iterations": 30},
        {"goal": "...", "context": "...", "toolsets": [...], "max_iterations": 30},
    ]
)

# Wave 2 (if exists)
wave2_results = delegate_task(
    tasks=[
        {"goal": "...", "context": f"...{wave1_results[0]['summary']}...", ...},
    ]
)

Phase 3: Verification

Controller checks subagent output, never trust blindly.

Step 3.1: Output Validation Checklist

□ Does summary match OUTCOME criteria?
□ Were MUST requirements fulfilled?
□ Were MUST NOT prohibitions respected?
□ If tests specified → Did tests pass?
□ If files specified → Check actual changes with read_file/diff
□ Any unexpected changes? → Investigate before accepting

Step 3.2: Failure Handling

If verification fails:
├── Minor issue → Fix in controller (patch/terminal)
├── Major issue → Re-dispatch with corrected context
├── Subagent ran off → Add MUST NOT constraints, retry
│
└── DO NOT accept subagent summary without checking

Phase 4: Wisdom Capture

Extract learnings from successful completion.

Step 4.1: Wisdom Extraction Checklist

Run after EVERY successful subagent completion:

□ Pattern discovered? → Extract to Pattern field
□ Gotcha identified? → Extract to Gotcha field
□ Convention learned? → Extract to Convention field
□ Tool combo worked? → Extract to Tool Combo field
□ Failure overcome? → Extract to Failure Recovery field
□ Key insight? → Extract to Key Insight field

□ Task failed? → DO NOT extract (only from successes)
□ Trivial task? → DO NOT extract (no learning value)

Step 4.2: Store Wisdom

hindsight_retain(
    content="[WISDOM ENTRY]\nTask Type: {type}\nPattern: {...}\n...",
    context="{task_type}"
)

Step 4.3: Completion Notification ⚠️

After wisdom capture, notify user of completion:

Task Completed:
- Subagent: {role}
- Outcome: {summary of deliverables}
- Verification: {passed checks}
- Wisdom: {key insight captured (if applicable)}

Result: {SUCCESS/PARTIAL/FAILED}

If PARTIAL or FAILED → Offer next steps instead of marking done.

This checkpoint prevents:

• User not knowing task status
• Premature closure without explicit confirmation
• Lost context for follow-up actions

6-Section Delegation Prompt (From OMO Research)

Every subagent context MUST follow this structure. This is the single most important factor in preventing subagent drift.

The 6 Sections

TASK:
[One-sentence task description]

OUTCOME:
[What success looks like - specific deliverables]

TOOLS:
[Available toolsets and any tool-specific instructions]

MUST:
[Explicit requirements - things that MUST be done]

MUST NOT:
[Explicit prohibitions - things that MUST NOT be done]

CONTEXT:
[Background information, prior findings, project conventions]

Why This Structure Works

1. TASK - Clear, singular focus prevents scope creep
2. OUTCOME - Defines completion criteria upfront
3. TOOLS - Prevents tool hallucination and wrong toolset selection
4. MUST - Forces positive constraints that can't be ignored
5. MUST NOT - Explicit prohibitions catch AI slop patterns (from OMO's "Anti-AI-Slop" design)
6. CONTEXT - Rich background without drowning in noise

Example: Good vs Bad

BAD - Vague context causes drift:

delegate_task(
    goal="Fix the auth tests",
    context="Tests are failing, figure it out"
)
# Result: Subagent explores entire codebase, changes unrelated files, breaks other tests

GOOD - 6-Section keeps subagent on track:

delegate_task(
    goal="Fix failing auth tests",
    context="""
TASK:
Make test_login_failure in tests/auth/test_login.py pass.

OUTCOME:
- Test passes: pytest tests/auth/test_login.py::test_login_failure succeeds
- Report: exact fix made with line numbers
- No other tests broken

TOOLS:
- terminal (pytest, git)
- file (read, patch)

MUST:
- Fix the password comparison logic in src/auth/login.py
- Run pytest after changes to verify
- Report exact changes made

MUST NOT:
- Change test assertions
- Add new dependencies
- Modify any files outside src/auth/login.py
- Skip running tests before reporting done

CONTEXT:
- test_login_failure fails with AssertionError: "Invalid credentials" expected but got "Login successful"
- Password is hashed with bcrypt, comparison should use checkpw()
- Project uses pytest, run: pytest tests/auth/test_login.py -v
- Related file: src/auth/login.py line 47-52
""",
    toolsets=["terminal", "file"],
    max_iterations=25
)

MUST NOT Anti-Patterns (From OMO)

Common AI slop patterns to explicitly prohibit:

• "Do NOT add unnecessary logging/print statements"
• "Do NOT add comments explaining obvious code"
• "Do NOT refactor unrelated code while fixing the issue"
• "Do NOT add TODOs or placeholders"
• "Do NOT create new abstractions unless explicitly requested"
• "Do NOT change variable names for 'clarity'"
• "Do NOT add defensive null checks that weren't requested"

Wisdom Format Reference

Standard format for hindsight_retain (details in Phase 4):

hindsight_retain(
    content="[WISDOM ENTRY]\nTask Type: {domain}-{action}\nPattern: {...}\nGotcha: {...}\nConvention: {...}\nTool Combo: {...}\nFailure Recovery: {...}\nKey Insight: {...}",
    context="{task_type}"
)

Query matching: Use task type as keyword (e.g., hindsight_recall(query="auth-test-fixing")).

Wave Dispatch Reference

Wave dispatch pattern (details in Phase 1-2):

Wave 1: [Task A, Task B, Task C] → parallel, max 3 concurrent
Wave 2: [Task D] → depends on Wave 1 results
Wave 3: [Task E] → depends on Wave 2 results

Dependency types requiring sequential execution:

• Same file edits
• Output → input data flow
• Decision/validation dependency

Max concurrent limit: Hermes config default = 3.

Partitioning for Parallel Execution

Decision Logic

Can tasks run independently?
├── YES → Can they touch the same files?
│   ├── NO → Dispatch in parallel (Wave 1)
│   └── YES → Can edits be cleanly separated?
│       ├── YES → Parallel with explicit file boundaries in MUST NOT
│       └── NO → Sequential execution
└── NO → Sequential execution required

Good Parallel Partitions

• Multiple independent investigations (different subsystems)
• Separate test files with isolated failures
• Read-only research tasks on different topics
• Independent implementation tasks with non-overlapping files

Bad Parallel Partitions

• Multiple implementers editing the same file
• Tasks where one's output is another's input
• Investigations that might discover shared root causes
• Any task pair where you can't predict the interaction

Complete Context Packaging Template

Use this template for every delegate_task call:

delegate_task(
    goal="[One-sentence task from TASK section]",
    
    context="""
TASK:
[One clear sentence describing what to accomplish]

OUTCOME:
- [Specific deliverable 1]
- [Specific deliverable 2]
- [Verification criteria]

TOOLS:
- [Toolset 1]: [any specific instructions]
- [Toolset 2]: [any specific instructions]

MUST:
- [Required action 1]
- [Required action 2]
- [Required verification step]

MUST NOT:
- [Prohibition 1 - catch AI slop]
- [Prohibition 2 - prevent scope creep]
- [Prohibition 3 - maintain invariants]

CONTEXT:
[Prior findings from controller]
[Project conventions]
[Related files/code snippets]
[Prior wisdom from hindsight_recall if applicable]
""",
    
    toolsets=["terminal", "file"],
    max_iterations=30  # Adjust based on complexity
)

Anti-Patterns

Anti-Pattern 1: Missing MUST NOT

# BAD - No prohibitions, subagent adds "helpful" extras
delegate_task(
    goal="Fix login bug",
    context="TASK: Fix the login validation bug."
)
# Result: Subagent fixes bug AND refactors code AND adds logging AND breaks tests

# GOOD - Explicit MUST NOT catches AI slop
delegate_task(
    goal="Fix login bug",
    context="""
TASK: Fix password validation in src/auth/login.py.

MUST NOT:
- Add logging statements
- Refactor surrounding code
- Change function signatures
- Modify tests
"""
)

Anti-Pattern 2: Parallel Editors

# BAD - Two implementers editing the same file
delegate_task(tasks=[
    {"goal": "Add login to app.py", ...},
    {"goal": "Add logout to app.py", ...}  # Race condition!
])

# GOOD - Sequential or parallel with file boundaries
# Option 1: Sequential (use Wave pattern)
delegate_task(goal="Add login to app.py", ...)
# Wait, then:
delegate_task(goal="Add logout to app.py", ...)

# Option 2: Parallel with explicit file separation in MUST NOT
delegate_task(tasks=[
    {
        "goal": "Add login to auth/login.py",
        "context": "... MUST NOT: Edit any file outside auth/login.py"
    },
    {
        "goal": "Add logout to auth/logout.py",
        "context": "... MUST NOT: Edit any file outside auth/logout.py"
    }
])

Anti-Pattern 3: No Wisdom Capture

# BAD - Learnings lost after subagent completes
result = delegate_task(...)
# Move on without capturing what worked

# Next similar task → same mistakes, same rediscovery

# GOOD - Capture wisdom for reuse
result = delegate_task(...)

# Extract and store
hindsight_retain(
    content=f"Pattern that worked: {result['key_insight']}",
    context="task-category"
)

# Future task benefits from prior learning

Anti-Pattern 4: Skipping Verification

# BAD - Trust subagent summary without checking
result = delegate_task(...)
user.tell("Done!")  # No verification

# GOOD - Controller verifies in MUST section
delegate_task(
    context="""
MUST:
- Run pytest tests/auth/ after changes
- Include test output in summary
"""
)
result = delegate_task(...)
# Check summary includes test results, not just "I fixed it"

Role Selection Guide

Backend Choice

The workflow discipline stays the same regardless of backend:

Hermes native children (default):

delegate_task(goal="...", context="...", toolsets=["terminal", "file"])

OpenCode with OMO (preferred for code-heavy work):

delegate_task(
    goal="...",
    context="...",
    acp_command="opencode",
    acp_args=["acp"],
    toolsets=["terminal", "file"]
)

Use the ACP entrypoint that is valid in your own environment. A local wrapper is fine, but keep it outside the reusable skill unless it is part of your public setup instructions.

**Model override for specialized tasks**:
```python
delegate_task(
    goal="...",
    context="...",
    model={"model": "anthropic/claude-opus-4"}  # Heavy reasoning
)

Integration with Other Skills

• subagent-driven-development: Use for executing pre-written implementation plans task-by-task
• subagent-collaboration-workflow: Use for complex multi-role workflows with planner/investigator/implementer/reviewer separation
• verification-before-completion: Always use before claiming work is done

Quick Reference Card

┌─────────────────────────────────────────────────────────────────┐
│               INTENT GATE → SUBAGENT EXECUTION                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  SOUL.md INTENT GATE (auto-injected, every message):           │
│  ├── Step 0: Verbalize Intent                                   │
│  ├── Step 1: Classify (Trivial/Explicit/Exploratory/etc.)       │
│  ├── Step 1.5: Turn-Local Reset                                 │
│  ├── Step 2: Ambiguity Check                                    │
│  ├── Step 2.5: Context-Completion Gate                          │
│  └── Step 3: Delegation Check → DELEGATE or DIRECT              │
│                                                                 │
│  IF DELEGATE (this skill applies):                              │
│  ├── 6-Section Prompt: TASK/OUTCOME/TOOLS/MUST/MUST NOT/CONTEXT │
│  ├── Wave Parallel: Map deps → Wave 1 → Wave 2 → ...            │
│  ├── Wisdom: Extract → hindsight_retain                         │
│  └── Verify: Controller checks subagent output                  │
│                                                                 │
│  IF DIRECT (Intent Gate decided trivial/explicit):              │
│  └── Execute in controller session                              │
│                                                                 │
│  CONTEXT: Always use 6-Section structure                        │
│  MUST NOT: Catch AI slop (no extra logging, no refactors, etc.) │
│  WISDOM: hindsight_recall before, hindsight_retain after        │
│  VERIFY: Never trust subagent summaries blindly                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Remember

1. Intent Gate runs first - SOUL.md auto-injects, you inherit its decision
2. DELEGATE → use this skill - Apply 6-Section, Wave Parallel, Wisdom protocols
3. DIRECT → skip this skill - Intent Gate already decided trivial/explicit
4. Always use 6-Section - TASK/OUTCOME/TOOLS/MUST/MUST NOT/CONTEXT
5. MUST NOT catches AI slop - Explicit prohibitions prevent scope creep
6. Capture wisdom - hindsight_retain after success, hindsight_recall before new tasks
7. Wave parallel - Map dependencies, dispatch in waves, respect config limits
8. Verify in controller - Never trust subagent summaries blindly