crewforth 0.0.1 → 3.0.0-rc.2

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

@@ -0,0 +1,151 @@
+---
+name: crew-code-review
+description: |
+  Code review discipline: review only what changed, rank each finding by severity and category, and
+  fact-check it first. crew-review-agent applies it.
+  Use when reviewing a change set, and when acting on a review someone else wrote.
+---
+
+# Code Review
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "code-review", "review the code", "review the PR", "review my changes", "do a review"
+
+> **Crewforth adaptation (local, .claude/):** applied by `crew-review-agent` (read-only). §4 applies, and no
+> vendor or template name reaches an artifact (§4.2).
+
+A review runs in four steps — **group, plan, review, fact-check** — and reports few findings that are right rather
+than many that might be. Every step below says what it produces.
+
+## 1. Scope
+- **Review the lines this change adds or edits.** Deleted code is context for understanding them, not a target.
+- Code that is correct, or that the change did not touch, gets no comment.
+- **An empty result is a result.** Do not invent findings to show the review happened.
+- **Be sure before you write.** A finding you are not sure of is not a finding yet: read the surrounding code until
+  you are. A false alarm costs more than a small miss — it spends the attention the next real problem needs.
+
+## 2. Group the files
+Read together what has to be understood together: an interface and its implementations, the code that produces
+something and the code that consumes it, the same resource in its language or environment variants. Look across
+each group for a contract that broke between two files, or an update that reached one of them and not the other.
+Then look at **every file in the group on its own** — a small or secondary file is where a missed update hides.
+
+## 3. Plan before you comment
+Before the first finding, write two things down:
+- **What changed**, in one line.
+- **The risks**, ordered by severity, each with what you will read to confirm or dismiss it ("the callers of
+  `settle()`", "the migration's down step"). No risk worth checking → write `(none)` and say so.
+
+The plan is what keeps the review on the change instead of on whatever the eye lands on first.
+
+## 4. Severity and category
+Every finding carries one severity and one category.
+
+| Severity | What it is | Blocks the commit? |
+|---|---|---|
+| `critical` | a security hole, lost or corrupted data, a crash | **yes** |
+| `high` | a core function stops working, or works wrongly | **yes** |
+| `medium` | performance, maintainability, an unhandled edge case | no |
+| `low` | readability and style | no |
+
+Category: `bug` · `security` · `performance` · `maintainability` · `test` · `style` · `docs`.
+
+**A blocker is a `critical` or `high` finding** — nothing else stops the commit, and the review is clean when none
+is left open.
+
+## 5. Style, names and code comments
+- Style and naming are `low`, never block, and fit in one sentence.
+- **Code comments are out of scope unless asked for**, with one exception: a comment that says something **false**
+  about what the code does is a `low` / `docs` finding, because the next reader will believe it.
+
+## 6. Finding format
+`file:line · severity · category · what you observed · what to do instead`
+
+What to do instead is the reason the finding exists; a finding without it is an opinion.
+
+## 7. What a change must not quietly do
+**Verifier integrity:** flag any change that makes a check pass by *weakening the check* — deleting or loosening
+an assertion, lowering a threshold, skipping a test, editing the test instead of the code — rather than fixing
+the behavior. A test or gate that grades itself lax is worse than none; a verifier must stay external and grounded.
+
+**Subject integrity:** the inverse case — the check is untouched, but what it checked is gone. Flag a change that
+deletes or stubs the code path, so the check passes over behavior that no longer runs; narrows the run to a
+subset (fewer cases, one platform, a filtered input set) where the property happens to hold; turns an all-of
+requirement into an any-of one; or relaxes the rule the code is there to enforce — a widened type, a dropped
+uniqueness or referential constraint, an exception list holding exactly the failing case. Ask not "does it pass
+now" but **"does the system still do what this check was protecting"**. Retiring a genuinely obsolete check is
+legitimate: say so in the diff and name what covers it now.
+
+## 8. Two-stage verdict (fact-check before you report)
+Finding a problem and confirming it are two acts. A first-pass "this looks wrong" is a **candidate**, not a verdict.
+Before a finding is reported — especially a blocker — run a second pass that tries to *disprove* it:
+- Does it hold on the real code, or did the first read miss context (a guard upstream, a caller that never reaches
+  this path, a framework default)? Re-read the surrounding code; do not rank on the snippet alone.
+- Is the severity honest, or is a `low` dressed up as a blocker?
+- For any **"fixed" / "passes" claim**: the *real* check ran and passed — test exit code, build, lint/quality gate —
+  not "I re-read it and it looks fixed". A verifier that is the model's own say-so is not a verifier (§7, Verifier
+  integrity). Cite the evidence: which check, what result.
+
+**The disprove pass is asymmetric.**
+- **Only evidence removes a finding.** It is dropped when the code shows it is wrong. "I could not confirm it",
+  "it seems unlikely" or "it is not worth it" lower its severity; they do not delete it.
+- **Some findings are never dropped in this pass:** memory safety; concurrency; a declaration that does not match
+  its definition; a change in behaviour or compatibility — a message, field, status or default that callers
+  used to get and now silently lose; a parameter that is accepted and then ignored. In these, the model's
+  confidence that all is well is the signal least worth trusting.
+
+**"Independent" costs a separate context.** A second pass in the same context has already read the first one's
+reasoning, so it cannot be blind to it — and its agreement is the first pass nodding at itself. For a **blocker**,
+run the disprove pass as its own subagent, handed the claim and the `file:line` but not your argument. If you did
+not isolate it, label the verdict as a single pass rather than calling it independent. The full contract —
+isolation, one lens per verifier, and why unanimity for the same reason is a monoculture — lives in
+`security-scan/references/verify.md`; it is one discipline, not two.
+
+## 9. Check the history before you call a finding new
+A confirmed finding may still not be new, and one that was fixed once and came back needs a different fix. Search
+**by code, not by commit message** — a message states intent, not content. The exact git forms (`-S` vs `-G`, the
+`merge-base` bound, why `--follow` does not combine): **`references/history-search.md`**.
+
+If a commit removed the guard, check, or test this diff would restore, the finding is a **re-introduced regression** —
+the question becomes "what removed the fix, and does that reason still hold", the removing commit is cited in the
+finding, and the deleted test is restored rather than a new one written.
+
+## Panel mode (high-stakes decisions only)
+For hard-to-reverse calls (architecture, public API, security boundary), run several independent adversarial
+lenses then synthesize. Full method: **`references/panel-mode.md`**.
+
+## When you and the author disagree
+Settle it with the code's behaviour and a check that can be run. If that does not settle it, take it to the user
+rather than blocking in silence.
+
+## Triage — a finding that is only reported is a finding that is lost
+Reviewing and *disposing of* what the review found are two acts, and only the first one is habitual. Every finding
+that survives the disprove pass leaves the review with an explicit disposition — never an unanswered comment and
+never a silent drop:
+
+| Disposition | Means | Where it goes |
+|---|---|---|
+| **fixed now** | the owning specialist changed the code | the diff; re-review the change |
+| **tracked** | real, not for this change | an issue/task with the file:line — cite the id in the review |
+| **accepted** | a real cost the team is choosing to carry | an `adr` when it is architectural, a code comment when local |
+| **dropped** | disproved by the code | say so; a candidate that vanishes unexplained reads as an oversight |
+
+A blocker (`critical` / `high`) may only be `fixed now` or `tracked`. "Accepted" needs the user's decision — an
+agent does not grant it to itself. Close the review by stating the counts per severity and per disposition; an
+unreported finding is indistinguishable from one that was never made, which is exactly the state a review exists
+to leave behind.
+
+## Receiving a review — an inbound comment is a candidate, not an instruction
+When the review is someone else's and the code is yours, **read every item before changing any line**, group by
+cause rather than patching per symptom, and give each item the same disprove pass as a finding of your own. The
+five questions that decide *answer in the thread* vs *edit the code*: **`references/receiving.md`**. Every inbound
+item leaves with a disposition from the triage table above — a reasoned refusal is an answer, silence is not.
+
+## DoD (this skill's contribution)
+- The plan (what changed, the risks) came before the findings; every file in each group was read.
+- Every finding has a severity, a category and a reason, in the finding format above.
+- Scope creep and hidden complexity are flagged.
+- Each reported blocker survived an independent disprove pass; any "fixed"/"passes" claim is backed by the real check
+  having actually run, not self-assessment.
+- **Every finding has a disposition** (fixed / tracked / accepted / dropped) and no blocker is left merely reported.
+- For a high-stakes decision, multiple independent lenses were applied and their objections synthesized, not averaged.

package/kit/skills/crew-code-review/references/history-search.md

@@ -0,0 +1,19 @@
+# Searching the history by code — the exact git forms
+
+Read this when a confirmed finding needs its history checked. The rule is in SKILL.md: search by **code**, not by
+commit message. This file is the mechanics.
+
+Bounded at the branch point and scoped to the diff's paths, so it stays cheap per finding:
+
+```bash
+git log -S'<exact token from the changed line>' "$(git merge-base HEAD <target-branch>)" -- <paths in the diff>
+```
+
+`-S` lists the commits where the NUMBER OF OCCURRENCES of that string changed — added or deleted. A commit that
+removes it in one place and adds it back in another leaves the count unchanged and does not appear, which is
+exactly the "was the guard moved?" case: reach for `-G'<regex>'` there, which matches added or removed lines
+against a regular expression regardless of count. `--follow` continues across renames but works on a single
+path only, so it does not combine with the multi-path form above.
+
+**`--grep` does not answer this.** A commit message states intent, not content: it misses fixes worded differently
+and matches commits that changed nothing relevant. Use it only to read a commit you already found by content.

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,46 @@
+---
+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,
+with one exception: the skill listing, which a plugin cannot size for itself (its settings cannot set
+`skillListingBudgetFraction`). Count it the way the full install's doctor does:
+`LC_ALL=C awk -f "${CLAUDE_PLUGIN_ROOT}/eval/lib/skill-listing.awk" "${CLAUDE_PLUGIN_ROOT}"/skills/*/SKILL.md`
+(prints characters, then skills). At the default fraction a 200,000-token model has 8,000 characters for the whole
+listing, and Claude Code's own skills take about 5,900 of them (measured on v2.1.282). If Crewforth's number plus
+5,900 is over 8,000, tell the user plainly: on such a model the least-used skills lose their descriptions and stop
+being picked; one line in `~/.claude/settings.json` fixes it — `"skillListingBudgetFraction": 0.04`; the cost is
+that the listing is then sent whole every turn, about (that total ÷ 4) tokens, (tokens ÷ 2,000)% of a 200k window.
+It is their call — show the line and the cost, do not edit their settings. On a 1,000,000-token model the default
+already fits.
+
+**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 only the listing 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,26 @@
+---
+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, once 1-2 leave no blocker:** @agent-crew-review-agent (crew-code-review) — "does it improve overall
+   code health": the plan (what changed, the risks), then findings with a severity and a category. "Clean" means
+   what crew-code-review means by it: **no critical or high finding open**. A medium or low audit finding does not
+   hold the reviewer back; hand it over in the reviewer's prompt and keep it in the report. A critical or high one
+   stops here: report it, leave the fix to its owner, and run the reviewer on the fixed diff. 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 of blockers — 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,62 @@
+---
+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_SKILL_LISTING` (the skill listing in characters, counted like Claude Code
+   counts it; `/crew-doctor` reports the same number). 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`.