henryzhangpku/agent-starter

A small kit for running a coding agent (Claude Code, or any agent that reads a
CLAUDE.md) the way you would run an engineer you have just hired: a written
working agreement, guardrails enforced by code rather than by asking nicely, a
reviewer that did not write the code, and a plan and decision log a human can
read afterwards.
One command drops it into any project, on any fresh machine, without
overwriting anything that is already there.
macOS / Linux / WSL / Git Bash:
Windows PowerShell:
Requirements: Python 3 for the hooks (standard library only) and, ideally, pytest.
A build day in one command
A teammate brings a problem (a spike, a hackathon, a pairing day); you have a
few hours to build it with an agent while they watch and weigh in. Bootstrap an empty folder, start claude, and type
**/step** again and again. It walks the day in order (capture the prompt,
ask the questions that matter, plan, failing acceptance tests, split into
parallel tasks, build, demo prep), checks in every 30 minutes, stops at each
point where a human should decide or speak, and asks when it needs input.
Every reply ends with what to say to the room and what happens next.
One page: template/COMMANDS.md.
**Starting a build day.** A brand-new problem: mkdir -p ~/repo/ && cd ~/repo/ ,
run the bootstrap line above, copy in whatever you were handed (read-only inputs in data/),
git init -q && git add -A && git commit -qm start && claude, then /step. Their existing
repo: clone it, branch, run the bootstrap line, commit, claude, then /onboard and /step.
What you get
**Every day, in any repository** (on as soon as it is installed)
| file | job |
|---|---|
| CLAUDE.md | the working agreement: plan first, small steps, tests before code, never weaken a test, the model proposes and code decides, one module calls a model, one task per session. Plus project facts you fill in |
| .claude/settings.json | wires the hooks below |
| .claude/hooks/guard.py | **PreToolUse, edit tools AND shell:** refuses changes to protected inputs and locked acceptance tests, and in a lane anything outside the lane's paths (exit 2, reason shown to the agent). A blocked Edit cannot be routed around with sed -i, >, cp or a one-line script. Paths in .claude/guard.json |
| .claude/hooks/run_tests.py | **PostToolUse:** runs the tests after every edit; the whole suite while it takes under 20 s, only the edited file's tests once it is slower, nothing for prose. Failures go straight back to the agent. "test_scope": "all"/"changed" in guard.json overrides |
| .claude/hooks/context_budget.py | **UserPromptSubmit:** silent until the session's context passes 150k tokens, then tells the agent to suggest NOTES.md and a fresh session; at 300k it asks it to wrap up first. Thresholds in guard.json |
| .claude/agents/reviewer.md | read-only reviewer with a fresh context: an agent grading its own work passes itself |
| .claude/skills/ | loaded on demand when a problem mixes them in: **sql-and-schema** (read a handed-over database, schema, idempotent writes, indexes), **async-concurrency** (task graphs, cancellation, timeouts, limits), **reliability** (retries, idempotency, Docker, health checks, Kubernetes on paper), **team-repo** (working in their repo with teammates) |
| PROMPT.md, PLAN.md, NOTES.md, DECISIONS.md | the request and answers; the plan with a test per step; state across /clear; what was proposed, chosen, and why |
| /next | take the next plan step, plan first |
**Build day (opt-in: silent until you start the clock)**
| file | job |
|---|---|
| .claude/kit/CARD.md | the whole day on one page: what to do and what to say at each moment; keep it open |
| .claude/kit/RUNBOOK.md | the build day step by step, with modes for a new problem, an existing codebase, team mode and shipping; time boxes, copy-paste prompts, the commit that closes each phase |