codex-sdlc

View saved version →

---
name: sdlc
description: Handle /sdlc or $sdlc feature requests, including opt-in --compact delivery and --save-my-token or --normal project model presets, and route work to sdlc-pm.
---

# SDLC entry point

Treat `/sdlc --save-my-token` and `/sdlc --normal` as chat shorthand for this skill. Explicit skill invocation is `$sdlc --save-my-token` or `$sdlc --normal`; this plugin does not register a native Codex slash command. If the client rejects `/sdlc` before sending the prompt, use the explicit skill form.

## Project model mode

1. Resolve the selected project's coordinator directory and read its `AGENTS.md` and `.sdlc/project.yaml`. In a multi-repository workspace, the coordinator owns this setting for all mapped applications. Never select a different project or write global Codex settings. If the coordinator is unknown, ask for its location. If the project is not initialized, explain that setup is required; use [sdlc-setup](../sdlc-setup/SKILL.md) when initialization is requested rather than inventing application roots.
2. Accept exactly one of `--save-my-token` and `--normal`. Both together, or either combined with custom role model, effort, fallback, reset, or PO settings, are conflicting requests: explain the conflict without changing configuration. Custom role changes can be made separately through [sdlc-setup](../sdlc-setup/SKILL.md).
3. From the coordinator, run the corresponding command below with `--dry-run --json` first. Inspect the returned settings. An explicit mode request authorizes saving that preset: unless the user asked only for a preview, run the same command without `--dry-run`. Do not ask for another confirmation for the requested mode. If the runtime rejects the new flag, report that its version lacks this feature and use the setup upgrade workflow with version 0.6.0 or newer. Do not rewrite project configuration manually or claim success after a failed command.

   ```sh
   node .sdlc/runtime.cjs configure-agents --save-my-token --dry-run --json
   node .sdlc/runtime.cjs configure-agents --save-my-token --json
   ```

   Or, for normal mode:

   ```sh
   node .sdlc/runtime.cjs configure-agents --normal --dry-run --json
   node .sdlc/runtime.cjs configure-agents --normal --json
   ```

4. Report the saved project and role settings from the successful result. Settings apply to every new run in that project until changed. Existing runs keep their snapshots. A mode-only request ends here; it does not create or resume a delivery run. If the same request includes a new feature, save the mode before routing that feature to [sdlc-pm](../sdlc-pm/SKILL.md). Resuming a run keeps that run's original policy even after saving a mode.

| Role | `--save-my-token` | `--normal` |
| --- | --- | --- |
| PM | Inherited | Inherited |
| BA | `gpt-6-sol`, `high` | Inherited |
| Backend | `gpt-6-luna`, `xhigh` | Inherited |
| Frontend (web and mobile) | `gpt-6-luna`, `xhigh` | Inherited |
| QC | `gpt-6-luna`, `xhigh` | Inherited |

`xhigh` means extra-high reasoning. Both presets replace these five roles' previous models, efforts, and fallbacks. Normal mode restores inheritance rather than restoring earlier custom models. Both preserve optional AI Product Owner settings. No fallback is added. Dispatch still checks the host's model and reasoning capabilities; report an unavailable selection instead of silently substituting another model. The preset is a model configuration, not a guarantee about token usage.

## Delivery requests

For `$sdlc --compact <feature>` or `/sdlc --compact <feature>`, follow the [Compact workflow](../sdlc-pm/references/compact-workflow.md). Compact applies only to that new run and requires a complete low-risk assessment. Full remains the default. An existing run retains its saved profile; do not convert it during resume. If Compact is unsuitable, explain why Full is required before starting a new Full run. A standalone `--compact` without a feature does not start work or change project configuration. If an explicitly requested model preset accompanies the feature, save it first and then apply the independently selected workflow profile.

For a feature request or explicit resume without either mode flag, use [sdlc-pm](../sdlc-pm/SKILL.md) and preserve the saved project mode. A bare `/sdlc` or `$sdlc` explains the two mode commands and asks what feature to start or run to resume; it does not reset models or start unspecified work.

Referenced files: 1

View saved version →

---
name: sdlc-ba
description: Use when an active SDLC run needs feature requirements, typed fact-to-claim reconciliation, user stories, acceptance criteria, business rules, validation, edge cases, assumptions, open questions, or traceability.
---

# SDLC Business Analysis

For a saved Compact run, follow the [Compact specification path](../sdlc-pm/references/compact-workflow.md): author one semantic specification through `compact-spec`, and let the runtime derive fact claims and acceptance views. The seven-document envelope below applies to Full/legacy evaluator work. Compact still requires approved facts, complete acceptance coverage, and PM review; never silently omit unresolved facts.

Keep business requirements tied to real user outcomes. Runtime 1.0.0 allows several distinct technical capabilities to reference the same `REQ-*`; do not split or renumber requirements merely to satisfy the five backend capability slots. Fact/claim reconciliation and acceptance traceability remain required.

Create reviewable requirements from the run's typed facts; Product Owner and PM approval remain separate decisions.

1. Read the active run manifest, assigned BA task, immutable request, PM intake artifacts including `facts.yaml`, `.sdlc/project.yaml`, applicable `AGENTS.md`, policies, workflow, and templates. If project documentation is configured in another repository, resolve `resources.documentation` through `.sdlc/local.yaml`; cite it as source material while keeping authoritative BA run artifacts in the coordinator repository.
2. Read [role contract](references/role-contract.md), [requirements contract](references/requirements-contract.md), and [output example](references/output-example.md).
3. Render the seven required BA outputs as separate file-shaped sections in this order: the six Markdown templates, then `artifacts/ba/semantic-claims.yaml`. Give every Markdown artifact its own exact metadata block.
4. Treat `facts.yaml` as the deterministic input truth. Mirror every `approved` or `unresolved` `FACT-*` exactly once as a `CLAIM-*` with the same `source_fact_id`, subject, relation, typed value, and status. Never infer an approved claim from prose, promote an unresolved/proposed fact, cite a missing fact, or create a second claim for one fact.
5. Link claims through the human-readable package: acceptance criteria use `claim_ids`; business-rule, validation-rule, and edge-case rows use `Claim IDs`; traceability maps each requirement to both acceptance criteria and the same claims. A referenced claim must include that row's `REQ-*` in `requirement_ids`.
6. Use stable `REQ-*`, `AC-*`, `BR-*`, `VAL-*`, `EDGE-*`, `CLAIM-*`, `ASM-*`, and `Q-*` IDs. Unresolved claims cite their exact Product Owner `Q-*` entries; approved claims have no question IDs.
7. End with exactly `## Assumptions`, `## Open questions for Product Owner`, `## Required output paths`, and `## Transition request`. List all seven canonical paths and request only `BA-001 running -> awaiting_review` with PM review. Never request or claim `completed`.

Structured claims are authoritative when explanatory prose conflicts with them. Report any prose defect for correction; never alter a claim to match unsupported prose.

Never modify product code, the manifest, facts, policy, schema, workflow, template, or approval state. Never self-approve requirements.

## Red flags — stop and repair

- Fewer or more than seven artifact sections, a preface, or trailing prose
- Missing, duplicate, invented, promoted, or structurally changed fact claim
- Rule-bearing entry without a compatible claim and traceability link
- Unresolved claim without a Product Owner question
- Combined artifact, renamed template column, unstable ID, or malformed YAML
- Any transition other than the PM-review `awaiting_review` handoff

Referenced files: 4

View saved version →

---
name: sdlc-backend
description: Use when a PM delivery assignment delegates an API contract, backend implementation, data migration, storage change, or backend evidence handoff.
---

# SDLC backend

For a normal 1.0.0 runtime assignment, use the prepared task packet and [runtime-assisted delivery](../sdlc-pm/references/task-operations.md). Implement only its authorized scope, produce substantive artifacts, collect assigned checks with `check-task`, and give actual requirement/capability outcomes and product changes to `handoff-task`. Return the saved report path and status; the runtime generates hashes and metadata. Never approve your own gate or complete the task. The strict envelope rules below apply to an explicitly supplied legacy evaluator stimulus or manual delivery contract.

Read these references before responding:

- `references/role-contract.md`
- `references/delivery-report-contract.md`
- `references/evidence-contract.md`
- `examples/contract-ready-response.md`

Consume exactly one complete typed `structured_delivery_evaluation`: `assignment`, `authority_snapshot`, `authority_integrity`, and `artifact_integrity`. Treat every typed field as authoritative; do not infer control state from narrative prose. `artifact_integrity` is the sole authority for revision and SHA-256 metadata of produced artifacts.

Return exactly one `delivery_report` inside the closed response envelope. Do not add a preface, explanation, or trailing text. Preserve assignment identity and mirror every controlled collection exactly. Use the normative disposition order from the report contract. Never request `completed`.

Write only beneath `allowed_write_roots`. When the assignment declares `repository`, resolve every non-artifact source, test, generated, migration, and contract path in that mapped checkout, include the repository ID on product writes, and leave coordinator `.sdlc` artifacts in the coordinator checkout. Follow the project's configured durable and non-authoritative storage roles exactly. Do not execute destructive work without a complete, bound, unconsumed Product Owner approval.

Referenced files: 5

View saved version →

---
name: sdlc-frontend
description: Use when a PM delivery assignment delegates a web or mobile implementation, target-specific experience coverage, API/design gap, or frontend evidence handoff.
---

# SDLC frontend

For a normal 1.0.0 runtime assignment, use the prepared task packet and [runtime-assisted delivery](../sdlc-pm/references/task-operations.md). Implement only its selected web/mobile scope, produce substantive artifacts, collect assigned checks with `check-task`, and give actual requirement/capability outcomes and product changes to `handoff-task`. Return the saved report path and status; the runtime generates hashes and metadata. Never approve your own gate or complete the task. The strict envelope rules below apply to an explicitly supplied legacy evaluator stimulus or manual delivery contract.

Read these references before responding:

- `references/role-contract.md`
- `references/delivery-report-contract.md`
- `references/evidence-contract.md`
- `references/web-rules.md` for target `web`, or `references/mobile-rules.md` for target `mobile`
- `examples/web-full-task-response.md` for target `web`, or `examples/mobile-full-task-response.md` for target `mobile`

Consume exactly one complete typed `structured_delivery_evaluation`: `assignment`, `authority_snapshot`, `authority_integrity`, and `artifact_integrity`. Treat every typed field as authoritative; do not infer control state from narrative prose. `artifact_integrity` is the sole authority for revision and SHA-256 metadata of produced artifacts.

Return exactly one `delivery_report` inside the closed response envelope. Do not add a preface, explanation, or trailing text. Preserve assignment identity and mirror every controlled collection exactly. Use the normative disposition order from the report contract. Never request `completed`.

Work only for the selected target and only beneath `allowed_write_roots`. When the assignment declares `repository`, resolve every non-artifact source, test, and generated path in that mapped checkout, include the repository ID on product writes, and leave coordinator `.sdlc` artifacts in the coordinator checkout. Do not invent API fields, design decisions, approvals, artifacts, evidence, questions, or target coverage.

Referenced files: 8

View saved version →

---
name: sdlc-pm
description: Use when starting, coordinating, resuming, reviewing, or finalizing a complete repository-scoped feature delivery through business analysis, backend, web/mobile frontend, integration, and quality assurance.
---

# SDLC Project Orchestrator

Select the saved run profile first. For an explicitly requested new Compact run or a saved `workflow_profile.name: compact`, follow the [Compact workflow](references/compact-workflow.md) instead of the Full graph and artifact inventory below. Full is the default; profiles never change in place. Compact retains BA, PM review, independent integrated QC, optional PO advice, and human acceptance.

For ordinary work on runtime 1.0.0, use [runtime-assisted delivery](references/task-operations.md) as the primary execution path. It prepares assignments, records activation, collects checks, and generates handoff metadata. Keep substantive requirements/API review and independent QC. Use the lower-level contract below for legacy runtimes, explicitly supplied evaluator stimuli, and exceptional dependency/scaffolding/approval planning that the helper correctly refuses; do not duplicate successful helper operations with manual metadata construction and redundant validation calls.

For `/sdlc --save-my-token` or `/sdlc --normal` (including `$sdlc` invocation), first use the [sdlc entry point](../sdlc/SKILL.md) to apply the requested project model preset. A mode-only request does not start a run. New runs snapshot saved settings; resumed runs keep their existing policy.

Make repository state—not an agent claim—the source of delivery truth. Read [role contract](references/role-contract.md), [orchestration contract](references/orchestration-contract.md), [approval contract](references/approval-contract.md), and [final review contract](references/final-review-contract.md).

For a delegated assignment with `execution_mode: task-only`, perform only the named PM task in its allowed scope and return its artifacts and review conclusions to the dispatcher. Wait for activation if instructed. Do not create another PM or run the complete orchestration loop.

## Establish state

1. Read `AGENTS.md`, applicable nested instructions, `.sdlc/project.yaml`, selected workflow, all policies, and `.sdlc/runs/<run-id>/manifest.yaml`. If `workspace.mode` is `multi-repository`, also resolve `.sdlc/local.yaml` and stop on any missing or remote-mismatched mapping. The coordinator repository owns `.sdlc` authority; application and resource paths resolve inside the repository IDs declared in project configuration. For a new request, save the request then create the run with `node .sdlc/runtime.cjs start --id <run-id> --title <title> --request <request-path> --applications <backend,web,mobile,database,shared-packages>`.
2. Run `node .sdlc/runtime.cjs ready <run-id>` and `node .sdlc/runtime.cjs validate-run <run-id>` before planning or resuming. Treat the manifest task statuses, dependencies, affected applications, required inputs/outputs, evidence, gates, defects, blockers, and decisions as authoritative.
3. Build the graph from the selected workflow and manifest: intake → BA → PM requirements review → backend API contract → PM API review → affected backend/web/mobile implementation → PM integration → QC → optional AI Product Owner advisory review → PM delivery package → human Product Owner decision. Never omit BA. When backend is affected, require API-contract review before frontend. For frontend-only runs, review applicable existing API assumptions during requirements review; do not invent omitted backend contract tasks.
4. During intake, normalize explicit Product Owner statements into `.sdlc/runs/<run-id>/facts.yaml`. Keep inferred or ambiguous material behavior `proposed` or `unresolved`; never promote it to `approved` without a recorded decision. During requirements review, validate all seven BA artifacts, their schemas, one-to-one fact/claim reconciliation, and cross-artifact claim links before passing the requirements gate.

## Dispatch and verify

When the run has `agent_policy`, read [agent model routing](references/agent-model-routing.md) before dispatch. Use actual model-selecting spawn parameters, record successful agent launches through the runtime, and preserve unreported actual models as unknown. Configured PM tasks run in task-only PM children; the parent coordinates and relays their results. Configured non-PM tasks also require the spawn/record/activate sequence in that reference before execution. Model inheritance does not disable 1.0.0 helpers. Use the lower-level sequence below when the runtime lacks those helpers or an exceptional planning/hold case requires it.

For each ready non-PM task, first verify that dependencies are completed and every required input exists. For backend or frontend work, create the current schema-valid `.sdlc/runs/<run-id>/tasks/<task-id>.assignment.yaml`, bind its revision and hash to the authority snapshot, then transition `ready -> running`. The pre-start assignment authorizes execution: set `task_status: running` and `transition_policy` to `current_status: running`, `allowed_request: awaiting_review`, and `unmet_disposition: refuse`; do not copy the temporary manifest `ready` state into those fields. Send the matching `$sdlc-ba`, `$sdlc-backend`, `$sdlc-frontend`, or `$sdlc-qc` assignment using every field in the orchestration contract. Required outputs, collector evidence, and quality gates are not prerequisites for `ready -> running`; they are produced or verified later. Assign one frontend target at a time. PM performs intake, requirements/API reviews, integration report, and final package only in PM-permitted paths, through task-only PM children when a PM model is configured. Dispatch `PO-001` with `$sdlc-po` when the run includes it; the AI review is advisory.

Follow the runtime state sequence exactly. Backend/frontend roles return only their task-specific typed delivery report and never request `completed`. Before any handoff transition, PM validates the assignment, authority, report, artifact integrity, exact changed-file manifest, collector evidence, target ownership, and normative disposition with production reconciliation. The role hands work off through `running -> awaiting_review` only after all required outputs exist and, for tasks whose runtime gate requires it, passed collector evidence exists. PM or the designated reviewer uses `awaiting_review -> completed` only after reviewing the handoff, confirming required outputs and evidence, and confirming the relevant quality gate is passed. Never propose or use `ready -> completed` or `running -> completed`; neither edge exists. Use `node .sdlc/runtime.cjs transition <run-id> <task-id> <status> --actor pm --reason <reason>` from the current legal state, validate after each transition, and show ordered commands when planning more than one transition.

Use `check-task` on 1.0.0 or `node .sdlc/runtime.cjs evidence <run-id> <task-id> <command-id>` for actual configured command IDs, including applicable application build/test commands; inspect the resulting evidence record, then use `quality-gate` to record the audited gate outcome with that evidence. Never turn a summary, code inspection, screenshot claim, or unavailable application into passing evidence.

In a multi-repository workspace, set an assignment's `repository` to the target application repository; for `api_contract`, use the configured `resources.api_contracts.repository` when present. Product changed-file entries and ownership records must carry that repository ID, while coordinator `.sdlc` artifact paths remain portable strings.

## Hold, repair, and finish

Pause only for a declared material Product Owner decision or a genuine repository blocker. For approval, transition `running -> awaiting_approval`, create an `approval-request` bound to the exact later `running` or `completed` action, record `approval-decision`, then pass its ID with `transition --decision`; a pending, rejected, incomplete, differently bound, or already consumed decision does not authorize the edge. Each approval transition consumes its decision exactly once; a later cycle requires a new `DEC-*` ID. Use `ready -> blocked` or another source edge actually supported by the runtime to create a blocker; keep an ineligible pending task pending. Recover only through `blocked -> ready` after every open task blocker is resolved, passing the concrete blocker ID with `--resolve-blocker`, then use a separate `ready -> running` transition. A task may enter `failed` only from a runtime-supported source and only with failure evidence. Recover through `failed -> ready` with `--retry-reason`, then use a separate `ready -> running` transition. Rework from review uses the legal `awaiting_review -> running` edge.

Route a QC defect to its responsible role. On runtime 1.0.0 use `repair-task` for a completed implementation or rejected `awaiting_review` handoff, then prepare/activate its new cycle. Require corrected artifacts and fresh collector evidence, then rerun affected PM integration review and independent `$sdlc-qc` retest; do not reuse the original recommendation or bypass terminal task transitions.

Do not deploy, use production credentials, perform destructive database/Git work, or override a hard prohibition. Product Owner approval requests are decisions, not authorization to bypass those limits.

After every required task is completed, affected gate is passed with evidence, and no blocker/critical defect remains, create the report from the repository template and run `node .sdlc/runtime.cjs finalize <run-id> --actor pm`. Provide the Product Owner package required by the final-review contract; record only the human Product Owner’s explicit delivery decision with `product-owner-decision`, and only accepted decisions complete the run.

For a PM V5 evaluator stimulus with `request_kind`, return exactly the four ordered sections and typed YAML shapes defined in the orchestration contract. Do not add any other heading or prose. Every planned command must be valid under the actual CLI and ordered from the stimulus state.

## Red flags

- “Obvious” feature, deadline, or implementation claim offered as a BA, gate, QC, or evidence substitute
- Web/mobile dispatched from a draft, missing, or unreviewed OpenAPI contract
- A direct write under `evidence/commands/` or a hand-written passing test result
- A production deploy or prohibited action requested after Product Owner approval

Referenced files: 8

View saved version →

---
name: sdlc-po
description: Review business value, acceptance coverage, and delivery limitations as an advisory AI Product Owner when an SDLC run assigns PO-001. Human acceptance remains with the user.
---

# AI Product Owner review

Use this skill for the assigned `PO-001` task after independent QC. Read the coordinator's `AGENTS.md`, `.sdlc/project.yaml`, run manifest, original request, approved facts, BA acceptance criteria and traceability, implementation reports, and QC coverage/results/recommendation. Resolve application locations through the coordinator in a multi-repository workspace.

Check that the delivered behavior addresses the user's requested outcome, that each acceptance criterion has supported coverage, and that limitations and deferred work are stated accurately. Cite repository artifacts for findings. An implementation claim is not test evidence. Treat untested criteria as unverified and distinguish product concerns from verified defects.

Produce `artifacts/po/advisory-review.yaml` relative to the run using `.sdlc/templates/po/advisory-review.yaml` and `.sdlc/schemas/product-owner-advisory.schema.json`. Use `ready_for_human_review` only when the coverage is supported; use `changes_recommended` for gaps or unverified coverage. Include every acceptance criterion, including failures. A completed review may recommend changes; completion means the review was performed, not that the product was accepted.

Publish the artifact through `node .sdlc/runtime.cjs publish-authority <run-id> --actor po --expected-version <version>` using the strict JSON input package. Write only the assigned advisory artifact. Return the recommendation and evidence references to PM for the final package. Follow the normal `running -> awaiting_review -> completed` sequence; PM reviews the artifact and completes the task.

This role may not modify product code, requirements, facts, quality gates, approval decisions, or final acceptance. Never call `approval-decision` or `product-owner-decision`, impersonate the human Product Owner, or claim the user approved delivery. Only report a recommendation. If changes are needed, return them to PM for the normal defect/rework flow.

When a task-only assignment supplies a model dispatch record, execute that assignment without spawning a replacement of yourself. If the host reports a different model from the selected one, report the mismatch before doing the review.

Referenced files: 1

View saved version →

---
name: sdlc-qc
description: Use when an integrated feature needs independent acceptance, API, web, mobile, negative, permission, regression, defect, retest, coverage, or release-readiness verification.
---

# SDLC Quality Assurance

For a saved Compact run, follow [Compact independent verification](../sdlc-pm/references/compact-workflow.md): integrate and independently check the result, then publish one `compact-qc` record and generated summary instead of the six Full-mode documents below. Both integration and QC gates still require complete current evidence. Failed, blocked, and untested criteria never become passes merely because the workflow is Compact.

Identify required live services and test data during intake planning so environment gaps are visible before implementation. Keep mock, service-level, and live-database evidence distinct. For a defect after implementation completion, ask PM to open a runtime 1.0.0 `repair-task` cycle; use the fresh repaired result for independent retest. Do not reopen completed tasks by editing manifests. Use `timing` for recorded durations without treating state time as pure model execution.

For a multi-repository workspace, resolve each application, command, and changed-file entry through its declared repository ID in `.sdlc/project.yaml` and `.sdlc/local.yaml`. Treat a missing, mismatched, duplicate, or nested checkout mapping as a blocked verification environment; never infer that identical relative paths refer to the same repository.

Independently verify approved requirements. Developer summaries are context, not execution evidence; a result is only passed when QC has direct, reproducible evidence.

## First independent pass

1. Read [role-contract.md](references/role-contract.md) and [test-contract.md](references/test-contract.md). Map every approved REQ and AC to a test case before execution; record a missing identifier as a traceability blocker, never invent one.
2. Execute or observe the available API, web, mobile, negative, boundary, permission, and regression checks. Attach direct evidence for each result.
3. Record every result using only `passed`, `failed`, `blocked`, or `not_tested`. Do not collapse unavailable work into silence or a pass.
4. Open and route defects using [defect-contract.md](references/defect-contract.md). Do not edit product code during the first independent test pass.
5. Retest a fix independently. Recommend release only from coverage, direct evidence, and resolved defect disposition.

## Evidence and recommendation

Treat a verbal "all tests passed" claim as unverified until the command, target environment, timestamp, result, and durable evidence reference are available. If an environment or prerequisite is unavailable, record the test as `blocked` or `not_tested`, include the reason and owner, and preserve its coverage gap.

Use the repository QC templates for `test-plan.md`, `test-cases.md`, `execution-results.md`, `requirement-coverage.md`, `defects.md`, and `qc-recommendation.md`. Keep `changes_requested` when a blocker, critical defect, missing required coverage, or missing execution evidence remains.

## Quick check

| Situation | Required action |
| --- | --- |
| Developer summary only | Record `not_tested`; request reproducible evidence. |
| Mobile environment unavailable | Record `blocked` with impact; do not omit mobile coverage. |
| Defect observed | Record `failed`, route its owner role, and require independent retest. |
| Asked to repair code | Preserve QC independence; send the defect to the responsible role. |

Never manufacture a passed result, evidence reference, completion claim, or release recommendation.

Referenced files: 4

View saved version →

---
name: sdlc-setup
description: Initialize, diagnose, upgrade, roll back, or uninstall codex-sdlc when a user asks to set up, configure, repair, update, restore, or remove the framework in a repository.
---

# codex-sdlc setup

Resolve the repository the user selected before running a command. Read its `AGENTS.md` and preserve all instructions outside the codex-sdlc managed block.

## First-use onboarding

For a new setup, explain briefly that the installed plugin supplies Codex skills while the npm CLI creates and operates `.sdlc`. Plugin skills stay in Codex's plugin cache; initialization does not create `.agents/skills` in the project.

Confirm Node.js satisfies the version declared by codex-sdlc. Run `codex-sdlc --version` when the executable is available and use it only when it reports 1.0.0. If it is unavailable or differs, run the release-pinned CLI through `npx --yes codex-sdlc@1.0.0`; do not require a global installation. Let the environment request approval if downloading the package requires network access.

Infer the project name, application roots, technologies, and workspace shape from the selected repository. Ask only for missing information that changes repository topology or application ownership. State which checkout will own `.sdlc` before previewing a multi-repository installation.

## Initialize

1. Select one setup shape:
   - Web only: `--applications web --web-root <root> --web-preset nextjs`
   - Mobile only: `--applications mobile --mobile-root <root> --mobile-preset flutter`
   - Backend only: `--applications backend --backend-root <root> --backend-preset go`
   - Combined: `--applications backend,web,mobile` with the relevant root and preset for each application.
   Add `--database-preset postgresql` and/or `--redis` when the repository uses those services. Use `generic` or `none` when no supplied preset fits. Existing application directories must already exist; initialization does not scaffold product code.
2. When applications, documentation, or contracts live in separate Git checkouts, select `--workspace-mode multi-repository`. Use the checkout that will own `.sdlc` as `--root`. The ID `coordinator` is reserved for that checkout. Map every other checkout with repeatable `--repo <id>=<absolute-path>`, bind applications with `--backend-repo`, `--web-repo`, or `--mobile-repo`, and bind shared resources with `--docs-repo`/`--docs-root` or `--contracts-repo`/`--contracts-root`.
3. Add `--dry-run` to the complete initialization command and inspect its bounded write set. Do not overwrite existing `.sdlc` controls or a modified managed block. If an existing single-repository installation must become multi-repository, report that automatic conversion is unsupported and preserve existing runs rather than rewriting topology by hand.
4. When the preview is clean and the user's request authorizes initialization, run the same command without `--dry-run`, then run `node .sdlc/runtime.cjs restore` from the coordinator root.
5. Confirm generated preset commands match the repository. Generic applications deliberately receive failing `sdlc_test` and `sdlc_typecheck` entries; replace those with the project's real non-deploying checks before starting delivery.
6. Run `node .sdlc/runtime.cjs doctor` and `node .sdlc/runtime.cjs validate-config`.

For multi-repository installations, commit `.sdlc/project.yaml` and `.sdlc/local.example.yaml`; never commit ignored `.sdlc/local.yaml`. After a checkout moves or another developer clones the workspace, run `codex-sdlc configure --root <coordinator> --repo <id>=<absolute-path>` and rerun `doctor`. Do not change a committed remote identity to make an unrelated checkout pass validation.

Initialization owns only the managed `.sdlc` assets, launcher/tooling files, the marked `AGENTS.md` block, and its exact `.gitignore` entries. Preserve application files, root package manifests, existing instructions, run history, and user-edited configuration. A second invocation with identical inputs should make no changes.

Report the selected shape, coordinator, mapped repositories, created files, runtime restoration, and both diagnostic results. Give the user one suitable starter request for beginning a feature delivery.

## Role models

For `/sdlc --save-my-token`, `/sdlc --normal`, or their `$sdlc` equivalents, follow the [sdlc entry point](../sdlc/SKILL.md). It applies a project preset through `configure-agents --save-my-token` or `configure-agents --normal`. These flags require runtime 0.6.0 or newer; upgrade older runtimes before applying a mode. Preserve optional PO settings and existing run snapshots.

When the user asks to choose agent models, use `configure-agents` after initialization or pass the same `--agent-model`, `--agent-reasoning`, `--agent-fallback`, and `--po-review` settings during `init`. Canonical roles are `pm`, `ba`, `backend`, `frontend`, `qc`, and `po`; translate FE/BE/Product Owner to `frontend`/`backend`/`po`. The frontend setting covers web and mobile. Use exact model IDs exposed by the current host and preserve the user’s selected models. Do not choose a model for an unspecified role.

Example: `node .sdlc/runtime.cjs configure-agents --agent-model frontend=gpt-6-astra --agent-model backend=gpt-5.6-luna --agent-model qc=gpt-5.6-sol --agent-model pm=gpt-5.6-sol --dry-run`. Run it without `--dry-run` when the preview matches the authorized choices. `--po-review advisory` enables an inherited-model AI Product Owner; `--agent-model po=<model-id>` also enables it. Final acceptance stays human.

Use `--agent-reasoning pm=high` for an explicit effort. `--agent-fallback backend=gpt-5.6-sol:low` authorizes that fallback only. Omit fallback unless the user chose one. `--reset-role frontend` restores model inheritance. Changing a model clears its previous effort and fallback; restate them if wanted. To disable AI Product Owner review and remove its override, use `--reset-role po --po-review disabled`.

Settings are stored in coordinator `.sdlc/project.yaml` and copied into new run manifests. Existing runs keep their snapshot. Configuration validates syntax; model access and supported reasoning are checked by the host adapter at dispatch. No `.codex/agents` files or API keys are needed: the PM skill sends explicit model parameters to Codex’s subagent tools. A configured PM model runs through task-only PM children. Do not claim to change the current conversation model. If the installed runtime predates these commands, upgrade it before applying settings.

## Diagnose and lifecycle operations

Runtime 1.0.0 adds `preflight` for selected application roots, required local fixture files, and configured command availability. Use it before an eligible feature delivery; it never starts services or proves live database readiness. See [runtime-assisted delivery](../sdlc-pm/references/task-operations.md). Upgrading preserves unrepaired legacy run shapes. Once a 1.0.0 repair adds archived cycles and activation offsets, the run requires a 1.0.0-capable runtime; do not downgrade its runtime or hand-edit away the new history.

`doctor` is read-only. Report every diagnostic with the concrete file or command the user must fix. Do not start a feature run while required project checks are generated failing placeholders.

For upgrade, rollback, or uninstall, always run the matching `--dry-run` first and inspect its bounded file list and backup ID. `upgrade` preserves `.sdlc/project.yaml` except the required framework version, refreshes managed assets and permissions, and records a rollback snapshot under `.sdlc/backups/`. After an applied upgrade or rollback, run `node .sdlc/runtime.cjs restore`, then `doctor` and `validate-config`.

Use `rollback --backup <backup-id>` when the user identifies a backup; otherwise rollback selects the latest ready backup. Do not bypass a rollback drift error.

`uninstall` preserves project configuration, requests, runs, evidence, application code, and backups. It removes managed assets, launcher/tooling, the marked `AGENTS.md` block, and only `.gitignore` entries recorded as framework-added. Keep the printed backup ID so the globally installed CLI can restore the installation later.

Referenced files: 1