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. For `--save-my-token`, check `node .sdlc/runtime.cjs --version` first: the GPT-6.1 Sol preset requires runtime 1.0.1 or newer. If it is older, use the [setup upgrade workflow](../sdlc-setup/SKILL.md) before applying the preset; older runtimes can accept the flag while selecting the previous Sol model. `--normal` remains supported on runtime 0.6.0 or newer. 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 flag, use the setup upgrade workflow. 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.1-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. 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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 p

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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.1. If it is unavailable or differs, run the release-pinned CLI through `npx --yes codex-sdlc@1.0.1`; 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 identi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.