MAINFRAME
CATWILLgh/MAINFRAME
Personal hub of global Claude Code customizations — umbrella CLAUDE.md, skills, agents, hooks — that apply to every project on the machine via a plugin + a few symlinks.
Instalação
npx convez-ai CATWILLgh/MAINFRAME1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
MAINFRAME
Maintained by @CATWILLgh
A baseline of operating rules, focused sub-agents, and small automatic checks I want to apply in every Claude Code session on my machine. Set up once — every project, every session, inherits the same discipline.
It's shaped for one workflow in particular: long auto-mode runs — hours, sometimes days, where Claude and I plan a larger feature up front, then it executes on its own with no one watching each step. Every rule, hook, and permission tier here is built to hold quality through exactly that: an unattended run where a missed check turns into a bug nobody catches until later.
Engineering at a glance
For the technically curious — the concrete engineering this repo demonstrates, not the motivation behind it:
- Fail-open hooks. Every check exits cleanly when its tool is missing or it errors, so the hook layer can never break a session — safety that degrades to silence, never to a stall.
- A git-level secret gate. A
PreToolUsehook scans the staged diff and blocksgit commitwhen a high-confidence credential is present — caught before it ever reaches history, not after. - Size budgets against lost-in-the-middle. Skills, agents, and hooks are capped at ≤5K tokens — a limit calibrated to the runtime's compaction behaviour so the content survives a context compaction intact instead of being truncated.
- Covered by tests and CI. ~90 stdlib-Python tests, zero third-party runtime dependencies, run on every push (the CI badge above) alongside the format/size validators.
Personal-use. No support, no compatibility guarantees, no backwards-compatibility promises. Forks are welcome under MIT, but this hub is shaped to one engineer's workflow.
Why this exists
Working with Claude Code (or any AI coding agent) on multiple projects, you keep running into the same friction:
- Same baseline, every time. You re-deploy the same useful sub-agents, the same operating rules, the same little safety checks for every new project. Manually. Forever.
- Project-level config doesn't scale. Putting it all into the project's own
CLAUDE.mdworks — until that file grows. Then attention scatters, the well-known lost-in-the-middle problem kicks in, and important rules quietly stop being followed mid-session. - The agent itself bloats its own config. Left to its habits, Claude keeps appending new instructions to
CLAUDE.md. The file grows, focus thins, the rules crumble. And so it grows, slowly, until you notice the discipline you started with is gone.
This repo is my attempt to do that baseline layer separately from any specific project, with deliberate size limits and small reminders so things don't drift:
- Strict file-size budgets on skills, agents, hooks. A file gets too big — a hook nudges me.
- Skills and agents stay granular and narrowly focused — at any moment, only the most relevant context is loaded, not a soup of "a little bit of everything".
- Constantly iterating: try a new approach, see what stabilizes Claude's behavior, keep what works, drop what doesn't.
- Every decision cross-checked against authoritative sources (Anthropic docs, RFCs, well-known engineering material) — not "feels right".
Honest disclaimer. I'm not claiming this hub closes every pain. Some friction with AI agents is just current-generation model limits — the best a hub can do is smooth them, not fix them. What I am aiming for: a higher minimum quality of output code by default. On long-running development that pays back many times over — problems caught and prevented up front instead of bugs to chase later, by you or by the agent.
Where this comes from
This isn't a weekend project or a copied template. It's distilled from thousands of hours of working with AI coding agents, day after day — what consistently helped, what quietly broke, what was worth keeping. Every rule here earned its place by surviving real use.
Three things shape it:
- Hard-won experience. The rules come from patterns I hit over and over on real projects — not from theory.
- Authoritative sources. I don't ship a rule on a hunch. Each non-trivial decision is checked against primary sources — Anthropic's own docs, RFCs, established engineering material — and validated with a small experiment where I can.
- Constant feedback. I work on this almost every day, together with the agent. When something underperforms in real use, it gets refined or dropped. The hub is never "finished" — it's continuously corrected against what actually happens.
And here's the part that's easy to miss. It looks like just a folder of Markdown files — some skills, a few agents. It isn't. Steering a language model reliably, across many projects and long autonomous runs, is one of the genuinely hard parts of working with agentic systems. The model's inference — how it generates each step — is a kind of ordered chaos: powerful, but hard to keep pointed in the right direction at scale. This hub is my standing attempt to put just enough structure around that chaos to make the output dependable, without strangling what the model is good at.
What you actually get
In plain words — what each piece is for:
- Umbrella
CLAUDE.md— a tight set of working rules Claude follows in every project on your machine. Partnership-mode, honest pushback when I'm wrong, no flattery, source-checking before non-trivial decisions, atomic commits, no leftoverTODO/FIXMEmarkers, and so on. Around 160 lines, intentionally short to stay in focus. - Skills — small focused playbooks Claude pulls when they're relevant. Things like "audit this code carefully", "format this commit message in Conventional Commits style", "scan this diff for forgotten secrets" — instead of one giant document trying to cover everything.
- Agents (sub-agents) — pre-configured specialists with their own model and effort level wired in. Backend engineers for Python, Node.js, and Next.js (App Router server layer), a frontend engineer for React, a devops engineer for deploys and infra, a decision-reviewer for high-stakes design calls, and a web-search agent for authoritative source-checking. You don't have to remember which model to pick for what — the right one is already attached.
- Hooks — small automatic checks that run on tool events. Catch leftover
TODO/FIXMEmarkers before commit. Warn on risky bash patterns. Scan diffs for security issues withruff/semgrep/osv-scanner. Block a finished turn when a real problem is still unresolved. Things that fire without you having to remember to fire them — the full list with what each one does is in Inventory below. - Rules — small path-scoped guidance files that load on demand when Claude reads a matching path. Doesn't bloat the global context.
- Permissions — three-tier model (deny / ask / allow) that's strict by default. Some things must never run; some need confirmation; the rest run quietly with logging.
End result the hub aims for: the same baseline of quality and discipline applied to every project on your machine — without re-configuring Claude each time or babysitting it through a long unattended run. When the baseline is high, day-to-day output is more predictable and bug rate drops.
Inventory — what's actually inside
The concrete list of everything the hub ships, in plain words. Three groups: agents (specialist sub-agents you delegate to), hooks (automatic checks on tool events), skills (focused playbooks Claude pulls when relevant).
Agents — 7 specialist sub-agents
Each ships with its model and effort already wired in, calibrated separately so you don't pick at call time. Invoked as subagent_type: "mainframe:<name>".
| Agent | What it's for | Model |
|---|---|---|
python-backend-engineer | Python backend work — FastAPI / Django / Flask endpoints, ORM models, auth, background workers | Sonnet |
nestjs-backend-engineer | Node.js / NestJS backend — endpoints, ORM, auth, WebSocket gateways, queue workers | Sonnet |
nextjs-backend-engineer | Next.js App Router server layer — route handlers, server actions, RSC data, caching, auth | Sonnet |
react-frontend-engineer | React + Vite frontend — pages, components, forms, data fetching, API integration | Sonnet |
devops-engineer | Deploys, CI/CD, containers, infra config, managed databases, Dokploy | Opus |
decision-reviewer | Adversarial, evidence-grounded second look at a high-stakes design or approach before you commit | Opus |
web-search | Authoritative source lookup — Context7 docs + live web, returns cited quotes | Sonnet (low) |
Hooks — what each one checks, and when
Hooks fire on tool-lifecycle events. Two kinds: a gate can block or ask (it stops the action or the turn until something is fixed); an advisory only injects a note and never blocks. The core design is warn early, block at the end — when you edit a file the advisory scanners flag a problem immediately, and if it's still unresolved when Claude tries to finish, the matching Stop-gate blocks the finish. So a real issue can't quietly slip through to the end of an unattended run. Every hook is fail-safe: if it errors, or its tool isn't installed, it exits silently and never breaks your session.
At session start — SessionStart (fresh start, resume, /clear, and after every compaction)
session-posture.py— Injects the hub working posture as context: engage the process instead of reasoning past it, work in two phases (plan with the user, then execute autonomously), surface out-of-scope findings as tickets, and delegate broad work to sub-agents. A salient reminder at the moment context is fresh, since a steadyCLAUDE.mdline fades into the background.task-workflow-engagement.py(reset half) — Resets a per-segment marker tracking whether thetask-workflowprocess skill was actively invoked. Its enforcement half fires before your first edit — see below. This reset on every session start (including after a compaction) is what makes it re-fire post-compaction.hooklib-smoke-check.py— Self-test that the shared hook library imports cleanly. Every other hook silently no-ops if that library is broken, so this one announces the failure loudly at session start instead of letting the whole hook layer go dark unnoticed.
Before a Bash command — PreToolUse on Bash
secret-commit-gate.py— Gate (blocks). When the command is agit commit, scans the staged diff for high-confidence secret shapes (vendor API tokens, private keys) and blocks the commit if one is staged. Skips repos that use SOPS or git-crypt; defers on any error rather than risk a false block.path-validation.py— Gate (asks). Parses a recursiverm -rf, resolves every target path, and allows it silently when all targets are inside the project — but asks for confirmation if any path is outside the project, unresolved, or built from a subshell. Anything that isn't a recursivermpasses straight through.bash-pattern-reminder.py— Advisory. Catches commands that historically trigger auto-mode permission prompts or stall a hands-off run (literalrm -rf, heredoc/redirect into/tmp, ad-hoc global installs) and suggests the friction-free alternative (the Write tool, the installer's helper). Non-blocking on purpose — a block would become a freeze in auto-mode.commit-conventional-reminder.py— Advisory. On agit commit, reminds about Conventional Commits grammar (type / scope / subject).
Before you load a skill, or edit a file — PreToolUse on Skill / Edit / Write
task-workflow-engagement.py(enforcement half) — Advisory. When thetask-workflowskill is invoked it marks the segment active; on your first file-modifying call (Edit / Write / MultiEdit) of a segment where it wasn't, it nudges the main agent to invoketask-workflowfirst. A skill survives a compaction (its first 5K tokens get re-attached) but the runtime frames the copy "context only" and the model deprioritises it — so the process can be present yet not actually followed. Fires once per segment, main agent only (sub-agents can't invoke skills).
Right after you edit a file — PostToolUse on Edit / Write / MultiEdit (all advisory — the "warn early" half)
scan-suppression-markers.py— Flags suppression markers (TODO/FIXME/HACK, skipped or focused tests,@ts-ignore/eslint-disable/# noqa) and debug residue (debugger,breakpoint(),console.debug,var_dump/dd) that the edit just introduced. Diff-aware: it flags only what the change added, not what was already there.comment-discipline-reminder.py— Flags comments the edit just added that match a banned form — process narration, redundant paraphrase of the code, position / phase markers, journal / byline notes. The "comment the WHY, not the WHAT" rule, surfaced at write time.ticket-id-format-reminder.py— On a newdocs/tickets/<id>-*.mdwhose id is a short sequential number (NNN), nudges to use a random 8-hex id instead (openssl rand -hex 4). Sequential ids collide when several branches or agents each allocate "the next number" independently; random ones don't. Write-only, so editing a legacyNNNticket doesn't nag.python-security-scan.py— Runs Ruff's curated S (flake8-bandit, OWASP-aligned) + B (flake8-bugbear) rules over the changed Python and notes high-confidence dangerous patterns and correctness bugs —pickle.load, unsafeyaml.load,subprocess(..., shell=True), and similar.python-deps-audit.py— When a Python dependency file changes, runspip-auditand notes known CVEs in the dependency tree.nodejs-security-scan.py— Runs oxlint's curated dangerous-pattern subset over the changed JS / TS — classic RCE (eval,new Function), unsafe React, and more — and notes the hits.nodejs-deps-audit.py— When a Node dependency file changes, runsosv-scannerand notes known CVEs.
Before the turn ends — Stop (the final gates, plus a few advisory notes)
stop-gate-suppression-markers.py— Gate (blocks). Blocks the turn from finishing while suppression markers or debug residue added this session remain unresolved — the hard backstop to the advisory scanner above.stop-gate-comment-discipline.py— Gate (blocks). Blocks finishing while banned narration comments (measured againstgit HEAD) remain.python-security-stop-gate.py— Gate (blocks). Blocks finishing while unresolved Ruff security findings remain in changed Python.nodejs-security-stop-gate.py— Gate (blocks). Blocks finishing while unresolved Semgrep security findings remain in changed JS / TS (using the YAML rules underhooks/rules/).frontend-fsd-gate.py— Gate (blocks). Blocks finishing on Feature-Sliced-Design import-direction violations (a lower layer importing an upper one), via dependency-cruiser.frontend-dead-code.py— Advisory. Notes dead / unused files via Knip. Opt-in per project.fallow-quality-note.py— Advisory. Notes quality smells in changed TS / JS — import cycles, layer-boundary breaks, dead files, over-complexity, copy-paste — via thefallowanalyzer. Throttled, conservative categories only.memory-reminder.py— Advisory. A gentle nudge to save a durable cross-session fact to Claude's native auto-memory after a substantive session. Throttled (~30 min), skips trivial sessions, and is framed so "nothing worth saving" is a fine answer.
Always-on, and the plumbing
telemetry.py— (dev-only.) Fires across many events — session start/end, skill loads, file edits, todo-list updates, permission denials, sub-agent starts — and logs local-only event metadata (counts and coarse buckets, never prompts, code, todo text, or file paths) into a local SQLite DB. Present only when the--devinstrumentation is installed; on a plain install it isn't wired and writes nothing.- Shared libraries (not hooks themselves):
_hooklib.py— common scaffolding (payload parsing, the emit / gate helpers, git diffing);_markers.py— the suppression-marker and debug-residue detector sets;comment_extract.py— false-positive-free comment / docstring extraction.
Skills — 18 focused playbooks
Pulled automatically when the situation matches, or invoked as /mainframe:<name>.
| Group | Skills |
|---|---|
| Process & quality | task-workflow (the universal task cycle), surface-ticket (file deferred problems as tickets), no-suppression-markers (completion gate), testing-strategy (which test tier + level), severity-calibration (rank findings honestly), code-audit (parallel multi-aspect review), decision-review (validate an approach), git-conventional-commits (commit message grammar) |
| Backend | python-backend-patterns, nestjs-backend-patterns, nextjs-backend-patterns — stack recon + ORM / validation / auth / observability patterns |
| Frontend | react-frontend-patterns (FSD, state, data fetching), frontend-design (colour, type, a11y, motion, layout), shadcn (shadcn/ui composition) |
| Ops & misc | ops-app-server-safety (no duplicate servers, safe stops), dokploy-api (Dokploy PaaS HTTP API), curl-requests (HTTP request templates), secrets-handling (credentials layout + pre-reply secret scan) |
Architecture
graph LR
subgraph repo["MAINFRAME repo (this)"]
P[plugin-dist/<br/>skills + agents + hooks + commands]
E[export/<br/>CLAUDE.md + settings.json + rules + secret helper]
end
P -->|one symlink<br/>~/.claude/skills/mainframe/| home[~/.claude/]
E -->|per-item symlinks| home
home -->|Claude auto-loads<br/>as 'mainframe' plugin| any[Any project<br/>on the machine]
The hub ships in two channels:
- A plugin (
plugin-dist/) carries skills, agents, hooks, and commands. After install, Claude Code auto-loads it as themainframeplugin via the skills-dir mechanism, and everything inside becomes available with themainframe:namespace prefix (e.g./mainframe:code-audit,subagent_type: "mainframe:python-backend-engineer"). That namespace is the visible mark that something is coming from this hub, not from your local project setup or another plugin. - Single-file and per-item symlinks (
export/) carry the umbrellaCLAUDE.md, the permissionsettings.json, path-scopedrules/, and a small credentials helper — pieces the plugin format does not currently support.
See docs/layers/ for full per-layer specifications.
Requirements
Required:
- Claude Code v2.1+ — the host (CLI or IDE extension).
- git — to clone the repo, and for the hooks that diff your working tree.
- Bash 3.2+ — to run
install.sh(macOS system Bash is fine; no GNU-only extensions used). - Python 3 — every shipped hook is stdlib Python 3 (they shell out to the linters below, but need no Python packages of their own). Without Python 3 they silently no-op (the installer warns; it does not fail).
Recommended — each unlocks a group of checks; anything missing just stays silent, and install.sh prints an OS-specific install hint:
- Node.js / npm — the React and Node.js agents, the shadcn CLI (
npx), the frontend recon script, and the JS hooks (oxlint,dependency-cruiser,knip,fallow).install.shinstalls the four hook tools as npm globals for you. - uv or pipx — installs the Python-packaged linters the hooks call:
ruff,semgrep,pip-audit(semgreppowers the JS/TS security stop-gate, but installs as a Python package). - osv-scanner — the dependency-vulnerability hook (
install.shcan fetch the binary for you).
Nothing here hard-fails a session: a tool that isn't installed disables only its own hook. Run ./install.sh --dry-run to preview everything and see exactly what's missing.
Install
git clone https://github.com/CATWILLgh/MAINFRAME ~/Documents/projects/MAINFRAME
cd ~/Documents/projects/MAINFRAME
./install.sh
graph LR
A[git clone] --> B[./install.sh]
B --> C[plugin-dist/ →<br/>~/.claude/skills/mainframe/]
B --> D[export/CLAUDE.md & settings.json<br/>→ ~/.claude/ symlinks]
B --> E[export/rules/* →<br/>~/.claude/rules/ per-item]
C --> F[Claude auto-loads<br/>'mainframe' plugin]
D --> G[Umbrella + permissions<br/>active in every session]
E --> G
F --> G
What install.sh does:
- One symlink for the plugin —
plugin-dist/becomes~/.claude/skills/mainframe/. Claude Code auto-loads it and prefixes everything inside with themainframe:namespace. - Single-file symlinks for the umbrella
CLAUDE.mdand the permissionsettings.json(the plugin format does not provide an equivalent for these). - Per-item symlinks for
export/rules/*into~/.claude/rules/, so the hub composes with any rules you already have without replacing the whole directory. - Credentials helper — links
export/scripts/secretinto~/.local/bin/and seeds~/.config/credentials/+~/.claude/credentials-index.mdfrom the template. - Stale-symlink cleanup — on first run after upgrading from the older per-item layout, removes leftover hub symlinks under
~/.claude/{skills,agents,hooks}/. - Backs up any pre-existing real file before replacing it with a symlink.
- Idempotent — re-running is a no-op when state matches.
Options:
./install.sh # install (with backups)
./install.sh --dev # install + hub-development instrumentation (see below)
./install.sh --dry-run # preview, no changes
./install.sh --uninstall # remove managed symlinks (incl. --dev ones)
./install.sh --help
--dev — hub-development instrumentation (most users don't need this). A plain install ships none of it. The flag adds three opt-in pieces, all strictly local; their data lives inside the repo at workspace/runtime/ (gitignored), reached via the hub-owned symlink ~/.claude/mainframe:
harness-feedbackskill (dev/skills/) — agents file structured friction reports about the hub's own rules/hooks into~/.claude/mainframe/feedback/for later triage. Without the skill installed, the related nudges in hook output stay silent.- Usage telemetry — hooks log event metadata (no prompts, no code, no paths) into a local SQLite DB under
~/.claude/mainframe/telemetry/, and only while that hub-owned namespace exists. Nothing is ever sent anywhere. Remove the symlink to stop logging. - Local hub map — a self-contained
workspace/runtime/hub.htmlpage. A searchable catalog of every skill, agent, and hook — click any card, or any graph node, for its details and what references it; the hook trigger matrix; a Config panel showing the permission tiers and key settings; a Health panel that surfaces broken cross-references, orphaned skills, and missing hook scripts; a telemetry panel broken down by agent, by day, and by miss type; and a relationship graph. Generated on--devinstall; regenerate any time with.venv/bin/python3 tools/build_hub_page.py. Open it straight from disk (no server) — it reads nothing remote.
To temporarily disable the plugin without uninstalling, use claude plugin disable mainframe (and claude plugin enable mainframe to re-enable).
Update
cd ~/Documents/projects/MAINFRAME
git pull
That's it. Symlinks point to files in this repo — the next Claude Code session sees the latest. Re-run install.sh only if a new top-level directory appeared under export/.
graph LR
A[git pull] --> B[Files updated<br/>in repo]
B --> C[Symlinks already<br/>point to repo]
C --> D[Next Claude session:<br/>latest active]
Tested configuration
What I have actually verified this hub on:
- Claude Code CLI — the primary surface I use daily.
- Claude Code IDE extension — also in active use.
- Main thread model: Claude Opus 4.7+ at
highorxhigheffort (currently Opus 4.8 day to day). This is what I run every day and what all the discipline is tuned against. - Sub-agents — each one calibrated separately via a small empirical tournament so the right model + effort sits inside the agent file itself. You don't have to think about it at call time.
Other model / effort combinations may work but I haven't verified them. When an agent's prompt body changes in a meaningful way, I re-run its tournament.
Trying the hub on other models or effort levels is very welcome — Sonnet, Haiku, lower or higher effort, different IDEs. Share what you observe (open an issue or a PR with notes); empirical results on configurations I don't run daily are exactly the kind of feedback the hub gets better from.
OpenAI Codex support is in the future-list, not in scope yet.
Platforms
- macOS — primary, tested daily.
- Linux — should work;
install.shis plain Bash 3.2+ compatible, no macOS-specific paths. - Windows — not supported yet, no timeline for it.
Directory map
MAINFRAME/
├── README.md, LICENSE, CONTRIBUTING.md # project meta
├── install.sh # installer (creates the symlinks into ~/.claude/)
├── assets/ # README images (banner, divider, badge)
│
├── plugin-dist/ # the plugin — auto-loads as 'mainframe' after install
│ ├── .claude-plugin/plugin.json # plugin manifest (name, version, license)
│ ├── skills/ # 18 skills, one folder per skill
│ ├── agents/ # 7 file-based sub-agents (Python, Node.js, Next.js, React, devops, decision-reviewer, web-search)
│ ├── commands/ # slash commands (currently empty)
│ └── hooks/
│ ├── hooks.json # which hook fires on which event
│ ├── scripts/ # 26 Python files — 23 hook scripts + 3 shared libs (security scans, marker discipline, ...)
│ └── rules/ # Semgrep YAML rules
│
├── export/ # what the plugin format does NOT carry
│ ├── CLAUDE.md # umbrella operating rules (partnership, evidence, honesty, ...)
│ ├── settings.json # permissions (allow/ask/deny tiers)
│ ├── output-styles/ # custom reply styles (e.g. explanatory-concise)
│ ├── rules/ # path-scoped guidance (currently empty, future-proof)
│ ├── scripts/secret # credentials helper script
│ └── templates/credentials-index.md # starter template for the credentials index
│
├── tools/ # Python validators (used by hooks; runnable manually)
│ ├── validate-claude-md.py # umbrella spec + project-agnosticism check
│ ├── validate-skill.py # skill format + size limits
│ └── agnostic-blacklist.txt.example # copy to agnostic-blacklist.txt and add your own project names
│
└── docs/
└── layers/ # architecture spec per layer (skills, agents, hooks, rules, ...)
Anything you do not see here lives outside the repo by design — internal ADRs, working notes, the maintainer's inbox of unprocessed candidates, and per-machine memory are all gitignored. The published artifact is the hub itself, not the maintainer's working files.
Layer architecture
Each artifact type has its own layer with explicit contract: where it lives, what frontmatter it carries, what limits apply, when it activates. New artifacts go through a decision tree to land in the correct layer.
graph TD
Start[New hub artifact<br/>needs a home] --> Q1{Triggers on<br/>file path?}
Q1 -->|yes| Rules[rules/<br/>paths: frontmatter]
Q1 -->|no| Q2{User invokes<br/>by slash?}
Q2 -->|yes| Commands[commands/<br/>or skills user-invocable]
Q2 -->|no| Q3{Domain<br/>playbook?}
Q3 -->|yes| Skills[skills/]
Q3 -->|no| Q4{Tool event<br/>trigger?}
Q4 -->|yes| Hooks[hooks/]
Q4 -->|no| Q5{Isolated<br/>subagent?}
Q5 -->|yes| Agents[agents/]
Q5 -->|no| CLAUDE[Add to umbrella<br/>CLAUDE.md]
| Layer | Spec |
|---|---|
Umbrella CLAUDE.md | docs/layers/claude-md.md |
| Skills | docs/layers/skills.md |
| Agents | docs/layers/agents.md |
| Hooks | docs/layers/hooks.md |
| Rules | docs/layers/rules.md |
| Commands | docs/layers/commands.md |
| Permissions | docs/layers/permissions.md |
| Settings | docs/layers/settings.md |
| Output styles | docs/layers/output-styles.md |
| Decision tree | docs/layers/decision-tree.md |
Principles
Every artifact shipped by this hub (whether in plugin-dist/ or export/) holds these:
- Project-agnostic — no hardcoded project names, stacks, paths, or domains.
- Evidence-based — new rules need real experience, an authoritative source, or a measured experiment. Not "feels right".
- English in artifacts — skills, agents, commands, hooks all in English (LLM adherence).
- Single source of truth — each artifact exists in exactly one location in the repo.
- Sub-agent economy — pick the right model per task (Haiku for trivial, Sonnet for most research, Opus only for genuine reasoning needs).
A personal note
I'm not a scientist or a credentialed engineer. I'm just someone who genuinely enjoys working with AI agents and models — and who has put a lot of hours into it over the past couple of years. To put it plainly: this year alone my Git history already shows over 2,300 private commits across 3+ production projects and counting; about 300 the year before; and before that, nothing — I worked entirely on my own machine and didn't even know how Git worked.
I started sharing this for people just getting into all of this, or looking for something new — because I hadn't come across repos quite like it. Maybe they're out there, somewhere at the bottom of GitHub; maybe some are even better than mine. But this one is mine, and I enjoy making it.
So if you want to try it, try it. If not, that's fine too — I'm not insisting on anything. Take what's useful, leave the rest.
Contributing
This is a personal hub but friends, acquaintances, and curious strangers are welcome to fork, adapt, and share what works. The repo gets better when more people poke at it from different angles — new approaches, sharper rules, things I haven't tried.
See CONTRIBUTING.md for fork conventions, principles, validators, and commit format.
License
MIT — use, fork, modify freely, no warranty.