Truffle — agent orientation

Truffle is a project-agnostic company-research engine: Firecrawl captures company sites, tools/ captures repeatable external source signals, Claude reasons, and a file-first store any project can query. This is the shared engine — not any one project's knowledge base. Status + layout: README.md.

Find your path

• Run a capture (profile/research a company) → use the /research-company skill. It's self-contained — its own capture playbook (firecrawl-capture.md) ships beside it, plus the store contract (SCHEMA.md/TAXONOMIES.md) — you need nothing else here. To make one company's offerings.md roster comprehensive (re-capture missing lines), use the sibling /deepen-offerings preset. For a company's visual & brand evidence (blind typography/layout/color/iconography cards + a ~5-second Visual & brand impression), use the sibling /visual-evidence skill — it runs after capture over the cached screenshots (contract modules/VISUAL.md), never inside it.
• Consume the store (query captured research) → use the /query-companies skill. It is the read-only router/guardrail; recipes stay in QUERYING.md, then store/<domain>/. For a human-facing handoff, render python scripts/render.py <company>; the brief is a regenerable lens, not a new source of truth.
• Capture repeatable external signals (SERP visibility, Wayback tenure, Trustpilot profile state, branded Trends, Exa neighbors, SEC EDGAR funding) → SIGNALS.md for the layer (the capture → persist → diff loop + run commands), then tools/README.md for the individual tools. The short of it: tools print JSON to stdout, scripts/signals.py persists captures to store/<domain>/signals/…, and signal_delta.py diffs them — never a blended score. Callers decide cadence + interpretation.
• Work on the engine (design/build) → frame (why / scope / non-goals) → architecture (how it works) → SCHEMA.md + TAXONOMIES.md (the contract). Changing a contract → MAINTAINING.md: the downstream blast-radius map + the gate to run. Working principles + prior art live in .claude/rules/engine-dev.md (Python house style in .claude/rules/python.md) — these auto-load when you touch the build surface, but read them directly if your agent doesn't load .claude/rules/ (e.g. Codex). Touching the human-facing surface (brief / comparison sheet / index) → read the presentation layer frame first.

Planning lives in Notion, not the repo. Strategy, the roadmap (initiatives grouped by Pillar / Theme + status), and proposals live in the Truffle — Teamspace Home teamspace. The repo holds the engine itself + the smaller/hardening BACKLOG.md.

Output / Chat Formatting

Do the messy work offstage; answer with a skimmable result. Use whatever framing, scratch checks, exploration, or verification the task needs while working. Before replying, decide the 1-3 things Brian actually needs to know. For normal execution work, final chat should lead with the outcome: what changed / what I found, why it matters, and any verification or risk Brian needs to trust it.

When the work is thinking together, show the reasoning shape. For brainstorming, framing, strategy, prioritization, or ambiguous tradeoffs, make the problem easier to see: name the frame, the real options, the tradeoffs, and your recommendation. Still keep it skim-first; don’t dump scratch work, checklist passes, or every path considered.

Depth is opt-in. Link to files or name where detail lives instead of pasting it. Use .claude/docs/writing-guidelines.md for durable docs and human-facing artifacts; for chat, use the smallest structure that makes the answer skimmable.