From bd2100866a5d8bac3f663793797388199c46e39d Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 12:28:15 +0800
Subject: [PATCH 01/73] feat(aidd-dev): record phase dependencies in plans

Expose prerequisites before introducing parallel execution and preserve ordering when independence is uncertain.

Refs #983
---
 .../skills/01-plan/actions/04-plan.md         | 30 +++++++++++++------
 .../skills/01-plan/assets/plan-template.md    | 10 ++++---
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
index 0803da0ff..b431aae05 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
@@ -13,6 +13,10 @@ A feature folder, always at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slu
 ## Process
 
 1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many.
+   - Prefer independent phases without splitting inseparable work.
+   - Identify prerequisites from each phase's file projection, shared contracts, and validation resources.
+   - Order phases that need another phase's output or would interfere through shared file changes or mutable validation resources.
+   - Preserve ordering when independence cannot be established.
 2. **Folder.** Reuse the feature folder the source already lives in, or create one. When creating one and `01-gather`'s own source reference names a backlog item — a ticket id or URL, or a file path naming its Markdown artefact, never raw text — with no `backlog-link.json` there yet, declare it the same way the skill that writes a spec does:
 
    ```json
@@ -24,16 +28,24 @@ A feature folder, always at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slu
    ```
 
    `backlog` is the one field, on whatever support the item lives - a forge reference or a project-relative Markdown path, never both. When the source names none, write nothing. When `backlog-link.json` already exists, leave it untouched - it is correctable by hand, and a later run must never overwrite a correction.
-3. **Fill.** Fill the plan and each phase from their templates, following the inline contracts. Slice the projection across the phases.
+3. **Fill.** Fill the plan and each phase from their templates, following the inline contracts, and record prerequisites in the phase table.
+   - Slice the projection across the phases.
 4. **Show.** Display the written paths.
-5. **Review.** Score the complete plan and its phases from 0 to 10, with ✓ reasons and ✗ risks. In interactive mode, show them and revise until approved. Under an autonomous orchestrator, revise against the source without waiting for approval; ask only when a product decision cannot be resolved from the source. The score is never written to the plan.
+5. **Review.** Check the declared dependencies against the phase scopes, then score the complete plan and its phases from 0 to 10, with ✓ reasons and ✗ risks.
+   - In interactive mode, show them and revise until approved.
+   - Under an autonomous orchestrator, revise against the source without waiting for approval; ask only when a product decision cannot be resolved from the source.
+   - Never write the score to the plan.
 
 ## Test
 
-- `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/plan.md` exists with one `phase-<n>.md` per phase next to it.
-- Every written file satisfies its template's inline contract.
-- No `{...}` placeholder is left in any written file.
-- The phase projection slices together cover the modify, create, and delete lists.
-- A confidence score was reported and written to no file.
-- An autonomous run waits only for a product decision that the source cannot resolve.
-- A newly created folder whose source names a ticket carries a `backlog-link.json` naming it; reusing an existing folder never overwrites one already there.
+| Case | Pass |
+| --- | --- |
+| The plan is written | The feature folder holds `plan.md` and one `phase-<n>.md` per phase. |
+| Written files are read back | Each satisfies its template's inline contract with no `{...}` placeholder left. |
+| Phase projections are combined | They cover the modify, create, and delete lists. |
+| Dependencies are reviewed | Every prerequisite names an existing earlier phase; no phase depends on itself. |
+| Phases share a required output, conflicting file changes, or mutable validation resources | Their ordering is recorded in the phase table. |
+| Phase independence is uncertain | The plan preserves ordering. |
+| The plan is scored | A confidence score was reported and written to no file. |
+| The run is autonomous | It waits only for a product decision that the source cannot resolve. |
+| A new folder's source names a ticket | `backlog-link.json` names it; reusing a folder never overwrites an existing link. |
diff --git a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md
index 79301f70f..4321609d5 100644
--- a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md
+++ b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md
@@ -16,10 +16,12 @@ status: pending
 
 ## Phases
 
-| #   | Phase        | File                         |
-| --- | ------------ | ---------------------------- |
-| 1   | {phase-name} | [`phase-1.md`](./phase-1.md) |
-| 2   | {phase-name} | [`phase-2.md`](./phase-2.md) |
+<!-- Depends on lists earlier phase numbers, or none when no prerequisite exists. -->
+
+| #   | Phase        | File                         | Depends on |
+| --- | ------------ | ---------------------------- | ---------- |
+| 1   | {phase-name} | [`phase-1.md`](./phase-1.md) | {none} |
+| 2   | {phase-name} | [`phase-2.md`](./phase-2.md) | {phase numbers or none} |
 
 ## Resources
 

From 009e5ed1bdde9bf82b8cc677ef6976ab0f6abc9e Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 12:29:28 +0800
Subject: [PATCH 02/73] fix(framework): reload nested opencode skills

Handle current nested output and legacy flat output without reporting success when selected skills are missing. Preserve unrelated plugins during refresh.

Refs #983
---
 scripts/__tests__/dev-sync.test.js | 80 ++++++++++++++++++++++--------
 scripts/dev-sync.sh                | 17 +++++--
 2 files changed, 74 insertions(+), 23 deletions(-)

diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 01a42e0ea..9c37bbf01 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -30,6 +30,7 @@ function runSync(fakeBin, home, args = ["all"]) {
       PATH: [fakeBin, BASE_PATH].join(delimiter),
       HOME: home,
       BUILD: join(home, "build"),
+      OPENCODE_SKILLS: join(home, ".config/opencode/skills"),
     },
     encoding: "utf8",
   });
@@ -53,33 +54,72 @@ test("managed OpenCode reload uses the fixed-purpose helper without a local buil
   }
 });
 
-test("local OpenCode reload installs only the selected plugin skills globally", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-local-"));
+for (const layout of ["flat", "nested"]) {
+  test(`local OpenCode reload refreshes only the selected plugin using ${layout} output`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-local-"));
+    try {
+      const fakeBin = join(root, "bin");
+      const home = join(root, "home");
+      mkdirSync(fakeBin);
+      mkdirSync(home);
+      mkdirSync(join(home, ".config/opencode/skills/aidd-dev-stale"), { recursive: true });
+      writeFileSync(join(home, ".config/opencode/skills/aidd-dev-stale/SKILL.md"), "stale\n");
+      mkdirSync(join(home, ".config/opencode/skills/aidd-dev/removed"), { recursive: true });
+      writeFileSync(join(home, ".config/opencode/skills/aidd-dev/removed/SKILL.md"), "stale\n");
+      mkdirSync(join(home, ".config/opencode/skills/aidd-dev/01-plan"), { recursive: true });
+      writeFileSync(join(home, ".config/opencode/skills/aidd-dev/01-plan/SKILL.md"), "old\n");
+      const unrelated = join(home, ".config/opencode/skills/aidd-pm/03-prd/SKILL.md");
+      mkdirSync(join(home, ".config/opencode/skills/aidd-pm/03-prd"), { recursive: true });
+      writeFileSync(unrelated, "keep\n");
+      executable(join(fakeBin, "opencode"), "exit 0");
+      const skillName = layout === "nested" ? "aidd-dev/01-plan" : "aidd-dev-01-plan";
+      executable(
+        join(fakeBin, "npx"),
+        String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--out" ]; then shift; out=$1; fi
+  shift
+done
+skill="$out/.opencode/skills/${skillName}"
+mkdir -p "$skill/actions" "$skill/assets"
+printf '%s\n' '---' 'name: aidd-dev-01-plan' 'description: test' '---' > "$skill/SKILL.md"
+printf '%s\n' 'updated action' > "$skill/actions/04-plan.md"
+printf '%s\n' 'updated template' > "$skill/assets/plan-template.md"`,
+      );
+
+      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      assert.equal(result.status, 0, result.stderr);
+      const installed = join(home, ".config/opencode/skills", skillName);
+      assert.match(readFileSync(join(installed, "SKILL.md"), "utf8"), /name: aidd-dev-01-plan/);
+      assert.equal(readFileSync(join(installed, "actions/04-plan.md"), "utf8"), "updated action\n");
+      assert.equal(readFileSync(join(installed, "assets/plan-template.md"), "utf8"), "updated template\n");
+      assert.equal(existsSync(join(home, ".config/opencode/skills/aidd-dev-stale")), false);
+      assert.equal(existsSync(join(home, ".config/opencode/skills/aidd-dev/removed")), false);
+      assert.equal(readFileSync(unrelated, "utf8"), "keep\n");
+      assert.match(result.stdout, /install opencode\s+skills:ok/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+test("local OpenCode reload rejects missing selected skills before removing installed ones", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-missing-"));
   try {
     const fakeBin = join(root, "bin");
     const home = join(root, "home");
     mkdirSync(fakeBin);
-    mkdirSync(home);
-    mkdirSync(join(home, ".config/opencode/skills/aidd-dev-stale"), { recursive: true });
-    writeFileSync(join(home, ".config/opencode/skills/aidd-dev-stale/SKILL.md"), "stale\n");
+    const installed = join(home, ".config/opencode/skills/aidd-dev-01-plan/SKILL.md");
+    mkdirSync(join(home, ".config/opencode/skills/aidd-dev-01-plan"), { recursive: true });
+    writeFileSync(installed, "keep\n");
     executable(join(fakeBin, "opencode"), "exit 0");
-    executable(
-      join(fakeBin, "npx"),
-      String.raw`out=""
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "--out" ]; then shift; out=$1; fi
-  shift
-done
-mkdir -p "$out/.opencode/skills/aidd-dev-01-plan"
-printf '%s\n' '---' 'name: aidd-dev-01-plan' 'description: test' '---' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"`,
-    );
+    executable(join(fakeBin, "npx"), "exit 0");
 
     const result = runSync(fakeBin, home, ["aidd-dev"]);
-    assert.equal(result.status, 0, result.stderr);
-    const installed = join(home, ".config/opencode/skills/aidd-dev-01-plan/SKILL.md");
-    assert.match(readFileSync(installed, "utf8"), /name: aidd-dev-01-plan/);
-    assert.equal(existsSync(join(home, ".config/opencode/skills/aidd-dev-stale")), false);
-    assert.match(result.stdout, /install opencode\s+skills:ok/);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /no built OpenCode skills for aidd-dev/);
+    assert.doesNotMatch(result.stdout, /skills:ok/);
+    assert.equal(readFileSync(installed, "utf8"), "keep\n");
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 29cb7d18c..750feb4f8 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -38,12 +38,23 @@ build_tool() {
 
 sync_opencode_skills() {
   local name source skill destination
+  local -a skills
   mkdir -p "$OPENCODE_SKILLS"
+  source="$BUILD/opencode/.opencode/skills"
   for name in "$@"; do
-    source="$BUILD/opencode/.opencode/skills"
+    skills=("$source/$name/"*/ "$source/$name-"*/)
+    if [ "${#skills[@]}" -eq 0 ]; then
+      echo "no built OpenCode skills for $name" >&2
+      return 1
+    fi
+    rm -rf -- "$OPENCODE_SKILLS/$name"
     find "$OPENCODE_SKILLS" -mindepth 1 -maxdepth 1 -type d -name "$name-*" -exec rm -rf -- {} +
-    for skill in "$source/$name-"*/; do
-      destination="$OPENCODE_SKILLS/$(basename "$skill")"
+    for skill in "${skills[@]}"; do
+      case "$skill" in
+        "$source/$name/"*) destination="$OPENCODE_SKILLS/$name/$(basename "$skill")" ;;
+        *) destination="$OPENCODE_SKILLS/$(basename "$skill")" ;;
+      esac
+      mkdir -p "$(dirname "$destination")"
       cp -R "$skill" "$destination"
     done
   done

From 1f151d191012d93b1ba43a7a0d073ff571c8e20a Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 13:27:02 +0800
Subject: [PATCH 03/73] feat(aidd-dev): add scoped sub-agent workflows

Separate exploration, implementation, completion validation and quality review. Allow assigned phases and independent batches while keeping shared state and acceptance with the caller.

Refs #983
---
 AGENTS.md                                     | 13 ++++++
 README.md                                     |  2 +-
 docs/ARCHITECTURE.md                          | 10 ++---
 .../02-project-memory/actions/04-sync.md      | 12 +++++-
 .../assets/templates/AGENTS.md                |  9 ++++
 plugins/aidd-dev/.claude-plugin/plugin.json   |  2 +
 plugins/aidd-dev/CATALOG.md                   |  6 ++-
 plugins/aidd-dev/agents/checker.md            | 15 ++++---
 plugins/aidd-dev/agents/executor.md           |  6 +--
 plugins/aidd-dev/agents/explorer.md           | 24 +++++++++++
 plugins/aidd-dev/agents/validator.md          | 30 ++++++++++++++
 plugins/aidd-dev/skills/01-plan/SKILL.md      | 36 +++++++++-------
 .../skills/01-plan/actions/02-explore.md      | 13 ++++--
 .../skills/01-plan/references/plan-status.md  |  2 +-
 plugins/aidd-dev/skills/02-implement/SKILL.md | 41 +++++++++++++------
 .../skills/02-implement/actions/01-prepare.md | 11 ++---
 .../skills/02-implement/actions/02-execute.md | 39 ++++++++++++------
 .../02-implement/actions/03-finalize.md       | 15 +++++--
 .../skills/02-implement/references/blocked.md |  2 +-
 .../aidd-orchestrator/skills/01-sdlc/SKILL.md |  4 +-
 .../skills/01-sdlc/references/02-deliver.md   | 19 ++++++---
 .../skills/01-sdlc/references/03-check.md     | 17 +++++---
 22 files changed, 238 insertions(+), 90 deletions(-)
 create mode 100644 plugins/aidd-dev/agents/explorer.md
 create mode 100644 plugins/aidd-dev/agents/validator.md

diff --git a/AGENTS.md b/AGENTS.md
index 53ad41f8b..94caba638 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,19 @@
 - **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 agents when useful. The caller owns scope, delegation, and final acceptance; no mandatory sequence.
+
+<!-- aidd_agents:start -->
+| name | role |
+| --- | --- |
+| @explorer (Codex), @aidd-dev-explorer (OpenCode) | Explore scoped questions. Return sourced findings, uncertainties, and risks. Never modify inspected material. |
+| @executor (Codex), @aidd-dev-executor (OpenCode) | Implement assigned scope. Validate, repair failures, and report evidence and blockers. Never change requirements. |
+| @validator (Codex), @aidd-dev-validator (OpenCode) | Validate supplied criteria and mandatory checks. Report PASS, FAIL, or BLOCKED with evidence. Never repair. |
+| @checker (Codex), @aidd-dev-checker (OpenCode) | Review quality, risks, and fitness for the need. Report actionable findings. Never modify the deliverable. |
+<!-- aidd_agents:end -->
+
 ## Memory Management
 
 Project docs, memory, specs, and plans live in `aidd_docs/`.
diff --git a/README.md b/README.md
index 760238e8d..d49c184a9 100644
--- a/README.md
+++ b/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>4 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/)
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 486617d92..9db584b29 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -147,16 +147,16 @@ A skill never links outside itself (`scripts/__tests__/a-skill-links-only-inside
 
 Choose by context, not complexity: keep the work visible to the caller → skill; isolate it and take only the result → agent.
 
-- **Spawning is authorized by the high-level orchestrator, never invented by a recipe skill.** A recipe skill normally runs in the caller's context. A bounded fan-out capability may mechanically spawn leaf agents only when the orchestrator explicitly delegates that responsibility and retains routing ownership.
-- An orchestrator spawns each isolated step as a leaf agent that runs a recipe, or runs the recipe itself when isolation is unnecessary. The SDLC owns planning, delegates delivery to `executor`, and delegates independent judgments to a fresh `checker`. For independent repair findings, it may explicitly delegate bounded fan-out to `10-todo`; Todo's leaf executors return their results to the SDLC. A recipe invoked inside an agent never spawns again.
-- An agent invokes only the recipe skills it declares under `# Skills you may invoke`, never an orchestrator skill, and never reads a skill's files. It names every skill by its canonical `/plugin:folder` address so its permissions are explicit and auditable.
-- An agent never delegates flow work to another agent and never invokes an orchestrator skill. It may spawn a read-only recon helper (for example `Explore`) that mutates nothing and spawns nothing. So the write path stays two layers deep and delegation can never cycle.
+- **The primary caller owns delegation.** A user-invoked recipe may offer bounded delegation through available host capabilities. An orchestrator owns delegation when it invokes the recipe. Neither requires a fixed provider or model.
+- A primary caller may delegate independent read-only questions to explorers and independent implementation phases to executors. It owns scope, dependencies, shared state, integration, and acceptance. Concurrent writers need distinct checkouts and nonconflicting validation resources; otherwise execution stays serial.
+- An isolated agent is a leaf. It never spawns another agent or invokes an orchestrator. It invokes only recipe skills listed under `# Skills you may invoke`, using their canonical `/plugin:folder` addresses without reading their files.
+- Independent validation uses a validator on an identified candidate. A checker reviews quality and outcome using that evidence. Neither modifies the candidate; gaps return to the primary caller for repair and renewed verification.
 
 ## 🔗 Capability addressing
 
 Address a capability only where the dispatch is declared: a router's `## Actions` table, an agent's `# Skills you may invoke` list. Everywhere else, name the concept the capability owns, never the skill that owns it.
 
-Recipe skills never hardcode a sibling provider. They discover cross-plugin capabilities at runtime through description matching. Agent permission lists and orchestration references are responsibility maps, so they name the current provider with its canonical `/plugin:folder` or `@plugin:agent` address. The orchestrator must verify that provider is installed before calling it.
+Recipe skills never hardcode a sibling provider. They discover cross-plugin capabilities at runtime through description matching. Agent permission lists name allowed skills with canonical `/plugin:folder` addresses. Orchestration references map responsibilities to providers discovered from installed descriptions; canonical addresses in diagrams illustrate current providers. Verify availability and the role contract before dispatch.
 
 Two paths are exempt, both in `isExemptFromOrthogonality`:
 
diff --git a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
index e96e752ae..9fa1dd693 100644
--- a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
+++ b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
@@ -8,7 +8,7 @@ The memory bank in `aidd_docs/memory/`.
 
 ## Output
 
-Each picked tool's context file, carrying the filled block.
+Each picked tool's context file, carrying the memory block and available agent table.
 
 ## Process
 
@@ -20,7 +20,12 @@ Each picked tool's context file, carrying the filled block.
    - Its AIDD structure differs: offer to reconcile it, applying only what the user approves.
 5. **Fill.** Run `hooks/update_memory.js` from the project root, naming the picked tools, and stop on a non-zero exit.
    - No script, the skill shipped alone: write each block from the bank.
-6. **Verify.** Read each picked tool's block back and compare it to the bank.
+6. **Agents.** Inspect the picked tools' available agent definitions and registration. Fill or replace only `aidd_agents:start` / `aidd_agents:end` with a `name | role` table.
+   - List only installed, invocable agents. Use their actual host identities, including plugin namespaces or flat prefixes; never assume a short role name is callable everywhere.
+   - Write short English descriptions beginning with the role's action verb. Keep detailed contracts in the agent definitions.
+   - When tools share a context file, label differing identities by host. Omit unavailable roles; leave only the table header if no agents are available.
+   - Preserve all user text outside the managed markers. Add the block when absent; do not add a discovery script or session hook.
+7. **Verify.** Read each picked tool's block back and compare it to the bank.
    - A file in one and not the other: the fill did not land, report it and stop.
 
 ## Test
@@ -32,3 +37,6 @@ Each picked tool's context file, carrying the filled block.
 | Picked tool | its block lists every root `.md` except `README.md`, nothing else |
 | Bank grew | the block gains that file and keeps the rest |
 | Unpicked tool | its context file is unchanged |
+| Agent table | every row resolves to an installed agent on its labelled host |
+| Agent unavailable | no row advertises it |
+| Existing context | text outside managed blocks is preserved |
diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
index 84d30658d..bcefe20a0 100644
--- a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
+++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
@@ -31,6 +31,15 @@
 - **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 agents when useful. The caller owns scope, delegation, and final acceptance; no mandatory sequence.
+
+<!-- aidd_agents:start -->
+| name | role |
+| --- | --- |
+<!-- aidd_agents:end -->
+
 ## Memory Management
 
 Project docs, memory, specs, and plans live in `aidd_docs/`.
diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json
index 766e5b871..bee38e7a9 100644
--- a/plugins/aidd-dev/.claude-plugin/plugin.json
+++ b/plugins/aidd-dev/.claude-plugin/plugin.json
@@ -20,7 +20,9 @@
     "./skills/10-todo"
   ],
   "agents": [
+    "./agents/explorer.md",
     "./agents/executor.md",
+    "./agents/validator.md",
     "./agents/checker.md"
   ],
   "keywords": [
diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md
index c54c4de54..32baab02c 100644
--- a/plugins/aidd-dev/CATALOG.md
+++ b/plugins/aidd-dev/CATALOG.md
@@ -32,8 +32,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 | File | Description |
 |------|---|
-| [checker.md](agents/checker.md) | `Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix.` |
+| [checker.md](agents/checker.md) | `Reviews quality, risks, and fitness for the intended need. Use for an independent judgment of a deliverable. Never edits the work or implements the fix.` |
 | [executor.md](agents/executor.md) | `Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.` |
+| [explorer.md](agents/explorer.md) | `Explores scoped questions and returns sourced findings. Use when a caller needs evidence before deciding. Never modifies the inspected material.` |
+| [validator.md](agents/validator.md) | `Validates an identified deliverable against supplied criteria and mandatory checks. Use for independent completion evidence. Never repairs or performs a general quality review.` |
 
 ### `skills`
 
@@ -59,7 +61,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [02-execute.md](skills/02-implement/actions/02-execute.md) | - |
 | `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - |
 | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` |
-| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.` |
+| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Implements an existing plan or an assigned phase until its acceptance criteria hold. Use when a plan or bounded phase needs implementing. Not for writing a plan or reviewing a diff.` |
 
 #### `skills/03-assert`
 
diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md
index 6f0752098..62aea7815 100644
--- a/plugins/aidd-dev/agents/checker.md
+++ b/plugins/aidd-dev/agents/checker.md
@@ -1,20 +1,19 @@
 ---
 name: checker
-description: Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix.
-model: opus
+description: Reviews quality, risks, and fitness for the intended need. Use for an independent judgment of a deliverable. Never edits the work or implements the fix.
 ---
 
 # Role
 
-You are the checker. Your job is to judge finished work against its validator and the real need, in a fresh context with no memory of how it was built, and to leave nothing unchecked.
+Review the deliverable's quality, risks, and fitness for its intended need in a fresh context.
 
 # Behavior
 
-- Build your validator stack first: the acceptance criteria and the need the work is meant to serve. Extend the checklist below with the project's own review checklist when it provides one.
-- Judge each criterion: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence.
+- Read the intended need, acceptance criteria, candidate identity, and available validation evidence. Extend the checklist below with the project's own review checklist when it provides one.
+- Use existing completion evidence. Repeat targeted checks only when it is insufficient, inconsistent, or stale; report missing validation instead of duplicating the full completion suite.
 - Run the checklist on every code or diff, leaving no item unchecked.
 - Then check the layer the reviews miss: does the delivered logic serve the actual need, end to end, even when code review and functional review both pass? Name any gap between intent and result.
-- Demand command output or file evidence, never bare claims. Lean strict: a false alarm costs less than a missed defect.
+- Demand command output or file evidence, never bare claims. Report concrete risks with their impact and uncertainty.
 - When a review skill fits the work, run it and let it write its report; that report is your deliverable and your judgment is what fills it. Never hand-write a parallel prose review beside it.
 - Return your verdict, findings, and score on top. Hold yourself accountable for whatever you pass.
 
@@ -29,8 +28,8 @@ This is the behavioral baseline. Apply it to every code or diff, and extend it w
 
 # Scoring
 
-- If the validator defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero.
-- Otherwise score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning.
+- If the supplied review checklist defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero.
+- Otherwise score quality and fitness for the need against the review checklist, adjusted for finding severity, with your reasoning.
 - The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail.
 
 # Guardrails
diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md
index e2af667ce..f7244af59 100644
--- a/plugins/aidd-dev/agents/executor.md
+++ b/plugins/aidd-dev/agents/executor.md
@@ -1,7 +1,6 @@
 ---
 name: executor
 description: Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.
-model: sonnet
 ---
 
 # Role
@@ -14,12 +13,13 @@ You are the executor. Your job is to turn a dispatched task into working, valida
 - Internalize the acceptance criteria before writing anything. If the scope is ambiguous, surface it instead of guessing.
 - Work in a tight loop: build a substep, validate it, repair on red, and only then move on. Validation passing is the gate, never your own say-so.
 - When a validation failure has no clear cause, run `/aidd-dev:08-debug` before repairing and validating again.
-- Commit per coherent unit, code and its status together, one unit one commit.
+- In an assigned phase, execute only that phase. Return checks and changes to the caller before unrelated phases begin.
+- Commit only when authorized and when you own the Git index. In parallel work, leave shared Git operations and plan updates to the caller.
 - When you finish or stall, return to whoever invoked you with what is done, what is left, and why.
 
 # Guardrails
 
-- Never author or edit a plan, spec, or acceptance criterion. That authority is the caller's. On any drift, stop and hand it back to be replanned.
+- Never change plan content, scope, specs, or acceptance criteria. Update lifecycle status only for plan or phase files assigned by the caller. An assigned-phase executor never updates shared-plan status. On drift, stop and hand it back to be replanned.
 - Stay strictly in the scope you are handed. Declare anything you bypass: no silent TODO, skipped test, or placeholder mock.
 - Never judge your own work, and never start a review. The caller handles that.
 - Never delegate to another agent.
diff --git a/plugins/aidd-dev/agents/explorer.md b/plugins/aidd-dev/agents/explorer.md
new file mode 100644
index 000000000..1d6bf5c4c
--- /dev/null
+++ b/plugins/aidd-dev/agents/explorer.md
@@ -0,0 +1,24 @@
+---
+name: explorer
+description: Explores scoped questions and returns sourced findings. Use when a caller needs evidence before deciding. Never modifies the inspected material.
+---
+
+# Role
+
+Explore the assigned question. Return evidence to the caller without deciding implementation scope.
+
+# Behavior
+
+- Read relevant code, documentation, and sources. Trace relationships needed to answer the question.
+- Separate observed facts from inference. Cite file paths and lines or source URLs.
+- Report uncertainties, conflicting evidence, and material risks.
+- Stay within the question. Return unresolved questions instead of expanding the task.
+
+# Outputs
+
+Return a concise answer, verifiable references, and remaining uncertainties.
+
+# Guardrails
+
+- Never modify files or external state. Do not run commands that mutate the inspected material.
+- Never implement changes, delegate work, or invoke an orchestrator.
diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
new file mode 100644
index 000000000..3ed70e33a
--- /dev/null
+++ b/plugins/aidd-dev/agents/validator.md
@@ -0,0 +1,30 @@
+---
+name: validator
+description: Validates an identified deliverable against supplied criteria and mandatory checks. Use for independent completion evidence. Never repairs or performs a general quality review.
+---
+
+# Role
+
+Validate whether the supplied candidate satisfies its acceptance criteria and mandatory checks.
+
+# Behavior
+
+- Identify the candidate revision or artifact before checking it. Confirm the criteria and mandatory checks supplied by the caller or project.
+- Use the smallest sufficient observable checks. Run every mandatory check.
+- Record PASS, FAIL, or BLOCKED for each criterion and mandatory check with the supporting command output or artifact evidence.
+- Mark missing, ambiguous, or unobservable criteria and missing prerequisites BLOCKED. An empty criteria set is blocked even if every command exits zero.
+- Never infer completion from an implementer's claim.
+- Confirm the candidate did not change during validation. If it changed, report affected evidence as stale.
+
+# Outputs
+
+Return the candidate identity, results and evidence, and one overall status:
+
+- COMPLETE only when every criterion and mandatory check passed on the unchanged identified candidate.
+- BLOCKED when criteria or prerequisites are missing, criteria are ambiguous or unobservable, or candidate evidence is stale.
+- INCOMPLETE when checks failed and no blocker prevents a reliable conclusion.
+
+# Guardrails
+
+- Never repair the candidate or change its criteria. Checks may create their normal temporary artifacts, but must not rewrite the deliverable.
+- Never perform a general quality review, delegate work, or invoke an orchestrator.
diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md
index 1bbb438ae..b0609c7ab 100644
--- a/plugins/aidd-dev/skills/01-plan/SKILL.md
+++ b/plugins/aidd-dev/skills/01-plan/SKILL.md
@@ -6,19 +6,31 @@ argument-hint: request | ticket | file
 
 # Skill: plan
 
-Turn a gathered source into an implementation plan and its phase files. Never writes code.
+```mermaid
+flowchart TD
+  Request([request, ticket, or file]) --> gather
+  gather --> explore
+  explore -- UI --> wireframe
+  explore -- no UI --> plan
+  wireframe --> plan
+  plan -- revision needed --> plan
+  plan --> Ready([plan ready])
+```
 
 ## Actions
 
-| #   | Action      | Role                                                 | Input                      |
-| --- | ----------- | ---------------------------------------------------- | -------------------------- |
-| 01  | `gather`    | Collect and restate the source                       | user request               |
-| 02  | `explore`   | Read the codebase for projection, rules, feasibility | gathered source            |
-| 03  | `wireframe` | Sketch a screen at low fidelity, frontend only       | source + explore context   |
-| 04  | `plan`      | Break into phases, write the plan and phase files    | explore output + wireframe |
+Read only the next matching numbered action file in `actions/`.
+
+| Action | Does |
+| --- | --- |
+| gather | collect and restate the source |
+| explore | ground the projection, rules, and feasibility |
+| wireframe | sketch frontend screens at low fidelity |
+| plan | write and review the plan and phase files |
 
-Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI.
-Before running an action, read its file in `actions/`, not only the table or assets.
+## Transversal rules
+
+- Planning never writes application code.
 
 Once the plan and its phase files are written, and only then, run:
 
@@ -26,12 +38,6 @@ Once the plan and its phase files are written, and only then, run:
 echo "aidd:step-end aidd-dev:01-plan"
 ```
 
-This is the one thing about a step nothing else can supply. No host reports when a skill's
-work finished — a skill call's own result comes back in a tenth of a second, which is the
-dispatch, not the completion — so a measurement that never hears this ends the step at the
-next pause and credits planning with one turn out of however many it took. The framework
-repository documents the run journal this writes into, in `aidd_docs/runs/README.md`.
-
 ## References
 
 - `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index 33a6916d5..f906d5301 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -12,12 +12,17 @@ The architecture projection (files to modify, create, delete, each with a one-li
 
 ## Process
 
-1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions.
+1. **Read.** Explore the code the source touches and build the projection with its infrastructure assumptions.
+   - The primary caller may delegate independent, bounded read-only questions to available explorers when useful. Each returns references and unresolved questions.
+   - Reconcile their findings against the source before planning. Resolve conflicting claims or retain the uncertainty. An isolated agent never delegates again.
 2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
 3. **Select.** Keep the project rules that apply to the projection.
 
 ## Test
 
-- The projection lists files to modify, create, and delete, each with a one-line reason.
-- Every feasibility check records its source and what it settled.
-- The applicable rules are identified and justified, or none apply.
+| Case | Pass |
+| --- | --- |
+| The exploration completes | The projection names files to modify, create, and delete with reasons; applicable rules are justified or none apply. |
+| A feasibility claim is made | Its source and what it settled are recorded. |
+| Exploration is delegated | Returned references and unresolved questions are reconciled into the projection and risks. |
+| Sources disagree | The conflict is resolved with evidence or remains explicit as uncertainty. |
diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md
index 51e98bf1e..59442bb8b 100644
--- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md
+++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md
@@ -20,4 +20,4 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The
 - Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state.
 - Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan.
 - `implemented` ≠ reviewed. Only the review layer sets `reviewed`.
-- Workers never write `status`; only plan creation and the orchestration layers do.
+- Assigned phase workers never write the plan status. They may update only their own phase status; the whole-plan owner updates the plan.
diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md
index dd77f0fd3..e07d2af44 100644
--- a/plugins/aidd-dev/skills/02-implement/SKILL.md
+++ b/plugins/aidd-dev/skills/02-implement/SKILL.md
@@ -1,29 +1,44 @@
 ---
 name: 02-implement
-description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.
-argument-hint: plan
+description: Implements an existing plan or an assigned phase until its acceptance criteria hold. Use when a plan or bounded phase needs implementing. Not for writing a plan or reviewing a diff.
+argument-hint: plan | phase
 ---
 
 # Skill: implement
 
-Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds.
+```mermaid
+flowchart TD
+  Whole([whole plan]) --> prepare
+  Assigned([assigned phase]) --> execute
+  prepare --> execute
+  execute -- check failed, repair --> execute
+  execute -- more ready phases --> execute
+  execute -- assigned phase complete --> Returned([return phase and evidence])
+  execute -- whole plan complete --> finalize
+  finalize -- validation failed, repair affected scope --> execute
+  finalize --> Implemented([implemented])
+  prepare -- plan missing --> Missing([stop])
+  execute -- blocked or drift --> Stopped([report blocker or replan needed])
+```
 
 ## Actions
 
-| #   | Action     | Role                                            | Input         |
-| --- | ---------- | ----------------------------------------------- | ------------- |
-| 01  | `prepare`  | Resolve the plan, branch, mark it in-progress   | a plan path   |
-| 02  | `execute`  | Loop the phases, code and assert each           | prepared plan |
-| 03  | `finalize` | Verify and mark the plan implemented            | coded phases  |
+Read only the next matching numbered action file in `actions/`.
 
-Run them in order, `01 → 03`.
-Before running an action, read its file in `actions/`, not only the table or assets.
+| Action | Does |
+| --- | --- |
+| prepare | resolve the whole plan and prepare its branch |
+| execute | implement and validate the selected scope |
+| finalize | verify the integrated plan and mark it implemented |
 
 ## Transversal rules
 
-- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit.
-- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against.
+- Supplying a whole plan assigns lifecycle-status ownership of that plan and its phases to the whole-plan runner. Supplying an assigned phase grants only that phase's lifecycle-status ownership. Neither grant permits changes to scope, specifications, or criteria.
+- A whole-plan run owns integration and completion verification. An assigned-phase run enters execute directly and returns without prepare or finalize. The primary caller retains final acceptance.
+- Phase status follows `pending → in-progress → done`. The whole-plan owner drives `pending → in-progress → implemented` or `blocked`. Runtime markers need no separate commit.
+- Follow the caller's commit policy. When commits are authorized, commit each phase's code with its own `done` status and the final plan status separately. Keep unrelated changes out of these commits.
+- Isolated agents never spawn agents. Only the primary caller may delegate bounded work using available host capabilities.
 
 ## References
 
-- `references/blocked.md`: the conditions that make a plan `blocked` and need a human.
+- `references/blocked.md`: conditions requiring a human.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
index 7e99042de..8171926c0 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
@@ -4,7 +4,7 @@ Resolve the plan, put the workspace on a feature branch, and mark the plan in-pr
 
 ## Input
 
-A plan, passed as arguments as a path or inline content.
+A whole plan, passed as arguments as a path or inline content.
 
 ## Output
 
@@ -14,10 +14,11 @@ The resolved plan on a feature branch with its frontmatter `status: in-progress`
 
 1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at <path>`. Never fabricate a plan.
 2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it.
-3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code.
+3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. Leave shared plan updates to the whole-plan owner; they follow the caller's commit policy.
 
 ## Test
 
-- A missing or unreadable plan with no inline content stops with `plan not found at <path>`, and no plan is fabricated.
-- The current branch is not the default branch.
-- The plan frontmatter reads `status: in-progress`.
+| Case | Pass |
+| --- | --- |
+| No readable plan or inline content resolves | Execution stops with `plan not found at <path>`; no plan is fabricated. |
+| Preparation succeeds | The current branch is not the default branch and the plan status is in-progress. |
diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index 2c531ffb4..952d59fe1 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -1,26 +1,39 @@
 # 02 - Execute
 
-Loop the plan's phases in order, coding each until every acceptance criterion holds.
-
 ## Input
 
-The prepared plan on its feature branch, from `01-prepare`.
+A prepared whole plan, or an assigned phase whose file is included in the assigned scope, with its plan context, completed prerequisites, acceptance criteria, checkout, and commit policy.
 
 ## Output
 
-Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan.
+The selected phases implemented with passing checks, `status: done`, and evidence identifying the checked revision. Or a blocker or `replan needed` report.
 
 ## Process
 
-1. **Open.** Walk the phases in order. In a feature folder each is a `phase-<n>.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet.
-2. **Code.** Build the phase scope against its acceptance criteria.
-3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together.
-4. **Guard.** Stop the loop on either condition:
-   - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop.
-   - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: <reason>`. Never rewrite the plan; replanning is the caller's job.
+1. **Select.** Resolve the execution scope and its prerequisites before changing files.
+   - Assigned phase: implement only that phase. Require a distinct checkout and nonconflicting validation resources when other executors run concurrently. Do not restart the plan, update its shared status, or run finalization.
+   - Whole plan: select phases whose `Depends on` prerequisites are done and integrated. Check file projections, shared contracts, and mutable validation resources before the primary caller dispatches a parallel batch to available executors. Give each ownership of its phase file for lifecycle-status updates only, completed prerequisites, criteria, isolated checkout, resources, and commit policy.
+   - Execute serially when isolation is unavailable or independence is uncertain. A plan without declared dependencies runs in phase order.
+   - Report `replan needed` for missing or contradictory prerequisites, or when unfinished phases have no ready phase; never skip them to declare completion.
+2. **Code.** Mark the selected phase `in-progress` and implement only its projection against its acceptance criteria.
+3. **Assert.** Run the relevant phase checks, repair failures, and repeat until they pass.
+   - Then mark the phase `done` and deliver its code, phase status, check commands, results, and checked revision under the caller's commit policy.
+   - The whole-plan owner integrates returned work before considering a dependency complete. Run checks for interactions changed by integration; reserve full plan validation for finalize. Select the next ready phases until all are done.
+4. **Guard.** Stop affected work on a blocker or any scope drift.
+   - **Blocked:** apply [blocked.md](../references/blocked.md); an assigned executor reports to the caller, while the whole-plan owner marks the plan `blocked`.
+   - **Drift:** report `replan needed: <reason>` without rewriting the plan or criteria. The caller decides how to revise the plan before resuming dependent work.
 
 ## Test
 
-- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits).
-- The branch holds one commit per phase; there are no separate `in-progress` status commits.
-- A blocker leaves the plan `status: blocked` with no later phase run.
+| Case | Pass |
+| --- | --- |
+| An assigned phase runs | Only its code and owned phase lifecycle status change; prepare, shared plan updates, other phases, and finalize are not run. |
+| A whole-plan executor runs | It updates only lifecycle statuses in supplied plan and phase files; scope, specifications, and criteria remain unchanged. |
+| A prerequisite is unfinished | Its dependent phase is not started. |
+| Prerequisites are missing or contradictory | Execution stops for replanning without marking unfinished phases done. |
+| A parallel batch runs | File changes and mutable validation resources do not conflict; executors use distinct checkouts and Git indexes. |
+| Isolation or independence is uncertain | Execution is serial. |
+| The plan has no dependency declarations | Phases run in their original order. |
+| A phase reaches done | Its criteria pass and the returned evidence identifies the checked revision. |
+| A returned phase has dependents | Its changes are integrated before any dependent starts. |
+| A blocker or scope drift occurs | Affected work stops; an assigned executor reports without rewriting shared plan state. |
diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
index 2943bc426..bf5ccfb19 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
@@ -12,10 +12,17 @@ The feature validated green with the plan frontmatter `status: implemented`.
 
 ## Process
 
-1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode.
-2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it.
+1. **Verify.** Verify every plan-level acceptance criterion and required validation against the integrated candidate.
+   - Phase checks alone do not establish that the combined workflow works.
+   - Reuse a passing result only when it covers the same candidate and required scope; rerun checks invalidated by later changes or integration. Never format code or run dev mode.
+   - On failure, return the affected scope to execution and verify the repaired candidate before marking completion.
+2. **Mark.** Set the plan `status: implemented` only when every phase is done and integrated validation is green, then deliver under the caller's commit policy.
 
 ## Test
 
-- The validation commands exit zero.
-- The plan reads `status: implemented`, committed (`git status --short` shows it clean).
+| Case | Pass |
+| --- | --- |
+| Finalization succeeds | Every phase is done and the required validation covers the integrated candidate with passing results. |
+| A previous result is reused | Its candidate and required scope match; changed candidates invalidate affected checks. |
+| Validation fails | The plan is not marked implemented; affected work returns for repair. |
+| The plan reaches implemented | Its status is delivered under the caller's commit policy. |
diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md
index 505a33899..42c94f6a1 100644
--- a/plugins/aidd-dev/skills/02-implement/references/blocked.md
+++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md
@@ -5,6 +5,6 @@ description: Conditions that make a plan blocked (needs a human).
 
 # When a plan is blocked
 
-`blocked` means implementation cannot proceed and only a human can unblock it. Stop, set `status: blocked`, and escalate.
+`blocked` means implementation cannot proceed and only a human can unblock it. Stop and escalate to the whole-plan owner, who sets the plan `status: blocked`.
 
 Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
index 24c3114f3..354b0c7a4 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
@@ -8,9 +8,9 @@ argument-hint: request
 
 ## Behavior
 
-Operate autonomously from the request to a draft pull request: decide and act without confirmation, asking only before spending money, taking an irreversible action, or making a decision that requires user authority. Read only the current zone reference. Verify that every named provider is installed before calling it.
+Operate autonomously from the request to a draft pull request: decide and act without confirmation, asking only before spending money, taking an irreversible action, or making a decision that requires user authority. Read only the current zone reference. Discover providers from installed skill and agent descriptions by responsibility. Verify their availability and contracts before dispatch; addresses in diagrams illustrate current providers.
 
-Spawn specialized agents for isolated work. Parallelize independent work when it is faster. Give each agent one focused task that a smaller model can execute. Repeat the responsible zone when delegated work returns an actionable gap.
+Spawn specialized agents for isolated work. Parallelize independent work when it is faster. Give each leaf agent one focused task. Keep model selection outside the role contract. Repeat the responsible zone when delegated work returns an actionable gap.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index c2b1a817c..d7b8192fd 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,9 +2,13 @@
 
 ## Behavior
 
-Turn the contract into a proportional plan, then give one executor the plan. The executor implements it and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Run a required end-to-end journey after every other validation.
+Turn the contract into a proportional plan. Delegate bounded read-only exploration when useful and reconcile sources and unknowns before planning.
 
-Commit and push the validated work through the commit skill. Send only the clean committed candidate to Check.
+Own preparation, shared plan status, dependencies, integration, and finalization. Assign ready, independent phases to executors in distinct checkouts with nonconflicting validation resources. Include each assigned phase file in its scope for lifecycle-status updates only, alongside plan context, criteria, completed prerequisites, and commit policy. Run sequentially when isolation is unavailable or independence is uncertain; legacy plans retain their phase order. For a sequential whole-plan executor, grant lifecycle-status ownership of the plan and all its phases while retaining acceptance; never grant changes to scope, specifications, or criteria.
+
+Executors implement, validate, and repair only their assigned scope without further delegation. Include architecture conformance when documented. Integrate each returned phase before starting its dependents. Finalize against the integrated candidate, including any required end-to-end journey last. Preserve passing evidence only when its candidate and scope still match.
+
+Commit and push through the commit capability. Send the clean committed candidate and its validation evidence to Check.
 
 ```mermaid
 ---
@@ -20,9 +24,11 @@ flowchart TD
 
   subgraph ExecuteStage["Execute and validate the plan"]
     direction TB
+    Dispatch["Caller selects ready phases"]
     Executor(["@aidd-dev:executor"])
     Implement["/aidd-dev:02-implement"]
     Assert["/aidd-dev:03-assert"]
+    Integrate["Integrate phases and finalize plan"]
     Test["/aidd-dev:06-test"]
     Commit["/aidd-vcs:01-commit"]
   end
@@ -35,11 +41,14 @@ flowchart TD
 
   Contract --> Plan
   Plan --> PlanArtifact
-  PlanArtifact --> Executor
+  PlanArtifact --> Dispatch
+  Dispatch -- "Isolated executors for independent phases; serial otherwise." --> Executor
   Executor --> Implement
   Implement --> Assert
-  Assert -- "When no end-to-end journey is required, commit the result." --> Commit
-  Assert -- "When an end-to-end journey is required, run it last." --> Test
+  Assert --> Integrate
+  Integrate -- "More ready phases." --> Dispatch
+  Integrate -- "No required end-to-end journey." --> Commit
+  Integrate -- "Run required end-to-end journey last." --> Test
   Test -- "After the journey succeeds, commit the result." --> Commit
   Test -- "Return a failed journey for repair." --> Executor
   Commit --> CommittedCandidate
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index c871e419f..38b042aa5 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -2,7 +2,9 @@
 
 ## Behavior
 
-Use one fresh checker, independent from implementation, to review the candidate against the contract, plan, and validation evidence. After the review clears, the same checker challenges whether the real outcome is trustworthy and serves the user.
+Use a fresh validator independent from implementation to verify the identified committed candidate against the contract, plan criteria, and mandatory checks. Require PASS, FAIL, or BLOCKED per criterion with evidence. The validator does not repair.
+
+Only after validation passes, use a fresh checker to review quality, risks, and fitness against the contract, plan, and validation evidence. Repeat targeted checks only when evidence is missing, inconsistent, or stale. After review clears, the same checker challenges the outcome. Any repaired candidate returns to independent validation; neither judgment carries forward automatically.
 
 Use product or contract findings as the next Frame source. Dispatch independent implementation findings through Todo and keep dependent repairs together in Deliver. Re-enter Check after every new candidate. Open the draft pull request when the checker returns no actionable finding.
 
@@ -17,6 +19,7 @@ flowchart TD
     Plan["$plan"]
     CommittedCandidate["$committed_candidate"]
     ValidationReports["$validation_reports"]
+    Validator(["@aidd-dev:validator"])
     Checker(["@aidd-dev:checker"])
     Review["/aidd-dev:05-review"]
   end
@@ -40,10 +43,12 @@ flowchart TD
     PullRequestUrl["$pull_request_url"]
   end
 
-  Contract --> Checker
-  Plan --> Checker
-  CommittedCandidate --> Checker
-  ValidationReports --> Checker
+  Contract --> Validator
+  Plan --> Validator
+  CommittedCandidate --> Validator
+  ValidationReports --> Validator
+  Validator -- "All criteria pass with evidence." --> Checker
+  Validator -- "Fail or blocked." --> Findings
   Checker --> Review
   Review -- "Return actionable review findings." --> Findings
   Review -- "When the review clears, challenge the outcome." --> Challenge
@@ -61,7 +66,7 @@ flowchart TD
   classDef zone fill:#F1F5F9,stroke:#64748B,color:#0F172A,stroke-width:2px
 
   class Review,Challenge,Todo,PullRequest skill
-  class Checker agent
+  class Checker,Validator agent
   class Contract,Plan,CommittedCandidate,ValidationReports,Findings,PullRequestUrl artifact
   class Frame,Deliver zone
 ```

From e00f124c59d3fe4ca44c173355f04d5ad809d97a Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 13:48:08 +0800
Subject: [PATCH 04/73] fix(framework): sync opencode agents and reject
 incomplete reloads

Install every selected native agent and preflight complete build output before replacing installed content. Surface build and installation failures instead of claiming success.

Refs #983
---
 aidd_docs/memory/deployment.md     |  21 ++++
 scripts/__tests__/dev-sync.test.js | 189 ++++++++++++++++++++++++++++-
 scripts/dev-sync.sh                |  55 +++++++--
 3 files changed, 255 insertions(+), 10 deletions(-)

diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index 901f9cdd9..cd8af01d2 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -56,6 +56,27 @@ 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` refreshes every plugin. `scripts/dev-sync.sh` copies built OpenCode skills and
+namespaced agents into the global directories, replacing only selected plugin namespaces.
+Missing expected build files fail before changing installed OpenCode content. A managed
+OpenCode host keeps its fixed-purpose `aidd-opencode-reload` helper.
+
+OpenCode V2 documents global agents at `~/.config/opencode/agents/`, filename-based agent
+names, and `mode: subagent`. Native restrictions use a `permissions` list with `action`,
+`resource`, and `effect`; `edit` covers write, edit and patch, `shell` gates commands, and
+`subagent` gates delegation. Source: <https://opencode.ai/v2/docs/agents>, read 2026-10-14.
+V2.0.28 also migrates legacy Markdown fields during discovery:
+<https://github.com/anomalyco/opencode/blob/v2.0.28/packages/core/src/config/plugin/agent.ts>,
+read 2026-10-14. After reload, `opencode debug agents` lists installed names; file presence
+alone does not establish discovery, invocation, or permission enforcement.
+
+For an OpenCode V2.0.28 subprocess probe, set both its working directory and `PWD` to the
+fixture: `run` prefers `process.env.PWD` over `process.cwd()` and changes directory to it.
+Source: <https://github.com/anomalyco/opencode/blob/v2.0.28/packages/cli/src/run/run.ts>,
+read 2026-10-14.
+
 ## Monitoring
 
 None. Failures surface as a red run; `back-merge.yml` opens a tracking issue when it cannot push, so drift is never silent.
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 9c37bbf01..2c0fcf9ba 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -6,12 +6,32 @@ const { delimiter, join, resolve } = require("node:path");
 const test = require("node:test");
 
 const repo = resolve(__dirname, "../..");
+const devAgents = ["checker.md", "executor.md"];
+const buildDevAgents = devAgents.map((name) => `printf '%s\\n' 'updated agent' > "$out/.opencode/agents/aidd-dev-${name}"`).join("\n");
 
 function executable(path, body) {
   writeFileSync(path, `#!/bin/sh\nset -eu\n${body}\n`);
   chmodSync(path, 0o755);
 }
 
+function fixture(home) {
+  const source = join(home, "framework");
+  if (!existsSync(source)) {
+    for (const [plugin, skill, agents] of [["aidd-dev", "01-plan", devAgents], ["aidd-pm", "03-prd", []]]) {
+      const pluginDir = join(source, "plugins", plugin);
+      mkdirSync(join(pluginDir, ".claude-plugin"), { recursive: true });
+      writeFileSync(join(pluginDir, ".claude-plugin/plugin.json"), "{}\n");
+      mkdirSync(join(pluginDir, "skills", skill), { recursive: true });
+      writeFileSync(join(pluginDir, "skills", skill, "SKILL.md"), "source skill\n");
+      for (const name of agents) {
+        mkdirSync(join(pluginDir, "agents"), { recursive: true });
+        writeFileSync(join(pluginDir, "agents", name), "source agent\n");
+      }
+    }
+  }
+  return source;
+}
+
 /** On POSIX, nothing but the stubs and the platform's own utilities, so a real `opencode` or
  * `claude` installed on the machine running these tests can never answer in their place.
  * Windows has neither directory, and the utilities `dev-sync.sh` calls live wherever Git for
@@ -29,8 +49,13 @@ function runSync(fakeBin, home, args = ["all"]) {
       ...process.env,
       PATH: [fakeBin, BASE_PATH].join(delimiter),
       HOME: home,
+      FW: fixture(home),
       BUILD: join(home, "build"),
+      CODEX_CACHE: join(home, ".codex/plugins/cache"),
+      CLAUDE_CACHE: join(home, ".claude/plugins/cache"),
+      CODEX_AGENTS: join(home, ".codex/agents"),
       OPENCODE_SKILLS: join(home, ".config/opencode/skills"),
+      OPENCODE_AGENTS: join(home, ".config/opencode/agents"),
     },
     encoding: "utf8",
   });
@@ -71,6 +96,12 @@ for (const layout of ["flat", "nested"]) {
       const unrelated = join(home, ".config/opencode/skills/aidd-pm/03-prd/SKILL.md");
       mkdirSync(join(home, ".config/opencode/skills/aidd-pm/03-prd"), { recursive: true });
       writeFileSync(unrelated, "keep\n");
+      const agentDir = join(home, ".config/opencode/agents");
+      mkdirSync(agentDir, { recursive: true });
+      writeFileSync(join(agentDir, "aidd-dev-checker.md"), "old agent\n");
+      writeFileSync(join(agentDir, "aidd-dev-removed.md"), "stale\n");
+      writeFileSync(join(agentDir, "personal.md"), "keep\n");
+      writeFileSync(join(agentDir, "aidd-pm-review.md"), "keep\n");
       executable(join(fakeBin, "opencode"), "exit 0");
       const skillName = layout === "nested" ? "aidd-dev/01-plan" : "aidd-dev-01-plan";
       executable(
@@ -84,7 +115,9 @@ skill="$out/.opencode/skills/${skillName}"
 mkdir -p "$skill/actions" "$skill/assets"
 printf '%s\n' '---' 'name: aidd-dev-01-plan' 'description: test' '---' > "$skill/SKILL.md"
 printf '%s\n' 'updated action' > "$skill/actions/04-plan.md"
-printf '%s\n' 'updated template' > "$skill/assets/plan-template.md"`,
+printf '%s\n' 'updated template' > "$skill/assets/plan-template.md"
+mkdir -p "$out/.opencode/agents"
+${buildDevAgents}`,
       );
 
       const result = runSync(fakeBin, home, ["aidd-dev"]);
@@ -97,6 +130,13 @@ printf '%s\n' 'updated template' > "$skill/assets/plan-template.md"`,
       assert.equal(existsSync(join(home, ".config/opencode/skills/aidd-dev/removed")), false);
       assert.equal(readFileSync(unrelated, "utf8"), "keep\n");
       assert.match(result.stdout, /install opencode\s+skills:ok/);
+      for (const name of devAgents) {
+        assert.equal(readFileSync(join(agentDir, `aidd-dev-${name}`), "utf8"), "updated agent\n");
+      }
+      assert.equal(existsSync(join(agentDir, "aidd-dev-removed.md")), false);
+      assert.equal(readFileSync(join(agentDir, "personal.md"), "utf8"), "keep\n");
+      assert.equal(readFileSync(join(agentDir, "aidd-pm-review.md"), "utf8"), "keep\n");
+      assert.match(result.stdout, /agents:ok/);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
@@ -117,10 +157,155 @@ test("local OpenCode reload rejects missing selected skills before removing inst
 
     const result = runSync(fakeBin, home, ["aidd-dev"]);
     assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /no built OpenCode skills for aidd-dev/);
+    assert.match(result.stderr, /no built OpenCode skill for aidd-dev-01-plan/);
     assert.doesNotMatch(result.stdout, /skills:ok/);
     assert.equal(readFileSync(installed, "utf8"), "keep\n");
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+test("local OpenCode reload rejects a missing agent before changing installed content", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-agent-missing-"));
+  try {
+    const fakeBin = join(root, "bin");
+    const home = join(root, "home");
+    mkdirSync(fakeBin);
+    const skillDir = join(home, ".config/opencode/skills/aidd-dev-01-plan");
+    const agentDir = join(home, ".config/opencode/agents");
+    mkdirSync(skillDir, { recursive: true });
+    mkdirSync(agentDir, { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), "keep skill\n");
+    writeFileSync(join(agentDir, "aidd-dev-checker.md"), "keep agent\n");
+    executable(join(fakeBin, "opencode"), "exit 0");
+    const remainingAgents = devAgents.filter((name) => name !== "checker.md").map((name) =>
+      `printf '%s\\n' 'agent' > "$out/.opencode/agents/aidd-dev-${name}"`,
+    ).join("\n");
+    executable(join(fakeBin, "npx"), String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--out" ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/.opencode/skills/aidd-dev-01-plan"
+printf '%s\n' 'new skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
+mkdir -p "$out/.opencode/agents"
+${remainingAgents}`);
+
+    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /no built OpenCode agent for aidd-dev-/);
+    assert.doesNotMatch(result.stdout, /skills:ok|agents:ok/);
+    assert.equal(readFileSync(join(skillDir, "SKILL.md"), "utf8"), "keep skill\n");
+    assert.equal(readFileSync(join(agentDir, "aidd-dev-checker.md"), "utf8"), "keep agent\n");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("default OpenCode reload installs every plugin's skills and agents", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-all-"));
+  try {
+    const fakeBin = join(root, "bin");
+    const home = join(root, "home");
+    mkdirSync(fakeBin);
+    mkdirSync(home);
+    const skills = ["aidd-dev-01-plan", "aidd-pm-03-prd"];
+    const agents = devAgents.map((name) => `aidd-dev-${name}`);
+    const buildSkills = skills.map((name) => `mkdir -p "$out/.opencode/skills/${name}"\nprintf '%s\\n' 'skill' > "$out/.opencode/skills/${name}/SKILL.md"`).join("\n");
+    const buildAgents = agents.map((name) => `printf '%s\\n' 'agent' > "$out/.opencode/agents/${name}"`).join("\n");
+    executable(join(fakeBin, "opencode"), "exit 0");
+    executable(join(fakeBin, "npx"), `out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--out" ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/.opencode/agents"
+${buildSkills}
+${buildAgents}`);
+
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    for (const skill of skills) {
+      assert.equal(readFileSync(join(home, ".config/opencode/skills", `${skill}/SKILL.md`), "utf8"), "skill\n");
+    }
+    for (const agent of agents) {
+      assert.equal(readFileSync(join(home, ".config/opencode/agents", agent), "utf8"), "agent\n");
+    }
+    assert.match(result.stdout, /skills:ok agents:ok/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+for (const badOutput of ["missing", "empty"]) {
+  test(`OpenCode rejects ${badOutput} expected skill output despite another built skill`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-partial-"));
+    try {
+      const fakeBin = join(root, "bin");
+      const home = join(root, "home");
+      mkdirSync(fakeBin);
+      const source = fixture(home);
+      const second = join(source, "plugins/aidd-dev/skills/02-implement");
+      mkdirSync(second);
+      writeFileSync(join(second, "SKILL.md"), "source skill\n");
+      const installed = join(home, ".config/opencode/skills/aidd-dev-02-implement");
+      mkdirSync(installed, { recursive: true });
+      writeFileSync(join(installed, "SKILL.md"), "keep\n");
+      executable(join(fakeBin, "opencode"), "exit 0");
+      executable(join(fakeBin, "npx"), String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--out" ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/.opencode/skills/aidd-dev-01-plan" "$out/.opencode/agents"
+printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
+${buildDevAgents}
+${badOutput === "empty" ? 'mkdir -p "$out/.opencode/skills/aidd-dev-02-implement"; touch "$out/.opencode/skills/aidd-dev-02-implement/SKILL.md"' : ""}`);
+      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, /no built OpenCode skill for aidd-dev-02-implement/);
+      assert.equal(readFileSync(join(installed, "SKILL.md"), "utf8"), "keep\n");
+      assert.doesNotMatch(result.stdout, /skills:ok|Done\./);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+for (const host of ["opencode", "codex"]) {
+  test(`reload fails when the installed ${host} host's build fails`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-build-failed-"));
+    try {
+      const fakeBin = join(root, "bin");
+      const home = join(root, "home");
+      mkdirSync(fakeBin);
+      executable(join(fakeBin, host), "exit 0");
+      executable(join(fakeBin, "npx"), "exit 7");
+      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, new RegExp(`${host} build failed`));
+      assert.doesNotMatch(result.stdout, /Done\./);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+for (const host of ["codex", "claude"]) {
+  test(`reload fails when the installed ${host} host rejects a plugin`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-install-failed-"));
+    try {
+      const fakeBin = join(root, "bin");
+      const home = join(root, "home");
+      mkdirSync(fakeBin);
+      executable(join(fakeBin, host), `if [ "$1" = plugin ] && [ "$2" = ${host === "codex" ? "add" : "install"} ]; then exit 8; fi\nexit 0`);
+      executable(join(fakeBin, "npx"), "exit 0");
+      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, /plugin install failed for aidd-dev/);
+      assert.doesNotMatch(result.stdout, /Done\./);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 750feb4f8..bb999cff1 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -21,6 +21,7 @@ CODEX_CACHE="${CODEX_CACHE:-$HOME/.codex/plugins/cache}"
 CLAUDE_CACHE="${CLAUDE_CACHE:-$HOME/.claude/plugins/cache}"
 CODEX_AGENTS="${CODEX_AGENTS:-$HOME/.codex/agents}"
 OPENCODE_SKILLS="${OPENCODE_SKILLS:-$HOME/.config/opencode/skills}"
+OPENCODE_AGENTS="${OPENCODE_AGENTS:-$HOME/.config/opencode/agents}"
 
 HAVE_CODEX=0;  command -v codex  >/dev/null 2>&1 && HAVE_CODEX=1
 HAVE_CLAUDE=0; command -v claude >/dev/null 2>&1 && HAVE_CLAUDE=1
@@ -36,6 +37,26 @@ build_tool() {
     --to "$tool" --out "$BUILD/$tool" --as "$mode" --force >/dev/null 2>&1
 }
 
+validate_opencode_content() {
+  local name agent skill skill_name
+  for name in "$@"; do
+    for skill in "$FW/plugins/$name/skills/"*/SKILL.md; do
+      skill_name="$(basename "$(dirname "$skill")")"
+      if [ ! -s "$BUILD/opencode/.opencode/skills/$name/$skill_name/SKILL.md" ] &&
+         [ ! -s "$BUILD/opencode/.opencode/skills/$name-$skill_name/SKILL.md" ]; then
+        echo "no built OpenCode skill for $name-$skill_name (missing or empty SKILL.md)" >&2
+        return 1
+      fi
+    done
+    for agent in "$FW/plugins/$name/agents/"*.md; do
+      if [ ! -s "$BUILD/opencode/.opencode/agents/$name-$(basename "$agent")" ]; then
+        echo "no built OpenCode agent for $name-$(basename "$agent" .md)" >&2
+        return 1
+      fi
+    done
+  done
+}
+
 sync_opencode_skills() {
   local name source skill destination
   local -a skills
@@ -43,10 +64,6 @@ sync_opencode_skills() {
   source="$BUILD/opencode/.opencode/skills"
   for name in "$@"; do
     skills=("$source/$name/"*/ "$source/$name-"*/)
-    if [ "${#skills[@]}" -eq 0 ]; then
-      echo "no built OpenCode skills for $name" >&2
-      return 1
-    fi
     rm -rf -- "$OPENCODE_SKILLS/$name"
     find "$OPENCODE_SKILLS" -mindepth 1 -maxdepth 1 -type d -name "$name-*" -exec rm -rf -- {} +
     for skill in "${skills[@]}"; do
@@ -60,6 +77,18 @@ sync_opencode_skills() {
   done
 }
 
+sync_opencode_agents() {
+  local name agent
+  mkdir -p "$OPENCODE_AGENTS"
+  for name in "$@"; do
+    # Only the selected plugin namespace is managed; personal and other plugins' agents stay.
+    for agent in "$OPENCODE_AGENTS/$name-"*.md; do rm -f -- "$agent"; done
+    for agent in "$BUILD/opencode/.opencode/agents/$name-"*.md; do
+      cp -f "$agent" "$OPENCODE_AGENTS/"
+    done
+  done
+}
+
 register_marketplace() {
   case "$1" in
     # Codex needs the built tree (the raw repo is Claude-syntax; Codex wants TOML/.codex-plugin).
@@ -93,6 +122,8 @@ sync_one() {
       [ "$n" -gt 0 ] && printf '(+%d agents)' "$n"
     else
       printf ' codex:FAIL'
+      echo "Codex plugin install failed for $name; rerun codex plugin add $name@$MKT for details." >&2
+      return 1
     fi
   fi
   if [ "$HAVE_CLAUDE" = 1 ]; then
@@ -114,10 +145,14 @@ sync_one() {
           [ "$fixed" -gt 0 ] && printf '(+%d agents, repaired %d)' "$n" "$fixed" || printf '(+%d agents)' "$n"
         else
           printf '(agents:NO-INSTALLPATH)'
+          echo "Claude plugin install path missing for $name; rerun claude plugin install $name@$MKT --scope user for details." >&2
+          return 1
         fi
       fi
     else
       printf ' claude:FAIL'
+      echo "Claude plugin install failed for $name; rerun claude plugin install $name@$MKT --scope user for details." >&2
+      return 1
     fi
   fi
   echo
@@ -138,26 +173,30 @@ fi
 # repo (already native), so it only needs the marketplace registered - no build.
 if [ "$HAVE_CODEX" = 1 ]; then
   printf '%-22s' "build codex"
-  build_tool codex && { register_marketplace codex; echo "ok"; } || { echo "FAIL"; HAVE_CODEX=0; }
+  build_tool codex || { echo "FAIL"; echo "codex build failed; rerun the translate command in scripts/dev-sync.sh without output redirection for details." >&2; exit 1; }
+  register_marketplace codex || { echo "FAIL"; echo "Codex marketplace registration failed for $BUILD/codex." >&2; exit 1; }
+  echo "ok"
 fi
 if [ "$HAVE_CLAUDE" = 1 ]; then
   register_marketplace claude
 fi
 if [ "$HAVE_OPENCODE" = 1 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
   printf '%-22s' "build opencode"
-  build_tool opencode && echo "ok" || { echo "FAIL"; HAVE_OPENCODE=0; }
+  build_tool opencode && echo "ok" || { echo "FAIL"; echo "opencode build failed; rerun the translate command in scripts/dev-sync.sh without output redirection for details." >&2; exit 1; }
 fi
 
 for t in "${targets[@]}"; do sync_one "$t"; done
 
 if [ "$HAVE_OPENCODE" = 1 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
   printf '%-22s' "install opencode"
+  validate_opencode_content "${targets[@]}"
   sync_opencode_skills "${targets[@]}"
-  echo "skills:ok"
+  sync_opencode_agents "${targets[@]}"
+  echo "skills:ok agents:ok"
 fi
 if [ "$HAVE_MANAGED_OPENCODE" = 1 ]; then
   printf '%-22s' "reload opencode"
   aidd-opencode-reload
 fi
 
-echo "Done. Restart Claude/Codex; OpenCode discovers the refreshed skills without a restart."
+echo "Done. Restart Claude/Codex; reload OpenCode configuration for refreshed agents and skills."

From 1cc3c0b2ea02f892bd7b533cea5311031afe2027 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 14:02:10 +0800
Subject: [PATCH 05/73] test(framework): record native sub-agent verification

Capture observed host invocations, scoped execution, parallel integration and the remaining controller and provider limits.

Refs #983
---
 .../2026_10_14_sub_agents/verification.md     | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
new file mode 100644
index 000000000..02c37dd52
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -0,0 +1,51 @@
+# Sub-agent verification
+
+Verified 2026-10-14 on `feature/sub-agents`: workflow candidate `1f151d19`, delivery candidate `e00f124c`.
+
+## Native roles
+
+| Host | Version | Invoked roles |
+| --- | --- | --- |
+| Codex | 0.162.1 | explorer, executor, validator, checker |
+| Claude Code | 2.1.299 | aidd-dev:explorer, aidd-dev:executor, aidd-dev:validator, aidd-dev:checker |
+| OpenCode | 2.0.28 | aidd-dev-explorer, aidd-dev-executor, aidd-dev-validator, aidd-dev-checker |
+
+Native dispatch traces identify the selected roles and fresh child contexts. Agent self-reports alone were not used to establish invocation.
+
+| Scenario | Codex | Claude | OpenCode |
+| --- | --- | --- | --- |
+| Explorer cites the readiness rule and refuses a conflicting write request | PASS | PASS | PASS |
+| Validator reports INCOMPLETE for the failing mandatory check without repair | PASS | PASS | PASS |
+| Validator reports BLOCKED without criteria despite an offered green command | PASS | PASS | PASS |
+| Executor invokes the installed implement skill for only its assigned phase | PASS | PASS | PASS |
+| Fresh validator reports COMPLETE for the repaired, unchanged candidate | PASS | PASS | PASS |
+| Checker reviews quality and fitness without modifying the candidate | PASS | PASS | PASS |
+
+Independent final readback found exact bytes `72 65 61 64 79 0a`, a passing `node check.cjs`, and only the assigned phase's lifecycle update. The shared plan, completed prerequisite, check command, and unrelated file retained their baseline contents.
+
+## Parallel implementation
+
+Two native Codex executors used separate supplied worktrees and Git indexes. Their recorded execution intervals overlapped by 19 seconds. Each invoked the installed assigned-phase workflow and committed only its own data file and phase status.
+
+| Phase | Executor commit | Integrated commit | Check |
+| --- | --- | --- | --- |
+| 1 | 551702df | 5e4bcaa1 | check-a.cjs: READY, exit 0 |
+| 2 | add8b135 | 32521585 | check-b.cjs: READY, exit 0 |
+
+The caller integrated both, obtained `BOTH_READY` and exit 0 from `node check-all.cjs`, then committed plan status `implemented` at `c2b8ff32`. Independent readback confirmed the plan and both phases complete, with all three checkouts clean. These commits belong to the disposable probe repository, not the framework.
+
+A restricted-workspace negative probe could not write Git metadata. It reported BLOCKED and left the integrated plan incomplete. The successful disposable probe used the desktop's unrestricted execution profile. No authentication or product security control was changed.
+
+## Real-project planning
+
+The installed planning skill produced three phases in Gouvernail's `2026_10_14_sub_agents_plan_probe` folder: two disjoint diagnostic scripts with no prerequisites, followed by shared package-command wiring depending on both. The phase projections and dependency table were inspected. No application source changed. Session-start memory formatting changes were restored; only the probe artifacts remain.
+
+The large-project planning and review controllers exceeded their imposed time limits after producing the artifacts. Their full interactive completion is not claimed. Codex's combined role controller also exceeded its limit; its native thread subsequently emitted all six results and `turn.completed`. A separate normal-session validator probe exited 0.
+
+## Delivery and gates
+
+`make reload` ran without `PLUGIN`, installing all nine plugins. OpenCode skills and agents were compared with the generated tree; native discovery listed all four roles. Claude's manifest explicitly declares the new agents.
+
+OpenCode's configured local model server was unavailable. Its behavioral probe used the already authenticated `openai/gpt-6.1-sol` through an invocation-only override, with matching `cwd` and `PWD`. Global model and authentication settings were unchanged. Versioned discovery and directory behavior sources are recorded in deployment memory.
+
+The wrapped scripts suite passed 559 tests, including 12 reload regressions. Architecture, JSON manifest validation, Markdown links, duplication checks, and commit hooks passed. These results establish the observed contracts and host paths; they do not guarantee every future task or model choice.

From 77094596b196ed9617c1abc104872a118c245be5 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 15:59:10 +0800
Subject: [PATCH 06/73] fix(framework): reload global instructions across hosts

---
 aidd_docs/memory/deployment.md       |  13 +++
 scripts/__tests__/dev-sync.test.js   | 155 ++++++++++++++++++++++++++-
 scripts/dev-sync.sh                  |  18 +++-
 scripts/sync-global-instructions.cjs |  61 +++++++++++
 4 files changed, 244 insertions(+), 3 deletions(-)
 create mode 100644 scripts/sync-global-instructions.cjs

diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index cd8af01d2..38f686a0f 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -63,6 +63,19 @@ namespaced agents into the global directories, replacing only selected plugin na
 Missing expected build files fail before changing installed OpenCode content. A managed
 OpenCode host keeps its fixed-purpose `aidd-opencode-reload` helper.
 
+Reload also updates a managed AIDD block in each installed host's global instructions:
+Codex `~/.codex/AGENTS.md`, Claude `~/.claude/CLAUDE.md`, OpenCode
+`~/.config/opencode/AGENTS.md`. Personal text remains outside the block. The framework's
+entire Memory Management section and its local architecture-file obligation are excluded;
+agent names match the host. First OpenCode sync preserves its previous Claude personal-rule
+fallback. `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, and `XDG_CONFIG_HOME` relocate instruction
+destinations; explicit `*_INSTRUCTIONS` overrides are available to isolate tests.
+
+Global instruction locations and OpenCode fallback precedence checked 2026-10-14:
+[Codex](https://developers.openai.com/codex/guides/agents-md),
+[Claude](https://code.claude.com/docs/en/memory),
+[OpenCode](https://opencode.ai/docs/rules/).
+
 OpenCode V2 documents global agents at `~/.config/opencode/agents/`, filename-based agent
 names, and `mode: subagent`. Native restrictions use a `permissions` list with `action`,
 `resource`, and `effect`; `edit` covers write, edit and patch, `shell` gates commands, and
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 2c0fcf9ba..50f9200af 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -2,13 +2,94 @@ const assert = require("node:assert/strict");
 const { spawnSync } = require("node:child_process");
 const { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } = require("node:fs");
 const { tmpdir } = require("node:os");
-const { delimiter, join, resolve } = require("node:path");
+const { delimiter, dirname, join, resolve } = require("node:path");
 const test = require("node:test");
 
 const repo = resolve(__dirname, "../..");
+const { render, sync } = require("../sync-global-instructions.cjs");
 const devAgents = ["checker.md", "executor.md"];
 const buildDevAgents = devAgents.map((name) => `printf '%s\\n' 'updated agent' > "$out/.opencode/agents/aidd-dev-${name}"`).join("\n");
 
+const instructionSource = "# AGENTS.md\n\n## Action\n- Keep scope.\n- Follow `docs/ARCHITECTURE.md`.\n\n## Agents\n| name | role |\n| --- | --- |\n| @executor (Codex), @aidd-dev-executor (OpenCode) | Implement scope. |\n\n## Memory Management\nProject docs live in aidd_docs/.\n<!-- aidd_project_memory:start -->\n@aidd_docs/memory/private.md\n<!-- aidd_project_memory:end -->\nLoad more memory.\n";
+
+test("global instructions exclude project context and use each host's native agent names", () => {
+  for (const [host, name] of [["codex", "@executor"], ["claude", "@aidd-dev:executor"], ["opencode", "@aidd-dev-executor"]]) {
+    const content = render(instructionSource, host);
+    assert.ok(content.includes(`| ${name} | Implement scope. |`));
+    assert.doesNotMatch(content, /Memory|memory|aidd_docs|ARCHITECTURE/);
+    assert.match(content, /Keep scope/);
+  }
+});
+
+test("global sync preserves personal rules, updates its block, and is idempotent", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-global-rules-"));
+  try {
+    const source = join(root, "source.md");
+    const destination = join(root, "codex/AGENTS.md");
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(source, instructionSource);
+    const personal = "Personal rules with no trailing newline";
+    writeFileSync(destination, personal);
+    sync(source, [["codex", destination]]);
+    const first = readFileSync(destination, "utf8");
+    sync(source, [["codex", destination]]);
+    assert.equal(readFileSync(destination, "utf8"), first);
+    writeFileSync(source, instructionSource.replace("Keep scope.", "Check scope."));
+    sync(source, [["codex", destination]]);
+    const updated = readFileSync(destination, "utf8");
+    assert.ok(updated.startsWith(personal));
+    assert.match(updated, /Check scope/);
+    assert.doesNotMatch(updated, /Keep scope/);
+    assert.equal(updated.split("aidd_global_instructions:start").length, 2);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("first OpenCode sync retains effective Claude personal rules without its managed block", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-global-fallback-"));
+  try {
+    const source = join(root, "source.md");
+    const claude = join(root, "CLAUDE.md");
+    const opencode = join(root, "opencode/AGENTS.md");
+    writeFileSync(source, instructionSource);
+    writeFileSync(claude, "Claude personal rules.\n");
+    sync(source, [["claude", claude]]);
+    sync(source, [["opencode", opencode]], claude);
+    const installed = readFileSync(opencode, "utf8");
+    assert.match(installed, /Claude personal rules/);
+    assert.match(installed, /@aidd-dev-executor/);
+    assert.doesNotMatch(installed, /@aidd-dev:executor/);
+    writeFileSync(claude, "Changed fallback.\n");
+    sync(source, [["opencode", opencode]], claude);
+    assert.equal(readFileSync(opencode, "utf8"), installed);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("malformed managed blocks and missing memory boundaries leave all global files untouched", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-global-invalid-"));
+  try {
+    const source = join(root, "source.md");
+    const codex = join(root, "AGENTS.md");
+    const claude = join(root, "CLAUDE.md");
+    writeFileSync(source, instructionSource);
+    writeFileSync(codex, "Keep Codex.\n");
+    for (const malformed of ["<!-- aidd_global_instructions:start -->", "<!-- aidd_global_instructions:end --><!-- aidd_global_instructions:start -->", "<!-- aidd_global_instructions:start --><!-- aidd_global_instructions:end -->".repeat(2)]) {
+      writeFileSync(claude, malformed);
+      assert.throws(() => sync(source, [["codex", codex], ["claude", claude]]), /Malformed/);
+      assert.equal(readFileSync(codex, "utf8"), "Keep Codex.\n");
+      assert.equal(readFileSync(claude, "utf8"), malformed);
+    }
+    writeFileSync(source, "Unbounded context.\n");
+    assert.throws(() => sync(source, [["codex", codex]]), /Memory Management boundary/);
+    assert.equal(readFileSync(codex, "utf8"), "Keep Codex.\n");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 function executable(path, body) {
   writeFileSync(path, `#!/bin/sh\nset -eu\n${body}\n`);
   chmodSync(path, 0o755);
@@ -28,6 +109,7 @@ function fixture(home) {
         writeFileSync(join(pluginDir, "agents", name), "source agent\n");
       }
     }
+    writeFileSync(join(source, "AGENTS.md"), "# AGENTS.md\n\n## Behavior\nKeep scope.\n\n## Memory Management\nProject-only memory.\n");
   }
   return source;
 }
@@ -39,7 +121,8 @@ function fixture(home) {
 const BASE_PATH =
   process.platform === "win32" ? (process.env.PATH ?? "") : ["/usr/bin", "/bin"].join(delimiter);
 
-function runSync(fakeBin, home, args = ["all"]) {
+function runSync(fakeBin, home, args = ["all"], overrides = {}) {
+  executable(join(fakeBin, "node"), `exec '${process.execPath}' "$@"`);
   // `bash`, resolved on PATH, never the literal `/bin/bash`: that path does not exist on
   // Windows, where bash is the one Git for Windows ships. `spawnSync` resolves a bare name
   // through the platform's own rules on both.
@@ -56,6 +139,12 @@ function runSync(fakeBin, home, args = ["all"]) {
       CODEX_AGENTS: join(home, ".codex/agents"),
       OPENCODE_SKILLS: join(home, ".config/opencode/skills"),
       OPENCODE_AGENTS: join(home, ".config/opencode/agents"),
+      CODEX_INSTRUCTIONS: join(home, ".codex/AGENTS.md"),
+      CLAUDE_INSTRUCTIONS: join(home, ".claude/CLAUDE.md"),
+      OPENCODE_INSTRUCTIONS: join(home, ".config/opencode/AGENTS.md"),
+      OPENCODE_DISABLE_CLAUDE_CODE: "",
+      OPENCODE_DISABLE_CLAUDE_CODE_PROMPT: "",
+      ...overrides,
     },
     encoding: "utf8",
   });
@@ -74,6 +163,68 @@ test("managed OpenCode reload uses the fixed-purpose helper without a local buil
     assert.equal(result.status, 0, result.stderr);
     assert.match(result.stdout, /reload opencode\s+managed:ok/);
     assert.equal(existsSync(join(home, "build")), false);
+    assert.match(readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8"), /Keep scope/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+for (const flag of ["OPENCODE_DISABLE_CLAUDE_CODE", "OPENCODE_DISABLE_CLAUDE_CODE_PROMPT"]) {
+  test(`OpenCode first reload respects disabled Claude fallback via ${flag}`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-no-fallback-"));
+    try {
+      const fakeBin = join(root, "bin");
+      const home = join(root, "home");
+      mkdirSync(fakeBin);
+      mkdirSync(join(home, ".claude"), { recursive: true });
+      writeFileSync(join(home, ".claude/CLAUDE.md"), "Excluded Claude personal rules.\n");
+      executable(join(fakeBin, "aidd-opencode-reload"), "exit 0");
+      const result = runSync(fakeBin, home, [], { [flag]: "1" });
+      assert.equal(result.status, 0, result.stderr);
+      const installed = readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8");
+      assert.doesNotMatch(installed, /Excluded Claude/);
+      assert.match(installed, /Keep scope/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+test("reload delivers global instructions to all three hosts while preserving personal rules", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-rules-"));
+  try {
+    const fakeBin = join(root, "bin");
+    const home = join(root, "home");
+    mkdirSync(fakeBin);
+    mkdirSync(home);
+    const source = fixture(home);
+    writeFileSync(join(source, "AGENTS.md"), instructionSource);
+    const destinations = [[".codex/AGENTS.md", "@executor"], [".claude/CLAUDE.md", "@aidd-dev:executor"], [".config/opencode/AGENTS.md", "@aidd-dev-executor"]];
+    for (const [path] of destinations) {
+      mkdirSync(dirname(join(home, path)), { recursive: true });
+      writeFileSync(join(home, path), "Personal rules.\n");
+    }
+    for (const host of ["codex", "claude", "opencode"]) executable(join(fakeBin, host), "exit 0");
+    executable(join(fakeBin, "npx"), String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--out" ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/.opencode/skills/aidd-pm-03-prd"
+printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-pm-03-prd/SKILL.md"`);
+    const first = runSync(fakeBin, home, ["aidd-pm"]);
+    assert.equal(first.status, 0, first.stderr);
+    assert.match(first.stdout, /global instructions\s+ok/);
+    const contents = destinations.map(([path, name]) => {
+      const content = readFileSync(join(home, path), "utf8");
+      assert.ok(content.startsWith("Personal rules.\n"));
+      assert.ok(content.includes(`| ${name} | Implement scope. |`));
+      assert.doesNotMatch(content, /Memory|aidd_docs|ARCHITECTURE/);
+      return content;
+    });
+    const second = runSync(fakeBin, home, ["aidd-pm"]);
+    assert.equal(second.status, 0, second.stderr);
+    destinations.forEach(([path], index) => assert.equal(readFileSync(join(home, path), "utf8"), contents[index]));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index bb999cff1..21db8d3ee 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -22,6 +22,9 @@ CLAUDE_CACHE="${CLAUDE_CACHE:-$HOME/.claude/plugins/cache}"
 CODEX_AGENTS="${CODEX_AGENTS:-$HOME/.codex/agents}"
 OPENCODE_SKILLS="${OPENCODE_SKILLS:-$HOME/.config/opencode/skills}"
 OPENCODE_AGENTS="${OPENCODE_AGENTS:-$HOME/.config/opencode/agents}"
+CODEX_INSTRUCTIONS="${CODEX_INSTRUCTIONS:-${CODEX_HOME:-$HOME/.codex}/AGENTS.md}"
+CLAUDE_INSTRUCTIONS="${CLAUDE_INSTRUCTIONS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md}"
+OPENCODE_INSTRUCTIONS="${OPENCODE_INSTRUCTIONS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md}"
 
 HAVE_CODEX=0;  command -v codex  >/dev/null 2>&1 && HAVE_CODEX=1
 HAVE_CLAUDE=0; command -v claude >/dev/null 2>&1 && HAVE_CLAUDE=1
@@ -199,4 +202,17 @@ if [ "$HAVE_MANAGED_OPENCODE" = 1 ]; then
   aidd-opencode-reload
 fi
 
-echo "Done. Restart Claude/Codex; reload OpenCode configuration for refreshed agents and skills."
+instructions=()
+[ "$HAVE_CODEX" = 0 ] || instructions+=(codex "$CODEX_INSTRUCTIONS")
+[ "$HAVE_CLAUDE" = 0 ] || instructions+=(claude "$CLAUDE_INSTRUCTIONS")
+if [ "$HAVE_OPENCODE" = 1 ] || [ "$HAVE_MANAGED_OPENCODE" = 1 ]; then
+  instructions+=(opencode "$OPENCODE_INSTRUCTIONS")
+fi
+printf '%-22s' "global instructions"
+instruction_fallback="$CLAUDE_INSTRUCTIONS"
+case "${OPENCODE_DISABLE_CLAUDE_CODE:-}" in 1|true) instruction_fallback="" ;; esac
+case "${OPENCODE_DISABLE_CLAUDE_CODE_PROMPT:-}" in 1|true) instruction_fallback="" ;; esac
+node "$SCRIPT_DIR/sync-global-instructions.cjs" "$FW/AGENTS.md" "$instruction_fallback" "${instructions[@]}"
+echo "ok (project memory excluded)"
+
+echo "Done. Restart Claude/Codex; reload OpenCode configuration for refreshed agents, skills, and instructions."
diff --git a/scripts/sync-global-instructions.cjs b/scripts/sync-global-instructions.cjs
new file mode 100644
index 000000000..3e02feb40
--- /dev/null
+++ b/scripts/sync-global-instructions.cjs
@@ -0,0 +1,61 @@
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { dirname } = require("node:path");
+
+const start = "<!-- aidd_global_instructions:start -->";
+const end = "<!-- aidd_global_instructions:end -->";
+
+function render(source, host) {
+  const boundary = source.search(/^## Memory Management\s*$/m);
+  if (boundary < 0) throw new Error("AGENTS.md has no Memory Management boundary; refusing global sync");
+  const names = {
+    codex: (role) => `@${role}`,
+    claude: (role) => `@aidd-dev:${role}`,
+    opencode: (role) => `@aidd-dev-${role}`,
+  };
+  if (!names[host]) throw new Error(`Unknown instruction host: ${host}`);
+  return source.slice(0, boundary).trim().replace(/^.*\bdocs\/ARCHITECTURE\.md.*\n?/gm, "").replace(
+    /^\| @([a-z]+)[^|]*\|/gm,
+    (_, role) => `| ${names[host](role)} |`,
+  );
+}
+
+function merge(existing, content) {
+  const starts = existing.split(start).length - 1;
+  const ends = existing.split(end).length - 1;
+  if (starts !== ends || starts > 1 || (starts === 1 && existing.indexOf(start) > existing.indexOf(end))) {
+    throw new Error("Malformed global AIDD instruction block; refusing to overwrite personal rules");
+  }
+  const block = content === null ? "" : `${start}\n${content}\n${end}`;
+  if (starts === 1) {
+    return existing.slice(0, existing.indexOf(start)) + block + existing.slice(existing.indexOf(end) + end.length);
+  }
+  if (content === null) return existing;
+  return existing + (existing.endsWith("\n\n") || !existing ? "" : existing.endsWith("\n") ? "\n" : "\n\n") + block + "\n";
+}
+
+function sync(sourcePath, destinations, claudeFallback) {
+  const source = readFileSync(sourcePath, "utf8");
+  // Prepare every destination before writing any: a malformed block must not partially sync hosts.
+  const updates = destinations.map(([host, path]) => {
+    let existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    // Creating OpenCode's global file disables its Claude fallback. Keep those personal rules.
+    if (host === "opencode" && !existsSync(path) && claudeFallback && existsSync(claudeFallback)) {
+      existing = merge(readFileSync(claudeFallback, "utf8"), null);
+    }
+    return { path, content: merge(existing, render(source, host)) };
+  });
+  for (const { path, content } of updates) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+  }
+}
+
+module.exports = { render, merge, sync };
+
+if (require.main === module) {
+  const [sourcePath, claudeFallback, ...args] = process.argv.slice(2);
+  if (!sourcePath || claudeFallback === undefined || args.length % 2) throw new Error("Usage: sync-global-instructions.cjs SOURCE CLAUDE_FALLBACK [HOST DESTINATION ...]");
+  const destinations = [];
+  for (let i = 0; i < args.length; i += 2) destinations.push([args[i], args[i + 1]]);
+  sync(sourcePath, destinations, claudeFallback);
+}

From dbf82b757743ec253df6a72084925cbcbc94eaac Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 16:24:28 +0800
Subject: [PATCH 07/73] refactor(aidd-dev): trim workflows and template agent
 outputs

---
 aidd_docs/memory/deployment.md                | 32 +---------
 docs/ARCHITECTURE.md                          | 10 ++--
 .../02-project-memory/actions/04-sync.md      | 34 ++++-------
 plugins/aidd-dev/agents/checker.md            | 50 ++++++++--------
 plugins/aidd-dev/agents/executor.md           | 48 +++++++++------
 plugins/aidd-dev/agents/explorer.md           | 28 +++++----
 plugins/aidd-dev/agents/validator.md          | 34 ++++++-----
 plugins/aidd-dev/skills/01-plan/SKILL.md      | 38 ++++--------
 .../skills/01-plan/actions/01-gather.md       | 17 +++---
 .../skills/01-plan/actions/02-explore.md      | 29 ++++-----
 .../skills/01-plan/actions/03-wireframe.md    | 16 ++---
 .../skills/01-plan/actions/04-plan.md         | 59 +++++++------------
 .../skills/01-plan/references/plan-status.md  |  8 +--
 .../references/wireframe-conventions.md       |  8 +--
 plugins/aidd-dev/skills/02-implement/SKILL.md | 35 +++++------
 .../skills/02-implement/actions/01-prepare.md | 21 +++----
 .../skills/02-implement/actions/02-execute.md | 46 +++++----------
 .../02-implement/actions/03-finalize.md       | 25 +++-----
 .../skills/01-sdlc/references/02-deliver.md   | 11 ++--
 .../skills/01-sdlc/references/03-check.md     |  9 ++-
 scripts/dev-sync.sh                           | 15 +++++
 21 files changed, 237 insertions(+), 336 deletions(-)

diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index 38f686a0f..ff79cff50 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -58,37 +58,7 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 ## Local reload
 
-`make reload` refreshes every plugin. `scripts/dev-sync.sh` copies built OpenCode skills and
-namespaced agents into the global directories, replacing only selected plugin namespaces.
-Missing expected build files fail before changing installed OpenCode content. A managed
-OpenCode host keeps its fixed-purpose `aidd-opencode-reload` helper.
-
-Reload also updates a managed AIDD block in each installed host's global instructions:
-Codex `~/.codex/AGENTS.md`, Claude `~/.claude/CLAUDE.md`, OpenCode
-`~/.config/opencode/AGENTS.md`. Personal text remains outside the block. The framework's
-entire Memory Management section and its local architecture-file obligation are excluded;
-agent names match the host. First OpenCode sync preserves its previous Claude personal-rule
-fallback. `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, and `XDG_CONFIG_HOME` relocate instruction
-destinations; explicit `*_INSTRUCTIONS` overrides are available to isolate tests.
-
-Global instruction locations and OpenCode fallback precedence checked 2026-10-14:
-[Codex](https://developers.openai.com/codex/guides/agents-md),
-[Claude](https://code.claude.com/docs/en/memory),
-[OpenCode](https://opencode.ai/docs/rules/).
-
-OpenCode V2 documents global agents at `~/.config/opencode/agents/`, filename-based agent
-names, and `mode: subagent`. Native restrictions use a `permissions` list with `action`,
-`resource`, and `effect`; `edit` covers write, edit and patch, `shell` gates commands, and
-`subagent` gates delegation. Source: <https://opencode.ai/v2/docs/agents>, read 2026-10-14.
-V2.0.28 also migrates legacy Markdown fields during discovery:
-<https://github.com/anomalyco/opencode/blob/v2.0.28/packages/core/src/config/plugin/agent.ts>,
-read 2026-10-14. After reload, `opencode debug agents` lists installed names; file presence
-alone does not establish discovery, invocation, or permission enforcement.
-
-For an OpenCode V2.0.28 subprocess probe, set both its working directory and `PWD` to the
-fixture: `run` prefers `process.env.PWD` over `process.cwd()` and changes directory to it.
-Source: <https://github.com/anomalyco/opencode/blob/v2.0.28/packages/cli/src/run/run.ts>,
-read 2026-10-14.
+`make reload` syncs all plugins and global instructions to Claude, Codex, and OpenCode; details in `scripts/dev-sync.sh`.
 
 ## Monitoring
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 9db584b29..79382ce34 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -136,7 +136,7 @@ flowchart LR
   ActionN --> Out
 ```
 
-Recipe skills route to self-contained actions with inputs, outputs, process steps, and tests. An orchestrator with no domain logic may instead route through numbered reference protocols that define handoffs and delegate the work to capabilities discovered at runtime.
+Recipe skills route to self-contained actions with inputs, outputs, process steps, and rules. An orchestrator with no domain logic may instead route through numbered reference protocols that define handoffs and delegate the work to capabilities discovered at runtime.
 
 A skill never links outside itself (`scripts/__tests__/a-skill-links-only-inside-itself.test.js`). The same tree ships flat, where the skill folder is renamed `<plugin>-<skill>`, or as a marketplace, so no relative path survives both. A bundled script is named plugin-relative in backticks, never linked.
 
@@ -147,16 +147,14 @@ A skill never links outside itself (`scripts/__tests__/a-skill-links-only-inside
 
 Choose by context, not complexity: keep the work visible to the caller → skill; isolate it and take only the result → agent.
 
-- **The primary caller owns delegation.** A user-invoked recipe may offer bounded delegation through available host capabilities. An orchestrator owns delegation when it invokes the recipe. Neither requires a fixed provider or model.
-- A primary caller may delegate independent read-only questions to explorers and independent implementation phases to executors. It owns scope, dependencies, shared state, integration, and acceptance. Concurrent writers need distinct checkouts and nonconflicting validation resources; otherwise execution stays serial.
-- An isolated agent is a leaf. It never spawns another agent or invokes an orchestrator. It invokes only recipe skills listed under `# Skills you may invoke`, using their canonical `/plugin:folder` addresses without reading their files.
-- Independent validation uses a validator on an identified candidate. A checker reviews quality and outcome using that evidence. Neither modifies the candidate; gaps return to the primary caller for repair and renewed verification.
+- **Caller:** own delegation, integration, and acceptance; use available agents when useful.
+- **Agent:** stay within assigned scope, never delegate or invoke an orchestrator, and invoke only declared recipe skills without reading their files.
 
 ## 🔗 Capability addressing
 
 Address a capability only where the dispatch is declared: a router's `## Actions` table, an agent's `# Skills you may invoke` list. Everywhere else, name the concept the capability owns, never the skill that owns it.
 
-Recipe skills never hardcode a sibling provider. They discover cross-plugin capabilities at runtime through description matching. Agent permission lists name allowed skills with canonical `/plugin:folder` addresses. Orchestration references map responsibilities to providers discovered from installed descriptions; canonical addresses in diagrams illustrate current providers. Verify availability and the role contract before dispatch.
+Recipe skills discover providers by description. Agent allowlists use canonical `/plugin:folder` addresses; orchestration diagrams illustrate providers. Verify availability and role before dispatch.
 
 Two paths are exempt, both in `isExemptFromOrthogonality`:
 
diff --git a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
index 9fa1dd693..e7cd958e7 100644
--- a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
+++ b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
@@ -16,27 +16,15 @@ Each picked tool's context file, carrying the memory block and available agent t
 2. **Detect.** Find the AI tools present per [tools.md](../references/tools.md).
 3. **Pick.** Show every tool, the detected ones ticked, and wait for one or several.
 4. **Upsert.** Ensure each picked tool's context file carries the block, per [tools.md](../references/tools.md).
-   - Absent file: create it from [AGENTS.md](../assets/templates/AGENTS.md).
-   - Its AIDD structure differs: offer to reconcile it, applying only what the user approves.
+   - **Absent:** create it from [AGENTS.md](../assets/templates/AGENTS.md).
+   - **Different:** reconcile its AIDD structure only with approval.
 5. **Fill.** Run `hooks/update_memory.js` from the project root, naming the picked tools, and stop on a non-zero exit.
-   - No script, the skill shipped alone: write each block from the bank.
-6. **Agents.** Inspect the picked tools' available agent definitions and registration. Fill or replace only `aidd_agents:start` / `aidd_agents:end` with a `name | role` table.
-   - List only installed, invocable agents. Use their actual host identities, including plugin namespaces or flat prefixes; never assume a short role name is callable everywhere.
-   - Write short English descriptions beginning with the role's action verb. Keep detailed contracts in the agent definitions.
-   - When tools share a context file, label differing identities by host. Omit unavailable roles; leave only the table header if no agents are available.
-   - Preserve all user text outside the managed markers. Add the block when absent; do not add a discovery script or session hook.
-7. **Verify.** Read each picked tool's block back and compare it to the bank.
-   - A file in one and not the other: the fill did not land, report it and stop.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| Empty bank | no context file created, the run stops |
-| Script | it exits `0` |
-| Picked tool | its block lists every root `.md` except `README.md`, nothing else |
-| Bank grew | the block gains that file and keeps the rest |
-| Unpicked tool | its context file is unchanged |
-| Agent table | every row resolves to an installed agent on its labelled host |
-| Agent unavailable | no row advertises it |
-| Existing context | text outside managed blocks is preserved |
+   - **Standalone:** without the script, fill each block from the bank.
+6. **Agents.** Fill `aidd_agents:start` / `aidd_agents:end` with installed, invocable agents and short English verb-led roles; label differing names by host in shared files.
+7. **Verify.** Read back each selected block; stop if it differs from the bank or advertises an unavailable agent.
+
+## Rules
+
+- **Memory:** list every root `.md` except `README.md`.
+- **Preserve:** leave unselected tools and text outside managed blocks unchanged.
+- **Missing block:** add the agent block, even if only its table header; no new discovery hook or script.
diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md
index 62aea7815..77e4c742d 100644
--- a/plugins/aidd-dev/agents/checker.md
+++ b/plugins/aidd-dev/agents/checker.md
@@ -5,41 +5,37 @@ description: Reviews quality, risks, and fitness for the intended need. Use for
 
 # Role
 
-Review the deliverable's quality, risks, and fitness for its intended need in a fresh context.
+Review quality, risks, and fitness for the intended need in a fresh context.
 
 # Behavior
 
-- Read the intended need, acceptance criteria, candidate identity, and available validation evidence. Extend the checklist below with the project's own review checklist when it provides one.
-- Use existing completion evidence. Repeat targeted checks only when it is insufficient, inconsistent, or stale; report missing validation instead of duplicating the full completion suite.
-- Run the checklist on every code or diff, leaving no item unchecked.
-- Then check the layer the reviews miss: does the delivered logic serve the actual need, end to end, even when code review and functional review both pass? Name any gap between intent and result.
-- Demand command output or file evidence, never bare claims. Report concrete risks with their impact and uncertainty.
-- When a review skill fits the work, run it and let it write its report; that report is your deliverable and your judgment is what fills it. Never hand-write a parallel prose review beside it.
-- Return your verdict, findings, and score on top. Hold yourself accountable for whatever you pass.
+- **Ground.** Read the need, criteria, candidate identity, and validation evidence; flag ambiguity instead of guessing.
+- **Inspect.** Apply the project's checklist; check duplication, contradictions, unnecessary complexity, leftovers, and gaps between intent and result.
+- **Verify.** Reuse validation evidence; repeat targeted checks only when insufficient, inconsistent, or stale.
+- **Report.** Tie findings to evidence and impact; use supplied checklist thresholds without inventing a score.
+- **Reuse.** When a review skill fits, let its report carry findings; reference it below instead of writing a duplicate.
+- **Read only.** Never edit the deliverable or its validator, implement fixes, or delegate.
 
-# Checklist
+# Output
 
-This is the behavioral baseline. Apply it to every code or diff, and extend it with the project's own checklist when one exists.
+Fill this Markdown template; replace placeholders and use `None` for empty fields.
+Use the findings table only when no skill report carries those findings.
 
-- [ ] No information duplication. DRY across code and docs; link to the canonical home instead of copying.
-- [ ] No incoherence or contradiction. Naming, behavior, and docs-versus-code stay consistent.
-- [ ] No over-engineering. The simplest solution that meets the need; no speculative generality, no unused abstraction.
-- [ ] No dead code or debug leftovers. No commented-out blocks, stray logs, or silent TODOs.
+```markdown
+## Review: <deliverable>
 
-# Scoring
+- **Candidate:** <revision or artifact identity>
+- **Verdict:** <fitness for the need, with decisive reason>
+- **Report:** <skill report path or None>
+- **Blockers:** <missing evidence or ambiguous criteria>
 
-- If the supplied review checklist defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero.
-- Otherwise score quality and fitness for the need against the review checklist, adjusted for finding severity, with your reasoning.
-- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail.
-
-# Guardrails
-
-- Never edit the work or its validator. Never implement the fix. Never delegate to another agent.
-- Never pass on vibes: tie every verdict to a stated criterion, a checklist item, or a named need-gap.
-- Flag an ambiguous criterion instead of guessing. Do not go easy because the work looks impressive.
+| Finding | Impact | Evidence | Suggested action |
+| --- | --- | --- | --- |
+| <concrete issue> | <consequence> | <path:line or check> | <minimal correction> |
+```
 
 # Skills you may invoke
 
-- `/aidd-dev:05-review`
-- `/aidd-dev:04-audit`
-- `/aidd-refine:02-challenge`
+- **Review.** `/aidd-dev:05-review`
+- **Audit.** `/aidd-dev:04-audit`
+- **Challenge.** `/aidd-refine:02-challenge`
diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md
index f7244af59..9116bc968 100644
--- a/plugins/aidd-dev/agents/executor.md
+++ b/plugins/aidd-dev/agents/executor.md
@@ -5,30 +5,40 @@ description: Turns a dispatched task into working, validated code that fits the
 
 # Role
 
-You are the executor. Your job is to turn a dispatched task into working, validated code that fits the project. You decide how, never what.
+Implement the assigned scope. Decide how, never what.
 
 # Behavior
 
-- Honour the project's own conventions where it defines them, and match the code around you. Where it stays silent, follow the prevailing idiom.
-- Internalize the acceptance criteria before writing anything. If the scope is ambiguous, surface it instead of guessing.
-- Work in a tight loop: build a substep, validate it, repair on red, and only then move on. Validation passing is the gate, never your own say-so.
-- When a validation failure has no clear cause, run `/aidd-dev:08-debug` before repairing and validating again.
-- In an assigned phase, execute only that phase. Return checks and changes to the caller before unrelated phases begin.
-- Commit only when authorized and when you own the Git index. In parallel work, leave shared Git operations and plan updates to the caller.
-- When you finish or stall, return to whoever invoked you with what is done, what is left, and why.
+- **Scope.** Follow acceptance criteria and project conventions; stop on ambiguity or drift.
+- **Build.** Validate each substep, repair failures, and repeat; debug an unclear cause first.
+- **Complete.** Report COMPLETE only after assigned criteria and mandatory checks pass.
+- **Ownership.** Change only assigned files and lifecycle status; an assigned phase never updates shared-plan status.
+- **Git.** Commit only when authorized and owning the Git index; leave shared operations to the caller.
+- **Report.** Return changes, checks, remaining work, and blockers; disclose skipped checks or placeholders.
+- **Boundary.** Never change requirements, review your own work, or delegate; stop at inaccessible human actions.
 
-# Guardrails
+# Output
 
-- Never change plan content, scope, specs, or acceptance criteria. Update lifecycle status only for plan or phase files assigned by the caller. An assigned-phase executor never updates shared-plan status. On drift, stop and hand it back to be replanned.
-- Stay strictly in the scope you are handed. Declare anything you bypass: no silent TODO, skipped test, or placeholder mock.
-- Never judge your own work, and never start a review. The caller handles that.
-- Never delegate to another agent.
-- When the work is physically impossible for the AI, stop and say so plainly: a real payment, a human login, an unreadable secret, anything behind hardware or 2FA. Do not fake progress.
+Fill this Markdown template; replace placeholders and use `None` for empty fields.
+
+```markdown
+## Implementation: <assigned scope>
+
+- **Status:** <COMPLETE | INCOMPLETE | BLOCKED>
+- **Candidate:** <revision or changed artifact paths>
+- **Changes:** <delivered behavior>
+- **Remaining:** <unfinished scope or skipped checks>
+- **Blockers:** <cause and needed input>
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| <criterion or command> | <PASS | FAIL | BLOCKED> | <output or artifact> |
+```
 
 # Skills you may invoke
 
-- `/aidd-dev:02-implement`
-- `/aidd-dev:03-assert`
-- `/aidd-dev:06-test`
-- `/aidd-dev:08-debug`
-- `/aidd-vcs:01-commit`
+- **Implement.** `/aidd-dev:02-implement`
+- **Assert.** `/aidd-dev:03-assert`
+- **Test.** `/aidd-dev:06-test`
+- **Debug.** `/aidd-dev:08-debug`
+- **Commit.** `/aidd-vcs:01-commit`
diff --git a/plugins/aidd-dev/agents/explorer.md b/plugins/aidd-dev/agents/explorer.md
index 1d6bf5c4c..15d06d93e 100644
--- a/plugins/aidd-dev/agents/explorer.md
+++ b/plugins/aidd-dev/agents/explorer.md
@@ -5,20 +5,28 @@ description: Explores scoped questions and returns sourced findings. Use when a
 
 # Role
 
-Explore the assigned question. Return evidence to the caller without deciding implementation scope.
+Explore an assigned question or codebase domain for the caller's decision.
 
 # Behavior
 
-- Read relevant code, documentation, and sources. Trace relationships needed to answer the question.
-- Separate observed facts from inference. Cite file paths and lines or source URLs.
-- Report uncertainties, conflicting evidence, and material risks.
-- Stay within the question. Return unresolved questions instead of expanding the task.
+- **Trace.** Read relevant code and sources, including relationships across the assigned domain's boundary.
+- **Ground.** Separate observations from inference; cite file lines or source URLs.
+- **Bound.** Report uncertainty and risks without expanding scope or deciding implementation.
+- **Read only.** Never mutate inspected material, implement, delegate, or invoke an orchestrator.
 
-# Outputs
+# Output
 
-Return a concise answer, verifiable references, and remaining uncertainties.
+Fill this Markdown template; replace placeholders and use `None` for empty fields.
 
-# Guardrails
+```markdown
+## Exploration: <question or domain>
 
-- Never modify files or external state. Do not run commands that mutate the inspected material.
-- Never implement changes, delegate work, or invoke an orchestrator.
+- **Answer:** <concise conclusion>
+- **Uncertainty:** <unknowns or conflicting evidence>
+- **Risks:** <material impacts>
+- **Blockers:** <missing access or evidence>
+
+| Finding | Evidence | Observation or inference |
+| --- | --- | --- |
+| <finding> | <path:line or URL> | <type> |
+```
diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
index 3ed70e33a..0bb88a669 100644
--- a/plugins/aidd-dev/agents/validator.md
+++ b/plugins/aidd-dev/agents/validator.md
@@ -5,26 +5,30 @@ description: Validates an identified deliverable against supplied criteria and m
 
 # Role
 
-Validate whether the supplied candidate satisfies its acceptance criteria and mandatory checks.
+Validate an identified candidate against supplied criteria and mandatory checks.
 
 # Behavior
 
-- Identify the candidate revision or artifact before checking it. Confirm the criteria and mandatory checks supplied by the caller or project.
-- Use the smallest sufficient observable checks. Run every mandatory check.
-- Record PASS, FAIL, or BLOCKED for each criterion and mandatory check with the supporting command output or artifact evidence.
-- Mark missing, ambiguous, or unobservable criteria and missing prerequisites BLOCKED. An empty criteria set is blocked even if every command exits zero.
-- Never infer completion from an implementer's claim.
-- Confirm the candidate did not change during validation. If it changed, report affected evidence as stale.
+- **Identify.** Record the candidate and confirm criteria, prerequisites, and mandatory checks.
+- **Check.** Run every mandatory check and the smallest sufficient observable checks; record evidence for each result.
+- **Complete.** Report COMPLETE only when all criteria and mandatory checks pass on an unchanged candidate.
+- **Block.** Report BLOCKED for absent, ambiguous, or unobservable criteria, missing prerequisites, or stale evidence.
+- **Fail.** Report INCOMPLETE for failures when no blocker prevents a reliable conclusion.
+- **Boundary.** Never accept an implementer's claim as evidence, repair, change criteria, review quality, or delegate; normal temporary check artifacts are allowed.
 
-# Outputs
+# Output
 
-Return the candidate identity, results and evidence, and one overall status:
+Fill this Markdown template; replace placeholders and use `None` for empty fields.
 
-- COMPLETE only when every criterion and mandatory check passed on the unchanged identified candidate.
-- BLOCKED when criteria or prerequisites are missing, criteria are ambiguous or unobservable, or candidate evidence is stale.
-- INCOMPLETE when checks failed and no blocker prevents a reliable conclusion.
+```markdown
+## Validation: <deliverable>
 
-# Guardrails
+- **Candidate:** <revision or artifact identity>
+- **Status:** <COMPLETE | INCOMPLETE | BLOCKED>
+- **Stability:** <evidence the candidate stayed unchanged>
+- **Blockers:** <missing criteria, prerequisites, or stale evidence>
 
-- Never repair the candidate or change its criteria. Checks may create their normal temporary artifacts, but must not rewrite the deliverable.
-- Never perform a general quality review, delegate work, or invoke an orchestrator.
+| Criterion or mandatory check | Result | Evidence |
+| --- | --- | --- |
+| <supplied requirement or command> | <PASS | FAIL | BLOCKED> | <output or artifact> |
+```
diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md
index b0609c7ab..88fe5ad11 100644
--- a/plugins/aidd-dev/skills/01-plan/SKILL.md
+++ b/plugins/aidd-dev/skills/01-plan/SKILL.md
@@ -4,46 +4,28 @@ description: Turn a request, ticket, or file into a phased implementation plan.
 argument-hint: request | ticket | file
 ---
 
-# Skill: plan
+# Plan
 
 ```mermaid
 flowchart TD
-  Request([request, ticket, or file]) --> gather
-  gather --> explore
-  explore -- UI --> wireframe
+  Request([request, ticket, or file]) --> gather --> explore
+  explore -- UI --> wireframe --> plan
   explore -- no UI --> plan
-  wireframe --> plan
-  plan -- revision needed --> plan
+  plan -- challenge finds gaps --> plan
   plan --> Ready([plan ready])
 ```
 
 ## Actions
 
-Read only the next matching numbered action file in `actions/`.
+Read only the next numbered action file in `actions/`.
 
 | Action | Does |
 | --- | --- |
-| gather | collect and restate the source |
-| explore | ground the projection, rules, and feasibility |
-| wireframe | sketch frontend screens at low fidelity |
-| plan | write and review the plan and phase files |
+| gather | identify the source and constraints |
+| explore | ground scope and feasibility in evidence |
+| wireframe | sketch frontend screens |
+| plan | write and challenge phases |
 
 ## Transversal rules
 
-- Planning never writes application code.
-
-Once the plan and its phase files are written, and only then, run:
-
-```shell
-echo "aidd:step-end aidd-dev:01-plan"
-```
-
-## References
-
-- `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs.
-- `references/plan-status.md`: the plan lifecycle `status` values and who writes each.
-
-## Assets
-
-- `assets/plan-template.md`: the `plan.md` scaffold.
-- `assets/phase-template.md`: the per-phase scaffold.
+- **Read-only.** Never write application code.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md
index 22d9571cc..76c4a20e1 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md
@@ -1,21 +1,18 @@
-# 01 - Gather
-
-Collect the source the plan will rest on, before any planning. Read only.
+# Gather
 
 ## Input
 
-The user's request, which may be empty.
+A request, file, or ticket.
 
 ## Output
 
-The source restated in a few bullets: what is asked and the hard constraints it states. The source kind and reference (file path, ticket id, or text) are named.
+Source kind and reference, requested outcome, hard constraints.
 
 ## Process
 
-1. **Find.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source.
-2. **Pull.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain.
-3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan.
+1. **Resolve.** Read the file, fetch the ticket, or use the supplied text; ask for a source if none exists.
+2. **Restate.** Summarize the outcome and constraints in bullets with bold labels.
 
-## Test
+## Rules
 
-- The output names the source kind and reference and restates it in bullets, states no solution, and when nothing concrete was given the user was asked before anything else.
+- **Fidelity.** Invent no source content, solution, or phases.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index f906d5301..95a0990cb 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -1,28 +1,23 @@
-# 02 - Explore
-
-Read the codebase to ground the plan: what it touches, which rules apply, what is feasible. Read only.
+# Explore
 
 ## Input
 
-The gathered source from `01-gather`.
+The gathered source.
 
 ## Output
 
-The architecture projection (files to modify, create, delete, each with a one-line reason), the project rules that apply (each justified in one line, or none), the feasibility checks (each source consulted, a doc URL or an in-repo file, and what it settled), and the risks.
+- **Projection.** Files to modify, create, or delete, each with a reason.
+- **Rules.** Applicable project rules and why, or none.
+- **Evidence.** Sources consulted and what each settled.
+- **Risks.** Blockers, conflicts, and unresolved questions.
 
 ## Process
 
-1. **Read.** Explore the code the source touches and build the projection with its infrastructure assumptions.
-   - The primary caller may delegate independent, bounded read-only questions to available explorers when useful. Each returns references and unresolved questions.
-   - Reconcile their findings against the source before planning. Resolve conflicting claims or retain the uncertainty. An isolated agent never delegates again.
-2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
-3. **Select.** Keep the project rules that apply to the projection.
+1. **Scope.** Identify the code and contracts the request touches.
+   - **Delegate.** The primary caller may assign independent questions by relevant codebase domain, such as frontend, backend, or a bounded context, to available explorers; give each a scope and requested evidence.
+2. **Verify.** Check feasibility against in-repo code or official documentation.
+3. **Reconcile.** Combine findings into the projection and applicable rules; resolve conflicting claims with evidence or retain the uncertainty.
 
-## Test
+## Rules
 
-| Case | Pass |
-| --- | --- |
-| The exploration completes | The projection names files to modify, create, and delete with reasons; applicable rules are justified or none apply. |
-| A feasibility claim is made | Its source and what it settled are recorded. |
-| Exploration is delegated | Returned references and unresolved questions are reconciled into the projection and risks. |
-| Sources disagree | The conflict is resolved with evidence or remains explicit as uncertainty. |
+- **Boundaries.** Explore only relevant domains; delegation is optional and isolated agents never delegate again.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md
index 928b9cb95..81ac7a5a0 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md
@@ -1,20 +1,14 @@
-# 03 - Wireframe
-
-Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI.
+# Wireframe
 
 ## Input
 
-The screens to sketch, from the gathered source and the `02-explore` context (the existing screens and components).
+Required screens and existing components from exploration.
 
 ## Output
 
-A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy.
+An ASCII wireframe per screen, with numbered regions and one-line notes.
 
 ## Process
 
-1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI.
-2. **Draw.** Sketch each screen per [wireframe-conventions.md](../references/wireframe-conventions.md). The wireframe feeds the plan.
-
-## Test
-
-- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carrying no behavior, styling, or final copy.
+1. **Select.** Identify required screens; skip when there is no UI.
+2. **Draw.** Follow [wireframe-conventions.md](../references/wireframe-conventions.md).
diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
index b431aae05..d32737c9c 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
@@ -1,51 +1,34 @@
-# 04 - Plan
-
-Turn the explored source into a plan and its phases, save them, then review the whole before handoff. Never code.
+# Plan
 
 ## Input
 
-The explore output from `02-explore` (projection, rules, feasibility, risks), plus any confirmed wireframe from `03-wireframe`.
+Exploration findings and any wireframes.
 
 ## Output
 
-A feature folder, always at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/`, holding `plan.md` from [plan-template.md](../assets/plan-template.md) and one `phase-<n>.md` per phase from [phase-template.md](../assets/phase-template.md).
+`plan.md` and `phase-<n>.md` files in the source's feature folder or `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/`.
 
 ## Process
 
-1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many.
-   - Prefer independent phases without splitting inseparable work.
-   - Identify prerequisites from each phase's file projection, shared contracts, and validation resources.
-   - Order phases that need another phase's output or would interfere through shared file changes or mutable validation resources.
-   - Preserve ordering when independence cannot be established.
-2. **Folder.** Reuse the feature folder the source already lives in, or create one. When creating one and `01-gather`'s own source reference names a backlog item — a ticket id or URL, or a file path naming its Markdown artefact, never raw text — with no `backlog-link.json` there yet, declare it the same way the skill that writes a spec does:
+1. **Slice.** Prefer independent phases, each coherent, verifiable, and sized for one executor pass.
+2. **Write.** Fill [plan-template.md](../assets/plan-template.md) and [phase-template.md](../assets/phase-template.md), covering the full projection without placeholders.
+3. **Link.** For a new folder whose source reference names a backlog item, create `backlog-link.json`:
 
    ```json
-   {
-     "backlog": "owner/repo#123",
-     "written_at": "2026-08-21T09:00:00Z",
-     "written_by": "aidd-dev:01-plan"
-   }
+   {"backlog": "<reference>", "written_at": "<UTC timestamp>", "written_by": "aidd-dev:01-plan"}
    ```
 
-   `backlog` is the one field, on whatever support the item lives - a forge reference or a project-relative Markdown path, never both. When the source names none, write nothing. When `backlog-link.json` already exists, leave it untouched - it is correctable by hand, and a later run must never overwrite a correction.
-3. **Fill.** Fill the plan and each phase from their templates, following the inline contracts, and record prerequisites in the phase table.
-   - Slice the projection across the phases.
-4. **Show.** Display the written paths.
-5. **Review.** Check the declared dependencies against the phase scopes, then score the complete plan and its phases from 0 to 10, with ✓ reasons and ✗ risks.
-   - In interactive mode, show them and revise until approved.
-   - Under an autonomous orchestrator, revise against the source without waiting for approval; ask only when a product decision cannot be resolved from the source.
-   - Never write the score to the plan.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| The plan is written | The feature folder holds `plan.md` and one `phase-<n>.md` per phase. |
-| Written files are read back | Each satisfies its template's inline contract with no `{...}` placeholder left. |
-| Phase projections are combined | They cover the modify, create, and delete lists. |
-| Dependencies are reviewed | Every prerequisite names an existing earlier phase; no phase depends on itself. |
-| Phases share a required output, conflicting file changes, or mutable validation resources | Their ordering is recorded in the phase table. |
-| Phase independence is uncertain | The plan preserves ordering. |
-| The plan is scored | A confidence score was reported and written to no file. |
-| The run is autonomous | It waits only for a product decision that the source cannot resolve. |
-| A new folder's source names a ticket | `backlog-link.json` names it; reusing a folder never overwrites an existing link. |
+4. **Challenge.** Check source coverage, phase boundaries, acceptance criteria, and dependencies; revise gaps, using an available challenge capability when useful.
+   - **Interactive.** Show paths and obtain approval.
+   - **Autonomous.** Ask only for product decisions the source cannot resolve.
+5. **Finish.** Emit the completion marker once the files are written and challenged.
+
+   ```shell
+   echo "aidd:step-end aidd-dev:01-plan"
+   ```
+
+## Rules
+
+- **Dependencies.** Record earlier phase numbers in `Depends on` for required outputs, conflicting file changes, or shared mutable validation resources; preserve ordering when independence is uncertain.
+- **Link preservation.** Never overwrite an existing backlog link; `backlog` holds one forge reference or project-relative Markdown path, never both or inferred from raw text.
+- **Lifecycle.** Follow [plan-status.md](../references/plan-status.md).
diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md
index 59442bb8b..3480af0e3 100644
--- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md
+++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md
@@ -17,7 +17,7 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The
 
 ## Rules
 
-- Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state.
-- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan.
-- `implemented` ≠ reviewed. Only the review layer sets `reviewed`.
-- Assigned phase workers never write the plan status. They may update only their own phase status; the whole-plan owner updates the plan.
+- **Transitions.** `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state.
+- **Rejection.** Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan.
+- **Review ownership.** `implemented` ≠ reviewed. Only the review layer sets `reviewed`.
+- **Phase ownership.** Assigned phase workers never write the plan status. They may update only their own phase status; the whole-plan owner updates the plan.
diff --git a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md
index 1dfb23947..9156451fe 100644
--- a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md
+++ b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md
@@ -4,10 +4,10 @@ A wireframe is a low-fidelity ASCII sketch of a screen. Structure only: no behav
 
 ## Drawing
 
-- One box per screen, drawn with `┌ ─ ┐ │ └ ┘`.
-- Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit.
-- Number each region.
-- Under the sketch, one line per number on what it holds and why.
+- **Screen.** One box per screen, drawn with `┌ ─ ┐ │ └ ┘`.
+- **Layout.** Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit.
+- **Regions.** Number each region.
+- **Notes.** Under the sketch, one line per number on what it holds and why.
 
 ## Example
 
diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md
index e07d2af44..deb3c7985 100644
--- a/plugins/aidd-dev/skills/02-implement/SKILL.md
+++ b/plugins/aidd-dev/skills/02-implement/SKILL.md
@@ -4,41 +4,34 @@ description: Implements an existing plan or an assigned phase until its acceptan
 argument-hint: plan | phase
 ---
 
-# Skill: implement
+# Implement
 
 ```mermaid
 flowchart TD
   Whole([whole plan]) --> prepare
   Assigned([assigned phase]) --> execute
   prepare --> execute
-  execute -- check failed, repair --> execute
-  execute -- more ready phases --> execute
-  execute -- assigned phase complete --> Returned([return phase and evidence])
-  execute -- whole plan complete --> finalize
-  finalize -- validation failed, repair affected scope --> execute
-  finalize --> Implemented([implemented])
   prepare -- plan missing --> Missing([stop])
-  execute -- blocked or drift --> Stopped([report blocker or replan needed])
+  execute -- repair or more ready phases --> execute
+  execute -- assigned phase done --> Returned([return evidence])
+  execute -- whole plan done --> finalize
+  execute -- blocked or drift --> Stopped([report blocker or replan])
+  finalize -- repair --> execute
+  finalize --> Implemented([implemented])
 ```
 
 ## Actions
 
-Read only the next matching numbered action file in `actions/`.
+Read only the next numbered action file in `actions/`.
 
 | Action | Does |
 | --- | --- |
-| prepare | resolve the whole plan and prepare its branch |
-| execute | implement and validate the selected scope |
-| finalize | verify the integrated plan and mark it implemented |
+| prepare | resolve the plan and prepare its branch |
+| execute | implement and check assigned scope |
+| finalize | validate the integrated plan |
 
 ## Transversal rules
 
-- Supplying a whole plan assigns lifecycle-status ownership of that plan and its phases to the whole-plan runner. Supplying an assigned phase grants only that phase's lifecycle-status ownership. Neither grant permits changes to scope, specifications, or criteria.
-- A whole-plan run owns integration and completion verification. An assigned-phase run enters execute directly and returns without prepare or finalize. The primary caller retains final acceptance.
-- Phase status follows `pending → in-progress → done`. The whole-plan owner drives `pending → in-progress → implemented` or `blocked`. Runtime markers need no separate commit.
-- Follow the caller's commit policy. When commits are authorized, commit each phase's code with its own `done` status and the final plan status separately. Keep unrelated changes out of these commits.
-- Isolated agents never spawn agents. Only the primary caller may delegate bounded work using available host capabilities.
-
-## References
-
-- `references/blocked.md`: conditions requiring a human.
+- **Ownership.** Whole-plan runners own integration and plan/phase lifecycle statuses; assigned-phase runners own only their phase status and skip prepare/finalize. Never change requirements or criteria; the caller retains final acceptance.
+- **Commits.** Follow caller policy; when authorized, commit each phase's code with its `done` status and the final plan status separately, excluding unrelated changes. Runtime markers need no separate commit.
+- **Delegation.** Only the primary caller may delegate; isolated agents never spawn agents.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
index 8171926c0..7c6000662 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
@@ -1,24 +1,19 @@
-# 01 - Prepare
-
-Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress.
+# Prepare
 
 ## Input
 
-A whole plan, passed as arguments as a path or inline content.
+A whole plan, as a path or inline content.
 
 ## Output
 
-The resolved plan on a feature branch with its frontmatter `status: in-progress`, ready for the phase loop. Or a fail-fast stop when no plan resolves.
+Resolved plan on a feature branch, `status: in-progress`, or a missing-plan error.
 
 ## Process
 
-1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at <path>`. Never fabricate a plan.
-2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it.
-3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. Leave shared plan updates to the whole-plan owner; they follow the caller's commit policy.
+1. **Resolve.** Read the supplied plan; if unavailable, stop with `plan not found at <path>`.
+2. **Branch.** Create and announce a feature branch when on the default branch; otherwise keep the current branch.
+3. **Mark.** Set the plan `status: in-progress`.
 
-## Test
+## Rules
 
-| Case | Pass |
-| --- | --- |
-| No readable plan or inline content resolves | Execution stops with `plan not found at <path>`; no plan is fabricated. |
-| Preparation succeeds | The current branch is not the default branch and the plan status is in-progress. |
+- **Source.** Never fabricate a missing plan.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index 952d59fe1..44ecf2dc1 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -1,39 +1,25 @@
-# 02 - Execute
+# Execute
 
 ## Input
 
-A prepared whole plan, or an assigned phase whose file is included in the assigned scope, with its plan context, completed prerequisites, acceptance criteria, checkout, and commit policy.
+A prepared plan or assigned phase, with plan context, prerequisites, criteria, checkout, resources, and commit policy.
 
 ## Output
 
-The selected phases implemented with passing checks, `status: done`, and evidence identifying the checked revision. Or a blocker or `replan needed` report.
+Implemented phases, `status: done`, check commands/results and checked revision, or a blocker/replan report.
 
 ## Process
 
-1. **Select.** Resolve the execution scope and its prerequisites before changing files.
-   - Assigned phase: implement only that phase. Require a distinct checkout and nonconflicting validation resources when other executors run concurrently. Do not restart the plan, update its shared status, or run finalization.
-   - Whole plan: select phases whose `Depends on` prerequisites are done and integrated. Check file projections, shared contracts, and mutable validation resources before the primary caller dispatches a parallel batch to available executors. Give each ownership of its phase file for lifecycle-status updates only, completed prerequisites, criteria, isolated checkout, resources, and commit policy.
-   - Execute serially when isolation is unavailable or independence is uncertain. A plan without declared dependencies runs in phase order.
-   - Report `replan needed` for missing or contradictory prerequisites, or when unfinished phases have no ready phase; never skip them to declare completion.
-2. **Code.** Mark the selected phase `in-progress` and implement only its projection against its acceptance criteria.
-3. **Assert.** Run the relevant phase checks, repair failures, and repeat until they pass.
-   - Then mark the phase `done` and deliver its code, phase status, check commands, results, and checked revision under the caller's commit policy.
-   - The whole-plan owner integrates returned work before considering a dependency complete. Run checks for interactions changed by integration; reserve full plan validation for finalize. Select the next ready phases until all are done.
-4. **Guard.** Stop affected work on a blocker or any scope drift.
-   - **Blocked:** apply [blocked.md](../references/blocked.md); an assigned executor reports to the caller, while the whole-plan owner marks the plan `blocked`.
-   - **Drift:** report `replan needed: <reason>` without rewriting the plan or criteria. The caller decides how to revise the plan before resuming dependent work.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| An assigned phase runs | Only its code and owned phase lifecycle status change; prepare, shared plan updates, other phases, and finalize are not run. |
-| A whole-plan executor runs | It updates only lifecycle statuses in supplied plan and phase files; scope, specifications, and criteria remain unchanged. |
-| A prerequisite is unfinished | Its dependent phase is not started. |
-| Prerequisites are missing or contradictory | Execution stops for replanning without marking unfinished phases done. |
-| A parallel batch runs | File changes and mutable validation resources do not conflict; executors use distinct checkouts and Git indexes. |
-| Isolation or independence is uncertain | Execution is serial. |
-| The plan has no dependency declarations | Phases run in their original order. |
-| A phase reaches done | Its criteria pass and the returned evidence identifies the checked revision. |
-| A returned phase has dependents | Its changes are integrated before any dependent starts. |
-| A blocker or scope drift occurs | Affected work stops; an assigned executor reports without rewriting shared plan state. |
+1. **Select.** Run only assigned or whole-plan phases whose prerequisites are done and integrated.
+   - **Parallel.** The primary caller may dispatch independent phases to executors with their owned files, criteria, completed prerequisites, distinct checkouts/Git indexes, and nonconflicting validation resources.
+   - **Serial.** Run in order when isolation or independence is uncertain, or dependencies are undeclared.
+2. **Implement.** Mark the phase `in-progress`, implement its projection, check its criteria, and repair until passing.
+3. **Deliver.** Mark the phase `done` and return its changes and evidence.
+   - **Whole plan.** Integrate returned work, recheck affected interactions, and select the next ready phases.
+   - **Assigned phase.** Return to the caller.
+
+## Rules
+
+- **Readiness.** Missing/contradictory dependencies or unfinished phases with none ready require `replan needed`; never skip them or declare completion.
+- **Drift.** Stop affected work and report `replan needed: <reason>` without rewriting scope or criteria.
+- **Blocked.** Follow [blocked.md](../references/blocked.md); assigned executors report, the whole-plan owner sets plan `status: blocked`.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
index bf5ccfb19..d3970fdb2 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
@@ -1,28 +1,19 @@
-# 03 - Finalize
-
-Run the validation and mark the plan implemented once every phase is done.
+# Finalize
 
 ## Input
 
-A plan whose phases are all `status: done`, from `02-execute`.
+A plan with all phases done and integrated.
 
 ## Output
 
-The feature validated green with the plan frontmatter `status: implemented`.
+Plan `status: implemented`, with integrated acceptance and validation evidence.
 
 ## Process
 
-1. **Verify.** Verify every plan-level acceptance criterion and required validation against the integrated candidate.
-   - Phase checks alone do not establish that the combined workflow works.
-   - Reuse a passing result only when it covers the same candidate and required scope; rerun checks invalidated by later changes or integration. Never format code or run dev mode.
-   - On failure, return the affected scope to execution and verify the repaired candidate before marking completion.
-2. **Mark.** Set the plan `status: implemented` only when every phase is done and integrated validation is green, then deliver under the caller's commit policy.
+1. **Verify.** Check every plan-level acceptance criterion and required validation on the integrated candidate; return failures to execution and revalidate repairs.
+2. **Mark.** Set the plan `status: implemented` only when all required checks pass.
 
-## Test
+## Rules
 
-| Case | Pass |
-| --- | --- |
-| Finalization succeeds | Every phase is done and the required validation covers the integrated candidate with passing results. |
-| A previous result is reused | Its candidate and required scope match; changed candidates invalidate affected checks. |
-| Validation fails | The plan is not marked implemented; affected work returns for repair. |
-| The plan reaches implemented | Its status is delivered under the caller's commit policy. |
+- **Evidence.** Reuse passing results only for the same candidate and required scope; phase checks alone do not establish integrated acceptance.
+- **Validation scope.** Never format code or run dev mode during finalization.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index d7b8192fd..e9ecb3ab1 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,13 +2,10 @@
 
 ## Behavior
 
-Turn the contract into a proportional plan. Delegate bounded read-only exploration when useful and reconcile sources and unknowns before planning.
-
-Own preparation, shared plan status, dependencies, integration, and finalization. Assign ready, independent phases to executors in distinct checkouts with nonconflicting validation resources. Include each assigned phase file in its scope for lifecycle-status updates only, alongside plan context, criteria, completed prerequisites, and commit policy. Run sequentially when isolation is unavailable or independence is uncertain; legacy plans retain their phase order. For a sequential whole-plan executor, grant lifecycle-status ownership of the plan and all its phases while retaining acceptance; never grant changes to scope, specifications, or criteria.
-
-Executors implement, validate, and repair only their assigned scope without further delegation. Include architecture conformance when documented. Integrate each returned phase before starting its dependents. Finalize against the integrated candidate, including any required end-to-end journey last. Preserve passing evidence only when its candidate and scope still match.
-
-Commit and push through the commit capability. Send the clean committed candidate and its validation evidence to Check.
+- **Plan:** reconcile scoped exploration, then produce the implementation plan.
+- **Assign:** retain shared lifecycle and integration; delegate independent phases with their criteria, prerequisites, status-file ownership, checkout, resources, and commit policy. Use separate checkouts for parallel writers; otherwise run serially. A whole-plan executor may own all lifecycle statuses, never scope or criteria.
+- **Integrate:** accept scoped changes and evidence before starting dependents; finalize against the combined candidate, with required end-to-end checks last. Reuse only evidence still valid for that candidate and scope.
+- **Handoff:** commit and push through the commit capability; send the clean candidate and evidence to Check.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index 38b042aa5..481165fee 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -2,11 +2,10 @@
 
 ## Behavior
 
-Use a fresh validator independent from implementation to verify the identified committed candidate against the contract, plan criteria, and mandatory checks. Require PASS, FAIL, or BLOCKED per criterion with evidence. The validator does not repair.
-
-Only after validation passes, use a fresh checker to review quality, risks, and fitness against the contract, plan, and validation evidence. Repeat targeted checks only when evidence is missing, inconsistent, or stale. After review clears, the same checker challenges the outcome. Any repaired candidate returns to independent validation; neither judgment carries forward automatically.
-
-Use product or contract findings as the next Frame source. Dispatch independent implementation findings through Todo and keep dependent repairs together in Deliver. Re-enter Check after every new candidate. Open the draft pull request when the checker returns no actionable finding.
+- **Validate:** dispatch a fresh validator on the committed candidate, contract, criteria, and mandatory checks.
+- **Challenge:** after validation passes, dispatch a fresh checker for review and outcome challenge using that evidence.
+- **Route:** send product findings to Frame, independent repairs to Todo, dependent repairs to Deliver; revalidate each repaired candidate.
+- **Ship:** open the draft pull request when no actionable finding remains.
 
 ```mermaid
 ---
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 21db8d3ee..f9af1c402 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -9,6 +9,19 @@
 #
 # Codex caveat: the .codex-plugin manifest does not declare codex-agents/*.toml, and Codex
 # loads agents only from ~/.codex/agents/, so the built TOML is copied there after install.
+# Global rules: replace only the managed AIDD block; exclude project memory and adapt agent
+# names. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
+# Instruction paths honor CODEX_HOME, CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME; tests use
+# *_INSTRUCTIONS overrides. Sources checked 2026-10-14:
+# https://developers.openai.com/codex/guides/agents-md
+# https://code.claude.com/docs/en/memory
+# https://opencode.ai/docs/rules/
+# OpenCode V2 discovery: global agents are filename-named subagents; inspect with
+# `opencode debug agents`. File presence alone does not prove invocation or permissions.
+# https://opencode.ai/v2/docs/agents (read 2026-10-14)
+# https://github.com/anomalyco/opencode/blob/v2.0.28/packages/core/src/config/plugin/agent.ts
+# V2.0.28 probe cwd must match PWD because run prefers PWD (read 2026-10-14):
+# https://github.com/anomalyco/opencode/blob/v2.0.28/packages/cli/src/run/run.ts
 set -euo pipefail
 shopt -s nullglob
 
@@ -41,6 +54,7 @@ build_tool() {
 }
 
 validate_opencode_content() {
+  # Check every expected nonempty skill and agent before replacing selected namespaces.
   local name agent skill skill_name
   for name in "$@"; do
     for skill in "$FW/plugins/$name/skills/"*/SKILL.md; do
@@ -61,6 +75,7 @@ validate_opencode_content() {
 }
 
 sync_opencode_skills() {
+  # Accept nested and legacy flat builds; preserve personal and unselected plugin content.
   local name source skill destination
   local -a skills
   mkdir -p "$OPENCODE_SKILLS"

From e04e3e33093c86645a9bd3e0ed28011288797020 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 16:53:10 +0800
Subject: [PATCH 08/73] fix(framework): align workflow contracts and remove
 repeated instructions

---
 .../skills/04-skill-generate/SKILL.md         |  8 ++--
 .../04-skill-generate/actions/01-scope.md     | 14 +-----
 .../04-skill-generate/actions/02-plan.md      | 25 ++++------
 .../04-skill-generate/actions/03-write.md     | 27 ++++-------
 .../04-skill-generate/actions/04-validate.md  | 14 ++----
 .../assets/action-template.md                 |  8 ++--
 .../assets/skill-template.md                  |  2 +-
 .../references/scope-frame.md                 | 30 ++++--------
 .../references/skill-authoring.md             |  8 ++--
 .../02-implement/actions/03-finalize.md       |  2 +-
 .../skills/01-sdlc/references/02-deliver.md   | 15 +++---
 plugins/aidd-refine/CATALOG.md                |  3 +-
 plugins/aidd-refine/README.md                 |  2 +-
 .../aidd-refine/skills/02-challenge/SKILL.md  | 29 ++++-------
 .../02-challenge/actions/01-challenge.md      | 34 +++++--------
 .../02-challenge/assets/report-template.md    | 25 ++++++----
 .../references/confidence-rubric.md           | 10 ----
 scripts/__tests__/dev-sync.test.js            | 48 +++++++++++++++----
 scripts/dev-sync.sh                           |  6 +--
 scripts/sync-global-instructions.cjs          |  7 +--
 20 files changed, 139 insertions(+), 178 deletions(-)
 delete mode 100644 plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md

diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
index 6e546fb72..4f6e262f1 100644
--- a/plugins/aidd-context/skills/04-skill-generate/SKILL.md
+++ b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
@@ -25,7 +25,7 @@ Run the flow above. Read only the next action file.
 
 ## Transversal rules
 
-- Default to `create`; follow `modify` when asked.
-- If a cited reference cannot be read, stop and report the missing file.
-- Confirm every target and name with the user.
-- Never write silently.
+- **Entry.** Default to `create`; follow `modify` when asked.
+- **References.** If a cited reference cannot be read, stop and report the missing file.
+- **Confirmation.** Confirm every target and name with the user.
+- **Visibility.** Never write silently.
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md b/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md
index 2ed28f681..d7f85953c 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md
@@ -13,16 +13,6 @@ The confirmed frame, written nowhere, per [scope-frame.md](../references/scope-f
 ## Process
 
 1. **Detect.** Detect the installed tools per [tool-detect.md](../references/tool-detect.md).
-2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question.
-3. **Check.** Check the name per [naming.md](../references/naming.md) and surface any overlap.
+2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question at a time.
+3. **Check.** Check the name per [naming.md](../references/naming.md), reporting overlaps or none.
 4. **Confirm.** Hand the confirmed frame to plan.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| The action runs to completion | `git status --porcelain` reads the same after as before |
-| A name overlaps an installed skill | the overlap is surfaced before the frame is handed on |
-| No name overlaps | the run states that it found none |
-| A frame field needs the user | one question is asked, and only that one |
-| The frame is handed to plan | its target was confirmed by the user first |
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md b/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md
index 41c70fa72..baaf0f3cd 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md
@@ -1,27 +1,20 @@
 # 02 - Plan
 
-Break the skill into atomic, testable actions: one action, one job.
+Break the skill into atomic actions: one action, one job.
 
 ## Input
 
-- From scope, the create frame.
-- For a modify, the existing skill, read in place.
+- **Create.** The frame from scope.
+- **Modify.** The existing skill, read in place.
 
 ## Output
 
-A plan table, one row per action: slug, input to output, test, and any dependency.
+A plan table, one row per action: slug, input to output, observable success, and dependencies.
 
 ## Process
 
-1. **List.** List every distinct job the output needs. Modify: start from the existing actions, touch only the jobs the user named.
-2. **Atomize.** Prefer few actions, a job each, not a step. Merge two that share most logic.
-3. **Number.** Name, number, and give each an observable test, per [skill-authoring.md](../references/skill-authoring.md).
-4. **Confirm.** Present the table, validate each test with the user.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| The table is presented | every row is one job carrying a checkable test |
-| A row consumes an output | that output comes from an earlier row, never a later one |
-| The run is a modify | only the jobs the user named have a row |
+1. **List.** List every distinct job the output needs.
+   - **Modify.** Keep only jobs the user named.
+2. **Atomize.** Prefer few actions, a job each; merge two that share most logic.
+3. **Order.** Name and number each action per [skill-authoring.md](../references/skill-authoring.md), placing consumed outputs before their consumers.
+4. **Confirm.** Present the table and confirm each observable success condition with the user.
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md b/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md
index 595826e48..eefe567a9 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md
@@ -4,8 +4,8 @@ Write the skill tree from the plan.
 
 ## Input
 
-- The plan from 02.
-- The target from 01, or for a modify the existing skill's own location.
+- **Plan.** The plan from 02.
+- **Target.** The target from 01, or for a modify the existing skill's own location.
 
 ## Output
 
@@ -14,21 +14,10 @@ The skill tree at the target, and the list of files written.
 ## Process
 
 1. **Tree.** Create the shape in [skill-tree.md](../references/skill-tree.md).
-2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md), strip the scaffold.
-   - Modify: revise the existing SKILL.md in place, keeping the user's edits.
-3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row against [skill-authoring.md](../references/skill-authoring.md), its test copied from the plan.
-   - Modify: revise a changed action in place. Leave an untouched one alone.
+2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md).
+   - **Modify.** Revise the existing SKILL.md in place, keeping the user's edits.
+3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row, weaving its success check into the process.
+   - **Modify.** Revise changed actions in place; leave untouched ones alone.
 4. **Hint.** Set `argument-hint` per [skill-authoring.md](../references/skill-authoring.md).
-5. **Place.** Write once per confirmed target, using [tool-write.md](../references/tool-write.md).
-6. **Check.** Confirm every written path is relative, inside the workspace, outside the plugin install directory, and under the chosen target. Else stop and report it.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| The router is written | it holds a `mermaid` flowchart and an `Action \| Does` table |
-| The action table is read back | every slug is bare and every `Does` is a lowercase imperative with no final period |
-| An action file is written | it holds `## Output`, `## Process`, and a `Case \| Pass` `## Test` |
-| The tree is written | its shape matches [skill-tree.md](../references/skill-tree.md) |
-| Any written file is read back | no `<` placeholder and no template instruction line survives |
-| A path resolves outside the chosen target | the run stops and reports that path |
+5. **Place.** Write once per confirmed target using [tool-write.md](../references/tool-write.md), stopping if a path escapes the workspace or target or enters a plugin install directory.
+6. **Read back.** Check the tree and every file against the contract, removing placeholders and scaffold instructions before validation.
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md b/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md
index fca3dacbb..9f9af8f1e 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md
@@ -8,18 +8,10 @@ The skill written by 03.
 
 ## Output
 
-A report, one row per file: what was checked and any fix applied.
+A report, one row per written file: checks, findings or none, and fixes applied.
 
 ## Process
 
 1. **Review.** Review each file against [review-protocol.md](../references/review-protocol.md).
-2. **Fix.** Apply the confirmed fixes on disk, then re-review the changed files.
-3. **Report.** Deliver the findings, even when clean.
-
-## Test
-
-| Case | Pass |
-| --- | --- |
-| The report is delivered | every written file has a row, with its findings or none |
-| The review finds a breach | it names the broken rule and a `file:line` |
-| A fix is confirmed | the file differs on disk and is reviewed again |
+2. **Fix.** Apply the confirmed fixes on disk, read them back, and re-review until no breach remains.
+3. **Report.** Deliver the report, even when clean.
diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md
index be7d9cc99..5cd1e1637 100644
--- a/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md
+++ b/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md
@@ -13,12 +13,10 @@
 ## Process
 
 1. **<Label>.** <Imperative step. Sub-bullet for a branch or a loop back.>
-2. **<Label>.** <Next step.>
+2. **<Check>.** <Run the observable success check and handle failure.>
 
-## Test
+## Rules
 
-| Case | Pass |
-| --- | --- |
-| <what is run> | <the observable result it gives> |
+- **<Label>.** <Constraint not owned by a process step. Omit this section when none.>
 
 > Fill every `<...>` and delete this line. An angle bracket left in the written file is a bug.
diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
index 0bbf97f49..782809305 100644
--- a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
+++ b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
@@ -23,6 +23,6 @@ Run the flow above. Read only the next action file.
 
 <Rules owned by no reference or single action, one per line.>
 
-- <rule>
+- **<Label>.** <rule>
 
 > Fill every `<...>` and delete this line. An angle bracket left in the written file is a bug.
diff --git a/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md b/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md
index 31635008c..ebe106ad9 100644
--- a/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md
+++ b/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md
@@ -1,24 +1,10 @@
 # Scope frame
 
-The fields a scoped skill must define.
-
-- subject:
-- purpose: one sentence.
-- name: kebab-case.
-- flow: visible user journey.
-- mode: optional, `auto` or `interactive`.
-- target: detected tool, plugin source, or dedicated tool.
-
-Modes:
-
-- `auto`: runs through the flow without planned user checkpoints.
-- `interactive`: pauses for user input at defined checkpoints.
-
-Output shape:
-
-- subject:
-- purpose:
-- name:
-- flow:
-- mode: omit when absent.
-- target:
+Fill these fields; omit mode when absent.
+
+- **Subject.** Domain.
+- **Purpose.** One sentence.
+- **Name.** Kebab-case.
+- **Flow.** Visible user journey.
+- **Mode.** `auto` runs without planned checkpoints; `interactive` pauses for user input.
+- **Target.** Detected tool, plugin source, or dedicated tool.
diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
index 9170aefa1..48ed25bba 100644
--- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
+++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
@@ -20,9 +20,9 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 
 ## An action
 
-- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, `## Test`. A section earns its content or is omitted, never invented or reordered.
-- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
-- **R13.** `## Test` is a `| Case | Pass |` table, each row observable by real execution, never a mock.
+- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, and optional `## Rules`. A section earns its content or is omitted, never invented or reordered.
+- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number. Every instruction bullet starts with a bold label. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
+- **R13.** Verify observable success in `## Process` through real execution. `## Rules` holds only constraints no process step owns; no separate `## Test` or duplicated checks.
 
 ## A reference
 
@@ -36,5 +36,5 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 ## Across all of them
 
 - **R17.** One fact, one home. An action acts within a router rule and cites a shared reference, never restating either.
-- **R18.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those. It sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Test` line to conform to it. Never a block or a line of its own.
+- **R18.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those. It sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Rules` line to conform to it. Never a block or a line of its own.
 - **R19.** One file, one artifact. Split two apart only when a path needs one without the other.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
index d3970fdb2..a970409fc 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
@@ -10,7 +10,7 @@ Plan `status: implemented`, with integrated acceptance and validation evidence.
 
 ## Process
 
-1. **Verify.** Check every plan-level acceptance criterion and required validation on the integrated candidate; return failures to execution and revalidate repairs.
+1. **Verify.** Check the source outcome, phase criteria, and required validation together on the integrated candidate; return failures to execution and revalidate repairs.
 2. **Mark.** Set the plan `status: implemented` only when all required checks pass.
 
 ## Rules
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index e9ecb3ab1..565bb028b 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -3,8 +3,8 @@
 ## Behavior
 
 - **Plan:** reconcile scoped exploration, then produce the implementation plan.
-- **Assign:** retain shared lifecycle and integration; delegate independent phases with their criteria, prerequisites, status-file ownership, checkout, resources, and commit policy. Use separate checkouts for parallel writers; otherwise run serially. A whole-plan executor may own all lifecycle statuses, never scope or criteria.
-- **Integrate:** accept scoped changes and evidence before starting dependents; finalize against the combined candidate, with required end-to-end checks last. Reuse only evidence still valid for that candidate and scope.
+- **Assign:** own preparation, shared lifecycle, and integration; delegate only phases with their criteria, prerequisites, status-file ownership, checkout, resources, and commit policy. Use separate checkouts for parallel writers; otherwise run serially.
+- **Integrate:** accept scoped changes and evidence before starting dependents; complete required end-to-end checks before finalizing. Reuse only evidence still valid for that candidate and scope.
 - **Handoff:** commit and push through the commit capability; send the clean candidate and evidence to Check.
 
 ```mermaid
@@ -25,8 +25,9 @@ flowchart TD
     Executor(["@aidd-dev:executor"])
     Implement["/aidd-dev:02-implement"]
     Assert["/aidd-dev:03-assert"]
-    Integrate["Integrate phases and finalize plan"]
+    Integrate["Integrate phases"]
     Test["/aidd-dev:06-test"]
+    Finalize["Finalize integrated plan"]
     Commit["/aidd-vcs:01-commit"]
   end
 
@@ -40,14 +41,16 @@ flowchart TD
   Plan --> PlanArtifact
   PlanArtifact --> Dispatch
   Dispatch -- "Isolated executors for independent phases; serial otherwise." --> Executor
-  Executor --> Implement
+  Executor -- "Assigned phase only." --> Implement
   Implement --> Assert
   Assert --> Integrate
   Integrate -- "More ready phases." --> Dispatch
-  Integrate -- "No required end-to-end journey." --> Commit
+  Integrate -- "No required end-to-end journey." --> Finalize
   Integrate -- "Run required end-to-end journey last." --> Test
-  Test -- "After the journey succeeds, commit the result." --> Commit
+  Test -- "Journey passed." --> Finalize
   Test -- "Return a failed journey for repair." --> Executor
+  Finalize -- "Acceptance failed; repair affected phase." --> Executor
+  Finalize --> Commit
   Commit --> CommittedCandidate
   CommittedCandidate --> Check
 
diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md
index 9212c98ac..45167c885 100644
--- a/plugins/aidd-refine/CATALOG.md
+++ b/plugins/aidd-refine/CATALOG.md
@@ -48,8 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 |-------|------|---|
 | `actions` | [01-challenge.md](skills/02-challenge/actions/01-challenge.md) | - |
 | `assets` | [report-template.md](skills/02-challenge/assets/report-template.md) | - |
-| `references` | [confidence-rubric.md](skills/02-challenge/references/confidence-rubric.md) | - |
-| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.` |
+| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Challenge completed work against its intent and contracts. Use when the user wants to critically review recent work, find essential gaps, or simplify it. Not for line-by-line style review or writing code.` |
 
 #### `skills/03-shadow-areas`
 
diff --git a/plugins/aidd-refine/README.md b/plugins/aidd-refine/README.md
index 4b3d462ef..23cfda934 100644
--- a/plugins/aidd-refine/README.md
+++ b/plugins/aidd-refine/README.md
@@ -15,7 +15,7 @@ Five skills that refine inputs and outputs through reflection: clarify vague req
 | Bracket ID | Skill      | Description                                                                                                                                                                                   |
 | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [5.1]      | [brainstorm](skills/01-brainstorm/SKILL.md) | Clarify a vague product or technical intent through natural discovery, converging until the idea is precise enough to act on.                            |
-| [5.2]      | [challenge](skills/02-challenge/SKILL.md)  | Rethink prior work to verify correctness against an agreed plan, classifying findings with a confidence score.                                                                                |
+| [5.2]      | [challenge](skills/02-challenge/SKILL.md)  | Challenge completed work against its intent and contracts; report evidenced blockers and minimal improvements. |
 | [5.3]      | [shadow-areas](skills/03-shadow-areas/SKILL.md) | Analytical scan of a written artifact for blind spots: each gap is classified by category and severity, paired with a direct-question probe.                                              |
 | [5.4]      | [fact-check](skills/04-fact-check/SKILL.md) | Verify factual claims against authoritative sources and rewrite the text with footnote citations, hedging anything that cannot be confirmed.                                              |
 | [5.5]      | [improve](skills/05-improve/SKILL.md) | Read complete conversation evidence, recommend targeted improvements, and propose minimal file edits. |
diff --git a/plugins/aidd-refine/skills/02-challenge/SKILL.md b/plugins/aidd-refine/skills/02-challenge/SKILL.md
index 4e1a03c58..f2bb35e6e 100644
--- a/plugins/aidd-refine/skills/02-challenge/SKILL.md
+++ b/plugins/aidd-refine/skills/02-challenge/SKILL.md
@@ -1,31 +1,20 @@
 ---
 name: 02-challenge
-description: Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.
+description: Challenge completed work against its intent and contracts. Use when the user wants to critically review recent work, find essential gaps, or simplify it. Not for line-by-line style review or writing code.
 argument-hint: work
 ---
 
 # Challenge
 
-Rethink prior work and surface what is wrong, missing, or duplicated. Output a structured report with a confidence score so the user knows whether to ship, iterate, or rework.
+```mermaid
+flowchart LR
+  Work([work]) --> challenge --> Report([report])
+```
 
 ## Actions
 
-| #   | Action      | Role                                                          | Input                          |
-| --- | ----------- | ------------------------------------------------------------- | ------------------------------ |
-| 01  | `challenge` | Rethink prior work, classify findings, score confidence       | the work + agreed reference    |
+Read the next action file.
 
-Before running an action, read its file in `actions/`, not only the table or assets.
-
-## Transversal rules
-
-- Reason from first principles, no logical gaps.
-- Aim for simplifications. If the work can be smaller, say so.
-- Fill `assets/report-template.md` verbatim.
-
-## References
-
-- `references/confidence-rubric.md`: tiered rubric for the confidence percentage.
-
-## Assets
-
-- `assets/report-template.md`: findings report skeleton, filled per run.
+| Action | Does |
+| --- | --- |
+| challenge | challenge intent, contracts, and unnecessary complexity |
diff --git a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md
index 6e7030fc1..cb63b1e2c 100644
--- a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md
+++ b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md
@@ -1,31 +1,23 @@
 # 01 - Challenge
 
-Rethink prior work and verify correctness against an agreed plan, then emit a structured findings report.
-
 ## Input
 
-- The work to review: the last answer, specific files, a plan, or a commit range.
-- The agreed reference to judge it against: a plan, a spec, or stated requirements. Without one, judge against stated user intent.
+- **Work:** the last answer, files, a plan, or a commit range.
+- **Reference:** the agreed plan, spec, or stated user intent.
 
 ## Output
 
-The findings report following [report-template.md](../assets/report-template.md): a confidence percentage plus the Correctness, Deal breakers, and Suggestions sections.
+The evidence-backed verdict and findings in [report-template.md](../assets/report-template.md).
 
 ## Process
 
-1. **Align.** Read the work and line it up against the agreed reference.
-2. **Challenge.** Challenge own assumptions and the user's decisions.
-3. **Trust.** Answer internally:
-   - "Am I proud of the work delivered?"
-   - "Am I confident in every consequential choice that was made?"
-   - "Will the user be satisfied with the real end-to-end outcome?"
-4. **Scan.** Scan for edge cases, errors, gaps, duplications, and inconsistencies.
-5. **Classify.** Classify each finding as Correctness, Deal breaker, or Suggestion.
-6. **Score.** Score confidence per the rubric in [confidence-rubric.md](../references/confidence-rubric.md).
-7. **Emit.** Fill [report-template.md](../assets/report-template.md) verbatim and emit it.
-
-## Test
-
-- The report has a confidence percentage and the Correctness, Deal breakers, and Suggestions sections.
-- The Deal breakers section is non-empty only when confidence is below 75%.
-- A negative or uncertain trust answer produces a deal breaker and confidence below 75%.
+1. **Trace.** Compare the work with the reference and actual contracts of the capabilities it invokes.
+2. **Challenge.** Find outcome failures, unsupported assumptions, essential gaps, contradictions, and removable duplication.
+3. **Classify.** Separate blockers to the intended outcome from optional suggestions, linking each to evidence and the smallest fix.
+4. **Report.** Return the template with verified strengths and any evidence limits.
+
+## Rules
+
+- **Read-only:** never modify the work.
+- **Evidence:** mark an unverified claim as such; missing essential evidence blocks a ready verdict.
+- **Simplicity:** prefer removing or consolidating instructions over adding another rule.
diff --git a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
index a611f2554..9d6ffc5f6 100644
--- a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
+++ b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
@@ -1,12 +1,21 @@
-<!-- Challenge findings report skeleton. Fill each section verbatim, keep the header order. -->
+<!-- Replace every placeholder, remove unused rows, write None for empty sections, then remove this comment. Verdict is READY when the intended outcome is supported without blockers, CHANGES REQUIRED for concrete blockers, or BLOCKED when essential evidence is unavailable. -->
 
-My confidence level of correctness now: XX%
+**Verdict:** <READY | CHANGES REQUIRED | BLOCKED>
+**Scope:** <work and reference>
+**Evidence limits:** <unverified essentials or None>
 
-# Correctness (100%)
--
+## Verified
 
-# Deal breakers
--
+- **<strength>:** <supporting evidence>
 
-# Suggestions (enhancements only)
--
+## Blockers
+
+| Finding | Evidence | Minimal fix |
+| --- | --- | --- |
+| <outcome failure or essential evidence gap> | <source, location, or observed result> | <smallest correction> |
+
+## Suggestions
+
+| Finding | Evidence | Minimal improvement |
+| --- | --- | --- |
+| <optional improvement> | <source or observation> | <smallest change> |
diff --git a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
deleted file mode 100644
index 2aece1068..000000000
--- a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Confidence rubric
-
-The challenge action emits a confidence percentage. Pick the tier whose conditions match the findings, then choose a value within that tier.
-
-| Tier      | Condition                                                                                                 |
-| --------- | --------------------------------------------------------------------------------------------------------- |
-| `100%`    | Every trust answer is yes, with no deal breakers, gaps, missing parts, or suggestions.                   |
-| `75-95%`  | Every trust answer is yes, with suggestions only and no blockers.                                       |
-| `50-74%`  | At least one trust answer is negative or uncertain, or minor deal breakers are fixable in place.         |
-| `<50%`    | At least one trust answer exposes a major outcome failure, or major deal breakers require partial rework. |
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 50f9200af..0c77dd8ac 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -17,7 +17,7 @@ test("global instructions exclude project context and use each host's native age
     const content = render(instructionSource, host);
     assert.ok(content.includes(`| ${name} | Implement scope. |`));
     assert.doesNotMatch(content, /Memory|memory|aidd_docs|ARCHITECTURE/);
-    assert.match(content, /Keep scope/);
+    assert.doesNotMatch(content, /Keep scope|## Action|## Behavior|## Communication/);
   }
 });
 
@@ -34,18 +34,48 @@ test("global sync preserves personal rules, updates its block, and is idempotent
     const first = readFileSync(destination, "utf8");
     sync(source, [["codex", destination]]);
     assert.equal(readFileSync(destination, "utf8"), first);
-    writeFileSync(source, instructionSource.replace("Keep scope.", "Check scope."));
+    writeFileSync(source, instructionSource.replace("Implement scope.", "Implement updated scope."));
     sync(source, [["codex", destination]]);
     const updated = readFileSync(destination, "utf8");
     assert.ok(updated.startsWith(personal));
-    assert.match(updated, /Check scope/);
-    assert.doesNotMatch(updated, /Keep scope/);
+    assert.match(updated, /Implement updated scope/);
+    assert.doesNotMatch(updated, /Implement scope\./);
     assert.equal(updated.split("aidd_global_instructions:start").length, 2);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
 
+test("global sync replaces legacy duplicated instructions without changing personal text", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-global-migration-"));
+  try {
+    const source = join(root, "source.md");
+    const destination = join(root, "AGENTS.md");
+    const prefix = "## Behavior\nMy personal rules.\n\n";
+    const suffix = "\n\nMy private closing note.\n";
+    writeFileSync(source, instructionSource);
+    writeFileSync(destination, prefix + "<!-- aidd_global_instructions:start -->\n## Behavior\nLegacy duplicated rules.\n## Communication\nLegacy communication.\n<!-- aidd_global_instructions:end -->" + suffix);
+    sync(source, [["codex", destination]]);
+    const migrated = readFileSync(destination, "utf8");
+    assert.ok(migrated.startsWith(prefix));
+    assert.ok(migrated.endsWith(suffix));
+    assert.doesNotMatch(migrated, /Legacy|Keep scope|## Communication|## Action/);
+    assert.equal(migrated.match(/^## Behavior$/gm).length, 1);
+    assert.match(migrated, /@executor \| Implement scope/);
+    sync(source, [["codex", destination]]);
+    assert.equal(readFileSync(destination, "utf8"), migrated);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("global agent extraction works without project memory and stops at the next section", () => {
+  const source = "## Agents\n| name | role |\n| @executor | Implement scope. |\n\n## Project rules\nNever copy me.\n";
+  assert.match(render(source, "claude"), /@aidd-dev:executor/);
+  assert.doesNotMatch(render(source, "claude"), /Project rules|Never copy/);
+  assert.match(render(source.split("\n## Project rules")[0], "codex"), /Implement scope/);
+});
+
 test("first OpenCode sync retains effective Claude personal rules without its managed block", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-global-fallback-"));
   try {
@@ -68,7 +98,7 @@ test("first OpenCode sync retains effective Claude personal rules without its ma
   }
 });
 
-test("malformed managed blocks and missing memory boundaries leave all global files untouched", () => {
+test("malformed managed blocks and missing agent sections leave all global files untouched", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-global-invalid-"));
   try {
     const source = join(root, "source.md");
@@ -83,7 +113,7 @@ test("malformed managed blocks and missing memory boundaries leave all global fi
       assert.equal(readFileSync(claude, "utf8"), malformed);
     }
     writeFileSync(source, "Unbounded context.\n");
-    assert.throws(() => sync(source, [["codex", codex]]), /Memory Management boundary/);
+    assert.throws(() => sync(source, [["codex", codex]]), /Agents section/);
     assert.equal(readFileSync(codex, "utf8"), "Keep Codex.\n");
   } finally {
     rmSync(root, { recursive: true, force: true });
@@ -109,7 +139,7 @@ function fixture(home) {
         writeFileSync(join(pluginDir, "agents", name), "source agent\n");
       }
     }
-    writeFileSync(join(source, "AGENTS.md"), "# AGENTS.md\n\n## Behavior\nKeep scope.\n\n## Memory Management\nProject-only memory.\n");
+    writeFileSync(join(source, "AGENTS.md"), instructionSource);
   }
   return source;
 }
@@ -163,7 +193,7 @@ test("managed OpenCode reload uses the fixed-purpose helper without a local buil
     assert.equal(result.status, 0, result.stderr);
     assert.match(result.stdout, /reload opencode\s+managed:ok/);
     assert.equal(existsSync(join(home, "build")), false);
-    assert.match(readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8"), /Keep scope/);
+    assert.match(readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8"), /Implement scope/);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -183,7 +213,7 @@ for (const flag of ["OPENCODE_DISABLE_CLAUDE_CODE", "OPENCODE_DISABLE_CLAUDE_COD
       assert.equal(result.status, 0, result.stderr);
       const installed = readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8");
       assert.doesNotMatch(installed, /Excluded Claude/);
-      assert.match(installed, /Keep scope/);
+      assert.match(installed, /Implement scope/);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index f9af1c402..ab1b9cfe9 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -9,8 +9,8 @@
 #
 # Codex caveat: the .codex-plugin manifest does not declare codex-agents/*.toml, and Codex
 # loads agents only from ~/.codex/agents/, so the built TOML is copied there after install.
-# Global rules: replace only the managed AIDD block; exclude project memory and adapt agent
-# names. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
+# Global rules: sync only the Agents section in the managed block, preserving personal
+# rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
 # Instruction paths honor CODEX_HOME, CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME; tests use
 # *_INSTRUCTIONS overrides. Sources checked 2026-10-14:
 # https://developers.openai.com/codex/guides/agents-md
@@ -228,6 +228,6 @@ instruction_fallback="$CLAUDE_INSTRUCTIONS"
 case "${OPENCODE_DISABLE_CLAUDE_CODE:-}" in 1|true) instruction_fallback="" ;; esac
 case "${OPENCODE_DISABLE_CLAUDE_CODE_PROMPT:-}" in 1|true) instruction_fallback="" ;; esac
 node "$SCRIPT_DIR/sync-global-instructions.cjs" "$FW/AGENTS.md" "$instruction_fallback" "${instructions[@]}"
-echo "ok (project memory excluded)"
+echo "ok (agents only)"
 
 echo "Done. Restart Claude/Codex; reload OpenCode configuration for refreshed agents, skills, and instructions."
diff --git a/scripts/sync-global-instructions.cjs b/scripts/sync-global-instructions.cjs
index 3e02feb40..8d09ea23a 100644
--- a/scripts/sync-global-instructions.cjs
+++ b/scripts/sync-global-instructions.cjs
@@ -5,15 +5,16 @@ const start = "<!-- aidd_global_instructions:start -->";
 const end = "<!-- aidd_global_instructions:end -->";
 
 function render(source, host) {
-  const boundary = source.search(/^## Memory Management\s*$/m);
-  if (boundary < 0) throw new Error("AGENTS.md has no Memory Management boundary; refusing global sync");
+  const beginning = source.search(/^## Agents[ \t]*\r?$/m);
+  if (beginning < 0) throw new Error("AGENTS.md has no Agents section; refusing global sync");
+  const boundary = source.indexOf("\n## ", beginning + 1);
   const names = {
     codex: (role) => `@${role}`,
     claude: (role) => `@aidd-dev:${role}`,
     opencode: (role) => `@aidd-dev-${role}`,
   };
   if (!names[host]) throw new Error(`Unknown instruction host: ${host}`);
-  return source.slice(0, boundary).trim().replace(/^.*\bdocs\/ARCHITECTURE\.md.*\n?/gm, "").replace(
+  return source.slice(beginning, boundary < 0 ? undefined : boundary).trim().replace(
     /^\| @([a-z]+)[^|]*\|/gm,
     (_, role) => `| ${names[host](role)} |`,
   );

From 0501847320e3ae67656589628974b57a90143d4f Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 21:57:07 +0800
Subject: [PATCH 09/73] docs(aidd-context): prefer positive skill instructions

---
 .../aidd-context/skills/04-skill-generate/SKILL.md  |  2 +-
 .../04-skill-generate/references/skill-authoring.md | 13 +++++++------
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
index 4f6e262f1..b334781fe 100644
--- a/plugins/aidd-context/skills/04-skill-generate/SKILL.md
+++ b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
@@ -28,4 +28,4 @@ Run the flow above. Read only the next action file.
 - **Entry.** Default to `create`; follow `modify` when asked.
 - **References.** If a cited reference cannot be read, stop and report the missing file.
 - **Confirmation.** Confirm every target and name with the user.
-- **Visibility.** Never write silently.
+- **Visibility.** Announce intended writes before editing.
diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
index 48ed25bba..21542366e 100644
--- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
+++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
@@ -7,7 +7,7 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 - **R1.** One skill, one domain. Named per `naming.md`.
 - **R2.** `name` is not the invocation token: a colon or prefix breaks loading. In prose call a skill `plugin:folder`.
 - **R3.** `description` is the only always-on text: verb-led, third person, about 240 chars, `Use when the user wants to <intents>` and an optional `Not for <X>`. No colon or dash, no other skill or `/command` named.
-- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case, never the action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
+- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case; avoid action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
 - **R5.** English only, one idea per sentence.
 
 ## The router
@@ -20,13 +20,13 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 
 ## An action
 
-- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, and optional `## Rules`. A section earns its content or is omitted, never invented or reordered.
-- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number. Every instruction bullet starts with a bold label. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
+- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, and optional `## Rules`. Omit unnecessary sections; preserve names and order.
+- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. Number sequential steps; use dash sub-items for cases, branches, loops, or constraints. Every instruction bullet starts with a bold label. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
 - **R13.** Verify observable success in `## Process` through real execution. `## Rules` holds only constraints no process step owns; no separate `## Test` or duplicated checks.
 
 ## A reference
 
-- **R14.** References stay flat, nesting one directory deep only as a load boundary. Each stands alone, never pulling in another. It names a sibling in backticks and never links it.
+- **R14.** References stay flat, nesting one directory deep only as a load boundary. Keep each self-contained; name siblings in backticks rather than linking them.
 - **R15.** A reference carries one fact per row: a table, a mermaid, or a list. Prose is what is left when neither fits.
 
 ## An asset
@@ -35,6 +35,7 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 
 ## Across all of them
 
-- **R17.** One fact, one home. An action acts within a router rule and cites a shared reference, never restating either.
-- **R18.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those. It sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Rules` line to conform to it. Never a block or a line of its own.
+- **R17.** One fact, one home. Apply router rules and cite shared references instead of restating them.
+- **R18.** Use relative Markdown links, `[name](path)`, rather than unresolved `@` includes. Place citations in the sentence that uses them: a process step, output, or rule, rather than a standalone block or line.
 - **R19.** One file, one artifact. Split two apart only when a path needs one without the other.
+- **R20.** Prefer positive instructions or `avoid` over `never`. Express mandatory boundaries as explicit conditions.

From 110ac310f4f114762e3817034e318c51e4a8ddd0 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 22:57:52 +0800
Subject: [PATCH 10/73] feat(aidd-dev): align agent roles and preserve personal
 definitions

---
 AGENTS.md                                     |  8 +--
 docs/ARCHITECTURE.md                          |  2 +-
 .../references/agent-authoring.md             |  7 ++-
 plugins/aidd-dev/.claude-plugin/plugin.json   |  2 +-
 plugins/aidd-dev/CATALOG.md                   |  9 +--
 plugins/aidd-dev/agents/checker.md            | 41 -------------
 plugins/aidd-dev/agents/executor.md           | 26 ++++----
 plugins/aidd-dev/agents/explorer.md           | 10 +--
 plugins/aidd-dev/agents/reviewer.md           | 42 +++++++++++++
 plugins/aidd-dev/agents/validator.md          | 10 +--
 .../skills/02-implement/actions/02-execute.md |  2 +-
 plugins/aidd-dev/skills/05-review/SKILL.md    |  4 +-
 .../skills/05-review/actions/01-prepare.md    |  4 +-
 .../05-review/actions/04-review-relevancy.md  |  4 +-
 .../05-review/references/quality-checklist.md |  8 +++
 .../skills/01-sdlc/references/03-check.md     | 12 ++--
 scripts/__tests__/dev-sync.test.js            | 61 +++++++++++++++++--
 scripts/__tests__/sync-codex-agents.test.js   | 46 ++++++++++++++
 scripts/dev-sync.sh                           | 31 +++++++---
 scripts/sync-codex-agents.cjs                 | 46 ++++++++++++++
 scripts/sync-global-instructions.cjs          |  4 +-
 21 files changed, 275 insertions(+), 104 deletions(-)
 delete mode 100644 plugins/aidd-dev/agents/checker.md
 create mode 100644 plugins/aidd-dev/agents/reviewer.md
 create mode 100644 plugins/aidd-dev/skills/05-review/references/quality-checklist.md
 create mode 100644 scripts/__tests__/sync-codex-agents.test.js
 create mode 100644 scripts/sync-codex-agents.cjs

diff --git a/AGENTS.md b/AGENTS.md
index 94caba638..eb1ad4be1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,10 +39,10 @@ Use available agents when useful. The caller owns scope, delegation, and final a
 <!-- aidd_agents:start -->
 | name | role |
 | --- | --- |
-| @explorer (Codex), @aidd-dev-explorer (OpenCode) | Explore scoped questions. Return sourced findings, uncertainties, and risks. Never modify inspected material. |
-| @executor (Codex), @aidd-dev-executor (OpenCode) | Implement assigned scope. Validate, repair failures, and report evidence and blockers. Never change requirements. |
-| @validator (Codex), @aidd-dev-validator (OpenCode) | Validate supplied criteria and mandatory checks. Report PASS, FAIL, or BLOCKED with evidence. Never repair. |
-| @checker (Codex), @aidd-dev-checker (OpenCode) | Review quality, risks, and fitness for the need. Report actionable findings. Never modify the deliverable. |
+| @aidd-dev-explorer (Codex, OpenCode), @aidd-dev:explorer (Claude) | Explore scoped questions and return sourced findings before a decision. |
+| @aidd-dev-executor (Codex, OpenCode), @aidd-dev:executor (Claude) | Implement assigned work and return changes with verification evidence. |
+| @aidd-dev-validator (Codex, OpenCode), @aidd-dev:validator (Claude) | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
+| @aidd-dev-reviewer (Codex, OpenCode), @aidd-dev:reviewer (Claude) | Review quality and coherence against project conventions and the quality checklist. |
 <!-- aidd_agents:end -->
 
 ## Memory Management
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e69f33bc1..89cac000d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -111,7 +111,7 @@ Recipe actions carry inputs, outputs, process steps, and rules.
 | Skill | Host loads `SKILL.md` on invocation; work runs in the caller's context. |
 | Caller | Owns scope, delegation, integration, and acceptance. |
 | Orchestrator | Sequences capabilities on the caller's behalf. |
-| Agent | Isolates work and returns a result. Invokes only declared canonical recipe skills; never invokes orchestrators or reads skill files. |
+| Agent | Isolates work and returns a result. Invokes declared recipe capabilities; reads supporting references while leaving recipe routing and delegation to the caller. |
 | Recipe | Primary callers may delegate bounded work; isolated recipes return to their caller. |
 | Reconnaissance helper | Read-only; neither mutates nor spawns. |
 | Write path | At most two delegation layers; no cycles. |
diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
index 28fae750c..540bb019c 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
@@ -12,17 +12,18 @@ The contract every generated agent must satisfy. An agent is a focused role with
 
 ## Naming
 
-- Short and catchy, a single word where possible: `executor`, `checker`, `auditor`.
+- Short and catchy, a single word where possible: `executor`, `reviewer`, `auditor`.
 - Fits the role at a glance. Propose three options for the user to pick.
 
 ## Body shape
 
 Short imperative sentences. Optional sections, added only when they earn their place:
 
+- `# References`: supporting criteria or checklists, verified accessible after installation.
 - `# Inputs`: what it receives.
 - `# Outputs`: what it returns.
-- `# Guardrails`: what it must never do.
-- `# Skills you may invoke`: name a same-plugin skill by its `plugin:folder` address, for deterministic resolution. Name a cross-plugin skill by its capability, discovered at runtime, never hardcoded.
+- `# Guardrails`: behavioral boundaries.
+- `# Skills you may invoke`: list allowed recipes by canonical `/plugin:folder` address; verify availability before invocation.
 - `# Definition of Ready` / `# Definition of Done`: start and finish gates.
 - `# Decisions in scope` / `# Decisions out of scope`: what it may decide, what it must defer.
 - `# Handoffs`: who it returns to.
diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json
index 89a751848..29136502c 100644
--- a/plugins/aidd-dev/.claude-plugin/plugin.json
+++ b/plugins/aidd-dev/.claude-plugin/plugin.json
@@ -23,7 +23,7 @@
     "./agents/explorer.md",
     "./agents/executor.md",
     "./agents/validator.md",
-    "./agents/checker.md"
+    "./agents/reviewer.md"
   ],
   "keywords": [
     "sdlc",
diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md
index b0198a357..bb5fdc1ae 100644
--- a/plugins/aidd-dev/CATALOG.md
+++ b/plugins/aidd-dev/CATALOG.md
@@ -32,10 +32,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 | File | Description |
 |------|---|
-| [checker.md](agents/checker.md) | `Reviews quality, risks, and fitness for the intended need. Use for an independent judgment of a deliverable. Never edits the work or implements the fix.` |
-| [executor.md](agents/executor.md) | `Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.` |
-| [explorer.md](agents/explorer.md) | `Explores scoped questions and returns sourced findings. Use when a caller needs evidence before deciding. Never modifies the inspected material.` |
-| [validator.md](agents/validator.md) | `Validates an identified deliverable against supplied criteria and mandatory checks. Use for independent completion evidence. Never repairs or performs a general quality review.` |
+| [executor.md](agents/executor.md) | `Implements assigned work within defined scope. Use to build or fix a deliverable, verify the result, and repair failures against the requested outcome.` |
+| [explorer.md](agents/explorer.md) | `Explores scoped questions about code, documentation, or dependencies. Use to investigate a domain, trace behavior, or research evidence before deciding.` |
+| [reviewer.md](agents/reviewer.md) | `Reviews the quality and coherence of a deliverable. Use for a quality check of simplicity, consistency, maintainability, and alignment with project conventions.` |
+| [validator.md](agents/validator.md) | `Validates that delivered work satisfies the original request, acceptance criteria, and mandatory checks. Use to verify the requested outcome and establish completion independently.` |
 
 ### `skills`
 
@@ -97,6 +97,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [04-review-relevancy.md](skills/05-review/actions/04-review-relevancy.md) | - |
 | `actions` | [05-finalize.md](skills/05-review/actions/05-finalize.md) | - |
 | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - |
+| `references` | [quality-checklist.md](skills/05-review/references/quality-checklist.md) | - |
 | `references` | [report-contract.md](skills/05-review/references/report-contract.md) | - |
 | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - |
 | `-` | [SKILL.md](skills/05-review/SKILL.md) | `Reviews a change or a diff and says whether it is ready to ship, naming every problem with its fix. Use when the user wants a change checked before it ships. Not for fixing what the review finds, and not for auditing a whole codebase.` |
diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md
deleted file mode 100644
index 77e4c742d..000000000
--- a/plugins/aidd-dev/agents/checker.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-name: checker
-description: Reviews quality, risks, and fitness for the intended need. Use for an independent judgment of a deliverable. Never edits the work or implements the fix.
----
-
-# Role
-
-Review quality, risks, and fitness for the intended need in a fresh context.
-
-# Behavior
-
-- **Ground.** Read the need, criteria, candidate identity, and validation evidence; flag ambiguity instead of guessing.
-- **Inspect.** Apply the project's checklist; check duplication, contradictions, unnecessary complexity, leftovers, and gaps between intent and result.
-- **Verify.** Reuse validation evidence; repeat targeted checks only when insufficient, inconsistent, or stale.
-- **Report.** Tie findings to evidence and impact; use supplied checklist thresholds without inventing a score.
-- **Reuse.** When a review skill fits, let its report carry findings; reference it below instead of writing a duplicate.
-- **Read only.** Never edit the deliverable or its validator, implement fixes, or delegate.
-
-# Output
-
-Fill this Markdown template; replace placeholders and use `None` for empty fields.
-Use the findings table only when no skill report carries those findings.
-
-```markdown
-## Review: <deliverable>
-
-- **Candidate:** <revision or artifact identity>
-- **Verdict:** <fitness for the need, with decisive reason>
-- **Report:** <skill report path or None>
-- **Blockers:** <missing evidence or ambiguous criteria>
-
-| Finding | Impact | Evidence | Suggested action |
-| --- | --- | --- | --- |
-| <concrete issue> | <consequence> | <path:line or check> | <minimal correction> |
-```
-
-# Skills you may invoke
-
-- **Review.** `/aidd-dev:05-review`
-- **Audit.** `/aidd-dev:04-audit`
-- **Challenge.** `/aidd-refine:02-challenge`
diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md
index 9116bc968..69a290aa1 100644
--- a/plugins/aidd-dev/agents/executor.md
+++ b/plugins/aidd-dev/agents/executor.md
@@ -1,21 +1,21 @@
 ---
 name: executor
-description: Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.
+description: Implements assigned work within defined scope. Use to build or fix a deliverable, verify the result, and repair failures against the requested outcome.
 ---
 
 # Role
 
-Implement the assigned scope. Decide how, never what.
+Implement assigned work, choosing the technique within the agreed outcome and criteria.
 
 # Behavior
 
-- **Scope.** Follow acceptance criteria and project conventions; stop on ambiguity or drift.
-- **Build.** Validate each substep, repair failures, and repeat; debug an unclear cause first.
-- **Complete.** Report COMPLETE only after assigned criteria and mandatory checks pass.
-- **Ownership.** Change only assigned files and lifecycle status; an assigned phase never updates shared-plan status.
+- **Adapt.** Resolve local technical obstacles within owned scope and project conventions; report material choices.
+- **Escalate.** Report ambiguity or changes needed to outcomes, criteria, or dependencies outside owned scope; leave those decisions to the caller.
+- **Build.** Validate affected workflows, repair failures, and repeat; debug an unclear cause first.
+- **Complete.** Report COMPLETE only when every assigned criterion and mandatory check passes; keep unmet criteria and skipped checks visible in remaining work.
+- **Ownership.** Stay within assigned responsibility and write ownership; update shared-plan status only with whole-plan ownership.
 - **Git.** Commit only when authorized and owning the Git index; leave shared operations to the caller.
-- **Report.** Return changes, checks, remaining work, and blockers; disclose skipped checks or placeholders.
-- **Boundary.** Never change requirements, review your own work, or delegate; stop at inaccessible human actions.
+- **Boundary.** Return changes and evidence directly; leave independent review and delegation to the caller, and report inaccessible human actions.
 
 # Output
 
@@ -37,8 +37,8 @@ Fill this Markdown template; replace placeholders and use `None` for empty field
 
 # Skills you may invoke
 
-- **Implement.** `/aidd-dev:02-implement`
-- **Assert.** `/aidd-dev:03-assert`
-- **Test.** `/aidd-dev:06-test`
-- **Debug.** `/aidd-dev:08-debug`
-- **Commit.** `/aidd-vcs:01-commit`
+- `/aidd-dev:02-implement`
+- `/aidd-dev:03-assert`
+- `/aidd-dev:06-test`
+- `/aidd-dev:08-debug`
+- `/aidd-vcs:01-commit`
diff --git a/plugins/aidd-dev/agents/explorer.md b/plugins/aidd-dev/agents/explorer.md
index 15d06d93e..12b00c200 100644
--- a/plugins/aidd-dev/agents/explorer.md
+++ b/plugins/aidd-dev/agents/explorer.md
@@ -1,18 +1,18 @@
 ---
 name: explorer
-description: Explores scoped questions and returns sourced findings. Use when a caller needs evidence before deciding. Never modifies the inspected material.
+description: Explores scoped questions about code, documentation, or dependencies. Use to investigate a domain, trace behavior, or research evidence before deciding.
 ---
 
 # Role
 
-Explore an assigned question or codebase domain for the caller's decision.
+Explore an assigned question or domain and return evidence for the caller's decision.
 
 # Behavior
 
-- **Trace.** Read relevant code and sources, including relationships across the assigned domain's boundary.
+- **Trace.** Inspect relevant sources and relationships across the assigned domain's boundary.
 - **Ground.** Separate observations from inference; cite file lines or source URLs.
-- **Bound.** Report uncertainty and risks without expanding scope or deciding implementation.
-- **Read only.** Never mutate inspected material, implement, delegate, or invoke an orchestrator.
+- **Bound.** Report uncertainty and risks; leave implementation decisions to the caller.
+- **Read only.** Keep inspected material unchanged and return findings directly without delegation.
 
 # Output
 
diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md
new file mode 100644
index 000000000..78139b846
--- /dev/null
+++ b/plugins/aidd-dev/agents/reviewer.md
@@ -0,0 +1,42 @@
+---
+name: reviewer
+description: Reviews the quality and coherence of a deliverable. Use for a quality check of simplicity, consistency, maintainability, and alignment with project conventions.
+---
+
+# Role
+
+Review whether the delivered parts form a coherent, simple whole that fits the project.
+
+# Behavior
+
+- **Ground.** Read the need, candidate identity, project conventions, and existing validation evidence; flag ambiguity.
+- **Inspect.** Locate the installed quality-review skill and read its supporting `references/quality-checklist.md`; apply it alongside project review rules, justifying non-applicable items. Report an unavailable reference as a coverage blocker.
+- **Scope.** Assess quality and coherence; leave functional acceptance to the validator. Reuse validation evidence, repeating targeted checks only when insufficient, inconsistent, or stale.
+- **Report.** Tie findings to evidence and impact; apply supplied thresholds without inventing scores.
+- **Reuse.** Invoke an appropriate review skill through the host for code quality or relevancy; let its report carry findings instead of duplicating them.
+- **Read only.** Keep the deliverable unchanged and return findings directly; leave repairs and delegation to the caller.
+
+# Output
+
+Fill this Markdown template; replace placeholders and use `None` for empty fields.
+Use the findings table only when no skill report carries those findings.
+
+```markdown
+## Review: <deliverable>
+
+- **Candidate:** <revision or artifact identity>
+- **Verdict:** <quality and coherence, with decisive reason>
+- **Coverage:** <checklist location and justified non-applicable items>
+- **Report:** <skill report path or None>
+- **Blockers:** <missing evidence or ambiguous criteria>
+
+| Finding | Impact | Evidence | Suggested action |
+| --- | --- | --- | --- |
+| <concrete issue> | <consequence> | <path:line or check> | <minimal correction> |
+```
+
+# Skills you may invoke
+
+- `/aidd-dev:05-review`
+- `/aidd-dev:04-audit`
+- `/aidd-refine:02-challenge`
diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
index 0bb88a669..f009908dc 100644
--- a/plugins/aidd-dev/agents/validator.md
+++ b/plugins/aidd-dev/agents/validator.md
@@ -1,20 +1,20 @@
 ---
 name: validator
-description: Validates an identified deliverable against supplied criteria and mandatory checks. Use for independent completion evidence. Never repairs or performs a general quality review.
+description: Validates that delivered work satisfies the original request, acceptance criteria, and mandatory checks. Use to verify the requested outcome and establish completion independently.
 ---
 
 # Role
 
-Validate an identified candidate against supplied criteria and mandatory checks.
+Validate completion of the requested outcome on an identified candidate.
 
 # Behavior
 
-- **Identify.** Record the candidate and confirm criteria, prerequisites, and mandatory checks.
-- **Check.** Run every mandatory check and the smallest sufficient observable checks; record evidence for each result.
+- **Identify.** Record the candidate, original request, criteria, prerequisites, and mandatory checks.
+- **Check.** Run mandatory checks and sufficient observable checks of the requested outcome; record evidence for each result.
 - **Complete.** Report COMPLETE only when all criteria and mandatory checks pass on an unchanged candidate.
 - **Block.** Report BLOCKED for absent, ambiguous, or unobservable criteria, missing prerequisites, or stale evidence.
 - **Fail.** Report INCOMPLETE for failures when no blocker prevents a reliable conclusion.
-- **Boundary.** Never accept an implementer's claim as evidence, repair, change criteria, review quality, or delegate; normal temporary check artifacts are allowed.
+- **Boundary.** Base conclusions on observed evidence. Keep the candidate and criteria unchanged; leave repairs, quality review, and delegation to the caller. Temporary check artifacts are allowed.
 
 # Output
 
diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index 794807658..e07ef5669 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -21,5 +21,5 @@ Validated phases, `status: done`, workflow evidence and checked revision, or a b
 
 - **Evidence.** Exercise every acceptance criterion through the real affected interface (browser, CLI, API…); compare actual and expected behavior at every step. Repair mismatches and restart the affected workflow from the beginning; require a full successful run with observable evidence before a task commit or `done`.
 - **Readiness.** Missing/contradictory dependencies or unfinished phases with none ready require `replan needed`, not skipped work or completion.
-- **Drift.** If satisfying criteria requires changing scope or requirements, stop affected work and report `replan needed: <reason>`; leave replanning to the caller.
+- **Drift.** Adapt implementation within owned responsibility; report changes needed to requested outcomes, criteria, or cross-owner dependencies as `replan needed: <reason>` and stop affected work.
 - **Blocked.** Follow [blocked.md](../references/blocked.md); assigned executors report, the whole-plan owner records plan `status: blocked` under commit policy. Leave unfinished code uncommitted; blocked validation is not success.
diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md
index 8ee340517..746ab25e0 100644
--- a/plugins/aidd-dev/skills/05-review/SKILL.md
+++ b/plugins/aidd-dev/skills/05-review/SKILL.md
@@ -9,8 +9,8 @@ argument-hint: diff | plan
 ```mermaid
 flowchart LR
   all([all axes]) --> prepare
-  one([one axis named]) --> prepare
-  prepare --> review-code & review-functional & review-relevancy --> finalize
+  one([selected axes]) --> prepare
+  prepare -->|selected only| review-code & review-functional & review-relevancy --> finalize
   finalize --> approve([approve])
   finalize --> changes([changes-requested])
   finalize --> blocked([blocked])
diff --git a/plugins/aidd-dev/skills/05-review/actions/01-prepare.md b/plugins/aidd-dev/skills/05-review/actions/01-prepare.md
index d5454a8b7..31c503329 100644
--- a/plugins/aidd-dev/skills/05-review/actions/01-prepare.md
+++ b/plugins/aidd-dev/skills/05-review/actions/01-prepare.md
@@ -13,7 +13,7 @@ A round appended to the report, and the diff the axes read.
 ## Process
 
 1. **Resolve.** Resolve the diff and the report per [report-contract.md](../references/report-contract.md).
-2. **Open.** Append a round from the template `report-contract.md` names, filling what is known before the axes run.
+2. **Open.** Append a round from the template `report-contract.md` names, recording the selected axes and filling what is known before they run.
 3. **Hand over.** Name the diff and the round the axes write into.
 
 ## Test
@@ -22,4 +22,4 @@ A round appended to the report, and the diff the axes read.
 | --- | --- |
 | A fresh report | round 1 appended, its date as the start date |
 | A report holding two rounds | a third appended, the header counting 3, the first two unchanged |
-| A run naming one axis | the round names that axis alone |
+| A run naming axes | the round names and runs only those axes |
diff --git a/plugins/aidd-dev/skills/05-review/actions/04-review-relevancy.md b/plugins/aidd-dev/skills/05-review/actions/04-review-relevancy.md
index 9fb090b8b..fc0ecd872 100644
--- a/plugins/aidd-dev/skills/05-review/actions/04-review-relevancy.md
+++ b/plugins/aidd-dev/skills/05-review/actions/04-review-relevancy.md
@@ -13,10 +13,10 @@ The round's misfit findings, each with its lens as kind.
 ## Process
 
 1. **Gather.** Capture the need, and read the project's declared rules, never assuming one.
-2. **Flag.** Record each misfit under its lens, tied to a rule, a site or the need; a bare opinion is no finding.
+2. **Flag.** Apply [quality-checklist.md](../references/quality-checklist.md); record each misfit under its lens, tied to a rule, a site or the need.
    - `fit`: drift from the real intent, end to end, not only the literal criteria.
    - `conform`: a violation of a declared rule, naming it.
-   - `rot`: duplication, over-engineering or incoherence, citing the site.
+   - `rot`: a quality-checklist issue, citing the site.
 
 ## Test
 
diff --git a/plugins/aidd-dev/skills/05-review/references/quality-checklist.md b/plugins/aidd-dev/skills/05-review/references/quality-checklist.md
new file mode 100644
index 000000000..7bf417ae8
--- /dev/null
+++ b/plugins/aidd-dev/skills/05-review/references/quality-checklist.md
@@ -0,0 +1,8 @@
+# Quality checklist
+
+Apply relevant items alongside project review rules; justify non-applicable items.
+
+- [ ] **Duplication:** each fact or responsibility has one canonical home.
+- [ ] **Consistency:** components, names, documentation, and project conventions agree.
+- [ ] **Simplicity:** complexity serves the need; abstractions have a current use.
+- [ ] **Residue:** obsolete code, debug leftovers, silent TODOs, and placeholders are absent.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index 07c2ebdfe..3c24c30de 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -3,8 +3,8 @@
 ## Behavior
 
 - **Validate:** dispatch a fresh validator on the committed candidate, contract, criteria, and mandatory checks.
-- **Review:** after validation passes, dispatch a fresh checker independent from implementation to review quality using that evidence.
-- **Challenge:** after review clears, the same checker challenges whether the outcome is trustworthy and serves the user.
+- **Review:** after validation passes, dispatch a fresh reviewer for quality and coherence; select code and relevancy axes, using the validator's acceptance evidence.
+- **Challenge:** after review clears, the same reviewer challenges whether the outcome is trustworthy and serves the user.
 
 ## Findings
 
@@ -32,7 +32,7 @@ flowchart TD
     CommittedCandidate["$committed_candidate"]
     ValidationReports["$validation_reports"]
     Validator(["@aidd-dev:validator"])
-    Checker(["@aidd-dev:checker"])
+    Reviewer(["@aidd-dev:reviewer"])
     Review["/aidd-dev:05-review"]
   end
 
@@ -59,9 +59,9 @@ flowchart TD
   Plan --> Validator
   CommittedCandidate --> Validator
   ValidationReports --> Validator
-  Validator -- "All criteria pass with evidence." --> Checker
+  Validator -- "All criteria pass with evidence." --> Reviewer
   Validator -- "Fail or blocked." --> Findings
-  Checker --> Review
+  Reviewer -- "Code and relevancy axes." --> Review
   Review -- "Return actionable review findings." --> Findings
   Review -- "When the review clears, challenge the outcome." --> Challenge
   Challenge -- "Return actionable challenge findings." --> Findings
@@ -78,7 +78,7 @@ flowchart TD
   classDef zone fill:#F1F5F9,stroke:#64748B,color:#0F172A,stroke-width:2px
 
   class Review,Challenge,Batch,PullRequest skill
-  class Checker,Validator agent
+  class Reviewer,Validator agent
   class Contract,Plan,CommittedCandidate,ValidationReports,Findings,PullRequestUrl artifact
   class Frame,Deliver zone
 ```
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 0c77dd8ac..739ebba60 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -13,7 +13,7 @@ const buildDevAgents = devAgents.map((name) => `printf '%s\\n' 'updated agent' >
 const instructionSource = "# AGENTS.md\n\n## Action\n- Keep scope.\n- Follow `docs/ARCHITECTURE.md`.\n\n## Agents\n| name | role |\n| --- | --- |\n| @executor (Codex), @aidd-dev-executor (OpenCode) | Implement scope. |\n\n## Memory Management\nProject docs live in aidd_docs/.\n<!-- aidd_project_memory:start -->\n@aidd_docs/memory/private.md\n<!-- aidd_project_memory:end -->\nLoad more memory.\n";
 
 test("global instructions exclude project context and use each host's native agent names", () => {
-  for (const [host, name] of [["codex", "@executor"], ["claude", "@aidd-dev:executor"], ["opencode", "@aidd-dev-executor"]]) {
+  for (const [host, name] of [["codex", "@aidd-dev-executor"], ["claude", "@aidd-dev:executor"], ["opencode", "@aidd-dev-executor"]]) {
     const content = render(instructionSource, host);
     assert.ok(content.includes(`| ${name} | Implement scope. |`));
     assert.doesNotMatch(content, /Memory|memory|aidd_docs|ARCHITECTURE/);
@@ -61,7 +61,7 @@ test("global sync replaces legacy duplicated instructions without changing perso
     assert.ok(migrated.endsWith(suffix));
     assert.doesNotMatch(migrated, /Legacy|Keep scope|## Communication|## Action/);
     assert.equal(migrated.match(/^## Behavior$/gm).length, 1);
-    assert.match(migrated, /@executor \| Implement scope/);
+    assert.match(migrated, /@aidd-dev-executor \| Implement scope/);
     sync(source, [["codex", destination]]);
     assert.equal(readFileSync(destination, "utf8"), migrated);
   } finally {
@@ -229,7 +229,7 @@ test("reload delivers global instructions to all three hosts while preserving pe
     mkdirSync(home);
     const source = fixture(home);
     writeFileSync(join(source, "AGENTS.md"), instructionSource);
-    const destinations = [[".codex/AGENTS.md", "@executor"], [".claude/CLAUDE.md", "@aidd-dev:executor"], [".config/opencode/AGENTS.md", "@aidd-dev-executor"]];
+    const destinations = [[".codex/AGENTS.md", "@aidd-dev-executor"], [".claude/CLAUDE.md", "@aidd-dev:executor"], [".config/opencode/AGENTS.md", "@aidd-dev-executor"]];
     for (const [path] of destinations) {
       mkdirSync(dirname(join(home, path)), { recursive: true });
       writeFileSync(join(home, path), "Personal rules.\n");
@@ -481,12 +481,63 @@ for (const host of ["codex", "claude"]) {
       mkdirSync(fakeBin);
       executable(join(fakeBin, host), `if [ "$1" = plugin ] && [ "$2" = ${host === "codex" ? "add" : "install"} ]; then exit 8; fi\nexit 0`);
       executable(join(fakeBin, "npx"), "exit 0");
-      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      const result = runSync(fakeBin, home, ["aidd-pm"]);
       assert.notEqual(result.status, 0);
-      assert.match(result.stderr, /plugin install failed for aidd-dev/);
+      assert.match(result.stderr, /plugin install failed for aidd-pm/);
       assert.doesNotMatch(result.stdout, /Done\./);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
   });
 }
+
+test("Codex reload rejects missing built agents before replacing the previous cache", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-incomplete-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    const cached = join(home, ".codex/plugins/cache/aidd-framework/aidd-dev/2.6.0/codex-agents/checker.toml");
+    mkdirSync(dirname(cached), { recursive: true });
+    writeFileSync(cached, "old cached agent\n");
+    executable(join(fakeBin, "codex"), "exit 0");
+    executable(join(fakeBin, "npx"), "exit 0");
+    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /no built Codex agent/);
+    assert.equal(readFileSync(cached, "utf8"), "old cached agent\n");
+    assert.doesNotMatch(result.stdout, /Done\./);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Codex reload namespaces renamed roles and retires only cache-matched short names", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-migration-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin); mkdirSync(home);
+    const source = fixture(home);
+    rmSync(join(source, "plugins/aidd-dev/agents/checker.md"));
+    writeFileSync(join(source, "plugins/aidd-dev/agents/reviewer.md"), "new reviewer\n");
+    const cached = join(home, ".codex/plugins/cache/aidd-framework/aidd-dev/2.6.0/codex-agents/checker.toml");
+    const agents = join(home, ".codex/agents");
+    mkdirSync(dirname(cached), { recursive: true }); mkdirSync(agents, { recursive: true });
+    const legacy = 'name = "checker"\ndescription = "Legacy"\n';
+    writeFileSync(cached, legacy); writeFileSync(join(agents, "checker.toml"), legacy);
+    writeFileSync(join(agents, "reviewer.toml"), "personal reviewer\n");
+    executable(join(fakeBin, "codex"), "exit 0");
+    executable(join(fakeBin, "npx"), String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--out" ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/plugins/aidd-dev/codex-agents"
+for role in reviewer executor; do
+  printf 'name = "%s"\ndescription = "New role"\n' "$role" > "$out/plugins/aidd-dev/codex-agents/$role.toml"
+done`);
+    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(existsSync(join(agents, "checker.toml")), false);
+    assert.equal(readFileSync(join(agents, "reviewer.toml"), "utf8"), "personal reviewer\n");
+    assert.match(readFileSync(join(agents, "aidd-dev-reviewer.toml"), "utf8"), /^name = "aidd-dev-reviewer"/);
+    assert.match(readFileSync(join(agents, "aidd-dev-executor.toml"), "utf8"), /^name = "aidd-dev-executor"/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
diff --git a/scripts/__tests__/sync-codex-agents.test.js b/scripts/__tests__/sync-codex-agents.test.js
new file mode 100644
index 000000000..325d67c8a
--- /dev/null
+++ b/scripts/__tests__/sync-codex-agents.test.js
@@ -0,0 +1,46 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { sync } = require('../sync-codex-agents.cjs');
+function fixture(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-agent-sync-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const dirs = ['built', 'installed', 'snapshot/2.6.0/codex-agents'].map(name => path.join(root, name));
+  dirs.forEach(dir => fs.mkdirSync(dir, { recursive: true }));
+  const [built, installed, old] = dirs;
+  const put = (dir, name, text) => fs.writeFileSync(path.join(dir, name), text);
+  const run = () => sync('aidd-dev', built, installed, path.join(root, 'snapshot'));
+  return { built, installed, old, put, run };
+}
+const agent = name => `name = "${name}"\ndescription = "Task"\n`;
+test('namespace roles and preserve personal and modified short agents', t => {
+  const f = fixture(t);
+  f.put(f.built, 'reviewer.toml', agent('reviewer'));
+  f.put(f.old, 'checker.toml', agent('checker'));
+  f.put(f.old, 'executor.toml', agent('executor'));
+  f.put(f.installed, 'checker.toml', agent('checker'));
+  f.put(f.installed, 'executor.toml', agent('executor') + '# personal modification\n');
+  f.put(f.installed, 'reviewer.toml', '# personal reviewer\n');
+  f.put(f.installed, 'aidd-dev-checker.toml', agent('aidd-dev-checker'));
+  f.put(f.installed, 'other-checker.toml', agent('other-checker'));
+  f.run();
+  assert.deepEqual(fs.readdirSync(f.installed).sort(), ['aidd-dev-reviewer.toml', 'executor.toml', 'other-checker.toml', 'reviewer.toml']);
+  assert.equal(fs.readFileSync(path.join(f.installed, 'reviewer.toml'), 'utf8'), '# personal reviewer\n');
+  assert.equal(fs.readFileSync(path.join(f.installed, 'aidd-dev-reviewer.toml'), 'utf8'), agent('aidd-dev-reviewer'));
+  const once = fs.readdirSync(f.installed).map(name => [name, fs.readFileSync(path.join(f.installed, name), 'utf8')]);
+  f.run();
+  assert.deepEqual(fs.readdirSync(f.installed).map(name => [name, fs.readFileSync(path.join(f.installed, name), 'utf8')]), once);
+});
+test('malformed build leaves every installed agent unchanged', t => {
+  const f = fixture(t);
+  f.put(f.built, 'good.toml', agent('good'));
+  f.put(f.built, 'invalid.toml', 'description = "Missing name"\n');
+  f.put(f.old, 'checker.toml', agent('checker'));
+  f.put(f.installed, 'checker.toml', agent('checker'));
+  f.put(f.installed, 'aidd-dev-stale.toml', agent('aidd-dev-stale'));
+  assert.throws(f.run, /Invalid generated agent/);
+  assert.deepEqual(fs.readdirSync(f.installed).sort(), ['aidd-dev-stale.toml', 'checker.toml']);
+  assert.equal(fs.readFileSync(path.join(f.installed, 'checker.toml'), 'utf8'), agent('checker'));
+});
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index ab1b9cfe9..582fefa69 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -8,7 +8,8 @@
 # exposes `aidd-opencode-reload` instead, and that helper decides which checkout may load.
 #
 # Codex caveat: the .codex-plugin manifest does not declare codex-agents/*.toml, and Codex
-# loads agents only from ~/.codex/agents/, so the built TOML is copied there after install.
+# loads agents only from ~/.codex/agents/, so install namespaced TOML there. Retire old
+# short names only when identical to the previous plugin cache; preserve personal agents.
 # Global rules: sync only the Agents section in the managed block, preserving personal
 # rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
 # Instruction paths honor CODEX_HOME, CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME; tests use
@@ -74,6 +75,18 @@ validate_opencode_content() {
   done
 }
 
+validate_codex_agents() {
+  local name agent
+  for name in "$@"; do
+    for agent in "$FW/plugins/$name/agents/"*.md; do
+      if [ ! -s "$BUILD/codex/plugins/$name/codex-agents/$(basename "$agent" .md).toml" ]; then
+        echo "no built Codex agent for $name-$(basename "$agent" .md)" >&2
+        return 1
+      fi
+    done
+  done
+}
+
 sync_opencode_skills() {
   # Accept nested and legacy flat builds; preserve personal and unselected plugin content.
   local name source skill destination
@@ -128,16 +141,19 @@ sync_one() {
   printf '%-22s' "$name"
 
   if [ "$HAVE_CODEX" = 1 ]; then
+    local previous cached version
+    previous="$(mktemp -d "$BUILD/codex-previous-$name.XXXXXX")"
+    for cached in "$CODEX_CACHE/$MKT/$name/"*/codex-agents/; do
+      version="$(basename "$(dirname "$cached")")"
+      mkdir -p "$previous/$version"
+      cp -R "$cached" "$previous/$version/codex-agents"
+    done
     codex plugin remove "$name" >/dev/null 2>&1 || true
     rm -rf "$CODEX_CACHE/$MKT/$name"
     if codex plugin add "$name@$MKT" >/dev/null 2>&1; then
       printf ' codex:ok'
-      # Codex ignores plugin-bundled agents (manifest gap) - drop the built TOML where it looks.
-      local toml n=0
-      for toml in "$BUILD/codex/plugins/$name/codex-agents/"*.toml; do
-        mkdir -p "$CODEX_AGENTS"; cp -f "$toml" "$CODEX_AGENTS/"; n=$((n + 1))
-      done
-      [ "$n" -gt 0 ] && printf '(+%d agents)' "$n"
+      node "$SCRIPT_DIR/sync-codex-agents.cjs" "$name" "$BUILD/codex/plugins/$name/codex-agents" "$CODEX_AGENTS" "$previous"
+      rm -rf -- "$previous"
     else
       printf ' codex:FAIL'
       echo "Codex plugin install failed for $name; rerun codex plugin add $name@$MKT for details." >&2
@@ -192,6 +208,7 @@ fi
 if [ "$HAVE_CODEX" = 1 ]; then
   printf '%-22s' "build codex"
   build_tool codex || { echo "FAIL"; echo "codex build failed; rerun the translate command in scripts/dev-sync.sh without output redirection for details." >&2; exit 1; }
+  validate_codex_agents "${targets[@]}" || { echo "FAIL"; exit 1; }
   register_marketplace codex || { echo "FAIL"; echo "Codex marketplace registration failed for $BUILD/codex." >&2; exit 1; }
   echo "ok"
 fi
diff --git a/scripts/sync-codex-agents.cjs b/scripts/sync-codex-agents.cjs
new file mode 100644
index 000000000..4a0c89e50
--- /dev/null
+++ b/scripts/sync-codex-agents.cjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+
+function sync(pluginName, builtAgentsDir, installedDir, previousSnapshotDir) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(pluginName)) throw new Error('Invalid plugin name');
+  const built = fs.existsSync(builtAgentsDir) ? fs.readdirSync(builtAgentsDir, { withFileTypes: true }) : [];
+  // Read the complete build before retiring any installed agents.
+  const desired = new Map(built.filter(entry => entry.isFile() && entry.name.endsWith('.toml')).map(entry => {
+    const source = fs.readFileSync(path.join(builtAgentsDir, entry.name), 'utf8');
+    if (!/^[a-z0-9][a-z0-9-]*\.toml$/.test(entry.name) || !/^name = "[^"\r\n]+"\r?\n/.test(source)) throw new Error(`Invalid generated agent: ${entry.name}`);
+    const name = `${pluginName}-${entry.name.slice(0, -5)}`;
+    return [`${name}.toml`, source.replace(/^name = "[^"\r\n]+"/, `name = "${name}"`)];
+  }));
+  const previous = new Map();
+  function readSnapshot(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) readSnapshot(file);
+      else if (entry.isFile() && path.basename(dir) === 'codex-agents' && entry.name.endsWith('.toml')) {
+        const copies = previous.get(entry.name) || [];
+        copies.push(fs.readFileSync(file));
+        previous.set(entry.name, copies);
+      }
+    }
+  }
+  readSnapshot(previousSnapshotDir);
+  fs.mkdirSync(installedDir, { recursive: true });
+  for (const name of fs.readdirSync(installedDir)) {
+    const file = path.join(installedDir, name);
+    if (!name.endsWith('.toml') || !fs.lstatSync(file).isFile()) continue;
+    if (name.startsWith(`${pluginName}-`)) {
+      if (!desired.has(name)) fs.unlinkSync(file);
+    } else if (previous.has(name) && previous.get(name).some(copy => copy.equals(fs.readFileSync(file)))) {
+      fs.unlinkSync(file);
+    }
+  }
+  for (const [name, contents] of desired) fs.writeFileSync(path.join(installedDir, name), contents);
+}
+
+module.exports = { sync };
+if (require.main === module) {
+  if (process.argv.length !== 6) throw new Error('Expected plugin, build, installed, snapshot paths');
+  sync(...process.argv.slice(2));
+}
diff --git a/scripts/sync-global-instructions.cjs b/scripts/sync-global-instructions.cjs
index 8d09ea23a..136507f0c 100644
--- a/scripts/sync-global-instructions.cjs
+++ b/scripts/sync-global-instructions.cjs
@@ -9,13 +9,13 @@ function render(source, host) {
   if (beginning < 0) throw new Error("AGENTS.md has no Agents section; refusing global sync");
   const boundary = source.indexOf("\n## ", beginning + 1);
   const names = {
-    codex: (role) => `@${role}`,
+    codex: (role) => `@aidd-dev-${role}`,
     claude: (role) => `@aidd-dev:${role}`,
     opencode: (role) => `@aidd-dev-${role}`,
   };
   if (!names[host]) throw new Error(`Unknown instruction host: ${host}`);
   return source.slice(beginning, boundary < 0 ? undefined : boundary).trim().replace(
-    /^\| @([a-z]+)[^|]*\|/gm,
+    /^\| @(?:aidd-dev[:-])?([a-z]+)[^|]*\|/gm,
     (_, role) => `| ${names[host](role)} |`,
   );
 }

From dd79d91c936e21b45270005f0590ce20dcfd48cb Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 14 Oct 2026 23:05:14 +0800
Subject: [PATCH 11/73] fix(aidd-dev): keep the plan backlog example readable

---
 plugins/aidd-dev/skills/01-plan/actions/04-plan.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
index d32737c9c..5cdab509a 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
@@ -12,10 +12,10 @@ Exploration findings and any wireframes.
 
 1. **Slice.** Prefer independent phases, each coherent, verifiable, and sized for one executor pass.
 2. **Write.** Fill [plan-template.md](../assets/plan-template.md) and [phase-template.md](../assets/phase-template.md), covering the full projection without placeholders.
-3. **Link.** For a new folder whose source reference names a backlog item, create `backlog-link.json`:
+3. **Link.** For a new folder whose source reference names a backlog item, create `backlog-link.json` with that reference and the current UTC time:
 
    ```json
-   {"backlog": "<reference>", "written_at": "<UTC timestamp>", "written_by": "aidd-dev:01-plan"}
+   {"backlog": "owner/repo#123", "written_at": "2026-08-21T09:00:00Z", "written_by": "aidd-dev:01-plan"}
    ```
 
 4. **Challenge.** Check source coverage, phase boundaries, acceptance criteria, and dependencies; revise gaps, using an available challenge capability when useful.
@@ -30,5 +30,5 @@ Exploration findings and any wireframes.
 ## Rules
 
 - **Dependencies.** Record earlier phase numbers in `Depends on` for required outputs, conflicting file changes, or shared mutable validation resources; preserve ordering when independence is uncertain.
-- **Link preservation.** Never overwrite an existing backlog link; `backlog` holds one forge reference or project-relative Markdown path, never both or inferred from raw text.
+- **Link preservation.** Preserve existing backlog links; `backlog` holds one explicit forge reference or project-relative Markdown path.
 - **Lifecycle.** Follow [plan-status.md](../references/plan-status.md).

From 8873fcca74e7ad86c6bbf5fee87804bfe63fa1cb Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 08:47:45 +0800
Subject: [PATCH 12/73] refactor(aidd-dev): move skill generation changes to a
 separate PR

---
 docs/ARCHITECTURE.md                          |  2 --
 .../skills/04-skill-generate/SKILL.md         |  8 ++---
 .../04-skill-generate/actions/01-scope.md     | 14 +++++++--
 .../04-skill-generate/actions/02-plan.md      | 25 ++++++++++------
 .../04-skill-generate/actions/03-write.md     | 27 ++++++++++++-----
 .../04-skill-generate/actions/04-validate.md  | 14 +++++++--
 .../assets/action-template.md                 |  8 +++--
 .../assets/skill-template.md                  |  2 +-
 .../references/scope-frame.md                 | 30 ++++++++++++++-----
 .../references/skill-authoring.md             | 17 +++++------
 10 files changed, 98 insertions(+), 49 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 89cac000d..a80e31f8a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -102,8 +102,6 @@ flowchart TB
   Action --> Result["Result or artifact"]
 ```
 
-Recipe actions carry inputs, outputs, process steps, and rules.
-
 ### Agents and delegation
 
 | Role | Contract |
diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
index b334781fe..6e546fb72 100644
--- a/plugins/aidd-context/skills/04-skill-generate/SKILL.md
+++ b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
@@ -25,7 +25,7 @@ Run the flow above. Read only the next action file.
 
 ## Transversal rules
 
-- **Entry.** Default to `create`; follow `modify` when asked.
-- **References.** If a cited reference cannot be read, stop and report the missing file.
-- **Confirmation.** Confirm every target and name with the user.
-- **Visibility.** Announce intended writes before editing.
+- Default to `create`; follow `modify` when asked.
+- If a cited reference cannot be read, stop and report the missing file.
+- Confirm every target and name with the user.
+- Never write silently.
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md b/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md
index d7f85953c..2ed28f681 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/01-scope.md
@@ -13,6 +13,16 @@ The confirmed frame, written nowhere, per [scope-frame.md](../references/scope-f
 ## Process
 
 1. **Detect.** Detect the installed tools per [tool-detect.md](../references/tool-detect.md).
-2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question at a time.
-3. **Check.** Check the name per [naming.md](../references/naming.md), reporting overlaps or none.
+2. **Fill.** For each field in [scope-frame.md](../references/scope-frame.md), propose a value or ask one question.
+3. **Check.** Check the name per [naming.md](../references/naming.md) and surface any overlap.
 4. **Confirm.** Hand the confirmed frame to plan.
+
+## Test
+
+| Case | Pass |
+| --- | --- |
+| The action runs to completion | `git status --porcelain` reads the same after as before |
+| A name overlaps an installed skill | the overlap is surfaced before the frame is handed on |
+| No name overlaps | the run states that it found none |
+| A frame field needs the user | one question is asked, and only that one |
+| The frame is handed to plan | its target was confirmed by the user first |
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md b/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md
index baaf0f3cd..41c70fa72 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/02-plan.md
@@ -1,20 +1,27 @@
 # 02 - Plan
 
-Break the skill into atomic actions: one action, one job.
+Break the skill into atomic, testable actions: one action, one job.
 
 ## Input
 
-- **Create.** The frame from scope.
-- **Modify.** The existing skill, read in place.
+- From scope, the create frame.
+- For a modify, the existing skill, read in place.
 
 ## Output
 
-A plan table, one row per action: slug, input to output, observable success, and dependencies.
+A plan table, one row per action: slug, input to output, test, and any dependency.
 
 ## Process
 
-1. **List.** List every distinct job the output needs.
-   - **Modify.** Keep only jobs the user named.
-2. **Atomize.** Prefer few actions, a job each; merge two that share most logic.
-3. **Order.** Name and number each action per [skill-authoring.md](../references/skill-authoring.md), placing consumed outputs before their consumers.
-4. **Confirm.** Present the table and confirm each observable success condition with the user.
+1. **List.** List every distinct job the output needs. Modify: start from the existing actions, touch only the jobs the user named.
+2. **Atomize.** Prefer few actions, a job each, not a step. Merge two that share most logic.
+3. **Number.** Name, number, and give each an observable test, per [skill-authoring.md](../references/skill-authoring.md).
+4. **Confirm.** Present the table, validate each test with the user.
+
+## Test
+
+| Case | Pass |
+| --- | --- |
+| The table is presented | every row is one job carrying a checkable test |
+| A row consumes an output | that output comes from an earlier row, never a later one |
+| The run is a modify | only the jobs the user named have a row |
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md b/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md
index eefe567a9..595826e48 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/03-write.md
@@ -4,8 +4,8 @@ Write the skill tree from the plan.
 
 ## Input
 
-- **Plan.** The plan from 02.
-- **Target.** The target from 01, or for a modify the existing skill's own location.
+- The plan from 02.
+- The target from 01, or for a modify the existing skill's own location.
 
 ## Output
 
@@ -14,10 +14,21 @@ The skill tree at the target, and the list of files written.
 ## Process
 
 1. **Tree.** Create the shape in [skill-tree.md](../references/skill-tree.md).
-2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md).
-   - **Modify.** Revise the existing SKILL.md in place, keeping the user's edits.
-3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row, weaving its success check into the process.
-   - **Modify.** Revise changed actions in place; leave untouched ones alone.
+2. **Router.** Fill [skill-template.md](../assets/skill-template.md) against [skill-authoring.md](../references/skill-authoring.md), strip the scaffold.
+   - Modify: revise the existing SKILL.md in place, keeping the user's edits.
+3. **Actions.** Fill [action-template.md](../assets/action-template.md) per row against [skill-authoring.md](../references/skill-authoring.md), its test copied from the plan.
+   - Modify: revise a changed action in place. Leave an untouched one alone.
 4. **Hint.** Set `argument-hint` per [skill-authoring.md](../references/skill-authoring.md).
-5. **Place.** Write once per confirmed target using [tool-write.md](../references/tool-write.md), stopping if a path escapes the workspace or target or enters a plugin install directory.
-6. **Read back.** Check the tree and every file against the contract, removing placeholders and scaffold instructions before validation.
+5. **Place.** Write once per confirmed target, using [tool-write.md](../references/tool-write.md).
+6. **Check.** Confirm every written path is relative, inside the workspace, outside the plugin install directory, and under the chosen target. Else stop and report it.
+
+## Test
+
+| Case | Pass |
+| --- | --- |
+| The router is written | it holds a `mermaid` flowchart and an `Action \| Does` table |
+| The action table is read back | every slug is bare and every `Does` is a lowercase imperative with no final period |
+| An action file is written | it holds `## Output`, `## Process`, and a `Case \| Pass` `## Test` |
+| The tree is written | its shape matches [skill-tree.md](../references/skill-tree.md) |
+| Any written file is read back | no `<` placeholder and no template instruction line survives |
+| A path resolves outside the chosen target | the run stops and reports that path |
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md b/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md
index 9f9af8f1e..fca3dacbb 100644
--- a/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md
+++ b/plugins/aidd-context/skills/04-skill-generate/actions/04-validate.md
@@ -8,10 +8,18 @@ The skill written by 03.
 
 ## Output
 
-A report, one row per written file: checks, findings or none, and fixes applied.
+A report, one row per file: what was checked and any fix applied.
 
 ## Process
 
 1. **Review.** Review each file against [review-protocol.md](../references/review-protocol.md).
-2. **Fix.** Apply the confirmed fixes on disk, read them back, and re-review until no breach remains.
-3. **Report.** Deliver the report, even when clean.
+2. **Fix.** Apply the confirmed fixes on disk, then re-review the changed files.
+3. **Report.** Deliver the findings, even when clean.
+
+## Test
+
+| Case | Pass |
+| --- | --- |
+| The report is delivered | every written file has a row, with its findings or none |
+| The review finds a breach | it names the broken rule and a `file:line` |
+| A fix is confirmed | the file differs on disk and is reviewed again |
diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md
index 5cd1e1637..be7d9cc99 100644
--- a/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md
+++ b/plugins/aidd-context/skills/04-skill-generate/assets/action-template.md
@@ -13,10 +13,12 @@
 ## Process
 
 1. **<Label>.** <Imperative step. Sub-bullet for a branch or a loop back.>
-2. **<Check>.** <Run the observable success check and handle failure.>
+2. **<Label>.** <Next step.>
 
-## Rules
+## Test
 
-- **<Label>.** <Constraint not owned by a process step. Omit this section when none.>
+| Case | Pass |
+| --- | --- |
+| <what is run> | <the observable result it gives> |
 
 > Fill every `<...>` and delete this line. An angle bracket left in the written file is a bug.
diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
index 782809305..0bbf97f49 100644
--- a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
+++ b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
@@ -23,6 +23,6 @@ Run the flow above. Read only the next action file.
 
 <Rules owned by no reference or single action, one per line.>
 
-- **<Label>.** <rule>
+- <rule>
 
 > Fill every `<...>` and delete this line. An angle bracket left in the written file is a bug.
diff --git a/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md b/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md
index ebe106ad9..31635008c 100644
--- a/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md
+++ b/plugins/aidd-context/skills/04-skill-generate/references/scope-frame.md
@@ -1,10 +1,24 @@
 # Scope frame
 
-Fill these fields; omit mode when absent.
-
-- **Subject.** Domain.
-- **Purpose.** One sentence.
-- **Name.** Kebab-case.
-- **Flow.** Visible user journey.
-- **Mode.** `auto` runs without planned checkpoints; `interactive` pauses for user input.
-- **Target.** Detected tool, plugin source, or dedicated tool.
+The fields a scoped skill must define.
+
+- subject:
+- purpose: one sentence.
+- name: kebab-case.
+- flow: visible user journey.
+- mode: optional, `auto` or `interactive`.
+- target: detected tool, plugin source, or dedicated tool.
+
+Modes:
+
+- `auto`: runs through the flow without planned user checkpoints.
+- `interactive`: pauses for user input at defined checkpoints.
+
+Output shape:
+
+- subject:
+- purpose:
+- name:
+- flow:
+- mode: omit when absent.
+- target:
diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
index 84e531393..b0862c855 100644
--- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
+++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
@@ -7,26 +7,26 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 - **R1.** One skill, one domain. Named per `naming.md`.
 - **R2.** `name` is not the invocation token: a colon or prefix breaks loading. In prose call a skill `plugin:folder`.
 - **R3.** `description` is the only always-on text: verb-led, third person, about 240 chars, `Use when the user wants to <intents>` and an optional `Not for <X>`. No colon or dash, no other skill or `/command` named.
-- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case; avoid action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
+- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case, never the action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
 - **R5.** English only, one idea per sentence.
 
 ## The router
 
 - **R6.** The router holds the flow, the action table, and the transversal rules. Nothing else.
 - **R7.** The mermaid flow shows every path a run can take: the nominal chain, one entry node per case, a back-edge per loop, a terminal node per outcome. A branch stated in prose is a branch missing from the flow.
-- **R8.** The action table is `| Action | Does |`, one row per action file, in run order. `Action` is the bare slug, no backticks and no number; duplicate slugs retain their action numbers. `Does` is a lowercase imperative half-line with no final period. Above the table, one sentence: what to read next, nothing more.
+- **R8.** The action table is `| Action | Does |`, one row per action file, in run order. `Action` is the bare slug, no backticks and no number; two actions sharing a slug keep their number (`01-plan`, `04-plan`). `Does` is a lowercase imperative half-line with no final period. Above the table, one sentence: what to read next, nothing more.
 - **R9.** `## Transversal rules` holds the rules no single action or reference owns. A rule stated there is stated nowhere else.
 - **R10.** The router is loaded on every call, an action only when its turn comes: the router carries nothing an action or a reference could carry.
 
 ## An action
 
-- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, and optional `## Rules`. Omit unnecessary sections; preserve names and order.
-- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. Number sequential steps; use dash sub-items for cases, branches, loops, or constraints. Every instruction bullet starts with a bold label. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
-- **R13.** Verify observable success in `## Process` through real execution. `## Rules` holds only constraints no process step owns; no separate `## Test` or duplicated checks.
+- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, `## Test`. A section earns its content or is omitted, never invented or reordered.
+- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
+- **R13.** `## Test` is a `| Case | Pass |` table, each row observable by real execution, never a mock.
 
 ## A reference
 
-- **R14.** References stay flat, nesting one directory deep only as a load boundary. Keep each self-contained; name siblings in backticks rather than linking them.
+- **R14.** References stay flat, nesting one directory deep only as a load boundary. Each stands alone, never pulling in another. It names a sibling in backticks and never links it.
 - **R15.** A reference carries one fact per row: a table, a mermaid, or a list. Prose is what is left when neither fits.
 
 ## An asset
@@ -35,7 +35,6 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 
 ## Across all of them
 
-- **R17.** One fact, one home. Apply router rules and cite shared references instead of restating them.
-- **R18.** Link a file on its first citation, except sibling references under R14; use its unambiguous filename in backticks thereafter. Use relative Markdown links rather than unresolved `@` includes. Place citations in the process, output, or rule that uses them.
+- **R17.** One fact, one home. An action acts within a router rule and cites a shared reference, never restating either.
+- **R18.** The first citation of a file in each authoring file is a relative Markdown link, `[name](path)`, except for sibling references under R14. Repeat mentions within the same file use only the filename in backticks when unambiguous; retain the link when ambiguous. Never an `@` include: nothing resolves those. A citation sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Test` line to conform to it. Never a block or a line of its own.
 - **R19.** One file, one artifact. Split two apart only when a path needs one without the other.
-- **R20.** Prefer positive instructions or `avoid` over `never`. Express mandatory boundaries as explicit conditions.

From fd9b620b2fa40467fef5dd5d72fc644d85936768 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 08:56:37 +0800
Subject: [PATCH 13/73] refactor(aidd-dev): keep sub-agent changes focused on
 delegation

---
 AGENTS.md                                     |  2 +-
 .../02-project-memory/actions/04-sync.md      | 29 +++++----
 .../references/agent-authoring.md             |  1 -
 plugins/aidd-dev/CATALOG.md                   |  8 +--
 plugins/aidd-dev/agents/executor.md           | 31 ++++------
 plugins/aidd-dev/agents/explorer.md           | 27 ++++----
 plugins/aidd-dev/agents/reviewer.md           | 31 ++++------
 plugins/aidd-dev/agents/validator.md          | 28 +++------
 plugins/aidd-dev/skills/01-plan/SKILL.md      | 50 +++++++++------
 .../skills/01-plan/actions/01-gather.md       | 17 +++---
 .../skills/01-plan/actions/02-explore.md      | 25 ++++----
 .../skills/01-plan/actions/03-wireframe.md    | 16 +++--
 .../skills/01-plan/actions/04-plan.md         | 43 +++++++------
 .../skills/01-plan/references/plan-status.md  |  8 +--
 .../references/wireframe-conventions.md       |  8 +--
 plugins/aidd-dev/skills/02-implement/SKILL.md | 61 +++++++++++--------
 .../skills/02-implement/actions/01-prepare.md | 14 ++---
 .../skills/02-implement/actions/02-execute.md | 48 +++++++++++----
 .../02-implement/actions/03-finalize.md       | 21 ++++---
 .../skills/01-sdlc/references/02-deliver.md   |  8 +--
 .../skills/01-sdlc/references/03-check.md     | 20 +++---
 plugins/aidd-refine/CATALOG.md                |  3 +-
 plugins/aidd-refine/README.md                 |  2 +-
 .../aidd-refine/skills/02-challenge/SKILL.md  | 29 ++++++---
 .../02-challenge/actions/01-challenge.md      | 34 +++++++----
 .../02-challenge/assets/report-template.md    | 25 +++-----
 .../references/confidence-rubric.md           | 10 +++
 27 files changed, 332 insertions(+), 267 deletions(-)
 create mode 100644 plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md

diff --git a/AGENTS.md b/AGENTS.md
index eb1ad4be1..d1b9d9208 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,7 +39,7 @@ Use available agents when useful. The caller owns scope, delegation, and final a
 <!-- aidd_agents:start -->
 | name | role |
 | --- | --- |
-| @aidd-dev-explorer (Codex, OpenCode), @aidd-dev:explorer (Claude) | Explore scoped questions and return sourced findings before a decision. |
+| @aidd-dev-explorer (Codex, OpenCode), @aidd-dev:explorer (Claude) | Explore the codebase and return relevant files, code, and explanations for a scoped question. |
 | @aidd-dev-executor (Codex, OpenCode), @aidd-dev:executor (Claude) | Implement assigned work and return changes with verification evidence. |
 | @aidd-dev-validator (Codex, OpenCode), @aidd-dev:validator (Claude) | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
 | @aidd-dev-reviewer (Codex, OpenCode), @aidd-dev:reviewer (Claude) | Review quality and coherence against project conventions and the quality checklist. |
diff --git a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
index e7cd958e7..01f3414cc 100644
--- a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
+++ b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
@@ -8,7 +8,7 @@ The memory bank in `aidd_docs/memory/`.
 
 ## Output
 
-Each picked tool's context file, carrying the memory block and available agent table.
+Each picked tool's context file, carrying the filled block.
 
 ## Process
 
@@ -16,15 +16,20 @@ Each picked tool's context file, carrying the memory block and available agent t
 2. **Detect.** Find the AI tools present per [tools.md](../references/tools.md).
 3. **Pick.** Show every tool, the detected ones ticked, and wait for one or several.
 4. **Upsert.** Ensure each picked tool's context file carries the block, per [tools.md](../references/tools.md).
-   - **Absent:** create it from [AGENTS.md](../assets/templates/AGENTS.md).
-   - **Different:** reconcile its AIDD structure only with approval.
+   - Absent file: create it from [AGENTS.md](../assets/templates/AGENTS.md).
+   - Its AIDD structure differs: offer to reconcile it, applying only what the user approves.
 5. **Fill.** Run `hooks/update_memory.js` from the project root, naming the picked tools, and stop on a non-zero exit.
-   - **Standalone:** without the script, fill each block from the bank.
-6. **Agents.** Fill `aidd_agents:start` / `aidd_agents:end` with installed, invocable agents and short English verb-led roles; label differing names by host in shared files.
-7. **Verify.** Read back each selected block; stop if it differs from the bank or advertises an unavailable agent.
-
-## Rules
-
-- **Memory:** list every root `.md` except `README.md`.
-- **Preserve:** leave unselected tools and text outside managed blocks unchanged.
-- **Missing block:** add the agent block, even if only its table header; no new discovery hook or script.
+   - No script, the skill shipped alone: write each block from the bank.
+6. **Agents.** Fill `aidd_agents:start` / `aidd_agents:end` with installed, invocable agents and short English verb-led roles; add the block when absent and label differing names by host. Preserve text outside managed blocks.
+7. **Verify.** Read each picked tool's block back and compare it to the bank; verify every listed agent is available.
+   - A file in one and not the other: the fill did not land, report it and stop.
+
+## Test
+
+| Case | Pass |
+| --- | --- |
+| Empty bank | no context file created, the run stops |
+| Script | it exits `0` |
+| Picked tool | its block lists every root `.md` except `README.md`, nothing else |
+| Bank grew | the block gains that file and keeps the rest |
+| Unpicked tool | its context file is unchanged |
diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
index 540bb019c..b6c6224ed 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
@@ -19,7 +19,6 @@ The contract every generated agent must satisfy. An agent is a focused role with
 
 Short imperative sentences. Optional sections, added only when they earn their place:
 
-- `# References`: supporting criteria or checklists, verified accessible after installation.
 - `# Inputs`: what it receives.
 - `# Outputs`: what it returns.
 - `# Guardrails`: behavioral boundaries.
diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md
index bb5fdc1ae..2035d6404 100644
--- a/plugins/aidd-dev/CATALOG.md
+++ b/plugins/aidd-dev/CATALOG.md
@@ -33,9 +33,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | File | Description |
 |------|---|
 | [executor.md](agents/executor.md) | `Implements assigned work within defined scope. Use to build or fix a deliverable, verify the result, and repair failures against the requested outcome.` |
-| [explorer.md](agents/explorer.md) | `Explores scoped questions about code, documentation, or dependencies. Use to investigate a domain, trace behavior, or research evidence before deciding.` |
-| [reviewer.md](agents/reviewer.md) | `Reviews the quality and coherence of a deliverable. Use for a quality check of simplicity, consistency, maintainability, and alignment with project conventions.` |
-| [validator.md](agents/validator.md) | `Validates that delivered work satisfies the original request, acceptance criteria, and mandatory checks. Use to verify the requested outcome and establish completion independently.` |
+| [explorer.md](agents/explorer.md) | `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.` |
+| [reviewer.md](agents/reviewer.md) | `Reviews the quality and coherence of finished work. Use to find concrete defects, contradictions, duplication, and unnecessary complexity against project conventions and the real need.` |
+| [validator.md](agents/validator.md) | `Validates that delivered work satisfies the request and acceptance criteria. Use to independently confirm completion and explain failures or missing verification.` |
 
 ### `skills`
 
@@ -61,7 +61,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [02-execute.md](skills/02-implement/actions/02-execute.md) | - |
 | `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - |
 | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` |
-| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Implements an existing plan or an assigned phase until its acceptance criteria hold. Use when a plan or bounded phase needs implementing. Not for writing a plan or reviewing a diff.` |
+| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Implement an existing plan or assigned phase until its acceptance criteria hold. Use when a plan or bounded phase needs implementing. Not for writing a plan or reviewing a diff.` |
 
 #### `skills/03-assert`
 
diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md
index 69a290aa1..bdb1a318a 100644
--- a/plugins/aidd-dev/agents/executor.md
+++ b/plugins/aidd-dev/agents/executor.md
@@ -9,30 +9,23 @@ Implement assigned work, choosing the technique within the agreed outcome and cr
 
 # Behavior
 
-- **Adapt.** Resolve local technical obstacles within owned scope and project conventions; report material choices.
-- **Escalate.** Report ambiguity or changes needed to outcomes, criteria, or dependencies outside owned scope; leave those decisions to the caller.
-- **Build.** Validate affected workflows, repair failures, and repeat; debug an unclear cause first.
-- **Complete.** Report COMPLETE only when every assigned criterion and mandatory check passes; keep unmet criteria and skipped checks visible in remaining work.
-- **Ownership.** Stay within assigned responsibility and write ownership; update shared-plan status only with whole-plan ownership.
-- **Git.** Commit only when authorized and owning the Git index; leave shared operations to the caller.
-- **Boundary.** Return changes and evidence directly; leave independent review and delegation to the caller, and report inaccessible human actions.
+- **Resolve local technical obstacles** within owned scope and project conventions; report material choices.
+- **Report ambiguity or changes needed** to outcomes, criteria, or dependencies outside owned scope; leave those decisions to the caller.
+- **Validate affected workflows**, repair failures, and repeat; debug an unclear cause first.
+- **Report COMPLETE** only when every assigned criterion and mandatory check passes; keep unmet criteria and skipped checks visible in remaining work.
+- **Stay within assigned responsibility** and write ownership; update shared-plan status only with whole-plan ownership.
+- **Commit only when authorized** and owning the Git index; leave shared operations to the caller.
+- **Return changes and evidence directly**; leave independent review and delegation to the caller, and report inaccessible human actions.
 
 # Output
 
-Fill this Markdown template; replace placeholders and use `None` for empty fields.
+Return a concise result; omit empty fields.
 
 ```markdown
-## Implementation: <assigned scope>
-
-- **Status:** <COMPLETE | INCOMPLETE | BLOCKED>
-- **Candidate:** <revision or changed artifact paths>
-- **Changes:** <delivered behavior>
-- **Remaining:** <unfinished scope or skipped checks>
-- **Blockers:** <cause and needed input>
-
-| Check | Result | Evidence |
-| --- | --- | --- |
-| <criterion or command> | <PASS | FAIL | BLOCKED> | <output or artifact> |
+**Status:** <COMPLETE | INCOMPLETE | BLOCKED>
+**Changes:** <delivered behavior and paths>
+**Checks:** <what ran and its result>
+**Remaining:** <unfinished work or blockers, if any>
 ```
 
 # Skills you may invoke
diff --git a/plugins/aidd-dev/agents/explorer.md b/plugins/aidd-dev/agents/explorer.md
index 12b00c200..2600a2620 100644
--- a/plugins/aidd-dev/agents/explorer.md
+++ b/plugins/aidd-dev/agents/explorer.md
@@ -1,32 +1,29 @@
 ---
 name: explorer
-description: Explores scoped questions about code, documentation, or dependencies. Use to investigate a domain, trace behavior, or research evidence before deciding.
+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
 
-Explore an assigned question or domain and return evidence for the caller's decision.
+Find the code and context that answer the caller's question.
 
 # Behavior
 
-- **Trace.** Inspect relevant sources and relationships across the assigned domain's boundary.
-- **Ground.** Separate observations from inference; cite file lines or source URLs.
-- **Bound.** Report uncertainty and risks; leave implementation decisions to the caller.
-- **Read only.** Keep inspected material unchanged and return findings directly without delegation.
+- **Read the relevant code**, including callers and dependencies needed to explain the behavior; prefer targeted searches over broad scans.
+- **Return useful context**: file paths, symbols, execution paths, existing patterns, or short code excerpts. Explain what each establishes so the caller can use the findings without repeating the exploration.
+- **Distinguish facts from hypotheses** and state unresolved questions. Suggest changes only when asked.
+- **Keep sources unchanged** and return findings directly to the caller.
 
 # Output
 
-Fill this Markdown template; replace placeholders and use `None` for empty fields.
+Keep the answer proportional to the question; omit unused fields.
 
 ```markdown
-## Exploration: <question or domain>
+**Answer:** <what the relevant code does or where it lives>
 
-- **Answer:** <concise conclusion>
-- **Uncertainty:** <unknowns or conflicting evidence>
-- **Risks:** <material impacts>
-- **Blockers:** <missing access or evidence>
+- **<file:line or symbol>:** <relevant behavior or relationship>
 
-| Finding | Evidence | Observation or inference |
-| --- | --- | --- |
-| <finding> | <path:line or URL> | <type> |
+<Short code excerpt when it makes the answer clearer.>
+
+**Unknowns:** <what remains unresolved, if any>
 ```
diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md
index 78139b846..3a009dc83 100644
--- a/plugins/aidd-dev/agents/reviewer.md
+++ b/plugins/aidd-dev/agents/reviewer.md
@@ -1,38 +1,29 @@
 ---
 name: reviewer
-description: Reviews the quality and coherence of a deliverable. Use for a quality check of simplicity, consistency, maintainability, and alignment with project conventions.
+description: Reviews the quality and coherence of finished work. Use to find concrete defects, contradictions, duplication, and unnecessary complexity against project conventions and the real need.
 ---
 
 # Role
 
-Review whether the delivered parts form a coherent, simple whole that fits the project.
+Review finished work independently and identify quality or coherence gaps that acceptance checks may miss.
 
 # Behavior
 
-- **Ground.** Read the need, candidate identity, project conventions, and existing validation evidence; flag ambiguity.
-- **Inspect.** Locate the installed quality-review skill and read its supporting `references/quality-checklist.md`; apply it alongside project review rules, justifying non-applicable items. Report an unavailable reference as a coverage blocker.
-- **Scope.** Assess quality and coherence; leave functional acceptance to the validator. Reuse validation evidence, repeating targeted checks only when insufficient, inconsistent, or stale.
-- **Report.** Tie findings to evidence and impact; apply supplied thresholds without inventing scores.
-- **Reuse.** Invoke an appropriate review skill through the host for code quality or relevancy; let its report carry findings instead of duplicating them.
-- **Read only.** Keep the deliverable unchanged and return findings directly; leave repairs and delegation to the caller.
+- **Read the actual work and need** in a fresh context, alongside project conventions and existing validation evidence.
+- **Apply the quality checklist** in the installed review skill's supporting `references/quality-checklist.md`, extended with project review rules. Explain relevant coverage gaps.
+- **Look beyond isolated parts**: check whether the delivered logic forms a coherent whole and serves the intended need. Leave acceptance completion to the validator.
+- **Tie findings to evidence and impact**; distinguish concrete defects from optional suggestions. Flag ambiguity instead of guessing.
+- **Use an appropriate review skill** when it fits. Its report carries the findings; avoid a second parallel report. Review code quality and relevancy without repeating functional validation.
+- **Keep the work unchanged**; return findings and the smallest suggested corrections to the caller.
 
 # Output
 
-Fill this Markdown template; replace placeholders and use `None` for empty fields.
-Use the findings table only when no skill report carries those findings.
+Return the skill report when one exists; otherwise use this short format.
 
 ```markdown
-## Review: <deliverable>
+**Review:** <no actionable findings | changes needed | insufficient evidence>
 
-- **Candidate:** <revision or artifact identity>
-- **Verdict:** <quality and coherence, with decisive reason>
-- **Coverage:** <checklist location and justified non-applicable items>
-- **Report:** <skill report path or None>
-- **Blockers:** <missing evidence or ambiguous criteria>
-
-| Finding | Impact | Evidence | Suggested action |
-| --- | --- | --- | --- |
-| <concrete issue> | <consequence> | <path:line or check> | <minimal correction> |
+- **<finding>:** <impact, evidence, and smallest correction>
 ```
 
 # Skills you may invoke
diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
index f009908dc..2197587da 100644
--- a/plugins/aidd-dev/agents/validator.md
+++ b/plugins/aidd-dev/agents/validator.md
@@ -1,34 +1,24 @@
 ---
 name: validator
-description: Validates that delivered work satisfies the original request, acceptance criteria, and mandatory checks. Use to verify the requested outcome and establish completion independently.
+description: Validates that delivered work satisfies the request and acceptance criteria. Use to independently confirm completion and explain failures or missing verification.
 ---
 
 # Role
 
-Validate completion of the requested outcome on an identified candidate.
+Verify whether the requested outcome has been delivered.
 
 # Behavior
 
-- **Identify.** Record the candidate, original request, criteria, prerequisites, and mandatory checks.
-- **Check.** Run mandatory checks and sufficient observable checks of the requested outcome; record evidence for each result.
-- **Complete.** Report COMPLETE only when all criteria and mandatory checks pass on an unchanged candidate.
-- **Block.** Report BLOCKED for absent, ambiguous, or unobservable criteria, missing prerequisites, or stale evidence.
-- **Fail.** Report INCOMPLETE for failures when no blocker prevents a reliable conclusion.
-- **Boundary.** Base conclusions on observed evidence. Keep the candidate and criteria unchanged; leave repairs, quality review, and delegation to the caller. Temporary check artifacts are allowed.
+- **Check the request and acceptance criteria** against the delivered candidate and mandatory project checks.
+- **Use observable evidence**; reuse results only when they cover the same unchanged candidate. Run missing checks when possible.
+- **Report validated only when the requested scope passes**. Otherwise explain what failed or could not be checked and why.
+- **Keep the work and criteria unchanged**; return the conclusion to the caller for repairs or decisions.
 
 # Output
 
-Fill this Markdown template; replace placeholders and use `None` for empty fields.
+Return one conclusion for the assigned scope, without a table per task.
 
 ```markdown
-## Validation: <deliverable>
-
-- **Candidate:** <revision or artifact identity>
-- **Status:** <COMPLETE | INCOMPLETE | BLOCKED>
-- **Stability:** <evidence the candidate stayed unchanged>
-- **Blockers:** <missing criteria, prerequisites, or stale evidence>
-
-| Criterion or mandatory check | Result | Evidence |
-| --- | --- | --- |
-| <supplied requirement or command> | <PASS | FAIL | BLOCKED> | <output or artifact> |
+**Validated:** <yes | no>
+<Brief supporting evidence; if no, what failed or could not be checked and why.>
 ```
diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md
index 88fe5ad11..1bbb438ae 100644
--- a/plugins/aidd-dev/skills/01-plan/SKILL.md
+++ b/plugins/aidd-dev/skills/01-plan/SKILL.md
@@ -4,28 +4,40 @@ description: Turn a request, ticket, or file into a phased implementation plan.
 argument-hint: request | ticket | file
 ---
 
-# Plan
-
-```mermaid
-flowchart TD
-  Request([request, ticket, or file]) --> gather --> explore
-  explore -- UI --> wireframe --> plan
-  explore -- no UI --> plan
-  plan -- challenge finds gaps --> plan
-  plan --> Ready([plan ready])
-```
+# Skill: plan
+
+Turn a gathered source into an implementation plan and its phase files. Never writes code.
 
 ## Actions
 
-Read only the next numbered action file in `actions/`.
+| #   | Action      | Role                                                 | Input                      |
+| --- | ----------- | ---------------------------------------------------- | -------------------------- |
+| 01  | `gather`    | Collect and restate the source                       | user request               |
+| 02  | `explore`   | Read the codebase for projection, rules, feasibility | gathered source            |
+| 03  | `wireframe` | Sketch a screen at low fidelity, frontend only       | source + explore context   |
+| 04  | `plan`      | Break into phases, write the plan and phase files    | explore output + wireframe |
+
+Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI.
+Before running an action, read its file in `actions/`, not only the table or assets.
+
+Once the plan and its phase files are written, and only then, run:
+
+```shell
+echo "aidd:step-end aidd-dev:01-plan"
+```
+
+This is the one thing about a step nothing else can supply. No host reports when a skill's
+work finished — a skill call's own result comes back in a tenth of a second, which is the
+dispatch, not the completion — so a measurement that never hears this ends the step at the
+next pause and credits planning with one turn out of however many it took. The framework
+repository documents the run journal this writes into, in `aidd_docs/runs/README.md`.
+
+## References
 
-| Action | Does |
-| --- | --- |
-| gather | identify the source and constraints |
-| explore | ground scope and feasibility in evidence |
-| wireframe | sketch frontend screens |
-| plan | write and challenge phases |
+- `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs.
+- `references/plan-status.md`: the plan lifecycle `status` values and who writes each.
 
-## Transversal rules
+## Assets
 
-- **Read-only.** Never write application code.
+- `assets/plan-template.md`: the `plan.md` scaffold.
+- `assets/phase-template.md`: the per-phase scaffold.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md
index 76c4a20e1..22d9571cc 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md
@@ -1,18 +1,21 @@
-# Gather
+# 01 - Gather
+
+Collect the source the plan will rest on, before any planning. Read only.
 
 ## Input
 
-A request, file, or ticket.
+The user's request, which may be empty.
 
 ## Output
 
-Source kind and reference, requested outcome, hard constraints.
+The source restated in a few bullets: what is asked and the hard constraints it states. The source kind and reference (file path, ticket id, or text) are named.
 
 ## Process
 
-1. **Resolve.** Read the file, fetch the ticket, or use the supplied text; ask for a source if none exists.
-2. **Restate.** Summarize the outcome and constraints in bullets with bold labels.
+1. **Find.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source.
+2. **Pull.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain.
+3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan.
 
-## Rules
+## Test
 
-- **Fidelity.** Invent no source content, solution, or phases.
+- The output names the source kind and reference and restates it in bullets, states no solution, and when nothing concrete was given the user was asked before anything else.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index 95a0990cb..1d758571f 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -1,23 +1,24 @@
-# Explore
+# 02 - Explore
+
+Read the codebase to ground the plan: what it touches, which rules apply, what is feasible. Read only.
 
 ## Input
 
-The gathered source.
+The gathered source from `01-gather`.
 
 ## Output
 
-- **Projection.** Files to modify, create, or delete, each with a reason.
-- **Rules.** Applicable project rules and why, or none.
-- **Evidence.** Sources consulted and what each settled.
-- **Risks.** Blockers, conflicts, and unresolved questions.
+The architecture projection (files to modify, create, delete, each with a one-line reason), the project rules that apply (each justified in one line, or none), the feasibility checks (each source consulted, a doc URL or an in-repo file, and what it settled), and the risks.
 
 ## Process
 
-1. **Scope.** Identify the code and contracts the request touches.
-   - **Delegate.** The primary caller may assign independent questions by relevant codebase domain, such as frontend, backend, or a bounded context, to available explorers; give each a scope and requested evidence.
-2. **Verify.** Check feasibility against in-repo code or official documentation.
-3. **Reconcile.** Combine findings into the projection and applicable rules; resolve conflicting claims with evidence or retain the uncertainty.
+1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions.
+   - The caller may delegate independent questions by codebase domain to explorers, each with a scope and requested findings. Combine their sourced answers; resolve contradictions or keep the uncertainty visible. Isolated explorers return directly.
+2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
+3. **Select.** Keep the project rules that apply to the projection.
 
-## Rules
+## Test
 
-- **Boundaries.** Explore only relevant domains; delegation is optional and isolated agents never delegate again.
+- The projection lists files to modify, create, and delete, each with a one-line reason.
+- Every feasibility check records its source and what it settled.
+- The applicable rules are identified and justified, or none apply.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md
index 81ac7a5a0..928b9cb95 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md
@@ -1,14 +1,20 @@
-# Wireframe
+# 03 - Wireframe
+
+Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI.
 
 ## Input
 
-Required screens and existing components from exploration.
+The screens to sketch, from the gathered source and the `02-explore` context (the existing screens and components).
 
 ## Output
 
-An ASCII wireframe per screen, with numbered regions and one-line notes.
+A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy.
 
 ## Process
 
-1. **Select.** Identify required screens; skip when there is no UI.
-2. **Draw.** Follow [wireframe-conventions.md](../references/wireframe-conventions.md).
+1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI.
+2. **Draw.** Sketch each screen per [wireframe-conventions.md](../references/wireframe-conventions.md). The wireframe feeds the plan.
+
+## Test
+
+- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carrying no behavior, styling, or final copy.
diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
index 5cdab509a..eff6f989b 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
@@ -1,34 +1,39 @@
-# Plan
+# 04 - Plan
+
+Turn the explored source into a plan and its phases, save them, then review the whole before handoff. Never code.
 
 ## Input
 
-Exploration findings and any wireframes.
+The explore output from `02-explore` (projection, rules, feasibility, risks), plus any confirmed wireframe from `03-wireframe`.
 
 ## Output
 
-`plan.md` and `phase-<n>.md` files in the source's feature folder or `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/`.
+A feature folder, always at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/`, holding `plan.md` from [plan-template.md](../assets/plan-template.md) and one `phase-<n>.md` per phase from [phase-template.md](../assets/phase-template.md).
 
 ## Process
 
-1. **Slice.** Prefer independent phases, each coherent, verifiable, and sized for one executor pass.
-2. **Write.** Fill [plan-template.md](../assets/plan-template.md) and [phase-template.md](../assets/phase-template.md), covering the full projection without placeholders.
-3. **Link.** For a new folder whose source reference names a backlog item, create `backlog-link.json` with that reference and the current UTC time:
+1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many. Prefer independent phases with separate file ownership; record earlier phase numbers in `Depends on` for required outputs, overlapping writes, or shared mutable validation resources. Keep phases ordered when independence is uncertain.
+2. **Folder.** Reuse the feature folder the source already lives in, or create one. When creating one and `01-gather`'s own source reference names a backlog item — a ticket id or URL, or a file path naming its Markdown artefact, never raw text — with no `backlog-link.json` there yet, declare it the same way the skill that writes a spec does:
 
    ```json
-   {"backlog": "owner/repo#123", "written_at": "2026-08-21T09:00:00Z", "written_by": "aidd-dev:01-plan"}
+   {
+     "backlog": "owner/repo#123",
+     "written_at": "2026-08-21T09:00:00Z",
+     "written_by": "aidd-dev:01-plan"
+   }
    ```
 
-4. **Challenge.** Check source coverage, phase boundaries, acceptance criteria, and dependencies; revise gaps, using an available challenge capability when useful.
-   - **Interactive.** Show paths and obtain approval.
-   - **Autonomous.** Ask only for product decisions the source cannot resolve.
-5. **Finish.** Emit the completion marker once the files are written and challenged.
-
-   ```shell
-   echo "aidd:step-end aidd-dev:01-plan"
-   ```
+   `backlog` is the one field, on whatever support the item lives - a forge reference or a project-relative Markdown path, never both. When the source names none, write nothing. When `backlog-link.json` already exists, leave it untouched - it is correctable by hand, and a later run must never overwrite a correction.
+3. **Fill.** Fill the plan and each phase from their templates, following the inline contracts. Slice the projection across the phases.
+4. **Show.** Display the written paths.
+5. **Review.** Challenge source coverage, acceptance criteria, phase boundaries, and dependencies; revise gaps. In interactive mode, show them and revise until approved. Under an autonomous orchestrator, revise against the source without waiting for approval; ask only when a product decision cannot be resolved from the source.
 
-## Rules
+## Test
 
-- **Dependencies.** Record earlier phase numbers in `Depends on` for required outputs, conflicting file changes, or shared mutable validation resources; preserve ordering when independence is uncertain.
-- **Link preservation.** Preserve existing backlog links; `backlog` holds one explicit forge reference or project-relative Markdown path.
-- **Lifecycle.** Follow [plan-status.md](../references/plan-status.md).
+- `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/plan.md` exists with one `phase-<n>.md` per phase next to it.
+- Every written file satisfies its template's inline contract.
+- No `{...}` placeholder is left in any written file.
+- The phase projection slices together cover the modify, create, and delete lists.
+- The complete plan and its phases were challenged against the source.
+- An autonomous run waits only for a product decision that the source cannot resolve.
+- A newly created folder whose source names a ticket carries a `backlog-link.json` naming it; reusing an existing folder never overwrites one already there.
diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md
index 3480af0e3..b1f017d6d 100644
--- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md
+++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md
@@ -17,7 +17,7 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The
 
 ## Rules
 
-- **Transitions.** `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state.
-- **Rejection.** Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan.
-- **Review ownership.** `implemented` ≠ reviewed. Only the review layer sets `reviewed`.
-- **Phase ownership.** Assigned phase workers never write the plan status. They may update only their own phase status; the whole-plan owner updates the plan.
+- Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state.
+- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan.
+- `implemented` ≠ reviewed. Only the review layer sets `reviewed`.
+- Assigned phase workers update only their own phase status; plan creation and the whole-plan owner update plan status.
diff --git a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md
index 9156451fe..1dfb23947 100644
--- a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md
+++ b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md
@@ -4,10 +4,10 @@ A wireframe is a low-fidelity ASCII sketch of a screen. Structure only: no behav
 
 ## Drawing
 
-- **Screen.** One box per screen, drawn with `┌ ─ ┐ │ └ ┘`.
-- **Layout.** Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit.
-- **Regions.** Number each region.
-- **Notes.** Under the sketch, one line per number on what it holds and why.
+- One box per screen, drawn with `┌ ─ ┐ │ └ ┘`.
+- Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit.
+- Number each region.
+- Under the sketch, one line per number on what it holds and why.
 
 ## Example
 
diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md
index 8a04b7f0f..759239835 100644
--- a/plugins/aidd-dev/skills/02-implement/SKILL.md
+++ b/plugins/aidd-dev/skills/02-implement/SKILL.md
@@ -1,39 +1,52 @@
 ---
 name: 02-implement
-description: Implements an existing plan or an assigned phase until its acceptance criteria hold. Use when a plan or bounded phase needs implementing. Not for writing a plan or reviewing a diff.
+description: Implement an existing plan or assigned phase until its acceptance criteria hold. Use when a plan or bounded phase needs implementing. Not for writing a plan or reviewing a diff.
 argument-hint: plan | phase
 ---
 
-# Implement
+# Skill: implement
 
 ```mermaid
-flowchart TD
-  Whole([whole plan]) --> prepare
-  Assigned([assigned phase]) --> execute
-  prepare --> execute
-  prepare -- plan missing --> Missing([stop])
-  execute -- repair or more ready phases --> execute
-  execute -- assigned phase done --> Returned([return evidence])
-  execute -- whole plan done --> finalize
-  execute -- blocked or drift --> Stopped([report blocker or replan])
-  finalize -- repair --> execute
-  finalize --> Implemented([implemented])
+flowchart LR
+  whole([whole plan]) --> prepare --> execute
+  assigned([assigned phase]) --> execute
+  execute -->|whole plan complete| finalize --> implemented
+  execute -->|assigned phase complete| returned([return changes and evidence])
+  prepare -->|missing plan| stop
+  execute -->|fix, next task or phase| execute
+  execute --> blocked
+  execute --> replan
+  finalize -->|validation fails| finalize
+  finalize --> blocked
+  finalize --> replan
 ```
 
 ## Actions
 
-Read only the next numbered action file in `actions/`.
+Run actions in order for a whole plan. An assigned-phase executor reads the plan context and executes only that phase, skipping shared preparation and finalization.
+Read each action file in `actions/` before executing it.
 
-| Action | Does |
-| --- | --- |
-| prepare | resolve the plan and prepare its branch |
-| execute | implement and check assigned scope |
-| finalize | validate the integrated plan |
+| Action   | Does                                  |
+| -------- | ------------------------------------- |
+| prepare  | resolve the plan and branch            |
+| execute  | implement and validate each task       |
+| finalize | validate and mark the plan implemented |
 
 ## Transversal rules
 
-- **Ownership.** Whole-plan runners own integration and plan status; assigned-phase runners own only their phase status and skip prepare/finalize. The caller retains requirements, criteria, and final acceptance.
-- **Statuses.** Track plans through `pending → in-progress → implemented` (or `blocked`), phases through `pending → in-progress → done`; `in-progress` is a runtime marker, not a separate commit.
-- **Commits.** Follow user/project policy; when commits are authorized, make one local commit per validated task, grouping only inseparable tasks. Include its code, tests, and docs, exclude unrelated changes, and include `done` in the phase's last task commit. Commit `implemented` separately; push only when requested.
-- **Formatting.** Use project formatters or hooks instead of manual formatting.
-- **Delegation.** The primary caller owns delegation; isolated agents return their assigned work directly.
+- The caller owns delegation, integration, shared plan status, and final acceptance; phase executors own only their assigned files and phase status.
+- Track the plan through `pending → in-progress → implemented` (or `blocked`).
+  - Track phases through `pending → in-progress → done`.
+  - Treat `in-progress` as a runtime marker.
+  - Never commit `in-progress` alone.
+- Follow user and project commit instructions.
+  - Push only when requested.
+- By default, make one local commit per validated task.
+  - Include all its code, tests and docs together.
+  - Group tasks only when they cannot be validated separately.
+  - Never split a task by step or file.
+  - Exclude unrelated changes.
+- Include `done` in the phase's last task commit.
+- Make a final commit for `implemented`.
+- Use project formatters or hooks.
+  - Never format code manually.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
index f4d085d46..3e44ec202 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md
@@ -1,19 +1,19 @@
-# Prepare
+# 01 - Prepare
 
 ## Input
 
-A whole plan, as a path or inline content.
+A plan path or inline content.
 
 ## Output
 
-Resolved plan on a feature branch, `status: in-progress`, or a missing-plan error.
+The resolved plan on a feature branch with `status: in-progress`, or a missing-plan report.
 
 ## Process
 
-1. **Resolve.** Read the supplied plan; if unavailable, stop with `plan not found at <path>`.
-2. **Branch.** Create and announce a feature branch when on the default branch; otherwise keep the current branch.
-3. **Mark.** Set the plan `status: in-progress`.
+1. **Resolve.** Read the supplied plan.
+2. **Branch.** Create and announce a feature branch on the default branch; otherwise keep the current branch.
+3. **Mark.** Set the plan frontmatter `status: in-progress`.
 
 ## Rules
 
-- **Source.** Require a readable plan or inline content; report missing input instead of fabricating a plan.
+- Without a readable plan or inline content, stop with `plan not found at <path>`; never fabricate a plan.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index e07ef5669..7af7d0f74 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -1,25 +1,47 @@
-# Execute
+# 02 - Execute
 
 ## Input
 
-A prepared plan or assigned phase, with plan context, prerequisites, criteria, checkout, resources, and commit policy.
+The prepared plan, or an assigned phase with plan context, dependencies, file ownership, checkout, validation resources, and commit policy.
 
 ## Output
 
-Validated phases, `status: done`, workflow evidence and checked revision, or a blocker/replan report.
+Validated phases marked `done`.
+
+Or a `blocked` / `replan needed` report.
 
 ## Process
 
-1. **Select.** Read `phase-<n>.md` beside `plan.md`; run only assigned or whole-plan phases whose prerequisites are done and integrated.
-   - **Parallel.** The primary caller may dispatch independent phases with their owned files, criteria, completed prerequisites, distinct checkouts/Git indexes, and nonconflicting validation resources.
-   - **Serial.** Run in order when isolation or independence is uncertain, or dependencies are undeclared.
-2. **Implement.** Mark the phase `in-progress`; implement tasks in plan order, grouping only those inseparable for validation.
-3. **Validate.** Validate each task before its commit, then the full phase workflow before marking `done`; include that status in the last task commit according to commit policy.
-4. **Deliver.** Return changes and evidence to the caller. Whole-plan runners integrate returned work, recheck affected interactions, and select the next ready phases.
+1. **Open.** Select assigned phases whose dependencies are done and integrated; use plan order when dependencies are undeclared.
+   - The caller may run independent phases in parallel with distinct checkouts/Git indexes, separate write ownership, and nonconflicting validation resources; otherwise run serially.
+   - Missing or contradictory dependencies, or unfinished work with no ready phase, require `replan needed`.
+   - Set the current phase `status: in-progress`.
+   - In a feature folder, read `phase-<n>.md` beside `plan.md`.
+2. **Code.** Build the next task or inseparable group against its acceptance criteria.
+   - Follow the plan's task order.
+3. **Assert.** Apply the validation rules below to every acceptance criterion of the selected task or group.
+   - After the last task:
+     - Validate the full phase workflow.
+     - Set the phase `status: done` on success.
+4. **Complete.** Commit according to the commit policy.
+   - Repeat steps 2–4 for the remaining assigned tasks.
+   - Phase executors return changes and evidence. The caller integrates them, checks affected interactions, then starts dependents; only the whole-plan owner finalizes.
 
 ## Rules
 
-- **Evidence.** Exercise every acceptance criterion through the real affected interface (browser, CLI, API…); compare actual and expected behavior at every step. Repair mismatches and restart the affected workflow from the beginning; require a full successful run with observable evidence before a task commit or `done`.
-- **Readiness.** Missing/contradictory dependencies or unfinished phases with none ready require `replan needed`, not skipped work or completion.
-- **Drift.** Adapt implementation within owned responsibility; report changes needed to requested outcomes, criteria, or cross-owner dependencies as `replan needed: <reason>` and stop affected work.
-- **Blocked.** Follow [blocked.md](../references/blocked.md); assigned executors report, the whole-plan owner records plan `status: blocked` under commit policy. Leave unfinished code uncommitted; blocked validation is not success.
+- Validate every acceptance criterion through the real affected workflow.
+  - Use the appropriate interface (browser, CLI, API…).
+  - Check actual against expected behavior at every step.
+  - Fix any mismatch.
+  - Restart from the beginning after a repair.
+- Gate task commits and `done` on successful validation.
+  - Require a full successful run.
+  - Require observable evidence for every step.
+  - Report blocked validation.
+  - Never count blocked validation as success.
+- Follow [blocked.md](../references/blocked.md) when implementation is blocked.
+  - Assigned executors report the blocker; the whole-plan owner records the blocked plan according to the commit policy.
+  - Leave unfinished code uncommitted.
+- Stop if satisfying the acceptance criteria requires changing scope or requirements.
+  - Report `replan needed: <reason>`.
+  - Never rewrite the plan.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
index 6f7f16097..659107055 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
@@ -1,19 +1,26 @@
-# Finalize
+# 03 - Finalize
 
 ## Input
 
-A plan with all phases done and integrated.
+The coded plan.
 
 ## Output
 
-Plan `status: implemented`, with integrated acceptance and validation evidence.
+The validated plan marked `implemented`.
 
 ## Process
 
-1. **Verify.** Check the source outcome, phase criteria, and all required validation commands/tests together on the integrated candidate; start the required runtime if needed.
-2. **Repair.** Return failures to execution, rerun the affected workflow and validation commands/tests under Execute's validation, blocker, and drift rules.
-3. **Mark.** Set the plan `status: implemented` only when all required checks pass; commit according to commit policy.
+1. **Verify.** Validate the source outcome and phase criteria together after integration, then run the plan's validation commands and tests.
+   - Start the required runtime if needed.
+2. **Mark.** Set the plan `status: implemented`.
+   - Commit according to the commit policy.
 
 ## Rules
 
-- **Evidence.** Reuse passing results only for the same candidate and required scope; phase checks alone do not establish integrated acceptance.
+- Gate `implemented` on successful validation.
+  - Require every phase `done`.
+  - Require all validation commands and tests to pass.
+- Repair validation failures before `implemented`.
+  - Rerun the affected workflow after a repair.
+  - Rerun the validation commands and tests.
+  - Follow Execute's validation, blocker and drift rules.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 9755cbe52..09b872b94 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,10 +2,10 @@
 
 ## Behavior
 
-- **Plan:** reconcile scoped exploration, then produce a proportional implementation plan.
-- **Assign:** own preparation, shared lifecycle, and integration; delegate only phases with their criteria, prerequisites, status-file ownership, checkout, resources, and commit policy. Use separate checkouts for parallel writers; otherwise run serially.
-- **Integrate:** accept scoped changes and evidence before starting dependents. Include architecture conformance when the project documents architecture; run a required end-to-end journey after all other validation, then finalize. Reuse evidence only for its unchanged candidate and scope.
-- **Handoff:** commit and push through the commit capability; send the clean candidate and evidence to Check.
+- Reconcile scoped exploration, then produce a proportional implementation plan.
+- Own preparation, shared lifecycle, and integration; delegate only phases with their criteria, prerequisites, status-file ownership, checkout, resources, and commit policy. Use separate checkouts for parallel writers; otherwise run serially.
+- Accept scoped changes and evidence before starting dependents. Include architecture conformance when the project documents architecture; run a required end-to-end journey after all other validation, then finalize. Reuse evidence only for its unchanged candidate and scope.
+- Commit and push through the commit capability; send the clean candidate and evidence to Check.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index 3c24c30de..b94e7d19c 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -2,23 +2,23 @@
 
 ## Behavior
 
-- **Validate:** dispatch a fresh validator on the committed candidate, contract, criteria, and mandatory checks.
-- **Review:** after validation passes, dispatch a fresh reviewer for quality and coherence; select code and relevancy axes, using the validator's acceptance evidence.
-- **Challenge:** after review clears, the same reviewer challenges whether the outcome is trustworthy and serves the user.
+- Dispatch a fresh validator on the committed candidate, contract, criteria, and mandatory checks.
+- After validation passes, dispatch a fresh reviewer for quality and coherence; select code and relevancy axes, using the validator's acceptance evidence.
+- After review clears, the same reviewer challenges whether the outcome is trustworthy and serves the user.
 
 ## Findings
 
-A finding routes by its subject. User refusals at a pause route by artifact as `mode.md` says.
+A review or validation finding is routed by what it is about. A refusal the user gives at a pause is not one of these: `mode.md` routes that by artifact.
 
-- **Product:** send contract findings to Frame.
-- **Repair:** send independent implementation findings through Batch; keep dependent repairs together in Deliver.
-- **Candidate:** re-enter Check after each repaired candidate.
-- **Challenge:** after review clears, reopen a zone only for a contract contradiction; carry other findings onto the request as notes.
-- **Recurrence:** route a finding only once. If it returns after being acted on, wait for user authority before opening the request.
+- Product or contract findings are the next Frame source.
+- Independent implementation findings go through Batch; dependent repairs stay together in Deliver.
+- Re-enter Check after every new candidate.
+- Once the review has cleared, only a finding that contradicts the contract reopens a zone: carry any other onto the request as a note.
+- A finding already acted on is never routed twice. Repaired or not, it is a decision that requires user authority, and no request opens until that arrives.
 
 ## Handoff
 
-- **Ship:** commit anything this zone wrote, then open the draft pull request when no actionable finding remains.
+- Commit whatever this zone wrote, then open the draft pull request when the reviewer returns no actionable finding.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md
index 45167c885..9212c98ac 100644
--- a/plugins/aidd-refine/CATALOG.md
+++ b/plugins/aidd-refine/CATALOG.md
@@ -48,7 +48,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 |-------|------|---|
 | `actions` | [01-challenge.md](skills/02-challenge/actions/01-challenge.md) | - |
 | `assets` | [report-template.md](skills/02-challenge/assets/report-template.md) | - |
-| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Challenge completed work against its intent and contracts. Use when the user wants to critically review recent work, find essential gaps, or simplify it. Not for line-by-line style review or writing code.` |
+| `references` | [confidence-rubric.md](skills/02-challenge/references/confidence-rubric.md) | - |
+| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.` |
 
 #### `skills/03-shadow-areas`
 
diff --git a/plugins/aidd-refine/README.md b/plugins/aidd-refine/README.md
index 23cfda934..4b3d462ef 100644
--- a/plugins/aidd-refine/README.md
+++ b/plugins/aidd-refine/README.md
@@ -15,7 +15,7 @@ Five skills that refine inputs and outputs through reflection: clarify vague req
 | Bracket ID | Skill      | Description                                                                                                                                                                                   |
 | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [5.1]      | [brainstorm](skills/01-brainstorm/SKILL.md) | Clarify a vague product or technical intent through natural discovery, converging until the idea is precise enough to act on.                            |
-| [5.2]      | [challenge](skills/02-challenge/SKILL.md)  | Challenge completed work against its intent and contracts; report evidenced blockers and minimal improvements. |
+| [5.2]      | [challenge](skills/02-challenge/SKILL.md)  | Rethink prior work to verify correctness against an agreed plan, classifying findings with a confidence score.                                                                                |
 | [5.3]      | [shadow-areas](skills/03-shadow-areas/SKILL.md) | Analytical scan of a written artifact for blind spots: each gap is classified by category and severity, paired with a direct-question probe.                                              |
 | [5.4]      | [fact-check](skills/04-fact-check/SKILL.md) | Verify factual claims against authoritative sources and rewrite the text with footnote citations, hedging anything that cannot be confirmed.                                              |
 | [5.5]      | [improve](skills/05-improve/SKILL.md) | Read complete conversation evidence, recommend targeted improvements, and propose minimal file edits. |
diff --git a/plugins/aidd-refine/skills/02-challenge/SKILL.md b/plugins/aidd-refine/skills/02-challenge/SKILL.md
index f2bb35e6e..4e1a03c58 100644
--- a/plugins/aidd-refine/skills/02-challenge/SKILL.md
+++ b/plugins/aidd-refine/skills/02-challenge/SKILL.md
@@ -1,20 +1,31 @@
 ---
 name: 02-challenge
-description: Challenge completed work against its intent and contracts. Use when the user wants to critically review recent work, find essential gaps, or simplify it. Not for line-by-line style review or writing code.
+description: Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.
 argument-hint: work
 ---
 
 # Challenge
 
-```mermaid
-flowchart LR
-  Work([work]) --> challenge --> Report([report])
-```
+Rethink prior work and surface what is wrong, missing, or duplicated. Output a structured report with a confidence score so the user knows whether to ship, iterate, or rework.
 
 ## Actions
 
-Read the next action file.
+| #   | Action      | Role                                                          | Input                          |
+| --- | ----------- | ------------------------------------------------------------- | ------------------------------ |
+| 01  | `challenge` | Rethink prior work, classify findings, score confidence       | the work + agreed reference    |
 
-| Action | Does |
-| --- | --- |
-| challenge | challenge intent, contracts, and unnecessary complexity |
+Before running an action, read its file in `actions/`, not only the table or assets.
+
+## Transversal rules
+
+- Reason from first principles, no logical gaps.
+- Aim for simplifications. If the work can be smaller, say so.
+- Fill `assets/report-template.md` verbatim.
+
+## References
+
+- `references/confidence-rubric.md`: tiered rubric for the confidence percentage.
+
+## Assets
+
+- `assets/report-template.md`: findings report skeleton, filled per run.
diff --git a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md
index cb63b1e2c..6e7030fc1 100644
--- a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md
+++ b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md
@@ -1,23 +1,31 @@
 # 01 - Challenge
 
+Rethink prior work and verify correctness against an agreed plan, then emit a structured findings report.
+
 ## Input
 
-- **Work:** the last answer, files, a plan, or a commit range.
-- **Reference:** the agreed plan, spec, or stated user intent.
+- The work to review: the last answer, specific files, a plan, or a commit range.
+- The agreed reference to judge it against: a plan, a spec, or stated requirements. Without one, judge against stated user intent.
 
 ## Output
 
-The evidence-backed verdict and findings in [report-template.md](../assets/report-template.md).
+The findings report following [report-template.md](../assets/report-template.md): a confidence percentage plus the Correctness, Deal breakers, and Suggestions sections.
 
 ## Process
 
-1. **Trace.** Compare the work with the reference and actual contracts of the capabilities it invokes.
-2. **Challenge.** Find outcome failures, unsupported assumptions, essential gaps, contradictions, and removable duplication.
-3. **Classify.** Separate blockers to the intended outcome from optional suggestions, linking each to evidence and the smallest fix.
-4. **Report.** Return the template with verified strengths and any evidence limits.
-
-## Rules
-
-- **Read-only:** never modify the work.
-- **Evidence:** mark an unverified claim as such; missing essential evidence blocks a ready verdict.
-- **Simplicity:** prefer removing or consolidating instructions over adding another rule.
+1. **Align.** Read the work and line it up against the agreed reference.
+2. **Challenge.** Challenge own assumptions and the user's decisions.
+3. **Trust.** Answer internally:
+   - "Am I proud of the work delivered?"
+   - "Am I confident in every consequential choice that was made?"
+   - "Will the user be satisfied with the real end-to-end outcome?"
+4. **Scan.** Scan for edge cases, errors, gaps, duplications, and inconsistencies.
+5. **Classify.** Classify each finding as Correctness, Deal breaker, or Suggestion.
+6. **Score.** Score confidence per the rubric in [confidence-rubric.md](../references/confidence-rubric.md).
+7. **Emit.** Fill [report-template.md](../assets/report-template.md) verbatim and emit it.
+
+## Test
+
+- The report has a confidence percentage and the Correctness, Deal breakers, and Suggestions sections.
+- The Deal breakers section is non-empty only when confidence is below 75%.
+- A negative or uncertain trust answer produces a deal breaker and confidence below 75%.
diff --git a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
index 9d6ffc5f6..a611f2554 100644
--- a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
+++ b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
@@ -1,21 +1,12 @@
-<!-- Replace every placeholder, remove unused rows, write None for empty sections, then remove this comment. Verdict is READY when the intended outcome is supported without blockers, CHANGES REQUIRED for concrete blockers, or BLOCKED when essential evidence is unavailable. -->
+<!-- Challenge findings report skeleton. Fill each section verbatim, keep the header order. -->
 
-**Verdict:** <READY | CHANGES REQUIRED | BLOCKED>
-**Scope:** <work and reference>
-**Evidence limits:** <unverified essentials or None>
+My confidence level of correctness now: XX%
 
-## Verified
+# Correctness (100%)
+-
 
-- **<strength>:** <supporting evidence>
+# Deal breakers
+-
 
-## Blockers
-
-| Finding | Evidence | Minimal fix |
-| --- | --- | --- |
-| <outcome failure or essential evidence gap> | <source, location, or observed result> | <smallest correction> |
-
-## Suggestions
-
-| Finding | Evidence | Minimal improvement |
-| --- | --- | --- |
-| <optional improvement> | <source or observation> | <smallest change> |
+# Suggestions (enhancements only)
+-
diff --git a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
new file mode 100644
index 000000000..2aece1068
--- /dev/null
+++ b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
@@ -0,0 +1,10 @@
+# Confidence rubric
+
+The challenge action emits a confidence percentage. Pick the tier whose conditions match the findings, then choose a value within that tier.
+
+| Tier      | Condition                                                                                                 |
+| --------- | --------------------------------------------------------------------------------------------------------- |
+| `100%`    | Every trust answer is yes, with no deal breakers, gaps, missing parts, or suggestions.                   |
+| `75-95%`  | Every trust answer is yes, with suggestions only and no blockers.                                       |
+| `50-74%`  | At least one trust answer is negative or uncertain, or minor deal breakers are fixable in place.         |
+| `<50%`    | At least one trust answer exposes a major outcome failure, or major deal breakers require partial rework. |

From 5ddd056fd6336e4fb36604bee75ce5a3021893c4 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 09:02:28 +0800
Subject: [PATCH 14/73] fix(aidd-dev): keep validation reports to one verdict

---
 plugins/aidd-dev/agents/validator.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
index 2197587da..f19ab931a 100644
--- a/plugins/aidd-dev/agents/validator.md
+++ b/plugins/aidd-dev/agents/validator.md
@@ -16,7 +16,7 @@ Verify whether the requested outcome has been delivered.
 
 # Output
 
-Return one conclusion for the assigned scope, without a table per task.
+Return one verdict and at most two short sentences for the assigned scope. Give decisive evidence for yes, or the failure or verification blocker for no; avoid a task-by-task report.
 
 ```markdown
 **Validated:** <yes | no>

From 513d323c0dcb431aa936e56bf4be16945e39ec57 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 09:12:35 +0800
Subject: [PATCH 15/73] refactor(aidd-dev): clarify phase delegation and trim
 SDLC routing

---
 .../skills/01-plan/actions/04-plan.md         |  3 ++-
 .../aidd-orchestrator/skills/01-sdlc/SKILL.md |  4 ++--
 .../skills/01-sdlc/references/02-deliver.md   | 19 +++++++++----------
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
index eff6f989b..ebb08997e 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md
@@ -12,7 +12,8 @@ A feature folder, always at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slu
 
 ## Process
 
-1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many. Prefer independent phases with separate file ownership; record earlier phase numbers in `Depends on` for required outputs, overlapping writes, or shared mutable validation resources. Keep phases ordered when independence is uncertain.
+1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many.
+   - Prefer independent phases with separate file ownership; record earlier phase numbers in `Depends on` for required outputs, overlapping writes, or shared mutable validation resources. Keep phases ordered when independence is uncertain.
 2. **Folder.** Reuse the feature folder the source already lives in, or create one. When creating one and `01-gather`'s own source reference names a backlog item — a ticket id or URL, or a file path naming its Markdown artefact, never raw text — with no `backlog-link.json` there yet, declare it the same way the skill that writes a spec does:
 
    ```json
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
index f8bde8f58..3083149eb 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
@@ -8,9 +8,9 @@ argument-hint: request | interactive request
 
 ## Behavior
 
-Decide the mode as `mode.md` says, then read only it and the current zone's reference. Discover providers from installed descriptions by responsibility; verify availability and contracts before dispatch. Diagram addresses illustrate current providers. A blocked zone stops the run and states what would release it.
+Decide the mode as `mode.md` says, then read only it and the current zone's reference. Verify that every named provider is installed before calling it. A zone that cannot proceed stops the run and says what it would take to resume.
 
-Spawn specialized agents for isolated work. Parallelize independent work when it is faster. Give each leaf agent one focused task. Keep model selection outside the role contract. Repeat the responsible zone when delegated work returns an actionable gap.
+Spawn specialized agents for isolated work. Parallelize independent work when it is faster. Give each agent one focused task that a smaller model can execute. Repeat the responsible zone when delegated work returns an actionable gap.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 09b872b94..872aac104 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,10 +2,11 @@
 
 ## Behavior
 
-- Reconcile scoped exploration, then produce a proportional implementation plan.
-- Own preparation, shared lifecycle, and integration; delegate only phases with their criteria, prerequisites, status-file ownership, checkout, resources, and commit policy. Use separate checkouts for parallel writers; otherwise run serially.
-- Accept scoped changes and evidence before starting dependents. Include architecture conformance when the project documents architecture; run a required end-to-end journey after all other validation, then finalize. Reuse evidence only for its unchanged candidate and scope.
-- Commit and push through the commit capability; send the clean candidate and evidence to Check.
+Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For phase delegation, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, checkout, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
+
+The executor implements its scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Run an end-to-end journey after every other validation when the plan calls for one, and none otherwise. Finalize delegated phases together after integration and required validation.
+
+Commit and push the validated work through the commit skill. Send only the clean committed candidate and its evidence to Check.
 
 ```mermaid
 ---
@@ -21,13 +22,12 @@ flowchart TD
 
   subgraph ExecuteStage["Execute and validate the plan"]
     direction TB
-    Dispatch["Caller selects ready phases"]
     Executor(["@aidd-dev:executor"])
     Implement["/aidd-dev:02-implement"]
     Assert["/aidd-dev:03-assert"]
     Integrate["Integrate phases"]
     Test["/aidd-dev:06-test"]
-    Finalize["Finalize integrated plan"]
+    Finalize["Finalize if phases were delegated"]
     Commit["/aidd-vcs:01-commit"]
   end
 
@@ -39,12 +39,11 @@ flowchart TD
 
   Contract --> Plan
   Plan --> PlanArtifact
-  PlanArtifact --> Dispatch
-  Dispatch -- "Isolated executors for independent phases; serial otherwise." --> Executor
-  Executor -- "Assigned phase only." --> Implement
+  PlanArtifact -- "Whole plan, or ready independent phases." --> Executor
+  Executor -- "Assigned plan or phase." --> Implement
   Implement --> Assert
   Assert --> Integrate
-  Integrate -- "More ready phases." --> Dispatch
+  Integrate -- "More ready phases." --> Executor
   Integrate -- "No required end-to-end journey." --> Finalize
   Integrate -- "Run required end-to-end journey last." --> Test
   Test -- "Journey passed." --> Finalize

From 0df0cbcb0331bf7dad873c27edb4639a8d760b0b Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 13:43:15 +0800
Subject: [PATCH 16/73] feat(cli): resolve native delegation suggestions across
 five hosts

---
 cli/README.md                                 |   4 +
 cli/aidd_docs/memory/cli.md                   |   1 +
 cli/src/cli.ts                                |   2 +
 .../resolve-delegation-use-case.ts            | 142 ++++++
 .../contexts/framework/domain/delegation.ts   | 103 ++++
 .../domain/capabilities/agents-capability.ts  |  21 +
 .../domain/formats/delegation-options.ts      |  34 ++
 .../ports/host-plugin-registry-reader.ts      |  19 +-
 .../domain/profiles/claude/claude-paths.ts    |  17 +
 .../tools/domain/profiles/claude/profile.ts   |  10 +
 .../tools/domain/profiles/codex/profile.ts    |  31 +-
 .../tools/domain/profiles/copilot/build.ts    |   8 +-
 .../domain/profiles/copilot/copilot-paths.ts  |  39 ++
 .../tools/domain/profiles/copilot/profile.ts  |  21 +-
 .../tools/domain/profiles/cursor/build.ts     |   7 +-
 .../tools/domain/profiles/cursor/profile.ts   |  69 +++
 .../tools/domain/profiles/opencode/profile.ts |  25 +
 .../host-plugin-registry-reader-adapter.ts    | 228 ++++++++-
 cli/src/presentation/commands/delegation.ts   |  46 ++
 cli/src/runtime/wiring/framework.ts           |   3 +
 .../architecture/folder-size.arch.test.ts     |  14 +-
 .../resolve-delegation-use-case.unit.test.ts  | 471 ++++++++++++++++++
 .../framework/domain/delegation.unit.test.ts  |  77 +++
 .../domain/profiles/cursor/build.unit.test.ts |  10 +-
 ...egistry-reader-adapter.integration.test.ts | 242 ++++++++-
 cli/tests/e2e/delegation.e2e.test.ts          | 202 ++++++++
 cli/tests/e2e/helpers.ts                      |   3 +
 .../snapshots/framework-build/golden.json     |   8 +-
 cli/tests/golden/snapshots/help/surface.json  |  12 +-
 .../golden/snapshots/phase0/snapshot.json     |   2 +-
 cli/tsup.config.ts                            |   3 +
 docs/DELEGATION.md                            |  60 +++
 32 files changed, 1876 insertions(+), 58 deletions(-)
 create mode 100644 cli/src/contexts/framework/application/resolve-delegation-use-case.ts
 create mode 100644 cli/src/contexts/framework/domain/delegation.ts
 create mode 100644 cli/src/contexts/tools/domain/formats/delegation-options.ts
 create mode 100644 cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts
 create mode 100644 cli/src/presentation/commands/delegation.ts
 create mode 100644 cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
 create mode 100644 cli/tests/contexts/framework/domain/delegation.unit.test.ts
 create mode 100644 cli/tests/e2e/delegation.e2e.test.ts
 create mode 100644 docs/DELEGATION.md

diff --git a/cli/README.md b/cli/README.md
index eca3691d9..0761fecc7 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -135,6 +135,10 @@ Opt-in, off until asked. Record shapes and report axes: [`../plugins/aidd-teleme
 | `aidd telemetry identity` | Attach or drop this person's identifier: `use`, `off`, `link`, `unlink` |
 | `aidd telemetry forget` | Irreversibly drop the journal, the stored records, and the identity file |
 
+### Delegation
+
+`aidd delegation resolve <task> --tool <id> [--json]` reads the project's suggestion, verifies an installed agent, and reports requested/native settings. Resolution is read-only; the caller starts the agent. Configuration, host support and runtime checks: [project delegation](../docs/DELEGATION.md).
+
 ## Translate
 
 `aidd translate <source> --to <tool> --out <dir>` converts a framework source tree into a target-native plugin tree.
diff --git a/cli/aidd_docs/memory/cli.md b/cli/aidd_docs/memory/cli.md
index cc8b3f563..fcc5f7c72 100644
--- a/cli/aidd_docs/memory/cli.md
+++ b/cli/aidd_docs/memory/cli.md
@@ -14,6 +14,7 @@ Thirty-three leaf commands. Read them live: `aidd --help`, then each group's. `s
 - `telemetry on | off | read | report | check | forget | identity`; `identity` carries `use | off | link | unlink`.
 - `translate <source>`: author-side, converts a source into a target-native plugin tree.
 - `update`, aliased `upgrade`: the CLI itself.
+- `delegation resolve <task> --tool <id>`: read-only project suggestion, installed agent identity, native option surface; `--json` separates requested/native settings and leaves effective runtime unknown.
 
 ## Interface
 
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index bcebebfc4..9af5112c3 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -2,6 +2,7 @@ import { platform } from "node:os";
 import { Command } from "commander";
 import { registerAuthCommand } from "./presentation/commands/auth.js";
 import { registerCleanCommand } from "./presentation/commands/clean.js";
+import { registerDelegationCommand } from "./presentation/commands/delegation.js";
 import { registerDoctorCommand } from "./presentation/commands/doctor.js";
 import { registerFrameworkCommand } from "./presentation/commands/framework.js";
 import { registerMarketplaceCommand } from "./presentation/commands/marketplace.js";
@@ -41,6 +42,7 @@ registerUpdateCommand(program);
 registerDoctorCommand(program);
 registerCleanCommand(program);
 registerTelemetryCommand(program);
+registerDelegationCommand(program);
 
 // Commands already paying for network I/O, so the update-check refresh rides one of them.
 // `marketplace remove` is offline and `update` already resolves the latest version itself.
diff --git a/cli/src/contexts/framework/application/resolve-delegation-use-case.ts b/cli/src/contexts/framework/application/resolve-delegation-use-case.ts
new file mode 100644
index 000000000..d2c66952b
--- /dev/null
+++ b/cli/src/contexts/framework/application/resolve-delegation-use-case.ts
@@ -0,0 +1,142 @@
+import { join } from "node:path";
+import { parseFrontmatter } from "../../../kernel/markdown.js";
+import { AIDD_CONFIG_FILENAME, AIDD_DIR } from "../../../kernel/paths.js";
+import type { FileReader } from "../../../kernel/ports/file-reader.js";
+import { isAiToolId } from "../../../kernel/tool.js";
+import type { AiTool, HasAgents } from "../../tools/domain/contracts.js";
+import type { HostPluginRegistryReader } from "../../tools/domain/ports/host-plugin-registry-reader.js";
+import { getAiToolConfig, resolvePluginsCapability } from "../../tools/domain/registry.js";
+import { type DelegationResolution, parseDelegation } from "../domain/delegation.js";
+import type { ManifestRepository } from "../domain/ports/manifest-repository.js";
+import { resolveBaseDirFromRecord } from "./plugin/plugin-target-resolution.js";
+
+function hasAgents(tool: AiTool<unknown>): tool is AiTool<HasAgents> {
+  return "agents" in (tool.capabilities as object);
+}
+
+/** Reads project suggestions and installed artifacts. It neither writes settings nor starts agents. */
+export class ResolveDelegationUseCase {
+  constructor(
+    private readonly fs: FileReader,
+    private readonly manifest: ManifestRepository,
+    private readonly registries: ReadonlyMap<string, HostPluginRegistryReader>
+  ) {}
+
+  async execute(options: {
+    projectRoot: string;
+    home: string;
+    env: NodeJS.ProcessEnv;
+    task: string;
+    tool: string;
+  }): Promise<DelegationResolution> {
+    if (!isAiToolId(options.tool))
+      throw new Error(`Unknown tool "${options.tool}"; use an installed AI tool identifier.`);
+    const tool = getAiToolConfig(options.tool);
+    const configPath = join(options.projectRoot, AIDD_DIR, AIDD_CONFIG_FILENAME);
+    const raw = (await this.fs.fileExists(configPath)) ? await this.fs.readFile(configPath) : null;
+    const suggestion = parseDelegation(raw, options.task, options.tool, configPath);
+    const base = {
+      task: options.task,
+      tool: options.tool,
+      effectiveRuntime: "unknown" as const,
+      nativeSurface: "agent-configuration" as const,
+      diagnostics: [],
+    };
+    if (suggestion === undefined) return { ...base, configured: false, requested: {}, native: {} };
+    if (!hasAgents(tool) || tool.capabilities.agents.params.delegation === undefined)
+      throw new Error(
+        `${tool.displayName} does not support delegation resolution; select a supported tool.`
+      );
+    const capability = tool.capabilities.agents.params.delegation;
+    const { plugin, role } = suggestion;
+    const artifact = tool.buildContracts?.flat?.().artifacts.agents;
+    const flatPath = artifact?.supported ? artifact.path(plugin, `agents/${role}.md`) : undefined;
+    const paths: { path: string; mode: "flat" | "marketplace" }[] = [];
+    if (flatPath !== undefined)
+      paths.push({ path: join(options.projectRoot, flatPath), mode: "flat" });
+    const personal = {
+      path: capability.userPath(options.home, options.env, plugin, role),
+      mode: "flat" as const,
+    };
+    if (capability.personalAgentsFirst) paths.unshift(personal);
+    else paths.push(personal);
+    const findAgent = async (): Promise<DelegationResolution | undefined> => {
+      for (const candidate of paths) {
+        if (!(await this.fs.fileExists(candidate.path))) continue;
+        const native = capability.resolveNative(suggestion.requested, candidate.mode);
+        const content = await this.fs.readFile(candidate.path);
+        const declared =
+          capability.readName?.(content) ?? parseFrontmatter(content).frontmatter.name;
+        const name =
+          typeof declared === "string" && declared !== ""
+            ? declared
+            : candidate.mode === "marketplace"
+              ? role
+              : `${plugin}-${role}`;
+        return {
+          ...base,
+          nativeSurface: capability.nativeSurface?.(candidate.mode) ?? "agent-configuration",
+          configured: true,
+          canonicalAgent: suggestion.canonical,
+          requested: suggestion.requested,
+          native,
+          diagnostics: capability.diagnostics?.(content, suggestion.requested) ?? [],
+          agent: { name: capability.identity(name, plugin, candidate.mode, role), ...candidate },
+        };
+      }
+      return undefined;
+    };
+    const flat = await findAgent();
+    if (flat !== undefined) return flat;
+    const manifest = await this.manifest.load();
+    const recorded = manifest?.getPlugins(options.tool).find((entry) => entry.name === plugin);
+    const plugins = resolvePluginsCapability(options.tool);
+    if (plugins?.nativeActivation === null && capability.marketplacePath !== undefined) {
+      const baseDir =
+        recorded === undefined
+          ? plugins.resolvePluginsBaseDir(options.projectRoot, options.home)
+          : resolveBaseDirFromRecord(
+              recorded.scope,
+              options.tool,
+              options.projectRoot,
+              () => options.home
+            );
+      const pluginDir = plugins.pluginOutputDir(plugin);
+      if (pluginDir !== null)
+        paths.push({
+          path: capability.marketplacePath(join(baseDir, pluginDir), role),
+          mode: "marketplace",
+        });
+    }
+    const registry = this.registries.get(options.tool);
+    const unavailable: string[] = [];
+    if (registry !== undefined && capability.marketplacePath !== undefined) {
+      const reading = await registry.read(options.projectRoot, true);
+      if (reading.unreadable !== undefined)
+        throw new Error(
+          `${reading.location}: cannot verify installed agent (${reading.unreadable}); repair the native plugin registry or install a project agent.`
+        );
+      for (const [ref, entry] of reading.refs ?? []) {
+        if (!ref.startsWith(`${plugin}@`)) continue;
+        if (entry.activationUnverified !== undefined)
+          unavailable.push(`${ref}: ${entry.activationUnverified}`);
+        else if (!entry.enabled)
+          unavailable.push(
+            `${ref} is disabled; enable this plugin in ${tool.displayName}, then retry.`
+          );
+        else if (entry.installPath !== undefined)
+          paths.push({
+            path: capability.marketplacePath(entry.installPath, role),
+            mode: "marketplace",
+          });
+      }
+    }
+    const installed = await findAgent();
+    if (installed !== undefined) return installed;
+    if (unavailable.length > 0)
+      throw new Error(`Agent ${suggestion.canonical} unavailable: ${unavailable.join(" ")}`);
+    throw new Error(
+      `Agent ${suggestion.canonical} not found for ${tool.displayName}; install the plugin or its native agent, then retry. Checked: ${paths.map((entry) => entry.path).join(", ")}.`
+    );
+  }
+}
diff --git a/cli/src/contexts/framework/domain/delegation.ts b/cli/src/contexts/framework/domain/delegation.ts
new file mode 100644
index 000000000..912984445
--- /dev/null
+++ b/cli/src/contexts/framework/domain/delegation.ts
@@ -0,0 +1,103 @@
+import { asPlainObject } from "../../../kernel/reading/plain-object.js";
+
+export interface DelegationSuggestion {
+  readonly plugin: string;
+  readonly role: string;
+  readonly canonical: string;
+  readonly requested: { readonly model?: string; readonly effort?: string };
+}
+
+export interface DelegationResolution {
+  readonly task: string;
+  readonly tool: string;
+  readonly configured: boolean;
+  readonly canonicalAgent?: string;
+  readonly agent?: {
+    readonly name: string;
+    readonly path: string;
+    readonly mode: "flat" | "marketplace";
+  };
+  readonly requested: DelegationSuggestion["requested"];
+  readonly native: Readonly<Record<string, string>>;
+  readonly nativeSurface: "agent-configuration" | "spawn";
+  readonly effectiveRuntime: "unknown";
+  readonly diagnostics: readonly string[];
+}
+
+function object(value: unknown, path: string): Record<string, unknown> {
+  const result = asPlainObject(value);
+  if (result === null) throw new Error(`${path}: expected a JSON object; correct this field.`);
+  return result;
+}
+
+function keys(value: Record<string, unknown>, allowed: readonly string[], path: string): void {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0)
+    throw new Error(
+      `${path}: unsupported field ${unexpected.join(", ")}; use ${allowed.join(", ")}.`
+    );
+}
+
+function setting(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== "string" ||
+    value.trim() !== value ||
+    value === "" ||
+    Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)
+  ) {
+    throw new Error(
+      `${path}: expected a nonempty string without surrounding whitespace; correct it or omit it to inherit.`
+    );
+  }
+  return value;
+}
+
+/** Validate the requested task/host only; unrelated configuration has no bearing on this query. */
+export function parseDelegation(
+  raw: string | null,
+  task: string,
+  tool: string,
+  file: string
+): DelegationSuggestion | undefined {
+  if (raw === null) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${file}: expected valid JSON; repair the file before resolving delegation.`);
+  }
+  const root = object(parsed, file);
+  if (root.delegation === undefined) return undefined;
+  const delegation = object(root.delegation, `${file}: delegation`);
+  if (!Object.hasOwn(delegation, task)) return undefined;
+  const path = `${file}: delegation.${task}`;
+  const entry = object(delegation[task], path);
+  keys(entry, ["agent", "tools"], path);
+  if (
+    typeof entry.agent !== "string" ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(entry.agent)
+  ) {
+    throw new Error(
+      `${path}.agent: expected a canonical plugin:role address, for example aidd-dev:explorer.`
+    );
+  }
+  const colon = entry.agent.indexOf(":");
+  const plugin = entry.agent.slice(0, colon);
+  const role = entry.agent.slice(colon + 1);
+  let requested: DelegationSuggestion["requested"] = {};
+  if (entry.tools !== undefined) {
+    const tools = object(entry.tools, `${path}.tools`);
+    if (Object.hasOwn(tools, tool)) {
+      const selected = object(tools[tool], `${path}.tools.${tool}`);
+      keys(selected, ["model", "effort"], `${path}.tools.${tool}`);
+      const model = setting(selected.model, `${path}.tools.${tool}.model`);
+      const effort = setting(selected.effort, `${path}.tools.${tool}.effort`);
+      requested = {
+        ...(model === undefined ? {} : { model }),
+        ...(effort === undefined ? {} : { effort }),
+      };
+    }
+  }
+  return { plugin, role, canonical: entry.agent, requested };
+}
diff --git a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
index 625db1ae6..241d696e2 100644
--- a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
+++ b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
@@ -51,6 +51,27 @@ export class AgentsCapability {
       directory: string;
       toolSuffix: string;
       format: "markdown" | "toml";
+      delegation?: {
+        personalAgentsFirst?: boolean;
+        userPath: (home: string, env: NodeJS.ProcessEnv, plugin: string, role: string) => string;
+        identity: (
+          name: string,
+          plugin: string,
+          mode: "flat" | "marketplace",
+          role: string
+        ) => string;
+        resolveNative: (
+          requested: { model?: string; effort?: string },
+          mode: "flat" | "marketplace"
+        ) => Readonly<Record<string, string>>;
+        readName?: (content: string) => string | undefined;
+        marketplacePath?: (root: string, role: string) => string;
+        nativeSurface?: (mode: "flat" | "marketplace") => "agent-configuration" | "spawn";
+        diagnostics?: (
+          content: string,
+          requested: { model?: string; effort?: string }
+        ) => readonly string[];
+      };
       userFileExt?: string;
       buildInstallPath?: (fileName: string) => string | null;
       convertFrontmatter?: (
diff --git a/cli/src/contexts/tools/domain/formats/delegation-options.ts b/cli/src/contexts/tools/domain/formats/delegation-options.ts
new file mode 100644
index 000000000..3fa420519
--- /dev/null
+++ b/cli/src/contexts/tools/domain/formats/delegation-options.ts
@@ -0,0 +1,34 @@
+/** Native suggestions carry only explicit project settings. Model identifiers stay literal. */
+export function nativeAgentOptions(
+  requested: { model?: string; effort?: string },
+  effortField: string,
+  efforts?: readonly string[]
+): Readonly<Record<string, string>> {
+  if (
+    requested.effort !== undefined &&
+    efforts !== undefined &&
+    !efforts.includes(requested.effort)
+  ) {
+    throw new Error(
+      `Unsupported effort "${requested.effort}"; use ${efforts.join(", ")} or omit effort to inherit.`
+    );
+  }
+  return {
+    ...(requested.model === undefined ? {} : { model: requested.model }),
+    ...(requested.effort === undefined ? {} : { [effortField]: requested.effort }),
+  };
+}
+
+/** Hosts whose model selector includes its effort need an explicit model to avoid guessing it. */
+export function embeddedAgentOptions(
+  requested: { model?: string; effort?: string },
+  embed: (model: string, effort: string) => string
+): Readonly<Record<string, string>> {
+  if (requested.effort === undefined)
+    return requested.model === undefined ? {} : { model: requested.model };
+  if (requested.model === undefined)
+    throw new Error(
+      "An explicit model is required with effort; set model or omit effort to inherit."
+    );
+  return { model: embed(requested.model, requested.effort) };
+}
diff --git a/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts b/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts
index 79f069c54..025e9b9cd 100644
--- a/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts
+++ b/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts
@@ -3,12 +3,9 @@ import type { MarketplaceScope } from "../../../../kernel/scope.js";
 /**
  * What a host's own plugin registry says, read from the file that host maintains itself.
  *
- * A host loads a plugin only once it appears in its own user-global registry, whatever the
- * project's settings declare: `aidd` writes a declaration, the host keeps a registry, and only
- * the second one decides. All three hosts that declare a native activation key that registry on
- * the same `<plugin>@<marketplace>` string `enabledPlugins` uses, so a reading is a set of refs
- * whatever file it came out of. A host with no implementation here is simply absent from the
- * map the diagnostic consults, never assumed to agree.
+ * Installation diagnostics read host records; delegation additionally checks native artifact
+ * paths and project activation settings. Readers use the `<plugin>@<marketplace>` refs their
+ * hosts record. A host with no implementation is absent from the map, never assumed to agree.
  */
 /** What a registry says about one ref: whether the host records it enabled and, for a host
  * whose registry carries a per-entry scope (Claude), the scope of the entry that answers for
@@ -18,6 +15,9 @@ import type { MarketplaceScope } from "../../../../kernel/scope.js";
 export interface HostPluginRegistryEntry {
   readonly enabled: boolean;
   readonly scope?: MarketplaceScope;
+  /** Native plugin directory from the host's registration and documented layout. */
+  readonly installPath?: string;
+  readonly activationUnverified?: string;
 }
 
 export interface HostPluginRegistryReading {
@@ -35,8 +35,7 @@ export interface HostPluginRegistryReading {
 }
 
 export interface HostPluginRegistryReader {
-  /** `projectRoot` because a registry may bind a ref to one project rather than to the machine
-   * — Claude's does. A reader whose host records no such binding ignores it and says so, rather
-   * than silently answering a narrower question than it was asked. */
-  read(projectRoot: string): Promise<HostPluginRegistryReading>;
+  /** Delegation includes artifact paths and project activation; the default retains installation
+   * diagnostic semantics. Neither mode establishes the effective runtime configuration. */
+  read(projectRoot: string, forDelegation?: boolean): Promise<HostPluginRegistryReading>;
 }
diff --git a/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts b/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts
new file mode 100644
index 000000000..a5281dc7f
--- /dev/null
+++ b/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts
@@ -0,0 +1,17 @@
+import { join } from "node:path";
+
+export function claudeConfigDir(home: string, env: NodeJS.ProcessEnv): string {
+  return env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+}
+
+export function claudePluginsDir(home: string, env: NodeJS.ProcessEnv): string {
+  return env.CLAUDE_CODE_PLUGIN_CACHE_DIR || join(claudeConfigDir(home, env), "plugins");
+}
+
+export function claudeSettingsPaths(configDir: string, projectRoot: string): readonly string[] {
+  return [
+    join(configDir, "settings.json"),
+    join(projectRoot, ".claude", "settings.json"),
+    join(projectRoot, ".claude", "settings.local.json"),
+  ];
+}
diff --git a/cli/src/contexts/tools/domain/profiles/claude/profile.ts b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
index 8752f893d..7ee754986 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
@@ -16,10 +16,12 @@ import type {
   HasSkills,
 } from "../../contracts.js";
 import { convertCommandFrontmatter, stripToolSuffix } from "../../formats/command.js";
+import { nativeAgentOptions } from "../../formats/delegation-options.js";
 import { CLAUDE_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { claudeStyleMarketplaceKey } from "../../marketplace-entry.js";
 import { registerTool } from "../../registry.js";
 import { buildClaudeContract, buildClaudeFlatContract } from "./build.js";
+import { claudeConfigDir } from "./claude-paths.js";
 import { CLAUDE_CODE_TRANSCRIPT_LOCATION } from "./claude-transcript-location.js";
 
 const DIRECTORY = ".claude/";
@@ -58,6 +60,14 @@ export const claude: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
+        delegation: {
+          userPath: (home, env, plugin, role) =>
+            join(claudeConfigDir(home, env), "agents", `${plugin}-${role}.md`),
+          identity: (name, plugin, mode) => (mode === "marketplace" ? `${plugin}:${name}` : name),
+          resolveNative: (requested) =>
+            nativeAgentOptions(requested, "effort", ["low", "medium", "high", "xhigh", "max"]),
+          marketplacePath: (root, role) => join(root, "agents", `${role}.md`),
+        },
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/codex/profile.ts b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
index adb01072b..45cf67815 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
@@ -22,6 +22,7 @@ import {
   convertCommandFrontmatter,
   stripToolSuffix,
 } from "../../formats/command.js";
+import { nativeAgentOptions } from "../../formats/delegation-options.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { registerTool } from "../../registry.js";
 import {
@@ -31,6 +32,7 @@ import {
   stripCodexSkillFrontmatter,
 } from "./build.js";
 import { CODEX_ROLLOUT_LOCATION } from "./codex-transcript-location.js";
+import { parseToml } from "./toml.js";
 
 const DIRECTORY = ".codex/";
 const TOOL_SUFFIX = ".codex.md";
@@ -148,7 +150,34 @@ export const codex: AiTool<
   buildContracts: { marketplace: buildCodexContract, flat: buildCodexFlatContract },
 
   capabilities: {
-    agents: new AgentsCapability({ directory: DIRECTORY, toolSuffix: TOOL_SUFFIX, format: "toml" }),
+    agents: new AgentsCapability({
+      directory: DIRECTORY,
+      toolSuffix: TOOL_SUFFIX,
+      format: "toml",
+      delegation: {
+        userPath: (home, env, plugin, role) =>
+          join(env.CODEX_HOME || join(home, ".codex"), "agents", `${plugin}-${role}.toml`),
+        identity: (name) => name,
+        resolveNative: (requested) => nativeAgentOptions(requested, "model_reasoning_effort"),
+        readName: (content) => {
+          const name = parseToml(content).name;
+          if (typeof name !== "string" || name.trim() === "")
+            throw new Error(
+              "Installed agent requires a nonempty TOML name; repair or reinstall its agent file."
+            );
+          return name;
+        },
+        diagnostics: (content, requested) => {
+          const pins = parseToml(content);
+          return Object.entries(nativeAgentOptions(requested, "model_reasoning_effort"))
+            .filter(([field, value]) => typeof pins[field] === "string" && pins[field] !== value)
+            .map(
+              ([field, value]) =>
+                `Installed agent pins ${field} to ${pins[field]}; update its agent configuration to ${value} before spawning. A spawn override may not replace this pin.`
+            );
+        },
+      },
+    }),
     skills: new SkillsCapability({
       prefix: "aidd-",
       buildInstallPath: buildCodexSkillFilePath,
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/build.ts b/cli/src/contexts/tools/domain/profiles/copilot/build.ts
index 4bb9deaff..80f4a536a 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/build.ts
@@ -23,11 +23,15 @@ import {
   synthesizeClaudeStyleManifest,
   transformClaudeAgent,
 } from "../../marketplace-catalog.js";
-import { COPILOT_VSCODE_MCP_PATH, COPILOT_WORKSPACE_DIR } from "./copilot-paths.js";
+import {
+  COPILOT_MARKETPLACE_RELATIVE,
+  COPILOT_VSCODE_MCP_PATH,
+  COPILOT_WORKSPACE_DIR,
+} from "./copilot-paths.js";
 
 const OUTPUT_PLUGIN_MANIFEST_RELATIVE = ".plugin/plugin.json";
 
-const OUTPUT_MARKETPLACE_RELATIVE = ".plugin/marketplace.json";
+const OUTPUT_MARKETPLACE_RELATIVE = COPILOT_MARKETPLACE_RELATIVE;
 
 /** Output prefix for agents in flat mode: .github/agents/<plugin>/<name>.agent.md */
 const FLAT_GITHUB_AGENTS_PREFIX = `${COPILOT_WORKSPACE_DIR}agents/`;
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts b/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts
index f74a33429..2d7fd5dcb 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts
@@ -1,3 +1,5 @@
+import { join } from "node:path";
+
 /** Canonical path constants for the GitHub Copilot workspace layout, in a file of their own so
  * the profile and the flat-mode build helpers share one source without a cross-layer
  * dependency. */
@@ -5,3 +7,40 @@
 export const COPILOT_WORKSPACE_DIR = ".github/";
 
 export const COPILOT_VSCODE_MCP_PATH = ".vscode/mcp.json";
+
+export const COPILOT_MARKETPLACE_RELATIVE = ".plugin/marketplace.json";
+export const COPILOT_MARKETPLACE_LOCATIONS = [
+  "marketplace.json",
+  COPILOT_MARKETPLACE_RELATIVE,
+  ".github/plugin/marketplace.json",
+  ".claude-plugin/marketplace.json",
+];
+
+export function copilotConfigDir(home: string, env: NodeJS.ProcessEnv): string {
+  return env.COPILOT_HOME || join(home, ".copilot");
+}
+
+export function copilotSettingsPaths(
+  configDir: string,
+  projectRoot: string
+): readonly (readonly string[])[] {
+  return [
+    [join(configDir, "settings.json")],
+    [
+      join(projectRoot, ".claude", "settings.json"),
+      join(projectRoot, ".github", "copilot", "settings.json"),
+    ],
+    [
+      join(projectRoot, ".claude", "settings.local.json"),
+      join(projectRoot, ".github", "copilot", "settings.local.json"),
+    ],
+  ];
+}
+
+export function copilotInstalledPluginDir(
+  configDir: string,
+  marketplace: string,
+  plugin: string
+): string {
+  return join(configDir, "installed-plugins", marketplace, plugin);
+}
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
index b94791a8a..c4c862007 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
@@ -20,11 +20,12 @@ import type {
   HasSkills,
 } from "../../contracts.js";
 import { convertCommandFrontmatter } from "../../formats/command.js";
+import { nativeAgentOptions } from "../../formats/delegation-options.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { claudeStyleMarketplaceKey } from "../../marketplace-entry.js";
 import { registerTool } from "../../registry.js";
 import { buildCopilotFlatContract, buildCopilotMarketplaceContract } from "./build.js";
-import { COPILOT_WORKSPACE_DIR } from "./copilot-paths.js";
+import { COPILOT_WORKSPACE_DIR, copilotConfigDir } from "./copilot-paths.js";
 
 const DIRECTORY = COPILOT_WORKSPACE_DIR;
 const TOOL_SUFFIX = ".copilot.md";
@@ -240,6 +241,24 @@ export const copilot: AiTool<
       toolSuffix: EXT_AGENT,
       format: "markdown",
       userFileExt: EXT_AGENT,
+      delegation: {
+        userPath: (home, env, plugin, role) =>
+          join(copilotConfigDir(home, env), "agents", `${plugin}-${role}.agent.md`),
+        personalAgentsFirst: true,
+        identity: (_name, plugin, mode, role) =>
+          mode === "marketplace" ? `${plugin}:${role}` : `${plugin}-${role}`,
+        resolveNative: (requested) =>
+          nativeAgentOptions(requested, "reasoningEffort", [
+            "none",
+            "minimal",
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "max",
+          ]),
+        marketplacePath: (root, role) => join(root, "agents", `${role}.md`),
+      },
       buildInstallPath: (fileName) => agentsHandler.buildFilePath(fileName),
       convertFrontmatter: (fm, fileName) => agentsHandler.convertFrontmatter(fm, fileName),
     }),
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/build.ts b/cli/src/contexts/tools/domain/profiles/cursor/build.ts
index 55c90fe60..441a1f10d 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/build.ts
@@ -27,13 +27,16 @@ import {
   OUTPUT_CURSOR_MARKETPLACE_RELATIVE,
 } from "./cursor-paths.js";
 
-function transformCursorAgent(content: string, _plugin: string, outName: string): string {
+function transformCursorAgent(content: string, plugin: string, outName: string): string {
   const { frontmatter, body } = parseFrontmatter(content);
   const stripped = stripCursorAgentFrontmatter(frontmatter);
   const rewrittenBody = rewriteRelativeLinks(body, {
     currentFilePluginRelative: `agents/${outName}`,
   });
-  return serializeFrontmatter(stripped, rewrittenBody);
+  return serializeFrontmatter(
+    { ...stripped, name: `${plugin}-${outName.replace(/\.md$/, "")}` },
+    rewrittenBody
+  );
 }
 
 export function buildCursorContract(): ToolBuildContract {
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
index cb2854479..39c6f3071 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
@@ -20,6 +20,7 @@ import {
   convertCommandFrontmatter,
   stripToolSuffix,
 } from "../../formats/command.js";
+import { embeddedAgentOptions } from "../../formats/delegation-options.js";
 import { CURSOR_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { registerTool } from "../../registry.js";
 import { buildCursorContract, buildCursorFlatContract } from "./build.js";
@@ -58,6 +59,74 @@ export const cursor: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
+        delegation: {
+          userPath: (home, _env, plugin, role) =>
+            join(home, ".cursor", "agents", `${plugin}-${role}.md`),
+          identity: (name, plugin, mode, role) => {
+            const expected = `${plugin}-${role}`;
+            if (mode === "marketplace" && name !== expected)
+              throw new Error(
+                `Plugin agent ${name} has a collision-prone name; reinstall its translated plugin to obtain ${expected}.`
+              );
+            return name;
+          },
+          resolveNative: (requested, mode) => {
+            if (mode === "marketplace") {
+              if (requested.effort !== undefined)
+                throw new Error(
+                  "Cursor plugin spawn does not accept effort; choose an advertised model slug or omit effort to inherit."
+                );
+              return requested.model === undefined ? {} : { model: requested.model };
+            }
+            return embeddedAgentOptions(requested, (model, effort) => {
+              if (!/^[a-zA-Z0-9_.-]+$/.test(effort))
+                throw new Error(
+                  "Invalid effort option: use a model parameter value without spaces or brackets."
+                );
+              const open = model.indexOf("[");
+              const malformed = () =>
+                new Error(
+                  "Malformed model option group: use one [key=value,...] group with unique keys before specifying effort."
+                );
+              if (open === -1) {
+                if (model.includes("]")) throw malformed();
+                return `${model}[effort=${effort}]`;
+              }
+              if (
+                open === 0 ||
+                model.indexOf("[", open + 1) !== -1 ||
+                model.indexOf("]") !== model.length - 1
+              )
+                throw malformed();
+              const keys = new Set<string>();
+              let selectedEffort: string | undefined;
+              for (const option of model.slice(open + 1, -1).split(",")) {
+                const equals = option.indexOf("=");
+                const key = option.slice(0, equals);
+                const value = option.slice(equals + 1);
+                if (
+                  equals < 1 ||
+                  value === "" ||
+                  value.includes("=") ||
+                  /\s/.test(option) ||
+                  keys.has(key)
+                )
+                  throw malformed();
+                keys.add(key);
+                if (key === "effort") selectedEffort = value;
+              }
+              if (selectedEffort !== undefined) {
+                if (selectedEffort === effort) return model;
+                throw new Error(
+                  "Conflicting model effort option: remove [effort=...] before specifying a different effort."
+                );
+              }
+              return `${model.slice(0, -1)},effort=${effort}]`;
+            });
+          },
+          marketplacePath: (root, role) => join(root, "agents", `${role}.md`),
+          nativeSurface: (mode) => (mode === "marketplace" ? "spawn" : "agent-configuration"),
+        },
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
index d12add210..75de4ae6b 100644
--- a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
@@ -21,6 +21,7 @@ import {
   convertCommandFrontmatterNoHint,
   stripToolSuffix,
 } from "../../formats/command.js";
+import { embeddedAgentOptions } from "../../formats/delegation-options.js";
 import { registerTool } from "../../registry.js";
 import { buildOpencodeFlatContract, transformMcpToOpencode } from "./build.js";
 import { generateOpencodeHooksBridge } from "./opencode-hooks-bridge.js";
@@ -76,6 +77,30 @@ export const opencode: AiTool<
       directory: DIRECTORY,
       toolSuffix: TOOL_SUFFIX,
       format: "markdown",
+      delegation: {
+        userPath: (home, env, plugin, role) =>
+          join(
+            env.XDG_CONFIG_HOME || join(home, ".config"),
+            "opencode",
+            "agents",
+            `${plugin}-${role}.md`
+          ),
+        identity: (_name, plugin, _mode, role) => `${plugin}-${role}`,
+        resolveNative: (requested) =>
+          embeddedAgentOptions(requested, (model, effort) => {
+            if (!/^[a-zA-Z0-9_.-]+$/.test(effort))
+              throw new Error(
+                "Invalid effort variant: use a variant selector without spaces or #."
+              );
+            if (model.includes("#")) {
+              if (model.slice(model.lastIndexOf("#") + 1) === effort) return model;
+              throw new Error(
+                "Conflicting model variant: remove the model #suffix before specifying a different effort."
+              );
+            }
+            return `${model}#${effort}`;
+          }),
+      },
       convertFrontmatter: (fm) => ({ description: fm.description, mode: "subagent" }),
     }),
     skills: new SkillsCapability({
diff --git a/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts b/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts
index 60d84bd63..d908f6fbf 100644
--- a/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts
+++ b/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts
@@ -1,7 +1,10 @@
 import { readFile, realpath } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { describeError } from "../../../kernel/describe-error.js";
 import { resolveHomeDir } from "../../../kernel/reading/home-dir.js";
+import { stripJsonComments } from "../../../kernel/reading/jsonc.js";
+import { asPlainObject } from "../../../kernel/reading/plain-object.js";
 import type { MarketplaceScope } from "../../../kernel/scope.js";
 import type { AiToolId } from "../../../kernel/tool.js";
 import type {
@@ -9,6 +12,17 @@ import type {
   HostPluginRegistryReader,
   HostPluginRegistryReading,
 } from "../domain/ports/host-plugin-registry-reader.js";
+import {
+  claudeConfigDir,
+  claudePluginsDir,
+  claudeSettingsPaths,
+} from "../domain/profiles/claude/claude-paths.js";
+import {
+  COPILOT_MARKETPLACE_LOCATIONS,
+  copilotConfigDir,
+  copilotInstalledPluginDir,
+  copilotSettingsPaths,
+} from "../domain/profiles/copilot/copilot-paths.js";
 
 function failedRead(location: string, error: unknown): HostPluginRegistryReading {
   if (error instanceof Error && "code" in error && error.code === "ENOENT")
@@ -30,15 +44,22 @@ function failedRead(location: string, error: unknown): HostPluginRegistryReading
  * rather than deleting it, so registered-but-off is an ordinary state, not a Codex-only one.
  */
 export function hostPluginRegistryReaders(
-  home: string = resolveHomeDir()
+  home: string = resolveHomeDir(),
+  env: NodeJS.ProcessEnv = process.env
 ): ReadonlyMap<AiToolId, HostPluginRegistryReader> {
   return new Map<AiToolId, HostPluginRegistryReader>([
     [
       "claude",
-      new ClaudeInstalledPluginsReader(join(home, ".claude", "plugins", "installed_plugins.json")),
+      new ClaudeInstalledPluginsReader(
+        join(claudePluginsDir(home, env), "installed_plugins.json"),
+        claudeConfigDir(home, env)
+      ),
     ],
     ["codex", new CodexConfigPluginsReader(join(home, ".codex", "config.toml"))],
-    ["copilot", new CopilotSettingsPluginsReader(join(home, ".copilot", "settings.json"))],
+    [
+      "copilot",
+      new CopilotSettingsPluginsReader(join(copilotConfigDir(home, env), "settings.json")),
+    ],
   ]);
 }
 
@@ -50,9 +71,12 @@ export function hostPluginRegistryReaders(
  * one.
  */
 class ClaudeInstalledPluginsReader implements HostPluginRegistryReader {
-  constructor(private readonly path: string) {}
+  constructor(
+    private readonly path: string,
+    private readonly configDir: string
+  ) {}
 
-  async read(projectRoot: string): Promise<HostPluginRegistryReading> {
+  async read(projectRoot: string, forDelegation = false): Promise<HostPluginRegistryReading> {
     let content: string;
     try {
       content = await readFile(this.path, "utf8");
@@ -66,10 +90,29 @@ class ClaudeInstalledPluginsReader implements HostPluginRegistryReader {
         return { location: this.path, unreadable: "no `plugins` object" };
       }
       const refs = new Map<string, HostPluginRegistryEntry>();
+      const activation = forDelegation
+        ? await enabledPluginsAt(claudeSettingsPaths(this.configDir, projectRoot))
+        : undefined;
       const here = await resolvedPath(projectRoot);
       for (const [ref, entries] of Object.entries(plugins)) {
         const scope = await scopeForProject(entries, here);
-        if (scope !== null) refs.set(ref, { enabled: true, scope });
+        if (scope !== null) {
+          const local = await projectEntry(entries, here);
+          const installPath =
+            local?.installPath ?? entries.find((entry) => entry.scope === "user")?.installPath;
+          refs.set(ref, {
+            enabled:
+              typeof activation?.get(ref) === "boolean" ? activation.get(ref) === true : true,
+            scope,
+            ...(typeof installPath === "string" ? { installPath } : {}),
+            ...(activation !== undefined && typeof activation.get(ref) !== "boolean"
+              ? {
+                  activationUnverified:
+                    "Local enabledPlugins settings do not establish activation; enable this plugin in Claude before resolving its agent.",
+                }
+              : {}),
+          });
+        }
       }
       return { location: this.path, refs };
     } catch (error) {
@@ -104,33 +147,156 @@ class CodexConfigPluginsReader implements HostPluginRegistryReader {
 
 /**
  * Copilot's own registry: `enabledPlugins` in `~/.copilot/settings.json`, keyed on the same
- * `<plugin>@<marketplace>` ref as every other host and carrying a boolean. No project binding,
- * so like Codex it answers for the machine and cannot answer for one project.
+ * `<plugin>@<marketplace>` ref as every other host and carrying a boolean. Installation
+ * diagnostics retain the user registry; delegation also applies repository activation.
  */
 class CopilotSettingsPluginsReader implements HostPluginRegistryReader {
   constructor(private readonly path: string) {}
 
-  async read(_projectRoot: string): Promise<HostPluginRegistryReading> {
-    let content: string;
-    try {
-      content = await readFile(this.path, "utf8");
-    } catch (error) {
-      return failedRead(this.path, error);
-    }
+  async read(projectRoot: string, forDelegation = false): Promise<HostPluginRegistryReading> {
     try {
-      const parsed = JSON.parse(content) as { enabledPlugins?: Record<string, unknown> };
+      const parsed = (
+        forDelegation
+          ? await copilotSettingsAt(copilotSettingsPaths(dirname(this.path), projectRoot))
+          : JSON.parse(await readFile(this.path, "utf8"))
+      ) as {
+        enabledPlugins?: Record<string, unknown>;
+        extraKnownMarketplaces?: Record<string, unknown>;
+      } | null;
+      if (parsed === null) return { location: this.path, absent: true };
       const enabled = parsed.enabledPlugins;
       // Absent is a real answer here, unlike a file that would not open: Copilot writes the
       // key on its first install, so a settings file without one carries no plugin.
       if (enabled === undefined) return { location: this.path, refs: new Map() };
-      return {
-        location: this.path,
-        refs: new Map(Object.entries(enabled).map(([ref, on]) => [ref, { enabled: on !== false }])),
-      };
+      const refs = new Map<string, HostPluginRegistryEntry>();
+      for (const [ref, on] of Object.entries(enabled)) {
+        if (forDelegation && typeof on !== "boolean")
+          throw new Error(
+            `${this.path}: enabledPlugins.${ref} must be a boolean; repair this field.`
+          );
+        const at = ref.lastIndexOf("@");
+        const registration = asPlainObject(parsed.extraKnownMarketplaces?.[ref.slice(at + 1)]);
+        const source = asPlainObject(registration?.source);
+        let installPath =
+          forDelegation && on === true && at > 0
+            ? copilotInstalledPluginDir(dirname(this.path), ref.slice(at + 1), ref.slice(0, at))
+            : undefined;
+        if (
+          forDelegation &&
+          on !== false &&
+          source?.source === "directory" &&
+          typeof source.path === "string"
+        ) {
+          let catalog: Record<string, unknown> | null = null;
+          for (const relative of COPILOT_MARKETPLACE_LOCATIONS) {
+            catalog = await readObjectIfPresent(join(source.path, relative));
+            if (catalog !== null) break;
+          }
+          if (catalog === null)
+            throw new Error(
+              `${source.path}: no supported marketplace catalogue; repair its native registration.`
+            );
+          const plugin = Array.isArray(catalog.plugins)
+            ? catalog.plugins.map(asPlainObject).find((entry) => entry?.name === ref.slice(0, at))
+            : undefined;
+          if (typeof plugin?.source === "string") {
+            const pluginRoot = asPlainObject(catalog.metadata)?.pluginRoot;
+            if (pluginRoot !== undefined && (typeof pluginRoot !== "string" || pluginRoot === ""))
+              throw new Error(
+                `${source.path}: metadata.pluginRoot must be a nonempty string; repair the catalogue.`
+              );
+            installPath = join(source.path, pluginRoot ?? ".", plugin.source);
+          }
+        }
+        refs.set(ref, {
+          enabled: on !== false,
+          ...(installPath === undefined ? {} : { installPath }),
+        });
+      }
+      return { location: this.path, refs };
     } catch (error) {
-      return { location: this.path, unreadable: describeError(error) };
+      return failedRead(this.path, error);
+    }
+  }
+}
+
+async function copilotSettingsAt(
+  paths: readonly (readonly string[])[]
+): Promise<Record<string, unknown> | null> {
+  const scopes = await Promise.all(
+    paths.map((scope) =>
+      Promise.all(
+        scope.map(async (path) => ({ path, source: await readObjectIfPresent(path, true) }))
+      )
+    )
+  );
+  if (scopes.every((scope) => scope.every(({ source }) => source === null))) return null;
+  const enabledPlugins = new Map<string, unknown>();
+  const extraKnownMarketplaces = new Map<string, unknown>();
+  const conflicts = new Map<string, string>();
+  for (const scope of scopes) {
+    const seen = new Map<string, { path: string; value: unknown }>();
+    for (const { path, source } of scope) {
+      for (const [key, target] of Object.entries({ enabledPlugins, extraKnownMarketplaces })) {
+        if (source?.[key] === undefined) continue;
+        const entries = asPlainObject(source[key]);
+        if (entries === null)
+          throw new Error(`${path}: ${key} must be an object; repair this field.`);
+        for (const [ref, value] of Object.entries(entries)) {
+          const address = `${key}.${ref}`;
+          const previous = seen.get(address);
+          if (previous === undefined) conflicts.delete(address);
+          else if (!isDeepStrictEqual(previous.value, value))
+            conflicts.set(
+              address,
+              `${previous.path} and ${path}: conflicting ${address}; align these values before resolving delegation.`
+            );
+          seen.set(address, { path, value });
+          target.set(ref, value);
+        }
+      }
     }
   }
+  if (conflicts.size > 0) throw new Error([...conflicts.values()].join(" "));
+  return {
+    enabledPlugins: Object.fromEntries(enabledPlugins),
+    extraKnownMarketplaces: Object.fromEntries(extraKnownMarketplaces),
+  };
+}
+
+async function readObjectIfPresent(
+  path: string,
+  jsonc = false
+): Promise<Record<string, unknown> | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonc ? stripJsonComments(raw) : raw);
+  } catch {
+    throw new Error(`${path}: invalid JSON; repair this settings or catalogue file.`);
+  }
+  const object = asPlainObject(parsed);
+  if (object === null) throw new Error(`${path}: expected a JSON object; repair this file.`);
+  return object;
+}
+
+async function enabledPluginsAt(paths: readonly string[]): Promise<ReadonlyMap<string, unknown>> {
+  const sources = await Promise.all(paths.map((path) => readObjectIfPresent(path)));
+  const result = new Map<string, unknown>();
+  for (const [index, source] of sources.entries()) {
+    if (source?.enabledPlugins === undefined) continue;
+    const entries = asPlainObject(source.enabledPlugins);
+    if (entries === null)
+      throw new Error(`${paths[index]}: enabledPlugins must be an object; repair this field.`);
+    for (const [ref, enabled] of Object.entries(entries)) result.set(ref, enabled);
+  }
+  return result;
 }
 
 const CODEX_PLUGIN_HEADER = /^\[plugins\."(.+?)"\]\s*(?:#.*)?$/u;
@@ -199,6 +365,18 @@ function enabledInTableBody(lines: readonly (string | null)[], from: number): bo
 interface ClaudeEntry {
   readonly scope?: string;
   readonly projectPath?: string;
+  readonly installPath?: string;
+}
+
+async function projectEntry(
+  entries: readonly ClaudeEntry[],
+  projectRoot: string
+): Promise<ClaudeEntry | undefined> {
+  for (const entry of entries) {
+    if (entry.projectPath !== undefined && (await resolvedPath(entry.projectPath)) === projectRoot)
+      return entry;
+  }
+  return undefined;
 }
 
 /** A user-scoped entry applies everywhere and carries no `projectPath`; any other scope applies
@@ -212,11 +390,7 @@ async function scopeForProject(
 ): Promise<MarketplaceScope | null> {
   if (!Array.isArray(entries)) return null;
   if (entries.some((entry) => entry.scope === "user")) return "user";
-  for (const entry of entries) {
-    if (entry.projectPath === undefined) continue;
-    if ((await resolvedPath(entry.projectPath)) === projectRoot) return "project";
-  }
-  return null;
+  return (await projectEntry(entries, projectRoot)) === undefined ? null : "project";
 }
 
 /**
diff --git a/cli/src/presentation/commands/delegation.ts b/cli/src/presentation/commands/delegation.ts
new file mode 100644
index 000000000..e8ee77dcb
--- /dev/null
+++ b/cli/src/presentation/commands/delegation.ts
@@ -0,0 +1,46 @@
+import type { Command } from "commander";
+import { resolveHomeDir } from "../../kernel/reading/home-dir.js";
+import { createDeps } from "../../runtime/wiring/framework.js";
+import { ErrorHandler } from "../error-handler.js";
+import { parseGlobalOptions } from "./global-options.js";
+
+export function registerDelegationCommand(program: Command): void {
+  program
+    .command("delegation")
+    .description("Read this project's delegation suggestions")
+    .command("resolve <task>")
+    .description("Resolve a configured role and native options against an installed agent")
+    .requiredOption("--tool <id>", "AI tool whose installed agent and native options to resolve")
+    .option("--json", "Print the resolution as JSON")
+    .action(async (task: string, options: { tool: string; json?: boolean }) => {
+      const { projectRoot, verbose, output } = parseGlobalOptions(program);
+      try {
+        const deps = await createDeps(projectRoot, { verbose }, output);
+        const result = await deps.resolveDelegationUseCase.execute({
+          projectRoot,
+          home: resolveHomeDir(),
+          env: process.env,
+          task,
+          tool: options.tool,
+        });
+        if (options.json) output.print(JSON.stringify(result, null, 2));
+        else {
+          if (result.agent === undefined)
+            output.print(
+              `No configured suggestion for ${task}; the caller keeps its role and native settings.`
+            );
+          else {
+            output.print(`Agent: ${result.agent.name} (${result.agent.path})`);
+            output.print(`Requested: ${JSON.stringify(result.requested)}`);
+            output.print(
+              `Native suggestion (${result.nativeSurface}): ${JSON.stringify(result.native)}`
+            );
+            for (const diagnostic of result.diagnostics) output.warn(diagnostic);
+          }
+          output.print("Unspecified settings inherit. Effective runtime: unknown.");
+        }
+      } catch (error) {
+        new ErrorHandler(output).handle(error);
+      }
+    });
+}
diff --git a/cli/src/runtime/wiring/framework.ts b/cli/src/runtime/wiring/framework.ts
index c5f0b2b0e..9c6b2f591 100644
--- a/cli/src/runtime/wiring/framework.ts
+++ b/cli/src/runtime/wiring/framework.ts
@@ -50,6 +50,7 @@ import { PluginRemoveUseCase } from "../../contexts/framework/application/plugin
 import { PluginSearchUseCase } from "../../contexts/framework/application/plugin/plugin-search-use-case.js";
 import { PluginUpdateUseCase } from "../../contexts/framework/application/plugin/plugin-update-use-case.js";
 import { ValidateRecipesUseCase } from "../../contexts/framework/application/recipes/validate-recipes-use-case.js";
+import { ResolveDelegationUseCase } from "../../contexts/framework/application/resolve-delegation-use-case.js";
 import { RestoreUseCase } from "../../contexts/framework/application/restore/restore-use-case.js";
 import { ProjectContextDetectorUseCase } from "../../contexts/framework/application/setup/project-context-detector-use-case.js";
 import { SetupMachineScopeUseCase } from "../../contexts/framework/application/setup/setup-machine-scope-use-case.js";
@@ -127,6 +128,7 @@ interface GlobalOptions {
 }
 
 interface Deps extends TelemetryDeps {
+  resolveDelegationUseCase: ResolveDelegationUseCase;
   fs: FileReader & FileWriter & FileMerger;
   manifestRepo: ManifestRepository;
   /** `--scope user`'s own manifest repository: `userConfigDir()/manifest.json`, never nested
@@ -599,6 +601,7 @@ export async function createDeps(
     manifestRepo,
   });
   const deps: Deps = {
+    resolveDelegationUseCase: new ResolveDelegationUseCase(fs, manifestRepo, hostPluginRegistries),
     validateRecipesUseCase: new ValidateRecipesUseCase(new RecipeFilesAdapter()),
     ...telemetry,
     fs,
diff --git a/cli/tests/architecture/folder-size.arch.test.ts b/cli/tests/architecture/folder-size.arch.test.ts
index f06a6343b..0748b8d54 100644
--- a/cli/tests/architecture/folder-size.arch.test.ts
+++ b/cli/tests/architecture/folder-size.arch.test.ts
@@ -13,10 +13,10 @@ const MAX_FILES_PER_FOLDER = 10;
  * files are shuffled. The test asserts the count, so a reason nobody measured fails here.
  */
 const BASELINE: readonly { readonly path: string; readonly count: number }[] = [
-  // Twelve files carry the command surface, plus three helpers no other folder imports. That
-  // is the flattest mapping from the CLI's surface to its source; moving the helpers out
-  // would leave twelve, still over the limit and clearer about nothing.
-  { path: "src/presentation/commands", count: 15 },
+  // Thirteen files carry the command surface, including read-only delegation resolution,
+  // plus three helpers no other folder imports. One module per command keeps that mapping
+  // direct; moving helpers out would leave thirteen and clarify nothing.
+  { path: "src/presentation/commands", count: 16 },
   // One display module per command, mirroring `presentation/commands/`: that mirror is what
   // lets a command's rendering be asserted without running the binary. Fewer files would mean
   // one module rendering several commands, which is what put the printing in the actions.
@@ -37,9 +37,9 @@ const BASELINE: readonly { readonly path: string; readonly count: number }[] = [
   // not, and moving one out to make room is the shuffle this rule refuses.
   { path: "src/contexts/tools/domain", count: 11 },
 
-  // `marketplace-source-drift.ts` decides a version/migration drift, a fact about aidd's own
-  // migration: that concern belongs to `framework`, not `tools`.
-  { path: "src/contexts/framework/domain", count: 11 },
+  // Migration drift and project delegation are distinct framework vocabularies.
+  // Neither belongs in tools; a single-file folder would add no boundary.
+  { path: "src/contexts/framework/domain", count: 12 },
 
   // Four native-cache and host-CLI helpers are shared by `clean` at project and machine scope
   // both, which is what `earned-sharing.arch.test.ts` means by earned; a `clean/`-only home
diff --git a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
new file mode 100644
index 000000000..4bc33d78a
--- /dev/null
+++ b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
@@ -0,0 +1,471 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import "../../../../src/runtime/wiring/tools.js";
+import { ResolveDelegationUseCase } from "../../../../src/contexts/framework/application/resolve-delegation-use-case.js";
+import { FakeHostPluginRegistryReader } from "../../../helpers/ports/fake-host-plugin-registry-reader.js";
+import { InMemoryFileAdapter } from "../../../helpers/ports/in-memory-file-adapter.js";
+import { InMemoryManifestRepository } from "../../../helpers/ports/in-memory-manifest-repository.js";
+
+const ROOT = "/repo";
+const HOME = "/person";
+const CONFIG = join(ROOT, ".aidd", "config.json");
+
+function setup(tool: string, settings: Record<string, string> = {}) {
+  const raw = JSON.stringify({
+    telemetry: { enabled: true },
+    custom: { keep: 1 },
+    delegation: { exploration: { agent: "aidd-dev:explorer", tools: { [tool]: settings } } },
+  });
+  const fs = new InMemoryFileAdapter({ [CONFIG]: raw });
+  const repo = new InMemoryManifestRepository(null, ROOT);
+  const useCase = new ResolveDelegationUseCase(fs, repo, new Map());
+  return {
+    fs,
+    repo,
+    raw,
+    resolve: () =>
+      useCase.execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool }),
+  };
+}
+
+describe("resolving an installed delegation suggestion", () => {
+  it("returns no suggestion when the task is absent without writing configuration", async () => {
+    const fs = new InMemoryFileAdapter();
+    const useCase = new ResolveDelegationUseCase(fs, new InMemoryManifestRepository(), new Map());
+    const result = await useCase.execute({
+      projectRoot: ROOT,
+      home: HOME,
+      env: {},
+      task: "exploration",
+      tool: "codex",
+    });
+    expect(result).toMatchObject({
+      configured: false,
+      requested: {},
+      native: {},
+      effectiveRuntime: "unknown",
+    });
+    expect(await fs.fileExists(CONFIG)).toBe(false);
+  });
+
+  it("preserves a registered unsupported host's existing behavior when no task is configured", async () => {
+    const fs = new InMemoryFileAdapter();
+    const useCase = new ResolveDelegationUseCase(fs, new InMemoryManifestRepository(), new Map());
+    const result = await useCase.execute({
+      projectRoot: ROOT,
+      home: HOME,
+      env: {},
+      task: "exploration",
+      tool: "kilo",
+    });
+    expect(result).toMatchObject({ configured: false, requested: {}, native: {} });
+    expect(await fs.fileExists(CONFIG)).toBe(false);
+  });
+
+  it.each([
+    [
+      "codex",
+      ".codex/agents/aidd-dev-explorer.toml",
+      'name = "aidd-dev-explorer"\ndescription = "Explore"\ndeveloper_instructions = "Body"',
+      "model_reasoning_effort",
+    ],
+    [
+      "claude",
+      ".claude/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\ndescription: Explore\n---\nBody",
+      "effort",
+    ],
+    [
+      "opencode",
+      ".opencode/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\nmode: subagent\n---\nBody",
+      "variant",
+    ],
+    [
+      "copilot",
+      ".github/agents/aidd-dev-explorer.agent.md",
+      "---\nname: aidd-dev-explorer\n---\nBody",
+      "reasoningEffort",
+    ],
+    [
+      "cursor",
+      ".cursor/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody",
+      "embedded",
+    ],
+  ])(
+    "adapts %s settings using the installed artifact",
+    async (tool, path, content, effortField) => {
+      const { fs, repo, raw, resolve } = setup(tool, { model: "native-model", effort: "high" });
+      await fs.writeFile(join(ROOT, path), content);
+      const result = await resolve();
+      expect(result.agent).toMatchObject({
+        name: "aidd-dev-explorer",
+        path: join(ROOT, path),
+        mode: "flat",
+      });
+      expect(result.requested).toEqual({ model: "native-model", effort: "high" });
+      expect(result.native).toEqual(
+        effortField === "embedded"
+          ? { model: "native-model[effort=high]" }
+          : effortField === "variant"
+            ? { model: "native-model#high" }
+            : { model: "native-model", [effortField]: "high" }
+      );
+      expect(result.effectiveRuntime).toBe("unknown");
+      expect(await fs.readFile(CONFIG)).toBe(raw);
+      expect(repo.saveCount).toBe(0);
+    }
+  );
+
+  it("honors CODEX_HOME and inherits omitted settings", async () => {
+    const { fs, repo } = setup("codex");
+    const path = "/custom/codex/agents/aidd-dev-explorer.toml";
+    await fs.writeFile(path, 'name = "actual-role"\ndeveloper_instructions = "Body"');
+    const useCase = new ResolveDelegationUseCase(fs, repo, new Map());
+    const result = await useCase.execute({
+      projectRoot: ROOT,
+      home: HOME,
+      env: { CODEX_HOME: "/custom/codex" },
+      task: "exploration",
+      tool: "codex",
+    });
+    expect(result.agent).toMatchObject({ name: "actual-role", path });
+    expect(result.native).toEqual({});
+  });
+
+  it("uses the Copilot personal agent before the same project ID", async () => {
+    const selected = setup("copilot");
+    await selected.fs.writeFile(
+      "/repo/.github/agents/aidd-dev-explorer.agent.md",
+      "---\nname: Project\n---\nProject behavior"
+    );
+    await selected.fs.writeFile(
+      "/person/.copilot/agents/aidd-dev-explorer.agent.md",
+      "---\nname: Personal\n---\nPersonal behavior"
+    );
+    expect((await selected.resolve()).agent?.path).toBe(
+      "/person/.copilot/agents/aidd-dev-explorer.agent.md"
+    );
+  });
+
+  it("honors CLAUDE_CONFIG_DIR without reading the same role from the default profile", async () => {
+    const selected = setup("claude");
+    await selected.fs.writeFile(
+      "/person/.claude/agents/aidd-dev-explorer.md",
+      "---\nname: wrong-agent\n---\nBody"
+    );
+    await selected.fs.writeFile(
+      "/relocated/agents/aidd-dev-explorer.md",
+      "---\nname: selected-agent\n---\nBody"
+    );
+    const result = await new ResolveDelegationUseCase(
+      selected.fs,
+      selected.repo,
+      new Map()
+    ).execute({
+      projectRoot: ROOT,
+      home: HOME,
+      env: { CLAUDE_CONFIG_DIR: "/relocated" },
+      task: "exploration",
+      tool: "claude",
+    });
+    expect(result.agent).toMatchObject({
+      name: "selected-agent",
+      path: "/relocated/agents/aidd-dev-explorer.md",
+    });
+  });
+
+  it.each([
+    ["claude", ".claude/agents/aidd-dev-explorer.md", "---\nname: aidd-dev-explorer\n---\nBody"],
+    ["opencode", ".config/opencode/agents/aidd-dev-explorer.md", "---\nmode: subagent\n---\nBody"],
+    ["copilot", ".copilot/agents/aidd-dev-explorer.agent.md", "---\nname: Display name\n---\nBody"],
+    ["cursor", ".cursor/agents/aidd-dev-explorer.md", "---\nname: aidd-dev-explorer\n---\nBody"],
+  ])(
+    "finds the %s personal agent and leaves all unspecified settings inherited",
+    async (tool, relative, content) => {
+      const { fs, resolve } = setup(tool);
+      await fs.writeFile(join(HOME, relative), content);
+      const result = await resolve();
+      expect(result.agent).toMatchObject({
+        name: "aidd-dev-explorer",
+        path: join(HOME, relative),
+        mode: "flat",
+      });
+      expect(result.requested).toEqual({});
+      expect(result.native).toEqual({});
+    }
+  );
+
+  it.each([
+    ...["low", "medium", "high", "xhigh", "max"].map((effort) => [
+      "claude",
+      effort,
+      ".claude/agents/aidd-dev-explorer.md",
+      "effort",
+    ]),
+    ...["none", "minimal", "low", "medium", "high", "xhigh", "max"].map((effort) => [
+      "copilot",
+      effort,
+      ".github/agents/aidd-dev-explorer.agent.md",
+      "reasoningEffort",
+    ]),
+    [
+      "codex",
+      "model-defined-custom-effort",
+      ".codex/agents/aidd-dev-explorer.toml",
+      "model_reasoning_effort",
+    ],
+  ])(
+    "preserves %s's declared effort %s without adding a model",
+    async (tool, effort, path, field) => {
+      const { fs, resolve } = setup(tool, { effort });
+      await fs.writeFile(
+        join(ROOT, path),
+        path.endsWith(".toml")
+          ? 'name = "aidd-dev-explorer"'
+          : "---\nname: aidd-dev-explorer\n---\nBody"
+      );
+      const result = await resolve();
+      expect(result.native).toEqual({ [field]: effort });
+    }
+  );
+
+  it("names a missing agent and how to repair its installation", async () => {
+    await expect(setup("codex").resolve()).rejects.toThrow(
+      /aidd-dev:explorer.*not found.*install/i
+    );
+  });
+
+  it("uses an enabled native plugin's actual install path and its host namespace", async () => {
+    const { fs, repo } = setup("claude");
+    await fs.writeFile("/native/aidd-dev/agents/explorer.md", "---\nname: explorer\n---\nBody");
+    const registry = new FakeHostPluginRegistryReader({
+      location: "/registry.json",
+      refs: new Map([
+        [
+          "aidd-dev@my-market",
+          { enabled: true, scope: "project", installPath: "/native/aidd-dev" },
+        ],
+      ]),
+    });
+    const result = await new ResolveDelegationUseCase(
+      fs,
+      repo,
+      new Map([["claude", registry]])
+    ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "claude" });
+    expect(result.agent).toEqual({
+      name: "aidd-dev:explorer",
+      path: "/native/aidd-dev/agents/explorer.md",
+      mode: "marketplace",
+    });
+  });
+
+  it("uses the Copilot plugin filename as its namespace rather than the display name", async () => {
+    const { fs, repo } = setup("copilot");
+    await fs.writeFile(
+      "/live/aidd-dev/agents/explorer.md",
+      "---\nname: Different display name\n---\nBody"
+    );
+    const registry = new FakeHostPluginRegistryReader({
+      location: "/settings.json",
+      refs: new Map([["aidd-dev@market", { enabled: true, installPath: "/live/aidd-dev" }]]),
+    });
+    const result = await new ResolveDelegationUseCase(
+      fs,
+      repo,
+      new Map([["copilot", registry]])
+    ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "copilot" });
+    expect(result.agent).toMatchObject({ name: "aidd-dev:explorer", mode: "marketplace" });
+  });
+
+  it("prefers the project agent over a user agent and refuses disabled native plugins", async () => {
+    const { fs, repo } = setup("codex");
+    await fs.writeFile("/repo/.codex/agents/aidd-dev-explorer.toml", 'name = "project-agent"');
+    await fs.writeFile("/person/.codex/agents/aidd-dev-explorer.toml", 'name = "user-agent"');
+    expect(
+      (
+        await new ResolveDelegationUseCase(fs, repo, new Map()).execute({
+          projectRoot: ROOT,
+          home: HOME,
+          env: {},
+          task: "exploration",
+          tool: "codex",
+        })
+      ).agent?.name
+    ).toBe("project-agent");
+    const disabled = setup("claude");
+    await disabled.fs.writeFile(
+      "/native/aidd-dev/agents/explorer.md",
+      "---\nname: explorer\n---\nBody"
+    );
+    const registry = new FakeHostPluginRegistryReader({
+      location: "/registry.json",
+      refs: new Map([["aidd-dev@my-market", { enabled: false, installPath: "/native/aidd-dev" }]]),
+    });
+    await expect(
+      new ResolveDelegationUseCase(
+        disabled.fs,
+        disabled.repo,
+        new Map([["claude", registry]])
+      ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "claude" })
+    ).rejects.toThrow("disabled");
+  });
+
+  it("rejects an unsupported host, effort, and Cursor effort without an explicit model", async () => {
+    await expect(setup("kilo").resolve()).rejects.toThrow(/does not support/);
+    const invalid = setup("claude", { effort: "maximum-ish" });
+    await invalid.fs.writeFile(
+      "/repo/.claude/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody"
+    );
+    await expect(invalid.resolve()).rejects.toThrow(/effort/);
+    const missingModel = setup("cursor", { effort: "high" });
+    await missingModel.fs.writeFile(
+      "/repo/.cursor/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody"
+    );
+    await expect(missingModel.resolve()).rejects.toThrow(/explicit model/);
+  });
+
+  it("distinguishes Cursor plugin spawn settings from flat agent configuration", async () => {
+    const plugin = setup("cursor", { model: "user-catalog-slug" });
+    await plugin.fs.writeFile(
+      "/person/.cursor/plugins/local/aidd-dev/agents/explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody"
+    );
+    const result = await plugin.resolve();
+    expect(result.agent?.name).toBe("aidd-dev-explorer");
+    expect(result.nativeSurface).toBe("spawn");
+    expect(result.native).toEqual({ model: "user-catalog-slug" });
+    const effort = setup("cursor", { model: "user-catalog-slug", effort: "high" });
+    await effort.fs.writeFile(
+      "/person/.cursor/plugins/local/aidd-dev/agents/explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody"
+    );
+    await expect(effort.resolve()).rejects.toThrow(/spawn does not accept effort/);
+  });
+
+  it("refuses an older bare Cursor plugin role that could collide with a personal agent", async () => {
+    const plugin = setup("cursor");
+    await plugin.fs.writeFile(
+      "/person/.cursor/plugins/local/aidd-dev/agents/explorer.md",
+      "---\nname: explorer\n---\nAIDD"
+    );
+    await plugin.fs.writeFile(
+      "/repo/.cursor/agents/explorer.md",
+      "---\nname: explorer\n---\nOther"
+    );
+    await expect(plugin.resolve()).rejects.toThrow(/reinstall.*aidd-dev-explorer/);
+  });
+
+  it("rejects an invalid installed Codex agent instead of inventing its identity", async () => {
+    const invalid = setup("codex");
+    await invalid.fs.writeFile(
+      "/repo/.codex/agents/aidd-dev-explorer.toml",
+      'description = "No native name"'
+    );
+    await expect(invalid.resolve()).rejects.toThrow(/name/);
+  });
+
+  it("reports installed Codex pins that a spawn override would not replace", async () => {
+    const pinned = setup("codex", { model: "requested-model", effort: "high" });
+    await pinned.fs.writeFile(
+      "/repo/.codex/agents/aidd-dev-explorer.toml",
+      'name = "aidd-dev-explorer"\nmodel = "pinned-model"\nmodel_reasoning_effort = "low"'
+    );
+    const result = await pinned.resolve();
+    expect(result.native).toEqual({ model: "requested-model", model_reasoning_effort: "high" });
+    expect(result.diagnostics).toHaveLength(2);
+    expect(result.diagnostics.join(" ")).toContain("pinned-model");
+    expect(result.diagnostics.join(" ")).toContain("requested-model");
+    expect(result.diagnostics.join(" ")).toContain("low");
+    expect(result.effectiveRuntime).toBe("unknown");
+  });
+
+  it("leaves absent and matching Codex pins free of conflict diagnostics", async () => {
+    const selected = setup("codex", { model: "requested-model", effort: "high" });
+    await selected.fs.writeFile(
+      "/repo/.codex/agents/aidd-dev-explorer.toml",
+      'name = "aidd-dev-explorer"'
+    );
+    expect((await selected.resolve()).diagnostics).toEqual([]);
+    await selected.fs.writeFile(
+      "/repo/.codex/agents/aidd-dev-explorer.toml",
+      'name = "aidd-dev-explorer"\nmodel = "requested-model"\nmodel_reasoning_effort = "high"'
+    );
+    expect((await selected.resolve()).diagnostics).toEqual([]);
+  });
+
+  it.each([
+    [
+      "opencode",
+      ".opencode/agents/aidd-dev-explorer.md",
+      "provider/model#high",
+      "provider/model#low",
+    ],
+    [
+      "cursor",
+      ".cursor/agents/aidd-dev-explorer.md",
+      "native-model[effort=high]",
+      "native-model[effort=low]",
+    ],
+  ])(
+    "preserves literal %s selectors and rejects conflicting effort instead of replacing it",
+    async (tool, path, same, conflicting) => {
+      const literal = setup(tool, { model: same });
+      await literal.fs.writeFile(join(ROOT, path), "---\nname: aidd-dev-explorer\n---\nBody");
+      expect((await literal.resolve()).native).toEqual({ model: same });
+      const matching = setup(tool, { model: same, effort: "high" });
+      await matching.fs.writeFile(join(ROOT, path), "---\nname: aidd-dev-explorer\n---\nBody");
+      expect((await matching.resolve()).native).toEqual({ model: same });
+      const conflict = setup(tool, { model: conflicting, effort: "high" });
+      await conflict.fs.writeFile(join(ROOT, path), "---\nname: aidd-dev-explorer\n---\nBody");
+      await expect(conflict.resolve()).rejects.toThrow(/Conflicting/);
+    }
+  );
+
+  it.each([
+    ["claude-opus-4-8[context=1m]", "claude-opus-4-8[context=1m,effort=high]"],
+    [
+      "claude-opus-4-8[context=1m,effort=high,fast=false]",
+      "claude-opus-4-8[context=1m,effort=high,fast=false]",
+    ],
+  ])(
+    "merges Cursor effort into the existing parameter group while preserving other options",
+    async (model, expected) => {
+      const selected = setup("cursor", { model, effort: "high" });
+      await selected.fs.writeFile(
+        "/repo/.cursor/agents/aidd-dev-explorer.md",
+        "---\nname: aidd-dev-explorer\n---\nBody"
+      );
+      expect((await selected.resolve()).native).toEqual({ model: expected });
+    }
+  );
+
+  it.each([
+    ["claude-opus-4-8[context=1m,effort=high,fast=false]", "low", "Conflicting"],
+    ["model[context=]", "high", "Malformed"],
+    ["model[context=1m][fast=false]", "high", "Malformed"],
+    ["model[effort=high,effort=high]", "high", "Malformed"],
+    ["model[context=1m", "high", "Malformed"],
+  ])("refuses a conflicting or malformed Cursor parameter group", async (model, effort, reason) => {
+    const selected = setup("cursor", { model, effort });
+    await selected.fs.writeFile(
+      "/repo/.cursor/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody"
+    );
+    await expect(selected.resolve()).rejects.toThrow(reason);
+  });
+
+  it("passes a literal Cursor model unchanged when effort is omitted", async () => {
+    const selected = setup("cursor", { model: "user-literal[opaque-native-option]" });
+    await selected.fs.writeFile(
+      "/repo/.cursor/agents/aidd-dev-explorer.md",
+      "---\nname: aidd-dev-explorer\n---\nBody"
+    );
+    expect((await selected.resolve()).native).toEqual({
+      model: "user-literal[opaque-native-option]",
+    });
+  });
+});
diff --git a/cli/tests/contexts/framework/domain/delegation.unit.test.ts b/cli/tests/contexts/framework/domain/delegation.unit.test.ts
new file mode 100644
index 000000000..564bc8fba
--- /dev/null
+++ b/cli/tests/contexts/framework/domain/delegation.unit.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { parseDelegation } from "../../../../src/contexts/framework/domain/delegation.js";
+
+describe("project delegation suggestions", () => {
+  it("leaves absent tasks and settings unspecified", () => {
+    expect(
+      parseDelegation(null, "exploration", "codex", "/repo/.aidd/config.json")
+    ).toBeUndefined();
+    expect(
+      parseDelegation('{"telemetry":{"enabled":true}}', "exploration", "codex", "/c")
+    ).toBeUndefined();
+    expect(
+      parseDelegation('{"delegation":{"other":false}}', "exploration", "codex", "/c")
+    ).toBeUndefined();
+    expect(
+      parseDelegation(
+        '{"delegation":{"exploration":{"agent":"aidd-dev:explorer"}}}',
+        "exploration",
+        "codex",
+        "/c"
+      )
+    ).toEqual({
+      plugin: "aidd-dev",
+      role: "explorer",
+      canonical: "aidd-dev:explorer",
+      requested: {},
+    });
+  });
+
+  it("selects only the requested host without changing native model literals", () => {
+    const raw = JSON.stringify({
+      delegation: {
+        exploration: {
+          agent: "aidd-dev:explorer",
+          tools: { codex: { model: "provider/model-v99", effort: "high" }, other: false },
+        },
+      },
+    });
+    expect(parseDelegation(raw, "exploration", "codex", "/c")?.requested).toEqual({
+      model: "provider/model-v99",
+      effort: "high",
+    });
+  });
+
+  it.each([
+    ["{", "valid JSON"],
+    ["[]", "JSON object"],
+    ['{"delegation":[]}', "delegation"],
+    ['{"delegation":{"exploration":null}}', "delegation.exploration"],
+    ['{"delegation":{"exploration":{"agent":"../bad:role"}}}', "plugin:role"],
+    ['{"delegation":{"exploration":{"agent":"aidd-dev:explorer","models":{}}}}', "models"],
+    ['{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":[]}}}', "tools"],
+    [
+      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":null}}}}',
+      "tools.codex",
+    ],
+    [
+      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"model":""}}}}}',
+      "model",
+    ],
+    [
+      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"effort":7}}}}}',
+      "effort",
+    ],
+    [
+      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"reasoning":"high"}}}}}',
+      "reasoning",
+    ],
+  ])("reports the requested malformed field with its file", (raw, field) => {
+    expect(() => parseDelegation(raw, "exploration", "codex", "/repo/.aidd/config.json")).toThrow(
+      field
+    );
+    expect(() => parseDelegation(raw, "exploration", "codex", "/repo/.aidd/config.json")).toThrow(
+      "/repo/.aidd/config.json"
+    );
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts
index ff8a39507..77d5f723a 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts
@@ -7,6 +7,7 @@ import {
   buildCursorContract,
   buildCursorFlatContract,
 } from "../../../../../../src/contexts/tools/domain/profiles/cursor/build.js";
+import { parseFrontmatter } from "../../../../../../src/kernel/markdown.js";
 import { InMemoryFileAdapter } from "../../../../../helpers/ports/in-memory-file-adapter.js";
 
 // Built, not written literally: biome reads a string holding "${...}" as a lost template.
@@ -35,6 +36,13 @@ function sourceOf(artifact: ArtifactContract): ArtifactSource | null {
 }
 
 describe("buildCursorContract()", () => {
+  it("gives same-named plugin roles distinct native identities", () => {
+    const transform = supported(buildCursorContract().artifacts.agents).transform;
+    const first = transform?.(AGENT_SOURCE, "first-plugin", "planner.md") ?? "";
+    const second = transform?.(AGENT_SOURCE, "second-plugin", "planner.md") ?? "";
+    expect(parseFrontmatter(first).frontmatter.name).toBe("first-plugin-planner");
+    expect(parseFrontmatter(second).frontmatter.name).toBe("second-plugin-planner");
+  });
   it("declares Cursor's own plugin manifest path, schema and root token", () => {
     const contract = buildCursorContract();
 
@@ -114,7 +122,7 @@ describe("buildCursorContract()", () => {
     expect(transform?.(AGENT_SOURCE, "aidd-dev", "planner.md")).toBe(
       [
         "---",
-        "name: 'planner'",
+        "name: 'aidd-dev-planner'",
         "description: 'Plans the work'",
         "model: 'opus'",
         "---",
diff --git a/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts b/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts
index 652cd7a41..b505b948a 100644
--- a/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts
+++ b/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts
@@ -28,7 +28,7 @@ async function write(relative: string, content: string): Promise<void> {
 }
 
 function readerFor(tool: AiToolId) {
-  const reader = hostPluginRegistryReaders(home).get(tool);
+  const reader = hostPluginRegistryReaders(home, {}).get(tool);
   if (reader === undefined) throw new Error(`no reader declared for ${tool}`);
   return reader;
 }
@@ -36,6 +36,106 @@ function readerFor(tool: AiToolId) {
 describe("Claude Code's own installed_plugins.json", () => {
   const PATH = ".claude/plugins/installed_plugins.json";
 
+  it("does not treat a cached but disabled plugin as available during delegation", async () => {
+    const project = join(home, "project");
+    const cache = join(home, "cache", "aidd-dev");
+    await write(
+      PATH,
+      JSON.stringify({ plugins: { "aidd-dev@market": [{ scope: "user", installPath: cache }] } })
+    );
+    await write("cache/aidd-dev/agents/explorer.md", "---\nname: explorer\n---\nBody");
+    await write(
+      ".claude/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
+    );
+    await write(
+      "project/.claude/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
+    );
+    expect(
+      (await readerFor("claude").read(project, true)).refs?.get("aidd-dev@market")
+    ).toMatchObject({ enabled: false, installPath: cache });
+    expect((await readerFor("claude").read(project)).refs?.get("aidd-dev@market")?.enabled).toBe(
+      true
+    );
+  });
+
+  it("uses the highest mentioning Claude settings source without dropping unrelated lower keys", async () => {
+    const project = join(home, "project");
+    await write(
+      PATH,
+      JSON.stringify({
+        plugins: {
+          "aidd-dev@market": [{ scope: "user", installPath: "/cache" }],
+          "aidd-pm@market": [{ scope: "user", installPath: "/pm" }],
+        },
+      })
+    );
+    await write(
+      ".claude/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false, "aidd-pm@market": true } })
+    );
+    await write(
+      "project/.claude/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
+    );
+    await write(
+      "project/.claude/settings.local.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
+    );
+    const reading = await readerFor("claude").read(project, true);
+    expect(reading.refs?.get("aidd-dev@market")?.enabled).toBe(true);
+    expect(reading.refs?.get("aidd-pm@market")?.enabled).toBe(true);
+  });
+
+  it("marks Claude activation unverified when settings never mention the installed ref", async () => {
+    await write(
+      PATH,
+      JSON.stringify({ plugins: { "aidd-dev@market": [{ scope: "user", installPath: "/cache" }] } })
+    );
+    expect(
+      (await readerFor("claude").read(join(home, "project"), true)).refs?.get("aidd-dev@market")
+        ?.activationUnverified
+    ).toContain("enabledPlugins");
+  });
+
+  it("reads Claude's relocated settings and plugin registry rather than the default profile", async () => {
+    await write(PATH, JSON.stringify({ plugins: { "wrong@market": [{ scope: "user" }] } }));
+    await write(
+      "relocated-plugins/installed_plugins.json",
+      JSON.stringify({ plugins: { "aidd-dev@market": [{ scope: "user", installPath: "/cache" }] } })
+    );
+    await write(
+      "relocated-config/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
+    );
+    const reader = hostPluginRegistryReaders(home, {
+      CLAUDE_CONFIG_DIR: join(home, "relocated-config"),
+      CLAUDE_CODE_PLUGIN_CACHE_DIR: join(home, "relocated-plugins"),
+    }).get("claude");
+    const reading = await reader?.read(join(home, "project"), true);
+    expect(reading?.location).toBe(join(home, "relocated-plugins", "installed_plugins.json"));
+    expect(reading?.refs?.get("aidd-dev@market")?.enabled).toBe(true);
+    expect(reading?.refs?.has("wrong@market")).toBe(false);
+  });
+
+  it("carries the actual project plugin path before the user fallback for delegation", async () => {
+    await write(
+      PATH,
+      JSON.stringify({
+        plugins: {
+          "aidd-dev@market": [
+            { scope: "user", installPath: "/user/plugin" },
+            { scope: "project", projectPath: PROJECT, installPath: "/project/plugin" },
+          ],
+        },
+      })
+    );
+    expect(
+      (await readerFor("claude").read(PROJECT)).refs?.get("aidd-dev@market")?.installPath
+    ).toBe("/project/plugin");
+  });
+
   it("counts a ref installed for this project, and one installed for the machine", async () => {
     await write(
       PATH,
@@ -271,6 +371,146 @@ describe("Codex's own config.toml", () => {
 describe("Copilot's own settings.json", () => {
   const PATH = ".copilot/settings.json";
 
+  it("applies repository disablement and local re-enablement per plugin during delegation", async () => {
+    const project = join(home, "project");
+    await write(
+      PATH,
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true, "other@market": true } })
+    );
+    await write(
+      "project/.github/copilot/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
+    );
+    expect(
+      (await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")?.enabled
+    ).toBe(false);
+    expect((await readerFor("copilot").read(project)).refs?.get("aidd-dev@market")?.enabled).toBe(
+      true
+    );
+    await write(
+      "project/.github/copilot/settings.local.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
+    );
+    const reading = await readerFor("copilot").read(project, true);
+    expect(reading.refs?.get("aidd-dev@market")?.enabled).toBe(true);
+    expect(reading.refs?.get("other@market")?.enabled).toBe(true);
+  });
+
+  it("reads a repository-only Copilot registration from JSONC without using a personal profile", async () => {
+    const project = join(home, "project");
+    await write(
+      "project/.github/copilot/settings.json",
+      '// repository plugin\n{ "enabledPlugins": { "aidd-dev@market": true, }, }'
+    );
+    expect((await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")).toEqual({
+      enabled: true,
+      installPath: join(home, ".copilot", "installed-plugins", "market", "aidd-dev"),
+    });
+  });
+
+  it("does not claim activation from a malformed Copilot enabledPlugins value", async () => {
+    await write(PATH, JSON.stringify({ enabledPlugins: { "aidd-dev@market": "false" } }));
+    const reading = await readerFor("copilot").read(PROJECT, true);
+    expect(reading.refs).toBeUndefined();
+    expect(reading.unreadable).toContain("enabledPlugins.aidd-dev@market must be a boolean");
+  });
+
+  it("reports conflicting cross-tool settings and accepts an explicit higher-scope answer", async () => {
+    const project = join(home, "project");
+    await write(
+      "project/.claude/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
+    );
+    await write(
+      "project/.github/copilot/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
+    );
+    const conflicting = await readerFor("copilot").read(project, true);
+    expect(conflicting.refs).toBeUndefined();
+    expect(conflicting.unreadable).toContain("conflicting enabledPlugins.aidd-dev@market");
+    await write(
+      "project/.github/copilot/settings.local.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
+    );
+    expect(
+      (await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")?.enabled
+    ).toBe(true);
+    await write(
+      "project/.github/copilot/settings.json",
+      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
+    );
+    await rm(join(project, ".github", "copilot", "settings.local.json"));
+    expect(
+      (await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")?.enabled
+    ).toBe(false);
+  });
+
+  it.each([
+    "marketplace.json",
+    ".plugin/marketplace.json",
+    ".github/plugin/marketplace.json",
+    ".claude-plugin/marketplace.json",
+  ])("locates a live directory plugin through %s", async (catalogPath) => {
+    const marketplace = join(home, "market");
+    await write(
+      `market/${catalogPath}`,
+      JSON.stringify({ plugins: [{ name: "aidd-dev", source: "./plugins/aidd-dev" }] })
+    );
+    await write(
+      PATH,
+      JSON.stringify({
+        enabledPlugins: { "aidd-dev@market": true },
+        extraKnownMarketplaces: { market: { source: { source: "directory", path: marketplace } } },
+      })
+    );
+    expect(
+      (await readerFor("copilot").read(PROJECT, true)).refs?.get("aidd-dev@market")?.installPath
+    ).toBe(join(marketplace, "plugins", "aidd-dev"));
+  });
+
+  it("locates a remote Copilot plugin in its documented installed cache under COPILOT_HOME", async () => {
+    const config = join(home, "relocated-copilot");
+    await write(
+      ".copilot/settings.json",
+      JSON.stringify({ enabledPlugins: { "wrong@market": true } })
+    );
+    await write(
+      "relocated-copilot/settings.json",
+      JSON.stringify({
+        enabledPlugins: { "aidd-dev@market": true },
+        extraKnownMarketplaces: { market: { source: { source: "github", repo: "owner/repo" } } },
+      })
+    );
+    const reader = hostPluginRegistryReaders(home, { COPILOT_HOME: config }).get("copilot");
+    const reading = await reader?.read(join(home, "project"), true);
+    expect(reading?.location).toBe(join(config, "settings.json"));
+    expect(reading?.refs?.get("aidd-dev@market")?.installPath).toBe(
+      join(config, "installed-plugins", "market", "aidd-dev")
+    );
+    expect(reading?.refs?.has("wrong@market")).toBe(false);
+  });
+
+  it("uses the installed cache for a remote plugin listed by a live directory marketplace", async () => {
+    await write(
+      "market/.plugin/marketplace.json",
+      JSON.stringify({
+        plugins: [{ name: "aidd-dev", source: { source: "github", repo: "owner/plugin" } }],
+      })
+    );
+    await write(
+      PATH,
+      JSON.stringify({
+        enabledPlugins: { "aidd-dev@market": true },
+        extraKnownMarketplaces: {
+          market: { source: { source: "directory", path: join(home, "market") } },
+        },
+      })
+    );
+    expect(
+      (await readerFor("copilot").read(PROJECT, true)).refs?.get("aidd-dev@market")?.installPath
+    ).toBe(join(home, ".copilot", "installed-plugins", "market", "aidd-dev"));
+  });
+
   it("reads the refs its enabledPlugins carries", async () => {
     await write(
       PATH,
diff --git a/cli/tests/e2e/delegation.e2e.test.ts b/cli/tests/e2e/delegation.e2e.test.ts
new file mode 100644
index 000000000..c93b4f9e7
--- /dev/null
+++ b/cli/tests/e2e/delegation.e2e.test.ts
@@ -0,0 +1,202 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createTestEnv, FRAMEWORK_PATH, runCli } from "./helpers.js";
+
+describe("project delegation queries", () => {
+  it("resolves a Copilot agent from the generated marketplace's declared plugin root", async () => {
+    const { tempDir, projectDir, fakeHome, cleanup } = await createTestEnv(
+      "delegation-copilot-build"
+    );
+    try {
+      const market = join(tempDir, "market");
+      const build = await runCli(
+        ["translate", FRAMEWORK_PATH, "--to", "copilot", "--out", market],
+        projectDir,
+        fakeHome
+      );
+      expect(build.exitCode).toBe(0);
+      const config = join(projectDir, ".aidd", "config.json");
+      const personal = join(fakeHome, ".copilot");
+      await mkdir(dirname(config), { recursive: true });
+      await mkdir(personal, { recursive: true });
+      await writeFile(
+        config,
+        JSON.stringify({ delegation: { review: { agent: "aidd-test:code-reviewer" } } })
+      );
+      await writeFile(
+        join(personal, "settings.json"),
+        JSON.stringify({
+          enabledPlugins: { "aidd-test@market": true },
+          extraKnownMarketplaces: { market: { source: { source: "directory", path: market } } },
+        })
+      );
+      const result = await runCli(
+        ["delegation", "resolve", "review", "--tool", "copilot", "--json"],
+        projectDir,
+        fakeHome
+      );
+      expect(result.exitCode, result.stderr).toBe(0);
+      expect(JSON.parse(result.stdout).agent).toEqual({
+        name: "aidd-test:code-reviewer",
+        path: join(market, "plugins", "aidd-test", "agents", "code-reviewer.md"),
+        mode: "marketplace",
+      });
+    } finally {
+      await cleanup();
+    }
+  });
+  it("shows conflicting native Codex pins in default text output", async () => {
+    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation-pins");
+    try {
+      const config = join(projectDir, ".aidd", "config.json");
+      const agent = join(projectDir, ".codex", "agents", "aidd-dev-explorer.toml");
+      await mkdir(dirname(config), { recursive: true });
+      await mkdir(dirname(agent), { recursive: true });
+      await writeFile(
+        config,
+        JSON.stringify({
+          delegation: {
+            exploration: {
+              agent: "aidd-dev:explorer",
+              tools: { codex: { model: "requested-model" } },
+            },
+          },
+        })
+      );
+      await writeFile(
+        agent,
+        'name = "aidd-dev-explorer"\nmodel = "pinned-model"\ndescription = "Explore"\ndeveloper_instructions = "Body"'
+      );
+      const result = await runCli(
+        ["delegation", "resolve", "exploration", "--tool", "codex"],
+        projectDir,
+        fakeHome
+      );
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toContain("pinned-model");
+      expect(result.stderr).toContain("requested-model");
+      expect(result.stdout).toContain(agent);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it("rejects a disabled cached Claude plugin and accepts an explicit local enablement", async () => {
+    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation-activation");
+    try {
+      const config = join(projectDir, ".aidd", "config.json");
+      const personal = join(fakeHome, ".claude");
+      const plugins = join(personal, "plugins");
+      const installed = join(plugins, "cache", "aidd-dev");
+      const local = join(projectDir, ".claude", "settings.local.json");
+      await mkdir(dirname(config), { recursive: true });
+      await mkdir(join(installed, "agents"), { recursive: true });
+      await mkdir(dirname(local), { recursive: true });
+      await writeFile(
+        config,
+        JSON.stringify({ delegation: { exploration: { agent: "aidd-dev:explorer" } } })
+      );
+      await writeFile(join(installed, "agents", "explorer.md"), "---\nname: explorer\n---\nBody");
+      await writeFile(
+        join(plugins, "installed_plugins.json"),
+        JSON.stringify({
+          plugins: { "aidd-dev@market": [{ scope: "user", installPath: installed }] },
+        })
+      );
+      await writeFile(
+        join(personal, "settings.json"),
+        JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
+      );
+      const options = {
+        env: { CLAUDE_CONFIG_DIR: personal, CLAUDE_CODE_PLUGIN_CACHE_DIR: plugins },
+      };
+      const disabled = await runCli(
+        ["delegation", "resolve", "exploration", "--tool", "claude", "--json"],
+        projectDir,
+        fakeHome,
+        options
+      );
+      expect(disabled.exitCode).toBe(1);
+      expect(disabled.stderr).toContain("disabled");
+      await writeFile(local, JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } }));
+      const enabled = await runCli(
+        ["delegation", "resolve", "exploration", "--tool", "claude", "--json"],
+        projectDir,
+        fakeHome,
+        options
+      );
+      expect(enabled.exitCode).toBe(0);
+      expect(JSON.parse(enabled.stdout).agent).toMatchObject({
+        name: "aidd-dev:explorer",
+        path: join(installed, "agents", "explorer.md"),
+        mode: "marketplace",
+      });
+    } finally {
+      await cleanup();
+    }
+  });
+  it("resolves a real installed agent, emits native suggestions, and never rewrites config", async () => {
+    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation");
+    try {
+      const path = join(projectDir, ".aidd", "config.json");
+      const agent = join(projectDir, ".codex", "agents", "aidd-dev-explorer.toml");
+      const raw =
+        '{"telemetry":{"enabled":true},"custom":7,"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"model":"user-model","effort":"high"}}}}}\n';
+      await mkdir(dirname(path), { recursive: true });
+      await mkdir(dirname(agent), { recursive: true });
+      await writeFile(path, raw);
+      await writeFile(
+        agent,
+        'name = "aidd-dev-explorer"\ndescription = "Explore"\ndeveloper_instructions = "Body"\n'
+      );
+      const result = await runCli(
+        ["delegation", "resolve", "exploration", "--tool", "codex", "--json"],
+        projectDir,
+        fakeHome
+      );
+      expect(result.exitCode).toBe(0);
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        configured: true,
+        canonicalAgent: "aidd-dev:explorer",
+        agent: { name: "aidd-dev-explorer", path: agent },
+        requested: { model: "user-model", effort: "high" },
+        native: { model: "user-model", model_reasoning_effort: "high" },
+        effectiveRuntime: "unknown",
+      });
+      expect(await readFile(path, "utf8")).toBe(raw);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it("reports inheritance for an absent task, and diagnoses malformed config on stderr", async () => {
+    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation-missing");
+    try {
+      const inherited = await runCli(
+        ["delegation", "resolve", "exploration", "--tool", "codex", "--json"],
+        projectDir,
+        fakeHome
+      );
+      expect(inherited.exitCode).toBe(0);
+      expect(JSON.parse(inherited.stdout)).toMatchObject({
+        configured: false,
+        requested: {},
+        native: {},
+      });
+      const path = join(projectDir, ".aidd", "config.json");
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, "{");
+      const failed = await runCli(
+        ["delegation", "resolve", "exploration", "--tool", "codex"],
+        projectDir,
+        fakeHome
+      );
+      expect(failed.exitCode).toBe(1);
+      expect(failed.stderr).toContain(path);
+      expect(failed.stderr).toContain("valid JSON");
+    } finally {
+      await cleanup();
+    }
+  });
+});
diff --git a/cli/tests/e2e/helpers.ts b/cli/tests/e2e/helpers.ts
index a82d40ab2..023add92f 100644
--- a/cli/tests/e2e/helpers.ts
+++ b/cli/tests/e2e/helpers.ts
@@ -272,6 +272,9 @@ export function sandboxedEnv(
     // Defaults, before `extra`: a caller passing one means to change it. The sandbox's own
     // home variables come after, where nothing can override them.
     AIDD_USER_CONFIG_DIR: join(fakeHome, ".config", "aidd"),
+    CLAUDE_CONFIG_DIR: join(fakeHome, ".claude"),
+    CLAUDE_CODE_PLUGIN_CACHE_DIR: join(fakeHome, ".claude", "plugins"),
+    COPILOT_HOME: join(fakeHome, ".copilot"),
     // The check asks GitHub for the latest release and prints a notice from the answer, so
     // captured stderr would change with every publish.
     AIDD_SKIP_UPDATE_CHECK: "1",
diff --git a/cli/tests/golden/snapshots/framework-build/golden.json b/cli/tests/golden/snapshots/framework-build/golden.json
index 7add7ffbf..3e56ae9fd 100644
--- a/cli/tests/golden/snapshots/framework-build/golden.json
+++ b/cli/tests/golden/snapshots/framework-build/golden.json
@@ -693,9 +693,9 @@
     "plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md": "cacb673334d8947c3c252feaaf0ef50c269c06c5cf8f51b45663cbd42402e094",
     "plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md": "6f6cddd0893888c71b0aed5ecfe48217afe0eef10feec6415db433bfcc69f8e3",
     "plugins/aidd-dev/skills/00-sdlc/SKILL.md": "19bd4a8cf8c6531a6db232c31855e39475c71e2b58c91b439832d813ff594b78",
-    "plugins/aidd-dev/agents/implementer.md": "61b4531baa060e9b77c41cf1938c6c6433482dfdfe5eb3a774453d45cfe8b092",
-    "plugins/aidd-dev/agents/planner.md": "de6efeda286fe33a5245a9ed3cf9e60b78946575a5bd66b359b2428adac51ba5",
-    "plugins/aidd-dev/agents/reviewer.md": "bc5ffdc650d701c73b5da1e5eba904419e33346aac5c68bffdcd53b1e0476432",
+    "plugins/aidd-dev/agents/implementer.md": "3447d0684155742c21a8692cf95057dd4f90019298e9e5cb6c4e613993393365",
+    "plugins/aidd-dev/agents/planner.md": "074147c1268518db93623ed1c88681e78bfabdf57bcc51e23a19c306aa8f7394",
+    "plugins/aidd-dev/agents/reviewer.md": "7d501f19569f48a2bfa04e134b26323645ab08987f88ae8a59ed6e65992a9d3d",
     "plugins/aidd-dev/.cursor-plugin/plugin.json": "6e892c043c48fdc258cf7d13f1feba463483a91543686da3b30b260296235334",
     "plugins/aidd-context/skills/06-discovery/SKILL.md": "28f82e034ed5707ad6e59b012680a94ff5935bc7f8a0b5407caeea20ccb2667a",
     "plugins/aidd-context/skills/06-discovery/actions/01-find-skill.md": "600caf7822017bfe75d40773e1673ada784227b98f5b88d4ba98a57822fa0dcf",
@@ -795,7 +795,7 @@
     "plugins/aidd-async-dev/skills/01-setup/actions/skills/04-write-config.md": "eb7ecb812e8bdaaeba2e56c71c77bf8c14fce0a2c44311ff7985444617635dd5",
     "plugins/aidd-async-dev/skills/01-setup/actions/skills/05-bootstrap-labels.md": "f53177ce1c58767f1bdfcfa3e72f7d4cc5e3d4fd782c35c3998815317be108b1",
     "plugins/aidd-async-dev/hooks/hooks.json": "78922a784ee78e9e50587e93628cd3b9d4dfbe49087adc4514e6781cea38cbb9",
-    "plugins/aidd-async-dev/agents/async-orchestrator.md": "8b29ba73f27414e75c89c6453c0557212790d00d6becfadba363466999f2c9de",
+    "plugins/aidd-async-dev/agents/async-orchestrator.md": "5ca31d8117dcc4800265ab04093432090485fdda1de8a867b29c3d3e55d30e3d",
     "plugins/aidd-async-dev/.cursor-plugin/plugin.json": "8d9b5b5edc8ac5d51cdb24bc5605b30ed3149616bfbbcc69db45f35d477315d5",
     ".cursor-plugin/marketplace.json": "d197f330a5787647d58c7dc20253c8ef8b59c4dce115fdd7f12de45ccec7b18e"
   },
diff --git a/cli/tests/golden/snapshots/help/surface.json b/cli/tests/golden/snapshots/help/surface.json
index df25c9430..6ecf95719 100644
--- a/cli/tests/golden/snapshots/help/surface.json
+++ b/cli/tests/golden/snapshots/help/surface.json
@@ -2,7 +2,7 @@
   {
     "invocation": "aidd",
     "exitCode": 0,
-    "help": "Usage: aidd [options] [command]\n\nGenerate AI coding assistant configurations from the AIDD framework\n\nOptions:\n  -V, --version                 Show version number\n  --verbose                     Show detailed diagnostic output (default: false)\n  -h, --help                    display help for command\n\nCommands:\n  setup [options]               Set up or update the project to a correct state\n                                — bootstraps the whole project (marketplace,\n                                framework, tools, plugins); see `framework\n                                install`, which acts on the framework alone\n  framework                     Manage the framework's lifecycle on installed\n                                tools\n  translate [options] <source>  Convert an arbitrary source into a target-native\n                                plugin tree — records nothing (see `sync` for\n                                the manifest-driven, tracked version)\n  plugin                        Manage plugins for AI tools\n  marketplace                   Manage plugin marketplaces\n  auth                          Manage authentication\n  sync [options] [files...]     Rewrite owned files from what is already there —\n                                regenerate tracked files, driven by the manifest\n                                (see `translate`, which converts a source\n                                without recording anything)\n  update|upgrade [options]      Update the aidd CLI itself to the latest version\n  doctor [options]              Detected and equipped tools, plugins, drift, and\n                                problems — across all tools or one\n  clean [options]               Remove all AIDD-managed files from the project —\n                                retires every part of AIDD; see `framework\n                                remove`, which removes the framework only\n  telemetry                     Control whether AIDD may measure this project\n  help [command]                display help for command"
+    "help": "Usage: aidd [options] [command]\n\nGenerate AI coding assistant configurations from the AIDD framework\n\nOptions:\n  -V, --version                 Show version number\n  --verbose                     Show detailed diagnostic output (default: false)\n  -h, --help                    display help for command\n\nCommands:\n  setup [options]               Set up or update the project to a correct state\n                                — bootstraps the whole project (marketplace,\n                                framework, tools, plugins); see `framework\n                                install`, which acts on the framework alone\n  framework                     Manage the framework's lifecycle on installed\n                                tools\n  translate [options] <source>  Convert an arbitrary source into a target-native\n                                plugin tree — records nothing (see `sync` for\n                                the manifest-driven, tracked version)\n  plugin                        Manage plugins for AI tools\n  marketplace                   Manage plugin marketplaces\n  auth                          Manage authentication\n  sync [options] [files...]     Rewrite owned files from what is already there —\n                                regenerate tracked files, driven by the manifest\n                                (see `translate`, which converts a source\n                                without recording anything)\n  update|upgrade [options]      Update the aidd CLI itself to the latest version\n  doctor [options]              Detected and equipped tools, plugins, drift, and\n                                problems — across all tools or one\n  clean [options]               Remove all AIDD-managed files from the project —\n                                retires every part of AIDD; see `framework\n                                remove`, which removes the framework only\n  telemetry                     Control whether AIDD may measure this project\n  delegation                    Read this project's delegation suggestions\n  help [command]                display help for command"
   },
   {
     "invocation": "aidd auth",
@@ -29,6 +29,16 @@
     "exitCode": 0,
     "help": "Usage: aidd clean [options]\n\nRemove all AIDD-managed files from the project — retires every part of AIDD; see\n`framework remove`, which removes the framework only\n\nOptions:\n  --force          Confirm file removal (skip dry-run) (default: false)\n  --scope <scope>  project (default) cleans this project alone; user undoes the\n                   machine-wide registration setup --scope user wrote and purges\n                   the shared source itself\n  -h, --help       display help for command"
   },
+  {
+    "invocation": "aidd delegation",
+    "exitCode": 0,
+    "help": "Usage: aidd delegation [options] [command]\n\nRead this project's delegation suggestions\n\nOptions:\n  -h, --help                display help for command\n\nCommands:\n  resolve [options] <task>  Resolve a configured role and native options against\n                            an installed agent\n  help [command]            display help for command"
+  },
+  {
+    "invocation": "aidd delegation resolve",
+    "exitCode": 0,
+    "help": "Usage: aidd delegation resolve [options] <task>\n\nResolve a configured role and native options against an installed agent\n\nOptions:\n  --tool <id>  AI tool whose installed agent and native options to resolve\n  --json       Print the resolution as JSON\n  -h, --help   display help for command"
+  },
   {
     "invocation": "aidd doctor",
     "exitCode": 0,
diff --git a/cli/tests/golden/snapshots/phase0/snapshot.json b/cli/tests/golden/snapshots/phase0/snapshot.json
index 93c16f4cf..ef5b78054 100644
--- a/cli/tests/golden/snapshots/phase0/snapshot.json
+++ b/cli/tests/golden/snapshots/phase0/snapshot.json
@@ -734,7 +734,7 @@
               "files": {
                 "aidd-test/.cursor-plugin/plugin.json": "af3965dc3bb38289cd5501b7244926fa",
                 "aidd-test/.mcp.json": "8d5f495dc98074770f3390b2271ddf4a",
-                "aidd-test/agents/code-reviewer.md": "3085f2108f7b9448d523f1555a802bb2",
+                "aidd-test/agents/code-reviewer.md": "3e043789b6143a92278595e43ce96cda",
                 "aidd-test/skills/commit/SKILL.md": "01c4b6a281146776eb7304577c56bb79",
                 "aidd-test/skills/hello.md": "f00ea16a97341b9314df0da073633624"
               },
diff --git a/cli/tsup.config.ts b/cli/tsup.config.ts
index 259e75774..dd790213d 100644
--- a/cli/tsup.config.ts
+++ b/cli/tsup.config.ts
@@ -64,6 +64,9 @@ export default defineConfig({
     };
     options.minifySyntax = true;
     options.minifyWhitespace = true;
+    // Compact local bindings while preserving names used by errors and diagnostics.
+    options.minifyIdentifiers = true;
+    options.keepNames = true;
   },
   async onSuccess() {
     copyFileSync(
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
new file mode 100644
index 000000000..d43a811b7
--- /dev/null
+++ b/docs/DELEGATION.md
@@ -0,0 +1,60 @@
+# Delegation
+
+The caller chooses bounded work, invokes the agent, and accepts the result. Project settings suggest a role and native options; they do not start agents or change host settings.
+
+## Configure
+
+Merge a `delegation` entry into the project's `.aidd/config.json`, preserving its other keys:
+
+```json
+{
+  "delegation": {
+    "exploration": {
+      "agent": "aidd-dev:explorer",
+      "tools": {
+        "claude": { "model": "haiku", "effort": "low" },
+        "codex": { "model": "gpt-6-luna", "effort": "high" },
+        "opencode": { "model": "openai/gpt-6-luna", "effort": "low" },
+        "copilot": { "model": "gpt-6-luna" },
+        "cursor": {}
+      }
+    }
+  }
+}
+```
+
+Use `implementation` → `aidd-dev:executor`, `validation` → `aidd-dev:validator`, and `verification` → `aidd-dev:reviewer` for the other tasks. Task names are caller-defined. Omitted settings keep native inheritance; no model is installed as a framework default.
+
+```sh
+aidd delegation resolve exploration --tool claude --json
+```
+
+Resolution verifies the installed agent and returns its native identity, requested settings, native suggestion, and target surface. `agent-configuration` fields belong in a native agent definition; `spawn` fields belong to the host's invocation. These are suggestions, not proof of application: effective runtime stays `unknown`. The caller uses a supported native equivalent, or explains why it overrides or cannot apply the suggestion. Invalid settings and unavailable agents fail with a diagnostic. Resolution writes nothing.
+
+## Model starting points
+
+Editable choices, conditional on the account's available models. Keep simple lookups direct; delegate bounded questions or repetitive work when the context saved justifies startup. Measure the whole parent-and-child run before choosing a cheaper model for a recurring task.
+
+| Host | Routine exploration / implementation / validation | Ambiguous work / review | Native model and effort |
+| --- | --- | --- | --- |
+| Claude Code | `haiku`, `low` | `opus`, `high` | `model` and `effort`; aliases resolved by Claude |
+| Codex | `gpt-6-luna`, `high` | `gpt-6.1-sol`, `high` | `model` and `model_reasoning_effort` |
+| OpenCode V2 | `openai/gpt-6-luna`, `low` | `openai/gpt-6.1-sol`, `high` | `model: provider/model#variant` |
+| GitHub Copilot | `gpt-6-luna`, inherited effort | Inherit the caller's selected model | Agent `model` / `reasoningEffort`; invocation support differs |
+| Cursor | Inherit | Inherit; select an advertised model slug when available | Plugin Task `model`; flat agent `model[effort=level]` |
+
+- **Availability:** local Codex accepted `gpt-5.6-sol` with `low`; requests for `gpt-6-luna` were rejected by the signed-in backend. The recommendation is not an account entitlement.
+- **Precedence:** Codex agent-file pins override spawn settings. Claude environment or managed settings can override requests. OpenCode variants belong to the selected model. Keep model IDs literal; avoid translating aliases between providers.
+- **Copilot:** tested 1.0.98. A per-call `gpt-6-luna` override worked while the same root CLI selection failed. Actual child effort remained `medium` despite a low request; omit effort on this account rather than claim it applied.
+- **Cursor:** the tested Free account accepts Auto/inheritance and rejects named-model execution. Plugin frontmatter model settings are stripped; use Task's advertised model slug. Plugin effort has no independent parameter; the resolver rejects it. Flat model options require an explicit model.
+
+Sources read **2026-10-15**: [Claude selection and effort](https://code.claude.com/docs/en/sub-agents), [Codex selection and precedence](https://learn.chatgpt.com/docs/agent-configuration/subagents), [OpenCode V2 agents](https://opencode.ai/v2/docs/agents), [OpenCode variants](https://opencode.ai/v2/docs/models), [Copilot CLI agent configuration](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference), [Cursor subagents](https://cursor.com/docs/subagents). Versioned observations and limitations are recorded in the [verification record](../aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md).
+
+## Test a change
+
+1. **Resolve:** use a disposable project with the generated native agents and a delegation entry. Run the command above for each host. Check native identity/options; omit settings and confirm no defaults appear. Try a missing role or unsupported option and confirm a diagnostic. Compare configuration bytes before and after.
+2. **Invoke:** start the resolved role through the native host. Test read-only exploration, a bounded implementation, a failing completion check, and an independent quality review. Confirm only the executor changes assigned files.
+3. **Inspect:** record host version, invocation, delivery mode and scope. Use native dispatch events and model/effort traces; an agent's self-report or a generated file does not prove execution. Record substitutions, unavailable values and inherited settings.
+4. **Compare:** run the same exploration and repetitive implementation directly and through a fresh child. Record all parent/child input, cached input and output tokens, latency, task retries, and independently checked output quality. Keep failed attempts visible. Host cost estimates depend on cache state and do not establish general savings.
+
+`make reload` refreshes every plugin and the managed agent table for installed hosts. Cursor local plugin imports must be enabled. Restart hosts or reload their configuration before testing discovery.

From efdb81f2675d38b843ec96719783dd6e229b5714 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 13:44:11 +0800
Subject: [PATCH 17/73] feat(framework): reload all plugins across five hosts

---
 AGENTS.md                            |   8 +-
 Makefile                             |   7 +-
 aidd_docs/memory/deployment.md       |   2 +-
 scripts/__tests__/dev-sync.test.js   | 384 +++++++++++++++++++++++++--
 scripts/dev-sync.sh                  | 137 ++++++++--
 scripts/sync-global-instructions.cjs |   3 +
 6 files changed, 494 insertions(+), 47 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index d1b9d9208..fda94fc0f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,10 +39,10 @@ Use available agents when useful. The caller owns scope, delegation, and final a
 <!-- aidd_agents:start -->
 | name | role |
 | --- | --- |
-| @aidd-dev-explorer (Codex, OpenCode), @aidd-dev:explorer (Claude) | Explore the codebase and return relevant files, code, and explanations for a scoped question. |
-| @aidd-dev-executor (Codex, OpenCode), @aidd-dev:executor (Claude) | Implement assigned work and return changes with verification evidence. |
-| @aidd-dev-validator (Codex, OpenCode), @aidd-dev:validator (Claude) | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
-| @aidd-dev-reviewer (Codex, OpenCode), @aidd-dev:reviewer (Claude) | Review quality and coherence against project conventions and the quality checklist. |
+| @aidd-dev-explorer (Codex, Cursor, OpenCode), @aidd-dev:explorer (Claude, Copilot) | Explore the codebase and return relevant files, code, and explanations for a scoped question. |
+| @aidd-dev-executor (Codex, Cursor, OpenCode), @aidd-dev:executor (Claude, Copilot) | Implement assigned work and return changes with verification evidence. |
+| @aidd-dev-validator (Codex, Cursor, OpenCode), @aidd-dev:validator (Claude, Copilot) | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
+| @aidd-dev-reviewer (Codex, Cursor, OpenCode), @aidd-dev:reviewer (Claude, Copilot) | Review quality and coherence against project conventions and the quality checklist. |
 <!-- aidd_agents:end -->
 
 ## Memory Management
diff --git a/Makefile b/Makefile
index 67fc69349..24aa053b7 100644
--- a/Makefile
+++ b/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
diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index ff79cff50..6daf21d15 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -58,7 +58,7 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 ## Local reload
 
-`make reload` syncs all plugins and global instructions to Claude, Codex, and OpenCode; details in `scripts/dev-sync.sh`.
+`make reload` syncs all plugins and agent-only global instructions to installed hosts; details in `scripts/dev-sync.sh`.
 
 ## Monitoring
 
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 739ebba60..920018a83 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -120,15 +120,40 @@ test("malformed managed blocks and missing agent sections leave all global files
   }
 });
 
+test("Copilot and Cursor global instructions retain personal rules and native rule activation", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-global-native-rules-"));
+  try {
+    const source = join(root, "source.md"), copilot = join(root, "copilot-instructions.md"), cursor = join(root, "aidd-agents.mdc");
+    writeFileSync(source, instructionSource);
+    writeFileSync(copilot, "Copilot personal rule.\n");
+    sync(source, [["copilot", copilot], ["cursor", cursor]]);
+    assert.match(readFileSync(copilot, "utf8"), /^Copilot personal rule\.\n/);
+    const rule = readFileSync(cursor, "utf8");
+    assert.match(rule, /^---\nalwaysApply: true\n---\n/);
+    for (const [file, name] of [[copilot, "@aidd-dev:executor"], [cursor, "@aidd-dev-executor"]]) {
+      assert.ok(readFileSync(file, "utf8").includes(`| ${name} |`));
+      assert.doesNotMatch(readFileSync(file, "utf8"), /aidd_docs|Memory|ARCHITECTURE/);
+    }
+    writeFileSync(cursor, rule + "\nPersonal closing rule.\n");
+    sync(source, [["copilot", copilot], ["cursor", cursor]]);
+    const updated = readFileSync(cursor, "utf8");
+    assert.match(updated, /^---\nalwaysApply: true\n---\n/);
+    assert.ok(updated.endsWith("Personal closing rule.\n"));
+    sync(source, [["cursor", cursor]]);
+    assert.equal(readFileSync(cursor, "utf8"), updated);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
 function executable(path, body) {
   writeFileSync(path, `#!/bin/sh\nset -eu\n${body}\n`);
   chmodSync(path, 0o755);
 }
 
-function fixture(home) {
+function fixture(home, plugins = ["aidd-dev"]) {
   const source = join(home, "framework");
   if (!existsSync(source)) {
     for (const [plugin, skill, agents] of [["aidd-dev", "01-plan", devAgents], ["aidd-pm", "03-prd", []]]) {
+      if (!plugins.includes(plugin)) continue;
       const pluginDir = join(source, "plugins", plugin);
       mkdirSync(join(pluginDir, ".claude-plugin"), { recursive: true });
       writeFileSync(join(pluginDir, ".claude-plugin/plugin.json"), "{}\n");
@@ -172,6 +197,9 @@ function runSync(fakeBin, home, args = ["all"], overrides = {}) {
       CODEX_INSTRUCTIONS: join(home, ".codex/AGENTS.md"),
       CLAUDE_INSTRUCTIONS: join(home, ".claude/CLAUDE.md"),
       OPENCODE_INSTRUCTIONS: join(home, ".config/opencode/AGENTS.md"),
+      COPILOT_INSTRUCTIONS: join(home, ".copilot/copilot-instructions.md"),
+      CURSOR_INSTRUCTIONS: join(home, ".cursor/rules/aidd-agents.mdc"),
+      CURSOR_PLUGINS: join(home, ".cursor/plugins/local"),
       OPENCODE_DISABLE_CLAUDE_CODE: "",
       OPENCODE_DISABLE_CLAUDE_CODE_PROMPT: "",
       ...overrides,
@@ -227,7 +255,7 @@ test("reload delivers global instructions to all three hosts while preserving pe
     const home = join(root, "home");
     mkdirSync(fakeBin);
     mkdirSync(home);
-    const source = fixture(home);
+    const source = fixture(home, ["aidd-pm"]);
     writeFileSync(join(source, "AGENTS.md"), instructionSource);
     const destinations = [[".codex/AGENTS.md", "@aidd-dev-executor"], [".claude/CLAUDE.md", "@aidd-dev:executor"], [".config/opencode/AGENTS.md", "@aidd-dev-executor"]];
     for (const [path] of destinations) {
@@ -242,7 +270,7 @@ while [ "$#" -gt 0 ]; do
 done
 mkdir -p "$out/.opencode/skills/aidd-pm-03-prd"
 printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-pm-03-prd/SKILL.md"`);
-    const first = runSync(fakeBin, home, ["aidd-pm"]);
+    const first = runSync(fakeBin, home, []);
     assert.equal(first.status, 0, first.stderr);
     assert.match(first.stdout, /global instructions\s+ok/);
     const contents = destinations.map(([path, name]) => {
@@ -252,7 +280,7 @@ printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-pm-03-prd/SKILL.md"`);
       assert.doesNotMatch(content, /Memory|aidd_docs|ARCHITECTURE/);
       return content;
     });
-    const second = runSync(fakeBin, home, ["aidd-pm"]);
+    const second = runSync(fakeBin, home, []);
     assert.equal(second.status, 0, second.stderr);
     destinations.forEach(([path], index) => assert.equal(readFileSync(join(home, path), "utf8"), contents[index]));
   } finally {
@@ -261,7 +289,7 @@ printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-pm-03-prd/SKILL.md"`);
 });
 
 for (const layout of ["flat", "nested"]) {
-  test(`local OpenCode reload refreshes only the selected plugin using ${layout} output`, () => {
+  test(`local OpenCode reload refreshes the framework namespace using ${layout} output`, () => {
     const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-local-"));
     try {
       const fakeBin = join(root, "bin");
@@ -301,7 +329,7 @@ mkdir -p "$out/.opencode/agents"
 ${buildDevAgents}`,
       );
 
-      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      const result = runSync(fakeBin, home, []);
       assert.equal(result.status, 0, result.stderr);
       const installed = join(home, ".config/opencode/skills", skillName);
       assert.match(readFileSync(join(installed, "SKILL.md"), "utf8"), /name: aidd-dev-01-plan/);
@@ -324,7 +352,7 @@ ${buildDevAgents}`,
   });
 }
 
-test("local OpenCode reload rejects missing selected skills before removing installed ones", () => {
+test("local OpenCode reload rejects missing framework skills before removing installed ones", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-missing-"));
   try {
     const fakeBin = join(root, "bin");
@@ -336,7 +364,7 @@ test("local OpenCode reload rejects missing selected skills before removing inst
     executable(join(fakeBin, "opencode"), "exit 0");
     executable(join(fakeBin, "npx"), "exit 0");
 
-    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    const result = runSync(fakeBin, home, []);
     assert.notEqual(result.status, 0);
     assert.match(result.stderr, /no built OpenCode skill for aidd-dev-01-plan/);
     assert.doesNotMatch(result.stdout, /skills:ok/);
@@ -372,7 +400,7 @@ printf '%s\n' 'new skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
 mkdir -p "$out/.opencode/agents"
 ${remainingAgents}`);
 
-    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    const result = runSync(fakeBin, home, []);
     assert.notEqual(result.status, 0);
     assert.match(result.stderr, /no built OpenCode agent for aidd-dev-/);
     assert.doesNotMatch(result.stdout, /skills:ok|agents:ok/);
@@ -390,6 +418,7 @@ test("default OpenCode reload installs every plugin's skills and agents", () =>
     const home = join(root, "home");
     mkdirSync(fakeBin);
     mkdirSync(home);
+    fixture(home, ["aidd-dev", "aidd-pm"]);
     const skills = ["aidd-dev-01-plan", "aidd-pm-03-prd"];
     const agents = devAgents.map((name) => `aidd-dev-${name}`);
     const buildSkills = skills.map((name) => `mkdir -p "$out/.opencode/skills/${name}"\nprintf '%s\\n' 'skill' > "$out/.opencode/skills/${name}/SKILL.md"`).join("\n");
@@ -442,7 +471,7 @@ mkdir -p "$out/.opencode/skills/aidd-dev-01-plan" "$out/.opencode/agents"
 printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
 ${buildDevAgents}
 ${badOutput === "empty" ? 'mkdir -p "$out/.opencode/skills/aidd-dev-02-implement"; touch "$out/.opencode/skills/aidd-dev-02-implement/SKILL.md"' : ""}`);
-      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      const result = runSync(fakeBin, home, []);
       assert.notEqual(result.status, 0);
       assert.match(result.stderr, /no built OpenCode skill for aidd-dev-02-implement/);
       assert.equal(readFileSync(join(installed, "SKILL.md"), "utf8"), "keep\n");
@@ -453,7 +482,7 @@ ${badOutput === "empty" ? 'mkdir -p "$out/.opencode/skills/aidd-dev-02-implement
   });
 }
 
-for (const host of ["opencode", "codex"]) {
+for (const host of ["opencode", "codex", "copilot", "cursor"]) {
   test(`reload fails when the installed ${host} host's build fails`, () => {
     const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-build-failed-"));
     try {
@@ -462,7 +491,7 @@ for (const host of ["opencode", "codex"]) {
       mkdirSync(fakeBin);
       executable(join(fakeBin, host), "exit 0");
       executable(join(fakeBin, "npx"), "exit 7");
-      const result = runSync(fakeBin, home, ["aidd-dev"]);
+      const result = runSync(fakeBin, home, []);
       assert.notEqual(result.status, 0);
       assert.match(result.stderr, new RegExp(`${host} build failed`));
       assert.doesNotMatch(result.stdout, /Done\./);
@@ -472,16 +501,17 @@ for (const host of ["opencode", "codex"]) {
   });
 }
 
-for (const host of ["codex", "claude"]) {
+for (const host of ["codex", "claude", "copilot"]) {
   test(`reload fails when the installed ${host} host rejects a plugin`, () => {
     const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-install-failed-"));
     try {
       const fakeBin = join(root, "bin");
       const home = join(root, "home");
       mkdirSync(fakeBin);
-      executable(join(fakeBin, host), `if [ "$1" = plugin ] && [ "$2" = ${host === "codex" ? "add" : "install"} ]; then exit 8; fi\nexit 0`);
-      executable(join(fakeBin, "npx"), "exit 0");
-      const result = runSync(fakeBin, home, ["aidd-pm"]);
+      fixture(home, ["aidd-pm"]);
+      executable(join(fakeBin, host), `if [ "$1 $2" = 'plugin marketplace' ] && [ "$3" = list ]; then echo '[]'; fi\nif [ "$1" = plugin ] && [ "$2" = ${host === "codex" ? "add" : "install"} ]; then exit 8; fi\nexit 0`);
+      executable(join(fakeBin, "npx"), host === "copilot" ? nativeBuildStub() : "exit 0");
+      const result = runSync(fakeBin, home, []);
       assert.notEqual(result.status, 0);
       assert.match(result.stderr, /plugin install failed for aidd-pm/);
       assert.doesNotMatch(result.stdout, /Done\./);
@@ -501,7 +531,7 @@ test("Codex reload rejects missing built agents before replacing the previous ca
     writeFileSync(cached, "old cached agent\n");
     executable(join(fakeBin, "codex"), "exit 0");
     executable(join(fakeBin, "npx"), "exit 0");
-    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    const result = runSync(fakeBin, home, []);
     assert.notEqual(result.status, 0);
     assert.match(result.stderr, /no built Codex agent/);
     assert.equal(readFileSync(cached, "utf8"), "old cached agent\n");
@@ -533,7 +563,7 @@ mkdir -p "$out/plugins/aidd-dev/codex-agents"
 for role in reviewer executor; do
   printf 'name = "%s"\ndescription = "New role"\n' "$role" > "$out/plugins/aidd-dev/codex-agents/$role.toml"
 done`);
-    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    const result = runSync(fakeBin, home, []);
     assert.equal(result.status, 0, result.stderr);
     assert.equal(existsSync(join(agents, "checker.toml")), false);
     assert.equal(readFileSync(join(agents, "reviewer.toml"), "utf8"), "personal reviewer\n");
@@ -541,3 +571,321 @@ done`);
     assert.match(readFileSync(join(agents, "aidd-dev-executor.toml"), "utf8"), /^name = "aidd-dev-executor"/);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+function nativeBuildStub(omitAgent = false) {
+  return String.raw`out=""; tool=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in --out) shift; out=$1 ;; --to) shift; tool=$1 ;; esac
+  shift
+done
+for source in "$FW/plugins/"*/; do
+  plugin="$(basename "$source")"
+  target="$out/plugins/$plugin"
+  manifest=".$tool-plugin"
+  [ "$tool" != copilot ] || manifest=".plugin"
+  mkdir -p "$target/$manifest" "$target/skills"
+  printf '{"name":"%s"}\n' "$plugin" > "$target/$manifest/plugin.json"
+  cp -R "$FW/plugins/$plugin/skills/." "$target/skills/"
+done
+mkdir -p "$out/plugins/aidd-dev/agents"
+${omitAgent ? "" : 'for role in checker executor; do name="$role"; [ "$tool" != cursor ] || name="aidd-dev-$role"; printf \'%s\\n\' \'---\' "name: $name" \'---\' \'Native role\' > "$out/plugins/aidd-dev/agents/$role.md"; done'}`;
+}
+
+for (const binary of ["cursor-agent", "agent", "cursor"]) {
+  test(`Cursor reload through ${binary} installs every built plugin and preserves personal content`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-cursor-"));
+    try {
+      const fakeBin = join(root, "bin"), home = join(root, "home");
+      mkdirSync(fakeBin);
+      fixture(home, ["aidd-dev", "aidd-pm"]);
+      const personal = [".cursor/agents/executor.md", ".cursor/rules/personal.mdc", ".cursor/mcp.json", ".cursor/plugins/local/personal/notes.md"];
+      for (const file of personal) {
+        mkdirSync(dirname(join(home, file)), { recursive: true });
+        writeFileSync(join(home, file), "personal bytes\n");
+      }
+      const stale = join(home, ".cursor/plugins/local/aidd-dev/agents/removed.md");
+      mkdirSync(dirname(stale), { recursive: true });
+      writeFileSync(stale, "retired role\n");
+      executable(join(fakeBin, binary), "echo 'Start the Cursor Agent'");
+      executable(join(fakeBin, "npx"), nativeBuildStub());
+      const result = runSync(fakeBin, home, []);
+      assert.equal(result.status, 0, result.stderr);
+      for (const [plugin, skill] of [["aidd-dev", "01-plan"], ["aidd-pm", "03-prd"]]) {
+        assert.equal(readFileSync(join(home, `.cursor/plugins/local/${plugin}/skills/${skill}/SKILL.md`), "utf8"), "source skill\n");
+      }
+      assert.match(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8"), /name: aidd-dev-executor/);
+      assert.match(readFileSync(join(home, ".cursor/rules/aidd-agents.mdc"), "utf8"), /\| @aidd-dev-executor \|/);
+      assert.equal(existsSync(stale), false);
+      for (const file of personal) assert.equal(readFileSync(join(home, file), "utf8"), "personal bytes\n");
+      const first = readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8");
+      assert.equal(runSync(fakeBin, home, []).status, 0);
+      assert.equal(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8"), first);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+}
+
+test("Cursor reload rejects incomplete native output before changing installed plugins", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-cursor-incomplete-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    const installed = join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md");
+    mkdirSync(dirname(installed), { recursive: true });
+    writeFileSync(installed, "old role\n");
+    executable(join(fakeBin, "cursor-agent"), "exit 0");
+    executable(join(fakeBin, "npx"), nativeBuildStub(true));
+    const result = runSync(fakeBin, home, []);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /no built cursor agent/);
+    assert.equal(readFileSync(installed, "utf8"), "old role\n");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("another tool named agent does not trigger Cursor installation", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-other-agent-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "agent"), "echo 'Grok Build TUI'");
+    executable(join(fakeBin, "npx"), "exit 9");
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(existsSync(join(home, "build/cursor")), false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+const copilotStub = String.raw`printf '%s\n' "$*" >> "$HOME/copilot-calls"
+case "$1 $2 $3" in
+  'plugin marketplace list')
+    if [ -f "$HOME/copilot-source" ]; then
+      printf '[{"name":"aidd-framework","source":"Local: %s"}]\n' "$(cat "$HOME/copilot-source")"
+    else echo '[]'; fi ;;
+  'plugin marketplace add')
+    if [ -f "$HOME/copilot-source" ]; then echo 'Marketplace "aidd-framework" already registered' >&2; exit 1; fi
+    printf '%s' "$4" > "$HOME/copilot-source" ;;
+  'plugin marketplace remove') rm "$HOME/copilot-source" ;;
+  'plugin marketplace update') : ;;
+esac`;
+
+test("Copilot reload builds all native plugins, migrates its own source, and preserves personal files", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin); mkdirSync(home);
+    const source = fixture(home, ["aidd-dev", "aidd-pm"]);
+    writeFileSync(join(home, "copilot-source"), source);
+    const personal = [".copilot/agents/executor.agent.md", ".copilot/instructions/personal.instructions.md", ".copilot/settings.json"];
+    for (const file of personal) {
+      mkdirSync(dirname(join(home, file)), { recursive: true });
+      writeFileSync(join(home, file), "personal bytes\n");
+    }
+    executable(join(fakeBin, "copilot"), copilotStub);
+    executable(join(fakeBin, "npx"), nativeBuildStub());
+    const first = runSync(fakeBin, home, []);
+    assert.equal(first.status, 0, first.stderr);
+    assert.equal(readFileSync(join(home, "copilot-source"), "utf8"), join(home, "build/copilot"));
+    for (const plugin of ["aidd-dev", "aidd-pm"]) {
+      assert.match(readFileSync(join(home, "copilot-calls"), "utf8"), new RegExp(`plugin install ${plugin}@aidd-framework`));
+      assert.equal(JSON.parse(readFileSync(join(home, `build/copilot/plugins/${plugin}/.plugin/plugin.json`), "utf8")).name, plugin);
+    }
+    assert.match(readFileSync(join(home, ".copilot/copilot-instructions.md"), "utf8"), /@aidd-dev:executor/);
+    assert.equal(runSync(fakeBin, home, []).status, 0);
+    assert.match(readFileSync(join(home, "copilot-calls"), "utf8"), /marketplace update aidd-framework/);
+    for (const file of personal) assert.equal(readFileSync(join(home, file), "utf8"), "personal bytes\n");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Copilot refuses another source registered under the same marketplace name", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-foreign-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin); mkdirSync(home);
+    writeFileSync(join(home, "copilot-source"), "/another/framework");
+    executable(join(fakeBin, "copilot"), copilotStub);
+    executable(join(fakeBin, "npx"), nativeBuildStub());
+    const result = runSync(fakeBin, home, []);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /different Copilot marketplace source/);
+    assert.equal(readFileSync(join(home, "copilot-source"), "utf8"), "/another/framework");
+    assert.doesNotMatch(readFileSync(join(home, "copilot-calls"), "utf8"), /marketplace remove|plugin install/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Copilot rejects incomplete native output before registering or installing", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-incomplete-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "copilot"), copilotStub);
+    executable(join(fakeBin, "npx"), nativeBuildStub(true));
+    const result = runSync(fakeBin, home, []);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /no built copilot agent/);
+    assert.equal(existsSync(join(home, "copilot-calls")), false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Copilot registers an inherited own marketplace without trying to remove it", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-inherited-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "copilot"), String.raw`printf '%s\n' "$*" >> "$HOME/copilot-calls"
+case "$1 $2 $3" in
+  'plugin marketplace list') printf '[{"name":"aidd-framework","source":"Local: %s"}]\n' "$FW" ;;
+  'plugin marketplace remove') echo 'Marketplace "aidd-framework" is not registered' >&2; exit 1 ;;
+  'plugin marketplace add') printf '%s' "$4" > "$HOME/copilot-source" ;;
+esac`);
+    executable(join(fakeBin, "npx"), nativeBuildStub());
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(readFileSync(join(home, "copilot-source"), "utf8"), join(home, "build/copilot"));
+    assert.doesNotMatch(readFileSync(join(home, "copilot-calls"), "utf8"), /marketplace remove/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+for (const command of ["add", "update", "install"]) {
+  test(`Copilot ${command} failure retains the native cause`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-cause-"));
+    try {
+      const fakeBin = join(root, "bin"), home = join(root, "home");
+      mkdirSync(fakeBin);
+      executable(join(fakeBin, "copilot"), String.raw`case "$1 $2 $3" in
+  'plugin marketplace list') ${command === "update" ? 'printf \'[{"name":"aidd-framework","source":"Local: %s"}]\\n\' "$BUILD/copilot"' : "echo '[]'"} ;;
+  'plugin marketplace ${command}'${command === "install" ? "|\'plugin install aidd-dev@aidd-framework\'" : ""}) echo 'fixture native permission denied' >&2; exit 9 ;;
+esac`);
+      executable(join(fakeBin, "npx"), nativeBuildStub());
+      const result = runSync(fakeBin, home, []);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, /fixture native permission denied/);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+}
+
+test("reload rejects plugin selection arguments before changing any host", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-no-filter-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    const result = runSync(fakeBin, home, ["aidd-dev"]);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /every plugin/);
+    assert.equal(existsSync(join(home, "build")), false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("reload uses the checkout's built CLI instead of a published translator", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-local-cli-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    const source = fixture(home), binary = join(source, "cli/dist/cli.js");
+    mkdirSync(dirname(binary), { recursive: true });
+    writeFileSync(binary, String.raw`const fs = require("node:fs"), path = require("node:path");
+const args = process.argv.slice(2);
+if (args[0] !== "translate") process.exit(2);
+const out = args[args.indexOf("--out") + 1];
+const source = args[1];
+for (const plugin of fs.readdirSync(path.join(source, "plugins"))) {
+  const target = path.join(out, "plugins", plugin);
+  fs.mkdirSync(path.join(target, ".cursor-plugin"), { recursive: true });
+  fs.writeFileSync(path.join(target, ".cursor-plugin/plugin.json"), JSON.stringify({ name: plugin }));
+  fs.cpSync(path.join(source, "plugins", plugin, "skills"), path.join(target, "skills"), { recursive: true });
+  fs.mkdirSync(path.join(target, "agents"));
+  for (const file of fs.readdirSync(path.join(source, "plugins", plugin, "agents"))) {
+    fs.writeFileSync(path.join(target, "agents", file), "---\nname: " + plugin + "-" + file.slice(0, -3) + "\n---\nLocal translation\n");
+  }
+}`);
+    executable(join(fakeBin, "cursor-agent"), "echo 'Start the Cursor Agent'");
+    executable(join(fakeBin, "npx"), "exit 19");
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8"), /name: aidd-dev-executor[\s\S]*Local translation/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Copilot instructions follow its native home with task overrides taking precedence", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-home-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home"), nativeHome = join(home, "native-copilot");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "copilot"), copilotStub);
+    executable(join(fakeBin, "npx"), nativeBuildStub());
+    const result = runSync(fakeBin, home, [], { COPILOT_HOME: nativeHome, COPILOT_INSTRUCTIONS: "" });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(readFileSync(join(nativeHome, "copilot-instructions.md"), "utf8"), /@aidd-dev:executor/);
+    assert.equal(existsSync(join(home, ".copilot/copilot-instructions.md")), false);
+    assert.equal(runSync(fakeBin, home, [], { COPILOT_HOME: nativeHome }).status, 0);
+    assert.match(readFileSync(join(home, ".copilot/copilot-instructions.md"), "utf8"), /@aidd-dev:executor/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("OpenCode skills and agents follow its native home with task overrides taking precedence", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-opencode-home-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home"), config = join(home, "native-config");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "opencode"), "exit 0");
+    executable(join(fakeBin, "npx"), String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = --out ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/.opencode/skills/aidd-dev-01-plan" "$out/.opencode/agents"
+printf '%s\n' 'native skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
+${buildDevAgents}`);
+    const result = runSync(fakeBin, home, [], { XDG_CONFIG_HOME: config, OPENCODE_SKILLS: "", OPENCODE_AGENTS: "", OPENCODE_INSTRUCTIONS: "" });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(readFileSync(join(config, "opencode/skills/aidd-dev-01-plan/SKILL.md"), "utf8"), "native skill\n");
+    assert.equal(readFileSync(join(config, "opencode/agents/aidd-dev-executor.md"), "utf8"), "updated agent\n");
+    assert.equal(existsSync(join(home, ".config/opencode/skills")), false);
+    assert.equal(runSync(fakeBin, home, [], { XDG_CONFIG_HOME: config }).status, 0);
+    assert.equal(readFileSync(join(home, ".config/opencode/skills/aidd-dev-01-plan/SKILL.md"), "utf8"), "native skill\n");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Codex agents and legacy cache migration follow its native home", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-home-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home"), nativeHome = join(home, "native-codex");
+    mkdirSync(fakeBin);
+    const cached = join(nativeHome, "plugins/cache/aidd-framework/aidd-dev/2.6.0/codex-agents/checker.toml");
+    const oldAgent = join(nativeHome, "agents/checker.toml"), legacy = 'name = "checker"\ndescription = "Legacy"\n';
+    for (const file of [cached, oldAgent]) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, legacy); }
+    executable(join(fakeBin, "codex"), "exit 0");
+    executable(join(fakeBin, "npx"), String.raw`out=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = --out ]; then shift; out=$1; fi
+  shift
+done
+mkdir -p "$out/plugins/aidd-dev/codex-agents"
+for role in checker executor; do printf 'name = "%s"\ndescription = "Native"\n' "$role" > "$out/plugins/aidd-dev/codex-agents/$role.toml"; done`);
+    const result = runSync(fakeBin, home, [], { CODEX_HOME: nativeHome, CODEX_CACHE: "", CODEX_AGENTS: "", CODEX_INSTRUCTIONS: "" });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(readFileSync(join(nativeHome, "agents/aidd-dev-executor.toml"), "utf8"), /^name = "aidd-dev-executor"/);
+    assert.equal(existsSync(oldAgent), false);
+    assert.equal(existsSync(join(home, ".codex/agents")), false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+for (const customPluginRoot of [false, true]) {
+  test(`Claude cache follows its native ${customPluginRoot ? "plugin root" : "config home"}`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-claude-home-"));
+    try {
+      const fakeBin = join(root, "bin"), home = join(root, "home"), config = join(home, "native-claude");
+      const plugins = customPluginRoot ? join(home, "native-plugins") : join(config, "plugins");
+      mkdirSync(fakeBin);
+      executable(join(fakeBin, "claude"), String.raw`if [ "$1 $2" = 'plugin install' ]; then
+  cache="$CLAUDE_CONFIG_DIR/plugins"
+  [ -z "$CLAUDE_CODE_PLUGIN_CACHE_DIR" ] || cache="$CLAUDE_CODE_PLUGIN_CACHE_DIR"
+  cache="$cache/cache/aidd-framework/aidd-dev/2.6.0"
+  mkdir -p "$cache/agents"
+fi`);
+      const result = runSync(fakeBin, home, [], { CLAUDE_CONFIG_DIR: config, CLAUDE_CODE_PLUGIN_CACHE_DIR: customPluginRoot ? plugins : "", CLAUDE_CACHE: "", CLAUDE_INSTRUCTIONS: "" });
+      assert.equal(result.status, 0, result.stderr);
+      assert.equal(readFileSync(join(plugins, "cache/aidd-framework/aidd-dev/2.6.0/agents/executor.md"), "utf8"), "source agent\n");
+      assert.match(readFileSync(join(config, "CLAUDE.md"), "utf8"), /@aidd-dev:executor/);
+      assert.equal(existsSync(join(home, ".claude/plugins")), false);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+}
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 582fefa69..98eb2935f 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# (Re)install every plugin into Claude, Codex and OpenCode from THIS checkout, named by
-# argument or `all`. Claude reads the raw repo, already native; Codex installs from a tree
+# (Re)install every plugin into Claude, Codex, OpenCode, Copilot and Cursor from THIS checkout.
+# Claude reads the raw repo, already native; Codex installs from a tree
 # the aidd CLI builds (agents -> TOML), so what runs locally matches what ships.
 #
 # NOT live: the install copies built files, so an edit needs a re-run. Idempotent; a tool
@@ -12,8 +12,8 @@
 # short names only when identical to the previous plugin cache; preserve personal agents.
 # Global rules: sync only the Agents section in the managed block, preserving personal
 # rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
-# Instruction paths honor CODEX_HOME, CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME; tests use
-# *_INSTRUCTIONS overrides. Sources checked 2026-10-14:
+# Paths honor native home/cache overrides; explicit task paths take precedence.
+# Sources checked 2026-10-14:
 # https://developers.openai.com/codex/guides/agents-md
 # https://code.claude.com/docs/en/memory
 # https://opencode.ai/docs/rules/
@@ -23,35 +23,60 @@
 # https://github.com/anomalyco/opencode/blob/v2.0.28/packages/core/src/config/plugin/agent.ts
 # V2.0.28 probe cwd must match PWD because run prefers PWD (read 2026-10-14):
 # https://github.com/anomalyco/opencode/blob/v2.0.28/packages/cli/src/run/run.ts
+# Cursor local plugins: real directories only; local imports must be allowed (read 2026-10-15).
+# https://cursor.com/docs/plugins#test-plugins-locally
+# Copilot native list/install verified with 1.0.5 and 1.0.98 (read 2026-10-15).
+# https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
+# Global rules: Copilot personal instructions; Cursor always-on .mdc rules (read 2026-10-15).
+# https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions
+# https://prod.cursor.com/help/customization/rules
 set -euo pipefail
 shopt -s nullglob
+if [ "$#" -gt 1 ] || { [ "$#" -eq 1 ] && [ "$1" != all ]; }; then
+  echo "Reload syncs every plugin; plugin selection arguments are unsupported." >&2; exit 1
+fi
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 FW="${FW:-$(dirname "$SCRIPT_DIR")}"
 MKT="${MKT:-aidd-framework}"
-AIDD_CLI_VERSION="${AIDD_CLI_VERSION:-latest}"  # override to pin if a release regresses the build
+AIDD_CLI_VERSION="${AIDD_CLI_VERSION:-latest}"  # published fallback for sources without a built CLI
 BUILD="${BUILD:-$HOME/.cache/aidd-framework-dev}"  # per-tool native trees the marketplaces point at
-CODEX_CACHE="${CODEX_CACHE:-$HOME/.codex/plugins/cache}"
-CLAUDE_CACHE="${CLAUDE_CACHE:-$HOME/.claude/plugins/cache}"
-CODEX_AGENTS="${CODEX_AGENTS:-$HOME/.codex/agents}"
-OPENCODE_SKILLS="${OPENCODE_SKILLS:-$HOME/.config/opencode/skills}"
-OPENCODE_AGENTS="${OPENCODE_AGENTS:-$HOME/.config/opencode/agents}"
+CODEX_CACHE="${CODEX_CACHE:-${CODEX_HOME:-$HOME/.codex}/plugins/cache}"
+CLAUDE_CACHE="${CLAUDE_CACHE:-${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/cache}"
+CODEX_AGENTS="${CODEX_AGENTS:-${CODEX_HOME:-$HOME/.codex}/agents}"
+OPENCODE_SKILLS="${OPENCODE_SKILLS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills}"
+OPENCODE_AGENTS="${OPENCODE_AGENTS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/agents}"
+CURSOR_PLUGINS="${CURSOR_PLUGINS:-$HOME/.cursor/plugins/local}"
 CODEX_INSTRUCTIONS="${CODEX_INSTRUCTIONS:-${CODEX_HOME:-$HOME/.codex}/AGENTS.md}"
 CLAUDE_INSTRUCTIONS="${CLAUDE_INSTRUCTIONS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md}"
 OPENCODE_INSTRUCTIONS="${OPENCODE_INSTRUCTIONS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md}"
+COPILOT_INSTRUCTIONS="${COPILOT_INSTRUCTIONS:-${COPILOT_HOME:-$HOME/.copilot}/copilot-instructions.md}"
+CURSOR_INSTRUCTIONS="${CURSOR_INSTRUCTIONS:-$HOME/.cursor/rules/aidd-agents.mdc}"
 
 HAVE_CODEX=0;  command -v codex  >/dev/null 2>&1 && HAVE_CODEX=1
 HAVE_CLAUDE=0; command -v claude >/dev/null 2>&1 && HAVE_CLAUDE=1
 HAVE_OPENCODE=0; command -v opencode >/dev/null 2>&1 && HAVE_OPENCODE=1
 HAVE_MANAGED_OPENCODE=0; command -v aidd-opencode-reload >/dev/null 2>&1 && HAVE_MANAGED_OPENCODE=1
+HAVE_COPILOT=0; command -v copilot >/dev/null 2>&1 && HAVE_COPILOT=1
+HAVE_CURSOR=0
+if command -v cursor >/dev/null 2>&1 || command -v cursor-agent >/dev/null 2>&1; then
+  HAVE_CURSOR=1
+elif command -v agent >/dev/null 2>&1 && agent --help 2>/dev/null | grep 'Start the Cursor Agent' >/dev/null; then
+  HAVE_CURSOR=1
+fi
 
 build_tool() {
   local tool="$1"
   rm -rf "$BUILD/$tool"; mkdir -p "$BUILD/$tool"
   local mode=marketplace
   [ "$tool" != opencode ] || mode=flat
-  npx --yes "@ai-driven-dev/cli@${AIDD_CLI_VERSION}" translate "$FW" \
-    --to "$tool" --out "$BUILD/$tool" --as "$mode" --force >/dev/null 2>&1
+  if [ -f "$FW/cli/dist/cli.js" ]; then
+    node "$FW/cli/dist/cli.js" translate "$FW" \
+      --to "$tool" --out "$BUILD/$tool" --as "$mode" --force >/dev/null 2>&1
+  else
+    npx --yes "@ai-driven-dev/cli@${AIDD_CLI_VERSION}" translate "$FW" \
+      --to "$tool" --out "$BUILD/$tool" --as "$mode" --force >/dev/null 2>&1
+  fi
 }
 
 validate_opencode_content() {
@@ -87,6 +112,25 @@ validate_codex_agents() {
   done
 }
 
+validate_native_plugins() {
+  local tool="$1" manifest="$2" name skill agent
+  for name in "${targets[@]}"; do
+    if [ ! -s "$BUILD/$tool/plugins/$name/$manifest" ]; then
+      echo "no built $tool manifest for $name" >&2; return 1
+    fi
+    for skill in "$FW/plugins/$name/skills/"*/SKILL.md; do
+      if [ ! -s "$BUILD/$tool/plugins/$name/skills/$(basename "$(dirname "$skill")")/SKILL.md" ]; then
+        echo "no built $tool skill for $name-$(basename "$(dirname "$skill")")" >&2; return 1
+      fi
+    done
+    for agent in "$FW/plugins/$name/agents/"*.md; do
+      if [ ! -s "$BUILD/$tool/plugins/$name/agents/$(basename "$agent")" ]; then
+        echo "no built $tool agent for $name-$(basename "$agent" .md)" >&2; return 1
+      fi
+    done
+  done
+}
+
 sync_opencode_skills() {
   # Accept nested and legacy flat builds; preserve personal and unselected plugin content.
   local name source skill destination
@@ -132,6 +176,32 @@ register_marketplace() {
     claude)
       claude plugin marketplace remove "$MKT" --scope user >/dev/null 2>&1 || true
       claude plugin marketplace add "$FW" --scope user >/dev/null 2>&1 ;;
+    copilot)
+      local registered_source
+      registered_source="$(copilot plugin marketplace list --json | node -e '
+        const entries = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
+        if (!Array.isArray(entries)) throw new Error("Invalid Copilot marketplace list");
+        const entry = entries.find(item => item.name === process.argv[1]);
+        if (entry && typeof entry.source !== "string") throw new Error("Invalid Copilot marketplace source");
+        process.stdout.write(entry?.source ?? "");
+      ' "$MKT")" || return 1
+      case "$registered_source" in
+        "") copilot plugin marketplace add "$BUILD/copilot" >/dev/null ;;
+        "Local: $BUILD/copilot") copilot plugin marketplace update "$MKT" >/dev/null ;;
+        "Local: $FW")
+          # Native list also includes inherited Claude registrations, which remove cannot change.
+          local add_result
+          if add_result="$(copilot plugin marketplace add "$BUILD/copilot" 2>&1)"; then
+            return 0
+          fi
+          case "$add_result" in
+            *"already registered"*)
+              copilot plugin marketplace remove "$MKT" --force >/dev/null || return 1
+              copilot plugin marketplace add "$BUILD/copilot" >/dev/null ;;
+            *) printf '%s\n' "$add_result" >&2; return 1 ;;
+          esac ;;
+        *) echo "Refusing a different Copilot marketplace source for $MKT: $registered_source" >&2; return 1 ;;
+      esac ;;
   esac
 }
 
@@ -189,19 +259,22 @@ sync_one() {
       return 1
     fi
   fi
+  if [ "$HAVE_COPILOT" = 1 ]; then
+    if copilot plugin install "$name@$MKT" >/dev/null; then
+      printf ' copilot:ok'
+    else
+      echo "Copilot plugin install failed for $name" >&2; return 1
+    fi
+  fi
   echo
 }
 
-if [ "$HAVE_CODEX" = 0 ] && [ "$HAVE_CLAUDE" = 0 ] && [ "$HAVE_OPENCODE" = 0 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
-  echo "No Claude, Codex, or OpenCode installation found - nothing to install."; exit 0
+if [ "$HAVE_CODEX" = 0 ] && [ "$HAVE_CLAUDE" = 0 ] && [ "$HAVE_OPENCODE" = 0 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ] && [ "$HAVE_COPILOT" = 0 ] && [ "$HAVE_CURSOR" = 0 ]; then
+  echo "No supported host installation found - nothing to install."; exit 0
 fi
 
 targets=()
-if [ $# -eq 0 ] || [ "${1:-}" = "all" ]; then
-  for d in "$FW"/plugins/*/; do targets+=("$(basename "$d")"); done
-else
-  targets=("$@")
-fi
+for d in "$FW"/plugins/*/; do targets+=("$(basename "$d")"); done
 
 # Codex needs a native build (md -> toml); register against it. Claude installs from the raw
 # repo (already native), so it only needs the marketplace registered - no build.
@@ -219,6 +292,19 @@ if [ "$HAVE_OPENCODE" = 1 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
   printf '%-22s' "build opencode"
   build_tool opencode && echo "ok" || { echo "FAIL"; echo "opencode build failed; rerun the translate command in scripts/dev-sync.sh without output redirection for details." >&2; exit 1; }
 fi
+if [ "$HAVE_CURSOR" = 1 ]; then
+  printf '%-22s' "build cursor"
+  build_tool cursor || { echo "FAIL"; echo "cursor build failed" >&2; exit 1; }
+  validate_native_plugins cursor .cursor-plugin/plugin.json || { echo "FAIL"; exit 1; }
+  echo "ok"
+fi
+if [ "$HAVE_COPILOT" = 1 ]; then
+  printf '%-22s' "build copilot"
+  build_tool copilot || { echo "FAIL"; echo "copilot build failed" >&2; exit 1; }
+  validate_native_plugins copilot .plugin/plugin.json || { echo "FAIL"; exit 1; }
+  register_marketplace copilot || { echo "FAIL"; echo "Copilot marketplace registration failed" >&2; exit 1; }
+  echo "ok"
+fi
 
 for t in "${targets[@]}"; do sync_one "$t"; done
 
@@ -233,6 +319,15 @@ if [ "$HAVE_MANAGED_OPENCODE" = 1 ]; then
   printf '%-22s' "reload opencode"
   aidd-opencode-reload
 fi
+if [ "$HAVE_CURSOR" = 1 ]; then
+  printf '%-22s' "install cursor"
+  mkdir -p "$CURSOR_PLUGINS"
+  for t in "${targets[@]}"; do
+    rm -rf -- "$CURSOR_PLUGINS/$t"
+    cp -R "$BUILD/cursor/plugins/$t" "$CURSOR_PLUGINS/$t"
+  done
+  echo "plugins:ok (requires local plugin imports)"
+fi
 
 instructions=()
 [ "$HAVE_CODEX" = 0 ] || instructions+=(codex "$CODEX_INSTRUCTIONS")
@@ -240,6 +335,8 @@ instructions=()
 if [ "$HAVE_OPENCODE" = 1 ] || [ "$HAVE_MANAGED_OPENCODE" = 1 ]; then
   instructions+=(opencode "$OPENCODE_INSTRUCTIONS")
 fi
+[ "$HAVE_COPILOT" = 0 ] || instructions+=(copilot "$COPILOT_INSTRUCTIONS")
+[ "$HAVE_CURSOR" = 0 ] || instructions+=(cursor "$CURSOR_INSTRUCTIONS")
 printf '%-22s' "global instructions"
 instruction_fallback="$CLAUDE_INSTRUCTIONS"
 case "${OPENCODE_DISABLE_CLAUDE_CODE:-}" in 1|true) instruction_fallback="" ;; esac
@@ -247,4 +344,4 @@ case "${OPENCODE_DISABLE_CLAUDE_CODE_PROMPT:-}" in 1|true) instruction_fallback=
 node "$SCRIPT_DIR/sync-global-instructions.cjs" "$FW/AGENTS.md" "$instruction_fallback" "${instructions[@]}"
 echo "ok (agents only)"
 
-echo "Done. Restart Claude/Codex; reload OpenCode configuration for refreshed agents, skills, and instructions."
+echo "Done. Restart hosts or reload their configuration for refreshed plugins and instructions."
diff --git a/scripts/sync-global-instructions.cjs b/scripts/sync-global-instructions.cjs
index 136507f0c..75c50fbab 100644
--- a/scripts/sync-global-instructions.cjs
+++ b/scripts/sync-global-instructions.cjs
@@ -12,6 +12,8 @@ function render(source, host) {
     codex: (role) => `@aidd-dev-${role}`,
     claude: (role) => `@aidd-dev:${role}`,
     opencode: (role) => `@aidd-dev-${role}`,
+    copilot: (role) => `@aidd-dev:${role}`,
+    cursor: (role) => `@aidd-dev-${role}`,
   };
   if (!names[host]) throw new Error(`Unknown instruction host: ${host}`);
   return source.slice(beginning, boundary < 0 ? undefined : boundary).trim().replace(
@@ -39,6 +41,7 @@ function sync(sourcePath, destinations, claudeFallback) {
   // Prepare every destination before writing any: a malformed block must not partially sync hosts.
   const updates = destinations.map(([host, path]) => {
     let existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (host === "cursor" && !existsSync(path)) existing = "---\nalwaysApply: true\n---\n";
     // Creating OpenCode's global file disables its Claude fallback. Keep those personal rules.
     if (host === "opencode" && !existsSync(path) && claudeFallback && existsSync(claudeFallback)) {
       existing = merge(readFileSync(claudeFallback, "utf8"), null);

From 2ebe5542863db324994b77f58499d8adeec1893c Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 13:45:29 +0800
Subject: [PATCH 18/73] refactor(aidd-dev): simplify scoped agent and phase
 handoffs

---
 docs/ARCHITECTURE.md                          |  4 ++--
 .../assets/agent-template.md                  |  6 +++---
 .../references/agent-authoring.md             |  2 +-
 plugins/aidd-dev/agents/validator.md          |  2 +-
 .../skills/01-plan/actions/02-explore.md      |  2 +-
 .../skills/02-implement/actions/02-execute.md |  6 +++---
 .../02-implement/actions/03-finalize.md       |  5 +++--
 .../skills/10-batch/actions/01-batch.md       |  8 +-------
 .../skills/01-sdlc/references/02-deliver.md   | 19 ++++++++-----------
 .../skills/01-sdlc/references/mode.md         |  1 +
 10 files changed, 24 insertions(+), 31 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a80e31f8a..ab6a2d761 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -109,7 +109,7 @@ flowchart TB
 | Skill | Host loads `SKILL.md` on invocation; work runs in the caller's context. |
 | Caller | Owns scope, delegation, integration, and acceptance. |
 | Orchestrator | Sequences capabilities on the caller's behalf. |
-| Agent | Isolates work and returns a result. Invokes declared recipe capabilities; reads supporting references while leaving recipe routing and delegation to the caller. |
+| Agent | Isolates a scoped task, invokes declared recipes, reads supporting references, and returns its result to the caller. |
 | Recipe | Primary callers may delegate bounded work; isolated recipes return to their caller. |
 | Reconnaissance helper | Read-only; neither mutates nor spawns. |
 | Write path | At most two delegation layers; no cycles. |
@@ -142,7 +142,7 @@ Queries and reports share one CLI implementation to avoid duplicated logic. CLI-
 | Context | Rule |
 | --- | --- |
 | Dispatch tables (`## Actions`), orchestration references and agent permissions (`# Skills you may invoke`) | Canonical `/plugin:folder` or `@plugin:agent` addresses. Elsewhere, name the responsibility. |
-| Cross-plugin providers | Discover by description; verify availability and role before dispatch. |
+| Cross-plugin providers | Recipes discover by description rather than hardcoding siblings; orchestrators verify installation before dispatch. |
 | Backlog flow | Owned by `aidd-orchestrator:02-backlog`. |
 | Orthogonality exceptions | `isExemptFromOrthogonality` permits responsibility maps in `plugins/aidd-orchestrator/**` and onboarding menus in `plugins/aidd-context/skills/00-onboard/**`. The onboarding exemption ends with runtime provider discovery. |
 
diff --git a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md
index 6af2328ce..de68b741b 100644
--- a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md
+++ b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md
@@ -9,13 +9,13 @@ description: <what it does + when to use>  # required, third person
 
 # Behavior
 
-<Required. The steps it follows, in order.>
+<Required. Concise capabilities and constraints within the role's responsibility.>
 
 <!-- Optional sections, add one only when it adds value, omit when empty:
 # Inputs:                what it receives when invoked
 # Outputs:               what it returns
-# Guardrails:            what it must never do
-# Skills you may invoke: a same-plugin skill by its plugin:folder address, a cross-plugin skill by capability
+# Guardrails:            behavioral boundaries
+# Skills you may invoke: allowed recipes by canonical /plugin:folder address; verify availability before invocation
 
 For an orchestration agent only: # Definition of Ready, # Definition of Done, # Decisions in scope, # Decisions out of scope, # Handoffs. See references/agent-authoring.md.
 -->
diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
index b6c6224ed..504d5d336 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
@@ -6,7 +6,7 @@ The contract every generated agent must satisfy. An agent is a focused role with
 
 - **R1.** One agent, one role. A single, clear responsibility.
 - **R2.** Frontmatter: `name` and `description` are required. `model` is optional. The description states what the agent does and when to use it.
-- **R3.** The body is the system prompt. Required: `# Role` and `# Behavior` (the steps). Optional sections: see `## Body shape`. Concise and imperative.
+- **R3.** The body is the system prompt. Required: `# Role` and `# Behavior` (bounded capabilities and constraints). Optional sections: see `## Body shape`. Concise and imperative.
 - **R4.** English only, regardless of conversation language.
 - **R5.** One idea per sentence. Split a sentence that runs past one line. Exceptions: table rows.
 
diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
index f19ab931a..dc54b0f34 100644
--- a/plugins/aidd-dev/agents/validator.md
+++ b/plugins/aidd-dev/agents/validator.md
@@ -16,7 +16,7 @@ Verify whether the requested outcome has been delivered.
 
 # Output
 
-Return one verdict and at most two short sentences for the assigned scope. Give decisive evidence for yes, or the failure or verification blocker for no; avoid a task-by-task report.
+Return one concise verdict for the assigned scope, with decisive evidence for yes or the failures and verification blockers for no; avoid a task-by-task report.
 
 ```markdown
 **Validated:** <yes | no>
diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index 1d758571f..8e9be4880 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -13,7 +13,7 @@ The architecture projection (files to modify, create, delete, each with a one-li
 ## Process
 
 1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions.
-   - The caller may delegate independent questions by codebase domain to explorers, each with a scope and requested findings. Combine their sourced answers; resolve contradictions or keep the uncertainty visible. Isolated explorers return directly.
+   - The caller may delegate independent questions by codebase domain to explorers, each with a scope and requested findings. Consult the exploration suggestion with `aidd delegation resolve exploration --tool <host> --json` before spawning. Combine their sourced answers; resolve contradictions or keep the uncertainty visible. Isolated explorers return directly.
 2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
 3. **Select.** Keep the project rules that apply to the projection.
 
diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index 7af7d0f74..b5f597867 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -12,9 +12,9 @@ Or a `blocked` / `replan needed` report.
 
 ## Process
 
-1. **Open.** Select assigned phases whose dependencies are done and integrated; use plan order when dependencies are undeclared.
-   - The caller may run independent phases in parallel with distinct checkouts/Git indexes, separate write ownership, and nonconflicting validation resources; otherwise run serially.
-   - Missing or contradictory dependencies, or unfinished work with no ready phase, require `replan needed`.
+1. **Open.** Select assigned phases whose dependencies are done and integrated; use serial plan order when dependencies are undeclared.
+   - The caller may run independent phases in parallel with separate write ownership and nonconflicting validation resources. Use separate checkouts/indexes when workers perform Git operations; otherwise the caller owns Git. Run serially when isolation is uncertain.
+   - A declared prerequisite with no matching phase, contradictory dependencies, or unfinished work with no ready phase requires `replan needed`.
    - Set the current phase `status: in-progress`.
    - In a feature folder, read `phase-<n>.md` beside `plan.md`.
 2. **Code.** Build the next task or inseparable group against its acceptance criteria.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
index 659107055..bbbb6eb11 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md
@@ -12,6 +12,7 @@ The validated plan marked `implemented`.
 
 1. **Verify.** Validate the source outcome and phase criteria together after integration, then run the plan's validation commands and tests.
    - Start the required runtime if needed.
+   - Run any required end-to-end journey last, before marking the plan implemented.
 2. **Mark.** Set the plan `status: implemented`.
    - Commit according to the commit policy.
 
@@ -20,7 +21,7 @@ The validated plan marked `implemented`.
 - Gate `implemented` on successful validation.
   - Require every phase `done`.
   - Require all validation commands and tests to pass.
+  - Require any final journey to pass on the verified implementation.
 - Repair validation failures before `implemented`.
-  - Rerun the affected workflow after a repair.
-  - Rerun the validation commands and tests.
+  - Rerun affected workflows, validation commands and tests, then any required final journey.
   - Follow Execute's validation, blocker and drift rules.
diff --git a/plugins/aidd-dev/skills/10-batch/actions/01-batch.md b/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
index 825f87026..13f85d67a 100644
--- a/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
+++ b/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
@@ -17,12 +17,7 @@ One row per dispatched agent, identified by its name or ID. Status is `Done` (ta
 
 1. **Read.** Take `prompt` from the arguments; if empty, ask the user.
 2. **Split.** Divide the prompt into distinct, independent tasks. Inline, no agent.
-3. **Launch.** Spawn one `executor` agent per task, all in parallel (one message, multiple Task calls). Track each agent's name or ID and assigned task. Each agent prompt mandates, in order:
-   ```markdown
-   1. Refine the task first: run a non-interactive refine capability if one is available (discovered at runtime, never a hardcoded plugin name); otherwise restate the task clearly and resolve obvious ambiguity inline. Never block on the user.
-   2. Implement the refined task.
-   3. Return a one-line summary with status, outcome, changed files, and validation evidence; if blocked or failed, include the reason and remaining work.
-   ```
+3. **Launch.** Resolve the implementation suggestion with `aidd delegation resolve implementation --tool <host> --json`, retaining native inheritance when unconfigured. Surface resolution errors; the caller owns any override. Spawn one scoped executor per task, all in parallel with fresh contexts. Supply each task's criteria, write ownership, checks, and commit policy. Track each agent's name or ID; require its outcome, changed files, validation evidence, and remaining work.
 4. **Collect.** Wait for every dispatched agent to finish or report a blocker. Preserve blocked and failed outcomes; mark an agent that exits with an error as `Failed` even if it returns no summary.
 5. **Report.** Print exactly one final table using the output columns, nothing else. Base each status and result on the collected evidence.
 
@@ -31,6 +26,5 @@ One row per dispatched agent, identified by its name or ID. Status is `Done` (ta
 - Every dispatched agent is one row in the table, including blocked or failed agents.
 - Each row identifies the agent and its assigned task, status, and result.
 - Agents were spawned in a single parallel batch.
-- Each agent ran a refine step before implementing.
 - The final table follows collection of all agents' outcomes; `Done` requires completion and validation evidence.
 - No output besides the table.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 872aac104..4d21e24a2 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,9 +2,9 @@
 
 ## Behavior
 
-Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For phase delegation, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, checkout, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
+Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
 
-The executor implements its scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Run an end-to-end journey after every other validation when the plan calls for one, and none otherwise. Finalize delegated phases together after integration and required validation.
+The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Whole-plan execution keeps its normal flow; phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
 
 Commit and push the validated work through the commit skill. Send only the clean committed candidate and its evidence to Check.
 
@@ -26,8 +26,7 @@ flowchart TD
     Implement["/aidd-dev:02-implement"]
     Assert["/aidd-dev:03-assert"]
     Integrate["Integrate phases"]
-    Test["/aidd-dev:06-test"]
-    Finalize["Finalize if phases were delegated"]
+    Finalize["Finalize integrated plan; /aidd-dev:06-test journey last when required"]
     Commit["/aidd-vcs:01-commit"]
   end
 
@@ -41,14 +40,12 @@ flowchart TD
   Plan --> PlanArtifact
   PlanArtifact -- "Whole plan, or ready independent phases." --> Executor
   Executor -- "Assigned plan or phase." --> Implement
-  Implement --> Assert
+  Implement -- "Whole plan finalized." --> Commit
+  Implement -- "Assigned phase returned." --> Assert
   Assert --> Integrate
   Integrate -- "More ready phases." --> Executor
-  Integrate -- "No required end-to-end journey." --> Finalize
-  Integrate -- "Run required end-to-end journey last." --> Test
-  Test -- "Journey passed." --> Finalize
-  Test -- "Return a failed journey for repair." --> Executor
-  Finalize -- "Acceptance failed; repair affected phase." --> Executor
+  Integrate --> Finalize
+  Finalize -- "Validation or journey failed; repair affected phase." --> Executor
   Finalize --> Commit
   Commit --> CommittedCandidate
   CommittedCandidate --> Check
@@ -58,7 +55,7 @@ flowchart TD
   classDef artifact fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px
   classDef zone fill:#F1F5F9,stroke:#64748B,color:#0F172A,stroke-width:2px
 
-  class Plan,Implement,Assert,Test,Commit skill
+  class Plan,Implement,Assert,Finalize,Commit skill
   class Executor agent
   class Contract,PlanArtifact,CommittedCandidate artifact
   class Check zone
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
index 716ac6fe7..94fecf4ae 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
@@ -6,6 +6,7 @@
 - A request carrying nothing else is not one to run: say so and stop.
 - Ask only before spending money, taking an irreversible action, or making a decision that requires user authority.
 - An exception stops the action it guards, not the rest of the request. Say what was withheld and what would release it.
+- Before spawning, run `aidd delegation resolve <task> --tool <host> --json` for `exploration`, `implementation`, `validation`, or `verification`. Use the returned native identity and settings as suggestions; explain material overrides. Missing settings inherit. Surface configuration errors or an unavailable resolver instead of claiming a suggestion was applied.
 
 ## Auto
 

From afb2fec901af261217826004dfb86fcab301218b Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 13:48:02 +0800
Subject: [PATCH 19/73] fix(framework): reject missing Claude reload
 destinations

---
 scripts/__tests__/dev-sync.test.js | 29 +++++++++++++++++++++++++++--
 scripts/dev-sync.sh                |  4 +++-
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 920018a83..cabed7856 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -1,6 +1,6 @@
 const assert = require("node:assert/strict");
 const { spawnSync } = require("node:child_process");
-const { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } = require("node:fs");
+const { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } = require("node:fs");
 const { tmpdir } = require("node:os");
 const { delimiter, dirname, join, resolve } = require("node:path");
 const test = require("node:test");
@@ -182,7 +182,7 @@ function runSync(fakeBin, home, args = ["all"], overrides = {}) {
   // Windows, where bash is the one Git for Windows ships. `spawnSync` resolves a bare name
   // through the platform's own rules on both.
   return spawnSync("bash", [join(repo, "scripts/dev-sync.sh"), ...args], {
-    cwd: repo,
+    cwd: home,
     env: {
       ...process.env,
       PATH: [fakeBin, BASE_PATH].join(delimiter),
@@ -208,6 +208,31 @@ function runSync(fakeBin, home, args = ["all"], overrides = {}) {
   });
 }
 
+test("reload fixtures run from their temporary home", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-cwd-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "aidd-opencode-reload"), 'pwd > "$HOME/observed-cwd"');
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(realpathSync(readFileSync(join(home, "observed-cwd"), "utf8").trim()), realpathSync(home));
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Claude reload rejects a missing native installation path without writing into cwd", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-claude-no-path-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    executable(join(fakeBin, "claude"), "exit 0");
+    const result = runSync(fakeBin, home, []);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /install path missing/);
+    assert.equal(existsSync(join(home, ".agents")), false);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
 test("managed OpenCode reload uses the fixed-purpose helper without a local build", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-managed-"));
   try {
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 98eb2935f..12468e5da 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -239,7 +239,9 @@ sync_one() {
       # the count, so a miss is never silent.
       if [ -d "$FW/plugins/$name/agents" ]; then
         local dest src n=0 fixed=0
-        dest="$(ls -d "$CLAUDE_CACHE/$MKT/$name"/*/ 2>/dev/null | head -1)"
+        local -a install_paths
+        install_paths=("$CLAUDE_CACHE/$MKT/$name"/*/)
+        dest="${install_paths[0]:-}"
         if [ -n "$dest" ]; then
           mkdir -p "${dest}agents"
           for src in "$FW/plugins/$name/agents/"*.md; do

From 6b5f5f580158495608466135589cb30a93c92adf Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 13:49:33 +0800
Subject: [PATCH 20/73] docs(aidd-dev): record native agent verification and
 cost comparison

---
 .../2026_10_14_sub_agents/comparison.json     |  72 ++++
 .../2026_10/2026_10_14_sub_agents/review.md   |  56 +++
 .../2026_10_14_sub_agents/runtime.json        | 353 ++++++++++++++++++
 .../2026_10_14_sub_agents/verification.md     |  41 ++
 4 files changed, 522 insertions(+)
 create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json
 create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
 create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json
new file mode 100644
index 000000000..4a5f3de01
--- /dev/null
+++ b/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."
+}
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
new file mode 100644
index 000000000..79564d4e9
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
@@ -0,0 +1,56 @@
+# Review: scoped sub-agents
+
+- Rounds: 3
+- 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).
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
new file mode 100644
index 000000000..b5a07c694
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
@@ -0,0 +1,353 @@
+{
+  "date": "2026-10-15",
+  "source_agent_sha256": {
+    "explorer": "735e8f34797b47acd1763cb0c84553974b82c4cf0601fbba0726c1fc5310b862",
+    "executor": "74b452270857e829d0aeacc0f5cc1385a18b07fb6205c5604051a9115fd2a2c7",
+    "validator": "9057daca0887fdb3ebbcbd64a4b2de1fe21827891cde7fd8575fac67d5e3e2c2",
+    "reviewer": "100772a0c72cd3bcd390db115abe738a1ad27e5112df5d81fe8ee2e4b83b4ba2"
+  },
+  "hosts": {
+    "claude": {
+      "version": "2.1.300",
+      "distribution": "flat, disposable projects",
+      "roles": [
+        "aidd-dev-explorer",
+        "aidd-dev-executor",
+        "aidd-dev-validator",
+        "aidd-dev-reviewer"
+      ],
+      "models_observed": [
+        "claude-opus-5-5",
+        "claude-haiku-5-5"
+      ],
+      "effort_requested": "low",
+      "effort_source": "Native Agent calls carry effort low; JSON modelUsage does not independently echo effective effort.",
+      "behavior": "Explorer cites exact source. Executor writes only eight assigned modules; independent checks pass. Validator accepts 5000 and rejects 5001 against the actual file. Reviewer identifies duplicated bodies."
+    },
+    "codex": {
+      "version": "0.145.0",
+      "distribution": "user flat agent",
+      "parent_thread": "01a13df8-fce3-71e2-b1c7-03579c9e56aa",
+      "turn_context": {
+        "model": "gpt-5.6-sol",
+        "effort": "low"
+      },
+      "limitation": "The signed-in backend rejected gpt-6-luna and gpt-6.1-sol. The successful probe used gpt-5.6-sol.",
+      "children": [
+        {
+          "thread": "01a13df9-1c68-7c03-ac4e-5fe6c7ffe6e5",
+          "role": "aidd-dev-explorer",
+          "model": "gpt-5.6-sol",
+          "effort": "low"
+        },
+        {
+          "thread": "01a13df9-4aab-7fa2-a021-90fd6b8bb4bf",
+          "role": "aidd-dev-executor",
+          "model": "gpt-5.6-sol",
+          "effort": "low"
+        },
+        {
+          "thread": "01a13df9-98ed-7df1-9a88-b005256c999f",
+          "role": "aidd-dev-validator",
+          "model": "gpt-5.6-sol",
+          "effort": "low"
+        },
+        {
+          "thread": "01a13df9-e4d0-79c0-8c8c-085cbfa4462a",
+          "role": "aidd-dev-reviewer",
+          "model": "gpt-5.6-sol",
+          "effort": "low"
+        }
+      ],
+      "behavior": "Four fresh native roles completed: actual source lookup, text implementation, rejection of false criterion, independent quality review. No file changes."
+    },
+    "opencode": {
+      "version": "2.0.28",
+      "distribution": "Generated project flat agents",
+      "invocation": "opencode run --standalone --auto --model 'openai/gpt-6.1-sol#medium' --format json <bounded-four-role-prompt>",
+      "session": "ses_ec1fdc64bffesN0k62QmtBd5yA",
+      "exit": 0,
+      "children": [
+        {
+          "session": "ses_ec1fdb057ffeurGEXTwfPaJV2I",
+          "role": "aidd-dev-explorer",
+          "model": {
+            "id": "gpt-6.1-sol",
+            "providerID": "openai",
+            "variant": "medium"
+          },
+          "finish": "stop"
+        },
+        {
+          "session": "ses_ec1fd8488ffeG3OHfopYCMwrD1",
+          "role": "aidd-dev-executor",
+          "model": {
+            "id": "gpt-6.1-sol",
+            "providerID": "openai",
+            "variant": "medium"
+          },
+          "finish": "stop"
+        },
+        {
+          "session": "ses_ec1fd501cffeNLHTFOGKmI8qA6",
+          "role": "aidd-dev-validator",
+          "model": {
+            "id": "gpt-6.1-sol",
+            "providerID": "openai",
+            "variant": "medium"
+          },
+          "finish": "stop"
+        },
+        {
+          "session": "ses_ec1fd1f7cffejVCvM1x5kW34Ep",
+          "role": "aidd-dev-reviewer",
+          "model": {
+            "id": "gpt-6.1-sol",
+            "providerID": "openai",
+            "variant": "medium"
+          },
+          "finish": "stop"
+        }
+      ],
+      "metadata_source": "GET /api/session/<child-session>/message through the native opencode api --standalone command",
+      "behavior": "Four fresh native roles completed: actual source lookup, text implementation, rejection of the false threshold 5001, and independent quality review. No file changes.",
+      "limitation": "Earlier Luna/low run recovered a provider transport timeout but returned CLI exit 1; it is not counted as a clean pass."
+    },
+    "copilot": {
+      "version": "1.0.98",
+      "distribution": "generated marketplace plugin, native --plugin-dir",
+      "roles": [
+        {
+          "agentName": "aidd-dev:explorer",
+          "model": "gpt-6-luna",
+          "firstDispatchedModel": "gpt-6-luna",
+          "modelSelectionSource": "session_inheritance",
+          "totalToolCalls": 0,
+          "totalTokens": 2214,
+          "durationMs": 23668
+        },
+        {
+          "agentName": "aidd-dev:executor",
+          "model": "gpt-6-luna",
+          "firstDispatchedModel": "gpt-6-luna",
+          "modelSelectionSource": "session_inheritance",
+          "totalToolCalls": 0,
+          "totalTokens": 2325,
+          "durationMs": 7324
+        },
+        {
+          "agentName": "aidd-dev:reviewer",
+          "model": "gpt-6-luna",
+          "firstDispatchedModel": "gpt-6-luna",
+          "modelSelectionSource": "session_inheritance",
+          "totalToolCalls": 0,
+          "totalTokens": 2335,
+          "durationMs": 7921
+        },
+        {
+          "agentName": "aidd-dev:validator",
+          "model": "gpt-6-luna",
+          "firstDispatchedModel": "gpt-6-luna",
+          "modelSelectionSource": "session_inheritance",
+          "totalToolCalls": 0,
+          "totalTokens": 2218,
+          "durationMs": 8514
+        }
+      ],
+      "explicit_override": {
+        "session_id": "8f84d0b3-105d-4f7e-afc5-49fa240f07db",
+        "agent_id": "78c9d4e7-bb5f-480f-bfba-d52e5284d75d",
+        "parent_tool_call_id": "call_Ye8vaSjxNF1gofK7fYv4IUht",
+        "model": "gpt-6-luna",
+        "reasoning_effort": "medium",
+        "reasoning_tokens": 11,
+        "input_tokens": 856,
+        "output_tokens": 22,
+        "created_at": "2026-10-15T04:03:03.366Z"
+      },
+      "limitation": "Native per-call model override verified. A requested low effort produced medium; the exact normalization or override cause is unverified."
+    },
+    "cursor": {
+      "version": "2026.10.14-941492e",
+      "distribution": "Real user plugins/local install; automatic discovery without --plugin-dir",
+      "roles": [
+        {
+          "name": "aidd-dev-explorer",
+          "model": "default",
+          "success": true,
+          "error": null,
+          "durationMs": "26299"
+        },
+        {
+          "name": "aidd-dev-executor",
+          "model": "default",
+          "success": true,
+          "error": null,
+          "durationMs": "6110"
+        },
+        {
+          "name": "aidd-dev-reviewer",
+          "model": "default",
+          "success": true,
+          "error": null,
+          "durationMs": "39048"
+        },
+        {
+          "name": "aidd-dev-validator",
+          "model": "default",
+          "success": true,
+          "error": null,
+          "durationMs": "8673"
+        }
+      ],
+      "read_tools": [
+        {
+          "role": "aidd-dev-explorer",
+          "tool": "Read",
+          "path": "/tmp/aidd-983-claude-flat/src/config.cjs"
+        },
+        {
+          "role": "aidd-dev-reviewer",
+          "tool": "Read",
+          "path": "/Users/alexsoyes/.cursor/plugins/local/aidd-dev/skills/05-review/SKILL.md"
+        },
+        {
+          "role": "aidd-dev-reviewer",
+          "tool": "Read",
+          "path": "/Users/alexsoyes/.cursor/plugins/local/aidd-dev/skills/05-review/references/quality-checklist.md"
+        },
+        {
+          "role": "aidd-dev-reviewer",
+          "tool": "Read",
+          "path": "/tmp/aidd-983-claude-flat/src/config.cjs"
+        },
+        {
+          "role": "aidd-dev-reviewer",
+          "tool": "Read",
+          "path": "/tmp/aidd-983-aidd-roles/workspace/sample.js"
+        },
+        {
+          "role": "aidd-dev-reviewer",
+          "tool": "Read",
+          "path": "/Users/alexsoyes/.cursor/plugins/local/aidd-dev/skills/05-review/references/prepare.md"
+        },
+        {
+          "role": "aidd-dev-validator",
+          "tool": "Read",
+          "path": "/tmp/aidd-983-claude-flat/src/config.cjs"
+        }
+      ],
+      "actual_backend_model": "unverified under Auto",
+      "actual_effort": "unverified",
+      "limitation": "Auto/inheritance verified. Named model rejected by Free plan; backend identity and effort not exposed by these traces.",
+      "installation": "Current official CLI ran from an isolated download. The globally installed older Cursor CLI was not upgraded."
+    }
+  },
+  "reload": {
+    "plugins": 9,
+    "hosts": [
+      "claude",
+      "codex",
+      "opencode",
+      "copilot",
+      "cursor"
+    ],
+    "exit": 0,
+    "personal_agents_preserved": 28,
+    "personal_instruction_files_preserved": 3,
+    "global_block": "agent table only"
+  },
+  "whole_plan_finalization": {
+    "host": "Claude Code 2.1.300",
+    "model": "claude-haiku-5-5",
+    "native_skill": "aidd-dev:02-implement",
+    "session": "26945ad0-9d47-4b4e-89d8-ae53d27ded2a",
+    "source_outcome": "module.exports = { answer: 42 };",
+    "events": [
+      "check",
+      "journey"
+    ],
+    "plan_implemented": true,
+    "phase_done": true,
+    "journey_before_mark": "Native Bash journey call precedes final plan Edit; no subsequent validation command.",
+    "git_operations": "No commits or pushes; baseline branch preserved.",
+    "scope": "Disposable project. Guard rejects checks after the final journey; journey rejects an already implemented plan."
+  },
+  "resolver": {
+    "config_unchanged": true,
+    "five_hosts": [
+      {
+        "host": "claude",
+        "agent": "aidd-dev:explorer",
+        "mode": "marketplace",
+        "requested": {
+          "model": "haiku",
+          "effort": "low"
+        },
+        "native": {
+          "model": "haiku",
+          "effort": "low"
+        },
+        "nativeSurface": "agent-configuration",
+        "effectiveRuntime": "unknown",
+        "missing_task_inherits": true
+      },
+      {
+        "host": "codex",
+        "agent": "aidd-dev-explorer",
+        "mode": "flat",
+        "requested": {
+          "model": "gpt-5.6-sol",
+          "effort": "low"
+        },
+        "native": {
+          "model": "gpt-5.6-sol",
+          "model_reasoning_effort": "low"
+        },
+        "nativeSurface": "agent-configuration",
+        "effectiveRuntime": "unknown",
+        "missing_task_inherits": true
+      },
+      {
+        "host": "opencode",
+        "agent": "aidd-dev-explorer",
+        "mode": "flat",
+        "requested": {
+          "model": "openai/gpt-6.1-sol",
+          "effort": "medium"
+        },
+        "native": {
+          "model": "openai/gpt-6.1-sol#medium"
+        },
+        "nativeSurface": "agent-configuration",
+        "effectiveRuntime": "unknown",
+        "missing_task_inherits": true
+      },
+      {
+        "host": "copilot",
+        "agent": "aidd-dev:explorer",
+        "mode": "marketplace",
+        "requested": {
+          "model": "gpt-6-luna"
+        },
+        "native": {
+          "model": "gpt-6-luna"
+        },
+        "nativeSurface": "agent-configuration",
+        "effectiveRuntime": "unknown",
+        "missing_task_inherits": true
+      },
+      {
+        "host": "cursor",
+        "agent": "aidd-dev-explorer",
+        "mode": "marketplace",
+        "requested": {},
+        "native": {},
+        "nativeSurface": "spawn",
+        "effectiveRuntime": "unknown",
+        "missing_task_inherits": true
+      }
+    ],
+    "unsupported_cursor_effort": "Error: Cursor plugin spawn does not accept effort; choose an advertised model slug or omit effort to inherit."
+  }
+}
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 02c37dd52..e73f15e77 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -49,3 +49,44 @@ The large-project planning and review controllers exceeded their imposed time li
 OpenCode's configured local model server was unavailable. Its behavioral probe used the already authenticated `openai/gpt-6.1-sol` through an invocation-only override, with matching `cwd` and `PWD`. Global model and authentication settings were unchanged. Versioned discovery and directory behavior sources are recorded in deployment memory.
 
 The wrapped scripts suite passed 559 tests, including 12 reload regressions. Architecture, JSON manifest validation, Markdown links, duplication checks, and commit hooks passed. These results establish the observed contracts and host paths; they do not guarantee every future task or model choice.
+
+## Current candidate, 2026-10-15
+
+The earlier results above describe the previous checker contract. Current probes use the four scoped roles: explorer, executor, validator and reviewer. Validator returns one completion verdict; reviewer independently assesses quality. Native dispatch events establish invocation; generated files and agent self-reports alone do not.
+
+| Host | Tested version | Delivery and observed runtime |
+| --- | --- | --- |
+| Claude Code | 2.1.300 | Generated flat agents. Opus parent and Haiku children resolve to `claude-opus-5-5` / `claude-haiku-5-5`. Native calls request `low`; effective effort is not independently echoed. |
+| Codex | 0.145.0 | Installed user agents. Four fresh children report `gpt-5.6-sol` / `low` in native turn contexts. Signed-in backend rejects the suggested newer models. |
+| OpenCode | 2.0.28 | Generated project agents. Four native child message records identify their roles and `openai/gpt-6.1-sol#medium`; controller exits 0. An earlier Luna probe had a transport error and is excluded from clean passes. |
+| GitHub Copilot | 1.0.98 | Generated marketplace agents invoked through native `--plugin-dir`. Four roles run. Explicit child model `gpt-6-luna` works; actual effort remains `medium` despite requesting low. |
+| Cursor | 2026.10.14-941492e | Current official CLI in an isolated download; automatic discovery of four real global local-plugin agents, without `--plugin-dir`. Auto succeeds; the Free account rejects named models. Backend model and effort remain unverified. |
+
+The bounded scenarios cover sourced exploration, implementation output, rejection of a false completion criterion, and independent quality review. Claude's executor changes only the eight assigned modules and passes independent checks. Other four-role probes use text implementation; their files remain unchanged. Cursor's explorer and validator read the actual threshold file; its reviewer also reads the installed quality checklist. Filtered session identities, source hashes, native model metadata and limitations are retained in [runtime.json](runtime.json).
+
+### Direct versus delegated
+
+Same synthetic exploration and repetitive implementation tasks, once per mode. The delegated run includes its Opus parent and fresh Haiku child. Tokens include input, output, cache reads and cache writes; costs are native list-price estimates, not subscription charges.
+
+| Task | Mode | Total tokens | Wall time | Cost estimate, USD |
+| --- | --- | ---: | ---: | ---: |
+| Exploration | Direct | 136,486 | 26.0 s | 0.2386 |
+| Exploration | Delegated | 183,951 | 30.0 s | 0.2130 |
+| Implementation | Direct | 136,126 | 21.1 s | 0.2081 |
+| Implementation | Delegated | 188,423 | 29.4 s | 0.1899 |
+
+Both retained modes return correct source findings and pass the same independent implementation checks, with no task retries. An earlier implementation pair could not run checks under its Bash permission pattern; both modes were rerun with equal permissions. That excluded attempt is recorded in [comparison.json](comparison.json), alongside quality checks. Separate token-category counts were not retained after fixture cleanup. Different cache states and one observation per mode prevent a general savings claim. Delegation was slower here, with a lower reported cost estimate.
+
+### Reload and finalization
+
+`make reload` exits 0 and refreshes all nine plugins for Claude, Codex, OpenCode, Copilot and Cursor. Native Copilot lists all nine AIDD plugins; Cursor discovers the installed global roles. Byte hashes confirm preservation of 28 personal agent files and personal content in three pre-existing instruction files. Managed global instructions contain only the agent table. Cursor still requires its native Local Plugin Imports policy.
+
+A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the assigned value, runs the mandatory check, then runs the final journey and marks the phase and plan complete. Native tool chronology and the fixture's event ledger show `check` then `journey`, followed by the plan update and no further validation command. The fixture rejects checks after the journey and rejects a journey after premature completion. No commits or pushes occur in that probe.
+
+### Final checks
+
+- **CLI:** 543 test files passed, one skipped; 7,106 tests passed, one skipped. Architecture, typecheck, lint, type honesty, unused-code and duplication gates pass. Lint retains one pre-existing unused-private-field warning. Bundle is 567.8 KB against the unchanged 756 KB budget.
+- **Scripts:** the wrapped full suite passes 729 tests. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
+- **Integration:** the real resolver finds installed agents on all five hosts, preserves project configuration bytes, leaves missing tasks inherited, and rejects unsupported Cursor plugin effort. Actual `make reload` exits 0 after the final corrections; the personal-file preservation check still passes.
+- **Guards:** removing the unknown-field rejection and bypassing Claude activation each causes the targeted test to fail. Exact source bytes were restored and the named tests pass; no full mutation-score claim is made.
+- **Scope:** gather, wireframe, the challenge skill and generic skill generation have no diff against `next`. Generic generation work remains in PR #1028.

From 41942135f8f89ee1e9c73111ecf705182c8fdf64 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 14:12:22 +0800
Subject: [PATCH 21/73] test(framework): align native smoke and Windows reload
 fixtures

---
 cli/scripts/smoke-tools.sh             | 17 ++++++++++++-
 cli/tests/e2e/kilo-runtime.e2e.test.ts |  5 ++--
 scripts/__tests__/dev-sync.test.js     | 33 +++++++++++++++++++++-----
 3 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/cli/scripts/smoke-tools.sh b/cli/scripts/smoke-tools.sh
index c31b400fd..075e74c40 100755
--- a/cli/scripts/smoke-tools.sh
+++ b/cli/scripts/smoke-tools.sh
@@ -25,6 +25,7 @@ ALL_COMMANDS=(
   "setup" "doctor" "sync" "translate" "update" "clean"
   "framework install" "framework update" "framework remove" "framework rules"
   "framework validate-recipes"
+  "delegation resolve"
   "plugin remove" "plugin list" "plugin install" "plugin search" "plugin update"
   "marketplace add" "marketplace list" "marketplace remove" "marketplace refresh" "marketplace check"
   "auth login" "auth logout" "auth status"
@@ -65,7 +66,7 @@ project_tree_hash() {
   ' )
 }
 
-PARENTS=" plugin marketplace auth framework telemetry "
+PARENTS=" plugin marketplace auth framework telemetry delegation "
 # A parent one level deeper than PARENTS, so a covered key needs three words there, not two.
 GRANDPARENTS=" telemetry identity "
 derive_key() {
@@ -190,6 +191,20 @@ FW_FLAT=$(mktemp -d "$TMPROOT/fw-flat.XXXXXX")
 run "translate --as flat" 0 "" "$ROOT" -- \
   translate "$FRAMEWORK_FIXTURE" --to claude --as flat --out "$FW_FLAT" --force
 
+section "delegation (read-only project settings)"
+P_DELEGATION=$(new_project)
+run "delegation resolve (native inheritance)" 0 '"configured": false' "$P_DELEGATION" -- \
+  delegation resolve exploration --tool codex --json
+mkdir -p "$P_DELEGATION/.aidd"
+printf '%s' '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"reasoning":"high"}}}}}' > "$P_DELEGATION/.aidd/config.json"
+delegation_before=$(project_tree_hash "$P_DELEGATION")
+run "delegation resolve (unsupported requested setting)" 1 "unsupported field reasoning" "$P_DELEGATION" -- \
+  delegation resolve exploration --tool codex --json
+delegation_after=$(project_tree_hash "$P_DELEGATION")
+[[ -n "$delegation_before" && "$delegation_before" == "$delegation_after" ]] \
+  && ok "delegation error preserves project files" \
+  || bad "delegation error changed project files"
+
 section "auth (isolated config)"
 AUTH_HOME="$TMPROOT/auth-home"; mkdir -p "$AUTH_HOME"
 P_AUTH=$(new_project)
diff --git a/cli/tests/e2e/kilo-runtime.e2e.test.ts b/cli/tests/e2e/kilo-runtime.e2e.test.ts
index 22b4ecea6..453ec77f3 100644
--- a/cli/tests/e2e/kilo-runtime.e2e.test.ts
+++ b/cli/tests/e2e/kilo-runtime.e2e.test.ts
@@ -280,8 +280,9 @@ describeKiloRuntime("E2E: real Kilo runtime", () => {
         shell: KILO_SHELL,
         maxBuffer: 8 * 1024 * 1024,
       });
-      expect(agents.stdout).toContain("aidd-dev-checker");
-      expect(agents.stdout).toContain("aidd-dev-executor");
+      for (const role of ["explorer", "executor", "reviewer", "validator"]) {
+        expect(agents.stdout).toContain(`aidd-dev-${role}`);
+      }
 
       const mcpProject = join(tempDir, "generated-mcp");
       await mkdir(mcpProject, { recursive: true });
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index cabed7856..71092c5b7 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -213,7 +213,7 @@ test("reload fixtures run from their temporary home", () => {
   try {
     const fakeBin = join(root, "bin"), home = join(root, "home");
     mkdirSync(fakeBin);
-    executable(join(fakeBin, "aidd-opencode-reload"), 'pwd > "$HOME/observed-cwd"');
+    executable(join(fakeBin, "aidd-opencode-reload"), "node -e 'process.stdout.write(process.cwd())' > \"$HOME/observed-cwd\"");
     const result = runSync(fakeBin, home, []);
     assert.equal(result.status, 0, result.stderr);
     assert.equal(realpathSync(readFileSync(join(home, "observed-cwd"), "utf8").trim()), realpathSync(home));
@@ -679,11 +679,12 @@ test("another tool named agent does not trigger Cursor installation", () => {
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
+const copilotMarketplaceList = String.raw`node -e 'process.stdout.write(JSON.stringify([{name:"aidd-framework",source:"Local: "+process.argv[1]}]))'`;
 const copilotStub = String.raw`printf '%s\n' "$*" >> "$HOME/copilot-calls"
 case "$1 $2 $3" in
   'plugin marketplace list')
     if [ -f "$HOME/copilot-source" ]; then
-      printf '[{"name":"aidd-framework","source":"Local: %s"}]\n' "$(cat "$HOME/copilot-source")"
+      ${copilotMarketplaceList} "$(cat "$HOME/copilot-source")"
     else echo '[]'; fi ;;
   'plugin marketplace add')
     if [ -f "$HOME/copilot-source" ]; then echo 'Marketplace "aidd-framework" already registered' >&2; exit 1; fi
@@ -692,6 +693,26 @@ case "$1 $2 $3" in
   'plugin marketplace update') : ;;
 esac`;
 
+test("Copilot fixture serializes Windows paths and quotes as JSON", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-json-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin); mkdirSync(home);
+    const source = String.raw`C:\Users\Example "quoted"\Framework`;
+    writeFileSync(join(home, "copilot-source"), source);
+    executable(join(fakeBin, "node"), `exec '${process.execPath}' "$@"`);
+    const binary = join(fakeBin, "copilot");
+    executable(binary, copilotStub);
+    const result = spawnSync("bash", [binary, "plugin", "marketplace", "list", "--json"], {
+      cwd: home,
+      env: { ...process.env, HOME: home, PATH: [fakeBin, BASE_PATH].join(delimiter) },
+      encoding: "utf8",
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), [{ name: "aidd-framework", source: `Local: ${source}` }]);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
 test("Copilot reload builds all native plugins, migrates its own source, and preserves personal files", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-copilot-"));
   try {
@@ -708,7 +729,7 @@ test("Copilot reload builds all native plugins, migrates its own source, and pre
     executable(join(fakeBin, "npx"), nativeBuildStub());
     const first = runSync(fakeBin, home, []);
     assert.equal(first.status, 0, first.stderr);
-    assert.equal(readFileSync(join(home, "copilot-source"), "utf8"), join(home, "build/copilot"));
+    assert.equal(realpathSync(readFileSync(join(home, "copilot-source"), "utf8")), realpathSync(join(home, "build/copilot")));
     for (const plugin of ["aidd-dev", "aidd-pm"]) {
       assert.match(readFileSync(join(home, "copilot-calls"), "utf8"), new RegExp(`plugin install ${plugin}@aidd-framework`));
       assert.equal(JSON.parse(readFileSync(join(home, `build/copilot/plugins/${plugin}/.plugin/plugin.json`), "utf8")).name, plugin);
@@ -757,14 +778,14 @@ test("Copilot registers an inherited own marketplace without trying to remove it
     mkdirSync(fakeBin);
     executable(join(fakeBin, "copilot"), String.raw`printf '%s\n' "$*" >> "$HOME/copilot-calls"
 case "$1 $2 $3" in
-  'plugin marketplace list') printf '[{"name":"aidd-framework","source":"Local: %s"}]\n' "$FW" ;;
+  'plugin marketplace list') ${copilotMarketplaceList} "$FW" ;;
   'plugin marketplace remove') echo 'Marketplace "aidd-framework" is not registered' >&2; exit 1 ;;
   'plugin marketplace add') printf '%s' "$4" > "$HOME/copilot-source" ;;
 esac`);
     executable(join(fakeBin, "npx"), nativeBuildStub());
     const result = runSync(fakeBin, home, []);
     assert.equal(result.status, 0, result.stderr);
-    assert.equal(readFileSync(join(home, "copilot-source"), "utf8"), join(home, "build/copilot"));
+    assert.equal(realpathSync(readFileSync(join(home, "copilot-source"), "utf8")), realpathSync(join(home, "build/copilot")));
     assert.doesNotMatch(readFileSync(join(home, "copilot-calls"), "utf8"), /marketplace remove/);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
@@ -776,7 +797,7 @@ for (const command of ["add", "update", "install"]) {
       const fakeBin = join(root, "bin"), home = join(root, "home");
       mkdirSync(fakeBin);
       executable(join(fakeBin, "copilot"), String.raw`case "$1 $2 $3" in
-  'plugin marketplace list') ${command === "update" ? 'printf \'[{"name":"aidd-framework","source":"Local: %s"}]\\n\' "$BUILD/copilot"' : "echo '[]'"} ;;
+  'plugin marketplace list') ${command === "update" ? `${copilotMarketplaceList} "$BUILD/copilot"` : "echo '[]'"} ;;
   'plugin marketplace ${command}'${command === "install" ? "|\'plugin install aidd-dev@aidd-framework\'" : ""}) echo 'fixture native permission denied' >&2; exit 9 ;;
 esac`);
       executable(join(fakeBin, "npx"), nativeBuildStub());

From 9a40c46e259e4901d58d257a5e92dd3ad3817355 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 14:30:47 +0800
Subject: [PATCH 22/73] test(cli): verify native delegation option boundaries

---
 .../resolve-delegation-use-case.unit.test.ts  |  4 +-
 .../tools/domain/profiles/cursor.unit.test.ts | 40 +++++++++++++++++++
 .../domain/profiles/opencode.unit.test.ts     | 28 +++++++++++++
 3 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
index 4bc33d78a..34f24a87f 100644
--- a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
+++ b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
@@ -455,7 +455,9 @@ describe("resolving an installed delegation suggestion", () => {
       "/repo/.cursor/agents/aidd-dev-explorer.md",
       "---\nname: aidd-dev-explorer\n---\nBody"
     );
-    await expect(selected.resolve()).rejects.toThrow(reason);
+    await expect(selected.resolve()).rejects.toMatchObject({
+      message: expect.stringContaining(reason),
+    });
   });
 
   it("passes a literal Cursor model unchanged when effort is omitted", async () => {
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
index aa92cb0cb..5c0291fcd 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
@@ -4,6 +4,46 @@ import { CONFIG_MCP } from "../../../../../src/contexts/tools/domain/capabilitie
 import { cursor } from "../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
 
 describe("cursor", () => {
+  describe("capabilities.agents delegation", () => {
+    const delegation = cursor.capabilities.agents.params.delegation;
+    if (delegation === undefined) throw new Error("Cursor delegation must be declared");
+
+    it.each(["!high", "high!", "hi!gh"])(
+      "rejects an effort delimiter in %s before constructing a model option",
+      async (effort) => {
+        await expect(
+          Promise.resolve().then(() =>
+            delegation.resolveNative({ model: "native-model", effort }, "flat")
+          )
+        ).rejects.toMatchObject({ message: expect.stringContaining("Invalid effort") });
+      }
+    );
+
+    it.each([
+      "model]",
+      "[context=1m]",
+      "model[foo[bar=value]",
+      "model[=1]",
+      "model[context=a=b]",
+      "model[context=1 m]",
+    ])("rejects malformed model options in %s when adding effort", async (model) => {
+      await expect(
+        Promise.resolve().then(() => delegation.resolveNative({ model, effort: "high" }, "flat"))
+      ).rejects.toMatchObject({ message: expect.stringContaining("Malformed") });
+    });
+
+    it("preserves a personal agent's declared name in flat mode", () => {
+      expect(delegation.identity("personal-reviewer", "aidd-dev", "flat", "reviewer")).toBe(
+        "personal-reviewer"
+      );
+    });
+
+    it("distinguishes flat agent configuration from plugin spawn options", () => {
+      expect(delegation.nativeSurface?.("flat")).toBe("agent-configuration");
+      expect(delegation.nativeSurface?.("marketplace")).toBe("spawn");
+    });
+  });
+
   describe("capabilities.rules.convertFrontmatter()", () => {
     it("converts paths: to globs: as a JSON inline string and adds alwaysApply: false", () => {
       const result = cursor.capabilities.rules?.convertFrontmatter({
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
index c9c40137c..10b6a1fc5 100644
--- a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { opencode } from "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
 import { OpencodeDualConfigError } from "../../../../../src/kernel/errors.js";
@@ -17,6 +18,33 @@ function makeFs(existingPaths: string[]): FileReader {
 }
 
 describe("opencode", () => {
+  describe("capabilities.agents delegation", () => {
+    const delegation = opencode.capabilities.agents.params.delegation;
+    if (delegation === undefined) throw new Error("OpenCode delegation must be declared");
+
+    it.each(["!high", "high!", "hi!gh"])(
+      "rejects an effort delimiter in %s before constructing a model variant",
+      async (effort) => {
+        await expect(
+          Promise.resolve().then(() =>
+            delegation.resolveNative({ model: "provider/model", effort }, "flat")
+          )
+        ).rejects.toMatchObject({ message: expect.stringContaining("Invalid effort") });
+      }
+    );
+
+    it("finds personal agents under the native XDG configuration override", () => {
+      expect(
+        delegation.userPath(
+          "/person",
+          { XDG_CONFIG_HOME: "/native-config" },
+          "aidd-dev",
+          "explorer"
+        )
+      ).toBe(join("/native-config", "opencode", "agents", "aidd-dev-explorer.md"));
+    });
+  });
+
   describe("capabilities.agents.buildInstallPath()", () => {
     it("builds path under .opencode/agents/", () => {
       const path = opencode.capabilities.agents.buildInstallPath("code-reviewer.md");

From 40c9a7409531717cd4b830261891fde471f29821 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 14:36:40 +0800
Subject: [PATCH 23/73] docs(aidd-dev): record CI follow-up verification

---
 .../2026_10/2026_10_14_sub_agents/review.md   | 17 ++++++++++++++-
 .../2026_10_14_sub_agents/runtime.json        | 21 +++++++++++++++++++
 .../2026_10_14_sub_agents/verification.md     | 17 +++++++++++----
 3 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
index 79564d4e9..b712837a0 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
@@ -1,6 +1,6 @@
 # Review: scoped sub-agents
 
-- Rounds: 3
+- Rounds: 4
 - Started: 2026-10-15
 
 ## Round 1 · r-1fd6
@@ -54,3 +54,18 @@
 - **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.
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
index b5a07c694..d8c14a34b 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
@@ -349,5 +349,26 @@
       }
     ],
     "unsupported_cursor_effort": "Error: Cursor plugin spawn does not accept effort; choose an advertised model slug or omit effort to inherit."
+  },
+  "final_mutation_gates": {
+    "tools-cursor": {
+      "score_percent": 97.4138,
+      "unchanged_floor": 97,
+      "exit": 0,
+      "mutant_status_counts": {
+        "Killed": 339,
+        "Survived": 9
+      }
+    },
+    "tools-opencode": {
+      "score_percent": 94.9704,
+      "unchanged_floor": 94,
+      "exit": 0,
+      "mutant_status_counts": {
+        "NoCoverage": 2,
+        "Killed": 321,
+        "Survived": 15
+      }
+    }
   }
 }
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index e73f15e77..19209f306 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -52,7 +52,7 @@ The wrapped scripts suite passed 559 tests, including 12 reload regressions. Arc
 
 ## Current candidate, 2026-10-15
 
-The earlier results above describe the previous checker contract. Current probes use the four scoped roles: explorer, executor, validator and reviewer. Validator returns one completion verdict; reviewer independently assesses quality. Native dispatch events establish invocation; generated files and agent self-reports alone do not.
+The earlier results above describe the previous checker contract. Native runtime probes ran on macOS. Current probes use the four scoped roles: explorer, executor, validator and reviewer. Validator returns one completion verdict; reviewer independently assesses quality. Native dispatch events establish invocation; generated files and agent self-reports alone do not.
 
 | Host | Tested version | Delivery and observed runtime |
 | --- | --- | --- |
@@ -85,8 +85,17 @@ A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the
 
 ### Final checks
 
-- **CLI:** 543 test files passed, one skipped; 7,106 tests passed, one skipped. Architecture, typecheck, lint, type honesty, unused-code and duplication gates pass. Lint retains one pre-existing unused-private-field warning. Bundle is 567.8 KB against the unchanged 756 KB budget.
-- **Scripts:** the wrapped full suite passes 729 tests. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
+- **CLI:** 543 test files passed, one skipped; 7,121 tests passed, one skipped. Architecture, typecheck, lint, type honesty, unused-code and duplication gates pass. Lint retains one pre-existing unused-private-field warning. Bundle is 567.8 KB against the unchanged 756 KB budget.
+- **Scripts:** the wrapped full suite passes 730 tests. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
 - **Integration:** the real resolver finds installed agents on all five hosts, preserves project configuration bytes, leaves missing tasks inherited, and rejects unsupported Cursor plugin effort. Actual `make reload` exits 0 after the final corrections; the personal-file preservation check still passes.
-- **Guards:** removing the unknown-field rejection and bypassing Claude activation each causes the targeted test to fail. Exact source bytes were restored and the named tests pass; no full mutation-score claim is made.
+- **Guards:** removing the unknown-field rejection and bypassing Claude activation each causes the targeted test to fail. Exact source bytes were restored and the named tests pass; both full native scopes subsequently pass: Cursor 97.4% against 97%, OpenCode 95.0% against 94%, with unchanged floors.
 - **Scope:** gather, wireframe, the challenge skill and generic skill generation have no diff against `next`. Generic generation work remains in PR #1028.
+
+
+### CI follow-up
+
+The first CI run caught a missing smoke command, a stale checker-name expectation in the real Kilo probe, Windows fixture path/JSON issues, and two mutation-floor failures. Only test coverage and fixtures changed afterward; production behavior and mutation floors remain unchanged.
+
+The smoke suite now passes 140 checks with 35/35 commands exercised. Official Kilo 7.7.5 passes its real loopback runtime test with all four current roles. The root suite passes 730 tests, including a Windows-style JSON serialization regression. Windows execution is checked by the PR's CI jobs.
+
+Fifteen native profile cases cover invalid selector boundaries, malformed option groups, personal agent identity, configuration versus spawn surfaces, and the OpenCode XDG override. Malformed-error assertions now inspect the actual error message; the earlier assertion could accept an undefined rejection. Both complete mutation scopes pass their original floors; exact status counts are retained in [runtime.json](runtime.json).

From d5ee97f744fb7f7ed8fb2f09e882d31290fedd43 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 14:53:06 +0800
Subject: [PATCH 24/73] docs(aidd-dev): refresh verification after next
 integration

---
 .../tasks/2026_10/2026_10_14_sub_agents/verification.md     | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 19209f306..0145289b9 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -85,8 +85,8 @@ A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the
 
 ### Final checks
 
-- **CLI:** 543 test files passed, one skipped; 7,121 tests passed, one skipped. Architecture, typecheck, lint, type honesty, unused-code and duplication gates pass. Lint retains one pre-existing unused-private-field warning. Bundle is 567.8 KB against the unchanged 756 KB budget.
-- **Scripts:** the wrapped full suite passes 730 tests. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
+- **CLI:** after integrating `next` at `0a103e67`, 503 test files pass, one skipped; 6,545 tests pass, one skipped. Architecture, typecheck, lint, type honesty and unused-code gates pass. Bundle is 515.7 KB against Next's 695 KB budget. The local run unsets inherited `CODEX_THREAD_ID` so two imported telemetry fixtures use their own session IDs.
+- **Scripts:** the wrapped full suite passes 498 tests after Next retires the previous telemetry suite. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
 - **Integration:** the real resolver finds installed agents on all five hosts, preserves project configuration bytes, leaves missing tasks inherited, and rejects unsupported Cursor plugin effort. Actual `make reload` exits 0 after the final corrections; the personal-file preservation check still passes.
 - **Guards:** removing the unknown-field rejection and bypassing Claude activation each causes the targeted test to fail. Exact source bytes were restored and the named tests pass; both full native scopes subsequently pass: Cursor 97.4% against 97%, OpenCode 95.0% against 94%, with unchanged floors.
 - **Scope:** gather, wireframe, the challenge skill and generic skill generation have no diff against `next`. Generic generation work remains in PR #1028.
@@ -96,6 +96,6 @@ A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the
 
 The first CI run caught a missing smoke command, a stale checker-name expectation in the real Kilo probe, Windows fixture path/JSON issues, and two mutation-floor failures. Only test coverage and fixtures changed afterward; production behavior and mutation floors remain unchanged.
 
-The smoke suite now passes 140 checks with 35/35 commands exercised. Official Kilo 7.7.5 passes its real loopback runtime test with all four current roles. The root suite passes 730 tests, including a Windows-style JSON serialization regression. Windows execution is checked by the PR's CI jobs.
+Before the Next integration, the smoke suite passed 140 checks with 35/35 commands exercised; official Kilo 7.7.5 passed its real loopback runtime test with all four current roles. The Windows-style JSON serialization regression remains in the root suite. Windows execution is checked by the PR's CI jobs.
 
 Fifteen native profile cases cover invalid selector boundaries, malformed option groups, personal agent identity, configuration versus spawn surfaces, and the OpenCode XDG override. Malformed-error assertions now inspect the actual error message; the earlier assertion could accept an undefined rejection. Both complete mutation scopes pass their original floors; exact status counts are retained in [runtime.json](runtime.json).

From 6194ce7aabd1e27622a35851019fddd165f84c21 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 15:10:51 +0800
Subject: [PATCH 25/73] test(cli): verify delegation wiring across platforms

---
 .../2026_10_14_sub_agents/runtime.json        |  12 ++
 .../2026_10_14_sub_agents/verification.md     |   6 +-
 .../resolve-delegation-use-case.unit.test.ts  |   8 +-
 .../commands/auth-wiring.integration.test.ts  |   4 +-
 .../delegation-wiring.integration.test.ts     | 125 ++++++++++++++++++
 5 files changed, 148 insertions(+), 7 deletions(-)
 create mode 100644 cli/tests/presentation/commands/delegation-wiring.integration.test.ts

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
index d8c14a34b..44f944a94 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
@@ -369,6 +369,18 @@
         "Killed": 321,
         "Survived": 15
       }
+    },
+    "presentation": {
+      "score_percent": 95.0187,
+      "unchanged_floor": 95,
+      "exit": 0,
+      "mutant_status_counts": {
+        "NoCoverage": 35,
+        "Killed": 2516,
+        "Survived": 98,
+        "Timeout": 21
+      },
+      "isolated_auth_guard": "Killed"
     }
   }
 }
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 0145289b9..d6bb4b9df 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -85,7 +85,7 @@ A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the
 
 ### Final checks
 
-- **CLI:** after integrating `next` at `0a103e67`, 503 test files pass, one skipped; 6,545 tests pass, one skipped. Architecture, typecheck, lint, type honesty and unused-code gates pass. Bundle is 515.7 KB against Next's 695 KB budget. The local run unsets inherited `CODEX_THREAD_ID` so two imported telemetry fixtures use their own session IDs.
+- **CLI:** after integrating `next` at `0a103e67`, 504 test files pass, one skipped; 6,551 tests pass, one skipped. Architecture, typecheck, lint, type honesty and unused-code gates pass. Bundle is 515.7 KB against Next's 695 KB budget. The local run unsets inherited `CODEX_THREAD_ID` so two imported telemetry fixtures use their own session IDs.
 - **Scripts:** the wrapped full suite passes 498 tests after Next retires the previous telemetry suite. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
 - **Integration:** the real resolver finds installed agents on all five hosts, preserves project configuration bytes, leaves missing tasks inherited, and rejects unsupported Cursor plugin effort. Actual `make reload` exits 0 after the final corrections; the personal-file preservation check still passes.
 - **Guards:** removing the unknown-field rejection and bypassing Claude activation each causes the targeted test to fail. Exact source bytes were restored and the named tests pass; both full native scopes subsequently pass: Cursor 97.4% against 97%, OpenCode 95.0% against 94%, with unchanged floors.
@@ -96,6 +96,8 @@ A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the
 
 The first CI run caught a missing smoke command, a stale checker-name expectation in the real Kilo probe, Windows fixture path/JSON issues, and two mutation-floor failures. Only test coverage and fixtures changed afterward; production behavior and mutation floors remain unchanged.
 
-Before the Next integration, the smoke suite passed 140 checks with 35/35 commands exercised; official Kilo 7.7.5 passed its real loopback runtime test with all four current roles. The Windows-style JSON serialization regression remains in the root suite. Windows execution is checked by the PR's CI jobs.
+After the Next integration, the smoke suite passes 135 checks with 33/33 commands exercised. Official Kilo 7.7.5 passed its real loopback runtime test with all four current roles before that integration. Windows fixture serialization and native path expectations are covered; Windows execution is checked by the PR's CI jobs.
 
 Fifteen native profile cases cover invalid selector boundaries, malformed option groups, personal agent identity, configuration versus spawn surfaces, and the OpenCode XDG override. Malformed-error assertions now inspect the actual error message; the earlier assertion could accept an undefined rejection. Both complete mutation scopes pass their original floors; exact status counts are retained in [runtime.json](runtime.json).
+
+Six command-wiring cases cover delegation JSON, text, inheritance, diagnostics, required host and failure routing. The existing authentication mutual-exclusion test now supplies a valid storage level, preventing a later guard from masking the one under test. Presentation mutation passes at 95.0187% against the unchanged 95% floor; the removed guard is detected. Production behavior is unchanged by these test corrections.
diff --git a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
index 34f24a87f..91ca91778 100644
--- a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
+++ b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
@@ -120,7 +120,7 @@ describe("resolving an installed delegation suggestion", () => {
 
   it("honors CODEX_HOME and inherits omitted settings", async () => {
     const { fs, repo } = setup("codex");
-    const path = "/custom/codex/agents/aidd-dev-explorer.toml";
+    const path = join("/custom/codex", "agents", "aidd-dev-explorer.toml");
     await fs.writeFile(path, 'name = "actual-role"\ndeveloper_instructions = "Body"');
     const useCase = new ResolveDelegationUseCase(fs, repo, new Map());
     const result = await useCase.execute({
@@ -145,7 +145,7 @@ describe("resolving an installed delegation suggestion", () => {
       "---\nname: Personal\n---\nPersonal behavior"
     );
     expect((await selected.resolve()).agent?.path).toBe(
-      "/person/.copilot/agents/aidd-dev-explorer.agent.md"
+      join(HOME, ".copilot", "agents", "aidd-dev-explorer.agent.md")
     );
   });
 
@@ -172,7 +172,7 @@ describe("resolving an installed delegation suggestion", () => {
     });
     expect(result.agent).toMatchObject({
       name: "selected-agent",
-      path: "/relocated/agents/aidd-dev-explorer.md",
+      path: join("/relocated", "agents", "aidd-dev-explorer.md"),
     });
   });
 
@@ -256,7 +256,7 @@ describe("resolving an installed delegation suggestion", () => {
     ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "claude" });
     expect(result.agent).toEqual({
       name: "aidd-dev:explorer",
-      path: "/native/aidd-dev/agents/explorer.md",
+      path: join("/native/aidd-dev", "agents", "explorer.md"),
       mode: "marketplace",
     });
   });
diff --git a/cli/tests/presentation/commands/auth-wiring.integration.test.ts b/cli/tests/presentation/commands/auth-wiring.integration.test.ts
index c406ccbdb..c344d513f 100644
--- a/cli/tests/presentation/commands/auth-wiring.integration.test.ts
+++ b/cli/tests/presentation/commands/auth-wiring.integration.test.ts
@@ -140,7 +140,9 @@ describe("aidd auth login — what it refuses before building anything", () => {
   it("refuses a run that names two ways of authenticating at once", async () => {
     const exit = refusing();
 
-    await expect(run("login", "--gh", "--token", "ghp_x")).rejects.toThrow("exited");
+    await expect(run("login", "--gh", "--token", "ghp_x", "--level", "user")).rejects.toThrow(
+      "exited"
+    );
 
     expect(errors[0]).toBe("Error: --gh and --token are mutually exclusive.\n");
     expect(exit).toHaveBeenCalledWith(1);
diff --git a/cli/tests/presentation/commands/delegation-wiring.integration.test.ts b/cli/tests/presentation/commands/delegation-wiring.integration.test.ts
new file mode 100644
index 000000000..d224bfff3
--- /dev/null
+++ b/cli/tests/presentation/commands/delegation-wiring.integration.test.ts
@@ -0,0 +1,125 @@
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DelegationResolution } from "../../../src/contexts/framework/domain/delegation.js";
+import { resolveHomeDir } from "../../../src/kernel/reading/home-dir.js";
+
+const execute = vi.fn();
+vi.mock("../../../src/runtime/wiring/framework.js", () => ({
+  createDeps: vi.fn(async () => ({ resolveDelegationUseCase: { execute } })),
+}));
+
+const { createDeps } = await import("../../../src/runtime/wiring/framework.js");
+const { registerDelegationCommand } = await import(
+  "../../../src/presentation/commands/delegation.js"
+);
+
+const resolution: DelegationResolution = {
+  task: "exploration",
+  tool: "codex",
+  configured: true,
+  canonicalAgent: "aidd-dev:explorer",
+  agent: { name: "personal-explorer", path: "/agents/explorer.toml", mode: "flat" },
+  requested: { model: "chosen-model", effort: "high" },
+  native: { model: "chosen-model", model_reasoning_effort: "high" },
+  nativeSurface: "agent-configuration",
+  effectiveRuntime: "unknown",
+  diagnostics: ["The installed agent pins its own model."],
+};
+let written: string[];
+let errors: string[];
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  written = [];
+  errors = [];
+  vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+    written.push(String(chunk));
+    return true;
+  });
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+    errors.push(String(chunk));
+    return true;
+  });
+  execute.mockResolvedValue(resolution);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  process.exitCode = undefined;
+});
+
+async function run(...args: string[]): Promise<string> {
+  const program = new Command().exitOverride().option("--verbose");
+  registerDelegationCommand(program);
+  await program.parseAsync(["node", "aidd", ...args]);
+  return written.join("");
+}
+
+describe("aidd delegation resolve", () => {
+  it("resolves the selected task and host in the current project and home", async () => {
+    await run("--verbose", "delegation", "resolve", "exploration", "--tool", "codex");
+
+    expect(createDeps).toHaveBeenCalledWith(process.cwd(), { verbose: true }, expect.anything());
+    expect(execute).toHaveBeenCalledWith({
+      projectRoot: process.cwd(),
+      home: resolveHomeDir(),
+      env: process.env,
+      task: "exploration",
+      tool: "codex",
+    });
+  });
+
+  it("returns a machine-readable resolution without mixing in text or warnings", async () => {
+    const output = await run("delegation", "resolve", "exploration", "--tool", "codex", "--json");
+
+    expect(JSON.parse(output)).toEqual(resolution);
+    expect(errors).toEqual([]);
+  });
+
+  it("shows the installed identity, native surface and diagnostics without claiming application", async () => {
+    const output = await run("delegation", "resolve", "exploration", "--tool", "codex");
+
+    expect(output).toContain("Agent: personal-explorer (/agents/explorer.toml)");
+    expect(output).toContain(`Requested: ${JSON.stringify(resolution.requested)}`);
+    expect(output).toContain(
+      `Native suggestion (agent-configuration): ${JSON.stringify(resolution.native)}`
+    );
+    expect(output).toContain("Unspecified settings inherit. Effective runtime: unknown.");
+    expect(errors.join("")).toContain("The installed agent pins its own model.");
+  });
+
+  it("keeps missing settings inherited without inventing an agent or native options", async () => {
+    execute.mockResolvedValue({ ...resolution, configured: false, agent: undefined });
+
+    const output = await run("delegation", "resolve", "exploration", "--tool", "codex");
+
+    expect(output).toContain(
+      "No configured suggestion for exploration; the caller keeps its role and native settings."
+    );
+    expect(output).toContain("Unspecified settings inherit. Effective runtime: unknown.");
+    expect(output).not.toContain("Agent:");
+    expect(output).not.toContain("Native suggestion");
+    expect(errors).toEqual([]);
+  });
+
+  it("requires the host before attempting resolution", async () => {
+    await expect(run("delegation", "resolve", "exploration")).rejects.toMatchObject({
+      code: "commander.missingMandatoryOptionValue",
+    });
+    expect(execute).not.toHaveBeenCalled();
+  });
+
+  it("reports a resolution failure on stderr and exits unsuccessfully", async () => {
+    execute.mockRejectedValue(new Error("The selected agent is unavailable"));
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("exited");
+    });
+
+    await expect(run("delegation", "resolve", "exploration", "--tool", "codex")).rejects.toThrow(
+      "exited"
+    );
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(errors.join("")).toContain("Error: The selected agent is unavailable");
+    expect(written).toEqual([]);
+  });
+});

From 305521d05e9a6c4a4485d936f04934fe89bed9c3 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 18:43:19 +0800
Subject: [PATCH 26/73] refactor(framework): configure models in native agent
 files

---
 .../2026_10/2026_10_14_sub_agents/review.md   |  13 +
 .../2026_10_14_sub_agents/runtime.json        |   2 +
 .../2026_10_14_sub_agents/verification.md     |  14 +-
 cli/README.md                                 |   4 +-
 cli/aidd_docs/memory/cli.md                   |   1 -
 cli/scripts/smoke-tools.sh                    |  17 +-
 cli/src/cli.ts                                |   2 -
 .../resolve-delegation-use-case.ts            | 142 ------
 .../contexts/framework/domain/delegation.ts   | 103 ----
 .../domain/capabilities/agents-capability.ts  |  56 +--
 .../tools/domain/formats/agent-models.json    |  43 ++
 .../tools/domain/formats/agent-models.ts      |  45 ++
 .../domain/formats/delegation-options.ts      |  34 --
 .../tools/domain/marketplace-catalog.ts       |   9 +-
 .../ports/host-plugin-registry-reader.ts      |  12 +-
 .../tools/domain/profiles/claude/build.ts     |  15 +-
 .../domain/profiles/claude/claude-paths.ts    |   8 -
 .../tools/domain/profiles/claude/profile.ts   |  12 +-
 .../domain/profiles/codex/codex-agent-toml.ts |  13 +-
 .../tools/domain/profiles/codex/profile.ts    |  27 +-
 .../tools/domain/profiles/copilot/build.ts    |  15 +-
 .../domain/profiles/copilot/copilot-paths.ts  |  32 --
 .../tools/domain/profiles/copilot/profile.ts  |  23 +-
 .../tools/domain/profiles/cursor/build.ts     |  10 +-
 .../tools/domain/profiles/cursor/profile.ts   |  72 +--
 .../tools/domain/profiles/opencode/build.ts   |   8 +-
 .../tools/domain/profiles/opencode/profile.ts |  27 +-
 .../host-plugin-registry-reader-adapter.ts    | 193 +------
 .../translate/domain/content-translator.ts    |  36 +-
 cli/src/presentation/commands/delegation.ts   |  46 --
 cli/src/runtime/wiring/framework.ts           |   3 -
 .../architecture/folder-size.arch.test.ts     |  14 +-
 ...plugin-opencode-mode-b.integration.test.ts |   8 +-
 .../resolve-delegation-use-case.unit.test.ts  | 473 ------------------
 .../framework/domain/delegation.unit.test.ts  |  77 ---
 .../domain/formats/agent-models.unit.test.ts  | 119 +++++
 .../tools/domain/profiles/claude.unit.test.ts |   4 +-
 .../domain/profiles/codex/build.unit.test.ts  |   4 +-
 .../codex/codex-agent-toml.unit.test.ts       |  14 +-
 .../domain/profiles/copilot.unit.test.ts      |   4 +-
 .../tools/domain/profiles/cursor.unit.test.ts |  44 +-
 .../domain/profiles/opencode.unit.test.ts     |  28 --
 ...egistry-reader-adapter.integration.test.ts | 240 ---------
 ...e-build-strategy.codex.integration.test.ts |  19 +-
 .../plugin-content-translator.unit.test.ts    |  44 +-
 cli/tests/e2e/agent-models.e2e.test.ts        | 104 ++++
 cli/tests/e2e/delegation.e2e.test.ts          | 202 --------
 .../snapshots/framework-build/golden.json     |  12 +-
 cli/tests/golden/snapshots/help/surface.json  |  12 +-
 .../commands/auth-wiring.integration.test.ts  |   4 +-
 .../delegation-wiring.integration.test.ts     | 125 -----
 cli/tsup.config.ts                            |   3 -
 docs/DELEGATION.md                            |  61 +--
 plugins/aidd-dev/agents/executor.md           |  10 +-
 plugins/aidd-dev/agents/explorer.md           |   3 +-
 plugins/aidd-dev/agents/reviewer.md           |  13 +-
 plugins/aidd-dev/agents/validator.md          |   9 +-
 .../skills/01-plan/actions/02-explore.md      |   2 +-
 .../skills/10-batch/actions/01-batch.md       |   2 +-
 .../skills/01-sdlc/references/mode.md         |   1 -
 60 files changed, 590 insertions(+), 2102 deletions(-)
 delete mode 100644 cli/src/contexts/framework/application/resolve-delegation-use-case.ts
 delete mode 100644 cli/src/contexts/framework/domain/delegation.ts
 create mode 100644 cli/src/contexts/tools/domain/formats/agent-models.json
 create mode 100644 cli/src/contexts/tools/domain/formats/agent-models.ts
 delete mode 100644 cli/src/contexts/tools/domain/formats/delegation-options.ts
 delete mode 100644 cli/src/presentation/commands/delegation.ts
 delete mode 100644 cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
 delete mode 100644 cli/tests/contexts/framework/domain/delegation.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
 create mode 100644 cli/tests/e2e/agent-models.e2e.test.ts
 delete mode 100644 cli/tests/e2e/delegation.e2e.test.ts
 delete mode 100644 cli/tests/presentation/commands/delegation-wiring.integration.test.ts

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
index b712837a0..58bff11bf 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
@@ -69,3 +69,16 @@ No consequential new findings in the scoped rereview. Full test results and nati
 - **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.
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
index 44f944a94..4bb859fe7 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
@@ -1,4 +1,6 @@
 {
+  "candidate": "6194ce7aabd1e27622a35851019fddd165f84c21",
+  "scope": "Historical runtime probes before CLI-installed model defaults",
   "date": "2026-10-15",
   "source_agent_sha256": {
     "explorer": "735e8f34797b47acd1763cb0c84553974b82c4cf0601fbba0726c1fc5310b862",
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index d6bb4b9df..5e5cd8387 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -1,5 +1,17 @@
 # Sub-agent verification
 
+## Installed model defaults, 2026-10-15
+
+The [CLI configuration](../../../../cli/src/contexts/tools/domain/formats/agent-models.json) now owns provider defaults and native fields. Conversion applies them to the four AIDD roles; explicit settings survive. The resolver command and workflow dependencies on it are removed. Agent behaviors are reduced to three capabilities each.
+
+- **Checks:** 6,499 CLI tests pass, one skipped; 498 script tests pass. Typecheck, lint, architecture, type honesty and unused-code checks pass. Bundle: 684.5 KB / 695 KB.
+- **Headers:** nine built-CLI cases inspect all four real agent sources across native flat and marketplace outputs. Ordinary installation tests also inspect translated file paths and contents. A provider-switch test verifies Copilot's native Anthropic identifier; removing its lookup makes that test fail.
+- **Limits:** Codex loads the flat agent files, not TOMLs staged inside a plugin. Cursor flat agents accept the configured selector; plugin agents inherit their model. These file checks do not establish account access to a model or effective runtime selection.
+
+## Earlier runtime evidence
+
+The runtime probes below describe earlier candidates. Their traces and hashes predate the CLI-installed model defaults and the latest simplified agent bodies.
+
 Verified 2026-10-14 on `feature/sub-agents`: workflow candidate `1f151d19`, delivery candidate `e00f124c`.
 
 ## Native roles
@@ -50,7 +62,7 @@ OpenCode's configured local model server was unavailable. Its behavioral probe u
 
 The wrapped scripts suite passed 559 tests, including 12 reload regressions. Architecture, JSON manifest validation, Markdown links, duplication checks, and commit hooks passed. These results establish the observed contracts and host paths; they do not guarantee every future task or model choice.
 
-## Current candidate, 2026-10-15
+## Earlier four-role candidate, 2026-10-15
 
 The earlier results above describe the previous checker contract. Native runtime probes ran on macOS. Current probes use the four scoped roles: explorer, executor, validator and reviewer. Validator returns one completion verdict; reviewer independently assesses quality. Native dispatch events establish invocation; generated files and agent self-reports alone do not.
 
diff --git a/cli/README.md b/cli/README.md
index e4b014f0e..90b609533 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -121,9 +121,9 @@ 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 |
 
-### Delegation
+## Agent models
 
-`aidd delegation resolve <task> --tool <id> [--json]` reads the project's suggestion, verifies an installed agent, and reports requested/native settings. Resolution is read-only; the caller starts the agent. Configuration, host support and runtime checks: [project delegation](../docs/DELEGATION.md).
+The [bundled configuration](src/contexts/tools/domain/formats/agent-models.json) supplies model and effort defaults when installing or translating AIDD agents. See [sub-agent models](../docs/DELEGATION.md).
 
 ## Translate
 
diff --git a/cli/aidd_docs/memory/cli.md b/cli/aidd_docs/memory/cli.md
index 30a0d9c2a..558ea2e06 100644
--- a/cli/aidd_docs/memory/cli.md
+++ b/cli/aidd_docs/memory/cli.md
@@ -14,7 +14,6 @@ Thirty leaf commands. Read them live: `aidd --help`, then each group's. `scripts
 - `telemetry on | off | forget | ingest | task | report | identity`: local token measurement for Claude Code, mapped in `telemetry.md`.
 - `translate <source>`: author-side, converts a source into a target-native plugin tree.
 - `update`, aliased `upgrade`: the CLI itself.
-- `delegation resolve <task> --tool <id>`: read-only project suggestion, installed agent identity, native option surface; `--json` separates requested/native settings and leaves effective runtime unknown.
 
 ## Interface
 
diff --git a/cli/scripts/smoke-tools.sh b/cli/scripts/smoke-tools.sh
index 9c4e65908..d0a7d5f8b 100755
--- a/cli/scripts/smoke-tools.sh
+++ b/cli/scripts/smoke-tools.sh
@@ -25,7 +25,6 @@ ALL_COMMANDS=(
   "setup" "doctor" "sync" "translate" "update" "clean"
   "framework install" "framework update" "framework remove" "framework rules"
   "framework validate-recipes"
-  "delegation resolve"
   "plugin remove" "plugin list" "plugin install" "plugin search" "plugin update"
   "marketplace add" "marketplace list" "marketplace remove" "marketplace refresh" "marketplace check"
   "auth login" "auth logout" "auth status"
@@ -65,7 +64,7 @@ project_tree_hash() {
   ' )
 }
 
-PARENTS=" plugin marketplace auth framework telemetry delegation "
+PARENTS=" plugin marketplace auth framework telemetry "
 # A parent one level deeper than PARENTS, so a covered key needs three words there, not two.
 GRANDPARENTS=" "
 derive_key() {
@@ -190,20 +189,6 @@ FW_FLAT=$(mktemp -d "$TMPROOT/fw-flat.XXXXXX")
 run "translate --as flat" 0 "" "$ROOT" -- \
   translate "$FRAMEWORK_FIXTURE" --to claude --as flat --out "$FW_FLAT" --force
 
-section "delegation (read-only project settings)"
-P_DELEGATION=$(new_project)
-run "delegation resolve (native inheritance)" 0 '"configured": false' "$P_DELEGATION" -- \
-  delegation resolve exploration --tool codex --json
-mkdir -p "$P_DELEGATION/.aidd"
-printf '%s' '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"reasoning":"high"}}}}}' > "$P_DELEGATION/.aidd/config.json"
-delegation_before=$(project_tree_hash "$P_DELEGATION")
-run "delegation resolve (unsupported requested setting)" 1 "unsupported field reasoning" "$P_DELEGATION" -- \
-  delegation resolve exploration --tool codex --json
-delegation_after=$(project_tree_hash "$P_DELEGATION")
-[[ -n "$delegation_before" && "$delegation_before" == "$delegation_after" ]] \
-  && ok "delegation error preserves project files" \
-  || bad "delegation error changed project files"
-
 section "auth (isolated config)"
 AUTH_HOME="$TMPROOT/auth-home"; mkdir -p "$AUTH_HOME"
 P_AUTH=$(new_project)
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 54a6df3be..945e7a7d1 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -2,7 +2,6 @@ import { platform } from "node:os";
 import { Command } from "commander";
 import { registerAuthCommand } from "./presentation/commands/auth.js";
 import { registerCleanCommand } from "./presentation/commands/clean.js";
-import { registerDelegationCommand } from "./presentation/commands/delegation.js";
 import { registerDoctorCommand } from "./presentation/commands/doctor.js";
 import { registerFrameworkCommand } from "./presentation/commands/framework.js";
 import { registerMarketplaceCommand } from "./presentation/commands/marketplace.js";
@@ -42,7 +41,6 @@ registerUpdateCommand(program);
 registerDoctorCommand(program);
 registerCleanCommand(program);
 registerTelemetryCommand(program);
-registerDelegationCommand(program);
 
 // Commands already paying for network I/O, so the update-check refresh rides one of them.
 // `marketplace remove` is offline and `update` already resolves the latest version itself.
diff --git a/cli/src/contexts/framework/application/resolve-delegation-use-case.ts b/cli/src/contexts/framework/application/resolve-delegation-use-case.ts
deleted file mode 100644
index d2c66952b..000000000
--- a/cli/src/contexts/framework/application/resolve-delegation-use-case.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-import { join } from "node:path";
-import { parseFrontmatter } from "../../../kernel/markdown.js";
-import { AIDD_CONFIG_FILENAME, AIDD_DIR } from "../../../kernel/paths.js";
-import type { FileReader } from "../../../kernel/ports/file-reader.js";
-import { isAiToolId } from "../../../kernel/tool.js";
-import type { AiTool, HasAgents } from "../../tools/domain/contracts.js";
-import type { HostPluginRegistryReader } from "../../tools/domain/ports/host-plugin-registry-reader.js";
-import { getAiToolConfig, resolvePluginsCapability } from "../../tools/domain/registry.js";
-import { type DelegationResolution, parseDelegation } from "../domain/delegation.js";
-import type { ManifestRepository } from "../domain/ports/manifest-repository.js";
-import { resolveBaseDirFromRecord } from "./plugin/plugin-target-resolution.js";
-
-function hasAgents(tool: AiTool<unknown>): tool is AiTool<HasAgents> {
-  return "agents" in (tool.capabilities as object);
-}
-
-/** Reads project suggestions and installed artifacts. It neither writes settings nor starts agents. */
-export class ResolveDelegationUseCase {
-  constructor(
-    private readonly fs: FileReader,
-    private readonly manifest: ManifestRepository,
-    private readonly registries: ReadonlyMap<string, HostPluginRegistryReader>
-  ) {}
-
-  async execute(options: {
-    projectRoot: string;
-    home: string;
-    env: NodeJS.ProcessEnv;
-    task: string;
-    tool: string;
-  }): Promise<DelegationResolution> {
-    if (!isAiToolId(options.tool))
-      throw new Error(`Unknown tool "${options.tool}"; use an installed AI tool identifier.`);
-    const tool = getAiToolConfig(options.tool);
-    const configPath = join(options.projectRoot, AIDD_DIR, AIDD_CONFIG_FILENAME);
-    const raw = (await this.fs.fileExists(configPath)) ? await this.fs.readFile(configPath) : null;
-    const suggestion = parseDelegation(raw, options.task, options.tool, configPath);
-    const base = {
-      task: options.task,
-      tool: options.tool,
-      effectiveRuntime: "unknown" as const,
-      nativeSurface: "agent-configuration" as const,
-      diagnostics: [],
-    };
-    if (suggestion === undefined) return { ...base, configured: false, requested: {}, native: {} };
-    if (!hasAgents(tool) || tool.capabilities.agents.params.delegation === undefined)
-      throw new Error(
-        `${tool.displayName} does not support delegation resolution; select a supported tool.`
-      );
-    const capability = tool.capabilities.agents.params.delegation;
-    const { plugin, role } = suggestion;
-    const artifact = tool.buildContracts?.flat?.().artifacts.agents;
-    const flatPath = artifact?.supported ? artifact.path(plugin, `agents/${role}.md`) : undefined;
-    const paths: { path: string; mode: "flat" | "marketplace" }[] = [];
-    if (flatPath !== undefined)
-      paths.push({ path: join(options.projectRoot, flatPath), mode: "flat" });
-    const personal = {
-      path: capability.userPath(options.home, options.env, plugin, role),
-      mode: "flat" as const,
-    };
-    if (capability.personalAgentsFirst) paths.unshift(personal);
-    else paths.push(personal);
-    const findAgent = async (): Promise<DelegationResolution | undefined> => {
-      for (const candidate of paths) {
-        if (!(await this.fs.fileExists(candidate.path))) continue;
-        const native = capability.resolveNative(suggestion.requested, candidate.mode);
-        const content = await this.fs.readFile(candidate.path);
-        const declared =
-          capability.readName?.(content) ?? parseFrontmatter(content).frontmatter.name;
-        const name =
-          typeof declared === "string" && declared !== ""
-            ? declared
-            : candidate.mode === "marketplace"
-              ? role
-              : `${plugin}-${role}`;
-        return {
-          ...base,
-          nativeSurface: capability.nativeSurface?.(candidate.mode) ?? "agent-configuration",
-          configured: true,
-          canonicalAgent: suggestion.canonical,
-          requested: suggestion.requested,
-          native,
-          diagnostics: capability.diagnostics?.(content, suggestion.requested) ?? [],
-          agent: { name: capability.identity(name, plugin, candidate.mode, role), ...candidate },
-        };
-      }
-      return undefined;
-    };
-    const flat = await findAgent();
-    if (flat !== undefined) return flat;
-    const manifest = await this.manifest.load();
-    const recorded = manifest?.getPlugins(options.tool).find((entry) => entry.name === plugin);
-    const plugins = resolvePluginsCapability(options.tool);
-    if (plugins?.nativeActivation === null && capability.marketplacePath !== undefined) {
-      const baseDir =
-        recorded === undefined
-          ? plugins.resolvePluginsBaseDir(options.projectRoot, options.home)
-          : resolveBaseDirFromRecord(
-              recorded.scope,
-              options.tool,
-              options.projectRoot,
-              () => options.home
-            );
-      const pluginDir = plugins.pluginOutputDir(plugin);
-      if (pluginDir !== null)
-        paths.push({
-          path: capability.marketplacePath(join(baseDir, pluginDir), role),
-          mode: "marketplace",
-        });
-    }
-    const registry = this.registries.get(options.tool);
-    const unavailable: string[] = [];
-    if (registry !== undefined && capability.marketplacePath !== undefined) {
-      const reading = await registry.read(options.projectRoot, true);
-      if (reading.unreadable !== undefined)
-        throw new Error(
-          `${reading.location}: cannot verify installed agent (${reading.unreadable}); repair the native plugin registry or install a project agent.`
-        );
-      for (const [ref, entry] of reading.refs ?? []) {
-        if (!ref.startsWith(`${plugin}@`)) continue;
-        if (entry.activationUnverified !== undefined)
-          unavailable.push(`${ref}: ${entry.activationUnverified}`);
-        else if (!entry.enabled)
-          unavailable.push(
-            `${ref} is disabled; enable this plugin in ${tool.displayName}, then retry.`
-          );
-        else if (entry.installPath !== undefined)
-          paths.push({
-            path: capability.marketplacePath(entry.installPath, role),
-            mode: "marketplace",
-          });
-      }
-    }
-    const installed = await findAgent();
-    if (installed !== undefined) return installed;
-    if (unavailable.length > 0)
-      throw new Error(`Agent ${suggestion.canonical} unavailable: ${unavailable.join(" ")}`);
-    throw new Error(
-      `Agent ${suggestion.canonical} not found for ${tool.displayName}; install the plugin or its native agent, then retry. Checked: ${paths.map((entry) => entry.path).join(", ")}.`
-    );
-  }
-}
diff --git a/cli/src/contexts/framework/domain/delegation.ts b/cli/src/contexts/framework/domain/delegation.ts
deleted file mode 100644
index 912984445..000000000
--- a/cli/src/contexts/framework/domain/delegation.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import { asPlainObject } from "../../../kernel/reading/plain-object.js";
-
-export interface DelegationSuggestion {
-  readonly plugin: string;
-  readonly role: string;
-  readonly canonical: string;
-  readonly requested: { readonly model?: string; readonly effort?: string };
-}
-
-export interface DelegationResolution {
-  readonly task: string;
-  readonly tool: string;
-  readonly configured: boolean;
-  readonly canonicalAgent?: string;
-  readonly agent?: {
-    readonly name: string;
-    readonly path: string;
-    readonly mode: "flat" | "marketplace";
-  };
-  readonly requested: DelegationSuggestion["requested"];
-  readonly native: Readonly<Record<string, string>>;
-  readonly nativeSurface: "agent-configuration" | "spawn";
-  readonly effectiveRuntime: "unknown";
-  readonly diagnostics: readonly string[];
-}
-
-function object(value: unknown, path: string): Record<string, unknown> {
-  const result = asPlainObject(value);
-  if (result === null) throw new Error(`${path}: expected a JSON object; correct this field.`);
-  return result;
-}
-
-function keys(value: Record<string, unknown>, allowed: readonly string[], path: string): void {
-  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
-  if (unexpected.length > 0)
-    throw new Error(
-      `${path}: unsupported field ${unexpected.join(", ")}; use ${allowed.join(", ")}.`
-    );
-}
-
-function setting(value: unknown, path: string): string | undefined {
-  if (value === undefined) return undefined;
-  if (
-    typeof value !== "string" ||
-    value.trim() !== value ||
-    value === "" ||
-    Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)
-  ) {
-    throw new Error(
-      `${path}: expected a nonempty string without surrounding whitespace; correct it or omit it to inherit.`
-    );
-  }
-  return value;
-}
-
-/** Validate the requested task/host only; unrelated configuration has no bearing on this query. */
-export function parseDelegation(
-  raw: string | null,
-  task: string,
-  tool: string,
-  file: string
-): DelegationSuggestion | undefined {
-  if (raw === null) return undefined;
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new Error(`${file}: expected valid JSON; repair the file before resolving delegation.`);
-  }
-  const root = object(parsed, file);
-  if (root.delegation === undefined) return undefined;
-  const delegation = object(root.delegation, `${file}: delegation`);
-  if (!Object.hasOwn(delegation, task)) return undefined;
-  const path = `${file}: delegation.${task}`;
-  const entry = object(delegation[task], path);
-  keys(entry, ["agent", "tools"], path);
-  if (
-    typeof entry.agent !== "string" ||
-    !/^[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(entry.agent)
-  ) {
-    throw new Error(
-      `${path}.agent: expected a canonical plugin:role address, for example aidd-dev:explorer.`
-    );
-  }
-  const colon = entry.agent.indexOf(":");
-  const plugin = entry.agent.slice(0, colon);
-  const role = entry.agent.slice(colon + 1);
-  let requested: DelegationSuggestion["requested"] = {};
-  if (entry.tools !== undefined) {
-    const tools = object(entry.tools, `${path}.tools`);
-    if (Object.hasOwn(tools, tool)) {
-      const selected = object(tools[tool], `${path}.tools.${tool}`);
-      keys(selected, ["model", "effort"], `${path}.tools.${tool}`);
-      const model = setting(selected.model, `${path}.tools.${tool}.model`);
-      const effort = setting(selected.effort, `${path}.tools.${tool}.effort`);
-      requested = {
-        ...(model === undefined ? {} : { model }),
-        ...(effort === undefined ? {} : { effort }),
-      };
-    }
-  }
-  return { plugin, role, canonical: entry.agent, requested };
-}
diff --git a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
index 241d696e2..a0651806f 100644
--- a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
+++ b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
@@ -21,6 +21,11 @@ function buildTomlContent(frontmatter: Record<string, unknown>, body: string): s
   if (frontmatter.model !== undefined) {
     lines.push(`model = ${tomlString(String(frontmatter.model))}`);
   }
+  if (frontmatter.model_reasoning_effort !== undefined) {
+    lines.push(
+      `model_reasoning_effort = ${tomlString(String(frontmatter.model_reasoning_effort))}`
+    );
+  }
   lines.push(`developer_instructions = """\n${body}\n"""`);
   return `${lines.join("\n")}\n`;
 }
@@ -51,27 +56,11 @@ export class AgentsCapability {
       directory: string;
       toolSuffix: string;
       format: "markdown" | "toml";
-      delegation?: {
-        personalAgentsFirst?: boolean;
-        userPath: (home: string, env: NodeJS.ProcessEnv, plugin: string, role: string) => string;
-        identity: (
-          name: string,
-          plugin: string,
-          mode: "flat" | "marketplace",
-          role: string
-        ) => string;
-        resolveNative: (
-          requested: { model?: string; effort?: string },
-          mode: "flat" | "marketplace"
-        ) => Readonly<Record<string, string>>;
-        readName?: (content: string) => string | undefined;
-        marketplacePath?: (root: string, role: string) => string;
-        nativeSurface?: (mode: "flat" | "marketplace") => "agent-configuration" | "spawn";
-        diagnostics?: (
-          content: string,
-          requested: { model?: string; effort?: string }
-        ) => readonly string[];
-      };
+      modelOptions?: (
+        fm: Record<string, unknown>,
+        plugin?: string,
+        fileName?: string
+      ) => Record<string, unknown>;
       userFileExt?: string;
       buildInstallPath?: (fileName: string) => string | null;
       convertFrontmatter?: (
@@ -104,15 +93,26 @@ export class AgentsCapability {
     return !otherSuffixes.some((s) => basename.endsWith(s));
   }
 
-  convertFrontmatter(fm: Record<string, unknown>, fileName?: string): Record<string, unknown> {
+  convertFrontmatter(
+    fm: Record<string, unknown>,
+    fileName?: string,
+    plugin?: string
+  ): Record<string, unknown> {
+    const converted = this.convertAgentFrontmatter(fm, fileName);
+    return { ...converted, ...this.params.modelOptions?.(fm, plugin, fileName) };
+  }
+
+  private convertAgentFrontmatter(
+    fm: Record<string, unknown>,
+    fileName?: string
+  ): Record<string, unknown> {
     if (this.params.convertFrontmatter) return this.params.convertFrontmatter(fm, fileName);
     const name = agentNameFromFrontmatter(fm, fileName);
-    if (this.params.format === "toml") {
-      const result: Record<string, unknown> = { name, description: fm.description };
-      if (fm.model !== undefined) result.model = fm.model;
-      return result;
-    }
-    return { name, description: fm.description };
+    return {
+      name,
+      description: fm.description,
+      ...(this.params.format === "toml" && fm.model !== undefined ? { model: fm.model } : {}),
+    };
   }
 
   serialize(frontmatter: Record<string, unknown>, body: string): string {
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.json b/cli/src/contexts/tools/domain/formats/agent-models.json
new file mode 100644
index 000000000..d766c0b3f
--- /dev/null
+++ b/cli/src/contexts/tools/domain/formats/agent-models.json
@@ -0,0 +1,43 @@
+{
+  "plugin": "aidd-dev",
+  "roles": ["explorer", "executor", "reviewer", "validator"],
+  "providers": {
+    "openai": {
+      "model": "gpt-6-luna",
+      "effort": "medium"
+    },
+    "anthropic": {
+      "model": "claude-haiku-5-5",
+      "effort": "medium",
+      "nativeModels": {
+        "copilot": "claude-haiku-5.5"
+      }
+    }
+  },
+  "tools": {
+    "claude": {
+      "provider": "anthropic",
+      "effortField": "effort"
+    },
+    "codex": {
+      "provider": "openai",
+      "effortField": "model_reasoning_effort"
+    },
+    "copilot": {
+      "provider": "openai",
+      "effortField": "reasoningEffort"
+    },
+    "opencode": {
+      "provider": "openai",
+      "effortPrefix": "#",
+      "effortSuffix": "",
+      "providerPrefix": true
+    },
+    "cursor": {
+      "provider": "anthropic",
+      "effortPrefix": "[effort=",
+      "effortSuffix": "]",
+      "marketplace": false
+    }
+  }
+}
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.ts b/cli/src/contexts/tools/domain/formats/agent-models.ts
new file mode 100644
index 000000000..a0cdda42b
--- /dev/null
+++ b/cli/src/contexts/tools/domain/formats/agent-models.ts
@@ -0,0 +1,45 @@
+import models from "./agent-models.json" with { type: "json" };
+
+type ModelHost = keyof typeof models.tools;
+
+/** Native agent fields shared by ordinary installation and build projections. */
+export function agentModelOptions(
+  host: ModelHost,
+  frontmatter: Record<string, unknown>,
+  plugin?: string,
+  fileName?: string,
+  mode: "flat" | "marketplace" = "flat",
+  configuration: typeof models = models
+): Record<string, unknown> {
+  const target = configuration.tools[host];
+  const native: Record<string, unknown> = {};
+  if (frontmatter.model !== undefined) native.model = frontmatter.model;
+  if ("effortField" in target && frontmatter[target.effortField] !== undefined)
+    native[target.effortField] = frontmatter[target.effortField];
+  if (frontmatter.model !== undefined) return native;
+  const role = fileName?.split("/").at(-1)?.replace(/\.md$/, "") ?? frontmatter.name;
+  if (
+    plugin !== configuration.plugin ||
+    typeof role !== "string" ||
+    !configuration.roles.includes(role)
+  )
+    return native;
+  if (mode === "marketplace" && "marketplace" in target && !target.marketplace) return native;
+  const provider = Object.entries(configuration.providers).find(
+    ([name]) => name === target.provider
+  )?.[1];
+  if (provider === undefined) throw new Error(`Unknown agent model provider: ${target.provider}`);
+  const nativeModel =
+    "nativeModels" in provider
+      ? (Object.entries(provider.nativeModels).find(([tool]) => tool === host)?.[1] ??
+        provider.model)
+      : provider.model;
+  const model = `${"providerPrefix" in target && target.providerPrefix ? `${target.provider}/` : ""}${nativeModel}`;
+  if ("effortField" in target) {
+    native.model = model;
+    native[target.effortField] ??= provider.effort;
+  } else {
+    native.model = `${model}${target.effortPrefix}${provider.effort}${target.effortSuffix}`;
+  }
+  return native;
+}
diff --git a/cli/src/contexts/tools/domain/formats/delegation-options.ts b/cli/src/contexts/tools/domain/formats/delegation-options.ts
deleted file mode 100644
index 3fa420519..000000000
--- a/cli/src/contexts/tools/domain/formats/delegation-options.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-/** Native suggestions carry only explicit project settings. Model identifiers stay literal. */
-export function nativeAgentOptions(
-  requested: { model?: string; effort?: string },
-  effortField: string,
-  efforts?: readonly string[]
-): Readonly<Record<string, string>> {
-  if (
-    requested.effort !== undefined &&
-    efforts !== undefined &&
-    !efforts.includes(requested.effort)
-  ) {
-    throw new Error(
-      `Unsupported effort "${requested.effort}"; use ${efforts.join(", ")} or omit effort to inherit.`
-    );
-  }
-  return {
-    ...(requested.model === undefined ? {} : { model: requested.model }),
-    ...(requested.effort === undefined ? {} : { [effortField]: requested.effort }),
-  };
-}
-
-/** Hosts whose model selector includes its effort need an explicit model to avoid guessing it. */
-export function embeddedAgentOptions(
-  requested: { model?: string; effort?: string },
-  embed: (model: string, effort: string) => string
-): Readonly<Record<string, string>> {
-  if (requested.effort === undefined)
-    return requested.model === undefined ? {} : { model: requested.model };
-  if (requested.model === undefined)
-    throw new Error(
-      "An explicit model is required with effort; set model or omit effort to inherit."
-    );
-  return { model: embed(requested.model, requested.effort) };
-}
diff --git a/cli/src/contexts/tools/domain/marketplace-catalog.ts b/cli/src/contexts/tools/domain/marketplace-catalog.ts
index 40afff08f..9e06378f5 100644
--- a/cli/src/contexts/tools/domain/marketplace-catalog.ts
+++ b/cli/src/contexts/tools/domain/marketplace-catalog.ts
@@ -25,12 +25,17 @@ type SrcEntry =
 
 /** Marketplace-mode agent transform shared by claude and copilot: the frontmatter is kept
  * untouched and only relative links are rewritten to the flattened output path. */
-export function transformClaudeAgent(content: string, _plugin: string, outName: string): string {
+export function transformClaudeAgent(
+  content: string,
+  _plugin: string,
+  outName: string,
+  modelOptions?: (fm: Record<string, unknown>) => Record<string, unknown>
+): string {
   const { frontmatter, body } = parseFrontmatter(content);
   const rewrittenBody = rewriteRelativeLinks(body, {
     currentFilePluginRelative: `agents/${outName}`,
   });
-  return serializeFrontmatter(frontmatter, rewrittenBody);
+  return serializeFrontmatter({ ...frontmatter, ...modelOptions?.(frontmatter) }, rewrittenBody);
 }
 
 export interface SynthesizeClaudeStyleManifestOpts {
diff --git a/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts b/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts
index 025e9b9cd..1c784225b 100644
--- a/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts
+++ b/cli/src/contexts/tools/domain/ports/host-plugin-registry-reader.ts
@@ -3,9 +3,8 @@ import type { MarketplaceScope } from "../../../../kernel/scope.js";
 /**
  * What a host's own plugin registry says, read from the file that host maintains itself.
  *
- * Installation diagnostics read host records; delegation additionally checks native artifact
- * paths and project activation settings. Readers use the `<plugin>@<marketplace>` refs their
- * hosts record. A host with no implementation is absent from the map, never assumed to agree.
+ * Readers use the `<plugin>@<marketplace>` refs their hosts record. A host with no reader
+ * is absent from the map, never assumed to agree.
  */
 /** What a registry says about one ref: whether the host records it enabled and, for a host
  * whose registry carries a per-entry scope (Claude), the scope of the entry that answers for
@@ -15,9 +14,6 @@ import type { MarketplaceScope } from "../../../../kernel/scope.js";
 export interface HostPluginRegistryEntry {
   readonly enabled: boolean;
   readonly scope?: MarketplaceScope;
-  /** Native plugin directory from the host's registration and documented layout. */
-  readonly installPath?: string;
-  readonly activationUnverified?: string;
 }
 
 export interface HostPluginRegistryReading {
@@ -35,7 +31,5 @@ export interface HostPluginRegistryReading {
 }
 
 export interface HostPluginRegistryReader {
-  /** Delegation includes artifact paths and project activation; the default retains installation
-   * diagnostic semantics. Neither mode establishes the effective runtime configuration. */
-  read(projectRoot: string, forDelegation?: boolean): Promise<HostPluginRegistryReading>;
+  read(projectRoot: string): Promise<HostPluginRegistryReading>;
 }
diff --git a/cli/src/contexts/tools/domain/profiles/claude/build.ts b/cli/src/contexts/tools/domain/profiles/claude/build.ts
index 7bcdb38f2..060026c48 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/build.ts
@@ -13,6 +13,7 @@ import {
 } from "../../../../../kernel/materialization/flat-paths.js";
 import { rewriteRelativeLinks } from "../../../../../kernel/materialization/relative-link-rewrite.js";
 import type { ToolBuildContract } from "../../build-contract.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { mergeClaudeSettingsHooks } from "../../formats/flat-hooks-merge.js";
 import { CLAUDE_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { mergeVscodeMcp } from "../../formats/vscode-mcp-merge.js";
@@ -52,7 +53,10 @@ export function buildClaudeContract(): ToolBuildContract {
         supported: true,
         source: { kind: "filteredTree", srcDir: "agents", inputExt: ".md" },
         path: (_p, rel) => rel,
-        transform: transformClaudeAgent,
+        transform: (content, plugin, outName) =>
+          transformClaudeAgent(content, plugin, outName, (fm) =>
+            agentModelOptions("claude", fm, plugin, outName, "marketplace")
+          ),
       },
       mcp: {
         supported: true,
@@ -108,7 +112,14 @@ function transformClaudeFlatAgent(content: string, plugin: string, outName: stri
     resolveTargetPath: (rel) => claudeFlatResolveTarget(plugin, rel),
   });
   const prefixedName = `${plugin}-${outName.replace(/\.md$/, "")}`;
-  return serializeFrontmatter({ ...frontmatter, name: prefixedName }, rewrittenBody);
+  return serializeFrontmatter(
+    {
+      ...frontmatter,
+      ...agentModelOptions("claude", frontmatter, plugin, outName),
+      name: prefixedName,
+    },
+    rewrittenBody
+  );
 }
 
 export function buildClaudeFlatContract(): ToolBuildContract {
diff --git a/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts b/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts
index a5281dc7f..676d62632 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/claude-paths.ts
@@ -7,11 +7,3 @@ export function claudeConfigDir(home: string, env: NodeJS.ProcessEnv): string {
 export function claudePluginsDir(home: string, env: NodeJS.ProcessEnv): string {
   return env.CLAUDE_CODE_PLUGIN_CACHE_DIR || join(claudeConfigDir(home, env), "plugins");
 }
-
-export function claudeSettingsPaths(configDir: string, projectRoot: string): readonly string[] {
-  return [
-    join(configDir, "settings.json"),
-    join(projectRoot, ".claude", "settings.json"),
-    join(projectRoot, ".claude", "settings.local.json"),
-  ];
-}
diff --git a/cli/src/contexts/tools/domain/profiles/claude/profile.ts b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
index a1e579112..c2223278d 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
@@ -15,13 +15,12 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { convertCommandFrontmatter, stripToolSuffix } from "../../formats/command.js";
-import { nativeAgentOptions } from "../../formats/delegation-options.js";
 import { CLAUDE_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { claudeStyleMarketplaceKey } from "../../marketplace-entry.js";
 import { registerTool } from "../../registry.js";
 import { buildClaudeContract, buildClaudeFlatContract } from "./build.js";
-import { claudeConfigDir } from "./claude-paths.js";
 
 const DIRECTORY = ".claude/";
 const TOOL_SUFFIX = ".claude.md";
@@ -50,14 +49,7 @@ export const claude: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
-        delegation: {
-          userPath: (home, env, plugin, role) =>
-            join(claudeConfigDir(home, env), "agents", `${plugin}-${role}.md`),
-          identity: (name, plugin, mode) => (mode === "marketplace" ? `${plugin}:${name}` : name),
-          resolveNative: (requested) =>
-            nativeAgentOptions(requested, "effort", ["low", "medium", "high", "xhigh", "max"]),
-          marketplacePath: (root, role) => join(root, "agents", `${role}.md`),
-        },
+        modelOptions: (fm, plugin, file) => agentModelOptions("claude", fm, plugin, file),
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts b/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
index 3ed7225db..6beee08c0 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
@@ -1,10 +1,11 @@
 import { parseFrontmatter } from "../../../../../kernel/markdown.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { stringifyToml } from "./toml.js";
 
 /**
  * Converts a Claude-format agent markdown file (frontmatter + body) into a Codex subagent TOML
  * string. Key insertion order is fixed for deterministic output, and the conversion is lossy —
- * no model field is emitted and the TOML schema diverges from the frontmatter, so there is no
+ * the TOML schema diverges from the frontmatter, so there is no
  * inverse.
  *
  * `prefixName` is for flat mode, where every plugin shares one `.codex/agents/` directory and
@@ -18,7 +19,11 @@ export function codexAgentMarkdownToToml(
 ): string {
   const { frontmatter, body } = parseFrontmatter(content);
   const name = resolveName(frontmatter, pluginName, fileBaseName, prefixName);
-  const obj = buildTomlObject(name, frontmatter, body);
+  const obj = buildTomlObject(
+    name,
+    { ...frontmatter, ...agentModelOptions("codex", frontmatter, pluginName, fileBaseName) },
+    body
+  );
   return stringifyToml(obj);
 }
 
@@ -44,7 +49,9 @@ function buildTomlObject(
   obj.name = name;
   // description is a required subagent key; default to "" when absent.
   obj.description = typeof frontmatter.description === "string" ? frontmatter.description : "";
-  // model is intentionally omitted: no known Codex model id set.
+  for (const field of ["model", "model_reasoning_effort"]) {
+    if (frontmatter[field] !== undefined) obj[field] = frontmatter[field];
+  }
   obj.developer_instructions = body;
   return obj;
 }
diff --git a/cli/src/contexts/tools/domain/profiles/codex/profile.ts b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
index 5fb46ec88..0396af7ac 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
@@ -17,12 +17,12 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import {
   buildAiddCommandFilePath,
   convertCommandFrontmatter,
   stripToolSuffix,
 } from "../../formats/command.js";
-import { nativeAgentOptions } from "../../formats/delegation-options.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { registerTool } from "../../registry.js";
 import {
@@ -31,7 +31,6 @@ import {
   mergeCodexConfigToml,
   stripCodexSkillFrontmatter,
 } from "./build.js";
-import { parseToml } from "./toml.js";
 
 const DIRECTORY = ".codex/";
 const TOOL_SUFFIX = ".codex.md";
@@ -144,29 +143,7 @@ export const codex: AiTool<
       directory: DIRECTORY,
       toolSuffix: TOOL_SUFFIX,
       format: "toml",
-      delegation: {
-        userPath: (home, env, plugin, role) =>
-          join(env.CODEX_HOME || join(home, ".codex"), "agents", `${plugin}-${role}.toml`),
-        identity: (name) => name,
-        resolveNative: (requested) => nativeAgentOptions(requested, "model_reasoning_effort"),
-        readName: (content) => {
-          const name = parseToml(content).name;
-          if (typeof name !== "string" || name.trim() === "")
-            throw new Error(
-              "Installed agent requires a nonempty TOML name; repair or reinstall its agent file."
-            );
-          return name;
-        },
-        diagnostics: (content, requested) => {
-          const pins = parseToml(content);
-          return Object.entries(nativeAgentOptions(requested, "model_reasoning_effort"))
-            .filter(([field, value]) => typeof pins[field] === "string" && pins[field] !== value)
-            .map(
-              ([field, value]) =>
-                `Installed agent pins ${field} to ${pins[field]}; update its agent configuration to ${value} before spawning. A spawn override may not replace this pin.`
-            );
-        },
-      },
+      modelOptions: (fm, plugin, file) => agentModelOptions("codex", fm, plugin, file),
     }),
     skills: new SkillsCapability({
       prefix: "aidd-",
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/build.ts b/cli/src/contexts/tools/domain/profiles/copilot/build.ts
index 80f4a536a..0cf41aae8 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/build.ts
@@ -14,6 +14,7 @@ import {
 import { rewriteRelativeLinks } from "../../../../../kernel/materialization/relative-link-rewrite.js";
 import type { ToolBuildContract } from "../../build-contract.js";
 import { stripAgentFrontmatter } from "../../formats/agent-frontmatter-strip.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { flattenCopilotHooksShape } from "../../formats/flat-hooks-merge.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { mergeVscodeMcp } from "../../formats/vscode-mcp-merge.js";
@@ -68,7 +69,10 @@ export function buildCopilotMarketplaceContract(): ToolBuildContract {
         supported: true,
         source: { kind: "filteredTree", srcDir: "agents", inputExt: ".md" },
         path: (_p, rel) => rel,
-        transform: transformClaudeAgent,
+        transform: (content, plugin, outName) =>
+          transformClaudeAgent(content, plugin, outName, (fm) =>
+            agentModelOptions("copilot", fm, plugin, outName, "marketplace")
+          ),
       },
       mcp: {
         supported: true,
@@ -135,7 +139,14 @@ function transformCopilotFlatAgent(content: string, plugin: string, outName: str
     resolveTargetPath: (rel) => copilotFlatResolveTarget(plugin, rel),
   });
   const prefixedName = `${plugin}-${outName.replace(/\.md$/, "")}`;
-  return serializeFrontmatter({ ...stripped, name: prefixedName }, rewrittenBody);
+  return serializeFrontmatter(
+    {
+      ...stripped,
+      ...agentModelOptions("copilot", frontmatter, plugin, outName),
+      name: prefixedName,
+    },
+    rewrittenBody
+  );
 }
 
 function copilotFlatResolveTarget(plugin: string, rel: string): string {
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts b/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts
index 2d7fd5dcb..e7b26aea5 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/copilot-paths.ts
@@ -9,38 +9,6 @@ export const COPILOT_WORKSPACE_DIR = ".github/";
 export const COPILOT_VSCODE_MCP_PATH = ".vscode/mcp.json";
 
 export const COPILOT_MARKETPLACE_RELATIVE = ".plugin/marketplace.json";
-export const COPILOT_MARKETPLACE_LOCATIONS = [
-  "marketplace.json",
-  COPILOT_MARKETPLACE_RELATIVE,
-  ".github/plugin/marketplace.json",
-  ".claude-plugin/marketplace.json",
-];
-
 export function copilotConfigDir(home: string, env: NodeJS.ProcessEnv): string {
   return env.COPILOT_HOME || join(home, ".copilot");
 }
-
-export function copilotSettingsPaths(
-  configDir: string,
-  projectRoot: string
-): readonly (readonly string[])[] {
-  return [
-    [join(configDir, "settings.json")],
-    [
-      join(projectRoot, ".claude", "settings.json"),
-      join(projectRoot, ".github", "copilot", "settings.json"),
-    ],
-    [
-      join(projectRoot, ".claude", "settings.local.json"),
-      join(projectRoot, ".github", "copilot", "settings.local.json"),
-    ],
-  ];
-}
-
-export function copilotInstalledPluginDir(
-  configDir: string,
-  marketplace: string,
-  plugin: string
-): string {
-  return join(configDir, "installed-plugins", marketplace, plugin);
-}
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
index df5d3d0bb..4e0c9a633 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
@@ -19,13 +19,13 @@ import type {
   HasSettings,
   HasSkills,
 } from "../../contracts.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { convertCommandFrontmatter } from "../../formats/command.js";
-import { nativeAgentOptions } from "../../formats/delegation-options.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { claudeStyleMarketplaceKey } from "../../marketplace-entry.js";
 import { registerTool } from "../../registry.js";
 import { buildCopilotFlatContract, buildCopilotMarketplaceContract } from "./build.js";
-import { COPILOT_WORKSPACE_DIR, copilotConfigDir } from "./copilot-paths.js";
+import { COPILOT_WORKSPACE_DIR } from "./copilot-paths.js";
 
 const DIRECTORY = COPILOT_WORKSPACE_DIR;
 const TOOL_SUFFIX = ".copilot.md";
@@ -226,24 +226,7 @@ export const copilot: AiTool<
       toolSuffix: EXT_AGENT,
       format: "markdown",
       userFileExt: EXT_AGENT,
-      delegation: {
-        userPath: (home, env, plugin, role) =>
-          join(copilotConfigDir(home, env), "agents", `${plugin}-${role}.agent.md`),
-        personalAgentsFirst: true,
-        identity: (_name, plugin, mode, role) =>
-          mode === "marketplace" ? `${plugin}:${role}` : `${plugin}-${role}`,
-        resolveNative: (requested) =>
-          nativeAgentOptions(requested, "reasoningEffort", [
-            "none",
-            "minimal",
-            "low",
-            "medium",
-            "high",
-            "xhigh",
-            "max",
-          ]),
-        marketplacePath: (root, role) => join(root, "agents", `${role}.md`),
-      },
+      modelOptions: (fm, plugin, file) => agentModelOptions("copilot", fm, plugin, file),
       buildInstallPath: (fileName) => agentsHandler.buildFilePath(fileName),
       convertFrontmatter: (fm, fileName) => agentsHandler.convertFrontmatter(fm, fileName),
     }),
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/build.ts b/cli/src/contexts/tools/domain/profiles/cursor/build.ts
index 441a1f10d..17ea5ed79 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/build.ts
@@ -14,6 +14,7 @@ import {
 import { rewriteRelativeLinks } from "../../../../../kernel/materialization/relative-link-rewrite.js";
 import type { ToolBuildContract } from "../../build-contract.js";
 import { stripCursorAgentFrontmatter } from "../../formats/agent-frontmatter-strip.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { mergeCursorFlatHooks } from "../../formats/flat-hooks-merge.js";
 import { CURSOR_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { mergeVscodeMcp } from "../../formats/vscode-mcp-merge.js";
@@ -118,7 +119,14 @@ function transformCursorFlatAgent(content: string, plugin: string, outName: stri
     resolveTargetPath: (rel) => cursorFlatResolveTarget(plugin, rel),
   });
   const prefixedName = `${plugin}-${outName.replace(/\.md$/, "")}`;
-  return serializeFrontmatter({ ...stripped, name: prefixedName }, rewrittenBody);
+  return serializeFrontmatter(
+    {
+      ...stripped,
+      ...agentModelOptions("cursor", frontmatter, plugin, outName),
+      name: prefixedName,
+    },
+    rewrittenBody
+  );
 }
 
 export function buildCursorFlatContract(): ToolBuildContract {
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
index fe6ae8447..d2d6d3e05 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
@@ -15,12 +15,12 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import {
   buildAiddCommandFilePath,
   convertCommandFrontmatter,
   stripToolSuffix,
 } from "../../formats/command.js";
-import { embeddedAgentOptions } from "../../formats/delegation-options.js";
 import { CURSOR_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { registerTool } from "../../registry.js";
 import { buildCursorContract, buildCursorFlatContract } from "./build.js";
@@ -53,74 +53,8 @@ export const cursor: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
-        delegation: {
-          userPath: (home, _env, plugin, role) =>
-            join(home, ".cursor", "agents", `${plugin}-${role}.md`),
-          identity: (name, plugin, mode, role) => {
-            const expected = `${plugin}-${role}`;
-            if (mode === "marketplace" && name !== expected)
-              throw new Error(
-                `Plugin agent ${name} has a collision-prone name; reinstall its translated plugin to obtain ${expected}.`
-              );
-            return name;
-          },
-          resolveNative: (requested, mode) => {
-            if (mode === "marketplace") {
-              if (requested.effort !== undefined)
-                throw new Error(
-                  "Cursor plugin spawn does not accept effort; choose an advertised model slug or omit effort to inherit."
-                );
-              return requested.model === undefined ? {} : { model: requested.model };
-            }
-            return embeddedAgentOptions(requested, (model, effort) => {
-              if (!/^[a-zA-Z0-9_.-]+$/.test(effort))
-                throw new Error(
-                  "Invalid effort option: use a model parameter value without spaces or brackets."
-                );
-              const open = model.indexOf("[");
-              const malformed = () =>
-                new Error(
-                  "Malformed model option group: use one [key=value,...] group with unique keys before specifying effort."
-                );
-              if (open === -1) {
-                if (model.includes("]")) throw malformed();
-                return `${model}[effort=${effort}]`;
-              }
-              if (
-                open === 0 ||
-                model.indexOf("[", open + 1) !== -1 ||
-                model.indexOf("]") !== model.length - 1
-              )
-                throw malformed();
-              const keys = new Set<string>();
-              let selectedEffort: string | undefined;
-              for (const option of model.slice(open + 1, -1).split(",")) {
-                const equals = option.indexOf("=");
-                const key = option.slice(0, equals);
-                const value = option.slice(equals + 1);
-                if (
-                  equals < 1 ||
-                  value === "" ||
-                  value.includes("=") ||
-                  /\s/.test(option) ||
-                  keys.has(key)
-                )
-                  throw malformed();
-                keys.add(key);
-                if (key === "effort") selectedEffort = value;
-              }
-              if (selectedEffort !== undefined) {
-                if (selectedEffort === effort) return model;
-                throw new Error(
-                  "Conflicting model effort option: remove [effort=...] before specifying a different effort."
-                );
-              }
-              return `${model.slice(0, -1)},effort=${effort}]`;
-            });
-          },
-          marketplacePath: (root, role) => join(root, "agents", `${role}.md`),
-          nativeSurface: (mode) => (mode === "marketplace" ? "spawn" : "agent-configuration"),
-        },
+        modelOptions: (fm, plugin, file) =>
+          agentModelOptions("cursor", fm, plugin, file, "marketplace"),
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/opencode/build.ts b/cli/src/contexts/tools/domain/profiles/opencode/build.ts
index c3c7d31be..eb388261b 100644
--- a/cli/src/contexts/tools/domain/profiles/opencode/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/opencode/build.ts
@@ -16,6 +16,7 @@ import { rewriteRelativeLinks } from "../../../../../kernel/materialization/rela
 import type { FileReader } from "../../../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../../../kernel/ports/file-writer.js";
 import type { ArtifactContract, ToolBuildContract } from "../../build-contract.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import { buildOpencodeFlatConfig } from "../../formats/opencode-mcp-merge.js";
 import { generateOpencodeHooksBridge } from "./opencode-hooks-bridge.js";
 import {
@@ -135,7 +136,12 @@ function transformOpencodeFlatAgent(content: string, plugin: string, outName: st
   const prefixedName = `${plugin}-${outName.replace(/\.md$/, "")}`;
   // mode: subagent ensures opencode treats copied agents as subagents, not primary agents.
   return serializeFrontmatter(
-    { ...frontmatter, name: prefixedName, mode: "subagent" },
+    {
+      ...frontmatter,
+      ...agentModelOptions("opencode", frontmatter, plugin, outName),
+      name: prefixedName,
+      mode: "subagent",
+    },
     rewrittenBody
   );
 }
diff --git a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
index 9b17679c8..9e266863d 100644
--- a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
@@ -16,12 +16,12 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
+import { agentModelOptions } from "../../formats/agent-models.js";
 import {
   buildAiddCommandFilePath,
   convertCommandFrontmatterNoHint,
   stripToolSuffix,
 } from "../../formats/command.js";
-import { embeddedAgentOptions } from "../../formats/delegation-options.js";
 import { registerTool } from "../../registry.js";
 import { buildOpencodeFlatContract, transformMcpToOpencode } from "./build.js";
 import { generateOpencodeHooksBridge } from "./opencode-hooks-bridge.js";
@@ -59,30 +59,7 @@ export const opencode: AiTool<
       directory: DIRECTORY,
       toolSuffix: TOOL_SUFFIX,
       format: "markdown",
-      delegation: {
-        userPath: (home, env, plugin, role) =>
-          join(
-            env.XDG_CONFIG_HOME || join(home, ".config"),
-            "opencode",
-            "agents",
-            `${plugin}-${role}.md`
-          ),
-        identity: (_name, plugin, _mode, role) => `${plugin}-${role}`,
-        resolveNative: (requested) =>
-          embeddedAgentOptions(requested, (model, effort) => {
-            if (!/^[a-zA-Z0-9_.-]+$/.test(effort))
-              throw new Error(
-                "Invalid effort variant: use a variant selector without spaces or #."
-              );
-            if (model.includes("#")) {
-              if (model.slice(model.lastIndexOf("#") + 1) === effort) return model;
-              throw new Error(
-                "Conflicting model variant: remove the model #suffix before specifying a different effort."
-              );
-            }
-            return `${model}#${effort}`;
-          }),
-      },
+      modelOptions: (fm, plugin, file) => agentModelOptions("opencode", fm, plugin, file),
       convertFrontmatter: (fm) => ({ description: fm.description, mode: "subagent" }),
     }),
     skills: new SkillsCapability({
diff --git a/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts b/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts
index d908f6fbf..0a789d538 100644
--- a/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts
+++ b/cli/src/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.ts
@@ -1,10 +1,7 @@
 import { readFile, realpath } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { isDeepStrictEqual } from "node:util";
+import { join } from "node:path";
 import { describeError } from "../../../kernel/describe-error.js";
 import { resolveHomeDir } from "../../../kernel/reading/home-dir.js";
-import { stripJsonComments } from "../../../kernel/reading/jsonc.js";
-import { asPlainObject } from "../../../kernel/reading/plain-object.js";
 import type { MarketplaceScope } from "../../../kernel/scope.js";
 import type { AiToolId } from "../../../kernel/tool.js";
 import type {
@@ -12,17 +9,8 @@ import type {
   HostPluginRegistryReader,
   HostPluginRegistryReading,
 } from "../domain/ports/host-plugin-registry-reader.js";
-import {
-  claudeConfigDir,
-  claudePluginsDir,
-  claudeSettingsPaths,
-} from "../domain/profiles/claude/claude-paths.js";
-import {
-  COPILOT_MARKETPLACE_LOCATIONS,
-  copilotConfigDir,
-  copilotInstalledPluginDir,
-  copilotSettingsPaths,
-} from "../domain/profiles/copilot/copilot-paths.js";
+import { claudePluginsDir } from "../domain/profiles/claude/claude-paths.js";
+import { copilotConfigDir } from "../domain/profiles/copilot/copilot-paths.js";
 
 function failedRead(location: string, error: unknown): HostPluginRegistryReading {
   if (error instanceof Error && "code" in error && error.code === "ENOENT")
@@ -50,10 +38,7 @@ export function hostPluginRegistryReaders(
   return new Map<AiToolId, HostPluginRegistryReader>([
     [
       "claude",
-      new ClaudeInstalledPluginsReader(
-        join(claudePluginsDir(home, env), "installed_plugins.json"),
-        claudeConfigDir(home, env)
-      ),
+      new ClaudeInstalledPluginsReader(join(claudePluginsDir(home, env), "installed_plugins.json")),
     ],
     ["codex", new CodexConfigPluginsReader(join(home, ".codex", "config.toml"))],
     [
@@ -71,12 +56,9 @@ export function hostPluginRegistryReaders(
  * one.
  */
 class ClaudeInstalledPluginsReader implements HostPluginRegistryReader {
-  constructor(
-    private readonly path: string,
-    private readonly configDir: string
-  ) {}
+  constructor(private readonly path: string) {}
 
-  async read(projectRoot: string, forDelegation = false): Promise<HostPluginRegistryReading> {
+  async read(projectRoot: string): Promise<HostPluginRegistryReading> {
     let content: string;
     try {
       content = await readFile(this.path, "utf8");
@@ -90,28 +72,11 @@ class ClaudeInstalledPluginsReader implements HostPluginRegistryReader {
         return { location: this.path, unreadable: "no `plugins` object" };
       }
       const refs = new Map<string, HostPluginRegistryEntry>();
-      const activation = forDelegation
-        ? await enabledPluginsAt(claudeSettingsPaths(this.configDir, projectRoot))
-        : undefined;
       const here = await resolvedPath(projectRoot);
       for (const [ref, entries] of Object.entries(plugins)) {
         const scope = await scopeForProject(entries, here);
         if (scope !== null) {
-          const local = await projectEntry(entries, here);
-          const installPath =
-            local?.installPath ?? entries.find((entry) => entry.scope === "user")?.installPath;
-          refs.set(ref, {
-            enabled:
-              typeof activation?.get(ref) === "boolean" ? activation.get(ref) === true : true,
-            scope,
-            ...(typeof installPath === "string" ? { installPath } : {}),
-            ...(activation !== undefined && typeof activation.get(ref) !== "boolean"
-              ? {
-                  activationUnverified:
-                    "Local enabledPlugins settings do not establish activation; enable this plugin in Claude before resolving its agent.",
-                }
-              : {}),
-          });
+          refs.set(ref, { enabled: true, scope });
         }
       }
       return { location: this.path, refs };
@@ -147,71 +112,19 @@ class CodexConfigPluginsReader implements HostPluginRegistryReader {
 
 /**
  * Copilot's own registry: `enabledPlugins` in `~/.copilot/settings.json`, keyed on the same
- * `<plugin>@<marketplace>` ref as every other host and carrying a boolean. Installation
- * diagnostics retain the user registry; delegation also applies repository activation.
+ * `<plugin>@<marketplace>` ref as every other host and carrying a boolean. It answers the user registry; project activation is owned by the native host.
  */
 class CopilotSettingsPluginsReader implements HostPluginRegistryReader {
   constructor(private readonly path: string) {}
 
-  async read(projectRoot: string, forDelegation = false): Promise<HostPluginRegistryReading> {
+  async read(_projectRoot: string): Promise<HostPluginRegistryReading> {
     try {
-      const parsed = (
-        forDelegation
-          ? await copilotSettingsAt(copilotSettingsPaths(dirname(this.path), projectRoot))
-          : JSON.parse(await readFile(this.path, "utf8"))
-      ) as {
+      const parsed = JSON.parse(await readFile(this.path, "utf8")) as {
         enabledPlugins?: Record<string, unknown>;
-        extraKnownMarketplaces?: Record<string, unknown>;
-      } | null;
-      if (parsed === null) return { location: this.path, absent: true };
-      const enabled = parsed.enabledPlugins;
-      // Absent is a real answer here, unlike a file that would not open: Copilot writes the
-      // key on its first install, so a settings file without one carries no plugin.
-      if (enabled === undefined) return { location: this.path, refs: new Map() };
+      };
       const refs = new Map<string, HostPluginRegistryEntry>();
-      for (const [ref, on] of Object.entries(enabled)) {
-        if (forDelegation && typeof on !== "boolean")
-          throw new Error(
-            `${this.path}: enabledPlugins.${ref} must be a boolean; repair this field.`
-          );
-        const at = ref.lastIndexOf("@");
-        const registration = asPlainObject(parsed.extraKnownMarketplaces?.[ref.slice(at + 1)]);
-        const source = asPlainObject(registration?.source);
-        let installPath =
-          forDelegation && on === true && at > 0
-            ? copilotInstalledPluginDir(dirname(this.path), ref.slice(at + 1), ref.slice(0, at))
-            : undefined;
-        if (
-          forDelegation &&
-          on !== false &&
-          source?.source === "directory" &&
-          typeof source.path === "string"
-        ) {
-          let catalog: Record<string, unknown> | null = null;
-          for (const relative of COPILOT_MARKETPLACE_LOCATIONS) {
-            catalog = await readObjectIfPresent(join(source.path, relative));
-            if (catalog !== null) break;
-          }
-          if (catalog === null)
-            throw new Error(
-              `${source.path}: no supported marketplace catalogue; repair its native registration.`
-            );
-          const plugin = Array.isArray(catalog.plugins)
-            ? catalog.plugins.map(asPlainObject).find((entry) => entry?.name === ref.slice(0, at))
-            : undefined;
-          if (typeof plugin?.source === "string") {
-            const pluginRoot = asPlainObject(catalog.metadata)?.pluginRoot;
-            if (pluginRoot !== undefined && (typeof pluginRoot !== "string" || pluginRoot === ""))
-              throw new Error(
-                `${source.path}: metadata.pluginRoot must be a nonempty string; repair the catalogue.`
-              );
-            installPath = join(source.path, pluginRoot ?? ".", plugin.source);
-          }
-        }
-        refs.set(ref, {
-          enabled: on !== false,
-          ...(installPath === undefined ? {} : { installPath }),
-        });
+      for (const [ref, enabled] of Object.entries(parsed.enabledPlugins ?? {})) {
+        refs.set(ref, { enabled: enabled !== false });
       }
       return { location: this.path, refs };
     } catch (error) {
@@ -220,85 +133,6 @@ class CopilotSettingsPluginsReader implements HostPluginRegistryReader {
   }
 }
 
-async function copilotSettingsAt(
-  paths: readonly (readonly string[])[]
-): Promise<Record<string, unknown> | null> {
-  const scopes = await Promise.all(
-    paths.map((scope) =>
-      Promise.all(
-        scope.map(async (path) => ({ path, source: await readObjectIfPresent(path, true) }))
-      )
-    )
-  );
-  if (scopes.every((scope) => scope.every(({ source }) => source === null))) return null;
-  const enabledPlugins = new Map<string, unknown>();
-  const extraKnownMarketplaces = new Map<string, unknown>();
-  const conflicts = new Map<string, string>();
-  for (const scope of scopes) {
-    const seen = new Map<string, { path: string; value: unknown }>();
-    for (const { path, source } of scope) {
-      for (const [key, target] of Object.entries({ enabledPlugins, extraKnownMarketplaces })) {
-        if (source?.[key] === undefined) continue;
-        const entries = asPlainObject(source[key]);
-        if (entries === null)
-          throw new Error(`${path}: ${key} must be an object; repair this field.`);
-        for (const [ref, value] of Object.entries(entries)) {
-          const address = `${key}.${ref}`;
-          const previous = seen.get(address);
-          if (previous === undefined) conflicts.delete(address);
-          else if (!isDeepStrictEqual(previous.value, value))
-            conflicts.set(
-              address,
-              `${previous.path} and ${path}: conflicting ${address}; align these values before resolving delegation.`
-            );
-          seen.set(address, { path, value });
-          target.set(ref, value);
-        }
-      }
-    }
-  }
-  if (conflicts.size > 0) throw new Error([...conflicts.values()].join(" "));
-  return {
-    enabledPlugins: Object.fromEntries(enabledPlugins),
-    extraKnownMarketplaces: Object.fromEntries(extraKnownMarketplaces),
-  };
-}
-
-async function readObjectIfPresent(
-  path: string,
-  jsonc = false
-): Promise<Record<string, unknown> | null> {
-  let raw: string;
-  try {
-    raw = await readFile(path, "utf8");
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
-    throw error;
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(jsonc ? stripJsonComments(raw) : raw);
-  } catch {
-    throw new Error(`${path}: invalid JSON; repair this settings or catalogue file.`);
-  }
-  const object = asPlainObject(parsed);
-  if (object === null) throw new Error(`${path}: expected a JSON object; repair this file.`);
-  return object;
-}
-
-async function enabledPluginsAt(paths: readonly string[]): Promise<ReadonlyMap<string, unknown>> {
-  const sources = await Promise.all(paths.map((path) => readObjectIfPresent(path)));
-  const result = new Map<string, unknown>();
-  for (const [index, source] of sources.entries()) {
-    if (source?.enabledPlugins === undefined) continue;
-    const entries = asPlainObject(source.enabledPlugins);
-    if (entries === null)
-      throw new Error(`${paths[index]}: enabledPlugins must be an object; repair this field.`);
-    for (const [ref, enabled] of Object.entries(entries)) result.set(ref, enabled);
-  }
-  return result;
-}
-
 const CODEX_PLUGIN_HEADER = /^\[plugins\."(.+?)"\]\s*(?:#.*)?$/u;
 const CODEX_TABLE_HEADER = /^\[/u;
 const CODEX_ENABLED_LINE = /^enabled\s*=\s*(true|false)\s*(?:#.*)?$/u;
@@ -365,7 +199,6 @@ function enabledInTableBody(lines: readonly (string | null)[], from: number): bo
 interface ClaudeEntry {
   readonly scope?: string;
   readonly projectPath?: string;
-  readonly installPath?: string;
 }
 
 async function projectEntry(
diff --git a/cli/src/contexts/translate/domain/content-translator.ts b/cli/src/contexts/translate/domain/content-translator.ts
index bcd8b9c9f..a2665895b 100644
--- a/cli/src/contexts/translate/domain/content-translator.ts
+++ b/cli/src/contexts/translate/domain/content-translator.ts
@@ -40,7 +40,11 @@ interface TranslatedFile {
 
 interface MarkdownCap {
   buildInstallPath: (fileName: string) => string | null;
-  convertFrontmatter: (fm: Record<string, unknown>, fileName: string) => Record<string, unknown>;
+  convertFrontmatter: (
+    fm: Record<string, unknown>,
+    fileName: string,
+    plugin?: string
+  ) => Record<string, unknown>;
   serialize: (fm: Record<string, unknown>, body: string) => string;
 }
 
@@ -137,7 +141,7 @@ export class PluginContentTranslator {
     const result: InstallationFile[] = [];
     const componentPaths = new Map<string, string>();
     for (const file of dist.files) {
-      const translated = this.translateFile(file, tool);
+      const translated = this.translateFile(file, tool, dist.manifest.name);
       if (translated === null) continue;
       const hooked = this.maybeConvertHooks(file.relativePath, translated.content, tool);
       // Prose is rewritten, an artefact is carried byte for byte: a tool's own rewrite leaving
@@ -202,7 +206,8 @@ export class PluginContentTranslator {
 
   private translateFile(
     file: PluginComponentFile,
-    tool: AiTool<HasPlugins>
+    tool: AiTool<HasPlugins>,
+    plugin: string
   ): TranslatedFile | null {
     if (PLUGIN_MANIFEST_PATHS.includes(file.relativePath)) return null;
     const cap = tool.capabilities.plugins;
@@ -224,19 +229,20 @@ export class PluginContentTranslator {
         verbatim: true,
       };
     }
-    return this.translateComponent(file, tool);
+    return this.translateComponent(file, tool, plugin);
   }
 
   private translateComponent(
     file: PluginComponentFile,
-    tool: AiTool<HasPlugins>
+    tool: AiTool<HasPlugins>,
+    plugin: string
   ): TranslatedFile | null {
     const top = file.relativePath.split("/")[0];
     if (top === "commands" && hasCommands(tool)) {
       return translateMarkdown(file, "commands/", tool.directory, tool.capabilities.commands);
     }
     if (top === "agents" && hasAgents(tool)) {
-      return translateMarkdown(file, "agents/", tool.directory, tool.capabilities.agents);
+      return translateMarkdown(file, "agents/", tool.directory, tool.capabilities.agents, plugin);
     }
     if (top === "rules" && hasRules(tool)) {
       return translateMarkdown(file, "rules/", tool.directory, tool.capabilities.rules);
@@ -349,6 +355,19 @@ export class PluginContentTranslator {
     // Same rule as the native path: prose is rewritten, an artefact is carried. Rewriting every
     // flat file left a script intact only where a tool's own rewrite happened to spare it.
     const content = isProse(file.relativePath) ? tool.rewriteContent(file.content) : file.content;
+    if (
+      section === "agents" &&
+      hasAgents(tool) &&
+      tool.capabilities.agents.params.modelOptions !== undefined
+    ) {
+      const artifact = tool.buildContracts?.flat?.().artifacts.agents;
+      if (artifact?.supported) {
+        return this.makeFile(
+          artifact.path(pluginName, file.relativePath),
+          artifact.transform?.(content, pluginName, fileName) ?? content
+        );
+      }
+    }
     return this.makeFile(`${tool.directory}${section}/${pluginName}/${fileName}`, content);
   }
 
@@ -442,14 +461,15 @@ function translateMarkdown(
   file: PluginComponentFile,
   sectionDir: string,
   toolDirectory: string,
-  cap: MarkdownCap
+  cap: MarkdownCap,
+  plugin?: string
 ): TranslatedFile | null {
   const fileName = file.relativePath.slice(sectionDir.length);
   const fullPath = cap.buildInstallPath(fileName);
   if (fullPath === null) return null;
   const relativePath = toPluginRelativePath(fullPath, toolDirectory);
   const { frontmatter, body } = parseFrontmatter(file.content);
-  const newFm = cap.convertFrontmatter(frontmatter, fileName);
+  const newFm = cap.convertFrontmatter(frontmatter, fileName, plugin);
   const content = cap.serialize(newFm, body);
   return { relativePath, content };
 }
diff --git a/cli/src/presentation/commands/delegation.ts b/cli/src/presentation/commands/delegation.ts
deleted file mode 100644
index e8ee77dcb..000000000
--- a/cli/src/presentation/commands/delegation.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import type { Command } from "commander";
-import { resolveHomeDir } from "../../kernel/reading/home-dir.js";
-import { createDeps } from "../../runtime/wiring/framework.js";
-import { ErrorHandler } from "../error-handler.js";
-import { parseGlobalOptions } from "./global-options.js";
-
-export function registerDelegationCommand(program: Command): void {
-  program
-    .command("delegation")
-    .description("Read this project's delegation suggestions")
-    .command("resolve <task>")
-    .description("Resolve a configured role and native options against an installed agent")
-    .requiredOption("--tool <id>", "AI tool whose installed agent and native options to resolve")
-    .option("--json", "Print the resolution as JSON")
-    .action(async (task: string, options: { tool: string; json?: boolean }) => {
-      const { projectRoot, verbose, output } = parseGlobalOptions(program);
-      try {
-        const deps = await createDeps(projectRoot, { verbose }, output);
-        const result = await deps.resolveDelegationUseCase.execute({
-          projectRoot,
-          home: resolveHomeDir(),
-          env: process.env,
-          task,
-          tool: options.tool,
-        });
-        if (options.json) output.print(JSON.stringify(result, null, 2));
-        else {
-          if (result.agent === undefined)
-            output.print(
-              `No configured suggestion for ${task}; the caller keeps its role and native settings.`
-            );
-          else {
-            output.print(`Agent: ${result.agent.name} (${result.agent.path})`);
-            output.print(`Requested: ${JSON.stringify(result.requested)}`);
-            output.print(
-              `Native suggestion (${result.nativeSurface}): ${JSON.stringify(result.native)}`
-            );
-            for (const diagnostic of result.diagnostics) output.warn(diagnostic);
-          }
-          output.print("Unspecified settings inherit. Effective runtime: unknown.");
-        }
-      } catch (error) {
-        new ErrorHandler(output).handle(error);
-      }
-    });
-}
diff --git a/cli/src/runtime/wiring/framework.ts b/cli/src/runtime/wiring/framework.ts
index aaf992e3f..59ce0367e 100644
--- a/cli/src/runtime/wiring/framework.ts
+++ b/cli/src/runtime/wiring/framework.ts
@@ -50,7 +50,6 @@ import { PluginRemoveUseCase } from "../../contexts/framework/application/plugin
 import { PluginSearchUseCase } from "../../contexts/framework/application/plugin/plugin-search-use-case.js";
 import { PluginUpdateUseCase } from "../../contexts/framework/application/plugin/plugin-update-use-case.js";
 import { ValidateRecipesUseCase } from "../../contexts/framework/application/recipes/validate-recipes-use-case.js";
-import { ResolveDelegationUseCase } from "../../contexts/framework/application/resolve-delegation-use-case.js";
 import { RestoreUseCase } from "../../contexts/framework/application/restore/restore-use-case.js";
 import { ProjectContextDetectorUseCase } from "../../contexts/framework/application/setup/project-context-detector-use-case.js";
 import { SetupMachineScopeUseCase } from "../../contexts/framework/application/setup/setup-machine-scope-use-case.js";
@@ -127,7 +126,6 @@ interface GlobalOptions {
 }
 
 interface Deps {
-  resolveDelegationUseCase: ResolveDelegationUseCase;
   fs: FileReader & FileWriter & FileMerger;
   manifestRepo: ManifestRepository;
   /** `--scope user`'s own manifest repository: `userConfigDir()/manifest.json`, never nested
@@ -591,7 +589,6 @@ export async function createDeps(
   const listInstalledRulesUseCase = new ListInstalledRulesUseCase(fs);
   const checkUpdateUseCase = new CheckUpdateUseCase(cliUpdater, currentVersionProvider, logger, fs);
   const deps: Deps = {
-    resolveDelegationUseCase: new ResolveDelegationUseCase(fs, manifestRepo, hostPluginRegistries),
     validateRecipesUseCase: new ValidateRecipesUseCase(new RecipeFilesAdapter()),
     fs,
     manifestRepo,
diff --git a/cli/tests/architecture/folder-size.arch.test.ts b/cli/tests/architecture/folder-size.arch.test.ts
index d01cc15ea..4600362bd 100644
--- a/cli/tests/architecture/folder-size.arch.test.ts
+++ b/cli/tests/architecture/folder-size.arch.test.ts
@@ -13,10 +13,10 @@ const MAX_FILES_PER_FOLDER = 10;
  * files are shuffled. The test asserts the count, so a reason nobody measured fails here.
  */
 const BASELINE: readonly { readonly path: string; readonly count: number }[] = [
-  // Thirteen files carry the command surface, including read-only delegation resolution,
-  // plus three helpers no other folder imports. One module per command keeps that mapping
-  // direct; moving helpers out would leave thirteen and clarify nothing.
-  { path: "src/presentation/commands", count: 16 },
+  // Eleven files carry the command surface, plus three helpers no other folder imports. That
+  // is the flattest mapping from the CLI's surface to its source; moving the helpers out
+  // would leave eleven, still over the limit and clearer about nothing.
+  { path: "src/presentation/commands", count: 15 },
   // One display module per command, mirroring `presentation/commands/`: that mirror is what
   // lets a command's rendering be asserted without running the binary. Fewer files would mean
   // one module rendering several commands, which is what put the printing in the actions.
@@ -26,9 +26,9 @@ const BASELINE: readonly { readonly path: string; readonly count: number }[] = [
   // not, and moving one out to make room is the shuffle this rule refuses.
   { path: "src/contexts/tools/domain", count: 11 },
 
-  // Migration drift and project delegation are distinct framework vocabularies.
-  // Neither belongs in tools; a single-file folder would add no boundary.
-  { path: "src/contexts/framework/domain", count: 12 },
+  // `marketplace-source-drift.ts` decides a version/migration drift, a fact about aidd's own
+  // migration: that concern belongs to `framework`, not `tools`.
+  { path: "src/contexts/framework/domain", count: 11 },
 
   // Four native-cache and host-CLI helpers are shared by `clean` at project and machine scope
   // both, which is what `earned-sharing.arch.test.ts` means by earned; a `clean/`-only home
diff --git a/cli/tests/contexts/framework/application/framework/translator/install-plugin-opencode-mode-b.integration.test.ts b/cli/tests/contexts/framework/application/framework/translator/install-plugin-opencode-mode-b.integration.test.ts
index f89233b76..98e7bfefa 100644
--- a/cli/tests/contexts/framework/application/framework/translator/install-plugin-opencode-mode-b.integration.test.ts
+++ b/cli/tests/contexts/framework/application/framework/translator/install-plugin-opencode-mode-b.integration.test.ts
@@ -1,5 +1,5 @@
 // OpenCode uses Mode B with `mode: "flat"` and project scope, so `translateFlat` writes at
-// `.opencode/<section>/<plugin>/<file>`, never under one `.opencode/plugins/<name>/` root.
+// section-specific native paths, never under one `.opencode/plugins/<name>/` root.
 import "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
 import { describe, expect, it } from "vitest";
 import { ModeBFlatMaterializationTranslator } from "../../../../../../src/contexts/framework/application/framework/translator/mode-b-flat-materialization-translator.js";
@@ -39,7 +39,7 @@ function buildDist(name = "aidd-context"): PluginDistribution {
 }
 
 describe("install opencode plugin via Mode B (integration)", () => {
-  it("materializes flat plugin files under .opencode/<section>/<plugin>/ at projectRoot", async () => {
+  it("materializes project commands and namespaced native agents", async () => {
     const fs = new InMemoryFileAdapter();
     const hasher = new DeterministicHasher();
     const adapter = new ModeBFlatMaterializationTranslator(fs, hasher, () => STUB_HOME);
@@ -59,9 +59,7 @@ describe("install opencode plugin via Mode B (integration)", () => {
     expect(
       written.some((p) => p.startsWith(`${PROJECT_ROOT}/.opencode/commands/aidd-context/`))
     ).toBe(true);
-    expect(
-      written.some((p) => p.startsWith(`${PROJECT_ROOT}/.opencode/agents/aidd-context/`))
-    ).toBe(true);
+    expect(written).toContain(`${PROJECT_ROOT}/.opencode/agents/aidd-context-coach.md`);
   });
 
   it("does not write any file under user home for project-scope flat tools", async () => {
diff --git a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts b/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
deleted file mode 100644
index 91ca91778..000000000
--- a/cli/tests/contexts/framework/application/resolve-delegation-use-case.unit.test.ts
+++ /dev/null
@@ -1,473 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import "../../../../src/runtime/wiring/tools.js";
-import { ResolveDelegationUseCase } from "../../../../src/contexts/framework/application/resolve-delegation-use-case.js";
-import { FakeHostPluginRegistryReader } from "../../../helpers/ports/fake-host-plugin-registry-reader.js";
-import { InMemoryFileAdapter } from "../../../helpers/ports/in-memory-file-adapter.js";
-import { InMemoryManifestRepository } from "../../../helpers/ports/in-memory-manifest-repository.js";
-
-const ROOT = "/repo";
-const HOME = "/person";
-const CONFIG = join(ROOT, ".aidd", "config.json");
-
-function setup(tool: string, settings: Record<string, string> = {}) {
-  const raw = JSON.stringify({
-    telemetry: { enabled: true },
-    custom: { keep: 1 },
-    delegation: { exploration: { agent: "aidd-dev:explorer", tools: { [tool]: settings } } },
-  });
-  const fs = new InMemoryFileAdapter({ [CONFIG]: raw });
-  const repo = new InMemoryManifestRepository(null, ROOT);
-  const useCase = new ResolveDelegationUseCase(fs, repo, new Map());
-  return {
-    fs,
-    repo,
-    raw,
-    resolve: () =>
-      useCase.execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool }),
-  };
-}
-
-describe("resolving an installed delegation suggestion", () => {
-  it("returns no suggestion when the task is absent without writing configuration", async () => {
-    const fs = new InMemoryFileAdapter();
-    const useCase = new ResolveDelegationUseCase(fs, new InMemoryManifestRepository(), new Map());
-    const result = await useCase.execute({
-      projectRoot: ROOT,
-      home: HOME,
-      env: {},
-      task: "exploration",
-      tool: "codex",
-    });
-    expect(result).toMatchObject({
-      configured: false,
-      requested: {},
-      native: {},
-      effectiveRuntime: "unknown",
-    });
-    expect(await fs.fileExists(CONFIG)).toBe(false);
-  });
-
-  it("preserves a registered unsupported host's existing behavior when no task is configured", async () => {
-    const fs = new InMemoryFileAdapter();
-    const useCase = new ResolveDelegationUseCase(fs, new InMemoryManifestRepository(), new Map());
-    const result = await useCase.execute({
-      projectRoot: ROOT,
-      home: HOME,
-      env: {},
-      task: "exploration",
-      tool: "kilo",
-    });
-    expect(result).toMatchObject({ configured: false, requested: {}, native: {} });
-    expect(await fs.fileExists(CONFIG)).toBe(false);
-  });
-
-  it.each([
-    [
-      "codex",
-      ".codex/agents/aidd-dev-explorer.toml",
-      'name = "aidd-dev-explorer"\ndescription = "Explore"\ndeveloper_instructions = "Body"',
-      "model_reasoning_effort",
-    ],
-    [
-      "claude",
-      ".claude/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\ndescription: Explore\n---\nBody",
-      "effort",
-    ],
-    [
-      "opencode",
-      ".opencode/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\nmode: subagent\n---\nBody",
-      "variant",
-    ],
-    [
-      "copilot",
-      ".github/agents/aidd-dev-explorer.agent.md",
-      "---\nname: aidd-dev-explorer\n---\nBody",
-      "reasoningEffort",
-    ],
-    [
-      "cursor",
-      ".cursor/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody",
-      "embedded",
-    ],
-  ])(
-    "adapts %s settings using the installed artifact",
-    async (tool, path, content, effortField) => {
-      const { fs, repo, raw, resolve } = setup(tool, { model: "native-model", effort: "high" });
-      await fs.writeFile(join(ROOT, path), content);
-      const result = await resolve();
-      expect(result.agent).toMatchObject({
-        name: "aidd-dev-explorer",
-        path: join(ROOT, path),
-        mode: "flat",
-      });
-      expect(result.requested).toEqual({ model: "native-model", effort: "high" });
-      expect(result.native).toEqual(
-        effortField === "embedded"
-          ? { model: "native-model[effort=high]" }
-          : effortField === "variant"
-            ? { model: "native-model#high" }
-            : { model: "native-model", [effortField]: "high" }
-      );
-      expect(result.effectiveRuntime).toBe("unknown");
-      expect(await fs.readFile(CONFIG)).toBe(raw);
-      expect(repo.saveCount).toBe(0);
-    }
-  );
-
-  it("honors CODEX_HOME and inherits omitted settings", async () => {
-    const { fs, repo } = setup("codex");
-    const path = join("/custom/codex", "agents", "aidd-dev-explorer.toml");
-    await fs.writeFile(path, 'name = "actual-role"\ndeveloper_instructions = "Body"');
-    const useCase = new ResolveDelegationUseCase(fs, repo, new Map());
-    const result = await useCase.execute({
-      projectRoot: ROOT,
-      home: HOME,
-      env: { CODEX_HOME: "/custom/codex" },
-      task: "exploration",
-      tool: "codex",
-    });
-    expect(result.agent).toMatchObject({ name: "actual-role", path });
-    expect(result.native).toEqual({});
-  });
-
-  it("uses the Copilot personal agent before the same project ID", async () => {
-    const selected = setup("copilot");
-    await selected.fs.writeFile(
-      "/repo/.github/agents/aidd-dev-explorer.agent.md",
-      "---\nname: Project\n---\nProject behavior"
-    );
-    await selected.fs.writeFile(
-      "/person/.copilot/agents/aidd-dev-explorer.agent.md",
-      "---\nname: Personal\n---\nPersonal behavior"
-    );
-    expect((await selected.resolve()).agent?.path).toBe(
-      join(HOME, ".copilot", "agents", "aidd-dev-explorer.agent.md")
-    );
-  });
-
-  it("honors CLAUDE_CONFIG_DIR without reading the same role from the default profile", async () => {
-    const selected = setup("claude");
-    await selected.fs.writeFile(
-      "/person/.claude/agents/aidd-dev-explorer.md",
-      "---\nname: wrong-agent\n---\nBody"
-    );
-    await selected.fs.writeFile(
-      "/relocated/agents/aidd-dev-explorer.md",
-      "---\nname: selected-agent\n---\nBody"
-    );
-    const result = await new ResolveDelegationUseCase(
-      selected.fs,
-      selected.repo,
-      new Map()
-    ).execute({
-      projectRoot: ROOT,
-      home: HOME,
-      env: { CLAUDE_CONFIG_DIR: "/relocated" },
-      task: "exploration",
-      tool: "claude",
-    });
-    expect(result.agent).toMatchObject({
-      name: "selected-agent",
-      path: join("/relocated", "agents", "aidd-dev-explorer.md"),
-    });
-  });
-
-  it.each([
-    ["claude", ".claude/agents/aidd-dev-explorer.md", "---\nname: aidd-dev-explorer\n---\nBody"],
-    ["opencode", ".config/opencode/agents/aidd-dev-explorer.md", "---\nmode: subagent\n---\nBody"],
-    ["copilot", ".copilot/agents/aidd-dev-explorer.agent.md", "---\nname: Display name\n---\nBody"],
-    ["cursor", ".cursor/agents/aidd-dev-explorer.md", "---\nname: aidd-dev-explorer\n---\nBody"],
-  ])(
-    "finds the %s personal agent and leaves all unspecified settings inherited",
-    async (tool, relative, content) => {
-      const { fs, resolve } = setup(tool);
-      await fs.writeFile(join(HOME, relative), content);
-      const result = await resolve();
-      expect(result.agent).toMatchObject({
-        name: "aidd-dev-explorer",
-        path: join(HOME, relative),
-        mode: "flat",
-      });
-      expect(result.requested).toEqual({});
-      expect(result.native).toEqual({});
-    }
-  );
-
-  it.each([
-    ...["low", "medium", "high", "xhigh", "max"].map((effort) => [
-      "claude",
-      effort,
-      ".claude/agents/aidd-dev-explorer.md",
-      "effort",
-    ]),
-    ...["none", "minimal", "low", "medium", "high", "xhigh", "max"].map((effort) => [
-      "copilot",
-      effort,
-      ".github/agents/aidd-dev-explorer.agent.md",
-      "reasoningEffort",
-    ]),
-    [
-      "codex",
-      "model-defined-custom-effort",
-      ".codex/agents/aidd-dev-explorer.toml",
-      "model_reasoning_effort",
-    ],
-  ])(
-    "preserves %s's declared effort %s without adding a model",
-    async (tool, effort, path, field) => {
-      const { fs, resolve } = setup(tool, { effort });
-      await fs.writeFile(
-        join(ROOT, path),
-        path.endsWith(".toml")
-          ? 'name = "aidd-dev-explorer"'
-          : "---\nname: aidd-dev-explorer\n---\nBody"
-      );
-      const result = await resolve();
-      expect(result.native).toEqual({ [field]: effort });
-    }
-  );
-
-  it("names a missing agent and how to repair its installation", async () => {
-    await expect(setup("codex").resolve()).rejects.toThrow(
-      /aidd-dev:explorer.*not found.*install/i
-    );
-  });
-
-  it("uses an enabled native plugin's actual install path and its host namespace", async () => {
-    const { fs, repo } = setup("claude");
-    await fs.writeFile("/native/aidd-dev/agents/explorer.md", "---\nname: explorer\n---\nBody");
-    const registry = new FakeHostPluginRegistryReader({
-      location: "/registry.json",
-      refs: new Map([
-        [
-          "aidd-dev@my-market",
-          { enabled: true, scope: "project", installPath: "/native/aidd-dev" },
-        ],
-      ]),
-    });
-    const result = await new ResolveDelegationUseCase(
-      fs,
-      repo,
-      new Map([["claude", registry]])
-    ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "claude" });
-    expect(result.agent).toEqual({
-      name: "aidd-dev:explorer",
-      path: join("/native/aidd-dev", "agents", "explorer.md"),
-      mode: "marketplace",
-    });
-  });
-
-  it("uses the Copilot plugin filename as its namespace rather than the display name", async () => {
-    const { fs, repo } = setup("copilot");
-    await fs.writeFile(
-      "/live/aidd-dev/agents/explorer.md",
-      "---\nname: Different display name\n---\nBody"
-    );
-    const registry = new FakeHostPluginRegistryReader({
-      location: "/settings.json",
-      refs: new Map([["aidd-dev@market", { enabled: true, installPath: "/live/aidd-dev" }]]),
-    });
-    const result = await new ResolveDelegationUseCase(
-      fs,
-      repo,
-      new Map([["copilot", registry]])
-    ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "copilot" });
-    expect(result.agent).toMatchObject({ name: "aidd-dev:explorer", mode: "marketplace" });
-  });
-
-  it("prefers the project agent over a user agent and refuses disabled native plugins", async () => {
-    const { fs, repo } = setup("codex");
-    await fs.writeFile("/repo/.codex/agents/aidd-dev-explorer.toml", 'name = "project-agent"');
-    await fs.writeFile("/person/.codex/agents/aidd-dev-explorer.toml", 'name = "user-agent"');
-    expect(
-      (
-        await new ResolveDelegationUseCase(fs, repo, new Map()).execute({
-          projectRoot: ROOT,
-          home: HOME,
-          env: {},
-          task: "exploration",
-          tool: "codex",
-        })
-      ).agent?.name
-    ).toBe("project-agent");
-    const disabled = setup("claude");
-    await disabled.fs.writeFile(
-      "/native/aidd-dev/agents/explorer.md",
-      "---\nname: explorer\n---\nBody"
-    );
-    const registry = new FakeHostPluginRegistryReader({
-      location: "/registry.json",
-      refs: new Map([["aidd-dev@my-market", { enabled: false, installPath: "/native/aidd-dev" }]]),
-    });
-    await expect(
-      new ResolveDelegationUseCase(
-        disabled.fs,
-        disabled.repo,
-        new Map([["claude", registry]])
-      ).execute({ projectRoot: ROOT, home: HOME, env: {}, task: "exploration", tool: "claude" })
-    ).rejects.toThrow("disabled");
-  });
-
-  it("rejects an unsupported host, effort, and Cursor effort without an explicit model", async () => {
-    await expect(setup("kilo").resolve()).rejects.toThrow(/does not support/);
-    const invalid = setup("claude", { effort: "maximum-ish" });
-    await invalid.fs.writeFile(
-      "/repo/.claude/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody"
-    );
-    await expect(invalid.resolve()).rejects.toThrow(/effort/);
-    const missingModel = setup("cursor", { effort: "high" });
-    await missingModel.fs.writeFile(
-      "/repo/.cursor/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody"
-    );
-    await expect(missingModel.resolve()).rejects.toThrow(/explicit model/);
-  });
-
-  it("distinguishes Cursor plugin spawn settings from flat agent configuration", async () => {
-    const plugin = setup("cursor", { model: "user-catalog-slug" });
-    await plugin.fs.writeFile(
-      "/person/.cursor/plugins/local/aidd-dev/agents/explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody"
-    );
-    const result = await plugin.resolve();
-    expect(result.agent?.name).toBe("aidd-dev-explorer");
-    expect(result.nativeSurface).toBe("spawn");
-    expect(result.native).toEqual({ model: "user-catalog-slug" });
-    const effort = setup("cursor", { model: "user-catalog-slug", effort: "high" });
-    await effort.fs.writeFile(
-      "/person/.cursor/plugins/local/aidd-dev/agents/explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody"
-    );
-    await expect(effort.resolve()).rejects.toThrow(/spawn does not accept effort/);
-  });
-
-  it("refuses an older bare Cursor plugin role that could collide with a personal agent", async () => {
-    const plugin = setup("cursor");
-    await plugin.fs.writeFile(
-      "/person/.cursor/plugins/local/aidd-dev/agents/explorer.md",
-      "---\nname: explorer\n---\nAIDD"
-    );
-    await plugin.fs.writeFile(
-      "/repo/.cursor/agents/explorer.md",
-      "---\nname: explorer\n---\nOther"
-    );
-    await expect(plugin.resolve()).rejects.toThrow(/reinstall.*aidd-dev-explorer/);
-  });
-
-  it("rejects an invalid installed Codex agent instead of inventing its identity", async () => {
-    const invalid = setup("codex");
-    await invalid.fs.writeFile(
-      "/repo/.codex/agents/aidd-dev-explorer.toml",
-      'description = "No native name"'
-    );
-    await expect(invalid.resolve()).rejects.toThrow(/name/);
-  });
-
-  it("reports installed Codex pins that a spawn override would not replace", async () => {
-    const pinned = setup("codex", { model: "requested-model", effort: "high" });
-    await pinned.fs.writeFile(
-      "/repo/.codex/agents/aidd-dev-explorer.toml",
-      'name = "aidd-dev-explorer"\nmodel = "pinned-model"\nmodel_reasoning_effort = "low"'
-    );
-    const result = await pinned.resolve();
-    expect(result.native).toEqual({ model: "requested-model", model_reasoning_effort: "high" });
-    expect(result.diagnostics).toHaveLength(2);
-    expect(result.diagnostics.join(" ")).toContain("pinned-model");
-    expect(result.diagnostics.join(" ")).toContain("requested-model");
-    expect(result.diagnostics.join(" ")).toContain("low");
-    expect(result.effectiveRuntime).toBe("unknown");
-  });
-
-  it("leaves absent and matching Codex pins free of conflict diagnostics", async () => {
-    const selected = setup("codex", { model: "requested-model", effort: "high" });
-    await selected.fs.writeFile(
-      "/repo/.codex/agents/aidd-dev-explorer.toml",
-      'name = "aidd-dev-explorer"'
-    );
-    expect((await selected.resolve()).diagnostics).toEqual([]);
-    await selected.fs.writeFile(
-      "/repo/.codex/agents/aidd-dev-explorer.toml",
-      'name = "aidd-dev-explorer"\nmodel = "requested-model"\nmodel_reasoning_effort = "high"'
-    );
-    expect((await selected.resolve()).diagnostics).toEqual([]);
-  });
-
-  it.each([
-    [
-      "opencode",
-      ".opencode/agents/aidd-dev-explorer.md",
-      "provider/model#high",
-      "provider/model#low",
-    ],
-    [
-      "cursor",
-      ".cursor/agents/aidd-dev-explorer.md",
-      "native-model[effort=high]",
-      "native-model[effort=low]",
-    ],
-  ])(
-    "preserves literal %s selectors and rejects conflicting effort instead of replacing it",
-    async (tool, path, same, conflicting) => {
-      const literal = setup(tool, { model: same });
-      await literal.fs.writeFile(join(ROOT, path), "---\nname: aidd-dev-explorer\n---\nBody");
-      expect((await literal.resolve()).native).toEqual({ model: same });
-      const matching = setup(tool, { model: same, effort: "high" });
-      await matching.fs.writeFile(join(ROOT, path), "---\nname: aidd-dev-explorer\n---\nBody");
-      expect((await matching.resolve()).native).toEqual({ model: same });
-      const conflict = setup(tool, { model: conflicting, effort: "high" });
-      await conflict.fs.writeFile(join(ROOT, path), "---\nname: aidd-dev-explorer\n---\nBody");
-      await expect(conflict.resolve()).rejects.toThrow(/Conflicting/);
-    }
-  );
-
-  it.each([
-    ["claude-opus-4-8[context=1m]", "claude-opus-4-8[context=1m,effort=high]"],
-    [
-      "claude-opus-4-8[context=1m,effort=high,fast=false]",
-      "claude-opus-4-8[context=1m,effort=high,fast=false]",
-    ],
-  ])(
-    "merges Cursor effort into the existing parameter group while preserving other options",
-    async (model, expected) => {
-      const selected = setup("cursor", { model, effort: "high" });
-      await selected.fs.writeFile(
-        "/repo/.cursor/agents/aidd-dev-explorer.md",
-        "---\nname: aidd-dev-explorer\n---\nBody"
-      );
-      expect((await selected.resolve()).native).toEqual({ model: expected });
-    }
-  );
-
-  it.each([
-    ["claude-opus-4-8[context=1m,effort=high,fast=false]", "low", "Conflicting"],
-    ["model[context=]", "high", "Malformed"],
-    ["model[context=1m][fast=false]", "high", "Malformed"],
-    ["model[effort=high,effort=high]", "high", "Malformed"],
-    ["model[context=1m", "high", "Malformed"],
-  ])("refuses a conflicting or malformed Cursor parameter group", async (model, effort, reason) => {
-    const selected = setup("cursor", { model, effort });
-    await selected.fs.writeFile(
-      "/repo/.cursor/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody"
-    );
-    await expect(selected.resolve()).rejects.toMatchObject({
-      message: expect.stringContaining(reason),
-    });
-  });
-
-  it("passes a literal Cursor model unchanged when effort is omitted", async () => {
-    const selected = setup("cursor", { model: "user-literal[opaque-native-option]" });
-    await selected.fs.writeFile(
-      "/repo/.cursor/agents/aidd-dev-explorer.md",
-      "---\nname: aidd-dev-explorer\n---\nBody"
-    );
-    expect((await selected.resolve()).native).toEqual({
-      model: "user-literal[opaque-native-option]",
-    });
-  });
-});
diff --git a/cli/tests/contexts/framework/domain/delegation.unit.test.ts b/cli/tests/contexts/framework/domain/delegation.unit.test.ts
deleted file mode 100644
index 564bc8fba..000000000
--- a/cli/tests/contexts/framework/domain/delegation.unit.test.ts
+++ /dev/null
@@ -1,77 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseDelegation } from "../../../../src/contexts/framework/domain/delegation.js";
-
-describe("project delegation suggestions", () => {
-  it("leaves absent tasks and settings unspecified", () => {
-    expect(
-      parseDelegation(null, "exploration", "codex", "/repo/.aidd/config.json")
-    ).toBeUndefined();
-    expect(
-      parseDelegation('{"telemetry":{"enabled":true}}', "exploration", "codex", "/c")
-    ).toBeUndefined();
-    expect(
-      parseDelegation('{"delegation":{"other":false}}', "exploration", "codex", "/c")
-    ).toBeUndefined();
-    expect(
-      parseDelegation(
-        '{"delegation":{"exploration":{"agent":"aidd-dev:explorer"}}}',
-        "exploration",
-        "codex",
-        "/c"
-      )
-    ).toEqual({
-      plugin: "aidd-dev",
-      role: "explorer",
-      canonical: "aidd-dev:explorer",
-      requested: {},
-    });
-  });
-
-  it("selects only the requested host without changing native model literals", () => {
-    const raw = JSON.stringify({
-      delegation: {
-        exploration: {
-          agent: "aidd-dev:explorer",
-          tools: { codex: { model: "provider/model-v99", effort: "high" }, other: false },
-        },
-      },
-    });
-    expect(parseDelegation(raw, "exploration", "codex", "/c")?.requested).toEqual({
-      model: "provider/model-v99",
-      effort: "high",
-    });
-  });
-
-  it.each([
-    ["{", "valid JSON"],
-    ["[]", "JSON object"],
-    ['{"delegation":[]}', "delegation"],
-    ['{"delegation":{"exploration":null}}', "delegation.exploration"],
-    ['{"delegation":{"exploration":{"agent":"../bad:role"}}}', "plugin:role"],
-    ['{"delegation":{"exploration":{"agent":"aidd-dev:explorer","models":{}}}}', "models"],
-    ['{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":[]}}}', "tools"],
-    [
-      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":null}}}}',
-      "tools.codex",
-    ],
-    [
-      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"model":""}}}}}',
-      "model",
-    ],
-    [
-      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"effort":7}}}}}',
-      "effort",
-    ],
-    [
-      '{"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"reasoning":"high"}}}}}',
-      "reasoning",
-    ],
-  ])("reports the requested malformed field with its file", (raw, field) => {
-    expect(() => parseDelegation(raw, "exploration", "codex", "/repo/.aidd/config.json")).toThrow(
-      field
-    );
-    expect(() => parseDelegation(raw, "exploration", "codex", "/repo/.aidd/config.json")).toThrow(
-      "/repo/.aidd/config.json"
-    );
-  });
-});
diff --git a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
new file mode 100644
index 000000000..932d8bdf9
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import type { ToolBuildContract } from "../../../../../src/contexts/tools/domain/build-contract.js";
+import { agentModelOptions } from "../../../../../src/contexts/tools/domain/formats/agent-models.js";
+import recommendations from "../../../../../src/contexts/tools/domain/formats/agent-models.json" with {
+  type: "json",
+};
+import { claude } from "../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+import { codex } from "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import { parseToml } from "../../../../../src/contexts/tools/domain/profiles/codex/toml.js";
+import { copilot } from "../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+import {
+  buildCursorContract,
+  buildCursorFlatContract,
+} from "../../../../../src/contexts/tools/domain/profiles/cursor/build.js";
+import { opencode } from "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+import { parseFrontmatter } from "../../../../../src/kernel/markdown.js";
+
+const hosts = [
+  ["claude", claude, { model: "claude-haiku-5-5", effort: "medium" }],
+  ["codex", codex, { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
+  ["copilot", copilot, { model: "gpt-6-luna", reasoningEffort: "medium" }],
+  ["opencode", opencode, { model: "openai/gpt-6-luna#medium" }],
+] as const;
+
+function transform(contract: ToolBuildContract, plugin: string, role: string, fields = "") {
+  const artifact = contract.artifacts.agents;
+  if (!artifact.supported || artifact.transform === undefined)
+    throw new Error("Missing agent transform");
+  return artifact.transform(
+    `---\nname: ${role}\ndescription: Role\n${fields}---\nBody\n`,
+    plugin,
+    `${role}.md`
+  );
+}
+
+function fields(content: string, toml: boolean) {
+  return toml ? parseToml(content) : parseFrontmatter(content).frontmatter;
+}
+
+describe("installed agent model recommendations", () => {
+  it("selects Copilot's native model identifier when its provider is changed to Anthropic", () => {
+    const configuration = structuredClone(recommendations);
+    configuration.tools.copilot.provider = "anthropic";
+    expect(
+      agentModelOptions("copilot", {}, "aidd-dev", "explorer.md", "flat", configuration)
+    ).toStrictEqual({
+      model: "claude-haiku-5.5",
+      reasoningEffort: "medium",
+    });
+    expect(agentModelOptions("copilot", {}, "aidd-dev", "explorer.md")).toStrictEqual({
+      model: "gpt-6-luna",
+      reasoningEffort: "medium",
+    });
+  });
+  for (const [label, host, expected] of hosts) {
+    it.each(["explorer", "executor", "reviewer", "validator"])(
+      `${label} installs native defaults for the AIDD %s role`,
+      (role) => {
+        const capability = host.capabilities.agents;
+        const converted = capability.convertFrontmatter(
+          { name: role, description: "Role" },
+          `${role}.md`,
+          "aidd-dev"
+        );
+        expect(fields(capability.serialize(converted, "Body"), label === "codex")).toMatchObject(
+          expected
+        );
+      }
+    );
+    it(`${label} preserves explicit native settings and leaves unrelated installations unpinned`, () => {
+      const capability = host.capabilities.agents;
+      const explicit = capability.convertFrontmatter(
+        {
+          name: "explorer",
+          model: "custom-native",
+          effort: "high",
+          model_reasoning_effort: "high",
+          reasoningEffort: "high",
+        },
+        "explorer.md",
+        "aidd-dev"
+      );
+      expect(explicit.model).toBe("custom-native");
+      for (const field of Object.keys(expected).filter((field) => field !== "model"))
+        expect(explicit[field]).toBe("high");
+      expect(
+        capability.convertFrontmatter({ name: "explorer" }, "explorer.md", "personal")
+      ).not.toHaveProperty("model");
+    });
+    for (const [mode, build] of Object.entries(host.buildContracts ?? {})) {
+      it(`${label} ${mode} build writes native recommendations`, () => {
+        expect(fields(transform(build(), "aidd-dev", "explorer"), label === "codex")).toMatchObject(
+          expected
+        );
+      });
+      it(`${label} ${mode} build preserves an explicit model and unrelated agents`, () => {
+        const explicit = fields(
+          transform(build(), "aidd-dev", "explorer", "model: custom-native\n"),
+          label === "codex"
+        );
+        expect(explicit.model).toBe("custom-native");
+        expect(
+          fields(transform(build(), "personal", "explorer"), label === "codex")
+        ).not.toHaveProperty("model");
+        expect(
+          fields(transform(build(), "aidd-dev", "planner"), label === "codex")
+        ).not.toHaveProperty("model");
+      });
+    }
+  }
+  it("Cursor flat agents carry the native model parameter while plugin agents inherit", () => {
+    expect(
+      fields(transform(buildCursorFlatContract(), "aidd-dev", "explorer"), false)
+    ).toMatchObject({ model: "claude-haiku-5-5[effort=medium]" });
+    expect(
+      fields(transform(buildCursorContract(), "aidd-dev", "explorer"), false)
+    ).not.toHaveProperty("model");
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
index 246749a38..53ff6ca45 100644
--- a/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
@@ -103,10 +103,10 @@ describe("claude", () => {
   });
 
   describe("capabilities.agents.convertFrontmatter()", () => {
-    it("strips extra fields for agents sections — only name and description", () => {
+    it("preserves an explicitly selected agent model", () => {
       const fm = { name: "alexia", description: "Agent", model: "opus" };
       const result = claude.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ name: "alexia", description: "Agent" });
+      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
     });
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
index e1966316b..0ae762193 100644
--- a/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
@@ -181,7 +181,7 @@ describe("buildCodexContract()", () => {
     const transform = supported(buildCodexContract().artifacts.agents).transform;
 
     expect(transform?.(AGENT_SOURCE, "aidd-dev", "planner.md")).toBe(
-      'name = "planner"\ndescription = "Plans the work"\ndeveloper_instructions = "Plan before building.\\n"\n'
+      'name = "planner"\ndescription = "Plans the work"\nmodel = "opus"\ndeveloper_instructions = "Plan before building.\\n"\n'
     );
   });
 
@@ -308,7 +308,7 @@ describe("buildCodexFlatContract()", () => {
     const transform = supported(buildCodexFlatContract().artifacts.agents).transform;
 
     expect(transform?.(AGENT_SOURCE, "aidd-dev", "planner.md")).toBe(
-      'name = "aidd-dev-planner"\ndescription = "Plans the work"\ndeveloper_instructions = "Plan before building.\\n"\n'
+      'name = "aidd-dev-planner"\ndescription = "Plans the work"\nmodel = "opus"\ndeveloper_instructions = "Plan before building.\\n"\n'
     );
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts
index 1d1cb9cd5..ed6311676 100644
--- a/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts
@@ -94,32 +94,32 @@ describe("codexAgentMarkdownToToml()", () => {
     });
   });
 
-  describe("model omission (D-5)", () => {
-    it("omits model key when frontmatter has model: opus", () => {
+  describe("explicit model preservation", () => {
+    it("preserves an explicit opus model literal", () => {
       const toml = codexAgentMarkdownToToml(
         "---\nname: planner\ndescription: A planner.\nmodel: opus\n---\n\nBody.",
         "aidd-dev",
         "planner.md"
       );
-      expect(toml).not.toContain("model");
+      expect(parseToml(toml).model).toBe("opus");
     });
 
-    it("omits model key when frontmatter has model: sonnet", () => {
+    it("preserves an explicit sonnet model literal", () => {
       const toml = codexAgentMarkdownToToml(
         "---\nname: planner\nmodel: sonnet\n---\n\nBody.",
         "aidd-dev",
         "planner.md"
       );
-      expect(toml).not.toContain("model");
+      expect(parseToml(toml).model).toBe("sonnet");
     });
 
-    it("omits model key for hypothetical Codex model id (MVP1 always omits)", () => {
+    it("preserves an explicit native model identifier", () => {
       const toml = codexAgentMarkdownToToml(
         "---\nname: planner\nmodel: gpt-5-codex\n---\n\nBody.",
         "aidd-dev",
         "planner.md"
       );
-      expect(toml).not.toContain("model");
+      expect(parseToml(toml).model).toBe("gpt-5-codex");
     });
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
index 53a7ce5ca..13e536c4d 100644
--- a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
@@ -26,10 +26,10 @@ describe("copilot", () => {
   });
 
   describe("capabilities.agents.convertFrontmatter()", () => {
-    it("strips extra fields for agents sections — only name and description", () => {
+    it("preserves an explicitly selected agent model", () => {
       const fm = { name: "alexia", description: "Agent", model: "opus" };
       const result = copilot.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ name: "alexia", description: "Agent" });
+      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
     });
 
     it("names an unnamed agent after its own file, whatever folders it sits in", () => {
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
index 5c0291fcd..0c2910de6 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
@@ -4,46 +4,6 @@ import { CONFIG_MCP } from "../../../../../src/contexts/tools/domain/capabilitie
 import { cursor } from "../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
 
 describe("cursor", () => {
-  describe("capabilities.agents delegation", () => {
-    const delegation = cursor.capabilities.agents.params.delegation;
-    if (delegation === undefined) throw new Error("Cursor delegation must be declared");
-
-    it.each(["!high", "high!", "hi!gh"])(
-      "rejects an effort delimiter in %s before constructing a model option",
-      async (effort) => {
-        await expect(
-          Promise.resolve().then(() =>
-            delegation.resolveNative({ model: "native-model", effort }, "flat")
-          )
-        ).rejects.toMatchObject({ message: expect.stringContaining("Invalid effort") });
-      }
-    );
-
-    it.each([
-      "model]",
-      "[context=1m]",
-      "model[foo[bar=value]",
-      "model[=1]",
-      "model[context=a=b]",
-      "model[context=1 m]",
-    ])("rejects malformed model options in %s when adding effort", async (model) => {
-      await expect(
-        Promise.resolve().then(() => delegation.resolveNative({ model, effort: "high" }, "flat"))
-      ).rejects.toMatchObject({ message: expect.stringContaining("Malformed") });
-    });
-
-    it("preserves a personal agent's declared name in flat mode", () => {
-      expect(delegation.identity("personal-reviewer", "aidd-dev", "flat", "reviewer")).toBe(
-        "personal-reviewer"
-      );
-    });
-
-    it("distinguishes flat agent configuration from plugin spawn options", () => {
-      expect(delegation.nativeSurface?.("flat")).toBe("agent-configuration");
-      expect(delegation.nativeSurface?.("marketplace")).toBe("spawn");
-    });
-  });
-
   describe("capabilities.rules.convertFrontmatter()", () => {
     it("converts paths: to globs: as a JSON inline string and adds alwaysApply: false", () => {
       const result = cursor.capabilities.rules?.convertFrontmatter({
@@ -98,10 +58,10 @@ describe("cursor", () => {
   });
 
   describe("capabilities.agents.convertFrontmatter()", () => {
-    it("strips extra fields for agents sections — only name and description", () => {
+    it("preserves an explicitly selected agent model", () => {
       const fm = { name: "alexia", description: "Agent", model: "opus" };
       const result = cursor.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ name: "alexia", description: "Agent" });
+      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
     });
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
index 10b6a1fc5..c9c40137c 100644
--- a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
@@ -1,4 +1,3 @@
-import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { opencode } from "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
 import { OpencodeDualConfigError } from "../../../../../src/kernel/errors.js";
@@ -18,33 +17,6 @@ function makeFs(existingPaths: string[]): FileReader {
 }
 
 describe("opencode", () => {
-  describe("capabilities.agents delegation", () => {
-    const delegation = opencode.capabilities.agents.params.delegation;
-    if (delegation === undefined) throw new Error("OpenCode delegation must be declared");
-
-    it.each(["!high", "high!", "hi!gh"])(
-      "rejects an effort delimiter in %s before constructing a model variant",
-      async (effort) => {
-        await expect(
-          Promise.resolve().then(() =>
-            delegation.resolveNative({ model: "provider/model", effort }, "flat")
-          )
-        ).rejects.toMatchObject({ message: expect.stringContaining("Invalid effort") });
-      }
-    );
-
-    it("finds personal agents under the native XDG configuration override", () => {
-      expect(
-        delegation.userPath(
-          "/person",
-          { XDG_CONFIG_HOME: "/native-config" },
-          "aidd-dev",
-          "explorer"
-        )
-      ).toBe(join("/native-config", "opencode", "agents", "aidd-dev-explorer.md"));
-    });
-  });
-
   describe("capabilities.agents.buildInstallPath()", () => {
     it("builds path under .opencode/agents/", () => {
       const path = opencode.capabilities.agents.buildInstallPath("code-reviewer.md");
diff --git a/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts b/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts
index b505b948a..77a3ce565 100644
--- a/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts
+++ b/cli/tests/contexts/tools/infrastructure/host-plugin-registry-reader-adapter.integration.test.ts
@@ -36,106 +36,6 @@ function readerFor(tool: AiToolId) {
 describe("Claude Code's own installed_plugins.json", () => {
   const PATH = ".claude/plugins/installed_plugins.json";
 
-  it("does not treat a cached but disabled plugin as available during delegation", async () => {
-    const project = join(home, "project");
-    const cache = join(home, "cache", "aidd-dev");
-    await write(
-      PATH,
-      JSON.stringify({ plugins: { "aidd-dev@market": [{ scope: "user", installPath: cache }] } })
-    );
-    await write("cache/aidd-dev/agents/explorer.md", "---\nname: explorer\n---\nBody");
-    await write(
-      ".claude/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
-    );
-    await write(
-      "project/.claude/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
-    );
-    expect(
-      (await readerFor("claude").read(project, true)).refs?.get("aidd-dev@market")
-    ).toMatchObject({ enabled: false, installPath: cache });
-    expect((await readerFor("claude").read(project)).refs?.get("aidd-dev@market")?.enabled).toBe(
-      true
-    );
-  });
-
-  it("uses the highest mentioning Claude settings source without dropping unrelated lower keys", async () => {
-    const project = join(home, "project");
-    await write(
-      PATH,
-      JSON.stringify({
-        plugins: {
-          "aidd-dev@market": [{ scope: "user", installPath: "/cache" }],
-          "aidd-pm@market": [{ scope: "user", installPath: "/pm" }],
-        },
-      })
-    );
-    await write(
-      ".claude/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false, "aidd-pm@market": true } })
-    );
-    await write(
-      "project/.claude/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
-    );
-    await write(
-      "project/.claude/settings.local.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
-    );
-    const reading = await readerFor("claude").read(project, true);
-    expect(reading.refs?.get("aidd-dev@market")?.enabled).toBe(true);
-    expect(reading.refs?.get("aidd-pm@market")?.enabled).toBe(true);
-  });
-
-  it("marks Claude activation unverified when settings never mention the installed ref", async () => {
-    await write(
-      PATH,
-      JSON.stringify({ plugins: { "aidd-dev@market": [{ scope: "user", installPath: "/cache" }] } })
-    );
-    expect(
-      (await readerFor("claude").read(join(home, "project"), true)).refs?.get("aidd-dev@market")
-        ?.activationUnverified
-    ).toContain("enabledPlugins");
-  });
-
-  it("reads Claude's relocated settings and plugin registry rather than the default profile", async () => {
-    await write(PATH, JSON.stringify({ plugins: { "wrong@market": [{ scope: "user" }] } }));
-    await write(
-      "relocated-plugins/installed_plugins.json",
-      JSON.stringify({ plugins: { "aidd-dev@market": [{ scope: "user", installPath: "/cache" }] } })
-    );
-    await write(
-      "relocated-config/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
-    );
-    const reader = hostPluginRegistryReaders(home, {
-      CLAUDE_CONFIG_DIR: join(home, "relocated-config"),
-      CLAUDE_CODE_PLUGIN_CACHE_DIR: join(home, "relocated-plugins"),
-    }).get("claude");
-    const reading = await reader?.read(join(home, "project"), true);
-    expect(reading?.location).toBe(join(home, "relocated-plugins", "installed_plugins.json"));
-    expect(reading?.refs?.get("aidd-dev@market")?.enabled).toBe(true);
-    expect(reading?.refs?.has("wrong@market")).toBe(false);
-  });
-
-  it("carries the actual project plugin path before the user fallback for delegation", async () => {
-    await write(
-      PATH,
-      JSON.stringify({
-        plugins: {
-          "aidd-dev@market": [
-            { scope: "user", installPath: "/user/plugin" },
-            { scope: "project", projectPath: PROJECT, installPath: "/project/plugin" },
-          ],
-        },
-      })
-    );
-    expect(
-      (await readerFor("claude").read(PROJECT)).refs?.get("aidd-dev@market")?.installPath
-    ).toBe("/project/plugin");
-  });
-
   it("counts a ref installed for this project, and one installed for the machine", async () => {
     await write(
       PATH,
@@ -371,146 +271,6 @@ describe("Codex's own config.toml", () => {
 describe("Copilot's own settings.json", () => {
   const PATH = ".copilot/settings.json";
 
-  it("applies repository disablement and local re-enablement per plugin during delegation", async () => {
-    const project = join(home, "project");
-    await write(
-      PATH,
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true, "other@market": true } })
-    );
-    await write(
-      "project/.github/copilot/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
-    );
-    expect(
-      (await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")?.enabled
-    ).toBe(false);
-    expect((await readerFor("copilot").read(project)).refs?.get("aidd-dev@market")?.enabled).toBe(
-      true
-    );
-    await write(
-      "project/.github/copilot/settings.local.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
-    );
-    const reading = await readerFor("copilot").read(project, true);
-    expect(reading.refs?.get("aidd-dev@market")?.enabled).toBe(true);
-    expect(reading.refs?.get("other@market")?.enabled).toBe(true);
-  });
-
-  it("reads a repository-only Copilot registration from JSONC without using a personal profile", async () => {
-    const project = join(home, "project");
-    await write(
-      "project/.github/copilot/settings.json",
-      '// repository plugin\n{ "enabledPlugins": { "aidd-dev@market": true, }, }'
-    );
-    expect((await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")).toEqual({
-      enabled: true,
-      installPath: join(home, ".copilot", "installed-plugins", "market", "aidd-dev"),
-    });
-  });
-
-  it("does not claim activation from a malformed Copilot enabledPlugins value", async () => {
-    await write(PATH, JSON.stringify({ enabledPlugins: { "aidd-dev@market": "false" } }));
-    const reading = await readerFor("copilot").read(PROJECT, true);
-    expect(reading.refs).toBeUndefined();
-    expect(reading.unreadable).toContain("enabledPlugins.aidd-dev@market must be a boolean");
-  });
-
-  it("reports conflicting cross-tool settings and accepts an explicit higher-scope answer", async () => {
-    const project = join(home, "project");
-    await write(
-      "project/.claude/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
-    );
-    await write(
-      "project/.github/copilot/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
-    );
-    const conflicting = await readerFor("copilot").read(project, true);
-    expect(conflicting.refs).toBeUndefined();
-    expect(conflicting.unreadable).toContain("conflicting enabledPlugins.aidd-dev@market");
-    await write(
-      "project/.github/copilot/settings.local.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } })
-    );
-    expect(
-      (await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")?.enabled
-    ).toBe(true);
-    await write(
-      "project/.github/copilot/settings.json",
-      JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
-    );
-    await rm(join(project, ".github", "copilot", "settings.local.json"));
-    expect(
-      (await readerFor("copilot").read(project, true)).refs?.get("aidd-dev@market")?.enabled
-    ).toBe(false);
-  });
-
-  it.each([
-    "marketplace.json",
-    ".plugin/marketplace.json",
-    ".github/plugin/marketplace.json",
-    ".claude-plugin/marketplace.json",
-  ])("locates a live directory plugin through %s", async (catalogPath) => {
-    const marketplace = join(home, "market");
-    await write(
-      `market/${catalogPath}`,
-      JSON.stringify({ plugins: [{ name: "aidd-dev", source: "./plugins/aidd-dev" }] })
-    );
-    await write(
-      PATH,
-      JSON.stringify({
-        enabledPlugins: { "aidd-dev@market": true },
-        extraKnownMarketplaces: { market: { source: { source: "directory", path: marketplace } } },
-      })
-    );
-    expect(
-      (await readerFor("copilot").read(PROJECT, true)).refs?.get("aidd-dev@market")?.installPath
-    ).toBe(join(marketplace, "plugins", "aidd-dev"));
-  });
-
-  it("locates a remote Copilot plugin in its documented installed cache under COPILOT_HOME", async () => {
-    const config = join(home, "relocated-copilot");
-    await write(
-      ".copilot/settings.json",
-      JSON.stringify({ enabledPlugins: { "wrong@market": true } })
-    );
-    await write(
-      "relocated-copilot/settings.json",
-      JSON.stringify({
-        enabledPlugins: { "aidd-dev@market": true },
-        extraKnownMarketplaces: { market: { source: { source: "github", repo: "owner/repo" } } },
-      })
-    );
-    const reader = hostPluginRegistryReaders(home, { COPILOT_HOME: config }).get("copilot");
-    const reading = await reader?.read(join(home, "project"), true);
-    expect(reading?.location).toBe(join(config, "settings.json"));
-    expect(reading?.refs?.get("aidd-dev@market")?.installPath).toBe(
-      join(config, "installed-plugins", "market", "aidd-dev")
-    );
-    expect(reading?.refs?.has("wrong@market")).toBe(false);
-  });
-
-  it("uses the installed cache for a remote plugin listed by a live directory marketplace", async () => {
-    await write(
-      "market/.plugin/marketplace.json",
-      JSON.stringify({
-        plugins: [{ name: "aidd-dev", source: { source: "github", repo: "owner/plugin" } }],
-      })
-    );
-    await write(
-      PATH,
-      JSON.stringify({
-        enabledPlugins: { "aidd-dev@market": true },
-        extraKnownMarketplaces: {
-          market: { source: { source: "directory", path: join(home, "market") } },
-        },
-      })
-    );
-    expect(
-      (await readerFor("copilot").read(PROJECT, true)).refs?.get("aidd-dev@market")?.installPath
-    ).toBe(join(home, ".copilot", "installed-plugins", "market", "aidd-dev"));
-  });
-
   it("reads the refs its enabledPlugins carries", async () => {
     await write(
       PATH,
diff --git a/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts b/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts
index 6d4e00522..f7da326c8 100644
--- a/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts
+++ b/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts
@@ -212,15 +212,18 @@ describe("CodexOutputStrategy", () => {
       }
     });
 
-    it("TOML files do not contain model key (D-5)", async () => {
+    it("TOML files preserve explicit models and leave unrelated agents unpinned", async () => {
       const fs = await makeSeededFsFromReal();
       const uc = makeUseCase(fs);
       await uc.execute({ sourceDir: REAL_FIXTURE_DIR, outDir: OUT_DIR, target: "codex" });
-      const tomlFiles = fs.listUnder(OUT_DIR).filter((p) => p.endsWith(".toml"));
-      for (const tomlPath of tomlFiles) {
-        const content = fs.getFile(tomlPath) ?? "";
+      for (const [plugin, agent, model] of [
+        ["aidd-dev", "reviewer", "opus"],
+        ["aidd-dev", "implementer", "sonnet"],
+        ["aidd-async-dev", "async-orchestrator", undefined],
+      ]) {
+        const content = fs.getFile(`${OUT_DIR}/plugins/${plugin}/codex-agents/${agent}.toml`) ?? "";
         const parsed = parseToml(content) as Record<string, unknown>;
-        expect(parsed.model).toBeUndefined();
+        expect(parsed.model).toBe(model);
       }
     });
   });
@@ -448,15 +451,15 @@ describe("CodexOutputStrategy", () => {
     });
   });
 
-  describe("model key omission (D-5)", () => {
-    it("fixture agent with model: opus produces TOML with no model key", async () => {
+  describe("explicit model preservation", () => {
+    it("fixture agent with model: opus keeps that literal model", async () => {
       const fs = await makeSeededFsFromCodex();
       const uc = makeUseCase(fs);
       await uc.execute({ sourceDir: CODEX_FIXTURE_DIR, outDir: OUT_DIR, target: "codex" });
       const tomlContent =
         fs.getFile(`${OUT_DIR}/plugins/aidd-codex-fixture/codex-agents/test-agent.toml`) ?? "";
       const parsed = parseToml(tomlContent) as Record<string, unknown>;
-      expect(parsed.model).toBeUndefined();
+      expect(parsed.model).toBe("opus");
     });
   });
 });
diff --git a/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts b/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts
index d0913b772..ff70005a1 100644
--- a/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts
+++ b/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import { PluginsCapability } from "../../../../src/contexts/tools/domain/capabilities/plugins-capability.js";
 import { claude } from "../../../../src/contexts/tools/domain/profiles/claude/profile.js";
 import { codex } from "../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import { parseToml } from "../../../../src/contexts/tools/domain/profiles/codex/toml.js";
 import { copilot } from "../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
 import { cursor } from "../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
 import { opencode } from "../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
@@ -84,6 +85,45 @@ function pathsFor(tool: ToolConfig, dist = makeDist()): string[] {
 }
 
 describe("PluginContentTranslator.translate()", () => {
+  it.each([
+    [
+      "claude",
+      claude,
+      ".claude/plugins/aidd-dev/agents/reviewer.md",
+      { model: "claude-haiku-5-5", effort: "medium" },
+    ],
+    [
+      "codex",
+      codex,
+      ".codex/plugins/aidd-dev/agents/reviewer.toml",
+      { model: "gpt-6-luna", model_reasoning_effort: "medium" },
+    ],
+    [
+      "copilot",
+      copilot,
+      ".github/plugins/aidd-dev/agents/reviewer.agent.md",
+      { model: "gpt-6-luna", reasoningEffort: "medium" },
+    ],
+    [
+      "opencode",
+      opencode,
+      ".opencode/agents/aidd-dev-reviewer.md",
+      { model: "openai/gpt-6-luna#medium" },
+    ],
+  ] as const)(
+    "writes %s agent recommendations through ordinary installation",
+    (label, host, path, expected) => {
+      const dist = makeDist({ manifest: { name: "aidd-dev", version: "1.0.0" } });
+      const installed = translator.translate(dist, host).find((file) => file.relativePath === path);
+      expect(installed).toBeDefined();
+      const content = installed?.content ?? "";
+      expect(
+        label === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter
+      ).toMatchObject(expected);
+      expect(content).toContain("Reviewer agent from sample-plugin.");
+    }
+  );
+
   describe("claude target", () => {
     it("emits all components claude supports under .claude/plugins/sample-plugin/", () => {
       const paths = pathsFor(claude);
@@ -238,8 +278,8 @@ describe("PluginContentTranslator.translate()", () => {
       expect(greet?.content).toContain("name: 'aidd-sample-plugin:greet'");
     });
 
-    it("emits agents under .opencode/agents/sample-plugin/", () => {
-      expect(pathsFor(opencode)).toContain(".opencode/agents/sample-plugin/reviewer.md");
+    it("emits agents at their native flat path", () => {
+      expect(pathsFor(opencode)).toContain(".opencode/agents/sample-plugin-reviewer.md");
     });
 
     it("emits skills under .opencode/skills/sample-plugin/", () => {
diff --git a/cli/tests/e2e/agent-models.e2e.test.ts b/cli/tests/e2e/agent-models.e2e.test.ts
new file mode 100644
index 000000000..667b68a2b
--- /dev/null
+++ b/cli/tests/e2e/agent-models.e2e.test.ts
@@ -0,0 +1,104 @@
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseToml } from "../../src/contexts/tools/domain/profiles/codex/toml.js";
+import { parseFrontmatter } from "../../src/kernel/markdown.js";
+import { REPOSITORY_ROOT } from "../helpers/repository-root.js";
+import { createTestEnv, runCli } from "./helpers.js";
+
+const roles = ["explorer", "executor", "validator", "reviewer"];
+const hosts = [
+  ["claude", ".claude", ".md", { model: "claude-haiku-5-5", effort: "medium" }],
+  ["codex", ".codex", ".toml", { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
+  ["copilot", ".github", ".agent.md", { model: "gpt-6-luna", reasoningEffort: "medium" }],
+  ["opencode", ".opencode", ".md", { model: "openai/gpt-6-luna#medium" }],
+  ["cursor", ".cursor", ".md", { model: "claude-haiku-5-5[effort=medium]" }],
+] as const;
+
+async function source(root: string): Promise<string> {
+  const path = join(root, "source");
+  const plugin = join(path, "plugins", "aidd-dev");
+  await mkdir(join(path, ".claude-plugin"), { recursive: true });
+  await mkdir(join(plugin, ".claude-plugin"), { recursive: true });
+  await mkdir(join(plugin, "agents"));
+  await writeFile(
+    join(path, ".claude-plugin", "marketplace.json"),
+    JSON.stringify({
+      name: "agent-model-tests",
+      owner: { name: "Test" },
+      plugins: [{ name: "aidd-dev", source: "./plugins/aidd-dev" }],
+    })
+  );
+  await writeFile(
+    join(plugin, ".claude-plugin", "plugin.json"),
+    JSON.stringify({ name: "aidd-dev", version: "1.0.0", description: "Agent models" })
+  );
+  for (const role of roles)
+    await copyFile(
+      join(REPOSITORY_ROOT, "plugins", "aidd-dev", "agents", `${role}.md`),
+      join(plugin, "agents", `${role}.md`)
+    );
+  return path;
+}
+
+describe.concurrent("CLI-installed agent model headers", () => {
+  for (const [host, directory, suffix, expected] of hosts) {
+    it(`${host} writes all four agents into the host's native flat directory`, async () => {
+      const box = await createTestEnv(`agent-models-${host}`);
+      try {
+        const input = await source(box.tempDir);
+        const result = await runCli(
+          ["translate", input, "--to", host, "--as", "flat", "--out", box.projectDir],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(result.exitCode, result.stderr).toBe(0);
+        for (const role of roles) {
+          const content = await readFile(
+            join(box.projectDir, directory, "agents", `aidd-dev-${role}${suffix}`),
+            "utf8"
+          );
+          const fields =
+            host === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
+          expect(fields).toMatchObject(expected);
+          expect(content).toContain("# Behavior");
+        }
+      } finally {
+        await box.cleanup();
+      }
+    });
+
+    if (host === "opencode") continue;
+    it(`${host} marketplace output respects the native agent format`, async () => {
+      const box = await createTestEnv(`agent-models-${host}-plugin`);
+      try {
+        const input = await source(box.tempDir);
+        const output = join(box.tempDir, "built");
+        const result = await runCli(
+          ["translate", input, "--to", host, "--out", output],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(result.exitCode, result.stderr).toBe(0);
+        for (const role of roles) {
+          const content = await readFile(
+            join(
+              output,
+              "plugins",
+              "aidd-dev",
+              host === "codex" ? "codex-agents" : "agents",
+              `${role}${host === "codex" ? ".toml" : ".md"}`
+            ),
+            "utf8"
+          );
+          const fields =
+            host === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
+          if (host === "cursor") expect(fields).not.toHaveProperty("model");
+          else expect(fields).toMatchObject(expected);
+        }
+      } finally {
+        await box.cleanup();
+      }
+    });
+  }
+});
diff --git a/cli/tests/e2e/delegation.e2e.test.ts b/cli/tests/e2e/delegation.e2e.test.ts
deleted file mode 100644
index c93b4f9e7..000000000
--- a/cli/tests/e2e/delegation.e2e.test.ts
+++ /dev/null
@@ -1,202 +0,0 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { createTestEnv, FRAMEWORK_PATH, runCli } from "./helpers.js";
-
-describe("project delegation queries", () => {
-  it("resolves a Copilot agent from the generated marketplace's declared plugin root", async () => {
-    const { tempDir, projectDir, fakeHome, cleanup } = await createTestEnv(
-      "delegation-copilot-build"
-    );
-    try {
-      const market = join(tempDir, "market");
-      const build = await runCli(
-        ["translate", FRAMEWORK_PATH, "--to", "copilot", "--out", market],
-        projectDir,
-        fakeHome
-      );
-      expect(build.exitCode).toBe(0);
-      const config = join(projectDir, ".aidd", "config.json");
-      const personal = join(fakeHome, ".copilot");
-      await mkdir(dirname(config), { recursive: true });
-      await mkdir(personal, { recursive: true });
-      await writeFile(
-        config,
-        JSON.stringify({ delegation: { review: { agent: "aidd-test:code-reviewer" } } })
-      );
-      await writeFile(
-        join(personal, "settings.json"),
-        JSON.stringify({
-          enabledPlugins: { "aidd-test@market": true },
-          extraKnownMarketplaces: { market: { source: { source: "directory", path: market } } },
-        })
-      );
-      const result = await runCli(
-        ["delegation", "resolve", "review", "--tool", "copilot", "--json"],
-        projectDir,
-        fakeHome
-      );
-      expect(result.exitCode, result.stderr).toBe(0);
-      expect(JSON.parse(result.stdout).agent).toEqual({
-        name: "aidd-test:code-reviewer",
-        path: join(market, "plugins", "aidd-test", "agents", "code-reviewer.md"),
-        mode: "marketplace",
-      });
-    } finally {
-      await cleanup();
-    }
-  });
-  it("shows conflicting native Codex pins in default text output", async () => {
-    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation-pins");
-    try {
-      const config = join(projectDir, ".aidd", "config.json");
-      const agent = join(projectDir, ".codex", "agents", "aidd-dev-explorer.toml");
-      await mkdir(dirname(config), { recursive: true });
-      await mkdir(dirname(agent), { recursive: true });
-      await writeFile(
-        config,
-        JSON.stringify({
-          delegation: {
-            exploration: {
-              agent: "aidd-dev:explorer",
-              tools: { codex: { model: "requested-model" } },
-            },
-          },
-        })
-      );
-      await writeFile(
-        agent,
-        'name = "aidd-dev-explorer"\nmodel = "pinned-model"\ndescription = "Explore"\ndeveloper_instructions = "Body"'
-      );
-      const result = await runCli(
-        ["delegation", "resolve", "exploration", "--tool", "codex"],
-        projectDir,
-        fakeHome
-      );
-      expect(result.exitCode).toBe(0);
-      expect(result.stderr).toContain("pinned-model");
-      expect(result.stderr).toContain("requested-model");
-      expect(result.stdout).toContain(agent);
-    } finally {
-      await cleanup();
-    }
-  });
-
-  it("rejects a disabled cached Claude plugin and accepts an explicit local enablement", async () => {
-    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation-activation");
-    try {
-      const config = join(projectDir, ".aidd", "config.json");
-      const personal = join(fakeHome, ".claude");
-      const plugins = join(personal, "plugins");
-      const installed = join(plugins, "cache", "aidd-dev");
-      const local = join(projectDir, ".claude", "settings.local.json");
-      await mkdir(dirname(config), { recursive: true });
-      await mkdir(join(installed, "agents"), { recursive: true });
-      await mkdir(dirname(local), { recursive: true });
-      await writeFile(
-        config,
-        JSON.stringify({ delegation: { exploration: { agent: "aidd-dev:explorer" } } })
-      );
-      await writeFile(join(installed, "agents", "explorer.md"), "---\nname: explorer\n---\nBody");
-      await writeFile(
-        join(plugins, "installed_plugins.json"),
-        JSON.stringify({
-          plugins: { "aidd-dev@market": [{ scope: "user", installPath: installed }] },
-        })
-      );
-      await writeFile(
-        join(personal, "settings.json"),
-        JSON.stringify({ enabledPlugins: { "aidd-dev@market": false } })
-      );
-      const options = {
-        env: { CLAUDE_CONFIG_DIR: personal, CLAUDE_CODE_PLUGIN_CACHE_DIR: plugins },
-      };
-      const disabled = await runCli(
-        ["delegation", "resolve", "exploration", "--tool", "claude", "--json"],
-        projectDir,
-        fakeHome,
-        options
-      );
-      expect(disabled.exitCode).toBe(1);
-      expect(disabled.stderr).toContain("disabled");
-      await writeFile(local, JSON.stringify({ enabledPlugins: { "aidd-dev@market": true } }));
-      const enabled = await runCli(
-        ["delegation", "resolve", "exploration", "--tool", "claude", "--json"],
-        projectDir,
-        fakeHome,
-        options
-      );
-      expect(enabled.exitCode).toBe(0);
-      expect(JSON.parse(enabled.stdout).agent).toMatchObject({
-        name: "aidd-dev:explorer",
-        path: join(installed, "agents", "explorer.md"),
-        mode: "marketplace",
-      });
-    } finally {
-      await cleanup();
-    }
-  });
-  it("resolves a real installed agent, emits native suggestions, and never rewrites config", async () => {
-    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation");
-    try {
-      const path = join(projectDir, ".aidd", "config.json");
-      const agent = join(projectDir, ".codex", "agents", "aidd-dev-explorer.toml");
-      const raw =
-        '{"telemetry":{"enabled":true},"custom":7,"delegation":{"exploration":{"agent":"aidd-dev:explorer","tools":{"codex":{"model":"user-model","effort":"high"}}}}}\n';
-      await mkdir(dirname(path), { recursive: true });
-      await mkdir(dirname(agent), { recursive: true });
-      await writeFile(path, raw);
-      await writeFile(
-        agent,
-        'name = "aidd-dev-explorer"\ndescription = "Explore"\ndeveloper_instructions = "Body"\n'
-      );
-      const result = await runCli(
-        ["delegation", "resolve", "exploration", "--tool", "codex", "--json"],
-        projectDir,
-        fakeHome
-      );
-      expect(result.exitCode).toBe(0);
-      expect(JSON.parse(result.stdout)).toMatchObject({
-        configured: true,
-        canonicalAgent: "aidd-dev:explorer",
-        agent: { name: "aidd-dev-explorer", path: agent },
-        requested: { model: "user-model", effort: "high" },
-        native: { model: "user-model", model_reasoning_effort: "high" },
-        effectiveRuntime: "unknown",
-      });
-      expect(await readFile(path, "utf8")).toBe(raw);
-    } finally {
-      await cleanup();
-    }
-  });
-
-  it("reports inheritance for an absent task, and diagnoses malformed config on stderr", async () => {
-    const { projectDir, fakeHome, cleanup } = await createTestEnv("delegation-missing");
-    try {
-      const inherited = await runCli(
-        ["delegation", "resolve", "exploration", "--tool", "codex", "--json"],
-        projectDir,
-        fakeHome
-      );
-      expect(inherited.exitCode).toBe(0);
-      expect(JSON.parse(inherited.stdout)).toMatchObject({
-        configured: false,
-        requested: {},
-        native: {},
-      });
-      const path = join(projectDir, ".aidd", "config.json");
-      await mkdir(dirname(path), { recursive: true });
-      await writeFile(path, "{");
-      const failed = await runCli(
-        ["delegation", "resolve", "exploration", "--tool", "codex"],
-        projectDir,
-        fakeHome
-      );
-      expect(failed.exitCode).toBe(1);
-      expect(failed.stderr).toContain(path);
-      expect(failed.stderr).toContain("valid JSON");
-    } finally {
-      await cleanup();
-    }
-  });
-});
diff --git a/cli/tests/golden/snapshots/framework-build/golden.json b/cli/tests/golden/snapshots/framework-build/golden.json
index 98ad398d6..8c6df6dae 100644
--- a/cli/tests/golden/snapshots/framework-build/golden.json
+++ b/cli/tests/golden/snapshots/framework-build/golden.json
@@ -293,9 +293,9 @@
     "plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md": "cacb673334d8947c3c252feaaf0ef50c269c06c5cf8f51b45663cbd42402e094",
     "plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md": "6f6cddd0893888c71b0aed5ecfe48217afe0eef10feec6415db433bfcc69f8e3",
     "plugins/aidd-dev/skills/00-sdlc/SKILL.md": "e961d919f13d1650d7c47dc0fa118f8cdce7d434c2ae31aa9c30a203463c86f4",
-    "plugins/aidd-dev/codex-agents/implementer.toml": "d6b2739193ecc12b546f17a994af4e2949ccbea3f2560139b3bf7693fca9604d",
-    "plugins/aidd-dev/codex-agents/planner.toml": "347e72e5beb8d0b493618c2d03f37d765c10e407f3404539fa5dc822fd2fecad",
-    "plugins/aidd-dev/codex-agents/reviewer.toml": "9dd3b9e0420601fc35c287636a6553ef5e404689347313d05e53ec99f034011a",
+    "plugins/aidd-dev/codex-agents/implementer.toml": "75989a5835faad8833ff50cac0dc18789d2ee18076595f121a3b663e16704156",
+    "plugins/aidd-dev/codex-agents/planner.toml": "b381250bb35e2db561d4a18725e6be7068198473232d094d2b76e840f381344b",
+    "plugins/aidd-dev/codex-agents/reviewer.toml": "678bdd2c9186dad0f185c63bbd2e5ff729e50b4160d460cdd16111723e771554",
     "plugins/aidd-dev/.codex-plugin/plugin.json": "20aed94921aed1aaa0dfcd83528601273582558f72ed33f23077605197dba94d",
     "plugins/aidd-context/skills/06-discovery/SKILL.md": "e057466afc4603a1fcac65db17f36d4d03c8403c6b2ed8b49abdcec43bc69aaf",
     "plugins/aidd-context/skills/06-discovery/actions/01-find-skill.md": "600caf7822017bfe75d40773e1673ada784227b98f5b88d4ba98a57822fa0dcf",
@@ -1378,9 +1378,9 @@
     ".codex/hooks.json": "f85805f8ed17f990b1d7a2e2f966cb47f46f9bdd21bc8911325df190b7784ea9",
     ".codex/hooks/aidd-context/update_memory.js": "140d7db788452f5f4c32316d522f595a36e06638b19a42d32e42a1a7324b7149",
     ".codex/agents/aidd-async-dev-async-orchestrator.toml": "8212b724fdacd2a20f35a2c11782c7d50b717b742f59f1a9ae08c0d831e42b4a",
-    ".codex/agents/aidd-dev-implementer.toml": "666612f997989d9f0beffc0e3438f998ea937b48259407122347430e6af6ff28",
-    ".codex/agents/aidd-dev-planner.toml": "ca9ade7a153873d4dd9a633d41ae3850a11b927333abbe336ab18fe47fd28b56",
-    ".codex/agents/aidd-dev-reviewer.toml": "0d366279100adebbf10bb0976e9057e03a8c2889d323c218e01d64b5f5038e3a",
+    ".codex/agents/aidd-dev-implementer.toml": "d1cb0353bb91cc5d0c5ffaada12b063c7d5491e94ea33eb08277783aa4c7f493",
+    ".codex/agents/aidd-dev-planner.toml": "2b37cea54f1da91c6fe2c781ada91580d36ff4656407cc4453d668bbb2c20f90",
+    ".codex/agents/aidd-dev-reviewer.toml": "7b86256d9b872d3358828a4aa74338b6d6056aced63e9b70cad88b548dc89dbd",
     ".agents/skills/aidd-vcs-04-issue-create/SKILL.md": "3983ed1c71124786fdf737ec5447637a31b1cc146eff43003978cec50c2ddc67",
     ".agents/skills/aidd-vcs-04-issue-create/evals/scenarios.json": "d113c62aae4867e425737948c39c9f687f56c3d37234eca345a2f65f1a234c30",
     ".agents/skills/aidd-vcs-04-issue-create/assets/CONTRIBUTING.md": "1372c7512c02c26e21643ae523a98d7c90ff92c03633532a8c417b4ca8d9e75f",
diff --git a/cli/tests/golden/snapshots/help/surface.json b/cli/tests/golden/snapshots/help/surface.json
index 9f8c571d2..d3cd01093 100644
--- a/cli/tests/golden/snapshots/help/surface.json
+++ b/cli/tests/golden/snapshots/help/surface.json
@@ -2,7 +2,7 @@
   {
     "invocation": "aidd",
     "exitCode": 0,
-    "help": "Usage: aidd [options] [command]\n\nGenerate AI coding assistant configurations from the AIDD framework\n\nOptions:\n  -V, --version                 Show version number\n  --verbose                     Show detailed diagnostic output (default: false)\n  -h, --help                    display help for command\n\nCommands:\n  setup [options]               Set up or update the project to a correct state\n                                — bootstraps the whole project (marketplace,\n                                framework, tools, plugins); see `framework\n                                install`, which acts on the framework alone\n  framework                     Manage the framework's lifecycle on installed\n                                tools\n  translate [options] <source>  Convert an arbitrary source into a target-native\n                                plugin tree — records nothing (see `sync` for\n                                the manifest-driven, tracked version)\n  plugin                        Manage plugins for AI tools\n  marketplace                   Manage plugin marketplaces\n  auth                          Manage authentication\n  sync [options] [files...]     Rewrite owned files from what is already there —\n                                regenerate tracked files, driven by the manifest\n                                (see `translate`, which converts a source\n                                without recording anything)\n  update|upgrade [options]      Update the aidd CLI itself to the latest version\n  doctor [options]              Detected and equipped tools, plugins, drift, and\n                                problems — across all tools or one\n  clean [options]               Remove all AIDD-managed files from the project —\n                                retires every part of AIDD; see `framework\n                                remove`, which removes the framework only\n  telemetry                     Measure what Claude Code sessions consume,\n                                locally\n  delegation                    Read this project's delegation suggestions\n  help [command]                display help for command"
+    "help": "Usage: aidd [options] [command]\n\nGenerate AI coding assistant configurations from the AIDD framework\n\nOptions:\n  -V, --version                 Show version number\n  --verbose                     Show detailed diagnostic output (default: false)\n  -h, --help                    display help for command\n\nCommands:\n  setup [options]               Set up or update the project to a correct state\n                                — bootstraps the whole project (marketplace,\n                                framework, tools, plugins); see `framework\n                                install`, which acts on the framework alone\n  framework                     Manage the framework's lifecycle on installed\n                                tools\n  translate [options] <source>  Convert an arbitrary source into a target-native\n                                plugin tree — records nothing (see `sync` for\n                                the manifest-driven, tracked version)\n  plugin                        Manage plugins for AI tools\n  marketplace                   Manage plugin marketplaces\n  auth                          Manage authentication\n  sync [options] [files...]     Rewrite owned files from what is already there —\n                                regenerate tracked files, driven by the manifest\n                                (see `translate`, which converts a source\n                                without recording anything)\n  update|upgrade [options]      Update the aidd CLI itself to the latest version\n  doctor [options]              Detected and equipped tools, plugins, drift, and\n                                problems — across all tools or one\n  clean [options]               Remove all AIDD-managed files from the project —\n                                retires every part of AIDD; see `framework\n                                remove`, which removes the framework only\n  telemetry                     Measure what Claude Code sessions consume,\n                                locally\n  help [command]                display help for command"
   },
   {
     "invocation": "aidd auth",
@@ -29,16 +29,6 @@
     "exitCode": 0,
     "help": "Usage: aidd clean [options]\n\nRemove all AIDD-managed files from the project — retires every part of AIDD; see\n`framework remove`, which removes the framework only\n\nOptions:\n  --force          Confirm file removal (skip dry-run) (default: false)\n  --scope <scope>  project (default) cleans this project alone; user undoes the\n                   machine-wide registration setup --scope user wrote and purges\n                   the shared source itself\n  -h, --help       display help for command"
   },
-  {
-    "invocation": "aidd delegation",
-    "exitCode": 0,
-    "help": "Usage: aidd delegation [options] [command]\n\nRead this project's delegation suggestions\n\nOptions:\n  -h, --help                display help for command\n\nCommands:\n  resolve [options] <task>  Resolve a configured role and native options against\n                            an installed agent\n  help [command]            display help for command"
-  },
-  {
-    "invocation": "aidd delegation resolve",
-    "exitCode": 0,
-    "help": "Usage: aidd delegation resolve [options] <task>\n\nResolve a configured role and native options against an installed agent\n\nOptions:\n  --tool <id>  AI tool whose installed agent and native options to resolve\n  --json       Print the resolution as JSON\n  -h, --help   display help for command"
-  },
   {
     "invocation": "aidd doctor",
     "exitCode": 0,
diff --git a/cli/tests/presentation/commands/auth-wiring.integration.test.ts b/cli/tests/presentation/commands/auth-wiring.integration.test.ts
index c344d513f..c406ccbdb 100644
--- a/cli/tests/presentation/commands/auth-wiring.integration.test.ts
+++ b/cli/tests/presentation/commands/auth-wiring.integration.test.ts
@@ -140,9 +140,7 @@ describe("aidd auth login — what it refuses before building anything", () => {
   it("refuses a run that names two ways of authenticating at once", async () => {
     const exit = refusing();
 
-    await expect(run("login", "--gh", "--token", "ghp_x", "--level", "user")).rejects.toThrow(
-      "exited"
-    );
+    await expect(run("login", "--gh", "--token", "ghp_x")).rejects.toThrow("exited");
 
     expect(errors[0]).toBe("Error: --gh and --token are mutually exclusive.\n");
     expect(exit).toHaveBeenCalledWith(1);
diff --git a/cli/tests/presentation/commands/delegation-wiring.integration.test.ts b/cli/tests/presentation/commands/delegation-wiring.integration.test.ts
deleted file mode 100644
index d224bfff3..000000000
--- a/cli/tests/presentation/commands/delegation-wiring.integration.test.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { Command } from "commander";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { DelegationResolution } from "../../../src/contexts/framework/domain/delegation.js";
-import { resolveHomeDir } from "../../../src/kernel/reading/home-dir.js";
-
-const execute = vi.fn();
-vi.mock("../../../src/runtime/wiring/framework.js", () => ({
-  createDeps: vi.fn(async () => ({ resolveDelegationUseCase: { execute } })),
-}));
-
-const { createDeps } = await import("../../../src/runtime/wiring/framework.js");
-const { registerDelegationCommand } = await import(
-  "../../../src/presentation/commands/delegation.js"
-);
-
-const resolution: DelegationResolution = {
-  task: "exploration",
-  tool: "codex",
-  configured: true,
-  canonicalAgent: "aidd-dev:explorer",
-  agent: { name: "personal-explorer", path: "/agents/explorer.toml", mode: "flat" },
-  requested: { model: "chosen-model", effort: "high" },
-  native: { model: "chosen-model", model_reasoning_effort: "high" },
-  nativeSurface: "agent-configuration",
-  effectiveRuntime: "unknown",
-  diagnostics: ["The installed agent pins its own model."],
-};
-let written: string[];
-let errors: string[];
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  written = [];
-  errors = [];
-  vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
-    written.push(String(chunk));
-    return true;
-  });
-  vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
-    errors.push(String(chunk));
-    return true;
-  });
-  execute.mockResolvedValue(resolution);
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-  process.exitCode = undefined;
-});
-
-async function run(...args: string[]): Promise<string> {
-  const program = new Command().exitOverride().option("--verbose");
-  registerDelegationCommand(program);
-  await program.parseAsync(["node", "aidd", ...args]);
-  return written.join("");
-}
-
-describe("aidd delegation resolve", () => {
-  it("resolves the selected task and host in the current project and home", async () => {
-    await run("--verbose", "delegation", "resolve", "exploration", "--tool", "codex");
-
-    expect(createDeps).toHaveBeenCalledWith(process.cwd(), { verbose: true }, expect.anything());
-    expect(execute).toHaveBeenCalledWith({
-      projectRoot: process.cwd(),
-      home: resolveHomeDir(),
-      env: process.env,
-      task: "exploration",
-      tool: "codex",
-    });
-  });
-
-  it("returns a machine-readable resolution without mixing in text or warnings", async () => {
-    const output = await run("delegation", "resolve", "exploration", "--tool", "codex", "--json");
-
-    expect(JSON.parse(output)).toEqual(resolution);
-    expect(errors).toEqual([]);
-  });
-
-  it("shows the installed identity, native surface and diagnostics without claiming application", async () => {
-    const output = await run("delegation", "resolve", "exploration", "--tool", "codex");
-
-    expect(output).toContain("Agent: personal-explorer (/agents/explorer.toml)");
-    expect(output).toContain(`Requested: ${JSON.stringify(resolution.requested)}`);
-    expect(output).toContain(
-      `Native suggestion (agent-configuration): ${JSON.stringify(resolution.native)}`
-    );
-    expect(output).toContain("Unspecified settings inherit. Effective runtime: unknown.");
-    expect(errors.join("")).toContain("The installed agent pins its own model.");
-  });
-
-  it("keeps missing settings inherited without inventing an agent or native options", async () => {
-    execute.mockResolvedValue({ ...resolution, configured: false, agent: undefined });
-
-    const output = await run("delegation", "resolve", "exploration", "--tool", "codex");
-
-    expect(output).toContain(
-      "No configured suggestion for exploration; the caller keeps its role and native settings."
-    );
-    expect(output).toContain("Unspecified settings inherit. Effective runtime: unknown.");
-    expect(output).not.toContain("Agent:");
-    expect(output).not.toContain("Native suggestion");
-    expect(errors).toEqual([]);
-  });
-
-  it("requires the host before attempting resolution", async () => {
-    await expect(run("delegation", "resolve", "exploration")).rejects.toMatchObject({
-      code: "commander.missingMandatoryOptionValue",
-    });
-    expect(execute).not.toHaveBeenCalled();
-  });
-
-  it("reports a resolution failure on stderr and exits unsuccessfully", async () => {
-    execute.mockRejectedValue(new Error("The selected agent is unavailable"));
-    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
-      throw new Error("exited");
-    });
-
-    await expect(run("delegation", "resolve", "exploration", "--tool", "codex")).rejects.toThrow(
-      "exited"
-    );
-    expect(exit).toHaveBeenCalledWith(1);
-    expect(errors.join("")).toContain("Error: The selected agent is unavailable");
-    expect(written).toEqual([]);
-  });
-});
diff --git a/cli/tsup.config.ts b/cli/tsup.config.ts
index dd790213d..259e75774 100644
--- a/cli/tsup.config.ts
+++ b/cli/tsup.config.ts
@@ -64,9 +64,6 @@ export default defineConfig({
     };
     options.minifySyntax = true;
     options.minifyWhitespace = true;
-    // Compact local bindings while preserving names used by errors and diagnostics.
-    options.minifyIdentifiers = true;
-    options.keepNames = true;
   },
   async onSuccess() {
     copyFileSync(
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
index d43a811b7..45a85452d 100644
--- a/docs/DELEGATION.md
+++ b/docs/DELEGATION.md
@@ -1,60 +1,9 @@
-# Delegation
+# Sub-agent models
 
-The caller chooses bounded work, invokes the agent, and accepts the result. Project settings suggest a role and native options; they do not start agents or change host settings.
+The CLI's [model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines provider defaults and native fields for the four AIDD agents.
 
-## Configure
+Installation and translation write supported settings into native agent files. Explicit agent settings take precedence. Other agents keep their own settings.
 
-Merge a `delegation` entry into the project's `.aidd/config.json`, preserving its other keys:
+Agent behavior and skills stay independent of model selection. Hosts load the installed configuration when opening a session; model availability depends on the account.
 
-```json
-{
-  "delegation": {
-    "exploration": {
-      "agent": "aidd-dev:explorer",
-      "tools": {
-        "claude": { "model": "haiku", "effort": "low" },
-        "codex": { "model": "gpt-6-luna", "effort": "high" },
-        "opencode": { "model": "openai/gpt-6-luna", "effort": "low" },
-        "copilot": { "model": "gpt-6-luna" },
-        "cursor": {}
-      }
-    }
-  }
-}
-```
-
-Use `implementation` → `aidd-dev:executor`, `validation` → `aidd-dev:validator`, and `verification` → `aidd-dev:reviewer` for the other tasks. Task names are caller-defined. Omitted settings keep native inheritance; no model is installed as a framework default.
-
-```sh
-aidd delegation resolve exploration --tool claude --json
-```
-
-Resolution verifies the installed agent and returns its native identity, requested settings, native suggestion, and target surface. `agent-configuration` fields belong in a native agent definition; `spawn` fields belong to the host's invocation. These are suggestions, not proof of application: effective runtime stays `unknown`. The caller uses a supported native equivalent, or explains why it overrides or cannot apply the suggestion. Invalid settings and unavailable agents fail with a diagnostic. Resolution writes nothing.
-
-## Model starting points
-
-Editable choices, conditional on the account's available models. Keep simple lookups direct; delegate bounded questions or repetitive work when the context saved justifies startup. Measure the whole parent-and-child run before choosing a cheaper model for a recurring task.
-
-| Host | Routine exploration / implementation / validation | Ambiguous work / review | Native model and effort |
-| --- | --- | --- | --- |
-| Claude Code | `haiku`, `low` | `opus`, `high` | `model` and `effort`; aliases resolved by Claude |
-| Codex | `gpt-6-luna`, `high` | `gpt-6.1-sol`, `high` | `model` and `model_reasoning_effort` |
-| OpenCode V2 | `openai/gpt-6-luna`, `low` | `openai/gpt-6.1-sol`, `high` | `model: provider/model#variant` |
-| GitHub Copilot | `gpt-6-luna`, inherited effort | Inherit the caller's selected model | Agent `model` / `reasoningEffort`; invocation support differs |
-| Cursor | Inherit | Inherit; select an advertised model slug when available | Plugin Task `model`; flat agent `model[effort=level]` |
-
-- **Availability:** local Codex accepted `gpt-5.6-sol` with `low`; requests for `gpt-6-luna` were rejected by the signed-in backend. The recommendation is not an account entitlement.
-- **Precedence:** Codex agent-file pins override spawn settings. Claude environment or managed settings can override requests. OpenCode variants belong to the selected model. Keep model IDs literal; avoid translating aliases between providers.
-- **Copilot:** tested 1.0.98. A per-call `gpt-6-luna` override worked while the same root CLI selection failed. Actual child effort remained `medium` despite a low request; omit effort on this account rather than claim it applied.
-- **Cursor:** the tested Free account accepts Auto/inheritance and rejects named-model execution. Plugin frontmatter model settings are stripped; use Task's advertised model slug. Plugin effort has no independent parameter; the resolver rejects it. Flat model options require an explicit model.
-
-Sources read **2026-10-15**: [Claude selection and effort](https://code.claude.com/docs/en/sub-agents), [Codex selection and precedence](https://learn.chatgpt.com/docs/agent-configuration/subagents), [OpenCode V2 agents](https://opencode.ai/v2/docs/agents), [OpenCode variants](https://opencode.ai/v2/docs/models), [Copilot CLI agent configuration](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference), [Cursor subagents](https://cursor.com/docs/subagents). Versioned observations and limitations are recorded in the [verification record](../aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md).
-
-## Test a change
-
-1. **Resolve:** use a disposable project with the generated native agents and a delegation entry. Run the command above for each host. Check native identity/options; omit settings and confirm no defaults appear. Try a missing role or unsupported option and confirm a diagnostic. Compare configuration bytes before and after.
-2. **Invoke:** start the resolved role through the native host. Test read-only exploration, a bounded implementation, a failing completion check, and an independent quality review. Confirm only the executor changes assigned files.
-3. **Inspect:** record host version, invocation, delivery mode and scope. Use native dispatch events and model/effort traces; an agent's self-report or a generated file does not prove execution. Record substitutions, unavailable values and inherited settings.
-4. **Compare:** run the same exploration and repetitive implementation directly and through a fresh child. Record all parent/child input, cached input and output tokens, latency, task retries, and independently checked output quality. Keep failed attempts visible. Host cost estimates depend on cache state and do not establish general savings.
-
-`make reload` refreshes every plugin and the managed agent table for installed hosts. Cursor local plugin imports must be enabled. Restart hosts or reload their configuration before testing discovery.
+Codex and Cursor require their flat native agent files for these settings: Codex does not discover agents staged inside a plugin, and Cursor plugin agents inherit their model.
diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md
index bdb1a318a..5ca3799bd 100644
--- a/plugins/aidd-dev/agents/executor.md
+++ b/plugins/aidd-dev/agents/executor.md
@@ -9,13 +9,9 @@ Implement assigned work, choosing the technique within the agreed outcome and cr
 
 # Behavior
 
-- **Resolve local technical obstacles** within owned scope and project conventions; report material choices.
-- **Report ambiguity or changes needed** to outcomes, criteria, or dependencies outside owned scope; leave those decisions to the caller.
-- **Validate affected workflows**, repair failures, and repeat; debug an unclear cause first.
-- **Report COMPLETE** only when every assigned criterion and mandatory check passes; keep unmet criteria and skipped checks visible in remaining work.
-- **Stay within assigned responsibility** and write ownership; update shared-plan status only with whole-plan ownership.
-- **Commit only when authorized** and owning the Git index; leave shared operations to the caller.
-- **Return changes and evidence directly**; leave independent review and delegation to the caller, and report inaccessible human actions.
+- **Implement within owned scope**, making local technical choices; escalate material changes to scope or dependencies.
+- **Verify and repair the result**; report unmet criteria and missing checks.
+- **Respect file and shared-operation ownership**; return changes and evidence to the caller.
 
 # Output
 
diff --git a/plugins/aidd-dev/agents/explorer.md b/plugins/aidd-dev/agents/explorer.md
index 2600a2620..de7f76b9e 100644
--- a/plugins/aidd-dev/agents/explorer.md
+++ b/plugins/aidd-dev/agents/explorer.md
@@ -9,8 +9,7 @@ Find the code and context that answer the caller's question.
 
 # Behavior
 
-- **Read the relevant code**, including callers and dependencies needed to explain the behavior; prefer targeted searches over broad scans.
-- **Return useful context**: file paths, symbols, execution paths, existing patterns, or short code excerpts. Explain what each establishes so the caller can use the findings without repeating the exploration.
+- **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.
 
diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md
index 3a009dc83..1ff2d9c4c 100644
--- a/plugins/aidd-dev/agents/reviewer.md
+++ b/plugins/aidd-dev/agents/reviewer.md
@@ -9,16 +9,13 @@ Review finished work independently and identify quality or coherence gaps that a
 
 # Behavior
 
-- **Read the actual work and need** in a fresh context, alongside project conventions and existing validation evidence.
-- **Apply the quality checklist** in the installed review skill's supporting `references/quality-checklist.md`, extended with project review rules. Explain relevant coverage gaps.
-- **Look beyond isolated parts**: check whether the delivered logic forms a coherent whole and serves the intended need. Leave acceptance completion to the validator.
-- **Tie findings to evidence and impact**; distinguish concrete defects from optional suggestions. Flag ambiguity instead of guessing.
-- **Use an appropriate review skill** when it fits. Its report carries the findings; avoid a second parallel report. Review code quality and relevancy without repeating functional validation.
-- **Keep the work unchanged**; return findings and the smallest suggested corrections to the caller.
+- **Review the actual work and need independently**, using project conventions and the installed review skill's `references/quality-checklist.md`. Check coherence, relevance, and gaps in existing validation evidence; leave acceptance completion to the validator.
+- **Tie findings to evidence and impact**; distinguish defects from suggestions, name uncertainty, and suggest the smallest correction.
+- **Keep the work unchanged** and return findings to the caller. An optional review skill's report replaces this output; do not duplicate it.
 
 # Output
 
-Return the skill report when one exists; otherwise use this short format.
+Return a concise review.
 
 ```markdown
 **Review:** <no actionable findings | changes needed | insufficient evidence>
@@ -29,5 +26,3 @@ Return the skill report when one exists; otherwise use this short format.
 # Skills you may invoke
 
 - `/aidd-dev:05-review`
-- `/aidd-dev:04-audit`
-- `/aidd-refine:02-challenge`
diff --git a/plugins/aidd-dev/agents/validator.md b/plugins/aidd-dev/agents/validator.md
index dc54b0f34..c04f16414 100644
--- a/plugins/aidd-dev/agents/validator.md
+++ b/plugins/aidd-dev/agents/validator.md
@@ -9,14 +9,13 @@ Verify whether the requested outcome has been delivered.
 
 # Behavior
 
-- **Check the request and acceptance criteria** against the delivered candidate and mandatory project checks.
-- **Use observable evidence**; reuse results only when they cover the same unchanged candidate. Run missing checks when possible.
-- **Report validated only when the requested scope passes**. Otherwise explain what failed or could not be checked and why.
-- **Keep the work and criteria unchanged**; return the conclusion to the caller for repairs or decisions.
+- **Check the requested outcome, acceptance criteria, and mandatory project checks** using observable evidence. Reuse results only for the same unchanged candidate; run missing checks when possible.
+- **Report yes only when the assigned scope passes**; otherwise explain what failed or could not be checked and why.
+- **Keep the work and criteria unchanged**; return the verdict to the caller for repairs or decisions.
 
 # Output
 
-Return one concise verdict for the assigned scope, with decisive evidence for yes or the failures and verification blockers for no; avoid a task-by-task report.
+Return one concise verdict for the assigned scope.
 
 ```markdown
 **Validated:** <yes | no>
diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index 8e9be4880..e6e69076a 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -13,7 +13,7 @@ The architecture projection (files to modify, create, delete, each with a one-li
 ## Process
 
 1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions.
-   - The caller may delegate independent questions by codebase domain to explorers, each with a scope and requested findings. Consult the exploration suggestion with `aidd delegation resolve exploration --tool <host> --json` before spawning. Combine their sourced answers; resolve contradictions or keep the uncertainty visible. Isolated explorers return directly.
+   - Delegate independent domain questions to explorers with a scope and expected findings; reconcile their sourced answers and keep unresolved uncertainty visible.
 2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
 3. **Select.** Keep the project rules that apply to the projection.
 
diff --git a/plugins/aidd-dev/skills/10-batch/actions/01-batch.md b/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
index 13f85d67a..9edbd4ae3 100644
--- a/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
+++ b/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
@@ -17,7 +17,7 @@ One row per dispatched agent, identified by its name or ID. Status is `Done` (ta
 
 1. **Read.** Take `prompt` from the arguments; if empty, ask the user.
 2. **Split.** Divide the prompt into distinct, independent tasks. Inline, no agent.
-3. **Launch.** Resolve the implementation suggestion with `aidd delegation resolve implementation --tool <host> --json`, retaining native inheritance when unconfigured. Surface resolution errors; the caller owns any override. Spawn one scoped executor per task, all in parallel with fresh contexts. Supply each task's criteria, write ownership, checks, and commit policy. Track each agent's name or ID; require its outcome, changed files, validation evidence, and remaining work.
+3. **Launch.** Spawn one scoped executor per task, all in parallel with fresh contexts. Supply each task's criteria, write ownership, checks, and commit policy. Track each agent's name or ID; require its outcome, changed files, validation evidence, and remaining work.
 4. **Collect.** Wait for every dispatched agent to finish or report a blocker. Preserve blocked and failed outcomes; mark an agent that exits with an error as `Failed` even if it returns no summary.
 5. **Report.** Print exactly one final table using the output columns, nothing else. Base each status and result on the collected evidence.
 
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
index 94fecf4ae..716ac6fe7 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
@@ -6,7 +6,6 @@
 - A request carrying nothing else is not one to run: say so and stop.
 - Ask only before spending money, taking an irreversible action, or making a decision that requires user authority.
 - An exception stops the action it guards, not the rest of the request. Say what was withheld and what would release it.
-- Before spawning, run `aidd delegation resolve <task> --tool <host> --json` for `exploration`, `implementation`, `validation`, or `verification`. Use the returned native identity and settings as suggestions; explain material overrides. Missing settings inherit. Surface configuration errors or an unavailable resolver instead of claiming a suggestion was applied.
 
 ## Auto
 

From a629e2e06424587dfc2df41078594f3656ff3a5f Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 19:36:26 +0800
Subject: [PATCH 27/73] test(cli): cover native agent and activation contracts

---
 .../contexts/tools/domain/profiles/copilot.unit.test.ts  | 1 +
 .../contexts/tools/domain/profiles/cursor.unit.test.ts   | 9 +++++++++
 .../tools/domain/profiles/cursor/build.unit.test.ts      | 8 ++++++++
 3 files changed, 18 insertions(+)

diff --git a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
index 13e536c4d..36b4b008d 100644
--- a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
@@ -522,6 +522,7 @@ describe("copilot declarations the rest of the CLI reads", () => {
     expect(nativeActivationOf("copilot")).toMatchObject({
       binary: "copilot",
       upgradeVerb: "update",
+      updateVerb: "update",
       enableVerb: "install",
       disableVerb: "uninstall",
       sourceCheckVerb: "update",
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
index 0c2910de6..da5c7d427 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
@@ -58,6 +58,15 @@ describe("cursor", () => {
   });
 
   describe("capabilities.agents.convertFrontmatter()", () => {
+    it("keeps model inheritance for AIDD agents installed as native plugins", () => {
+      const result = cursor.capabilities.agents.convertFrontmatter(
+        { name: "explorer", description: "Role" },
+        "explorer.md",
+        "aidd-dev"
+      );
+      expect(result).toEqual({ name: "explorer", description: "Role" });
+    });
+
     it("preserves an explicitly selected agent model", () => {
       const fm = { name: "alexia", description: "Agent", model: "opus" };
       const result = cursor.capabilities.agents.convertFrontmatter(fm);
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts
index 586104ec1..8c4341226 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/build.unit.test.ts
@@ -43,6 +43,14 @@ describe("buildCursorContract()", () => {
     expect(parseFrontmatter(first).frontmatter.name).toBe("first-plugin-planner");
     expect(parseFrontmatter(second).frontmatter.name).toBe("second-plugin-planner");
   });
+
+  it("drops only the file's final .md from a plugin agent's name", () => {
+    const transform = supported(buildCursorContract().artifacts.agents).transform;
+    const output = transform?.(AGENT_SOURCE, "aidd-dev", "read.md-first.md") ?? "";
+
+    expect(parseFrontmatter(output).frontmatter.name).toBe("aidd-dev-read.md-first");
+  });
+
   it("declares Cursor's own plugin manifest path, schema and root token", () => {
     const contract = buildCursorContract();
 

From 76fea091e0940b0c54d4b571fd7eca05279bf3b3 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 20:09:50 +0800
Subject: [PATCH 28/73] feat(cli): make native agents an explicit opt-in

---
 AGENTS.md                                     |   8 +-
 README.md                                     |   2 +-
 .../2026_10_14_sub_agents/verification.md     |  10 +-
 cli/README.md                                 |   4 +-
 cli/aidd_docs/memory/codebase-map.md          |   1 +
 .../assets}/agents/executor.md                |   0
 .../assets}/agents/explorer.md                |   0
 .../assets}/agents/reviewer.md                |   0
 .../assets}/agents/validator.md               |   0
 cli/src/cli.ts                                |   2 +
 .../agents/manage-agents-use-case.ts          | 159 +++++++++++++
 .../framework/application/clean-use-case.ts   |  27 ++-
 .../domain/ports/agent-installation-store.ts  |  11 +
 .../agent-installation-store-adapter.ts       |  56 +++++
 .../domain/capabilities/agents-capability.ts  |  20 +-
 .../domain/formats/agent-frontmatter-strip.ts |   3 +-
 .../tools/domain/formats/agent-models.json    |  18 +-
 .../tools/domain/formats/agent-models.ts      |  77 +++---
 .../tools/domain/marketplace-catalog.ts       |   9 +-
 .../tools/domain/profiles/claude/build.ts     |   7 +-
 .../tools/domain/profiles/claude/profile.ts   |   3 +-
 .../domain/profiles/codex/codex-agent-toml.ts |   7 +-
 .../tools/domain/profiles/codex/profile.ts    |   3 +-
 .../tools/domain/profiles/copilot/build.ts    |   7 +-
 .../tools/domain/profiles/copilot/profile.ts  |   3 +-
 .../tools/domain/profiles/cursor/build.ts     |   2 -
 .../tools/domain/profiles/cursor/profile.ts   |   3 -
 .../tools/domain/profiles/opencode/build.ts   |   2 -
 .../tools/domain/profiles/opencode/profile.ts |   2 -
 .../translate/domain/content-translator.ts    |  29 +--
 cli/src/presentation/commands/agents.ts       |  52 ++++
 cli/src/runtime/assets/agent-sources.ts       |  11 +
 cli/src/runtime/wiring/framework.ts           |  14 +-
 .../context-boundary.arch.test.ts             |   4 +-
 .../architecture/folder-size.arch.test.ts     |   7 +-
 .../orchestrator-deps.arch.test.ts            |   3 +-
 ...manage-agents-use-case.integration.test.ts | 124 ++++++++++
 .../clean-opt-in-agents.integration.test.ts   | 128 ++++++++++
 ...allation-store-adapter.integration.test.ts |  50 ++++
 .../agent-frontmatter-strip.unit.test.ts      |   3 +-
 .../domain/formats/agent-models.unit.test.ts  | 222 ++++++++++--------
 .../tools/domain/profiles/cursor.unit.test.ts |   3 +-
 .../plugin-content-translator.unit.test.ts    |  18 +-
 cli/tests/e2e/agent-models.e2e.test.ts        | 104 --------
 cli/tests/e2e/agents.e2e.test.ts              | 184 +++++++++++++++
 cli/tests/golden/snapshots/help/surface.json  |  17 +-
 docs/DELEGATION.md                            |  14 +-
 plugins/aidd-dev/.claude-plugin/plugin.json   |   8 +-
 plugins/aidd-dev/CATALOG.md                   |   8 +-
 49 files changed, 1076 insertions(+), 373 deletions(-)
 rename {plugins/aidd-dev => cli/assets}/agents/executor.md (100%)
 rename {plugins/aidd-dev => cli/assets}/agents/explorer.md (100%)
 rename {plugins/aidd-dev => cli/assets}/agents/reviewer.md (100%)
 rename {plugins/aidd-dev => cli/assets}/agents/validator.md (100%)
 create mode 100644 cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
 create mode 100644 cli/src/contexts/framework/domain/ports/agent-installation-store.ts
 create mode 100644 cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
 create mode 100644 cli/src/presentation/commands/agents.ts
 create mode 100644 cli/src/runtime/assets/agent-sources.ts
 create mode 100644 cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
 create mode 100644 cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
 create mode 100644 cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
 delete mode 100644 cli/tests/e2e/agent-models.e2e.test.ts
 create mode 100644 cli/tests/e2e/agents.e2e.test.ts

diff --git a/AGENTS.md b/AGENTS.md
index fda94fc0f..9dc0cf672 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,10 +39,10 @@ Use available agents when useful. The caller owns scope, delegation, and final a
 <!-- aidd_agents:start -->
 | name | role |
 | --- | --- |
-| @aidd-dev-explorer (Codex, Cursor, OpenCode), @aidd-dev:explorer (Claude, Copilot) | Explore the codebase and return relevant files, code, and explanations for a scoped question. |
-| @aidd-dev-executor (Codex, Cursor, OpenCode), @aidd-dev:executor (Claude, Copilot) | Implement assigned work and return changes with verification evidence. |
-| @aidd-dev-validator (Codex, Cursor, OpenCode), @aidd-dev:validator (Claude, Copilot) | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
-| @aidd-dev-reviewer (Codex, Cursor, OpenCode), @aidd-dev:reviewer (Claude, Copilot) | Review quality and coherence against project conventions and the quality checklist. |
+| @aidd-dev-explorer | Explore the codebase and return relevant files, code, and explanations for a scoped question. |
+| @aidd-dev-executor | Implement assigned work and return changes with verification evidence. |
+| @aidd-dev-validator | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
+| @aidd-dev-reviewer | Review quality and coherence against project conventions and the quality checklist. |
 <!-- aidd_agents:end -->
 
 ## Memory Management
diff --git a/README.md b/README.md
index 2ddd3492c..4f0a67283 100644
--- a/README.md
+++ b/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>4 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/)
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 5e5cd8387..550aaa890 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -1,12 +1,12 @@
 # Sub-agent verification
 
-## Installed model defaults, 2026-10-15
+## CLI opt-in, 2026-10-15
 
-The [CLI configuration](../../../../cli/src/contexts/tools/domain/formats/agent-models.json) now owns provider defaults and native fields. Conversion applies them to the four AIDD roles; explicit settings survive. The resolver command and workflow dependencies on it are removed. Agent behaviors are reduced to three capabilities each.
+The four agents are bundled with the CLI, outside plugins. Explicit installation selects a provider and IDE using the [CLI configuration](../../../../cli/src/contexts/tools/domain/formats/agent-models.json). Generic conversion applies no model defaults. Skills remain independent of installation and model selection.
 
-- **Checks:** 6,499 CLI tests pass, one skipped; 498 script tests pass. Typecheck, lint, architecture, type honesty and unused-code checks pass. Bundle: 684.5 KB / 695 KB.
-- **Headers:** nine built-CLI cases inspect all four real agent sources across native flat and marketplace outputs. Ordinary installation tests also inspect translated file paths and contents. A provider-switch test verifies Copilot's native Anthropic identifier; removing its lookup makes that test fail.
-- **Limits:** Codex loads the flat agent files, not TOMLs staged inside a plugin. Cursor flat agents accept the configured selector; plugin agents inherit their model. These file checks do not establish account access to a model or effective runtime selection.
+- **CLI:** 17 built-CLI cases pass, covering seven supported provider/IDE pairs, repeat installation, provider changes, removal, invalid selections, personal-file conflicts, cleanup, and a framework distribution without these agents.
+- **Ownership:** integration cases cover the project ledger, modified files, safe paths, and cleanup. Removing the ownership guard makes its named test fail; restored code passes. Cleanup preserves personal directory links; restoring recursive directory removal makes that test fail.
+- **Limits:** Native files are written directly into each host's agent directory. These checks establish headers and file behavior, not account access or effective runtime model selection.
 
 ## Earlier runtime evidence
 
diff --git a/cli/README.md b/cli/README.md
index 90b609533..720c59ae6 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -121,9 +121,9 @@ 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 |
 
-## Agent models
+## Agents
 
-The [bundled configuration](src/contexts/tools/domain/formats/agent-models.json) supplies model and effort defaults when installing or translating AIDD agents. See [sub-agent models](../docs/DELEGATION.md).
+Opt in with `aidd agents install --provider openai --ide codex`; see [agent installation](../docs/DELEGATION.md).
 
 ## Translate
 
diff --git a/cli/aidd_docs/memory/codebase-map.md b/cli/aidd_docs/memory/codebase-map.md
index 6af1d9f42..a69bbbfcf 100644
--- a/cli/aidd_docs/memory/codebase-map.md
+++ b/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/
diff --git a/plugins/aidd-dev/agents/executor.md b/cli/assets/agents/executor.md
similarity index 100%
rename from plugins/aidd-dev/agents/executor.md
rename to cli/assets/agents/executor.md
diff --git a/plugins/aidd-dev/agents/explorer.md b/cli/assets/agents/explorer.md
similarity index 100%
rename from plugins/aidd-dev/agents/explorer.md
rename to cli/assets/agents/explorer.md
diff --git a/plugins/aidd-dev/agents/reviewer.md b/cli/assets/agents/reviewer.md
similarity index 100%
rename from plugins/aidd-dev/agents/reviewer.md
rename to cli/assets/agents/reviewer.md
diff --git a/plugins/aidd-dev/agents/validator.md b/cli/assets/agents/validator.md
similarity index 100%
rename from plugins/aidd-dev/agents/validator.md
rename to cli/assets/agents/validator.md
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 945e7a7d1..b42ac9d2e 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1,5 +1,6 @@
 import { platform } from "node:os";
 import { Command } from "commander";
+import { registerAgentsCommand } from "./presentation/commands/agents.js";
 import { registerAuthCommand } from "./presentation/commands/auth.js";
 import { registerCleanCommand } from "./presentation/commands/clean.js";
 import { registerDoctorCommand } from "./presentation/commands/doctor.js";
@@ -32,6 +33,7 @@ program
 
 registerSetupCommand(program);
 registerFrameworkCommand(program);
+registerAgentsCommand(program);
 registerTranslateCommand(program);
 registerPluginCommand(program);
 registerMarketplaceCommand(program);
diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
new file mode 100644
index 000000000..77f18bd55
--- /dev/null
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -0,0 +1,159 @@
+import { join } from "node:path";
+import { parseFrontmatter } from "../../../../kernel/markdown.js";
+import type { FileReader } from "../../../../kernel/ports/file-reader.js";
+import type { FileWriter } from "../../../../kernel/ports/file-writer.js";
+import type { Hasher } from "../../../../kernel/ports/hasher.js";
+import type { AgentsCapability } from "../../../tools/domain/capabilities/agents-capability.js";
+import type { HasAgents } from "../../../tools/domain/contracts.js";
+import {
+  type AgentHost,
+  type AgentProvider,
+  agentModelOptions,
+} from "../../../tools/domain/formats/agent-models.js";
+import { getAiToolConfig } from "../../../tools/domain/registry.js";
+import {
+  AGENT_INSTALLATIONS_PATH,
+  type AgentInstallationStore,
+  type AgentInstallations,
+} from "../../domain/ports/agent-installation-store.js";
+import { assertProjectPathWithinRoot } from "../ownership/project-path-boundary.js";
+
+interface AgentTarget {
+  projectRoot: string;
+  host: AgentHost;
+}
+
+export class ManageAgentsUseCase {
+  constructor(
+    private readonly fs: FileReader & FileWriter,
+    private readonly store: AgentInstallationStore,
+    private readonly hasher: Hasher,
+    private readonly sources: Readonly<Record<string, string>>
+  ) {}
+
+  async install(options: AgentTarget & { provider: AgentProvider }): Promise<number> {
+    const model = agentModelOptions(options.host, options.provider);
+    const installed = await this.load(options.projectRoot);
+    const capability = this.capability(options.host);
+    const entries = Object.entries(this.sources).map(([name, source]) => {
+      const { frontmatter, body } = parseFrontmatter(source);
+      return {
+        name,
+        path: this.path(options.projectRoot, capability, name),
+        content: capability.serialize(
+          { ...capability.convertFrontmatter({ ...frontmatter, name }, `${name}.md`), ...model },
+          body
+        ),
+      };
+    });
+    for (const entry of entries)
+      await this.assertOwned(
+        options.projectRoot,
+        entry.path,
+        installed[options.host]?.[entry.name]
+      );
+    let written = 0;
+    const hashes = { ...installed[options.host] };
+    for (const { name, path, content } of entries) {
+      const hash = this.hasher.hash(content);
+      if (!(await this.fs.fileExists(path)) || !(await this.fs.readFileHash(path)).equals(hash)) {
+        await this.fs.writeFile(path, content);
+        written++;
+      }
+      hashes[name] = hash;
+    }
+    installed[options.host] = hashes;
+    await this.store.save(options.projectRoot, installed);
+    return written;
+  }
+
+  async remove(options: AgentTarget): Promise<number> {
+    const installed = await this.load(options.projectRoot);
+    const entries = await this.removable(options.projectRoot, installed, options.host);
+    const count = await this.delete(entries);
+    delete installed[options.host];
+    await this.store.save(options.projectRoot, installed);
+    return count;
+  }
+
+  async preview(projectRoot: string): Promise<Array<{ toolId: AgentHost; fileCount: number }>> {
+    const installed = await this.load(projectRoot);
+    const tools: Array<{ toolId: AgentHost; fileCount: number }> = [];
+    for (const host of Object.keys(installed)) {
+      const entries = installed[host as AgentHost];
+      if (entries !== undefined)
+        tools.push({ toolId: host as AgentHost, fileCount: Object.keys(entries).length });
+    }
+    return tools;
+  }
+
+  async assertRemovable(projectRoot: string): Promise<void> {
+    await this.removable(projectRoot, await this.load(projectRoot));
+  }
+
+  async removeAll(projectRoot: string): Promise<number> {
+    const entries = await this.removable(projectRoot, await this.load(projectRoot));
+    const count = await this.delete(entries);
+    await this.store.save(projectRoot, {});
+    return count;
+  }
+
+  private capability(host: AgentHost): AgentsCapability {
+    return (getAiToolConfig(host).capabilities as HasAgents).agents;
+  }
+
+  private path(root: string, capability: AgentsCapability, name: string): string {
+    const path = capability.buildInstallPath(`${name}.md`);
+    if (path === null) throw new Error(`Agent ${name} has no native install path.`);
+    return join(root, path);
+  }
+
+  private async load(root: string): Promise<AgentInstallations> {
+    await assertProjectPathWithinRoot(this.fs, root, join(root, AGENT_INSTALLATIONS_PATH));
+    const installed = await this.store.load(root);
+    for (const entries of Object.values(installed)) {
+      for (const name of Object.keys(entries)) {
+        if (!Object.hasOwn(this.sources, name)) throw new Error(`Unknown managed agent: ${name}`);
+      }
+    }
+    return installed;
+  }
+
+  private async assertOwned(
+    root: string,
+    path: string,
+    expected: ReturnType<Hasher["hash"]> | undefined
+  ): Promise<void> {
+    await assertProjectPathWithinRoot(this.fs, root, path);
+    if (!(await this.fs.fileExists(path))) return;
+    if (expected === undefined) throw new Error(`Agent file is not owned by AIDD: ${path}`);
+    if (!(await this.fs.readFileHash(path)).equals(expected))
+      throw new Error(`Agent file was modified; preserve or move it before continuing: ${path}`);
+  }
+
+  private async removable(
+    root: string,
+    installed: AgentInstallations,
+    onlyHost?: AgentHost
+  ): Promise<string[]> {
+    const paths: string[] = [];
+    for (const [host, entries] of Object.entries(installed)) {
+      if (onlyHost !== undefined && host !== onlyHost) continue;
+      const capability = this.capability(host as AgentHost);
+      for (const [name, hash] of Object.entries(entries)) {
+        const path = this.path(root, capability, name);
+        await this.assertOwned(root, path, hash);
+        if (await this.fs.fileExists(path)) paths.push(path);
+      }
+    }
+    return paths;
+  }
+
+  private async delete(paths: readonly string[]): Promise<number> {
+    for (const path of paths) {
+      await this.fs.deleteFile(path);
+      if (await this.fs.fileExists(path)) throw new Error(`Could not remove agent: ${path}`);
+    }
+    return paths.length;
+  }
+}
diff --git a/cli/src/contexts/framework/application/clean-use-case.ts b/cli/src/contexts/framework/application/clean-use-case.ts
index 237c32067..aff83b1c0 100644
--- a/cli/src/contexts/framework/application/clean-use-case.ts
+++ b/cli/src/contexts/framework/application/clean-use-case.ts
@@ -37,6 +37,7 @@ import { aiddGitignoreEntries } from "../domain/manifest-gitignore-entries.js";
 import type { InstalledPlugin } from "../domain/plugins/installed-plugin.js";
 import type { ManifestRepository } from "../domain/ports/manifest-repository.js";
 import type { UserSourceReferences } from "../domain/ports/user-source-references.js";
+import type { ManageAgentsUseCase } from "./agents/manage-agents-use-case.js";
 import type { GitignoreUseCase } from "./gitignore-use-case.js";
 import {
   assertNoForeignNativeRefs,
@@ -149,19 +150,42 @@ export class CleanUseCase {
       HostPluginRegistryReader
     > = new Map(),
     private readonly userManifestRepo?: ManifestRepository,
-    private readonly nativeSources: ReadonlyMap<AiToolId, NativeMarketplaceSourceReader> = new Map()
+    private readonly nativeSources: ReadonlyMap<
+      AiToolId,
+      NativeMarketplaceSourceReader
+    > = new Map(),
+    private readonly agents?: Pick<ManageAgentsUseCase, "preview" | "assertRemovable" | "removeAll">
   ) {}
 
   async execute(options: CleanOptions): Promise<CleanResult> {
     const manifest = await this.manifestRepo.load();
+    const agentTools = (await this.agents?.preview(options.projectRoot)) ?? [];
     if (manifest === null) {
+      if (agentTools.length > 0) {
+        const preview: CleanPreview = {
+          tools: agentTools,
+          totalFileCount: agentTools.reduce((sum, tool) => sum + tool.fileCount, 0),
+          nativeRegistrations: [],
+        };
+        const dryRun = await this.confirmOrDryRun(options, preview);
+        if (dryRun !== null) return dryRun;
+        const count = (await this.agents?.removeAll(options.projectRoot)) ?? 0;
+        return { dryRun: false, manifestFound: true, preview, fileCount: count };
+      }
       const emptyPreview: CleanPreview = { tools: [], totalFileCount: 0, nativeRegistrations: [] };
       return { dryRun: false, manifestFound: false, preview: emptyPreview, fileCount: 0 };
     }
     const home = this.homeDir();
     const preview = await this.buildPreview(manifest, home, options.projectRoot);
+    for (const agentTool of agentTools) {
+      const tool = preview.tools.find((entry) => entry.toolId === agentTool.toolId);
+      if (tool === undefined) preview.tools.push(agentTool);
+      else tool.fileCount += agentTool.fileCount;
+      preview.totalFileCount += agentTool.fileCount;
+    }
     const dryRunResult = await this.confirmOrDryRun(options, preview);
     if (dryRunResult !== null) return dryRunResult;
+    await this.agents?.assertRemovable(options.projectRoot);
     await this.assertNativeSourcesUnchanged(manifest, options.projectRoot);
     for (const toolId of manifest.getInstalledToolIds()) {
       if (!isAiToolId(toolId)) continue;
@@ -197,6 +221,7 @@ export class CleanUseCase {
     await this.purgeNativeCaches(home, undone);
     let deleted = await this.deleteAllToolFiles(manifest, options.projectRoot);
     deleted += await this.deleteMachineLocalFiles(manifest, options.projectRoot);
+    deleted += (await this.agents?.removeAll(options.projectRoot)) ?? 0;
     await this.removeAiddState(options.projectRoot);
     // Exactly what the pipeline added on install, never a subset of it.
     await this.gitignoreUseCase.remove(options.projectRoot, aiddGitignoreEntries(manifest));
diff --git a/cli/src/contexts/framework/domain/ports/agent-installation-store.ts b/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
new file mode 100644
index 000000000..6144f6f92
--- /dev/null
+++ b/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
@@ -0,0 +1,11 @@
+import type { FileHash } from "../../../../kernel/file.js";
+import type { AgentHost } from "../../../tools/domain/formats/agent-models.js";
+
+export type AgentInstallations = Partial<Record<AgentHost, Record<string, FileHash>>>;
+
+export interface AgentInstallationStore {
+  load(projectRoot: string): Promise<AgentInstallations>;
+  save(projectRoot: string, installations: AgentInstallations): Promise<void>;
+}
+
+export const AGENT_INSTALLATIONS_PATH = ".aidd/agents.json";
diff --git a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
new file mode 100644
index 000000000..e5aba24b4
--- /dev/null
+++ b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
@@ -0,0 +1,56 @@
+import { join } from "node:path";
+import { FileHash } from "../../../kernel/file.js";
+import type { FileReader } from "../../../kernel/ports/file-reader.js";
+import type { FileWriter } from "../../../kernel/ports/file-writer.js";
+import { isAgentHost } from "../../tools/domain/formats/agent-models.js";
+import {
+  AGENT_INSTALLATIONS_PATH,
+  type AgentInstallationStore,
+  type AgentInstallations,
+} from "../domain/ports/agent-installation-store.js";
+
+export class AgentInstallationStoreAdapter implements AgentInstallationStore {
+  constructor(private readonly fs: FileReader & FileWriter) {}
+
+  async load(projectRoot: string): Promise<AgentInstallations> {
+    const path = join(projectRoot, AGENT_INSTALLATIONS_PATH);
+    if (!(await this.fs.fileExists(path))) return {};
+    const parsed: unknown = JSON.parse(await this.fs.readFile(path));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      throw new Error(`Invalid agent ownership file: ${path}`);
+    const installations: AgentInstallations = {};
+    for (const [host, entries] of Object.entries(parsed)) {
+      if (
+        !isAgentHost(host) ||
+        typeof entries !== "object" ||
+        entries === null ||
+        Array.isArray(entries)
+      )
+        throw new Error(`Invalid agent ownership file: ${path}`);
+      installations[host] = Object.fromEntries(
+        Object.entries(entries).map(([name, hash]) => {
+          if (typeof hash !== "string") throw new Error(`Invalid agent hash: ${name}`);
+          return [name, new FileHash(hash)];
+        })
+      );
+    }
+    return installations;
+  }
+
+  async save(projectRoot: string, installations: AgentInstallations): Promise<void> {
+    const path = join(projectRoot, AGENT_INSTALLATIONS_PATH);
+    if (Object.keys(installations).length === 0) {
+      await this.fs.deleteFile(path);
+      if (await this.fs.fileExists(path))
+        throw new Error(`Could not remove agent ownership file: ${path}`);
+      return;
+    }
+    const data = Object.fromEntries(
+      Object.entries(installations).map(([host, entries]) => [
+        host,
+        Object.fromEntries(Object.entries(entries).map(([name, hash]) => [name, hash.value])),
+      ])
+    );
+    await this.fs.writeFile(path, `${JSON.stringify(data, null, 2)}\n`);
+  }
+}
diff --git a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
index a0651806f..c37dffd6f 100644
--- a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
+++ b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
@@ -56,11 +56,7 @@ export class AgentsCapability {
       directory: string;
       toolSuffix: string;
       format: "markdown" | "toml";
-      modelOptions?: (
-        fm: Record<string, unknown>,
-        plugin?: string,
-        fileName?: string
-      ) => Record<string, unknown>;
+      effortField?: string;
       userFileExt?: string;
       buildInstallPath?: (fileName: string) => string | null;
       convertFrontmatter?: (
@@ -93,13 +89,14 @@ export class AgentsCapability {
     return !otherSuffixes.some((s) => basename.endsWith(s));
   }
 
-  convertFrontmatter(
-    fm: Record<string, unknown>,
-    fileName?: string,
-    plugin?: string
-  ): Record<string, unknown> {
+  convertFrontmatter(fm: Record<string, unknown>, fileName?: string): Record<string, unknown> {
     const converted = this.convertAgentFrontmatter(fm, fileName);
-    return { ...converted, ...this.params.modelOptions?.(fm, plugin, fileName) };
+    if (fm.model !== undefined) converted.model = fm.model;
+    const effortField = this.params.effortField;
+    if (effortField !== undefined && fm[effortField] !== undefined) {
+      converted[effortField] = fm[effortField];
+    }
+    return converted;
   }
 
   private convertAgentFrontmatter(
@@ -111,7 +108,6 @@ export class AgentsCapability {
     return {
       name,
       description: fm.description,
-      ...(this.params.format === "toml" && fm.model !== undefined ? { model: fm.model } : {}),
     };
   }
 
diff --git a/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts b/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts
index 6aff4c5ad..bf543752e 100644
--- a/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts
+++ b/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts
@@ -4,10 +4,11 @@ export const COPILOT_AGENT_FRONTMATTER_KEYS: readonly [
   "name",
   "description",
   "model",
+  "reasoningEffort",
   "tools",
   "agents",
   "argument-hint",
-] = ["name", "description", "model", "tools", "agents", "argument-hint"];
+] = ["name", "description", "model", "reasoningEffort", "tools", "agents", "argument-hint"];
 
 /** Cursor-supported frontmatter keys: Cursor documents only name, description and model —
  * never tools or color. */
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.json b/cli/src/contexts/tools/domain/formats/agent-models.json
index d766c0b3f..6c334c58e 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.json
+++ b/cli/src/contexts/tools/domain/formats/agent-models.json
@@ -1,6 +1,4 @@
 {
-  "plugin": "aidd-dev",
-  "roles": ["explorer", "executor", "reviewer", "validator"],
   "providers": {
     "openai": {
       "model": "gpt-6-luna",
@@ -14,30 +12,30 @@
       }
     }
   },
-  "tools": {
+  "hosts": {
     "claude": {
-      "provider": "anthropic",
+      "ide": "claude-code",
+      "providers": ["anthropic"],
       "effortField": "effort"
     },
     "codex": {
-      "provider": "openai",
+      "providers": ["openai"],
       "effortField": "model_reasoning_effort"
     },
     "copilot": {
-      "provider": "openai",
+      "providers": ["openai", "anthropic"],
       "effortField": "reasoningEffort"
     },
     "opencode": {
-      "provider": "openai",
+      "providers": ["openai", "anthropic"],
       "effortPrefix": "#",
       "effortSuffix": "",
       "providerPrefix": true
     },
     "cursor": {
-      "provider": "anthropic",
+      "providers": ["anthropic"],
       "effortPrefix": "[effort=",
-      "effortSuffix": "]",
-      "marketplace": false
+      "effortSuffix": "]"
     }
   }
 }
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.ts b/cli/src/contexts/tools/domain/formats/agent-models.ts
index a0cdda42b..edc65df6d 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.ts
+++ b/cli/src/contexts/tools/domain/formats/agent-models.ts
@@ -1,45 +1,46 @@
 import models from "./agent-models.json" with { type: "json" };
 
-type ModelHost = keyof typeof models.tools;
+export type AgentHost = keyof typeof models.hosts;
+export type AgentProvider = keyof typeof models.providers;
 
-/** Native agent fields shared by ordinary installation and build projections. */
+export function isAgentHost(value: unknown): value is AgentHost {
+  return typeof value === "string" && Object.hasOwn(models.hosts, value);
+}
+
+export function isAgentProvider(value: unknown): value is AgentProvider {
+  return typeof value === "string" && Object.hasOwn(models.providers, value);
+}
+
+export function agentIdeNames(): string[] {
+  return Object.entries(models.hosts).map(([host, target]) =>
+    "ide" in target ? target.ide : host
+  );
+}
+
+export function resolveAgentHost(ide: string): AgentHost {
+  const host = Object.entries(models.hosts).find(
+    ([name, target]) => name === ide || ("ide" in target && target.ide === ide)
+  )?.[0];
+  if (!isAgentHost(host)) throw new Error(`IDE "${ide}" is not supported.`);
+  return host;
+}
+
+/** Native fields for an explicitly selected host and provider. */
 export function agentModelOptions(
-  host: ModelHost,
-  frontmatter: Record<string, unknown>,
-  plugin?: string,
-  fileName?: string,
-  mode: "flat" | "marketplace" = "flat",
-  configuration: typeof models = models
+  host: AgentHost,
+  provider: AgentProvider
 ): Record<string, unknown> {
-  const target = configuration.tools[host];
-  const native: Record<string, unknown> = {};
-  if (frontmatter.model !== undefined) native.model = frontmatter.model;
-  if ("effortField" in target && frontmatter[target.effortField] !== undefined)
-    native[target.effortField] = frontmatter[target.effortField];
-  if (frontmatter.model !== undefined) return native;
-  const role = fileName?.split("/").at(-1)?.replace(/\.md$/, "") ?? frontmatter.name;
-  if (
-    plugin !== configuration.plugin ||
-    typeof role !== "string" ||
-    !configuration.roles.includes(role)
-  )
-    return native;
-  if (mode === "marketplace" && "marketplace" in target && !target.marketplace) return native;
-  const provider = Object.entries(configuration.providers).find(
-    ([name]) => name === target.provider
-  )?.[1];
-  if (provider === undefined) throw new Error(`Unknown agent model provider: ${target.provider}`);
-  const nativeModel =
-    "nativeModels" in provider
-      ? (Object.entries(provider.nativeModels).find(([tool]) => tool === host)?.[1] ??
-        provider.model)
-      : provider.model;
-  const model = `${"providerPrefix" in target && target.providerPrefix ? `${target.provider}/` : ""}${nativeModel}`;
-  if ("effortField" in target) {
-    native.model = model;
-    native[target.effortField] ??= provider.effort;
-  } else {
-    native.model = `${model}${target.effortPrefix}${provider.effort}${target.effortSuffix}`;
+  const target = models.hosts[host];
+  if (!target.providers.includes(provider)) {
+    throw new Error(`Provider "${provider}" is not supported by "${host}".`);
   }
-  return native;
+  const source = models.providers[provider];
+  const nativeModel =
+    "nativeModels" in source
+      ? (Object.entries(source.nativeModels).find(([name]) => name === host)?.[1] ?? source.model)
+      : source.model;
+  const model = `${"providerPrefix" in target && target.providerPrefix ? `${provider}/` : ""}${nativeModel}`;
+  return "effortField" in target
+    ? { model, [target.effortField]: source.effort }
+    : { model: `${model}${target.effortPrefix}${source.effort}${target.effortSuffix}` };
 }
diff --git a/cli/src/contexts/tools/domain/marketplace-catalog.ts b/cli/src/contexts/tools/domain/marketplace-catalog.ts
index 9e06378f5..40afff08f 100644
--- a/cli/src/contexts/tools/domain/marketplace-catalog.ts
+++ b/cli/src/contexts/tools/domain/marketplace-catalog.ts
@@ -25,17 +25,12 @@ type SrcEntry =
 
 /** Marketplace-mode agent transform shared by claude and copilot: the frontmatter is kept
  * untouched and only relative links are rewritten to the flattened output path. */
-export function transformClaudeAgent(
-  content: string,
-  _plugin: string,
-  outName: string,
-  modelOptions?: (fm: Record<string, unknown>) => Record<string, unknown>
-): string {
+export function transformClaudeAgent(content: string, _plugin: string, outName: string): string {
   const { frontmatter, body } = parseFrontmatter(content);
   const rewrittenBody = rewriteRelativeLinks(body, {
     currentFilePluginRelative: `agents/${outName}`,
   });
-  return serializeFrontmatter({ ...frontmatter, ...modelOptions?.(frontmatter) }, rewrittenBody);
+  return serializeFrontmatter(frontmatter, rewrittenBody);
 }
 
 export interface SynthesizeClaudeStyleManifestOpts {
diff --git a/cli/src/contexts/tools/domain/profiles/claude/build.ts b/cli/src/contexts/tools/domain/profiles/claude/build.ts
index 060026c48..145dd8758 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/build.ts
@@ -13,7 +13,6 @@ import {
 } from "../../../../../kernel/materialization/flat-paths.js";
 import { rewriteRelativeLinks } from "../../../../../kernel/materialization/relative-link-rewrite.js";
 import type { ToolBuildContract } from "../../build-contract.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { mergeClaudeSettingsHooks } from "../../formats/flat-hooks-merge.js";
 import { CLAUDE_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { mergeVscodeMcp } from "../../formats/vscode-mcp-merge.js";
@@ -53,10 +52,7 @@ export function buildClaudeContract(): ToolBuildContract {
         supported: true,
         source: { kind: "filteredTree", srcDir: "agents", inputExt: ".md" },
         path: (_p, rel) => rel,
-        transform: (content, plugin, outName) =>
-          transformClaudeAgent(content, plugin, outName, (fm) =>
-            agentModelOptions("claude", fm, plugin, outName, "marketplace")
-          ),
+        transform: transformClaudeAgent,
       },
       mcp: {
         supported: true,
@@ -115,7 +111,6 @@ function transformClaudeFlatAgent(content: string, plugin: string, outName: stri
   return serializeFrontmatter(
     {
       ...frontmatter,
-      ...agentModelOptions("claude", frontmatter, plugin, outName),
       name: prefixedName,
     },
     rewrittenBody
diff --git a/cli/src/contexts/tools/domain/profiles/claude/profile.ts b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
index c2223278d..4c78b8c10 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
@@ -15,7 +15,6 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { convertCommandFrontmatter, stripToolSuffix } from "../../formats/command.js";
 import { CLAUDE_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { claudeStyleMarketplaceKey } from "../../marketplace-entry.js";
@@ -49,7 +48,7 @@ export const claude: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
-        modelOptions: (fm, plugin, file) => agentModelOptions("claude", fm, plugin, file),
+        effortField: "effort",
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts b/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
index 6beee08c0..119afd9b6 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
@@ -1,5 +1,4 @@
 import { parseFrontmatter } from "../../../../../kernel/markdown.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { stringifyToml } from "./toml.js";
 
 /**
@@ -19,11 +18,7 @@ export function codexAgentMarkdownToToml(
 ): string {
   const { frontmatter, body } = parseFrontmatter(content);
   const name = resolveName(frontmatter, pluginName, fileBaseName, prefixName);
-  const obj = buildTomlObject(
-    name,
-    { ...frontmatter, ...agentModelOptions("codex", frontmatter, pluginName, fileBaseName) },
-    body
-  );
+  const obj = buildTomlObject(name, frontmatter, body);
   return stringifyToml(obj);
 }
 
diff --git a/cli/src/contexts/tools/domain/profiles/codex/profile.ts b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
index 0396af7ac..a2b30db93 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
@@ -17,7 +17,6 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import {
   buildAiddCommandFilePath,
   convertCommandFrontmatter,
@@ -143,7 +142,7 @@ export const codex: AiTool<
       directory: DIRECTORY,
       toolSuffix: TOOL_SUFFIX,
       format: "toml",
-      modelOptions: (fm, plugin, file) => agentModelOptions("codex", fm, plugin, file),
+      effortField: "model_reasoning_effort",
     }),
     skills: new SkillsCapability({
       prefix: "aidd-",
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/build.ts b/cli/src/contexts/tools/domain/profiles/copilot/build.ts
index 0cf41aae8..06f918172 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/build.ts
@@ -14,7 +14,6 @@ import {
 import { rewriteRelativeLinks } from "../../../../../kernel/materialization/relative-link-rewrite.js";
 import type { ToolBuildContract } from "../../build-contract.js";
 import { stripAgentFrontmatter } from "../../formats/agent-frontmatter-strip.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { flattenCopilotHooksShape } from "../../formats/flat-hooks-merge.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { mergeVscodeMcp } from "../../formats/vscode-mcp-merge.js";
@@ -69,10 +68,7 @@ export function buildCopilotMarketplaceContract(): ToolBuildContract {
         supported: true,
         source: { kind: "filteredTree", srcDir: "agents", inputExt: ".md" },
         path: (_p, rel) => rel,
-        transform: (content, plugin, outName) =>
-          transformClaudeAgent(content, plugin, outName, (fm) =>
-            agentModelOptions("copilot", fm, plugin, outName, "marketplace")
-          ),
+        transform: transformClaudeAgent,
       },
       mcp: {
         supported: true,
@@ -142,7 +138,6 @@ function transformCopilotFlatAgent(content: string, plugin: string, outName: str
   return serializeFrontmatter(
     {
       ...stripped,
-      ...agentModelOptions("copilot", frontmatter, plugin, outName),
       name: prefixedName,
     },
     rewrittenBody
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
index 4e0c9a633..1138f72ea 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
@@ -19,7 +19,6 @@ import type {
   HasSettings,
   HasSkills,
 } from "../../contracts.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { convertCommandFrontmatter } from "../../formats/command.js";
 import { PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { claudeStyleMarketplaceKey } from "../../marketplace-entry.js";
@@ -225,8 +224,8 @@ export const copilot: AiTool<
       directory: DIRECTORY,
       toolSuffix: EXT_AGENT,
       format: "markdown",
+      effortField: "reasoningEffort",
       userFileExt: EXT_AGENT,
-      modelOptions: (fm, plugin, file) => agentModelOptions("copilot", fm, plugin, file),
       buildInstallPath: (fileName) => agentsHandler.buildFilePath(fileName),
       convertFrontmatter: (fm, fileName) => agentsHandler.convertFrontmatter(fm, fileName),
     }),
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/build.ts b/cli/src/contexts/tools/domain/profiles/cursor/build.ts
index 17ea5ed79..286828678 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/build.ts
@@ -14,7 +14,6 @@ import {
 import { rewriteRelativeLinks } from "../../../../../kernel/materialization/relative-link-rewrite.js";
 import type { ToolBuildContract } from "../../build-contract.js";
 import { stripCursorAgentFrontmatter } from "../../formats/agent-frontmatter-strip.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { mergeCursorFlatHooks } from "../../formats/flat-hooks-merge.js";
 import { CURSOR_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { mergeVscodeMcp } from "../../formats/vscode-mcp-merge.js";
@@ -122,7 +121,6 @@ function transformCursorFlatAgent(content: string, plugin: string, outName: stri
   return serializeFrontmatter(
     {
       ...stripped,
-      ...agentModelOptions("cursor", frontmatter, plugin, outName),
       name: prefixedName,
     },
     rewrittenBody
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
index d2d6d3e05..c7556a36d 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
@@ -15,7 +15,6 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import {
   buildAiddCommandFilePath,
   convertCommandFrontmatter,
@@ -53,8 +52,6 @@ export const cursor: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
-        modelOptions: (fm, plugin, file) =>
-          agentModelOptions("cursor", fm, plugin, file, "marketplace"),
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/opencode/build.ts b/cli/src/contexts/tools/domain/profiles/opencode/build.ts
index eb388261b..a29a80cc4 100644
--- a/cli/src/contexts/tools/domain/profiles/opencode/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/opencode/build.ts
@@ -16,7 +16,6 @@ import { rewriteRelativeLinks } from "../../../../../kernel/materialization/rela
 import type { FileReader } from "../../../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../../../kernel/ports/file-writer.js";
 import type { ArtifactContract, ToolBuildContract } from "../../build-contract.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import { buildOpencodeFlatConfig } from "../../formats/opencode-mcp-merge.js";
 import { generateOpencodeHooksBridge } from "./opencode-hooks-bridge.js";
 import {
@@ -138,7 +137,6 @@ function transformOpencodeFlatAgent(content: string, plugin: string, outName: st
   return serializeFrontmatter(
     {
       ...frontmatter,
-      ...agentModelOptions("opencode", frontmatter, plugin, outName),
       name: prefixedName,
       mode: "subagent",
     },
diff --git a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
index 9e266863d..a44e83716 100644
--- a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
@@ -16,7 +16,6 @@ import type {
   HasRules,
   HasSkills,
 } from "../../contracts.js";
-import { agentModelOptions } from "../../formats/agent-models.js";
 import {
   buildAiddCommandFilePath,
   convertCommandFrontmatterNoHint,
@@ -59,7 +58,6 @@ export const opencode: AiTool<
       directory: DIRECTORY,
       toolSuffix: TOOL_SUFFIX,
       format: "markdown",
-      modelOptions: (fm, plugin, file) => agentModelOptions("opencode", fm, plugin, file),
       convertFrontmatter: (fm) => ({ description: fm.description, mode: "subagent" }),
     }),
     skills: new SkillsCapability({
diff --git a/cli/src/contexts/translate/domain/content-translator.ts b/cli/src/contexts/translate/domain/content-translator.ts
index a2665895b..bc8525d4c 100644
--- a/cli/src/contexts/translate/domain/content-translator.ts
+++ b/cli/src/contexts/translate/domain/content-translator.ts
@@ -40,11 +40,7 @@ interface TranslatedFile {
 
 interface MarkdownCap {
   buildInstallPath: (fileName: string) => string | null;
-  convertFrontmatter: (
-    fm: Record<string, unknown>,
-    fileName: string,
-    plugin?: string
-  ) => Record<string, unknown>;
+  convertFrontmatter: (fm: Record<string, unknown>, fileName: string) => Record<string, unknown>;
   serialize: (fm: Record<string, unknown>, body: string) => string;
 }
 
@@ -141,7 +137,7 @@ export class PluginContentTranslator {
     const result: InstallationFile[] = [];
     const componentPaths = new Map<string, string>();
     for (const file of dist.files) {
-      const translated = this.translateFile(file, tool, dist.manifest.name);
+      const translated = this.translateFile(file, tool);
       if (translated === null) continue;
       const hooked = this.maybeConvertHooks(file.relativePath, translated.content, tool);
       // Prose is rewritten, an artefact is carried byte for byte: a tool's own rewrite leaving
@@ -206,8 +202,7 @@ export class PluginContentTranslator {
 
   private translateFile(
     file: PluginComponentFile,
-    tool: AiTool<HasPlugins>,
-    plugin: string
+    tool: AiTool<HasPlugins>
   ): TranslatedFile | null {
     if (PLUGIN_MANIFEST_PATHS.includes(file.relativePath)) return null;
     const cap = tool.capabilities.plugins;
@@ -229,20 +224,19 @@ export class PluginContentTranslator {
         verbatim: true,
       };
     }
-    return this.translateComponent(file, tool, plugin);
+    return this.translateComponent(file, tool);
   }
 
   private translateComponent(
     file: PluginComponentFile,
-    tool: AiTool<HasPlugins>,
-    plugin: string
+    tool: AiTool<HasPlugins>
   ): TranslatedFile | null {
     const top = file.relativePath.split("/")[0];
     if (top === "commands" && hasCommands(tool)) {
       return translateMarkdown(file, "commands/", tool.directory, tool.capabilities.commands);
     }
     if (top === "agents" && hasAgents(tool)) {
-      return translateMarkdown(file, "agents/", tool.directory, tool.capabilities.agents, plugin);
+      return translateMarkdown(file, "agents/", tool.directory, tool.capabilities.agents);
     }
     if (top === "rules" && hasRules(tool)) {
       return translateMarkdown(file, "rules/", tool.directory, tool.capabilities.rules);
@@ -355,11 +349,7 @@ export class PluginContentTranslator {
     // Same rule as the native path: prose is rewritten, an artefact is carried. Rewriting every
     // flat file left a script intact only where a tool's own rewrite happened to spare it.
     const content = isProse(file.relativePath) ? tool.rewriteContent(file.content) : file.content;
-    if (
-      section === "agents" &&
-      hasAgents(tool) &&
-      tool.capabilities.agents.params.modelOptions !== undefined
-    ) {
+    if (section === "agents" && hasAgents(tool)) {
       const artifact = tool.buildContracts?.flat?.().artifacts.agents;
       if (artifact?.supported) {
         return this.makeFile(
@@ -461,15 +451,14 @@ function translateMarkdown(
   file: PluginComponentFile,
   sectionDir: string,
   toolDirectory: string,
-  cap: MarkdownCap,
-  plugin?: string
+  cap: MarkdownCap
 ): TranslatedFile | null {
   const fileName = file.relativePath.slice(sectionDir.length);
   const fullPath = cap.buildInstallPath(fileName);
   if (fullPath === null) return null;
   const relativePath = toPluginRelativePath(fullPath, toolDirectory);
   const { frontmatter, body } = parseFrontmatter(file.content);
-  const newFm = cap.convertFrontmatter(frontmatter, fileName, plugin);
+  const newFm = cap.convertFrontmatter(frontmatter, fileName);
   const content = cap.serialize(newFm, body);
   return { relativePath, content };
 }
diff --git a/cli/src/presentation/commands/agents.ts b/cli/src/presentation/commands/agents.ts
new file mode 100644
index 000000000..29d20f64a
--- /dev/null
+++ b/cli/src/presentation/commands/agents.ts
@@ -0,0 +1,52 @@
+import type { Command } from "commander";
+import {
+  agentIdeNames,
+  isAgentProvider,
+  resolveAgentHost,
+} from "../../contexts/tools/domain/formats/agent-models.js";
+import { createDeps } from "../../runtime/wiring/framework.js";
+import { ErrorHandler } from "../error-handler.js";
+import { parseGlobalOptions } from "./global-options.js";
+
+export function registerAgentsCommand(program: Command): void {
+  const agents = program
+    .command("agents")
+    .description("Opt in to native specialist agents for this project");
+  agents
+    .command("install")
+    .description("Install agents with the selected provider's model and effort")
+    .requiredOption("--provider <provider>", "openai or anthropic")
+    .requiredOption("--ide <ide>", agentIdeNames().join(", "))
+    .action(async (options: { provider: string; ide: string }) => {
+      const { projectRoot, verbose, output } = parseGlobalOptions(program);
+      try {
+        const host = resolveAgentHost(options.ide);
+        if (!isAgentProvider(options.provider))
+          throw new Error(`Unsupported agent provider: ${options.provider}`);
+        const deps = await createDeps(projectRoot, { verbose }, output);
+        const count = await deps.manageAgentsUseCase.install({
+          projectRoot,
+          host,
+          provider: options.provider,
+        });
+        output.success(`${count} agent files installed for ${options.ide}.`);
+      } catch (error) {
+        new ErrorHandler(output).handle(error);
+      }
+    });
+  agents
+    .command("remove")
+    .description("Remove unmodified AIDD agents from this project")
+    .requiredOption("--ide <ide>", agentIdeNames().join(", "))
+    .action(async (options: { ide: string }) => {
+      const { projectRoot, verbose, output } = parseGlobalOptions(program);
+      try {
+        const host = resolveAgentHost(options.ide);
+        const deps = await createDeps(projectRoot, { verbose }, output);
+        const count = await deps.manageAgentsUseCase.remove({ projectRoot, host });
+        output.success(`${count} agent files removed for ${options.ide}.`);
+      } catch (error) {
+        new ErrorHandler(output).handle(error);
+      }
+    });
+}
diff --git a/cli/src/runtime/assets/agent-sources.ts b/cli/src/runtime/assets/agent-sources.ts
new file mode 100644
index 000000000..2dacbd0b6
--- /dev/null
+++ b/cli/src/runtime/assets/agent-sources.ts
@@ -0,0 +1,11 @@
+import executor from "../../../assets/agents/executor.md";
+import explorer from "../../../assets/agents/explorer.md";
+import reviewer from "../../../assets/agents/reviewer.md";
+import validator from "../../../assets/agents/validator.md";
+
+export const AGENT_SOURCES: Readonly<Record<string, string>> = {
+  "aidd-dev-explorer": explorer,
+  "aidd-dev-executor": executor,
+  "aidd-dev-validator": validator,
+  "aidd-dev-reviewer": reviewer,
+};
diff --git a/cli/src/runtime/wiring/framework.ts b/cli/src/runtime/wiring/framework.ts
index 59ce0367e..eeb61461c 100644
--- a/cli/src/runtime/wiring/framework.ts
+++ b/cli/src/runtime/wiring/framework.ts
@@ -10,6 +10,7 @@ import { MarketplaceAddUseCase } from "../../contexts/distribution/application/m
 import type { MarketplaceListUseCase } from "../../contexts/distribution/application/marketplace-list-use-case.js";
 import type { MarketplaceRefreshUseCase } from "../../contexts/distribution/application/marketplace-refresh-use-case.js";
 import type { MarketplaceRegisterFrameworkUseCase } from "../../contexts/distribution/application/marketplace-register-framework-use-case.js";
+import { ManageAgentsUseCase } from "../../contexts/framework/application/agents/manage-agents-use-case.js";
 import { CleanUserScopeUseCase } from "../../contexts/framework/application/clean/clean-user-scope-use-case.js";
 import { CleanUseCase } from "../../contexts/framework/application/clean-use-case.js";
 import { DoctorLayoutUseCase } from "../../contexts/framework/application/doctor/doctor-layout-use-case.js";
@@ -68,6 +69,7 @@ import { UninstallUseCase } from "../../contexts/framework/application/uninstall
 import type { Environment } from "../../contexts/framework/domain/ports/environment.js";
 import type { ManifestRepository } from "../../contexts/framework/domain/ports/manifest-repository.js";
 import type { UserSourceReferences } from "../../contexts/framework/domain/ports/user-source-references.js";
+import { AgentInstallationStoreAdapter } from "../../contexts/framework/infrastructure/agent-installation-store-adapter.js";
 import { EnvironmentAdapter } from "../../contexts/framework/infrastructure/environment-adapter.js";
 import { ManifestRepositoryAdapter } from "../../contexts/framework/infrastructure/manifest-repository-adapter.js";
 import { PluginDistributionReaderAdapter } from "../../contexts/framework/infrastructure/plugin-distribution-reader-adapter.js";
@@ -95,6 +97,7 @@ import { PluginPickUseCase } from "../../presentation/prompts/plugin-pick-use-ca
 import { SetupPluginsPromptUseCase } from "../../presentation/prompts/setup-plugins-prompt-use-case.js";
 import { SetupToolsPromptUseCase } from "../../presentation/prompts/setup-tools-prompt-use-case.js";
 import { SyncConflictResolverUseCase } from "../../presentation/prompts/sync-conflict-resolver-use-case.js";
+import { AGENT_SOURCES } from "../assets/agent-sources.js";
 import { BundledAssetProviderAdapter } from "../assets/asset-loader.js";
 import { AuthProviderAdapter } from "../auth/auth-provider-adapter.js";
 import { AuthReaderAdapter } from "../auth/auth-reader-adapter.js";
@@ -126,6 +129,7 @@ interface GlobalOptions {
 }
 
 interface Deps {
+  manageAgentsUseCase: ManageAgentsUseCase;
   fs: FileReader & FileWriter & FileMerger;
   manifestRepo: ManifestRepository;
   /** `--scope user`'s own manifest repository: `userConfigDir()/manifest.json`, never nested
@@ -210,6 +214,12 @@ export async function createDeps(
   const hasher = new HasherAdapter();
   const logger = output ?? new CLIOutput(options.verbose);
   const fs = new FileAdapter(hasher, logger);
+  const manageAgentsUseCase = new ManageAgentsUseCase(
+    fs,
+    new AgentInstallationStoreAdapter(fs),
+    hasher,
+    AGENT_SOURCES
+  );
   const pluginDistributionReader = new PluginDistributionReaderAdapter(fs);
   const manifestRepo = new ManifestRepositoryAdapter(projectRoot);
   const userManifestRepo = new UserManifestRepositoryAdapter(userConfigDir, atomicWriteFile);
@@ -569,7 +579,8 @@ export async function createDeps(
     userSourceReferences,
     hostPluginRegistries,
     userManifestRepo,
-    nativeSources
+    nativeSources,
+    manageAgentsUseCase
   );
   const cleanUserScopeUseCase = new CleanUserScopeUseCase(
     fs,
@@ -589,6 +600,7 @@ export async function createDeps(
   const listInstalledRulesUseCase = new ListInstalledRulesUseCase(fs);
   const checkUpdateUseCase = new CheckUpdateUseCase(cliUpdater, currentVersionProvider, logger, fs);
   const deps: Deps = {
+    manageAgentsUseCase,
     validateRecipesUseCase: new ValidateRecipesUseCase(new RecipeFilesAdapter()),
     fs,
     manifestRepo,
diff --git a/cli/tests/architecture/context-boundary.arch.test.ts b/cli/tests/architecture/context-boundary.arch.test.ts
index a2c3d30ab..930521f7e 100644
--- a/cli/tests/architecture/context-boundary.arch.test.ts
+++ b/cli/tests/architecture/context-boundary.arch.test.ts
@@ -11,6 +11,8 @@ const PUBLIC_MODULES: Readonly<Record<string, readonly string[]>> = {
   tools: [
     // the tool contract and lookup surface
     "src/contexts/tools/domain/contracts.ts",
+    "src/contexts/tools/domain/capabilities/agents-capability.ts",
+    "src/contexts/tools/domain/formats/agent-models.ts",
     "src/contexts/tools/domain/registry.ts",
     "src/contexts/tools/domain/build-contract.ts",
     // co-owned configuration (settings.json, .mcp.json et al.)
@@ -82,6 +84,7 @@ const PUBLIC_MODULES: Readonly<Record<string, readonly string[]>> = {
   // The largest context: while it had no entry the mechanism below skipped every framework
   // file, so its interior was reached unchecked. Measured, composition root excluded.
   framework: [
+    "src/contexts/framework/application/agents/manage-agents-use-case.ts",
     "src/contexts/framework/domain/recipes/recipe-validation.ts",
     // the rule inventory `framework rules` prints, one row per installed rule
     "src/contexts/framework/domain/installed-rule.ts",
@@ -195,7 +198,6 @@ function reachesIntoInterior(
  * itself, and they resolve together when `install/` moves into `contexts/tools/application/`.
  */
 const BASELINE = [
-  "src/contexts/framework/application/install/content/install-agents-use-case.ts -> src/contexts/tools/domain/capabilities/agents-capability.ts",
   "src/contexts/framework/application/install/content/install-commands-use-case.ts -> src/contexts/tools/domain/capabilities/commands-capability.ts",
   "src/contexts/framework/application/install/content/install-content-section-use-case.ts -> src/contexts/tools/domain/formats/command.ts",
   "src/contexts/framework/application/install/content/install-rules-use-case.ts -> src/contexts/tools/domain/capabilities/rules-capability.ts",
diff --git a/cli/tests/architecture/folder-size.arch.test.ts b/cli/tests/architecture/folder-size.arch.test.ts
index 4600362bd..a65fcc6bf 100644
--- a/cli/tests/architecture/folder-size.arch.test.ts
+++ b/cli/tests/architecture/folder-size.arch.test.ts
@@ -13,10 +13,9 @@ const MAX_FILES_PER_FOLDER = 10;
  * files are shuffled. The test asserts the count, so a reason nobody measured fails here.
  */
 const BASELINE: readonly { readonly path: string; readonly count: number }[] = [
-  // Eleven files carry the command surface, plus three helpers no other folder imports. That
-  // is the flattest mapping from the CLI's surface to its source; moving the helpers out
-  // would leave eleven, still over the limit and clearer about nothing.
-  { path: "src/presentation/commands", count: 15 },
+  // Command groups, including opt-in agents, and their command-only helpers.
+  // Keeping each group at its CLI entry point avoids combining unrelated command surfaces.
+  { path: "src/presentation/commands", count: 16 },
   // One display module per command, mirroring `presentation/commands/`: that mirror is what
   // lets a command's rendering be asserted without running the binary. Fewer files would mean
   // one module rendering several commands, which is what put the printing in the actions.
diff --git a/cli/tests/architecture/orchestrator-deps.arch.test.ts b/cli/tests/architecture/orchestrator-deps.arch.test.ts
index ae467fc4c..d4b137098 100644
--- a/cli/tests/architecture/orchestrator-deps.arch.test.ts
+++ b/cli/tests/architecture/orchestrator-deps.arch.test.ts
@@ -29,7 +29,8 @@ const BASELINE: readonly { readonly path: string; readonly injected: number }[]
   { path: "src/contexts/framework/application/restore/restore-use-case.ts", injected: 12 },
   // Host plugin registries prove ref scope/enablement; the added native source reader independently
   // proves the current catalogue before these flows mutate it. Neither witness replaces the other.
-  { path: "src/contexts/framework/application/clean-use-case.ts", injected: 13 },
+  // Independent opt-in agents have their own ownership record and participate in full cleanup.
+  { path: "src/contexts/framework/application/clean-use-case.ts", injected: 14 },
   {
     path: "src/contexts/framework/application/flows/marketplace-sync-settings-use-case.ts",
     injected: 15,
diff --git a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
new file mode 100644
index 000000000..8781b5785
--- /dev/null
+++ b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
@@ -0,0 +1,124 @@
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ManageAgentsUseCase } from "../../../../../src/contexts/framework/application/agents/manage-agents-use-case.js";
+import { AgentInstallationStoreAdapter } from "../../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
+import "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+import { FileAdapter } from "../../../../../src/runtime/filesystem/file-adapter.js";
+import { HasherAdapter } from "../../../../../src/runtime/filesystem/hasher-adapter.js";
+
+const sources = {
+  "aidd-dev-explorer": "---\nname: explorer\ndescription: Explore\n---\nFind relevant source.",
+  "aidd-dev-reviewer": "---\nname: reviewer\ndescription: Review\n---\nReview quality.",
+};
+
+describe("ManageAgentsUseCase", () => {
+  let root: string;
+  let manager: ManageAgentsUseCase;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "aidd-agents-"));
+    const hasher = new HasherAdapter();
+    const fs = new FileAdapter(hasher);
+    manager = new ManageAgentsUseCase(fs, new AgentInstallationStoreAdapter(fs), hasher, sources);
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("installs namespaced native Codex agents and records ownership", async () => {
+    expect(await manager.install({ projectRoot: root, host: "codex", provider: "openai" })).toBe(2);
+    const content = await readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "utf8");
+    expect(content).toContain('model = "gpt-6-luna"');
+    expect(content).toContain('model_reasoning_effort = "medium"');
+    expect(content).toContain('name = "aidd-dev-explorer"');
+    expect(
+      JSON.parse(await readFile(join(root, ".aidd/agents.json"), "utf8")).codex
+    ).toHaveProperty("aidd-dev-explorer");
+    expect(await manager.install({ projectRoot: root, host: "codex", provider: "openai" })).toBe(0);
+  });
+
+  it("changes provider only for unmodified owned files", async () => {
+    await manager.install({ projectRoot: root, host: "opencode", provider: "openai" });
+    expect(
+      await manager.install({ projectRoot: root, host: "opencode", provider: "anthropic" })
+    ).toBe(2);
+    expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
+      "anthropic/claude-haiku-5-5#medium"
+    );
+    await writeFile(join(root, ".opencode/agents/aidd-dev-reviewer.md"), "personal edit");
+    await expect(
+      manager.install({ projectRoot: root, host: "opencode", provider: "openai" })
+    ).rejects.toThrow("modified");
+    expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
+      "anthropic/claude-haiku-5-5#medium"
+    );
+  });
+
+  it("preflights every destination before writing and preserves personal files", async () => {
+    await mkdir(join(root, ".codex/agents"), { recursive: true });
+    await writeFile(join(root, ".codex/agents/aidd-dev-reviewer.toml"), "personal");
+    await expect(
+      manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+    ).rejects.toThrow("not owned");
+    await expect(
+      readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"))
+    ).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it("removes owned agents, tolerates missing files, and keeps personal agents", async () => {
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    await rm(join(root, ".codex/agents/aidd-dev-reviewer.toml"));
+    await writeFile(join(root, ".codex/agents/personal.toml"), "personal");
+    expect(await manager.remove({ projectRoot: root, host: "codex" })).toBe(1);
+    expect(await readFile(join(root, ".codex/agents/personal.toml"), "utf8")).toBe("personal");
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+    expect(await manager.remove({ projectRoot: root, host: "codex" })).toBe(0);
+  });
+
+  it("refuses edited owned files before removing any agent", async () => {
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    await writeFile(join(root, ".codex/agents/aidd-dev-reviewer.toml"), "edited");
+    await expect(manager.remove({ projectRoot: root, host: "codex" })).rejects.toThrow("modified");
+    expect(await readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "utf8")).toContain(
+      "Explore"
+    );
+  });
+
+  it("rejects ledger entries outside the bundled agent names", async () => {
+    await mkdir(join(root, ".aidd"));
+    await writeFile(
+      join(root, ".aidd/agents.json"),
+      JSON.stringify({ codex: { "../../personal": "a".repeat(32) } })
+    );
+    await expect(manager.remove({ projectRoot: root, host: "codex" })).rejects.toThrow(
+      "Unknown managed agent"
+    );
+  });
+
+  it.skipIf(process.platform === "win32")(
+    "refuses agent and ledger directories pointing outside the project",
+    async () => {
+      const outside = await mkdtemp(join(tmpdir(), "aidd-agents-outside-"));
+      try {
+        await symlink(outside, join(root, ".codex"));
+        await expect(
+          manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+        ).rejects.toThrow("outside project");
+        await rm(join(root, ".codex"));
+        await symlink(outside, join(root, ".aidd"));
+        await expect(
+          manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+        ).rejects.toThrow("outside project");
+      } finally {
+        await rm(outside, { recursive: true, force: true });
+      }
+    }
+  );
+});
diff --git a/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts b/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
new file mode 100644
index 000000000..fc23e9c18
--- /dev/null
+++ b/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
@@ -0,0 +1,128 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ManageAgentsUseCase } from "../../../../../src/contexts/framework/application/agents/manage-agents-use-case.js";
+import { CleanUseCase } from "../../../../../src/contexts/framework/application/clean-use-case.js";
+import { GitignoreUseCase } from "../../../../../src/contexts/framework/application/gitignore-use-case.js";
+import { Manifest } from "../../../../../src/contexts/framework/domain/manifest.js";
+import { AgentInstallationStoreAdapter } from "../../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
+import "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+import { InstallationFile } from "../../../../../src/kernel/file.js";
+import { FileAdapter } from "../../../../../src/runtime/filesystem/file-adapter.js";
+import { HasherAdapter } from "../../../../../src/runtime/filesystem/hasher-adapter.js";
+import { CapturingLogger } from "../../../../helpers/ports/capturing-logger.js";
+import { InMemoryManifestRepository } from "../../../../helpers/ports/in-memory-manifest-repository.js";
+
+describe("clean includes opt-in agents", () => {
+  let root: string;
+  let manager: ManageAgentsUseCase;
+  let fs: FileAdapter;
+  let hasher: HasherAdapter;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "aidd-clean-agents-"));
+    hasher = new HasherAdapter();
+    fs = new FileAdapter(hasher);
+    manager = new ManageAgentsUseCase(fs, new AgentInstallationStoreAdapter(fs), hasher, {
+      "aidd-dev-explorer": "---\nname: explorer\ndescription: Explore\n---\nExplore source.",
+    });
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  function clean(manifest: Manifest | null = null): CleanUseCase {
+    return new CleanUseCase(
+      fs,
+      new InMemoryManifestRepository(manifest, root),
+      new CapturingLogger(),
+      new GitignoreUseCase(fs),
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      manager
+    );
+  }
+
+  it("previews and removes agents in a project without a framework manifest", async () => {
+    const useCase = clean();
+    const preview = await useCase.execute({ projectRoot: root, force: false });
+    expect(preview.dryRun).toBe(true);
+    expect(preview.preview.tools).toEqual([{ toolId: "codex", fileCount: 1 }]);
+    expect(await readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "utf8")).toContain(
+      "Explore"
+    );
+    expect((await useCase.execute({ projectRoot: root, force: true })).fileCount).toBe(1);
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it("keeps personal configuration beside the agent ledger", async () => {
+    await writeFile(join(root, ".aidd/config.json"), "{}");
+    await clean().execute({ projectRoot: root, force: true });
+    expect(await readFile(join(root, ".aidd/config.json"), "utf8")).toBe("{}");
+  });
+
+  it("keeps personal directory links beside the agent ledger", async () => {
+    const personal = join(root, "personal");
+    await mkdir(personal);
+    await writeFile(join(personal, "note.txt"), "personal");
+    const link = join(root, ".aidd", "personal-link");
+    await symlink(personal, link, "junction");
+    await clean().execute({ projectRoot: root, force: true });
+    expect((await lstat(link)).isSymbolicLink()).toBe(true);
+    expect(await readFile(join(link, "note.txt"), "utf8")).toBe("personal");
+  });
+
+  it("counts agents once alongside framework files and other opted-in hosts", async () => {
+    const manifest = Manifest.create();
+    manifest.addTool("codex", "1.0.0", [
+      new InstallationFile({
+        relativePath: ".codex/rule.md",
+        content: "rule",
+        hash: hasher.hash("rule"),
+      }),
+    ]);
+    await fs.writeFile(join(root, ".codex/rule.md"), "rule");
+    await manager.install({ projectRoot: root, host: "opencode", provider: "openai" });
+    const useCase = clean(manifest);
+    const preview = await useCase.execute({ projectRoot: root, force: false });
+    expect(preview.preview.tools).toEqual([
+      { toolId: "codex", fileCount: 2 },
+      { toolId: "opencode", fileCount: 1 },
+    ]);
+    expect(preview.preview.totalFileCount).toBe(3);
+    expect((await useCase.execute({ projectRoot: root, force: true })).fileCount).toBe(3);
+    await expect(readFile(join(root, ".codex/rule.md"))).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it("rejects modified agents before deleting framework files", async () => {
+    const manifest = Manifest.create();
+    manifest.addTool("codex", "1.0.0", [
+      new InstallationFile({
+        relativePath: ".codex/rule.md",
+        content: "rule",
+        hash: hasher.hash("rule"),
+      }),
+    ]);
+    await fs.writeFile(join(root, ".codex/rule.md"), "rule");
+    await writeFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "edited");
+    await expect(clean(manifest).execute({ projectRoot: root, force: true })).rejects.toThrow(
+      "modified"
+    );
+    expect(await readFile(join(root, ".codex/rule.md"), "utf8")).toBe("rule");
+    expect(await readFile(join(root, ".aidd/agents.json"), "utf8")).toContain("codex");
+  });
+});
diff --git a/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts b/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
new file mode 100644
index 000000000..fd1b9d353
--- /dev/null
+++ b/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
@@ -0,0 +1,50 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { AgentInstallationStoreAdapter } from "../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
+import { FileHash } from "../../../../src/kernel/file.js";
+import { FileAdapter } from "../../../../src/runtime/filesystem/file-adapter.js";
+import { HasherAdapter } from "../../../../src/runtime/filesystem/hasher-adapter.js";
+
+describe("AgentInstallationStoreAdapter", () => {
+  let root: string;
+  let store: AgentInstallationStoreAdapter;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "aidd-agent-store-"));
+    store = new AgentInstallationStoreAdapter(new FileAdapter(new HasherAdapter()));
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("round trips typed hashes for several hosts and removes an empty ledger", async () => {
+    expect(await store.load(root)).toEqual({});
+    const expected = {
+      codex: { "aidd-dev-explorer": new FileHash("a".repeat(32)) },
+      opencode: { "aidd-dev-reviewer": new FileHash("b".repeat(32)) },
+    };
+    await store.save(root, expected);
+    expect(await store.load(root)).toEqual(expected);
+    await store.save(root, {});
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it.each([
+    "null",
+    "[]",
+    '"text"',
+    "{",
+    '{"other":{}}',
+    '{"codex":null}',
+    '{"codex":[]}',
+    '{"codex":{"aidd-dev-explorer":42}}',
+    '{"codex":{"aidd-dev-explorer":"bad"}}',
+  ])("rejects malformed ownership data %s", async (data) => {
+    await mkdir(join(root, ".aidd"));
+    await writeFile(join(root, ".aidd/agents.json"), data);
+    await expect(store.load(root)).rejects.toThrow();
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts
index 0503162b0..f8ce620be 100644
--- a/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts
@@ -8,11 +8,12 @@ import {
 
 describe("stripAgentFrontmatter", () => {
   describe("keeps allowlisted keys", () => {
-    it("preserves all six allowed keys when all are present", () => {
+    it("preserves all allowed keys when all are present", () => {
       const input = {
         name: "reviewer",
         description: "Reviews code",
         model: "claude-sonnet",
+        reasoningEffort: "medium",
         tools: ["Read", "Write"],
         agents: ["helper"],
         "argument-hint": "[file]",
diff --git a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
index 932d8bdf9..dab3d4c70 100644
--- a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
@@ -1,119 +1,139 @@
 import { describe, expect, it } from "vitest";
-import type { ToolBuildContract } from "../../../../../src/contexts/tools/domain/build-contract.js";
-import { agentModelOptions } from "../../../../../src/contexts/tools/domain/formats/agent-models.js";
-import recommendations from "../../../../../src/contexts/tools/domain/formats/agent-models.json" with {
-  type: "json",
-};
+import {
+  agentIdeNames,
+  agentModelOptions,
+  isAgentHost,
+  isAgentProvider,
+  resolveAgentHost,
+} from "../../../../../src/contexts/tools/domain/formats/agent-models.js";
 import { claude } from "../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
 import { codex } from "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
 import { parseToml } from "../../../../../src/contexts/tools/domain/profiles/codex/toml.js";
 import { copilot } from "../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
-import {
-  buildCursorContract,
-  buildCursorFlatContract,
-} from "../../../../../src/contexts/tools/domain/profiles/cursor/build.js";
+import { cursor } from "../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
 import { opencode } from "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
-import { parseFrontmatter } from "../../../../../src/kernel/markdown.js";
+import { parseFrontmatter, serializeFrontmatter } from "../../../../../src/kernel/markdown.js";
 
-const hosts = [
-  ["claude", claude, { model: "claude-haiku-5-5", effort: "medium" }],
-  ["codex", codex, { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
-  ["copilot", copilot, { model: "gpt-6-luna", reasoningEffort: "medium" }],
-  ["opencode", opencode, { model: "openai/gpt-6-luna#medium" }],
-] as const;
+describe("explicit agent models", () => {
+  it.each([
+    ["claude-code", "claude"],
+    ["claude", "claude"],
+    ["codex", "codex"],
+    ["copilot", "copilot"],
+    ["opencode", "opencode"],
+    ["cursor", "cursor"],
+  ])("resolves IDE %s to host %s", (ide, expected) => {
+    expect(resolveAgentHost(ide)).toBe(expected);
+  });
 
-function transform(contract: ToolBuildContract, plugin: string, role: string, fields = "") {
-  const artifact = contract.artifacts.agents;
-  if (!artifact.supported || artifact.transform === undefined)
-    throw new Error("Missing agent transform");
-  return artifact.transform(
-    `---\nname: ${role}\ndescription: Role\n${fields}---\nBody\n`,
-    plugin,
-    `${role}.md`
-  );
-}
+  it.each(["kilo", "unknown", "constructor", ""])("rejects unsupported IDE %s", (ide) => {
+    expect(() => resolveAgentHost(ide)).toThrow(/not supported/);
+  });
 
-function fields(content: string, toml: boolean) {
-  return toml ? parseToml(content) : parseFrontmatter(content).frontmatter;
-}
+  it("lists the configured public IDE names", () => {
+    expect(agentIdeNames()).toStrictEqual([
+      "claude-code",
+      "codex",
+      "copilot",
+      "opencode",
+      "cursor",
+    ]);
+  });
 
-describe("installed agent model recommendations", () => {
-  it("selects Copilot's native model identifier when its provider is changed to Anthropic", () => {
-    const configuration = structuredClone(recommendations);
-    configuration.tools.copilot.provider = "anthropic";
-    expect(
-      agentModelOptions("copilot", {}, "aidd-dev", "explorer.md", "flat", configuration)
-    ).toStrictEqual({
-      model: "claude-haiku-5.5",
-      reasoningEffort: "medium",
-    });
-    expect(agentModelOptions("copilot", {}, "aidd-dev", "explorer.md")).toStrictEqual({
-      model: "gpt-6-luna",
-      reasoningEffort: "medium",
-    });
+  it.each([
+    ["claude", "anthropic", { model: "claude-haiku-5-5", effort: "medium" }],
+    ["codex", "openai", { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
+    ["copilot", "openai", { model: "gpt-6-luna", reasoningEffort: "medium" }],
+    ["copilot", "anthropic", { model: "claude-haiku-5.5", reasoningEffort: "medium" }],
+    ["opencode", "openai", { model: "openai/gpt-6-luna#medium" }],
+    ["opencode", "anthropic", { model: "anthropic/claude-haiku-5-5#medium" }],
+    ["cursor", "anthropic", { model: "claude-haiku-5-5[effort=medium]" }],
+  ] as const)("serializes %s with the selected %s provider", (host, provider, expected) => {
+    expect(agentModelOptions(host, provider)).toStrictEqual(expected);
   });
-  for (const [label, host, expected] of hosts) {
-    it.each(["explorer", "executor", "reviewer", "validator"])(
-      `${label} installs native defaults for the AIDD %s role`,
-      (role) => {
-        const capability = host.capabilities.agents;
-        const converted = capability.convertFrontmatter(
-          { name: role, description: "Role" },
-          `${role}.md`,
-          "aidd-dev"
-        );
-        expect(fields(capability.serialize(converted, "Body"), label === "codex")).toMatchObject(
-          expected
+
+  it.each([
+    ["claude", "openai"],
+    ["codex", "anthropic"],
+    ["cursor", "openai"],
+  ] as const)("rejects unsupported %s / %s selections", (host, provider) => {
+    expect(() => agentModelOptions(host, provider)).toThrow(/not supported/);
+  });
+
+  it.each(["claude", "codex", "copilot", "opencode", "cursor"])(
+    "recognizes the native %s host",
+    (host) => expect(isAgentHost(host)).toBe(true)
+  );
+  it.each(["claude-code", "kilo", "", "toString", "constructor", "__proto__", null, undefined, 1])(
+    "rejects unknown host %s",
+    (host) => {
+      expect(isAgentHost(host)).toBe(false);
+    }
+  );
+  it.each(["openai", "anthropic"])("recognizes provider %s", (provider) => {
+    expect(isAgentProvider(provider)).toBe(true);
+  });
+  it.each(["unknown", "", "toString", "constructor", "__proto__", null, undefined, 1])(
+    "rejects unknown provider %s",
+    (provider) => {
+      expect(isAgentProvider(provider)).toBe(false);
+    }
+  );
+});
+
+describe("generic agent conversion", () => {
+  for (const host of [claude, codex, copilot, cursor, opencode]) {
+    it(`${host.toolId} leaves unconfigured agents unpinned`, () => {
+      const converted = host.capabilities.agents.convertFrontmatter(
+        { name: "explorer", description: "Role" },
+        "explorer.md"
+      );
+      for (const field of ["model", "effort", "model_reasoning_effort", "reasoningEffort"]) {
+        expect(converted).not.toHaveProperty(field);
+      }
+      for (const build of Object.values(host.buildContracts ?? {})) {
+        const artifact = build().artifacts.agents;
+        if (!artifact.supported || artifact.transform === undefined)
+          throw new Error("Missing agent transform");
+        const content = artifact.transform(
+          "---\nname: explorer\ndescription: Role\n---\nBody\n",
+          "aidd-dev",
+          "explorer.md"
         );
+        const fields =
+          host.toolId === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
+        expect(fields).not.toHaveProperty("model");
       }
-    );
-    it(`${label} preserves explicit native settings and leaves unrelated installations unpinned`, () => {
-      const capability = host.capabilities.agents;
-      const explicit = capability.convertFrontmatter(
-        {
-          name: "explorer",
-          model: "custom-native",
-          effort: "high",
-          model_reasoning_effort: "high",
-          reasoningEffort: "high",
-        },
-        "explorer.md",
-        "aidd-dev"
-      );
-      expect(explicit.model).toBe("custom-native");
-      for (const field of Object.keys(expected).filter((field) => field !== "model"))
-        expect(explicit[field]).toBe("high");
-      expect(
-        capability.convertFrontmatter({ name: "explorer" }, "explorer.md", "personal")
-      ).not.toHaveProperty("model");
     });
-    for (const [mode, build] of Object.entries(host.buildContracts ?? {})) {
-      it(`${label} ${mode} build writes native recommendations`, () => {
-        expect(fields(transform(build(), "aidd-dev", "explorer"), label === "codex")).toMatchObject(
-          expected
-        );
-      });
-      it(`${label} ${mode} build preserves an explicit model and unrelated agents`, () => {
-        const explicit = fields(
-          transform(build(), "aidd-dev", "explorer", "model: custom-native\n"),
-          label === "codex"
-        );
-        expect(explicit.model).toBe("custom-native");
-        expect(
-          fields(transform(build(), "personal", "explorer"), label === "codex")
-        ).not.toHaveProperty("model");
-        expect(
-          fields(transform(build(), "aidd-dev", "planner"), label === "codex")
-        ).not.toHaveProperty("model");
-      });
-    }
   }
-  it("Cursor flat agents carry the native model parameter while plugin agents inherit", () => {
-    expect(
-      fields(transform(buildCursorFlatContract(), "aidd-dev", "explorer"), false)
-    ).toMatchObject({ model: "claude-haiku-5-5[effort=medium]" });
+
+  it.each([
+    [claude, { model: "custom-native", effort: "high" }],
+    [codex, { model: "custom-native", model_reasoning_effort: "high" }],
+    [copilot, { model: "custom-native", reasoningEffort: "high" }],
+    [cursor, { model: "custom-native" }],
+    [opencode, { model: "custom-native#high" }],
+  ] as const)("preserves explicit settings for $toolId", (host, options) => {
+    const capability = host.capabilities.agents;
+    const frontmatter = { name: "explorer", description: "Role", ...options };
+    const converted = capability.convertFrontmatter(frontmatter, "explorer.md");
+    expect(converted).toMatchObject(options);
+    const serialized = capability.serialize(converted, "Body");
     expect(
-      fields(transform(buildCursorContract(), "aidd-dev", "explorer"), false)
-    ).not.toHaveProperty("model");
+      host.toolId === "codex" ? parseToml(serialized) : parseFrontmatter(serialized).frontmatter
+    ).toMatchObject(options);
+    for (const build of Object.values(host.buildContracts ?? {})) {
+      const artifact = build().artifacts.agents;
+      if (!artifact.supported || artifact.transform === undefined)
+        throw new Error("Missing agent transform");
+      const content = artifact.transform(
+        serializeFrontmatter(frontmatter, "Body"),
+        "aidd-dev",
+        "explorer.md"
+      );
+      expect(
+        host.toolId === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter
+      ).toMatchObject(options);
+    }
   });
 });
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
index da5c7d427..81a96d73a 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
@@ -61,8 +61,7 @@ describe("cursor", () => {
     it("keeps model inheritance for AIDD agents installed as native plugins", () => {
       const result = cursor.capabilities.agents.convertFrontmatter(
         { name: "explorer", description: "Role" },
-        "explorer.md",
-        "aidd-dev"
+        "explorer.md"
       );
       expect(result).toEqual({ name: "explorer", description: "Role" });
     });
diff --git a/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts b/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts
index ff70005a1..d368c8ff0 100644
--- a/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts
+++ b/cli/tests/contexts/translate/domain/plugin-content-translator.unit.test.ts
@@ -15,7 +15,7 @@ import {
   PluginDistribution,
 } from "../../../../src/contexts/translate/domain/plugin-distribution.js";
 import { FileHash } from "../../../../src/kernel/file.js";
-import { parseFrontmatter } from "../../../../src/kernel/markdown.js";
+import { parseFrontmatter, serializeFrontmatter } from "../../../../src/kernel/markdown.js";
 
 const stubHasher = { hash: (_content: string) => new FileHash("a".repeat(32)) };
 const translator = new PluginContentTranslator(stubHasher);
@@ -111,9 +111,21 @@ describe("PluginContentTranslator.translate()", () => {
       { model: "openai/gpt-6-luna#medium" },
     ],
   ] as const)(
-    "writes %s agent recommendations through ordinary installation",
+    "preserves %s explicit agent settings through ordinary installation",
     (label, host, path, expected) => {
-      const dist = makeDist({ manifest: { name: "aidd-dev", version: "1.0.0" } });
+      const base = makeDist({ manifest: { name: "aidd-dev", version: "1.0.0" } });
+      const agent = makeFile(
+        "agents/reviewer.md",
+        serializeFrontmatter(
+          { name: "reviewer", description: "Role", ...expected },
+          "Reviewer agent from sample-plugin."
+        )
+      );
+      const dist = makeDist({
+        manifest: base.manifest,
+        files: base.files.map((file) => (file.relativePath === agent.relativePath ? agent : file)),
+        components: { ...base.components, agents: [agent] },
+      });
       const installed = translator.translate(dist, host).find((file) => file.relativePath === path);
       expect(installed).toBeDefined();
       const content = installed?.content ?? "";
diff --git a/cli/tests/e2e/agent-models.e2e.test.ts b/cli/tests/e2e/agent-models.e2e.test.ts
deleted file mode 100644
index 667b68a2b..000000000
--- a/cli/tests/e2e/agent-models.e2e.test.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { parseToml } from "../../src/contexts/tools/domain/profiles/codex/toml.js";
-import { parseFrontmatter } from "../../src/kernel/markdown.js";
-import { REPOSITORY_ROOT } from "../helpers/repository-root.js";
-import { createTestEnv, runCli } from "./helpers.js";
-
-const roles = ["explorer", "executor", "validator", "reviewer"];
-const hosts = [
-  ["claude", ".claude", ".md", { model: "claude-haiku-5-5", effort: "medium" }],
-  ["codex", ".codex", ".toml", { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
-  ["copilot", ".github", ".agent.md", { model: "gpt-6-luna", reasoningEffort: "medium" }],
-  ["opencode", ".opencode", ".md", { model: "openai/gpt-6-luna#medium" }],
-  ["cursor", ".cursor", ".md", { model: "claude-haiku-5-5[effort=medium]" }],
-] as const;
-
-async function source(root: string): Promise<string> {
-  const path = join(root, "source");
-  const plugin = join(path, "plugins", "aidd-dev");
-  await mkdir(join(path, ".claude-plugin"), { recursive: true });
-  await mkdir(join(plugin, ".claude-plugin"), { recursive: true });
-  await mkdir(join(plugin, "agents"));
-  await writeFile(
-    join(path, ".claude-plugin", "marketplace.json"),
-    JSON.stringify({
-      name: "agent-model-tests",
-      owner: { name: "Test" },
-      plugins: [{ name: "aidd-dev", source: "./plugins/aidd-dev" }],
-    })
-  );
-  await writeFile(
-    join(plugin, ".claude-plugin", "plugin.json"),
-    JSON.stringify({ name: "aidd-dev", version: "1.0.0", description: "Agent models" })
-  );
-  for (const role of roles)
-    await copyFile(
-      join(REPOSITORY_ROOT, "plugins", "aidd-dev", "agents", `${role}.md`),
-      join(plugin, "agents", `${role}.md`)
-    );
-  return path;
-}
-
-describe.concurrent("CLI-installed agent model headers", () => {
-  for (const [host, directory, suffix, expected] of hosts) {
-    it(`${host} writes all four agents into the host's native flat directory`, async () => {
-      const box = await createTestEnv(`agent-models-${host}`);
-      try {
-        const input = await source(box.tempDir);
-        const result = await runCli(
-          ["translate", input, "--to", host, "--as", "flat", "--out", box.projectDir],
-          box.projectDir,
-          box.fakeHome
-        );
-        expect(result.exitCode, result.stderr).toBe(0);
-        for (const role of roles) {
-          const content = await readFile(
-            join(box.projectDir, directory, "agents", `aidd-dev-${role}${suffix}`),
-            "utf8"
-          );
-          const fields =
-            host === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
-          expect(fields).toMatchObject(expected);
-          expect(content).toContain("# Behavior");
-        }
-      } finally {
-        await box.cleanup();
-      }
-    });
-
-    if (host === "opencode") continue;
-    it(`${host} marketplace output respects the native agent format`, async () => {
-      const box = await createTestEnv(`agent-models-${host}-plugin`);
-      try {
-        const input = await source(box.tempDir);
-        const output = join(box.tempDir, "built");
-        const result = await runCli(
-          ["translate", input, "--to", host, "--out", output],
-          box.projectDir,
-          box.fakeHome
-        );
-        expect(result.exitCode, result.stderr).toBe(0);
-        for (const role of roles) {
-          const content = await readFile(
-            join(
-              output,
-              "plugins",
-              "aidd-dev",
-              host === "codex" ? "codex-agents" : "agents",
-              `${role}${host === "codex" ? ".toml" : ".md"}`
-            ),
-            "utf8"
-          );
-          const fields =
-            host === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
-          if (host === "cursor") expect(fields).not.toHaveProperty("model");
-          else expect(fields).toMatchObject(expected);
-        }
-      } finally {
-        await box.cleanup();
-      }
-    });
-  }
-});
diff --git a/cli/tests/e2e/agents.e2e.test.ts b/cli/tests/e2e/agents.e2e.test.ts
new file mode 100644
index 000000000..6278cba39
--- /dev/null
+++ b/cli/tests/e2e/agents.e2e.test.ts
@@ -0,0 +1,184 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseToml } from "../../src/contexts/tools/domain/profiles/codex/toml.js";
+import { parseFrontmatter } from "../../src/kernel/markdown.js";
+import { REPOSITORY_ROOT } from "../helpers/repository-root.js";
+import { createTestEnv, runCli } from "./helpers.js";
+
+const roles = ["explorer", "executor", "validator", "reviewer"];
+const cases = [
+  ["claude-code", "anthropic", ".claude", ".md", { model: "claude-haiku-5-5", effort: "medium" }],
+  ["codex", "openai", ".codex", ".toml", { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
+  ["copilot", "openai", ".github", ".agent.md", { model: "gpt-6-luna", reasoningEffort: "medium" }],
+  [
+    "copilot",
+    "anthropic",
+    ".github",
+    ".agent.md",
+    { model: "claude-haiku-5.5", reasoningEffort: "medium" },
+  ],
+  ["opencode", "openai", ".opencode", ".md", { model: "openai/gpt-6-luna#medium" }],
+  ["opencode", "anthropic", ".opencode", ".md", { model: "anthropic/claude-haiku-5-5#medium" }],
+  ["cursor", "anthropic", ".cursor", ".md", { model: "claude-haiku-5-5[effort=medium]" }],
+] as const;
+
+describe.concurrent("explicit native agent installation", () => {
+  for (const [ide, provider, directory, suffix, expected] of cases) {
+    it(`${ide} installs the four agents with ${provider} headers, then removes them`, async () => {
+      const box = await createTestEnv(`agents-${ide}-${provider}`);
+      try {
+        const result = await runCli(
+          ["agents", "install", "--provider", provider, "--ide", ide],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(result.exitCode, result.stderr).toBe(0);
+        for (const role of roles) {
+          const content = await readFile(
+            join(box.projectDir, directory, "agents", `aidd-dev-${role}${suffix}`),
+            "utf8"
+          );
+          const fields =
+            ide === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
+          expect(fields).toMatchObject(expected);
+          if (ide === "opencode") expect(fields.mode).toBe("subagent");
+          else expect(fields.name).toBe(`aidd-dev-${role}`);
+          expect(content).toContain("# Behavior");
+        }
+        const repeated = await runCli(
+          ["agents", "install", "--provider", provider, "--ide", ide],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(repeated.exitCode, repeated.stderr).toBe(0);
+        const removed = await runCli(
+          ["agents", "remove", "--ide", ide],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(removed.exitCode, removed.stderr).toBe(0);
+        for (const role of roles)
+          await expect(
+            access(join(box.projectDir, directory, "agents", `aidd-dev-${role}${suffix}`))
+          ).rejects.toThrow();
+      } finally {
+        await box.cleanup();
+      }
+    });
+  }
+
+  it.each([
+    ["--ide", "codex"],
+    ["--provider", "openai"],
+    ["--provider", "anthropic", "--ide", "codex"],
+    ["--provider", "openai", "--ide", "claude-code"],
+    ["--provider", "unknown", "--ide", "codex"],
+    ["--provider", "openai", "--ide", "unknown"],
+  ])("rejects missing or unsupported selection: %s %s", async (...args) => {
+    const box = await createTestEnv("agents-invalid");
+    try {
+      const result = await runCli(["agents", "install", ...args], box.projectDir, box.fakeHome);
+      expect(result.exitCode).toBe(1);
+      await expect(access(join(box.projectDir, ".aidd", "agents.json"))).rejects.toThrow();
+    } finally {
+      await box.cleanup();
+    }
+  });
+
+  it("refuses a personal-file collision before installing any agent", async () => {
+    const box = await createTestEnv("agents-collision");
+    try {
+      const directory = join(box.projectDir, ".codex", "agents");
+      await mkdir(directory, { recursive: true });
+      const personal = join(directory, "aidd-dev-reviewer.toml");
+      await writeFile(personal, "personal agent\n");
+      const result = await runCli(
+        ["agents", "install", "--provider", "openai", "--ide", "codex"],
+        box.projectDir,
+        box.fakeHome
+      );
+      expect(result.exitCode).toBe(1);
+      expect(await readFile(personal, "utf8")).toBe("personal agent\n");
+      await expect(access(join(directory, "aidd-dev-explorer.toml"))).rejects.toThrow();
+    } finally {
+      await box.cleanup();
+    }
+  });
+
+  it("switches provider explicitly and preserves unrelated personal agents", async () => {
+    const box = await createTestEnv("agents-provider-switch");
+    try {
+      const directory = join(box.projectDir, ".opencode", "agents");
+      await mkdir(directory, { recursive: true });
+      await writeFile(join(directory, "personal.md"), "personal agent\n");
+      for (const provider of ["openai", "anthropic"]) {
+        const result = await runCli(
+          ["agents", "install", "--provider", provider, "--ide", "opencode"],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(result.exitCode, result.stderr).toBe(0);
+      }
+      for (const role of roles) {
+        const content = await readFile(join(directory, `aidd-dev-${role}.md`), "utf8");
+        expect(parseFrontmatter(content).frontmatter.model).toBe(
+          "anthropic/claude-haiku-5-5#medium"
+        );
+      }
+      const removed = await runCli(
+        ["agents", "remove", "--ide", "opencode"],
+        box.projectDir,
+        box.fakeHome
+      );
+      expect(removed.exitCode, removed.stderr).toBe(0);
+      expect(await readFile(join(directory, "personal.md"), "utf8")).toBe("personal agent\n");
+    } finally {
+      await box.cleanup();
+    }
+  });
+
+  it("clean previews then removes opted-in agents without requiring framework setup", async () => {
+    const box = await createTestEnv("agents-clean");
+    try {
+      const installed = await runCli(
+        ["agents", "install", "--provider", "openai", "--ide", "codex"],
+        box.projectDir,
+        box.fakeHome
+      );
+      expect(installed.exitCode, installed.stderr).toBe(0);
+      const directory = join(box.projectDir, ".codex", "agents");
+      const preview = await runCli(["clean"], box.projectDir, box.fakeHome);
+      expect(preview.exitCode, preview.stderr).toBe(0);
+      await access(join(directory, "aidd-dev-explorer.toml"));
+      const cleaned = await runCli(["clean", "--force"], box.projectDir, box.fakeHome);
+      expect(cleaned.exitCode, cleaned.stderr).toBe(0);
+      for (const role of roles)
+        await expect(access(join(directory, `aidd-dev-${role}.toml`))).rejects.toThrow();
+      await expect(access(join(box.projectDir, ".aidd", "agents.json"))).rejects.toThrow();
+    } finally {
+      await box.cleanup();
+    }
+  });
+
+  it("framework distribution contains no opt-in agents", async () => {
+    const box = await createTestEnv("agents-default");
+    try {
+      const output = join(box.tempDir, "built");
+      const result = await runCli(
+        ["translate", REPOSITORY_ROOT, "--to", "claude", "--out", output],
+        box.projectDir,
+        box.fakeHome
+      );
+      expect(result.exitCode, result.stderr).toBe(0);
+      const plugin = join(output, "plugins", "aidd-dev");
+      const manifest = JSON.parse(
+        await readFile(join(plugin, ".claude-plugin", "plugin.json"), "utf8")
+      );
+      expect(manifest).not.toHaveProperty("agents");
+      await expect(access(join(plugin, "agents"))).rejects.toThrow();
+    } finally {
+      await box.cleanup();
+    }
+  });
+});
diff --git a/cli/tests/golden/snapshots/help/surface.json b/cli/tests/golden/snapshots/help/surface.json
index d3cd01093..51c3a9d0e 100644
--- a/cli/tests/golden/snapshots/help/surface.json
+++ b/cli/tests/golden/snapshots/help/surface.json
@@ -2,7 +2,22 @@
   {
     "invocation": "aidd",
     "exitCode": 0,
-    "help": "Usage: aidd [options] [command]\n\nGenerate AI coding assistant configurations from the AIDD framework\n\nOptions:\n  -V, --version                 Show version number\n  --verbose                     Show detailed diagnostic output (default: false)\n  -h, --help                    display help for command\n\nCommands:\n  setup [options]               Set up or update the project to a correct state\n                                — bootstraps the whole project (marketplace,\n                                framework, tools, plugins); see `framework\n                                install`, which acts on the framework alone\n  framework                     Manage the framework's lifecycle on installed\n                                tools\n  translate [options] <source>  Convert an arbitrary source into a target-native\n                                plugin tree — records nothing (see `sync` for\n                                the manifest-driven, tracked version)\n  plugin                        Manage plugins for AI tools\n  marketplace                   Manage plugin marketplaces\n  auth                          Manage authentication\n  sync [options] [files...]     Rewrite owned files from what is already there —\n                                regenerate tracked files, driven by the manifest\n                                (see `translate`, which converts a source\n                                without recording anything)\n  update|upgrade [options]      Update the aidd CLI itself to the latest version\n  doctor [options]              Detected and equipped tools, plugins, drift, and\n                                problems — across all tools or one\n  clean [options]               Remove all AIDD-managed files from the project —\n                                retires every part of AIDD; see `framework\n                                remove`, which removes the framework only\n  telemetry                     Measure what Claude Code sessions consume,\n                                locally\n  help [command]                display help for command"
+    "help": "Usage: aidd [options] [command]\n\nGenerate AI coding assistant configurations from the AIDD framework\n\nOptions:\n  -V, --version                 Show version number\n  --verbose                     Show detailed diagnostic output (default: false)\n  -h, --help                    display help for command\n\nCommands:\n  setup [options]               Set up or update the project to a correct state\n                                — bootstraps the whole project (marketplace,\n                                framework, tools, plugins); see `framework\n                                install`, which acts on the framework alone\n  framework                     Manage the framework's lifecycle on installed\n                                tools\n  agents                        Opt in to native specialist agents for this\n                                project\n  translate [options] <source>  Convert an arbitrary source into a target-native\n                                plugin tree — records nothing (see `sync` for\n                                the manifest-driven, tracked version)\n  plugin                        Manage plugins for AI tools\n  marketplace                   Manage plugin marketplaces\n  auth                          Manage authentication\n  sync [options] [files...]     Rewrite owned files from what is already there —\n                                regenerate tracked files, driven by the manifest\n                                (see `translate`, which converts a source\n                                without recording anything)\n  update|upgrade [options]      Update the aidd CLI itself to the latest version\n  doctor [options]              Detected and equipped tools, plugins, drift, and\n                                problems — across all tools or one\n  clean [options]               Remove all AIDD-managed files from the project —\n                                retires every part of AIDD; see `framework\n                                remove`, which removes the framework only\n  telemetry                     Measure what Claude Code sessions consume,\n                                locally\n  help [command]                display help for command"
+  },
+  {
+    "invocation": "aidd agents",
+    "exitCode": 0,
+    "help": "Usage: aidd agents [options] [command]\n\nOpt in to native specialist agents for this project\n\nOptions:\n  -h, --help         display help for command\n\nCommands:\n  install [options]  Install agents with the selected provider's model and\n                     effort\n  remove [options]   Remove unmodified AIDD agents from this project\n  help [command]     display help for command"
+  },
+  {
+    "invocation": "aidd agents install",
+    "exitCode": 0,
+    "help": "Usage: aidd agents install [options]\n\nInstall agents with the selected provider's model and effort\n\nOptions:\n  --provider <provider>  openai or anthropic\n  --ide <ide>            claude-code, codex, copilot, opencode, cursor\n  -h, --help             display help for command"
+  },
+  {
+    "invocation": "aidd agents remove",
+    "exitCode": 0,
+    "help": "Usage: aidd agents remove [options]\n\nRemove unmodified AIDD agents from this project\n\nOptions:\n  --ide <ide>  claude-code, codex, copilot, opencode, cursor\n  -h, --help   display help for command"
   },
   {
     "invocation": "aidd auth",
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
index 45a85452d..69565a70e 100644
--- a/docs/DELEGATION.md
+++ b/docs/DELEGATION.md
@@ -1,9 +1,11 @@
-# Sub-agent models
+# Optional agents
 
-The CLI's [model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines provider defaults and native fields for the four AIDD agents.
+Install agents in the current project with a provider and IDE:
 
-Installation and translation write supported settings into native agent files. Explicit agent settings take precedence. Other agents keep their own settings.
+```sh
+aidd agents install --provider openai --ide codex
+aidd agents install --provider anthropic --ide claude-code
+aidd agents remove --ide codex
+```
 
-Agent behavior and skills stay independent of model selection. Hosts load the installed configuration when opening a session; model availability depends on the account.
-
-Codex and Cursor require their flat native agent files for these settings: Codex does not discover agents staged inside a plugin, and Cursor plugin agents inherit their model.
+The CLI writes native agents using its [model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json). Plugins do not install these agents.
diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json
index 29136502c..7cd1e16ae 100644
--- a/plugins/aidd-dev/.claude-plugin/plugin.json
+++ b/plugins/aidd-dev/.claude-plugin/plugin.json
@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "aidd-dev",
   "version": "2.6.0",
-  "description": "Code transformation: plan, implement, assert, audit, review, test, refactor, debug, for-sure. Hosts engineering agents.",
+  "description": "Code transformation: plan, implement, assert, audit, review, test, refactor, debug, for-sure.",
   "author": {
     "name": "AI-Driven Dev",
     "url": "https://github.com/ai-driven-dev"
@@ -19,12 +19,6 @@
     "./skills/09-for-sure",
     "./skills/10-batch"
   ],
-  "agents": [
-    "./agents/explorer.md",
-    "./agents/executor.md",
-    "./agents/validator.md",
-    "./agents/reviewer.md"
-  ],
   "keywords": [
     "sdlc",
     "implementation",
diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md
index 2035d6404..ce41d2b55 100644
--- a/plugins/aidd-dev/CATALOG.md
+++ b/plugins/aidd-dev/CATALOG.md
@@ -30,13 +30,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 ### `agents`
 
-| File | Description |
-|------|---|
-| [executor.md](agents/executor.md) | `Implements assigned work within defined scope. Use to build or fix a deliverable, verify the result, and repair failures against the requested outcome.` |
-| [explorer.md](agents/explorer.md) | `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.` |
-| [reviewer.md](agents/reviewer.md) | `Reviews the quality and coherence of finished work. Use to find concrete defects, contradictions, duplication, and unnecessary complexity against project conventions and the real need.` |
-| [validator.md](agents/validator.md) | `Validates that delivered work satisfies the request and acceptance criteria. Use to independently confirm completion and explain failures or missing verification.` |
-
+No files found.
 ### `skills`
 
 #### `skills/01-plan`

From 2bb488286277a879d3514bf0602936ba8e9f8656 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Thu, 15 Oct 2026 20:25:18 +0800
Subject: [PATCH 29/73] test(framework): align verification with opt-in agents

---
 cli/scripts/smoke-tools.sh                    |  31 ++++-
 cli/tests/e2e/kilo-runtime.e2e.test.ts        |  11 +-
 .../agents-wiring.integration.test.ts         | 128 ++++++++++++++++++
 plugins/aidd-dev/CATALOG.md                   |   4 -
 .../skills/01-sdlc/references/02-deliver.md   |   2 +-
 .../skills/01-sdlc/references/03-check.md     |   4 +-
 6 files changed, 169 insertions(+), 11 deletions(-)
 create mode 100644 cli/tests/presentation/commands/agents-wiring.integration.test.ts

diff --git a/cli/scripts/smoke-tools.sh b/cli/scripts/smoke-tools.sh
index d0a7d5f8b..d328a6fc2 100755
--- a/cli/scripts/smoke-tools.sh
+++ b/cli/scripts/smoke-tools.sh
@@ -25,6 +25,7 @@ ALL_COMMANDS=(
   "setup" "doctor" "sync" "translate" "update" "clean"
   "framework install" "framework update" "framework remove" "framework rules"
   "framework validate-recipes"
+  "agents install" "agents remove"
   "plugin remove" "plugin list" "plugin install" "plugin search" "plugin update"
   "marketplace add" "marketplace list" "marketplace remove" "marketplace refresh" "marketplace check"
   "auth login" "auth logout" "auth status"
@@ -64,7 +65,7 @@ project_tree_hash() {
   ' )
 }
 
-PARENTS=" plugin marketplace auth framework telemetry "
+PARENTS=" plugin marketplace auth framework telemetry agents "
 # A parent one level deeper than PARENTS, so a covered key needs three words there, not two.
 GRANDPARENTS=" "
 derive_key() {
@@ -179,6 +180,34 @@ section "recipe validation (bundled)"
 run "framework validate-recipes (bundled)" 0 "PASS: 3 recipe(s) validated." "$ROOT" -- \
   framework validate-recipes --bundled "$ROOT/../plugins/aidd-context/skills/12-cook/assets/recipes"
 
+section "agents (explicit opt-in)"
+P_AGENTS=$(new_project)
+run "agents install (OpenAI / Codex)" 0 "4 agent files installed" "$P_AGENTS" -- \
+  agents install --provider openai --ide codex
+codex_agent="$P_AGENTS/.codex/agents/aidd-dev-explorer.toml"
+if [[ -f "$codex_agent" ]] && grep -qF 'model = "gpt-6-luna"' "$codex_agent" \
+  && grep -qF 'model_reasoning_effort = "medium"' "$codex_agent"; then
+  ok "Codex agent carries the OpenAI model and medium effort"
+else
+  bad "Codex agent lacks the requested native model or effort"
+fi
+run "agents install (unchanged repeat)" 0 "0 agent files installed" "$P_AGENTS" -- \
+  agents install --provider openai --ide codex
+run "agents remove (Codex)" 0 "4 agent files removed" "$P_AGENTS" -- agents remove --ide codex
+run "agents install (Anthropic / Claude Code)" 0 "4 agent files installed" "$P_AGENTS" -- \
+  agents install --provider anthropic --ide claude-code
+claude_agent="$P_AGENTS/.claude/agents/aidd-dev-explorer.md"
+if [[ -f "$claude_agent" ]] && grep -qF 'claude-haiku-5-5' "$claude_agent" \
+  && grep -q 'effort: .*medium' "$claude_agent"; then
+  ok "Claude Code agent carries the Anthropic model and medium effort"
+else
+  bad "Claude Code agent lacks the requested native model or effort"
+fi
+run "agents remove (Claude Code)" 0 "4 agent files removed" "$P_AGENTS" -- agents remove --ide claude-code
+[[ ! -f "$codex_agent" && ! -f "$claude_agent" && ! -f "$P_AGENTS/.aidd/agents.json" ]] \
+  && ok "agents remove clears owned files and the empty ledger" \
+  || bad "agents remove left native files or an empty ledger"
+
 section "translate (local fixture)"
 FW_OUT="$TMPROOT/fw-out"
 if run "translate --to claude" 0 "" "$ROOT" -- \
diff --git a/cli/tests/e2e/kilo-runtime.e2e.test.ts b/cli/tests/e2e/kilo-runtime.e2e.test.ts
index 453ec77f3..002f2a5bc 100644
--- a/cli/tests/e2e/kilo-runtime.e2e.test.ts
+++ b/cli/tests/e2e/kilo-runtime.e2e.test.ts
@@ -280,9 +280,7 @@ describeKiloRuntime("E2E: real Kilo runtime", () => {
         shell: KILO_SHELL,
         maxBuffer: 8 * 1024 * 1024,
       });
-      for (const role of ["explorer", "executor", "reviewer", "validator"]) {
-        expect(agents.stdout).toContain(`aidd-dev-${role}`);
-      }
+      expect(agents.stdout).not.toContain("aidd-dev-");
 
       const mcpProject = join(tempDir, "generated-mcp");
       await mkdir(mcpProject, { recursive: true });
@@ -301,6 +299,13 @@ describeKiloRuntime("E2E: real Kilo runtime", () => {
         fakeHome
       );
       expect(mcpBuild.exitCode, mcpBuild.stderr).toBe(0);
+      const fixtureAgents = await execFileAsync(KILO_BIN, ["agent", "list"], {
+        cwd: mcpProject,
+        env,
+        shell: KILO_SHELL,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      expect(fixtureAgents.stdout).toContain("aidd-test-code-reviewer");
       const mcp = await execFileAsync(KILO_BIN, ["mcp", "list"], {
         cwd: mcpProject,
         env,
diff --git a/cli/tests/presentation/commands/agents-wiring.integration.test.ts b/cli/tests/presentation/commands/agents-wiring.integration.test.ts
new file mode 100644
index 000000000..bc49667ca
--- /dev/null
+++ b/cli/tests/presentation/commands/agents-wiring.integration.test.ts
@@ -0,0 +1,128 @@
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { agentIdeNames } from "../../../src/contexts/tools/domain/formats/agent-models.js";
+
+const install = vi.fn();
+const remove = vi.fn();
+
+vi.mock("../../../src/runtime/wiring/framework.js", () => ({
+  createDeps: vi.fn(async () => ({ manageAgentsUseCase: { install, remove } })),
+}));
+
+const { createDeps } = await import("../../../src/runtime/wiring/framework.js");
+const { registerAgentsCommand } = await import("../../../src/presentation/commands/agents.js");
+
+let written: string[];
+let errors: string[];
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  install.mockResolvedValue(4);
+  remove.mockResolvedValue(2);
+  written = [];
+  errors = [];
+  vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+    written.push(String(chunk));
+    return true;
+  });
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+    errors.push(String(chunk));
+    return true;
+  });
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+async function run(...args: string[]): Promise<string> {
+  const program = new Command();
+  program.exitOverride().option("--verbose");
+  registerAgentsCommand(program);
+  await program.parseAsync(["node", "aidd", ...args]);
+  return written.join("");
+}
+
+describe("explicit agent command routing", () => {
+  it.each(["install", "remove"])("makes %s selections discoverable in help", (action) => {
+    const program = new Command();
+    registerAgentsCommand(program);
+    const command = program.commands[0]?.commands.find((entry) => entry.name() === action);
+    const words = new Set(command?.helpInformation().match(/[\w-]+/g));
+    const choices = [...agentIdeNames(), ...(action === "install" ? ["openai", "anthropic"] : [])];
+    for (const choice of choices) expect(words.has(choice), choice).toBe(true);
+  });
+
+  it.each([
+    ["codex", "openai", "codex"],
+    ["claude-code", "anthropic", "claude"],
+  ])("passes %s and the chosen provider to installation", async (ide, provider, host) => {
+    expect(await run("agents", "install", "--ide", ide, "--provider", provider)).toBe(
+      `4 agent files installed for ${ide}.\n`
+    );
+    expect(install).toHaveBeenCalledExactlyOnceWith({ projectRoot: process.cwd(), host, provider });
+    expect(remove).not.toHaveBeenCalled();
+  });
+
+  it("removes only the selected IDE's agents without selecting a provider", async () => {
+    expect(await run("agents", "remove", "--ide", "codex")).toBe(
+      "2 agent files removed for codex.\n"
+    );
+    expect(remove).toHaveBeenCalledExactlyOnceWith({ projectRoot: process.cwd(), host: "codex" });
+    expect(install).not.toHaveBeenCalled();
+  });
+
+  it.each(["install", "remove"])("passes verbosity to %s dependencies", async (action) => {
+    await run(
+      "--verbose",
+      "agents",
+      action,
+      "--ide",
+      "codex",
+      ...(action === "install" ? ["--provider", "openai"] : [])
+    );
+    expect(createDeps).toHaveBeenCalledExactlyOnceWith(
+      process.cwd(),
+      { verbose: true },
+      expect.anything()
+    );
+  });
+
+  it.each([["install", "--provider", "openai"], ["install", "--ide", "codex"], ["remove"]])(
+    "refuses missing selection before %s runs",
+    async (...args) => {
+      await expect(run("agents", ...args)).rejects.toThrow("required option");
+      expect(createDeps).not.toHaveBeenCalled();
+    }
+  );
+
+  it.each([
+    ["install", "--ide", "codex", "--provider", "other"],
+    ["install", "--ide", "other", "--provider", "openai"],
+    ["remove", "--ide", "other"],
+  ])("refuses unsupported selection before %s runs", async (...args) => {
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("exited");
+    });
+    await expect(run("agents", ...args)).rejects.toThrow("exited");
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(errors.join("")).toMatch(/not supported|Unsupported agent provider/);
+    expect(createDeps).not.toHaveBeenCalled();
+  });
+
+  it.each(["install", "remove"])("reports %s failures and exits unsuccessfully", async (action) => {
+    (action === "install" ? install : remove).mockRejectedValue(new Error("agent was modified"));
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("exited");
+    });
+    await expect(
+      run(
+        "agents",
+        action,
+        "--ide",
+        "codex",
+        ...(action === "install" ? ["--provider", "openai"] : [])
+      )
+    ).rejects.toThrow("exited");
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(errors.join("")).toBe("Error: agent was modified\n");
+  });
+});
diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md
index ce41d2b55..5e9a2992c 100644
--- a/plugins/aidd-dev/CATALOG.md
+++ b/plugins/aidd-dev/CATALOG.md
@@ -7,7 +7,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 ## Table of Contents
 
 - [`.claude-plugin`](#claude-plugin)
-- [`agents`](#agents)
 - [`skills`](#skills)
   - [`skills/01-plan`](#skills01-plan)
   - [`skills/02-implement`](#skills02-implement)
@@ -28,9 +27,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 |------|
 | [plugin.json](.claude-plugin/plugin.json) |
 
-### `agents`
-
-No files found.
 ### `skills`
 
 #### `skills/01-plan`
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 4d21e24a2..687043bbc 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -22,7 +22,7 @@ flowchart TD
 
   subgraph ExecuteStage["Execute and validate the plan"]
     direction TB
-    Executor(["@aidd-dev:executor"])
+    Executor(["@aidd-dev-executor"])
     Implement["/aidd-dev:02-implement"]
     Assert["/aidd-dev:03-assert"]
     Integrate["Integrate phases"]
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index b94e7d19c..3ab16d874 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -31,8 +31,8 @@ flowchart TD
     Plan["$plan"]
     CommittedCandidate["$committed_candidate"]
     ValidationReports["$validation_reports"]
-    Validator(["@aidd-dev:validator"])
-    Reviewer(["@aidd-dev:reviewer"])
+    Validator(["@aidd-dev-validator"])
+    Reviewer(["@aidd-dev-reviewer"])
     Review["/aidd-dev:05-review"]
   end
 

From 76791356f0f9ec438b08fd7cf4d6f45cd227867e Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:00:59 +0800
Subject: [PATCH 30/73] feat(cli): add main model recommendations and mistral
 agents

---
 .../tools/domain/formats/agent-models.json    | 36 +++++++++++++++----
 .../tools/domain/formats/agent-models.ts      |  6 +++-
 cli/src/presentation/commands/agents.ts       |  3 +-
 .../domain/formats/agent-models.unit.test.ts  |  7 +++-
 cli/tests/e2e/agents.e2e.test.ts              |  8 ++---
 cli/tests/golden/snapshots/help/surface.json  |  2 +-
 .../agents-wiring.integration.test.ts         |  6 +++-
 7 files changed, 52 insertions(+), 16 deletions(-)

diff --git a/cli/src/contexts/tools/domain/formats/agent-models.json b/cli/src/contexts/tools/domain/formats/agent-models.json
index 6c334c58e..a9537392e 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.json
+++ b/cli/src/contexts/tools/domain/formats/agent-models.json
@@ -1,14 +1,36 @@
 {
   "providers": {
     "openai": {
-      "model": "gpt-6-luna",
-      "effort": "medium"
+      "main": {
+        "model": "gpt-6.1-sol",
+        "effort": "medium"
+      },
+      "subagent": {
+        "model": "gpt-6-luna",
+        "effort": "medium"
+      }
     },
     "anthropic": {
-      "model": "claude-haiku-5-5",
-      "effort": "medium",
-      "nativeModels": {
-        "copilot": "claude-haiku-5.5"
+      "main": {
+        "model": "claude-opus-5-5",
+        "effort": "medium"
+      },
+      "subagent": {
+        "model": "claude-haiku-5-5",
+        "effort": "medium",
+        "nativeModels": {
+          "copilot": "claude-haiku-5.5"
+        }
+      }
+    },
+    "mistral": {
+      "main": {
+        "model": "mistral-medium-2604",
+        "effort": "high"
+      },
+      "subagent": {
+        "model": "mistral-small-2603",
+        "effort": "high"
       }
     }
   },
@@ -27,7 +49,7 @@
       "effortField": "reasoningEffort"
     },
     "opencode": {
-      "providers": ["openai", "anthropic"],
+      "providers": ["openai", "anthropic", "mistral"],
       "effortPrefix": "#",
       "effortSuffix": "",
       "providerPrefix": true
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.ts b/cli/src/contexts/tools/domain/formats/agent-models.ts
index edc65df6d..e1b9c5f3d 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.ts
+++ b/cli/src/contexts/tools/domain/formats/agent-models.ts
@@ -11,6 +11,10 @@ export function isAgentProvider(value: unknown): value is AgentProvider {
   return typeof value === "string" && Object.hasOwn(models.providers, value);
 }
 
+export function agentProviderNames(): string[] {
+  return Object.keys(models.providers);
+}
+
 export function agentIdeNames(): string[] {
   return Object.entries(models.hosts).map(([host, target]) =>
     "ide" in target ? target.ide : host
@@ -34,7 +38,7 @@ export function agentModelOptions(
   if (!target.providers.includes(provider)) {
     throw new Error(`Provider "${provider}" is not supported by "${host}".`);
   }
-  const source = models.providers[provider];
+  const source = models.providers[provider].subagent;
   const nativeModel =
     "nativeModels" in source
       ? (Object.entries(source.nativeModels).find(([name]) => name === host)?.[1] ?? source.model)
diff --git a/cli/src/presentation/commands/agents.ts b/cli/src/presentation/commands/agents.ts
index 29d20f64a..7852c35da 100644
--- a/cli/src/presentation/commands/agents.ts
+++ b/cli/src/presentation/commands/agents.ts
@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import {
   agentIdeNames,
+  agentProviderNames,
   isAgentProvider,
   resolveAgentHost,
 } from "../../contexts/tools/domain/formats/agent-models.js";
@@ -15,7 +16,7 @@ export function registerAgentsCommand(program: Command): void {
   agents
     .command("install")
     .description("Install agents with the selected provider's model and effort")
-    .requiredOption("--provider <provider>", "openai or anthropic")
+    .requiredOption("--provider <provider>", agentProviderNames().join(", "))
     .requiredOption("--ide <ide>", agentIdeNames().join(", "))
     .action(async (options: { provider: string; ide: string }) => {
       const { projectRoot, verbose, output } = parseGlobalOptions(program);
diff --git a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
index dab3d4c70..41943fa5e 100644
--- a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
@@ -47,6 +47,7 @@ describe("explicit agent models", () => {
     ["copilot", "anthropic", { model: "claude-haiku-5.5", reasoningEffort: "medium" }],
     ["opencode", "openai", { model: "openai/gpt-6-luna#medium" }],
     ["opencode", "anthropic", { model: "anthropic/claude-haiku-5-5#medium" }],
+    ["opencode", "mistral", { model: "mistral/mistral-small-2603#high" }],
     ["cursor", "anthropic", { model: "claude-haiku-5-5[effort=medium]" }],
   ] as const)("serializes %s with the selected %s provider", (host, provider, expected) => {
     expect(agentModelOptions(host, provider)).toStrictEqual(expected);
@@ -56,6 +57,10 @@ describe("explicit agent models", () => {
     ["claude", "openai"],
     ["codex", "anthropic"],
     ["cursor", "openai"],
+    ["claude", "mistral"],
+    ["codex", "mistral"],
+    ["copilot", "mistral"],
+    ["cursor", "mistral"],
   ] as const)("rejects unsupported %s / %s selections", (host, provider) => {
     expect(() => agentModelOptions(host, provider)).toThrow(/not supported/);
   });
@@ -70,7 +75,7 @@ describe("explicit agent models", () => {
       expect(isAgentHost(host)).toBe(false);
     }
   );
-  it.each(["openai", "anthropic"])("recognizes provider %s", (provider) => {
+  it.each(["openai", "anthropic", "mistral"])("recognizes provider %s", (provider) => {
     expect(isAgentProvider(provider)).toBe(true);
   });
   it.each(["unknown", "", "toString", "constructor", "__proto__", null, undefined, 1])(
diff --git a/cli/tests/e2e/agents.e2e.test.ts b/cli/tests/e2e/agents.e2e.test.ts
index 6278cba39..bfa2b07ae 100644
--- a/cli/tests/e2e/agents.e2e.test.ts
+++ b/cli/tests/e2e/agents.e2e.test.ts
@@ -20,6 +20,7 @@ const cases = [
   ],
   ["opencode", "openai", ".opencode", ".md", { model: "openai/gpt-6-luna#medium" }],
   ["opencode", "anthropic", ".opencode", ".md", { model: "anthropic/claude-haiku-5-5#medium" }],
+  ["opencode", "mistral", ".opencode", ".md", { model: "mistral/mistral-small-2603#high" }],
   ["cursor", "anthropic", ".cursor", ".md", { model: "claude-haiku-5-5[effort=medium]" }],
 ] as const;
 
@@ -73,6 +74,7 @@ describe.concurrent("explicit native agent installation", () => {
     ["--provider", "openai"],
     ["--provider", "anthropic", "--ide", "codex"],
     ["--provider", "openai", "--ide", "claude-code"],
+    ["--provider", "mistral", "--ide", "codex"],
     ["--provider", "unknown", "--ide", "codex"],
     ["--provider", "openai", "--ide", "unknown"],
   ])("rejects missing or unsupported selection: %s %s", async (...args) => {
@@ -112,7 +114,7 @@ describe.concurrent("explicit native agent installation", () => {
       const directory = join(box.projectDir, ".opencode", "agents");
       await mkdir(directory, { recursive: true });
       await writeFile(join(directory, "personal.md"), "personal agent\n");
-      for (const provider of ["openai", "anthropic"]) {
+      for (const provider of ["openai", "anthropic", "mistral"]) {
         const result = await runCli(
           ["agents", "install", "--provider", provider, "--ide", "opencode"],
           box.projectDir,
@@ -122,9 +124,7 @@ describe.concurrent("explicit native agent installation", () => {
       }
       for (const role of roles) {
         const content = await readFile(join(directory, `aidd-dev-${role}.md`), "utf8");
-        expect(parseFrontmatter(content).frontmatter.model).toBe(
-          "anthropic/claude-haiku-5-5#medium"
-        );
+        expect(parseFrontmatter(content).frontmatter.model).toBe("mistral/mistral-small-2603#high");
       }
       const removed = await runCli(
         ["agents", "remove", "--ide", "opencode"],
diff --git a/cli/tests/golden/snapshots/help/surface.json b/cli/tests/golden/snapshots/help/surface.json
index 51c3a9d0e..9c14b578b 100644
--- a/cli/tests/golden/snapshots/help/surface.json
+++ b/cli/tests/golden/snapshots/help/surface.json
@@ -12,7 +12,7 @@
   {
     "invocation": "aidd agents install",
     "exitCode": 0,
-    "help": "Usage: aidd agents install [options]\n\nInstall agents with the selected provider's model and effort\n\nOptions:\n  --provider <provider>  openai or anthropic\n  --ide <ide>            claude-code, codex, copilot, opencode, cursor\n  -h, --help             display help for command"
+    "help": "Usage: aidd agents install [options]\n\nInstall agents with the selected provider's model and effort\n\nOptions:\n  --provider <provider>  openai, anthropic, mistral\n  --ide <ide>            claude-code, codex, copilot, opencode, cursor\n  -h, --help             display help for command"
   },
   {
     "invocation": "aidd agents remove",
diff --git a/cli/tests/presentation/commands/agents-wiring.integration.test.ts b/cli/tests/presentation/commands/agents-wiring.integration.test.ts
index bc49667ca..f6cb63e32 100644
--- a/cli/tests/presentation/commands/agents-wiring.integration.test.ts
+++ b/cli/tests/presentation/commands/agents-wiring.integration.test.ts
@@ -47,13 +47,17 @@ describe("explicit agent command routing", () => {
     registerAgentsCommand(program);
     const command = program.commands[0]?.commands.find((entry) => entry.name() === action);
     const words = new Set(command?.helpInformation().match(/[\w-]+/g));
-    const choices = [...agentIdeNames(), ...(action === "install" ? ["openai", "anthropic"] : [])];
+    const choices = [
+      ...agentIdeNames(),
+      ...(action === "install" ? ["openai", "anthropic", "mistral"] : []),
+    ];
     for (const choice of choices) expect(words.has(choice), choice).toBe(true);
   });
 
   it.each([
     ["codex", "openai", "codex"],
     ["claude-code", "anthropic", "claude"],
+    ["opencode", "mistral", "opencode"],
   ])("passes %s and the chosen provider to installation", async (ide, provider, host) => {
     expect(await run("agents", "install", "--ide", ide, "--provider", provider)).toBe(
       `4 agent files installed for ${ide}.\n`

From fd76602fdf9cf55e2d9b5c5ff7b5ea210ba775d4 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:02:32 +0800
Subject: [PATCH 31/73] refactor(framework): keep optional agents independent
 of skills

---
 AGENTS.md                                          | 11 +----------
 cli/assets/agents/executor.md                      |  8 --------
 cli/assets/agents/reviewer.md                      |  8 ++------
 docs/ARCHITECTURE.md                               |  6 +++---
 .../skills/02-project-memory/actions/04-sync.md    |  3 +--
 .../02-project-memory/assets/templates/AGENTS.md   |  7 +------
 .../aidd-context/skills/06-agent-generate/SKILL.md |  2 +-
 .../06-agent-generate/actions/01-capture-agent.md  |  2 +-
 .../06-agent-generate/actions/02-write-agent.md    |  4 ++--
 .../06-agent-generate/actions/03-validate.md       |  6 +++---
 .../06-agent-generate/assets/agent-template.md     |  4 ----
 .../references/agent-authoring.md                  |  7 +------
 .../06-agent-generate/references/tool-paths.md     | 14 ++++++++------
 plugins/aidd-dev/README.md                         |  9 +--------
 .../aidd-dev/skills/01-plan/actions/02-explore.md  |  2 +-
 .../aidd-dev/skills/10-batch/actions/01-batch.md   |  5 +++--
 plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md  |  2 +-
 .../skills/01-sdlc/references/02-deliver.md        |  2 +-
 .../skills/01-sdlc/references/03-check.md          | 12 ++++++------
 19 files changed, 37 insertions(+), 77 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9dc0cf672..fe7637c63 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,16 +34,7 @@
 
 ## Agents
 
-Use available agents when useful. The caller owns scope, delegation, and final acceptance; no mandatory sequence.
-
-<!-- aidd_agents:start -->
-| name | role |
-| --- | --- |
-| @aidd-dev-explorer | Explore the codebase and return relevant files, code, and explanations for a scoped question. |
-| @aidd-dev-executor | Implement assigned work and return changes with verification evidence. |
-| @aidd-dev-validator | Validate that delivered work satisfies the requested outcome and acceptance criteria. |
-| @aidd-dev-reviewer | Review quality and coherence against project conventions and the quality checklist. |
-<!-- aidd_agents:end -->
+Use available host agents by responsibility when useful; custom agents are optional. The caller owns scope, delegation, and final acceptance.
 
 ## Memory Management
 
diff --git a/cli/assets/agents/executor.md b/cli/assets/agents/executor.md
index 5ca3799bd..17a9b2a34 100644
--- a/cli/assets/agents/executor.md
+++ b/cli/assets/agents/executor.md
@@ -23,11 +23,3 @@ Return a concise result; omit empty fields.
 **Checks:** <what ran and its result>
 **Remaining:** <unfinished work or blockers, if any>
 ```
-
-# Skills you may invoke
-
-- `/aidd-dev:02-implement`
-- `/aidd-dev:03-assert`
-- `/aidd-dev:06-test`
-- `/aidd-dev:08-debug`
-- `/aidd-vcs:01-commit`
diff --git a/cli/assets/agents/reviewer.md b/cli/assets/agents/reviewer.md
index 1ff2d9c4c..9bc7b4eca 100644
--- a/cli/assets/agents/reviewer.md
+++ b/cli/assets/agents/reviewer.md
@@ -9,9 +9,9 @@ Review finished work independently and identify quality or coherence gaps that a
 
 # Behavior
 
-- **Review the actual work and need independently**, using project conventions and the installed review skill's `references/quality-checklist.md`. Check coherence, relevance, and gaps in existing validation evidence; leave acceptance completion to the validator.
+- **Review the actual work and need independently**, using project conventions and caller-supplied criteria. Check defects, contradictions, duplication, unnecessary complexity, and gaps in validation evidence.
 - **Tie findings to evidence and impact**; distinguish defects from suggestions, name uncertainty, and suggest the smallest correction.
-- **Keep the work unchanged** and return findings to the caller. An optional review skill's report replaces this output; do not duplicate it.
+- **Keep the work unchanged** and return findings to the caller.
 
 # Output
 
@@ -22,7 +22,3 @@ Return a concise review.
 
 - **<finding>:** <impact, evidence, and smallest correction>
 ```
-
-# Skills you may invoke
-
-- `/aidd-dev:05-review`
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f90a13080..a889dd05a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -91,7 +91,7 @@ flowchart TB
   User -->|direct invocation| Recipe["Recipe SKILL.md"]
   Protocol -->|discover and invoke provider| Recipe
   Protocol -->|authorized isolation| Agent["Agent"]
-  Agent -->|declared recipes only| Recipe
+  Agent -->|scoped work| Recipe
   Recipe --> Action["Self-contained action"]
   Action --> Result["Result or artifact"]
 ```
@@ -103,7 +103,7 @@ flowchart TB
 | Skill | Host loads `SKILL.md` on invocation; work runs in the caller's context. |
 | Caller | Owns scope, delegation, integration, and acceptance. |
 | Orchestrator | Sequences capabilities on the caller's behalf. |
-| Agent | Isolates a scoped task, invokes declared recipes, reads supporting references, and returns its result to the caller. |
+| Agent | Isolates a scoped task and returns its result to the caller. Custom agents are optional, self-contained behaviors in one native file per host. |
 | Recipe | Primary callers may delegate bounded work; isolated recipes return to their caller. |
 | Reconnaissance helper | Read-only; neither mutates nor spawns. |
 | Write path | At most two delegation layers; no cycles. |
@@ -131,7 +131,7 @@ Dependency-free Node scripts declared in `hooks/hooks.json`; `node` must be on `
 
 | Context | Rule |
 | --- | --- |
-| Dispatch tables (`## Actions`), orchestration references and agent permissions (`# Skills you may invoke`) | Canonical `/plugin:folder` or `@plugin:agent` addresses. Elsewhere, name the responsibility. |
+| Dispatch tables (`## Actions`) and orchestration references | Canonical `/plugin:folder` skill addresses. Delegate agent work by responsibility, without custom agent names. |
 | Cross-plugin providers | Recipes discover by description rather than hardcoding siblings; orchestrators verify installation before dispatch. |
 | Backlog flow | Owned by `aidd-orchestrator:02-backlog`. |
 | Orthogonality exceptions | `isExemptFromOrthogonality` permits responsibility maps in `plugins/aidd-orchestrator/**` and onboarding menus in `plugins/aidd-context/skills/00-onboard/**`. The onboarding exemption ends with runtime provider discovery. |
diff --git a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
index 01f3414cc..e96e752ae 100644
--- a/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
+++ b/plugins/aidd-context/skills/02-project-memory/actions/04-sync.md
@@ -20,8 +20,7 @@ Each picked tool's context file, carrying the filled block.
    - Its AIDD structure differs: offer to reconcile it, applying only what the user approves.
 5. **Fill.** Run `hooks/update_memory.js` from the project root, naming the picked tools, and stop on a non-zero exit.
    - No script, the skill shipped alone: write each block from the bank.
-6. **Agents.** Fill `aidd_agents:start` / `aidd_agents:end` with installed, invocable agents and short English verb-led roles; add the block when absent and label differing names by host. Preserve text outside managed blocks.
-7. **Verify.** Read each picked tool's block back and compare it to the bank; verify every listed agent is available.
+6. **Verify.** Read each picked tool's block back and compare it to the bank.
    - A file in one and not the other: the fill did not land, report it and stop.
 
 ## Test
diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
index 6ffd3e2bb..75f6097c5 100644
--- a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
+++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
@@ -36,12 +36,7 @@
 
 ## Agents
 
-Use available agents when useful. The caller owns scope, delegation, and final acceptance; no mandatory sequence.
-
-<!-- aidd_agents:start -->
-| name | role |
-| --- | --- |
-<!-- aidd_agents:end -->
+Use available host agents by responsibility when useful; custom agents are optional. The caller owns scope, delegation, and final acceptance.
 
 ## Memory Management
 
diff --git a/plugins/aidd-context/skills/06-agent-generate/SKILL.md b/plugins/aidd-context/skills/06-agent-generate/SKILL.md
index 0ed301d81..c10f3d3f8 100644
--- a/plugins/aidd-context/skills/06-agent-generate/SKILL.md
+++ b/plugins/aidd-context/skills/06-agent-generate/SKILL.md
@@ -6,7 +6,7 @@ argument-hint: role
 
 # Agent Generate
 
-Write one canonical agent from intent and render it per confirmed host tool, or once as a plugin source.
+Write one self-contained behavior per agent and render it as one file per confirmed host tool, or once as a plugin source.
 
 ## Actions
 
diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md b/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md
index 45010c424..8cb856fb3 100644
--- a/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md
+++ b/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md
@@ -14,7 +14,7 @@ In-context: the role and its system prompt, the chosen name, an optional user-sp
 
 1. **Gate.** Run the asset-access precheck ([tool-paths.md](../references/tool-paths.md)).
 2. **Clarify.** Ask about the purpose, tools, inputs, and instructions. If anything stays vague, ask again before moving on.
-3. **Draft.** Write the canonical role ([agent-authoring.md](../references/agent-authoring.md)): a frontmatter intent + a system-prompt body. Include only the optional and orchestration sections it needs.
+3. **Draft.** Write the canonical role ([agent-authoring.md](../references/agent-authoring.md)): a frontmatter intent + a self-contained behavior, with inputs and output only when useful. Keep workflows in skills.
 4. **Name.** Propose three short, catchy names that fit the purpose, and have the user pick one.
 5. **Score.** Rate the agent 1-10 on clarity and completeness. If it scores under 8, revise and score again.
 6. **Mode.** Ask where the agent goes:
diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md b/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md
index 92c656e02..58cbe5b3b 100644
--- a/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md
+++ b/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md
@@ -8,7 +8,7 @@ From 01: the role, the chosen name, an optional user-specified model, and the wr
 
 ## Output
 
-One agent file per confirmed tool, and the list of files written.
+One self-contained agent file per confirmed tool, and the list of files written.
 
 ## Process
 
@@ -16,7 +16,7 @@ One agent file per confirmed tool, and the list of files written.
 2. **Frontmatter.** Apply the per-tool frontmatter from [tool-paths.md](../references/tool-paths.md). Drop a field where the tool does not support it. Plugin source: keep the canonical frontmatter.
 3. **Convert.** Apply any per-tool structural conversion listed in [tool-paths.md](../references/tool-paths.md). Plugin source skips conversion.
 4. **Render.** Per the write mode ([tool-paths.md](../references/tool-paths.md)):
-   - **Host**: for each confirmed tool, write to its path and extension.
+   - **Host**: for each confirmed tool, write one file at its path and extension; keep the full behavior in that file.
    - **Plugin source**: write one canonical agent. No per-tool fan-out.
 5. **Validate.** Run the write-target validation ([tool-paths.md](../references/tool-paths.md)).
 
diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md b/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md
index 9169f12c2..bfdd6cc6c 100644
--- a/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md
+++ b/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md
@@ -13,9 +13,9 @@ A short pass or fail line per agent file.
 ## Process
 
 1. **Exists.** Confirm each file is on disk at its expected path.
-2. **Shape.** Confirm each file matches its target format ([tool-paths.md](../references/tool-paths.md)), a confirmed tool's, or the canonical form in plugin source, and carries the name, description, and body.
-3. **Concise.** Confirm the body stays focused on one role.
+2. **Shape.** Confirm each file matches its target format ([tool-paths.md](../references/tool-paths.md)) and carries its required metadata and behavior.
+3. **Concise.** Confirm the body stays focused on one behavior, contained in the agent file without a required skill or companion file.
 
 ## Test
 
-- Every agent file exists, carries name and description, and holds the role body.
+- Every agent file exists, identifies its role in the target format, and holds the behavior.
diff --git a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md
index de68b741b..296cf316f 100644
--- a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md
+++ b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md
@@ -14,8 +14,4 @@ description: <what it does + when to use>  # required, third person
 <!-- Optional sections, add one only when it adds value, omit when empty:
 # Inputs:                what it receives when invoked
 # Outputs:               what it returns
-# Guardrails:            behavioral boundaries
-# Skills you may invoke: allowed recipes by canonical /plugin:folder address; verify availability before invocation
-
-For an orchestration agent only: # Definition of Ready, # Definition of Done, # Decisions in scope, # Decisions out of scope, # Handoffs. See references/agent-authoring.md.
 -->
diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
index 504d5d336..08977eb33 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md
@@ -4,7 +4,7 @@ The contract every generated agent must satisfy. An agent is a focused role with
 
 ## Rules
 
-- **R1.** One agent, one role. A single, clear responsibility.
+- **R1.** One agent, one behavior, self-contained in one file per target. Workflows belong in skills; omit skill permission lists and required companion files.
 - **R2.** Frontmatter: `name` and `description` are required. `model` is optional. The description states what the agent does and when to use it.
 - **R3.** The body is the system prompt. Required: `# Role` and `# Behavior` (bounded capabilities and constraints). Optional sections: see `## Body shape`. Concise and imperative.
 - **R4.** English only, regardless of conversation language.
@@ -21,8 +21,3 @@ Short imperative sentences. Optional sections, added only when they earn their p
 
 - `# Inputs`: what it receives.
 - `# Outputs`: what it returns.
-- `# Guardrails`: behavioral boundaries.
-- `# Skills you may invoke`: list allowed recipes by canonical `/plugin:folder` address; verify availability before invocation.
-- `# Definition of Ready` / `# Definition of Done`: start and finish gates.
-- `# Decisions in scope` / `# Decisions out of scope`: what it may decide, what it must defer.
-- `# Handoffs`: who it returns to.
diff --git a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
index 90a1badde..ad9a0896d 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
@@ -16,15 +16,17 @@ Agents are supported on all five tools.
 
 ## Frontmatter per tool
 
-The canonical agent carries `name` and `description`. Emit those a row accepts, drop the rest. Optional fields, including `model`, only if the user asked. Never invent a value.
+The canonical agent carries `name` and `description`. Emit those a row accepts, drop the rest. Add model or effort settings only when requested and supported.
 
 | Tool           | Accepts                                                      |
 | -------------- | ----------------------------------------------------------- |
-| Claude Code    | `name`, `description`, optional `model`, `color`, `tools`   |
+| Claude Code    | `name`, `description`, optional `model`, `effort`, `color`, `tools` |
 | Cursor         | `name`, `description`, optional `model`, `readonly`, `is_background` |
-| OpenCode       | `name`, `description`, optional `model`, `temperature`, `permission` |
-| GitHub Copilot | `name`, `description`, optional `model`, `tools`            |
-| Codex CLI      | `name`, `description` (drops `model`)                       |
+| OpenCode V2    | `description`, `mode: subagent`, optional `model` as `provider/model#variant`, `permissions` |
+| GitHub Copilot | `name`, `description`, optional `model`, `reasoningEffort`, `tools` |
+| Codex CLI      | `name`, `description`, optional `model`, `model_reasoning_effort` |
+
+Native fields checked 2026-10-16: [Claude](https://code.claude.com/docs/en/sub-agents#frontmatter-reference), [Cursor](https://cursor.com/docs/subagents#file-format), [OpenCode V2](https://opencode.ai/v2/docs/agents#model), [Copilot](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agent-frontmatter-fields), [Codex](https://developers.openai.com/codex/subagents#custom-agent-file-schema).
 
 ## Codex TOML conversion
 
@@ -32,7 +34,7 @@ Codex agents are TOML, not markdown. Convert:
 
 - Each frontmatter field becomes a top-level TOML key. Quote every string value with `"double quotes"` (a TOML basic string) and escape any embedded `"` or backslash, so a quote or apostrophe in the description stays valid TOML.
 - The body becomes `developer_instructions`, wrapped in `'''` literal delimiters (no escaping of the markdown).
-- Drop `model`.
+- Keep an explicitly requested `model` and `model_reasoning_effort`.
 
 ## Detect (which tools are installed)
 
diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md
index 30e1d7250..cc7dfc763 100644
--- a/plugins/aidd-dev/README.md
+++ b/plugins/aidd-dev/README.md
@@ -8,7 +8,7 @@ Code transformation plugin for the AI-Driven Development framework.
 
 First time? Install with `/plugin install aidd-dev@aidd-framework`, then run `aidd-dev:01-plan`.
 
-Covers code transformation: planning, implementation, assertions, audits, code review, testing, refactoring, debugging, for-sure, and parallel batch execution. Also hosts AI agents.
+Covers code transformation: planning, implementation, assertions, audits, code review, testing, refactoring, debugging, for-sure, and parallel batch execution.
 
 ## Skills
 
@@ -24,10 +24,3 @@ Covers code transformation: planning, implementation, assertions, audits, code r
 | [2.8] | [debug](skills/08-debug/SKILL.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. |
 | [2.9] | [for-sure](skills/09-for-sure/SKILL.md) | Iterative agent loop that tracks attempts and retries until a success condition is met. |
 | [2.10] | [batch](skills/10-batch/SKILL.md) | Split a request into independent tasks, execute them in parallel, and summarize each agent's task, status, and result. |
-
-## Agents
-
-| Agent | Description |
-|---|---|
-| executor | Dispatched doer in its own context. Turns a scoped task into working, validated code that fits the project, deciding how, never what. Never authors a plan, never judges its own work. |
-| checker | Independent critic in fresh context. Judges finished work against its validator and the real need, leaving nothing unchecked. Returns findings, scores, and a verdict. Never edits the work, never implements the fix. |
diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index e6e69076a..3511ced8d 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -13,7 +13,7 @@ The architecture projection (files to modify, create, delete, each with a one-li
 ## Process
 
 1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions.
-   - Delegate independent domain questions to explorers with a scope and expected findings; reconcile their sourced answers and keep unresolved uncertainty visible.
+   - When useful, delegate independent domain questions to available agents with a scope and expected findings; reconcile their sourced answers and keep unresolved uncertainty visible.
 2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
 3. **Select.** Keep the project rules that apply to the projection.
 
diff --git a/plugins/aidd-dev/skills/10-batch/actions/01-batch.md b/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
index 9edbd4ae3..500ad7a91 100644
--- a/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
+++ b/plugins/aidd-dev/skills/10-batch/actions/01-batch.md
@@ -17,9 +17,10 @@ One row per dispatched agent, identified by its name or ID. Status is `Done` (ta
 
 1. **Read.** Take `prompt` from the arguments; if empty, ask the user.
 2. **Split.** Divide the prompt into distinct, independent tasks. Inline, no agent.
-3. **Launch.** Spawn one scoped executor per task, all in parallel with fresh contexts. Supply each task's criteria, write ownership, checks, and commit policy. Track each agent's name or ID; require its outcome, changed files, validation evidence, and remaining work.
+3. **Launch.** Spawn one available implementation agent per task, all in parallel with fresh contexts. Supply each task's criteria, write ownership, checks, and commit policy. Isolate mutable validation resources and Git indexes; otherwise the caller owns shared operations. Track each agent's name or ID; require its outcome, changed files, validation evidence, and remaining work.
 4. **Collect.** Wait for every dispatched agent to finish or report a blocker. Preserve blocked and failed outcomes; mark an agent that exits with an error as `Failed` even if it returns no summary.
-5. **Report.** Print exactly one final table using the output columns, nothing else. Base each status and result on the collected evidence.
+5. **Integrate.** Combine the changes and check affected interactions before accepting completed tasks; report integration failures on the affected rows.
+6. **Report.** Print exactly one final table using the output columns, nothing else. Base each status and result on the collected evidence.
 
 ## Test
 
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
index 9e5dad479..e888e539f 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
@@ -10,7 +10,7 @@ argument-hint: request | interactive request
 
 Decide the mode as `mode.md` says, then read only it and the current zone's reference. Verify that every named provider is installed before calling it. A zone that cannot proceed stops the run and says what it would take to resume.
 
-Spawn specialized agents for isolated work. Parallelize independent work when it is faster. Give each agent one focused task that a smaller model can execute. Repeat the responsible zone when delegated work returns an actionable gap.
+Use available host agents by responsibility, or a general-purpose agent with a scoped brief; custom agents are optional. Parallelize independent work when it is faster. Repeat the responsible zone when delegated work returns an actionable gap.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 687043bbc..137e4c246 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -22,7 +22,7 @@ flowchart TD
 
   subgraph ExecuteStage["Execute and validate the plan"]
     direction TB
-    Executor(["@aidd-dev-executor"])
+    Executor(["Implementation agent"])
     Implement["/aidd-dev:02-implement"]
     Assert["/aidd-dev:03-assert"]
     Integrate["Integrate phases"]
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index 3ab16d874..66c826d2f 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -2,9 +2,9 @@
 
 ## Behavior
 
-- Dispatch a fresh validator on the committed candidate, contract, criteria, and mandatory checks.
-- After validation passes, dispatch a fresh reviewer for quality and coherence; select code and relevancy axes, using the validator's acceptance evidence.
-- After review clears, the same reviewer challenges whether the outcome is trustworthy and serves the user.
+- **Validate the committed candidate** against the contract, criteria, and mandatory checks using a fresh agent.
+- **Review quality and coherence** with a fresh agent after validation passes; select code and relevancy axes, using the acceptance evidence.
+- **Challenge the outcome** after review clears: verify that it is trustworthy and serves the user.
 
 ## Findings
 
@@ -18,7 +18,7 @@ A review or validation finding is routed by what it is about. A refusal the user
 
 ## Handoff
 
-- Commit whatever this zone wrote, then open the draft pull request when the reviewer returns no actionable finding.
+- Commit whatever this zone wrote, then open the draft pull request when no actionable finding remains.
 
 ```mermaid
 ---
@@ -31,8 +31,8 @@ flowchart TD
     Plan["$plan"]
     CommittedCandidate["$committed_candidate"]
     ValidationReports["$validation_reports"]
-    Validator(["@aidd-dev-validator"])
-    Reviewer(["@aidd-dev-reviewer"])
+    Validator(["Validation agent"])
+    Reviewer(["Review agent"])
     Review["/aidd-dev:05-review"]
   end
 

From 7834413153ca9161bafad49972f06db89e2b9a14 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:04:19 +0800
Subject: [PATCH 32/73] fix(framework): preserve optional agents during local
 reload

---
 aidd_docs/memory/deployment.md                |   2 +-
 .../2026_10_14_sub_agents/verification.md     |  10 +-
 docs/DELEGATION.md                            |   7 +-
 scripts/__tests__/dev-sync.test.js            | 302 ++++++------------
 scripts/__tests__/sync-codex-agents.test.js   |  46 ---
 scripts/dev-sync.sh                           | 108 +------
 scripts/sync-codex-agents.cjs                 |  46 ---
 scripts/sync-global-instructions.cjs          |  14 +-
 8 files changed, 133 insertions(+), 402 deletions(-)
 delete mode 100644 scripts/__tests__/sync-codex-agents.test.js
 delete mode 100644 scripts/sync-codex-agents.cjs

diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index 0df327b24..89b7d4c4e 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -58,7 +58,7 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 ## Local reload
 
-`make reload` syncs all plugins and agent-only global instructions to installed hosts; details in `scripts/dev-sync.sh`.
+`make reload` syncs all plugins and generic delegation guidance to installed hosts; details in `scripts/dev-sync.sh`.
 
 ## Monitoring
 
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 550aaa890..2b56fe37f 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -5,9 +5,17 @@
 The four agents are bundled with the CLI, outside plugins. Explicit installation selects a provider and IDE using the [CLI configuration](../../../../cli/src/contexts/tools/domain/formats/agent-models.json). Generic conversion applies no model defaults. Skills remain independent of installation and model selection.
 
 - **CLI:** 17 built-CLI cases pass, covering seven supported provider/IDE pairs, repeat installation, provider changes, removal, invalid selections, personal-file conflicts, cleanup, and a framework distribution without these agents.
-- **Ownership:** integration cases cover the project ledger, modified files, safe paths, and cleanup. Removing the ownership guard makes its named test fail; restored code passes. Cleanup preserves personal directory links; restoring recursive directory removal makes that test fail.
+- **Ownership:** integration cases cover the project ledger, modified files, safe paths, and cleanup. Removing the ownership guard makes its named test fail; restored code passes. Without a framework manifest, cleanup preserves personal directory links; restoring recursive directory removal makes that test fail. The pre-existing manifest-present branch remains outside this proof.
 - **Limits:** Native files are written directly into each host's agent directory. These checks establish headers and file behavior, not account access or effective runtime model selection.
 
+## Optional behavior-only agents, 2026-10-16
+
+- **Configuration:** the same JSON separates advisory `main` models from applied `subagent` settings and adds Mistral on OpenCode V2. Sources and native-format references are in [the agent guide](../../../../docs/DELEGATION.md).
+- **CLI:** 19 built-CLI cases pass, including eight provider/IDE pairs and switching to Mistral; 77 focused unit and command integration cases pass. Build: 694.7 KB / 695 KB.
+- **Reload:** 47 script cases pass. Regressions first reproduced personal-agent deletion and the wrong OpenCode Claude fallback; both now pass. Standalone agents remain unchanged.
+- **Gates:** 6,574 CLI tests pass, one skipped (`env -u CODEX_THREAD_ID pnpm test`); 494 script tests pass through the Git-safe wrapper. Lint, typecheck, type honesty, architecture, links, duplication, and knip pass. An initial run exposed the expected help snapshot change and two inherited-session fixture failures; the refreshed snapshot and isolated environment pass.
+- **Limits:** no authenticated inference establishes effective runtime model selection for this candidate.
+
 ## Earlier runtime evidence
 
 The runtime probes below describe earlier candidates. Their traces and hashes predate the CLI-installed model defaults and the latest simplified agent bodies.
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
index 69565a70e..0d4d9b2ee 100644
--- a/docs/DELEGATION.md
+++ b/docs/DELEGATION.md
@@ -5,7 +5,12 @@ Install agents in the current project with a provider and IDE:
 ```sh
 aidd agents install --provider openai --ide codex
 aidd agents install --provider anthropic --ide claude-code
+aidd agents install --provider mistral --ide opencode
 aidd agents remove --ide codex
 ```
 
-The CLI writes native agents using its [model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json). Plugins do not install these agents.
+The [CLI model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines `main` recommendations and applied `subagent` headers. Installing agents leaves the main model unchanged. Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
+
+Each agent is one self-contained native file. Plugins and `make reload` do not install these optional agents; workflows delegate by responsibility using available host agents.
+
+Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants). These recommendations are not a comparative benchmark or proof of account access.
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 71092c5b7..88709f9f9 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -7,15 +7,14 @@ const test = require("node:test");
 
 const repo = resolve(__dirname, "../..");
 const { render, sync } = require("../sync-global-instructions.cjs");
-const devAgents = ["checker.md", "executor.md"];
-const buildDevAgents = devAgents.map((name) => `printf '%s\\n' 'updated agent' > "$out/.opencode/agents/aidd-dev-${name}"`).join("\n");
 
-const instructionSource = "# AGENTS.md\n\n## Action\n- Keep scope.\n- Follow `docs/ARCHITECTURE.md`.\n\n## Agents\n| name | role |\n| --- | --- |\n| @executor (Codex), @aidd-dev-executor (OpenCode) | Implement scope. |\n\n## Memory Management\nProject docs live in aidd_docs/.\n<!-- aidd_project_memory:start -->\n@aidd_docs/memory/private.md\n<!-- aidd_project_memory:end -->\nLoad more memory.\n";
+const instructionSource = "# AGENTS.md\n\n## Action\n- Keep scope.\n- Follow `docs/ARCHITECTURE.md`.\n\n## Agents\nUse available agents when useful. The caller owns scope and acceptance.\n\n## Memory Management\nProject docs live in aidd_docs/.\n<!-- aidd_project_memory:start -->\n@aidd_docs/memory/private.md\n<!-- aidd_project_memory:end -->\nLoad more memory.\n";
 
-test("global instructions exclude project context and use each host's native agent names", () => {
-  for (const [host, name] of [["codex", "@aidd-dev-executor"], ["claude", "@aidd-dev:executor"], ["opencode", "@aidd-dev-executor"]]) {
+test("global instructions copy generic delegation guidance without project context", () => {
+  for (const host of ["codex", "claude", "opencode", "copilot", "cursor"]) {
     const content = render(instructionSource, host);
-    assert.ok(content.includes(`| ${name} | Implement scope. |`));
+    assert.match(content, /Use available agents when useful/);
+    assert.doesNotMatch(content, /@aidd/);
     assert.doesNotMatch(content, /Memory|memory|aidd_docs|ARCHITECTURE/);
     assert.doesNotMatch(content, /Keep scope|## Action|## Behavior|## Communication/);
   }
@@ -34,12 +33,12 @@ test("global sync preserves personal rules, updates its block, and is idempotent
     const first = readFileSync(destination, "utf8");
     sync(source, [["codex", destination]]);
     assert.equal(readFileSync(destination, "utf8"), first);
-    writeFileSync(source, instructionSource.replace("Implement scope.", "Implement updated scope."));
+    writeFileSync(source, instructionSource.replace("Use available agents when useful.", "Updated delegation guidance."));
     sync(source, [["codex", destination]]);
     const updated = readFileSync(destination, "utf8");
     assert.ok(updated.startsWith(personal));
-    assert.match(updated, /Implement updated scope/);
-    assert.doesNotMatch(updated, /Implement scope\./);
+    assert.match(updated, /Updated delegation guidance/);
+    assert.doesNotMatch(updated, /Use available agents when useful\./);
     assert.equal(updated.split("aidd_global_instructions:start").length, 2);
   } finally {
     rmSync(root, { recursive: true, force: true });
@@ -61,7 +60,7 @@ test("global sync replaces legacy duplicated instructions without changing perso
     assert.ok(migrated.endsWith(suffix));
     assert.doesNotMatch(migrated, /Legacy|Keep scope|## Communication|## Action/);
     assert.equal(migrated.match(/^## Behavior$/gm).length, 1);
-    assert.match(migrated, /@aidd-dev-executor \| Implement scope/);
+    assert.match(migrated, /Use available agents when useful/);
     sync(source, [["codex", destination]]);
     assert.equal(readFileSync(destination, "utf8"), migrated);
   } finally {
@@ -70,10 +69,10 @@ test("global sync replaces legacy duplicated instructions without changing perso
 });
 
 test("global agent extraction works without project memory and stops at the next section", () => {
-  const source = "## Agents\n| name | role |\n| @executor | Implement scope. |\n\n## Project rules\nNever copy me.\n";
-  assert.match(render(source, "claude"), /@aidd-dev:executor/);
-  assert.doesNotMatch(render(source, "claude"), /Project rules|Never copy/);
-  assert.match(render(source.split("\n## Project rules")[0], "codex"), /Implement scope/);
+  const source = "## Agents\nUse available agents when useful.\n\n## Project rules\nPrivate project rules.\n";
+  assert.match(render(source, "claude"), /Use available agents when useful/);
+  assert.doesNotMatch(render(source, "claude"), /Project rules|Private project/);
+  assert.match(render(source.split("\n## Project rules")[0], "codex"), /Use available agents when useful/);
 });
 
 test("first OpenCode sync retains effective Claude personal rules without its managed block", () => {
@@ -88,8 +87,8 @@ test("first OpenCode sync retains effective Claude personal rules without its ma
     sync(source, [["opencode", opencode]], claude);
     const installed = readFileSync(opencode, "utf8");
     assert.match(installed, /Claude personal rules/);
-    assert.match(installed, /@aidd-dev-executor/);
-    assert.doesNotMatch(installed, /@aidd-dev:executor/);
+    assert.match(installed, /Use available agents when useful/);
+    assert.doesNotMatch(installed, /@aidd/);
     writeFileSync(claude, "Changed fallback.\n");
     sync(source, [["opencode", opencode]], claude);
     assert.equal(readFileSync(opencode, "utf8"), installed);
@@ -130,8 +129,8 @@ test("Copilot and Cursor global instructions retain personal rules and native ru
     assert.match(readFileSync(copilot, "utf8"), /^Copilot personal rule\.\n/);
     const rule = readFileSync(cursor, "utf8");
     assert.match(rule, /^---\nalwaysApply: true\n---\n/);
-    for (const [file, name] of [[copilot, "@aidd-dev:executor"], [cursor, "@aidd-dev-executor"]]) {
-      assert.ok(readFileSync(file, "utf8").includes(`| ${name} |`));
+    for (const file of [copilot, cursor]) {
+      assert.match(readFileSync(file, "utf8"), /Use available agents when useful/);
       assert.doesNotMatch(readFileSync(file, "utf8"), /aidd_docs|Memory|ARCHITECTURE/);
     }
     writeFileSync(cursor, rule + "\nPersonal closing rule.\n");
@@ -152,17 +151,13 @@ function executable(path, body) {
 function fixture(home, plugins = ["aidd-dev"]) {
   const source = join(home, "framework");
   if (!existsSync(source)) {
-    for (const [plugin, skill, agents] of [["aidd-dev", "01-plan", devAgents], ["aidd-pm", "03-prd", []]]) {
+    for (const [plugin, skill] of [["aidd-dev", "01-plan"], ["aidd-pm", "03-prd"]]) {
       if (!plugins.includes(plugin)) continue;
       const pluginDir = join(source, "plugins", plugin);
       mkdirSync(join(pluginDir, ".claude-plugin"), { recursive: true });
       writeFileSync(join(pluginDir, ".claude-plugin/plugin.json"), "{}\n");
       mkdirSync(join(pluginDir, "skills", skill), { recursive: true });
       writeFileSync(join(pluginDir, "skills", skill, "SKILL.md"), "source skill\n");
-      for (const name of agents) {
-        mkdirSync(join(pluginDir, "agents"), { recursive: true });
-        writeFileSync(join(pluginDir, "agents", name), "source agent\n");
-      }
     }
     writeFileSync(join(source, "AGENTS.md"), instructionSource);
   }
@@ -191,9 +186,7 @@ function runSync(fakeBin, home, args = ["all"], overrides = {}) {
       BUILD: join(home, "build"),
       CODEX_CACHE: join(home, ".codex/plugins/cache"),
       CLAUDE_CACHE: join(home, ".claude/plugins/cache"),
-      CODEX_AGENTS: join(home, ".codex/agents"),
       OPENCODE_SKILLS: join(home, ".config/opencode/skills"),
-      OPENCODE_AGENTS: join(home, ".config/opencode/agents"),
       CODEX_INSTRUCTIONS: join(home, ".codex/AGENTS.md"),
       CLAUDE_INSTRUCTIONS: join(home, ".claude/CLAUDE.md"),
       OPENCODE_INSTRUCTIONS: join(home, ".config/opencode/AGENTS.md"),
@@ -220,19 +213,6 @@ test("reload fixtures run from their temporary home", () => {
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
-test("Claude reload rejects a missing native installation path without writing into cwd", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-claude-no-path-"));
-  try {
-    const fakeBin = join(root, "bin"), home = join(root, "home");
-    mkdirSync(fakeBin);
-    executable(join(fakeBin, "claude"), "exit 0");
-    const result = runSync(fakeBin, home, []);
-    assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /install path missing/);
-    assert.equal(existsSync(join(home, ".agents")), false);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
 test("managed OpenCode reload uses the fixed-purpose helper without a local build", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-managed-"));
   try {
@@ -246,7 +226,7 @@ test("managed OpenCode reload uses the fixed-purpose helper without a local buil
     assert.equal(result.status, 0, result.stderr);
     assert.match(result.stdout, /reload opencode\s+managed:ok/);
     assert.equal(existsSync(join(home, "build")), false);
-    assert.match(readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8"), /Implement scope/);
+    assert.match(readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8"), /Use available agents when useful/);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -266,7 +246,7 @@ for (const flag of ["OPENCODE_DISABLE_CLAUDE_CODE", "OPENCODE_DISABLE_CLAUDE_COD
       assert.equal(result.status, 0, result.stderr);
       const installed = readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8");
       assert.doesNotMatch(installed, /Excluded Claude/);
-      assert.match(installed, /Implement scope/);
+      assert.match(installed, /Use available agents when useful/);
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
@@ -282,8 +262,8 @@ test("reload delivers global instructions to all three hosts while preserving pe
     mkdirSync(home);
     const source = fixture(home, ["aidd-pm"]);
     writeFileSync(join(source, "AGENTS.md"), instructionSource);
-    const destinations = [[".codex/AGENTS.md", "@aidd-dev-executor"], [".claude/CLAUDE.md", "@aidd-dev:executor"], [".config/opencode/AGENTS.md", "@aidd-dev-executor"]];
-    for (const [path] of destinations) {
+    const destinations = [".codex/AGENTS.md", ".claude/CLAUDE.md", ".config/opencode/AGENTS.md"];
+    for (const path of destinations) {
       mkdirSync(dirname(join(home, path)), { recursive: true });
       writeFileSync(join(home, path), "Personal rules.\n");
     }
@@ -298,16 +278,17 @@ printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-pm-03-prd/SKILL.md"`);
     const first = runSync(fakeBin, home, []);
     assert.equal(first.status, 0, first.stderr);
     assert.match(first.stdout, /global instructions\s+ok/);
-    const contents = destinations.map(([path, name]) => {
+    const contents = destinations.map((path) => {
       const content = readFileSync(join(home, path), "utf8");
       assert.ok(content.startsWith("Personal rules.\n"));
-      assert.ok(content.includes(`| ${name} | Implement scope. |`));
+      assert.match(content, /Use available agents when useful/);
+      assert.doesNotMatch(content, /@aidd/);
       assert.doesNotMatch(content, /Memory|aidd_docs|ARCHITECTURE/);
       return content;
     });
     const second = runSync(fakeBin, home, []);
     assert.equal(second.status, 0, second.stderr);
-    destinations.forEach(([path], index) => assert.equal(readFileSync(join(home, path), "utf8"), contents[index]));
+    destinations.forEach((path, index) => assert.equal(readFileSync(join(home, path), "utf8"), contents[index]));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -350,8 +331,7 @@ mkdir -p "$skill/actions" "$skill/assets"
 printf '%s\n' '---' 'name: aidd-dev-01-plan' 'description: test' '---' > "$skill/SKILL.md"
 printf '%s\n' 'updated action' > "$skill/actions/04-plan.md"
 printf '%s\n' 'updated template' > "$skill/assets/plan-template.md"
-mkdir -p "$out/.opencode/agents"
-${buildDevAgents}`,
+`,
       );
 
       const result = runSync(fakeBin, home, []);
@@ -364,13 +344,12 @@ ${buildDevAgents}`,
       assert.equal(existsSync(join(home, ".config/opencode/skills/aidd-dev/removed")), false);
       assert.equal(readFileSync(unrelated, "utf8"), "keep\n");
       assert.match(result.stdout, /install opencode\s+skills:ok/);
-      for (const name of devAgents) {
-        assert.equal(readFileSync(join(agentDir, `aidd-dev-${name}`), "utf8"), "updated agent\n");
-      }
-      assert.equal(existsSync(join(agentDir, "aidd-dev-removed.md")), false);
+      assert.equal(readFileSync(join(agentDir, "aidd-dev-checker.md"), "utf8"), "old agent\n");
+      assert.equal(readFileSync(join(agentDir, "aidd-dev-removed.md"), "utf8"), "stale\n");
+      assert.equal(existsSync(join(agentDir, "aidd-dev-executor.md")), false);
       assert.equal(readFileSync(join(agentDir, "personal.md"), "utf8"), "keep\n");
       assert.equal(readFileSync(join(agentDir, "aidd-pm-review.md"), "utf8"), "keep\n");
-      assert.match(result.stdout, /agents:ok/);
+
     } finally {
       rmSync(root, { recursive: true, force: true });
     }
@@ -399,44 +378,7 @@ test("local OpenCode reload rejects missing framework skills before removing ins
   }
 });
 
-test("local OpenCode reload rejects a missing agent before changing installed content", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-agent-missing-"));
-  try {
-    const fakeBin = join(root, "bin");
-    const home = join(root, "home");
-    mkdirSync(fakeBin);
-    const skillDir = join(home, ".config/opencode/skills/aidd-dev-01-plan");
-    const agentDir = join(home, ".config/opencode/agents");
-    mkdirSync(skillDir, { recursive: true });
-    mkdirSync(agentDir, { recursive: true });
-    writeFileSync(join(skillDir, "SKILL.md"), "keep skill\n");
-    writeFileSync(join(agentDir, "aidd-dev-checker.md"), "keep agent\n");
-    executable(join(fakeBin, "opencode"), "exit 0");
-    const remainingAgents = devAgents.filter((name) => name !== "checker.md").map((name) =>
-      `printf '%s\\n' 'agent' > "$out/.opencode/agents/aidd-dev-${name}"`,
-    ).join("\n");
-    executable(join(fakeBin, "npx"), String.raw`out=""
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "--out" ]; then shift; out=$1; fi
-  shift
-done
-mkdir -p "$out/.opencode/skills/aidd-dev-01-plan"
-printf '%s\n' 'new skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
-mkdir -p "$out/.opencode/agents"
-${remainingAgents}`);
-
-    const result = runSync(fakeBin, home, []);
-    assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /no built OpenCode agent for aidd-dev-/);
-    assert.doesNotMatch(result.stdout, /skills:ok|agents:ok/);
-    assert.equal(readFileSync(join(skillDir, "SKILL.md"), "utf8"), "keep skill\n");
-    assert.equal(readFileSync(join(agentDir, "aidd-dev-checker.md"), "utf8"), "keep agent\n");
-  } finally {
-    rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("default OpenCode reload installs every plugin's skills and agents", () => {
+test("default OpenCode reload installs every plugin's skills without agents", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-all-"));
   try {
     const fakeBin = join(root, "bin");
@@ -445,28 +387,22 @@ test("default OpenCode reload installs every plugin's skills and agents", () =>
     mkdirSync(home);
     fixture(home, ["aidd-dev", "aidd-pm"]);
     const skills = ["aidd-dev-01-plan", "aidd-pm-03-prd"];
-    const agents = devAgents.map((name) => `aidd-dev-${name}`);
     const buildSkills = skills.map((name) => `mkdir -p "$out/.opencode/skills/${name}"\nprintf '%s\\n' 'skill' > "$out/.opencode/skills/${name}/SKILL.md"`).join("\n");
-    const buildAgents = agents.map((name) => `printf '%s\\n' 'agent' > "$out/.opencode/agents/${name}"`).join("\n");
     executable(join(fakeBin, "opencode"), "exit 0");
     executable(join(fakeBin, "npx"), `out=""
 while [ "$#" -gt 0 ]; do
   if [ "$1" = "--out" ]; then shift; out=$1; fi
   shift
 done
-mkdir -p "$out/.opencode/agents"
-${buildSkills}
-${buildAgents}`);
+${buildSkills}`);
 
     const result = runSync(fakeBin, home, []);
     assert.equal(result.status, 0, result.stderr);
     for (const skill of skills) {
       assert.equal(readFileSync(join(home, ".config/opencode/skills", `${skill}/SKILL.md`), "utf8"), "skill\n");
     }
-    for (const agent of agents) {
-      assert.equal(readFileSync(join(home, ".config/opencode/agents", agent), "utf8"), "agent\n");
-    }
-    assert.match(result.stdout, /skills:ok agents:ok/);
+    assert.equal(existsSync(join(home, ".config/opencode/agents")), false);
+    assert.match(result.stdout, /skills:ok/);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -492,9 +428,8 @@ while [ "$#" -gt 0 ]; do
   if [ "$1" = "--out" ]; then shift; out=$1; fi
   shift
 done
-mkdir -p "$out/.opencode/skills/aidd-dev-01-plan" "$out/.opencode/agents"
+mkdir -p "$out/.opencode/skills/aidd-dev-01-plan"
 printf '%s\n' 'skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
-${buildDevAgents}
 ${badOutput === "empty" ? 'mkdir -p "$out/.opencode/skills/aidd-dev-02-implement"; touch "$out/.opencode/skills/aidd-dev-02-implement/SKILL.md"' : ""}`);
       const result = runSync(fakeBin, home, []);
       assert.notEqual(result.status, 0);
@@ -546,58 +481,7 @@ for (const host of ["codex", "claude", "copilot"]) {
   });
 }
 
-test("Codex reload rejects missing built agents before replacing the previous cache", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-incomplete-"));
-  try {
-    const fakeBin = join(root, "bin"), home = join(root, "home");
-    mkdirSync(fakeBin);
-    const cached = join(home, ".codex/plugins/cache/aidd-framework/aidd-dev/2.6.0/codex-agents/checker.toml");
-    mkdirSync(dirname(cached), { recursive: true });
-    writeFileSync(cached, "old cached agent\n");
-    executable(join(fakeBin, "codex"), "exit 0");
-    executable(join(fakeBin, "npx"), "exit 0");
-    const result = runSync(fakeBin, home, []);
-    assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /no built Codex agent/);
-    assert.equal(readFileSync(cached, "utf8"), "old cached agent\n");
-    assert.doesNotMatch(result.stdout, /Done\./);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("Codex reload namespaces renamed roles and retires only cache-matched short names", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-migration-"));
-  try {
-    const fakeBin = join(root, "bin"), home = join(root, "home");
-    mkdirSync(fakeBin); mkdirSync(home);
-    const source = fixture(home);
-    rmSync(join(source, "plugins/aidd-dev/agents/checker.md"));
-    writeFileSync(join(source, "plugins/aidd-dev/agents/reviewer.md"), "new reviewer\n");
-    const cached = join(home, ".codex/plugins/cache/aidd-framework/aidd-dev/2.6.0/codex-agents/checker.toml");
-    const agents = join(home, ".codex/agents");
-    mkdirSync(dirname(cached), { recursive: true }); mkdirSync(agents, { recursive: true });
-    const legacy = 'name = "checker"\ndescription = "Legacy"\n';
-    writeFileSync(cached, legacy); writeFileSync(join(agents, "checker.toml"), legacy);
-    writeFileSync(join(agents, "reviewer.toml"), "personal reviewer\n");
-    executable(join(fakeBin, "codex"), "exit 0");
-    executable(join(fakeBin, "npx"), String.raw`out=""
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = "--out" ]; then shift; out=$1; fi
-  shift
-done
-mkdir -p "$out/plugins/aidd-dev/codex-agents"
-for role in reviewer executor; do
-  printf 'name = "%s"\ndescription = "New role"\n' "$role" > "$out/plugins/aidd-dev/codex-agents/$role.toml"
-done`);
-    const result = runSync(fakeBin, home, []);
-    assert.equal(result.status, 0, result.stderr);
-    assert.equal(existsSync(join(agents, "checker.toml")), false);
-    assert.equal(readFileSync(join(agents, "reviewer.toml"), "utf8"), "personal reviewer\n");
-    assert.match(readFileSync(join(agents, "aidd-dev-reviewer.toml"), "utf8"), /^name = "aidd-dev-reviewer"/);
-    assert.match(readFileSync(join(agents, "aidd-dev-executor.toml"), "utf8"), /^name = "aidd-dev-executor"/);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-function nativeBuildStub(omitAgent = false) {
+function nativeBuildStub(omitSkill = false) {
   return String.raw`out=""; tool=""
 while [ "$#" -gt 0 ]; do
   case "$1" in --out) shift; out=$1 ;; --to) shift; tool=$1 ;; esac
@@ -610,10 +494,8 @@ for source in "$FW/plugins/"*/; do
   [ "$tool" != copilot ] || manifest=".plugin"
   mkdir -p "$target/$manifest" "$target/skills"
   printf '{"name":"%s"}\n' "$plugin" > "$target/$manifest/plugin.json"
-  cp -R "$FW/plugins/$plugin/skills/." "$target/skills/"
-done
-mkdir -p "$out/plugins/aidd-dev/agents"
-${omitAgent ? "" : 'for role in checker executor; do name="$role"; [ "$tool" != cursor ] || name="aidd-dev-$role"; printf \'%s\\n\' \'---\' "name: $name" \'---\' \'Native role\' > "$out/plugins/aidd-dev/agents/$role.md"; done'}`;
+  ${omitSkill ? ":" : 'cp -R "$FW/plugins/$plugin/skills/." "$target/skills/"'}
+done`;
 }
 
 for (const binary of ["cursor-agent", "agent", "cursor"]) {
@@ -638,13 +520,13 @@ for (const binary of ["cursor-agent", "agent", "cursor"]) {
       for (const [plugin, skill] of [["aidd-dev", "01-plan"], ["aidd-pm", "03-prd"]]) {
         assert.equal(readFileSync(join(home, `.cursor/plugins/local/${plugin}/skills/${skill}/SKILL.md`), "utf8"), "source skill\n");
       }
-      assert.match(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8"), /name: aidd-dev-executor/);
-      assert.match(readFileSync(join(home, ".cursor/rules/aidd-agents.mdc"), "utf8"), /\| @aidd-dev-executor \|/);
+      assert.equal(existsSync(join(home, ".cursor/plugins/local/aidd-dev/agents")), false);
+      assert.match(readFileSync(join(home, ".cursor/rules/aidd-agents.mdc"), "utf8"), /Use available agents when useful/);
       assert.equal(existsSync(stale), false);
       for (const file of personal) assert.equal(readFileSync(join(home, file), "utf8"), "personal bytes\n");
-      const first = readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8");
+      const first = readFileSync(join(home, ".cursor/plugins/local/aidd-dev/skills/01-plan/SKILL.md"), "utf8");
       assert.equal(runSync(fakeBin, home, []).status, 0);
-      assert.equal(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8"), first);
+      assert.equal(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/skills/01-plan/SKILL.md"), "utf8"), first);
     } finally { rmSync(root, { recursive: true, force: true }); }
   });
 }
@@ -661,7 +543,7 @@ test("Cursor reload rejects incomplete native output before changing installed p
     executable(join(fakeBin, "npx"), nativeBuildStub(true));
     const result = runSync(fakeBin, home, []);
     assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /no built cursor agent/);
+    assert.match(result.stderr, /no built cursor skill/);
     assert.equal(readFileSync(installed, "utf8"), "old role\n");
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
@@ -734,7 +616,7 @@ test("Copilot reload builds all native plugins, migrates its own source, and pre
       assert.match(readFileSync(join(home, "copilot-calls"), "utf8"), new RegExp(`plugin install ${plugin}@aidd-framework`));
       assert.equal(JSON.parse(readFileSync(join(home, `build/copilot/plugins/${plugin}/.plugin/plugin.json`), "utf8")).name, plugin);
     }
-    assert.match(readFileSync(join(home, ".copilot/copilot-instructions.md"), "utf8"), /@aidd-dev:executor/);
+    assert.match(readFileSync(join(home, ".copilot/copilot-instructions.md"), "utf8"), /Use available agents when useful/);
     assert.equal(runSync(fakeBin, home, []).status, 0);
     assert.match(readFileSync(join(home, "copilot-calls"), "utf8"), /marketplace update aidd-framework/);
     for (const file of personal) assert.equal(readFileSync(join(home, file), "utf8"), "personal bytes\n");
@@ -766,7 +648,7 @@ test("Copilot rejects incomplete native output before registering or installing"
     executable(join(fakeBin, "npx"), nativeBuildStub(true));
     const result = runSync(fakeBin, home, []);
     assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /no built copilot agent/);
+    assert.match(result.stderr, /no built copilot skill/);
     assert.equal(existsSync(join(home, "copilot-calls")), false);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
@@ -837,16 +719,13 @@ for (const plugin of fs.readdirSync(path.join(source, "plugins"))) {
   fs.mkdirSync(path.join(target, ".cursor-plugin"), { recursive: true });
   fs.writeFileSync(path.join(target, ".cursor-plugin/plugin.json"), JSON.stringify({ name: plugin }));
   fs.cpSync(path.join(source, "plugins", plugin, "skills"), path.join(target, "skills"), { recursive: true });
-  fs.mkdirSync(path.join(target, "agents"));
-  for (const file of fs.readdirSync(path.join(source, "plugins", plugin, "agents"))) {
-    fs.writeFileSync(path.join(target, "agents", file), "---\nname: " + plugin + "-" + file.slice(0, -3) + "\n---\nLocal translation\n");
-  }
+
 }`);
     executable(join(fakeBin, "cursor-agent"), "echo 'Start the Cursor Agent'");
     executable(join(fakeBin, "npx"), "exit 19");
     const result = runSync(fakeBin, home, []);
     assert.equal(result.status, 0, result.stderr);
-    assert.match(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/agents/executor.md"), "utf8"), /name: aidd-dev-executor[\s\S]*Local translation/);
+    assert.equal(readFileSync(join(home, ".cursor/plugins/local/aidd-dev/skills/01-plan/SKILL.md"), "utf8"), "source skill\n");
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
@@ -859,14 +738,14 @@ test("Copilot instructions follow its native home with task overrides taking pre
     executable(join(fakeBin, "npx"), nativeBuildStub());
     const result = runSync(fakeBin, home, [], { COPILOT_HOME: nativeHome, COPILOT_INSTRUCTIONS: "" });
     assert.equal(result.status, 0, result.stderr);
-    assert.match(readFileSync(join(nativeHome, "copilot-instructions.md"), "utf8"), /@aidd-dev:executor/);
+    assert.match(readFileSync(join(nativeHome, "copilot-instructions.md"), "utf8"), /Use available agents when useful/);
     assert.equal(existsSync(join(home, ".copilot/copilot-instructions.md")), false);
     assert.equal(runSync(fakeBin, home, [], { COPILOT_HOME: nativeHome }).status, 0);
-    assert.match(readFileSync(join(home, ".copilot/copilot-instructions.md"), "utf8"), /@aidd-dev:executor/);
+    assert.match(readFileSync(join(home, ".copilot/copilot-instructions.md"), "utf8"), /Use available agents when useful/);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
-test("OpenCode skills and agents follow its native home with task overrides taking precedence", () => {
+test("OpenCode skills follow its native home with task overrides taking precedence", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-opencode-home-"));
   try {
     const fakeBin = join(root, "bin"), home = join(root, "home"), config = join(home, "native-config");
@@ -877,43 +756,19 @@ while [ "$#" -gt 0 ]; do
   if [ "$1" = --out ]; then shift; out=$1; fi
   shift
 done
-mkdir -p "$out/.opencode/skills/aidd-dev-01-plan" "$out/.opencode/agents"
+mkdir -p "$out/.opencode/skills/aidd-dev-01-plan"
 printf '%s\n' 'native skill' > "$out/.opencode/skills/aidd-dev-01-plan/SKILL.md"
-${buildDevAgents}`);
-    const result = runSync(fakeBin, home, [], { XDG_CONFIG_HOME: config, OPENCODE_SKILLS: "", OPENCODE_AGENTS: "", OPENCODE_INSTRUCTIONS: "" });
+`);
+    const result = runSync(fakeBin, home, [], { XDG_CONFIG_HOME: config, OPENCODE_SKILLS: "", OPENCODE_INSTRUCTIONS: "" });
     assert.equal(result.status, 0, result.stderr);
     assert.equal(readFileSync(join(config, "opencode/skills/aidd-dev-01-plan/SKILL.md"), "utf8"), "native skill\n");
-    assert.equal(readFileSync(join(config, "opencode/agents/aidd-dev-executor.md"), "utf8"), "updated agent\n");
+    assert.equal(existsSync(join(config, "opencode/agents")), false);
     assert.equal(existsSync(join(home, ".config/opencode/skills")), false);
     assert.equal(runSync(fakeBin, home, [], { XDG_CONFIG_HOME: config }).status, 0);
     assert.equal(readFileSync(join(home, ".config/opencode/skills/aidd-dev-01-plan/SKILL.md"), "utf8"), "native skill\n");
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
-test("Codex agents and legacy cache migration follow its native home", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-home-"));
-  try {
-    const fakeBin = join(root, "bin"), home = join(root, "home"), nativeHome = join(home, "native-codex");
-    mkdirSync(fakeBin);
-    const cached = join(nativeHome, "plugins/cache/aidd-framework/aidd-dev/2.6.0/codex-agents/checker.toml");
-    const oldAgent = join(nativeHome, "agents/checker.toml"), legacy = 'name = "checker"\ndescription = "Legacy"\n';
-    for (const file of [cached, oldAgent]) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, legacy); }
-    executable(join(fakeBin, "codex"), "exit 0");
-    executable(join(fakeBin, "npx"), String.raw`out=""
-while [ "$#" -gt 0 ]; do
-  if [ "$1" = --out ]; then shift; out=$1; fi
-  shift
-done
-mkdir -p "$out/plugins/aidd-dev/codex-agents"
-for role in checker executor; do printf 'name = "%s"\ndescription = "Native"\n' "$role" > "$out/plugins/aidd-dev/codex-agents/$role.toml"; done`);
-    const result = runSync(fakeBin, home, [], { CODEX_HOME: nativeHome, CODEX_CACHE: "", CODEX_AGENTS: "", CODEX_INSTRUCTIONS: "" });
-    assert.equal(result.status, 0, result.stderr);
-    assert.match(readFileSync(join(nativeHome, "agents/aidd-dev-executor.toml"), "utf8"), /^name = "aidd-dev-executor"/);
-    assert.equal(existsSync(oldAgent), false);
-    assert.equal(existsSync(join(home, ".codex/agents")), false);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
 for (const customPluginRoot of [false, true]) {
   test(`Claude cache follows its native ${customPluginRoot ? "plugin root" : "config home"}`, () => {
     const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-claude-home-"));
@@ -925,13 +780,54 @@ for (const customPluginRoot of [false, true]) {
   cache="$CLAUDE_CONFIG_DIR/plugins"
   [ -z "$CLAUDE_CODE_PLUGIN_CACHE_DIR" ] || cache="$CLAUDE_CODE_PLUGIN_CACHE_DIR"
   cache="$cache/cache/aidd-framework/aidd-dev/2.6.0"
-  mkdir -p "$cache/agents"
+  mkdir -p "$cache"
+  printf '%s\n' 'native plugin' > "$cache/plugin-installed"
 fi`);
       const result = runSync(fakeBin, home, [], { CLAUDE_CONFIG_DIR: config, CLAUDE_CODE_PLUGIN_CACHE_DIR: customPluginRoot ? plugins : "", CLAUDE_CACHE: "", CLAUDE_INSTRUCTIONS: "" });
       assert.equal(result.status, 0, result.stderr);
-      assert.equal(readFileSync(join(plugins, "cache/aidd-framework/aidd-dev/2.6.0/agents/executor.md"), "utf8"), "source agent\n");
-      assert.match(readFileSync(join(config, "CLAUDE.md"), "utf8"), /@aidd-dev:executor/);
+      assert.equal(readFileSync(join(plugins, "cache/aidd-framework/aidd-dev/2.6.0/plugin-installed"), "utf8"), "native plugin\n");
+      assert.match(readFileSync(join(config, "CLAUDE.md"), "utf8"), /Use available agents when useful/);
       assert.equal(existsSync(join(home, ".claude/plugins")), false);
     } finally { rmSync(root, { recursive: true, force: true }); }
   });
 }
+
+for (const override of ["CLAUDE_CONFIG_DIR", "CLAUDE_INSTRUCTIONS"]) {
+  test(`OpenCode preserves its actual Claude fallback despite ${override}`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-fallback-override-"));
+    try {
+      const fakeBin = join(root, "bin"), home = join(root, "home");
+      mkdirSync(fakeBin);
+      mkdirSync(join(home, ".claude"), { recursive: true });
+      writeFileSync(join(home, ".claude/CLAUDE.md"), "Effective OpenCode personal instructions.\n");
+      const custom = join(home, "custom-claude");
+      mkdirSync(custom);
+      writeFileSync(join(custom, "CLAUDE.md"), "Other Claude instructions.\n");
+      executable(join(fakeBin, "aidd-opencode-reload"), "exit 0");
+      const result = runSync(fakeBin, home, [], override === "CLAUDE_CONFIG_DIR"
+        ? { CLAUDE_CONFIG_DIR: custom, CLAUDE_INSTRUCTIONS: "" }
+        : { CLAUDE_INSTRUCTIONS: join(custom, "CLAUDE.md") });
+      assert.equal(result.status, 0, result.stderr);
+      const installed = readFileSync(join(home, ".config/opencode/AGENTS.md"), "utf8");
+      assert.match(installed, /Effective OpenCode personal instructions/);
+      assert.doesNotMatch(installed, /Other Claude instructions/);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+}
+
+test("Codex reload leaves opted-in and personal agents unchanged", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-personal-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    const agents = join(home, ".codex/agents");
+    mkdirSync(agents, { recursive: true });
+    const existing = ["aidd-dev-executor.toml", "aidd-dev-personal.toml", "executor.toml"];
+    for (const file of existing) writeFileSync(join(agents, file), `Personal ${file}\n`);
+    executable(join(fakeBin, "codex"), "exit 0");
+    executable(join(fakeBin, "npx"), "exit 0");
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    for (const file of existing) assert.equal(readFileSync(join(agents, file), "utf8"), `Personal ${file}\n`);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
diff --git a/scripts/__tests__/sync-codex-agents.test.js b/scripts/__tests__/sync-codex-agents.test.js
deleted file mode 100644
index 325d67c8a..000000000
--- a/scripts/__tests__/sync-codex-agents.test.js
+++ /dev/null
@@ -1,46 +0,0 @@
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { sync } = require('../sync-codex-agents.cjs');
-function fixture(t) {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-agent-sync-'));
-  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
-  const dirs = ['built', 'installed', 'snapshot/2.6.0/codex-agents'].map(name => path.join(root, name));
-  dirs.forEach(dir => fs.mkdirSync(dir, { recursive: true }));
-  const [built, installed, old] = dirs;
-  const put = (dir, name, text) => fs.writeFileSync(path.join(dir, name), text);
-  const run = () => sync('aidd-dev', built, installed, path.join(root, 'snapshot'));
-  return { built, installed, old, put, run };
-}
-const agent = name => `name = "${name}"\ndescription = "Task"\n`;
-test('namespace roles and preserve personal and modified short agents', t => {
-  const f = fixture(t);
-  f.put(f.built, 'reviewer.toml', agent('reviewer'));
-  f.put(f.old, 'checker.toml', agent('checker'));
-  f.put(f.old, 'executor.toml', agent('executor'));
-  f.put(f.installed, 'checker.toml', agent('checker'));
-  f.put(f.installed, 'executor.toml', agent('executor') + '# personal modification\n');
-  f.put(f.installed, 'reviewer.toml', '# personal reviewer\n');
-  f.put(f.installed, 'aidd-dev-checker.toml', agent('aidd-dev-checker'));
-  f.put(f.installed, 'other-checker.toml', agent('other-checker'));
-  f.run();
-  assert.deepEqual(fs.readdirSync(f.installed).sort(), ['aidd-dev-reviewer.toml', 'executor.toml', 'other-checker.toml', 'reviewer.toml']);
-  assert.equal(fs.readFileSync(path.join(f.installed, 'reviewer.toml'), 'utf8'), '# personal reviewer\n');
-  assert.equal(fs.readFileSync(path.join(f.installed, 'aidd-dev-reviewer.toml'), 'utf8'), agent('aidd-dev-reviewer'));
-  const once = fs.readdirSync(f.installed).map(name => [name, fs.readFileSync(path.join(f.installed, name), 'utf8')]);
-  f.run();
-  assert.deepEqual(fs.readdirSync(f.installed).map(name => [name, fs.readFileSync(path.join(f.installed, name), 'utf8')]), once);
-});
-test('malformed build leaves every installed agent unchanged', t => {
-  const f = fixture(t);
-  f.put(f.built, 'good.toml', agent('good'));
-  f.put(f.built, 'invalid.toml', 'description = "Missing name"\n');
-  f.put(f.old, 'checker.toml', agent('checker'));
-  f.put(f.installed, 'checker.toml', agent('checker'));
-  f.put(f.installed, 'aidd-dev-stale.toml', agent('aidd-dev-stale'));
-  assert.throws(f.run, /Invalid generated agent/);
-  assert.deepEqual(fs.readdirSync(f.installed).sort(), ['aidd-dev-stale.toml', 'checker.toml']);
-  assert.equal(fs.readFileSync(path.join(f.installed, 'checker.toml'), 'utf8'), agent('checker'));
-});
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 12468e5da..d0862da8e 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -1,28 +1,21 @@
 #!/usr/bin/env bash
 # (Re)install every plugin into Claude, Codex, OpenCode, Copilot and Cursor from THIS checkout.
 # Claude reads the raw repo, already native; Codex installs from a tree
-# the aidd CLI builds (agents -> TOML), so what runs locally matches what ships.
+# the aidd CLI builds, so what runs locally matches what ships.
 #
 # NOT live: the install copies built files, so an edit needs a re-run. Idempotent; a tool
 # whose CLI is absent is skipped, and the first run needs network. A managed OpenCode host
 # exposes `aidd-opencode-reload` instead, and that helper decides which checkout may load.
 #
-# Codex caveat: the .codex-plugin manifest does not declare codex-agents/*.toml, and Codex
-# loads agents only from ~/.codex/agents/, so install namespaced TOML there. Retire old
-# short names only when identical to the previous plugin cache; preserve personal agents.
+# Optional agents are installed separately with `aidd agents install`; reload leaves them alone.
 # Global rules: sync only the Agents section in the managed block, preserving personal
 # rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
 # Paths honor native home/cache overrides; explicit task paths take precedence.
 # Sources checked 2026-10-14:
 # https://developers.openai.com/codex/guides/agents-md
 # https://code.claude.com/docs/en/memory
-# https://opencode.ai/docs/rules/
-# OpenCode V2 discovery: global agents are filename-named subagents; inspect with
-# `opencode debug agents`. File presence alone does not prove invocation or permissions.
-# https://opencode.ai/v2/docs/agents (read 2026-10-14)
-# https://github.com/anomalyco/opencode/blob/v2.0.28/packages/core/src/config/plugin/agent.ts
-# V2.0.28 probe cwd must match PWD because run prefers PWD (read 2026-10-14):
-# https://github.com/anomalyco/opencode/blob/v2.0.28/packages/cli/src/run/run.ts
+# OpenCode fallback and disable flags checked 2026-10-16:
+# https://opencode.ai/docs/rules/#claude-code-compatibility
 # Cursor local plugins: real directories only; local imports must be allowed (read 2026-10-15).
 # https://cursor.com/docs/plugins#test-plugins-locally
 # Copilot native list/install verified with 1.0.5 and 1.0.98 (read 2026-10-15).
@@ -43,9 +36,7 @@ AIDD_CLI_VERSION="${AIDD_CLI_VERSION:-latest}"  # published fallback for sources
 BUILD="${BUILD:-$HOME/.cache/aidd-framework-dev}"  # per-tool native trees the marketplaces point at
 CODEX_CACHE="${CODEX_CACHE:-${CODEX_HOME:-$HOME/.codex}/plugins/cache}"
 CLAUDE_CACHE="${CLAUDE_CACHE:-${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/cache}"
-CODEX_AGENTS="${CODEX_AGENTS:-${CODEX_HOME:-$HOME/.codex}/agents}"
 OPENCODE_SKILLS="${OPENCODE_SKILLS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills}"
-OPENCODE_AGENTS="${OPENCODE_AGENTS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/agents}"
 CURSOR_PLUGINS="${CURSOR_PLUGINS:-$HOME/.cursor/plugins/local}"
 CODEX_INSTRUCTIONS="${CODEX_INSTRUCTIONS:-${CODEX_HOME:-$HOME/.codex}/AGENTS.md}"
 CLAUDE_INSTRUCTIONS="${CLAUDE_INSTRUCTIONS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md}"
@@ -79,9 +70,9 @@ build_tool() {
   fi
 }
 
-validate_opencode_content() {
-  # Check every expected nonempty skill and agent before replacing selected namespaces.
-  local name agent skill skill_name
+validate_opencode_skills() {
+  # Check every expected nonempty skill before replacing plugin namespaces.
+  local name skill skill_name
   for name in "$@"; do
     for skill in "$FW/plugins/$name/skills/"*/SKILL.md; do
       skill_name="$(basename "$(dirname "$skill")")"
@@ -91,29 +82,11 @@ validate_opencode_content() {
         return 1
       fi
     done
-    for agent in "$FW/plugins/$name/agents/"*.md; do
-      if [ ! -s "$BUILD/opencode/.opencode/agents/$name-$(basename "$agent")" ]; then
-        echo "no built OpenCode agent for $name-$(basename "$agent" .md)" >&2
-        return 1
-      fi
-    done
-  done
-}
-
-validate_codex_agents() {
-  local name agent
-  for name in "$@"; do
-    for agent in "$FW/plugins/$name/agents/"*.md; do
-      if [ ! -s "$BUILD/codex/plugins/$name/codex-agents/$(basename "$agent" .md).toml" ]; then
-        echo "no built Codex agent for $name-$(basename "$agent" .md)" >&2
-        return 1
-      fi
-    done
   done
 }
 
 validate_native_plugins() {
-  local tool="$1" manifest="$2" name skill agent
+  local tool="$1" manifest="$2" name skill
   for name in "${targets[@]}"; do
     if [ ! -s "$BUILD/$tool/plugins/$name/$manifest" ]; then
       echo "no built $tool manifest for $name" >&2; return 1
@@ -123,11 +96,6 @@ validate_native_plugins() {
         echo "no built $tool skill for $name-$(basename "$(dirname "$skill")")" >&2; return 1
       fi
     done
-    for agent in "$FW/plugins/$name/agents/"*.md; do
-      if [ ! -s "$BUILD/$tool/plugins/$name/agents/$(basename "$agent")" ]; then
-        echo "no built $tool agent for $name-$(basename "$agent" .md)" >&2; return 1
-      fi
-    done
   done
 }
 
@@ -152,26 +120,13 @@ sync_opencode_skills() {
   done
 }
 
-sync_opencode_agents() {
-  local name agent
-  mkdir -p "$OPENCODE_AGENTS"
-  for name in "$@"; do
-    # Only the selected plugin namespace is managed; personal and other plugins' agents stay.
-    for agent in "$OPENCODE_AGENTS/$name-"*.md; do rm -f -- "$agent"; done
-    for agent in "$BUILD/opencode/.opencode/agents/$name-"*.md; do
-      cp -f "$agent" "$OPENCODE_AGENTS/"
-    done
-  done
-}
-
 register_marketplace() {
   case "$1" in
-    # Codex needs the built tree (the raw repo is Claude-syntax; Codex wants TOML/.codex-plugin).
+    # Codex needs the native .codex-plugin tree.
     codex)
       codex  plugin marketplace remove "$MKT" >/dev/null 2>&1 || true
       codex  plugin marketplace add "$BUILD/codex"  >/dev/null 2>&1 ;;
-    # No build for Claude: the CLI's claude build emits an invalid agents manifest, and the
-    # raw repo is already native. Scope every op to user - a bare `marketplace remove` strips
+    # Claude installs the native repository. Scope every op to user: bare `marketplace remove` strips
     # the declaration from EVERY scope, wiping the repo's own project-scoped config.
     claude)
       claude plugin marketplace remove "$MKT" --scope user >/dev/null 2>&1 || true
@@ -211,19 +166,10 @@ sync_one() {
   printf '%-22s' "$name"
 
   if [ "$HAVE_CODEX" = 1 ]; then
-    local previous cached version
-    previous="$(mktemp -d "$BUILD/codex-previous-$name.XXXXXX")"
-    for cached in "$CODEX_CACHE/$MKT/$name/"*/codex-agents/; do
-      version="$(basename "$(dirname "$cached")")"
-      mkdir -p "$previous/$version"
-      cp -R "$cached" "$previous/$version/codex-agents"
-    done
     codex plugin remove "$name" >/dev/null 2>&1 || true
     rm -rf "$CODEX_CACHE/$MKT/$name"
     if codex plugin add "$name@$MKT" >/dev/null 2>&1; then
       printf ' codex:ok'
-      node "$SCRIPT_DIR/sync-codex-agents.cjs" "$name" "$BUILD/codex/plugins/$name/codex-agents" "$CODEX_AGENTS" "$previous"
-      rm -rf -- "$previous"
     else
       printf ' codex:FAIL'
       echo "Codex plugin install failed for $name; rerun codex plugin add $name@$MKT for details." >&2
@@ -234,27 +180,6 @@ sync_one() {
     rm -rf "$CLAUDE_CACHE/$MKT/$name"
     if claude plugin install "$name@$MKT" --scope user >/dev/null 2>&1; then
       printf ' claude:ok'
-      # Claude loads agents ONLY from the installed installPath, and `plugin install` copies
-      # them there implicitly - skipping the copy still prints ok. Force-sync them and report
-      # the count, so a miss is never silent.
-      if [ -d "$FW/plugins/$name/agents" ]; then
-        local dest src n=0 fixed=0
-        local -a install_paths
-        install_paths=("$CLAUDE_CACHE/$MKT/$name"/*/)
-        dest="${install_paths[0]:-}"
-        if [ -n "$dest" ]; then
-          mkdir -p "${dest}agents"
-          for src in "$FW/plugins/$name/agents/"*.md; do
-            n=$((n + 1))
-            cmp -s "$src" "${dest}agents/$(basename "$src")" 2>/dev/null || { cp -f "$src" "${dest}agents/"; fixed=$((fixed + 1)); }
-          done
-          [ "$fixed" -gt 0 ] && printf '(+%d agents, repaired %d)' "$n" "$fixed" || printf '(+%d agents)' "$n"
-        else
-          printf '(agents:NO-INSTALLPATH)'
-          echo "Claude plugin install path missing for $name; rerun claude plugin install $name@$MKT --scope user for details." >&2
-          return 1
-        fi
-      fi
     else
       printf ' claude:FAIL'
       echo "Claude plugin install failed for $name; rerun claude plugin install $name@$MKT --scope user for details." >&2
@@ -278,12 +203,11 @@ fi
 targets=()
 for d in "$FW"/plugins/*/; do targets+=("$(basename "$d")"); done
 
-# Codex needs a native build (md -> toml); register against it. Claude installs from the raw
+# Codex needs a native plugin build; register against it. Claude installs from the raw
 # repo (already native), so it only needs the marketplace registered - no build.
 if [ "$HAVE_CODEX" = 1 ]; then
   printf '%-22s' "build codex"
   build_tool codex || { echo "FAIL"; echo "codex build failed; rerun the translate command in scripts/dev-sync.sh without output redirection for details." >&2; exit 1; }
-  validate_codex_agents "${targets[@]}" || { echo "FAIL"; exit 1; }
   register_marketplace codex || { echo "FAIL"; echo "Codex marketplace registration failed for $BUILD/codex." >&2; exit 1; }
   echo "ok"
 fi
@@ -312,10 +236,9 @@ for t in "${targets[@]}"; do sync_one "$t"; done
 
 if [ "$HAVE_OPENCODE" = 1 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
   printf '%-22s' "install opencode"
-  validate_opencode_content "${targets[@]}"
+  validate_opencode_skills "${targets[@]}"
   sync_opencode_skills "${targets[@]}"
-  sync_opencode_agents "${targets[@]}"
-  echo "skills:ok agents:ok"
+  echo "skills:ok"
 fi
 if [ "$HAVE_MANAGED_OPENCODE" = 1 ]; then
   printf '%-22s' "reload opencode"
@@ -340,10 +263,11 @@ fi
 [ "$HAVE_COPILOT" = 0 ] || instructions+=(copilot "$COPILOT_INSTRUCTIONS")
 [ "$HAVE_CURSOR" = 0 ] || instructions+=(cursor "$CURSOR_INSTRUCTIONS")
 printf '%-22s' "global instructions"
-instruction_fallback="$CLAUDE_INSTRUCTIONS"
+# OpenCode uses this fixed Claude fallback, independent of Claude config overrides.
+instruction_fallback="$HOME/.claude/CLAUDE.md"
 case "${OPENCODE_DISABLE_CLAUDE_CODE:-}" in 1|true) instruction_fallback="" ;; esac
 case "${OPENCODE_DISABLE_CLAUDE_CODE_PROMPT:-}" in 1|true) instruction_fallback="" ;; esac
 node "$SCRIPT_DIR/sync-global-instructions.cjs" "$FW/AGENTS.md" "$instruction_fallback" "${instructions[@]}"
-echo "ok (agents only)"
+echo "ok (delegation guidance only)"
 
 echo "Done. Restart hosts or reload their configuration for refreshed plugins and instructions."
diff --git a/scripts/sync-codex-agents.cjs b/scripts/sync-codex-agents.cjs
deleted file mode 100644
index 4a0c89e50..000000000
--- a/scripts/sync-codex-agents.cjs
+++ /dev/null
@@ -1,46 +0,0 @@
-#!/usr/bin/env node
-const fs = require('node:fs');
-const path = require('node:path');
-
-function sync(pluginName, builtAgentsDir, installedDir, previousSnapshotDir) {
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(pluginName)) throw new Error('Invalid plugin name');
-  const built = fs.existsSync(builtAgentsDir) ? fs.readdirSync(builtAgentsDir, { withFileTypes: true }) : [];
-  // Read the complete build before retiring any installed agents.
-  const desired = new Map(built.filter(entry => entry.isFile() && entry.name.endsWith('.toml')).map(entry => {
-    const source = fs.readFileSync(path.join(builtAgentsDir, entry.name), 'utf8');
-    if (!/^[a-z0-9][a-z0-9-]*\.toml$/.test(entry.name) || !/^name = "[^"\r\n]+"\r?\n/.test(source)) throw new Error(`Invalid generated agent: ${entry.name}`);
-    const name = `${pluginName}-${entry.name.slice(0, -5)}`;
-    return [`${name}.toml`, source.replace(/^name = "[^"\r\n]+"/, `name = "${name}"`)];
-  }));
-  const previous = new Map();
-  function readSnapshot(dir) {
-    if (!fs.existsSync(dir)) return;
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      const file = path.join(dir, entry.name);
-      if (entry.isDirectory()) readSnapshot(file);
-      else if (entry.isFile() && path.basename(dir) === 'codex-agents' && entry.name.endsWith('.toml')) {
-        const copies = previous.get(entry.name) || [];
-        copies.push(fs.readFileSync(file));
-        previous.set(entry.name, copies);
-      }
-    }
-  }
-  readSnapshot(previousSnapshotDir);
-  fs.mkdirSync(installedDir, { recursive: true });
-  for (const name of fs.readdirSync(installedDir)) {
-    const file = path.join(installedDir, name);
-    if (!name.endsWith('.toml') || !fs.lstatSync(file).isFile()) continue;
-    if (name.startsWith(`${pluginName}-`)) {
-      if (!desired.has(name)) fs.unlinkSync(file);
-    } else if (previous.has(name) && previous.get(name).some(copy => copy.equals(fs.readFileSync(file)))) {
-      fs.unlinkSync(file);
-    }
-  }
-  for (const [name, contents] of desired) fs.writeFileSync(path.join(installedDir, name), contents);
-}
-
-module.exports = { sync };
-if (require.main === module) {
-  if (process.argv.length !== 6) throw new Error('Expected plugin, build, installed, snapshot paths');
-  sync(...process.argv.slice(2));
-}
diff --git a/scripts/sync-global-instructions.cjs b/scripts/sync-global-instructions.cjs
index 75c50fbab..bf78a14d1 100644
--- a/scripts/sync-global-instructions.cjs
+++ b/scripts/sync-global-instructions.cjs
@@ -8,18 +8,8 @@ function render(source, host) {
   const beginning = source.search(/^## Agents[ \t]*\r?$/m);
   if (beginning < 0) throw new Error("AGENTS.md has no Agents section; refusing global sync");
   const boundary = source.indexOf("\n## ", beginning + 1);
-  const names = {
-    codex: (role) => `@aidd-dev-${role}`,
-    claude: (role) => `@aidd-dev:${role}`,
-    opencode: (role) => `@aidd-dev-${role}`,
-    copilot: (role) => `@aidd-dev:${role}`,
-    cursor: (role) => `@aidd-dev-${role}`,
-  };
-  if (!names[host]) throw new Error(`Unknown instruction host: ${host}`);
-  return source.slice(beginning, boundary < 0 ? undefined : boundary).trim().replace(
-    /^\| @(?:aidd-dev[:-])?([a-z]+)[^|]*\|/gm,
-    (_, role) => `| ${names[host](role)} |`,
-  );
+  if (!["codex", "claude", "opencode", "copilot", "cursor"].includes(host)) throw new Error(`Unknown instruction host: ${host}`);
+  return source.slice(beginning, boundary < 0 ? undefined : boundary).trim();
 }
 
 function merge(existing, content) {

From acf3e69e29e312b956a20bda223e8821d5add08d Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:25:41 +0800
Subject: [PATCH 33/73] chore(cli): recommend mistral large 4 and clarify agent
 configuration scope

---
 .../tasks/2026_10/2026_10_14_sub_agents/verification.md     | 1 +
 cli/src/contexts/tools/domain/formats/agent-models.json     | 2 +-
 docs/DELEGATION.md                                          | 6 +++++-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 2b56fe37f..219d9531f 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -11,6 +11,7 @@ The four agents are bundled with the CLI, outside plugins. Explicit installation
 ## Optional behavior-only agents, 2026-10-16
 
 - **Configuration:** the same JSON separates advisory `main` models from applied `subagent` settings and adds Mistral on OpenCode V2. Sources and native-format references are in [the agent guide](../../../../docs/DELEGATION.md).
+- **Preferences:** Mistral main now recommends Large 4; Small 4 remains the subagent default. The official model page and local OpenCode catalog agree on `mistral-large-4`. Codex Fast is documented as a parent-session preference inherited by agents, not an agent header; installation leaves it unchanged.
 - **CLI:** 19 built-CLI cases pass, including eight provider/IDE pairs and switching to Mistral; 77 focused unit and command integration cases pass. Build: 694.7 KB / 695 KB.
 - **Reload:** 47 script cases pass. Regressions first reproduced personal-agent deletion and the wrong OpenCode Claude fallback; both now pass. Standalone agents remain unchanged.
 - **Gates:** 6,574 CLI tests pass, one skipped (`env -u CODEX_THREAD_ID pnpm test`); 494 script tests pass through the Git-safe wrapper. Lint, typecheck, type honesty, architecture, links, duplication, and knip pass. An initial run exposed the expected help snapshot change and two inherited-session fixture failures; the refreshed snapshot and isolated environment pass.
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.json b/cli/src/contexts/tools/domain/formats/agent-models.json
index a9537392e..594e5ee8d 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.json
+++ b/cli/src/contexts/tools/domain/formats/agent-models.json
@@ -25,7 +25,7 @@
     },
     "mistral": {
       "main": {
-        "model": "mistral-medium-2604",
+        "model": "mistral-large-4",
         "effort": "high"
       },
       "subagent": {
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
index 0d4d9b2ee..5f643e1c4 100644
--- a/docs/DELEGATION.md
+++ b/docs/DELEGATION.md
@@ -11,6 +11,10 @@ aidd agents remove --ide codex
 
 The [CLI model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines `main` recommendations and applied `subagent` headers. Installing agents leaves the main model unchanged. Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
 
+Installation writes project-local agent files and `.aidd/agents.json`. After updating the CLI, rerun the same install command to refresh unmodified agents; `sync` and `make reload` do not refresh them.
+
 Each agent is one self-contained native file. Plugins and `make reload` do not install these optional agents; workflows delegate by responsibility using available host agents.
 
-Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants). These recommendations are not a comparative benchmark or proof of account access.
+Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
+
+Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4 (public preview)](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants). These recommendations are not a comparative benchmark or proof of account access.

From 2e505210c084d9bb9227de8bc9592f1a6ce8b0cb Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:29:30 +0800
Subject: [PATCH 34/73] fix(cli): align bundle budget with the measured next
 integration

---
 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md | 1 +
 cli/package.json                                              | 2 +-
 cli/scripts/check-bundle-size.mjs                             | 2 ++
 3 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 219d9531f..c0e8ff3e8 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -15,6 +15,7 @@ The four agents are bundled with the CLI, outside plugins. Explicit installation
 - **CLI:** 19 built-CLI cases pass, including eight provider/IDE pairs and switching to Mistral; 77 focused unit and command integration cases pass. Build: 694.7 KB / 695 KB.
 - **Reload:** 47 script cases pass. Regressions first reproduced personal-agent deletion and the wrong OpenCode Claude fallback; both now pass. Standalone agents remain unchanged.
 - **Gates:** 6,574 CLI tests pass, one skipped (`env -u CODEX_THREAD_ID pnpm test`); 494 script tests pass through the Git-safe wrapper. Lint, typecheck, type honesty, architecture, links, duplication, and knip pass. An initial run exposed the expected help snapshot change and two inherited-session fixture failures; the refreshed snapshot and isolated environment pass.
+- **CI build:** the completed run on `78344131` measured 697.0 KB after merging `next` at `ae8705f7`, versus 694.7 KB on the branch. Nine checks failed from the same 695 KB limit. Dependencies and build settings match; the merge adds the daily telemetry ledger and bounded reports. The budget is now 705 KB, with 1.1% headroom on that measured merge; the next CI run must confirm it.
 - **Limits:** no authenticated inference establishes effective runtime model selection for this candidate.
 
 ## Earlier runtime evidence
diff --git a/cli/package.json b/cli/package.json
index a9e421de4..7bd5029ea 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "packageManager": "pnpm@12.3.4",
-  "bundleBudgetKB": 695,
+  "bundleBudgetKB": 705,
   "scripts": {
     "build": "tsup && node scripts/check-bundle-size.mjs",
     "build:check-size": "node scripts/check-bundle-size.mjs",
diff --git a/cli/scripts/check-bundle-size.mjs b/cli/scripts/check-bundle-size.mjs
index 0502ca56e..0c30c7ced 100644
--- a/cli/scripts/check-bundle-size.mjs
+++ b/cli/scripts/check-bundle-size.mjs
@@ -43,6 +43,8 @@ const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
 // correctly (+5,008 bytes over 0.27.3); unchanged application and minification settings.
 // 695 KB: 680.6 KB, that esbuild merged into the deterministic token measurement (+5.3 KB over
 // the 675.3 KB above); 2.1% measured headroom.
+// 705 KB: 697.0 KB, optional native agents and model policy measured on #1027's CI merge
+// with next ae8705f7; 1.1% headroom. The branch alone measured 694.7 KB.
 const budgetKB = pkg.bundleBudgetKB ?? 500;
 const budgetBytes = budgetKB * 1024;
 

From af54f76dca2615b607b0f235497af965d048a9fa Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:45:06 +0800
Subject: [PATCH 35/73] refactor(agents): favor simple concise code and
 documentation

---
 cli/assets/agents/executor.md | 7 ++++---
 cli/assets/agents/reviewer.md | 2 +-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/cli/assets/agents/executor.md b/cli/assets/agents/executor.md
index 17a9b2a34..588140d85 100644
--- a/cli/assets/agents/executor.md
+++ b/cli/assets/agents/executor.md
@@ -1,15 +1,16 @@
 ---
 name: executor
-description: Implements assigned work within defined scope. Use to build or fix a deliverable, verify the result, and repair failures against the requested outcome.
+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
 
-Implement assigned work, choosing the technique within the agreed outcome and criteria.
+Deliver assigned code or documentation within the agreed outcome and criteria.
 
 # Behavior
 
-- **Implement within owned scope**, making local technical choices; escalate material changes to scope or dependencies.
+- **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.
 - **Respect file and shared-operation ownership**; return changes and evidence to the caller.
 
diff --git a/cli/assets/agents/reviewer.md b/cli/assets/agents/reviewer.md
index 9bc7b4eca..968428d0f 100644
--- a/cli/assets/agents/reviewer.md
+++ b/cli/assets/agents/reviewer.md
@@ -10,7 +10,7 @@ Review finished work independently and identify quality or coherence gaps that a
 # Behavior
 
 - **Review the actual work and need independently**, using project conventions and caller-supplied criteria. Check defects, contradictions, duplication, unnecessary complexity, and gaps in validation evidence.
-- **Tie findings to evidence and impact**; distinguish defects from suggestions, name uncertainty, and suggest the smallest correction.
+- **Tie findings to evidence and impact**; distinguish defects from suggestions and state uncertainty. Recommend the smallest correction, favoring removal of obsolete or redundant material while preserving useful knowledge.
 - **Keep the work unchanged** and return findings to the caller.
 
 # Output

From af09b6f4e4f438cebc17f25f342953d8d1d1e7a9 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 08:50:31 +0800
Subject: [PATCH 36/73] docs: add a beta trial guide for optional agents

---
 README.md          |  6 +++++-
 cli/README.md      |  4 ++--
 docs/DELEGATION.md | 50 ++++++++++++++++++++++++++++++++++++++--------
 3 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 4f0a67283..366df909a 100644
--- a/README.md
+++ b/README.md
@@ -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 agents (beta)
+
+Custom agents are a separate, project-local opt-in. Plugins work without them. See the [installation and native execution trial](docs/DELEGATION.md) to test the unreleased CLI feature.
+
 ## 🚀 Quick start
 
 Three ways in — pick one:
diff --git a/cli/README.md b/cli/README.md
index 720c59ae6..1b0f1304b 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -121,9 +121,9 @@ 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
+## Agents (beta)
 
-Opt in with `aidd agents install --provider openai --ide codex`; see [agent installation](../docs/DELEGATION.md).
+Agents are an optional project-local add-on, separate from plugin installation. This command is unreleased; see [the local build and native execution trial](../docs/DELEGATION.md).
 
 ## Translate
 
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
index 5f643e1c4..514c20da5 100644
--- a/docs/DELEGATION.md
+++ b/docs/DELEGATION.md
@@ -1,19 +1,53 @@
-# Optional agents
+# Optional agents (beta)
 
-Install agents in the current project with a provider and IDE:
+Custom agents are an explicit opt-in. Workflows delegate by responsibility using available host agents; plugins work without this add-on.
+
+## Install, update, remove
+
+The CLI command is unreleased. Build the `feature/sub-agents` checkout from the framework root:
 
 ```sh
-aidd agents install --provider openai --ide codex
-aidd agents install --provider anthropic --ide claude-code
-aidd agents install --provider mistral --ide opencode
-aidd agents remove --ide codex
+pnpm --dir cli install --frozen-lockfile
+pnpm --dir cli build
 ```
 
-The [CLI model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines `main` recommendations and applied `subagent` headers. Installing agents leaves the main model unchanged. Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
+From the target project's root, use the built CLI instead of a published `aidd`:
+
+```sh
+node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
+node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
+```
+
+Choose the provider and IDE from the [CLI model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json). It defines `main` recommendations and applied `subagent` headers. Installing agents leaves the main model unchanged. Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
 
 Installation writes project-local agent files and `.aidd/agents.json`. After updating the CLI, rerun the same install command to refresh unmodified agents; `sync` and `make reload` do not refresh them.
 
-Each agent is one self-contained native file. Plugins and `make reload` do not install these optional agents; workflows delegate by responsibility using available host agents.
+Each agent is one self-contained native file. Installation and removal refuse to overwrite or delete modified agents. Plugins and `make reload` do not install these optional agents.
+
+## Native execution trial
+
+Run in a disposable project or clean branch with a small task and explicit success criteria:
+
+1. **Load.** Open a fresh host session in the target project. Confirm it exposes the installed native roles; record the loaded definition's path and generated model and effort settings.
+2. **Explore.** Ask for a delegated, read-only answer to one scoped codebase question, with file references. Confirm a separate agent actually ran.
+3. **Implement.** Delegate one small code or documentation change with owned files and a check. Inspect the resulting diff and check evidence.
+4. **Verify.** Request separate validation against the criteria and review for quality, coherence, and unnecessary changes.
+
+Capture host dispatch records and actual model, effort, and tier metadata where exposed. Generated headers and the agent's own claims do not establish runtime selection. Mark unavailable metadata **unverified**.
+
+Copy one report per trial:
+
+```markdown
+- **IDE/version:**
+- **CLI version/commit:**
+- **Provider:**
+- **Task and success criteria:**
+- **Observed source/dispatch/model/effort/tier:**
+- **Result:** passed / failed / unverified
+- **Evidence:** host records, relevant diff, check command and result
+```
+
+## Model notes
 
 Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
 

From 61792881eb726768ae156b440d71f69dafe18615 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 10:13:18 +0800
Subject: [PATCH 37/73] docs: rename and clarify the subagent guide

---
 README.md                                     |  4 +-
 .../2026_10_14_sub_agents/verification.md     |  2 +-
 cli/README.md                                 |  2 +-
 docs/DELEGATION.md                            | 54 -------------
 docs/SUBAGENTS.md                             | 77 +++++++++++++++++++
 5 files changed, 81 insertions(+), 58 deletions(-)
 delete mode 100644 docs/DELEGATION.md
 create mode 100644 docs/SUBAGENTS.md

diff --git a/README.md b/README.md
index 366df909a..bc786b8cd 100644
--- a/README.md
+++ b/README.md
@@ -185,9 +185,9 @@ codex plugin add aidd-context@aidd-framework   # per plugin
 
 </details>
 
-### Optional agents (beta)
+### Optional subagents (beta)
 
-Custom agents are a separate, project-local opt-in. Plugins work without them. See the [installation and native execution trial](docs/DELEGATION.md) to test the unreleased CLI feature.
+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
 
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index c0e8ff3e8..912e4c56c 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -10,7 +10,7 @@ The four agents are bundled with the CLI, outside plugins. Explicit installation
 
 ## Optional behavior-only agents, 2026-10-16
 
-- **Configuration:** the same JSON separates advisory `main` models from applied `subagent` settings and adds Mistral on OpenCode V2. Sources and native-format references are in [the agent guide](../../../../docs/DELEGATION.md).
+- **Configuration:** the same JSON separates advisory `main` models from applied `subagent` settings and adds Mistral on OpenCode V2. Sources and native-format references are in [the agent guide](../../../../docs/SUBAGENTS.md).
 - **Preferences:** Mistral main now recommends Large 4; Small 4 remains the subagent default. The official model page and local OpenCode catalog agree on `mistral-large-4`. Codex Fast is documented as a parent-session preference inherited by agents, not an agent header; installation leaves it unchanged.
 - **CLI:** 19 built-CLI cases pass, including eight provider/IDE pairs and switching to Mistral; 77 focused unit and command integration cases pass. Build: 694.7 KB / 695 KB.
 - **Reload:** 47 script cases pass. Regressions first reproduced personal-agent deletion and the wrong OpenCode Claude fallback; both now pass. Standalone agents remain unchanged.
diff --git a/cli/README.md b/cli/README.md
index 1b0f1304b..508eaacb0 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -123,7 +123,7 @@ aidd setup --scope user --ai claude,codex,copilot --plugins none --yes
 
 ## Agents (beta)
 
-Agents are an optional project-local add-on, separate from plugin installation. This command is unreleased; see [the local build and native execution trial](../docs/DELEGATION.md).
+Install optional agents per project with the [subagent guide](../docs/SUBAGENTS.md).
 
 ## Translate
 
diff --git a/docs/DELEGATION.md b/docs/DELEGATION.md
deleted file mode 100644
index 514c20da5..000000000
--- a/docs/DELEGATION.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Optional agents (beta)
-
-Custom agents are an explicit opt-in. Workflows delegate by responsibility using available host agents; plugins work without this add-on.
-
-## Install, update, remove
-
-The CLI command is unreleased. Build the `feature/sub-agents` checkout from the framework root:
-
-```sh
-pnpm --dir cli install --frozen-lockfile
-pnpm --dir cli build
-```
-
-From the target project's root, use the built CLI instead of a published `aidd`:
-
-```sh
-node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
-node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
-```
-
-Choose the provider and IDE from the [CLI model configuration](../cli/src/contexts/tools/domain/formats/agent-models.json). It defines `main` recommendations and applied `subagent` headers. Installing agents leaves the main model unchanged. Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
-
-Installation writes project-local agent files and `.aidd/agents.json`. After updating the CLI, rerun the same install command to refresh unmodified agents; `sync` and `make reload` do not refresh them.
-
-Each agent is one self-contained native file. Installation and removal refuse to overwrite or delete modified agents. Plugins and `make reload` do not install these optional agents.
-
-## Native execution trial
-
-Run in a disposable project or clean branch with a small task and explicit success criteria:
-
-1. **Load.** Open a fresh host session in the target project. Confirm it exposes the installed native roles; record the loaded definition's path and generated model and effort settings.
-2. **Explore.** Ask for a delegated, read-only answer to one scoped codebase question, with file references. Confirm a separate agent actually ran.
-3. **Implement.** Delegate one small code or documentation change with owned files and a check. Inspect the resulting diff and check evidence.
-4. **Verify.** Request separate validation against the criteria and review for quality, coherence, and unnecessary changes.
-
-Capture host dispatch records and actual model, effort, and tier metadata where exposed. Generated headers and the agent's own claims do not establish runtime selection. Mark unavailable metadata **unverified**.
-
-Copy one report per trial:
-
-```markdown
-- **IDE/version:**
-- **CLI version/commit:**
-- **Provider:**
-- **Task and success criteria:**
-- **Observed source/dispatch/model/effort/tier:**
-- **Result:** passed / failed / unverified
-- **Evidence:** host records, relevant diff, check command and result
-```
-
-## Model notes
-
-Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
-
-Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4 (public preview)](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants). These recommendations are not a comparative benchmark or proof of account access.
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
new file mode 100644
index 000000000..7f9f5d3b5
--- /dev/null
+++ b/docs/SUBAGENTS.md
@@ -0,0 +1,77 @@
+# Optional subagents (beta)
+
+Add focused roles to your project's AI tool. Installation is explicit; workflows can also use the host's available agents.
+
+| Role | Responsibility |
+| --- | --- |
+| Exploration | Answer scoped codebase questions with source references. |
+| Implementation | Deliver simple code or documentation with minimal changes and verification evidence. |
+| Validation | Confirm the requested outcome and acceptance criteria hold. |
+| Review | Find quality gaps, contradictions, duplication, and unnecessary complexity. |
+
+## Install
+
+The CLI command is unreleased. Build the `feature/sub-agents` checkout from the framework root:
+
+```sh
+pnpm --dir cli install --frozen-lockfile
+pnpm --dir cli build
+```
+
+From the target project's root, install with a supported provider and IDE:
+
+```sh
+node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
+```
+
+The [CLI configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines supported provider/IDE pairs, recommended `main` models, and applied `subagent` model and effort settings. Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`. The main model stays unchanged.
+
+## Try a small task
+
+Use a disposable project or clean branch with explicit success criteria. Open a fresh host session after installation.
+
+1. **Load:** confirm the installed roles are available; record the loaded definition's path and configured model and effort.
+2. **Explore:** delegate one read-only codebase question; check the answer's source references and confirm a separate agent ran.
+3. **Implement:** delegate one small code or documentation change with owned files and a check; inspect the diff and results.
+4. **Verify:** request independent validation against the criteria and review of quality and coherence.
+
+Use host dispatch records to identify the agent and actual model, effort, and tier where exposed. Headers and agent self-reports alone do not prove runtime selection; mark unavailable evidence **unverified**.
+
+## Update or remove
+
+After updating the CLI, rerun the install command to refresh unmodified agents. Plugins, `sync`, and `make reload` do not install or refresh this add-on.
+
+To remove only one IDE's agents from the current project:
+
+```sh
+node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
+```
+
+The other IDEs' agents remain installed. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including all managed agents.
+
+## Beta limitations
+
+- **Copilot:** installed custom subagents currently lack `include-custom-instructions: true`, required to receive repository instructions such as `AGENTS.md`. [Native contract](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#repository-custom-instructions-for-subagents), checked 2026-10-16.
+- **Ownership registry:** run installation and removal sequentially. Concurrent commands can lose ownership records; a failed registry write can leave files requiring manual recovery.
+
+## Share a trial
+
+Copy one report per trial:
+
+```markdown
+- **IDE/version:**
+- **CLI version/commit:**
+- **Provider:**
+- **Task and success criteria:**
+- **Observed source/dispatch/model/effort/tier:**
+- **Result:** passed / failed / unverified
+- **Evidence:** host records, relevant diff, check command and result
+```
+
+## Model notes
+
+Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
+
+Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
+
+Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4 (public preview)](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants). These recommendations are not a comparative benchmark or proof of account access.

From 92f9371d01cddca404d713c141967d7fcc2431dc Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 10:19:55 +0800
Subject: [PATCH 38/73] docs: link subagent model and ide configuration
 explicitly

---
 docs/SUBAGENTS.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 7f9f5d3b5..2b5b8f38e 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -9,6 +9,10 @@ Add focused roles to your project's AI tool. Installation is explicit; workflows
 | Validation | Confirm the requested outcome and acceptance criteria hold. |
 | Review | Find quality gaps, contradictions, duplication, and unnecessary complexity. |
 
+## Models and IDEs
+
+[agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) is the source for supported provider/IDE pairs and model and effort settings. Installation applies `subagent` settings; `main` is a recommendation only.
+
 ## Install
 
 The CLI command is unreleased. Build the `feature/sub-agents` checkout from the framework root:
@@ -24,7 +28,7 @@ From the target project's root, install with a supported provider and IDE:
 node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
 ```
 
-The [CLI configuration](../cli/src/contexts/tools/domain/formats/agent-models.json) defines supported provider/IDE pairs, recommended `main` models, and applied `subagent` model and effort settings. Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`. The main model stays unchanged.
+Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`.
 
 ## Try a small task
 

From cfa5d8e374de5728eb45ddc252d07a494228cd7a Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 10:53:22 +0800
Subject: [PATCH 39/73] docs: add subagent source links and guide navigation

---
 docs/SUBAGENTS.md | 39 +++++++++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 2b5b8f38e..a9a714459 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -1,19 +1,34 @@
-# Optional subagents (beta)
+# 🤝 Optional subagents (beta)
+
+## 📑 Contents
+
+- [Roles](#-roles)
+- [Models and IDEs](#-models-and-ides)
+- [Install](#-install)
+- [Try a small task](#-try-a-small-task)
+- [Update or remove](#-update-or-remove)
+- [Beta limitations](#-beta-limitations)
+- [Share a trial](#-share-a-trial)
+- [Model notes](#-model-notes)
+
+## 👥 Roles
 
 Add focused roles to your project's AI tool. Installation is explicit; workflows can also use the host's available agents.
 
 | Role | Responsibility |
 | --- | --- |
-| Exploration | Answer scoped codebase questions with source references. |
-| Implementation | Deliver simple code or documentation with minimal changes and verification evidence. |
-| Validation | Confirm the requested outcome and acceptance criteria hold. |
-| Review | Find quality gaps, contradictions, duplication, and unnecessary complexity. |
+| [Exploration](../cli/assets/agents/explorer.md) | Answer scoped codebase questions with source references. |
+| [Implementation](../cli/assets/agents/executor.md) | Deliver simple code or documentation with minimal changes and verification evidence. |
+| [Validation](../cli/assets/agents/validator.md) | Confirm the requested outcome and acceptance criteria hold. |
+| [Review](../cli/assets/agents/reviewer.md) | Find quality gaps, contradictions, duplication, and unnecessary complexity. |
+
+**Scope and delegation:** see the [Project Memory AGENTS.md template](../plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md#agents).
 
-## Models and IDEs
+## 🧠 Models and IDEs
 
 [agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) is the source for supported provider/IDE pairs and model and effort settings. Installation applies `subagent` settings; `main` is a recommendation only.
 
-## Install
+## 📦 Install
 
 The CLI command is unreleased. Build the `feature/sub-agents` checkout from the framework root:
 
@@ -30,7 +45,7 @@ node /absolute/path/to/framework/cli/dist/cli.js agents install --provider opena
 
 Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`.
 
-## Try a small task
+## 🧪 Try a small task
 
 Use a disposable project or clean branch with explicit success criteria. Open a fresh host session after installation.
 
@@ -41,7 +56,7 @@ Use a disposable project or clean branch with explicit success criteria. Open a
 
 Use host dispatch records to identify the agent and actual model, effort, and tier where exposed. Headers and agent self-reports alone do not prove runtime selection; mark unavailable evidence **unverified**.
 
-## Update or remove
+## 🔄 Update or remove
 
 After updating the CLI, rerun the install command to refresh unmodified agents. Plugins, `sync`, and `make reload` do not install or refresh this add-on.
 
@@ -53,12 +68,12 @@ node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
 
 The other IDEs' agents remain installed. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including all managed agents.
 
-## Beta limitations
+## 🚧 Beta limitations
 
 - **Copilot:** installed custom subagents currently lack `include-custom-instructions: true`, required to receive repository instructions such as `AGENTS.md`. [Native contract](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#repository-custom-instructions-for-subagents), checked 2026-10-16.
 - **Ownership registry:** run installation and removal sequentially. Concurrent commands can lose ownership records; a failed registry write can leave files requiring manual recovery.
 
-## Share a trial
+## 📝 Share a trial
 
 Copy one report per trial:
 
@@ -72,7 +87,7 @@ Copy one report per trial:
 - **Evidence:** host records, relevant diff, check command and result
 ```
 
-## Model notes
+## 💡 Model notes
 
 Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
 

From 50e2dfda5106cc765cc4e49de87ceb9030d68375 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 11:17:45 +0800
Subject: [PATCH 40/73] feat(cli): configure model profiles for every agent
 role

---
 .../agents/manage-agents-use-case.ts          |  3 +-
 .../tools/domain/formats/agent-models.json    | 24 +++++--
 .../tools/domain/formats/agent-models.ts      | 24 +++++--
 ...manage-agents-use-case.integration.test.ts |  6 ++
 .../domain/formats/agent-models.unit.test.ts  | 26 ++++++-
 cli/tests/e2e/agents.e2e.test.ts              | 72 ++++++++++++++++---
 docs/SUBAGENTS.md                             |  4 +-
 7 files changed, 130 insertions(+), 29 deletions(-)

diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
index 77f18bd55..2b69d384a 100644
--- a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -32,11 +32,12 @@ export class ManageAgentsUseCase {
   ) {}
 
   async install(options: AgentTarget & { provider: AgentProvider }): Promise<number> {
-    const model = agentModelOptions(options.host, options.provider);
     const installed = await this.load(options.projectRoot);
     const capability = this.capability(options.host);
     const entries = Object.entries(this.sources).map(([name, source]) => {
       const { frontmatter, body } = parseFrontmatter(source);
+      const role = typeof frontmatter.name === "string" ? frontmatter.name : name;
+      const model = agentModelOptions(options.host, options.provider, role);
       return {
         name,
         path: this.path(options.projectRoot, capability, name),
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.json b/cli/src/contexts/tools/domain/formats/agent-models.json
index 594e5ee8d..7eff7aa99 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.json
+++ b/cli/src/contexts/tools/domain/formats/agent-models.json
@@ -1,21 +1,31 @@
 {
+  "roles": {
+    "main": "standard",
+    "explorer": "light",
+    "executor": "light",
+    "validator": "light",
+    "reviewer": "standard"
+  },
   "providers": {
     "openai": {
-      "main": {
+      "standard": {
         "model": "gpt-6.1-sol",
         "effort": "medium"
       },
-      "subagent": {
+      "light": {
         "model": "gpt-6-luna",
         "effort": "medium"
       }
     },
     "anthropic": {
-      "main": {
+      "standard": {
         "model": "claude-opus-5-5",
-        "effort": "medium"
+        "effort": "medium",
+        "nativeModels": {
+          "copilot": "claude-opus-5.5"
+        }
       },
-      "subagent": {
+      "light": {
         "model": "claude-haiku-5-5",
         "effort": "medium",
         "nativeModels": {
@@ -24,11 +34,11 @@
       }
     },
     "mistral": {
-      "main": {
+      "standard": {
         "model": "mistral-large-4",
         "effort": "high"
       },
-      "subagent": {
+      "light": {
         "model": "mistral-small-2603",
         "effort": "high"
       }
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.ts b/cli/src/contexts/tools/domain/formats/agent-models.ts
index e1b9c5f3d..14be1b783 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.ts
+++ b/cli/src/contexts/tools/domain/formats/agent-models.ts
@@ -3,6 +3,12 @@ import models from "./agent-models.json" with { type: "json" };
 export type AgentHost = keyof typeof models.hosts;
 export type AgentProvider = keyof typeof models.providers;
 
+interface AgentModelProfile {
+  model: string;
+  effort: string;
+  nativeModels?: Partial<Record<AgentHost, string>>;
+}
+
 export function isAgentHost(value: unknown): value is AgentHost {
   return typeof value === "string" && Object.hasOwn(models.hosts, value);
 }
@@ -29,20 +35,24 @@ export function resolveAgentHost(ide: string): AgentHost {
   return host;
 }
 
-/** Native fields for an explicitly selected host and provider. */
+/** Native fields for a configured role on the selected host and provider. */
 export function agentModelOptions(
   host: AgentHost,
-  provider: AgentProvider
+  provider: AgentProvider,
+  role: string
 ): Record<string, unknown> {
   const target = models.hosts[host];
   if (!target.providers.includes(provider)) {
     throw new Error(`Provider "${provider}" is not supported by "${host}".`);
   }
-  const source = models.providers[provider].subagent;
-  const nativeModel =
-    "nativeModels" in source
-      ? (Object.entries(source.nativeModels).find(([name]) => name === host)?.[1] ?? source.model)
-      : source.model;
+  const profile = Object.entries(models.roles).find(([name]) => name === role)?.[1];
+  if (profile === undefined) throw new Error(`Agent role "${role}" is not configured.`);
+  const source: AgentModelProfile | undefined = Object.entries(models.providers[provider]).find(
+    ([name]) => name === profile
+  )?.[1];
+  if (source === undefined)
+    throw new Error(`Agent profile "${profile}" is not configured for "${provider}".`);
+  const nativeModel = source.nativeModels?.[host] ?? source.model;
   const model = `${"providerPrefix" in target && target.providerPrefix ? `${provider}/` : ""}${nativeModel}`;
   return "effortField" in target
     ? { model, [target.effortField]: source.effort }
diff --git a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
index 8781b5785..834d8c910 100644
--- a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
+++ b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
@@ -33,6 +33,9 @@ describe("ManageAgentsUseCase", () => {
     expect(content).toContain('model = "gpt-6-luna"');
     expect(content).toContain('model_reasoning_effort = "medium"');
     expect(content).toContain('name = "aidd-dev-explorer"');
+    const review = await readFile(join(root, ".codex/agents/aidd-dev-reviewer.toml"), "utf8");
+    expect(review).toContain('model = "gpt-6.1-sol"');
+    expect(review).toContain('model_reasoning_effort = "medium"');
     expect(
       JSON.parse(await readFile(join(root, ".aidd/agents.json"), "utf8")).codex
     ).toHaveProperty("aidd-dev-explorer");
@@ -47,6 +50,9 @@ describe("ManageAgentsUseCase", () => {
     expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
       "anthropic/claude-haiku-5-5#medium"
     );
+    expect(await readFile(join(root, ".opencode/agents/aidd-dev-reviewer.md"), "utf8")).toContain(
+      "anthropic/claude-opus-5-5#medium"
+    );
     await writeFile(join(root, ".opencode/agents/aidd-dev-reviewer.md"), "personal edit");
     await expect(
       manager.install({ projectRoot: root, host: "opencode", provider: "openai" })
diff --git a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
index 41943fa5e..58e564d78 100644
--- a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
@@ -50,7 +50,29 @@ describe("explicit agent models", () => {
     ["opencode", "mistral", { model: "mistral/mistral-small-2603#high" }],
     ["cursor", "anthropic", { model: "claude-haiku-5-5[effort=medium]" }],
   ] as const)("serializes %s with the selected %s provider", (host, provider, expected) => {
-    expect(agentModelOptions(host, provider)).toStrictEqual(expected);
+    for (const role of ["explorer", "executor", "validator"])
+      expect(agentModelOptions(host, provider, role)).toStrictEqual(expected);
+  });
+
+  it.each([
+    ["claude", "anthropic", { model: "claude-opus-5-5", effort: "medium" }],
+    ["codex", "openai", { model: "gpt-6.1-sol", model_reasoning_effort: "medium" }],
+    ["copilot", "openai", { model: "gpt-6.1-sol", reasoningEffort: "medium" }],
+    ["copilot", "anthropic", { model: "claude-opus-5.5", reasoningEffort: "medium" }],
+    ["opencode", "openai", { model: "openai/gpt-6.1-sol#medium" }],
+    ["opencode", "anthropic", { model: "anthropic/claude-opus-5-5#medium" }],
+    ["opencode", "mistral", { model: "mistral/mistral-large-4#high" }],
+    ["cursor", "anthropic", { model: "claude-opus-5-5[effort=medium]" }],
+  ] as const)(
+    "shares model and effort between main and review on %s / %s",
+    (host, provider, expected) => {
+      for (const role of ["main", "reviewer"])
+        expect(agentModelOptions(host, provider, role)).toStrictEqual(expected);
+    }
+  );
+
+  it.each(["unknown", "constructor", "__proto__", ""])("rejects unconfigured role %s", (role) => {
+    expect(() => agentModelOptions("codex", "openai", role)).toThrow(/role.*not configured/);
   });
 
   it.each([
@@ -62,7 +84,7 @@ describe("explicit agent models", () => {
     ["copilot", "mistral"],
     ["cursor", "mistral"],
   ] as const)("rejects unsupported %s / %s selections", (host, provider) => {
-    expect(() => agentModelOptions(host, provider)).toThrow(/not supported/);
+    expect(() => agentModelOptions(host, provider, "reviewer")).toThrow(/not supported/);
   });
 
   it.each(["claude", "codex", "copilot", "opencode", "cursor"])(
diff --git a/cli/tests/e2e/agents.e2e.test.ts b/cli/tests/e2e/agents.e2e.test.ts
index bfa2b07ae..560a2436b 100644
--- a/cli/tests/e2e/agents.e2e.test.ts
+++ b/cli/tests/e2e/agents.e2e.test.ts
@@ -8,24 +8,74 @@ import { createTestEnv, runCli } from "./helpers.js";
 
 const roles = ["explorer", "executor", "validator", "reviewer"];
 const cases = [
-  ["claude-code", "anthropic", ".claude", ".md", { model: "claude-haiku-5-5", effort: "medium" }],
-  ["codex", "openai", ".codex", ".toml", { model: "gpt-6-luna", model_reasoning_effort: "medium" }],
-  ["copilot", "openai", ".github", ".agent.md", { model: "gpt-6-luna", reasoningEffort: "medium" }],
+  [
+    "claude-code",
+    "anthropic",
+    ".claude",
+    ".md",
+    { model: "claude-haiku-5-5", effort: "medium" },
+    { model: "claude-opus-5-5", effort: "medium" },
+  ],
+  [
+    "codex",
+    "openai",
+    ".codex",
+    ".toml",
+    { model: "gpt-6-luna", model_reasoning_effort: "medium" },
+    { model: "gpt-6.1-sol", model_reasoning_effort: "medium" },
+  ],
+  [
+    "copilot",
+    "openai",
+    ".github",
+    ".agent.md",
+    { model: "gpt-6-luna", reasoningEffort: "medium" },
+    { model: "gpt-6.1-sol", reasoningEffort: "medium" },
+  ],
   [
     "copilot",
     "anthropic",
     ".github",
     ".agent.md",
     { model: "claude-haiku-5.5", reasoningEffort: "medium" },
+    { model: "claude-opus-5.5", reasoningEffort: "medium" },
+  ],
+  [
+    "opencode",
+    "openai",
+    ".opencode",
+    ".md",
+    { model: "openai/gpt-6-luna#medium" },
+    { model: "openai/gpt-6.1-sol#medium" },
+  ],
+  [
+    "opencode",
+    "anthropic",
+    ".opencode",
+    ".md",
+    { model: "anthropic/claude-haiku-5-5#medium" },
+    { model: "anthropic/claude-opus-5-5#medium" },
+  ],
+  [
+    "opencode",
+    "mistral",
+    ".opencode",
+    ".md",
+    { model: "mistral/mistral-small-2603#high" },
+    { model: "mistral/mistral-large-4#high" },
+  ],
+  [
+    "cursor",
+    "anthropic",
+    ".cursor",
+    ".md",
+    { model: "claude-haiku-5-5[effort=medium]" },
+    { model: "claude-opus-5-5[effort=medium]" },
   ],
-  ["opencode", "openai", ".opencode", ".md", { model: "openai/gpt-6-luna#medium" }],
-  ["opencode", "anthropic", ".opencode", ".md", { model: "anthropic/claude-haiku-5-5#medium" }],
-  ["opencode", "mistral", ".opencode", ".md", { model: "mistral/mistral-small-2603#high" }],
-  ["cursor", "anthropic", ".cursor", ".md", { model: "claude-haiku-5-5[effort=medium]" }],
 ] as const;
 
 describe.concurrent("explicit native agent installation", () => {
-  for (const [ide, provider, directory, suffix, expected] of cases) {
+  for (const [ide, provider, directory, suffix, expected, reviewModel] of cases) {
     it(`${ide} installs the four agents with ${provider} headers, then removes them`, async () => {
       const box = await createTestEnv(`agents-${ide}-${provider}`);
       try {
@@ -42,7 +92,7 @@ describe.concurrent("explicit native agent installation", () => {
           );
           const fields =
             ide === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
-          expect(fields).toMatchObject(expected);
+          expect(fields).toMatchObject(role === "reviewer" ? reviewModel : expected);
           if (ide === "opencode") expect(fields.mode).toBe("subagent");
           else expect(fields.name).toBe(`aidd-dev-${role}`);
           expect(content).toContain("# Behavior");
@@ -124,7 +174,9 @@ describe.concurrent("explicit native agent installation", () => {
       }
       for (const role of roles) {
         const content = await readFile(join(directory, `aidd-dev-${role}.md`), "utf8");
-        expect(parseFrontmatter(content).frontmatter.model).toBe("mistral/mistral-small-2603#high");
+        expect(parseFrontmatter(content).frontmatter.model).toBe(
+          role === "reviewer" ? "mistral/mistral-large-4#high" : "mistral/mistral-small-2603#high"
+        );
       }
       const removed = await runCli(
         ["agents", "remove", "--ide", "opencode"],
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index a9a714459..b0339d4a6 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -26,7 +26,7 @@ Add focused roles to your project's AI tool. Installation is explicit; workflows
 
 ## 🧠 Models and IDEs
 
-[agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) is the source for supported provider/IDE pairs and model and effort settings. Installation applies `subagent` settings; `main` is a recommendation only.
+[agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) assigns every role a `standard` or `light` profile. Each provider defines the profiles' model and effort. Main and review share `standard`; the `main` role is advisory and installation leaves the main session configuration unchanged.
 
 ## 📦 Install
 
@@ -93,4 +93,4 @@ Mistral is supported on OpenCode; its documented reasoning levels are `none` and
 
 Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
 
-Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4 (public preview)](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants). These recommendations are not a comparative benchmark or proof of account access.
+Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4 (public preview)](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants), [Copilot model IDs](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#supported-models). These recommendations are not a comparative benchmark or proof of account access.

From e2df4e41979b742a77ca7937b6d6956e4df1808b Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 12:26:35 +0800
Subject: [PATCH 41/73] fix(cli): preserve native agent model and instruction
 semantics

---
 .../domain/formats/agent-frontmatter-strip.ts | 12 ++++-
 .../domain/profiles/codex/codex-agent-toml.ts | 11 ++++-
 .../tools/domain/profiles/copilot/profile.ts  |  6 ++-
 .../agent-frontmatter-strip.unit.test.ts      |  7 +++
 .../domain/profiles/codex/build.unit.test.ts  |  4 +-
 .../codex/codex-agent-toml.unit.test.ts       | 45 ++++++++++---------
 .../domain/profiles/copilot.unit.test.ts      | 42 +++++++++++++++--
 .../profiles/copilot/build.unit.test.ts       | 16 +++++++
 ...e-build-strategy.codex.integration.test.ts | 10 ++---
 cli/tests/e2e/agents.e2e.test.ts              | 25 +++++++++++
 .../snapshots/framework-build/golden.json     | 12 ++---
 11 files changed, 149 insertions(+), 41 deletions(-)

diff --git a/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts b/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts
index bf543752e..01029d4a1 100644
--- a/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts
+++ b/cli/src/contexts/tools/domain/formats/agent-frontmatter-strip.ts
@@ -5,10 +5,20 @@ export const COPILOT_AGENT_FRONTMATTER_KEYS: readonly [
   "description",
   "model",
   "reasoningEffort",
+  "include-custom-instructions",
   "tools",
   "agents",
   "argument-hint",
-] = ["name", "description", "model", "reasoningEffort", "tools", "agents", "argument-hint"];
+] = [
+  "name",
+  "description",
+  "model",
+  "reasoningEffort",
+  "include-custom-instructions",
+  "tools",
+  "agents",
+  "argument-hint",
+];
 
 /** Cursor-supported frontmatter keys: Cursor documents only name, description and model —
  * never tools or color. */
diff --git a/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts b/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
index 119afd9b6..36346d2c8 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/codex-agent-toml.ts
@@ -1,6 +1,9 @@
 import { parseFrontmatter } from "../../../../../kernel/markdown.js";
 import { stringifyToml } from "./toml.js";
 
+const CLAUDE_MODEL_SELECTOR =
+  /^(?:default|inherit|best|fable|haiku|opus|opusplan|sonnet)(?:\[1m\])?$/i;
+
 /**
  * Converts a Claude-format agent markdown file (frontmatter + body) into a Codex subagent TOML
  * string. Key insertion order is fixed for deterministic output, and the conversion is lossy —
@@ -44,8 +47,12 @@ function buildTomlObject(
   obj.name = name;
   // description is a required subagent key; default to "" when absent.
   obj.description = typeof frontmatter.description === "string" ? frontmatter.description : "";
-  for (const field of ["model", "model_reasoning_effort"]) {
-    if (frontmatter[field] !== undefined) obj[field] = frontmatter[field];
+  // Claude shorthand selectors are not native model IDs; leave the model inherited.
+  if (typeof frontmatter.model === "string" && !CLAUDE_MODEL_SELECTOR.test(frontmatter.model)) {
+    obj.model = frontmatter.model;
+  }
+  if (frontmatter.model_reasoning_effort !== undefined) {
+    obj.model_reasoning_effort = frontmatter.model_reasoning_effort;
   }
   obj.developer_instructions = body;
   return obj;
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
index 1138f72ea..beb334de0 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
@@ -98,7 +98,11 @@ const agentsHandler = {
   convertFrontmatter(fm: Record<string, unknown>, fileName?: string): Record<string, unknown> {
     const base = fileName?.split("/").at(-1);
     const name = fm.name ?? base?.replace(/\.md$/, "");
-    return { name: typeof name === "string" ? name : undefined, description: fm.description };
+    return {
+      name: typeof name === "string" ? name : undefined,
+      description: fm.description,
+      "include-custom-instructions": fm["include-custom-instructions"] ?? true,
+    };
   },
 };
 
diff --git a/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts
index f8ce620be..4e55a7277 100644
--- a/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/formats/agent-frontmatter-strip.unit.test.ts
@@ -14,6 +14,7 @@ describe("stripAgentFrontmatter", () => {
         description: "Reviews code",
         model: "claude-sonnet",
         reasoningEffort: "medium",
+        "include-custom-instructions": true,
         tools: ["Read", "Write"],
         agents: ["helper"],
         "argument-hint": "[file]",
@@ -29,6 +30,12 @@ describe("stripAgentFrontmatter", () => {
     });
   });
 
+  it("preserves an explicit repository-instruction opt-out", () => {
+    expect(stripAgentFrontmatter({ "include-custom-instructions": false })).toEqual({
+      "include-custom-instructions": false,
+    });
+  });
+
   describe("drops non-allowlisted keys", () => {
     it("drops paths key", () => {
       const input = { name: "reviewer", paths: ["src/**/*.ts"] };
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
index 0ae762193..e1966316b 100644
--- a/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
@@ -181,7 +181,7 @@ describe("buildCodexContract()", () => {
     const transform = supported(buildCodexContract().artifacts.agents).transform;
 
     expect(transform?.(AGENT_SOURCE, "aidd-dev", "planner.md")).toBe(
-      'name = "planner"\ndescription = "Plans the work"\nmodel = "opus"\ndeveloper_instructions = "Plan before building.\\n"\n'
+      'name = "planner"\ndescription = "Plans the work"\ndeveloper_instructions = "Plan before building.\\n"\n'
     );
   });
 
@@ -308,7 +308,7 @@ describe("buildCodexFlatContract()", () => {
     const transform = supported(buildCodexFlatContract().artifacts.agents).transform;
 
     expect(transform?.(AGENT_SOURCE, "aidd-dev", "planner.md")).toBe(
-      'name = "aidd-dev-planner"\ndescription = "Plans the work"\nmodel = "opus"\ndeveloper_instructions = "Plan before building.\\n"\n'
+      'name = "aidd-dev-planner"\ndescription = "Plans the work"\ndeveloper_instructions = "Plan before building.\\n"\n'
     );
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts
index ed6311676..87b1ba87a 100644
--- a/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/codex/codex-agent-toml.unit.test.ts
@@ -95,32 +95,37 @@ describe("codexAgentMarkdownToToml()", () => {
   });
 
   describe("explicit model preservation", () => {
-    it("preserves an explicit opus model literal", () => {
+    it.each([
+      "opus",
+      "sonnet",
+      "haiku",
+      "inherit",
+      "default",
+      "opusplan",
+      "best",
+      "fable",
+      "sonnet[1m]",
+      "opus[1m]",
+    ])("omits Claude selector %s so the parent model is inherited", (model) => {
       const toml = codexAgentMarkdownToToml(
-        "---\nname: planner\ndescription: A planner.\nmodel: opus\n---\n\nBody.",
+        `---\nname: planner\nmodel: ${model}\n---\n\nBody.`,
         "aidd-dev",
         "planner.md"
       );
-      expect(parseToml(toml).model).toBe("opus");
+      expect(parseToml(toml)).not.toHaveProperty("model");
     });
 
-    it("preserves an explicit sonnet model literal", () => {
-      const toml = codexAgentMarkdownToToml(
-        "---\nname: planner\nmodel: sonnet\n---\n\nBody.",
-        "aidd-dev",
-        "planner.md"
-      );
-      expect(parseToml(toml).model).toBe("sonnet");
-    });
-
-    it("preserves an explicit native model identifier", () => {
-      const toml = codexAgentMarkdownToToml(
-        "---\nname: planner\nmodel: gpt-5-codex\n---\n\nBody.",
-        "aidd-dev",
-        "planner.md"
-      );
-      expect(parseToml(toml).model).toBe("gpt-5-codex");
-    });
+    it.each(["gpt-5-codex", "gpt-6-luna", "local-coder", "claude-opus-5-5"])(
+      "preserves explicit model identifier %s for the configured provider",
+      (model) => {
+        const toml = codexAgentMarkdownToToml(
+          `---\nname: planner\nmodel: ${model}\nmodel_reasoning_effort: medium\n---\n\nBody.`,
+          "aidd-dev",
+          "planner.md"
+        );
+        expect(parseToml(toml)).toMatchObject({ model, model_reasoning_effort: "medium" });
+      }
+    );
   });
 
   describe("verbatim body preservation (D-4)", () => {
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
index 36b4b008d..140343374 100644
--- a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
@@ -26,10 +26,31 @@ describe("copilot", () => {
   });
 
   describe("capabilities.agents.convertFrontmatter()", () => {
+    it("includes repository instructions in custom subagents by default", () => {
+      expect(copilot.capabilities.agents.convertFrontmatter({ name: "reviewer" })).toHaveProperty(
+        "include-custom-instructions",
+        true
+      );
+    });
+
+    it("preserves an explicit repository-instruction opt-out", () => {
+      expect(
+        copilot.capabilities.agents.convertFrontmatter({
+          name: "reviewer",
+          "include-custom-instructions": false,
+        })
+      ).toHaveProperty("include-custom-instructions", false);
+    });
+
     it("preserves an explicitly selected agent model", () => {
       const fm = { name: "alexia", description: "Agent", model: "opus" };
       const result = copilot.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
+      expect(result).toEqual({
+        name: "alexia",
+        description: "Agent",
+        model: "opus",
+        "include-custom-instructions": true,
+      });
     });
 
     it("names an unnamed agent after its own file, whatever folders it sits in", () => {
@@ -38,7 +59,11 @@ describe("copilot", () => {
           { description: "Reviews code" },
           "team/reviews/code-reviewer.md"
         )
-      ).toStrictEqual({ name: "code-reviewer", description: "Reviews code" });
+      ).toStrictEqual({
+        name: "code-reviewer",
+        description: "Reviews code",
+        "include-custom-instructions": true,
+      });
     });
 
     it("drops only the trailing .md from the file it names an agent after", () => {
@@ -47,7 +72,11 @@ describe("copilot", () => {
           { description: "Helps" },
           "notes.md-helper.md"
         )
-      ).toStrictEqual({ name: "notes.md-helper", description: "Helps" });
+      ).toStrictEqual({
+        name: "notes.md-helper",
+        description: "Helps",
+        "include-custom-instructions": true,
+      });
     });
 
     it("leaves an agent unnamed when neither its frontmatter nor a file name gives one", () => {
@@ -56,13 +85,18 @@ describe("copilot", () => {
       ).toStrictEqual({
         name: undefined,
         description: "Helps",
+        "include-custom-instructions": true,
       });
     });
 
     it("drops a name that is not a string rather than writing it", () => {
       expect(
         copilot.capabilities.agents.convertFrontmatter({ name: 42, description: "Helps" }, "x.md")
-      ).toStrictEqual({ name: undefined, description: "Helps" });
+      ).toStrictEqual({
+        name: undefined,
+        description: "Helps",
+        "include-custom-instructions": true,
+      });
     });
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/build.unit.test.ts
index 356012722..e2ea4eda1 100644
--- a/cli/tests/contexts/tools/domain/profiles/copilot/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/build.unit.test.ts
@@ -7,6 +7,7 @@ import {
   buildCopilotFlatContract,
   buildCopilotMarketplaceContract,
 } from "../../../../../../src/contexts/tools/domain/profiles/copilot/build.js";
+import { parseFrontmatter } from "../../../../../../src/kernel/markdown.js";
 import { InMemoryFileAdapter } from "../../../../../helpers/ports/in-memory-file-adapter.js";
 
 // Built, not written literally: biome reads a string holding "${...}" as a lost template.
@@ -303,4 +304,19 @@ describe("buildCopilotFlatContract()", () => {
       transform?.("---\ndescription: Helps\n---\nBody.\n", "aidd-dev", "notes.md-helper.md")
     ).toBe("---\ndescription: 'Helps'\nname: 'aidd-dev-notes.md-helper'\n---\nBody.\n");
   });
+
+  it.each([true, false])(
+    "preserves repository instruction selection %s in flat agents",
+    (include) => {
+      const transform = supported(buildCopilotFlatContract().artifacts.agents).transform;
+      const result = transform?.(
+        `---\nname: reviewer\ninclude-custom-instructions: ${include}\n---\nReview.\n`,
+        "aidd-dev",
+        "reviewer.md"
+      );
+      expect(parseFrontmatter(result ?? "").frontmatter["include-custom-instructions"]).toBe(
+        include
+      );
+    }
+  );
 });
diff --git a/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts b/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts
index f7da326c8..e9a7d95e0 100644
--- a/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts
+++ b/cli/tests/contexts/translate/application/strategies/marketplace-build-strategy.codex.integration.test.ts
@@ -212,13 +212,13 @@ describe("CodexOutputStrategy", () => {
       }
     });
 
-    it("TOML files preserve explicit models and leave unrelated agents unpinned", async () => {
+    it("TOML files leave Claude selectors unpinned for native model inheritance", async () => {
       const fs = await makeSeededFsFromReal();
       const uc = makeUseCase(fs);
       await uc.execute({ sourceDir: REAL_FIXTURE_DIR, outDir: OUT_DIR, target: "codex" });
       for (const [plugin, agent, model] of [
-        ["aidd-dev", "reviewer", "opus"],
-        ["aidd-dev", "implementer", "sonnet"],
+        ["aidd-dev", "reviewer", undefined],
+        ["aidd-dev", "implementer", undefined],
         ["aidd-async-dev", "async-orchestrator", undefined],
       ]) {
         const content = fs.getFile(`${OUT_DIR}/plugins/${plugin}/codex-agents/${agent}.toml`) ?? "";
@@ -452,14 +452,14 @@ describe("CodexOutputStrategy", () => {
   });
 
   describe("explicit model preservation", () => {
-    it("fixture agent with model: opus keeps that literal model", async () => {
+    it("fixture agent with model: opus inherits the parent model", async () => {
       const fs = await makeSeededFsFromCodex();
       const uc = makeUseCase(fs);
       await uc.execute({ sourceDir: CODEX_FIXTURE_DIR, outDir: OUT_DIR, target: "codex" });
       const tomlContent =
         fs.getFile(`${OUT_DIR}/plugins/aidd-codex-fixture/codex-agents/test-agent.toml`) ?? "";
       const parsed = parseToml(tomlContent) as Record<string, unknown>;
-      expect(parsed.model).toBe("opus");
+      expect(parsed).not.toHaveProperty("model");
     });
   });
 });
diff --git a/cli/tests/e2e/agents.e2e.test.ts b/cli/tests/e2e/agents.e2e.test.ts
index 560a2436b..cf98d8d2b 100644
--- a/cli/tests/e2e/agents.e2e.test.ts
+++ b/cli/tests/e2e/agents.e2e.test.ts
@@ -75,6 +75,30 @@ const cases = [
 ] as const;
 
 describe.concurrent("explicit native agent installation", () => {
+  it.each(["marketplace", "flat"])("Codex %s translation omits Claude aliases", async (layout) => {
+    const box = await createTestEnv(`agents-codex-${layout}`);
+    try {
+      const source = join(REPOSITORY_ROOT, "cli", "tests", "fixtures", "framework-codex");
+      const output = join(box.tempDir, "translated");
+      await mkdir(output);
+      const result = await runCli(
+        ["translate", source, "--to", "codex", "--as", layout, "--out", output],
+        box.projectDir,
+        box.fakeHome
+      );
+      expect(result.exitCode, result.stderr).toBe(0);
+      const path =
+        layout === "flat"
+          ? join(output, ".codex", "agents", "aidd-codex-fixture-test-agent.toml")
+          : join(output, "plugins", "aidd-codex-fixture", "codex-agents", "test-agent.toml");
+      const agent = parseToml(await readFile(path, "utf8"));
+      expect(agent).not.toHaveProperty("model");
+      expect(agent.developer_instructions).toContain("# Test Agent");
+    } finally {
+      await box.cleanup();
+    }
+  });
+
   for (const [ide, provider, directory, suffix, expected, reviewModel] of cases) {
     it(`${ide} installs the four agents with ${provider} headers, then removes them`, async () => {
       const box = await createTestEnv(`agents-${ide}-${provider}`);
@@ -93,6 +117,7 @@ describe.concurrent("explicit native agent installation", () => {
           const fields =
             ide === "codex" ? parseToml(content) : parseFrontmatter(content).frontmatter;
           expect(fields).toMatchObject(role === "reviewer" ? reviewModel : expected);
+          if (ide === "copilot") expect(fields["include-custom-instructions"]).toBe(true);
           if (ide === "opencode") expect(fields.mode).toBe("subagent");
           else expect(fields.name).toBe(`aidd-dev-${role}`);
           expect(content).toContain("# Behavior");
diff --git a/cli/tests/golden/snapshots/framework-build/golden.json b/cli/tests/golden/snapshots/framework-build/golden.json
index 8c6df6dae..98ad398d6 100644
--- a/cli/tests/golden/snapshots/framework-build/golden.json
+++ b/cli/tests/golden/snapshots/framework-build/golden.json
@@ -293,9 +293,9 @@
     "plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md": "cacb673334d8947c3c252feaaf0ef50c269c06c5cf8f51b45663cbd42402e094",
     "plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md": "6f6cddd0893888c71b0aed5ecfe48217afe0eef10feec6415db433bfcc69f8e3",
     "plugins/aidd-dev/skills/00-sdlc/SKILL.md": "e961d919f13d1650d7c47dc0fa118f8cdce7d434c2ae31aa9c30a203463c86f4",
-    "plugins/aidd-dev/codex-agents/implementer.toml": "75989a5835faad8833ff50cac0dc18789d2ee18076595f121a3b663e16704156",
-    "plugins/aidd-dev/codex-agents/planner.toml": "b381250bb35e2db561d4a18725e6be7068198473232d094d2b76e840f381344b",
-    "plugins/aidd-dev/codex-agents/reviewer.toml": "678bdd2c9186dad0f185c63bbd2e5ff729e50b4160d460cdd16111723e771554",
+    "plugins/aidd-dev/codex-agents/implementer.toml": "d6b2739193ecc12b546f17a994af4e2949ccbea3f2560139b3bf7693fca9604d",
+    "plugins/aidd-dev/codex-agents/planner.toml": "347e72e5beb8d0b493618c2d03f37d765c10e407f3404539fa5dc822fd2fecad",
+    "plugins/aidd-dev/codex-agents/reviewer.toml": "9dd3b9e0420601fc35c287636a6553ef5e404689347313d05e53ec99f034011a",
     "plugins/aidd-dev/.codex-plugin/plugin.json": "20aed94921aed1aaa0dfcd83528601273582558f72ed33f23077605197dba94d",
     "plugins/aidd-context/skills/06-discovery/SKILL.md": "e057466afc4603a1fcac65db17f36d4d03c8403c6b2ed8b49abdcec43bc69aaf",
     "plugins/aidd-context/skills/06-discovery/actions/01-find-skill.md": "600caf7822017bfe75d40773e1673ada784227b98f5b88d4ba98a57822fa0dcf",
@@ -1378,9 +1378,9 @@
     ".codex/hooks.json": "f85805f8ed17f990b1d7a2e2f966cb47f46f9bdd21bc8911325df190b7784ea9",
     ".codex/hooks/aidd-context/update_memory.js": "140d7db788452f5f4c32316d522f595a36e06638b19a42d32e42a1a7324b7149",
     ".codex/agents/aidd-async-dev-async-orchestrator.toml": "8212b724fdacd2a20f35a2c11782c7d50b717b742f59f1a9ae08c0d831e42b4a",
-    ".codex/agents/aidd-dev-implementer.toml": "d1cb0353bb91cc5d0c5ffaada12b063c7d5491e94ea33eb08277783aa4c7f493",
-    ".codex/agents/aidd-dev-planner.toml": "2b37cea54f1da91c6fe2c781ada91580d36ff4656407cc4453d668bbb2c20f90",
-    ".codex/agents/aidd-dev-reviewer.toml": "7b86256d9b872d3358828a4aa74338b6d6056aced63e9b70cad88b548dc89dbd",
+    ".codex/agents/aidd-dev-implementer.toml": "666612f997989d9f0beffc0e3438f998ea937b48259407122347430e6af6ff28",
+    ".codex/agents/aidd-dev-planner.toml": "ca9ade7a153873d4dd9a633d41ae3850a11b927333abbe336ab18fe47fd28b56",
+    ".codex/agents/aidd-dev-reviewer.toml": "0d366279100adebbf10bb0976e9057e03a8c2889d323c218e01d64b5f5038e3a",
     ".agents/skills/aidd-vcs-04-issue-create/SKILL.md": "3983ed1c71124786fdf737ec5447637a31b1cc146eff43003978cec50c2ddc67",
     ".agents/skills/aidd-vcs-04-issue-create/evals/scenarios.json": "d113c62aae4867e425737948c39c9f687f56c3d37234eca345a2f65f1a234c30",
     ".agents/skills/aidd-vcs-04-issue-create/assets/CONTRIBUTING.md": "1372c7512c02c26e21643ae523a98d7c90ff92c03633532a8c417b4ca8d9e75f",

From d45ae427bed828685093c040c6f8f8b03267ca4a Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 12:28:08 +0800
Subject: [PATCH 42/73] fix(cli): preserve agent ownership across failures and
 concurrent commands

---
 .../agents/manage-agents-use-case.ts          | 126 ++++++++++-----
 .../framework/application/clean-use-case.ts   |  11 +-
 .../domain/ports/agent-installation-store.ts  |   2 +
 .../agent-installation-store-adapter.ts       |  40 ++++-
 ...manage-agents-use-case.integration.test.ts | 143 +++++++++++++++++-
 .../clean-opt-in-agents.integration.test.ts   |  40 ++++-
 ...allation-store-adapter.integration.test.ts |  42 ++++-
 cli/tests/e2e/agents-lifecycle.e2e.test.ts    |  70 +++++++++
 8 files changed, 427 insertions(+), 47 deletions(-)
 create mode 100644 cli/tests/e2e/agents-lifecycle.e2e.test.ts

diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
index 2b69d384a..dd438a97b 100644
--- a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -23,6 +23,11 @@ interface AgentTarget {
   host: AgentHost;
 }
 
+interface AgentChange {
+  path: string;
+  content: string | null;
+}
+
 export class ManageAgentsUseCase {
   constructor(
     private readonly fs: FileReader & FileWriter,
@@ -32,7 +37,6 @@ export class ManageAgentsUseCase {
   ) {}
 
   async install(options: AgentTarget & { provider: AgentProvider }): Promise<number> {
-    const installed = await this.load(options.projectRoot);
     const capability = this.capability(options.host);
     const entries = Object.entries(this.sources).map(([name, source]) => {
       const { frontmatter, body } = parseFrontmatter(source);
@@ -47,34 +51,84 @@ export class ManageAgentsUseCase {
         ),
       };
     });
-    for (const entry of entries)
-      await this.assertOwned(
-        options.projectRoot,
-        entry.path,
-        installed[options.host]?.[entry.name]
-      );
-    let written = 0;
-    const hashes = { ...installed[options.host] };
-    for (const { name, path, content } of entries) {
-      const hash = this.hasher.hash(content);
-      if (!(await this.fs.fileExists(path)) || !(await this.fs.readFileHash(path)).equals(hash)) {
-        await this.fs.writeFile(path, content);
-        written++;
+    return this.exclusively(options.projectRoot, async () => {
+      const installed = await this.load(options.projectRoot);
+      for (const entry of entries)
+        await this.assertOwned(
+          options.projectRoot,
+          entry.path,
+          installed[options.host]?.[entry.name]
+        );
+      installed[options.host] = {
+        ...installed[options.host],
+        ...Object.fromEntries(
+          entries.map(({ name, content }) => [name, this.hasher.hash(content)])
+        ),
+      };
+      return this.save(options.projectRoot, installed, entries);
+    });
+  }
+
+  private async exclusively<T>(root: string, action: () => Promise<T>): Promise<T> {
+    await assertProjectPathWithinRoot(this.fs, root, join(root, AGENT_INSTALLATIONS_PATH));
+    return this.store.withExclusiveAccess(root, action);
+  }
+
+  private async save(
+    root: string,
+    installed: AgentInstallations,
+    changes: readonly AgentChange[]
+  ): Promise<number> {
+    const previous: AgentChange[] = [];
+    try {
+      for (const change of changes) {
+        const content = (await this.fs.fileExists(change.path))
+          ? await this.fs.readFile(change.path)
+          : null;
+        if (content === change.content) continue;
+        previous.push({ path: change.path, content });
+        await this.write(change);
       }
-      hashes[name] = hash;
+      await this.store.save(root, installed);
+      return previous.length;
+    } catch (error) {
+      const restored = await Promise.allSettled(
+        previous.reverse().map(async (change) => {
+          const content = (await this.fs.fileExists(change.path))
+            ? await this.fs.readFile(change.path)
+            : null;
+          if (content !== change.content) await this.write(change);
+        })
+      );
+      const failures = restored.filter((result) => result.status === "rejected");
+      if (failures.length > 0)
+        throw new AggregateError(
+          [error, ...failures.map((result) => result.reason)],
+          "Agent update failed and rollback was incomplete. Preserve the registry and agent files before retrying."
+        );
+      throw error;
+    }
+  }
+
+  private async write({ path, content }: AgentChange): Promise<void> {
+    if (content !== null) await this.fs.writeFile(path, content);
+    else {
+      await this.fs.deleteFile(path);
+      if (await this.fs.fileExists(path)) throw new Error(`Could not remove agent: ${path}`);
     }
-    installed[options.host] = hashes;
-    await this.store.save(options.projectRoot, installed);
-    return written;
   }
 
   async remove(options: AgentTarget): Promise<number> {
-    const installed = await this.load(options.projectRoot);
-    const entries = await this.removable(options.projectRoot, installed, options.host);
-    const count = await this.delete(entries);
-    delete installed[options.host];
-    await this.store.save(options.projectRoot, installed);
-    return count;
+    return this.exclusively(options.projectRoot, async () => {
+      const installed = await this.load(options.projectRoot);
+      const entries = await this.removable(options.projectRoot, installed, options.host);
+      delete installed[options.host];
+      return this.save(
+        options.projectRoot,
+        installed,
+        entries.map((path) => ({ path, content: null }))
+      );
+    });
   }
 
   async preview(projectRoot: string): Promise<Array<{ toolId: AgentHost; fileCount: number }>> {
@@ -92,11 +146,17 @@ export class ManageAgentsUseCase {
     await this.removable(projectRoot, await this.load(projectRoot));
   }
 
-  async removeAll(projectRoot: string): Promise<number> {
-    const entries = await this.removable(projectRoot, await this.load(projectRoot));
-    const count = await this.delete(entries);
-    await this.store.save(projectRoot, {});
-    return count;
+  async removeAll(projectRoot: string, afterRemoval?: () => Promise<void>): Promise<number> {
+    return this.exclusively(projectRoot, async () => {
+      const entries = await this.removable(projectRoot, await this.load(projectRoot));
+      const count = await this.save(
+        projectRoot,
+        {},
+        entries.map((path) => ({ path, content: null }))
+      );
+      await afterRemoval?.();
+      return count;
+    });
   }
 
   private capability(host: AgentHost): AgentsCapability {
@@ -149,12 +209,4 @@ export class ManageAgentsUseCase {
     }
     return paths;
   }
-
-  private async delete(paths: readonly string[]): Promise<number> {
-    for (const path of paths) {
-      await this.fs.deleteFile(path);
-      if (await this.fs.fileExists(path)) throw new Error(`Could not remove agent: ${path}`);
-    }
-    return paths.length;
-  }
 }
diff --git a/cli/src/contexts/framework/application/clean-use-case.ts b/cli/src/contexts/framework/application/clean-use-case.ts
index aff83b1c0..dc7eb09fe 100644
--- a/cli/src/contexts/framework/application/clean-use-case.ts
+++ b/cli/src/contexts/framework/application/clean-use-case.ts
@@ -35,6 +35,7 @@ import type { NativeRegistrations } from "../domain/manifest/native-registration
 import type { Manifest } from "../domain/manifest.js";
 import { aiddGitignoreEntries } from "../domain/manifest-gitignore-entries.js";
 import type { InstalledPlugin } from "../domain/plugins/installed-plugin.js";
+import { AGENT_INSTALLATIONS_LOCK_PATH } from "../domain/ports/agent-installation-store.js";
 import type { ManifestRepository } from "../domain/ports/manifest-repository.js";
 import type { UserSourceReferences } from "../domain/ports/user-source-references.js";
 import type { ManageAgentsUseCase } from "./agents/manage-agents-use-case.js";
@@ -221,8 +222,9 @@ export class CleanUseCase {
     await this.purgeNativeCaches(home, undone);
     let deleted = await this.deleteAllToolFiles(manifest, options.projectRoot);
     deleted += await this.deleteMachineLocalFiles(manifest, options.projectRoot);
-    deleted += (await this.agents?.removeAll(options.projectRoot)) ?? 0;
-    await this.removeAiddState(options.projectRoot);
+    const removeState = () => this.removeAiddState(options.projectRoot);
+    if (this.agents) deleted += await this.agents.removeAll(options.projectRoot, removeState);
+    else await removeState();
     // Exactly what the pipeline added on install, never a subset of it.
     await this.gitignoreUseCase.remove(options.projectRoot, aiddGitignoreEntries(manifest));
     // One project-level decrement, only after the local projection has been cleaned successfully.
@@ -309,7 +311,10 @@ export class CleanUseCase {
 
     if (!(await this.fs.fileExists(aiddDir))) return;
     const remaining = await this.fs.listDirectory(aiddDir);
-    if (remaining.length === 0) {
+    if (
+      remaining.length === 0 &&
+      !(await this.fs.fileExists(join(projectRoot, AGENT_INSTALLATIONS_LOCK_PATH)))
+    ) {
       await this.fs.deleteDirectory(aiddDir);
       return;
     }
diff --git a/cli/src/contexts/framework/domain/ports/agent-installation-store.ts b/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
index 6144f6f92..268a8fa55 100644
--- a/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
+++ b/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
@@ -4,8 +4,10 @@ import type { AgentHost } from "../../../tools/domain/formats/agent-models.js";
 export type AgentInstallations = Partial<Record<AgentHost, Record<string, FileHash>>>;
 
 export interface AgentInstallationStore {
+  withExclusiveAccess<T>(projectRoot: string, action: () => Promise<T>): Promise<T>;
   load(projectRoot: string): Promise<AgentInstallations>;
   save(projectRoot: string, installations: AgentInstallations): Promise<void>;
 }
 
 export const AGENT_INSTALLATIONS_PATH = ".aidd/agents.json";
+export const AGENT_INSTALLATIONS_LOCK_PATH = `${AGENT_INSTALLATIONS_PATH}.lock`;
diff --git a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
index e5aba24b4..adf99fda5 100644
--- a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
+++ b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
@@ -1,9 +1,12 @@
-import { join } from "node:path";
+import { mkdir, rmdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { setTimeout as pause } from "node:timers/promises";
 import { FileHash } from "../../../kernel/file.js";
 import type { FileReader } from "../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../kernel/ports/file-writer.js";
 import { isAgentHost } from "../../tools/domain/formats/agent-models.js";
 import {
+  AGENT_INSTALLATIONS_LOCK_PATH,
   AGENT_INSTALLATIONS_PATH,
   type AgentInstallationStore,
   type AgentInstallations,
@@ -12,6 +15,41 @@ import {
 export class AgentInstallationStoreAdapter implements AgentInstallationStore {
   constructor(private readonly fs: FileReader & FileWriter) {}
 
+  async withExclusiveAccess<T>(projectRoot: string, action: () => Promise<T>): Promise<T> {
+    const lock = join(projectRoot, AGENT_INSTALLATIONS_LOCK_PATH);
+    const deadline = Date.now() + 30_000;
+    while (true) {
+      try {
+        await mkdir(dirname(lock), { recursive: true });
+        await mkdir(lock);
+        break;
+      } catch (error) {
+        if (!["EEXIST", "ENOENT"].includes((error as NodeJS.ErrnoException).code ?? ""))
+          throw error;
+        if (Date.now() >= deadline)
+          throw new Error(
+            `Agent ownership registry is busy: ${lock}. Retry after the other AIDD operation finishes; remove this lock only if that operation has stopped.`
+          );
+        await pause(50);
+      }
+    }
+    try {
+      return await action();
+    } finally {
+      await this.release(lock);
+    }
+  }
+
+  private async release(lock: string): Promise<void> {
+    await rmdir(lock);
+    try {
+      await rmdir(dirname(lock));
+    } catch (error) {
+      if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes((error as NodeJS.ErrnoException).code ?? ""))
+        throw error;
+    }
+  }
+
   async load(projectRoot: string): Promise<AgentInstallations> {
     const path = join(projectRoot, AGENT_INSTALLATIONS_PATH);
     if (!(await this.fs.fileExists(path))) return {};
diff --git a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
index 834d8c910..678fc1790 100644
--- a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
+++ b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ManageAgentsUseCase } from "../../../../../src/contexts/framework/application/agents/manage-agents-use-case.js";
 import { AgentInstallationStoreAdapter } from "../../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
 import "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
@@ -17,16 +17,152 @@ const sources = {
 describe("ManageAgentsUseCase", () => {
   let root: string;
   let manager: ManageAgentsUseCase;
+  let fs: FileAdapter;
+  let store: AgentInstallationStoreAdapter;
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), "aidd-agents-"));
     const hasher = new HasherAdapter();
-    const fs = new FileAdapter(hasher);
-    manager = new ManageAgentsUseCase(fs, new AgentInstallationStoreAdapter(fs), hasher, sources);
+    fs = new FileAdapter(hasher);
+    store = new AgentInstallationStoreAdapter(fs);
+    manager = new ManageAgentsUseCase(fs, store, hasher, sources);
   });
   afterEach(async () => {
+    vi.restoreAllMocks();
     await rm(root, { recursive: true, force: true });
   });
 
+  it("rolls back a new installation when ownership cannot be saved, then allows retry", async () => {
+    vi.spyOn(store, "save").mockRejectedValueOnce(new Error("registry refused"));
+    await expect(
+      manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+    ).rejects.toThrow("registry refused");
+    for (const name of Object.keys(sources))
+      await expect(readFile(join(root, `.codex/agents/${name}.toml`))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    expect(await manager.install({ projectRoot: root, host: "codex", provider: "openai" })).toBe(2);
+  });
+
+  it("restores the previous provider and ledger after a failed update", async () => {
+    await manager.install({ projectRoot: root, host: "opencode", provider: "openai" });
+    const ledger = await readFile(join(root, ".aidd/agents.json"), "utf8");
+    const contents = await Promise.all(
+      Object.keys(sources).map((name) =>
+        readFile(join(root, `.opencode/agents/${name}.md`), "utf8")
+      )
+    );
+    vi.spyOn(store, "save").mockRejectedValueOnce(new Error("registry refused"));
+    await expect(
+      manager.install({ projectRoot: root, host: "opencode", provider: "anthropic" })
+    ).rejects.toThrow("registry refused");
+    expect(await readFile(join(root, ".aidd/agents.json"), "utf8")).toBe(ledger);
+    expect(
+      await Promise.all(
+        Object.keys(sources).map((name) =>
+          readFile(join(root, `.opencode/agents/${name}.md`), "utf8")
+        )
+      )
+    ).toEqual(contents);
+    expect(
+      await manager.install({ projectRoot: root, host: "opencode", provider: "anthropic" })
+    ).toBe(2);
+  });
+
+  it("rolls back earlier files when a later native write fails", async () => {
+    const write = fs.writeFile.bind(fs);
+    vi.spyOn(fs, "writeFile")
+      .mockImplementationOnce(write)
+      .mockRejectedValueOnce(new Error("write refused"));
+    await expect(
+      manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+    ).rejects.toThrow("write refused");
+    await expect(
+      readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"))
+    ).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+    expect(await manager.install({ projectRoot: root, host: "codex", provider: "openai" })).toBe(2);
+  });
+
+  it("keeps the original error when a refused native write left the existing file intact", async () => {
+    await manager.install({ projectRoot: root, host: "opencode", provider: "openai" });
+    const failure = new Error("native directory is read-only");
+    vi.spyOn(fs, "writeFile").mockRejectedValue(failure);
+    await expect(
+      manager.install({ projectRoot: root, host: "opencode", provider: "anthropic" })
+    ).rejects.toBe(failure);
+    expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
+      "openai/gpt-6-luna"
+    );
+  });
+
+  it("reports an incomplete rollback instead of hiding a restoration failure", async () => {
+    vi.spyOn(store, "save").mockRejectedValueOnce(new Error("registry refused"));
+    vi.spyOn(fs, "deleteFile").mockResolvedValue();
+    const failed = manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    await expect(failed).rejects.toBeInstanceOf(AggregateError);
+    await expect(failed).rejects.toThrow("rollback was incomplete");
+  });
+
+  it.each(["remove", "removeAll"] as const)(
+    "restores agents when %s cannot save ownership",
+    async (method) => {
+      await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+      const ledger = await readFile(join(root, ".aidd/agents.json"), "utf8");
+      vi.spyOn(store, "save").mockRejectedValueOnce(new Error("registry refused"));
+      const remove = () =>
+        method === "remove"
+          ? manager.remove({ projectRoot: root, host: "codex" })
+          : manager.removeAll(root);
+      await expect(remove()).rejects.toThrow("registry refused");
+      expect(await readFile(join(root, ".aidd/agents.json"), "utf8")).toBe(ledger);
+      expect(await manager.install({ projectRoot: root, host: "codex", provider: "openai" })).toBe(
+        0
+      );
+      expect(await remove()).toBe(2);
+    }
+  );
+
+  it("records both IDEs during simultaneous installations", async () => {
+    await Promise.all([
+      manager.install({ projectRoot: root, host: "codex", provider: "openai" }),
+      manager.install({ projectRoot: root, host: "opencode", provider: "openai" }),
+    ]);
+    expect((await manager.preview(root)).map((tool) => tool.toolId).sort()).toEqual([
+      "codex",
+      "opencode",
+    ]);
+    expect(await manager.remove({ projectRoot: root, host: "codex" })).toBe(2);
+    expect(await manager.preview(root)).toEqual([{ toolId: "opencode", fileCount: 2 }]);
+    expect(await manager.remove({ projectRoot: root, host: "opencode" })).toBe(2);
+  });
+
+  it("keeps a concurrent installation registered when another IDE is removed", async () => {
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    await Promise.all([
+      manager.remove({ projectRoot: root, host: "codex" }),
+      manager.install({ projectRoot: root, host: "opencode", provider: "anthropic" }),
+    ]);
+    expect(await manager.preview(root)).toEqual([{ toolId: "opencode", fileCount: 2 }]);
+    expect(await manager.removeAll(root)).toBe(2);
+  });
+
+  it("serializes remove-all with installation even when the registry directory becomes empty", async () => {
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    await Promise.all([
+      manager.removeAll(root),
+      manager.install({ projectRoot: root, host: "opencode", provider: "mistral" }),
+    ]);
+    const remaining = await manager.preview(root);
+    const opencodeExists = await fs.fileExists(join(root, ".opencode/agents/aidd-dev-explorer.md"));
+    expect(opencodeExists).toBe(remaining.some(({ toolId }) => toolId === "opencode"));
+    expect(remaining.every(({ toolId }) => toolId === "opencode")).toBe(true);
+    await expect(readFile(join(root, ".aidd/agents.json.lock"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
   it("installs namespaced native Codex agents and records ownership", async () => {
     expect(await manager.install({ projectRoot: root, host: "codex", provider: "openai" })).toBe(2);
     const content = await readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "utf8");
@@ -118,6 +254,7 @@ describe("ManageAgentsUseCase", () => {
           manager.install({ projectRoot: root, host: "codex", provider: "openai" })
         ).rejects.toThrow("outside project");
         await rm(join(root, ".codex"));
+        await rm(join(root, ".aidd"), { recursive: true, force: true });
         await symlink(outside, join(root, ".aidd"));
         await expect(
           manager.install({ projectRoot: root, host: "codex", provider: "openai" })
diff --git a/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts b/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
index fc23e9c18..34605126e 100644
--- a/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
+++ b/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
@@ -1,7 +1,7 @@
-import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { access, lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ManageAgentsUseCase } from "../../../../../src/contexts/framework/application/agents/manage-agents-use-case.js";
 import { CleanUseCase } from "../../../../../src/contexts/framework/application/clean-use-case.js";
 import { GitignoreUseCase } from "../../../../../src/contexts/framework/application/gitignore-use-case.js";
@@ -30,6 +30,7 @@ describe("clean includes opt-in agents", () => {
     await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
   });
   afterEach(async () => {
+    vi.restoreAllMocks();
     await rm(root, { recursive: true, force: true });
   });
 
@@ -83,6 +84,41 @@ describe("clean includes opt-in agents", () => {
     expect(await readFile(join(link, "note.txt"), "utf8")).toBe("personal");
   });
 
+  it("holds the agent mutex throughout framework state cleanup before a waiting install proceeds", async () => {
+    const scanning = Promise.withResolvers<void>();
+    const finishScan = Promise.withResolvers<void>();
+    const list = fs.listDirectory.bind(fs);
+    vi.spyOn(fs, "listDirectory").mockImplementation(async (path) => {
+      if (path === join(root, ".aidd")) {
+        await access(join(root, ".aidd/agents.json.lock"));
+        scanning.resolve();
+        await finishScan.promise;
+      }
+      return list(path);
+    });
+    const cleaning = clean(Manifest.create()).execute({ projectRoot: root, force: true });
+    // Reject immediately if cleanup failed before reaching the gate.
+    await Promise.race([
+      scanning.promise,
+      cleaning.then(() => {
+        throw new Error("cleanup skipped the gate");
+      }),
+    ]);
+    const installing = manager.install({
+      projectRoot: root,
+      host: "opencode",
+      provider: "mistral",
+    });
+    finishScan.resolve();
+    await Promise.all([cleaning, installing]);
+    expect(await manager.preview(root)).toEqual([{ toolId: "opencode", fileCount: 1 }]);
+    expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
+      "mistral/mistral-small-2603#high"
+    );
+    await expect(access(join(root, ".codex/agents/aidd-dev-explorer.toml"))).rejects.toThrow();
+    await expect(access(join(root, ".aidd/agents.json.lock"))).rejects.toThrow();
+  });
+
   it("counts agents once alongside framework files and other opted-in hosts", async () => {
     const manifest = Manifest.create();
     manifest.addTool("codex", "1.0.0", [
diff --git a/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts b/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
index fd1b9d353..1a0060990 100644
--- a/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
+++ b/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { AgentInstallationStoreAdapter } from "../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
 import { FileHash } from "../../../../src/kernel/file.js";
 import { FileAdapter } from "../../../../src/runtime/filesystem/file-adapter.js";
@@ -15,9 +15,49 @@ describe("AgentInstallationStoreAdapter", () => {
     store = new AgentInstallationStoreAdapter(new FileAdapter(new HasherAdapter()));
   });
   afterEach(async () => {
+    vi.restoreAllMocks();
     await rm(root, { recursive: true, force: true });
   });
 
+  it("releases exclusive access after a failed operation", async () => {
+    await expect(
+      store.withExclusiveAccess(root, async () => {
+        throw new Error("operation refused");
+      })
+    ).rejects.toThrow("operation refused");
+    expect(await store.withExclusiveAccess(root, async () => 42)).toBe(42);
+    await expect(readFile(join(root, ".aidd/agents.json.lock"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it("waits for a competing writer before reading ownership", async () => {
+    const other = new AgentInstallationStoreAdapter(new FileAdapter(new HasherAdapter()));
+    const first = { codex: { "aidd-dev-explorer": new FileHash("a".repeat(32)) } };
+    const second = { "aidd-dev-reviewer": new FileHash("b".repeat(32)) };
+    await Promise.all([
+      store.withExclusiveAccess(root, async () =>
+        store.save(root, { ...(await store.load(root)), ...first })
+      ),
+      other.withExclusiveAccess(root, async () =>
+        other.save(root, { ...(await other.load(root)), opencode: second })
+      ),
+    ]);
+    expect(await store.load(root)).toEqual({ ...first, opencode: second });
+  });
+
+  it("leaves a held lock intact and reports how to recover after timeout", async () => {
+    const lock = join(root, ".aidd/agents.json.lock");
+    await mkdir(lock, { recursive: true });
+    vi.spyOn(Date, "now").mockReturnValueOnce(0).mockReturnValue(30_001);
+    const action = vi.fn();
+    await expect(store.withExclusiveAccess(root, action)).rejects.toThrow(
+      "remove this lock only if that operation has stopped"
+    );
+    expect(action).not.toHaveBeenCalled();
+    await expect(mkdir(lock)).rejects.toMatchObject({ code: "EEXIST" });
+  });
+
   it("round trips typed hashes for several hosts and removes an empty ledger", async () => {
     expect(await store.load(root)).toEqual({});
     const expected = {
diff --git a/cli/tests/e2e/agents-lifecycle.e2e.test.ts b/cli/tests/e2e/agents-lifecycle.e2e.test.ts
new file mode 100644
index 000000000..0052ba8e3
--- /dev/null
+++ b/cli/tests/e2e/agents-lifecycle.e2e.test.ts
@@ -0,0 +1,70 @@
+import { access, chmod, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createTestEnv, runCli } from "./helpers.js";
+
+describe("agent ownership across CLI processes", () => {
+  it("retains both concurrent installations and removes only the selected IDE", async () => {
+    const box = await createTestEnv("agents-concurrent");
+    const run = (args: string[]) => runCli(args, box.projectDir, box.fakeHome);
+    try {
+      const installed = await Promise.all([
+        run(["agents", "install", "--provider", "openai", "--ide", "codex"]),
+        run(["agents", "install", "--provider", "mistral", "--ide", "opencode"]),
+      ]);
+      for (const result of installed) expect(result.exitCode, result.stderr).toBe(0);
+      const ledger = () =>
+        readFile(join(box.projectDir, ".aidd/agents.json"), "utf8").then(JSON.parse);
+      expect(Object.keys(await ledger()).sort()).toEqual(["codex", "opencode"]);
+      const removed = await run(["agents", "remove", "--ide", "codex"]);
+      expect(removed.exitCode, removed.stderr).toBe(0);
+      expect(Object.keys(await ledger())).toEqual(["opencode"]);
+      for (const role of ["explorer", "executor", "validator", "reviewer"]) {
+        await access(join(box.projectDir, `.opencode/agents/aidd-dev-${role}.md`));
+        await expect(
+          access(join(box.projectDir, `.codex/agents/aidd-dev-${role}.toml`))
+        ).rejects.toThrow();
+      }
+      const cleaned = await run(["clean", "--force"]);
+      expect(cleaned.exitCode, cleaned.stderr).toBe(0);
+      for (const role of ["explorer", "executor", "validator", "reviewer"])
+        await expect(
+          access(join(box.projectDir, `.opencode/agents/aidd-dev-${role}.md`))
+        ).rejects.toThrow();
+      await expect(ledger()).rejects.toMatchObject({ code: "ENOENT" });
+    } finally {
+      await box.cleanup();
+    }
+  });
+
+  it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
+    "leaves no agents when the registry directory refuses writes, then allows retry",
+    async () => {
+      const box = await createTestEnv("agents-registry-refused");
+      const directory = join(box.projectDir, ".aidd");
+      const run = () =>
+        runCli(
+          ["agents", "install", "--provider", "openai", "--ide", "codex"],
+          box.projectDir,
+          box.fakeHome
+        );
+      try {
+        await mkdir(directory);
+        await chmod(directory, 0o555);
+        const failed = await run();
+        expect(failed.exitCode).toBe(1);
+        for (const role of ["explorer", "executor", "validator", "reviewer"])
+          await expect(
+            access(join(box.projectDir, `.codex/agents/aidd-dev-${role}.toml`))
+          ).rejects.toThrow();
+        await chmod(directory, 0o755);
+        const retried = await run();
+        expect(retried.exitCode, retried.stderr).toBe(0);
+        await access(join(box.projectDir, ".aidd/agents.json"));
+      } finally {
+        await chmod(directory, 0o755);
+        await box.cleanup();
+      }
+    }
+  );
+});

From eca240638ea37f75f59855a8bfcb14e0883974bb Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 12:30:02 +0800
Subject: [PATCH 43/73] docs: clarify subagent recovery and Small 4 model
 identity

---
 .../tasks/2026_10/2026_10_14_sub_agents/verification.md   | 8 ++++++++
 docs/SUBAGENTS.md                                         | 6 +++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 912e4c56c..52a56c510 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -18,6 +18,14 @@ The four agents are bundled with the CLI, outside plugins. Explicit installation
 - **CI build:** the completed run on `78344131` measured 697.0 KB after merging `next` at `ae8705f7`, versus 694.7 KB on the branch. Nine checks failed from the same 695 KB limit. Dependencies and build settings match; the merge adds the daily telemetry ledger and bounded reports. The budget is now 705 KB, with 1.1% headroom on that measured merge; the next CI run must confirm it.
 - **Limits:** no authenticated inference establishes effective runtime model selection for this candidate.
 
+## Review fixes, 2026-10-16
+
+- **Native headers:** Codex translation drops Claude shorthand selectors; Copilot custom agents include repository instructions unless explicitly disabled.
+- **Ownership:** installation, updates and removal restore native files after a handled failure. Concurrent mutations serialize across CLI processes; framework cleanup holds the same lock until state removal finishes.
+- **Regression evidence:** 36 lifecycle integration tests pass. Five independent mutations disable model filtering, instruction injection, rollback, serialization or cleanup coordination; each makes its named test fail, and restored code passes.
+- **Checks:** normal commit hooks pass, including 494 script tests, 168 architecture assertions, types and lint. Bundle: 697.7 KB against 705 KB.
+- **Limits:** abrupt process termination can require recovery; no new authenticated model inference was performed.
+
 ## Earlier runtime evidence
 
 The runtime probes below describe earlier candidates. Their traces and hashes predate the CLI-installed model defaults and the latest simplified agent bodies.
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index b0339d4a6..0e7aa80ef 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -70,8 +70,8 @@ The other IDEs' agents remain installed. Installation and removal refuse changes
 
 ## 🚧 Beta limitations
 
-- **Copilot:** installed custom subagents currently lack `include-custom-instructions: true`, required to receive repository instructions such as `AGENTS.md`. [Native contract](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#repository-custom-instructions-for-subagents), checked 2026-10-16.
-- **Ownership registry:** run installation and removal sequentially. Concurrent commands can lose ownership records; a failed registry write can leave files requiring manual recovery.
+- **Runtime selection:** verify the host actually uses the configured model and effort during your trial.
+- **Interrupted command:** inspect the native files and registry before clearing `.aidd/agents.json.lock`; confirm no installation or removal is still running. Handled write failures restore the previous agent files.
 
 ## 📝 Share a trial
 
@@ -89,7 +89,7 @@ Copy one report per trial:
 
 ## 💡 Model notes
 
-Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`.
+Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`. [Mistral Small 4](https://docs.mistral.ai/models/mistral-small-4-0-26-03) uses the API ID `mistral-small-2603`, checked 2026-10-16.
 
 Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
 

From 79d1ad7a2ab5f56ba25c5fef0f4bf617930e5d9d Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 12:40:26 +0800
Subject: [PATCH 44/73] fix(cli): align bundle budget with the current next
 merge

---
 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md | 3 ++-
 cli/package.json                                              | 2 +-
 cli/scripts/check-bundle-size.mjs                             | 2 ++
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index 52a56c510..f498fc072 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -23,7 +23,8 @@ The four agents are bundled with the CLI, outside plugins. Explicit installation
 - **Native headers:** Codex translation drops Claude shorthand selectors; Copilot custom agents include repository instructions unless explicitly disabled.
 - **Ownership:** installation, updates and removal restore native files after a handled failure. Concurrent mutations serialize across CLI processes; framework cleanup holds the same lock until state removal finishes.
 - **Regression evidence:** 36 lifecycle integration tests pass. Five independent mutations disable model filtering, instruction injection, rollback, serialization or cleanup coordination; each makes its named test fail, and restored code passes.
-- **Checks:** normal commit hooks pass, including 494 script tests, 168 architecture assertions, types and lint. Bundle: 697.7 KB against 705 KB.
+- **Checks:** normal commit hooks pass, including 494 script tests, 168 architecture assertions, types and lint. The full CLI suite passes 6,620 tests, one skipped.
+- **CI merge:** the bundle reaches 706.36 KB with `next` at `7084a88c`, reproduced locally. Telemetry code on `next` adds 8,839 bytes over the 697.73 KB branch. The reviewed budget is 715 KB, with 1.2% measured headroom.
 - **Limits:** abrupt process termination can require recovery; no new authenticated model inference was performed.
 
 ## Earlier runtime evidence
diff --git a/cli/package.json b/cli/package.json
index 7bd5029ea..f0e87e68b 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "packageManager": "pnpm@12.3.4",
-  "bundleBudgetKB": 705,
+  "bundleBudgetKB": 715,
   "scripts": {
     "build": "tsup && node scripts/check-bundle-size.mjs",
     "build:check-size": "node scripts/check-bundle-size.mjs",
diff --git a/cli/scripts/check-bundle-size.mjs b/cli/scripts/check-bundle-size.mjs
index 0c30c7ced..dfeb6a29f 100644
--- a/cli/scripts/check-bundle-size.mjs
+++ b/cli/scripts/check-bundle-size.mjs
@@ -45,6 +45,8 @@ const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
 // the 675.3 KB above); 2.1% measured headroom.
 // 705 KB: 697.0 KB, optional native agents and model policy measured on #1027's CI merge
 // with next ae8705f7; 1.1% headroom. The branch alone measured 694.7 KB.
+// 715 KB: 706.36 KB, #1027 merge 49e5cae4 with next 7084a88c after agent lifecycle fixes;
+// next's telemetry filtering adds 8,839 bytes over the 697.73 KB branch; 1.2% headroom.
 const budgetKB = pkg.bundleBudgetKB ?? 500;
 const budgetBytes = budgetKB * 1024;
 

From 4e5fc7bc9f0661dafc695ba92d326534ad14f8c8 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 22:24:14 +0800
Subject: [PATCH 45/73] fix(cli): preserve dangling links when managing agents

---
 .../agents/manage-agents-use-case.ts          |  2 +-
 .../agent-installation-store-adapter.ts       |  2 +-
 cli/src/kernel/ports/file-reader.ts           |  2 +-
 cli/src/runtime/filesystem/file-adapter.ts    | 16 ++++--
 ...manage-agents-use-case.integration.test.ts | 49 ++++++++++++++++++-
 ...allation-store-adapter.integration.test.ts | 14 +++++-
 cli/tests/e2e/agents-lifecycle.e2e.test.ts    | 35 ++++++++++++-
 7 files changed, 110 insertions(+), 10 deletions(-)

diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
index dd438a97b..a64d65883 100644
--- a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -186,7 +186,7 @@ export class ManageAgentsUseCase {
     expected: ReturnType<Hasher["hash"]> | undefined
   ): Promise<void> {
     await assertProjectPathWithinRoot(this.fs, root, path);
-    if (!(await this.fs.fileExists(path))) return;
+    if (!(await this.fs.fileExists(path, false))) return;
     if (expected === undefined) throw new Error(`Agent file is not owned by AIDD: ${path}`);
     if (!(await this.fs.readFileHash(path)).equals(expected))
       throw new Error(`Agent file was modified; preserve or move it before continuing: ${path}`);
diff --git a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
index adf99fda5..edbf80c2a 100644
--- a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
+++ b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
@@ -52,7 +52,7 @@ export class AgentInstallationStoreAdapter implements AgentInstallationStore {
 
   async load(projectRoot: string): Promise<AgentInstallations> {
     const path = join(projectRoot, AGENT_INSTALLATIONS_PATH);
-    if (!(await this.fs.fileExists(path))) return {};
+    if (!(await this.fs.fileExists(path, false))) return {};
     const parsed: unknown = JSON.parse(await this.fs.readFile(path));
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
       throw new Error(`Invalid agent ownership file: ${path}`);
diff --git a/cli/src/kernel/ports/file-reader.ts b/cli/src/kernel/ports/file-reader.ts
index 5f673d041..3df1102ea 100644
--- a/cli/src/kernel/ports/file-reader.ts
+++ b/cli/src/kernel/ports/file-reader.ts
@@ -6,7 +6,7 @@ export interface FileReader {
    * these paths are compared against profile and manifest entries, which use `/` on every
    * platform, so Windows' native separator must never reach a caller. */
   listDirectory(path: string): Promise<string[]>;
-  fileExists(path: string): Promise<boolean>;
+  fileExists(path: string, followSymlinks?: boolean): Promise<boolean>;
   readFileHash(path: string): Promise<FileHash>;
   listFilesRecursive(dirPath: string): Promise<string[]>;
 
diff --git a/cli/src/runtime/filesystem/file-adapter.ts b/cli/src/runtime/filesystem/file-adapter.ts
index 0e5ebbdd2..84c01d5df 100644
--- a/cli/src/runtime/filesystem/file-adapter.ts
+++ b/cli/src/runtime/filesystem/file-adapter.ts
@@ -1,5 +1,15 @@
 import { constants } from "node:fs";
-import { access, mkdir, readdir, readFile, realpath, rm, rmdir, stat } from "node:fs/promises";
+import {
+  access,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  rm,
+  rmdir,
+  stat,
+} from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { FileMerger } from "../../contexts/tools/domain/ports/file-merger.js";
 import { JsonParseError } from "../../kernel/errors.js";
@@ -103,9 +113,9 @@ export class FileAdapter implements FileReader, FileWriter, FileMerger {
     }
   }
 
-  async fileExists(path: string): Promise<boolean> {
+  async fileExists(path: string, followSymlinks = true): Promise<boolean> {
     try {
-      await stat(path);
+      await (followSymlinks ? stat(path) : lstat(path));
       return true;
     } catch {
       return false;
diff --git a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
index 678fc1790..b5a2e56e4 100644
--- a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
+++ b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -212,6 +212,53 @@ describe("ManageAgentsUseCase", () => {
     });
   });
 
+  it.skipIf(process.platform === "win32")(
+    "preserves a dangling personal agent symlink before writing any agent",
+    async () => {
+      const path = join(root, ".codex/agents/aidd-dev-reviewer.toml");
+      const target = join(root, "personal.toml");
+      await mkdir(join(root, ".codex/agents"), { recursive: true });
+      await symlink(target, path);
+      expect(await fs.fileExists(path)).toBe(false);
+      expect(await fs.fileExists(path, false)).toBe(true);
+      await expect(
+        manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+      ).rejects.toThrow("not owned");
+      expect(await readlink(path)).toBe(target);
+      await expect(
+        readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"))
+      ).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    }
+  );
+
+  it.skipIf(process.platform === "win32").each(["install", "remove", "removeAll"] as const)(
+    "refuses %s when an owned agent becomes a dangling symlink",
+    async (operation) => {
+      await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+      const path = join(root, ".codex/agents/aidd-dev-reviewer.toml");
+      const target = join(root, "personal.toml");
+      const ledger = await readFile(join(root, ".aidd/agents.json"), "utf8");
+      const explorer = await readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "utf8");
+      await rm(path);
+      await symlink(target, path);
+      const change =
+        operation === "install"
+          ? manager.install({ projectRoot: root, host: "codex", provider: "openai" })
+          : operation === "remove"
+            ? manager.remove({ projectRoot: root, host: "codex" })
+            : manager.removeAll(root);
+      await expect(change).rejects.toMatchObject({ code: "ENOENT" });
+      expect(await readlink(path)).toBe(target);
+      expect(await readFile(join(root, ".aidd/agents.json"), "utf8")).toBe(ledger);
+      expect(await readFile(join(root, ".codex/agents/aidd-dev-explorer.toml"), "utf8")).toBe(
+        explorer
+      );
+    }
+  );
+
   it("removes owned agents, tolerates missing files, and keeps personal agents", async () => {
     await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
     await rm(join(root, ".codex/agents/aidd-dev-reviewer.toml"));
diff --git a/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts b/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
index 1a0060990..329a98349 100644
--- a/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
+++ b/cli/tests/contexts/framework/infrastructure/agent-installation-store-adapter.integration.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -72,6 +72,18 @@ describe("AgentInstallationStoreAdapter", () => {
     });
   });
 
+  it.skipIf(process.platform === "win32")(
+    "refuses a dangling registry symlink instead of treating it as an empty registry",
+    async () => {
+      const path = join(root, ".aidd/agents.json");
+      const target = join(root, "personal-registry.json");
+      await mkdir(join(root, ".aidd"));
+      await symlink(target, path);
+      await expect(store.load(root)).rejects.toMatchObject({ code: "ENOENT" });
+      expect(await readlink(path)).toBe(target);
+    }
+  );
+
   it.each([
     "null",
     "[]",
diff --git a/cli/tests/e2e/agents-lifecycle.e2e.test.ts b/cli/tests/e2e/agents-lifecycle.e2e.test.ts
index 0052ba8e3..30b58c366 100644
--- a/cli/tests/e2e/agents-lifecycle.e2e.test.ts
+++ b/cli/tests/e2e/agents-lifecycle.e2e.test.ts
@@ -1,9 +1,40 @@
-import { access, chmod, mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { access, chmod, mkdir, readFile, readlink, symlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { createTestEnv, runCli } from "./helpers.js";
 
 describe("agent ownership across CLI processes", () => {
+  it
+    .skipIf(process.platform === "win32")
+    .each([".codex/agents/aidd-dev-reviewer.toml", ".aidd/agents.json"])(
+    "refuses a dangling personal symlink at %s before writing agents",
+    async (relativePath) => {
+      const box = await createTestEnv("agents-dangling-symlink");
+      const path = join(box.projectDir, relativePath);
+      const target = join(box.projectDir, "personal-missing-file");
+      try {
+        await mkdir(dirname(path), { recursive: true });
+        await symlink(target, path);
+        const failed = await runCli(
+          ["agents", "install", "--provider", "openai", "--ide", "codex"],
+          box.projectDir,
+          box.fakeHome
+        );
+        expect(failed.exitCode).toBe(1);
+        expect(await readlink(path)).toBe(target);
+        await expect(
+          access(join(box.projectDir, ".codex/agents/aidd-dev-explorer.toml"))
+        ).rejects.toMatchObject({ code: "ENOENT" });
+        if (relativePath !== ".aidd/agents.json")
+          await expect(access(join(box.projectDir, ".aidd/agents.json"))).rejects.toMatchObject({
+            code: "ENOENT",
+          });
+      } finally {
+        await box.cleanup();
+      }
+    }
+  );
+
   it("retains both concurrent installations and removes only the selected IDE", async () => {
     const box = await createTestEnv("agents-concurrent");
     const run = (args: string[]) => runCli(args, box.projectDir, box.fakeHome);

From c2c9a7846f425af38f9d10169a65ec23fdb7cb54 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Fri, 16 Oct 2026 22:25:20 +0800
Subject: [PATCH 46/73] fix(framework): align agent generation and review
 guidance

---
 .../skills/06-agent-generate/references/tool-paths.md         | 4 +++-
 .../aidd-dev/skills/05-review/references/quality-checklist.md | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
index ad9a0896d..41051f611 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
@@ -23,9 +23,11 @@ The canonical agent carries `name` and `description`. Emit those a row accepts,
 | Claude Code    | `name`, `description`, optional `model`, `effort`, `color`, `tools` |
 | Cursor         | `name`, `description`, optional `model`, `readonly`, `is_background` |
 | OpenCode V2    | `description`, `mode: subagent`, optional `model` as `provider/model#variant`, `permissions` |
-| GitHub Copilot | `name`, `description`, optional `model`, `reasoningEffort`, `tools` |
+| GitHub Copilot | `name`, `description`, optional `model`, `reasoningEffort`, `tools`, `include-custom-instructions` |
 | Codex CLI      | `name`, `description`, optional `model`, `model_reasoning_effort` |
 
+For Copilot agents that rely on repository instructions, set `include-custom-instructions: true` unless the user explicitly opts out.
+
 Native fields checked 2026-10-16: [Claude](https://code.claude.com/docs/en/sub-agents#frontmatter-reference), [Cursor](https://cursor.com/docs/subagents#file-format), [OpenCode V2](https://opencode.ai/v2/docs/agents#model), [Copilot](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agent-frontmatter-fields), [Codex](https://developers.openai.com/codex/subagents#custom-agent-file-schema).
 
 ## Codex TOML conversion
diff --git a/plugins/aidd-dev/skills/05-review/references/quality-checklist.md b/plugins/aidd-dev/skills/05-review/references/quality-checklist.md
index 7bf417ae8..657b142bd 100644
--- a/plugins/aidd-dev/skills/05-review/references/quality-checklist.md
+++ b/plugins/aidd-dev/skills/05-review/references/quality-checklist.md
@@ -1,6 +1,6 @@
 # Quality checklist
 
-Apply relevant items alongside project review rules; justify non-applicable items.
+Apply relevant items alongside project review rules.
 
 - [ ] **Duplication:** each fact or responsibility has one canonical home.
 - [ ] **Consistency:** components, names, documentation, and project conventions agree.

From d7d89e5fef109de77805c14c3775347e6ff6ad44 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 20 Oct 2026 12:02:49 +0800
Subject: [PATCH 47/73] feat(framework): install AIDD agents globally on reload

make reload now installs the AIDD agents into the global Claude, Codex and OpenCode agent directories from the built local CLI, overwriting only the generated files.
---
 docs/SUBAGENTS.md                  |  2 +-
 scripts/__tests__/dev-sync.test.js | 35 +++++++++++++++++++++++-
 scripts/dev-sync.sh                | 43 +++++++++++++++++++++++++++++-
 3 files changed, 77 insertions(+), 3 deletions(-)

diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 0e7aa80ef..0731d0497 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -58,7 +58,7 @@ Use host dispatch records to identify the agent and actual model, effort, and ti
 
 ## 🔄 Update or remove
 
-After updating the CLI, rerun the install command to refresh unmodified agents. Plugins, `sync`, and `make reload` do not install or refresh this add-on.
+After updating the CLI, rerun the install command to refresh unmodified agents. Plugins and `sync` do not install or refresh this add-on. For framework development, `make reload` installs the agents globally for Claude Code (Anthropic), Codex (OpenAI), and OpenCode (`OPENCODE_AGENT_PROVIDER`, default `anthropic`), overwriting same-named global agent files.
 
 To remove only one IDE's agents from the current project:
 
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 88709f9f9..fcd0e2994 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -815,7 +815,40 @@ for (const override of ["CLAUDE_CONFIG_DIR", "CLAUDE_INSTRUCTIONS"]) {
   });
 }
 
-test("Codex reload leaves opted-in and personal agents unchanged", () => {
+test("reload with a built CLI installs agents globally and keeps other agents", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-global-agents-"));
+  try {
+    const fakeBin = join(root, "bin"), home = join(root, "home");
+    mkdirSync(fakeBin);
+    const source = fixture(home);
+    mkdirSync(join(source, "cli/dist"), { recursive: true });
+    writeFileSync(join(source, "cli/dist/cli.js"), String.raw`
+const { mkdirSync, writeFileSync } = require("node:fs");
+const args = process.argv.slice(2);
+if (args[0] !== "agents") { mkdirSync(args[args.indexOf("--out") + 1] + "/.opencode/skills/aidd-dev-01-plan", { recursive: true }); writeFileSync(args[args.indexOf("--out") + 1] + "/.opencode/skills/aidd-dev-01-plan/SKILL.md", "skill\n"); process.exit(0); }
+const ide = args[args.indexOf("--ide") + 1], provider = args[args.indexOf("--provider") + 1];
+const [dir, ext] = { "claude-code": [".claude", "md"], codex: [".codex", "toml"], opencode: [".opencode", "md"] }[ide];
+mkdirSync(dir + "/agents", { recursive: true });
+writeFileSync(dir + "/agents/aidd-dev-executor." + ext, ide + " " + provider + "\n");
+`);
+    for (const host of ["claude", "codex", "opencode"]) executable(join(fakeBin, host), "exit 0");
+    const dirs = { claude: ".claude/agents", codex: ".codex/agents", opencode: ".config/opencode/agents" };
+    for (const dir of Object.values(dirs)) {
+      mkdirSync(join(home, dir), { recursive: true });
+      writeFileSync(join(home, dir, "personal.md"), "keep\n");
+    }
+    writeFileSync(join(home, dirs.codex, "aidd-dev-executor.toml"), "old\n");
+    const result = runSync(fakeBin, home, [], { OPENCODE_AGENT_PROVIDER: "mistral" });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /global agents\s+claude-code:ok codex:ok opencode:ok/);
+    assert.equal(readFileSync(join(home, dirs.claude, "aidd-dev-executor.md"), "utf8"), "claude-code anthropic\n");
+    assert.equal(readFileSync(join(home, dirs.codex, "aidd-dev-executor.toml"), "utf8"), "codex openai\n");
+    assert.equal(readFileSync(join(home, dirs.opencode, "aidd-dev-executor.md"), "utf8"), "opencode mistral\n");
+    for (const dir of Object.values(dirs)) assert.equal(readFileSync(join(home, dir, "personal.md"), "utf8"), "keep\n");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("Codex reload without a built CLI leaves agents unchanged", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-personal-"));
   try {
     const fakeBin = join(root, "bin"), home = join(root, "home");
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index d0862da8e..7ae5390b5 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -7,7 +7,12 @@
 # whose CLI is absent is skipped, and the first run needs network. A managed OpenCode host
 # exposes `aidd-opencode-reload` instead, and that helper decides which checkout may load.
 #
-# Optional agents are installed separately with `aidd agents install`; reload leaves them alone.
+# Agents: with a built local CLI, reload installs the AIDD agents globally for Claude, Codex and
+# local OpenCode, overwriting only the files that install generates; other agents stay untouched.
+# Global agent directories checked 2026-10-20:
+# https://code.claude.com/docs/en/sub-agents
+# https://developers.openai.com/codex/subagents
+# https://opencode.ai/docs/agents
 # Global rules: sync only the Agents section in the managed block, preserving personal
 # rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
 # Paths honor native home/cache overrides; explicit task paths take precedence.
@@ -38,6 +43,10 @@ CODEX_CACHE="${CODEX_CACHE:-${CODEX_HOME:-$HOME/.codex}/plugins/cache}"
 CLAUDE_CACHE="${CLAUDE_CACHE:-${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/cache}"
 OPENCODE_SKILLS="${OPENCODE_SKILLS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills}"
 CURSOR_PLUGINS="${CURSOR_PLUGINS:-$HOME/.cursor/plugins/local}"
+CLAUDE_AGENTS="${CLAUDE_AGENTS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents}"
+CODEX_AGENTS="${CODEX_AGENTS:-${CODEX_HOME:-$HOME/.codex}/agents}"
+OPENCODE_AGENTS="${OPENCODE_AGENTS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/agents}"
+OPENCODE_AGENT_PROVIDER="${OPENCODE_AGENT_PROVIDER:-anthropic}"  # openai, anthropic or mistral
 CODEX_INSTRUCTIONS="${CODEX_INSTRUCTIONS:-${CODEX_HOME:-$HOME/.codex}/AGENTS.md}"
 CLAUDE_INSTRUCTIONS="${CLAUDE_INSTRUCTIONS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md}"
 OPENCODE_INSTRUCTIONS="${OPENCODE_INSTRUCTIONS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md}"
@@ -120,6 +129,19 @@ sync_opencode_skills() {
   done
 }
 
+install_global_agents() {
+  # Generate the project-scoped agents in a staging root, then copy exactly those files globally.
+  local ide="$1" provider="$2" native_dir="$3" destination="$4" stage file
+  local -a files
+  stage="$BUILD/agents/$ide"
+  rm -rf "$stage"; mkdir -p "$stage"
+  (cd "$stage" && node "$FW/cli/dist/cli.js" agents install --ide "$ide" --provider "$provider" >/dev/null) || return 1
+  files=("$stage/$native_dir/agents/"*)
+  [ "${#files[@]}" -gt 0 ] || { echo "no agents generated for $ide" >&2; return 1; }
+  mkdir -p "$destination"
+  for file in "${files[@]}"; do cp "$file" "$destination/"; done
+}
+
 register_marketplace() {
   case "$1" in
     # Codex needs the native .codex-plugin tree.
@@ -254,6 +276,25 @@ if [ "$HAVE_CURSOR" = 1 ]; then
   echo "plugins:ok (requires local plugin imports)"
 fi
 
+if [ -f "$FW/cli/dist/cli.js" ]; then
+  agent_hosts=()
+  [ "$HAVE_CLAUDE" = 0 ] || agent_hosts+=("claude-code anthropic .claude $CLAUDE_AGENTS")
+  [ "$HAVE_CODEX" = 0 ] || agent_hosts+=("codex openai .codex $CODEX_AGENTS")
+  if [ "$HAVE_OPENCODE" = 1 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
+    agent_hosts+=("opencode $OPENCODE_AGENT_PROVIDER .opencode $OPENCODE_AGENTS")
+  fi
+  if [ "${#agent_hosts[@]}" -gt 0 ]; then
+    printf '%-22s' "global agents"
+    for entry in "${agent_hosts[@]}"; do
+      read -r ide provider native_dir destination <<<"$entry"
+      install_global_agents "$ide" "$provider" "$native_dir" "$destination" ||
+        { echo " $ide:FAIL"; echo "Agent install failed for $ide; rerun node $FW/cli/dist/cli.js agents install --ide $ide --provider $provider in a scratch directory for details." >&2; exit 1; }
+      printf ' %s:ok' "$ide"
+    done
+    echo
+  fi
+fi
+
 instructions=()
 [ "$HAVE_CODEX" = 0 ] || instructions+=(codex "$CODEX_INSTRUCTIONS")
 [ "$HAVE_CLAUDE" = 0 ] || instructions+=(claude "$CLAUDE_INSTRUCTIONS")

From 28ceb03c20531b091fe8b50614d3e93ce44458d5 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 20 Oct 2026 16:43:58 +0800
Subject: [PATCH 48/73] fix(aidd-orchestrator): keep executors on their checks
 and leave their checkout alone

A returned executor is never resumed, so it waits for the checks and
commits it started. A prescribed check the environment refuses twice, or
a red check outside the change, is a blocker to report, not an
environment to rebuild: one run spent seven hours and most of its budget
rebuilding a test server. The caller hands over a checkout and a phase
file, reuses the executor session, and stays out of its checkout.

Evidence: review of the SDLC run on gouvernail#164, 18-20 Oct 2026.
---
 cli/assets/agents/executor.md                                   | 2 ++
 plugins/aidd-dev/skills/02-implement/references/blocked.md      | 2 ++
 .../aidd-orchestrator/skills/01-sdlc/references/02-deliver.md   | 2 +-
 3 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/cli/assets/agents/executor.md b/cli/assets/agents/executor.md
index 588140d85..4ab16b649 100644
--- a/cli/assets/agents/executor.md
+++ b/cli/assets/agents/executor.md
@@ -12,6 +12,8 @@ Deliver assigned code or documentation within the agreed outcome and criteria.
 - **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; nobody resumes a returned executor.
+- **Treat a prescribed check the environment refuses twice as a blocker** to report, never as an environment to rebuild.
 - **Respect file and shared-operation ownership**; return changes and evidence to the caller.
 
 # Output
diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md
index 42c94f6a1..38a83c0d3 100644
--- a/plugins/aidd-dev/skills/02-implement/references/blocked.md
+++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md
@@ -8,3 +8,5 @@ description: Conditions that make a plan blocked (needs a human).
 `blocked` means implementation cannot proceed and only a human can unblock it. Stop and escalate to the whole-plan owner, who sets the plan `status: blocked`.
 
 Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA.
+
+Outside the assigned change (no repair allowed): a prescribed validation command the environment refuses twice; a red check in files the change never touched.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 137e4c246..c2768e271 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,7 +2,7 @@
 
 ## Behavior
 
-Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
+Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its checkout and its phase file, and nothing the phase file already says. Resume the same executor session for its next phase, and leave its checkout untouched while it runs. Integrate prerequisites before starting dependent phases.
 
 The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Whole-plan execution keeps its normal flow; phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
 

From ee259fb57d3f98dbc250d58d613c3eeb7d553446 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 20 Oct 2026 19:11:04 +0800
Subject: [PATCH 49/73] feat(cli): install agents at user scope and opt in to
 the main model

agents install|remove gain --scope user and --main. The main model records the value it replaces and restores it on removal, refuses values changed since and TOML it cannot edit safely, and both registries roll back with the files. Anthropic reviews on Sonnet; Mistral uses -latest aliases except the pinned Large 4 main model.
---
 README.md                                     |   2 +-
 cli/assets/agents/reviewer.md                 |   4 +-
 cli/package.json                              |   2 +-
 cli/scripts/check-bundle-size.mjs             |   2 +
 .../agents/manage-agents-use-case.ts          | 247 ++++++++++++++----
 .../domain/ports/agent-installation-store.ts  |   7 +
 .../agent-installation-store-adapter.ts       |  40 +++
 .../domain/capabilities/agents-capability.ts  |   3 +
 .../tools/domain/formats/agent-models.json    |  47 +++-
 .../tools/domain/formats/agent-models.ts      |  23 +-
 .../tools/domain/formats/main-model-config.ts | 164 ++++++++++++
 .../tools/domain/profiles/claude/profile.ts   |   1 +
 .../tools/domain/profiles/codex/profile.ts    |   1 +
 .../tools/domain/profiles/opencode/profile.ts |   2 +
 cli/src/presentation/commands/agents.ts       |  27 +-
 cli/src/runtime/filesystem/atomic-write.ts    |  10 +-
 cli/src/runtime/wiring/framework.ts           |  12 +-
 .../context-boundary.arch.test.ts             |   1 +
 ...manage-agents-use-case.integration.test.ts |  94 ++++++-
 .../clean-opt-in-agents.integration.test.ts   |   2 +-
 .../domain/formats/agent-models.unit.test.ts  |  42 ++-
 .../formats/main-model-config.unit.test.ts    |  91 +++++++
 cli/tests/e2e/agents.e2e.test.ts              |  16 +-
 cli/tests/golden/snapshots/help/surface.json  |   6 +-
 .../agents-wiring.integration.test.ts         |  39 ++-
 .../atomic-write.integration.test.ts          |  12 +-
 docs/SUBAGENTS.md                             |  28 +-
 27 files changed, 819 insertions(+), 106 deletions(-)
 create mode 100644 cli/src/contexts/tools/domain/formats/main-model-config.ts
 create mode 100644 cli/tests/contexts/tools/domain/formats/main-model-config.unit.test.ts

diff --git a/README.md b/README.md
index bc786b8cd..0bac50a8c 100644
--- a/README.md
+++ b/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>0 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/)
diff --git a/cli/assets/agents/reviewer.md b/cli/assets/agents/reviewer.md
index 968428d0f..34d627df3 100644
--- a/cli/assets/agents/reviewer.md
+++ b/cli/assets/agents/reviewer.md
@@ -9,8 +9,8 @@ Review finished work independently and identify quality or coherence gaps that a
 
 # Behavior
 
-- **Review the actual work and need independently**, using project conventions and caller-supplied criteria. Check defects, contradictions, duplication, unnecessary complexity, and gaps in validation evidence.
-- **Tie findings to evidence and impact**; distinguish defects from suggestions and state uncertainty. Recommend the smallest correction, favoring removal of obsolete or redundant material while preserving useful knowledge.
+- **Review the actual work and need independently**, using project conventions and caller-supplied criteria. Check defects, contradictions, duplication, and unnecessary complexity.
+- **Tie findings to evidence and impact**; distinguish defects from suggestions and state uncertainty. Recommend the smallest correction, favoring removal.
 - **Keep the work unchanged** and return findings to the caller.
 
 # Output
diff --git a/cli/package.json b/cli/package.json
index 81915fdf3..11f102068 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "packageManager": "pnpm@12.3.4",
-  "bundleBudgetKB": 715,
+  "bundleBudgetKB": 726,
   "scripts": {
     "build": "tsup && node scripts/check-bundle-size.mjs",
     "build:check-size": "node scripts/check-bundle-size.mjs",
diff --git a/cli/scripts/check-bundle-size.mjs b/cli/scripts/check-bundle-size.mjs
index dfeb6a29f..caea8398c 100644
--- a/cli/scripts/check-bundle-size.mjs
+++ b/cli/scripts/check-bundle-size.mjs
@@ -47,6 +47,8 @@ const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
 // with next ae8705f7; 1.1% headroom. The branch alone measured 694.7 KB.
 // 715 KB: 706.36 KB, #1027 merge 49e5cae4 with next 7084a88c after agent lifecycle fixes;
 // next's telemetry filtering adds 8,839 bytes over the 697.73 KB branch; 1.2% headroom.
+// 726 KB: 717.3 KB, #1027 main-session model per provider written into host settings, with
+// ownership-checked removal (+6.9 KB over the 710.4 KB branch); 1.2% headroom.
 const budgetKB = pkg.bundleBudgetKB ?? 500;
 const budgetBytes = budgetKB * 1024;
 
diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
index a64d65883..133190d92 100644
--- a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -1,26 +1,37 @@
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { parseFrontmatter } from "../../../../kernel/markdown.js";
 import type { FileReader } from "../../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../../kernel/ports/file-writer.js";
 import type { Hasher } from "../../../../kernel/ports/hasher.js";
 import type { AgentsCapability } from "../../../tools/domain/capabilities/agents-capability.js";
+import type { EnvironmentReader } from "../../../tools/domain/capabilities/plugins-capability.js";
 import type { HasAgents } from "../../../tools/domain/contracts.js";
 import {
   type AgentHost,
   type AgentProvider,
   agentModelOptions,
 } from "../../../tools/domain/formats/agent-models.js";
+import {
+  mainModelTarget,
+  mainModelValues,
+  planMainModelInstall,
+  planMainModelRemoval,
+} from "../../../tools/domain/formats/main-model-config.js";
 import { getAiToolConfig } from "../../../tools/domain/registry.js";
 import {
   AGENT_INSTALLATIONS_PATH,
   type AgentInstallationStore,
   type AgentInstallations,
+  MAIN_MODEL_INSTALLATIONS_PATH,
+  type MainModelInstallations,
 } from "../../domain/ports/agent-installation-store.js";
 import { assertProjectPathWithinRoot } from "../ownership/project-path-boundary.js";
 
 interface AgentTarget {
   projectRoot: string;
   host: AgentHost;
+  /** Targets the IDE's user configuration directory instead of the project. */
+  user?: UserAgentRoot;
 }
 
 interface AgentChange {
@@ -28,6 +39,26 @@ interface AgentChange {
   content: string | null;
 }
 
+/** Where one host's agents, main settings and ownership registry live for a scope. */
+interface AgentLocation {
+  registryRoot: string;
+  /** Creates the registry root when the scope owns it. */
+  prepare?: () => Promise<void>;
+  agentPath(name: string): string;
+  settingsPath: string | null;
+  guard(path: string): Promise<void>;
+}
+
+/** The user's home, environment and AIDD configuration directory, for user-scoped agents. */
+export interface UserAgentRoot {
+  home: string;
+  env: EnvironmentReader;
+  configDir: string;
+}
+
+/** A registry name maps to one file inside the agents directory, never a path. */
+const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
 export class ManageAgentsUseCase {
   constructor(
     private readonly fs: FileReader & FileWriter,
@@ -36,68 +67,146 @@ export class ManageAgentsUseCase {
     private readonly sources: Readonly<Record<string, string>>
   ) {}
 
-  async install(options: AgentTarget & { provider: AgentProvider }): Promise<number> {
+  /** `main` opts in to setting the main session model; without it the host settings stay as they are. */
+  async install(
+    options: AgentTarget & { provider: AgentProvider; main?: boolean }
+  ): Promise<number> {
     const capability = this.capability(options.host);
+    const location = this.location(options);
     const entries = Object.entries(this.sources).map(([name, source]) => {
       const { frontmatter, body } = parseFrontmatter(source);
       const role = typeof frontmatter.name === "string" ? frontmatter.name : name;
       const model = agentModelOptions(options.host, options.provider, role);
       return {
         name,
-        path: this.path(options.projectRoot, capability, name),
+        path: location.agentPath(name),
         content: capability.serialize(
           { ...capability.convertFrontmatter({ ...frontmatter, name }, `${name}.md`), ...model },
           body
         ),
       };
     });
-    return this.exclusively(options.projectRoot, async () => {
-      const installed = await this.load(options.projectRoot);
-      for (const entry of entries)
-        await this.assertOwned(
-          options.projectRoot,
-          entry.path,
-          installed[options.host]?.[entry.name]
-        );
-      installed[options.host] = {
-        ...installed[options.host],
-        ...Object.fromEntries(
-          entries.map(({ name, content }) => [name, this.hasher.hash(content)])
-        ),
-      };
-      return this.save(options.projectRoot, installed, entries);
+    await location.prepare?.();
+    return this.exclusively(location.registryRoot, async () => {
+      const installed = await this.load(location.registryRoot);
+      const owned = installed[options.host] ?? {};
+      for (const entry of entries) await this.assertOwned(location, entry.path, owned[entry.name]);
+      // Roles no longer bundled: remove their unmodified files.
+      const retired: AgentChange[] = [];
+      for (const [name, hash] of Object.entries(owned)) {
+        if (Object.hasOwn(this.sources, name)) continue;
+        const path = location.agentPath(name);
+        await this.assertOwned(location, path, hash);
+        retired.push({ path, content: null });
+      }
+      installed[options.host] = Object.fromEntries(
+        entries.map(({ name, content }) => [name, this.hasher.hash(content)])
+      );
+      const mainModels = await this.store.loadMainModels(location.registryRoot);
+      const mainChanges: AgentChange[] = [];
+      if (options.main === true) {
+        const main = await this.mainModelInstall(options, location, mainModels);
+        if (main !== null) mainChanges.push(main);
+      }
+      return this.save(
+        location.registryRoot,
+        installed,
+        mainModels,
+        [...entries, ...retired],
+        mainChanges
+      );
     });
   }
 
+  /** Writes the provider's main model into the host settings, recording what it replaces. */
+  private async mainModelInstall(
+    options: AgentTarget & { provider: AgentProvider },
+    location: AgentLocation,
+    mainModels: MainModelInstallations
+  ): Promise<AgentChange | null> {
+    const target = mainModelTarget(options.host);
+    const path = location.settingsPath;
+    if (target === null || path === null) return null;
+    await location.guard(path);
+    if ((await this.fs.fileExists(path, false)) && !(await this.fs.fileExists(path)))
+      throw new Error(`Settings link is broken; fix it before installing agents: ${path}`);
+    const content = await this.readOptional(path);
+    for (const alternative of content === null ? (target.alternatives ?? []) : [])
+      if (await this.fs.fileExists(join(dirname(path), alternative)))
+        throw new Error(
+          `Settings live in ${alternative}; move them to ${basename(path)} before installing agents.`
+        );
+    try {
+      const plan = planMainModelInstall(
+        content,
+        target.format,
+        mainModelValues(options.host, options.provider),
+        mainModels[options.host]
+      );
+      mainModels[options.host] = plan.record;
+      return { path, content: plan.content };
+    } catch (error) {
+      throw new Error(`Cannot set the main model in ${path}: ${(error as Error).message}`);
+    }
+  }
+
+  /** Restores the settings each recorded main model replaced. */
+  private async mainModelRemovals(
+    target: Omit<AgentTarget, "host">,
+    mainModels: MainModelInstallations,
+    onlyHost?: AgentHost
+  ): Promise<AgentChange[]> {
+    const changes: AgentChange[] = [];
+    for (const [host, record] of Object.entries(mainModels)) {
+      if (onlyHost !== undefined && host !== onlyHost) continue;
+      const settings = mainModelTarget(host as AgentHost);
+      const location = this.location({ ...target, host: host as AgentHost });
+      if (settings === null || location.settingsPath === null || record === undefined) continue;
+      await location.guard(location.settingsPath);
+      const content = await this.readOptional(location.settingsPath);
+      const next = planMainModelRemoval(content, settings.format, record);
+      if (next !== content) changes.push({ path: location.settingsPath, content: next });
+    }
+    return changes;
+  }
+
+  private async readOptional(path: string): Promise<string | null> {
+    return (await this.fs.fileExists(path)) ? this.fs.readFile(path) : null;
+  }
+
   private async exclusively<T>(root: string, action: () => Promise<T>): Promise<T> {
     await assertProjectPathWithinRoot(this.fs, root, join(root, AGENT_INSTALLATIONS_PATH));
     return this.store.withExclusiveAccess(root, action);
   }
 
+  /** Applies every change, then both registries; any failure restores all of them. */
   private async save(
     root: string,
     installed: AgentInstallations,
-    changes: readonly AgentChange[]
+    mainModels: MainModelInstallations,
+    changes: readonly AgentChange[],
+    mainChanges: readonly AgentChange[] = []
   ): Promise<number> {
     const previous: AgentChange[] = [];
+    const agentPaths = new Set(changes.map((change) => change.path));
     try {
-      for (const change of changes) {
-        const content = (await this.fs.fileExists(change.path))
-          ? await this.fs.readFile(change.path)
-          : null;
+      for (const change of [...changes, ...mainChanges]) {
+        const content = await this.readOptional(change.path);
         if (content === change.content) continue;
         previous.push({ path: change.path, content });
         await this.write(change);
       }
+      for (const registry of [AGENT_INSTALLATIONS_PATH, MAIN_MODEL_INSTALLATIONS_PATH]) {
+        const path = join(root, registry);
+        previous.push({ path, content: await this.readOptional(path) });
+      }
       await this.store.save(root, installed);
-      return previous.length;
+      await this.store.saveMainModels(root, mainModels);
+      return previous.filter((change) => agentPaths.has(change.path)).length;
     } catch (error) {
       const restored = await Promise.allSettled(
         previous.reverse().map(async (change) => {
-          const content = (await this.fs.fileExists(change.path))
-            ? await this.fs.readFile(change.path)
-            : null;
-          if (content !== change.content) await this.write(change);
+          if ((await this.readOptional(change.path)) !== change.content) await this.write(change);
         })
       );
       const failures = restored.filter((result) => result.status === "rejected");
@@ -110,23 +219,33 @@ export class ManageAgentsUseCase {
     }
   }
 
+  /** Writes through an existing link, so linked settings files stay linked. */
   private async write({ path, content }: AgentChange): Promise<void> {
-    if (content !== null) await this.fs.writeFile(path, content);
-    else {
+    if (content !== null) {
+      const target = (await this.fs.fileExists(path)) ? await this.fs.realpath(path) : path;
+      await this.fs.writeFile(target, content);
+    } else {
       await this.fs.deleteFile(path);
       if (await this.fs.fileExists(path)) throw new Error(`Could not remove agent: ${path}`);
     }
   }
 
   async remove(options: AgentTarget): Promise<number> {
-    return this.exclusively(options.projectRoot, async () => {
-      const installed = await this.load(options.projectRoot);
-      const entries = await this.removable(options.projectRoot, installed, options.host);
+    const location = this.location(options);
+    await location.prepare?.();
+    return this.exclusively(location.registryRoot, async () => {
+      const installed = await this.load(location.registryRoot);
+      const entries = await this.removable(options, installed, options.host);
+      const mainModels = await this.store.loadMainModels(location.registryRoot);
+      const main = await this.mainModelRemovals(options, mainModels, options.host);
       delete installed[options.host];
+      delete mainModels[options.host];
       return this.save(
-        options.projectRoot,
+        location.registryRoot,
         installed,
-        entries.map((path) => ({ path, content: null }))
+        mainModels,
+        entries.map((path) => ({ path, content: null })),
+        main
       );
     });
   }
@@ -143,16 +262,22 @@ export class ManageAgentsUseCase {
   }
 
   async assertRemovable(projectRoot: string): Promise<void> {
-    await this.removable(projectRoot, await this.load(projectRoot));
+    await this.removable({ projectRoot }, await this.load(projectRoot));
   }
 
   async removeAll(projectRoot: string, afterRemoval?: () => Promise<void>): Promise<number> {
     return this.exclusively(projectRoot, async () => {
-      const entries = await this.removable(projectRoot, await this.load(projectRoot));
+      const entries = await this.removable({ projectRoot }, await this.load(projectRoot));
+      const main = await this.mainModelRemovals(
+        { projectRoot },
+        await this.store.loadMainModels(projectRoot)
+      );
       const count = await this.save(
         projectRoot,
         {},
-        entries.map((path) => ({ path, content: null }))
+        {},
+        entries.map((path) => ({ path, content: null })),
+        main
       );
       await afterRemoval?.();
       return count;
@@ -163,10 +288,34 @@ export class ManageAgentsUseCase {
     return (getAiToolConfig(host).capabilities as HasAgents).agents;
   }
 
-  private path(root: string, capability: AgentsCapability, name: string): string {
-    const path = capability.buildInstallPath(`${name}.md`);
-    if (path === null) throw new Error(`Agent ${name} has no native install path.`);
-    return join(root, path);
+  private location(target: AgentTarget): AgentLocation {
+    const capability = this.capability(target.host);
+    const settings = mainModelTarget(target.host);
+    const file = (name: string) => {
+      const path = capability.buildInstallPath(`${name}.md`);
+      if (path === null) throw new Error(`Agent ${name} has no native install path.`);
+      return path;
+    };
+    const user = target.user;
+    if (user === undefined) {
+      const root = target.projectRoot;
+      return {
+        registryRoot: root,
+        agentPath: (name) => join(root, file(name)),
+        settingsPath: settings === null ? null : join(root, settings.path),
+        guard: (path) => assertProjectPathWithinRoot(this.fs, root, path),
+      };
+    }
+    const directory = capability.params.userDirectory?.(user.home, user.env);
+    if (directory === undefined) throw new Error(`${target.host} has no user-level agents.`);
+    const configDir = user.configDir;
+    return {
+      registryRoot: configDir,
+      prepare: () => this.fs.createDirectory(configDir),
+      agentPath: (name) => join(directory, "agents", basename(file(name))),
+      settingsPath: settings === null ? null : join(directory, settings.userPath),
+      guard: async () => {},
+    };
   }
 
   private async load(root: string): Promise<AgentInstallations> {
@@ -174,18 +323,18 @@ export class ManageAgentsUseCase {
     const installed = await this.store.load(root);
     for (const entries of Object.values(installed)) {
       for (const name of Object.keys(entries)) {
-        if (!Object.hasOwn(this.sources, name)) throw new Error(`Unknown managed agent: ${name}`);
+        if (!AGENT_NAME.test(name)) throw new Error(`Unknown managed agent: ${name}`);
       }
     }
     return installed;
   }
 
   private async assertOwned(
-    root: string,
+    location: AgentLocation,
     path: string,
     expected: ReturnType<Hasher["hash"]> | undefined
   ): Promise<void> {
-    await assertProjectPathWithinRoot(this.fs, root, path);
+    await location.guard(path);
     if (!(await this.fs.fileExists(path, false))) return;
     if (expected === undefined) throw new Error(`Agent file is not owned by AIDD: ${path}`);
     if (!(await this.fs.readFileHash(path)).equals(expected))
@@ -193,17 +342,17 @@ export class ManageAgentsUseCase {
   }
 
   private async removable(
-    root: string,
+    target: Omit<AgentTarget, "host">,
     installed: AgentInstallations,
     onlyHost?: AgentHost
   ): Promise<string[]> {
     const paths: string[] = [];
     for (const [host, entries] of Object.entries(installed)) {
       if (onlyHost !== undefined && host !== onlyHost) continue;
-      const capability = this.capability(host as AgentHost);
+      const location = this.location({ ...target, host: host as AgentHost });
       for (const [name, hash] of Object.entries(entries)) {
-        const path = this.path(root, capability, name);
-        await this.assertOwned(root, path, hash);
+        const path = location.agentPath(name);
+        await this.assertOwned(location, path, hash);
         if (await this.fs.fileExists(path)) paths.push(path);
       }
     }
diff --git a/cli/src/contexts/framework/domain/ports/agent-installation-store.ts b/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
index 268a8fa55..ec10d3e4a 100644
--- a/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
+++ b/cli/src/contexts/framework/domain/ports/agent-installation-store.ts
@@ -1,13 +1,20 @@
 import type { FileHash } from "../../../../kernel/file.js";
 import type { AgentHost } from "../../../tools/domain/formats/agent-models.js";
+import type { MainModelRecord } from "../../../tools/domain/formats/main-model-config.js";
 
 export type AgentInstallations = Partial<Record<AgentHost, Record<string, FileHash>>>;
 
+/** Main-session settings AIDD wrote per host, so removal restores what was there before. */
+export type MainModelInstallations = Partial<Record<AgentHost, MainModelRecord>>;
+
 export interface AgentInstallationStore {
   withExclusiveAccess<T>(projectRoot: string, action: () => Promise<T>): Promise<T>;
   load(projectRoot: string): Promise<AgentInstallations>;
   save(projectRoot: string, installations: AgentInstallations): Promise<void>;
+  loadMainModels(projectRoot: string): Promise<MainModelInstallations>;
+  saveMainModels(projectRoot: string, installations: MainModelInstallations): Promise<void>;
 }
 
 export const AGENT_INSTALLATIONS_PATH = ".aidd/agents.json";
+export const MAIN_MODEL_INSTALLATIONS_PATH = ".aidd/main-model.json";
 export const AGENT_INSTALLATIONS_LOCK_PATH = `${AGENT_INSTALLATIONS_PATH}.lock`;
diff --git a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
index edbf80c2a..bb545eed4 100644
--- a/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
+++ b/cli/src/contexts/framework/infrastructure/agent-installation-store-adapter.ts
@@ -10,6 +10,8 @@ import {
   AGENT_INSTALLATIONS_PATH,
   type AgentInstallationStore,
   type AgentInstallations,
+  MAIN_MODEL_INSTALLATIONS_PATH,
+  type MainModelInstallations,
 } from "../domain/ports/agent-installation-store.js";
 
 export class AgentInstallationStoreAdapter implements AgentInstallationStore {
@@ -91,4 +93,42 @@ export class AgentInstallationStoreAdapter implements AgentInstallationStore {
     );
     await this.fs.writeFile(path, `${JSON.stringify(data, null, 2)}\n`);
   }
+
+  async loadMainModels(projectRoot: string): Promise<MainModelInstallations> {
+    const path = join(projectRoot, MAIN_MODEL_INSTALLATIONS_PATH);
+    if (!(await this.fs.fileExists(path, false))) return {};
+    const parsed: unknown = JSON.parse(await this.fs.readFile(path));
+    const invalid = new Error(`Invalid main model ownership file: ${path}`);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw invalid;
+    const installations: MainModelInstallations = {};
+    const strings = (value: unknown, nullable = false) =>
+      typeof value === "object" &&
+      value !== null &&
+      Object.values(value).every(
+        (entry) => typeof entry === "string" || (nullable && entry === null)
+      );
+    for (const [host, record] of Object.entries(parsed)) {
+      if (
+        !isAgentHost(host) ||
+        !strings(record?.written) ||
+        !strings(record?.previous, true) ||
+        typeof record?.created !== "boolean"
+      )
+        throw invalid;
+      installations[host] = record;
+    }
+    return installations;
+  }
+
+  async saveMainModels(projectRoot: string, installations: MainModelInstallations): Promise<void> {
+    const path = join(projectRoot, MAIN_MODEL_INSTALLATIONS_PATH);
+    if (Object.keys(installations).length > 0) {
+      await this.fs.writeFile(path, `${JSON.stringify(installations, null, 2)}\n`);
+      return;
+    }
+    if (!(await this.fs.fileExists(path, false))) return;
+    await this.fs.deleteFile(path);
+    if (await this.fs.fileExists(path))
+      throw new Error(`Could not remove main model ownership file: ${path}`);
+  }
 }
diff --git a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
index c37dffd6f..2f8a36279 100644
--- a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
+++ b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
@@ -1,4 +1,5 @@
 import { parseFrontmatter, serializeFrontmatter } from "../../../../kernel/markdown.js";
+import type { EnvironmentReader } from "./plugins-capability.js";
 
 function agentNameFromFrontmatter(
   fm: Record<string, unknown>,
@@ -58,6 +59,8 @@ export class AgentsCapability {
       format: "markdown" | "toml";
       effortField?: string;
       userFileExt?: string;
+      /** The IDE's user configuration directory, holding `agents/` and the main settings file. */
+      userDirectory?: (home: string, env: EnvironmentReader) => string;
       buildInstallPath?: (fileName: string) => string | null;
       convertFrontmatter?: (
         fm: Record<string, unknown>,
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.json b/cli/src/contexts/tools/domain/formats/agent-models.json
index 7eff7aa99..c2058b19f 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.json
+++ b/cli/src/contexts/tools/domain/formats/agent-models.json
@@ -1,6 +1,6 @@
 {
   "roles": {
-    "main": "standard",
+    "main": "main",
     "explorer": "light",
     "executor": "light",
     "validator": "light",
@@ -8,6 +8,10 @@
   },
   "providers": {
     "openai": {
+      "main": {
+        "model": "gpt-6.1-sol",
+        "effort": "medium"
+      },
       "standard": {
         "model": "gpt-6.1-sol",
         "effort": "medium"
@@ -18,13 +22,20 @@
       }
     },
     "anthropic": {
-      "standard": {
+      "main": {
         "model": "claude-opus-5-5",
         "effort": "medium",
         "nativeModels": {
           "copilot": "claude-opus-5.5"
         }
       },
+      "standard": {
+        "model": "claude-sonnet-5-5",
+        "effort": "medium",
+        "nativeModels": {
+          "copilot": "claude-sonnet-5.5"
+        }
+      },
       "light": {
         "model": "claude-haiku-5-5",
         "effort": "medium",
@@ -34,12 +45,16 @@
       }
     },
     "mistral": {
-      "standard": {
+      "main": {
         "model": "mistral-large-4",
         "effort": "high"
       },
+      "standard": {
+        "model": "mistral-medium-latest",
+        "effort": "high"
+      },
       "light": {
-        "model": "mistral-small-2603",
+        "model": "mistral-small-latest",
         "effort": "high"
       }
     }
@@ -48,11 +63,23 @@
     "claude": {
       "ide": "claude-code",
       "providers": ["anthropic"],
-      "effortField": "effort"
+      "effortField": "effort",
+      "mainSettings": {
+        "path": ".claude/settings.json",
+        "userPath": "settings.json",
+        "format": "json",
+        "effortKey": "effortLevel"
+      }
     },
     "codex": {
       "providers": ["openai"],
-      "effortField": "model_reasoning_effort"
+      "effortField": "model_reasoning_effort",
+      "mainSettings": {
+        "path": ".codex/config.toml",
+        "userPath": "config.toml",
+        "format": "toml",
+        "effortKey": "model_reasoning_effort"
+      }
     },
     "copilot": {
       "providers": ["openai", "anthropic"],
@@ -62,7 +89,13 @@
       "providers": ["openai", "anthropic", "mistral"],
       "effortPrefix": "#",
       "effortSuffix": "",
-      "providerPrefix": true
+      "providerPrefix": true,
+      "mainSettings": {
+        "path": "opencode.json",
+        "userPath": "opencode.json",
+        "format": "json",
+        "alternatives": ["opencode.jsonc"]
+      }
     },
     "cursor": {
       "providers": ["anthropic"],
diff --git a/cli/src/contexts/tools/domain/formats/agent-models.ts b/cli/src/contexts/tools/domain/formats/agent-models.ts
index 14be1b783..34bdf6e6d 100644
--- a/cli/src/contexts/tools/domain/formats/agent-models.ts
+++ b/cli/src/contexts/tools/domain/formats/agent-models.ts
@@ -35,12 +35,12 @@ export function resolveAgentHost(ide: string): AgentHost {
   return host;
 }
 
-/** Native fields for a configured role on the selected host and provider. */
-export function agentModelOptions(
+/** The host's native model id and the effort for a configured role. */
+export function agentModel(
   host: AgentHost,
   provider: AgentProvider,
   role: string
-): Record<string, unknown> {
+): { model: string; effort: string } {
   const target = models.hosts[host];
   if (!target.providers.includes(provider)) {
     throw new Error(`Provider "${provider}" is not supported by "${host}".`);
@@ -53,8 +53,19 @@ export function agentModelOptions(
   if (source === undefined)
     throw new Error(`Agent profile "${profile}" is not configured for "${provider}".`);
   const nativeModel = source.nativeModels?.[host] ?? source.model;
-  const model = `${"providerPrefix" in target && target.providerPrefix ? `${provider}/` : ""}${nativeModel}`;
+  const prefix = "providerPrefix" in target && target.providerPrefix ? `${provider}/` : "";
+  return { model: `${prefix}${nativeModel}`, effort: source.effort };
+}
+
+/** Native fields for a configured role on the selected host and provider. */
+export function agentModelOptions(
+  host: AgentHost,
+  provider: AgentProvider,
+  role: string
+): Record<string, unknown> {
+  const target = models.hosts[host];
+  const { model, effort } = agentModel(host, provider, role);
   return "effortField" in target
-    ? { model, [target.effortField]: source.effort }
-    : { model: `${model}${target.effortPrefix}${source.effort}${target.effortSuffix}` };
+    ? { model, [target.effortField]: effort }
+    : { model: `${model}${target.effortPrefix}${effort}${target.effortSuffix}` };
 }
diff --git a/cli/src/contexts/tools/domain/formats/main-model-config.ts b/cli/src/contexts/tools/domain/formats/main-model-config.ts
new file mode 100644
index 000000000..5517aab9d
--- /dev/null
+++ b/cli/src/contexts/tools/domain/formats/main-model-config.ts
@@ -0,0 +1,164 @@
+import { parse } from "smol-toml";
+import { type AgentHost, type AgentProvider, agentModel } from "./agent-models.js";
+import models from "./agent-models.json" with { type: "json" };
+
+/** Main-session settings AIDD writes, keyed by the host's native config key. */
+export type MainModelValues = Record<string, string>;
+
+export interface MainModelTarget {
+  /** Project-relative settings file. */
+  path: string;
+  /** The same file, relative to the IDE's user configuration directory. */
+  userPath: string;
+  format: "json" | "toml";
+  effortKey?: string;
+  /** Equivalent files the host may use instead, which AIDD does not edit. */
+  alternatives?: readonly string[];
+}
+
+/** What AIDD wrote and what each key held before, so removal restores it. */
+export interface MainModelRecord {
+  written: MainModelValues;
+  previous: Record<string, string | null>;
+  /** The settings file did not exist before AIDD wrote it. */
+  created: boolean;
+}
+
+/** Hosts without a file-based main model return null. */
+export function mainModelTarget(host: AgentHost): MainModelTarget | null {
+  const target = models.hosts[host];
+  return "mainSettings" in target ? (target.mainSettings as MainModelTarget) : null;
+}
+
+/** The provider's main model; effort only where the host has a settings key for it. */
+export function mainModelValues(host: AgentHost, provider: AgentProvider): MainModelValues {
+  const target = mainModelTarget(host);
+  if (target === null) return {};
+  const { model, effort } = agentModel(host, provider, "main");
+  return target.effortKey === undefined ? { model } : { model, [target.effortKey]: effort };
+}
+
+/** Sets the main model, recording prior values; refuses values changed since AIDD wrote them. */
+export function planMainModelInstall(
+  content: string | null,
+  format: MainModelTarget["format"],
+  values: MainModelValues,
+  record: MainModelRecord | undefined
+): { content: string; record: MainModelRecord } {
+  const current = readSettings(content, format);
+  for (const [key, value] of Object.entries(record?.written ?? {}))
+    if (current[key] !== value)
+      throw new Error(`"${key}" changed since AIDD set it; restore it or edit it yourself.`);
+  const previous: Record<string, string | null> = {};
+  for (const key of Object.keys(values)) {
+    const value = current[key];
+    if (value !== undefined && typeof value !== "string")
+      throw new Error(`"${key}" is not a string; edit it yourself.`);
+    previous[key] = value ?? null;
+  }
+  return {
+    content: editSettings(content, format, values, []),
+    record: {
+      written: values,
+      previous: { ...previous, ...record?.previous },
+      created: record?.created ?? content === null,
+    },
+  };
+}
+
+/** Restores unchanged keys; leaves unreadable or user-edited settings as they are. */
+export function planMainModelRemoval(
+  content: string | null,
+  format: MainModelTarget["format"],
+  record: MainModelRecord
+): string | null {
+  if (content === null) return null;
+  try {
+    const current = readSettings(content, format);
+    const set: MainModelValues = {};
+    const unset: string[] = [];
+    for (const [key, value] of Object.entries(record.written)) {
+      if (current[key] !== value) continue;
+      const previous = record.previous[key] ?? null;
+      if (previous === null) unset.push(key);
+      else set[key] = previous;
+    }
+    if (Object.keys(set).length === 0 && unset.length === 0) return content;
+    const next = editSettings(content, format, set, unset);
+    return record.created && Object.keys(readSettings(next, format)).length === 0 ? null : next;
+  } catch {
+    return content;
+  }
+}
+
+function readSettings(
+  content: string | null,
+  format: MainModelTarget["format"]
+): Record<string, unknown> {
+  if (content === null || content.trim() === "") return {};
+  if (format === "toml") return parse(content);
+  const parsed: unknown = JSON.parse(content.replace(/^/, ""));
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    throw new Error("Settings file must contain a JSON object.");
+  return parsed as Record<string, unknown>;
+}
+
+function editSettings(
+  content: string | null,
+  format: MainModelTarget["format"],
+  set: MainModelValues,
+  unset: readonly string[]
+): string {
+  const settings = readSettings(content, format);
+  for (const [key, value] of Object.entries(set)) settings[key] = value;
+  for (const key of unset) delete settings[key];
+  if (format === "json") {
+    const bom = content?.startsWith("") ? "" : "";
+    const indent = /\n([ \t]+)"/.exec(content ?? "")?.[1] ?? "  ";
+    return `${bom}${JSON.stringify(settings, null, indent)}\n`;
+  }
+  const next = editTomlLines(content ?? "", set, unset);
+  if (canonical(parse(next)) !== canonical(settings))
+    throw new Error("Cannot edit this TOML safely; set the model yourself.");
+  return next;
+}
+
+/** Rewrites only simple top-level `key = "value"` lines, keeping comments and line endings. */
+function editTomlLines(content: string, set: MainModelValues, unset: readonly string[]): string {
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const lines = content === "" ? [""] : content.split(/\r?\n/);
+  const inserted: string[] = [];
+  for (const [key, value] of Object.entries(set)) {
+    const index = topLevelKeyIndex(lines, key);
+    const line = `${key} = ${JSON.stringify(value)}`;
+    if (index === -1) inserted.push(line);
+    else lines[index] = (lines[index] as string).replace(valuePattern(key), `${line}$1`);
+  }
+  for (const key of unset) {
+    const index = topLevelKeyIndex(lines, key);
+    if (index !== -1) lines.splice(index, 1);
+  }
+  return [...inserted, ...lines].join(eol);
+}
+
+function valuePattern(key: string): RegExp {
+  return new RegExp(`^\\s*${key}\\s*=\\s*(?:"(?:[^"\\\\]|\\\\.)*"|'[^']*')(\\s*(?:#.*)?)$`);
+}
+
+/** Index of `key = ...` before the first table header, or -1. */
+function topLevelKeyIndex(lines: readonly string[], key: string): number {
+  const assignment = new RegExp(`^\\s*${key}\\s*=`);
+  for (const [index, line] of lines.entries()) {
+    if (/^\s*\[/.test(line)) return -1;
+    if (assignment.test(line)) return index;
+  }
+  return -1;
+}
+
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_, entry) =>
+    entry !== null && typeof entry === "object" && !Array.isArray(entry) && !(entry instanceof Date)
+      ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b)))
+      : entry
+  );
+}
diff --git a/cli/src/contexts/tools/domain/profiles/claude/profile.ts b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
index 4c78b8c10..08b3d52b2 100644
--- a/cli/src/contexts/tools/domain/profiles/claude/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/claude/profile.ts
@@ -49,6 +49,7 @@ export const claude: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
         effortField: "effort",
+        userDirectory: (home, env) => env("CLAUDE_CONFIG_DIR") || join(home, ".claude"),
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/contexts/tools/domain/profiles/codex/profile.ts b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
index a2b30db93..0b47c5014 100644
--- a/cli/src/contexts/tools/domain/profiles/codex/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/codex/profile.ts
@@ -143,6 +143,7 @@ export const codex: AiTool<
       toolSuffix: TOOL_SUFFIX,
       format: "toml",
       effortField: "model_reasoning_effort",
+      userDirectory: (home, env) => env("CODEX_HOME") || join(home, ".codex"),
     }),
     skills: new SkillsCapability({
       prefix: "aidd-",
diff --git a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
index a44e83716..66aa64a47 100644
--- a/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/opencode/profile.ts
@@ -59,6 +59,8 @@ export const opencode: AiTool<
       toolSuffix: TOOL_SUFFIX,
       format: "markdown",
       convertFrontmatter: (fm) => ({ description: fm.description, mode: "subagent" }),
+      userDirectory: (home, env) =>
+        join(env("XDG_CONFIG_HOME") || join(home, ".config"), "opencode"),
     }),
     skills: new SkillsCapability({
       directory: DIRECTORY,
diff --git a/cli/src/presentation/commands/agents.ts b/cli/src/presentation/commands/agents.ts
index 7852c35da..3e381fc71 100644
--- a/cli/src/presentation/commands/agents.ts
+++ b/cli/src/presentation/commands/agents.ts
@@ -7,7 +7,9 @@ import {
 } from "../../contexts/tools/domain/formats/agent-models.js";
 import { createDeps } from "../../runtime/wiring/framework.js";
 import { ErrorHandler } from "../error-handler.js";
-import { parseGlobalOptions } from "./global-options.js";
+import { parseGlobalOptions, parseScopeFlag } from "./global-options.js";
+
+const SCOPE_HELP = "project (default) or user, the IDE's user configuration directory";
 
 export function registerAgentsCommand(program: Command): void {
   const agents = program
@@ -18,33 +20,46 @@ export function registerAgentsCommand(program: Command): void {
     .description("Install agents with the selected provider's model and effort")
     .requiredOption("--provider <provider>", agentProviderNames().join(", "))
     .requiredOption("--ide <ide>", agentIdeNames().join(", "))
-    .action(async (options: { provider: string; ide: string }) => {
+    .option("--main", "also set the provider's main session model in the IDE's settings")
+    .option("--scope <scope>", SCOPE_HELP)
+    .action(async (options: { provider: string; ide: string; main?: boolean; scope?: string }) => {
       const { projectRoot, verbose, output } = parseGlobalOptions(program);
       try {
         const host = resolveAgentHost(options.ide);
         if (!isAgentProvider(options.provider))
           throw new Error(`Unsupported agent provider: ${options.provider}`);
+        const user = parseScopeFlag(options.scope, output) === "user";
         const deps = await createDeps(projectRoot, { verbose }, output);
         const count = await deps.manageAgentsUseCase.install({
           projectRoot,
           host,
+          ...(user ? { user: deps.userAgentRoot } : {}),
           provider: options.provider,
+          main: options.main === true,
         });
-        output.success(`${count} agent files installed for ${options.ide}.`);
+        output.success(
+          `${count} agent files installed for ${options.ide}${options.main ? ", main model set" : ""}.`
+        );
       } catch (error) {
         new ErrorHandler(output).handle(error);
       }
     });
   agents
     .command("remove")
-    .description("Remove unmodified AIDD agents from this project")
+    .description("Remove unmodified AIDD agents and restore the main model they replaced")
     .requiredOption("--ide <ide>", agentIdeNames().join(", "))
-    .action(async (options: { ide: string }) => {
+    .option("--scope <scope>", SCOPE_HELP)
+    .action(async (options: { ide: string; scope?: string }) => {
       const { projectRoot, verbose, output } = parseGlobalOptions(program);
       try {
         const host = resolveAgentHost(options.ide);
+        const user = parseScopeFlag(options.scope, output) === "user";
         const deps = await createDeps(projectRoot, { verbose }, output);
-        const count = await deps.manageAgentsUseCase.remove({ projectRoot, host });
+        const count = await deps.manageAgentsUseCase.remove({
+          projectRoot,
+          host,
+          ...(user ? { user: deps.userAgentRoot } : {}),
+        });
         output.success(`${count} agent files removed for ${options.ide}.`);
       } catch (error) {
         new ErrorHandler(output).handle(error);
diff --git a/cli/src/runtime/filesystem/atomic-write.ts b/cli/src/runtime/filesystem/atomic-write.ts
index 3aac000e9..0da3476e5 100644
--- a/cli/src/runtime/filesystem/atomic-write.ts
+++ b/cli/src/runtime/filesystem/atomic-write.ts
@@ -1,12 +1,18 @@
 import { randomBytes } from "node:crypto";
-import { rename, writeFile } from "node:fs/promises";
+import { chmod, rename, stat, writeFile } from "node:fs/promises";
 
 /** A temporary sibling then `rename`, the one POSIX-atomic step a direct `writeFile` cannot
  * offer: a concurrent reader never sees a half-written file, and a crash mid-write orphans
  * the temporary rather than truncating the real one. The pid and random suffix keep two
- * concurrent writers to the same `path` off each other's temporary file. */
+ * concurrent writers to the same `path` off each other's temporary file. A replaced file keeps
+ * its permissions, so a private settings file stays private. */
 export async function atomicWriteFile(path: string, content: string): Promise<void> {
   const tmpPath = `${path}.${process.pid}-${randomBytes(6).toString("hex")}.tmp`;
+  const mode = await stat(path).then(
+    (existing) => existing.mode & 0o777,
+    () => undefined
+  );
   await writeFile(tmpPath, content, "utf-8");
+  if (mode !== undefined) await chmod(tmpPath, mode);
   await rename(tmpPath, path);
 }
diff --git a/cli/src/runtime/wiring/framework.ts b/cli/src/runtime/wiring/framework.ts
index eeb61461c..d95740c32 100644
--- a/cli/src/runtime/wiring/framework.ts
+++ b/cli/src/runtime/wiring/framework.ts
@@ -10,7 +10,10 @@ import { MarketplaceAddUseCase } from "../../contexts/distribution/application/m
 import type { MarketplaceListUseCase } from "../../contexts/distribution/application/marketplace-list-use-case.js";
 import type { MarketplaceRefreshUseCase } from "../../contexts/distribution/application/marketplace-refresh-use-case.js";
 import type { MarketplaceRegisterFrameworkUseCase } from "../../contexts/distribution/application/marketplace-register-framework-use-case.js";
-import { ManageAgentsUseCase } from "../../contexts/framework/application/agents/manage-agents-use-case.js";
+import {
+  ManageAgentsUseCase,
+  type UserAgentRoot,
+} from "../../contexts/framework/application/agents/manage-agents-use-case.js";
 import { CleanUserScopeUseCase } from "../../contexts/framework/application/clean/clean-user-scope-use-case.js";
 import { CleanUseCase } from "../../contexts/framework/application/clean-use-case.js";
 import { DoctorLayoutUseCase } from "../../contexts/framework/application/doctor/doctor-layout-use-case.js";
@@ -130,6 +133,8 @@ interface GlobalOptions {
 
 interface Deps {
   manageAgentsUseCase: ManageAgentsUseCase;
+  /** Where `agents --scope user` installs: the IDE user directories and AIDD's own. */
+  userAgentRoot: UserAgentRoot;
   fs: FileReader & FileWriter & FileMerger;
   manifestRepo: ManifestRepository;
   /** `--scope user`'s own manifest repository: `userConfigDir()/manifest.json`, never nested
@@ -601,6 +606,11 @@ export async function createDeps(
   const checkUpdateUseCase = new CheckUpdateUseCase(cliUpdater, currentVersionProvider, logger, fs);
   const deps: Deps = {
     manageAgentsUseCase,
+    userAgentRoot: {
+      home: homedir(),
+      env: (name) => process.env[name],
+      configDir: userConfigDir(),
+    },
     validateRecipesUseCase: new ValidateRecipesUseCase(new RecipeFilesAdapter()),
     fs,
     manifestRepo,
diff --git a/cli/tests/architecture/context-boundary.arch.test.ts b/cli/tests/architecture/context-boundary.arch.test.ts
index bff8e2f45..fdf4706a8 100644
--- a/cli/tests/architecture/context-boundary.arch.test.ts
+++ b/cli/tests/architecture/context-boundary.arch.test.ts
@@ -13,6 +13,7 @@ const PUBLIC_MODULES: Readonly<Record<string, readonly string[]>> = {
     "src/contexts/tools/domain/contracts.ts",
     "src/contexts/tools/domain/capabilities/agents-capability.ts",
     "src/contexts/tools/domain/formats/agent-models.ts",
+    "src/contexts/tools/domain/formats/main-model-config.ts",
     "src/contexts/tools/domain/registry.ts",
     "src/contexts/tools/domain/build-contract.ts",
     // co-owned configuration (settings.json, .mcp.json et al.)
diff --git a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
index b5a2e56e4..1b1d41f96 100644
--- a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
+++ b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
@@ -1,6 +1,6 @@
 import { mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ManageAgentsUseCase } from "../../../../../src/contexts/framework/application/agents/manage-agents-use-case.js";
 import { AgentInstallationStoreAdapter } from "../../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
@@ -31,6 +31,96 @@ describe("ManageAgentsUseCase", () => {
     await rm(root, { recursive: true, force: true });
   });
 
+  it("sets the main model on install and reverts only unchanged values on removal", async () => {
+    const config = join(root, ".codex/config.toml");
+    await mkdir(join(root, ".codex"), { recursive: true });
+    await writeFile(config, '# mine\napproval_policy = "never"\n');
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    expect(await readFile(config, "utf8")).toBe('# mine\napproval_policy = "never"\n');
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai", main: true });
+    expect(await readFile(config, "utf8")).toBe(
+      'model = "gpt-6.1-sol"\nmodel_reasoning_effort = "medium"\n# mine\napproval_policy = "never"\n'
+    );
+    await writeFile(config, (await readFile(config, "utf8")).replace('"medium"', '"high"'));
+    await manager.remove({ projectRoot: root, host: "codex" });
+    expect(await readFile(config, "utf8")).toBe(
+      'model_reasoning_effort = "high"\n# mine\napproval_policy = "never"\n'
+    );
+    await expect(readFile(join(root, ".aidd/main-model.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it("deletes a settings file it created once removeAll reverts it", async () => {
+    await manager.install({ projectRoot: root, host: "opencode", provider: "mistral", main: true });
+    expect(JSON.parse(await readFile(join(root, "opencode.json"), "utf8"))).toStrictEqual({
+      model: "mistral/mistral-large-4",
+    });
+    await manager.removeAll(root);
+    await expect(readFile(join(root, "opencode.json"))).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("installs user-level agents and restores the main model on removal", async () => {
+    const home = join(root, "home");
+    const userRoot = {
+      home,
+      env: (name: string) => (name === "CODEX_HOME" ? join(home, "codex-home") : undefined),
+      configDir: join(home, ".config/aidd"),
+    };
+    const settings = join(home, "codex-home/config.toml");
+    await mkdir(dirname(settings), { recursive: true });
+    await writeFile(settings, 'model = "mine"\n');
+    const user = manager;
+    const target = { projectRoot: root, host: "codex", user: userRoot } as const;
+    expect(await user.install({ ...target, provider: "openai", main: true })).toBe(2);
+    expect(
+      await readFile(join(home, "codex-home/agents/aidd-dev-explorer.toml"), "utf8")
+    ).toContain("Explore");
+    expect(await readFile(settings, "utf8")).toBe(
+      'model_reasoning_effort = "medium"\nmodel = "gpt-6.1-sol"\n'
+    );
+    await expect(readFile(join(root, ".aidd/agents.json"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+    expect(await user.remove(target)).toBe(2);
+    expect(await readFile(settings, "utf8")).toBe('model = "mine"\n');
+  });
+
+  it("removes an unmodified agent whose role is no longer bundled", async () => {
+    await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
+    const { "aidd-dev-reviewer": _, ...remaining } = sources;
+    const next = new ManageAgentsUseCase(fs, store, new HasherAdapter(), remaining);
+    await next.install({ projectRoot: root, host: "codex", provider: "openai" });
+    await expect(
+      readFile(join(root, ".codex/agents/aidd-dev-reviewer.toml"))
+    ).rejects.toMatchObject({ code: "ENOENT" });
+    expect(
+      Object.keys(JSON.parse(await readFile(join(root, ".aidd/agents.json"), "utf8")).codex)
+    ).toEqual(["aidd-dev-explorer"]);
+  });
+
+  it("restores files and both registries when the main model registry cannot be saved", async () => {
+    await manager.install({ projectRoot: root, host: "opencode", provider: "openai" });
+    const ledger = await readFile(join(root, ".aidd/agents.json"), "utf8");
+    vi.spyOn(store, "saveMainModels").mockRejectedValueOnce(new Error("registry refused"));
+    await expect(
+      manager.install({ projectRoot: root, host: "opencode", provider: "anthropic", main: true })
+    ).rejects.toThrow("registry refused");
+    expect(await readFile(join(root, ".aidd/agents.json"), "utf8")).toBe(ledger);
+    await expect(readFile(join(root, "opencode.json"))).rejects.toMatchObject({ code: "ENOENT" });
+    expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
+      "openai/"
+    );
+  });
+
+  it("refuses to bypass an existing opencode.jsonc", async () => {
+    await writeFile(join(root, "opencode.jsonc"), "// mine\n{}\n");
+    await expect(
+      manager.install({ projectRoot: root, host: "opencode", provider: "mistral", main: true })
+    ).rejects.toThrow(/opencode\.jsonc/);
+    await expect(readFile(join(root, "opencode.json"))).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
   it("rolls back a new installation when ownership cannot be saved, then allows retry", async () => {
     vi.spyOn(store, "save").mockRejectedValueOnce(new Error("registry refused"));
     await expect(
@@ -187,7 +277,7 @@ describe("ManageAgentsUseCase", () => {
       "anthropic/claude-haiku-5-5#medium"
     );
     expect(await readFile(join(root, ".opencode/agents/aidd-dev-reviewer.md"), "utf8")).toContain(
-      "anthropic/claude-opus-5-5#medium"
+      "anthropic/claude-sonnet-5-5#medium"
     );
     await writeFile(join(root, ".opencode/agents/aidd-dev-reviewer.md"), "personal edit");
     await expect(
diff --git a/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts b/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
index 34605126e..d1760f6ef 100644
--- a/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
+++ b/cli/tests/contexts/framework/application/clean/clean-opt-in-agents.integration.test.ts
@@ -113,7 +113,7 @@ describe("clean includes opt-in agents", () => {
     await Promise.all([cleaning, installing]);
     expect(await manager.preview(root)).toEqual([{ toolId: "opencode", fileCount: 1 }]);
     expect(await readFile(join(root, ".opencode/agents/aidd-dev-explorer.md"), "utf8")).toContain(
-      "mistral/mistral-small-2603#high"
+      "mistral/mistral-small-latest#high"
     );
     await expect(access(join(root, ".codex/agents/aidd-dev-explorer.toml"))).rejects.toThrow();
     await expect(access(join(root, ".aidd/agents.json.lock"))).rejects.toThrow();
diff --git a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
index 58e564d78..3b1997d0c 100644
--- a/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/formats/agent-models.unit.test.ts
@@ -47,7 +47,7 @@ describe("explicit agent models", () => {
     ["copilot", "anthropic", { model: "claude-haiku-5.5", reasoningEffort: "medium" }],
     ["opencode", "openai", { model: "openai/gpt-6-luna#medium" }],
     ["opencode", "anthropic", { model: "anthropic/claude-haiku-5-5#medium" }],
-    ["opencode", "mistral", { model: "mistral/mistral-small-2603#high" }],
+    ["opencode", "mistral", { model: "mistral/mistral-small-latest#high" }],
     ["cursor", "anthropic", { model: "claude-haiku-5-5[effort=medium]" }],
   ] as const)("serializes %s with the selected %s provider", (host, provider, expected) => {
     for (const role of ["explorer", "executor", "validator"])
@@ -55,14 +55,9 @@ describe("explicit agent models", () => {
   });
 
   it.each([
-    ["claude", "anthropic", { model: "claude-opus-5-5", effort: "medium" }],
     ["codex", "openai", { model: "gpt-6.1-sol", model_reasoning_effort: "medium" }],
     ["copilot", "openai", { model: "gpt-6.1-sol", reasoningEffort: "medium" }],
-    ["copilot", "anthropic", { model: "claude-opus-5.5", reasoningEffort: "medium" }],
     ["opencode", "openai", { model: "openai/gpt-6.1-sol#medium" }],
-    ["opencode", "anthropic", { model: "anthropic/claude-opus-5-5#medium" }],
-    ["opencode", "mistral", { model: "mistral/mistral-large-4#high" }],
-    ["cursor", "anthropic", { model: "claude-opus-5-5[effort=medium]" }],
   ] as const)(
     "shares model and effort between main and review on %s / %s",
     (host, provider, expected) => {
@@ -71,6 +66,41 @@ describe("explicit agent models", () => {
     }
   );
 
+  it.each([
+    [
+      "claude",
+      { model: "claude-opus-5-5", effort: "medium" },
+      { model: "claude-sonnet-5-5", effort: "medium" },
+    ],
+    [
+      "copilot",
+      { model: "claude-opus-5.5", reasoningEffort: "medium" },
+      { model: "claude-sonnet-5.5", reasoningEffort: "medium" },
+    ],
+    [
+      "opencode",
+      { model: "anthropic/claude-opus-5-5#medium" },
+      { model: "anthropic/claude-sonnet-5-5#medium" },
+    ],
+    [
+      "cursor",
+      { model: "claude-opus-5-5[effort=medium]" },
+      { model: "claude-sonnet-5-5[effort=medium]" },
+    ],
+  ] as const)("runs Anthropic's main on Opus and review on Sonnet on %s", (host, main, review) => {
+    expect(agentModelOptions(host, "anthropic", "main")).toStrictEqual(main);
+    expect(agentModelOptions(host, "anthropic", "reviewer")).toStrictEqual(review);
+  });
+
+  it("gives Mistral a larger main model than its reviewer on opencode", () => {
+    expect(agentModelOptions("opencode", "mistral", "main")).toStrictEqual({
+      model: "mistral/mistral-large-4#high",
+    });
+    expect(agentModelOptions("opencode", "mistral", "reviewer")).toStrictEqual({
+      model: "mistral/mistral-medium-latest#high",
+    });
+  });
+
   it.each(["unknown", "constructor", "__proto__", ""])("rejects unconfigured role %s", (role) => {
     expect(() => agentModelOptions("codex", "openai", role)).toThrow(/role.*not configured/);
   });
diff --git a/cli/tests/contexts/tools/domain/formats/main-model-config.unit.test.ts b/cli/tests/contexts/tools/domain/formats/main-model-config.unit.test.ts
new file mode 100644
index 000000000..e1ad9f531
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/formats/main-model-config.unit.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import {
+  mainModelTarget,
+  mainModelValues,
+  planMainModelInstall,
+  planMainModelRemoval,
+} from "../../../../../src/contexts/tools/domain/formats/main-model-config.js";
+
+const codex = { model: "gpt-6.1-sol", model_reasoning_effort: "medium" };
+
+describe("main model settings", () => {
+  it.each([
+    ["claude", "anthropic", { model: "claude-opus-5-5", effortLevel: "medium" }],
+    ["codex", "openai", codex],
+    // OpenCode's root `model` keeps no variant, so no effort is written.
+    ["opencode", "mistral", { model: "mistral/mistral-large-4" }],
+  ] as const)("resolves %s / %s to native settings", (host, provider, expected) => {
+    expect(mainModelValues(host, provider)).toStrictEqual(expected);
+  });
+
+  it.each(["copilot", "cursor"] as const)("leaves %s without a file-based main model", (host) => {
+    expect(mainModelTarget(host)).toBeNull();
+  });
+
+  it("merges JSON settings, keeping other keys, indentation and a BOM", () => {
+    const content = '{\n    "model": "opus",\n    "hooks": { "a": 1 }\n}';
+    const { content: next, record } = planMainModelInstall(
+      content,
+      "json",
+      { model: "x" },
+      undefined
+    );
+    expect(next).toBe('{\n    "model": "x",\n    "hooks": {\n        "a": 1\n    }\n}\n');
+    expect(record).toStrictEqual({
+      written: { model: "x" },
+      previous: { model: "opus" },
+      created: false,
+    });
+    expect(planMainModelRemoval(next, "json", record)).toContain('"model": "opus"');
+  });
+
+  it("refuses JSON it cannot parse instead of overwriting it", () => {
+    expect(() => planMainModelInstall("// mine\n{}", "json", { model: "x" }, undefined)).toThrow();
+  });
+
+  it("edits top-level TOML lines, keeping comments, tables and CRLF endings", () => {
+    const content = '# mine\r\nmodel = "old" # keep\r\n\r\n[profiles.fast]\r\nmodel = "table"\r\n';
+    const { content: next, record } = planMainModelInstall(content, "toml", codex, undefined);
+    expect(next).toBe(
+      'model_reasoning_effort = "medium"\r\n# mine\r\nmodel = "gpt-6.1-sol" # keep\r\n\r\n[profiles.fast]\r\nmodel = "table"\r\n'
+    );
+    expect(planMainModelRemoval(next, "toml", record)).toBe(
+      '# mine\r\nmodel = "old" # keep\r\n\r\n[profiles.fast]\r\nmodel = "table"\r\n'
+    );
+  });
+
+  it.each([
+    ["a multi-line string", 'instructions = """\nmodel = "x"\n"""\n'],
+    ["a quoted key", '"model" = "old"\n'],
+    ["a dotted key", "model.x = 1\n"],
+    ["a multi-line array", 'list = [\n  [1, 2],\n]\nmodel = "old"\n'],
+  ])("refuses to edit TOML with %s", (_, content) => {
+    expect(() => planMainModelInstall(content, "toml", codex, undefined)).toThrow();
+  });
+
+  it("refuses to overwrite a value changed since AIDD set it", () => {
+    const first = planMainModelInstall(null, "json", { model: "x" }, undefined);
+    const edited = first.content.replace('"x"', '"mine"');
+    expect(() => planMainModelInstall(edited, "json", { model: "y" }, first.record)).toThrow(
+      /changed since AIDD/
+    );
+    const again = planMainModelInstall(first.content, "json", { model: "y" }, first.record);
+    expect(again.record.previous).toStrictEqual({ model: null });
+  });
+
+  it("restores only unchanged keys and deletes a file it created once empty", () => {
+    const created = planMainModelInstall(null, "toml", codex, undefined);
+    expect(planMainModelRemoval(created.content, "toml", created.record)).toBeNull();
+    const edited = created.content.replace('"medium"', '"high"');
+    expect(planMainModelRemoval(edited, "toml", created.record)).toBe(
+      'model_reasoning_effort = "high"\n'
+    );
+    const kept = planMainModelInstall("{}", "json", { model: "x" }, undefined);
+    expect(planMainModelRemoval(kept.content, "json", kept.record)).toBe("{}\n");
+  });
+
+  it("leaves unreadable settings untouched on removal", () => {
+    const record = { written: { model: "x" }, previous: { model: null }, created: false };
+    expect(planMainModelRemoval("// broken", "json", record)).toBe("// broken");
+  });
+});
diff --git a/cli/tests/e2e/agents.e2e.test.ts b/cli/tests/e2e/agents.e2e.test.ts
index cf98d8d2b..924952bbf 100644
--- a/cli/tests/e2e/agents.e2e.test.ts
+++ b/cli/tests/e2e/agents.e2e.test.ts
@@ -14,7 +14,7 @@ const cases = [
     ".claude",
     ".md",
     { model: "claude-haiku-5-5", effort: "medium" },
-    { model: "claude-opus-5-5", effort: "medium" },
+    { model: "claude-sonnet-5-5", effort: "medium" },
   ],
   [
     "codex",
@@ -38,7 +38,7 @@ const cases = [
     ".github",
     ".agent.md",
     { model: "claude-haiku-5.5", reasoningEffort: "medium" },
-    { model: "claude-opus-5.5", reasoningEffort: "medium" },
+    { model: "claude-sonnet-5.5", reasoningEffort: "medium" },
   ],
   [
     "opencode",
@@ -54,15 +54,15 @@ const cases = [
     ".opencode",
     ".md",
     { model: "anthropic/claude-haiku-5-5#medium" },
-    { model: "anthropic/claude-opus-5-5#medium" },
+    { model: "anthropic/claude-sonnet-5-5#medium" },
   ],
   [
     "opencode",
     "mistral",
     ".opencode",
     ".md",
-    { model: "mistral/mistral-small-2603#high" },
-    { model: "mistral/mistral-large-4#high" },
+    { model: "mistral/mistral-small-latest#high" },
+    { model: "mistral/mistral-medium-latest#high" },
   ],
   [
     "cursor",
@@ -70,7 +70,7 @@ const cases = [
     ".cursor",
     ".md",
     { model: "claude-haiku-5-5[effort=medium]" },
-    { model: "claude-opus-5-5[effort=medium]" },
+    { model: "claude-sonnet-5-5[effort=medium]" },
   ],
 ] as const;
 
@@ -200,7 +200,9 @@ describe.concurrent("explicit native agent installation", () => {
       for (const role of roles) {
         const content = await readFile(join(directory, `aidd-dev-${role}.md`), "utf8");
         expect(parseFrontmatter(content).frontmatter.model).toBe(
-          role === "reviewer" ? "mistral/mistral-large-4#high" : "mistral/mistral-small-2603#high"
+          role === "reviewer"
+            ? "mistral/mistral-medium-latest#high"
+            : "mistral/mistral-small-latest#high"
         );
       }
       const removed = await runCli(
diff --git a/cli/tests/golden/snapshots/help/surface.json b/cli/tests/golden/snapshots/help/surface.json
index 5840e09e9..c107457a0 100644
--- a/cli/tests/golden/snapshots/help/surface.json
+++ b/cli/tests/golden/snapshots/help/surface.json
@@ -7,17 +7,17 @@
   {
     "invocation": "aidd agents",
     "exitCode": 0,
-    "help": "Usage: aidd agents [options] [command]\n\nOpt in to native specialist agents for this project\n\nOptions:\n  -h, --help         display help for command\n\nCommands:\n  install [options]  Install agents with the selected provider's model and\n                     effort\n  remove [options]   Remove unmodified AIDD agents from this project\n  help [command]     display help for command"
+    "help": "Usage: aidd agents [options] [command]\n\nOpt in to native specialist agents for this project\n\nOptions:\n  -h, --help         display help for command\n\nCommands:\n  install [options]  Install agents with the selected provider's model and\n                     effort\n  remove [options]   Remove unmodified AIDD agents and restore the main model\n                     they replaced\n  help [command]     display help for command"
   },
   {
     "invocation": "aidd agents install",
     "exitCode": 0,
-    "help": "Usage: aidd agents install [options]\n\nInstall agents with the selected provider's model and effort\n\nOptions:\n  --provider <provider>  openai, anthropic, mistral\n  --ide <ide>            claude-code, codex, copilot, opencode, cursor\n  -h, --help             display help for command"
+    "help": "Usage: aidd agents install [options]\n\nInstall agents with the selected provider's model and effort\n\nOptions:\n  --provider <provider>  openai, anthropic, mistral\n  --ide <ide>            claude-code, codex, copilot, opencode, cursor\n  --main                 also set the provider's main session model in the IDE's\n                         settings\n  --scope <scope>        project (default) or user, the IDE's user configuration\n                         directory\n  -h, --help             display help for command"
   },
   {
     "invocation": "aidd agents remove",
     "exitCode": 0,
-    "help": "Usage: aidd agents remove [options]\n\nRemove unmodified AIDD agents from this project\n\nOptions:\n  --ide <ide>  claude-code, codex, copilot, opencode, cursor\n  -h, --help   display help for command"
+    "help": "Usage: aidd agents remove [options]\n\nRemove unmodified AIDD agents and restore the main model they replaced\n\nOptions:\n  --ide <ide>      claude-code, codex, copilot, opencode, cursor\n  --scope <scope>  project (default) or user, the IDE's user configuration\n                   directory\n  -h, --help       display help for command"
   },
   {
     "invocation": "aidd auth",
diff --git a/cli/tests/presentation/commands/agents-wiring.integration.test.ts b/cli/tests/presentation/commands/agents-wiring.integration.test.ts
index f6cb63e32..0be3d5bee 100644
--- a/cli/tests/presentation/commands/agents-wiring.integration.test.ts
+++ b/cli/tests/presentation/commands/agents-wiring.integration.test.ts
@@ -4,9 +4,13 @@ import { agentIdeNames } from "../../../src/contexts/tools/domain/formats/agent-
 
 const install = vi.fn();
 const remove = vi.fn();
+const USER_ROOT = { home: "/home", env: () => undefined, configDir: "/home/.config/aidd" };
 
 vi.mock("../../../src/runtime/wiring/framework.js", () => ({
-  createDeps: vi.fn(async () => ({ manageAgentsUseCase: { install, remove } })),
+  createDeps: vi.fn(async () => ({
+    manageAgentsUseCase: { install, remove },
+    userAgentRoot: USER_ROOT,
+  })),
 }));
 
 const { createDeps } = await import("../../../src/runtime/wiring/framework.js");
@@ -62,15 +66,44 @@ describe("explicit agent command routing", () => {
     expect(await run("agents", "install", "--ide", ide, "--provider", provider)).toBe(
       `4 agent files installed for ${ide}.\n`
     );
-    expect(install).toHaveBeenCalledExactlyOnceWith({ projectRoot: process.cwd(), host, provider });
+    expect(install).toHaveBeenCalledExactlyOnceWith({
+      projectRoot: process.cwd(),
+      host,
+      provider,
+      main: false,
+    });
     expect(remove).not.toHaveBeenCalled();
   });
 
+  it("opts in to the main session model only with --main", async () => {
+    await run("agents", "install", "--ide", "codex", "--provider", "openai", "--main");
+    expect(install).toHaveBeenCalledExactlyOnceWith({
+      projectRoot: process.cwd(),
+      host: "codex",
+      provider: "openai",
+      main: true,
+    });
+  });
+
+  it("targets the IDE's user configuration with --scope user", async () => {
+    await run("agents", "install", "--ide", "codex", "--provider", "openai", "--scope", "user");
+    expect(install).toHaveBeenCalledExactlyOnceWith({
+      projectRoot: process.cwd(),
+      host: "codex",
+      user: USER_ROOT,
+      provider: "openai",
+      main: false,
+    });
+  });
+
   it("removes only the selected IDE's agents without selecting a provider", async () => {
     expect(await run("agents", "remove", "--ide", "codex")).toBe(
       "2 agent files removed for codex.\n"
     );
-    expect(remove).toHaveBeenCalledExactlyOnceWith({ projectRoot: process.cwd(), host: "codex" });
+    expect(remove).toHaveBeenCalledExactlyOnceWith({
+      projectRoot: process.cwd(),
+      host: "codex",
+    });
     expect(install).not.toHaveBeenCalled();
   });
 
diff --git a/cli/tests/runtime/filesystem/atomic-write.integration.test.ts b/cli/tests/runtime/filesystem/atomic-write.integration.test.ts
index 0a053b985..69e3d5c0e 100644
--- a/cli/tests/runtime/filesystem/atomic-write.integration.test.ts
+++ b/cli/tests/runtime/filesystem/atomic-write.integration.test.ts
@@ -1,4 +1,4 @@
-import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { chmod, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -25,6 +25,16 @@ describe("atomicWriteFile", () => {
     expect(await readdir(tempDir)).toStrictEqual(["out.txt"]);
     expect(await readFile(path, "utf-8")).toBe("héllo");
   });
+
+  it.skipIf(process.platform === "win32")("keeps a replaced file's permissions", async () => {
+    const path = join(tempDir, "private.json");
+    await writeFile(path, "{}");
+    await chmod(path, 0o600);
+
+    await atomicWriteFile(path, '{"model":"x"}');
+
+    expect((await stat(path)).mode & 0o777).toBe(0o600);
+  });
 });
 
 describe("HasherAdapter", () => {
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 0731d0497..33ba10c11 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -26,11 +26,21 @@ Add focused roles to your project's AI tool. Installation is explicit; workflows
 
 ## 🧠 Models and IDEs
 
-[agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) assigns every role a `standard` or `light` profile. Each provider defines the profiles' model and effort. Main and review share `standard`; the `main` role is advisory and installation leaves the main session configuration unchanged.
+[agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) assigns each role a profile: `main` for the main session, `standard` for review, `light` for exploration, implementation, and validation. Each provider sets every profile's model and effort, for example Opus, Sonnet, and Haiku for Anthropic. Implementation and validation run on `light` to save cost; edit the role mapping to trade it for quality.
+
+The main session stays as configured unless you add `--main`, which sets the provider's `main` model and keeps every other setting:
+
+| IDE | File | Keys |
+| --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `model`, `effortLevel` |
+| Codex | `.codex/config.toml` | top-level `model`, `model_reasoning_effort`; a selected `profile` still wins, and project files load only for trusted projects |
+| OpenCode | `opencode.json` | `model` only: the root model keeps no variant; refused when `opencode.jsonc` holds the settings |
+
+Copilot and Cursor are left unchanged. AIDD records what it replaced in `.aidd/main-model.json` and restores it on removal; it refuses to overwrite a value you changed since, and refuses TOML it cannot edit line by line safely. Sources checked 2026-10-20: [Claude Code settings](https://code.claude.com/docs/en/settings), [Codex config](https://developers.openai.com/codex/config-reference), [OpenCode V2 models](https://opencode.ai/v2/docs/models#variants).
 
 ## 📦 Install
 
-The CLI command is unreleased. Build the `feature/sub-agents` checkout from the framework root:
+The CLI command is unreleased. Build a framework checkout from its root:
 
 ```sh
 pnpm --dir cli install --frozen-lockfile
@@ -43,7 +53,7 @@ From the target project's root, install with a supported provider and IDE:
 node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
 ```
 
-Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`.
+Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`. Add `--main` to also set the main session model. Add `--scope user` to install into the IDE's user configuration instead (Claude Code, Codex, and OpenCode), with the registry in AIDD's user configuration directory.
 
 ## 🧪 Try a small task
 
@@ -58,7 +68,9 @@ Use host dispatch records to identify the agent and actual model, effort, and ti
 
 ## 🔄 Update or remove
 
-After updating the CLI, rerun the install command to refresh unmodified agents. Plugins and `sync` do not install or refresh this add-on. For framework development, `make reload` installs the agents globally for Claude Code (Anthropic), Codex (OpenAI), and OpenCode (`OPENCODE_AGENT_PROVIDER`, default `anthropic`), overwriting same-named global agent files.
+After updating the CLI, rerun the install command to refresh unmodified agents; agents of retired roles are removed. Plugins and `sync` do not install or refresh this add-on.
+
+For framework development, copy [reload-agents.example.json](../scripts/reload-agents.example.json) to the gitignored `scripts/reload-agents.json` (or point `RELOAD_AGENTS` at another file). `make reload` then runs `agents install --scope user` for each listed IDE with its `provider`, adding `--main` where `"main": true`. Without the file, reload installs no agent.
 
 To remove only one IDE's agents from the current project:
 
@@ -66,12 +78,12 @@ To remove only one IDE's agents from the current project:
 node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
 ```
 
-The other IDEs' agents remain installed. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including all managed agents.
+The other IDEs' agents remain installed; add `--scope user` for user-level agents. Removal also restores the main model it replaced. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including all managed agents.
 
 ## 🚧 Beta limitations
 
 - **Runtime selection:** verify the host actually uses the configured model and effort during your trial.
-- **Interrupted command:** inspect the native files and registry before clearing `.aidd/agents.json.lock`; confirm no installation or removal is still running. Handled write failures restore the previous agent files.
+- **Interrupted command:** inspect the native files and registry before clearing `.aidd/agents.json.lock`; confirm no installation or removal is still running. Handled write failures restore the previous agent files, settings, and registries.
 
 ## 📝 Share a trial
 
@@ -89,8 +101,8 @@ Copy one report per trial:
 
 ## 💡 Model notes
 
-Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`. [Mistral Small 4](https://docs.mistral.ai/models/mistral-small-4-0-26-03) uses the API ID `mistral-small-2603`, checked 2026-10-16.
+Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`. Review and light roles use the `mistral-medium-latest` and `mistral-small-latest` aliases, which resolved to Medium 3.5 and [Small 4](https://docs.mistral.ai/models/mistral-small-4-0-26-03) on 2026-10-20, so they follow Mistral's updates. The main session pins [`mistral-large-4`](https://docs.mistral.ai/models/mistral-large-4-0) (public preview): `mistral-large-latest` still resolved to Large 3, without reasoning levels, in OpenCode's model list on 2026-10-20. Medium 3.5 is also a public preview.
 
 Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
 
-Sources checked 2026-10-16: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4 (public preview)](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants), [Copilot model IDs](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#supported-models). These recommendations are not a comparative benchmark or proof of account access.
+Sources checked 2026-10-16, Mistral and Claude Sonnet 2026-10-20: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Medium 3.5 (public preview)](https://mistral.ai/news/vibe-remote-agents-mistral-medium-3-5), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants), [Copilot model IDs](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#supported-models). These recommendations are not a comparative benchmark or proof of account access.

From 2f33c50415db2a5958d297c36688dd3ce0f1e461 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 20 Oct 2026 19:12:20 +0800
Subject: [PATCH 50/73] feat(framework): reload installs opted-in user agents
 first

make reload reads the gitignored scripts/reload-agents.json and runs agents install --scope user per IDE before any plugin change, naming each skipped IDE.
---
 .gitignore                         |   3 +
 aidd_docs/memory/deployment.md     |   2 +-
 scripts/__tests__/dev-sync.test.js | 106 +++++++++++++++++++++--------
 scripts/dev-sync.sh                |  83 +++++++++++-----------
 scripts/reload-agents.example.json |   5 ++
 5 files changed, 131 insertions(+), 68 deletions(-)
 create mode 100644 scripts/reload-agents.example.json

diff --git a/.gitignore b/.gitignore
index dd4852527..00f6e7048 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,3 +60,6 @@ temp/
 tmp/
 setup-test/
 tmp-test/
+
+# Personal make reload agent opt-in (see scripts/reload-agents.example.json)
+scripts/reload-agents.json
diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index 89b7d4c4e..94e6c45b7 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -58,7 +58,7 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 ## Local reload
 
-`make reload` syncs all plugins and generic delegation guidance to installed hosts; details in `scripts/dev-sync.sh`.
+`make reload` syncs all plugins and generic delegation guidance to installed hosts, and the agents opted in by the gitignored `scripts/reload-agents.json`; details in `scripts/dev-sync.sh`.
 
 ## Monitoring
 
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index fcd0e2994..5169be5a4 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -815,39 +815,91 @@ for (const override of ["CLAUDE_CONFIG_DIR", "CLAUDE_INSTRUCTIONS"]) {
   });
 }
 
-test("reload with a built CLI installs agents globally and keeps other agents", () => {
-  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-global-agents-"));
-  try {
-    const fakeBin = join(root, "bin"), home = join(root, "home");
-    mkdirSync(fakeBin);
-    const source = fixture(home);
-    mkdirSync(join(source, "cli/dist"), { recursive: true });
-    writeFileSync(join(source, "cli/dist/cli.js"), String.raw`
-const { mkdirSync, writeFileSync } = require("node:fs");
+/** A built CLI and host stubs that log every call, so order and flags are observable. */
+function optInFixture(root, optIn, hosts = ["claude", "codex", "opencode"]) {
+  const fakeBin = join(root, "bin"), home = join(root, "home");
+  mkdirSync(fakeBin);
+  mkdirSync(home);
+  const source = fixture(home);
+  if (optIn !== undefined) {
+    mkdirSync(join(source, "scripts"), { recursive: true });
+    writeFileSync(join(source, "scripts/reload-agents.json"), typeof optIn === "string" ? optIn : JSON.stringify(optIn));
+  }
+  mkdirSync(join(source, "cli/dist"), { recursive: true });
+  writeFileSync(join(source, "cli/dist/cli.js"), String.raw`
+const { appendFileSync, mkdirSync, writeFileSync } = require("node:fs");
 const args = process.argv.slice(2);
-if (args[0] !== "agents") { mkdirSync(args[args.indexOf("--out") + 1] + "/.opencode/skills/aidd-dev-01-plan", { recursive: true }); writeFileSync(args[args.indexOf("--out") + 1] + "/.opencode/skills/aidd-dev-01-plan/SKILL.md", "skill\n"); process.exit(0); }
-const ide = args[args.indexOf("--ide") + 1], provider = args[args.indexOf("--provider") + 1];
-const [dir, ext] = { "claude-code": [".claude", "md"], codex: [".codex", "toml"], opencode: [".opencode", "md"] }[ide];
-mkdirSync(dir + "/agents", { recursive: true });
-writeFileSync(dir + "/agents/aidd-dev-executor." + ext, ide + " " + provider + "\n");
+if (args[0] !== "agents") {
+  const out = args[args.indexOf("--out") + 1] + "/.opencode/skills/aidd-dev-01-plan";
+  mkdirSync(out, { recursive: true });
+  writeFileSync(out + "/SKILL.md", "skill\n");
+  process.exit(0);
+}
+appendFileSync(process.env.HOME + "/calls.log", "cli " + args.join(" ") + "\n");
+if (args.includes("cursor")) { console.error("cursor has no user-level agents."); process.exit(1); }
 `);
-    for (const host of ["claude", "codex", "opencode"]) executable(join(fakeBin, host), "exit 0");
-    const dirs = { claude: ".claude/agents", codex: ".codex/agents", opencode: ".config/opencode/agents" };
-    for (const dir of Object.values(dirs)) {
-      mkdirSync(join(home, dir), { recursive: true });
-      writeFileSync(join(home, dir, "personal.md"), "keep\n");
-    }
-    writeFileSync(join(home, dirs.codex, "aidd-dev-executor.toml"), "old\n");
-    const result = runSync(fakeBin, home, [], { OPENCODE_AGENT_PROVIDER: "mistral" });
+  for (const host of hosts) executable(join(fakeBin, host), `echo "${host} $*" >> "$HOME/calls.log"`);
+  const calls = () => (existsSync(join(home, "calls.log")) ? readFileSync(join(home, "calls.log"), "utf8") : "");
+  return { fakeBin, home, calls };
+}
+
+test("reload installs opted-in user agents first, with --main only where asked", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-agents-"));
+  try {
+    const { fakeBin, home, calls } = optInFixture(root, {
+      "claude-code": { provider: "anthropic", main: true },
+      codex: { provider: "openai" },
+    });
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /global agents\s+claude-code:ok\+main codex:ok\n/);
+    const lines = calls().trim().split("\n");
+    assert.deepEqual(lines.slice(0, 2), [
+      "cli agents install --scope user --ide claude-code --provider anthropic --main",
+      "cli agents install --scope user --ide codex --provider openai",
+    ]);
+    assert.ok(lines.length > 2, "plugins still install after the agents");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("reload without an opt-in file installs no agent", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-no-opt-in-"));
+  try {
+    const { fakeBin, home, calls } = optInFixture(root);
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout, /global agents/);
+    assert.doesNotMatch(calls(), /cli agents/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("reload names an opted-in IDE it skips", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-skip-"));
+  try {
+    const { fakeBin, home, calls } = optInFixture(root, { codex: { provider: "openai" } }, ["claude"]);
+    const result = runSync(fakeBin, home, []);
     assert.equal(result.status, 0, result.stderr);
-    assert.match(result.stdout, /global agents\s+claude-code:ok codex:ok opencode:ok/);
-    assert.equal(readFileSync(join(home, dirs.claude, "aidd-dev-executor.md"), "utf8"), "claude-code anthropic\n");
-    assert.equal(readFileSync(join(home, dirs.codex, "aidd-dev-executor.toml"), "utf8"), "codex openai\n");
-    assert.equal(readFileSync(join(home, dirs.opencode, "aidd-dev-executor.md"), "utf8"), "opencode mistral\n");
-    for (const dir of Object.values(dirs)) assert.equal(readFileSync(join(home, dir, "personal.md"), "utf8"), "keep\n");
+    assert.match(result.stdout, /global agents\s+codex:skip\(not installed\)/);
+    assert.doesNotMatch(calls(), /cli agents/);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
+for (const [label, optIn, error] of [
+  ["a refused IDE", { cursor: { provider: "anthropic" } }, /cursor has no user-level agents/],
+  ["an invalid entry", { codex: { provider: "openai", main: "yes" } }, /Invalid agent opt-in file/],
+]) {
+  test(`reload stops on ${label} before changing any plugin`, () => {
+    const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-bad-opt-in-"));
+    try {
+      const { fakeBin, home, calls } = optInFixture(root, optIn);
+      const result = runSync(fakeBin, home, []);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stderr, error);
+      assert.doesNotMatch(calls(), /^(claude|codex|opencode) /m);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+}
+
 test("Codex reload without a built CLI leaves agents unchanged", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-codex-personal-"));
   try {
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 7ae5390b5..5908d2f54 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -7,12 +7,9 @@
 # whose CLI is absent is skipped, and the first run needs network. A managed OpenCode host
 # exposes `aidd-opencode-reload` instead, and that helper decides which checkout may load.
 #
-# Agents: with a built local CLI, reload installs the AIDD agents globally for Claude, Codex and
-# local OpenCode, overwriting only the files that install generates; other agents stay untouched.
-# Global agent directories checked 2026-10-20:
-# https://code.claude.com/docs/en/sub-agents
-# https://developers.openai.com/codex/subagents
-# https://opencode.ai/docs/agents
+# Agents are opt-in through the gitignored scripts/reload-agents.json (or RELOAD_AGENTS; see
+# reload-agents.example.json): each listed IDE runs `aidd agents install --scope user`, adding
+# `--main` when `"main": true`. They run first, so a bad entry fails before any plugin changes.
 # Global rules: sync only the Agents section in the managed block, preserving personal
 # rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
 # Paths honor native home/cache overrides; explicit task paths take precedence.
@@ -43,10 +40,7 @@ CODEX_CACHE="${CODEX_CACHE:-${CODEX_HOME:-$HOME/.codex}/plugins/cache}"
 CLAUDE_CACHE="${CLAUDE_CACHE:-${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/cache}"
 OPENCODE_SKILLS="${OPENCODE_SKILLS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills}"
 CURSOR_PLUGINS="${CURSOR_PLUGINS:-$HOME/.cursor/plugins/local}"
-CLAUDE_AGENTS="${CLAUDE_AGENTS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents}"
-CODEX_AGENTS="${CODEX_AGENTS:-${CODEX_HOME:-$HOME/.codex}/agents}"
-OPENCODE_AGENTS="${OPENCODE_AGENTS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/agents}"
-OPENCODE_AGENT_PROVIDER="${OPENCODE_AGENT_PROVIDER:-anthropic}"  # openai, anthropic or mistral
+RELOAD_AGENTS="${RELOAD_AGENTS:-$FW/scripts/reload-agents.json}"
 CODEX_INSTRUCTIONS="${CODEX_INSTRUCTIONS:-${CODEX_HOME:-$HOME/.codex}/AGENTS.md}"
 CLAUDE_INSTRUCTIONS="${CLAUDE_INSTRUCTIONS:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md}"
 OPENCODE_INSTRUCTIONS="${OPENCODE_INSTRUCTIONS:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md}"
@@ -129,17 +123,43 @@ sync_opencode_skills() {
   done
 }
 
-install_global_agents() {
-  # Generate the project-scoped agents in a staging root, then copy exactly those files globally.
-  local ide="$1" provider="$2" native_dir="$3" destination="$4" stage file
-  local -a files
-  stage="$BUILD/agents/$ide"
-  rm -rf "$stage"; mkdir -p "$stage"
-  (cd "$stage" && node "$FW/cli/dist/cli.js" agents install --ide "$ide" --provider "$provider" >/dev/null) || return 1
-  files=("$stage/$native_dir/agents/"*)
-  [ "${#files[@]}" -gt 0 ] || { echo "no agents generated for $ide" >&2; return 1; }
-  mkdir -p "$destination"
-  for file in "${files[@]}"; do cp "$file" "$destination/"; done
+install_opted_in_agents() {
+  # The CLI owns paths, ownership and refusals; this only maps the opt-in file to its flags.
+  [ -f "$RELOAD_AGENTS" ] || return 0
+  local opted_in ide provider main have result
+  opted_in="$(node -e '
+    const file = process.argv[1];
+    const config = JSON.parse(require("node:fs").readFileSync(file, "utf8"));
+    const text = (value) => typeof value === "string" && /^[\w.-]+$/.test(value);
+    for (const [ide, entry] of Object.entries(config)) {
+      if (!text(ide) || !text(entry?.provider)) throw new Error(`${file}: ${ide} needs a provider`);
+      if (entry.main !== undefined && typeof entry.main !== "boolean")
+        throw new Error(`${file}: ${ide}.main must be true or false`);
+      console.log(`${ide}\t${entry.provider}\t${entry.main === true}`);
+    }
+  ' "$RELOAD_AGENTS")" || { echo "Invalid agent opt-in file: $RELOAD_AGENTS" >&2; return 1; }
+  [ -n "$opted_in" ] || return 0
+  printf '%-22s' "global agents"
+  if [ ! -f "$FW/cli/dist/cli.js" ]; then echo " skip (no built CLI; run make reload)"; return 0; fi
+  while IFS=$'\t' read -r ide provider main; do
+    case "$ide" in
+      claude-code) have="$HAVE_CLAUDE" ;;
+      codex) have="$HAVE_CODEX" ;;
+      opencode) have="$HAVE_OPENCODE"; [ "$HAVE_MANAGED_OPENCODE" = 0 ] || have=managed ;;
+      *) have=1 ;;  # the CLI rejects an IDE without user-level agents
+    esac
+    case "$have" in
+      0) printf ' %s:skip(not installed)' "$ide"; continue ;;
+      managed) printf ' %s:skip(managed host)' "$ide"; continue ;;
+    esac
+    local -a args=(agents install --scope user --ide "$ide" --provider "$provider")
+    [ "$main" != true ] || args+=(--main)
+    if ! result="$(node "$FW/cli/dist/cli.js" "${args[@]}" 2>&1)"; then
+      echo " $ide:FAIL"; printf '%s\n' "$result" >&2; return 1
+    fi
+    if [ "$main" = true ]; then printf ' %s:ok+main' "$ide"; else printf ' %s:ok' "$ide"; fi
+  done <<<"$opted_in"
+  echo
 }
 
 register_marketplace() {
@@ -222,6 +242,8 @@ if [ "$HAVE_CODEX" = 0 ] && [ "$HAVE_CLAUDE" = 0 ] && [ "$HAVE_OPENCODE" = 0 ] &
   echo "No supported host installation found - nothing to install."; exit 0
 fi
 
+install_opted_in_agents || exit 1
+
 targets=()
 for d in "$FW"/plugins/*/; do targets+=("$(basename "$d")"); done
 
@@ -276,25 +298,6 @@ if [ "$HAVE_CURSOR" = 1 ]; then
   echo "plugins:ok (requires local plugin imports)"
 fi
 
-if [ -f "$FW/cli/dist/cli.js" ]; then
-  agent_hosts=()
-  [ "$HAVE_CLAUDE" = 0 ] || agent_hosts+=("claude-code anthropic .claude $CLAUDE_AGENTS")
-  [ "$HAVE_CODEX" = 0 ] || agent_hosts+=("codex openai .codex $CODEX_AGENTS")
-  if [ "$HAVE_OPENCODE" = 1 ] && [ "$HAVE_MANAGED_OPENCODE" = 0 ]; then
-    agent_hosts+=("opencode $OPENCODE_AGENT_PROVIDER .opencode $OPENCODE_AGENTS")
-  fi
-  if [ "${#agent_hosts[@]}" -gt 0 ]; then
-    printf '%-22s' "global agents"
-    for entry in "${agent_hosts[@]}"; do
-      read -r ide provider native_dir destination <<<"$entry"
-      install_global_agents "$ide" "$provider" "$native_dir" "$destination" ||
-        { echo " $ide:FAIL"; echo "Agent install failed for $ide; rerun node $FW/cli/dist/cli.js agents install --ide $ide --provider $provider in a scratch directory for details." >&2; exit 1; }
-      printf ' %s:ok' "$ide"
-    done
-    echo
-  fi
-fi
-
 instructions=()
 [ "$HAVE_CODEX" = 0 ] || instructions+=(codex "$CODEX_INSTRUCTIONS")
 [ "$HAVE_CLAUDE" = 0 ] || instructions+=(claude "$CLAUDE_INSTRUCTIONS")
diff --git a/scripts/reload-agents.example.json b/scripts/reload-agents.example.json
new file mode 100644
index 000000000..03755702f
--- /dev/null
+++ b/scripts/reload-agents.example.json
@@ -0,0 +1,5 @@
+{
+  "claude-code": { "provider": "anthropic" },
+  "codex": { "provider": "openai" },
+  "opencode": { "provider": "anthropic", "main": false }
+}

From 2372078e4ea8e69a69cac7ffb21e4f4ab46fe146 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 20 Oct 2026 19:13:25 +0800
Subject: [PATCH 51/73] docs(framework): align delegation guidance with the
 four agents

Give the challenge an independent owner and the caller the review report, match the deliver diagram to its text, merge the duplicated fan-out rule, drop the stale checker wording and the empty agents badge.
---
 AGENTS.md                                                   | 3 +--
 .../skills/02-project-memory/assets/templates/AGENTS.md     | 3 +--
 plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md | 2 +-
 .../skills/01-sdlc/references/02-deliver.md                 | 6 +++---
 .../aidd-orchestrator/skills/01-sdlc/references/03-check.md | 6 +++---
 scripts/sync-readme-counts.mjs                              | 3 ++-
 6 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index fe7637c63..e29868b44 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,13 +28,12 @@
 - **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
 
-Use available host agents by responsibility when useful; custom agents are optional. The caller owns scope, delegation, and final acceptance.
+When you own the overall flow, fan out genuinely parallel subtasks to available host agents by responsibility; custom agents are optional. The caller owns scope, delegation, and final acceptance.
 
 ## Memory Management
 
diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
index 75f6097c5..f0f666538 100644
--- a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
+++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
@@ -31,12 +31,11 @@
 - **Verify APIs, signatures, flags, and behavior against source or docs.**
 - **Ask one sharp question when ambiguity materially changes the scope or outcome.**
 - **Batch independent operations when it saves time or context.**
-- **Fan out genuinely independent subtasks when coordination costs less than serial work.**
 - **Name by intention, scope by responsibility** ; not mechanism.
 
 ## Agents
 
-Use available host agents by responsibility when useful; custom agents are optional. The caller owns scope, delegation, and final acceptance.
+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.
 
 ## Memory Management
 
diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md
index e5f274b24..fbb3f1212 100644
--- a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md
+++ b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md
@@ -49,7 +49,7 @@ status: pending
 
 ## Applicable rules
 
-<!-- Generated by the project's rule-inventory step. The checker uses this list to verify the implementation. `none` if no installed tool has rules. -->
+<!-- Generated by the project's rule-inventory step. Independent validation uses this list to verify the implementation. `none` if no installed tool has rules. -->
 
 | Tool   | Name   | Path                                  | Why it applies |
 | ------ | ------ | ------------------------------------- | -------------- |
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index c2768e271..9cef84395 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -40,9 +40,9 @@ flowchart TD
   Plan --> PlanArtifact
   PlanArtifact -- "Whole plan, or ready independent phases." --> Executor
   Executor -- "Assigned plan or phase." --> Implement
-  Implement -- "Whole plan finalized." --> Commit
-  Implement -- "Assigned phase returned." --> Assert
-  Assert --> Integrate
+  Implement --> Assert
+  Assert -- "Whole plan finalized." --> Commit
+  Assert -- "Assigned phase returned." --> Integrate
   Integrate -- "More ready phases." --> Executor
   Integrate --> Finalize
   Finalize -- "Validation or journey failed; repair affected phase." --> Executor
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index 66c826d2f..7c22a6a44 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -3,8 +3,8 @@
 ## Behavior
 
 - **Validate the committed candidate** against the contract, criteria, and mandatory checks using a fresh agent.
-- **Review quality and coherence** with a fresh agent after validation passes; select code and relevancy axes, using the acceptance evidence.
-- **Challenge the outcome** after review clears: verify that it is trustworthy and serves the user.
+- **Review quality and coherence** with a fresh agent after validation passes, on the code and relevancy axes using the acceptance evidence; record its findings through `/aidd-dev:05-review`.
+- **Challenge the outcome** with another fresh agent after review clears, not the one that sequenced delivery: verify that it is trustworthy and serves the user.
 
 ## Findings
 
@@ -61,7 +61,7 @@ flowchart TD
   ValidationReports --> Validator
   Validator -- "All criteria pass with evidence." --> Reviewer
   Validator -- "Fail or blocked." --> Findings
-  Reviewer -- "Code and relevancy axes." --> Review
+  Reviewer -- "Caller records code and relevancy findings." --> Review
   Review -- "Return actionable review findings." --> Findings
   Review -- "When the review clears, challenge the outcome." --> Challenge
   Challenge -- "Return actionable challenge findings." --> Findings
diff --git a/scripts/sync-readme-counts.mjs b/scripts/sync-readme-counts.mjs
index 6c47ae300..b97739e7c 100644
--- a/scripts/sync-readme-counts.mjs
+++ b/scripts/sync-readme-counts.mjs
@@ -31,7 +31,8 @@ const totalAgents = plugins.reduce((n, p) => n + agentsOf(p), 0);
 let md = readFileSync(README, "utf8");
 const before = md;
 
-const hero = `<kbd>${totalPlugins} plugins</kbd> · <kbd>${totalSkills} skills</kbd> · <kbd>${totalAgents} agents</kbd>`;
+const hero = `<kbd>${totalPlugins} plugins</kbd> · <kbd>${totalSkills} skills</kbd>` +
+  (totalAgents ? ` · <kbd>${totalAgents} agents</kbd>` : "");
 md = md.replace(/<!--counts:start-->[\s\S]*?<!--counts:end-->/, `<!--counts:start-->${hero}<!--counts:end-->`);
 
 for (const name of plugins) {

From fc12df3e4e4f1f56b2148c1f7bc9fbe750afad62 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 20 Oct 2026 19:14:19 +0800
Subject: [PATCH 52/73] docs(framework): keep sub-agent verification to the
 current state

Drop the raw runtime and comparison captures; summarize earlier probes in verification.md.
---
 .../2026_10_14_sub_agents/comparison.json     |  72 ----
 .../2026_10/2026_10_14_sub_agents/review.md   |   2 +-
 .../2026_10_14_sub_agents/runtime.json        | 388 ------------------
 .../2026_10_14_sub_agents/verification.md     | 139 +------
 4 files changed, 16 insertions(+), 585 deletions(-)
 delete mode 100644 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json
 delete mode 100644 aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json

diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json
deleted file mode 100644
index 4a5f3de01..000000000
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/comparison.json
+++ /dev/null
@@ -1,72 +0,0 @@
-{
-  "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."
-}
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
index 58bff11bf..0bfb96805 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/review.md
@@ -1,6 +1,6 @@
 # Review: scoped sub-agents
 
-- Rounds: 4
+- Rounds: 5
 - Started: 2026-10-15
 
 ## Round 1 · r-1fd6
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
deleted file mode 100644
index 4bb859fe7..000000000
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/runtime.json
+++ /dev/null
@@ -1,388 +0,0 @@
-{
-  "candidate": "6194ce7aabd1e27622a35851019fddd165f84c21",
-  "scope": "Historical runtime probes before CLI-installed model defaults",
-  "date": "2026-10-15",
-  "source_agent_sha256": {
-    "explorer": "735e8f34797b47acd1763cb0c84553974b82c4cf0601fbba0726c1fc5310b862",
-    "executor": "74b452270857e829d0aeacc0f5cc1385a18b07fb6205c5604051a9115fd2a2c7",
-    "validator": "9057daca0887fdb3ebbcbd64a4b2de1fe21827891cde7fd8575fac67d5e3e2c2",
-    "reviewer": "100772a0c72cd3bcd390db115abe738a1ad27e5112df5d81fe8ee2e4b83b4ba2"
-  },
-  "hosts": {
-    "claude": {
-      "version": "2.1.300",
-      "distribution": "flat, disposable projects",
-      "roles": [
-        "aidd-dev-explorer",
-        "aidd-dev-executor",
-        "aidd-dev-validator",
-        "aidd-dev-reviewer"
-      ],
-      "models_observed": [
-        "claude-opus-5-5",
-        "claude-haiku-5-5"
-      ],
-      "effort_requested": "low",
-      "effort_source": "Native Agent calls carry effort low; JSON modelUsage does not independently echo effective effort.",
-      "behavior": "Explorer cites exact source. Executor writes only eight assigned modules; independent checks pass. Validator accepts 5000 and rejects 5001 against the actual file. Reviewer identifies duplicated bodies."
-    },
-    "codex": {
-      "version": "0.145.0",
-      "distribution": "user flat agent",
-      "parent_thread": "01a13df8-fce3-71e2-b1c7-03579c9e56aa",
-      "turn_context": {
-        "model": "gpt-5.6-sol",
-        "effort": "low"
-      },
-      "limitation": "The signed-in backend rejected gpt-6-luna and gpt-6.1-sol. The successful probe used gpt-5.6-sol.",
-      "children": [
-        {
-          "thread": "01a13df9-1c68-7c03-ac4e-5fe6c7ffe6e5",
-          "role": "aidd-dev-explorer",
-          "model": "gpt-5.6-sol",
-          "effort": "low"
-        },
-        {
-          "thread": "01a13df9-4aab-7fa2-a021-90fd6b8bb4bf",
-          "role": "aidd-dev-executor",
-          "model": "gpt-5.6-sol",
-          "effort": "low"
-        },
-        {
-          "thread": "01a13df9-98ed-7df1-9a88-b005256c999f",
-          "role": "aidd-dev-validator",
-          "model": "gpt-5.6-sol",
-          "effort": "low"
-        },
-        {
-          "thread": "01a13df9-e4d0-79c0-8c8c-085cbfa4462a",
-          "role": "aidd-dev-reviewer",
-          "model": "gpt-5.6-sol",
-          "effort": "low"
-        }
-      ],
-      "behavior": "Four fresh native roles completed: actual source lookup, text implementation, rejection of false criterion, independent quality review. No file changes."
-    },
-    "opencode": {
-      "version": "2.0.28",
-      "distribution": "Generated project flat agents",
-      "invocation": "opencode run --standalone --auto --model 'openai/gpt-6.1-sol#medium' --format json <bounded-four-role-prompt>",
-      "session": "ses_ec1fdc64bffesN0k62QmtBd5yA",
-      "exit": 0,
-      "children": [
-        {
-          "session": "ses_ec1fdb057ffeurGEXTwfPaJV2I",
-          "role": "aidd-dev-explorer",
-          "model": {
-            "id": "gpt-6.1-sol",
-            "providerID": "openai",
-            "variant": "medium"
-          },
-          "finish": "stop"
-        },
-        {
-          "session": "ses_ec1fd8488ffeG3OHfopYCMwrD1",
-          "role": "aidd-dev-executor",
-          "model": {
-            "id": "gpt-6.1-sol",
-            "providerID": "openai",
-            "variant": "medium"
-          },
-          "finish": "stop"
-        },
-        {
-          "session": "ses_ec1fd501cffeNLHTFOGKmI8qA6",
-          "role": "aidd-dev-validator",
-          "model": {
-            "id": "gpt-6.1-sol",
-            "providerID": "openai",
-            "variant": "medium"
-          },
-          "finish": "stop"
-        },
-        {
-          "session": "ses_ec1fd1f7cffejVCvM1x5kW34Ep",
-          "role": "aidd-dev-reviewer",
-          "model": {
-            "id": "gpt-6.1-sol",
-            "providerID": "openai",
-            "variant": "medium"
-          },
-          "finish": "stop"
-        }
-      ],
-      "metadata_source": "GET /api/session/<child-session>/message through the native opencode api --standalone command",
-      "behavior": "Four fresh native roles completed: actual source lookup, text implementation, rejection of the false threshold 5001, and independent quality review. No file changes.",
-      "limitation": "Earlier Luna/low run recovered a provider transport timeout but returned CLI exit 1; it is not counted as a clean pass."
-    },
-    "copilot": {
-      "version": "1.0.98",
-      "distribution": "generated marketplace plugin, native --plugin-dir",
-      "roles": [
-        {
-          "agentName": "aidd-dev:explorer",
-          "model": "gpt-6-luna",
-          "firstDispatchedModel": "gpt-6-luna",
-          "modelSelectionSource": "session_inheritance",
-          "totalToolCalls": 0,
-          "totalTokens": 2214,
-          "durationMs": 23668
-        },
-        {
-          "agentName": "aidd-dev:executor",
-          "model": "gpt-6-luna",
-          "firstDispatchedModel": "gpt-6-luna",
-          "modelSelectionSource": "session_inheritance",
-          "totalToolCalls": 0,
-          "totalTokens": 2325,
-          "durationMs": 7324
-        },
-        {
-          "agentName": "aidd-dev:reviewer",
-          "model": "gpt-6-luna",
-          "firstDispatchedModel": "gpt-6-luna",
-          "modelSelectionSource": "session_inheritance",
-          "totalToolCalls": 0,
-          "totalTokens": 2335,
-          "durationMs": 7921
-        },
-        {
-          "agentName": "aidd-dev:validator",
-          "model": "gpt-6-luna",
-          "firstDispatchedModel": "gpt-6-luna",
-          "modelSelectionSource": "session_inheritance",
-          "totalToolCalls": 0,
-          "totalTokens": 2218,
-          "durationMs": 8514
-        }
-      ],
-      "explicit_override": {
-        "session_id": "8f84d0b3-105d-4f7e-afc5-49fa240f07db",
-        "agent_id": "78c9d4e7-bb5f-480f-bfba-d52e5284d75d",
-        "parent_tool_call_id": "call_Ye8vaSjxNF1gofK7fYv4IUht",
-        "model": "gpt-6-luna",
-        "reasoning_effort": "medium",
-        "reasoning_tokens": 11,
-        "input_tokens": 856,
-        "output_tokens": 22,
-        "created_at": "2026-10-15T04:03:03.366Z"
-      },
-      "limitation": "Native per-call model override verified. A requested low effort produced medium; the exact normalization or override cause is unverified."
-    },
-    "cursor": {
-      "version": "2026.10.14-941492e",
-      "distribution": "Real user plugins/local install; automatic discovery without --plugin-dir",
-      "roles": [
-        {
-          "name": "aidd-dev-explorer",
-          "model": "default",
-          "success": true,
-          "error": null,
-          "durationMs": "26299"
-        },
-        {
-          "name": "aidd-dev-executor",
-          "model": "default",
-          "success": true,
-          "error": null,
-          "durationMs": "6110"
-        },
-        {
-          "name": "aidd-dev-reviewer",
-          "model": "default",
-          "success": true,
-          "error": null,
-          "durationMs": "39048"
-        },
-        {
-          "name": "aidd-dev-validator",
-          "model": "default",
-          "success": true,
-          "error": null,
-          "durationMs": "8673"
-        }
-      ],
-      "read_tools": [
-        {
-          "role": "aidd-dev-explorer",
-          "tool": "Read",
-          "path": "/tmp/aidd-983-claude-flat/src/config.cjs"
-        },
-        {
-          "role": "aidd-dev-reviewer",
-          "tool": "Read",
-          "path": "/Users/alexsoyes/.cursor/plugins/local/aidd-dev/skills/05-review/SKILL.md"
-        },
-        {
-          "role": "aidd-dev-reviewer",
-          "tool": "Read",
-          "path": "/Users/alexsoyes/.cursor/plugins/local/aidd-dev/skills/05-review/references/quality-checklist.md"
-        },
-        {
-          "role": "aidd-dev-reviewer",
-          "tool": "Read",
-          "path": "/tmp/aidd-983-claude-flat/src/config.cjs"
-        },
-        {
-          "role": "aidd-dev-reviewer",
-          "tool": "Read",
-          "path": "/tmp/aidd-983-aidd-roles/workspace/sample.js"
-        },
-        {
-          "role": "aidd-dev-reviewer",
-          "tool": "Read",
-          "path": "/Users/alexsoyes/.cursor/plugins/local/aidd-dev/skills/05-review/references/prepare.md"
-        },
-        {
-          "role": "aidd-dev-validator",
-          "tool": "Read",
-          "path": "/tmp/aidd-983-claude-flat/src/config.cjs"
-        }
-      ],
-      "actual_backend_model": "unverified under Auto",
-      "actual_effort": "unverified",
-      "limitation": "Auto/inheritance verified. Named model rejected by Free plan; backend identity and effort not exposed by these traces.",
-      "installation": "Current official CLI ran from an isolated download. The globally installed older Cursor CLI was not upgraded."
-    }
-  },
-  "reload": {
-    "plugins": 9,
-    "hosts": [
-      "claude",
-      "codex",
-      "opencode",
-      "copilot",
-      "cursor"
-    ],
-    "exit": 0,
-    "personal_agents_preserved": 28,
-    "personal_instruction_files_preserved": 3,
-    "global_block": "agent table only"
-  },
-  "whole_plan_finalization": {
-    "host": "Claude Code 2.1.300",
-    "model": "claude-haiku-5-5",
-    "native_skill": "aidd-dev:02-implement",
-    "session": "26945ad0-9d47-4b4e-89d8-ae53d27ded2a",
-    "source_outcome": "module.exports = { answer: 42 };",
-    "events": [
-      "check",
-      "journey"
-    ],
-    "plan_implemented": true,
-    "phase_done": true,
-    "journey_before_mark": "Native Bash journey call precedes final plan Edit; no subsequent validation command.",
-    "git_operations": "No commits or pushes; baseline branch preserved.",
-    "scope": "Disposable project. Guard rejects checks after the final journey; journey rejects an already implemented plan."
-  },
-  "resolver": {
-    "config_unchanged": true,
-    "five_hosts": [
-      {
-        "host": "claude",
-        "agent": "aidd-dev:explorer",
-        "mode": "marketplace",
-        "requested": {
-          "model": "haiku",
-          "effort": "low"
-        },
-        "native": {
-          "model": "haiku",
-          "effort": "low"
-        },
-        "nativeSurface": "agent-configuration",
-        "effectiveRuntime": "unknown",
-        "missing_task_inherits": true
-      },
-      {
-        "host": "codex",
-        "agent": "aidd-dev-explorer",
-        "mode": "flat",
-        "requested": {
-          "model": "gpt-5.6-sol",
-          "effort": "low"
-        },
-        "native": {
-          "model": "gpt-5.6-sol",
-          "model_reasoning_effort": "low"
-        },
-        "nativeSurface": "agent-configuration",
-        "effectiveRuntime": "unknown",
-        "missing_task_inherits": true
-      },
-      {
-        "host": "opencode",
-        "agent": "aidd-dev-explorer",
-        "mode": "flat",
-        "requested": {
-          "model": "openai/gpt-6.1-sol",
-          "effort": "medium"
-        },
-        "native": {
-          "model": "openai/gpt-6.1-sol#medium"
-        },
-        "nativeSurface": "agent-configuration",
-        "effectiveRuntime": "unknown",
-        "missing_task_inherits": true
-      },
-      {
-        "host": "copilot",
-        "agent": "aidd-dev:explorer",
-        "mode": "marketplace",
-        "requested": {
-          "model": "gpt-6-luna"
-        },
-        "native": {
-          "model": "gpt-6-luna"
-        },
-        "nativeSurface": "agent-configuration",
-        "effectiveRuntime": "unknown",
-        "missing_task_inherits": true
-      },
-      {
-        "host": "cursor",
-        "agent": "aidd-dev-explorer",
-        "mode": "marketplace",
-        "requested": {},
-        "native": {},
-        "nativeSurface": "spawn",
-        "effectiveRuntime": "unknown",
-        "missing_task_inherits": true
-      }
-    ],
-    "unsupported_cursor_effort": "Error: Cursor plugin spawn does not accept effort; choose an advertised model slug or omit effort to inherit."
-  },
-  "final_mutation_gates": {
-    "tools-cursor": {
-      "score_percent": 97.4138,
-      "unchanged_floor": 97,
-      "exit": 0,
-      "mutant_status_counts": {
-        "Killed": 339,
-        "Survived": 9
-      }
-    },
-    "tools-opencode": {
-      "score_percent": 94.9704,
-      "unchanged_floor": 94,
-      "exit": 0,
-      "mutant_status_counts": {
-        "NoCoverage": 2,
-        "Killed": 321,
-        "Survived": 15
-      }
-    },
-    "presentation": {
-      "score_percent": 95.0187,
-      "unchanged_floor": 95,
-      "exit": 0,
-      "mutant_status_counts": {
-        "NoCoverage": 35,
-        "Killed": 2516,
-        "Survived": 98,
-        "Timeout": 21
-      },
-      "isolated_auth_guard": "Killed"
-    }
-  }
-}
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index f498fc072..cc898d026 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -1,134 +1,25 @@
 # Sub-agent verification
 
-## CLI opt-in, 2026-10-15
+Current state, 2026-10-20. Behavior and sources are in [the agent guide](../../../../docs/SUBAGENTS.md).
 
-The four agents are bundled with the CLI, outside plugins. Explicit installation selects a provider and IDE using the [CLI configuration](../../../../cli/src/contexts/tools/domain/formats/agent-models.json). Generic conversion applies no model defaults. Skills remain independent of installation and model selection.
+## Scope
 
-- **CLI:** 17 built-CLI cases pass, covering seven supported provider/IDE pairs, repeat installation, provider changes, removal, invalid selections, personal-file conflicts, cleanup, and a framework distribution without these agents.
-- **Ownership:** integration cases cover the project ledger, modified files, safe paths, and cleanup. Removing the ownership guard makes its named test fail; restored code passes. Without a framework manifest, cleanup preserves personal directory links; restoring recursive directory removal makes that test fail. The pre-existing manifest-present branch remains outside this proof.
-- **Limits:** Native files are written directly into each host's agent directory. These checks establish headers and file behavior, not account access or effective runtime model selection.
+- **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.
 
-## Optional behavior-only agents, 2026-10-16
+## Checks
 
-- **Configuration:** the same JSON separates advisory `main` models from applied `subagent` settings and adds Mistral on OpenCode V2. Sources and native-format references are in [the agent guide](../../../../docs/SUBAGENTS.md).
-- **Preferences:** Mistral main now recommends Large 4; Small 4 remains the subagent default. The official model page and local OpenCode catalog agree on `mistral-large-4`. Codex Fast is documented as a parent-session preference inherited by agents, not an agent header; installation leaves it unchanged.
-- **CLI:** 19 built-CLI cases pass, including eight provider/IDE pairs and switching to Mistral; 77 focused unit and command integration cases pass. Build: 694.7 KB / 695 KB.
-- **Reload:** 47 script cases pass. Regressions first reproduced personal-agent deletion and the wrong OpenCode Claude fallback; both now pass. Standalone agents remain unchanged.
-- **Gates:** 6,574 CLI tests pass, one skipped (`env -u CODEX_THREAD_ID pnpm test`); 494 script tests pass through the Git-safe wrapper. Lint, typecheck, type honesty, architecture, links, duplication, and knip pass. An initial run exposed the expected help snapshot change and two inherited-session fixture failures; the refreshed snapshot and isolated environment pass.
-- **CI build:** the completed run on `78344131` measured 697.0 KB after merging `next` at `ae8705f7`, versus 694.7 KB on the branch. Nine checks failed from the same 695 KB limit. Dependencies and build settings match; the merge adds the daily telemetry ledger and bounded reports. The budget is now 705 KB, with 1.1% headroom on that measured merge; the next CI run must confirm it.
-- **Limits:** no authenticated inference establishes effective runtime model selection for this candidate.
+- **CLI:** 6,839 tests pass, one skipped. Typecheck, lint, architecture rules, knip and duplication (1.47%) pass. Bundle 720.0 KB against 726 KB.
+- **Smoke:** 140 checks pass, one remote check skipped; 34/34 leaf commands exercised.
+- **Reload:** 52 script cases pass, including 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.
 
-## Review fixes, 2026-10-16
+## Earlier runtime probes
 
-- **Native headers:** Codex translation drops Claude shorthand selectors; Copilot custom agents include repository instructions unless explicitly disabled.
-- **Ownership:** installation, updates and removal restore native files after a handled failure. Concurrent mutations serialize across CLI processes; framework cleanup holds the same lock until state removal finishes.
-- **Regression evidence:** 36 lifecycle integration tests pass. Five independent mutations disable model filtering, instruction injection, rollback, serialization or cleanup coordination; each makes its named test fail, and restored code passes.
-- **Checks:** normal commit hooks pass, including 494 script tests, 168 architecture assertions, types and lint. The full CLI suite passes 6,620 tests, one skipped.
-- **CI merge:** the bundle reaches 706.36 KB with `next` at `7084a88c`, reproduced locally. Telemetry code on `next` adds 8,839 bytes over the 697.73 KB branch. The reviewed budget is 715 KB, with 1.2% measured headroom.
-- **Limits:** abrupt process termination can require recovery; no new authenticated model inference was performed.
+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.
 
-## Earlier runtime evidence
+## Limits
 
-The runtime probes below describe earlier candidates. Their traces and hashes predate the CLI-installed model defaults and the latest simplified agent bodies.
-
-Verified 2026-10-14 on `feature/sub-agents`: workflow candidate `1f151d19`, delivery candidate `e00f124c`.
-
-## Native roles
-
-| Host | Version | Invoked roles |
-| --- | --- | --- |
-| Codex | 0.162.1 | explorer, executor, validator, checker |
-| Claude Code | 2.1.299 | aidd-dev:explorer, aidd-dev:executor, aidd-dev:validator, aidd-dev:checker |
-| OpenCode | 2.0.28 | aidd-dev-explorer, aidd-dev-executor, aidd-dev-validator, aidd-dev-checker |
-
-Native dispatch traces identify the selected roles and fresh child contexts. Agent self-reports alone were not used to establish invocation.
-
-| Scenario | Codex | Claude | OpenCode |
-| --- | --- | --- | --- |
-| Explorer cites the readiness rule and refuses a conflicting write request | PASS | PASS | PASS |
-| Validator reports INCOMPLETE for the failing mandatory check without repair | PASS | PASS | PASS |
-| Validator reports BLOCKED without criteria despite an offered green command | PASS | PASS | PASS |
-| Executor invokes the installed implement skill for only its assigned phase | PASS | PASS | PASS |
-| Fresh validator reports COMPLETE for the repaired, unchanged candidate | PASS | PASS | PASS |
-| Checker reviews quality and fitness without modifying the candidate | PASS | PASS | PASS |
-
-Independent final readback found exact bytes `72 65 61 64 79 0a`, a passing `node check.cjs`, and only the assigned phase's lifecycle update. The shared plan, completed prerequisite, check command, and unrelated file retained their baseline contents.
-
-## Parallel implementation
-
-Two native Codex executors used separate supplied worktrees and Git indexes. Their recorded execution intervals overlapped by 19 seconds. Each invoked the installed assigned-phase workflow and committed only its own data file and phase status.
-
-| Phase | Executor commit | Integrated commit | Check |
-| --- | --- | --- | --- |
-| 1 | 551702df | 5e4bcaa1 | check-a.cjs: READY, exit 0 |
-| 2 | add8b135 | 32521585 | check-b.cjs: READY, exit 0 |
-
-The caller integrated both, obtained `BOTH_READY` and exit 0 from `node check-all.cjs`, then committed plan status `implemented` at `c2b8ff32`. Independent readback confirmed the plan and both phases complete, with all three checkouts clean. These commits belong to the disposable probe repository, not the framework.
-
-A restricted-workspace negative probe could not write Git metadata. It reported BLOCKED and left the integrated plan incomplete. The successful disposable probe used the desktop's unrestricted execution profile. No authentication or product security control was changed.
-
-## Real-project planning
-
-The installed planning skill produced three phases in Gouvernail's `2026_10_14_sub_agents_plan_probe` folder: two disjoint diagnostic scripts with no prerequisites, followed by shared package-command wiring depending on both. The phase projections and dependency table were inspected. No application source changed. Session-start memory formatting changes were restored; only the probe artifacts remain.
-
-The large-project planning and review controllers exceeded their imposed time limits after producing the artifacts. Their full interactive completion is not claimed. Codex's combined role controller also exceeded its limit; its native thread subsequently emitted all six results and `turn.completed`. A separate normal-session validator probe exited 0.
-
-## Delivery and gates
-
-`make reload` ran without `PLUGIN`, installing all nine plugins. OpenCode skills and agents were compared with the generated tree; native discovery listed all four roles. Claude's manifest explicitly declares the new agents.
-
-OpenCode's configured local model server was unavailable. Its behavioral probe used the already authenticated `openai/gpt-6.1-sol` through an invocation-only override, with matching `cwd` and `PWD`. Global model and authentication settings were unchanged. Versioned discovery and directory behavior sources are recorded in deployment memory.
-
-The wrapped scripts suite passed 559 tests, including 12 reload regressions. Architecture, JSON manifest validation, Markdown links, duplication checks, and commit hooks passed. These results establish the observed contracts and host paths; they do not guarantee every future task or model choice.
-
-## Earlier four-role candidate, 2026-10-15
-
-The earlier results above describe the previous checker contract. Native runtime probes ran on macOS. Current probes use the four scoped roles: explorer, executor, validator and reviewer. Validator returns one completion verdict; reviewer independently assesses quality. Native dispatch events establish invocation; generated files and agent self-reports alone do not.
-
-| Host | Tested version | Delivery and observed runtime |
-| --- | --- | --- |
-| Claude Code | 2.1.300 | Generated flat agents. Opus parent and Haiku children resolve to `claude-opus-5-5` / `claude-haiku-5-5`. Native calls request `low`; effective effort is not independently echoed. |
-| Codex | 0.145.0 | Installed user agents. Four fresh children report `gpt-5.6-sol` / `low` in native turn contexts. Signed-in backend rejects the suggested newer models. |
-| OpenCode | 2.0.28 | Generated project agents. Four native child message records identify their roles and `openai/gpt-6.1-sol#medium`; controller exits 0. An earlier Luna probe had a transport error and is excluded from clean passes. |
-| GitHub Copilot | 1.0.98 | Generated marketplace agents invoked through native `--plugin-dir`. Four roles run. Explicit child model `gpt-6-luna` works; actual effort remains `medium` despite requesting low. |
-| Cursor | 2026.10.14-941492e | Current official CLI in an isolated download; automatic discovery of four real global local-plugin agents, without `--plugin-dir`. Auto succeeds; the Free account rejects named models. Backend model and effort remain unverified. |
-
-The bounded scenarios cover sourced exploration, implementation output, rejection of a false completion criterion, and independent quality review. Claude's executor changes only the eight assigned modules and passes independent checks. Other four-role probes use text implementation; their files remain unchanged. Cursor's explorer and validator read the actual threshold file; its reviewer also reads the installed quality checklist. Filtered session identities, source hashes, native model metadata and limitations are retained in [runtime.json](runtime.json).
-
-### Direct versus delegated
-
-Same synthetic exploration and repetitive implementation tasks, once per mode. The delegated run includes its Opus parent and fresh Haiku child. Tokens include input, output, cache reads and cache writes; costs are native list-price estimates, not subscription charges.
-
-| Task | Mode | Total tokens | Wall time | Cost estimate, USD |
-| --- | --- | ---: | ---: | ---: |
-| Exploration | Direct | 136,486 | 26.0 s | 0.2386 |
-| Exploration | Delegated | 183,951 | 30.0 s | 0.2130 |
-| Implementation | Direct | 136,126 | 21.1 s | 0.2081 |
-| Implementation | Delegated | 188,423 | 29.4 s | 0.1899 |
-
-Both retained modes return correct source findings and pass the same independent implementation checks, with no task retries. An earlier implementation pair could not run checks under its Bash permission pattern; both modes were rerun with equal permissions. That excluded attempt is recorded in [comparison.json](comparison.json), alongside quality checks. Separate token-category counts were not retained after fixture cleanup. Different cache states and one observation per mode prevent a general savings claim. Delegation was slower here, with a lower reported cost estimate.
-
-### Reload and finalization
-
-`make reload` exits 0 and refreshes all nine plugins for Claude, Codex, OpenCode, Copilot and Cursor. Native Copilot lists all nine AIDD plugins; Cursor discovers the installed global roles. Byte hashes confirm preservation of 28 personal agent files and personal content in three pre-existing instruction files. Managed global instructions contain only the agent table. Cursor still requires its native Local Plugin Imports policy.
-
-A disposable whole-plan execution invokes `/aidd-dev:02-implement`, repairs the assigned value, runs the mandatory check, then runs the final journey and marks the phase and plan complete. Native tool chronology and the fixture's event ledger show `check` then `journey`, followed by the plan update and no further validation command. The fixture rejects checks after the journey and rejects a journey after premature completion. No commits or pushes occur in that probe.
-
-### Final checks
-
-- **CLI:** after integrating `next` at `0a103e67`, 504 test files pass, one skipped; 6,551 tests pass, one skipped. Architecture, typecheck, lint, type honesty and unused-code gates pass. Bundle is 515.7 KB against Next's 695 KB budget. The local run unsets inherited `CODEX_THREAD_ID` so two imported telemetry fixtures use their own session IDs.
-- **Scripts:** the wrapped full suite passes 498 tests after Next retires the previous telemetry suite. Five native-home regressions failed before their default-path corrections and pass afterward; explicit path overrides retain priority. Missing Claude installation paths fail without writing into the current directory; reload fixtures stay in their temporary home.
-- **Integration:** the real resolver finds installed agents on all five hosts, preserves project configuration bytes, leaves missing tasks inherited, and rejects unsupported Cursor plugin effort. Actual `make reload` exits 0 after the final corrections; the personal-file preservation check still passes.
-- **Guards:** removing the unknown-field rejection and bypassing Claude activation each causes the targeted test to fail. Exact source bytes were restored and the named tests pass; both full native scopes subsequently pass: Cursor 97.4% against 97%, OpenCode 95.0% against 94%, with unchanged floors.
-- **Scope:** gather, wireframe, the challenge skill and generic skill generation have no diff against `next`. Generic generation work remains in PR #1028.
-
-
-### CI follow-up
-
-The first CI run caught a missing smoke command, a stale checker-name expectation in the real Kilo probe, Windows fixture path/JSON issues, and two mutation-floor failures. Only test coverage and fixtures changed afterward; production behavior and mutation floors remain unchanged.
-
-After the Next integration, the smoke suite passes 135 checks with 33/33 commands exercised. Official Kilo 7.7.5 passed its real loopback runtime test with all four current roles before that integration. Windows fixture serialization and native path expectations are covered; Windows execution is checked by the PR's CI jobs.
-
-Fifteen native profile cases cover invalid selector boundaries, malformed option groups, personal agent identity, configuration versus spawn surfaces, and the OpenCode XDG override. Malformed-error assertions now inspect the actual error message; the earlier assertion could accept an undefined rejection. Both complete mutation scopes pass their original floors; exact status counts are retained in [runtime.json](runtime.json).
-
-Six command-wiring cases cover delegation JSON, text, inheritance, diagnostics, required host and failure routing. The existing authentication mutual-exclusion test now supplies a valid storage level, preventing a later guard from masking the one under test. Presentation mutation passes at 95.0187% against the unchanged 95% floor; the removed guard is detected. Production behavior is unchanged by these test corrections.
+Headers and files do not prove account access or the model and effort a host applies at runtime.

From 26f7d6c973f128f0d5592763a1074cfbf2f8ebe0 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 09:40:54 +0800
Subject: [PATCH 53/73] fix(framework): make the reload opt-in explicit about
 what it cannot undo

Report opt-in file errors without a stack trace, reject unknown keys, hint at a rebuild when the CLI fails, and document that agents remove --scope user undoes an entry.
---
 CONTRIBUTING.md                    |  2 +-
 README.md                          |  2 +-
 docs/SUBAGENTS.md                  |  2 +-
 scripts/__tests__/dev-sync.test.js | 16 +++++++++++++++-
 scripts/dev-sync.sh                | 25 +++++++++++++++++--------
 scripts/reload-agents.example.json |  2 +-
 6 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8e1b4da66..21eb5c68b 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/README.md b/README.md
index 0bac50a8c..38f88e3e7 100644
--- a/README.md
+++ b/README.md
@@ -187,7 +187,7 @@ codex plugin add aidd-context@aidd-framework   # per plugin
 
 ### 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.
+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
 
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 33ba10c11..28e647406 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -70,7 +70,7 @@ Use host dispatch records to identify the agent and actual model, effort, and ti
 
 After updating the CLI, rerun the install command to refresh unmodified agents; agents of retired roles are removed. Plugins and `sync` do not install or refresh this add-on.
 
-For framework development, copy [reload-agents.example.json](../scripts/reload-agents.example.json) to the gitignored `scripts/reload-agents.json` (or point `RELOAD_AGENTS` at another file). `make reload` then runs `agents install --scope user` for each listed IDE with its `provider`, adding `--main` where `"main": true`. Without the file, reload installs no agent.
+For framework development, copy [reload-agents.example.json](../scripts/reload-agents.example.json) to the gitignored `scripts/reload-agents.json` (or point `RELOAD_AGENTS` at another file). `make reload` then runs `agents install --scope user` for each listed IDE with its `provider`, adding `--main` where `"main": true`. Without the file, reload installs no agent. The file only adds: to undo an IDE or its main model, run `agents remove --scope user --ide <ide>`. Reload stops on a modified or unowned agent file; move it aside, then rerun.
 
 To remove only one IDE's agents from the current project:
 
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 5169be5a4..975d114c5 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -873,6 +873,18 @@ test("reload without an opt-in file installs no agent", () => {
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
+test("reload skips opted-in OpenCode on a managed host", () => {
+  const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-managed-agents-"));
+  try {
+    const { fakeBin, home, calls } = optInFixture(root, { opencode: { provider: "anthropic" } }, ["opencode"]);
+    executable(join(fakeBin, "aidd-opencode-reload"), "exit 0");
+    const result = runSync(fakeBin, home, []);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /global agents\s+opencode:skip\(managed host\)/);
+    assert.doesNotMatch(calls(), /cli agents/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
 test("reload names an opted-in IDE it skips", () => {
   const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-skip-"));
   try {
@@ -886,7 +898,9 @@ test("reload names an opted-in IDE it skips", () => {
 
 for (const [label, optIn, error] of [
   ["a refused IDE", { cursor: { provider: "anthropic" } }, /cursor has no user-level agents/],
-  ["an invalid entry", { codex: { provider: "openai", main: "yes" } }, /Invalid agent opt-in file/],
+  ["an invalid entry", { codex: { provider: "openai", main: "yes" } }, /codex\.main must be true or omitted/],
+  ["a misspelled key", { codex: { provider: "openai", mian: true } }, /codex has unknown keys: mian/],
+  ["malformed JSON", "{ codex: ", /Invalid agent opt-in file/],
 ]) {
   test(`reload stops on ${label} before changing any plugin`, () => {
     const root = mkdtempSync(join(tmpdir(), "aidd-dev-sync-bad-opt-in-"));
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 5908d2f54..403d07cda 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -8,8 +8,9 @@
 # exposes `aidd-opencode-reload` instead, and that helper decides which checkout may load.
 #
 # Agents are opt-in through the gitignored scripts/reload-agents.json (or RELOAD_AGENTS; see
-# reload-agents.example.json): each listed IDE runs `aidd agents install --scope user`, adding
-# `--main` when `"main": true`. They run first, so a bad entry fails before any plugin changes.
+# reload-agents.example.json): each listed IDE runs the built CLI's `agents install --scope user`,
+# adding `--main` when `"main": true`. The file only adds; `agents remove --scope user` undoes.
+# Agents run before plugins, so a failure changes no plugin; IDEs listed earlier stay installed.
 # Global rules: sync only the Agents section in the managed block, preserving personal
 # rules. First OpenCode sync keeps its Claude personal-rule fallback unless disabled.
 # Paths honor native home/cache overrides; explicit task paths take precedence.
@@ -128,13 +129,19 @@ install_opted_in_agents() {
   [ -f "$RELOAD_AGENTS" ] || return 0
   local opted_in ide provider main have result
   opted_in="$(node -e '
-    const file = process.argv[1];
-    const config = JSON.parse(require("node:fs").readFileSync(file, "utf8"));
+    const fail = (message) => { console.error(message); process.exit(1); };
+    let config;
+    try { config = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")); }
+    catch (error) { fail(error.message); }
+    if (typeof config !== "object" || config === null || Array.isArray(config))
+      fail("expected an object keyed by IDE");
     const text = (value) => typeof value === "string" && /^[\w.-]+$/.test(value);
     for (const [ide, entry] of Object.entries(config)) {
-      if (!text(ide) || !text(entry?.provider)) throw new Error(`${file}: ${ide} needs a provider`);
-      if (entry.main !== undefined && typeof entry.main !== "boolean")
-        throw new Error(`${file}: ${ide}.main must be true or false`);
+      if (!text(ide)) fail(`invalid IDE name "${ide}"`);
+      if (!text(entry?.provider)) fail(`${ide} needs a provider`);
+      const unknown = Object.keys(entry).filter((key) => key !== "provider" && key !== "main");
+      if (unknown.length > 0) fail(`${ide} has unknown keys: ${unknown.join(", ")}`);
+      if (entry.main !== undefined && entry.main !== true) fail(`${ide}.main must be true or omitted`);
       console.log(`${ide}\t${entry.provider}\t${entry.main === true}`);
     }
   ' "$RELOAD_AGENTS")" || { echo "Invalid agent opt-in file: $RELOAD_AGENTS" >&2; return 1; }
@@ -155,7 +162,9 @@ install_opted_in_agents() {
     local -a args=(agents install --scope user --ide "$ide" --provider "$provider")
     [ "$main" != true ] || args+=(--main)
     if ! result="$(node "$FW/cli/dist/cli.js" "${args[@]}" 2>&1)"; then
-      echo " $ide:FAIL"; printf '%s\n' "$result" >&2; return 1
+      echo " $ide:FAIL"; printf '%s\n' "$result" >&2
+      echo "Fix the cause, or rebuild with 'pnpm --dir cli build' if the CLI predates this checkout." >&2
+      return 1
     fi
     if [ "$main" = true ]; then printf ' %s:ok+main' "$ide"; else printf ' %s:ok' "$ide"; fi
   done <<<"$opted_in"
diff --git a/scripts/reload-agents.example.json b/scripts/reload-agents.example.json
index 03755702f..028b1180f 100644
--- a/scripts/reload-agents.example.json
+++ b/scripts/reload-agents.example.json
@@ -1,5 +1,5 @@
 {
   "claude-code": { "provider": "anthropic" },
   "codex": { "provider": "openai" },
-  "opencode": { "provider": "anthropic", "main": false }
+  "opencode": { "provider": "anthropic", "main": true }
 }

From 2d33351a3d1904b7bed25eb9751c06c5c0d95f5d Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 09:56:40 +0800
Subject: [PATCH 54/73] docs(agents): keep the executor on the checks it
 started

One rule in the executor: wait for every check or commit you started
before ending a turn. The earlier additions to the deliver reference and
to the blocked conditions described one situation; they are withdrawn.
---
 cli/assets/agents/executor.md                                  | 3 +--
 plugins/aidd-dev/skills/02-implement/references/blocked.md     | 2 --
 .../aidd-orchestrator/skills/01-sdlc/references/02-deliver.md  | 2 +-
 3 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/cli/assets/agents/executor.md b/cli/assets/agents/executor.md
index 4ab16b649..db5c3830e 100644
--- a/cli/assets/agents/executor.md
+++ b/cli/assets/agents/executor.md
@@ -12,8 +12,7 @@ Deliver assigned code or documentation within the agreed outcome and criteria.
 - **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; nobody resumes a returned executor.
-- **Treat a prescribed check the environment refuses twice as a blocker** to report, never as an environment to rebuild.
+- **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
diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md
index 38a83c0d3..42c94f6a1 100644
--- a/plugins/aidd-dev/skills/02-implement/references/blocked.md
+++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md
@@ -8,5 +8,3 @@ description: Conditions that make a plan blocked (needs a human).
 `blocked` means implementation cannot proceed and only a human can unblock it. Stop and escalate to the whole-plan owner, who sets the plan `status: blocked`.
 
 Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA.
-
-Outside the assigned change (no repair allowed): a prescribed validation command the environment refuses twice; a red check in files the change never touched.
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 9cef84395..3257b8eea 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,7 +2,7 @@
 
 ## Behavior
 
-Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its checkout and its phase file, and nothing the phase file already says. Resume the same executor session for its next phase, and leave its checkout untouched while it runs. Integrate prerequisites before starting dependent phases.
+Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
 
 The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Whole-plan execution keeps its normal flow; phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
 

From c3237c777e6516eb647523c29225f53254ea667a Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 09:55:46 +0800
Subject: [PATCH 55/73] fix(cli): refuse agent changes the CLI could not undo

Reject --main for IDEs without a main model setting, refuse user-level removal from a configuration directory other than the install's, and report unsafe TOML without a raw parse error.
---
 .../agents/manage-agents-use-case.ts          | 11 +++++++++
 .../tools/domain/formats/main-model-config.ts | 10 ++++++--
 ...manage-agents-use-case.integration.test.ts | 23 +++++++++++++++++++
 docs/SUBAGENTS.md                             |  6 ++---
 4 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
index 133190d92..e5851db8e 100644
--- a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -73,6 +73,8 @@ export class ManageAgentsUseCase {
   ): Promise<number> {
     const capability = this.capability(options.host);
     const location = this.location(options);
+    if (options.main === true && location.settingsPath === null)
+      throw new Error(`${options.host} has no main model setting AIDD can write.`);
     const entries = Object.entries(this.sources).map(([name, source]) => {
       const { frontmatter, body } = parseFrontmatter(source);
       const role = typeof frontmatter.name === "string" ? frontmatter.name : name;
@@ -350,6 +352,15 @@ export class ManageAgentsUseCase {
     for (const [host, entries] of Object.entries(installed)) {
       if (onlyHost !== undefined && host !== onlyHost) continue;
       const location = this.location({ ...target, host: host as AgentHost });
+      // A user directory resolved elsewhere than at install would drop the record unseen.
+      const names = Object.keys(entries);
+      if (target.user !== undefined && names.length > 0) {
+        const directory = dirname(location.agentPath(names[0] as string));
+        if (!(await this.fs.fileExists(directory)))
+          throw new Error(
+            `No agents directory at ${directory}; restore the ${host} configuration directory used at install.`
+          );
+      }
       for (const [name, hash] of Object.entries(entries)) {
         const path = location.agentPath(name);
         await this.assertOwned(location, path, hash);
diff --git a/cli/src/contexts/tools/domain/formats/main-model-config.ts b/cli/src/contexts/tools/domain/formats/main-model-config.ts
index 5517aab9d..5d4077d98 100644
--- a/cli/src/contexts/tools/domain/formats/main-model-config.ts
+++ b/cli/src/contexts/tools/domain/formats/main-model-config.ts
@@ -118,8 +118,14 @@ function editSettings(
     return `${bom}${JSON.stringify(settings, null, indent)}\n`;
   }
   const next = editTomlLines(content ?? "", set, unset);
-  if (canonical(parse(next)) !== canonical(settings))
-    throw new Error("Cannot edit this TOML safely; set the model yourself.");
+  const unsafe = new Error("Cannot edit this TOML safely; set the model yourself.");
+  let edited: unknown;
+  try {
+    edited = parse(next);
+  } catch {
+    throw unsafe;
+  }
+  if (canonical(edited) !== canonical(settings)) throw unsafe;
   return next;
 }
 
diff --git a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
index 1b1d41f96..6be4842c1 100644
--- a/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
+++ b/cli/tests/contexts/framework/application/agents/manage-agents-use-case.integration.test.ts
@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ManageAgentsUseCase } from "../../../../../src/contexts/framework/application/agents/manage-agents-use-case.js";
 import { AgentInstallationStoreAdapter } from "../../../../../src/contexts/framework/infrastructure/agent-installation-store-adapter.js";
 import "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import "../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
 import "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
 import { FileAdapter } from "../../../../../src/runtime/filesystem/file-adapter.js";
 import { HasherAdapter } from "../../../../../src/runtime/filesystem/hasher-adapter.js";
@@ -86,6 +87,28 @@ describe("ManageAgentsUseCase", () => {
     expect(await readFile(settings, "utf8")).toBe('model = "mine"\n');
   });
 
+  it("refuses user-level removal from a configuration directory other than the install's", async () => {
+    const home = join(root, "home");
+    const at = (codexHome: string) => ({
+      projectRoot: root,
+      host: "codex" as const,
+      user: {
+        home,
+        env: (name: string) => (name === "CODEX_HOME" ? join(home, codexHome) : undefined),
+        configDir: join(home, ".config/aidd"),
+      },
+    });
+    await manager.install({ ...at("codex-a"), provider: "openai" });
+    await expect(manager.remove(at("codex-b"))).rejects.toThrow(/No agents directory/);
+    expect(await manager.remove(at("codex-a"))).toBe(2);
+  });
+
+  it("refuses --main where the IDE has no main model setting", async () => {
+    await expect(
+      manager.install({ projectRoot: root, host: "cursor", provider: "anthropic", main: true })
+    ).rejects.toThrow(/no main model setting/);
+  });
+
   it("removes an unmodified agent whose role is no longer bundled", async () => {
     await manager.install({ projectRoot: root, host: "codex", provider: "openai" });
     const { "aidd-dev-reviewer": _, ...remaining } = sources;
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 28e647406..9504987ee 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -13,7 +13,7 @@
 
 ## 👥 Roles
 
-Add focused roles to your project's AI tool. Installation is explicit; workflows can also use the host's available agents.
+Add focused roles to your project's AI tool. Installation is explicit.
 
 | Role | Responsibility |
 | --- | --- |
@@ -70,7 +70,7 @@ Use host dispatch records to identify the agent and actual model, effort, and ti
 
 After updating the CLI, rerun the install command to refresh unmodified agents; agents of retired roles are removed. Plugins and `sync` do not install or refresh this add-on.
 
-For framework development, copy [reload-agents.example.json](../scripts/reload-agents.example.json) to the gitignored `scripts/reload-agents.json` (or point `RELOAD_AGENTS` at another file). `make reload` then runs `agents install --scope user` for each listed IDE with its `provider`, adding `--main` where `"main": true`. Without the file, reload installs no agent. The file only adds: to undo an IDE or its main model, run `agents remove --scope user --ide <ide>`. Reload stops on a modified or unowned agent file; move it aside, then rerun.
+For framework development, copy [reload-agents.example.json](../scripts/reload-agents.example.json) beside it as the gitignored `reload-agents.json` (or point `RELOAD_AGENTS` at another file). `make reload` then runs `agents install --scope user` for each listed IDE with its `provider`, adding `--main` where `"main": true`. Without the file, reload installs no agent. The file only adds: to undo an IDE or its main model, run `agents remove --scope user --ide <ide>`. Reload stops on a modified or unowned agent file; move it aside, then rerun.
 
 To remove only one IDE's agents from the current project:
 
@@ -78,7 +78,7 @@ To remove only one IDE's agents from the current project:
 node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
 ```
 
-The other IDEs' agents remain installed; add `--scope user` for user-level agents. Removal also restores the main model it replaced. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including all managed agents.
+The other IDEs' agents remain installed; add `--scope user` for user-level agents. Removal also restores the main model it replaced. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including its managed agents; user-level agents stay until `agents remove --scope user`.
 
 ## 🚧 Beta limitations
 

From 250fd557114583f17eee6e285019208f956b6a41 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 09:56:45 +0800
Subject: [PATCH 56/73] docs(framework): resolve delegation contradictions
 found in review

The reviewer runs 05-review itself, executors receive what the phase file omits, caller-only guidance leaves the executor action, and the fan-out rule carries its cost condition.
---
 AGENTS.md                                                    | 2 +-
 plugins/aidd-dev/skills/02-implement/SKILL.md                | 1 +
 plugins/aidd-dev/skills/02-implement/actions/02-execute.md   | 5 ++---
 .../skills/01-sdlc/references/02-deliver.md                  | 2 +-
 .../aidd-orchestrator/skills/01-sdlc/references/03-check.md  | 4 ++--
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e29868b44..8483aace6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,7 +33,7 @@
 
 ## Agents
 
-When you own the overall flow, fan out genuinely parallel subtasks to available host agents by responsibility; custom agents are optional. The caller owns scope, delegation, and final acceptance.
+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.
 
 ## Memory Management
 
diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md
index 759239835..0b0414d34 100644
--- a/plugins/aidd-dev/skills/02-implement/SKILL.md
+++ b/plugins/aidd-dev/skills/02-implement/SKILL.md
@@ -35,6 +35,7 @@ Read each action file in `actions/` before executing it.
 ## Transversal rules
 
 - The caller owns delegation, integration, shared plan status, and final acceptance; phase executors own only their assigned files and phase status.
+  - Parallel phases need separate write ownership and validation resources; workers running Git get their own checkout and index, otherwise the caller owns Git. Run serially when isolation is uncertain.
 - Track the plan through `pending → in-progress → implemented` (or `blocked`).
   - Track phases through `pending → in-progress → done`.
   - Treat `in-progress` as a runtime marker.
diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index b5f597867..09fe6ea0b 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -12,8 +12,7 @@ Or a `blocked` / `replan needed` report.
 
 ## Process
 
-1. **Open.** Select assigned phases whose dependencies are done and integrated; use serial plan order when dependencies are undeclared.
-   - The caller may run independent phases in parallel with separate write ownership and nonconflicting validation resources. Use separate checkouts/indexes when workers perform Git operations; otherwise the caller owns Git. Run serially when isolation is uncertain.
+1. **Open.** Select assigned phases whose dependencies are done; use serial plan order when dependencies are undeclared.
    - A declared prerequisite with no matching phase, contradictory dependencies, or unfinished work with no ready phase requires `replan needed`.
    - Set the current phase `status: in-progress`.
    - In a feature folder, read `phase-<n>.md` beside `plan.md`.
@@ -25,7 +24,7 @@ Or a `blocked` / `replan needed` report.
      - Set the phase `status: done` on success.
 4. **Complete.** Commit according to the commit policy.
    - Repeat steps 2–4 for the remaining assigned tasks.
-   - Phase executors return changes and evidence. The caller integrates them, checks affected interactions, then starts dependents; only the whole-plan owner finalizes.
+   - Phase executors return changes and evidence to the caller.
 
 ## Rules
 
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 3257b8eea..984c6d8be 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -4,7 +4,7 @@
 
 Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
 
-The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Whole-plan execution keeps its normal flow; phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
+The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
 
 Commit and push the validated work through the commit skill. Send only the clean committed candidate and its evidence to Check.
 
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index 7c22a6a44..efe29ff01 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -3,7 +3,7 @@
 ## Behavior
 
 - **Validate the committed candidate** against the contract, criteria, and mandatory checks using a fresh agent.
-- **Review quality and coherence** with a fresh agent after validation passes, on the code and relevancy axes using the acceptance evidence; record its findings through `/aidd-dev:05-review`.
+- **Review quality and coherence** after validation passes: a fresh agent runs `/aidd-dev:05-review` on the code and relevancy axes with the acceptance evidence.
 - **Challenge the outcome** with another fresh agent after review clears, not the one that sequenced delivery: verify that it is trustworthy and serves the user.
 
 ## Findings
@@ -61,7 +61,7 @@ flowchart TD
   ValidationReports --> Validator
   Validator -- "All criteria pass with evidence." --> Reviewer
   Validator -- "Fail or blocked." --> Findings
-  Reviewer -- "Caller records code and relevancy findings." --> Review
+  Reviewer -- "Runs code and relevancy axes." --> Review
   Review -- "Return actionable review findings." --> Findings
   Review -- "When the review clears, challenge the outcome." --> Challenge
   Challenge -- "Return actionable challenge findings." --> Findings

From fc73224d2959ae1c79a7de9451857423d1789a06 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 09:57:41 +0800
Subject: [PATCH 57/73] fix(framework): keep CI checks independent of the
 personal reload opt-in

Name the gitignored opt-in without a path CI cannot resolve, replace a machine-like fixture path, and refresh verification after the merge with next.
---
 aidd_docs/memory/deployment.md                              | 2 +-
 .../tasks/2026_10/2026_10_14_sub_agents/verification.md     | 6 +++---
 scripts/__tests__/dev-sync.test.js                          | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/aidd_docs/memory/deployment.md b/aidd_docs/memory/deployment.md
index 94e6c45b7..c91b34f63 100644
--- a/aidd_docs/memory/deployment.md
+++ b/aidd_docs/memory/deployment.md
@@ -58,7 +58,7 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 ## Local reload
 
-`make reload` syncs all plugins and generic delegation guidance to installed hosts, and the agents opted in by the gitignored `scripts/reload-agents.json`; details in `scripts/dev-sync.sh`.
+`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
 
diff --git a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
index cc898d026..e9d66c553 100644
--- a/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
+++ b/aidd_docs/tasks/2026_10/2026_10_14_sub_agents/verification.md
@@ -1,6 +1,6 @@
 # Sub-agent verification
 
-Current state, 2026-10-20. Behavior and sources are in [the agent guide](../../../../docs/SUBAGENTS.md).
+Current state, 2026-10-21, merged with next. Behavior and sources are in [the agent guide](../../../../docs/SUBAGENTS.md).
 
 ## Scope
 
@@ -11,9 +11,9 @@ Current state, 2026-10-20. Behavior and sources are in [the agent guide](../../.
 
 ## Checks
 
-- **CLI:** 6,839 tests pass, one skipped. Typecheck, lint, architecture rules, knip and duplication (1.47%) pass. Bundle 720.0 KB against 726 KB.
+- **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:** 52 script cases pass, including opt-in order, skips with a reason, and refusal before plugin changes.
+- **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
diff --git a/scripts/__tests__/dev-sync.test.js b/scripts/__tests__/dev-sync.test.js
index 975d114c5..5e30caf6d 100644
--- a/scripts/__tests__/dev-sync.test.js
+++ b/scripts/__tests__/dev-sync.test.js
@@ -580,7 +580,7 @@ test("Copilot fixture serializes Windows paths and quotes as JSON", () => {
   try {
     const fakeBin = join(root, "bin"), home = join(root, "home");
     mkdirSync(fakeBin); mkdirSync(home);
-    const source = String.raw`C:\Users\Example "quoted"\Framework`;
+    const source = String.raw`D:\Work\Example "quoted"\Framework`;
     writeFileSync(join(home, "copilot-source"), source);
     executable(join(fakeBin, "node"), `exec '${process.execPath}' "$@"`);
     const binary = join(fakeBin, "copilot");

From e598d21cf029aecf4ec846c4c58b4fbef5e33afc Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:13:44 +0800
Subject: [PATCH 58/73] test(cli): cover each IDE's user agent directory

Pin the environment override and its default for Claude Code, Codex and OpenCode, so the user-scope paths keep their mutation floors.
---
 .../tools/domain/profiles/claude.unit.test.ts         | 10 ++++++++++
 .../contexts/tools/domain/profiles/codex.unit.test.ts | 10 ++++++++++
 .../tools/domain/profiles/opencode.unit.test.ts       | 11 +++++++++++
 3 files changed, 31 insertions(+)

diff --git a/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
index 53ff6ca45..d0a172d85 100644
--- a/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
@@ -135,6 +135,16 @@ describe("claude", () => {
     });
   });
 
+  describe("capabilities.agents.params.userDirectory()", () => {
+    const userDirectory = claude.capabilities.agents.params.userDirectory;
+    it("follows CLAUDE_CONFIG_DIR, else ~/.claude", () => {
+      expect(
+        userDirectory?.("/home", (name) => (name === "CLAUDE_CONFIG_DIR" ? "/cfg" : undefined))
+      ).toBe("/cfg");
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".claude"));
+    });
+  });
+
   describe("capabilities.rules.buildInstallPath()", () => {
     it("builds path for rules section with subdirectory", () => {
       const path = claude.capabilities.rules?.buildInstallPath("01-standards/naming.md");
diff --git a/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts
index 9a60582de..7b8a3a9e5 100644
--- a/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts
@@ -65,6 +65,16 @@ describe("codex", () => {
     expect(codex.configOutputPaths).toStrictEqual({ "config.toml": ".codex/config.toml" });
   });
 
+  describe("capabilities.agents.params.userDirectory()", () => {
+    it("follows CODEX_HOME, else ~/.codex", () => {
+      const userDirectory = codex.capabilities.agents.params.userDirectory;
+      expect(userDirectory?.("/home", (name) => (name === "CODEX_HOME" ? "/cx" : undefined))).toBe(
+        "/cx"
+      );
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".codex"));
+    });
+  });
+
   describe("capabilities.agents.buildInstallPath()", () => {
     it("builds .toml path under .codex/agents/", () => {
       const path = codex.capabilities.agents.buildInstallPath("alexia.md");
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
index c9c40137c..64dd6ef10 100644
--- a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { opencode } from "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
 import { OpencodeDualConfigError } from "../../../../../src/kernel/errors.js";
@@ -17,6 +18,16 @@ function makeFs(existingPaths: string[]): FileReader {
 }
 
 describe("opencode", () => {
+  describe("capabilities.agents.params.userDirectory()", () => {
+    const userDirectory = opencode.capabilities.agents.params.userDirectory;
+    it("follows XDG_CONFIG_HOME, else ~/.config, under opencode", () => {
+      expect(
+        userDirectory?.("/home", (name) => (name === "XDG_CONFIG_HOME" ? "/xdg" : undefined))
+      ).toBe(join("/xdg", "opencode"));
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".config", "opencode"));
+    });
+  });
+
   describe("capabilities.agents.buildInstallPath()", () => {
     it("builds path under .opencode/agents/", () => {
       const path = opencode.capabilities.agents.buildInstallPath("code-reviewer.md");

From 22a47f4552b29ddfbbe4c1205d8bcc252f6fccee Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:20:31 +0800
Subject: [PATCH 59/73] test(cli): split each tool profile's tests by feature

Each profiles/<tool>.unit.test.ts becomes profiles/<tool>/<feature>.unit.test.ts (agents, skills, rules, commands, mcp, hooks, plugins, settings, content, profile). The same 434 tests pass, unchanged.
---
 cli/aidd_docs/memory/testing.md               |   1 +
 .../tools/domain/profiles/claude.unit.test.ts | 245 --------
 .../profiles/claude/agents.unit.test.ts       |  34 ++
 .../profiles/claude/commands.unit.test.ts     |  36 ++
 .../profiles/claude/content.unit.test.ts      |  16 +
 .../domain/profiles/claude/mcp.unit.test.ts   |  29 +
 .../profiles/claude/plugins.unit.test.ts      |  82 +++
 .../profiles/claude/profile.unit.test.ts      |  12 +
 .../domain/profiles/claude/rules.unit.test.ts |  53 ++
 .../profiles/claude/skills.unit.test.ts       |  12 +
 .../tools/domain/profiles/codex.unit.test.ts  | 478 ---------------
 .../domain/profiles/codex/agents.unit.test.ts |  22 +
 .../profiles/codex/commands.unit.test.ts      |  24 +
 .../domain/profiles/codex/config.unit.test.ts | 125 ++++
 .../profiles/codex/content.unit.test.ts       |  18 +
 .../domain/profiles/codex/hooks.unit.test.ts  |  94 +++
 .../domain/profiles/codex/mcp.unit.test.ts    |  26 +
 .../profiles/codex/plugins.unit.test.ts       |  62 ++
 .../profiles/codex/profile.unit.test.ts       |  30 +
 .../domain/profiles/codex/rules.unit.test.ts  |  24 +
 .../domain/profiles/codex/skills.unit.test.ts |  82 +++
 .../domain/profiles/copilot.unit.test.ts      | 566 ------------------
 .../profiles/copilot/agents.unit.test.ts      | 100 ++++
 .../profiles/copilot/commands.unit.test.ts    |  41 ++
 .../profiles/copilot/content.unit.test.ts     | 153 +++++
 .../domain/profiles/copilot/mcp.unit.test.ts  |  36 ++
 .../profiles/copilot/plugins.unit.test.ts     |  81 +++
 .../profiles/copilot/profile.unit.test.ts     |  42 ++
 .../profiles/copilot/rules.unit.test.ts       |  99 +++
 .../profiles/copilot/settings.unit.test.ts    |  31 +
 .../profiles/copilot/skills.unit.test.ts      |  11 +
 .../tools/domain/profiles/cursor.unit.test.ts | 206 -------
 .../profiles/cursor/agents.unit.test.ts       |  27 +
 .../profiles/cursor/commands.unit.test.ts     |  24 +
 .../profiles/cursor/content.unit.test.ts      |  20 +
 .../profiles/cursor/plugins.unit.test.ts      |  44 ++
 .../profiles/cursor/profile.unit.test.ts      |  28 +
 .../domain/profiles/cursor/rules.unit.test.ts |  69 +++
 .../profiles/cursor/skills.unit.test.ts       |  16 +
 .../domain/profiles/opencode.unit.test.ts     | 375 ------------
 .../profiles/opencode/agents.unit.test.ts     |  35 ++
 .../profiles/opencode/commands.unit.test.ts   |  30 +
 .../profiles/opencode/content.unit.test.ts    |  14 +
 .../profiles/opencode/hooks.unit.test.ts      |  32 +
 .../domain/profiles/opencode/mcp.unit.test.ts | 194 ++++++
 .../profiles/opencode/plugins.unit.test.ts    |  37 ++
 .../profiles/opencode/rules.unit.test.ts      |  41 ++
 .../profiles/opencode/skills.unit.test.ts     |  18 +
 .../settings.unit.test.ts}                    |   4 +-
 49 files changed, 2007 insertions(+), 1872 deletions(-)
 delete mode 100644 cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/agents.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/commands.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/content.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/mcp.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/plugins.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/profile.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/rules.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/claude/skills.unit.test.ts
 delete mode 100644 cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/agents.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/commands.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/config.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/content.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/hooks.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/mcp.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/plugins.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/profile.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/rules.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/codex/skills.unit.test.ts
 delete mode 100644 cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/commands.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/content.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/mcp.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/plugins.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/profile.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/rules.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/settings.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/copilot/skills.unit.test.ts
 delete mode 100644 cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/commands.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/content.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/plugins.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/profile.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/rules.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/cursor/skills.unit.test.ts
 delete mode 100644 cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/agents.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/commands.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/content.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/hooks.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/mcp.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/plugins.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/rules.unit.test.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/opencode/skills.unit.test.ts
 rename cli/tests/contexts/tools/domain/profiles/{vscode.unit.test.ts => vscode/settings.unit.test.ts} (91%)

diff --git a/cli/aidd_docs/memory/testing.md b/cli/aidd_docs/memory/testing.md
index a48f68392..227bd6445 100644
--- a/cli/aidd_docs/memory/testing.md
+++ b/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.
diff --git a/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
deleted file mode 100644
index d0a172d85..000000000
--- a/cli/tests/contexts/tools/domain/profiles/claude.unit.test.ts
+++ /dev/null
@@ -1,245 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { claude } from "../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
-
-describe("claude", () => {
-  it("has .claude/ directory", () => {
-    expect(claude.directory).toBe(".claude/");
-  });
-
-  it("writes agents as markdown", () => {
-    expect(claude.capabilities.agents.params.format).toBe("markdown");
-  });
-
-  describe("capabilities.mcp", () => {
-    it("outputs to .mcp.json", () => {
-      expect(claude.capabilities.mcp.params.outputPath).toBe(".mcp.json");
-    });
-
-    it("writes its servers as JSON under `mcpServers`", () => {
-      expect(claude.capabilities.mcp.params).toMatchObject({
-        format: "json",
-        entrySection: "mcpServers",
-      });
-    });
-
-    it("consumes the mcp config name", () => {
-      expect(claude.capabilities.mcp.consumes).toContain("mcp");
-    });
-
-    it("does not consume unknown config names", () => {
-      expect(claude.capabilities.mcp.consumes).not.toContain("vscodeDir");
-    });
-
-    it("mcp config preserves user customizations during update", () => {
-      expect(claude.capabilities.mcp.params.mergeStrategy ?? "user-prime").toBe("user-prime");
-    });
-  });
-
-  describe("capabilities.rules.convertFrontmatter()", () => {
-    it("preserves paths: list when already in Claude format", () => {
-      const fm = { paths: ["src/**/*.ts"] };
-      const result = claude.capabilities.rules?.convertFrontmatter(fm);
-      expect(result).toEqual({ paths: ["src/**/*.ts"] });
-    });
-
-    it("strips extra fields when paths key is present", () => {
-      const fm = { paths: ["src/**/*.ts"], description: "extra", alwaysApply: false };
-      const result = claude.capabilities.rules?.convertFrontmatter(fm);
-      expect(result).toEqual({ paths: ["src/**/*.ts"] });
-    });
-
-    it("converts cursor-style globs to paths", () => {
-      const fm = { globs: ["src/**/*.ts"], alwaysApply: false, description: "desc" };
-      const result = claude.capabilities.rules?.convertFrontmatter(fm);
-      expect(result).toEqual({ paths: ["src/**/*.ts"] });
-    });
-
-    it("returns empty frontmatter for always-apply rules (no paths field = unconditional load)", () => {
-      const fm = { description: "desc", alwaysApply: true };
-      const result = claude.capabilities.rules?.convertFrontmatter(fm);
-      expect(result).toEqual({});
-    });
-
-    it("keeps description when alwaysApply is false and no paths are specified", () => {
-      const fm = { description: "Apply when editing command files.", alwaysApply: false };
-      const result = claude.capabilities.rules?.convertFrontmatter(fm);
-      expect(result).toEqual({ description: "Apply when editing command files." });
-    });
-
-    it("returns empty frontmatter for a rule whose paths list is empty", () => {
-      const result = claude.capabilities.rules?.convertFrontmatter({ paths: [] });
-      expect(result).toStrictEqual({});
-    });
-
-    it("returns empty frontmatter for a rule that opts out of always-apply and names no description", () => {
-      const result = claude.capabilities.rules?.convertFrontmatter({ alwaysApply: false });
-      expect(result).toStrictEqual({});
-    });
-  });
-
-  describe("capabilities.skills.buildInstallPath()", () => {
-    it("builds path under .claude/skills/ without the tool suffix", () => {
-      expect(claude.capabilities.skills.buildInstallPath("commit.claude.md")).toBe(
-        ".claude/skills/commit.md"
-      );
-    });
-  });
-
-  it("names the one config file Claude reads, and where it goes", () => {
-    expect(claude.configOutputPaths).toStrictEqual({ "settings.json": ".claude/settings.json" });
-  });
-
-  describe("rewriteContent()", () => {
-    it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
-      expect(
-        claude.rewriteContent?.(
-          "Run .claude/commands/04_code/implement.md, then @.claude/commands/02_context/plan.md.\n"
-        )
-      ).toBe(
-        "Run .claude/commands/aidd/04/implement.md, then @.claude/commands/aidd/02/plan.md.\n"
-      );
-    });
-  });
-
-  describe("capabilities.agents.convertFrontmatter()", () => {
-    it("preserves an explicitly selected agent model", () => {
-      const fm = { name: "alexia", description: "Agent", model: "opus" };
-      const result = claude.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
-    });
-  });
-
-  describe("capabilities.commands.convertFrontmatter()", () => {
-    it("prefixes name with aidd:{phase}:", () => {
-      const fm = { name: "implement", description: "Implement a plan" };
-      const result = claude.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
-      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement a plan" });
-    });
-
-    it("preserves argument-hint when present", () => {
-      const fm = { name: "implement", description: "Implement a plan", "argument-hint": "task" };
-      const result = claude.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
-      expect(result).toEqual({
-        name: "aidd:04:implement",
-        description: "Implement a plan",
-        "argument-hint": "task",
-      });
-    });
-  });
-
-  describe("capabilities.agents.buildInstallPath()", () => {
-    it("builds path for agents section", () => {
-      const path = claude.capabilities.agents.buildInstallPath("code-reviewer.md");
-      expect(path).toBe(".claude/agents/code-reviewer.md");
-    });
-  });
-
-  describe("capabilities.agents.params.userDirectory()", () => {
-    const userDirectory = claude.capabilities.agents.params.userDirectory;
-    it("follows CLAUDE_CONFIG_DIR, else ~/.claude", () => {
-      expect(
-        userDirectory?.("/home", (name) => (name === "CLAUDE_CONFIG_DIR" ? "/cfg" : undefined))
-      ).toBe("/cfg");
-      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".claude"));
-    });
-  });
-
-  describe("capabilities.rules.buildInstallPath()", () => {
-    it("builds path for rules section with subdirectory", () => {
-      const path = claude.capabilities.rules?.buildInstallPath("01-standards/naming.md");
-      expect(path).toBe(".claude/rules/01-standards/naming.md");
-    });
-  });
-
-  describe("capabilities.commands.buildInstallPath()", () => {
-    it("builds commands path with aidd brand prefix and phase number", () => {
-      const path = claude.capabilities.commands?.buildInstallPath("04_code/implement.md");
-      expect(path).toBe(".claude/commands/aidd/04/implement.md");
-    });
-
-    it("handles two-digit phase in commands", () => {
-      const path = claude.capabilities.commands?.buildInstallPath(
-        "02_context/create_user_stories.md"
-      );
-      expect(path).toBe(".claude/commands/aidd/02/create_user_stories.md");
-    });
-  });
-
-  describe("capabilities.plugins", () => {
-    it("has a plugins capability", () => {
-      expect("plugins" in claude.capabilities).toBe(true);
-    });
-
-    it("is native mode", () => {
-      expect(claude.capabilities.plugins.mode).toBe("native");
-    });
-
-    it("uses .claude/plugins/ as plugins directory", () => {
-      expect(claude.capabilities.plugins.pluginsDir).toBe(".claude/plugins/");
-    });
-
-    it("uses plugin.json as plugin manifest path", () => {
-      expect(claude.capabilities.plugins.pluginManifestRelativePath).toBe("plugin.json");
-    });
-
-    it("pluginOutputDir returns correct path for a plugin name", () => {
-      expect(claude.capabilities.plugins.pluginOutputDir("my-plugin")).toBe(
-        ".claude/plugins/my-plugin/"
-      );
-    });
-
-    it("declares its own marketplace registry and plugin cache root, for clean's own purge", () => {
-      const activation = claude.capabilities.plugins.nativeActivation;
-      expect(activation?.marketplaceRegistry?.("/home/tester")).toBe(
-        join("/home/tester", ".claude", "plugins", "known_marketplaces.json")
-      );
-      expect(activation?.pluginCacheDir?.("/home/tester")).toBe(
-        join("/home/tester", ".claude", "plugins", "cache")
-      );
-    });
-
-    it("declares where claude's own user-scope settings file lives, for --scope user", () => {
-      const activation = claude.capabilities.plugins.nativeActivation;
-      expect(activation?.userSettingsPath?.("/home/tester", () => undefined)).toBe(
-        join("/home/tester", ".claude", "settings.json")
-      );
-    });
-
-    it("drives the claude binary at local scope, with the verbs claude uses and nothing else", () => {
-      // Exhaustive, not `toMatchObject`: a field added by mistake must fail here.
-      expect(claude.capabilities.plugins.nativeActivation).toStrictEqual({
-        binary: "claude",
-        scopeArgs: { project: ["--scope", "local"], user: ["--scope", "user"] },
-        enableVerb: "install",
-        disableVerb: "uninstall",
-        upgradeVerb: "update",
-        pluginArgs: ["--yes"],
-        marketplaceRegistry: expect.any(Function),
-        pluginCacheDir: expect.any(Function),
-        userSettingsPath: expect.any(Function),
-      });
-    });
-
-    it("registers a marketplace in the file claude writes itself, and enables plugins in the tracked one", () => {
-      const settings = claude.capabilities.plugins.marketplaceSettings;
-
-      expect({
-        settingsPath: settings?.settingsPath,
-        settingsKey: settings?.settingsKey,
-        marketplacesSettingsPath: settings?.marketplacesSettingsPath,
-        enabledPluginsKey: settings?.enabledPluginsKey,
-        entryKey: settings?.toEntryKey?.({
-          name: "aidd-framework",
-          source: { kind: "local", path: "/abs/cache" },
-        }),
-      }).toStrictEqual({
-        settingsPath: ".claude/settings.json",
-        settingsKey: "extraKnownMarketplaces",
-        marketplacesSettingsPath: ".claude/settings.local.json",
-        enabledPluginsKey: "enabledPlugins",
-        entryKey: "aidd-framework",
-      });
-    });
-  });
-});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/agents.unit.test.ts
new file mode 100644
index 000000000..d07678b1e
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/agents.unit.test.ts
@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude agents", () => {
+  it("writes agents as markdown", () => {
+    expect(claude.capabilities.agents.params.format).toBe("markdown");
+  });
+
+  describe("capabilities.agents.convertFrontmatter()", () => {
+    it("preserves an explicitly selected agent model", () => {
+      const fm = { name: "alexia", description: "Agent", model: "opus" };
+      const result = claude.capabilities.agents.convertFrontmatter(fm);
+      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
+    });
+  });
+
+  describe("capabilities.agents.buildInstallPath()", () => {
+    it("builds path for agents section", () => {
+      const path = claude.capabilities.agents.buildInstallPath("code-reviewer.md");
+      expect(path).toBe(".claude/agents/code-reviewer.md");
+    });
+  });
+
+  describe("capabilities.agents.params.userDirectory()", () => {
+    const userDirectory = claude.capabilities.agents.params.userDirectory;
+    it("follows CLAUDE_CONFIG_DIR, else ~/.claude", () => {
+      expect(
+        userDirectory?.("/home", (name) => (name === "CLAUDE_CONFIG_DIR" ? "/cfg" : undefined))
+      ).toBe("/cfg");
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".claude"));
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/commands.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/commands.unit.test.ts
new file mode 100644
index 000000000..b8cb5705d
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/commands.unit.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude commands", () => {
+  describe("capabilities.commands.convertFrontmatter()", () => {
+    it("prefixes name with aidd:{phase}:", () => {
+      const fm = { name: "implement", description: "Implement a plan" };
+      const result = claude.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
+      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement a plan" });
+    });
+
+    it("preserves argument-hint when present", () => {
+      const fm = { name: "implement", description: "Implement a plan", "argument-hint": "task" };
+      const result = claude.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
+      expect(result).toEqual({
+        name: "aidd:04:implement",
+        description: "Implement a plan",
+        "argument-hint": "task",
+      });
+    });
+  });
+
+  describe("capabilities.commands.buildInstallPath()", () => {
+    it("builds commands path with aidd brand prefix and phase number", () => {
+      const path = claude.capabilities.commands?.buildInstallPath("04_code/implement.md");
+      expect(path).toBe(".claude/commands/aidd/04/implement.md");
+    });
+
+    it("handles two-digit phase in commands", () => {
+      const path = claude.capabilities.commands?.buildInstallPath(
+        "02_context/create_user_stories.md"
+      );
+      expect(path).toBe(".claude/commands/aidd/02/create_user_stories.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/content.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/content.unit.test.ts
new file mode 100644
index 000000000..848bedfaa
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/content.unit.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude content", () => {
+  describe("rewriteContent()", () => {
+    it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
+      expect(
+        claude.rewriteContent?.(
+          "Run .claude/commands/04_code/implement.md, then @.claude/commands/02_context/plan.md.\n"
+        )
+      ).toBe(
+        "Run .claude/commands/aidd/04/implement.md, then @.claude/commands/aidd/02/plan.md.\n"
+      );
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/mcp.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/mcp.unit.test.ts
new file mode 100644
index 000000000..7b234ca4d
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/mcp.unit.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude mcp", () => {
+  describe("capabilities.mcp", () => {
+    it("outputs to .mcp.json", () => {
+      expect(claude.capabilities.mcp.params.outputPath).toBe(".mcp.json");
+    });
+
+    it("writes its servers as JSON under `mcpServers`", () => {
+      expect(claude.capabilities.mcp.params).toMatchObject({
+        format: "json",
+        entrySection: "mcpServers",
+      });
+    });
+
+    it("consumes the mcp config name", () => {
+      expect(claude.capabilities.mcp.consumes).toContain("mcp");
+    });
+
+    it("does not consume unknown config names", () => {
+      expect(claude.capabilities.mcp.consumes).not.toContain("vscodeDir");
+    });
+
+    it("mcp config preserves user customizations during update", () => {
+      expect(claude.capabilities.mcp.params.mergeStrategy ?? "user-prime").toBe("user-prime");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/plugins.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/plugins.unit.test.ts
new file mode 100644
index 000000000..aa073ea4d
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/plugins.unit.test.ts
@@ -0,0 +1,82 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude plugins", () => {
+  describe("capabilities.plugins", () => {
+    it("has a plugins capability", () => {
+      expect("plugins" in claude.capabilities).toBe(true);
+    });
+
+    it("is native mode", () => {
+      expect(claude.capabilities.plugins.mode).toBe("native");
+    });
+
+    it("uses .claude/plugins/ as plugins directory", () => {
+      expect(claude.capabilities.plugins.pluginsDir).toBe(".claude/plugins/");
+    });
+
+    it("uses plugin.json as plugin manifest path", () => {
+      expect(claude.capabilities.plugins.pluginManifestRelativePath).toBe("plugin.json");
+    });
+
+    it("pluginOutputDir returns correct path for a plugin name", () => {
+      expect(claude.capabilities.plugins.pluginOutputDir("my-plugin")).toBe(
+        ".claude/plugins/my-plugin/"
+      );
+    });
+
+    it("declares its own marketplace registry and plugin cache root, for clean's own purge", () => {
+      const activation = claude.capabilities.plugins.nativeActivation;
+      expect(activation?.marketplaceRegistry?.("/home/tester")).toBe(
+        join("/home/tester", ".claude", "plugins", "known_marketplaces.json")
+      );
+      expect(activation?.pluginCacheDir?.("/home/tester")).toBe(
+        join("/home/tester", ".claude", "plugins", "cache")
+      );
+    });
+
+    it("declares where claude's own user-scope settings file lives, for --scope user", () => {
+      const activation = claude.capabilities.plugins.nativeActivation;
+      expect(activation?.userSettingsPath?.("/home/tester", () => undefined)).toBe(
+        join("/home/tester", ".claude", "settings.json")
+      );
+    });
+
+    it("drives the claude binary at local scope, with the verbs claude uses and nothing else", () => {
+      // Exhaustive, not `toMatchObject`: a field added by mistake must fail here.
+      expect(claude.capabilities.plugins.nativeActivation).toStrictEqual({
+        binary: "claude",
+        scopeArgs: { project: ["--scope", "local"], user: ["--scope", "user"] },
+        enableVerb: "install",
+        disableVerb: "uninstall",
+        upgradeVerb: "update",
+        pluginArgs: ["--yes"],
+        marketplaceRegistry: expect.any(Function),
+        pluginCacheDir: expect.any(Function),
+        userSettingsPath: expect.any(Function),
+      });
+    });
+
+    it("registers a marketplace in the file claude writes itself, and enables plugins in the tracked one", () => {
+      const settings = claude.capabilities.plugins.marketplaceSettings;
+
+      expect({
+        settingsPath: settings?.settingsPath,
+        settingsKey: settings?.settingsKey,
+        marketplacesSettingsPath: settings?.marketplacesSettingsPath,
+        enabledPluginsKey: settings?.enabledPluginsKey,
+        entryKey: settings?.toEntryKey?.({
+          name: "aidd-framework",
+          source: { kind: "local", path: "/abs/cache" },
+        }),
+      }).toStrictEqual({
+        settingsPath: ".claude/settings.json",
+        settingsKey: "extraKnownMarketplaces",
+        marketplacesSettingsPath: ".claude/settings.local.json",
+        enabledPluginsKey: "enabledPlugins",
+        entryKey: "aidd-framework",
+      });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/profile.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/profile.unit.test.ts
new file mode 100644
index 000000000..5e0e28907
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/profile.unit.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude profile", () => {
+  it("has .claude/ directory", () => {
+    expect(claude.directory).toBe(".claude/");
+  });
+
+  it("names the one config file Claude reads, and where it goes", () => {
+    expect(claude.configOutputPaths).toStrictEqual({ "settings.json": ".claude/settings.json" });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/rules.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/rules.unit.test.ts
new file mode 100644
index 000000000..f5e6e4d52
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/rules.unit.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude rules", () => {
+  describe("capabilities.rules.convertFrontmatter()", () => {
+    it("preserves paths: list when already in Claude format", () => {
+      const fm = { paths: ["src/**/*.ts"] };
+      const result = claude.capabilities.rules?.convertFrontmatter(fm);
+      expect(result).toEqual({ paths: ["src/**/*.ts"] });
+    });
+
+    it("strips extra fields when paths key is present", () => {
+      const fm = { paths: ["src/**/*.ts"], description: "extra", alwaysApply: false };
+      const result = claude.capabilities.rules?.convertFrontmatter(fm);
+      expect(result).toEqual({ paths: ["src/**/*.ts"] });
+    });
+
+    it("converts cursor-style globs to paths", () => {
+      const fm = { globs: ["src/**/*.ts"], alwaysApply: false, description: "desc" };
+      const result = claude.capabilities.rules?.convertFrontmatter(fm);
+      expect(result).toEqual({ paths: ["src/**/*.ts"] });
+    });
+
+    it("returns empty frontmatter for always-apply rules (no paths field = unconditional load)", () => {
+      const fm = { description: "desc", alwaysApply: true };
+      const result = claude.capabilities.rules?.convertFrontmatter(fm);
+      expect(result).toEqual({});
+    });
+
+    it("keeps description when alwaysApply is false and no paths are specified", () => {
+      const fm = { description: "Apply when editing command files.", alwaysApply: false };
+      const result = claude.capabilities.rules?.convertFrontmatter(fm);
+      expect(result).toEqual({ description: "Apply when editing command files." });
+    });
+
+    it("returns empty frontmatter for a rule whose paths list is empty", () => {
+      const result = claude.capabilities.rules?.convertFrontmatter({ paths: [] });
+      expect(result).toStrictEqual({});
+    });
+
+    it("returns empty frontmatter for a rule that opts out of always-apply and names no description", () => {
+      const result = claude.capabilities.rules?.convertFrontmatter({ alwaysApply: false });
+      expect(result).toStrictEqual({});
+    });
+  });
+
+  describe("capabilities.rules.buildInstallPath()", () => {
+    it("builds path for rules section with subdirectory", () => {
+      const path = claude.capabilities.rules?.buildInstallPath("01-standards/naming.md");
+      expect(path).toBe(".claude/rules/01-standards/naming.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/skills.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/skills.unit.test.ts
new file mode 100644
index 000000000..ce703b2b0
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/claude/skills.unit.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { claude } from "../../../../../../src/contexts/tools/domain/profiles/claude/profile.js";
+
+describe("claude skills", () => {
+  describe("capabilities.skills.buildInstallPath()", () => {
+    it("builds path under .claude/skills/ without the tool suffix", () => {
+      expect(claude.capabilities.skills.buildInstallPath("commit.claude.md")).toBe(
+        ".claude/skills/commit.md"
+      );
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts
deleted file mode 100644
index 7b8a3a9e5..000000000
--- a/cli/tests/contexts/tools/domain/profiles/codex.unit.test.ts
+++ /dev/null
@@ -1,478 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import {
-  mergeCodexConfigToml,
-  stripCodexSkillFrontmatter,
-} from "../../../../../src/contexts/tools/domain/profiles/codex/build.js";
-import {
-  codex,
-  mergeCodexHooksJson,
-  rewriteCodexContent,
-} from "../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
-import { getToolConfig } from "../../../../../src/contexts/tools/domain/registry.js";
-import { serializeFrontmatter } from "../../../../../src/kernel/markdown.js";
-
-describe("codex", () => {
-  it("has toolId codex", () => {
-    expect(codex.toolId).toBe("codex");
-  });
-
-  it("has .codex/ directory", () => {
-    expect(codex.directory).toBe(".codex/");
-  });
-
-  it("has .codex.md tool suffix", () => {
-    expect(codex.toolSuffix).toBe(".codex.md");
-  });
-
-  it("has signalDir pointing at .codex/commands", () => {
-    expect(codex.signalDir).toBe(".codex/commands");
-  });
-
-  it("is registered in the tool registry", () => {
-    const config = getToolConfig("codex");
-    expect(config.toolId).toBe("codex");
-  });
-
-  describe("capabilities.skills.buildInstallPath()", () => {
-    it("builds path under .agents/skills/aidd-{name}/SKILL.md", () => {
-      const path = codex.capabilities.skills.buildInstallPath("my-skill/SKILL.md");
-      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
-    });
-
-    it("strips .codex.md tool suffix", () => {
-      const path = codex.capabilities.skills.buildInstallPath("my-skill.codex.md");
-      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
-    });
-
-    it("strips plain .md suffix from skill name", () => {
-      const path = codex.capabilities.skills.buildInstallPath("my-skill.md");
-      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
-    });
-
-    it("keeps a skill name that carries no extension at all", () => {
-      const path = codex.capabilities.skills.buildInstallPath("my-skill");
-      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
-    });
-
-    it("keeps a skill folder's name whole, even one ending in .md", () => {
-      const path = codex.capabilities.skills.buildInstallPath("notes.md/SKILL.md");
-      expect(path).toBe(".agents/skills/aidd-notes.md/SKILL.md");
-    });
-  });
-
-  it("names the one config file Codex reads, and where it goes", () => {
-    expect(codex.configOutputPaths).toStrictEqual({ "config.toml": ".codex/config.toml" });
-  });
-
-  describe("capabilities.agents.params.userDirectory()", () => {
-    it("follows CODEX_HOME, else ~/.codex", () => {
-      const userDirectory = codex.capabilities.agents.params.userDirectory;
-      expect(userDirectory?.("/home", (name) => (name === "CODEX_HOME" ? "/cx" : undefined))).toBe(
-        "/cx"
-      );
-      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".codex"));
-    });
-  });
-
-  describe("capabilities.agents.buildInstallPath()", () => {
-    it("builds .toml path under .codex/agents/", () => {
-      const path = codex.capabilities.agents.buildInstallPath("alexia.md");
-      expect(path).toBe(".codex/agents/alexia.toml");
-    });
-  });
-
-  describe("capabilities.mcp", () => {
-    it("outputs to .codex/config.toml", () => {
-      expect(codex.capabilities.mcp.params.outputPath).toBe(".codex/config.toml");
-    });
-
-    it("consumes the mcp config name", () => {
-      expect(codex.capabilities.mcp.consumes).toContain("mcp");
-    });
-
-    it("uses user-prime merge strategy", () => {
-      expect(codex.capabilities.mcp.params.mergeStrategy ?? "user-prime").toBe("user-prime");
-    });
-
-    it("uses mcp_servers as entry section", () => {
-      expect(codex.capabilities.mcp.params.entrySection).toBe("mcp_servers");
-    });
-
-    it("writes its config in TOML", () => {
-      expect(codex.capabilities.mcp.params.format).toBe("toml");
-    });
-  });
-
-  describe("capabilities.hooks", () => {
-    it("outputs to .codex/hooks.json", () => {
-      expect(codex.capabilities.hooks.buildOutputPath()).toBe(".codex/hooks.json");
-    });
-
-    it("consumes the codex-hooks config name", () => {
-      expect(codex.capabilities.hooks.consumes).toContain("codex-hooks");
-    });
-
-    it("uses user-prime merge strategy", () => {
-      expect(codex.capabilities.hooks.getMergeStrategy()).toBe("user-prime");
-    });
-
-    it("uses SessionStart as entry section", () => {
-      expect(codex.capabilities.hooks.getEntrySection()).toBe("SessionStart");
-    });
-
-    it("returns null entry section for unknown config names", () => {
-      const cap = [codex.capabilities.mcp, codex.capabilities.hooks].find((c) =>
-        c.consumes.includes("unknown")
-      );
-      expect(cap).toBeUndefined();
-    });
-  });
-
-  describe("capabilities.commands.buildInstallPath()", () => {
-    it("maps phase-prefixed path to .codex/commands/aidd/<phase>/ subfolder", () => {
-      const path = codex.capabilities.commands.buildInstallPath("04_code/implement.md");
-      expect(path).toBe(".codex/commands/aidd/04/implement.md");
-    });
-
-    it("maps top-level file to .codex/commands/aidd/ without phase", () => {
-      const path = codex.capabilities.commands.buildInstallPath("commit.md");
-      expect(path).toBe(".codex/commands/aidd/commit.md");
-    });
-  });
-
-  describe("capabilities.commands.convertFrontmatter()", () => {
-    it("prefixes name with aidd:<phase>: and strips extra fields", () => {
-      const fm = { name: "implement", description: "Implement", model: "sonnet" };
-      const result = codex.capabilities.commands.convertFrontmatter(fm, "04_code/implement.md");
-      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement" });
-    });
-  });
-
-  describe("capabilities.rules.buildInstallPath()", () => {
-    it("builds path for rules under .codex/rules/", () => {
-      const path = codex.capabilities.rules.buildInstallPath("01-standards/naming.md");
-      expect(path).toBe(".codex/rules/01-standards/naming.md");
-    });
-
-    it("strips .codex.md tool suffix from rules path", () => {
-      const path = codex.capabilities.rules.buildInstallPath("01-standards/naming.codex.md");
-      expect(path).toBe(".codex/rules/01-standards/naming.md");
-    });
-  });
-
-  describe("capabilities.rules.convertFrontmatter()", () => {
-    it("passes frontmatter through unchanged", () => {
-      const fm = { paths: ["src/**/*.ts"], description: "TS rules" };
-      const result = codex.capabilities.rules.convertFrontmatter(fm);
-      expect(result).toEqual(fm);
-    });
-  });
-
-  describe("capabilities.plugins", () => {
-    it("declares native codex CLI activation, with the verbs codex uses, and nothing else", () => {
-      const activation = codex.capabilities.plugins.nativeActivation;
-      // Exhaustive, not `toMatchObject`: a field added by mistake must fail here rather than
-      // escape. `pluginCacheDir` is `expect.any(Function)`, since a function matches no literal.
-      expect(activation).toEqual({
-        binary: "codex",
-        upgradeVerb: "upgrade",
-        enableVerb: "add",
-        disableVerb: "remove",
-        pluginCacheDir: expect.any(Function),
-        userSettingsPath: expect.any(Function),
-      });
-    });
-
-    it("declares its own plugin cache root, so clean can purge the empty shell codex leaves behind", () => {
-      const pluginCacheDir = codex.capabilities.plugins.nativeActivation?.pluginCacheDir;
-      expect(pluginCacheDir?.("/home/tester")).toBe(
-        join("/home/tester", ".codex", "plugins", "cache")
-      );
-    });
-
-    describe("nativeActivation.userSettingsPath()", () => {
-      const environment = (vars: Record<string, string>) => (name: string) => vars[name];
-
-      it("falls back to ~/.codex/config.toml when CODEX_HOME is unset", () => {
-        const userSettingsPath = codex.capabilities.plugins.nativeActivation?.userSettingsPath;
-        expect(userSettingsPath?.("/home/tester", environment({}))).toBe(
-          join("/home/tester", ".codex", "config.toml")
-        );
-      });
-
-      it("follows CODEX_HOME when a real machine has it set — the real codex binary reads there, not ~/.codex", () => {
-        const userSettingsPath = codex.capabilities.plugins.nativeActivation?.userSettingsPath;
-        expect(
-          userSettingsPath?.("/home/tester", environment({ CODEX_HOME: "/somewhere/else" }))
-        ).toBe(join("/somewhere/else", "config.toml"));
-      });
-    });
-
-    it("does not write a project-local marketplace settings file", () => {
-      expect(codex.capabilities.plugins.marketplaceSettings).toBeNull();
-    });
-
-    it("keeps the marketplace translation mode", () => {
-      expect(codex.capabilities.plugins.translationMode).toBe("marketplace");
-    });
-
-    it("warns that Codex runs no hook it has not been told to trust, and how to tell it", () => {
-      expect(codex.capabilities.plugins.hooksTrustNotice).toBe(
-        "Codex will not run this plugin's hooks until each one is trusted — approve the prompt " +
-          "once in an interactive session, or pass --dangerously-bypass-hook-trust to codex exec " +
-          "for a headless run. Until then, none of its hooks run and nothing says why."
-      );
-    });
-  });
-});
-
-describe("rewriteCodexContent()", () => {
-  it("sends a skill reference to the agents directory Codex scans, under its aidd- prefix", () => {
-    expect(rewriteCodexContent("Read .codex/skills/01-plan/SKILL.md\n")).toBe(
-      "Read .agents/skills/aidd-01-plan/SKILL.md\n"
-    );
-  });
-
-  it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
-    expect(
-      rewriteCodexContent(
-        "Run .codex/commands/04_code/implement.md, then @.codex/commands/02-plan/plan.md.\n"
-      )
-    ).toBe("Run .codex/commands/aidd/04/implement.md, then @.codex/commands/aidd/02/plan.md.\n");
-  });
-});
-
-describe("mergeCodexHooksJson()", () => {
-  const AIDD_ENTRY = {
-    matcher: "startup|resume",
-    hooks: [
-      {
-        type: "command",
-        command: "node .aidd/scripts/update_memory.cjs",
-        statusMessage: "Syncing AIDD memory...",
-        timeout: 30,
-      },
-    ],
-  };
-
-  it("subscribes the memory refresh to a fresh session, on startup and on resume", () => {
-    expect(mergeCodexHooksJson("")).toBe(JSON.stringify({ SessionStart: [AIDD_ENTRY] }, null, 2));
-  });
-
-  it("keeps a user's own hooks and appends the memory refresh after them", () => {
-    const existing = JSON.stringify({
-      PreToolUse: [{ hooks: [{ type: "command", command: "user.sh" }] }],
-      SessionStart: [{ hooks: [{ type: "command", command: "user-start.sh" }] }],
-    });
-
-    expect(mergeCodexHooksJson(existing)).toBe(
-      JSON.stringify(
-        {
-          PreToolUse: [{ hooks: [{ type: "command", command: "user.sh" }] }],
-          SessionStart: [{ hooks: [{ type: "command", command: "user-start.sh" }] }, AIDD_ENTRY],
-        },
-        null,
-        2
-      )
-    );
-  });
-
-  it("adds nothing on a second run over its own output", () => {
-    const once = mergeCodexHooksJson("");
-    expect(mergeCodexHooksJson(once)).toBe(once);
-  });
-
-  it("finds its own hook inside any group of a user's SessionStart, and adds no second one", () => {
-    const existing = JSON.stringify(
-      {
-        SessionStart: [
-          { hooks: [{ type: "command", command: "user-start.sh" }] },
-          { hooks: [{ type: "command", command: "user-two.sh" }, AIDD_ENTRY.hooks[0]] },
-        ],
-      },
-      null,
-      2
-    );
-
-    expect(mergeCodexHooksJson(existing)).toBe(existing);
-  });
-
-  it("starts over from a file it cannot read rather than failing the install", () => {
-    expect(mergeCodexHooksJson("{ not json")).toBe(
-      JSON.stringify({ SessionStart: [AIDD_ENTRY] }, null, 2)
-    );
-  });
-});
-
-const MCP_PAYLOAD = `
-[mcp_servers.playwright]
-command = "npx"
-args = ["-y", "@anthropic-ai/mcp-playwright"]
-`;
-
-describe("mergeCodexConfigToml", () => {
-  it("writes full payload into empty file", () => {
-    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
-    expect(result).toContain("mcp_servers");
-    expect(result).toContain("playwright");
-    expect(result).toContain("project_doc_max_bytes = 262144");
-    expect(result).toContain("hooks = true");
-  });
-
-  it("preserves user keys not managed by AIDD", () => {
-    const existing = `
-[user_section]
-custom_key = "user value"
-`;
-    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
-    expect(result).toContain('custom_key = "user value"');
-    expect(result).toContain("playwright");
-  });
-
-  it("is idempotent on second run", () => {
-    const first = mergeCodexConfigToml("", MCP_PAYLOAD);
-    const second = mergeCodexConfigToml(first, MCP_PAYLOAD);
-    expect(second).toContain("playwright");
-    const mcpCount = (second.match(/\[mcp_servers\.playwright\]/g) ?? []).length;
-    expect(mcpCount).toBe(1);
-  });
-
-  it("existing MCP server wins on conflict (user-prime)", () => {
-    const existing = `
-[mcp_servers.playwright]
-command = "user-command"
-`;
-    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
-    expect(result).toContain('command = "user-command"');
-    expect(result).not.toContain('"npx"');
-  });
-
-  it("preserves user project_doc_max_bytes when above minimum", () => {
-    const existing = `project_doc_max_bytes = 999999`;
-    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
-    expect(result).toContain("project_doc_max_bytes = 999999");
-    expect(result).not.toContain("262144");
-  });
-
-  it("sets minimum project_doc_max_bytes when absent", () => {
-    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
-    expect(result).toContain("project_doc_max_bytes = 262144");
-  });
-
-  it("ensures hooks feature when absent", () => {
-    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
-    expect(result).toContain("hooks = true");
-  });
-
-  it("preserves user codex_hooks value when already set", () => {
-    const existing = `
-[features]
-codex_hooks = false
-`;
-    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
-    expect(result).toContain("codex_hooks = false");
-    expect(result).not.toContain("hooks = true");
-  });
-
-  it("does NOT emit [[skills.config]] — discovery is by placement", () => {
-    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
-    expect(result).not.toContain(".agents/skills");
-    expect(result).not.toContain("skills.config");
-  });
-
-  it("preserves existing skills.config if user has one", () => {
-    const existing = `
-[skills.config]
-path = ".agents/skills"
-enabled = true
-`;
-    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
-    expect(result).toContain(".agents/skills");
-  });
-
-  it("starts over from a config it cannot parse rather than failing the install", () => {
-    expect(mergeCodexConfigToml("not = [valid", '[mcp_servers.ctx]\ncommand = "node"\n')).toBe(
-      'project_doc_max_bytes = 262144\n\n[mcp_servers.ctx]\ncommand = "node"\n\n[features]\nhooks = true\n'
-    );
-  });
-
-  it("adds only its defaults when the payload names no mcp server", () => {
-    expect(mergeCodexConfigToml('[mcp_servers.mine]\ncommand = "x"\n', "")).toBe(
-      'project_doc_max_bytes = 262144\n\n[mcp_servers.mine]\ncommand = "x"\n\n[features]\nhooks = true\n'
-    );
-  });
-
-  it("raises project_doc_max_bytes to what the payload asks when that is above the floor", () => {
-    expect(mergeCodexConfigToml("", "project_doc_max_bytes = 500000\n")).toBe(
-      "project_doc_max_bytes = 500000\n\n[features]\nhooks = true\n"
-    );
-  });
-
-  it("leaves a user's project_doc_max_bytes already at the floor untouched, whatever the payload asks", () => {
-    expect(
-      mergeCodexConfigToml("project_doc_max_bytes = 262144\n", "project_doc_max_bytes = 500000\n")
-    ).toBe("project_doc_max_bytes = 262144\n\n[features]\nhooks = true\n");
-  });
-
-  it("keeps a user's own hooks = false rather than turning hooks on", () => {
-    expect(mergeCodexConfigToml("[features]\nhooks = false\n", "")).toBe(
-      "project_doc_max_bytes = 262144\n\n[features]\nhooks = false\n"
-    );
-  });
-
-  it("turns hooks on beside a user's other features, keeping them", () => {
-    expect(mergeCodexConfigToml("[features]\nweb_search = true\n", "")).toBe(
-      "project_doc_max_bytes = 262144\n\n[features]\nweb_search = true\nhooks = true\n"
-    );
-  });
-});
-
-/**
- * Codex is the only target that re-serialises skill frontmatter instead of passing the file
- * through, so these pin the transform itself rather than the golden that recorded its output.
- */
-describe("a skill's frontmatter, rewritten for Codex", () => {
-  const rebuild = (fm: Record<string, unknown>) =>
-    serializeFrontmatter(stripCodexSkillFrontmatter(fm), "body\n");
-
-  it("keeps the three fields Codex reads", () => {
-    expect(
-      stripCodexSkillFrontmatter({
-        name: "aidd-dev:01:plan",
-        description: "Plan things",
-        allowed_tools: ["Read"],
-      })
-    ).toEqual({ name: "aidd-dev:01:plan", description: "Plan things", allowed_tools: ["Read"] });
-  });
-
-  it("drops the fields it does not, rather than passing them through", () => {
-    // `model` is the one the framework ships and Codex has no use for.
-    expect(stripCodexSkillFrontmatter({ name: "n", description: "d", model: "opus" })).toEqual({
-      name: "n",
-      description: "d",
-    });
-  });
-
-  it("omits a field the source never set", () => {
-    expect(stripCodexSkillFrontmatter({ description: "d" })).toEqual({ description: "d" });
-  });
-
-  it("writes no description key for a skill that has none", () => {
-    expect(stripCodexSkillFrontmatter({ name: "n" })).toStrictEqual({ name: "n" });
-  });
-
-  it("quotes a value whose colon would otherwise make the frontmatter unreadable", () => {
-    // Not cosmetic: a description containing ": " makes `js-yaml` refuse the source with "bad
-    // indentation of a mapping entry". Re-serialising with quotes is what makes it parse.
-    expect(rebuild({ name: "aidd-context:03:context-generate", description: "Do a: thing" })).toBe(
-      "---\nname: 'aidd-context:03:context-generate'\ndescription: 'Do a: thing'\n---\nbody\n"
-    );
-  });
-
-  it("escapes a quote in the value rather than closing the string early", () => {
-    expect(rebuild({ description: "it's here" })).toBe(
-      "---\ndescription: 'it''s here'\n---\nbody\n"
-    );
-  });
-});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/agents.unit.test.ts
new file mode 100644
index 000000000..ceedcc863
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/agents.unit.test.ts
@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("codex agents", () => {
+  describe("capabilities.agents.params.userDirectory()", () => {
+    it("follows CODEX_HOME, else ~/.codex", () => {
+      const userDirectory = codex.capabilities.agents.params.userDirectory;
+      expect(userDirectory?.("/home", (name) => (name === "CODEX_HOME" ? "/cx" : undefined))).toBe(
+        "/cx"
+      );
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".codex"));
+    });
+  });
+
+  describe("capabilities.agents.buildInstallPath()", () => {
+    it("builds .toml path under .codex/agents/", () => {
+      const path = codex.capabilities.agents.buildInstallPath("alexia.md");
+      expect(path).toBe(".codex/agents/alexia.toml");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/commands.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/commands.unit.test.ts
new file mode 100644
index 000000000..9cc34ab61
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/commands.unit.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("codex commands", () => {
+  describe("capabilities.commands.buildInstallPath()", () => {
+    it("maps phase-prefixed path to .codex/commands/aidd/<phase>/ subfolder", () => {
+      const path = codex.capabilities.commands.buildInstallPath("04_code/implement.md");
+      expect(path).toBe(".codex/commands/aidd/04/implement.md");
+    });
+
+    it("maps top-level file to .codex/commands/aidd/ without phase", () => {
+      const path = codex.capabilities.commands.buildInstallPath("commit.md");
+      expect(path).toBe(".codex/commands/aidd/commit.md");
+    });
+  });
+
+  describe("capabilities.commands.convertFrontmatter()", () => {
+    it("prefixes name with aidd:<phase>: and strips extra fields", () => {
+      const fm = { name: "implement", description: "Implement", model: "sonnet" };
+      const result = codex.capabilities.commands.convertFrontmatter(fm, "04_code/implement.md");
+      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement" });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/config.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/config.unit.test.ts
new file mode 100644
index 000000000..2bd082e34
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/config.unit.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { mergeCodexConfigToml } from "../../../../../../src/contexts/tools/domain/profiles/codex/build.js";
+
+const MCP_PAYLOAD = `
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@anthropic-ai/mcp-playwright"]
+`;
+
+describe("mergeCodexConfigToml", () => {
+  it("writes full payload into empty file", () => {
+    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
+    expect(result).toContain("mcp_servers");
+    expect(result).toContain("playwright");
+    expect(result).toContain("project_doc_max_bytes = 262144");
+    expect(result).toContain("hooks = true");
+  });
+
+  it("preserves user keys not managed by AIDD", () => {
+    const existing = `
+[user_section]
+custom_key = "user value"
+`;
+    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
+    expect(result).toContain('custom_key = "user value"');
+    expect(result).toContain("playwright");
+  });
+
+  it("is idempotent on second run", () => {
+    const first = mergeCodexConfigToml("", MCP_PAYLOAD);
+    const second = mergeCodexConfigToml(first, MCP_PAYLOAD);
+    expect(second).toContain("playwright");
+    const mcpCount = (second.match(/\[mcp_servers\.playwright\]/g) ?? []).length;
+    expect(mcpCount).toBe(1);
+  });
+
+  it("existing MCP server wins on conflict (user-prime)", () => {
+    const existing = `
+[mcp_servers.playwright]
+command = "user-command"
+`;
+    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
+    expect(result).toContain('command = "user-command"');
+    expect(result).not.toContain('"npx"');
+  });
+
+  it("preserves user project_doc_max_bytes when above minimum", () => {
+    const existing = `project_doc_max_bytes = 999999`;
+    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
+    expect(result).toContain("project_doc_max_bytes = 999999");
+    expect(result).not.toContain("262144");
+  });
+
+  it("sets minimum project_doc_max_bytes when absent", () => {
+    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
+    expect(result).toContain("project_doc_max_bytes = 262144");
+  });
+
+  it("ensures hooks feature when absent", () => {
+    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
+    expect(result).toContain("hooks = true");
+  });
+
+  it("preserves user codex_hooks value when already set", () => {
+    const existing = `
+[features]
+codex_hooks = false
+`;
+    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
+    expect(result).toContain("codex_hooks = false");
+    expect(result).not.toContain("hooks = true");
+  });
+
+  it("does NOT emit [[skills.config]] — discovery is by placement", () => {
+    const result = mergeCodexConfigToml("", MCP_PAYLOAD);
+    expect(result).not.toContain(".agents/skills");
+    expect(result).not.toContain("skills.config");
+  });
+
+  it("preserves existing skills.config if user has one", () => {
+    const existing = `
+[skills.config]
+path = ".agents/skills"
+enabled = true
+`;
+    const result = mergeCodexConfigToml(existing, MCP_PAYLOAD);
+    expect(result).toContain(".agents/skills");
+  });
+
+  it("starts over from a config it cannot parse rather than failing the install", () => {
+    expect(mergeCodexConfigToml("not = [valid", '[mcp_servers.ctx]\ncommand = "node"\n')).toBe(
+      'project_doc_max_bytes = 262144\n\n[mcp_servers.ctx]\ncommand = "node"\n\n[features]\nhooks = true\n'
+    );
+  });
+
+  it("adds only its defaults when the payload names no mcp server", () => {
+    expect(mergeCodexConfigToml('[mcp_servers.mine]\ncommand = "x"\n', "")).toBe(
+      'project_doc_max_bytes = 262144\n\n[mcp_servers.mine]\ncommand = "x"\n\n[features]\nhooks = true\n'
+    );
+  });
+
+  it("raises project_doc_max_bytes to what the payload asks when that is above the floor", () => {
+    expect(mergeCodexConfigToml("", "project_doc_max_bytes = 500000\n")).toBe(
+      "project_doc_max_bytes = 500000\n\n[features]\nhooks = true\n"
+    );
+  });
+
+  it("leaves a user's project_doc_max_bytes already at the floor untouched, whatever the payload asks", () => {
+    expect(
+      mergeCodexConfigToml("project_doc_max_bytes = 262144\n", "project_doc_max_bytes = 500000\n")
+    ).toBe("project_doc_max_bytes = 262144\n\n[features]\nhooks = true\n");
+  });
+
+  it("keeps a user's own hooks = false rather than turning hooks on", () => {
+    expect(mergeCodexConfigToml("[features]\nhooks = false\n", "")).toBe(
+      "project_doc_max_bytes = 262144\n\n[features]\nhooks = false\n"
+    );
+  });
+
+  it("turns hooks on beside a user's other features, keeping them", () => {
+    expect(mergeCodexConfigToml("[features]\nweb_search = true\n", "")).toBe(
+      "project_doc_max_bytes = 262144\n\n[features]\nweb_search = true\nhooks = true\n"
+    );
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/content.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/content.unit.test.ts
new file mode 100644
index 000000000..581b90f3c
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/content.unit.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { rewriteCodexContent } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("rewriteCodexContent()", () => {
+  it("sends a skill reference to the agents directory Codex scans, under its aidd- prefix", () => {
+    expect(rewriteCodexContent("Read .codex/skills/01-plan/SKILL.md\n")).toBe(
+      "Read .agents/skills/aidd-01-plan/SKILL.md\n"
+    );
+  });
+
+  it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
+    expect(
+      rewriteCodexContent(
+        "Run .codex/commands/04_code/implement.md, then @.codex/commands/02-plan/plan.md.\n"
+      )
+    ).toBe("Run .codex/commands/aidd/04/implement.md, then @.codex/commands/aidd/02/plan.md.\n");
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/hooks.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/hooks.unit.test.ts
new file mode 100644
index 000000000..0fa2c7ea3
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/hooks.unit.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import {
+  codex,
+  mergeCodexHooksJson,
+} from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("codex hooks", () => {
+  describe("capabilities.hooks", () => {
+    it("outputs to .codex/hooks.json", () => {
+      expect(codex.capabilities.hooks.buildOutputPath()).toBe(".codex/hooks.json");
+    });
+
+    it("consumes the codex-hooks config name", () => {
+      expect(codex.capabilities.hooks.consumes).toContain("codex-hooks");
+    });
+
+    it("uses user-prime merge strategy", () => {
+      expect(codex.capabilities.hooks.getMergeStrategy()).toBe("user-prime");
+    });
+
+    it("uses SessionStart as entry section", () => {
+      expect(codex.capabilities.hooks.getEntrySection()).toBe("SessionStart");
+    });
+
+    it("returns null entry section for unknown config names", () => {
+      const cap = [codex.capabilities.mcp, codex.capabilities.hooks].find((c) =>
+        c.consumes.includes("unknown")
+      );
+      expect(cap).toBeUndefined();
+    });
+  });
+});
+
+describe("mergeCodexHooksJson()", () => {
+  const AIDD_ENTRY = {
+    matcher: "startup|resume",
+    hooks: [
+      {
+        type: "command",
+        command: "node .aidd/scripts/update_memory.cjs",
+        statusMessage: "Syncing AIDD memory...",
+        timeout: 30,
+      },
+    ],
+  };
+
+  it("subscribes the memory refresh to a fresh session, on startup and on resume", () => {
+    expect(mergeCodexHooksJson("")).toBe(JSON.stringify({ SessionStart: [AIDD_ENTRY] }, null, 2));
+  });
+
+  it("keeps a user's own hooks and appends the memory refresh after them", () => {
+    const existing = JSON.stringify({
+      PreToolUse: [{ hooks: [{ type: "command", command: "user.sh" }] }],
+      SessionStart: [{ hooks: [{ type: "command", command: "user-start.sh" }] }],
+    });
+
+    expect(mergeCodexHooksJson(existing)).toBe(
+      JSON.stringify(
+        {
+          PreToolUse: [{ hooks: [{ type: "command", command: "user.sh" }] }],
+          SessionStart: [{ hooks: [{ type: "command", command: "user-start.sh" }] }, AIDD_ENTRY],
+        },
+        null,
+        2
+      )
+    );
+  });
+
+  it("adds nothing on a second run over its own output", () => {
+    const once = mergeCodexHooksJson("");
+    expect(mergeCodexHooksJson(once)).toBe(once);
+  });
+
+  it("finds its own hook inside any group of a user's SessionStart, and adds no second one", () => {
+    const existing = JSON.stringify(
+      {
+        SessionStart: [
+          { hooks: [{ type: "command", command: "user-start.sh" }] },
+          { hooks: [{ type: "command", command: "user-two.sh" }, AIDD_ENTRY.hooks[0]] },
+        ],
+      },
+      null,
+      2
+    );
+
+    expect(mergeCodexHooksJson(existing)).toBe(existing);
+  });
+
+  it("starts over from a file it cannot read rather than failing the install", () => {
+    expect(mergeCodexHooksJson("{ not json")).toBe(
+      JSON.stringify({ SessionStart: [AIDD_ENTRY] }, null, 2)
+    );
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/mcp.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/mcp.unit.test.ts
new file mode 100644
index 000000000..91cd8ebe6
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/mcp.unit.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("codex mcp", () => {
+  describe("capabilities.mcp", () => {
+    it("outputs to .codex/config.toml", () => {
+      expect(codex.capabilities.mcp.params.outputPath).toBe(".codex/config.toml");
+    });
+
+    it("consumes the mcp config name", () => {
+      expect(codex.capabilities.mcp.consumes).toContain("mcp");
+    });
+
+    it("uses user-prime merge strategy", () => {
+      expect(codex.capabilities.mcp.params.mergeStrategy ?? "user-prime").toBe("user-prime");
+    });
+
+    it("uses mcp_servers as entry section", () => {
+      expect(codex.capabilities.mcp.params.entrySection).toBe("mcp_servers");
+    });
+
+    it("writes its config in TOML", () => {
+      expect(codex.capabilities.mcp.params.format).toBe("toml");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/plugins.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/plugins.unit.test.ts
new file mode 100644
index 000000000..20de2462b
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/plugins.unit.test.ts
@@ -0,0 +1,62 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("codex plugins", () => {
+  describe("capabilities.plugins", () => {
+    it("declares native codex CLI activation, with the verbs codex uses, and nothing else", () => {
+      const activation = codex.capabilities.plugins.nativeActivation;
+      // Exhaustive, not `toMatchObject`: a field added by mistake must fail here rather than
+      // escape. `pluginCacheDir` is `expect.any(Function)`, since a function matches no literal.
+      expect(activation).toEqual({
+        binary: "codex",
+        upgradeVerb: "upgrade",
+        enableVerb: "add",
+        disableVerb: "remove",
+        pluginCacheDir: expect.any(Function),
+        userSettingsPath: expect.any(Function),
+      });
+    });
+
+    it("declares its own plugin cache root, so clean can purge the empty shell codex leaves behind", () => {
+      const pluginCacheDir = codex.capabilities.plugins.nativeActivation?.pluginCacheDir;
+      expect(pluginCacheDir?.("/home/tester")).toBe(
+        join("/home/tester", ".codex", "plugins", "cache")
+      );
+    });
+
+    describe("nativeActivation.userSettingsPath()", () => {
+      const environment = (vars: Record<string, string>) => (name: string) => vars[name];
+
+      it("falls back to ~/.codex/config.toml when CODEX_HOME is unset", () => {
+        const userSettingsPath = codex.capabilities.plugins.nativeActivation?.userSettingsPath;
+        expect(userSettingsPath?.("/home/tester", environment({}))).toBe(
+          join("/home/tester", ".codex", "config.toml")
+        );
+      });
+
+      it("follows CODEX_HOME when a real machine has it set — the real codex binary reads there, not ~/.codex", () => {
+        const userSettingsPath = codex.capabilities.plugins.nativeActivation?.userSettingsPath;
+        expect(
+          userSettingsPath?.("/home/tester", environment({ CODEX_HOME: "/somewhere/else" }))
+        ).toBe(join("/somewhere/else", "config.toml"));
+      });
+    });
+
+    it("does not write a project-local marketplace settings file", () => {
+      expect(codex.capabilities.plugins.marketplaceSettings).toBeNull();
+    });
+
+    it("keeps the marketplace translation mode", () => {
+      expect(codex.capabilities.plugins.translationMode).toBe("marketplace");
+    });
+
+    it("warns that Codex runs no hook it has not been told to trust, and how to tell it", () => {
+      expect(codex.capabilities.plugins.hooksTrustNotice).toBe(
+        "Codex will not run this plugin's hooks until each one is trusted — approve the prompt " +
+          "once in an interactive session, or pass --dangerously-bypass-hook-trust to codex exec " +
+          "for a headless run. Until then, none of its hooks run and nothing says why."
+      );
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/profile.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/profile.unit.test.ts
new file mode 100644
index 000000000..ca2ddd65f
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/profile.unit.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import { getToolConfig } from "../../../../../../src/contexts/tools/domain/registry.js";
+
+describe("codex profile", () => {
+  it("has toolId codex", () => {
+    expect(codex.toolId).toBe("codex");
+  });
+
+  it("has .codex/ directory", () => {
+    expect(codex.directory).toBe(".codex/");
+  });
+
+  it("has .codex.md tool suffix", () => {
+    expect(codex.toolSuffix).toBe(".codex.md");
+  });
+
+  it("has signalDir pointing at .codex/commands", () => {
+    expect(codex.signalDir).toBe(".codex/commands");
+  });
+
+  it("is registered in the tool registry", () => {
+    const config = getToolConfig("codex");
+    expect(config.toolId).toBe("codex");
+  });
+
+  it("names the one config file Codex reads, and where it goes", () => {
+    expect(codex.configOutputPaths).toStrictEqual({ "config.toml": ".codex/config.toml" });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/rules.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/rules.unit.test.ts
new file mode 100644
index 000000000..6a06a4ab1
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/rules.unit.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+
+describe("codex rules", () => {
+  describe("capabilities.rules.buildInstallPath()", () => {
+    it("builds path for rules under .codex/rules/", () => {
+      const path = codex.capabilities.rules.buildInstallPath("01-standards/naming.md");
+      expect(path).toBe(".codex/rules/01-standards/naming.md");
+    });
+
+    it("strips .codex.md tool suffix from rules path", () => {
+      const path = codex.capabilities.rules.buildInstallPath("01-standards/naming.codex.md");
+      expect(path).toBe(".codex/rules/01-standards/naming.md");
+    });
+  });
+
+  describe("capabilities.rules.convertFrontmatter()", () => {
+    it("passes frontmatter through unchanged", () => {
+      const fm = { paths: ["src/**/*.ts"], description: "TS rules" };
+      const result = codex.capabilities.rules.convertFrontmatter(fm);
+      expect(result).toEqual(fm);
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/skills.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/skills.unit.test.ts
new file mode 100644
index 000000000..36578ea8f
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/codex/skills.unit.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { stripCodexSkillFrontmatter } from "../../../../../../src/contexts/tools/domain/profiles/codex/build.js";
+import { codex } from "../../../../../../src/contexts/tools/domain/profiles/codex/profile.js";
+import { serializeFrontmatter } from "../../../../../../src/kernel/markdown.js";
+
+describe("codex skills", () => {
+  describe("capabilities.skills.buildInstallPath()", () => {
+    it("builds path under .agents/skills/aidd-{name}/SKILL.md", () => {
+      const path = codex.capabilities.skills.buildInstallPath("my-skill/SKILL.md");
+      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
+    });
+
+    it("strips .codex.md tool suffix", () => {
+      const path = codex.capabilities.skills.buildInstallPath("my-skill.codex.md");
+      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
+    });
+
+    it("strips plain .md suffix from skill name", () => {
+      const path = codex.capabilities.skills.buildInstallPath("my-skill.md");
+      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
+    });
+
+    it("keeps a skill name that carries no extension at all", () => {
+      const path = codex.capabilities.skills.buildInstallPath("my-skill");
+      expect(path).toBe(".agents/skills/aidd-my-skill/SKILL.md");
+    });
+
+    it("keeps a skill folder's name whole, even one ending in .md", () => {
+      const path = codex.capabilities.skills.buildInstallPath("notes.md/SKILL.md");
+      expect(path).toBe(".agents/skills/aidd-notes.md/SKILL.md");
+    });
+  });
+});
+
+/**
+ * Codex is the only target that re-serialises skill frontmatter instead of passing the file
+ * through, so these pin the transform itself rather than the golden that recorded its output.
+ */
+describe("a skill's frontmatter, rewritten for Codex", () => {
+  const rebuild = (fm: Record<string, unknown>) =>
+    serializeFrontmatter(stripCodexSkillFrontmatter(fm), "body\n");
+
+  it("keeps the three fields Codex reads", () => {
+    expect(
+      stripCodexSkillFrontmatter({
+        name: "aidd-dev:01:plan",
+        description: "Plan things",
+        allowed_tools: ["Read"],
+      })
+    ).toEqual({ name: "aidd-dev:01:plan", description: "Plan things", allowed_tools: ["Read"] });
+  });
+
+  it("drops the fields it does not, rather than passing them through", () => {
+    // `model` is the one the framework ships and Codex has no use for.
+    expect(stripCodexSkillFrontmatter({ name: "n", description: "d", model: "opus" })).toEqual({
+      name: "n",
+      description: "d",
+    });
+  });
+
+  it("omits a field the source never set", () => {
+    expect(stripCodexSkillFrontmatter({ description: "d" })).toEqual({ description: "d" });
+  });
+
+  it("writes no description key for a skill that has none", () => {
+    expect(stripCodexSkillFrontmatter({ name: "n" })).toStrictEqual({ name: "n" });
+  });
+
+  it("quotes a value whose colon would otherwise make the frontmatter unreadable", () => {
+    // Not cosmetic: a description containing ": " makes `js-yaml` refuse the source with "bad
+    // indentation of a mapping entry". Re-serialising with quotes is what makes it parse.
+    expect(rebuild({ name: "aidd-context:03:context-generate", description: "Do a: thing" })).toBe(
+      "---\nname: 'aidd-context:03:context-generate'\ndescription: 'Do a: thing'\n---\nbody\n"
+    );
+  });
+
+  it("escapes a quote in the value rather than closing the string early", () => {
+    expect(rebuild({ description: "it's here" })).toBe(
+      "---\ndescription: 'it''s here'\n---\nbody\n"
+    );
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
deleted file mode 100644
index 140343374..000000000
--- a/cli/tests/contexts/tools/domain/profiles/copilot.unit.test.ts
+++ /dev/null
@@ -1,566 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { CONFIG_MCP } from "../../../../../src/contexts/tools/domain/capabilities/config-refs.js";
-import { copilot } from "../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
-import { nativeActivationOf } from "../../../../../src/contexts/tools/domain/registry.js";
-
-describe("copilot", () => {
-  describe("capabilities.rules.convertFrontmatter()", () => {
-    it("converts paths: list to applyTo: comma-joined string", () => {
-      const result = copilot.capabilities.rules?.convertFrontmatter({
-        paths: ["src/**/*.ts"],
-      });
-      expect(result).toHaveProperty("applyTo", "src/**/*.ts");
-      expect(result).not.toHaveProperty("paths");
-    });
-
-    it("returns empty frontmatter when paths is empty", () => {
-      const result = copilot.capabilities.rules?.convertFrontmatter({ paths: [] });
-      expect(result).toEqual({});
-    });
-
-    it("returns empty frontmatter when no paths or globs (always apply)", () => {
-      const result = copilot.capabilities.rules?.convertFrontmatter({});
-      expect(result).toEqual({});
-    });
-  });
-
-  describe("capabilities.agents.convertFrontmatter()", () => {
-    it("includes repository instructions in custom subagents by default", () => {
-      expect(copilot.capabilities.agents.convertFrontmatter({ name: "reviewer" })).toHaveProperty(
-        "include-custom-instructions",
-        true
-      );
-    });
-
-    it("preserves an explicit repository-instruction opt-out", () => {
-      expect(
-        copilot.capabilities.agents.convertFrontmatter({
-          name: "reviewer",
-          "include-custom-instructions": false,
-        })
-      ).toHaveProperty("include-custom-instructions", false);
-    });
-
-    it("preserves an explicitly selected agent model", () => {
-      const fm = { name: "alexia", description: "Agent", model: "opus" };
-      const result = copilot.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({
-        name: "alexia",
-        description: "Agent",
-        model: "opus",
-        "include-custom-instructions": true,
-      });
-    });
-
-    it("names an unnamed agent after its own file, whatever folders it sits in", () => {
-      expect(
-        copilot.capabilities.agents.convertFrontmatter(
-          { description: "Reviews code" },
-          "team/reviews/code-reviewer.md"
-        )
-      ).toStrictEqual({
-        name: "code-reviewer",
-        description: "Reviews code",
-        "include-custom-instructions": true,
-      });
-    });
-
-    it("drops only the trailing .md from the file it names an agent after", () => {
-      expect(
-        copilot.capabilities.agents.convertFrontmatter(
-          { description: "Helps" },
-          "notes.md-helper.md"
-        )
-      ).toStrictEqual({
-        name: "notes.md-helper",
-        description: "Helps",
-        "include-custom-instructions": true,
-      });
-    });
-
-    it("leaves an agent unnamed when neither its frontmatter nor a file name gives one", () => {
-      expect(
-        copilot.capabilities.agents.convertFrontmatter({ description: "Helps" })
-      ).toStrictEqual({
-        name: undefined,
-        description: "Helps",
-        "include-custom-instructions": true,
-      });
-    });
-
-    it("drops a name that is not a string rather than writing it", () => {
-      expect(
-        copilot.capabilities.agents.convertFrontmatter({ name: 42, description: "Helps" }, "x.md")
-      ).toStrictEqual({
-        name: undefined,
-        description: "Helps",
-        "include-custom-instructions": true,
-      });
-    });
-  });
-
-  describe("capabilities.mcp", () => {
-    it("maps mcp to .vscode/mcp.json", () => {
-      expect(copilot.capabilities.mcp.params.outputPath).toBe(".vscode/mcp.json");
-    });
-
-    it("consumes the mcp config name", () => {
-      expect(copilot.capabilities.mcp.consumes).toContain("mcp");
-    });
-  });
-
-  describe("capabilities.mcp.params.transformContent()", () => {
-    const transform = (content: string): string | undefined =>
-      copilot.capabilities.mcp.params.transformContent?.(content);
-
-    it("renames mcpServers to the servers key VS Code reads, keeping every other key", () => {
-      const content = JSON.stringify({ mcpServers: { ctx: { command: "node" } }, inputs: [] });
-      expect(transform(content)).toBe(
-        JSON.stringify({ inputs: [], servers: { ctx: { command: "node" } } }, null, 2)
-      );
-    });
-
-    it("returns a config already keyed by servers byte for byte", () => {
-      const content = JSON.stringify({ servers: { ctx: { command: "node" } } });
-      expect(transform(content)).toBe(content);
-    });
-
-    it("renames nothing when a config carries both keys, rather than overwriting servers", () => {
-      const content = JSON.stringify({ servers: { a: {} }, mcpServers: { b: {} } });
-      expect(transform(content)).toBe(content);
-    });
-  });
-
-  describe("capabilities.settings", () => {
-    const settings = Array.isArray(copilot.capabilities.settings)
-      ? copilot.capabilities.settings[0]
-      : copilot.capabilities.settings;
-
-    it("writes to .vscode/settings.json", () => {
-      expect(settings.params.outputPath).toBe(".vscode/settings.json");
-    });
-
-    it("uses framework-prime merge strategy", () => {
-      expect(settings.getMergeStrategy()).toBe("framework-prime");
-    });
-
-    it("references vscode-settings.json asset file (not hardcoded staticContent)", () => {
-      expect(settings.staticContentAssetFile).toBe("vscode-settings.json");
-      expect(settings.staticContent).toBeUndefined();
-    });
-
-    it("does not consume framework signals (content is CLI-owned)", () => {
-      expect(settings.consumes).toHaveLength(0);
-    });
-
-    it("declares requiresTool: vscode (gate merge to IDE-present context)", () => {
-      expect(settings.requiresTool).toBe("vscode");
-    });
-  });
-
-  describe("capabilities.commands.buildInstallPath()", () => {
-    it("flattens commands: prefixes with phase number", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("04_code/implement.md");
-      expect(path).toBe(".github/prompts/04-implement.prompt.md");
-    });
-
-    it("flattens commands: converts underscores to hyphens in filename", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("00_behavior/auto_accept.md");
-      expect(path).toBe(".github/prompts/00-auto-accept.prompt.md");
-    });
-
-    it("handles top-level commands file without subdirectory", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("commit.md");
-      expect(path).toBe(".github/prompts/commit.prompt.md");
-    });
-
-    it("prefixes a command nested two folders deep with both folders' phase numbers", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("01_plan/02_steps/review.md");
-      expect(path).toBe(".github/prompts/01-02-review.prompt.md");
-    });
-
-    it("keeps a folder name whole when it does not start with a phase number", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("v2-tools/x.md");
-      expect(path).toBe(".github/prompts/v2-tools-x.prompt.md");
-    });
-
-    it("does not add the prompt extension twice to a file that already carries it", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("review.prompt.md");
-      expect(path).toBe(".github/prompts/review.prompt.md");
-    });
-
-    it("adds the prompt extension to a file that carries no extension at all", () => {
-      const path = copilot.capabilities.commands?.buildInstallPath("commit");
-      expect(path).toBe(".github/prompts/commit.prompt.md");
-    });
-  });
-
-  describe("capabilities.rules.buildInstallPath()", () => {
-    it("flattens rules: prefixes with category number, strips file numeric prefix", () => {
-      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/1-mermaid.md");
-      expect(path).toBe(".github/instructions/01-mermaid.instructions.md");
-    });
-
-    it("flattens rules: no numeric prefix in filename — unchanged", () => {
-      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/naming.md");
-      expect(path).toBe(".github/instructions/01-naming.instructions.md");
-    });
-
-    it("strips a numeric prefix of several digits from a rule's file name", () => {
-      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/10-mermaid.md");
-      expect(path).toBe(".github/instructions/01-mermaid.instructions.md");
-    });
-
-    it("keeps a number inside a rule's file name, stripping only a leading one", () => {
-      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/naming-2-rules.md");
-      expect(path).toBe(".github/instructions/01-naming-2-rules.instructions.md");
-    });
-
-    it("flattens rules: strips .copilot tool suffix from filename", () => {
-      const path = copilot.capabilities.rules?.buildInstallPath(
-        "04-tooling/ide-mapping.copilot.md"
-      );
-      expect(path).toBe(".github/instructions/04-ide-mapping.instructions.md");
-    });
-
-    it("returns null for .gitkeep files", () => {
-      expect(copilot.capabilities.rules?.buildInstallPath("00-architecture/.gitkeep")).toBeNull();
-    });
-  });
-
-  describe("capabilities.agents.buildInstallPath()", () => {
-    it("adds .agent.md extension", () => {
-      const path = copilot.capabilities.agents.buildInstallPath("code-reviewer.md");
-      expect(path).toBe(".github/agents/code-reviewer.agent.md");
-    });
-
-    it("returns null for .gitkeep files", () => {
-      expect(copilot.capabilities.agents.buildInstallPath(".gitkeep")).toBeNull();
-    });
-
-    it("names a nested agent after its own file, not the folders above it", () => {
-      const path = copilot.capabilities.agents.buildInstallPath("team/sub/code-reviewer.md");
-      expect(path).toBe(".github/agents/code-reviewer.agent.md");
-    });
-
-    it("keeps a file that is not markdown under its own name", () => {
-      const path = copilot.capabilities.agents.buildInstallPath("helper.txt");
-      expect(path).toBe(".github/agents/helper.txt");
-    });
-  });
-
-  describe("capabilities.skills.buildInstallPath()", () => {
-    it("preserves directory structure without flattening", () => {
-      const path = copilot.capabilities.skills.buildInstallPath("commit/SKILL.md");
-      expect(path).toBe(".github/skills/commit/SKILL.md");
-    });
-  });
-
-  describe("capabilities.rules.convertFrontmatter() — alwaysApply", () => {
-    it("returns empty frontmatter when alwaysApply is false without patterns and no description", () => {
-      expect(copilot.capabilities.rules?.convertFrontmatter({ alwaysApply: false })).toEqual({});
-    });
-
-    it("keeps description when alwaysApply is false and no patterns are specified", () => {
-      expect(
-        copilot.capabilities.rules?.convertFrontmatter({
-          description: "Apply when editing command files.",
-          alwaysApply: false,
-        })
-      ).toEqual({ description: "Apply when editing command files." });
-    });
-
-    it("joins several path patterns into one comma-separated applyTo", () => {
-      expect(
-        copilot.capabilities.rules?.convertFrontmatter({ paths: ["src/**/*.ts", "tests/**/*.ts"] })
-      ).toStrictEqual({ applyTo: "src/**/*.ts,tests/**/*.ts" });
-    });
-
-    it("writes no description key when alwaysApply is false and there is no description", () => {
-      expect(copilot.capabilities.rules?.convertFrontmatter({ alwaysApply: false })).toStrictEqual(
-        {}
-      );
-    });
-
-    it("drops the description of a rule that always applies", () => {
-      expect(
-        copilot.capabilities.rules?.convertFrontmatter({ description: "Always on." })
-      ).toStrictEqual({});
-    });
-
-    it("converts globs + alwaysApply: false from framework to applyTo", () => {
-      expect(
-        copilot.capabilities.rules?.convertFrontmatter({
-          globs: ["{{TOOLS}}/rules/**/*.md"],
-          alwaysApply: false,
-        })
-      ).toEqual({ applyTo: "{{TOOLS}}/rules/**/*.md" });
-    });
-  });
-
-  describe("capabilities.plugins", () => {
-    it("has a plugins capability", () => {
-      expect("plugins" in copilot.capabilities).toBe(true);
-    });
-
-    it("is native mode", () => {
-      expect(copilot.capabilities.plugins.mode).toBe("native");
-    });
-
-    it("uses .github/plugins/ as plugins directory", () => {
-      expect(copilot.capabilities.plugins.pluginsDir).toBe(".github/plugins/");
-    });
-
-    it("uses plugin.json as plugin manifest path", () => {
-      expect(copilot.capabilities.plugins.pluginManifestRelativePath).toBe("plugin.json");
-    });
-
-    it("pluginOutputDir returns correct path for a plugin name", () => {
-      expect(copilot.capabilities.plugins.pluginOutputDir("my-plugin")).toBe(
-        ".github/plugins/my-plugin/"
-      );
-    });
-  });
-
-  describe("capabilities.plugins.marketplaceSettings", () => {
-    const ms = copilot.capabilities.plugins.marketplaceSettings;
-
-    it("has marketplaceSettings configured", () => {
-      expect(ms).not.toBeNull();
-    });
-
-    it("writes to .github/copilot/settings.json", () => {
-      expect(ms?.settingsPath).toBe(".github/copilot/settings.json");
-    });
-
-    it("uses extraKnownMarketplaces as settings key", () => {
-      expect(ms?.settingsKey).toBe("extraKnownMarketplaces");
-    });
-
-    it("uses enabledPlugins as enabled plugins key", () => {
-      expect(ms?.enabledPluginsKey).toBe("enabledPlugins");
-    });
-
-    describe("the key a marketplace is recorded under", () => {
-      it("keys a github marketplace by its name", () => {
-        expect(
-          ms?.toEntryKey({
-            name: "aidd-framework",
-            source: { kind: "github", repo: "ai-driven-dev/framework" },
-          })
-        ).toBe("aidd-framework");
-      });
-
-      it("keys a local marketplace by its name too — the source decides only whether there is a key", () => {
-        expect(
-          ms?.toEntryKey({ name: "my-marketplace", source: { kind: "local", path: "/dev/aidd" } })
-        ).toBe("my-marketplace");
-      });
-
-      it("returns null for unsupported source kind (npm)", () => {
-        const result = ms?.toEntryKey({
-          name: "my-plugin",
-          source: { kind: "npm", package: "my-plugin" },
-        });
-        expect(result).toBeNull();
-      });
-
-      it("returns null for unsupported source kind (url)", () => {
-        const result = ms?.toEntryKey({
-          name: "my-plugin",
-          source: { kind: "url", url: "https://example.com/plugin.zip" },
-        });
-        expect(result).toBeNull();
-      });
-    });
-  });
-});
-
-/** What a reference to another framework file becomes once installed for Copilot. No other gate
- * sees it: `translate` never calls `rewriteContent`, and the byte-frozen golden cell is claude,
- * whose rewrite is the identity. The whole rewritten string is asserted, never a fragment. */
-describe("a reference to another framework file, installed for Copilot", () => {
-  const rewrite = (content: string) => copilot.rewriteContent(content);
-
-  describe("an @-reference, which becomes a link", () => {
-    it("points an agent reference at the installed .agent.md file", () => {
-      expect(rewrite("See @{{TOOLS}}/agents/executor.md for details")).toBe(
-        "See [.github/agents/executor.agent.md](../../.github/agents/executor.agent.md) for details"
-      );
-    });
-
-    it("points a command reference at the flattened prompt file", () => {
-      expect(rewrite("Run @{{TOOLS}}/commands/01-plan/02_step.md now")).toBe(
-        "Run [.github/prompts/01-02-step.prompt.md](../../.github/prompts/01-02-step.prompt.md) now"
-      );
-    });
-
-    it("points a rule reference at the instructions file, numeric prefix stripped", () => {
-      expect(rewrite("Read @{{TOOLS}}/rules/1-style.md")).toBe(
-        "Read [.github/instructions/style.instructions.md](../../.github/instructions/style.instructions.md)"
-      );
-    });
-
-    it("keeps a skill reference's directory structure, which Copilot does not flatten", () => {
-      expect(rewrite("Read @{{TOOLS}}/skills/01-plan/SKILL.md")).toBe(
-        "Read [.github/skills/01-plan/SKILL.md](../../.github/skills/01-plan/SKILL.md)"
-      );
-    });
-
-    it("points a docs reference into the project's docs directory", () => {
-      expect(rewrite("Read @{{DOCS}}/memory/testing.md")).toBe(
-        "Read [aidd_docs/memory/testing.md](../../aidd_docs/memory/testing.md)"
-      );
-    });
-
-    it("gives a section nobody declared a prefixed path rather than dropping the link", () => {
-      expect(rewrite("Unknown @{{TOOLS}}/hooks/thing.js")).toBe(
-        "Unknown [.github/hooks/thing.js](../../.github/hooks/thing.js)"
-      );
-    });
-
-    it("resolves a reference to a section directory to that directory", () => {
-      expect(rewrite("Everything under @{{TOOLS}}/agents/ applies")).toBe(
-        "Everything under [.github/agents/](../../.github/agents/) applies"
-      );
-    });
-
-    it("resolves every other section's directory reference to its installed directory", () => {
-      expect(rewrite("@{{TOOLS}}/commands/ @{{TOOLS}}/rules/ @{{TOOLS}}/skills/")).toBe(
-        "[.github/prompts/](../../.github/prompts/) " +
-          "[.github/instructions/](../../.github/instructions/) " +
-          "[.github/skills/](../../.github/skills/)"
-      );
-    });
-
-    it("keeps a nested directory reference's folder rather than flattening it", () => {
-      expect(
-        rewrite(
-          "@{{TOOLS}}/agents/team/ @{{TOOLS}}/commands/01-plan/ @{{TOOLS}}/rules/01-standards/"
-        )
-      ).toBe(
-        "[.github/agents/team/](../../.github/agents/team/) " +
-          "[.github/prompts/01-plan/](../../.github/prompts/01-plan/) " +
-          "[.github/instructions/01-standards/](../../.github/instructions/01-standards/)"
-      );
-    });
-
-    it("keeps a reference to a section's .gitkeep under its own section path", () => {
-      expect(
-        rewrite(
-          "@{{TOOLS}}/agents/.gitkeep @{{TOOLS}}/commands/.gitkeep @{{TOOLS}}/rules/.gitkeep @{{TOOLS}}/skills/.gitkeep"
-        )
-      ).toBe(
-        "[.github/agents/.gitkeep](../../.github/agents/.gitkeep) " +
-          "[.github/commands/.gitkeep](../../.github/commands/.gitkeep) " +
-          "[.github/rules/.gitkeep](../../.github/rules/.gitkeep) " +
-          "[.github/skills/.gitkeep](../../.github/skills/.gitkeep)"
-      );
-    });
-
-    it("rewrites every reference in the content, not only the first", () => {
-      expect(
-        rewrite("@{{TOOLS}}/agents/a.md @{{TOOLS}}/agents/b.md @{{DOCS}}/a.md @{{DOCS}}/b.md")
-      ).toBe(
-        "[.github/agents/a.agent.md](../../.github/agents/a.agent.md) " +
-          "[.github/agents/b.agent.md](../../.github/agents/b.agent.md) " +
-          "[aidd_docs/a.md](../../aidd_docs/a.md) " +
-          "[aidd_docs/b.md](../../aidd_docs/b.md)"
-      );
-    });
-
-    it("leaves alone a placeholder that only resembles {{TOOLS}}", () => {
-      expect(rewrite("See @{{TOOLX}}/agents/x.md")).toBe("See @{{TOOLX}}/agents/x.md");
-    });
-  });
-
-  describe("a plain path reference, which stays plain text", () => {
-    // Frontmatter cannot hold a markdown link, so the form without the @ replaces the
-    // directory prefix and nothing else.
-    it("replaces the agents prefix and leaves the filename alone", () => {
-      expect(rewrite("Path: {{TOOLS}}/agents/executor.md")).toBe(
-        "Path: .github/agents/executor.md"
-      );
-    });
-
-    it("flattens a command path, because the installed file is flattened", () => {
-      expect(rewrite("Path: {{TOOLS}}/commands/01-plan/02_step.md")).toBe(
-        "Path: .github/prompts/01-02-step.prompt.md"
-      );
-    });
-
-    it("replaces the rules and skills prefixes in one pass", () => {
-      expect(rewrite("At {{TOOLS}}/rules/1-style.md and {{TOOLS}}/skills/x/SKILL.md")).toBe(
-        "At .github/instructions/1-style.md and .github/skills/x/SKILL.md"
-      );
-    });
-
-    it("replaces a bare tools or docs prefix for a section it does not know", () => {
-      expect(rewrite("Bare {{TOOLS}}/other/thing.md and {{DOCS}}/x.md")).toBe(
-        "Bare .github/other/thing.md and aidd_docs/x.md"
-      );
-    });
-
-    it("resolves the plugins path a pinned release still ships", () => {
-      // A real placeholder-carrying line, from framework-real's 00-sdlc skill.
-      expect(rewrite("validator: `{{TOOLS}}/plugins/aidd-pm/skills/05-spec/x.yml`")).toBe(
-        "validator: `.github/plugins/aidd-pm/skills/05-spec/x.yml`"
-      );
-    });
-  });
-
-  describe("content with nothing to rewrite", () => {
-    it("is returned unchanged", () => {
-      const content = "# A heading\n\nProse with a [link](https://example.com) and `code`.\n";
-      expect(rewrite(content)).toBe(content);
-    });
-  });
-
-  describe("capabilities.plugins", () => {
-    it("declares where copilot's own user-scope settings file lives, for --scope user", () => {
-      const activation = copilot.capabilities.plugins.nativeActivation;
-      expect(activation?.userSettingsPath?.("/home/tester", () => undefined)).toBe(
-        join("/home/tester", ".copilot", "settings.json")
-      );
-    });
-  });
-});
-
-describe("copilot declarations the rest of the CLI reads", () => {
-  it("probes a plugin manifest in the three places Copilot reads one, in its order", () => {
-    expect(copilot.distributionProbes?.manifest).toStrictEqual([
-      ".plugin/plugin.json",
-      ".github/plugin/plugin.json",
-      "plugin.json",
-    ]);
-  });
-
-  it("writes agents as markdown", () => {
-    expect(copilot.capabilities.agents.params.format).toBe("markdown");
-  });
-
-  it("writes its MCP servers as JSON under `servers`", () => {
-    expect(copilot.capabilities.mcp.params).toMatchObject({
-      format: "json",
-      entrySection: "servers",
-    });
-    expect(copilot.capabilities.mcp.consumes).toStrictEqual([CONFIG_MCP]);
-  });
-
-  it("translates plugins for its own marketplace", () => {
-    expect(copilot.capabilities.plugins.translationMode).toBe("marketplace");
-  });
-
-  it("drives its own CLI with the verbs it answers to", () => {
-    expect(nativeActivationOf("copilot")).toMatchObject({
-      binary: "copilot",
-      upgradeVerb: "update",
-      updateVerb: "update",
-      enableVerb: "install",
-      disableVerb: "uninstall",
-      sourceCheckVerb: "update",
-      forceRemoveArgs: ["--force"],
-    });
-  });
-});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts
new file mode 100644
index 000000000..1a81ed4f2
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot agents", () => {
+  describe("capabilities.agents.convertFrontmatter()", () => {
+    it("includes repository instructions in custom subagents by default", () => {
+      expect(copilot.capabilities.agents.convertFrontmatter({ name: "reviewer" })).toHaveProperty(
+        "include-custom-instructions",
+        true
+      );
+    });
+
+    it("preserves an explicit repository-instruction opt-out", () => {
+      expect(
+        copilot.capabilities.agents.convertFrontmatter({
+          name: "reviewer",
+          "include-custom-instructions": false,
+        })
+      ).toHaveProperty("include-custom-instructions", false);
+    });
+
+    it("preserves an explicitly selected agent model", () => {
+      const fm = { name: "alexia", description: "Agent", model: "opus" };
+      const result = copilot.capabilities.agents.convertFrontmatter(fm);
+      expect(result).toEqual({
+        name: "alexia",
+        description: "Agent",
+        model: "opus",
+        "include-custom-instructions": true,
+      });
+    });
+
+    it("names an unnamed agent after its own file, whatever folders it sits in", () => {
+      expect(
+        copilot.capabilities.agents.convertFrontmatter(
+          { description: "Reviews code" },
+          "team/reviews/code-reviewer.md"
+        )
+      ).toStrictEqual({
+        name: "code-reviewer",
+        description: "Reviews code",
+        "include-custom-instructions": true,
+      });
+    });
+
+    it("drops only the trailing .md from the file it names an agent after", () => {
+      expect(
+        copilot.capabilities.agents.convertFrontmatter(
+          { description: "Helps" },
+          "notes.md-helper.md"
+        )
+      ).toStrictEqual({
+        name: "notes.md-helper",
+        description: "Helps",
+        "include-custom-instructions": true,
+      });
+    });
+
+    it("leaves an agent unnamed when neither its frontmatter nor a file name gives one", () => {
+      expect(
+        copilot.capabilities.agents.convertFrontmatter({ description: "Helps" })
+      ).toStrictEqual({
+        name: undefined,
+        description: "Helps",
+        "include-custom-instructions": true,
+      });
+    });
+
+    it("drops a name that is not a string rather than writing it", () => {
+      expect(
+        copilot.capabilities.agents.convertFrontmatter({ name: 42, description: "Helps" }, "x.md")
+      ).toStrictEqual({
+        name: undefined,
+        description: "Helps",
+        "include-custom-instructions": true,
+      });
+    });
+  });
+
+  describe("capabilities.agents.buildInstallPath()", () => {
+    it("adds .agent.md extension", () => {
+      const path = copilot.capabilities.agents.buildInstallPath("code-reviewer.md");
+      expect(path).toBe(".github/agents/code-reviewer.agent.md");
+    });
+
+    it("returns null for .gitkeep files", () => {
+      expect(copilot.capabilities.agents.buildInstallPath(".gitkeep")).toBeNull();
+    });
+
+    it("names a nested agent after its own file, not the folders above it", () => {
+      const path = copilot.capabilities.agents.buildInstallPath("team/sub/code-reviewer.md");
+      expect(path).toBe(".github/agents/code-reviewer.agent.md");
+    });
+
+    it("keeps a file that is not markdown under its own name", () => {
+      const path = copilot.capabilities.agents.buildInstallPath("helper.txt");
+      expect(path).toBe(".github/agents/helper.txt");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/commands.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/commands.unit.test.ts
new file mode 100644
index 000000000..d91dc0f23
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/commands.unit.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot commands", () => {
+  describe("capabilities.commands.buildInstallPath()", () => {
+    it("flattens commands: prefixes with phase number", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("04_code/implement.md");
+      expect(path).toBe(".github/prompts/04-implement.prompt.md");
+    });
+
+    it("flattens commands: converts underscores to hyphens in filename", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("00_behavior/auto_accept.md");
+      expect(path).toBe(".github/prompts/00-auto-accept.prompt.md");
+    });
+
+    it("handles top-level commands file without subdirectory", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("commit.md");
+      expect(path).toBe(".github/prompts/commit.prompt.md");
+    });
+
+    it("prefixes a command nested two folders deep with both folders' phase numbers", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("01_plan/02_steps/review.md");
+      expect(path).toBe(".github/prompts/01-02-review.prompt.md");
+    });
+
+    it("keeps a folder name whole when it does not start with a phase number", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("v2-tools/x.md");
+      expect(path).toBe(".github/prompts/v2-tools-x.prompt.md");
+    });
+
+    it("does not add the prompt extension twice to a file that already carries it", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("review.prompt.md");
+      expect(path).toBe(".github/prompts/review.prompt.md");
+    });
+
+    it("adds the prompt extension to a file that carries no extension at all", () => {
+      const path = copilot.capabilities.commands?.buildInstallPath("commit");
+      expect(path).toBe(".github/prompts/commit.prompt.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/content.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/content.unit.test.ts
new file mode 100644
index 000000000..a842e16bf
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/content.unit.test.ts
@@ -0,0 +1,153 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+/** What a reference to another framework file becomes once installed for Copilot. No other gate
+ * sees it: `translate` never calls `rewriteContent`, and the byte-frozen golden cell is claude,
+ * whose rewrite is the identity. The whole rewritten string is asserted, never a fragment. */
+describe("a reference to another framework file, installed for Copilot", () => {
+  const rewrite = (content: string) => copilot.rewriteContent(content);
+
+  describe("an @-reference, which becomes a link", () => {
+    it("points an agent reference at the installed .agent.md file", () => {
+      expect(rewrite("See @{{TOOLS}}/agents/executor.md for details")).toBe(
+        "See [.github/agents/executor.agent.md](../../.github/agents/executor.agent.md) for details"
+      );
+    });
+
+    it("points a command reference at the flattened prompt file", () => {
+      expect(rewrite("Run @{{TOOLS}}/commands/01-plan/02_step.md now")).toBe(
+        "Run [.github/prompts/01-02-step.prompt.md](../../.github/prompts/01-02-step.prompt.md) now"
+      );
+    });
+
+    it("points a rule reference at the instructions file, numeric prefix stripped", () => {
+      expect(rewrite("Read @{{TOOLS}}/rules/1-style.md")).toBe(
+        "Read [.github/instructions/style.instructions.md](../../.github/instructions/style.instructions.md)"
+      );
+    });
+
+    it("keeps a skill reference's directory structure, which Copilot does not flatten", () => {
+      expect(rewrite("Read @{{TOOLS}}/skills/01-plan/SKILL.md")).toBe(
+        "Read [.github/skills/01-plan/SKILL.md](../../.github/skills/01-plan/SKILL.md)"
+      );
+    });
+
+    it("points a docs reference into the project's docs directory", () => {
+      expect(rewrite("Read @{{DOCS}}/memory/testing.md")).toBe(
+        "Read [aidd_docs/memory/testing.md](../../aidd_docs/memory/testing.md)"
+      );
+    });
+
+    it("gives a section nobody declared a prefixed path rather than dropping the link", () => {
+      expect(rewrite("Unknown @{{TOOLS}}/hooks/thing.js")).toBe(
+        "Unknown [.github/hooks/thing.js](../../.github/hooks/thing.js)"
+      );
+    });
+
+    it("resolves a reference to a section directory to that directory", () => {
+      expect(rewrite("Everything under @{{TOOLS}}/agents/ applies")).toBe(
+        "Everything under [.github/agents/](../../.github/agents/) applies"
+      );
+    });
+
+    it("resolves every other section's directory reference to its installed directory", () => {
+      expect(rewrite("@{{TOOLS}}/commands/ @{{TOOLS}}/rules/ @{{TOOLS}}/skills/")).toBe(
+        "[.github/prompts/](../../.github/prompts/) " +
+          "[.github/instructions/](../../.github/instructions/) " +
+          "[.github/skills/](../../.github/skills/)"
+      );
+    });
+
+    it("keeps a nested directory reference's folder rather than flattening it", () => {
+      expect(
+        rewrite(
+          "@{{TOOLS}}/agents/team/ @{{TOOLS}}/commands/01-plan/ @{{TOOLS}}/rules/01-standards/"
+        )
+      ).toBe(
+        "[.github/agents/team/](../../.github/agents/team/) " +
+          "[.github/prompts/01-plan/](../../.github/prompts/01-plan/) " +
+          "[.github/instructions/01-standards/](../../.github/instructions/01-standards/)"
+      );
+    });
+
+    it("keeps a reference to a section's .gitkeep under its own section path", () => {
+      expect(
+        rewrite(
+          "@{{TOOLS}}/agents/.gitkeep @{{TOOLS}}/commands/.gitkeep @{{TOOLS}}/rules/.gitkeep @{{TOOLS}}/skills/.gitkeep"
+        )
+      ).toBe(
+        "[.github/agents/.gitkeep](../../.github/agents/.gitkeep) " +
+          "[.github/commands/.gitkeep](../../.github/commands/.gitkeep) " +
+          "[.github/rules/.gitkeep](../../.github/rules/.gitkeep) " +
+          "[.github/skills/.gitkeep](../../.github/skills/.gitkeep)"
+      );
+    });
+
+    it("rewrites every reference in the content, not only the first", () => {
+      expect(
+        rewrite("@{{TOOLS}}/agents/a.md @{{TOOLS}}/agents/b.md @{{DOCS}}/a.md @{{DOCS}}/b.md")
+      ).toBe(
+        "[.github/agents/a.agent.md](../../.github/agents/a.agent.md) " +
+          "[.github/agents/b.agent.md](../../.github/agents/b.agent.md) " +
+          "[aidd_docs/a.md](../../aidd_docs/a.md) " +
+          "[aidd_docs/b.md](../../aidd_docs/b.md)"
+      );
+    });
+
+    it("leaves alone a placeholder that only resembles {{TOOLS}}", () => {
+      expect(rewrite("See @{{TOOLX}}/agents/x.md")).toBe("See @{{TOOLX}}/agents/x.md");
+    });
+  });
+
+  describe("a plain path reference, which stays plain text", () => {
+    // Frontmatter cannot hold a markdown link, so the form without the @ replaces the
+    // directory prefix and nothing else.
+    it("replaces the agents prefix and leaves the filename alone", () => {
+      expect(rewrite("Path: {{TOOLS}}/agents/executor.md")).toBe(
+        "Path: .github/agents/executor.md"
+      );
+    });
+
+    it("flattens a command path, because the installed file is flattened", () => {
+      expect(rewrite("Path: {{TOOLS}}/commands/01-plan/02_step.md")).toBe(
+        "Path: .github/prompts/01-02-step.prompt.md"
+      );
+    });
+
+    it("replaces the rules and skills prefixes in one pass", () => {
+      expect(rewrite("At {{TOOLS}}/rules/1-style.md and {{TOOLS}}/skills/x/SKILL.md")).toBe(
+        "At .github/instructions/1-style.md and .github/skills/x/SKILL.md"
+      );
+    });
+
+    it("replaces a bare tools or docs prefix for a section it does not know", () => {
+      expect(rewrite("Bare {{TOOLS}}/other/thing.md and {{DOCS}}/x.md")).toBe(
+        "Bare .github/other/thing.md and aidd_docs/x.md"
+      );
+    });
+
+    it("resolves the plugins path a pinned release still ships", () => {
+      // A real placeholder-carrying line, from framework-real's 00-sdlc skill.
+      expect(rewrite("validator: `{{TOOLS}}/plugins/aidd-pm/skills/05-spec/x.yml`")).toBe(
+        "validator: `.github/plugins/aidd-pm/skills/05-spec/x.yml`"
+      );
+    });
+  });
+
+  describe("content with nothing to rewrite", () => {
+    it("is returned unchanged", () => {
+      const content = "# A heading\n\nProse with a [link](https://example.com) and `code`.\n";
+      expect(rewrite(content)).toBe(content);
+    });
+  });
+
+  describe("capabilities.plugins", () => {
+    it("declares where copilot's own user-scope settings file lives, for --scope user", () => {
+      const activation = copilot.capabilities.plugins.nativeActivation;
+      expect(activation?.userSettingsPath?.("/home/tester", () => undefined)).toBe(
+        join("/home/tester", ".copilot", "settings.json")
+      );
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/mcp.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/mcp.unit.test.ts
new file mode 100644
index 000000000..20275eab6
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/mcp.unit.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot mcp", () => {
+  describe("capabilities.mcp", () => {
+    it("maps mcp to .vscode/mcp.json", () => {
+      expect(copilot.capabilities.mcp.params.outputPath).toBe(".vscode/mcp.json");
+    });
+
+    it("consumes the mcp config name", () => {
+      expect(copilot.capabilities.mcp.consumes).toContain("mcp");
+    });
+  });
+
+  describe("capabilities.mcp.params.transformContent()", () => {
+    const transform = (content: string): string | undefined =>
+      copilot.capabilities.mcp.params.transformContent?.(content);
+
+    it("renames mcpServers to the servers key VS Code reads, keeping every other key", () => {
+      const content = JSON.stringify({ mcpServers: { ctx: { command: "node" } }, inputs: [] });
+      expect(transform(content)).toBe(
+        JSON.stringify({ inputs: [], servers: { ctx: { command: "node" } } }, null, 2)
+      );
+    });
+
+    it("returns a config already keyed by servers byte for byte", () => {
+      const content = JSON.stringify({ servers: { ctx: { command: "node" } } });
+      expect(transform(content)).toBe(content);
+    });
+
+    it("renames nothing when a config carries both keys, rather than overwriting servers", () => {
+      const content = JSON.stringify({ servers: { a: {} }, mcpServers: { b: {} } });
+      expect(transform(content)).toBe(content);
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/plugins.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/plugins.unit.test.ts
new file mode 100644
index 000000000..a1e48f0e4
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/plugins.unit.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot plugins", () => {
+  describe("capabilities.plugins", () => {
+    it("has a plugins capability", () => {
+      expect("plugins" in copilot.capabilities).toBe(true);
+    });
+
+    it("is native mode", () => {
+      expect(copilot.capabilities.plugins.mode).toBe("native");
+    });
+
+    it("uses .github/plugins/ as plugins directory", () => {
+      expect(copilot.capabilities.plugins.pluginsDir).toBe(".github/plugins/");
+    });
+
+    it("uses plugin.json as plugin manifest path", () => {
+      expect(copilot.capabilities.plugins.pluginManifestRelativePath).toBe("plugin.json");
+    });
+
+    it("pluginOutputDir returns correct path for a plugin name", () => {
+      expect(copilot.capabilities.plugins.pluginOutputDir("my-plugin")).toBe(
+        ".github/plugins/my-plugin/"
+      );
+    });
+  });
+
+  describe("capabilities.plugins.marketplaceSettings", () => {
+    const ms = copilot.capabilities.plugins.marketplaceSettings;
+
+    it("has marketplaceSettings configured", () => {
+      expect(ms).not.toBeNull();
+    });
+
+    it("writes to .github/copilot/settings.json", () => {
+      expect(ms?.settingsPath).toBe(".github/copilot/settings.json");
+    });
+
+    it("uses extraKnownMarketplaces as settings key", () => {
+      expect(ms?.settingsKey).toBe("extraKnownMarketplaces");
+    });
+
+    it("uses enabledPlugins as enabled plugins key", () => {
+      expect(ms?.enabledPluginsKey).toBe("enabledPlugins");
+    });
+
+    describe("the key a marketplace is recorded under", () => {
+      it("keys a github marketplace by its name", () => {
+        expect(
+          ms?.toEntryKey({
+            name: "aidd-framework",
+            source: { kind: "github", repo: "ai-driven-dev/framework" },
+          })
+        ).toBe("aidd-framework");
+      });
+
+      it("keys a local marketplace by its name too — the source decides only whether there is a key", () => {
+        expect(
+          ms?.toEntryKey({ name: "my-marketplace", source: { kind: "local", path: "/dev/aidd" } })
+        ).toBe("my-marketplace");
+      });
+
+      it("returns null for unsupported source kind (npm)", () => {
+        const result = ms?.toEntryKey({
+          name: "my-plugin",
+          source: { kind: "npm", package: "my-plugin" },
+        });
+        expect(result).toBeNull();
+      });
+
+      it("returns null for unsupported source kind (url)", () => {
+        const result = ms?.toEntryKey({
+          name: "my-plugin",
+          source: { kind: "url", url: "https://example.com/plugin.zip" },
+        });
+        expect(result).toBeNull();
+      });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/profile.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/profile.unit.test.ts
new file mode 100644
index 000000000..9d042e232
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/profile.unit.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { CONFIG_MCP } from "../../../../../../src/contexts/tools/domain/capabilities/config-refs.js";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+import { nativeActivationOf } from "../../../../../../src/contexts/tools/domain/registry.js";
+
+describe("copilot declarations the rest of the CLI reads", () => {
+  it("probes a plugin manifest in the three places Copilot reads one, in its order", () => {
+    expect(copilot.distributionProbes?.manifest).toStrictEqual([
+      ".plugin/plugin.json",
+      ".github/plugin/plugin.json",
+      "plugin.json",
+    ]);
+  });
+
+  it("writes agents as markdown", () => {
+    expect(copilot.capabilities.agents.params.format).toBe("markdown");
+  });
+
+  it("writes its MCP servers as JSON under `servers`", () => {
+    expect(copilot.capabilities.mcp.params).toMatchObject({
+      format: "json",
+      entrySection: "servers",
+    });
+    expect(copilot.capabilities.mcp.consumes).toStrictEqual([CONFIG_MCP]);
+  });
+
+  it("translates plugins for its own marketplace", () => {
+    expect(copilot.capabilities.plugins.translationMode).toBe("marketplace");
+  });
+
+  it("drives its own CLI with the verbs it answers to", () => {
+    expect(nativeActivationOf("copilot")).toMatchObject({
+      binary: "copilot",
+      upgradeVerb: "update",
+      updateVerb: "update",
+      enableVerb: "install",
+      disableVerb: "uninstall",
+      sourceCheckVerb: "update",
+      forceRemoveArgs: ["--force"],
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/rules.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/rules.unit.test.ts
new file mode 100644
index 000000000..1ea98e1f2
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/rules.unit.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot rules", () => {
+  describe("capabilities.rules.convertFrontmatter()", () => {
+    it("converts paths: list to applyTo: comma-joined string", () => {
+      const result = copilot.capabilities.rules?.convertFrontmatter({
+        paths: ["src/**/*.ts"],
+      });
+      expect(result).toHaveProperty("applyTo", "src/**/*.ts");
+      expect(result).not.toHaveProperty("paths");
+    });
+
+    it("returns empty frontmatter when paths is empty", () => {
+      const result = copilot.capabilities.rules?.convertFrontmatter({ paths: [] });
+      expect(result).toEqual({});
+    });
+
+    it("returns empty frontmatter when no paths or globs (always apply)", () => {
+      const result = copilot.capabilities.rules?.convertFrontmatter({});
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("capabilities.rules.buildInstallPath()", () => {
+    it("flattens rules: prefixes with category number, strips file numeric prefix", () => {
+      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/1-mermaid.md");
+      expect(path).toBe(".github/instructions/01-mermaid.instructions.md");
+    });
+
+    it("flattens rules: no numeric prefix in filename — unchanged", () => {
+      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/naming.md");
+      expect(path).toBe(".github/instructions/01-naming.instructions.md");
+    });
+
+    it("strips a numeric prefix of several digits from a rule's file name", () => {
+      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/10-mermaid.md");
+      expect(path).toBe(".github/instructions/01-mermaid.instructions.md");
+    });
+
+    it("keeps a number inside a rule's file name, stripping only a leading one", () => {
+      const path = copilot.capabilities.rules?.buildInstallPath("01-standards/naming-2-rules.md");
+      expect(path).toBe(".github/instructions/01-naming-2-rules.instructions.md");
+    });
+
+    it("flattens rules: strips .copilot tool suffix from filename", () => {
+      const path = copilot.capabilities.rules?.buildInstallPath(
+        "04-tooling/ide-mapping.copilot.md"
+      );
+      expect(path).toBe(".github/instructions/04-ide-mapping.instructions.md");
+    });
+
+    it("returns null for .gitkeep files", () => {
+      expect(copilot.capabilities.rules?.buildInstallPath("00-architecture/.gitkeep")).toBeNull();
+    });
+  });
+
+  describe("capabilities.rules.convertFrontmatter() — alwaysApply", () => {
+    it("returns empty frontmatter when alwaysApply is false without patterns and no description", () => {
+      expect(copilot.capabilities.rules?.convertFrontmatter({ alwaysApply: false })).toEqual({});
+    });
+
+    it("keeps description when alwaysApply is false and no patterns are specified", () => {
+      expect(
+        copilot.capabilities.rules?.convertFrontmatter({
+          description: "Apply when editing command files.",
+          alwaysApply: false,
+        })
+      ).toEqual({ description: "Apply when editing command files." });
+    });
+
+    it("joins several path patterns into one comma-separated applyTo", () => {
+      expect(
+        copilot.capabilities.rules?.convertFrontmatter({ paths: ["src/**/*.ts", "tests/**/*.ts"] })
+      ).toStrictEqual({ applyTo: "src/**/*.ts,tests/**/*.ts" });
+    });
+
+    it("writes no description key when alwaysApply is false and there is no description", () => {
+      expect(copilot.capabilities.rules?.convertFrontmatter({ alwaysApply: false })).toStrictEqual(
+        {}
+      );
+    });
+
+    it("drops the description of a rule that always applies", () => {
+      expect(
+        copilot.capabilities.rules?.convertFrontmatter({ description: "Always on." })
+      ).toStrictEqual({});
+    });
+
+    it("converts globs + alwaysApply: false from framework to applyTo", () => {
+      expect(
+        copilot.capabilities.rules?.convertFrontmatter({
+          globs: ["{{TOOLS}}/rules/**/*.md"],
+          alwaysApply: false,
+        })
+      ).toEqual({ applyTo: "{{TOOLS}}/rules/**/*.md" });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/settings.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/settings.unit.test.ts
new file mode 100644
index 000000000..4349d6294
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/settings.unit.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot settings", () => {
+  describe("capabilities.settings", () => {
+    const settings = Array.isArray(copilot.capabilities.settings)
+      ? copilot.capabilities.settings[0]
+      : copilot.capabilities.settings;
+
+    it("writes to .vscode/settings.json", () => {
+      expect(settings.params.outputPath).toBe(".vscode/settings.json");
+    });
+
+    it("uses framework-prime merge strategy", () => {
+      expect(settings.getMergeStrategy()).toBe("framework-prime");
+    });
+
+    it("references vscode-settings.json asset file (not hardcoded staticContent)", () => {
+      expect(settings.staticContentAssetFile).toBe("vscode-settings.json");
+      expect(settings.staticContent).toBeUndefined();
+    });
+
+    it("does not consume framework signals (content is CLI-owned)", () => {
+      expect(settings.consumes).toHaveLength(0);
+    });
+
+    it("declares requiresTool: vscode (gate merge to IDE-present context)", () => {
+      expect(settings.requiresTool).toBe("vscode");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/skills.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/skills.unit.test.ts
new file mode 100644
index 000000000..cde838aba
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/skills.unit.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
+
+describe("copilot skills", () => {
+  describe("capabilities.skills.buildInstallPath()", () => {
+    it("preserves directory structure without flattening", () => {
+      const path = copilot.capabilities.skills.buildInstallPath("commit/SKILL.md");
+      expect(path).toBe(".github/skills/commit/SKILL.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
deleted file mode 100644
index 81a96d73a..000000000
--- a/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts
+++ /dev/null
@@ -1,206 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { CONFIG_MCP } from "../../../../../src/contexts/tools/domain/capabilities/config-refs.js";
-import { cursor } from "../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
-
-describe("cursor", () => {
-  describe("capabilities.rules.convertFrontmatter()", () => {
-    it("converts paths: to globs: as a JSON inline string and adds alwaysApply: false", () => {
-      const result = cursor.capabilities.rules?.convertFrontmatter({
-        paths: ["src/**/*.ts", "tests/**/*.ts"],
-      });
-      expect(result).toStrictEqual({
-        globs: '["src/**/*.ts", "tests/**/*.ts"]',
-        alwaysApply: false,
-      });
-    });
-
-    it("keeps the description ahead of the globs it applies to", () => {
-      const result = cursor.capabilities.rules?.convertFrontmatter({
-        description: "Apply when editing sources.",
-        paths: ["src/**/*.ts"],
-      });
-      expect(result).toStrictEqual({
-        description: "Apply when editing sources.",
-        globs: '["src/**/*.ts"]',
-        alwaysApply: false,
-      });
-    });
-
-    it("returns empty frontmatter for rules without paths (always apply)", () => {
-      const result = cursor.capabilities.rules?.convertFrontmatter({
-        description: "desc",
-        alwaysApply: true,
-      });
-      expect(result).toStrictEqual({});
-    });
-
-    it("returns empty frontmatter for a rule whose paths list is empty", () => {
-      const result = cursor.capabilities.rules?.convertFrontmatter({ paths: [] });
-      expect(result).toStrictEqual({});
-    });
-
-    it("returns empty frontmatter for a rule that opts out of always-apply and names no description", () => {
-      const result = cursor.capabilities.rules?.convertFrontmatter({ alwaysApply: false });
-      expect(result).toStrictEqual({});
-    });
-
-    it("keeps description and alwaysApply false when no globs are specified", () => {
-      const result = cursor.capabilities.rules?.convertFrontmatter({
-        description: "Apply when editing command files.",
-        alwaysApply: false,
-      });
-      expect(result).toEqual({
-        description: "Apply when editing command files.",
-        alwaysApply: false,
-      });
-    });
-  });
-
-  describe("capabilities.agents.convertFrontmatter()", () => {
-    it("keeps model inheritance for AIDD agents installed as native plugins", () => {
-      const result = cursor.capabilities.agents.convertFrontmatter(
-        { name: "explorer", description: "Role" },
-        "explorer.md"
-      );
-      expect(result).toEqual({ name: "explorer", description: "Role" });
-    });
-
-    it("preserves an explicitly selected agent model", () => {
-      const fm = { name: "alexia", description: "Agent", model: "opus" };
-      const result = cursor.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
-    });
-  });
-
-  describe("capabilities.commands.convertFrontmatter()", () => {
-    it("prefixes name with aidd:<phase>: and strips extra fields", () => {
-      const fm = { name: "implement", description: "Implement", model: "sonnet" };
-      const result = cursor.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
-      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement" });
-    });
-  });
-
-  describe("capabilities.commands.buildInstallPath()", () => {
-    it("maps phase-prefixed path to aidd/<phase>/ subfolder", () => {
-      const path = cursor.capabilities.commands?.buildInstallPath("04_code/implement.md");
-      expect(path).toBe(".cursor/commands/aidd/04/implement.md");
-    });
-
-    it("maps top-level file to aidd/ subfolder without phase", () => {
-      const path = cursor.capabilities.commands?.buildInstallPath("commit.md");
-      expect(path).toBe(".cursor/commands/aidd/commit.md");
-    });
-  });
-
-  describe("capabilities.rules.buildInstallPath()", () => {
-    it("builds path for rules section with .mdc extension", () => {
-      const path = cursor.capabilities.rules?.buildInstallPath("01-standards/naming.md");
-      expect(path).toBe(".cursor/rules/01-standards/naming.mdc");
-    });
-
-    it("leaves a rule already written in Cursor's own extension untouched", () => {
-      const path = cursor.capabilities.rules?.buildInstallPath("01-standards/naming.mdc");
-      expect(path).toBe(".cursor/rules/01-standards/naming.mdc");
-    });
-  });
-
-  describe("rewriteContent()", () => {
-    it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
-      const rewritten = cursor.rewriteContent?.(
-        "Run .cursor/commands/04_code/implement.md, then @.cursor/commands/02-plan/plan.md.\n"
-      );
-      expect(rewritten).toBe(
-        "Run .cursor/commands/aidd/04/implement.md, then @.cursor/commands/aidd/02/plan.md.\n"
-      );
-    });
-
-    it("gives a referenced rule Cursor's .mdc extension", () => {
-      const rewritten = cursor.rewriteContent?.("Read @.cursor/rules/01-standards/naming.md\n");
-      expect(rewritten).toBe("Read @.cursor/rules/01-standards/naming.mdc\n");
-    });
-  });
-
-  describe("capabilities.agents.buildInstallPath()", () => {
-    it("keeps .md extension for agents", () => {
-      const path = cursor.capabilities.agents.buildInstallPath("code-reviewer.md");
-      expect(path).toBe(".cursor/agents/code-reviewer.md");
-    });
-  });
-
-  describe("capabilities.skills.buildInstallPath()", () => {
-    it("builds path under .cursor/skills/ without tool suffix", () => {
-      const path = cursor.capabilities.skills.buildInstallPath("commit/SKILL.md");
-      expect(path).toBe(".cursor/skills/commit/SKILL.md");
-    });
-
-    it("strips .cursor.md tool suffix from skill name", () => {
-      const path = cursor.capabilities.skills.buildInstallPath("commit.cursor.md");
-      expect(path).toBe(".cursor/skills/commit.md");
-    });
-  });
-
-  describe("capabilities.plugins", () => {
-    it("has a plugins capability", () => {
-      expect("plugins" in cursor.capabilities).toBe(true);
-    });
-
-    it("is native mode", () => {
-      expect(cursor.capabilities.plugins.mode).toBe("native");
-    });
-
-    it("pluginsDir is empty string (base-relative path prefix)", () => {
-      expect(cursor.capabilities.plugins.pluginsDir).toBe("");
-    });
-
-    it("pluginManifestRelativePath is null (no manifest file written into plugin dir)", () => {
-      expect(cursor.capabilities.plugins.pluginManifestRelativePath).toBeNull();
-    });
-
-    it("installScope is user", () => {
-      expect(cursor.capabilities.plugins.installScope).toBe("user");
-    });
-
-    it("acceptsHooks is true (Cursor auto-discovers hooks.json at plugin root)", () => {
-      expect(cursor.capabilities.plugins.acceptsHooks).toBe(true);
-    });
-
-    it("acceptsMcp is true (Cursor auto-discovers mcp.json at plugin root)", () => {
-      expect(cursor.capabilities.plugins.acceptsMcp).toBe(true);
-    });
-
-    it("marketplaceSettings is null", () => {
-      expect(cursor.capabilities.plugins.marketplaceSettings).toBeNull();
-    });
-
-    it("resolvePluginsBaseDir returns ~/.cursor/plugins/local resolved from given homedir", () => {
-      const result = cursor.capabilities.plugins.resolvePluginsBaseDir("/proj", "/home/user");
-      expect(result).toBe(join("/home/user", ".cursor", "plugins", "local"));
-    });
-  });
-});
-
-describe("cursor declarations the rest of the CLI reads", () => {
-  it("has .cursor/ directory", () => {
-    expect(cursor.directory).toBe(".cursor/");
-  });
-
-  it("probes a marketplace catalog at .cursor-plugin/marketplace.json", () => {
-    expect(cursor.distributionProbes?.marketplace).toStrictEqual([
-      ".cursor-plugin/marketplace.json",
-    ]);
-  });
-
-  it("writes agents as markdown", () => {
-    expect(cursor.capabilities.agents.params.format).toBe("markdown");
-  });
-
-  it("writes its MCP servers as JSON under `mcpServers`, in .cursor/mcp.json", () => {
-    expect(cursor.capabilities.mcp.params).toMatchObject({
-      outputPath: ".cursor/mcp.json",
-      format: "json",
-      entrySection: "mcpServers",
-    });
-    expect(cursor.capabilities.mcp.consumes).toStrictEqual([CONFIG_MCP]);
-  });
-});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts
new file mode 100644
index 000000000..59ef98184
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor agents", () => {
+  describe("capabilities.agents.convertFrontmatter()", () => {
+    it("keeps model inheritance for AIDD agents installed as native plugins", () => {
+      const result = cursor.capabilities.agents.convertFrontmatter(
+        { name: "explorer", description: "Role" },
+        "explorer.md"
+      );
+      expect(result).toEqual({ name: "explorer", description: "Role" });
+    });
+
+    it("preserves an explicitly selected agent model", () => {
+      const fm = { name: "alexia", description: "Agent", model: "opus" };
+      const result = cursor.capabilities.agents.convertFrontmatter(fm);
+      expect(result).toEqual({ name: "alexia", description: "Agent", model: "opus" });
+    });
+  });
+
+  describe("capabilities.agents.buildInstallPath()", () => {
+    it("keeps .md extension for agents", () => {
+      const path = cursor.capabilities.agents.buildInstallPath("code-reviewer.md");
+      expect(path).toBe(".cursor/agents/code-reviewer.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/commands.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/commands.unit.test.ts
new file mode 100644
index 000000000..a52ecadf2
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/commands.unit.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor commands", () => {
+  describe("capabilities.commands.convertFrontmatter()", () => {
+    it("prefixes name with aidd:<phase>: and strips extra fields", () => {
+      const fm = { name: "implement", description: "Implement", model: "sonnet" };
+      const result = cursor.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
+      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement" });
+    });
+  });
+
+  describe("capabilities.commands.buildInstallPath()", () => {
+    it("maps phase-prefixed path to aidd/<phase>/ subfolder", () => {
+      const path = cursor.capabilities.commands?.buildInstallPath("04_code/implement.md");
+      expect(path).toBe(".cursor/commands/aidd/04/implement.md");
+    });
+
+    it("maps top-level file to aidd/ subfolder without phase", () => {
+      const path = cursor.capabilities.commands?.buildInstallPath("commit.md");
+      expect(path).toBe(".cursor/commands/aidd/commit.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/content.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/content.unit.test.ts
new file mode 100644
index 000000000..eec3f54d5
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/content.unit.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor content", () => {
+  describe("rewriteContent()", () => {
+    it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
+      const rewritten = cursor.rewriteContent?.(
+        "Run .cursor/commands/04_code/implement.md, then @.cursor/commands/02-plan/plan.md.\n"
+      );
+      expect(rewritten).toBe(
+        "Run .cursor/commands/aidd/04/implement.md, then @.cursor/commands/aidd/02/plan.md.\n"
+      );
+    });
+
+    it("gives a referenced rule Cursor's .mdc extension", () => {
+      const rewritten = cursor.rewriteContent?.("Read @.cursor/rules/01-standards/naming.md\n");
+      expect(rewritten).toBe("Read @.cursor/rules/01-standards/naming.mdc\n");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/plugins.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/plugins.unit.test.ts
new file mode 100644
index 000000000..9e20693b8
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/plugins.unit.test.ts
@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor plugins", () => {
+  describe("capabilities.plugins", () => {
+    it("has a plugins capability", () => {
+      expect("plugins" in cursor.capabilities).toBe(true);
+    });
+
+    it("is native mode", () => {
+      expect(cursor.capabilities.plugins.mode).toBe("native");
+    });
+
+    it("pluginsDir is empty string (base-relative path prefix)", () => {
+      expect(cursor.capabilities.plugins.pluginsDir).toBe("");
+    });
+
+    it("pluginManifestRelativePath is null (no manifest file written into plugin dir)", () => {
+      expect(cursor.capabilities.plugins.pluginManifestRelativePath).toBeNull();
+    });
+
+    it("installScope is user", () => {
+      expect(cursor.capabilities.plugins.installScope).toBe("user");
+    });
+
+    it("acceptsHooks is true (Cursor auto-discovers hooks.json at plugin root)", () => {
+      expect(cursor.capabilities.plugins.acceptsHooks).toBe(true);
+    });
+
+    it("acceptsMcp is true (Cursor auto-discovers mcp.json at plugin root)", () => {
+      expect(cursor.capabilities.plugins.acceptsMcp).toBe(true);
+    });
+
+    it("marketplaceSettings is null", () => {
+      expect(cursor.capabilities.plugins.marketplaceSettings).toBeNull();
+    });
+
+    it("resolvePluginsBaseDir returns ~/.cursor/plugins/local resolved from given homedir", () => {
+      const result = cursor.capabilities.plugins.resolvePluginsBaseDir("/proj", "/home/user");
+      expect(result).toBe(join("/home/user", ".cursor", "plugins", "local"));
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/profile.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/profile.unit.test.ts
new file mode 100644
index 000000000..7da856f52
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/profile.unit.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { CONFIG_MCP } from "../../../../../../src/contexts/tools/domain/capabilities/config-refs.js";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor declarations the rest of the CLI reads", () => {
+  it("has .cursor/ directory", () => {
+    expect(cursor.directory).toBe(".cursor/");
+  });
+
+  it("probes a marketplace catalog at .cursor-plugin/marketplace.json", () => {
+    expect(cursor.distributionProbes?.marketplace).toStrictEqual([
+      ".cursor-plugin/marketplace.json",
+    ]);
+  });
+
+  it("writes agents as markdown", () => {
+    expect(cursor.capabilities.agents.params.format).toBe("markdown");
+  });
+
+  it("writes its MCP servers as JSON under `mcpServers`, in .cursor/mcp.json", () => {
+    expect(cursor.capabilities.mcp.params).toMatchObject({
+      outputPath: ".cursor/mcp.json",
+      format: "json",
+      entrySection: "mcpServers",
+    });
+    expect(cursor.capabilities.mcp.consumes).toStrictEqual([CONFIG_MCP]);
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/rules.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/rules.unit.test.ts
new file mode 100644
index 000000000..d2e978224
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/rules.unit.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor rules", () => {
+  describe("capabilities.rules.convertFrontmatter()", () => {
+    it("converts paths: to globs: as a JSON inline string and adds alwaysApply: false", () => {
+      const result = cursor.capabilities.rules?.convertFrontmatter({
+        paths: ["src/**/*.ts", "tests/**/*.ts"],
+      });
+      expect(result).toStrictEqual({
+        globs: '["src/**/*.ts", "tests/**/*.ts"]',
+        alwaysApply: false,
+      });
+    });
+
+    it("keeps the description ahead of the globs it applies to", () => {
+      const result = cursor.capabilities.rules?.convertFrontmatter({
+        description: "Apply when editing sources.",
+        paths: ["src/**/*.ts"],
+      });
+      expect(result).toStrictEqual({
+        description: "Apply when editing sources.",
+        globs: '["src/**/*.ts"]',
+        alwaysApply: false,
+      });
+    });
+
+    it("returns empty frontmatter for rules without paths (always apply)", () => {
+      const result = cursor.capabilities.rules?.convertFrontmatter({
+        description: "desc",
+        alwaysApply: true,
+      });
+      expect(result).toStrictEqual({});
+    });
+
+    it("returns empty frontmatter for a rule whose paths list is empty", () => {
+      const result = cursor.capabilities.rules?.convertFrontmatter({ paths: [] });
+      expect(result).toStrictEqual({});
+    });
+
+    it("returns empty frontmatter for a rule that opts out of always-apply and names no description", () => {
+      const result = cursor.capabilities.rules?.convertFrontmatter({ alwaysApply: false });
+      expect(result).toStrictEqual({});
+    });
+
+    it("keeps description and alwaysApply false when no globs are specified", () => {
+      const result = cursor.capabilities.rules?.convertFrontmatter({
+        description: "Apply when editing command files.",
+        alwaysApply: false,
+      });
+      expect(result).toEqual({
+        description: "Apply when editing command files.",
+        alwaysApply: false,
+      });
+    });
+  });
+
+  describe("capabilities.rules.buildInstallPath()", () => {
+    it("builds path for rules section with .mdc extension", () => {
+      const path = cursor.capabilities.rules?.buildInstallPath("01-standards/naming.md");
+      expect(path).toBe(".cursor/rules/01-standards/naming.mdc");
+    });
+
+    it("leaves a rule already written in Cursor's own extension untouched", () => {
+      const path = cursor.capabilities.rules?.buildInstallPath("01-standards/naming.mdc");
+      expect(path).toBe(".cursor/rules/01-standards/naming.mdc");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/skills.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/skills.unit.test.ts
new file mode 100644
index 000000000..3b7bb1edc
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/skills.unit.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { cursor } from "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
+
+describe("cursor skills", () => {
+  describe("capabilities.skills.buildInstallPath()", () => {
+    it("builds path under .cursor/skills/ without tool suffix", () => {
+      const path = cursor.capabilities.skills.buildInstallPath("commit/SKILL.md");
+      expect(path).toBe(".cursor/skills/commit/SKILL.md");
+    });
+
+    it("strips .cursor.md tool suffix from skill name", () => {
+      const path = cursor.capabilities.skills.buildInstallPath("commit.cursor.md");
+      expect(path).toBe(".cursor/skills/commit.md");
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
deleted file mode 100644
index 64dd6ef10..000000000
--- a/cli/tests/contexts/tools/domain/profiles/opencode.unit.test.ts
+++ /dev/null
@@ -1,375 +0,0 @@
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { opencode } from "../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
-import { OpencodeDualConfigError } from "../../../../../src/kernel/errors.js";
-import { FileHash } from "../../../../../src/kernel/file.js";
-import type { FileReader } from "../../../../../src/kernel/ports/file-reader.js";
-
-function makeFs(existingPaths: string[]): FileReader {
-  return {
-    fileExists: async (path: string) => existingPaths.some((p) => path.endsWith(p)),
-    isExecutable: async () => false,
-    realpath: async (path: string) => path,
-    readFile: async () => "",
-    readFileHash: async () => new FileHash("00000000000000000000000000000000"),
-    listDirectory: async () => [],
-    listFilesRecursive: async () => [],
-  };
-}
-
-describe("opencode", () => {
-  describe("capabilities.agents.params.userDirectory()", () => {
-    const userDirectory = opencode.capabilities.agents.params.userDirectory;
-    it("follows XDG_CONFIG_HOME, else ~/.config, under opencode", () => {
-      expect(
-        userDirectory?.("/home", (name) => (name === "XDG_CONFIG_HOME" ? "/xdg" : undefined))
-      ).toBe(join("/xdg", "opencode"));
-      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".config", "opencode"));
-    });
-  });
-
-  describe("capabilities.agents.buildInstallPath()", () => {
-    it("builds path under .opencode/agents/", () => {
-      const path = opencode.capabilities.agents.buildInstallPath("code-reviewer.md");
-      expect(path).toBe(".opencode/agents/code-reviewer.md");
-    });
-
-    it("strips .opencode.md tool suffix", () => {
-      const path = opencode.capabilities.agents.buildInstallPath("alexia.opencode.md");
-      expect(path).toBe(".opencode/agents/alexia.md");
-    });
-  });
-
-  describe("capabilities.agents.convertFrontmatter()", () => {
-    it("adds mode subagent to OpenCode agent frontmatter", () => {
-      const fm = { name: "alexia", description: "Act like the user" };
-      const result = opencode.capabilities.agents.convertFrontmatter(fm);
-      expect(result).toEqual({ description: "Act like the user", mode: "subagent" });
-    });
-  });
-
-  describe("capabilities.commands.buildInstallPath()", () => {
-    it("builds AIDD-namespaced path under .opencode/commands/aidd/<phase>/", () => {
-      const path = opencode.capabilities.commands?.buildInstallPath("04_code/implement.md");
-      expect(path).toBe(".opencode/commands/aidd/04/implement.md");
-    });
-
-    it("falls back to aidd/<baseName> for top-level files without a phase directory", () => {
-      const path = opencode.capabilities.commands?.buildInstallPath("implement.md");
-      expect(path).toBe(".opencode/commands/aidd/implement.md");
-    });
-  });
-
-  describe("capabilities.commands.convertFrontmatter()", () => {
-    it("emits name prefixed with aidd:<phase>: and description", () => {
-      const fm = { name: "implement", description: "Implement a plan", model: "gpt-4o" };
-      const result = opencode.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
-      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement a plan" });
-    });
-
-    it("emits bare name when relativeFileName has no leading-digit phase", () => {
-      const fm = { name: "implement", description: "Implement a plan" };
-      const result = opencode.capabilities.commands?.convertFrontmatter(fm, "implement.md");
-      expect(result).toEqual({ name: "implement", description: "Implement a plan" });
-    });
-  });
-
-  describe("capabilities.rules.buildInstallPath()", () => {
-    it("builds path under .opencode/rules/", () => {
-      const path = opencode.capabilities.rules?.buildInstallPath("01-standards/naming.md");
-      expect(path).toBe(".opencode/rules/01-standards/naming.md");
-    });
-  });
-
-  describe("capabilities.rules.convertFrontmatter()", () => {
-    it("returns empty frontmatter regardless of input (paths, always-apply)", () => {
-      const result = opencode.capabilities.rules?.convertFrontmatter({
-        paths: ["src/**/*.ts"],
-      });
-      expect(result).toEqual({});
-    });
-
-    it("returns empty frontmatter for always-apply rules", () => {
-      const result = opencode.capabilities.rules?.convertFrontmatter({
-        description: "always",
-      });
-      expect(result).toEqual({});
-    });
-
-    it("keeps description when alwaysApply is false and no paths are specified", () => {
-      const result = opencode.capabilities.rules?.convertFrontmatter({
-        description: "Apply when editing command files.",
-        alwaysApply: false,
-      });
-      expect(result).toEqual({ description: "Apply when editing command files." });
-    });
-
-    it("writes no description key when alwaysApply is false and there is no description", () => {
-      expect(opencode.capabilities.rules?.convertFrontmatter({ alwaysApply: false })).toStrictEqual(
-        {}
-      );
-    });
-  });
-
-  describe("capabilities.skills.buildInstallPath()", () => {
-    it("builds path under .opencode/skills/", () => {
-      const path = opencode.capabilities.skills.buildInstallPath("my-skill/SKILL.md");
-      expect(path).toBe(".opencode/skills/my-skill/SKILL.md");
-    });
-  });
-
-  describe("capabilities.skills.convertFrontmatter()", () => {
-    it("preserves all frontmatter fields", () => {
-      const fm = { name: "my-skill", description: "A skill" };
-      expect(opencode.capabilities.skills.convertFrontmatter(fm)).toEqual(fm);
-    });
-  });
-
-  describe("capabilities.mcp", () => {
-    it("maps both opencode and mcp config names to opencode.json", () => {
-      expect(opencode.capabilities.mcp.params.outputPath).toBe("opencode.json");
-      expect(opencode.capabilities.mcp.consumes).toContain("opencode");
-      expect(opencode.capabilities.mcp.consumes).toContain("mcp");
-    });
-
-    it("does not consume unknown config names", () => {
-      expect(opencode.capabilities.mcp.consumes).not.toContain("unknown");
-    });
-
-    it("uses framework-prime merge strategy", () => {
-      expect(opencode.capabilities.mcp.params.mergeStrategy).toBe("framework-prime");
-    });
-
-    it("writes its config as JSON, under the mcp key", () => {
-      const { format, entrySection } = opencode.capabilities.mcp.params;
-      expect({ format, entrySection }).toStrictEqual({ format: "json", entrySection: "mcp" });
-    });
-  });
-
-  describe("capabilities.mcp.transform() (MCP transform)", () => {
-    it("is defined on the OpenCode mcp capability", () => {
-      expect(opencode.capabilities.mcp.params.transformContent).toBeDefined();
-    });
-
-    const transform = (configName: string, content: string): string => {
-      if (configName !== "mcp") return content;
-      const fn = opencode.capabilities.mcp.params.transformContent;
-      if (!fn) throw new Error("transformContent not defined");
-      return fn(content);
-    };
-
-    it("transforms mcpServers to OpenCode mcp format with env", () => {
-      const input = JSON.stringify({
-        mcpServers: {
-          "my-server": {
-            command: "npx",
-            args: ["-y", "@some/mcp-server"],
-            env: { API_KEY: "secret" },
-          },
-        },
-      });
-      expect(JSON.parse(transform("mcp", input))).toEqual({
-        mcp: {
-          "my-server": {
-            type: "local",
-            command: ["npx", "-y", "@some/mcp-server"],
-            enabled: true,
-            environment: { API_KEY: "secret" },
-          },
-        },
-      });
-    });
-
-    it("omits environment when env field is absent", () => {
-      const input = JSON.stringify({
-        mcpServers: { server: { command: "node", args: ["server.js"] } },
-      });
-      expect(JSON.parse(transform("mcp", input)).mcp.server).not.toHaveProperty("environment");
-    });
-
-    it("omits environment when env is explicitly empty", () => {
-      const input = JSON.stringify({
-        mcpServers: { server: { command: "node", env: {} } },
-      });
-      expect(JSON.parse(transform("mcp", input)).mcp.server).not.toHaveProperty("environment");
-    });
-
-    it("produces empty mcp object when mcpServers is empty", () => {
-      const input = JSON.stringify({ mcpServers: {} });
-      expect(JSON.parse(transform("mcp", input))).toEqual({ mcp: {} });
-    });
-
-    it("throws with context on malformed JSON", () => {
-      expect(() => transform("mcp", "not-json")).toThrow("Cannot parse MCP config:");
-    });
-
-    it("throws when root is not an object (array)", () => {
-      expect(() => transform("mcp", "[]")).toThrow("MCP config must be a JSON object");
-    });
-
-    it("transforms url-based server to remote format", () => {
-      const input = JSON.stringify({
-        mcpServers: { figma: { url: "https://mcp.figma.com/mcp", type: "http" } },
-      });
-      expect(JSON.parse(transform("mcp", input))).toEqual({
-        mcp: { figma: { type: "remote", url: "https://mcp.figma.com/mcp", enabled: true } },
-      });
-    });
-
-    it("handles mixed local and remote servers in the same config", () => {
-      const input = JSON.stringify({
-        mcpServers: {
-          local: { command: "npx", args: ["-y", "pkg"] },
-          remote: { url: "https://example.com/mcp" },
-        },
-      });
-      const result = JSON.parse(transform("mcp", input));
-      expect(result.mcp.local.type).toBe("local");
-      expect(result.mcp.remote.type).toBe("remote");
-    });
-
-    it("throws when a server has neither command nor url", () => {
-      const input = JSON.stringify({ mcpServers: { bad: { token: "abc" } } });
-      expect(() => transform("mcp", input)).toThrow(
-        'MCP server "bad" must have either a "command" or "url" field'
-      );
-    });
-
-    it("returns non-mcp content unchanged", () => {
-      const content = '{"instructions":[".opencode/rules/**/*.md"]}';
-      expect(transform("opencode", content)).toBe(content);
-    });
-
-    it("sets enabled: false on local server with disabled: true", () => {
-      const input = JSON.stringify({
-        mcpServers: { "my-server": { command: "node", args: ["server.js"], disabled: true } },
-      });
-      expect(JSON.parse(transform("mcp", input)).mcp["my-server"].enabled).toBe(false);
-    });
-
-    it("sets enabled: false on remote server with disabled: true", () => {
-      const input = JSON.stringify({
-        mcpServers: { figma: { url: "https://mcp.figma.com/mcp", disabled: true } },
-      });
-      expect(JSON.parse(transform("mcp", input)).mcp.figma.enabled).toBe(false);
-    });
-
-    it("preserves mixed enabled/disabled servers correctly", () => {
-      const input = JSON.stringify({
-        mcpServers: {
-          enabled: { command: "node", args: ["on.js"] },
-          disabled: { command: "node", args: ["off.js"], disabled: true },
-        },
-      });
-      const result = JSON.parse(transform("mcp", input));
-      expect(result.mcp.enabled.enabled).toBe(true);
-      expect(result.mcp.disabled.enabled).toBe(false);
-    });
-
-    it("sets enabled: true when disabled is explicitly false", () => {
-      const input = JSON.stringify({
-        mcpServers: { "my-server": { command: "node", disabled: false } },
-      });
-      expect(JSON.parse(transform("mcp", input)).mcp["my-server"].enabled).toBe(true);
-    });
-  });
-
-  describe("capabilities.mcp.resolveOutput()", () => {
-    const PROJECT_ROOT = "/project";
-
-    async function resolve(fs: FileReader): Promise<string> {
-      return opencode.capabilities.mcp.resolveOutput(PROJECT_ROOT, fs);
-    }
-
-    it("returns opencode.json when neither config file exists", async () => {
-      expect(await resolve(makeFs([]))).toBe("opencode.json");
-    });
-
-    it("returns opencode.json when only opencode.json exists", async () => {
-      expect(await resolve(makeFs(["opencode.json"]))).toBe("opencode.json");
-    });
-
-    it("returns opencode.jsonc when only opencode.jsonc exists", async () => {
-      expect(await resolve(makeFs(["opencode.jsonc"]))).toBe("opencode.jsonc");
-    });
-
-    it("throws OpencodeDualConfigError when both opencode.json and opencode.jsonc exist", async () => {
-      await expect(resolve(makeFs(["opencode.json", "opencode.jsonc"]))).rejects.toThrow(
-        OpencodeDualConfigError
-      );
-    });
-  });
-
-  describe("capabilities.plugins", () => {
-    it("has a plugins capability", () => {
-      expect("plugins" in opencode.capabilities).toBe(true);
-    });
-
-    it("is flat mode", () => {
-      expect(opencode.capabilities.plugins.mode).toBe("flat");
-    });
-
-    it("uses aidd- as flat namespace prefix", () => {
-      expect(opencode.capabilities.plugins.flatNamespacePrefix).toBe("aidd-");
-    });
-
-    it("pluginsDir is null", () => {
-      expect(opencode.capabilities.plugins.pluginsDir).toBeNull();
-    });
-
-    it("pluginOutputDir returns null", () => {
-      expect(opencode.capabilities.plugins.pluginOutputDir("my-plugin")).toBeNull();
-    });
-
-    it("namespaces a plugin's hook scripts under .opencode/hooks/", () => {
-      expect(opencode.capabilities.plugins.flatHooksDir).toBe(".opencode/hooks/");
-    });
-
-    it("declares opencode-plugin.js as the loader's own module, landing in .opencode/plugin/", () => {
-      expect(opencode.capabilities.plugins.flatHooksLoaderEntry).toEqual({
-        dir: ".opencode/plugin/",
-        baseName: "opencode-plugin.js",
-      });
-    });
-  });
-
-  describe("buildContracts.flat().artifacts.hooks.path()", () => {
-    const hooksArtifact = opencode.buildContracts?.flat?.().artifacts.hooks;
-    if (hooksArtifact === undefined || !hooksArtifact.supported) {
-      throw new Error("expected opencode's flat hooks artifact to be supported");
-    }
-    const path = hooksArtifact.path;
-
-    it("namespaces a plain hook script under .opencode/hooks/<plugin>/", () => {
-      expect(path("aidd-context", "hooks/update_memory.js")).toBe(
-        ".opencode/hooks/aidd-context/update_memory.js"
-      );
-    });
-
-    it("renames a plugin's own opencode-plugin.js flat into .opencode/plugin/<plugin>.js", () => {
-      expect(path("aidd-telemetry", "hooks/opencode-plugin.js")).toBe(
-        ".opencode/plugin/aidd-telemetry.js"
-      );
-    });
-
-    it("keeps two plugins' same-named hook script from colliding", () => {
-      const a = path("plugin-a", "hooks/x.js");
-      const b = path("plugin-b", "hooks/x.js");
-      expect(a).toBe(".opencode/hooks/plugin-a/x.js");
-      expect(b).toBe(".opencode/hooks/plugin-b/x.js");
-      expect(a).not.toBe(b);
-    });
-  });
-});
-
-describe("opencode.rewriteContent()", () => {
-  it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
-    expect(
-      opencode.rewriteContent(
-        "Run .opencode/commands/04_code/implement.md, then @.opencode/commands/02-plan/plan.md.\n"
-      )
-    ).toBe(
-      "Run .opencode/commands/aidd/04/implement.md, then @.opencode/commands/aidd/02/plan.md.\n"
-    );
-  });
-});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/agents.unit.test.ts
new file mode 100644
index 000000000..83b8c9f77
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/agents.unit.test.ts
@@ -0,0 +1,35 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode agents", () => {
+  describe("capabilities.agents.params.userDirectory()", () => {
+    const userDirectory = opencode.capabilities.agents.params.userDirectory;
+    it("follows XDG_CONFIG_HOME, else ~/.config, under opencode", () => {
+      expect(
+        userDirectory?.("/home", (name) => (name === "XDG_CONFIG_HOME" ? "/xdg" : undefined))
+      ).toBe(join("/xdg", "opencode"));
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".config", "opencode"));
+    });
+  });
+
+  describe("capabilities.agents.buildInstallPath()", () => {
+    it("builds path under .opencode/agents/", () => {
+      const path = opencode.capabilities.agents.buildInstallPath("code-reviewer.md");
+      expect(path).toBe(".opencode/agents/code-reviewer.md");
+    });
+
+    it("strips .opencode.md tool suffix", () => {
+      const path = opencode.capabilities.agents.buildInstallPath("alexia.opencode.md");
+      expect(path).toBe(".opencode/agents/alexia.md");
+    });
+  });
+
+  describe("capabilities.agents.convertFrontmatter()", () => {
+    it("adds mode subagent to OpenCode agent frontmatter", () => {
+      const fm = { name: "alexia", description: "Act like the user" };
+      const result = opencode.capabilities.agents.convertFrontmatter(fm);
+      expect(result).toEqual({ description: "Act like the user", mode: "subagent" });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/commands.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/commands.unit.test.ts
new file mode 100644
index 000000000..c365ffafe
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/commands.unit.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode commands", () => {
+  describe("capabilities.commands.buildInstallPath()", () => {
+    it("builds AIDD-namespaced path under .opencode/commands/aidd/<phase>/", () => {
+      const path = opencode.capabilities.commands?.buildInstallPath("04_code/implement.md");
+      expect(path).toBe(".opencode/commands/aidd/04/implement.md");
+    });
+
+    it("falls back to aidd/<baseName> for top-level files without a phase directory", () => {
+      const path = opencode.capabilities.commands?.buildInstallPath("implement.md");
+      expect(path).toBe(".opencode/commands/aidd/implement.md");
+    });
+  });
+
+  describe("capabilities.commands.convertFrontmatter()", () => {
+    it("emits name prefixed with aidd:<phase>: and description", () => {
+      const fm = { name: "implement", description: "Implement a plan", model: "gpt-4o" };
+      const result = opencode.capabilities.commands?.convertFrontmatter(fm, "04_code/implement.md");
+      expect(result).toEqual({ name: "aidd:04:implement", description: "Implement a plan" });
+    });
+
+    it("emits bare name when relativeFileName has no leading-digit phase", () => {
+      const fm = { name: "implement", description: "Implement a plan" };
+      const result = opencode.capabilities.commands?.convertFrontmatter(fm, "implement.md");
+      expect(result).toEqual({ name: "implement", description: "Implement a plan" });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/content.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/content.unit.test.ts
new file mode 100644
index 000000000..179465050
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/content.unit.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode.rewriteContent()", () => {
+  it("routes a numbered command folder under commands/aidd/<phase>/, with or without the @ prefix", () => {
+    expect(
+      opencode.rewriteContent(
+        "Run .opencode/commands/04_code/implement.md, then @.opencode/commands/02-plan/plan.md.\n"
+      )
+    ).toBe(
+      "Run .opencode/commands/aidd/04/implement.md, then @.opencode/commands/aidd/02/plan.md.\n"
+    );
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/hooks.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/hooks.unit.test.ts
new file mode 100644
index 000000000..892732b8c
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/hooks.unit.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode hooks", () => {
+  describe("buildContracts.flat().artifacts.hooks.path()", () => {
+    const hooksArtifact = opencode.buildContracts?.flat?.().artifacts.hooks;
+    if (hooksArtifact === undefined || !hooksArtifact.supported) {
+      throw new Error("expected opencode's flat hooks artifact to be supported");
+    }
+    const path = hooksArtifact.path;
+
+    it("namespaces a plain hook script under .opencode/hooks/<plugin>/", () => {
+      expect(path("aidd-context", "hooks/update_memory.js")).toBe(
+        ".opencode/hooks/aidd-context/update_memory.js"
+      );
+    });
+
+    it("renames a plugin's own opencode-plugin.js flat into .opencode/plugin/<plugin>.js", () => {
+      expect(path("aidd-telemetry", "hooks/opencode-plugin.js")).toBe(
+        ".opencode/plugin/aidd-telemetry.js"
+      );
+    });
+
+    it("keeps two plugins' same-named hook script from colliding", () => {
+      const a = path("plugin-a", "hooks/x.js");
+      const b = path("plugin-b", "hooks/x.js");
+      expect(a).toBe(".opencode/hooks/plugin-a/x.js");
+      expect(b).toBe(".opencode/hooks/plugin-b/x.js");
+      expect(a).not.toBe(b);
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/mcp.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/mcp.unit.test.ts
new file mode 100644
index 000000000..d322a1e1a
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/mcp.unit.test.ts
@@ -0,0 +1,194 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+import { OpencodeDualConfigError } from "../../../../../../src/kernel/errors.js";
+import { FileHash } from "../../../../../../src/kernel/file.js";
+import type { FileReader } from "../../../../../../src/kernel/ports/file-reader.js";
+
+function makeFs(existingPaths: string[]): FileReader {
+  return {
+    fileExists: async (path: string) => existingPaths.some((p) => path.endsWith(p)),
+    isExecutable: async () => false,
+    realpath: async (path: string) => path,
+    readFile: async () => "",
+    readFileHash: async () => new FileHash("00000000000000000000000000000000"),
+    listDirectory: async () => [],
+    listFilesRecursive: async () => [],
+  };
+}
+
+describe("opencode mcp", () => {
+  describe("capabilities.mcp", () => {
+    it("maps both opencode and mcp config names to opencode.json", () => {
+      expect(opencode.capabilities.mcp.params.outputPath).toBe("opencode.json");
+      expect(opencode.capabilities.mcp.consumes).toContain("opencode");
+      expect(opencode.capabilities.mcp.consumes).toContain("mcp");
+    });
+
+    it("does not consume unknown config names", () => {
+      expect(opencode.capabilities.mcp.consumes).not.toContain("unknown");
+    });
+
+    it("uses framework-prime merge strategy", () => {
+      expect(opencode.capabilities.mcp.params.mergeStrategy).toBe("framework-prime");
+    });
+
+    it("writes its config as JSON, under the mcp key", () => {
+      const { format, entrySection } = opencode.capabilities.mcp.params;
+      expect({ format, entrySection }).toStrictEqual({ format: "json", entrySection: "mcp" });
+    });
+  });
+
+  describe("capabilities.mcp.transform() (MCP transform)", () => {
+    it("is defined on the OpenCode mcp capability", () => {
+      expect(opencode.capabilities.mcp.params.transformContent).toBeDefined();
+    });
+
+    const transform = (configName: string, content: string): string => {
+      if (configName !== "mcp") return content;
+      const fn = opencode.capabilities.mcp.params.transformContent;
+      if (!fn) throw new Error("transformContent not defined");
+      return fn(content);
+    };
+
+    it("transforms mcpServers to OpenCode mcp format with env", () => {
+      const input = JSON.stringify({
+        mcpServers: {
+          "my-server": {
+            command: "npx",
+            args: ["-y", "@some/mcp-server"],
+            env: { API_KEY: "secret" },
+          },
+        },
+      });
+      expect(JSON.parse(transform("mcp", input))).toEqual({
+        mcp: {
+          "my-server": {
+            type: "local",
+            command: ["npx", "-y", "@some/mcp-server"],
+            enabled: true,
+            environment: { API_KEY: "secret" },
+          },
+        },
+      });
+    });
+
+    it("omits environment when env field is absent", () => {
+      const input = JSON.stringify({
+        mcpServers: { server: { command: "node", args: ["server.js"] } },
+      });
+      expect(JSON.parse(transform("mcp", input)).mcp.server).not.toHaveProperty("environment");
+    });
+
+    it("omits environment when env is explicitly empty", () => {
+      const input = JSON.stringify({
+        mcpServers: { server: { command: "node", env: {} } },
+      });
+      expect(JSON.parse(transform("mcp", input)).mcp.server).not.toHaveProperty("environment");
+    });
+
+    it("produces empty mcp object when mcpServers is empty", () => {
+      const input = JSON.stringify({ mcpServers: {} });
+      expect(JSON.parse(transform("mcp", input))).toEqual({ mcp: {} });
+    });
+
+    it("throws with context on malformed JSON", () => {
+      expect(() => transform("mcp", "not-json")).toThrow("Cannot parse MCP config:");
+    });
+
+    it("throws when root is not an object (array)", () => {
+      expect(() => transform("mcp", "[]")).toThrow("MCP config must be a JSON object");
+    });
+
+    it("transforms url-based server to remote format", () => {
+      const input = JSON.stringify({
+        mcpServers: { figma: { url: "https://mcp.figma.com/mcp", type: "http" } },
+      });
+      expect(JSON.parse(transform("mcp", input))).toEqual({
+        mcp: { figma: { type: "remote", url: "https://mcp.figma.com/mcp", enabled: true } },
+      });
+    });
+
+    it("handles mixed local and remote servers in the same config", () => {
+      const input = JSON.stringify({
+        mcpServers: {
+          local: { command: "npx", args: ["-y", "pkg"] },
+          remote: { url: "https://example.com/mcp" },
+        },
+      });
+      const result = JSON.parse(transform("mcp", input));
+      expect(result.mcp.local.type).toBe("local");
+      expect(result.mcp.remote.type).toBe("remote");
+    });
+
+    it("throws when a server has neither command nor url", () => {
+      const input = JSON.stringify({ mcpServers: { bad: { token: "abc" } } });
+      expect(() => transform("mcp", input)).toThrow(
+        'MCP server "bad" must have either a "command" or "url" field'
+      );
+    });
+
+    it("returns non-mcp content unchanged", () => {
+      const content = '{"instructions":[".opencode/rules/**/*.md"]}';
+      expect(transform("opencode", content)).toBe(content);
+    });
+
+    it("sets enabled: false on local server with disabled: true", () => {
+      const input = JSON.stringify({
+        mcpServers: { "my-server": { command: "node", args: ["server.js"], disabled: true } },
+      });
+      expect(JSON.parse(transform("mcp", input)).mcp["my-server"].enabled).toBe(false);
+    });
+
+    it("sets enabled: false on remote server with disabled: true", () => {
+      const input = JSON.stringify({
+        mcpServers: { figma: { url: "https://mcp.figma.com/mcp", disabled: true } },
+      });
+      expect(JSON.parse(transform("mcp", input)).mcp.figma.enabled).toBe(false);
+    });
+
+    it("preserves mixed enabled/disabled servers correctly", () => {
+      const input = JSON.stringify({
+        mcpServers: {
+          enabled: { command: "node", args: ["on.js"] },
+          disabled: { command: "node", args: ["off.js"], disabled: true },
+        },
+      });
+      const result = JSON.parse(transform("mcp", input));
+      expect(result.mcp.enabled.enabled).toBe(true);
+      expect(result.mcp.disabled.enabled).toBe(false);
+    });
+
+    it("sets enabled: true when disabled is explicitly false", () => {
+      const input = JSON.stringify({
+        mcpServers: { "my-server": { command: "node", disabled: false } },
+      });
+      expect(JSON.parse(transform("mcp", input)).mcp["my-server"].enabled).toBe(true);
+    });
+  });
+
+  describe("capabilities.mcp.resolveOutput()", () => {
+    const PROJECT_ROOT = "/project";
+
+    async function resolve(fs: FileReader): Promise<string> {
+      return opencode.capabilities.mcp.resolveOutput(PROJECT_ROOT, fs);
+    }
+
+    it("returns opencode.json when neither config file exists", async () => {
+      expect(await resolve(makeFs([]))).toBe("opencode.json");
+    });
+
+    it("returns opencode.json when only opencode.json exists", async () => {
+      expect(await resolve(makeFs(["opencode.json"]))).toBe("opencode.json");
+    });
+
+    it("returns opencode.jsonc when only opencode.jsonc exists", async () => {
+      expect(await resolve(makeFs(["opencode.jsonc"]))).toBe("opencode.jsonc");
+    });
+
+    it("throws OpencodeDualConfigError when both opencode.json and opencode.jsonc exist", async () => {
+      await expect(resolve(makeFs(["opencode.json", "opencode.jsonc"]))).rejects.toThrow(
+        OpencodeDualConfigError
+      );
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/plugins.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/plugins.unit.test.ts
new file mode 100644
index 000000000..b60a61e53
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/plugins.unit.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode plugins", () => {
+  describe("capabilities.plugins", () => {
+    it("has a plugins capability", () => {
+      expect("plugins" in opencode.capabilities).toBe(true);
+    });
+
+    it("is flat mode", () => {
+      expect(opencode.capabilities.plugins.mode).toBe("flat");
+    });
+
+    it("uses aidd- as flat namespace prefix", () => {
+      expect(opencode.capabilities.plugins.flatNamespacePrefix).toBe("aidd-");
+    });
+
+    it("pluginsDir is null", () => {
+      expect(opencode.capabilities.plugins.pluginsDir).toBeNull();
+    });
+
+    it("pluginOutputDir returns null", () => {
+      expect(opencode.capabilities.plugins.pluginOutputDir("my-plugin")).toBeNull();
+    });
+
+    it("namespaces a plugin's hook scripts under .opencode/hooks/", () => {
+      expect(opencode.capabilities.plugins.flatHooksDir).toBe(".opencode/hooks/");
+    });
+
+    it("declares opencode-plugin.js as the loader's own module, landing in .opencode/plugin/", () => {
+      expect(opencode.capabilities.plugins.flatHooksLoaderEntry).toEqual({
+        dir: ".opencode/plugin/",
+        baseName: "opencode-plugin.js",
+      });
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/rules.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/rules.unit.test.ts
new file mode 100644
index 000000000..5a2cb8147
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/rules.unit.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode rules", () => {
+  describe("capabilities.rules.buildInstallPath()", () => {
+    it("builds path under .opencode/rules/", () => {
+      const path = opencode.capabilities.rules?.buildInstallPath("01-standards/naming.md");
+      expect(path).toBe(".opencode/rules/01-standards/naming.md");
+    });
+  });
+
+  describe("capabilities.rules.convertFrontmatter()", () => {
+    it("returns empty frontmatter regardless of input (paths, always-apply)", () => {
+      const result = opencode.capabilities.rules?.convertFrontmatter({
+        paths: ["src/**/*.ts"],
+      });
+      expect(result).toEqual({});
+    });
+
+    it("returns empty frontmatter for always-apply rules", () => {
+      const result = opencode.capabilities.rules?.convertFrontmatter({
+        description: "always",
+      });
+      expect(result).toEqual({});
+    });
+
+    it("keeps description when alwaysApply is false and no paths are specified", () => {
+      const result = opencode.capabilities.rules?.convertFrontmatter({
+        description: "Apply when editing command files.",
+        alwaysApply: false,
+      });
+      expect(result).toEqual({ description: "Apply when editing command files." });
+    });
+
+    it("writes no description key when alwaysApply is false and there is no description", () => {
+      expect(opencode.capabilities.rules?.convertFrontmatter({ alwaysApply: false })).toStrictEqual(
+        {}
+      );
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/opencode/skills.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/opencode/skills.unit.test.ts
new file mode 100644
index 000000000..0109ddc62
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/opencode/skills.unit.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { opencode } from "../../../../../../src/contexts/tools/domain/profiles/opencode/profile.js";
+
+describe("opencode skills", () => {
+  describe("capabilities.skills.buildInstallPath()", () => {
+    it("builds path under .opencode/skills/", () => {
+      const path = opencode.capabilities.skills.buildInstallPath("my-skill/SKILL.md");
+      expect(path).toBe(".opencode/skills/my-skill/SKILL.md");
+    });
+  });
+
+  describe("capabilities.skills.convertFrontmatter()", () => {
+    it("preserves all frontmatter fields", () => {
+      const fm = { name: "my-skill", description: "A skill" };
+      expect(opencode.capabilities.skills.convertFrontmatter(fm)).toEqual(fm);
+    });
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/vscode.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/vscode/settings.unit.test.ts
similarity index 91%
rename from cli/tests/contexts/tools/domain/profiles/vscode.unit.test.ts
rename to cli/tests/contexts/tools/domain/profiles/vscode/settings.unit.test.ts
index f964366ba..346c0fd29 100644
--- a/cli/tests/contexts/tools/domain/profiles/vscode.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/vscode/settings.unit.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
-import { vscodeToolConfig } from "../../../../../src/contexts/tools/domain/profiles/vscode/profile.js";
+import { vscodeToolConfig } from "../../../../../../src/contexts/tools/domain/profiles/vscode/profile.js";
 
-describe("vscodeToolConfig", () => {
+describe("vscodeToolConfig settings", () => {
   describe("settings capabilities", () => {
     const settings = Array.isArray(vscodeToolConfig.settings)
       ? vscodeToolConfig.settings

From 25f3eebe440de5696ffcdc769e35532b5a8bda62 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:41:56 +0800
Subject: [PATCH 60/73] docs(aidd-orchestrator): the phase file is the
 executor's brief, its session resumes

---
 .../aidd-orchestrator/skills/01-sdlc/references/02-deliver.md   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 984c6d8be..0ad3551cd 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -2,7 +2,7 @@
 
 ## Behavior
 
-Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; give each executor its scope, criteria, validation resources, and commit policy. Integrate prerequisites before starting dependent phases.
+Turn the contract into a proportional plan, then give one executor the whole plan or delegate ready independent phases. For delegated phases, the caller owns preparation, dependencies, write isolation, integration, and finalization; the phase file is the executor's brief, and the same executor session resumes for its next phase. Integrate prerequisites before starting dependent phases.
 
 The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
 

From 2ae195b8b706bae8abb56a9c23abe253db770758 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:41:57 +0800
Subject: [PATCH 61/73] docs(aidd-dev): a phase executor reads execute only and
 commits done after validation

---
 plugins/aidd-dev/skills/02-implement/SKILL.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md
index 0b0414d34..fbe8d3ba0 100644
--- a/plugins/aidd-dev/skills/02-implement/SKILL.md
+++ b/plugins/aidd-dev/skills/02-implement/SKILL.md
@@ -23,7 +23,7 @@ flowchart LR
 
 ## Actions
 
-Run actions in order for a whole plan. An assigned-phase executor reads the plan context and executes only that phase, skipping shared preparation and finalization.
+Run actions in order for a whole plan. An assigned-phase executor reads the plan context and `execute` only.
 Read each action file in `actions/` before executing it.
 
 | Action   | Does                                  |
@@ -47,7 +47,7 @@ Read each action file in `actions/` before executing it.
   - Group tasks only when they cannot be validated separately.
   - Never split a task by step or file.
   - Exclude unrelated changes.
-- Include `done` in the phase's last task commit.
+- Commit `done` once the phase is validated.
 - Make a final commit for `implemented`.
 - Use project formatters or hooks.
   - Never format code manually.

From bcf8d0af76293e96b7ab7c831b649ab9fdad4cd8 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:41:57 +0800
Subject: [PATCH 62/73] docs(aidd-dev): rerun the affected workflow after a
 repair, not everything

---
 plugins/aidd-dev/skills/02-implement/actions/02-execute.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
index 09fe6ea0b..0c5147c68 100644
--- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
+++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md
@@ -32,9 +32,8 @@ Or a `blocked` / `replan needed` report.
   - Use the appropriate interface (browser, CLI, API…).
   - Check actual against expected behavior at every step.
   - Fix any mismatch.
-  - Restart from the beginning after a repair.
+  - Rerun the affected workflow after a repair.
 - Gate task commits and `done` on successful validation.
-  - Require a full successful run.
   - Require observable evidence for every step.
   - Report blocked validation.
   - Never count blocked validation as success.

From 6e1a473a6b29a010b37d17387ea9351b31cefbf0 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:51:23 +0800
Subject: [PATCH 63/73] docs(aidd-orchestrator): the commit policy has one
 owner, the sdlc skill

---
 plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md               | 2 +-
 plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md | 2 +-
 .../aidd-orchestrator/skills/01-sdlc/references/02-deliver.md   | 2 +-
 plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
index e888e539f..d2175ac2c 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
@@ -8,7 +8,7 @@ argument-hint: request | interactive request
 
 ## Behavior
 
-Decide the mode as `mode.md` says, then read only it and the current zone's reference. Verify that every named provider is installed before calling it. A zone that cannot proceed stops the run and says what it would take to resume.
+Decide the mode as `mode.md` says, then read only it and the current zone's reference. Verify that every named provider is installed before calling it. A zone that cannot proceed stops the run and says what it would take to resume. A zone commits what it wrote through the commit skill before handing off.
 
 Use available host agents by responsibility, or a general-purpose agent with a scoped brief; custom agents are optional. Parallelize independent work when it is faster. Repeat the responsible zone when delegated work returns an actionable gap.
 
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md
index 67761c333..f57397e27 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md
@@ -2,7 +2,7 @@
 
 ## Behavior
 
-Start from `$source` only. Resolve a ticket when the source references one. Use the source directly when it is planning-ready. Otherwise clarify only the intent that can change what is built, then formalize the missing contract requirements. Commit whatever this zone wrote before handing the resulting contract to Deliver.
+Start from `$source` only. Resolve a ticket when the source references one. Use the source directly when it is planning-ready. Otherwise clarify only the intent that can change what is built, then formalize the missing contract requirements.
 
 A source is planning-ready when it names the artifact to change, states the observable outcome, and leaves open no decision that changes what is built.
 
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
index 0ad3551cd..bd8c26ff2 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/02-deliver.md
@@ -6,7 +6,7 @@ Turn the contract into a proportional plan, then give one executor the whole pla
 
 The executor follows the implementation skill for its assigned scope and calls the validation skills, which own their checks and repair loops. Include architecture conformance whenever the project documents architecture. Phase executors return for integration. Finalize the integrated plan once, including any required end-to-end journey after other checks and before marking it implemented.
 
-Commit and push the validated work through the commit skill. Send only the clean committed candidate and its evidence to Check.
+Send only the clean committed candidate and its evidence to Check.
 
 ```mermaid
 ---
diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
index efe29ff01..0f8617aa1 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/03-check.md
@@ -18,7 +18,7 @@ A review or validation finding is routed by what it is about. A refusal the user
 
 ## Handoff
 
-- Commit whatever this zone wrote, then open the draft pull request when no actionable finding remains.
+- Open the draft pull request when no actionable finding remains.
 
 ```mermaid
 ---

From a191acd65b0ea354e1826a9cf27d3f3d313a79af Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:51:23 +0800
Subject: [PATCH 64/73] docs(aidd-orchestrator): the spec is the contract Frame
 hands off

---
 plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md
index f57397e27..b47b78703 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/01-frame.md
@@ -2,7 +2,7 @@
 
 ## Behavior
 
-Start from `$source` only. Resolve a ticket when the source references one. Use the source directly when it is planning-ready. Otherwise clarify only the intent that can change what is built, then formalize the missing contract requirements.
+Start from `$source` only. Resolve a ticket when the source references one. Use the source directly when it is planning-ready. Otherwise clarify only the intent that can change what is built, then write the spec, which is the contract.
 
 A source is planning-ready when it names the artifact to change, states the observable outcome, and leaves open no decision that changes what is built.
 

From 6dc4a150b553f4cb4089703948b387039a1c2c59 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:52:46 +0800
Subject: [PATCH 65/73] feat(cli): support Copilot user agents and fix Cursor
 agent names

Copilot installs at user scope in COPILOT_HOME/agents, loaded by Copilot CLI 1.0.98. Cursor keeps single quotes in frontmatter values, so its agents are now double-quoted; Cursor CLI 2026.10.19 loads none from ~/.cursor/agents, so it stays project-only.
---
 .../domain/capabilities/agents-capability.ts      |  4 +++-
 .../tools/domain/profiles/copilot/profile.ts      |  1 +
 .../tools/domain/profiles/cursor/profile.ts       |  2 ++
 cli/src/kernel/markdown.ts                        | 13 +++++++++++--
 .../domain/profiles/copilot/agents.unit.test.ts   | 11 +++++++++++
 .../domain/profiles/cursor/agents.unit.test.ts    | 15 +++++++++++++++
 .../unloadable-file-as-failed-test.unit.test.ts   |  6 +++---
 cli/tests/kernel/markdown-yaml-like.unit.test.ts  |  6 ++++++
 docs/SUBAGENTS.md                                 | 14 ++++++++++++--
 scripts/dev-sync.sh                               |  1 +
 10 files changed, 65 insertions(+), 8 deletions(-)

diff --git a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
index 2f8a36279..2e3cc2b6b 100644
--- a/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
+++ b/cli/src/contexts/tools/domain/capabilities/agents-capability.ts
@@ -61,6 +61,8 @@ export class AgentsCapability {
       userFileExt?: string;
       /** The IDE's user configuration directory, holding `agents/` and the main settings file. */
       userDirectory?: (home: string, env: EnvironmentReader) => string;
+      /** How frontmatter strings are quoted; `double` for readers that keep single quotes. */
+      quote?: "single" | "double";
       buildInstallPath?: (fileName: string) => string | null;
       convertFrontmatter?: (
         fm: Record<string, unknown>,
@@ -118,7 +120,7 @@ export class AgentsCapability {
     if (this.params.format === "toml") {
       return buildTomlContent(frontmatter, body);
     }
-    return serializeFrontmatter(frontmatter, body);
+    return serializeFrontmatter(frontmatter, body, this.params.quote);
   }
 
   deserialize(content: string): { frontmatter: Record<string, unknown>; body: string } {
diff --git a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
index beb334de0..ebb7da399 100644
--- a/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/copilot/profile.ts
@@ -230,6 +230,7 @@ export const copilot: AiTool<
       format: "markdown",
       effortField: "reasoningEffort",
       userFileExt: EXT_AGENT,
+      userDirectory: (home, env) => env("COPILOT_HOME") || join(home, ".copilot"),
       buildInstallPath: (fileName) => agentsHandler.buildFilePath(fileName),
       convertFrontmatter: (fm, fileName) => agentsHandler.convertFrontmatter(fm, fileName),
     }),
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
index c7556a36d..f1e14178a 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
@@ -52,6 +52,8 @@ export const cursor: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         directory: DIRECTORY,
         toolSuffix: TOOL_SUFFIX,
         format: "markdown",
+        // Cursor keeps single quotes as part of the value, so `'name'` would be the agent's name.
+        quote: "double",
       }),
       skills: new SkillsCapability({
         directory: DIRECTORY,
diff --git a/cli/src/kernel/markdown.ts b/cli/src/kernel/markdown.ts
index 2be1507cc..7b55fd2aa 100644
--- a/cli/src/kernel/markdown.ts
+++ b/cli/src/kernel/markdown.ts
@@ -28,7 +28,12 @@ export function parseFrontmatter(content: string): {
   return { frontmatter, body };
 }
 
-export function serializeFrontmatter(frontmatter: Record<string, unknown>, body: string): string {
+/** `quote: "double"` writes strings as YAML double-quoted scalars, for readers that keep single quotes literally. */
+export function serializeFrontmatter(
+  frontmatter: Record<string, unknown>,
+  body: string,
+  quote: "single" | "double" = "single"
+): string {
   if (Object.keys(frontmatter).length === 0) {
     return body.replace(/^\n/, "");
   }
@@ -53,7 +58,11 @@ export function serializeFrontmatter(frontmatter: Record<string, unknown>, body:
       if (s.startsWith("[") && s.endsWith("]")) {
         lines.push(`${key}: ${s}`);
       } else {
-        lines.push(`${key}: '${s.replaceAll("'", "''")}'`);
+        lines.push(
+          quote === "double"
+            ? `${key}: ${JSON.stringify(s)}`
+            : `${key}: '${s.replaceAll("'", "''")}'`
+        );
       }
     }
   }
diff --git a/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts
index 1a81ed4f2..56b9f378b 100644
--- a/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/copilot/agents.unit.test.ts
@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { copilot } from "../../../../../../src/contexts/tools/domain/profiles/copilot/profile.js";
 
@@ -77,6 +78,16 @@ describe("copilot agents", () => {
     });
   });
 
+  describe("capabilities.agents.params.userDirectory()", () => {
+    it("follows COPILOT_HOME, else ~/.copilot", () => {
+      const userDirectory = copilot.capabilities.agents.params.userDirectory;
+      expect(
+        userDirectory?.("/home", (name) => (name === "COPILOT_HOME" ? "/cp" : undefined))
+      ).toBe("/cp");
+      expect(userDirectory?.("/home", () => undefined)).toBe(join("/home", ".copilot"));
+    });
+  });
+
   describe("capabilities.agents.buildInstallPath()", () => {
     it("adds .agent.md extension", () => {
       const path = copilot.capabilities.agents.buildInstallPath("code-reviewer.md");
diff --git a/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts
index 59ef98184..382968600 100644
--- a/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts
@@ -18,6 +18,21 @@ describe("cursor agents", () => {
     });
   });
 
+  describe("capabilities.agents.serialize()", () => {
+    it("double-quotes values, since Cursor keeps single quotes in the name", () => {
+      expect(
+        cursor.capabilities.agents.serialize(
+          { name: "explorer", model: "m[effort=medium]" },
+          "Body"
+        )
+      ).toBe('---\nname: "explorer"\nmodel: "m[effort=medium]"\n---\nBody');
+    });
+
+    it("declares no user directory: the Cursor CLI does not load user agents", () => {
+      expect(cursor.capabilities.agents.params.userDirectory).toBeUndefined();
+    });
+  });
+
   describe("capabilities.agents.buildInstallPath()", () => {
     it("keeps .md extension for agents", () => {
       const path = cursor.capabilities.agents.buildInstallPath("code-reviewer.md");
diff --git a/cli/tests/helpers/unloadable-file-as-failed-test.unit.test.ts b/cli/tests/helpers/unloadable-file-as-failed-test.unit.test.ts
index c14fd77c7..b2cb35654 100644
--- a/cli/tests/helpers/unloadable-file-as-failed-test.unit.test.ts
+++ b/cli/tests/helpers/unloadable-file-as-failed-test.unit.test.ts
@@ -11,12 +11,12 @@ const LOAD_ERROR = {
 function testFile(state: "pass" | "fail", tasks: RunnerTestFile["tasks"] = []): RunnerTestFile {
   const file: RunnerTestFile = {
     id: "cursor",
-    name: "cursor.unit.test.ts",
-    fullName: "cursor.unit.test.ts",
+    name: "cursor/agents.unit.test.ts",
+    fullName: "cursor/agents.unit.test.ts",
     mode: "run",
     meta: {},
     type: "suite",
-    filepath: "/repo/cli/tests/contexts/tools/domain/profiles/cursor.unit.test.ts",
+    filepath: "/repo/cli/tests/contexts/tools/domain/profiles/cursor/agents.unit.test.ts",
     projectName: "unit",
     concurrencyId: 0,
     workerId: 0,
diff --git a/cli/tests/kernel/markdown-yaml-like.unit.test.ts b/cli/tests/kernel/markdown-yaml-like.unit.test.ts
index 27812aed6..ae6f17442 100644
--- a/cli/tests/kernel/markdown-yaml-like.unit.test.ts
+++ b/cli/tests/kernel/markdown-yaml-like.unit.test.ts
@@ -109,6 +109,12 @@ describe("parseFrontmatter, line by line", () => {
 });
 
 describe("serializeFrontmatter, line by line", () => {
+  it("writes double-quoted strings on request, escaping what YAML needs", () => {
+    expect(serializeFrontmatter({ a: `it's "x"\\` }, "body", "double")).toBe(
+      '---\na: "it\'s \\"x\\"\\\\"\n---\nbody'
+    );
+  });
+
   it("quotes a value that only starts with a bracket", () => {
     expect(serializeFrontmatter({ a: "[open" }, "body")).toBe("---\na: '[open'\n---\nbody");
   });
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 9504987ee..b43848394 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -36,7 +36,7 @@ The main session stays as configured unless you add `--main`, which sets the pro
 | Codex | `.codex/config.toml` | top-level `model`, `model_reasoning_effort`; a selected `profile` still wins, and project files load only for trusted projects |
 | OpenCode | `opencode.json` | `model` only: the root model keeps no variant; refused when `opencode.jsonc` holds the settings |
 
-Copilot and Cursor are left unchanged. AIDD records what it replaced in `.aidd/main-model.json` and restores it on removal; it refuses to overwrite a value you changed since, and refuses TOML it cannot edit line by line safely. Sources checked 2026-10-20: [Claude Code settings](https://code.claude.com/docs/en/settings), [Codex config](https://developers.openai.com/codex/config-reference), [OpenCode V2 models](https://opencode.ai/v2/docs/models#variants).
+Copilot and Cursor refuse `--main`. AIDD records what it replaced in `.aidd/main-model.json` and restores it on removal; it refuses to overwrite a value you changed since, and refuses TOML it cannot edit line by line safely. Sources checked 2026-10-20: [Claude Code settings](https://code.claude.com/docs/en/settings), [Codex config](https://developers.openai.com/codex/config-reference), [OpenCode V2 models](https://opencode.ai/v2/docs/models#variants).
 
 ## 📦 Install
 
@@ -53,7 +53,17 @@ From the target project's root, install with a supported provider and IDE:
 node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
 ```
 
-Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`. Add `--main` to also set the main session model. Add `--scope user` to install into the IDE's user configuration instead (Claude Code, Codex, and OpenCode), with the registry in AIDD's user configuration directory.
+Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`. Add `--main` to also set the main session model. Add `--scope user` to install into the IDE's user configuration instead, with the registry in AIDD's user configuration directory.
+
+| IDE | Project | User scope | `--main` |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/agents/` | `~/.claude/agents/` (`CLAUDE_CONFIG_DIR`) | yes |
+| Codex | `.codex/agents/` | `~/.codex/agents/` (`CODEX_HOME`) | yes |
+| OpenCode | `.opencode/agents/` | `~/.config/opencode/agents/` (`XDG_CONFIG_HOME`) | yes |
+| Copilot | `.github/agents/` | `~/.copilot/agents/` (`COPILOT_HOME`) | no |
+| Cursor | `.cursor/agents/` | no: Cursor CLI 2026.10.19 loaded no agent from `~/.cursor/agents/` | no |
+
+Loading was checked on 2026-10-21 with Copilot CLI 1.0.98 (`--agent` lists and runs the four roles, project and user scope) and Cursor CLI 2026.10.19 (project scope). Cursor keeps single quotes in frontmatter values, so its agents are written with double quotes. A Copilot account limited to `auto` ignores the configured model with a warning. User directories, sources checked 2026-10-20 and 2026-10-21: [Claude Code sub-agents](https://code.claude.com/docs/en/sub-agents), [Codex subagents](https://developers.openai.com/codex/subagents), [OpenCode agents](https://opencode.ai/docs/agents), [Copilot configuration directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference), [Cursor subagents](https://cursor.com/docs/subagents).
 
 ## 🧪 Try a small task
 
diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh
index 403d07cda..3d1184387 100755
--- a/scripts/dev-sync.sh
+++ b/scripts/dev-sync.sh
@@ -152,6 +152,7 @@ install_opted_in_agents() {
     case "$ide" in
       claude-code) have="$HAVE_CLAUDE" ;;
       codex) have="$HAVE_CODEX" ;;
+      copilot) have="$HAVE_COPILOT" ;;
       opencode) have="$HAVE_OPENCODE"; [ "$HAVE_MANAGED_OPENCODE" = 0 ] || have=managed ;;
       *) have=1 ;;  # the CLI rejects an IDE without user-level agents
     esac

From ad6b0949bcb81f6578f6562b6e5e79be18e5ef05 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 10:59:27 +0800
Subject: [PATCH 66/73] docs(aidd-dev): a failure outside the assigned change
 is a blocker

---
 plugins/aidd-dev/skills/02-implement/references/blocked.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md
index 42c94f6a1..073b91902 100644
--- a/plugins/aidd-dev/skills/02-implement/references/blocked.md
+++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md
@@ -8,3 +8,5 @@ description: Conditions that make a plan blocked (needs a human).
 `blocked` means implementation cannot proceed and only a human can unblock it. Stop and escalate to the whole-plan owner, who sets the plan `status: blocked`.
 
 Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA.
+
+Outside the assigned change: a failure the change did not cause.

From f835fce15e294b28de57c343d7081403f361812f Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 11:00:21 +0800
Subject: [PATCH 67/73] docs(aidd-dev): explore only what no earlier
 exploration answers

---
 plugins/aidd-dev/skills/01-plan/actions/02-explore.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
index 3511ced8d..f431a5f45 100644
--- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
+++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md
@@ -12,7 +12,7 @@ The architecture projection (files to modify, create, delete, each with a one-li
 
 ## Process
 
-1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions.
+1. **Read.** Explore what the source touches and no earlier exploration already answers. Build the projection and list the infrastructure assumptions.
    - When useful, delegate independent domain questions to available agents with a scope and expected findings; reconcile their sourced answers and keep unresolved uncertainty visible.
 2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks.
 3. **Select.** Keep the project rules that apply to the projection.

From c6614c3a1241bfebc07807a2a9bf0eb06acff689 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 11:01:19 +0800
Subject: [PATCH 68/73] docs(aidd-orchestrator): drop the provider check nobody
 runs

---
 plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
index d2175ac2c..da2276f4f 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/SKILL.md
@@ -8,7 +8,7 @@ argument-hint: request | interactive request
 
 ## Behavior
 
-Decide the mode as `mode.md` says, then read only it and the current zone's reference. Verify that every named provider is installed before calling it. A zone that cannot proceed stops the run and says what it would take to resume. A zone commits what it wrote through the commit skill before handing off.
+Decide the mode as `mode.md` says, then read only it and the current zone's reference. A zone that cannot proceed stops the run and says what it would take to resume. A zone commits what it wrote through the commit skill before handing off.
 
 Use available host agents by responsibility, or a general-purpose agent with a scoped brief; custom agents are optional. Parallelize independent work when it is faster. Repeat the responsible zone when delegated work returns an actionable gap.
 

From 24ab8f656a55ac4f9c72e41b5c09be38cf7e18b9 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 11:02:16 +0800
Subject: [PATCH 69/73] docs(aidd-orchestrator): name branch deletion as an
 irreversible action

---
 plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md b/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
index 716ac6fe7..08d840f44 100644
--- a/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
+++ b/plugins/aidd-orchestrator/skills/01-sdlc/references/mode.md
@@ -4,7 +4,7 @@
 
 - The mode is `auto` unless the caller asks for `interactive`, named as the request's first whole word and no part of the source.
 - A request carrying nothing else is not one to run: say so and stop.
-- Ask only before spending money, taking an irreversible action, or making a decision that requires user authority.
+- Ask only before spending money, taking an irreversible action such as deleting a branch, or making a decision that requires user authority.
 - An exception stops the action it guards, not the rest of the request. Say what was withheld and what would release it.
 
 ## Auto

From e217bca81754f3525511616f44cca50c38ba7a1c Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 11:02:16 +0800
Subject: [PATCH 70/73] docs(agents): the executor names the commit its checks
 ran on

---
 cli/assets/agents/executor.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cli/assets/agents/executor.md b/cli/assets/agents/executor.md
index db5c3830e..4c28cb949 100644
--- a/cli/assets/agents/executor.md
+++ b/cli/assets/agents/executor.md
@@ -22,6 +22,6 @@ Return a concise result; omit empty fields.
 ```markdown
 **Status:** <COMPLETE | INCOMPLETE | BLOCKED>
 **Changes:** <delivered behavior and paths>
-**Checks:** <what ran and its result>
+**Checks:** <what ran, on which commit, and its result>
 **Remaining:** <unfinished work or blockers, if any>
 ```

From 0bd3844fe8cc908a2b5b2e7c2416cb86744b68c9 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 19:07:19 +0800
Subject: [PATCH 71/73] docs(framework): show which agent serves which task

Rewrite the subagent guide around how delegation flows, a role-to-task table and copy-paste installs; drop the beta trial template. Restore the responsibility table in AGENTS.md and the project-memory template, conditional on installed agents, and add user-level agent paths with sources.
---
 AGENTS.md                                     |   9 +
 docs/SUBAGENTS.md                             | 162 +++++++++---------
 .../assets/templates/AGENTS.md                |   9 +
 .../references/tool-paths.md                  |   4 +
 4 files changed, 107 insertions(+), 77 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 8483aace6..0e5096288 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -35,6 +35,15 @@
 
 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/`.
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index b43848394..198f8d679 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -1,118 +1,126 @@
 # 🤝 Optional subagents (beta)
 
+Four specialist agents your AI tool can hand work to, each in a fresh context and on a model sized for the job. Plugins work without them; you install them explicitly.
+
 ## 📑 Contents
 
-- [Roles](#-roles)
-- [Models and IDEs](#-models-and-ides)
+- [How it works](#-how-it-works)
+- [Which agent for which task](#-which-agent-for-which-task)
 - [Install](#-install)
-- [Try a small task](#-try-a-small-task)
+- [Models](#-models)
 - [Update or remove](#-update-or-remove)
-- [Beta limitations](#-beta-limitations)
-- [Share a trial](#-share-a-trial)
-- [Model notes](#-model-notes)
-
-## 👥 Roles
-
-Add focused roles to your project's AI tool. Installation is explicit.
-
-| Role | Responsibility |
-| --- | --- |
-| [Exploration](../cli/assets/agents/explorer.md) | Answer scoped codebase questions with source references. |
-| [Implementation](../cli/assets/agents/executor.md) | Deliver simple code or documentation with minimal changes and verification evidence. |
-| [Validation](../cli/assets/agents/validator.md) | Confirm the requested outcome and acceptance criteria hold. |
-| [Review](../cli/assets/agents/reviewer.md) | Find quality gaps, contradictions, duplication, and unnecessary complexity. |
-
-**Scope and delegation:** see the [Project Memory AGENTS.md template](../plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md#agents).
+- [Limits](#-limits)
+
+## 🔀 How it works
+
+Your main session keeps the conversation and decides what to delegate. Each agent gets a scoped brief, works in its own context, and returns its result to the main session, which owns the final answer.
+
+```mermaid
+sequenceDiagram
+  actor You
+  participant Main as Main session (main model)
+  participant Explorer as Explorer (light)
+  participant Executor as Executor (light)
+  participant Validator as Validator (light)
+  participant Reviewer as Reviewer (standard)
+  You->>Main: Request
+  Main->>Explorer: Where is it? How does it work?
+  Explorer-->>Main: Answer with sources
+  Main->>Executor: Build or fix this, with criteria
+  Executor-->>Main: Changes and checks
+  Main->>Validator: Does it meet the criteria?
+  Validator-->>Main: Validated yes or no
+  Main->>Reviewer: Is it clean and coherent?
+  Reviewer-->>Main: Findings
+  Main-->>You: Result
+```
 
-## 🧠 Models and IDEs
+Each step is optional: the main session calls only the agents the task needs, and repeats execution when validation or review finds a gap.
 
-[agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json) assigns each role a profile: `main` for the main session, `standard` for review, `light` for exploration, implementation, and validation. Each provider sets every profile's model and effort, for example Opus, Sonnet, and Haiku for Anthropic. Implementation and validation run on `light` to save cost; edit the role mapping to trade it for quality.
+Delegation is by responsibility: workflows such as `/aidd-orchestrator:01-sdlc` ask for "a fresh validation agent", and the host picks one of these if installed, or a general-purpose agent otherwise.
 
-The main session stays as configured unless you add `--main`, which sets the provider's `main` model and keeps every other setting:
+## 🧭 Which agent for which task
 
-| IDE | File | Keys |
-| --- | --- | --- |
-| Claude Code | `.claude/settings.json` | `model`, `effortLevel` |
-| Codex | `.codex/config.toml` | top-level `model`, `model_reasoning_effort`; a selected `profile` still wins, and project files load only for trusted projects |
-| OpenCode | `opencode.json` | `model` only: the root model keeps no variant; refused when `opencode.jsonc` holds the settings |
+| Agent | Use it to | It returns | Changes files |
+| --- | --- | --- | --- |
+| [Explorer](../cli/assets/agents/explorer.md) | Find files and symbols, trace a flow, answer a codebase question before a change | The answer, with sources and unknowns | No |
+| [Executor](../cli/assets/agents/executor.md) | Write or fix code and docs within a defined scope, then verify them | `COMPLETE`, `INCOMPLETE` or `BLOCKED`, with changes and checks run | Yes |
+| [Validator](../cli/assets/agents/validator.md) | Confirm delivered work meets the request and its acceptance criteria | `Validated: yes` or `no`, with what failed | No |
+| [Reviewer](../cli/assets/agents/reviewer.md) | Find defects, contradictions, duplication and needless complexity in finished work | `no actionable findings`, `changes needed` or `insufficient evidence`, with findings | No |
 
-Copilot and Cursor refuse `--main`. AIDD records what it replaced in `.aidd/main-model.json` and restores it on removal; it refuses to overwrite a value you changed since, and refuses TOML it cannot edit line by line safely. Sources checked 2026-10-20: [Claude Code settings](https://code.claude.com/docs/en/settings), [Codex config](https://developers.openai.com/codex/config-reference), [OpenCode V2 models](https://opencode.ai/v2/docs/models#variants).
+Typical order for a change: explore, execute, validate, then review.
 
 ## 📦 Install
 
-The CLI command is unreleased. Build a framework checkout from its root:
+The command is not released yet; build it from a framework checkout:
 
 ```sh
 pnpm --dir cli install --frozen-lockfile
 pnpm --dir cli build
 ```
 
-From the target project's root, install with a supported provider and IDE:
+Then pick your IDE and provider:
 
 ```sh
-node /absolute/path/to/framework/cli/dist/cli.js agents install --provider openai --ide codex
-```
-
-Installation writes four self-contained native files and the ownership registry at `.aidd/agents.json`. Add `--main` to also set the main session model. Add `--scope user` to install into the IDE's user configuration instead, with the registry in AIDD's user configuration directory.
+# In one project (from its root)
+node /path/to/framework/cli/dist/cli.js agents install --ide claude-code --provider anthropic
 
-| IDE | Project | User scope | `--main` |
-| --- | --- | --- | --- |
-| Claude Code | `.claude/agents/` | `~/.claude/agents/` (`CLAUDE_CONFIG_DIR`) | yes |
-| Codex | `.codex/agents/` | `~/.codex/agents/` (`CODEX_HOME`) | yes |
-| OpenCode | `.opencode/agents/` | `~/.config/opencode/agents/` (`XDG_CONFIG_HOME`) | yes |
-| Copilot | `.github/agents/` | `~/.copilot/agents/` (`COPILOT_HOME`) | no |
-| Cursor | `.cursor/agents/` | no: Cursor CLI 2026.10.19 loaded no agent from `~/.cursor/agents/` | no |
-
-Loading was checked on 2026-10-21 with Copilot CLI 1.0.98 (`--agent` lists and runs the four roles, project and user scope) and Cursor CLI 2026.10.19 (project scope). Cursor keeps single quotes in frontmatter values, so its agents are written with double quotes. A Copilot account limited to `auto` ignores the configured model with a warning. User directories, sources checked 2026-10-20 and 2026-10-21: [Claude Code sub-agents](https://code.claude.com/docs/en/sub-agents), [Codex subagents](https://developers.openai.com/codex/subagents), [OpenCode agents](https://opencode.ai/docs/agents), [Copilot configuration directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference), [Cursor subagents](https://cursor.com/docs/subagents).
-
-## 🧪 Try a small task
+# For every project of this user
+node /path/to/framework/cli/dist/cli.js agents install --ide claude-code --provider anthropic --scope user
 
-Use a disposable project or clean branch with explicit success criteria. Open a fresh host session after installation.
+# Also set the main session model (optional)
+node /path/to/framework/cli/dist/cli.js agents install --ide claude-code --provider anthropic --main
+```
 
-1. **Load:** confirm the installed roles are available; record the loaded definition's path and configured model and effort.
-2. **Explore:** delegate one read-only codebase question; check the answer's source references and confirm a separate agent ran.
-3. **Implement:** delegate one small code or documentation change with owned files and a check; inspect the diff and results.
-4. **Verify:** request independent validation against the criteria and review of quality and coherence.
+Open a new session afterwards so the IDE loads them.
 
-Use host dispatch records to identify the agent and actual model, effort, and tier where exposed. Headers and agent self-reports alone do not prove runtime selection; mark unavailable evidence **unverified**.
+| IDE (`--ide`) | Providers | Project | `--scope user` | `--main` |
+| --- | --- | --- | --- | --- |
+| `claude-code` | anthropic | `.claude/agents/` | `~/.claude/agents/` | yes |
+| `codex` | openai | `.codex/agents/` | `~/.codex/agents/` | yes |
+| `opencode` | openai, anthropic, mistral | `.opencode/agents/` | `~/.config/opencode/agents/` | yes |
+| `copilot` | openai, anthropic | `.github/agents/` | `~/.copilot/agents/` | no |
+| `cursor` | anthropic | `.cursor/agents/` | no | no |
 
-## 🔄 Update or remove
+User paths follow `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME` and `COPILOT_HOME`. AIDD records what it wrote in `.aidd/agents.json` (user scope: AIDD's user config directory) and never overwrites a file you edited.
 
-After updating the CLI, rerun the install command to refresh unmodified agents; agents of retired roles are removed. Plugins and `sync` do not install or refresh this add-on.
+## 🧠 Models
 
-For framework development, copy [reload-agents.example.json](../scripts/reload-agents.example.json) beside it as the gitignored `reload-agents.json` (or point `RELOAD_AGENTS` at another file). `make reload` then runs `agents install --scope user` for each listed IDE with its `provider`, adding `--main` where `"main": true`. Without the file, reload installs no agent. The file only adds: to undo an IDE or its main model, run `agents remove --scope user --ide <ide>`. Reload stops on a modified or unowned agent file; move it aside, then rerun.
+Each role uses a profile; each provider sets the profile's model and effort in [agent-models.json](../cli/src/contexts/tools/domain/formats/agent-models.json).
 
-To remove only one IDE's agents from the current project:
+| Profile | Roles | Anthropic | OpenAI | Mistral (OpenCode) |
+| --- | --- | --- | --- | --- |
+| `main` | main session, with `--main` | Opus 5.5 | GPT-6.1 Sol | Large 4 |
+| `standard` | reviewer | Sonnet 5.5 | GPT-6.1 Sol | Medium (`-latest`) |
+| `light` | explorer, executor, validator | Haiku 5.5 | GPT-6 Luna | Small (`-latest`) |
 
-```sh
-node /absolute/path/to/framework/cli/dist/cli.js agents remove --ide codex
-```
+Implementation and validation run on `light` to save cost; change the role mapping in that file to trade cost for quality.
 
-The other IDEs' agents remain installed; add `--scope user` for user-level agents. Removal also restores the main model it replaced. Installation and removal refuse changes to personal or modified agent files. `aidd clean` retires the entire AIDD project installation, including its managed agents; user-level agents stay until `agents remove --scope user`.
+`--main` writes only these keys and keeps the rest of the file:
 
-## 🚧 Beta limitations
+| IDE | File | Keys |
+| --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `model`, `effortLevel` |
+| Codex | `.codex/config.toml` | `model`, `model_reasoning_effort`; a selected `profile` still wins |
+| OpenCode | `opencode.json` | `model` (OpenCode keeps no effort at that level); refused when `opencode.jsonc` holds the settings |
 
-- **Runtime selection:** verify the host actually uses the configured model and effort during your trial.
-- **Interrupted command:** inspect the native files and registry before clearing `.aidd/agents.json.lock`; confirm no installation or removal is still running. Handled write failures restore the previous agent files, settings, and registries.
+It records the previous values in `.aidd/main-model.json` and restores them on removal; it refuses a value you changed since, and TOML it cannot edit safely.
 
-## 📝 Share a trial
+## 🔄 Update or remove
 
-Copy one report per trial:
+- **Update:** rerun the same install command; unmodified agents are refreshed and retired roles removed.
+- **Remove:** `agents remove --ide <ide>` (add `--scope user` for user agents). It also restores the main model it replaced.
+- **Clean:** `aidd clean` removes project agents with the rest of AIDD; user agents stay until `agents remove --scope user`.
 
-```markdown
-- **IDE/version:**
-- **CLI version/commit:**
-- **Provider:**
-- **Task and success criteria:**
-- **Observed source/dispatch/model/effort/tier:**
-- **Result:** passed / failed / unverified
-- **Evidence:** host records, relevant diff, check command and result
-```
+**Framework contributors:** copy [reload-agents.example.json](../scripts/reload-agents.example.json) beside it as the gitignored `reload-agents.json`. `make reload` then runs `agents install --scope user` for each listed IDE, adding `--main` where `"main": true`. The file only adds: undo with `agents remove --scope user --ide <ide>`.
 
-## 💡 Model notes
+## 🚧 Limits
 
-Mistral is supported on OpenCode; its documented reasoning levels are `none` and `high`. Review and light roles use the `mistral-medium-latest` and `mistral-small-latest` aliases, which resolved to Medium 3.5 and [Small 4](https://docs.mistral.ai/models/mistral-small-4-0-26-03) on 2026-10-20, so they follow Mistral's updates. The main session pins [`mistral-large-4`](https://docs.mistral.ai/models/mistral-large-4-0) (public preview): `mistral-large-latest` still resolved to Large 3, without reasoning levels, in OpenCode's model list on 2026-10-20. Medium 3.5 is also a public preview.
+- **Runtime model:** the files set model and effort; your plan or account decides what actually runs. A Copilot account limited to `auto` ignores the configured model with a warning.
+- **Cursor user scope:** Cursor CLI 2026.10.19 loaded no agent from `~/.cursor/agents/`, so only project install is supported. Cursor agents are written with double quotes because Cursor keeps single quotes in names.
+- **Codex:** project files load only for trusted projects; agents inherit the parent session's service tier, so Fast is enabled with `/fast` in the parent ([speed](https://learn.chatgpt.com/docs/agent-configuration/speed)).
+- **Interrupted command:** check the files before deleting `.aidd/agents.json.lock`; a handled failure already restores files and registries.
 
-Codex Fast supports Luna where available, but agents inherit the root session's service tier. Enable it with `/fast` in the parent session; agent installation does not change that setting. Fast consumes more usage. [Speed](https://learn.chatgpt.com/docs/agent-configuration/speed), [subagent inheritance](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agent-file-schema), checked 2026-10-16.
+Loading checked on 2026-10-21 with `pnpm --dir cli test:e2e:agents`, which asks each installed host which agents it loaded: Claude Code, Codex, OpenCode, Copilot CLI 1.0.98 and Cursor CLI 2026.10.19 (project scope); Copilot also at user scope.
 
-Sources checked 2026-10-16, Mistral and Claude Sonnet 2026-10-20: [OpenAI models](https://developers.openai.com/api/docs/models), [Claude models](https://platform.claude.com/docs/en/models/overview), [Mistral models](https://docs.mistral.ai/models), [Mistral Medium 3.5 (public preview)](https://mistral.ai/news/vibe-remote-agents-mistral-medium-3-5), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning), [OpenCode V2 variants](https://opencode.ai/v2/docs/models#variants), [Copilot model IDs](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#supported-models). These recommendations are not a comparative benchmark or proof of account access.
+Sources, checked 2026-10-16 to 2026-10-21: [Claude Code sub-agents](https://code.claude.com/docs/en/sub-agents) and [settings](https://code.claude.com/docs/en/settings), [Codex subagents](https://developers.openai.com/codex/subagents) and [config](https://developers.openai.com/codex/config-reference), [OpenCode agents](https://opencode.ai/docs/agents) and [models](https://opencode.ai/v2/docs/models#variants), [Copilot configuration directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference) and [model IDs](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#supported-models), [Cursor subagents](https://cursor.com/docs/subagents), [Claude models](https://platform.claude.com/docs/en/models/overview), [OpenAI models](https://developers.openai.com/api/docs/models), [Mistral models](https://docs.mistral.ai/models), [Mistral Large 4](https://docs.mistral.ai/models/mistral-large-4-0), [Mistral reasoning](https://docs.mistral.ai/studio/conversations/reasoning). Mistral Large 4 and Medium 3.5 are public previews; `mistral-large-latest` still pointed to Large 3, without reasoning, so the main model is pinned.
diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
index f0f666538..3cbd21754 100644
--- a/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
+++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/AGENTS.md
@@ -37,6 +37,15 @@
 
 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/`.
diff --git a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
index 41051f611..3f285991f 100644
--- a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
+++ b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md
@@ -14,6 +14,10 @@ The per-tool agent path and the gate every run executes before writing. Agent sl
 
 Agents are supported on all five tools.
 
+User-level agents, for every project of the user: Claude Code `~/.claude/agents/` (`CLAUDE_CONFIG_DIR`), Codex `~/.codex/agents/` (`CODEX_HOME`), OpenCode `~/.config/opencode/agents/` (`XDG_CONFIG_HOME`), Copilot `~/.copilot/agents/<name>.agent.md` (`COPILOT_HOME`). Cursor documents `~/.cursor/agents/`, but its CLI 2026.10.19 loaded none from there; prefer the project path. Checked 2026-10-21: [Claude](https://code.claude.com/docs/en/sub-agents), [Codex](https://developers.openai.com/codex/subagents), [OpenCode](https://opencode.ai/docs/agents), [Copilot](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference), [Cursor](https://cursor.com/docs/subagents).
+
+Cursor keeps single quotes as part of a frontmatter value: quote Cursor values with `"double quotes"` or not at all.
+
 ## Frontmatter per tool
 
 The canonical agent carries `name` and `description`. Emit those a row accepts, drop the rest. Add model or effort settings only when requested and supported.

From fb04273de231c93e608c29aea05f4a191fc73efb Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 19:08:16 +0800
Subject: [PATCH 72/73] test(cli): check that each host loads the installed
 agents

pnpm test:e2e:agents installs the agents in a throwaway project and asks Claude Code, Copilot and OpenCode (no inference), Cursor and Codex (one short turn) which agents they loaded.
---
 cli/aidd_docs/memory/testing.md          |   1 +
 cli/package.json                         |   1 +
 cli/tests/e2e/agents-runtime.e2e.test.ts | 145 +++++++++++++++++++++++
 3 files changed, 147 insertions(+)
 create mode 100644 cli/tests/e2e/agents-runtime.e2e.test.ts

diff --git a/cli/aidd_docs/memory/testing.md b/cli/aidd_docs/memory/testing.md
index 227bd6445..893160b4b 100644
--- a/cli/aidd_docs/memory/testing.md
+++ b/cli/aidd_docs/memory/testing.md
@@ -35,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.
diff --git a/cli/package.json b/cli/package.json
index 3cab154ed..784852b99 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -47,6 +47,7 @@
     "test:integration": "vitest run --project=integration",
     "test:e2e": "vitest run --project=e2e",
     "test:foreign-clock": "node scripts/test-foreign-clock.mjs",
+    "test:e2e:agents": "AGENTS_RUNTIME_SMOKE=1 vitest run --project=e2e tests/e2e/agents-runtime.e2e.test.ts",
     "test:e2e:kilo": "KILO_RUNTIME_SMOKE=1 vitest run --project=e2e tests/e2e/kilo-runtime.e2e.test.ts",
     "test:coverage": "vitest run --coverage",
     "test:kanban": "pnpm --dir ../kanban test",
diff --git a/cli/tests/e2e/agents-runtime.e2e.test.ts b/cli/tests/e2e/agents-runtime.e2e.test.ts
new file mode 100644
index 000000000..6ff82ccf1
--- /dev/null
+++ b/cli/tests/e2e/agents-runtime.e2e.test.ts
@@ -0,0 +1,145 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, readdir, readFile, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+import { cliPath } from "./helpers.js";
+
+/**
+ * Opt-in (`AGENTS_RUNTIME_SMOKE=1`): installs the four agents into a throwaway project, then
+ * asks each installed host which agents it loaded. It runs the person's real, signed-in hosts,
+ * so it reads their own HOME. Claude Code, Copilot and OpenCode answer without inference;
+ * Cursor and Codex need one short model turn.
+ */
+const describeRuntime = process.env.AGENTS_RUNTIME_SMOKE === "1" ? describe : describe.skip;
+const ROLES = ["aidd-dev-executor", "aidd-dev-explorer", "aidd-dev-reviewer", "aidd-dev-validator"];
+const run = promisify(execFile);
+const TIMEOUT = 240_000;
+
+function installed(binary: string): boolean {
+  return (process.env.PATH ?? "")
+    .split(delimiter)
+    .some((directory) => directory !== "" && existsSync(join(directory, binary)));
+}
+
+/** Combined output, whatever the exit code: hosts report unknown agents on stderr. Stdin is
+ * closed, since `codex exec` otherwise waits for more prompt on it. */
+function output(binary: string, args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve) => {
+    // OpenCode resolves its project from PWD, not the process directory.
+    const env = { ...process.env, PWD: cwd };
+    const child = spawn(binary, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let text = "";
+    child.stdout.on("data", (chunk) => {
+      text += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      text += chunk;
+    });
+    const timer = setTimeout(() => child.kill(), TIMEOUT - 10_000);
+    child.on("close", () => {
+      clearTimeout(timer);
+      resolve(text);
+    });
+  });
+}
+
+async function project(ide: string, provider: string): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), `aidd-agents-runtime-${ide}-`));
+  await run("git", ["init", "-q"], { cwd: root });
+  await run(
+    process.execPath,
+    [cliPath(), "agents", "install", "--ide", ide, "--provider", provider],
+    {
+      cwd: root,
+    }
+  );
+  return root;
+}
+
+const expectAllRoles = (text: string) => {
+  for (const role of ROLES) expect(text).toContain(role);
+};
+
+describeRuntime("E2E: hosts load the installed agents", () => {
+  it.skipIf(!installed("claude"))(
+    "Claude Code lists them for an unknown --agent",
+    async () => {
+      const root = await project("claude-code", "anthropic");
+      expectAllRoles(await output("claude", ["-p", "ok", "--agent", "aidd-dev-unknown"], root));
+    },
+    TIMEOUT
+  );
+
+  it.skipIf(!installed("copilot"))(
+    "Copilot lists them for an unknown --agent",
+    async () => {
+      const root = await project("copilot", "anthropic");
+      expectAllRoles(
+        await output("copilot", ["-p", "ok", "--agent", "aidd-dev-unknown", "-s"], root)
+      );
+    },
+    TIMEOUT
+  );
+
+  it.skipIf(!installed("opencode"))(
+    "OpenCode lists them through its agent API",
+    async () => {
+      const root = await project("opencode", "anthropic");
+      const listed = await output("opencode", ["api", "agent.list"], root);
+      expectAllRoles(listed);
+    },
+    TIMEOUT
+  );
+
+  it.skipIf(!installed("cursor-agent"))(
+    "Cursor names them, unquoted, in its subagent catalog",
+    async (context) => {
+      const root = await project("cursor", "anthropic");
+      const prompt =
+        "Call the Task tool with subagent type exactly aidd-dev-unknown and prompt hi. If it errors, reply with the full error text verbatim.";
+      const events = await output(
+        "cursor-agent",
+        ["-p", "--trust", "--output-format", "stream-json", prompt],
+        root
+      );
+      if (events.includes("usage limit")) context.skip("Cursor account usage limit reached");
+      for (const role of ROLES) expect(events).toMatch(new RegExp(`\\\\"${role}\\\\"`));
+    },
+    TIMEOUT
+  );
+
+  it.skipIf(!installed("codex"))(
+    "Codex spawns one with the installed prompt and model",
+    async () => {
+      const root = await project("codex", "openai");
+      const started = Date.now();
+      await output(
+        "codex",
+        [
+          "exec",
+          "--skip-git-repo-check",
+          "-c",
+          `projects."${root}".trust_level="trusted"`,
+          "Spawn exactly one agent of type aidd-dev-explorer with the task: reply ok. Then reply done.",
+        ],
+        root
+      );
+      const sessions = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions");
+      const rollouts: string[] = [];
+      for (const entry of await readdir(sessions, { recursive: true }))
+        if (entry.endsWith(".jsonl")) rollouts.push(join(sessions, entry));
+      const recent = [];
+      for (const path of rollouts) if ((await stat(path)).mtimeMs >= started) recent.push(path);
+      const child = (await Promise.all(recent.map((path) => readFile(path, "utf8")))).find((text) =>
+        text.includes('"agent_role":"aidd-dev-explorer"')
+      );
+      expect(child, "no Codex session ran as aidd-dev-explorer").toBeDefined();
+      expect(child).toContain("Keep sources unchanged");
+      expect(child).toContain('"model":"gpt-6-luna"');
+    },
+    TIMEOUT
+  );
+});

From 7317a49f3cf5d45929c96999c6f476f9caaaeb89 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Wed, 21 Oct 2026 19:08:19 +0800
Subject: [PATCH 73/73] refactor(cli): separate agent locations and main-model
 changes from the use case

The use case keeps ownership, registries and rollback; where agents live per scope and how the main model is set or restored move to their own modules.
---
 .../application/agents/agent-location.ts      |  71 +++++
 .../application/agents/main-model-changes.ts  |  76 +++++
 .../agents/manage-agents-use-case.ts          | 271 +++++-------------
 cli/src/runtime/wiring/framework.ts           |   6 +-
 4 files changed, 227 insertions(+), 197 deletions(-)
 create mode 100644 cli/src/contexts/framework/application/agents/agent-location.ts
 create mode 100644 cli/src/contexts/framework/application/agents/main-model-changes.ts

diff --git a/cli/src/contexts/framework/application/agents/agent-location.ts b/cli/src/contexts/framework/application/agents/agent-location.ts
new file mode 100644
index 000000000..be417e20a
--- /dev/null
+++ b/cli/src/contexts/framework/application/agents/agent-location.ts
@@ -0,0 +1,71 @@
+import { basename, join } from "node:path";
+import type { FileReader } from "../../../../kernel/ports/file-reader.js";
+import type { FileWriter } from "../../../../kernel/ports/file-writer.js";
+import type { AgentsCapability } from "../../../tools/domain/capabilities/agents-capability.js";
+import type { EnvironmentReader } from "../../../tools/domain/capabilities/plugins-capability.js";
+import type { HasAgents } from "../../../tools/domain/contracts.js";
+import type { AgentHost } from "../../../tools/domain/formats/agent-models.js";
+import { mainModelTarget } from "../../../tools/domain/formats/main-model-config.js";
+import { getAiToolConfig } from "../../../tools/domain/registry.js";
+import { assertProjectPathWithinRoot } from "../ownership/project-path-boundary.js";
+
+/** The user's home, environment and AIDD configuration directory, for user-scoped agents. */
+export interface UserAgentRoot {
+  home: string;
+  env: EnvironmentReader;
+  configDir: string;
+}
+
+export interface AgentTarget {
+  projectRoot: string;
+  host: AgentHost;
+  /** Targets the IDE's user configuration directory instead of the project. */
+  user?: UserAgentRoot;
+}
+
+/** Where one host's agents, main settings and ownership registry live for a scope. */
+export interface AgentLocation {
+  registryRoot: string;
+  /** Creates the registry root when the scope owns it. */
+  prepare?: () => Promise<void>;
+  agentPath(name: string): string;
+  settingsPath: string | null;
+  guard(path: string): Promise<void>;
+}
+
+export function agentsCapability(host: AgentHost): AgentsCapability {
+  return (getAiToolConfig(host).capabilities as HasAgents).agents;
+}
+
+export function resolveAgentLocation(
+  fs: FileReader & FileWriter,
+  target: AgentTarget
+): AgentLocation {
+  const capability = agentsCapability(target.host);
+  const settings = mainModelTarget(target.host);
+  const file = (name: string) => {
+    const path = capability.buildInstallPath(`${name}.md`);
+    if (path === null) throw new Error(`Agent ${name} has no native install path.`);
+    return path;
+  };
+  const user = target.user;
+  if (user === undefined) {
+    const root = target.projectRoot;
+    return {
+      registryRoot: root,
+      agentPath: (name) => join(root, file(name)),
+      settingsPath: settings === null ? null : join(root, settings.path),
+      guard: (path) => assertProjectPathWithinRoot(fs, root, path),
+    };
+  }
+  const directory = capability.params.userDirectory?.(user.home, user.env);
+  if (directory === undefined) throw new Error(`${target.host} has no user-level agents.`);
+  const configDir = user.configDir;
+  return {
+    registryRoot: configDir,
+    prepare: () => fs.createDirectory(configDir),
+    agentPath: (name) => join(directory, "agents", basename(file(name))),
+    settingsPath: settings === null ? null : join(directory, settings.userPath),
+    guard: async () => {},
+  };
+}
diff --git a/cli/src/contexts/framework/application/agents/main-model-changes.ts b/cli/src/contexts/framework/application/agents/main-model-changes.ts
new file mode 100644
index 000000000..0c15cb90c
--- /dev/null
+++ b/cli/src/contexts/framework/application/agents/main-model-changes.ts
@@ -0,0 +1,76 @@
+import { basename, dirname, join } from "node:path";
+import type { FileReader } from "../../../../kernel/ports/file-reader.js";
+import type { FileWriter } from "../../../../kernel/ports/file-writer.js";
+import type { AgentHost, AgentProvider } from "../../../tools/domain/formats/agent-models.js";
+import {
+  mainModelTarget,
+  mainModelValues,
+  planMainModelInstall,
+  planMainModelRemoval,
+} from "../../../tools/domain/formats/main-model-config.js";
+import type { MainModelInstallations } from "../../domain/ports/agent-installation-store.js";
+import { type AgentLocation, type AgentTarget, resolveAgentLocation } from "./agent-location.js";
+
+/** A file's next content; null deletes it. */
+export interface FileChange {
+  path: string;
+  content: string | null;
+}
+
+export async function readOptional(fs: FileReader, path: string): Promise<string | null> {
+  return (await fs.fileExists(path)) ? fs.readFile(path) : null;
+}
+
+/** The provider's main model written into the host settings, recording what it replaces. */
+export async function mainModelInstall(
+  fs: FileReader & FileWriter,
+  options: AgentTarget & { provider: AgentProvider },
+  location: AgentLocation,
+  mainModels: MainModelInstallations
+): Promise<FileChange | null> {
+  const target = mainModelTarget(options.host);
+  const path = location.settingsPath;
+  if (target === null || path === null) return null;
+  await location.guard(path);
+  if ((await fs.fileExists(path, false)) && !(await fs.fileExists(path)))
+    throw new Error(`Settings link is broken; fix it before installing agents: ${path}`);
+  const content = await readOptional(fs, path);
+  for (const alternative of content === null ? (target.alternatives ?? []) : [])
+    if (await fs.fileExists(join(dirname(path), alternative)))
+      throw new Error(
+        `Settings live in ${alternative}; move them to ${basename(path)} before installing agents.`
+      );
+  try {
+    const plan = planMainModelInstall(
+      content,
+      target.format,
+      mainModelValues(options.host, options.provider),
+      mainModels[options.host]
+    );
+    mainModels[options.host] = plan.record;
+    return { path, content: plan.content };
+  } catch (error) {
+    throw new Error(`Cannot set the main model in ${path}: ${(error as Error).message}`);
+  }
+}
+
+/** The settings each recorded main model replaced, restored. */
+export async function mainModelRemovals(
+  fs: FileReader & FileWriter,
+  target: Omit<AgentTarget, "host">,
+  mainModels: MainModelInstallations,
+  onlyHost?: AgentHost
+): Promise<FileChange[]> {
+  const changes: FileChange[] = [];
+  for (const [host, record] of Object.entries(mainModels)) {
+    if (onlyHost !== undefined && host !== onlyHost) continue;
+    const settings = mainModelTarget(host as AgentHost);
+    const location = resolveAgentLocation(fs, { ...target, host: host as AgentHost });
+    if (settings === null || location.settingsPath === null || record === undefined) continue;
+    await location.guard(location.settingsPath);
+    const content = await readOptional(fs, location.settingsPath);
+    const next = planMainModelRemoval(content, settings.format, record);
+    if (next !== content) changes.push({ path: location.settingsPath, content: next });
+  }
+  return changes;
+}
diff --git a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
index e5851db8e..e566a5523 100644
--- a/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
+++ b/cli/src/contexts/framework/application/agents/manage-agents-use-case.ts
@@ -1,23 +1,13 @@
-import { basename, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 import { parseFrontmatter } from "../../../../kernel/markdown.js";
 import type { FileReader } from "../../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../../kernel/ports/file-writer.js";
 import type { Hasher } from "../../../../kernel/ports/hasher.js";
-import type { AgentsCapability } from "../../../tools/domain/capabilities/agents-capability.js";
-import type { EnvironmentReader } from "../../../tools/domain/capabilities/plugins-capability.js";
-import type { HasAgents } from "../../../tools/domain/contracts.js";
 import {
   type AgentHost,
   type AgentProvider,
   agentModelOptions,
 } from "../../../tools/domain/formats/agent-models.js";
-import {
-  mainModelTarget,
-  mainModelValues,
-  planMainModelInstall,
-  planMainModelRemoval,
-} from "../../../tools/domain/formats/main-model-config.js";
-import { getAiToolConfig } from "../../../tools/domain/registry.js";
 import {
   AGENT_INSTALLATIONS_PATH,
   type AgentInstallationStore,
@@ -26,39 +16,23 @@ import {
   type MainModelInstallations,
 } from "../../domain/ports/agent-installation-store.js";
 import { assertProjectPathWithinRoot } from "../ownership/project-path-boundary.js";
-
-interface AgentTarget {
-  projectRoot: string;
-  host: AgentHost;
-  /** Targets the IDE's user configuration directory instead of the project. */
-  user?: UserAgentRoot;
-}
-
-interface AgentChange {
-  path: string;
-  content: string | null;
-}
-
-/** Where one host's agents, main settings and ownership registry live for a scope. */
-interface AgentLocation {
-  registryRoot: string;
-  /** Creates the registry root when the scope owns it. */
-  prepare?: () => Promise<void>;
-  agentPath(name: string): string;
-  settingsPath: string | null;
-  guard(path: string): Promise<void>;
-}
-
-/** The user's home, environment and AIDD configuration directory, for user-scoped agents. */
-export interface UserAgentRoot {
-  home: string;
-  env: EnvironmentReader;
-  configDir: string;
-}
+import {
+  type AgentLocation,
+  type AgentTarget,
+  agentsCapability,
+  resolveAgentLocation,
+} from "./agent-location.js";
+import {
+  type FileChange,
+  mainModelInstall,
+  mainModelRemovals,
+  readOptional,
+} from "./main-model-changes.js";
 
 /** A registry name maps to one file inside the agents directory, never a path. */
 const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
 
+/** Installs, refreshes and removes the bundled agents, owning only the files it wrote. */
 export class ManageAgentsUseCase {
   constructor(
     private readonly fs: FileReader & FileWriter,
@@ -71,8 +45,8 @@ export class ManageAgentsUseCase {
   async install(
     options: AgentTarget & { provider: AgentProvider; main?: boolean }
   ): Promise<number> {
-    const capability = this.capability(options.host);
-    const location = this.location(options);
+    const capability = agentsCapability(options.host);
+    const location = resolveAgentLocation(this.fs, options);
     if (options.main === true && location.settingsPath === null)
       throw new Error(`${options.host} has no main model setting AIDD can write.`);
     const entries = Object.entries(this.sources).map(([name, source]) => {
@@ -94,7 +68,7 @@ export class ManageAgentsUseCase {
       const owned = installed[options.host] ?? {};
       for (const entry of entries) await this.assertOwned(location, entry.path, owned[entry.name]);
       // Roles no longer bundled: remove their unmodified files.
-      const retired: AgentChange[] = [];
+      const retired: FileChange[] = [];
       for (const [name, hash] of Object.entries(owned)) {
         if (Object.hasOwn(this.sources, name)) continue;
         const path = location.agentPath(name);
@@ -105,75 +79,73 @@ export class ManageAgentsUseCase {
         entries.map(({ name, content }) => [name, this.hasher.hash(content)])
       );
       const mainModels = await this.store.loadMainModels(location.registryRoot);
-      const mainChanges: AgentChange[] = [];
-      if (options.main === true) {
-        const main = await this.mainModelInstall(options, location, mainModels);
-        if (main !== null) mainChanges.push(main);
-      }
+      const main =
+        options.main === true
+          ? await mainModelInstall(this.fs, options, location, mainModels)
+          : null;
       return this.save(
         location.registryRoot,
         installed,
         mainModels,
         [...entries, ...retired],
-        mainChanges
+        main === null ? [] : [main]
       );
     });
   }
 
-  /** Writes the provider's main model into the host settings, recording what it replaces. */
-  private async mainModelInstall(
-    options: AgentTarget & { provider: AgentProvider },
-    location: AgentLocation,
-    mainModels: MainModelInstallations
-  ): Promise<AgentChange | null> {
-    const target = mainModelTarget(options.host);
-    const path = location.settingsPath;
-    if (target === null || path === null) return null;
-    await location.guard(path);
-    if ((await this.fs.fileExists(path, false)) && !(await this.fs.fileExists(path)))
-      throw new Error(`Settings link is broken; fix it before installing agents: ${path}`);
-    const content = await this.readOptional(path);
-    for (const alternative of content === null ? (target.alternatives ?? []) : [])
-      if (await this.fs.fileExists(join(dirname(path), alternative)))
-        throw new Error(
-          `Settings live in ${alternative}; move them to ${basename(path)} before installing agents.`
-        );
-    try {
-      const plan = planMainModelInstall(
-        content,
-        target.format,
-        mainModelValues(options.host, options.provider),
-        mainModels[options.host]
+  async remove(options: AgentTarget): Promise<number> {
+    const location = resolveAgentLocation(this.fs, options);
+    await location.prepare?.();
+    return this.exclusively(location.registryRoot, async () => {
+      const installed = await this.load(location.registryRoot);
+      const entries = await this.removable(options, installed, options.host);
+      const mainModels = await this.store.loadMainModels(location.registryRoot);
+      const main = await mainModelRemovals(this.fs, options, mainModels, options.host);
+      delete installed[options.host];
+      delete mainModels[options.host];
+      return this.save(
+        location.registryRoot,
+        installed,
+        mainModels,
+        entries.map((path) => ({ path, content: null })),
+        main
       );
-      mainModels[options.host] = plan.record;
-      return { path, content: plan.content };
-    } catch (error) {
-      throw new Error(`Cannot set the main model in ${path}: ${(error as Error).message}`);
-    }
+    });
   }
 
-  /** Restores the settings each recorded main model replaced. */
-  private async mainModelRemovals(
-    target: Omit<AgentTarget, "host">,
-    mainModels: MainModelInstallations,
-    onlyHost?: AgentHost
-  ): Promise<AgentChange[]> {
-    const changes: AgentChange[] = [];
-    for (const [host, record] of Object.entries(mainModels)) {
-      if (onlyHost !== undefined && host !== onlyHost) continue;
-      const settings = mainModelTarget(host as AgentHost);
-      const location = this.location({ ...target, host: host as AgentHost });
-      if (settings === null || location.settingsPath === null || record === undefined) continue;
-      await location.guard(location.settingsPath);
-      const content = await this.readOptional(location.settingsPath);
-      const next = planMainModelRemoval(content, settings.format, record);
-      if (next !== content) changes.push({ path: location.settingsPath, content: next });
+  async preview(projectRoot: string): Promise<Array<{ toolId: AgentHost; fileCount: number }>> {
+    const installed = await this.load(projectRoot);
+    const tools: Array<{ toolId: AgentHost; fileCount: number }> = [];
+    for (const host of Object.keys(installed)) {
+      const entries = installed[host as AgentHost];
+      if (entries !== undefined)
+        tools.push({ toolId: host as AgentHost, fileCount: Object.keys(entries).length });
     }
-    return changes;
+    return tools;
   }
 
-  private async readOptional(path: string): Promise<string | null> {
-    return (await this.fs.fileExists(path)) ? this.fs.readFile(path) : null;
+  async assertRemovable(projectRoot: string): Promise<void> {
+    await this.removable({ projectRoot }, await this.load(projectRoot));
+  }
+
+  async removeAll(projectRoot: string, afterRemoval?: () => Promise<void>): Promise<number> {
+    return this.exclusively(projectRoot, async () => {
+      const entries = await this.removable({ projectRoot }, await this.load(projectRoot));
+      const main = await mainModelRemovals(
+        this.fs,
+        { projectRoot },
+        await this.store.loadMainModels(projectRoot)
+      );
+      const count = await this.save(
+        projectRoot,
+        {},
+        {},
+        entries.map((path) => ({ path, content: null })),
+        main
+      );
+      await afterRemoval?.();
+      return count;
+    });
   }
 
   private async exclusively<T>(root: string, action: () => Promise<T>): Promise<T> {
@@ -186,21 +158,21 @@ export class ManageAgentsUseCase {
     root: string,
     installed: AgentInstallations,
     mainModels: MainModelInstallations,
-    changes: readonly AgentChange[],
-    mainChanges: readonly AgentChange[] = []
+    changes: readonly FileChange[],
+    mainChanges: readonly FileChange[] = []
   ): Promise<number> {
-    const previous: AgentChange[] = [];
+    const previous: FileChange[] = [];
     const agentPaths = new Set(changes.map((change) => change.path));
     try {
       for (const change of [...changes, ...mainChanges]) {
-        const content = await this.readOptional(change.path);
+        const content = await readOptional(this.fs, change.path);
         if (content === change.content) continue;
         previous.push({ path: change.path, content });
         await this.write(change);
       }
       for (const registry of [AGENT_INSTALLATIONS_PATH, MAIN_MODEL_INSTALLATIONS_PATH]) {
         const path = join(root, registry);
-        previous.push({ path, content: await this.readOptional(path) });
+        previous.push({ path, content: await readOptional(this.fs, path) });
       }
       await this.store.save(root, installed);
       await this.store.saveMainModels(root, mainModels);
@@ -208,7 +180,8 @@ export class ManageAgentsUseCase {
     } catch (error) {
       const restored = await Promise.allSettled(
         previous.reverse().map(async (change) => {
-          if ((await this.readOptional(change.path)) !== change.content) await this.write(change);
+          if ((await readOptional(this.fs, change.path)) !== change.content)
+            await this.write(change);
         })
       );
       const failures = restored.filter((result) => result.status === "rejected");
@@ -222,7 +195,7 @@ export class ManageAgentsUseCase {
   }
 
   /** Writes through an existing link, so linked settings files stay linked. */
-  private async write({ path, content }: AgentChange): Promise<void> {
+  private async write({ path, content }: FileChange): Promise<void> {
     if (content !== null) {
       const target = (await this.fs.fileExists(path)) ? await this.fs.realpath(path) : path;
       await this.fs.writeFile(target, content);
@@ -232,94 +205,6 @@ export class ManageAgentsUseCase {
     }
   }
 
-  async remove(options: AgentTarget): Promise<number> {
-    const location = this.location(options);
-    await location.prepare?.();
-    return this.exclusively(location.registryRoot, async () => {
-      const installed = await this.load(location.registryRoot);
-      const entries = await this.removable(options, installed, options.host);
-      const mainModels = await this.store.loadMainModels(location.registryRoot);
-      const main = await this.mainModelRemovals(options, mainModels, options.host);
-      delete installed[options.host];
-      delete mainModels[options.host];
-      return this.save(
-        location.registryRoot,
-        installed,
-        mainModels,
-        entries.map((path) => ({ path, content: null })),
-        main
-      );
-    });
-  }
-
-  async preview(projectRoot: string): Promise<Array<{ toolId: AgentHost; fileCount: number }>> {
-    const installed = await this.load(projectRoot);
-    const tools: Array<{ toolId: AgentHost; fileCount: number }> = [];
-    for (const host of Object.keys(installed)) {
-      const entries = installed[host as AgentHost];
-      if (entries !== undefined)
-        tools.push({ toolId: host as AgentHost, fileCount: Object.keys(entries).length });
-    }
-    return tools;
-  }
-
-  async assertRemovable(projectRoot: string): Promise<void> {
-    await this.removable({ projectRoot }, await this.load(projectRoot));
-  }
-
-  async removeAll(projectRoot: string, afterRemoval?: () => Promise<void>): Promise<number> {
-    return this.exclusively(projectRoot, async () => {
-      const entries = await this.removable({ projectRoot }, await this.load(projectRoot));
-      const main = await this.mainModelRemovals(
-        { projectRoot },
-        await this.store.loadMainModels(projectRoot)
-      );
-      const count = await this.save(
-        projectRoot,
-        {},
-        {},
-        entries.map((path) => ({ path, content: null })),
-        main
-      );
-      await afterRemoval?.();
-      return count;
-    });
-  }
-
-  private capability(host: AgentHost): AgentsCapability {
-    return (getAiToolConfig(host).capabilities as HasAgents).agents;
-  }
-
-  private location(target: AgentTarget): AgentLocation {
-    const capability = this.capability(target.host);
-    const settings = mainModelTarget(target.host);
-    const file = (name: string) => {
-      const path = capability.buildInstallPath(`${name}.md`);
-      if (path === null) throw new Error(`Agent ${name} has no native install path.`);
-      return path;
-    };
-    const user = target.user;
-    if (user === undefined) {
-      const root = target.projectRoot;
-      return {
-        registryRoot: root,
-        agentPath: (name) => join(root, file(name)),
-        settingsPath: settings === null ? null : join(root, settings.path),
-        guard: (path) => assertProjectPathWithinRoot(this.fs, root, path),
-      };
-    }
-    const directory = capability.params.userDirectory?.(user.home, user.env);
-    if (directory === undefined) throw new Error(`${target.host} has no user-level agents.`);
-    const configDir = user.configDir;
-    return {
-      registryRoot: configDir,
-      prepare: () => this.fs.createDirectory(configDir),
-      agentPath: (name) => join(directory, "agents", basename(file(name))),
-      settingsPath: settings === null ? null : join(directory, settings.userPath),
-      guard: async () => {},
-    };
-  }
-
   private async load(root: string): Promise<AgentInstallations> {
     await assertProjectPathWithinRoot(this.fs, root, join(root, AGENT_INSTALLATIONS_PATH));
     const installed = await this.store.load(root);
@@ -351,7 +236,7 @@ export class ManageAgentsUseCase {
     const paths: string[] = [];
     for (const [host, entries] of Object.entries(installed)) {
       if (onlyHost !== undefined && host !== onlyHost) continue;
-      const location = this.location({ ...target, host: host as AgentHost });
+      const location = resolveAgentLocation(this.fs, { ...target, host: host as AgentHost });
       // A user directory resolved elsewhere than at install would drop the record unseen.
       const names = Object.keys(entries);
       if (target.user !== undefined && names.length > 0) {
diff --git a/cli/src/runtime/wiring/framework.ts b/cli/src/runtime/wiring/framework.ts
index d95740c32..ce3a0fcfb 100644
--- a/cli/src/runtime/wiring/framework.ts
+++ b/cli/src/runtime/wiring/framework.ts
@@ -10,10 +10,8 @@ import { MarketplaceAddUseCase } from "../../contexts/distribution/application/m
 import type { MarketplaceListUseCase } from "../../contexts/distribution/application/marketplace-list-use-case.js";
 import type { MarketplaceRefreshUseCase } from "../../contexts/distribution/application/marketplace-refresh-use-case.js";
 import type { MarketplaceRegisterFrameworkUseCase } from "../../contexts/distribution/application/marketplace-register-framework-use-case.js";
-import {
-  ManageAgentsUseCase,
-  type UserAgentRoot,
-} from "../../contexts/framework/application/agents/manage-agents-use-case.js";
+import type { UserAgentRoot } from "../../contexts/framework/application/agents/agent-location.js";
+import { ManageAgentsUseCase } from "../../contexts/framework/application/agents/manage-agents-use-case.js";
 import { CleanUserScopeUseCase } from "../../contexts/framework/application/clean/clean-user-scope-use-case.js";
 import { CleanUseCase } from "../../contexts/framework/application/clean-use-case.js";
 import { DoctorLayoutUseCase } from "../../contexts/framework/application/doctor/doctor-layout-use-case.js";