crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/automode-policy/scripts/apply.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Install Crewforth's auto-mode classifier policy into USER settings — the one part of Crewforth that lives
+# outside the project, because the classifier deliberately ignores `autoMode` in .claude/settings.json
+# (a repo could otherwise ship its own allow rules). Writing outside the project is exactly the kind of
+# action §4.4 says needs the user's word, so this script asks, backs up, and verifies — in that order.
+#
+# Usage:
+#   apply.sh              propose the change, show the diff, ask, install, verify
+#   apply.sh --yes        same without the prompt (for a scripted setup the user drives)
+#   apply.sh --strict     also set autoMode.classifyAllShell — every shell command reaches the classifier
+#   apply.sh --print      print the policy fragment and exit (paste it yourself; no writes, no tooling)
+set -u
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+POLICY="$HERE/../references/policy.json"
+CHECK="$HERE/check.sh"
+TARGET="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"
+YES=0; STRICT=0
+for a in "$@"; do case "$a" in
+  --yes) YES=1 ;; --strict) STRICT=1 ;;
+  --print) cat "$POLICY"; exit 0 ;;
+  *) echo "apply.sh: unknown argument '$a'"; exit 64 ;;
+esac; done
+
+[ -f "$POLICY" ] || { echo "❌ policy.json not found next to this script"; exit 1; }
+
+# A JSON merge into the user's own settings file is not a job for sed. It goes through Crewforth's one JSON reader
+# (eval/lib/settings-json.awk, the same file adopt.sh merges with) — the same code on every OS. This used to pick
+# jq, then python3, and on a stock Windows box with neither it printed the fragment and stopped, so the one
+# platform with no JSON tool could not install the policy at all. The reader sits three levels up in both
+# editions: .claude/skills/<s>/scripts -> .claude/eval/lib, and <plugin>/skills/<s>/scripts -> <plugin>/eval/lib.
+SJ="$HERE/../../../eval/lib/settings-json.awk"
+if [ ! -f "$SJ" ]; then
+  echo "⚠️  Crewforth's JSON reader is missing ($SJ) — not merging your settings file by hand."
+  echo "   Add this block to $TARGET yourself (keep the \"\$defaults\" entries verbatim):"
+  echo; cat "$POLICY"; exit 3
+fi
+
+mkdir -p "$(dirname "$TARGET")"
+[ -f "$TARGET" ] || printf '{}\n' > "$TARGET"
+
+TMP="$TARGET.crew-new"; BAK="$TARGET.crew-bak-$(date +%Y%m%d-%H%M%S)"
+# autoMode takes every member of the policy's autoMode (the policy wins), the user's other members and every other
+# key untouched. rc 10 = the target is not a JSON object: nothing is written.
+if [ "$STRICT" = 1 ]; then set -- -v setk=classifyAllShell -v setv=true; else set --; fi
+awk -v op=overlay -v key=autoMode "$@" -f "$SJ" "$TARGET" "$POLICY" > "$TMP" && [ -s "$TMP" ] \
+  || { echo "❌ merge failed (invalid JSON in $TARGET?)"; rm -f "$TMP"; exit 1; }
+
+# Verify the CANDIDATE before it is anyone's real configuration. `claude --settings <file>` runs the
+# classifier config resolution against the file, so a policy that would silently drop the 66 built-in
+# soft blocks is caught here — while the only file on disk is still a temp file.
+echo "== verifying the candidate (nothing installed yet) =="
+bash "$CHECK" --settings "$TMP"; RC=$?
+if [ "$RC" != 0 ]; then
+  echo "❌ candidate did not verify (rc=$RC) — nothing was written."
+  rm -f "$TMP"; exit "$RC"
+fi
+
+echo
+echo "== what changes in $TARGET =="
+if command -v diff >/dev/null 2>&1; then diff -u "$TARGET" "$TMP" | sed -n '1,60p'; else echo "(no diff tool; new file written to $TMP)"; fi
+echo
+if [ "$YES" != 1 ]; then
+  # No terminal means no one can consent. Asking anyway is worse than useless: with a tty present but nobody
+  # reading it — a CI runner, a background job, a test harness — `read </dev/tty` blocks forever. Measured:
+  # this hung Crewforth's own smoke test. No consent possible -> abort, and say how to do it deliberately.
+  if [ ! -t 0 ] && [ ! -t 1 ]; then
+    echo "not an interactive session — nothing written. Re-run with --yes if this is a setup you are driving."
+    rm -f "$TMP"; exit 0
+  fi
+  printf "Install this policy into your USER settings? [y/N] "
+  read -r ans </dev/tty 2>/dev/null || ans=""
+  case "$ans" in y|Y|yes|YES) : ;; *) echo "aborted — nothing written."; rm -f "$TMP"; exit 0 ;; esac
+fi
+
+cp "$TARGET" "$BAK" && mv "$TMP" "$TARGET" || { echo "❌ could not write $TARGET"; exit 1; }
+echo "✅ installed. backup: $BAK"
+echo "== verifying what the classifier now actually uses =="
+bash "$CHECK"; RC=$?
+if [ "$RC" != 0 ]; then
+  echo "❌ post-install verification failed (rc=$RC) — restoring the backup."
+  cp "$BAK" "$TARGET"; exit "$RC"
+fi
+echo "   Undo any time:  cp \"$BAK\" \"$TARGET\""

package/kit/skills/automode-policy/scripts/check.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Report what the auto-mode classifier is CONFIGURED with — and be exact about what that does and does not prove.
+#
+# MEASURED, 2026-08-24, Claude Code 2.1.238, interactive session, permissionMode=auto, this policy installed in
+# USER settings and shown as present by `claude auto-mode config`:
+#   `git reset --hard && git clean -fd` ran with no prompt and no block, destroying uncommitted work — the exact
+#   action Crewforth's hard_deny rule names verbatim and calls unconditional.
+#   A control run with NO policy and NO explicit user intent behaved identically.
+#   Two headless probes agreed, including an absolute "never write any file" rule, and a protected-path write
+#   (.git/config) that the docs say auto mode routes to the classifier went through untouched.
+# Reading: the classifier did not gate this class of action at all, with or without custom rules. So this script
+# reports CONFIGURATION, never enforcement. Crewforth's enforcement lives in its PreToolUse hooks and git hooks,
+# which are measured firing in smoke-test; nothing here replaces them.
+#
+# Auto mode is the default permission mode on Pro/Max/Team since 2026-08-14: a classifier, not the user,
+# answers most permission prompts. It reads its rules from `autoMode` in USER or MANAGED settings only
+# (never from .claude/settings.json — a repo could otherwise ship its own allow rules), so this policy is
+# the one part of Crewforth that lives outside the project. That is why it is installed explicitly and
+# verified here rather than assumed.
+#
+# The failure this guards against is silent: setting an autoMode array WITHOUT the literal "$defaults"
+# replaces the built-in list for that section — 66 soft-block rules and the single built-in hard block
+# disappear with no error, and the session looks healthy. So this script does not read the policy file;
+# it reads what the classifier ACTUALLY uses (`claude auto-mode config`) and checks the built-ins are
+# still there. A policy file that parses is not a policy that applies.
+#
+# Side effect, measured — this script writes nothing itself, but `claude auto-mode config` does: reading the
+# effective config makes Claude Code rewrite its own settings.json (reformatted, values normalised such as
+# `opus` -> `opus[1m]`, a backups/ directory created). That is Claude Code maintaining its own file, and it
+# keeps a backup, but "verifying costs nothing" would be a false claim.
+#
+# What it still catches, and why it is worth running: setting an autoMode array without the literal "$defaults"
+# silently replaces the built-in list for that section (measured: soft_deny 66 -> 2, no error, no warning). That
+# footgun is real whatever the enforcement story is, and nothing else in the toolchain reports it.
+#
+# Usage:  check.sh [--settings <file>]     # --settings inspects a CANDIDATE policy without installing it
+# Exit:   0 config as expected · 2 built-ins DROPPED · 3 kit rules absent/partial · 4 cannot read the config
+set -u
+
+SETTINGS=""
+[ "${1:-}" = "--settings" ] && { SETTINGS="${2:-}"; [ -z "$SETTINGS" ] && { echo "check.sh: --settings needs a file"; exit 4; }; }
+
+command -v claude >/dev/null 2>&1 || { echo "  ⚠️  claude CLI not on PATH — auto-mode policy cannot be verified"; exit 4; }
+
+if [ -n "$SETTINGS" ]; then CFG="$(claude --settings "$SETTINGS" auto-mode config 2>/dev/null)"
+else                        CFG="$(claude auto-mode config 2>/dev/null)"; fi
+
+# `auto-mode` is v2.1.19x+; an older CLI prints usage/error instead of the four rule lists.
+case "$CFG" in *'"soft_deny"'*) : ;; *)
+  echo "  ⚠️  'claude auto-mode config' did not return a rule set — CLI too old, or auto mode unavailable on this account"
+  exit 4 ;;
+esac
+
+# Built-ins, checked PER SECTION and anchored to the rule's label.
+#
+# A whole-blob substring search is NOT enough and this was measured, not assumed: "Data Exfiltration" and
+# "Auto-Mode Bypass" also occur inside the prose of `allow` rules, so a config with those built-ins dropped
+# still contains both strings somewhere. That check reports a false PASS — the worst kind for a policy gate.
+# `claude auto-mode config` prints one rule per line inside `"<section>": [ ... ]`, and every rule begins
+# with its label, so slice the section first and anchor the match to the start of the string.
+section(){ printf '%s\n' "$CFG" | awk -v s="$1" '
+  $0 ~ "^[[:space:]]*\""s"\"[[:space:]]*:[[:space:]]*\\[" { inb=1; next }
+  inb && /^[[:space:]]*\]/ { inb=0 }
+  inb { print }'; }
+
+has_rule(){ printf '%s\n' "$2" | grep -q "^[[:space:]]*\"$1"; }
+
+HD="$(section hard_deny)"; SD="$(section soft_deny)"
+MISSING=""
+has_rule 'Data Exfiltration' "$HD" || MISSING="$MISSING hard_deny/Data-Exfiltration"
+has_rule 'Git Destructive'   "$SD" || MISSING="$MISSING soft_deny/Git-Destructive"
+has_rule 'Auto-Mode Bypass'  "$SD" || MISSING="$MISSING soft_deny/Auto-Mode-Bypass"
+
+# Each kit rule counts under its 3.0 name or its pre-3.0 one ("CSK …"): a config applied by 2.x keeps passing
+# until the user re-applies, which overlays autoMode and so replaces the old names rather than adding beside them.
+KITR=0
+kit_rule(){ has_rule "Crewforth $1" "$2" || has_rule "CSK $1" "$2"; }
+kit_rule 'Uncommitted Work Destruction' "$HD" && KITR=$((KITR+1))
+kit_rule 'Gate Tampering'               "$SD" && KITR=$((KITR+1))
+kit_rule 'Internal Docs Publication'    "$SD" && KITR=$((KITR+1))
+
+if [ -n "$MISSING" ]; then
+  echo "  ❌ classifier built-ins DROPPED:$MISSING"
+  echo "     ↳ an autoMode array was set without the literal \"\$defaults\" — restore it in ~/.claude/settings.json"
+  echo "     ↳ inspect with: claude auto-mode config    · built-ins: claude auto-mode defaults"
+  exit 2
+fi
+
+if [ "$KITR" -eq 0 ]; then
+  echo "  ·  Crewforth auto-mode rules not in the classifier config (built-ins only) — not a gate either way"
+  echo "     ↳ optional: bash .claude/skills/automode-policy/scripts/apply.sh"
+  exit 3
+fi
+
+if [ "$KITR" -lt 3 ]; then
+  echo "  ·  Crewforth auto-mode rules PARTIAL ($KITR/3 present) — built-ins intact"
+  echo "     ↳ re-apply: bash .claude/skills/automode-policy/scripts/apply.sh"
+  exit 3
+fi
+
+echo "  ✅ classifier config: built-ins intact, 3/3 Crewforth rules present (CONFIGURED, not proven to enforce)"
+exit 0

package/kit/skills/backend-architecture/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: backend-architecture
+description: |
+  Decide, record and apply the backend stack and architecture pattern.
+  Use when backend work starts with no recorded stack, or a framework/DB/pattern must be chosen.
+---
+
+# Backend Architecture (stack resolution + pattern)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "tech stack", "which framework", "choose a database", "backend pattern", "project structure", "new api", "new handler", "write a command", "add a query", "validator", "which stack should", "set up the project structure", "language or framework", "layered or", "vertical slice", "hexagonal", "clean architecture"
+
+The "how" behind `crew-backend-expert`, and the stack step `crew-planner` and `crew-database-expert` rely on.
+**Model discipline, not a gate:** no hook checks that the stack was resolved before code was written.
+
+## When
+- A backend task starts and `CLAUDE.md ## Stack` is empty or silent on the part the task needs.
+- Someone asks which language, framework, database or pattern to use.
+- A new service, API, module or handler is being shaped and the pattern is not obvious from neighbouring code.
+
+## 1 · Stack resolution — in this order, stop at the first answer
+1. **The request says it.** "Add a Go service…" is an answer. Use it; record it if the section was empty.
+2. **`CLAUDE.md ## Stack` says it.** The project's own section (below Crewforth's `@.claude/DISCIPLINE.md` import),
+   not `DISCIPLINE.md`. A filled section is a decision: follow it.
+3. **The repo says it.** Look for manifests at the root and one level down (`backend/`, `server/`, `src/`, `apps/*`):
+
+   | Manifest | Runtime |
+   |:--|:--|
+   | `package.json` | Node (TypeScript if `tsconfig.json`) |
+   | `go.mod` | Go |
+   | `pyproject.toml` / `requirements.txt` | Python |
+   | `*.csproj` / `*.sln` | .NET |
+   | `pom.xml` / `build.gradle*` | JVM (Java/Kotlin) |
+   | `Cargo.toml` | Rust |
+   | `composer.json` | PHP |
+   | `Gemfile` | Ruby |
+
+   The framework and database usually follow from the same manifest's dependencies and from config files
+   (`docker-compose*.yml`, connection-string env names, migration folders). Two backends in one repo is a
+   monorepo, not an ambiguity: record each with its path.
+4. **Still open (a greenfield repo) → ask, once.** Use `AskUserQuestion` with **at most four** questions, only for
+   what is still unknown: runtime/language · web framework · database · architecture pattern. **Every question has
+   exactly one option whose label ends with `(Recommended)`** (its description gives the one-line reason) **and
+   exactly one option labelled `Decide for me`, verbatim** — the user's way to hand the choice back to you.
+   No `AskUserQuestion` in this session (headless, or the tool is off)? Write the same questions as text, with the
+   same two labels on every question, and stop there.
+
+**Record it.** Write the answer into the `## Stack` section of the project's `CLAUDE.md` (Runtime · Web framework ·
+Database + migration tool · Architecture pattern), then record the choice with the `adr` skill (and `board.sh decide`
+when the team board is in use). If "Decide for me" was picked, the ADR says so: *chosen by the agent at the user's
+request*, with the reason for each pick.
+
+**Never ask twice.** A recorded stack is followed, not re-litigated. It changes only when the user explicitly asks;
+then update the section and supersede the ADR. Headless / non-interactive and nobody to ask → stop and report the
+open question; do not guess a stack and start writing code.
+
+## 2 · Pattern menu — default to the simplest one that fits (YAGNI)
+| Pattern | Fits | Too much when |
+|:--|:--|:--|
+| **Layered** (controller → service → repository) | CRUD-heavy services, small teams, most first versions | rules sprawl across services and every change touches every layer |
+| **Clean / hexagonal** (domain core, ports, adapters) | rich domain rules, several delivery channels or swappable infrastructure | the "domain" is mostly forms over tables |
+| **Vertical slice** (one folder per feature, request → handler → response) | many independent features, teams owning features end to end | features share most of their logic |
+| **CQRS** (separate command and query paths) | reads and writes that differ sharply in shape, load or consistency | reads and writes look the same — it doubles the code for no gain |
+
+Existing code wins over this table: a repo already on a pattern keeps it, even where the table would pick another.
+A change of pattern is an architecture decision → design summary + ADR, never a side effect of a feature.
+
+## 3 · Rules that hold in any language
+- **One error contract.** Every endpoint returns failures in the same envelope (e.g. RFC 9457 problem details or the
+  project's own shape) with the correct status: 400 invalid input · 401 unauthenticated · 403 forbidden · 404 not
+  found (also for another tenant's resource — do not leak existence) · 409 conflict · 422 rule violated · 5xx only for
+  the server's own fault. No raw exceptions or stack traces in responses.
+- **Validate at the edge.** Parse and validate input where it enters (request DTO + schema/validator), so the core
+  only sees valid values. Business rules stay out of controllers/routes.
+- **Cross-cutting concerns in one place** — logging, auth, transactions, caching, rate limits live in
+  middleware / decorators / pipeline behaviours, not copied into each handler.
+- **Dependencies are injected**, not constructed inside handlers; the composition root is the only place that knows
+  concrete types.
+- **Transaction boundaries are explicit**: one use case, one unit of work. No remote call inside an open DB transaction.
+- **Idempotency** for anything a client may retry (payments, webhooks, create-with-client-id): an idempotency key or a
+  natural unique constraint.
+- **Secrets and personal data are never logged** — see `observability` for what to log and `privacy-compliance` for
+  personal data.
+
+## 4 · Ecosystem map — common choices, not requirements
+| Runtime | Web | Validation | Data / migrations |
+|:--|:--|:--|:--|
+| .NET | ASP.NET Core (MediatR optional) | FluentValidation | EF Core |
+| Node | NestJS / Fastify | zod | Prisma / Drizzle |
+| Go | chi / echo | go-playground/validator | sqlc / GORM |
+| Python | FastAPI | pydantic | SQLAlchemy / Alembic |
+| JVM | Spring Boot | Bean Validation | JPA / Flyway |
+
+The project's recorded choices beat this table. Adding a dependency that is not already in the repo → `dependency-audit`.
+
+## 5 · Project override
+A pattern skill the project ships under `.claude/skills/` wins over sections 2-4 — for example a `cqrs-aop-module`
+kept from an older install, or one the team wrote (format: `.claude/AGENT_TEMPLATE.md`). Section 1 still applies:
+the stack is resolved and recorded the same way.
+
+## Not here — the single source is elsewhere
+Schema and migrations → `db-migration` · tests → `testing` · review → `crew-code-review` · contracts and
+versioning → `api-design` · logs/traces → `observability`.

package/kit/skills/brainstorm/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: brainstorm
+description: |
+  Divergent discovery BEFORE planning: turn a fuzzy ask into 2–4 scoped options + named unknowns, pick a
+  direction, hand to spec-planning. Bounded; converges to explicit choices, never guesses.
+---
+
+# Brainstorm — diverge before you converge
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "brainstorm", "explore options", "not sure what we want", "help me scope", "ideate"
+
+## When
+The ask is **under-defined**: the goal, the users, or the shape of the solution aren't clear yet, so jumping
+straight to `spec-planning` would just plan the wrong thing. This is the front-end of planning, not a
+replacement — brainstorm *diverges* (widens the option space), spec-planning *converges* (breaks the chosen
+option into tasks). If scope is already clear, skip this and go straight to [[spec-planning]].
+
+## The loop
+1. **Frame the real problem** — restate the request as the underlying need in one sentence ("the user wants
+   X so that Y"). Separate the stated solution from the goal; often the solution is negotiable, the goal isn't.
+2. **Diverge — generate distinct directions.** Produce **2–4 genuinely different** approaches, not variations
+   of one. For each: the core idea, who it serves, the main trade-off. Include a deliberately cheap/minimal
+   option (fight gold-plating early).
+3. **Surface the unknowns** — list assumptions and open questions that would change the answer. Mark which are
+   **blocking** (must resolve before planning) vs. deferrable.
+4. **Converge — ask, don't guess.** Present the directions as **explicit numbered options** and let the user
+   choose (CLAUDE.md discipline: a decision point = multiple choice, never a prose either/or). Record the
+   chosen direction + the rejected ones with the one-line reason they lost.
+5. **Hand off.** The chosen direction + resolved constraints flow into `spec-planning`; a lasting
+   architectural choice made here is recorded with [[adr]].
+
+## Guardrails
+- **Bounded, not open-ended.** Divergence has a stop: 2–4 options, then converge. Endless ideation with no
+  decision is the failure mode, not thoroughness.
+- **No premature convergence either.** Don't collapse to the first idea to look decisive — the point is that
+  the option space was actually explored before a direction was picked.
+- **Evidence over invention.** Read the existing code/data and state assumptions explicitly; a plausible guess
+  presented as fact is worse than a named unknown.
+- **Token discipline** ([[token-budget]]): the options + the decision are a short summary to the main thread;
+  push a long exploration to `docs/DISCOVERY.md` and return the option headings + the choice.
+
+## DoD (this skill's contribution)
+- The real goal is stated separately from the requested solution.
+- 2–4 distinct directions exist, each with its trade-off, including a minimal option.
+- Blocking unknowns are named and were asked as explicit options — nothing ambiguous was filled by guessing.
+- A direction is chosen and ready to enter [[spec-planning]] (rejected options logged with their reason).

package/kit/skills/ci-pipeline/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ci-pipeline
+description: |
+  CI pipeline discipline: lint→build→test→quality→security, fail-fast, deterministic build, secret handling, PR gates.
+---
+
+# CI Pipeline
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "ci", "pipeline", "github actions", "jenkins", "build pipeline", "pr gate", "pr check", "build fail", "build broke", "ci is failing", "workflow"
+
+## Stages (fail-fast — stop if it breaks early)
+1. **Lint / format** — style and static analysis
+2. **Build** — 0 warnings / 0 errors
+3. **Test** — unit + integration, coverage collected
+4. **Quality** — `sonarqube-check` quality gate
+5. **Security** — `dependency-audit` + `security-scan` (where applicable)
+6. **Artifact / packaging** — (deployment is separate, `deploy`)
+
+## Principles
+- **Deterministic:** dependencies pinned, cache keyed correctly; no "it worked on my machine".
+- **Secret management:** CI secret store; NO plaintext secrets in the repo/logs (overlaps with trace scan).
+- **PR gate:** quality gate + tests must pass; a red build is not merged.
+- **Branch protection:** direct push to main is disabled; PR + review required.
+
+## When a stage fails
+1. **Fetch the failing job's log first** — `gh run view --log-failed`, `glab ci trace`, `jenkins-cli console <job>`,
+   whichever this project's host provides — and quote the failing lines: a status icon names which job broke, never why.
+   Log unreachable (no access, retention expired, the job never started) → report exactly that; never infer the cause.
+2. **Reproduce with the exact command the pipeline runs**, copied out of the CI config — same flags, same env, same
+   versions. Green locally is not a pass: the environment difference is now the defect, so take it to `systematic-debugging`.
+3. **A re-run is not a fix.** Re-running until it passes hides the cause; re-run only to establish that a failure is
+   intermittent — and an intermittent failure in this repo's own suite is a bug (`testing`), not a retry.
+4. **Say which failures aren't yours.** A required check owned by another change, or an external service that was
+   down, is reported out of scope with the job named — silence about it reads as a clean run.
+
+## DoD
+- All stages green; PR gates enforced; no secret leakage; build reproducible.

package/kit/skills/commit-message/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: commit-message
+description: |
+  Conventional Commits: reads the staged diff and proposes `type(scope): summary`, with body/footer when needed.
+  One logical change = one commit. crew-commit-agent applies it.
+---
+
+# Commit Message (Conventional Commits v1.0.0)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "commit message", "make a commit", "conventional commit", "write a commit", "git commit"
+
+Format: `type(scope): summary` + (optional blank line + body) + (optional footer).
+
+## The project decides the format and the language — read that FIRST
+Conventional Commits below is the **default**, not a law. Before writing anything, read `./CLAUDE.md` for a
+`## Conventions` section (`Commit language:` / `Commit format:`). A declared format REPLACES the shape below —
+ticket-prefixed subjects, smart-commit trailers (`#comment`, `#time`), gitmoji, whatever the team runs on. A
+declared language replaces "the project's established language" guess. Nothing declared → the defaults here.
+
+**Whatever the request hands you verbatim — a ticket id, a `#time 1d`, a required prefix — goes into the
+message EXACTLY as given.** Rewriting a literal someone typed is the worst failure this skill has: it looks
+correct and books the wrong number. If a literal contradicts the format, say so and ask; never silently adjust
+it. Same rule for the rest of the message: everything else is yours to word, the literals are not.
+
+
+## Type (required)
+- `feat` — new feature             · `fix` — bug fix
+- `docs` — docs only               · `refactor` — restructure with no behavior change
+- `perf` — performance             · `test` — add/fix tests
+- `build` — build/dependency       · `ci` — CI configuration
+- `chore` — maintenance/automated  · `revert` — revert a previous commit
+- `style` — formatting (no logic)
+
+### Which type? (deciding when ambiguous)
+- A new capability for the user? → `feat`. Fixing an existing wrong behavior? → `fix`.
+- Behavior the same, only the structure changed? → `refactor` (if behavior changed it's `feat`/`fix`, not refactor).
+- Touched only tests/docs/formatting? → `test`/`docs`/`style` (don't touch code logic).
+
+## Scope (optional, preferred)
+The affected area/module: `auth`, `api`, `backend`, `db`, `frontend`, `session`, `agent`, etc.
+One word, consistent with the project's module name.
+
+## Summary line
+- **In the project's established language** (English by default for open source), imperative/summary mood, start lowercase, NO period at the end, ≤ ~72 characters.
+- Say **what it does**, not how; avoid vague words ("fix", "update", "wip").
+  ✅ `feat(auth): one-time code TTL + brute-force limit`
+  ❌ `fix: bug` · ❌ `update` · ❌ `changes`
+
+## Body (optional — recommended for meaningful changes)
+After a blank line: the **WHY** (motivation) + notable consequences/tradeoffs. Wrap at ~72 characters.
+Leave context for the future reader who opens git-blame — the diff already shows the "what"; you write the "why".
+
+## Footer (optional)
+- `BREAKING CHANGE: <description>` — a backward-incompatible breaking change (triggers SemVer MAJOR, `release` skill).
+- `Refs: #<issue>` / `Closes #<issue>`.
+
+## Atomic commit — splitting a mixed diff
+If a diff contains several logical changes, **split it**; don't cram it into one commit:
+```bash
+git add -p            # pick hunk by hunk; stage related changes separately
+git add <specific/file>
+```
+Each commit focused on a single topic; "feat + fix + refactor" doesn't belong in one commit.
+
+## Good / bad
+
+Worked good-vs-bad commit examples: **`references/examples.md`**.
+
+## Rules
+- **Atomic:** one logical change = one commit.
+- **No commit without DoD:** don't propose a message until `/simplify` + tests green + (if SonarQube is used) `sonarqube-check` 0/0/0/0 pass.
+- If there is no staged diff, warn; ask the user about the `git add` scope with explicit options.
+- Don't run `git commit` silently; propose the message, **wait for approval**.
+
+## Prohibitions (absolute — see CLAUDE.md §4)
+- **No AI trace:** no co-author trailer, auto-generation footer, or robot emoji in the subject/body;
+  words naming an AI assistant, model, or coding tool, and the `.claude` name, do not appear in the message.
+- **No vendor name:** the third-party template/skeleton name and any "vendor copy / cleanup" disclosure are not written in the message (§4.2).
+- **Human, natural language:** the message is natural, technical, and in the project's established language (English by default for open source).
+- **Approval:** commit only when the user says "commit"; "done" is not approval (§4.4).
+- **Destructive:** amend / reset / force / `--no-verify` only on an explicit request; the hook is not skipped (§4.5).

package/kit/skills/commit-message/references/examples.md

@@ -0,0 +1,8 @@
+# Good / bad commit examples
+
+| ✅ Good | ❌ Bad |
+|---|---|
+| `fix(db): return 404 instead of 403 on IDOR (prevent entity leak)` | `fix: db issue` |
+| `refactor(api): consolidate query handlers into one contract` | `refactor stuff` |
+| `feat(session): session-health line + threshold rule` | `feat: added new stuff` |
+| `revert: "feat(auth): code TTL"` (sha) | `reverted it` |

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

@@ -0,0 +1,86 @@
+---
+name: confidence-check
+description: |
+  Readiness gate BEFORE writing implementation code: does this already exist, does it fit the project's
+  architecture, is the API claim actually checked, is there a working reference, is the root cause known.
+---
+
+# Confidence Check — earn the right to start
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "confidence check", "ready to implement", "before I start", "am I sure enough", "readiness"
+
+## When
+Right before implementation code gets written for anything beyond a one-line change, and *after* the scope is
+clear ([[spec-planning]] / planner). Every other gate in Crewforth fires at the end — review, DoD, the commit
+approval. Those catch bad code. None of them catch **good code that should never have been written**: the
+duplicate of a helper that already exists, the pattern that fights the project's architecture, the call built
+against an API that behaves differently than remembered. That waste is invisible to a reviewer, because what
+they see is a clean diff.
+
+## The six checks
+Each is answered with **evidence**, not with a feeling. Name what you ran or read.
+
+| # | Check | How it is actually answered |
+|---|---|---|
+| 1 | **Does it already exist?** | Grep/Glob the codebase for the behaviour *and* its likely other names. A near-duplicate counts. |
+| 2 | **Does it fit this project?** | Read `CLAUDE.md` + the relevant project skill. Same stack, same pattern, no new dependency smuggled in. |
+| 3 | **Is the external claim verified?** | The API / library / config behaviour you are relying on: read the real docs or the installed source. Recalled API shapes are the single most common wrong assumption. |
+| 4 | **Is there a working reference?** | An existing call site in this repo, or a known-good implementation. "It should work like this" is not one. |
+| 5 | **Is the root cause known?** | For a fix: the *cause*, not the symptom. Unknown → this is a [[systematic-debugging]] task, not an implementation task. |
+| 6 | **Can it be PROVEN when it is done — with what is running right now?** | Name the thing that will show it works — the suite, a migration applied to a real database, a request against a running service — and confirm it is reachable *before* starting, not after. One command. Measured: an agent spent 44 minutes and 167k tokens producing a migration, then found the database daemon was down and returned unverified. A precondition discovered at the end costs the whole run. |
+
+## The verdict is not a score
+The tempting form is a weighted score with a threshold. It is theatre: with six checks and any sane bar, a
+single failure sinks it anyway, so the weights only decorate a decision that was already binary. So: **any "no"
+is a stop.** Say which check failed and do the one thing that answers it — search, read the doc, find the
+reference, debug the cause — then start. If the user wants to proceed with a known gap, that is their call to
+make explicitly, and it gets written down as an assumption, not swallowed.
+
+Checks 3–6 do not apply to every task (a pure refactor has no external claim and no bug; a change the suite alone
+proves needs nothing brought up). Mark those **n/a**
+with a reason — n/a is a judgement you are stating, not a check you are skipping.
+
+An ambiguity you cannot resolve is not a failed check — it is a `[NEEDS CLARIFICATION: …]` marker
+([[spec-planning]]) carried into the plan. Guessing it and passing check 2 is the failure mode this gate exists
+to catch.
+
+## A bypassed gate leaves a record
+Gates get bypassed, legitimately: the user accepts a known gap, a DoD item is deferred, scope is trimmed under
+time pressure. What must not happen is the bypass being *spoken and forgotten* — three weeks later nobody can
+say whether a rule was weighed and overridden or simply missed, and those two are indistinguishable from the
+code. That gap is the missing half of "rule → gate": Crewforth enforces the rule at the tool level, and this line is
+the record of a human deliberately stepping past it.
+
+So when a gate is knowingly bypassed, write one line where the decision lives — the ADR for anything lasting
+([[adr]]), otherwise the plan's assumptions section:
+
+`BYPASSED <gate> — <why> — asked by <who> — revisit: <condition or date>`
+
+The `revisit` field is what separates a decision from a leak: a bypass with no condition attached is permanent
+by default, and nobody chose that. Never write this on the model's own authority — a bypass is the user's call,
+so the line records *their* decision, and its absence means the gate was not bypassed at all.
+
+## Output
+Six lines, one per check: `✅ <what was run/read>` or `❌ <what is missing>` or `n/a — <why>`. Then either
+"starting" or the single action that unblocks it. Keep it to the main thread; it is a handful of lines, not a
+document.
+
+## Fix the deciding rule before you see the options
+When this check ends in a choice — which approach, which library, which of three designs — write down what would
+make an option **win**, and what would **disqualify** one, *before* generating or evaluating any. A criterion
+chosen after the options exist is a criterion shaped by them: it will quietly favour the one already preferred,
+and nothing in the output will show that it did.
+
+Write the **kill criterion** in the same breath: what would make you abandon the whole approach. An option set
+with no losing condition is a preference wearing an analysis.
+
+> Honest boundary: this one is discipline, not a gate. Nothing can check whether the rule was written before the
+> options or backfilled after them — the value is that the user can see the rule stated first and argue with it,
+> which is impossible when the criterion never leaves your head. Treat it as cheap insurance, not as proof.
+
+## DoD (this skill's contribution)
+- Every check is answered with a named command, file, or document — never with a recollection.
+- Any "no" was resolved before implementation started, or is recorded as a user-accepted assumption.
+- Check 1 was answered by an actual search, not by "I don't think we have one".
+- A fix with an unknown cause went to [[systematic-debugging]] instead of being implemented on a guess.

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

@@ -0,0 +1,55 @@
+---
+name: crew-board
+description: Experimental: team board — claim an item, hand it over, complete it.
+argument-hint: "[claim <id> | done <id> | drop <id> | add <id> <title> | init | sync]"
+disable-model-invocation: true
+metadata:
+  kind: command
+  experimental: true
+---
+# /crew-board
+Argument: $ARGUMENTS
+
+Apply the `teamboard` skill. The engine is `bash .claude/hooks/board.sh`; never hand-edit the board.
+
+**Never make the user learn the syntax.** They should be able to run `/crew-board` and answer questions from
+there; `claim 3` and `done 3` are yours to type, not theirs. Every step below ends in a question with explicit
+options, not an instruction to go and type something.
+
+- **no argument** → `board.sh status`, plus `board.sh decisions` when the session-start line says decisions are
+  unread. Report: who holds what and for how long, what is claimable, what is blocked by which item, any STALE
+  claim, and any unread team decision. Then **ask which item to take, as options** (the claimable ones, each
+  labelled with its title and why it is a sensible next pick, plus "just looking"). On their answer, claim it —
+  do not tell them to run a claim command. If nothing is claimable, say what would unblock what, and stop.
+- **`claim <id>`** → `board.sh claim <id>`. A refusal is an answer, not an error: name who holds it and offer the
+  claimable alternatives. Never work around a refusal. On success it prints the **connected work** — what each
+  dependency actually delivered, and which items are waiting on this one. Read that back to the user before
+  writing anything; it is the context the previous person had and you do not.
+- **`done <id>`** → ask for what shipped (commit/PR), then `board.sh done <id> "<note>"`, tell the user which
+  items this unblocked, and **immediately offer the next item as options** — closing one and picking the next is
+  one movement, not two commands to remember.
+- **`decide "<what>"`** → `board.sh decide`. Anything that changes how OTHER work must be done — a contract, a
+  rejected approach, a constraint discovered the hard way — goes here the moment it is settled, while the reason
+  is still in the session. It reaches every teammate's next session opening; a decision that stays in this chat
+  reaches nobody. Write what was decided, why, and what it means for other items; name the items it affects.
+- **`decisions`** → list them, or read one. Read these before planning anything.
+- **`drop <id>`** → write the handover note FIRST — exactly where it stands, which files, and why the discarded
+  approach was discarded — then `board.sh drop <id> "<note>"`. The engine refuses an empty note.
+- **`add <id> <title> [deps]`** → add items. From `docs/PLAN.md`, carry each task's dependency edges across.
+- **no board in this repo yet** → do not tell the user to run `init`; that is the syntax they should never have to
+  learn. Say plainly what a board is for (a teammate's in-progress work is invisible without one) and **ask, with
+  options**: set one up on this repo's own remote · set one up in a separate repository (they give the URL — for a
+  board shared across repos, or people who cannot push to the code) · not now, this is solo work. On "not now",
+  drop it and do not raise it again unprompted. On a yes, run `init` yourself, then offer to fill it from
+  `docs/PLAN.md` if one exists, or ask for the items. Report what the server accepted (custom ref namespace or the
+  orphan-branch fallback) in one line — the user should know where their board lives without having to ask.
+- **`init`** → the same thing when asked for directly. `init --remote <url>` puts the board in a separate
+  repository. Run by ONE person, once — everyone else configures nothing and the board reaches them on its own.
+  If a board already exists this fetches it rather than creating a second.
+- **`sync`** → fetch and re-read; use it when the board looks stale or a gate message disagrees with reality.
+- **`off` / `on`** → release every board gate for this repo (`off --global` for all of them) and put them back.
+  The board is untouched either way. A repo that never ran `init` has no gates to begin with — never imply the
+  user must turn something off to work alone.
+
+Before writing any code for an item, confirm this user holds it. Commits are gated: `[#<id>]` for a held item,
+`[chore]` otherwise. Strip secrets from anything written to the board — it is pushed to the whole team.

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

@@ -0,0 +1,19 @@
+---
+name: crew-brainstorm
+description: Diverge before planning — turn a fuzzy ask into scoped options and a chosen direction.
+argument-hint: "[fuzzy idea / problem to explore]"
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-brainstorm
+Argument: $ARGUMENTS
+
+Delegate to the @agent-crew-planner agent applying the **brainstorm** skill. For an under-defined ask:
+1. Restate the real goal separately from the requested solution.
+2. Generate **2–4 genuinely different** directions (include a cheap/minimal one); give each its trade-off.
+3. Surface assumptions + open questions; mark which are blocking.
+4. Ask the user to choose WITH **explicit numbered options**; log the rejected directions + why.
+
+Write a long exploration to `docs/DISCOVERY.md`; return the option headings + the chosen direction (token-budget).
+Do NOT write code — this is discovery. Once a direction is chosen, hand off to `/crew-plan` (spec-planning).