@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/examples/nuxt-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. Dashboard pages should consume typed product contracts and repository functions instead of calling `fetch` directly in every component.
+
+The UI should reuse the existing dashboard shell, route middleware, Nuxt UI primitives, and Tailwind conventions. The plan assumes a Nuxt app may use `app/pages/dashboard/products/index.vue`, `app/pages/dashboard/products/[id].vue` or `app/pages/dashboard/products/[id]/index.vue`, `domains/products/`, shared HTTP utilities, route middleware for auth, and a componentized dashboard shell.
+
+## Proposed Folders And Files
+
+| Path | Purpose |
+| ---- | ------- |
+| `domains/products/types.ts` | Product and product list contracts |
+| `domains/products/repository.ts` | DummyJSON product fetch functions |
+| `domains/products/mappers.ts` | Optional response normalization if needed |
+| `app/pages/dashboard/products/index.vue` | Products list route |
+| `app/pages/dashboard/products/[id].vue` | Product detail route if the app uses flat dynamic pages |
+| `app/pages/dashboard/products/[id]/index.vue` | Product detail route if the app uses folder-based dynamic pages |
+| `components/dashboard/products/` | Product-specific UI components if page files become too large |
+| `shared/http/` | Existing shared HTTP 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 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 repository 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.
+8. Run typecheck, lint, tests, and build before reporting completion.
+
+## Dependencies
+
+- Existing Nuxt 4 and Vue 3 app.
+- Existing TypeScript configuration.
+- Existing Nuxt UI and Tailwind setup.
+- Existing route 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.
+
+## Validation Plan
+
+- Run `npm run typecheck`.
+- Run `npm run lint`.
+- Run `npm run test` 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/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?