@sienklogic/plan-build-run 2.55.0 → 2.56.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.56.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.0...plan-build-run-v2.56.1) (2026-03-03)
+
+
+### Documentation
+
+* **quick-020:** comprehensively update documentation for v2.56.0 ([82f9177](https://github.com/SienkLogic/plan-build-run/commit/82f917792dd573192c4ce69df8633f13b1050b0a))
+
+## [2.56.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.55.0...plan-build-run-v2.56.0) (2026-03-02)
+
+
+### Features
+
+* **58-02:** add Codex manual files (AGENTS.md, config.toml, README) ([c928ea6](https://github.com/SienkLogic/plan-build-run/commit/c928ea6d7170ce5c2b97bf5fe11505046f008396))
+
+
+### Bug Fixes
+
+* **58-02:** correct repo URL in codex-pbr README ([1b13b2a](https://github.com/SienkLogic/plan-build-run/commit/1b13b2a4799fa9827abf82feda4f87c2c65e2880))
+
 ## [2.55.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.54.0...plan-build-run-v2.55.0) (2026-03-02)
 
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Context-engineered development workflow for Claude Code, Cursor, and GitHub Copilot CLI.</strong>
+  <strong>Context-engineered development workflow for Claude Code, Cursor, GitHub Copilot CLI, OpenAI Codex, and Google Jules.</strong>
   <br />
   Build ambitious multi-phase software without quality degradation.
   <br />
@@ -27,7 +27,7 @@
   <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
   <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
   <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/Tests-2153_passing-brightgreen?style=for-the-badge" alt="2153 Tests" />
+  <img src="https://img.shields.io/badge/Tests-9283_passing-brightgreen?style=for-the-badge" alt="9283 Tests" />
 </p>
 
 ---
@@ -132,6 +132,48 @@ All three plugins share the same `.planning/` directory — start in any tool, c
 
 </details>
 
+<details>
+<summary><strong>Install for OpenAI Codex CLI</strong></summary>
+
+Plan-Build-Run also works in OpenAI Codex CLI. Skills and agents are available via the `plugins/codex-pbr/` plugin. No hooks (Codex CLI does not support lifecycle hooks).
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/codex-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\codex-pbr\setup.ps1
+```
+
+All five plugins share the same `.planning/` directory. See [`plugins/codex-pbr/README.md`](plugins/codex-pbr/README.md) for full details.
+
+</details>
+
+<details>
+<summary><strong>Install for Google Jules</strong></summary>
+
+Plan-Build-Run also works in Google Jules. Skills and agents are available via the `plugins/jules-pbr/` plugin. No hooks (Jules does not support lifecycle hooks).
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/jules-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\jules-pbr\setup.ps1
+```
+
+All five plugins share the same `.planning/` directory. See [`plugins/jules-pbr/README.md`](plugins/jules-pbr/README.md) for full details.
+
+</details>
+
 <details>
 <summary><strong>Dashboard (Optional)</strong></summary>
 
@@ -219,7 +261,7 @@ Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
 | `/pbr:build <N>` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |
 | `/pbr:review <N>` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |
 
-See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 26 commands with flags, cost-by-depth tables, and detailed descriptions.
+See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 27 commands with flags, cost-by-depth tables, and detailed descriptions.
 
 ---
 
@@ -292,8 +334,8 @@ Requires a GPU with 6+ GB VRAM for best performance. CPU-only works but adds lat
 | Topic | Description |
 |-------|-------------|
 | **[Agents](https://github.com/SienkLogic/plan-build-run/wiki/Agents)** | 12 specialized agents with configurable model profiles and file-based communication |
-| **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 13 config keys, depth/model profiles, 16+ feature toggles, local LLM settings |
-| **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 38 hook scripts that enforce discipline at zero token cost |
+| **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 12 config keys, depth/model profiles, 14+ feature toggles, local LLM settings |
+| **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 41 hook scripts that enforce discipline at zero token cost |
 | **[Local LLM](https://github.com/SienkLogic/plan-build-run/wiki/Configuration#local_llm)** | Offload hook-level inference to Ollama for token savings with automatic fallback |
 | **[Project Structure](https://github.com/SienkLogic/plan-build-run/wiki/Project-Structure)** | The `.planning/` directory layout, key files, and file ownership |
 | **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI with live updates for browsing project state |
@@ -306,28 +348,29 @@ Requires a GPU with 6+ GB VRAM for best performance. CPU-only works but adds lat
 
 ## Platform Compatibility
 
-Plan-Build-Run works across three platforms with varying levels of hook support. Hooks are the mechanism that fires validation scripts on every tool call — they power local LLM offloading, commit format enforcement, context budget tracking, and workflow gates.
-
-| Feature | Claude Code | Copilot CLI | Cursor IDE |
-|---------|:-----------:|:-----------:|:----------:|
-| Skills (slash commands) | All 26 | All 26 | All 26 |
-| Agents (subagent delegation) | All 12 | All 12 | All 12 |
-| `.planning/` state management | Full | Full | Full |
-| **Hook support** | **Full (14 events)** | **Partial (4 events)** | **Unverified** |
-| Commit format enforcement | Hook-enforced | Hook-enforced | Manual |
-| PLAN/SUMMARY quality classification | Hook + skill fallback | Hook + skill fallback | Skill fallback only |
-| Test failure triage | Automatic (hook) | Automatic (hook) | Not available |
-| Context budget tracking | Automatic (hook) | Not available | Not available |
-| Auto-continue between skills | Automatic (hook) | Not available | Not available |
-| Subagent lifecycle logging | Automatic (hook) | Not available | Not available |
-| **Local LLM offloading** | **Full (8 operations)** | **Mostly (6-7 operations)** | **CLI only** |
-| `pbr-tools.js llm` CLI commands | Full | Full | Full |
+Plan-Build-Run works across five platforms with varying levels of hook support. Hooks are the mechanism that fires validation scripts on every tool call — they power local LLM offloading, commit format enforcement, context budget tracking, and workflow gates.
+
+| Feature | Claude Code | Copilot CLI | Cursor IDE | Codex CLI | Jules |
+|---------|:-----------:|:-----------:|:----------:|:---------:|:-----:|
+| Skills (slash commands) | All 27 | All 27 | All 27 | All 27 | All 27 |
+| Agents (subagent delegation) | All 12 | All 12 | All 12 | All 12 | All 12 |
+| `.planning/` state management | Full | Full | Full | Full | Full |
+| **Hook support** | **Full (14 events)** | **Partial (4 events)** | **Unverified** | **None** | **None** |
+| Commit format enforcement | Hook-enforced | Hook-enforced | Manual | Manual | Manual |
+| PLAN/SUMMARY quality classification | Hook + skill fallback | Hook + skill fallback | Skill fallback only | Skill fallback only | Skill fallback only |
+| Test failure triage | Automatic (hook) | Automatic (hook) | Not available | Not available | Not available |
+| Context budget tracking | Automatic (hook) | Not available | Not available | Not available | Not available |
+| Auto-continue between skills | Automatic (hook) | Not available | Not available | Not available | Not available |
+| Subagent lifecycle logging | Automatic (hook) | Not available | Not available | Not available | Not available |
+| **Local LLM offloading** | **Full (8 operations)** | **Mostly (6-7 operations)** | **CLI only** | **CLI only** | **CLI only** |
+| `pbr-tools.js llm` CLI commands | Full | Full | Full | Full | Full |
 
 **Key differences:**
 
 - **Claude Code** has full hook support — all local LLM operations fire automatically on every tool call
 - **Copilot CLI** supports `sessionStart`, `preToolUse`, `postToolUse`, and `sessionEnd` — covers most validation hooks but misses lifecycle events (`SubagentStop`, `PreCompact`, `Stop`)
 - **Cursor IDE** hook support is unverified — hooks.json is configured but whether Cursor actually fires them is unknown. Skills include `pbr-tools.js llm` fallback calls for key operations (plan quality, verification quality) so local LLM classification is available even without hooks
+- **OpenAI Codex CLI** and **Google Jules** do not support hooks. All skills and agents are available via `plugins/codex-pbr/` and `plugins/jules-pbr/` respectively. Agent definitions use AGENTS.md format.
 
 All platforms share the same scripts via relative paths — no code duplication. See the [Copilot CLI](plugins/copilot-pbr/README.md) and [Cursor IDE](plugins/cursor-pbr/README.md) READMEs for platform-specific details.
 
@@ -341,7 +384,7 @@ git clone https://github.com/SienkLogic/plan-build-run.git
 cd plan-build-run
 npm install
 
-# Run tests (2153 tests, 73 suites)
+# Run tests (9283 tests, 281 suites)
 npm test
 
 # Lint
@@ -362,14 +405,19 @@ CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md]
 
 | Metric | Count |
 |--------|-------|
-| Skills (slash commands) | 26 |
+| Skills (slash commands) | 27 |
 | Specialized agents | 12 |
-| Hook scripts | 38 |
+| Hook scripts | 41 |
 | Local LLM operations | 8 |
-| Supported platforms | 3 (Claude Code, Cursor, Copilot CLI) |
-| Tests | 2153 |
-| Test suites | 73 |
-| Config keys | 13 top-level (62+ properties) |
+| Supported platforms | 5 (Claude Code, Cursor, Copilot CLI, Codex, Jules) |
+| Tests | 9283 |
+| Test suites | 281 |
+| Config keys | 12 top-level (62+ properties) |
+| Feature toggles | 14 |
+| Lib modules | 19 |
+| Shared fragments | 12 |
+| Templates | 10 |
+| References | 19 |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.55.0",
+  "version": "2.56.1",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/codex-pbr/.codex/config.toml

@@ -0,0 +1,101 @@
+# PBR Workflow Configuration for Codex CLI
+# Copy this file to your project's .codex/config.toml and customize as needed.
+#
+# Each [profiles.*] section defines a named agent profile that can be selected
+# when Codex runs PBR skills. Uncomment and adjust the fields you want to change.
+#
+# Reference: https://github.com/openai/codex
+
+# ---------------------------------------------------------------------------
+# Sandbox Settings
+# ---------------------------------------------------------------------------
+# Controls which shell commands Codex is allowed to run during builds.
+# Adjust based on your project's build toolchain.
+
+[sandbox]
+# allow = ["bash", "git", "npm", "node", "python", "pip", "cargo", "make"]
+# deny  = ["curl", "wget", "ssh"]
+
+# ---------------------------------------------------------------------------
+# PBR Agent Profiles
+# ---------------------------------------------------------------------------
+# Each profile corresponds to a PBR agent role. Codex selects the appropriate
+# profile based on the active skill. You can override model and instructions
+# per role to tune cost/quality tradeoffs.
+
+# Research agent — explores domain, reads docs, summarizes findings.
+# Called by: $pbr-explore, $pbr-begin, $pbr-plan (research phase)
+[profiles.pbr-researcher]
+# description = "Research agent: investigates domain and summarizes findings"
+# model = "o4-mini"
+# instructions = "Focus on gathering factual information. Cite sources."
+
+# Planner agent — creates detailed, task-level phase plans.
+# Called by: $pbr-plan, $pbr-begin
+[profiles.pbr-planner]
+# description = "Planner agent: produces structured PLAN.md files"
+# model = "o3"
+# instructions = "Output valid PLAN.md frontmatter. Define must_haves precisely."
+
+# Executor agent — implements tasks from a PLAN.md, commits each task.
+# Called by: $pbr-build
+[profiles.pbr-executor]
+# description = "Executor agent: implements plan tasks with atomic commits"
+# model = "o4-mini"
+# instructions = "One task per commit. Follow the plan exactly. No scope creep."
+
+# Verifier agent — checks build output against plan must_haves.
+# Called by: $pbr-review
+[profiles.pbr-verifier]
+# description = "Verifier agent: produces VERIFICATION.md with evidence"
+# model = "o4-mini"
+# instructions = "Check evidence in the codebase. Do not assume correctness."
+
+# Integration checker agent — validates cross-component integration.
+# Called by: $pbr-health, $pbr-scan
+[profiles.pbr-integration-checker]
+# description = "Integration checker: validates cross-component contracts"
+# model = "o4-mini"
+# instructions = "Focus on interface boundaries and data flow between modules."
+
+# Debugger agent — hypothesis-driven bug investigation.
+# Called by: $pbr-debug
+[profiles.pbr-debugger]
+# description = "Debugger agent: systematic hypothesis-driven investigation"
+# model = "o3"
+# instructions = "Form falsifiable hypotheses. Test each before moving on."
+
+# Codebase mapper agent — creates ARCHITECTURE.md and related codebase docs.
+# Called by: $pbr-explore, $pbr-begin
+[profiles.pbr-mapper]
+# description = "Mapper agent: documents codebase structure and architecture"
+# model = "o4-mini"
+# instructions = "Be concise. Focus on structure over implementation details."
+
+# Synthesizer agent — aggregates research and produces structured summaries.
+# Called by: $pbr-explore, $pbr-discuss
+[profiles.pbr-synthesizer]
+# description = "Synthesizer agent: aggregates findings into structured output"
+# model = "o4-mini"
+# instructions = "Extract key insights. Surface tensions and open questions."
+
+# General agent — handles ad-hoc tasks and one-off instructions.
+# Called by: $pbr-do, $pbr-discuss
+[profiles.pbr-general]
+# description = "General agent: flexible agent for miscellaneous PBR tasks"
+# model = "o4-mini"
+# instructions = "Follow PBR workflow rules. Commit with correct format."
+
+# Audit agent — analyzes session logs for workflow compliance.
+# Called by: $pbr-audit
+[profiles.pbr-audit]
+# description = "Audit agent: reviews session logs and produces compliance reports"
+# model = "o4-mini"
+# instructions = "Be objective. Report findings without judgment."
+
+# Dev-sync agent — synchronizes changes across plugin derivatives.
+# Called internally — not a user-facing skill.
+[profiles.pbr-dev-sync]
+# description = "Dev-sync agent: propagates pbr/ changes to cursor-pbr/ and codex-pbr/"
+# model = "o4-mini"
+# instructions = "Apply diffs exactly. Do not add scope beyond the sync target."