clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'docs: document ISO versioning & release schema in AGENTS.md' (#94) from document-iso-versioning into main

Browse source 
Reviewed-on: #94
This commit is contained in:
clawdie 2026-06-21 20:37:44 +02:00
commit 67e7bef002
1 changed files with 31 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
AGENTS.md
View file

@ -4,6 +4,7 @@
**clawdie-iso** builds the operator USB image — a live FreeBSD 15 XFCE
environment that serves two roles:
- **Development surface** for Colibri: build, validate, and iterate on the
control plane from a bootable USB without touching the host OS.
- **Installer** for the **Clawdie service**: deploys Colibri as an rc.d
@ -13,20 +14,42 @@ environment that serves two roles:
The USB is the swiss-army knife — the bare-metal install is the production
target.
## Versioning & Release
The image carries its **own product version**, not one borrowed from a
component. `ISO_VERSION` is set explicitly in `build.cfg` (currently `0.11.0`,
unified with Colibri); a build with no version fails fast. The image name
derives from the FreeBSD codename and this version — e.g.
`clawdie-quindecim-0.11.0.img` (`quindecim` = FreeBSD 15, `build.sh:146`).
Component versions (clawdie-iso, clawdie-ai, colibri, zot) are **provenance**:
recorded in `build-manifest.json` as `version_scheme: "product"`. They describe
what went into the artifact; they are not its identity.
`BUILD_CHANNEL` selects the build mode:
- `dev` (default) — iteration builds; staged repos may be dirty.
- `release` — the published-artifact gate. `build.sh:check_release_gate`
requires every staged source (clawdie-iso, clawdie-ai, colibri, zot) to be a
clean tree (`git status --porcelain`, so untracked files also fail) so the
manifest's recorded commits fully describe the build. This is
reproducibility-by-record, and is separate from any future package-repo
channel (latest/quarterly/signed).
## Agent Identity and Current Role Split
The XFCE operator USB work now uses a git-coordinated split. Agents may review
or suggest across boundaries, but must coordinate explicitly before taking over
another role's load-bearing responsibility.
| Role name | Identity | Owns | Restrictions |
| ---------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Pi ISO Developer** | Pi harness (this dev agent) | Source changes, docs, static checks, commits, pushes | Does not start ISO builds or flash media unless explicitly assigned |
| **Codex ISO Builder** | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation | Focuses on targeted changes; broad source refactors require prior review; reports exact logs/output back through git or handoff notes |
| **Hermes USB/IMG Deployer** | Hermes on Debian/Linux | Downloading verified published artifacts, USB target identification, flashing | Only flashes verified artifacts to whole-disk target paths; does not need git-host access |
| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Builds ISO only through Codex ISO Builder; validates with Linux tooling; marks speculative runtime claims as such |
| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Validates on Linux and refers FreeBSD runtime claims to the build host; uses Sam-provided API keys only for provider validation |
| **Operator (Sam)** | Human operator | Product, hardware, acceptance, release judgment | Human approval required for release/tagging decisions |
| Role name | Identity | Owns | Restrictions |
| ---------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Pi ISO Developer** | Pi harness (this dev agent) | Source changes, docs, static checks, commits, pushes | Does not start ISO builds or flash media unless explicitly assigned |
| **Codex ISO Builder** | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation | Focuses on targeted changes; broad source refactors require prior review; reports exact logs/output back through git or handoff notes |
| **Hermes USB/IMG Deployer** | Hermes on Debian/Linux | Downloading verified published artifacts, USB target identification, flashing | Only flashes verified artifacts to whole-disk target paths; does not need git-host access |
| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Builds ISO only through Codex ISO Builder; validates with Linux tooling; marks speculative runtime claims as such |
| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Validates on Linux and refers FreeBSD runtime claims to the build host; uses Sam-provided API keys only for provider validation |
| **Operator (Sam)** | Human operator | Product, hardware, acceptance, release judgment | Human approval required for release/tagging decisions |
## Agent / Codebase Check-In Matrix