Related Pages

Related topics: The 10 MCP Tools, Corpus: Skills, Community Scars & Personal Scar Storage, Privacy, Telemetry & the Improvement Flywheel

Introduction to Kira & The Scar Loop

What Kira Is

Kira is an MCP (Model Context Protocol) server that delivers curated, failure-aware guidance to AI coding agents. It exposes a small set of tools that let an agent locate the right Skill for a goal, fetch its instructions, and consult the Scars — sanitized failure lessons — that have been recorded against that path.

As of v0.8.2 the corpus contains 38 skills / 27 scars, harvested from real release-night races, web-platform traps, and ffmpeg pitfalls. Source: README.md:1-50

The product contract is "one MCP install": register the server once and the host agent gains access to skill routing, scar lookup, and the failure-recording surface without bespoke glue code. Source: USAGE.md:1-40

Skills vs. Scars

The corpus is split into two complementary artifact types:

• Skills — procedural playbooks for a goal (e.g. "deploy to Cloudflare Workers", "set up Drizzle with Vitest"). They tell the agent *how* to approach a task.
• Scars — short, sanitized failure lessons ("crop w/h expressions evaluate once", "infinite lavfi source + output-side -t hang"). They tell the agent *what not to repeat*.

Each scar is shaped to be agent-readable, free of personal data, and linked back to the skill or topic it constrains. Source: DESIGN.md:1-80

The Scar Loop

The Scar Loop is the closed feedback cycle that turns isolated failures into a shared failure memory. It has four legs, delivered as MCP tools.

flowchart LR
    A[Agent fails or retries] --> B[kira_record_failure]
    B --> C[Personal scar on disk]
    C --> D[kira_premortem]
    D --> E[Agent avoids repeat]

Related Pages

Related topics: Introduction to Kira & The Scar Loop, Corpus: Skills, Community Scars & Personal Scar Storage, Privacy, Telemetry & the Improvement Flywheel

The 10 MCP Tools

Kira exposes its entire surface area to a host agent (Claude Code, Cursor, etc.) through exactly ten MCP tools. They split into two cohorts: six community-facing tools that operate over the published skill/scars corpus, and four personal-scar tools (F1–F4) that close the local failure-memory loop introduced in v0.7.0 and v0.8.0. Source: src/server.ts.

Cohort 1 — The Six Community Tools

The first six tools were the original surface and shipped with annotations in v0.6.0. They read the bundled corpus, route queries, fetch skill bodies, report outcomes, manage telemetry consent, and report server health.

kira_report was the first tool to be reworked behind a privacy gate: prior to v0.5.0 it wrote to a local log, and the v0.5.0 release replaced that with a Cloudflare Worker backend so the flywheel could close only if users trusted the pipe. Source: src/tools/report.ts. The annotation vocabulary (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) was added across the whole cohort in v0.6.0 and follows the Anthropic *Tool Annotations as Risk Vocabulary* post. Source: src/tools/kira_status.ts.

Cohort 2 — The Four Personal-Scar Tools (F1–F4)

These four tools implement a private, on-disk failure memory rooted at ~/.kira/personal-scars/. Nothing they produce leaves the machine unless the human explicitly runs the F4 step.

• F1 — kira_record_failure captures a retry or exception as a personal scar (private, local-only). Source: src/tools/record-failure.ts.
• F2 — kira_personal_brief runs at SessionStart and surfaces a brief grounded in the user's accumulated personal scars. Source: src/tools/personal-brief.ts.
• F3 — kira_premortem produces a failure heat-map for a goal *before* the agent starts, ranked by past scar hits. Source: src/tools/premortem.ts.
• F4 — kira_share_scar is the promotion step: it re-sanitizes a personal scar, generalizes it to the community shape, and returns a prefilled GitHub issue URL plus a gh CLI fallback. The tool itself uploads nothing — submitting remains an explicit human act. Source: src/tools/share-scar.ts.

The four tools are intentionally ordered F1→F2→F3→F4 along a learn→brief→forecast→publish loop. v0.7.0 shipped F1, F2, F3; v0.8.0 added F4 as the 10th tool and unblocked community intake via the scar-submission issue form. Source: src/server.ts.

flowchart LR
  A[Agent retry / exception] -->|F1 kira_record_failure| B[~/.kira/personal-scars/]
  B -->|F2 kira_personal_brief| C[SessionStart brief]
  B -->|F3 kira_premortem| D[Failure heat-map]
  D -->|F4 kira_share_scar| E[Prefilled GH issue URL]
  E -->|human submits| F[Community scar corpus]
  F -->|kira_lookup / kira_route| A

Annotations, Consent, and the Flywheel Boundary

Every one of the ten tools carries the v0.6.0 annotation set so a host can render an accurate risk card before invocation. Read-only and idempotent tools (kira_lookup, kira_route, kira_get, kira_status, kira_consent on read) are safe to call speculatively; kira_report is the only tool that crosses the open-world boundary, and even it is gated by the bit kira_consent flips. Source: src/tools/kira_consent.ts.

The boundary is deliberate. The personal-scar tools (F1–F4) operate entirely under ~/.kira/ and never touch the worker, so the local failure memory stays usable even with telemetry off. The community tools (1–6) read the bundled corpus freely but only kira_report writes back, and only when consent is on. That split is what lets Kira stay useful offline *and* let the flywheel spin when the user opts in. Source: src/tools/report.ts, src/tools/share-scar.ts.

Operational Notes

• Corpus shape at v0.8.2: 38 skills / 27 scars, all served by the six community tools. Source: src/tools/lookup.ts.
• Adding the 11th tool is a breaking change for hosts that pin the tool list; F4 was added in v0.8.0 precisely because the loop was incomplete without it. Source: src/server.ts.
• Docker handshake gate added in v0.8.2 applies to the server process that registers these ten tools, not to the tool surface itself. Source: src/server.ts.

The ten tools are intentionally a closed set: the v0.6.0 annotation work and the v0.7.0→v0.8.0 personal-scar arc were designed to make this number a stable contract for host integrations while the corpus behind it keeps growing.

Related Pages

Related topics: The 10 MCP Tools, Privacy, Telemetry & the Improvement Flywheel

Corpus: Skills, Community Scars & Personal Scar Storage

Kira ships a curated, versioned knowledge corpus that combines reusable Skills (canonical "do it right" instructions for a target), Community Scars (real-world "don't do this" failure modes), and Personal Scar Storage (a private, local-only failure journal). The corpus is the data layer that the MCP server's kira_lookup, kira_route, kira_get, and kira_premortem tools read from; the four scar-loop tools (kira_record_failure, kira_personal_brief, kira_premortem, kira_share_scar) write into or promote out of it. As of v0.8.2 the corpus contains 38 skills / 27 scars, harvested from the maintainer's release nights and from community issues (#164, #172, #173).

Taxonomy and On-Disk Layout

The corpus is split into two communities under skills/:

• skills/community/* — success-oriented setup guides (e.g. setup-vercel-nextjs.json, setup-supabase-nextjs.json). Each entry describes the deterministic steps to scaffold a working integration.
• skills/scars/* — failure-oriented scars (e.g. prisma-generate-forgotten.json, stripe-webhook-body-parsed.json, supabase-rls-not-enabled.json, authjs-v5-signin-wrong-import.json). Each entry captures a symptom, root cause, and corrective check.

Source: skills/community/setup-vercel-nextjs.json:1-1, skills/scars/prisma-generate-forgotten.json:1-1, skills/scars/stripe-webhook-body-parsed.json:1-1.

A third, separate tier lives outside the repo: Personal Scar Storage, a private directory at ~/.kira/personal-scars/ introduced in v0.7.0. It is local-only and never uploaded unless the user explicitly promotes an entry via kira_share_scar.

The Scar Submission & Personal Loop

The four scar-loop tools (F1–F4) close the loop from private failure → public scar:

The scar-submission intake uses an issue form at .github/ISSUE_TEMPLATE/scar-submission.yml so that community scars arrive in a pre-shaped YAML the maintainer can review without re-parsing free text. Source: skills/community/setup-supabase-nextjs.json:1-1, skills/scars/supabase-rls-not-enabled.json:1-1.

Search Semantics and Result Quality

Search across the corpus is tiered; v0.4.0 hardened the lowest tier to stop false positives:

• Tier 3 word-overlap now requires 2+ meaningful word matches (was 1). Consequently "react native" no longer returns react-email or zod-validation, and "deploy to mars" correctly returns 0 results.
• 0-result fallback returns nearest neighbors instead of silent empty output — an explicit "did you mean?" affordance before an agent commits to the wrong skill.

The corpus is also pre-bundled for offline use, so a single npx kira or Docker install yields a working knowledge base with no network round-trip on first call.

Personal Scar Storage Discipline

Because Personal Scar Storage is on the developer's own filesystem, it inherits one design discipline: the privacy boundary is the filesystem, not the schema. kira_record_failure never sends its output anywhere; kira_share_scar is the only sanctioned egress path, and even it produces a draft URL rather than a network call. This keeps "I tripped on X" shareable while making "let me vent about my employer's auth code" non-shareable by default. Promoted scars go through re-sanitization (the personal naming is dropped, the pattern is generalized) before the URL is produced.

Corpus Growth and the Flywheel

The corpus is grown the same way it is consumed: by harvesting scars from real failures. Each release since v0.8.0 has added a corpus delta in its changelog:

• v0.8.2 — 7 community scars: the parallel-rails release race (#164), 3 web-platform traps from bbutton-site (#172), 3 ffmpeg pitfalls — crop w/h expression once-only evaluation, animated-testsrc frame-diff false positives, infinite lavfi source + output-side -t hang (#173).
• v0.8.1 — 5 scars + 4 process skills from the repo's own release night (piped-gate, push-race, write-without-read, merge-compile-gate, UTC-misread, npm-404-is-auth, nested-package-install, credential-CI three gates, and skills cut-a-release, delegate-to-subagents, npm-trusted-publishing).
• v0.8.0 — added the kira_share_scar tool and the scar-submission intake.
• v0.7.0 — closed the personal-scar loop with the F1/F2/F3 tools.
• v0.6.0 — added MCP tool annotations across the read tools and prepped registry publication.
• v0.5.0 — privacy-first telemetry + Cloudflare Worker backend, so kira_report no longer writes to a local log when the user opts in.
• v0.4.0 — search-quality overhaul + 31 skills.

flowchart LR
  A[Personal run<br/>exception] -->|kira_record_failure F1| B[~/.kira/personal-scars/]
  B -->|SessionStart| C[kira_personal_brief F2]
  B -->|pre-task| D[kira_premortem F3]
  D --> E[skills/scars/*<br/>community scars]
  E --> F[kira_share_scar F4<br/>re-sanitize + generalize]
  F -->|returns prefilled GitHub URL<br/>human runs gh| G[Issue form scar-submission.yml]
  G --> H[skills/scars/*<br/>next release delta]

Practical Implications

For users of the corpus:

1. Skills are authoritative setup recipes. A community skill (e.g. setup-vercel-nextjs.json) is meant to be applied verbatim for the first attempt; deviations should be justified.
2. Community scars are advisory. prisma-generate-forgotten.json, stripe-webhook-body-parsed.json, supabase-rls-not-enabled.json, and authjs-v5-signin-wrong-import.json each encode a single checked mistake; kira_premortem ranks them by past hit count for the active goal.
3. Personal scars are the user's, not the project's. Promotion is opt-in, explicit, and mediated by kira_share_scar.
4. The corpus is versioned with the release. A v0.8.2 install sees a 38/27 corpus; upstreaming a scar lands it in the next minor.

The corpus is therefore both the input to every Kira tool and the output of every scar-eligible failure — the closed loop the project is designed around.

Related Pages

Related topics: Introduction to Kira & The Scar Loop, Corpus: Skills, Community Scars & Personal Scar Storage

Privacy, Telemetry & the Improvement Flywheel

What the Flywheel Is and Why It Exists

Kira is built around an explicit feedback loop: agents consume Skills, apply them to real work, and report outcomes back so the index can improve over time. The repository documents this contract as the Improvement Flywheel — a cycle of *apply → report → index → serve better results next time* that only spins when contributors trust the data pipe enough to leave it on.

The flywheel is not a side feature. It is the engine that converts every successful (or failed) agent invocation into a calibration signal for ranking, scar harvest, and skill quality. Without it, the corpus would freeze at release time. The framing is laid out in FLYWHEEL.md and reinforced in RECIPROCITY.md, which describe the give-and-take between local users and the shared index.

flowchart LR
    A[Agent applies Skill] --> B[kira_report outcome]
    B --> C{User consented?}
    C -- No --> D[Local-only log]
    C -- Yes --> E[Cloudflare Worker ingest]
    E --> F[Aggregate + rank]
    F --> G[Improved Skill index]
    G --> A
    D -.opt-in upgrade.-> C

The diagram captures the three-state outcome of kira_report: the call always lands locally, but only crosses the network boundary when the user has explicitly opted in.

Source: FLYWHEEL.md:1-40 · RECIPROCITY.md:1-30

Privacy-First Telemetry (Phase A, v0.5.0)

Before v0.5.0, kira_report wrote to a local file only — useful for debugging, useless for collective learning. Phase A replaced that with a privacy-first Cloudflare Worker backend, but kept the same local-first guarantee as the default. The principle documented in PRIVACY.md is that telemetry must never become a liability the user did not sign up for.

Concretely, the telemetry surface is bounded:

• What is collected: aggregate skill-id, outcome class (success / scar), hashed environment fingerprint, and a coarse timestamp. No prompt bodies, no file contents, no credential material. Source: src/telemetry.ts:1-80
• What is never collected: source code, environment variables, secrets, user identifiers beyond a rotating anonymous ID. Source: PRIVACY.md:20-65
• Where it lives: Cloudflare Worker edge ingest with KV-backed aggregation; no third-party analytics SDK is loaded. Source: SECURITY.md:10-45

The "trust the pipe" framing from the release notes is operationalised here: the wire format is small, scrubbed, and reviewed. The default state is off — the user must opt in before any record crosses the edge.

Source: PRIVACY.md:1-90 · SECURITY.md:1-60 · src/telemetry.ts:1-120

Consent, Tool Annotations & User Control

Consent is a first-class tool, not a config flag. kira_consent lets an agent (or a human via the MCP client) inspect current state, grant telemetry, or revoke it. The companion kira_status tool surfaces the effective mode at any moment, which is critical for SessionStart hooks where the agent must know whether kira_report will actually transmit.

In v0.6.0 every Kira tool received MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). These annotations are the agent-visible contract that kira_consent is *not* destructive, kira_report is idempotent, and kira_share_scar (added in v0.8.0) opens an external world link only when the user explicitly invokes it. Source: src/tools/consent.ts:1-60

The personal-scar loop introduced in v0.7.0 stays strictly local: kira_record_failure writes to ~/.kira/personal-scars/ and never leaves the machine. kira_share_scar re-sanitises, generalises to the community scar shape, and returns a prefilled GitHub issue URL plus an gh fallback — the tool itself uploads nothing; submitting remains an explicit human act. This two-stage design (local → explicit human submission) is the same trust model as telemetry, applied to qualitative scar data.

Source: src/tools/report.ts:1-90 · src/tools/consent.ts:1-70 · src/tools/share-scar.ts:1-110

Local Defaults, Collective Upside

The design has a deliberate asymmetry: the local path is always available, the collective path is opt-in. Personal scars, premortem briefs, and recorded failures work without any network access. Only the aggregate outcome signal — the smallest possible payload — requires consent. This means a user can get full personal-loop value (F1 record, F2 brief, F3 premortem from v0.7.0) with telemetry permanently disabled, and still benefit from corpus improvements released by others.

The reciprocal half — RECIPROCITY.md — makes the social contract explicit: those who opt in fuel the flywheel that improves results for everyone, including those who don't. Versioned releases (v0.5.0 through v0.8.2) show the flywheel accelerating: the corpus reached 38 skills / 27 scars by v0.8.2, harvested from community-sourced scars (#164, #172, #173). Without telemetry opt-ins, that growth rate would not be sustainable.

For operators, the practical guidance is short: read PRIVACY.md before enabling, use kira_status to verify state, and treat kira_consent as the canonical toggle. The system is designed so that the safest answer — local-only — is also the default.

Source: FLYWHEEL.md:40-90 · RECIPROCITY.md:30-70 · PRIVACY.md:65-110

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/aibenyclaude-coder/Kira

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/aibenyclaude-coder/Kira

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/aibenyclaude-coder/Kira

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/aibenyclaude-coder/Kira

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/aibenyclaude-coder/Kira

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/aibenyclaude-coder/Kira

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/aibenyclaude-coder/Kira