crewforth 0.0.1 → 3.0.0-rc.1

package/kit/skills/crew-code-review/references/panel-mode.md

@@ -0,0 +1,32 @@
+# Panel mode — adversarial expert panel
+
+For a **consequential, hard-to-reverse** decision (an architecture choice, a public API contract, a security
+boundary) a single-lens review under-covers. Run an **adversarial expert panel**: evaluate the change from
+**several independent lenses in parallel**, each arguing on its own terms, then synthesize.
+- **Distinct lenses, not repetition:** e.g. *correctness/edge cases · security & privacy · maintainability &
+  altitude (YAGNI) · operational cost/perf*. Give each lens a real advocate whose job is to find where the
+  change fails on *that* axis — diversity catches failure modes redundancy can't.
+- **Adversarial by default:** each lens tries to refute "this is the right change", not to bless it. A concern
+  raised by one lens isn't overruled by the others' approval — it's recorded and weighed.
+- **Synthesize, don't average:** collect every lens's findings, keep the sharpest objection from each, and
+  reach one decision (proceed / proceed-with-changes / reject) with the reasoning. This is the distilled
+  judge-panel pattern — reserve it for high stakes; routine diffs get the single-lens review above (don't
+  burn a panel on a one-liner).
+
+## The lenses (named, first-class)
+
+Pick the lenses that fit the change — not all six every time. Each is a distinct advocate; assign one concern per
+lens so they don't collapse into the same review twice.
+
+| Lens | Asks | Fails the change when |
+|---|---|---|
+| **Correctness** | Does it do the right thing on every path? | An edge case, race, off-by-one, or error path is unhandled |
+| **Security & privacy** | Can it be abused; does data leak? | Injection, missing authz, secret exposure, PII beyond purpose (→ `security-scan`, `privacy-compliance`) |
+| **Simplicity & altitude** | Is it more than the problem needs? | Over-engineering, speculative generality, YAGNI, wrong abstraction level |
+| **Contract & compatibility** | What breaks downstream? | A public API / schema / event shape changes without a migration or version (→ `api-design`) |
+| **Operability** | What happens at 3am in prod? | No logs/metrics on the new path, silent failure, no rollback (→ `observability`, `incident-runbook`) |
+| **Verifier integrity** | Is the *check* still honest? | A test/assertion/threshold was weakened to pass, instead of the behavior being fixed |
+
+**Adversarial pairing:** the strongest panel pits lenses that pull against each other — Simplicity vs. Contract
+(don't over-build, but don't break callers), Correctness vs. Operability (handle every case, but stay debuggable).
+When two lenses conflict, that tension IS the decision to surface — resolve it explicitly, don't let one silently win.

package/kit/skills/crew-code-review/references/receiving.md

@@ -0,0 +1,23 @@
+# Receiving a review — an inbound comment is a candidate, not an instruction
+
+Read this on the skill's other mode: the review is someone else's and the code is yours — a teammate's comments, a
+quality gate's report, a bot's PR review.
+
+**Read every item before changing any line.** Comments are written one per symptom, and two of them
+often share one cause; applying them in arrival order yields a patch per symptom instead of one fix at the cause.
+Group by cause, then decide.
+
+Each item then earns the same disprove pass as a finding of your own. Any "no" below is a reason to answer in the
+thread, not to edit:
+1. **Defect or preference?** Give each comment a severity and a category from SKILL.md — inbound prose arrives
+   unranked, you rank it, and only a `critical` or `high` blocks.
+2. **Does it hold where the reviewer did not look?** Check the call sites and callers the comment never opened.
+3. **Does it contradict a decision already recorded?** An `adr` or a documented constraint outranks the comment —
+   reopen the decision, do not quietly edit around it.
+4. **Does the real check still pass with it applied?** Run it, don't re-read it. A suggestion that turns a check
+   red is reported back, and never satisfied by weakening the check (Verifier integrity, in SKILL.md).
+5. **Is it against the current revision?** A comment on an older one may already be answered by a later commit.
+
+Every inbound item leaves with a disposition from SKILL.md's triage table; none is left merely read. **A reasoned
+refusal is an answer** — say why in the thread and let the reviewer press it or drop it. Not doing it quietly is not
+an answer: it reads as agreement, and the same comment returns on the next review.

package/kit/skills/crew-doctor/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: crew-doctor
+description: Health-check the install — hooks executable, core.hooksPath set, gates wired, discipline loaded.
+metadata:
+  kind: command
+---
+# /crew-doctor
+Verify Crewforth is actually *active* in this project (not just present on disk):
+1. Run `bash .claude/eval/doctor.sh`.
+2. Read its report. It checks: VERSION present · every hook executable · the required git hooks (pre-commit,
+   commit-msg) present · **guard-bash actually blocks a force-push** (catches a hook that is present but neutered) ·
+   `core.hooksPath` points at `.claude/hooks` (else the §4.1/§4.2 commit trace + secret/bloat scan never runs) ·
+   `settings.json` valid and wiring the PreToolUse / UserPromptSubmit / Stop gates to **non-empty** hook arrays
+   (an empty `[]` wires nothing); SessionStart (rehydration) is reported as a warning if absent · **`./CLAUDE.md`
+   actually imports `.claude/DISCIPLINE.md`** — without that line the discipline sits on disk and never loads, which
+   every other check is blind to.
+3. For each ❌, apply the printed fix. Anything that changes git config or file permissions needs approval first —
+   show the exact command and wait.
+4. Read the **Readiness** block too. It is advisory (never changes the verdict) and asks a different question — is
+   this *project* set up to be worked on by agents: CLAUDE.md project section filled in · a project-specific skill
+   alongside Crewforth's generic ones · a devcontainer to sandbox agent commands · an MCP server · CLAUDE.md not
+   drifted behind the code. Report the gaps as suggestions, not as failures, and never "fix" them unasked — adding
+   a devcontainer or an MCP server is the user's call.
+5. Summarise: **healthy**, or the precise fixes applied/needed, plus the readiness score. If it's not a git repo,
+   note that the commit-time gates need `git init` + `git config core.hooksPath .claude/hooks`.
+   If the output contains a line starting with ⭐, pass it to the user verbatim as the LAST line of your summary —
+   it prints once per Crewforth version, and it is meant for the user, not for you.
+
+If `.claude/eval/doctor.sh` doesn't exist, this is not a full (start.sh / adopt.sh) install — Crewforth is likely
+running as a **plugin**, whose hooks are managed by Claude Code itself; there's nothing for the doctor to check.
+
+**The eval scripts are installer-only, by decision.** `eval/` — `doctor.sh`, `smoke-test.sh`, `routing-eval.sh`,
+`scan-skill.sh`, `utilization.sh` — ships with `start.sh` and `adopt.sh` and NOT with the plugin edition. The eval
+scripts are developer instruments: they inspect an installation from outside it, and the plugin edition has no
+installation to inspect. Say this plainly when someone asks why `/crew-doctor` reports nothing on a plugin install,
+rather than treating it as a defect. The Studio panel ships in both editions (`/crew-studio`).

package/kit/skills/crew-gates/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: crew-gates
+description: Gate report — what the tool-level gates actually did, and which rules nothing has tripped.
+argument-hint: "[--log <path>]"
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+
+Run the report and read it back to the user:
+
+```bash
+bash .claude/eval/gate-report.sh $ARGUMENTS
+```
+
+Then interpret it in two sentences, in the user's language:
+
+- **Exit 3 (no log).** Say plainly that gate activity is *not measured* — not that the gates never fired. Offer
+  the one-line opt-in the report prints. Do not present the rule count as if it were evidence of anything.
+- **Exit 0.** Lead with the verdict split (how often the gates asked vs blocked). Then the notable rules: a rule
+  firing repeatedly is worth a conversation ("something keeps reaching for this"), and the not-observed list is
+  a prompt to check whether a rule *can* still match, not a delete list. `smoke-test` is what proves a rule can
+  fire; this only shows what tripped it.
+
+Never infer that a gate works because it appears in the report, or that it is broken because it does not.

package/kit/skills/crew-handoff/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: crew-handoff
+description: Session handover — SESSION_STATE.md + /clear suggestion.
+metadata:
+  kind: command
+---
+# /crew-handoff
+applies the `handoff` skill:
+1. Read the measured fill: the `🔋 Session` line, or `bash .claude/hooks/context-usage.sh --verbose`.
+2. Write an actionable handover to `docs/SESSION_STATE.md`: Done · In progress (exactly where) · Next step · Open decisions · File pointers · Blockers.
+3. Preserve decision rationale; the next session should not start from scratch.
+4. **Cold-reader pass** (`handoff/references/cold-reader.md`): the questions are written from the work BEFORE the
+   file, then answered from the file alone. Anything unanswerable goes back into the handover and is re-checked.
+5. Once written — and only once every question is answerable — suggest `/clear`.

package/kit/skills/crew-plan/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: crew-plan
+description: Spec-first planning — break down ambiguously scoped work with crew-planner.
+argument-hint: "[task/feature description]"
+metadata:
+  kind: command
+---
+# /crew-plan
+Argument: $ARGUMENTS
+
+Delegate to the @agent-crew-planner agent (spec-planning skill). For ambiguously scoped work:
+1. Clarify the goal + what's out of scope.
+2. Split into vertical slices; give each task a measurable acceptance criterion.
+3. Order by dependency + put the riskiest first.
+4. Ask about ambiguities with **explicit options**; write down the assumptions.
+
+Write the output to `docs/PLAN.md`, return a summary + pointer to the main thread (token-budget).
+Do NOT write code — this is a planning step.

package/kit/skills/crew-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: crew-review
+description: Review pass — review + security + quality gates.
+metadata:
+  kind: command
+---
+# /crew-review
+Run the change set through the review trio (read-only). **The audits go out in parallel; the reviewer closes.**
+1. **At once, in ONE message** — several `Agent` calls, because none of these writes code and so there is
+   nothing to serialise:
+   - @agent-crew-security-expert (security-scan) — auth/IDOR/injection/secret; findings with severity.
+   - @agent-crew-performance-expert (`performance`) — hot path, query/loop, render, payload. Reports
+     **candidates** (reasoned) and **findings** (measured) separately; an unmeasured claim is never a verdict.
+   - @agent-crew-privacy-agent (`privacy-compliance`) — **when the diff touches personal data**: legal basis,
+     minimisation, retention, transfer.
+2. (if SonarQube is in use) **sonarqube-check** — 0/0/0/0 gate (language-agnostic).
+3. **Last, and only once 1-2 are clean:** @agent-crew-review-agent (code-review) — "does it improve overall code
+   health"; severity-ranked comments. It is the closing reviewer in every writing agent's Coordination ("at
+   closure, report findings to crew-review-agent"), so it reads a diff the audits have already cleared — not the
+   other way round.
+
+Each agent returns a **short summary** to the main thread; raw output goes to `docs/` if needed. Do NOT modify code;
+collect findings in severity order, and leave the fix to the relevant expert.

package/kit/skills/crew-ship/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: crew-ship
+description: DoD gate + commit proposal (waits for approval).
+metadata:
+  kind: command
+---
+# /crew-ship
+Closure flow — in order:
+1. **DoD gate:** was `/simplify` applied · are tests green (@agent-crew-test-expert) · (if SonarQube is used) `sonarqube-check` 0/0/0/0.
+   If any one is red, **STOP**, report what is missing; no deferral.
+2. If clean, @agent-crew-commit-agent (commit-message) **proposes** an atomic Conventional Commit from the staged diff.
+3. Commit runs ONLY if the user says "commit" (§4.4). "Done" is not approval.
+4. **Close the board item too** (`teamboard`), when one is held. Closing work is one movement: ask what shipped,
+   run `board.sh done <id> "<note>"`, name the items it unblocked, and offer the next one as options. Do not
+   leave this to the user to remember — a claim nobody closes reads to the whole team as still in progress, and
+   the items behind it stay unclaimable. If a decision came out of this work that changes how other items must
+   be done, record it with `board.sh decide` in the same breath; it is worthless in a session nobody else reads.
+
+No destructive operations (§4.5). No AI trace / vendor name in the message (§4.1/§4.2 — the hook already scans).

package/kit/skills/crew-skill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: crew-skill
+description: Author or change a Crewforth component (skill / agent / command) against the template and its gates.
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-skill
+
+`AGENT_TEMPLATE.md` states the contract for a component. Full installs carry it (refreshed on `update`); the
+plugin edition does not. No gate routes to it, so this command is the route, and it ends in the gates.
+
+**A component is not finished when it is written. It is finished when the suite says so.**
+
+## 1. Decide the shape before writing anything
+Read `.claude/AGENT_TEMPLATE.md`. Then answer, in one line each:
+
+- **What is the smallest form that works?** A rule in an existing skill's body beats a new skill; a new skill beats
+  a new agent. Every new skill costs its NAME in every session, forever, for every user — and its description too,
+  until the listing overflows its budget, at which point descriptions start being dropped from the skills you
+  invoke least. Say what that buys.
+- **Who reaches it?** An agent, a command, or the discipline's trigger map. If the answer is "the model will notice
+  the description", stop — that is the dark component §3b exists to catch.
+- **Read or write?** A component that reports and a component that changes files do not belong together: different
+  risk, different done-criterion. Split them.
+- **Is it stack-neutral?** Anything shipped to every profile names no language, framework or vendor as *the* case.
+  The example you have in mind is not the scope.
+
+## 2. Write it
+- Skill: `.claude/skills/<name>/SKILL.md` — the directory name and the `name:` field must match. Keep the body
+  lean; depth goes to `references/*.md` and is loaded on demand.
+- Agent: a thin trigger — *who and when*. The *how* lives in the skill it applies; do not copy the method in.
+- The `description` says **when to reach for this**, not what its author knows.
+
+## 3. Register it — the cascade, in this order
+Skipping one of these is how a component ships half-installed:
+1. **Route it.** Name it in an agent body, a command, or the trigger map. §3b checks exactly this.
+2. **Golden case.** Add a positive line to `.claude/eval/golden-routing.txt` — and a **negative** one
+   (`prompt|!target`) for a neighbour it must NOT steal.
+3. **Catalog + counts** *(Crewforth repository only — `packaging/` is not installed anywhere)*.
+   Add the Turkish summary line (`packaging/skill-summaries.tr.tsv`; agents and commands have their own `.tr.tsv`),
+   which the site build requires (`cd site && npm ci && npm run build`), and the diagrams if the component set changed:
+   `node packaging/gen-diagrams.mjs` writes `assets/`, and smoke fails while any of them is stale.
+4. **Plugin edition** *(Crewforth repository only)*. `bash packaging/build-plugin.sh` — in the same commit, or the
+   release stops at the sync gate.
+5. **Budget.** A new skill moves `BUDGET_SKILLS`; raise it in the same commit with the justification comment the
+   file's convention requires. Never raise it to make a red gate green without saying why.
+
+## 4. Prove it — run all four, in this order
+```
+bash .claude/eval/scan-skill.sh .claude/skills/<name>    # supply-chain: SAFE, and rc=3 means NOT scanned
+bash .claude/eval/routing-eval.sh                        # the golden case, positive and negative
+bash .claude/eval/smoke-test.sh                          # structure, budget, §3b routed, cross-links
+CREW_NO_STAR=1 bash .claude/eval/doctor.sh               # the live install still healthy (star line off here)
+```
+
+In the plugin edition none of the four commands above exist — it ships no `eval/` at all — so there the proof is
+the Crewforth repository's own suite, not a local run.
+
+**Do not finish while §3b is red.** "It works when I invoke it by name" is not the claim being tested — the claim
+is that something reaches it without being told to. If the suite skips a case, that is not a pass: chase why.

package/kit/skills/crew-studio/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: crew-studio
+description: Open Crewforth Studio — the visual panel for what agents are doing, what they spent, and which gates fired.
+argument-hint: "[--port <n>]"
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-studio
+
+Start the panel and hand the user its URL. Never leave a half-started server behind: if any step below
+fails, say which one and stop — do not improvise a different launch.
+
+1. **Resolve the panel.** Both editions carry it, in different places, and this one file serves both.
+
+   ```
+   PLUGIN_PANEL=${CLAUDE_PLUGIN_ROOT}/studio/server/index.js
+   ```
+
+   Claude Code replaces `${CLAUDE_PLUGIN_ROOT}` in this text **before you read it**, and only when this
+   command came from the plugin. So read the line above literally:
+
+   - It names a real absolute path → **plugin edition**. That is the panel. Use it.
+   - It still contains the characters `${CLAUDE_PLUGIN_ROOT}` → this is a **full install**. The panel is
+     `.claude/studio/server/index.js`.
+
+   The variable is not in the shell's environment — it is text substituted into this file — so never try
+   to read it with `printenv` or let a shell expand it. Never write the unbraced `$CLAUDE_PLUGIN_ROOT`
+   either; only the braced form is substituted, and the unbraced one reaches bash unset and collapses the
+   path to `/studio/server/index.js`.
+
+   Neither path is there? Then this is an install older than the release that added the panel:
+   `npx crewforth@latest update --here --yes` at the project root, or `/crew-update`.
+   Then stop. Do not go hunting for the panel anywhere else on disk.
+
+   **What the plugin edition cannot show.** A plugin install puts no `.claude/VERSION`, `kit.conf` or Crewforth
+   scripts into a project. So that project's row in the list has no version badge (each row reads its own
+   project), and for the project you opened the panel from, the inspector's gates, stats and board tabs
+   say "Not measured" with the reason, rather than zero. The gates tab can still list observed entries
+   below that. The plugin's Bash guard logs its blocks, approval prompts and `CLAUDE_GIT_OK` pre-authorised
+   git actions, and its gate-file write guard logs its blocks, to `.claude/gate-log.tsv` when the project
+   has a `.claude/` directory and the file is git-ignored or the project is not a repo. With `CREW_GATE_LOG`
+   set they write wherever it points instead, and the panel reads only the project's own
+   `.claude/gate-log.tsv`, so a log sent anywhere else does not show. The commit scan and the board gate
+   refuse without writing a line. Say this once when you hand over the URL, so an honest blank is not
+   read as a broken panel. Everything else — the live agent graph, owned sessions, the permission bridge —
+   works the same in both editions.
+
+2. **Resolve a runtime — do not ask whether a name resolves.** `ensure-node.sh` sits one level ABOVE the panel
+   — beside the `server/` directory, not inside it. Both spellings, in full, so there is nothing to guess:
+
+   ```bash
+   bash .claude/studio/ensure-node.sh --explain               # full install
+   bash ${CLAUDE_PLUGIN_ROOT}/studio/ensure-node.sh --explain  # plugin edition (step 1 decided which)
+   ```
+
+   It prints the absolute path of a Node 18+ that actually runs, and exits 1 when there is none. Use that path;
+   do not assume it is `node`. It looks in places PATH does not reach — a version manager puts node on
+   PATH from a login shell only, so "nvm is installed" and "this shell can see node" are different
+   facts. And it runs what it finds rather than trusting the name: the Windows Store ships a stub that
+   satisfies `command -v`, prints nothing and exits 49.
+
+   **No `ensure-node.sh` beside the panel?** Then the panel predates the fetcher. Fall back to running
+   `node --version` and reading the output — 18+ required — and tell the user `/crew-update` brings the
+   fetcher along with everything else.
+
+3. **No runtime? Crewforth gets one — after the user says so.** Show them what it would do, then ask:
+
+   ```bash
+   bash <the same path as step 2> --plan       # url, size, checksum source, target directory
+   ```
+
+   It fetches the current Node LTS from nodejs.org into `~/.claude/studio-runtime`, verifies it against
+   the published SHA-256 and refuses to install on a mismatch. Nothing else on the machine is touched:
+   no admin rights, no package manager, no PATH or profile edit. Deleting that one directory undoes it.
+
+   Ask with `AskUserQuestion`, and offer the alternative honestly — some people would rather their own
+   package manager owned it (`winget install OpenJS.NodeJS.LTS`, `brew install node`, or their distro's).
+   On yes:
+
+   ```bash
+   bash <the same path as step 2> --install    # prints the node path on success
+   ```
+
+   Never run `--install --yes` on the user's behalf without that answer, and never install anything
+   system-wide.
+
+4. **Start it in the background**, from the project root, with the node from step 2 or 3:
+
+   ```bash
+   "$NODE" <panel> --open
+   ```
+
+   It prints a tokenised URL (`http://127.0.0.1:7777/?token=…`) and keeps running. **Report that URL**
+   whether or not a browser opened — over SSH or headless nothing can open, and a running server with no
+   way in is the worst outcome here. Tell the user it runs until they stop it, and how (Ctrl-C in that
+   shell, or kill the process). Do not hold it in a foreground tool call.
+
+5. **Port already in use.** Start it anyway and read what it says — the panel checks whether the holder is
+   another crewforth-studio first, and there is nothing for you to decide before it does. Two answers:
+
+   - `already running on port <n> (pid …) — reusing it`, followed by a tokenised URL and exit 0. That is a
+     panel someone else started, usually another session in this project. **Report that URL**; it is the same
+     panel, and the token in it is the running instance's own. Tell the user it belongs to whoever started it,
+     so closing this shell does not stop it.
+   - `held by something that is not a crewforth-studio panel` and exit 1. Then retry once with `--port <n+1>` and
+     report the new URL. If that port is taken too, stop and say both are taken rather than walking up the
+     range — something is listening that the user should look at.
+
+   The record that makes the first answer possible lives in `~/.claude/studio-runtime/instance-<port>.json`,
+   0600, and holds the token. A panel that was killed leaves one behind; the next start probes it, gets no
+   answer, and deletes it — so a stale file reports as the second answer, never as a URL that does not open.
+
+**Quoting the panel's output.** It prints two things that belong to this machine and nowhere else: the machine
+NAME, and a URL carrying a freshly generated token. Handing both to the user is the whole point — they are
+sitting at that machine. Putting either into anything that leaves it is not: a commit message, a PR, a
+CHANGELOG, an issue, a report to another session. The name is a §4.3 private term, and the token is a
+credential, loopback-scoped but still live for as long as that panel runs. So when you quote panel output
+anywhere but to the user, drop the machine line and replace the token with `…`. `.private-terms.txt` catches
+the name only if someone thought to add it; nothing catches the token.
+
+**What the panel's scope actually is.** It reads `~/.claude/projects` — every Claude Code session on this
+machine, not this project's. Starting it from a project root only decides which project it opens on. Say
+that when you hand over the URL, so nobody reports "it shows other projects" as a bug.
+
+Offline diagnostic, no browser and no tokens: `"$NODE" <panel> --selftest`.
+
+**In the plugin edition this command is namespaced** — `/crewforth:crew-studio`, not
+`/crew-studio`. Measured: the bare name does not resolve for a plugin command.

package/kit/skills/crew-update/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: crew-update
+description: Check for a newer version, update, report what changed, then prompt /clear to reload.
+metadata:
+  kind: command
+---
+# /crew-update
+Bring the Crewforth install up to the latest published version:
+1. **Detect install type.** If `.claude/VERSION` exists → a full install (steps below). If Crewforth runs as a
+   **plugin** (no `.claude/VERSION`), it updates through the plugin system: run
+   `claude plugin update crewforth@crewforth`, tell the user it applies when they restart Claude Code, and stop here.
+2. **Current version:** read `.claude/VERSION`.
+3. **Latest version:** `npm view crewforth version` (needs network). If it can't be reached,
+   say so and stop — don't guess.
+4. **Compare.** Already on the latest → report "up to date (vX)" and stop. Otherwise show **old → new**.
+5. **Before:** run `bash .claude/eval/update-guard.sh pre`. It records what is on disk (in `.claude/.state/`, nothing
+   else) and prints one of three verdicts:
+   - `clean` → nothing to report, go on.
+   - `UNCOMMITTED:` with the changed paths in `.claude/` and `CLAUDE.md` → show the user that list and **ask** —
+     with your question tool — whether to go ahead (the update rewrites Crewforth-owned files under `.claude/`), commit
+     or stash first, or stop. Continue only on their yes.
+   - `NOT IN GIT:` (a private install gitignores `.claude/` and `CLAUDE.md`, so edits there cannot be detected) →
+     pass its two lines to the user and go on; there is nothing to commit.
+6. **Update** — this rewrites Crewforth-owned files under `.claude/` (your `./CLAUDE.md` and project skills are
+   preserved). **Show this plan first, then run:** `npx --yes crewforth@latest update --here --yes`.
+   Two DIFFERENT `--yes` flags, both required for a non-interactive run: the one **before** the package name is
+   **npx's own** — it auto-confirms npx's `Ok to proceed?` install prompt, which reads the real TTY and IGNORES piped
+   input, so without it the command hangs before Crewforth even starts. The `--here --yes` **after** the package go to
+   the updater (`--here` = apply on the current branch, `--yes` = accept the smart defaults). Together they let it run
+   to completion instead of blocking on a prompt your shell can't answer.
+   If you'd rather review each handover decision yourself, tell the user to run `npx crewforth@latest update`
+   (no flags) in **their own terminal**, where both the npx and the interactive prompts work.
+7. **After:** run `bash .claude/eval/update-guard.sh post` and show the user its lists — added, changed, moved,
+   removed.
+8. **Verify:** run `/crew-doctor` (or `bash .claude/eval/doctor.sh`) so a bad/partial update surfaces immediately.
+   If the updater's or doctor's output contains a line starting with ⭐, pass it to the user verbatim as the LAST
+   line of your summary — it prints once per Crewforth version, and it is meant for the user, not for you.
+9. **Report** old → new + the headline changes. Take them from `.claude/.state/whats-new.md` — the updater writes
+   there the installed package's own CHANGELOG sections between the old and the new version. Do not fetch release
+   notes from the network. No file → say no release notes were included.
+10. **Reload (manual — a command can't do it itself):** the discipline in the running session is still the OLD one.
+   Tell the user to run **`/clear`** (or quit and relaunch Claude Code): a new session loads the updated
+   `.claude/DISCIPLINE.md`.

package/kit/skills/db-migration/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: db-migration
+description: |
+  Apply schema migrations safely: detect the tool, classify the change by risk, gate destructive ones behind
+  approval, back up in prod, preview-apply-verify, roll back on failure.
+  Use when a schema change is about to be applied to any environment.
+---
+
+# Database Migration
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "migration", "schema change", "update database", "add column", "create table", "alter table", "add a column to", "adding a column to", "drop a column", "rename the table", "change the column type", "backfill"
+
+A migration is very often a **one-way gate**: once applied, going back is expensive or impossible
+unless it was planned for. That is why the heart of the flow is not running a command, but **classifying
+the change by risk class before it passes through the gate** — let the safe one flow through, stop and
+get approval for the destructive one, and keep a rollback path ready in every case. The skill works with
+all common ORM/migration tools.
+
+> **Crewforth adaptation (local, .claude/):** Engine and tool come from `CLAUDE.md ## Stack` or repo detection
+> (`backend-architecture`). `crew-database-expert` applies it; **a destructive migration requires explicit approval (§4.5)**, commit/push with explicit approval (§4.4). Authorization/IDOR
+> impact → **crew-security-expert**; personal-data retention → **crew-privacy-agent**. §4 Prohibitions apply.
+
+## Checklist
+- [ ] Tool detected, pending migrations listed
+- [ ] Every change classified (additive / destructive / ambiguous)
+- [ ] Destructive/ambiguous changes approved by the user
+- [ ] Backup taken (mandatory in prod, verified)
+- [ ] Preview (dry-run) shown and approved
+- [ ] Applied, schema verified post-apply
+- [ ] Rollback path (tool or backup) ready
+
+---
+
+## 1. Detect the tool
+
+Determine the tool from the file trace; if none is found, fall back to **raw SQL mode** (below); if several are found, ask the user.
+
+| Trace | Tool |
+|---|---|
+| `prisma/schema.prisma` | Prisma |
+| `knexfile.{js,ts}` | Knex |
+| `.sequelizerc` / `config/config.json` + `models/` | Sequelize |
+| `data-source.ts` (typeorm) / `ormconfig.ts` | TypeORM |
+| `drizzle.config.ts` | Drizzle |
+| `alembic.ini` / `alembic/` | Alembic |
+| `manage.py` + `django` dependency | Django |
+| `db/migrate/` + `rails` in Gemfile | Rails |
+| `Microsoft.EntityFrameworkCore` in `*.csproj` + `Migrations/` | EF Core |
+
+---
+
+## 2. Classify the change — the heart of the flow
+
+Extract the SQL to be applied (the "Preview" column in the matrix below) and place it into one of three classes:
+
+| Class | Example operations | How it is handled |
+|---|---|---|
+| **Additive** (safe) | `CREATE TABLE`, nullable/defaulted `ADD COLUMN`, `CREATE INDEX`, non-destructive `ADD CONSTRAINT`, seed `INSERT` | Proceed in the normal flow |
+| **Destructive** (dangerous) | `DROP TABLE/COLUMN/INDEX/CONSTRAINT`, `ALTER COLUMN … TYPE`, `TRUNCATE`, `DELETE` without WHERE, `RENAME` (breaks references) | **Always the approval gate** (below) |
+| **Ambiguous** (human judgment) | `ALTER COLUMN`, `ADD COLUMN NOT NULL` without a default (blows up on a populated table), `UPDATE`, mixed migration | **Treat as destructive**, warn and ask |
+
+**Approval gate (destructive/ambiguous):** list the operations one by one, show the environment and the target, wait for explicit approval. Even if "run" was said in the general flow, this gate requires separate approval.
+```
+WARNING — this migration contains a destructive operation:
+  · DROP COLUMN "legacy_email" (table: users)
+  · ALTER COLUMN "status" TYPE integer (table: orders)
+CANNOT BE UNDONE without a backup.  Target: production (myapp_db @ db.example.com)
+Continue? (yes / no)
+```
+If rejected, stop immediately and propose a safer path (e.g. a new column + background copy instead of changing the type).
+
+---
+
+## 3. Backup (mandatory in prod)
+
+Back up before any migration; it cannot be skipped in prod, and can be skipped in dev with approval. Then verify
+**the backup was created and is not empty** — otherwise abort:
+```bash
+[ -s "$BACKUP_FILE" ] || { echo "ERROR: Backup empty/not created — migration aborted."; exit 1; }
+```
+Backup + restore + post-apply verify commands **per engine** (PostgreSQL · MySQL · SQLite):
+**`references/backup-restore.md`** — read the one for your database, not all three.
+
+---
+
+## 4. Tool × life-cycle matrix
+
+Once classification and backup are complete: **Preview → (approval) → Apply → Verify**.
+
+Per-tool commands for those four steps and for rollback — Prisma, Knex, Sequelize, TypeORM, Drizzle, Alembic, Django, Rails, EF Core: **`references/tool-matrix.md`**. Look up the one the project uses.
+
+**Rules:** **Always** show the preview before applying and get it approved (if the tool does not support a dry-run, treat the migration file itself as the preview). A destructive migration is not applied without passing the approval gate (§2). Show the full apply output; if there is an error, roll back.
+
+**Additional post-apply verification** — compare against the expected schema using your engine's inspect command (`references/backup-restore.md`).
+
+---
+
+## 5. Rollback
+
+First the tool-specific rollback (last column of the matrix); if that fails, restore from the backup (per-engine
+restore command in **`references/backup-restore.md`**); then re-verify. If neither works, warn the user with the full error detail.
+
+---
+
+## No tool — raw SQL mode
+
+If no tool is detected, manage numbered up/down files (every `up` has a `down`, each SQL inside `BEGIN`/`COMMIT`)
+with a `_migrations` tracking table. Full pattern + example + the apply loop: **`references/raw-sql.md`**.
+
+---
+
+## Invariant rules
+1. **Classify first** — additive/destructive/ambiguous; treat the ambiguous as destructive.
+2. **Destructive = human approval** — a separate gate even in an automated flow.
+3. **Prod backup mandatory** — no apply without a verified backup.
+4. **Preview on by default** — opting out requires an explicit request.
+5. **Always verify after applying.**
+6. **Rollback path always ready** — tool or backup.
+7. **Show the target** — DB name/host/environment, before applying.

package/kit/skills/db-migration/references/backup-restore.md

@@ -0,0 +1,33 @@
+# Backup & restore — per engine
+
+Take the backup **before** any migration (mandatory in prod; dev may skip with approval), then verify it is
+non-empty or abort. Rollback order: the tool-specific rollback first (matrix, last column) → if it fails, restore
+from this backup → re-verify. Read **only the section for your database**.
+
+## PostgreSQL
+```bash
+# backup — compressed full dump
+pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME -F c -f backup_$(date +%Y%m%d_%H%M%S).dump
+# restore (rollback)
+pg_restore -h $DB_HOST -U $DB_USER -d $DB_NAME --clean --if-exists $BACKUP_FILE
+# post-apply verify
+psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "\d $TABLE"
+```
+
+## MySQL
+```bash
+# backup
+mysqldump -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME > backup_$(date +%Y%m%d_%H%M%S).sql
+# restore (rollback)
+mysql -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME < $BACKUP_FILE
+# post-apply verify
+mysql -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME -e "DESCRIBE $TABLE;"
+```
+
+## SQLite
+```bash
+# backup
+sqlite3 $DB_PATH ".backup 'backup_$(date +%Y%m%d_%H%M%S).db'"
+# restore (rollback)
+cp $BACKUP_FILE $DB_PATH
+```

package/kit/skills/db-migration/references/raw-sql.md

@@ -0,0 +1,30 @@
+# No tool — raw SQL mode
+
+If no migration tool is detected, manage numbered up/down files; every `up` has a `down`, and every SQL runs
+inside `BEGIN`/`COMMIT`.
+```
+migrations/001_create_users.up.sql   +   001_create_users.down.sql
+```
+```sql
+-- 001_create_users.up.sql
+BEGIN;
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY,
+  email VARCHAR(255) NOT NULL UNIQUE,
+  created_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+COMMIT;
+-- 001_create_users.down.sql
+BEGIN;
+DROP TABLE IF EXISTS users;
+COMMIT;
+```
+Keep the applied ones in a tracking table; run only those with no record:
+```bash
+psql … -c "CREATE TABLE IF NOT EXISTS _migrations(id SERIAL PRIMARY KEY, name TEXT UNIQUE, applied_at TIMESTAMP DEFAULT NOW())"
+for f in migrations/*.up.sql; do
+  n=$(basename "$f" .up.sql)
+  [ "$(psql … -tAc "SELECT count(*) FROM _migrations WHERE name='$n'")" = 0 ] || continue
+  psql … -f "$f" && psql … -c "INSERT INTO _migrations(name) VALUES('$n')"
+done
+```