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

.gitignore

@@ -63,3 +63,6 @@ tmp-test/
 
 # Session journals the previous telemetry plugin wrote into a project: private, never tracked.
 aidd_docs/runs/
+
+# Personal make reload agent opt-in (see scripts/reload-agents.example.json)
+scripts/reload-agents.json

AGENTS.md

@@ -28,10 +28,22 @@
 - **Don't guess** APIs, signatures, flags, or behavior - read the source or docs to confirm before relying on them.
 - **Ambiguous or expensive task:** ask one sharp question to pin down scope before building, rather than guess.
 - **Batch independent operations** in one pass, not one at a time.
-- **Fan out** independent subtasks to parallel subagents when you own the overall flow and the work is genuinely parallel.
 - **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
+
+When you own the overall flow, fan out genuinely independent subtasks to available host agents by responsibility when coordination costs less than serial work; custom agents are optional. The caller owns scope, delegation, and final acceptance.
+
+| Responsibility | Agent when installed |
+| --- | --- |
+| Answer a scoped codebase question with sources | `aidd-dev-explorer` |
+| Implement assigned work and verify it | `aidd-dev-executor` |
+| Confirm the outcome meets its acceptance criteria | `aidd-dev-validator` |
+| Review quality, coherence, and needless complexity | `aidd-dev-reviewer` |
+
+Without them, give the same brief to a general-purpose agent.
+
 ## Memory Management
 
 Project docs, memory, specs, and plans live in `aidd_docs/`.

CONTRIBUTING.md

@@ -45,7 +45,7 @@ make setup   # deps, git hooks, registers the marketplace, installs plugins into
 ## ✏️ Make your change
 
 - **Follow the [Principles](#-principles).**
-- **Test locally** — run `make reload`, restart your session(s). Test in Claude *and* one other tool (e.g. Codex).
+- **Test locally** — run `make reload`, restart your session(s). Test in Claude *and* one other tool (e.g. Codex). To load the optional agents too, see [reload opt-in](docs/SUBAGENTS.md#-update-or-remove).
 - **Commit** — `<type>(<scope>): description`, one scope per commit → [convention](aidd_docs/memory/vcs.md#commits).
 
 ## 🔀 Open a pull request

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><!--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 opt-in, per project or per user. 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, and the agents opted in by the gitignored `reload-agents.json` beside `scripts/reload-agents.example.json`; 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/review.md

@@ -0,0 +1,84 @@
+# Review: scoped sub-agents
+
+- Rounds: 5
+- 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.

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

@@ -0,0 +1,25 @@
+# Sub-agent verification
+
+Current state, 2026-10-21, merged with next. Behavior and sources are in [the agent guide](../../../../docs/SUBAGENTS.md).
+
+## Scope
+
+- **Agents:** explorer, executor, validator and reviewer ship with the CLI, outside plugins. `aidd agents install --provider --ide` writes them per project; `--scope user` writes them to the IDE's user directory (Claude Code, Codex, OpenCode). Ownership hashes guard every write; retired roles are removed when unmodified.
+- **Models:** [agent-models.json](../../../../cli/src/contexts/tools/domain/formats/agent-models.json) maps roles to `main`, `standard` and `light` profiles per provider.
+- **Main model:** opt-in with `--main`. The prior value is recorded and restored on removal; a value changed since, or TOML that cannot be edited line by line, is refused. OpenCode's root model takes no variant.
+- **Reload:** `make reload` runs `agents install --scope user` for each IDE listed in the gitignored `scripts/reload-agents.json`, before any plugin change.
+
+## Checks
+
+- **CLI:** 7,070 tests pass, one skipped. Typecheck, lint, architecture rules, knip and duplication (1.44%) pass. Bundle 733.5 KB against 742 KB.
+- **Smoke:** 140 checks pass, one remote check skipped; 34/34 leaf commands exercised.
+- **Reload:** 539 script tests pass, including reload opt-in order, skips with a reason, and refusal before plugin changes.
+- **Edge cases:** unit cases cover multi-line strings, quoted and dotted keys, nested arrays, inline comments, CRLF and a JSON BOM; integration cases cover user scope, restore on removal, retired roles and rollback of both registries.
+
+## Earlier runtime probes
+
+Native probes on 2026-10-14 and 2026-10-15 confirmed that Claude Code, Codex, OpenCode, Copilot and Cursor dispatch the four roles in fresh contexts. They predate the current agent bodies and model profiles. One delegated-versus-direct observation per task gave no general cost or speed claim.
+
+## Limits
+
+Headers and files do not prove account access or the model and effort a host applies at runtime.

cli/README.md

@@ -121,6 +121,10 @@ aidd setup --scope user --ai claude,codex,copilot --plugins none --yes
 | `aidd auth status` | Show which credential resolves, from where, at which level |
 | `aidd auth logout` | Delete the stored credential |
 
+## Agents (beta)
+
+Install optional agents per project with the [subagent guide](../docs/SUBAGENTS.md).
+
 ## Translate
 
 `aidd translate <source> --to <tool> --out <dir>` converts a framework source tree into a target-native plugin tree.

cli/aidd_docs/memory/codebase-map.md

@@ -13,6 +13,7 @@ src/
 │   │   └── infrastructure/
 │   ├── framework/    # the installation record and everything done to a project
 │   │   ├── application/
+│   │   │   ├── agents/       # opt-in native agents and file ownership
 │   │   │   ├── clean/
 │   │   │   ├── doctor/
 │   │   │   ├── flows/

cli/aidd_docs/memory/testing.md

@@ -18,6 +18,7 @@ How this package is tested: the layers, the tools, the conventions.
 ## Conventions
 
 - `tests/` mirrors `src/`; where it does not, the mirror is wrong.
+- A tool profile's tests split by feature: `tests/contexts/tools/domain/profiles/<tool>/<feature>.unit.test.ts` (`agents`, `skills`, `rules`, `commands`, `mcp`, `hooks`, `plugins`, `settings`, `content`), with the profile's own declarations in `profile.unit.test.ts`.
 - Doubles from `tests/helpers/ports/`. Substitute at the seam; never mock functional behaviour.
 - Fixtures in `tests/fixtures/`, read-only, excluded from JSON and link checks. Mutate a copy in a temp directory.
 - `.gitattributes`'s `tests/fixtures/** text eol=lf` keeps byte-for-byte comparisons (`manifest-round-trip.unit.test.ts`) passing on Windows.
@@ -34,6 +35,7 @@ How this package is tested: the layers, the tools, the conventions.
 
 - `pnpm test` runs every project; `test:unit`, `test:integration`, `test:e2e`, `test:arch` select one.
 - `pnpm smoke` drives the real binary over the command matrix, hermetically. `pnpm smoke:full` adds the remote fetch.
+- `pnpm test:e2e:agents` installs the optional agents into a throwaway project and asks each installed host (Claude Code, Codex, OpenCode, Copilot, Cursor) which agents it loaded, through the person's signed-in hosts; Cursor and Codex spend one short model turn, and a Cursor usage limit skips its case.
 - `pnpm smoke:real` reaches real host registries: [`smoke-real.md`](internal/smoke-real.md).
 - `pnpm smoke:collision` runs the real `codex` and `copilot` binaries in a throwaway HOME against a person's own install under the keys aidd uses, and checks `setup` and `clean` leave it as seeded. `smoke:real`'s unique names cannot meet that case.
 - `pnpm test:mutation:<scope>`; `mutation-scopes.json` declares each scope's globs (a leading `!` excludes) and the floor its score must hold. `tools` is split one scope per tool profile (`tools-claude`, `tools-codex`, …): a profile is a static declaration whose every mutant reruns each test that loads it, and the profiles together outlasted every other scope on a two-core runner. A weekly scheduled run replays every mutant with `--force`, so drift through a dependency an incremental run never replays is bounded to a week. `scripts/run-mutation.mjs` fails under the floor and keeps one incremental file per scope under `reports/mutation/<scope>/`; `--force` reruns every mutant. Before a run the runner prunes the incremental file to kills alone: stryker reuses a result unless the mutant's file or a test that covered it changed, so a test written after the fact never reaches a mutant recorded as survived, uncovered or static, and a scope measured 74 read 67 in CI until it did. Raise a floor to the measured score after a run; never lower one without the reason in that file.

cli/assets/agents/executor.md

@@ -0,0 +1,27 @@
+---
+name: executor
+description: Implements assigned work within defined scope. Use to write or revise code and documentation, verify the result, and repair failures against the requested outcome.
+---
+
+# Role
+
+Deliver assigned code or documentation within the agreed outcome and criteria.
+
+# Behavior
+
+- **Choose the simplest solution within owned scope**, minimizing changes; escalate material changes to scope or dependencies.
+- **Express clear intent with few words** in names, code, and documentation. Prefer removing obsolete or redundant material while preserving required behavior and useful knowledge.
+- **Verify and repair the result**; report unmet criteria and missing checks.
+- **Wait for every check or commit you started** before ending a turn.
+- **Respect file and shared-operation ownership**; return changes and evidence to the caller.
+
+# Output
+
+Return a concise result; omit empty fields.
+
+```markdown
+**Status:** <COMPLETE | INCOMPLETE | BLOCKED>
+**Changes:** <delivered behavior and paths>
+**Checks:** <what ran, on which commit, and its result>
+**Remaining:** <unfinished work or blockers, if any>
+```

cli/assets/agents/explorer.md

@@ -0,0 +1,28 @@
+---
+name: explorer
+description: Explores a codebase to answer scoped questions. Use to locate files and symbols, trace execution or dependencies, and return relevant code with an explanation before changes.
+---
+
+# Role
+
+Find the code and context that answer the caller's question.
+
+# Behavior
+
+- **Read relevant code, callers, and dependencies**; return sourced paths, symbols, patterns, or short excerpts and explain what they establish.
+- **Distinguish facts from hypotheses** and state unresolved questions. Suggest changes only when asked.
+- **Keep sources unchanged** and return findings directly to the caller.
+
+# Output
+
+Keep the answer proportional to the question; omit unused fields.
+
+```markdown
+**Answer:** <what the relevant code does or where it lives>
+
+- **<file:line or symbol>:** <relevant behavior or relationship>
+
+<Short code excerpt when it makes the answer clearer.>
+
+**Unknowns:** <what remains unresolved, if any>
+```