Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
90 lines
3.8 KiB
Markdown
90 lines
3.8 KiB
Markdown
# 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. |