@williambeto/ai-workflow 1.19.1 → 2.1.0

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

@@ -0,0 +1,219 @@
+# 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 for list/search/pagination and detail fetches.
+- Add response mapping only if DummyJSON fields need normalization.
+
+Likely files:
+
+- `domains/products/types.ts`
+- `domains/products/repository.ts`
+- `domains/products/mappers.ts`
+- Existing shared HTTP utility files if already present
+
+Validation:
+
+- Run `npm run typecheck`.
+- 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 HTTP utilities.
+
+Dependencies:
+
+- Existing HTTP helper 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 rows or cards using existing dashboard components.
+- Wire search and pagination to the products repository.
+- Show loading, empty, and error states.
+
+Likely files:
+
+- `app/pages/dashboard/products/index.vue`
+- `components/dashboard/products/ProductList.vue`
+- `components/dashboard/products/ProductSearch.vue`
+- `domains/products/repository.ts`
+
+Validation:
+
+- Run `npm run typecheck`.
+- Run `npm run lint`.
+- Run `npm run 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/pages/dashboard/products/[id].vue`
+- `app/pages/dashboard/products/[id]/index.vue`
+- `components/dashboard/products/ProductDetail.vue`
+- `domains/products/repository.ts`
+
+Validation:
+
+- Run `npm run typecheck`.
+- Run `npm run lint`.
+- Run `npm run 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/pages/dashboard/products/index.vue`
+- Product detail route file selected in PR 3
+- `components/dashboard/products/`
+
+Validation:
+
+- Run `npm run typecheck`.
+- Run `npm run lint`.
+- Run `npm run 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
+- `domains/products/`
+- `components/dashboard/products/`
+- PR validation notes or pull request description
+
+Validation:
+
+- Run `npm run typecheck`.
+- Run `npm run lint`.
+- Run `npm run test`.
+- 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/nuxt-dashboard/05-execution-handoff.md

@@ -0,0 +1,88 @@
+# Handoff: PR 2 Products List Page
+
+## Source Agent
+
+Planner
+
+## Target Agent
+
+Executor
+
+## Objective
+
+Implement PR 2: add the protected products list page with search, pagination, and core list states.
+
+## Context
+
+The Nuxt Dashboard Boilerplate already has a protected dashboard area, a dashboard shell, and products domain contracts from PR 1. The products list should use DummyJSON through the products repository instead of calling the API directly from unrelated UI code.
+
+This handoff covers only the list page. Product detail and real CRUD behavior are separate PRs.
+
+## Decisions Already Made
+
+- Use DummyJSON as the demo product data source.
+- Keep product API access behind `domains/products/`.
+- Reuse existing dashboard layout, route middleware, Nuxt UI, and Tailwind conventions.
+- Implement create, edit, and delete behavior in a later PR.
+- Keep search and pagination simple unless the existing app already has a query-state convention.
+
+## Files In Scope
+
+- `app/pages/dashboard/products/index.vue` — add or update the protected products list route.
+- `components/dashboard/products/` — add small list, search, pagination, empty, or error components only if the page becomes too large.
+- `domains/products/repository.ts` — use or lightly adjust list/search/pagination fetch functions from PR 1.
+- `domains/products/types.ts` — use existing product contracts and adjust only if PR 1 missed a required list field.
+- Existing dashboard navigation file — add a products link only if navigation is centrally configured.
+
+## Files Out Of Scope
+
+- `app/pages/dashboard/products/[id].vue` — product detail belongs to PR 3.
+- `app/pages/dashboard/products/[id]/index.vue` — product detail belongs to PR 3.
+- Authentication middleware files — existing protected route behavior should be reused.
+- Global design system files — layout rules should be followed, not redesigned.
+- Backend API routes — DummyJSON access should remain client or repository level for this example.
+
+## Constraints
+
+- Preserve existing behavior unless explicitly changed.
+- Keep the change small and reviewable.
+- Do not implement future PRs.
+- Do not introduce unrelated dependencies or tooling.
+- Follow existing repository patterns.
+- Do not add real create, edit, or delete mutation behavior.
+- Keep DummyJSON-specific code inside the products domain or existing shared HTTP utility.
+
+## Validation Required
+
+- Run `npm run typecheck` and record the result.
+- Run `npm run lint` and record the result.
+- Run `npm run test` if the target project defines it.
+- Run `npm run build`.
+- Manually verify authenticated access to the products route.
+- Manually verify list loading, search, pagination, empty state, and error state.
+- Confirm the list page does not call real mutation endpoints.
+
+## Known Risks
+
+- Search and pagination state can become inconsistent if the query changes while a page request is pending.
+- Missing thumbnails or long product names can break compact dashboard layouts.
+- DummyJSON response shape may require a small mapper update.
+- The target project may not have test infrastructure for page-level states.
+
+## Stop Conditions
+
+- Stop if the dashboard route protection pattern cannot be identified.
+- Stop if PR 1 products repository contracts are missing or incompatible.
+- Stop if implementing list behavior requires changing auth, global layout, or unrelated navigation architecture.
+- Stop if new dependencies appear necessary.
+- Stop if DummyJSON is unavailable and no approved mock strategy exists.
+
+## Expected Output
+
+- Summary of implemented list behavior.
+- Files changed.
+- Behavior preserved and behavior changed.
+- Validation commands with results.
+- Manual checks performed.
+- Untested areas and remaining risks.
+- Final recommendation using the repository approval labels.

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

@@ -0,0 +1,56 @@
+# Validation Report: PR 2 Products List Page
+
+## Status
+
+```txt
+Example expected validation report, not actual results from this repository.
+```
+
+The target Nuxt project should run these checks after implementing PR 2. This repository does not contain the Nuxt application, so the commands below are illustrative expected commands for that project.
+
+## Commands Run
+
+| Command | Result | Evidence |
+| ------- | ------ | -------- |
+| `npm run typecheck` | Example expected pass | Confirms products list types, repository contracts, and page usage are valid |
+| `npm run lint` | Example expected pass | Confirms the changed Vue and TypeScript files follow project lint rules |
+| `npm run test` | Example expected pass or not configured | Confirms product list behavior if the target project has tests |
+| `npm run build` | Example expected pass | Confirms the Nuxt app can build with the products list route |
+
+## Checks
+
+| Check | Result | Evidence |
+| ----- | ------ | -------- |
+| Protected route behavior | Example expected pass | Authenticated user can open `/dashboard/products`; unauthenticated behavior follows existing middleware |
+| Product list rendering | Example expected pass | Products show title, price, category, stock, and thumbnail when available |
+| Search | Example expected pass | Search input updates product results and handles empty query |
+| Pagination | Example expected pass | Next and previous page controls update displayed results |
+| Loading state | Example expected pass | Loading indicator appears while product data is requested |
+| Empty state | Example expected pass | Empty message appears when no product matches the query |
+| Error state | Example expected pass | Request failure shows a recoverable error message |
+| Scope control | Example expected pass | Detail page and CRUD mutations are not implemented in PR 2 |
+
+## Issues
+
+No confirmed issues in this example report.
+
+Potential observations to record in a real PR:
+
+- If `npm run test` is not configured, mark tests as not run and explain the project gap.
+- If DummyJSON cannot be reached during manual validation, record the network failure and use a deterministic mock only if the project already supports one.
+- If URL query synchronization is deferred, list it as a follow-up rather than expanding PR 2.
+
+## Remaining Risks
+
+- DummyJSON availability can affect manual validation.
+- Search and pagination behavior may need more automated coverage in a later PR.
+- Missing thumbnail and long text layout should be checked across common viewport widths.
+- Placeholder CRUD actions are not covered until PR 4.
+
+## Recommendation
+
+```txt
+Approved with notes
+```
+
+PR 2 can move forward when the target project records passing typecheck, lint, build, relevant tests, and manual evidence for protected access, search, pagination, loading, empty, and error states.

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

@@ -0,0 +1,79 @@
+# Orchestration Report
+
+## Purpose
+
+Demonstrate that gate-based automatic orchestration works for both success and blocked transitions.
+
+References:
+
+```txt
+harness/workflows/multi-agent-handoff.md
+opencode/commands/Atlas.md
+harness/handoffs/HANDOFF.template.md
+```
+
+## Scenario A — PASS path
+
+### Context
+
+- Selected PR: `PR-1 — Add products list page`
+- Existing artifacts: requirement, functional spec, technical plan, PR breakdown, execution handoff
+- Expected chain: `Orion -> Astra -> Sage -> Orion`
+
+### Gate results
+
+| Gate | Input status | Result | Next agent |
+| ---- | ------------ | ------ | ---------- |
+| A (`Orion -> Astra`) | Selected PR scope + handoff complete | Pass | `Astra` |
+| B (`Astra -> Sage`) | Scoped implementation + branch gate evidence + validation notes present | Pass | `Sage` |
+| C (`Sage -> Orion`) | Findings severity-ranked; no unresolved High/Medium blockers | Pass | `Orion` |
+
+### Autopilot output sample
+
+```md
+Current workflow step: Sage
+Gate result: Pass
+Next agent to run: Orion
+Required handoff packet:
+- validation report with commands and evidence
+- merge recommendation
+- remaining risks (if any)
+```
+
+## Scenario B — BLOCKED path
+
+### Context
+
+- Selected PR: `PR-2 — Add product filters`
+- Implementation manager delivered implementation notes but omitted branch gate evidence
+- Current branch during execution was not proven outside `main`
+
+### Gate result
+
+| Gate | Block reason | Result | Return owner |
+| ---- | ------------ | ------ | ------------ |
+| B (`Astra -> Sage`) | Missing branch gate evidence (`git status -sb` before edits) | Blocked | `Astra` |
+
+### Autopilot output sample
+
+```md
+Current workflow step: Astra
+Gate result: Blocked
+Blocking reason: branch gate evidence missing for execution step
+Next agent to run: Astra
+Required input packet for retry:
+- execution summary including branch evidence
+- explicit note that implementation was not performed on `main`
+- updated validation evidence
+```
+
+## Expected behavior confirmed
+
+- Orchestrator advances only when gate criteria are satisfied.
+- Orchestrator blocks escalation when required evidence is missing.
+- Blocked transitions return to the previous owner with a smallest safe fix request.
+- Validation gate is mandatory before release recommendation.
+
+## Final note
+
+This report is a workflow proof artifact. It does not claim application deployment or production behavior.

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

@@ -0,0 +1,52 @@
+# Nuxt Dashboard Example
+
+## Context
+
+Project:
+
+```txt
+Nuxt Dashboard Boilerplate
+```
+
+Stack:
+
+```txt
+Nuxt 4
+Vue 3
+TypeScript
+Nuxt 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
+05-execution-handoff.md
+06-validation-report.md
+07-orchestration-report.md
+```
+
+The example follows this path:
+
+```txt
+requirement
+→ functional spec
+→ technical plan
+→ PR breakdown
+→ handoff
+→ validation report
+→ orchestration report
+```
+
+This is not a Nuxt starter project. It is a workflow example for planning and validating dashboard work in a real Nuxt repository.

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

@@ -0,0 +1,84 @@
+# 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 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.
+- Replacing existing auth or layout patterns.
+
+## Assumptions
+
+- The Next.js app already has an authenticated dashboard shell.
+- Middleware already protects dashboard routes.
+- DummyJSON is acceptable for demo data.
+- Existing components or UI primitives (e.g., shadcn/ui, Tailwind CSS) should be reused before adding new abstractions.
+- Product mutations can be represented as disabled or non-persistent placeholders.
+- Standard Next.js App Router conventions apply (`app/dashboard/products/page.tsx`, `app/dashboard/products/[id]/page.tsx`).
+
+## 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 API layer.
+- Use React Server Components and client components appropriately.
+
+## 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 or server actions |
+| 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 (`?q=keyword`)?
+- Should pagination default to 10, 12, or 20 items per page?
+- Should product detail pages use `app/dashboard/products/[id]/page.tsx`?
+- Should placeholder create and edit routes exist, or should actions open disabled dialogs?

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.