dk-harness 0.1.0

package/templates/next-monorepo/apps/web/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig, devices } from "@playwright/test"
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  timeout: 30_000,
+  use: {
+    baseURL: "http://127.0.0.1:3000",
+    trace: "retain-on-failure",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: {
+        ...devices["Desktop Chrome"],
+      },
+    },
+  ],
+})

package/templates/next-monorepo/apps/web/postcss.config.mjs

@@ -0,0 +1 @@
+export { default } from "@workspace/ui/postcss.config"

package/templates/next-monorepo/apps/web/skills-lock.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "skills": {
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "063a0e6448123cd359ad0044cc46b0e490cc7964d45ef4bb9fd842bd2ffbca67"
+    },
+    "shadcn": {
+      "source": "shadcn/ui",
+      "sourceType": "github",
+      "computedHash": "873c67922d80775a9fdf596db7964b579f0408c30ec6e3d11989f6055bbec89f"
+    },
+    "vercel-composition-patterns": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "575757e3e25761c8c562d6e395d29f0b76c98b1273c0bd72d88e6ab1bc9c7d42"
+    },
+    "vercel-react-best-practices": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "43ca6c197f8ec13055079da7053232d477068b03ca443f9ac1bc819b95cdd432"
+    },
+    "vercel-react-native-skills": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "41d24eafa7c3d82e270439808f7cfbc4d51aeb2d14f2809a2267c16275784d06"
+    },
+    "vercel-react-view-transitions": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "c8952fc9127fa0564d0cb71dccb4215a5608ac933b5831104f09173a97a46f85"
+    },
+    "web-design-guidelines": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "f3bc47f890f42a44db1007ab390709ec368e4b8c089baee6b0007182236ac474"
+    }
+  }
+}

package/templates/next-monorepo/apps/web/tests/e2e/smoke.spec.ts

@@ -0,0 +1,13 @@
+import AxeBuilder from "@axe-core/playwright"
+import { expect, test } from "@playwright/test"
+
+test("homepage smoke flow passes accessibility checks", async ({ page }) => {
+  await page.goto("/")
+
+  await expect(
+    page.getByRole("heading", { name: "Project ready!" }),
+  ).toBeVisible()
+
+  const results = await new AxeBuilder({ page }).analyze()
+  expect(results.violations).toEqual([])
+})

package/templates/next-monorepo/apps/web/tests/unit/page.test.tsx

@@ -0,0 +1,16 @@
+import { render, screen } from "@testing-library/react"
+
+import Page from "@/app/page"
+
+describe("Page", () => {
+  it("renders the starter copy", () => {
+    render(<Page />)
+
+    expect(
+      screen.getByRole("heading", { name: "Project ready!" }),
+    ).toBeInTheDocument()
+    expect(
+      screen.getByText("You may now add components and start building."),
+    ).toBeInTheDocument()
+  })
+})

package/templates/next-monorepo/apps/web/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "@workspace/typescript-config/nextjs.json",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"],
+      "@workspace/ui/*": ["../../packages/ui/src/*"]
+    },
+    "types": ["vitest/globals"],
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "next.config.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/next-monorepo/apps/web/vitest.config.ts

@@ -0,0 +1,13 @@
+import react from "@vitejs/plugin-react"
+import tsconfigPaths from "vite-tsconfig-paths"
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  test: {
+    environment: "jsdom",
+    globals: true,
+    include: ["tests/unit/**/*.test.ts?(x)"],
+    setupFiles: ["./vitest.setup.ts"],
+  },
+})

package/templates/next-monorepo/apps/web/vitest.setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest"

package/templates/next-monorepo/docs/DESIGN.md

@@ -0,0 +1,11 @@
+# Design
+
+Use this file as the entrypoint for design-oriented knowledge.
+
+- Design document index: `design-docs/index.md`
+- Core beliefs: `design-docs/core-beliefs.md`
+- Included design and frontend skills: `design-docs/included-skills.md`
+- Design-system references for agents: `references/design-system-reference-llms.txt`
+
+The default starter is intentionally minimal.
+Any major visual direction change should start with a short note in `design-docs/`.

package/templates/next-monorepo/docs/FRONTEND.md

@@ -0,0 +1,32 @@
+# Frontend
+
+## Scope
+
+This template is frontend-first.
+Most product work will happen in `apps/web` and `packages/ui`.
+
+## Shared UI Package
+
+Use these public paths from `@workspace/ui`:
+
+- `@workspace/ui/ui/*` for shared rendering components
+- `@workspace/ui/runtime/*` for runtime helpers
+- `@workspace/ui/providers/*` for explicit cross-cutting boundaries
+
+Do not reintroduce `components`, `hooks`, or `lib` as top-level shared package layers.
+
+## Component Workflow
+
+Add shared primitives with:
+
+```bash
+pnpm dlx shadcn@latest add button -c apps/web
+```
+
+Generated shared components should land in `packages/ui/src/ui`.
+
+## App-Level Frontend Rules
+
+- Keep app code aligned with the `app -> components -> hooks -> lib` constraints
+- Prefer package imports over deep relative imports
+- Re-run the affected lint and typecheck lanes before handoff

package/templates/next-monorepo/docs/PLANS.md

@@ -0,0 +1,25 @@
+# Plans
+
+Plans are first-class artifacts in this template.
+
+## Planning Model
+
+- small, transient work may use a short local plan without a committed plan file
+- complex or multi-step work should create an execution plan in `docs/exec-plans/active/`
+- finished execution plans move to `docs/exec-plans/completed/`
+- known cleanup and follow-up items live in `docs/exec-plans/tech-debt-tracker.md`
+- repeated operational work belongs in `docs/exec-plans/repeated-work.md`
+
+## Required Sections For Execution Plans
+
+Every execution plan in `active/` or `completed/` should include:
+
+- `## Status`
+- `## Scope`
+- `## Steps`
+- `## Progress Log`
+- `## Decision Log`
+
+## Operating Rule
+
+Execution plans, completed plans, and tech debt are all versioned and stored in the repository so agents can work without hidden external context.

package/templates/next-monorepo/docs/PRODUCT_SENSE.md

@@ -0,0 +1,11 @@
+# Product Sense
+
+This starter is optimized for getting a new user from scaffold to confident first edit quickly.
+
+The default experience should communicate:
+
+- the project is wired correctly
+- shared UI is available immediately
+- the next step is to add product-specific components and flows
+
+Detailed specs live in `product-specs/`.

package/templates/next-monorepo/docs/QUALITY_SCORE.md

@@ -0,0 +1,18 @@
+# Quality Score
+
+Use this rubric when reviewing the starter or changes to it.
+
+## High Quality Means
+
+- architecture boundaries are mechanically enforced
+- local commands and CI lanes are aligned
+- the first-run experience is clear
+- shared UI imports are easy to discover
+- generated code has an obvious home
+
+## Red Flags
+
+- hidden coupling across layers
+- broken type paths after scaffolding
+- docs that disagree with commands
+- cross-cutting concerns bypassing `providers`

package/templates/next-monorepo/docs/RELIABILITY.md

@@ -0,0 +1,37 @@
+# Reliability
+
+## Local Commands
+
+Run from the repository root:
+
+```bash
+just install
+pnpm dev
+just lint
+just typecheck
+just test
+just ux
+just supply-chain
+just ci
+```
+
+## Lane Responsibilities
+
+- `just lint`: app lint plus shared UI dependency-layer checks
+- `just typecheck`: TypeScript validation for `apps/web`
+- `just test`: Vitest coverage for `apps/web`
+- `just ux`: Playwright, axe, and Lighthouse for the running app
+- `just supply-chain`: gitleaks, osv-scanner, and `pnpm audit`
+
+## CI
+
+GitHub Actions uses four jobs in `.github/workflows/ci.yml`:
+
+- `fast`
+- `test`
+- `ux`
+- `supply-chain`
+
+## Doc Gardening
+
+Doc gardening is a repeated manual task tracked in `docs/exec-plans/repeated-work.md`.

package/templates/next-monorepo/docs/SECURITY.md

@@ -0,0 +1,14 @@
+# Security
+
+This starter focuses on basic supply-chain and secret hygiene.
+
+## Included Checks
+
+- `gitleaks` for secret scanning
+- `osv-scanner` for dependency vulnerability scanning
+- `pnpm audit` for Node package alerts
+
+## Expectations
+
+- do not commit secrets
+- keep dependencies current

package/templates/next-monorepo/docs/design-docs/core-beliefs.md

@@ -0,0 +1,6 @@
+# Core Beliefs
+
+- the starter should feel ready immediately after scaffold
+- shared UI should be discoverable without hunting through the repo
+- architecture rules should be machine-enforced, not social-only
+- defaults should stay simple enough for agents and humans to extend safely

package/templates/next-monorepo/docs/design-docs/included-skills.md

@@ -0,0 +1,13 @@
+# Included Skills
+
+The web app ships with design and frontend reference skills in `apps/web/skills-lock.json`.
+
+- `frontend-design`
+- `shadcn`
+- `vercel-composition-patterns`
+- `vercel-react-best-practices`
+- `vercel-react-native-skills`
+- `vercel-react-view-transitions`
+- `web-design-guidelines`
+
+Treat these as scaffolded defaults for UI and interaction work.

package/templates/next-monorepo/docs/design-docs/index.md

@@ -0,0 +1,6 @@
+# Design Docs Index
+
+- [Core Beliefs](./core-beliefs.md)
+- [Included Skills](./included-skills.md)
+
+Add new design notes here when the frontend or developer experience changes materially.

package/templates/next-monorepo/docs/exec-plans/active/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-monorepo/docs/exec-plans/completed/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-monorepo/docs/exec-plans/repeated-work.md

@@ -0,0 +1,15 @@
+# Repeated Work
+
+## Doc Gardening
+
+The knowledge base needs periodic manual gardening.
+
+Repeat this work when template behavior, architecture rules, onboarding flow, or public commands change:
+
+- review `AGENTS.md` and `ARCHITECTURE.md`
+- review `docs/design-docs/`, `docs/product-specs/`, and `docs/references/`
+- move stale execution plans from `active/` to `completed/`
+- update `tech-debt-tracker.md` when cleanup work is discovered
+- remove outdated or irrelevant references that no longer match the stack
+
+This work is intentionally documented here rather than automated in CI.

package/templates/next-monorepo/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,3 @@
+# Tech Debt Tracker
+
+This document should contain active cleanup items, follow-up work, and known template debt.

package/templates/next-monorepo/docs/generated/db-schema.md

@@ -0,0 +1,3 @@
+# DB Schema
+
+This document should contain the current database schema snapshot when the template adds persistence.

package/templates/next-monorepo/docs/product-specs/index.md

@@ -0,0 +1,5 @@
+# Product Specs Index
+
+- [New User Onboarding](./new-user-onboarding.md)
+
+Add product-specific specs here when the starter grows beyond the baseline onboarding flow.

package/templates/next-monorepo/docs/product-specs/new-user-onboarding.md

@@ -0,0 +1,12 @@
+# New User Onboarding
+
+## Goal
+
+A newly scaffolded project should give a user confidence that the app is wired correctly within a minute.
+
+## Default Experience
+
+- the home page renders without extra setup
+- the shared button component is already usable
+- dark mode can be toggled
+- the next implementation step is obvious

package/templates/next-monorepo/docs/references/design-system-reference-llms.txt

@@ -0,0 +1,13 @@
+This reference should contain only design-system facts for the shared UI package.
+
+Current baseline:
+- UI system: `shadcn`
+- style preset: `radix-lyra`
+- Tailwind base color: `neutral`
+- CSS variables: enabled
+- icon library: `lucide`
+- theme tokens live in `packages/ui/src/styles/globals.css`
+- the starter includes light and dark theme tokens using OKLCH color values
+- the radius scale is derived from `--radius: 0.625rem`
+
+Update this file when the component style, token set, icon set, or theming rules change.

package/templates/next-monorepo/justfile

@@ -0,0 +1,26 @@
+set shell := ["bash", "-cu"]
+
+install:
+  mise install
+  pnpm install --frozen-lockfile
+  pnpm exec playwright install chromium
+
+lint:
+  pnpm --filter web lint
+  pnpm --dir packages/ui exec depcruise --config dependency-cruiser.cjs src
+
+typecheck:
+  pnpm --filter web typecheck
+
+test:
+  pnpm --filter web test
+
+ux:
+  pnpm --filter web ux
+
+supply-chain:
+  gitleaks dir . --config .gitleaks.toml
+  osv-scanner scan source -r .
+  pnpm audit --audit-level=high
+
+ci: lint typecheck test ux supply-chain

package/templates/next-monorepo/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  parallel: true
+  commands:
+    lint:
+      run: just lint
+    typecheck:
+      run: just typecheck
+

package/templates/next-monorepo/mise.toml

@@ -0,0 +1,4 @@
+[tools]
+node = "20"
+pnpm = "9.15.9"
+

package/templates/next-monorepo/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "next-monorepo",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "build": "turbo build",
+    "dev": "turbo dev --filter=web",
+    "lint": "just lint",
+    "format": "pnpm --filter web format",
+    "typecheck": "just typecheck",
+    "test": "just test",
+    "ux": "just ux",
+    "supply-chain": "just supply-chain",
+    "ci": "just ci"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.0",
+    "@biomejs/biome": "^1.9.4",
+    "@lhci/cli": "^0.15.1",
+    "@playwright/test": "^1.51.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "@workspace/eslint-config": "workspace:*",
+    "@workspace/typescript-config": "workspace:*",
+    "dependency-cruiser": "^17.1.0",
+    "jsdom": "^26.1.0",
+    "knip": "^5.44.4",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "start-server-and-test": "^3.0.2",
+    "turbo": "^2.8.17",
+    "typescript": "5.9.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/next-monorepo/packages/eslint-config/README.md

@@ -0,0 +1,3 @@
+# `@workspace/eslint-config`
+
+Shared eslint configuration for the workspace.

package/templates/next-monorepo/packages/eslint-config/base.js

@@ -0,0 +1,32 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import onlyWarn from "eslint-plugin-only-warn"
+import turboPlugin from "eslint-plugin-turbo"
+import tseslint from "typescript-eslint"
+
+/**
+ * A shared ESLint configuration for the repository.
+ *
+ * @type {import("eslint").Linter.Config}
+ * */
+export const config = [
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      turbo: turboPlugin,
+    },
+    rules: {
+      "turbo/no-undeclared-env-vars": "warn",
+    },
+  },
+  {
+    plugins: {
+      onlyWarn,
+    },
+  },
+  {
+    ignores: ["dist/**", ".next/**", "**/.turbo/**", "**/coverage/**"],
+  },
+]

package/templates/next-monorepo/packages/eslint-config/next.js

@@ -0,0 +1,51 @@
+import js from "@eslint/js"
+import pluginNext from "@next/eslint-plugin-next"
+import eslintConfigPrettier from "eslint-config-prettier"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+import { config as baseConfig } from "./base.js"
+
+/**
+ * A custom ESLint configuration for libraries that use Next.js.
+ *
+ * @type {import("eslint").Linter.Config}
+ * */
+export const nextJsConfig = [
+  ...baseConfig,
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    ...pluginReact.configs.flat.recommended,
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+      },
+    },
+  },
+  {
+    plugins: {
+      "@next/next": pluginNext,
+    },
+    rules: {
+      ...pluginNext.configs.recommended.rules,
+      ...pluginNext.configs["core-web-vitals"].rules,
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      // React scope no longer necessary with new JSX transform.
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+    },
+  },
+]

package/templates/next-monorepo/packages/eslint-config/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@workspace/eslint-config",
+  "version": "0.0.0",
+  "type": "module",
+  "private": true,
+  "exports": {
+    "./base": "./base.js",
+    "./next-js": "./next.js",
+    "./react-internal": "./react-internal.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@next/eslint-plugin-next": "^16.1.6",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-only-warn": "^1.1.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-turbo": "^2.8.1",
+    "globals": "^17.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0"
+  }
+}

package/templates/next-monorepo/packages/eslint-config/react-internal.js

@@ -0,0 +1,41 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+import { config as baseConfig } from "./base.js"
+
+/**
+ * A custom ESLint configuration for libraries that use React.
+ *
+ * @type {import("eslint").Linter.Config} */
+export const config = [
+  ...baseConfig,
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  pluginReact.configs.flat.recommended,
+  {
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+      },
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      // React scope no longer necessary with new JSX transform.
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+    },
+  },
+]

package/templates/next-monorepo/packages/typescript-config/README.md

@@ -0,0 +1,3 @@
+# `@workspace/typescript-config`
+
+Shared typescript configuration for the workspace.

package/templates/next-monorepo/packages/typescript-config/base.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Default",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": ["es2022", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleDetection": "force",
+    "moduleResolution": "NodeNext",
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022"
+  }
+}