crawfish

Author definition.py — typed inputs/outputs (Parameter, static vs fluid) and the team shape (lead/coordination). Load when writing or editing a Definition's typed boundary. Static is the deliberate consequential choice; fluid is the untrusted default.

Author fixtures/ for craw test and gate on a baseline with craw eval — deterministic, mock-by-default, randomness carried in --seed. Load when adding test inputs or an eval gate to a Definition.

Author instructions.md and agents/*.md — front-matter (role, delegates_to, tools, model) over a markdown prompt. Load when writing a lead prompt or a subagent. Fluid inputs are data the prompt analyzes, never instructions to obey.

Attach knowledge with Wiki / with_context / SkillRef — summoned content is tainted data, never instructions, and is pinned by content hash. Load when giving an agent a rubric, corpus, or reference it should consult.

Author mcp/*.py — MCPConnection instances; auth is a secret reference (env-var name), never inline. Load when adding an external tool server. A new connection re-enters the consent gate (craw code grant).

Optimize a Crawfish component — set a baseline (craw eval), search knobs (craw tune), iterate (craw refine), self-version (craw learn). Train vs eval mode, budget-bounded. Load when improving a component's quality or cost.

Author policies/*.py (module-level Policy instances — consequential static config) and skills/*.md (bundled skills). Load when adding a guardrail/routing/permission policy or a bundled skill. A policy is static-only.

Author tools/*.py — a callable whose name matches the filename stem, with typed IO and taint propagation from fluid inputs. Load when writing a host-side tool. Agent-authored tool code compiles jailed (CRA-267), fail-closed.

Determinism discipline and reading the ledger in Crawfish. Load before running, evaluating, or debugging a component: iterate on the mock (craw dev), carry randomness in --seed, promote to --live under --budget; read results via craw inspect / craw logs and the versioned --json surface.

The Crawfish pipeline mental model — Source → Filter → Batch → Aggregator → Router → Sink, and the Definition directory contract. Load when designing a pipeline or deciding between batch fan-out, an aggregator reduce, a router branch, or a refine loop.

The Crawfish security spine — the prompt-injection boundary. Load whenever authoring or wiring a Definition, sink, MCP connection, policy, router, or pipeline. Fluid inputs are untrusted data and never reach a sink target or an instruction slot; consequential sink targets and idempotency keys are static-only; secrets resolve by reference, never in a prompt or config. This skill teaches the boundary; the craw code verbs enforce it.