next-codex-workflow

Repo-local Codex workflow installer for existing Next.js repositories.

New here: start with USER_JOURNEY.md for the end-to-end flow.

Status

v0.1 is implemented from nextjs-codex-workflow-kit-implementation-spec-v0.1.md.

Version Updates

• 0.1.0 Initial repo-local Codex workflow installer for existing Next.js repositories.
• 0.1.1 Stabilized the generated multi-agent workflow, bundled execution/testing quality skills, and hardened the verification/update path.
• 0.1.2 Added the explorer planning step, single-agent vs multi-agent workflow selection, the interactive installer, optional stage-prefixed auto-commit behavior, explicit subagent cleanup instructions, and stricter automated test policy generation.
• 0.1.3 Released with workflow hardening and release polish: repo-scoped Vitest discovery, optional auto-commit flow, gstack-strategist, explicit subagent cleanup instructions, and stricter automated test policy generation.
• 0.1.4 Adds selectable Next.js 16 Cache Components / PPR workflow mode, role-based default model tuning for workflow agents, and workflow history archiving with $archive-workflow.

What It Does

next-codex-workflow prepares an existing Next.js repository so Codex can use a structured implementation workflow inside that repository.

During init, it:

• validates that the target repository is a supported Next.js project
• detects router style, package manager, scripts, and TypeScript usage
• generates a short AGENTS.md with repo-specific workflow rules
• generates project-scoped Codex config and custom agents for planning, execution/refactors, testing, verification, and review
• generates repo-local skills for clarification, exploration, planning, decision logging, verification, and review
• generates short $skill-name workflow shortcuts so users do not need to keep retyping long Codex prompts
• supports both multi-agent and single-agent workflow modes
• can explicitly enable Next.js 16 Cache Components / PPR guidance for eligible App Router repositories
• can archive accepted workflow artifacts into task-scoped history snapshots
• can optionally create stage-prefixed git commits after completed workflow steps
• vendors approved external skills into the repository from bundled snapshots shipped with this package
• creates workflow artifact files as starter templates immediately during init
• writes an install-state manifest so future updates can refresh the workflow without re-entering the original setup flags
• creates a deterministic verification script
• optionally adds Lighthouse-based performance audit support

Supported Repositories

init currently expects:

• an existing package.json
• next declared in dependencies or devDependencies
• at least one of app/, src/app/, pages/, or src/pages/

Usage

npx next-codex-workflow init

When run in a normal terminal without --yes, init now guides the user through workflow mode, skill preset, optional performance setup, and optional automatic workflow commits.

After upgrading the package in a repo that already uses this workflow:

npx next-codex-workflow update

Example:

npx next-codex-workflow init --performance --external-skill-set full

Example with explicit workflow mode:

npx next-codex-workflow init --workflow-mode single-agent

Example with Next.js 16 Cache Components / PPR guidance:

npx next-codex-workflow init --ppr

Workflow Shortcuts

Codex supports explicit skill invocation by mentioning a skill with $. If the user prefers a picker UI, they can also open /skills and choose one of the generated workflow skills there. This package generates a few command-like shortcut skills so users can trigger the workflow with short prompts instead of rewriting the same instructions.

Examples after init in the target repository:

$plan-feature add saved search filters to the dashboard
$build-feature implement the approved dashboard filters plan
$verify-feature
$review-feature
$archive-workflow dashboard filters closeout

These are thin workflow entrypoints built on top of the generated planning, execution, testing, verification, and review agents plus the installed repo-local skills.

Subagent Workflow

One of the main strengths of this package is that it prepares the repository for orchestrated multi-agent work.

In practice, the main Codex session acts as the orchestrator:

• it keeps the feature request and repo-level goal in view
• it reads the workflow artifacts
• it delegates focused jobs to subagents when helpful
• it collects their results and returns one coherent outcome

The generated custom agents support that workflow:

• explorer for read-only repository inspection before planning
• planner for planning artifacts
• executor for implementation and refactor work
• tester for required automated coverage, test updates, and test-focused checks
• verifier for deterministic checks
• reviewer for final review

All six agents are expected to consult the relevant vendored quality skills in .agents/skills/. Planning and execution especially use those skills to shape architecture, file boundaries, implementation details, UI quality, and test impact. The tester and verifier agents also inspect the generated repo-test-policy skill so routing and browser behavior changes trigger Playwright coverage, while pure logic and service changes trigger Vitest-style coverage. The tester agent uses bundled vitest, playwright-best-practices, and playwright-cli guidance where relevant.

This is especially useful for larger changes where exploration, implementation, verification, and review benefit from being split into focused jobs. It is a quality and parallelism benefit, not a token-saving mode by itself.

The generated agents also ship with role-based model defaults so exploration, testing, and verification can use lighter settings while planning and review keep stronger reasoning by default.

Flags

• --yes Accept defaults automatically and skip the interactive installer prompts. This is the non-interactive path for scripts, CI, or quick setup. The default path uses multi-agent workflow mode and the recommended external skill preset.

• --performance Enables performance-mode generation. This adds the performance audit skill, agent-workflow/artifacts/PERF.md, scripts/run-lighthouse.mjs, agent-workflow/config/lighthouserc.cjs, and agent-workflow/config/budgets.json.

• --auto-commit Enables stage-prefixed workflow commits after completed shortcut steps. Generated prompts only attempt this when the git tree is scoped to the current workflow step.

  Prefixes:

  • plan:
  • build:
  • verify:
  • review:

  If unrelated pre-existing changes are present, the generated workflow should skip the commit and report why instead of creating a mixed commit.

• --ppr Enables Next.js 16 Cache Components / PPR guidance when the target repository is an eligible App Router project. When enabled, generated rules and agents explicitly evaluate Cache Components, use cache, and related static/cached/dynamic boundaries during planning and implementation.

• --routes <comma-separated-routes> Sets the routes used by the generated Lighthouse performance workflow. This is only meaningful together with --performance.

  Example:

  npx next-codex-workflow init --performance --routes /,/dashboard,/settings

• --external-skill-set <minimal|recommended|full> Controls how many bundled external skills are copied into the target repository.

  minimal Core external skills only. This includes the default testing quality skills.

  recommended Core skills plus the supported design/component/composition skills.

  full Everything from recommended, plus any remaining optional bundled skills.

• --workflow-mode <single-agent|multi-agent> Chooses whether the generated workflow shortcuts keep work in one session or route it through specialist spawned agents.

  multi-agent Uses explorer, planner, executor, tester, verifier, and reviewer through the generated shortcut skills, and the generated prompts tell Codex to close each spawned agent after its result is integrated.

  single-agent Keeps the same workflow artifacts and quality-skill guidance, but performs planning, implementation, testing, verification, and review in the current session instead of spawning specialist agents.

• --overwrite-managed Allows init to replace files that were previously generated by this tool. It still stops on user-owned files that already exist at those paths.

• --dry-run Prints the planned changes and validation results without writing any files.

Updating An Existing Installation

Use update after upgrading the package to refresh files that were previously generated by this tool:

npx next-codex-workflow update

If the package is installed as a dev dependency, the same flow is:

pnpm up next-codex-workflow@latest
pnpm next-codex-workflow update

update:

• reuses the saved install-state manifest from the previous install
• preserves the saved workflow auto-commit setting from the previous install
• preserves the saved Cache Components / PPR preference from the previous install
• refreshes files previously managed by this tool
• still stops on user-owned unmanaged files
• can fall back to inferring the prior install shape for older repositories that do not yet have the install-state manifest
• supports --dry-run for previewing the refresh

External Skill Sets

Current bundled presets:

• minimal next-best-practices, vercel-react-best-practices, vitest, playwright-best-practices
• recommended everything in minimal, plus building-components, web-design-guidelines, vercel-composition-patterns, and playwright-cli
• full everything in recommended, plus any remaining optional bundled skills

next-cache-components is controlled separately by --ppr. It is copied only when:

• --ppr is enabled
• the repository uses the App Router
• the detected Next.js major version is 16 or newer

What It Generates

The files below are generated into the target Next.js repository when you run npx next-codex-workflow init. They do not exist in this package repository by default because this repository is the installer itself.

• AGENTS.md
• .codex/config.toml
• .codex/agents/explorer.toml
• .codex/agents/planner.toml
• .codex/agents/executor.toml
• .codex/agents/tester.toml
• .codex/agents/verifier.toml
• .codex/agents/reviewer.toml
• .agents/skills/*
• agent-workflow/artifacts/PLAN.md
• agent-workflow/artifacts/FILE_SPECS.md
• agent-workflow/artifacts/DECISION.md
• agent-workflow/artifacts/VERIFY.md
• agent-workflow/artifacts/REVIEW.md
• agent-workflow/artifacts/PERF.md when --performance is enabled
• agent-workflow/history/HISTORY.md
• agent-workflow/history/index.json
• agent-workflow/manifest/install-state.json
• scripts/archive-agent-workflow.mjs
• scripts/verify-agent-workflow.mjs
• scripts/run-lighthouse.mjs when --performance is enabled

Workflow Artifacts

These artifact files are created during init as starter templates, then updated later as Codex works through a feature:

• PLAN.md Implementation plan for non-trivial work.
• FILE_SPECS.md File-by-file responsibilities, boundaries, and expectations.
• DECISION.md Append-only log of explicit user choices between viable options.
• VERIFY.md Human-readable verification record after deterministic checks run.
• REVIEW.md Structured post-implementation review output.
• PERF.md Performance audit notes when performance mode is enabled.

Completed workflow snapshots can also be archived with $archive-workflow. That writes task-level copies of the current artifacts into agent-workflow/history/tasks/<task-id>/ and updates:

• agent-workflow/history/HISTORY.md
• agent-workflow/history/index.json

What init Does Not Do

• It does not implement application features for you during installation.
• It does not fetch skills from the network during init. Bundled external skills are copied from vendored snapshots included in this package.
• It does not wait for a later user request to create the workflow artifact files; the artifact files are created immediately as templates during init.

Development Checks

npm install
npm run typecheck
npm run build
npm run test