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

docs(iso): clean builder handoff terminology (Sam & Codex) #64

Merged
clawdie merged 1 commit from docs/clean-builder-handoff-terminology into main 2026-06-15 18:52:17 +02:00
Conversation 0 Commits 1 Files changed 8 +56 -51
8 changed files with 56 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
AGENTS.md
View file

@ -6,14 +6,14 @@ The XFCE operator USB work now uses a git-coordinated split. Agents may review
or suggest across boundaries, but should not silently take 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 | Should avoid broad source refactors; 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 | Does not need git-host access; never flashes unverified artifacts or partition paths |
| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Cannot build ISO, cannot run FreeBSD-only validation, should mark speculative runtime claims as such |
| **Opencode / Z.ai Integrator** | Opencode CLI on Linux | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane smoke wiring | Cannot claim FreeBSD runtime proof; 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 | Should avoid broad source refactors; 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 | Does not need git-host access; never flashes unverified artifacts or partition paths |
| **Claude Reviewer / XFCE Tweaker** | Claude (Linux) | Review/plans plus Track E XFCE GUI polish | Cannot build ISO, cannot run FreeBSD-only validation, should mark 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 | Cannot claim FreeBSD runtime proof; 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
@ -21,14 +21,14 @@ Use this as the lightweight "who checks in where" matrix while work spans
multiple repos. Pushed commits, mounted-image reports, manifests, or explicit
handoff docs are the expected check-in surface.
| Agent lane / identity | Primary codebase(s) | Typical check-in artifact |
| ------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------- |
| **Pi ISO Developer** | `clawdie-iso` | Small pushed commit on active branch plus static-check result |
| **Codex ISO Builder** | `/home/clawdie/ai/clawdie-iso`, `/home/clawdie/ai/colibri` | Build log, mounted-image sweep, publish manifest, smoke notes |
| **Hermes USB/IMG Deployer** | published ISO artifacts | Checksum/manifest verification plus flash-target confirmation |
| **Claude Reviewer / Tweaker** | `clawdie-iso` | Review/GUI-polish commit or explicit handoff note |
| **Opencode / Z.ai Integrator** | `clawdie-ai`, `colibri` | Provider smoke output, small manifest, or handoff doc |
| **Operator (Sam)** | all three repos | Final acceptance note, branch choice, release/publish approval |
| Agent lane / identity | Primary codebase(s) | Typical check-in artifact |
| ------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| **Pi ISO Developer** | `clawdie-iso` | Small pushed commit on active branch plus static-check result |
| **Codex ISO Builder** | `/home/clawdie/ai/clawdie-iso`, `/home/clawdie/ai/colibri` | Build log, mounted-image sweep, publish manifest, validation notes |
| **Hermes USB/IMG Deployer** | published ISO artifacts | Checksum/manifest verification plus flash-target confirmation |
| **Claude Reviewer / Tweaker** | `clawdie-iso` | Review/GUI-polish commit or explicit handoff note |
| **Opencode / Z.ai Integrator** | `clawdie-ai`, `colibri` | Provider validation output, small manifest, or handoff doc |
| **Operator (Sam)** | all three repos | Final acceptance note, branch choice, release/publish approval |
### Git Coordination Rules
@ -43,7 +43,7 @@ handoff docs are the expected check-in surface.
checksums on Linux, identifies the USB target, and owns the final image-to-USB
deployment handoff.
- Opencode / Z.ai Integrator owns Linux-side Colibri/dashboard experiments and
the Pi/DeepSeek v4 smoke lane when Sam provides a `ZAI_API_KEY`; findings
the Pi/DeepSeek v4 validation lane when Sam provides a `ZAI_API_KEY`; findings
should come back as exact commands, output, provider/version notes, and small
manifests/summaries that Colibri can ingest.
- If a change needs a long ISO build, USB flash, or real hardware proof, hand it
@ -104,7 +104,7 @@ the ISO does **not** build Rust while the image is mounted.
skill (§Colibri artifact preflight).
- Staging layout (installed paths, rc.d, directory ownership) is owned by
Colibri `docs/ISO-INTEGRATION-PLAN.md`.
- Required by ISO preflight: `colibri-daemon`, `colibri`, `colibri-smoke-agent`,
- Required by ISO preflight: `colibri-daemon`, `colibri`, `colibri-test-agent`,
and `colibri-mcp`.
`colibri-tui` is optional in staging code but desired for this USB target and
should be verified alongside the required binaries.

38
PLAN-OPERATOR-USB-NEXT.md
View file

@ -144,7 +144,7 @@ This round does **not** ship a full installer. It sets up the plumbing.
will later pull `pkg-list-kde.txt`; not creating that file yet).
3. **Hook from `firstboot.sh`.** Call the new function after base
firstboot completes, before `clawdie_shell_deploy_*` runs.
4. **Bhyve smoke test.** A shell script under `scripts/` that boots the
4. **Bhyve validation test.** A shell script under `scripts/` that boots the
built image in bhyve, runs the disk-install path with
`CLAWDIE_PROFILE=xfce`, and asserts `blender` (the roadmap-essential
member of disk-install-extras) ends up installed on the target disk.
@ -225,15 +225,15 @@ contract between agents.
**Manifest surfaces:**
| Surface | Example skill / script | Schema target | Purpose |
| ------------------ | ------------------------------ | ---------------------------------- | ----------------------------------------------------- |
| Build result | `iso-build` | `clawdie.iso.build.v1` | Commit, flags, log path, output files, static checks |
| Publish result | `iso-publish` | `clawdie.iso.publish.v1` | Public URLs, checksums, manifest path, symlink state |
| Flash verification | `iso-flash-verify` | `clawdie.iso.flash.v1` | Download, checksum, xz test, target disk fit, flash |
| Mounted validation | `iso-validate-image` | `clawdie.iso.validation.v1` | SDDM, CLIs, `mdo`, seed slice, no-blank, panel assets |
| Hardware report | `iso-hardware-report-ingest` | `clawdie.iso.hardware.v1` | GPU/KMS, GL renderer, input, audio, Wi-Fi, SDDM/XFCE |
| Package audit | `iso-package-audit` | `clawdie.iso.package-audit.v1` | Category, size, flat size, reason kept, deferral risk |
| Provider smoke | `pi-provider-smoke` equivalent | `clawdie.provider-smoke.result.v1` | Pi JSONL events, provider/model identity, pass/fail |
| Surface | Example skill / script | Schema target | Purpose |
| ------------------- | ------------------------------ | ---------------------------------- | ----------------------------------------------------- |
| Build result | `iso-build` | `clawdie.iso.build.v1` | Commit, flags, log path, output files, static checks |
| Publish result | `iso-publish` | `clawdie.iso.publish.v1` | Public URLs, checksums, manifest path, symlink state |
| Flash verification | `iso-flash-verify` | `clawdie.iso.flash.v1` | Download, checksum, xz test, target disk fit, flash |
| Mounted validation | `iso-validate-image` | `clawdie.iso.validation.v1` | SDDM, CLIs, `mdo`, seed slice, no-blank, panel assets |
| Hardware report | `iso-hardware-report-ingest` | `clawdie.iso.hardware.v1` | GPU/KMS, GL renderer, input, audio, Wi-Fi, SDDM/XFCE |
| Package audit | `iso-package-audit` | `clawdie.iso.package-audit.v1` | Category, size, flat size, reason kept, deferral risk |
| Provider validation | `pi-provider-check` equivalent | `clawdie.provider-smoke.result.v1` | Pi JSONL events, provider/model identity, pass/fail |
**Key architectural decisions:**
@ -687,15 +687,15 @@ split:
Role definitions are canonical in `AGENTS.md`. This table only maps those
roles to this round:
| Role | Owns in this round |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pi ISO Developer** | Primary source implementation: shell scripts, validation hooks, package-list mechanics, docs updates, static checks, commits and pushes. |
| **Codex ISO Builder** | Build + flash + validate on Intel and AMD after each build target lands. Runs mounted-image checks, the validation script, USB flashing, and NVIDIA validation when hardware arrives. Reports exact logs/output back through git or handoff notes. |
| **Claude Reviewer / XFCE Tweaker** | Reviews plans/diffs, identifies blind spots, owns Track E XFCE GUI tweaks, and reviews the ISO manifest surface for Colibri compatibility. |
| **Opencode (z.ai-GLM4.7)** | Owns Linux-side Colibri/dashboard experiments and the GLM-4.7/DeepSeek provider smoke lanes. Reports results as manifests/summaries. GLM-4.7 transport already proven (this session runs on it); DeepSeek uses Sam's own key with `--provider deepseek`. |
| **Pi + DeepSeek v4** | Provider-lane validation target: prove `pi --mode json` works against DeepSeek v4 with Sam's DeepSeek API key, report provider/model identity, and hand exact command/output back before anyone treats the lane as production-ready. |
| **Codex (FreeBSD endpoint)** | Build/validate endpoint for ISO manifests: runs skills on FreeBSD, emits exact build/hardware results, and keeps `watchdog`/`hostd` as local safety boundaries. |
| **Operator (Sam)** | Final product direction, hardware purchases, hands-on acceptance, release/tag decisions, and NVIDIA/portable-workstation UX judgment. |
| Role | Owns in this round |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pi ISO Developer** | Primary source implementation: shell scripts, validation hooks, package-list mechanics, docs updates, static checks, commits and pushes. |
| **Codex ISO Builder** | Build + flash + validate on Intel and AMD after each build target lands. Runs mounted-image checks, the validation script, USB flashing, and NVIDIA validation when hardware arrives. Reports exact logs/output back through git or handoff notes. |
| **Claude Reviewer / XFCE Tweaker** | Reviews plans/diffs, identifies blind spots, owns Track E XFCE GUI tweaks, and reviews the ISO manifest surface for Colibri compatibility. |
| **Opencode (z.ai-GLM4.7)** | Owns Linux-side Colibri/dashboard experiments and the GLM-4.7/DeepSeek provider validation lanes. Reports results as manifests/summaries. GLM-4.7 transport already proven (this session runs on it); DeepSeek uses Sam's own key with `--provider deepseek`. |
| **Pi + DeepSeek v4** | Provider-lane validation target: prove `pi --mode json` works against DeepSeek v4 with Sam's DeepSeek API key, report provider/model identity, and hand exact command/output back before anyone treats the lane as production-ready. |
| **Codex (FreeBSD endpoint)** | Build/validate endpoint for ISO manifests: runs skills on FreeBSD, emits exact build/hardware results, and keeps `watchdog`/`hostd` as local safety boundaries. |
| **Operator (Sam)** | Final product direction, hardware purchases, hands-on acceptance, release/tag decisions, and NVIDIA/portable-workstation UX judgment. |
Cross-agent handoff: use git as the shared control plane. Suggestion commits are
welcome, but each build target should be re-fetched and checked before build.

2
TESTING.md
View file

@ -336,7 +336,7 @@ sudo mdconfig -d -u md0
bhyve is an **on-demand** verification lane, not a per-change gate — it's slow and
needs the ML350p, so run it when you want boot/runtime confidence before
committing to physical hardware, not on every iteration. The cheap gates that run
every change are the static checks (`sh -n`, the staging smoke) and `cargo test`.
every change are the static checks (`sh -n`, staging self-tests) and `cargo test`.
When you do run it, treat bhyve as authoritative for boot/runtime plumbing and
still treat real hardware as the final authority for GPU, panel, input, Wi-Fi,

5
build.cfg
View file

@ -18,7 +18,7 @@ BUILD_CHANNEL="${BUILD_CHANNEL:-dev}" # dev | release
# Output image
# User-facing operator image format:
# clawdie-<desktop>-<freebsd-codename>-usb-DD.MM.YY.img
# clawdie-<freebsd-codename>-<iso-version>.img
#
# USB KEY SIZING GUIDE:
# 32GB USB → IMAGE_SIZE="28G" (current fast-iteration default)
@ -28,8 +28,7 @@ BUILD_CHANNEL="${BUILD_CHANNEL:-dev}" # dev | release
# Current validation target: 32GB-class USB sticks.
# Raise IMAGE_SIZE manually when the workflow shifts back to larger media.
IMAGE_SIZE="28G"
# build.sh derives IMAGE_NAME from desktop, the FreeBSD major-version codename,
# and the build date.
# build.sh derives IMAGE_NAME from the FreeBSD codename and ISO_VERSION.
# Clawdie-AI ref to bundle from Forgejo.
# Use main for install validation so ISO firstboot exercises the current

4
docs/POUDRIERE-BUILD-SERVER.md
View file

@ -229,9 +229,9 @@ This gives us:
- `colibri`
- `colibri-daemon`
- `colibri-tui`
- `colibri-smoke-agent`
- `colibri-test-agent`
- `colibri-mcp`
- `colibri-tui` (optional in current raw-binary staging, desired for operator USB)
All with proper pkg metadata, upgradeable, with dependencies tracked.

2
packages/pkg-list-xfce.txt
View file

@ -20,7 +20,7 @@ adwaita-icon-theme-legacy
gtk-update-icon-cache
shared-mime-info
desktop-file-utils
# Keep xterm as a tiny canonical Xorg rescue/smoke-test client. If startx is
# Keep xterm as a tiny canonical Xorg rescue/validation client. If startx is
# invoked without a working xinitrc, Xorg defaults to xterm rather than failing
# with "Unable to run program xterm".
xterm

2
scripts/test-release-gate.sh
View file

@ -47,4 +47,4 @@ _release_errors=0; assert_clean_repo modified "${modified}"; check "${_release_e
_release_errors=0; assert_clean_repo nogit "${TMP}/does-not-exist"; check "${_release_errors}" 0 "non-git path is skipped"
[ "${fail}" -eq 0 ] && echo "PASS: release gate smoke test" || { echo "FAILED"; exit 1; }
[ "${fail}" -eq 0 ] && echo "PASS: release gate self-test" || { echo "FAILED"; exit 1; }

18
skills/iso-build/SKILL.md
View file

@ -150,15 +150,21 @@ cargo build --workspace --release
ls -lh target/release/colibri-daemon \
target/release/colibri \
target/release/colibri-smoke-agent \
target/release/colibri-mcp \
target/release/colibri-tui
target/release/colibri-test-agent \
target/release/colibri-mcp
file target/release/colibri-daemon \
target/release/colibri \
target/release/colibri-smoke-agent \
target/release/colibri-mcp \
target/release/colibri-tui
target/release/colibri-test-agent \
target/release/colibri-mcp
# Optional in the staging script, but desired for this operator USB target.
if [ -x target/release/colibri-tui ]; then
ls -lh target/release/colibri-tui
file target/release/colibri-tui
else
echo "WARN: optional colibri-tui artifact is missing"
fi
target/release/colibri --help | head
```