codex-workflow

Enforces the AgenticApps spec-first workflow on Codex. This skill MUST activate whenever the user asks Codex to implement, build, code, fix, refactor, or design anything. Triggers on: "let's work on [issue]", "implement the [feature]", "build the [component]", "fix the [bug]", any task involving writing or changing code, creating architecture, or making technical decisions. Use this even when the user just says "start working" or references a Linear / Asana / Jira / GitHub issue number. The skill emits the workflow commitment ritual, picks task size, routes to the right GSD entry-point skill, and binds every spec gate to the upstream Superpowers skill or codex-* gate-fulfilling skill that satisfies it.

Bootstrap a fresh project with the codex-workflow scaffolding — apply the baseline migration to install the trigger skill's required project-side artifacts (AGENTS.md sections, .planning/config.codex.json, .codex/workflow-config.md, docs/decisions/, .codex/workflow-version.txt). Use when a project is freshly cloned or initialized and the user asks to "set up the workflow", "add agenticapps workflow", "enable codex-workflow", "install the discipline layer", "scaffold this project", or anything else that means "I want this project to use codex-workflow from this point forward". Idempotent — refuses to re-run on a project that already has `.codex/workflow-version.txt` and routes to `$update-codex-agenticapps-workflow` instead.

Update an installed codex-workflow project to the current scaffolder version by applying pending migrations between the project's recorded version and the scaffolder's. Use when the user runs "update workflow", "apply pending workflow migrations", "upgrade to the new scaffolder version", or after pulling a new release of codex-workflow. Reads `.codex/workflow-version.txt`, finds pending migrations in `${CODEX_HOME}/skills/update-codex-agenticapps-workflow/migrations/`, pre-flights required external skills, applies each step with diff preview + per-step confirm, bumps the version on success, commits atomically. Supports `--dry-run` for diff-only output.

Declare-first TypeScript discipline for new modules in TS-primary AgenticApps projects on the Codex host, per workflow-core spec §13. Strengthens the `tdd` gate for TypeScript module API surfaces. When invoked on a new TS module, produces three ATOMIC commits in order: Phase 1 declaration (`<name>.declare.ts`, declare-only, type-checks clean), Phase 2 tests (import + exercise the declared surface; MUST be observable as failing in the expected way — the RED output is §06 evidence), Phase 3 implementation (signatures match the declaration exactly; tests go green). Use when authoring a new TS module's public API, or when the user says "declare first", "ts-declare-first", "type surface first", or starts a new TypeScript module in a TS-primary project. The skill REFUSES to bundle Phase 1 and Phase 3 into a single commit — the three-commit atomicity is the structural evidence that the discipline was followed; collapsing it erases the evidence.

Database-specialist security audit in two modes. **phase-scoped mode**: when the security gate fires AND the phase scope matches supabase|postgres|mongodb|firebase|mysql, audit the changed surface for RLS / auth bypass / storage exposure / known CVEs (MongoBleed, pgBouncer, mysql_native_password drift) and produce DB-AUDIT.md. **pre-launch mode**: before first production launch and after any major DB migration, audit the FULL project surface (every supported backend). Critical or High findings BLOCK branch close per ADR-0012; override only via the database-security acceptance ADR template.

Post-implementation visual quality audit against the deployed component. Re-scores the seven design dimensions (typography, color, spatial, motion, interaction, responsive, UX writing) against the shipping code, runs the 24-item AI-slop anti-pattern scan, and blocks branch close on Red findings (per ADR-0011). Use after a UI-shipping phase's implementation is complete and the changes are visible in the dev server. May also be invoked retroactively against shipped UI to catch drift between mockup and implementation.

Browser-driven QA in two modes. **ui-preview mode** (per-task, pre-commit): boot the dev server, screenshot the changed component, reference the screenshot path in the commit message — fires for any task modifying a frontend component, route, or visual surface. **qa mode** (post-phase): walk user flows in a real browser against a running dev server, log interactions, produce a QA report referenced from VERIFICATION.md — fires per phase that ships user-visible behavior. Use whichever mode the calling context selects; the body branches on `mode=preview` vs `mode=phase-qa`.

Stage 1 of the two-stage review: audit the phase's changeset against CONTEXT.md decisions, every must_have in VERIFICATION.md, the gate bindings, and the protocol-violation list (commitment ritual, brainstorm artifact, TDD commit pair). Use after all execution tasks complete and before any code-review pass. Writes the `## Stage 1 — Spec compliance` section into REVIEW.md. The implementer agent runs this stage in the same session; Stage 2 (`superpowers:requesting-code-review`) MUST run independently afterwards.

Run an OWASP-aligned security audit at a phase boundary when the changeset touches authentication, storage, request handling, secret material, or LLM trust boundaries. Produces SECURITY.md with audited threat models and mitigation evidence. Use when the phase's diff includes auth flows, session handling, file/blob storage, API surfaces, environment variables/secrets, or LLM tool-use trust boundaries. Composes with `codex-database-sentinel-audit` (DB-specific sub-gate) per ADR-0012.

Impeccable-style design critique against an existing UI-SPEC.md or set of design-shotgun variants. Scores against typography, color, spatial design, motion, interaction, responsive behavior, and UX writing dimensions; flags AI-slop tells (24 anti-patterns); produces a critique document that names at least one specific issue and its remediation. Use before implementation begins on a UI plan, OR as the filter step in a design-shotgun slate (per ADR-0011).

Generate at least three rendered visual variants of a UI surface and let the user pick. Use when a phase has a UI plan and no UI-SPEC.md exists for the surface yet — the gate fires once per surface. Ships variants as screenshots, sketches, mockup URLs, or any combination the user can compare visually. Marks the chosen variant in CONTEXT.md or UI-SPEC.md. Pairs with `codex-design-critique` to filter sub-bar variants per ADR-0011 before the user picks.