crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/sonarqube-check/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sonarqube-check
+description: |
+  SonarQube quality gate, any language, no company server needed: run SonarQube Community Build locally (Docker),
+  read the real gate + issues, fix by rule id, re-scan and diff. A linter's green build is a pre-check, never the gate.
+---
+
+# SonarQube quality gate — produce the real report, locally
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "sonarqube", "quality gate", "code smell", "sonar scan", "sonar rapor", "A rating"
+
+**Only a SonarQube analysis can say "rating A, 0 findings".** A clean `build` says the compiler was happy — a
+different claim, about a different rule set. Passing one off as the other is how a team is told the code is clean
+and then opens a report full of findings.
+
+You do **not** need a company server or someone else's token to get the real thing: **SonarQube Community Build is
+free, needs no licence key, and runs in one Docker container on this machine.** That is the default path here — the
+gate is produced locally, offline, and it is a genuine SonarQube verdict, not a proxy for one.
+
+Language-agnostic on purpose: SonarQube covers 20+ languages plus IaC (Terraform, Kubernetes, Dockerfile). Detect
+what the project actually uses; never assume a stack.
+
+## Step 1 — get a real analysis (pick the first that applies)
+
+**a) The project already has a SonarQube** → use it, and skip to step 2.
+
+**b) It does not → stand one up locally.** Docker one-liner, the Docker-free server zip, the first login and the
+token: **`references/stand-up-server.md`**. No licence, no external account, nothing leaves the machine.
+
+> **Restarting is not installing.** Bringing an already-approved service back up on this machine — the same
+> image, the same volumes — is resuming what the user already said yes to, and this skill's own advice to keep
+> a named volume assumes exactly that. A NEW image, a new volume, or a tool this machine does not have is an
+> install, and needs the answer below.
+>
+> **Nothing here is installed without the user saying so.** Docker, Java, a scanner, a linter — each is a proposal
+> with its cost stated, and the user picks. If they decline all of them, that is a valid answer: go to (c) and
+> report "unverified" rather than installing anything to make a number appear.
+
+Scan with whatever runner the project's stack uses — the scanner is the same product for every language:
+
+| Project | Scan command |
+|---|---|
+| Any stack (generic) | `sonar-scanner -Dsonar.projectKey=app -Dsonar.sources=. -Dsonar.host.url=http://localhost:9000 -Dsonar.token=$T` |
+| Maven / Gradle | `mvn sonar:sonar -Dsonar.host.url=… -Dsonar.token=$T` · `gradle sonarqube …` |
+| .NET | `dotnet sonarscanner begin /k:app /d:sonar.host.url=… /d:sonar.token=$T` → `dotnet build` → `dotnet sonarscanner end /d:sonar.token=$T` |
+| JS/TS, Python, Go, PHP, Ruby | the generic `sonar-scanner` above (add coverage report paths if the project produces them) |
+
+**c) No server is possible at all** (no Docker, no Java, no permission to run one) → run the language's Sonar-rule
+engine locally as a pre-check (**`references/local-engines.md`** — which engine per language, and how close it is
+to Sonar's own rules) and **say what that is worth**, in these words rather than a
+rating: *"the local rule engine reports N issues, none open; the SonarQube rating and the gate were not produced —
+no analysis ran."* Then list what stays unverified: taint/injection, hotspot review state, coverage, duplication,
+files outside the compiled language, and the project's own quality profile. Offer branch (b) — a local server, with
+or without Docker — as the way to close it.
+
+**Never invent the verdict.** A rating exists only where an analysis produced one; without it the honest output is
+"unverified", and that is the sentence that saves the user from promising a clean report they cannot back.
+
+## Step 2 — read the verdict, don't infer it
+
+```bash
+S=http://localhost:9000; K=app          # or the project's own host/key
+curl -sfu "$T:" "$S/api/qualitygates/project_status?projectKey=$K"     # pass / fail, and which condition failed
+curl -sfu "$T:" "$S/api/issues/search?componentKeys=$K&resolved=false&ps=500"   # rule id + file + line per finding
+curl -sfu "$T:" "$S/api/hotspots/search?projectKey=$K&status=TO_REVIEW"          # hotspots are a SEPARATE endpoint
+curl -sfu "$T:" "$S/api/measures/component?component=$K&metricKeys=alert_status,bugs,vulnerabilities,security_hotspots,code_smells,coverage,duplicated_lines_density,reliability_rating,security_rating,sqale_rating"
+```
+
+Also read the gate's definition (`/api/qualitygates/show`): most gates judge **new code**, not the whole project.
+Chasing overall counts while the gate measures new code burns days and still fails; the reverse leaves real debt.
+Know which one applies before planning the work.
+
+## Step 3 — fix by rule, never by impression
+
+Group findings by `rule` (`csharpsquid:S1481`, `typescript:S3776`, `python:S5852`, …) and take one rule at a time,
+all occurrences together. Read what the rule actually asks, fix the cause, cite the rule id in the change. The
+domain owner does the fixing — a security rule is `crew-security-expert`'s, a query/index rule is
+`crew-database-expert`'s.
+
+**Never close a finding by silencing it.** `#pragma warning disable`, `// NOSONAR`, `eslint-disable`, an exclusion in
+`sonar-project.properties` — each one changes the report without changing the code. It needs a written reason and
+the user's approval, every time.
+
+**Security Hotspots do not close by editing code.** Each is reviewed in the UI and marked *safe* (with a rationale)
+or *fixed*. Code changes alone leave it `TO_REVIEW` and the gate keeps failing.
+
+## Step 4 — re-scan and diff. The loop is the deliverable
+
+Re-run step 1's scan, re-read step 2, and report the **difference**: counts before → after, which rule ids
+disappeared, which remain, which are new. "It should be clean now" is not a result — a second analysis is.
+Repeat until the gate says `OK`, or every remaining finding has a user-approved suppression. Nothing here closes on a first pass.
+
+## What even a local SonarQube cannot see
+
+Community Build has no **taint/injection analysis** (data flow from user input to a dangerous sink — SQLi, XSS,
+command injection); that engine is in the paid editions. It also has no branch/PR analysis. So a clean local gate
+is not proof of injection safety: cover that with the **`security-scan`** and **`threat-model`** skills plus a
+`crew-security-expert` review, and say which of the two verdicts you are reporting.
+
+## DoD
+- The verdict is quoted **from an analysis**: gate status, counts by severity, ratings, analysis date, and where it
+  ran (project server or local container).
+- Every finding closed by a code change, or by a suppression the user explicitly approved with a written reason.
+- Hotspots reviewed in the UI, not merely edited around.
+- A re-scan ran after the fixes and the before → after diff by rule id is reported.
+- Injection risk stated separately (taint analysis is not in Community Build).
+- Anything not done is said plainly — never implied clean.

package/kit/skills/sonarqube-check/references/local-engines.md

@@ -0,0 +1,32 @@
+# Running Sonar rules locally with no server at all
+
+Read this only on branch (c) of step 1 — no server is possible (no Docker, no Java, no permission to run one), or
+as a pre-check before anything is scanned.
+
+This is worth more than it sounds: several languages have SonarSource's **own** rule engine as a normal dependency,
+so you can find and fix most rule violations offline, before anything is ever scanned. What no local engine can
+produce is the **verdict** — ratings (A/B/C), gate pass/fail, coverage, duplication, hotspot review state and the
+project's quality profile are computed by the server, from an analysis. Findings yes; a rating no.
+
+**The rule, for every language:** find whether SonarSource publishes its own rule engine for the project's
+language and wire *that* into the build or the editor. Where only a third-party look-alike exists, use it and say
+that the rule ids will not match the report. Ask which languages the repo actually contains — most repos have
+more than one, and each needs its own engine.
+
+| Stack (alphabetical — no language is the default) | Local engine | How close to Sonar's own rules |
+|---|---|---|
+| Go | `golangci-lint` and friends | Third-party; overlaps in intent, not in rule ids |
+| Java / Kotlin | SonarQube for IDE (SonarLint) in the editor; SpotBugs + PMD in the build | Editor-side runs Sonar analyzers; the build-side pair is a different rule set |
+| JS / TS | `eslint-plugin-sonarjs` | SonarSource's own JS/TS rules, delivered through ESLint |
+| .NET (C# · VB.NET) | `SonarAnalyzer.CSharp` / `.VisualBasic` (Roslyn, at build time) | SonarSource's own analyzer, 480+ C# rules; rule-set parity with the server is not documented either way — close, not proven identical |
+| PHP / Ruby / other | that language's linter | Varies; check whether it is SonarSource's or a look-alike |
+| Python | `ruff` / `pylint` + `bandit` | **Not Sonar rules** — an approximation |
+
+**Injection / taint rules are not in any of these** — they run only on SonarQube Server/Cloud, in the commercial
+editions. So even a spotless local run says nothing about SQLi/XSS/command injection; that gap is covered by
+`security-scan` + `threat-model` + a `crew-security-expert` review, and is reported as its own line, never folded
+into a "clean" claim.
+
+Pin versions so builds stay reproducible (with Central Package Management, declare it there). Turning warnings into
+errors is the project's call — propose it, don't impose it. And whatever the local run says, the honest wording
+stays: *findings fixed; rating and gate not produced — no analysis ran.*

package/kit/skills/sonarqube-check/references/stand-up-server.md

@@ -0,0 +1,25 @@
+# Standing up SonarQube Community Build locally
+
+Read this only on branch (b) of step 1 — the project has no SonarQube and one is being stood up. No licence, no
+external account, nothing leaves the machine.
+
+**The consent rule in SKILL.md governs every line below.** Docker, Java, a scanner — each is a proposal with its
+cost stated, and the user picks. Restarting an already-approved service is not installing; a new image, a new
+volume, or a tool this machine does not have is.
+
+```bash
+# b1 — with Docker (one command)
+docker run -d --name sonarqube -p 9000:9000 sonarqube:community    # first boot ~1-2 min
+
+# b2 — WITHOUT Docker: the plain server zip. Needs Java 17 or 21 on PATH (`java -version`), nothing else.
+#   download SonarQube Community Build, unzip (e.g. C:\sonarqube), then start it:
+#     Windows      C:\sonarqube\bin\windows-x86-64\StartSonar.bat
+#     Linux/macOS  ./bin/<platform>/sonar.sh console
+#   It runs on an embedded H2 database — no database to install for local use.
+```
+
+Either way: http://localhost:9000 · first login `admin`/`admin` · set a new password · then My Account → Security →
+generate a token. **That token is local and yours** — it is not a company credential and nothing is sent anywhere.
+
+Persist the container (`-v sonarqube_data:/opt/sonarqube/data`) so history survives, and put the key/exclusions in
+`sonar-project.properties` so every later run is identical.

package/kit/skills/spec-planning/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: spec-planning
+description: |
+  Spec-first planning: task breakdown, measurable acceptance criteria, dependency order, risk priority.
+  crew-planner applies it; the plan goes to docs/PLAN.md.
+  Use when the scope is unclear or the work spans more than one change.
+---
+
+# Spec-First Planning
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "plan", "spec", "task breakdown", "acceptance criteria", "roadmap", "how do we split this"
+
+Before writing code: what will be done, how it counts as "done", and in what order to proceed become clear.
+
+## Steps
+1. **Purpose & scope:** the problem being solved in a single sentence; also write the out-of-scope explicitly (prevent scope creep).
+2. **Split into vertical slices:** the smallest end-to-end working pieces (not horizontal layers). Each slice delivers value on its own.
+3. **A contract for every task:** input · output · **measurable acceptance criterion** (testable) · estimated risk.
+4. **Dependency graph:** which task waits on what; no cycles. **Bring the riskiest/most-unknown to the front** (fail-fast).
+5. **Uncertainties:** assumption list + open questions; do not fill ambiguous spots with a guess, ask with explicit options.
+
+## Output (docs/PLAN.md)
+```
+# <Feature> — Plan
+## Acceptance criteria
+- [ ] AC-1: <measurable outcome>
+- [ ] AC-2: <measurable outcome>
+## Tasks (order)
+1. <task> — satisfies: AC-1 — dependency: <none/#n> — risk: <low/medium/high>
+## Assumptions / Open questions
+- ...
+```
+
+**Every criterion carries a stable id, and every task names the ids it satisfies.** The id is what makes the plan
+checkable later: "AC-2 is only partly built" can be said, argued about and tracked; "the second checkbox" cannot,
+and renumbering a list silently re-points every reference to it. Never reuse or renumber an id — a dropped
+criterion keeps its id with a strike-through and a one-line reason. A criterion no task satisfies, and a task that
+satisfies no criterion, are both findings before a line of code is written.
+
+## Mark what you do not know — do not fill it in
+Where a requirement admits more than one reading, write the marker **`[NEEDS CLARIFICATION: <the question>]`** at
+that exact spot in the plan. Do not resolve it with the likeliest interpretation and move on.
+
+This is the difference between a discipline and a hope. "Stop and ask when unsure" (§1) depends on noticing the
+uncertainty in the moment; a marker survives into the artifact, where the user, a reviewer and a later session
+can all see it. A plausible assumption silently written into a spec is indistinguishable from a decision, and
+that is exactly how the wrong feature gets built correctly.
+
+Rules that keep it honest:
+- The marker carries the **question**, not the label. `[NEEDS CLARIFICATION: does an expired invite count as
+  used, or can it be re-sent?]` is actionable; `[NEEDS CLARIFICATION: invites]` is noise.
+- A plan may ship with markers — that is the point. It may **not** ship with a marker inside an acceptance
+  criterion: a criterion nobody can evaluate is not a criterion.
+- Resolve by asking, never by choosing. When the user answers, replace the marker with the answer *and* record
+  which reading was rejected — the alternative is what a future reader needs.
+- Zero markers on a genuinely ambiguous brief is a smell, not a win.
+
+## Converge — before the work is called done, hold the code up against the plan
+
+Tests prove the code does what the tests say. Nothing so far proves it does what the PLAN said: a criterion can be
+quietly half-built with every test green, and code nobody asked for can ride along unremarked. So when a plan
+exists, closing the work includes one pass that reads each criterion against the code as it now stands.
+
+Bound the pass to what the plan names — the criteria, the tasks, and the files and components they point at. Do not
+widen the audit into the rest of the codebase. For each `AC-n`, look at the code in that scope and record a finding
+**only where there is a gap**, classified as exactly one of:
+
+| Gap | Means |
+|---|---|
+| **missing** | nothing in the code implements the criterion |
+| **partial** | something does, but not all of what the criterion states |
+| **contradicts** | the code does something that conflicts with the criterion or a plan decision |
+| **unrequested** | the code contains work no criterion or task called for |
+
+`unrequested` is the one that is easy to skip and should not be: it is scope creep made visible (principle 3,
+"surgical change"). It is surfaced, never deleted by this pass — the user decides whether it stays, and if it
+does, it gets a criterion.
+
+Report it as a table — `AC-n | gap | evidence (file/area) | remaining work` — then either:
+- **Converged:** zero findings. Say so in one line, with how many criteria were checked.
+- **Not converged:** append each remaining item to the plan as a task that names its `AC-n`, and go back to
+  producing. Repeat the pass after that work, until it converges or the user accepts a named gap explicitly.
+
+This is model discipline, not a gate: no exit code can judge "partially built". What makes it hold is the table —
+a pass that produced no table did not run.
+
+## DoD (this skill's contribution)
+- Every task's "done" is testable; ordering and dependencies are visible; the riskiest work has been brought to the front.
+- Every unresolved ambiguity carries a `[NEEDS CLARIFICATION: …]` marker; no acceptance criterion contains one.
+- Every criterion has a stable `AC-n` id and at least one task that satisfies it; at close, a converge pass
+  has run and either reported **Converged** or left its remaining items in the plan as tasks.

package/kit/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: systematic-debugging
+description: |
+  Root-cause a bug before touching a fix: reproduce, isolate, form and test a hypothesis, confirm the cause,
+  then fix and verify. Stops guess-driven patching. For persistent, intermittent, or "already tried a few things" bugs.
+---
+
+# Systematic Debugging
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "debug", "root cause", "why is this failing", "intermittent bug", "can't reproduce", "is broken", "crashes"
+
+One rule holds the whole skill together: **no fix without a confirmed root cause.** A patch that makes the symptom
+disappear without a proven cause is not a fix — it's a coin flip that hides the bug until it returns somewhere worse.
+This skill is the discipline that turns "try things until it works" into "understand, then change one thing."
+
+> **Crewforth adaptation (local, .claude/):** Distinct from `iterate` (a self-correction loop over a *task*) and `reflect`
+> (meta-review of an approach) — this skill is for a *defect*. §4 Prohibitions apply; a fix still goes through the
+> project's review/test gates. Don't disable a test or a gate to make a symptom pass (that is masking, not fixing).
+
+## The loop (do them in order — skipping a step is why bugs come back)
+1. **Reproduce** — a reliable, minimal repro. Can't reproduce → that IS the first problem; see `references/techniques.md` (intermittent/heisenbug).
+2. **Isolate** — shrink the surface until the failure is in the smallest possible slice (bisect commits, halve the input, disable half the system).
+3. **Hypothesize** — state ONE falsifiable cause: "X fails because Y." Write it down. A vague hunch is not a hypothesis.
+4. **Test the hypothesis** — the cheapest observation that would *disprove* it (a log, a breakpoint, a probe). If it survives, you have the cause; if not, back to 3.
+5. **Confirm the root cause** — you can explain the full chain symptom←…←cause, and you can turn the bug on and off by touching the cause.
+6. **Fix** — the smallest change at the cause (not the symptom). Consider what else shares that cause.
+7. **Verify** — the original repro now passes, a regression test locks it, and nothing nearby broke.
+
+## Checklist
+- [ ] Reliable repro captured (exact steps/input/env)
+- [ ] Failure isolated to the smallest slice
+- [ ] One falsifiable hypothesis written down
+- [ ] Hypothesis tested by observation (not by applying a fix and seeing)
+- [ ] Root cause confirmed (can toggle the bug via the cause; full chain explained)
+- [ ] Fix at the cause + regression test added
+- [ ] Original repro passes; no new failures
+
+## Anti-patterns (each is guess-driven patching wearing a disguise)
+- **Shotgun debugging** — changing several things at once; now you can't tell what mattered. One change at a time.
+- **Symptom patching** — a `try/catch`, a null-guard, a retry that swallows the failure without explaining it.
+- **"It works now"** without knowing *why* it broke — the bug is dormant, not dead.
+- **Blaming the environment/flake** before isolating — sometimes true, but only *after* step 2, never as the first move.
+- **Deleting/skipping the failing test** to go green — that is masking; the gate exists to catch exactly this.
+
+---
+
+## Techniques by symptom
+Bisecting (git + input + system), instrumentation vs. debugger, intermittent/heisenbugs (timing, state, ordering,
+resource), the hypothesis log, and when to stop and ask for a second pair of eyes: **`references/techniques.md`**.
+
+## Invariant rules
+1. **No fix without a confirmed root cause** — the one rule; everything else serves it.
+2. **One change at a time** — isolate cause and effect; never shotgun.
+3. **Fix the cause, not the symptom** — a guard that hides the failure is not a fix.
+4. **Lock it with a regression test** — the repro becomes a test so it can't silently return.
+5. **Never mask to go green** — don't disable a test/gate/assertion to make the symptom pass.

package/kit/skills/systematic-debugging/references/techniques.md

@@ -0,0 +1,44 @@
+# Debugging techniques by symptom
+
+Loaded on demand — the SKILL.md loop is the method; this is the toolbox for a specific kind of bug.
+
+## Isolation: how to shrink the surface (step 2)
+
+- **git bisect** — a regression that "used to work". `git bisect start; git bisect bad; git bisect good <rev>` then let it binary-search the commit that introduced it. Automate with `git bisect run <cmd>` where `<cmd>` exits 0 on good, non-zero on bad.
+- **Binary-search the input** — halve the failing input until the smallest reproducing case remains. A 10k-row file that fails narrows to the one row; a 500-line config to the one key.
+- **Halve the system** — disable half the middleware / feature flags / plugins. Failure gone → it's in the disabled half. Repeat.
+- **Minimal repro** — rebuild the failure in isolation (a scratch script, a single failing unit test). If it won't reproduce in isolation, the cause is in the *environment/state* you left out — that's a finding, not a dead end.
+
+## Instrumentation vs. debugger
+
+- **Logging/print** — best for intermittent, timing, production, and "can't attach" cases; leaves a trace across runs. Log the *hypothesis-relevant* value, not everything. Remove or gate the probes before committing.
+- **Debugger/breakpoint** — best for a reliable, local repro where you want to inspect live state and step. Conditional breakpoints (`x == badValue`) skip the noise.
+- **Assertions/invariants** — add a check that *should* always hold; the point it fires is upstream of the symptom.
+- **Bisect on values** — binary-search *when* a value goes wrong: log at start/middle/end of the pipeline, then narrow.
+
+## Intermittent / heisenbugs (can't reliably reproduce)
+
+The cause is almost always one of:
+- **Timing / races** — order of concurrent operations; add delays/logging to widen the window and expose it. A bug that vanishes when you add a log is a timing bug (the log changed the timing).
+- **Shared/leaked state** — a previous test/run left state behind; run the case in full isolation and in a different order (`--shuffle`).
+- **Ordering dependence** — passes alone, fails in the suite → cross-test coupling. Bisect the test order.
+- **Resource / environment** — memory pressure, disk, clock, locale, network flake, an unpinned dependency version. Pin and compare.
+- **Uninitialized / nondeterministic** — reads of uninitialized memory, map iteration order, unseeded randomness, `Date.now()`.
+
+Make it reproducible *first* (loop the case 100×, add stress, shuffle). An intermittent bug you can't trigger on demand can't be confirmed fixed.
+
+## The hypothesis log
+
+For a bug that resists a few rounds, write it down — it stops you from re-testing the same dead hypothesis and reveals patterns:
+
+```
+Symptom: <exact observable failure>
+Repro:   <steps / input / env>
+H1: <cause> → test: <observation> → RESULT: disproved (saw X, not Y)
+H2: <cause> → test: <observation> → RESULT: CONFIRMED (toggles bug)
+Root cause: <the confirmed chain>  Fix: <change at cause>  Test: <regression test>
+```
+
+## When to stop and get a second pair of eyes
+
+After ~3 disproved hypotheses with no new information, or when you've been staring at the same 20 lines — you likely hold a wrong assumption you can't see. Escalate: hand over the hypothesis log (not "it's broken") so the next person starts from what's *already ruled out*, not from zero. In Crewforth, that handover is the `handoff` skill.

package/kit/skills/teamboard/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: teamboard
+description: |
+  Experimental: a shared team board. Claim a work item, hand it over, finish it; the claim is a git-ref
+  lock, so two people cannot take the same item.
+metadata:
+  experimental: true
+---
+
+# Team Board (shared claims + shared item memory)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "team board", "who is working on", "claim", "take this item", "pick up a task", "sprint item", "release the item", "hand the item over", "is anyone on", "board", "of us are working", "stepping on each other", "who is doing what", "who else is working"
+
+## The problem this closes
+Every teammate runs Crewforth **locally**. `docs/PLAN.md` and `docs/SESSION_STATE.md` are gitignored, so the fact
+that Ali started item #1 two hours ago exists nowhere the other sessions can see. Two people start the same item;
+a blocked item gets picked up before its dependency lands; whoever inherits half-finished work rebuilds the
+context from scratch. The board makes those three facts shared.
+
+## The engine (all commands go through it)
+`bash .claude/hooks/board.sh <cmd>` — `status` · `show <id>` · `claim <id>` · `done <id> [note]` ·
+`drop <id> <note>` · `note <id> <text>` · `add <id> <title> [deps] [external]` · `init` · `sync`.
+Never hand-edit the board; every write must go through the engine or it loses its atomicity.
+
+## Why a claim is a real lock, not a convention
+The board lives on a git ref (`refs/crew/board`), not in the worktree. A claim is a commit pushed to that ref, and
+`git push` is fast-forward-only: when two people claim the same item from the same base, **one push is rejected**
+and that session re-reads the board and refuses. This is an atomic compare-and-swap with no server, no token and
+no daemon. The engine builds its commits with git plumbing, so claiming **never touches your working tree,
+index, branch or stash** — you can claim mid-feature with dirty files.
+
+## Off by default; on when a team asks for it
+A repo that never ran `init` **has no board and no gates** — no claim, no commit gate, no edit gate, nothing at
+session start. Solo work is unchanged, and so is every project that installed Crewforth before this existed. Do not
+create a board because a repo merely has more than one contributor; create one when the user says the team keeps
+colliding. Creating one, choosing between its three levels and the ref-namespace fallback: **`references/setup.md`**
+— one person runs it once, and everybody else configures nothing.
+
+Already have a board and want it out of the way? `/crew-board off` (add `--global` for every repo) releases **all
+three** gates and leaves the board itself intact; `/crew-board on` restores it. `CREW_NO_BOARD=1` does the same for
+one session. This half stays here on purpose: someone a gate has just stopped needs the answer without opening a
+second file.
+
+## The rules
+1. **Claim before you touch code.** `claim <id>` fails if someone else holds it, if it is done, or if a
+   dependency is unfinished — with the reason and the list of what *is* claimable. Do not argue with a refusal;
+   take a free item.
+2. **Two gates, not one, and the early one is the point.** The first file edit is refused while you hold no item
+   (`guard-write.sh`) — unclaimed work is caught at minute one, not at commit time after an afternoon of it. The
+   commit then has to carry `[#<id>]` for an item you hold and that is `in_progress`, or `[chore]` for work
+   belonging to no item. In a repo with no board neither gate exists. `CREW_NO_BOARD=1` disables both for a
+   session; say so out loud if you set it.
+3. **Never release silently.** `drop` REQUIRES a handover note, because the whole cost of a handover is the
+   context the next person does not have: where exactly it stands, which files, and *why* the rejected approach
+   was rejected. `done` takes a completion note (what shipped, commit/PR).
+4. **Never steal a stale claim.** A claim with no heartbeat for `stale_hours` (default 8) is reported as STALE.
+   Stale means *ask the owner*, not *take it*. Surface it to the user and let them decide.
+5. **Read before you plan.** At session start the board summary is injected automatically. Before proposing what
+   to work on, run `status` — recommending an item somebody already holds is the failure this exists to prevent.
+
+## Redaction — the board is shared
+Everything written here is pushed to a remote the whole team reads. `handoff`'s `<private>…</private>` rule
+applies unchanged: strip secrets, tokens, credentials and personal notes, leave `[redacted]`, and point at
+*where* a value lives (env var, secret manager, the person to ask) rather than the value.
+
+## Filling the board
+Items come from either direction, and both end at `add`:
+- **From a plan:** `crew-planner` + `spec-planning` produce `docs/PLAN.md` with measurable acceptance criteria and
+  a dependency order; each task becomes one `add <id> <title> <deps>`. Keep the plan's dependency edges — they
+  are what makes `claim` able to refuse blocked work.
+- **By hand:** the user dictates the items.
+
+## Tracker link (honest boundary)
+Teams use Jira, Trello, Linear, GitHub Issues or nothing, so Crewforth **binds to none of them**. An item carries an
+optional `external:` field, which is a link and nothing more — no sync, no import, no write-back. A team that
+wants two-way sync writes an executable `.crew/board-adapter.sh` answering two verbs: `import` (emit
+`<id>|<title>|<deps>|<external>` lines to be fed to `add`) and `export <id> <status>` (push the state outward).
+Crewforth ships no adapter; do not claim integration Crewforth does not have.
+
+## When the remote is unreachable
+Claims stay local and are labelled `UNSHARED` — meaning **the team cannot see them**, so the lock is not in force.
+Say that plainly rather than reporting success, and re-run `sync` once the network is back.
+
+## DoD
+- Work started only on an item held by this user; the board shows it `in_progress`.
+- An item left for any reason carries a handover note a stranger could resume from.
+- `done` recorded with what shipped, and the dependents it unblocked named to the user.

package/kit/skills/teamboard/references/setup.md

@@ -0,0 +1,37 @@
+# Setting a board up — one person, one command
+
+Read this only when a board is being created or its level changed. Claiming, dropping and finishing an item never
+need it: a teammate who clones the repo configures nothing.
+
+## Who runs what
+
+- **Whoever starts it:** `/crew-board init`, then add the items. It probes what the server accepts, creates the
+  board on the code repo's own `origin`, and that is the whole setup — no account, no token, no service.
+- **A separate board repository:** `/crew-board init --remote <url>` (or an existing remote's name). Use it when
+  the board is shared across several repos, or when people who must claim work cannot push to the code repo. It
+  gets its own `crew-board` remote and never touches `origin`.
+- **Everyone else: nothing.** They clone as usual. Session start fetches the board on its own (detached), the
+  ref namespace is auto-detected including the orphan-branch fallback, and `/crew-board` fetches on the spot if
+  the background refresh has not landed yet. Never tell a teammate to run `init` — a second `init` is how a team
+  ends up with two boards.
+
+## The ref namespace, and the fallback
+
+`init` first probes whether the server accepts a custom ref namespace (`refs/crew/board`); if it does not, it
+falls back to the orphan branch `refs/heads/crew-board`, which every server accepts and which enforces the same
+fast-forward rule. Do not merge that branch into code.
+
+## Which level to create
+
+Do not create a board because a repo merely has more than one contributor; create one when the user says the team
+keeps colliding. Three levels, and the user picks:
+
+| | Effect |
+|---|---|
+| no board (default) | nothing at all |
+| `require_item: referenced` in the board's `config` | claims and the shared memory, but no gate: a commit is only checked when it names an item |
+| `require_item: all` (what `init` writes) | claim before you edit, and every commit names an item or `[chore]` |
+
+A board with no remote is fine too — you get the item list, the dependency order and the gates, just nothing
+shared. Turning the gates off on an existing board is in SKILL.md, not here: someone a gate has just stopped
+needs that answer without opening a second file.

package/kit/skills/testing/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: testing
+description: |
+  The how of testing: pyramid, AAA, isolation, risk coverage, determinism. Guarantees the DoD's "tests are
+  green". crew-test-expert applies it.
+  Use when writing or changing tests, or when a suite is flaky, slow or green for the wrong reason.
+---
+
+# Testing Discipline
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "write a test", "run the tests", "coverage", "are the tests green", "unit test", "integration test", "tests pass locally", "flaky test", "test is flaky"
+
+Goal: **behavior correctness** — test real behavior without breaking product code just to make a test pass.
+
+## Principles
+- **Pyramid:** many unit, fewer integration, few end-to-end (e2e). Limit e2e to critical flows.
+- **AAA:** Arrange-Act-Assert; **one test = one behavior**.
+- **Isolation & determinism:** external dependencies are mocked/faked; time and randomness are fixed; test order is independent.
+- **Risk-coverage:** risk, not metrics. Critical path + **boundary** + **negative** + **authorization (IDOR/404)** scenarios.
+- **Naming:** `what_it_tests_under_which_condition_what_it_expects` — on failure it is clear what broke.
+- **Red-green:** first a failing test, then the implementation.
+
+## Watch out
+- **Flaky = bug:** an occasionally failing test is not tolerated; it is fixed at the root.
+- In snapshot/golden-file tests, avoid needless brittleness (assert only the meaningful output).
+
+## Tests that cannot fail
+
+Green is evidence only if the test could have gone red. Shapes that check nothing:
+- **Assertion restates the code:** it recomputes the implementation's own expression, so it moves with every change.
+- **Setup guarantees the result:** arrange plants the value the assert reads back; it holds even if the act never ran.
+- **Expected value derived the way the code derives it:** same formula, query or parser — the same wrong assumption on
+  both sides still matches.
+- **A double asserted against its own stub:** the fake is told to return X and the test asserts X; only the fake runs.
+- **No assertion:** it passes because nothing threw. If *not throwing* is the behavior under test, assert that.
+
+**Prove it can fail:** break what the test covers — invert a condition, return a wrong constant — confirm it goes red,
+then restore. Still green means the test is documentation, not a gate: fix it or delete it, never count it as coverage.
+
+## Flaky triage
+An intermittent failure gets exactly one outcome, decided the day it is seen: **fix** it, **quarantine** it (out of
+the gating lane, never out of the suite, with an owner and a date), or **escalate** it as the product defect it
+signals. Infrastructure flakes may get a bounded, logged retry; product flakes never do. Classifying them, the retry
+rule, and what a quarantine entry must carry: **`references/flaky-triage.md`**.
+
+## DoD (this skill's contribution)
+- The project's own test command is green — read it off the manifest/CI (`dotnet test` · `npm test` · `pytest` ·
+  `go test ./...`), don't assume one; critical paths are covered; no empty/meaningless tests.

package/kit/skills/testing/references/flaky-triage.md

@@ -0,0 +1,51 @@
+# Flaky test triage
+
+Loaded on demand — SKILL.md holds the rule (`Flaky = bug`); this is the decision procedure for one that has already
+failed intermittently. A test that passes and fails on the same commit gates nothing, and every red run it produces
+teaches the team to ignore red runs. Triage it the day it is seen and record the outcome.
+
+## 1 · Classify first: infrastructure or product
+The two kinds get opposite treatment, so this call comes before the outcome.
+
+- **Infrastructure flake** — fails the same way regardless of the test's logic, and clusters in time. Signals:
+  identical error text across unrelated tests (connection refused, image pull, no disk, name resolution); a whole
+  run or one machine fails and the next run passes with no code change; the assertion is never reached.
+- **Product flake** — follows the data or the ordering. Signals: it tracks one case, fixture or seed; it appears
+  only under randomized order or parallel execution; it reproduces in a loop on one machine; the assertion *is*
+  reached and the value is wrong.
+- Cannot tell yet → treat it as a product flake. Guessing "infrastructure" is how a real race gets a retry put
+  around it.
+
+## 2 · Retry policy follows that classification
+- **Infrastructure: a bounded retry is allowed** — a fixed cap decided once and written down, applied where the
+  resource is owned (readiness wait, fixture setup, the job step), never around an assertion. Log every retry that
+  fires: a retry nobody can see is a failure nobody counts, and a rising count means the label was wrong.
+- **Product: never retry.** A retry there turns a real bug into a slower green — the defect ships and the suite
+  reports success. Widening a timeout and sleeping until it passes are the same move under another name.
+
+## 3 · Three outcomes — pick exactly one, in writing
+| Outcome | Use when | What it requires |
+|---|---|---|
+| **Fix** | the test or the code under it is genuinely wrong: unfrozen clock, unseeded randomness, shared state, order dependence, an assertion on something unordered | the change, plus a run that reproduced the old failure (loop, shuffle, parallel) and now holds |
+| **Quarantine** | the failure is real but not yet understood, and blocking every other change on it costs more than the coverage it holds | a named owner, a date, a linked issue — and the test still executing |
+| **Escalate** | the flake is a symptom, not a test defect: a race, a leak, a resource limit, an unsafe ordering in the code under test | hand it over as a product defect and root-cause it (`systematic-debugging`) |
+
+Escalate means the change lands in product code. Rewriting the test to step around the race deletes the only
+evidence that the race exists, and it resurfaces in production instead of in CI.
+
+## 4 · Quarantine has a shape, or it is deletion
+- **Scoped, not removed.** The test leaves the *gating* lane, not the suite: it keeps running in a non-gating or
+  scheduled job, so its failure rate stays visible and the fix can be proven.
+- **Owner and date, always** — both stored next to the test (marker, tag, or an explicit list the gating job filters
+  on) and re-read on that date. If nobody will own it and no date fits, the honest outcome was Fix or Escalate.
+- **Re-decide on the date**, choosing again from the three. A quarantined test nobody returns to is worse than a
+  deleted one: it reports coverage that is not being checked.
+- Deleting the test deliberately, with the reason recorded, is a legitimate end state. Silent expiry is not.
+- Quarantine is not a way to go green for a release; an escalate-class flake blocks the release it belongs to.
+
+## Boundary with the rest of the discipline
+- Disabling or skipping a red test to finish a task is masking, not quarantine: masking removes the signal,
+  quarantine relocates it and puts a date on it.
+- Making an intermittent failure reproduce on demand — loop the case, randomize order, add stress, widen the timing
+  window — is `systematic-debugging/references/techniques.md`. Triage without a repro is a guess.
+- The quarantine list is a debt list. If it only grows, nothing is being fixed: report the count and the oldest entry.