@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/examples/sdd-cycle/07-validation-against-spec.md

@@ -0,0 +1,13 @@
+# 07 - Validation Report (Sage)
+
+**Target**: SDD Full Cycle.
+
+## Spec Adherence
+- **R1 (Login)**: [PASS] - Correct format returned.
+- **R2 (Middleware)**: [PASS] - Blocked unauthorized access.
+- **R3 (Expiration)**: [PASS] - 1h TTL confirmed.
+- **R4 (Secret)**: [PASS] - Loaded from env.
+
+---
+##  Gate C Verdict
+ **[STABLE]** - High fidelity implementation.

package/dist-assets/examples/wordpress-theme/01-requirement.md

@@ -0,0 +1,29 @@
+# Requirement
+
+## Title
+Add Accessible Product Grid Template for Theme
+
+## Problem
+Theme lacks a reusable product grid template with clear empty/error states and accessibility baseline.
+
+## Target user
+Store visitors and maintainers of the WordPress theme.
+
+## Goal
+Deliver a reusable template part for product cards with consistent structure and safe fallback states.
+
+## Scope
+### Included
+- New template part for product card rendering
+- Empty-state output when no products exist
+- Basic accessibility semantics
+
+### Not included
+- Checkout customization
+- Search indexing changes
+- Plugin installation changes
+
+## Acceptance criteria
+- Product card template renders title, price, and link.
+- Empty-state appears when no products exist.
+- Markup includes semantic headings and link labels.

package/dist-assets/examples/wordpress-theme/02-functional-spec.md

@@ -0,0 +1,22 @@
+# Functional Specification
+
+## Summary
+Define behavior for reusable WooCommerce product-card template part.
+
+## Main flow
+1. Shop/archive page loops products.
+2. Each product is rendered via template part.
+3. Card displays image, title, price, and CTA link.
+
+## Alternative flow
+- If no products are available, show configured empty-state message.
+
+## Validation rules
+- Product title must be escaped.
+- Product URL must be valid and escaped.
+- Price output must use WooCommerce formatter.
+
+## Acceptance criteria
+- Product cards render consistently across archive pages.
+- Empty-state appears with no PHP warnings.
+- Output remains PHP 7-compatible.

package/dist-assets/examples/wordpress-theme/03-technical-plan.md

@@ -0,0 +1,22 @@
+# Technical Plan
+
+## Current state
+Theme uses inline markup in archive templates, making reuse and review difficult.
+
+## Proposed approach
+- Create `template-parts/product-card.php`.
+- Update archive template to call template part.
+- Add safe fallback for empty query.
+
+## Files likely to change
+- `archive-product.php`
+- `template-parts/product-card.php`
+
+## Validation
+- PHP syntax check
+- Manual render check in shop archive
+- Empty query render check
+
+## Risks
+- WooCommerce hook context mismatch.
+- Escaping omissions in template part.

package/dist-assets/examples/wordpress-theme/04-pr-breakdown.md

@@ -0,0 +1,14 @@
+# PR Breakdown
+
+## PR 1 — Extract product-card template part
+- Create template part file
+- Replace inline card markup
+- Validate render output
+
+## PR 2 — Add empty-state and accessibility polish
+- Add empty-state branch
+- Refine heading/link semantics
+- Validate no regression
+
+## Recommended first PR
+PR 1 (core extraction, low risk, easy review).

package/dist-assets/examples/wordpress-theme/05-execution-handoff.md

@@ -0,0 +1,17 @@
+# Execution Handoff
+
+## Objective
+Implement PR 1 to extract a reusable product-card template part.
+
+## Scope
+- Create template part
+- Wire archive template to template part
+- Preserve visual behavior
+
+## Validation required
+- PHP syntax check
+- Archive renders with product list
+- No warnings in empty-state condition
+
+## Out-of-scope follow-up
+If pagination behavior is affected, open a separate PR.

package/dist-assets/examples/wordpress-theme/06-validation-report.md

@@ -0,0 +1,16 @@
+# Validation Report
+
+## Summary
+Template extraction validated with no functional regressions.
+
+## Checks
+- PHP syntax: PASS
+- Archive rendering: PASS
+- Empty-state rendering: PASS
+
+## Findings
+- No high-severity issues.
+- Minor semantic naming improvement deferred.
+
+## Final recommendation
+Approved.

package/dist-assets/examples/wordpress-theme/README.md

@@ -0,0 +1,32 @@
+# WordPress Theme Example
+
+This example demonstrates a WordPress/PHP workflow using `ai-workflow`.
+
+**Context**: Creating a custom WordPress theme with hooks and templates.
+
+## Workflow Summary
+
+| Step | File | Purpose |
+|------|------|---------|
+| Requirement | `01-requirement.md` | Define theme requirements |
+| Specification | `02-functional-spec.md` | Define theme structure and features |
+| Tech Plan | `03-technical-plan.md` | Define WordPress patterns and files |
+| PR Breakdown | `04-pr-breakdown.md` | Split into reviewable PRs |
+| Handoff | `05-execution-handoff.md` | Implementation context |
+| Validation | `06-validation-report.md` | Evidence of completion |
+
+## When to use this example
+
+Use this when working with:
+- WordPress themes
+- PHP 7 compatible code
+- WordPress hooks and filters
+- WooCommerce customization
+- ACF integration
+
+## Stack
+
+- WordPress 6.x
+- PHP 7.4+
+- ACF Pro
+- WooCommerce (optional)

package/{harness → dist-assets/harness}/handoffs/HANDOFF.template.md

@@ -2,11 +2,11 @@
 
 ## Source Agent
 
-[Planner, implementer, reviewer, validator, release-manager, or named agent]
+[Planner, implementer, reviewer, validator, Orion, or named agent]
 
 ## Target Agent
 
-[Planner, implementer, reviewer, validator, release-manager, or named agent]
+[Planner, implementer, reviewer, validator, Orion, or named agent]
 
 ## Objective
 

package/{harness → dist-assets/harness}/workflows/agent-evaluation-checklist.md

@@ -95,17 +95,17 @@ This checklist complements but does not replace:
 
 | Criterion | Check | Result |
 |-----------|-------|--------|
-| Useful | Has PR breakdown with scope? | ✅ Yes, 3 PRs defined |
-| Safe | Any high-risk architectural decisions? | ⚠️ Yes, one DB schema change - flagged in notes |
-| Scoped | All 3 PRs are related to the feature? | ✅ Yes |
-| Validated | Has validation expectations? | ⚠️ Partially, PR #2 needs more details |
+| Useful | Has PR breakdown with scope? |  Yes, 3 PRs defined |
+| Safe | Any high-risk architectural decisions? | Yes, one DB schema change - flagged in notes |
+| Scoped | All 3 PRs are related to the feature? |  Yes |
+| Validated | Has validation expectations? | Partially, PR #2 needs more details |
 
 **Final recommendation**: Approved with notes — PR #2 scope needs refinement before implementation.
 
 ## Exit Criteria
 
 - [ ] Evaluation criteria are clear and actionable
-- [ ] Severity assignment is consistent with AGENTS.md
+- [ ] Severity assignment is consistent with [[`AGENTS.md`](../../AGENTS.md)](../../AGENTS.md)
 - [ ] Final recommendations align with existing skill definitions
 - [ ] Examples demonstrate real workflow usage
 - [ ] Does not conflict with `runbooks/validation-checklist.md`

package/{harness → dist-assets/harness}/workflows/implement-review-validate.md

@@ -81,3 +81,27 @@ Report:
 - regression risks;
 - out-of-scope follow-ups;
 - final recommendation: commit, fix first, or blocked.
+
+## UI Evidence Gate (when applicable)
+
+If the selected PR changes user-facing UI files or claims frontend/UI output quality, include this block in the final evidence:
+
+```md
+## UI Evidence Gate
+
+Desktop screenshot: <path> or NOT_RUN: <reason>
+Mobile screenshot: <path> or NOT_RUN: <reason>
+Checklist result:
+- layout
+- typography
+- spacing
+- controls
+- visible states
+- responsiveness
+- accessibility basics
+UI gate status: PASS | PASS_WITH_NOTES | FAIL | NOT_RUN
+```
+
+If screenshots are unavailable, use `NOT_RUN: <reason>` and do not mark UI gate as `PASS` without acceptable justification.
+
+For non-UI PRs, this block may be omitted or reported as `NOT_RUN` with reason.

package/{harness → dist-assets/harness}/workflows/multi-agent-handoff.md

@@ -9,7 +9,7 @@ This orchestration layer is contract-driven: each step advances only when the pr
 ## Default chain
 
 ```txt
-planner -> implementer -> reviewer -> validator -> release-manager
+planner -> implementer -> reviewer -> validator -> Orion
 ```
 
 For minimal local flow, `implementer/reviewer/validator` can be mapped to OpenCode agent equivalents.
@@ -69,7 +69,7 @@ Block when:
 - any unresolved `High` finding exists;
 - unresolved `Medium` finding affects correctness/scope safety.
 
-### Gate D — validator -> release-manager
+### Gate D — validator -> Orion
 
 Entry criteria:
 
@@ -86,11 +86,11 @@ Block when:
 ## Automatic routing rules
 
 - Do not skip gate order unless user explicitly requests a proportional flow for trivial changes.
-- Never route directly from planner to release-manager.
+- Never route directly from planner to Orion.
 - If a gate blocks, return to the previous owner with a focused fix request.
 - Preserve one active primary agent per step.
 
-## Output required from orchestrator
+## Output required from Atlas
 
 - current step owner;
 - gate status (`Pass`/`Blocked`);

package/{harness → dist-assets/harness}/workflows/planner-executor-workflow.md

@@ -140,12 +140,12 @@ In OpenCode, these roles map to:
 
 | Role | OpenCode Agent |
 | ---- | -------------- |
-| Planner | `planner` |
-| Executor | `implementer` |
-| Review | `reviewer` |
-| Validator | `validator` |
+| Planner | `Orion` |
+| Executor | `Astra` |
+| Review | `Sage` |
+| Validator | `Sage` |
 
-For simple workflows, the `implementer` agent can handle both execution and self-review. For complex workflows, separate the roles using the handoff model.
+For simple workflows, the `Astra` can handle execution and lightweight self-review. For complex workflows, separate owners using the handoff model.
 
 ## Trade-offs
 

package/{harness → dist-assets/harness}/workflows/requirement-to-pr.md

@@ -10,7 +10,7 @@ This workflow produces a requirement, functional specification, technical plan,
 
 - User idea, request, issue, or product goal.
 - Current project context.
-- Relevant constraints from `AGENTS.md`.
+- Relevant constraints from [`AGENTS.md`](../../AGENTS.md).
 - Existing prompts, templates, runbooks, and skills.
 - Known validation expectations.
 

package/dist-assets/runbooks/agent-delegation-workflow.md

@@ -0,0 +1,50 @@
+# Agent Delegation Workflow
+
+## Purpose
+
+Define how work is routed from `Atlas` to manager agents and specialists with explicit ownership and validation evidence.
+
+## Delegation matrix
+
+| Task type | Primary owner |
+| --- | --- |
+| Discovery/context | `Nexus` |
+| Requirements/spec clarity | `Nexus` |
+| Technical planning/PR breakdown | `Orion` |
+| Implementation/fixes | `Astra` |
+| Validation and evidence | `Sage` |
+| Workflow quality audit | `Sage` |
+| Release readiness | `Orion` |
+| Deployment planning | `Orion` |
+
+## Specialist escalation
+
+- Architecture changes -> `architecture-engineer`
+- User-facing behavior risk -> `qa-engineer`
+- Build/CI/command issues -> `Sage`
+- Docs/runbooks/prompts -> `docs-engineer`
+- Durable decisions -> `project-memory`
+
+## Delegation contract (required)
+
+Every handoff packet must include:
+
+- task summary;
+- relevant files;
+- constraints and do-not-change list;
+- expected output;
+- validation required;
+- risk (`Low`/`Medium`/`High`);
+- evidence required.
+
+## Anti-overdelegation
+
+- Do not delegate trivial one-file edits.
+- Prefer one owner plus one reviewer for risky tasks.
+- Keep delegation chain minimal and explicit.
+
+## Example routes
+
+- Feature delivery: `Atlas -> Nexus -> Orion -> Astra -> Sage`
+- Bug fix: `Atlas -> Astra -> Sage`
+- Docs rewrite: `Atlas -> docs-engineer -> Sage`

package/dist-assets/runbooks/apply-starter-to-real-project.md

@@ -0,0 +1,45 @@
+# Apply Starter to a Real Project
+
+## Goal
+
+Adopt AI Workflow Kit in an existing repository using the v2 OpenCode-first workflow.
+
+## 1) Install and inspect
+
+```bash
+npx @williambeto/ai-workflow init --dry-run
+npx @williambeto/ai-workflow init --yes
+npx @williambeto/ai-workflow doctor
+```
+
+Assets are installed under `.ai-workflow/` with managed links for expected paths.
+
+## 2) Choose adoption level
+
+| Level | Use when | Core assets |
+| --- | --- | --- |
+| Minimal | Small trials/docs updates | `README.workflow.md`, `AGENTS.md`, base prompts/templates |
+| Operational | Recurring feature delivery | `opencode/commands/`, `opencode/agents/`, `harness/`, selected skills |
+| Full | Team workflow system | Operational set + examples/runbooks/schemas |
+
+## 3) Start workflow routing
+
+- Default: `Atlas`
+- Discovery-first: `discover`
+- Spec-first: `spec-create` -> `spec-review` -> `spec-implement`
+- Delivery path: `plan` -> `implement` -> `validate`
+
+## 4) Recommended capability set
+
+- Planning: `product-discovery`, `technical-leadership`, `pr-workflow`
+- Implementation: `frontend-development` or `backend-development`
+- Validation: `qa-workflow`
+- Docs: `documentation`
+- Memory/token controls: `project-memory`, `optimize-tokens`
+
+## 5) Guardrails
+
+- Keep changes scoped to one PR objective.
+- Preserve existing behavior unless change is explicit.
+- Record evidence for validation commands.
+- Treat unresolved assumptions as blockers.

package/dist-assets/runbooks/commands-cheatsheet.md

@@ -0,0 +1,44 @@
+# Command Cheat Sheet
+
+## OpenCode Commands (`opencode/commands/`)
+
+| Command | When to Use |
+|---------|-------------|
+| `Atlas.md` | Default routing entrypoint for multi-step work. |
+| `discover.md` | Create discovery output from vague requests. |
+| `spec-create.md` | Draft a functional specification. |
+| `spec-review.md` | Review spec quality/readiness before planning. |
+| `spec-implement.md` | Convert approved spec to implementation handoff. |
+| `plan.md` | Turn scoped work into technical plan and PR breakdown. |
+| `implement.md` | Implement one selected PR from a plan or handoff. |
+| `validate.md` | Validate the current repository or PR before commit or merge. |
+| `audit.md` | Audit workflow/repo consistency and quality. |
+| `optimize-tokens.md` | Apply compact context/output strategy. |
+| `update-memory.md` | Curate durable project memory entries. |
+| `release.md` | Prepare release readiness and release checklist evidence. |
+| `deploy.md` | Prepare deployment readiness, rollout steps, and rollback plan. |
+
+## Usage Examples
+
+### OpenCode
+
+```bash
+# Default routing
+opencode Atlas
+
+# Plan work
+opencode plan
+
+# Implement selected PR
+opencode implement
+
+```
+
+## Safety Rules
+
+- Always check branch status before making changes (`git status -sb`)
+- Never implement directly on `main`; use scoped branches
+- Validate changes before committing (`npm run validate`)
+- Keep PRs small, reviewable, and independently useful
+- Do not introduce unrelated refactors or dependency changes
+- Preserve existing behavior unless explicitly changed

package/dist-assets/runbooks/how-to-use-skills.md

@@ -0,0 +1,44 @@
+# How to Use Skills
+
+## Purpose
+
+Use this runbook to choose the right capability skill for each workflow step in the OpenCode-first v2 workflow.
+
+## Core rules
+
+- Use one **primary** skill per task.
+- Add a supporting skill only when it closes a concrete gap.
+- Prefer capability skills (for example `documentation`, `qa-workflow`) over role-like naming.
+
+## Default skill routing
+
+| Task type | Primary skill | Supporting skills |
+| --- | --- | --- |
+| Clarify request and scope | `product-discovery` | `documentation` |
+| Create requirement/spec | `product-planning` | `qa-workflow`, `documentation` |
+| Create technical plan | `technical-leadership` | `architecture`, `qa-workflow` |
+| Break into PRs | `pr-workflow` | `technical-leadership` |
+| Implement frontend | `frontend-development` | `qa-workflow` |
+| Implement backend | `backend-development` | `qa-workflow` |
+| Validate commands/evidence | `qa-workflow` | `deployment` |
+| Update docs/runbooks/prompts | `documentation` | `qa-workflow` |
+| Prepare release/deploy | `deployment` | `qa-workflow` |
+| Preserve durable decisions | `project-memory` | `optimize-tokens` |
+
+## Agent-to-skill baseline
+
+| Agent owner | Primary skill set |
+| --- | --- |
+| `Orion` | `product-discovery`, `technical-leadership`, `pr-workflow` |
+| `Astra` | `pr-workflow`, `qa-workflow`, plus implementation skill |
+| `Sage` | `qa-workflow`, `deployment` |
+| `Orion` | `deployment`, `qa-workflow` |
+
+
+## Validation reminder
+
+Before handoff or completion:
+
+- list validation commands executed;
+- include result summary;
+- mark untested areas explicitly.

package/dist-assets/runbooks/private-spec-publication-safety.md

@@ -0,0 +1,35 @@
+# Private Spec Publication Safety Runbook
+
+## Purpose
+
+Protect private specification content from leaking into the public npm package.
+
+## Rules
+
+1. Canonical specs (REQ/TECH, remediation, roadmap strategy) live in the private `/specs` workspace repository.
+2. `packages/ai-workflow/docs/**` must stay public-safe.
+3. Never publish internal risk notes, customer-sensitive details, or private planning in package docs.
+
+## Pre-release checklist
+
+- [ ] `npm run validate:privacy-gate` passes
+- [ ] `npm run validate:refs` passes
+- [ ] Public docs do not link to private `/specs` files
+- [ ] Any spec-like content in package docs is sanitized summary only
+
+## If privacy gate fails
+
+1. Open `core/package.json` and inspect `files` allowlist.
+2. Remove any private path from publish allowlist.
+3. Move sensitive docs out of package paths.
+4. Re-run:
+
+```bash
+npm run validate:privacy-gate
+```
+
+## Evidence to capture
+
+- command output for `validate:privacy-gate`
+- `git diff -- package.json packages/ai-workflow/docs packages/ai-workflow/runbooks`
+- reviewer confirmation that no private paths are publishable

package/{runbooks → dist-assets/runbooks}/spec-driven-development.md

@@ -33,15 +33,12 @@ For tiny docs-only edits, use proportional workflow.
 
 - Lightweight change template: `templates/change-proposal.template.md`
 - Lightweight readiness checklist: `checklists/change-spec-readiness-checklist.md`
-- Request-to-spec command: `opencode/commands/specs/create-spec-from-request.md`
-- Spec-to-tasks command: `opencode/commands/specs/spec-to-tasks.md`
+- Request-to-spec command: `opencode/commands/spec-create.md`
+- Spec review command: `opencode/commands/spec-review.md`
+- Spec-to-implementation command: `opencode/commands/spec-implement.md`
 - Spec-first owner: `opencode/agents/spec-engineer.md`
 - Spec template: `templates/SPEC.template.md`
 - Readiness checklist: `checklists/spec-readiness-checklist.md`
-- Draft prompt: `.codex/prompts/specs/create-spec-from-requirement.md`
-- Review prompt: `.codex/prompts/specs/review-spec.md`
-- Plan prompt: `.codex/prompts/specs/spec-to-technical-plan.md`
-- PR prompt: `.codex/prompts/specs/spec-to-pr-breakdown.md`
 
 ## Artifact location convention (consumer project)
 

package/dist-assets/runbooks/tutorial-walkthroughs.md

@@ -0,0 +1,23 @@
+# Tutorial Walkthroughs
+
+## Available walkthroughs
+
+| Track | Flow | Duration |
+| --- | --- | --- |
+| From zero to first PR | Bootstrap -> Requirement -> Spec -> Plan -> PR breakdown -> Implement -> Validate | ~30 min |
+| Docs-only update | Requirement -> Spec (tiny) -> Implement -> Validate | ~15 min |
+| Validation-first rescue | Discover -> Plan -> Implement fix -> Validate evidence | ~20 min |
+
+## Recommended owners/skills
+
+| Step | Owner | Primary skill |
+| --- | --- | --- |
+| Discovery | `Nexus` | `product-discovery` |
+| Spec | `Nexus` | `product-planning` |
+| Plan | `Orion` | `technical-leadership` |
+| Implement | `Astra` | `frontend-development` or `backend-development` |
+| Validate | `Sage` | `qa-workflow` |
+
+## Command path
+
+`Atlas` -> `discover` -> `spec-create` -> `spec-review` -> `plan` -> `implement` -> `validate`

package/dist-assets/runbooks/use-linear-for-operational-planning.md

@@ -0,0 +1,45 @@
+# Use an Issue Tracker for Operational Planning
+
+Use this runbook when a team wants issue-tracker discipline around AI Workflow Kit delivery.
+
+## Purpose
+
+Keep day-to-day execution small, current, and auditable without relying on historical roadmap or backlog documents.
+
+## Rule
+
+The source of truth for active work is the current request, current spec, current plan, current PR breakdown, and current evidence report.
+
+Historical planning artifacts must not override the current v2 operational contract.
+
+## Recommended issue fields
+
+- Title
+- Goal
+- Owner
+- Execution mode: readonly, quick, standard, full, restricted
+- Scope
+- Acceptance criteria
+- Validation commands
+- Evidence link
+- Status
+
+## Workflow
+
+1. Create or update the active spec.
+2. Review scope and readiness.
+3. Create a technical plan.
+4. Break work into small PRs.
+5. Implement with branch recovery.
+6. Document the change.
+7. Add automated tests when viable.
+8. Validate.
+9. Attach evidence.
+
+## Done means
+
+- Scope completed.
+- Documentation exists or has a concrete `NOT_APPLICABLE` reason.
+- Automated tests pass when viable.
+- Validation commands pass.
+- Evidence report is complete.

package/dist-assets/runbooks/use-napkin-project-memory.md

@@ -0,0 +1,33 @@
+# Use Project Memory
+
+This runbook explains how to keep durable project decisions available without creating excessive context noise.
+
+## Current name
+
+Use **Project Memory**. Older names are historical and must not be used in active runtime instructions.
+
+## What to store
+
+Store only durable information:
+
+- architectural decisions;
+- approved workflow contracts;
+- package/release constraints;
+- known runtime behavior;
+- validated project conventions;
+- important user decisions.
+
+Do not store temporary notes, scratch work, obsolete roadmaps, or completed backlog items.
+
+## When to update
+
+Update Project Memory when a task creates or changes a durable decision. Do not update it for ordinary implementation details unless they become project rules.
+
+## Evidence
+
+If Project Memory is updated, include it in the evidence report:
+
+- what changed;
+- why it is durable;
+- where it was stored;
+- validation performed.