I have been excitedly digging into the attractor project.

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

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

codeagent> Implement Attractor as described by https://factory.strongdm.ai/

claude thought for about ten minutes, then asked me a couple of questions: and then pretty much one shotted it.

In this new world where we—as an industry—have settled 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.

There is some reference in that repo about NLSpecs, but little or nothing else on the internet. So, I thought I'd make some.

nlspec.nlspec.md

I compared the three specs that came with the attractor project, and extracted the commonalities, the "patterns".

Then, in the style of RFC 2119, I wrote had generated an NLSpec of NLSpec.

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.

Then, I pushed it to Github, where we can poke at it, and build tools, skills and commands around it.

You can read nlspec.nlspec.md in this Github repo, with some claude-generated commentary, which is actually quite readable. I found it, genuinely, fascinating.

Features of NLSpec

There are quite a few things to talk about, but I'll restrict this post to just two:

Complementary representations of requirements

The use of multiple overlapping, complementary representations to express requirements: for example: prose, pseudo-code, tables, ascii diagrams, checklists.

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.

The complementary representations then massively reduce the ambiguity.

Complementary interrogatives of requirements, and a definition of done

The four clusters of sections can be summarized as Why, What, How and Done.

So, then we have requirements described in complementary interrogative sections.

The final of these sections is the Definition of Done section: it defines a checklist of integration tests, together with pseudo-code on what these tests actually are.

Each integration test mirrors the What section, which in turn is represented in the How section.

This allows an agent to work forwards, when implementing then checking: WHAT, HOW, DONE. Or backwards: DONE, WHAT, HOW when validating or debugging: each requirement is woven in to the document.

Next Steps

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…