# 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
```

**Repo-specific in-place upgrade (existing install):**
```bash
cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/update_openclaw.sh
```
This script stops gateway, upgrades OpenClaw, reapplies schedule/budget guardrails, and restarts gateway.

### 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.