# bifrost-plugin — AGENTS.md

## Skill Discovery — check before non-trivial work (MANDATORY)

The `bifrost` MCP gateway may expose a shared skill library and a set of MCP
servers (docs, search, issue tracker, memory, etc.) — whatever your gateway is
configured to route to.

**BEFORE starting any non-trivial task** — researching prospects, qualifying leads, planning campaigns, preparing client proposals, implementing features, debugging, reviewing PRs, or drafting docs — you MUST call the gateway's skill-search tool, typically
**`mcp__plugin_<plugin>_bifrost__<skills-server>-skill_search`** (the plugin server;
`mcp__bifrost__…` only for a hand-added server, `mcp__claude_ai_<Name>__…` via the claude.ai
connector; the skill server is named `skills` by default; set `BIFROST_SKILLS_SERVER` if your gateway names it
differently), with a short description of the task. It returns the top matching
skills (a skill may handle the task entirely or give a specialized workflow). If
search doesn't surface the right one, browse with the corresponding
`skill_navigate` tool (decision tree), then load the chosen skill's full
instructions with `get_skill` before proceeding.

**Skip skill discovery for:** single-line edits with a known target, file
reads / grep, clarifying questions, or tasks the user has scoped to one file.

### Gateway routing (use bifrost, don't ask the user / don't guess)
Route capability requests through whichever MCP servers your gateway exposes, for
example:
- CRM / customer records / deal pipeline → your CRM server (e.g. HubSpot)
- Issue / ticket status → your issue-tracker server (e.g. Jira, GitLab)
- Production errors / stacktraces → your error-tracking server (e.g. Sentry, GlitchTip)
- Analytics / database queries → your analytics server (e.g. Metabase, Grafana)
- Web search, enrichment & scraping → your web tooling (e.g. Exa, Tavily, Firecrawl)
- Up-to-date library/API docs → your docs server (NOT training memory)
- Past decisions, customer notes, people, project facts → your memory server (query directly
  via the gateway's memory MCP tool — see Memory section below)

---

## Memory — agent-driven via the gateway MCP

Memory is accessed through the gateway's memory MCP server. There is no
automatic HTTP injection — memory recall and save are your responsibility as
the agent.

**Before non-trivial tasks:** call the gateway's memory search tool (typically
`mcp__plugin_<plugin>_bifrost__<memory-server>-search`, or the `mcp__bifrost__…` / `mcp__claude_ai_<Name>__…` form for a hand-added server or the connector) with a short query to recall relevant
past decisions, customer context, project facts, or known caveats (e.g. `k=5`).

**After completing significant work:** save durable facts or decisions with the
gateway's memory store tool (typically `mcp__plugin_<plugin>_bifrost__<memory-server>-store`, same prefix rules).
Include: customer notes and deal context, architectural decisions made, root causes of bugs found, project
conventions learned, gotchas discovered. Exclude: transient details, secrets,
per-file noise. Most stretches of work produce nothing durable, and storing
nothing is the right outcome then — a corpus padded with restatements of the
task is worse than a smaller one.

**If a search turns up something wrong:** correcting it is worth more than adding
to it. `memory_call` actions such as `evolve.edit` (correct a fact), `evolve.invalidate`
(retire an outdated one) and `evolve.link` (relate two) are how that happens. On a shared
gateway they are exposed only to admin keys. With a colleague key, store the
corrected fact with `memory_store` and name what it replaces. A store that only ever appends
accumulates contradictions no reader can resolve.

Run `/mcp` to confirm which memory tools your gateway exposes and their exact
tool names.

---

## Plugin file ownership

This repo is split into two concerns with clear boundaries.

### Manifests + MCP + Installer
Owns: `.claude-plugin/`, `.mcp.json`, `scripts/`, `commands/`, `.gitignore`, `README.md`

### Hooks + Skills + Guidance
Owns: `hooks/`, `skills/`, `guidance/`, `AGENTS.md`

**Cross-cutting rules:**
- Do **not** declare `hooks/hooks.json` in `plugin.json` — CC auto-loads it; manifest `hooks` is only for *additional* hook files. Never edit hook bodies for naming.
- Hooks reference the MCP server only by name (`bifrost`, skill tool prefix `<skills-server>-`) — never edit `.mcp.json`.

---

## Hook silent-fail contract

Every hook in `hooks/` MUST:
- Wrap the entire body in `try/catch` with `catch: process.exit(0)`
- Never write stack traces or error messages to stderr in a way that surfaces to the user
- Exit 0 on every code path — a non-zero exit blocks the CC session