gravl/CLAUDE.md

CLAUDE.md — Agent Development Foundation

This document is THE foundation for developing Claude agents and autonomous systems in Gravl.
Together with the actual codebase, this is your north star.

Part 1: Agent Development Principles

1. Autonomy with Verification

• Agents execute tasks independently
• 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 + quality gates
• browser-tester — E2E testing + QA

These live in ~/clawd/claude-agents-skills/agents/ and symlink to ~/clawd/agents/.

5. Single Source of Truth

All skills and agents in ONE central repo:

• Hub location: ~/clawd/claude-agents-skills/
• Symlinks from: ~/clawd/skills/ and ~/clawd/agents/
• Commit all changes to hub repo
• Enables sharing, versioning, and collaboration

6. Communication Pattern

• PM drives autonomously
• Silence = approval (no blocking)
• Report only at milestones or blocking issues
• Use Telegram for delivery (explicit "channel: telegram")

---

Part 2: Coding Conventions (MANDATORY)

Red/Green/Refactor TDD (OBLIGATORY)

All new code follows the TDD cycle:

🔴 RED → 🟢 GREEN → 🔄 REFACTOR

Step 1: 🔴 RED - Write Failing Test First

// test/feature.test.js
describe('Feature', () => {
  it('should do expected behavior', async () => {
    const result = await feature.doSomething();
    expect(result).toBe(expected);
  });
});

Run the test - it MUST fail!

npm test -- --grep "Feature"
# ❌ FAIL (this is correct!)

Step 2: 🟢 GREEN - Minimal Implementation

Write just enough code to pass the test:

// src/feature.js
export function doSomething() {
  return expected; // Minimal solution
}

Run the test again:

npm test -- --grep "Feature"
# ✅ PASS

Step 3: 🔄 REFACTOR - Improve

Now you can:

• Refactor for clean code
• Extract functions
• Improve naming
• Remove duplication

Run tests continuously:

npm test
# ✅ All tests must still pass

Test Structure

/workspace/gravl/
├── src/
│   └── components/
├── server/
│   └── routes/
└── test/
    ├── unit/           # Unit tests
    ├── integration/    # API tests
    └── e2e/            # End-to-end (Playwright)

Naming Conventions

Test Files

• [feature].test.js — Unit tests
• [feature].integration.test.js — Integration tests
• Describe block: Noun (what is tested)
• It block: "should [verb] [expected outcome]"

Commits

test: add failing test for [feature]
feat: implement [feature] to pass tests
refactor: clean up [feature] implementation

Agent Workflow (Step-by-Step)

When spawned with a coding task:

1. Read the spec → Check docs/current-task.md
2. Write failing test → Show to PM that you understand the requirement
3. Implement code → Make the test pass (minimal solution)
4. Refactor → Clean code if needed
5. Run full test suite → Ensure nothing broke
6. Commit with proper prefix → test:, feat:, refactor:
7. Report to PM → Include git log, test results
8. Verification → PM checks git status, git log, diffs

---

Part 3: Operations

Cron Jobs (3 Active)

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

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

Repository Structure

/workspace/gravl/
├── frontend/              # React app
├── backend/               # Express API
├── db/                    # Database setup + migrations
├── scripts/               # Automation scripts
├── docker/                # Compose files
├── test/                  # Test suites
├── docs/
│   └── CODING-CONVENTIONS.md  # (Deprecated, see CLAUDE.md)
├── README.md              # Project overview
├── CLAUDE.md              # THIS FILE — Agent & coding foundation
└── .gitignore             # Excludes node_modules, planning docs

Local-Only Files (Not in Git)

These stay on disk but excluded 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 planning work locally.

---

Part 4: Agent Development Workflow

Adding a New Agent

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

Example SOUL.md:

# My Agent SOUL

## Core Identity
- Name: [Agent Name]
- Expertise: [Domain]
- Personality: [Vibe]

## Instructions
1. [Guideline 1]
2. [Guideline 2]

## Communication
- Report at milestones
- Verify before completion

Adding a New Skill

1. Create in hub: ~/clawd/claude-agents-skills/skills/my-skill/
2. Write SKILL.md (documentation, usage, examples)
3. Add code/scripts
4. Symlink automatically created: ~/clawd/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. ONLY THEN update checkpoint
echo '{
  "lastRun": "'$(date -Iseconds)'",
  "status": "completed",
  "result": "Summary..."
}' > checkpoint.json

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

---

Key Decisions

1. Generalized agents — Reusable, maintainable, shareable
2. Single hub repo — Centralized versioning
3. Symlinks for discovery — OpenClaw finds everything automatically
4. TDD mandatory — Red → Green → Refactor
5. Verification protocol — No hallucinations allowed
6. Checkpoint-based recovery — Self-healing cron jobs
7. Telegram delivery — Explicit channel routing

---

PM Agent Playbook (30-minute cycles)

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

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

---

References

• Agent Symlink Hub: ~/clawd/claude-agents-skills/
• Frontend Stack: React + Vite + Tailwind
• Backend Stack: Express + PostgreSQL
• Testing: Jest (unit), Playwright (E2E)
• Database: PostgreSQL with migrations
• Deployment: Docker Compose (local), staging via Traefik

---

Last Updated: 2026-03-02
Version: 1.0
Audience: All Claude agents, PM, developers

Remember: This document is your north star. Follow it. Extend it. Improve it.

---

Part 5: Git Hygiene - Keep the Repo Clean

No "Fix" Commits

❌ NEVER commit fixes for typos, syntax errors, or accidentally added files:

# BAD - Creates noise in history:
commit 1a2b3c: feat: add feature
commit 1a2b3d: fix: typo in feature  ← NO!
commit 1a2b3e: chore: remove extra file  ← NO!

✅ INSTEAD: Use interactive rebase to clean up BEFORE pushing:

# GOOD - Clean, single commit:
commit 1a2b3c: feat: add feature (with typo fixed)

Interactive Rebase Workflow

1. Check recent commits:

git log --oneline -5
# abc1234 feat: add feature
# def5678 fix: typo in feature        ← Oops!
# ghi9012 chore: remove extra file    ← Oops!

2. Rebase the last 3 commits:

git rebase -i HEAD~3

3. Edit in your editor:

pick abc1234 feat: add feature
squash def5678 fix: typo in feature
squash ghi9012 chore: remove extra file

Change pick to squash (or s) for commits you want to merge into the previous one.

4. Save and edit the commit message: The editor will ask for a final commit message. Edit it to be clean:

feat: add feature

- Added feature X
- Removed extra file

5. Force-push (only if not yet pushed):

git push -f origin branch-name

When to Rebase

• ✅ Before first push — Fix typos, add forgotten files
• ✅ Before review — Squash "work in progress" commits
• ❌ After pushed to shared branch — Don't force-push to main/develop

Common Rebase Scenarios

Fix a typo in last commit:

git commit --amend
# Edit the file, save
# Git updates the commit without a new one

Reorder commits:

git rebase -i HEAD~3
# Reorder the lines in the editor

Combine last 2 commits:

git rebase -i HEAD~2
# Change second line from "pick" to "squash"

Rule of Thumb

One logical change = One commit

If you're writing a commit message that says "fixed typo from previous commit", you should have rebased instead.