Clawdie AI
a521ec77ff
Systematic review of all doc/, docs/internal/, docs/public/, ARCHITECTURE.md,
and README.md against recent codebase changes. 16 files updated:
Cross-cutting fixes (multiple files):
- Model references: anthropic/claude-3-5-sonnet → zai/glm-5-turbo (4 files)
- Port references: hardcoded 3100 → CONTROLPLANE_API_PORT (3 files)
- Skills mechanism: --no-skills + --append-system-prompt + skills_search (6 files)
- CONTROLPLANE_SHARED_SECRET: documented in security, architecture, install (5 files)
- Prompt guardrails: AGENT_MAX_INBOUND_CHARS etc. added to 3 files
- controlplane is NOT a jail — runs on host (3 files corrected)
- git jail added to layouts and IP tables (3 files)
- npm run → just (2 files)
Specific fixes:
- .env.example: AGENT_SESSION_MAX_BYTES session rollover hint
- README.md: fix IP layout (git=.6 not .4), add run-*.sh generation note
- ARCHITECTURE.md: add config vars, recipe count update, --no-skills
- doc/CONTROLPLANE-AGENT-ROLES.md: fix model, remove deleted file ref
- doc/CONTROLPLANE-ARCHITECTURE.md: port params, security, guardrails section
- doc/CONTROLPLANE-MESSAGE-CONTRACT.md: auth header, skills catalog rewrite
- doc/SESSION-HANDOFF-2026-04-18.md: fix Telegram (plain text not Markdown)
- doc/THREE-BIRD-ARCHITECTURE.md: fix 5 broken STRAPI-FREEBSD-GOTCHA refs
- doc/HANDOFF-PHASE7.md: mark sysprompt cleanup as done
- docs/internal/DOCUMENTATION.md: just CLI, tracked hooks, parameterized paths
- docs/internal/HEARTBEAT.md: add controlplane heartbeat reference, fix setup step
- docs/public/architecture/controlplane.md: phases 2-7 all ✅ DONE
- docs/public/architecture/freebsd-jail-implementation.md: git jail, Forgejo
- docs/public/architecture/warden.md: controlplane=host, git jail added
- docs/public/operate/monitoring.md: just doctor, all guardrail vars
- docs/public/operate/security.md: API auth, shell injection, guardrails
Build: pass | Tests: not run (Linux) (Sam & Claude)
5.1 KiB
5.1 KiB
Control Plane Agent Roles
Organization
┌──────────────────────────────────────────────┐
│ Control Plane: clawdie │
│ Host-based (integrated with clawdie service) │
│ Daily Token Budget: 100,000 │
└──────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───▼────┐ ┌──────▼─────┐ ┌─────▼─────┐
│ Orch. │ │ Sysadmin │ │ DBA │
│ 80% │ │ 10% daily │ │ 5% on-dmd │
│ on-dmd │ │ daily+on-d │ │ │
└────────┘ └────────────┘ └───────────┘
│
┌───▼──────────┐
│ Git Admin │
│ 5% on-demand │
└───────────────┘
Orchestrator / Coordinator — Primary Decision-Maker
Agent ID: coordinator
Identity: .agent/identities/COORDINATOR.md
Adapter: pi-local, model: zai/glm-5-turbo
Jail: ctrl-worker (when CONTROLPLANE_JAIL_ISOLATION=YES)
- Primary decision-maker and coordinator
- Reviews work, prioritizes tasks, delegates to specialists
- Approves architectural decisions
- Wakes on-demand only (no timer heartbeat)
- Budget: 80% (80,000 tokens)
Sysadmin — Systems Administrator
Agent ID: sysadmin
Identity: .agent/identities/SYSADMIN.md
Adapter: pi-local, model: zai/glm-5-turbo
Jail: host (no jail — needs privileged bastille/zfs/pf access)
- Monitor jail health, manage services, handle incidents
- Daily heartbeat (86400s) + on-demand
- Budget: 10% (10,000 tokens)
Skill patterns:
| Task Pattern | Skill |
|---|---|
| "Check if X jail is running" | jail-status |
| "How much free disk?" | disk-usage |
| "System health?" | system-stats |
| "Restart X service" | service-restart |
| "Back up the database" | backup-db |
| "Create ZFS snapshot" | zfs-snapshot |
| No match | Escalate to orchestrator |
DBA — Database Administrator
Agent ID: db-admin
Identity: .agent/identities/DB_ADMIN.md
Adapter: pi-local, model: zai/glm-5-turbo
Jail: db-worker (when CONTROLPLANE_JAIL_ISOLATION=YES)
- PostgreSQL operations: migrations, backups, performance tuning
- On-demand only (no timer heartbeat)
- Budget: 5% (5,000 tokens)
Skill patterns:
| Task Pattern | Skill |
|---|---|
| "Run vacuum on X" | db-vacuum |
| "Analyze the database" | db-analyze |
| "Apply migrations" | db-migrate |
| "Check replication lag" | db-sync-check |
| "Back up database" | backup-db |
| No match | Escalate to orchestrator |
Git Admin — Git Administrator
Agent ID: git-admin
Identity: .agent/identities/GIT_ADMIN.md
Adapter: pi-local, model: zai/glm-5-turbo
Jail: git-worker (when CONTROLPLANE_JAIL_ISOLATION=YES)
- Manage repositories, branches, releases, merges
- On-demand only (no timer heartbeat)
- Budget: 5% (5,000 tokens)
Skill patterns:
| Task Pattern | Skill |
|---|---|
| "Merge PR X into Y" | git-merge |
| "Tag version X" | git-release-tag |
| "Push to mirror" | git-push-mirror |
| "Pull from origin" | git-pull |
| "Protect branch" | git-branch-protect |
| No match | Escalate to orchestrator |
Approval Workflows
Orchestrator cannot approve own escalations. Flow:
Agent proposes → Operator (Sam) approves/denies → Execute/Halt
Budget limit reached → Control plane pauses work → Operator must approve increase.
Skills Mechanism
--no-skills disables pi's built-in skill discovery; skills are injected as a compact index via --append-system-prompt from agent/library.yaml; full content served on-demand through the skills_search extension tool.
References
doc/CONTROLPLANE-ARCHITECTURE.md— service architecture (incl. jail isolation section)doc/CONTROLPLANE-MESSAGE-CONTRACT.md— API contracts.agent/identities/— agent identity files (injected as system prompt)src/controlplane-runner.ts—AGENT_JAIL_MAP,resolveAgentJail(), skill index injectionsrc/skill-library.ts—getAgentSkillIndex()provides compact skill summariessrc/skills-discovery.ts— task-to-skill pattern matching vialibrary.yaml