atelier/CONTRIBUTING.md

Contributing to Atelier

Thank you for considering a contribution to Atelier. This framework lives by its principles; contributions are expected to follow them.

What We Accept

• New domain first-principles — if a domain is missing (e.g., domains/ai-ml/), propose it with 10 principles (P1–P10), each traced to a core principle (C1–C8) in matrix/principles-matrix.md.
• New domain derived docs — topic docs under an existing domain (e.g., domains/api/webhooks.md), deriving from the domain's first-principles.
• New language application docs — languages/<lang>.md showing how domain principles apply in a specific language.
• New examples — examples/good/* (with principle citations) or examples/bad/* (with violation citations).
• Corrections — to existing principles, derivations, or examples. A correction to a core principle is a major version change; treat with care.
• Improvements to the matrix — if a derivation is missing or wrong, propose the fix with the rationale.

What We Do Not Accept

• Style rules — Atelier is principles, not style. Use a linter for style.
• Tooling — linters, analyzers, or enforcement code. Atelier is markdown.
• Unlisted docs — every document must be in MANIFEST.md. An unlisted doc is not part of the framework.
• Principles without derivation — a domain principle that does not trace to a core principle is orphaned and will be rejected.

How to Contribute

1. Read the relevant docs first

• core/first-principles.md — the eight axioms.
• core/conflict-resolution.md — how conflicts are resolved.
• The domain(s) you are contributing to.
• matrix/principles-matrix.md — to see existing derivations.

2. Follow the document structure

See domains/documentation/doc-templates.md for the canonical structure. Every first-principles doc has:

• Manifesto
• The Principles (P1–P10, named, defined, with "what violates it")
• Conflict Resolution
• What Violates These Principles (table)
• Relationship to Core

3. Update the matrix

If you add or change a principle, update matrix/principles-matrix.md with the derivation. A PR with a new principle but no matrix row is incomplete.

4. Update the manifest

If you add a new document, add it to MANIFEST.md in the correct section. An unlisted document is not part of the framework.

5. Add examples

If you add a principle, add at least one good example and one bad example in examples/. Examples are mandatory (Documentation P3).

6. Write a clear PR description

• What principle or document you are adding/changing.
• Why (the rationale, not just the what — Documentation P8 Why Over What).
• Which core principle(s) it derives from.
• What conflicts it might introduce (if any).

Review Criteria

Reviewers will check (see review/peer-review-checklist.md):

• Does the new principle trace to a core principle?
• Is the matrix updated?
• Is the manifest updated?
• Are there examples?
• Does the structure follow the template?
• Does it conflict with existing principles? If so, is the conflict resolvable per core/conflict-resolution.md?

Versioning

• A new domain or language doc is a minor version (e.g., v0.1 → v0.2).
• A new topic doc or example is a patch version (e.g., v0.1.0 → v0.1.1).
• A change to core/first-principles.md (adding, removing, or reordering a core principle) is a major version (e.g., v0.x → v1.0).
• See CHANGELOG.md for the version history.

License

By contributing, you agree that your contributions are licensed under the MIT license (see LICENSE).