@williambeto/ai-workflow 1.19.0 → 2.1.0

package/.agents/skills/build-and-validate/SKILL.md

@@ -1,442 +0,0 @@
----
-name: build-and-validate
-description: Use when running or defining project validation commands such as lint, typecheck, tests, build, formatting checks, or release readiness checks.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Build and Validate Skill
-
-## Purpose
-
-Use this skill when Codex needs to verify that a project, feature, pull request, or generated change can be built, checked, and validated safely.
-
-The goal of this skill is to provide a disciplined validation layer before a change is considered ready.
-
-This skill focuses on build commands, validation commands, test execution, error analysis, regression risk, and evidence-based reporting.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- running or planning build validation;
-- checking if a project compiles;
-- validating lint, format, typecheck, unit tests, integration tests, or E2E tests;
-- reviewing command output;
-- diagnosing failed validation commands;
-- preparing a validation report;
-- checking whether a pull request is safe to review;
-- validating generated files or build artifacts;
-- confirming that a change did not break existing behavior.
-
-## Core responsibilities
-
-When using this skill, Codex must:
-
-1. identify the project stack when possible;
-2. detect available validation commands from project files;
-3. run or recommend the smallest relevant validation set;
-4. distinguish build errors from lint, type, test, runtime, and environment errors;
-5. report exact commands and results;
-6. explain failures with evidence;
-7. avoid claiming validation success without command output or clear evidence;
-8. identify untested areas;
-9. assess regression risk;
-10. recommend the next safe action.
-
-## Validation hierarchy
-
-Use the lightest effective validation first, then escalate when needed.
-
-Recommended order:
-
-1. static file review;
-2. formatting or lint check;
-3. typecheck or compile check;
-4. unit tests;
-5. integration tests;
-6. build;
-7. E2E tests;
-8. manual validation;
-9. deployment or production-like validation.
-
-Do not run expensive validation before cheaper checks when cheaper checks are likely to catch the issue.
-
-## Command discovery
-
-Before inventing commands, inspect available project configuration when possible.
-
-Common files to check:
-
-- `package.json`
-- `pnpm-lock.yaml`
-- `package-lock.json`
-- `yarn.lock`
-- `composer.json`
-- `phpunit.xml`
-- `vite.config.*`
-- `nuxt.config.*`
-- `tsconfig.json`
-- `playwright.config.*`
-- `cypress.config.*`
-- `vitest.config.*`
-- `jest.config.*`
-- `Dockerfile`
-- `docker-compose.yml`
-- `.github/workflows/*`
-
-Prefer commands already defined by the project.
-
-Examples:
-
-```bash
-npm run lint
-npm run typecheck
-npm test
-npm run build
-```
-
-Only recommend or run generic commands when no project-specific command is available.
-
-## Package manager rule
-
-Use the package manager indicated by the project.
-
-Prefer:
-
-- `pnpm` when `pnpm-lock.yaml` exists;
-- `npm` when `package-lock.json` exists;
-- `yarn` when `yarn.lock` exists;
-- `composer` when `composer.json` exists;
-- project documentation when it explicitly defines commands.
-
-Do not switch package managers without explicit reason.
-
-## Validation scope
-
-Validation must be proportional to the change.
-
-### Documentation-only changes
-
-Recommended checks:
-
-- Markdown formatting;
-- broken code fences;
-- broken links when feasible;
-- consistency with repository structure;
-- clarity and completeness.
-
-### Frontend changes
-
-Recommended checks:
-
-- lint;
-- typecheck;
-- unit tests when available;
-- component tests when available;
-- build;
-- browser/manual validation for affected screens;
-- accessibility basics when UI changes.
-
-### Backend changes
-
-Recommended checks:
-
-- lint or static analysis when available;
-- unit tests;
-- integration tests;
-- API contract validation;
-- database migration checks when relevant;
-- security and authorization checks.
-
-### Full-stack changes
-
-Recommended checks:
-
-- frontend validation;
-- backend validation;
-- integration flow validation;
-- environment variable checks;
-- contract compatibility checks.
-
-### Deployment changes
-
-Recommended checks:
-
-- build;
-- environment configuration;
-- CI/CD workflow syntax;
-- secrets handling;
-- rollback path;
-- smoke test plan.
-
-## Failure classification
-
-When a command fails, classify the failure.
-
-### Build failure
-
-The project cannot generate the expected production or distributable output.
-
-Examples:
-
-- bundler error;
-- missing dependency;
-- compile failure;
-- invalid import;
-- broken asset pipeline.
-
-### Type failure
-
-The project has type errors or invalid type assumptions.
-
-Examples:
-
-- TypeScript error;
-- invalid interface usage;
-- unsafe null access reported by typecheck;
-- incompatible return type.
-
-### Lint failure
-
-The project violates lint rules.
-
-Examples:
-
-- unused variables;
-- forbidden imports;
-- style violations;
-- rule-specific errors.
-
-### Test failure
-
-A test command runs but one or more tests fail.
-
-Examples:
-
-- failed assertion;
-- timeout;
-- snapshot mismatch;
-- mocked dependency mismatch.
-
-### Runtime failure
-
-The code builds but fails during execution.
-
-Examples:
-
-- browser console error;
-- API request failure;
-- server exception;
-- broken navigation;
-- hydration error.
-
-### Environment failure
-
-The validation cannot complete because of missing or invalid environment setup.
-
-Examples:
-
-- missing `.env`;
-- missing service;
-- missing database;
-- unavailable API;
-- invalid credentials;
-- unsupported local runtime.
-
-## Evidence rules
-
-Every validation report must include evidence.
-
-Evidence can be:
-
-- command executed;
-- command exit status;
-- relevant error excerpt;
-- file path;
-- line number when available;
-- screenshot or manual observation when relevant;
-- test name;
-- CI result;
-- build output summary.
-
-Do not fabricate command results.
-
-If a command was not executed, state that clearly.
-
-## Output format
-
-When using this skill, Codex should respond using this structure:
-
-```md
-# Build and Validation Report
-
-## Summary
-
-Short conclusion about the validation result.
-
-## Scope
-
-- Files or areas validated.
-- Change or PR being checked.
-
-## Environment
-
-- Runtime:
-- Package manager:
-- Relevant framework:
-- Notes:
-
-## Commands executed
-
-| Command   | Result                    | Notes      |
-| --------- | ------------------------- | ---------- |
-| `command` | Passed / Failed / Not run | Short note |
-
-## Findings
-
-### Finding 1
-
-Severity: High | Medium | Low
-Type: Build failure | Type failure | Lint failure | Test failure | Runtime failure | Environment failure | Observation | Hypothesis
-
-Description:
-Explain the issue clearly.
-
-Evidence:
-Show the exact evidence.
-
-Impact:
-Explain why it matters.
-
-Recommended action:
-Explain the smallest safe next step.
-
-How to validate after fix:
-Explain the command or manual check.
-
-## Untested areas
-
-- Area not validated — reason.
-
-## Regression risks
-
-- Risk 1
-- Risk 2
-
-## Final recommendation
-
-Approved | Approved with notes | Changes requested | Blocked
-```
-
-## Severity model
-
-### High
-
-Use `High` when validation shows or strongly indicates:
-
-- build failure;
-- failing required tests;
-- broken critical flow;
-- security risk;
-- deployment-blocking issue;
-- data loss risk;
-- severe regression.
-
-### Medium
-
-Use `Medium` when validation shows or suggests:
-
-- missing validation for important behavior;
-- partial test failure in non-critical flow;
-- type or lint issues that do not block runtime but reduce safety;
-- fragile configuration;
-- environment-specific risk;
-- unclear build assumptions.
-
-### Low
-
-Use `Low` when validation shows:
-
-- minor warning;
-- non-blocking cleanup;
-- small documentation gap;
-- minor formatting issue;
-- low-risk command or configuration improvement.
-
-## Approval criteria
-
-A change can be approved when:
-
-- relevant commands were identified;
-- appropriate validation was executed or explicitly marked as not executed;
-- no high-severity issue remains;
-- failures are understood or documented;
-- regression risks are acceptable;
-- untested areas are visible;
-- the final recommendation is clear.
-
-Use `Approved` when all relevant checks pass.
-
-Use `Approved with notes` when the change is acceptable but has low-risk gaps or non-blocking warnings.
-
-Use `Changes requested` when there are fixable failures or medium/high issues.
-
-Use `Blocked` when validation cannot continue because of missing environment, missing dependencies, missing context, or unavailable required services.
-
-## Boundaries
-
-When using this skill, Codex must not:
-
-- invent command results;
-- claim that tests passed without evidence;
-- switch package managers unnecessarily;
-- run destructive commands without explicit permission;
-- delete files to make validation pass;
-- ignore failing commands;
-- treat environment failures as code failures without evidence;
-- treat hypotheses as confirmed issues;
-- expand validation scope beyond what is useful;
-- approve deployment when build validation failed.
-
-## Destructive command rule
-
-Do not run destructive or irreversible commands unless explicitly instructed.
-
-Examples of commands that require explicit permission:
-
-```bash
-rm -rf
-git reset --hard
-git clean -fd
-docker system prune
-dropdb
-php artisan migrate:fresh
-npm publish
-pnpm publish
-composer update
-```
-
-If cleanup is needed, recommend a safe command first and explain the risk.
-
-## Good validation behavior
-
-Good validation is:
-
-- proportional;
-- evidence-based;
-- repeatable;
-- explicit about failures;
-- explicit about untested areas;
-- aligned with project scripts;
-- focused on regression prevention;
-- practical enough to be used repeatedly.
-
-The goal is not to run every possible command.
-
-The goal is to run the right checks for the risk of the change.
-
-## Stop conditions
-
-- Stop when validation evidence is complete and the final recommendation is clear.
-- Stop and report `Blocked` if required environment, dependencies, or context is missing.