246 lines
13 KiB
Markdown
246 lines
13 KiB
Markdown
# Clawdie ISO Agent Guidelines
|
|
|
|
## 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 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 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
|
|
|
|
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
|
|
```
|
|
|
|
Do not hand-align Markdown tables or reflow prose manually. `.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. Do not commit, quote, summarize publicly, or copy private content
|
|
to Forgejo unless the operator explicitly approves it.
|
|
|
|
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 MUST NOT attempt to build the ISO (`./build.sh`, `./build-vps.sh`).
|
|
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 MUST NOT start a new ISO build unless 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 fake-agent helper
|
|
with `COLIBRI_STAGE_TEST_AGENT=YES`.
|
|
|
|
**Invariant:** do not `cargo clean` `/home/clawdie/ai/colibri` until the ISO
|
|
preflight/build has consumed `/home/clawdie/ai/colibri/target/release`.
|
|
|
|
---
|
|
|
|
## 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 — do not treat bhyve, nested VMs, or static image
|
|
inspection as 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 must not shell out to `sudo` for privileged host changes.
|
|
- Privileged Clawdie-AI host operations go through the hostd RPC layer.
|
|
|
|
---
|
|
|
|
## 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"
|
|
```
|
|
|
|
Use `$PROJECT_TMP/...` for generated checks, transient logs, extracted manifests,
|
|
image-inspection notes, helper-script test output, and other disposable files.
|
|
Do not create new `/tmp/clawdie-*`, `/tmp/colibri-*`, or ad-hoc `/tmp/...` paths
|
|
from agent work unless the operator explicitly asks for a host-global scratch
|
|
location.
|
|
|
|
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. Do not mount
|
|
unrelated datasets, recovery filesystems, or scratch filesystems elsewhere under
|
|
repo `tmp/`. 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). Codeberg is the public mirror only; do not treat it as the source of
|
|
truth for agent coordination or branch-state claims.
|
|
|
|
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)
|
|
```
|