# create-ai-dev-vault A complete AI-assisted development environment for [Claude Code](https://claude.ai/claude-code). One command gives you a 12-agent pipeline, semantic search, crash recovery, institutional memory, [Ralph Wiggum](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md) iterative quality loops, [Yggdrasil](https://github.com/krzysztofdudek/Yggdrasil)-inspired architectural knowledge graphs, and comprehensive safety features — all running locally with **zero MCP servers required**. ```bash npx create-ai-dev-vault my-project ``` --- ## What You Get ### 12 Specialized AI Agents A full development pipeline where each agent has a specific role and isolated context window: ``` RESEARCHER -> ADVISOR -> ARCHITECT -> DESIGNER | [YOUR APPROVAL] | BUILDER -> TESTER -> CRITIC -> DEBUGGER -> REFACTOR -> REVIEWER ``` | Agent | Role | |-------|------| | **Researcher** | Gathers context from your vault, codebase, and docs before any work starts | | **Advisor** | Assesses feasibility and recommends approach | | **Architect** | Creates detailed implementation plans with pre-flight checklists | | **Designer** | Validates visual design and UX before and after building | | **Builder** | Implements the plan exactly. No scope creep. Self-correcting (3 iteration loops). | | **Tester** | Runs code, tests, verifies. Reports issues but doesn't fix them. | | **Critic** | Adversarial reviewer. Finds what will break. Scores on a 0-5 rubric. | | **Debugger** | Root-cause-first fixing. Max 5 iterations per issue. Surgical changes only. | | **Refactor** | Improves quality without changing behavior | | **Reviewer** | Final gate. Binary APPROVED/NEEDS WORK. Triggers retrospective + metrics. | | **Compliance** | Auto-triggers for legal/platform audits (every 5th run or milestone features) | | **Data Integrity** | Auto-triggers for data validation (after imports or every 10th run) | Every agent: - Reads past patterns and mistakes before starting - Writes learnings immediately (not batched at end) - Stops and flags contradictions instead of guessing - Has pushback rules to prevent cascading errors ### 10 Skills (Commands) | Command | What It Does | |---------|-------------| | `/pipeline [task]` | Run the full agent pipeline (auto-selects small/medium/large path) | | `/startup` | Daily briefing: crash recovery check, status, priorities | | `/closeout` | Full session end: handoff doc, logs, git commit, backup, continuation prompt | | `/experiment` | Structured sandbox in `.lab/` with THINK-TEST-REFLECT cycle | | `/quality-gate` | Typecheck + lint + test in one command | | `/context` | Show current session state (files changed, decisions, progress) | | `/briefing` | Generate plain-language status summary | | `/backup` | Backup workspace to local or cloud storage | | `/dashboard-update` | Update project dashboard with current metrics (auto-runs after pipeline) | | `/retrospective` | Self-evaluation after pipeline run (auto-runs after Reviewer) | ### 13 Hooks (All Enabled by Default) Safety, monitoring, and automation — no configuration needed: | Hook | Event | What It Does | |------|-------|-------------| | **session-start** | SessionStart | Archives old session, creates fresh state tracking | | **session-end** | SessionEnd | Marks session as ended, preserves state for recovery | | **checkpoint** | PostToolUse (Write/Edit) | Updates checkpoint after every file change | | **pre-compact** | PreCompact | Saves full state before context compression | | **reindex-vault** | PostToolUse (Write/Edit .md) | Auto-reindexes search after markdown changes | | **codebase-map-refresh** | PostToolUse (Write/Edit source) | Auto-updates architecture map | | **secret-detector** | PostToolUse (Write/Edit) | Warns if API keys or passwords are written | | **claudemd-watchdog** | PostToolUse (Write/Edit CLAUDE.md) | Warns if CLAUDE.md exceeds 300 lines | | **auto-commit** | PostToolUse (Write/Edit) | Safety checkpoint commits every 10 file operations | | **context-monitor** | PostToolUse (any) | Warns at 50/100/150 tool uses about context limits | | **learning-size-guard** | PostToolUse (Write/Edit) | Warns when learning files grow past 500 lines | | **backup-vault** | Manual (/backup, /closeout) | Zips and uploads vault to cloud storage | | **ralph-wiggum** | PostToolUse (Write/Edit source) | Quality gate that checks code after every write — type-check, lint, syntax. Iterates until clean. | ### Ralph Wiggum Iterative Loops Named after the [Ralph Wiggum pattern](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md) for Claude Code. Instead of an agent writing code and moving on (leaving bugs for the next agent), the agent checks its own work and self-corrects in a loop. **How it works:** 1. Builder/Debugger/Refactor writes code 2. The Ralph Wiggum hook automatically runs quality checks (type-check, lint, syntax) 3. If checks fail, the agent sees the errors and fixes them immediately 4. Repeat until clean (max 3-5 iterations to prevent runaway loops) 5. Agent outputs **QUALITY GATE PASSED** when all checks pass This catches 80%+ of bugs before they ever reach the Tester agent, dramatically reducing pipeline waste. ### Yggdrasil Architectural Knowledge Graph Inspired by [Yggdrasil](https://github.com/krzysztofdudek/Yggdrasil) — a semantic memory graph that captures the *meaning between* your files. Unlike code comments that describe what code does, Yggdrasil captures why the code is structured this way, what depends on what, and what constraints apply. **What's included:** - `.yggdrasil/` directory with templates for nodes (modules), aspects (cross-cutting concerns), and flows (end-to-end processes) - `yg-context.py` — query the graph from the command line: `python3 yg-context.py auth-system` - Agents automatically query Yggdrasil before modifying code, getting a focused context package: dependencies, constraints, related aspects, and involved flows **Why it matters:** Without architectural context, agents make changes in isolation — they don't know that modifying module A will break modules B, C, and D. With Yggdrasil, they do. ### 8 Python Scripts | Script | What It Does | |--------|-------------| | **vault-search.py** | Semantic + keyword hybrid search across all markdown files. BM25 + sentence-transformers with Reciprocal Rank Fusion. Multi-query mode for maximum recall. | | **codebase-map.py** | Scans your project, extracts imports/exports/dependencies, generates an architecture summary agents can read. | | **tldr-codefile.py** | Compressed code summaries (~75% token savings). Extracts functions, classes, types, exports — skips implementation details. | | **health-check.py** | Validates your vault setup: checks agents, hooks, learning files, CLAUDE.md size, git config, Python deps, scans for leaked secrets. Auto-fix mode. | | **diff-summary.py** | Plain-English summaries of git changes. Categorizes files by role, shows additions/removals, groups by project area. | | **token-estimator.py** | Estimates token costs for files and directories. Shows which files are most expensive, fits files into token budgets, groups by category. | | **vault-status.py** | At-a-glance dashboard showing everything installed: agents, skills, hooks, scripts, learning stats, search index, git activity, session state, available commands. Your terminal-based project overview. | | **yg-context.py** | Yggdrasil context builder. Query the architectural knowledge graph: `yg-context.py auth-system` returns the module's purpose, constraints, dependencies, relevant aspects, and related flows. | ### Learning System (Institutional Memory) Five interconnected files that persist knowledge across sessions: - **PATTERNS.md** — What works well. Approaches to reuse. - **MISTAKES.md** — What to avoid. Root causes and prevention. - **DECISIONS.md** — Settled decisions. Agents must not relitigate. - **IMPROVEMENTS.md** — Parking lot for ideas. Advisor checks every assessment. - **METRICS.md** — Pipeline runs, quality trends, per-agent stats. Every entry has a `Last Validated` field for confidence decay. Every 10th session, a consolidation pass archives stale entries. ### Session Management & Crash Recovery Every session is tracked and recoverable: ``` SESSION START |-- session-start.sh creates .session/ (state.md, checkpoint.md) | WORK |-- checkpoint.sh updates after every file write |-- pre-compact.sh saves snapshot before context compression |-- auto-commit.sh creates safety commits every 10 writes |-- context-monitor.sh warns at tool use thresholds | SESSION END |-- /closeout writes handoff, logs, commits, backs up |-- Continuation prompt for next session | CRASH RECOVERY |-- Next /startup detects crashed session (status: active, not ended) |-- Reads checkpoint.md to see exactly what was happening |-- Presents recovery briefing ``` --- ## Zero MCP Required This is important: **everything runs locally without any MCP server connections.** The vault-search.py script replaces what would normally need MCP-based tools. All hooks run as shell scripts. All agents use Claude Code's built-in tool system. This means: - No network dependencies for core functionality - No MCP connection issues (a known pain point for many Claude Code users) - Works offline (after initial setup) - No third-party service accounts needed - Your data never leaves your machine --- ## Quick Start ### 1. Create your vault ```bash npx create-ai-dev-vault my-project cd my-project ``` ### 2. Install Python dependencies ```bash pip3 install sentence-transformers numpy ``` ### 3. Customize CLAUDE.md Edit `CLAUDE.md` to describe your project. This is the most important file — Claude Code reads it at the start of every session. Key sections to fill in: - **Project Summary** — What your project does - **Tech Stack** — Your languages, frameworks, tools - **Conventions** — Your coding standards and patterns - **Current Status** — What's done, what's in progress ### 4. Build the search index ```bash python3 vault-search.py --reindex ``` ### 5. Run health check ```bash python3 health-check.py ``` ### 6. Start Claude Code ```bash claude # Then type: /startup ``` --- ## Project Structure ``` my-project/ |-- CLAUDE.md # Project brain (Claude reads this first) |-- .claude/ | |-- agents/ # 12 agent definitions | |-- skills/ # 10 skill definitions | |-- hooks/ # 13 hook scripts (all active) | |-- settings.json # Hook configuration | |-- agent-memory/ # Per-agent persistent memory |-- agent-learnings/ # Institutional memory | |-- PATTERNS.md | |-- MISTAKES.md | |-- DECISIONS.md | |-- IMPROVEMENTS.md | |-- METRICS.md |-- handoffs/ # Session handoff documents |-- docs/status/ # Session log, dashboard, briefings |-- agent-reports/ # Pipeline run reports |-- docs/ | |-- specs/ # What to build | |-- plans/ # How to build it | |-- guides/ # How-to documentation | |-- reference/ # Look-up information | |-- research/ # Deep dives | |-- status/ # Current state |-- .session/ # Live session state (auto-managed) |-- vault-search.py # Semantic + keyword search |-- codebase-map.py # Architecture visualization |-- tldr-codefile.py # Compressed code summaries |-- health-check.py # Setup validation |-- diff-summary.py # Git change summaries |-- token-estimator.py # Token cost estimation ``` --- ## Customization ### Adding project-specific agents Create new `.md` files in `.claude/agents/`. Follow the existing template: ```markdown --- name: my-agent description: What this agent does tools: [Read, Write, Edit, Grep, Glob, Bash] model: opus --- ## Your Role [What this agent is responsible for] ## Process [Step-by-step instructions] ## Rules - Stop on ambiguity rather than guessing - Write learnings immediately to agent-learnings/ - [Your project-specific rules] ``` ### Adjusting the pipeline Edit `.claude/skills/pipeline/SKILL.md` to change which agents run and in what order. The three task sizes (small/medium/large) can be customized. ### Tuning safety hooks All hooks are enabled by default. To disable one, remove it from `.claude/settings.json`. To adjust thresholds: - **auto-commit interval**: Edit `COMMIT_INTERVAL` in `.claude/hooks/auto-commit.sh` (default: 10) - **context warnings**: Edit thresholds in `.claude/hooks/context-monitor.sh` (default: 50/100/150) - **learning file cap**: Edit `MAX_LINES` in `.claude/hooks/learning-size-guard.sh` (default: 500) ### Adding your own hooks Create a `.sh` file in `.claude/hooks/` and register it in `.claude/settings.json`: ```json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "command": ".claude/hooks/my-hook.sh", "timeout": 10, "async": true } ] } ] } } ``` --- ## Commands Reference ### vault-search.py ```bash vault-search "query" # Hybrid search (semantic + keyword) vault-search "query" --top 10 # More results vault-search "query" --full # Don't truncate vault-search "query" --explain # Show why each result matched vault-search "query" --semantic # Semantic only vault-search "query" --keyword # Keyword only vault-search "query" --multi # Multi-query (3 phrasings, max recall) vault-search --reindex # Force rebuild index vault-search --stats # Show index statistics ``` ### codebase-map.py ```bash codebase-map # Map current directory codebase-map /path/to/project # Map specific directory codebase-map --depth 3 # Limit scan depth codebase-map --format json # JSON output ``` ### tldr-codefile.py ```bash tldr-codefile src/App.tsx # Summarize one file tldr-codefile src/ --recursive # Summarize directory tldr-codefile src/ --out .tldr/ # Write to directory tldr-codefile src/ --stats # Show compression ratio ``` ### health-check.py ```bash health-check # Run all checks health-check --fix # Auto-fix what's possible health-check --quiet # Only show failures health-check --json # Machine-readable output ``` ### diff-summary.py ```bash diff-summary # Uncommitted changes diff-summary HEAD~3 # Last 3 commits diff-summary main..develop # Branch comparison diff-summary --staged # Staged changes only diff-summary --since "2 hours ago" # Time-based diff-summary --files # Just file list with stats ``` ### token-estimator.py ```bash token-estimator src/ # Estimate directory token-estimator src/App.tsx # Estimate single file token-estimator . --top 20 # Top 20 most expensive token-estimator . --budget 50000 # What fits in 50K tokens token-estimator . --category # Group by file category ``` ### vault-status.py ```bash vault-status # Full status overview vault-status --brief # One-line summary vault-status --json # Machine-readable output ``` --- ## FAQ ### Does this work with models other than Claude? The agent definitions and pipeline are designed for Claude Code, but the vault structure, learning system, hooks, and scripts work with any AI coding tool that reads markdown files. Adapting the agents for other tools is straightforward. ### Do I need Obsidian? No. The vault is just a directory of markdown files. Obsidian is a great way to browse and edit them, but it's optional. Any markdown editor works. ### How much does this cost? The package is free and open source (Apache 2.0). You need a Claude Code subscription to use the agents — check [Claude pricing](https://claude.ai/pricing) for current rates. ### Can I use this with an existing project? Yes! Run `npx create-ai-dev-vault .` in your existing project directory. It will add the vault structure alongside your code without disturbing existing files. ### What if my Claude Code session crashes? The crash recovery system handles this automatically. The next `/startup` will detect the crashed session, show you what was happening, and help you resume. Checkpoint files track every file write, and pre-compact snapshots preserve state before context compression. ### How do I update? Re-run `npx create-ai-dev-vault@latest .` in your project. It will update scripts and add new hooks without overwriting your customizations (CLAUDE.md, learning files, and handoffs are preserved). --- ## Contributing Contributions welcome! Please open an issue or PR at [github.com/mmayasaurus/create-ai-dev-vault](https://github.com/mmayasaurus/create-ai-dev-vault). --- ## License Apache 2.0 -- see [LICENSE](LICENSE) for details. Built with Claude Code by [Maya Tobi](https://github.com/mmayasaurus).