atelier/.ciagent/atelier/PROJECT.md

Atelier — Project Vision

Objective

Build Atelier — a first-principles, docs-as-code engineering framework for AI agents and humans, organized as a hierarchical document tree: core → domains → languages → review → matrix → examples. Each domain defines its own first principles derived from a small set of core principles, with every rule traced back via a principles matrix. The framework is consumed by AI agents as pre-completion guidance and by humans as engineering canon.

Core Value

Principles over rules. A small set of universal core principles (Correctness, Clarity, Simplicity, Locality, Reversibility, Composability, Observability, Economy) govern every domain. Domain rules derive from these and never contradict them. The principles matrix is the connective tissue — no domain rule is orphaned, and conflicts resolve upward to core.

Requirements

• Hierarchical document tree: core/, domains/, languages/, review/, matrix/, examples/
• core/first-principles.md — 8 universal principles (C1–C8)
• core/conflict-resolution.md — formal cross-document conflict rules
• core/reading-order.md — recommended consumption order
• 11 domain folders, each with first-principles.md (P1–P10) plus derived docs
• Domains: uiux, api, security, data, testing, performance, observability, errors, documentation, concurrency, devops
• UI/UX derived: components, accessibility, tokens, copywriting
• API derived: rest, graphql, versioning, error-responses, pagination
• Security derived: authentication, authorization, input-validation, secrets, supply-chain
• Data derived: schema-design, migrations, indexing
• Testing derived: pyramid, fixtures
• Performance derived: frontend, backend
• Observability derived: logging, metrics, tracing
• Errors derived: patterns
• Documentation derived: doc-templates
• Concurrency derived: patterns
• DevOps derived: ci-cd, environments
• matrix/principles-matrix.md — every domain P-rule → core C-rule mapping
• matrix/domain-coverage.md — where each principle applies
• review/agent-checklist.md — pre-completion checklist for agents
• review/peer-review-checklist.md — human review checklist
• review/anti-patterns.md — catalog of violations
• examples/good/* and examples/bad/* — worked examples
• languages/*.md — language-specific application (typescript, python, go, rust, ...)
• MANIFEST.md — authoritative index (unlisted = not part of framework)
• README.md, LICENSE, CHANGELOG.md, CONTRIBUTING.md

Constraints

• Docs-as-code: versioned, reviewed, tested, owned (Documentation P1)
• Every domain principle MUST trace to a core principle via the matrix
• The manifest is authoritative — unlisted documents are not part of the framework
• Security principles are non-tradeable (8 of 10 are never sacrificed)
• Manifest reading order: core first-principles → core conflict-resolution → domain first-principles → domain topic → matrix reference
• No runtime code — Atelier is a documentation-only framework

Out of Scope

• Tooling to enforce the rules (linters, analyzers) — future work
• Translation/localization of the framework docs
• Automated agent integration adapters beyond markdown consumption
• Versioned per-domain release artifacts (the whole framework versions together)
• Runtime code (terraform manifests, k8s YAML, deployable artifacts) — Atelier remains docs-only. Examples under examples/iac/ and examples/k8s/ are illustrative markdown (rendered manifests in code fences), never deployed.

v0.2 — Infrastructure as Code + Kubernetes

Milestone type: NFR (all phases produce docs — no feat runtime code) Tag line: v0.1.x (previous minor from v0.2) Scope: Extend the domain tree with two new top-level domains covering IaC tooling and the Kubernetes platform, plus matrix, review, and examples integration.

New Domains

• domains/infrastructure-as-code/ — tooling domain
  • first-principles.md — 10 IaC principles (P1–P10)
  • Derived: terraform.md, opentofu.md, state.md, modules.md
• domains/kubernetes/ — platform domain
  • first-principles.md — 10 k8s principles (P1–P10)
  • Derived: workloads.md, networking.md, storage.md, rbac.md, helm.md, kustomize.md

Cross-Domain Integration

• Extend matrix/principles-matrix.md with 20 new P-rules → core C-rule mappings (10 per new domain)
• Extend matrix/domain-coverage.md with the two new domains
• Extend review/agent-checklist.md and review/anti-patterns.md with IaC/k8s checks/violations
• Update MANIFEST.md to list all new documents (manifest is authoritative)
• New examples: examples/good/terraform-module.md, examples/good/k8s-deployment.md, examples/bad/ counterparts
• Cross-links from new domains to existing devops/, security/, observability/, data/ domains

v0.3 — GitOps + Operators + AI/ML + i18n + Compliance

Milestone type: NFR (all phases produce docs — no feat runtime code) Tag line: v0.2.x (previous minor from v0.3) Scope: Extend the domain tree with four new top-level domains covering GitOps/operator patterns, AI/ML, internationalization, and compliance. Plus matrix, review, examples, and cross-link integration. All content is docs-only markdown with illustrative code fences; no runtime/deployable artifacts.

New Domains

• domains/gitops-operators/ — platform-automation domain (ArgoCD + Flux + Operators)
  • first-principles.md — 10 GitOps/operator principles (P1–P10)
  • Derived: argocd.md, flux.md, operators.md, progressive-delivery.md
• domains/ai-ml/ — ML engineering domain
  • first-principles.md — 10 AI/ML principles (P1–P10)
  • Derived: data-versioning.md, model-evaluation.md, serving.md, monitoring-drift.md
• domains/i18n/ — internationalization domain
  • first-principles.md — 10 i18n principles (P1–P10)
  • Derived: locale-resources.md, formatting.md, rtl-bidi.md, testing-i18n.md
• domains/compliance/ — compliance/audit domain
  • first-principles.md — 10 compliance principles (P1–P10)
  • Derived: audit-logs.md, data-retention.md, policy-as-code.md, evidence.md

Cross-Domain Integration

• Extend matrix/principles-matrix.md with 40 new P-rules → core C-rule mappings (10 per new domain)
• Extend matrix/domain-coverage.md with the four new domains
• Extend review/agent-checklist.md, review/peer-review-checklist.md, and review/anti-patterns.md with new domain sections
• Update MANIFEST.md to list all new v0.3 documents (manifest is authoritative)
• New examples (good + bad): gitops-pr, ai-ml-reproducibility, i18n-string-concat, compliance-audit-log
• Cross-links from new domains to existing devops/, security/, observability/, data/, kubernetes/, infrastructure-as-code/ domains

Phase Plan (proposed, finalized in PLAN)

• P0 Pre-Execution: spec, clarify, research, ideate, plan, grill
• P1 GitOps + Operators domain
• P2 AI/ML domain
• P3 i18n + Compliance domains
• P4 Matrix + Review Integration (40 new mappings, manifest, checklist parity)
• P5 Examples + Cross-Links
• P6 Final Review + Ship (IS the v0.3 release → tag v0.2.6)

NFR milestone: no separate minor tag. The final patch (v0.2.6) IS the v0.3 deliverable.

Key Decisions

ID	Decision	Rationale	Confidence
D-001	MIT license (deferred to P1)	Not pasted in spec; standard permissive choice for docs frameworks	0.70
D-002	Defer README/CHANGELOG/CONTRIBUTING to execute phase	Referenced in spec tree but content not pasted	0.80
D-003	core/* first-principles deferred to P1	Referenced as "already drafted" but not pasted	0.70
D-004	domains/uiux/first-principles.md deferred to P2	Referenced as "already drafted" but not pasted	0.70
D-005	examples/, languages/, review/, matrix/domain-coverage.md deferred to later phases	Execute-phase deliverables per spec build order	0.90
D-006	GITEA_API_TOKEN as token env var name	Matches existing /root/.ciagent/config.json convention	0.80
D-007	Milestone v0.1 (user override)	User explicitly required first milestone = v0.1, not v1.0	0.95
D-008	6 execution phases (P1–P6) + final phase P7	Mirrors spec Part 6 "Recommended Build Order"	0.88
D-009	NFR milestone type (all phases are docs/chore)	Every phase produces markdown docs, no feat code; NFR patch-line versioning	0.92
D-010	Tags run on v0.0.x patch line (prev minor from v0.1)	Per branch-strategy.md: milestone 0.1 → tags v0.0.0..v0.0.7	0.90
D-011	v0.2 adds two new top-level domains: infrastructure-as-code + kubernetes	User directive to incorporate terraform/opentofu + kubernetes; two-domain split reflects tool-vs-platform distinction	0.90
D-012	v0.2 remains docs-only (NFR milestone type)	PROJECT.md constraint "no runtime code" preserved; manifests appear only as illustrative code-fence content in examples	0.95
D-013	v0.2 tags run on v0.1.x patch line (prev minor from v0.2)	Per branch-strategy.md: milestone 0.2 → tags v0.1.0..v0.1.5; v0.1.5 IS the v0.2 release (NFR → no separate minor tag)	0.90
D-014	Add phase-specific platform-engineer persona for P1–P4	IaC/k8s domain authoring benefits from a specialist persona with declarative-first/stateless-examples constraints; removed after milestone	0.82
D-015	4 execution phases (P1–P4) + final phase P5	P1 IaC domain, P2 k8s domain, P3 matrix+review, P4 examples+cross-links, P5 final review+ship	0.85
D-016	v0.3 covers 4 deferred domains: gitops-operators, ai-ml, i18n, compliance	Carries forward v0.2 deferred ideation (IDEATE-15, IDEATE-16); single milestone groups them to limit release overhead	0.86
D-017	v0.3 tags run on v0.2.x patch line (prev minor from v0.3)	Per branch-strategy.md: milestone 0.3 → tags v0.2.0..v0.2.6; v0.2.6 IS the v0.3 release (NFR → no separate minor tag)	0.90
D-018	v0.3 splits P1 GitOps/Operators, P2 AI/ML, P3 i18n+Compliance, P4 Matrix+Review, P5 Examples, P6 Final	Each domain cluster is a coherent vertical slice; i18n + compliance paired (smaller surface) to balance phase load	0.84
D-019	Reuse platform-engineer persona (extended) + add ml-engineer phase-specific persona for P2	GitOps/Operators/k8s reuse platform-engineer; AI/ML benefits from a data/ML-specialist persona with reproducibility/data-lineage constraints; removed after milestone	0.80
D-020	v0.3 remains docs-only (NFR milestone type)	PROJECT.md constraint "no runtime code" preserved; manifests/models/locale resources appear only as illustrative code-fence content in examples	0.95
D-021	GitOps-operators domain groups ArgoCD + Flux + Operators + Progressive Delivery under one first-principles doc	All four share the declarative-source-of-truth reconciliation loop; splitting would fragment the P-rules and duplicate the core principles they trace to	0.84
D-022	i18n + compliance paired in P3 (not separate phases)	Both are smaller-surface domains (4 derived docs each); pairing balances phase load against the heavier P1/P2 single-domain phases	0.83
D-023	AI/ML domain scope = engineering discipline (data versioning, evaluation, serving, drift), NOT algorithm/model design	Atelier is a framework for engineering practice; algorithm choice is domain-knowledge out of scope. Mirrors how iac/k8s docs cover practice not implementation	0.88
D-024	Compliance domain is framework-agnostic (audit logs, retention, policy-as-code, evidence), NOT tied to a specific regulation (GDPR/HIPAA/SOC2)	Regulation-specific docs would bloat the framework and go stale; principles derive from core Security/Correctness and apply across regulations	0.86
D-025	Examples set = 2 good + 2 bad (not 4+4)	v0.3 adds 4 domains; 4+4 examples would unbalance P5. 2 good (gitops-pr, ai-ml-reproducibility) + 2 bad (i18n-string-concat, compliance-audit-log) cover the highest-illustration-value cases; remaining domains covered by cross-links and anti-patterns	0.80
D-026	40 new matrix mappings (10 per domain × 4 domains)	Consistent with v0.1 (110 mappings / 11 domains = 10) and v0.2 (20 mappings / 2 domains = 10). Each P-rule maps to ≥1 C-rule	0.92
D-035	Add examples/ directory listing to MANIFEST.md in v0.3 P4 (ATELIER-91)	v0.2 audit escalation ESC-002 note flagged examples/ unlisted; manifest is authoritative, so this is pre-existing drift that v0.3 closes	0.85
D-036	Matrix coverage summary must state post-v0.3 totals (17 domains, 170 P-rules)	Both the summary block and per-domain section count must update; consistent with v0.2's "post-v0.2" summary	0.93
D-037	domain-coverage.md Core Principle Coverage table (C1–C8 → domains) must update for 4 new domains	ATELIER-81 covers the per-domain row schema; this is the complementary C-rule → domains table that also needs the 4 new domains	0.90
D-038	v0.3 anti-patterns must pre-specify domain-specific violations + v0.3 artifact types	Avoids generic "deployable example artifact" only; v0.3 has new artifact types (.po, .rego, model files) and 4 domains × ~4 anti-patterns each	0.86
D-039	ArgoCD vs Flux decision matrix required in argocd.md + flux.md	Parallel to v0.2 Helm vs Kustomize decision matrix (IDEATE-10); both tools share the GitOps model but differ in architecture (App CRD vs composable controllers)	0.82
D-040	Data versioning tool comparison table required in data-versioning.md (DVC/Delta Lake/LakeFS)	Parallel to v0.2 state comparison table (IDEATE-11); three主流 tools with distinct versioning/lineage models	0.80
D-041	Policy-as-code engine comparison table required in policy-as-code.md (OPA/Cedar/Kyverno/Sentinel)	Parallel to v0.2 PSS coverage (IDEATE-12); four engines with distinct policy languages and gate models	0.81
D-042	GitOps push-pattern is a named anti-pattern (violates P3 Pull Don't Push)	Chaos scenario: a "GitOps" example that uses push-based deploy is a fundamental violation; pre-specify to reject on sight	0.85
D-043	i18n LTR-only assumption is a named anti-pattern (violates P6 Text Direction)	Chaos scenario: formatting/layout examples that assume LTR only fail RTL/bidi users; pre-specify to reject	0.83
D-044	compliance-audit-log bad example must cover both append-only violation (P1) and redaction failure (P9)	Two-breach example maximizes illustration value; mirrors v0.2 named-bad-example pattern but doubles the breach surface for the highest-stakes domain	0.87
D-045	AI/ML orphan-model anti-pattern required (deployed prediction with no lineage trace, violates P3)	Chaos scenario: a serving example with no model→training→data lineage is the AI/ML analog of v0.2 orphaned P-rule; pre-specify	0.84
D-046	i18n testing-i18n.md must map pseudo-locale testing to testing pyramid tiers	Avoids generic "test i18n" guidance; maps to unit (missing-key), integration (snapshot per locale), e2e (RTL coverage)	0.78
D-047	compliance evidence.md must include a fenced signed-attestation example (Cosign or in-toto)	Prose-only evidence guidance is weak; a fenced example demonstrates the principle concretely (P6 Evidence Collected Continuously)	0.80
D-048	ai-ml monitoring-drift.md must enumerate 3 drift types (data/concept/prediction) with a detection signal per type	Avoids conflating drift types; each has distinct detection signals and retraining triggers	0.82
D-049	P3 splits Wave 2 into 2a (i18n) + 2b (compliance) labels but both are the same dependency tier	8 derived docs are all independent post-Wave-1; 2a/2b labels organize by domain, executor schedules ≤5 concurrent per config.json. Avoids inventing a false dependency between i18n and compliance	0.88
D-050	P4 Wave 2 runs exactly 5 concurrent tasks (at the max_concurrent_agents cap)	matrix, coverage, agent-checklist, peer-review-checklist, anti-patterns, manifest = 6 extensions, but anti-patterns (04-02-04) and manifest (04-02-05) are combined under lead-developer for manifest to sequence after anti-patterns content is settled. Net 5 concurrent slots	0.82
D-051	P5 ai-ml-reproducibility.md example authored by tech-writer with ml-engineer consultation (not ml-engineer primary)	ml-engineer is removed after P2 per PERSONAS.md; P5 examples are tech-writer territory. ml-engineer constraints are baked into the task must-have (P1/P2/P3/P5 demonstrated) so the constraint survives the persona	0.80
D-052	P6 review uses platform-engineer + ml-engineer for content review before removal	Phase-specific personas review their authored content one final time in P6 Wave 1, then are removed in 06-01-04. Ensures D-023 (ai-ml scope) and GitOps correctness are checked by the specialist before the roster returns to 3	0.84
D-053	Vertical-slice integrity: each phase is independently shippable	P1 ships gitops-operators domain docs (matrix rows land in P4 — acceptable because the domain is self-consistent; matrix extension is the traceability closure, not a blocker for the domain's internal consistency). P3 ships 2 domains together (D-022). P4 closes traceability + manifest. P5 closes examples + cross-links. P6 ships the release	0.86

Cross-Project References

None yet. Atelier is a standalone docs framework.

Milestone History

• v0.1 — Initial Framework (COMPLETE). 8 core principles, 11 domains, 110 domain principles, full matrix, 4+3 examples, 4 languages. Tag v0.0.7.
• v0.2 — Infrastructure as Code + Kubernetes (COMPLETE). Adds 2 domains (20 new P-rules), matrix/review/examples integration. Tags v0.1.0–v0.1.5; v0.1.5 is the v0.2 release.
• v0.3 — GitOps + Operators + AI/ML + i18n + Compliance (COMPLETE). Adds 4 domains (40 new P-rules), matrix 130→170 across 13→17 domains, review/checklist/anti-patterns integration, 4 new examples, MANIFEST examples/ listing (closes ESC-002). Tags v0.2.0–v0.2.6; v0.2.6 is the v0.3 release.