Launch host subagents
Skills stay the playbook (SKILL.md). Host subagents are a process boundary: a fresh Cursor Task or Claude subagent, optional readonly, optional model class at launch. The parent is agent-orchestrator. The contract between windows is the handover file, not the chat summary.
Allowlist and install: docs/subagents.md. Model class: model-routing.md (wk model resolve --skill <id>). Do not hardcode vendor slugs.
Parent must pass
- Linear id when playing a ticket.
- Relevant handover paths under
~/.agents/handover/<project>/. - Definition of Done for this phase.
- Next agent (role skill name).
The child writes COMPLETE or BLOCKED to the handover and returns a short summary only.
Print the Task body (do not invent it):
wk agents launch-prompt --skill agent-tdd --project my-app \
--linear MZW-59 \
--handover ~/.agents/handover/my-app/handover_spec.md \
--next agent-xfn
Cursor Task invocation
After wk agents install, launch ~/.cursor/agents/<name>.md as a Cursor Task (host subagent). The child does not inherit parent chat. Paste the launch-prompt output. Resolve the slug with wk model resolve --skill <id>. Do not paste SKILL.md into the prompt. When the Task returns, read COMPLETE or BLOCKED from ~/.agents/handover/<project>/.
Claude Code: same contract with ~/.claude/agents/<name>.md.
EDD’s launch_specialist tool is an eval adapter for this host Task. Live Cursor/Claude sessions do not call it.
Keep one MCP profile. If the specialist needs Cloudflare or PostHog, wk mcp <profile> --project, then restore wk mcp default --project. Do not stack vendor MCP onto the default profile.
Routing rules
| Situation | Launch |
|---|---|
| Spec after grilling/stories | agent-spec |
Spec handover COMPLETE, implement the slice | agent-tdd (gear 1 and gear 2 in one child) |
| XFN apply rows / browser noise | agent-xfn (own window) |
| Failed CI, live symptom, RCA | agent-debug (own window). Do not open the full lifecycle. |
| Independent PR / OWASP / hex drift check | agent-review, agent-security, or agent-arch-drift with readonly: true. Handover and diff only. BLOCKED goes back to tdd or xfn. |
| Tiny typo / one-liner | Stay in the parent. |
Do not generate or launch lang-* / framework-* / profile-* as agents. Load those skills inside the specialist.
Do not split TDD across two agents. agent-adapter stays a skill when gear 2 is too large.
Skills-only mode
Default is launch. Set WK_SUBAGENTS=0 for this session (also off / false / skills) in the shell that starts the host, then run wk agents status. Stay in the parent and load the matching SKILL.md. Set WK_SUBAGENTS=1 (also on / launch) to force launch even if skills/subagents.yaml has skillsOnly: true. Unset follows that YAML flag (false in the kit). Handovers still go to disk. Do not uninstall ~/.cursor/agents for this mode.
When skills-only is on, do not call a host Task for spec, tdd, debug, xfn, or audit.
Kill
Freeze the generate list if auto-delegation picks the wrong specialist more often than today’s skill picker. Run wk eval miss-rate after promoting misses with wk eval dataset from-trace into evals/edd/subagent_routing.jsonl and comparing to skill-picker misses in evals/suites/routing-matrix.json. No traces prints not-enough. A freeze verdict shows on wk agents status and wk verify fails if the generate list grows. Fix thin handovers before adding roles.