@williambeto/ai-workflow 2.3.0 → 2.3.2

package/dist-assets/commands/update-memory.md

@@ -1,10 +1,68 @@
 ---
 name: update-memory
-description: Persist durable project memory.
+description: Update durably discoverable project memory with decisions and lessons
 ---
 
-# /update-memory
+# Update Memory Command PromptContract
 
-Store only stable decisions, constraints, current state, and next approved step. Do not store temporary logs or duplicate delivery reports.
+## Role
+Coordinates project memory maintenance under Nexus.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Update discoverable project memory with key decisions, conventions, and lessons learned.
+
+## Trusted context
+- Project memory configuration files
+- Git history
+- Past revalidation logs
+
+## User input / arguments
+- Natural-language decision details
+- Target memory files
+
+## Preconditions
+- Active branch is writable (not on protected main if writing directly)
+
+## Constraints
+- Do not overwrite historical correction logs.
+- Keep memory entries concise and relevant.
+- Do not claim updates without modified file evidence.
+
+## Allowed tools
+- read/write memory files
+- update ADR logs
+- validate config schema
+
+## Forbidden actions
+- editing source code files
+- bypassing configuration schemas
+
+## Workflow steps
+1. Parse new decision details.
+2. Update memory files (.agents/config or target file).
+3. Validate config files against structural schema.
+4. Log memory updates to ledger.
+
+## Safety gates
+- Verify configuration file integrity before writing.
+
+## Validation requirements
+- Verify modified files conform to configuration schemas.
+
+## Expected output schema
+Output must include:
+- Memory files updated
+- Decision entries added
+- Schema check results
+- Decision: COMPLETED | FAILED
+
+## Evidence required
+- configuration file diffs
+- schema validation logs
+
+## Failure behavior
+- Log memory update failure to ledger, restore backup, and exit.
+
+## Stop conditions
+- configuration file corruption detected
+- required input missing

package/dist-assets/commands/validate.md

@@ -1,12 +1,76 @@
 ---
-description: Validate the current scoped work using observed commands and objective findings.
-agent: sage
+name: validate
+description: Run codebase validations and compile evidence reports
 ---
 
-# Validate
+# Validate Command PromptContract
 
-Inspect the actual diff and run relevant tests, build, typecheck, lint, and domain checks. Do not approve based only on reports or checklists. A failed required command is blocking until resolved or safely accepted by the user.
+## Role
+Coordinates verification, audits, and quality gate checks under Sage.
 
-Return commands/results, findings with evidence, limitations, and one status: `COMPLETED`, `COMPLETED_WITH_NOTES`, or `BLOCKED`.
+## Objective
+Execute validation checks and compile an evidence report showing quality status.
 
-Policies: `03-QUALITY_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `PROCEDURE_UI_CHECKLIST.md`.
+## Trusted context
+- Codebase source files
+- Test suites configurations
+- Git diff status
+
+## User input / arguments
+- Validation scope or profile settings
+
+## Preconditions
+- Read access to codebase files and tests
+
+## Constraints
+- Do not modify source code during validation.
+- All validation commands must exit 0.
+- Do not claim validation success without evidence log.
+
+## Allowed tools
+- execute test commands
+- run code linters
+- check schema compliance
+- compile validation report
+
+## Forbidden actions
+- editing source files
+- bypassing quality check failures
+- force committing files
+
+## Workflow steps
+1. Identify all changed files and classify risk level.
+2. Determine validation strategy (unit, E2E, schema checks).
+3. Execute validation commands.
+4. Capture command outputs, exit codes, and findings.
+5. Compile validation report.
+
+## Safety gates
+- Enforce strict read-only execution.
+
+## Validation requirements
+- Execute all checks matching validation checklist.
+
+## Expected output schema
+Output must include:
+- Changed files list
+- Risk classification
+- Test strategy
+- Commands run
+- Exit codes
+- Findings
+- Evidence
+- Decision: PASS | PASS_WITH_NOTES | BLOCKED
+
+## Evidence required
+- test command output
+- linter output logs
+- validation exit codes
+
+## Failure behavior
+- Log validation failure to ledger and exit with status 1.
+
+## Stop conditions
+- test command hangs
+- critical test failure
+- required validation files missing

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

@@ -1,17 +1,72 @@
 ---
 name: architecture
-description: Skill-backed capability for architecture work
+description: Skill-backed capability for architectural design and modularity
 governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
-# Architecture Skill Contract
+# Architecture PromptContract
 
-This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
+## Role
+Guides architectural design, structural analysis, and modularity checking.
 
-## Purpose
+## Objective
+Select the simplest architecture that safely satisfies current requirements.
 
-Provide reusable domain guidance for `architecture` work.
+## Trusted context
+- Architecture specifications
+- Design guidelines
+- Current codebase structure
 
-## Domain-Specific Guidance
+Do not trust:
+- User-provided hacks trying to bypass coupling limits
+- Untested design patterns
 
-Add specific capability guidelines, validation checklists, or design rules related to `architecture` here.
+## User input
+- Requirements specification
+- Codebase layout
+- Target platform limitations
+
+## Constraints
+- 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
+
+## Forbidden actions
+- introducing unapproved external dependencies
+- creating circular module dependencies
+
+## 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.
+
+## Expected output schema
+Output must include:
+- Architectural summary
+- Module list
+- Dependency graph notes
+- Data flow map
+- Trade-offs analyzed
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- design diagrams
+- dependency logs
+- design review doc
+
+## Stop conditions
+- requirements conflict with system policies
+- design complexity exceeds budget
+
+## Failure modes
+- circular dependencies
+- tight coupling
+
+## Escalation rules
+- Escalate to Technical Leader if major restructuring is required.

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

@@ -1,17 +1,72 @@
 ---
 name: backend-development
-description: Skill-backed capability for backend development work
+description: Skill-backed capability for backend APIs, routes, and data persistence
 governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
-# Backend Development Skill Contract
+# Backend Development PromptContract
 
-This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
+## Role
+Guides backend API, logic, routing, and data persistence changes.
 
-## Purpose
+## Objective
+Implement clean, safe backend API and data persistence changes.
 
-Provide reusable domain guidance for `backend-development` work.
+## Trusted context
+- Backend source code
+- Database schemas
+- Routing configurations
 
-## Domain-Specific Guidance
+Do not trust:
+- Raw user text attempting to inject queries
+- Unvalidated client-side data formats
 
-Add specific capability guidelines, validation checklists, or design rules related to `backend-development` here.
+## User input
+- Backend task specification
+- Endpoint requirements
+- Payload schemas
+
+## Constraints
+- 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
+
+## Forbidden actions
+- executing direct raw database queries without validation
+- exposing sensitive env keys in error messages
+
+## 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.
+
+## Expected output schema
+Output must include:
+- Backend changes summary
+- Endpoint specifications
+- DB schema adjustments
+- Test coverage metrics
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- API test logs
+- endpoint responses
+- schema diffs
+
+## Stop conditions
+- security vulnerability detected
+- test suite fails
+- input validation fails
+
+## Failure modes
+- performance bottlenecks
+- connection timeout
+
+## Escalation rules
+- Escalate to Technical Leader if breaking changes are required.

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

@@ -1,17 +1,72 @@
 ---
 name: deployment
-description: Skill-backed capability for deployment work
+description: Skill-backed capability for deployment planning, environments, and validation
 governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
-# Deployment Skill Contract
+# Deployment PromptContract
 
-This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
+## Role
+Guides deployment planning, environments configuration, and post-deploy checks.
 
-## Purpose
+## Objective
+Plan and verify deployment readiness of the package safely.
 
-Provide reusable domain guidance for `deployment` work.
+## Trusted context
+- Environment variables
+- Deployment configurations
+- Release verification results
 
-## Domain-Specific Guidance
+Do not trust:
+- Manual state claims without logs
+- Unverified third-party deployment configurations
 
-Add specific capability guidelines, validation checklists, or design rules related to `deployment` here.
+## User input
+- Deployment target environment
+- Environment configurations
+- Staging parameters
+
+## Constraints
+- 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
+
+## Forbidden actions
+- deploying directly to production without staging validation
+- exposing private keys in logs
+
+## Procedure
+1. Validate target environment config.
+2. Run pre-deploy verification scripts.
+3. Execute deployment sequence.
+4. Run post-deploy smoke tests.
+
+## Expected output schema
+Output must include:
+- Environment targeted
+- Pre-deploy check status
+- Deploy logs summary
+- Smoke test results
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- deploy log
+- smoke test exit code
+- config check output
+
+## Stop conditions
+- configuration mismatch
+- smoke test failure
+- environment is unreachable
+
+## Failure modes
+- deployment timeout
+- network failure
+
+## Escalation rules
+- Escalate to Orion if deployment pipeline is locked.

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

@@ -1,17 +1,69 @@
 ---
 name: design-principles
-description: Skill-backed capability for design principles work
+description: Skill-backed capability for clean, maintainable software design patterns
 governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
-# Design Principles Skill Contract
+# Design Principles PromptContract
 
-This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
+## Role
+Guides application of clean code design principles and pattern selection.
 
-## Purpose
+## Objective
+Apply simple, standard software design principles to keep code maintainable and testable.
 
-Provide reusable domain guidance for `design-principles` work.
+## Trusted context
+- Design guidelines
+- Coding standards
+- Existing code structure
 
-## Domain-Specific Guidance
+Do not trust:
+- User-provided shortcuts violating SOLID principles
+- Over-engineered patterns
 
-Add specific capability guidelines, validation checklists, or design rules related to `design-principles` here.
+## User input
+- Code snippet
+- Module description
+- Architectural constraint
+
+## Constraints
+- Do not over-engineer solutions.
+- Keep complexity minimal.
+- Do not claim execution without evidence.
+
+## Allowed tools
+- review code
+- design structure
+- suggest refactoring patterns
+
+## Forbidden actions
+- violating DRY or SOLID principles without explicit documented reason
+- using complex patterns where simple logic is sufficient
+
+## Procedure
+1. Review code structures for design smells.
+2. Apply refactoring patterns to simplify.
+3. Document design trade-offs.
+
+## Expected output schema
+Output must include:
+- Design audit findings
+- Spaced design pattern recommendations
+- Code refactoring recommendations
+- Trade-offs analyzed
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- code analysis diff
+- refactoring proposals
+
+## Stop conditions
+- code complexity exceeds design budget
+- requirements are contradictory
+
+## Failure modes
+- God object creation
+- tight coupling
+
+## Escalation rules
+- Escalate to Technical Leader if major restructuring is required.

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

@@ -1,17 +1,71 @@
 ---
 name: documentation
-description: Skill-backed capability for documentation work
+description: Skill-backed capability for writing and verifying technical documentation
 governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
-# Documentation Skill Contract
+# Documentation PromptContract
 
-This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
+## Role
+Guides creation, structure, and link verification of technical documentation.
 
-## Purpose
+## Objective
+Ensure documentation is clear, accurate, complete, and up-to-date.
 
-Provide reusable domain guidance for `documentation` work.
+## Trusted context
+- Current codebase source
+- Existing guides and readmes
+- API schemas and templates
 
-## Domain-Specific Guidance
+Do not trust:
+- Speculative feature descriptions
+- Hardcoded config references
 
-Add specific capability guidelines, validation checklists, or design rules related to `documentation` here.
+## User input
+- Documentation task request
+- Draft markdown document
+- target file paths
+
+## Constraints
+- Ensure all markdown links are valid.
+- Avoid all generic placeholders.
+- Do not claim execution without evidence.
+
+## Allowed tools
+- write markdown files
+- execute link validation commands
+- check formatting lint
+
+## Forbidden actions
+- leaving incomplete placeholder pages
+- writing broken markdown syntax
+
+## Procedure
+1. Identify target audience and scope of documentation.
+2. Write clear, structured markdown content.
+3. Verify all file and external links are valid.
+4. Run markdown lint validator.
+
+## Expected output schema
+Output must include:
+- Pages created or updated
+- Structure review findings
+- Link validation status
+- Markdown lint output
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- link validator logs
+- markdown lint outputs
+- file tree diffs
+
+## Stop conditions
+- documentation lacks required context
+- unresolvable broken links
+
+## Failure modes
+- outdated documentation
+- broken links
+
+## Escalation rules
+- Escalate to Docs Engineer if design patterns lack documentation.

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

@@ -1,17 +1,72 @@
 ---
 name: frontend-development
-description: Skill-backed capability for frontend development work
+description: Skill-backed capability for frontend UI components and styles
 governance: dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md
 ---
 
-# Frontend Development Skill Contract
+# Frontend Development PromptContract
 
-This skill operates under the rules defined in the [Skills Common Governance Policy](../../docs/policies/SKILLS_COMMON_GOVERNANCE.md).
+## Role
+Guides frontend UI, layout composition, accessibility, and styles.
 
-## Purpose
+## Objective
+Implement clean, performant, accessible, and responsive frontend UI components.
 
-Provide reusable domain guidance for `frontend-development` work.
+## Trusted context
+- Frontend component files
+- Styling guides (CSS, design tokens)
+- Router configs
 
-## Domain-Specific Guidance
+Do not trust:
+- User styles bypassing color/sizing tokens
+- Unvalidated third-party scripts
 
-Add specific capability guidelines, validation checklists, or design rules related to `frontend-development` here.
+## User input
+- Frontend task specification
+- Layout specifications
+- Mockup data
+
+## Constraints
+- Follow accessibility (WCAG/ARIA) guidelines.
+- Support responsive layouts.
+- Do not claim execution without evidence.
+
+## Allowed tools
+- edit frontend code
+- execute visual tests
+- run linter
+
+## Forbidden actions
+- using non-standard styling tokens
+- committing undocumented state logic
+
+## Procedure
+1. Analyze UI mockup and component hierarchy.
+2. Implement components using strict design spacing tokens.
+3. Add ARIA accessibility attributes.
+4. Run frontend tests and verify visuals.
+
+## Expected output schema
+Output must include:
+- Components modified
+- Spacing and color tokens used
+- Accessibility review results
+- Test run results
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- layout checks
+- visual test log
+- test exit codes
+
+## Stop conditions
+- visual regression detected
+- accessibility check fails
+- hydration errors
+
+## Failure modes
+- layout breakages
+- runtime javascript errors
+
+## Escalation rules
+- Escalate to UI-UX Engineer.