@williambeto/ai-workflow 2.4.6 → 2.4.7

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [2.4.7] - 2026-06-27
+
+### Added
+- Integrated `@vitest/coverage-v8` to compute code coverage, establishing a strict **80% minimum threshold** for lines, functions, branches, and statements in `vitest.config.js`.
+- Added the `npm run test:coverage` script in `package.json` for easy local and CI coverage reporting.
+- Created the official community Code of Conduct template at `.github/CODE_OF_CONDUCT.md` with maintainer contact method.
+- Excluded the `coverage/` directory from git tracking in `.gitignore`.
+
+### Fixed
+- Mitigated shell injection risks in the `cli-remediation-executor.js` by removing the insecure `shell:true` parameter and spawning native subprocess commands directly via platform detection (`npm` on POSIX and `npm.cmd` on Windows).
+- Fixed 3 failing unit tests in `visual-verifier.test.js` to align with the CSS variables flexibilization threshold (>200 chars) introduced in v2.4.6.
+- Documented `ai-workflow clean` limitations regarding the absolute deletion of custom `opencode.jsonc` configs in `cli-reference.md` and `troubleshooting.md`.
+
+### Changed
+- Bumped and updated development dependencies (dev-dependencies group) to their latest stable versions for security and build stability.
+
+## [2.4.6] - 2026-06-25
+
+### Fixed
+- Flexibilized Design System CSS variables check in `ArtifactFidelityGate` to only enforce the validation when CSS rules volume is substantial (>200 characters), preventing false-positive blocks on tiny or simple style additions.
+
 ## [2.4.5] - 2026-06-24
 
 ### Changed

package/dist-assets/docs/cli-reference.md

@@ -1,55 +1,207 @@
-# CLI reference
+# CLI Reference
+
+Complete reference for all `ai-workflow` (alias: `aw`) commands.
+
+## Global Usage
+
+```
+ai-workflow <command> [options]
+ai-workflow --version
+ai-workflow --help
+```
+
+---
+
+## `ai-workflow init`
+
+Installs AI Workflow Kit assets into a consumer project.
+
+**Synopsis:**
+```bash
+ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--profile=<profile>] [--gemini] [--claude] [--codex] [--antigravity]
+```
+
+**Description:**
+Creates the `.ai-workflow/` directory with agents, skills, commands, policies, and templates. Generates `opencode.jsonc`, updates `.gitignore`, and creates symlinks for `opencode` and `.agents`.
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Auto-approve all confirmations |
+| `--force` | Force overwrite existing files (backs up originals to `.ai-workflow-backups/`) |
+| `--dry-run` | Print actions without applying any changes |
+| `--no-install` | Skip installing npm dependencies |
+| `--no-overwrite` | Do not overwrite any existing files |
+| `--profile=<profile>` | Installation profile: `standard` (default) or `full` (includes examples) |
+| `--gemini` | Install Gemini platform adapter configuration |
+| `--claude` | Install Claude platform adapter configuration |
+| `--codex` | Install Codex platform adapter configuration |
+| `--antigravity` | Install Antigravity platform adapter configuration |
+
+**Example:**
+```bash
+ai-workflow init --yes --profile=full --gemini --claude
+```
+
+---
 
 ## `ai-workflow execute`
 
-Orchestrate execution of a natural request through the state machine.
+Orchestrates execution of a natural language request through the workflow state machine.
+
+**Synopsis:**
+```bash
+ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
+```
+
+**Description:**
+Accepts a natural language request, classifies intent, selects the appropriate workflow mode, creates a safe branch, delegates to the right agent, runs observed validation, and returns a structured delivery summary.
 
 | Flag | Description |
 | --- | --- |
-| `--task=<slug>` | Optional custom task slug for the workflow execution. |
-| `--request=<request>` | Positional or named natural language request. |
+| `"<request>"` | Positional argument: the natural language request |
+| `--request="<request>"` | Named alternative for the request string |
+| `--task=<slug>` | Optional custom task slug for the workflow execution |
+
+**Example:**
+```bash
+ai-workflow execute "Add input validation to the user registration form"
+ai-workflow execute --request="Refactor the database module" --task=db-refactor
+```
+
+---
 
 ## `ai-workflow run`
 
-Runs formal orchestration for an approved specification. It enforces branch safety, observed validation, bounded remediation, and handoff generation.
+Runs formal orchestration for an approved specification with branch safety, observed validation, bounded remediation, and handoff generation.
+
+**Synopsis:**
+```bash
+ai-workflow run --spec-path=<path>
+```
+
+**Description:**
+Reads an approved specification file and orchestrates the full implementation workflow. Enforces branch gate safety, runs validation commands, applies bounded remediation (up to configured attempt limits), and generates a handoff summary.
 
 | Flag | Description |
 | --- | --- |
-| `--spec-path=<path>` | Path to the approved specification file. |
+| `--spec-path=<path>` | Path to the approved specification file (required) |
 
-## `ai-workflow init`
+**Example:**
+```bash
+ai-workflow run --spec-path=.ai-workflow/specs/feature-auth.md
+```
+
+---
+
+## `ai-workflow validate`
+
+Runs the project validation suite including tests, linting, and quality checks.
+
+**Synopsis:**
+```bash
+ai-workflow validate [--a11y] [--visual-dist=<path>] [--port=<port>]
+```
 
-Installs the OpenCode-first workflow assets into a consumer project.
+**Description:**
+Executes the project's configured validation commands (`npm test`, `npm run lint`, `npm run build`, etc.) and optionally runs visual regression and accessibility checks.
 
 | Flag | Description |
 | --- | --- |
-| `--yes` | Auto-approve all confirmations. |
-| `--force` | Force overwrite existing files. |
-| `--dry-run` | Print actions without applying changes. |
-| `--no-install` | Skip installing dependencies. |
-| `--no-overwrite` | Do not overwrite existing files. |
-| `--gemini` | Install Gemini-specific configurations. |
-| `--claude` | Install Claude-specific configurations. |
-| `--codex` | Install Codex-specific configurations. |
-| `--antigravity` | Install Antigravity-specific configurations. |
-| `--profile=<profile>` | Specify installation profile (e.g. `standard`, `full`). |
+| `--a11y` | Run accessibility audit using Axe-core (requires Playwright) |
+| `--visual-dist=<path>` | Path to the built frontend assets for visual validation |
+| `--port=<port>` | Port to serve the frontend assets on for screenshot capture |
+
+**Example:**
+```bash
+ai-workflow validate
+ai-workflow validate --a11y --visual-dist=dist --port=3000
+```
+
+---
 
 ## `ai-workflow collect-evidence`
 
-Runs relevant project validation scripts and objective quality checks.
+Runs observed project validation and collects structured evidence.
+
+**Synopsis:**
+```bash
+ai-workflow collect-evidence [--task=<slug>] [--mode=<mode>] [--dry-run] [--visual-dist=<path>] [--port=<port>]
+```
+
+**Description:**
+Executes validation scripts, collects results, and produces a delivery summary. In `full` mode, persists an `EVIDENCE.json` artifact. Returns one of three statuses: `COMPLETED`, `COMPLETED_WITH_NOTES`, or `BLOCKED`.
 
 | Flag | Description |
 | --- | --- |
-| `--task=<slug>` | Optional task slug to target. |
-| `--mode=<mode>` | Validation mode (`quick`, `standard`, `full`). |
-| `--dry-run` | Run checks without writing `EVIDENCE.json`. |
+| `--task=<slug>` | Optional task slug to associate with the evidence |
+| `--mode=<mode>` | Validation mode: `quick`, `standard` (default), or `full` |
+| `--dry-run` | Run checks without writing `EVIDENCE.json` |
+| `--visual-dist=<path>` | Path to built frontend assets for visual validation |
+| `--port=<port>` | Port for serving frontend assets |
+
+**Example:**
+```bash
+ai-workflow collect-evidence --mode=full --task=auth-feature
+ai-workflow collect-evidence --dry-run
+```
+
+---
 
 ## `ai-workflow doctor`
 
-Checks the local installation and generated configuration.
+Verifies the local AI Workflow Kit installation and configuration.
+
+**Synopsis:**
+```bash
+ai-workflow doctor
+```
+
+**Description:**
+Checks that the CLI is properly installed, the project has a valid Git repository, Node.js version is compatible, and the `.ai-workflow/` configuration exists and is valid.
+
+**Example:**
+```bash
+ai-workflow doctor
+```
+
+---
+
+## `ai-workflow clean`
 
-## Public states
+De-initializes and removes AI Workflow Kit files and symlinks from the project.
 
-- `COMPLETED`
-- `COMPLETED_WITH_NOTES`
-- `BLOCKED`
+**Synopsis:**
+```bash
+ai-workflow clean [--yes] [--dry-run] [--purge-agents]
+```
+
+**Description:**
+Removes `.ai-workflow/`, `opencode.jsonc`, `.workflow-state.json`, and the `opencode` symlink. Prompts for confirmation unless `--yes` is provided. Use `--purge-agents` to also remove the `.agents/` directory.
+
+> [!WARNING]
+> **Limitations:** `ai-workflow clean` deletes the `opencode.jsonc` file entirely. If you had pre-existing configurations or custom additions merged into `opencode.jsonc` before or during initialization, they will not be restored to their original state. Back up any custom `opencode.jsonc` configs before cleaning.
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Skip confirmation prompt |
+| `--dry-run` | Preview what would be deleted without removing anything |
+| `--purge-agents` | Also remove the `.agents/` directory and symlink |
+
+**Example:**
+```bash
+ai-workflow clean --dry-run       # Preview
+ai-workflow clean --yes           # Remove without confirmation
+ai-workflow clean --purge-agents  # Remove everything including .agents/
+```
+
+---
+
+## Public Statuses
+
+All workflow commands that produce delivery summaries use these statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `COMPLETED` | All validation passed successfully |
+| `COMPLETED_WITH_NOTES` | Passed with recorded limitations or observations |
+| `BLOCKED` | Validation failed, approval missing, or policy violation detected |

package/docs/getting-started/quickstart.md

@@ -1,23 +1,117 @@
-# Quickstart
+# Quickstart — 5-Minute Guide
 
-1. Install and initialize AI Workflow Kit.
-2. Ask Atlas for a natural software outcome.
-3. Atlas selects quick, standard, or full mode and the closest domain profile.
-4. Write-capable work moves off protected branches before editing.
-5. Relevant validation runs before completion.
+Get AI Workflow Kit running in your project in under 5 minutes.
 
-## Completion
+## Prerequisites
 
-- `COMPLETED`
-- `COMPLETED_WITH_NOTES`
-- `BLOCKED`
+- **Node.js** ≥ 18 (LTS recommended)
+- **npm** ≥ 9
+- **Git** initialized repository
+- **OpenCode** runtime installed ([opencode.ai](https://opencode.ai)) — required for `aw run` and `aw execute`
 
-Quick and standard work return a concise summary with branch, changed areas, observed validation, and limitations. Full/release/audit/security work may persist structured evidence.
+## Step 1: Install
 
-Use `ai-workflow collect-evidence --mode=full` when a durable validation artefact is required. Do not use workflow files as substitutes for actual commands.
+```bash
+npm install -g @williambeto/ai-workflow
+```
 
-## Visual & Accessibility Evidence Requirements
+Verify the installation:
 
-If your project utilizes 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`.
+```bash
+ai-workflow doctor
+```
+
+Expected output:
+
+```
+✔ ai-workflow CLI found
+✔ Node.js version compatible
+✔ Git repository detected
+```
+
+## Step 2: Initialize your project
+
+Navigate to your project root and run:
+
+```bash
+cd your-project
+ai-workflow init
+```
+
+This installs the workflow assets into your project:
+
+```
+✔ Created .ai-workflow/
+✔ Created opencode.jsonc
+✔ Updated .gitignore
+✔ Installed 6 agents, 20 skills, 14 commands, 11 policies
+```
+
+### Init options
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Auto-approve all confirmations |
+| `--dry-run` | Preview changes without writing files |
+| `--profile=full` | Install with examples (default: `standard`) |
+| `--gemini` | Also install Gemini adapter config |
+| `--claude` | Also install Claude adapter config |
+| `--antigravity` | Also install Antigravity adapter config |
+
+## Step 3: Make a request
+
+With OpenCode running, ask Atlas for a natural software outcome:
+
+```bash
+ai-workflow execute "Add a health check endpoint to the Express API"
+```
+
+Atlas will:
+1. Classify the request intent
+2. Select the appropriate mode (`quick`, `standard`, or `full`)
+3. Create a safe branch (never writes to `main`)
+4. Delegate to the right agent (e.g., Astra for implementation)
+5. Run observed validation (tests, lint, build)
+6. Return a structured delivery summary
+
+## Step 4: Collect evidence
+
+After work is complete, collect validation evidence:
+
+```bash
+ai-workflow collect-evidence --mode=standard
+```
+
+Expected output:
+
+```
+--- Delivery Summary ---
+Status: COMPLETED
+Branch: feat/health-check
+Changes: src/routes/health.js, tests/health.test.js
+Validation: npm,test: PASS
+Known limitations: None recorded
+```
+
+## Completion statuses
+
+| Status | Meaning |
+| --- | --- |
+| `COMPLETED` | All validation passed |
+| `COMPLETED_WITH_NOTES` | Passed with recorded limitations |
+| `BLOCKED` | Validation failed or approval missing |
+
+## Visual & accessibility evidence
+
+If your project uses visual validation or accessibility audits, install the required dependencies:
+
+```bash
+npm install -D playwright @playwright/test axe-core
+npx playwright install chromium
+```
+
+## Next steps
+
+- [CLI Reference](../../dist-assets/docs/cli-reference.md) — all commands, flags, and examples
+- [Troubleshooting](./troubleshooting.md) — common errors and FAQ
+- [Upgrading to v2](./upgrading-to-v2.md) — migration guide from v1

package/docs/getting-started/troubleshooting.md

@@ -0,0 +1,123 @@
+# Troubleshooting
+
+Common issues, solutions, and frequently asked questions for AI Workflow Kit.
+
+## Common Errors
+
+### `Error: Not a git repository`
+
+**Cause:** `ai-workflow` requires a Git-initialized project directory.
+
+**Solution:**
+```bash
+git init
+ai-workflow init
+```
+
+### `Error: ai-workflow must not run init inside its own repository`
+
+**Cause:** You are running `ai-workflow init` inside the AI Workflow Kit source repository itself.
+
+**Solution:** Navigate to your consumer project directory before running `init`.
+
+### `Error: Current branch is protected (main/master)`
+
+**Cause:** The Branch Gate prevents writing directly to protected branches.
+
+**Solution:** The workflow will automatically create a feature branch. If on a dirty working tree, commit or stash changes first:
+```bash
+git stash
+ai-workflow execute "your request"
+```
+
+### `Status: BLOCKED — FAIL_QUALITY_GATE`
+
+**Cause:** Validation commands (`npm test`, `npm run lint`, `npm run build`) failed.
+
+**Solution:**
+1. Check the delivery summary for which command failed
+2. Fix the failing tests or lint errors
+3. Re-run: `ai-workflow collect-evidence --mode=standard`
+
+### `Error: opencode not found` or `ENOENT: opencode`
+
+**Cause:** The OpenCode runtime is not installed or not in your PATH.
+
+**Solution:**
+1. Install OpenCode from [opencode.ai](https://opencode.ai)
+2. Verify: `which opencode`
+3. If installed but not found, add it to your PATH
+
+### `BLOCKED — Delivery decision is blocking: BLOCK_STACK_CONFLICT`
+
+**Cause:** The request asks for a framework or stack that conflicts with the existing project setup.
+
+**Solution:** Be explicit about the target stack in your request, or use the `explicitApprovals` mechanism to override.
+
+### `Fidelity Violation: Design System token mismatch`
+
+**Cause:** CSS files with more than 200 characters of rules were detected without CSS custom properties (`var(--...)`), and the `frontend-design-system` skill is installed.
+
+**Solution:**
+- Add CSS custom properties to your stylesheets, or
+- Add explicit approval `no-css-vars` to bypass for simple/legacy stylesheets
+
+## Frequently Asked Questions
+
+### 1. Can I use AI Workflow Kit without OpenCode?
+
+The `init`, `doctor`, `clean`, `validate`, and `collect-evidence` commands work without OpenCode. However, `run` and `execute` require the OpenCode runtime to orchestrate agent workflows.
+
+### 2. Does `aw init` modify my existing code?
+
+No. It only creates workflow configuration files (`.ai-workflow/`, `opencode.jsonc`, symlinks) and appends entries to `.gitignore`. Your source code is never modified by `init`.
+
+### 3. How do I uninstall AI Workflow Kit from a project?
+
+```bash
+ai-workflow clean --yes
+```
+
+This removes `.ai-workflow/`, `opencode.jsonc`, `.workflow-state.json`, and the `opencode` symlink. Add `--purge-agents` to also remove `.agents/`. Use `--dry-run` to preview what will be deleted.
+
+> [!WARNING]
+> **Limitations:** `clean` deletes `opencode.jsonc` entirely. If you had pre-existing configurations or custom additions merged into `opencode.jsonc` before or during initialization, they will not be restored to their original state. Back up any custom `opencode.jsonc` configs before cleaning.
+
+### 4. Which AI platforms are supported?
+
+AI Workflow Kit includes adapters for:
+- **Gemini** (`--gemini`)
+- **Claude** (`--claude`)
+- **Codex** (`--codex`)
+- **Antigravity** (`--antigravity`)
+
+### 5. What is the difference between `standard` and `full` profiles?
+
+| Feature | `standard` | `full` |
+| --- | --- | --- |
+| Agents, skills, commands, policies | ✅ | ✅ |
+| Example specs and templates | ❌ | ✅ |
+| Default | ✅ | ❌ |
+
+### 6. Can agents push directly to `main`?
+
+No. The Branch Gate policy enforces that all write operations happen on feature branches (`feat/*`, `fix/*`, `chore/*`, `docs/*`). Direct pushes to `main` or `master` are blocked.
+
+### 7. How do I update to a newer version?
+
+```bash
+npm install -g @williambeto/ai-workflow@latest
+ai-workflow init --force
+```
+
+See [Upgrading to v2](./upgrading-to-v2.md) for detailed migration instructions.
+
+## Reporting Issues
+
+- **Security vulnerabilities:** Follow the process in [SECURITY.md](../../.github/SECURITY.md)
+- **Bug reports:** Open an issue in the project's GitHub repository with:
+  - AI Workflow Kit version (`ai-workflow --version`)
+  - Node.js version (`node --version`)
+  - Operating system
+  - Steps to reproduce
+  - Expected vs actual behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.4.6",
+  "version": "2.4.7",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -73,6 +73,7 @@
     "test": "npm run test:unit",
     "test:unit": "vitest run tests/unit/",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:e2e": "node tests/validate-e2e.mjs && vitest run tests/e2e/consumer-workflow.test.js",
     "test:e2e:runtime": "AI_WORKFLOW_RELEASE=1 vitest run tests/e2e/consumer-workflow.test.js -t \"Real OpenCode Smoke Test\"",
     "release:verify": "npm run clean:verify && npm test && npm run test:e2e && npm run validate && npm run pack:verify && npm run test:e2e:runtime",
@@ -90,10 +91,11 @@
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.8",
     "@semantic-release/npm": "^13.1.5",
+    "@vitest/coverage-v8": "^4.1.7",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "axe-core": "^4.10.0",
-    "markdownlint-cli": "^0.48.0",
+    "markdownlint-cli": "^0.49.0",
     "playwright": "^1.60.0",
     "semantic-release": "^25.0.3",
     "vitest": "^4.1.7"

package/src/core/healing/cli-remediation-executor.js

@@ -116,9 +116,11 @@ export function createCliRemediationExecutor(cwd) {
 
     for (const scriptName of toRetry) {
       process.stdout.write(`  → npm run ${scriptName} ... `);
-      const result = spawnSync("npm", ["run", scriptName], {
+      const isWin32 = process.platform === "win32";
+      const cmd = isWin32 ? "npm.cmd" : "npm";
+      const result = spawnSync(cmd, ["run", scriptName], {
         cwd,
-        shell: true,
+        shell: false,
         encoding: "utf8",
         timeout: 120000
       });