Meridian

Development workflow engine that gives AI coding agents persistent memory, structured execution, and quality enforcement. Built on SQLite with zero external dependencies.

1058 tests | 39 commands | Python stdlib only

Why This Exists

If you've used Claude Code (or similar AI coding tools) on anything beyond a single-file change, you've hit the wall: context windows fill up, sessions reset, and you're back to explaining everything from scratch. There's no way to track what was done, what failed, or what comes next.

Meridian treats your development workflow as a state machine. Every phase, plan, decision, and checkpoint lives in a local SQLite database. When your session resets — and it will — you resume from the exact same position with the exact same prompt. No re-explaining. No lost progress.

It was built out of frustration with the gap between what AI coding assistants can do and what they actually deliver on real projects with multiple phases, parallel work streams, and quality requirements.

Key Features

Deterministic Resume

All state lives in SQLite. Resume prompts are generated entirely from the database — no LLM prose. Same state = same prompt, guaranteed.

prompt1 = generate_resume_prompt("/path/to/project")
prompt2 = generate_resume_prompt("/path/to/project")
assert prompt1 == prompt2  # Always identical

Context-Efficient Subagents

Each plan executes in a fresh, scoped subagent — only the context it needs, nothing more. This is a deliberate design choice: instead of burning through a 1M-token conversation on a single task, Meridian breaks work into focused units that use a fraction of the context window. Less token usage means fewer weekly limit hits and more consistent output quality. Plans within the same wave run in parallel.

Context budget is fully configurable to match your plan's limits:

# Option 1: Per-project setting (persisted in DB)
/meridian:config set context_size 150000

# Option 2: Environment variable
export MERIDIAN_CONTEXT_SIZE=150000

Priority: project setting > env var > model auto-detect > default (200k).

Quality Gates

Automated enforcement at every stage:

Regression Gate — prior phase tests run before new execution begins
Requirements Coverage — every requirement must map to a plan
Stub Detection — scans for TODO, FIXME, NotImplementedError after execution
Two-Stage Review — spec compliance first, then code quality
Node Repair — automatic retry, decomposition, or pruning on failure

Pluggable Board Sync

Connect any kanban board (Linear, Jira, or your own) via the BoardProvider protocol. Phase transitions automatically sync ticket status. Works standalone without any board configured.

export BOARD_PM_SCRIPT=~/tools/my-board-cli.sh  # Point to your CLI

See Board Integration Guide for details.

Session Intelligence

Structured Handoff — /meridian:pause captures full context as JSON
Debug Knowledge Base — resolved bugs persist and inform future debugging
Decision Traceability — every decision gets a unique ID and audit trail
Notes & Seeds — capture ideas with trigger conditions that surface at the right time

Remote Agent Dispatch

Optionally dispatch plans to any self-hosted AI agent (Nero, OpenClaw, Hermes, or your own) for autonomous execution on a secondary machine. The agent implements plans, creates branches and PRs, and reports back via HTTP or webhooks.

Quick Start

# 1. Clone and install
git clone https://github.com/mattjaikaran/meridian.git ~/dev/meridian
cd ~/dev/meridian && uv sync

# 2. Register as Claude Code skill
ln -sfn ~/dev/meridian ~/.claude/skills/meridian
export MERIDIAN_HOME=~/dev/meridian  # Add to ~/.zshrc
uv run python scripts/generate_commands.py --fix-symlink
uv run python scripts/generate_commands.py

# 3. Use in any project
/meridian:init                    # Initialize state database
/meridian:plan "Build feature X"  # Create phases and plans
/meridian:execute                 # Run with fresh-context subagents
/meridian:next                    # Auto-advance to next step

See the Getting Started Guide for a full walkthrough.

Architecture

graph TB
    User["/meridian:* commands"] --> Skills["SKILL.md routing"]
    Skills --> Scripts["scripts/*.py<br/>(state machine, gates, security)"]
    Scripts --> DB[(".meridian/state.db<br/>SQLite, WAL mode")]
    Scripts --> Agents["Subagent Dispatch<br/>Scoped context per plan"]

    Agents --> W1["Wave 1: Plan 1 + Plan 2 + Plan 3<br/>(parallel)"]
    W1 --> W2["Wave 2: Plan 4 + Plan 5<br/>(after wave 1 completes)"]

    Scripts -.->|"optional"| Nero["Remote Agent<br/>Self-hosted AI executor"]
    Scripts -.->|"optional"| Board["Board Provider<br/>Linear / Jira / Custom CLI"]

    Nero -.->|"commit SHAs + PR URLs"| Scripts

    Board -.->|"ticket sync"| Scripts

Data Model

graph LR
    P[Project] --> M[Milestone]
    M --> Ph[Phase]
    Ph --> Pl[Plan]
    Pl --> W[Wave]

    style P fill:#4a9eff,color:#fff
    style M fill:#6b7280,color:#fff
    style Ph fill:#8b5cf6,color:#fff
    style Pl fill:#10b981,color:#fff
    style W fill:#f59e0b,color:#fff

Project > Milestone (v1.0, v2.0) > Phase (work unit with acceptance criteria) > Plan (one subagent's task) > Wave (parallel execution group)

State Machines

stateDiagram-v2
    direction LR
    [*] --> planned
    planned --> context_gathered
    context_gathered --> planned_out
    planned_out --> executing
    executing --> verifying
    verifying --> reviewing
    reviewing --> complete
    complete --> [*]

    planned --> blocked
    executing --> blocked
    blocked --> planned
    blocked --> executing

stateDiagram-v2
    direction LR
    [*] --> pending
    pending --> executing
    executing --> complete
    executing --> failed
    failed --> pending: retry (node repair)
    executing --> paused
    paused --> executing
    pending --> skipped: pruned
    complete --> [*]

Commands (39)

Core Workflow

Command	Description
`/meridian:init`	Initialize `.meridian/` and `state.db` in current project
`/meridian:plan`	Brainstorm phases, gather context, generate wave-assigned plans
`/meridian:execute`	Run plans via fresh subagents with TDD and review
`/meridian:next`	Auto-detect state and advance to the next logical step
`/meridian:resume`	Deterministic resume from SQLite state
`/meridian:status`	Show progress, blockers, and next action
`/meridian:ship`	Commit + push + create PR via `gh` CLI

Quick Actions

Command	Description
`/meridian:fast`	Inline trivial tasks — no DB records
`/meridian:quick`	Lightweight tracked task — no phase overhead
`/meridian:do`	Natural language router — maps freeform text to commands
`/meridian:note`	Zero-friction idea capture (append, list, promote)
`/meridian:seed`	Backlog parking lot with trigger conditions

Planning & Discussion

Command	Description
`/meridian:discuss`	Gather phase context through adaptive questioning
`/meridian:insert-phase`	Insert a phase mid-milestone without renumbering
`/meridian:remove-phase`	Remove a future phase and renumber
`/meridian:complete-milestone`	Archive milestone and prepare next version
`/meridian:roadmap`	Cross-milestone progress bars and ETAs

Quality & Review

Command	Description
`/meridian:review`	Two-stage code review (spec compliance + quality)
`/meridian:audit-uat`	Cross-phase verification debt tracking
`/meridian:verify-phase`	Nyquist compliance check on validation artifacts
`/meridian:validate`	Git state + DB consistency validation
`/meridian:debug`	4-phase systematic debugging with knowledge base

Visibility & Metrics

Command	Description
`/meridian:dashboard`	Project health, velocity, stalls, dispatch status
`/meridian:history`	Event timeline — all state transitions
`/meridian:report`	Session summary with work completed and outcomes
`/meridian:profile`	Developer preference profiling from project analysis

Session Management

Command	Description
`/meridian:pause`	Structured handoff with full context for rich resume
`/meridian:resume`	Restore from HANDOFF.json + DB state
`/meridian:checkpoint`	Manual save point with notes
`/meridian:pr-branch`	Create clean PR branch filtering internal commits

Execution Control

Command	Description
`/meridian:autonomous`	Hands-free execution across remaining phases
`/meridian:freeze`	Lock edit scope to prevent unrelated changes
`/meridian:learn`	Capture execution patterns as persistent rules
`/meridian:retro`	Structured retrospective after milestone completion
`/meridian:config`	View and modify workflow configuration

Integration

Command	Description
`/meridian:dispatch`	Send plans to a remote AI agent for autonomous execution
`/meridian:scan`	Codebase audit and work discovery
`/meridian:template`	Apply pre-built workflow templates
`/meridian:migrate`	Move Meridian state between projects
`/meridian:revert`	Revert a completed plan's changes

Typical Workflow

# 1. Initialize in your project
/meridian:init

# 2. Plan the work
/meridian:plan "Build user authentication with JWT"
# --> Creates phases: DB Models, API Routes, Middleware, Tests
# --> Each phase gets context-gathered plans in parallel waves

# 3. Execute with quality gates
/meridian:execute
# --> Spawns scoped subagents per plan (context-efficient)
# --> TDD enforced: red -> green -> refactor
# --> Regression gate blocks if prior phases break
# --> Auto-advances state machine on completion

# 4. Monitor progress
/meridian:dashboard          # Health, velocity, ETA
/meridian:next               # What should happen next?

# 5. Handle session boundaries
/meridian:pause              # Save context before stopping
# ... new session ...
/meridian:resume             # Deterministic restore

# 6. Ship it
/meridian:ship               # Commit + push + PR

Quick Tasks (Skip Full Planning)

/meridian:fast "fix typo in README"                    # Inline, no tracking
/meridian:quick "add error handling to API routes"     # Tracked, no phase
/meridian:do "what's next"                             # Natural language routing

Capturing Ideas

/meridian:note append "should add caching to API responses"
/meridian:note list
/meridian:note promote N001                            # Convert to task

/meridian:seed plant "rate limiting" --trigger "after_phase:Auth"
# --> Surfaces automatically when Auth phase completes

Installation

Prerequisites

Python 3.11+ — python3 --version
uv — curl -LsSf https://astral.sh/uv/install.sh | sh
git — git --version
Claude Code — with skills support

Install

# Clone
git clone https://github.com/mattjaikaran/meridian.git ~/dev/meridian
cd ~/dev/meridian

# Install dev dependencies (pytest only — everything else is stdlib)
uv sync

# Register as Claude Code skill
ln -sfn ~/dev/meridian ~/.claude/skills/meridian

# Set MERIDIAN_HOME (add to ~/.zshrc or ~/.bashrc)
export MERIDIAN_HOME=~/dev/meridian

# Generate command wrappers
uv run python scripts/generate_commands.py --fix-symlink
uv run python scripts/generate_commands.py

Verify

# Should list 39 .md files
ls ~/.claude/commands/meridian/

# Should show 1055 passed
uv run pytest tests/ -q

# In Claude Code, type /meridian: — autocomplete shows all commands

CLI (scripts/cli.py)

Meridian ships a standalone CLI for inspecting and advancing project state directly from the terminal — no Claude Code session required.

Install options

# Run directly (no install needed)
PYTHONPATH=/path/to/meridian uv run --project /path/to/meridian -- python scripts/cli.py --help

# Install into current environment with uv (recommended)
uv pip install -e /path/to/meridian

# Or with pip
pip install -e /path/to/meridian

After installing, the meridian binary is available on your PATH:

meridian --help                          # show all subcommands
meridian init                            # initialize in current project
meridian status                          # show project status
meridian next                            # show next recommended action
meridian --json status                   # machine-readable JSON output

Available subcommands

Subcommand	Description
`status`	Show project status
`next`	Show next recommended action
`init`	Initialize Meridian in current project
`note`	Capture notes (add/list/promote)
`fast`	Execute a fast inline task
`dashboard`	Open HTML dashboard
`execute`	Dispatch a plan for execution
`plan`	Show current plan status
`resume`	Generate a deterministic resume prompt
`ship`	Complete a milestone
`checkpoint`	Create a checkpoint
`pause`	Freeze/unfreeze a directory
`review`	Show cross-review status
`validate`	Validate project state against git
`config`	Manage configuration profiles
`workstream`	Manage workstreams (list/create/activate)

Uninstall

cd ~/dev/meridian
uv run python scripts/generate_commands.py --uninstall
rm ~/.claude/skills/meridian

Board Integration

Meridian syncs phase status to external kanban boards via a pluggable provider system.

Built-in Providers

Provider	Description
`noop`	Default — Meridian works standalone
`cli`	Shells out to any board CLI tool via `BOARD_PM_SCRIPT` env var

Using the CLI Provider

# Point to your board's CLI script
export BOARD_PM_SCRIPT=~/tools/my-board-cli.sh

# Set provider during project init
# board_provider = "cli"
# board_project_id = "YOUR-PROJECT"

Your script must support:

my-board-cli.sh ticket add <project_id> <name> --description <desc>
my-board-cli.sh ticket move <ticket_id> <status>

Writing a Custom Provider

from scripts.board.provider import register_provider

class LinearProvider:
    def create_ticket(self, project_id: str, name: str, description: str = "") -> str | None:
        # Call Linear API, return issue ID
        ...

    def move_ticket(self, ticket_id: str, status: str) -> str | None:
        # Update issue status
        ...

register_provider("linear", LinearProvider)

See Board Integration Guide for the full protocol.

Quality Gates

Regression Gate

Before executing a phase, all prior phases' test suites run. If any regress, execution blocks.

Requirements Coverage

Every phase requirement must map to at least one plan. Gaps trigger warnings.

Stub Detection

After execution, scans modified files for TODO, FIXME, NotImplementedError, and pass-only functions.

Node Repair

Automatic recovery when plans fail:

RETRY — re-execute with error context
DECOMPOSE — split into smaller sub-plans
PRUNE — skip non-critical plan and continue

Two-Stage Review

Spec compliance — does implementation match the plan?
Code quality — security, performance, conventions

Session Intelligence

Deterministic Resume

Resume prompts are generated from SQLite — no LLM prose. Same state = same prompt.

Structured Handoff

/meridian:pause creates HANDOFF.json with active phase, blockers, recent decisions, modified files, and user notes. /meridian:resume consumes it.

Debug Knowledge Base

Resolved debug sessions are persisted to debug-kb.md. Future sessions search for similar symptoms before investigating.

Decision Traceability

Decisions get unique IDs (DEC-001, DEC-002, ...) linked to plans. Full audit trail in DISCUSSION-LOG.md.

Security

Centralized validation in scripts/security.py:

Function	Purpose
`validate_path()`	Reject path traversal (`../`) and symlink escapes
`safe_json_loads()`	JSON parsing with size limits
`validate_field_name()`	SQL-safe identifiers only
`sanitize_shell_arg()`	Reject shell metacharacters

Project Structure

meridian/
├── README.md
├── LICENSE                            # Apache 2.0
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SKILL.md                           # Skill entry point (39 commands)
├── pyproject.toml                     # uv-managed, stdlib only
│
├── scripts/                           # Python modules (stdlib only)
│   ├── db.py                          # Schema v7, migrations, WAL mode
│   ├── state.py                       # CRUD, transitions, auto-advance
│   ├── resume.py                      # Deterministic resume
│   ├── security.py                    # Path, JSON, field, shell validation
│   ├── gates.py                       # Regression, coverage, stub detection
│   ├── node_repair.py                 # RETRY / DECOMPOSE / PRUNE
│   ├── metrics.py                     # Velocity, stalls, forecasts
│   ├── board/                         # Pluggable board sync
│   │   ├── provider.py                # BoardProvider protocol + registry
│   │   ├── cli.py                     # CLI-based provider (env var config)
│   │   └── sync.py                    # Phase transition sync bridge
│   ├── dispatch.py                    # Remote agent HTTP dispatch
│   ├── sync.py                        # Bidirectional remote agent sync
│   └── ...                            # 30+ modules total
│
├── skills/                            # 39 slash command definitions
│   ├── init/SKILL.md
│   ├── plan/SKILL.md
│   ├── execute/SKILL.md
│   └── ...                            # 39 total
│
├── tests/                             # 1058 tests across 55 files
│   ├── test_state.py
│   ├── test_security.py
│   ├── test_gates.py
│   └── ...
│
├── prompts/                           # Subagent prompt templates
│   ├── implementer.md
│   ├── spec-reviewer.md
│   ├── code-quality-reviewer.md
│   ├── context-gatherer.md
│   └── resume-template.md
│
├── references/                        # Architecture documentation
│   ├── state-machine.md               # State transitions + rules
│   ├── discipline-protocols.md        # TDD, debugging, review protocols
│   └── remote-agent.md                # Remote agent dispatch protocol
│   └── board-integration.md           # Pluggable board sync protocol
│
└── docs/                              # User guides and tutorials
    ├── getting-started.md             # Installation + first project
    ├── command-reference.md           # All 39 commands
    ├── architecture.md                # System design + diagrams
    └── tutorials/
        ├── workflow-walkthrough.md     # End-to-end project tutorial
        ├── board-integration.md        # Setting up board sync
        └── remote-dispatch.md         # Remote agent setup guide

Schema

Current version: v7 (with automatic migrations from any prior version)

Table	Purpose
`project`	Project metadata, repo path, tech stack, board config
`milestone`	Versioned releases with status lifecycle
`phase`	Work units with sequence, priority, acceptance criteria
`plan`	Subagent tasks with wave assignment and TDD flag
`checkpoint`	Save points with git state and blockers
`decision`	Decisions with unique IDs and rationale
`plan_decision`	Links plans to informing decisions
`nero_dispatch`	Remote dispatch tracking (task ID, status, PR URL)
`quick_task`	Lightweight tasks without phase overhead
`state_event`	Audit log for all state transitions
`settings`	Key-value project configuration
`review`	Code review records
`learning`	Execution patterns captured as persistent rules

Stack

Python 3.11+ — stdlib only (sqlite3, json, pathlib, subprocess, re, hashlib)
SQLite — WAL mode, foreign keys, busy_timeout, automatic backups
Claude Code Skills — SKILL.md routing with auto-generated command wrappers
pytest — 1055 tests (dev dependency only)

Documentation

Document	Description
Getting Started	Installation and first project walkthrough
Command Reference	All 39 commands with usage and examples
Architecture Guide	System design, data model, state machines
Workflow Tutorial	End-to-end project from init to ship
Board Integration	Setting up kanban board sync
Remote Dispatch	Self-hosted agent setup
State Machine Reference	Phase and plan lifecycle rules
Discipline Protocols	TDD, debugging, review enforcement
Board Protocol	BoardProvider API and custom providers
Remote Agent Protocol	HTTP dispatch and webhook integration

Troubleshooting

Commands not showing in Claude Code

cd ~/dev/meridian
uv run python scripts/generate_commands.py --fix-symlink
uv run python scripts/generate_commands.py

"Database is locked"

Meridian uses WAL mode with 5s busy_timeout and exponential backoff retry. If persistent:

lsof .meridian/state.db

"Module not found" errors

echo $MERIDIAN_HOME  # Should print your meridian clone path
export MERIDIAN_HOME=~/dev/meridian

State seems corrupted

Automatic backups exist before every migration in .meridian/backups/:

cp .meridian/backups/state-<timestamp>.db .meridian/state.db

Inspiration & Credits

Meridian grew out of working with several AI workflow tools — specifically GSD (Get Shit Done), BMAD, and various "superpowers" skill collections for Claude Code. Each of these contributed ideas worth keeping:

GSD — the concept of a SQLite-backed state machine for tracking AI agent work across sessions
BMAD — structured phase-based planning with context gathering before execution
Superpowers — engineering discipline protocols (TDD enforcement, systematic debugging, two-stage review)

Meridian combines and extends these ideas into a single, cohesive system with a cleaner architecture, pluggable integrations, and comprehensive test coverage. If you're using any of those tools and they work for you — great, keep using them. Meridian is what I built when I wanted something that fit my workflow more precisely.

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

Apache License 2.0 — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 210 Commits
docs		docs
prompts		prompts
references		references
scripts		scripts
skills		skills
tasks		tasks
templates		templates
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Meridian

Why This Exists

Key Features

Deterministic Resume

Context-Efficient Subagents

Quality Gates

Pluggable Board Sync

Session Intelligence

Remote Agent Dispatch

Quick Start

Architecture

Data Model

State Machines

Commands (39)

Core Workflow

Quick Actions

Planning & Discussion

Quality & Review

Visibility & Metrics

Session Management

Execution Control

Integration

Typical Workflow

Quick Tasks (Skip Full Planning)

Capturing Ideas

Installation

Prerequisites

Install

Verify

CLI (scripts/cli.py)

Uninstall

Board Integration

Built-in Providers

Using the CLI Provider

Writing a Custom Provider

Quality Gates

Regression Gate

Requirements Coverage

Stub Detection

Node Repair

Two-Stage Review

Session Intelligence

Deterministic Resume

Structured Handoff

Debug Knowledge Base

Decision Traceability

Security

Project Structure

Schema

Stack

Documentation

Troubleshooting

Commands not showing in Claude Code

"Database is locked"

"Module not found" errors

State seems corrupted

Inspiration & Credits

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages