📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,347 @@
|
||||
---
|
||||
name: subagents
|
||||
description: This skill should be used when coordinating agents, delegating tasks to specialists, or when "dispatch agents", "which agent", or "multi-agent" are mentioned.
|
||||
metadata:
|
||||
version: "2.2.0"
|
||||
related-skills:
|
||||
- context-management
|
||||
- pathfinding
|
||||
---
|
||||
|
||||
# Subagent Coordination
|
||||
|
||||
Orchestrate outfitter subagents by matching tasks to the right agent + skill combinations.
|
||||
|
||||
## Orchestration Planning
|
||||
|
||||
For complex multi-agent tasks, **start with the Plan subagent** to research and design the orchestration strategy before execution.
|
||||
|
||||
```
|
||||
Complex task arrives
|
||||
│
|
||||
├─► Plan subagent (research stage)
|
||||
│ └─► Explore codebase, gather context
|
||||
│ └─► Identify which agents and skills needed
|
||||
│ └─► Design execution sequence (sequential, parallel, or hybrid)
|
||||
│ └─► Return orchestration plan
|
||||
│
|
||||
└─► Execute plan (dispatch agents per plan)
|
||||
```
|
||||
|
||||
**Plan subagent benefits**:
|
||||
- Runs in isolated context — doesn't consume main conversation tokens
|
||||
- Can read many files without bloating orchestrator context
|
||||
- Returns concise plan for execution
|
||||
|
||||
**When to use Plan subagent**:
|
||||
- Task touches multiple domains (auth + performance + testing)
|
||||
- Unknown codebase area — needs exploration first
|
||||
- Sequence of agents matters (dependencies between steps)
|
||||
- High-stakes changes requiring careful coordination
|
||||
|
||||
## Context Management
|
||||
|
||||
For long-running orchestration, load the **context-management** skill. It teaches:
|
||||
- Using Tasks as survivable state (persists across compaction)
|
||||
- Delegating to subagents to preserve main context
|
||||
- Pre-compaction checklists to capture progress
|
||||
- Cross-session patterns for multi-day work
|
||||
|
||||
**Key principle**: Main conversation context is precious. Delegate exploration and research to subagents — only their summaries return, keeping main context lean.
|
||||
|
||||
## Roles and Agents
|
||||
|
||||
Coordination uses **roles** (what function is needed) mapped to **agents** (who fulfills it). This allows substitution when better-suited agents are available.
|
||||
|
||||
### Baselayer Agents
|
||||
|
||||
| Role | Agent | Purpose |
|
||||
|------|-------|---------|
|
||||
| coding | **engineer** | Build, implement, fix, refactor |
|
||||
| reviewing | **reviewer** | Evaluate code, PRs, architecture, security |
|
||||
| research | **analyst** | Investigate, research, explore |
|
||||
| debugging | **debugger** | Diagnose issues, trace problems |
|
||||
| testing | **tester** | Validate, prove, verify behavior |
|
||||
| challenging | **skeptic** | Challenge complexity, question assumptions |
|
||||
| specialist | **specialist** | Domain expertise (CI/CD, design, accessibility, etc.) |
|
||||
| patterns | **analyst** | Extract reusable patterns from work |
|
||||
|
||||
### Other Available Agents
|
||||
|
||||
Additional agents may be available in your environment (user-defined, plugin-provided, or built-in). When dispatching:
|
||||
|
||||
1. Check available agents for best fit to the role
|
||||
2. Prefer specialized agents over generalists when they match the task
|
||||
3. Fall back to outfitter agents when no better option exists
|
||||
|
||||
Examples of role substitution:
|
||||
- **coding** → `senior-engineer`, `developer`, `engineer`
|
||||
- **reviewing** → `security-auditor`, `code-reviewer`, `reviewer`
|
||||
- **research** → `research-engineer`, `docs-librarian`, `analyst`
|
||||
- **specialist** → `cicd-expert`, `design-agent`, `accessibility-auditor`, `bun-expert`
|
||||
|
||||
## Task Routing
|
||||
|
||||
Route by role, then select the best available agent for that role:
|
||||
|
||||
```
|
||||
User request arrives
|
||||
│
|
||||
├─► "build/implement/fix/refactor" ──► coding role
|
||||
│
|
||||
├─► "review/critique/audit" ──► reviewing role
|
||||
│
|
||||
├─► "investigate/research/explore" ──► research role
|
||||
│
|
||||
├─► "debug/diagnose/trace" ──► debugging role
|
||||
│
|
||||
├─► "test/validate/prove" ──► testing role
|
||||
│
|
||||
├─► "simplify/challenge/is this overkill" ──► challenging role
|
||||
│
|
||||
├─► "deploy/configure/CI/design/a11y" ──► specialist role
|
||||
│
|
||||
└─► "capture this workflow/make reusable" ──► patterns role
|
||||
```
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Sequential Handoff
|
||||
|
||||
One agent completes, passes to next:
|
||||
|
||||
```
|
||||
research (investigate) → coding (implement) → reviewing (verify) → testing (validate)
|
||||
```
|
||||
|
||||
**Use when**: Clear stages, each requires different expertise.
|
||||
|
||||
### Parallel Execution
|
||||
|
||||
Multiple agents work simultaneously using `run_in_background: true`:
|
||||
|
||||
```
|
||||
┌─► reviewing (code quality)
|
||||
│
|
||||
task ──┼─► research (impact analysis)
|
||||
│
|
||||
└─► testing (regression tests)
|
||||
```
|
||||
|
||||
**Use when**: Independent concerns, time-sensitive, comprehensive coverage needed.
|
||||
|
||||
### Challenge Loop
|
||||
|
||||
Build → challenge → refine:
|
||||
|
||||
```
|
||||
coding (propose) ←→ challenging (evaluate) → coding (refine)
|
||||
```
|
||||
|
||||
**Use when**: Complex architecture, preventing over-engineering, high-stakes decisions.
|
||||
|
||||
### Investigation Chain
|
||||
|
||||
Narrow down, then fix:
|
||||
|
||||
```
|
||||
research (scope) → debugging (root cause) → coding (fix) → testing (verify)
|
||||
```
|
||||
|
||||
**Use when**: Bug reports, production issues, unclear symptoms.
|
||||
|
||||
## Role + Skill Combinations
|
||||
|
||||
### Coding Role
|
||||
|
||||
| Task | Skills |
|
||||
|------|--------|
|
||||
| New feature | software-craft, tdd |
|
||||
| Bug fix | debugging → software-craft |
|
||||
| Refactor | software-craft + simplify |
|
||||
| API endpoint | hono-dev, software-craft |
|
||||
| React component | react-dev, software-craft |
|
||||
| AI feature | ai-sdk, software-craft |
|
||||
|
||||
### Reviewing Role
|
||||
|
||||
| Task | Skills |
|
||||
|------|--------|
|
||||
| PR review | code-review |
|
||||
| Architecture review | architecture |
|
||||
| Performance audit | performance |
|
||||
| Security audit | security |
|
||||
| Pre-merge check | code-review + scenarios |
|
||||
|
||||
### Research Role
|
||||
|
||||
| Task | Skills |
|
||||
|------|--------|
|
||||
| Codebase exploration | codebase-recon |
|
||||
| Research question | research |
|
||||
| Unclear requirements | pathfinding |
|
||||
| Status report | status, report-findings |
|
||||
|
||||
### Testing Role
|
||||
|
||||
| Task | Skills |
|
||||
|------|--------|
|
||||
| Feature validation | scenarios |
|
||||
| TDD implementation | tdd |
|
||||
| Integration testing | scenarios |
|
||||
|
||||
## Advanced Execution Patterns
|
||||
|
||||
### Background Execution
|
||||
|
||||
Run agents asynchronously for parallel work:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Security review",
|
||||
"prompt": "Review auth module for vulnerabilities",
|
||||
"subagent_type": "outfitter:reviewer",
|
||||
"run_in_background": true
|
||||
}
|
||||
```
|
||||
|
||||
Retrieve results with `TaskOutput`:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "agent-abc123",
|
||||
"block": true
|
||||
}
|
||||
```
|
||||
|
||||
### Chaining Subagents
|
||||
|
||||
Sequence agents for complex workflows — each agent's output informs the next:
|
||||
|
||||
```
|
||||
research agent → "Found 3 auth patterns in use"
|
||||
↓
|
||||
coding agent → "Implementing refresh token flow using pattern A"
|
||||
↓
|
||||
reviewing agent → "Verified implementation, found 1 issue"
|
||||
↓
|
||||
coding agent → "Fixed issue, ready for merge"
|
||||
```
|
||||
|
||||
Pass context explicitly between agents via prompt.
|
||||
|
||||
### Resumable Sessions
|
||||
|
||||
Continue long-running work across invocations:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Continue security analysis",
|
||||
"prompt": "Now examine session management",
|
||||
"subagent_type": "outfitter:reviewer",
|
||||
"resume": "agent-abc123"
|
||||
}
|
||||
```
|
||||
|
||||
Agent preserves full context from previous execution.
|
||||
|
||||
**Use cases**:
|
||||
- Multi-stage research spanning topics
|
||||
- Iterative refinement without re-explaining context
|
||||
- Long debugging sessions with incremental discoveries
|
||||
|
||||
### Model Selection
|
||||
|
||||
Override model for specific needs:
|
||||
|
||||
```json
|
||||
{
|
||||
"subagent_type": "outfitter:analyst",
|
||||
"model": "haiku" // Fast, cheap for exploration
|
||||
}
|
||||
```
|
||||
|
||||
- **haiku**: Fast exploration, simple queries
|
||||
- **sonnet**: Balanced reasoning (default)
|
||||
- **opus**: Complex analysis, nuanced judgment
|
||||
|
||||
## Coordination Rules
|
||||
|
||||
1. **Single owner**: One role owns each task stage
|
||||
2. **Clear handoffs**: Explicit deliverables between agents
|
||||
3. **Skill loading**: Agent loads only needed skills
|
||||
4. **User prefs first**: Check `CLAUDE.md` before applying defaults
|
||||
5. **Minimal agents**: Don't parallelize what can be sequential
|
||||
|
||||
## Decision Framework
|
||||
|
||||
When agents face implementation choices:
|
||||
|
||||
1. **Favor existing patterns** — Match what's already in the codebase
|
||||
2. **Prefer simplicity** — Cleverness is a liability; simple is maintainable
|
||||
3. **Optimize for maintainability** — Next developer (or agent) must understand it
|
||||
4. **Consider backward compatibility** — Breaking changes require explicit approval
|
||||
5. **Document trade-offs** — When choosing between options, record why
|
||||
|
||||
These principles apply across all roles. Agents should surface decisions to the orchestrator when trade-offs are significant.
|
||||
|
||||
## Communication Style
|
||||
|
||||
Orchestrators and agents should:
|
||||
|
||||
- **Report progress** at each major step (don't go silent)
|
||||
- **Flag blockers immediately** — don't spin on unsolvable problems
|
||||
- **Provide clear summaries** of delegated work (what was done, what remains)
|
||||
- **Include file paths and line numbers** when referencing code
|
||||
|
||||
Progress format:
|
||||
|
||||
```
|
||||
░░░░░░░░░░ [1/5] research: Exploring auth patterns
|
||||
▓▓▓▓░░░░░░ [2/5] coding: Implementing refresh token flow
|
||||
```
|
||||
|
||||
## When to Escalate
|
||||
|
||||
- **Blocked**: Agent can't proceed → route to research role
|
||||
- **Conflicting findings**: Multiple agents disagree → surface to user
|
||||
- **Scope creep**: Task expands beyond role's domain → re-route
|
||||
- **Missing context**: Not enough info → research role with pathfinding skill
|
||||
|
||||
## Git Operations Policy
|
||||
|
||||
> **CRITICAL**: Subagents MUST NOT perform git operations (commit, push, branch creation) when running in parallel.
|
||||
>
|
||||
> Only the **orchestrator** handles git state. Subagents write code to the filesystem and report completion.
|
||||
|
||||
For detailed workflows and recovery procedures, see the **source-control** plugin:
|
||||
|
||||
- `source-control:multi-agent-vcs` — Full orchestrator-only workflow patterns
|
||||
- `source-control:graphite-stacks` — Graphite-specific commands and recovery
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Running all agents on every task (wasteful)
|
||||
- Skipping reviewing role for "small changes" (risk)
|
||||
- Coding role debugging without debugging skills (inefficient)
|
||||
- Parallel agents with dependencies (race conditions)
|
||||
- Not challenging complex proposals (over-engineering)
|
||||
- **Parallel agents with git permissions** (stack corruption)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**"I need to build X"** → coding role + TDD skills
|
||||
|
||||
**"Review this PR"** → reviewing role + code-review
|
||||
|
||||
**"Why is this broken?"** → debugging role + debugging
|
||||
|
||||
**"Is this approach overkill?"** → challenging role + simplify
|
||||
|
||||
**"Prove this works"** → testing role + scenarios
|
||||
|
||||
**"What's the codebase doing?"** → research role + codebase-recon
|
||||
|
||||
**"Deploy to production"** → specialist role + domain skills
|
||||
|
||||
**"Make this workflow reusable"** → patterns role + codify
|
||||
Reference in New Issue
Block a user