@maestria/codex 0.2.1 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# @maestria/codex
|
|
2
2
|
|
|
3
|
+
## 0.2.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#210](https://github.com/agustinusnathaniel/maestria/pull/210) [`88cc573`](https://github.com/agustinusnathaniel/maestria/commit/88cc5738ac2b1d5c381bba58f7208498087b2bfa) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Keep normal engineering sessions autonomous through continuation, scope-frozen bounded repair, and reviewable PR delivery. Incomplete specialist work is recovered or reported as a structured blocker instead of becoming an implicit user checkpoint.
|
|
8
|
+
|
|
3
9
|
## 0.2.1
|
|
4
10
|
|
|
5
11
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,71 +1,44 @@
|
|
|
1
1
|
# @maestria/codex
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A provisional Codex CLI projection of Maestria's canonical agent methodology, packaged as namespaced `$maestria:*` skills inside a `.codex-plugin/plugin.json` bundle.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> This package is part of Maestria. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope. The skills are **generated** from the canonical directives in `packages/core/agent-directives/` by the [sync pipeline](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md#3-the-sync-pipeline-core-concept).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Status / Support Boundary
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
`Provisional` spike verified against the locally available `codex 0.145.0` on 2026-08-13. It demonstrates a generated skills projection and is not a production support promise; it does not claim Codex desktop parity. Reverify host marketplace and skills behavior when upgrading Codex.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## Local package validation
|
|
14
|
-
|
|
15
|
-
From the repository root:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
python3 /path/to/plugin-creator/scripts/validate_plugin.py packages/codex
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
Use the `validate_plugin.py` shipped with the Codex plugin-creator skill in your Codex installation; the path is installation-specific.
|
|
22
|
-
|
|
23
|
-
When a Codex marketplace is available, install the package through that marketplace and start a fresh session before checking skill discovery. This repository does not create or mutate a marketplace as part of the spike.
|
|
24
|
-
|
|
25
|
-
For the published package, the supported convenience path is:
|
|
11
|
+
## Installation
|
|
26
12
|
|
|
27
13
|
```bash
|
|
14
|
+
# Supported convenience path (requires Codex CLI and npm on PATH)
|
|
28
15
|
npx maestria install codex
|
|
16
|
+
npx maestria status
|
|
17
|
+
npx maestria update codex
|
|
18
|
+
npx maestria uninstall codex
|
|
29
19
|
```
|
|
30
20
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
Codex CLI does not expose a plugin update command in the supported surface used by this projection. `maestria update codex` refreshes the staged npm package, removes the installed plugin, and adds it again. Exact version pinning is not available through `maestria update codex --version`.
|
|
34
|
-
|
|
35
|
-
## Skills
|
|
21
|
+
The CLI stages the published npm package into a local marketplace under `~/.cache/maestria/` and runs `codex plugin add maestria@maestria`. Codex CLI exposes no plugin update command in the pinned surface, so `maestria update codex` refreshes the staged package, removes the plugin, and adds it again. 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.
|
|
36
22
|
|
|
37
|
-
|
|
23
|
+
## What It Provides
|
|
38
24
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
| `$maestria:global-rules` | Universal evidence, safety, authorization, review, and branch contracts |
|
|
42
|
-
| `$maestria:orchestrator` | Route work and coordinate specialist skills |
|
|
43
|
-
| `$maestria:adventurer` | Reconnaissance and codebase mapping |
|
|
44
|
-
| `$maestria:architect` | Architecture trade-offs and ADR decisions |
|
|
45
|
-
| `$maestria:builder` | Atomic implementation and verification |
|
|
46
|
-
| `$maestria:diagnose` | Root-cause analysis and regression tracing |
|
|
47
|
-
| `$maestria:planner` | Phased implementation planning |
|
|
48
|
-
| `$maestria:reviewer` | Independent quality review |
|
|
49
|
-
| `$maestria:writer` | Documentation and structured prose |
|
|
50
|
-
| `$maestria:handoff` | Inter-stage handoff contracts |
|
|
51
|
-
| `$maestria:iteration-limits` | Bounded loops and repair termination |
|
|
52
|
-
| `$maestria:fein` | Full pipeline mode |
|
|
53
|
-
| `$maestria:sonar` | Research-only mode |
|
|
54
|
-
| `$maestria:blitz` | Fast capability-aware mode |
|
|
25
|
+
- **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`.
|
|
26
|
+
- **Maestria CLI compatibility** - install, status, check, update, and uninstall through the CLI.
|
|
55
27
|
|
|
56
|
-
|
|
28
|
+
## Support / Platform Notes
|
|
57
29
|
|
|
58
|
-
|
|
30
|
+
- Skills-only projection: workflow modes ship as skills, not slash commands, because the verified surface for this spike is the plugin `skills/` directory.
|
|
31
|
+
- Read-only specialist boundaries are documented guidance, not tool enforcement; Codex's own sandbox, approvals, and hook trust controls remain the host boundary.
|
|
32
|
+
- No hooks, MCP servers, model configuration, or `AGENTS.md` writer are shipped.
|
|
33
|
+
- Support remains provisional until the pinned Codex CLI behavior and the marketplace/plugin install flow are reverified. Evidence baseline: [runtime support matrix](https://github.com/agustinusnathaniel/maestria/blob/main/docs/runtime-support-matrix.md) and [ADR-CORE-014](https://github.com/agustinusnathaniel/maestria/blob/main/docs/adr/core/ADR-CORE-014-runtime-support-and-adapter-policy.md).
|
|
34
|
+
- The skills are projections of the canonical core directives. To change behavior, edit `packages/core/agent-directives/` and re-run the sync pipeline - never hand-edit the generated `skills/` directory.
|
|
59
35
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
scripts/sync-all
|
|
64
|
-
scripts/check-sync
|
|
65
|
-
```
|
|
36
|
+
## Documentation and Changelog
|
|
66
37
|
|
|
67
|
-
|
|
38
|
+
- [User-facing documentation](https://maestria.sznm.dev/codex/) on the docs site
|
|
39
|
+
- [Installation checklist](https://github.com/agustinusnathaniel/maestria/blob/main/packages/codex/INSTALL.md)
|
|
40
|
+
- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/codex/CHANGELOG.md)
|
|
68
41
|
|
|
69
|
-
##
|
|
42
|
+
## License
|
|
70
43
|
|
|
71
|
-
|
|
44
|
+
MIT
|
package/package.json
CHANGED
|
@@ -37,6 +37,14 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
|
|
|
37
37
|
- Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
|
|
38
38
|
- Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `$maestria:architect` and obtain the applicable authorization before proceeding.
|
|
39
39
|
|
|
40
|
+
## Session Continuation and Delivery
|
|
41
|
+
|
|
42
|
+
- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
|
|
43
|
+
- A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
|
|
44
|
+
- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
|
|
45
|
+
- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
|
|
46
|
+
- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
|
|
47
|
+
|
|
40
48
|
## Delegation and Context
|
|
41
49
|
|
|
42
50
|
Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `planner`, `reviewer`, and `writer`.
|
|
@@ -11,8 +11,14 @@ description: Verifiable termination and bounded repair guidance for loops, revie
|
|
|
11
11
|
- Define a verifiable termination condition before looping.
|
|
12
12
|
- Set a practical repair bound, normally three rounds. Extend only when the
|
|
13
13
|
latest attempt shows observable progress; never silently reset the bound.
|
|
14
|
+
- The bound applies to the same user outcome, even when work is split across
|
|
15
|
+
more delegations or specialist types. Start a new bound only after recording
|
|
16
|
+
a genuinely new outcome with new acceptance criteria.
|
|
14
17
|
- Repeated causes, repeated findings, restored diffs, or no new evidence mean
|
|
15
18
|
non-progress. Change strategy or escalate rather than retrying unchanged.
|
|
19
|
+
- Do not broaden the outcome merely because review found adjacent work. Keep
|
|
20
|
+
the accepted slice deliverable and record adjacent findings as follow-ups
|
|
21
|
+
unless they invalidate acceptance or trigger a safety/authorization stop.
|
|
16
22
|
- Stop on safety ambiguity, authorization boundaries, or unresolved review
|
|
17
23
|
blockers. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to
|
|
18
24
|
proceed.`
|
|
@@ -95,7 +95,13 @@ Modes are case-insensitive and per-turn unless the platform documents another li
|
|
|
95
95
|
|
|
96
96
|
## Commit and Session Flow
|
|
97
97
|
|
|
98
|
-
For
|
|
98
|
+
For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair -> commit -> push -> PR`.
|
|
99
|
+
|
|
100
|
+
When the repository, branch, remote, ownership, and host capabilities support PR delivery, complete it without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
|
|
101
|
+
|
|
102
|
+
The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
|
|
103
|
+
|
|
104
|
+
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.
|
|
99
105
|
|
|
100
106
|
An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.
|
|
101
107
|
|