Merge branch 'main' into feat/121-research-doc-grammar

docs/adr/0027-research-fan-out-restored-and-its-tool-list-kept.md

@@ -0,0 +1,47 @@
+# `research` gets its fan-out back and keeps its tool list; a body must not disclaim spawning
+
+**Status:** Accepted (2026-09-21)
+
+`plugins/bin/.apm/skills/research/SKILL.md` once told the agent to "spawn one subagent per URL"
+while its `allowed-tools` listed nothing that spawns. `WebFetch` was listed, so nothing hard-failed:
+the skill degraded to serial fetches in the orchestrator's own context, and the "in parallel"
+wording, the page cap and the "subagents summarise, orchestrator writes" gotcha quietly stopped
+meaning anything. The #99 retrofit rewrote steps 4 and 5 as serial reads and said in the text that
+no subagent tool was granted (#116).
+
+**What #116 did not establish.** It read the missing tool as the cause. The repo's own sources
+describe `allowed-tools` as pre-approval, not restriction: `skill-author/references/create.md:113`
+("space-separated pre-approved tools; reduces permission prompts"), the agentskills.io
+specification, and the Copilot plugin docs. On that reading an unlisted spawn tool would prompt, not
+fail. What Claude Code, Copilot and Codex actually do with an unlisted tool is **not verified
+here**, and neither is whether omitting the field grants anything. What is documented is that the
+serial behaviour followed the step text, which told the agent to go serial.
+
+**Decision.** `research` keeps its `allowed-tools` list and gets its parallel fan-out back in steps
+4 and 5, with the "subagents read and summarise; the orchestrator writes every file" gotcha
+restored (version 1.0.1 → 1.0.2). A skill body that instructs spawning must not be paired with text
+saying spawning is unavailable. Step 4 carries a serial fallback for a target with no spawn tool, so
+an unavailable spawn degrades visibly instead of silently.
+
+The spawn tool is **not** added to the list. Its name is sourced for Claude Code (`Agent`) only; the
+Copilot and Codex names are not known. On Claude Code, spawns therefore prompt instead of being
+pre-approved. Add the tool once its name is sourced for each target.
+
+**Corpus facts, with limits.** `write-docs`, `improve-codebase-architecture` and `forge` all omit
+`allowed-tools` and instruct spawning subagents — `forge` from `references/author-routes.md` and
+`references/version-bump.md`, not from its `SKILL.md`. That shows they spawn, not that a run
+succeeded. `skill-author/SKILL.md:24` forbids spawning a subagent to recheck one's own work, which
+is a different question and unaffected here. `CONTEXT.md` says a plugin-scope agent delegates to
+skills because it cannot disclose to itself; nothing there bans a skill from delegating.
+
+**The security cost is real and not mitigated.** "The orchestrator alone writes files" is prose,
+not enforcement. The subagents read untrusted web pages, and nothing restricts what tools they
+hold. Not done, by decision: an instruction to treat fetched page content as data, a cap on the
+number of subagents (user-supplied URLs are uncapped, and the step 5 page cap bounds less once
+reads run in parallel), and read-only subagents. `docs/research/ai-coding-factory/
+ai-coding-factory-principles.md:53` recommends applying `allowed-tools` restrictions, which is why
+the list was kept.
+
+Rejected: dropping `allowed-tools` on the premise that it blocked spawning (unsupported by the
+repo's own sources, and it widens the tool surface for nothing), and banning spawning in skills
+(three skills instruct it, and `CONTEXT.md` does not forbid it).