{
  "markdown": "<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.svg\">\n  <img alt=\"Instinct\" src=\"assets/logo.svg\" width=\"420\">\n</picture>\n\nEngineering judgment as a default instinct for AI coding agents — installed\nas ambient behavior, not a persona, a checklist, or a slash command you have\nto remember to invoke.\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-informational)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-91%20passing-success)](tests/)\n[![Status](https://img.shields.io/badge/status-pre--alpha-yellow)](docs/ROADMAP.md)\n[![Hosts](https://img.shields.io/badge/hosts-14-blue)](docs/installation.md)\n\n> Engineering is not writing code. Engineering is making good decisions.\n> Every line of existing code was somebody's answer to a question you\n> haven't asked yet.\n\n---\n\n## What this is\n\nMost coding assistants optimize for implementation: given a request, they\nbuild it. Instinct changes the default so that, before any code is written,\nClaude instinctively asks the questions a staff engineer asks without being\nprompted to — why does this code exist, is this actually the right fix, does\nan abstraction for this already exist, what's the smallest correct change.\n\nTwo compiled sentences carry the philosophy\n(see [`docs/rfcs/0001-charter.md`](docs/rfcs/0001-charter.md)):\n\n- **Identity** — Engineering is not writing code. Engineering is making good\n  decisions.\n- **Operational maxim** — Every line of existing code was somebody's answer\n  to a question you haven't asked yet.\n\nUnderneath them sits a mechanical procedure, not a vibe: a three-question\nGate, followed by two tiers of behavior once you're past it. It turns\nProvenance, Judgment, and Efficiency from named virtues into something\ncheckable — with explicit guardrails so \"judgment\" degrades toward neither\nnegligence (skipping it) nor contrarianism (applying it uniformly regardless\nof stakes).\n\n## The Gate\n\nThis is the entire mechanism. Everything else in this repository exists to\ndeliver it, verify it, or carry it to another host.\n\nAsk, **in order**, about the request in front of you. Answer by looking at\nwhat the change actually touches, not by trusting the request's phrasing.\n**Stop at the first yes. Treat an unclear answer as yes.**\n\n```\n1. Does this touch anything beyond what was explicitly named?\n2. Does it have more than one consumer — another caller, another\n   service, another person who reads this as an interface rather\n   than an implementation detail?\n3. Is it expensive to undo — already shipped, crosses a trust\n   boundary (auth, payment, deletion, data access), or needs\n   someone else's coordinated follow-up to reverse?\n\n   no · no · no  →  implement directly, nothing else applies\n   yes to Q1/Q2  →  Consequential  (reuse-check, minimal diff, state why)\n   yes to Q3     →  Critical       (reconstruct why, name the alternative,\n                                     deposit the reasoning somewhere durable)\n```\n\nTwo carve-outs exist specifically because real evaluation caught the Gate\nover-escalating for the wrong reason, and both are load-bearing, not\ndecorative: a **public or heavily-used surface isn't automatically a yes to\nQ2** (a signup form having many users isn't the same as another piece of\ncode depending on it as an interface), and a **sensitive-sounding surface\nisn't automatically a yes to Q3** (tightening validation with no required\ncaller changes is usually a no, even on a security-adjacent surface — but a\nnew *required* parameter is a yes regardless of how additive it sounds). The\nfull text, with the rest of the tier obligations, `Bug fixes`, `Never`, and\n`Scope` sections, lives in [`skills/instinct/SKILL.md`](skills/instinct/SKILL.md) —\nthat file is the actual artifact; everything above is a summary of it.\n\n## The Gate in action\n\n> \"Add a required tenantId parameter to the public createUser API, used at 12 call sites.\"\n\nRead as a request, this sounds additive — nothing removed, just one more\nfield. Read through the Gate:\n\n- **Q1** (touches beyond what's named)? Yes — all 12 call sites now have to\n  pass a value they didn't before.\n- **Q2** (more than one consumer)? Yes.\n- **Q3** (expensive to undo)? Yes — a *required* parameter breaks every\n  existing caller simultaneously the moment it ships. \"Adds a parameter\"\n  doesn't make that safe.\n\n**Critical.** Reconstruct why `createUser` doesn't already scope by tenant,\nstate the alternative once (an optional parameter defaulting to the\ncaller's own tenant, say), then implement whichever the requester confirms.\n\nThis is this project's own canonical Critical-tier example\n(`gt-03` in [`eval/corpus/gate_tier.yaml`](eval/corpus/gate_tier.yaml)) —\nand also the one real bug this evaluation found and fixed *twice*: a fresh\nmodel talked itself out of escalating it by leaning on the word \"additive,\"\nbefore the Gate's own wording was corrected to name the actual test (\"does\nan existing caller have to change anything\"). It now lands Critical on\n**11/11** independent fresh-Claude samples, unanimous. Full history:\n[`docs/known-failure-modes.md`](docs/known-failure-modes.md).\n\n## What this is not\n\n- A prompt pack of style instructions.\n- A collection of workflow macros.\n- A \"senior engineer\" persona or tone change.\n- A code-size minimizer — see\n  [Ponytail](https://github.com/DietrichGebert/ponytail) for that, which\n  this project is designed to compose with, not replace. Ponytail asks\n  \"is this the smallest correct version\"; Instinct asks \"is this the right\n  change and how much scrutiny does it deserve\" — a layer earlier.\n- A way to make Claude slower or more argumentative on every request.\n  Proportional to stakes is a hard constraint, not a suggestion — the fast\n  exit (no to all three questions) is deliberately as cheap as the Gate\n  itself.\n\n## The skill family\n\n| Skill | Invocation | What it does |\n|---|---|---|\n| `instinct` | ambient | The Gate itself — applies before a change is made. |\n| `instinct-review` | explicit | Audits one already-made diff against the Gate. |\n| `instinct-audit` | explicit | The same question at repo/history scale: did recent Critical-tier-shaped commits actually leave the provenance the Gate obligates? |\n| `instinct-debt` | explicit | Harvests `instinct:` accepted-limitation markers into a ledger, so a scoped-for-now tradeoff can't quietly become permanent. |\n| `instinct-help` | explicit | One-screen quick reference — the Gate, the tiers, without re-reading `SKILL.md` or the RFCs. |\n\nDeliberately missing two things a Ponytail-inspired reader might expect: no\nuser-selectable intensity modes (`/instinct lite|full|ultra`), and no\n`instinct-gain` scoreboard — see [`docs/ROADMAP.md`](docs/ROADMAP.md) for\nwhy both were considered and rejected rather than silently never brought up.\n\n## Where it runs\n\nDistributed to **14 hosts** across two delivery mechanisms, kept in sync\nautomatically rather than hand-maintained:\n\n**7 file-based hosts** read `AGENTS.md` (the canonical consolidated body) or\na thin per-host copy of it — Claude Code, Cursor, Windsurf, Kiro, Cline,\nGitHub Copilot, Qoder. `scripts/check_adapters.py` proves every copy stays\nbyte-identical to `skills/instinct/SKILL.md`, not just once but on every\nchange — and has itself been tested to actually catch injected drift, not\njust pass when nothing's wrong.\n\n**7 plugin-tier hosts** get real manifests and lifecycle hooks — Claude\nCode (`.claude-plugin/`), Codex, GitHub Copilot CLI, Qoder, Gemini CLI,\nOpenCode, the pi editor, and Hermes Agent — plus an MCP server\n(`instinct-mcp/`) for any host with no file-based rule mechanism and no hook\nlifecycle to piggyback on.\n\nEvery one of these has been verified by actually running it — not just\nwritten and assumed correct. That includes installing the real Claude Code\nplugin with the `claude` CLI, which caught a genuine load-failure bug\n(`hooks/hooks.json` declared both explicitly and via auto-discovery, a hard\nconflict) that had gone unnoticed because nobody had actually installed it\nbefore. See [`docs/installation.md`](docs/installation.md) for exactly what's\n**confirmed** (actually run, output inspected) versus **inferred** (follows\nfrom a documented contract, not run against real host software from this\nenvironment) for every host — that distinction is maintained deliberately,\nnot glossed over.\n\n## Evidence\n\nInstinct doesn't have Ponytail's kind of number — there's no LOC/cost/time\nbenchmark suite behind it, and building one just to have a chart would be\nexactly the fabricated-looking-metrics theater this project argues\nagainst elsewhere (see `docs/ROADMAP.md`'s call on why there's no\n`instinct-gain` skill). What it has instead is real, individually-verified\nevaluation evidence — every row below is something that was actually run,\nnot projected:\n\n| What was tested | Result | Where |\n|---|---|---|\n| Trigger accuracy — does the skill correctly fire or skip | **10/10** on two independent fresh-Claude samples (20/20 total) | [`docs/known-failure-modes.md`](docs/known-failure-modes.md) |\n| Canonical breaking-change example (`gt-03`, above) | **11/11** unanimous, Critical tier | [`docs/rfcs/0011`](docs/rfcs/0011-gt03-resolution.md) |\n| Q2 wording fix (`gt-07`) | **3/3** clean after the fix — meets this project's own N≥3 confirmation standard | [`docs/known-failure-modes.md`](docs/known-failure-modes.md) |\n| Real-repo pilot, 3 tasks, baseline vs. Instinct-loaded | Instinct-loaded added a verification step baseline skipped **in all 3**; caught a real CSV-injection vulnerability baseline missed entirely | [`docs/rfcs/0013`](docs/rfcs/0013-real-repo-pilot.md) |\n| Claude Code plugin installability | Confirmed by actually installing it with the real `claude` CLI — found and fixed a load-breaking bug in the process that nobody had caught, because nobody had actually installed it before | [`docs/installation.md`](docs/installation.md) |\n| Full test suite | **91/91** passing (85 Python + 6 Node), including tests that prove the checkers themselves catch injected drift, not just pass when nothing's wrong | [`tests/`](tests/) |\n\nThree real bugs found and fixed via evaluation this way, not hypothesized\n— each one confirmed on fresh model samples *after* the fix, not just\npatched and assumed correct.\n\n**The honest gap, stated here rather than only in `docs/ROADMAP.md`**:\nthis is real evidence, not a properly-powered evaluation program. The\ncorpus is 21 hand-labeled scenarios, not hundreds; the pilots are 1 and 3\ntasks, not dozens. A judgment regression suite\n([`eval/run.py`](eval/run.py)) is wired into CI and ready to run\nautomatically the moment a real `ANTHROPIC_API_KEY` is available — it\nisn't yet, so it skips cleanly today rather than pretending to run.\n\n## Installation\n\nSee [`docs/installation.md`](docs/installation.md) for exact steps per host,\neach one marked confirmed or inferred. Quick version for Claude Code:\n\n```bash\nclaude plugin marketplace add /path/to/this/checkout\nclaude plugin install instinct@instinct\n```\n\nInstalls at user scope by default, applying the ambient Gate to every\nproject on the machine — pass `-s project` to scope it to one repo instead.\n\n## Project structure\n\n```\nskills/\n  instinct/            the Gate itself — SKILL.md, Claude Code-native\n  instinct-review/      audit an already-made diff against the Gate\n  instinct-audit/       the same question at repo/history scale\n  instinct-debt/        harvest instinct: accepted-limitation markers\n  instinct-help/        quick reference — explicit invocation, not ambient\nAGENTS.md              canonical instruction-tier body — Critical-tier\n                       detail consolidated (inlined), not pointed to,\n                       for hosts with no matching step (RFC-0007)\n.cursor/ .windsurf/ .kiro/ .clinerules/ .qoder/ .github/copilot-instructions.md\n                       thin per-host copies of AGENTS.md, generated (not\n                       hand-typed) by scripts/generate_adapters.py\n.claude-plugin/ .codex-plugin/ .qoder-plugin/ .github/plugin/\n                       plugin-tier manifests (RFC-0007 Phase 1/3)\ngemini-extension.json  points Gemini CLI at AGENTS.md\nopencode.json          points OpenCode at .opencode/plugins/instinct.mjs\nplugin.yaml + __init__.py\n                       Hermes Agent plugin (root-level, per Hermes convention)\nhooks/                 SessionStart/SubagentStart (Claude Code, Codex),\n                       Copilot- and Qoder-specific equivalents, shared\n                       SKILL.md-reading logic (hooks/lib.js)\ninstinct-mcp/          MCP server (prompt + tool) for hosts with no\n                       file-based rule mechanism — its own npm package\n.opencode/plugins/     OpenCode server plugin\npi-extension/          pi editor extension\nreferences/            detail SKILL.md defers to when a Critical-tier\n                       request actually needs it\nscripts/\n  check_adapters.py    sync checker — all adapters vs. SKILL.md\n  check_versions.py    every host manifest's version field must agree\n  generate_adapters.py regenerates the plain-markdown adapters from AGENTS.md\n  test_all.py          runs the entire suite in one local command\ntests/                 pytest suite for the tooling itself (85 tests),\n                       plus instinct-mcp/test/ and pi-extension/test/\n                       (6 more, Node) — 91 total\neval/\n  corpus/              labeled scenarios (RFC-0005) — what \"correct\" means,\n                       locked before SKILL.md was written (ADR-0009)\n  run.py               the corpus runner — stub, real Anthropic, and\n                       OpenAI-compatible backends\ndocs/\n  rfcs/                design proposals — the \"what and why\"\n  adrs/                point-in-time decisions and the alternatives that lost\n  installation.md      per-host setup, confirmed vs. inferred\n  known-failure-modes.md  specific scenarios that have actually fooled\n                       real models, with dates, models, and fixes\n  ROADMAP.md           the live task list — what's done, open, and why\n```\n\n## Reading order\n\nDesign, in dependency order: `docs/rfcs/0001` (charter) →\n`docs/rfcs/0002` (prompt architecture) → `docs/rfcs/0003` (mechanism\ndesign) → `docs/rfcs/0004` (evaluation methodology) → `docs/rfcs/0005`\n(testing strategy) → `docs/rfcs/0006` (v1 dry-run notes, superseded — read\n`docs/adrs/0011-ponytail-informed-hardening.md` right after it) →\n`docs/rfcs/0008` (first independent evaluation — a real bug, found and\nfixed) → `docs/rfcs/0009` (first full-corpus run against a live external\nmodel — mostly a lesson about that backend's reliability, but one\nunresolved real signal survived it) → `docs/rfcs/0010` (repeat sampling\nturns that signal into a confirmed bug, and finds a second bug hiding in\nthe first fix's own wording — read this one for the sharpest example in\nthe whole project of why a single test pass isn't evidence) →\n`docs/rfcs/0011` (the fix confirmed, this time at N=10 instead of N=1 or\nN=3) → `docs/rfcs/0007` (multi-platform distribution), preceded by\n`docs/adrs/0012-defer-platform-adapters-pending-rfc.md`, which explains why\nthat RFC exists instead of a batch of adapter files. Each RFC's `Depends\non` / `Blocks` header lines say why that order, and each has one or more\nADRs immediately after it in `docs/adrs/` covering the sharpest calls\ninside it — read the RFC first, the ADRs are the \"why not the obvious\nalternative\" footnotes, not prerequisites.\n\nIf you just want the artifact itself rather than the reasoning behind it:\n[`skills/instinct/SKILL.md`](skills/instinct/SKILL.md), then `references/`\nonly if a Critical-tier example doesn't make sense on its own.\n\n## Landing page\n\n[`site/index.html`](site/index.html) is a single self-contained static\npage (zero build step — deploy the repo to Vercel as-is, `vercel.json`\npoints it at `site/`). It carries the same content and the same honesty\nrule as this README: every install command is labeled **confirmed**\n(actually run against real host software) or **inferred**, and there's no\nfabricated benchmark chart — the \"Evidence\" section is the same real,\nindividually-verified data as above, not a marketing number invented to\nmatch Ponytail's.\n\n## Contributing\n\nThis project holds itself to one standard throughout its own history: every\n\"sync,\" \"verification,\" or \"confirmed\" claim has actually been run,\nincluding proving the negative case (a checker is tested to confirm it\n*catches* drift, not just that it passes when nothing's wrong). Read\n[`CLAUDE.md`](CLAUDE.md) for the working norms this repo has accumulated\nbefore assuming something is undecided — it's written for exactly that\npurpose.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n",
  "bytes": 16653,
  "sha": "a3b5d79ad21a97de7fc29af59ba5c55c52d8a333eb23db9a56bee11a7fbeb389",
  "repo_slug": "bhouvana/instinct",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_bhouvana_instinct_b4c9b8b7/readme"
}