create-ai-dev-vault

A complete AI-assisted development environment for Claude Code. One command gives you a 12-agent pipeline, semantic search, crash recovery, institutional memory, Ralph Wiggum iterative quality loops, Yggdrasil-inspired architectural knowledge graphs, and comprehensive safety features — all running locally with zero MCP servers required.

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 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 — 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

npx create-ai-dev-vault my-project
cd my-project

2. Install Python dependencies

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

python3 vault-search.py --reindex

5. Run health check

python3 health-check.py

6. Start Claude Code

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:

---
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:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "command": ".claude/hooks/my-hook.sh", "timeout": 10, "async": true }
        ]
      }
    ]
  }
}

Commands Reference

vault-search.py

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

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

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

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

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

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

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 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.

License

Apache 2.0 -- see LICENSE for details.

Built with Claude Code by Maya Tobi.