@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/skills/release-workflow/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: release-workflow
+description: Skill-backed capability for release workflow work
+---
+
+# Release Workflow 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.
+
+
+## Purpose
+
+Provide reusable domain guidance for `release-workflow` 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 `release workflow`.
+
+## 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:
+- release-workflow
+
+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
+
+- 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.

package/dist-assets/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: spec-driven-development
+description: Skill-backed capability for spec driven development work
+---
+
+# Spec Driven 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.
+
+
+## Purpose
+
+Provide reusable domain guidance for `spec-driven-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 `spec driven 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:
+- spec-driven-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
+
+- 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.

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

@@ -0,0 +1,166 @@
+---
+name: technical-leadership
+description: Skill-backed capability for technical leadership work
+---
+
+# 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.
+
+
+## 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
+
+- 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.

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

@@ -0,0 +1,202 @@
+---
+name: ui-ux-design
+description: Skill-backed capability for ui ux design work
+---
+
+# 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.
+
+
+## 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
+
+- 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.