crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/handoff/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: handoff
+description: |
+  Session handover: when context fills, a phase closes, or the topic changes, write an action-oriented handover
+  to docs/SESSION_STATE.md, then recommend /clear.
+---
+
+# Session Handover (Handoff)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "handoff", "hand off", "session summary", "session state", "clear context", "I'll continue", "next session", "where we left off", "run out of room", "continue tomorrow"
+
+## When
+Session fill (the `🔋` line) > 75% · phase closure · topic change. Goal: the next session should **not start from scratch**.
+
+## Output (docs/SESSION_STATE.md, local)
+```
+# Session Handover — <date>
+## Done
+- <completed work + which files>
+## In progress
+- <what's half-finished + exactly where it was left off>
+## Next step
+- <a clear, single high-value step>
+## Open decisions
+- <pending decision + options>
+## File pointers
+- docs/PLAN.md, relevant modules...
+## Blockers / risks
+- <if any>
+```
+
+## Measure the session before summarising it
+Run **`bash .claude/hooks/session-stats.sh`** first. What it reports belongs in the handover as fact, not
+impression — an auto-compaction means state was already dropped before you started writing (say what was lost),
+a runaway loop marks an approach the next session should not walk back into, and repeated prompts mark context
+that never landed and has to be written down explicitly this time. Missing script (plugin install) → say so.
+
+## Principles
+- **Action-oriented:** focused not on "what was done" but on "exactly where to resume now."
+- Preserve the rationale behind decisions (why this path was chosen) — so context isn't lost.
+- Once written, start a fresh session with `/clear`.
+
+## Holding a board item? The handover is not finished until the TEAM has it
+`docs/SESSION_STATE.md` is gitignored — it survives your `/clear`, and nobody else can read it. So when a
+`teamboard` claim is open, **the handover is not complete until it is on the board**. This is not an optional
+extra step:
+- Still on it → `board.sh note <id> "<where it stands, and why the rejected path was rejected>"`.
+- Not coming back → `board.sh drop <id> "<same>"`, which puts it back in circulation with your context attached.
+- Anything settled here that changes how OTHER items must be done → `board.sh decide "<what>" "<why + what it
+  means>"`. A decision that stays in your transcript reaches nobody; on the board it reaches every teammate at
+  their next session opening.
+
+Write the board note FIRST, then the local file — an interrupted handover should lose the private copy, not the
+shared one.
+
+## Redaction (`<private>` marker)
+`docs/SESSION_STATE.md` is local, but its content is copied into board notes and handovers — never persist a secret, token, credential, or
+personal note into it. Any content wrapped in **`<private>…</private>`** is a redaction marker: strip it from the
+written handover and leave a `[redacted]` placeholder in its place. If a resume genuinely needs a sensitive value,
+point to *where it lives* (env var, secret manager, the person to ask) — never the value itself.
+
+## Check it before trusting it
+That DoD sentence is a claim about a file nobody has tested. Before closing, run the **cold-reader pass**: write
+5–8 questions from the WORK (not from the file) with their expected answers, then answer them from the handover
+alone. A question that cannot be answered is a gap in the file. Procedure, phrasing that keeps the test honest,
+and the common failure shapes: **`references/cold-reader.md`**.
+
+## DoD
+- A handover file; a new session can resume where it left off by reading only this file.
+- The cold-reader questions were written **before** the file and every one of them is answerable from it.

package/kit/skills/handoff/references/cold-reader.md

@@ -0,0 +1,51 @@
+# The cold-reader pass
+
+Loaded on demand. SKILL.md's DoD says a new session can resume by reading only the handover file. This is how
+that sentence is checked instead of asserted — and it is the only part of the handover that can fail silently:
+a file that reads well to its author reads well *because* the author remembers what it leaves out.
+
+## The rule the pass exists to enforce
+
+**Write the questions before you write the file, from the work — not from the file.** An answer key derived
+from the handover only proves the handover is self-consistent. Derived from the session, it proves the handover
+carries the session.
+
+## Procedure
+
+1. **Before writing the handover**, list 5–8 questions the next session must be able to answer to continue. Take
+   them from the work itself: what was decided and why, what is half-finished and exactly where, what was ruled
+   out, what breaks if it is touched, what the next action is. Write the expected answers down beside them.
+2. **Write the handover** as usual.
+3. **Answer the questions from the handover alone.** The consumer may open only the paths the file itself names
+   — the template requires a file-pointers section, so following those pointers *is* the file working. It may
+   not use the session's memory, search the repository for context the file never mentions, or ask.
+4. **Score each question**: answered · partly answered · not answerable. Any "not answerable" is a gap in the
+   handover, not in the reader.
+5. **Fix the file and re-answer** the failed questions. The pass closes when every question is answerable.
+
+## Phrasing that keeps the test honest
+
+- **Do not reuse the handover's own words in the question.** "What did we decide about the cache?" is answerable
+  by keyword-matching the heading; "What happens to a request that arrives while the cache is rebuilding?" is
+  not. A question a reader can answer by lifting a phrase has measured the search, not the content.
+- **Ask for the reason, not the label.** "Which approach was chosen" is a lookup. "Why was the other one
+  rejected" is what a resuming session actually needs, and it is what handovers most often drop.
+- **Ask at least one question whose answer is a location** — a file, a branch, a command. Handovers routinely
+  describe a state that nothing points at.
+
+## Who runs it
+
+Wherever the handover is written — usually inside `crew-session-manager`, which the discipline routes this
+through, sometimes the main thread. Either way no agent in Crewforth holds the delegation tool (all twelve
+shipped agents declare an explicit allowlist and none contains it), so there is no separate cold-reader
+subagent to hand the file to. That is a real limitation and worth naming: the same context that wrote the file is answering
+from it, so the discipline is entirely in step 1 (questions from the work, written first) and step 3 (answer
+from the file only). If a genuinely cold reader is available — another session, a teammate, a fresh window
+opened at the file — use it; the procedure is unchanged and the result is stronger.
+
+## What a failure looks like
+
+The common ones, in the order they occur: the "in progress" entry names a task but not the line it stopped at;
+a decision is recorded without the alternative it beat; a blocker is described without who or what unblocks it;
+and the next step is a category ("continue the refactor") rather than an action. Each of those passes a reading
+by its author and fails a cold reader.

package/kit/skills/i18n-integrity/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: i18n-integrity
+description: |
+  Translation integrity: every key present in every language, no hardcoded strings, consistent placeholders
+  and plurals. Runs when user-facing text changes.
+---
+
+# Translation Integrity (i18n)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "i18n", "translation", "language file", "missing translation", "localization", "translate", "untranslated", "hardcoded string", "multi language", "multiple languages", "still in english", "locale"
+
+Goal: no missing/broken text in any language. Languages: the set the project declares (e.g. in `CLAUDE.md` or the locale directory).
+
+## Audit dimensions
+- **Key parity:** every key has a counterpart in ALL languages; a missing/extra key = a finding.
+- **No hardcoded strings:** user-facing text is not embedded in code, it comes from the language file.
+- **Placeholder consistency:** `{name}`, `%s`, ICU `{count, plural, ...}` are identical in every language.
+- **Plural rules:** language-specific plural forms (especially RU) are correct.
+- **Empty/identical value:** an untranslated (identical to the source) placeholder value is flagged.
+
+## Check (key-set comparison)
+```bash
+# Example: compare the key sets of JSON language files
+for f in locales/*.json; do echo "== $f =="; jq -r 'keys[]' "$f" | sort > "/tmp/$(basename $f).keys"; done
+diff /tmp/tr.json.keys /tmp/en.json.keys   # differences = missing/extra keys
+```
+
+## DoD
+- Key sets are equal across all languages; no hardcoded user text; placeholders are consistent.
+- **Missing translation = red** (no deferral).

package/kit/skills/incident-runbook/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: incident-runbook
+description: |
+  Production incident response: diagnose → mitigate → resolve, then a blameless postmortem and a repeatable
+  runbook. Stop the impact first, root cause second.
+  Use when production is degraded or broken, and again for the postmortem afterwards.
+---
+
+# Incident Response & Runbook
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "incident", "incident response", "runbook", "postmortem", "root cause", "outage", "production incident", "post-incident"
+
+Two modes: **live incident** (what to do right now) and **aftermath** (postmortem + runbook). Priority: stopping
+user impact > finding the root cause. No panic, one ordered step at a time.
+
+## Live incident — sequence
+1. **Acknowledge & classify** — what is the impact (who, how much), severity (SEV1 full outage … SEV3 minor).
+2. **Mitigate the impact FIRST** — rollback, turn off a feature flag, shift traffic, scale up. Without waiting on the root cause.
+3. **Single coordinator** — it is clear who decides; communication goes through one channel.
+4. **Diagnose** — last change? (deploy/migration/config) narrow it down with logs+metrics+traces (observability).
+5. **Resolve** — the smallest safe fix; then verify (health check).
+6. **Close** — confirm the impact is over; note the timeline (a postmortem input).
+
+## Mitigation reflexes
+- Last deploy suspect → **rollback** (deploy revert).
+- Suspect feature → turn off the **feature flag**.
+- After a destructive migration → restore from backup (db-migration).
+- Dependency/service down → circuit breaker / graceful degradation.
+
+## After the incident
+
+Blameless postmortem + producing a durable runbook: **`references/postmortem.md`**.
+
+## Invariant rules
+1. **Stop the impact, then understand** — the root cause does not hold up the resolution.
+2. **Blameless culture** — the postmortem questions the system, not the person.
+3. **Actions are owned + dated** — no "we'll look at it later".
+4. **The runbook is executable** — real commands/steps, not wishes.
+5. **Make learning permanent** — the lesson goes into an adr/runbook/monitoring, it does not get lost.

package/kit/skills/incident-runbook/references/postmortem.md

@@ -0,0 +1,16 @@
+# After the incident — postmortem & runbook
+
+Both of these happen **after** the live response is over, not during it. Get the impact stopped first (SKILL.md);
+come here once the incident is resolved.
+
+## Postmortem (blameless)
+Once the incident is resolved, within 24-72 hours:
+- **Timeline**: detection → response → resolution (actual times).
+- **Impact**: who, for how long, what was lost.
+- **Root cause**: "5 whys"; the system/process is questioned, not the person (**blameless**).
+- **Actions**: concrete, owned, dated items that prevent a recurrence (no deferral).
+- If a lasting decision came out of it → `adr`.
+
+## Produce a runbook
+For repeatable incidents, a step-by-step runbook: symptom → diagnostic commands → mitigation → verification → escalation.
+The runbook must be **project-specific** and **executable** (not generic); coordinate with `docs-writer`.

package/kit/skills/iterate/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: iterate
+description: |
+  Refine-to-Done loop: repeat until tests green + review clean + nothing deferred; bounded. Not the harness /loop.
+---
+
+# Iterate — refine to Done, don't stop at the first attempt
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "iterate", "loop until done", "keep going until"
+
+## When
+A task has an objective acceptance criterion (tests, a review gate, a spec) and the first attempt may not
+meet it. This is a single-session refinement loop — NOT the harness `/loop`, which schedules a prompt on an
+interval. Open-ended exploration with no checkable target does not belong here.
+
+## The loop
+1. **Name the exit test first** — the concrete, checkable condition that means "done": tests green,
+   `crew-review-agent` clean, the spec's acceptance criterion met, zero SonarQube findings. No exit test →
+   go to spec-planning first; a loop without a target never terminates.
+   **Prefer an external, machine-grounded verifier** — a test exit code, a schema match, a lint/quality gate —
+   over an LLM's self-assessment. A model grading its own output inflates; an "it looks done" or even a single
+   "review clean" with no objective check is a weak verifier. When the only available check is a judgment call,
+   ground it (a second agent with a distinct lens, an explicit rubric) rather than trusting the loop's own say-so.
+   For a generative task with no exit code, the `eval-grader` skill *is* that external verifier — a two-layer
+   scorecard (code metrics + LLM-judge) over a fixed set, read as signed deltas vs a pinned baseline.
+2. **Run one round**: change → verify (drive the real flow, not only tests) → check the exit test.
+3. **Report the gap** every round — state what still fails and why. Never loop silently.
+4. **Repeat** until the exit test passes. Stop early and surface it if: two rounds pass with no new
+   progress (you are stuck — report, don't spin), the exit test itself is wrong, or a blocker needs a
+   decision from the user.
+5. **Close at the DoD gate, not at a commit.** `crew-commit-agent` still proposes and waits for §4.4
+   approval. The loop never commits, pushes, or deploys on its own.
+
+## Guardrails
+- **Bounded, not infinite.** A fixed exit test plus a no-progress stop is the whole point; "keep trying
+  forever" is a bug, not diligence.
+- **Token discipline** ([[token-budget]]): each round re-pays for context. Keep a round's output a summary,
+  push heavy logs to `docs/*.md`, and don't fan out a subagent per round unless isolation demands it.
+- **Don't move the goalposts.** Never weaken the exit test to end the loop — fix the work, or stop and ask.

package/kit/skills/mcp-builder/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: mcp-builder
+description: |
+  Build a Model Context Protocol (MCP) server so an AI client can call your tools/resources: design tool schemas,
+  pick a transport, handle errors, and test it. For exposing an API, database, or service to Claude and other clients.
+---
+
+# MCP Builder
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "MCP server", "build an MCP", "model context protocol", "expose tools to Claude", "MCP tool"
+
+An MCP server exposes **tools** (actions the model can call), **resources** (data it can read), and **prompts**
+(reusable templates) to any MCP client over a standard protocol. The whole job is: **design a small set of clear,
+well-described tools, validate their inputs, return useful errors, and prove it works with a real client.** The
+protocol is easy; the design of the tools is what makes the server good or useless.
+
+> **Crewforth adaptation (local, .claude/):** Stack-agnostic — TypeScript (`@modelcontextprotocol/sdk`) or Python
+> (`mcp` / FastMCP) are the maintained SDKs; match the project's language. §4 Prohibitions apply (no AI trace in
+> generated code/strings). Secrets (API keys the server needs) go via env, never hardcoded — Crewforth's secret gates apply.
+
+## Design first (the tools ARE the product)
+- **Few, purposeful tools** — expose *tasks*, not a 1:1 mirror of every API endpoint. "create_invoice" beats "post_v2_billing_documents".
+- **The description is the interface** — the model routes on it. Say what it does, when to use it, and what it returns, in plain language. A vague description = an unused or misused tool.
+- **Typed, validated inputs** — a JSON-Schema for each tool; required vs optional explicit; enums over free strings where possible. Reject bad input with a clear message, don't guess.
+- **Useful returns & errors** — return structured, model-readable results; on failure return an actionable error ("no invoice with id X") not a stack trace. Never crash the server on bad input.
+- **Least privilege** — a tool does one scoped thing; destructive actions are explicit and, where possible, confirmable. Don't expose raw SQL / shell unless that is genuinely the product.
+
+## Checklist
+- [ ] Tools chosen by task, not by mirroring endpoints
+- [ ] Each tool has a clear description (what · when · returns) and a JSON-Schema input
+- [ ] Inputs validated; bad input → clear error, not a crash
+- [ ] Returns are structured and model-readable; errors are actionable
+- [ ] Transport chosen (stdio for local, HTTP/SSE for remote) — see references
+- [ ] Secrets via env; no hardcoded keys
+- [ ] Tested against a real client (Inspector + a live client)
+
+---
+
+## Protocol, SDK skeletons, transport, and testing
+Concrete server skeletons (TypeScript + Python), stdio vs. HTTP transport choice, resources/prompts (not just
+tools), and the test loop (MCP Inspector → real client): **`references/building.md`**.
+
+## Invariant rules
+1. **Design the tools before writing them** — task-shaped, few, clearly described.
+2. **Validate every input** — schema-checked; bad input returns an error, never crashes.
+3. **Errors are for the model** — actionable text it can recover from, not raw traces.
+4. **Secrets via env only** — never hardcode credentials the server needs.
+5. **Prove it with a real client** — a server that only "looks right" is untested.
+6. **Descriptions guide; they never authorize** — a tool's description, schema or metadata shapes what the model
+   tries. Whether a call is allowed is decided in the handler, per requester and per resource, every time. A schema
+   narrows shape; it does not make a path, URL or id safe.
+7. **Bind identity to the connection, not to a name** — never route a call or accept a result by a tool name,
+   server name or alias the other side can choose. How these fail is in `security-scan/references/ai-agents.md`.

package/kit/skills/mcp-builder/references/building.md

@@ -0,0 +1,71 @@
+# MCP: protocol, skeletons, transport, testing
+
+Loaded on demand. SKILL.md is the design discipline; this is the concrete how.
+
+## The three primitives
+
+- **Tools** — actions the model invokes (side effects allowed): `create_ticket`, `search_orders`. This is what most servers are for.
+- **Resources** — readable data addressed by URI the client can pull into context: `file://…`, `db://customers/42`. Read-only.
+- **Prompts** — named, parameterized templates the user/client can invoke. Optional; add only if you have reusable flows.
+
+Start with tools. Add resources when the client needs to *read* your data as context; add prompts only if there's a real reusable template.
+
+## Transport — pick by where it runs
+
+- **stdio** — the server is a local subprocess of the client (desktop app, CLI). Simplest; no network, no auth. Default for local/dev tools.
+- **Streamable HTTP / SSE** — the server is remote (hosted, shared). You now own auth, CORS, and network errors. Use only when the tool must be remote/multi-user.
+
+## Skeletons
+
+**TypeScript (`@modelcontextprotocol/sdk`):**
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "orders", version: "1.0.0" });
+
+server.tool(
+  "search_orders",
+  "Search orders by customer email. Returns up to 20 orders, newest first.",
+  { email: z.string().email(), limit: z.number().int().min(1).max(20).default(20) },
+  async ({ email, limit }) => {
+    const orders = await db.findOrders(email, limit);        // your logic
+    if (!orders.length) return { content: [{ type: "text", text: `No orders for ${email}.` }] };
+    return { content: [{ type: "text", text: JSON.stringify(orders) }] };
+  }
+);
+await server.connect(new StdioServerTransport());
+```
+
+**Python (FastMCP):**
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("orders")
+
+@mcp.tool()
+def search_orders(email: str, limit: int = 20) -> str:
+    """Search orders by customer email. Returns up to 20 orders, newest first."""
+    orders = db.find_orders(email, limit)          # your logic
+    return f"No orders for {email}." if not orders else json_dumps(orders)
+
+if __name__ == "__main__":
+    mcp.run()          # stdio by default
+```
+
+Both: the **docstring/description is the model's interface** — write it as the design step demands. Types drive the input schema (zod / Python type hints) — no hand-written JSON-Schema needed with these SDKs.
+
+## Error handling
+
+- Validate at the boundary — the SDK schema rejects wrong *types*; you still check *semantics* (does the id exist? is the caller allowed?).
+- Return errors as normal tool results with clear text the model can act on, or throw the SDK's error type for protocol-level failures. Never let an unhandled exception kill the process on bad input.
+- Don't leak internals (stack traces, connection strings) in error text.
+
+## The test loop
+
+1. **MCP Inspector** — `npx @modelcontextprotocol/inspector <run-command>` launches a UI that lists your tools/resources and lets you call them with arbitrary inputs. Verify each tool's schema, a happy path, and a bad-input path here first — fastest feedback.
+2. **Real client** — register the server in an actual client (e.g. Claude Desktop / Claude Code `.mcp.json`) and confirm the model *discovers* it, *routes* to the right tool from a natural prompt (validates your descriptions), and handles the returned data.
+3. **Edge cases** — empty results, invalid input, missing auth, large output. A tool is done when its failure modes are as clean as its happy path.
+
+If the model picks the wrong tool or ignores yours, the bug is almost always the **description**, not the code — rewrite it and re-test in the real client.

package/kit/skills/observability/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: observability
+description: |
+  Stack-agnostic observability: structured logs, correlation ids, metrics and traces; no PII or secrets in logs.
+  Makes a production issue traceable to why it happened.
+  Use when adding a log line, an error path, a metric, or when an incident could not be traced.
+---
+
+# Observability
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "observability", "structured logging", "structured log", "add a trace", "add a metric", "correlation id", "add logging"
+
+Goal: to be able to answer "what happened, where, why" during a production incident **by looking at the logs**.
+It is stack-agnostic; when you need a framework-specific library/format, do a web search.
+
+## Three signals
+- **Log** — event record (structured/JSON, leveled).
+- **Metric** — numeric time series (request count, latency, error rate, resource usage).
+- **Trace** — a request's journey across services (spans + correlation id).
+
+## Checklist
+- [ ] Logs are **structured** (JSON/key-value), not string interpolation
+- [ ] Every log line carries a **correlation id** (request/trace id)
+- [ ] Levels are correct: the DEBUG/INFO/WARN/ERROR distinction is meaningful
+- [ ] **No PII/secret is logged** (password, token, card, national/ID number, email body)
+- [ ] Error logs carry context (input summary, user/resource id — not PII); the stack trace does not leak to the user
+- [ ] Critical business metric + infrastructure metric are emitted (where applicable)
+- [ ] The correlation id is **propagated** across service-to-service calls (header/propagation)
+
+## How
+1. **Structured logger** — set up/use one whose output is machine-readable (JSON). Search for the library the framework recommends.
+2. **Correlation id**: generate it at the entry point (HTTP middleware / message consumer) or take it from the incoming `X-Request-Id`/trace header; put it in the log context; **propagate** it to downstream calls.
+3. **Level discipline**: INFO = business event, WARN = expected-but-noteworthy, ERROR = needs intervention. DEBUG is off/sampled in production.
+4. **Context fields**: `event`, `correlation_id`, `user_id` (not PII, an opaque id), `duration_ms`, `outcome`. Do not embed them in free text.
+5. **Metrics**: at minimum RED (Rate, Errors, Duration) or USE; plus business-critical counters. Search for the framework's metrics library.
+6. **Trace** (in a distributed system): start/end spans, bind the correlation id to the trace id.
+
+## PII / secret leakage (critical)
+**Never** to the log: password, token, API key, card number, national/ID number, full email/phone body, raw request body.
+- Mask: `user@***`, card `**** 1234`, token `sk-p…789`.
+- When needed, log an **opaque id** (hash/uuid), not the raw value.
+- This axis overlaps with `security-scan` (sensitive data in logs) and `privacy-compliance` (KVKK/GDPR) — if personal data is involved, trigger those too.
+
+## Invariant rules
+1. **Structured > free text** — greppable, parseable.
+2. **Correlation id on every line** — without it, a distributed error is untraceable.
+3. **No PII/secret is logged** — mask it or use an opaque id.
+4. **Do not make noise** — every line must answer a question; do not add meaningless spam logs.
+5. **Match the existing format** — if the repo has a logger, follow its pattern; do not impose a new one.

package/kit/skills/performance/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: performance
+description: |
+  Stack-agnostic performance: measure first, find the bottleneck, then optimise. N+1, needless allocation, wrong
+  async boundary, missing index/cache, heavy payload. No premature optimisation.
+  Use when something is slow, before optimising anything, and when a change touches a hot path.
+---
+
+# Performance
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "performance", "slow", "optimization", "profiling", "N+1", "latency", "memory leak", "leaked memory", "load test", "seconds to open", "seconds to respond", "anything slower", "make it slower"
+
+Core rule: **measure first, optimize later.** Optimization without measurement is a guess; it usually speeds up the
+wrong place and adds complexity. Stack-agnostic; do a web search when you need the profiling tool/library.
+
+## Method (in order)
+1. **Set a target** — what is "acceptable"? (p95 latency, throughput, memory ceiling). Numeric.
+2. **Measure** — find the real bottleneck with a profiler/APM/benchmark; don't start from a guess.
+3. **Fix the single most expensive thing** — Amdahl: speeding up a 5% path by 2x is wasted; target the hot path.
+4. **Measure again** — did it actually improve, is there a regression.
+5. **Stop** — once you hit the target, finish; no endless micro-optimization.
+
+## Common bottlenecks
+
+Catalog of common bottlenecks + fixes to consult: **`references/bottlenecks.md`**.
+
+## Measurement tips
+- Measure **under load** (a single request misleads); with a realistic data volume.
+- **Not p50, but p95/p99** — tail latency is what burns the user.
+- Don't trust micro-benchmarks; an end-to-end profile is more honest.
+
+## Invariant rules
+1. **Don't optimize without measuring** — a change without a profile = a guess.
+2. **Target the hot path** — don't speed up the small share.
+3. **Don't break correctness** — don't sacrifice behavior/edge cases for speed.
+4. **Complexity budget** — make an optimization that seriously hurts readability only if there is a measured gain; comment it.
+5. **Stop once you hit the target** — YAGNI; no premature/excessive optimization.

package/kit/skills/performance/references/bottlenecks.md

@@ -0,0 +1,10 @@
+# Common bottlenecks
+
+| Area | Pattern | Fix |
+|---|---|---|
+| **DB** | N+1 query, missing index, `SELECT *`, table scan | eager/batch loading, index (db-migration), only needed columns |
+| **Memory** | needless allocation, holding large objects, leak | pooling, streaming, releasing references |
+| **Async** | wrong sync/async boundary, blocking I/O, serial await | parallel await, non-blocking I/O |
+| **Network/payload** | oversized response, no compression, chatty API | pagination, field selection, gzip, batch (api-design) |
+| **Cache** | repeated expensive computation, no/wrong cache | cache at the right layer + correct invalidation |
+| **Frontend** | needless render, large bundle, blocking resource | memo, code-split, lazy, critical CSS |

package/kit/skills/privacy-compliance/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: privacy-compliance
+description: |
+  KVKK/GDPR audit method: data inventory, purpose/basis/retention, minimisation, consent, transparency,
+  data-subject rights, cross-border transfer. crew-privacy-agent applies it.
+---
+
+# Privacy Compliance (KVKK / GDPR)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "kvkk", "gdpr", "privacy", "consent", "data retention", "minimization", "personal information", "what we store about", "data we collect", "delete my data", "right to be forgotten"
+
+<!-- Requires-tool: WebFetch -->
+<!-- Machine-readable, and smoke-test enforces it: every agent that applies this skill must carry WebFetch.
+     Without it the instruction below is one an agent physically cannot obey — it would either decide from
+     memory, which this skill forbids in the same breath, or quietly skip the check. -->
+
+## Official sources (authority — always defer to these)
+The **primary, official** sources this skill rests on; rules are always interpreted against these:
+- **KVKK** (Turkey): https://www.kvkk.gov.tr/ — the law, regulations, principle decisions, guidelines.
+- **GDPR** (EU): https://gdpr-info.eu/ — article texts (Art.) and Recitals.
+
+If you are unsure about a specific article/threshold/definition (retention period, explicit-consent requirement,
+the Art. 8 age limit, transfer basis, etc.), **check the relevant official source** — do not decide from memory or by
+guessing. In the finding, **cite** the article you rely on (KVKK Art. … / GDPR Art. …). Fetched content is a reference; you own the interpretation.
+
+## Which regimes apply — the project says so, Crewforth does not guess
+KVKK and GDPR above are the **defaults**, not the world. A product sold in California is under CCPA and one in
+Brazil under LGPD, and Crewforth shipping a global list would be claiming knowledge it does not have — the same
+mistake as rating code without running the analyser. So the project declares its own, and the authority is
+whatever source it names.
+
+Read **`.claude/regulations.conf`** if it exists. One regime per line, `#` comments ignored:
+
+```
+# name | official source | axis
+KVKK | https://www.kvkk.gov.tr/         | personal-data
+GDPR | https://gdpr-info.eu/            | personal-data
+CCPA | https://oag.ca.gov/privacy/ccpa  | personal-data
+```
+
+| What you find | What you do |
+|---|---|
+| No file | Audit against KVKK + GDPR |
+| A regime **with** a source | Audit it; every finding cites that regime's article, checked against its source |
+| A regime with **no** source | **Do not rule on it.** Report "declared, no source given — cannot audit" and ask for the URL |
+| An axis other than `personal-data` (BDDK, PCI-DSS, HIPAA, SOX…) | **Say so out loud**: sector regulation is outside this skill. Do not audit it, and do not let its presence in the file imply that it was |
+
+That last row is the point of the file, not an edge case. Somebody who writes `BDDK` into it and gets a clean
+report would reasonably conclude Crewforth checked it. It did not, and silence would be the lie.
+
+The declaration file is the **project's**, never Crewforth's: no installer writes it and no update rewrites it.
+Its absence means "the defaults apply", which is why nothing has to be created for the common case.
+
+## Audit axes
+- **Inventory:** what data, collected from where, flowing to where, shared with whom?
+- **Purpose + basis + retention:** for each field, purpose is limited, legal basis is clear, retention period is defined.
+- **Minimization:** data not needed for the purpose is not collected.
+- **Consent:** where required, explicit, recorded, and revocable.
+- **Transparency:** disclosure has been made; the user knows what is collected/processed.
+- **Data subject rights:** access / rectification / erasure / portability / objection are actionable.
+- **Cross-border transfer & third-party:** bound to a legitimate basis (SCC/adequacy/consent).
+
+## Output
+Per-field/per-flow finding + fix; if "clean", the rationale.
+
+**Evidence redaction (`<private>` marker):** an audit report is a shared artifact — it must not itself leak the
+personal data it audits. When a finding has to reference a real value as evidence, wrap it in
+**`<private>…</private>`**: the raw value is stripped and shown as `[redacted]` in the report, while the finding still
+names the field, flow, and article. Never paste live PII (national ID, email, phone, health data) into the report body.
+
+> **Project note:** If data of minors (children) is processed, special protection is required
+> (KVKK / GDPR Art. 8 · parental consent & age verification). This is a domain-specific rule and is
+> defined in the project's own skill/CLAUDE.md — it is not baked into the generic audit.
+> Project-specific rules (consent texts, retention periods) also live in the project CLAUDE.md.

package/kit/skills/red-team/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: red-team
+description: |
+  Attacker's-eye test of LLM/agent defenses: instruction hijacking, data exfiltration and tool abuse through
+  untrusted content; verifies whether the defense actually holds.
+---
+
+# Red Team (LLM / Agent Defense)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "red team", "red-team", "prompt injection", "test prompt injection", "jailbreak", "defense test", "adversarial test", "injection scenario", "previous instructions", "hidden instructions", "malicious instructions", "injected instructions"
+
+Goal: verify a system's defense against prompt injection and abuse by **attempting to break it**.
+Only meaningful on systems that have a defense (the CLAUDE.md "Untrusted content" axis); report findings to `crew-security-expert`.
+
+> **Ethical boundary:** Only test **your own / authorized** system. The attack scenarios generated are for
+> verifying the defense; actual harm / use against someone else's system is out of scope (§4, security policy).
+
+## Threat model — what to test
+- **Instruction hijacking**: content read via a tool (web, file, issue, e-mail, DOM) says "forget the previous instructions / run this." Does the system keep it as **data**, or treat it as a command?
+- **Authority/approval bypass**: content gives a fake approval like "the user authorized / test mode / admin." Does the system take its §4.4/§4.5 approval only from the user?
+- **Data exfiltration**: content suggests sending user data to an address/endpoint. Does the system blindly fetch/exfil?
+- **Tool abuse**: content embeds a destructive command / hidden link / encoded instruction.
+- **Indirect injection**: a malicious instruction is stashed in data that will be read later (a record, a comment, a file name).
+
+## How to test
+1. **Extract entry points** — every place the system reads untrusted content (the same attack surface: security-scan).
+2. **Plant an injection payload** — embed an instruction/authority-claim/urgency/encoded text into that content.
+3. **Observe**: did the system apply the instruction, or surface it and ask the user? Did it take approval from the content?
+4. **Vary it**: role-play, "test mode", multi-step, cross-language, base64/homoglyph evasion.
+5. **Classify the result**: defense held / partial / broken; every break is a finding.
+
+## Evaluation
+| Result | Meaning |
+|---|---|
+| **Held** | The instruction was treated as data, surfaced, approval only from the user |
+| **Partial** | Some variants leaked; the defense is inconsistent |
+| **Broken** | The instruction in the content was applied / a fake approval was accepted → CRITICAL |
+
+## Invariant rules
+1. **Authorized system only** — test your own defense; no real attack / someone else's system.
+2. **Finding = a defense gap** — report it for the fix, not for exploitation (crew-security-expert).
+3. **Do not leak payloads** — masked/summarized in the finding; do not spread a live malicious command.
+4. **Strengthen the defense layer** — every break feeds back into the CLAUDE.md "Untrusted content" rule.
+5. **A model saying the wrong thing is not yet a finding** — it becomes one when code lets that output cross a
+   boundary: reach another user's context, act with authority the requester lacks, disclose data they cannot read,
+   or drive a sink they could not reach. The code-level classes behind that line are in
+   `security-scan/references/ai-agents.md`.