Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@williambeto/ai-workflow) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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
runbooks/branch-cleanup.md

The anti-chaos rules

Do not start with code.
Do not implement without scope.
Do not change unrelated files.
Do not bundle multiple PRs.
Do not approve without evidence.
Do not deploy without rollback thinking.
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`	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

Pick one small feature or documentation change in a real project.
Start with the generated README.workflow.md and local project rules.
Clarify the requirement using the workflow prompts.
Create a technical plan before editing files.
Split the work into PRs.
Implement only PR 1.
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 (atlas, 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 developers and teams who want validation-first AI workflow assets and accept that the CLI, OpenCode integration, and stack variants are still evolving. Use GitHub issues for questions, bugs, and improvement proposals.

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.

Before changing repository visibility or making a major public-facing release, use runbooks/publication-readiness-checklist.md.

Start now

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

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