gravl/CLAUDE.md

CLAUDE.md — Agent Development Guidelines

This is the foundation for developing Claude agents and autonomous systems in the Gravl ecosystem.

Core Principles

1. Autonomy with Verification

• Agents execute tasks independently (autonomy)
• Always verify results after delegation (no hallucinations)
• Verification pattern: git status, git log, ls, diff before checkpoint update
• Never report completion without checking actual work

2. Checkpoint-Based Self-Monitoring

All long-running tasks use checkpoint files:

{
  "lastRun": "2026-03-02T08:00:00Z",
  "status": "completed|blocked|interrupted|error",
  "result": "Summary of work",
  "nextCheck": "What to do next"
}

Recovery logic:

• If lastRun > 60min OR status ≠ "completed" → trigger recovery
• Log recovery attempts to help debugging
• Use simple JSON for checkpoint files (no complex parsing)

3. PM (Project Manager) Autonomy

The Gravl PM agent:

• Plans sprints/phases autonomously
• Spawns specialized agents (frontend-dev, backend-dev, etc.)
• Verifies their work before checkpoint completion
• Reports progress to Telegram (not silent failures)
• Timeout: 15 minutes (900s) per cron cycle

4. Generalized Agents (Reusable)

Never create project-specific agents.

Use generalized agents instead:

• frontend-dev — React/CSS specialist
• backend-dev — Node.js/PostgreSQL specialist
• architect — System design
• reviewer — Code review
• browser-tester — E2E testing + QA

These are in ~/clawd/claude-agents-skills/agents/ and symlinked to ~/clawd/agents/.

5. Single Source of Truth

All skills and agents live in ONE central repo:

• Hub location: ~/clawd/claude-agents-skills/
• Symlinks from: ~/clawd/skills/ and ~/clawd/agents/
• Commit everything to hub repo
• This enables sharing, versioning, and collaboration

Development Workflow

Adding a New Agent

1. Create in hub: ~/clawd/claude-agents-skills/agents/my-agent/
2. Write SOUL.md (agent definition + personality)
3. Optional: Add README.md, scripts, config
4. Symlink automatically created: ~/clawd/agents/my-agent → hub/agents/my-agent
5. Commit to hub repo

Adding a New Skill

1. Create in hub: ~/clawd/claude-agents-skills/skills/my-skill/
2. Write SKILL.md (how to use it)
3. Add code/scripts as needed
4. Symlink automatically created: ~/clawd/skills/my-skill → hub/skills/my-skill
5. Commit to hub repo

Verification Pattern (CRITICAL)

After any subagent completes work:

# 1. Check git status
git status

# 2. Verify files changed
git log --oneline -3

# 3. Inspect actual changes
git diff HEAD~1

# 4. THEN update checkpoint
echo '{"status":"completed",...}' > checkpoint.json

This prevents hallucination bugs where agents claim work they didn't do.

Communication

Report-Only Pattern

• PM drives autonomously
• Silence = approval (no blocking)
• Only report at milestones or blocking issues
• Use Telegram for delivery (channel: telegram)

Cron Jobs (3 active)

Job	Schedule	Timeout	Checkpoint
Gravl PM	Every 30m	15 min	/workspace/gravl/.pm-checkpoint.json
Vietnam Flights	Daily 09:00	2 min	~/.checkpoint-vietnam-flights.json
System Updates	Daily 10:00	5 min	~/.checkpoint-system-updates.json

All use explicit "channel: telegram" for Telegram delivery.

Code Conventions

See CODING-CONVENTIONS.md for:

• Frontend (React, CSS)
• Backend (Express, PostgreSQL)
• Database (schema, migrations)
• Testing (Playwright, E2E)

Repository Structure

/workspace/gravl/
├── frontend/          # React app
├── backend/           # Node.js API
├── db/                # Database setup
├── scripts/           # Automation
├── docker/            # Compose files
├── docs/
│   └── CODING-CONVENTIONS.md  # Technical standards
├── README.md          # Project overview
├── CLAUDE.md          # This file (agent guidelines)
└── .gitignore         # Excludes planning docs, node_modules

Local-Only Files (Not in Git)

These stay on disk but are excluded from .git via .gitignore:

• .planning/ — research, requirements, roadmap
• TODO.md — task tracking
• frontend/tasks/ — feature tasks
• docs/plans/ — planning notes

This keeps the repo clean while preserving your planning work locally.

Key Decisions

1. Generalized agents over project-specific — More reusable, easier to maintain
2. Single hub repo — Centralized versioning + easy sharing
3. Symlinks for discovery — OpenClaw finds skills/agents automatically
4. Verification protocol — Prevents hallucination bugs
5. Checkpoint-based recovery — Self-healing cron jobs
6. Telegram for delivery — Explicit channel to avoid missed messages

For the PM Agent

The Gravl PM uses this playbook:

1. Plan phase → Identify tasks, delegate to specialized agents
2. Execute phase → Spawn agents, monitor progress
3. Verify phase → Check git status, diffs, logs (NO HALLUCINATIONS)
4. Report phase → Send Telegram update with result or blocking issue
5. Checkpoint phase → Update checkpoint.json with status + nextCheck

PM runs every 30 minutes autonomously. No human approval needed unless blocked.

---

Last Updated: 2026-03-02
Version: 1.0
For questions: Check specific agent SOUL.md or skill SKILL.md files