Work
Orchestrate end-to-end task implementation: understand the task, assess complexity, implement directly or distribute across a team, then polish the result.
Workflow
1) Parse Task
Read the task description from $ARGUMENTS.
- If
$ARGUMENTSis empty, ask the user for a task description and stop. - Extract key signals: scope (files, modules, components mentioned), action type (new feature, bug fix, refactor, migration), and any constraints.
- Note any referenced issues, PRs, or URLs for later context gathering.
2) Assess Complexity
Classify the task as simple or complex using these heuristics:
| Signal | Simple | Complex |
|---|---|---|
| File count | 1-3 files | 4+ files |
| Module span | Single module or package | Cross-module or cross-package |
| Dependency chain | No new dependencies | New packages or service integrations |
| Risk surface | Low (UI, docs, config) | High (auth, payments, data, infra) |
| Parallelism | Sequential steps only | Independent subtasks benefit from concurrency |
A task is complex when 3 or more signals fall in the complex column. When in doubt, prefer the simple path — team overhead is only justified when parallelism provides a real speedup.
- Simple — proceed to Step 3.
- Complex — proceed to Step 4.
3) Implement (Simple Path)
Execute the task directly without spawning subagents.
- Gather context: Read all relevant files. Understand existing code, tests, and conventions.
- Implement: Make the changes. Follow project conventions inferred from existing code, linters, and formatters.
- Verify: Run the narrowest useful checks:
- Formatter/linter on touched files. - Targeted tests for touched modules. - Type check when relevant. - If fast checks pass, run broader checks only when risk warrants it.
- Proceed to Step 5 (Polish).
4) Implement (Complex Path)
Distribute work across a team of subagents.
4a) Decompose
Break the task into independent subtasks. Each subtask should:
- Target a distinct set of files with minimal overlap.
- Be completable without waiting on other subtasks (no circular dependencies).
- Include clear acceptance criteria.
Avoid over-decomposition. If subtasks cannot run in parallel, prefer the simple path.
4b) Create Team and Assign
Create a team with a name derived from the task (e.g., "add-auth", "refactor-api"). Create a task for each subtask. Set up dependencies when ordering matters.
Spawn implementation agents as teammates. Assign each agent one or more tasks.
Recommended team sizing:
- 1 agent per module when modules are independent.
- Separate agent for shared utilities when consumers depend on them (utility blocks consumers).
- Dedicated agent for tests if test volume is high.
4c) Coordinate
Monitor progress. As agents complete tasks:
- Review output for integration issues.
- Resolve cross-agent conflicts (merge overlaps, API mismatches).
- Assign follow-up tasks if gaps emerge.
After all tasks complete:
- Run integration verification: full test suite, type check, lint.
- Fix any integration issues directly — do not re-spawn agents for small fixes.
- Shut down teammates.
- Proceed to Step 5 (Polish).
5) Polish
Invoke /code-polish to simplify and review all session-modified files.
Wait for completion. If it reports residual risks or stop conditions, relay them to the user.
This step is mandatory — always run it, even if the implementation seems clean.
Error Handling
| Error | Response |
|---|---|
Empty $ARGUMENTS | Ask for a task description and stop |
| Verification failures after impl | Attempt to fix; if unfixable, report to user before polishing |
| Team agent fails or times out | Reclaim the task and complete it directly |
code-polish reports stop condition | Relay to user with context |
Stop Conditions
Stop and ask for direction when:
- The task description is ambiguous and multiple interpretations exist.
- Implementation requires changing public APIs or breaking contracts not mentioned in the task.
- The task scope grows beyond the original description during implementation.
- External dependencies (APIs, services, packages) are unavailable or broken.
- A CRITICAL security concern is discovered in existing code adjacent to the task.