Skip to content

getting-started.md

Latest commit

 

History

History
112 lines (76 loc) · 6.11 KB

getting-started.md

File metadata and controls

112 lines (76 loc) · 6.11 KB
Raw

Getting started with codex-sdlc

codex-sdlc combines a Codex skills plugin with a deterministic npm CLI. The plugin teaches Codex how to initialize and coordinate delivery. The CLI creates and operates the repository's .sdlc framework.

Requirements

Version 1.0.0 includes opt-in Compact delivery and runtime-assisted task operations. Update both the plugin and project runtime to use them; existing Full-mode runs and model presets are preserved.

  • Codex with the public codex-sdlc plugin installed.
  • Node.js >=24.16.0 <25 and npm 11.
  • One or more existing application directories. The initializer configures applications; it does not scaffold product code.
  • Every checkout used by a multi-repository workspace must be a Git root with an origin remote.

Initialize through Codex

Open the repository that should own .sdlc and start a new Codex task:

Initialize codex-sdlc for this existing repository. Explain the setup choices and show the dry run before applying changes. If the CLI is unavailable, use codex-sdlc@1.0.1 through npx.

Tell Codex which applications already exist and where they live. Supported presets are Go for backend, Next.js for web, Flutter for mobile, PostgreSQL for the primary database, and Redis for cache. Codex will inspect the repository, show the proposed files, apply the same command without --dry-run, restore the pinned project runtime, and run diagnostics.

Common project shapes

For a new bounded feature using established patterns, ask $sdlc --compact <describe the feature>. Codex assesses eligibility before selecting Compact. Full remains the default and is required for migrations, breaking APIs, permission changes, new sensitive-data exposure, or unresolved risk. Compact is per run and does not change the project's model preset. See the Compact workflow.

Shape Example request
Web only Initialize this existing Next.js repository as a web-only codex-sdlc project.
Mobile only Initialize this existing Flutter repository as a mobile-only codex-sdlc project.
Backend only Initialize this existing Go repository as a backend-only codex-sdlc project using PostgreSQL and Redis.
Combined Initialize this repository with the Go backend in backend, Next.js in web, and Flutter in mobile. It uses PostgreSQL and Redis.
Multiple repositories Use this checkout as the coordinator. Map my backend, web, and mobile Git checkouts and initialize codex-sdlc in multi-repository mode.

Manual web-only initialization

Preview first:

npx --yes codex-sdlc@1.0.1 init --root /absolute/path/to/web --name example-web \
  --applications web --web-root . --web-preset nextjs --dry-run

Run the same command without --dry-run, then verify:

cd /absolute/path/to/web
node .sdlc/runtime.cjs restore
node .sdlc/runtime.cjs doctor
node .sdlc/runtime.cjs validate-config

Manual multi-repository initialization

One checkout is the coordinator and owns .sdlc. The reserved repository ID coordinator represents the path passed through --root. Map every other checkout with a stable ID and an absolute path.

This example uses the frontend checkout as the coordinator and maps a backend elsewhere:

npx --yes codex-sdlc@1.0.1 init \
  --root /absolute/path/to/frontend \
  --name example-platform \
  --workspace-mode multi-repository \
  --repo backend=/absolute/path/to/backend \
  --applications backend,web \
  --web-repo coordinator --web-root . --web-preset nextjs \
  --backend-repo backend --backend-root . --backend-preset go \
  --database-preset postgresql --redis \
  --dry-run

Run the same command without --dry-run, then restore and validate from the coordinator:

cd /absolute/path/to/frontend
node .sdlc/runtime.cjs restore
node .sdlc/runtime.cjs doctor
node .sdlc/runtime.cjs validate-config

Only the coordinator receives .sdlc. The plugin skills remain in each user's Codex plugin cache. Another contributor binds their local checkout paths with npx --yes codex-sdlc@1.0.1 configure --root <coordinator> --repo <id>=<absolute-path> and reruns doctor.

Choose single-repository or multi-repository mode before starting delivery. Version 1.0.0 does not automatically convert an initialized single-repository project to multi-repository mode. Preserve existing runs before changing topology.

Choose agent models (optional)

Ask Codex: Configure frontend to use Astra, backend to use Luna, and PM and QC to use Sol. The setup skill maps your choices to model IDs supported by your Codex host and stores them in the coordinator’s .sdlc/project.yaml. Unspecified roles inherit from Codex.

You can also ask: Enable an advisory AI Product Owner review using Sol. The review runs after QC; final acceptance remains your decision. See Choose a model for each role for exact commands, explicit fallbacks, and resetting settings. Custom role settings require plugin/runtime 0.5.0 or newer. The GPT-6.1 Sol preset ($sdlc --save-my-token) requires plugin/runtime 1.0.1 or newer; $sdlc --normal requires 0.6.0. After upgrading, reapply the token-saving preset to update existing saved settings. Existing runs keep their original model settings.

Upgrade an existing project

After installing the new plugin version, preview the project runtime upgrade:

npx --yes codex-sdlc@1.0.1 upgrade --root /absolute/path/to/coordinator --dry-run

Run the same command without --dry-run, then run node .sdlc/runtime.cjs restore, doctor, and validate-config from the coordinator. The plugin update supplies skills; the project upgrade supplies commands and schemas.

Start using the framework

After diagnostics pass, ask Codex:

Start a codex-sdlc feature delivery for <describe the requested outcome>.

Codex uses the PM, BA, backend, frontend, QC, and optional AI Product Owner skills as the work requires. Configuration, approvals, run manifests, reports, defects, and evidence remain under .sdlc/ in the coordinator repository.

Use GitHub Issues for usage questions and reproducible defects.