@williambeto/ai-workflow 1.19.0 → 2.1.0

package/dist-assets/examples/react-dashboard/03-technical-plan.md

@@ -0,0 +1,76 @@
+# Technical Plan: Products Dashboard Area
+
+## Architecture Summary
+
+Add a small products domain that isolates DummyJSON access from dashboard pages using Next.js App Router conventions. Dashboard pages should consume typed product contracts and repository functions or server actions instead of calling fetch directly in every component.
+
+The UI should reuse the existing dashboard shell, middleware, UI primitives (e.g., shadcn/ui), and Tailwind CSS conventions. The plan assumes a Next.js app may use `app/dashboard/products/page.tsx`, `app/dashboard/products/[id]/page.tsx`, `lib/products/`, shared API utilities, middleware for auth, and a componentized dashboard shell.
+
+## Proposed Folders And Files
+
+| Path | Purpose |
+| ---- | ------- |
+| `lib/products/types.ts` | Product and product list contracts |
+| `lib/products/repository.ts` | DummyJSON product fetch functions or server actions |
+| `lib/products/mappers.ts` | Optional response normalization if needed |
+| `app/dashboard/products/page.tsx` | Products list route (RSC or client component as needed) |
+| `app/dashboard/products/[id]/page.tsx` | Product detail route |
+| `components/dashboard/products/` | Product-specific UI components if page files become too large |
+| `lib/api/` | Existing shared API utilities if already present |
+
+Do not assume all paths exist. Inspect the target repository before editing and follow the local folder pattern.
+
+## Implementation Steps
+
+1. Inspect the existing dashboard routes, auth middleware, component structure, and data-fetching helpers.
+2. Add products domain types and repository functions or server actions for list, search, pagination, and detail fetches.
+3. Implement the products list page using existing dashboard layout conventions.
+4. Wire search and pagination state with clear loading, empty, and error states.
+5. Add the product detail page using the products detail fetch.
+6. Add create, edit, and delete placeholders without real mutation calls.
+7. Add or update focused tests where the project already has test infrastructure (e.g., Vitest, React Testing Library, Playwright).
+8. Run typecheck, lint, tests, and build before reporting completion.
+
+## Dependencies
+
+- Existing Next.js 14+ and React 18+ app.
+- Existing TypeScript configuration.
+- Existing shadcn/ui and Tailwind setup.
+- Existing middleware for protected dashboard pages.
+- DummyJSON product endpoints.
+- Existing test and validation commands, when available.
+
+No new runtime dependency is required for this plan.
+
+## Risks
+
+- DummyJSON response fields may need mapping before UI use.
+- Product list search and pagination can produce stale results if query state is not handled carefully.
+- Page files can become too large if list, empty, error, and placeholder action UI are all inline.
+- Placeholder actions can be mistaken for real persistence if labels are unclear.
+- Tests may not exist yet in the target project.
+
+## Trade-Offs
+
+- A small repository layer adds one extra file but keeps DummyJSON details out of pages.
+- Keeping placeholders non-persistent limits scope but still shows intended CRUD workflow.
+- URL query synchronization improves shareability but may be deferred if it increases PR size.
+- Component extraction should happen only when page complexity justifies it.
+- Server Components vs Client Components: default to Server Components for data fetching; use "use client" only when interactivity is needed.
+
+## Validation Plan
+
+- Run `npm run typecheck` or `tsc --noEmit`.
+- Run `npm run lint`.
+- Run `npm test` or `vitest` if the target project defines it.
+- Run `npm run build`.
+- Manually verify protected route behavior.
+- Manually verify list loading, search, pagination, empty state, error state, and detail navigation.
+- Confirm CRUD placeholders do not send mutation requests.
+
+## Rollback Plan
+
+- Revert the selected PR if validation fails and the fix is not small.
+- Remove added product routes from dashboard navigation if navigation was modified.
+- Remove the products domain files added by the failing PR.
+- Keep unrelated dashboard routes and auth middleware unchanged.

package/dist-assets/examples/react-dashboard/04-pr-breakdown.md

@@ -0,0 +1,218 @@
+# PR Breakdown: Products Dashboard Area
+
+## Strategy
+
+Build the products area through small PRs that separate data contracts, list behavior, detail behavior, placeholder actions, and validation hardening. Each PR should preserve existing dashboard behavior and avoid implementing future PR scope.
+
+## PR 1 — Products Domain Contracts And Repository
+
+Goal:
+
+Create the typed products domain boundary for DummyJSON access.
+
+Scope:
+
+- Define product and product list types.
+- Add repository functions or server actions for list/search/pagination and detail fetches.
+- Add response mapping only if DummyJSON fields need normalization.
+
+Likely files:
+
+- `lib/products/types.ts`
+- `lib/products/repository.ts`
+- `lib/products/mappers.ts`
+- Existing shared API utility files if already present
+
+Validation:
+
+- Run `npm run typecheck` or `tsc --noEmit`.
+- Run `npm run lint`.
+- Add or run focused repository tests if the project has test infrastructure.
+
+Risks:
+
+- Response contracts may not match DummyJSON exactly.
+- Repository helpers may duplicate existing API utilities.
+
+Dependencies:
+
+- Existing API utility conventions.
+
+Estimated size:
+
+```txt
+small
+```
+
+## PR 2 — Products List Page With Search And Pagination
+
+Goal:
+
+Add the protected products list page with search, pagination, and core list states.
+
+Scope:
+
+- Add the products list dashboard route.
+- Render product cards or rows using existing dashboard components.
+- Wire search and pagination to the products repository.
+- Show loading, empty, and error states.
+
+Likely files:
+
+- `app/dashboard/products/page.tsx`
+- `components/dashboard/products/ProductList.tsx`
+- `components/dashboard/products/ProductSearch.tsx`
+- `lib/products/repository.ts`
+
+Validation:
+
+- Run `npm run typecheck` or `tsc --noEmit`.
+- Run `npm run lint`.
+- Run `npm test` if available.
+- Run `npm run build`.
+- Manually verify protected route access, search, pagination, loading, empty, and error states.
+
+Risks:
+
+- Query state may become inconsistent when search changes.
+- Long product names or missing thumbnails may affect layout.
+
+Dependencies:
+
+- PR 1.
+
+Estimated size:
+
+```txt
+medium
+```
+
+## PR 3 — Product Detail Page
+
+Goal:
+
+Add a protected product detail route for individual product inspection.
+
+Scope:
+
+- Add the product detail page.
+- Fetch product by ID through the products repository.
+- Render key product attributes and navigation back to the list.
+- Handle loading, not found, and error states.
+
+Likely files:
+
+- `app/dashboard/products/[id]/page.tsx`
+- `components/dashboard/products/ProductDetail.tsx`
+- `lib/products/repository.ts`
+
+Validation:
+
+- Run `npm run typecheck` or `tsc --noEmit`.
+- Run `npm run lint`.
+- Run `npm test` if available.
+- Run `npm run build`.
+- Manually verify valid, invalid, and failing product detail states.
+
+Risks:
+
+- Dynamic route pattern may differ from the target project.
+- Invalid IDs may show a generic error instead of a useful not found state.
+
+Dependencies:
+
+- PR 1.
+- PR 2 for list-to-detail navigation.
+
+Estimated size:
+
+```txt
+small
+```
+
+## PR 4 — Create, Edit, Delete Placeholders And UX States
+
+Goal:
+
+Expose CRUD-style entry points without implementing persistence.
+
+Scope:
+
+- Add create entry point from the list page.
+- Add edit and delete entry points from detail or list actions.
+- Make placeholder behavior explicit and non-persistent.
+- Refine empty and error state copy if needed.
+
+Likely files:
+
+- `app/dashboard/products/page.tsx`
+- Product detail route file selected in PR 3
+- `components/dashboard/products/`
+
+Validation:
+
+- Run `npm run typecheck` or `tsc --noEmit`.
+- Run `npm run lint`.
+- Run `npm test` if available.
+- Confirm no mutation requests are sent.
+- Manually verify placeholder copy is clear.
+
+Risks:
+
+- Users may mistake placeholder actions for real persistence.
+- Delete controls may look destructive even though no mutation exists.
+
+Dependencies:
+
+- PR 2.
+- PR 3.
+
+Estimated size:
+
+```txt
+small
+```
+
+## PR 5 — Tests And Validation Hardening
+
+Goal:
+
+Strengthen confidence that the products workflow is stable and ready for future backend integration.
+
+Scope:
+
+- Add missing tests for repository behavior, list states, and detail states where the project supports tests.
+- Confirm build, lint, typecheck, and existing tests pass.
+- Document validation evidence and remaining risks.
+
+Likely files:
+
+- Existing test folders used by the target project
+- `lib/products/`
+- `components/dashboard/products/`
+- PR validation notes or pull request description
+
+Validation:
+
+- Run `npm run typecheck` or `tsc --noEmit`.
+- Run `npm run lint`.
+- Run `npm test` or `vitest`.
+- Run `npm run build`.
+
+Risks:
+
+- The target project may not have test infrastructure yet.
+- Tests may need to mock DummyJSON to stay deterministic.
+
+Dependencies:
+
+- PR 1.
+- PR 2.
+- PR 3.
+- PR 4.
+
+Estimated size:
+
+```txt
+medium
+```

package/dist-assets/examples/react-dashboard/05-execution-handoff.md

@@ -0,0 +1,13 @@
+# 05 - Execution Handoff
+
+**Agent**: Astra (Developer)
+**Task**: Initial setup of React Dashboard.
+
+##  Actions
+- Initialized Vite + React + Tailwind project.
+- Configured React Router.
+- Implemented `AuthLayout` and `Login` page mock.
+
+##  Verification
+- `npm run dev` starts correctly.
+- Lint: [PASS].

package/dist-assets/examples/react-dashboard/06-validation-report.md

@@ -0,0 +1,12 @@
+# 06 - Validation Report (Sage)
+
+**Target**: React Dashboard Boilerplate.
+
+## Audit findings
+- **Component Structure**: [PASS] - Follows Atomic Design principles.
+- **Tailwind Config**: [PASS] - Consistent with design specs.
+- **Accessibility**: [PASS] - Aria labels present on interactive elements.
+
+---
+##  Gate C Verdict
+ **[APPROVED]**

package/dist-assets/examples/react-dashboard/07-orchestration-report.md

@@ -0,0 +1,7 @@
+# 07 - Orchestration Report
+
+**Task**: React Dashboard Foundation.
+**Status**: [COMPLETE]
+
+---
+*Maintained by Atlas*

package/dist-assets/examples/react-dashboard/README.md

@@ -0,0 +1,70 @@
+# React Dashboard Example
+
+## Context
+
+Project:
+
+```txt
+React Dashboard Boilerplate
+```
+
+Stack:
+
+```txt
+Next.js 14+
+React 18+
+TypeScript
+shadcn/ui
+Tailwind CSS
+DummyJSON
+```
+
+Objective:
+
+Evolve a controlled dashboard boilerplate through small PRs, using the OpenCode-first workflow to plan, implement, review, and validate one scoped change at a time.
+
+## Workflow
+
+Read the files in order:
+
+```txt
+01-requirement.md
+02-functional-spec.md
+03-technical-plan.md
+04-pr-breakdown.md
+```
+
+The example follows this path:
+
+```txt
+requirement
+→ functional spec
+→ technical plan
+→ PR breakdown
+```
+
+This is not a Next.js starter project. It is a workflow example for planning and validating dashboard work in a real React/Next.js repository.
+
+## Stack Conventions Used
+
+| Convention | Example |
+|---|---|
+| App Router | `app/dashboard/products/page.tsx` |
+| Dynamic routes | `app/dashboard/products/[id]/page.tsx` |
+| Domain layer | `lib/products/types.ts`, `lib/products/repository.ts` |
+| Components | `components/dashboard/products/ProductList.tsx` |
+| Server Components | Default for data fetching |
+| Client Components | `"use client"` only when interactivity needed |
+| Validation | `tsc --noEmit`, `npm run lint`, `npm run build` |
+
+## Reference Variants
+
+This example mirrors the pattern established by:
+
+```txt
+examples/nuxt-dashboard/    — Nuxt/Vue stack variant
+examples/wordpress-theme/   — WordPress/PHP stack variant
+examples/docs-only-repo/    — Non-code stack variant
+```
+
+Use `stack-variant-creator` skill when creating new variants.

package/dist-assets/examples/refactoring-service/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# Refactoring Service - Technical Debt Removal
+
+## 0. Context
+This example demonstrates how to perform a large-scale refactoring task (extracting a service) while preserving existing behavioral contracts, using the `Refactoring-Specialist` agent.
+
+---
+
+## The Request
+**User**: "The payment logic in my routes file is getting too complex. I want to extract it into a dedicated `PaymentService` to improve maintainability and testability."

package/dist-assets/examples/refactoring-service/01-debt-report.md

@@ -0,0 +1,12 @@
+# 01 - Technical Debt Report
+
+## 1. Description
+The `payment.routes.ts` file contains over 500 lines of business logic, including tax calculation, third-party API calls, and database updates.
+
+## 2. Identified Risks
+- **Testing Difficulty**: Hard to unit test logic without spinning up the entire route.
+- **Duplication**: Similar logic is being copied to other routes.
+- **Fragility**: High risk of breaking payments during minor UI changes.
+
+---
+*Status: [REFACTORING_APPROVED]*

package/dist-assets/examples/refactoring-service/02-behavior-spec.md

@@ -0,0 +1,11 @@
+# 02 - Behavioral Contract Specification
+
+**Agent**: Nexus (Spec Architect)
+
+## 1. Existing Behavior (MUST PRESERVE)
+- `POST /pay`: Accepts amount and method. Returns transaction ID.
+- Success Scenario: Returns 200 and triggers email confirmation.
+- Error Scenario: Returns 400 for insufficient funds.
+
+## 2. Refactoring Goal
+Move logic to `PaymentService.ts`. No changes allowed in external API signatures.

package/dist-assets/examples/refactoring-service/03-technical-plan.md

@@ -0,0 +1,13 @@
+# 03 - Technical Plan: Safe Migration
+
+**Agent**: Refactoring-Specialist
+
+## 1. Safety Strategy
+1. Create `PaymentService` class.
+2. Write unit tests for the NEW service based on EXISTING behavior.
+3. Replace route logic with service call.
+4. Run integration tests on the route.
+
+## 2. Refactoring Patterns
+- **Extract Class**: Move methods to the new service.
+- **Dependency Injection**: Inject service into the route handler.

package/dist-assets/examples/refactoring-service/04-pr-breakdown.md

@@ -0,0 +1,9 @@
+# 04 - PR Breakdown
+
+**Sequence**:
+1. **PR 1**: `PaymentService` skeleton + behavioral tests.
+2. **PR 2**: Logic migration (internal methods).
+3. **PR 3**: Route integration + final cleanup.
+
+---
+*Ready for Astra*

package/dist-assets/examples/refactoring-service/05-execution-handoff.md

@@ -0,0 +1,14 @@
+# 05 - Execution Handoff
+
+**Agent**: Refactoring-Specialist
+**Task**: Extract Payment Service.
+
+##  Actions
+- Created `src/services/PaymentService.ts`.
+- Migrated 450 lines of code.
+- Reduced `payment.routes.ts` from 580 to 30 lines.
+
+##  Verification
+- Unit tests for `PaymentService`: [PASS].
+- Integration tests for `/pay`: [PASS].
+- Manual regression: [SUCCESS].

package/dist-assets/examples/refactoring-service/06-stability-report.md

@@ -0,0 +1,12 @@
+# 06 - Stability Report
+
+**Task**: Technical Debt Removal (Payment Service).
+**Outcome**: 100% Behavioral Parity maintained.
+
+## Metrics
+- Code removed from routes: 95%.
+- Test coverage of new service: 98%.
+- Performance impact: Neutral.
+
+---
+*Maintained by Atlas — The Quality Partner*

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

@@ -0,0 +1,12 @@
+# SDD Full Cycle - Spec-Driven Development
+
+## 0. Context
+This example demonstrates the complete Spec-Driven Development (SDD) process of the AI Workflow Kit, from an ambiguous user request to a validated implementation.
+
+## The Goal
+Show how the agents (Nexus, Orion, Astra, Sage) work together using formal specifications to ensure 100% compliance.
+
+---
+
+## The Request
+**User**: "I want JWT authentication for my API. It needs to be secure and use environment variables for the secret."

package/dist-assets/examples/sdd-cycle/01-raw-request.md

@@ -0,0 +1,13 @@
+# 01 - Raw Requirement
+
+**Source**: User Request.
+**Priority**: High.
+
+## Description
+Implement JWT-based authentication for the backend API.
+
+## High-Level Desires
+- Use `jsonwebtoken` library.
+- Secret must be in `.env`.
+- Middleware to protect private routes.
+- Login endpoint returns a token.

package/dist-assets/examples/sdd-cycle/02-spec-creation.md

@@ -0,0 +1,18 @@
+# 02 - Functional Specification (STANDARD)
+
+**Agent**: Nexus (Spec Architect)
+**Status**: [DRAFT]
+
+## 1. Goal
+Implement a robust JWT authentication system to protect private resources.
+
+## 2. Requirements
+- **R1**: Provide a `/auth/login` endpoint that accepts credentials and returns a signed JWT.
+- **R2**: Implement a `verifyToken` middleware for route protection.
+- **R3**: Tokens must expire in 1 hour.
+- **R4**: The JWT secret MUST be loaded from `JWT_SECRET` environment variable.
+
+## 3. Acceptance Criteria
+- [ ] `/auth/login` returns 200 with `{ token: string }` on success.
+- [ ] Middleware returns 401 if header `Authorization: Bearer <token>` is missing or invalid.
+- [ ] Secret is NOT hardcoded in source code.

package/dist-assets/examples/sdd-cycle/03-spec-review.md

@@ -0,0 +1,12 @@
+# 03 - Spec Review Report
+
+**Agent**: Nexus (Spec Architect)
+**Audit Date**: 2026-05-29
+
+## Quality Check
+- **Completeness**: [PASS] - Covers login, middleware, and config.
+- **Ambiguity**: [PASS] - Clear error codes and header requirements.
+- **Feasibility**: [PASS] - Uses standard libraries.
+
+## Verdict
+ **[APPROVED]** - Ready for technical planning.

package/dist-assets/examples/sdd-cycle/04-technical-plan.md

@@ -0,0 +1,16 @@
+# 04 - Technical Plan
+
+**Agent**: Orion (Strategist)
+
+## 1. Architecture
+- Use `jsonwebtoken` for signing and verification.
+- Create `AuthService` to encapsulate logic.
+- Create `AuthMiddleware` for Fastify/Express.
+
+## 2. Security Patterns
+- **Secret Management**: Use `dotenv` to load `JWT_SECRET`.
+- **Payload**: Minimal data (user ID only).
+
+## 3. Testing Strategy
+- Unit tests for `AuthService` (valid/invalid tokens).
+- Integration tests for middleware using mock tokens.

package/dist-assets/examples/sdd-cycle/05-pr-breakdown.md

@@ -0,0 +1,9 @@
+# 05 - PR Breakdown
+
+**Sequence**:
+1. **PR 1**: AuthService implementation + Unit Tests.
+2. **PR 2**: AuthMiddleware + Integration Tests.
+3. **PR 3**: Login route wiring.
+
+---
+*Ready for Astra*

package/dist-assets/examples/sdd-cycle/06-spec-implement.md

@@ -0,0 +1,13 @@
+# 06 - Implementation Handoff
+
+**Agent**: Astra (Developer)
+**Task**: Complete JWT Cycle.
+
+##  Actions
+- Implemented `AuthService` with `sign` and `verify`.
+- Created middleware to validate Bearer tokens.
+- Secured the `/private` routes.
+
+##  Verification
+- `npm run test:unit` [PASS].
+- `npm run test:integration` [PASS].

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.