lingyu9495-source/subagent-first

Subagent First · Primary Agent Stays Out

The primary agent's attention belongs to the user, not to the task. Any task expected to take many rounds must always be delegated to a sub-agent to work in the background; the primary agent only handles decomposition, delegation, verification, and consolidation, always retaining the ability to respond to the user.

Many agents feel awkward to use. The root cause is not that the model isn't smart enough, but that the primary agent is blocked by heavy work: the user sends one message, and the primary agent dives into twenty rounds of tool calls, unable to respond or change course in the middle. The user can only wait. By the time it finally surfaces, the requirements may have changed.

This skill provides a set of operational discipline—turning "when to delegate, how to delegate, and how to verify" into determinable rules rather than gut feeling. The discipline is platform-agnostic: it applies to any AI Agent that supports sub-agents / background tasks (Claude Code, Codex, Cursor, WorkBuddy, Hermes, and similar tools). The differences are only in tool names—mapping is provided in the "Tool Name Reference Table" section of this document.

Runtime reality differences for specific platforms: Hermes field names, concurrency limits, background semantics, and cost accounting are documented in references/hermes-runtime-reality.md (example implementation; other platforms can ignore it). The main text only covers the discipline, independent of that page.

---

Trigger Conditions

When any of the following situations occur, you should apply this skill (rather than doing it yourself out of convenience):

1. The task is expected to exceed 2–3 rounds of tool calls: e.g., "read 8 files and summarize" or "run one round of search and then organize."
2. Multiple independent units must be processed at once: multiple files, directories, URLs, data sets, or candidate solutions.
3. Long research / long search: requires repeated retrieval, fetching, and comparison, taking minutes.
4. Batch processing: applying the same set of operations to a batch of inputs (cleaning, transforming, line-by-line checking, line-by-line generation).
5. The user explicitly asks for parallelism or to "do several things at once."
6. The primary agent is in the middle of a conversation with the user: the user may ask follow-ups, change requirements, or interject new tasks at any time.
7. Sub-tasks have no dependencies on each other and can start simultaneously: typical example is "proofread three documents separately, then merge conclusions."
8. The user wants to continue chatting about other things while heavy work runs in the background (this is the primary benefit scenario for this skill).

Reverse trigger condition: if a task can be done in one round of tool calls, and the user won't talk to you again after sending that message—then do it yourself. Forcing delegation to a sub-agent will only make it slower. Criteria are in the decision tree in the next section.

---

Core Principles

1. The primary agent does not do heavy work. The primary agent only does four things: decomposition → delegation → consolidation → conversation with the user. It must maintain a "ready to respond at any time" state.
2. Heavy work must be delegated to sub-agents (mandatory). If the trigger conditions above are met, delegate. "I think I'm fast and I'll just do it" is not allowed. The judgment is based on task attributes, not the primary agent's confidence.
3. Self-report is not fact. A sub-agent claiming "done" is just its own statement; any output that has not been verified is considered incomplete (see "Verification Checklist").
4. Context must be self-contained. The sub-agent cannot see your conversation history with the user. The background in your head doesn't reach it at all. If the delegation ticket is incomplete, it will definitely go off-track—it's not that it's dumb, it's that you didn't provide.
5. Parallelism has boundaries. Only parallelize tasks with no dependencies; tasks with sequential dependencies must be serialized, or the upstream output must be fed to the downstream.
6. Tasks requiring user approval are not delegated. Tasks needing user confirmation, carrying irreversible consequences, or requiring immediate oversight stay with the primary agent.
7. Cross-session long tasks use a different mechanism. Tasks that need to outlive the current session (continuous monitoring, scheduled triggers, resident processes) use your platform's scheduling / resident mechanism (cron jobs, scheduled tasks, resident background processes), not sub-agents—a sub-agent's lifecycle is tied to a single delegation.
8. Failure must degrade, not fabricate. If a sub-agent fails, times out, or produces substandard output: degrade by doing it yourself, or re-delegate via a different route. Never write "got the result" when you didn't.

These principles correspond to the well-known fork-join / fan-out-fan-in engineering paradigm: fork tasks to multiple execution units, then merge results (Java's ForkJoinPool, and the MapReduce proposed by Dean and Ghemawat at OSDI 2004 are concrete implementations of this idea). This skill doesn't invent new concepts; it just translates them into actionable operational discipline for the agent scenario.

---

Decision Tree: What is Heavy, What to Do Yourself

Answer the following questions in order. The first branch answered "yes" is your conclusion.

Question 1: Can this task be done in one round of tool calls?

Judgment Item	Criterion
Number of tool calls	You can count them, and ≤ 1 round
Need to read multiple files	No (0–1 file)
Loops involved	No (no "for each…")
Estimated time	Seconds

All four satisfied → Do it yourself. Any one unsatisfied → Go to Question 2.

Question 2: Does this task need user approval?

• User needs to choose among several options → Do it yourself (or only do information gathering first, then present options to the user).
• Involves irreversible operations (delete data, publish publicly, pay, send messages to third parties) and needs immediate oversight → Do it yourself.
• Only "needs user to know," but doesn't require a decision in the process → Can be delegated, but the summary must clarify the situation.

Question 3: Does this task need to outlive the current session?

• Yes (scheduled triggers, continuous monitoring, resident services) → Use the platform's scheduling / resident mechanism (cron jobs, scheduled tasks, background processes), not sub-agents.
• No, it can be completed within this session → Go to Question 4.

Question 4: Can it be split into independent blocks?

• Yes → Delegate multiple sub-agents in parallel, each handling its own file / directory / URL / dataset, then the primary agent merges.
• No, but there is a clear sequence → Delegate serially, or delegate to a single sub-agent to run the whole chain (still saves you the trouble).
• Cannot be split, and not long → Go back to Question 1 to double-check; likely do it yourself.

Quick Quantitative Reference

Nature of Work	Typical Duration	Action
Look up a value, read a section of a file	Seconds	Do it yourself
Edit one piece of text, run one command	Seconds	Do it yourself
Read 3 files and summarize	1–2 minutes	Either is fine; delegate if user is waiting
Read 8 files, summarize each	Several minutes	Delegate
Multi-source search + cross-reference	Several to tens of minutes	Delegate (can be split and parallelized)
Batch process N inputs (N ≥ 5)	Grows with N	Delegate (slice and parallelize)
User needs to choose from options	Varies	Do it yourself (gather + present options)
Runs once daily	Cross-session	Scheduled task (not sub-agent)

---

Five-Step Workflow

Step 1: Decomposition

First, cut the work into clearly bounded units. Each unit must independently answer three questions:

• What is the input: specific file paths, directories, URL lists, dataset names, parameters.
• What is the output: specific filenames, formats, paths.
• How do we know it's done: a determinable criterion, not "just make it work."

When splitting, adhere to two rules:

• No file write collisions: Two sub-agents must never write to the same file. Either each writes its own file, then the primary agent merges, or do it serially.
• Dependencies must be explicit: If A's output feeds into B, they cannot be parallelized—must be serial, or delegate a single sub-agent to do both A and B.

Completion Criteria (check each)

• Each unit has its input specified (with specific paths / lists)
• Each unit has its output specified (filename + format + storage location)
• Each unit has a determinable completion criterion
• No two units write to the same file
• All dependencies are marked (which must be serial)

Step 2: Delegation

Use your platform's sub-agent / background task tool to delegate each unit (for Hermes, it's delegate_task; for other platforms, map via the "Tool Name Reference Table"). Write each ticket according to the "Four Elements" (see next section). Key points:

• One sub-agent only picks up one clearly bounded task; don't stuff three unrelated things into one ticket.
• Write complete background in the ticket—the sub-agent cannot see your conversation with the user.
• Clearly tell it where to place the output and what to report back (file path? line count? command output?).
• Clearly ask it to only report verifiable things: what commands it ran, what output it got; if it couldn't do something, just say so.
• If the platform supports structured reporting / output validation (e.g., validating the sub-agent's final reply against a JSON Schema)—use structured format rather than free text.

Completion Criteria

• Each ticket has all four elements (goal / context / output structure / verification method)
• Each ticket specifies the output path
• Each ticket requires reporting verifiable evidence (command + real output)
• No ambiguous references like "you know what I mean" or "same as before"

Step 3: Parallel Scheduling

• Parallelize independent units: Delegate all units with no dependencies at once, don't queue them one by one.
• Serialize dependent units: Wait for upstream verification to pass, then feed its output as context to the downstream ticket.
• Set a concurrency limit: Too many at once will compete for resources and increase your workload during consolidation. Three to five at a time is a usual comfortable range; for more, consider batching (consequences of exceeding the limit vary by platform—see "Tool Name Reference Table" and platform reality page).
• Return to the user immediately after delegation: Don't stand still waiting for sub-agents. This is exactly the purpose of this discipline—while the user is waiting for you, you should be responsive.
• Don't poll, don't wait idle: The delegation call should return immediately, with results delivered by the platform; the primary agent should be able to handle new user messages while waiting. If your platform blocks by default, put the delegation call into background / asynchronous mode.
• Give the user a control point: If the platform supports viewing running sub-agents, adding corrections to a specific sub-agent, or early termination with partial results, use it; if not, fall back to "include corrections in the next batch of tickets."

Completion Criteria

• Independent units are already sent out simultaneously (not queued one by one)
• Dependent units are serialized in order, and downstream units have received upstream outputs
• Concurrency is within a manageable range (not over a dozen at once)
• After delegation, the primary agent is not blocked and can still respond to the user

Step 4: Verification

This is the easiest step to skip, and the most critical step not to skip. A sub-agent's "done" is a claim to be verified, not a conclusion.

Verify in order (see "Verification Checklist" for details):

1. Does the output exist?: Is the file really there? Is the path correct? Read the actual content.
2. Is the output compliant?: Does the format, fields, line count, and scope meet the ticket requirements?
3. Is the conclusion supported by evidence?: For key numbers/claims, is there corresponding command output or source?
4. Original text spot-check: Randomly pick 1–2 data points and verify against the primary source.

If any item fails → follow the failure handling in Step 5.

Completion Criteria

• Each sub-agent's output is actually read back using the platform's file-read / execution tool (for Hermes: read_file / terminal)
• Format and fields meet ticket requirements
• Key conclusions have traceable evidence
• At least one spot-check against the original text matches the sub-agent's claim
• Failed / unqualified outputs are clearly marked and not mixed into the final result

Step 5: Consolidation

When summarizing for the user, three things must be done:

• Attribute sources: which parts were done by sub-agents and which by you. The user has the right to know.
• State status: which parts are verified, which are unverified, and which failed. Don't gloss over with "probably" or "should be."
• Provide next steps: explicitly present items that require user approval.

Failure handling (in priority order):

1. Degrade to do it yourself—if the work is actually small, just do it yourself.
2. Re-delegate via a different route—include the failure reason in the new ticket and try a different approach.
3. Split and re-delegate—the ticket was too large and caused deviation; cut it smaller and re-delegate.
4. Report honestly—if it can't be done, explain the blockage and eliminated paths. Fabricating results is not allowed.

Completion Criteria

• The summary attributes the source of each part (sub-agent / primary agent)
• The summary states the verification status of each part
• Failed work has been handled (done yourself / re-delegated / reported honestly), not hidden
• Items requiring user decision are listed separately
• No unverified statement is presented as fact

---

Four Elements of Delegation

Every delegation ticket must contain these four elements. Missing any one significantly increases the risk of accidents.

1. Goal — What to Do

State the goal in one sentence, starting with a verb, outcome-oriented.

• Good: Merge 3 CSV files into a single deduplicated combined.csv, preserving original column order
• Bad: Process these files

2. Context — Why and Based on What (Must Be Self-Contained)

This is the easiest of the four elements to mess up. The reason is simple:

The sub-agent cannot see your conversation history with the user. It only knows what you wrote in the ticket. The background in your head—the user's preferences, previous pitfalls, why a certain option can't be used, data definitions—it receives none of it.

So context must explicitly include:

• Task background: What goal this task serves, what the user cares about.
• Hard constraints: Definitions, formats, naming rules, prohibited items that must be followed.
• Input list: Specific file paths / directories / URLs / datasets—not "those files."
• Known pitfalls: What didn't work before, where the traps are, easily misunderstood parts.
• Environment information: Working directory, available tools, whether dependencies are installed.

Self-check method: Could a colleague with no prior context do this task with only this ticket? If yes, it's self-contained.

3. Output Schema — What the Output Looks Like

Specify the output structure upfront to avoid needing to reprocess it when it comes back.

• For files: path + filename + format (markdown / json / csv) + required fields or sections.
• For reports: require a structured return (conclusions / evidence / sources / unresolved items), not a paragraph of prose.
• Machine-readable first: if you can use json, don't use free text—saves you the effort of re-parsing.
• If the platform supports output validation (validate sub-agent reply against schema), enable it; if not, repeat the structure in the ticket body and require "report according to this structure."

4. Verification Method — How to Prove It's Done

Tell it in advance how you will verify; then it will work accordingly. Finding out later that there's no evidence means rework.

• Require actual commands run and their output (not "I checked it").
• Require the output path to be directly readable.
• Require explicit listing of unfinished / questionable parts—voluntary disclosure is better than being caught out.

Four Elements Quick Reference

Element	One-Liner	Common Defect
Goal	What to do, outcome-oriented	Too vague: "sort out the materials"
Context	Background + constraints + input list + known pitfalls	Only writes goal, no context; sub-agent goes off on its own
Output Schema	Output path, format, fields	No path specified, output scattered and unfindable
Verification Method	Which commands/standards to use	No criterion; passes based on "feels okay"

---

Verification Checklist

For every sub-agent output, go through each item. If any item is "no," it's not complete.

A. Existence

• The output file actually exists at the path specified in the ticket (check with the platform's file-read / execution tool, not just by looking at the filename)
• The file is non-empty; the content is not a placeholder / template remnant / obviously truncated
• If it's code or a script: it can actually run (not just "looks correct")

B. Compliance

• Format, fields, and naming meet the ticket requirements
• Quantity matches (if 10 items were requested, there are exactly 10, not "about 8")
• No overreach: didn't modify files that shouldn't be changed, didn't write to locations outside the ticket
• No overwriting between parallel tasks (check file modification times / content integrity)

C. Authenticity

• Commands the sub-agent claims to have run have corresponding real output
• Key conclusions can be traced to specific sources (files, URLs, command results)
• Randomly pick 1–2 data points, verify against the primary source, and the conclusions match
• No numbers or claims that "look reasonable but have no source"

D. Completeness

• Every item requested in the ticket has been submitted
• Unfinished / questionable parts are explicitly listed, not hidden
• Failed items are clearly explained (where it went wrong, what was tried)

E. Final Pre-Summary Check

• In my response to the user, I've attributed sources and verification status
• I have not written a sub-agent's "self-reported success" as "completed" into the conclusion

---

Common