| name | skill-discovery |
| description | Decision tree for routing any task to the right agent and skill set. Loaded on session start and consulted whenever you're unsure which specialist applies, which skill combination to load for a given task, or when main Claude (running core/orchestration) needs to decide which subagent to spawn for a Phase 3 subtask. Also surfaces available CLI tools, MCP servers, and user-installed skills/agents/plugins so you can prefer what's actually on the machine.
|
| user-invocable | false |
Skill Discovery
Route tasks to the right agent. Follow the first matching branch.
Relationship to orchestration. When main Claude runs core/orchestration and reaches Phase 3, it consults this tree to decide which specialist to spawn for each subtask (builder vs cli-builder vs shipper vs tester). The tree is orthogonal to the orchestration workflow — orchestration owns when and how to spawn; this skill owns who to spawn.
Cross-cutting: All agents load core/token-efficiency — compresses human-facing output, never specs or agent-to-agent artifacts. Use /compact to adjust level.
How to Use This Tree
- Language detection is automatic. The session-start hook emits
detected_languages in the session context. Agents read it directly; the tree does not need to branch on language.
- Follow the first matching branch. Branches are ordered roughly by specificity. When a task matches multiple branches, choose the most specific one (e.g., "write tests for a new feature" →
tester, not builder; "design a new HTTP API" → architect, not builder; "debug the failing test" → debugging + tester, not just tester).
- External writes are gated. Any task that pushes, creates PRs, publishes releases, or pushes container images requires
ops_enabled=true in session context — the opt-in ops-skills plugin. If disabled, report the action as a follow-up; do not execute. See the "Push, PR, release" branch at the bottom of the tree.
Tool Awareness
Before recommending an external command or a third-party integration, read the session-start JSON for what's actually available on this machine:
available_tools — comma-joined CLI tools present from a fixed probe list: ast-grep, fd, rg, jq, yq, gh, docker, kubectl. When a task could use ast-grep or rg for code exploration, prefer the one that's present. When neither is present, fall back to Grep/Glob without complaint.missing_tools — the complement of available_tools. Use this only to explain why you're recommending a fallback ("ast-grep not installed, using Grep instead"). Do not ask the user to install anything unless they've asked for a setup plan.mcp_servers — comma-joined names of MCP servers configured for this user or project. When a task matches an MCP server's domain (e.g. browser automation and playwright is listed), surface the MCP option in your plan alongside the framework's native approach and let the user choose.user_skills — skill directory names installed at ~/.claude/skills/, outside this framework. Observational signal only: if a task clearly overlaps with a listed user skill, mention it once as "a related option" and proceed with the framework's own approach by default.user_agents — agent directory names at ~/.claude/agents/, outside this framework. Same treatment as user_skills.user_plugins — plugin names from the user's installed-plugins manifest (~/.claude/plugins/installed_plugins.json). Same treatment.
Treat every field as potentially empty. A bare system with no MCP servers, no user extensions, and none of the probed CLI tools is a fully supported configuration — the framework's core flows do not depend on any of them. Never gate framework behavior on a third-party integration being present.
Decision Tree
When a task arrives, follow the first matching branch:
- Vague idea or unclear requirements?
- Has a specific problem? → critic → clarify before anything else
- Exploring or brainstorming? → idea-refine → then
/define
- Grounding a task in existing code before spec?
- scout →
core/discovery → runs in parallel with critic during /define
- Complex task spanning multiple concerns?
- main Claude via
core/orchestration → decomposes into spec, delegates to specialists, enforces HITL gates
- New project or scaffold from scratch?
- architect →
core/project-structure + lang/project-init
- Design change, restructure, or define interfaces?
- architect →
core/api-design + lang/interface-design
- Implement feature or write application code?
- CLI command? → cli-builder →
lang/cli
- Other code → builder →
core/error-handling + lang/*
- Write or fix tests?
- tester →
core/testing + lang/testing
- Review code or PR review?
- reviewer →
core/code-review + lang/code-review
- Containerize, add logging, metrics, or tracing?
- shipper →
core/docker + core/observability + lang/*
- Refactor, remove code, or simplify?
- reviewer (or builder if applying) →
core/simplification
- Debug a bug, failing test, or incident?
- builder →
core/debugging + core/testing
- Security design, threat model, authz/authn?
- architect →
core/security (design-time); review-time covered by core/code-review §4
- Performance issue, profiling, benchmark?
- builder or reviewer →
core/performance
- Write ADR, README, design doc?
- architect →
core/documentation
- Author or modify project invariants?
- From scratch → architect (or critic if evaluating whether an invariant is warranted) →
core/constitution
- From an existing codebase → main Claude (spawns
scout + critic in parallel) → core/constitution (Proposing Candidates) via /constitution-propose
- Commit (local only)?
- builder or shipper →
core/git-workflow
- Push, PR, release, or registry push (external writes)?
- Requires
ops-skills opt-in. Check ops_enabled in session context.
- When
ops_enabled=true: shipper → ops/git-remote, ops/pull-requests, ops/release, ops/registry
- When
ops_enabled=false (default): report as follow-up; do not execute
- Unsure?
- critic → will clarify and route
Agent Quick Reference
| Agent | When | Never |
|---|
| critic | First pass on any non-trivial task | Don't skip for "obvious" tasks |
| scout | Discovery of existing code during /define | Don't use for design or code writing |
main Claude (core/orchestration) | Multi-step tasks, spec generation, gated execution | Don't use for single-concern tasks |
| architect | Structure, interfaces, API design | Don't use for implementation |
| builder | Application code (handlers, services) | Don't use for tests or infra |
| cli-builder | CLI commands, flags, config | Don't use for non-CLI code |
| tester | Unit/integration tests, mocks | Don't modify app code |
| reviewer | Code review (read-only) | Don't use to fix code |
| shipper | Docker, logging, metrics, health | Don't modify business logic |
Core Operating Behaviors (all agents)
- Surface assumptions — state what you're assuming before implementing
- Manage confusion — STOP and clarify inconsistencies; don't guess
- Push back — honestly disagree on problematic approaches
- Enforce simplicity — resist overcomplication
- Maintain scope — touch only what's asked; no unsolicited renovation
- Verify, don't assume — "seems right" is never sufficient; evidence required
Verification
