zen

# Zen — AI Workflow Architecture for Claude Code

> **What You See Is What It Does** — Structured workflows, persistent memory, and self-evolving agents for Claude Code.

Zen is a plugin that brings production-grade software engineering workflows to Claude Code. It provides 91 MCP tools, 30 slash commands, 16 specialized agents, and 43 skills — orchestrated through declarative synchronization rules that make AI-assisted development reproducible and auditable.

## Installation

```bash
# Add the Zen marketplace
/plugin marketplace add mkolb22/zen-plugin

# Install the plugin
/plugin install zen
```

Dependencies install automatically on first session start (requires Node.js 18+).

## What Zen Does

| Capability | How |
|-----------|-----|
| **Workflow orchestration** | Declarative sync rules route tasks through Story, Architecture, Implementation, Quality, and Version phases |
| **Code intelligence** | AST indexing with tree-sitter, semantic search with MiniLM embeddings, and knowledge graphs |
| **Persistent memory** | Semantic memories with embeddings, confidence evolution, and graph traversal survive across sessions |
| **Checkpoint/restore** | Save and restore full session context with structured layers, warm-up files, and lessons learned |
| **Test generation & repair** | Generate tests, run them, analyze coverage, and auto-repair failures iteratively |
| **Spec-driven development** | Define function contracts (pre/postconditions, effects) and generate verified code |
| **Competitive evaluation** | Statistical A/B testing with Welch's t-test measures tool impact on code quality |
| **Agent evolution** | MAP-Elites optimization of agent prompts and workflow topologies |

## Quick Start

```
User: /zen:feature "Add user authentication"

Phase 1: Story (Sonnet)
  Created story with 4 acceptance criteria

Phase 2: Architecture (Opus)
  Evaluated 3 approaches -> selected OAuth2 with passport.js

Phase 3: Implementation (Sonnet)
  Generated auth middleware, token refresh, 12 tests

Phase 4: Quality (Sonnet)
  Code review: approved | Tests: 12/12 passing

Phase 5: Version (Sonnet)
  Committed with full provenance trail
```

## Commands

30 slash commands organized by function:

**Workflow**: `/zen:feature`, `/zen:workflow`, `/zen:sync`, `/zen:task`, `/zen:trace`, `/zen:replay`
**Context**: `/zen:checkpoint`, `/zen:restore`, `/zen:health`, `/zen:status`
**Memory**: `/zen:remember`, `/zen:recall`, `/zen:forget`, `/zen:global-remember`, `/zen:global-recall`
**Analysis**: `/zen:costs`, `/zen:observe`, `/zen:classify`, `/zen:estimate`, `/zen:predict-cost`, `/zen:explore`
**Quality**: `/zen:pr-review`, `/zen:retrospective`, `/zen:compete`, `/zen:spec`, `/zen:slo`
**Utility**: `/zen:cache`, `/zen:profile`, `/zen:visualize`, `/zen:reasoning`, `/zen:help`

## Agents

16 specialized agents for multi-agent workflows:

| Agent | Model | Purpose |
|-------|-------|---------|
| story-concept | Sonnet | Capture and validate requirements |
| architecture-concept | Opus | Design systems with deep reasoning |
| implementation-concept | Sonnet | Generate code from specifications |
| quality-concept | Sonnet | Review code and run tests |
| security-concept | Sonnet | Threat modeling and vulnerability scanning |
| verification-concept | Sonnet | Multi-pass independent review |
| version-concept | Sonnet | Git operations and release management |
| code-analysis-concept | Sonnet | Codebase context via AST and semantic search |
| context-concept | Sonnet | Manage context window usage |
| documentation-concept | Sonnet | Generate comprehensive documentation |
| spec-concept | Sonnet | Define contracts and generate code from specs |
| research-concept | Sonnet | Gather evidence before architecture decisions |
| checkpoint-concept | Sonnet | Session state preservation |
| debate-advocate | Sonnet | Propose and defend architectural approaches |
| debate-critic | Sonnet | Challenge assumptions and identify weaknesses |
| debate-synthesis | Sonnet | Resolve debate and produce final decisions |

## MCP Server — 91 Tools

The zen-server provides 91 tools across 12 modules:

| Module | Tools | Purpose |
|--------|-------|---------|
| **AST Indexing** | 8 | Code structure analysis with tree-sitter (TS, JS, Python, Go, Rust, Java, C, Swift) |
| **Semantic Search** | 4 | MiniLM-L6-v2 embedding-based code search |
| **Memory** | 7 | Persistent semantic memory with graph traversal |
| **Knowledge Graph** | 7 | Entity/relation graphs with hybrid search and community detection |
| **Framework** | 11 | Workflow orchestration, concepts, sync rules |
| **State** | 10 | Health, events, checkpoints, stories, workflow sessions |
| **Spec** | 6 | Type-safe specification DSL with code generation |
| **Testing** | 7 | Test generation, execution, coverage analysis |
| **Repair** | 6 | Self-debug, iterative refinement, repair history |
| **Evolution** | 4 | Genetic prompt optimization |
| **Compete** | 6 | Statistical A/B testing framework |
| **Agent Evolution** | 15 | Genome parsing, MAP-Elites, topology co-evolution |

## Architecture

### Concepts

Zen uses stateless concept services that never call each other directly. Synchronization rules define how outputs flow between them:

```yaml
- when: { concept: story, status: completed }
  where: "story.status == 'ready'"
  then: { concept: architecture, model: opus, action: design }

- when: { concept: architecture, status: completed }
  then: { concept: implementation, model: sonnet, action: generate }
```

### State Storage

All state lives in SQLite databases created in your project's `koan/` directory:

```
koan/
├── state/state.db     # Health, events, checkpoints, stories, workflows
├── memory/memory.db   # Semantic memories, embeddings, knowledge graph
└── index/             # AST index (rebuilt on demand)
```

State is per-project and gitignored. The plugin itself is read-only.

### Multi-Tier Model Optimization

Zen assigns models by task complexity:
- **Opus**: Architecture decisions, deep reasoning, complex trade-offs
- **Sonnet**: Implementation, quality review, most workflows
- **Haiku**: Checkpoints, fast tasks, evolved prompts

## Skills

43 skills provide specialized capabilities to agents:

**Analysis**: code-coverage-analysis, dependency-impact-analysis, error-classification, ide-diagnostics, provenance-analysis, project-structure

**Design**: api-design-patterns, code-template-patterns, refactoring-patterns, security-design-patterns, synchronization-patterns, test-generation-strategy, schema-validation

**Process**: acceptance-criteria-generation, branch-strategy, changelog-generation, documentation-generation, release-management, requirement-prioritization, semantic-versioning, workflow-replay

**Performance**: batch-processing, cost-optimization, incremental-loading, output-caching, performance-estimation, performance-testing-patterns, smart-retry

**Memory**: cross-project-knowledge, semantic-memory

**Quality**: error-messages, smart-summarization, story-decomposition, security-vulnerability-scanning

## Hooks

14 lifecycle hooks integrate with Claude Code events:

| Event | Hook | Purpose |
|-------|------|---------|
| SessionStart | session-start.sh | Initialize state, show checkpoints, install deps |
| Stop | stop.sh | Auto-checkpoint on session exit |
| PreCompact | pre-compact.sh | Save state before context compression |
| PostToolUse | post-tool-use.sh | Track context after subagent tasks |
| PostToolUse | post-tool-structure-check.sh | Validate file writes against project structure |
| PreToolUse | pre-tool-grounding.sh | Ground bash commands in project context |
| UserPromptSubmit | user-prompt-submit.sh | Enrich prompts with context |
| SubagentStop | subagent-stop.sh | Track subagent completion |

Plus: statusline (real-time context health), concept-complete, post-commit, sync-blocked, init-koan, session-exit-checkpoint.

## Requirements

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
- Node.js 18+ (for MCP server)
- Git repository initialized in your project

## How It Works

When you install Zen as a plugin, Claude Code automatically discovers:
- **Commands** in `commands/` — available as `/zen:command-name`
- **Agents** in `agents/` — available as `zen:agent-name` in Task tool
- **Skills** in `skills/` — specialized capabilities for agents
- **Hooks** in `hooks/hooks.json` — lifecycle event handlers
- **MCP Server** in `.mcp.json` — 91 tools loaded on session start

State databases are created in your project's `koan/` directory on first use. The plugin cache at `~/.claude/plugins/cache/` is read-only after installation.

## License

Commons Clause + MIT. See [LICENSE](LICENSE).

Free to use, modify, and distribute for any purpose, except selling the software itself or offering it as a paid service.