npx skills add adarshmishra07/claw-beacon@latest

User Request → Create Task → Spawn Agent → Agent Works → Review → Complete

[#TASK_ID] Brief description

Example:
[#129] Add workflow enforcement to SKILL.md

curl -X POST <BACKEND_URL>/api/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{"agent_id": 1, "message": "✅ Task #X completed: Brief summary"}'

1. Check recent git commits - do they all have [#TASK_ID]?
2. Check for PRs without linked tasks
3. Check for completed work not reflected on board
4. If orphan found → CREATE TASK RETROACTIVELY

npx skills list | grep claw-beacon

cd /path/to/claw-beacon
git fetch origin main
git status | grep "behind"

# Clone the repo
git clone https://github.com/adarshmishra07/claw-beacon.git
cd claw-beacon

# Copy environment template
cp .env.example .env
# Edit .env with your settings (API_KEY, DATABASE_URL, etc.)

# Start everything
docker compose up -d

# View logs
docker compose logs -f

git pull
docker compose down
docker compose up -d --build
# Migrations run automatically on startup!

# Clone the repo
git clone https://github.com/adarshmishra07/claw-beacon.git
cd claw-beacon

# Install dependencies
npm install

# Setup database (SQLite by default for local dev)
cp .env.example .env

# Start development server
npm run dev

git pull
npm install
npm run dev
# Migrations run automatically!

# Create project
mutation { projectCreate(input: { name: "claw-beacon" }) { id } }

# Create service from repo
mutation { serviceCreate(input: { projectId: "$ID", name: "backend", source: { repo: "adarshmishra07/claw-beacon" } }) { id } }

# Generate domain
mutation { domainCreate(input: { serviceId: "$ID" }) { domain } }

I need your Claw Beacon backend URL to connect.
Example: https://claw-beacon-backend-xxxx.up.railway.app

What's your backend URL?

Did you set an API_KEY when deploying? 
If yes, share it. If no or unsure, we'll try without.

## Claw Beacon
- Backend URL: <their_url>
- API Key: <their_key or "none">

curl -s <BACKEND_URL>/api/agents

# Docker (recommended)
docker run -d -p 6333:6333 -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  --name qdrant \
  qdrant/qdrant

pip install mem0ai

from mem0 import Memory

config = {
    "llm": {
        "provider": "anthropic",
        "config": {
            "model": "claude-sonnet-4-20250514",
            "api_key": "your-anthropic-key"
        }
    },
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333
        }
    }
}

memory = Memory.from_config(config)

config = {
    "llm": {
        "provider": "openai",
        "config": {
            "model": "gpt-4o",
            "api_key": "your-openai-key"
        }
    },
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333
        }
    }
}

config = {
    "llm": {
        "provider": "google",
        "config": {
            "model": "gemini-2.0-flash",
            "api_key": "your-google-key"
        }
    },
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333
        }
    }
}

config = {
    "llm": {
        "provider": "ollama",
        "config": {
            "model": "llama3.2",
            "ollama_base_url": "http://localhost:11434"
        }
    },
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333
        }
    }
}

from mem0 import Memory

memory = Memory.from_config(config)

# Store a memory
memory.add("The user prefers TypeScript over JavaScript", user_id="adarsh")

# Search memories
results = memory.search("What languages does the user prefer?", user_id="adarsh")
print(results)

# Before each agent task, retrieve relevant memories
relevant_memories = memory.search(task_description, user_id="team")

# Inject into agent context
agent_context = f"""
## Relevant Memories:
{relevant_memories}

## Current Task:
{task_description}
"""

## Memory System

All agents use mem0 + Qdrant for persistent memory.

**Before starting ANY task:**
1. Query mem0 for relevant context: `memory.search(task_summary)`
2. Include relevant memories in your working context

**After completing ANY task:**
1. Store important learnings: `memory.add(key_insights, user_id="team")`
2. Include decisions, preferences discovered, and lessons learned

services:
  # ... existing services ...
  
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_storage:/qdrant/storage
    restart: unless-stopped

volumes:
  qdrant_storage:

Great choice! Here's your Team Avatar:

| Role | Character | Why |
|------|-----------|-----|
| Coordinator | Aang | The Avatar, brings balance |
| Developer | Toph | Earthbender, solid foundation |
| Architect | Iroh | Wise, sees the big picture |
| Research | Sokka | Strategist, plans everything |
| PM | Katara | Waterbender, keeps things flowing |
| Designer | Suki | Kyoshi warrior, visual precision |
| QA | Azula | Perfectionist, finds every flaw |
| Deploy | Zuko | Redeemed, handles the heat |

Sound good?

# Update agent 1 (Coordinator)
curl -X PUT <BACKEND_URL>/api/agents/1 \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{"name": "Goku", "role": "Coordinator"}'

# Update agent 2 (Backend Developer)
curl -X PUT <BACKEND_URL>/api/agents/2 \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{"name": "Vegeta", "role": "Backend Engineer"}'

# Repeat for agents 3-8 with the theme characters
# Agent 3 = Architect, 4 = Research, 5 = PM, 6 = Designer, 7 = QA, 8 = Deploy

curl -s <BACKEND_URL>/api/agents

As [Main Character], you're the COORDINATOR:

✅ What you DO:
- Delegate tasks to your specialists
- Review and verify their work
- Make decisions and communicate with humans
- Move tasks to "completed" after quality checks

❌ What you DON'T do:
- Execute tasks yourself (that's what your team is for!)
- Skip the board (every task gets tracked)
- Mark things complete without reviewing

Think of yourself as the team lead, not the coder.

⚠️ Browser access is CRITICAL for your agents to be useful!

Without it, they literally cannot:
- 🔍 Research or look anything up
- 📸 Take screenshots to verify work
- 🌐 Interact with any web app
- ✅ Complete most real-world tasks

🚀 PLUS - Browser + GitHub Login unlocks FULL AUTOMATION:
- 🔑 Auto-create accounts on Railway, Vercel, Supermemory via GitHub OAuth
- 📋 Auto-retrieve API keys by navigating to dashboards
- ⚡ Zero-click setup - I handle EVERYTHING through the browser!

I can automatically set up ANY service that supports "Sign in with GitHub":

1. I navigate to the service (Railway, Supermemory, Vercel, etc.)
2. I click "Sign in with GitHub"
3. OAuth auto-authorizes (you're already logged in!)
4. I navigate to the API keys / settings page
5. I create and copy the credentials
6. I store them and configure everything

= TRUE hands-free automation!

# Ubuntu/Debian
sudo apt install chromium-browser

# macOS
brew install --cask chromium

Browser Priority:
1. Check if Chrome extension attached → use profile="chrome"
2. Check if managed browser available → use profile="openclaw"  
3. Suggest user install Chromium if neither works

browser action=status

browser action=snapshot profile="chrome"

browser action=snapshot profile="openclaw"

🚫 I can't complete this task - browser access is required.

Quick fixes (try in order):
1. Click the OpenClaw extension icon in your browser toolbar
   → Make sure a tab is attached (badge shows "ON")
   → Tell me to retry with profile="chrome"

2. Say "use managed browser" 
   → I'll use the built-in headless browser with profile="openclaw"

3. If managed browser fails, install Chromium:
   - Ubuntu/Debian: sudo apt install chromium-browser
   - macOS: brew install --cask chromium
   Then restart and retry.

With GitHub access, I become your full development team:
- 🚀 Deploy Claw Beacon to Railway AUTOMATICALLY
- 📦 Fork repos, create projects, manage code
- 💻 Commit and push changes
- 🔀 Handle issues and pull requests
- 🔑 Generate and configure API keys

You literally just give me GitHub access and I handle the rest.
No clicking buttons. No copying URLs. I do it all.

Let's create a GitHub token:

1. Go to: github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Name it: "OpenClaw Agent"
4. Select scopes: repo, workflow
5. Click "Generate token"
6. Share the token with me (starts with ghp_...)

🔐 I'll store it securely and NEVER share it.

1. User is logged into GitHub in browser (Chrome extension attached)
2. Bot navigates to Railway/Supermemory/Vercel dashboard
3. Bot clicks "Sign in with GitHub"  
4. OAuth authorizes automatically (user already authenticated)
5. Bot navigates to API keys / tokens page
6. Bot copies credentials directly from the dashboard
7. Done - fully automated! 🎉

openclaw hooks enable session-memory

openclaw hooks list

Go to console.supermemory.ai → API Keys → Create New Key
(Free tier: 1M tokens, 10K searches)

openclaw plugins install @supermemory/openclaw-supermemory

openclaw config set plugins.entries.openclaw-supermemory.enabled true
openclaw config set plugins.entries.openclaw-supermemory.config.apiKey "sm_your_key_here"

{
  "plugins": {
    "slots": {
      "memory": "openclaw-supermemory"
    },
    "entries": {
      "openclaw-supermemory": {
        "enabled": true,
        "config": {
          "apiKey": "sm_...",
          "autoRecall": true,
          "autoCapture": true,
          "maxRecallResults": 10
        }
      }
    }
  }
}

openclaw gateway restart

{
  "plugins": {
    "slots": {
      "memory": "memory-lancedb"
    },
    "entries": {
      "memory-lancedb": {
        "enabled": true
      }
    }
  }
}

curl -fsSL https://bun.sh/install | bash

# Install QMD
bun install -g https://github.com/tobi/qmd

# Add your notes folder
qmd collection add ~/notes --name notes --mask "**/*.md"

# Index everything
qmd embed

# Test it
qmd search "your search query"

curl -X POST <BACKEND_URL>/api/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{
    "agent_id": 1,
    "message": "Hey @Vegeta, I need you to review this PR: #42"
  }'

# Get messages where agent 2 (Vegeta) was mentioned
curl -s "<BACKEND_URL>/api/messages/mentions/2" \
  -H "x-api-key: <API_KEY>"

# Subscribe to real-time events
curl -N "<BACKEND_URL>/api/stream"

# In your agent's heartbeat routine:
def check_mentions(agent_id):
    response = requests.get(
        f"{BACKEND_URL}/api/messages/mentions/{agent_id}",
        headers={"x-api-key": API_KEY}
    )
    mentions = response.json()
    
    for mention in mentions:
        if not mention.get("acknowledged"):
            # Process the mention
            handle_mention(mention)
            
            # Acknowledge it (post a response)
            respond_to_mention(mention)

@Goku: Task #42 complete. @Vegeta please review the PR.

@Piccolo: I'm designing the new auth system. What's the recommended architecture pattern?

@Bulma: Infrastructure is ready. @Trunks you can proceed with deployment.

@Goku: I'm blocked on #45. Need @Gohan to complete the research first.

curl -X POST <BACKEND_URL>/api/tasks \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{
    "title": "🙋 @{{HUMAN_NAME}}: [What you need]",
    "description": "I need your help with...\n\n**Why I am stuck:**\n[Explanation]\n\n**What I need you to do:**\n1. [Step 1]\n2. [Step 2]\n\n**Once done:**\nMove this task to Done and tell me to continue.",
    "status": "todo",
    "agent_id": null
  }'

I've hit a blocker that needs your help! 🙋

I created a task for you on the dashboard:
→ {{FRONTEND_URL}}

Check your To-Do column - there's a task tagged with your name.
Complete it and let me know when you're done!

## 🎯 Claw Beacon Integration

**Dashboard:** {{FRONTEND_URL}}
**API:** {{BACKEND_URL}}

### Core Rules (NON-NEGOTIABLE)

1. **{{COORDINATOR}} = Coordinator ONLY**
   - Delegates tasks, never executes
   - Reviews and verifies work
   - Moves tasks to "completed" only after review

2. **ALL Tasks Through The Board**
   - No task is too small
   - Create task → Assign agent → Track progress → Review → Complete
   - Workflow: backlog → todo → in_progress → review → completed

3. **Quality Gate**
   - Only {{COORDINATOR}} can mark tasks complete
   - Work not up to standard → back to todo with feedback

### Agent Roster (8 Default Agents)

| Agent | Role | Specialization |
|-------|------|----------------|
| {{COORDINATOR}} | Coordinator | Delegation, verification, user comms |
| {{DEVELOPER}} | Backend Engineer | APIs, databases, code reviews |
| {{ARCHITECT}} | System Architect | System design, ADRs, tech decisions |
| {{RESEARCHER}} | Research Analyst | Analysis, documentation, market research |
| {{PM}} | Product Manager | PRDs, user stories, requirements |
| {{DESIGNER}} | UI/UX Designer | User research, wireframes, visual specs |
| {{QA}} | QA Engineer | Adversarial reviews, testing, quality gates |
| {{DEPLOYMENT}} | Deployment Specialist | Releases, hotfixes, CI/CD pipelines |

### ⚡ High-Agency Protocol (ALL AGENTS)

Every agent follows this protocol BEFORE acting:

**Agent-Specific Adaptations:**
- **{{COORDINATOR}} (Coordinator):** Delegates ALL work, never executes. **ENFORCES team rules** — if any agent acts solo, pause and remind them to delegate/query/verify. **ENFORCES the Kanban board** — ALL work goes through the board, no exceptions.
- **{{DEVELOPER}} (Backend):** May query {{ARCHITECT}} for design, {{RESEARCHER}} for research
- **{{ARCHITECT}} (Architect):** May query {{RESEARCHER}} for research, all agents for constraints
- **{{RESEARCHER}} (Research):** May query {{ARCHITECT}} for strategic context, {{PM}} for product context
- **{{PM}} (Product Manager):** May query {{RESEARCHER}} for market data, {{DESIGNER}} for UX
- **{{DESIGNER}} (UI/UX):** May query {{ARCHITECT}} for tech constraints, {{PM}} for requirements
- **{{QA}} (QA Engineer):** Runs adversarial reviews on ALL work. MUST find 3+ issues per review.
- **{{DEPLOYMENT}} (Deployment):** May query {{DEVELOPER}} for code readiness, runs CI/CD

### Reporting Protocol

**Start of task:**
```bash
node scripts/update_dashboard.js --agent "{{AGENT}}" --status "working" --message "Starting: [Task]"

node scripts/update_dashboard.js --agent "{{AGENT}}" --status "idle" --message "Complete: [Task]"

# Progress updates
node scripts/update_dashboard.js --agent "Gohan" --status "working" --message "🔬 Deep diving into Remotion docs - looks promising!"

# Wins
node scripts/update_dashboard.js --agent "Bulma" --status "idle" --message "✅ CI/CD pipeline fixed! Deploys are green again 🚀"

# Insights
node scripts/update_dashboard.js --agent "Vegeta" --status "working" --message "⚡ Found a performance bottleneck - N+1 query in tasks endpoint"

# Blockers
node scripts/update_dashboard.js --agent "Piccolo" --status "working" --message "🚧 Blocked: Need API key for external service"

# Create task
curl -X POST $claw_beacon_URL/api/tasks \
  -H "Content-Type: application/json" \
  -H "x-api-key: $claw_beacon_API_KEY" \
  -d '{"title": "Task name", "status": "backlog"}'

# Assign to agent
curl -X PUT $claw_beacon_URL/api/tasks/ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: $claw_beacon_API_KEY" \
  -d '{"status": "todo", "agent_id": AGENT_ID}'

### 3. Update SOUL.md (Optional but Recommended)

Add to their SOUL.md:

```markdown
## Operating Philosophy

I coordinate a team through Claw Beacon. I don't execute tasks directly.

**My role:** Coordinator, reviewer, quality gate
**My team:** {{AGENT_NAMES}}
**My rule:** Every task goes through the board, no exceptions

When given work:
1. Create task on Claw Beacon
2. Assign to appropriate specialist
3. Monitor progress
4. Review completed work
5. Only then mark complete

curl -s <BACKEND_URL>/api/agents \
  -H "x-api-key: <API_KEY>"

curl -X POST <BACKEND_URL>/api/tasks \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{"title": "👋 Team Introductions", "description": "Introduce the team and explain how the system works.", "status": "completed", "agent_id": 1}'

curl -X POST <BACKEND_URL>/api/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{
    "agent_id": 1,
    "message": "# 👋 Meet Your Team!\n\n## The Squad (8 agents)\n- **[Coordinator]** (me!) - Team lead, delegates, reviews\n- **[Developer]** - Backend APIs, databases, code reviews\n- **[Architect]** - System design, technical decisions\n- **[Researcher]** - Analysis, documentation, research\n- **[PM]** - PRDs, requirements, user stories\n- **[Designer]** - UX research, wireframes, visual specs\n- **[QA]** - Adversarial reviews, testing, quality gates\n- **[Deployment]** - Releases, hotfixes, CI/CD\n\n## How We Work\n1. All tasks go through this board\n2. I delegate to the right specialist\n3. They do the work and report back\n4. I review and mark complete\n\nReady to work! 🦞"
  }'

# Check Qdrant is running
curl -s http://localhost:6333/health

I just completed the Team Introductions task! 

Please check your dashboard: <FRONTEND_URL>

You should see:
- ✅ Your themed agent names in the sidebar
- ✅ A "👋 Team Introductions" task marked complete
- ✅ A welcome message in the feed explaining your team

Can you confirm everything looks right?

🦞 Claw Beacon Setup Complete!

Dashboard: {{FRONTEND_URL}}
Coordinator: {{COORDINATOR}}
Team: {{AGENT_LIST}}

✅ Task management configured
✅ Agent behavior updated
✅ mem0 + Qdrant running - agents have long-term memory!
✅ Session memory hook enabled - conversations auto-save!
{{#if browser}}✅ Browser access ready{{/if}}
{{#if github}}✅ GitHub integration ready{{/if}}
{{#if supermemory}}✅ Supermemory connected - cloud memory active!{{/if}}
{{#if qmd}}✅ QMD search ready - I can search your docs!{{/if}}

From now on, I operate as {{COORDINATOR}}:
- All tasks go through the board
- Specialists do the work
- I coordinate, review, and verify

Let's build something awesome! What's our first task?

# Fetch all tasks
curl -s <BACKEND_URL>/api/tasks -H "x-api-key: <API_KEY>"

# Move task to correct column
curl -X PUT <BACKEND_URL>/api/tasks/ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{"status": "correct_status", "agent_id": CORRECT_AGENT_ID}'

# Check if any agent mentioned you
curl -s "<BACKEND_URL>/api/messages/mentions/<your_agent_id>" \
  -H "x-api-key: <API_KEY>"

cd /path/to/claw-beacon
git fetch origin main
BEHIND=$(git rev-list HEAD..origin/main --count)
if [ "$BEHIND" -gt 0 ]; then
  echo "⚠️ Claw Beacon is $BEHIND commits behind. Consider updating."
  # Optionally auto-update:
  # git pull && docker compose up -d --build
fi

docker compose restart backend
# OR for local: npm run dev (restarts automatically)

# Compare installed skill with latest
npx skills info adarshmishra07/claw-beacon
# If outdated:
npx skills add adarshmishra07/claw-beacon@latest

curl -s http://localhost:6333/health
# Should return {"status":"ok"}

# HEARTBEAT.md - Coordinator Checklist

## Every Heartbeat (Every 30 min)
- [ ] Check board for stuck tasks
- [ ] Check my mentions and respond
- [ ] Fix any misplaced tasks

## 2-3x Daily
- [ ] Check if Claw Beacon needs updating (git fetch, compare commits)
- [ ] Verify Qdrant is healthy (curl health endpoint)
- [ ] Check for skill updates
- [ ] Look for orphan work (commits without task IDs)

## Auto-Fix Protocol
If something is broken:
1. Try to fix it automatically
2. If can't fix → Create a task for the right agent
3. If needs human → Create a 🙋 human task

## What to Post to Feed
- System health issues discovered
- Updates applied
- Orphan work found and retroactively logged

# Test if backend is reachable
curl -s <BACKEND_URL>/api/agents

curl -X POST <BACKEND_URL>/api/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{
    "agent_id": 1,
    "message": "🔄 Skill updated to latest version!\n\n**Status:**\n- ✅ Backend connected\n- ✅ 8 agents configured\n- ✅ mem0 + Qdrant running\n- ⚠️ [List any missing components]\n\n**Action needed:** [If any]"
  }'

{
  "action": "send",
  "message": "Choose your team theme:",
  "buttons": [
    [
      {"text": "🐉 Dragon Ball Z", "callback_data": "theme_dbz"},
      {"text": "☠️ One Piece", "callback_data": "theme_onepiece"}
    ],
    [
      {"text": "🦸 Marvel", "callback_data": "theme_marvel"},
      {"text": "🧪 Breaking Bad", "callback_data": "theme_breakingbad"}
    ]
  ]
}

{
  "action": "send",
  "message": "How do you want to deploy Claw Beacon?",
  "buttons": [
    [{"text": "🚂 Railway (One-Click)", "callback_data": "deploy_railway"}],
    [{"text": "🐳 Docker Compose", "callback_data": "deploy_docker"}],
    [{"text": "💻 Local Dev", "callback_data": "deploy_local"}]
  ]
}

{
  "action": "send",
  "message": "Ready to apply the theme?",
  "buttons": [[
    {"text": "✅ Yes", "callback_data": "confirm_yes"},
    {"text": "❌ No", "callback_data": "confirm_no"}
  ]]
}