diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f19c61..0caf899 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,30 @@ All notable changes to this project are documented here. +## [0.3.12] - 2026-07-19 + +### Added + +- New `codex-onboarding` skill: a guided first run that routes a newcomer from + zero to a checked Codex artifact through the add-one, build-a-plugin, and + marketplace paths. `codex-builder-orientation` now points newcomers to it. The + builder plugin exposes 29 skills. + +### Fixed + +- The `config` checker now accepts the full Codex 0.144.6 reasoning-effort ladder + for `model_reasoning_effort` and `plan_mode_reasoning_effort`. `max` and `ultra` + (and `none`) map to the same `ReasoningEffort` type as an agent role's effort, + but a stricter config-only allowlist rejected them as false positives. + +### Changed + +- The contracts reference notes that current capability toggles are centralized + in `[features]` and points at the checker and `$openai-docs` as the authority, + rather than freezing the fast-moving flag list. +- The builder plugin advances to 0.3.7 so an in-place `install-builder` + re-materializes the cache. + ## [0.3.11] - 2026-07-19 ### Fixed diff --git a/VERSION b/VERSION index 2080591..0b9c019 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.11 +0.3.12 diff --git a/build/manifest.json b/build/manifest.json index 0e62a1b..1ee8c05 100644 --- a/build/manifest.json +++ b/build/manifest.json @@ -5,7 +5,7 @@ "location": "sibling ..nddev-codex-backups", "slots": 10 }, - "build_version": "0.3.11", + "build_version": "0.3.12", "command_policy": { "json_supported": [ "list", diff --git a/build/release-evidence.json b/build/release-evidence.json index 6fc1c76..028b2f2 100644 --- a/build/release-evidence.json +++ b/build/release-evidence.json @@ -2,15 +2,15 @@ "schema_version": 2, "module": { "repository": "NDDev-it-com/nddev-codex-app", - "setup_digest": "sha256:47c123ec6af139298ec37c82157511cb231a95e8de9b1a8db18884c85c8fd8d2" + "setup_digest": "sha256:cf9ea19a63c751b3cc12962da675e11bcaa8b494d1ae0edb5660499b4541dc68" }, "harness": { "repository": "NDDev-it-com/nddev-harnesses", - "commit": "c10983fa2094e1052b3d69413d391a2e8bb9391b" + "commit": "adc96b1eea357d6130f5b916f182625b87b5ea5a" }, "adapter": { "id": "codex", - "version": "0.3.11" + "version": "0.3.12" }, "vendor": { "cli_version": "0.144.6", @@ -29,8 +29,8 @@ } ], "lanes": [], - "generated_at_utc": "2026-07-19T07:40:21Z", - "expires_at_utc": "2027-01-15T07:40:21Z", + "generated_at_utc": "2026-07-19T11:21:55Z", + "expires_at_utc": "2027-01-15T11:21:55Z", "promotion": { "decision": "pending", "waivers": [] diff --git a/build/version.json b/build/version.json index 0f8d565..c6d0b47 100644 --- a/build/version.json +++ b/build/version.json @@ -1,8 +1,8 @@ { - "build_version": "0.3.11", + "build_version": "0.3.12", "codex_permission_profiles_since": "0.138.0", "codex_cli_tested": "0.144.6", - "nddev_builder_plugin_version": "0.3.6", + "nddev_builder_plugin_version": "0.3.7", "python_requires": ">=3.10", "runtime_baseline_ref": "references/codex-baseline.json", "schema_version": 2 diff --git a/plugins/nddev-builder/.codex-plugin/plugin.json b/plugins/nddev-builder/.codex-plugin/plugin.json index 341d540..83db02b 100644 --- a/plugins/nddev-builder/.codex-plugin/plugin.json +++ b/plugins/nddev-builder/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "nddev-builder", - "version": "0.3.6", + "version": "0.3.7", "description": "Create and validate native Codex skills, plugins, marketplaces, agents, hooks, MCP servers, app mappings, configuration, instructions, execpolicy rules, and managed requirements.", "author": { "name": "Danil Silantyev / NDDev", diff --git a/plugins/nddev-builder/README.md b/plugins/nddev-builder/README.md index 8445f91..73894e2 100644 --- a/plugins/nddev-builder/README.md +++ b/plugins/nddev-builder/README.md @@ -12,8 +12,8 @@ The artifact contracts used by every workflow are documented in ## Skill inventory -The plugin exposes exactly 28 skills: eleven creator/checker pairs, one -cross-artifact reviewer, and five workflow/lifecycle skills. +The plugin exposes exactly 29 skills: eleven creator/checker pairs, one +cross-artifact reviewer, and six workflow/lifecycle skills. | Artifact | Creator | Checker | | --- | --- | --- | @@ -30,11 +30,12 @@ cross-artifact reviewer, and five workflow/lifecycle skills. | Managed requirements | `codex-requirements-creator` | `codex-requirements-checker` | | Cross-artifact review | `codex-artifact-reviewer` | — | -The five workflow/lifecycle skills orchestrate the artifacts above into a +The six workflow/lifecycle skills orchestrate the artifacts above into a complete build cycle: | Workflow | Skill | | --- | --- | +| Guided first run | `codex-onboarding` | | Orientation and routing | `codex-builder-orientation` | | Scaffold a whole plugin | `codex-plugin-scaffolder` | | Local dev-mode test loop | `codex-plugin-devtest` | diff --git a/plugins/nddev-builder/references/codex-artifact-contracts.md b/plugins/nddev-builder/references/codex-artifact-contracts.md index ada27d6..2ac355d 100644 --- a/plugins/nddev-builder/references/codex-artifact-contracts.md +++ b/plugins/nddev-builder/references/codex-artifact-contracts.md @@ -54,3 +54,14 @@ legacy top-level `mcpServers` wrapper. Keep the documentation-correct direct map as the generator default, record the validator discrepancy when it occurs, and require pinned-runtime discovery rather than rewriting the artifact solely to satisfy the stale validator. + +Current capability toggles are centralized in the top-level `[features]` table +(and a few dedicated tables it fronts). Rather than freeze the fast-moving flag +list here, treat `scripts/check_codex_artifact.py` (which pins the exact +top-level config surface) and the built-in `$openai-docs` skill as the +authority for names and defaults. Powerful surfaces an author reaches this way +include Code Mode, agent memories, tool search, guardian approvals, +browser/computer use, and multi-agent orchestration; enable only what the task +needs and prove each at runtime. One stable consequence: web search is on by +default, so the `features.web_search*` toggles are legacy — the config checker +rejects them, mirroring Codex's own deprecation notice. diff --git a/plugins/nddev-builder/scripts/check_codex_artifact.py b/plugins/nddev-builder/scripts/check_codex_artifact.py index 41ac611..778aee4 100644 --- a/plugins/nddev-builder/scripts/check_codex_artifact.py +++ b/plugins/nddev-builder/scripts/check_codex_artifact.py @@ -169,8 +169,11 @@ } MCP_APPROVAL_MODES = {"auto", "prompt", "writes", "approve"} -CONFIG_REASONING_EFFORTS = {"minimal", "low", "medium", "high", "xhigh"} -PLAN_REASONING_EFFORTS = CONFIG_REASONING_EFFORTS | {"none"} +# The Codex 0.144.6 reasoning-effort ladder (protocol/src/openai_models.rs). +# config.schema.json types `ReasoningEffort` as a non-empty string, and +# `model_reasoning_effort`/`plan_mode_reasoning_effort` share the same type as an +# agent role's effort, so accept the full known ladder for all three (a stricter +# config set wrongly rejected `max`/`ultra`). AGENT_REASONING_EFFORTS = { "none", "minimal", @@ -181,6 +184,8 @@ "max", "ultra", } +CONFIG_REASONING_EFFORTS = AGENT_REASONING_EFFORTS +PLAN_REASONING_EFFORTS = AGENT_REASONING_EFFORTS DEPRECATED_CONFIG_KEYS = { "codex_hooks", diff --git a/plugins/nddev-builder/skills/codex-builder-orientation/SKILL.md b/plugins/nddev-builder/skills/codex-builder-orientation/SKILL.md index ca583f4..0dd76a0 100644 --- a/plugins/nddev-builder/skills/codex-builder-orientation/SKILL.md +++ b/plugins/nddev-builder/skills/codex-builder-orientation/SKILL.md @@ -9,6 +9,8 @@ Resolve every ../../scripts and ../../references path relative to this SKILL.md The first skill to read for any nddev-builder task: index the artifact families, point at the schema and currency source of truth, and route to the skill that owns the work. +New to the toolkit? Start with `$codex-onboarding` — a guided first run that walks a newcomer from zero to a checked artifact through the paths below. + ## Workflow 1. Name the artifact family the task targets. The generator and checker own the authoritative family list; read it rather than trusting any copy: diff --git a/plugins/nddev-builder/skills/codex-onboarding/SKILL.md b/plugins/nddev-builder/skills/codex-onboarding/SKILL.md new file mode 100644 index 0000000..a2789f6 --- /dev/null +++ b/plugins/nddev-builder/skills/codex-onboarding/SKILL.md @@ -0,0 +1,80 @@ +--- +name: codex-onboarding +description: A guided first run of the nddev-builder toolkit — from zero to a working, checked Codex artifact in ordered steps. Use when new to nddev-builder, onboarding, or unsure which builder skill to start with. +--- + +# Codex Onboarding + +Resolve every ../../scripts and ../../references path relative to this SKILL.md directory, never the caller working directory. + +The fastest correct path from nothing to a working, validated Codex artifact. +Read `$codex-builder-orientation` once for the family map, pick a path below, +and let each step hand off to the focused creator, checker, or workflow skill. + +## The one thing to understand first + +Choose the **smallest native surface** the task needs, because Codex validates +and loads each one differently: + +- `AGENTS.md` for durable repository guidance; a **skill** for a reusable + workflow; a **plugin** to distribute skills/hooks/MCP/apps; **MCP or an app** + for a live external capability; a **hook** for lifecycle enforcement; a + **rule** for outside-sandbox command policy; and a **config/permission + profile** for model and safety posture. +- Codex has **no first-class authored slash commands** — a reusable command + workflow is authored as a skill. +- Custom-agent TOML is a **standalone config-scope file** + (`$CODEX_HOME/agents/.toml` or `/.codex/agents/.toml`), not + a plugin-bundled component. + +The family list, schemas, and current (Beta/experimental/under-development) +surfaces live in ../../references/codex-artifact-contracts.md and the two script +`--help` outputs — read them, never a frozen copy. + +## Path 1 — add one artifact to an existing repo or config + +1. Name the family (`skill`, `config`, `hook`, `mcp`, `agent`, `rule`, + `instructions`, `app`, `requirements`). +2. Author with the owning creator: `$codex--creator` (for example + `$codex-skill-creator`). It stages a conservative skeleton. +3. Complete the content, then validate with `$codex--checker` (or + `python3 ../../scripts/check_codex_artifact.py `). +4. Prove behavior with the runtime step in that family's contract, using a + temporary `HOME`/`CODEX_HOME` — a static PASS proves shape only. + +## Path 2 — build a whole plugin from an idea + +1. `$codex-plugin-scaffolder` — compose the bundle (manifest plus the skills, + hooks, MCP servers, and app mapping the idea needs) from intent. +2. `$codex-plugin-devtest` — register through a temporary marketplace with + isolated `CODEX_HOME` and confirm discovery and install. +3. `$codex-release-review` — gate the whole bundle for release readiness. +4. `$codex-plugin-publish` — version, catalog, and publish when others install + it. + +## Path 3 — start or distribute a marketplace + +1. `$codex-marketplace-creator` — scaffold the catalog (`local`, `url`, + `git-subdir`, or `npm` plugin sources via `--source-type`). +2. Add plugins with Path 2, then `$codex-release-review`. +3. `$codex-plugin-publish` for distribution; register and inspect only with the + exact target-owned Codex CLI. + +## Golden rules (from day one) + +- Read `$codex-builder-orientation` first; author with exactly one owning skill + and defer to its description. +- A static generate or check proves shape only — always run the matching + checker and then the contract's runtime step in isolated state. +- Full `agent` and `config` TOML validation needs Python 3.11+; on 3.10 the + checker fails closed rather than returning an unchecked PASS. +- Keep credentials, OAuth tokens, trust hashes, and machine-local paths out of + every artifact; reference secrets through the environment. +- English only. Never mix permission profiles with legacy `sandbox_mode` in one + loaded layer. + +## Where to go deeper + +`$codex-builder-orientation` for the full family map and ownership boundaries, +and ../../references/codex-artifact-contracts.md for every artifact's exact +contract, runtime check, and current maturity. diff --git a/plugins/nddev-builder/skills/codex-onboarding/agents/openai.yaml b/plugins/nddev-builder/skills/codex-onboarding/agents/openai.yaml new file mode 100644 index 0000000..a2af2d6 --- /dev/null +++ b/plugins/nddev-builder/skills/codex-onboarding/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Codex Onboarding" + short_description: "Guided first run from zero to a checked Codex artifact" + default_prompt: "Use $codex-onboarding for a guided first build with the Codex builder toolkit."