orchestrata-ultimate — Claude configuration
Project-specific customization of the Claude Code environment for
~/workspace/orchestrata-ultimate-architecture. Everything below is checked
into the repo unless marked otherwise.
Instruction layers (always in context)
CLAUDE.md(repo root) — project instructions. @imports two generated tiers and defines the Key Rules (no xdist, no mocking, no pip/uv-only, no relative imports,os.environ.getonly, function-scope fixtures, no AI attribution in commits, AST-toolkit-over-grep, all deps declared).docs/LEVEL0.md— the always-loaded foundation tier: identity, Incus infra topology (10.53.1.x— NOT docker/localhost), the two-graph map (Neo4j.11= operational KG; Memgraph orchgraph Raft HA, routing.160:7691= shared semantic/RAG graph), tool/volk inventory. Generated byscripts/gen_level0.pyfrom.env+ tool registry +context.json;--checkgates drift. Never hand-edit.docs/CODEBASE_MAP.md— auto-regenerated each session (see hooks): the ~31K-token header tier (runners, entrypoints, packages, test inventory). The full ~263K-token signature skeleton lives indocs/CODEBASE_MAP_FULL.md, on-demand only (grep + ranged reads) — loading it killed 4 subagents in one night. Tier rationale:plans/context-tiers-design.md.
Instruction layer stack
Hooks — .claude/settings.json
| Event | Hook | Effect |
|---|---|---|
| SessionStart | .claude/hooks/inject-codebase-map.sh |
regenerates both codebase-map tiers so structure is fresh every session |
| SessionStart | .claude/hooks/start-ast-daemon.sh |
starts the warm per-repo AST daemon |
| SessionStart | .claude/hooks/start-architecture-sync.sh |
starts the architecture-semantic-twin sync |
| PreToolUse (Bash) | .claude/hooks/no-xdist.sh |
blocks pytest -n/--dist — xdist deadlocks this suite at ~78% |
| PreToolUse (Bash) | .claude/hooks/ast-toolkit-hint.sh |
nudges grep/sed toward scripts/serialize_codebase_ast.py (never blocks) |
| PreToolUse (Bash) | .claude/hooks/force-test-observation.sh |
forces pytest runs through the live observer, no escape hatch |
| PreToolUse (Write/Edit/MultiEdit) | .claude/hooks/no-doubles-py.sh |
blocks mocks/stubs/fakes/monkeypatch being written into .py |
| PreToolUse (Write/Edit/MultiEdit) | .claude/hooks/no-banned-deps.sh |
blocks banned dependencies being written into pyproject.toml |
| Stop | .claude/hooks/forbidden-doubles-stop.sh |
end-of-turn double-check for forbidden test doubles |
.claude/settings.local.json (not committed) holds a small permission
allow-list (git diff, /tmp reads, swipl).
Subagent definitions — .claude/agents/ (8)
analyst (Fable, design/contract diagrams), auditor (read-only
spec-vs-code), builder (Sonnet implementation to a settled brief),
lint-fixer (Haiku-tier mechanical), refactorer (behavior-preserving),
reviewer (adversarial diff review), test-writer (coverage waves),
wirer (surgical integration). Conventions baked into the definitions:
Opus orchestrates / Sonnet builds; verification must be SYNCHRONOUS
parallel per-file pytest inside one Bash call (the harness auto-backgrounds
long commands and subagents never get completion notifications — the
"orphaned-wait trap"); builders never touch the git index.
Skills — .claude/skills/
ast-toolkit— full subcommand catalog forscripts/serialize_codebase_ast.py(symbols/refs/rename/attr-refs/ trace-audit/trace-lint/…): the mandated tool for structure questions, inventories, and refactors.ask-openrouter— scoped-context questions to OpenRouter models.knowledge-wiki— this wiki's CLI workflow.
Workflows — .claude/workflows/ (versioned; gitignore whitelisted 2026-07-09)
trace-wave.js— the generic @traces remediation wave engine (per-packet Sonnet fix + independent adversarial verify, structured outputs, hardened package-import gates). Driven byplans/trace-remediation-plan.md.
Session tracking
Per-project context.json/context.md managed exclusively by the session
CLI (python3 ~/.claude/tools/session_cli.py, alias session) — never
hand-edited (atomic + fcntl-locked I/O after a corruption incident). Five
session hooks (sns/cts/remember + SessionStart/End) + the SPEC-023 goal-gate
are deployed; deep doc: claude/SESSION_SYSTEM.md in-repo.
Memory (two-tier, outside the repo)
- Global:
~/.claude/projects/-home-mohamed/memory/— loads everywhere. - Project:
~/.claude/projects/-home-mohamed-workspace-orchestrata-ultimate-architecture/memory/— loads only in this project (infra IPs, no-xdist, git-hook quirks, specs-are-authoritative, swarm-builder rules, etc.).
Git-side gates (adjacent, not Claude-specific)
.git/hooks/pre-commit (custom): ruff --fix + blocking code-review.py on
staged src/* + test-review.py on tests/*. .pre-commit-config.yaml
(CI layer): check-deps, standards, untyped-ratchet, pyright-ratchet
(--max 283), check-traces-ratchet, auto-fix dry-run. scripts/git-hooks/ pre-push runs the threadpool suite (known false timeouts on slow live-e2e
modules under load — re-run solo before trusting).