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