Skip to content

Commit ad7b3ea

Browse files
ebourgeoisebourgeois
authored
5-Spot is now ADD - Architecture Driven Developed
Added initial, simple workshop Signed-off-by: Erick Bourgeois <erick@jeb.ca>
1 parent ba0c6ed commit ad7b3ea

12 files changed

Lines changed: 810 additions & 0 deletions

‎.claude/CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,37 @@ The format is based on the regulated environment requirements:
99

1010
---
1111

12+
## [2026-05-31 00:00] - Adopt Architecture Driven Development (ADD) methodology
13+
14+
**Author:** Erick Bourgeois
15+
16+
### Changed
17+
- `docs/adr/`: new directory for Architecture Decision Records —
18+
`template.md`, `README.md` (conventions + index), and
19+
`0001-adopt-architecture-driven-development.md` (Accepted) recording the
20+
adoption decision and rationale.
21+
- `.claude/rules/architecture-driven-development.md`: new rule file defining the
22+
ADD methodology (`ADR → CALM → TDD → implement → docs`), adapted to 5-Spot
23+
(`src/crd.rs` source of truth, `make crds`/`crddoc`, CALM targets,
24+
`cargo-quality`/`sync-docs`, roadmaps external at `~/dev/roadmaps/`).
25+
- `.claude/CLAUDE.md`: added ADD as the governing methodology (new section + as
26+
the first "CRITICAL Coding Pattern"); links to the rule file and ADR-0001.
27+
- `.claude/SKILL.md`: added an ADD gate to the top of `pre-commit-checklist`
28+
(ADR written/indexed; CALM updated or "no CALM impact"; ADR precedes code).
29+
30+
### Why
31+
5-Spot already had strong TDD and a CALM model, but no first-class, ordered way
32+
to record *why* an architecturally significant change was made before building
33+
it. ADD (per the sibling banlieue project) layers ADR + CALM on top of TDD so
34+
decisions are auditable and traceable — fitting the regulated context — instead
35+
of reconstructed from diffs and changelog entries. See ADR-0001.
36+
37+
### Impact
38+
- [ ] Breaking change
39+
- [ ] Requires cluster rollout
40+
- [ ] Config change only
41+
- [x] Process / documentation only
42+
1243
## [2026-05-30 12:00] - Revert docs deploy trigger to release:published (CodeQL: pwn-request + cache poisoning)
1344

1445
**Author:** Erick Bourgeois

‎.claude/CLAUDE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
> **Project Focus**: Time-based scheduling of physical machines in k0smotron clusters. This controller manages machine lifecycle (add/remove from cluster) based on configurable time schedules with timezone support.
77
>
88
> **CRITICAL Coding Patterns**:
9+
> - **Architecture Driven Development (ADD)**: For any architecturally significant change, architecture is decided, recorded, and visualized BEFORE code: `ADR → CALM → TDD → implement → docs`, in that order. ADRs (`docs/adr/`) and CALM diagrams are first-class deliverables, equal to code and tests. Full rule: `.claude/rules/architecture-driven-development.md`. ADD wraps TDD below — it does not replace it.
910
> - **Test-Driven Development (TDD)**: ALWAYS write tests FIRST before implementing functionality. Write failing tests that define the expected behavior, then implement code to make tests pass. This ensures all code is testable and has comprehensive test coverage from the start.
1011
> - **Event-Driven Programming**: In Kubernetes controller development, ALWAYS use event-driven programming (e.g., "watch" on kube API) as opposed to polling. Controllers must react to cluster state changes efficiently.
1112
> - **Early Returns**: Use as few `else` statements as possible. Return from functions as soon as you can to minimize nesting and improve code clarity (see Early Return / Guard Clause Pattern section).
@@ -14,6 +15,25 @@
1415
1516
---
1617

18+
## 🏛️ GOVERNING METHODOLOGY: Architecture Driven Development (ADD)
19+
20+
**5-Spot is built ADR-first. Architecture is decided, recorded, and visualized BEFORE code.** For any architecturally significant change, follow this order — full details in `.claude/rules/architecture-driven-development.md`:
21+
22+
```
23+
ADR → CALM → TDD → implement → docs
24+
```
25+
26+
1. **ADR** — record the decision in `docs/adr/NNNN-title.md` (Status / Context / Decision / Consequences) from `docs/adr/template.md`; update the index in `docs/adr/README.md`.
27+
2. **CALM** — model it in `docs/architecture/calm/architecture.json`; `make calm-validate` + `make calm-diagrams`. *(Process-only decisions have no CALM impact — say so in the ADR and skip this step.)*
28+
3. **TDD** — only then write failing tests, then the minimum implementation (`tdd-workflow` skill); `cargo-quality` gate.
29+
4. **Docs** — CHANGELOG (`**Author:**`) + affected `docs/src/`; `sync-docs`.
30+
31+
ADRs and CALM diagrams are **first-class deliverables, equal to code and tests.** ADD applies to new CRDs / CRD-field contract changes, controllers/reconcilers/binaries, changes to the CAPI interaction (Machine / bootstrap / infrastructure contract, allowed API groups), deploy/admission/GitOps topology, and cross-cutting security / RBAC / scheduling concerns. Typos, isolated bug fixes, and behavior-preserving refactors are **TDD-only**. **When unsure whether a change is architectural, write the ADR.**
32+
33+
> See ADR [0001](../docs/adr/0001-adopt-architecture-driven-development.md) for the adoption decision and rationale.
34+
35+
---
36+
1737
## ⚙️ Claude Code Configuration
1838

1939
### 🚨 CRITICAL: Always Verify CRD Schema Sync

‎.claude/SKILL.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,12 @@ done
293293

294294
**Checklist:**
295295

296+
### If the change is architecturally significant (ADD — do FIRST):
297+
See `.claude/rules/architecture-driven-development.md`. Applies to new CRDs / CRD-field contract changes, controllers/reconcilers/binaries, CAPI-interaction changes, deploy/admission/GitOps topology, and security/RBAC/scheduling concerns.
298+
- [ ] ADR written/updated in `docs/adr/NNNN-*.md` (Status/Context/Decision/Consequences) and indexed in `docs/adr/README.md`
299+
- [ ] CALM model updated, `make calm-validate` + `make calm-diagrams` pass — OR the ADR states "no CALM impact (process-only)"
300+
- [ ] ADR was written BEFORE the implementation (ADR → CALM → TDD order)
301+
296302
### If ANY `.rs` file was modified:
297303
- [ ] Tests updated/added/deleted to match changes (TDD — see `tdd-workflow`)
298304
- [ ] All new public functions have tests

‎.claude/rules/architecture-driven-development.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Architecture Driven Development (ADD)
2+
3+
> **ADD is the governing methodology for 5-Spot.** Architecture is designed,
4+
> recorded, and visualized **before** code is written. ADRs and CALM diagrams
5+
> are first-class deliverables — equal in importance to the code and the tests.
6+
7+
ADD layers *on top of* the existing TDD discipline; it does not replace it. The
8+
order is fixed:
9+
10+
```
11+
ADR → CALM → TDD → implement → docs
12+
```
13+
14+
## The ADD cycle
15+
16+
For any **architecturally significant** change, complete each step before
17+
starting the next:
18+
19+
### 1. ADR — decide and record (FIRST)
20+
21+
Write or update an Architecture Decision Record in
22+
`docs/adr/NNNN-title.md` (lowercase-hyphen, zero-padded sequential number)
23+
using `docs/adr/template.md`, with the standard sections:
24+
25+
- **Status** — Proposed → Accepted (→ Superseded by NNNN)
26+
- **Context** — the forces, constraints, and the problem being solved
27+
- **Decision** — what we will do, stated plainly
28+
- **Consequences** — trade-offs, follow-ups, what this rules out
29+
30+
ADRs are kept **in the repo** (unlike roadmaps, which live outside it at
31+
`~/dev/roadmaps/`). One decision per ADR. If a change reverses an earlier ADR,
32+
mark the old one *Superseded* and link forward. Keep the index in
33+
`docs/adr/README.md` current.
34+
35+
### 2. CALM — model and visualize
36+
37+
Update the FINOS CALM architecture model
38+
(`docs/architecture/calm/architecture.json`) to reflect the decision: nodes,
39+
relationships, interfaces, controls, and flows. Then:
40+
41+
```sh
42+
make calm-validate # architecture conforms to the meta-schema (hard gate)
43+
make calm-diagrams # regenerate Mermaid diagrams into docs/src/architecture/
44+
```
45+
46+
The architecture must be modeled and the diagrams must render cleanly **before**
47+
implementation begins. A change that isn't reflected in CALM isn't designed yet.
48+
49+
> **Process-only decisions** (e.g. adopting a methodology, CI policy) have **no
50+
> CALM impact** — CALM models the running system (controller, `ScheduledMachine`
51+
> CRD, CAPI/provider resources, flows), not the development process. Say so
52+
> explicitly in the ADR's Consequences and skip step 2.
53+
54+
### 3. TDD — red / green / refactor
55+
56+
Only now write code, **tests first**, per the `tdd-workflow` skill: failing test
57+
→ minimum implementation → refactor. Tests go in separate `_tests.rs` files
58+
(`src/foo.rs` → `#[cfg(test)] mod foo_tests;` → `src/foo_tests.rs`). After any
59+
`.rs` change, run the `cargo-quality` skill (fmt + clippy + test — all must pass).
60+
61+
CRD shape changes start in `src/crd.rs` (the source of truth), then regenerate:
62+
`regen-crds` skill (`make crds`) → update `examples/` → `regen-api-docs`
63+
(`make crddoc`, LAST). Never hand-edit `deploy/crds/*.yaml`.
64+
65+
### 4. Docs
66+
67+
Update `.claude/CHANGELOG.md` (with `**Author:**`) and any affected `docs/src/`
68+
pages / examples. Run the `sync-docs` skill to verify docs match the code.
69+
70+
## When does ADD apply?
71+
72+
**Full ADR + CALM** (architecturally significant):
73+
74+
- New CRDs / CRD fields that change a contract, new controllers, reconcilers, or binaries
75+
- Changes to how 5-Spot interacts with CAPI (Machine / bootstrap / infrastructure contract, allowed API groups)
76+
- New deploy / admission / GitOps topology (e.g. ValidatingAdmissionPolicy posture, child-cluster routing)
77+
- Cross-cutting concerns: security boundaries, RBAC posture, failure domains, scheduling semantics
78+
- Any decision where "why A over B" is worth recording
79+
80+
**ADR only, no CALM** (process / policy, no system-topology change):
81+
82+
- Methodology, CI/CD policy, repository conventions
83+
84+
**TDD only** (no ADR/CALM needed):
85+
86+
- Typos, comment/doc tweaks, formatting
87+
- Isolated bug fixes with no architectural impact
88+
- Mechanical refactors that preserve behavior and structure
89+
90+
> When unsure whether a change is "architectural," **write the ADR.** A short,
91+
> slightly-redundant ADR costs little; an undocumented architectural decision
92+
> costs the next person a re-derivation.
93+
94+
## Checklist (paste into the work)
95+
96+
- [ ] ADR written/updated in `docs/adr/NNNN-*.md` (Status/Context/Decision/Consequences); index in `docs/adr/README.md` updated
97+
- [ ] CALM model updated; `make calm-validate` passes; `make calm-diagrams` renders — **or** ADR states "no CALM impact (process-only)"
98+
- [ ] Tests written **first**, then implementation (TDD); CRD changes regenerated via `regen-crds` → `regen-api-docs`
99+
- [ ] `cargo-quality` passes (fmt + clippy + test)
100+
- [ ] CHANGELOG (`**Author:**`) + docs updated; `sync-docs` clean

‎docs/adr/0001-adopt-architecture-driven-development.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<!--
2+
Copyright (c) 2026 Erick Bourgeois, 5-Spot
3+
SPDX-License-Identifier: Apache-2.0
4+
-->
5+
# 0001 — Adopt Architecture Driven Development (ADD)
6+
7+
- **Status:** Accepted
8+
- **Date:** 2026-05-31
9+
- **Deciders:** Erick Bourgeois
10+
- **Supersedes:** —
11+
- **Related:** `.claude/rules/architecture-driven-development.md`; CALM model at `docs/architecture/calm/architecture.json`; the existing TDD discipline in `.claude/CLAUDE.md`.
12+
13+
## Context
14+
15+
5-Spot already enforces strong **Test-Driven Development** (tests first, separate
16+
`_tests.rs` files, `cargo-quality` as a hard gate) and already maintains a
17+
**FINOS CALM** architecture model with `make calm-validate` / `make
18+
calm-diagrams`. What it lacked was an explicit, ordered methodology tying the
19+
*decision*, the *model*, and the *code* together — and a durable home for the
20+
"why A over B" reasoning behind architecturally significant changes.
21+
22+
Several recent changes illustrate the gap. The RBAC anti-escalation design (VAP
23+
`authorizer` checks for the requesting user + a controller-side
24+
`SelfSubjectAccessReview`), the embedded-`metadata` policy (reject
25+
`name`/`namespace`, allow reserved-prefix-checked `labels`/`annotations`), and
26+
the child-cluster Node-routing model were all real architectural decisions with
27+
non-obvious trade-offs. They were captured in the changelog and code comments,
28+
but there was no first-class record of the decision and the alternatives
29+
weighed — so the next contributor must re-derive the reasoning from the diff.
30+
31+
A sibling project (banlieue) adopted **Architecture Driven Development**:
32+
decisions are recorded as ADRs and modeled in CALM *before* code, on top of the
33+
existing TDD loop. The order is fixed:
34+
35+
```
36+
ADR → CALM → TDD → implement → docs
37+
```
38+
39+
The alternative — staying TDD-only and relying on the changelog plus code
40+
comments — keeps the process lighter, but leaves architectural intent scattered
41+
and reconstructed rather than stated. Given 5-Spot operates in a regulated
42+
environment where changes must be auditable and traceable to a rationale, a
43+
first-class decision log is worth the modest per-change overhead.
44+
45+
## Decision
46+
47+
We adopt **Architecture Driven Development (ADD)** as the governing methodology
48+
for 5-Spot. For any architecturally significant change, contributors complete
49+
the steps in order — **ADR → CALM → TDD → implement → docs** — before the next
50+
step begins:
51+
52+
1. **ADR** — record the decision in `docs/adr/NNNN-title.md` (Status / Context /
53+
Decision / Consequences), from `docs/adr/template.md`, indexed in
54+
`docs/adr/README.md`.
55+
2. **CALM** — reflect it in `docs/architecture/calm/architecture.json`;
56+
`make calm-validate` + `make calm-diagrams` must pass. *Process-only decisions
57+
have no CALM impact and say so.*
58+
3. **TDD** — failing tests first, then minimum implementation; `cargo-quality`
59+
gate; CRD changes regenerate via `regen-crds` → `regen-api-docs`.
60+
4. **Docs** — CHANGELOG (`**Author:**`) + affected `docs/src/`; `sync-docs` clean.
61+
62+
ADRs and CALM diagrams are first-class deliverables, equal to code and tests.
63+
The full rule lives in `.claude/rules/architecture-driven-development.md` and is
64+
referenced as the governing methodology from `.claude/CLAUDE.md`. ADD applies to
65+
new CRDs/CRD-field contract changes, controllers/reconcilers/binaries, changes
66+
to the CAPI interaction, deploy/admission/GitOps topology, and cross-cutting
67+
security/RBAC/scheduling concerns. Typos, isolated bug fixes, and behavior-
68+
preserving refactors remain TDD-only. **When unsure, write the ADR.**
69+
70+
## Consequences
71+
72+
- **Easier:** architectural intent is recorded once, at decision time, with the
73+
alternatives weighed — auditable and traceable, which suits the regulated
74+
context. New contributors read `docs/adr/` instead of re-deriving from diffs.
75+
- **Harder / slower:** a modest per-change overhead for significant work (write
76+
the ADR, touch CALM). Mitigated by scoping ADD to *architecturally
77+
significant* changes and keeping ADRs short.
78+
- **Ruled out:** silently making a significant decision in code-only form. If
79+
it's worth a "why A over B," it gets an ADR.
80+
- **Retroactive ADRs:** existing significant decisions (RBAC anti-escalation,
81+
embedded-metadata policy, child-cluster routing, `release:published` docs
82+
trigger) may be back-filled as ADRs over time; not required immediately.
83+
- **CALM impact:** **none.** This is a process decision, not a change to the
84+
running system's topology, so the CALM model is unchanged. (This ADR is itself
85+
an instance of the "process-only → no CALM" rule it establishes.)

‎docs/adr/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<!--
2+
Copyright (c) 2026 Erick Bourgeois, 5-Spot
3+
SPDX-License-Identifier: Apache-2.0
4+
-->
5+
# Architecture Decision Records
6+
7+
This directory holds 5-Spot's **Architecture Decision Records (ADRs)** — the
8+
durable log of *why* the system is shaped the way it is.
9+
10+
5-Spot follows **Architecture Driven Development (ADD)**: for any
11+
architecturally significant change, the decision is recorded here **before** code
12+
is written, then modeled in CALM, then implemented test-first. See
13+
[`.claude/rules/architecture-driven-development.md`](../../.claude/rules/architecture-driven-development.md)
14+
for the full methodology.
15+
16+
## Conventions
17+
18+
- **Filename:** `NNNN-title.md` — zero-padded sequential number, lowercase, hyphenated.
19+
- **One decision per ADR.** Copy [`template.md`](./template.md) to start.
20+
- **Status lifecycle:** `Proposed` → `Accepted` → (`Superseded by ADR-NNNN`).
21+
Never delete or rewrite a decision — supersede it and link forward.
22+
- **In the repo.** ADRs are version-controlled here. (Roadmaps and phase plans
23+
are *not* — those live outside the repo at `~/dev/roadmaps/`.)
24+
25+
## When to write one
26+
27+
Write a full ADR (and update the CALM model) for: new CRDs/CRD-field contract
28+
changes, controllers/reconcilers/binaries, changes to the CAPI interaction
29+
(Machine / bootstrap / infrastructure contract, allowed API groups), deploy /
30+
admission / GitOps topology, and cross-cutting concerns (security boundaries,
31+
RBAC posture, scheduling semantics). Process/policy decisions get an ADR with
32+
**no CALM impact**. Trivial changes (typos, isolated bugfixes, mechanical
33+
refactors) need neither. When unsure, **write the ADR.**
34+
35+
## Index
36+
37+
| ADR | Title | Status |
38+
|----:|-------|--------|
39+
| [0001](./0001-adopt-architecture-driven-development.md) | Adopt Architecture Driven Development (ADD) | Accepted |

‎docs/adr/template.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<!--
2+
Copyright (c) 2026 Erick Bourgeois, 5-Spot
3+
SPDX-License-Identifier: Apache-2.0
4+
-->
5+
# NNNN — <short decision title>
6+
7+
- **Status:** Proposed | Accepted | Superseded by ADR-NNNN
8+
- **Date:** YYYY-MM-DD
9+
- **Deciders:** <name(s)>
10+
- **Supersedes:** <ADR-NNNN, or "—">
11+
- **Related:** <ADRs, CALM nodes, docs, or "—">
12+
13+
## Context
14+
15+
The forces, constraints, and the problem being solved. What is true today, what
16+
pressure is pushing for a change, and what options were on the table. State the
17+
alternatives you weighed and why they were rejected — that is the part future
18+
readers cannot reconstruct.
19+
20+
## Decision
21+
22+
What we will do, stated plainly and in the present tense ("We use X", "Providers
23+
satisfy Y"). One decision per ADR.
24+
25+
## Consequences
26+
27+
The trade-offs this locks in: what becomes easier, what becomes harder, what is
28+
now ruled out, and any follow-up work it implies. Note CALM impact explicitly —
29+
either "CALM updated (nodes/flows …)" or "no CALM impact (process-only / no
30+
system-topology change)".

0 commit comments

Comments
 (0)