From taches-principled
Orchestrate general-purpose parallel subagents for investigation, self-review, and feedback loops. Use for multi-perspective research, review, and delegated exploration — NOT for executing structured task plans (use a plan-execution workflow instead).
How this skill is triggered — by the user, by Claude, or both
Slash command
/taches-principled:subagent-orchestrationWhen to use
Do NOT use for simple single-step tasks or when Claude is already acting as orchestrator without explicit delegation request.
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Orchestrate multiple subagents in parallel, self-review work, iterate with feedback loops, and manage background workers. The orchestrator owns all cognition; subagents own only execution.
Orchestrate multiple subagents in parallel, self-review work, iterate with feedback loops, and manage background workers. The orchestrator owns all cognition; subagents own only execution.
| Situation | Action |
|---|---|
| Single-step, <5 min inline | Do it yourself |
| Multi-file, independent streams | Spawn parallel subagents |
| Sequential dependencies | Pipeline (research → implement) |
| Unknown root cause | Contest pattern |
| Need verification before commit | Maker-checker loop |
| Long-running external process | Monitor or ScheduleWakeup |
Four rules that govern every delegation decision:
When spawning subagents for investigation/research/exploration:
.principled/scratch/{topic}.md[Read, Write, Grep, Glob, Bash]Why: The telephone game degrades quality by ~50% when orchestrators synthesize without source access. Direct scratchpad access eliminates paraphrase drift.
Before spawning any subagent, validate:
.principled/scratch/{topic}.md)Match the agent type to the task complexity:
| Type | Model | Context | Cost | Use when |
|---|---|---|---|---|
Bash | — | Shell only | Lowest | Git ops, build commands, script execution |
Explore | Haiku | Fresh, read-only | Lowest | Codebase discovery, targeted lookups |
Plan | Sonnet | Fresh, read-only | Low | Architecture analysis, implementation planning |
general-purpose | Inherit | Fresh, configurable | Medium | Custom workflows, complex orchestration |
Rule: Never spawn a subagent for a task that fits in a single context window and would take less than 5 minutes inline.
Structure every spawn prompt with RACE — see the RACE framework reference for full details.
## Role
[What this agent is and what expertise it brings]
## Action
[Concrete, scoped task — imperative form, one clear objective]
## Context
[What the orchestrator has done; what this agent should do next; file ownership boundaries]
## Expectation
[Output format/schema; success criteria; coverage rule]
## Rollback
[One-command revert — what to undo if this fails]
## Failure Signal
[Required JSON schema — see below]
## Approach
[Numbered step-by-step methodology]
Key principles:
Every subagent must return structured JSON on completion:
{"status": "failed" | "success", "reason": "...", "completed_portion": "...", "retry_possible": true/false}
Do not guess or produce partial output without flagging it.
When using grep in pipes for Monitor, ALWAYS use --line-buffered:
tail -f app.log | grep --line-buffered "ERROR"
Why: Unix pipe buffering delays output by minutes. --line-buffered forces grep to flush each match immediately. Without it, your monitor may never see events that arrived during the delay window.
See the orchestration patterns reference for full patterns and use-case examples.
| Pattern | When to use |
|---|---|
| Horizontal Split | Split research by dimension (security, perf, style) |
| Vertical Slice | Split implementation by layer (frontend, backend, tests) |
| Pipeline | Sequential dependencies (research then implement) |
| Contest | Unknown root cause — test competing hypotheses |
| Aggregator Fan-out/Fan-in | N parallel workers → 1 aggregator synthesizes |
Parallel Code Review — Horizontal split by concern (security, perf, style)
Lead → @security "Audit auth/ for vulnerabilities"
→ @perf "Analyze db queries for N+1"
→ @style "Check code style violations"
Bug Investigation with Competing Theories — Contest pattern for unknown root cause
Lead → @theory-A "Test: race condition in async handler"
→ @theory-B "Test: memory leak in connection pool"
→ @theory-C "Test: deadlocks in goroutine scheduler"
Multi-Domain Migration — Vertical slice by layer (data, API, UI)
Lead → @service-A "Migrate auth/, own files: auth/*"
→ @service-B "Migrate user/, own files: user/*"
→ @service-C "Migrate order/, own files: order/*"
Library Evaluation — Pipeline (research → compare → recommend)
Lead → @researcher "Research X alternatives → /tmp/research.json"
[lead waits, then:]
└── @implementer "Implement using /tmp/research.json"
Architecture Review — Fan-out by subsystem, fan-in for decision
Lead → @data-arch "Review data layer: schemas, queries, indexes"
→ @api-arch "Review API layer: endpoints, auth, rate limits"
→ @infra-arch "Review infra: deployment, scaling, monitoring"
[lead synthesizes: unified recommendations]
Test Coverage Expansion — Parallel workers by module, aggregator merges
Lead → @unit-tests "Generate tests for src/models/"
→ @unit-tests "Generate tests for src/services/"
→ @unit-tests "Generate tests for src/api/"
[lead merges: dedupe → combined suite]
Documentation Audit — Parallel readers across doc sections
Lead → @docs-review "Audit docs/api/ for completeness"
→ @docs-review "Audit docs/guides/ for accuracy"
→ @docs-review "Audit docs/reference/ for consistency"
Dependency Audit — Contest (safe vs unsafe upgrade paths)
Lead → @safe-upgrade "Test upgrade path: minor versions only"
→ @risky-upgrade "Test upgrade path: major versions with deprecations"
Performance Profiling — Horizontal split (CPU, memory, network)
Lead → @perf-cpu "Profile CPU usage in src/"
→ @perf-memory "Profile memory allocations"
→ @perf-network "Profile network call latency"
Refactoring Safety Check — Fan-out by risk level, aggregator synthesizes
Lead → @safe-refactor "Refactor low-risk: utils, helpers"
→ @risky-refactor "Refactor high-risk: core business logic"
[lead synthesizes: migration plan with risk assessment]
After implementing a solution, run a maker-checker loop:
Orchestrator → Implement → Spawn reviewer (read-only) → [pass] → integrate
↓ [fail, specific feedback]
Fix → Respawn reviewer → ...
The reviewer must report ALL findings including low-confidence ones. A downstream filter ranks severity — don't ask the reviewer to make that judgment.
Choose by trigger type:
| Tool | Trigger | Best for |
|---|---|---|
| Hooks | Tool events | Validate subagent outputs, enforce guardrails |
| ScheduleWakeup / CronCreate | Time | Recurring orchestration, long-poll retries |
| Monitor | External events | Real-time CI/log watching, instant reaction |
Never poll when you can watch. ScheduleWakeup fires on a timer regardless of state. Monitor wakes only when output matches — zero cost while silent.
See the automation layers reference for detailed comparison.
Claude Code implements a four-layer memory system:
| Layer | Mechanism | Persistence |
|---|---|---|
CLAUDE.md | Human-authored, loaded every session | Global/Project |
MEMORY.md | Learned during sessions, auto-written | Project |
| Subagent Memory | memory: frontmatter per agent | Agent-scoped |
State persistence rules:
See the memory architecture reference for full details.
| Failure Mode | Detection | Recovery Cost | Prevention |
|---|---|---|---|
| Over-delegation | Obvious in hindsight | Low | Default to inline for <5min tasks |
| Context leakage | Silent, subtle | High | Non-semantic agent names; explicit subagent type |
| Tool permission misconfig | Immediate failure | Medium | Validate YAML; use allowlists |
| State management failures | Silent corruption | High | Schema validation at every tool boundary |
| Blocking anti-patterns | Appears productive | Very high | Hard iteration limits; don't race |
| File conflicts | Git conflicts visible | Medium | Worktree isolation; file-disjoint decomposition |
Key rule: Stop and report after 2 retries on the same failure. Never loop silently.
See the failure modes reference for detailed prevention strategies.
Key reference files for subagent authoring and orchestration include:
race-framework.md — Full RACE prompt structureorchestration-patterns.md — All five patterns with examplesautomation-layers.md — Monitor vs ScheduleWakeup vs Hooksmemory-architecture.md — Four-layer system detailsfailure-modes.md — Detection, recovery, and preventioncontext-management.md — Context hardening strategiesgotchas.md — Common subagent pitfallsnpx claudepluginhub git-fg/taches-principled --plugin tp-session-auditProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.