@sienklogic/plan-build-run 2.55.0 → 2.56.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "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."

package/plugins/codex-pbr/AGENTS.md

@@ -0,0 +1,653 @@
+# Plan-Build-Run Workflow for Codex
+
+> This file teaches Codex the Plan-Build-Run (PBR) development methodology.
+> Place it in your repository root so Codex reads it before starting any task.
+>
+> PBR prevents quality degradation on complex projects by enforcing a
+> disciplined Plan → Build → Review cycle with file-based state tracking.
+
+---
+
+## Core Principle
+
+**Never build without a plan. Never ship without a review.**
+
+Every meaningful change flows through three stages:
+
+1. **Plan** — Research the problem, design the solution, define success criteria
+2. **Build** — Execute the plan with atomic commits, one task at a time
+3. **Review** — Verify the build achieved the plan's goals (goal-backward verification)
+
+---
+
+## Project State Directory
+
+All workflow state lives in `.planning/` at the repository root. Codex should
+create and maintain these files as it works:
+
+```
+.planning/
+├── STATE.md              # Current position in the workflow
+├── ROADMAP.md            # Phase structure with goals and dependencies
+├── config.json           # Workflow settings (optional)
+├── phases/
+│   └── NN-slug/          # One directory per phase
+│       ├── PLAN.md       # What to build and how
+│       ├── SUMMARY.md    # What was built (written after execution)
+│       └── VERIFICATION.md  # Did the build match the plan?
+├── quick/                # Lightweight tasks outside the full cycle
+│   └── NNN-slug/
+│       ├── PLAN.md
+│       └── SUMMARY.md
+├── debug/                # Persistent debug sessions
+│   └── slug/
+│       └── HYPOTHESIS.md
+├── notes/                # Captured ideas and decisions
+├── todos/
+│   ├── pending/          # Active cross-session backlog
+│   └── done/             # Completed todos
+└── milestones/           # Archived milestone snapshots
+    └── v{version}/
+```
+
+### STATE.md Format
+
+```markdown
+---
+current_phase: "01-setup"
+current_plan: "01-01"
+status: "Planning"           # Planning | Planned | Building | Built | Verified
+updated: "2025-01-15T10:30:00Z"
+---
+
+## Current Focus
+Brief description of what's happening now.
+
+## Recently Completed
+- Phase 01, Plan 01: Project scaffolding (Verified)
+
+## Next Steps
+1. Primary: Start planning phase 02
+2. Alternative: Review phase 01 verification results
+```
+
+Valid status transitions: Planning → Planned → Building → Built → Verified
+
+---
+
+## Skill Invocation
+
+PBR skills live in `.agents/skills/{name}/SKILL.md` in the plugin directory.
+Codex discovers and runs them using the `$pbr-{name}` syntax.
+
+### Available Skills
+
+| Skill | Command | When to Use |
+|-------|---------|-------------|
+| begin | `$pbr-begin` | Start a new project or onboard PBR to existing codebase |
+| plan | `$pbr-plan` | Plan the next phase or plan item |
+| build | `$pbr-build` | Execute the current plan |
+| review | `$pbr-review` | Verify a completed build against its plan |
+| status | `$pbr-status` | Show current workflow position |
+| quick | `$pbr-quick` | Run a lightweight task outside the full cycle |
+| continue | `$pbr-continue` | Resume from a checkpoint or interrupted session |
+| pause | `$pbr-pause` | Pause with context preservation |
+| resume | `$pbr-resume` | Resume a paused session |
+| debug | `$pbr-debug` | Start or continue a debug investigation |
+| explore | `$pbr-explore` | Research a domain or problem space |
+| discuss | `$pbr-discuss` | Think through a design decision |
+| do | `$pbr-do` | Execute a one-off instruction under PBR rules |
+| scan | `$pbr-scan` | Audit codebase for issues |
+| health | `$pbr-health` | Check project health and workflow hygiene |
+| milestone | `$pbr-milestone` | Manage versioned milestone releases |
+| todo | `$pbr-todo` | Manage cross-session task backlog |
+| note | `$pbr-note` | Capture a decision or observation |
+| import | `$pbr-import` | Import existing work into PBR structure |
+| config | `$pbr-config` | Manage workflow configuration |
+| setup | `$pbr-setup` | Configure or reconfigure PBR for this project |
+| audit | `$pbr-audit` | Analyze session logs for workflow compliance |
+| help | `$pbr-help` | Show available skills and usage |
+| statusline | `$pbr-statusline` | Output a compact status summary |
+| undo | `$pbr-undo` | Roll back the last plan or build step |
+
+Skills can be invoked explicitly (`$pbr-plan`) or triggered implicitly when
+your request description matches a skill's purpose. For example, saying
+"plan the authentication phase" may implicitly trigger `$pbr-plan`.
+
+---
+
+## Phase Workflow
+
+### Step 1: Planning a Phase
+
+Before writing any code for a phase, create a plan file:
+
+**`.planning/phases/NN-slug/PLAN.md`**:
+
+```markdown
+---
+phase: "01-setup"
+plan: "01-01"
+type: "feature"
+files_modified:
+  - "src/config.ts"
+  - "src/database.ts"
+must_haves:
+  truths:
+    - "Database connection is established on startup"
+    - "Configuration loads from environment variables"
+  artifacts:
+    - "src/config.ts: >30 lines, exports loadConfig()"
+    - "src/database.ts: >40 lines, exports connectDB()"
+---
+
+## Tasks
+
+### Task 1: Create configuration loader
+- Read environment variables for DB_HOST, DB_PORT, DB_NAME
+- Export a typed config object
+- Throw on missing required variables
+
+### Task 2: Create database connection module
+- Use the config from Task 1
+- Implement connection pooling
+- Export connectDB() and getDB() functions
+
+### Task 3: Add startup integration
+- Call loadConfig() then connectDB() in main entry point
+- Log connection success/failure
+```
+
+**Planning rules:**
+- Define `must_haves` with concrete, verifiable success criteria
+- List all files that will be created or modified
+- Break work into small, independently committable tasks
+- Each task should produce a working, testable increment
+
+### Step 2: Building (Executing the Plan)
+
+When executing a plan:
+
+1. **Read the plan first** — Load `.planning/phases/NN-slug/PLAN.md`
+2. **Update STATE.md** — Set status to "Building"
+3. **Execute tasks sequentially** — Follow the plan's task order
+4. **Commit after each task** — One atomic commit per task
+5. **Write SUMMARY.md** — Document what was actually built
+
+**Commit message format:**
+
+```
+{type}({phase}-{plan}): {description}
+```
+
+Examples:
+- `feat(01-01): implement configuration loader`
+- `fix(01-01): handle missing DB_PORT with default value`
+- `test(01-01): add unit tests for config validation`
+- `refactor(02-01): extract auth middleware into separate module`
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+**SUMMARY.md format** (written after all tasks complete):
+
+```markdown
+---
+phase: "01-setup"
+plan: "01-01"
+status: "complete"
+commits:
+  - "abc1234: feat(01-01): implement configuration loader"
+  - "def5678: feat(01-01): create database connection module"
+key_files:
+  - "src/config.ts"
+  - "src/database.ts"
+requires:
+  - "Node.js 18+"
+  - "PostgreSQL 14+"
+deferred:
+  - "Connection retry logic (moved to phase 03)"
+---
+
+## What Was Built
+Brief narrative of what was accomplished and any deviations from the plan.
+```
+
+### Step 3: Verification
+
+After building, verify the work against the plan's `must_haves`:
+
+**VERIFICATION.md format:**
+
+```markdown
+---
+phase: "01-setup"
+plan: "01-01"
+result: "PASS"
+verified_at: "2025-01-15T14:00:00Z"
+---
+
+## Must-Have Verification
+
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | Database connection established on startup | PASS | `connectDB()` called in `src/index.ts:15` |
+| 2 | Config loads from environment variables | PASS | `loadConfig()` reads DB_HOST, DB_PORT, DB_NAME |
+
+## Artifact Verification
+
+| # | Artifact | Status | Evidence |
+|---|----------|--------|----------|
+| 1 | src/config.ts: >30 lines, exports loadConfig() | PASS | 47 lines, exports `loadConfig()` at line 12 |
+| 2 | src/database.ts: >40 lines, exports connectDB() | PASS | 63 lines, exports `connectDB()` at line 28 |
+
+## Deviations
+None — plan executed as written.
+```
+
+---
+
+## ROADMAP.md Structure
+
+The roadmap defines the full project as a sequence of phases:
+
+```markdown
+# Project Roadmap
+
+## Phase 01: Project Setup
+**Goal:** Establish project foundation with configuration and database connectivity.
+**Status:** Verified
+**Depends on:** (none)
+
+## Phase 02: Authentication
+**Goal:** Users can sign in via OAuth and receive a session token.
+**Status:** Planning
+**Depends on:** Phase 01
+
+## Phase 03: Core Features
+**Goal:** Implement the primary user-facing features.
+**Status:** Pending
+**Depends on:** Phase 01, Phase 02
+```
+
+**Rules:**
+- Phases are numbered sequentially (`01`, `02`, `03`, ...)
+- Each phase has a clear, measurable goal
+- Dependencies between phases are explicit
+- Status tracks the highest completed stage for that phase
+
+---
+
+## Enforcement Rules
+
+Codex has no hook system, so these rules are self-enforced checkpoints.
+Run through this checklist at every stage transition.
+
+### Gate 1: Commit Format
+
+Before any `git commit`, verify the message matches:
+
+```
+{type}({scope}): {description}
+```
+
+- **Valid types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+- **Valid scopes**: `NN-MM` (phase-plan), `quick-NNN`, `planning`, or a descriptive word
+- **Block the commit** if the format doesn't match — fix the message first
+
+### Gate 2: Plan-Before-Build
+
+Before writing any source code for a phase:
+
+- Confirm `.planning/phases/NN-slug/PLAN.md` exists
+- Confirm the plan has `must_haves` with at least one truth and one artifact
+- **Never write production code without an approved plan**
+
+### Gate 3: Phase Boundary
+
+Only modify `.planning/phases/NN-*/` files for the phase shown in `STATE.md`.
+
+- Cross-phase edits require explicit justification in the commit body
+- Don't refactor an old phase while building a new one
+
+### Gate 4: Format Validation
+
+After writing any planning artifact, verify required frontmatter fields:
+
+| File | Required fields |
+|------|----------------|
+| PLAN.md | `phase`, `plan`, `must_haves` (with `truths` and `artifacts`) |
+| SUMMARY.md | `phase`, `plan`, `status`, `requires`, `key_files`, `deferred` |
+| VERIFICATION.md | `phase`, `plan`, `result` (must be `PASS`, `FAIL`, `BLOCKED`, or `DEFERRED`) |
+
+### Gate 5: State Sync
+
+After writing SUMMARY.md or VERIFICATION.md:
+
+1. Update `STATE.md` — set `status` to the new stage, update `updated` timestamp
+2. Update `ROADMAP.md` — update the phase's `**Status:**` line to match
+
+Both files must stay in sync. Stale state causes confusion across sessions.
+
+---
+
+## Stage Transition Checkpoints
+
+Use these checklists at each stage boundary.
+
+### Before Planning
+
+- [ ] Read `.planning/STATE.md` — confirm current phase and status
+- [ ] Read `.planning/ROADMAP.md` — confirm phase goal and dependencies
+- [ ] Verify dependent phases are "Verified" before starting this phase
+- [ ] Create `.planning/phases/NN-slug/` directory if it doesn't exist
+
+### After Planning (Before Building)
+
+- [ ] PLAN.md has valid frontmatter (Gate 4)
+- [ ] `must_haves.truths` are observable facts (not implementation notes)
+- [ ] `must_haves.artifacts` specify file path, minimum size, and key exports
+- [ ] Update STATE.md status to "Planned"
+
+### Before Building
+
+- [ ] PLAN.md exists and is readable (Gate 2)
+- [ ] Update STATE.md status to "Building"
+- [ ] Note any pre-existing test failures — don't fix them unless the plan says to
+
+### After Each Commit
+
+- [ ] Commit message matches `{type}({scope}): {description}` (Gate 1)
+- [ ] Only files listed in the plan's `files_modified` were staged
+- [ ] The commit represents a single logical change
+
+### After Building
+
+- [ ] SUMMARY.md written with all required frontmatter fields (Gate 4)
+- [ ] Every file listed in `key_files` exists on disk
+- [ ] All commits listed in `commits` frontmatter actually exist in git log
+- [ ] Update STATE.md status to "Built"
+- [ ] Check `.planning/todos/pending/` — auto-close any todos satisfied by this work
+
+### After Verification
+
+- [ ] VERIFICATION.md written with `result: PASS` or `result: FAIL`
+- [ ] Every must-have has a row in the verification table with evidence
+- [ ] Update STATE.md status to "Verified"
+- [ ] Update ROADMAP.md phase status to "Verified" (Gate 5)
+- [ ] Suggest next phase to the user
+
+---
+
+## Supplementary Workflows
+
+### Quick Tasks
+
+For small changes that don't justify the full Plan-Build-Review cycle:
+
+**Use quick tasks for:**
+- Single-file changes
+- Bug fixes with obvious solutions
+- Documentation updates
+- Configuration tweaks
+
+**Use the full cycle for:**
+- Changes spanning 3+ files
+- New features requiring design decisions
+- Anything that will take more than one commit
+
+**Quick task structure:**
+
+```
+.planning/quick/
+└── NNN-slug/
+    ├── PLAN.md     # Brief: what, why, files
+    └── SUMMARY.md  # What was done, commit SHA
+```
+
+Commit scope for quick tasks: `quick-NNN` (e.g., `fix(quick-001): correct typo in README`).
+
+Quick PLAN.md only needs: one-sentence goal, files to touch, and definition of done.
+Quick SUMMARY.md only needs: what was done and the commit hash.
+
+### Milestones
+
+Milestones group phases into versioned releases.
+
+**ROADMAP.md milestone syntax:**
+
+```markdown
+## Milestone v1.0: Initial Release
+**Phases:** 01, 02, 03
+**Status:** In Progress
+```
+
+**Completing a milestone:**
+
+1. Verify all included phases have `status: Verified`
+2. Create `.planning/milestones/v{version}/`
+3. Copy (archive) `ROADMAP.md` and phase directories into it
+4. Create `STATS.md` with completion date, total commits, and phase count
+5. Collapse the milestone section in active ROADMAP.md to a single "COMPLETED" line
+6. Tag the commit: `git tag v{version}`
+
+Archive structure:
+
+```
+.planning/milestones/v1.0/
+├── ROADMAP.md        # Snapshot of roadmap at completion
+├── STATS.md          # Summary stats
+└── phases/
+    ├── 01-setup/
+    └── 02-auth/
+```
+
+### Debug Workflow
+
+For bugs requiring systematic investigation across sessions:
+
+**Create a debug session:**
+
+```
+.planning/debug/{slug}/
+└── HYPOTHESIS.md
+```
+
+**HYPOTHESIS.md format:**
+
+```markdown
+---
+bug: "Brief bug description"
+created: "2025-01-15"
+status: "investigating"   # investigating | confirmed | resolved
+---
+
+## Symptoms
+What the user observes. Include error messages, reproduction steps.
+
+## Hypotheses
+
+### H1: [Hypothesis name]
+**Test:** How to confirm or deny this
+**Result:** (fill in after testing)
+**Conclusion:** CONFIRMED / RULED OUT
+
+### H2: [Hypothesis name]
+**Test:** ...
+**Result:** ...
+**Conclusion:** ...
+
+## Root Cause
+(fill in when found)
+
+## Fix Applied
+(fill in after resolution — commit SHA and description)
+```
+
+Update `status` to `resolved` and record the fix. The file persists across sessions
+so you never re-investigate the same root cause.
+
+### Notes System
+
+Capture decisions, observations, and ideas between sessions:
+
+```
+.planning/notes/{YYYY-MM-DD}-{slug}.md
+```
+
+**Note frontmatter:**
+
+```markdown
+---
+date: "2025-01-15"
+promoted: false
+---
+
+The note body goes here. Free-form markdown.
+```
+
+Use `promoted: true` when a note has been acted on (turned into a phase or todo).
+Notes are append-only — add new files rather than editing old ones.
+
+### Todo Management
+
+Cross-session task backlog for items that don't yet have a phase:
+
+```
+.planning/todos/pending/{NNN}-{slug}.md   # Active
+.planning/todos/done/{NNN}-{slug}.md      # Completed
+```
+
+**Todo format:**
+
+```markdown
+---
+id: "001"
+created: "2025-01-15"
+priority: medium   # high | medium | low
+---
+
+What needs to be done and why.
+```
+
+After completing any phase or quick task, check `.planning/todos/pending/` and
+move satisfied todos to `done/` by renaming the file.
+
+### Session Continuity
+
+Use `.planning/.continue-here.md` to preserve context between Codex sessions.
+
+**When pausing (write `.planning/.continue-here.md`):**
+
+```markdown
+---
+paused_at: "2025-01-15T16:00:00Z"
+current_phase: "02-auth"
+current_plan: "02-01"
+---
+
+## What Was In Progress
+Which task was active, what had been done, what remained.
+
+## Blockers
+Any external dependencies or decisions needed before resuming.
+
+## Next Action
+The single most important thing to do when resuming. Be specific.
+
+## Context Notes
+Anything Codex would need to know that isn't obvious from the files.
+```
+
+**When resuming:**
+
+1. Read `.planning/.continue-here.md` first
+2. Read `STATE.md` to confirm current position
+3. Execute the "Next Action" listed
+4. Delete `.planning/.continue-here.md` once work resumes normally
+
+### Brownfield Onboarding
+
+Introducing PBR to an existing project without a `.planning/` directory:
+
+1. **Scan the codebase** — understand the current structure, tech stack, and any existing docs
+2. **Create `.planning/`** — initialize the directory structure
+3. **Write ROADMAP.md** — identify logical phases based on what already exists
+   - Phase 01 is often "Baseline" — mark it Verified to acknowledge existing work
+   - Subsequent phases are planned work
+4. **Write STATE.md** — set `current_phase` to the first active phase, status "Planning"
+5. **Create PLAN.md for Phase 01 (if not trivial)** — document what exists as baseline
+6. **Proceed normally** — the next feature or bug fix becomes Phase 02+
+
+Don't try to retroactively document every historical decision. A lightweight ROADMAP.md
+that captures the current state is enough to enable PBR going forward.
+
+---
+
+## Configuration
+
+PBR behavior can be customized via `.codex/config.toml` in your project.
+See the sample config at `plugins/codex-pbr/.codex/config.toml` for all options.
+
+Key configuration areas:
+- **Agent profiles** — model selection per PBR agent role
+- **Sandbox** — which commands are allowed during builds
+- **Workflow** — timeouts and context limits
+
+---
+
+## Working Rules for Codex
+
+### Before Starting Any Task
+
+1. Check if `.planning/STATE.md` exists — if so, read it to understand current position
+2. Check if `.planning/ROADMAP.md` exists — if so, read it to understand phase structure
+3. If the user's request maps to an existing phase, follow the Plan-Build-Review cycle
+4. If no `.planning/` directory exists and the task is non-trivial, offer to create one
+5. Check `.planning/.continue-here.md` — if it exists, resume from there
+
+### During Execution
+
+- **One task, one commit** — never bundle unrelated changes
+- **Stage specific files** — never use `git add .` or `git add -A`
+- **Follow the plan** — if you need to deviate, document why in SUMMARY.md
+- **Update STATE.md** — keep it current as you transition between stages
+- **Don't over-engineer** — build exactly what the plan specifies, nothing more
+
+### After Completing Work
+
+- Write SUMMARY.md documenting what was built
+- Run verification against the plan's must_haves
+- Write VERIFICATION.md with pass/fail results and evidence
+- Update STATE.md status to "Built" or "Verified"
+- Check `.planning/todos/pending/` for any todos to close
+- Suggest the next logical step to the user
+
+---
+
+## Context Management
+
+Codex operates in interactive CLI sessions, so context management matters:
+
+- **Write decisions to disk** — don't rely on conversation memory
+- **STATE.md is the source of truth** — always read it at task start
+- **Plans are contracts** — they define what "done" means
+- **Summaries close the loop** — they record what actually happened
+- **Use `.continue-here.md`** — for deliberate pauses between sessions
+
+If a task is complex enough to span multiple sessions, the
+`.planning/` directory ensures continuity between them.
+
+---
+
+## Anti-Patterns to Avoid
+
+1. **Building without a plan** — leads to scope creep and rework
+2. **Skipping verification** — you don't know if you succeeded
+3. **Giant commits** — impossible to review or revert
+4. **Modifying files outside the plan's scope** — creates hidden dependencies
+5. **Ignoring must_haves** — they exist to define "done" objectively
+6. **Re-reading entire files when summaries exist** — wastes context
+7. **Creating artifacts the user didn't approve** — always confirm first
+8. **Using `git add .`** — stages unintended files; always stage explicitly
+9. **Skipping STATE.md updates** — stale state causes confusion across sessions
+10. **Fixing pre-existing bugs while building a phase** — log to todos, stay focused

package/plugins/codex-pbr/README.md

@@ -0,0 +1,116 @@
+# Plan-Build-Run for Codex CLI
+
+Plan-Build-Run (PBR) is a structured development workflow plugin for Codex CLI that prevents
+quality degradation on complex projects. It enforces a disciplined Plan → Build → Review cycle
+using file-based state tracking in a `.planning/` directory — ensuring that every meaningful
+change is planned before it's coded, committed atomically, and verified against concrete
+success criteria.
+
+---
+
+## Installation
+
+### 1. Copy skills to your project
+
+Copy (or symlink) the `skills/` directory into your project's agent skills folder:
+
+```bash
+# Copy
+cp -r plugins/codex-pbr/skills/ /path/to/your-project/.agents/skills/
+
+# Or symlink (for active development)
+ln -s /path/to/plan-build-run/plugins/codex-pbr/skills /path/to/your-project/.agents/skills
+```
+
+### 2. Copy AGENTS.md to your project root
+
+```bash
+cp plugins/codex-pbr/AGENTS.md /path/to/your-project/AGENTS.md
+```
+
+Codex reads `AGENTS.md` from the repository root automatically. This file teaches Codex
+the PBR workflow rules, file formats, and enforcement gates.
+
+### 3. (Optional) Copy sample config
+
+```bash
+cp plugins/codex-pbr/.codex/config.toml /path/to/your-project/.codex/config.toml
+```
+
+Edit the config to customize model selection per agent role and sandbox permissions.
+All settings are commented out by default — uncomment only what you need.
+
+---
+
+## Skill Reference
+
+Invoke skills using `$pbr-{name}` syntax in your Codex session.
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| begin | `$pbr-begin` | Onboard PBR to a new or existing project |
+| plan | `$pbr-plan` | Plan the next phase with must-haves and tasks |
+| build | `$pbr-build` | Execute the current PLAN.md with atomic commits |
+| review | `$pbr-review` | Verify a completed build against plan criteria |
+| status | `$pbr-status` | Show current workflow position and phase state |
+| quick | `$pbr-quick` | Run a lightweight task outside the full cycle |
+| continue | `$pbr-continue` | Resume from a checkpoint or interrupted session |
+| pause | `$pbr-pause` | Pause with context preservation to .continue-here.md |
+| resume | `$pbr-resume` | Resume a previously paused session |
+| debug | `$pbr-debug` | Start or continue a hypothesis-driven debug session |
+| explore | `$pbr-explore` | Research a domain, library, or problem space |
+| discuss | `$pbr-discuss` | Think through a design decision interactively |
+| do | `$pbr-do` | Execute a one-off instruction under PBR rules |
+| scan | `$pbr-scan` | Audit the codebase for issues and tech debt |
+| health | `$pbr-health` | Check overall project health and workflow hygiene |
+| milestone | `$pbr-milestone` | Manage versioned milestone releases |
+| todo | `$pbr-todo` | Manage the cross-session task backlog |
+| note | `$pbr-note` | Capture a decision, observation, or idea |
+| import | `$pbr-import` | Import existing work into PBR phase structure |
+| config | `$pbr-config` | View or update workflow configuration |
+| setup | `$pbr-setup` | Configure or reconfigure PBR for this project |
+| audit | `$pbr-audit` | Analyze Codex sessions for workflow compliance |
+| help | `$pbr-help` | Show available skills and usage |
+| statusline | `$pbr-statusline` | Output a compact one-line status summary |
+| undo | `$pbr-undo` | Roll back the last plan or build step |
+
+---
+
+## File Structure Notes
+
+### Auto-generated files
+
+The following are generated from the main `plugins/pbr/` source and should not be edited
+manually. Re-run the generator script to update them:
+
+- `skills/` — all 25 skill prompts
+- `agents/` — all 11 agent definitions
+- `references/` — all reference documents
+- `templates/` — all EJS-style output templates
+- `commands/` — command registration files
+
+To regenerate:
+
+```bash
+node scripts/generate-derivatives.js codex
+```
+
+### Manual files
+
+These files cannot be auto-generated and must be maintained by hand:
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | PBR workflow guide read by Codex at session start |
+| `.codex/config.toml` | Sample Codex config with PBR agent profiles |
+| `README.md` | This file |
+
+---
+
+## More Information
+
+- Main PBR repository: [plan-build-run](https://github.com/SienkLogic/plan-build-run)
+- Codex CLI documentation: [openai/codex](https://github.com/openai/codex)
+- Claude Code plugin (`plugins/pbr/`) — the canonical source for all skills and agents
+- Cursor plugin (`plugins/cursor-pbr/`) — Cursor IDE derivative
+- Copilot plugin (`plugins/copilot-pbr/`) — GitHub Copilot derivative

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",