claude-init

Make any repo AI-native in one command.

Quick Start · What Gets Generated · Stack Detection · Contributing

Point claude-init at any existing codebase, run /claude-init, and get a complete Claude Code configuration — CLAUDE.md, agents, skills, rules, and hooks — all tailored to your stack, framework, and patterns.

Why

Every time you open Claude Code on an existing repo, you start from zero. Claude doesn't know your architecture, conventions, test commands, or deployment flow. You burn context re-explaining the same things every session.

claude-init fixes the cold start. One command analyzes your codebase, bootstraps a test suite if none exists, and generates everything Claude needs to work effectively from the first message.

No tests? No problem. If your repo has no test framework, claude-init picks the right one for your stack, installs it, and writes a baseline test suite covering your existing code. Tests are the trust layer — without them, AI coding is just vibes.

Quick Start

Install globally (recommended):

curl -fsSL https://raw.githubusercontent.com/yash-gadodia/claude-init/main/scripts/install.sh | bash

Then in any repo:

cd /path/to/your-repo
claude
/claude-init

What Happens When You Run /claude-init

1. Analyze — Scans your codebase in parallel: stack, framework, architecture, tests, CI, conventions
2. Bootstrap tests — If no test framework exists, installs one and writes a baseline test suite
3. Generate ARCHITECTURE.md — Creates AI-facing architecture documentation (system map, data flow, design decisions, module boundaries) if none exists
4. Generate .claude/ config — CLAUDE.md, agents, skills, rules, and hooks — all tailored to what was found
5. Report — Shows what was generated and suggests next steps

After setup, Claude automatically follows a development workflow (clarify → plan → TDD → verify → review → finish) scaled to task size. No slash commands needed — but you can invoke any step manually:

Or install manually:

git clone [email protected]:yash-gadodia/claude-init.git ~/claude-init
cp -r ~/claude-init/.claude/skills/{claude-init,onboard,update,doctor} ~/.claude/skills/
cp -r ~/claude-init/templates ~/.claude/claude-init-templates

Or load as a plugin (skills arrive namespaced as /claude-init:claude-init etc.):

git clone [email protected]:yash-gadodia/claude-init.git ~/claude-init
claude --plugin-dir ~/claude-init

Commands

What Gets Generated

ARCHITECTURE.md

AI-facing architecture documentation at the repo root. Not loaded every conversation (that would waste tokens), but read on demand by /plan, /onboard, and the architect agent when deep context is needed. Contains system overview, directory map, data flow, design decisions, module boundaries, and entry points. Under 120 lines.

CLAUDE.md

A lean (under 80 lines) project file containing actual commands, architecture, conventions, and patterns found in your codebase. Every line earns its place. References ARCHITECTURE.md for deeper context.

Agents

Model-tiered personas that know your stack:

Skills

Auto-triggered by the workflow rule — Claude follows these automatically, scaled to task complexity. Users can also invoke manually.

Rules

Project-specific rules — only generated when they'd prevent Claude from making a mistake on your project:

Safety Hooks

Deterministic, command-based guardrails — minimal to avoid friction:

Always: Block writing to .env*, .pem, .key, .cert, credential files

Team projects (>1 contributor): Block git push --force, npm publish, docker push, terraform destroy. Deny reading ~/.ssh/, ~/.aws/, ~/.gnupg/

Solo dev: Minimal hooks only — no false positives on legitimate commands

Stack Detection

Analyzes and tailors config for:

Design Principles

Auto-triggered workflow — Generated workflow.md rule makes Claude automatically follow clarify → plan → TDD → verify → review → finish, scaled to task size. No slash commands needed.

Rationalization prevention — Every skill includes "Red Flags — STOP" tables listing the exact thoughts that signal an agent is about to skip process discipline. Inspired by obra/superpowers.

Spec persistence — The clarify skill saves specs to docs/specs/, dispatches a reviewer subagent, and gates on user approval before planning. Specs become artifacts that plans trace back to.

Progressive disclosure — Skill descriptions are ~100 tokens (always loaded). Full instructions load only when invoked. Skills over ~150 lines push long examples and scripts into sibling reference files so bundled-but-unread content costs nothing at startup.

Trigger-first descriptions — Generated skill descriptions are third-person and carry an explicit Use when… / Auto-triggered… trigger, the field Claude matches against for discovery. /doctor flags descriptions that lack one.

Correct hook schema — Safety hooks use the current hookSpecificOutput.permissionDecision form (allow/deny/ask/defer), not the legacy top-level decision field that PreToolUse silently ignores. An optional tdd-guard hook is available for teams wanting hard tool-level test-first enforcement.

Stack-aware — Every reference points to real commands, real file paths, and real patterns from your actual codebase.

AGENTS.md interop — If the target repo already has an AGENTS.md for other coding agents, /claude-init symlinks rather than duplicates, so every tool reads one source of truth.

Model-tiered agents — Opus for architecture. Sonnet for implementation and review. Haiku for exploration and docs. Templates use model aliases (opus/sonnet/haiku), so they track the current generation automatically.

RALPH loop — Developer agent uses Read-Act-Log-Pause-Hallucination-check for self-correction.

Non-destructive updates — /update re-analyzes without overwriting customizations.

Template sync — generated configs are static copies, so template fixes don't auto-propagate. /update includes a template-sync step that scans an existing project for known-stale generated patterns (e.g., the legacy {"decision":...} hook form) and proposes fixes — tagged (template sync), applied only on approval. Re-run install.sh first to pull the latest templates, then /update (or /doctor to just report) in each project.

Extras

Self-Learning Loop

The repo improves itself. A weekly GitHub Action (.github/workflows/self-learn.yml) runs Claude against the ecosystem — the Claude Code changelog, official docs, and the best comparable repos (superpowers, trailofbits/claude-code-config, awesome-claude-code) — and proposes at most one evidenced improvement per week as a PR. It never merges anything itself.

• LEARNINGS.md is the loop's memory: adopted ideas, rejected ideas (with reasons, so they're never re-proposed), and last-checked dates per source
• Guardrails: one idea per cycle, ≤200 changed lines, mandatory citations, self-tests must pass, human review gate
• Setup: add an ANTHROPIC_API_KEY repo secret; trigger manually once via the Actions tab (workflow_dispatch) to validate

Development

The repo ships a zero-dependency test suite that validates its own templates, skills, agents, hooks, and installer — the same idea as the generated /doctor check, turned inward. Run it before opening a PR:

bash tests/run.sh

No dependencies are required; python3/node are used only for JSON validation when present. CI runs the suite on every push and PR via .github/workflows/test.yml.

Contributing

PRs welcome. If you've battle-tested this on a stack we don't cover well, improvements to the templates and detection logic are especially useful.

Thanks

People and projects that shaped this:

• Shaun Chong, CTO @ Ninja Van — 4-stage agent pipeline architecture, RALPH loop concept, "tests as trust layer" framing
• Trail of Bits' claude-code-config — security-first defaults
• obra/superpowers — rationalization prevention, spec review loops, TDD discipline, subagent status protocol, finish workflow, progressive disclosure
• snarktank/ralph — RALPH autonomous loop
• nizos/tdd-guard — hook-level test-first enforcement (optional template)
• Anthropic's official skill & hook docs — progressive disclosure, third-person trigger descriptions, the hookSpecificOutput decision schema

License

MIT