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 discipline into Codex projects with Codex-native skills, .codex/ hooks, AGENTS.md, adaptive setup/update, and proof-aware git gates.

Which entry point should I use?

Think of the plugin, installer skill, and repo skill as three consecutive layers:

What you are doing	Use	How often
Install or enable the package	Codex SDLC Wizard in the Desktop Plugins Directory, or /plugins in Codex CLI	Once per supported surface
Set up or repair the current repository	$codex-sdlc-wizard with the target repo selected	Once per repo, then whenever setup needs repair
Plan, implement, test, and review normal repo work	$sdlc	Every meaningful delivery task after setup
Pull the newest npm release and update repo artifacts before the public listing is available	npx codex-sdlc-wizard@latest update	When you intentionally want the newest published package

The plugin is the installable container; $ opens the skill picker, so it should show the plugin's Install SDLC Guardrails skill rather than a second plugin row. After setup, restart or reopen Codex in the repository before invoking $sdlc so the repo-local config, hooks, docs, and skill are loaded.

Use the default maximum profile for normal work: GPT-5.6 Sol at high. The mixed profile is an experimental explicit opt-in using Terra at medium with a Sol high review. Luna is currently a bounded support option, not an install-time profile.

These workflows work in Codex Desktop, Codex CLI, and ChatGPT Work when the active project can access the repository and a shell. Ordinary Chat can display the installed plugin in its directory but cannot invoke repo-local skills; switch to Work or Codex for installation and delivery work.

For a Claude-driven Windows adoption test against a real product repository, use the Windows Codex Desktop real-install E2E runbook.

Quick Start

# Setup a new repo or sync an already-initialized clone
npx codex-sdlc-wizard@latest

# Start coding with SDLC enforcement and an explicit model profile
codex -m gpt-5.6-sol -c 'model_reasoning_effort="high"'

codex -m gpt-5.6-sol -c 'model_reasoning_effort="high"' is the recommended explicit consumer start once this wizard is installed. Use plain codex instead if you want to rely on trusted repo-local config. If a handoff is interrupted and Codex prints a resume id, continue with codex resume -m gpt-5.6-sol -c 'model_reasoning_effort="high"' <session-id> so resume does not fall back to an older model.

If you normally use yolo-style sessions, use Codex's canonical full-trust flag: --dangerously-bypass-approvals-and-sandbox. Current Codex may accept --yolo as shorthand, but this wizard prints the canonical flag. Full-auto is not full-trust: full-trust bypasses sandbox and approval prompts. Only use that variant in repos you fully trust.

Bare npx codex-sdlc-wizard is the adaptive setup/sync path. In an already-initialized repo clone, it runs the update/check-repair path automatically so a fresh Mac/Windows/Linux checkout can sync hooks, config, and helper skills without remembering separate commands. In a new repo, 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-trust if you explicitly want codex --dangerously-bypass-approvals-and-sandbox. 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 from an initialized repo, or use the explicit form 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.

The deterministic updater preserves a specialized AGENTS.md unless its bytes match a separately recorded generator-owned baseline. It never treats a stale managed-file hash as ownership proof. For customized repositories, use $update-wizard to inspect and explicitly merge only the necessary policy delta while preserving the repository contract.

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:

npx codex-sdlc-wizard@0.7.38 check
npx codex-sdlc-wizard@0.7.38 update

If you want pinned release examples instead of @latest, see Releases.

Optional GOALS.md

For long-running work, add an active-scope contract with:

npx codex-sdlc-wizard@latest setup --yes --goals

GOALS.md is separate from ROADMAP.md: keep ROADMAP.md as backlog/history, and use GOALS.md for the current active run. Its operating phrase is: complete everything in GOALS.md until the user says stop.

The template includes active goals, deferred work, definition of done, runtime boundary, evidence contract, and a paste-ready $sdlc prompt. This prevents “active goal complete” from being confused with “whole roadmap complete.”

Codex /goal With SDLC

Use Codex /goal for long-running roadmap work only after this repo has a real $sdlc setup. Treat the goal as an SDLC-backed active task, not as a substitute for planning, tests, review, proof, or repo-local instructions.

A good goal should include:

• the current GOALS.md, roadmap slice, or milestone
• $sdlc as the mandatory delivery contract
• any additional repo-local skills that are already installed and relevant
• the 95% confidence rule, including stopping to research or hand back when confidence drops
• RED/GREEN tests, focused checks, full tests/lint when code or config changed, and native review/self-review
• a clean break requirement: docs updated, evidence recorded, and changes committed locally before claiming the active task is done

Suggested manual /goal text:

Get as far as possible through GOALS.md in small, shippable slices. Follow $sdlc for every code/doc change and include any relevant repo-local skills already installed here. Keep confidence >=95%; if confidence drops, research or stop at a clean handoff point. Use RED/GREEN tests, focused checks, full tests/lint when code or config changed, and native review/self-review before shipping. Stop only at a clean break with evidence recorded and changes committed locally.

What This Repo Is

This repo is a skills-only plugin plus adaptive installer-style adapter for Codex projects.

• .codex-plugin/plugin.json makes the repository and npm package an installable Codex plugin.
• The plugin exposes one Codex skill at skills/codex-sdlc-wizard/SKILL.md; the legacy repo-root copy is gone, so recursive discovery cannot load the same installer twice.
• The plugin does not bundle MCP servers or declare plugin-level hooks. install.sh / setup.sh remain the adaptive repo-mutation path that writes repository-scoped skills, hooks, config, and guidance.

Need	Use	Why
Install from the shared plugin directory	Codex SDLC Wizard	The same skills-only plugin package can be loaded in ChatGPT Work, the Codex desktop app, and Codex CLI
Inspect the plugin skill source	skills/codex-sdlc-wizard/SKILL.md	Inspection-only: the skill depends on scripts at the plugin root, so install the complete plugin instead of this directory alone
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

Official Codex Distribution Status

The source and npm tarball are now plugin-ready. Until the public directory listing is accepted, npx codex-sdlc-wizard@latest remains the reliable public repo-setup path.

Official Codex docs now clarify the packaging boundary:

• Skills and plugins: skills are the authoring format for reusable workflows.
• Plugins and Build plugins: plugins are the installable distribution unit for reusable skills, app integrations, and MCP servers.

What that means for this repo:

1. ChatGPT Work, the Codex desktop app, and Codex CLI draw public plugins from the same universal directory, but installation and enablement are surface-specific. Install or enable the plugin on each intended surface, then start a fresh thread or session there so it reloads the plugin.
2. In ChatGPT Work, invoke the plugin with @Codex SDLC Wizard. In Codex, invoke its installer skill with $codex-sdlc-wizard; after repo setup, use the generated repo-scoped $sdlc workflow for delivery work.
3. Ordinary Chat mode does not support plugins. Switch to Work or Codex when the task needs this plugin. A ChatGPT Work project without local repository/shell access can explain or plan the setup, but the mutating install must run in Codex desktop, Codex CLI, or another environment that can access the target repo.
4. The official plugin submission portal is live. This package's public listing is pending validation and submission; no official OpenAI endorsement is implied.

Migrate the legacy standalone skill

Releases through 0.7.33 could be installed directly at ~/.codex/skills/codex-sdlc-wizard. Installing the plugin does not remove that old directory, so Codex can discover two copies of the installer skill. Before using the plugin, move the stale standalone copy to a recoverable backup outside the active skills/ directory. The default backup location is ~/.codex/skill-backups:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skill-backups"
mv "${CODEX_HOME:-$HOME/.codex}/skills/codex-sdlc-wizard" \
  "${CODEX_HOME:-$HOME/.codex}/skill-backups/codex-sdlc-wizard-standalone"

Skip the mv when the legacy path does not exist. If the backup destination already exists, choose another name instead of overwriting it. Start a fresh thread or session after the move so ChatGPT Work or Codex reloads plugin discovery without the duplicate.

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. 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:

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
  compact lifecycle hooks preserve SDLC state across context compaction and
  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
Compact lifecycle	PreCompact/PostCompact compact guard	Warns with SDLC carry-forward context
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	Reuses one stamped broad proof in a prompt-only Sol-high code review; predefined --uncommitted, --base, and --commit targets remain available for reviews without a custom prompt
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 focused checks and self-review, run required broad verification through the proof-stamping command:

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

For this repository's maintainer suite, use the single canonical command below. It runs all proof groups once and writes the receipt in that same invocation:

node .codex/hooks/git-guard.cjs prove --reviewed --check "node scripts/run-proof-suite.cjs"

If the repo has no detected commands in .codex-sdlc/manifest.json, provide the proof command explicitly:

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

Every Invoke-Pester proof command must explicitly propagate test failures with -EnableExit or Pester 5's -CI switch (for example, Invoke-Pester -Path tests -CI). The proof runner rejects a Pester command without either switch because Pester can otherwise report failed tests while the PowerShell process exits successfully. The switch must be literal on the Invoke-Pester command; configuration objects and splatted parameters are not statically accepted, so rewrite those proof commands to use a direct -CI or -EnableExit invocation. Proof commands also cannot define aliases, launch background jobs, or wrap PowerShell inside another shell command; invoke the checked command directly in the proof host.

If a non-PowerShell project currently uses a wrapper such as pwsh -File tests.ps1, make the proof configuration explicitly PowerShell and store the inner command instead. In .codex-sdlc/manifest.json, set scan.language to "PowerShell", then use a direct command such as & ./tests.ps1. The script itself must return a nonzero process status when its tests fail. Because language selects the proof host for every configured check, a mixed shell/PowerShell proof set must be consolidated into one PowerShell runner (and the other proof-command fields cleared); that runner must invoke each check and return nonzero if any check fails.

The stamp lives in Git metadata under codex-sdlc/proof.json, expires after four hours, and is tied to the current worktree content, so stale proof blocks again instead of dirtying the worktree. A guarded git -C <path> commit or git -C <path> push may use fresh proof from a same-repository linked worktree; the guard verifies that both worktrees share the same physical Git common directory. Unrelated repositories and other context changes—including cd, --git-dir, --work-tree, GIT_DIR, and GIT_WORK_TREE—remain blocked and must be handled from a session rooted in the target repository. Inherited GIT_NAMESPACE and GIT_OBJECT_DIRECTORY also remain blocked because they retarget ref or object writes even when the worktree path itself is unchanged. When an agent commits or pushes from a linked worktree, it must put the absolute target directly in the standalone git -C <path> ... command instead of relying only on the execution tool's workdir; some Codex surfaces omit that field from the PreToolUse payload.

Model Profiles

The wizard supports two wizard-owned model profiles:

• maximum: gpt-5.6-sol at high throughout. Sol high is the quality-first default and normal standing root driver for meaningful SDLC work, with flagship stability and depth. maximum selects the maximum model tier; it does not select Max reasoning.
• mixed: experimental explicit opt-in using gpt-5.6-terra at medium for the main pass plus a gpt-5.6-sol review that must explicitly override reasoning to high. It exists for measured speed, lower latency, or lower token-usage trials; it is not the routine-work recommendation.

How to choose:

# recommended interactive bootstrap path
npx codex-sdlc-wizard@0.7.38 --model-profile maximum

# experimental efficiency trial when you explicitly choose it
npx codex-sdlc-wizard@0.7.38 --model-profile mixed

# floating latest release with the same bootstrap recommendation
npx codex-sdlc-wizard@latest --model-profile maximum

Interactive setup asks which profile you want when you do not pass --model-profile, and recommends maximum as the normal Sol-high default.

Adaptive reasoning rule:

• the consumer default for meaningful SDLC and agentic coding is Sol high; keep the Sol root as the standing driver
• use Terra or Luna only for bounded support tasks, or select mixed explicitly for a measured experiment with strong verification
• setup records detected deployment, database, CI, and firmware surfaces so generated guidance can name repo-specific escalation scopes
• use xhigh for security review, migrations, destructive operations, long-running research, or difficult coding where high leaves unresolved risk
• if confidence is below 95%, research more first
• if it still stays below 95%, escalate the difficult slice or review to xhigh
• prefer maximum for abstract, complex, or high-blast-radius work
• use max only as a single-task reasoning escalation when xhigh evidence is insufficient
• use ultra only as a subagent-backed parallel-work escalation when the task divides cleanly into independent workstreams
• most tasks do not need Max or Ultra, and neither belongs in default wizard profiles

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:

model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
review_model = "gpt-5.6-sol"

[features]
hooks = true

maximum maps to:

model = "gpt-5.6-sol"
model_reasoning_effort = "high"
review_model = "gpt-5.6-sol"

[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:

• install/setup/update default to maximum, and normal agentic work stays on its Sol high driver
• profile-less updates restore maximum; updates preserve an existing explicit mixed selection instead of silently overriding it
• mixed remains experimental and explicit opt-in until representative local measurements prove it preserves quality
• use gpt-5.6-terra or gpt-5.6-luna manually only for bounded low-risk support work with an explicit verification boundary

Repo-specific maintainer rule:

• consumer repos can choose mixed or maximum
• this repo stays on maximum (gpt-5.6-sol at high); do not switch codex-sdlc-wizard maintenance to mixed, Terra, Luna, or lower-tier profiles because it is unusually meta and high-blast-radius
• escalate only difficult or high-risk slices to xhigh when high leaves unresolved risk

Native Codex Review

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

# Review staged, unstaged, and untracked local changes before commit
codex review --uncommitted

# Enforce the advertised Sol-high review gate, including from mixed mode
codex -c 'model_reasoning_effort="high"' 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 <sha>

# Proof-aware custom review: prompt only; do not add a predefined target flag
codex -c 'model_reasoning_effort="high"' review 'Review only this frozen diff. Base: <base-commit-or-tree>. Candidate: <candidate-tree>. Proof: <command> => <result>. Do not rerun tests. Return prioritized code-review findings only.'

When review_model = "gpt-5.6-sol" is present, native Codex review uses Sol for the review pass. review_model does not set review reasoning independently: effort otherwise inherits the profile's global model_reasoning_effort. Mixed-mode agents must therefore use the explicit high override above (and the same prefix with --base or --commit) to provide the advertised Sol-high gate.

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.

Run one broad proof run total on the frozen candidate through the proof-stamping entrypoint. Do not run the suite directly and then rerun it through the guard. When supplying custom proof-aware instructions, use a prompt-only review. A custom prompt must not be combined with --uncommitted, --base, or --commit; those predefined target flags are for reviews without a custom prompt. Include the exact base identity, frozen candidate tree identity, proof command, and result, and say Do not rerun tests. Targeted verification is allowed only for a concrete suspected defect; never rerun the broad suite.

When your repo policy requires a cross-model final gate, run Fable High only after the Sol review is clean:

node .codex/hooks/fable-review.cjs --base main --consent-subscription-quota

The consent flag is required because the review consumes Claude subscription quota. The wrapper verifies Claude first-party subscription auth, refuses API keys and alternate providers, disables tools/MCP/session persistence, reuses the current SDLC proof, and writes a candidate-bound receipt under Git metadata. It does not create a metered API-key charge when the verified subscription lane is used.

When policy requires both reviewers to certify one completion candidate, use the bounded joint gate instead:

node .codex/hooks/dual-review.cjs --base main --consent-subscription-quota

Sol High and Fable High review the same frozen candidate independently. Clean agreement stops after those two reviews. A verdict split gets exactly one verbatim cross-feed round, then the wrapper writes one conservative candidate-bound joint receipt; it never starts an unbounded reviewer dialogue.

Once the joint receipt is certified, deliver that exact candidate through the fixed-argv boundary rather than rebuilding the sequence with separate shell commands:

node .codex/hooks/dual-review.cjs deliver github \
  --message "feat: describe the certified change" \
  --branch feature-branch \
  --base main \
  --title "Describe the certified change" \
  --body "Closes #123"

The command commits the certified staged tree while honoring configured Git hooks, pushes its immutable SHA, creates or reuses the explicitly targeted PR, verifies the authoritative head/base and at least one completed check, then atomically advances the unchanged base to that exact commit. An empty check rollup waits and fails closed by default; use --allow-no-checks only when the repository intentionally has no GitHub checks. A changed base, failing hook, failing check, or protected branch blocks integration. deliver direct is available only for an explicitly intended non-GitHub path; it verifies the exact remote ref but does not claim GitHub CI semantics. This is immediate exact-SHA integration after verification, not GitHub auto-merge.

Incremental checkpoints and the completion boundary

For each coherent green slice, run affected proof, author-review the exact incremental diff, and use at most one risk-based reviewer before committing. During the ten-delivery pilot, the completion boundary is deliberately broader: freeze the candidate, run the broad proof once, and send the whole base-to-candidate diff through the bounded Sol High plus Fable High joint gate above. Outside the pilot, use Fable only when cross-model policy requires it. Fix a blocker as one bounded corrective delta with targeted proof. A third same-plan correction means stop; human approval may authorize a replan with newly scoped work, not silently extend the exhausted plan.

This cadence is a measured ten-delivery pilot, not permanent ceremony. Record delivery, duplicate-proof, per-reviewer disposition and confidence, reconciliation, quota/token cost, correction, tripwire, CI, milestone, and release outcomes in benchmarks/review-cadence.csv, then run bash scripts/summarize-review-cadence.sh. After ten eligible deliveries across at least two strategies, a human compares the arms and chooses whether to keep, tune, or sunset it.

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.

The repository keeps helper definitions under skill-sources/ as SKILL.template.md installer inputs, not directly discoverable plugin skills. Setup/update materialize the standard SKILL.md filename only in each intended direct global helper destination.

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

Codex CLI 0.144.0+, required for these GPT-5.6 profiles, supports eight hook events: PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, UserPromptSubmit, and Stop.

This wizard actively installs SessionStart, PreToolUse, PreCompact, and PostCompact. The remaining hook events are intentionally left unused until there is a proven SDLC need: PermissionRequest can change approval behavior, PostToolUse can create noisy post-command gates, UserPromptSubmit can over-police prompts, and Stop can interfere with normal session shutdown.

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

0.7.38 adds one fixed-argv delivery boundary for a certified candidate. It commits the exact reviewed tree while honoring configured Git hooks, pushes immutable object IDs, verifies the authoritative GitHub PR identity and at least one completed check by default, and atomically integrates only when the reviewed base is unchanged. This removes the fragile multi-command handoff that could read the wrong worktree or publish something other than the reviewed candidate. It includes the Desktop-safe linked-worktree guidance and bounded-review improvements from 0.7.37.

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.

# npm / npx pinned to the current release
npx codex-sdlc-wizard@0.7.38

# 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.38 --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 as the mandatory pre-tag checklist: sync to latest origin/main, run the full proof suite, and only then tag.

# 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.

Installed hook entrypoints are quiet and current-Codex aware: git-guard.cjs handles PreToolUse commit/push gates, session-start.cjs handles SessionStart baseline warnings, and compact-guard.cjs handles PreCompact/PostCompact SDLC carry-forward reminders.

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 0.144.0+ (npm install -g @openai/codex@latest)
• 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

# 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
• Plugin-skill packaging tests for skills/codex-sdlc-wizard/SKILL.md, its 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	Repo contract for planning, confidence, TDD, review, and model profile policy
START-SDLC.md	Quick operator entrypoint for starting SDLC work in an installed repo
SDLC-LOOP.md	Repeatable plan -> test -> implement -> review -> prove loop
PROVE-IT.md	Proof-stamp gate for commit/push and examples for explicit check commands
GOALS.md	Optional active-scope contract for long-running work; generated with setup --goals
RELEASE.md	Maintainer release checklist before semver tags and npm/GitHub release publish
ROADMAP.md	Current shipped state, next release cycle, and backlog ordering

Upstream

Based on 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 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 — 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

AI Setup Lanes

One default driver plus two bounded alternatives in AI_SETUP_LANES.md:

Lane	Main work	Review/escalation	When
A - Sol Quality-First	GPT-5.6 Sol high	Sol high; xhigh for difficult/high-risk slices	Normal meaningful SDLC work, architecture, releases, security
B - Experimental Mixed	GPT-5.6 Terra medium	Sol high via explicit override; xhigh when risk remains	Explicit measured efficiency trials only
C - Lightweight Support	GPT-5.6 Terra/Luna at the lowest reliable effort	Sol root integrates and accepts	Clear, repeatable, low-risk support tasks

The root agent normally owns planning. Explorer, reviewer, or planner agents are optional specializations, and Ultra is reserved for work that benefits from real parallel subagents.