Why this kit?

Most "agent setups" are a pile of suggestions — the rules sit in a file, and whether they're honored is left to the model. This kit is different: it drops a disciplined engineering team into Claude Code, where the rules that matter are gates, not reminders — it doesn't just tell the agent the rules, it makes breaking the critical ones impossible, and it installs safely onto the repo you already have.

🧠 The agents — the heart of the kit

11 agents, each a thin trigger — it says only who and when, and delegates the how to a skill. The main thread selects and chains them across five stages, escalating quality before anything is committed:

🧭 Understand  →  🔨 Produce  →  🔍 Audit  →  ✅ Close  →  🤝 Hand off

Agent names carry a -csk suffix (Claude Starter Kit) so they never collide with the host project's own agents. Each agent is thin; the real method lives in a skill — the single source of truth.

Three principles

1. Agent = thin trigger. An agent only says "who, when"; it stays short and leaves the "how" to a skill.
2. Skill = single source of truth. The actual method and rule live in the skill; they are not copied into the agent.
3. Rule → gate. The rule that matters is enforced at the tool level (hook · permission · eval). The model is not expected to remember it.

Install & run

Two entry points: start.sh sets up a fresh project; adopt (adopt.sh) hands the kit over to an existing one. Pick any channel — each runs the same two commands.

npx — nothing to install:

npx @byerlikaya/claude-starter-kit          # fresh project
npx @byerlikaya/claude-starter-kit adopt    # existing project
npx @byerlikaya/claude-starter-kit@latest update   # refresh a project that already has the kit

Homebrew:

brew install byerlikaya/tap/claude-starter-kit
claude-starter-kit          # fresh project
claude-starter-kit adopt    # existing project

Release tarball — no package manager:

gh release download --repo byerlikaya/claude-starter-kit -p '*.tgz' && tar xzf claude-starter-kit-*.tgz
bash start.sh               # fresh project
bash adopt.sh              # existing project

Just want the agents & skills inside your existing Claude Code (no scaffolding)? /plugin marketplace add byerlikaya/claude-starter-kit then /plugin install claude-starter-kit@byerlikaya.

Windows: the kit is bash-based — run it inside Git Bash (from git-scm.com) for the smoothest experience; WSL works as a fallback.

🌱 Fresh project — start.sh

bash start.sh [--backend|--frontend|--mobile|--fullstack] [--dotnet|--generic] [-h]

An install wizard. With no flags it walks each step (profile → backend stack → summary and approval); the flags are for silent/CI use, and -h / --help prints usage. Every choice shows what it will install before installing it.

After install, paste .claude/FIRST_PROMPT.md as your first Claude Code message — an optional kickoff that verifies the agents/skills and plans the first sprint. (CLAUDE.md loads the discipline every session regardless, so this is a one-time convenience, not a requirement.)

There is no separate mobile agent: frontend-expert-csk covers web, mobile and desktop, and the mobile how lives in the frontend-rn-expo skill. --fullstack installs it too, so a fullstack project is ready for mobile without picking --mobile.

The backend stack is asked only for --backend/--fullstack: --dotnet brings the .NET / DevArchitecture pattern (MediatR CQRS · IResult · AOP) behind an approval gate; --generic installs the same expert without it — for Node, Go, Python, or a .NET project on a different pattern.

.NET — start proven, not from scratch. --dotnet clones the production-ready DevArchitecture foundation (CQRS · IResult · AOP · auth) and installs agents that already know it — so you skip the tokens an agent would burn regenerating a standard architecture; they go to your business logic, not boilerplate. Opinionated by default, not by force: the backend expert applies your project's pattern skill — DevArchitecture out of the box, or your own (Clean Architecture, Vertical Slice, Minimal API, plain layered) dropped into .claude/skills/. --generic stays stack-agnostic.

On --fullstack + --dotnet the DevArchitecture backend is placed in ./backend, ./frontend is reserved for your frontend, and the solution file is renamed to your project's name — so the project root stays clean instead of looking like a bare backend.

🔄 Existing project — adopt.sh

bash adopt.sh          # at the root of the target project

Applies the kit to a project already in motion, like one team handing a project over to another — the project is not broken, decisions already made are not lost, and the kit does not stay passive.

All changes land on a separate git branch staged, not committed — so every added and changed file shows up in your editor's Source Control / Changes panel; you review it there, then git commit to accept (or reset to discard). main stays untouched. Kit agents install side-by-side (never colliding), the discipline is bound via a single @import, settings.json is merged schema-aware, and existing husky/lefthook chains run alongside the kit via a shim. It closes with a durable docs/HANDOVER.md and an ADR, so decisions live in version control, not in a chat.

🔁 Update an installed project

npx @byerlikaya/claude-starter-kit@latest update    # `update` is an alias of `adopt`; run it at the project root

At install time the kit stamps .claude/kit.conf with the profile, the backend stack and which installer ran, plus .claude/VERSION. The updater reads that stamp and refreshes the project in the shape it was installed in: a --backend project does not get frontend agents grafted back on, and a --dotnet project keeps its devarch-module pattern skill. Where the stamp is absent, the updater derives the shape from the installed files and writes it. Compare cat .claude/VERSION against npm view @byerlikaya/claude-starter-kit version to see whether an update is waiting.

Like adopt, an update needs a git repo and lands on a kit-adopt-<timestamp> branch, staged and uncommitted — review the diff, then commit to accept or reset to discard.

If a project's CLAUDE.md carries the discipline inline instead of importing it, discipline updates cannot reach that project. The updater detects this, shows which lines hold the inline block, and offers to replace them with the single @.claude/DISCIPLINE.md import — writing a backup first, on a branch you review. Decline and nothing is touched; your project section and your own rules survive either way.

What's inside

• 11 agents — see the table above.
• 30 skills — the single source of "how", one per area (full catalogue below).
• 6 slash commands — /brainstorm · /plan · /review · /ship · /handoff · /simplify.
• Hooks — guard-bash.sh (tool-level gate), pre-commit + commit-msg (trace + secret scan), context-usage.sh and session-guard.sh (session measurement).
• CLAUDE.md — behavior, the three principles, workflow, Definition of Done, token discipline, and prohibitions.

Session & token management

An assistant cannot run /context itself, so most setups guess the session fill. This kit measures it. context-usage.sh reads the real token count from the last turn's API usage in the transcript — the same figure /context shows. The UserPromptSubmit hook injects it every turn; the Stop hook (session-guard.sh) warns you the first time fill crosses 75%, and once more at 90% — one warning per threshold, and it never blocks your turn. The session-health line rests on a measurement, not a guess.

Token cost

DISCIPLINE.md and the agent/skill descriptions load into every session's context. That always-on material measured 9,198 tokens on a real turn for 11 agents and 28 skills; brainstorm and reflect add ~660 bytes (≈ 280 tokens) on top — the price of the whole discipline layer.

smoke-test.sh enforces a byte budget per component (discipline · agent descriptions · skill descriptions), so the cost cannot drift upward unnoticed. A budget can be raised, but only by editing smoke-test.sh explicitly.

Profile pruning does not save tokens. A --backend install (10 agents, 27 skills) costs only ~640 tokens less than --fullstack (11 agents, 30 skills). Pick a profile to narrow the scope of the work.

Rule → gate

The gates are armed via settings.json and git core.hooksPath; smoke-test.sh verifies they are ready after every change.

Verification

bash .claude/eval/smoke-test.sh      # structure, frontmatter, gate integrity
bash .claude/eval/routing-eval.sh    # does an example prompt route to the right agent/skill

Workflow

/plan (ambiguous scope) → expert agents build → /review (security · quality · test) → /ship (DoD gate; proposes the commit, waits for approval) → when context fills up, /handoff → /clear.

Extending

When you add an agent or skill, follow the AGENT_TEMPLATE.md contract: frontmatter (name · description + Trigger phrases · least-privilege tools · model tier) and body (When → Expertise stance → How/skill → Coordination → DoD → Output & context → Errors/escalation → Example → Constraints).

License & attribution

MIT — see LICENSE. The discipline layer builds on these upstream sources:

• DevArchitecture — the backend pattern (MediatR CQRS / IResult / AOP), referenced as a pattern only.
• multica-ai/andrej-karpathy-skills — the four working principles at the core of the discipline.
• google/eng-practices — the code-review skill, distilled and restated (CC-BY 3.0).