NexaLance Claude Code Kit — v4.5 (Auto-Wiki)

The complete AI development operating system for Claude Code. Token-optimized, quality-preserved, production-hardened.

---

🎯 What This Is

A production-ready CLAUDE.md system that solves the biggest pains of running Claude Code on real, large projects:

Pain	How this kit fixes it
Claude burns context fast on big projects	v4.4 LITE: ~70% token reduction, lazy-loaded playbooks, tiered Phase 0
Memory lost between sessions	MemPalace integration with wing isolation per project
Code review doesn't scale	Risk-tiered review — 5-agent for security, inline for routine
Quality drops on multi-task plans	Deep Focus Mode + inline self-review checklist
MemPalace "sometimes" doesn't work	diagnose-mempalace.sh + interpreter auto-detection (fixes pyenv/python3 issues)
Mock/stub data sneaks into production	Zero Mock Data Rule + connection-chain verification
Browser tests waste tokens	Playwright CLI (4× cheaper than MCP) + DOM-targeted snapshots
Multi-project context bleed	MemPalace Wings — fully isolated memory per project
Tokens balloon on large codebases	Optional Graphify — knowledge-graph queries, ~71× cheaper than re-reading files
No enforcement of token rules	Runtime hooks — playbook-tracker, cache-warn, reset-counter
Past prompts/discussions/research scatter and get lost	Auto-LLM-Wiki (Karpathy pattern) — docs/wiki/ auto-scaffolds, sessions auto-ingest via hooks, synthesis on demand

---

⭐ What's New in v4.5 (Auto-Wiki)

NEW: LLM Wiki layer — fully automatic, zero manual operation

Karpathy's LLM Wiki pattern baked into the kit. Every project automatically gets a docs/wiki/ knowledge base that compounds over time:

• Auto-ingest hook (zero LLM tokens): SessionStart + SessionEnd hooks fire wiki-ingest.py which converts Claude Code session JSONL transcripts → markdown into docs/wiki/raw/discussions/. Idempotent, ~50ms idle, basic secret redaction (sk-…, ghp_…, AKIA…, Bearer …).
• Auto-scaffold: setup-project-wing.sh creates the full docs/wiki/ structure (CLAUDE.md schema, index.md, log.md, raw/{discussions,prompts,articles,interviews,inbox}, synthesized/{_entities}) at project init.
• Auto-backfill: at end of setup, the hook runs once to convert any pre-existing sessions for that project — wiki starts populated.
• On-demand synthesis (Claude does it, not the user): when .synthesis-pending exists OR user asks a domain/recall question, Claude reads index.md first, drills 2-4 relevant pages, cites raw sources. See playbooks/llm-wiki.md.
• Privacy-aware defaults: raw/discussions/ and raw/interviews/ gitignored (may contain secrets). synthesized/, index.md, log.md are committed.

The user never has to run anything. Hooks handle plumbing. Claude handles thinking.

From v4.4 LITE+ (still all in)

Token-optimized

• Slim CLAUDE.md core (~6K tokens, was ~24K in v4.3) + 12 lazy-loaded playbooks read only when relevant
• Tier-aware Phase 0: lite (3 docs) / standard (6, default) / full (9), instead of always-9
• Risk-tiered review: inline 5-question check by default, escalates to 5-agent /code-review only for security-sensitive / pre-PR
• Inline self-review — saves an LLM round-trip per task; full 7-category fallback still available when escalated
• Haiku subagent dispatch rules for cheap auxiliary tasks (doc updates, status reports, routine commits)
• Cache discipline + Playwright --interactive-only snapshot optimization

Verified token math: typical session 80–120K → 25–40K (~65–70% reduction). Quality bar preserved — every v4.3 rule is either in the slim core or in a lazy-loaded playbook.

Production-hardened

• hooks/ runtime enforcement (4 scripts auto-installed by setup):
  • wiki-ingest.py — auto-converts session JSONL → wiki markdown (NEW)
  • playbook-tracker.sh — counts playbook reads/turn, warns if > 2
  • cache-warn.sh — warns when CLAUDE.md is edited mid-session (would break prompt cache)
  • reset-counter.sh — resets per-turn counter on each user prompt
• Tier-aware Feature Tracker in SESSION.md for Lite/Standard tiers
• MemPalace reliability fixes — auto-detects working Python 3, uses absolute paths, eliminates silent hook failures

Tools

• diagnose-mempalace.sh — 12-check health diagnostic; pinpoints the exact failing layer with the exact fix command
• migrate-to-v44.sh — idempotent v4.3 → v4.x migration; auto-detects existing wing config, full backup, 8-check verification (NEW: wiki + wiki-ingest checks), safe rollback
• setup-graphify.sh — optional Graphify codebase knowledge graph integration (~71× cheaper structural queries on large codebases)

---

📦 What's in the Kit

nexalance-claude-code-kit/
├── NexaLance-CLAUDE-v4.4-LITE.md       Slim core (~6K tokens)
│
├── playbooks/                           12 lazy-loaded modules
│   ├── phase-0.md                       Phase 0 doc generation (tier-aware)
│   ├── feature-workflow.md              Feature implementation + phase-based dev
│   ├── testing.md                       Action-Level Testing protocol
│   ├── browser-automation.md            Playwright CLI + Chrome DevTools
│   ├── self-review-full.md              7-category fallback (escalation only)
│   ├── session-management.md            Session start/middle/end + Exit Gate
│   ├── persistent-memory.md             MemPalace setup + wing protocol
│   ├── plugin-orchestration.md          Plugin priority + conflict matrix
│   ├── patterns.md                      Common + anti-patterns
│   ├── operations.md                    File routing + deployment + rollback
│   ├── mempalace-troubleshooting.md     Symptom → cause → fix reference
│   └── llm-wiki.md                      LLM Wiki ingest/query/lint workflow (Karpathy pattern)
│
├── hooks/                               4 runtime scripts (auto-installed per project)
│   ├── wiki-ingest.py                   Auto-converts Claude session JSONL → wiki markdown
│   ├── playbook-tracker.sh              Counts playbook reads/turn
│   ├── cache-warn.sh                    Warns on mid-session CLAUDE.md edits
│   └── reset-counter.sh                 Resets per-turn counter
│
├── setup-nexalance.sh                   One-time machine setup (interpreter auto-detection)
├── setup-project-wing.sh                Per-project setup (tier-aware, wires hooks)
├── setup-graphify.sh                    Optional Graphify integration
├── migrate-to-v44.sh                    Safe v4.3 → v4.4 LITE migration
├── diagnose-mempalace.sh                12-check MemPalace health diagnostic
├── README.md                            This file
├── LICENSE                              MIT
└── .gitignore

---

🚀 Quick Start (5 minutes)

1. Clone this repo

git clone https://github.com/developerjillur/nexalance-claude-code-kit.git ~/Desktop/nexalance-kit
cd ~/Desktop/nexalance-kit
chmod +x *.sh hooks/*.sh

2. Run machine setup (once per machine)

bash setup-nexalance.sh

Installs MemPalace + plugins (Superpowers, Code Review, Feature Dev, Frontend Design) + Playwright CLI + Chromium + Chrome DevTools MCP + design tooling. Auto-detects your working Python 3 interpreter so MCP and hooks use the right one — no more pyenv/python3 surprises.

3. Set up your first project (v4.4 LITE recommended)

mkdir -p ~/projects/my-project && cd ~/projects/my-project

# Copy the LITE core + playbooks
cp ~/Desktop/nexalance-kit/NexaLance-CLAUDE-v4.4-LITE.md ./CLAUDE.md
cp -r ~/Desktop/nexalance-kit/playbooks ./playbooks

# Init project (tier: lite | standard | full — default standard)
bash ~/Desktop/nexalance-kit/setup-project-wing.sh \
    "my-project" "My Awesome Project" "client-name" standard

# Drop your PRD in docs/PRD.md, then open in VS Code
code .

4. Start building

In Claude Code panel, type:

Start project

Claude reads CLAUDE.md → reads playbooks/phase-0.md (lazy-loaded) → generates the docs your tier requires → asks for Go. Type Go. Building begins.

---

📊 Token Savings

Stage	v4.3	v4.4 LITE+	Saving
CLAUDE.md baseline load	~24K	~6K	−75%
One playbook on demand	n/a	~1–3K	(was always-loaded)
Phase 0 (Standard tier, 6 docs)	~18–30K	~12–18K	−33%
Routine feature + inline review	~25–40K	~8–15K	−65%
Security feature + 5-agent review	~30–40K	~25–35K	preserved (full depth on purpose)
Typical session total	~80–120K	~25–40K	−65 to −70%

Quality bar identical: every rule from v4.3 is either in the slim core (non-negotiables) or a lazy-loaded playbook (deep detail). Nothing removed.

---

🪜 Tier System

Set PROJECT_TIER once at project init; Phase 0 generates only what's needed.

Tier	Phase 0 docs	Feature progress lives in	Use for
lite	DESIGN, SCHEMA, SESSION (3)	SESSION.md → Feature Tracker	MVPs, prototypes, small tools
standard (default)	+ TAD, API, RULES (6)	SESSION.md → Feature Tracker	Most production work
full	+ FEATURES, TASKS, TESTING (9)	Dedicated FEATURES.md	Enterprise, multi-team, regulated

Tier flag is just the 4th argument to setup-project-wing.sh:

bash setup-project-wing.sh "my-wing" "Project" "client" lite     # 3 docs
bash setup-project-wing.sh "my-wing" "Project" "client" standard # 6 docs (default)
bash setup-project-wing.sh "my-wing" "Project" "client" full     # 9 docs

Need a doc your tier didn't generate? Generate it on demand later — no need to re-init.

---

🪝 Runtime Hooks (auto-installed)

Auto-installed by setup-project-wing.sh into .claude/hooks/. Wired into .claude/settings.json. They observe, warn, and ingest — they never block.

Hook	Fires on	What it does
wiki-ingest.py ⭐	SessionStart, SessionEnd	Converts Claude Code session JSONL → markdown into docs/wiki/raw/discussions/. Idempotent, ~50ms idle, secret redaction.
playbook-tracker.sh	Read of playbooks/*.md	Counts reads/turn, warns if > 2
cache-warn.sh	Edit/Write of CLAUDE.md or playbooks	Warns about prompt-cache invalidation
reset-counter.sh	UserPromptSubmit	Resets per-turn playbook counter

Diagnostic files:

• .claude/.playbook-counter — current-turn playbook read count
• docs/wiki/.ingest.log — wiki-ingest history + errors
• docs/wiki/.ingest-manifest.json — processed session IDs (idempotency)
• docs/wiki/.synthesis-pending — flag set when new content awaits synthesis

---

📚 Auto-LLM-Wiki (v4.5)

Every project gets a docs/wiki/ per-project knowledge base, fully automatic.

How it runs (zero user action)

1. setup-project-wing.sh scaffolds the structure at project init:

   docs/wiki/
   ├── CLAUDE.md           (schema)
   ├── index.md            (catalog)
   ├── log.md              (audit)
   ├── raw/                (immutable: discussions/, prompts/, articles/, interviews/, inbox/)
   └── synthesized/        (LLM-curated pages + _entities/)
   

2. Backfill on setup: wiki-ingest.py runs once to convert any pre-existing Claude Code sessions for this project.

3. Continuous ingest: SessionStart + SessionEnd hooks re-run wiki-ingest.py every time you open or close Claude Code in this project.

4. On-demand synthesis (Claude, not the user): when .synthesis-pending exists or you ask a domain/recall question, Claude reads index.md first, drills 2–4 relevant pages, cites raw sources back. Workflow: playbooks/llm-wiki.md.

Privacy

Path	Committed?	Why
docs/wiki/CLAUDE.md, index.md, log.md, synthesized/**	✅ yes	Schema + LLM-cleaned content
docs/wiki/raw/articles/, raw/prompts/	✅ yes	User-curated, vetted
docs/wiki/raw/discussions/, raw/interviews/	❌ gitignored	May contain secrets / PII
.ingest-manifest.json, .synthesis-pending, .ingest.log	❌ gitignored	Local state

What it complements (not replaces)

Layer	Stores
MemPalace	Episodic conversation memory (wing-isolated per project)
Graphify (opt-in)	Code semantic index (call graph, deps)
LLM Wiki	Compounding domain knowledge for THIS project
SESSION.md	Current task state

---

🩺 MemPalace Not Working? Run the Diagnostic First

The single most common issue: python (the bare command) doesn't resolve to Python 3 on your machine — common on macOS pyenv users, modern macOS without legacy aliases, and python3-only Linux. Older versions of the kit hardcoded python -m mempalace.mcp_server, which silently failed.

Diagnose any MemPalace problem in 5 seconds:

cd ~/projects/your-project
bash ~/Desktop/nexalance-kit/diagnose-mempalace.sh

The script runs 12 checks across all layers (interpreter, package install, MCP registration, project .mcp.json, hooks, PROJECT_WING value, wing data, MCP server liveness, and more) and prints prioritized root causes with the exact fix command for each.

Surgical one-liner if you already know it's the python issue:

PY=$(command -v python3)
claude mcp remove mempalace --scope user 2>/dev/null
claude plugin uninstall mempalace 2>/dev/null
claude mcp add mempalace --scope user -- "$PY" -m mempalace.mcp_server
sed -i.bak "s|python -m mempalace|$PY -m mempalace|g" ~/.claude/settings.json
# Restart Claude Code, then verify:
claude mcp list | grep mempalace

For full symptom→cause→fix reference, see playbooks/mempalace-troubleshooting.md.

v4.4 LITE+ structural fixes (auto-applied if you re-run setup-nexalance.sh):

• Auto-detects working Python 3 interpreter, uses absolute path everywhere
• Removes duplicate project-level MCP entry
• Hook errors log to ~/.mempalace-hook.log instead of /dev/null
• Wing init errors are visible
• Refuses placeholder wing names ("project-wing-name")
• Wing seeded with 4 triples on init so mempalace_search returns data immediately

---

🔄 Migrating an Existing Project from v4.3 → v4.4 LITE

One command (recommended):

cd ~/projects/your-existing-project
bash ~/Desktop/nexalance-kit/migrate-to-v44.sh standard   # or: lite | full

Auto-detects existing PROJECT_WING, PROJECT_NAME, CLIENT. Backs up to .nexalance-backup-<timestamp>/. Installs LITE core + 11 playbooks + 3 hooks. Upgrades SESSION.md to add Feature Tracker for Lite/Standard tiers (preserves history). Runs 6 verification checks before declaring success. Idempotent — re-running on an already-migrated project aborts safely.

Rollback (paths in script output):

cp .nexalance-backup-<timestamp>/CLAUDE.md.v43 CLAUDE.md
cp .nexalance-backup-<timestamp>/settings.json.v43 .claude/settings.json
rm -rf playbooks/ .claude/hooks/

---

🕸️ Optional Add-On: Graphify (Codebase Knowledge Graph)

For large or multi-language codebases, add Graphify — a knowledge-graph index over your code, docs, papers, and images. Claude queries the graph instead of re-reading files (~71× fewer tokens per structural query).

Layer model:

Layer	Tool	What it stores
Episodic ("what we did")	MemPalace	conversation memory, decisions, per-project wings
Semantic ("what the code IS")	Graphify	structure, deps, call graph, doc concepts
Session state	SESSION.md / HANDOFF.md	current task, next step

Install (once per machine)

bash ~/Desktop/nexalance-kit/setup-graphify.sh

Use it (per project)

# In Claude Code, after Phase 0:
/graphify .

# Common queries:
/graphify query "how does the auth flow work?"
/graphify path "LoginForm" "sessionStore"
/graphify .  --update                       # incremental refresh
/graphify clone https://github.com/foo/bar  # index an external repo
/graphify merge-graphs g1.json g2.json      # cross-repo graph

When to add it: ✅ Codebase >30k LOC, multi-language, lots of /docs PDFs/specs. ❌ Skip for tiny projects, greenfield/empty repos, or pure PRD work.

CLAUDE.md core has a rule: query graph.json BEFORE Glob/Grep on >20 files when graphify-out/ exists. Auto-applied.

---

🔄 Daily Workflow

Start working

1. Open VS Code with your project folder
2. Open Claude Code panel (Spark icon)
3. Type: "Continue" or "Resume"
4. Claude loads MemPalace memory → reads SESSION.md → resumes the exact task

Switch projects

1. Open a different project folder
2. Open Claude Code panel
3. Type: "Continue"
4. MemPalace switches to that project's wing automatically — zero context bleed

End your day

1. Type: "I'm done for today"
2. Claude automatically:
   → Runs Session Exit Gate (codebase review + tests)
   → Runs risk-tiered review (5-agent if pre-PR; otherwise inline)
   → Saves to MemPalace
   → Updates SESSION.md + HANDOFF.md
   → Git commits all progress

Natural commands (no plugin syntax to remember)

"Build the user auth system"   → /feature-dev auto-runs
"Test the login form"           → Playwright CLI opens browser
"Why is this page broken?"      → Chrome DevTools checks console
"Review the code"               → tier-appropriate review (inline or 5-agent)
"Plan the payment integration"  → Superpowers brainstorm
"Deploy to hosting"             → Playwright CLI headed browser

---

🔌 Integrated Plugins

Plugin	Purpose	Auto-trigger
Superpowers	Brainstorm → Plan → TDD → Execute	New ideas / planning
MemPalace	Persistent memory across sessions	Every session start/end
Code Review	5-agent parallel review	Security-sensitive or pre-PR
Feature Dev	7-phase feature implementation	Complex features
Frontend Design	Anti-AI-slop design quality	Any frontend work
Playwright CLI	Browser testing (4× cheaper than MCP)	Testing, deploying
Chrome DevTools	Console, network, performance debugging	UI bugs
Vercel Guidelines	100+ UX/accessibility rules	UI quality checks
Graphify (opt-in)	Codebase knowledge graph	Big-codebase exploration

---

🏗️ Multi-Project Setup

Each project gets its own MemPalace "wing" — fully isolated memory:

# Project 1 (Standard tier)
cd ~/projects/project-alpha
cp ~/Desktop/nexalance-kit/NexaLance-CLAUDE-v4.4-LITE.md ./CLAUDE.md
cp -r ~/Desktop/nexalance-kit/playbooks ./playbooks
bash ~/Desktop/nexalance-kit/setup-project-wing.sh "alpha" "Project Alpha" "client-a" standard

# Project 2 (Full tier — enterprise)
cd ~/projects/project-beta
cp ~/Desktop/nexalance-kit/NexaLance-CLAUDE-v4.4-LITE.md ./CLAUDE.md
cp -r ~/Desktop/nexalance-kit/playbooks ./playbooks
bash ~/Desktop/nexalance-kit/setup-project-wing.sh "beta" "Project Beta" "client-b" full

# Switching: just open the folder → Claude loads correct wing

---

❓ Troubleshooting

MemPalace shows "Failed to connect"

bash ~/Desktop/nexalance-kit/diagnose-mempalace.sh

The script identifies the exact root cause and prints the fix command. Most common: the kit's older configs hardcoded python which fails on pyenv / python3-only systems. Re-running setup-nexalance.sh from the v4.4 LITE+ release auto-fixes this.

Playwright CLI "not found"

npm install -g @playwright/cli
npx playwright install chromium

Plugin not installed

In Claude Code:

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
/plugin install code-review@claude-plugins-official
/plugin install feature-dev@claude-plugins-official
/plugin install frontend-design@claude-plugins-official

Context getting heavy / slow responses

In Claude Code: /compact. Or start a new session — MemPalace preserves all context. Also check .claude/.playbook-counter — if > 2, you've been reading too many playbooks per turn (review the routing table in CLAUDE.md core).

Browser test needs login

Tell Claude: "Open browser and navigate to [URL]". Browser opens (headed mode); you log in manually; tell Claude: "Continue testing".

New session lost context

Type: "Read docs/HANDOFF.md and docs/SESSION.md, then resume." With MemPalace properly working, this happens automatically. If it doesn't → run the diagnostic.

Wing memory bleeding between projects

Every MemPalace operation MUST include --wing PROJECT_WING. Check that PROJECT_WING in each project's CLAUDE.md is unique. Audit recent calls: search for mempalace_search in your transcript and verify each has --wing.

Hook errors flooding `~/.mempalace-hook.log`

This file is good news — it means hooks are firing and you can see what's failing. Common entries:

• ModuleNotFoundError: No module named 'mempalace' → re-run setup-nexalance.sh (interpreter mismatch)
• pyenv: python: command not found → same fix
• Permission denied → chmod -R u+w ~/.mempalace

---

📈 Version History

Version	Lines	Score	Key change
v2.0	415	7.2	Basic orchestrator
v3.0	913	9.1	Security, deployment, rollback
v4.0	1,409	9.6	Deep focus, action testing, self-review, memory
v4.1	1,641	9.6	Superpowers + MemPalace + Official plugins
v4.2	1,793	8.4	Playwright CLI + Chrome DevTools
v4.3	2,350+	9.2	Design system, conflict resolution, file organization
v4.4 LITE+	core ~530 + playbooks ~2,000	9.0	Token-optimized: slim core + lazy-loaded playbooks, tiered Phase 0, risk-tiered review, MemPalace reliability fixes
v4.5	+ docs/wiki/ auto-scaffold + wiki-ingest hook + llm-wiki playbook	9.2	Auto-LLM-Wiki: Karpathy pattern fully automated. Every project auto-scaffolds docs/wiki/, hooks auto-convert session JSONL → markdown, on-demand synthesis. Zero manual user action after setup.

---

🏢 Credits

Built by NexaLance Agency — a full-service digital agency delivering 500+ projects across 30+ countries since 2016.

• Website: nexalance.com
• GitHub: @developerjillur
• Email: info@sorobindu.com

Engineering co-pilot: Claude Opus 4.7 (1M context).

---

📄 License

MIT License — free to use, modify, and distribute.

---

NexaLance Agency — Your Success, Our Mission.