@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/examples/react-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 the product card or row layout.
+- Long product names should not overflow the 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 (use server actions or route handlers only for demo data).
+- Authentication redesign.
+- Persistent filters (URL params are acceptable but not required).
+- Advanced table features such as sorting, column customization, exports, and bulk selection.

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].