Nine rules. Seventeen agents. Zero drift.

Make your AI ship the spec, not the vibe.

A governance framework that pins context, gates phase transitions, and forces atomic tasks — so Claude, Cursor, Copilot, and 14 others all produce the same PR from the same spec.

Install
Read the Nine Prime Directives

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 mechanism

How Atomic Spec works, in three moves.

Not more instructions. Three enforced mechanisms the agent cannot re-interpret, cannot skip, cannot silently ignore.

01 / atomic

Atomic tasks

One requirement per file — or the pipeline refuses to move. Every feature decomposes into isolated task files with domain rules, registry values, and the verification command embedded inline.

tasks/ ├── T-001-scaffold-users-route.md ├── T-002-validate-input-schema.md ├── T-003-write-repository.md └── T-037-wire-users-nav.md
02 / pinned

Context Pinning

The implementer sees exactly three files. plan.md and spec.md are architecturally blocked — when the model cannot read the roadmap, it stops building for it.

# readable index.md T-002-validate-input-schema.md traceability.md   # blocked spec.md → denied plan.md → denied
03 / enforced

Registry enforcement

Every project-wide default lives in one YAML file. Every command reads it on entry. Every new default routes through a HITL checkpoint before it lands.

# specs/_defaults/registry.yaml architecture: hexagonal data_access: repository tenancy: shared-schema error_envelope: rfc9457

The AI proposes. Humans approve.

See the full pipeline docs

Article IX

The Nine Prime Directives

Non-negotiable rules every command enforces. Articles I-VIII of the constitution flex with your project; Article IX is invariant across every consumer of the framework.

  • Directory Supremacy

    Every feature owns an index.md and traceability.md.

    Prevents: implementations that no one can trace back to a requirement.

  • Atomic Injunction

    Tasks live one per file in tasks/T-XXX-*.md, never a single tasks.md.

    Prevents: AI reading sibling tasks and drifting mid-feature.

  • Load-bearing

    Context Pinning

    During /implement, AI may only read index.md, the current task, and traceability.md.

    Prevents: kitchen-sink PRs that re-derive decisions from plan.md.

  • Gate Compliance

    Knowledge Station gate criteria must pass before phase transitions.

    Prevents: proceeding on "feels good" instead of objective criteria.

  • Knowledge Routing

    Unknown decisions consult the Station Map first, then the specific station.

    Prevents: AI improvising when a proven pattern exists.

  • Human-In-The-Loop

    /plan pauses at 4 mandatory HITL checkpoints.

    Prevents: silent architectural commitments the reviewer never sees.

  • Project Defaults Registry

    All commands read specs/_defaults/registry.yaml and enforce project-wide standards.

    Prevents: inconsistent conventions across a codebase.

  • Self-Contained Tasks

    Task files embed all context needed for implementation.

    Prevents: the implementer needing to read forbidden files.

  • New - v0.3+

    Orientation Read Surface

    /implement Phase 0 detects cross-provider handoff via stamp-lifecycle status.

    Prevents: one AI silently overwriting another AI's half-finished work.

Read the full text of Article IX

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.

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.

Review

code-reviewer

Regression audits, style checks, invariant verification.

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 16 more base subagents in .specify/subagents/ — and 157 mobile-specialized ones under mobile/. Drop in your own to extend the set.

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.

The humans

Built by

Two maintainers steward this fork. Each owns a load-bearing pillar of the framework — the Nine Prime Directives and the Assembly Line mental model.

Mohammad Khoddami

Maintainer · Prime Directives

View LinkedIn profile

Pablo Nastar

Maintainer · Assembly Line

View LinkedIn profile