agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/stacks/web-nextjs/claude/skills/design-component/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: design-component
+description: "Author a component in the design system — folder layout, API shape, tests, fixture, a11y. Use when adding or changing anything under src/design/."
+---
+
+# Authoring a design system component
+
+## Folder
+
+```
+src/design/{Name}/
+├── {Name}.tsx          # the component, nothing else
+├── {Name}.test.tsx     # interaction tests + one snapshot
+├── {Name}.fixture.tsx  # react-cosmos fixture
+├── types.ts            # props and any type this component owns
+└── index.ts            # public exports
+```
+
+Then add the component to `src/design/index.ts`.
+
+## Before writing
+
+1. Does a token exist for every value you are about to use? If not, add the
+   token first. Never hardcode a color, radius, spacing, or duration.
+2. Is there a native element with the right semantics? Use it. A `<div>`
+   with a click handler is a defect.
+3. Does this component need to know anything about the product? If yes, it
+   does not belong in `src/design/`.
+
+## API
+
+- accept `ref` as a prop — React 19 forwards it, `forwardRef` is legacy
+- merge `className` in, do not overwrite the caller's
+- spread remaining props onto the root
+- variants and sizes are unions (`"primary" | "danger"`), never independent
+  booleans that can contradict each other
+- no default that hides a required decision
+
+## Tests
+
+Interaction first, snapshot second.
+
+Browser mode, verified working shape:
+
+```tsx
+import { expect, test, vi } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Button } from "./Button";
+
+test("fires when clicked", async () => {
+  const onClick = vi.fn();
+  await render(<Button onClick={onClick}>Save</Button>);
+  await page.getByRole("button", { name: "Save" }).click();
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+
+test("does not fire when disabled", async () => {
+  const onClick = vi.fn();
+  await render(
+    <Button disabled onClick={onClick}>
+      Save
+    </Button>,
+  );
+  await expect.element(page.getByRole("button", { name: "Save" })).toBeDisabled();
+  expect(onClick).not.toHaveBeenCalled();
+});
+```
+
+`render` is async — await it. Query through `page`. Import from
+`vitest/browser`; `@vitest/browser/context` is deprecated.
+
+Always query by role **and** accessible name. Role alone passes on a button
+with no name, which is the defect a screen-reader user actually hits.
+
+Also cover: focus returns to the trigger when an overlay closes, and one
+snapshot per component for markup drift.
+
+`src/components/Button` and `src/components/Select` are the two worked
+examples — the native side of the line and the primitive side. Read them
+before writing a third.
+
+If the component wraps a third-party library, test *our* wrapper. A
+Dependabot bump that changes the library's behavior has to turn this suite
+red — that is the entire reason the suite exists.
+
+## Accessibility checklist
+
+- [ ] correct role, native element preferred
+- [ ] accessible name reachable by screen reader
+- [ ] full keyboard operation
+- [ ] Escape closes, focus returns to trigger (overlays)
+- [ ] focus ring visible in both themes
+- [ ] contrast holds in both themes
+
+## Done means
+
+Component, types, tests, fixture, barrel export, and a11y checklist — all
+of it. A component without a fixture is invisible to design comparison, and
+a component without interaction tests is untested.

package/template/.orchestra/stacks/web-nextjs/claude/skills/design-tokens/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: design-tokens
+description: "Extract tokens from the design source into Tailwind v4 @theme and the semantic theme layer. Use before writing any component, or when the design changes."
+---
+
+# Design tokens
+
+Tokens come first. A component written before the token system is a
+component that hardcodes values.
+
+## Extract every axis
+
+Color is the one people remember and the least sufficient. Pull all of it:
+
+| Axis | Examples |
+|---|---|
+| color | palette ramps, then semantic roles |
+| spacing | the scale, not ad-hoc values |
+| typography | family, size ramp, weight, line height |
+| radii | control vs surface |
+| shadow | elevation levels |
+| breakpoints | the real ones from the design, not Tailwind defaults |
+| z-index | named layers — overlay, modal, toast |
+| motion | durations and easings |
+
+## Two layers
+
+**Palette** goes in `@theme`. Raw values, no meaning attached.
+
+```css
+@theme {
+  --color-brand-500: oklch(0.62 0.19 250);
+}
+```
+
+**Semantic** maps meaning onto palette, and is what components use.
+
+```css
+:root          { --surface: var(--color-white); }
+[data-theme="dark"] { --surface: var(--color-brand-900); }
+```
+
+A component references `--surface`. It never references `--color-brand-500`.
+That is what makes a theme swap a one-file change.
+
+## Theming
+
+Three states must work: explicit light, explicit dark, and system default.
+
+- `[data-theme="dark"]` and `[data-theme="light"]` for an explicit choice
+- `@media (prefers-color-scheme: dark)` guarded with
+  `:root:not([data-theme="light"])` for the system default
+
+Never define a color only inside a media query — the explicit toggle will
+have nothing to override.
+
+## Tailwind v4
+
+There is no `tailwind.config.js`. `@theme` is the configuration, and its
+entries become real CSS custom properties. Do not add a JS config to make
+it feel familiar — you will end up with two sources of truth.

package/template/.orchestra/stacks/web-nextjs/setup.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Next.js App Router. Biome via the native create-next-app flag, Tailwind v4,
+# react-cosmos workbench, Vitest browser mode, Playwright 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"
+
+# --biome is native now, so we never install eslint just to remove it.
+# --disable-git because we are already inside a repo.
+# create-next-app does not create intermediate directories, and when the
+# parent is missing it reports "The application path is not writable, please
+# check folder permissions" — which sends you after the wrong thing entirely.
+mkdir -p "$(dirname "$DIR")"
+
+log "scaffolding next.js into $DIR"
+npx --yes create-next-app@latest "$DIR" \
+  --ts --app --src-dir --tailwind --biome --use-npm --skip-install --disable-git --yes </dev/null
+
+assert_scaffolded "$DIR"
+cd "$DIR"
+
+setup_yarn
+yarn_install
+
+# create-next-app writes its own CLAUDE.md, which would collide with the
+# stack's convention pack. AGENTS.md is kept — it does not clash.
+rm -f CLAUDE.md
+
+setup_typescript
+setup_node_pin
+setup_typecheck_script
+
+add_latest @sentry/nextjs 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 start --port 3000" "http://localhost:3000"
+setup_axe_e2e
+setup_bundle_budget
+
+pkg_set scripts.cosmos="cosmos" scripts.lint="biome check ." scripts.format="biome format --write ."
+
+# Next generates LayoutProps/PageProps into .next/types. On a clean checkout —
+# which is what CI is — they do not exist yet and tsc fails on them, so
+# generate before typechecking.
+pkg_set scripts.typecheck="next typegen && tsc -b --noEmit"
+# --json, or npm writes the string "false" and bundlers treat it as a glob.
+pkg_set sideEffects=false
+
+log "writing design system skeleton"
+mkdir -p src/design/helpers
+cat > src/design/tokens.css <<'CSS'
+@import "tailwindcss";
+
+/* Populate from the Claude Design source before writing any component.
+   Color is one axis of several — do not stop there. */
+@theme {
+  --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);
+  --radius-control: 0.5rem;
+  --font-sans: system-ui, sans-serif;
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --duration-fast: 120ms;
+}
+
+: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
+
+printf 'export type ThemeName = "light" | "dark";\nexport type Size = "sm" | "md" | "lg";\n' > src/design/types.ts
+printf 'export * from "./types";\n' > src/design/index.ts
+
+# create-next-app writes its own globals.css and imports it from the root
+# layout. Without this the tokens file exists and is never loaded.
+GLOBALS="$(find src/app -maxdepth 1 -name 'globals.css' | head -1)"
+if [ -n "$GLOBALS" ]; then
+  # tokens.css already does `@import "tailwindcss"` — drop the duplicate.
+  node -e '
+    const fs = require("fs");
+    const f = process.argv[1];
+    let s = fs.readFileSync(f, "utf8");
+    s = s.replace(/^@import\s+["\x27]tailwindcss["\x27];\s*$/m, "");
+    if (!s.includes("design/tokens.css")) {
+      s = `@import "../design/tokens.css";\n` + s;
+    }
+    fs.writeFileSync(f, s.trimStart() + "\n");
+  ' "$GLOBALS"
+  log "design tokens imported from $GLOBALS"
+else
+  warn "globals.css not found — import src/design/tokens.css manually or tokens will not load"
+fi
+
+# create-next-app --biome installs biome at whatever version its template
+# pinned and writes a bare biome.json. Running the shared setup brings the
+# version to current and applies the config the rest of the stack relies on
+# — tailwindDirectives, and excludes so build output is not linted.
+setup_biome
+
+install_pre_commit_gate
+setup_integrations_dir
+setup_ui_primitives client
+
+setup_coverage
+setup_mutation
+
+# create-next-app ships "@types/node": "^20" and friends. Nothing above
+# touches them, so without this the repo is born several majors behind.
+refresh_scaffold_deps
+# Everything above was generated after setup_biome formatted the scaffold.
+# Without this the first commit is rejected by the gate we just installed.
+yarn biome check --write . >/dev/null 2>&1 || true
+
+assert_verification_scripts
+assert_scaffold_clean
+log "web-nextjs ready in $DIR"

package/template/.orchestra/stacks/web-nextjs/stack.md

@@ -0,0 +1,170 @@
+# Web — Next.js (App Router)
+
+## Who you are
+
+You are a **senior frontend engineer** who understands where code runs.
+Server Components by default; `"use client"` only where interactivity
+genuinely requires it, and as far down the tree as possible. A page that
+ships the whole app to the browser because one leaf needed state is a
+defect.
+
+SOLID, KISS, YAGNI. No overengineering — when it starts feeling clever,
+simplify.
+
+## Structure
+
+Everything under `src/`.
+
+```
+src/
+├── app/                    # routes, layouts, server components
+├── design/                 # the UI kit. no business logic. ever.
+│   ├── tokens.css
+│   ├── types.ts
+│   ├── helpers/
+│   ├── index.ts
+│   └── Button/
+│       ├── Button.tsx
+│       ├── Button.test.tsx
+│       ├── Button.fixture.tsx
+│       ├── types.ts
+│       └── index.ts
+└── ...
+```
+
+Every component gets its own folder: component, tests, fixture, types,
+`index.ts`. Uniform, no exceptions.
+
+`src/design/` holds nothing that is not design. A component may contain
+logic about itself; never about your product.
+
+## Server and client
+
+- Design system components are presentational and mostly client-safe, but
+  do not add `"use client"` reflexively — only when the component actually
+  uses state, effects, or browser APIs.
+- Data fetching belongs in Server Components, not in `useEffect`.
+- Never leak a secret into a client component. It ships to the browser.
+
+## Order of work
+
+Tokens before components. Always.
+
+1. Extract every token from the design source — color, spacing, typography,
+   radii, shadows, breakpoints, z-index, motion.
+2. Write them into `src/design/tokens.css` under `@theme`.
+3. Add the semantic layer and the dark variant.
+4. Then write components.
+
+Hardcoded colors or spacing are bugs. Reject them in review.
+
+## Tailwind v4
+
+Configuration is CSS, not `tailwind.config.js`. `@theme` entries become
+real CSS custom properties, so tokens and theming are one system. Do not
+add a JS config file.
+
+## 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 — and on the server it is shared
+  by every request. Give it a maximum and an eviction rule, and never put a
+  request's data in it.
+
+## Testing
+
+Coverage target is effectively total. The deciding rule:
+
+> If one of our functions calls into a third-party library, that function
+> has a test. When Dependabot bumps the library and behavior changes, the
+> test must fail.
+
+- **Interaction tests** (Vitest browser mode, Playwright driver) — primary.
+- **Snapshots** — secondary, markup drift only. Snapshot-only is untested.
+- **E2E** (`@playwright/test`) — flows across routes.
+
+Server Components need tests too: assert what they render given data, and
+that they do not reach for browser APIs.
+
+## Accessibility
+
+Structural. Every component: correct role and native element first,
+reachable accessible name, full keyboard operation, Escape and focus return
+for overlays, visible focus in both themes, contrast holding in both.
+
+## Component API
+
+Forward `ref`, merge `className`, spread the rest. Variants and sizes are
+unions, not booleans that can contradict. Props types live in the
+component's folder and export from its `index.ts`.
+
+## Workbench
+
+`react-cosmos` (`npm run cosmos`). Every component has a fixture — it is
+the catalog and the stable render target for design comparison.
+
+## Tooling
+
+Biome for lint and format, installed natively by `create-next-app --biome`.
+No ESLint, no Prettier. TypeScript strict with `noUncheckedIndexedAccess`.

package/template/.orchestra/stacks/web-vite-react/claude/commands/component.md

@@ -0,0 +1,12 @@
+Scaffold a new design system component.
+
+Usage: `/web:component {Name}`
+
+1. Load the `design-component` skill and follow it exactly.
+2. Confirm every value the component needs has a token. If one is missing,
+   add it to `src/design/tokens.css` first — do not hardcode.
+3. Create `src/design/{Name}/` with the component, types, tests, fixture,
+   and `index.ts`.
+4. Export it from `src/design/index.ts`.
+5. Run `npm run typecheck && npm test && npm run lint`.
+6. Report the a11y checklist with each item explicitly checked or flagged.

package/template/.orchestra/stacks/web-vite-react/claude/skills/design-component/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: design-component
+description: "Author a component in the design system — folder layout, API shape, tests, fixture, a11y. Use when adding or changing anything under src/design/."
+---
+
+# Authoring a design system component
+
+## Folder
+
+```
+src/design/{Name}/
+├── {Name}.tsx          # the component, nothing else
+├── {Name}.test.tsx     # interaction tests + one snapshot
+├── {Name}.fixture.tsx  # react-cosmos fixture
+├── types.ts            # props and any type this component owns
+└── index.ts            # public exports
+```
+
+Then add the component to `src/design/index.ts`.
+
+## Before writing
+
+1. Does a token exist for every value you are about to use? If not, add the
+   token first. Never hardcode a color, radius, spacing, or duration.
+2. Is there a native element with the right semantics? Use it. A `<div>`
+   with a click handler is a defect.
+3. Does this component need to know anything about the product? If yes, it
+   does not belong in `src/design/`.
+
+## API
+
+- accept `ref` as a prop — React 19 forwards it, `forwardRef` is legacy
+- merge `className` in, do not overwrite the caller's
+- spread remaining props onto the root
+- variants and sizes are unions (`"primary" | "danger"`), never independent
+  booleans that can contradict each other
+- no default that hides a required decision
+
+## Tests
+
+Interaction first, snapshot second.
+
+Browser mode, verified working shape:
+
+```tsx
+import { expect, test, vi } from "vitest";
+import { page } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Button } from "./Button";
+
+test("fires when clicked", async () => {
+  const onClick = vi.fn();
+  await render(<Button onClick={onClick}>Save</Button>);
+  await page.getByRole("button", { name: "Save" }).click();
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+
+test("does not fire when disabled", async () => {
+  const onClick = vi.fn();
+  await render(
+    <Button disabled onClick={onClick}>
+      Save
+    </Button>,
+  );
+  await expect.element(page.getByRole("button", { name: "Save" })).toBeDisabled();
+  expect(onClick).not.toHaveBeenCalled();
+});
+```
+
+`render` is async — await it. Query through `page`. Import from
+`vitest/browser`; `@vitest/browser/context` is deprecated.
+
+Always query by role **and** accessible name. Role alone passes on a button
+with no name, which is the defect a screen-reader user actually hits.
+
+Also cover: focus returns to the trigger when an overlay closes, and one
+snapshot per component for markup drift.
+
+`src/components/Button` and `src/components/Select` are the two worked
+examples — the native side of the line and the primitive side. Read them
+before writing a third.
+
+If the component wraps a third-party library, test *our* wrapper. A
+Dependabot bump that changes the library's behavior has to turn this suite
+red — that is the entire reason the suite exists.
+
+## Accessibility checklist
+
+- [ ] correct role, native element preferred
+- [ ] accessible name reachable by screen reader
+- [ ] full keyboard operation
+- [ ] Escape closes, focus returns to trigger (overlays)
+- [ ] focus ring visible in both themes
+- [ ] contrast holds in both themes
+
+## Done means
+
+Component, types, tests, fixture, barrel export, and a11y checklist — all
+of it. A component without a fixture is invisible to design comparison, and
+a component without interaction tests is untested.

package/template/.orchestra/stacks/web-vite-react/claude/skills/design-tokens/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: design-tokens
+description: "Extract tokens from the design source into Tailwind v4 @theme and the semantic theme layer. Use before writing any component, or when the design changes."
+---
+
+# Design tokens
+
+Tokens come first. A component written before the token system is a
+component that hardcodes values.
+
+## Extract every axis
+
+Color is the one people remember and the least sufficient. Pull all of it:
+
+| Axis | Examples |
+|---|---|
+| color | palette ramps, then semantic roles |
+| spacing | the scale, not ad-hoc values |
+| typography | family, size ramp, weight, line height |
+| radii | control vs surface |
+| shadow | elevation levels |
+| breakpoints | the real ones from the design, not Tailwind defaults |
+| z-index | named layers — overlay, modal, toast |
+| motion | durations and easings |
+
+## Two layers
+
+**Palette** goes in `@theme`. Raw values, no meaning attached.
+
+```css
+@theme {
+  --color-brand-500: oklch(0.62 0.19 250);
+}
+```
+
+**Semantic** maps meaning onto palette, and is what components use.
+
+```css
+:root          { --surface: var(--color-white); }
+[data-theme="dark"] { --surface: var(--color-brand-900); }
+```
+
+A component references `--surface`. It never references `--color-brand-500`.
+That is what makes a theme swap a one-file change.
+
+## Theming
+
+Three states must work: explicit light, explicit dark, and system default.
+
+- `[data-theme="dark"]` and `[data-theme="light"]` for an explicit choice
+- `@media (prefers-color-scheme: dark)` guarded with
+  `:root:not([data-theme="light"])` for the system default
+
+Never define a color only inside a media query — the explicit toggle will
+have nothing to override.
+
+## Tailwind v4
+
+There is no `tailwind.config.js`. `@theme` is the configuration, and its
+entries become real CSS custom properties. Do not add a JS config to make
+it feel familiar — you will end up with two sources of truth.