Skip to main content
Spec Led starts from one simple observation: software changes faster than shared understanding. That creates the same failures again and again:
  • behavior drifts from intent
  • tests pass but the contract is unclear
  • docs lag behind code
  • new team members take too long to understand what matters
  • AI makes plausible changes without enough context

​
Specs are not enough by themselves

A spec helps, but only if the team keeps using it. If nobody checks the spec after the first draft, drift comes back. That is why the core idea is a loop, not just a file.

​
The intent verification loop

The loop is:
  1. a human has an idea
  2. a human writes or updates the spec
  3. a human and an AI build code, tests, and docs from that spec
  4. the project verifies the result
  5. a human reviews the result and adjusts the spec or the code
  6. CI runs the same checks to catch drift early
This is what makes specs operational.

​
Why humans stay in the loop

AI can help with implementation and drift repair. AI should not be the final authority on what the system is for. Humans still decide intent, approve changes, and resolve ambiguity.

​
Why CI matters

The shared gate should live in CI. That is where the team sees drift together. Some teams also run the same checks on pre-commit. That can help catch issues earlier, but CI is the main guard.

​
Why this can stay simple

The starter version does not need heavy governance. It can start with:
  • one spec file
  • one check command
  • one CI check
Larger systems can add more structure later.

​
The practical result

Specs help because they stay inside a loop that keeps intent, code, tests, docs, and CI tied together.