@williambeto/ai-workflow 2.2.0 → 2.2.6

package/dist-assets/skills/technical-leadership/SKILL.md

@@ -1,166 +1,17 @@
 ---
 name: technical-leadership
 description: Skill-backed capability for technical leadership work
+governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Technical Leadership 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 `technical-leadership` 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 `technical leadership`.
-
-## 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:
-- technical-leadership
-
-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 `technical-leadership` here.

package/dist-assets/skills/ui-ux-design/SKILL.md

@@ -1,202 +1,17 @@
 ---
 name: ui-ux-design
-description: Skill-backed capability for ui ux design work
+description: Skill-backed capability for ui ux-design work
+governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
 # Ui Ux Design 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 `ui-ux-design` 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 `ui ux design`.
-
-## 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.
-
-
-
-## Runtime safety
-
-This skill supports the owning agent. It does not bypass branch, documentation, testing, validation, evidence, UI, security, or release gates.
-
-## 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.
-
-
-
-## UI/UX behavioral quality baseline
-
-Before creating a user-facing page, define:
-
-- audience and user problem;
-- product promise and primary action;
-- page narrative from identity to proof to action;
-- one visual direction and a compact design system.
-
-Quality rules:
-
-- The first viewport must read as one intentional composition, not a collection of unrelated cards, badges, statistics, and CTAs.
-- Avoid generic SaaS layouts as the automatic default. Cards are a tool, not the page structure.
-- Create specific product identity through typography, scale, spacing, color roles, imagery, and copy.
-- Keep hierarchy, contrast, responsive behavior, focus states, reduced motion, and relevant empty/error/loading/success states coherent.
-- Do not fabricate metrics, customers, testimonials, certifications, prices, uptime, security, official-data access, APIs, or support capabilities. Label fictional, mock, and conceptual content close to the claim.
-- A footer-only disclaimer does not neutralize misleading claims elsewhere on the page.
-- Separate visual critique (identity, hierarchy, narrative, differentiation) from technical UI audit (accessibility, overflow, states, performance).
-- Render and inspect desktop and mobile output. Fix visible quality problems before returning `PASS`.
-
-## UI/UX references to load
-
-For landing pages, redesigns, and new product identity work, open the four frontend-quality references under `docs/references/frontend-quality/` before implementation. For smaller UI changes, load only the relevant reference. Evidence must list which references were used.
-
-## UI workflow profiles
-
-- `frontend-product`: guide public product/marketing experiences without enforcing a fixed SaaS template.
-- `frontend-utility`: guide focused tools and operational flows; commercial sections are out of scope unless requested.
-
-A visual review fails only for objective defects or an unmet explicit requirement: unloaded CSS, severe layout breakage, unusable interaction, critical contrast/accessibility failure, missing required states, or unsupported claims. Simplicity, whitespace, fewer sections, or a different style from a prior benchmark are not failures by themselves.
-
-## 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:
-- ui-ux-design
-
-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 `ui-ux-design` here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.2.0",
+  "version": "2.2.6",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -62,9 +62,13 @@
     "test:e2e": "node tests/validate-e2e.mjs",
     "pack:safe": "node internal/validate/pack-safe.mjs",
     "validate:behavioral-contracts": "node internal/validate/validate-behavioral-contracts.mjs",
+    "validate:token-economy": "node internal/validate/validate-token-economy.mjs",
+    "validate:upgrade": "node internal/validate/validate-upgrade-path.mjs",
+    "validate:visual": "node internal/validate/validate-visual.mjs",
     "validate:release-readiness": "node internal/validate/validate-release-readiness.mjs"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.8",
@@ -72,6 +76,7 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "markdownlint-cli": "^0.48.0",
+    "playwright": "^1.60.0",
     "semantic-release": "^25.0.3",
     "vitest": "^4.1.7"
   }