Agentic Workflow Kit

Reusable Codex workflow kit for spec-driven development, agentic security, git hygiene, and safe publishing.

Quick Start

Create a new Next.js project with Bun and install the workflow kit:

bunx create-agentic-workflow-kit create my-app --template next --pm bun

Or use Bun's create flow after publishing the package:

bun create agentic-workflow-kit my-app --template next --pm bun

Install into an existing project:

bunx create-agentic-workflow-kit init .

What It Provides

• spec: plan atomic features with SDD before implementation.
• spec-writer: named specialist gate for feature scope and SDD quality.
• design-director: named specialist gate for UI/UX, visual craft, and motion.
• feature-architect: named specialist gate for technical plans and module boundaries.
• git-manager: named specialist gate for branch, staging, commit, push, PR/MR, tag, and release decisions.
• implement: build from approved SDD docs with checks and commits.
• modify: change documented features while keeping docs and code synchronized.
• security-review: review app, privacy, dependency, and agentic security risks.
• spec-ship: publish work branches safely.
• agentic-init: install or update this workflow kit in another repository.
• Project-scoped .codex/ runtime config with native read-only specialist agents, Plan mode reasoning tuning, and documented hooks/rules extension points.
• Codex best-practice standards for code review, external context/MCP usage, workflow retrospectives, and automation candidates.
• Agent Run Gate, development-plan workflow, feature evidence docs, and compliance scripts that fail closed before edit/commit/publish steps.
• Durable SDD reference archives for user-provided screenshots, logos, mockups, Figma links, and visual examples under docs/feature-<slug>/references/.
• Durable UI implementation artifacts under docs/feature-<slug>/artifacts/, with rendered screenshots and evidence that archived references were read and compared.
• shadcn-first design-system bootstrap for Next.js + Tailwind projects after docs/brief.md and docs/design.md exist.
• Playwright-first visual QA for browser-reachable UI, including @playwright/test, playwright.config.ts, Chromium browser install, and saved mobile/desktop artifacts.
• Tailwind-only component styling and Motion-first animation choreography rules for UI work.
• lucide-react as the default functional iconography system for React/Next.js UI work.
• Next.js architecture compliance for App Router boundaries, clean architecture feature modules, shared component naming, and GitLab MR handoff honesty.

Install Into A Project

From the target project root:

bunx create-agentic-workflow-kit init .

Or with the PowerShell installer:

powershell -NoProfile -ExecutionPolicy Bypass -File path\to\agentic-workflow-kit\scripts\Install-AgenticWorkflow.ps1 -TargetPath .

The installer adds:

• .agents/skills/
• .codex/
• AGENTS.md
• CLAUDE.md
• docs/standards/design-system.md
• docs/standards/design-compliance.md
• docs/standards/feature-modules.md
• docs/standards/server-actions.md
• docs/standards/code-review.md
• docs/standards/codex-workflow.md
• docs/standards/external-context.md
• docs/standards/automation-candidates.md
• For Next.js projects, neutral architecture anchors:
  • src/components/README.md
  • src/lib/README.md
  • src/lib/decorators/retry.ts
  • src/lib/decorators/timeout.ts
  • src/lib/decorators/types.ts
  • src/lib/logger.ts
  • src/lib/query-executor.ts
  • src/lib/result.ts
  • src/lib/safe-action.ts
  • src/lib/utils.ts
  • src/features/README.md

It does not overwrite existing files unless you pass -Force.

For Next.js projects, the scaffold also declares next-safe-action, zod, pino, pino-pretty, clsx, and tailwind-merge in package.json when they are missing, because src/lib/safe-action.ts, src/lib/logger.ts, src/lib/utils.ts, and the feature-module standards rely on them.

The .codex/ layer is intentionally separate from .agents/skills/. Skills hold reusable workflows; .codex/config.toml tunes the project runtime, and .codex/agents/*.toml defines native read-only Codex specialists for spec_writer, design_director, feature_architect, and git_manager. Hooks and rules are documented but inactive by default.

The installer does not create docs/development-plan.md. It installs a pending docs/standards/design-system.md scaffold. After installation, the user provides docs/brief.md and docs/design.md; then an agent creates docs/development-plan.md, completes the design-system baseline from those source documents, and adjusts AGENTS.md. The kit does not fabricate product truth or project-level visual direction.

The agent-created plan follows the v2 template: Agent Control Block, Inputs Reviewed, Build Strategy, Development Phases, Execution Plan, Parallel Work, Open Decisions, Agent Handoff, and Change Log. The agent must fill those sections from real project context and keep the YAML state synchronized with the control block.

Recommended first flow:

bun create agentic-workflow-kit my-app --template next --pm bun
cd my-app
agentic-workflow-kit doctor .

Then the user creates these two source documents:

docs/brief.md
docs/design.md

Then open Codex in the project and send this chat prompt:

Usa $agentic-init para finalizar el bootstrap del proyecto. Si estas en main/dev con solo archivos del instalador, crea o usa chore/agentic-bootstrap preservando esos cambios. Lee docs/brief.md y docs/design.md, crea docs/development-plan.md, configura el sistema de diseño shadcn/Tailwind en docs/standards/design-system.md y ajusta AGENTS.md con contexto real del proyecto. No implementes features todavia.

After that bootstrap is complete, start the first feature:

/spec first-atomic-feature

The user should not need to provide branch or file commands. After bootstrap, Codex must give one concrete next prompt from the development plan, such as Siguiente prompt recomendado: /spec user-onboarding-intake, not /spec <feature-slug> or a loose example. /spec <feature> owns the feature branch, SDD docs, checks, and spec commit. If Codex asks whether it may use subagents, answering sí/yes is enough.

For UI, onboarding, sensitive data, or product-defining fields, /spec must still ask a human discovery checkpoint before writing final SDD docs. Visual references are optional, but the agent must ask whether they exist or whether it should proceed from the project design docs. When references are absent, the workflow still requires a reference-free excellence contract from docs/brief.md, docs/design.md, docs/standards/design-system.md, existing UI, and the feature goal.

When the user provides screenshots, logos, mockups, image files, Figma links, app examples, or brand references, /spec must archive accessible files or durable URLs in docs/feature-<feature>/references/manifest.md before committing. Evidence that only says "attached in chat" is not enough for future implementation.

For /modify requests that make an SDD ready for implementation, the same checkpoint is required. The evidence must say Human discovery source: explicit user reply; inferred answers from docs or subagents are not enough.

For /implement UI work, successful lint/build is not enough. The implementation must read references/manifest.md before coding when user references exist, use Playwright for browser-reachable visual QA, save rendered screenshots under docs/feature-<feature>/artifacts/, then compare the result against design.md and the archived references in evidence.md before visual QA can be marked complete.

For Next.js + Tailwind UI work, $agentic-init must initialize shadcn/ui, install the core primitive set under src/components/ui, install Playwright (@playwright/test, Chromium browser binaries, and playwright.config.ts), complete docs/standards/design-system.md, and adapt primitives to docs/design.md before feature UI work begins. shadcn is the base, not the fidelity ceiling.

UI components should use Tailwind CSS utilities and shadcn primitive variants. globals.css is limited to Tailwind/shadcn imports, tokens, base layers, and documented exceptions.

Use the motion package for actual UI animation choreography. CSS keyframes/manual animation rules require documented exceptions.

For UI iconography, use lucide-react. If the dependency is missing, the SDD plan must declare it before implementation; agents should not hand-roll SVG icon components for functional controls.

Generated project instructions tell agents to respond in Spanish by default unless the user asks for another language.

CLI

agentic-workflow-kit init [target]
agentic-workflow-kit create <project-name> --template next --pm bun
agentic-workflow-kit doctor [target]
agentic-workflow-kit repair [target]

The Next.js generator uses create-next-app with TypeScript, App Router, Tailwind CSS, src/, Turbopack, and the requested package manager. It passes --no-agents-md so the generated project uses this kit's AGENTS.md instead of the default one.

Validate The Kit

bun run test
bun run doctor
bun run version:check

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\Test-AgenticWorkflowKit.ps1 -PluginPath .

Repair An Existing Installation

For repositories installed with an older kit version, run:

agentic-workflow-kit doctor .
agentic-workflow-kit repair .
agentic-workflow-kit doctor .

Or use the shortcut:

agentic-workflow-kit doctor . --fix

repair installs missing workflow files, scripts, standards, and Next.js architecture baseline files without overwriting existing files. Use --force only when you intentionally want to regenerate existing workflow files. It does not create docs/development-plan.md; that still belongs to the post-context bootstrap after user-provided docs/brief.md and docs/design.md exist.

Versioning

The npm package and Codex plugin manifest share the same SemVer version. Check them with:

bun run version:check

Bump both files together with:

bun run version:bump -- patch

Use major, minor, patch, or an explicit version such as 0.2.0-alpha.0. Update CHANGELOG.md before publishing. See VERSIONING.md for the release policy.

Project Model

Keep this repository as the source of truth for the reusable workflow. Each product repository should keep its own generated AGENTS.md, .codex/, and installed .agents/skills/, customized for that project's stack, domain, security posture, and git rules.