Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/baseinfinity/codex-sdlc-wizard

SDLC Wizard adapter for OpenAI Codex CLI. Plan is certified, implementation needed. PRs welcome!
https://github.com/baseinfinity/codex-sdlc-wizard

Last synced: about 1 month ago
JSON representation

SDLC Wizard adapter for OpenAI Codex CLI. Plan is certified, implementation needed. PRs welcome!

Awesome Lists containing this project

README 

          
# Codex SDLC Wizard



A **self-evolving Software Development Life Cycle (SDLC) enforcement system for AI coding agents**, adapted for OpenAI's Codex CLI. It makes Codex plan before coding, test before shipping, state confidence, and self-review with repo-local guardrails instead of relying on memory.



This adapter brings the [SDLC Wizard](https://github.com/BaseInfinity/agentic-ai-sdlc-wizard) discipline into Codex projects with Codex-native skills, `.codex/` hooks, `AGENTS.md`, adaptive setup/update, and proof-aware git gates.



## Quick Start



```bash

# Run adaptive interactive setup in the current repo

npx codex-sdlc-wizard@latest



# Start coding with SDLC enforcement

codex --full-auto

```



`codex --full-auto` is the recommended default once this wizard is installed: you keep the repo guardrails and hook enforcement, but day-to-day editing and runs stay low-friction. Use plain `codex` instead if you want more manual confirmation. If a handoff is interrupted and Codex prints a resume id, continue with `codex resume --full-auto ` for the same low-friction posture.



If you normally use yolo-style sessions, use Codex's explicit current flags instead: `--sandbox danger-full-access --ask-for-approval never`. Only use that full-trust variant in repos you fully trust.



Bare `npx codex-sdlc-wizard` is the adaptive interactive path. It bootstraps the repo-local guardrails first, then hands off into a live plain Codex setup session so the unresolved setup questions happen inside Codex instead of inside a shell checklist. At that first-run handoff prompt, press Enter for plain `codex` or type `full-auto` if you explicitly want `codex --full-auto`. `setup --yes` still exists for automation, but it is not the normal human path.



Generic npm entrypoint examples: `npx codex-sdlc-wizard`, `npx codex-sdlc-wizard check`, and `npx codex-sdlc-wizard update`.



`update` repairs repo artifacts using the package version you invoked; it does not self-update the npm package. To consume the newest release and apply its repo-side updates in one command, run `npx codex-sdlc-wizard@latest update`.



Package upgrade vs repo repair:



- Package upgrade: run `npx codex-sdlc-wizard@latest update` to consume the newest published package.

- Repo repair/sync inside Codex: run `$update-wizard` to inspect and repair local SDLC artifacts using the skill/package already loaded in the active Codex session.



After either path changes skills, hooks, hook config, or helper scripts, restart/reopen Codex so the active session reloads them.



Useful follow-ups after install:



```bash

npx codex-sdlc-wizard@0.7.25 check

npx codex-sdlc-wizard@0.7.25 update

```



If you want pinned release examples instead of `@latest`, see [Releases](#releases).



## What This Repo Is



This repo is now a **Codex skill plus adaptive installer-style adapter** for Codex projects.



- It ships a repo-root `SKILL.md` for the normal Codex skill install flow.

- It is **not a Codex plugin** today.

- It still ships `install.sh` / `setup.sh` when you want direct repo mutation from GitHub or npm.



| Need | Use | Why |

|------|-----|-----|

| Install a reusable Codex skill from this repo | `SKILL.md` | The repo root is now a Codex skill package for normal GitHub skill-install flow |

| Add SDLC enforcement to an existing Codex project now | `npx codex-sdlc-wizard` or `setup.sh` | The npm package bootstraps then hands off into live Codex setup; direct scripts still exist for advanced/manual shell paths |

| Install a Codex plugin from this repo | Not supported | There is no `.codex-plugin/plugin.json` package here |



## Official Codex Distribution Status



Current recommended install/discovery path: `npx codex-sdlc-wizard@latest` for repo setup, plus the repo-root `SKILL.md` / `agents/openai.yaml` package for skill installation.



Official Codex docs now clarify the packaging boundary:



- [Agent Skills](https://developers.openai.com/codex/skills): skills are the authoring format for reusable workflows.

- [Plugins](https://developers.openai.com/codex/plugins) and [Build plugins](https://developers.openai.com/codex/plugins/build): plugins are the installable distribution unit for reusable skills, app integrations, and MCP servers in Codex.



What that means for this repo:



1. Today, keep npm/npx as the supported consumer path and keep this README honest that the repo is not a plugin yet.

2. Next packaging path, when worth doing, is a real Codex plugin with `.codex-plugin/plugin.json`, bundled `skills/`, optional `.mcp.json`, optional `.app.json`, and presentation assets.

3. Local or team testing should use a plugin marketplace file at `.agents/plugins/marketplace.json`, then verify with `codex plugin marketplace add` and the CLI `/plugins` browser.

4. Official public plugin listing is not self-serve yet; self-serve plugin publishing is coming soon. Until a listing actually exists, no approval or listing is implied.



## Why Use This



You want Codex to follow engineering discipline automatically:



- **Plan before coding** instead of jumping straight to edits

- **Write tests first** and keep TDD visible in the repo contract

- **State confidence** so low-confidence work triggers research instead of guessing

- **Self-review before presenting** using Codex-native review where appropriate

- **Prove the work is shippable** with fresh test/review evidence before commit or push

- **Preserve repo truth** in `AGENTS.md`, setup docs, hooks, and skills instead of one-off chat memory



The wizard auto-detects your stack, generates repo-specific SDLC docs, installs Codex hook enforcement, and gives you `check` / `update` paths so the setup can be repaired without flattening local customizations.



## Self-Adapting SDLC Enforcement



This adapter brings the SDLC Wizard discipline into Codex today with hard guardrails, repo-local guidance, and adaptive setup/update flows that work in existing projects.



**What works today:**

- Hard enforcement hooks that block bad habits (`git commit` without proof, `git push` without review)

- AGENTS.md guidance for planning, confidence tracking, TDD, and review

- Non-destructive installer that merges into your existing Codex config

- Adaptive setup that bootstraps first and then continues inside Codex when you use the default npm entrypoint

- Task-routing guidance that sends auth-heavy browser, tenant, MFA, and admin-portal work to Desktop/computer-use before unsafe CLI/browser instructions

- `check` / `update` flows for drift detection and selective repair



**What's still coming from upstream:**

- richer scoring mechanisms and self-improvement from E2E evaluation

- more domain-adaptive guidance refinements beyond the current templates



## Self-Evolving



This adapter tracks the upstream [SDLC Wizard](https://github.com/BaseInfinity/agentic-ai-sdlc-wizard). A weekly sync workflow checks for upstream releases and opens follow-up issues here when translation work is needed.



## What This Actually Is



Five layers working together:



```text

Layer 5: SELF-IMPROVEMENT

  Upstream sync checks, roadmap issues, release proof, and pilot feedback

  keep the wizard improving without silently changing consumer repos.



Layer 4: RELEASE VALIDATION

  Packaging, npm, release, roadmap, benchmark, setup/update, and E2E

  tests verify the shipped adapter surface before tags are published.



Layer 3: ADAPTIVE SETUP / UPDATE

  Deterministic scan plus live Codex refinement generates repo-specific

  docs and repairs drift while preserving intentional customizations.



Layer 2: ENFORCEMENT

  Codex hooks block commit/push until fresh reviewed proof exists, while

  repo-scoped skills carry the explicit workflow contract.



Layer 1: LOCAL TRUTH

  AGENTS.md, START-SDLC.md, SDLC-LOOP.md, PROVE-IT.md, TESTING.md, and

  ARCHITECTURE.md keep the SDLC rules durable inside the target repo.

```



## What It Does



| SDLC Goal | Enforcement | Level |

|-----------|-------------|-------|

| TDD workflow | AGENTS.md guidance | Soft (Codex has no file-edit hooks) |

| git commit gate | PreToolUse blocks `git commit` | **Hard** |

| git push gate | PreToolUse blocks `git push` | **Hard** |

| SDLC baseline | repo docs + installed skills | **Hard/Soft mix** |

| Session init | SessionStart hook | Warns if AGENTS.md is missing |



## What Makes This Different



| Capability | Codex-specific shape |

|------------|----------------------|

| **Proof-aware git gates** | `git commit` and `git push` stay blocked until a fresh reviewed SDLC proof stamp is tied to the current repo content |

| **Codex-native review** | Uses `codex review --uncommitted`, `--base`, or `--commit`; `review_model = "gpt-5.5"` provides the intended review pass |

| **Adaptive setup/update** | Default `npx` setup bootstraps first, then hands off into Codex for unresolved questions; update repairs drift without blind overwrites |

| **Honest skill model** | `$sdlc` is the public repo-scoped workflow; helper skills stay support tooling instead of pretending Codex has slash commands |

| **Cross-platform hook shape** | Universal Node hook entrypoints avoid Bash/PowerShell hook-config churn across macOS, Linux, Windows, and `type: module` repos |

| **Auth-aware routing** | Setup docs route browser sign-in, WAM, MFA, tenant, and admin-portal boundaries to Desktop/computer-use or human-owned proof instead of unsafe CLI guesses |



### Proof-Aware Git Gate



The git gate is proof-aware: `git commit` and `git push` are still hard manual

checkpoints, but they can proceed when a fresh SDLC proof stamp exists.



After running the required checks and self-review, stamp proof:



```bash

node .codex/hooks/git-guard.cjs prove --reviewed

```



If the repo has no detected commands in `.codex-sdlc/manifest.json`, provide the

proof command explicitly:



```bash

node .codex/hooks/git-guard.cjs prove --reviewed --check "npm test"

```



The stamp lives under `.git/codex-sdlc/proof.json`, expires after four hours,

and is tied to the current repo content, so stale proof blocks again instead of

dirtying the worktree.

For safety, guarded `git commit` / `git push` commands that change repo context

with `cd`, `git -C`, `--git-dir`, `--work-tree`, `GIT_DIR`, or `GIT_WORK_TREE`

must be run from the target repo root and stamped there.



## Model Profiles



The wizard supports two wizard-owned model profiles:



- `mixed`: `gpt-5.4-mini` for the main pass plus `gpt-5.5` at `xhigh` for review.

  Tradeoff: better speed, lower latency, and lower token usage on routine work after bootstrap.

- `maximum`: `gpt-5.5` at `xhigh` throughout.

  Tradeoff: higher latency and token usage in exchange for the most stable and thorough "ultimate mode."



How to choose:



```bash

# recommended interactive bootstrap path

npx codex-sdlc-wizard@0.7.25 --model-profile maximum



# interactive bootstrap with the efficiency-first profile if you already know you want it

npx codex-sdlc-wizard@0.7.25 --model-profile mixed



# floating latest release with the same bootstrap recommendation

npx codex-sdlc-wizard@latest --model-profile maximum

```



Interactive setup should ask which profile you want when you do not pass `--model-profile`, and it should recommend `maximum` as the safer bootstrap default.



Low-confidence rule:

- Default to `xhigh` in this repo when the work is meta, setup-heavy, or otherwise high-blast-radius.

- if confidence is below `95%`, research more first

- if it still stays below `95%`, escalate review to `xhigh`

- prefer `maximum` for abstract, complex, or high-blast-radius work



The wizard stores the selected profile in `.codex-sdlc/model-profile.json` so the repo can keep that choice explicit.

It also writes the matching repo-local Codex config to `.codex/config.toml` so trusted Codex sessions use the selected profile instead of silently inheriting stronger user-level defaults.



`mixed` is wizard policy, not a native Codex mode. The wizard maps it to:



```toml

model = "gpt-5.4-mini"

model_reasoning_effort = "xhigh"

review_model = "gpt-5.5"



[features]

hooks = true

```



`maximum` maps to:



```toml

model = "gpt-5.5"

model_reasoning_effort = "xhigh"



[features]

hooks = true

```



Codex only loads project-local `.codex/config.toml` for trusted projects. Once trusted, project config overrides user config in `~/.codex/config.toml`; the wizard does not edit your global config. Current Codex CLI builds warn that `[features].codex_hooks` is deprecated, so setup/update write `[features].hooks = true` and migrate active `codex_hooks` entries when repairing config.



Bootstrap recommendation:

- setup/update should use `maximum`; routine work after bootstrap should use `mixed`

- use `maximum` for setup/update because bootstrap work has higher blast radius

- switch back to `mixed` for routine day-to-day work after the repo is stable



Repo-specific maintainer rule:

- consumer repos can choose `mixed` or `maximum`

- this repo always stays on `maximum` (`gpt-5.5` at `xhigh` throughout); do not switch `codex-sdlc-wizard` maintenance to `mixed`, mini-only, or lower-reasoning profiles because it is unusually meta and high-blast-radius



## Native Codex Review



Review behavior is required by the SDLC contract. The portable Codex-native review path is `codex review`:



```bash

# Review staged, unstaged, and untracked local changes before commit

codex review --uncommitted



# Review a branch or PR-sized diff against a base branch

codex review --base main



# Review one already-created commit

codex review --commit 

```



When `review_model = "gpt-5.5"` is present, native Codex review uses that model for the review pass. In `mixed`, this gives the intended cross-model shape: faster main work, `gpt-5.5` review.



Do not treat `/autoreview` as a required SDLC command. `auto_review` is a Codex approval-review setting for eligible tool approval prompts; it is not the code-diff review path. In yolo/full-bypass sessions, approval review usually does not apply because approvals are already bypassed.



## Repo-Scoped Skills



`install.sh` and `setup.sh` scaffold repo-local Codex skills under `.agents/skills`.



Repo-scoped skill coverage is still a work in progress:



- `$sdlc` is the supported public workflow skill today

- additional repo-scoped workflows stay unnamed until their public contracts are ready



Canonical entrypoint: `$sdlc`. `/sdlc` is historical shorthand for the missing slash-command idea, not an invocation command. Adapter-specific SDLC aliases are legacy migration debris and should not appear as second user-facing workflows.



Codex treats same-name skills from different scopes as distinct choices. To avoid duplicate `$sdlc` workflow rows, normal setup installs global helper skills only (`feedback`, `setup-wizard`, and `update-wizard`) and keeps `.agents/skills/sdlc` as the canonical repo-scoped workflow.



These are Codex-native skill folders, so a fresh Codex session can discover them directly from repo scope. After install or setup, restart Codex so repo-scoped skills are loaded cleanly.



The bridge here is explicit, not magical: this adapter ships the Codex-native skill copies that target repos consume. It does not depend on local `.claude/skills/*` paths being present in the target repo.



## Honest Codex SDLC Shape



The current recommended Codex-native architecture is explicit:



- `skills = explicit workflow layer`

- `hooks = silent event enforcement`

- `repo docs = source of local truth`



That means:

- use repo-scoped or installed skills for the user-facing workflow contract

- use hooks to block or warn silently at the right events

- keep `AGENTS.md`, `ARCHITECTURE.md`, `TESTING.md`, and related repo docs as the local source of truth



What not to do:

- do not pretend Codex has native slash commands when it does not

- do not overload hooks to act as the user-facing workflow layer



## Feedback Flow and Repo Focus



When you dogfood this wizard in a product repo, keep the active session focused on that product repo.



- if you discover a **proven reusable** wizard lesson, prefer filing a **direct GitHub issue** in `codex-sdlc-wizard` right away

- if you are reporting a consumer-facing failure, use the repo's **Consumer bug report** template so command, repo shape, failed step, and auth context are captured consistently

- keep building the **product repo** in the current session

- only switch into live wizard work when the product repo is **actually blocked**



This keeps dogfooding useful without turning every implementation session into wizard meta-work.



## Releases



Versioned releases for this adapter live at:



https://github.com/BaseInfinity/codex-sdlc-wizard/releases



If you are consuming this repo in a real project, prefer a tagged release over `main`.



```bash

# npm / npx pinned to the current release

npx codex-sdlc-wizard@0.7.25



# npm / npx floating on the newest published release

npx codex-sdlc-wizard@latest



# Codex skill install

# Install this repository through the normal GitHub skill-install flow

# so $codex-sdlc-wizard is available inside Codex



# git-based install

git clone --branch v0.7.25 --depth 1 https://github.com/BaseInfinity/codex-sdlc-wizard.git /tmp/codex-sdlc-wizard

```



### Maintainer Release Flow



This adapter should follow the same semver-tag plus GitHub Release rhythm as the upstream wizard.

Use [RELEASE.md](RELEASE.md) as the mandatory pre-tag checklist: sync to latest `origin/main`, run the full proof suite, and only then tag.



```bash

# After tests pass on main

git tag vX.Y.Z

git push origin vX.Y.Z

```



Pushing a `vX.Y.Z` tag triggers this repo's release workflow, publishes the npm package, and publishes GitHub Release notes automatically. `workflow_dispatch` exists as a retry path for an existing tag if a release job needs to be rerun.



To enable npm publish from GitHub Actions, configure npm trusted publishing for this package instead of storing a long-lived token:



1. Open the npm package settings for `codex-sdlc-wizard`

2. Go to `Trusted publishing`

3. Choose `GitHub Actions`

4. Configure:

   `Organization or user`: `BaseInfinity`

   `Repository`: `codex-sdlc-wizard`

   `Workflow filename`: `release.yml`

   `Environment name`: leave blank unless you later add a protected GitHub environment



The workflow uses GitHub OIDC trusted publishing, validates that the tag matches `package.json`, and skips `npm publish` on reruns when that exact version already exists on npm. No `NPM_TOKEN` GitHub secret is required.



### What `install.sh` Changes



1. Copies `AGENTS.md` (skips if exists, so your customizations are safe)

2. Copies `SDLC-LOOP.md`, `START-SDLC.md`, and `PROVE-IT.md` if missing

3. Creates or merges `.codex/config.toml` with `[features].hooks = true`

4. Installs `.codex/hooks.json` (backs up existing)

5. Copies universal Node hook entrypoints plus legacy shell/PowerShell helpers to `.codex/hooks/`

6. Installs the repo-scoped SDLC skill at `.agents/skills/sdlc/SKILL.md`

7. Installs global helper skills under `~/.codex/skills` without installing a global `sdlc` duplicate



In other words, `install.sh` mutates the target repo by adding or updating `AGENTS.md`, `.codex/config.toml`, `.codex/hooks.json`, `.codex/hooks/*`, and the repo-scoped SDLC skill. It also writes `.codex-sdlc/model-profile.json` so the chosen profile is explicit. Existing `.codex/config.toml` files are merged: model keys and `[features].hooks` are patched, active deprecated `[features].codex_hooks` entries are migrated away, and MCP, sandbox, approval, and other custom settings are preserved. If an older wizard-managed global `sdlc` skill is detected, update/setup backs it up and removes it; user-owned global `sdlc` skills are preserved.



After restart, hook install is not complete until Codex trusts the repo and any pending repo hooks are reviewed. If Codex reports hooks need review, open `/hooks` and review the pending hooks before relying on SDLC enforcement.



### Requirements



- Codex CLI (`npm i -g @openai/codex`)

- `bash` (3.x+ macOS, 4.x+ Linux, Git Bash on Windows for the shell path)

- Node.js 18+; active Codex hooks use Node entrypoints so the same checked-in hook config works across macOS, Linux, and Windows



## E2E Proven



All hooks are verified in real Codex CLI sessions, not just unit tested in isolation.



## Testing



```bash

# Top-level maintainer proof runner (parallel by default, serial for debugging)

node scripts/run-proof-suite.cjs

node scripts/run-proof-suite.cjs --serial



# Release contract tests (workflow + docs)

bash tests/test-release.sh



# Packaging smoke test (clean temp project, validates install path)

bash tests/test-packaging.sh



# Codex skill package smoke test

bash tests/test-skill.sh



# npm / npx packaging smoke test, including the packed-tarball scratch smoke

bash tests/test-npm.sh



# Unit tests (no API calls, fast)

bash tests/test-adapter.sh

bash tests/test-setup.sh

bash tests/test-update.sh



# E2E tests (opt-in: requires codex CLI + auth, consumes tokens)

CODEX_E2E=1 bash tests/test-e2e.sh

```



- `node scripts/run-proof-suite.cjs` runs the maintainer proof suite with bounded parallel jobs and per-check logs; use `--serial` when debugging ordering-sensitive failures.

- Release contract tests for semver tags, GitHub Releases, and README release docs

- Packaging smoke tests for the documented installer path and README packaging contract

- Skill packaging tests for SKILL.md, agents/openai.yaml, and dual-distribution docs

- npm packaging smoke tests for package metadata, packed contents, and npm exec

- Adapter, setup, and update tests for the Codex-specific behavior surface

- E2E integration tests are token-consuming and opt-in; use `CODEX_E2E=1 bash tests/test-e2e.sh` when you explicitly want real Codex sessions proving hooks fire



## Documentation



| Document | What It Covers |

|----------|----------------|

| [AGENTS.md](AGENTS.md) | Repo contract for planning, confidence, TDD, review, and model profile policy |

| [START-SDLC.md](START-SDLC.md) | Quick operator entrypoint for starting SDLC work in an installed repo |

| [SDLC-LOOP.md](SDLC-LOOP.md) | Repeatable plan -> test -> implement -> review -> prove loop |

| [PROVE-IT.md](PROVE-IT.md) | Proof-stamp gate for commit/push and examples for explicit check commands |

| [RELEASE.md](RELEASE.md) | Maintainer release checklist before semver tags and npm/GitHub release publish |

| [ROADMAP.md](ROADMAP.md) | Current shipped state, next release cycle, and backlog ordering |



## Upstream



Based on [agentic-ai-sdlc-wizard](https://github.com/BaseInfinity/agentic-ai-sdlc-wizard). Same SDLC philosophy, translated to Codex's current tool model with Codex-native skills, repo hooks, and adaptive setup/update flows.



## Feedback



Three ways to report bugs, request features, or ask questions:



- **In-session:** run `$feedback` when installed; it is privacy-first and redacts sensitive context before preparing a report.

- **Consumer bug report:** use the [consumer bug report template](https://github.com/BaseInfinity/codex-sdlc-wizard/issues/new?template=consumer-bug-report.yml) for install/setup/runtime failures.

- **Issues:** open a normal GitHub issue for feature requests, docs gaps, or proven reusable wizard findings.



## Community



Come join **[Automation Station](https://discord.com/invite/fGPEF7GHrF)** — a community Discord packed with software engineers bringing 40+ years of combined experience across every area of the stack (frontend, backend, infra, embedded, data, QA, DevOps, you name it). Share patterns, ask questions, compare notes on AI agents, automation, and SDLC tooling.



## License



MIT