Precision engineering for AI-written code

Atomic Spec turns unpredictable AI into a governed assembly line — eight Prime Directives, four HITL checkpoints, atomic task files, and 24 specialized subagents.

Install
See how it works Read the manual
Chaos mode
Context pollution
Hallucinations
Zero governance
Assembly Line
HITL checkpoint: approved
Task T-001: pinned

The promise was speed.
The reality is rework.

Atomic Spec exists because one AI-instructions file isn't enough. Soft guidance drifts. Gates don't.

The AI invents requirements

You asked for a simple endpoint. The agent decided you also need PostgreSQL, Redis, Kubernetes, and microservices. Nobody asked.

Context pollution

The agent reads your whole repo, drowns in it, and ships a 500-line function that does everything and nothing well.

No traceability

"Where did this code come from? Which requirement does it satisfy?" Silence. Good luck debugging or extending it.

The wiring problem

Every component built. Nothing connected. Missing routes. Broken nav. "Feature complete" — and nothing works end-to-end.

The Solution

The Atomic Traceability Model

A governance framework that turns the AI from an unpredictable collaborator into a system that ships consistent, traceable code — feature after feature.

Constitutional governance

Every AI decision is bound by a constitution. Article IX hardcodes the eight Prime Directives — non-negotiable rules every command enforces.

  • Consistency across features
  • Eight immutable Prime Directives
  • Project Defaults Registry as source of truth

HITL checkpoints

The AI proposes. Humans approve. At four critical decision points, the system STOPS until you sign off.

  • No silent assumptions
  • Tech stack review
  • Validation review
  • UI/UX approval
  • Registry sync

Atomic task decomposition

Instead of one monolithic tasks.md, every feature explodes into isolated T-XXX files. The agent reads only the current task — by design.

  • One requirement per file
  • Embedded context (registry + domain rules + gate criteria)
  • Verification command included
  • Context Pinning during implementation

The Assembly Line Manual

18 Knowledge Stations encode domain expertise as gate criteria. The AI stops guessing — it follows your engineering standard, station by station.

Station 03Standard

Discovery

ICP, JTBD, wedge, competitor pain mining — raw requirement capture.

Gate criteria

  • User problem validated
  • Anti-goals (what we won't ship) listed

Required deliverables

  • discovery.md
  • problem_statement.md

Why it matters

Skip Station 03 and you ship technical debt on day one. Without this context, the AI produces code that runs and can't be maintained.

24 specialized subagents. Matched dynamically.

Generalist AI pretends to know every domain. Our specialists actually do. Subagents are discovered by scanning YAML frontmatter and matched to your feature's keywords — not hard-coded.

Backend

backend-architect

REST conventions, tenant isolation, API schemas.

Database

database-optimizer

Schema normalization, indexing strategies.

Frontend

frontend-developer

Component composition, state management.

Security

security-auditor

OWASP controls, vulnerability analysis.

DevOps

deployment-engineer

CI/CD pipelines, containerization.

Frontend

ui-ux-designer

User flows, accessibility (WCAG).

Billing

payment-integration

Stripe and LemonSqueezy integration patterns.

AI/ML

ai-engineer

RAG systems, prompt engineering.

Plus 13 more waiting in .specify/subagents/ — and you can drop in your own.

This is where the AI stops.

Most AI coding fails because the model makes silent decisions. HITL checkpoints flip that. The agent proposes, then HALTS. You review. You approve. Only then does it build.

atomicspec — interactive
$ atomicspec plan --interactive ══════════════════════════════════════════════════════════════ 🛑 TECH STACK REVIEW — Phase 0.5 checkpoint ══════════════════════════════════════════════════════════════ Resolved decisions: | Decision | Value | Source | |--------------|----------------|----------| | Language | Python 3.11 | Spec | | Framework | FastAPI | Spec | | Database | PostgreSQL 15 | Assumed | | ORM | SQLAlchemy 2.0 | Assumed | ⚠ ASSUMPTIONS: - PostgreSQL chosen over SQLite for multi-tenant support - SQLAlchemy chosen for async compatibility Your options: 1. [Approve all] — proceed with these choices 2. [Revise] — change Database to SQLite 3. [Reject] — start over

Context Pinning — the pollution shield

Conventional wisdom says AI needs more context. We disagree. Too much context causes drift. During implementation, the agent is architecturally prevented from reading anything outside the current task file — by design.

Context: pinned
# Task: Create the User model
# AI reads ONLY T-010-create-user-model.md
# Result: clean, focused implementation

class User(Base):
    id = Column(UUID, primary_key=True)
    email = Column(String, unique=True)
    password_hash = Column(String)

# Roles added in T-015
# Analytics added in T-020
# Billing added in T-025

Read access (Directive 3)

Current task
T-XXX.md
Full plan (plan.md)
BLOCKED
Spec (spec.md)
BLOCKED
Other task files
BLOCKED

"Why forbid plan.md? Because if the AI sees 'future admin panel', it will try to build it today. Pinning forces the agent to build only what this task needs — and nothing else."

The full Assembly Line

1. Specify

Discovery, requirements, gates 03–05

Output: spec.md
HITL #1

2. Plan

Architecture, research, registry sync

Output: plan.md
HITL #2

3. Tasks

Atomic decomposition, embedded context

Output: tasks/T-XXX-*.md
HITL #3

4. Implement

Context-Pinned execution, verification commands

Output: shipped code + traceability.md

Note: Reject at any HITL checkpoint and the workflow loops back to the previous phase automatically. No corrupted state. No half-built features.