Software Factory Archive

The spec was too tight. Jay knew it as soon as he saw the agent output.

He'd spent three days writing the NLSpec for a new module—a Cedar policy evaluation engine for Leash. He'd been thorough. Maybe too thorough. The spec described the exact function signatures, the exact error types, the exact flow of data through the system. He'd written it the way he would have written code, just in English instead of Go.

The agent produced an implementation that was correct. Precisely correct. It matched the spec perfectly. And it was mediocre.

"You strangled it," Justin said, reading the output over Jay's shoulder. Not unkindly. More like a diagnosis.

"I was being precise."

"You were being prescriptive. There's a difference." Justin sat down. "When you specify the exact function signatures, you're not writing a spec. You're writing pseudocode in natural language. The agent has no room to innovate. It implements your design instead of finding a better one."

Navan had the opposite problem. His first NLSpec had been so loose that the agent produced three entirely different architectures across three runs, all of which satisfied the scenarios but none of which were compatible with each other.

"I described the goal," Navan said, "but not enough of the constraints. The agent had too many degrees of freedom. It was like giving someone directions by saying 'go somewhere nice.'"

The specification problem, as they came to call it, was the central creative challenge of the factory. Not the agents. Not the scenarios. Not the twins. The specs. Writing specifications that were precise enough for agents to implement reliably but loose enough for agents to innovate meaningfully.

Justin called it the Goldilocks zone. Too tight, and you got your own mediocre design implemented perfectly. Too loose, and you got brilliant but incompatible solutions. The sweet spot was somewhere in between: clear on outcomes, flexible on approach.

The Attractor repo was the existence proof. Five thousand seven hundred lines of pure specification, and not a single line of code. Three spec documents: attractor-spec.md, coding-agent-loop-spec.md, unified-llm-spec.md. They described what the system should do, what invariants it should maintain, what interfaces it should expose. They did not describe how to implement any of it.

"The spec IS the product," Justin said. "The code is generated. The spec is authored. That's where the engineering lives now."

Jay rewrote his Cedar policy spec. This time he described the security invariants, the evaluation semantics, the observable behaviors. He did not describe function signatures. He did not prescribe data structures. He described the world the module lived in and the properties it needed to have.

The agent's second attempt was better than anything Jay would have designed. It used a pattern Jay hadn't considered—a lazy evaluation strategy that deferred policy compilation until first use, reducing startup time by forty percent.

"I wouldn't have thought of that," Jay admitted.

"That's the point," Justin said. "If the spec only allows solutions you would have thought of, the spec is too tight."

Jay wrote that on a sticky note and put it on his monitor. It was still there months later, edges curling, the ink fading. The best specs were the ones that surprised you.