Agent Collaboration Rules
Available Sub-Agents
| Agent | Purpose | When to Use |
|---|---|---|
| planner | Implementation planning | Before complex features or refactors |
| architect | Design review | Architecture changes, key design decisions |
| tdd-guide | Test-driven development | New features, bug fixes |
| code-reviewer | Code review | After code changes |
| security-reviewer | Security analysis | Before commits with auth/permission changes |
Auto-Launch (no user prompt needed)
- Complex feature request → planner
- Code changes complete → code-reviewer
- Security-relevant changes → security-reviewer
- Authentication / authorization changes
- File permission or capability changes
- Network configuration changes
- Secrets handling changes
- Architecture proposal → architect
Passing Context to Sub-Agents
Before launching a sub-agent, always include existing design decisions in the prompt:
- What already exists: current file contents, previous decisions
- What must NOT change: constraints that were deliberately set (e.g., "no jq", "use $HOME not absolute path")
- Why it was done that way: rationale, so the agent doesn't "fix" intentional choices
Without this context, sub-agents will apply generic best practices that may conflict with deliberate project decisions. The calling agent is responsible for providing context.
Example (bad):
"Check the statusline config and fix any issues."
Example (good):
"Check the statusline config. Existing decisions: (1) use grep not jq — shell-only principle, (2) use $HOME not absolute path — must work across environments. Fix only what is broken, do not change these."
Parallel Execution
Run independent agents concurrently:
Good: Launch code-reviewer and security-reviewer in the same message
Bad: Run code-reviewer, wait for result, then run security-reviewer