crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/deploy/references/topology-a.md

@@ -0,0 +1,128 @@
+# Topology A — self-managed host (phases 1-5)
+
+Read this only when Phase 0 answered **A**: you have SSH to a machine you own or rent, a release is a directory on
+that host, and rollback means moving a pointer back. On topology B read `references/topology-b.md` instead — never
+both, because mixing them is where deploys go wrong.
+
+The invariant rules in SKILL.md hold over everything here: no deploy without approval, back up before the swap,
+health-gate after it, keep the last three versions, the app binds to `127.0.0.1` only.
+
+## Phase 1 (A) — Surface: method and runtime
+
+```bash
+if   [ -f Dockerfile ] || [ -f docker-compose.yml ]; then METHOD=docker
+elif [ -f package.json ];                                then METHOD=bare RUNTIME=node
+elif [ -f requirements.txt ] || [ -f pyproject.toml ];   then METHOD=bare RUNTIME=python
+elif [ -f go.mod ];                                      then METHOD=bare RUNTIME=go
+elif ls ./*.csproj ./*.sln >/dev/null 2>&1;              then METHOD=bare RUNTIME=dotnet
+elif [ -f pom.xml ] || [ -f build.gradle ];              then METHOD=bare RUNTIME=java
+elif [ -f Cargo.toml ];                                  then METHOD=bare RUNTIME=rust
+elif [ -f Gemfile ];                                     then METHOD=bare RUNTIME=ruby
+elif [ -f composer.json ];                               then METHOD=bare RUNTIME=php
+else METHOD=unknown; fi
+```
+If `method: docker` and there's no Dockerfile, generate one. `method: bare` → a process manager suited to the runtime; build the release artefact with the runtime's own command (`dotnet publish -c Release`, `mvn package`, `cargo build --release`, …) and run it under systemd. Prefer Docker for any runtime whose bare setup needs a toolchain on the box. If detection is ambiguous, ask the user — never guess a runtime.
+
+---
+
+## Phase 2 (A) — Preparation: config, SSH, proxy, SSL
+
+**Config** — read `.deploy.yml` from the root, and if it's missing ask for each field:
+```yaml
+host: 192.168.1.100        # VPS IP/hostname (required)
+user: deploy               # SSH user (required)
+ssh_key: ~/.ssh/id_rsa     # private key
+app_port: 3000             # application port (required)
+health_check: /api/health  # HTTP path (default /)
+deploy_path: /var/www/app  # server path (required)
+method: auto               # auto | docker | bare
+domain: app.example.com    # for proxy/SSL (optional)
+ssl: true                  # default true if there is a domain
+reverse_proxy: auto        # auto | nginx | caddy
+```
+**Verify SSH first** — if you can't connect, stop immediately:
+```bash
+ssh -i $SSH_KEY -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new $USER@$HOST "echo OK"
+```
+
+**Reverse proxy** — detect the one installed on the server (`auto` → Caddy if present, otherwise Nginx). The application binds only to `127.0.0.1`; it is exposed outward **only** through the proxy.
+
+**SSL** — skip if `ssl: false` or there's no domain, and never on a bare IP. On the Nginx path, verify DNS resolves to the host (`dig +short $DOMAIN` = `$HOST`) *before* running Certbot; on the Caddy path the certificate and its renewal are automatic and there is no separate step.
+
+Config file contents for both proxies, the Certbot commands and the renewal timer: **`references/proxy-ssl.md`** — read the half for the proxy you found, not both.
+
+---
+
+## Phase 3 (A) — Swap: keep the old, put the new
+
+**First back up the running version** (timestamped `releases/`, last 3 kept):
+```bash
+ssh -i $SSH_KEY $USER@$HOST "
+  mkdir -p $DEPLOY_PATH/releases
+  [ -d $DEPLOY_PATH/current ] && cp -a $DEPLOY_PATH/current $DEPLOY_PATH/releases/$(date +%Y%m%d_%H%M%S)
+  cd $DEPLOY_PATH/releases && ls -dt */ | tail -n +4 | xargs -r rm -rf
+"
+```
+
+**Docker** — build the image locally, transfer it, replace the container:
+```bash
+docker build -t $APP:latest .
+docker save $APP:latest | gzip | ssh -i $SSH_KEY $USER@$HOST "gunzip | docker load"
+ssh -i $SSH_KEY $USER@$HOST "
+  docker rm -f $APP 2>/dev/null || true
+  docker run -d --name $APP --restart unless-stopped -p 127.0.0.1:$APP_PORT:$APP_PORT $APP:latest
+"
+```
+
+**Bare-metal** — `rsync` the source, install dependencies, start with the process manager:
+```bash
+rsync -avz --delete --exclude .git --exclude node_modules --exclude .venv \
+  -e "ssh -i $SSH_KEY" ./ $USER@$HOST:$DEPLOY_PATH/current/
+```
+
+| Runtime | Dependencies + startup |
+|---|---|
+| Node | `npm ci --production` → PM2: `pm2 start ecosystem.config.js --name $APP || pm2 start npm --name $APP -- start` → `pm2 save` |
+| Python | `python3 -m venv venv && venv/bin/pip install -r requirements.txt` → systemd (gunicorn/uvicorn or `python main.py`) |
+| Go | build locally `GOOS=linux GOARCH=amd64 go build -o $APP` → `scp` → systemd |
+
+systemd unit (for Python/Go, fill in ExecStart per the runtime):
+```ini
+[Unit]
+After=network.target
+[Service]
+Type=simple
+User=$USER
+WorkingDirectory=$DEPLOY_PATH/current
+ExecStart=<runtime command>
+Restart=always
+Environment=PORT=$APP_PORT
+[Install]
+WantedBy=multi-user.target
+```
+`systemctl daemon-reload && systemctl enable --now $APP`.
+
+---
+
+## Phase 4 (A) — Health gate
+
+Right after the swap; retry for ~30 s until a 200 comes back. **If it doesn't pass, trigger Phase 5 automatically.**
+```bash
+ssh -i $SSH_KEY $USER@$HOST '
+  for i in $(seq 1 6); do
+    [ "$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:'"$APP_PORT$HEALTH_CHECK"')" = 200 ] \
+      && { echo "Health gate PASSED"; exit 0; }
+    sleep 5
+  done
+  echo "Health gate FAILED"; exit 1
+'
+```
+Also verify the process is up: `docker ps` on Docker, otherwise `systemctl is-active $APP` / `pm2 show $APP`.
+
+---
+
+## Phase 5 (A) — Rollback
+
+On health-gate failure: put the most recent `releases/` version back into `current`, restart the service, and
+re-run the health gate (Phase 4). Guard-safe rollback script (uses `rsync --delete`, not `rm -rf`) + the
+approval-gate note: **`references/rollback.md`**.

package/kit/skills/deploy/references/topology-b.md

@@ -0,0 +1,44 @@
+# Topology B — managed platform (phases B1-B4)
+
+Read this only when Phase 0 answered **B**: you have an API/CLI and no shell on the box, a release is an immutable
+artefact, and rollback means re-pointing the environment at the previous one. On topology A read
+`references/topology-a.md` instead — never both.
+
+The invariant rules in SKILL.md hold over everything here, including the two that are B's alone: never rebuild to
+roll back, and the platform's own status is not the health gate.
+
+## Phase B1 — Build once, and know what you built
+The artefact is produced **once**, and the same one moves through every environment. Rebuilding for production
+means the thing you tested is not the thing you shipped — the inputs moved underneath you (a floating base
+image, a lockfile resolved a minute later, a different builder). Two consequences:
+- **Address it immutably.** A digest or a build id, never a moving tag. `latest`, `main` and a branch name all
+  name different bytes on different days, which makes both promotion and rollback unverifiable.
+- **Record which artefact is in which environment.** If nobody can answer "what exactly is running in
+  production", rollback is a guess and the health gate has nothing to compare against.
+
+## Phase B2 — Promote, do not rebuild
+Deploying to the next environment means pointing that environment at an artefact that already exists and has
+already passed the previous gate. Configuration is injected per environment, never baked into the artefact — the
+same bytes must be able to run in staging and in production, or you are back to rebuilding. Secrets come from
+the platform's own store; a secret inside the artefact ships to everyone who can pull it.
+
+**Approval is per environment (§4.4), and per topology.** Promoting to a user-facing environment is a deploy,
+whatever the platform calls it.
+
+## Phase B3 — Health gate, from outside
+Identical in spirit to Phase 4 (A) and worth stating because platforms invite the opposite: **the platform
+reporting "deployed", "healthy" or "active" is not the verification.** It reports that its own reconciliation
+finished. Check the thing users touch — a request through the public entry point, a real response body, the
+version endpoint returning the version you promoted. Give it the same failure rule: if the gate does not pass,
+go back before investigating.
+
+## Phase B4 — Roll back by re-pointing
+Rollback is promoting the previous artefact, not rebuilding the previous commit — a rebuild is a new artefact
+with new inputs and it may not even reproduce the bug you are escaping. So:
+- Keep the previous artefacts addressable for at least as long as you promise to be able to roll back. A
+  retention policy that deletes them is a rollback policy that does not work.
+- Rolling back **code** does not roll back a **migration**. If the release included an irreversible schema
+  change, the old artefact may not run against the new schema — that is `db-migration`'s expand/contract
+  question and it has to be answered before the deploy, not during the incident.
+- After a rollback, the environment is running an artefact older than the recorded state. Say so plainly to
+  whoever is watching; a silent rollback is how two people fix the same outage twice.

package/kit/skills/docs-writer/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: docs-writer
+description: |
+  Keeps documentation in sync with the code: README, usage and related docs when a public API or behavior
+  changes. Leaves no dead or misleading docs behind.
+---
+
+# Documentation
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "documentation", "docs", "update README", "API docs", "write docs", "document it", "write usage"
+
+Goal: the docs must **match the code**. Wrong/stale docs are worse than no docs (they inspire trust and mislead).
+Trigger: when a public API, command, configuration, or user-visible behavior changes.
+
+## When it is mandatory
+- A public function/endpoint/CLI signature or behavior changed.
+- A new feature, configuration key, or environment variable was added.
+- The install/run steps changed.
+- A breaking change was made (also coordinate via `release`/CHANGELOG).
+
+## Checklist
+- [ ] Docs are up to date for the changed public surface
+- [ ] Examples **work** (copy-paste tested / mentally traced)
+- [ ] Dead/misleading wording removed (no leftover old name/parameter)
+- [ ] New configuration/env documented (default + whether required)
+- [ ] Scope minimal — not a repetition of the code, but "why/how to use it"
+- [ ] No secret/real credential in the docs (use a placeholder)
+
+## How
+1. **Identify the changed surface** — extract the public signature/behavior diff from the diff.
+2. **Find the right doc** — README, `docs/`, docstring, OpenAPI, command `--help`. If there is more than one, update them all.
+3. **Write**: what it does · how it is called (example) · input/output · limits/error cases. Short and correct.
+4. **Verify the examples** — does the command/code example actually run.
+5. **Clean up the old** — delete references to removed APIs/parameters.
+6. **Translation**: if the user-visible doc is multilingual, coordinate with `i18n-integrity`.
+
+## Principles
+- **Single source** — behavior lives in the code; the doc *explains* it, does not copy it (a copied doc goes stale).
+- **Example > paragraph** — a working example beats three paragraphs.
+- **Minimal** — don't write a giant doc no one will maintain; answer the most-asked question.
+
+## Co-authoring a longer doc (guide, tutorial, README rewrite)
+For a substantial doc the content lives in the author's head, not the diff — don't guess it. Interview for intent
+and audience, draft in passes, and let the user steer before you polish. The collaborative workflow (audience/intent
+questions, outline-first, section-by-section drafting, revision loop): **`references/coauthoring.md`**.
+
+## Invariant rules
+1. **Correctness > completeness** — don't write a wrong doc; if unsure, flag it/ask.
+2. **Examples must work.**
+3. **Leave no stale/dead docs.**
+4. **No secret/real credential** — use a placeholder (aligned with §4).
+5. **Don't repeat the code** — don't just copy the signature; explain the usage.

package/kit/skills/docs-writer/references/coauthoring.md

@@ -0,0 +1,34 @@
+# Co-authoring a longer doc
+
+Loaded on demand. For a substantial doc (a guide, tutorial, concept explainer, README rewrite) — not a mechanical
+sync of a changed signature. Here the content lives in the author's head; your job is to draw it out and shape it,
+not to invent it.
+
+## Why not just write it
+
+A generated long-form doc that no one steered reads as generic, states things the maintainer wouldn't, and quietly
+guesses at intent — then it has to be rewritten anyway. Co-authoring front-loads the cheap questions so the expensive
+draft is right the first time.
+
+## The workflow
+
+1. **Interview first (before drafting).** Ask, don't assume:
+   - **Audience** — who reads this? (new user, integrator, contributor, ops) Their assumed knowledge sets the level.
+   - **Intent** — what should the reader be able to *do* after? One doc, one job.
+   - **Scope** — what's explicitly out of scope? (prevents the doc sprawling)
+   - **Voice/constraints** — house style, terminology, things that must/mustn't be said.
+   Keep it to the few questions whose answers actually change the draft — offer options where useful, don't interrogate.
+
+2. **Outline, get sign-off.** Propose the section structure (headings + one line each) and confirm it *before* writing prose. Re-structuring an outline is cheap; re-structuring 800 words is not.
+
+3. **Draft in passes, not one wall.** Write section by section (or a first full pass explicitly marked as a draft). Surface the open questions inline (`> TODO: confirm default value`) rather than silently guessing — the maintainer fills the gaps you can't.
+
+4. **Revision loop.** Invite specific feedback ("is the auth section at the right level?"), apply it, and keep the diff reviewable. Don't rewrite wholesale on each round — converge.
+
+5. **Then apply the base discipline.** Once the content is agreed, the SKILL.md rules take over: examples must actually run, no stale/dead wording, no real secrets, single-source (explain the code, don't copy it), and coordinate `i18n-integrity` if it's multilingual.
+
+## Keep it honest
+
+- Don't state capabilities, defaults, or roadmap you haven't verified — ask or mark as TODO.
+- Don't pad to look thorough; the maintainer maintains every sentence you add.
+- The author's voice wins over yours — you're drafting *their* doc, not authoring your own.

package/kit/skills/eval-grader/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: eval-grader
+description: |
+  Measure output quality, don't vibe it: score a generative task with a two-layer grader — deterministic code
+  metrics + per-dimension LLM-as-judge — over a fixed task set, as signed deltas vs a pinned baseline. Grades
+  cost alongside correctness (pass-slow).
+---
+
+# Eval Grader
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "eval", "grader", "measure output quality", "LLM-as-judge", "score the output"
+
+**Measure every change; don't vibe it.** When you iterate on a prompt, an agent, or any generative output (docs,
+slides, UI, a summary, an extraction), a two-layer grader over a fixed task set turns "feels better" into a signed
+number you can trust.
+
+This is the **external, machine-grounded verifier** the `iterate` skill asks for — a model grading its *own* output
+inflates; a separate grader on a fixed suite does not.
+
+> **Crewforth adaptation (local, .claude/):** use when tuning a generative task; the scorecard goes to `docs/EVAL.md`
+> (§4.3). Stack-agnostic — graders are ordinary code + judge calls. §4 Prohibitions apply.
+
+## Two layers
+- **Layer 1 — code graders** (deterministic, near-free, run every time): structural metrics over the artifact —
+  *did it produce a valid result?* plus counts, sizes, schema validity, "wall-of-text" / clutter flags. They catch
+  gross regressions a judge shouldn't be spent on. Ground truth is **computed from the source**, not hand-authored.
+- **Layer 2 — LLM-as-judge graders** (semantic): **one call per dimension** (clarity · correctness-vs-source ·
+  completeness…), scored on an explicit rubric. Steer against leniency — "use the full 0-5 range, not only 3-5";
+  judge with a **different model family** to avoid self-preference; **randomize A/B order** to kill position bias.
+
+Each grader is one **scorecard column**; adding a metric = appending one grader.
+
+## pass-slow — grade cost alongside correctness
+A result is not just right/wrong. An **efficiency grader** downgrades a correct output that ran **over a
+turn/token budget** to `pass-slow` — so "correct but too expensive" is visible, not hidden inside a green pass.
+
+## The loop
+1. A **fixed task set** (`tasks`), each with an input and a measurable expectation.
+2. Run all graders over each task's output → a scorecard.
+3. **Pin a baseline** once; every later run shows **signed deltas vs that baseline**, not vs the previous run — so
+   re-running the same round shows real movement, not noise.
+4. Change one thing, re-run, read the deltas. Keep what moves the number up.
+
+## Noise floor
+State it. At n=20 tasks, one task ≈ 5 points — deltas smaller than that are not meaningful. If the cheapest option
+already hits the ceiling, say so plainly instead of chasing a fractional gain.
+
+## Micro-test before you commit to a wording
+Changing an instruction — a skill's phrasing, a rule in the discipline, an agent's trigger — is a change to
+behaviour, and the temptation is to reason about whether it reads better. Reading better and working better are
+different properties. Test it cheaply first:
+
+1. **Sample it a handful of times**, not once. Same prompt, same conditions.
+2. **Against a no-guidance control** — the identical task with the instruction absent. Without the control you
+   learn what the model does, not what your wording adds.
+3. **Read every result by hand.** At this size there is no statistic to hide behind; a score computed over four
+   runs is a number pretending to be evidence.
+4. **Treat run-to-run variance as a warning, not noise to average away.** If the same arm swings across runs,
+   the wording is not doing reliable work — and any delta you measure is smaller than the variance you have not
+   controlled.
+
+The failure this prevents, observed in Crewforth's own evals: a case scored 7/9 against 9/9 — the guidance apparently making
+things *worse* — and an identical second round came back 9/9 to 9/9. Two checks of variance inverted the
+finding. Had the first round been reported, a good rule would have been removed on noise.
+
+Corollary: a delta smaller than the observed spread between identical runs is not a result. Say "below the
+noise floor" and either raise n or accept that the change is unmeasurable at this scale — both are honest;
+quoting the number is not.
+
+The grader architecture, a starter grader catalogue, and the judge-bias checklist live in **`references/method.md`**.
+
+## DoD
+- A fixed task set + a two-layer grader; a pinned baseline; every change reported as a signed delta with the noise floor stated.
+- Any wording change was micro-tested against a no-guidance control, with every run read rather than averaged.

package/kit/skills/eval-grader/references/method.md

@@ -0,0 +1,51 @@
+# Eval grader — architecture & catalogue
+
+## Shape
+A **declarative list of graders**; the harness stays grader-agnostic. One grader:
+
+```
+{ name, kind: "code" | "judge", description,
+  grade(context) -> number | string,
+  scale?: { min, max, good: "high" | "low" } }
+```
+- `scale.good` drives red→yellow→green heat-coloring of a cell (so a scorecard is scannable).
+- Build a **`GraderContext` once per task** (the parsed artifact + a rendered form + any client), and pass it to
+  every grader — graders are pure functions of the context.
+
+## Layer 1 — code graders (deterministic; adapt to your artifact)
+- `produced` → `ok` / `missing` / `invalid` — did it produce a valid artifact at all? The cheapest, first gate.
+- structural counts (sections · items · length), `too_long` / `cluttered` flags (`good: "low"`), schema validity.
+- **Compute expected values from the seed/source, not by hand** — reproducible, and it catches "right narrative,
+  wrong number" (a `numeric_tolerance` grader with a `must_mention` guard).
+
+## Layer 2 — judge graders (semantic)
+- **One call per dimension** (clarity, correctness-vs-source, completeness, tone…), integer **0-5** on an explicit
+  rubric. Do **not** blend dimensions into one holistic score.
+- **Structured output** (a typed schema) so the score lands parsed, not regex'd; retry on schema mismatch.
+- **Memoize shared judge calls**: if four dimensions read the same rendered output, make **one** batched call and
+  read four fields from it — not four calls.
+- Add an **anti-hallucination** dimension: does the output say "I don't know / the source doesn't cover this"
+  rather than inventing? Reward the honest gap.
+
+## Judge-bias checklist (an LLM judge is biased — correct for it)
+- **Position bias** → randomize A/B order across calls.
+- **Verbosity bias** → a longer answer is not a better one; rubric on substance.
+- **Self-preference** → judge with a **different model family** than the one under test.
+- **Label deference** → don't show the judge the "expected" answer as gospel; ask it to reason first.
+- Calibrate against a few human labels; test the judge on **known-negatives** (does it catch a deliberately-bad output?).
+
+## The measured-iteration loop
+- Pin the baseline once (`baseline.score.json`); later runs print **signed deltas vs the baseline**, not vs the
+  previous run.
+- One task's failure must not abort the scorecard (grade each independently, collect all results).
+- A run over the whole suite is **one command**. If you want a structural regression to *block*, wire the Layer-1
+  code graders into a Stop / PostToolUse hook (they're deterministic and fast — a natural gate).
+
+## pass-slow / efficiency grader
+Wrap a correctness grader: if it passes but `turns > budget_turns` or `tokens_out > budget`, return **`pass-slow`**
+instead of `pass`. Score = (pass + ½·pass-slow) / N — "correct but too expensive" is a distinct, visible verdict.
+
+## Cost/quality sweep (optional — picking a model/params for a task)
+Sweep the grid (model × thinking × effort), hold everything else constant, and rank on
+`cost_per_success = total_cost / passes` and `seconds_per_success` — a model 3× cheaper per call but passing half as
+often is **not** cheaper. Always state the noise floor next to the winner.

package/kit/skills/frontend/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: frontend
+description: |
+  Stack-agnostic frontend discipline (web · mobile · desktop): component structure, state, data fetching,
+  loading/empty/error states, i18n, accessibility, performance. crew-frontend-expert applies it on every stack.
+---
+
+# Frontend Discipline (stack-agnostic)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "frontend", "screen size", "component", "page", "UI", "state management", "interface"
+
+Web (React/Next/Vue/Svelte/Angular), mobile (React Native/Flutter) or desktop — shared principles.
+The stack-specific "how" (native bridge, router choice, etc.) lives in the relevant project skill; this skill applies to all of them.
+
+## Architecture
+- **Presentation / logic separation:** component/view is pure and thin; business logic lives in the hook/composable/service layer.
+- **Reusability:** repeated UI is factored out; the prop contract is clear and typed.
+- **Folder:** feature-based (`features/<name>/`) — view, logic, and test together.
+
+## State & data
+- **Local state first** (`useState`/signal); if global is needed, the project's choice (store/context) — nothing imposed.
+- **Data fetching:** cache + error + loading states are considered; race/abort are handled.
+
+## State-complete UI (design it from the start)
+Every data-bound view covers **four states**: **loading · empty · error · full**.
+Don't code only the "full" case; empty/error/loading are part of the experience.
+
+## i18n & accessibility (default, not decoration)
+- User-visible text comes from the language file (project languages); no hard-coded strings (`i18n-integrity`).
+- Meaningful labels/roles, sufficient contrast, keyboard/screen-reader access, appropriate touch/click target.
+
+## Visual & UX quality
+This skill covers *structure*; the **visual/UX design layer** — hierarchy, spacing rhythm, typographic scale, a
+restrained color system, and polished states — lives in **`frontend-design`**. Apply it when the work is about how the
+interface *looks and feels*, not just how it's wired.
+
+## Responsive & performance
+- Works across the target screen/device matrix (responsive/adaptive).
+- Unnecessary renders (memo/callback), bundle size, lazy loading, virtualization for long lists.
+
+## Verify at runtime (contract)
+Prove a change works by **observing the running UI**, structured — not by interpreting a screenshot. Have components
+emit `data-verify-*` state attributes, register verifiable units with fixtures + invariants (≥1 adversarial `probe`
+each), expose `window.__verify`, and adopt the `PASS/FAIL/BLOCKED/SKIP` taxonomy (when in doubt, FAIL). Then drive
+the browser to check it. The full convention: **`references/verify-contract.md`**.
+
+## DoD (this skill's contribution)
+- `/simplify`; no dead styles/unused props.
+- The four states are covered; `i18n-integrity` clean; accessibility passes the baseline matrix.
+- `crew-review-agent` clean.
+
+## Constraints
+- Surgical change; follow existing conventions, do not impose a stack/preference.
+- Do not present data the platform does not provide as if it existed; do not promise a capability that isn't there.
+- §4 applies: no AI trace or vendor template name in code/comments/strings.

package/kit/skills/frontend/references/verify-contract.md

@@ -0,0 +1,41 @@
+# Verify-by-contract — make the UI machine-checkable at runtime
+
+Tests and typecheck are CI's job. **Verification is runtime observation at the surface:** you run the thing, drive
+it, and read what it actually shows. Make that observation *structured and cheap* — so an agent (via the browser),
+CI, and a human dashboard all read the **same truth through one code path** — instead of interpreting screenshots.
+
+## 1 · The DOM is the machine-readable surface
+Every component emits `data-verify-*` attributes describing its **state**, not its internals:
+```html
+<section data-verify-unit="TodoApp" data-verify-total="3" data-verify-done="1" data-verify-active="2">
+```
+Verifiers read the **contract**, never React/Vue internals — so you can rewrite internals freely as long as the
+contract holds. A component with **no contract is a FAIL, not a warning**.
+
+## 2 · Verifiable units: fixtures + invariants + a schema
+Register each unit with: a props schema, named **fixtures** (a reproducible render config, with an optional
+imperative `act()` to click/type/wait), and **invariants** (a predicate over the mounted DOM → `true` or a
+human-readable violation).
+- **Every unit needs ≥1 `probe` fixture** — an adversarial edge case (empty, huge, inconsistent). Enforce it: "you
+  can't ship a unit that only tests the happy path."
+- Keep **one fixture that is *designed to fail*** — it proves the framework catches lies, not just confirms truths.
+
+## 3 · Isolated, deep-linkable render targets
+`/verify/:unit/:fixture` mounts **only** that unit in a known state, no app shell (`?chrome=0` for a clean
+screenshot). An agent navigates there, observes, reads the result — no scrolling the whole app.
+
+## 4 · One agent handle, one verdict taxonomy
+Expose `window.__verify`: `manifest()` (every unit × fixture × verifier), `current()` (structured result for what's
+mounted), `runAll()` (the full matrix). The dashboard is just a human rendering of the same data; CI calls the same
+runner.
+
+Verdicts: **`PASS` · `FAIL` · `BLOCKED` · `SKIP`**; checks: `ok / fail / warn / probe`.
+- **`BLOCKED` ("couldn't observe") is deliberately distinct from `FAIL` ("observed and wrong").**
+- Rule: **when in doubt, FAIL** — a false PASS ships a bug; a false FAIL costs one more look.
+- A verifier exception becomes a `fail` check with the stack as evidence — never swallowed.
+
+## 5 · How Crewforth drives it
+A frontend change is verified by driving the browser (the `claude-in-chrome` tools) to the isolated target and
+calling `window.__verify.runAll()`, then reading the **structured verdicts** — closing the "did my change actually
+work at runtime" loop without a human eyeballing pixels. This is the frontend counterpart to `iterate`'s external,
+machine-grounded verifier and `eval-grader`'s scorecard.

package/kit/skills/frontend-design/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: frontend-design
+description: |
+  Visual and UX design quality for interfaces: hierarchy, spacing rhythm, typographic scale, a restrained color
+  system, layout composition, and polished states. The taste layer above frontend architecture and a11y.
+---
+
+# Frontend Design (visual & UX quality)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "visual design", "design system", "make it look good", "UI polish", "page layout", "the layout is", "spacing", "typography"
+
+`frontend` decides how the code is structured; `a11y` decides whether everyone can use it; **this skill decides
+whether it looks considered and feels right.** The through-line: **a few consistent decisions, applied everywhere,
+read as "designed" — many one-off decisions read as "assembled".** Design is subtraction and rhythm, not adding flourish.
+
+> **Crewforth adaptation (local, .claude/):** Stack-agnostic. **Detect and respect the project's existing design system**
+> (tokens, component library, brand) — never impose a personal aesthetic or a new library. Accessibility is a floor,
+> not a trade-off: apply `a11y` alongside (contrast, focus, motion). §4 Prohibitions apply.
+
+## The six levers (order = impact; fix hierarchy before you touch color)
+1. **Hierarchy** — the eye must land on the one primary thing first. Establish it with size, weight, and space — not with more color. One primary action per view; everything else is visibly secondary.
+2. **Spacing & rhythm** — consistent spacing from a single scale (e.g. 4/8px steps). Group related things with *less* space, separate groups with *more*. Whitespace is the cheapest way to look premium.
+3. **Typography** — one or two families, a small scale (≈4–6 steps), consistent line-height (~1.5 body). Limit weights. Measure ~45–75 chars per line. Type does most of the hierarchy work.
+4. **Color** — a restrained system: 1 brand/accent, a neutral ramp, semantic states (success/warn/error). Accent is for *action and emphasis*, not decoration. Verify contrast (→ `a11y`).
+5. **Layout & composition** — align to a grid; consistent alignment edges. Respect proximity/similarity (Gestalt). Responsive by *intent* (reflow, not just shrink); design the breakpoints, don't inherit them by accident.
+6. **State & polish** — design loading / empty / error / disabled / hover / focus as first-class, not afterthoughts. Motion is restrained and purposeful (~150–250ms, ease), and honors `prefers-reduced-motion`.
+
+## When the project gives no design direction
+Look for the project's own system first: a token file, a theme, the components it already has. If there is one,
+follow it; the list below only fills a gap. With none, do not fall into these defaults on your own (use one when
+the user asks for it):
+- a cream or off-white ground with serif headings and a terracotta accent
+- a purple-to-blue gradient hero on white
+- a black ground with a single neon accent
+- an italic accent word in headings
+- "01 / 02 / 03" section numbers that tell no real sequence
+- monospace labels on everything
+- pill buttons and the same shadow everywhere
+- emoji as section markers
+- cards with a colored stripe along one edge
+
+"Avoid a generic look" alone swaps one default for another; naming the patterns is what works. After the first
+result, look at which default crept in and add it to this list for the project — iterate, don't restart.
+
+## Checklist
+- [ ] One clear primary action; hierarchy readable at a glance (squint test)
+- [ ] All spacing from one scale; related grouped, groups separated
+- [ ] Type scale limited and consistent; line length and line-height comfortable
+- [ ] Color restrained; accent reserved for action; contrast passes (`a11y`)
+- [ ] Aligned to a grid; responsive by intent with designed breakpoints
+- [ ] Loading / empty / error / disabled states designed, not default
+- [ ] Motion purposeful, reduced-motion honored
+- [ ] Existing design tokens/system reused — nothing one-off invented
+
+---
+
+## Tokens, scales, and a heuristic design review
+Spacing/type/color scale systems, turning ad-hoc values into tokens, dark-mode and density variants, and a
+squint-test / heuristic-review pass to run before handing UI back: **`references/design-review.md`**.
+
+## Coordination
+Architecture, state, and folder structure → `frontend`. Accessibility gate (contrast, focus, ARIA) → `a11y`.
+Applied by **crew-frontend-expert** on any stack; the stack-specific "how" stays in the project's frontend skill.
+
+## Invariant rules
+1. **Hierarchy before decoration** — fix what the eye sees first before adding any color or flourish.
+2. **One scale per dimension** — spacing, type, and radius each come from a single defined scale.
+3. **Reuse the project's system** — detect existing tokens/components; never impose a new aesthetic or library.
+4. **Accessibility is a floor** — contrast, focus, and reduced-motion are non-negotiable, not a style trade-off.
+5. **Every state is designed** — loading/empty/error/disabled are part of the design, not defaults.

package/kit/skills/frontend-design/references/design-review.md

@@ -0,0 +1,34 @@
+# Tokens, scales, and heuristic review
+
+Loaded on demand. The SKILL.md levers are the method; this is the concrete scales and the review pass.
+
+## Scales — turn ad-hoc values into a system
+
+**Spacing** — one base unit, multiples only. A 4px (or 8px) base: `4 · 8 · 12 · 16 · 24 · 32 · 48 · 64`. Every margin/padding/gap picks from this list — never `13px` because it "looked right". Consistency is what reads as designed.
+
+**Type scale** — a small set of steps from a ratio (~1.2–1.25). Example: `12 · 14 · 16 · 20 · 24 · 32 · 40`. Body ~16, line-height ~1.5; headings tighter (~1.2). Limit weights to 2–3 (e.g. 400/600/700). One or two families max.
+
+**Radius / border / shadow** — also scales, not one-offs: e.g. radius `4 · 8 · 16 · full`; elevation as 2–3 defined shadow steps. Consistent elevation communicates depth; random shadows look noisy.
+
+**Color ramp** — a neutral scale (e.g. 50→900) plus one accent and semantic colors (success/warning/error/info), each with an on-color that meets contrast. Don't hand-pick greys per component; pull from the ramp.
+
+## Tokens — name the decisions
+
+Once the scales exist, name them as tokens (CSS custom properties / theme object / design-token file) so a change is one edit, not fifty: `--space-4`, `--text-lg`, `--color-accent`, `--radius-md`. **First detect the project's existing token layer and extend it**; only introduce tokens where none exist, and match the project's naming. Semantic tokens (`--color-surface`, `--color-text-muted`) layer over primitive ones and make dark-mode/theming a token swap rather than a rewrite.
+
+## Dark mode & density
+
+- **Dark mode** is not "invert" — it's a second set of semantic token values. Surfaces get lighter with elevation (not pure black); reduce saturation; re-check contrast in both themes.
+- **Density** — if the product needs compact/comfortable modes, drive them from the spacing scale (a density multiplier), not per-component overrides.
+
+## The heuristic review pass (run before handing UI back)
+
+- **Squint test** — blur your eyes (or literally squint): does the primary action still stand out? If everything is equally loud, hierarchy failed.
+- **Grayscale test** — remove color: does it still communicate hierarchy and state? If it only works in color, you're leaning on color to do type/space's job (and it will fail for color-blind users).
+- **Spacing audit** — are there any values not on the scale? Any inconsistent gaps between similar groups?
+- **Alignment audit** — do elements share alignment edges, or is everything slightly off? One stray alignment reads as sloppy.
+- **State sweep** — force loading, empty, error, disabled, long-text, and tiny/huge viewport. Each should look intentional.
+- **Consistency sweep** — same button in two places identical? Same card padding everywhere? Divergence is the top "assembled, not designed" tell.
+- **Restraint check** — can anything be *removed*? A border that a gap already implies, a color that space already separates, a shadow doing nothing. Subtraction usually improves it.
+
+Report design findings the way `crew-review-agent` expects: concrete (element + which lever + the fix), not "make it prettier".

package/kit/skills/frontend-rn-expo/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: frontend-rn-expo
+description: |
+  OPTIONAL, stack-specific: React Native + Expo (prebuild). Mobile RN projects only; the generic principles
+  live in the `frontend` skill.
+---
+
+# React Native + Expo (stack-specific layer)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "expo", "react native", "native bridge", "expo router", "rn screen", "prebuild"
+
+For generic frontend discipline, applies the `frontend` skill; this file only covers the RN+Expo-specific additions.
+Not used in web/desktop projects (delete it if needed).
+
+## RN + Expo specifics
+- **Navigation:** expo-router (file-based) or react-navigation — follow whichever the project uses.
+- **Lists:** `FlatList`/`FlashList` + `keyExtractor`; virtualization for heavy lists.
+- **Native bridge:** only when needed; the JS side is **typed**, error paths are explicit (what the UI does if native rejects).
+  Via Expo prebuild / config plugin; mind the platform difference (iOS/Android).
+- **Render by capability:** do **not** promise in the UI a capability the device lacks; show it conditionally.
+- **Assets:** image size/resolution, `expo-image` cache, splash/icon prebuild compatibility.
+
+## DoD (in addition to the generic `frontend` DoD)
+- Works across the target iOS/Android version matrix; native bridge error paths are tested.