Atelier

A first-principles, docs-as-code engineering framework for AI agents and humans.

What This Is

Atelier is a hierarchical document tree of engineering principles. Eight universal core principles (C1–C8) govern eleven domains (API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps, UI/UX), each with ten derived principles (P1–P10). A principles matrix maps every domain rule back to the core rule it derives from, making conflict resolution deterministic.

This is not a style guide. This is not a linter. This is a principle hierarchy with cross-references, consumed by AI agents as pre-completion guidance and by humans as engineering canon.

Who It's For

• AI agents — read core/ then the relevant domains/ before completing a coding task. Run review/agent-checklist.md before finishing.
• Human engineers — read README.md → MANIFEST.md → core/ for onboarding, then the domains relevant to your work.
• Reviewers — use review/peer-review-checklist.md and review/anti-patterns.md.

Quickstart

For Agents

1. Read core/first-principles.md (the 8 axioms)
2. Read core/conflict-resolution.md (how to resolve rule conflicts)
3. Read domains/<your-task-domain>/first-principles.md
4. Read domains/<your-task-domain>/<topic>.md as needed
5. Run review/agent-checklist.md before completing

For Humans

1. Read this README
2. Read MANIFEST.md (the authoritative document index)
3. Read core/first-principles.md → core/conflict-resolution.md → core/reading-order.md
4. Pick a domain of interest and read its first-principles.md
5. Skim matrix/principles-matrix.md to see how everything connects

The Eight Core Principles

#	Principle	One-line
C1	Correctness	The system does what it is supposed to do, and nothing else.
C2	Clarity	The intent of the code is obvious to its reader.
C3	Simplicity	The solution is as simple as possible, and no simpler.
C4	Locality	Decisions and their consequences live near each other.
C5	Reversibility	Every decision can be undone, and the cost of undoing is known.
C6	Composability	Parts combine into wholes, and the parts are reusable.
C7	Observability	The system's behavior is visible to those who must understand it.
C8	Economy	The system uses no more resources than the task requires.

Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never sacrificed.

The Domains

Domain	First Principles	Derived Docs
UI/UX	✓	components, accessibility, tokens, copywriting
API	✓	rest, graphql, versioning, error-responses, pagination
Security	✓	authentication, authorization, input-validation, secrets, supply-chain
Data	✓	schema-design, migrations, indexing
Testing	✓	pyramid, fixtures
Performance	✓	frontend, backend
Observability	✓	logging, metrics, tracing
Errors	✓	patterns
Documentation	✓	doc-templates
Concurrency	✓	patterns
DevOps	✓	ci-cd, environments

Repository Structure

atelier/
├── core/           # The 8 universal principles (read first)
├── domains/        # 11 domains, each with first-principles + derived docs
├── languages/      # Language-specific application of domain rules
├── review/         # Checklists and anti-patterns
├── matrix/         # Cross-reference: domain ↔ core
├── examples/       # Worked examples (good + bad)
├── MANIFEST.md     # Authoritative document index
└── README.md       # This file

License

MIT. See LICENSE.

Contributing

See CONTRIBUTING.md.

Version

This is v0.1. See CHANGELOG.md for version history.