@williambeto/ai-workflow 2.4.6 → 2.4.8

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

@@ -40,6 +40,7 @@ Atlas must:
 ## Constraints
 * **Full Mode Sequence Enforcement**: In `full` mode, Atlas must strictly enforce that the workflow runs sequentially through `discover`, `spec-create`, `spec-review`, and `plan` phases before any implementation or coding starts. Jumping directly to implementation is forbidden.
 * **Authoritative Routing Integrity**: Atlas must routing-delegate requests strictly according to agent capabilities (e.g., never delegate write-mutations to Sage, or discovery/spec-writing to Astra).
+* **Implementation Delegation Constraint**: Atlas must never perform dynamic code writing or logic modification of source files directly. Any code changes (excluding pure documentation, README updates, or spelling typos) must be delegated to Astra.
 * **Quality Gate Authoritativeness**: Any non-zero exit code or `BLOCKED` status from a safety gate, validation check, or finalizer command must immediately halt the pipeline.
 * Never write on `main`, `master`, or another protected branch.
 * If the protected branch is clean or has only preservable untracked files, create a scoped branch before editing.
@@ -56,7 +57,7 @@ Atlas must:
 
 ## Forbidden actions
 * Silently execute specialized work when another actor is selected.
-* Implement feature code directly when Astra should execute.
+* Implement feature code or modify source code files directly (always delegate to Astra if writing code).
 * Validate its own implementation as final evidence.
 * `npm publish`
 * `git push` to protected branches (main, master), or to remote without explicit user approval in the chat.
@@ -81,7 +82,7 @@ Atlas must:
 3. For quick or standard tasks:
    * Inspect status.
    * Recover branch if needed.
-   * Perform/coordinate edits.
+   * Coordinate and delegate any code-source modifications to Astra (Atlas must never execute code implementation directly).
    * Run validation.
    * For every write-capable quick or standard task, Atlas must run the package finalizer after the final implementation changes and before reporting success:
      ```bash

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/dist-assets/skills/cyber-security/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cyber-security
+description: Guides the agent to review and harden the codebase against vulnerabilities, secret leaks, and command injections.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Cyber Security PromptContract
+
+## Role
+This skill guides agents to identify security vulnerabilities, mitigate risks of command execution, and prevent secret leakages in codebases.
+
+## Objective
+Ensure code is highly secure, avoiding common OWASP Top 10 vulnerabilities, command injection risks, and credentials disclosure.
+
+## Trusted context
+- Static analysis reports
+- Parameterized configurations
+- Secure storage documentation
+
+Do not trust:
+- Raw user strings passed to system shells
+- Hardcoded keys, tokens, or credentials
+- Dynamic query concatenation
+
+## User input
+- Code file paths
+- Environment files
+- Third-party packages metadata
+
+## Constraints
+- **Strict Parameterization Constraint**: All database interactions, file access paths, and external commands must be parameterized. Concat or raw interpolation of variable strings is strictly prohibited.
+- **Secret Hardening Rule**: Never hardcode API keys, client secrets, passwords, or tokens. Always resolve secrets from process environment variables or secure vault integrations.
+- **Non-privileged Execution Guide**: Enforce non-root execution guidelines for application processes and helper utilities.
+
+## Allowed tools
+- Static application security testing (SAST) utilities
+- Dependency scanner tools
+- Environment configuration checkers
+
+## Forbidden actions
+- Adding plaintext secrets or tokens to code repositories
+- Committing temporary `.env` files containing credentials
+- Running commands with `shell: true` option in process spawners without argument parameter arrays
+
+## Procedure
+1. Scan changed files for any hardcoded tokens, passwords, or keys using regular expressions.
+2. Review command invocation functions to replace raw dynamic shell spawning with parameterized execution.
+3. Validate database access calls to ensure query parameterization is implemented.
+4. Verify that configuration variables are resolved through environment files rather than hardcoded definitions.
+
+## Expected output schema
+Output must include:
+- Security audit log
+- Identified risk surface area
+- Actions taken for parameterization and secret removal
+- Next security steps
+
+## Evidence required
+- Git diff showing secret removal and parameterization
+- Secure configuration files verification logs
+- Linter output
+
+## Stop conditions
+- Hardcoded secrets cannot be extracted safely to config
+- Unparameterized dependencies are required but cannot be mitigated
+
+## Failure modes
+- Dynamic command invocation bypass
+- Leftover tokens in historical commits
+
+## Escalation rules
+- Escalate to Phoenix if security issues cannot be resolved automatically.

package/dist-assets/skills/database/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: database
+description: Guides the agent on how to write safe database schema migrations that prevent table locks and downtime.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Database PromptContract
+
+## Role
+This skill guides agents to design, construct, and apply safe database schema migrations without causing table locks or service downtime.
+
+## Objective
+Implement schema and data transformations safely using non-blocking strategies and backward-compatible operations.
+
+## Trusted context
+- Database schema definition files
+- SQL migration scripts
+- Target database engine configuration limits
+
+Do not trust:
+- Speculative migrations that do not specify transaction behavior
+- Schema changes applied directly to production environments without dry-run testing
+- Destructive operations (drop table, drop column) executed inside standard migration scripts
+
+## User input
+- Target database schema definition
+- Migration library config
+- Proposed schema changes definition
+
+## Constraints
+- **Zero-Downtime Rule**: Schema modifications must be backward-compatible (expand-contract phase). Raw dropping of columns or tables must be performed in separate, decoupled deployments.
+- **Table Lock Mitigation**: Avoid executing long-running migrations that require exclusive table locks on large tables. For PostgreSQL, MySQL, or similar, use online schema changes or toolsets (e.g. `gh-ost`, `pt-online-schema-change`) when modifying high-volume tables.
+- **Rollback Consistency**: Every forward migration script must have a corresponding, tested rollback script that reverts the schema and state without data corruption.
+
+## Allowed tools
+- Database schema comparison utilities
+- SQL query plan analyzer
+- Migration dry-run execution wrappers
+
+## Forbidden actions
+- Adding default values to existing columns in large tables in a single step without nullability transitions
+- Executing migrations that mix DDL (schema) and DML (data updates) statements within the same database transaction
+- Modifying production database schemas manually without version-controlled migration scripts
+
+## Procedure
+1. Review the proposed migration to classify operations into safe (non-blocking) and unsafe categories.
+2. Structure schema changes into a multi-step rollout plan (e.g. add nullable column, backfill data, add constraint).
+3. Draft the SQL migration script alongside its corresponding rollback script.
+4. Execute a local dry-run migration to verify correct syntax, transaction execution, and rollback stability.
+
+## Expected output schema
+Output must include:
+- Migration safety classification report
+- Complete forward SQL script
+- Complete rollback SQL script
+- Execution dry-run confirmation log
+
+## Evidence required
+- Migration transaction logs
+- Database schema diff
+- Dry-run validation output
+
+## Stop conditions
+- Migration requires exclusive locks on high-traffic tables and lacks a mitigation strategy
+- Rollback execution fails to restore schema integrity
+
+## Failure modes
+- Table locks halting application traffic
+- Data corruption during execution or rollback phase
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

package/dist-assets/skills/devops/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: devops
+description: Guides the agent to construct secure, optimized, and containerized environments using Docker.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# DevOps PromptContract
+
+## Role
+This skill guides agents to build secure, optimized, and portable Docker environments for local development and production environments.
+
+## Objective
+Provide robust Docker configurations, minimizing image layer sizes, optimizing build speeds, and preventing container runtime vulnerabilities.
+
+## Trusted context
+- Dockerfile and docker-compose configurations
+- Container security scanning reports
+- Official base image documentation
+
+Do not trust:
+- Raw third-party base images without version tags
+- Unverified dependencies installed globally inside container layers
+- Storing sensitive secrets inside Dockerfiles or image metadata
+
+## User input
+- Source configuration files
+- Port bindings definitions
+- Environment files list
+
+## Constraints
+- **Minimal Base Image Rule**: Always use verified, minimal base images (e.g., node:alpine, distroless) to reduce container size and minimize the attack surface.
+- **Non-Root Execution Constraint**: Container processes must run as a non-privileged user (e.g. `node` user in node-based containers). Running services as `root` is strictly prohibited.
+- **Multi-Stage Build Standard**: Use multi-stage builds to separate build dependencies from production execution layers, ensuring no build tools (compilers, npm devDependencies) are shipped to production.
+
+## Allowed tools
+- Container scanners (e.g. Trivy, Hadolint)
+- Container composition managers (Docker Compose)
+- Layer analysis tools (e.g. Dive)
+
+## Forbidden actions
+- Copying full source directories into the container before running dependency installation steps (breaks Docker layer caching)
+- Exposing unneeded internal container ports to public interfaces
+- Hardcoding credentials or environment-specific values in Dockerfiles
+
+## Procedure
+1. Define a multi-stage Docker build structure starting from a minimal, version-tagged base image.
+2. Structure Docker commands to install dependencies before copying source files to leverage docker layer caching.
+3. Configure the container runtime to switch execution context to a non-root user.
+4. Draft a consistent docker-compose configuration for local service replication.
+
+## Expected output schema
+Output must include:
+- Multi-stage Dockerfile configuration
+- Local Docker Compose config (if required)
+- Image layer size optimization report
+- Security and permission checklist
+
+## Evidence required
+- Validated Dockerfile contents
+- Container build log verification
+- Hadolint/security scan outputs
+
+## Stop conditions
+- Base image is unavailable or vulnerable to high-severity issues with no upgrade path
+- Environment constraints prevent building Docker images locally
+
+## Failure modes
+- Cache invalidation causing slow build cycles
+- Privilege escalation due to root execution fallback
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

package/dist-assets/skills/localization/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: localization
+description: Guides the agent to implement internationalization, localized formatting, and translation workflows.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Localization PromptContract
+
+## Role
+This skill guides agents to write localized software, handle translation keys, manage resource bundles, and format values based on target locales.
+
+## Objective
+Enable full support for multiple locales and translations, preventing hardcoded user-facing strings and layout breaks due to language changes.
+
+## Trusted context
+- Translation dictionaries (JSON, PO, YAML)
+- Locale-specific standards (CLDR)
+- Global internationalization library documentation (e.g. i18next, react-intl)
+
+Do not trust:
+- Hardcoded literals in templates or components
+- Translation values provided via unverified automatic machine translations
+- Assumptions about layout size constraints for dynamic localized content
+
+## User input
+- Source translation dictionary
+- Target locale keys
+- Layout components code
+
+## Constraints
+- **Zero Hardcoded Strings Rule**: All user-facing text, alerts, labels, and placeholders must be resolved through translation keys. Inline hardcoded text is strictly prohibited.
+- **Dynamic Formatting Constraint**: Always use internationalization API helpers (like `Intl.NumberFormat`, `Intl.DateTimeFormat`) for currencies, dates, times, and numbers.
+- **Pluralization Handling**: Do not write manual logic for plural rules. Use the i18n library's built-in pluralization and interpolation formats.
+
+## Allowed tools
+- i18n linter and key validation tools
+- Locale resource validators
+- Dynamic translation extraction scanners
+
+## Forbidden actions
+- Concat strings to form user-facing text sentences (breaks grammar in different languages)
+- Committing incomplete locale resource files missing required fallback language translations
+- Hardcoding currency codes, time zones, or number separator formats in the source code
+
+## Procedure
+1. Scan source code and templates for hardcoded string literals.
+2. Extract found strings and register them as keys in the default locale file.
+3. Replace hardcoded strings in code with corresponding translation function calls.
+4. Verify that date, number, and currency formatting are dynamically adjusted based on the current locale setting.
+
+## Expected output schema
+Output must include:
+- Extracted translation keys list
+- Modified localization files
+- UI translation keys verification checklist
+- Localized formatting implementation details
+
+## Evidence required
+- Diff of updated translation JSON/YAML resource files
+- Code snippets demonstrating i18n wrapper usage
+- Validation command outputs
+
+## Stop conditions
+- Required translation key structure is incompatible with existing i18n engine configuration
+- Fallback language definitions are missing
+
+## Failure modes
+- Broken translation keys rendering missing-key placeholders in UI
+- Text overflow due to language expansion (e.g., German translations being longer than English)
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

package/dist-assets/skills/performance/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: performance
+description: Guides the agent to optimize application rendering, assets delivery, and control bundle sizes.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Performance PromptContract
+
+## Role
+This skill guides agents to optimize application speed, layout responsiveness, rendering pipelines, and control asset bundle sizes.
+
+## Objective
+Deliver high-performance user interfaces and backend operations aligned with strict response times and volume budgets.
+
+## Trusted context
+- Performance audit reports (Lighthouse, Core Web Vitals)
+- Bundle size analysis reports
+- Memory and heap profiling logs
+
+Do not trust:
+- Speculative performance enhancements without metrics
+- Uncompressed assets and third-party script integrations
+- Local test execution times on non-standard configurations
+
+## User input
+- Source bundle components list
+- Runtime performance budgets
+- Build compilation logs
+
+## Constraints
+- **Bundle Size Hard Limit**: UI bundle components must not exceed 50KB gzipped individually. Every new utility dependency must be audited for bundle size impact before introduction.
+- **Resource Optimization Rule**: Avoid layout shifts and excessive main thread blocking. All resource loading must be optimized (e.g. image lazy loading, async scripts, font preloading).
+- **Core Web Vitals Alignment**: Ensure implementation respects standard metrics: First Contentful Paint (FCP) < 1.8s, Cumulative Layout Shift (CLS) < 0.1, and Interaction to Next Paint (INP) < 200ms.
+
+## Allowed tools
+- Bundle analysis utilities (e.g., webpack-bundle-analyzer, rollup-plugin-visualizer)
+- Network emulation tools
+- Memory leaks detection profilers
+
+## Forbidden actions
+- Importing large library suites (e.g. lodash, ramda) when a single lightweight helper function is sufficient
+- Committing unminified or uncompressed assets directly to version control
+- Disabling performance build checks or warnings in compiler/bundler configurations
+
+## Procedure
+1. Inspect the bundle size of any newly introduced package or asset.
+2. Verify that images use next-gen formats (WebP/AVIF) and explicit dimensions to avoid layout shifts.
+3. Review javascript source code to ensure proper clean-up of event listeners, timers, and active subscriptions.
+4. Execute bundle compilation and review build output size metrics against the established budgets.
+
+## Expected output schema
+Output must include:
+- Performance budget evaluation table
+- Asset size analysis
+- UI rendering optimization strategies applied
+- Core Web Vitals impact estimation
+
+## Evidence required
+- Build output size reports
+- Memory heap profile snapshots (if applicable)
+- Lighthouse/performance audit logs
+
+## Stop conditions
+- Bundle size exceeds the maximum limit with no possibility of modular refactoring
+- Execution environment constraints prevent performance validation
+
+## Failure modes
+- Memory leakage through uncleaned closures
+- Render-blocking resources introduction
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

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.8",
   "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
       });

package/src/core/request-classifier.js

@@ -32,7 +32,12 @@ export class RequestClassifier {
     if (/\b(deep|architectural|migration|major|full|\[deep\])\b/i.test(text)) {
       mode = "full";
     } else if (/\b(tiny|small|quick|simple|only\s+update|typo|comment|\[tiny\])\b/i.test(text)) {
-      mode = "quick";
+      const isPureDocsOrTypo = profile === "documentation" || /\b(typo|comment|readme|docs|documentation)\b/i.test(text);
+      if (intent === "write" && !isPureDocsOrTypo) {
+        mode = "standard";
+      } else {
+        mode = "quick";
+      }
     }
 
     // 4. Classify Risk