AI Workflow Kit

Workflow before code. Evidence before trust.

What is AI Workflow Kit?

AI Workflow Kit (AIWK) is an npm CLI you install in your project that makes AI-assisted software delivery safe, structured, and verifiable.

It works with OpenCode to turn a natural language request into a full delivery — with branch protection, specialist agent delegation, automated validation, and a persisted evidence log.

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  →  Specialist Agent
     →  Automated Validation  →  Evidence  →  Handoff

No step can be skipped. No claim of success is made without proof.

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 specialist agents into your repository. Each agent has a defined role, a permission boundary, and cannot claim work that belongs to another.

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 EVIDENCE.json + HANDOFF-<task>.md to .ai-workflow/ |

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, and all policies into your project:

✔ Created .ai-workflow/
✔ Created opencode.jsonc
✔ Updated .gitignore
✔ Installed 6 agents, 25 skills, 14 commands, 11 policies

3. Run your first task

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

Atlas classifies the request, creates a branch, delegates to Astra, validates with Sage, and writes evidence — all automatically.

4. Check the evidence

npx aw collect-evidence

--- 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/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 and compile delivery evidence to EVIDENCE.json | | 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:

.ai-workflow/
├── agents/          # Atlas, Nexus, Orion, Astra, Sage, Phoenix prompts
├── commands/        # Slash commands for your AI IDE
├── skills/          # 25 domain skills (architecture, security, database, ...)
├── templates/       # Specification and handoff templates
├── policies/        # Branch gate, quality gate, merge gate policies
├── history/         # Ledger of every workflow execution
└── handoffs/        # HANDOFF-<task>.md for every completed delivery
opencode.jsonc        # OpenCode runtime configuration

Everything is plain text — readable, auditable, and version-controlled.

Safety Guarantees

• Branch protection: execution is always blocked on main/master. A feature branch is created automatically.
• Read-only confinement: tasks classified as read-only are cryptographically verified — any file mutation blocks the execution.
• 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:

.agents/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

AIWK uses itself to manage its own development. To contribute:

src/           TypeScript source (CLI + Core)
dist-assets/   Templates, agents, skills, schemas installed into consumer repos
tests/         Unit (296 tests) and E2E (19 tests) 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.

License

MIT © José Willams