Clawdie ISO Agent Guidelines

Repo Status

clawdie-iso is the single canonical repo for all Clawdie installation targets.

The clawdie-shell repo is being archived (read-only). Do not make new commits there. All work goes into clawdie-iso. See PLAN-UNIFY.md for the active implementation plan.

Agent Identity

Identity	Platform	Capabilities	Restrictions
Claude (Linux)	Linux dev machine	Code search, file editing, git push	Cannot build ISO, cannot test on FreeBSD
Codex / FreeBSD agent	FreeBSD host	Build ISO, test firstboot flow	Receives handoff docs
Operator (Sam)	FreeBSD host + Linux	ISO builds, deploys, final review	Human — all commits require approval

Linux Agent Constraints

The Linux agent MUST NOT attempt to build the ISO (./build.sh, ./build-vps.sh). ISO builds require FreeBSD system tools (mdconfig, mount_msdosfs, pkg). Instead, guide the operator with exact commands to run on the FreeBSD system.

System Configuration

Privilege escalation: Unified on sudo (not doas)

All documentation uses sudo
Admin panel uses sudo for privileged operations
Agents should use sudo in examples and commands

Unified ISO: Single image works on VPS, baremetal, and cloud

Runtime detection handles configuration (display, GPU, desktop)
No build-time target selection needed

Installer Temp Files

The GUI installer uses /tmp/clawdie-install.conf to pass wizard values to firstboot.sh. This is an exemption from the project-local tmp/ rule.

Rationale:

Live ISO has no project root
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 to:

/tmp/clawdie-install.conf — GUI wizard config output
/tmp/clawdie-firstboot.* — firstboot progress and log (written by rc.d)

Cross-Repo Coordination

Clawdie spans two repos. Changes often require coordinated updates.

Repo	Purpose	Remote
`Clawdie-AI`	Agent runtime, control plane, channels	`git@codeberg.org:Clawdie/Clawdie-AI.git`
`clawdie-iso`	ISO builder, firstboot wizard, installer	`git@codeberg.org:Clawdie/Clawdie-ISO.git`

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)

3.2 KiB Raw Blame History