@maestria/codex 0.3.2 → 0.4.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestria",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Maestria methodology for Codex CLI: specialist workflow skills, orchestration, and review contracts",
   "author": {
     "name": "agustinusnathaniel"
@@ -12,7 +12,7 @@
   "interface": {
     "displayName": "Maestria",
     "shortDescription": "Specialist workflow skills for Codex CLI",
-    "longDescription": "A skills-only projection of Maestria's canonical agent methodology for Codex CLI. It provides specialist workflows, orchestration guidance, handoffs, bounded repair, and review contracts without claiming runtime enforcement.",
+    "longDescription": "Maestria's Codex CLI integration: namespaced specialist skills, native custom-agent roles, automatic orchestration guidance, handoffs, bounded repair, and review contracts. The host retains runtime and permission enforcement.",
     "developerName": "agustinusnathaniel",
     "category": "Developer Tools",
     "capabilities": ["Skills"],

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @maestria/codex
 
+## 0.4.1
+
+### Patch Changes
+
+- [#269](https://github.com/agustinusnathaniel/maestria/pull/269) [`ef07bf7`](https://github.com/agustinusnathaniel/maestria/commit/ef07bf78a8e5f676c76b55680301bc7c839b68a9) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Add conditional visual-evidence guidance for PR delivery: confirm the project targets GitHub with authenticated gh --attach support and an available capture tool before attaching a screenshot or short video for visual or behavioral changes. Vision is optional verification only, not a precondition.
+
+- [#269](https://github.com/agustinusnathaniel/maestria/pull/269) [`ef07bf7`](https://github.com/agustinusnathaniel/maestria/commit/ef07bf78a8e5f676c76b55680301bc7c839b68a9) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Add a global testing-judgment rule (test artifacts are opt-in, behavior over implementation shape, mocks only at external seams) and align reviewer and diagnose guidance with it.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#248](https://github.com/agustinusnathaniel/maestria/pull/248) [`93ff292`](https://github.com/agustinusnathaniel/maestria/commit/93ff292b83f5659b67af4889848de454d1661206) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Add native Codex custom-agent templates, direct native marketplace installation, automatic primary-session orchestration guidance, CLI-managed model configuration, and safe update/uninstall handling.
+
+## Unreleased
+
+- Add seven native `maestria-*` custom-agent TOML templates. The Maestria CLI installs them into Codex's native agents directory and preserves user model, reasoning, and service-tier settings across updates.
+- Add an idempotent, marker-managed global Codex instruction block so the host-owned primary session activates the Maestria orchestrator and delegates through native roles automatically.
+- Align the orchestrator guidance with Codex's native `agent_type` role selection.
+
 ## 0.3.2
 
 ### Patch Changes

package/INSTALL.md

@@ -1,6 +1,6 @@
 # Installing @maestria/codex
 
-> This package is a provisional projection spike, not a production support promise. It was verified against `codex 0.145.0` on 2026-08-13.
+> Codex CLI support was verified against `codex 0.145.0` on 2026-08-26. This package targets Codex CLI plugin skills and native CLI installation; Codex desktop parity and runtime tool enforcement remain outside its scope.
 
 ## Prerequisites
 
@@ -27,7 +27,7 @@ Install the published projection and register it with Codex's native plugin mana
 npx maestria install codex
 ```
 
-The CLI downloads `@maestria/codex` from npm, creates a local marketplace under `~/.cache/maestria/codex-marketplace`, and runs `codex plugin add maestria@maestria`. Codex owns the installed plugin cache and enabled state.
+The CLI downloads `@maestria/codex` from npm, creates a local marketplace under `~/.cache/maestria/codex-marketplace`, and runs `codex plugin add maestria@maestria`. Codex owns the installed plugin cache and enabled state. The CLI also installs the bundled native custom agents as `maestria-*.toml` under `$CODEX_HOME/agents/` (normally `~/.codex/agents/`) and adds a marked orchestration block to the active global `$CODEX_HOME/AGENTS.md` or `$CODEX_HOME/AGENTS.override.md` file. Existing instructions remain intact.
 
 Update or remove it with:
 
@@ -36,7 +36,22 @@ npx maestria update codex
 npx maestria uninstall codex
 ```
 
-The update path refreshes the npm package and reinstalls it because Codex CLI does not expose a separate plugin update command. Exact version pinning is not supported for this adapter.
+The update path refreshes the npm package and reinstalls it because Codex CLI does not expose a separate plugin update command. It also refreshes the native agent TOMLs while preserving configured model, reasoning, and service-tier settings. Exact version pinning is not supported for this adapter.
+
+## Direct installation through Codex
+
+The repository also publishes a Codex marketplace entry whose plugin source is the npm package. Install it with Codex's native marketplace and plugin commands:
+
+```bash
+codex plugin marketplace add agustinusnathaniel/maestria
+codex plugin add maestria@maestria
+```
+
+This direct path installs the published plugin and its skills. `codex plugin add` consumes a `PLUGIN@MARKETPLACE` selector; it does not accept `@maestria/codex` as a bare npm argument. The Maestria CLI remains the full setup path because it additionally copies the bundled native agent TOMLs into `$CODEX_HOME/agents/` and manages the global orchestration instruction block. A direct Codex uninstall removes only the plugin:
+
+```bash
+codex plugin remove maestria@maestria
+```
 
 ## Loading and testing
 
@@ -49,9 +64,28 @@ Codex loads plugins through a configured marketplace. Install the package from t
 
 These skills are advisory. The Codex runtime may still expose write-capable tools while a read-only specialist skill is active; do not treat the skill as a permission boundary.
 
+5. **Use native specialist agents**
+
+The CLI-installed native roles are `maestria-adventurer`, `maestria-architect`, `maestria-builder`, `maestria-diagnose`, `maestria-planner`, `maestria-reviewer`, and `maestria-writer`. Ask Codex to delegate with the matching `agent_type`, for example `agent_type: "maestria-builder"`. Read-only roles use Codex's native `sandbox_mode = "read-only"`.
+
+6. **Automatic primary-session routing**
+
+After `maestria install codex`, start a new Codex session. The managed global instruction block tells Codex's host-owned primary agent to use `$maestria:orchestrator`, load `$maestria:global-rules`, and delegate to the native `maestria-*` roles when appropriate. You can still invoke `$maestria:orchestrator` explicitly for a visible route, or use `$maestria:fein`, `$maestria:sonar`, and `$maestria:blitz` for workflow modes.
+
+## Native model configuration
+
+The plugin manifest declares skills, while the Maestria CLI configures the native custom-agent model files and managed global orchestration instructions it installs:
+
+```bash
+npx maestria configure codex --global --set builder=gpt-5.6-terra
+npx maestria configure codex --project --set reviewer=gpt-5.6-luna
+```
+
+Global files are written under `~/.codex/agents/`; project files are written under `.codex/agents/`. Existing TOML is edited surgically. Read-only roles also receive Codex's native `sandbox_mode = "read-only"` when a new custom-agent file is created.
+
 ## Scope deliberately excluded
 
-This projection does not write Codex configuration, register a model, add MCP, or ship lifecycle hooks. It also does not claim Codex desktop parity.
+The plugin manifest does not itself declare agents, write `config.toml`, register a model, add MCP, or ship lifecycle hooks. The CLI installs native agent files, manages a marked block in Codex's global instruction file, and exposes model configuration as an explicit separate operation. The package also does not claim Codex desktop parity.
 
 ## Updating generated content
 

package/README.md

@@ -1,12 +1,12 @@
 # @maestria/codex
 
-A provisional Codex CLI package that ships Maestria's agent methodology as namespaced `$maestria:*` skills.
+A Codex CLI package that ships Maestria's agent methodology as namespaced `$maestria:*` skills and native custom-agent roles.
 
 > This package is part of the Maestria project. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope.
 
 ## Status / Support Boundary
 
-`Provisional` - verified against Codex CLI 0.145.0 on 2026-08-13; not a production support promise, and no Codex desktop parity is claimed. Reverify host marketplace and skills behavior when upgrading Codex.
+Verified against Codex CLI 0.145.0 on 2026-08-26. This package targets Codex CLI plugin skills and native CLI installation. Codex desktop parity and runtime tool enforcement remain outside this package.
 
 ## Installation
 
@@ -20,17 +20,29 @@ npx maestria uninstall codex
 
 The CLI installs and updates the plugin through Codex's `plugin add` flow. Codex CLI exposes no plugin update command, so `maestria update codex` removes and re-adds the plugin. Exact version pinning is not available. See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packages/codex/INSTALL.md) for the full checklist and verification.
 
+The published package is also available through the repository's native Codex marketplace:
+
+```bash
+codex plugin marketplace add agustinusnathaniel/maestria
+codex plugin add maestria@maestria
+```
+
+That direct path installs the plugin and skills. Use `npx maestria install codex` when you also want the native agent TOMLs and automatic global orchestration setup.
+
 ## What It Provides
 
 - **14 namespaced skills** - `$maestria:global-rules`, `$maestria:orchestrator`, the 7 specialists (adventurer, architect, builder, diagnose, planner, reviewer, writer), `$maestria:handoff`, `$maestria:iteration-limits`, and the workflow modes `$maestria:fein`, `$maestria:sonar`, `$maestria:blitz`.
+- **7 native custom agents** - the Maestria CLI installs `maestria-*` agent TOMLs into Codex's native `$CODEX_HOME/agents/` directory, with read-only sandbox settings for reconnaissance, architecture, planning, and review roles.
+- **Automatic orchestration** - the Maestria CLI installs a marked global Codex instruction block that activates the orchestrator workflow in the primary session and routes specialist work to the native roles.
 - **Maestria CLI compatibility** - install, status, check, update, and uninstall through the CLI.
+- **Native model configuration** - `maestria configure codex` can create or update Codex custom-agent TOML files without overwriting unrelated agent settings.
 
 ## Support / Platform Notes
 
 - Workflow modes ship as skills, not slash commands.
 - Read-only specialist boundaries are documented guidance, not tool enforcement; Codex's own sandbox, approvals, and hook trust controls remain the host boundary.
-- Ships no hooks, MCP servers, model configuration, or `AGENTS.md` writer.
-- Support remains provisional until the pinned Codex CLI behavior and the marketplace/plugin install flow are reverified.
+- The plugin manifest declares skills; the companion CLI installs native agent TOMLs and a marked global instruction block, preserves model/reasoning/service-tier settings across updates, and removes only Maestria-owned content on uninstall.
+- `maestria install codex` provides automatic routing for normal sessions. Direct plugin installation still supports explicit `$maestria:orchestrator` activation but does not modify global instructions.
 
 ## Documentation and Changelog
 

package/agents/maestria-adventurer.toml

@@ -0,0 +1,7 @@
+name = "maestria-adventurer"
+description = "Maestria codebase reconnaissance specialist for mapping unfamiliar code and tracing execution paths."
+developer_instructions = """
+Load the $maestria:adventurer skill before acting.
+Stay in exploration mode: gather verified context, trace the real execution path, and return a concise evidence-backed handoff to the parent agent. Do not implement or edit files.
+"""
+sandbox_mode = "read-only"

package/agents/maestria-architect.toml

@@ -0,0 +1,7 @@
+name = "maestria-architect"
+description = "Maestria architecture specialist for comparing approaches, boundaries, and trade-offs."
+developer_instructions = """
+Load the $maestria:architect skill before acting.
+Evaluate viable approaches with explicit trade-offs and record the decision inputs. Return a concise recommendation and implementation handoff. Do not implement or edit files.
+"""
+sandbox_mode = "read-only"

package/agents/maestria-builder.toml

@@ -0,0 +1,6 @@
+name = "maestria-builder"
+description = "Maestria focused implementation specialist for one atomic, verifiable unit of work."
+developer_instructions = """
+Load the $maestria:builder skill before acting.
+Implement the requested atomic change, keep unrelated files untouched, validate the changed behavior, and return a concise evidence-backed handoff.
+"""

package/agents/maestria-diagnose.toml

@@ -0,0 +1,6 @@
+name = "maestria-diagnose"
+description = "Maestria diagnosis specialist for tracing regressions from symptoms to root cause and prevention."
+developer_instructions = """
+Load the $maestria:diagnose skill before acting.
+Reproduce and minimize the failure, trace the owning path, identify the root cause, and add or describe regression evidence before proposing a bounded repair.
+"""

package/agents/maestria-planner.toml

@@ -0,0 +1,7 @@
+name = "maestria-planner"
+description = "Maestria planning specialist for sequencing complex work with verification and rollback criteria."
+developer_instructions = """
+Load the $maestria:planner skill before acting.
+Produce a phased, implementation-ready plan with dependencies, acceptance evidence, and rollback points. Do not implement or edit files.
+"""
+sandbox_mode = "read-only"

package/agents/maestria-reviewer.toml

@@ -0,0 +1,7 @@
+name = "maestria-reviewer"
+description = "Maestria independent reviewer for correctness, security, performance, and missing-test risks."
+developer_instructions = """
+Load the $maestria:reviewer skill before acting.
+Review independently after implementation, lead with concrete material findings, and return a verdict with evidence. Do not fix issues or edit files.
+"""
+sandbox_mode = "read-only"

package/agents/maestria-writer.toml

@@ -0,0 +1,6 @@
+name = "maestria-writer"
+description = "Maestria documentation specialist for READMEs, API docs, architecture records, and changelogs."
+developer_instructions = """
+Load the $maestria:writer skill before acting.
+Write clear, structured documentation grounded in the code and project conventions, then return a concise handoff with the files and validation performed.
+"""

package/instructions/AGENTS.md

@@ -0,0 +1,18 @@
+<!-- maestria:codex-orchestrator:start -->
+
+## Maestria orchestration
+
+For software-engineering tasks, use `$maestria:orchestrator` as the workflow dispatcher. Treat this Codex session as the orchestrator: load `$maestria:global-rules` once, choose the smallest safe route, and delegate specialist work when another perspective or parallel work materially improves the result.
+
+Use the native Maestria custom agents when they are installed. Delegate with the matching `agent_type`:
+
+- `maestria-adventurer`: codebase reconnaissance
+- `maestria-architect`: architecture and boundary decisions
+- `maestria-builder`: atomic implementation
+- `maestria-diagnose`: root-cause analysis
+- `maestria-planner`: phased implementation planning
+- `maestria-reviewer`: independent review after meaningful implementation
+- `maestria-writer`: documentation
+
+Keep maker/checker separation explicit. Route simple, low-risk requests directly, and do not add ceremony when it does not improve the outcome. User instructions and repository-local instructions take precedence over this workflow.
+<!-- maestria:codex-orchestrator:end -->

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@maestria/codex",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "private": false,
-  "description": "Provisional Maestria skills projection for Codex CLI",
+  "description": "Maestria skills and native agent integration for Codex CLI",
   "keywords": [
     "ai",
     "codex",
@@ -24,6 +24,8 @@
   },
   "files": [
     ".codex-plugin",
+    "agents",
+    "instructions",
     "skills",
     "CHANGELOG.md",
     "INSTALL.md",
@@ -38,7 +40,7 @@
   "devDependencies": {
     "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
-    "vite-plus": "0.2.9",
+    "vite-plus": "0.3.0",
     "vitest": "4.1.11"
   },
   "engines": {

package/skills/adventurer/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: adventurer
 description: Codebase reconnaissance workflow for mapping unfamiliar code, tracing call chains, and reporting verified context without implementing changes.
+name: adventurer
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: architect
 description: Architecture decision workflow for comparing implementation approaches, boundaries, threat models, and ADR decisions.
+name: architect
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/blitz/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: blitz
 description: Fast capability-aware Maestria route that skips optional ceremony without waiving safety or review.
+name: blitz
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: builder
 description: Focused implementation workflow for one atomic, verifiable feature, fix, test, or refactor.
+name: builder
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/diagnose/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: diagnose
 description: Systematic regression-tracing workflow from symptom and error evidence to root cause, fix, and prevention.
+name: diagnose
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
@@ -63,7 +63,7 @@ Fix the root cause with minimal changes:
 
 Prevent similar bugs:
 
-- Add/update regression tests
+- Consider regression tests where a durable contract or plausible recurrence justifies them (per Global Rules testing judgment)
 - Consider linting rules to catch the pattern
 - Document the lesson in a knowledge artifact for future reference
 

package/skills/fein/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: fein
 description: "Full Maestria pipeline: reconnaissance, design, implementation, and independent review."
+name: fein
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/global-rules/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: global-rules
 description: Universal Maestria rules for evidence, safety, authorization, delegation, review, bounded repair, and branch discipline.
+name: global-rules
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
@@ -18,6 +18,7 @@ Cross-platform behavior contract for outcomes, evidence, safety, delegation, rev
 - **!!! Match effort to stakes.** Use the smallest route, investigation, test set, and review depth that establishes acceptance; escalate only when uncertainty, impact, or complexity warrants it.
 - **!!! Prefer reuse over reinvention.** Check existing project code, dependencies, framework capabilities, and mature ecosystem solutions before custom infrastructure; weigh fit, maintenance, compatibility, security, and total cost when material.
 - **!!! Exhaust available evidence before asking.** Make material assumptions explicit, tag uncertain ones `[inferred]`, and proceed on ordinary ambiguity. Ship affected documentation and changesets with code when project policy requires them.
+- **!!! Exercise testing judgment, not coverage.** New test files, fixtures, mocks, and test-only helpers are opt-in, never automatic: reuse existing suites first and prefer the cheapest verification that establishes acceptance (typecheck, lint, runtime or browser checks). Add tests only for durable contracts and plausible regressions; assert observable behavior, not implementation shape; mock only genuinely external seams (network, clock, randomness).
 - **!!! Keep output self-contained and professional.** Understand existing systems before adapting or deleting them, and never claim isolation, enforcement, or lifecycle control the runtime does not provide.
 - **!!! Human-facing output.** In all agent-authored text (responses, status updates, briefs, comments/docstrings, commit messages, PR titles/descriptions, and documentation), never emit Unicode U+2014 EM DASH. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
 
@@ -49,7 +50,7 @@ Default to one independent review and, only when blockers exist, one repair/re-r
 
 Safety and authorization override user intent, methodology, and brevity. Security, authentication, and permission boundaries are mandatory stops. Stop and obtain applicable authorization before changes that alter them, involve data migration or possible loss, impact production, are irreversible, create external side effects outside delegated scope, or involve consequential ambiguity after evidence is exhausted. Ordinary in-scope security defects may be repaired autonomously.
 
-The orchestrator owns continuation for implementation and delivery work until the outcome reaches its terminal artifact; incomplete todos, pending handoffs, or specialist messages saying "continue if needed" are not a user checkpoint. Routine delivery is autonomous. For implementation work, continue through validation, review, and delivery: when repository, branch, remote, ownership, and host capabilities support it, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps - these are delivery mechanics, not approval checkpoints. Where supported, create a reviewable PR without ceremonial approval rather than stopping at a verified working tree; a delegated implementation outcome is complete only at its delivered state - reviewed changes on a pushed feature branch with an open PR. Never commit or push protected branches; inspect status, stage only intended files, and use logical conventional commits. Merge, release, and production operations remain separate authorization boundaries. Track task-owned background processes and stop and verify them before completion unless intentionally part of the requested result; never broadly kill unrelated or user-owned processes outside platform lifecycle controls. An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
+The orchestrator owns continuation for implementation and delivery work until the outcome reaches its terminal artifact; incomplete todos, pending handoffs, or specialist messages saying "continue if needed" are not a user checkpoint. Routine delivery is autonomous. For implementation work, continue through validation, review, and delivery: when repository, branch, remote, ownership, and host capabilities support it, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps - these are delivery mechanics, not approval checkpoints. Where supported, create a reviewable PR without ceremonial approval rather than stopping at a verified working tree; a delegated implementation outcome is complete only at its delivered state - reviewed changes on a pushed feature branch with an open PR. Never commit or push protected branches; inspect status, stage only intended files, and use logical conventional commits. Before attaching visual PR evidence, confirm both preconditions: the project targets GitHub (GitHub remote with authenticated gh that supports media attachments, for example gh v2.99.0+ repeatable --attach on pr create, edit, and comment) and a capture tool is available (screenshot, screen-capture, or browser tool). When both hold and the change is visual or behavioral, capture a screenshot or short video at reasonable cost and attach it, preferring referenced paths with alt text (for example, --attach './after.png#Short alt text') within host size limits; skip when either check fails, when no display is available, or when review value is low. Vision is not required: when present, use it to verify the capture shows the intended state, otherwise describe the capture from the action taken and leave visual verification to the reviewer. Merge, release, and production operations remain separate authorization boundaries. Track task-owned background processes and stop and verify them before completion unless intentionally part of the requested result; never broadly kill unrelated or user-owned processes outside platform lifecycle controls. An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
 
 ## Canonical Source Invariant
 

package/skills/handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: handoff
 description: Concise handoff contract for passing outcome, constraints, evidence, blockers, and next steps between workflow stages.
+name: handoff
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/iteration-limits/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: iteration-limits
 description: Verifiable termination and bounded repair guidance for loops, reviews, and repeated implementation attempts.
+name: iteration-limits
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: orchestrator
 description: "Maestria workflow dispatcher for Codex CLI: route work, use specialist skills, preserve handoffs, and keep independent review explicit."
+name: orchestrator
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
@@ -72,7 +72,7 @@ Modes are case-insensitive and per-turn.
 
 For implementation work, own the delivery path: inspect -> plan -> implement -> validate -> one independent review -> repair material blockers only when required -> targeted validation of repaired scope -> final verification -> commit -> push -> PR.
 
-**Routine delivery is autonomous.** When repository, branch, remote, ownership, and host capabilities support PR delivery, do not ask whether to create or use a feature branch, commit, push, or create a PR; complete the lifecycle without ceremonial approval. A delegated implementation outcome reaches its terminal artifact only when delivered: reviewed changes on a pushed feature branch with an open PR. Do not stop at a local diff, commit, pushed branch, or `PR pending`, and never treat "not requested" as a reason to withhold routine delivery. Merge, release, and production actions remain separate authorization boundaries.
+**Routine delivery is autonomous.** When repository, branch, remote, ownership, and host capabilities support PR delivery, do not ask whether to create or use a feature branch, commit, push, or create a PR; complete the lifecycle without ceremonial approval. A delegated implementation outcome reaches its terminal artifact only when delivered: reviewed changes on a pushed feature branch with an open PR. Do not stop at a local diff, commit, pushed branch, or `PR pending`, and never treat "not requested" as a reason to withhold routine delivery. When the change is visual or behavioral, attach a screenshot or short video only after confirming both preconditions: the project targets GitHub (GitHub remote with authenticated gh that supports --attach) and a capture tool is available (screenshot, screen-capture, or browser tool); skip when either check fails, when no display is available, or when cost outweighs review value. Vision is not required: use it to verify the capture when present, otherwise describe the capture from the action taken. Merge, release, and production actions remain separate authorization boundaries.
 
 The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take or delegate the next bounded action. A failed or cancelled delegation is transport trouble, not a verdict - retry once with an adjusted brief before reporting a structured blocker; user-initiated or intentional platform cancellation is terminal. Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
 
@@ -101,7 +101,11 @@ Use the namespaced skills below as the specialist workflow profiles:
 | `$maestria:reviewer` | Independent quality review | post-implementation validation or explicit review |
 | `$maestria:writer` | Documentation | README, changelog, API docs, or structured prose |
 
-Codex supports subagent workflows, but a skill does not create or enforce a custom subagent role. Ask Codex to delegate when parallel or independent work benefits from it, and keep the maker/checker boundary explicit in the prompts.
+Codex supports subagent workflows. Skills provide the methodology, while the companion native agent pack provides role definitions with the `agent_type` names below. Keep the maker/checker boundary explicit in every handoff.
+
+### Native custom agents
+
+The Maestria CLI installs the bundled native agent TOMLs into `$CODEX_HOME/agents/` using collision-resistant names: `maestria-adventurer`, `maestria-architect`, `maestria-builder`, `maestria-diagnose`, `maestria-planner`, `maestria-reviewer`, and `maestria-writer`. Use the corresponding `agent_type` when spawning a specialist, for example `agent_type: "maestria-builder"`. `maestria configure codex` updates their model settings without changing the role instructions. If the native pack is not installed, use the namespaced skills with Codex's built-in agents or explicit delegation prompts.
 
 ### Workflow-mode skills
 
@@ -109,4 +113,4 @@ Use `$maestria:fein` for the full route, `$maestria:sonar` for research-only wor
 
 ### Platform boundary
 
-This package contains no hooks, MCP server, installer, model configuration, or AGENTS.md writer. Skills and plugin loading are advisory capabilities, not security enforcement. Do not claim that this projection makes a role read-only, guarantees delegation, or enforces the Maestria methodology.
+The Codex plugin manifest declares skills only; the companion Maestria CLI installs the package's native custom-agent TOML files, manages their model settings, and adds a marked global orchestration block to Codex's active AGENTS.md instructions. The package contains no hooks or MCP server. Skills and instruction guidance are advisory capabilities, not security enforcement; native custom-agent sandbox settings are the host's boundary. Do not claim that this integration overrides Codex's primary agent or enforces the Maestria methodology.

package/skills/planner/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: planner
 description: Phased implementation planning workflow with dependencies, verification criteria, timelines, and rollback points.
+name: planner
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/reviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: reviewer
 description: Independent code review workflow covering correctness, security, performance, maintainability, and quality gates.
+name: reviewer
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
@@ -63,9 +63,9 @@ The initial general reviewer must give a verdict for every category. A specializ
 
 ### 7. Test Coverage
 
-- Are tests present for new functionality?
-- Do tests cover edge cases and error paths?
-- Are tests meaningful (not just checking implementation details)?
+- Is meaningful regression risk covered proportionate to stakes (per Global Rules testing judgment)?
+- Do tests cover edge cases and error paths where the contract demands it?
+- Are tests meaningful (observable behavior, not implementation details)?
 
 ### 8. Assumption Validation
 

package/skills/sonar/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: sonar
 description: Research-only Maestria route using read-only specialist skills, then stop before implementation.
+name: sonar
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.

package/skills/writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: writer
 description: Structured documentation workflow for READMEs, API docs, architecture documents, changelogs, and decision records.
+name: writer
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.