codex-workflow

Opinionated workflow for Codex CLI built for Node.js / TypeScript fullstack applications. Enforces a consistent development process across your backend (Fastify, Express, SQLite) and frontend (React, CSS/SCSS) projects.

Why

Codex is powerful but stateless — every session starts fresh with no memory of what was planned or half-finished. Without structure, it improvises. This package gives Codex a shared rulebook: when to plan, when to just do, how to resume interrupted work, and how to hand off cleanly.

One source of truth. Install once per project, update from a single place.

Install

npx codex-workflow init

Copies AGENTS.md and .agents/skills/ into your project. Codex picks them up automatically on the next session.

To update to the latest version:

npx codex-workflow@latest init

For projects that only need core workflow skills (no stack-specific rules):

npx codex-workflow init --no-stack-skills

Commands

Use these at the start of any Codex message:

| Command | When to use | |---|---| | $plan <description or spec file> | New service, large feature, unclear or risky work | | $task <description> | Small, well-defined change | | $fix <description> | Bug fix | | $resume | Continue interrupted work in a new session | | $status | See what's in progress across all active plans | | $done | Current task is ready — trigger review, verify, handoff |

Example

$plan add user authentication with JWT

Codex produces a spec → you approve → Codex produces a task plan → you approve → implementation starts one task at a time.

$task add input validation to POST /api/users

Codex plans, implements, reviews, verifies, and hands off in one shot.

$resume

New session, clean context. Codex finds the interrupted task, reads where it stopped, and continues.

Skills included

| Skill | Use for | |---|---| | spec | Writing approval-ready specs for large or unclear work | | plan | Breaking approved specs into small, resumable tasks | | review | Code review with severity levels before handoff | | verify | Confirming completion with evidence | | ts | Node.js / TypeScript type safety and module design | | modules | Service boundaries and file size rules | | react | React components, hooks, TypeScript, performance | | css-scss | BEM naming, SCSS nesting, responsive patterns | | fastify | Routes, plugins, schemas, error handling | | express | Routers, middleware, validation, error handling | | sqlite-schema | Migrations, indexes, constraints | | sqlite-queries | Repositories, transactions, prepared statements |

How it works

AGENTS.md in your project root defines the rules Codex follows. Skills in .agents/skills/ are reusable procedures (spec writing, code review, verification) that Codex loads on demand. Planning artifacts live in plans/<slug>/ — a spec and a task list that persist across sessions so nothing is lost when context resets.