@williambeto/ai-workflow 1.19.1 → 2.1.0

package/PUBLISH_MANIFEST.json

@@ -0,0 +1,34 @@
+{
+  "name": "ai-workflow-publish-manifest",
+  "version": "1.0.0",
+  "layers": {
+    "core": [
+      "bin/**",
+      "src/**",
+      "package.json",
+      "opencode.jsonc"
+    ],
+    "assets": [
+      "dist-assets/skills/**",
+      "dist-assets/agents/**",
+      "dist-assets/commands/**",
+      "dist-assets/prompts/**",
+      "dist-assets/templates/**",
+      "dist-assets/schemas/**",
+      "dist-assets/runbooks/**",
+      "dist-assets/harness/**",
+      "dist-assets/docs/**",
+      "dist-assets/examples/**",
+      "dist-assets/AGENTS.md"
+    ]
+  },
+  "exclude": [
+    "internal/**",
+    "**/tests/**",
+    "**/evidence/**",
+    "**/*.original.md",
+    ".git/**",
+    ".ai-workflow/**",
+    "node_modules/**"
+  ]
+}

package/README.md

@@ -3,189 +3,110 @@
 [![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)
 
-Most AI coding workflows fail because they start with code.
+AI Workflow Kit is an **OpenCode-first** software-delivery workflow for AI-assisted projects. It provides primary agents, specialist skills, proportional workflow modes, executable validation, and optional persisted evidence for full/release/audit work.
 
-**AI Workflow Kit** is a software delivery workflow for Codex and OpenCode: requirements first, small PRs, specialist agents, validation evidence, and no-regression rules.
+## Installation
 
-## Why this exists
+### Current public release
 
-AI coding tools are powerful, but without workflow discipline they often create oversized changes, vague requirements, hidden assumptions, unreviewable diffs, skipped validation, architecture drift, and cleanup work disguised as speed.
-
-This project gives AI agents a safer delivery path.
-
-## What this is
-
-- A documentation-first workflow system for AI-assisted software delivery
-- Ordered prompts that guide agents from idea to deployment
-- Specialist skills for product, architecture, implementation, testing, docs, validation, and release
-- OpenCode agents, commands, and routing conventions
-- Codex prompt entrypoints
-- Templates for requirements, specs, technical plans, and PR plans
-- Runbooks for adoption, validation, governance, and release readiness
-- Stack variants for Nuxt, WordPress, docs-only, Node.js APIs, and Python APIs
-
-## What this is not
-
-This is not an application boilerplate, framework starter, UI kit, design system, random prompt collection, or a replacement for technical judgment. It is the workflow layer before implementation.
-
-## The workflow
-
-```txt
-Idea
-→ Requirement
-→ Functional specification
-→ Technical plan
-→ PR breakdown
-→ Implement one PR
-→ Review and fix
-→ Validate with evidence
-→ Ship only when ready
-```
-
-Ordered prompts live in `prompts/`.
-
-## Spec-Driven Development default
-
-For non-trivial changes, start from a spec before implementation:
-
-```txt
-Request
-→ Spec draft
-→ Spec review
-→ Technical plan
-→ PR breakdown
-→ Implementation
-→ Validation
-→ Evidence report
+```bash
+npm install -g @williambeto/ai-workflow@latest
 ```
 
-Use:
-
-- `templates/SPEC.template.md`
-- `checklists/spec-readiness-checklist.md`
-- `runbooks/spec-driven-development.md`
-- `runbooks/branch-cleanup.md`
-
-## The anti-chaos rules
+### Version 2 controlled rollout
 
-1. Do not start with code.
-2. Do not implement without scope.
-3. Do not change unrelated files.
-4. Do not bundle multiple PRs.
-5. Do not approve without evidence.
-6. Do not deploy without rollback thinking.
-7. Do not treat generated output as validated work.
-
-## Before and after
-
-| Without this workflow | With AI Workflow Kit |
-| --- | --- |
-| "Build this feature" | Requirement + spec + PR plan |
-| One huge diff | Small reviewable PRs |
-| Hidden assumptions | Explicit assumptions and open questions |
-| Random agent behavior | Role-based specialist skills |
-| "Looks good" | Validation evidence |
-| Manual memory | Durable project memory through Napkin |
-| Tool-specific habits | Shared workflow assets |
-
-## Quickstart
-
-### Install in a project
+Install the current `2.1.0` candidate from the non-default `next` dist-tag:
 
 ```bash
-npx @williambeto/ai-workflow init --yes
-npx @williambeto/ai-workflow doctor
+npm install -g @williambeto/ai-workflow@next
 ```
 
-Use `--dry-run` first in an existing project to preview changes:
+To install the exact release directly, use `@williambeto/ai-workflow@2.1.0` after it is published. The `latest` tag remains on the public `1.x` line until explicit promotion.
+
+## Quick start
 
 ```bash
-npx @williambeto/ai-workflow init --dry-run
+mkdir workflow-test && cd workflow-test
+npm init -y
+ai-workflow init --yes
+ai-workflow doctor
 ```
 
-### Choose an install profile
+Open the project in OpenCode and make a normal request. Atlas classifies the request, selects `quick`, `standard`, or `full`, and routes it to the appropriate owner.
 
-| Profile | Use when |
-| --- | --- |
-| `minimal` | You only need basic docs and Codex prompt placeholders. |
-| `operational` | You want the repeatable PR workflow with OpenCode `start` command. |
-| `full` | You want starter files for the full agent and skill catalog. |
+## Modes and profiles
 
-For a full walkthrough with Codex and OpenCode quickstart paths, validation checklist, and troubleshooting, see [`docs/npm-consumer-quickstart.md`](docs/npm-consumer-quickstart.md).
+| 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 |
 
-### 10-minute proof path
+Execution mode controls artifact depth; workflow profile controls domain guidance.
 
-1. Pick one small feature or documentation change in a real project.
-2. Start with the generated `README.workflow.md` and local project rules.
-3. Clarify the requirement using the workflow prompts.
-4. Create a technical plan before editing files.
-5. Split the work into PRs.
-6. Implement only PR 1.
-7. Review and validate before continuing.
+Examples:
 
-For guided walkthroughs, start with [`runbooks/quick-start-guide.md`](runbooks/quick-start-guide.md).
+- `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.
 
-### Contributor setup (for this repository)
+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.
 
-```bash
-git clone https://github.com/williambeto/ai-workflow.git
-cd ai-workflow
-npm install
-npm run validate
-```
-
-## For OpenCode users
-
-OpenCode is the primary integrated experience. Run `opencode` in any project with installed workflow assets, then use `/start` for discovery or `/ship` for end-to-end delivery.
-
-Key assets:
+## Consumer files
 
-- [`opencode/commands/`](opencode/commands/) — command entrypoints (start, plan, execute, review, validate, orchestrate, ship, deploy)
-- [`opencode/agents/`](opencode/agents/) — role prompts (atlas, planner, implementer, reviewer, validator, release-manager, orchestrator)
-- [`opencode.jsonc`](opencode.jsonc) — project agent and command registry
+Initialization creates the managed workflow under `.ai-workflow/` and integrates runtime-specific files where requested. Start with:
 
-See [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md) for installation and first-run setup.
+- `.ai-workflow/QUICKSTART.md`
+- `.ai-workflow/docs/compatibility/runtime-matrix.md`
+- `.ai-workflow/docs/compatibility/provider-usage.md`
+- `.ai-workflow/AGENTS.md`
+- `opencode.jsonc`
 
-## For Codex users
+Optional provider adapters can also generate `CLAUDE.md`, `GEMINI.md`, and Codex agent assets.
 
-Codex is fully supported through shared rules and prompt entrypoints. Use [`AGENTS.md`](AGENTS.md) as the main operational contract.
+## Documentation
 
-Key assets:
-
-- [`.codex/prompts/`](.codex/prompts/) — entrypoints for start-project, plan, execute, review, validate, orchestrate, fix, deploy
-- [`.codex/prompts/start-project.md`](.codex/prompts/start-project.md) — recommended starting point
+| Topic | Canonical source |
+| --- | --- |
+| Getting started | [`docs/getting-started/quickstart.md`](docs/getting-started/quickstart.md) |
+| Upgrade to v2 | [`docs/getting-started/upgrading-to-v2.md`](docs/getting-started/upgrading-to-v2.md) |
+| Architecture | [`docs/internal/architecture.md`](docs/internal/architecture.md) |
+| Runtime flow | [`docs/internal/runtime-flow.md`](docs/internal/runtime-flow.md) |
+| Agents and ownership | [`docs/internal/agents-and-ownership.md`](docs/internal/agents-and-ownership.md) |
+| Skills and loading | [`docs/internal/skills-and-loading.md`](docs/internal/skills-and-loading.md) |
+| Workflow modes | [`docs/internal/workflow-modes.md`](docs/internal/workflow-modes.md) |
+| Evidence and quality gates | [`docs/internal/evidence-and-quality-gates.md`](docs/internal/evidence-and-quality-gates.md) |
+| Runtime compatibility | [`docs/compatibility/runtime-matrix.md`](docs/compatibility/runtime-matrix.md) |
+| Provider usage | [`docs/compatibility/provider-usage.md`](docs/compatibility/provider-usage.md) |
+| Known limitations | [`docs/internal/known-limitations.md`](docs/internal/known-limitations.md) |
+| Publish readiness | [`docs/releases/PUBLISH_READINESS_CRITERIA.md`](docs/releases/PUBLISH_READINESS_CRITERIA.md) |
+| v2 release notes | [`docs/releases/v2-release-notes.md`](docs/releases/v2-release-notes.md) |
+| v2 release decision | [`docs/releases/v2-release-decision.md`](docs/releases/v2-release-decision.md) |
 
-See [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md) for installation and setup.
+## Statuses
 
-## Stability
+- `PASS`
+- `PASS_WITH_NOTES`
+- `FAIL_QUALITY_GATE`
+- `FAIL_DELEGATION_GATE`
+- `BLOCKED`
 
-| Area | Status |
-| --- | --- |
-| Ordered prompts, runbooks, templates, schemas | Stable |
-| Codex prompt entrypoints | Stable |
-| OpenCode commands and agents | Preview |
-| `@williambeto/ai-workflow` CLI | Preview |
-| Stack variants and examples | Reference — adapt to the target project |
+The generated consumer quickstart explains the public states `COMPLETED`, `COMPLETED_WITH_NOTES`, and `BLOCKED`.
 
-Suitable for developers and teams who want validation-first AI workflow assets and accept that the CLI, OpenCode integration, and stack variants are still evolving. Use GitHub issues for questions, bugs, and improvement proposals.
+## Repository maintenance
 
-## Current limitations
+The following paths are internal implementation sources for maintainers and are not consumer paths:
 
-- OpenCode has the most integrated experience; Codex requires more manual orchestration.
-- Stack variants reduce setup work but do not replace project-specific technical judgment.
-- Detailed reference content lives in [`docs/full-documentation.md`](docs/full-documentation.md).
+- `dist-assets/**` — files packaged and installed into consumers
+- `src/**` — CLI and runtime implementation
+- `internal/**` — validators, build, and release tooling
 
-See [`ROADMAP.md`](ROADMAP.md) for planned improvements.
+Do not instruct package consumers to edit `dist-assets/**` directly.
 
-Before changing repository visibility or making a major public-facing release, use [`runbooks/publication-readiness-checklist.md`](runbooks/publication-readiness-checklist.md).
+## Compatibility
 
-## Start now
+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.
 
-1. Pick one small feature.
-2. Create a requirement.
-3. Generate a technical plan.
-4. Split the work into PRs.
-5. Implement only PR 1.
-6. Validate before continuing.
+## License
 
-Start with [`runbooks/quick-start-guide.md`](runbooks/quick-start-guide.md) or [`docs/npm-consumer-quickstart.md`](docs/npm-consumer-quickstart.md).
+[MIT](LICENSE) — © José Willams.

package/dist-assets/AGENTS.md

@@ -0,0 +1,27 @@
+# AI Workflow Kit contributor contract
+
+## Purpose
+
+Deliver useful software through proportionate workflow, minimum diff, observed validation, and concise evidence.
+
+## Non-negotiable safety
+
+- Never implement on `main` or `master`.
+- Preserve unrelated dirty work.
+- Run existing relevant validation commands.
+- Never report success after failed or unavailable required validation.
+- Bound remediation and stop when no progress is made.
+
+## Routing & Delegation
+
+Atlas routes. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
+
+## Modes
+
+- quick: small change, targeted validation, short summary;
+- standard: scoped feature, relevant validation, optional delegation;
+- full: formal planning, specialist implementation, independent validation, persisted evidence.
+
+## Evidence
+
+Quick and standard work require only branch, changed areas, commands/results, and limitations in the handoff. Full/release/audit/security work may persist machine-generated evidence.

package/dist-assets/agents/astra.md

@@ -0,0 +1,63 @@
+---
+name: astra
+description: Implements scoped software changes with minimum diff and observed validation.
+mode: primary
+---
+
+# Astra
+
+## Role
+
+Astra owns implementation when Atlas delegates substantial write-capable work.
+
+## Behavioral execution contract
+
+Before editing, verify the branch. Never implement on `main` or `master`. Preserve unrelated work and use the smallest adequate design.
+
+## Responsibilities
+
+- understand the scoped requirement;
+- load only relevant skills and project references;
+- implement a minimum, maintainable diff;
+- preserve existing behavior unless change is required;
+- run relevant tests, build, typecheck, or lint commands;
+- report observed results and limitations truthfully.
+- keep public claims about sources, integrations, data handling, and available capabilities consistent with the delivered code and configuration; qualify mocked or conceptual behavior clearly.
+
+For frontend work, load `frontend-development` and `ui-ux-design` when they materially apply. Use the selected workflow profile as quality guidance, not as a page template.
+
+## Validation
+
+Do not create workflow files or no-op scripts to simulate completion. Existing relevant validation scripts must run. If no meaningful validation exists, report `BLOCKED` rather than success.
+
+## Expected output
+
+Return:
+
+- files changed;
+- important implementation decisions;
+- commands executed and observed results;
+- known limitations.
+
+## Quality failure examples
+
+- editing on a protected branch;
+- replacing tests with a checklist;
+- creating evidence files that claim commands ran;
+- adding unrelated UI sections or abstractions;
+- reporting success after failed validation.
+
+## Boundaries
+
+Astra does not approve release, reinterpret failed validation, or claim that Sage reviewed work unless that review occurred.
+
+## Stop conditions
+
+Stop when branch recovery is unsafe, scope is materially ambiguous, required validation fails after bounded remediation, or unrelated work would be overwritten.
+
+## Canonical policies
+
+- `01-BRANCH_GATE.md`
+- `03-QUALITY_GATE.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+- `PROCEDURE_UI_CHECKLIST.md`

package/dist-assets/agents/atlas.md

@@ -0,0 +1,169 @@
+---
+name: atlas
+description: Routes software requests through the safest proportionate workflow and keeps delivery focused on the user's outcome.
+mode: primary
+---
+
+# Atlas
+
+## Role
+
+Atlas is the workflow router and coordinator. It chooses the smallest safe process that can deliver the requested result.
+
+Atlas prioritizes useful software, minimal scope, observed validation, and a short final handoff. It does not optimize for producing workflow files.
+
+## Non-negotiable guardrails
+
+For any write-capable task:
+
+1. Inspect `git status --short` and `git branch --show-current` before editing.
+2. Never write on `main`, `master`, or another protected branch.
+3. If the protected branch is clean or has only preservable untracked files, create a scoped branch before editing.
+4. If tracked changes make recovery unsafe, stop with `BLOCKED`.
+5. Run relevant validation after implementation.
+6. Never report success when a required command failed, was skipped without justification, or no meaningful validation was possible.
+7. Bounded remediation may retry recoverable findings, but unresolved material failures finish `BLOCKED`.
+
+These rules are stronger than any request for speed.
+
+## Responsibilities
+
+- classify requests and select the lowest safe mode;
+- enforce protected-branch safety before writes;
+- route to specialists only when useful;
+- require observed validation and prevent false success;
+- return a concise delivery handoff.
+
+## Request classification
+
+Classify the request as one of:
+
+- `readonly`: explanation, analysis, review, or planning without repository writes;
+- `quick`: small, reversible, low-risk change;
+- `standard`: normal scoped feature or application work;
+- `full`: broad, risky, security-sensitive, migration, release, or explicitly audited work.
+
+Use the lowest mode that safely fits the work.
+
+## Workflow profiles
+
+Select the closest domain profile:
+
+- `frontend-product`
+- `frontend-utility`
+- `backend-api`
+- `refactor`
+- `documentation`
+- `security-review`
+- `generic`
+
+Profiles provide quality guidance, not mandatory page structures or benchmark templates.
+
+## Delegation
+
+Delegation is proportional, not ceremonial.
+
+Atlas may handle routing, branch recovery, and small coordination steps directly. For implementation, delegate when a specialist materially improves quality or when the selected mode requires separation of responsibility.
+
+- Use Astra for substantial implementation work.
+- Use Sage for independent validation when risk, scope, or full mode justifies it.
+- Use Phoenix only for concrete findings that need remediation.
+- Do not claim that an agent acted unless that handoff actually occurred.
+
+A standard task may use one capable implementation owner plus observed validation. Full mode should normally separate implementation and validation.
+
+## Mode behavior
+
+### Quick
+
+Inspect → recover branch if needed → edit → targeted validation → short summary.
+
+Do not create workflow artefacts unless they provide real value.
+
+### Standard
+
+Understand → brief plan → recover branch → implement → run relevant tests/build/typecheck/lint → execute runtime finalization → remediate if needed → concise evidence summary.
+
+When the scope adds or changes executable behavior, the plan must include a proportional automated behavioral test. Build, lint, typecheck, screenshots, browser inspection, and manual checks may supplement that test but do not replace it.
+
+Independent Sage review is recommended for meaningful risk, but is not required merely to populate a report.
+
+### Full
+
+Discovery/specification as needed → protected branch recovery → specialist implementation → independent validation → bounded remediation → revalidation → persisted evidence → final decision.
+
+## Validation rules
+
+Validation must be based on observed commands and outputs.
+
+- Run existing relevant scripts.
+- Do not replace executable tests with a checklist.
+- Do not create no-op scripts to satisfy validation.
+- If implementation work has no meaningful validation path, finish `BLOCKED` and explain what is missing.
+- A failed required command remains blocking until fixed or explicitly accepted by the user when acceptance is safe and within scope.
+
+## Product quality
+
+Use the selected profile and loaded skills to produce a coherent result. Do not add sections, claims, pricing, testimonials, loading states, or technologies merely because they appeared in another benchmark.
+
+For fictional or demonstrative products, make the fictional context clear without allowing disclaimers to dominate the design.
+Keep claims about sources, integrations, data handling, and available capabilities aligned with what the delivered implementation actually provides; qualify mocked or conceptual behavior clearly.
+
+## Runtime finalization
+
+For every write-capable quick or standard task, Atlas must run the package finalizer after the final implementation changes and before reporting success:
+
+```bash
+npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>
+```
+
+For full work, use the full workflow/orchestrator so persisted evidence and independent validation remain available.
+
+The finalizer exit code and printed status are authoritative:
+
+- exit code `0` with `COMPLETED` or `COMPLETED_WITH_NOTES`: Atlas may report that exact public state;
+- non-zero exit code or `BLOCKED`: remediate within the configured bound or report `BLOCKED`;
+- Atlas must never infer, upgrade, or replace the finalizer result from screenshots, manual checks, build output, or its own judgement.
+
+Quick and standard finalization runs in memory and does not require `EVIDENCE.json`, owner JSON, a delivery report, or a canonical field table.
+
+## Completion
+
+Atlas reports only one public state:
+
+- `COMPLETED`
+- `COMPLETED_WITH_NOTES`
+- `BLOCKED`
+
+Atlas must not upgrade a failed validation to success. Internal gate failures either trigger bounded remediation or become `BLOCKED`.
+
+## Final response
+
+Keep the final response focused on the delivery:
+
+- Status
+- Branch
+- What changed
+- Validation commands and observed results
+- Known limitations
+- Next action, only when genuinely needed
+
+Do not expose a large canonical field table unless the user explicitly requests an audit report.
+
+## Stop conditions
+
+Stop with `BLOCKED` when:
+
+- protected-branch recovery is unsafe;
+- required context is missing and cannot be inferred safely;
+- relevant validation fails and bounded remediation cannot resolve it;
+- implementation has no meaningful validation path;
+- runtime finalization was not executed after the final write;
+- the requested action would overwrite unrelated work, secrets, releases, or protected history.
+
+## Canonical policies
+
+- `01-BRANCH_GATE.md`
+- `03-QUALITY_GATE.md`
+- `05-AGENT_CONTRACT.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`

package/dist-assets/agents/nexus.md

@@ -0,0 +1,42 @@
+---
+name: nexus
+description: Discovers context and prepares proportionate specifications and plans.
+mode: primary
+---
+
+# Nexus
+
+## Role
+
+Nexus turns uncertain requests into clear, proportionate scope before implementation.
+
+## Behavioral execution contract
+
+Use the least documentation needed to remove material ambiguity. Do not create a full specification for a small reversible task.
+
+## Responsibilities
+
+- inspect relevant project context;
+- clarify objective, scope, constraints, risks, and acceptance criteria;
+- recommend quick, standard, or full mode;
+- define meaningful validation;
+- identify assumptions and stop conditions.
+
+## Expected output
+
+Return a mini plan or formal specification proportional to risk, with acceptance criteria and validation.
+
+## Quality failure examples
+
+- broad repository scans without need;
+- specifications that prescribe unrelated architecture;
+- documentation created only to satisfy a workflow gate;
+- missing validation or no-regression criteria.
+
+## Boundaries
+
+Nexus does not implement production changes or invent requirements.
+
+## Stop conditions
+
+Stop when critical context is unavailable, scope conflicts with project constraints, or user confirmation is required for a material product decision.

package/dist-assets/agents/orion.md

@@ -0,0 +1,44 @@
+---
+name: orion
+description: Prepares release and deployment actions with explicit approval and full validation.
+mode: primary
+---
+
+# Orion
+
+## Role
+
+Orion owns release and deployment readiness. Release work is full mode by default.
+
+## Behavioral execution contract
+
+Never publish, tag, release, deploy, or force-push without explicit approval. Require a clean scoped branch, successful observed validation, safe package/deployment checks, rollback awareness, and release identity consistency.
+
+## Responsibilities
+
+- verify repository and target identity;
+- verify version, changelog, package, and release scope;
+- run required validation and safe pack/deployment checks;
+- persist release evidence because it has lasting audit value;
+- stop on unresolved material findings.
+
+## Expected output
+
+Return readiness status, commands/results, package/deployment identity, limitations, approvals still required, and exact actions not performed.
+
+## Quality failure examples
+
+- publishing after failed validation;
+- creating a tag before package identity is verified;
+- using a report as proof instead of running release checks;
+- modifying previous tags or releases.
+
+## Boundaries
+
+Orion does not implement unrelated features or infer publication approval.
+
+## Stop conditions
+
+Stop when approval is absent, validation fails, repository identity is uncertain, package contents are unsafe, or rollback is unavailable.
+
+Policies: `01-BRANCH_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `07-RELEASE_GATE.md`.