Daniel Kliewer
← Back to writing
06-12-20269 min read
#SovereignSpec#spec-driven development#SDD#Spec Kit#local-first#local AI#offline development#specgen#synth01#objective05#GBNF#grammar enforcement#knowledge graph#RAG#contradiction detection#narrative drift#LLM#llama-cpp#deterministic code generation#sovereign AI

Project Proposal: SovereignSpec — Local-First Spec-Driven Development

image

Project initiated on Github

Project Proposal: SovereignSpec — Local-First Spec-Driven Development

The spec is alive. The code obeys. Nothing leaves your machine.

1. Executive Summary

GitHub's Spec Kit (released September 2025, now at v0.5.0 as of mid-2026) has catalyzed a shift in how software gets built: Spec-Driven Development (SDD) — where specifications are the single source of truth, and code serves the spec, not the other way around. Spec Kit has 28K+ GitHub stars, supports Claude Code, Copilot, Cursor, Gemini CLI, and more, and provides a structured workflow: /constitution → /specify → /clarify → /plan → /tasks → /analyze → /implement.

But Spec Kit has a fatal flaw for sovereign builders: it requires cloud AI agents. Every spec evaluation, clarification, and implementation step routes through an external API. For a project stack built on local-first principles — specgen, synth01, objective05 — this is unacceptable.

SovereignSpec is a local-first, fully offline implementation of SDD that treats specs as living, evolvable artifacts — not static markdown files that drift from reality. It combines Spec Kit's structured workflow with your existing architectural patterns: deterministic agentic pipelines, RAG, GBNF grammar enforcement, and GraphRAG-based knowledge management.

2. The Current Landscape

2.1 Spec-Driven Development (SDD)

SDD flips traditional development: instead of code-first with specs as afterthought, specs become executable. The core equation:

Complete Specs + AI Context = Reliable Code

The context hierarchy:

  1. Global rules (coding standards, patterns)
  2. Project context (architecture, tech stack)
  3. Feature specs (PRD, acceptance criteria)
  4. Implementation specs (API, schema, components)
  5. Task context (specific file, specific function)

SDD ensures layers 1–4 exist before asking for layer 5. Without specs, AI tools invent. With specs, they implement.

2.2 GitHub Spec Kit

The dominant open-source SDD toolkit. Key characteristics:

  • Agent-agnostic: Works with Claude Code, Copilot, Cursor, Gemini CLI, Windsurf, TabNine CLI, Kimi Code CLI
  • Structured workflow: Seven slash commands enforce a pipeline — constitution, specify, clarify, plan, tasks, analyze, implement
  • Living specs: Specs are version-controlled markdown that evolve alongside code, not static documents
  • Extensibility platform: v0.5.0 introduced presets, extensions, and lifecycle hooks
  • Claude Code integration: Native skill since v0.4.5

2.3 What Spec Kit Gets Wrong

Cloud dependency. Every step of the Spec Kit workflow requires a cloud AI agent. The /clarify command calls an LLM API. The /plan command calls an LLM API. The /implement command calls an LLM API. There is no offline mode. There is no local model integration. For anyone who believes a weak local model controlled by you is spiritually superior to a powerful cloud model, this is a design failure.

No RAG integration. Spec Kit's specs are flat markdown files. They don't reference knowledge graphs, they don't pull context from vector stores, and they don't do retrieval-augmented reasoning during spec evaluation. For complex systems — like a sovereign intelligence OS — specs need to be grounded in actual knowledge, not just text.

No grammar enforcement. Spec Kit generates code from specs but doesn't enforce deterministic output formats. No GBNF. No typed contradiction detection. No narrative drift tracking.

No spec evolution tracking. Specs evolve in Spec Kit, but there's no structured tracking of how they evolved, why they changed, or whether changes introduce contradictions. No spec diffing with semantic analysis. No spec dependency graph.

3. The Gap: What Doesn't Exist

There is no local-first SDD tool that:

  • Runs entirely offline with local LLM inference
  • Treats specs as evolvable knowledge graph nodes, not flat markdown
  • Enforces deterministic output via GBNF grammar
  • Tracks spec drift and contradictions across spec versions
  • Integrates with existing local-first toolchains (like specgen)
  • Provides a CLI workflow analogous to Spec Kit's slash commands, but fully sovereign

This gap is the project.

4. Project Concept: SovereignSpec

4.1 One-Liner

A local-first, offline spec-driven development engine that treats specifications as living, graph-grounded artifacts and enforces deterministic code generation through structured pipelines — no cloud API calls required.

4.2 Core Design Principles

  • Spec is the single source of truth — code serves the spec, not the other way around
  • Nothing leaves the machine — all inference, evaluation, and generation happens locally
  • Specs evolve — tracked through a knowledge graph with semantic diffing and contradiction detection
  • Deterministic output — GBNF grammar enforcement ensures generated code is parseable and consistent
  • Agent-agnostic — works with any local LLM (Llama, Mistral, Qwen, etc.) via llama-cpp or similar

4.3 High-Level Architecture

┌─────────────────────────────────────────────────┐
│                   SovereignSpec                  │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌─────────────┐    ┌──────────────────────┐    │
│  │  Spec CLI    │───▶│  Spec Engine         │    │
│  │  (commands)  │    │  (pipeline orchestrator)│  │
│  └─────────────┘    └──────────┬───────────┘    │
│                                │                │
│                   ┌────────────┼────────────┐   │
│                   ▼            ▼            ▼   │
│            ┌──────────┐ ┌──────────┐ ┌────────┐│
│            │ Spec RAG │ │ Spec KG  │ │ GBNF   ││
│            │ (retrieval│ │ (graph-  │ │ Grammar││
│            │  + context│ │ grounded │ │ enforce││
│            │  injection│ │ tracking)│ │ ment   ││
│            └──────────┘ └──────────┘ └────────┘│
│                                                 │
│  ┌─────────────┐    ┌──────────────────────┐    │
│  │  Local LLM   │◀───│  Code Generator      │    │
│  │  (llama-cpp) │    │  (deterministic      │    │
│  │              │    │   pipeline)          │    │
│  └─────────────┘    └──────────────────────┘    │
│                                                 │
└─────────────────────────────────────────────────┘

4.4 Workflow (Spec Kit Parity, Fully Offline)

Spec Kit Command SovereignSpec Command Key Difference
/constitution /sovereign-constitution Same concept, local-first principles baked in
/specify /specify Same, but spec is a graph node, not flat markdown
/clarify /clarify Clarification via local LLM + RAG retrieval from spec KG
/plan /plan Plan generation with GBNF grammar enforcement
/tasks /tasks Same, with dependency tracking via spec KG
/analyze /analyze Cross-artifact analysis + contradiction detection + spec drift tracking
/implement /implement Deterministic code generation via local LLM pipeline

4.5 What Makes It Different

Specs as Graph Nodes. Instead of flat .specify/specs/spec.md, each spec is a node in a knowledge graph. Relationships between specs are tracked: spec A depends on spec B, spec C contradicts spec D. When you /clarify, the engine doesn't just ask the LLM — it queries the spec KG for related context, retrieves via RAG, and grounds the clarification in actual project knowledge.

Evolvable Specs with Semantic Diffing. Every spec change is tracked. Not just line-level diffs — semantic diffs. If spec A says "the API must return JSON" and spec B later says "the API must return XML," the system detects the contradiction and flags it during /analyze. This is the spec equivalent of contradiction detection in specgen's pipeline.

GBNF Grammar Enforcement. Code generated from specs passes through GBNF grammar rules, ensuring deterministic, parseable output. No hallucinated syntax. No broken JSON. No malformed Python. The grammar is defined as part of the constitution.

Narrative Drift Tracking. Borrowed directly from specgen's pipeline architecture. As specs evolve, the system tracks whether the project's narrative — its core purpose and scope — has drifted. If the original constitution says "this is a local-first news synthesizer" but the specs have drifted to include cloud API integrations, the system flags it.

Typed Contradiction Detection. Specs are typed (functional vs. technical, as Context Ark distinguishes). Contradictions between functional specs and technical specs are detected and resolved through structured clarification workflows.

4.6 How It Relates to Your Existing Stack

  • specgen: SovereignSpec uses specgen's pipeline architecture (GBNF grammar, contradiction detection, narrative drift tracking) but applies it to the SDD workflow instead of natural-language-to-code. Think of SovereignSpec as specgen's big brother — same DNA, different domain.
  • synth01: The local LLM inference pattern is identical. SovereignSpec uses the same local-first inference stack.
  • objective05: SovereignSpec can be a first-class citizen in the sovereign intelligence OS. Specs are knowledge graph nodes. The spec KG integrates with the broader knowledge infrastructure.
  • Dynamic Persona MoE RAG: The spec KG can be queried via RAG during /clarify and /analyze steps, grounding spec evaluation in actual project knowledge.

5. Why Now

Spec Kit proved the market: 28K stars, adoption by AWS (Kiro), IBM (infrastructure-as-code), and the broader ecosystem. SDD is transitioning from "interesting idea" to "industry standard." But the entire ecosystem assumes cloud AI agents. The local-first SDD niche is completely empty.

You already have the building blocks: specgen's pipeline, synth01's local inference, objective05's knowledge graph infrastructure. SovereignSpec is the natural convergence point.

6. Phase 1 Scope (MVP)

  1. CLI with Spec Kit-compatible commands (/sovereign-constitution, /specify, /clarify, /plan, /tasks, /analyze, /implement)
  2. Local LLM integration via llama-cpp (same as specgen)
  3. Spec as graph nodes — basic knowledge graph with relationship tracking
  4. GBNF grammar enforcement on code generation
  5. Contradiction detection between spec versions
  6. RAG retrieval during clarification and analysis steps
  7. No cloud API calls — fully offline

7. Risks & Mitigations

Risk Mitigation
Local LLM quality vs. cloud LLM for spec evaluation Start with a high-capability local model (e.g., Llama 3.1 70B quantized). The GBNF grammar enforcement compensates for weaker models by constraining output space
Spec KG complexity Phase 1 uses a simple adjacency-list representation. No Neo4j required — SQLite or even JSON files work for MVP
Spec Kit's ecosystem momentum SovereignSpec doesn't compete — it fills the local-first gap. Spec Kit users who want offline operation have no alternative
Spec drift tracking accuracy Leverage existing contradiction detection patterns from specgen. The semantic diffing can start simple: keyword overlap + LLM-based contradiction scoring

8. The Bigger Picture

SovereignSpec isn't just another SDD tool. It's the local-first answer to a methodology that currently requires surrendering your compute to cloud providers. It proves that spec-driven development doesn't need API keys. It proves that specs can be living, graph-grounded artifacts instead of static markdown files. And it proves that deterministic, grammar-enforced code generation is possible without ever calling an external endpoint.

The compute shortage is a manufactured financial bottleneck. SovereignSpec is evidence that you can build production-grade, spec-driven tooling without contributing to it.

9. Sources

← Back to all writingHome →