claude-base

Make Claude Code follow a real engineering workflow — Explore → Specify → Plan → TDD → Audit → Commit — with guardrails that test-first, audit to a quality score, and block high-confidence secrets + destructive commands automatically.

Most Claude Code setups add more agents. claude-base adds discipline and safety: per-file rules, hooks, and an anti-drift CI gate. One install, auto-detects your stack — and it learns from your mistakes across every project so you stop repeating them.

What it takes off your plate, every session:

• re-explaining your standards — a human-gated lessons store carries them across all your projects, so a mistake fixed once doesn't come back;
• the agent "passing" its own checks with a hollow test, a stub, or a quietly-weakened linter — the anti-gaming layer refuses the weakened linter config and flags the hollow test or stub back to the agent the moment it is written;
• finding it in review — a known provider key written into a file, a git commit over a failing npm / pytest / go suite, or the --no-verify flag is stopped at the hook, before it lands.

A real curl | bash install + claude-base init scaffolding the foundation into a project — start to finish.

Try it (30 seconds)

Requires: bash 4.0 or newer, git and jq on your PATH — claude-base init refuses to run without them (it reads JSON manifests with jq). ⚠️ macOS ships bash 3.2 as /bin/bash: the installer in step 1 runs fine on it, but claude-base init in step 2 stops with "Bash 4.0+ required", so install a current one first (brew install bash). Plus the Claude Code CLI — init itself only needs it to install a preset's marketplace plugins, and warns and skips when it is absent, but you need it to use the foundation afterwards.

# 1. Install the foundation (clones to ~/.local/share/claude-base, symlinks to ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/christopherlouet/claude-base/main/install.sh | bash
claude-base version          # ✓ should print the installed version, e.g. claude-base vX.Y.Z

# 2. Install into a project (detects your stack and tells you which preset fits — `--detect-only` asks without installing)
claude-base init --preset nextjs ./my-app
# or just: claude-base init ./existing-project   (interactive, auto-detects)
# ✓ prints a summary of the .claude/ files written into the project

# 3. Open Claude Code in the project and run the canonical workflow
cd ./my-app && claude
> /work:work-flow-feature "add a /counter route with optimistic UI"

That last command chains the 6 phases automatically: Explore → Specify → Plan → TDD → Audit → Commit. Each phase has dedicated slash commands you can also drive manually.

Is it for you?

You are...	This helps...	Skip it if...
Solo dev shipping side-projects with Claude Code	preset gives you stack + workflow rigor in 30s ; no copy-pasting prompts between sessions	you barely use Claude Code yet — start with the official docs first
Team lead wanting consistent Claude Code outputs across a codebase	enforces TDD + audit-loop gates in shared .claude/ config, anti-drift counters CI-gated	your team has already built bespoke prompts you're happy with
Educator / mentor	the 6-phase workflow is named, teachable, and the audit-loop produces a quality score	you only need ad-hoc Claude Code use
Returning user who tried Claude Code, found it too freeform	the dispatcher CLI stays small and learnable, and the foundation is fully reversible (claude-base uninstall)	you prefer raw .claude/ files without a foundation layer

You don't have to learn the 106 commands. The core loop is six slash-commands — one per phase: /work:work-explore, /work:work-specify, /work:work-plan, /dev:dev-tdd, /qa:qa-loop, /work:work-pr. The rest are domain-specific (CI, a11y, payment, GDPR, etc.) and either auto-trigger via path rules or stay one slash away when relevant.

How it compares

claude-base is the opinionated discipline layer for Claude Code.

The workflow itself is now table-stakes — a spec → plan → implement flow ships in most serious Claude Code setups. What claude-base adds is enforcement: much of the discipline is checked at the hook, not left to the prompt:

• Anti-gaming layer — editing an existing ESLint, Prettier, Biome, Ruff (ruff.toml) or markdownlint config is refused at the hook (tsconfig and pyproject are not covered), and so is the --no-verify / -n flag. A hollow test, a focused .only test or a stub is flagged back to the agent the moment it is written: advisory, not a block, because a static signal can misfire on legitimate work. Others now ship parts of this; see the September 2026 re-audit note.
• Enforced by default, not opt-in — a git commit over a failing npm / pytest / go suite, a high-confidence provider key (AWS, GitHub, Stripe, Slack, Google, private-key block) written through an edit, or the --no-verify flag is blocked at the hook level, not just discouraged in a prompt. Wrapped forms (bash -c, HUSKY=0, a secret written through a Bash redirect) are not caught: these are guardrails against accidents, not a sandbox.
• Learns across all your projects — a human-gated, sanitized lessons referential: after a hard-won fix or a correction, claude-base proposes a one-line lesson and, on your approval, stores it in your own ~/.claude/rules/lessons.md — loaded into every project. Unlike auto-learners, you approve each lesson, and it's never committed to a repo. How it works →
• Curated vendor skills, kept fresh — instead of guessing among 6,700+ community skills, you get a vetted shortlist of which ones to trust. A billing-safe engine re-checks them for rot/abandonment and surfaces new candidates — observe-never-install: nothing lands in your project without you.

It composes with the neighbours rather than competing: Spec Kit for agent-agnostic SDD primitives, the official marketplace for per-tool depth. Both comparisons — with sources, and a capability table across seven similar projects — are in docs/POSITIONING.md.

The complete net of enforced checkpoints a bare Claude project lacks — method, security, verification, anti-gaming, audit, integrity — is catalogued in docs/GUARDRAILS.md, which is the count as well as the list.

Full positioning — comparison tables, the curation engine, and where it's heading — in docs/POSITIONING.md.

A default install ships the core only. The horizontal activity domains (biz, legal, growth) and the stack/thematic domains (nextjs, flutter, iac, observability, …) are opt-in modules (claude-base add <module>) — run claude-base modules to list all 15. A fresh project gets the smaller core slice. See specs/horizontal-pure-modules/.

What you get on disk

After claude-base init, your project gains:

your-project/
├── CLAUDE.md              # Project instructions auto-loaded by Claude Code
├── .claude/
│   ├── settings.json      # Hooks, permissions, plugin enablement
│   ├── commands/          # Slash commands grouped by domain (work, dev, qa, ops, ...)
│   ├── agents/            # Sub-agents with isolated context
│   ├── skills/            # Auto-triggered on keywords (some manual-only)
│   ├── rules/             # Path-specific rules (TDD, security, a11y, performance)
│   ├── presets/           # Stack-specific bundle manifests
│   └── output-styles/     # Output rendering styles
└── .github/               # (optional) CI workflows + pre-commit hooks

Everything is plain markdown + JSON, with no daemon and no telemetry. Some hooks do reach the network: claude --init installs dependencies and claude --maintenance runs npm audit / npm outdated; editing a manifest (package.json, pyproject.toml, go.mod, Cargo.toml, pubspec.yaml) re-syncs dependencies; the pre-commit test gate may run npm install to repair Husky; and the prompt-context hook asks GitHub for PRs awaiting your review through gh when it is installed (SKIP_PR_CHECK=1 turns that off). Reversible via claude-base uninstall.

What's included

Component	Count	What it is
Slash commands	106 across 9 domains (work, dev, qa, ops, doc, biz, growth, data, legal)	Manually triggered (/work:work-plan)
Sub-agents	44	Autonomous, isolated-context workers spawned by commands
Skills	53	Auto-triggered on keywords in your prompts — except a manual-only subset listed in the skills catalogue
Path-specific rules	34	Auto-activated based on the file being edited (TS strict, OWASP, WCAG, YAGNI/minimal-code, ...)
Presets	11	Stack-specific bundles ; tier breakdown in Going deeper

Learns across projects. A personal, human-gated lessons referential: after a hard-won fix or a correction, claude-base proposes a generalized, sanitized one-line lesson and — on your confirmation — stores it in your own ~/.claude/rules/lessons.md, which Claude Code loads into every project. A mistake made once stops recurring everywhere; run /lessons --bootstrap to seed it from what you already learned. The lessons stay yours — never committed to any repo. How it works →

Full catalogue: Docusaurus reference — or browse .claude/ directly after install.

The 6-phase workflow in action

After install, you cd ./my-app && claude and the foundation drives the workflow (the GIF at the top of this page is the real install, recorded in an isolated Docker container — reproducible, scaffolding under website/demo/):

> /work:work-flow-feature "add a /counter route with optimistic UI"

[work-explore]  Scans app/, hooks/, lib/ → detects the project shape
[work-specify]  Drafts user stories + acceptance criteria
[work-plan]     Lists the files to touch + identifies risks
[dev-tdd]       RED → GREEN → REFACTOR cycle, tests before code
[qa-loop]       Audit + auto-fix until target score (default ≥ 90)
[work-pr]       Branch, commit, push, open the PR

One command chains the 6 phases.

Or drive it yourself

/assistant              # guided: explains the workflow and suggests the next command
/assistant-auto "..."   # automatic: routes your request to the right workflow

Each phase is also a command of its own — /work:work-explore, /work:work-specify, /work:work-plan, /dev:dev-tdd, /qa:qa-loop "score 90", /work:work-pr — and the shape is identical for any stack; swap the arguments. A worked example per phase is in docs/CHEATSHEET.md.

Installation

Option 1: One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/christopherlouet/claude-base/main/install.sh | bash

This clones the foundation to ~/.local/share/claude-base and symlinks the dispatcher into ~/.local/bin/claude-base. The installer never runs as root, never modifies your shell rc files, and needs only git to run (the next step, claude-base init, additionally needs jq — see Requirements). After install:

claude-base init --preset fastapi ./my-api      # Python backend
claude-base init --preset nextjs   ./my-web-app # Next.js fullstack
claude-base init --simple          ./my-project # Foundation only, no preset
claude-base preset list                          # Discover available presets
claude-base help                                 # All commands

To update the foundation later:

curl -fsSL https://raw.githubusercontent.com/christopherlouet/claude-base/main/install.sh | bash -s -- --update

Pinning to a release (reproducible installs)

The one-liner above tracks the moving main tip. To install a specific, tested release instead, pass --ref <tag> — still a single line:

curl -fsSL https://raw.githubusercontent.com/christopherlouet/claude-base/main/install.sh | bash -s -- --ref v5.8.0

A pinned install stays pinned across --update (it never silently jumps to main). To move it to another release, pass --ref <newtag>; to return to the latest main, pass --ref main.

Verify before executing (supply-chain conscious)

Piping any script straight into your shell runs it unverified — our own security.md rule says to download → verify → execute, and a hook in this repo blocks curl … | sh in agent sessions. Each tagged release publishes a SHA256SUMS asset, so you can honor that on install:

TAG=v5.8.0
curl -fsSL "https://raw.githubusercontent.com/christopherlouet/claude-base/$TAG/install.sh" -o install.sh
curl -fsSL "https://github.com/christopherlouet/claude-base/releases/download/$TAG/SHA256SUMS" -o SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS   # must print: install.sh: OK
bash install.sh --ref "$TAG"

Fetch install.sh from the same tag as the checksum (/$TAG/, not /main/) — the published SHA256SUMS covers the tagged script, not the moving tip.

If ~/.local/bin is not on your PATH, add it (most modern distros already do):

export PATH="$HOME/.local/bin:$PATH"  # add to ~/.bashrc or ~/.zshrc

Installing without the one-liner

A manual git clone + in-repo dispatcher, or a raw copy of .claude/, are both documented in docs/QUICKSTART.md.

Keeping Claude Code itself up to date

The commands above install and update claude-base — they do not touch the underlying Claude Code CLI. If you installed Claude Code through Homebrew or WinGet, you can opt into background upgrades by exporting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 in your shell. This has no effect on the curl one-liner install of claude-base, and no effect if you installed Claude Code through any other channel. Available in Claude Code 2.1.129+.

Repository layout

After curl | bash install, the foundation lives at ~/.local/share/claude-base/. The repo's top-level layout:

Path	Role
bin/claude-base	CLI dispatcher (init / update / validate / doctor / lessons / add / remove / modules / preset / uninstall / version / help)
install.sh	One-liner installer — clones to ~/.local/share/claude-base/, symlinks the dispatcher to ~/.local/bin/
.claude/	Foundation kit — skills/, agents/, commands/, rules/, presets/, output-styles/, templates/, settings.json
scripts/	Implementation scripts behind the CLI + maintenance tools (audit-base.sh, audit-docs.sh, doctor.sh, diff.sh, ...) + hook scripts
templates/	Stack-specific CLAUDE.*.md templates + advisory docs (FAQ.md, PERFORMANCE-GUIDE.md, TROUBLESHOOTING.md)
docs/	Human-maintained documentation — QUICKSTART.md, CHEATSHEET.md, ARCHITECTURE.md, WORKFLOWS.md, STACK-RECIPES.md, CUSTOMIZATION.md, recipes/, reference/, guides/
website/	Docusaurus site — docs/ is auto-mirrored here by npm --prefix website run generate
specs/	Feature specs consumed by the workflow agents (/work:work-specify, /work:work-plan)
tests/	The bats suite — run with ./scripts/test.sh
eval/	Evidence harnesses — do the rules and gates actually change anything? value-proof/, rule-efficacy/, gate-scorecard/, cold-start/, minimal-code/, each with its own README and its own method
.github/workflows/	CI : ci.yml, security.yml, docs.yml, pr-check.yml, release.yml, dependabot-auto-merge.yml
AGENTS.md, CHANGELOG.md, VERSION, LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, counts.json	Project metadata

For the full file-by-file reference, see the Docusaurus reference docs.

Available Commands (106)

Commands are grouped into 9 domains:

Domain	Count	Examples
work-	15	/work:work-explore, /work:work-plan, /work:work-commit, /work:work-pr, /work:work-flow-feature
dev-	16	/dev:dev-tdd, /dev:dev-debug, /dev:dev-api, /dev:dev-flutter, /dev:dev-prisma
qa-	13	/qa:qa-loop, /qa:qa-security, /qa:qa-perf, /qa:wcag-audit, /qa:qa-e2e
ops-	28	/ops:ops-deploy, /ops:ops-docker, /ops:ops-monitoring, /ops:ops-k8s, /ops:ops-rollback
doc-	5	/doc:doc-onboard, /doc:doc-explain, /doc:doc-changelog, /doc:doc-generate
biz-	9	/biz:biz-model, /biz:biz-mvp, /biz:biz-pricing, /biz:biz-personas
growth-	9	/growth:growth-landing, /growth:growth-seo, /growth:growth-cro, /growth:growth-analytics
data-	2	/data:data-pipeline, /data:data-modeling
legal-	5	/legal:legal-rgpd, /legal:legal-terms-of-service, /legal:legal-privacy-policy

→ Full list: docs/CHEATSHEET.md or the Docusaurus catalog.

→ By stack: docs/STACK-RECIPES.md lists the relevant commands for each stack (Web, Mobile, API, Auth, etc.).

Stack templates

Ten CLAUDE.*.md starting points (React, Vue, Node API, Python, Go, Rust, Java, fullstack, Flutter, Neovim) — claude-base init --type react ./my-app wires one in, hooks and settings included. The table and the manual route are in docs/CUSTOMIZATION.md.

Utility CLI (claude-base)

After curl | bash install, the unified dispatcher is on your PATH. Use it as the canonical entry point:

# Create a new project (interactive)
claude-base init

# Install in an existing project
claude-base init --simple /path/to/project

# Update commands
claude-base update /path/to/project

# Validate the configuration
claude-base validate /path/to/project
claude-base validate --json /path/to/project   # for CI/CD

# Diagnose a project (config, deps, and downstream security drift)
claude-base doctor /path/to/project

# Add / remove / list the opt-in domain modules
claude-base modules
claude-base add nextjs /path/to/project

# Personal cross-project lessons (seed, prune the store)
claude-base lessons bootstrap-scan
/lessons --bootstrap    # the guided flow, from inside Claude Code

# Uninstall
claude-base uninstall /path/to/project

Maintenance tools without a dispatcher alias (still callable directly from a foundation clone):

# Diff against the foundation
./scripts/diff.sh /path/to/project

# IDE integration (VSCode, IntelliJ, Vim/Neovim)
./scripts/ide.sh setup vscode

IDE and CI

./scripts/ide.sh setup <vscode|idea|vim|all> wires settings, tasks and snippets — details in docs/CUSTOMIZATION.md. Six GitHub Actions workflows and the .husky/ pre-commit hooks ship with the foundation; what each one gates is in docs/guides/TEAM-GUIDE.md.

Documentation

Online documentation

The full documentation site lives at https://christopherlouet.github.io/claude-base/.

It covers:

• Quick start guide
• Catalog of 106 commands, 44 agents, 53 skills, 34 rules
• Recommended workflows (Explore → Specify → Plan → TDD → Audit → Commit)
• Stack Recipes: relevant commands per stack (Web, Mobile, API, Auth, Database, Infra, Observability, Testing, Data, AI/LLM, Business, Growth)
• Specific guides: Learning path, Extending, Team, Prompting, Troubleshooting

Local documentation

• QUICKSTART.md: 5-minute getting started
• CHEATSHEET.md: Command quick reference
• ARCHITECTURE.md: Commands vs Agents vs Skills vs Rules
• GUARDRAILS.md: every enforced checkpoint a bare Claude project lacks — method, security, verification, anti-gaming, audit, integrity
• WORKFLOWS.md: Workflow diagrams
• STACK-RECIPES.md: Commands/agents/skills per stack (Web, Mobile, API…)
• CUSTOMIZATION.md: Customization guide
• recipes/: Targeted recipes — recommended vendor skills, Python toolchain options, SaaS monetization, nightly curation-bot deploy, etc.
• guides/EXTENDING-GUIDE.md: Extend the foundation (custom commands/skills/rules)
• guides/TEAM-GUIDE.md: Team adoption — including When .claude/ is gitignored (scope choices for plugins & skills)
• guides/PROMPTING-GUIDE.md: Prompting techniques
• guides/TROUBLESHOOTING-GUIDE.md: Common issues and fixes
• Learning path (Docusaurus only): 9h30, 5 levels novice → pro

Elsewhere

• Claude Code Best Practices · Claude Code docs · How Anthropic teams use Claude Code

Automated Tests

The foundation ships with bats-core tests that validate every script. Install bats via the upstream instructions (or ./scripts/test.sh --install-bats to use the foundation's bundled helper).

./scripts/test.sh                # parallel run, all tests
./scripts/test.sh validate       # filter to one suite (e.g. validate.bats)
./scripts/test.sh -v             # verbose

Full file-by-file inventory at tests/. Run via ./scripts/test.sh (parallel) or bats tests/*.bats (sequential).

Upgrades & Changelog

For per-release details (Added / Changed / Fixed / Security / Removed), see CHANGELOG.md — kept in Keep a Changelog format.

Upgrading an installed project

# Upgrade the foundation itself (refreshes ~/.local/share/claude-base)
curl -fsSL https://raw.githubusercontent.com/christopherlouet/claude-base/main/install.sh | bash -s -- --update

# Refresh an installed project to the current foundation
claude-base update /path/to/your/project

# Or adopt a preset: its filter applies now and is recorded for later updates
claude-base update --preset nextjs /path/to/your/project

# Read-only: check whether your project still matches its recorded preset
claude-base update --detect-only /path/to/your/project

claude-base update is COPY-only by default — existing files in your project's .claude/ are not deleted. Pass --clean to wipe-and-replace (a backup is created first). update also flags a stack pivot: if your project has outgrown its recorded preset (e.g. a Vite SPA that grew into Next.js), it prints a non-blocking notice pointing at claude-base update --preset <name>, and once you pick one, it stays quiet until the stack changes again; --detect-only reports that check (Diverges: yes/no) without updating anything.

Versioning policy

The foundation follows Semantic Versioning. Each release is tagged vX.Y.Z and shipped with a GitHub Release containing the relevant CHANGELOG excerpt. Pin via git checkout vX.Y.Z in ~/.local/share/claude-base if you need reproducible installs. Behaviour-breaking changes between minor versions are explicitly called out in the CHANGELOG under ### Breaking.

Production Readiness

Concrete signals rather than a self-assessment score :

• The full bats suite runs on every PR (Linux + macOS), parallelised via ./scripts/test.sh — the count is not restated here, because the suite itself is what verifies it
• Six GitHub Actions workflows (CI, security, docs, PR check, release, dependabot auto-merge) gating merges
• Doc drift firewall (scripts/audit-docs.sh) catches syntactic doc drift before merge — see PR #201
• Counter anti-drift gate (scripts/validate-counts.sh) regenerated from counts.json
• Pinned versions via git tags (current : v5.8.0) with full CHANGELOG.md in Keep-a-Changelog format

Security measures

• Gitleaks: a pre-configured ruleset at .gitleaks.toml (AWS/GitHub/GitLab/Stripe/Slack tokens, JWTs, private keys, database URLs) runs on every PR via security.yml and in the pre-commit hook when enabled. Local scan: gitleaks detect --source . --config .gitleaks.toml, or --staged for the pre-commit shape
• Private names: a pre-commit gate stops an end user's private project names from reaching this public repo, in staged paths or staged content. The protected list is deliberately kept outside the repository (~/.claude/private-names, or CLAUDE_BASE_PRIVATE_NAMES), so it is never itself published — and no list means a silent no-op, so a fresh clone is never blocked. Scans only what a commit adds; bypass once with SKIP_PRIVATE_NAMES=1. See docs/GUARDRAILS.md
• ShellCheck: bash linting on all scripts/ (CI workflow security.yml, severity warning)
• Deny list: rm -rf / and sudo are refused by the command validator; git push --force / -f is refused only by the permission deny list, in its literal leading form (git push --force…, git push origin --force…) — a flag placed later is not caught
• Protection hooks: keeps Edit/Write edits off main/master by moving them to a new feature/auto-* branch (refused if that branch cannot be created); a Bash write to a tracked file on main is refused
• GitHub Secret Scanning: enabled on the public repo
• Not protected: reading secrets. Nothing stops the agent from reading .env or another secrets file (cat .env, the Read tool); what it reads reaches the session transcript. The guards cover secrets being written into files, and a secrets file being overwritten through Bash
• GitHub Code Scanning (CodeQL): JavaScript/TypeScript security analysis (Default Setup — repo-wide)
• Downstream drift detection: claude-base doctor (and an advisory after claude-base update) flags an installed project whose settings.json / hook scripts have fallen behind the foundation — e.g. security hooks on a stale input contract that would silently no-op — and points you at the resync command
• Verified install: install.sh --ref <tag> pins to a released tag and each release publishes SHA256SUMS, so the installer can be verified before execution (see Installation)

See SECURITY.md for the full security policy.

Going deeper

Detail-level docs and editorial pieces that didn't make the front-door:

• Three preset tiers — maintainer-vouched (production use ≥3 months) / vendor-pointer (vendor-authored, validated via marketplace audit) / community-curated (signed maintenance commitment). See .claude/presets/README.md and specs/presets-vendor-pointer-tier/spec.md.
• Pre-detection category prompt — when claude-base init runs on an empty directory with no preset/type and no auto-detect match, an interactive 8-entry intent prompt narrows the menu. Spec: specs/preset-category-prompt/spec.md.
• Cross-tool compatibility — AGENTS.md at repo root signals SKILL.md open-standard compliance to Codex, Cursor, Copilot, Gemini CLI. Skills under .claude/skills/ use the standard frontmatter ; Claude-specific extensions are silently ignored by other tools. See AGENTS.md.
• Doc drift firewall — scripts/audit-docs.sh catches 5 categories of syntactic drift (paths, claude-base verbs, init/update flags, local scripts, npm scripts) before merge. CI-gated.

Long-term direction

The foundation lives alongside the marketplace, not against it: its irreducible value is the workflow rigor + path rules, while tool-specific depth increasingly ships as vendor skills. Four mechanisms keep it aligned with that trajectory (a billing-safe curation engine, advice-neutrality over publisher-veto, per-preset recommendations with drift tracking, and trajectory-driven automation) — detailed in docs/POSITIONING.md.