Spec Editor

Active Memory Layer for Requirements & Code — powered by AI agents

▶ Watch the demo (GIF)

Spec Editor is an active memory layer for AI-driven development.
Unlike passive docs, this memory is alive — AI agents continuously debate,
cross-reference, and evolve the project knowledge.

# One-liner install (macOS / Linux):
curl -sSL https://raw.githubusercontent.com/spec-editor/spec-editor/main/install.sh | bash

# Or via pip (requires Python 3.11+):
pip install spec-editor && spec-editor init --with-example && spec-editor run

Every AI coding agent suffers from amnesia between sessions. Spec Editor gives them — and your team — a shared, persistent memory that grows smarter with every run. Not a wiki. Not a task tracker. An active, self-maintaining knowledge base that debates its own completeness.

Why Now?

Cursor, Copilot, and Claude Code have made AI-assisted coding mainstream. But they all share one critical flaw: no memory between sessions. Every conversation starts from zero.

Spec Editor is the missing layer — a team memory for the AI era. Solo developers get a structured analysis process they'd otherwise skip. Teams get a single source of truth that stays in sync with code via @implements traceability.

Built with 2 years of LLM engineering experience and 20+ years in software development.

What is Spec Editor?

Spec Editor is an active memory system for your project. AI agents don't just
write to it — they debate, cross-validate, and continuously refine the knowledge.
Every specification element is a version-controlled artifact that any AI coding
agent can query via MCP.

         ┌─────────────────────────────────────┐
         │           ACTIVE MEMORY              │
         │                                      │
         │   ┌──────┐  ┌──────┐  ┌─────────┐   │
         │   │Agent 1│  │Agent 2│  │Orchestr.│  │  ← debate & refine
         │   └──┬───┘  └───┬───┘  └────┬────┘   │
         │      │          │           │        │
         │      ▼          ▼           ▼        │
         │   ┌──────────────────────────────┐   │
         │   │  Structured Knowledge Base   │   │  ← YAML + Markdown + Git
         │   │  MOD-001  SCN-007  ENT-004   │   │
         │   └──────────────────────────────┘   │
         │                                      │
         │   MCP → Cursor, Claude, Zed, ...     │  ← any agent can query
         └─────────────────────────────────────┘

Built around a pluggable methodology system — define any set of aspects
(for ex. modules, scenarios, UI, entities, NFRs), their relationships, and the
agent skills that populate them. Create your own or use the built-in waterfall.

It is:

• An active memory layer — AI agents debate, maintain, and evolve project knowledge
• A methodology engine — define your own aspects, relationships, and agent skills in YAML
• An architectural code generator — produces structured code from patterns (hexagonal, DDD, MVC)
• An MCP server — 40+ tools for external AI agents to read, search, and drive your specification
• A VS Code extension + web UI — tree view, diagrams, trace map, and inline validation, no terminal required

It is NOT:

• A replacement for human decision-making — agents debate, humans decide

[!NOTE]
Works with any OpenAI-compatible API. Default: DeepSeek Reasoner (~$0.55/M tokens).
Free & Open Source — Apache 2.0. No per-seat pricing, no vendor lock-in, your data stays in your Git repo.

Who Is This For?

• Business analysts — turn stakeholder interviews and vague docs into structured specs
• System analysts — decompose requirements into modules, data models, and API contracts
• Engineering teams — need traceability across the whole requirements model
• Technical PMs — tired of Word docs and Jira tickets drifting apart over time
• AI-assisted developers — using Cursor, Claude Code, or Zed — give your coding agent full spec context
• AI agent developers — give your agents a shared, persistent memory of project requirements, decisions, and code contracts via MCP
• Vibe-coders — gives you a secret sauce of technical architecture and professional-grade requirements

Before & After

Input — a single paragraph in source/readme.md:

"We need a user authentication system with login, registration, and password reset."

Output — structured specification in aspects/:

aspects/
├── modules/MOD-003.md        Authentication Module
├── user_scenarios/SCN-007.md  User Login (happy path, error states, rate limiting)
├── user_scenarios/SCN-008.md  Password Reset (email flow, token expiry)
├── user_interface/UI-005.md   Login Form (widgets, validation rules)
├── data_entities/ENT-004.md   User entity (fields, constraints, relationships)
└── non_functional/NFR-002.md  Auth latency < 200ms, bcrypt hashing, OWASP compliance

Each element is a version-controlled Markdown file with YAML frontmatter —
diffable, mergeable, and connected via bidirectional traceability links.

Why Not Just Prompt an LLM Directly?

A raw LLM prompt produces superficial, flat requirements. Spec Editor's
multi-agent debate and methodology-driven structure produce deeply
connected specifications — much better than what any single LLM prompt
can achieve.

Quick Start

pip install spec-editor

# 1. Instant preview (no API key)
spec-editor demo              # opens pre-generated spec in browser

# 2. Create project and run agents
spec-editor init my-project --with-example   # creates project with sample requirements
cd my-project
spec-editor run                               # needs DEEPSEEK_API_KEY in .env

# 3. Connect to your AI coding agent
spec-editor mcp &             # start MCP server in background
# Add the MCP config to your agent (see below)

# 4. Export to shareable format
spec-editor export -f html    # styled HTML report
spec-editor export -f srs     # IEEE 830 Markdown
spec-editor validate          # check methodology compliance

After spec-editor run completes, you'll have:

• aspects/ — structured specification in Markdown + YAML frontmatter
• source/session_summary.md — what the agents did and why

Connect to AI Coding Assistants (MCP)

Spec Editor runs an MCP server for any MCP-compatible agent
(Zed, Cursor, Claude Code, Windsurf, etc.).

spec-editor mcp &   # start in background

Add to your agent's MCP config (.mcp.json):

{
  "mcpServers": {
    "spec-editor": {
      "command": "spec-editor",
      "args": ["mcp", "-p", "/absolute/path/to/project"]
    }
  }
}

What Your Agent Gets

Full tool list: readme_mcp.md. Plugins can add further
tools on top of these.

Add @implements("REQ-ID") decorators to your code, then run
spec-editor context --file <path> to pull the linked requirements into
context — a fast way to trace a bug back to the spec element it was built
to satisfy.

Full API reference: readme_mcp.md

VS Code Extension

Install from the .vsix file included in the repository:

code --install-extension packages/vscode-extension/spec-editor-vscode-1.4.0.vsix

What you get:

• Tree view — browse aspects and all spec elements
• Validation panel — see errors and warnings inline as you work
• Mermaid diagrams — visualize relationships between elements

The extension automatically connects to the MCP server started by spec-editor mcp.

Web UI (Experimental)

Launch a browser-based interface to explore your specification visually:

spec-editor mcp --transport http --port 8088   # terminal 1 — MCP server (or `make dev-http`)
make web                                       # terminal 2 — static export on the fixed port
# Open http://127.0.0.1:3080

The local web version always lives on port 3080 (WEB_PORT in the
Makefile) and talks to the MCP server on 8088. Do not serve the static export
on port 3000: the frontend treats 3000 as the nginx-proxied Docker deployment
and routes MCP calls through /api/mcp instead of 127.0.0.1:8088.

Or with Docker (configured during spec-editor init):

docker compose up -d

Ideal for team reviews, stakeholder walkthroughs, and non-technical users.
A web-cloud version is coming!

What's in it: a left sidebar with a Reqs tab — the element tree,
following whichever aspect chip you clicked, with a filter box and an
"Only this aspect" toggle — and an Agents tab. A grouped view
switcher covers the Spec views (Diagram, Trace map) and the
Agents views (Agents, Runs, Prompts), each reachable via a
?view=<mode> link you can bookmark or share. The Diagram view pans,
zooms (toolbar or scroll wheel), and drills into an element's own
sub-diagram on double click. The Agents view's inspector is tabbed:
Chat with an agent directly from the browser, Tasks/Log to
see what it's working on and what it actually did, Questions to
answer what it's asked you. And you can create, edit, and delete
elements — and edit their relationships — from the UI itself, no editor
required.

A commercial plugin can add further tabs and view groups on top of this —
see Pro plugin below.

How It Works

┌──────────────────────────────────────────────────────────────┐
│                     SPEC EDITOR                              │
│                                                              │
│  SOURCE DOCUMENTS                                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                      │
│  │ PDF/TXT  │ │ Telegram │ │  Voice   │  ...                 │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘                      │
│       │             │            │                            │
│       ▼             ▼            ▼                            │
│  ┌─────────────────────────────────────┐                     │
│  │        Ingestion Pipeline           │                     │
│  │  PDF → text, spam filter, SRC gen   │                     │
│  └─────────────────┬───────────────────┘                     │
│                    ▼                                          │
│  ┌─────────────────────────────────────┐                     │
│  │        AGENT DIALOGUE               │                     │
│  │  ┌──────────┐  ┌──────────┐         │                     │
│  │  │ Agent 1  │  │ Agent 2  │  +Orch  │                     │
│  │  │ modules  │  │scenarios │         │                     │
│  │  └────┬─────┘  └────┬─────┘         │                     │
│  │       │   debate    │               │                     │
│  │       ▼             ▼               │                     │
│  │  ┌─────────────────────────────┐    │                     │
│  │  │  Skill-based helpers        │    │                     │
│  │  │  scenario_decomposer,       │    │                     │
│  │  │  ui_navigator, metrics_linker   │                     │
│  │  └─────────────────────────────┘    │                     │
│  └─────────────────┬───────────────────┘                     │
│                    ▼                                          │
│  ┌─────────────────────────────────────┐                     │
│  │         SPECIFICATION               │                     │
│  │  aspects/modules/    MOD-001.md     │                     │
│  │  aspects/scenarios/  SCN-001.md     │                     │
│  │  aspects/entities/   ENT-001.md     │                     │
│  └──────────────────┬──────────────────┘                     │
│                     ▼                                        │
│  ┌──────────────────────────────────────┐                    │
│  │           MCP SERVER                  │                    │
│  │  40+ tools — read_element,           │                    │
│  │  search_elements, run_validate,      │                    │
│  │  changeset_get, ...                   │                    │
│  └──────────────────┬───────────────────┘                    │
│                     ▼                                        │
│  ┌──────────────────────────────────────┐                    │
│  │     AI CODING AGENTS                  │                    │
│  │  Claude Code · Cursor · Zed · ...    │                    │
│  │  Code with full spec context          │                    │
│  └──────────────────┬───────────────────┘                    │
│                     ▼                                        │
│  ┌──────────────────────────────────────┐                    │
│  │    VS CODE EXTENSION + WEB UI        │                    │
│  │  Tree view · Diagrams · Validation   │                    │
│  │  Browser UI for non-technical users  │                    │
│  └──────────────────────────────────────┘                    │
└──────────────────────────────────────────────────────────────┘

Key Features

Supported Methodologies

Specifications follow a methodology — a YAML-defined structure of aspects,
element types, cross-aspect relationships, and agent skills. Create your own
or use the built-in ones:

Create your own methodology in YAML — define aspects, element types,
cross-aspect relationships, and agent skills. See data/methodology.yaml
for the waterfall example.

Reverse Engineering

Already have code but no spec? Run agents in reengineer mode to extract
requirements from an existing codebase:

spec-editor run --reengineer --code-dir ./my-codebase

The code-scanning tools this mode uses come from a plugin.

Supported languages: Python, TypeScript, JavaScript, Go, Java, Kotlin, Rust.

CLI Commands

spec-editor demo                         # Instant preview (no API key)
spec-editor init ./my-project            # Create project
spec-editor run -p ./my-project          # Run agent dialogue
spec-editor view -p ./my-project         # Interactive Mermaid graph
spec-editor validate -p ./my-project     # Validate specification
spec-editor status -p ./my-project       # Show spec status
spec-editor export -p ./my-project       # Export to SRS/TRLC/OpenAPI/Jira/HTML
spec-editor mcp                          # Start MCP server (40+ tools)

spec-editor migrate -p ./my-project      # Upgrade an existing project to the latest conventions
spec-editor sync -p ./my-project         # Bidirectional sync with tracker channels
spec-editor diff -p ./my-project --run RUN_ID  # Show what changed (--run/--change/--element/--since)

A commercial plugin extends the core beyond the requirements model; the
extension points are documented in docs/PLUGINS.md.

Diff, versions, and roles

Every element write is content-addressed, and the same ChangeSet /
DiffPanel shows up wherever "what changed" matters — a run's own result,
an element's full version history, or a spec-wide window of activity.

• Diff everywhere — spec-editor diff --run/--change/--element/--since,
  read-only MCP changeset_get/element_at/element_versions, and the
  frontend DiffPanel wired into Runs and Trace map; in VS Code, "Show
  changes"/"Show History" open a native vscode.diff.
• Roles from the methodology — methodology.yaml can declare roles:
  (name/skills/aspects/llm_profile); the analysis-agent registry becomes
  the union of methodology roles and agents.yaml: roles: overrides.
• e2e-kit and scenario videos — packages/e2e records Playwright
  scenarios as mp4s (see packages/e2e/SCENARIOS.md) alongside the checks
  that prove the same pass.

Run on your Claude Code subscription. The claude-code LLM provider
shells out to your locally installed claude CLI, authenticated by
claude login, no API key needed (see Configuration below).

Configuration

Edit agents.yaml to choose your provider:

agents:
  agent_1:
    provider: deepseek     # or openai, anthropic
    model: deepseek/deepseek-reasoner
    temperature: 0.7
  agent_2:
    provider: deepseek
    model: deepseek/deepseek-reasoner
    temperature: 0.7
  orchestrator:
    provider: deepseek
    model: deepseek/deepseek-reasoner

More configuration options are available through the VS Code extension:
Ctrl+Shift+P → type Spec Editor to access settings, project switching,
and MCP controls.

Run on your Claude Code subscription. No API key? Set
provider: claude-code instead — it runs your locally installed claude
CLI headless, authenticated by claude login:

agents:
  agent_1:
    provider: claude-code
    model: opus       # or: sonnet, fable, haiku — see `claude --help`

spec-editor init skips the API-key prompt for this provider. Details and
limits: docs/FAQ.md, "Can I use my Claude Code subscription
instead of API keys?".

Contributing

Prompts are the engine of Spec Editor. Better prompts = better specifications.

• Language packs — translations for EN, RU, ES, FR, DE. Missing your language? Add prompts/xx.yaml and open a PR.
• LLM-specific tuning — DeepSeek, GPT-4, Claude each respond differently. Share your tuned prompts.
• Few-shot examples — help us add domain-specific examples.

Got ideas? Open an issue or submit a PR — we review everything.

Pro Plugin

A commercial plugin extends the core beyond the requirements model —
through the same extension points described in
docs/PLUGINS.md. The OSS core never imports plugin
code directly; it works standalone as a requirements and methodology tool
with or without it.

Documentation

• Quickstart — 5-minute setup
• Upgrading from 0.2.x to 1.4 — migrating an existing 0.2.x project
• Architecture — pipeline, components, CLI reference
• Plugins — the plugin extension points (e.g. the Pro plugin)
• MCP API Reference — MCP server tools
• Extension Integration — VS Code + MCP setup
• e2e Scenarios — Playwright scenario suite + demo videos
• Contributing Prompts — how to improve agent quality
• CONTRIBUTING.md — code contributions
• CHANGELOG.md — release history

License

Apache 2.0 — see LICENSE.