agent-starter

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.
• eslint.shadcn.mjs (opt-in, Tailwind v4 + React). Spreads @shadcn/lint into the ESLint config: no raw palette colors, no arbitrary values, no inline styles, no unknown classes, no restyling design-system components via className. /new-project asks about it for UI stacks; /adopt-project offers it when Tailwind v4 is detected.
• 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 ①)
   ▲                                              │
   └──────────────────────────────────────────────┘