Host subagent allowlist
Skills stay the playbook (SKILL.md). Subagents are a process boundary: a fresh Cursor or Claude window, optional readonly, optional model class at launch. This page is the published allowlist. The machine-readable copy is skills/subagents.yaml (roles only; generate lists are derived). Thin host stubs live in agents/ (wk agents generate). Install them for the logged-in user with wk agents install (also runs on wk align . --write and after a successful wk sync --install). wk verify and wk check fail if the allowlist, docs, and stubs drift.
Waykit does not turn every agent-* role into a host agent. Cursor auto-delegation gets worse when descriptions overlap. Stack profiles never become agents.
Launch flow
The parent stays in chat. Allowlisted specialists run in a child window. IPC is the handover file. Procedure and the copy-paste Task prompt: SOPs/subagent-launch.md.
wk agents status
wk agents launch-prompt --skill agent-tdd --project my-app --linear MZW-59 --handover ~/.agents/handover/my-app/handover_spec.md --next agent-xfn
launch_specialist in EDD is an eval adapter for that host Task. Cursor and Claude do not expose that tool. On the map, stubs are subagent:* nodes with an adapts edge to their skill (Waykit map). Look them up with kit-knowledge get_entity using subagent:agent-tdd (same prefix style as skill:agent-tdd). wk ontology check fails if sync/ontology-index.json is missing Subagent after a schema bump — delete that cache and restart kit-knowledge.
Generate list
| Bucket | Skills | Why a subagent |
|---|---|---|
| Isolation | agent-debug, agent-xfn | Logs, DOM, and suite output must not fill the parent chat |
| Readonly audit | agent-review, agent-security, agent-arch-drift | Independent check; readonly: true |
| Sequential specialists | agent-spec, agent-tdd | Multi-step phase with a handover contract |
Parent only: agent-orchestrator routes and launches. It is not a generated specialist stub.
TDD: Gear 1 (domain + mocked ports) and gear 2 (thin adapter) stay one agent-tdd session. agent-adapter stays a skill: the escape hatch when gear 2 is too large, not a second TDD agent.
Skills-only mode
Default is launch (skillsOnly: false in subagents.yaml). For a cheaper parent session, set WK_SUBAGENTS=0 in the shell that starts the host, then run wk agents status so the parent sees mode: skills-only and loads the matching SKILL.md instead of a host Task. WK_SUBAGENTS=1 forces launch. The Cursor chat does not read your shell env by itself. Stubs may stay installed; this switch is routing, not uninstall.
Eval coverage: evals/edd/subagent_routing.yaml (launch) and evals/edd/subagent_routing_skills_only.yaml (parent skill). Procedure: subagent launch.
Stay skills
| Kind | Runtime |
|---|---|
lang-*, framework-*, profile-* | Skill. How to write this stack. Loaded by the specialist. |
Other agent-* roles not in the table above | Skill (copy, docs, pre-commit, grill-me, …) |
| SOPs | On demand via kit-knowledge, never copied into agent files |
Adding a role
Do not grow the generate list because a role “sounds like an agent.” Freeze this list if auto-delegation picks the wrong specialist more often than today’s skill picker. Measure that with wk eval miss-rate after promoting misses via wk eval dataset from-trace into evals/edd/subagent_routing.jsonl versus skill-picker misses in evals/suites/routing-matrix.json. Empty traces print not-enough, not a fake 0% win. If the verdict is freeze, wk agents status says freeze and wk verify fails if you add another specialist. Fix the handover before generating more stubs.
Out of this page’s scope: Copilot/Antigravity agent directories. Stubs themselves are generated into agents/. wk agents install writes only ~/.cursor/agents and ~/.claude/agents.
Related: skills taxonomy, feature lifecycle, hosts, context budget, model routing, subagent launch.