feat(codex)!: prefix sub-agent names add-* (closes #28)

Registrations become add-explorer/add-implementer/add-reviewer/
add-test-writer/add-verify — no more collision risk in the global
~/.codex/agents/ namespace. Installer cleans up ADD-owned legacy names
(manifest-sha or marker gated), preserves user-owned files with a warning.
Explorer role rewritten as a generic read-only discovery agent (was
mispointing at add-docs/SKILL.md). Smoke asserts the exact prefixed set.
Migration hop lands with the v0.11.0 release.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: MountainUnicorn

CHANGELOG.md

@@ -6,6 +6,10 @@ For commit-level detail see `git log`.
 
 ## [Unreleased]
 
+### Changed
+
+- **Codex sub-agent names prefixed `add-*` (#28)** — `explorer`/`implementer`/`reviewer`/`test-writer`/`verify` registrations become `add-explorer` etc., ending collision risk with user or built-in agents in the global `~/.codex/agents/` namespace. The installer removes ADD-owned legacy-named TOMLs (prior-manifest sha or `# ADD sub-agent` marker) and warns-but-preserves user-owned files (16-case suite). The explorer role no longer misappropriates the docs skill as its role definition. Claude-side role vocabulary is unchanged. Codex users: re-run the installer; a migration hop will accompany the v0.11.0 release.
+
 ### Added
 
 - **`/add:init --defaults` (#23)** — true non-interactive init: zero questions, every value derived (name from CWD, language from manifest files) or defaulted (poc maturity, local-only environments, autonomous mode). Never overwrites an existing config. Both install smokes now exercise this real headless path instead of smuggling interview answers into the prompt.

dist/codex/.codex/agents/add-explorer.toml

@@ -0,0 +1,16 @@
+# ADD sub-agent — add-explorer
+#
+# Broad, lower-stakes codebase sweeps (architecture discovery, dependency
+# mapping, pattern detection). Used by /add-docs and /add-optimize in their
+# discovery phases. Read-only by design.
+# See spec AC-015..AC-020.
+
+name = "add-explorer"
+description = "Broad, read-only codebase exploration. Used for discovery, mapping, and pattern detection."
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+# Codex ≥0.14x agent-role schema (issue #24): prompt_skill was removed;
+# developer_instructions is the required behavioral field. No dedicated
+# explorer skill exists (#28) — the role is defined inline as a generic
+# read-only discovery agent.
+developer_instructions = "You are ADD's read-only discovery sub-agent. Explore the codebase broadly per the task you were spawned with: map architecture, trace dependencies, and detect patterns and conventions. Report findings concisely with concrete file paths. Do not modify, create, or delete any files — honor the read-only sandbox_mode declared for this role."

runtimes/codex/agents/implementer.toml …codex/.codex/agents/add-implementer.tomlruntimes/codex/agents/implementer.toml renamed to dist/codex/.codex/agents/add-implementer.toml runtimes/codex/agents/implementer.toml renamed to dist/codex/.codex/agents/add-implementer.toml

@@ -1,10 +1,10 @@
-# ADD sub-agent — implementer (TDD GREEN phase)
+# ADD sub-agent — add-implementer (TDD GREEN phase)
 #
 # Behavioral source: core/skills/implementer/SKILL.md
 # Minimal implementation to make failing tests pass. Does not write tests.
 # See spec AC-015..AC-020.
 
-name = "implementer"
+name = "add-implementer"
 description = "Writes minimal implementation to pass failing tests (TDD GREEN phase)."
 model_reasoning_effort = "high"
 sandbox_mode = "workspace-write"

runtimes/codex/agents/reviewer.toml …st/codex/.codex/agents/add-reviewer.tomlruntimes/codex/agents/reviewer.toml renamed to dist/codex/.codex/agents/add-reviewer.toml runtimes/codex/agents/reviewer.toml renamed to dist/codex/.codex/agents/add-reviewer.toml

@@ -1,11 +1,11 @@
-# ADD sub-agent — reviewer
+# ADD sub-agent — add-reviewer
 #
 # Behavioral source: core/skills/reviewer/SKILL.md
 # Read-only: inspects working-tree changes against the driving spec, produces
 # a structured review report. Does not modify files.
 # See spec AC-015..AC-020.
 
-name = "reviewer"
+name = "add-reviewer"
 description = "Reviews changes against spec acceptance criteria. Read-only."
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"

runtimes/codex/agents/test-writer.toml …codex/.codex/agents/add-test-writer.tomlruntimes/codex/agents/test-writer.toml renamed to dist/codex/.codex/agents/add-test-writer.toml runtimes/codex/agents/test-writer.toml renamed to dist/codex/.codex/agents/add-test-writer.toml

@@ -1,10 +1,10 @@
-# ADD sub-agent — test-writer (TDD RED phase)
+# ADD sub-agent — add-test-writer (TDD RED phase)
 #
 # Behavioral source: core/skills/test-writer/SKILL.md
 # Invoked via add-tdd-cycle orchestration in Codex sub-agent mode.
 # See spec AC-015..AC-020.
 
-name = "test-writer"
+name = "add-test-writer"
 description = "Writes failing tests from a spec (TDD RED phase). Does not implement."
 model_reasoning_effort = "high"
 sandbox_mode = "workspace-write"

dist/codex/.codex/agents/verify.toml dist/codex/.codex/agents/add-verify.tomldist/codex/.codex/agents/verify.toml renamed to dist/codex/.codex/agents/add-verify.toml

@@ -1,11 +1,11 @@
-# ADD sub-agent — verify
+# ADD sub-agent — add-verify
 #
 # Behavioral source: core/skills/verify/SKILL.md
 # Runs ADD's quality gates — lint, types, tests, coverage, spec compliance —
 # and produces a pass/fail report. Executes checks (may write coverage/build
 # artifacts) but does not modify source. See spec AC-015..AC-020.
 
-name = "verify"
+name = "add-verify"
 description = "Runs quality gates — lint, types, tests, coverage, spec compliance. Produces a pass/fail report."
 model_reasoning_effort = "high"
 sandbox_mode = "workspace-write"

dist/codex/.codex/agents/explorer.toml

@@ -68,11 +68,11 @@ Before executing any ADD skill, read `~/.codex/add/knowledge/global.md` (Tier-1
 
 Registered in `.codex/agents/`. Active when `[features] collab = true` (set in emitted `.codex/config.toml`).
 
-- `test-writer` — TDD RED phase (workspace-write, high reasoning)
-- `implementer` — TDD GREEN phase (workspace-write, high reasoning)
-- `reviewer` — spec-compliance review (read-only, high reasoning)
-- `verify` — quality gates: lint/types/tests/coverage/spec (workspace-write, high reasoning)
-- `explorer` — broad codebase discovery (read-only, medium reasoning)
+- `add-test-writer` — TDD RED phase (workspace-write, high reasoning)
+- `add-implementer` — TDD GREEN phase (workspace-write, high reasoning)
+- `add-reviewer` — spec-compliance review (read-only, high reasoning)
+- `add-verify` — quality gates: lint/types/tests/coverage/spec (workspace-write, high reasoning)
+- `add-explorer` — broad codebase discovery (read-only, medium reasoning)
 
 ## Hooks
 

dist/codex/AGENTS.md

@@ -39,11 +39,11 @@ skills = [
 ]
 
 agents = [
-  ".codex/agents/explorer.toml",
-  ".codex/agents/implementer.toml",
-  ".codex/agents/reviewer.toml",
-  ".codex/agents/test-writer.toml",
-  ".codex/agents/verify.toml",
+  ".codex/agents/add-explorer.toml",
+  ".codex/agents/add-implementer.toml",
+  ".codex/agents/add-reviewer.toml",
+  ".codex/agents/add-test-writer.toml",
+  ".codex/agents/add-verify.toml",
 ]
 
 hooks = ".codex/hooks.json"

dist/codex/plugin.toml

@@ -19,7 +19,7 @@ expected to obey; no mechanical backstop. **Advisory**: documentation/patterns o
 | Hooks (learnings filter, CHANGELOG, autofix) | Enforced (PreToolUse / SessionStart) | Agent-followed→Enforced only if user enables `[features] codex_hooks = true`; hook stderr not surfaced to the agent (F-012) | hooks.json emitted in the ≥0.14x schema since v0.10.1 (#24); merge is manual when one already exists |
 | Prompt-injection scanning | Enforced detection, warn-only response (PostToolUse scanner emits ADD-SEC warnings + audit events at `.add/security/injection-events.jsonl`; never blocks by design) | Advisory (pattern catalog ships at `~/.codex/add/security/`; no scanner hook, no audit events) | Per adapter.yaml truth-pass (v0.9.8); Codex parity revisits v1.1 |
 | Secrets scanning / redaction | Enforced in hook pipeline (`lib/scan-secrets.sh` via scanner + learnings filter) | Advisory (library + catalog ship; skills reference them, no hook auto-registration) | |
-| Sub-agents (test-writer, implementer, reviewer, explorer) | Enforced (Task tool dispatch) | Agent-followed (TOML defs; requires `[features] collab = true`; `developer_instructions` load the role's skill) | TOMLs emitted in the ≥0.14x schema since v0.10.1 (#24 — `prompt_skill` era was silently ignored); verified accepted by CLI 0.144.5 |
+| Sub-agents (`add-test-writer`, `add-implementer`, `add-reviewer`, `add-verify`, `add-explorer`) | Enforced (Task tool dispatch; Claude role vocabulary stays unprefixed) | Agent-followed (TOML defs; requires `[features] collab = true`; `developer_instructions` load the role's skill) | TOMLs emitted in the ≥0.14x schema since v0.10.1 (#24 — `prompt_skill` era was silently ignored); verified accepted by CLI 0.144.5. Registered names prefixed `add-*` since v0.11.0 (#28); installer removes ADD-owned legacy names |
 | Learnings persistence + active view | Enforced (`filter-learnings.sh` hook auto-registered) | Shipped but NOT auto-registered | Codex user must wire the hook manually |
 | Telemetry JSONL emission | Spec'd; emission verification tracked as D6 (see milestone) | — | Several PRD metrics depend on this |
 | Migrations (`migrations.json` hop chain) | Enforced via `/add:version` | Agent-followed via `/add-version` | Chain continuity checked by release-evidence script (v0.10.0) |