AI coding agents are fast. If you've reviewed enough agent-written diffs, though, you've seen the same short list of failures show up again and again:
await
that turns an async call into a race you only find in production.as any
sprinkled in wherever the types didn't line up.package.json
.try/except: pass
wrapped around failing code to make a red test go green.git reset --hard
that eats uncommitted work.You can keep catching these in review, one diff at a time, forever. Or you can make the codebase itself push back the moment the agent writes them. That second option is what agent-starter sets up, and most of it lands in one command.
/plugin marketplace add sneg55/agent-starter
/plugin install agent-starter@agent-starter
That wires five enforcement hooks and loads eight slash commands. Then you point it at a codebase: /new-project
for a fresh repo, /adopt-project
to retrofit an existing one (it audits first, everything is opt-in, nothing gets overwritten).
The rest of this post is what that command actually does, and why each piece is there.
Claude Code hooks run shell scripts at defined points in the agent's loop: before a Bash command, after a file write, at session start. agent-starter ships them as small, dependency-light bash scripts. The ones that earn their keep:
block-dangerous-commands.sh
runs before any Bash command executes. It blocks the short list of things that destroy work you can't get back:
git push --force
(it points you at --force-with-lease
instead)git reset --hard
/ --merge
git clean -f
, git checkout -- .
, git restore .
rm
on /
, ~
, or $HOME
chmod -R 777 /
When it fires, the agent sees this on stderr and stops:
Blocked dangerous command:
git push --force origin main
Why: 'git push --force' rewrites remote history - use --force-with-lease.
There's an escape hatch (CLAUDE_ALLOW_DANGEROUS=1
) for the rare time you actually mean it. The goal isn't to babysit. It's to make the destructive path require a deliberate override instead of a stray token in a long autonomous run.
check-silent-errors.sh
runs after every write. LLMs reach for try/except
to make a failing test pass, but the code still breaks, just quietly, in a way nobody notices until later. The hook blocks the patterns that swallow errors:
except:
, except: pass
, except: ...
in Pythoncatch {}
in JS/TScatch
block whose only body is console.log
(logging an error at info severity is still swallowing it)Every handler has to do something real: re-raise, return a sentinel, or log with context via console.error
. One-off exceptions are explicit. You drop a // silent-ok
(or # silent-ok
) comment and the hook leaves that site alone. Because the exemption lives in the diff, it shows up in review instead of hiding.
This is the idea worth stealing even if you take nothing else from the repo.
Most projects treat lint as a CI gate: the agent writes a whole feature, opens a PR, CI goes red, and by then the agent has moved on to something else. The correction is expensive and out of context.
agent-starter runs lint on every single edit. lint-on-edit.sh
runs biome check --write
then eslint --fix
on just the file the agent touched, and pipes any remaining errors back on stderr. The agent reads them on its next turn and fixes them while the context is still warm. Python gets the same treatment with ruff check
then ruff format
.
The ruleset is tuned for the mistakes agents actually make, not for taste:
no-floating-promises
, no-misused-promises
, await-thenable
. That's the dropped-await
class, caught at write time.import/no-unresolved
flags an import from a package that doesn't exist; import/no-extraneous-dependencies
flags one that isn't declared.no-explicit-any
plus the no-unsafe-*
familyas any
escape hatch, so the agent has to fix the type shape instead of routing around it.require-description
), so an eslint-disable
can't quietly become the path of least resistance.And a deliberate omission: no max-lines
. Line caps punish coherent long code (a reducer, a parser, a JSX-heavy component) and reward the agent for shredding logic into single-use helpers that only make sense read together. Cognitive complexity, capped at 15, measures the thing you actually care about.
Biome owns formatting and the fast syntactic rules (it's 10 to 100 times faster than ESLint); ESLint owns the type-aware rules that need the compiler. You get the speed on every keystroke and the depth where it counts.
check-file-size.sh
warns when a file crosses a size target, since oversized files are where agents lose the thread. check-codebase-health.sh
runs at session start so the agent opens with context instead of discovering problems mid-task. There's also an opt-in read-before-edit guard (./install.sh --with-read-guard
) for older setups; recent Claude Code enforces read-before-edit natively, so it's left out of the default install on purpose.
Guardrails stop bad writes. Context prevents them. The CLAUDE.md
template ships a 4-type memory system so what the agent knows about your project is structured, not a scratchpad:
| Type | Holds |
|---|---|
| user | |
| who you are: role, preferences, level | |
| feedback | |
| how to work: corrections and confirmations, with the reason why | |
| project | |
| what's happening: ongoing work, decisions, deadlines | |
| reference | |
| where to look: pointers to Linear, Grafana, Slack |
Two rules keep it honest. Never store what's derivable from code or git, because that copy goes stale and starts lying. And convert relative dates to absolute, because "last week" is meaningless three sessions later. feedback
memories carry a Why and a How to apply, so a correction you give once keeps applying itself.
Everything above is a good frozen setup. The reason I built this instead of copying a pile of dotfiles is the loop on top.
Most starters are a snapshot. Every project begins from the same rules and never gets smarter about how this codebase is actually used. agent-starter captures that signal and turns it into better rules. Four steps:
① signal → ② store → ③ promote → ④ measure → (back to ①)
▲ │
└──────────────────────────────────────────────┘
await
, swallowed error, dangerous command), it appends one JSON line to .harness/ledger.jsonl
. Logging is best-effort and always exits 0, so it can never break the hook that called it. Your explicit corrections are already captured as feedback
memories, which are the highest-value signal of all./reflect
skill reads the ledger and your feedback memories, clusters the recurring mistakes, and recurring_events
metric, and each reflection snapshots it to .harness/reflections/
. The next reflection can check whether a rule you added last time actually reduced the mistake it targeted, so the loop closes instead of just piling up well-meaning rules nobody validated.The principle underneath it: signal is private (the gitignored ledger), wisdom is shared (the committed reflections and the rules they produce). A project scaffolded with /new-project
is born with this wired in.
The base patterns aren't invented. A lot of them are reverse-engineered from the Claude Code CLI's own source: the file-size targets, the tool-per-directory layout, the lint tiering. Those are marked "derived from Anthropic's Claude Code source" in the repo. The self-improvement loop and the extra tooling are added on top.
Pick the entry point that matches what you want:
npx skills add sneg55/agent-starter -a claude-code -g
~/.claude
:./install.sh
. It merges its settings wiring idempotently, so re-runs never duplicate entries.Repo: github.com/sneg55/agent-starter, MIT licensed.
If you already work with an AI agent every day, the single highest-leverage piece is lint-on-edit
. Move your linter out of CI and into the agent's write loop, and watch how much never reaches review in the first place.