Summary

PR #652 migrated sub-agent definitions from JSON+MD sidecar pairs to single .md files with YAML frontmatter, added an optional Context parameter to spawn_agent, and enriched the [available-subagents] discovery context layer to include per-agent description, tools, and an example call. None of that was reflected in the runbook — anyone following the existing "Defining subagents" section would write a .json file the loader rejects.

This PR rewrites docs/runbooks/subagents.md end to end and minimally updates one stale entry in IMPLEMENTATION_PLAN.md.

What changed in the runbook

• Discovery section now shows the enriched per-agent block (description + tools + timeout + a how-to-delegate block with the context field example) instead of the old one-line form.
• Invocation section documents all three spawn_agent arguments (agent, task, context) with one null-context and one populated-context example. Clarifies that Context is prefixed onto the subagent's first user message as a Context:/Task: block, and that the agent's system prompt stays verbatim from disk (not mutated by runtime context).
• Defining subagents section replaces the JSON schema + companion-file walkthrough with a single markdown-with-frontmatter template. Documents every frontmatter field with required/default columns: name, description, tools, modelRole, timeoutSeconds, visibility (accepts both hyphenated user-facing and PascalCase UserFacing), emitStructuredFindings. New loader behavior (fail loud) subsection enumerates every rejection reason the scanner can log, matching the contract pinned by test(subagents): consolidate anemic loader and actor tests #654's consolidated test.
• Creating a custom agent walkthrough now writes a single .md file with frontmatter instead of a JSON+MD pair.
• Limitations gains an entry noting that per-agent model selection is not yet supported and is blocked on the multi-model provider follow-on (feat(providers): concurrent multi-model / multi-provider architecture for per-role and per-agent routing #648).

IMPLEMENTATION_PLAN.md fix

Line 969 still listed the JSON file format in the "Subagent Roadmap" section. Updated minimally to reference the new format and cite both #226 (original disk-based design) and #652 (migration to frontmatter). The rest of the roadmap section is left alone — retconning historical entries would make the document less accurate.

What is NOT changed

• RELEASE_NOTES.md references to ~/.netclaw/agents/<name>.json are historical — they accurately describe what shipped at feat(subagents): definition registry, spawn_agent tool, and file-based agents #226 and shouldn't be retconned.
• The broader "Subagent Roadmap" items in IMPLEMENTATION_PLAN.md (lines 972-985) that have also shipped (spawn_agent tool, discovery context layer) — that's housekeeping outside the scope of "fix stale format references."

Test plan

Documentation-only change. No code touched, no tests to run. Existing CI (test + slopwatch + Docker build + smoke sandbox) will confirm nothing else regressed.

Related

• Builds on feat(subagents): single-file markdown format with contextual prompt #652 (single-file format + context parameter + enriched discovery)
• References feat(subagents): definition registry, spawn_agent tool, and file-based agents #226, feat(providers): concurrent multi-model / multi-provider architecture for per-role and per-agent routing #648 in the updated content
• Sits on top of test(subagents): consolidate anemic loader and actor tests #654 (test consolidation, currently queued to auto-merge) — no file conflicts, can land in either order