@williambeto/ai-workflow 2.2.7 → 2.3.1

package/dist-assets/commands/implement.md

@@ -1,28 +1,76 @@
 ---
-description: Implement a scoped change using a proportionate workflow and observed validation.
-agent: atlas
+name: implement
+description: Implement scoped changes incrementally and verify them
 ---
 
-# Implement
+# Implement Command PromptContract
 
-## Task
+## Role
+Guides Astra in making scoped source code implementation changes.
 
-Implement the requested scoped change.
+## Objective
+Implement a small task with defined scope, verifying changes incrementally.
 
-## Required behavior
+## Trusted context
+- Codebase source files
+- Requirements specifications
+- Current git diff status
 
-1. Verify branch and dirty state before editing.
-2. Never write on `main` or `master`; create a scoped branch when safe, otherwise stop `BLOCKED`.
-3. Select quick, standard, or full proportionately.
-4. Delegate only when specialization or independent review materially helps.
-5. Apply the minimum diff and preserve unrelated behavior.
-6. For new or changed executable behavior, add and run a proportional automated behavioral test; build/manual checks do not replace it.
-7. After the final implementation changes, run `npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>`.
-8. Treat the finalizer exit code and public status as authoritative; never report success when it returns `BLOCKED` or fails.
-9. Use bounded remediation for recoverable findings.
+## User input / arguments
+- Implementation task spec or requirements document
 
-## Output
+## Preconditions
+- Clean branch state (branch gate validation passed)
 
-Return status, branch, changes, validation commands/results, and known limitations. Do not create workflow artefacts solely to satisfy this command.
+## Constraints
+- 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.
+- Treat the finalizer exit code and public status as authoritative.
 
-Policies: `01-BRANCH_GATE.md`, `03-QUALITY_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `PROCEDURE_UI_CHECKLIST.md`.
+## Allowed tools
+- read files
+- edit source files
+- execute validation commands
+- generate diffs
+
+## Forbidden actions
+- force pushing to remote
+- committing directly to main/master branch
+- bypassing quality gates
+
+## 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.
+
+## Safety gates
+- Enforce branch gate safety.
+- Verify changes do not conflict with existing behaviors.
+
+## Validation requirements
+- Code must pass linter checks and all relevant tests.
+
+## Expected output schema
+Output must include:
+- Changed files list
+- Code diff summary
+- Validation logs
+- Hand-off notes
+- Decision: COMPLETED | FAILED
+
+## Evidence required
+- git diff output
+- test log results
+- linter output
+
+## Failure behavior
+- Log implementation failure to ledger and exit.
+
+## Stop conditions
+- compilation error
+- test validation fails
+- change exceeds defined scope

package/dist-assets/commands/optimize-tokens.md

@@ -1,10 +1,66 @@
 ---
 name: optimize-tokens
-description: Reduce workflow context without weakening safety.
+description: Optimize context window size by analyzing and cleaning up logs and cache
 ---
 
-# /optimize-tokens
+# Optimize Tokens Command PromptContract
 
-Remove duplicated prose and unnecessary artefacts. Preserve branch safety, required validation, bounded remediation, and truthful reporting.
+## Role
+Optimizes context size by removing redundant temporary files.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Analyze token usage and suggest/apply context file compactions.
+
+## Trusted context
+- Codebase files
+- Log history files
+- Token estimation stats
+
+## User input / arguments
+- Target directories for analysis
+
+## Preconditions
+- Read access to codebase files
+
+## Constraints
+- Do not delete critical history or validation evidence files.
+- Do not claim optimization without size reduction evidence.
+
+## Allowed tools
+- read files
+- analyze token usage
+- remove caches and temporary files
+
+## Forbidden actions
+- deleting active source code files
+- overwriting configuration files
+
+## Workflow steps
+1. Scan workspace for redundant caches, logs, and temp files.
+2. Measure current context token usage.
+3. Suggest or apply compaction of large files.
+4. Output context optimization report.
+
+## Safety gates
+- Enforce safety rules protecting source code and git history.
+
+## Validation requirements
+- Verify remaining file structures are intact after cleanup.
+
+## Expected output schema
+Output must include:
+- Directories cleaned
+- Token count before and after
+- Cache files removed
+- Decision: COMPLETED | FAILED
+
+## Evidence required
+- token measurement output
+- file size comparisons
+
+## Failure behavior
+- Log failed optimization status and exit.
+
+## Stop conditions
+- deletion of critical active source code attempted
+- clean command fails

package/dist-assets/commands/plan.md

@@ -1,10 +1,70 @@
 ---
 name: plan
-description: Create a proportionate implementation plan.
+description: Plan a software change, defining steps, risks, and validation
 ---
 
-# /plan
+# Plan Command PromptContract
 
-Define scope, risks, steps, validation, and stop conditions. Use a mini plan for small work and formal planning only when risk justifies it.
+## Role
+Coordinates technical planning and PR sequencing under Orion.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Convert requirements into an implementation plan defining steps, risks, and validation.
+
+## Trusted context
+- Codebase source files
+- Requirements specification
+- Project memory and ADRs
+
+## User input / arguments
+- Natural-language feature request or requirement document
+
+## Preconditions
+- Read access to codebase files
+
+## Constraints
+- Plans must identify all risk areas.
+- Plans must define explicit validation steps.
+- Do not claim planning execution without technical plan evidence.
+
+## Allowed tools
+- read files
+- inspect dependency logs
+- write plan files
+
+## Forbidden actions
+- direct source code edits
+- force committing files
+
+## Workflow steps
+1. Review requirements specification.
+2. Map dependencies and codebase locations.
+3. Outline implementation steps.
+4. Assess technical risks and mitigations.
+5. Define testing and validation requirements.
+
+## Safety gates
+- Enforce strict read-only execution during planning.
+
+## Validation requirements
+- Technical plan must comply with the plan schema.
+
+## Expected output schema
+Output must include:
+- Requirements mapping
+- Architectural changes
+- Step-by-step implementation tasks
+- Risk assessment
+- Test and validation plan
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- technical plan file created
+- schema validation status
+
+## Failure behavior
+- Log planning failure to ledger and exit.
+
+## Stop conditions
+- scope is ambiguous
+- required input missing

package/dist-assets/commands/release.md

@@ -1,12 +1,83 @@
 ---
 name: release
-description: Prepare release readiness without publishing automatically.
+description: Prepare local repository for next release with validations and evidence
 ---
 
-# /release
+# Release Command PromptContract
 
-Require clean branch state, successful required validation, safe package checks, changelog/version consistency, and explicit approval before tag, publish, or release.
+## Role
+Prepares the local repository for release, verifies package, and documents evidence.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Coordinate the release process, verifying package status and generating release evidence.
 
-Policies: `01-BRANCH_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `07-RELEASE_GATE.md`.
+## Trusted context
+- Package metadata
+- CHANGELOG.md
+- Repository git log
+- Staging environment status
+
+## User input / arguments
+- Target version release parameters
+- Release details description
+
+## Preconditions
+- Clean working tree
+- Main/master branch is targeted
+
+## Constraints
+- 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.
+
+## Allowed tools
+- read version configuration
+- update changelog
+- generate tarball and calculate sha256 checksum
+- run release validations
+
+## Forbidden actions
+- npm publish without explicit user approval
+- git push without explicit user approval
+- git tag without explicit user approval
+- gh release create without explicit user approval
+
+## Workflow steps
+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.
+
+## Safety gates
+- Enforce release gate validation rules.
+- Verify branch rules.
+
+## Validation requirements
+- Package must pass release readiness validation.
+
+## Expected output schema
+Output must include:
+- Release version target
+- Commit hash
+- Clean working tree status
+- Tarball filename
+- Tarball SHA-256
+- npm publish status
+- git tag status
+- remote push status
+- Decision: publish-ready pending approval | BLOCKED
+
+## Evidence required
+- changelog updates diff
+- release verification logs
+- tarball checksum
+
+## Failure behavior
+- Block release preparation, log failure to ledger, and exit with status 1.
+
+## Stop conditions
+- working tree is dirty
+- validation checks fail
+- user denies approval

package/dist-assets/commands/run.md

@@ -1,26 +1,72 @@
 ---
-description: Run the safest proportionate workflow for an approved task.
-agent: atlas
+name: run
+description: Execute the master AI Workflow pipeline and coordinate agents
 ---
 
-# Run
+# Run Command PromptContract
 
-## Task
+## Role
+Coordinates the main orchestration pipeline for AI Workflow Kit.
 
-Route and execute the approved task using the lowest safe workflow mode.
+## Objective
+Coordinate the execution of the workflow pipeline, executing branch validation, specifications, implementation, validation, and healing.
 
-## Required behavior
+## Trusted context
+- Project configurations (opencode.jsonc)
+- Ledgers and evidence logs
+- Current git status
 
-- enforce protected-branch safety before writes;
-- use project context and the closest domain profile;
-- delegate proportionately, not ceremonially;
-- run relevant validation from the project;
-- block false success when validation fails or is unavailable;
-- use bounded remediation and stop on no progress;
-- persist evidence only for full, release, audit, security, or explicitly requested work.
+## User input / arguments
+- Natural-language request
 
-## Output
+## Preconditions
+- System initialized
+- Active branch status verified
 
-Return a concise delivery summary: status, branch, changed areas, observed validation, limitations, and next action when needed.
+## Constraints
+- Do not run pipeline on main branch if it modifies codebase.
+- Enforce strict state transitions.
+- Do not claim execution without ledger evidence.
 
-Policies: `01-BRANCH_GATE.md`, `03-QUALITY_GATE.md`, `05-AGENT_CONTRACT.md`, `06-FINAL_EVIDENCE_CONTRACT.md`.
+## Allowed tools
+- execute subprocess commands
+- run validation suite
+- coordinate subagent delegation
+
+## Forbidden actions
+- force pushing to remote
+- editing files in read-only mode
+
+## Workflow steps
+1. Validate branch rules and check workspace status.
+2. Route natural request to resolved agent.
+3. Plan and write technical specifications.
+4. Implement modifications incrementally.
+5. Run validations and compile evidence report.
+6. Trigger remediation loop if validation fails.
+
+## Safety gates
+- Enforce branch gate and quality gate check steps.
+
+## Validation requirements
+- Execute all package validators.
+
+## Expected output schema
+Output must include:
+- Request summary
+- Executed steps checklist
+- Test and validation exit codes
+- Findings report
+- Decision: COMPLETED | FAILED | BLOCKED
+
+## Evidence required
+- validation reports
+- git logs
+- execution transcripts
+
+## Failure behavior
+- Log failure to ledger, roll back to last safe state if needed, and exit.
+
+## Stop conditions
+- quality gate check fails and healing fails
+- branch gate violation detected

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

@@ -1,10 +1,72 @@
 ---
 name: spec-create
-description: Create a specification proportionate to scope.
+description: Create technical and functional specifications before implementation
 ---
 
-# /spec-create
+# Spec Create Command PromptContract
 
-Capture objective, scope, constraints, acceptance criteria, risks, and validation. Avoid ceremony for small work.
+## Role
+Coordinates specification creation under Nexus.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Convert customer requirements into detailed functional and technical specifications.
+
+## Trusted context
+- Requirements specification
+- Project memory and ADRs
+- Stack limitations
+
+## User input / arguments
+- Requirement document path
+- Spec template parameters
+
+## Preconditions
+- Read access to requirements files
+
+## Constraints
+- Specifications must define clear test plans.
+- Do not modify codebase during specification creation.
+- Do not claim spec creation without spec file evidence.
+
+## Allowed tools
+- read files
+- write spec markdown files
+- check schema compliance
+
+## Forbidden actions
+- editing source code files
+- bypassing design principles
+
+## Workflow steps
+1. Parse requirement document.
+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.
+
+## Safety gates
+- Enforce read-only constraint during spec creation.
+
+## Validation requirements
+- Verify spec matches specification schemas.
+
+## Expected output schema
+Output must include:
+- Spec path created
+- Problem statement
+- Scope and non-goals
+- Requirements detailed
+- Test plan
+- Decision: PASS | BLOCKED
+
+## Evidence required
+- created spec file contents
+- schema validation status
+
+## Failure behavior
+- Report specification failure and exit.
+
+## Stop conditions
+- requirements are contradictory
+- scope is undefined

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

@@ -1,10 +1,74 @@
 ---
 name: spec-implement
-description: Implement an approved specification safely.
+description: Implement approved specifications incrementally
 ---
 
-# /spec-implement
+# Spec Implement Command PromptContract
 
-Enforce branch safety, implement incrementally, run relevant validation, remediate bounded findings, and return concise evidence.
+## Role
+Guides Astra in implementing approved technical specifications.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Implement code changes that satisfy the criteria defined in the specification.
+
+## Trusted context
+- Approved specification file
+- Source code files
+- Test configurations
+
+## User input / arguments
+- Specification path
+
+## Preconditions
+- Branch safety gate passed
+- Spec approval verified
+
+## Constraints
+- Modifications must strictly follow spec guidelines.
+- Do not implement out-of-scope code.
+- Do not claim implementation without validation evidence.
+
+## Allowed tools
+- read files
+- edit source files
+- run tests
+- check git diff
+
+## Forbidden actions
+- modifying files outside spec scope
+- bypassing quality checks
+- committing to main/master branch
+
+## Workflow steps
+1. Parse technical specification and implementation steps.
+2. Modify codebase source files incrementally.
+3. Run local unit and integration tests.
+4. Verify changes meet acceptance criteria.
+5. Create implementation report.
+
+## Safety gates
+- Enforce branch gate safety.
+- Verify changes do not introduce regressions.
+
+## Validation requirements
+- Code must pass linter and test suite.
+
+## Expected output schema
+Output must include:
+- Spec path processed
+- Modified files list
+- Code diff summary
+- Local test execution logs
+- Decision: COMPLETED | FAILED
+
+## Evidence required
+- git diff
+- test execution logs and exit codes
+
+## Failure behavior
+- Log implementation failure to ledger, clean working tree, and exit.
+
+## Stop conditions
+- test suite fails
+- compilation error
+- spec instructions are contradictory

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

@@ -1,10 +1,69 @@
 ---
 name: spec-review
-description: Review specification readiness.
+description: Review specifications for scope, risks, gaps, and criteria compliance
 ---
 
-# /spec-review
+# Spec Review Command PromptContract
 
-Find ambiguity, missing acceptance criteria, unsafe assumptions, scope creep, and validation gaps. Do not rewrite the spec unless requested.
+## Role
+Coordinates specification auditing and review under Nexus.
 
-Core rules: never write on protected branches, never skip relevant validation, never report false success.
+## Objective
+Verify that specifications meet structural quality criteria and cover all requirements.
+
+## Trusted context
+- Codebase source files
+- Specification file under review
+- Requirements document
+
+## User input / arguments
+- Specification path
+- Requirements path
+
+## Preconditions
+- Spec file exists and is readable
+
+## Constraints
+- Do not modify specifications or code during review.
+- Do not claim review execution without review report evidence.
+
+## Allowed tools
+- read files
+- check schema compliance
+- write review report
+
+## Forbidden actions
+- editing source files
+- bypass safety validations
+
+## Workflow steps
+1. Parse requirement document and spec file.
+2. Check that the spec covers all requirements.
+3. Verify the spec functional details and test plan.
+4. Assess technical risks and completeness.
+5. Create specification review report.
+
+## Safety gates
+- Enforce strict read-only execution.
+
+## Validation requirements
+- Verify spec matches structural specifications schema.
+
+## Expected output schema
+Output must include:
+- Specification reviewed path
+- Requirements coverage checklist
+- Risk assessment findings
+- Quality gaps list
+- Decision: APPROVED | REJECTED
+
+## Evidence required
+- review report file created
+- schema checks status
+
+## Failure behavior
+- Log failed review status to ledger and exit.
+
+## Stop conditions
+- spec file is unreadable
+- required input missing