crewforth 0.0.1 → 3.0.0-rc.1

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.

package/kit/skills/handoff/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: handoff
+description: |
+  Session handover: when context fills, a phase closes, or the topic changes, write an action-oriented handover
+  to docs/SESSION_STATE.md, then recommend /clear.
+---
+
+# Session Handover (Handoff)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "handoff", "hand off", "session summary", "session state", "clear context", "I'll continue", "next session", "where we left off", "run out of room", "continue tomorrow"
+
+## When
+Session fill (the `🔋` line) > 75% · phase closure · topic change. Goal: the next session should **not start from scratch**.
+
+## Output (docs/SESSION_STATE.md, local)
+```
+# Session Handover — <date>
+## Done
+- <completed work + which files>
+## In progress
+- <what's half-finished + exactly where it was left off>
+## Next step
+- <a clear, single high-value step>
+## Open decisions
+- <pending decision + options>
+## File pointers
+- docs/PLAN.md, relevant modules...
+## Blockers / risks
+- <if any>
+```
+
+## Measure the session before summarising it
+Run **`bash .claude/hooks/session-stats.sh`** first. What it reports belongs in the handover as fact, not
+impression — an auto-compaction means state was already dropped before you started writing (say what was lost),
+a runaway loop marks an approach the next session should not walk back into, and repeated prompts mark context
+that never landed and has to be written down explicitly this time. Missing script (plugin install) → say so.
+
+## Principles
+- **Action-oriented:** focused not on "what was done" but on "exactly where to resume now."
+- Preserve the rationale behind decisions (why this path was chosen) — so context isn't lost.
+- Once written, start a fresh session with `/clear`.
+
+## Holding a board item? The handover is not finished until the TEAM has it
+`docs/SESSION_STATE.md` is gitignored — it survives your `/clear`, and nobody else can read it. So when a
+`teamboard` claim is open, **the handover is not complete until it is on the board**. This is not an optional
+extra step:
+- Still on it → `board.sh note <id> "<where it stands, and why the rejected path was rejected>"`.
+- Not coming back → `board.sh drop <id> "<same>"`, which puts it back in circulation with your context attached.
+- Anything settled here that changes how OTHER items must be done → `board.sh decide "<what>" "<why + what it
+  means>"`. A decision that stays in your transcript reaches nobody; on the board it reaches every teammate at
+  their next session opening.
+
+Write the board note FIRST, then the local file — an interrupted handover should lose the private copy, not the
+shared one.
+
+## Redaction (`<private>` marker)
+`docs/SESSION_STATE.md` is local, but its content is copied into board notes and handovers — never persist a secret, token, credential, or
+personal note into it. Any content wrapped in **`<private>…</private>`** is a redaction marker: strip it from the
+written handover and leave a `[redacted]` placeholder in its place. If a resume genuinely needs a sensitive value,
+point to *where it lives* (env var, secret manager, the person to ask) — never the value itself.
+
+## Check it before trusting it
+That DoD sentence is a claim about a file nobody has tested. Before closing, run the **cold-reader pass**: write
+5–8 questions from the WORK (not from the file) with their expected answers, then answer them from the handover
+alone. A question that cannot be answered is a gap in the file. Procedure, phrasing that keeps the test honest,
+and the common failure shapes: **`references/cold-reader.md`**.
+
+## DoD
+- A handover file; a new session can resume where it left off by reading only this file.
+- The cold-reader questions were written **before** the file and every one of them is answerable from it.

package/kit/skills/handoff/references/cold-reader.md

@@ -0,0 +1,51 @@
+# The cold-reader pass
+
+Loaded on demand. SKILL.md's DoD says a new session can resume by reading only the handover file. This is how
+that sentence is checked instead of asserted — and it is the only part of the handover that can fail silently:
+a file that reads well to its author reads well *because* the author remembers what it leaves out.
+
+## The rule the pass exists to enforce
+
+**Write the questions before you write the file, from the work — not from the file.** An answer key derived
+from the handover only proves the handover is self-consistent. Derived from the session, it proves the handover
+carries the session.
+
+## Procedure
+
+1. **Before writing the handover**, list 5–8 questions the next session must be able to answer to continue. Take
+   them from the work itself: what was decided and why, what is half-finished and exactly where, what was ruled
+   out, what breaks if it is touched, what the next action is. Write the expected answers down beside them.
+2. **Write the handover** as usual.
+3. **Answer the questions from the handover alone.** The consumer may open only the paths the file itself names
+   — the template requires a file-pointers section, so following those pointers *is* the file working. It may
+   not use the session's memory, search the repository for context the file never mentions, or ask.
+4. **Score each question**: answered · partly answered · not answerable. Any "not answerable" is a gap in the
+   handover, not in the reader.
+5. **Fix the file and re-answer** the failed questions. The pass closes when every question is answerable.
+
+## Phrasing that keeps the test honest
+
+- **Do not reuse the handover's own words in the question.** "What did we decide about the cache?" is answerable
+  by keyword-matching the heading; "What happens to a request that arrives while the cache is rebuilding?" is
+  not. A question a reader can answer by lifting a phrase has measured the search, not the content.
+- **Ask for the reason, not the label.** "Which approach was chosen" is a lookup. "Why was the other one
+  rejected" is what a resuming session actually needs, and it is what handovers most often drop.
+- **Ask at least one question whose answer is a location** — a file, a branch, a command. Handovers routinely
+  describe a state that nothing points at.
+
+## Who runs it
+
+Wherever the handover is written — usually inside `crew-session-manager`, which the discipline routes this
+through, sometimes the main thread. Either way no agent in Crewforth holds the delegation tool (all twelve
+shipped agents declare an explicit allowlist and none contains it), so there is no separate cold-reader
+subagent to hand the file to. That is a real limitation and worth naming: the same context that wrote the file is answering
+from it, so the discipline is entirely in step 1 (questions from the work, written first) and step 3 (answer
+from the file only). If a genuinely cold reader is available — another session, a teammate, a fresh window
+opened at the file — use it; the procedure is unchanged and the result is stronger.
+
+## What a failure looks like
+
+The common ones, in the order they occur: the "in progress" entry names a task but not the line it stopped at;
+a decision is recorded without the alternative it beat; a blocker is described without who or what unblocks it;
+and the next step is a category ("continue the refactor") rather than an action. Each of those passes a reading
+by its author and fails a cold reader.

package/kit/skills/i18n-integrity/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: i18n-integrity
+description: |
+  Translation integrity: every key present in every language, no hardcoded strings, consistent placeholders
+  and plurals. Runs when user-facing text changes.
+---
+
+# Translation Integrity (i18n)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "i18n", "translation", "language file", "missing translation", "localization", "translate", "untranslated", "hardcoded string", "multi language", "multiple languages", "still in english", "locale"
+
+Goal: no missing/broken text in any language. Languages: the set the project declares (e.g. in `CLAUDE.md` or the locale directory).
+
+## Audit dimensions
+- **Key parity:** every key has a counterpart in ALL languages; a missing/extra key = a finding.
+- **No hardcoded strings:** user-facing text is not embedded in code, it comes from the language file.
+- **Placeholder consistency:** `{name}`, `%s`, ICU `{count, plural, ...}` are identical in every language.
+- **Plural rules:** language-specific plural forms (especially RU) are correct.
+- **Empty/identical value:** an untranslated (identical to the source) placeholder value is flagged.
+
+## Check (key-set comparison)
+```bash
+# Example: compare the key sets of JSON language files
+for f in locales/*.json; do echo "== $f =="; jq -r 'keys[]' "$f" | sort > "/tmp/$(basename $f).keys"; done
+diff /tmp/tr.json.keys /tmp/en.json.keys   # differences = missing/extra keys
+```
+
+## DoD
+- Key sets are equal across all languages; no hardcoded user text; placeholders are consistent.
+- **Missing translation = red** (no deferral).

package/kit/skills/incident-runbook/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: incident-runbook
+description: |
+  Production incident response: diagnose → mitigate → resolve, then a blameless postmortem and a repeatable
+  runbook. Stop the impact first, root cause second.
+  Use when production is degraded or broken, and again for the postmortem afterwards.
+---
+
+# Incident Response & Runbook
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "incident", "incident response", "runbook", "postmortem", "root cause", "outage", "production incident", "post-incident"
+
+Two modes: **live incident** (what to do right now) and **aftermath** (postmortem + runbook). Priority: stopping
+user impact > finding the root cause. No panic, one ordered step at a time.
+
+## Live incident — sequence
+1. **Acknowledge & classify** — what is the impact (who, how much), severity (SEV1 full outage … SEV3 minor).
+2. **Mitigate the impact FIRST** — rollback, turn off a feature flag, shift traffic, scale up. Without waiting on the root cause.
+3. **Single coordinator** — it is clear who decides; communication goes through one channel.
+4. **Diagnose** — last change? (deploy/migration/config) narrow it down with logs+metrics+traces (observability).
+5. **Resolve** — the smallest safe fix; then verify (health check).
+6. **Close** — confirm the impact is over; note the timeline (a postmortem input).
+
+## Mitigation reflexes
+- Last deploy suspect → **rollback** (deploy revert).
+- Suspect feature → turn off the **feature flag**.
+- After a destructive migration → restore from backup (db-migration).
+- Dependency/service down → circuit breaker / graceful degradation.
+
+## After the incident
+
+Blameless postmortem + producing a durable runbook: **`references/postmortem.md`**.
+
+## Invariant rules
+1. **Stop the impact, then understand** — the root cause does not hold up the resolution.
+2. **Blameless culture** — the postmortem questions the system, not the person.
+3. **Actions are owned + dated** — no "we'll look at it later".
+4. **The runbook is executable** — real commands/steps, not wishes.
+5. **Make learning permanent** — the lesson goes into an adr/runbook/monitoring, it does not get lost.

package/kit/skills/incident-runbook/references/postmortem.md

@@ -0,0 +1,16 @@
+# After the incident — postmortem & runbook
+
+Both of these happen **after** the live response is over, not during it. Get the impact stopped first (SKILL.md);
+come here once the incident is resolved.
+
+## Postmortem (blameless)
+Once the incident is resolved, within 24-72 hours:
+- **Timeline**: detection → response → resolution (actual times).
+- **Impact**: who, for how long, what was lost.
+- **Root cause**: "5 whys"; the system/process is questioned, not the person (**blameless**).
+- **Actions**: concrete, owned, dated items that prevent a recurrence (no deferral).
+- If a lasting decision came out of it → `adr`.
+
+## Produce a runbook
+For repeatable incidents, a step-by-step runbook: symptom → diagnostic commands → mitigation → verification → escalation.
+The runbook must be **project-specific** and **executable** (not generic); coordinate with `docs-writer`.

package/kit/skills/iterate/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: iterate
+description: |
+  Refine-to-Done loop: repeat until tests green + review clean + nothing deferred; bounded. Not the harness /loop.
+---
+
+# Iterate — refine to Done, don't stop at the first attempt
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "iterate", "loop until done", "keep going until"
+
+## When
+A task has an objective acceptance criterion (tests, a review gate, a spec) and the first attempt may not
+meet it. This is a single-session refinement loop — NOT the harness `/loop`, which schedules a prompt on an
+interval. Open-ended exploration with no checkable target does not belong here.
+
+## The loop
+1. **Name the exit test first** — the concrete, checkable condition that means "done": tests green,
+   `crew-review-agent` clean, the spec's acceptance criterion met, zero SonarQube findings. No exit test →
+   go to spec-planning first; a loop without a target never terminates.
+   **Prefer an external, machine-grounded verifier** — a test exit code, a schema match, a lint/quality gate —
+   over an LLM's self-assessment. A model grading its own output inflates; an "it looks done" or even a single
+   "review clean" with no objective check is a weak verifier. When the only available check is a judgment call,
+   ground it (a second agent with a distinct lens, an explicit rubric) rather than trusting the loop's own say-so.
+   For a generative task with no exit code, the `eval-grader` skill *is* that external verifier — a two-layer
+   scorecard (code metrics + LLM-judge) over a fixed set, read as signed deltas vs a pinned baseline.
+2. **Run one round**: change → verify (drive the real flow, not only tests) → check the exit test.
+3. **Report the gap** every round — state what still fails and why. Never loop silently.
+4. **Repeat** until the exit test passes. Stop early and surface it if: two rounds pass with no new
+   progress (you are stuck — report, don't spin), the exit test itself is wrong, or a blocker needs a
+   decision from the user.
+5. **Close at the DoD gate, not at a commit.** `crew-commit-agent` still proposes and waits for §4.4
+   approval. The loop never commits, pushes, or deploys on its own.
+
+## Guardrails
+- **Bounded, not infinite.** A fixed exit test plus a no-progress stop is the whole point; "keep trying
+  forever" is a bug, not diligence.
+- **Token discipline** ([[token-budget]]): each round re-pays for context. Keep a round's output a summary,
+  push heavy logs to `docs/*.md`, and don't fan out a subagent per round unless isolation demands it.
+- **Don't move the goalposts.** Never weaken the exit test to end the loop — fix the work, or stop and ask.