Claude Code Setup

A ~/.claude/ configuration that turns Claude Code into a four-layer personal AI Engineering OS — Warp cockpit, Claude Code execution, SocratiCode intelligence, AIS-OS context layer — with explicit guardrails, governed agents, and a controlled self-evolution loop. Not a chatbot.

For whom

Engineers who want Claude Code to:

• Ship production-grade code end-to-end (/ship), not scaffolds.
• Inspect first, fix root-cause, and leave a regression test (/audit-deep, /fix-root).
• Refuse to commit secrets, force-push, or delete system paths without confirmation.
• Route by risk tier and authority level, not by vibe.
• Own a personal operating layer that knows your business, tracks repeat work, and improves weekly (/onboard, /audit, /level-up).

If you want a one-file prompt tweak, this is not it. This is a full operating environment, mounted at ~/.claude/.

Start here

Two surfaces cover the common cases — engineering work and AI OS operation. Full map in docs/SURFACE-MAP.md. Common workflow recipes in docs/RUNBOOK.md.

Engineering surface

AI OS surface (AIS-OS layer)

For planning heavy/cross-system work, /plan is canonical (/ultraplan for enterprise-risk only). Pick one.

Tasks route via three domain indexes — domains/engineering/DOMAIN.md (6 subdomains: full-stack, devops, security, quality, ai-ml, design), domains/finance/DOMAIN.md (trading, analysis, portfolio), domains/marketing/DOMAIN.md (growth, content, brand, ads). DOMAIN.md files are lazy-loaded pointers into existing skills/, agents/, commands/, recipes/ — no skills or agents move.

Install

git clone https://github.com/kmshihab7878/claude-code-setup.git
cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d) 2>/dev/null
rsync -av --exclude='.git' claude-code-setup/ ~/.claude/

Then:

• Edit ~/.claude/CLAUDE.md — replace identity/email.
• Review ~/.claude/rules/ — adapt path rules to your conventions.
• Run claude and type /plan test to confirm the pipeline wires up.

Four-layer architecture

Adapted from AIS-OS by Nate Herk (the personal/business layer); built on top of Claude Code (the execution engine). CLAUDE.md is canonical — every other config (WARP.md, AGENTS.md, AIS-OS docs) points back to it instead of competing.

What's real today

Proof

• Phase 0 audit: docs/AUDIT.md (441 lines) — per-file bucket classification, dependency graph, overlap map, extraction-value zones. Raw evidence in docs/_audit-workspace/ (CLASSIFY / CROSSREF / CONFLICTS).
• Why the repo is shaped this way: docs/ARCHITECTURE.md — rationale for virtual-index design (core/, domains/, memory/), deviations from the target layout, context-loading tiers.
• What could be pulled out as standalone products: docs/EXTRACTABLE-PRODUCTS.md — 10 self-contained extraction candidates (Elite Ops, self-evolution, /market, Hue, JARVIS-sec, react-bits, mcp-mastery, anti-ai-writing, n8n, JARVIS-Core governance).
• What a session actually looks like: docs/DEMO.md — reproducible /audit-deep → /fix-root → /ship sequence on a target repo. Script ready; video not recorded yet.
• Common workflows: docs/RUNBOOK.md — 10 recipes from "start a coding task" to "recover from a failed task".
• What's in the repo, deterministically: docs/INVENTORY.md — machine-generated from disk. Regenerate with make inventory.
• How accumulation is measured, not asserted: docs/TELEMETRY.md — PreToolUse hook logs every tool call to ~/.claude/usage.jsonl; analyze with make usage.
• How drift is caught: make validate — pass=25 / fail=0 at last run. Checks CLAUDE.md + REGISTRY counts against disk, anti-regression patterns for 16 stale-count fingerprints, hook-script integrity, fake URLs. See docs/COUNCIL-REMEDIATION.md for history.
• Pruning protocol: docs/TELEMETRY.md → archive zero-invocation surfaces after 14 days of real usage.
• Controlled self-evolution: evolution/README.md — observe → record → evaluate → promote pipeline with hard evidence gates. Status via /evolution status; smoke test via make evolve-test.

Guardrails (active)

These hooks fire automatically (configured in settings.json, implemented in hooks/*.sh or inline):

Self-evolution layer (controlled)

Active in every session. Observes, records, and learns — but never mutates stable behavior without passing an evidence gate.

• Pipeline: observe → record → analyze → evaluate → propose → test → promote → monitor → prune.
• Startup injection (SessionStart hook) adds evolution/stable/global.md — the operating contract — plus any evolution/stable/by-project/<cwd-basename>.md if present. Hard cap via evolution/config.yaml: startup_budget_chars.
• Candidates live in evolution/candidates/*.yaml and never enter startup context until promoted.
• Promotion gate (evolution/bin/evolve-promote.sh) enforces: evidence ≥ 3, distinct sessions ≥ 2, distinct projects ≥ 2 (unless project-scoped), no contradiction, size budget respected.
• Kill switch: /evolution disable (creates evolution/disabled). Baseline mode: CLAUDE_EVOLUTION_BASELINE=1 claude for one clean session.

Operator commands: /evolution status | candidates | promotions | regressions | prune | run | promote <id> | demote <id> | disable | enable | baseline.

See evolution/README.md for full architecture.

Architecture, briefly

~/.claude/
├── CLAUDE.md            # Always-loaded operating contract (≤270 lines, ~4k tokens) — canonical
├── WARP.md              # Thin pointer to CLAUDE.md (Warp cockpit rules)
├── AGENTS.md            # Thin pointer to CLAUDE.md (for tools that look for AGENTS.md)
├── settings.json        # Hook bindings, enabled plugins
│
├── core/                # Lazy-loaded contract expansions
│   ├── identity.md      # Execution posture · ambiguity · completion · communication
│   ├── governance.md    # Non-negotiables · operating philosophy · Constitution (SEC-001)
│   ├── context-budget.md # Loading tiers · token-cost rules
│   └── memory.md        # Memory architecture across 6 layers
│
├── domains/             # Virtual domain indexes — pointers into skills/agents/commands
│   ├── engineering/DOMAIN.md  + 6 subdomains (full-stack, devops, security, quality, ai-ml, design)
│   ├── finance/DOMAIN.md      + 3 subdomains (trading, analysis, portfolio)
│   └── marketing/DOMAIN.md    + 4 subdomains (growth, content, brand, ads)
│
├── memory/              # File-based auto-memory + MEMORY.md always-loaded index
├── skills/              # Prompt-library skills (SKILL.md + references) — 209 skills
├── commands/            # Slash commands: 42 custom + 31 SuperClaude + 15 BMAD = 88
├── agents/              # Agent definitions (243) + REGISTRY.md dispatch table
├── rules/               # Path-scoped rules (python, typescript, security, testing, infrastructure, implementation)
├── hooks/               # Shell scripts invoked from settings.json
├── recipes/             # Parameterized YAML workflows
├── evolution/           # Self-evolution layer (observe → record → evaluate → promote, kill-switchable)
├── kb/                  # Knowledge base — wiki + decisions (ADRs) + retrospectives
│   └── wiki/_hot.md     # Current-week cache (AIS-OS pattern), refreshed via /weekly-operating-review
│
├── ── AIS-OS personal/business layer ──
├── context/             # About Me · About Business · Priorities · Voice Sample · Operating Preferences
├── decisions/log.md     # Append-only operating log (lighter than ADRs in kb/decisions/)
├── archives/            # Cold storage for retired material; quarterly review only
├── references/          # Three Ms · Four Cs · skill-building · API integration · direct-API-vs-MCP
├── connections.md       # Single source of truth for tools/accounts/sensitivity tiers
├── aios-intake.md       # The 7-question /onboard interview
├── .env.example         # Placeholder credential vars (real .env stays gitignored)
├── .socraticodeignore   # Patterns SocratiCode (when installed) should skip
├── templates/ai-engineering-os/  # Starter pack for replicating this pattern in other repos
│
└── docs/                # AUDIT · ARCHITECTURE · RUNBOOK · SURFACE-MAP · INVENTORY · OVERHEAD · TELEMETRY · KB-STATUS
                         # + AIS_OS_INTEGRATION · CADENCE · CAPABILITIES · CONNECTIONS_ROADMAP
                         # + MCP_GOVERNANCE · SECURITY · SOCRATICODE · WARP_COCKPIT · WARP_WORKFLOWS · WIKI_LAYER

Risk tiers control execution: T0 auto, T1 log+proceed, T2 wait for approval, T3 block unless pre-authorized. Agents operate only within their declared MCP server bindings (aspirational Tier-3 bindings gated at runtime by hooks/mcp-security-gate.sh). Full structural rationale in docs/ARCHITECTURE.md. AIS-OS integration mapping in docs/AIS_OS_INTEGRATION.md.

Inventory

Exact counts live in the machine-generated docs/INVENTORY.md. Regenerate anytime with make inventory. If you see a count elsewhere in the repo that doesn't match, make validate will flag it.

Validation and maintenance

make validate     # frontmatter + count drift + fake URLs + hook-script integrity
make inventory    # regenerate docs/INVENTORY.md from disk
make usage        # analyze ~/.claude/usage.jsonl (last 30 days)

make validate is the one command to run before committing structural changes.

Credits & sources

Patterns and skills integrated from:

• Anthropic Skills Spec
• Claude Code — the execution engine
• AIS-OS by Nate Herk — personal/business operating layer (Three Ms, Four Cs, /onboard, /audit, /level-up, weekly loops, connections roadmap)
• SocratiCode — codebase intelligence (AST search, graph, impact, call-flow) — documented; install on demand
• Warp — terminal cockpit (panes, blocks, workflows, diff review)
• SuperClaude Framework — 31 commands, specialized agents, cognitive personas
• BMAD Method — 15 agile/product commands
• oh-my-claudecode — hook patterns, persistent mode
• everything-claude-code — context optimization
• pbakaus/impeccable — frontend design skills (Apache 2.0)
• JCodesMore/ai-website-cloner-template
• wshobson — Kubernetes and quant trading skills
• alirezarezvani — C-suite advisor and marketing skills
• czlonkowski — n8n automation skills
• dominikmartn/hue — brand design-language meta-skill
• DavidHDev/react-bits — React component catalog

Security posture

• settings.local.json, projects/, audit.log, history.jsonl, usage.jsonl, .env, *.pem, *.key, and Python bytecode (__pycache__/, *.pyc) are .gitignored.
• Gitleaks-clean at commit time.
• No real emails, API keys, or personal paths in tracked files (placeholders only).

License

MIT.