# 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:

```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 + 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

```javascript
// 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!**
```bash
npm test -- --grep "Feature"
# ❌ FAIL (this is correct!)
```

#### Step 2: 🟢 GREEN - Minimal Implementation

Write just enough code to pass the test:

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

**Run the test again:**
```bash
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:**
```bash
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:
```markdown
# 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:

```bash
# 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:
```bash
# 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:
```bash
# GOOD - Clean, single commit:
commit 1a2b3c: feat: add feature (with typo fixed)
```

### Interactive Rebase Workflow

**1. Check recent commits:**
```bash
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:**
```bash
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):**
```bash
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:**
```bash
git commit --amend
# Edit the file, save
# Git updates the commit without a new one
```

**Reorder commits:**
```bash
git rebase -i HEAD~3
# Reorder the lines in the editor
```

**Combine last 2 commits:**
```bash
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.


---

## Part 6: Branching Strategy - One Feature Per Branch

### The Workflow

**Each phase/feature gets its own branch:**

```
main
 └─ feature/03-design-polish (Phase 03)
     └─ feature/04-workout-modification (Phase 04, branched from 03)
         └─ feature/05-exercise-encyclopedia (Phase 05, branched from 04)
```

### Step-by-Step

#### 1. Work on Phase 03
```bash
git checkout -b feature/03-design-polish
# ... do all Phase 03 work ...
# Multiple commits, testing, refinement
git push origin feature/03-design-polish
```

#### 2. When Phase 03 is Done → Create PR
```bash
# Create PR: feature/03-design-polish → main
# Get code review, merge when approved
# This becomes the baseline for Phase 04
```

#### 3. Start Phase 04 (NEW BRANCH from Phase 03)
```bash
# First, make sure local is up-to-date
git checkout feature/03-design-polish
git pull origin feature/03-design-polish

# Create new branch FROM the current feature
git checkout -b feature/04-workout-modification

# Now do all Phase 04 work on this new branch
# ... commits for 04-01, 04-02, 04-03, etc ...
git push origin feature/04-workout-modification
```

#### 4. When Phase 04 is Done → Rebase Before PR
```bash
# Make sure feature/03 is merged to main
git fetch origin

# Rebase Phase 04 onto main (to get clean history)
git rebase origin/main feature/04-workout-modification

# Force-push (since we're rebasing)
git push -f origin feature/04-workout-modification

# Create PR: feature/04-workout-modification → main
```

### Why This Matters

- ✅ **Cleaner history** — Each phase is separate
- ✅ **Easier reviews** — PRs are focused on one phase
- ✅ **Better testing** — Each phase tested independently
- ✅ **Easy rollback** — Remove one phase without touching others
- ✅ **Work in parallel** — Different agents can work on different phases

### Current Situation

We've mixed Phase 03 and 04 in `feature/03-design-polish`. Going forward:

1. **Merge feature/03-design-polish → main** (code review, then merge)
2. **Create feature/04-workout-modification** from main
3. Move/cherry-pick Phase 04 commits to new branch (or just continue from here)
4. **Create feature/05-exercise-encyclopedia** from feature/04 when 04 is done

### Rebase Chain Example

```bash
# After 03 is merged and 04 starts:
git checkout feature/04-workout-modification
git rebase origin/main  # Rebase 04 onto latest main

# After 04 is merged and 05 starts:
git checkout feature/05-exercise-encyclopedia
git rebase origin/main  # Always rebase new features onto main
```

### Rule of Thumb

- **One feature per branch**
- **Each branch is independent**
- **Rebase onto main before PR**
- **No "feature/03-design-polish" commits after it's merged**