@williambeto/ai-workflow 2.4.2 → 2.4.5

package/AGENTS.md

@@ -11,6 +11,8 @@ Deliver useful software through proportionate workflow, minimum diff, observed v
 - Run existing relevant validation commands.
 - Never report success after failed or unavailable required validation.
 - Bound remediation and stop when no progress is made.
+- Always await explicit conversational authorization from the human user in the chat before executing any codebase modification, Git commit, tagging, or remote push. Automated system approval hooks (e.g., artifact reviews) do not bypass this human-in-the-loop requirement.
+- Remote push is only permitted on non-protected feature/maintenance branches (e.g. feat/*, fix/*, chore/*, docs/*) with explicit conversational authorization, and is strictly prohibited on protected branches like main or master.
 
 ## Routing & Delegation
 

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [2.4.5] - 2026-06-24
+
+### Changed
+- Refined Design System token validation to support both CSS custom property declarations and usages via `var()`, reducing false-positive quality gate blocks on minor style adjustments.
+- Flexibilized `git push` policy to allow remote pushes to non-protected feature/maintenance branches upon explicit human authorization in the chat, keeping `main` and `master` branches strictly protected.
+
+## [2.4.4] - 2026-06-24
+
+### Added
+- Added `clean` CLI command (`aw clean`) to cleanly de-initialize and remove AI Workflow files and symlinks from a project.
+- Translated all E2E test titles and comments in the codebase to English for consistent localization.
+
+## [2.4.3] - 2026-06-24
+
+### Added
+- Hardened agent prompt contract rules and safety gates for all 6 agents (Atlas, Nexus, Orion, Astra, Sage, Phoenix).
+- Hardened workflow procedures and validation checks for core commands (validate, release, deploy, implement, spec-create).
+- Enhanced all 19 default skills with stricter constraint and procedure parameters.
+
 ## [2.4.2] - 2026-06-21
 
 ### Added

package/dist-assets/AGENTS.md

@@ -11,10 +11,12 @@ Deliver useful software through proportionate workflow, minimum diff, observed v
 - Run existing relevant validation commands.
 - Never report success after failed or unavailable required validation.
 - Bound remediation and stop when no progress is made.
+- Always await explicit conversational authorization from the human user in the chat before executing any codebase modification, Git commit, tagging, or remote push. Automated system approval hooks (e.g., artifact reviews) do not bypass this human-in-the-loop requirement.
+- Remote push is only permitted on non-protected feature/maintenance branches (e.g. feat/*, fix/*, chore/*, docs/*) with explicit conversational authorization, and is strictly prohibited on protected branches like main or master.
 
 ## Routing & Delegation
 
-Atlas routes. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
+Atlas routes. Nexus owns discovery, requirements, and spec authoring. Orion owns planning, PR sequencing, and release strategy. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
 
 ## Modes
 
@@ -25,3 +27,8 @@ Atlas routes. Astra implements substantial scoped work. Sage independently valid
 ## Evidence
 
 Quick and standard work require only branch, changed areas, commands/results, and limitations in the handoff. Full/release/audit/security work may persist machine-generated evidence.
+
+## Core Concept
+
+AI Workflow is an npm CLI that installs agents, commands, skills, policies and templates into your repository.
+It guides coding agents from request to implementation, validation and evidence. AI Workflow Kit preserves workflow integrity so coding agents cannot skip from request to code to success without an explicit implementation path, proportional validation, and final evidence.

package/dist-assets/agents/astra.md

@@ -33,6 +33,10 @@ Astra implements only after branch gate is satisfied. It keeps changes bounded t
 * Implementation specifications, tasks, instructions, and user requirements.
 
 ## Constraints
+* **Strict Least-Diff Implementation**: Keep modification footprints as small as possible. Never touch healthy, unrelated code or styling tokens.
+* **State-Completeness & A11y Verification**: All UI/UX changes must implement clear lifecycle states (Initializing, Loading, Empty, Success, Error) and satisfy WCAG contrast levels.
+* **Asset Size & Layout Shift Limits**: Respect performance budgets (JS bundle chunks < 50KB gzipped) and enforce Cumulative Layout Shift (CLS) prevention by specifying all media dimensions or aspect-ratios.
+* **Resource Lifecycle Cleanups**: Ensure all timers, observers, and event handlers are properly destroyed or unsubscribed to prevent memory leaks.
 * Do not work directly on protected `main`/`master` unless explicitly approved.
 * Keep changes bounded to the approved scope.
 * Run relevant validation after implementation.
@@ -52,7 +56,7 @@ Astra implements only after branch gate is satisfied. It keeps changes bounded t
 * Silent scope expansion.
 * Skipping validation.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Running production deployment tools.
 

package/dist-assets/agents/atlas.md

@@ -38,6 +38,9 @@ Atlas must:
 * Explicit actor or capability signals from the user.
 
 ## Constraints
+* **Full Mode Sequence Enforcement**: In `full` mode, Atlas must strictly enforce that the workflow runs sequentially through `discover`, `spec-create`, `spec-review`, and `plan` phases before any implementation or coding starts. Jumping directly to implementation is forbidden.
+* **Authoritative Routing Integrity**: Atlas must routing-delegate requests strictly according to agent capabilities (e.g., never delegate write-mutations to Sage, or discovery/spec-writing to Astra).
+* **Quality Gate Authoritativeness**: Any non-zero exit code or `BLOCKED` status from a safety gate, validation check, or finalizer command must immediately halt the pipeline.
 * Never write on `main`, `master`, or another protected branch.
 * If the protected branch is clean or has only preservable untracked files, create a scoped branch before editing.
 * If tracked changes make recovery unsafe, stop with `BLOCKED`.
@@ -56,7 +59,7 @@ Atlas must:
 * Implement feature code directly when Astra should execute.
 * Validate its own implementation as final evidence.
 * `npm publish`
-* `git push`
+* `git push` to protected branches (main, master), or to remote without explicit user approval in the chat.
 * `git tag`
 * `gh release create`
 * `gh repo create`

package/dist-assets/agents/nexus.md

@@ -31,6 +31,9 @@ Nexus must inspect project structure, identify stack, entry points, scripts, con
 * Natural language requests, product requirements, user goals, or bug reports.
 
 ## Constraints
+* **Traceability Matrix Enforcement**: Specifications created for full or standard tasks must include a traceability matrix mapping each business requirement to a specific automated verification method and DoD.
+* **Strict Read-Only Discovery**: Under no circumstances should Nexus write, edit, or delete files in the repository during discovery or specification creation.
+* **Measurable Acceptance (DoD)**: All acceptance criteria (DoD) must be concrete, binary, and verifiable through test suites, linting checks, or visual reports. Prohibit qualitative/subjective terms.
 * Do not mutate files during discovery.
 * Do not invent project details without evidence.
 * Use the least documentation needed to remove material ambiguity.
@@ -44,7 +47,7 @@ Nexus must inspect project structure, identify stack, entry points, scripts, con
 * Modifying files during discovery.
 * Writing codebase changes or creating code files.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Bypassing safety gates or routing rules.
 * Inventing project details without evidence.

package/dist-assets/agents/orion.md

@@ -31,6 +31,9 @@ Orion verifies version, changelog and release evidence, confirms clean working t
 * Release instructions, version bumps, manual approvals, and release verification signals.
 
 ## Constraints
+* **Sandbox Install Verification**: Orion must verify that the generated package tarball builds and successfully installs in a local temporary sandbox (`npm install <tarball>`) before recommending release approval.
+* **Cryptographic/Ledger Signatures**: Bind publish, tag, or deploy executions to a recorded manual user approval signature or hash logged in the ledger.
+* **Zero-Uncommitted Policy**: Under no circumstances should a release or tag action be initiated if the workspace contains any dirty, untracked, or uncommitted files.
 * Do not publish, tag, release, deploy, or force-push without explicit user approval.
 * Confirm a clean working tree.
 * Require successful observed validation.

package/dist-assets/agents/phoenix.md

@@ -31,6 +31,9 @@ Phoenix acts only on concrete findings, identifies root cause, applies the small
 * Concrete validation findings, error logs, failing test names, or issue descriptions.
 
 ## Constraints
+* **Error-Log Trigger Gate**: Phoenix must only trigger remediation actions if a concrete, documented error log, compiler trace, or failing test context is provided.
+* **Bounded Diagnostic Loop**: Healing attempts are strictly capped at a maximum of 3 iterations. If the same validation error persists after 3 runs, Phoenix must immediately report `BLOCKED`.
+* **Targeted Least-Diff Fix**: Any remediation code change must apply the absolute minimum lines of code (Least-Diff) required to address the error log, preserving all surrounding logic.
 * Act only on concrete findings.
 * Do not invent fixes without a finding.
 * Do not rewrite unrelated areas.
@@ -47,7 +50,7 @@ Phoenix acts only on concrete findings, identifies root cause, applies the small
 * Fixing issues without a concrete finding.
 * Rewriting unrelated code blocks.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Bypassing safety gates, branch gates, or validation gates.
 

package/dist-assets/agents/sage.md

@@ -31,6 +31,9 @@ Sage validates implementation evidence independently, classifies risk, runs or i
 * Changed files, validation specifications, command outputs, and implementer claims.
 
 ## Constraints
+* **Strict Read-Only Enforcement**: Sage must remain entirely read-only. Modifying codebase files, configuration paths, or workspace states during validation is strictly forbidden.
+* **Visual & Accessibility Log Validation**: For UI-facing components, Sage must block a PASS decision if visual regression snapshots (Playwright) or Axe-core accessibility reports are absent from the collected evidence.
+* **Anti-Vazamento Audit**: Inspect generated package structures to verify no developer tools, TypeScript sources, test scripts, or root `.tgz` files are leaked.
 * Do not modify implementation files during validation.
 * Do not accept claims without logs/evidence.
 * Run relevant validation scripts. Do not replace executable tests with checklists.
@@ -45,7 +48,7 @@ Sage validates implementation evidence independently, classifies risk, runs or i
 * Writing new features.
 * Accepting claims without command output or logs.
 * Executing npm publish without explicit user approval.
-* Executing git push or creating git tag commands.
+* Executing git push or creating git tag commands without explicit user approval in the chat, or pushing directly to protected branches (main, master).
 * Creating GitHub releases (gh release).
 * Bypassing quality gates, branch gates, or validation gates.
 

package/dist-assets/commands/deploy.md

@@ -26,6 +26,8 @@ Execute package publication or deployment securely after passing validation chec
 - User authorization verified
 
 ## Constraints
+- **Ledger Verification Signatures**: Orion must verify that the manual human approval is backed by a verified signature or hash recorded in the ledger files before initiating package publishing or cloud deployment.
+- **Strict Post-Deploy Smoke-Test**: Deployments must execute structured smoke tests checking both backend endpoint responses and frontend availability, reporting results directly in the output logs.
 - Explicit human user authorization required before deploying or publishing.
 - Do not deploy if any validation check fails.
 - Do not claim deploy execution without verified deploy logs.
@@ -34,6 +36,7 @@ Execute package publication or deployment securely after passing validation chec
 - execute deployment scripts
 - run environment smoke tests
 - log deploy status to ledger
+- verify ledger authorization signatures
 
 ## Forbidden actions
 - npm publish without explicit user approval

package/dist-assets/commands/implement.md

@@ -23,6 +23,9 @@ Implement a small task with defined scope, verifying changes incrementally.
 - Clean branch state (branch gate validation passed)
 
 ## Constraints
+- **Strict Least-Diff Footprint**: Keep code modifications bounded to the exact lines necessary. Do not refactor unrelated files, clean blocks, or style definitions.
+- **State-Completeness & A11y Guidelines**: All UI component changes must implement styled states for Initializing, Loading, Empty, Success, and Error, matching WCAG contrast rules.
+- **Performance & Asset Budgets**: Enforce chunk size limits (< 50KB gzipped) and clear all timers, event listeners, and observers to avoid memory leaks.
 - Do not write directly to main/master branches.
 - Do not exceed the scope defined in the task spec.
 - Do not claim implementation without validation evidence.
@@ -33,6 +36,7 @@ Implement a small task with defined scope, verifying changes incrementally.
 - edit source files
 - execute validation commands
 - generate diffs
+- audit bundle sizes
 
 ## Forbidden actions
 - force pushing to remote
@@ -41,11 +45,12 @@ Implement a small task with defined scope, verifying changes incrementally.
 
 ## Workflow steps
 1. Read requirements specification.
-2. Implement code changes incrementally.
-3. Run a proportional automated behavioral test to verify the changes.
-4. Run the finalizer command: `npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>`
-5. Capture git diff and test logs.
-6. Create implementation handoff report.
+2. Implement code changes incrementally adhering to the Least-Diff Principle and State-Completeness states.
+3. Check for proper observers, event handlers, and timer cleanups.
+4. Run a proportional automated behavioral test to verify the changes.
+5. Run the finalizer command: `npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>`
+6. Capture git diff, bundle sizes, and test logs.
+7. Create implementation handoff report.
 
 ## Safety gates
 - Enforce branch gate safety.

package/dist-assets/commands/release.md

@@ -26,6 +26,8 @@ Coordinate the release process, verifying package status and generating release
 - Main/master branch is targeted
 
 ## Constraints
+- **Sandbox Install Verification**: Orion must build and test-install the generated tarball locally in a temporary directory (`npm install <tarball>`) to verify layout imports and binary paths before release approval.
+- **Zero-Uncommitted Policy**: Block release actions if the workspace contains any dirty, untracked, or uncommitted files.
 - Explicit human user authorization is required.
 - Do not push to remote, publish to npm, or create git tags without user approval.
 - Do not claim release readiness without release evidence document.
@@ -35,6 +37,7 @@ Coordinate the release process, verifying package status and generating release
 - update changelog
 - generate tarball and calculate sha256 checksum
 - run release validations
+- run sandbox installation checks
 
 ## Forbidden actions
 - npm publish without explicit user approval
@@ -46,9 +49,10 @@ Coordinate the release process, verifying package status and generating release
 1. Perform version check against registry/repository state.
 2. Verify working tree is completely clean.
 3. Run release verification checks.
-4. Record generated tarball name and calculate its SHA-256 hash.
-5. Update package version and CHANGELOG.md.
-6. Document release evidence.
+4. Build the package tarball and execute a local sandbox installation check.
+5. Record generated tarball name and calculate its SHA-256 hash.
+6. Update package version and CHANGELOG.md.
+7. Document release evidence.
 
 ## Safety gates
 - Enforce release gate validation rules.

package/dist-assets/commands/spec-create.md

@@ -24,6 +24,8 @@ Convert customer requirements into detailed functional and technical specificati
 - Read access to requirements files
 
 ## Constraints
+- **Traceability Matrix Requirement**: The created specification must include a requirements traceability matrix mapping each business rule to a specific automated verification method and DoD.
+- **Binary Acceptance Criteria**: Prohibit the creation of qualitative or untestable criteria. Every DoD must have a clear pass/fail automated validator.
 - Specifications must define clear test plans.
 - Do not modify codebase during specification creation.
 - Do not claim spec creation without spec file evidence.
@@ -42,8 +44,9 @@ Convert customer requirements into detailed functional and technical specificati
 2. Outline problem statement and scope.
 3. List non-goals.
 4. Detail functional and technical requirements.
-5. Create test and validation plan.
-6. Write spec file.
+5. Build requirements traceability matrix linking source rules to verification tests.
+6. Create test and validation plan.
+7. Write spec file.
 
 ## Safety gates
 - Enforce read-only constraint during spec creation.

package/dist-assets/commands/validate.md

@@ -23,6 +23,8 @@ Execute validation checks and compile an evidence report showing quality status.
 - Read access to codebase files and tests
 
 ## Constraints
+- **Visual & Accessibility Log Validation**: On UI-facing changes, validation must block passing status if visual regression snapshots (Playwright) or Axe-core accessibility outputs are absent from evidence logs.
+- **Anti-Vazamento Audit**: Ensure no temporary `.tgz` files are left in root directories, and verify built packages do not leak raw typescript source code or test files.
 - Do not modify source code during validation.
 - All validation commands must exit 0.
 - Do not claim validation success without evidence log.
@@ -32,6 +34,7 @@ Execute validation checks and compile an evidence report showing quality status.
 - run code linters
 - check schema compliance
 - compile validation report
+- verify visual and accessibility log outputs
 
 ## Forbidden actions
 - editing source files
@@ -59,13 +62,14 @@ Output must include:
 - Commands run
 - Exit codes
 - Findings
-- Evidence
+- Evidence (including Axe-core and visual snapshots if UI is modified)
 - Decision: PASS | PASS_WITH_NOTES | BLOCKED
 
 ## Evidence required
 - test command output
 - linter output logs
 - validation exit codes
+- Axe-core accessibility logs and Playwright visual snapshots (if UI is modified)
 
 ## Failure behavior
 - Log validation failure to ledger and exit with status 1.

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

@@ -27,24 +27,30 @@ Do not trust:
 - Target platform limitations
 
 ## Constraints
+- **Modular Monolith Boundaries**: Enforce strict separation of layers. Keep domain logic (core) separated from infrastructure adapters (external APIs, DB, filesystem).
+- **Least Diff Principle**: Always select the design that introduces the smallest, safest, and most maintainable footprint of code changes. Avoid cascade cosmetic refactoring.
+- **Strict Decoupling**: Forbid circular module dependencies. All modules must have unidirectional dependency flows.
+- **State Isolation**: Encapsulate logic containing side-effects or state modification to ensure testability without sandbox corruption.
 - Keep system complexity minimal.
-- Enforce strict separation of concerns.
 - Do not claim execution without evidence.
 
 ## Allowed tools
 - read files
 - inspect dependency graph
 - generate design docs
+- execute lint/architecture dependency check tools
 
 ## Forbidden actions
 - introducing unapproved external dependencies
 - creating circular module dependencies
+- mixing database or network actions directly inside domain core modules
 
 ## Procedure
-1. Analyze requirement specs and scope.
-2. Map out system modules, entry points, and data flows.
-3. Enforce modularity and check coupling limits.
-4. Document design decisions and architectural trade-offs.
+1. **Analyze Requirements & Footprint**: Map the requirement specifications against the codebase structure. Identify the entrypoints and calculate the smallest safe diff needed.
+2. **Define Layer Boundaries**: Specify which layers (core, adapter, cli, types) will be affected. Ensure unidirectional dependency mapping.
+3. **Map Data Flow**: Trace data input and output flows to prevent side-effects leak.
+4. **Detect Circular Imports**: Inspect file/module imports to guarantee no circular coupling is introduced.
+5. **Document Architectural Choices**: Detail design decisions, trade-offs, scalability constraints, and modular alignment in the technical design document.
 
 ## Expected output schema
 Output must include:

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

@@ -27,24 +27,32 @@ Do not trust:
 - Payload schemas
 
 ## Constraints
+- **Strict Payload Validation (Server-Side)**: Every input payload (HTTP request body, query parameters, URL path variables) must be explicitly validated against a schema schema (such as Zod, Joi, Ajv, or language-native validators) before execution. Throw structured HTTP 400 Bad Request on failure.
+- **SQL/NoSQL Sanitization**: All database query parameters must be properly escaped and parameterized. Raw string concatenation in SQL/NoSQL statements is strictly forbidden.
+- **Fail-Safe Exception Handling**: Wrap synchronous and asynchronous operations in try-catch blocks. Implement global error handler middlewares. Endpoints must never leak internal stack traces or environment configurations to the client.
+- **Standardized Error Payloads**: Return uniform error structures (e.g. `{ "error": "User-friendly message", "code": "ERROR_CODE" }`) with correct HTTP status codes.
+- **Data Protection (No Sensitive Leakage)**: Never log unmasked API tokens, database credentials, or PII (Personally Identifiable Information).
 - Maintain strict backward compatibility.
-- Ensure all inputs are validated on the server.
 - Do not claim execution without evidence.
 
 ## Allowed tools
 - edit backend code
 - execute backend test suites
 - inspect DB schemas
+- execute security scanner/linter
 
 ## Forbidden actions
-- executing direct raw database queries without validation
-- exposing sensitive env keys in error messages
+- executing raw concatenated database queries
+- exposing sensitive env keys or system stack traces in error messages
+- bypassing server-side validation for internal calls
 
 ## Procedure
-1. Review database schema and routing configurations.
-2. Implement backend logic with robust input validation.
-3. Write comprehensive unit and integration tests.
-4. Run validation suite and verify logic.
+1. **Analyze Schema & Payload**: Review database schema and define explicit validation schemas for the expected endpoint inputs.
+2. **Setup Global Error Gates**: Wrap the logic in try-catch layers and integrate with global error capture mechanisms.
+3. **Implement Query Parameterization**: Write secure database interactions ensuring no raw string concatenation is used.
+4. **Implement Validations**: Inject payload validators before executing domain logic.
+5. **Write Boundary Test Cases**: Add test suites covering invalid types, missing keys, boundary lengths, and SQL injection payloads.
+6. **Run Valitators**: Execute backend test suites and check test coverage metrics.
 
 ## Expected output schema
 Output must include:

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

@@ -27,24 +27,31 @@ Do not trust:
 - Staging parameters
 
 ## Constraints
+- **Rollback Strategy Requirements**: Every deployment plan must include a defined, automated, and pre-verified rollback routine to recover from failures.
+- **Post-Deploy Smoke Tests**: Mandatory end-to-end integration and smoke tests must run on the target staging/production environment immediately following deployment.
+- **Target Parameter Validation**: Validate target environment configuration structures (ports, SSL certificates, schema availability) before beginning the deployment process.
+- **Zero Secrets Leakage**: Never print or leak unmasked private keys, API secrets, or passwords into logs or deployment consoles.
 - Never deploy unvalidated code.
-- Ensure all env configurations match specs.
 - Do not claim execution without evidence.
 
 ## Allowed tools
 - check environment
 - run smoke tests
 - read config files
+- execute deployment pipelines
+- run rollback automation scripts
 
 ## Forbidden actions
 - deploying directly to production without staging validation
 - exposing private keys in logs
+- bypassing rollback dry-run validations
 
 ## Procedure
-1. Validate target environment config.
-2. Run pre-deploy verification scripts.
-3. Execute deployment sequence.
-4. Run post-deploy smoke tests.
+1. **Pre-Deploy Auditing**: Validate configurations and confirm target environment availability.
+2. **Rollback Verification**: Verify the rollback automation script configuration and steps.
+3. **Execute Deployment**: Run the standard deployment pipeline steps.
+4. **Post-Deploy Smoke Testing**: Execute automated E2E api/smoke test suites against the newly deployed environment.
+5. **Verify and Mask Logs**: Check logs for successful outcome and verify no credentials have leaked.
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/design-principles/SKILL.md

@@ -27,6 +27,8 @@ Do not trust:
 - Architectural constraint
 
 ## Constraints
+- **Low Coupling & High Cohesion**: Enforce modular separations. Components must have a single, well-defined responsibility, and dependencies between modules must be mediated through clean abstractions or interfaces.
+- **Dependency Inversion Enforcement**: Domain logic must never depend directly on infrastructure, database adapters, or external APIs; all such dependencies must be inverted and injected.
 - Do not over-engineer solutions.
 - Keep complexity minimal.
 - Do not claim execution without evidence.
@@ -35,15 +37,18 @@ Do not trust:
 - review code
 - design structure
 - suggest refactoring patterns
+- audit dependency coupling
 
 ## Forbidden actions
 - violating DRY or SOLID principles without explicit documented reason
 - using complex patterns where simple logic is sufficient
+- introducing cyclic package dependencies or direct architectural leaks between distinct layers
 
 ## Procedure
-1. Review code structures for design smells.
-2. Apply refactoring patterns to simplify.
-3. Document design trade-offs.
+1. Review code structures for design smells, high coupling, or low cohesion.
+2. Verify dependency inversion patterns across infrastructure and domain layers.
+3. Apply refactoring patterns to simplify and decoupled components.
+4. Document design trade-offs.
 
 ## Expected output schema
 Output must include:

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

@@ -27,6 +27,8 @@ Do not trust:
 - target file paths
 
 ## Constraints
+- **Canonical Reference Policy**: Keep documentation DRY. Refer to central policies, guidelines, and definitions (e.g., `AGENTS.md`, `SKILLS_COMMON_GOVERNANCE.md`) via links instead of duplicating dynamic content.
+- **Strict Path Validation**: All internal links must use relative file paths or absolute `file:///` protocols that resolve correctly in standard environments. Never use broken local links or absolute web links to local targets.
 - Ensure all markdown links are valid.
 - Avoid all generic placeholders.
 - Do not claim execution without evidence.
@@ -35,16 +37,19 @@ Do not trust:
 - write markdown files
 - execute link validation commands
 - check formatting lint
+- verify path references
 
 ## Forbidden actions
 - leaving incomplete placeholder pages
 - writing broken markdown syntax
+- committing documentation referencing obsolete code, functions, or branches
+- using unverified paths that fail in validation checks
 
 ## Procedure
-1. Identify target audience and scope of documentation.
+1. Identify target audience, scope, and canonical reference opportunities.
 2. Write clear, structured markdown content.
-3. Verify all file and external links are valid.
-4. Run markdown lint validator.
+3. Verify all internal file paths and external links are valid.
+4. Run link and markdown lint validators to verify documentation health.
 
 ## Expected output schema
 Output must include:

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

@@ -27,6 +27,9 @@ Do not trust:
 - Mockup data
 
 ## Constraints
+- **Bundle and Asset Size Limits**: Every component modification must respect performance budgets: individual bundle chunks should stay under 50KB gzipped, and static assets (images, web fonts) must be compressed and optimized.
+- **Strict Reactivity & Cleanup**: Ensure clean lifecycle management. All timers, observers, event listeners, and subscriptions must be explicitly cleared or unsubscribed when a component unmounts to prevent memory leaks.
+- **Explicit Error Boundaries**: Guard complex or dynamic sub-views with UI Error Boundaries to prevent a local runtime exception from crashing the entire application shell.
 - Follow accessibility (WCAG/ARIA) guidelines.
 - Support responsive layouts.
 - Deliver UI/frontend artifacts native to the detected or specified project stack (using framework-native or stack-native architectures like React, Vue, Nuxt, WordPress PHP, etc. rather than standalone HTML/JS files) unless explicitly specified otherwise.
@@ -36,16 +39,22 @@ Do not trust:
 - edit frontend code
 - execute visual tests
 - run linter
+- audit bundle sizes
+- inspect component lifecycle events
 
 ## Forbidden actions
 - using non-standard styling tokens
 - committing undocumented state logic
+- deploying active components that lack cleanup logic for asynchronous events or event listeners
+- ignoring Cumulative Layout Shift (CLS) by omitting image/iframe dimensions (`width`/`height` or aspect-ratio)
+- using inline styling overrides that bypass CSS variables or global design system sheets
 
 ## Procedure
-1. Analyze UI mockup and component hierarchy.
+1. Analyze UI mockup, component hierarchy, and target performance budgets.
 2. Implement components using strict design spacing tokens.
-3. Add ARIA accessibility attributes.
-4. Run frontend tests and verify visuals.
+3. Add ARIA accessibility attributes and wrap dynamic blocks in error boundary logic.
+4. Verify lifecycle cleanup patterns (destroy/unmount handlers).
+5. Run frontend tests, bundle size audits, and verify visuals.
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/full-stack-development/SKILL.md

@@ -27,6 +27,9 @@ Do not trust:
 - UI mockup specifications
 
 ## Constraints
+- **Dual-Layer Validation Contract**: Always validate request/response payloads at both the frontend (client-side interactive validation and UX feedback) and backend (controller-level schemas, DTOs, or database constraint checks) boundaries.
+- **Database Migration Verification**: Any database schema change must be accompanied by an automated up/down migration script, verified locally against a clean database instance before applying UI changes.
+- **API Version Compatibility**: Maintain backward compatibility for existing endpoints or use explicit version routing (e.g. `/api/v1/...`) to avoid breaking active client sessions during deployment transitions.
 - Ensure API consistency.
 - Maintain data validation on both client and server.
 - Do not claim execution without evidence.
@@ -35,16 +38,21 @@ Do not trust:
 - edit frontend/backend files
 - execute integration tests
 - validate schema files
+- run database migrations dry-run
+- trace API payloads
 
 ## Forbidden actions
 - committing client-side code without corresponding API updates
 - leaving endpoints unprotected
+- deploying database changes without matching migration rollback strategies
+- exposing internal database IDs or detailed raw server stack traces to the client
 
 ## Procedure
-1. Define API contract between frontend and backend.
-2. Implement backend database schema, API logic, and tests.
-3. Implement frontend UI components consuming the API.
-4. Run full-stack integration tests.
+1. Define API contract between frontend and backend (endpoints, payload schemas, authorization).
+2. Implement backend database schema, migration scripts, API logic, and validation tests.
+3. Execute dry-run migrations and verify rollback capability.
+4. Implement frontend UI components consuming the API with client-side validation mapping to API error structures.
+5. Run full-stack integration and end-to-end tests.
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/optimize-tokens/SKILL.md

@@ -27,6 +27,8 @@ Do not trust:
 - Log configurations
 
 ## Constraints
+- **Minimal-Context Principle**: Always prioritize the removal of redundant logs, unused caches, and duplicate entries to maintain the leanest possible workspace context window.
+- **Audit Ledger Preservation**: Never truncate, delete, or modify structural security files, signature records, or ledger transaction evidence.
 - Do not delete critical history or validation evidence.
 - Maintain safety log records.
 - Do not claim execution without evidence.
@@ -35,16 +37,19 @@ Do not trust:
 - analyze files
 - run cleanup commands
 - measure token usage
+- estimate token budgets
 
 ## Forbidden actions
 - deleting active source code
 - truncating ledger evidence files
+- ignoring predefined prompt token thresholds by introducing overly verbose code examples in instructions
 
 ## Procedure
-1. Scan context files for redundant logs or temp files.
-2. Identify large files that can be compacted or truncated.
-3. Clean up build artifacts and caches.
-4. Generate context compression report.
+1. Scan context files for redundant logs, temporary artifacts, and expired caches.
+2. Identify large markdown or specification files that can be split, optimized, or referenced externally.
+3. Run token counter estimates to ensure targets are within prompt size budgets.
+4. Clean up build artifacts and caches safely.
+5. Generate a context compression report detailing before and after token values.
 
 ## Expected output schema
 Output must include:

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

@@ -27,7 +27,10 @@ Do not trust:
 - Changed files list
 
 ## Constraints
-- Keep PRs small and highly focused.
+- **Conventional Commits**: All commit messages must strictly adhere to the Conventional Commits specification (e.g. `feat(core): message`, `fix(cli): message`, `docs(skills): message`).
+- **PR Size Limits (Incremental Delivery)**: Pull requests must be highly targeted and minimal. Changes exceeding a reasonable line-count limit (e.g., 500 lines of code) must be split into multiple scoped branches.
+- **Dirty State Preservation**: Preserve unrelated local uncommitted files or dirty states. Never wipe unrelated local modifications during branch checkouts.
+- **Task Traceability**: Reference the task slug or ticket ID in branch names and commit descriptions.
 - Never write directly to protected main/master branches.
 - Do not claim execution without evidence.
 
@@ -36,16 +39,20 @@ Do not trust:
 - commit files
 - run validation suite
 - generate handoff reports
+- git diff and status tools
 
 ## Forbidden actions
 - merging pull requests with failing validations
 - force pushing to main/master
+- committing unrelated changes to the same feature branch
+- writing generic or opaque commit messages (e.g., "fix code", "update")
 
 ## Procedure
-1. Create a scoped feature branch from main.
-2. Apply changes incrementally in small commits.
-3. Run validation scripts on the branch.
-4. Produce handoff documentation summarizing the change.
+1. **Assess Git Working Tree**: Run `git status` to identify and protect any existing unrelated dirty work.
+2. **Branch Creation**: Create a scoped feature branch containing the task slug/ID from the clean head.
+3. **Incremental Staging & Commits**: Group edits logically. Write clear, Conventional Commit messages for each change.
+4. **Local Validation**: Run the branch validation pipelines before staging completion.
+5. **Handoff Generation**: Generate standard handoff ledgers detailing branch, changes, validations, and limitations.
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/product-discovery/SKILL.md

@@ -30,6 +30,8 @@ Do not trust:
 - Target framework parameters
 
 ## Constraints
+- **Non-Destructive Execution**: Under no circumstances should discovery operations mutate, rewrite, or delete workspace files, permissions, or git tags. All file access must be strictly read-only.
+- **Validation Routine Discovery**: Locate and map every local testing and validation command available. Verify their presence and executable health via safe dry-runs or status checks without writing changes.
 - Do not mutate files in discovery mode.
 - Do not bypass branch gate.
 - Do not claim execution without evidence.
@@ -40,6 +42,7 @@ Do not trust:
 - inspect package metadata
 - run safe validation commands
 - generate structured report
+- query git status and logs
 
 ## Forbidden actions
 - git push
@@ -48,14 +51,15 @@ Do not trust:
 - gh release create
 - writing directly to main
 - editing files
+- proposing solutions that bypass local safety gates or skip required validation checks
 
 ## Procedure
-1. Inspect package.json and lock files to identify project type and stack.
-2. Map key entry points, source directories, and configuration files.
-3. Identify all package scripts and validation commands.
-4. Check for existing documentation and generated files.
-5. Audit code and configurations for risk areas and missing validation checks.
-6. Synthesize findings into the discovery report.
+1. Inspect package.json, lock files, and build setups to identify project type and technical stack.
+2. Map key entry points, source directories, configuration folders, and dependency chains.
+3. Identify and document all package scripts, validation tools, and E2E testing commands.
+4. Check for existing technical documentation, policies, and generated configuration files.
+5. Audit codebase files for risks, outdated dependencies, and missing local verification gates.
+6. Synthesize discovery findings into the final project structure report.
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/product-planning/SKILL.md

@@ -27,6 +27,8 @@ Do not trust:
 - Target milestone dates
 
 ## Constraints
+- **Sprint Scope Containment**: Under no circumstances should unplanned feature requests or cosmetic modifications be injected into an active sprint backlog without formal impact analysis and stakeholder approval.
+- **Explicit Definition of Done (DoD)**: Every planning requirement must specify an explicit, automated verification method (e.g., test cases, compliance script exit codes) before being cataloged as planned.
 - Maintain product scope boundaries.
 - Ensure all requirements have clear acceptance criteria.
 - Do not claim execution without evidence.
@@ -35,16 +37,18 @@ Do not trust:
 - read roadmap
 - create requirement files
 - define acceptance criteria
+- construct prioritization matrices
 
 ## Forbidden actions
 - adding unapproved features to active Sprint scope
 - bypassing design guidelines
+- declaring milestones without explicit validation gates
 
 ## Procedure
-1. Review raw feedback and feature requests.
-2. Formulate target requirements and milestones.
-3. Categorize features by priority and impact.
-4. Define acceptance criteria for requirements.
+1. Review raw user feedback, bug reports, and roadmap specifications.
+2. Construct feature priority matrices using defined impact and complexity scores.
+3. Formulate target requirements, milestone timelines, and dependency mappings.
+4. Define concrete acceptance criteria and verify their alignment with the project's Definition of Done (DoD).
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/project-memory/SKILL.md

@@ -27,6 +27,9 @@ Do not trust:
 - Project memory request
 
 ## Constraints
+- **Structured ADR Formatting**: Architecture Decision Records (ADRs) must follow a strict format (Context, Decision, Consequences, Status: Proposed/Accepted/Deprecated/Superseded).
+- **Anti-Regression Correction Logging**: Record lessons learned from past failures, E2E errors, and quality gate rejections to prevent future agents from repeating them.
+- **Discoverable Rules Enforcement**: Align memory additions with `.agents/config` or workspace rules files so future agents load this context at session start.
 - Never delete history of past corrections.
 - Keep memory entries concise and discoverable.
 - Do not claim execution without evidence.
@@ -35,15 +38,20 @@ Do not trust:
 - read/write memory files
 - update ADR logs
 - check formatting
+- run schema linter
+- search git history
 
 ## Forbidden actions
 - editing memory files with unverified details
 - force overwriting active config files
+- omitting consequences or context from decision logs
 
 ## Procedure
-1. Capture new project decision or lessons learned.
-2. Update project-memory.md or configuration details.
-3. Ensure guidelines are discoverable by future agents.
+1. **Analyze Decision/Incident**: Map the new architectural decision, correction, or lesson learned from recent tests/incidents.
+2. **Format as ADR**: Structure the decision in the standard ADR format.
+3. **Register Anti-Regression Context**: Log past failures and their corrections in the historical ledger.
+4. **Enforce Discoverability**: Reference or link the new rule/memory block inside the workspace rules (`AGENTS.md` or `.agents/config`).
+5. **Verify Formatting & Schemas**: Run schema linting tools to guarantee memory configuration integrity.
 
 ## Expected output schema
 Output must include:

package/dist-assets/skills/prompt-engineer/SKILL.md

@@ -27,6 +27,8 @@ Do not trust:
 - Execution transcript
 
 ## Constraints
+- **Security & Injection Auditing**: All system instructions and custom prompt configurations must be audited against prompt injection vulnerabilities and instructions leakage before deployment.
+- **Predictable Token Footprint**: Optimize instruction syntax to avoid boilerplate, maintaining crisp, actionable clauses (ideally under 500 lines or token budget limits) to preserve workspace context.
 - Maintain strict behavioral boundaries.
 - Ensure prompts are deterministic.
 - Do not claim execution without evidence.
@@ -35,15 +37,18 @@ Do not trust:
 - design prompts
 - review system instructions
 - analyze transcripts
+- test prompt resilience
 
 ## Forbidden actions
 - altering core agent identities
 - injecting instructions that bypass safety gates
+- introducing conflicting or overlapping constraints that cause agent non-determinism
 
 ## Procedure
-1. Analyze prompt failure or improvement area.
-2. Draft clear, structured system instructions.
-3. Test prompt under multiple edge cases.
+1. Analyze prompt execution failures, non-deterministic behaviors, or improvement areas.
+2. Draft clear, structured system instructions containing specific constraints and allowed tools.
+3. Run resilience tests against potential prompt injection scenarios.
+4. Perform token economy checks to verify prompt length fits within limits.
 
 ## Expected output schema
 Output must include:

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

@@ -29,6 +29,10 @@ Do not trust:
 - Codebase paths
 
 ## Constraints
+- **Visual & Accessibility (A11y) Gates**: If changes affect frontend UIs, automated visual regression (screenshots) and accessibility (Axe-core via Playwright) checks must be executed.
+- **Mock Safety & Boundary Containment**: Forbid testing dependencies on active production environments or unmocked third-party APIs. Sandbox external calls using mock fixtures.
+- **Coverage Maintenance**: Test coverage metrics must not decrease after the implementation of new features. Any new code block must be covered by unit or E2E tests.
+- **Regression Testing**: Every bug fix or issue resolution must be accompanied by a failing test case that proves the fix is operational (regression test).
 - All validation commands must exit 0.
 - No manual test overrides allowed.
 - Do not claim execution without evidence.
@@ -38,20 +42,21 @@ Do not trust:
 - execute test suites
 - analyze coverage
 - run linter
+- execute Axe-core accessibility scanners
+- run visual screenshot tools
 
 ## Forbidden actions
-- git push
-- git tag
-- npm publish
 - bypassing quality gates
+- using manual assertions as substitutes for automated test execution
+- hardcoding local file system paths inside test assertions
 
 ## Procedure
-1. Identify all changed files and classify risk level.
-2. Determine appropriate test strategy (unit, E2E, integration).
-3. Run relevant validation commands.
-4. Capture command outputs, exit codes, and coverage metrics.
-5. Document all findings and failures.
-6. Evaluate overall quality against the quality gate.
+1. **Analyze Diff & Identify Risks**: Inspect the modified files, classify the risk level, and identify frontend vs backend boundaries.
+2. **Select Testing Strategy**: Choose the correct blend of unit tests, API integration tests, visual regression tests, and accessibility scans.
+3. **Inject Mock Fixtures**: Prepare mocks for any database, network, or external API interaction.
+4. **Execute Tests & Linters**: Run the appropriate linting, styling, and test runner commands.
+5. **Inspect Coverage & UI Outputs**: Analyze code coverage reports, visual diffs, and Axe-core accessibility violation reports.
+6. **Compile Validation Ledger**: Document exit codes, coverage deltas, screenshot locations, and final decision (PASS, PASS_WITH_NOTES, BLOCKED).
 
 ## Expected output schema
 Output must include:

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

@@ -29,6 +29,9 @@ Do not trust:
 - File paths
 
 ## Constraints
+- **Least-Diff Principle**: Make the smallest possible code changes (minimum lines modified) to achieve the structural improvement or fix. Avoid refactoring unrelated code blocks or cosmetic changes.
+- **Pre-Refactor Snapshot validation**: Execute a local baseline test run to verify the workspace is functional before applying any structural refactoring.
+- **No Signature Mutation**: Do not alter public API structures, function signatures, exported types, or database schemas during refactoring unless explicitly required to resolve the issue.
 - Ensure all tests pass.
 - Do not introduce new features during refactoring or fixing.
 - Do not claim execution without evidence.
@@ -37,20 +40,24 @@ Do not trust:
 - edit code files
 - run validation commands
 - run linter
+- profile performance impact
 
 ## Forbidden actions
 - git push
 - git tag
 - npm publish
 - editing files outside allowed scope
+- applying speculative optimization patterns without performance profiles or profiling data
+- modifying unrelated healthy components or styling variables
 
 ## Procedure
 1. Require a concrete finding or failing test before starting.
-2. Investigate the root cause of the issue.
-3. Design a bounded fix targeting only the affected area.
-4. Apply the change to allowed files.
-5. Run revalidation commands to verify the fix.
-6. Limit remediation to a maximum of 3 attempts before blocking.
+2. Run a baseline execution of the validation/test suite.
+3. Investigate the root cause of the issue.
+4. Design a bounded fix using the Least-Diff Principle targeting only the affected area.
+5. Apply the change to allowed files.
+6. Run revalidation commands to verify the fix.
+7. Limit remediation to a maximum of 3 attempts before blocking.
 
 ## Expected output schema
 Output must include:

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

@@ -28,6 +28,9 @@ Do not trust:
 - Release parameters
 
 ## Constraints
+- **NPM Package Verification Gate**: Before final release approval, the generated package tarball must be built, packaged, and verified locally by running installation tests (`npm install <tarball>`) in a temporary sandbox.
+- **SemVer Conformity Check**: Enforce strict Semantic Versioning. Bumping of major, minor, or patch versions must directly correspond to API-breaking changes, new non-breaking features, or bug fixes, respectively.
+- **Unlinked Draft Prevention**: Ensure that release tags or release attempts are linked only to commits that have successfully completed building and testing in the target branch.
 - Explicit user approval required.
 - Do not publish to npm, push to remote, or create tags without approval.
 - Do not claim execution without evidence.
@@ -37,20 +40,23 @@ Do not trust:
 - update version files
 - generate changelog
 - calculate sha256 checksum
+- run sandbox installation checks
 
 ## Forbidden actions
 - npm publish without approval
 - git push without approval
 - git tag without approval
 - gh release create without approval
+- publishing with local/untracked source file leaks or untested dependency variants
 
 ## Procedure
 1. Perform version check against remote/registry state.
 2. Ensure working tree is completely clean.
 3. Run full release verification suite.
-4. Record tarball filename and compute its SHA-256 hash.
-5. Update package version and CHANGELOG.md.
-6. Document release evidence.
+4. Build the package tarball and execute a sandbox installation check.
+5. Record tarball filename and compute its SHA-256 hash.
+6. Update package version and CHANGELOG.md.
+7. Document release evidence.
 
 ## Expected output schema
 Output must include:

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

@@ -28,6 +28,8 @@ Do not trust:
 - Target specifications template
 
 ## Constraints
+- **Atomic Verification Criteria**: Every acceptance criterion in the specification must map to a distinct, automated verification method (unit test, integration test, visual snapshot, or compilation validation). Avoid vague or qualitative assertions.
+- **Traceability Matrix**: Every requirement must explicitly link back to a business goal or user request and point forward to its corresponding test case or validation check.
 - Specs must be testable.
 - Non-goals must be explicitly defined.
 - No code changes allowed in spec phase.
@@ -37,6 +39,7 @@ Do not trust:
 - read requirements
 - write specification files
 - validate schema compliance
+- map requirements matrix
 
 ## Forbidden actions
 - git push
@@ -44,16 +47,18 @@ Do not trust:
 - npm publish
 - gh release create
 - modifying source code files
+- creating ambiguous acceptance criteria (e.g., "should feel fast" or "should be easy to use")
 
 ## Procedure
 1. Read and analyze the requirement document.
 2. Define the problem statement and scope of work.
 3. List explicit non-goals to prevent scope creep.
 4. Formulate functional and technical requirements.
-5. Create acceptance criteria for each requirement.
-6. Design a validation and test plan.
-7. Outline the implementation plan step-by-step.
-8. Define verification evidence and PASS/BLOCKED criteria.
+5. Create acceptance criteria for each requirement, ensuring they are concrete and measurable.
+6. Design a validation and test plan specifying the automated tools to verify each requirement.
+7. Build a requirements traceability matrix mapping source requests to specification sections and verification methods.
+8. Outline the implementation plan step-by-step.
+9. Define verification evidence and PASS/BLOCKED criteria.
 
 ## Expected output schema
 Output must include:

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

@@ -27,6 +27,9 @@ Do not trust:
 - Stack criteria
 
 ## Constraints
+- **Anti-Over-Engineering Principle**: Choose the simplest technology stack that solves the problem. Enforce the use of platform-native APIs (e.g. Node.js native fs/promises, crypto, fetch) instead of adding external dependencies whenever possible.
+- **Strict Dependency Control**: Reject proposals that introduce redundant or overlapping npm packages (such as importing multiple utility, HTTP, or parser libraries).
+- **Performance-Complexity Auditing**: Analyze the resource footprint (bundle size, startup latency, CPU overhead) of any library proposal before approval.
 - Ensure stack scalability.
 - Enforce strict maintainability guidelines.
 - Do not claim execution without evidence.
@@ -35,15 +38,19 @@ Do not trust:
 - review design proposals
 - run stack analysis
 - evaluate architectural trade-offs
+- inspect package dependency graphs
+- run bundle size analyzers
 
 ## Forbidden actions
-- adopting experimental tools without staging validation
-- introducing conflicting dependencies
+- adopting experimental or unmaintained dependencies
+- introducing redundant libraries that duplicate native capabilities
+- approving designs without documented alternatives and trade-offs
 
 ## Procedure
-1. Review architectural or design proposals.
-2. Evaluate trade-offs (performance, cost, security).
-3. Approve technical plan or recommend adjustments.
+1. **Verify Native Alternatives**: Assess if the requirement can be resolved using built-in runtime features.
+2. **Audit Dependencies**: Review the package graph to ensure no redundant or overlapping modules are introduced.
+3. **Evaluate Trade-offs**: Measure implementation speed and developer maintenance cost against runtime footprint and bundle size impact.
+4. **Approve and Document**: Deliver the final design approval along with a scalability assessment and architectural compromise details.
 
 ## Expected output schema
 Output must include:

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

@@ -27,6 +27,9 @@ Do not trust:
 - Design feedback
 
 ## Constraints
+- **State-Completeness Enforcement**: Every interactive component and view must define styles and transitions for all execution states: Initializing, Loading, Empty, Error, and Success.
+- **Strict Typography Ratio**: All text styles must use proportional line-heights matching their function: 1.1–1.25 for headings and titles, and 1.5–1.7 for body text and long-form descriptions.
+- **Rigid 8px Layout Grid**: Spacing, margins, paddings, and structural sizing must align strictly to the 8px grid system (allowable steps: 4px for fine adjustments, 8px, 16px, 24px, 32px, 48px, 64px, 96px).
 - Follow strict contrast and accessibility (WCAG) guidelines.
 - Spacing must align with layout grids.
 - Do not claim execution without evidence.
@@ -35,15 +38,20 @@ Do not trust:
 - review layouts
 - verify visual styles
 - check accessibility contrast
+- audit state completeness
+- inspect typography line-heights
 
 ## Forbidden actions
 - using non-standard styling tokens
 - committing inconsistent layouts
+- introducing components lacking complete lifecycle states (loading/error/empty)
+- using arbitrary spacing or padding values outside the 8px grid
 
 ## Procedure
 1. Review wireframe or layout for design inconsistencies.
-2. Align elements with standard typography and spacing tokens.
+2. Align elements with standard typography and spacing tokens, checking that line-heights match headings (1.1–1.25) or body (1.5–1.7) criteria.
 3. Validate contrast ratios and accessibility parameters.
+4. Verify that all lifecycle/feedback states (Initializing, Loading, Empty, Error, Success) are covered with consistent visual cues.
 
 ## Expected output schema
 Output must include:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.4.2",
+  "version": "2.4.5",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",

package/src/cli.js

@@ -4,6 +4,7 @@ import { runDoctor } from "./commands/doctor.js";
 import { runCollectEvidence } from "./commands/collect-evidence.js";
 import { runMasterOrchestrator } from "./commands/run.js";
 import { runExecute } from "./commands/execute.js";
+import { runClean } from "./commands/clean.js";
 
 function printHelp() {
   console.log(`ai-workflow
@@ -15,6 +16,7 @@ Usage:
   ai-workflow validate [--a11y] [--visual-dist=<path>] [--port=<port>]
   ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run] [--visual-dist=<path>] [--port=<port>]
   ai-workflow doctor
+  ai-workflow clean [--yes] [--dry-run] [--purge-agents]
 
 Commands:
   execute           Orchestrate execution of a natural request through the state machine
@@ -22,6 +24,7 @@ Commands:
   init              Install AI workflow defaults (OpenCode). --profile=standard (default) or --profile=full (adds examples)
   collect-evidence  Run observed project validation; persists EVIDENCE.json only for full mode
   doctor            Verify local ai-workflow installation
+  clean             De-initialize and remove AI Workflow files and symlinks from the project
 `);
 }
 
@@ -58,7 +61,8 @@ function parseFlags(args) {
     request: requestArg ? requestArg.replace("--request=", "") : undefined,
     visualDist: visualDistArg ? visualDistArg.replace("--visual-dist=", "") : undefined,
     port: portArg ? portArg.replace("--port=", "") : undefined,
-    a11y: args.includes("--a11y")
+    a11y: args.includes("--a11y"),
+    purgeAgents: args.includes("--purge-agents") || args.includes("--purge")
   };
 }
 
@@ -139,5 +143,13 @@ export async function runCli(args) {
     return;
   }
 
+  if (command === "clean") {
+    await runClean({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    return;
+  }
+
   throw new Error(`unknown command: ${command}`);
 }

package/src/commands/clean.js

@@ -0,0 +1,106 @@
+import { existsSync, rmSync, lstatSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import readline from "node:readline";
+
+function askConfirmation(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function isSymlink(filePath) {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+
+export async function runClean({ cwd, yes = false, dryRun = false, purgeAgents = false }) {
+  const targets = [
+    ".ai-workflow",
+    "opencode.jsonc",
+    ".workflow-state.json",
+    "opencode"
+  ];
+
+  const hasAgents = existsSync(join(cwd, ".agents"));
+
+  // Check what actually exists
+  const existingTargets = targets
+    .map(name => join(cwd, name))
+    .filter(path => existsSync(path) || isSymlink(path));
+
+  if (existingTargets.length === 0 && (!hasAgents || !purgeAgents)) {
+    console.log("No AI Workflow configuration or files found in the current project.");
+    return;
+  }
+
+  console.log("\n[AI WORKFLOW] De-initialization");
+  console.log("===============================");
+
+  if (dryRun) {
+    console.log("[DRY RUN] The following items would be deleted:");
+    existingTargets.forEach(path => console.log(`  - ${path}`));
+    if (hasAgents && purgeAgents) {
+      console.log(`  - ${join(cwd, ".agents")} (customizations folder)`);
+    } else if (hasAgents) {
+      console.log(`  - NOTE: ${join(cwd, ".agents")} exists but will NOT be deleted (run with --purge-agents to delete)`);
+    }
+    return;
+  }
+
+  // Interactive prompts if --yes / -y is not passed
+  if (!yes) {
+    if (!process.stdin.isTTY) {
+      console.log("Error: Non-interactive terminal detected. Run with --yes to bypass confirmation.");
+      if (process.env.NODE_ENV === "test") {
+        // Allow tests to bypass TTY block if they mock/stub process.stdin
+      } else {
+        process.exit(1);
+      }
+    }
+
+    const confirmDeinit = await askConfirmation("Are you sure you want to de-initialize AI Workflow from the project? [y/N] ");
+    if (confirmDeinit !== "y" && confirmDeinit !== "yes") {
+      console.log("Aborted.");
+      return;
+    }
+
+    if (hasAgents && !purgeAgents) {
+      const confirmPurge = await askConfirmation("A custom '.agents' folder was detected. Do you want to purge it (this deletes custom prompts/rules/skills)? [y/N] ");
+      if (confirmPurge === "y" || confirmPurge === "yes") {
+        purgeAgents = true;
+      }
+    }
+  }
+
+  // Add .agents if requested and exists
+  if (purgeAgents && hasAgents) {
+    existingTargets.push(join(cwd, ".agents"));
+  }
+
+  console.log("\nRemoving files...");
+  for (const target of existingTargets) {
+    try {
+      if (isSymlink(target)) {
+        unlinkSync(target);
+        console.log(`Deleted symlink: ${target}`);
+      } else {
+        rmSync(target, { recursive: true, force: true });
+        console.log(`Deleted directory/file: ${target}`);
+      }
+    } catch (error) {
+      console.error(`Failed to delete ${target}: ${error.message}`);
+    }
+  }
+
+  console.log("\nAI Workflow has been successfully removed from this project.");
+}

package/src/core/validation/artifact-fidelity-gate.js

@@ -392,19 +392,19 @@ export class ArtifactFidelityGate {
       }
     }
 
-    // 1. Tokens CSS mínimos Check
+    // 1. Minimum CSS tokens check
     const hasRules = cssContentCombined.includes("{");
-    const hasCssVars = /--[a-zA-Z0-9_-]+\s*:/g.test(cssContentCombined);
+    const hasCssVars = /(--[a-zA-Z0-9_-]+\s*:|var\(--[a-zA-Z0-9_-]+\))/g.test(cssContentCombined);
     if (hasRules && !hasCssVars) {
-      violations.push("Fidelity Violation: Design System token mismatch. No CSS custom properties (variables) detected in changed UI stylesheets.");
+      violations.push("Fidelity Violation: Design System token mismatch. No CSS custom properties (variables) detected or used in changed UI stylesheets.");
     }
 
-    // 2. Excesso de style="..."
+    // 2. Excessive style="..." inline styles check
     if (styleAttrsCount > 5) {
       violations.push(`Fidelity Violation: excessive inline styles detected (${styleAttrsCount} style="..." declarations). Use CSS classes or utility classes instead.`);
     }
 
-    // 3. HTML principal tags semânticas básicas Check
+    // 3. Main HTML semantic tags check
     if (htmlContentCombined.length > 0) {
       const hasSemanticTags = /<(header|main|footer|nav|section)\b/i.test(htmlContentCombined);
       const hasH1 = /<h1\b/i.test(htmlContentCombined);