AI Workflow Kit

Workflow before code. Evidence before trust.

What is AI Workflow Kit?

AI Workflow is an npm CLI that installs agents, commands, skills, policies and templates into your repository. It guides coding agents from request to implementation, validation and evidence.

AI Workflow Kit preserves workflow integrity so coding agents cannot skip from request to code to success without an explicit implementation path, proportional validation, and final evidence.

It works with OpenCode to turn a natural language request into a proportionate delivery — with branch isolation, optional specialist analysis, observed validation, and evidence appropriate to the task risk.

Without AIWK, a coding agent receives a request, writes code, and reports success. There is no proof, no branch isolation, and no guarantee that tests passed.

With AIWK, the same request travels through a mandatory workflow:

Your request  →  Classification  →  Branch Gate  →  Workflow Owner
     →  Observed Validation  →  Evidence  →  Handoff

Within the ai-workflow execute control plane, every stage is evaluated and a successful final state requires observed validation. Direct model chat remains subject to runtime capabilities; see the runtime compatibility matrix.

The problem it solves

Coding agents are fast but undisciplined. Left to their own devices, they:

• Write directly to main without a feature branch
• Skip tests if they think the change is "simple"
• Report Done! without any verifiable trace of what happened
• Mix discovery, implementation, and validation into one unstructured loop

AI Workflow Kit enforces a contract: the agent must earn the right to deliver.

How it works

AIWK installs a structured team of 6 core workflow agents into your repository. Each agent has a defined role and ownership boundary. Any core agent may request bounded analysis from a registered specialist when that improves the result, while retaining ownership of its workflow stage.

When you run npx aw execute "your task", Atlas (the coordinator) takes over:

| Step | Who | What happens | |:---|:---|:---| | 1. Classify | Atlas | Reads the request, assigns risk level (low / medium / high), selects evidence and spec policies | | 2. Branch Gate | Atlas | Creates feat/<task> from main. Never writes to protected branches. | | 3. Plan | Nexus / Orion | Writes a specification (when required by risk level) | | 4. Implement | Astra | Implements the change on the feature branch | | 5. Validate | Sage | Runs tests, accessibility checks, visual regression — writes evidence | | 6. Remediate | Phoenix | If validation fails, Phoenix heals within a bounded attempt limit | | 7. Evidence | Atlas | Saves the handoff and ledger; persists EVIDENCE.json when the evidence policy requires it |

Proportional by design. A typo fix in a README gets 1 remediation attempt and no spec. A payment integration gets 3 attempts, a required SDD, and mandatory persisted evidence. The kit calibrates automatically.

Quick Start

Prerequisites

• Node.js ≥ 20.11
• Git repository initialised (git init)
• OpenCode runtime installed

1. Install

npm install -D @williambeto/ai-workflow

2. Initialise

npx aw init --yes

This creates the .ai-workflow/ directory and installs 6 agents, 25 skills, 14 commands, operational prompts and runbooks, and the runtime policies into your project:

✔ Created .ai-workflow/
✔ Created opencode.jsonc
✔ Updated .gitignore
✔ Installed agents, commands, skills, prompts, runbooks, and policies

Existing project files are preserved. AIWK only updates its managed directory, adds missing package scripts, maintains a delimited .gitignore block, and merges missing OpenCode entries. It never overwrites root AGENTS.md; create or review that file with your runtime's /init command.

3. Run your first task

npx aw execute "Add a health check endpoint returning HTTP 200"

Atlas classifies the request, the branch gate establishes a safe branch, Astra owns requested changes, and validation and evidence run proportionally.

4. Check the evidence

npx aw collect-evidence \
  --request="Add a health check endpoint returning HTTP 200" \
  --task=health-check

Pass the original request when finalizing standalone work so AIWK can classify the delivery and select proportional validation. A successful read-only run with zero processed commands is not a project quality certification.

--- Delivery Summary ---
Status:      COMPLETED
Branch:      feat/health-check
Changes:     src/routes/health.js, tests/health.test.js
Validation:  npm test: PASS
Limitations: None recorded

Using Antigravity IDE? Run npx aw init --yes --antigravity to enable Atlas directly from the agent selector dropdown.

The Agent Team

Each agent has a fixed role and cannot exceed its operational boundary.

| Agent | Role | What it does | |:---|:---|:---| | 🧭 Atlas | Coordinator | Classifies requests, manages branches, routes to specialists | | 🔍 Nexus | Analyst | Researches codebase, defines requirements, authors specifications | | 📅 Orion | Planner | Sequences pull requests, coordinates releases and planning | | 💻 Astra | Engineer | Implements code changes safely on isolated feature branches | | 🧪 Sage | Validator | Audits changes, runs quality gates, writes verifiable evidence | | 🔧 Phoenix | Recovery | Heals broken states within a bounded remediation limit |

Agents are installed as prompts in your .ai-workflow/opencode/agents/ directory. You can read, audit, or customise them.

CLI Commands

| Command | Description | |:---|:---| | npx aw execute "<request>" | Run the full workflow from a natural language request | | npx aw run --spec-path=<path> | Run implementation against an existing specification | | npx aw validate | Execute all quality gates manually | | npx aw collect-evidence | Collect delivery evidence; persist EVIDENCE.json only when required | | npx aw doctor | Diagnose installation health | | npx aw clean | Remove all AIWK configuration from the project | | npx aw skill create <name> | Scaffold a workspace-local skill with valid frontmatter |

Risk Levels and Policies

AIWK automatically assigns a risk level to every request. Policies scale accordingly.

| Signal in your request | Risk | Spec required | Evidence persisted | Remediation attempts | |:---|:---:|:---:|:---:|:---:| | "fix typo in README" | Low | No | No | 1 | | "refactor auth module" | Medium | No | Optional | 2 | | "publish to npm", "payment integration" | High | Yes | Yes | 3 |

You don't configure this. The kit reads your request and calibrates automatically.

What gets installed in your project

Running npx aw init writes the following into your repository:

The canonical OpenCode runtime paths are .ai-workflow/opencode/agents/, .ai-workflow/opencode/commands/, .ai-workflow/opencode/skills/, and .ai-workflow/opencode/docs/. Operational references are installed under .ai-workflow/prompts/ and .ai-workflow/runbooks/.

.ai-workflow/
├── opencode/
│   ├── agents/      # Atlas, Nexus, Orion, Astra, Sage, Phoenix prompts
│   ├── commands/    # Slash commands for OpenCode
│   ├── skills/      # Domain skills (architecture, security, database, ...)
│   └── docs/        # Runtime policies, profiles, references, and guides
├── harness/         # Workflow and handoff harness
├── prompts/         # Operational prompts used by workflow phases
├── runbooks/        # On-demand execution and release guidance
├── schemas/         # Evidence and workflow schemas
├── templates/       # Specification and handoff templates
├── AGENTS.md         # Reference contract used by runtime adapters
├── QUICKSTART.md     # Installed quickstart
├── history/         # Runtime-generated workflow ledgers
└── handoffs/        # Runtime-generated delivery handoffs
opencode.jsonc        # OpenCode runtime configuration

Everything is plain text, readable, auditable, and reproducibly generated. The managed .ai-workflow/ directory is gitignored by default.

The root opencode runtime link is created only when its path is free. A real file, directory, or unrelated symlink at that path blocks initialization even with --force; consumer content is never replaced. Existing opencode.jsonc entries with the same name are preserved and reported as conflicts.

Safety Guarantees

• Branch gate: write-mode execution is blocked on main/master. A feature branch is created automatically when the worktree is clean.
• Read-only confinement: tasks classified as read-only compare SHA-256 workspace snapshots before and after execution; any observed mutation blocks completion.
• Bounded remediation: Phoenix is limited to N attempts. The kit never loops indefinitely.
• Mandatory handoff: every write-mode execution produces a HANDOFF-<task>.md with evidence, diff, and status — regardless of risk level.
• Schema-validated evidence: EVIDENCE.json is validated against a strict Ajv schema. Path traversal and shell injection are blocked.

Skills

Beyond the 6 core agents, AIWK ships 25 domain skills that agents activate as context lenses when the request profile warrants it. You can also author your own:

.ai-workflow/opencode/skills/
├── architecture/
├── backend-development/
├── cyber-security/       # activated by Sage on audit tasks
├── database/             # activated by Astra on schema work
├── frontend-design-system/
├── performance/
├── qa-workflow/
└── ... 18 more

→ Custom Skill Authoring Guide

Documentation

| Guide | Description | |:---|:---| | Quickstart | Step-by-step 5-minute setup | | Upgrading to v2 | Migration from v1 | | Visual Validation Guide | Screenshot and layout regression testing | | Custom Skill Authoring | Write project-specific guidance | | CHANGELOG | Full version history | | Site | Official documentation site |

Contributing

This development repository follows the AIWK contributor contract directly without installing consumer runtime assets into itself. To contribute:

src/           TypeScript source (CLI + Core)
dist-assets/   Templates, agents, skills, schemas installed into consumer repos
tests/         Unit, contract, linting, and E2E suites
internal/      Validation pipelines and release scripts
docs/          Guides, ADRs, specs, and release notes

Run the full validation suite before submitting a pull request:

npm run validate

All 23 quality gates must pass.

Contributors without server-side branch protection can enable the repository's local push safeguard explicitly:

npm run setup:hooks

The hook blocks pushes targeting main or master and allows maintenance or feature branches. It prevents accidents but is not a server-side security boundary and can be bypassed with Git's --no-verify option.

License

MIT © José Willams