diff --git a/openclaw-setup-max/docs/openclaw-setup-guide.md b/openclaw-setup-max/docs/openclaw-setup-guide.md new file mode 100644 index 0000000..9111e65 --- /dev/null +++ b/openclaw-setup-max/docs/openclaw-setup-guide.md @@ -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 + +# Send message to subagent +subagents steer --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 --status in-progress + +# Add comment +./task.sh update --add-comment "Progress update" + +# Update multiple fields +./task.sh update \ + --status done \ + --priority low +``` + +**Delete Task:** +```bash +./task.sh delete +``` + +### 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 +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.