agentic-team 0.0.0-stage → 6.1.0

package/template/.orchestra/stacks/web-vite-react/setup.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# React SPA on Vite. Tailwind v4 (CSS-first config), react-cosmos workbench,
+# Vitest browser mode driven by Playwright, Playwright for e2e.
+set -euo pipefail
+
+DIR="${1:?usage: setup.sh <target-dir>}"
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)"
+# shellcheck source=../_lib/common.sh
+source "$LIB/common.sh"
+
+log "scaffolding vite + react-ts into $DIR"
+npm create vite@latest "$DIR" -- --template react-ts </dev/null
+assert_scaffolded "$DIR"
+cd "$DIR"
+
+setup_yarn
+yarn_install
+
+setup_typescript
+setup_biome
+setup_node_pin
+setup_typecheck_script
+
+add_latest tailwindcss @tailwindcss/vite
+add_latest @sentry/react posthog-js
+add_latest --dev react-cosmos
+setup_vitest_browser
+# The API seam, faked at the network layer. Mocking our own fetch wrapper
+# instead would leave the wrapper — the thing that breaks when the API
+# changes — untested.
+add_latest --dev msw
+setup_axe
+setup_playwright_e2e "yarn build && yarn preview --port 4173" "http://localhost:4173"
+setup_axe_e2e
+setup_bundle_budget
+
+pkg_set scripts.cosmos="cosmos"
+
+log "writing design system skeleton"
+mkdir -p src/design/helpers
+
+# Tailwind v4 configures in CSS. @theme entries become real CSS custom
+# properties, which is also the theming mechanism — one system, not two.
+cat > src/design/tokens.css <<'CSS'
+@import "tailwindcss";
+
+/* Design tokens. Populated from the Claude Design source before any
+   component is written. Colors are only one axis — do not stop there. */
+@theme {
+  /* color */
+  --color-brand-50: oklch(0.97 0.02 250);
+  --color-brand-500: oklch(0.62 0.19 250);
+  --color-brand-900: oklch(0.35 0.12 250);
+
+  /* spacing scale */
+  --spacing-gutter: 1rem;
+
+  /* radii */
+  --radius-control: 0.5rem;
+  --radius-surface: 0.75rem;
+
+  /* typography */
+  --font-sans: system-ui, sans-serif;
+  --text-caption: 0.75rem;
+
+  /* motion */
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --duration-fast: 120ms;
+
+  /* elevation */
+  --shadow-surface: 0 1px 2px rgb(0 0 0 / 0.08);
+}
+
+/* Semantic layer. Components reference these, never raw palette values,
+   so a theme swap never requires touching a component. */
+:root {
+  --surface: var(--color-white);
+  --on-surface: var(--color-brand-900);
+}
+
+[data-theme="dark"] {
+  --surface: var(--color-brand-900);
+  --on-surface: var(--color-brand-50);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --surface: var(--color-brand-900);
+    --on-surface: var(--color-brand-50);
+  }
+}
+CSS
+
+cat > src/design/types.ts <<'TS'
+// Shared design-system types only. Nothing app-specific, no business logic.
+
+export type ThemeName = "light" | "dark";
+
+export type Size = "sm" | "md" | "lg";
+TS
+
+cat > src/design/index.ts <<'TS'
+// Barrel for the design system. Every component re-exports from here.
+// Keep the build ESM and `sideEffects: false` so this stays tree-shakeable.
+
+export * from "./types";
+TS
+
+# --json, or npm writes the string "false" and bundlers treat it as a glob.
+pkg_set sideEffects=false
+
+if [ -f src/index.css ]; then
+  printf '@import "./design/tokens.css";\n' | cat - src/index.css > src/index.css.tmp
+  mv src/index.css.tmp src/index.css
+else
+  printf '@import "./design/tokens.css";\n' > src/index.css
+fi
+
+node -e '
+  const fs = require("fs");
+  const f = fs.existsSync("vite.config.ts") ? "vite.config.ts" : "vite.config.js";
+  let s = fs.readFileSync(f, "utf8");
+  if (!s.includes("@tailwindcss/vite")) {
+    s = `import tailwindcss from "@tailwindcss/vite";\n` + s;
+    s = s.replace(/plugins:\s*\[/, "plugins: [tailwindcss(), ");
+    fs.writeFileSync(f, s);
+  }
+'
+
+install_pre_commit_gate
+setup_integrations_dir
+setup_ui_primitives
+
+setup_coverage
+setup_mutation
+# Replace the Vite demo. It fails the lint gate we just installed
+# (non-null assertion, ambiguous anchor text) and every real project deletes
+# it anyway — leaving it means the first commit is rejected.
+cat > src/main.tsx <<'TSX'
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("root element not found");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+TSX
+
+cat > src/App.tsx <<'TSX'
+export default function App() {
+  return (
+    <main className="min-h-dvh bg-[var(--surface)] text-[var(--on-surface)]">
+      <h1 className="p-[var(--spacing-gutter)] text-2xl">App</h1>
+    </main>
+  );
+}
+TSX
+rm -f src/App.css
+node -e '
+  const fs = require("fs");
+  const f = "src/index.css";
+  if (!fs.existsSync(f)) process.exit(0);
+  const kept = fs.readFileSync(f, "utf8")
+    .split("\n")
+    .filter((l) => l.includes("design/tokens.css"))
+    .join("\n");
+  fs.writeFileSync(f, (kept || `@import "./design/tokens.css";`) + "\n");
+'
+
+# create-vite writes its own dependency versions and they are only current
+# on the day its template shipped. Bring them up before the first commit.
+refresh_scaffold_deps
+
+# Format again — the files above were just rewritten.
+yarn biome check --write . >/dev/null 2>&1 || true
+
+assert_verification_scripts
+assert_scaffold_clean
+log "web-vite-react ready in $DIR"

package/template/.orchestra/stacks/web-vite-react/stack.md

@@ -0,0 +1,177 @@
+# Web — React SPA (Vite)
+
+## Who you are
+
+You are a **senior frontend engineer**. You care about accessibility,
+render cost, and the honesty of a component's API. You do not reach for a
+library when twenty lines of your own will do, and you do not hand-roll
+what a mature library already solves.
+
+SOLID, KISS, YAGNI. When a design starts feeling clever, it is wrong —
+simplify it. No overengineering.
+
+## Structure
+
+Everything lives under `src/`.
+
+```
+src/
+├── design/                 # the UI kit. no business logic. ever.
+│   ├── tokens.css          # @theme tokens + semantic theme layer
+│   ├── types.ts            # shared design types only
+│   ├── helpers/            # one helper per file, named after the helper
+│   ├── index.ts            # barrel — everything public exits here
+│   └── Button/
+│       ├── Button.tsx
+│       ├── Button.test.tsx
+│       ├── Button.fixture.tsx
+│       ├── types.ts
+│       └── index.ts
+└── ...                     # app code
+```
+
+Every component gets its own folder. Inside it: the component in a file of
+its own name, its tests, its cosmos fixture, its types, and an `index.ts`
+that exports everything public. No exceptions — the structure is uniform so
+an agent can navigate it without reading a map.
+
+`src/design/` contains nothing that is not design. A component may hold
+logic about *itself*; it may not hold logic about your product.
+
+## Order of work
+
+Tokens exist before components do. Always.
+
+1. Read the Claude Design source. Extract every token — not just color.
+   Spacing, typography scale, radii, shadows, breakpoints, z-index layers,
+   motion durations and easings.
+2. Write them into `src/design/tokens.css` under `@theme`.
+3. Add the semantic layer (`--surface`, `--on-surface`, …) and the dark
+   variant. Components reference semantic names, never raw palette values.
+4. Only then write components.
+
+A component that hardcodes `#3b82f6` or `padding: 13px` is a bug, not a
+style preference. Reject it in review.
+
+## Tailwind v4
+
+Configuration is CSS, not `tailwind.config.js`. `@theme` entries compile to
+real CSS custom properties, which is why tokens and theming are one system
+here rather than two. Do not add a JS config file to "make it familiar."
+
+## Where a component comes from
+
+One question decides it:
+
+> Does the browser already give me the role, the keyboard behaviour and the
+> focus management?
+
+**Yes — write it.** `button`, `input`, `select`, `textarea`, `a`, `table`,
+`details`, `dialog` with `showModal()`, the Popover API. These carry their
+semantics for free, and a library on top of them buys a dependency and
+nothing else. Prefer the platform, and check its support at the time rather
+than trusting a table written here — that is the same rule dependencies
+follow.
+
+**No — use an unstyled primitive.** Combobox, listbox with custom content,
+menu with typeahead, tabs, date picker, slider. There is no element for
+these, so hand-writing one means re-implementing the WAI-ARIA authoring
+practice: roving focus, typeahead, dismissal layers, focus return,
+`aria-activedescendant`. That work is not a component, it is a library, and
+this stack runs axe as an assertion — so a hand-rolled one fails the gate
+over and over instead of once, at the library choice.
+
+`react-aria-components` is the default. It ships behaviour and **no styling**,
+it is tree-shaken per component, and it covers the patterns that have no
+element — including the date picker, which nothing should hand-roll. Radix is
+an acceptable substitute; a styled kit like shadcn or MUI is not, because it
+brings someone else's opinion about your product.
+
+Tailwind stays. It is utility CSS, not components — it styles the elements we
+write.
+
+### The line is not a style preference
+
+Take the worked `Select` and swap the primitive's `Popover` for a plain
+`div`, which is what a hand-rolled version is. Opening still works, selecting
+still works, and **axe still passes**. The only thing that breaks is Escape
+returning focus to the trigger — a keyboard user is silently dropped at the
+top of the document.
+
+That is the whole argument. The failure is invisible to the linter, invisible
+to a snapshot, and invisible in review. It is only visible to an interaction
+test, which is why `src/components/Select/Select.test.tsx` has one.
+
+A primitive is **not** an `src/integrations/` seam — it is neither an SDK call
+nor an HTTP API, so it lives with the component that uses it. Its coverage
+comes from the interaction test driving the real thing, which is a stronger
+check than a line-count gate.
+## Memory — the collector cannot end what you still hold
+
+React does not free a subscription for you, and the collector cannot free
+what a live closure still references. So:
+
+- **Every effect that starts something returns the function that stops
+  it.** `addEventListener` → `removeEventListener`; `setInterval` →
+  `clearInterval`; `subscribe` → `unsubscribe`; a fetch → an
+  `AbortController` aborted in the cleanup. The gate checks that the cleanup
+  exists; only you can check that it stops the right thing.
+- State that only grows is a leak with a UI. A list that appends on every
+  event and never trims, a map of every id ever seen — bound it, or key it
+  by what is on screen.
+- A closure created in render captures the render's state and is recreated
+  every render. That is by design; it becomes a cost when it is passed to a
+  memoized child or a long list. `.claude/rules/performance.orchestra.md`
+  says where that matters.
+- A module-level cache is process-lifetime. Give it a maximum and an
+  eviction rule, or it is the thing that grows with uptime.
+
+## Testing
+
+Coverage target is effectively total. The rule that decides what to test:
+
+> If one of our functions calls into a third-party library, that function
+> has a test. When Dependabot bumps the library and the behavior changes,
+> the test must fail.
+
+That is the point of the suite — a green build is the merge signal.
+
+- **Interaction tests** (Vitest browser mode, Playwright driver) are the
+  primary form. They assert behavior: clicks fire, focus moves, disabled
+  means disabled.
+- **Snapshots** are secondary. They catch unintended markup drift and
+  nothing else. A snapshot-only component is untested — snapshots pass
+  happily while a handler silently stops firing.
+- **E2E** (`@playwright/test`) covers flows across screens, not components.
+
+## Accessibility
+
+Structural, not polish. Every component ships with:
+
+- a correct role, native element first (`<button>`, not `<div onClick>`)
+- a reachable accessible name
+- keyboard operation, including Escape and focus return for anything overlaid
+- visible focus that survives the theme
+- contrast that holds in light and dark
+
+An inaccessible component is incomplete, not "to be improved later."
+
+## Component API
+
+- Forward `ref`. Merge incoming `className`. Spread the rest onto the root.
+- Variants and sizes are props with union types, never booleans that
+  combine into nonsense (`primary` + `danger` at once).
+- Props types live in the component's own folder and are exported from its
+  `index.ts`.
+
+## Workbench
+
+`react-cosmos` (`npm run cosmos`). Every component has a fixture. It is the
+catalog, and it is the stable render target for design comparison — far
+more reliable to screenshot than a live app screen with real data in it.
+
+## Tooling
+
+Biome for lint and format — there is no ESLint or Prettier here, and adding
+one back means two formatters fighting. TypeScript is strict with
+`noUncheckedIndexedAccess`.