feat(framework): support scoped sub-agents across five hosts

AGENTS.md

@@ -32,6 +32,10 @@
 - **Before adding any instruction, finding, or rule, check whether an existing one already covers or contradicts it.** If so, don't add a parallel: delete it, merge it into the stronger one, or rewrite with explicit scope and priority.
 - **Name by intention, not mechanism:** describe the goal or responsibility, not the tool or file format.
 
+## Agents
+
+Use available host agents by responsibility when useful; custom agents are optional. The caller owns scope, delegation, and final acceptance.
+
 ## Memory Management
 
 Project docs, memory, specs, and plans live in `aidd_docs/`.

Makefile

@@ -1,5 +1,3 @@
-PLUGIN ?= all
-
 .DEFAULT_GOAL := help
 .PHONY: help setup doctor check reload
 
@@ -17,5 +15,6 @@ doctor: ## Check the local toolchain
 check: ## Run the pre-commit checks
 	pnpm exec lefthook run pre-commit
 
-reload: ## Dev: reload this checkout into Claude, Codex, and OpenCode (PLUGIN="aidd-refine aidd-pm", default all)
-	scripts/dev-sync.sh $(PLUGIN)
+reload: ## Dev: reload all plugins into Claude, Codex, OpenCode, Copilot, and Cursor
+	pnpm --dir cli build
+	scripts/dev-sync.sh

README.md

@@ -11,7 +11,7 @@ Unify **engineering teams** around **standardized workflows** and **shared best
 🧱 **IDE agnostic** · 🏗️ **Legacy systems** · 🌱 **Token-optimized** · 🇫🇷 **Made in France**
 
 <p>
-  <!--counts:start--><kbd>9 plugins</kbd> · <kbd>51 skills</kbd> · <kbd>2 agents</kbd><!--counts:end-->
+  <!--counts:start--><kbd>9 plugins</kbd> · <kbd>51 skills</kbd> · <kbd>0 agents</kbd><!--counts:end-->
 </p>
 
 [![Open Source](https://img.shields.io/badge/Open_Source-Yes-yellow?logo=open-source-initiative&logoColor=white)](https://opensource.org/)
@@ -26,7 +26,7 @@ Unify **engineering teams** around **standardized workflows** and **shared best
 
 ---
 
-The **AI-Driven Dev Framework** installs a working SDLC (Software Development Life Cycle) into your AI coding tool — **skills, agents, commands, rules** — that turns a rough idea into a reviewed, shipped pull request:
+The **AI-Driven Dev Framework** installs a working SDLC (Software Development Life Cycle) into your AI coding tool — **skills, commands, rules** — that turns a rough idea into a reviewed, shipped pull request:
 
 ```text
 /aidd-orchestrator:01-sdlc "add rate limiting to the /login endpoint"
@@ -185,6 +185,10 @@ codex plugin add aidd-context@aidd-framework   # per plugin
 
 </details>
 
+### Optional subagents (beta)
+
+Custom agents are a separate, project-local opt-in. Plugins work without them. See the [subagent guide](docs/SUBAGENTS.md) for installation, a native trial, and removal by IDE.
+
 ## 🚀 Quick start
 
 Three ways in — pick one:

aidd_docs/memory/deployment.md

@@ -56,6 +56,10 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 - `build-per-tool` builds the CLI from this run's own checkout (`cd cli && pnpm install && pnpm build`, then `node cli/dist/cli.js translate`) rather than pinning a published version — no version to bump, and nothing can go stale the way the old `@ai-driven-dev/cli@5.1.1 framework build` pin did once `framework build` was replaced by `translate`.
 
+## Local reload
+
+`make reload` syncs all plugins and generic delegation guidance to installed hosts; details in `scripts/dev-sync.sh`.
+
 ## Monitoring
 
 None. Failures surface as a red run; `back-merge.yml` opens a tracking issue when it cannot push, so drift is never silent.

aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json

@@ -0,0 +1,72 @@
+{
+  "date": "2026-10-15",
+  "host": "Claude Code 2.1.300",
+  "parent": {
+    "model": "opus",
+    "effort_requested": "low"
+  },
+  "child": {
+    "model": "haiku",
+    "effort_requested": "low"
+  },
+  "delivery": "Generated flat agents in disposable projects, with fresh native Agent children.",
+  "measurement": "Native CLI JSON modelUsage summed across parent and child: input, output, cache-read and cache-write. One observation per retained case, with differing cache state. Host list-price estimates, not billing. Values captured from process output; temporary fixtures were subsequently swept.",
+  "earlier_attempt": "One earlier implementation pair used Bash(node *) permissions. The child authored valid code but could not run checks. The independent check passed; both modes were rerun with the same Bash permission in isolated fixtures. Earlier attempt costs and timings are excluded.",
+  "cases": [
+    {
+      "task": "exploration",
+      "mode": "direct",
+      "session": "42f186ac-3d4d-4986-8421-89c79c651119",
+      "wall_ms": 25997,
+      "total_tokens_including_cache": 136486,
+      "host_list_cost_usd": 0.2386296,
+      "models": [
+        "claude-opus-5-5"
+      ],
+      "quality": "Correct five-file trace, threshold 5000 inclusive, tax 700 bps; no fixture edits.",
+      "task_retries": 0
+    },
+    {
+      "task": "exploration",
+      "mode": "delegated",
+      "session": "42fd2da4-d84f-47dc-8843-cdcb1e997b92",
+      "wall_ms": 29960,
+      "total_tokens_including_cache": 183951,
+      "host_list_cost_usd": 0.2129891,
+      "models": [
+        "claude-opus-5-5",
+        "claude-haiku-5-5"
+      ],
+      "quality": "Same correct trace and cited values; no fixture edits.",
+      "task_retries": 0
+    },
+    {
+      "task": "implementation",
+      "mode": "direct",
+      "session": "f9056995-d39b-4b09-b890-d1dbdded8b56",
+      "wall_ms": 21064,
+      "total_tokens_including_cache": 136126,
+      "host_list_cost_usd": 0.2080506,
+      "models": [
+        "claude-opus-5-5"
+      ],
+      "quality": "Eight modules pass 32 lookup cases plus checkout; only assigned new files.",
+      "task_retries": 0
+    },
+    {
+      "task": "implementation",
+      "mode": "delegated",
+      "session": "08903722-ab01-45dd-9799-f9a8ff7209e5",
+      "wall_ms": 29374,
+      "total_tokens_including_cache": 188423,
+      "host_list_cost_usd": 0.18985041,
+      "models": [
+        "claude-opus-5-5",
+        "claude-haiku-5-5"
+      ],
+      "quality": "Same independent checks pass; only assigned new files.",
+      "task_retries": 0
+    }
+  ],
+  "token_breakdown": "Totals were captured from native modelUsage categories. The separate category counts were not retained after temporary fixture cleanup; repeat the documented procedure before a cache-normalized decision."
+}

aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md

@@ -0,0 +1,84 @@
+# Review: scoped sub-agents
+
+- Rounds: 4
+- Started: 2026-10-15
+
+## Round 1 · r-1fd6
+
+- Date: 2026-10-15
+- By: alexsoyes
+- Diff: `origin/next...513d323c0dcb431aa936e56bf4be16945e39ec57`
+- Axes: code, relevancy
+- Verdict: changes-requested
+- Score: not scored
+
+### Findings
+
+- `plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md:49` : Delegated delivery sends the required final journey into Finalize, whose first step runs plan validation again (`02-implement/actions/03-finalize.md:13`). The journey is therefore no longer last → perform integrated validation before that journey and mark completion after it passes; major, fit
+- `plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md:25` : The changed contract requires canonical recipe addresses, while the copied scaffold still prescribes capability discovery for cross-plugin recipes (`assets/agent-template.md:18`; `actions/02-write-agent.md:15` copies it) → align the scaffold with the contract; major, architecture
+- `plugins/aidd-dev/skills/02-implement/actions/02-execute.md:17` : Missing dependencies demand replanning, while line 15 gives undeclared dependencies a serial fallback → distinguish absent declarations from unresolved referenced prerequisites; minor, error-handling
+- `docs/ARCHITECTURE.md:145` : Rewriting general cross-plugin provider discovery is unnecessary for adding sub-agents; agent permission addressing already has its own row → retain the existing provider rule; minor, fit
+
+## Round 2 · r-7c2a
+
+- Date: 2026-10-15
+- By: alexsoyes
+- Diff: `origin/next...513d323c0dcb431aa936e56bf4be16945e39ec57` plus the working tree
+- Axes: code, relevancy
+- Verdict: changes-requested
+- Score: not scored
+
+### Findings
+
+- `plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md:7` : The local correction makes every executor stop after Execute, including whole-plan executors, while the implementation router still instructs whole-plan calls to run Prepare, Execute and Finalize (`02-implement/SKILL.md:26`). The caller must override that routing and resume inside another action → preserve the normal whole-plan route and keep shared integration/finalization ownership specific to delegated phases; major, architecture
+- `plugins/aidd-dev/skills/02-implement/actions/02-execute.md:16` : Distinct checkouts/Git indexes are mandatory for parallel execution even when workers own disjoint files and leave Git operations to the caller → require independent writes and validation resources; require separate indexes only when workers also perform Git operations; minor, fit
+- `plugins/aidd-dev/agents/validator.md:19` : A two-sentence maximum can hide distinct failures or verification blockers; the requested concise verdict does not need a fixed sentence count → retain one verdict and concise decisive evidence without the numeric cap; minor, fit
+
+
+## Round 3 · r-983d
+
+- Date: 2026-10-15
+- By: independent reviewer for CLI; caller for workflow and scope
+- Diff: final working candidate
+- Axes: code, relevancy
+- Verdict: approve
+- Score: not scored
+
+### Resolved
+
+- **Workflow:** whole-plan execution retains its normal route. Assigned phases return for integration and one finalization; the required journey runs last before completion. The native whole-plan probe confirms that order.
+- **Boundaries:** uncertain dependencies run serially; separate Git indexes are required only when workers perform Git operations. Validator retains one concise verdict without an arbitrary sentence cap. The template describes capabilities rather than ordered steps.
+- **Native discovery:** independent rereview confirms the four original CLI findings are resolved: Copilot catalogue/cache paths, Claude activation, Copilot personal precedence and native configuration homes. The generated-catalogue regression also covers `metadata.pluginRoot`.
+- **Reload safety:** an empty Claude cache glob now reaches the existing missing-install-path error. Regression fixtures run inside their temporary home; both cases failed before correction and pass afterward.
+- **Evidence:** real five-host resolution succeeds without configuration writes. Ambiguous Copilot cross-tool settings fail actionably; higher-scope overrides resolve them. Effective runtime remains unknown until native traces establish it.
+- **Scope:** unrelated cross-plugin provider wording is restored. Gather, wireframe and generic skill generation remain unchanged against `next`; Batch drops the mandatory refine pipeline that exceeded a bounded executor's responsibility.
+
+No consequential new findings in the scoped rereview. Full test results and native limitations are recorded in [verification.md](verification.md).
+
+
+## Round 4 · r-ci
+
+- Date: 2026-10-15
+- By: independent mutation reviewer; caller for verification
+- Diff: CI follow-up after `6b5f5f58`
+- Axes: verification, relevancy
+- Verdict: approve local corrections
+- Score: not scored
+
+- **CI coverage:** register the new smoke command, require the four current roles in the real Kilo probe, and serialize Windows fixture paths correctly.
+- **False-positive assertion:** replace the malformed-error assertion that accepted an undefined rejection with an actual error-message check.
+- **Native boundaries:** add 15 meaningful cases in existing profile tests. Keep equivalent object serialization and unchanged baseline metadata out of scope.
+- **Results:** full mutation scopes pass at Cursor 97.4% / floor 97 and OpenCode 95.0% / floor 94. No production or threshold changes in these corrections.
+
+## Round 5 · native model configuration
+
+- Date: 2026-10-15
+- By: independent reviewer
+- Diff: replacement of runtime resolution with CLI-installed native headers
+- Axes: code, relevancy
+- Verdict: no actionable findings
+- Score: not scored
+
+- **Configuration:** one CLI JSON owns provider defaults, native fields and the Copilot alias. Explicit native choices survive; defaults stay scoped to the four AIDD roles.
+- **Simplicity:** resolver machinery and workflow dependencies are removed. Agent behavior is limited to three capabilities per role.
+- **Evidence:** 6,499 CLI tests and 498 script tests pass, including nine built-CLI header cases. Existing Codex/Cursor plugin limitations remain explicit; effective runtime selection is not claimed from generated files.