Atomic-Spec CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repository Is

This is not a runtime application. It is a governance framework for AI-driven development — a customized fork of GitHub's Spec Kit that implements the Atomic Traceability Model. The deliverables are templates, prompts, knowledge stations, and a thin Python CLI. Consumers install this framework into their own projects to constrain how AI coding agents (Claude Code, Gemini, Copilot, Cursor, Windsurf, and ~13 others) generate code.

Inspired by Leapable's "Stop Vibe Coding (Until You Do This)" video. The core premise: AI agents produce drift unless forced through gated, atomic, context-pinned phases.

The Nine Prime Directives (memory/constitution.md, Article IX)

These are the non-negotiable rules that every command in this framework enforces. When working in this repo, never weaken or bypass them — they are the entire value proposition:

1. Directory Supremacy — every feature gets index.md + traceability.md
2. Atomic Injunction — /atomicspec.tasks is FORBIDDEN from creating a single tasks.md. It must create a tasks/ directory with individual T-XXX-[name].md files
3. Context Pinning — during /atomicspec.implement, the AI may ONLY read index.md, the current task file, and traceability.md. Reading plan.md or spec.md during implementation is forbidden
4. Gate Compliance — Knowledge Station gate criteria must pass before phase transitions
5. Knowledge Routing — unknown decisions consult the Station Map first, then the specific station
6. Human-In-The-Loop — /atomicspec.plan pauses at 4 mandatory checkpoints (tech stack, validation, UI, registry sync)
7. Project Defaults Registry — all commands read specs/_defaults/registry.yaml and enforce project-wide standards
8. Self-Contained Tasks — task files embed all context (registry values, domain rules, gate criteria) needed for execution under Context Pinning
9. Orientation Read Surface (v0.3+) — /atomicspec.implement Phase 0 detects cross-provider handoff state via stamp-lifecycle status on artifact Lifecycle Markers; direct body reads of plan.md / spec.md / clarify-log.md remain forbidden, even during orientation. Sibling control to Directive 3; does NOT widen it.