agent-kernel
AGENTS.md5 starsChanged 4 months agoMITView on GitHub
Instructions for AI coding agents working on or with the agent-kernel repository. agent-kernel is a local-first governance kernel for AI coding agents. It provides: Read these before non-trivial work: Use docs/TROUBLESHOOTING.md before changing runtime code to fix setup, linking, hook, MCP, architecture, or memory problems.
- Reads credentials
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- .codex/AGENTS.mdAGENTS.md
- agent-kernelSkill
- architecture-guardianSkill
- agent-kernelSkill
- architecture-guardianSkill
- agent-kernelSkill
- agent-kernel-evolveSkill
- agent-kernel-opsSkill
- architecture-guardianSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
35 rules. About 1 is common, 18 are distinctive, and 16 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈18
Distinctive · estimate
This author's own choices. Worth a look.
16
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 18
Read these before non-trivial work:
- Very specific: line 26
Use docs/TROUBLESHOOTING.md before changing runtime code to fix setup, linking, hook, MCP, architecture, or memory problems.
- Very specific: line 53
Do not add production code to src/adapters/, src/commands/, src/core/, or src/hooks/ unless you also wire the modularization into the …
- Very specific: line 55
Do not hand-edit dist/cli.mjs.
- Very specific: line 56
Do not hand-edit generated guidance in ~/.agent-kernel/dist/ or project-local generated files.
- Distinctive: line 57
Do not approve or publish memory from an agent hook.
- Distinctive: line 58
Do not auto-create or silently broaden Architecture Guardian baselines, contracts, policies, or exceptions.
- Distinctive: line 59
Do not attribute a baseline architecture finding to the current change unless the finding fingerprint is new.
- Distinctive: line 60
Do not use a broad permanent exception.
- Very specific: line 61
Do not commit secrets, .env files, node_modules/, or private MCP credentials.
- Common: line 62
Keep repo-local ECC configs reviewable and credential-free.
- Distinctive: line 63
Search existing docs, code symbols, and tests before inventing new behavior.
- Distinctive: line 67
When a user asks for work in this repo:
- Distinctive: line 72
Use an active change contract when the policy requires one.
- Distinctive: line 73
Prefer a small coherent PR over a broad rewrite.
- Distinctive: line 74
Update docs and tests when behavior changes.
- Distinctive: line 75
Run Architecture Guardian conformance before commit when architecture-relevant files change.
- Distinctive: line 83
Before creating a function, class, service, repository, adapter, validator, hook, state store, or utility for non-trivial work:
- Distinctive: line 91
When a change contract is required:
- Very specific: line 106
Use agent-kernel architecture baseline .
- Distinctive: line 110
When a command, test, edit, or workflow fails in a way that may repeat, capture it before blind retries:
- Distinctive: line 123
Before retrying a similar failure:
- Distinctive: line 129
If the lesson is likely to repeat:
- Very specific: line 137
Read docs/FAILURE_LESSONS_PROTOCOL.md before changing this workflow.
- Very specific: line 151
Do not use broad PostToolUse for failure capture unless the target agent lacks a failure-specific lifecycle event.
- Very specific: line 167
Read docs/MCP_SERVER.md before changing MCP behavior.
- Distinctive: line 172
Update help output and command routing.
- Very specific: line 173
Add or update focused tests and wire them through test/smoke.mjs.
- Very specific: line 174
Update README.md, docs/ARCHITECTURE_NOW.md, and the relevant protocol doc.
- Very specific: line 194
Commit and tag vX.Y.Z.
- Distinctive: line 199
Keep these aligned with current capabilities:
- Very specific: line 216
When behavior changes, update docs in the same PR.
- Very specific: line 223
Read docs/ARCHITECTURE_GUARDIAN.md for code architecture or agent write scope.
- Very specific: line 224
Check docs/TROUBLESHOOTING.md if something fails.
- Very specific: line 225
Check development/BACKLOG.md before building planned modular work.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Instructions for AI coding agents working on or with the agent-kernel repository.
What this project is
agent-kernel is a local-first governance kernel for AI coding agents. It provides:
- shared JSON-first memory for rules, preferences, workflows, project notes, and skill triggers
- an approval inbox so agents can propose durable memory but the user approves it
- episodic memory for searchable session/project history
- Failure Lessons for turning repeated build/test/edit errors into reviewable rules, workflows, policies, or skill triggers
- Architecture Guardian for dependency boundaries, change contracts, reuse-first search, baselines, scoped exceptions, conformance reports, and pre-write scope hooks
- compiled guidance for Claude Code, Codex, Cursor, OpenCode, Antigravity, Gemini CLI, and other
AGENTS.md-compatible agents - Claude hooks, git hooks, MCP tools, and deterministic guardrails
- repo-local ECC scaffolding for Claude Code and Codex
Read these before non-trivial work:
docs/AGENT_RUNBOOK.mddocs/ARCHITECTURE_NOW.mddocs/OPERATING_MODEL.mddocs/ARCHITECTURE_GUARDIAN.mdfor non-trivial code changes or architecture enforcement- Relevant protocol docs for the area being changed
Use docs/TROUBLESHOOTING.md before changing runtime code to fix setup, linking, hook, MCP, architecture, or memory problems.
Source layout
agent-kernel/
├── src/cli.mjs # Core CLI source, single ESM file
├── dist/cli.mjs # Built CLI copied from src by scripts/build.mjs
├── bin/ # Public wrappers and focused helper binaries
├── bin/architecture-guardian/ # Wired Architecture Guardian engine modules
├── skills/ # Canonical installable skills, references, schemas, templates
├── scripts/ # Build, lint, version, and consistency checks
├── test/ # Smoke orchestrator + focused tests + architecture eval corpus
├── docs/ # Architecture, protocol, hook, MCP, integration docs
├── examples/ # Sample rules, episodes, hooks, contracts, policies, CI workflows
├── development/ # Roadmap and sprint planning
├── .claude/ # Repo-local ECC artifacts and workflow commands
├── .codex/ # Repo-local Codex ECC baseline and agent configs
├── .agents/skills/ # Codex-facing repo skills
├── .claude-plugin/ # Claude Code marketplace metadata
├── SKILL.md # Root Skills.sh / Claude skill discovery
├── skills.sh.json # Skills.sh grouping metadata
└── package.json # npm metadata and scriptsHard rules
- Do not add production code to
src/adapters/,src/commands/,src/core/, orsrc/hooks/unless you also wire the modularization into the runtime. Those folders are placeholders today. - Core runtime commands live in
src/cli.mjs. Focused helper binaries and explicitly routed helper subsystems inbin/are acceptable when the behavior is outside the current single-file runtime. - Do not hand-edit
dist/cli.mjs. Runnpm run buildafter changingsrc/cli.mjs. - Do not hand-edit generated guidance in
~/.agent-kernel/dist/or project-local generated files. Edit source memory and publish/sync/link. - Do not approve or publish memory from an agent hook. Hooks may capture evidence or create context. Approval is a user action.
- Do not auto-create or silently broaden Architecture Guardian baselines, contracts, policies, or exceptions. These are review artifacts.
- Do not attribute a baseline architecture finding to the current change unless the finding fingerprint is new.
- Do not use a broad permanent exception. Exceptions need a reason, owner, scope, and expiry.
- Do not commit secrets,
.envfiles,node_modules/, or private MCP credentials. - Keep repo-local ECC configs reviewable and credential-free.
- Search existing docs, code symbols, and tests before inventing new behavior.
Agent workflow
When a user asks for work in this repo:
- Classify the request: docs, runtime, helper binary, architecture, hook, MCP, safe-link, Failure Lessons, release, or repo maintenance.
- Inspect the relevant files before editing.
- For non-trivial code changes, run Architecture Guardian discovery and reuse search before creating new components.
- Use an active change contract when the policy requires one.
- Prefer a small coherent PR over a broad rewrite.
- Update docs and tests when behavior changes.
- Run Architecture Guardian conformance before commit when architecture-relevant files change.
- Capture repeatable failures instead of retrying blindly.
- Summarize changed files and fresh validation clearly.
See docs/AGENT_RUNBOOK.md for the detailed workflow.
Architecture Guardian protocol
Before creating a function, class, service, repository, adapter, validator, hook, state store, or utility for non-trivial work:
agent-kernel architecture doctor .
agent-kernel architecture discover . --json
agent-kernel architecture reuse "<business capability>" . --jsonWhen a change contract is required:
agent-kernel architecture contract init . \
--task "<reviewed task>" \
--owner "<domain or team>" \
--allow "src/area/**,test/area/**"Before commit:
agent-kernel architecture check . --jsonUse agent-kernel architecture baseline . only after reviewing known existing findings. Use exceptions only for a narrow, temporary, reviewed condition. Read docs/ARCHITECTURE_GUARDIAN.md and skills/architecture-guardian/SKILL.md before changing this workflow.
Failure Lessons protocol
When a command, test, edit, or workflow fails in a way that may repeat, capture it before blind retries:
agent-kernel failure capture \
--from <agent> \
--type test-failure \
--command "npm test" \
--exit-code 1 \
--text "<error output>" \
--root-cause "<why it happened>" \
--fix "<known fix step>"Before retrying a similar failure:
agent-kernel failure search "ERR_MODULE_NOT_FOUND"If the lesson is likely to repeat:
agent-kernel failure propose <failure-lesson-id> --as ruleAllowed promotion targets are rule, policy, workflow, skill, and note. Promotion creates a pending proposal only.
Read docs/FAILURE_LESSONS_PROTOCOL.md before changing this workflow.
Hook protocol
Claude failure capture should use:
PostToolUseFailurefor failed tool payloads- narrow matchers such as
Bash|Write|Edit|MultiEdit - exec-form command hooks with
command+args - short timeouts
- structured JSON output with
hookSpecificOutput.additionalContext
Architecture scope enforcement should use PreToolUse with a narrow Write|Edit|MultiEdit matcher. It may block writes outside the active contract, but it must not pretend to validate future file content.
Do not use broad PostToolUse for failure capture unless the target agent lacks a failure-specific lifecycle event.
Read:
docs/hooks/FAILURE_LESSONS_HOOK.mddocs/hooks/CLAUDE_HOOKS_BEST_PRACTICES.mddocs/ARCHITECTURE_GUARDIAN.md
MCP protocol
Agents may use MCP to inspect status, search memory, propose memory, list pending proposals, guard commands, and work with episodes where supported.
Approval through MCP is disabled by default. Do not enable it unless the user explicitly asks for a trusted local workflow.
Architecture Guardian currently uses CLI and hook surfaces. Do not add hidden MCP policy mutation or automatic exception approval.
Read docs/MCP_SERVER.md before changing MCP behavior.
Adding a new command
- Decide whether it belongs in core runtime (
src/cli.mjs) or as a focusedbin/helper. - Update help output and command routing.
- Add or update focused tests and wire them through
test/smoke.mjs. - Update
README.md,docs/ARCHITECTURE_NOW.md, and the relevant protocol doc. - Run
npm run build && npm test && npm run lint && npm run typecheck.
Install and verify
npm install
npm run build
npm test
npm run lint
npm run typecheck
npm run sizeRelease checklist
- Bump
package.json#version. - Bump
.claude-plugin/marketplace.jsonand.claude-plugin/plugin.jsonto the same version. - Update
CHANGELOG.md. - Run
npm run build && npm test && npm run lint && npm run typecheck && npm run size. - Commit and tag
vX.Y.Z. - Push the tag so release workflows handle npm and GitHub release publishing.
Discovery files
Keep these aligned with current capabilities:
README.md
SKILL.md
skills.sh.json
.claude-plugin/marketplace.json
.claude-plugin/plugin.json
.claude/skills/agent-kernel/SKILL.md
.claude/skills/architecture-guardian/SKILL.md
.agents/skills/agent-kernel/SKILL.md
.agents/skills/architecture-guardian/SKILL.md
skills/architecture-guardian/SKILL.mdDocumentation rule
When behavior changes, update docs in the same PR. docs/README.md explains which doc to update for each kind of change.
When in doubt
- Read
docs/AGENT_RUNBOOK.md. - Read
docs/README.md. - Read
docs/ARCHITECTURE_NOW.md. - Read
docs/ARCHITECTURE_GUARDIAN.mdfor code architecture or agent write scope. - Check
docs/TROUBLESHOOTING.mdif something fails. - Check
development/BACKLOG.mdbefore building planned modular work.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

