agent-starter

Skills, hooks, templates, and engineering guides for bootstrapping AI-agent-friendly projects, with a per-project self-improvement loop.

What it is

A toolkit for setting up projects that AI agents can work in safely and productively. It scaffolds new projects, retrofits existing ones, and ships enforcement hooks, drop-in configs, and engineering patterns. The differentiator is the self-improvement loop: scaffolded projects capture signal from their own usage and turn it into better rules over time.

Component	What it does	Where
Skills	8 slash commands: scaffold, adopt, commit, reflect, remember, dream	skills/
Hooks	Enforcement (lint, file-size, dangerous-command) + signal capture for the loop	hooks/
Templates	Drop-in configs: Biome, ESLint, ruff, pyright, CLAUDE.md, env boundaries	templates/
Guides	9 engineering patterns for AI-agent codebases	guides/
Self-improvement loop	Projects learn from their own usage and propose their own rules	across the above

Provenance: patterns marked "derived from Anthropic's Claude Code source" are reverse-engineered from the Claude Code CLI; everything else is added on top. See About.

Quick start

This repo doubles as a Claude Code plugin marketplace. Installing the plugin is the recommended path: it loads every skill and wires the enforcement hooks in one step.

/plugin marketplace add sneg55/agent-starter
/plugin install agent-starter@agent-starter

Then run /new-project (new codebase) or /adopt-project (existing one).

Install

Pick the path that matches what you want:

I want...	Do this
Everything (skills + hooks), one step	Plugin install, see Quick start
Just the skills, globally	npx skills add sneg55/agent-starter -a claude-code -g
Just the hooks in ~/.claude	git clone …/agent-starter && cd agent-starter && ./install.sh
To point an agent at the repo	See the table below

Point an agent at the repo

No install needed. Give an agent the repo URL and it reads the matching entry file and drives the setup interactively (audit-first, opt-in, nothing overwritten):

Situation	Say	Agent reads
New project	"read this repo and set up my project https://github.com/sneg55/agent-starter/"	AGENT.md
Existing project	"read this repo and apply it to my project"	ADOPT.md
Whole team	ship the setup with the repo so everyone gets it from a git pull	TEAM.md

TEAM.md is the companion to ADOPT.md: where ADOPT.md installs into one developer's ~/.claude, TEAM.md vendors the setup (hooks, shared config, plugin defaults) into the repo itself.

Notes on the plugin and hooks

• The plugin wires five enforcement hooks (file-size, lint-on-edit, silent-error, dangerous-command, codebase-health) plus a /loop instruction-review hook, all from hooks/hooks.json.
• The read-before-edit guard pair is left out of the plugin on purpose (recent Claude Code enforces read-before-edit natively). Opt into it with ./install.sh --with-read-guard.
• install.sh merges its settings.json wiring idempotently via jq, so re-runs never duplicate entries.

Components

Skills

Install all skills globally with npx skills: npx skills add sneg55/agent-starter -a claude-code -g (or get them via the plugin).

Skill	What it does
/new-project	Interviews you, then scaffolds directory structure, CLAUDE.md, configs, hooks, skills, and the first commit. Mirrors AGENT.md.
/adopt-project	Audits an existing codebase, proposes components grouped by invasiveness, applies only what you approve. Mirrors ADOPT.md.
/commit	One well-crafted commit: analyzes the diff, follows repo style, writes a "why not what" message. Includes the Git Safety Protocol.
/commit-push-pr	Full git flow: branch, commit, push, and create/update a PR with summary and test plan.
/simplify	Spawns 3 parallel agents (Code Reuse, Quality, Efficiency) to review your diff and fix issues.
/reflect	The promote step of the loop: reads the .harness ledger and feedback memories, clusters recurring mistakes, proposes gated rule/threshold/lint/ADR changes.
/remember	Scans auto-memory and proposes promotions to CLAUDE.md, CLAUDE.local.md, or shared memory. Detects duplicates, stale entries, conflicts.
/dream	Memory consolidation: merges, prunes, and re-indexes memory files across four phases (orient, gather, consolidate, prune).

Hooks

Ready-to-use hook scripts in hooks/. The plugin wires the nine defaults; install.sh wires them into ~/.claude, and four more are opt-in behind flags. See guides/hooks-reference.md for the hook system itself. Needs jq and python3.

Hook	Fires on	What it does
check-file-size.sh	Write/Edit	Warns when a file exceeds size targets. Per-project overrides via .harness/file-size.conf.
lint-on-edit.sh	Write/Edit	Lints + typechecks the file just written.
check-silent-errors.sh	Write/Edit	Blocks writes that introduce swallowed/silent error handling.
block-dangerous-commands.sh	Bash	Blocks destructive shell commands before they run.
rm-scope-guard.py	Bash	Blocks rm whose targets escape the working directory; allows the rest.
check-codebase-health.sh	Session start	Surfaces codebase-health signals at the start of a session.
worktree-session-prompt.sh	Session start	Reports whether this is the shared main checkout or a worktree, and asks before editing the shared one.
worktree-exit-offer.sh	Stop	Offers to leave a worktree once it is clean and fully pushed.
suggest-loop-improvements.sh	Prompt submit	On /loop, injects an instruction-review step.
track-reads.sh + require-read-before-edit.sh	Read / Write+Edit	Opt-in (--with-read-guard): blocks edits to files not read this session.
check-new-comments.py	Write/Edit/MultiEdit	Opt-in (--with-comment-guard): blocks edits that add comments or docstrings. Toolchain directives pass.
check-em-dash.py	Write/Edit	Opt-in (--with-em-dash-guard): blocks em dashes in .md / .mdx / .markdown.
lib/log-event.sh	called by hooks	Appends one JSON event to .harness/ledger.jsonl (the loop's signal capture).
harness-ledger-stats.sh	on demand	Computes the recurring_events metric over the ledger, merged across worktrees.

Templates

Drop-in configs in templates/. Copy the ones you need.

Lint (paired with guides/lint-rules-for-ai.md):

• biome.jsonc + eslint.config.mjs (TypeScript). Biome owns formatting and fast syntactic rules; ESLint owns type-aware correctness (no-floating-promises, the no-unsafe-* family), import resolution (catches hallucinated modules), and security rules.
• ruff.toml + pyrightconfig.json, the Python counterpart. Ruff owns formatting and fast rules; pyright (strict) owns type-aware analysis.

Error handling & boundaries:

• errorIds.ts / error_ids.py: central error-ID registry + AppError; every throw references a stable E_DOMAIN_NNN that stays searchable across rewordings. Pairs with guides/error-id-registry.md.
• env.ts / env.py: single env-var boundary; Zod/pydantic schema is the source of truth, invalid env fails loudly at startup. Pairs with guides/zod-at-the-boundary.md.

Context & scaffolding:

• truncate-for-context.ts / truncate_for_context.py: head+tail truncator for tool output so cat large.log and npm test don't blow the context window.
• CLAUDE.md: project-instructions template with the full 4-type memory taxonomy, file format, and git safety rules. Also carries the working rules that hooks cannot enforce: verify a problem before reporting it, how to pick a subagent's model, one worker per worktree, freeze a shared contract before parallel dispatch, never commit internal documents to a public repo, and what to do when a classifier blocks a tool call. An optional response-style section (lead with the ask, no time estimates, no made-up numbers, no uninvited docs) sits at the end for deleting if it is not your taste.
• NEW_PROJECT_PROMPT.md: copy-paste prompt to scaffold a project from scratch. Fill in the {{placeholders}}.

Guides

Engineering patterns in guides/.

Guide	What it covers
large-codebase-best-practices.md	Directory structure, file-size targets, naming, error handling, CLAUDE.md hierarchy. Derived from Anthropic's Claude Code source.
lint-rules-for-ai.md	Tiered Biome + ESLint (and ruff + pyright) rules that block the mistakes LLMs make: dropped awaits, any escape hatches, hallucinated imports, half-finished functions.
hooks-reference.md	The Claude Code hook system: 4 hook types, all 27 events, exit-code behavior, config format, 10 worked examples.
tool-authoring-pattern.md	The BashTool/-style directory-per-tool layout extracted from Claude Code's source.
error-id-registry.md	Stable error IDs (E_CFG_003) shared across logs, telemetry, docs, and agents.
discriminated-union-results.md	Result<Ok, Err> as the one shape every fallible function returns, exhaustiveness-checked by the compiler.
abort-signal-threading.md	Threading AbortSignal through long-running calls so Ctrl+C, timeouts, and obsoleted work actually stop.
prompt-caching.md	Structuring prompts so Anthropic's prefix cache hits 80%+, plus the silent cache-breakers to avoid.
zod-at-the-boundary.md	Validate external data once, at entry; the schema is the source of truth for the type.

The Self-Improvement Loop

New, added on top of the original Anthropic patterns.

Most starters are a frozen snapshot: every project begins from the same patterns and never learns from how it's actually used. agent-starter ships the machinery for each scaffolded project to improve itself from its own signal.

The loop has four parts. The first three reuse the existing memory + hooks system; only signal capture and measurement are new.

 ① signal → ② store → ③ promote → ④ measure → (back to ①)
   ▲                                              │
   └──────────────────────────────────────────────┘

• ① Signal. hooks/lib/log-event.sh appends one JSON event to the project's .harness/ledger.jsonl every time an enforcement hook blocks or warns (file too large, lint failure, swallowed error, edit-before-read). It's best-effort and always exits 0, so logging can never break a hook. Your explicit corrections are already captured as feedback memories, the highest-value signal.
• ② Store. The append-only ledger (structured events) plus the existing memory files (prose knowledge). The raw ledger is gitignored (local and noisy); distilled learnings are committed.
• ③ Promote. The /reflect skill reads the ledger and your feedback memories, clusters recurring mistakes, and proposes concrete changes for your approval: a new project rule, a hook-threshold tweak, a lint rule, or an ADR. Nothing is auto-applied, you stay in the loop on every change.
• ④ Measure. hooks/harness-ledger-stats.sh computes a recurring_events metric (mistakes that fall in recurring (rule, path-prefix) clusters). Each reflection records a snapshot to .harness/reflections/YYYY-MM-DD.md, so the next reflection can confirm a promoted rule actually reduced the mistakes it targeted.

The principle: signal is private (gitignored ledger), wisdom is shared (committed reflections and the rules they produce). New projects scaffolded via AGENT.md / /new-project are born with the loop wired in.

Memory Taxonomy

The CLAUDE.md template uses a 4-type memory system:

Type	Scope	What belongs
user	Who they are	Role, goals, preferences, knowledge level
feedback	How to work	Corrections AND confirmations, both what to avoid and keep doing
project	What's happening	Ongoing work, deadlines, incidents, decisions
reference	Where to look	Pointers to external systems (Linear, Grafana, Slack, etc.)

Key principles:

• Never save what's derivable from code/git
• Convert relative dates to absolute
• Structure feedback with Why + How to apply
• Verify memories against current state before acting on them

About

agent-starter started as Anthropic's own engineering patterns, extracted from the Claude Code CLI source and packaged into reusable form. It has since been extended with additional best practices, tooling, and original ideas that go beyond the source material, the flagship being the self-improvement loop. Patterns marked "derived from Anthropic's Claude Code source" are reverse-engineered from the real thing; everything else is added on top.

Licensed under MIT.