diff --git a/CLAUDE.md b/CLAUDE.md
index 89e504d..cc85cfc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,11 +1,12 @@
-# CLAUDE.md — Agent Development Guidelines
+# CLAUDE.md — Agent Development Foundation
 
-This is the foundation for developing Claude agents and autonomous systems in the Gravl ecosystem.
+This document is **THE** foundation for developing Claude agents and autonomous systems in Gravl.  
+Together with the actual codebase, this is your north star.
 
-## Core Principles
+## Part 1: Agent Development Principles
 
 ### 1. Autonomy with Verification
-- Agents execute tasks independently (autonomy)
+- 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
@@ -31,45 +32,215 @@ All long-running tasks use checkpoint files:
 The Gravl PM agent:
 - Plans sprints/phases autonomously
 - Spawns specialized agents (frontend-dev, backend-dev, etc.)
-- Verifies their work before checkpoint completion
+- 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.**
+**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
+- `reviewer` — Code review + quality gates
 - `browser-tester` — E2E testing + QA
 
-These are in `~/clawd/claude-agents-skills/agents/` and symlinked to `~/clawd/agents/`.
+These live in `~/clawd/claude-agents-skills/agents/` and symlink to `~/clawd/agents/`.
 
 ### 5. Single Source of Truth
-All skills and agents live in ONE central repo:
+All skills and agents 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
+- Commit all changes to hub repo
+- Enables sharing, versioning, and collaboration
 
-## Development Workflow
+### 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)
-3. Optional: Add `README.md`, scripts, config
-4. Symlink automatically created: `~/clawd/agents/my-agent → hub/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` (how to use it)
-3. Add code/scripts as needed
-4. Symlink automatically created: `~/clawd/skills/my-skill → hub/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)
@@ -86,86 +257,55 @@ git log --oneline -3
 # 3. Inspect actual changes
 git diff HEAD~1
 
-# 4. THEN update checkpoint
-echo '{"status":"completed",...}' > checkpoint.json
+# 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.
 
-## 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
+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
 
-## For the PM Agent
+---
 
-The Gravl PM uses this playbook:
+## PM Agent Playbook (30-minute cycles)
 
-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
+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 every 30 minutes autonomously. No human approval needed unless blocked.
+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  
-**For questions:** Check specific agent SOUL.md or skill SKILL.md files
+**Audience:** All Claude agents, PM, developers
+
+> **Remember:** This document is your north star. Follow it. Extend it. Improve it.