conductor-sdd
This server exposes conductor-sdd's deterministic Spec-Driven Development guardrails as MCP tools so AI coding agents can validate specs, lock AST/SHA-256 baselines, detect drift, and safely checkpoint/rollback workspace changes.
Validate specs (
conductor_validate_spec): Checkconductor.spec.yamlschema and invariants before agent execution, with optional custom root and spec path.Lock baselines (
conductor_lock_baseline): Compute SHA-256 file hashes and AST symbol signatures into.conductor/lock.json.Detect drift (
conductor_verify_drift): Run static AST drift detection (SDD-001..009) against spec invariants and the locked baseline, with astrictmode to promote warnings to blocking errors.Create checkpoints (
conductor_create_checkpoint): Snapshot the workspace atomically with SHA-256 verification and a human-readable label before risky edits.Roll back (
conductor_rollback): Verify stored hashes and restore the workspace to a clean checkpoint, optionally targeting a specificcheckpoint_idor previewing changes viadry_run.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@conductor-sdd check my edits for drift against the locked baseline and roll back if broken"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Zero-Dependency Spec-Driven Development (SDD) Harness, Static AST Drift Detector & MCP Guardrail for Autonomous AI Coding Agents.
Locks public signatures, enforces task scope, catches silently deleted test assertions, and rolls back broken agent mutations in milliseconds — with zero external dependencies and zero LLM token burn.
⚡ Why conductor-sdd?
AI coding agents (Claude Code, Cursor, Codex CLI, Aider, Cline) ship turn-1 prototypes fast — and silently decay into multi-turn context drift by turn 5:
Silent Public API & Signature Breakage: Unguarded edits drop required parameters, rename public methods, or leave half-written syntax errors behind.
Test Tampering ("Fake Green CI"): When a refactor breaks existing tests, agents frequently delete
assertorpytest.raisesstatements instead of fixing the underlying bug.Out-of-Scope File Mutations & Forbidden Dependencies: Without cryptographic scope boundaries, agents touch protected config/auth files or pull in banned/unpinned packages.
LLM-as-a-Judge Spec Checkers Burn Tokens & Hallucinate: Asking another LLM whether code still matches a markdown spec is slow, expensive, and non-deterministic.
conductor-sdd replaces probabilistic guesswork with pure Python static AST verification, SHA-256 baseline locking, and atomic workspace rollback.
Related MCP server: AI Knowledge Center MCP
🏆 Architectural Benchmark: Top 5 Global Incumbents vs conductor-sdd
We compared conductor-sdd against the 5 largest global open-source Spec-Driven Development and coding-agent frameworks representing over 367,000 GitHub stars:
Feature / Metric |
|
|
|
|
|
|
Static AST Drift Engine | ❌ Markdown templates | ❌ Markdown diffs | ❌ No | ⚠️ Repo map only | ❌ Runtime schemas | ✅ Pure AST |
Verification LLM Cost | ⚠️ Prompt-driven | ⚠️ Prompt-driven | ⚠️ Agent-driven | ⚠️ Agent-driven | ⚠️ Eval-driven | ✅ $0.00 (Zero LLM Tokens) |
Deleted Assertion Guard | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No | ✅ Deterministic |
Runtime Dependencies | CLI + Agent Templates | Node.js / npm | VS Code Extension | Heavy Python Stack | Pydantic + Providers | ✅ Zero (Pure Python Stdlib) |
Atomic SHA-256 Rollback | ❌ Git manual | ❌ Git manual | ⚠️ Checkpoints in IDE | ⚠️ Git auto-commit | ❌ No | ✅ Sub-5ms Local Snapshot |
Native MCP Guardrail | ❌ Slash commands | ❌ Slash commands | ⚠️ MCP Client | ❌ No | ⚠️ Tool wrappers | ✅ Built-in JSON-RPC 2.0 stdio |
🏗️ Architecture
Developer / Coding Agents (Claude Code / Cursor / Codex CLI / Antigravity)
│
├──► 1. conductor init ──► Declares scope & invariants (conductor.spec.yaml)
├──► 2. conductor lock ──► Freezes AST signatures & SHA-256 baseline (.conductor/lock.json)
├──► 3. conductor checkpoint ──► Captures immutable pre-edit restore point
│
▼ (Agent performs multi-turn code mutations)
│
┌─────────────────────────────────────────────────────────────────────┐
│ CONDUCTOR AST DRIFT ENGINE (SDD-001..009) │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Integrity Guards │ │ AST Signatures │ │ Quality & Docs │ │
│ │ • SDD-001 Syntax │─►│ • SDD-003 Symbols │─►│ • SDD-007 McCabe│ │
│ │ • SDD-002 Protect │ │ • SDD-005 Imports │ │ • SDD-008 Lines │ │
│ │ • SDD-004 Scope │ │ • SDD-006 Asserts │ │ • SDD-009 Docs │ │
│ └───────────────────┘ └───────────────────┘ └─────────────────┘ │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Atomic Checkpoint │ │ Serve & MCP │ │ Tools & Matrix │ │
│ │ • SHA-256 Lock │ │ • JSON-RPC 2.0 │ │ • SDD Doctor │ │
│ │ • Sub-5ms Restore │ │ • Telemetry P99 │ │ • 6-Mode Bench │ │
│ └───────────────────┘ └───────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │
├── PASS (0.00% Drift) ──► Safe to commit / promote / pass Git hook
└── DRIFT DETECTED ──► Exit code 2 + `conductor rollback`See docs/ARCHITECTURE.md for the full layer specification.
🚀 60-Second Quickstart
1. Install
git clone https://github.com/Benni-OS/conductor-sdd.git
cd conductor-sdd
pip install -e .2. Lock Baseline & Verify After Every Agent Turn
# Scaffold `conductor.spec.yaml` and `AGENTS.md` inside any Python repository
conductor init --project my-service --allowed src tests --with-agent-rules
# Cryptographically lock all AST symbol signatures and SHA-256 file hashes
conductor lock
# Save an atomic pre-edit rollback checkpoint
conductor checkpoint --label "pre-agent-sprint"
# Verify zero architectural or test-assertion drift
conductor verify --strictWhen an agent silently mutates a locked signature or deletes assertions:
Conductor SDD Verification: DRIFT DETECTED (37.50%)
Files scanned: 8 | Baseline locked: 8 | Elapsed: 4.12ms
[CRITICAL] SDD-003 (src/auth.py::verify_token): Protected symbol signature mutated from `(token: str, secret: str) -> bool` to `(token: str) -> bool`.
-> Fix: Preserve the locked public signature to avoid downstream breakage.Restore cleanly in one command:
conductor rollbackKey CLI Commands
conductor init --with-agent-rules # Generate conductor.spec.yaml + AGENTS.md rules
conductor lock # Freeze AST signatures & SHA-256 baseline lock
conductor verify --strict --json # Audit AST & scope drift (exit code 2 on violation)
conductor checkpoint --label sprint1 # Create atomic SHA-256 pre-edit restore point
conductor rollback # Restore workspace cleanly from verified checkpoint
conductor bench --json # Run 6-scenario reproducible drift-recall benchmark
conductor doctor # Audit repository readiness for SDD governance
conductor install-hook # Install Git pre-commit anti-drift gate
conductor mcp # Launch native JSON-RPC 2.0 MCP stdio server🛡️ Deterministic Anti-Drift Rules (SDD-001 .. SDD-009)
Rule ID | Severity | What It Catches | Zero LLM Tokens |
|
| Broken Python syntax left behind mid-edit | ✔ |
|
| Unauthorized edits or deletion of | ✔ |
|
| Deletion, rename, or signature mutation of | ✔ |
|
| Out-of-scope edits or file creation outside | ✔ |
|
| Injection of banned libraries in | ✔ |
|
| Silent deletion of | ✔ |
|
| McCabe cyclomatic complexity exceeding | ✔ |
|
| Oversized modules exceeding | ✔ |
|
| Missing docstrings on public classes/functions (when enabled) | ✔ |
📊 Reproducible Drift Benchmark
Verify detection recall and scan latency across 6 real-world AI coding failure modes locally:
conductor benchMeasured output:
Conductor SDD — Reproducible Agent-Drift Benchmark
========================================================
Catch Recall : 100.0% (6/6 agent failure modes caught)
Avg Latency : ~12.24 ms per full 6-scenario verification pass
[CAUGHT] SCEN-01 | Expected SDD-003 | Got ['SDD-003', 'SDD-009'] — Silent public signature break
[CAUGHT] SCEN-02 | Expected SDD-006 | Got ['SDD-006'] — Silent deletion of unit test assertions
[CAUGHT] SCEN-03 | Expected SDD-005 | Got ['SDD-005'] — Injection of forbidden dependency
[CAUGHT] SCEN-04 | Expected SDD-002 | Got ['SDD-002'] — Unauthorized edit to protected file
[CAUGHT] SCEN-05 | Expected SDD-004 | Got ['SDD-004'] — Out-of-scope file creation
[CAUGHT] SCEN-06 | Expected SDD-001 | Got ['SDD-001'] — Broken syntax introduced mid-edit🔌 Native MCP Integration (Claude Code / Cursor / Antigravity)
Expose conductor-sdd directly as a native Model Context Protocol (MCP) server over stdio so coding agents self-verify before finishing any turn:
{
"mcpServers": {
"conductor-sdd": {
"command": "conductor-mcp",
"args": []
}
}
}Exposed MCP tools:
conductor_validate_spec— Validateconductor.spec.yamlschema invariantsconductor_lock_baseline— Generate/refresh.conductor/lock.jsonAST + SHA-256 lockconductor_verify_drift— RunSDD-001..009deterministic drift verificationconductor_create_checkpoint— Snapshot pre-edit state atomicallyconductor_rollback— Revert drifted changes cleanly
📁 Project Structure
conductor-sdd/
├── .github/workflows/ci.yml # Python 3.10 / 3.11 / 3.12 lint, pytest & bench gate
├── assets/
│ └── demo.gif # Branded terminal animation
├── conductor_sdd/
│ ├── __init__.py # Backwards-compatible public library exports
│ ├── cli.py # CLI commands (init, lock, verify, checkpoint, rollback, bench, doctor, mcp)
│ ├── core/
│ │ ├── __init__.py # Core package exports
│ │ ├── ast_analyzer.py # Zero-dependency AST symbol, complexity & assertion extractor
│ │ ├── checkpoint.py # Atomic SHA-256 snapshot & rollback engine
│ │ ├── drift_engine.py # SDD-001..009 deterministic rule evaluator & drift scorer
│ │ └── spec.py # Zero-dependency YAML subset parser & spec validator
│ ├── serve/
│ │ ├── __init__.py # Serve package exports
│ │ ├── mcp_server.py # Native JSON-RPC 2.0 MCP stdio server
│ │ ├── telemetry.py # AST verify P50/P90/P99 latency & SDD rule hit telemetry
│ │ └── health_monitor.py # Spec contract, lock manifest & AST self-test monitor
│ └── tools/
│ ├── __init__.py # Tools package exports
│ ├── doctor.py # Repository SDD readiness diagnostics & Git hook installer
│ ├── benchmarks.py # 6-scenario reproducible agent-drift benchmark suite
│ └── bench_matrix.py # Multi-scale AST lock & verification benchmark matrix
├── docs/
│ └── ARCHITECTURE.md # Layer-by-layer architectural specification
├── examples/
│ ├── mcp_client_config.json # Ready-to-use MCP client config
│ ├── quickstart_guardrail.py # Programmatic Python guardrail example
│ └── checkpoint_rollback_demo.py # Atomic pre-edit checkpoint & rollback demo
├── scripts/
│ ├── benchmark_drift_matrix.py # 5–100 module AST lock & verification matrix runner
│ └── gate_sdd_strict.py # Strict SDD readiness & 100% recall release gate
├── tests/
│ ├── test_ast_analyzer.py # AST symbol, complexity & assertion tests
│ ├── test_checkpoint_rollback.py # Atomic snapshot & rollback tests
│ ├── test_cli_and_bench.py # CLI & 6-scenario drift benchmark tests
│ ├── test_drift_engine.py # SDD-001..009 rule evaluation tests
│ ├── test_mcp_server.py # JSON-RPC 2.0 MCP server tests
│ ├── test_serve_and_tools.py # Telemetry, health monitor, doctor & bench matrix tests
│ └── test_spec.py # Spec parser & schema validation tests
├── conductor.spec.yaml # Dogfooded self-verification spec contract
└── pyproject.toml # Zero-dependency package & entrypoints🌐 The Benni OS Open-Source Ecosystem
conductor-sdd is part of the coordinated Benni Master OS v9.4 open-source infrastructure suite:
Repository | Focus & Architecture | Stars |
Zero-Dependency Spec-Driven Development, Static AST Drift Detector & MCP Guardrail | ||
High-Throughput Sovereign Local Inference for 8GB–16GB Consumer GPUs | ||
Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness | ||
Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents | ||
Autonomous Multi-Source Deep Research & Evidence Synthesis Engine | ||
Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler | ||
Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents | ||
Sub-Millisecond Context Compression & Semantic Deduplication Engine | ||
Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface | ||
Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction | ||
Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine | ||
Cryptographic State Verification & Invariant Proof Engine for Agents | ||
Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine | ||
Human-in-the-Loop Approval & Policy Enforcement Gateway | ||
Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling | ||
Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub | ||
Autonomous GitHub Community Triaging & PR Feedback Agent |
🏛️ Commercial & Sovereign Architecture
Need autonomous multi-agent swarm orchestration, Spec-Driven Governance at enterprise scale, or deep technical blueprints?
Official Website: https://benni-os.net
Deep-Dive Architecture Article: Spec-Driven Development (SDD): Eliminating AI Code Drift and Multi-Turn Hallucinations with Formal Consensus
Operator Mode Playbook: https://benni-os.net/blog/academy.html
GitHub Organization: https://github.com/Benni-OS
Maintainer: Benni Alencar
📄 License & Provenance
License: MIT License
Author: Benni Alencar (
bennialencar@benni-os.net)Architecture: Benni Master OS v9.4 Tier-0 Governance Standard
conductor-sdd — Deterministic Spec-Driven Development & AST Anti-Drift Harness • benni-os.net • MIT License
Available Tools
5 toolsconductor_create_checkpointA
Create an atomic SHA-256 verified workspace snapshot before risky edits.
Inputs: root, label.
conductor_lock_baselineC
Compute SHA-256 and AST symbol baseline hashes into .conductor/lock.json.
Inputs: root.
conductor_rollbackC
Verify stored SHA-256 hashes and roll back workspace to a clean checkpoint.
Inputs: root, dry_run, checkpoint_id.
conductor_validate_specB
Validate conductor.spec.yaml schema and invariants before AI coding execution.
Inputs: root, spec_path.
conductor_verify_driftC
Run static AST drift detection against spec invariants and baseline lock.
Inputs: root, strict.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct phase of the spec-driven development lifecycle: validate, lock, drift verification, checkpoint creation, and rollback. Actions are semantically different (schema validation vs. hashing vs. comparison vs. snapshotting vs. restoration), so misselection is unlikely.
All tool names share the conductor_ prefix followed by a predictable verb_noun pattern (validate_spec, lock_baseline, verify_drift, create_checkpoint, rollback). The lone nounless 'rollback' is a minor deviation but remains clear and consistent with the set.
Five tools is a tight, well-scoped set that maps directly to the workflow: validate → lock → verify → checkpoint → rollback. No redundant or filler tools; each earns its place.
The surface covers the core safety loop for spec-driven coding, including validation, baseline locking, drift detection, and rollback. Minor gaps exist, such as listing/inspecting existing checkpoints or modifying the spec itself, which agents would have to work around.
Maintenance
Related MCP Connectors
MCP server (stdio): lint OpenAPI specs with Spectral via the AgentForge API
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.1MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server that provides project context, verification gates, and structured tools for coding agents to discover knowledge, run diagnostics, and execute allowlisted commands within a repository.40 npmMIT
- AlicenseAqualityBmaintenanceLocal MCP server for AI agents and vibe coding safety: deterministic risk checks (payments, auth, database, secrets, infrastructure), sessions, checkpoints, policy inspection, and fix prompts. Runs over stdio against a local git repository; no language model judges risk.8Apache 2.0
- FlicenseNot gradedqualityNot gradedmaintenanceEnables agents and MCP-compliant clients to run multi-language code in a deterministic, zero-dependency sandbox where AST security analysis blocks dangerous syscalls and isolated execution telemetry is captured. It exposes this through JSON-RPC 2.0 stdio, letting frameworks like LangGraph, CrewAI, Cursor, and Claude Desktop validate and execute agent-generated code safely.-