@williambeto/ai-workflow 1.19.0 → 2.1.0

package/dist-assets/examples/autopilot-cycle/03-orion-planning.md

@@ -0,0 +1,20 @@
+# Technical Plan & PR Breakdown - Orion
+
+## 1. Technical Strategy
+- Create `CategoryFilter.vue` component.
+- Update `ProductStore.ts` to include category filter logic.
+- Use `computed` properties for real-time reactive filtering.
+
+## 2. PR Breakdown
+- **PR 1**: `ProductStore` logic + Unit tests.
+- **PR 2**: `CategoryFilter` UI component.
+- **PR 3**: Dashboard integration + E2E tests.
+
+---
+
+##  Gate B Self-Review (Orion)
+- [x] Plan is atomic and sequential.
+- [x] No broad refactoring included.
+- [x] Testing strategy defined.
+
+**Status**: Ready for Implementation (Astra)

package/dist-assets/examples/autopilot-cycle/04-astra-implementation.md

@@ -0,0 +1,17 @@
+# Implementation Log - Astra
+
+**Task**: PR 1 - ProductStore logic + Unit tests.
+
+##  Actions Taken
+- Added `selectedCategory` state to `ProductStore.ts`.
+- Implemented `setCategory(id)` action.
+- Updated `filteredProducts` getter to include category logic.
+- Created `tests/store/ProductStore.spec.ts`.
+
+##  Local Verification
+- `npm test` passed.
+- Lint clean.
+
+---
+##  Ready for Audit (Sage)
+- Handoff file generated: `HANDOFF-PR1.md`

package/dist-assets/examples/autopilot-cycle/05-sage-validation.md

@@ -0,0 +1,15 @@
+# Validation Report - Sage
+
+**Timestamp**: 2026-05-29T11:00:00Z
+**Agent**: Sage (Auditor)
+
+##  Quality Dimensions
+1. **Correctness**: [PASS] - Logic matches spec.
+2. **Maintainability**: [PASS] - Clean separation of concerns.
+3. **Validation**: [PASS] - New unit tests cover category filtering.
+4. **No regression**: [PASS] - Existing search tests still pass.
+
+---
+##  Gate C Verdict
+**Status**: [APPROVED]
+**Evidence Artifact**: `EVIDENCE.json` updated with test logs.

package/dist-assets/examples/autopilot-cycle/06-phoenix-healing.md

@@ -0,0 +1,12 @@
+# Healing Log (Simulation) - Phoenix
+
+**Event**: Validation Failed (Step 5 retry 1).
+**Root Cause**: CSS collision in category dropdown.
+
+##  Phoenix Action
+1. Analyzed `CategoryFilter.vue` vs global `reset.css`.
+2. Found conflicting `z-index`.
+3. Applied scoped CSS fix.
+4. Requested re-validation from Sage.
+
+**Status**: [HEALED]

package/dist-assets/examples/autopilot-cycle/07-orchestration-report.md

@@ -0,0 +1,18 @@
+# Orchestration Report - Orion
+
+**Task**: Product Category Search Filter.
+**Status**: [COMPLETE]
+
+##  Lifecycle Summary
+1. **Planning**: 20 mins (Orion).
+2. **Implementation**: 45 mins (Astra).
+3. **Audit**: 10 mins (Sage).
+4. **Healing**: 5 mins (Phoenix).
+
+##  Final Evidence
+- Total PRs: 3 (PR 1 merged).
+- Test Coverage: +5%.
+- Evidence Pack: `EVIDENCE.json`.
+
+---
+*Maintained by Atlas — The Senior Engineering Partner*

package/dist-assets/examples/backend-api/00-CONTEXT.md

@@ -0,0 +1,12 @@
+# Backend API Example - Product Management
+
+## 0. Context
+This example demonstrates how to use the AI Workflow Kit for backend development using Node.js, Fastify, and a Repository Pattern.
+
+## The Request
+**User**: "Create a secure API for managing products with CRUD operations and category-based searching."
+
+## Key Learning Points
+- **Schema Validation**: Using Zod for request/response contracts.
+- **Architecture**: Separating Routes, Services, and Repositories.
+- **Quality**: Integration testing with Supertest.

package/dist-assets/examples/backend-api/01-requirement.md

@@ -0,0 +1,19 @@
+# Requirement: Product CRUD API
+
+## 1. Goal
+Provide a set of REST endpoints to manage a product catalog.
+
+## 2. Requirements
+- **Create**: POST `/products` with name, price, and category.
+- **Read**: GET `/products/:id` and GET `/products` (with filtering).
+- **Update**: PUT `/products/:id`.
+- **Delete**: DELETE `/products/:id`.
+- **Search**: Support query param `?category=electronics`.
+
+## 3. Constraints
+- Use Fastify for performance.
+- Validate all inputs using Zod.
+- Use an in-memory repository for this MVP.
+
+---
+*Status: [APPROVED]*

package/dist-assets/examples/backend-api/02-functional-spec.md

@@ -0,0 +1,20 @@
+# Functional Specification: Product API
+
+## 1. Interface (Contract)
+
+### POST /products
+- **Input**: `{ "name": string, "price": number, "category": string }`
+- **Output**: `201 Created` with the product object including a generated UUID.
+
+### GET /products
+- **Query**: `?category=[string]`
+- **Output**: Array of products.
+
+## 2. Business Rules
+- Product name must be at least 3 characters.
+- Price must be positive.
+- Categories are case-insensitive.
+
+## 3. Error Handling
+- `400 Bad Request` for validation failures (Zod errors).
+- `404 Not Found` for missing IDs.

package/dist-assets/examples/backend-api/03-technical-plan.md

@@ -0,0 +1,15 @@
+# Technical Plan - Product API
+
+## 1. Architecture
+- **Layer 1: Routes** (Fastify handlers).
+- **Layer 2: Services** (Business logic + validation).
+- **Layer 3: Repository** (Persistence interface).
+
+## 2. Tech Stack
+- Fastify.
+- Zod (Validation).
+- Vitest (Testing).
+
+## 3. Design Trade-offs
+- **In-memory repo**: Chosen for speed of MVP. Will require a database migration (SQL/NoSQL) in the future.
+- **Zod schemas**: Used both for request validation and type inference.

package/dist-assets/examples/backend-api/04-pr-breakdown.md

@@ -0,0 +1,10 @@
+# PR Breakdown - Product API
+
+## Sequence
+1. **PR 1: Core Definitions**: Zod schemas and Repository interface.
+2. **PR 2: Base CRUD**: Create and Read implementations.
+3. **PR 3: Search & Filters**: Query parameters logic.
+4. **PR 4: Error Handling**: Global Fastify error handler.
+
+---
+*Managed by Orion (Strategist)*

package/dist-assets/examples/backend-api/05-execution-handoff.md

@@ -0,0 +1,13 @@
+# Execution Handoff - PR 1
+
+**Agent**: Astra (Developer)
+**Task**: PR 1 (Schemas + Repo).
+
+## Changes
+- Created `src/domain/product.schema.ts`.
+- Created `src/repositories/product.repository.ts`.
+- Created `src/repositories/memory/product.inmemory.repo.ts`.
+
+## Verification Done
+- Unit tests passed for in-memory storage.
+- Schema validation covers all business rules.

package/dist-assets/examples/backend-api/06-validation-report.md

@@ -0,0 +1,11 @@
+# Validation Report - Sage
+
+**Target**: PR 1.
+
+## Audit Findings
+- **Security**: [PASS] - No injection risks found.
+- **Contract Compliance**: [PASS] - API matches spec exactly.
+- **Test Coverage**: 95% on repository logic.
+
+## Evidence
+`EVIDENCE.json` generated.

package/dist-assets/examples/backend-api/07-orchestration-report.md

@@ -0,0 +1,7 @@
+# Orchestration Report - Product API
+
+**Status**: PR 1 Merged.
+**Current Mission**: Moving to PR 2 (CRUD Implementation).
+
+---
+*Maintained by Atlas*

package/dist-assets/examples/blocked-scenarios/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# Blocked Scenarios - Understanding the Gates
+
+## 0. Context
+This example demonstrates the defensive nature of the AI Workflow Kit. It shows what happens when a developer (human or agent) attempts to bypass the engineering standards and how the Atlas gates protect the repository.
+
+---
+
+## The Request
+**Astra**: "I'm going to quickly fix this bug directly on `main` branch to save time."

package/dist-assets/examples/blocked-scenarios/01-branch-gate-block.md

@@ -0,0 +1,12 @@
+# 01 - Branch Gate Block
+
+**Agent**: Atlas (Orchestrator)
+**Command**: `ai-workflow run`
+
+##  Gate A Evaluation
+- **Current Branch**: `main`
+- **Rule**: `01-BRANCH_GATE.md` - Direct modification to `main` is strictly prohibited.
+
+##  Verdict
+**Status**: [BLOCKED]
+**Message**: "You are currently on the 'main' branch. Engineering governance requires all changes to occur in feature branches. Please create a branch (e.g., `git checkout -b fix/issue`) before proceeding."

package/dist-assets/examples/blocked-scenarios/02-quality-gate-block.md

@@ -0,0 +1,13 @@
+# 02 - Quality Gate Block
+
+**Agent**: Sage (Auditor)
+**Event**: Implementation Handoff review.
+
+##  Gate C Evaluation
+- **Task**: Implement search logic.
+- **Evidence Provided**: None.
+- **Rule**: `03-QUALITY_GATE.md` - No success claim is valid without physical evidence (`EVIDENCE.json`).
+
+##  Verdict
+**Status**: [BLOCKED]
+**Message**: "Implementation rejected. You claimed success but failed to provide an updated EVIDENCE.json with test logs. Audit cannot proceed without verification data."

package/dist-assets/examples/blocked-scenarios/03-scope-creep-block.md

@@ -0,0 +1,13 @@
+# 03 - Scope Creep Block
+
+**Agent**: Atlas (Orchestrator)
+**Gate**: B (Pre-Implementation)
+
+##  Gate B Evaluation
+- **Approved PR**: "Fix typo in login screen".
+- **Astra Plan**: "Fix typo, refactor the entire auth service, and upgrade Nuxt".
+- **Rule**: `ORCHESTRATION_PROTOCOL.md` - No unrelated refactors allowed in a feature branch.
+
+##  Verdict
+**Status**: [BLOCKED]
+**Message**: "Scope Creep detected. Your plan includes changes outside the approved requirement. Refactoring the auth service and upgrading Nuxt must be handled as separate requirements. Re-align your plan with the original PR scope."

package/dist-assets/examples/blocked-scenarios/04-unblock-resolution.md

@@ -0,0 +1,9 @@
+# 04 - Unblock Resolution Path
+
+## How to resolve a Block
+- **Branch Gate**: Run `git checkout -b <name>` and restart the command.
+- **Quality Gate**: Run your tests, update `EVIDENCE.json`, and re-submit the handoff.
+- **Scope Creep**: Remove unrelated changes from your plan and only focus on the specific PR task.
+
+---
+*Status: Understanding restored.*

package/dist-assets/examples/blocked-scenarios/05-orchestration-decision-log.md

@@ -0,0 +1,11 @@
+# 05 - Orchestration Decision Log
+
+**Project**: Secure Dashboard.
+**Overall Status**: [RESOLVED] after 3 blocks.
+
+## Lessons Learned
+- **Astra**: "I learned that speed is not a substitute for quality. The gates forced me to follow the correct protocol, which saved us from a broken deployment."
+- **Atlas**: "Enforcing the gates maintained the integrity of the `main` branch despite high pressure."
+
+---
+*Maintained by Atlas — The Governance Partner*

package/dist-assets/examples/bugfix-critical/00-CONTEXT.md

@@ -0,0 +1,12 @@
+# Bugfix Critical - Authentication Regression
+
+## 0. Context
+This example demonstrates how the AI Workflow Kit handles emergency fixes and regressions using a hypothesis-led approach and the Phoenix healing agent.
+
+## The Problem
+Users report that they are suddenly unable to log in, receiving a generic "Network Error" after the latest deployment.
+
+## Workflow Path
+1. **Bug Report**: Collecting user symptoms.
+2. **Diagnosis**: Identifying the root cause (JWT expiration).
+3. **Healing**: Applying the fix and validating the recovery.

package/dist-assets/examples/bugfix-critical/01-bug-report.md

@@ -0,0 +1,11 @@
+# 01 - Bug Report: Login Failure Regression
+
+## 1. Description
+Login functionality is broken on the production environment.
+
+## 2. Evidence
+- **Log**: `TypeError: Cannot read property 'id' of undefined at auth.middleware.ts:45`.
+- **Environment**: Production (current release).
+
+## 3. Severity
+ [CRITICAL] - Complete service blockage.

package/dist-assets/examples/bugfix-critical/02-diagnosis-hypothesis.md

@@ -0,0 +1,11 @@
+# 02 - Diagnosis & Hypothesis
+
+## 1. Analysis
+The error occurs in the authentication middleware. It seems the user object is not being correctly decoded from the JWT token.
+
+## 2. Hypothesis
+A recent change in the JWT secret environment variable configuration caused old tokens to be invalid, but the error handling does not catch the "invalid signature" state, leading to a crash.
+
+## 3. Verification Plan
+- [x] Reproduce locally by forcing an invalid signature.
+- [ ] Verify if `process.env.JWT_SECRET` is correctly loaded.

package/dist-assets/examples/bugfix-critical/03-technical-plan.md

@@ -0,0 +1,12 @@
+# 03 - Technical Plan: Authentication Fix
+
+## 1. Mitigation
+Add a explicit try-catch block around the JWT verification logic.
+
+## 2. Implementation
+- Wrap `jwt.verify()` in a try-catch.
+- If it fails, return a `401 Unauthorized` with a clear message instead of crashing.
+- Log the specific error (expired, invalid signature, etc.) for internal telemetry.
+
+## 3. Rollback Plan
+Revert to the previous known-good release if this fix does not resolve the crash within 10 minutes of deploy.

package/dist-assets/examples/bugfix-critical/04-implementation-handoff.md

@@ -0,0 +1,8 @@
+# 04 - Implementation Handoff
+
+**Agent**: Phoenix (Healer)
+**Status**: Fix Applied.
+
+## Changes
+- Modified `src/middleware/auth.ts`.
+- Added unit test case for "Malformed Token" and "Invalid Secret".

package/dist-assets/examples/bugfix-critical/05-validation-report.md

@@ -0,0 +1,10 @@
+# 05 - Validation Report
+
+**Agent**: Sage (Auditor)
+
+## Verification
+- **Unit Tests**: [PASS] (New cases covered).
+- **Manual Regression**: [PASS] (Login now returns 401 instead of crashing).
+
+---
+**Verdict**:  [STABLE]

package/dist-assets/examples/bugfix-critical/06-orchestration-report.md

@@ -0,0 +1,7 @@
+# 06 - Orchestration Report
+
+**Issue**: Critical Login Regression.
+**Outcome**: Resolved in 15 mins.
+
+---
+*Maintained by Atlas*

package/dist-assets/examples/cli-package/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# CLI Package - Dogfooding Example
+
+## 0. Context
+This example demonstrates how to use the AI Workflow Kit for developing a Node.js library or CLI tool, focusing on semantic versioning and changelog management.
+
+---
+
+## The Request
+**User**: "I want to add a new command `ai-workflow doctor` to the CLI package to help users diagnose installation issues."

package/dist-assets/examples/cli-package/01-requirement.md

@@ -0,0 +1,14 @@
+# 01 - Requirement: Doctor Command
+
+## 1. Goal
+Provide a built-in diagnostic tool for the CLI.
+
+## 2. Requirements
+- Command: `ai-workflow doctor`.
+- Checks for `.ai-workflow.json` presence.
+- Validates `opencode.jsonc` format.
+- Checks if necessary agents are registered.
+- Reports [PASS/FAIL] for each step.
+
+---
+*Status: [APPROVED]*

package/dist-assets/examples/cli-package/02-technical-spec.md

@@ -0,0 +1,16 @@
+# 02 - Technical Specification
+
+**Agent**: Nexus (Spec Architect)
+
+## 1. Interface
+- New command added to `bin/ai-workflow.js`.
+- Logic implemented in `src/commands/doctor.js`.
+
+## 2. Validation Logic
+- **Check 1**: Check if `cwd` has `.ai-workflow.json`.
+- **Check 2**: Parse `opencode.jsonc` and verify if it has at least the `Atlas` agent.
+- **Check 3**: Verify if `templates/` directory is not empty.
+
+## 3. Exit Codes
+- `0`: All checks passed.
+- `1`: One or more failures detected.

package/dist-assets/examples/cli-package/03-technical-plan.md

@@ -0,0 +1,12 @@
+# 03 - Technical Plan
+
+**Agent**: Orion (Strategist)
+
+## 1. Implementation Detail
+- Use `node:fs` for path checks.
+- Use `JSON.parse` with comment stripping for `opencode.jsonc`.
+- Output formatted using ANSI colors (Chalk).
+
+## 2. Test Plan
+- Create mock project structures (one valid, one broken).
+- Run `doctor` against mocks and verify exit codes.

package/dist-assets/examples/cli-package/04-pr-breakdown.md

@@ -0,0 +1,9 @@
+# 04 - PR Breakdown
+
+**Sequence**:
+1. **PR 1**: `src/commands/doctor.js` logic + Mocks.
+2. **PR 2**: `bin/ai-workflow.js` wiring.
+3. **PR 3**: Update `CHANGELOG.md` for v2 release.
+
+---
+*Ready for Astra*

package/dist-assets/examples/cli-package/05-release-report.md

@@ -0,0 +1,15 @@
+# 05 - Release Report (v2)
+
+**Agent**: Orion (Strategist)
+
+##  Version Bump
+- New Version: `3.1.0`.
+- Type: `minor` (New feature: Doctor command).
+
+##  Changelog Entry
+### Added
+- `ai-workflow doctor`: A diagnostic tool to verify project integrity and OpenCode configuration.
+
+##  Deployment Status
+- Tarball generated: [SUCCESS].
+- Published to NPM (simulated): [SUCCESS].

package/dist-assets/examples/docs-only-repo/01-requirement.md

@@ -0,0 +1,31 @@
+# Requirement
+
+## Title
+Add API Authentication Documentation
+
+## Problem
+The project has authentication endpoints but no clear documentation for request/response, headers, and common errors.
+
+## Target user
+Developers integrating with the API.
+
+## Goal
+Provide clear and testable API auth docs to reduce integration errors.
+
+## Scope
+### Included
+- Authentication overview
+- Login endpoint documentation
+- Token usage examples
+- Common auth error responses
+
+### Not included
+- API behavior changes
+- New endpoints
+- SDK generation
+
+## Acceptance criteria
+- Login endpoint docs include method, path, payload, and response.
+- Auth header usage is documented with examples.
+- 401 and 403 error responses are documented.
+- Documentation is linked from main README.

package/dist-assets/examples/docs-only-repo/02-functional-spec.md

@@ -0,0 +1,25 @@
+# Functional Specification
+
+## Summary
+Define documentation behavior for API authentication usage.
+
+## Main flow
+1. User opens API docs.
+2. User finds authentication section.
+3. User reads login endpoint contract.
+4. User applies token to protected endpoints.
+
+## System states
+- Success examples: valid login and token usage.
+- Error examples: invalid credentials, missing token, expired token.
+
+## Data requirements
+- Endpoint path
+- Request schema
+- Response schema
+- Error payload examples
+
+## Acceptance criteria
+- Auth section is discoverable from docs index.
+- Endpoint examples are copy/paste-safe.
+- Error examples match API contract.

package/dist-assets/examples/docs-only-repo/03-technical-plan.md

@@ -0,0 +1,21 @@
+# Technical Plan
+
+## Current state
+Auth behavior exists but docs are incomplete.
+
+## Proposed changes
+- Update `README.md` docs section link.
+- Add/update `docs/api/auth.md` with endpoint and error contracts.
+- Add validation pass for markdown formatting.
+
+## Files likely to change
+- `README.md`
+- `docs/api/auth.md`
+
+## Validation
+- `npm run validate:md`
+- Manual check of internal links
+
+## Risks
+- Drift between docs and API implementation.
+- Broken links in docs index.

package/dist-assets/examples/docs-only-repo/04-pr-breakdown.md

@@ -0,0 +1,13 @@
+# PR Breakdown
+
+## PR 1 — Add auth endpoint docs
+- Add endpoint contract and examples.
+- Add error response examples.
+
+## PR 2 — Link and polish docs
+- Link docs in README/index.
+- Improve wording and consistency.
+- Run markdown validation.
+
+## Recommended first PR
+PR 1 (highest user value, lowest risk).

package/dist-assets/examples/docs-only-repo/05-execution-handoff.md

@@ -0,0 +1,17 @@
+# Execution Handoff
+
+## Objective
+Implement PR 1: authentication endpoint documentation.
+
+## Scope
+- Add login endpoint docs
+- Add auth header usage
+- Add 401/403 examples
+
+## Validation required
+- Markdown lint passes
+- Links resolve
+- Examples match documented contract
+
+## Out-of-scope follow-up
+If implementation reveals undocumented endpoints, list them as follow-up PR.

package/dist-assets/examples/docs-only-repo/06-validation-report.md

@@ -0,0 +1,16 @@
+# Validation Report
+
+## Summary
+Documentation update validated for format, links, and contract clarity.
+
+## Checks
+- Markdown lint: PASS
+- Internal links: PASS
+- Required sections present: PASS
+
+## Findings
+- No high-severity issues.
+- Optional wording cleanup noted for future pass.
+
+## Final recommendation
+Approved.

package/dist-assets/examples/docs-only-repo/README.md

@@ -0,0 +1,26 @@
+# Docs-Only Repository Example
+
+This example demonstrates a documentation-only workflow using `ai-workflow`.
+
+**Context**: Adding API documentation to an existing project.
+
+## Workflow Summary
+
+| Step | File | Purpose |
+|------|------|---------|
+| Requirement | `01-requirement.md` | Define documentation scope |
+| Specification | `02-functional-spec.md` | Define docs structure and content |
+| Tech Plan | `03-technical-plan.md` | Define file locations and format |
+| 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 the change is purely documentation:
+- README updates
+- API documentation
+- Runbook creation
+- Template changes
+
+The workflow skips implementation steps and focuses on clarity and accuracy.

package/dist-assets/examples/full-stack-checkout/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# Full-Stack Checkout - FE/BE Coordination
+
+## 0. Context
+This example demonstrates how the `Full-Stack-Engineer` agent coordinates complex changes across the frontend (Nuxt UI) and backend (Fastify API).
+
+---
+
+## The Request
+**User**: "Implement a complete checkout button that sends the cart to the server and redirects the user to the Stripe success page."

package/dist-assets/examples/full-stack-checkout/01-requirement.md

@@ -0,0 +1,12 @@
+# 01 - Requirement: Checkout Integration
+
+## 1. Goal
+Connect the frontend cart with the backend payment processing.
+
+## 2. Requirements
+- **Frontend**: "Checkout" button in `Cart.vue`.
+- **Backend**: `POST /checkout` endpoint.
+- **Workflow**: Client sends cart items  Server validates  Server returns Stripe URL  Client redirects.
+
+---
+*Classification: Full-Stack / Intermediate*

package/dist-assets/examples/full-stack-checkout/02-functional-spec.md

@@ -0,0 +1,15 @@
+# 02 - Functional Specification
+
+**Agent**: Nexus (Spec Architect)
+
+## 1. Backend Contract
+- `POST /api/checkout`:
+  - **Body**: `{ items: { id: string, qty: number }[] }`
+  - **Success**: `200 OK` with `{ checkoutUrl: string }`
+  - **Error**: `400 Bad Request` if inventory is insufficient.
+
+## 2. Frontend Behavior
+- User clicks "Checkout".
+- Button shows loading state.
+- If success, `window.location.href` to URL.
+- If failure, show toast notification.