302 lines
9.9 KiB
Markdown
302 lines
9.9 KiB
Markdown
|
|
|
|
---
|
|
|
|
## 📋 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. |