Tastes: your conventions as versioned, enforceable files

On 2026-08-05 an agent tagged v0.8.0 on semver reflex. The owner's rule — patch unless a minor is agreed for that release — lived in no file, so no agent could have read it and nothing could have refused it. Fixing it took three hand-built layers. Tastes make it one file with a path, and let the owner decide how hard that file binds.

A scope is a directory, and every preference in it is its own file. That is the whole structural idea, and it is the opposite of what conventions do today: a single instruction file that every new rule gets appended to until nobody can say what is in it, which is the failure mode tastes exist to replace.

├── branch-naming.md      9 lines    require · advise
├── commit-identity.md   13 lines    require · check
├── mr-style.md          11 lines    prefer  · advise
└── release-tier.md      18 lines    require · block

Kebab-case, and deliberately unnumbered. Numbering belongs to append-only records, where position is the history: agentkit's own designs/ runs 001-, 002-, 003-, and each number is permanent because the record is. A taste folder is not a record. It is a living dictionary keyed by name:, whose files get added, rewritten and deleted — and rules/, five files and no numbers, already works exactly that way.

One of those files in full. Frontmatter an agent can filter on, a body a human wrote — and, because this owner wants the rule refused rather than merely read, the declarative rule the generic hook enforces:

---
name: release-tier
scope: project
category: release
strength: require
enforce: block
rule:
  kind: command
  match: 'git tag .*\bv[0-9]+\.[0-9]+\.0\b'
  remedy: Cut a patch tag, or record the owner's
    agreement in the release PR first.
  override: AGENTKIT_RELEASE_TIER
provenance: 2026-08-05 · session correction
---

Precedence is project > external > user > kit. When the same name: appears at two scopes the higher one replaces the lower outright — agentkit never merges two tastes into a third that nobody wrote and nobody can review.

That ordering puts a project above the organisation policy it subscribes to, which is deliberate. A repository with a good reason to differ writes its own taste and the override shows up in the repository's diff, where a human approves it. Governance by review, not by a tool refusing to let you work.

To say the load-bearing part plainly, because it is the thing people assume works the other way: a project taste is an ordinary committed file. It lands on a branch, gets reviewed in a merge request, and arrives in every clone of the repository. There is no separate store, no database, and nothing that lives only on the machine that happened to write it. A vendored external source is committed too. Only the user layer is machine-local — and even that can be published as a repo you subscribe to from everywhere.

One copy, four harnesses: the installer already links ~/.claude/skills, ~/.agents/skills, ~/.codex and ~/.grok/skills back to ~/.agentkit. Tastes ride that same wiring, so a preference stated in one harness is present in the next without a second copy or a per-harness format.

The topology this is designed against is a single owner's. One central repository holds the conventions; every repository in the business subscribes to it as a vendored external source; and because one person sets them, the project scopes hold only deviations that are genuinely repo-specific and the user scope stays close to empty. Today those same conventions live as copy-pasted paragraphs in each repo's instruction file, where copies drift and nobody can say which one is stale.

sources: is an ordered list, and several sources compose at the external layer — a later entry wins a conflict with an earlier one. That is what makes two sets useful rather than one.

The first version of that central set is not written from scratch. It is extracted from the convention corpus already sitting in per-repo instruction files — the same paragraphs, moved somewhere an agent can find them and a diff can review them.

That last row is the one that decides the design. A policy fetched at read time is a policy that is missing on a fresh clone, on a plane, and on a CI runner with no credentials for the org's git host. So a source has a mode, and the default is to vendor it: the snapshot is committed alongside the code it governs and travels with every clone, exactly like a dependency you check in.

A source is declared in committed config, so subscribing is a reviewed change like any other. Project scope defaults to vendoring; a personal source on your own machine is usually a reference.

taste:
  sources:            # ordered — a later entry wins
    - repo: git@github.com:developerinlondon/agentkit-tastes.git
      mode: vendored  # the default — committed to this repo
      ref: v2026.08.1
      path: tastes/   # optional subdirectory
    - repo: git@github.com:developerinlondon/business-tastes.git
      mode: vendored
      ref: v2026.08.4 # wins conflicts with the set above

taste:
  sources:
    - repo: git@github.com:developerinlondon/my-tastes.git
      mode: reference   # cached on this machine only
      ref: main
      on_unreachable: warn   # use-cache | warn | fail
      max_cache_age: 14d     # quiet inside it, loud past

agentkit-tastes  4f1c2be9a7d0e3b8c5a19f7264e0d3b1c8a5f2e9  v2026.08.1

Nothing above is specific to consuming. A source is just a git repository whose files are tastes, which means any repository of taste files is already a publishable taste set — there is no registry to list it in, no package format to conform to, and no publish step beyond git push.

Learning is an event, not a background process. It fires when a correction arrives, and its whole output is a diff you can read, reject, or amend.

Day 0 you say patch increments. Day 2 you say you want minor increments. Nothing should let both of those be true at once, and the first thing capture does is make sure they cannot be: before writing anything it checks the existing tastes by name and topic, so an instruction that contradicts a covered preference never produces a second file. Two tastes that disagree can never both be loaded, because the second one is never written.

What the instruction means, though, is genuinely ambiguous, and the two readings want opposite things:

Which reading applies is not something to infer from tone, so strength decides how much ceremony the fork gets. Contradicting a require taste — more so one at enforce: block — asks outright: this contradicts release-tier — one-off, or change the taste? A policy that took a deliberate decision to set should not flip because of one ambiguous sentence at the end of a long session. A prefer taste updates directly and says that it did.

Either way the outcome is one file. A superseded taste is rewritten, never shadowed by a release-tier-v2.md sitting next to it, because the archive already exists: git history holds every previous version of that file. Reading the current preference should cost one file, not a chain of them — which is the same reason a decision record gets revised in place rather than superseded by a new document.

Learning routes to the owning scope. A correction lands in whichever repository you happened to be working in, but the preference usually is not about that repository. When it is global, the skill proposes a merge request against the central source — the repo that owns that taste — and the update reaches everywhere else the ordinary way, as lock-bump MRs. Writing it locally instead is the fast path and the wrong one: it fixes the repository you were in and leaves every other one wrong, which is exactly the drift that made copy-pasted conventions unusable.

Which set a given correction belongs to is judgment, and there is no honest way to present it as a lookup. What the skill can do is capture the signals at the moment the correction lands, when the context is still there:

Judgment is enough here because the stakes are bounded, and it is worth saying why rather than hoping the heuristic is good. A misfiled taste is one small file. Moving it is two merge requests — out of one set, into another — with no data migration and nothing to rewrite. The periodic audit reads placement as well as staleness, so the wrong call surfaces as a proposal rather than sitting there: nothing in this taste is business-specific — propose promoting it to the public set. Unsure defaults inward for the same reason: a private taste that should have been public costs a promotion MR, while the reverse costs a leak.

The shortest description of the mechanism is git hooks for agents, and it is a fair one: taste-police is mechanically a hook, refusing a command before it runs. Two differences are worth keeping in view. Enforcement is opt-in per taste rather than per repository, so most of your tastes never enforce anything. And the rule it applies is learned from a correction and arrives as a diff you approve, rather than being hand-written into a script nobody revisits.

Agents follow a loaded taste the large majority of the time, and most tastes will never need more than that. check and block exist for the tail: a long session where the instruction has been buried under hours of tool calls, a reflex that overrides what was read — semver beat the changelog in the incident above — and sessions where the taste was never loaded at all. agentkit has measured its own version of this:

So enforce: is a dial the owner sets on the file, in advance, for the reason they already know. advise is the default and where most tastes stay.

Which is the whole architectural point. The refusal below is produced by a hook that has never heard of releases, semver, or this repository:

Every bold fragment there is a field of the taste file in section 02 — the taste's name, its match, its remedy, its override. The hook contributes the word BLOCKED and the machinery to intercept a command. Adding a second blocking taste tomorrow changes no code anywhere.

The override is deliberate, and modelled on the branch WIP cap in hooks/claude/git-police.sh: a guard with no way through gets disabled wholesale, and a guard you can switch off by mistyping it is worse than no guard. One named escape hatch, used on purpose, visible in the command.

Two things deliberately do not happen here. A preference that cannot be expressed as a declarative rule stays at check rather than growing bespoke code — and if the gap it exposes is genuinely general, that is an agentkit feature request, which is outside what a taste is for. And an agent that observes repeated violations may propose raising enforce:, but the proposal arrives the same way every other change does: as a diff the owner reads and merges.

The idea is commandcode.ai's Taste, which deserves the credit for naming the problem: your preferences are real, they are learnable, and no tool was holding them. It describes itself as “an invisible architecture of your choices”. That invisibility is exactly the part agentkit inverts.