@williambeto/ai-workflow 1.19.1 → 2.2.0

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

@@ -0,0 +1,171 @@
+---
+name: documentation
+description: Skill-backed capability for documentation work
+---
+
+# Documentation 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 `documentation` 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 `documentation`.
+
+## 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.
+
+
+
+## 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:
+- documentation
+
+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/frontend-development/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: frontend-development
+description: Skill-backed capability for frontend development work
+---
+
+# Frontend 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 `frontend-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 `frontend 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.
+
+
+
+## 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.
+
+
+
+
+## Frontend behavioral quality baseline
+
+For new React, Vue, Angular, or comparable frontend applications:
+
+- Default to TypeScript unless the user explicitly requests JavaScript or the existing project is JavaScript-only.
+- Define the product audience, primary task, main promise, and primary action before composing the page.
+- Use a small explicit design system: color roles, typography roles, spacing rhythm, control states, and responsive breakpoints.
+- Deliver a deliberate composition appropriate to the selected workflow profile. Simplicity is acceptable; raw scaffolds, unloaded CSS, or unusable primary flows are not.
+- Implement only states that correspond to real behavior; do not add artificial loading to synchronous local logic.
+- Distinguish real, mock, hybrid, and conceptual data visibly. Never present mock results as a real external lookup.
+- Validate identifiers, dates, currency, status, API mappings, and domain labels against the actual data contract.
+- Provide a useful `README.md` for a new runnable app. Create or update `DESIGN.md` only when reusable visual decisions are established.
+- Run tests, build, and typecheck. Inspect rendered desktop and mobile output before completion.
+- Reject unsupported metrics, testimonials, prices, SLAs, security claims, official-data claims, or integrations unless they are clearly framed as conceptual/fictitious according to the truthfulness policy.
+
+## Frontend workflow profiles
+
+- `frontend-product`: product and marketing surfaces. Focus on audience, promise, primary action, truthful copy, responsive render, and accessibility. Do not impose pricing, testimonials, a fixed section count, or a complex hero.
+- `frontend-utility`: search, validation, forms, dashboards, calculators, and focused tools. Focus on the primary flow and applicable operational states. Do not add marketing sections or artificial loading.
+
+Quality review must use observable checks. Do not label work “modern”, “premium”, or “polished” as evidence. Record CSS loaded, desktop render, mobile render, primary interaction, UI states, and critical render failures.
+
+## Frontend references to load selectively
+
+For landing pages, redesigns, or visually important frontend work, load:
+
+- `docs/references/frontend-quality/landing-page-quality-checklist.md`
+- `docs/references/frontend-quality/product-copy-truthfulness.md`
+- `docs/references/frontend-quality/visual-composition-patterns.md`
+- `docs/references/frontend-quality/quality-failure-examples.md`
+
+For a small bug fix, load only the references relevant to the changed surface. Record loaded references in the delivery evidence.
+
+## Test setup defaults for implementation
+
+When implementing a frontend feature or app:
+
+- New frontend projects default to TypeScript.
+- Existing JavaScript projects preserve their current language unless migration is explicitly requested and planned.
+- TypeScript implementations require a working typecheck command and passing typecheck evidence.
+
+When implementing a JS/TS frontend feature or app:
+
+1. Inspect existing scripts and configs.
+2. If no test setup exists and the task creates/controls the frontend project, add a minimal test setup.
+3. Add tests for the most deterministic logic first: formatters, validators, data mappers, fetch/API wrappers with mocked fetch, counters, and recursive render helpers.
+4. Add component tests only when useful and not over-scoped.
+5. Run build and tests.
+6. If tests are viable but missing, report `FAIL_QUALITY_GATE`.
+
+Do not finish with `Tests: NOT_RUN` merely because the baseline had no test framework.
+
+
+## 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:
+- frontend-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/full-stack-development/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: full-stack-development
+description: Skill-backed capability for full stack development work
+---
+
+# Full Stack 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 `full-stack-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 `full stack 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:
+- full-stack-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.