Agent Orchestration
Available Agents
| Agent | Purpose | When to Use | Isolation |
|---|---|---|---|
| planner | Implementation planning | Complex features, refactoring | — |
| architect | System design | Architectural decisions, package structure | — |
| code-reviewer | Code review | After writing code | — |
| refactor-cleaner | Dead code cleanup | Code maintenance | worktree |
| doc-updater | Documentation | Updating docs, godoc | worktree |
| deep-inspector | EOL batch evidence fetching | Deep Inspection orchestration | — |
Available Skills
| Skill | Command | When to Use |
|---|---|---|
| deadcode | /deadcode [fix] [path] | Quick dead code audit or interactive cleanup |
| review | /review [PR#] [--copilot-only] [--dry-run] | Unified review: Claude + Copilot resolution + rule learning |
| batch-issues | /batch-issues [issue#s] [--dry-run] [--max-parallel N] | Parallel issue processing with conflict-aware agent dispatch |
| diet-trial | /diet-trial <org/repo> [--tool trivy|syft] [--compare] | Run diet on external OSS for testing, bug finding, and case study data |
| diet-fuzz | /diet-fuzz <languages|all> [--count N] [--tool trivy,syft,cdxgen] [--max-parallel N] | Batch fuzz-test diet across many OSS projects for parser accuracy bugs |
Immediate Agent Usage
No user prompt needed:
- Complex feature requests - Use planner agent
- Code just written/modified - Use code-reviewer agent
- Architectural decision - Use architect agent
Code Review Policy
When the user requests a code review (e.g., "レビューして", "review this"), use the /review skill.
This skill orchestrates:
- Phase 1 — Launch code-reviewer + architect agents in parallel (Claude review)
- Phase 2 — Discover and resolve unresolved Copilot review comments (fix, reply, resolve)
- Phase 3 — Detect recurring Copilot patterns and propose rule additions to prevent repeat feedback
Use /review --copilot-only to skip Phase 1 when only Copilot resolution is needed.
See .github/prompts/review.prompt.md for the full specification.
Reviewer Findings Are Input, Not Directives
Reviewer agent findings (including CRITICAL severity) are discussion input, not authoritative instructions. Before implementing a reviewer suggestion:
- Check ADRs (
docs/adr/) — the flagged behavior may be an intentional design decision with documented rationale. - Check conversation history — the user may have already made this decision earlier in the session.
- When in doubt, ask the user — do not auto-fix reviewer findings that contradict prior decisions.
Why: Reviewer agents see only code, not the design intent behind it. In PR #123, a reviewer flagged "transitive advisories not shown on RequestedVersion" as CRITICAL, but this was an intentional decision (see ADR-0011). Blindly implementing the "fix" re-introduced a bug the user had already reported and resolved.
Workflow-File PRs Are Resolved Locally, Not by CI Claude
PRs whose changes touch .github/workflows/** MUST be fixed locally by a human-driven Claude session, not by the auto-fix loop in copilot-review-fix.yml.
Why: The auto-fix PAT (GH_ACTIONS_TOKEN) intentionally lacks the workflow scope. Workflow files define CI runtime permissions and secret access — granting a bot the ability to rewrite them creates a privilege-escalation surface (prompt-injection or misbehaviour can self-modify the bot's own runtime). Defense-in-depth: keep PAT scope minimal; pay the small operational cost of manual intervention on workflow PRs.
How to apply:
- When CI Claude reports "PAT lacks
workflowscope" on a workflow-file thread, do NOT propose granting the scope. Pull the branch locally, apply the fix, push. - The marker dedup in
copilot-review-fix.ymlinvalidates on push (HEAD SHA changes), so a manual push cleanly re-arms the auto-fix loop for the next round. - If the same Copilot finding loops indefinitely on a non-workflow PR, that's a different bug — investigate the auto-fix loop, do NOT relax PAT scope.
Symptom of the broken case (for debugging): trigger-claude job runs success but logs trigger already posted for HEAD <sha> (count=1) — skip because a prior Claude run posted the marker but couldn't push the actual fix.
Worktree Isolation Policy
Agents that write files (Edit, Write) MUST be launched with isolation: "worktree" to prevent branch conflicts during parallel development. This gives each agent an isolated copy of the repository.
Rules:
- Agents with write tools (
refactor-cleaner,doc-updater) → alwaysisolation: "worktree" - Read-only agents (
planner,architect,code-reviewer) → no isolation needed - If the worktree agent makes changes, review the returned branch and merge manually
- NEVER remove another agent's worktree. Agent worktrees created by
isolation: "worktree"are automatically managed by the Agent tool. Only the spawning session or the agent itself should clean them up.
# GOOD: Write agent with worktree isolation
Agent(subagent_type="refactor-cleaner", isolation="worktree", prompt="...")
# GOOD: Read-only agent without isolation
Agent(subagent_type="code-reviewer", prompt="...")
# BAD: Write agent without isolation (can corrupt working tree)
Agent(subagent_type="doc-updater", prompt="...")
# BAD: Deleting a worktree you didn't create
git worktree remove .claude/worktrees/some-agent-worktree # may break another session!
Parallel Task Execution
ALWAYS use parallel Task execution for independent operations:
# GOOD: Parallel execution
Launch 3 agents in parallel:
1. Agent 1: Review cmd/root.go changes
2. Agent 2: Review internal/config/ changes
3. Agent 3: Check test coverage
# BAD: Sequential when unnecessary
First agent 1, then agent 2, then agent 3