@maestria/codex 0.3.2 → 0.4.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestria",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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,17 @@
 # @maestria/codex
 
+## 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.0",
   "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",

package/skills/orchestrator/SKILL.md

@@ -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.