# AGENTS.md - Clawdbot Workspace

This folder is the assistant's working directory.

## First run (one-time)
- If BOOTSTRAP.md exists, follow its ritual and delete it once complete.
- Your agent identity lives in IDENTITY.md.
- Your profile lives in USER.md.

## Backup tip (recommended)
If you treat this workspace as the agent's "memory", make it a git repo (ideally private) so identity
and notes are backed up.

```bash
git init
git add AGENTS.md
git commit -m "Add agent workspace"
```

## Safety defaults
- Don't exfiltrate secrets or private data.
- Don't run destructive commands unless explicitly asked.
- Be concise in chat; write longer output to files in this workspace.

## Daily memory (recommended)
- Keep a short daily log at memory/YYYY-MM-DD.md (create memory/ if needed).
- On session start, read today + yesterday if present.
- Capture durable facts, preferences, and decisions; avoid secrets.
- **Mid-day appends:** When a session has been going for hours, append milestones to today's daily log — don't wait until end of day. If the session dies, the work is captured.

## Self-Learning System (MANDATORY)
- **File:** `memory/lessons-learned.md`
- **When:** EVERY time you make a mistake and figure out the fix, or discover something non-obvious
- **What to log:** The mistake, what actually happened, and the rule to follow next time
- **Before attempting anything:** Search lessons-learned.md first to avoid repeating mistakes
- **Categories:** Gateway/Infra, Discord API, Cron Jobs, File Ops, iMessage, Context/Memory, Image Gen, Sub-agents, and any new category as needed
- **Goal:** Never make the same mistake twice. Become mega beastly through constant learning.

## Crash Recovery — Working State (MANDATORY)
- **File:** `memory/working-state.md`
- **Update when:** Starting a task, completing a task, spawning a sub-agent, receiving a sub-agent result
- **After any crash/restart/compaction:** Read `working-state.md` FIRST, then today's daily log, then yesterday's
- **Keep it short:** "Right Now" section + "Today's Done List" + "Pending" — not a novel
- **This replaces HEARTBEAT.md as the source of truth** for "what am I doing right now"

## Daily habit: Git backup
This workspace is a git repo. At end of each day/session:
```bash
cd ~/.clawdbot/workspace
git add -A && git commit -m "Daily backup: YYYY-MM-DD" && git push
```
This keeps identity, memory, and progress backed up. Consider making it private on GitHub.

## Customize
- Add your preferred style, rules, and "memory" here.

## Smart Model Routing (MANDATORY)

**Default model: Sonnet** — use `session_status(model="sonnet")` at session start if on Opus.

### Auto-escalate to Opus for:
- Multi-step architecture, system design, complex debugging
- Deep research synthesis (5+ sources, strategic analysis)
- Creative/nuanced writing, security analysis, pentesting strategy
- Business strategy, financial projections
- Anything Jake explicitly says needs deep thinking
- **How:** call `session_status(model="opus")`, do the work, then switch back to Sonnet

### Stay on Sonnet for:
- File reads, git ops, simple commands, quick lookups
- Casual chat, short answers, sending messages
- Memory searches, simple code edits, routine maintenance
- Anything that's basically CRUD or lookup

### Spawn sub-agent on Opus for:
- Heavy research (competitive analysis, market research)
- Building entire files/projects from scratch
- Long code generation, multi-file refactors
- **Why:** keeps main session context lean, isolates expensive work

### Label every message:
- End every reply with a model tag: `· sonnet` or `· opus`
- This costs ~2 tokens, helps Jake track what's being used

## MCP Work — MANDATORY Commit Rule

**ALL MCP-related work MUST be committed and pushed to `mcpengine-repo/` (`BusyBee3333/mcpengine`).**

This is non-negotiable. The mcpengine repo is the single source of truth.

### What goes where:
- New MCP server → `mcpengine-repo/servers/{platform-name}/`
- MCP apps/UI → `mcpengine-repo/servers/{platform-name}/src/apps/` or `ui/`
- Factory tools → `mcpengine-repo/infra/factory-tools/`
- Pipeline state → `mcpengine-repo/infra/command-center/`
- Reviews/evals → `mcpengine-repo/infra/factory-reviews/`
- Landing pages → `mcpengine-repo/landing-pages/`
- MCP research/docs → `mcpengine-repo/docs/`

### Workflow:
1. Can build in workspace for speed (scratch space)
2. When done: `rsync -a --exclude='node_modules' --exclude='.git' src/ mcpengine-repo/servers/{name}/`
3. `cd mcpengine-repo && git add -A && git commit -m "{name}: {what}" && git push`
4. **Never** leave MCP work as loose workspace directories without also syncing to mcpengine

### Also push to individual repos when they exist:
- GHL → `BusyBee3333/Go-High-Level-MCP-2026-Complete`
- 30 original servers → `BusyBee3333/{name}-mcp-2026-complete`

## Discord-specific rule
- If you ever feel like you lack context in a Discord conversation, **proactively read the past few messages** in that channel using the message tool (action=search or action=read with before/after parameters) before asking for clarification.

## Research Intel Memory System
For ongoing research/monitoring (competitor tracking, market research, intel gathering):
- **Store in:** `memory/{project}-research-intel.md`
- **Format:** Current week's detailed intel at TOP, compressed 1-3 sentence summaries of previous weeks at BOTTOM
- **Weekly maintenance:** Compress previous week to summary, add new detailed intel at top
- **When to check:** Any request for "action items from research," "what should we do based on X," or strategic decisions
- **Active files:** Check USER.md for list of active research intel files