AI Workflow Kit

Most AI coding workflows fail because they start with code.

AI Workflow Kit is a software delivery workflow for Codex and OpenCode: requirements first, small PRs, specialist agents, validation evidence, and no-regression rules.

Why this exists

AI coding tools are powerful, but without workflow discipline they often create oversized changes, vague requirements, hidden assumptions, unreviewable diffs, skipped validation, architecture drift, and cleanup work disguised as speed.

This project gives AI agents a safer delivery path.

What this is

• A documentation-first workflow system for AI-assisted software delivery
• Ordered prompts that guide agents from idea to deployment
• Specialist skills for product, architecture, implementation, testing, docs, validation, and release
• OpenCode agents, commands, and routing conventions
• Codex prompt entrypoints
• Templates for requirements, specs, technical plans, and PR plans
• Runbooks for adoption, validation, governance, and release readiness
• Stack variants for Nuxt, WordPress, docs-only, Node.js APIs, and Python APIs

What this is not

This is not an application boilerplate, framework starter, UI kit, design system, random prompt collection, or a replacement for technical judgment. It is the workflow layer before implementation.

The workflow

Idea
→ Requirement
→ Functional specification
→ Technical plan
→ PR breakdown
→ Implement one PR
→ Review and fix
→ Validate with evidence
→ Ship only when ready

Ordered prompts live in prompts/.

Spec-Driven Development default

For non-trivial changes, start from a spec before implementation:

Request
→ Spec draft
→ Spec review
→ Technical plan
→ PR breakdown
→ Implementation
→ Validation
→ Evidence report

Use:

• templates/SPEC.template.md
• checklists/spec-readiness-checklist.md
• runbooks/spec-driven-development.md

The anti-chaos rules

1. Do not start with code.
2. Do not implement without scope.
3. Do not change unrelated files.
4. Do not bundle multiple PRs.
5. Do not approve without evidence.
6. Do not deploy without rollback thinking.
7. Do not treat generated output as validated work.

Before and after

| Without this workflow | With AI Workflow Kit | | --- | --- | | "Build this feature" | Requirement + spec + PR plan | | One huge diff | Small reviewable PRs | | Hidden assumptions | Explicit assumptions and open questions | | Random agent behavior | Role-based specialist skills | | "Looks good" | Validation evidence | | Manual memory | Durable project memory through Napkin | | Tool-specific habits | Shared workflow assets |

Quickstart

Install in a project

npx @williambeto/ai-workflow init --yes
npx @williambeto/ai-workflow doctor

Use --dry-run first in an existing project to preview changes:

npx @williambeto/ai-workflow init --dry-run

Choose an install profile

| Profile | Use when | | --- | --- | | minimal | You only need basic docs and Codex prompt placeholders. | | operational (default) | You want the repeatable PR workflow with OpenCode start command. | | full | You want starter files for the full agent and skill catalog. |

For a full walkthrough with Codex and OpenCode quickstart paths, validation checklist, and troubleshooting, see docs/npm-consumer-quickstart.md.

10-minute proof path

1. Pick one small feature or documentation change in a real project.
2. Start with the generated README.workflow.md and local project rules.
3. Clarify the requirement using the workflow prompts.
4. Create a technical plan before editing files.
5. Split the work into PRs.
6. Implement only PR 1.
7. Review and validate before continuing.

For guided walkthroughs, start with runbooks/quick-start-guide.md.

Contributor setup (for this repository)

git clone https://github.com/williambeto/ai-workflow.git
cd ai-workflow
npm install
npm run validate

For OpenCode users

OpenCode is the primary integrated experience. Run opencode in any project with installed workflow assets, then use /start for discovery or /ship for end-to-end delivery.

Key assets:

• opencode/commands/ — command entrypoints (start, plan, execute, review, validate, orchestrate, ship, deploy)
• opencode/agents/ — role prompts (planner, implementer, reviewer, validator, release-manager, orchestrator)
• opencode.jsonc — project agent and command registry

See docs/setup-codex-opencode.md for installation and first-run setup.

For Codex users

Codex is fully supported through shared rules and prompt entrypoints. Use AGENTS.md as the main operational contract.

Key assets:

• .codex/prompts/ — entrypoints for start-project, plan, execute, review, validate, orchestrate, fix, deploy
• .codex/prompts/start-project.md — recommended starting point

See docs/setup-codex-opencode.md for installation and setup.

Stability

| Area | Status | | --- | --- | | Ordered prompts, runbooks, templates, schemas | Stable | | Codex prompt entrypoints | Stable | | OpenCode commands and agents | Preview | | @williambeto/ai-workflow CLI | Preview | | Stack variants and examples | Reference — adapt to the target project |

Suitable for private preview with developers who accept validation-first workflow assets and can report rough edges. Not ready for broad public announcement until the final public-readiness audit confirms no high-severity blockers remain.

Current limitations

• OpenCode has the most integrated experience; Codex requires more manual orchestration.
• Stack variants reduce setup work but do not replace project-specific technical judgment.
• Detailed reference content lives in docs/full-documentation.md.

See ROADMAP.md for planned improvements.

Start now

1. Pick one small feature.
2. Create a requirement.
3. Generate a technical plan.
4. Split the work into PRs.
5. Implement only PR 1.
6. Validate before continuing.

Start with runbooks/quick-start-guide.md or docs/npm-consumer-quickstart.md.