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:

```json
{
  "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:

```bash
# 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