{ "markdown": "# ai-registry\n\nAn **AI development registry**: the knowledge, skills, practices and shared memory an\norganization's agents run from, kept in git, owned by the organization, and reviewed like\ncode.\n\nStart with the [workflow selection guide](docs/skill-selection.md) to use the library,\n[CONTRIBUTING.md](CONTRIBUTING.md) to change it, or the\n[RKB profile](docs/rkb-profile.md) for the format every knowledge bundle is gated\nagainst. [AGENTS.md](AGENTS.md) gives agents a concise entry point. Use the [installation guide](docs/installations.md)\nto select a harness and a live development or pinned release installation.\n\nThe repository carries eight lanes, declared in [`registry.yaml`](registry.yaml):\n\n| Lane | Holds | Status |\n| --- | --- | --- |\n| [`knowledge/`](knowledge/README.md) | **Reference Knowledge Bundles** - four-layer domain knowledge (Golden Path → Technique → Application → Evidence), one bundle per domain. | Real content. Gated by CI. |\n| [`skills/`](docs/skills-lane.md) | The fleet's shared skill library, one directory per skill, published as a **plugin marketplace** for the reference harness. | Real content; current inventory in catalog.json. Gated by CI. |\n| [`recipes/`](recipes/README.md) | **Craftsman knowledge** - one kind of work done well, connector- and trigger-agnostic, versioned like a skill. Everything that binds a recipe to one installation lives on the adopted charter, never here. | Real content, all ten domains. Gated by CI. Declared 2026-09-06 with one worked example; the corpus migrated after operator approval and grows by assay. |\n| `practices/` | Repo-level habits plus the starter artifacts they drop. | Templates and reusable practices; inspect each adoption contract. |\n| `memory/` | Organizational memory notes, one fact per file. | Examples and dated observations; inspect scope and confidence. |\n| [`usage/`](docs/usage-lane.md) | Which skills actually get used - counts contributed by the installations that run them, one file per contributor. | Real, gated. First contributor reporting. |\n| [`signals/`](docs/signals-lane.md) | Whether the knowledge is still TRUE where it is used - stack versions, citation-resolution verdicts, deviations and consults, one file per contributor. | Real, gated. First contributor reporting (stack only, so far). |\n| [`librarian/`](librarian/index.md) | Coverage memory for the maintenance loop - what was swept when, what was dispatched, what external sources were mined, and what was declined and why. | Real. Seeded by the founding sweep. |\n\nThe practices and memory lanes include worked examples and subsequently added material.\nRead each artifact's scope and provenance before treating it as an adopted policy.\n\nLane depth is declared, not incidental. `knowledge/` and `recipes/` are `depth: nested` and cap\nevery level at ten folders, because their consumers read a GENERATED index rather than walking\nthe tree; `skills/`, `practices/`, `memory/`, `usage/` and `signals/` are `depth: fixed`\nbecause a consumer's indexer selects their artifacts by exact path length - a category folder\nthere would not error, it would make every artifact silently vanish from the index.\n\n## Why a repository\n\nAgent instructions are code that runs against your codebase. They deserve the same treatment as\ncode: version control, review, an owner, and history.\n\n- **Git is the door for content.** Every change to a skill, a practice or a memory note arrives as\n a pull request. Merging is adopting - see [`CODEOWNERS`](CODEOWNERS).\n- **Reading the library needs no account.** A developer with `git` and a text editor is a first-class\n citizen. Clone it, read it, copy what you need.\n- **Indexing is read-only.** A tool (here, [Ascent](.ascent/registry.yaml)) reads the tree, parses\n the frontmatter, and keeps an index. It is never in the write path.\n\n## Layout\n\n```\nREADME.md\nregistry.yaml # what this repository IS: its lanes, their specs and guarantees\n.ascent/registry.yaml # Ascent's overlay: how ONE consumer indexes it (mode, telemetry, policies)\n.claude-plugin/marketplace.json # GENERATED: the skills lane as a plugin marketplace, one plugin per skill\n.claude/skills/ # the skills that maintain THIS registry: /forge /deepen /librarian /intake\nCODEOWNERS # who merges = who adopts\ncatalog.json # GENERATED index: skills, practices, memory, bundles, hashes, adopters, counts\ndocs/rkb-profile.md # the knowledge lane's format spec (an OKF profile)\ndocs/skills-lane.md # the skills lane's format spec: shape, sub-resources, versions, distribution, resolution\ndocs/recipes-lane.md # the recipes lane's format spec: the v3 object, the rendered view, versions, dual improvement\ndocs/usage-lane.md # the usage lane's format spec + what may never go in it\ndocs/signals-lane.md # the signals lane's format spec: verdicts, never pointers\ndocs/reconcile-brief.md # the external-reconcile lane's contract, and how it extends past repositories\nscripts/gate.mjs # runs the gate chain CI enforces, in CI order: --all, or --lane \nscripts/check-bundles.mjs # the knowledge lane's gate (zero dependencies)\nscripts/check-skills.mjs # the skills lane's gate: shape, sub-resources, the version-bump rule\nscripts/check-recipes.mjs # the recipes lane's gate: the v3 object, the rendered view's coupling, depth, the version-bump rule\nscripts/build-recipes-index.mjs # GENERATES recipes/index.json (--check in CI)\nscripts/apply-skill-clauses.mjs # stamps the shared Skill Reflection / Knowledge sync clauses from docs/skill-clauses/ (--check in CI)\nscripts/check-usage.mjs # the usage lane's gate: shape + the counts-only privacy rule\nscripts/check-signals.mjs # the signals lane's gate: shape + the same privacy rule\nscripts/check-currency.mjs# REPORTS how old the knowledge is; never fails a build\nscripts/librarian-scan.mjs# REPORTS the maintenance scorecard; the instrument /librarian reads\nscripts/research-ingest.mjs# normalizes an external source into an auditable transcript (/intake)\nscripts/research-map.mjs # maps a claim's terms onto existing subjects: prior art, and where new goes\nscripts/apply-taxonomy.mjs# the ONLY thing allowed to move a subject (moves + rewrites links)\nscripts/lib/taxonomy.mjs # the shared slug -> path resolver; nothing else may build a subject path\nscripts/lib/skills-lane.mjs # the ONE reader of the skills lane: frontmatter, digest, lessons, sub-resources\nscripts/lib/fleet.mjs # the shared bulk-model dispatcher: retry, budget and model rotation\nscripts/experiments/fleet-use-when.mjs # proposes the missing use_when lines, then applies the reviewed ones\nscripts/build-index.mjs # regenerates knowledge//index.json (--check in CI)\nscripts/build-catalog.mjs # regenerates catalog.json from every lane (--check in CI)\nscripts/build-marketplace.mjs # regenerates .claude-plugin/marketplace.json from the skills lane (--check in CI)\nscripts/check-hash-stability.mjs # asserts the bundle digest is the same from a CRLF and an LF checkout\nscripts/link-registry.mjs # OPERATOR-SIDE: links each project's .claude/skills + .claude/rules at this registry\nscripts/build-knowledge-rules.mjs # regenerates rules/ - the always-on knowledge context projects link (--check in CI)\nscripts/fleet-audit.mjs # OPERATOR-SIDE: which installation runs which copy of which skill; writes adopters\nscripts/signals-collect.mjs # OPERATOR-SIDE: folds connected projects' consult logs + stacks into signals/\nscripts/usage-from-personas.mjs # OPERATOR-SIDE: bootstraps usage/ from a Personas installation's own counts\nknowledge// # a Reference Knowledge Bundle - see knowledge/README.md\nknowledge//taxonomy.json # the authority on where every subject lives; max 10 folders/level\nknowledge//index.json # GENERATED: every subject, technique, law and application\nrules/ai-registry-*.md # GENERATED: the always-on knowledge context, linked into each project's .claude/rules/\nskills//SKILL.md # frontmatter: name, description, category, memory, version (+ harness keys)\nskills//LESSONS.md # append-only reflection lane, beside the skill it is about\nskills//references/ # material the method loads on demand; scripts/, tools/, assets/ likewise\npractices//PRACTICE.md # frontmatter: id, dimension, applies-when; body = the shape\npractices//starter/** # templatized artifacts the practice drops into a repo\nmemory//.md # frontmatter: kind, confidence, namespace, source\nmemory/_index.md # map of content over the notes\nusage/.json # counts from ONE installation - see docs/usage-lane.md\nsignals/.json# currency verdicts from ONE installation - see docs/signals-lane.md\n.projects.local.json # GITIGNORED: slug -> checkout path on this machine; the bridge the operator-side scripts read\n```\n\nTwo `registry.yaml` files is deliberate, not drift: the root one says what this repository is,\nthe `.ascent/` one says how Ascent indexes it. A second consumer adds its own overlay; neither\nrewrites the other, and a reader that knows only one of them still works.\n\n## What is in here\n\n### Knowledge bundles\n\n| Bundle | Covers |\n| --- | --- |\n| [`software-engineering`](knowledge/software-engineering/) | Building and operating software: UI surfaces (including the published surfaces a product shows people who are not users yet), client architecture, LLM/agent engineering, backend platform (including the runtime for a graph of long-lived processes joined by typed channels, the semantics of data pipelines whose values carry their own frame and history, the contracts a packaged model and its workflow expose to hosts, and the internals of an embeddable language runtime - object shapes, engine strings, a tracing collector, register bytecode, guest execution ceilings, the host contract, native interop, standards-layered runtime crates and guest-language introspection), operations, security, secret custody and issuance (a server's own key hierarchy and seals, priced authority, dynamic-secret issuance and the roles that shape an issued artifact), integration, engineering process, and engineering assessment (measuring maturity, delivery and adoption). |\n| [`media-generation`](knowledge/media-generation/) | Producing factual audiovisual content with generative models: narrative craft, research grounding, image generation and prompting, frame direction, production operations. |\n| [`civic-intelligence`](knowledge/civic-intelligence/) | Watching public power with data: parliamentary records, legislation, public money, and the accountability methodology for publishing about real, named people. |\n| [`grant-funding`](knowledge/grant-funding/) | Finding, winning and accounting for grant money: the funding landscape, eligibility and matching, proposal craft, and grant operations from deadline to post-award. |\n| [`llm-observability`](knowledge/llm-observability/) | Operating production LLM traffic as a product: telemetry and cost attribution, price books and usage governance, unit economics, judge-scoring of live traces, and federated benchmark sharing. |\n| [`game-production`](knowledge/game-production/) | Producing a game's systems and content at scale with machine assistance: systems canon and balance validation, the content pipeline and its acceptance ladder, generative asset production, engine integration, machine craft judgment, and production governance. |\n| [`localization`](knowledge/localization/) | Language-specific craft, terminology, typography, register, and script/direction concerns, with product voice and termbases kept in the consuming project. |\n| [`recruiting`](knowledge/recruiting/) | Hiring people with machine assistance and staying defensible: role definition and intake, candidate evidence and its provenance, interviews and work samples, automated screening and its fairness gates, pipeline operations, candidate experience, governance and consent, and honest measurement of a small-sample process. |\n| [`marketing`](knowledge/marketing/) | Getting a small or mid-size business found, chosen and measured: search intent and keyword-metric honesty, site architecture and local pages that survive doorway filters, visibility in AI answers, content briefs, brand voice and channel-native social, paid-search triage, budget reallocation, search-term mining and ad craft, profit-aware measurement and diagnosis, zero-budget and local visibility, conversion and lead handling, and honest proof and positioning - with every threshold labelled as measured or convention. |\n\nA bundle's two upper layers (Golden Path, Technique) carry **no** repo paths, file extensions or\nproduct names - enforced by [`scripts/check-bundles.mjs`](scripts/check-bundles.mjs), not left to\ndiscipline - so they transplant to any codebase unchanged. Applications are the opposite by\ndesign: they cite real code and name their stack in the filename.\n\n**Evidence is not published.** The pointers proving a claim against a particular tree are noise to\neveryone else, so they live in each consumer's gitignored `/.evidence.local.md` overlay.\nThe gate fails any published file that declares them. Format spec:\n[`docs/rkb-profile.md`](docs/rkb-profile.md).\n\n**Read a bundle without reading 965 files.** Each bundle carries a generated\n`index.json` - every subject with its category, status, techniques (and the laws they cite),\nand applications. That is the file an agent selecting knowledge to consult should read; the\nmarkdown is for humans and for the agent that decided to go deeper. It excludes evidence for\nthe reason above, and says so in its own `meta.excludes`. Regenerate with\n`node scripts/build-index.mjs` **before** `build-catalog.mjs`, whose hash covers it.\n\n**The corpus is present, not fetched.** `rules/ai-registry-*.md` are generated from the\nbundle indexes and **linked into each project's `.claude/rules/`**, where a rule with no\n`paths:` frontmatter loads in *every* session at `.claude/CLAUDE.md` priority. So an agent\nopens a session already holding the access contract and the subject map for the domains its\nproject declares — no invocation, no copy, ~2k tokens. That closes the failure a\nconsult-only design has: recall. A standard nobody remembers to look up is a standard that\nis not there at the moment the decision is made.\n\n**And consulted deliberately when it matters.** The lane skill [`consult`](skills/consult/SKILL.md)\nis how a connected project reads the right subject before a product, architecture or domain\ncall: it resolves the registry (a sibling checkout or GitHub), matches the task against\n`use_when` triggers, reads the golden path and the techniques that apply, and logs the consult\nto the project's gitignored `.ai/consults.jsonl`, which is what reaches the `signals/` lane as\na count. A project declares the bundles it consumes in its `.ai/manifest.yaml`\n(`knowledge.domains`) and its agent guide says \"run `/consult` before deciding\".\n\n**Knowledge has an age, and the registry cannot check it alone.** Every application\ncarries `verified_on` - the date its citations were last resolved against a real tree -\nand [`scripts/check-currency.mjs`](scripts/check-currency.mjs) derives an expiry from it\nper stack. That answers \"how old is this claim\". It cannot answer \"is it still true\",\nbecause the registry does not have the consuming repository's checkout. That half arrives\nfrom the other side, through [`signals/`](docs/signals-lane.md): the installation resolves\nits own evidence overlay and reports **verdicts, never pointers** - `{\"gone\": 2}`, not\nwhich two files. A bundle nobody reports on reads as **unknown**, never as current, for\nthe same reason `invokes30d: 0` with no contributors means nobody is looking.\n\n**Some knowledge is correct but not yet.** A technique may declare a `stage` - `solo`,\n`team`, `multi-service` or `fleet` - naming the rung at which it *starts to pay*\n([`docs/rkb-profile.md` §3.2](docs/rkb-profile.md)). It is a floor, not a mandate: below it\nthe technique is over-engineering and a consumer is right to skip it; at or above it, its\nabsence is a gap. The field is optional and rare on purpose, and it is carried into each\nbundle's `index.json` so a consumer can filter on it.\n\n### Skills\n\nUse the [workflow selection guide](docs/skill-selection.md) to choose a coordinating\nskill and its supporting methods. The generated [catalog](catalog.json) carries the\ncurrent names, versions, hashes, and resources; versions are not duplicated here.\n\nRegistry maintenance methods live in [.claude/skills/](.claude/skills/): forge, deepen,\nlibrarian, intake, reconcile, harvest, and assay. They maintain the library rather than\nbelonging to its portable skills lane. The [skills specification](docs/skills-lane.md)\ndefines layout, versioning, overlays, and distribution.\n\n### Practices\n\n| Practice | Dimension | Starter |\n| --- | --- | --- |\n| [`agent-guidance`](practices/agent-guidance/PRACTICE.md) | D1 | [`AGENTS.md`](practices/agent-guidance/starter/AGENTS.md) |\n| [`local-first-readme`](practices/local-first-readme/PRACTICE.md) | D5 | [`README.md`](practices/local-first-readme/starter/README.md) |\n| [`prior-art-teardown`](practices/prior-art-teardown/PRACTICE.md) | D5 | [`docs/prior-art/`](practices/prior-art-teardown/starter/docs/prior-art/EXAMPLE.md) |\n| [`open-contribution`](practices/open-contribution/PRACTICE.md) | D5 | [`.github/` templates](practices/open-contribution/starter/.github/PULL_REQUEST_TEMPLATE.md), [`CODEOWNERS`](practices/open-contribution/starter/CODEOWNERS), [`CODE_OF_CONDUCT.md`](practices/open-contribution/starter/CODE_OF_CONDUCT.md) |\n| [`supply-chain-security`](practices/supply-chain-security/PRACTICE.md) | D9 | [`SECURITY.md`](practices/supply-chain-security/starter/SECURITY.md), [`supply-chain.yml`](practices/supply-chain-security/starter/.github/workflows/supply-chain.yml) |\n| [`least-powerful-test-first`](practices/least-powerful-test-first/PRACTICE.md) | D6 | Test-tier selection and a hermetic default test command. |\n| [`justified-lint-exemptions`](practices/justified-lint-exemptions/PRACTICE.md) | D6 | Explicit reasons for lint exemptions. |\n| [`self-declaring-spec-debt`](practices/self-declaring-spec-debt/PRACTICE.md) | D5 | Documents identify their known implementation gaps. |\n\nA practice describes the **shape** of what good looks like, never a repo's actual content. Its\n`starter/` files are templates full of `<...>` and `TODO:` markers: they scaffold, they do not\npretend to know your architecture. The starter workflow lives under `practices/` and does not run\nin this repository - copy it into a target repo's `.github/workflows/` to use it.\n\n### Memory\n\nNotes and worked examples, indexed in [`memory/_index.md`](memory/_index.md): `semantic` (durable\nfacts), `procedural` (what worked), `episodic` (what happened, dated), `summary` (a rollup).\nConfidence is a 0..1 float, banded as 1.0 verified, 0.6 probable, 0.3 a hunch.\n\n## How a project consumes this registry\n\nPlain git is the baseline. Nothing below requires an account or a token.\n\n```sh\n# read it\ngit clone https://github.com/xkazm04/ai-registry.git\n\n# skills, door 1 - LINK (the default when one owner holds the registry and the consumers)\nnode ai-registry/scripts/link-registry.mjs # match every project to its manifest\nnode ai-registry/scripts/link-registry.mjs --check # verify; nothing to sync, so nothing drifts\n\n# skills, door 2 - the plugin marketplace (a second machine, a second person, or CI)\nclaude plugin marketplace add xkazm04/ai-registry # once per machine\nclaude plugin install uat@ai-registry --scope project # records adoption in .claude/settings.json\n\n# skills, door 3 - copy (the oldest model; still reviewed, still pinned by its version)\ncp -r ai-registry/skills/ci-gate-check /.claude/skills/\n\n# check what you have against what is current\ncat ai-registry/catalog.json # name, version, contentHash, adopters per skill\n```\n\nA project points at the registry from its manifest, and names the bundles it consumes:\n\n```yaml\n# .ai/manifest.yaml\nregistry:\n remote: github:xkazm04/ai-registry\n local: ../ai-registry # the checkout this project links against\nknowledge:\n domains: [software-engineering] # which bundles it consumes -> which rules get linked\nskills: # which shared skills it uses -> what link-registry links\n - perfect\n - uat\n```\n\nThat manifest is the whole declaration. The links themselves are machine state and\ngitignored — a link committed into a repo is a dangling path on the next machine — so\n`scripts/link-registry.mjs` is what makes a machine match the declaration, and `--check`\nis what tells you it no longer does.\n\n**Which copy runs, when a name exists in more than one place.** The reference harness\nresolves a same-named skill *enterprise over personal over project*; plugin skills are\nnamespaced and never collide. So the lane's rule is **one home per name**: a name that\nlives in this lane lives nowhere else on an installation - not in `~/.claude/skills`, not\nas a second project copy beside an enabled plugin. A higher version here does **not**\ndisplace any copy; a version reports staleness, a human updates. Declared in\n[`registry.yaml`](registry.yaml) under `lanes.skills.resolution`, explained in\n[`docs/skills-lane.md`](docs/skills-lane.md), and checked - from the operator's machine,\nbecause the registry cannot see installations - by\n[`scripts/fleet-audit.mjs`](scripts/fleet-audit.mjs), which also writes what it finds into\nthe catalog's per-skill `adopters`.\n\n## How a change gets in\n\nThis is the short form; the full contributor guide - per-lane gates, the privacy rule,\nissue and AI-assistance expectations - is [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n1. Branch, edit `skills//SKILL.md` (or anything in its directory), **bump `version`**.\n2. Append an entry to that skill's `LESSONS.md`: `## - - `\n followed by `-` bullets. Record the version the run *used*, not the bump target.\n3. `node scripts/check-skills.mjs && node scripts/build-marketplace.mjs && node scripts/build-catalog.mjs`\n - the marketplace and the catalog are generated views and CI fails when they are stale.\n4. Open a pull request. A `CODEOWNERS` owner reviews and merges - that merge is the adoption\n decision.\n5. Cached or copied installations update separately. Linked installations read the\n working checkout immediately, including uncommitted changes. Review protects the\n published history; it does not isolate consumers linked to a development checkout.\n\nVersion discipline: **versions are the comparison currency, hashes only detect drift.** Bump\nminor or major when behaviour changes, patch when it does not - but bump. A checker cannot\ntell a typo from a behaviour change, so `scripts/check-skills.mjs --since ` asks for the\ncheapest honest signal on every pull request that edits a skill, and rejects a version that\nmoves backwards. Appending to `LESSONS.md` needs no bump: a lesson records a run *against* a\nversion. Full rule in [`docs/skills-lane.md`](docs/skills-lane.md).\n\n## Counts, witnesses and adopters\n\n`invokes30d` in `catalog.json` is **derived** from the [`usage/`](docs/usage-lane.md) lane -\nthe first contributor is a Personas installation reporting its own 30-day counts. A zero with\nan empty `usageContributors` means nobody is reporting on that skill, not that nobody runs it.\n`adopters` is written by the operator-side `fleet-audit` from the installations it can see\n(`@` for copies, `@plugin:` for enabled plugins); the\nregistry carries it forward and never invents it. Bundle currency reads from\n[`signals/`](docs/signals-lane.md): a bundle with no reporting installation is **unknown**,\nnever current.\n\n## Conventions\n\n- LF line endings, no trailing whitespace.\n- **ASCII where it bites.** `practices/` and `memory/` frontmatter is ASCII; prose is UTF-8: terse, templated files\n that get pasted into terminals and `.claude/` directories. In `skills/`, frontmatter is ASCII\n and fenced code may carry no lookalike punctuation (a Unicode dash or quote that reads as\n ASCII and breaks a pasted command); prose is UTF-8. **`knowledge/` is UTF-8 prose**: OKF\n requires valid UTF-8, and a bundle is long-form writing where an em dash is correct\n typography. The lanes differ because their readers do.\n- No secrets, ever - not in a file, not in an example, not in a test fixture. A tracked\n credential is a hard failure and has to be rotated, not deleted.\n- One idea per skill, per practice, per memory note.\n- Vendor-neutral: name the capability (`Test: npm test`), not the tool.\n\n## License\n\nPublic domain / [CC0 1.0](LICENSE). Copy anything here into your own registry and change\nit to fit.\n", "bytes": 24877, "sha": "5b6179878d8af4abf85c19b46ca7bed1f36cb1a859f4d7553448df1c5200f0d7", "repo_slug": "xkazm04/ai-registry", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/okf_xkazm04_ai_registry_knowledge_llm_observ_abbedf8f/readme" }