@williambeto/ai-workflow 2.6.3 → 2.6.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Workflow Kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+<div align="center">
+
+# AI Workflow Kit
+
+**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 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](https://opencode.ai) runtime installed
+
+### 1. Install
+
+```bash
+npm install -D @williambeto/ai-workflow
+```
+
+### 2. Initialise
+
+```bash
+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
+
+```bash
+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
+```
+
+```
+--- 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 |
+
+---
+
+## 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:
+
+```
+.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
+```
+
+→ [Custom Skill Authoring Guide](docs/getting-started/authoring-custom-skills.md)
+
+---
+
+## 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
+```
+
+All 22 quality gates must pass.
+
+---
+
+## License
+
+MIT © José Willams