docs: integrate coding conventions into CLAUDE.md
- Merged CODING-CONVENTIONS.md content into single authoritative document - Part 1: Agent development principles (autonomy, verification, PM pattern) - Part 2: Coding conventions (Red/Green/Refactor TDD, naming, commit patterns) - Part 3: Operations (cron jobs, repo structure) - Part 4: Agent/skill development workflow - CLAUDE.md is now the single source of truth for agent development
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user