# Agentic engineering experiment 4

> A continuation from Agent-based coding experiment 1, Experiment 2, and Experiment 3. Organized on March 13, 2026.

A continuation from [Agent-based coding experiment 1](https://wiki.g15e.com/en/pages/Agentic%20coding%20experiment%201.txt), [Experiment 2](https://wiki.g15e.com/en/pages/Agentic%20coding%20experiment%202.txt), and [Experiment 3](https://wiki.g15e.com/en/pages/Agentic%20coding%20experiment%203.txt). Organized on <March 13, 2026>.

I extended [s4](https://wiki.g15e.com/pages/Semi-structured%20software%20spec.txt) and made something called [specdown](https://wiki.g15e.com/pages/specdown.txt). The idea is to write specifications in Markdown while inserting executable <acceptance tests> and [Alloy](https://wiki.g15e.com/pages/Alloy%20Analyzer.txt) models here and there along the way.

## What was unsatisfying about the previous experiments

- In [semi-structured software specifications](https://wiki.g15e.com/pages/Semi-structured%20software%20spec.txt), I had used <YAML> because I wanted specifications to be both easy for humans to read and write and also easy for logic to analyze, but YAML was not as comfortable for humans to read as [Markdown](https://wiki.g15e.com/pages/Markdown.txt).
- In trying to put all executable specifications into a single file to reduce the mismatch problem between specifications and code, there was a problem where the specification would become endlessly long.
- Introducing the concept of <software traceability> was good, but I didn't like that it was hardcoded into the flow of business goals → features → acceptance tests. I would like to be able to freely express other kinds of graphs as well (e.g. epic → story → acceptance test, etc.).
- It was disappointing that I did not properly address the problem of [specifications written in natural language](https://wiki.g15e.com/en/pages/Specification%20written%20in%20natural%20language.txt).
- The idea of giving an [LLM](https://wiki.g15e.com/pages/Large%20language%20model.txt) a <CLI> and having the CLI guide the LLM ([recursive neuro-symbolic inversion of control](https://wiki.g15e.com/en/pages/Recursive%20Neuro-Symbolic%20Inversion%20of%20Control.txt)) was also decent. It seems that now the perception that LLMs and CLIs are a perfect match has become widespread.

## Improvements

I made something called [specdown](https://wiki.g15e.com/pages/specdown.txt). Like [s4](https://wiki.g15e.com/pages/Semi-structured%20software%20spec.txt), which I made last year, it is a way of expressing executable specifications as semi-structured documents.

- Instead of making the whole thing <YAML>, I changed it to a Markdown format with YAML frontmatter. Even this much is structured enough.
- Taking inspiration from [Ward Cunningham](https://wiki.g15e.com/pages/Ward%20Cunningham.txt)'s [FIT](https://wiki.g15e.com/en/pages/Framework%20for%20integrated%20test.txt) from about 20 years ago (and, further back, from <Donald Knuth>'s <literate programming>), I tried implementing a way for documents and executable code to blend well together.
- I made it possible to use [Alloy Analyzer](https://wiki.g15e.com/pages/Alloy%20Analyzer.txt). Now natural language, modeling languages, and acceptance tests are woven together a bit better within a single document. I made some progress on the problem of [specifications written in natural language](https://wiki.g15e.com/en/pages/Specification%20written%20in%20natural%20language.txt) a little more.
- I implemented <software traceability> naturally through Markdown links, and made it possible to define the properties of graphs simply in a configuration file.

## Eating my own dog food

- A specification defining specdown itself in specdown: https://corca-ai.github.io/specdown/
- The specifications for this wiki: https://wiki.g15e.com/specdown/
- Plus 3 other private projects