clawd/gravl
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: integrate coding conventions into CLAUDE.md

Browse Source 
- 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:
Clawd Agent
2026-03-02 08:47:30 +01:00
parent f4df4f7490
commit 6b05b88bf1
1 changed files with 225 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+225 -85
View File
@@ -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 ### 1. Autonomy with Verification
- Agents execute tasks independently (autonomy) - Agents execute tasks independently
- **Always verify results** after delegation (no hallucinations) - **Always verify results** after delegation (no hallucinations)
- Verification pattern: `git status`, `git log`, `ls`, diff before checkpoint update - Verification pattern: `git status`, `git log`, `ls`, diff before checkpoint update
- Never report completion without checking actual work - Never report completion without checking actual work
@@ -31,45 +32,215 @@ All long-running tasks use checkpoint files:
The Gravl PM agent: The Gravl PM agent:
- Plans sprints/phases autonomously - Plans sprints/phases autonomously
- Spawns specialized agents (frontend-dev, backend-dev, etc.) - 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) - Reports progress to Telegram (not silent failures)
- Timeout: 15 minutes (900s) per cron cycle - Timeout: 15 minutes (900s) per cron cycle
### 4. Generalized Agents (Reusable) ### 4. Generalized Agents (Reusable)
**Never create project-specific agents.** **NEVER create project-specific agents.**
Use generalized agents instead: Use generalized agents instead:
- `frontend-dev` — React/CSS specialist - `frontend-dev` — React/CSS specialist
- `backend-dev` — Node.js/PostgreSQL specialist - `backend-dev` — Node.js/PostgreSQL specialist
- `architect` — System design - `architect` — System design
- `reviewer` — Code review - `reviewer` — Code review + quality gates
- `browser-tester` — E2E testing + QA - `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 ### 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/` - **Hub location:** `~/clawd/claude-agents-skills/`
- **Symlinks from:** `~/clawd/skills/` and `~/clawd/agents/` - **Symlinks from:** `~/clawd/skills/` and `~/clawd/agents/`
- **Commit everything to hub repo** - Commit all changes to hub repo
- This enables sharing, versioning, and collaboration - 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 ### Adding a New Agent
1. Create in hub: `~/clawd/claude-agents-skills/agents/my-agent/` 1. Create in hub: `~/clawd/claude-agents-skills/agents/my-agent/`
2. Write `SOUL.md` (agent definition + personality) 2. Write `SOUL.md` (agent definition, personality, expertise)
3. Optional: Add `README.md`, scripts, config 3. Optional: Add `README.md`, scripts, config files
4. Symlink automatically created: `~/clawd/agents/my-agent → hub/agents/my-agent` 4. Symlink automatically created: `~/clawd/agents/my-agent`
5. Commit to hub repo 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 ### Adding a New Skill
1. Create in hub: `~/clawd/claude-agents-skills/skills/my-skill/` 1. Create in hub: `~/clawd/claude-agents-skills/skills/my-skill/`
2. Write `SKILL.md` (how to use it) 2. Write `SKILL.md` (documentation, usage, examples)
3. Add code/scripts as needed 3. Add code/scripts
4. Symlink automatically created: `~/clawd/skills/my-skill → hub/skills/my-skill` 4. Symlink automatically created: `~/clawd/skills/my-skill`
5. Commit to hub repo 5. Commit to hub repo
### Verification Pattern (CRITICAL) ### Verification Pattern (CRITICAL)
@@ -86,86 +257,55 @@ git log --oneline -3
# 3. Inspect actual changes # 3. Inspect actual changes
git diff HEAD~1 git diff HEAD~1
# 4. THEN update checkpoint # 4. ONLY THEN update checkpoint
echo '{"status":"completed",...}' > checkpoint.json echo '{
"lastRun": "'$(date -Iseconds)'",
"status": "completed",
"result": "Summary..."
}' > checkpoint.json
``` ```
**This prevents hallucination bugs** where agents claim work they didn't do. **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 ## Key Decisions
1. **Generalized agents over project-specific** — More reusable, easier to maintain 1. **Generalized agents** — Reusable, maintainable, shareable
2. **Single hub repo** — Centralized versioning + easy sharing 2. **Single hub repo** — Centralized versioning
3. **Symlinks for discovery** — OpenClaw finds skills/agents automatically 3. **Symlinks for discovery** — OpenClaw finds everything automatically
4. **Verification protocol** — Prevents hallucination bugs 4. **TDD mandatory** — Red → Green → Refactor
5. **Checkpoint-based recovery** — Self-healing cron jobs 5. **Verification protocol** — No hallucinations allowed
6. **Telegram for delivery** — Explicit channel to avoid missed messages 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 1. **Plan** → Identify phase tasks, delegate to agents
2. **Execute phase** → Spawn agents, monitor progress 2. **Execute** → Spawn agents with tasks, monitor progress
3. **Verify phase** → Check git status, diffs, logs (NO HALLUCINATIONS) 3. **Verify** → Check `git status`, diffs, test results (NO ASSUMPTIONS)
4. **Report phase** → Send Telegram update with result or blocking issue 4. **Report** → Send Telegram update (success or blocking issue)
5. **Checkpoint phase** → Update checkpoint.json with status + nextCheck 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 **Last Updated:** 2026-03-02
**Version:** 1.0 **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.