On NLSpecs: Why, What, How, Done

2026-02-13T00:00:00+00:00

I have been excitedly digging into the attractor</code> project</a>.</p>

One of the remarkable things about that project is how</em> it is specified. I followed the instructions in the README.md:</p>


Supply the following prompt to a modern coding agent (Claude Code, Codex, OpenCode, Amp, Cursor, etc):</p>

codeagent> Implement Attractor as described by https://factory.strongdm.ai/
</span></code></pre>
</blockquote>
claude</code> thought for about ten minutes, then asked me a couple of questions: and then pretty much one shotted it.</p>
In this new world where we—as an industry—have settled</a> on the importance of the specification (for this month, anyway). When a specification is written in such a way that a coding agent just eats, and then produces working code, then I think it's worth looking further.</p>
There is some reference in that repo about NLSpecs, but little or nothing else on the internet. So, I thought I'd make some.</p>
nlspec.nlspec.md</h2>
I compared the three specs that came with the attractor project</a>, and extracted the commonalities, the "patterns".</p>
Then, in the style of RFC 2119</a>, I wrote</del> had generated an NLSpec of NLSpec.</p>
Then, reading it, and understanding it a bit more, I re-arranged it. I think it's still a little verbose and explicit, but it's good for a first draft.</p>
Then, I pushed it to Github, where we can poke at it, and build tools, skills and commands around it.</p>
You can read nlspec.nlspec.md</code></a> in this Github repo</a>, with some claude</code>-generated commentary</a>, which is actually quite readable. I found it, genuinely, fascinating.</p>
Features of NLSpec</h2>
There are quite a few things to talk about, but I'll restrict this post to just two:</p>
Complementary representations of requirements</h3>
The use of multiple overlapping, complementary representations to express requirements: for example: prose, pseudo-code, tables, ascii diagrams, checklists.</p>
Previously, I have been asking for specs to be not have any imperative code in, to make it easy to read. Instead NLSpec asks for pseudo-code and some prose explanation combines the precision of code, and the brevity of prose.</p>
The complementary representations then massively reduce the ambiguity.</p>
Complementary interrogatives of requirements, and a definition of done</h3>
The four clusters of sections can be summarized as Why, What, How and Done.</p>
So, then we have requirements described in complementary interrogative sections.</p>
The final of these sections is the Definition of Done</strong> section: it defines a checklist of integration tests, together with pseudo-code on what these tests actually are.</p>
Each integration test mirrors the What</strong> section, which in turn is represented in the How</strong> section.</p>
This allows an agent to work forwards, when implementing then checking: WHAT</strong>, HOW</strong>, DONE</strong>. Or backwards: DONE</strong>, WHAT</strong>, HOW</strong> when validating or debugging: each requirement is woven in to the document.</p>
Next Steps</h2>
So many things can come from this. I think we have a workflow to get from a spec to working-ish code (for some product classes at least), but now, how to generate, modify, split, merge specs…</p>

Notes to a Future Self - strongdm

On NLSpecs: Why, What, How, Done

Next Steps</h2>
So many things can come from this. I think we have a workflow to get from a spec to working-ish code (for some product classes at least), but now, how to generate, modify, split, merge specs…</p>

Intent transfer

Notes to a Future Self - strongdm

On NLSpecs: Why, What, How, Done

Next Steps</h2> So many things can come from this. I think we have a workflow to get from a spec to working-ish code (for some product classes at least), but now, how to generate, modify, split, merge specs…</p>

Intent transfer

Next Steps</h2>
So many things can come from this. I think we have a workflow to get from a spec to working-ish code (for some product classes at least), but now, how to generate, modify, split, merge specs…</p>