---
name: sparda-mcp
description: >-
  Drive a SPARDA compiled Behavior Runtime to its full potential. Use this whenever
  you are connected to a backend running the SPARDA Runtime (compiled into a Unified
  Behavior Graph - UBG) — recognizable by the tools `sparda_get_context`, `sparda_info`,
  `sparda_confirm`, or composite tools. It teaches the graph-context-first workflow,
  how to exploit the response-recycling flywheel, the circuit-breaker, crystallized
  circuits, offline Twin simulations, and the two-phase confirm protocol for writes.
---

# Driving a SPARDA Behavior Runtime

A SPARDA server is driven by a compiled **Unified Behavior Graph (UBG)** — the graph SPARDA's compiler produces from the host application's states, transitions, permissions, and side-effects, serialized under the **SBIR** specification. Instead of exposing raw, disconnected endpoints, SPARDA compiles the app into a deterministic behavioral model. The local **SPARDA Runtime** dynamically executes this graph inside the live host process, powering the MCP interface, the Twin simulation clone, and the Immune system offline.

> This skill covers the **runtime** (driving a live MCP server) — the live half of SPARDA's trust layer: *"AI writes. SPARDA proves."* The same graph also powers dev-time proof commands you run in the app's repo — `sparda review` (the behavior diff of a PR), `apocalypse` (prove the deploy), `timeless` (record/replay a request), `heal` (prove a fix), `mirror` (serve the graph), `ubg` (compile), `verify` (prove the compiler's laws). Those are CLI, not MCP tools; see the project README.

## Rule 0 — call `sparda_get_context` first, every session

Before anything else, call **`sparda_get_context`** (no params). It returns the *live* state of the SPARDA Behavior Graph:

- the active routes/tools, workflows, and type-propagated schemas;
- `runtime` — current stats (calls, errors, quarantine states, Twin mode active);
- the last ~20 **events** (errors, latency anomalies, immune alerts);
- **immune memory** (cached antibodies and error diagnoses);
- **recycling** metrics (flywheel memory hit rates);
- a `behavior` snapshot of stable variables.

Read it to orient yourself inside the graph. `sparda_info` gives a lighter summary of counts.

## The tools you'll see

- **Per-route tools** — `snake_case` names derived from the app's real routes
  (e.g. `get_users`, `get_users_by_id`). A `[partial schema]` prefix means the
  parameter schema was only partially inferred — pass arguments carefully.
- **Meta-tools** — `sparda_get_context`, `sparda_info`,
  `sparda_list_disabled_tools`, `sparda_confirm`.
- **Composite tools** — labelled `[Labs circuit ×N]`, `readOnly`. One call runs a
  whole proven multi-step chain (see *Crystallized circuits* below).

Only **enabled** tools appear. Write tools are hidden until the user opts in, so a
missing write is a config state, not an error — see *Writing safely*.

## Exploit the intelligence layer (this is the "full potential")

**1. Response-recycling flywheel — make repeated reads free.**
When the *same* read tool returns a byte-identical result for the *same* arguments
**3 times within 30 seconds**, SPARDA serves the next identical call straight from
RAM (`servedByFlywheel: true`) **without touching the host app**. So:
- Don't fear repeating stable GETs — repetition is what *activates* the cache.
- Don't bolt your own client-side cache on top; you'd hide the signal that lets
  SPARDA recycle, and you'd lose freshness control.
- Watch `recycling.flywheel.servedFromMemory` climb in context — that's free work.
- Reads only; writes always hit the host. Operators can disable it (`SPARDA_FLYWHEEL=off`).

**2. Circuit-breaker / quarantine — stop hammering a sick backend.**
After **3 consecutive 5xx** on a tool, SPARDA quarantines it: subsequent calls
return **HTTP 503** with `reason` and `retryInMs` *instead of* hitting the failing
host. Honor `retryInMs` — do not retry-loop. Check `runtime.quarantine` in context
before depending on a tool. After a cooldown (~60s) the tool half-opens for one
probe; one more 5xx re-quarantines it.

**3. Crystallized circuits (Labs) — collapse a chain into one tool.**
If you repeat a **GET→GET** sequence where one call's output feeds the next call's
argument **3 times** (and the operator enabled Labs recording), SPARDA mints a
single **composite tool** for that chain and announces it mid-session via
`tools/list_changed`. Prefer the composite over re-walking the steps — it's one
call and it's marked read-only. (Writes are never absorbed into a circuit.)

**4. Adaptive immunity — read the diagnosis before retrying.**
Repeated, unfamiliar failures trigger a *one-shot* LLM diagnosis that SPARDA caches
as an "antibody" (keyed by `source|tool|status`). Recurrences reuse the cached
diagnosis at zero cost. When an error event carries a diagnosis, **read it** and
adapt — don't blindly retry the same call.

**5. Latency anomalies.** A call far slower than a tool's own baseline surfaces as
an `immune` event in `/mcp/events`. Treat it as a hint to back off or warn the user.

**6. Twin Simulation Mode — practice safely on a clone.**
When `/mcp/stats` or `sparda_get_context.runtime` contains `"twin": true`, you are connected to a safe, in-memory mock clone of the application.
- All GET reads return learned exemplars (observed response shapes and mock values).
- All write tools return simulated `202` echoes but do not write to database or external APIs.
- Use this twin mode to practice multi-step workflows, debug tool sequences, and test your plans without touching the live production backend.

**7. Grammar & Evolution — discover optimal workflows.**
- You can query or contribute to the app's grammar (`.sparda/grammar.json`). The grammar maps valid sequences of tool calls (edges).
- Running `sparda evolve` mutates and runs candidate chains against the twin. The successful evolved sequences are suggested as mid-session workflows.

## Writing safely — the mandatory two-phase protocol

Writes are **disabled by default**. The protocol is not optional:

1. **No write tool listed?** Call `sparda_list_disabled_tools`. Tell the user how
   to enable it: set `"enabled": true` for that tool in `sparda.json`, re-run
   `sparda init`, and restart the bridge. Never try to bypass it.
2. **Calling an enabled write** under the default `require_human` policy returns
   **HTTP 202 `awaiting_confirmation`** — the host was **not** touched. The payload
   carries: `confirm` (a single-use token), `preview`, `instruction`, `expiresInMs`,
   and a `spardingProof` (SPARDA's safety verdict for this action).
3. **Inspect first.** Follow `preview.inspectFirst`: call the matching read tool and
   show the user the current state, so the confirmation is informed.
4. **Commit** by calling **`sparda_confirm`** with `{ "token": "<confirm>" }`. The
   token is single-use and expires (~120s). SPARDA then executes and, because of
   proof-after-write, **re-reads** the resource and returns a `proof` of the new
   state — surface that proof to the user.
5. Never fabricate or reuse a token; never loop a write. If the client supports MCP
   elicitation, SPARDA may also prompt the user directly before the write — let it.

## Read the dashboards to steer

- **`/mcp/stats`** (in `sparda_get_context.runtime`): per-tool `calls`/`errors`;
  `purity.class === 'pure'` marks a tool whose answers are flywheel-recyclable;
  `quarantine` lists tools to avoid right now. Use it to pick hot, healthy tools.
- **`/mcp/events`**: the error / latency / immune stream, delivered as MCP logging
  notifications with any cached diagnosis attached.

## Full-potential plays

1. **Resume cold** → `sparda_get_context`; read `runtime.quarantine`, immune memory,
   and `workflows` before touching anything.
2. **Inspect-before-write** → on a 202, call the same-path read tool, show state,
   then `sparda_confirm`.
3. **Crystallize then call** → repeat a GET→GET id-chain to mint a `[Labs circuit]`
   composite, then call the composite once instead of N times.
4. **Find hot / sick tools** → read `/mcp/stats`: prefer `purity: pure`, skip
   `quarantine`.
5. **Free repeated reads** → repeat a stable GET to trigger flywheel serves; watch
   `servedFromMemory` rise.
6. **Listen** → keep an eye on `/mcp/events`; act on immune diagnoses and latency
   flags instead of retrying blindly.

## Troubleshooting

- **Bridge won't start / "localKey" error** → `sparda.json` is missing its key;
  re-run `sparda init` (the key is preserved across re-inits).
- **A tool you expect is missing** → it's disabled (write-safety) or the route was
  removed; run `sparda sync` after route edits, or `sparda_list_disabled_tools`.
- **General health** → `sparda doctor` checks Node version, framework detection,
  manifest validity, the semantic/immune cache, host reachability, and quarantine;
  it exits non-zero so it can gate CI.
- **Formal Deployment Proof** → `sparda apocalypse` reads the compiled graph (`ubg.json`) and proves five correctness obligations: catches unguarded mutations, non-atomic aggregate writes, unvalidated writes to constrained tables, uncompensated observable effects, and aggregate root bypasses. Run `sparda apocalypse --save-baseline` to store the reference graph; subsequent runs diff against the baseline to catch dropped guards, dropped SQL invariants, or grown blast radiuses.
- **Safety Matrix Report** → `sparda dossier` generates an ultra-premium, self-contained HTML matrix of the app's safety proof, ideal for security engineers and audit compliance.
- **Deep Framework Resolution** → SPARDA natively traces multi-hop Dependency Injection in NestJS, external controllers in Express, and wrapped handlers in Next.js, mapping them into the final Behavior Graph.
- **OpenAPI Ingestion** → Run `sparda ubg --openapi <openapi_spec.json>` to compile any non-JS/Python backend (Go, Java, Rails, Laravel, .NET) into a Unified Behavior Graph by mapping security schemes into guards and request/response structures. (JSON specs only — convert YAML once with `npx -y js-yaml spec.yaml > spec.json`.)
- **Executing the Graph (No code mock)** → Run `sparda mirror` to host a mock HTTP simulation server directly from `ubg.json` without any backend code. Enforces authentication guards, returns typed responses, and acts as a contract sandbox.
- **Exporting OpenAPI 3.1 Spec** → Run `sparda openapi` to generate a valid, deterministic OpenAPI 3.1 spec dynamically from the compiled behavior graph.
- **Self-Verification** → Run `sparda verify` to test the compiler's own invariants (byte-determinism, soundness, and spec round-trip) to guarantee trust.
- **Time-Travel Debugging** → `sparda timeless` records a production request's nondeterminism (db, http, clock, random, uuid) and replays it byte-identically against current code. `sparda timeless replay <id>` re-flies it; `sparda timeless export <id>` turns the bug into a vitest test. Recording is opt-in in the app (deterministic sampling + GDPR redaction built in).
- **Self-Healing, Proven** → `sparda heal <id>` builds a fix brief from the graph, then `--check --expect '{"status":200}'` gates a candidate fix on three axes at once: the recorded flight now returns the expected response (not the bug), `verify` still passes, and `apocalypse` finds no new critical/high and no removed guard. The gate is honest both ways — an unfixed bug keeps it closed (exit 1).
- **Clone learning / Transfer sémantique** → Use `sparda seed export` to package your app's descriptions, workflows, and antibodies. Then `sparda seed import --germinate` in another clone to import the structure and germinate simulated twin instances.
- **Learn exemplars** → Start your live app and run `sparda twin --learn` to fetch actual response data and construct `.sparda/twin.json` locally.

---
*This skill ships with `sparda-mcp` and is regenerated from SPARDA's capability
surface each release, so it tracks new tools and behaviors. The **live, per-project**
tool list, stats, and workflows always come from `sparda_get_context` at runtime —
trust it over any static list.*