@williambeto/ai-workflow 2.4.9 → 2.6.4

package/README.md

@@ -1,129 +1,255 @@
+<div align="center">
+
 # AI Workflow Kit
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/@williambeto/ai-workflow)](https://www.npmjs.com/package/@williambeto/ai-workflow)
+**Workflow before code. Evidence before trust.**
+
+[![npm version](https://img.shields.io/npm/v/@williambeto/ai-workflow?style=flat-square&color=0066cc)](https://www.npmjs.com/package/@williambeto/ai-workflow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D20.11-brightgreen.svg?style=flat-square)](package.json)
+[![Language](https://img.shields.io/badge/language-TypeScript-blue.svg?style=flat-square)](tsconfig.json)
+
+</div>
+
+---
+
+## 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](https://opencode.ai) 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 AI Workflow Kit is an npm/CLI package that installs a suite of agents, commands, skills, policies, and templates to guide a coding agent inside a project.
+## The problem it solves
 
-The central promise is:
+Coding agents are fast but undisciplined. Left to their own devices, they:
 
-> "Transform a natural language request into a proportionate, safe, and verifiable software delivery."
+- 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
 
-The workflow the product guarantees is:
+AI Workflow Kit enforces a contract: **the agent must earn the right to deliver.**
 
-1. **Request**: Understand the actual request.
-2. **Planning**: Select the execution mode and workflow profile.
-3. **Branch Gate**: Never implement directly on main/master.
-4. **Delegation**: Atlas routes; Astra implements; Sage validates when appropriate; Phoenix remediates within a defined limit.
-5. **Implementation**: Deliver useful code, not just reports.
-6. **Validation**: Run observed validations and relevant tests, blocking false success.
-7. **Evidence**: Summarize changes, validations, and limitations.
+---
 
-In practice, the kit is neither a frontend framework nor a UI library. It is an operational layer for software agents: it installs instructions and guardrails so that the agent can work more effectively inside the user's repository.
+## How it works
 
-## Installation and Usage
+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.
 
-### First-time usage
+When you run `npx aw execute "your task"`, Atlas (the coordinator) takes over:
 
-Use the full package command when running the kit before it is installed in a project:
+| 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](https://opencode.ai) runtime installed
+
+### 1. Install
+
+```bash
+npm install -D @williambeto/ai-workflow
+```
+
+### 2. Initialise
 
 ```bash
-npx @williambeto/ai-workflow init
+npx aw init --yes
 ```
 
-### Short alias after installation
+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
+```
 
-After installing AI Workflow Kit in a project, the shorter `aw` binary is available through `node_modules/.bin`:
+### 3. Run your first task
 
 ```bash
-npm install -D @williambeto/ai-workflow
+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
+
+```bash
+npx aw collect-evidence
+```
 
-npx aw init
-npx aw doctor
-npx aw run "Atlas, list all agents, subagents, skills, and commands in the project. Present them in a table with their name, description, and usage examples."
+```
+--- Delivery Summary ---
+Status:      COMPLETED
+Branch:      feat/health-check
+Changes:     src/routes/health.js, tests/health.test.js
+Validation:  npm test: PASS
+Limitations: None recorded
 ```
 
-The `aw` binary is an alias for the same CLI entrypoint as `ai-workflow`.
+> **Using Antigravity IDE?** Run `npx aw init --yes --antigravity` to enable Atlas directly from the agent selector dropdown.
 
-The CLI receives the natural request, classifies the intent, plans the workflow, switch/creates branch safely, delegates coding tasks to the OpenCode runtime adapter, validates changes, and runs bounded remediation if necessary before outputting the handoff summary.
+---
 
-### Visual & Accessibility (A11y) Requirements
+## The Agent Team
 
-For projects utilizing visual validation (screenshots) or accessibility audits (Axe-core), ensure you have:
-- `playwright` (or `@playwright/test`) and `axe-core` installed under `devDependencies`.
-- Browser binaries installed on the host machine by running `npx playwright install` (specifically Chromium).
+Each agent has a fixed role and cannot exceed its operational boundary.
 
-If these dependencies or browser binaries are missing, the visual and accessibility validations will fail gracefully with warning logs or block depending on CLI validation options.
+| 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 |
 
-## Modes and profiles
+Agents are installed as prompts in your `.ai-workflow/agents/` directory. You can read, audit, or customise them.
 
-| Mode | Use for | Primary evidence |
-| --- | --- | --- |
-| `quick` | Small, focused, low-risk work | Concise summary with targeted validation |
-| `standard` | Normal scoped feature or application work | Branch, changed areas, commands/results, limitations |
-| `full` | Broad, risky, architectural, migration, security, or release work | Independent validation and persisted evidence |
+---
 
-Execution mode controls artifact depth; workflow profile controls domain guidance.
+## CLI Commands
 
-Examples:
+| 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 |
 
-- `frontend-product` for landing pages and public product surfaces;
-- `frontend-utility` for validators, search pages, forms, dashboards, and focused tools;
-- `backend-api`, `refactor`, `documentation`, and `security-review` for their respective domains.
+---
 
-Profiles select relevant skills and objective checks. They do not force a fixed page structure, pricing, testimonials, or subjective visual style. See `.ai-workflow/docs/profiles/` after initialization.
+## Risk Levels and Policies
 
-## Consumer files
+AIWK automatically assigns a risk level to every request. Policies scale accordingly.
 
-Initialization creates the managed workflow under `.ai-workflow/` and integrates runtime-specific files where requested. Start with:
+| 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 |
 
-- `.ai-workflow/QUICKSTART.md`
-- `.ai-workflow/docs/compatibility/runtime-matrix.md`
-- `.ai-workflow/docs/compatibility/provider-usage.md`
-- `.ai-workflow/AGENTS.md`
-- `opencode.jsonc`
+You don't configure this. The kit reads your request and calibrates automatically.
 
-Optional provider adapters can also generate `CLAUDE.md`, `GEMINI.md`, and Codex agent assets.
+---
 
-## Documentation
+## What gets installed in your project
 
-For full guides, tutorials, and specifications, visit the [AI Workflow Kit Documentation Website](https://ai-workflow-kit-site.pages.dev/).
+Running `npx aw init` writes the following into your repository:
 
-### Local Consumer Files (created after `init`)
+```
+.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
+```
 
-When you initialize the kit in your project with `ai-workflow init`, the following guides are created locally in your `.ai-workflow/` folder:
+Everything is plain text — readable, auditable, and version-controlled.
 
-- **Getting Started**: `.ai-workflow/QUICKSTART.md`
-- **Architectural Policy**: `.ai-workflow/docs/architecture-policy.md`
-- **Design Conventions**: `.ai-workflow/docs/design-patterns-policy.md`
-- **Visual E2E Validation**: `.ai-workflow/docs/visual-validation-guide.md`
-- **Compatibility Matrix**: `.ai-workflow/docs/compatibility/runtime-matrix.md`
-- **Platform Governance**: `.ai-workflow/AGENTS.md`
+---
 
-## Statuses
+## Safety Guarantees
 
-- `PASS`
-- `PASS_WITH_NOTES`
-- `FAIL_QUALITY_GATE`
-- `FAIL_DELEGATION_GATE`
-- `BLOCKED`
+- **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.
 
-The generated consumer quickstart explains the public states `COMPLETED`, `COMPLETED_WITH_NOTES`, and `BLOCKED`.
+---
 
-## Repository maintenance
+## Skills
 
-The following paths are internal implementation sources for maintainers and are not consumer paths:
+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/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
+```
 
-- `dist-assets/**` — files packaged and installed into consumers
-- `src/**` — CLI and runtime implementation
-- `internal/**` — validators, build, and release tooling
+→ [Custom Skill Authoring Guide](docs/getting-started/authoring-custom-skills.md)
 
-Do not instruct package consumers to edit `dist-assets/**` directly.
+---
+
+## Documentation
+
+| Guide | Description |
+|:---|:---|
+| [Quickstart](docs/getting-started/quickstart.md) | Step-by-step 5-minute setup |
+| [Upgrading to v2](docs/getting-started/upgrading-to-v2.md) | Migration from v1 |
+| [Visual Validation Guide](dist-assets/docs/visual-validation-guide.md) | Screenshot and layout regression testing |
+| [Custom Skill Authoring](docs/getting-started/authoring-custom-skills.md) | Write project-specific guidance |
+| [CHANGELOG](CHANGELOG.md) | Full version history |
+| [Site](https://ai-workflow-kit-site.pages.dev/) | 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:
+
+```bash
+npm run validate
+```
 
-## Compatibility
+All 22 quality gates must pass.
 
-OpenCode is the primary runtime. Codex and Claude Code are supported with documented limitations. Gemini CLI is experimental. Adapter generation does not guarantee identical runtime behavior.
+---
 
 ## License
 
-[MIT](LICENSE) — © José Willams.
+MIT © José Willams

package/bin/ai-workflow.d.ts

@@ -0,0 +1,3 @@
+declare function runCli(args: string[]): Promise<void>;
+
+export { runCli };