@williambeto/ai-workflow 1.19.1 → 2.2.0

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.

package/dist-assets/examples/full-stack-checkout/03-technical-plan.md

@@ -0,0 +1,15 @@
+# 03 - Full-Stack Implementation Plan
+
+**Agent**: Full-Stack-Engineer
+
+## 1. Backend Implementation
+- Create `CheckoutController.ts`.
+- Integrate `StripeService`.
+- Add Zod validation for cart items.
+
+## 2. Frontend Implementation
+- Add `checkout` action to `CartStore.ts` using `useFetch`.
+- Update `Cart.vue` to trigger action.
+
+## 3. Coordination Strategy
+We will implement and test the Backend first using Postman/Supertest, then wire the Frontend.

package/dist-assets/examples/full-stack-checkout/04-pr-breakdown.md

@@ -0,0 +1,8 @@
+# 04 - PR Breakdown
+
+**Sequence**:
+1. **PR 1**: Backend - Checkout API + Validation + Tests.
+2. **PR 2**: Frontend - Store action + UI Integration + E2E Tests.
+
+---
+*Ready for Astra*

package/dist-assets/examples/full-stack-checkout/05-execution-handoff.md

@@ -0,0 +1,14 @@
+# 05 - Execution Handoff (Full-Stack)
+
+**Agent**: Full-Stack-Engineer
+**Task**: PR 1 + PR 2.
+
+##  Actions
+- **Backend**: Implemented `POST /api/checkout`.
+- **Frontend**: Updated `CartStore` and added "Checkout" button to `Cart.vue`.
+- **Security**: Added CSRF protection to the checkout endpoint.
+
+##  Verification
+- Backend Supertest: [PASS].
+- Frontend Vitest: [PASS].
+- Playwright E2E: [PASS].

package/dist-assets/examples/full-stack-checkout/06-validation-report.md

@@ -0,0 +1,12 @@
+# 06 - Validation Report (Sage)
+
+**Target**: Full-Stack Checkout integration.
+
+## Quality Dimensions
+- **FE/BE Sync**: [PASS] - Data formats match specification.
+- **Error Handling**: [PASS] - Correctly handles Stripe failures.
+- **Performance**: [PASS] - Redirect happens in < 500ms.
+
+---
+##  Gate C Verdict
+ **[STABLE]**

package/dist-assets/examples/healing-cycle/00-CONTEXT.md

@@ -0,0 +1,15 @@
+# Healing Cycle - Phoenix Path
+
+## 0. Context
+This example demonstrates the autonomous self-healing capability of the AI Workflow Kit. It shows what happens when a human or agent delivers a broken PR and how the system recovers.
+
+## The Scenario
+A developer implemented a new utility function but forgot to export it, causing a compilation error in the tests.
+
+---
+
+## Cycle Sequence
+1. **Sage** detects the failure (test build failed).
+2. **Phoenix** analyzes the error log.
+3. **Phoenix** applies the missing export.
+4. **Sage** re-runs the validation and approves.

package/dist-assets/examples/healing-cycle/01-broken-implementation.md

@@ -0,0 +1,10 @@
+# 01 - Broken Implementation Handoff
+
+**Agent**: Astra (Developer)
+
+## Changes
+- Created `src/utils/format.ts`.
+- Implemented `formatCurrency(val: number)`.
+
+## Error
+Forgot to add `export` keyword to the function.

package/dist-assets/examples/healing-cycle/02-sage-fails.md

@@ -0,0 +1,14 @@
+# 02 - Sage Detection (Failure)
+
+**Agent**: Sage (Auditor)
+**Event**: `npm test` failure detected during Gate C.
+
+## Error Log
+```
+src/utils/format.spec.ts:5:10 - error TS2339: Property 'formatCurrency' does not exist on type 'typeof import("/src/utils/format")'.
+```
+
+## Audit Result
+- **Status**: [FAIL]
+- **Reason**: The function `formatCurrency` exists in `src/utils/format.ts` but is not exported.
+- **Action**: Invoking Phoenix for autonomous healing.

package/dist-assets/examples/healing-cycle/03-phoenix-diagnosis.md

@@ -0,0 +1,17 @@
+# 03 - Phoenix Diagnosis
+
+**Agent**: Phoenix (Healer)
+**Incident**: TS2339 - Missing Export.
+
+## Analysis
+- **File**: `src/utils/format.ts`.
+- **Content**:
+```typescript
+function formatCurrency(val: number) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(val);
+}
+```
+- **Finding**: The function is correctly implemented but is missing the `export` keyword. The test file `src/utils/format.spec.ts` expects it to be available.
+
+## Hypothesis
+Adding `export` before the function definition will resolve the compilation error and satisfy the test requirements.

package/dist-assets/examples/healing-cycle/04-phoenix-fix.md

@@ -0,0 +1,18 @@
+# 04 - Phoenix Fix Applied
+
+**Agent**: Phoenix (Healer)
+**Task**: Apply atomic fix for missing export.
+
+##  Actions
+- Applied `export` to `formatCurrency` in `src/utils/format.ts`.
+
+```typescript
+// src/utils/format.ts
+export function formatCurrency(val: number) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(val);
+}
+```
+
+##  Self-Verification
+- Ran `npx tsc` on the file: [PASS].
+- Requested re-audit from Sage.

package/dist-assets/examples/healing-cycle/05-sage-revalidation.md

@@ -0,0 +1,12 @@
+# 05 - Sage Re-validation (Success)
+
+**Agent**: Sage (Auditor)
+**Event**: Re-validation after healing.
+
+## Audit Result
+- **Tests**: [PASS] - `src/utils/format.spec.ts` executed successfully.
+- **Evidence**: `EVIDENCE.json` updated with positive test logs.
+
+---
+##  Gate C Verdict
+**Status**: [APPROVED] (Self-Healed)

package/dist-assets/examples/healing-cycle/06-orchestration-log.md

@@ -0,0 +1,14 @@
+# 06 - Orchestration Decision Log
+
+**Task**: Utility format function.
+**Status**: [COMPLETE] (Healed)
+
+## Lifecycle Events
+1. **Gate A**: [PASS] - Trivial task.
+2. **Implementation**: [FAIL] - Missing export.
+3. **Audit**: [FAIL] - Compiler error detected.
+4. **Healing**: [PASS] - Phoenix applied fix in 1 loop.
+5. **Re-Audit**: [PASS] - Validation successful.
+
+---
+*Maintained by Atlas — The Self-Healing Partner*

package/dist-assets/examples/infra-deploy/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# Infrastructure & Deploy - Operational Excellence
+
+## 0. Context
+This example demonstrates how the AI Workflow Kit handles infrastructure tasks, such as Dockerization and CI/CD pipeline setup, using the `Deployment-Specialist` agent.
+
+---
+
+## The Request
+**User**: "I want to Dockerize the application and set up a GitHub Action to automatically build and push the image to Docker Hub."

package/dist-assets/examples/infra-deploy/01-operational-goal.md

@@ -0,0 +1,12 @@
+# 01 - Operational Goal: Automated Deployment
+
+## 1. Goal
+Containerize the app and automate the delivery pipeline.
+
+## 2. Success Criteria
+- [ ] Valid `Dockerfile` in root.
+- [ ] `.github/workflows/deploy.yml` created.
+- [ ] Image builds successfully in CI.
+
+## 3. Security
+- Secrets (Docker Hub Token) must be stored in GitHub Secrets, never in plain text.

package/dist-assets/examples/infra-deploy/02-architecture-specs.md

@@ -0,0 +1,15 @@
+# 02 - Architecture Specs
+
+**Agent**: Deployment-Specialist
+**Status**: [APPROVED]
+
+## 1. Container Specs
+- Base Image: `node:20-alpine`.
+- Multi-stage build to reduce final image size.
+- Environment variables injected via `.env` file or CLI.
+
+## 2. CI/CD Specs
+- Trigger: Push to `main` branch.
+- Step 1: Run tests.
+- Step 2: Build Docker image.
+- Step 3: Login and Push to registry.

package/dist-assets/examples/infra-deploy/03-implementation-plan.md

@@ -0,0 +1,14 @@
+# 03 - Implementation Plan
+
+**Agent**: Orion (Strategist)
+
+## 1. Strategy
+We will implement the Dockerfile first and test it locally before creating the GitHub Action.
+
+## 2. Dependencies
+- Docker installed locally for verification.
+- GitHub repository access for secrets setup.
+
+## 3. Risk Mitigation
+- Use a non-root user in Docker for security.
+- Version pin the base image.

package/dist-assets/examples/infra-deploy/04-step-breakdown.md

@@ -0,0 +1,9 @@
+# 04 - Step Breakdown
+
+## Sequence
+1. **Step 1**: Create `.dockerignore` and `Dockerfile`.
+2. **Step 2**: Create `.github/workflows/deploy.yml`.
+3. **Step 3**: Validation run on a test branch.
+
+---
+*Ready for Astra/Deployment-Specialist*

package/dist-assets/examples/infra-deploy/05-execution-handoff.md

@@ -0,0 +1,13 @@
+# 05 - Execution Handoff
+
+**Agent**: Deployment-Specialist
+**Task**: Dockerization.
+
+##  Actions
+- Created `Dockerfile` using multi-stage build.
+- Configured `.dockerignore` to exclude `node_modules`.
+- Created `.github/workflows/deploy.yml` with build-and-push logic.
+
+##  Local Test
+- Image built: [PASS].
+- Container started: [PASS].

package/dist-assets/examples/infra-deploy/06-operational-report.md

@@ -0,0 +1,11 @@
+# 06 - Operational Report
+
+**Task**: CI/CD Automation.
+**Status**: [OPERATIONAL]
+
+## Infrastructure Status
+- Docker Hub Image: `williambeto/example-app:latest` [AVAILABLE].
+- CI/CD Status: [GREEN] (1 successful run).
+
+---
+*Maintained by Atlas — The Operations Partner*

package/dist-assets/examples/multi-pr-release/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# Multi-PR Release - Complex Feature Lifecycle
+
+## 0. Context
+This example shows how to plan and execute a complex feature that requires multiple sequential pull requests. It demonstrates the coordination between Orion (Strategist) and Atlas (Orchestrator) to ensure a safe release.
+
+---
+
+## The Request
+**User**: "I want to implement a complete 'Checkout Flow' including cart management, address selection, and payment integration."

package/dist-assets/examples/multi-pr-release/01-requirement.md

@@ -0,0 +1,13 @@
+# 01 - Requirement: Checkout System
+
+## 1. Goal
+Provide a complete checkout experience for the e-commerce platform.
+
+## 2. Sub-Features
+- **Cart**: Add/remove/update items.
+- **Address**: Save and select shipping addresses.
+- **Payment**: Integrate with Stripe API.
+- **Order History**: Save order after payment.
+
+---
+*Classification: Large / Complex*

package/dist-assets/examples/multi-pr-release/02-strategic-plan.md

@@ -0,0 +1,13 @@
+# 02 - Strategic Tech Plan
+
+**Agent**: Orion (Strategist)
+
+## 1. Release Strategy
+We will use **Feature Flags** to implement the checkout flow in multiple increments without breaking the existing production site.
+
+## 2. Infrastructure Changes
+- New DB tables: `orders`, `addresses`.
+- New environment variables for Stripe integration.
+
+## 3. High-Level Dependency Graph
+Cart Logic  Address Selection  Stripe Integration  Final Order Persistence.

package/dist-assets/examples/multi-pr-release/03-pr-breakdown.md

@@ -0,0 +1,14 @@
+# 03 - Multi-PR Breakdown
+
+**Target Version**: v2.0.0
+
+## PR Sequence
+1. **PR 1**: `CartStore` refactoring + Feature Flag setup.
+2. **PR 2**: Database schema migration (`orders`, `addresses`).
+3. **PR 3**: UI - Shipping Address form + Validation.
+4. **PR 4**: Backend - Stripe API Service integration.
+5. **PR 5**: Final wiring + E2E "Happy Path" tests.
+6. **PR 6**: Enable Feature Flag and release.
+
+---
+*Estimated Duration: 2 sprints*

package/dist-assets/examples/multi-pr-release/04-release-plan.md

@@ -0,0 +1,12 @@
+# 04 - Release Readiness Report
+
+**Agent**: Orion (Strategist)
+**Status**: [READY]
+
+## Evidence Summary
+- [x] All 6 PRs merged and validated by Sage.
+- [x] E2E tests passing on Staging environment.
+- [x] Security audit on Stripe integration: [PASS].
+
+## Rollback Plan
+If v2.0.0 fails, disable Feature Flag `ENABLE_NEW_CHECKOUT` immediately via admin panel.

package/dist-assets/examples/multi-pr-release/05-orchestration-report.md

@@ -0,0 +1,7 @@
+# 05 - Orchestration Report
+
+**Release**: Checkout Flow v2.0.0.
+**Outcome**: Success.
+
+---
+*Maintained by Atlas*

package/dist-assets/examples/nuxt-dashboard/01-requirement.md

@@ -0,0 +1,81 @@
+# Requirement: Products Dashboard Area
+
+## Problem
+
+The dashboard boilerplate needs a realistic protected products area so developers can exercise authenticated data workflows, list filtering, navigation, and CRUD-style UI decisions without connecting to a production backend.
+
+## Goal
+
+Build a protected products CRUD-style dashboard area backed by DummyJSON, with list, search, pagination, product detail, create/edit/delete placeholders, loading states, empty states, error states, and a layout aligned with the existing dashboard design rules.
+
+## Users
+
+- Authenticated dashboard users who need to browse product records.
+- Developers extending the dashboard boilerplate.
+- Reviewers validating that dashboard workflows stay scoped and consistent.
+
+## Scope
+
+- Add a protected products list page.
+- Fetch product data from DummyJSON.
+- Support search and pagination on the list page.
+- Add a product detail page.
+- Add create, edit, and delete entry points as placeholders.
+- Show loading, empty, and error states.
+- Keep the layout consistent with the existing dashboard shell.
+- Preserve route middleware and authentication behavior.
+
+## Out Of Scope
+
+- Real product persistence.
+- Real create, edit, or delete mutations.
+- Role-based product permissions.
+- Offline caching.
+- Bulk actions.
+- Analytics dashboards.
+- Replacing the existing dashboard design system.
+
+## Assumptions
+
+- The Nuxt app already has an authenticated dashboard shell.
+- Route middleware already protects dashboard routes.
+- DummyJSON is acceptable for demo data.
+- Existing components or Nuxt UI primitives should be reused before adding new abstractions.
+- Product mutations can be represented as disabled or non-persistent placeholders.
+
+## Constraints
+
+- Keep changes split into small PRs.
+- Do not introduce new frontend frameworks.
+- Do not add a backend service.
+- Do not store secrets or credentials.
+- Preserve existing dashboard navigation and layout behavior.
+- Keep DummyJSON-specific code inside the products domain or shared HTTP layer.
+
+## Acceptance Criteria
+
+- Authenticated users can open a products list route under the dashboard.
+- The list displays product title, price, category, stock, and thumbnail when available.
+- Users can search products and see updated results.
+- Users can move through paginated results.
+- Users can open a product detail route from the list.
+- Loading, empty, and error states are visible and understandable.
+- Create, edit, and delete controls are present as placeholders without claiming persistence.
+- Unauthenticated users remain blocked by existing dashboard protection.
+- Validation evidence is recorded before each PR is considered complete.
+
+## Risks
+
+| Risk | Impact | Mitigation |
+| ---- | ------ | ---------- |
+| DummyJSON behavior differs from a real API | Future backend migration may require data mapping changes | Keep API access behind a small products repository |
+| Search and pagination can become coupled to page UI | Harder to test or reuse | Keep query state and fetch behavior simple and explicit |
+| Placeholder CRUD actions may mislead users | Users may think data is persisted | Label placeholders clearly in UI and validation notes |
+| Dashboard design may drift | Boilerplate becomes inconsistent | Reuse existing shell and component conventions |
+
+## Open Questions
+
+- Should product search update the URL query string?
+- Should pagination default to 10, 12, or 20 items per page?
+- Should product detail pages use `app/pages/dashboard/products/[id].vue` or `app/pages/dashboard/products/[id]/index.vue`?
+- Should placeholder create and edit routes exist, or should actions open disabled dialogs?

package/dist-assets/examples/nuxt-dashboard/02-functional-spec.md

@@ -0,0 +1,88 @@
+# Functional Specification: Products Dashboard Area
+
+## Summary
+
+The dashboard will include a protected products section backed by DummyJSON. Users can browse products, search by keyword, paginate results, open product details, and see create/edit/delete controls that are explicitly placeholders.
+
+## User Stories
+
+- As an authenticated dashboard user, I want to view products so I can inspect available catalog data.
+- As an authenticated dashboard user, I want to search products so I can find relevant records quickly.
+- As an authenticated dashboard user, I want to paginate products so large result sets remain manageable.
+- As an authenticated dashboard user, I want to open a product detail page so I can inspect one product.
+- As a developer, I want CRUD placeholders so I can see where future persistence work belongs without implementing it now.
+
+## Functional Requirements
+
+- The products area must live under the protected dashboard route group.
+- The list page must fetch products from DummyJSON.
+- The list page must display product title, price, category, stock, and thumbnail when present.
+- The list page must support keyword search.
+- The list page must support pagination.
+- Search and pagination state must be understandable to the user.
+- The detail page must fetch and display one product by ID.
+- Create, edit, and delete controls must be visible but non-persistent.
+- Loading states must appear while product data is being fetched.
+- Empty states must appear when no products match the current query.
+- Error states must appear when the product request fails.
+
+## Screens And States
+
+### Products List
+
+- Default state with paginated products.
+- Search state with filtered results.
+- Loading state during fetch.
+- Empty state when no results match the query.
+- Error state when DummyJSON fails or returns an unexpected response.
+
+### Product Detail
+
+- Default state with product summary and key attributes.
+- Loading state during fetch.
+- Not found state for an invalid product ID.
+- Error state for request failures.
+
+### Placeholder Actions
+
+- Create action appears from the products list.
+- Edit action appears from the detail page or row action.
+- Delete action appears where destructive actions are expected.
+- Placeholder actions must not send real mutation requests.
+
+## Errors
+
+- Network request fails.
+- DummyJSON returns an unexpected response shape.
+- Product ID is missing, invalid, or not found.
+- Search returns no products.
+- Pagination points beyond the available result range.
+
+## Edge Cases
+
+- Empty search query should return the default product list.
+- Fast search changes should not leave stale loading indicators.
+- Pagination should reset or remain coherent when the search query changes.
+- Missing thumbnails should not break row layout.
+- Long product names should not overflow the table or card layout.
+- API errors should not break dashboard navigation.
+
+## Acceptance Criteria
+
+- The list route is protected by existing dashboard auth behavior.
+- Product list data loads from DummyJSON and renders key fields.
+- Search changes the displayed product results.
+- Pagination changes the displayed product page.
+- Product detail navigation works for a valid product.
+- Invalid product IDs show a not found or error state.
+- Loading, empty, and error states are implemented for list and detail views.
+- CRUD placeholders are visible and clearly non-persistent.
+- Validation commands are run and reported for each PR.
+
+## Out Of Scope
+
+- Real create, update, or delete API calls.
+- Custom backend API routes.
+- Authentication redesign.
+- Persistent filters.
+- Advanced table features such as sorting, column customization, exports, and bulk selection.