convez.ai
MCP ServerAutomaçãoIntermediário
spec-editor

Spec Editor

spec-editor/spec-editor

Engenharia de requisitos com debate multi-agente e geração de specs

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que transforma documentos de requisitos em especificações estruturadas através de debate entre múltiplos agentes IA. Gera código skeleton em várias linguagens (SQLAlchemy, FastAPI, React, pytest) mantendo alinhamento entre requisitos e implementação de forma versionada.

Instalação

$npx convez-ai spec-editor/spec-editor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
1
Saúde
62%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Transformar requisitos soltos em especificações estruturadas via debate de agentes
  • Sincronizar agentes de IA coding (Claude, Cursor) com documentação de requisitos
  • Gerar esqueletos de código e arquitetura em 7 linguagens a partir de specs

Veredito

Ferramenta sólida para teams que precisam converter requisitos soltos em specs profundas via IA — o diferencial está no debate multi-agente estruturado vs. LLM bruto único. MCP integrado garante que código gerado fica alinhado com requisitos versionados em git.

README

A tradução para o português deste README ainda está na fila.


What is Spec Editor?

Spec Editor turns messy requirements documents into structured specifications using multiple AI agents in a structured dialogue. Then it connects to your AI coding agent (Claude Code, Cursor, Zed) via MCP so your generated code stays aligned with your requirements.

It is:

  • A CLI tool that generates specifications via multi-agent debate
  • An MCP server so external AI agents can read your specification
  • A code generator that creates skeletons from spec elements (SQLAlchemy, FastAPI, React, pytest)

It is NOT:

  • A generic code generator (we do templates, not AI code gen)
  • A task tracker (use Jira/Linear for that — we export to them)
  • A replacement for developers (agents debate, humans decide)

[!NOTE] Spec Editor works with any OpenAI-compatible API (DeepSeek, OpenAI, Anthropic). Default: DeepSeek ($0.14/M tokens).


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.

What happens with raw LLMWhat spec-editor does
Single perspectiveMulti-agent debate with structured rounds
No adversarial reviewAgents challenge each other — edge cases, contradictions caught
Freeform outputMethodology-driven: modules, scenarios, UI, data, NFR, metrics
Ephemeral sessionVersion-controlled artifacts in git (Markdown + YAML)

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   # creates project structure
cd my-project
# Put your requirements in source/ — or use --with-example
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

ToolDescription
get_context_for_fileSpec context for a code file via @implements
search_elementsFull-text search across requirements
read_elementRead any specification element by ID
list_all_elementsBrowse entire specification

Add @implements("REQ-ID") decorators to your code — the agent automatically pulls linked requirements into its context.

Full API reference: readme_mcp.md


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                  │                    │
│  │  19 tools — read_element,            │                    │
│  │  search_elements, list_aspect, ...   │                    │
│  └──────────────────┬───────────────────┘                    │
│                     ▼                                        │
│  ┌──────────────────────────────────────┐                    │
│  │     AI CODING AGENTS                  │                    │
│  │  Claude Code · Cursor · Zed · ...    │                    │
│  │  Code with full spec context          │                    │
│  └──────────────────────────────────────┘                    │
└──────────────────────────────────────────────────────────────┘

Key Features

FeatureDescription
Multi-agent dialogue2 agents + orchestrator debate requirements in structured rounds
Skill-based helpersAgents spawn specialised helpers: scenario decomposer, UI navigator, metrics linker
Methodology-drivenWaterfall decomposes into 8 aspects: modules, scenarios, UI, data, NFR, metrics, implementation, sources
MCP server19 tools — connect to Claude Code, Cursor, Zed for context-aware code generation
Export formatsSRS (IEEE 830), TRLC (BMW), OpenAPI 3.0, Jira CSV, styled HTML
Git-nativeEverything is Markdown + YAML in git — version, diff, merge, blame

Supported Methodologies

Specifications follow a methodology — a YAML-defined structure of aspects, element types, and relationships.

MethodologyWhat it generatesStatus
waterfallFull spec: modules, scenarios, UI, data, non-functional, implementation, metrics, sources✅ Free (OSS)
agileSprint backlog: epics → user stories → acceptance criteria + Jira CSV✅ Paid
scrumAgile + sprints (goal, capacity, focus factor, velocity, DoD)✅ Paid
kanbanAgile + workflow stages (WIP limits, cycle time, throughput)✅ Paid
api-firstOpenAPI 3.0 contract (service → endpoint → schema + auth)✅ Paid

waterfall is free and bundled with the OSS release. Agile, scrum, kanban, and api-first are Methodology Packs (coming soon).


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 (19 tools)

Export Formats

spec-editor export -p .                            # SRS document (default)
spec-editor export -p . -f html -o spec.html       # Styled HTML with relationships
spec-editor export -p . -f trlc -o spec.trlc       # TRLC (BMW-compatible)
spec-editor export -p . -f openapi -o api.yaml     # OpenAPI 3.0
spec-editor export -p . -f jira -o backlog.csv     # Jira CSV import
FormatCLI flagOutputUse case
SRS (IEEE 830)-f srs (default)MarkdownStakeholder-ready specification
HTML-f htmlspec.htmlStyled report with relationship traces
TRLC (BMW)-f trlc.trlc fileRequirements as code
OpenAPI 3.0-f openapiopenapi.yamlAPI contracts from api-first
Jira CSV-f jira.csv fileSprint backlog for Jira import
Markdown + YAMLNative (git)aspects/*.mdGit-native — version, diff, merge

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

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.


Documentation


License

Apache 2.0 — see LICENSE.

The core engine (spec-editor) is free and open source. Methodology Packs are source-available, purchased separately.

Ver o original no GitHub

Bom para