Purpose
AI agents are easier to control when requirements, decisions, acceptance criteria, evidence and open questions are written down in files.
Open SourceAgentic AISpecificationsJSON SchemaPython
SpecGen
Versioned software specifications that people can review and that compile into workflows for AI agents.
Case summary
System
SpecGen writes software specifications as structured data that a program can check. It records user decisions, source evidence, requirements, acceptance criteria, and how the work will be evaluated. It also records the implementation structure, where each fact came from, and open questions. It can be validated and handed off without relying on chat memory.
Contribution
I designed the specification model, the split between authoring and execution, the rules for recording where facts come from, the approach to existing codebases, evaluation intent, and the contracts for compiling to Agent-Workflow. Agents help with implementation and compatibility work, and I review it against the versioned contracts.
System diagrams
Each diagram links to its Mermaid source (a text format for diagrams) and has a static SVG version. They show how control and evidence move through the system. They illustrate the design and do not record real runs.
How a specification is compiled
Intent and an append-only log of authoring events are compiled into a frozen snapshot. The Markdown copy, change summary, checks and target output are all derived from it.
Curated from the public SpecGen docs/ARCHITECTURE.md Mermaid compilation diagram, source revision 7c3841bd. The derived outputs do not define the specification.
Supporting architecture views 4 additional views
System diagrams
These diagrams show the architecture, who is responsible for what, and where evidence comes from, based on the project record. They describe the implementation and its stated limits. They are not independent test results.
01 / Execution path
Who owns what, from specification to execution
SpecGen defines the specification and Agent-Workflow runs the work. A fixed set of shared contracts connects the two, and neither tool depends on the other at runtime.
- People and repository intent
- SpecGen owns the specification
- Shared schemas and fixtures
- Agent-Workflow owns execution
- Evidence, review and acceptance
02 / Who controls what
Facts and agent findings stay labeled
Facts checked by code and findings from agents are kept separate and clearly labeled.
The specification
- versioned requirements and acceptance criteria
- authoring decisions and where facts came from
- frozen snapshot and checksum
Repository evidence
- read-only discovery by code
- source baseline and drift checks
- research plan for existing codebases
Output for execution
- compilation for the target tool
- shared schemas and test fixtures
- prompt files in Agent-Workflow's own format
03 / Execution path
From frozen snapshot to target output
Authoring events and repository evidence lead to a versioned snapshot. The output compiled for the target is generated from that snapshot and cannot change it.
- Requirements + authoring decisions
- State rebuilt from events
- Read-only repository evidence
- Frozen snapshot + checksum
- Compile schemas and files for the target
- Agent-Workflow uses them under its own contract
More architecture diagrams 1 additional views
04 / Execution path
OpenSpec import runs alongside the SpecGen path
Agent-Workflow accepts a plan from OpenSpec 1.13.2 (a planning tool), tested against that release, through Agent-Workflow's job format (native-job/v2). The older SpecGen format (native-job/v1) is still supported. The first import step did not retire SpecGen. A planning document alone does not decide acceptance.
- OpenSpec plan
- Tested import into Agent-Workflow's job format
- Agent-Workflow owns execution
- Evidence, evaluation, review and acceptance
Engineering principles
Requirements are set in SpecGen
A tool that runs the work can read a compiled specification but cannot change the requirements.
Shared contracts keep the tools independent
SpecGen and Agent-Workflow agree on fixed handoff schemas without depending on each other's runtime code.
Problem
- Vague engineering intent is hard for people to review and for agents to carry out consistently.
- Work on an existing codebase needs evidence from the repository. Each fact needs a record of where it came from.
- Tools that run the work should read the specification but never decide what it means.
Technical Highlights
- Specifications stored as JSON, with versioned contracts that never change once published
- Authoring decisions kept in an append-only log, plus summaries of how the meaning changed between versions
- Repository analysis, drift checks (has the repository changed since the specification?) and research plans for existing codebases
- How the work will be evaluated is written down before it runs
- Compilation into the prompt files that Agent-Workflow, the tool that runs the work, reads
- Compiling for Agent-Workflow is tied to an exact source baseline (a specific repository version)
System Design
- Authoring events record why the state changed.
- The frozen snapshot defines what the specification means.
- The Markdown copy, the change summaries and the output for target tools are all derived from the snapshot.
- SpecGen can compile output for Agent-Workflow. SpecGen does not need Agent-Workflow to run.
Rule-Based Control
- Schema validation and contract versioning
- Snapshot and checksum generation
- Repository source checks and drift detection
- Rules for compiling to a target
Where Models Fit
- Agents may help analyze an existing codebase for meaning. Their findings are kept in separate files from the repository facts that code checks produce.
Failure and recovery
- Published contract identifiers have their own version numbers, separate from software releases.
- When an exact repository version is required, a stale baseline, or a plain folder with no repository version, is rejected.
Measured evidence
Current compatibility baseline
measuredSpecGen 0.2.9 → Agent-Workflow 0.11.9 target
The repository's release metadata and integration docs pin this SpecGen release and its Agent-Workflow target.
This shows version and contract compatibility. It is not a performance or quality benchmark.
2026-09-23source c27c07a9cd52
method and source