@williambeto/ai-workflow 2.2.0 → 2.2.6

package/README.md

@@ -75,22 +75,18 @@ Optional provider adapters can also generate `CLAUDE.md`, `GEMINI.md`, and Codex
 
 ## Documentation
 
-| 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) |
+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
 

package/dist-assets/docs/full-documentation.md

@@ -88,7 +88,6 @@ npx @williambeto/ai-workflow doctor
 - release
 - deploy
 
-
 ## Examples and runbooks
 
 Examples maturity: Complete (15 examples in catalog).

package/dist-assets/docs/policies/PROCEDURE_UI_CHECKLIST.md

@@ -31,7 +31,6 @@ Report:
 - missing error handling for critical action;
 - UI does not satisfy requested behavior.
 
-
 ## Rendered UI evidence
 
 For user-facing UI work, validation should inspect the rendered interface when the runtime can run or open the app. Prefer a browser screenshot, Playwright check, viewport check, or equivalent rendered inspection.

package/dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md

@@ -0,0 +1,85 @@
+# Skills Common Governance Policy
+
+This document defines the shared execution contracts, quality gates, and finalization requirements for all skill-backed capability files inside `@williambeto/ai-workflow`.
+
+---
+
+## Behavioral contract core
+
+All executing agents and specialist roles must respect these rules:
+- **Preserve Scope**: Preserve the requested scope and existing behavior unless change is explicit.
+- **Ownership**: Use the owning primary agent; a skill supplies domain judgment and must not pretend that delegation occurred.
+- **Reference Lookups**: Load the project conventions and the domain references named by this skill before making decisions.
+- **Truthfulness**: Do not invent capabilities, integrations, metrics, users, evidence, validation, security properties, or completed work.
+- **Proportionality**: Use the smallest safe execution mode and keep artifacts proportional.
+- **Delivery Support**: Implementation support must include relevant documentation, tests, validation, and current-task evidence.
+- **No Compromise**: A blocking finding remains `FAIL_QUALITY_GATE` or `BLOCKED`; never soften it to obtain completion.
+
+## Required context
+
+Before domain work, inspect the files, conventions, scripts, constraints, and existing behavior directly relevant to the request. If required context is unavailable, return a precise handoff or blocker instead of guessing.
+
+## Use when
+
+Use the skill when the task matches the specific domain expertise described in the skill purpose.
+
+## Do not use when
+
+- The task belongs to another primary owner or skill.
+- Bypassing branch safety, quality gates, or evidence is requested.
+
+## Purpose
+
+Provide common governance and execution guidelines for skills.
+
+## Core responsibilities
+
+- Enforce standard workflow guardrails.
+- Ensure consistent output reports and validation metrics.
+
+## Expected output
+
+All skill reports should be returned in this markdown format:
+
+```md
+## Skill Support Report
+
+Status: PASS | PASS_WITH_NOTES | FAIL_QUALITY_GATE | BLOCKED | NOT_RUN
+
+Skill:
+- [skill-name]
+
+Guidance:
+- [Domain-specific guidance and judgment applied]
+
+Evidence:
+- [Observed validation results and modifications]
+
+Recommendation:
+- [Actionable next steps]
+```
+
+## Stop conditions
+
+- Stop when domain guidance is complete and recommendations are compiled.
+- Stop if required validation or evidence is missing.
+
+## Quality failure examples
+
+- Claiming success without concrete observed evidence.
+- Attempting to edit files on protected main/master branches.
+- Bypassing quality gates or omitting mandatory test coverage.
+
+## Severity scale
+
+### High
+
+High severity means likely to break runtime behavior, safety gates, user-facing functionality, data integrity, or required docs/tests/evidence.
+
+### Medium
+
+Medium severity means reduces quality, maintainability, consistency, accessibility, or validation confidence without immediately breaking execution.
+
+### Low
+
+Low severity means wording, clarity, minor polish, or non-blocking maintainability improvement.

package/dist-assets/runbooks/how-to-use-skills.md

@@ -34,7 +34,6 @@ Use this runbook to choose the right capability skill for each workflow step in
 | `Sage` | `qa-workflow`, `deployment` |
 | `Orion` | `deployment`, `qa-workflow` |
 
-
 ## Validation reminder
 
 Before handoff or completion:

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

@@ -1,166 +1,17 @@
 ---
 name: architecture
 description: Skill-backed capability for architecture work
+governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Architecture Skill Contract
 
-
-## Runtime compatibility
-
-This file is plain Markdown and must remain usable as project instructions in OpenCode, Codex, Gemini, and Claude.
-
-Do not use runtime-specific tool syntax unless the file is explicitly a runtime adapter/template.
-
-If the runtime cannot call another agent directly, provide a useful handoff with exact next action instead of pretending delegation happened.
-
+This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
 
 ## Purpose
 
 Provide reusable domain guidance for `architecture` work.
 
-## Behavioral contract core
-
-These rules are loaded directly because they are too important to depend on optional reference lookup.
-
-- Preserve the requested scope and existing behavior unless change is explicit.
-- Use the owning primary agent; a skill supplies domain judgment and must not pretend that delegation occurred.
-- Load the project conventions and the domain references named by this skill before making domain decisions.
-- Do not invent capabilities, integrations, metrics, users, evidence, validation, security properties, or completed work.
-- Use the smallest safe execution mode and keep artifacts proportional.
-- Implementation support must include relevant documentation, tests, validation, and current-task evidence.
-- A blocking finding remains `FAIL_QUALITY_GATE` or `BLOCKED`; never soften it to obtain completion.
-
-## Required context
-
-Before domain work, inspect the files, conventions, scripts, constraints, and existing behavior directly relevant to the request. If required context is unavailable, return a precise handoff or blocker instead of guessing.
-
-## Finalization requirements
-
-- Return the canonical status and concrete evidence to the owning agent.
-- Write-capable work requires a safe non-protected branch, observed relevant validation, and no unresolved material failure. Workflow files are not proof by themselves.
-- Do not self-approve work that requires an independent validation owner.
-
-## Execution modes
-
-```txt
-readonly → Inspect → Report → Recommendation
-quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
-standard → Compact requirement → Compact technical plan → Implement → Document → Test/Validate → Compact evidence
-full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
-```
-
-## Use when
-
-Use this skill when the owning primary agent needs domain support related to `architecture`.
-
-## Do not use when
-
-- The task belongs to another primary owner.
-- The skill would bypass Branch Gate, validation, or evidence.
-- The skill would expand scope beyond the user request.
-
-## What good looks like
-
-- clear scope;
-- correct file placement;
-- evidence-based output;
-- validation appropriate to the selected mode;
-- useful handoff when outside domain.
-
-## Execution checklist
-
-1. Confirm the primary owner.
-2. Confirm the execution mode.
-3. Confirm scope.
-4. Apply domain-specific guidance.
-5. Identify validation and evidence needs.
-6. Return output to the primary owner.
-
-
-## Workflow guardrails
-
-Skills standardize domain work; they do not replace execution ownership.
-
-- Do not bypass Branch Gate Auto-Recovery.
-- Do not tell the owner to skip documentation, tests, validation, or evidence.
-- For implementation support, require modern UI quality when user-facing UI is involved.
-- Return guidance to the owning primary agent/command so execution can continue.
-
-## Validation checklist
-
-- Evidence is concrete.
-- Validation is run or marked NOT_RUN with reason.
-- Tests, documentation, and UI impact are addressed using explicit criteria: docs for runtime/API/config/user-facing changes; tests for behavior/data/validation/API helpers; UI checks for user-facing surfaces.
-- Output is not generic.
-
-
-## Quality gates
-
-Do not mark `PASS` when:
-
-- validation is missing or invented;
-- automated tests were technically viable but ignored or downgraded to `NOT_RUN`;
-- documentation was required but ignored;
-- user-facing UI is poor/raw or lacks relevant states;
-- files are in the wrong location;
-- scope expanded without approval;
-- the response is generic and not useful;
-- release/publish/tag/deploy action lacks explicit approval.
-
-
-
-## Severity scale
-
-Use this scale whenever the skill classifies findings or risks.
-
-### High
-
-High severity means likely to break runtime behavior, safety gates, user-facing functionality, data integrity, release safety, or required docs/tests/evidence.
-
-### Medium
-
-Medium severity means likely to reduce quality, maintainability, consistency, accessibility, or validation confidence without immediately breaking execution.
-
-### Low
-
-Low severity means wording, clarity, minor polish, or non-blocking maintainability improvement.
-
-## Expected output
-
-```md
-## Skill Support Report
-
-Status: PASS | PASS_WITH_NOTES | FAIL_QUALITY_GATE | BLOCKED | NOT_RUN
-
-Skill:
-- architecture
-
-Mode:
-- readonly | quick | standard | full
-
-Guidance:
-- ...
-
-Evidence:
-- ...
-
-Recommendation:
-- ...
-```
-
-## Quality failure examples
-
-- Claiming success without evidence.
-- Editing files on a protected branch.
-- Ignoring correct file placement.
-- Producing generic advice when executable guidance is required.
-- Over-engineering a simple task.
-- Skipping relevant UI/test/docs quality when the task requires it.
-
-## Stop conditions
+## Domain-Specific Guidance
 
-- Stop when domain guidance is complete.
-- Do not complete as “done” when another owner is required; return the needed owner/command so the owning agent can continue when the runtime can act.
-- Stop if required evidence is missing.
-- Stop if asked to bypass safety gates.
+Add specific capability guidelines, validation checklists, or design rules related to `architecture` here.

package/dist-assets/skills/backend-development/SKILL.md

@@ -1,166 +1,17 @@
 ---
 name: backend-development
 description: Skill-backed capability for backend development work
+governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Backend Development Skill Contract
 
-
-## Runtime compatibility
-
-This file is plain Markdown and must remain usable as project instructions in OpenCode, Codex, Gemini, and Claude.
-
-Do not use runtime-specific tool syntax unless the file is explicitly a runtime adapter/template.
-
-If the runtime cannot call another agent directly, provide a useful handoff with exact next action instead of pretending delegation happened.
-
+This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
 
 ## Purpose
 
 Provide reusable domain guidance for `backend-development` work.
 
-## Behavioral contract core
-
-These rules are loaded directly because they are too important to depend on optional reference lookup.
-
-- Preserve the requested scope and existing behavior unless change is explicit.
-- Use the owning primary agent; a skill supplies domain judgment and must not pretend that delegation occurred.
-- Load the project conventions and the domain references named by this skill before making domain decisions.
-- Do not invent capabilities, integrations, metrics, users, evidence, validation, security properties, or completed work.
-- Use the smallest safe execution mode and keep artifacts proportional.
-- Implementation support must include relevant documentation, tests, validation, and current-task evidence.
-- A blocking finding remains `FAIL_QUALITY_GATE` or `BLOCKED`; never soften it to obtain completion.
-
-## Required context
-
-Before domain work, inspect the files, conventions, scripts, constraints, and existing behavior directly relevant to the request. If required context is unavailable, return a precise handoff or blocker instead of guessing.
-
-## Finalization requirements
-
-- Return the canonical status and concrete evidence to the owning agent.
-- Write-capable work requires a safe non-protected branch, observed relevant validation, and no unresolved material failure. Workflow files are not proof by themselves.
-- Do not self-approve work that requires an independent validation owner.
-
-## Execution modes
-
-```txt
-readonly → Inspect → Report → Recommendation
-quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
-standard → Compact requirement → Compact technical plan → Implement → Document → Test/Validate → Compact evidence
-full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
-```
-
-## Use when
-
-Use this skill when the owning primary agent needs domain support related to `backend development`.
-
-## Do not use when
-
-- The task belongs to another primary owner.
-- The skill would bypass Branch Gate, validation, or evidence.
-- The skill would expand scope beyond the user request.
-
-## What good looks like
-
-- clear scope;
-- correct file placement;
-- evidence-based output;
-- validation appropriate to the selected mode;
-- useful handoff when outside domain.
-
-## Execution checklist
-
-1. Confirm the primary owner.
-2. Confirm the execution mode.
-3. Confirm scope.
-4. Apply domain-specific guidance.
-5. Identify validation and evidence needs.
-6. Return output to the primary owner.
-
-
-## Workflow guardrails
-
-Skills standardize domain work; they do not replace execution ownership.
-
-- Do not bypass Branch Gate Auto-Recovery.
-- Do not tell the owner to skip documentation, tests, validation, or evidence.
-- For implementation support, require modern UI quality when user-facing UI is involved.
-- Return guidance to the owning primary agent/command so execution can continue.
-
-## Validation checklist
-
-- Evidence is concrete.
-- Validation is run or marked NOT_RUN with reason.
-- Tests, documentation, and UI impact are addressed using explicit criteria: docs for runtime/API/config/user-facing changes; tests for behavior/data/validation/API helpers; UI checks for user-facing surfaces.
-- Output is not generic.
-
-
-## Quality gates
-
-Do not mark `PASS` when:
-
-- validation is missing or invented;
-- automated tests were technically viable but ignored or downgraded to `NOT_RUN`;
-- documentation was required but ignored;
-- user-facing UI is poor/raw or lacks relevant states;
-- files are in the wrong location;
-- scope expanded without approval;
-- the response is generic and not useful;
-- release/publish/tag/deploy action lacks explicit approval.
-
-
-
-## Severity scale
-
-Use this scale whenever the skill classifies findings or risks.
-
-### High
-
-High severity means likely to break runtime behavior, safety gates, user-facing functionality, data integrity, release safety, or required docs/tests/evidence.
-
-### Medium
-
-Medium severity means likely to reduce quality, maintainability, consistency, accessibility, or validation confidence without immediately breaking execution.
-
-### Low
-
-Low severity means wording, clarity, minor polish, or non-blocking maintainability improvement.
-
-## Expected output
-
-```md
-## Skill Support Report
-
-Status: PASS | PASS_WITH_NOTES | FAIL_QUALITY_GATE | BLOCKED | NOT_RUN
-
-Skill:
-- backend-development
-
-Mode:
-- readonly | quick | standard | full
-
-Guidance:
-- ...
-
-Evidence:
-- ...
-
-Recommendation:
-- ...
-```
-
-## Quality failure examples
-
-- Claiming success without evidence.
-- Editing files on a protected branch.
-- Ignoring correct file placement.
-- Producing generic advice when executable guidance is required.
-- Over-engineering a simple task.
-- Skipping relevant UI/test/docs quality when the task requires it.
-
-## Stop conditions
+## Domain-Specific Guidance
 
-- Stop when domain guidance is complete.
-- Do not complete as “done” when another owner is required; return the needed owner/command so the owning agent can continue when the runtime can act.
-- Stop if required evidence is missing.
-- Stop if asked to bypass safety gates.
+Add specific capability guidelines, validation checklists, or design rules related to `backend-development` here.

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

@@ -1,166 +1,17 @@
 ---
 name: deployment
 description: Skill-backed capability for deployment work
+governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Deployment Skill Contract
 
-
-## Runtime compatibility
-
-This file is plain Markdown and must remain usable as project instructions in OpenCode, Codex, Gemini, and Claude.
-
-Do not use runtime-specific tool syntax unless the file is explicitly a runtime adapter/template.
-
-If the runtime cannot call another agent directly, provide a useful handoff with exact next action instead of pretending delegation happened.
-
+This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
 
 ## Purpose
 
 Provide reusable domain guidance for `deployment` work.
 
-## Behavioral contract core
-
-These rules are loaded directly because they are too important to depend on optional reference lookup.
-
-- Preserve the requested scope and existing behavior unless change is explicit.
-- Use the owning primary agent; a skill supplies domain judgment and must not pretend that delegation occurred.
-- Load the project conventions and the domain references named by this skill before making domain decisions.
-- Do not invent capabilities, integrations, metrics, users, evidence, validation, security properties, or completed work.
-- Use the smallest safe execution mode and keep artifacts proportional.
-- Implementation support must include relevant documentation, tests, validation, and current-task evidence.
-- A blocking finding remains `FAIL_QUALITY_GATE` or `BLOCKED`; never soften it to obtain completion.
-
-## Required context
-
-Before domain work, inspect the files, conventions, scripts, constraints, and existing behavior directly relevant to the request. If required context is unavailable, return a precise handoff or blocker instead of guessing.
-
-## Finalization requirements
-
-- Return the canonical status and concrete evidence to the owning agent.
-- Write-capable work requires a safe non-protected branch, observed relevant validation, and no unresolved material failure. Workflow files are not proof by themselves.
-- Do not self-approve work that requires an independent validation owner.
-
-## Execution modes
-
-```txt
-readonly → Inspect → Report → Recommendation
-quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
-standard → Compact requirement → Compact technical plan → Implement → Document → Test/Validate → Compact evidence
-full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
-```
-
-## Use when
-
-Use this skill when the owning primary agent needs domain support related to `deployment`.
-
-## Do not use when
-
-- The task belongs to another primary owner.
-- The skill would bypass Branch Gate, validation, or evidence.
-- The skill would expand scope beyond the user request.
-
-## What good looks like
-
-- clear scope;
-- correct file placement;
-- evidence-based output;
-- validation appropriate to the selected mode;
-- useful handoff when outside domain.
-
-## Execution checklist
-
-1. Confirm the primary owner.
-2. Confirm the execution mode.
-3. Confirm scope.
-4. Apply domain-specific guidance.
-5. Identify validation and evidence needs.
-6. Return output to the primary owner.
-
-
-## Workflow guardrails
-
-Skills standardize domain work; they do not replace execution ownership.
-
-- Do not bypass Branch Gate Auto-Recovery.
-- Do not tell the owner to skip documentation, tests, validation, or evidence.
-- For implementation support, require modern UI quality when user-facing UI is involved.
-- Return guidance to the owning primary agent/command so execution can continue.
-
-## Validation checklist
-
-- Evidence is concrete.
-- Validation is run or marked NOT_RUN with reason.
-- Tests, documentation, and UI impact are addressed using explicit criteria: docs for runtime/API/config/user-facing changes; tests for behavior/data/validation/API helpers; UI checks for user-facing surfaces.
-- Output is not generic.
-
-
-## Quality gates
-
-Do not mark `PASS` when:
-
-- validation is missing or invented;
-- automated tests were technically viable but ignored or downgraded to `NOT_RUN`;
-- documentation was required but ignored;
-- user-facing UI is poor/raw or lacks relevant states;
-- files are in the wrong location;
-- scope expanded without approval;
-- the response is generic and not useful;
-- release/publish/tag/deploy action lacks explicit approval.
-
-
-
-## Severity scale
-
-Use this scale whenever the skill classifies findings or risks.
-
-### High
-
-High severity means likely to break runtime behavior, safety gates, user-facing functionality, data integrity, release safety, or required docs/tests/evidence.
-
-### Medium
-
-Medium severity means likely to reduce quality, maintainability, consistency, accessibility, or validation confidence without immediately breaking execution.
-
-### Low
-
-Low severity means wording, clarity, minor polish, or non-blocking maintainability improvement.
-
-## Expected output
-
-```md
-## Skill Support Report
-
-Status: PASS | PASS_WITH_NOTES | FAIL_QUALITY_GATE | BLOCKED | NOT_RUN
-
-Skill:
-- deployment
-
-Mode:
-- readonly | quick | standard | full
-
-Guidance:
-- ...
-
-Evidence:
-- ...
-
-Recommendation:
-- ...
-```
-
-## Quality failure examples
-
-- Claiming success without evidence.
-- Editing files on a protected branch.
-- Ignoring correct file placement.
-- Producing generic advice when executable guidance is required.
-- Over-engineering a simple task.
-- Skipping relevant UI/test/docs quality when the task requires it.
-
-## Stop conditions
+## Domain-Specific Guidance
 
-- Stop when domain guidance is complete.
-- Do not complete as “done” when another owner is required; return the needed owner/command so the owning agent can continue when the runtime can act.
-- Stop if required evidence is missing.
-- Stop if asked to bypass safety gates.
+Add specific capability guidelines, validation checklists, or design rules related to `deployment` here.