From 81fbd809ce8cbe783a38c2ba40e2bb10f337c829 Mon Sep 17 00:00:00 2001 From: Clawd Agent Date: Mon, 2 Mar 2026 08:46:26 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20add=20CLAUDE.md=20=E2=80=94=20agent=20d?= =?UTF-8?q?evelopment=20guidelines?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .gitignore | 54 +++++++++++++++++ CLAUDE.md | 171 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ec3b48a --- /dev/null +++ b/.gitignore @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..89e504d --- /dev/null +++ b/CLAUDE.md @@ -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