From ef23ecdfbb9b40a69188c7ddbfeccc686bef82db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tuncay=20=C3=96lmez?= Date: Mon, 27 Jul 2026 18:10:54 +0300 Subject: [PATCH] docs: explain Codex plugin workflow --- README.md | 72 +++++++++++++++++++++++++++++++ docs/release-notes.md | 8 ++++ tests/contracts/plugin-package.js | 14 ++++++ 3 files changed, 94 insertions(+) diff --git a/README.md b/README.md index 4e4ee6a..570cb11 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,37 @@ cewp init cewp doctor ``` +The npm install provides the `cewp` and `cewp-mcp` commands. It does not +automatically register the CEWP Codex plugin. + +## Install The Codex Plugin + +The full local plugin bundles three CEWP skills, the local `cewp-mcp` bridge, +review-required subagent evidence hooks, and plugin metadata. After installing +the npm package globally, register its marketplace with Codex. + +PowerShell: + +```powershell +$cewpPackage = Join-Path (npm root -g) "@setrathex\codex-engineering-workflow-pack" +codex plugin marketplace add "$cewpPackage" +codex plugin add cewp@cewp-local +codex plugin list +``` + +macOS or Linux: + +```bash +codex plugin marketplace add "$(npm root -g)/@setrathex/codex-engineering-workflow-pack" +codex plugin add cewp@cewp-local +codex plugin list +``` + +Restart Codex, open a new conversation, and enable CEWP from the Plugins +Directory. This installs the complete plugin on the current machine from a +local marketplace source; it does not list CEWP in the universal public plugin +directory. + To evaluate the exact GitHub candidate before or without a registry publication, run it from a source checkout: @@ -57,6 +88,13 @@ cd Codex-Engineering-Workflow-Pack node ./bin/cewp.js doctor ``` +The source checkout can also be registered directly: + +```bash +codex plugin marketplace add /path/to/Codex-Engineering-Workflow-Pack +codex plugin add cewp@cewp-local +``` + Run the credential-free walkthrough: ```bash @@ -89,6 +127,40 @@ cewp policy reset The advanced policy permits requested local operations; it does not disable scope, budget, verification, ownership, or reviewer gates. +## Use CEWP From Codex + +The intended product interaction is a normal Codex request that explicitly +selects CEWP: + +```text +Use CEWP to complete @roadmap.md. Turn it into bounded checkpoints, use +independent workers only where scopes do not overlap, verify every checkpoint, +require reviewer PASS, preserve receipts, and stop on a closed gate. +``` + +Native Codex `/goal` keeps a persistent objective attached to the active task. +CEWP does not replace or control that private host goal. The plugin adds an +engineering control plane around the work: source-bound planning, explicit +scope, isolated worktrees, budgets, deterministic verification, recovery, +independent review, and final evidence. + +Today CEWP provides three related execution levels: + +1. **Supervised checkpoint:** the plugin plans and runs one bounded managed + checkpoint at a time through CEWP Core. +2. **Coordinator Mode:** CEWP can run two non-overlapping `codex-exec` workers + sequentially or in parallel, then run an independent reviewer. +3. **Workflow runtime:** CEWP validates versioned DAGs, dependencies, worker + capacity, budgets, revisions, results, and reviewer gates. + +The complete one-sentence-to-finished-roadmap experience is a product direction, +not a current completion claim. The workflow compiler currently emits a +source-bound agent request; the host agent must produce the structured workflow +proposal, and approval, task start/result, review, and finalization transitions +remain explicit. Codex can spawn native subagents when directly requested or +when plugin/project instructions request them, but CEWP currently treats native +subagent hooks as optional evidence rather than canonical execution control. + ## Safety Model CEWP Core is the authority for every completion claim: diff --git a/docs/release-notes.md b/docs/release-notes.md index 30fbb60..6aece3a 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -2,6 +2,14 @@ ## Unreleased +### Changed + +- Documented full CEWP Codex plugin installation from the globally installed npm + package as a separate step from CLI installation. +- Clarified the intended roadmap-driven Codex experience and the current boundary + between supervised checkpoints, Coordinator Mode, workflow DAG state, and + native Codex subagent evidence. + ## 0.14.0-beta.1 — 2026-07-27 ### Changed diff --git a/tests/contracts/plugin-package.js b/tests/contracts/plugin-package.js index 6520bdb..4b2bedc 100644 --- a/tests/contracts/plugin-package.js +++ b/tests/contracts/plugin-package.js @@ -15,6 +15,7 @@ function runPluginPackageContract() { const packageJson = readJson(path.join(repoRoot, "package.json")); const manifest = readJson(path.join(repoRoot, "plugins", "cewp", ".codex-plugin", "plugin.json")); const marketplace = readJson(path.join(repoRoot, ".agents", "plugins", "marketplace.json")); + const readme = fs.readFileSync(path.join(repoRoot, "README.md"), "utf8"); const compatibility = readJson( path.join(repoRoot, "tests", "fixtures", "compat", "v0.7.0-beta.0", "contracts.json"), ); @@ -79,6 +80,19 @@ function runPluginPackageContract() { assert(entry.source.path === "./plugins/cewp", "marketplace path stays repo-relative"); assert(entry.policy.installation === "AVAILABLE", "plugin install remains opt-in"); assert(entry.policy.authentication === "ON_INSTALL", "marketplace auth policy is explicit"); + assert( + /npm.*CLI.*does not.*register.*Codex plugin/is.test(readme), + "README distinguishes npm CLI installation from Codex plugin registration", + ); + assert( + /codex plugin marketplace add.*codex-engineering-workflow-pack/is.test(readme), + "README installs the marketplace from the globally installed npm package", + ); + assert(readme.includes("codex plugin add cewp@cewp-local"), "README installs the CEWP plugin from its marketplace"); + assert( + /Use CEWP to complete.*roadmap\.md/is.test(readme), + "README shows the roadmap-completion product intent", + ); assert(compatibility.schemas.adapterResult === ADAPTER_RESULT_SCHEMA_VERSION, "v0.7 adapter result readable"); assert(