codex-workflow 1.0.0

package/.agents/skills/css-scss/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: css-scss
+description: Use for CSS or SCSS styling work. Covers naming, structure, nesting, and responsive patterns. Do not use for component logic — pair with react skill instead.
+---
+
+## When to use
+CSS or SCSS changes: component styles, global styles, responsive layouts, design tokens.
+
+## Naming and structure
+- Use BEM for component classes: `block__element--modifier`.
+- Prefer CSS modules for component-scoped styles; use global styles only for resets and design tokens.
+- One SCSS file per component. Avoid cross-component style imports.
+- Use variables / custom properties for colors, spacing, and typography. No magic numbers.
+
+## SCSS rules
+- Limit nesting to 3 levels. Deeper nesting is a structural problem.
+- Use `@mixin` for repeated patterns with parameters; use `%placeholder` for static repeated rules.
+- Do not `@extend` across files — output is unpredictable.
+- Keep partials small and single-purpose. No `utils.scss` dumping ground.
+
+## Responsive design
+- Mobile-first: base styles for small screens, `@media (min-width: ...)` for larger.
+- Use design-token breakpoints, not hardcoded pixel values.
+- Prefer `flex` and `grid` over absolute positioning.
+
+## Performance
+- Avoid universal selectors and deep descendant chains.
+- Minimize specificity. Prefer class selectors over element or ID selectors.
+- Define `@font-face` and `@keyframes` once. Do not duplicate.
+
+## Before handoff
+- No hardcoded colors or spacing outside of tokens / variables.
+- Nesting depth ≤ 3.
+- No unused variables, mixins, or selectors.
+- Responsive breakpoints use design tokens.

package/.agents/skills/express/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: express
+description: Use for Express route, middleware, or router work. Pair with ts skill for TypeScript rules and sqlite-queries/sqlite-schema for database work.
+---
+
+## When to use
+Express route registration, middleware, router organization, error handling.
+
+## Router design
+- Split routes into `express.Router()` instances by feature domain. Mount them in the main app file.
+- Keep route handlers thin: validate input, call a service, send response. No SQL or business logic in route files.
+- Do not attach routes directly to the `app` instance except for top-level mounts.
+
+## TypeScript
+- Extend `Request` and `Response` via module augmentation when adding custom properties (e.g., `req.user`).
+- Type request body, params, and query explicitly: `Request<Params, ResBody, ReqBody, Query>`.
+- Do not use `any` for `req.body`. Validate and narrow at the route boundary.
+
+## Validation
+- Validate all request input at the route boundary before passing to services.
+- Use a schema library (Zod, Joi, express-validator). Do not write manual `if` chains for input validation.
+- Return consistent error shape on validation failure: `{ error: string }` with appropriate status code.
+
+## Middleware
+- Apply middleware at the router level, not globally, unless it genuinely applies to every route.
+- Auth middleware must reject early. Never silently pass unauthenticated requests.
+- One concern per middleware function.
+
+## Error handling
+- Use a centralized error-handling middleware with 4 arguments: `(err, req, res, next) => ...`.
+- Always call `next(err)` for errors in non-error middleware. Do not send responses directly.
+- Register the error handler last.
+- Return consistent error shapes from the error handler.
+
+## Before handoff
+- All routes validate input before calling services.
+- Error handler is registered last and uses the 4-argument signature.
+- No SQL or business logic in route files.
+- `tsc --noEmit` passes with typed request/response generics.

package/.agents/skills/fastify/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fastify
+description: Use for Fastify route, plugin, schema, or hook work. Pair with ts skill for TypeScript rules and sqlite-queries/sqlite-schema for database work.
+---
+
+## When to use
+Fastify route registration, plugins, request/response schemas, hooks, error handling.
+
+## Route design
+- Register routes via plugins, not directly on the root instance.
+- One plugin file per feature domain.
+- Always define request and response JSON schemas. Fastify uses them for validation and serialization.
+- Use TypeScript generics for typed request params, body, query, and reply: `RouteGenericInterface`.
+
+## Schema and validation
+- Define schemas as `const` objects with `as const` or use TypeBox for TypeScript-native schemas.
+- Validate all incoming data through the schema — do not manually validate what the schema already covers.
+- Return consistent error shapes: `{ error: string, message: string }` for all 4xx responses.
+
+## Plugins and decorators
+- Use `fastify.decorate` for instance-level shared values (db, config, auth).
+- Wrap plugins with `fastify-plugin` only when you intend to share decorators across sibling plugins.
+- Keep plugin files thin: register routes and hooks, delegate logic to service modules.
+
+## Error handling
+- Use `fastify.setErrorHandler` for centralized error handling.
+- Use `@fastify/sensible` `httpErrors` for standard HTTP errors. Do not construct error objects manually.
+- Do not swallow errors in route handlers. Let them propagate to the error handler.
+
+## Hooks
+- Use `onRequest` / `preHandler` for auth and validation that applies to multiple routes.
+- Attach hooks at the plugin scope, not globally, unless they genuinely apply everywhere.
+
+## Before handoff
+- All routes have request and response schemas.
+- No business logic in route handlers — logic lives in service modules.
+- Error handler returns consistent shape.
+- `tsc --noEmit` passes with typed route generics.

package/.agents/skills/modules/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: modules
+description: Use when adding feature logic, growing a source file past 150 lines, or touching mixed-responsibility modules. Do not use for small localized edits within one clear module.
+---
+
+## When to use
+- Adding feature logic.
+- Growing a non-test source file past 150 lines.
+- Touching a mixed-responsibility module.
+- Introducing or refactoring a subsystem.
+
+## Structure
+- `src/services/<name>/` — feature and use-case orchestration.
+- `src/routes/` — HTTP transport only.
+- `src/infrastructure/` — SQLite, S3, Playwright, and other external adapters.
+- `index.ts` — narrow public surface for a slice only.
+- Entrypoints and bootstrap files must be thin.
+
+## Boundary rules
+- Each module has one role: entrypoint, route, service, repository, adapter, type module, or utility.
+- If a file owns more than one role, split it before adding behavior.
+- Routes: parse input, call services, shape responses. No SQL or storage.
+- Services: coordinate repositories, adapters, domain rules. One use case or related workflow.
+- Infrastructure: talks to external systems. Not hidden inside services.
+- `utils.ts`: genuinely cross-cutting pure helpers only. No feature logic.
+
+## Size rules
+- Non-test source files: target `<=150` lines. `>200` requires a split or written exception.
+- Functions: target `<=60` lines. `>80` requires a split or written reason.
+- Prefer extracting a cohesive module over adding private helpers that only make a large file slightly smaller.
+
+## Good decomposition
+- `src/services/worker/run-worker.ts`, `src/services/worker/scan-page.ts`
+- `src/infrastructure/sqlite/pages-repository.ts`, `src/infrastructure/sqlite/queue-repository.ts`
+
+## Bad decomposition
+- `src/worker-utils.ts`, `src/db-helpers.ts`, `src/services.ts`
+
+## Before handoff
+- Each changed file has one clear responsibility.
+- Entrypoints stayed thin.
+- Feature logic lives in a named service slice.
+- Infrastructure is isolated from transport.
+- No changed non-test file exceeded size rules without documentation.

package/.agents/skills/plan/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: plan
+description: Use after spec approval to break work into small, resumable tasks saved in plans/<slug>/tasks.md. Do not use before spec approval or for ad-hoc notes.
+---
+
+## When to use
+Only after the spec is approved.
+
+## Process
+1. Read the approved spec from `plans/<slug>/spec.md`.
+2. Reuse the same `<slug>` as the spec.
+3. Split work into the smallest tasks that each produce a reviewable diff.
+4. Order tasks to reduce risk and unblock verification early.
+5. For each task: list exact file paths, write a concrete acceptance check, leave `Resume:` empty.
+6. Save to `plans/<slug>/tasks.md`. Ask for approval.
+
+## Template
+
+```md
+# Task plan
+Spec: `plans/<slug>/spec.md`
+Next task: <task-id>
+
+## Tasks
+### <task-id>. <task name>
+- Status: `todo`
+- Scope: <one sentence — what changes and why>
+- Touches: <exact file paths created, modified, or deleted>
+- Depends on: <task-id or none>
+- Acceptance: <concrete command, assertion, or observable result>
+- Resume:
+- Notes / risks:
+```
+
+## Rules
+- Each task must be reviewable in isolation — one diff, one concern.
+- A task that needs more than one review round is too large. Split it.
+- Avoid bundling unrelated work.
+- Put risky or enabling work early.
+- Acceptance criteria must be concrete.
+  - Good: "`npm test` passes", "GET /api/health returns 200"
+  - Bad: "it works", "handles edge cases", "code is clean"
+  - Never use "correctly", "properly", or "appropriate" without a measurable check.
+- Include migration, compatibility, or cleanup tasks when needed.
+- Use explicit statuses: `todo`, `in_progress`, `done`.
+- Update `Resume:` at every handoff: `<last file touched> — <what was done> — <next step to take>`.
+- End by asking for approval and stating the save path.

package/.agents/skills/react/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: react
+description: Use for React component work. Covers component design, hooks, TypeScript, and performance patterns. Pair with ts skill for TypeScript rules and css-scss for styles.
+---
+
+## When to use
+React component creation or modification, hooks, state management, event handling.
+
+## Component design
+- Functional components only. No class components.
+- One component, one responsibility. Keep components small and focused.
+- Co-locate component, styles, and tests in one directory.
+- Keep JSX readable: extract complex expressions into named variables before the return.
+- Props interface must be explicit and minimal. No catch-all `[key: string]: any`.
+
+## Hooks
+- Prefer built-in hooks before writing custom hooks.
+- Extract a custom hook when the same stateful logic appears in 2+ components.
+- One hook, one concern. Do not bundle unrelated state into one hook.
+- Respect rules of hooks: no conditional calls, no calls outside React functions.
+
+## TypeScript
+- Type all props with an interface named `<ComponentName>Props`.
+- Type event handlers explicitly: `React.ChangeEvent<HTMLInputElement>`, not `any`.
+- Use `React.ReactNode` for children props.
+- Do not use `as` to silence type errors on props or event targets.
+
+## State and data flow
+- Lift state only as far as necessary.
+- Prefer props over context for state that belongs to a small subtree.
+- Use context for genuinely cross-cutting state (theme, auth, locale).
+- Do not store server data in local component state — fetch in a parent or data layer.
+
+## Performance
+- Wrap expensive children in `React.memo` only after profiling confirms a problem.
+- `useCallback` and `useMemo` are optimizations — do not add preemptively.
+- Avoid inline object / array literals in JSX props passed to memoized children.
+- Use stable, unique keys. Do not use array indexes for reorderable lists.
+
+## Before handoff
+- No `useEffect` with missing dependencies (ESLint `exhaustive-deps` passes).
+- No prop drilling past 2 levels without context or composition.
+- All event handlers are typed.
+- No `any` in component props or hooks.

package/.agents/skills/review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: review
+description: Use after implementing a task to review the diff for correctness, regressions, and missing tests before handoff. Do not use for planning or verification evidence gathering.
+---
+
+## When to use
+After implementation, before handoff.
+
+## Scope
+- Review only the changed code and its immediate context.
+- Do not flag issues in unchanged code unless security-critical.
+- Adapt to the existing codebase style; do not propose rewrites for preference.
+
+## Checklist
+
+### Critical — must fix before merge
+- Security: hardcoded secrets, injection vectors, unchecked auth, unsafe deserialization.
+- Correctness: logic errors, data loss paths, race conditions, broken contracts.
+
+### High — should fix
+- Missing or swallowed error handling.
+- Missing or broken tests for changed behavior.
+- Backward-incompatible changes without migration path.
+
+### Medium — worth fixing
+- Boundary violations, mixed responsibilities, unclear control flow.
+- Weak input validation at trust boundaries.
+- Unnecessary complexity or premature abstraction.
+
+### Low — consider
+- Naming, readability, minor duplication.
+- Missing docs on non-obvious behavior.
+
+## Noise control
+- Report only issues you are >80% confident are real problems.
+- Skip pure style preferences that don't violate project conventions.
+- Consolidate similar issues: "5 functions missing error handling", not 5 separate items.
+- No padding with praise or filler.
+
+## Output
+
+```md
+# Review
+Verdict: <pass | changes required>
+
+## Findings
+- [critical] file:location — description
+- [high] file:location — description
+- [medium] file:location — description
+
+## Required fixes
+1. <fix or none>
+```
+
+## Rules
+- Every finding must include a file reference and a concrete description.
+- If severity is unclear, demote rather than promote.
+- If no issues: state verdict and briefly say why the change is acceptable.

package/.agents/skills/spec/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: spec
+description: Use for large, risky, or unclear work. Produces an approval-ready spec before coding. Do not use for small, local, well-defined tasks.
+---
+
+## When to use
+New systems, large features, risky or unclear changes, cross-cutting work.
+Not for small, local, well-defined tasks — use `$task` instead.
+
+## Process
+1. Explore relevant code, docs, and recent changes. Do not skip this.
+2. If the request spans multiple independent subsystems, decompose first — spec one subsystem at a time.
+3. Restate the request in plain terms.
+4. Identify missing decisions, assumptions, risks, and boundary questions.
+5. Ask clarifying questions one at a time. Ask only what materially affects design or implementation.
+6. Propose 2–3 approaches with trade-offs. Pick one and explain why.
+7. Choose or reuse a stable `<slug>` for the work item.
+8. Draft a concise spec using the template below. No filler.
+9. Self-review: check for placeholders, contradictions, scope creep, and gaps.
+10. Save to `plans/<slug>/spec.md`. Ask for approval.
+
+## Template
+
+```md
+# Spec: <title>
+
+## Problem
+## Goals
+## Non-goals
+## Scope
+## Constraints
+## Assumptions
+## Open questions
+## Acceptance criteria
+## Risks / compatibility notes
+```
+
+## Rules
+- Do not write implementation tasks. Do not start coding.
+- Cut features not required by the stated problem (YAGNI).
+- Acceptance criteria must be explicit and testable.
+  - Bad: "handles errors correctly"
+  - Good: "returns 400 with `{ error: string }` on invalid input"
+- Resolve or explicitly defer all open questions before presenting the spec.
+- Reuse an existing slug when resuming work on the same item.
+- Call out compatibility, migration, security, and operational concerns when relevant.
+- End by asking for approval and stating the save path.

package/.agents/skills/sqlite-queries/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: sqlite-queries
+description: Use when editing better-sqlite3 queries, repositories, transactions, statements, or row mapping. Do not use for schema, migration, pragma, or index changes — use sqlite-schema instead.
+---
+
+## When to use
+Query code, repositories, transactions, statements, and data access helpers.
+
+## Rules
+- Keep SQL close to the data-access layer; do not leak it across unrelated modules.
+- Prefer explicit SQL over hidden query builders unless the project already standardizes one.
+- Use prepared statements; do not interpolate untrusted values into SQL.
+- Keep transactions small, deliberate, and scoped to a single consistency need.
+- Return stable shapes from repositories; do not expose raw DB rows carelessly.
+- Normalize nullability, defaults, and type conversion at the boundary.
+- Avoid N+1 query patterns and repeated statement creation in hot paths.
+- Make read/write intent obvious in naming and structure.
+- Handle not-found, conflict, and constraint errors explicitly.
+- Keep connection setup, pragmas, and repository logic separate.
+
+## Before handoff
+- Untrusted input is parameterized.
+- Transaction boundaries are correct.
+- Returned shapes are stable.
+- Hot-path query behavior is reasonable.

package/.agents/skills/sqlite-schema/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: sqlite-schema
+description: Use when editing better-sqlite3 tables, columns, constraints, indexes, pragmas, or migrations. Do not use for query, transaction, or repository logic — use sqlite-queries instead.
+---
+
+## When to use
+Tables, columns, constraints, indexes, pragmas, and migrations.
+
+## Rules
+- Keep schema changes backward-compatible unless the approved spec says otherwise.
+- Prefer additive changes first; treat destructive changes as explicit migration work.
+- Define primary keys, unique constraints, foreign keys, and defaults deliberately.
+- Add indexes only for real query patterns; remove speculative indexes.
+- Make migrations deterministic, idempotent when practical, and easy to review.
+- Keep migration logic separate from request handling and app startup orchestration.
+- Document required pragmas and connection assumptions explicitly.
+- Preserve existing data unless a migration explicitly changes or drops it.
+- Test schema changes against realistic existing data states when possible.
+
+## Before handoff
+- Migration path is clear.
+- Roll-forward behavior is understood.
+- Indexes and constraints match actual usage.
+- Compatibility and data risks are named.

package/.agents/skills/ts/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ts
+description: Use for Node.js or TypeScript code changes. Do not use for SQLite-specific rules — pair with sqlite-schema or sqlite-queries instead.
+---
+
+## When to use
+Node.js or TypeScript code changes.
+
+## Type safety
+- Prefer TypeScript for new code. Use explicit types, narrow unions, small interfaces.
+- NodeNext ESM: keep `.js` in relative imports inside `.ts` files.
+- No `any` without a written reason. Prefer `unknown` + type guards.
+- No Enums. Use union types or `as const` objects.
+- No `as` assertions on external data. Parse at runtime (Zod, superstruct, or manual checks).
+- No `@ts-ignore` or `@ts-expect-error` without an explanatory comment.
+- No inline ESLint rule disables. Fix the underlying issue.
+- Use `import type` for type-only imports.
+
+## Boundaries and errors
+- Validate runtime input at process, HTTP, queue, CLI, and storage boundaries.
+- Handle errors deliberately — do not swallow or over-generalize.
+- Prefer typed error results over thrown exceptions for expected failures.
+- Avoid magic objects with implicit shapes; use stable contracts.
+
+## Module design
+- Keep transport, domain, infrastructure, and data access code separate.
+- Keep modules small and focused. No utility dumping grounds.
+- Use `contracts.ts` for exported or cross-module boundary types.
+- No wrappers that only forward arguments or rename obvious steps.
+- In entrypoints: one exported start function, minimal helpers.
+- Prefer role-local ENV parsing over shared config abstractions until duplication is concrete.
+- Prefer plain objects over interface hierarchies when values stay inside one module.
+
+## Control flow
+- Prefer `async`/`await`. Keep control flow visible.
+- Use `const` by default, `let` when reassignment is needed.
+- Prefer standard library or existing project tools over new dependencies.
+
+## Before handoff
+- `tsc --noEmit` passes (or equivalent typecheck script).
+- Linter passes without new suppressions.
+- Types are explicit. Control flow and error paths are readable.
+- Boundaries and responsibilities are clear. New abstractions are necessary and justified.

package/.agents/skills/verify/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: verify
+description: Use after code review to confirm task completion with evidence before handoff. Do not use as a substitute for implementation or code review.
+---
+
+## When to use
+After review, before handoff.
+
+## Process
+1. Re-read the task acceptance criteria.
+2. Map each criterion to evidence in code, tests, or observed behavior.
+3. Run relevant checks.
+4. Record anything not verified and why.
+
+## Checks to run (use what is relevant)
+- Tests
+- Lint / formatting
+- Type checks / build
+- Contract or API checks
+- Migration or config validation
+- Manual behavior verification for changed paths
+
+## Output
+
+```md
+# Verification
+## Acceptance criteria
+- <criterion> — <evidence>
+
+## Checks run
+- <command or check> — <result>
+
+## Unverified items
+- <none or item + reason>
+```
+
+## Rules
+- Do not claim verified without evidence.
+- Name skipped checks explicitly.
+- Do not mark the task done if verification is incomplete or failing.

package/AGENTS.md

@@ -0,0 +1,155 @@
+# AGENTS.md
+
+## Purpose
+Repository-wide workflow rules. Brief, strict, explicit.
+Use skills for reusable procedures. Use nested `AGENTS.md` for subtree overrides.
+All tasks, plans, and specs must be written in English.
+
+## Commands
+
+### $plan <description | path to spec file>
+Use for new systems, large features, risky or unclear work.
+
+Sequence:
+1. Read description or file.
+2. Use `spec` skill to produce an approval-ready spec.
+3. **STOP. Wait for user approval.**
+4. Use `plan` skill to produce a task plan.
+5. **STOP. Wait for user approval.**
+6. Implement the first task.
+7. Use `review` skill.
+8. Use `verify` skill.
+9. Handoff.
+10. **STOP. Wait for user approval before starting the next task.**
+
+### $task <description>
+Use for small, local, well-defined changes with low risk.
+
+Sequence:
+1. Restate the task.
+2. Short plan.
+3. Implement.
+4. Use `review` skill.
+5. Use `verify` skill.
+6. Handoff.
+
+Rule: if hidden complexity appears, switch to `$plan` immediately.
+
+### $fix <description>
+Same as `$task` with bug-fix framing. Identify root cause first. Minimal change only.
+
+### $resume
+Continue interrupted work in a new session with clean context.
+
+Sequence:
+1. Find the first `in_progress` task across all `plans/*/tasks.md`.
+2. Read its `Resume:` field. If empty, read `Scope` and `Touches`.
+3. If no `in_progress` task exists, take the first `todo` task.
+4. Continue implementation from that point.
+5. Follow the full-flow handoff sequence for the current task.
+
+### $status
+Show the state of all active plans.
+
+Sequence:
+1. Read all `plans/*/tasks.md`.
+2. List each plan: slug, current task, status of all tasks.
+
+### $done
+Trigger completion sequence for the current in-progress task.
+
+Sequence:
+1. Use `review` skill.
+2. Use `verify` skill.
+3. Handoff.
+
+## Stop points
+Wait for user approval at:
+- After spec (`$plan` flow).
+- After task plan (`$plan` flow).
+- After each task handoff (`$plan` flow).
+
+## Workflow artifacts
+Persist full-flow artifacts so work can resume across sessions.
+
+Required paths:
+- `plans/<slug>/spec.md` — approved specification.
+- `plans/<slug>/tasks.md` — approved task plan with current statuses and Resume fields.
+
+Rules:
+- One stable `<slug>` per work item. Reuse it throughout.
+- Keep `tasks.md` current after each handoff.
+- Update `Resume:` in the active task at every handoff: `<last file touched> — <what was done> — <next step>`.
+- Use explicit statuses: `todo`, `in_progress`, `done`.
+- The next task to resume must be unambiguous.
+
+## Definition of Ready
+Start implementation only when all are true:
+- Objective is clear.
+- Scope and boundaries are clear.
+- Constraints and compatibility expectations are clear.
+- Acceptance criteria are explicit.
+- Affected files, modules, or subsystems are known, or assumptions are stated.
+- Open questions that materially affect implementation are resolved or explicitly documented.
+
+## Definition of Done
+A task is done only when all are true:
+- Acceptance criteria are satisfied.
+- Changes are minimal, coherent, and scoped to the task.
+- Review found no unresolved critical issues.
+- Relevant verification was completed, or any skipped checks are named with reason.
+- Errors and edge cases introduced by the change are handled deliberately.
+- Backward compatibility is preserved unless the spec explicitly changes it.
+- Any required docs, config notes, or migration notes are updated.
+
+## Engineering rules
+- Prefer the smallest coherent change that satisfies the task.
+- Follow existing project conventions unless the task explicitly includes a cleanup.
+- Validate external input at the boundary.
+- Keep control flow and error handling explicit.
+- Avoid speculative abstractions, single-use wrappers, and unnecessary indirection.
+- Add or update tests when behavior, contracts, or edge cases change.
+- Prefer feature- or service-oriented slices over large multi-purpose modules.
+- Non-test source files: target `<=150` lines. Exceed `200` only with documented reason.
+- Test files: target `<=250` lines. Exceed `350` only with documented reason.
+- Keep reusable workflow detail in skills. Keep `AGENTS.md` at the policy level.
+- If a change alters workflow, commands, artifact formats, or architecture rules, update the affected skills in the same change.
+
+## Required skills
+- Large or unclear work: use `spec` first.
+- After spec approval: use `plan`.
+- After implementation: use `review`.
+- Before handoff: use `verify`.
+- TypeScript work that adds feature logic or grows a file past `150` lines: use `modules`.
+
+## Stack-specific skills
+- Node.js / TypeScript: use `ts`.
+- SQLite schema, migrations, pragmas, indexes: use `sqlite-schema`.
+- SQLite queries, transactions, repositories: use `sqlite-queries`.
+- React components, hooks, state: use `react`.
+- CSS / SCSS styles: use `css-scss`.
+- Fastify routes, plugins, schemas: use `fastify`.
+- Express routes, middleware, routers: use `express`.
+
+## Handoff format
+Use this format exactly:
+
+```md
+Flow: <plan|task|fix>
+Task: <task name or short summary>
+Summary:
+- <what changed>
+
+Files changed:
+- <path> — <why>
+
+Review:
+- <pass/fail + key findings>
+
+Verification:
+- <checks run>
+- <result>
+
+Risks / follow-ups:
+- <none or concrete item>
+```

package/README.md

@@ -0,0 +1,80 @@
+# codex-workflow
+
+Opinionated workflow for [Codex CLI](https://github.com/openai/codex) 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
+
+```bash
+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:
+
+```bash
+npx codex-workflow@latest init
+```
+
+For projects that only need core workflow skills (no stack-specific rules):
+
+```bash
+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.

package/bin/init.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const CORE_SKILLS = ['spec', 'plan', 'review', 'verify'];
+const STACK_SKILLS = ['ts', 'modules', 'sqlite-queries', 'sqlite-schema', 'react', 'css-scss', 'fastify', 'express'];
+
+const args = process.argv.slice(2);
+const subcommand = args.find(a => !a.startsWith('-'));
+
+if (!subcommand || subcommand !== 'init') {
+  console.log('Usage: npx codex-workflow init [--no-stack-skills]');
+  process.exit(subcommand ? 1 : 0);
+}
+
+const noStackSkills = args.includes('--no-stack-skills');
+const forceYes = !process.stdin.isTTY;
+const targetDir = process.cwd();
+const sourceDir = path.join(__dirname, '..');
+const skillsToCopy = noStackSkills ? CORE_SKILLS : [...CORE_SKILLS, ...STACK_SKILLS];
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function ask(question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+async function copyFile(src, dest) {
+  if (fs.existsSync(dest)) {
+    if (forceYes) {
+      console.log(`  overwriting ${path.relative(targetDir, dest)} (non-interactive)`);
+    } else {
+      const answer = await ask(`  Overwrite ${path.relative(targetDir, dest)}? [y/N] `);
+      if (answer.trim().toLowerCase() !== 'y') {
+        console.log(`  skipped ${path.relative(targetDir, dest)}`);
+        return;
+      }
+    }
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  console.log(`  copied  ${path.relative(targetDir, dest)}`);
+}
+
+async function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.warn(`  warn: source not found, skipping ${src}`);
+    return;
+  }
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function main() {
+  console.log('codex-workflow init\n');
+
+  await copyFile(
+    path.join(sourceDir, 'AGENTS.md'),
+    path.join(targetDir, 'AGENTS.md')
+  );
+
+  for (const skill of skillsToCopy) {
+    await copyDir(
+      path.join(sourceDir, '.agents', 'skills', skill),
+      path.join(targetDir, '.agents', 'skills', skill)
+    );
+  }
+
+  console.log('\nDone.');
+  console.log(`Skills installed: ${skillsToCopy.join(', ')}`);
+  rl.close();
+}
+
+main().catch(err => {
+  console.error(err.message);
+  rl.close();
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "codex-workflow",
+  "version": "1.0.0",
+  "description": "Opinionated workflow for Codex CLI — consistent dev process across Node.js projects",
+  "bin": {
+    "codex-workflow": "bin/init.js"
+  },
+  "files": [
+    "AGENTS.md",
+    ".agents/",
+    "bin/"
+  ],
+  "keywords": [
+    "codex",
+    "workflow",
+    "agents",
+    "ai",
+    "openai"
+  ],
+  "scripts": {
+    "release:patch": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public",
+    "release:major": "npm version major && npm publish --access public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}