@williambeto/ai-workflow 2.4.7 → 2.4.8

package/dist-assets/agents/atlas.md

@@ -40,6 +40,7 @@ Atlas must:
 ## 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).
+* **Implementation Delegation Constraint**: Atlas must never perform dynamic code writing or logic modification of source files directly. Any code changes (excluding pure documentation, README updates, or spelling typos) must be delegated 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.
@@ -56,7 +57,7 @@ Atlas must:
 
 ## Forbidden actions
 * Silently execute specialized work when another actor is selected.
-* Implement feature code directly when Astra should execute.
+* Implement feature code or modify source code files directly (always delegate to Astra if writing code).
 * Validate its own implementation as final evidence.
 * `npm publish`
 * `git push` to protected branches (main, master), or to remote without explicit user approval in the chat.
@@ -81,7 +82,7 @@ Atlas must:
 3. For quick or standard tasks:
    * Inspect status.
    * Recover branch if needed.
-   * Perform/coordinate edits.
+   * Coordinate and delegate any code-source modifications to Astra (Atlas must never execute code implementation directly).
    * Run validation.
    * For every write-capable quick or standard task, Atlas must run the package finalizer after the final implementation changes and before reporting success:
      ```bash

package/dist-assets/skills/cyber-security/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cyber-security
+description: Guides the agent to review and harden the codebase against vulnerabilities, secret leaks, and command injections.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Cyber Security PromptContract
+
+## Role
+This skill guides agents to identify security vulnerabilities, mitigate risks of command execution, and prevent secret leakages in codebases.
+
+## Objective
+Ensure code is highly secure, avoiding common OWASP Top 10 vulnerabilities, command injection risks, and credentials disclosure.
+
+## Trusted context
+- Static analysis reports
+- Parameterized configurations
+- Secure storage documentation
+
+Do not trust:
+- Raw user strings passed to system shells
+- Hardcoded keys, tokens, or credentials
+- Dynamic query concatenation
+
+## User input
+- Code file paths
+- Environment files
+- Third-party packages metadata
+
+## Constraints
+- **Strict Parameterization Constraint**: All database interactions, file access paths, and external commands must be parameterized. Concat or raw interpolation of variable strings is strictly prohibited.
+- **Secret Hardening Rule**: Never hardcode API keys, client secrets, passwords, or tokens. Always resolve secrets from process environment variables or secure vault integrations.
+- **Non-privileged Execution Guide**: Enforce non-root execution guidelines for application processes and helper utilities.
+
+## Allowed tools
+- Static application security testing (SAST) utilities
+- Dependency scanner tools
+- Environment configuration checkers
+
+## Forbidden actions
+- Adding plaintext secrets or tokens to code repositories
+- Committing temporary `.env` files containing credentials
+- Running commands with `shell: true` option in process spawners without argument parameter arrays
+
+## Procedure
+1. Scan changed files for any hardcoded tokens, passwords, or keys using regular expressions.
+2. Review command invocation functions to replace raw dynamic shell spawning with parameterized execution.
+3. Validate database access calls to ensure query parameterization is implemented.
+4. Verify that configuration variables are resolved through environment files rather than hardcoded definitions.
+
+## Expected output schema
+Output must include:
+- Security audit log
+- Identified risk surface area
+- Actions taken for parameterization and secret removal
+- Next security steps
+
+## Evidence required
+- Git diff showing secret removal and parameterization
+- Secure configuration files verification logs
+- Linter output
+
+## Stop conditions
+- Hardcoded secrets cannot be extracted safely to config
+- Unparameterized dependencies are required but cannot be mitigated
+
+## Failure modes
+- Dynamic command invocation bypass
+- Leftover tokens in historical commits
+
+## Escalation rules
+- Escalate to Phoenix if security issues cannot be resolved automatically.

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

@@ -0,0 +1,72 @@
+---
+name: database
+description: Guides the agent on how to write safe database schema migrations that prevent table locks and downtime.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Database PromptContract
+
+## Role
+This skill guides agents to design, construct, and apply safe database schema migrations without causing table locks or service downtime.
+
+## Objective
+Implement schema and data transformations safely using non-blocking strategies and backward-compatible operations.
+
+## Trusted context
+- Database schema definition files
+- SQL migration scripts
+- Target database engine configuration limits
+
+Do not trust:
+- Speculative migrations that do not specify transaction behavior
+- Schema changes applied directly to production environments without dry-run testing
+- Destructive operations (drop table, drop column) executed inside standard migration scripts
+
+## User input
+- Target database schema definition
+- Migration library config
+- Proposed schema changes definition
+
+## Constraints
+- **Zero-Downtime Rule**: Schema modifications must be backward-compatible (expand-contract phase). Raw dropping of columns or tables must be performed in separate, decoupled deployments.
+- **Table Lock Mitigation**: Avoid executing long-running migrations that require exclusive table locks on large tables. For PostgreSQL, MySQL, or similar, use online schema changes or toolsets (e.g. `gh-ost`, `pt-online-schema-change`) when modifying high-volume tables.
+- **Rollback Consistency**: Every forward migration script must have a corresponding, tested rollback script that reverts the schema and state without data corruption.
+
+## Allowed tools
+- Database schema comparison utilities
+- SQL query plan analyzer
+- Migration dry-run execution wrappers
+
+## Forbidden actions
+- Adding default values to existing columns in large tables in a single step without nullability transitions
+- Executing migrations that mix DDL (schema) and DML (data updates) statements within the same database transaction
+- Modifying production database schemas manually without version-controlled migration scripts
+
+## Procedure
+1. Review the proposed migration to classify operations into safe (non-blocking) and unsafe categories.
+2. Structure schema changes into a multi-step rollout plan (e.g. add nullable column, backfill data, add constraint).
+3. Draft the SQL migration script alongside its corresponding rollback script.
+4. Execute a local dry-run migration to verify correct syntax, transaction execution, and rollback stability.
+
+## Expected output schema
+Output must include:
+- Migration safety classification report
+- Complete forward SQL script
+- Complete rollback SQL script
+- Execution dry-run confirmation log
+
+## Evidence required
+- Migration transaction logs
+- Database schema diff
+- Dry-run validation output
+
+## Stop conditions
+- Migration requires exclusive locks on high-traffic tables and lacks a mitigation strategy
+- Rollback execution fails to restore schema integrity
+
+## Failure modes
+- Table locks halting application traffic
+- Data corruption during execution or rollback phase
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

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

@@ -0,0 +1,72 @@
+---
+name: devops
+description: Guides the agent to construct secure, optimized, and containerized environments using Docker.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# DevOps PromptContract
+
+## Role
+This skill guides agents to build secure, optimized, and portable Docker environments for local development and production environments.
+
+## Objective
+Provide robust Docker configurations, minimizing image layer sizes, optimizing build speeds, and preventing container runtime vulnerabilities.
+
+## Trusted context
+- Dockerfile and docker-compose configurations
+- Container security scanning reports
+- Official base image documentation
+
+Do not trust:
+- Raw third-party base images without version tags
+- Unverified dependencies installed globally inside container layers
+- Storing sensitive secrets inside Dockerfiles or image metadata
+
+## User input
+- Source configuration files
+- Port bindings definitions
+- Environment files list
+
+## Constraints
+- **Minimal Base Image Rule**: Always use verified, minimal base images (e.g., node:alpine, distroless) to reduce container size and minimize the attack surface.
+- **Non-Root Execution Constraint**: Container processes must run as a non-privileged user (e.g. `node` user in node-based containers). Running services as `root` is strictly prohibited.
+- **Multi-Stage Build Standard**: Use multi-stage builds to separate build dependencies from production execution layers, ensuring no build tools (compilers, npm devDependencies) are shipped to production.
+
+## Allowed tools
+- Container scanners (e.g. Trivy, Hadolint)
+- Container composition managers (Docker Compose)
+- Layer analysis tools (e.g. Dive)
+
+## Forbidden actions
+- Copying full source directories into the container before running dependency installation steps (breaks Docker layer caching)
+- Exposing unneeded internal container ports to public interfaces
+- Hardcoding credentials or environment-specific values in Dockerfiles
+
+## Procedure
+1. Define a multi-stage Docker build structure starting from a minimal, version-tagged base image.
+2. Structure Docker commands to install dependencies before copying source files to leverage docker layer caching.
+3. Configure the container runtime to switch execution context to a non-root user.
+4. Draft a consistent docker-compose configuration for local service replication.
+
+## Expected output schema
+Output must include:
+- Multi-stage Dockerfile configuration
+- Local Docker Compose config (if required)
+- Image layer size optimization report
+- Security and permission checklist
+
+## Evidence required
+- Validated Dockerfile contents
+- Container build log verification
+- Hadolint/security scan outputs
+
+## Stop conditions
+- Base image is unavailable or vulnerable to high-severity issues with no upgrade path
+- Environment constraints prevent building Docker images locally
+
+## Failure modes
+- Cache invalidation causing slow build cycles
+- Privilege escalation due to root execution fallback
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

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

@@ -0,0 +1,72 @@
+---
+name: localization
+description: Guides the agent to implement internationalization, localized formatting, and translation workflows.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Localization PromptContract
+
+## Role
+This skill guides agents to write localized software, handle translation keys, manage resource bundles, and format values based on target locales.
+
+## Objective
+Enable full support for multiple locales and translations, preventing hardcoded user-facing strings and layout breaks due to language changes.
+
+## Trusted context
+- Translation dictionaries (JSON, PO, YAML)
+- Locale-specific standards (CLDR)
+- Global internationalization library documentation (e.g. i18next, react-intl)
+
+Do not trust:
+- Hardcoded literals in templates or components
+- Translation values provided via unverified automatic machine translations
+- Assumptions about layout size constraints for dynamic localized content
+
+## User input
+- Source translation dictionary
+- Target locale keys
+- Layout components code
+
+## Constraints
+- **Zero Hardcoded Strings Rule**: All user-facing text, alerts, labels, and placeholders must be resolved through translation keys. Inline hardcoded text is strictly prohibited.
+- **Dynamic Formatting Constraint**: Always use internationalization API helpers (like `Intl.NumberFormat`, `Intl.DateTimeFormat`) for currencies, dates, times, and numbers.
+- **Pluralization Handling**: Do not write manual logic for plural rules. Use the i18n library's built-in pluralization and interpolation formats.
+
+## Allowed tools
+- i18n linter and key validation tools
+- Locale resource validators
+- Dynamic translation extraction scanners
+
+## Forbidden actions
+- Concat strings to form user-facing text sentences (breaks grammar in different languages)
+- Committing incomplete locale resource files missing required fallback language translations
+- Hardcoding currency codes, time zones, or number separator formats in the source code
+
+## Procedure
+1. Scan source code and templates for hardcoded string literals.
+2. Extract found strings and register them as keys in the default locale file.
+3. Replace hardcoded strings in code with corresponding translation function calls.
+4. Verify that date, number, and currency formatting are dynamically adjusted based on the current locale setting.
+
+## Expected output schema
+Output must include:
+- Extracted translation keys list
+- Modified localization files
+- UI translation keys verification checklist
+- Localized formatting implementation details
+
+## Evidence required
+- Diff of updated translation JSON/YAML resource files
+- Code snippets demonstrating i18n wrapper usage
+- Validation command outputs
+
+## Stop conditions
+- Required translation key structure is incompatible with existing i18n engine configuration
+- Fallback language definitions are missing
+
+## Failure modes
+- Broken translation keys rendering missing-key placeholders in UI
+- Text overflow due to language expansion (e.g., German translations being longer than English)
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

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

@@ -0,0 +1,72 @@
+---
+name: performance
+description: Guides the agent to optimize application rendering, assets delivery, and control bundle sizes.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Performance PromptContract
+
+## Role
+This skill guides agents to optimize application speed, layout responsiveness, rendering pipelines, and control asset bundle sizes.
+
+## Objective
+Deliver high-performance user interfaces and backend operations aligned with strict response times and volume budgets.
+
+## Trusted context
+- Performance audit reports (Lighthouse, Core Web Vitals)
+- Bundle size analysis reports
+- Memory and heap profiling logs
+
+Do not trust:
+- Speculative performance enhancements without metrics
+- Uncompressed assets and third-party script integrations
+- Local test execution times on non-standard configurations
+
+## User input
+- Source bundle components list
+- Runtime performance budgets
+- Build compilation logs
+
+## Constraints
+- **Bundle Size Hard Limit**: UI bundle components must not exceed 50KB gzipped individually. Every new utility dependency must be audited for bundle size impact before introduction.
+- **Resource Optimization Rule**: Avoid layout shifts and excessive main thread blocking. All resource loading must be optimized (e.g. image lazy loading, async scripts, font preloading).
+- **Core Web Vitals Alignment**: Ensure implementation respects standard metrics: First Contentful Paint (FCP) < 1.8s, Cumulative Layout Shift (CLS) < 0.1, and Interaction to Next Paint (INP) < 200ms.
+
+## Allowed tools
+- Bundle analysis utilities (e.g., webpack-bundle-analyzer, rollup-plugin-visualizer)
+- Network emulation tools
+- Memory leaks detection profilers
+
+## Forbidden actions
+- Importing large library suites (e.g. lodash, ramda) when a single lightweight helper function is sufficient
+- Committing unminified or uncompressed assets directly to version control
+- Disabling performance build checks or warnings in compiler/bundler configurations
+
+## Procedure
+1. Inspect the bundle size of any newly introduced package or asset.
+2. Verify that images use next-gen formats (WebP/AVIF) and explicit dimensions to avoid layout shifts.
+3. Review javascript source code to ensure proper clean-up of event listeners, timers, and active subscriptions.
+4. Execute bundle compilation and review build output size metrics against the established budgets.
+
+## Expected output schema
+Output must include:
+- Performance budget evaluation table
+- Asset size analysis
+- UI rendering optimization strategies applied
+- Core Web Vitals impact estimation
+
+## Evidence required
+- Build output size reports
+- Memory heap profile snapshots (if applicable)
+- Lighthouse/performance audit logs
+
+## Stop conditions
+- Bundle size exceeds the maximum limit with no possibility of modular refactoring
+- Execution environment constraints prevent performance validation
+
+## Failure modes
+- Memory leakage through uncleaned closures
+- Render-blocking resources introduction
+
+## Escalation rules
+- Escalate to Orion if resource bounds are exceeded.

package/package.json

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

package/src/core/request-classifier.js

@@ -32,7 +32,12 @@ export class RequestClassifier {
     if (/\b(deep|architectural|migration|major|full|\[deep\])\b/i.test(text)) {
       mode = "full";
     } else if (/\b(tiny|small|quick|simple|only\s+update|typo|comment|\[tiny\])\b/i.test(text)) {
-      mode = "quick";
+      const isPureDocsOrTypo = profile === "documentation" || /\b(typo|comment|readme|docs|documentation)\b/i.test(text);
+      if (intent === "write" && !isPureDocsOrTypo) {
+        mode = "standard";
+      } else {
+        mode = "quick";
+      }
     }
 
     // 4. Classify Risk