claude-config

Prescriptive methodology for configuring Claude Code. This repo is the source of truth for ~/.claude/ (the runtime directory) and ships a complete framework for skill design, SDD orchestration, persistent memory, and project onboarding.

It plays two roles:

1. Global config — deployed to ~/.claude/ by install.sh, becoming the user-level instructions, skills, hooks, MCP servers, output-styles, and keybindings for every Claude Code session.
2. Methodology kit — the conventions, audit/refactor skills, and templates that other projects can adopt to standardize their own Claude config.

The canonical behavior contract is in CLAUDE.md. The full governance lives in docs/config-guidelines.md.

Repository layout

claude-config/
├── CLAUDE.md              # Global behavior rules (loaded every session)
├── settings.json          # Permissions, plugins, MCP servers, output-style
├── keybindings.json       # Custom keyboard shortcuts
├── install.sh             # One-way: repo → ~/.claude/
├── sync.sh                # One-way: ~/.claude/memory/ → repo/memory/
├── skills/                # 33 skills, auto-discovered by the harness
├── hooks/                 # Event hooks (UserPromptSubmit, SessionStart, …)
├── agents/                # Sub-agent contracts (e.g. sdd-orchestrator.md)
├── output-styles/         # Tone-only styles (direct, warm-direct, concise)
├── mcp/                   # MCP server definitions
└── docs/                  # Governance, templates, ADRs
    ├── config-guidelines.md   # Constitution (13 principles)
    ├── anti-patterns.md       # 10 cataloged anti-patterns (AP-1..AP-10)
    ├── format-types.md        # Skill format contract
    ├── output-style-guidelines.md
    ├── known-issues.md
    ├── inventory.md           # Complete artifact inventory (skills, docs, MCP, …)
    ├── SKILL-RESOLUTION.md
    ├── templates/             # project-claude, prd, adr
    └── adr/                   # Architectural Decision Records

What you get — skills overview

The core of this repo is a set of skills: focused capabilities the harness auto-loads when their trigger matches. They fall into five families. Each entry below explains what the family does for your project and links to the full, per-skill catalog in docs/inventory.md.

• SDD — Spec-Driven Development — a spec-first pipeline for risky changes (architecture, migrations, public contracts). Ten phase skills (/sdd-explore → /sdd-propose → /sdd-spec → /sdd-design → /sdd-tasks → /sdd-apply → /sdd-verify → /sdd-archive, plus /sdd-init and /sdd-status) walk a change from idea to audited implementation, persisting each artifact to Engram. Use it when jumping straight to code would be reckless; skip it for typos and renames. → details

• Governance — audit and bootstrap Claude configuration itself. /config-audit + /config-refactor keep THIS repo compliant with its own constitution; /project-audit + /project-fix, /project-onboard, /project-setup, and /project-claude-init diagnose and set up consumer projects. → details

• Memory & tracking — what survives between sessions. memory-manage and codebase-teach build the project-local ai-context/ layer; feature-define scaffolds per-feature domain knowledge; project-tracking runs a GitHub-backed backlog with an Epic → Story → Task hierarchy. → details

• Workflow — day-to-day operations: smart-commit (grouped conventional commits), branch-pr + issue-creation (issue-first PR flow), judgment-day (adversarial dual review), deep-analysis, skill-creator, output-style-creator, config-export, support-brief, and night-park. → details

• Tech reference — stack-specific pattern skills (React 19, Next.js 15, TypeScript, Tailwind, Zustand, React Native, Go testing). These are NOT global — they live as scaffolds in skills/_templates/tech/ and are copied into a consuming project's .claude/skills/ on demand. Only solid-ddd (SOLID + DDD, stack-agnostic) deploys globally. → details

The harness auto-discovers every skills/<name>/SKILL.md, so the authoritative runtime list is the one in your session reminder. The overview above is a reader's map, not a registry to hand-maintain per skill — that detail lives in docs/inventory.md alone (per config-guidelines Principle 2). For the complete inventory of docs, agents, output-styles, MCP servers, and root files, see the same file.

Two-layer architecture

Claude Code reads configuration from two layers that accumulate without replacing each other (see config-guidelines Principle 13):

This repo owns the global layer. Consumer projects own their project layer, bootstrapped via the project-claude-init skill or the template at docs/templates/project-claude-template.md.

A project rule that contradicts a global rule must declare an ## Overrides global block with a written reason; otherwise it is a CRITICAL finding from config-audit.

Installation

Prerequisites:

• Claude Code CLI installed and on PATH.
• Go toolchain (1.21+) — required to build the Engram binary (see below).
• GITHUB_TOKEN as a system environment variable — for the GitHub MCP server.
• POSIX-compatible shell — Git Bash on Windows, native bash on macOS/Linux/WSL.

1. Install the Engram binary (required)

Engram is the persistent-memory MCP server and is mandatory: CLAUDE.md, the SDD pipeline, the continuation-keyword protocol, and the session-summary contract all assume mem_save / mem_search exist. Without it, large parts of the methodology become inert.

go install github.com/Gentleman-Programming/engram/cmd/engram@latest

This drops the binary into $(go env GOPATH)/bin/ (typically ~/go/bin/ on Unix or C:\Users\<you>\go\bin\ on Windows). install.sh discovers it from there — you do **not** need to add anything to PATH for Claude Code's sake.

2. Install the Engram Claude Code plugin (required)

The binary provides the MCP server. The plugin injects the engram protocol into every SessionStart. Both are required. From inside Claude Code:

/plugin install engram@engram

3. Clone and deploy this repo

git clone <this-repo> ~/claude-config
cd ~/claude-config
bash install.sh

install.sh copies the repo into ~/.claude/, resolves the absolute path to the engram binary, rewrites the deployed ~/.claude/mcp/engram.json with that path, and registers the GitHub and filesystem MCP servers. The direction is one-way (repo → ~/.claude/). Never edit ~/.claude/ directly — any direct change is lost on the next install.

The repo's own mcp/engram.json ships with "command": "engram" (a portable placeholder); the absolute path lives only in the deployed copy under ~/.claude/, so no user-specific path ever gets committed.

For the full MCP inventory — every server (engram, context7, github, filesystem, plus account-level claude.ai connectors), how each is registered, and per-server install steps — see docs/mcp-servers.md.

sync.sh is the only reverse flow: it pulls ~/.claude/memory/ back into the repo. It does not touch skills, hooks, CLAUDE.md, settings, or anything else.

Methodology surface

The repo exposes three families of skills that together form the methodology:

• SDD (Spec-Driven Development) — 8 phases (sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive) plus sdd-init and sdd-status. Artifacts persist to Engram under topic keys sdd/<change>/<phase>. Orchestrator instructions live in agents/sdd-orchestrator.md.
• Meta-config governance — config-audit + config-refactor enforce docs/config-guidelines.md; project-audit + project-fix audit consumer projects; project-onboard, project-setup, project-claude-init bootstrap new projects.
• Memory + tracking — memory-manage for the ai-context/ layer in consumer projects, project-tracking for GitHub-backed backlogs.

Tech skills (react-19, nextjs-15, typescript, zustand-5, tailwind-4, react-native, go-testing, solid-ddd) are domain references loaded only when relevant.

Workflow skills (smart-commit, branch-pr, issue-creation, judgment-day, deep-analysis, skill-creator, output-style-creator, config-export, feature-domain-expert, codebase-teach) cover day-to-day operations.

Persistence

Cross-session memory uses Engram — see the Installation section above for the two required components (binary + plugin). Engram persists but is never recovered automatically: every session must explicitly invoke mem_context or mem_search to read prior state. The repo-specific extensions to the engram protocol (mem_save format, session-summary template, continuation-keyword rule) live in CLAUDE.md.

The ai-context/ directory (stack, architecture, conventions, known-issues, changelog) is a consumer-project memory layer. It is deployed BY /project-setup INTO target projects; the methodology repo itself does not populate one (see project-audit global-config exemptions).

Modifying this repo

1. Make changes in this repo (never in ~/.claude/).
2. Run bash install.sh to deploy.
3. Commit with conventional-commit prefixes (feat:, fix:, docs:, refactor:, chore:). Never add AI co-author trailers.

For substantial changes (new skills, hook protocols, behavior rules), follow the SDD cycle: /sdd-explore → /sdd-propose → /sdd-spec + /sdd-design → /sdd-tasks → /sdd-apply → /sdd-verify → /sdd-archive.

For governance changes (anything in docs/config-guidelines.md or docs/anti-patterns.md), run config-audit before and after the change to confirm the new rule is enforceable.

License

Personal configuration repository. Use, adapt, and fork freely.