Imported from wolverin0/clawtrol (
AGENTS.md). Install upstream withnpx skills add wolverin0/clawtrol. Copyright stays with the author.
AGENTS.md - ClawTrol Operational Guide
This file is the operational source-of-truth for AI coding assistants working on ClawTrol.
1) Operational Context (Critical)
Use this map first. Most recent confusion came from editing the wrong folder.
Canonical vs mirror folders
UPDATED 2026-07-26 — Source edits remain local, while releases use the exact SHA-tagged image produced by hosted CI. The VM does not pull or build application source during a normal deployment.
| Role | Path | Status | Notes |
|---|---|---|---|
| Local working copy (primary) | G:\_OneDrive\OneDrive\Desktop\Py Apps\clawtrol |
WRITE HERE | Full clone of wolverin0/clawtrol, same remote as VM. Work locally, deploy via /deploy-to-vm. |
| VM deployment target | $HOME/.local/share/clawtrol-deploy |
Immutable image | Non-secret Compose descriptor and exact-SHA release pointer. Runtime secrets remain in the access-restricted host environment. |
| VM worktree (alternate branch) | /home/ggorbalan/factory-workspaces/clawtrol-minimax |
Secondary working copy | Git worktree of ~/clawdeck/.git. Separate branch, separate working dir. |
| Audit workspace (archived) | G:\_OneDrive\OneDrive\Desktop\Py Apps\clawtrol-workspace |
Preserved audit docs | AUDIT.md, FIX_PROMPTS.md, FEATURE_IDEAS.md, roadmap.md, obsidian-vault/, screenshots. Moved aside from clawtrol/ during the 2026-04-19 re-clone. Reference only. |
| Scratch patch dump | G:\_OneDrive\OneDrive\Desktop\Py Apps\clawdeck_remote_work |
Non-canonical | Isolated files from prior remote-work flow, not the live repo |
| Repo comparison clones (Windows) | G:\_OneDrive\OneDrive\Desktop\Py Apps\gitclones |
Reference only | For benchmarking patterns |
| Repo comparison clones (Ubuntu) | /home/ggorbalan/gitclone |
Reference only | For benchmarking patterns |
| OpenClaw workspace | /home/ggorbalan/.openclaw/workspace |
Separate project | Cognitive/memory files, not ClawTrol app code |
Runtime endpoints
- ClawTrol app URL:
http://192.168.100.186:4001 - Runtime: one Compose-managed web container; retired systemd web/worker units remain stopped.
Deploy
Use the /deploy-to-vm skill at .claude/skills/deploy-to-vm/SKILL.md. It deploys only an exact SHA image after hosted CI and restored-database migration gates pass, then requires /health to report the same SHA.
2) Mandatory Preflight Before Any Edit
All edits happen in the local clone at G:\_OneDrive\OneDrive\Desktop\Py Apps\clawtrol\. Run these checks locally in order before coding:
# 1) Confirm cwd is the local clawtrol clone
pwd && git rev-parse --show-toplevel
# Expected: .../clawtrol (NOT clawtrol-workspace, NOT clawdeck_remote_work)
# 2) Confirm origin matches the canonical repo
git remote get-url origin
# Expected: https://github.com/wolverin0/clawtrol.git
# 3) Confirm branch + dirty state + sync with origin
git branch --show-current
git status --short
git fetch origin && git status -uno # see if behind/ahead
# 4) Confirm target file exists locally
ls -la <target_path>
If pwd does not end in clawtrol OR origin is not wolverin0/clawtrol, stop and re-route. Do NOT SSH to the VM to edit. Pre-deploy verification of the VM state is handled by the /deploy-to-vm skill, not the edit preflight.
3) Documentation Source-of-Truth Policy
- Canonical roadmap lives in:
docs/roadmaps/ - Execution evidence lives in:
docs/reports/anddocs/artifacts/ - Session handoff context lives in:
handoff.md
When roadmaps conflict:
- Keep one canonical roadmap marked ACTIVE.
- Mark older files as superseded, do not delete historical context.
- Update checkbox status immediately after each completed step.
4) Project Overview
ClawTrol (formerly ClawDeck) is a Rails 8.1 mission control dashboard for AI agents.
Core capabilities:
- Task queue with board-based workflow
- Agent orchestration state (sessions, model routing, validation)
- Swarm idea launcher
- Factory loop automation
- ZeroBitch fleet controls
- Nightshift/cron orchestration
5) Architecture Snapshot
Stack
- Ruby 3.3.x / Rails 8.1
- PostgreSQL (primary/cache/queue/cable)
- Solid Queue, Solid Cache, Solid Cable
- Hotwire (Turbo + Stimulus) + Tailwind
- Puma + Nginx deployment
P0 Data Contract (Feb 2026)
tasks.description is the HUMAN BRIEF only. Agent output goes to TaskRun.
Key columns:
tasks.description— Human task brief (never mutated by agents)tasks.original_description— Backup of original brieftasks.execution_prompt— Prompt for agent execution (wasexecution_plan)tasks.compiled_prompt— Pipeline-generated prompt from ERB templatestask_runs.agent_output— Agent findings/output per runtask_runs.prompt_used— Immutable snapshot of the prompt sent to agenttask_runs.agent_activity_md— Markdown transcript summarytask_runs.follow_up_prompt— Follow-up instructions for requeue
Prompt precedence chain: compiled_prompt || execution_prompt || original_description || description || name
Reading agent output:
task.agent_output_text # reads TaskRun first, falls back to description regex
task.has_agent_output? # checks TaskRun OR description pattern
task.latest_run # most recent TaskRun
task.effective_prompt # prompt that would be sent to agent
task.description_section("Agent Output") # legacy fallback only
Key domains
Tasklifecycle:inbox -> up_next -> in_progress -> in_review -> done- Factory loops: persistent automation cycles with logs/findings
- Swarm ideas: curated launch templates that create tasks
- ZeroBitch: external fleet/agent execution surface
6) Dev Commands
Setup + run
bin/setup
bin/dev
bin/rails server
DB
bin/rails db:prepare
bin/rails db:migrate
bin/rails db:reset
Tests + quality
bin/rails test
bin/rails test:system
bin/rubocop
bin/brakeman
bin/bundler-audit
bin/ci
7) Merge Gate Baseline (Do Not Skip)
Any change intended for integration should pass:
- Lint/static checks (
rubocop, security checks where applicable) - Unit/integration tests for touched areas
- E2E/system tests for user-facing flows changed
- Route/UI smoke check for impacted endpoints
- Evidence written to
docs/artifacts/ordocs/reports/
If any gate fails, do not mark task done.
8) Collaboration Rules for Agents
- Edit code in the local clone only (
G:\_OneDrive\OneDrive\Desktop\Py Apps\clawtrol\). Never SSH-edit/home/ggorbalan/clawdeckfor non-emergency work — see.claude/rules/local-first-workflow.md. - Avoid broad refactors in dirty worktrees unless explicitly requested.
- Never use destructive git commands (
reset --hard,checkout --, force-push) unless asked. - When context is ambiguous, run the section 2 preflight before touching files.
- Prefer small reversible changes with explicit validation steps.
- Keep roadmap checkboxes updated in the same execution window.
- Ship via
/deploy-to-vm. Never pull source, build an image, or deploy a mutable tag on the VM.
9) Common Pitfalls and Fixes
Pitfall: "I changed files but app did not change"
Cause: either (a) edited the wrong folder (clawtrol-workspace/, clawdeck_remote_work/, or a gitclones/ reference clone), or (b) the exact tested SHA image was not deployed.
Fix:
- Re-run section 2 preflight; confirm
pwdends inclawtroland origin iswolverin0/clawtrol. - Require green hosted CI, then run
/deploy-to-vm <40-character-sha>and verify/healthreturns that SHA.
Pitfall: "Nav differs across pages"
Cause: duplicated nav partials drifting. Fix: update all nav partials together and verify desktop + mobile.
Pitfall: "Factory produced many commits but low trust"
Cause: missing merge gate/E2E evidence. Fix: enforce merge gate baseline before integration.
10) API/Auth Notes
- API base:
/api/v1 - Auth header:
Authorization: Bearer <token>
- Agent identity headers (when used):
X-Agent-Name: <name>X-Agent-Emoji: <emoji>
11) Related Docs
docs/AGENT_INTEGRATION.mddocs/OPENCLAW_INTEGRATION.mddocs/API_REFERENCE.mddocs/factory/ARCHITECTURE.mddocs/roadmaps/
12) Swarm/Factory/ZeroClaw (Exception Mode Only)
Default execution mode is the normal task flow:
- One task at a time
- Standard board pipeline
- Normal review and validation gates
Do not activate Swarm/Factory/ZeroClaw by default.
Activate this mode only when at least one trigger is true:
- The roadmap explicitly marks a phase as
BURST,BATCH, orPARALLEL. - There are 5+ related tasks that can be safely parallelized.
- A large refactor needs isolated playground validation before merge.
- The user explicitly asks for swarm/factory/zeroclaw execution.
When exception mode is active:
- Swarm orchestrates phases and dispatch.
- Factory runs high-volume experiments in isolated workspaces.
- ZeroClaw handles heavy parallel subtasks and returns artifacts.
Guardrail:
- Never bypass the normal merge gates.
- If exception mode is not clearly required, stay on regular task flow.
Issue Tracking with bd (beads)
IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
Why bd?
- Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
Quick Start
Check for ready work:
bd ready --json
Create new issues:
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
Claim and update:
bd update <id> --claim --json
bd update bd-42 --priority 1 --json
Complete work:
bd close bd-42 --reason "Completed" --json
Issue Types
bug- Something brokenfeature- New functionalitytask- Work item (tests, docs, refactoring)epic- Large feature with subtaskschore- Maintenance (dependencies, tooling)
Priorities
0- Critical (security, data loss, broken builds)1- High (major features, important bugs)2- Medium (default, nice-to-have)3- Low (polish, optimization)4- Backlog (future ideas)
Workflow for AI Agents
- Check ready work:
bd readyshows unblocked issues - Claim your task atomically:
bd update <id> --claim - Work on it: Implement, test, document
- Discover new work? Create linked issue:
bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
- Complete:
bd close <id> --reason "Done"
Auto-Sync
bd automatically syncs via Dolt:
- Each write auto-commits to Dolt history
- Use
bd dolt push/bd dolt pullfor remote sync - No manual export/import needed!
Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use
--jsonflag for programmatic use - ✅ Link discovered work with
discovered-fromdependencies - ✅ Check
bd readybefore asking "what should I work on?" - ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
For more details, see README.md and docs/QUICKSTART.md.
Landing the Plane (Session Completion)
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
- File issues for remaining work - Create issues for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- PUSH TO REMOTE - This is MANDATORY:
git pull --rebase bd sync git push git status # MUST show "up to date with origin" - Clean up - Clear stashes, prune remote branches
- Verify - All changes committed AND pushed
- Hand off - Provide context for next session
CRITICAL RULES:
- Work is NOT complete until
git pushsucceeds - NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
