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

docs: agent identity, cross-repo coordination, handoff convention (Sam & Claude)

Browse source
This commit is contained in:
Sam & Claude 2026-04-07 19:52:48 +02:00 • committed by 123kupola
parent 18afbae2cd
commit c153445af8
1 changed files with 42 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
AGENTS.md
View file

@ -9,6 +9,22 @@ All work goes into `clawdie-iso`. See `PLAN-UNIFY.md` for the active implementat
---
## 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)
@ -39,6 +55,32 @@ The GUI installer uses `/tmp/clawdie-install.conf` to pass wizard values to
---
## 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.