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.
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
# Core — Reading Order
|
||
|
||
**Status:** Foundational
|
||
**Audience:** New readers (agents and humans). Read after `first-principles.md` and `conflict-resolution.md`.
|
||
|
||
## 1. The Canonical Order
|
||
|
||
This is the order in which the framework is designed to be consumed. Following it ensures you build the mental model before the details.
|
||
|
||
### For All Readers
|
||
|
||
1. **`core/first-principles.md`** — The eight axioms. Everything derives from these. Read first, always.
|
||
2. **`core/conflict-resolution.md`** — How to resolve disagreements between rules. Read second, always.
|
||
3. **`core/reading-order.md`** — This document. You are here.
|
||
|
||
### For a Specific Task
|
||
|
||
4. **`domains/<relevant>/first-principles.md`** — The domain's ten principles. Read the domain(s) relevant to your task.
|
||
5. **`domains/<relevant>/<topic>.md`** — The domain's derived topic docs. Read only what your task needs.
|
||
|
||
### For Reference
|
||
|
||
6. **`matrix/principles-matrix.md`** — The full mapping of every domain principle to its core derivation. Consult when a rule's authority is unclear or a conflict arises.
|
||
7. **`MANIFEST.md`** — The authoritative index of all framework documents. If a document is not here, it is not part of the framework.
|
||
|
||
### For Evaluation
|
||
|
||
8. **`review/agent-checklist.md`** — The pre-completion checklist. Agents run this before finishing a task.
|
||
9. **`review/peer-review-checklist.md`** — The human review checklist.
|
||
10. **`review/anti-patterns.md`** — Catalog of known violations.
|
||
|
||
### For Language-Specific Application
|
||
|
||
11. **`languages/<lang>.md`** — How the domain principles apply in a specific language. Read only for the language you are working in.
|
||
|
||
### For Illustration
|
||
|
||
12. **`examples/good/*`** — Worked examples of the framework applied correctly.
|
||
13. **`examples/bad/*`** — Worked examples of violations, with the breached principles cited.
|
||
|
||
## 2. Reading Paths
|
||
|
||
### Path A: New Agent (Pre-Task)
|
||
|
||
```
|
||
core/first-principles.md
|
||
→ core/conflict-resolution.md
|
||
→ core/reading-order.md
|
||
→ domains/<task-domain>/first-principles.md
|
||
→ domains/<task-domain>/<topic>.md
|
||
→ review/agent-checklist.md (run before completing)
|
||
```
|
||
|
||
Estimated time: 15–25 minutes depending on domain depth.
|
||
|
||
### Path B: New Human (Onboarding)
|
||
|
||
```
|
||
README.md
|
||
→ MANIFEST.md
|
||
→ core/first-principles.md
|
||
→ core/conflict-resolution.md
|
||
→ core/reading-order.md
|
||
→ one domain of personal interest (e.g., domains/api/first-principles.md)
|
||
→ matrix/principles-matrix.md (skim)
|
||
```
|
||
|
||
Estimated time: 30–45 minutes for a full pass.
|
||
|
||
### Path C: Conflict Resolution
|
||
|
||
```
|
||
core/conflict-resolution.md (procedure)
|
||
→ matrix/principles-matrix.md (look up both rules' derivations)
|
||
→ core/first-principles.md (apply precedence)
|
||
```
|
||
|
||
Estimated time: 5 minutes per conflict.
|
||
|
||
### Path D: Review
|
||
|
||
```
|
||
review/agent-checklist.md (or peer-review-checklist.md)
|
||
→ for each failed checklist item, follow Path C
|
||
→ examples/bad/* for the relevant violation pattern
|
||
```
|
||
|
||
## 3. What Not to Read First
|
||
|
||
- **Do not** start with `examples/`. Examples illustrate principles you have not yet read.
|
||
- **Do not** start with `languages/`. Language rules derive from domain rules you have not yet read.
|
||
- **Do not** start with `matrix/`. The matrix is a reference, not a tutorial.
|
||
- **Do not** skip `core/`. Everything depends on it.
|
||
|
||
## 4. Skipping is Allowed After Core
|
||
|
||
After reading `core/` (the three foundational documents), you may skip freely. The domains are independent of each other. You do not need to read `domains/security/` to use `domains/api/`. You only need the domain relevant to your task.
|
||
|
||
The one exception: `matrix/principles-matrix.md` references all domains. You do not need to read all domains to use the matrix, but the matrix is most useful when you have read at least one domain.
|
||
|
||
## 5. Versioning
|
||
|
||
The framework versions as a whole (semantic versioning). A change to `core/first-principles.md` is a major version. A new domain is a minor version. A new topic doc is a patch. See `CHANGELOG.md` for the version history. |