@williambeto/ai-workflow 2.4.8 → 2.6.3

package/README.md

@@ -1,129 +0,0 @@
-# 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)
-
-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 central promise is:
-
-> "Transform a natural language request into a proportionate, safe, and verifiable software delivery."
-
-The workflow the product guarantees is:
-
-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.
-
-## Installation and Usage
-
-### First-time usage
-
-Use the full package command when running the kit before it is installed in a project:
-
-```bash
-npx @williambeto/ai-workflow init
-```
-
-### Short alias after installation
-
-After installing AI Workflow Kit in a project, the shorter `aw` binary is available through `node_modules/.bin`:
-
-```bash
-npm install -D @williambeto/ai-workflow
-
-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."
-```
-
-The `aw` binary is an alias for the same CLI entrypoint as `ai-workflow`.
-
-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
-
-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).
-
-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.
-
-## Modes and profiles
-
-| 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.
-
-Examples:
-
-- `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.
-
-## Consumer files
-
-Initialization creates the managed workflow under `.ai-workflow/` and integrates runtime-specific files where requested. Start with:
-
-- `.ai-workflow/QUICKSTART.md`
-- `.ai-workflow/docs/compatibility/runtime-matrix.md`
-- `.ai-workflow/docs/compatibility/provider-usage.md`
-- `.ai-workflow/AGENTS.md`
-- `opencode.jsonc`
-
-Optional provider adapters can also generate `CLAUDE.md`, `GEMINI.md`, and Codex agent assets.
-
-## Documentation
-
-For full guides, tutorials, and specifications, visit the [AI Workflow Kit Documentation Website](https://ai-workflow-kit-site.pages.dev/).
-
-### Local Consumer Files (created after `init`)
-
-When you initialize the kit in your project with `ai-workflow init`, the following guides are created locally in your `.ai-workflow/` folder:
-
-- **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
-
-- `PASS`
-- `PASS_WITH_NOTES`
-- `FAIL_QUALITY_GATE`
-- `FAIL_DELEGATION_GATE`
-- `BLOCKED`
-
-The generated consumer quickstart explains the public states `COMPLETED`, `COMPLETED_WITH_NOTES`, and `BLOCKED`.
-
-## Repository maintenance
-
-The following paths are internal implementation sources for maintainers and are not consumer paths:
-
-- `dist-assets/**` — files packaged and installed into consumers
-- `src/**` — CLI and runtime implementation
-- `internal/**` — validators, build, and release tooling
-
-Do not instruct package consumers to edit `dist-assets/**` directly.
-
-## Compatibility
-
-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.

package/dist-assets/runbooks/use-linear-for-operational-planning.md

@@ -1,45 +0,0 @@
-# Use an Issue Tracker for Operational Planning
-
-Use this runbook when a team wants issue-tracker discipline around AI Workflow Kit delivery.
-
-## Purpose
-
-Keep day-to-day execution small, current, and auditable without relying on historical roadmap or backlog documents.
-
-## Rule
-
-The source of truth for active work is the current request, current spec, current plan, current PR breakdown, and current evidence report.
-
-Historical planning artifacts must not override the current v2 operational contract.
-
-## Recommended issue fields
-
-- Title
-- Goal
-- Owner
-- Execution mode: readonly, quick, standard, full, restricted
-- Scope
-- Acceptance criteria
-- Validation commands
-- Evidence link
-- Status
-
-## Workflow
-
-1. Create or update the active spec.
-2. Review scope and readiness.
-3. Create a technical plan.
-4. Break work into small PRs.
-5. Implement with branch recovery.
-6. Document the change.
-7. Add automated tests when viable.
-8. Validate.
-9. Attach evidence.
-
-## Done means
-
-- Scope completed.
-- Documentation exists or has a concrete `NOT_APPLICABLE` reason.
-- Automated tests pass when viable.
-- Validation commands pass.
-- Evidence report is complete.

package/dist-assets/runbooks/use-napkin-project-memory.md

@@ -1,33 +0,0 @@
-# Use Project Memory
-
-This runbook explains how to keep durable project decisions available without creating excessive context noise.
-
-## Current name
-
-Use **Project Memory**. Older names are historical and must not be used in active runtime instructions.
-
-## What to store
-
-Store only durable information:
-
-- architectural decisions;
-- approved workflow contracts;
-- package/release constraints;
-- known runtime behavior;
-- validated project conventions;
-- important user decisions.
-
-Do not store temporary notes, scratch work, obsolete roadmaps, or completed backlog items.
-
-## When to update
-
-Update Project Memory when a task creates or changes a durable decision. Do not update it for ordinary implementation details unless they become project rules.
-
-## Evidence
-
-If Project Memory is updated, include it in the evidence report:
-
-- what changed;
-- why it is durable;
-- where it was stored;
-- validation performed.

package/dist-assets/templates/.geminiignore.template

@@ -1,8 +0,0 @@
-.ai-workflow/
-.ai-workflow-backups/
-node_modules/
-.git/
-EVIDENCE.json
-*.tgz
-*.zip
-*.tar

package/dist-assets/templates/GEMINI.md.template

@@ -1,20 +0,0 @@
-# Gemini Instructions — AI Workflow Kit
-
-Use AGENTS.md and the relevant contracts.
-
-```txt
-readonly → Inspect → Report → Recommendation
-quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
-standard → Mini spec → Mini review → Mini plan → Scoped PR plan → Implement → Document → Test/Validate → Evidence
-full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
-```
-
-Use professional taxonomy: Primary Agents, Skill-backed Specialist Roles, Skills, Commands.
-
-
-## Documentation, UI, security, and delivery artifact gates
-
-- Explicit requirements, clean code, generated specs, and inline comments do not replace documentation.
-- For user-facing UI, rendered or visual evidence is required when the runtime can inspect it; raw/default browser UI is `FAIL_QUALITY_GATE`.
-- High/Critical security findings must be classified in evidence.
-- Implementation work must create delivery artifacts proportional to mode: quick uses compact evidence, standard uses compact workflow artifacts, and full uses the complete 01..07 set.

package/docs/compatibility/provider-usage.md

@@ -1,46 +0,0 @@
-# Provider Usage
-
-## OpenCode
-
-```bash
-npx @williambeto/ai-workflow init --yes
-npx @williambeto/ai-workflow doctor
-```
-
-Use `opencode.jsonc` and the generated OpenCode assets as the primary workflow interface.
-
-## Codex
-
-```bash
-npx @williambeto/ai-workflow init --yes --codex
-```
-
-Review generated `.github/agents/`, `.agents/skills/`, and `.codex/prompts/`. Preserve the repository's existing `AGENTS.md`; do not assume Codex reproduces OpenCode delegation semantics.
-
-## Claude Code
-
-```bash
-npx @williambeto/ai-workflow init --yes --claude
-```
-
-Review `CLAUDE.md` and `.claude/rules/`. Existing user-authored instructions must not be overwritten without backup and explicit intent.
-
-## Gemini CLI
-
-```bash
-npx @williambeto/ai-workflow init --yes --gemini
-```
-
-Review `GEMINI.md` and `.gemini/`. Gemini support remains experimental until real-runtime scenario evidence is recorded.
-
-## Antigravity
-
-```bash
-npx @williambeto/ai-workflow init --yes --antigravity
-```
-
-Review `ANTIGRAVITY.md` and `.agents/`. Antigravity support remains experimental until real-runtime scenario evidence is recorded.
-
-## Multiple adapters
-
-Flags may be combined, but each generated runtime increases maintenance surface. Generate only the integrations the consumer project actually uses.

package/docs/compatibility/runtime-matrix.md

@@ -1,31 +0,0 @@
-# Runtime Compatibility Matrix
-
-## Compatibility levels
-
-- **Primary:** native project target and most thoroughly exercised path.
-- **Supported:** generated integration and package-level smoke coverage exist; runtime limitations are documented.
-- **Supported with limitations:** assets are generated, but behavior is not equivalent to the primary runtime.
-- **Experimental:** adapter exists, but real-runtime evidence is insufficient for a stronger claim.
-
-| Runtime | Level | Generated integration | Current evidence | Known limitations |
-| --- | --- | --- | --- | --- |
-| OpenCode | Primary | `opencode.jsonc`, OpenCode agents, commands, and skills | init, doctor, package smoke, generated-file checks | Model may bypass canonical commands in direct conversation |
-| Codex | Supported with limitations | `.github/agents/`, `.agents/skills/`, `.codex/prompts/` | adapter/unit/structural checks and generated asset inspection | No claim of identical multi-agent execution; `.codex/` output is optional and only generated with `--codex` |
-| Claude Code | Supported with limitations | `CLAUDE.md`, `.claude/rules/` | adapter/unit/structural checks and generated asset inspection | Rule loading and tool permissions depend on Claude Code configuration |
-| Gemini CLI | Experimental | `GEMINI.md`, `.gemini/agents/`, `.gemini/skills/`, `.gemini/commands/` | adapter/unit/structural checks and generated asset inspection | Native discovery and command behavior require real Gemini CLI validation before `Supported` |
-| Antigravity | Supported | `ANTIGRAVITY.md`, `.agents/agents/`, `.agents/skills/`, `.agents/commands/` | unit tests, validation suite, and WSL/Desktop consumer validation | Agents are only listed under `/agents` when actively running (instantiated via `invoke_subagent`) |
-
-## Claim policy
-
-Compatibility levels must be based on evidence available in the release. Adapter code or generated files alone are not proof of full behavioral parity.
-
-## Promotion requirements
-
-A runtime may be promoted only after a clean consumer test records:
-
-1. package installation;
-2. `init` with the runtime flag;
-3. expected generated assets;
-4. runtime startup or configuration validation;
-5. at least one quick workflow scenario;
-6. known limitations and failures.

package/docs/getting-started/DESKTOP_PROMPT.md

@@ -1,52 +0,0 @@
-# Antigravity Desktop System Prompt
-
-Este documento fornece as instruções de sistema (System Prompt) prontas para serem utilizadas no **Antigravity Desktop** (no Windows). Ele configura o agente desktop para carregar, entender e respeitar os contratos de agentes, comandos, habilidades (skills) e validações do **AI Workflow Kit** localizados no WSL, direcionando execuções de comandos de forma consistente e prevenindo dogfooding recursivo.
-
----
-
-## Prompt de Integração
-
-Copie e cole as instruções abaixo na configuração de **System Prompt** (ou como a primeira mensagem da sessão) do seu Antigravity Desktop no Windows:
-
-```markdown
-Você é o Antigravity atuando sob o protocolo do **AI Workflow Kit** configurado para este workspace. Seu objetivo é guiar o desenvolvimento de software respeitando as diretrizes, papéis e validações definidos no framework.
-
----
-
-### 1. Localização do Framework
-O repositório do **AI Workflow Kit** está localizado no caminho de rede WSL:
-`\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit`
-
-Antes de iniciar qualquer tarefa conceitual ou de implementação, leia e entenda as regras e definições contidas em:
-- O contrato de contribuição: [AGENTS.md](file:///wsl.localhost/Ubuntu/home/williambeto/Development/dev-kit/AGENTS.md)
-- Os agentes e papéis disponíveis em: `\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit\dist-assets\agents\`
-- Os comandos e fluxo de trabalho em: `\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit\dist-assets\commands\`
-- As habilidades (skills) de governança em: `\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit\dist-assets\skills\`
-
----
-
-### 2. Diretrizes de Comportamento e Não-Dogfooding
-- **Foco no Projeto Consumidor**: Você está desenvolvendo o código deste workspace específico (e não o próprio AI Workflow Kit). Use as regras de validação para garantir a qualidade do projeto atual.
-- **Evite Dogfooding Recursivo**: Não tente executar scripts de validação de forma aninhada ou recursiva na pasta do próprio framework `dev-kit`, a menos que seja explicitamente solicitado pelo usuário. O foco das execuções e comandos é o diretório de trabalho atual do seu workspace.
-- **Preservação de Estado**: Nunca altere branches protegidas (`main`/`master`) e preserve estados não rastreados que o usuário tenha deixado no repositório.
-
----
-
-### 3. Execução de Comandos em Ambiente WSL
-Como você está rodando no Windows Host e o projeto está no WSL, sempre que precisar rodar comandos do Git, Node, ou os próprios scripts do CLI do AI Workflow Kit, execute-os através do wrapper do WSL para garantir consistência de ambiente.
-Exemplos de execução:
-- Em vez de rodar direto no CMD, use: `wsl -d Ubuntu -- npm test` ou `wsl -d Ubuntu -- npm run validate`.
-- Para invocar o CLI local do projeto: `wsl -d Ubuntu -- ./node_modules/.bin/ai-workflow doctor`.
-
----
-
-### 4. Divisão de Papéis (Routing & Delegation)
-Assuma o papel correto dependendo da fase da tarefa solicitada pelo usuário:
-- **Nexus**: Para levantamento de requisitos, refinamento de ideias e escrita de especificações funcionais e técnicas (`SPEC.template.md`).
-- **Orion**: Para planejamento técnico de tarefas, criação de planos de testes e sequenciamento de Pull Requests.
-- **Astra**: Para a implementação de código funcional e modificação de arquivos de comportamento.
-- **Sage**: Para validação independente, testes de regressão e garantia de qualidade (nunca declare sucesso sem validação comprovada).
-- **Phoenix**: Para remediação rápida de falhas apontadas pelos validadores de qualidade.
-
-Por favor, confirme que leu os arquivos do framework no caminho indicado e que está pronto para atuar sob este protocolo.
-```

package/docs/getting-started/quickstart.md

@@ -1,117 +0,0 @@
-# Quickstart — 5-Minute Guide
-
-Get AI Workflow Kit running in your project in under 5 minutes.
-
-## Prerequisites
-
-- **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`
-
-## Step 1: Install
-
-```bash
-npm install -g @williambeto/ai-workflow
-```
-
-Verify the installation:
-
-```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

@@ -1,123 +0,0 @@
-# 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/docs/getting-started/upgrading-to-v2.md

@@ -1,62 +0,0 @@
-# Upgrading to version 2
-
-Version `2.x` is a breaking public line from the previous `1.x` line. Test upgrades in a disposable or non-critical consumer before replacing an existing installation.
-
-## Upgrade path
-
-1. Record the installed version and back up project-level runtime files.
-2. Remove the global package when applicable:
-
-   ```bash
-   npm uninstall -g @williambeto/ai-workflow
-   ```
-
-3. Install the current public release:
-
-   ```bash
-   npm install -g @williambeto/ai-workflow@latest
-   ```
-
-4. Inspect initialization before applying it:
-
-   For first-time or pre-installation usage:
-   ```bash
-   npx @williambeto/ai-workflow init --dry-run
-   npx @williambeto/ai-workflow init --yes
-   ```
-
-   After installing AI Workflow Kit locally in your project:
-   ```bash
-   npx aw init --dry-run
-   npx aw init --yes
-   npx aw doctor
-   ```
-
-## Main changes in version 2
-
-- OpenCode-first runtime with six primary ownership roles.
-- Proportional `quick`, `standard`, and `full` modes.
-- Observed validation, false-success prevention, and bounded remediation.
-- Concise quick/standard summaries without mandatory owner JSON, fixed delivery filenames, or `EVIDENCE.json`.
-- Full/release/audit/security workflows may persist structured evidence when traceability is required.
-- Semantic Product Truthfulness guidance without keyword-only enforcement.
-- Consumer files managed under `.ai-workflow/`.
-- Optional Codex, Claude Code, and Gemini adapter assets with documented limitations.
-
-## Breaking changes
-
-- Generated assets and configuration may differ substantially from `1.x`.
-- Legacy paths, taxonomies, aliases, and obsolete documentation are not retained as active sources.
-- Consumer-managed files should be reviewed before accepting initialization changes.
-- Direct prompts and provider behavior remain subject to the documented known limitations.
-
-## Rollback
-
-If you need to return to the previous public line during migration testing, install the known `1.x` version explicitly:
-
-```bash
-npm uninstall -g @williambeto/ai-workflow
-npm install -g @williambeto/ai-workflow@1.19.1
-```
-
-Restore backed-up project files when initialization changed consumer integrations.