Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Banner Alt Text
"Good intentions don't work. Mechanisms do." -- Jeff Bezos
Operating mechanisms codified from working with Claude Code every day. Distilled into the ones that actually stuck.
Not rules (rules get forgotten between sessions). Not principles (too abstract to enforce). Mechanisms -- with triggers, retry logic, and failure notifications that fire whether you remember them or not.
Why mechanisms, not rules?
Early on, when something went wrong, I'd ask Claude to prevent it happening again. It would write a rule or save a note in memory. Next session? Gone. So I started thinking harder about what actually sticks.
A mechanism has:
- A clear trigger (not manual memory)
- Consistent execution when the trigger fires
- A defined expected outcome
- Retry logic (up to N attempts) when the outcome isn't met
- A failure notification if retries are exhausted -- never fail silently
Stability commitment (v3.0)
v3.0 marks the catalog as stable. 27 mechanisms cataloged, with implementations across 5 release themes in the paired claude-mechanisms-tools.
What stable means here:
- Existing mechanism IDs are permanent. The numbers (1-25) are stable identifiers used by
tools.yamlmechanism_ids:arrays in the toolkit. They never get renumbered or reused. - Existing mechanism file paths (
mechanisms/NN-name.md) WILL NOT break in v3.x - Existing `mechanisms.yaml` entries (id, name, file, scope, implementations) preserve their schema in v3.x
- The bidirectional cross-link contract with the toolkit is permanent: every
mechanisms.yamlimplementations:path resolves to a real toolkit file
What's still allowed:
- New mechanisms appended (next ID = max + 1)
- Mechanism file content refined for clarity (the prose may improve; the structure stays)
- New implementations added to existing mechanisms'
## Implementationstables as new tools ship - Deprecation: a mechanism may be marked superseded; it never gets deleted
Breaking changes (renumbering, schema changes, cross-link contract changes) ship as v4.0 with a deprecation cycle.
See CONTRIBUTING.md for how to propose new mechanisms.
The mechanisms
| # | Mechanism | One-liner |
|---|---|---|
| 01 | Discover and derive, never assume or ask | Check before creating, derive before asking, discover before computing |
| 02 | git mv, not cp + rm | Preserve history when moving files |
| 03 | No orphaned files | If content migrates, delete the source |
| 04 | One focused thing per session | Resist scope creep |
| 05 | Deferred work needs persistent markers | Write flags, not verbal promises |
| 06 | Fix conflicts autonomously | Fix it directly, don't surface the problem |
| 07 | Build mechanisms, not habits | The meta-mechanism that defines all others |
| 08 | Incremental rollout, not big-bang swap | Add alongside, verify, then remove the old |
| 09 | Atomic credential persistence | Persist replacements before doing any other work |
| 10 | Parity over independence | Test that N things work the same, not just individually |
| 11 | One branch, one scope | Branch frozen once PR is ready; verify scope before committing |
| 12 | Consolidate review in the artifact | Put proposed changes inside the file, not in chat |
| 13 | Dry-run before committing data-patching scripts | Test scripts against real data, not just synthetic tests |
| 14 | Trace the cascade | Walk every downstream consumer before finalizing a pipeline change |
| 15 | Build callables, not embedded logic | One script, multiple callers, same behaviour |
| 16 | Smallest shippable first | Ship the smallest slice that validates the hypothesis |
| 17 | Structural checks use hooks, not behavioral rules | Enforce objective checks with hooks; reserve rules for judgment calls |
| 18 | Safest path first on destructive ops | Backup, replace, verify, parallel-run, confirm, then destroy |
| 19 | Detection rules: more specific patterns, never broader allowlists | When a detector misses, tighten the pattern, never loosen the allowlist |
| 20 | Hooks silent on pass | Pass prints nothing; warn prints one line; block denies with full detail |
| 21 | Structural intervention beats pattern N+1 | After two rounds of patterns on the same detector, the third round is architectural |
| 22 | A failure fix is a memory and a mechanism | A memory records the lesson; a mechanism enforces it. Ship both. |
| 23 | Unit-test the parts, then end-to-end-test the whole | Per-component unit tests AND a final real end-to-end run; a green gate is not running the thing |
| 24 | Unblock the parallel path before your own serial work | Hand off concurrent work (a brief, a task, an interface) before doing your blocking work; optimize for others' throughput |
| 25 | Plan before build | Substantive code needs an approved plan first; reading is free, building is gated; one-line fixes exempt |
| 26 | Claude cannot defer on time; important work is done now or next | Time is never a deferral reason; the timing call is the user's; quick work is simply done, not offered as a choice |
| 27 | A mechanism is not done until it is wired, measured, and self-surfacing | Writing a hook/gate/skill is not shipping it; verify the connection (does it fire?), the metric (how do we know it works?), and the trigger (no human memory), not just that the artifact exists |
Quick start
Option 1: Copy what you need
Browse the mechanisms/ directory. Each file is self-contained. Copy any mechanism into your own CLAUDE.md or project configuration.
Option 2: Install as a Claude Code plugin
git clone https://github.com/christophecapel/claude-mechanisms.git ~/.claude/plugins/claude-mechanismsTools that implement these mechanisms
Mechanisms describe how the work should be done. Tools enforce it. The companion repo claude-mechanisms-tools packages tools that each implement one or more mechanisms here.
v0.1 — Session Hygiene (3 tools):
| Tool | Implements | Kind |
|---|---|---|
/check | #16, #11, #1 | skill |
worktree-edit-gate | #17, #11 | hook |
/press1-check | #21, #19 | skill+script |
v0.2 — Plan Discipline (2 tools):
| Tool | Implements | Kind |
|---|---|---|
plan-review-gate | #14, #16, #17 | hook (PreToolUse on ExitPlanMode + Bash) |
/plan-archive | #5 | skill+script |
v0.3 — Detection & Audit (1 tool):
| Tool | Implements | Kind |
|---|---|---|
/error-audit | #19, #21 | skill+script |
v0.4 — Memory Discipline (1 tool):
| Tool | Implements | Kind |
|---|---|---|
feedback-memory-gate | #17, #5 | hook (PostToolUse) |
v0.5 — Atomic Git Workflow (1 tool, 5 gates):
| Tool | Implements | Kind |
|---|---|---|
git-workflow-gate | #1, #11, #17 | hook (PreToolUse + PostToolUse on Bash) |
v0.5.1 / v0.6.0 — Gate 3 + Gate 6 (same git-workflow-gate, no new tool):
| Patch | Adds | Implements |
|---|---|---|
| v0.5.1 | Gate 3 — Pre-checkout dirty-tree deny on branch switch | #1, #11, #17 |
| v0.6.0 | Gate 6 — SessionStart stale-branches digest (info-nag) | #1, #11, #17 |
Each mechanism in this catalog with at least one implementation has an ## Implementations section linking forward to the tool. The full cross-link manifest is in mechanisms.yaml under the implementations: field of each mechanism.
About
Built by Christophe Capel -- a product leader building a personal operating system with Claude Code and codifying the discipline that makes it work.
These mechanisms emerged from real failures: wrong-branch commits, lost credentials, orphaned files, scope creep across parallel sessions, and rules that Claude forgot between conversations. Each one exists because something broke and I made sure it wouldn't break the same way twice.
If any of these save you time, I want to hear about it. If you have mechanisms of your own, open a PR or an issue.
License
MIT