design(bin): research had a fan-out design its allowed-tools never permitted #116

New Issue

Claude · 2026-08-30T14:58:30Z

Claude commented

2026-08-30 14:58:30 +00:00

plugins/bin/.apm/skills/research/SKILL.md declared allowed-tools: WebSearch, WebFetch, Read, Write, mcp__context7__resolve-library-id, mcp__context7__query-docs while steps 4 and 5 instructed the agent to "spawn one subagent per URL". No tool in that list spawns anything.

Because WebFetch is granted the skill never hard-failed — it silently degraded to serial orchestrator fetches. Three things then quietly stopped meaning anything:

The Gotcha "subagents read and summarise; the orchestrator writes every file" became vacuous.
Step 5's "roughly ten additional pages" cap bounded nothing, because there were no branches to cap.
Step 4's "in parallel" was simply false, so a run budgeted as parallel ran serial with no signal to the user that the plan had changed.

This predates the ADR-0020 retrofit — it is identical in the pre-retrofit file. The #99 wave-3 pass resolved it conservatively, rewriting steps 4 and 5 as honest serial WebFetch reads with the page cap as a real budget, and deleting the now-vacuous Gotcha. No tool was added, because tool names differ across this package's three targets (claude, copilot, codex) and guessing one is worse than an honest serial procedure.

Why this still needs a decision

The fan-out was not only about concurrency. It was summarisation before return: each subagent reduced a page to notes, and only the notes came back. Serially, up to fifteen fetched documentation pages accumulate raw in the orchestrator's own context — and that same context then has to hold all of them while writing seven topic files. That is precisely the failure the fan-out existed to prevent.

The retrofit mitigated it as far as prose can: steps 4 and 5 now instruct reducing each page to notes before the next fetch. That is a real mitigation, not a fix — it depends on the agent's compliance rather than on context isolation.

What is missing

Confirmed while resolving this: no skill in the 39-skill corpus declares a subagent-spawning tool. There is no house precedent to copy and no established answer to:

What is the correct tool name to grant, per target? This repo compiles to claude, copilot, and codex, and allowed-tools is a flat list with no per-target form.
Is skill-spawns-subagent a pattern this repo wants at all? The alternative is that fan-out belongs to an agent (plugins/*/.apm/agents/) which delegates to skills, matching the delegation-discipline split in CONTEXT.md. Under that reading research's fan-out was always misplaced and the serial rewrite is the correct end state, not a stopgap.

Option 2 looks more likely to be right, which is another reason not to have guessed a tool name.

Files

plugins/bin/.apm/skills/research/SKILL.md — steps 4-5, now serial
CONTEXT.md — "Delegation discipline", the agent/skill split this turns on

Found during #99 wave 3. See also #115 (a dead flag in a bundled validator) — same shape: a declared capability that never did anything, invisible because the failure was silent.

`plugins/bin/.apm/skills/research/SKILL.md` declared `allowed-tools: WebSearch, WebFetch, Read, Write, mcp__context7__resolve-library-id, mcp__context7__query-docs` while steps 4 and 5 instructed the agent to "spawn one subagent per URL". No tool in that list spawns anything. Because `WebFetch` *is* granted the skill never hard-failed — it silently degraded to serial orchestrator fetches. Three things then quietly stopped meaning anything: - The Gotcha "subagents read and summarise; the orchestrator writes every file" became vacuous. - Step 5's "roughly ten additional pages" cap bounded nothing, because there were no branches to cap. - Step 4's "in parallel" was simply false, so a run budgeted as parallel ran serial with no signal to the user that the plan had changed. This predates the ADR-0020 retrofit — it is identical in the pre-retrofit file. The #99 wave-3 pass resolved it **conservatively**, rewriting steps 4 and 5 as honest serial `WebFetch` reads with the page cap as a real budget, and deleting the now-vacuous Gotcha. No tool was added, because tool names differ across this package's three targets (`claude`, `copilot`, `codex`) and guessing one is worse than an honest serial procedure. ## Why this still needs a decision The fan-out was not only about concurrency. It was **summarisation before return**: each subagent reduced a page to notes, and only the notes came back. Serially, up to fifteen fetched documentation pages accumulate raw in the orchestrator's own context — and that same context then has to hold all of them while writing seven topic files. That is precisely the failure the fan-out existed to prevent. The retrofit mitigated it as far as prose can: steps 4 and 5 now instruct reducing each page to notes before the next fetch. That is a real mitigation, not a fix — it depends on the agent's compliance rather than on context isolation. ## What is missing Confirmed while resolving this: **no skill in the 39-skill corpus declares a subagent-spawning tool.** There is no house precedent to copy and no established answer to: 1. What is the correct tool name to grant, per target? This repo compiles to `claude`, `copilot`, and `codex`, and `allowed-tools` is a flat list with no per-target form. 2. Is skill-spawns-subagent a pattern this repo wants at all? The alternative is that fan-out belongs to an **agent** (`plugins/*/.apm/agents/`) which delegates to skills, matching the delegation-discipline split in `CONTEXT.md`. Under that reading `research`'s fan-out was always misplaced and the serial rewrite is the correct end state, not a stopgap. Option 2 looks more likely to be right, which is another reason not to have guessed a tool name. ## Files - `plugins/bin/.apm/skills/research/SKILL.md` — steps 4-5, now serial - `CONTEXT.md` — "Delegation discipline", the agent/skill split this turns on ## Related Found during #99 wave 3. See also #115 (a dead flag in a bundled validator) — same shape: a declared capability that never did anything, invisible because the failure was silent.

Claude referenced this issue

2026-08-30 15:12:26 +00:00

refactor(skills): retrofit the 39 skills to the ADR-0020 context contract #99

Claude added the Kind/Enhancement

labels 2026-08-30 15:58:54 +00:00

Claude added this to the Skills & Agents milestone 2026-08-30 15:58:59 +00:00