plan-led-subagents

name	plan-led-subagents
description	Run a coding or research workflow with one plan-agent as the main brain and dynamically spawned subagents for task execution, context relief, debugging, review, and audit. Use when the user wants parallel task work without building a heavy permanent multi-agent org chart, especially for GitHub-based development where coding can happen remotely and local machines are mainly for compile/validation.

Plan-Led Subagents

Use one strong orchestrator as the main brain. Spawn subagents only when the main brain needs parallelism, deep local context, a second opinion, or relief from context pressure.

Core model

Default topology:

• Main brain = plan agent
• Execution = task subagents
• Support = on-demand context/debug/review/audit subagents
• GitHub = source of truth for code state
• Local machine = compile / validation / device work when needed

Do not start with a permanent org chart unless one main brain is genuinely not enough.

Responsibilities

Plan agent (main brain)

Owns:

• goal understanding
• task decomposition
• parallel boundary definition
• subagent spawning and tracking
• progress monitoring
• exception routing
• result merge / summary / next-step decisions

The plan agent should keep only global context:

• current objective
• active tasks and ownership
• hard constraints
• acceptance criteria
• task states
• merge / validation decisions

Task subagents

Use for bounded implementation work:

• feature implementation
• file-local refactor
• test writing
• docs updates
• focused repo exploration

Task subagents should work on clear boundaries and return concise outputs:

• changed files
• what changed
• risks / assumptions
• suggested next actions

Context subagents

Use when context gets too long or too mixed.

Good uses:

• compress a long discussion into a short state snapshot
• extract a module-specific summary
• turn large intermediate results into a compact handoff
• separate local evidence from global planning context

Rule: the main brain keeps the map; context subagents carry local terrain.

Debug subagents

Use only when the main brain cannot quickly resolve failure handling itself.

Good triggers:

• a task subagent is blocked or failing repeatedly
• root cause is unclear
• multiple candidate causes exist
• failure spans several modules or systems

Debug is not a permanent seat by default. It is a troubleshooting mode or a spawned specialist.

Review subagents

Use for independent second-pass checks on implementation quality.

Good uses:

• code review before merge
• regression scan
• verifying task output matches the original scope
• checking for missing tests or edge cases

Audit subagents

Use as a higher-skepticism pass for risky or cross-cutting work.

Typical triggers:

• auth / permissions / security
• data deletion / irreversible actions
• large architectural changes
• multi-subagent merge before validation
• "it works, but I don’t trust it yet"

Audit is a capability, not necessarily a permanent role.

Default workflow

1. Plan agent receives the goal

   • clarify objective
   • identify constraints
   • decide what can run in parallel

2. Plan agent decomposes the work

   • split by module, surface, or responsibility
   • avoid overlapping edits when possible

3. Spawn task subagents

   • one subagent per bounded task
   • keep prompts narrow and explicit

4. Track execution centrally

   • running / blocked / done / needs review
   • the plan agent, not debug, owns progress monitoring

5. Escalate only when needed

   • blocked task -> debug subagent
   • long/noisy context -> context subagent
   • pre-merge skepticism -> review or audit subagent

6. Main brain collects and reconciles outputs

   • resolve conflicts
   • summarize changes
   • decide compile / validation path

7. Code state is synchronized through GitHub

   • use branches / PRs / commits as the collaboration backbone
   • avoid treating local folders on multiple machines as the source of truth

Parallelization rules

Parallelize when tasks are separated by:

• different modules
• different pages/screens
• docs vs code
• implementation vs tests
• implementation vs review

Do not parallelize blindly when tasks touch:

• the same file or method
• the same state machine / lifecycle core
• the same API contract under active change
• the same migration path or schema logic

When overlap risk is high, keep work serial or appoint one subagent as the single writer.

Context management rules

When the main brain feels overloaded, do not keep dragging all raw detail forward.

Instead, offload to a context subagent and retain only:

• decisions
• task status
• active risks
• next actions
• merge conditions

Good signs that a context subagent is needed:

• repeated rereading of the same evidence
• many active tasks with mixed detail
• large logs / traces / diffs flooding the main thread
• topic switching with a need to resume later
• plan quality degrading as history grows

Machine / workflow alignment

For the user’s preferred workflow:

• remote/cloud/other machine can do planning and code-writing
• local machine is especially valuable for compile, emulator, device, and final verification
• GitHub should mediate code synchronization across machines

This skill pairs naturally with:

• one main interactive session as the plan brain
• subagents for bounded work
• local compile / validation only when needed

Minimal role set (recommended V1)

Start with:

• plan agent (main brain)
• task subagents (many)
• context/debug/review/audit as on-demand subagents

Do not force permanent standalone debug or audit roles unless load and complexity justify them.

Decision heuristics

If a task is small and clear

• main brain handles it directly or spawns one task subagent

If a task is large but separable

• spawn multiple task subagents in parallel

If a task fails strangely

• let the main brain triage first
• spawn debug subagent only if needed

If review confidence is low

• spawn review subagent

If risk is high or merge is scary

• spawn audit subagent

If history is getting bloated

• spawn context subagent to compress and hand back only key state

Anti-patterns

Avoid these mistakes:

• creating a permanent org chart before the main brain hits real limits
• letting multiple subagents edit the same hotspot without coordination
• making debug own progress tracking
• making the main brain carry all raw logs, traces, and local evidence forever
• treating multiple machines’ local working copies as the source of truth instead of GitHub

Output contract for subagents

Ask subagents to return compactly:

• objective handled
• files touched / investigated
• result
• unresolved issues
• suggested next step

Prefer compact summaries over raw narrative dumps.

V1 principle

Agent-era default:

one main brain, many temporary branches of thought.

Use organization only after you prove one strong orchestrator plus dynamic subagents is not enough.

Source

Derived from a 2026-03-23 workflow design discussion in this workspace about:

• personal development clusters
• remote coding + local compile validation
• plan/debug/task/audit roles
• subagent-first orchestration