DEV Community

Ramprakash Munugapati
Ramprakash Munugapati

Posted on

Building a Deterministic Spec-Driven Development (SDD) Agent for GitHub Copilot

#ai #opensource #testing #architecture

We are living in an era where AI can write code in fractions of a second. But if you maintain high-stakes enterprise applications, you know the quiet nightmare that comes with it: subtle regressions, broken configurations, and silently passing suites with empty assertions.

The core architectural flaw of most AI tooling setups is simple: We are letting the LLM generate the implementation AND grade its own work.

To fix this, I spent the last few weeks building a local Spec-Driven Development (SDD) Agent designed to serve as a strict, non-negotiable supervisor for GitHub Copilot across both VS Code and IntelliJ IDEA.

The philosophy is straightforward: Let Copilot do the creative drafting, but decouple the state machine and verification pipeline entirely into an un-bypassable local engine.

The Dual-System Architecture

The codebase splits responsibilities clearly across three primary boundaries:

  1. The Native Prompts: A thin .github/copilot-instructions.md layer guiding requirement collection and path-scoped implementations inside the IDE.
  2. The Command Line Engine: A deterministic Python application (sdd_agent.py) managing task compilation, directed graphs, and approvals.
  3. The Local Status Dashboard: A vanilla HTML/JS portal bound strictly to a loopback address (localhost:8080) providing continuous log buffering.

[ Phase 1: DISCOVERY ]
AI discovers & drafts Spec, Plan, Tasks
│
▼
[ Cryptographic Gate ]
Human signs off via Python CLI (SHA-256)
│
▼
[ Phase 2: IMPLEMENTATION ]
AI writes code via Test-First workflow
│
▼
[ Phase 3: VERIFICATION ]
Python Engine executes Gradle / Checkstyle / JaCoCo

Enforcing a Cryptographic Contract (SHA-256)

To stop an AI agent from shifting the goalposts mid-way through writing code, the Python CLI introduces deterministic fingerprinting. When a human reviews and approves the initial specification, the system captures a unique hash of that document state.

  • Spec Approval: Binds the SPEC.md fingerprint.
  • Plan Approval: Binds the SPEC.md + PLAN.md fingerprints.
  • Task Approval: Binds the SPEC.md + PLAN.md + TASKS.json fingerprints.

If the AI tweaks a requirement line or alters a task definition during implementation, the signature changes instantly. The validation engine immediately trips, changes the workspace state to STALE, and freezes the pipeline until a human manually clears it.

The Hard Validation Gates

When you execute python sdd_agent.py verify, the core engine skips the "vibe checks" and processes cold static and dynamic parameters:

  1. Cycle Detection: Parses the TASKS.json file into a directed graph to explicitly trace dependencies and catch circular paths before spawning tasks.
  2. Style Adherence: Forcing standard Java 21 Gradle modules through active Checkstyle passes. Any style deviation fails the gate.
  3. The Coverage Floor: Rather than scanning human-readable HTML strings or relying on loose proxy numbers, the engine parses raw XML test evidence. It pulls data straight from the <counter type="LINE"> elements inside jacocoTestReport.xml. If the line metric reads 79.9% against an inclusive 80% floor, the execution fails outright.

Verification != Functional Completeness

As engineers, we know that hitting a 100% mechanical check pass does not guarantee that business logic parameters are actually solved. However, removing human error from the build safety loop allows us to spend our energy looking at the final human acceptance evaluation rather than fighting basic regressions.

The complete architectural setup, bootstrap files, and templates are open-source and ready for exploration.

I would love to get your feedback on this state-machine structure. How are you enforcing verification loops on your own local AI configurations?

🤖 2. The Reddit Plan (Targeted Subreddits)

Reddit communities have zero tolerance for self-promotion or marketing fluff. To get upvoted, your post must focus on architectural choices, challenges, and source patterns.

Recommended Communities:

• r/java (Focus strictly on the Java 21/Gradle layout, Checkstyle validation, and raw JaCoCo parsing).
• r/AIEngineering or r/LocalLLaMA (Focus on the local execution model, SHA-256 validation, and eliminating external cloud dependencies).

Top comments (0)