route
分析任务复杂性并路由到适当的工作流程(用于小变更的一次性氛围,用于中等任务的一次性规范,用于大型多工作流工作的编排器)。在开始任何新任务时使用以确定正确的方法。
name: route description: Analyze task complexity and route to appropriate workflow. Defaults to oneoff-spec (specs are cheap, bugs are expensive). Use oneoff-vibe only for truly trivial changes or explicit user override. Use orchestrator for large multi-workstream efforts. allowed-tools: Read, Glob, Grep
Route Skill
Purpose
Analyze the user request and determine the appropriate workflow path based on task complexity, scope, and estimated effort.
Complexity Heuristics
Default to specs. Use oneoff-spec unless the task is truly trivial OR the user explicitly requests to skip specs.
Trivial (oneoff-vibe)
Route to quick execution only when:
Truly trivial changes (all must apply):
- Single-line or few-character fix (typo, off-by-one, missing semicolon)
- Zero ambiguity about what to change
- No behavioral impact beyond the obvious fix
- No tests needed or test change is equally trivial
Examples of truly trivial:
- Fix typo in README: "teh" → "the"
- Fix obvious syntax error
- Update version number in config
- Add missing import that's causing a build error
- Comment clarification
User explicitly requests vibe:
- User says: "just do it", "vibe", "skip the spec", "don't need a spec", "quick fix"
- Honor the request but note in rationale
NOT trivial (use oneoff-spec instead):
- Bug fix requiring investigation
- "Simple" feature additions (even small ones have edge cases)
- Documentation updates with new content (not just typo fixes)
- Configuration changes affecting behavior
- Any change where you'd want to verify acceptance criteria
Standard (oneoff-spec / Spec Group) — THE DEFAULT
Route to spec group workflow for most tasks:
- Any feature addition, enhancement, or new functionality
- Bug fixes (even "simple" ones benefit from AC definition)
- Refactoring with defined goals
- Documentation with new content
- API changes
- UI changes
- Needs spec group: requirements.md, spec.md, atomic specs
- Spec location:
.claude/specs/groups/<spec-group-id>/ - Why default: Specs create accountability, testability, and prevent scope creep
Large (orchestrator / MasterSpec)
Route to multi-workstream orchestration with git worktrees:
- 5+ files impacted across multiple layers
- Multiple workstreams with interdependencies
- Cross-cutting concerns (contracts, interfaces, shared state)
- Impacts multiple services, layers, or subsystems
- Requires parallel execution by multiple subagents
- Complex coordination and integration needs
- Estimated effort: 4+ hours
- Needs MasterSpec with workstream spec groups: Each workstream gets its own spec group with atomic specs
- Spec structure:
.claude/specs/groups/<master-spec-group-id>/with workstream subdirectories - Parallel execution: Workstreams execute in isolated git worktrees
- Dependency orchestration: Facilitator manages merge order based on dependencies
Refactor (refactor workflow)
Route to refactor workflow for code quality improvements:
- Explicit refactoring requests ("refactor this", "clean up", "improve code quality")
- Tech debt reduction tasks
- Pattern migration requests ("migrate from X to Y pattern")
- Code consolidation or deduplication
- Architecture improvements without feature changes
- Key constraint: Behavior must be preserved (no feature changes)
- Needs: Clear scope definition, before/after patterns, test verification
- Uses:
/refactorskill with Refactorer subagent - Validation: Tests must pass before and after (behavior preservation proof)
Refactor triggers (route to refactor when ANY apply):
- User says: "refactor", "clean up", "improve code quality", "reduce tech debt"
- User says: "migrate to ", "consolidate", "deduplicate"
- Request focuses on code structure without changing behavior
- Request mentions: "maintainability", "readability", "consistency"
NOT refactor (route to oneoff-spec instead):
- "Refactor and add feature X" → oneoff-spec (behavior changes)
- "Clean up and fix this bug" → oneoff-spec (behavior changes)
- Unclear if behavior should change → oneoff-spec (spec clarifies intent)
Routing Process
Step 1: Load Context
If the user references an existing spec group:
# Check for active spec group
ls .claude/specs/groups/<spec-group-id>/manifest.json 2>/dev/null
Load the spec group and continue from its current state based on review_state and work_state.
Step 2: Analyze Scope
Use Glob and Grep to understand impact:
# Find relevant files
glob "**/*.ts" | grep -i "<keyword>"
# Understand current architecture
grep -r "class <Name>" --include="*.ts"
Step 3: Apply Heuristics
Count impacted files and assess complexity:
- File count: How many files need changes?
- Coupling: Are changes isolated or cross-cutting?
- Unknowns: How many open questions exist?
- Testing: What test coverage is needed?
Step 4: Analyze Delegation Opportunities
Delegation is the default. Before making a routing decision, analyze whether the task can be decomposed into independent subtasks for parallel subagent execution:
Always delegate when:
- Task has 2+ independent components that can run in parallel
- Exploration/research is needed before implementation
- Multiple files need changes that don't depend on each other
- Code review, security review, or testing can run in parallel
Delegation analysis checklist:
- Can parts of this work run independently? → Dispatch parallel subagents
- Is exploration needed first? → Dispatch Explore subagent before deciding scope
- Are there isolated concerns? → Dispatch specialized subagents (impl, test, review)
- Would main-context benefit from delegation? → Always yes for non-trivial tasks
Do NOT delegate only when:
- Single-file typo/config fix (oneoff-vibe)
- Task requires tight coordination that subagents can't provide
- User explicitly requests direct execution
Step 5: Make Routing Decision
Produce a routing decision with delegation plan:
workflow: oneoff-vibe | oneoff-spec | orchestrator | refactor
rationale: <Brief explanation of why this workflow was chosen>
estimated_scope: small | medium | large
estimated_files: <N>
delegation:
parallel_subtasks:
- <subtask 1>: <subagent type>
- <subtask 2>: <subagent type>
sequential_dependencies:
- <subtask that must complete first>
exploration_needed: true | false
workstreams:
- <workstream 1> (for orchestrator only)
- <workstream 2>
next_action: <Suggested next step>
Step 6: Persist Decision
Save routing decision to session state:
# Append to session context
echo "{\"timestamp\": \"$(date -Iseconds)\", \"workflow\": \"oneoff-spec\", \"rationale\": \"...\"}" >> .claude/context/session.json
Edge Cases
Ambiguous Complexity
When uncertain about task size:
- Default to oneoff-spec — specs are cheap, debugging without specs is expensive
- If task seems trivial but has any ambiguity → oneoff-spec
- Can escalate to orchestrator if spec reveals hidden complexity
- Better to "over-spec" a simple task than "under-spec" a complex one
User Override
If user explicitly requests a workflow:
- "Just do it", "vibe", "quick fix", "skip spec" → oneoff-vibe (honor request, note in rationale)
- "Write a full spec first" → oneoff-spec or orchestrator
- User preference always wins, but default assumption is: user wants quality (specs)
Existing Spec Group
If .claude/specs/groups/<spec-group-id>/manifest.json exists:
- Check
review_stateandwork_statefields in manifest - review_state:
DRAFT→ Continue spec authoring or atomizationREVIEWED→ Awaiting user approvalAPPROVED→ Route to implementation
- work_state:
PLAN_READY→ Ready for implementationIMPLEMENTING→ Continue implementationVERIFYING→ Run unify validationREADY_TO_MERGE→ Proceed to code review, security review
Output Format
Always output a clear routing decision:
## Routing Decision
**Workflow**: oneoff-spec
**Rationale**: This task involves adding a new API endpoint with authentication, requiring changes to 3-4 files (route handler, service layer, tests). The scope is well-defined but needs formal requirements and test planning.
**Estimated Scope**: medium
**Estimated Files**: 4 (controller, service, tests, types)
**Next Action**: Use `/pm` skill to interview user about endpoint requirements, then create TaskSpec.
For refactor workflows, include behavior preservation note:
## Routing Decision
**Workflow**: refactor
**Rationale**: Explicit refactoring request to migrate to repository pattern. No behavior changes - code reorganization only.
**Estimated Scope**: medium
**Estimated Files**: 4 (service, repository, interface, tests)
**Behavior Preservation**: Tests must pass before and after refactoring.
**Next Action**: Use `/refactor` skill to define scope and patterns.
Integration with Other Skills
After routing:
- oneoff-vibe: Proceed directly to implementation
- oneoff-spec: Use
/pmto gather requirements → (optional)/prd draftto write PRD to Google Docs →/specto create spec group →/atomizeto create atomic specs →/enforceto validate atomicity → User approval →/implement+/test→/unify→/code-review→/security→ (if PRD exists)/prd pushto sync discoveries - orchestrator: Use
/pmto create ProblemBrief → (optional)/prd draftfor stakeholder PRD →/specto create MasterSpec with workstream spec groups → For each workstream:/atomize+/enforce→ User approval → Facilitator orchestrates parallel execution →/prd pushto sync discoveries - refactor: Use
/refactorskill → Define scope and patterns → Run tests (baseline) → Execute refactoring → Run tests (verification) →/code-review→/security(if applicable)
Examples
Example 1: Truly Trivial (oneoff-vibe)
Request: "Fix the typo in README.md line 42: 'teh' should be 'the'"
Routing:
- workflow: oneoff-vibe
- rationale: Single character fix, zero ambiguity, no behavioral impact
- estimated_scope: trivial
- delegation: none
- next_action: Make the edit directly
Example 2: Seems Simple But Gets Spec (oneoff-spec)
Request: "Add a loading spinner to the submit button"
Routing:
- workflow: oneoff-spec
- rationale: Seems simple but has decisions: spinner placement, when to show/hide, error states, accessibility. Spec ensures we don't miss edge cases.
- estimated_scope: small-medium
- estimated_files: 2-3 (component, styles, tests)
- delegation:
- parallel_subtasks:
- implementation: implementer
- tests: test-writer
- parallel_subtasks:
- next_action: Use
/pmto clarify loading states and error handling
Example 3: Standard Feature (oneoff-spec)
Request: "Add a logout button to the user dashboard"
Routing:
- workflow: oneoff-spec
- rationale: Requires UI component, event handler, API call, state management. Need to clarify placement, behavior on logout, error handling.
- estimated_scope: medium
- estimated_files: 4 (component, handler, API client, tests)
- delegation:
- parallel_subtasks:
- implementation: implementer
- tests: test-writer
- sequential_dependencies:
- spec approval must complete before implementation
- parallel_subtasks:
- next_action: Use
/pmto gather UI/UX requirements
Example 4: Large Task (Full Orchestration)
Request: "Implement real-time notifications across the application"
Routing:
- workflow: orchestrator
- rationale: Cross-cutting feature affecting multiple layers: WebSocket server, frontend client, database schema, auth middleware, notification service (8+ files, 3+ workstreams)
- estimated_scope: large
- workstreams:
- ws-1: WebSocket server infrastructure
- ws-2: Frontend notification client
- ws-3: Notification persistence and delivery
- delegation:
- parallel_subtasks:
- ws-1 implementation: implementer (worktree)
- ws-2 implementation: implementer (worktree)
- ws-3 implementation: implementer (worktree)
- per-workstream tests: test-writer (parallel)
- sequential_dependencies:
- ws-1 must complete before ws-2 (client depends on server)
- exploration_needed: true (investigate WebSocket library options)
- parallel_subtasks:
- next_action: Use
/pmto create ProblemBrief, dispatch Explore subagent for WebSocket research
Example 5: Exploration-First (Delegation for Research)
Request: "Improve performance of the search feature"
Routing:
- workflow: oneoff-spec (may escalate to orchestrator)
- rationale: Requires investigation to understand bottlenecks before planning
- estimated_scope: unknown (pending exploration)
- delegation:
- exploration_needed: true
- parallel_subtasks:
- codebase analysis: Explore subagent
- performance profiling: Explore subagent (separate)
- sequential_dependencies:
- exploration must complete before spec authoring
- next_action: Dispatch Explore subagent to profile current search implementation
Example 6: User Requests Vibe (Override)
Request: "Just add a console.log to debug this, don't need a spec"
Routing:
- workflow: oneoff-vibe
- rationale: User explicitly requested to skip spec ("don't need a spec"). Honoring user preference.
- estimated_scope: trivial
- delegation: none
- next_action: Make the change directly
Note: Without the explicit override, even a "simple" debug statement might warrant a spec if it's part of a larger investigation.
Example 7: Refactor Request (refactor workflow)
Request: "Refactor the authentication service to use the repository pattern"
Routing:
- workflow: refactor
- rationale: Explicit refactoring request with pattern migration goal. No behavior changes expected - restructuring code organization only.
- estimated_scope: medium
- estimated_files: 3-5 (service, new repository, tests)
- delegation:
- exploration_needed: true (understand current auth service structure)
- parallel_subtasks:
- codebase analysis: Explore subagent
- sequential_dependencies:
- exploration must complete before refactoring
- tests must pass before refactoring (baseline)
- tests must pass after refactoring (verification)
- next_action: Use
/refactorskill to define scope and execute
Example 8: Tech Debt Reduction (refactor workflow)
Request: "Clean up the utils folder - too much duplicated code"
Routing:
- workflow: refactor
- rationale: Tech debt reduction request focused on code consolidation. "Clean up" and "duplicated code" are refactor triggers. No feature changes.
- estimated_scope: small-medium
- estimated_files: 4-8 (multiple utils files to consolidate)
- delegation:
- exploration_needed: true (identify duplication patterns)
- parallel_subtasks:
- duplication analysis: Explore subagent
- next_action: Use
/refactorskill to identify duplications and consolidate
Example 9: Refactor with Feature (routes to oneoff-spec, NOT refactor)
Request: "Refactor the payment service and add support for crypto payments"
Routing:
- workflow: oneoff-spec
- rationale: Although request includes "refactor", it also adds new behavior (crypto payments). Behavior changes require spec workflow for proper requirements and testing. The refactor portion can be part of implementation.
- estimated_scope: medium-large
- estimated_files: 5+
- delegation:
- parallel_subtasks:
- implementation: implementer
- tests: test-writer
- parallel_subtasks:
- next_action: Use
/pmto gather crypto payment requirements, then create TaskSpec
Note: Mixed requests (refactor + feature) always route to oneoff-spec because behavior changes need formal specification.