@llipe.com/dev-tasks 0.9.2 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/.claude/agents/developer.md +11 -0
  2. package/.claude/agents/qa-engineer.md +31 -2
  3. package/.claude/agents/researcher.md +96 -0
  4. package/.claude/agents/ux-engineer.md +118 -114
  5. package/.claude/commands/planner.md +22 -7
  6. package/.claude/commands/product-engineer.md +37 -10
  7. package/.claude/commands/researcher.md +28 -0
  8. package/.claude/skills/activity-codebase-research/SKILL.md +158 -0
  9. package/.claude/skills/activity-contract-validation/SKILL.md +167 -0
  10. package/.claude/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  11. package/.claude/skills/activity-integration-test-implementation/SKILL.md +156 -0
  12. package/.claude/skills/activity-refine/SKILL.md +1 -0
  13. package/.claude/skills/activity-test-standards/SKILL.md +41 -0
  14. package/.claude/skills/ux-scaffold/SKILL.md +129 -0
  15. package/.claude/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  16. package/.claude/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  17. package/.claude/skills/ux-theme-gen/SKILL.md +149 -0
  18. package/.github/agents/developer.agent.md +11 -0
  19. package/.github/agents/planner.agent.md +22 -7
  20. package/.github/agents/product-engineer.agent.md +37 -10
  21. package/.github/agents/qa-engineer.agent.md +30 -3
  22. package/.github/agents/researcher.agent.md +96 -0
  23. package/.github/agents/ux-engineer.agent.md +119 -114
  24. package/.github/prompts/researcher.prompt.md +29 -0
  25. package/.github/skills/activity-codebase-research/SKILL.md +158 -0
  26. package/.github/skills/activity-contract-validation/SKILL.md +167 -0
  27. package/.github/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  28. package/.github/skills/activity-integration-test-implementation/SKILL.md +156 -0
  29. package/.github/skills/activity-refine/SKILL.md +6 -0
  30. package/.github/skills/activity-test-standards/SKILL.md +41 -0
  31. package/.github/skills/ux-scaffold/SKILL.md +129 -0
  32. package/.github/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  33. package/.github/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  34. package/.github/skills/ux-theme-gen/SKILL.md +149 -0
  35. package/.kiro/agents/developer.md +11 -0
  36. package/.kiro/agents/planner.md +22 -7
  37. package/.kiro/agents/product-engineer.md +37 -10
  38. package/.kiro/agents/qa-engineer.md +30 -3
  39. package/.kiro/agents/researcher.md +99 -0
  40. package/.kiro/agents/ux-engineer.md +119 -132
  41. package/.kiro/agents/verifier.md +1 -1
  42. package/.kiro/skills/activity-codebase-research/SKILL.md +158 -0
  43. package/.kiro/skills/activity-contract-validation/SKILL.md +167 -0
  44. package/.kiro/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  45. package/.kiro/skills/activity-integration-test-implementation/SKILL.md +156 -0
  46. package/.kiro/skills/activity-refine/SKILL.md +1 -0
  47. package/.kiro/skills/activity-test-standards/SKILL.md +41 -0
  48. package/.kiro/skills/ux-scaffold/SKILL.md +129 -0
  49. package/.kiro/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  50. package/.kiro/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  51. package/.kiro/skills/ux-theme-gen/SKILL.md +149 -0
  52. package/AGENTS.md +91 -214
  53. package/CHANGELOG.md +64 -0
  54. package/CLAUDE.md +3 -2
  55. package/DESIGN.md +233 -0
  56. package/README.md +31 -28
  57. package/TESTING.md +19 -11
  58. package/bundle-manifest.json +1 -0
  59. package/dist/core/distribution/doctor.d.ts +2 -2
  60. package/dist/core/distribution/doctor.js +3 -3
  61. package/dist/core/distribution/profiles.d.ts.map +1 -1
  62. package/dist/core/distribution/profiles.js +1 -1
  63. package/dist/core/distribution/profiles.js.map +1 -1
  64. package/package.json +4 -3
  65. package/.claude/skills/webapp-mockup/SKILL.md +0 -76
  66. package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
  67. package/.github/skills/webapp-mockup/SKILL.md +0 -71
  68. package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
  69. package/.kiro/skills/webapp-mockup/SKILL.md +0 -76
@@ -0,0 +1,156 @@
1
+ ---
2
+ name: activity-e2e-test-implementation
3
+ description: "Author Playwright end-to-end tests from verifier scenario tables. Covers auth, state reset, CI config, and scenario-to-spec traceability. Use when writing or backfilling E2E tests."
4
+ ---
5
+
6
+ # Activity: E2E Test Implementation (Playwright)
7
+
8
+ Convert `verifier` Design Mode scenario tables into executable Playwright specs. This skill is the execution counterpart to `activity-e2e-test-design`, which produces the scenario tables.
9
+
10
+ ---
11
+
12
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
13
+
14
+ ## Goal
15
+
16
+ Produce Playwright E2E specs that fail when user-facing behavior is wrong. E2E tests assert on observable outcomes — never on internal state, database rows, or implementation details.
17
+
18
+ Consult `/TESTING.md` first. Its E2E layer boundary governs; this skill supplies the method.
19
+
20
+ ## E2E Layer Boundary
21
+
22
+ - **MUST** assert on user-visible behavior (page content, navigation, HTTP responses).
23
+ - **MUST NOT** assert on internal state, database contents, or implementation details.
24
+ - **MUST NOT** mock the application under test. The full stack runs.
25
+ - **MAY** seed test data via API or database before the test begins.
26
+
27
+ ## Part 1 — Playwright Prerequisite Contract
28
+
29
+ Before authoring specs, verify or establish these prerequisites:
30
+
31
+ ### Authentication strategy
32
+
33
+ | Strategy | When to Use | How |
34
+ | ---------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
35
+ | **`storageState` via setup project** (default) | Multi-test suites sharing a logged-in session | A `global-setup.ts` or setup project authenticates once, saves `storageState.json`, and all specs reuse it. |
36
+ | **Per-test programmatic login** | Tests that need different users or roles | Each spec calls login API directly in `beforeEach`. Slower but flexible. |
37
+ | **API-token seeding** | API-only E2E, no browser UI | Set auth headers directly via `request.newContext()`. No browser needed. |
38
+
39
+ Default to `storageState` unless the test requires a different user or role per test.
40
+
41
+ ### Seeded test users
42
+
43
+ - Create dedicated test users (not production accounts).
44
+ - Credentials reach CI via environment variables or secrets — never hardcoded in the repository.
45
+ - Use a deterministic naming convention: `e2e-user-admin@test.local`, `e2e-user-member@test.local`.
46
+ - Document how to create/reset test users in the project's test setup README.
47
+
48
+ ### Base URL and environment resolution
49
+
50
+ - Use `baseURL` in `playwright.config.ts`, resolved from `process.env.BASE_URL` or `process.env.PLAYWRIGHT_BASE_URL`.
51
+ - Never hardcode `localhost:3000` — CI and staging use different URLs.
52
+ - Provide a `.env.test.example` showing required variables.
53
+
54
+ ### Database state reset between runs
55
+
56
+ Choose one:
57
+
58
+ - **Migration + seed** (preferred): drop, migrate, seed before the test suite.
59
+ - **Transaction rollback**: wrap each test in a transaction (complex for E2E).
60
+ - **Snapshot restore**: restore a known-good database snapshot before runs.
61
+
62
+ State reset **MUST** run in `globalSetup` or a setup project, not inside individual specs.
63
+
64
+ ### Trace, screenshot, and video retention
65
+
66
+ - **Default:** `on-first-retry` for traces, `only-on-failure` for screenshots, `off` for video.
67
+ - **CI:** retain artifacts as test attachments. Configure `outputDir` and artifact upload in CI workflow.
68
+ - Keep retention bounded — do not retain video for every passing test.
69
+
70
+ ### Browser install in CI
71
+
72
+ - CI **MUST** install browsers explicitly: `npx playwright install --with-deps chromium`.
73
+ - Locally: `npx playwright install` on first run.
74
+ - Pin Playwright version in `package.json` — do not use `latest`.
75
+
76
+ ### Sharding (large suites)
77
+
78
+ - For suites >50 specs: shard across CI workers using `--shard=1/4`, `--shard=2/4`, etc.
79
+ - Configure in CI matrix, not in `playwright.config.ts`.
80
+
81
+ ## Part 2 — Scenario-to-Spec Mapping
82
+
83
+ ### Traceability convention
84
+
85
+ Every Playwright spec **MUST** be traceable to a `verifier` Design Mode scenario.
86
+
87
+ **Annotation format:** Include `@scenario SC-{n}` in the test title or as a comment:
88
+
89
+ ```typescript
90
+ // @scenario SC-1
91
+ test("SC-1: Successful login with valid credentials", async ({ page }) => {
92
+ // ...
93
+ });
94
+ ```
95
+
96
+ Or in the test title directly:
97
+
98
+ ```typescript
99
+ test("[SC-1] User logs in with valid credentials", async ({ page }) => {
100
+ // ...
101
+ });
102
+ ```
103
+
104
+ ### Traceability chain
105
+
106
+ ```
107
+ AC-{n} → SC-{n} (test plan) → .spec.ts file / test block (@scenario SC-{n}) → Pass/Fail
108
+ ```
109
+
110
+ The `verifier` audit resolves scenario IDs to spec files by searching for `@scenario SC-{n}` or `SC-{n}:` patterns. Orphaned scenarios (in the plan but not in specs) are reported as uncovered.
111
+
112
+ ### File naming
113
+
114
+ - One spec file per feature or user journey: `login.spec.ts`, `checkout.spec.ts`.
115
+ - Group related scenarios in one file. Do not create one file per scenario unless they are independent flows.
116
+
117
+ ## Part 3 — Converting Scenario Tables to Specs
118
+
119
+ Given a scenario table from `activity-e2e-test-design`:
120
+
121
+ 1. **Read the scenario.** Extract: preconditions, steps, expected result, pass criteria.
122
+ 2. **Write the spec.** Map steps to Playwright actions. Map pass criteria to assertions.
123
+ 3. **Annotate.** Add `@scenario SC-{n}` to the test.
124
+ 4. **Handle preconditions.** Seed required state in `beforeAll`/`beforeEach` or a fixture.
125
+ 5. **Assert observable outcomes.** Use `expect(page)` or `expect(response)` — never internal state.
126
+
127
+ ### Retry and flakiness
128
+
129
+ - Use Playwright's built-in retry (`retries: 2` in config) for CI.
130
+ - Prefer explicit `await expect(locator).toBeVisible()` over arbitrary `waitForTimeout`.
131
+ - If a test is flaky, fix the root cause (race condition, state leak) rather than increasing retries.
132
+ - A flaky test that occasionally passes is worse than no test.
133
+
134
+ ### Test isolation
135
+
136
+ - Each spec **MUST** be independent — runnable in any order, in parallel.
137
+ - Never rely on state from a previous test. Use fixtures or setup projects.
138
+ - Use `test.describe.configure({ mode: 'serial' })` only when tests represent a true sequential flow.
139
+
140
+ ## Output
141
+
142
+ - Specs written or updated, by path
143
+ - Scenario-to-spec mapping table: `SC-{n}` → file path and test name
144
+ - Uncovered scenarios (in the plan but not yet implemented)
145
+ - Prerequisites missing (base URL, auth setup, browser install, etc.)
146
+ - Stated limitations (e.g., "no staging environment — E2E limited to localhost")
147
+
148
+ ## Final Instructions
149
+
150
+ 1. You **MUST** consult `/TESTING.md` and respect its E2E layer boundary.
151
+ 2. You **MUST** annotate every spec with its scenario ID (`@scenario SC-{n}`).
152
+ 3. You **MUST NOT** assert on internal state or implementation details.
153
+ 4. You **MUST** verify Playwright prerequisites before authoring specs.
154
+ 5. You **MUST** report uncovered scenarios from the test plan.
155
+ 6. You **MUST** address flakiness causes, not mask them with retries.
156
+ 7. You **MUST NOT** install dependencies — detect and recommend only.
@@ -0,0 +1,156 @@
1
+ ---
2
+ name: activity-integration-test-implementation
3
+ description: "Author integration tests (Layer 2.5) against real databases — local via testcontainers/docker-compose/Supabase CLI, remote via testing environments. Covers migrations, RLS, pgTAP, fixtures, and fallback paths. Use when writing or backfilling integration tests."
4
+ ---
5
+
6
+ # Activity: Integration Test Implementation (Layer 2.5)
7
+
8
+ Author integration tests that exercise code against a real database. Layer 2.5 exists because mocking the data layer makes SQL errors, type mismatches, NULL handling, malformed joins, and RLS policies structurally invisible.
9
+
10
+ ---
11
+
12
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
13
+
14
+ ## Goal
15
+
16
+ Produce integration tests that fail when the data layer is wrong. If the database is mocked, the test belongs at Layer 2, not here.
17
+
18
+ Consult `/TESTING.md` first. Its Layer 2.5 boundary governs; this skill supplies the method.
19
+
20
+ ## Layer 2.5 Boundary
21
+
22
+ - **MUST** use a real database (Postgres, SQLite, etc.) — not a mock or in-memory fake.
23
+ - **MUST NOT** mock the data layer. If you mock `sql`, `prisma`, `drizzle`, or the ORM client, the test is Layer 2.
24
+ - **MUST NOT** assert on SQL text or internal query shape. Assert on persisted state or returned data.
25
+ - **MAY** mock third-party external services (payment gateways, email providers) at the HTTP boundary.
26
+
27
+ ## Part 1 — Local Integration Environment Detection
28
+
29
+ Detect the easiest applicable local option. Prefer in this order:
30
+
31
+ ### 1. Testcontainers (preferred for isolation)
32
+
33
+ - Look for `@testcontainers/postgresql` or equivalent in `package.json`/`pom.xml`/`Cargo.toml`.
34
+ - Requires Docker. Check: `docker info` succeeds.
35
+ - Each test suite gets an ephemeral container — full isolation, no cleanup conflicts.
36
+
37
+ ### 2. Docker Compose
38
+
39
+ - Look for `docker-compose.yml` or `compose.yml` with a database service.
40
+ - Requires Docker. Shared instance across tests — needs explicit state reset.
41
+
42
+ ### 3. Supabase Local CLI
43
+
44
+ - Look for `supabase/config.toml` or `.supabase/` directory.
45
+ - Check: `supabase status` succeeds.
46
+ - Provides real Postgres with auth, storage, and edge functions locally.
47
+
48
+ ### 4. Fallback — No Local Environment
49
+
50
+ - If Docker is unavailable and Supabase CLI is not installed, report the limitation.
51
+ - Emit: `SKIPPED(no local database environment — Docker unavailable, Supabase CLI not installed)`.
52
+ - Recommend environment setup as a follow-up. Do not silently omit.
53
+
54
+ ## Part 2 — Fixtures, Seeding, and Lifecycle
55
+
56
+ ### Test isolation
57
+
58
+ - Each test **SHOULD** run in a transaction that rolls back on completion (preferred).
59
+ - Alternative: truncate affected tables in `beforeEach`/`afterEach`.
60
+ - Alternative for testcontainers: fresh container per suite (slower but fully isolated).
61
+
62
+ ### Seeding
63
+
64
+ - Shared seed data lives in one location per package (e.g., `test/fixtures/seed.sql` or `test/helpers/seed.ts`).
65
+ - Seeds **MUST** be idempotent — running twice produces the same state.
66
+ - Seeds **MUST NOT** depend on auto-increment IDs. Use deterministic UUIDs or named references.
67
+
68
+ ### Deterministic teardown
69
+
70
+ - Every integration test file **MUST** clean up after itself or use rollback isolation.
71
+ - Tests **MUST NOT** depend on execution order.
72
+ - Tests **MUST NOT** leave residual data that affects other test files.
73
+
74
+ ## Part 3 — Migration Clean-Apply Tests
75
+
76
+ - **MUST** test that all migrations apply cleanly from an empty database.
77
+ - **MUST** verify apply order (no duplicate prefixes, no gaps).
78
+ - **MUST** verify idempotency: running migrations twice does not error.
79
+ - For large stacks (50+ migrations): run full clean-apply on CI/scheduled; run latest N on PR.
80
+ - Report duplicate migration prefixes as a finding.
81
+
82
+ ## Part 4 — Row-Level Security (RLS) Policy Tests
83
+
84
+ RLS tests **MUST** exercise the real database policy, not application-level tenant checks in JavaScript.
85
+
86
+ ### Multi-session setup
87
+
88
+ - Create at least two database roles or authenticated sessions (Tenant A, Tenant B).
89
+ - Use `SET ROLE` or separate connections per tenant.
90
+ - For Supabase: use `supabase.auth.admin.createUser()` for test users, then authenticate with their JWTs.
91
+
92
+ ### Required assertions
93
+
94
+ | Case | Assertion |
95
+ | ---------------------------- | ----------------------------------- |
96
+ | Tenant A reads own data | Returns expected rows |
97
+ | Tenant A reads Tenant B data | Returns empty set or error |
98
+ | Tenant A writes to Tenant B | Insert/update fails or is invisible |
99
+ | Unauthenticated access | Denied by policy |
100
+ | Service role bypasses RLS | Returns all rows (when expected) |
101
+
102
+ ### Record limitations
103
+
104
+ If isolation is asserted against application-level checks rather than the real RLS policy, you **MUST** record: "Production RLS policy unverified — tested against application-layer tenant filtering only."
105
+
106
+ ## Part 5 — pgTAP / Schema Contract Tests
107
+
108
+ Use pgTAP (or equivalent: `pg_prove`, raw SQL assertions) for:
109
+
110
+ - Table and column existence.
111
+ - Constraint verification (NOT NULL, UNIQUE, CHECK, FK).
112
+ - Function and trigger existence and signatures.
113
+ - Permission grants per role.
114
+ - Index existence for query-critical paths.
115
+
116
+ When pgTAP is unavailable, use raw `SELECT` assertions against `information_schema` or `pg_catalog`.
117
+
118
+ ## Part 6 — Remote Integration Testing
119
+
120
+ ### Default: read-only
121
+
122
+ - Inspect schema, permissions, RLS policies, and data shape without mutation.
123
+ - Use `EXPLAIN` for query plan verification without executing writes.
124
+ - No approval required for read-only operations.
125
+
126
+ ### Testing environment writes
127
+
128
+ - **REQUIRE** explicit user approval before any write or migration apply.
129
+ - Connect only to a dedicated testing environment — never to production for writes.
130
+ - After writes: verify applied state, then clean up test data.
131
+ - Record: environment name, operation performed, approval evidence.
132
+
133
+ ### No testing environment available
134
+
135
+ - Report: "Remote integration limited to read-only inspection. No testing environment configured."
136
+ - Recommend environment setup. Do not fabricate a pass.
137
+
138
+ ## Output
139
+
140
+ - Tests written or updated, by path and layer
141
+ - Local environment detection result (which option selected, or fallback triggered)
142
+ - Migration clean-apply result
143
+ - RLS policy test coverage per table with RLS enabled
144
+ - Schema contract coverage (tables, constraints, functions)
145
+ - Remote integration status (read-only / testing-env / unavailable)
146
+ - Stated limitations where real-policy testing was not possible
147
+
148
+ ## Final Instructions
149
+
150
+ 1. You **MUST** consult `/TESTING.md` and respect its Layer 2.5 boundary.
151
+ 2. You **MUST NOT** mock the data layer. If the database is mocked, the test is Layer 2.
152
+ 3. You **MUST** detect the local environment and recommend the easiest applicable option.
153
+ 4. You **MUST** report a limitation when no local or remote environment is available.
154
+ 5. You **MUST** test RLS against the real policy layer, not application-level checks.
155
+ 6. You **MUST** require explicit approval before any remote write operation.
156
+ 7. You **MUST NOT** install dependencies — detect and recommend only.
@@ -1,3 +1,8 @@
1
+ ---
2
+ name: activity-refine
3
+ description: "Clarify scope: produce a lightweight issue refinement or a full PRD. Use in product-engineer Feature or Issue Mode."
4
+ ---
5
+
1
6
  # Activity: Refine Scope
2
7
 
3
8
  Clarify the scope, acceptance criteria, and constraints of a feature or issue before implementation begins. Produces a lightweight refinement for a GitHub Issue, or a full PRD for a new feature description. Invoked by the `product-engineer` agent in Issue Mode or Feature Mode.
@@ -229,3 +234,4 @@ Rules:
229
234
  6. You **MUST** save the finalized document.
230
235
  7. In Issue Refinement mode, you **MUST** update the GitHub Issue with a "Refined Scope" section by delegating to `github-ops` whenever possible.
231
236
  8. When updating an existing document, you **MUST** add a new row to the Changelog table with an incremented version, the current date, a summary of changes, and the responsible author/agent.
237
+ 9. After producing the document, if the feature includes UI/UX scope (detected by keywords: UI, screen, page, form, modal, dialog, navigation, layout, component, responsive, accessibility), you **SHOULD** add the following recommendation to the user: "This feature has UI scope. **Recommended:** use `ux-engineer` (lite mode) to generate screen sketches before proceeding to spec/stories."
@@ -92,6 +92,47 @@ A monorepo defines `test:node` as `app && scraper && db` while the `api` package
92
92
 
93
93
  Correct output: **defect** — `api` is unreachable from the aggregate; the CI gate and the deploy gate both let untested backend code through. Reporting "all script names conform" here is a false pass.
94
94
 
95
+ ## Part 4 — Integration, E2E, and Contract Infrastructure Detection
96
+
97
+ Detect the presence and configuration state of higher-layer test infrastructure. Report findings as **informational** — missing infrastructure is not a defect, but it informs the gap analysis.
98
+
99
+ ### Integration testing infrastructure
100
+
101
+ | Check | What to look for |
102
+ | ----------------------- | ------------------------------------------------------------- |
103
+ | **Testcontainers** | `@testcontainers/postgresql` or similar in dependencies |
104
+ | **Docker Compose** | `docker-compose.yml` or `compose.yml` with a database service |
105
+ | **Supabase local CLI** | `supabase/config.toml` or `.supabase/` directory |
106
+ | **Docker availability** | `docker info` succeeds (report if unavailable) |
107
+
108
+ ### E2E testing infrastructure
109
+
110
+ | Check | What to look for |
111
+ | ------------------------- | -------------------------------------------------------------------------------- |
112
+ | **Playwright config** | `playwright.config.ts` or `playwright.config.js` present |
113
+ | **Base URL configured** | Config references `process.env.BASE_URL` or equivalent (not hardcoded localhost) |
114
+ | **Auth setup project** | A `global-setup` or setup project defined in Playwright config |
115
+ | **Browser install in CI** | CI workflow includes `playwright install` step |
116
+ | **`test:e2e` script** | Present in `package.json` and reachable from aggregate |
117
+
118
+ ### Contract validation infrastructure
119
+
120
+ | Check | What to look for |
121
+ | -------------------------- | ------------------------------------------------------ |
122
+ | **OpenAPI spec** | `openapi.yaml`, `openapi.json`, `swagger.*` in repo |
123
+ | **AsyncAPI spec** | `asyncapi.yaml`, `asyncapi.json` in repo |
124
+ | **`dt` CLI** | `which dt` succeeds |
125
+ | **`test:contract` script** | Present in `package.json` and reachable from aggregate |
126
+
127
+ ### Reporting
128
+
129
+ Report each finding as:
130
+
131
+ - `[INFO] <infrastructure> detected: <path or status>`
132
+ - `[INFO] <infrastructure> not found — Layer {X} tests require this`
133
+
134
+ These are informational findings for the gap analysis. They do **NOT** block or fail the standards check.
135
+
95
136
  ## Failure Modes
96
137
 
97
138
  | Condition | Required behavior |
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: ux-scaffold
3
+ description: "Template-aware mockup project creation with DESIGN.md-derived tokens. Supports html-lite (zero-install, navigable) and react-full (shadcn + Vite + Radix). Use when generating mockups from a PRD or spec."
4
+ ---
5
+
6
+ # UX Scaffold
7
+
8
+ ## Purpose
9
+
10
+ Create mockup projects at the correct fidelity level, styled from DESIGN.md tokens via `ux-theme-gen` output, and structured as navigable screen sets rather than monolithic apps.
11
+
12
+ ## When to Use
13
+
14
+ - `ux-engineer` invokes this after `ux-theme-gen` has produced theme artifacts.
15
+ - User explicitly requests a mockup scaffold.
16
+
17
+ ## Templates
18
+
19
+ | Template | Fidelity | Output | Build step required |
20
+ | --------------- | -------- | --------------------------------------------- | -------------------------------- |
21
+ | `html-lite` | Low | Self-contained HTML per screen + `index.html` | No — opens from `file://` |
22
+ | `react-full` | High | Vite + React + shadcn/ui project | Yes — `pnpm install && pnpm dev` |
23
+ | ~~`react-mid`~~ | — | Cut (decision 2) | — |
24
+ | `react-native` | — | Reserved, not implemented | — |
25
+
26
+ ## Scripts
27
+
28
+ ### `scaffold-lite.sh`
29
+
30
+ ```
31
+ Usage: ./scripts/scaffold-lite.sh <feature> <variant-num> <theme-css-path> <output-dir>
32
+ ```
33
+
34
+ Generates:
35
+
36
+ - `<output-dir>/index.html` — entry point listing all screens with nav
37
+ - `<output-dir>/screen-<name>.html` — one per enumerated screen
38
+ - `<output-dir>/screen-map.md` — Mermaid flowchart of screen navigation
39
+
40
+ ### `scaffold-full.sh`
41
+
42
+ ```
43
+ Usage: ./scripts/scaffold-full.sh <feature> <variant-num> <output-dir>
44
+ ```
45
+
46
+ Scaffolds a Vite + shadcn project. The script:
47
+
48
+ 1. Creates the Vite app via `npm create vite@latest`.
49
+ 2. Runs `pnpm install`.
50
+ 3. Runs `shadcn@4.18.0 init --base radix --preset nova --css-variables --yes --silent` in the created dir.
51
+ 4. Copies `ux-theme-gen` output (`theme.css`) into `src/index.css`, replacing the default token declarations.
52
+
53
+ ## Screen Enumeration
54
+
55
+ Before scaffolding, the agent enumerates screens from the source artifact:
56
+
57
+ | Screen type | Purpose |
58
+ | ------------------ | ------------------------------- |
59
+ | `happy` | Primary flow, success state |
60
+ | `error-validation` | Form validation failures |
61
+ | `error-server` | Server/network error states |
62
+ | `error-permission` | Permission denied, unauthorized |
63
+ | `empty` | No data, first-use experience |
64
+ | `loading` | Skeleton screens, spinners |
65
+ | `edge-overflow` | Long text, many items |
66
+ | `edge-zero` | Zero items, disabled states |
67
+
68
+ Each screen becomes a named file (`screen-happy.html`, `screen-error-validation.html`, etc.).
69
+
70
+ ## html-lite Navigation (Decision 2)
71
+
72
+ Lite output is a **browsable prototype**, not loose files:
73
+
74
+ - **`index.html`** — lists every screen with its purpose and the AC/story it satisfies, plus the screen map rendered inline.
75
+ - **Inter-screen links** — persistent nav strip on every screen: back to index, previous/next, and direct links to related states (e.g., happy → error-validation → empty).
76
+ - **Relative links only** — must work from `file://` with no server.
77
+ - **Current-screen indication** — highlighted in the nav strip.
78
+
79
+ ## Annotations
80
+
81
+ Every screen section carries a machine-readable reference to the AC or story it satisfies:
82
+
83
+ - HTML: `<section data-ac="AC-3">` or `<!-- AC: AC-3 -->`
84
+ - React: `{/* @ac AC-3 */}` comment above the relevant JSX
85
+
86
+ ## Theme Integration
87
+
88
+ - `html-lite`: reads `theme.css` and inlines the `:root` token values as a `<style>` block.
89
+ - `react-full`: `theme.css` replaces the shadcn-generated `:root` / `@theme inline` block in `src/index.css`.
90
+
91
+ Both templates **must not** contain hardcoded palette values. All styling derives from the theme output.
92
+
93
+ ## Palette Inputs — Removed
94
+
95
+ The `palette` parameter and the `colorhunt.co` fallback are **removed**. DESIGN.md is the sole palette source. If DESIGN.md is unfilled, the agent runs the filling procedure rather than inventing a palette.
96
+
97
+ ## Dependencies (react-full)
98
+
99
+ Pinned to the verified compatibility matrix:
100
+
101
+ | Package | Version | Notes |
102
+ | -------------------------- | ------- | ------------------------------- |
103
+ | `vite` | ^8 | via `create vite` |
104
+ | `@vitejs/plugin-react` | ^6 | Vite 8 only |
105
+ | `@tailwindcss/vite` | ^4 | replaces postcss + autoprefixer |
106
+ | `tailwindcss` | ^4 | CSS-first, no config file |
107
+ | `shadcn` | 4.18.0 | pinned exactly; never @latest |
108
+ | `radix-ui` | ^1.6 | unified package |
109
+ | `tw-animate-css` | ^1.4 | replaces tailwindcss-animate |
110
+ | `class-variance-authority` | ^0.7 | |
111
+ | `clsx` + `tailwind-merge` | latest | |
112
+ | `lucide-react` | ^1.33 | icon library |
113
+
114
+ **Node requirement:** `>= 24` (shadcn CLI needs `>= 20.18.1`; repo floor is `>= 24`).
115
+
116
+ ## Backward Compatibility
117
+
118
+ `webapp-mockup` has been removed. Use `ux-scaffold` directly with the appropriate template.
119
+
120
+ ## Acceptance Checklist
121
+
122
+ - Scripts run non-interactively with no TTY
123
+ - html-lite produces valid standalone HTML viewable from `file://`
124
+ - index.html includes screen map + screen listing
125
+ - Inter-screen navigation works with relative links
126
+ - react-full uses shadcn CLI (pinned), not hand-rolled components
127
+ - No hardcoded palette in any scaffold output
128
+ - Every screen carries an AC/story annotation
129
+ - No `postcss`, `autoprefixer`, `tailwindcss-animate`, or `tailwindcss init -p`