clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-iso/AGENTS.md
Sam & Claude da3f06f7da docs: rename 'fake-agent' → 'sample-agent' (matches colibri test rename) 
Harness-neutral, lighter wording for the optional local test-double agent
(colibri-test-agent), matching the colibri-side fake→sample rename. Only the
two references that named it 'fake-agent' (build.cfg comment, AGENTS.md
staging note); the unrelated /tmp/fake-usb example path in FIRSTBOOT.md is a
different context and left as-is.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-23 18:20:55 +02:00

284 lines
15 KiB
Markdown
Raw Permalink Blame History

# Clawdie ISO Agent Guidelines
## Project Identity
**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
service on bare FreeBSD hardware (ZFS RAID1 mirror, PostgreSQL + pgvector,
bhyve VMs, Bastille jails).
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 |
## Agent / Codebase Check-In Matrix
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, 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
- Coordinate through git: fetch before commenting on remote state, push small
reviewable commits, and include test/build status in commit messages.
- Claude may push critique/suggestion commits, but Pi ISO Developer should
re-check and adjust implementation details before the next build target is
treated as final.
- Codex ISO Builder consumes pushed build targets, builds/publishes artifacts,
and reports hardware findings with exact commands and output.
- Hermes USB/IMG Deployer consumes published artifact URLs/manifests, verifies
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 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
to the owning role instead of running it opportunistically.
### Markdown Formatting Gate
Markdown formatting is tool-owned, not taste-owned. Before pushing any commit
that edits `*.md`, run:
```sh
./scripts/check-format.sh
```
If it fails, format only the touched markdown files, then rerun the check:
```sh
npx --yes prettier@3 --write path/to/file.md
```
Use Prettier for all Markdown formatting; rely on tool-owned formatting
rather than manual alignment. `.prettierrc` uses
`proseWrap: preserve` so existing prose line breaks stay intentional, while
Prettier still catches table padding, list spacing, and emphasis drift.
### Private Planning Workspace
`private/` is gitignored and may contain operator-private strategy notes or PRDs.
Agents on this host may read files there only when directly relevant to the
assigned work. Keep private content in `private/`; share to Forgejo only with
explicit operator approval.
If working on custom ISO / hardware-report monetization, check
`private/PRD-CUSTOM-ISO.md` when present. Codex ISO Builder should focus first
on the local-only `hw-report` feasibility path and, after analysis,
return concise action notes for Claude Reviewer / XFCE Tweaker on what GUI
surface should expose for report collection and review.
### Linux Agent Constraints
Linux agents route all ISO builds to Codex ISO Builder on the FreeBSD
host. ISO builds require FreeBSD system tools (`mdconfig`, `mount_msdosfs`,
`pkg`). Instead, guide Codex ISO Builder with exact commands to run on the
FreeBSD system.
Agents on any platform start ISO builds only when explicitly assigned.
Builds are long-running, mutate repo-local caches, and can leave mounted md(4)
devices that require cleanup.
### Colibri Dependency
The ISO build stages FreeBSD-native Colibri control-plane artifacts from the
canonical `/home/clawdie/ai/colibri` checkout (`FEATURE_COLIBRI=YES` is the default
lane). The staging is wired into `build.sh` and `scripts/stage-colibri-iso.sh`;
the ISO does **not** build Rust while the image is mounted.
- Build Colibri release artifacts on the FreeBSD/OSA host, not on Debian/Linux.
- Build order, binary verification, and cleanup timing live in the `iso-build`
skill (§Colibri artifact preflight).
- Staging layout (installed paths, rc.d, directory ownership) is owned by
Colibri `docs/ISO-INTEGRATION-PLAN.md`.
- Production-image preflight requires the core Colibri set:
`colibri-daemon`, `colibri`, and `colibri-mcp`. `colibri-tui` is optional in
staging code but desired for this USB target and should be verified alongside
the required binaries. Validation images can add the local sample-agent helper
with `COLIBRI_STAGE_TEST_AGENT=YES`.
**Invariant:** preserve `/home/clawdie/ai/colibri/target/release` until the ISO
preflight/build has consumed it; run `cargo clean` only after the ISO build
completes successfully.
---
## Current XFCE Operator USB Baseline
The active branch target is the XFCE live operator USB. Authoritative state
lives in `packages/` (what ships) and `PLAN-OPERATOR-USB-NEXT.md` (round-scope
decisions and any "for now" retention notes). Final graphical validation
requires real hardware — treat bhyve, nested VMs, and static image
inspection as build gates only; real hardware is the final proof that
SDDM/XFCE works.
---
## System Configuration
**Privilege model:** distinguish build-host administration from live-USB runtime.
- On the FreeBSD build host, operator-facing commands may use `sudo`.
- Inside the live USB, `sudo` is intentionally absent.
- Live privileged actions use FreeBSD `mac_do` via `mdo -u root <command>`.
- Agent runtime code uses the hostd RPC layer for privileged host changes,
routing through the hostd RPC layer instead of shelling out to `sudo`.
---
## Scratch / Temporary Files Policy
Agents must use the project-local scratch workspace for repo work instead of
system-global `/tmp` paths. Treat the repo root as `$PROJECT_ROOT` and use:
```sh
PROJECT_ROOT=$(git rev-parse --show-toplevel)
PROJECT_TMP="$PROJECT_ROOT/tmp"
mkdir -p "$PROJECT_TMP"
```
Create all scratch files under `$PROJECT_TMP` for generated checks, transient
logs, extracted manifests, image-inspection notes, helper-script test output,
and other disposable files. Use host-global `/tmp` paths only when the operator
explicitly asks for a scratch location outside the repo.
Live-USB runtime code usually has no git checkout/project root. In that case,
prefer an app-owned cache/state path such as `$XDG_CACHE_HOME/clawdie`,
`$HOME/.cache/clawdie`, `/var/cache/clawdie`, or `/var/db/clawdie` rather than
`/tmp`. If a runtime helper supports both modes, it should use `$PROJECT_ROOT/tmp`
when a project root is detectable and fall back to the app-owned live path.
Known platform/tooling exceptions should stay narrow and documented: Xorg's
standard `/tmp/.X11-unix` / `/tmp/.X*-lock`, bsdinstall handoff files, and the
installer handoff below.
### Installer Temp Files Exception
The GUI installer uses `/tmp/clawdie-install.conf` to pass wizard values to
`firstboot.sh`. This is the narrow historical exemption from the project-local
`tmp/` rule.
**Rationale:**
- Live ISO has no project root during the installer handoff
- Single-user install phase (no other users on the system)
- File is consumed once by `firstboot.sh` then deleted on reboot
- PF firewall is not yet running during install
**Applies only to:**
- `/tmp/clawdie-install.conf` — GUI wizard config output
- `/tmp/clawdie-firstboot.*` — firstboot progress and log (written by rc.d)
## Repo-local ISO Build Workspace
ISO builds use repo-local `tmp/` for large caches and output artifacts:
- `tmp/cache` — build cache
- `tmp/cache/mnt` — temporary md(4) work-image mountpoint
- `tmp/output` — generated `.img.xz` artifacts and checksums
- `tmp/packages` — fetched package archives
`tmp/cache/mnt` is an ISO-builder-specific mountpoint exception. Use `tmp/`
mounts only for ISO builder work (cache/mnt); mount unrelated datasets,
recovery filesystems, or scratch filesystems elsewhere. If a build is
interrupted, use the `iso-build-cleanup` skill before retrying.
---
## Cross-Repo Coordination
Clawdie spans three repos. Changes often require coordinated updates.
| Repo | Purpose | Remote |
| ------------- | ---------------------------------------- | --------------------------------------------------- |
| `Clawdie-AI` | Agent runtime, control plane, channels | `git@code.smilepowered.org:clawdie/clawdie-ai.git` |
| `clawdie-iso` | ISO builder, firstboot wizard, installer | `git@code.smilepowered.org:clawdie/clawdie-iso.git` |
| `Colibri` | Cross-platform Rust control plane core | `git@code.smilepowered.org:clawdie/colibri.git` |
Primary remote: `code.smilepowered.org` (self-hosted Forgejo, SSH via local host
config). Treat `code.smilepowered.org` as the source of truth for agent
coordination and branch-state claims; Codeberg is the public mirror only.
When changes span both repos, create a handoff doc in the secondary repo
listing what needs updating. See `Clawdie-AI/AGENTS.md` for full protocol.
---
## Agent Handoff Documents
Use ephemeral handoff files to transfer context between agents.
- **Name:** `doc/<FEATURE>-HANDOFF.md` or `<FEATURE>-HANDOFF.md` (repo root)
- **Lifecycle:** Create when handing off, delete when complete
- **Structure:** Must include task checklist, deletion criteria, results section
See `Clawdie-AI/AGENTS.md` for the full handoff template and protocol.
---
## Attribution in Commit History
Use attribution in commit messages, not in code comments.
Labels:
- `Sam & Codex` — changes made by Sam and Codex
- `Sam & Claude` — changes made by Sam and Claude
- `C&C` — joint change with equal credit for Claude and Codex
Add the label to the commit subject or body. Example:
```
Fix bhyve preflight checks (C&C)
```
Reference in a new issue View git blame Copy permalink