---

## 📋 Research Workflow - URL → Document + Task + Plan

**When I say:** *"Research this URL"*

**Alice-Researcher MUST deliver:**
1. ✅ Document in Mission Control Documents
2. ✅ Task in Gantt Board (current sprint for today's date)
3. ✅ Analysis in task description (fit against current infrastructure)
4. ✅ **IMPLEMENTATION PLAN ATTACHED if verdict is ADOPT or EVALUATE_LATER**

**Skill file:** `/Users/mattbruce/.agents/skills/url-research-to-documents-and-tasks/SKILL.md`

**Critical checks:**
- Sprint must contain today's date (auto-detected)
- Verdict options: ADOPT / EVALUATE_LATER / PASS
- **Only PASS skips the implementation plan**
- Plan must include: Overview, Current vs Proposed, Phases, Risks, Timeline

**Verification before completion:**
```
- [ ] Document exists in Mission Control
- [ ] Task in correct sprint
- [ ] Analysis in description
- [ ] Implementation plan attached (if ADOPT/EVALUATE_LATER)
```

---

## 🤖 Agent Workflow - Checklist-Based Task Execution

**All agents (Alice/Bob/Charlie) MUST use this checklist format for task updates:**

### **Comment Format (MANDATORY):**
```markdown
## [YYYY-MM-DD HH:MM] 🔄 [STATUS] - [Agent Name]

### ✅ Completed
- [x] Task 1: Description - **DONE** - Details
- [x] Task 2: Description - **DONE** - Details
- [ ] Task 3: Description - **IN PROGRESS** - Current status

### 🔄 In Progress
- [ ] Task 4: Description - Started at HH:MM, expected completion HH:MM

### 📋 Remaining
- [ ] Task 5: Description - Prerequisites: X, Y
- [ ] Task 6: Description - Blocked by: Z
- [ ] Task 7: Description - Estimated effort: X hours

### 🎯 Next Steps
1. [Immediate next action]
2. [Follow-up action]
3. [Final validation]

### 🚨 Blockers (if any)
- [Issue]: [Description] - [Solution attempt]

### 📊 Progress: X/Y tasks complete (Z%)
```

### **Resumability Rules:**
- **Every session starts** by reading ALL previous comments chronologically
- **Resume from last incomplete task** in checklist
- **Never repeat completed work** - check ✅ Completed section
- **Update progress** before ending session

### **Agent-Specific Checklists:**

**Alice-Researcher:**
- ✅ Extract content from URL (Tavily → Scrapling fallback)
- ✅ Create Mission Control document
- ✅ Create Gantt Board task in current sprint
- ✅ Analyze fit vs current infrastructure
- ✅ Attach implementation plan (if ADOPT/EVALUATE_LATER)

**Bob-Implementer:**
- ✅ Understand requirements from task description/comments
- ✅ Plan implementation approach
- ✅ Write/modify code with tests
- ✅ Run tests and validate locally
- ✅ Commit changes with clear message
- ✅ Update documentation if needed

**Charlie-Tester:**
- ✅ Review code changes and understand requirements
- ✅ Run automated tests
- ✅ Manual testing of all functionality
- ✅ Check edge cases and error handling
- ✅ Update task to done when approved

### **Status Flow:**
- **open** → **in-progress** (starting work)
- **in-progress** → **review** (implementation complete, needs validation)
- **review** → **done** (approved/validated)

### **CLI Commands for Updates:**
```bash
# Update status
./task.sh update [task_id] --status in-progress

# Add detailed progress comment
./task.sh update [task_id] --comment "[full checklist markdown]"
```

**This ensures perfect resumability** — if an agent fails, the next session continues exactly where it left off.

---

## 🔧 Configuration Management

### **TOOLS.md = Single Source of Truth**
**ALL configuration variables and endpoints must be documented in TOOLS.md:**

- Service URLs (production + dev)
- API keys and credentials
- Database connection strings
- Authentication tokens
- File paths and directories
- Environment-specific settings

**If information is missing from TOOLS.md:**
- Stop and ask user to add it
- Do NOT guess or use defaults
- Document what was needed for future reference

**Self-Healing Pattern:**
When operations fail:
1. Check TOOLS.md for correct configuration
2. Retry with documented values
3. Log what was missing for user to add

**Endpoint Resolution:**
- **Production services**: Use URLs from TOOLS.md
- **Local development**: Use localhost only when explicitly testing local
- **Automation/cron jobs**: Always use production endpoints

---

## 📅 Sprint Management

### **Task Creation Rules**
- **ALWAYS find sprint containing today's date** when creating tasks
- If no sprint contains today → use most recent sprint
- Tasks must be in current sprint for automated workers to find them

### **Auto-Status Feature Needed**
- Sprints should auto-update status based on date:
  - `planning` → `active` when today >= start_date
  - `active` → `completed` when today > end_date
- Prevents manual sprint management overhead

---

## 🔄 Automation & Cron Jobs

### **Gantt Board Task Worker (24/7)**
- Runs hourly, checks current sprint for open/todo/in-progress tasks
- Works on highest priority task using agent workflow
- Updates with detailed checklist comments
- Uses programmatic login (no stored cookies)

### **Subagent Status Monitor (20-min)**
- Checks every 20 minutes if subagents are running
- If idle: Queries current sprint for available tasks
- Spawns appropriate agents (Alice/Bob/Charlie) to work on tasks
- Ensures continuous progress on backlog

### **Authentication for Automation**
- Cron jobs use programmatic login with stored credentials
- Login every hour keeps session fresh (30-day limit)
- No manual cookie management needed

---

## 🌐 Web Scraping & Research

### **X/Twitter Content Extraction**
- Primary: Tavily search (fast, clean results)
- Fallback: Scrapling StealthyFetcher (bypasses anti-bot protections)
- DynamicFetcher for complex sites requiring full browser
- Ensures research workflow works even on protected content

### **Research Workflow Triggers**
- User says: "Research this URL", "Save this article", "Summarize and create task"
- Alice-Researcher handles extraction, analysis, task creation
- Verdict determines if implementation plan is attached

---

## 🏗️ API-Centric CLI Pattern

**When building web apps with CLI companions:**

### Golden Rule
**API = single source of truth. CLI = passthrough client only.**

### Non-Negotiables
- ✅ All business logic lives in API/server code
- ✅ CLI only parses args, calls API, formats output
- ✅ No direct DB calls from CLI
- ✅ If CLI needs new behavior → add to API first
- ✅ Every CLI command has contract tests with mocked API

### Why This Matters
Prevents the Gantt Board situation where CLI scripts had duplicate logic, direct DB access, and broke when API changed. Now CLI is a thin client like the web UI.

### Skill
`/Users/mattbruce/.agents/skills/api-cli-passthrough/SKILL.md`

### Test Requirements
- API unit tests (domain logic)
- API integration tests (routes)
- CLI contract tests (mocked API transport)

---

## 🗄️ Shared Supabase Database - CRITICAL: Table Naming Convention

**Rule:** `<project_name>_<table_name>` with underscores (NO hyphens)

**Why:** All Vercel apps share one Supabase project to prevent collisions

**Current Prefixes:**
- *(none)* — Gantt Board (legacy - `tasks`, `projects`, `sprints` - no prefix)
- `blog_` — Blog Backup (messages, tags)  
- `mission_control_` — Mission Control (documents, folders)
- `heartbeat_` — Heartbeat Monitor (status, logs)

**Note:** Gantt Board is the legacy app (no prefixes). All NEW apps MUST use prefixes.

**Full doc:** `DB_TABLE_NAMING.md`

**Remember:** Always prefix, always underscores, never abbreviate!

---

## 🚀 Mission Control Future Vision — Voxyz Inspiration

**Date Added:** February 22, 2026
**Source:** X/Twitter Article by Vox ([@Voxyz_ai](https://x.com/Voxyz_ai))
**Article Title:** *"I Built an AI Company with OpenClaw + Vercel + Supabase — Two Weeks Later, They Run It Themselves"*

**Key Insights:**
- 6-agent autonomous company with closed-loop operations
- Single proposal service, cap gates, reaction matrix
- Self-healing system with 30-min stale task detection
- Long-term vision: Agents propose and execute tasks autonomously

**Current Application:** Focus on dashboard (Phases 6-9) before autonomous operations

---

## 🤖 Subagent Orchestration Rules (MANDATORY)

**NON-NEGOTIABLE rules for Alice/Bob/Charlie:**

1. **Progress Comments:** Every 15 minutes using checklist format
2. **Timeout Behavior:** Complete work OR explain blocker - never die silently
3. **Status Rules:** Only humans mark tasks "done" - agents end with "Ready for [next]"
4. **Spawn Template:** Include rules, SOUL.md path, and timeout instructions

**Cap Gates:** Maximum 3 review cycles before human escalation

**Task Admission:** Clear deliverables, success criteria, <2 hour effort before spawning

---

## 🔄 **System Restart & Session Start Requirements (MANDATORY)**

### **Post-Restart Verification Protocol**
**After ANY OpenClaw gateway restart or new session start:**

1. **Run the verification checklist:** `/Users/mattbruce/.openclaw/workspace/post-restart-checklist.md`
2. **Check each item systematically** - don't skip any section
3. **Document any failures** in the checklist with fixes applied
4. **Update the checklist** if new issues are discovered
5. **Confirm all systems operational** before proceeding with work

**Why this is critical:**
- Subagents, APIs, and configurations require restart to activate
- Prevents "everything worked before restart" assumptions
- Catches configuration issues immediately
- Ensures workflow continuity across sessions

**Checklist maintenance:**
- Add new verification items as systems are added
- Document common failure modes and their fixes
- Keep current with latest architecture changes
- Reference when subagents fail to spawn or APIs don't work

**Triggers for checklist:**
- OpenClaw gateway restart (manual or automatic)
- New session start after system changes
- Subagent spawning failures
- API authentication issues
- Configuration changes applied

**This is now a CORE OPERATIONAL REQUIREMENT.** The checklist ensures system reliability and prevents regression.