# 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.