crewforth 0.0.1 → 3.0.0-rc.1

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).

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.