José Miguel Gómez

Back to the home page

Specgate

Approved specs in, reviewed code out

This production is a private summary: description, learnings and stack are shown, the code stays private.

Draft. Written from the program notes and pending the author’s review.

Status
Now showing
Type
Agentic workflow
Running since
January 2025
Role
Architect and lead engineer
Domains
software delivery, governance
Cast
TypeScript, GitHub Actions, OpenAPI, PostgreSQL

Context and problem

Delivery intelligence in Go: business-hours flow metrics, QA bugs mapped to OpenAPI contracts, specs served to coding agents over MCP.

Assumption: teams adopting AI coding agents merge code that drifts from the specification that was approved, and reviewers cannot tell which specification a change implements.

Specgate keeps approved specifications as the single input of AI coding agents and ties every reviewed change back to the specification it implements.

How it was built

Built in 3.9 h · 224 tests · 10 audits

Source: Trysac/09-specgate docs/development-report.md (lines 18, 24-25); 233 min of commit time, dated 21 November 2026.

Architecture and interfaces

Provides
mcp specgate
Shared keys
spec_ref, endpoint, error_code

What the project taught

  • A specification reference carried from the approved document to the pull request makes drift visible at review time instead of after release.
  • Treating the approved specification as the single input of a coding agent constrains what it builds better than prompting rules do.
  • Being the source of specifications for a downstream software factory requires a stable read interface; the consumer should depend on a port, not on the storage.
  • Gating merges on a missing specification reference is accepted by a team once the reference is one click away.

Case study in preparation

The full case study adds these sections when it is published:

  • Constraints
  • Architecture diagrams (C4 context and containers)
  • Three key decisions
  • What went wrong
  • Results with dated evidence
  • Demo video
  • What I would do differently

In the project mesh

  • Forgeline, zero effort: interface specgate provided by one and consumed by the other
  • Resolvo, zero effort: 2 shared keys (endpoint, error_code) and both expose an api or mcp interface
  • Tideline, low effort: shared keys endpoint, error_code; a standard interface exists
  • Vigilo, low effort: shared keys endpoint; a standard interface exists

Highlights

spec driven, governance, github actions