docs: add CLAUDE.md — agent development guidelines
- Core principles for autonomous agents with verification - Checkpoint-based self-monitoring patterns - Generalized agent workflow (no project-specific agents) - Single source of truth in ~/clawd/claude-agents-skills/ - PM autonomy and cron job configuration - Verification protocol to prevent hallucinations - Together with CODING-CONVENTIONS.md, foundation for agent development
This commit is contained in:
+54
@@ -0,0 +1,54 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# Build & dist
|
||||
dist/
|
||||
build/
|
||||
*.bundle.js
|
||||
*.bundle.css
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
.env.production.local
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
.DS_Store
|
||||
|
||||
# OS
|
||||
Thumbs.db
|
||||
.DS_Store
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
logs/
|
||||
|
||||
# Test coverage
|
||||
.coverage/
|
||||
coverage/
|
||||
|
||||
# Python
|
||||
*.pyc
|
||||
__pycache__/
|
||||
*.py~
|
||||
|
||||
# Staging
|
||||
/tmp/
|
||||
/staging-*/
|
||||
|
||||
# Planning & Documentation (kept locally, not in repo)
|
||||
.planning/
|
||||
TODO.md
|
||||
./frontend/.planning/
|
||||
./frontend/tasks/
|
||||
./docs/plans/
|
||||
.claude/settings.local.json
|
||||
@@ -0,0 +1,171 @@
|
||||
# CLAUDE.md — Agent Development Guidelines
|
||||
|
||||
This is the foundation for developing Claude agents and autonomous systems in the Gravl ecosystem.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Autonomy with Verification
|
||||
- Agents execute tasks independently (autonomy)
|
||||
- **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
|
||||
- `browser-tester` — E2E testing + QA
|
||||
|
||||
These are in `~/clawd/claude-agents-skills/agents/` and symlinked to `~/clawd/agents/`.
|
||||
|
||||
### 5. Single Source of Truth
|
||||
All skills and agents live 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
|
||||
|
||||
## 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`
|
||||
5. Commit to hub repo
|
||||
|
||||
### 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`
|
||||
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. THEN update checkpoint
|
||||
echo '{"status":"completed",...}' > 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
|
||||
|
||||
## For the PM Agent
|
||||
|
||||
The Gravl PM uses this playbook:
|
||||
|
||||
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
|
||||
|
||||
PM runs every 30 minutes autonomously. No human approval needed unless blocked.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-03-02
|
||||
**Version:** 1.0
|
||||
**For questions:** Check specific agent SOUL.md or skill SKILL.md files
|
||||
Reference in New Issue
Block a user