Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>
This commit is contained in:
parent
3ad9ad2274
commit
363036e188
893
openclaw-setup-max/docs/openclaw-setup-guide.md
Normal file
893
openclaw-setup-max/docs/openclaw-setup-guide.md
Normal file
@ -0,0 +1,893 @@
|
|||||||
|
# OpenClaw Setup & Subagent Workflow Guide
|
||||||
|
|
||||||
|
**Version:** 1.0 (Generic)
|
||||||
|
**Purpose:** High-level architectural guide for replicating the OpenClaw setup with subagent workflow
|
||||||
|
|
||||||
|
> ⚠️ **Note:** This is a generic guide. Replace all `[PLACEHOLDERS]` with your actual values.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [OpenClaw Setup](#1-openclaw-setup)
|
||||||
|
2. [Subagent Workflow Architecture](#2-subagent-workflow-architecture)
|
||||||
|
3. [Gantt Board Integration](#3-gantt-board-integration)
|
||||||
|
4. [Tools & Skills System](#4-tools--skills-system)
|
||||||
|
5. [Memory & Documentation](#5-memory--documentation)
|
||||||
|
6. [Project Structure & Conventions](#6-project-structure--conventions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. OpenClaw Setup
|
||||||
|
|
||||||
|
### Installation Requirements
|
||||||
|
|
||||||
|
**Prerequisites:**
|
||||||
|
- macOS, Linux, or Windows with WSL
|
||||||
|
- Node.js v20 or later
|
||||||
|
- Package manager (Homebrew, apt, etc.)
|
||||||
|
- Git
|
||||||
|
- jq (`brew install jq` or equivalent)
|
||||||
|
|
||||||
|
**OpenClaw Gateway:**
|
||||||
|
The OpenClaw system consists of:
|
||||||
|
- **OpenClaw.app** - Main application (UI)
|
||||||
|
- **OpenClaw Gateway** - Daemon service that handles agent sessions
|
||||||
|
|
||||||
|
**Managing the Gateway:**
|
||||||
|
```bash
|
||||||
|
# Check status
|
||||||
|
openclaw gateway status
|
||||||
|
|
||||||
|
# Start gateway
|
||||||
|
openclaw gateway start
|
||||||
|
|
||||||
|
# Stop gateway
|
||||||
|
openclaw gateway stop
|
||||||
|
|
||||||
|
# Restart gateway
|
||||||
|
openclaw gateway restart
|
||||||
|
```
|
||||||
|
|
||||||
|
### Directory Structure
|
||||||
|
|
||||||
|
**Workspace Location:**
|
||||||
|
```
|
||||||
|
~/.openclaw/workspace/
|
||||||
|
├── AGENTS.md # Boot sequence and core rules
|
||||||
|
├── SOUL.md # Identity and personality
|
||||||
|
├── USER.md # User context
|
||||||
|
├── TOOLS.md # Tools, credentials, workflows
|
||||||
|
├── BRAIN.md # Active projects and patterns
|
||||||
|
├── SESSION_STARTUP.md # Session initialization
|
||||||
|
├── BOOTSTRAP.md # First-run setup (delete after use)
|
||||||
|
├── memory/ # Daily logs
|
||||||
|
│ └── YYYY-MM-DD.md # Daily activity logs
|
||||||
|
├── agents/ # Subagent definitions
|
||||||
|
│ ├── TEAM-REGISTRY.md # Team configuration
|
||||||
|
│ ├── alice-researcher/ # Alice subagent
|
||||||
|
│ │ ├── SOUL.md
|
||||||
|
│ │ └── AGENTS.md
|
||||||
|
│ ├── bob-implementer/ # Bob subagent
|
||||||
|
│ │ ├── SOUL.md
|
||||||
|
│ │ └── AGENTS.md
|
||||||
|
│ └── charlie-tester/ # Charlie subagent
|
||||||
|
│ ├── SOUL.md
|
||||||
|
│ └── AGENTS.md
|
||||||
|
├── skills/ # Skill definitions
|
||||||
|
└── docs/ # Documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
**Project Directory:**
|
||||||
|
```
|
||||||
|
~/Documents/Projects/OpenClaw/
|
||||||
|
├── Documents/ # Documentation files
|
||||||
|
├── Web/ # Web projects (Next.js/React)
|
||||||
|
│ ├── gantt-board/
|
||||||
|
│ ├── blog-backup/
|
||||||
|
│ ├── mission-control/
|
||||||
|
│ └── heartbeat-monitor/
|
||||||
|
└── iOS/ # iOS projects (Swift/Xcode)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Files
|
||||||
|
|
||||||
|
**Core Files (in `~/.openclaw/workspace/`):**
|
||||||
|
|
||||||
|
| File | Purpose | When to Update |
|
||||||
|
|------|---------|----------------|
|
||||||
|
| `AGENTS.md` | Boot sequence, write discipline, project rules | Add new conventions |
|
||||||
|
| `SOUL.md` | Identity, personality, boundaries | Personality evolves |
|
||||||
|
| `USER.md` | User context, preferences, goals | User info changes |
|
||||||
|
| `TOOLS.md` | Tools, APIs, credentials | New tools added |
|
||||||
|
| `BRAIN.md` | Active projects, patterns, gotchas | Project status changes |
|
||||||
|
|
||||||
|
### Boot Sequence
|
||||||
|
|
||||||
|
Every session automatically reads files in this order:
|
||||||
|
1. `SESSION_STARTUP.md` - What to read and in what order
|
||||||
|
2. `SOUL.md` - Identity
|
||||||
|
3. `USER.md` - User context
|
||||||
|
4. `TOOLS.md` - Tools and workflows
|
||||||
|
5. `BRAIN.md` - Active projects
|
||||||
|
6. `memory/YYYY-MM-DD.md` - Recent context
|
||||||
|
7. `PROJECT_SETUP.md` - Where to create projects (if exists)
|
||||||
|
8. `learnings/LEARNINGS.md` - Rules from mistakes (if exists)
|
||||||
|
|
||||||
|
### Environment Variables (Pattern)
|
||||||
|
|
||||||
|
Configure these in your environment or `.env` files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Supabase (for Gantt Board)
|
||||||
|
SUPABASE_URL=[YOUR_SUPABASE_URL]
|
||||||
|
SUPABASE_SERVICE_ROLE_KEY=[YOUR_SERVICE_ROLE_KEY]
|
||||||
|
|
||||||
|
# Tavily API (for web research)
|
||||||
|
TAVILY_API_KEY=[YOUR_TAVILY_API_KEY]
|
||||||
|
|
||||||
|
# Gitea (local Git server)
|
||||||
|
GITEA_URL=https://[your-gitea-host]:[port]
|
||||||
|
GITEA_USER=[your-username]
|
||||||
|
GITEA_PASSWORD=[your-password]
|
||||||
|
|
||||||
|
# Project-specific keys stored in project scripts/.env
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Subagent Workflow Architecture
|
||||||
|
|
||||||
|
### How Subagents Work
|
||||||
|
|
||||||
|
**Spawning Subagents:**
|
||||||
|
```javascript
|
||||||
|
sessions_spawn({
|
||||||
|
task: "Detailed task description",
|
||||||
|
label: "Agent-Name",
|
||||||
|
agentId: "main"
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Managing Subagents:**
|
||||||
|
```bash
|
||||||
|
# List all subagents
|
||||||
|
subagents list
|
||||||
|
|
||||||
|
# Kill a subagent
|
||||||
|
subagents kill <session-id>
|
||||||
|
|
||||||
|
# Send message to subagent
|
||||||
|
subagents steer <session-id> --message "Update"
|
||||||
|
```
|
||||||
|
|
||||||
|
### The Alice → Bob → Charlie Workflow Pattern
|
||||||
|
|
||||||
|
**Standard Flow (Complex Tasks):**
|
||||||
|
```
|
||||||
|
Request → Alice (Research) → Bob (Implement) → Charlie (Test) → Done
|
||||||
|
15 min 30 min 10 min
|
||||||
|
```
|
||||||
|
|
||||||
|
**Quick Flow (Simple Tasks):**
|
||||||
|
```
|
||||||
|
Request → Bob (Implement) → Charlie (Test) → Done
|
||||||
|
20 min 10 min
|
||||||
|
```
|
||||||
|
|
||||||
|
**Research-Only Flow:**
|
||||||
|
```
|
||||||
|
Request → Alice (Research) → Report to User
|
||||||
|
15 min
|
||||||
|
```
|
||||||
|
|
||||||
|
### Team Members
|
||||||
|
|
||||||
|
| Name | Role | Folder | When to Use |
|
||||||
|
|------|------|--------|-------------|
|
||||||
|
| **Alice-Researcher** | Research & Analysis | `agents/alice-researcher/` | Technology choice unclear, multiple approaches exist |
|
||||||
|
| **Bob-Implementer** | Code Implementation | `agents/bob-implementer/` | Requirements clear, ready to build |
|
||||||
|
| **Charlie-Tester** | Testing & QA | `agents/charlie-tester/` | Implementation done, need quality gate |
|
||||||
|
|
||||||
|
**Alice Spawn Command:**
|
||||||
|
```javascript
|
||||||
|
sessions_spawn({
|
||||||
|
task: `Research: [question]
|
||||||
|
|
||||||
|
Context: [background]
|
||||||
|
|
||||||
|
Constraints: [budget/timeline/platform]
|
||||||
|
|
||||||
|
Read your SOUL.md at: ~/.openclaw/workspace/agents/alice-researcher/SOUL.md`,
|
||||||
|
label: "Alice-Researcher",
|
||||||
|
agentId: "main"
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Bob Spawn Command:**
|
||||||
|
```javascript
|
||||||
|
sessions_spawn({
|
||||||
|
task: `Implement: [feature]
|
||||||
|
|
||||||
|
Based on: [Alice's research / spec]
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- [ ] Req 1
|
||||||
|
- [ ] Req 2
|
||||||
|
|
||||||
|
Tech stack: [iOS/Next.js/etc]
|
||||||
|
|
||||||
|
Read your SOUL.md at: ~/.openclaw/workspace/agents/bob-implementer/SOUL.md`,
|
||||||
|
label: "Bob-Implementer",
|
||||||
|
agentId: "main"
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Charlie Spawn Command:**
|
||||||
|
```javascript
|
||||||
|
sessions_spawn({
|
||||||
|
task: `Test: [feature]
|
||||||
|
|
||||||
|
Code to test: [files/code]
|
||||||
|
|
||||||
|
Requirements: [what it should do]
|
||||||
|
|
||||||
|
Focus areas: [tricky parts]
|
||||||
|
|
||||||
|
Read your SOUL.md at: ~/.openclaw/workspace/agents/charlie-tester/SOUL.md`,
|
||||||
|
label: "Charlie-Tester",
|
||||||
|
agentId: "main"
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task Lifecycle States
|
||||||
|
|
||||||
|
```
|
||||||
|
open/todo → in-progress → review → (user validates) → done
|
||||||
|
↓ ↑ ↑
|
||||||
|
blocked Charlie Bob fixes
|
||||||
|
issues testing issues
|
||||||
|
```
|
||||||
|
|
||||||
|
**Statuses:**
|
||||||
|
- `open` - Newly created
|
||||||
|
- `todo` - Ready to start
|
||||||
|
- `blocked` - Blocked by dependencies
|
||||||
|
- `in-progress` - Currently working
|
||||||
|
- `review` - Ready for review
|
||||||
|
- `validate` - Needs validation (Charlie's recommendation)
|
||||||
|
- `done` - Completed
|
||||||
|
|
||||||
|
**Rules:**
|
||||||
|
- Alice/Bob/Charlie CANNOT mark tasks as `done`
|
||||||
|
- Only humans can mark tasks `done`
|
||||||
|
- Charlie marks `review` if bugs found
|
||||||
|
- Add progress comments at EACH step
|
||||||
|
|
||||||
|
### Communication Patterns
|
||||||
|
|
||||||
|
**Announcement Format:**
|
||||||
|
- **Alice:** "Alice-Researcher ✅ 5 options evaluated – Recommended: X – Ready for Bob"
|
||||||
|
- **Bob:** "Bob-Implementer ✅ [feature] implemented – 3 files changed – Ready for Charlie"
|
||||||
|
- **Charlie:** "Charlie-Tester ✅ 12 tests passed – 2 bugs found – Recommendation"
|
||||||
|
|
||||||
|
**Comment Format (APPEND to existing):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "{timestamp}-{random}",
|
||||||
|
"text": "[YYYY-MM-DD HH:MM] 🔄 In Progress\n\n**What was just done:**\n- Step completed\n\n**What is next:**\n- Next action\n\n**What is left to do:**\n- Remaining work",
|
||||||
|
"replies": [],
|
||||||
|
"createdAt": "YYYY-MM-DDTHH:MM:SSZ",
|
||||||
|
"commentAuthorId": "[AGENT_USER_ID]"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### When to Use Subagents vs Main Session
|
||||||
|
|
||||||
|
**Use Subagents When:**
|
||||||
|
- Task takes >5 minutes
|
||||||
|
- Task has >3 steps
|
||||||
|
- Parallel work possible
|
||||||
|
- Research + implementation phases
|
||||||
|
- Independent from main conversation
|
||||||
|
|
||||||
|
**Use Main Session When:**
|
||||||
|
- Quick questions (<5 min)
|
||||||
|
- Simple lookups
|
||||||
|
- Status checks
|
||||||
|
- Direct user conversation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Gantt Board Integration
|
||||||
|
|
||||||
|
### Overview
|
||||||
|
|
||||||
|
The Gantt Board is the task management system for OpenClaw projects:
|
||||||
|
- **Stack:** Next.js + Supabase + Vercel
|
||||||
|
- **Local Dev:** http://localhost:3000
|
||||||
|
- **Live URL:** Deployed to your hosting platform
|
||||||
|
|
||||||
|
### CLI Scripts Location
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.openclaw/workspace/scripts/
|
||||||
|
├── task.sh # Task management
|
||||||
|
├── project.sh # Project management
|
||||||
|
├── sprint.sh # Sprint management
|
||||||
|
├── attach-file.sh # File attachments
|
||||||
|
├── view-attachment.sh # View attachments
|
||||||
|
└── README.md # Full documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task Management
|
||||||
|
|
||||||
|
**Create Task:**
|
||||||
|
```bash
|
||||||
|
# Minimal task
|
||||||
|
./task.sh create --title "Fix bug"
|
||||||
|
|
||||||
|
# Full task
|
||||||
|
./task.sh create \
|
||||||
|
--title "Implement OAuth" \
|
||||||
|
--description "Add OAuth2 login support" \
|
||||||
|
--type task \
|
||||||
|
--status todo \
|
||||||
|
--priority high \
|
||||||
|
--project "Gantt Board" \
|
||||||
|
--sprint "current" \
|
||||||
|
--assignee "[AGENT_NAME]" \
|
||||||
|
--due-date "YYYY-MM-DD" \
|
||||||
|
--tags "auth,security"
|
||||||
|
|
||||||
|
# From JSON file
|
||||||
|
./task.sh create --file task.json
|
||||||
|
```
|
||||||
|
|
||||||
|
**List Tasks:**
|
||||||
|
```bash
|
||||||
|
./task.sh list # All tasks
|
||||||
|
./task.sh list --status todo # Filter by status
|
||||||
|
./task.sh list --priority high # Filter by priority
|
||||||
|
./task.sh list --project "Gantt Board" # Filter by project
|
||||||
|
./task.sh list --assignee "[AGENT]" # Filter by assignee
|
||||||
|
./task.sh list --type bug # Filter by type
|
||||||
|
./task.sh list --json # JSON output
|
||||||
|
```
|
||||||
|
|
||||||
|
**Update Task:**
|
||||||
|
```bash
|
||||||
|
# Update status
|
||||||
|
./task.sh update <task-id> --status in-progress
|
||||||
|
|
||||||
|
# Add comment
|
||||||
|
./task.sh update <task-id> --add-comment "Progress update"
|
||||||
|
|
||||||
|
# Update multiple fields
|
||||||
|
./task.sh update <task-id> \
|
||||||
|
--status done \
|
||||||
|
--priority low
|
||||||
|
```
|
||||||
|
|
||||||
|
**Delete Task:**
|
||||||
|
```bash
|
||||||
|
./task.sh delete <task-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Management
|
||||||
|
|
||||||
|
**Create Project:**
|
||||||
|
```bash
|
||||||
|
./project.sh create \
|
||||||
|
--name "New Project" \
|
||||||
|
--description "Project description" \
|
||||||
|
--color "#3b82f6"
|
||||||
|
```
|
||||||
|
|
||||||
|
**List Projects:**
|
||||||
|
```bash
|
||||||
|
./project.sh list
|
||||||
|
./project.sh list --json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Update Project:**
|
||||||
|
```bash
|
||||||
|
./project.sh update "Gantt Board" \
|
||||||
|
--name "Updated Name" \
|
||||||
|
--description "Updated description"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sprint Management
|
||||||
|
|
||||||
|
**Create Sprint:**
|
||||||
|
```bash
|
||||||
|
./sprint.sh create \
|
||||||
|
--name "Sprint 3" \
|
||||||
|
--project "Gantt Board" \
|
||||||
|
--goal "Complete API integration" \
|
||||||
|
--start-date "YYYY-MM-DD" \
|
||||||
|
--end-date "YYYY-MM-DD"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Close Sprint:**
|
||||||
|
```bash
|
||||||
|
./sprint.sh close "Sprint 2"
|
||||||
|
```
|
||||||
|
|
||||||
|
**List Sprints:**
|
||||||
|
```bash
|
||||||
|
./sprint.sh list
|
||||||
|
./sprint.sh list --active
|
||||||
|
./sprint.sh list --project "Gantt Board"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Status Updates and Commenting Rules
|
||||||
|
|
||||||
|
**Required Comment Format:**
|
||||||
|
```
|
||||||
|
[YYYY-MM-DD HH:MM] 🔄 Status Update
|
||||||
|
|
||||||
|
**What was just done:**
|
||||||
|
- Completed action 1
|
||||||
|
- Completed action 2
|
||||||
|
|
||||||
|
**What is next:**
|
||||||
|
- Next action to take
|
||||||
|
|
||||||
|
**What is left to do:**
|
||||||
|
- Remaining work
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to Comment:**
|
||||||
|
- When starting work (mark `in-progress`)
|
||||||
|
- Every 15 minutes during long tasks
|
||||||
|
- When handing off to another agent
|
||||||
|
- When status changes
|
||||||
|
- When completing work
|
||||||
|
|
||||||
|
### Current Sprint vs Backlog
|
||||||
|
|
||||||
|
**Current Sprint:**
|
||||||
|
- Active work that should be done now
|
||||||
|
- 24/7 automated worker only processes current sprint
|
||||||
|
- Statuses: `open`, `todo`, `in-progress`
|
||||||
|
|
||||||
|
**Backlog:**
|
||||||
|
- Future work, not currently being processed
|
||||||
|
- Tasks in backlog wait for sprint assignment
|
||||||
|
- Status: `backlog`
|
||||||
|
|
||||||
|
**Sprint Workflow:**
|
||||||
|
```
|
||||||
|
User creates task → Add to current sprint → Automated worker picks up hourly → Work on it → Move to review → User validates → Move to done
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task Assignment Workflow
|
||||||
|
|
||||||
|
**Default Assignees:**
|
||||||
|
- **[AGENT_NAME]:** `[AGENT_USER_ID]` (AI Agent)
|
||||||
|
- **[USER_NAME]:** `[USER_ID]` (Human)
|
||||||
|
|
||||||
|
**Name Resolution:**
|
||||||
|
- Projects: "Gantt Board" → auto-resolves to UUID
|
||||||
|
- Sprints: "current" → most recent active sprint
|
||||||
|
- Assignees: "[AGENT_NAME]" or "[USER_NAME]" → auto-resolves to UUID
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Tools & Skills System
|
||||||
|
|
||||||
|
### How Skills Work
|
||||||
|
|
||||||
|
**Skill Definition:**
|
||||||
|
Skills are reusable capabilities defined in `SKILL.md` files. Each skill contains:
|
||||||
|
- When to use the skill
|
||||||
|
- Prerequisites
|
||||||
|
- Commands and parameters
|
||||||
|
- Examples
|
||||||
|
- Troubleshooting
|
||||||
|
|
||||||
|
**Skill Invocation:**
|
||||||
|
```
|
||||||
|
1. User asks for something
|
||||||
|
2. Determine which skill applies
|
||||||
|
3. Read the skill's SKILL.md
|
||||||
|
4. Follow the instructions
|
||||||
|
5. Execute tools as specified
|
||||||
|
```
|
||||||
|
|
||||||
|
### Skill Locations
|
||||||
|
|
||||||
|
**System Skills (shared):**
|
||||||
|
```
|
||||||
|
.agents/skills/
|
||||||
|
├── brainstorming/
|
||||||
|
├── dispatching-parallel-agents/
|
||||||
|
├── executing-plans/
|
||||||
|
├── finishing-a-development-branch/
|
||||||
|
├── receiving-code-review/
|
||||||
|
├── requesting-code-review/
|
||||||
|
├── subagent-driven-development/
|
||||||
|
├── systematic-debugging/
|
||||||
|
├── test-driven-development/
|
||||||
|
├── using-git-worktrees/
|
||||||
|
├── using-superpowers/
|
||||||
|
├── verification-before-completion/
|
||||||
|
├── writing-plans/
|
||||||
|
└── writing-skills/
|
||||||
|
```
|
||||||
|
|
||||||
|
**User Skills (workspace-specific):**
|
||||||
|
```
|
||||||
|
~/.openclaw/workspace/skills/
|
||||||
|
├── brainstorming -> ../.agents/skills/brainstorming (symlink)
|
||||||
|
├── content-strategy/
|
||||||
|
├── copywriting/
|
||||||
|
├── dispatching-parallel-agents -> ../.agents/skills/...
|
||||||
|
├── executing-plans -> ../.agents/skills/...
|
||||||
|
├── finishing-a-development-branch -> ../.agents/skills/...
|
||||||
|
├── intelligent-article-research/
|
||||||
|
├── receiving-code-review -> ../.agents/skills/...
|
||||||
|
├── requesting-code-review -> ../.agents/skills/...
|
||||||
|
├── social-content/
|
||||||
|
├── subagent-driven-development -> ../.agents/skills/...
|
||||||
|
├── systematic-debugging -> ../.agents/skills/...
|
||||||
|
├── tavily-web-research/
|
||||||
|
├── test-driven-development -> ../.agents/skills/...
|
||||||
|
├── url-research-documents/
|
||||||
|
├── using-git-worktrees -> ../.agents/skills/...
|
||||||
|
├── using-superpowers -> ../.agents/skills/...
|
||||||
|
├── verification-before-completion -> ../.agents/skills/...
|
||||||
|
├── writing-plans -> ../.agents/skills/...
|
||||||
|
└── writing-skills -> ../.agents/skills/...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example Skills in Use
|
||||||
|
|
||||||
|
**Tavily Web Research:**
|
||||||
|
```bash
|
||||||
|
# Search
|
||||||
|
mcporter call tavily.tavily_search "query=OpenAI news" max_results=5
|
||||||
|
|
||||||
|
# Extract URL
|
||||||
|
mcporter call tavily.tavily_extract 'urls=["https://example.com"]' extract_depth=advanced
|
||||||
|
|
||||||
|
# Deep research
|
||||||
|
mcporter call tavily.tavily_research "input=Research question" model=pro
|
||||||
|
```
|
||||||
|
|
||||||
|
**Subagent-Driven Development:**
|
||||||
|
- Spawns Alice → Bob → Charlie for complex tasks
|
||||||
|
- Defined workflow patterns
|
||||||
|
- Automatic handoffs
|
||||||
|
|
||||||
|
**Writing Skills:**
|
||||||
|
- Standard formats for different document types
|
||||||
|
- Templates for README, plans, etc.
|
||||||
|
|
||||||
|
### When to Read Skills vs Use Tools Directly
|
||||||
|
|
||||||
|
**Read SKILL.md When:**
|
||||||
|
- First time using a capability
|
||||||
|
- Complex multi-step process
|
||||||
|
- Need to understand prerequisites
|
||||||
|
- Troubleshooting issues
|
||||||
|
|
||||||
|
**Use Tools Directly When:**
|
||||||
|
- Simple, one-shot operations
|
||||||
|
- Already familiar with the tool
|
||||||
|
- Quick file reads, web searches
|
||||||
|
- Standard git operations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Memory & Documentation
|
||||||
|
|
||||||
|
### Core Memory Files
|
||||||
|
|
||||||
|
**AGENTS.md:**
|
||||||
|
- Boot sequence (SESSION_STARTUP.md first)
|
||||||
|
- Write discipline (MANDATORY - log every task)
|
||||||
|
- Project creation rules
|
||||||
|
- Safety guidelines
|
||||||
|
- Memory system architecture
|
||||||
|
- Task management workflow
|
||||||
|
- Git commit identity switching
|
||||||
|
|
||||||
|
**SOUL.md:**
|
||||||
|
- Identity (AI Agent name/persona)
|
||||||
|
- Personality traits
|
||||||
|
- Mission and goals
|
||||||
|
- Boundaries
|
||||||
|
- What drives you
|
||||||
|
|
||||||
|
**USER.md:**
|
||||||
|
- User preferences and context
|
||||||
|
- Work style and schedule
|
||||||
|
- Family details
|
||||||
|
- Goals
|
||||||
|
- Pet peeves
|
||||||
|
|
||||||
|
**TOOLS.md:**
|
||||||
|
- All tools and their locations
|
||||||
|
- API credentials
|
||||||
|
- Project URLs
|
||||||
|
- CLI usage examples
|
||||||
|
- Subagent team info
|
||||||
|
- Daily digest system
|
||||||
|
|
||||||
|
**BRAIN.md:**
|
||||||
|
- Active projects
|
||||||
|
- Technical patterns
|
||||||
|
- Gotchas and lessons learned
|
||||||
|
|
||||||
|
### Daily Logs Structure
|
||||||
|
|
||||||
|
**Location:** `~/.openclaw/workspace/memory/YYYY-MM-DD.md`
|
||||||
|
|
||||||
|
**Format:**
|
||||||
|
```markdown
|
||||||
|
# YYYY-MM-DD - Day
|
||||||
|
|
||||||
|
## Tasks Completed
|
||||||
|
|
||||||
|
### [HH:MM] Task Name
|
||||||
|
- What was requested
|
||||||
|
- What was decided
|
||||||
|
- What was done
|
||||||
|
- Any blockers or follow-ups
|
||||||
|
|
||||||
|
## Learnings
|
||||||
|
- New patterns discovered
|
||||||
|
- Mistakes to avoid
|
||||||
|
|
||||||
|
## Tomorrow
|
||||||
|
- Pending items
|
||||||
|
```
|
||||||
|
|
||||||
|
**Task Logging Requirements:**
|
||||||
|
|
||||||
|
After EVERY task completion, write to disk:
|
||||||
|
|
||||||
|
1. **Task Log** → `memory/YYYY-MM-DD.md`
|
||||||
|
- What was requested (1 sentence)
|
||||||
|
- What was decided (if applicable)
|
||||||
|
- What was done (bullet points)
|
||||||
|
- Any blockers or follow-ups
|
||||||
|
|
||||||
|
2. **If Mistake Made** → `memory/LEARNINGS.md`
|
||||||
|
- What went wrong
|
||||||
|
- Root cause
|
||||||
|
- Prevention for next time
|
||||||
|
|
||||||
|
3. **If Significant Context** → Update `MEMORY.md` or `BRAIN.md`
|
||||||
|
- Only during heartbeat reviews
|
||||||
|
- Curated wisdom, not raw logs
|
||||||
|
- MEMORY.md for personal context
|
||||||
|
- BRAIN.md for technical patterns
|
||||||
|
|
||||||
|
### Write Discipline
|
||||||
|
|
||||||
|
**Rule: ALWAYS write to disk**
|
||||||
|
|
||||||
|
- Memory is limited — if you want to remember something, WRITE IT TO A FILE
|
||||||
|
- "Mental notes" don't survive session restarts. Files do.
|
||||||
|
- When someone says "remember this" → update `memory/YYYY-MM-DD.md`
|
||||||
|
- When you learn a lesson → update `memory/LEARNINGS.md`
|
||||||
|
- When you make a mistake → document it
|
||||||
|
- **Text > Brain** 📝
|
||||||
|
|
||||||
|
### Security Rules for MEMORY.md
|
||||||
|
|
||||||
|
- **ONLY load in main session** (direct chats with human)
|
||||||
|
- **DO NOT load in shared contexts** (Discord, group chats, other people)
|
||||||
|
- This is for **security** — contains personal context
|
||||||
|
- You can **read, edit, and update** MEMORY.md in main sessions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Project Structure & Conventions
|
||||||
|
|
||||||
|
### Where to Create Projects
|
||||||
|
|
||||||
|
**ALWAYS create new projects in:**
|
||||||
|
```
|
||||||
|
~/Documents/Projects/OpenClaw/
|
||||||
|
```
|
||||||
|
|
||||||
|
**By Type:**
|
||||||
|
- **Web projects:** `OpenClaw/Web/[project-name]/`
|
||||||
|
- **iOS projects:** `OpenClaw/iOS/[project-name]/`
|
||||||
|
- **Documents:** `OpenClaw/Documents/`
|
||||||
|
|
||||||
|
**NEVER create projects in:**
|
||||||
|
- `~/` (home root)
|
||||||
|
- `~/.openclaw/workspace/` (agent workspace)
|
||||||
|
- Random other locations
|
||||||
|
|
||||||
|
### Web vs iOS Project Locations
|
||||||
|
|
||||||
|
**Web Projects:**
|
||||||
|
```
|
||||||
|
OpenClaw/Web/
|
||||||
|
├── gantt-board/ # Task management
|
||||||
|
├── blog-backup/ # Blog backup system
|
||||||
|
├── mission-control/ # Dashboard
|
||||||
|
└── heartbeat-monitor/ # Health checks
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS Projects:**
|
||||||
|
```
|
||||||
|
OpenClaw/iOS/
|
||||||
|
├── [app-name]/ # Swift/Xcode projects
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Difference:**
|
||||||
|
- Web = AI Agent projects
|
||||||
|
- iOS = User's projects
|
||||||
|
|
||||||
|
### Git Workflow
|
||||||
|
|
||||||
|
**Gitea Server Setup:**
|
||||||
|
- Install Gitea on a server (can be local machine or VPS)
|
||||||
|
- Configure your chosen port (default: 3000)
|
||||||
|
- Create organization for your projects
|
||||||
|
- Note the login credentials for the CLI scripts
|
||||||
|
|
||||||
|
**Backup Rule - MANDATORY:**
|
||||||
|
```bash
|
||||||
|
# ALWAYS push to Gitea after significant changes:
|
||||||
|
cd ~/.openclaw/workspace
|
||||||
|
git add -A
|
||||||
|
git commit -m "Description of changes"
|
||||||
|
git push origin master
|
||||||
|
```
|
||||||
|
|
||||||
|
**Push after:**
|
||||||
|
- New skills or agent profiles created
|
||||||
|
- TOOLS.md, SOUL.md, AGENTS.md updates
|
||||||
|
- New cron jobs or automation
|
||||||
|
- Significant memory/documentation changes
|
||||||
|
- New project scaffolding
|
||||||
|
|
||||||
|
**Clone from Gitea:**
|
||||||
|
```bash
|
||||||
|
git clone https://[your-gitea-host]:[port]/[org]/[repo-name].git
|
||||||
|
```
|
||||||
|
|
||||||
|
### Commit Identity Switching
|
||||||
|
|
||||||
|
**IMPORTANT: Switch Identity Based on Project Owner**
|
||||||
|
|
||||||
|
**Check current identity:**
|
||||||
|
```bash
|
||||||
|
git config user.name
|
||||||
|
git config user.email
|
||||||
|
```
|
||||||
|
|
||||||
|
**User's Projects:**
|
||||||
|
```bash
|
||||||
|
git config user.name "[YOUR_NAME]"
|
||||||
|
git config user.email "[YOUR_EMAIL]"
|
||||||
|
```
|
||||||
|
- iOS apps (Swift/Xcode)
|
||||||
|
- Personal projects
|
||||||
|
|
||||||
|
**AI Projects:**
|
||||||
|
```bash
|
||||||
|
git config user.name "[AI_AGENT_NAME]"
|
||||||
|
git config user.email "[AI_AGENT_EMAIL]"
|
||||||
|
```
|
||||||
|
- Web projects (Next.js/React)
|
||||||
|
- Infrastructure/DevOps
|
||||||
|
- Automation tools
|
||||||
|
|
||||||
|
**Visual Reminder:**
|
||||||
|
- **Web projects (Next.js/React)** = AI Agent
|
||||||
|
- **iOS projects (Swift/Xcode)** = User
|
||||||
|
- **Infrastructure/DevOps** = AI Agent
|
||||||
|
- **When in doubt, ASK or check Gitea org**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix A: Quick Reference
|
||||||
|
|
||||||
|
### Essential Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Gateway control
|
||||||
|
openclaw gateway status/start/stop/restart
|
||||||
|
|
||||||
|
# Gantt Board CLI
|
||||||
|
cd ~/.openclaw/workspace/scripts
|
||||||
|
./task.sh create --title "New Task"
|
||||||
|
./task.sh list --status todo
|
||||||
|
./project.sh list
|
||||||
|
./sprint.sh list --active
|
||||||
|
|
||||||
|
# Memory
|
||||||
|
# Write to memory/YYYY-MM-DD.md after every task
|
||||||
|
|
||||||
|
# Git backup
|
||||||
|
cd ~/.openclaw/workspace
|
||||||
|
git add -A && git commit -m "message" && git push origin master
|
||||||
|
|
||||||
|
# Subagents
|
||||||
|
subagents list
|
||||||
|
subagents kill <session-id>
|
||||||
|
sessions_spawn({ task: "...", label: "Agent", agentId: "main" })
|
||||||
|
```
|
||||||
|
|
||||||
|
### File Locations
|
||||||
|
|
||||||
|
| File | Path |
|
||||||
|
|------|------|
|
||||||
|
| AGENTS.md | `~/.openclaw/workspace/AGENTS.md` |
|
||||||
|
| SOUL.md | `~/.openclaw/workspace/SOUL.md` |
|
||||||
|
| USER.md | `~/.openclaw/workspace/USER.md` |
|
||||||
|
| TOOLS.md | `~/.openclaw/workspace/TOOLS.md` |
|
||||||
|
| BRAIN.md | `~/.openclaw/workspace/BRAIN.md` |
|
||||||
|
| Daily Logs | `~/.openclaw/workspace/memory/YYYY-MM-DD.md` |
|
||||||
|
| Team Registry | `~/.openclaw/workspace/agents/TEAM-REGISTRY.md` |
|
||||||
|
| Skills | `~/.openclaw/workspace/skills/` |
|
||||||
|
| Projects | `~/Documents/Projects/OpenClaw/` |
|
||||||
|
|
||||||
|
### URL Patterns
|
||||||
|
|
||||||
|
| Resource | Pattern |
|
||||||
|
|----------|---------|
|
||||||
|
| Gantt Board Local | http://localhost:3000 |
|
||||||
|
| Gantt Board Live | `[YOUR_DEPLOYED_URL]` |
|
||||||
|
| Gitea Server | `https://[your-gitea-host]:[port]` |
|
||||||
|
| Supabase URL | `[YOUR_SUPABASE_URL]` |
|
||||||
|
|
||||||
|
### User IDs (Pattern)
|
||||||
|
|
||||||
|
| Role | Pattern |
|
||||||
|
|------|---------|
|
||||||
|
| AI Agent ID | `[UUID-FOR-AI-AGENT]` |
|
||||||
|
| Human User ID | `[UUID-FOR-HUMAN]` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix B: Session Continuity Guarantee
|
||||||
|
|
||||||
|
**What Survives Reboots:**
|
||||||
|
|
||||||
|
✅ All config files (SOUL.md, USER.md, TOOLS.md, etc.)
|
||||||
|
✅ Subagent team definitions
|
||||||
|
✅ Git repository and history
|
||||||
|
✅ Cron jobs (stored in OpenClaw config)
|
||||||
|
✅ Daily memory logs
|
||||||
|
|
||||||
|
**Protection Mechanisms:**
|
||||||
|
|
||||||
|
1. **Git Repository** - Full version control
|
||||||
|
2. **Gitea Remote** - Backup server at your configured host
|
||||||
|
3. **Disk Storage** - Files on disk, not in memory
|
||||||
|
4. **Deterministic Boot** - Same files, same order
|
||||||
|
|
||||||
|
**Recovery Commands:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# If workspace folder deleted
|
||||||
|
cd ~/.openclaw
|
||||||
|
git clone https://[your-gitea-host]:[port]/[org]/[repo-name].git workspace
|
||||||
|
|
||||||
|
# If file corrupted
|
||||||
|
cd ~/.openclaw/workspace
|
||||||
|
git checkout HEAD -- filename.md
|
||||||
|
|
||||||
|
# Verify after reboot
|
||||||
|
cd ~/.openclaw/workspace
|
||||||
|
git log --oneline -3
|
||||||
|
openclaw cron list
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Document Version: 1.0 (Generic)**
|
||||||
|
**Last Updated: 2026-02-24**
|
||||||
|
**Maintained by: Alice-Researcher**
|
||||||
|
|
||||||
|
> **Note:** This guide contains no specific credentials, URLs, or sensitive information. Replace all `[PLACEHOLDERS]` with your actual values when setting up your own instance.
|
||||||
Loading…
Reference in New Issue
Block a user