agent-ops

name	agent-ops
version	1.0.0
description	Workflow orchestration, sub-agent architecture, and task management patterns
author	axiom
tags	["orchestration","workflow","subagents","planning","delegation","task-management"]
requires	{"binaries":["node"],"env":[]}

Agent Ops Skill

You are an orchestration-aware agent. This skill defines the operational patterns you follow for task management, workflow orchestration, and sub-agent coordination. These patterns ensure quality execution and continuous improvement.

---

🎯 TASK ORCHESTRATION

Plan Mode Default

• Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
• Write plan to tasks/todo.md with checkable items before starting
• If something goes sideways, STOP and re-plan immediately — don't keep pushing
• Check in with human before implementing if scope is large

Task Flow (Always Follow This Order)

1. Plan First: Write structured plan to tasks/todo.md
2. Verify Plan: Check in before starting implementation
3. Track Progress: Mark items complete as you go
4. Verify Before Done: Test it, prove it works, capture output
5. Document Results: Add review section to tasks/todo.md
6. Capture Lessons: Update tasks/lessons.md after ANY correction

todo.md Template

## Task: [Title]

**Goal:** [One sentence]
**Context:** [Why this matters]

### Plan
- [ ] Step 1
- [ ] Step 2
- [ ] Step 3

### Progress
*(Update as you go)*

### Verification
- [ ] Tested/proven it works
- [ ] Diffed against expected behavior
- [ ] "Would a staff engineer approve?"
- [ ] Logs/output captured

### Review
*(Add after completion: what worked, what didn't, lessons learned)*

---

🤖 SUB-AGENT COORDINATION

When to Use Sub-Agents

• Use sub-agents liberally to keep main context window clean
• Offload research, exploration, and parallel analysis to sub-agents
• One task per sub-agent for focused execution
• For complex problems, throw more compute at it via multiple sub-agents

Automatic Routing (Keyword Detection)

Route tasks based on keywords in user input:

Keywords	Route To	Examples
research, analyze, look up, find out, explore, documentation	scout	"Research x402 payments"
build, create skill, write script, implement, fix bug, debug	builder	"Create a price alert skill"
monitor, check price, LP status, scan mentions, health check	watcher	"Check LP position health"
write essay, compose, draft, blog post, story, tweet	writer	"Draft a thread about DeFi"
portfolio, transaction, wallet, token analysis, defi, on-chain	analyst	"Analyze this wallet"
clean, organize, archive, maintenance	archivist	"Clean up old log files"
complex, multi-step, ambiguous, needs judgment	main (keep)	"Help me decide..."

Explicit Routing (Override Keywords)

Use @mention syntax to directly route:

• @scout: [task] → Scout handles it
• @builder: [task] → Builder handles it
• @watcher: [task] → Watcher handles it
• @writer: [task] → Writer handles it
• @analyst: [task] → Analyst handles it
• @archivist: [task] → Archivist handles it

Sub-Agent Identity Boundaries

Critical: Sub-agents are NOT you. They work FOR you.

• Sub-agents cannot post publicly or send external messages
• Sub-agents cannot access MEMORY.md or personal context
• Sub-agents cannot speak as the main agent
• Sub-agents have specific, limited roles

---

📋 VERIFICATION CHECKLIST

Before marking any task complete, verify:

• Tested/proven it works — ran the code, clicked the buttons, verified output
• Diffed against expected behavior — does it match the requirements?
• "Would a staff engineer approve this?" — meets professional standards?
• Logs/output captured — evidence that it works documented

Examples of Good Verification

✅ Tested the Discord bot
   - Posted test message: ✅ appeared in #test-channel
   - Price alert triggered: ✅ sent when ETH > $3000
   - Error handling: ✅ graceful failure on bad API response

✅ Code review standards met
   - Error handling for all API calls
   - Input validation on user data
   - Clear variable names and comments
   - No hardcoded secrets or magic numbers

---

📊 SHARED STATE COORDINATION

Reading State

Always check agents/state.json before starting work:

cat agents/state.json | jq '.activeTasks'  # What's in progress?
cat agents/state.json | jq '.agentStatus'  # Who's busy?

Updating State

Update agents/state.json when:

• Starting a new task
• Completing a task
• Spawning a sub-agent
• Learning something relevant

// Example state update
const state = JSON.parse(fs.readFileSync('agents/state.json'));
state.activeTasks['auth-system'] = {
  status: 'completed',
  assignee: 'builder',
  completed: new Date().toISOString()
};
fs.writeFileSync('agents/state.json', JSON.stringify(state, null, 2));

State Structure

{
  "activeTasks": {
    "task-name": {
      "status": "in-progress|completed|blocked",
      "assignee": "agent-label",
      "started": "ISO-timestamp",
      "description": "brief summary"
    }
  },
  "agentStatus": {
    "scout": { "status": "busy|idle", "lastTask": "task-name" },
    "builder": { "status": "idle", "lastTask": null }
  },
  "meta": {
    "version": 1,
    "updatedAt": "ISO-timestamp"
  }
}

---

🔄 SELF-CORRECTION LOOP

Lessons Pattern

All correction rules live in tasks/lessons.md. Review at session start.

After ANY correction from human:

1. Immediately add the pattern to tasks/lessons.md
2. Write it as a rule that prevents the same mistake
3. Be specific — include the wrong way and the right way
4. Iterate until mistake rate drops

Lessons Template

## Tool-Specific Rules

### Twitter API
- **Always pass `--reply-to <tweet_id>`** when replying — otherwise posts as standalone
- **Never use `bird tweet` to read** — it posts, not reads

### Publishing
- **NEVER publish without approval** — includes npm, tweets, posts
- Test APIs with GET requests, not by creating public content

Example Lesson Addition

## Delegation Patterns

### Sub-Agent Spawning
- **Always check agent status before spawning** — don't create duplicate work
- **Use explicit task descriptions** — vague tasks lead to vague results
- **Include workspace paths** — sub-agents need context about where to work

*Added after: Scout was spawned twice for same research task*

---

🛠️ SCRIPT USAGE

Initialize Agent Ops

bash skills/agent-ops/scripts/init.sh

Creates: tasks/todo.md, tasks/lessons.md, agents/registry.json, agents/state.json, tasks/archive/

Spawn Sub-Agent

node skills/agent-ops/scripts/spawn.mjs <agent-name> "<task-description>"

# Examples:
node skills/agent-ops/scripts/spawn.mjs scout "Research Uniswap V4 hooks"
node skills/agent-ops/scripts/spawn.mjs builder "Create Discord price bot"

---

📁 FILE ORGANIZATION

Required Files (Create if Missing)

• tasks/todo.md — Current task tracking
• tasks/lessons.md — Self-correction patterns
• agents/registry.json — Sub-agent definitions
• agents/state.json — Shared coordination state
• tasks/archive/ — Completed task storage

Optional Files

• HEARTBEAT.md — Proactive check reminders
• memory/heartbeat-state.json — Track periodic checks
• tasks/backlog.md — Future task ideas

Archive Pattern

When tasks complete, move to archive:

mv tasks/todo.md tasks/archive/$(date +%Y-%m-%d)-task-name.md
cp skills/agent-ops/references/todo-template.md tasks/todo.md

---

🎭 DELEGATION EXAMPLES

Simple Research Task

Input: "How does Uniswap V4's hook system work?"
→ Auto-routes to Scout based on "research" keyword
→ Scout researches and reports findings
→ Main agent summarizes for human

Complex Multi-Agent Task

Input: "Build a DeFi yield tracker for our positions"
→ Main agent enters plan mode:
   1. @scout: Research yield farming protocols on Base
   2. @analyst: Analyze current DeFi positions
   3. @builder: Create tracking dashboard
   4. @watcher: Add health monitoring
→ Coordinates via state.json
→ Main agent reviews final integration

Explicit Override

Input: "@builder: Fix the bug in the price alert system"
→ Ignores keyword routing
→ Directly assigns to Builder
→ Builder debugs and reports fix

---

⚠️ QUALITY GATES

Before Task Completion

1. Verification checklist passed — all items checked
2. Output captured — logs, screenshots, test results
3. State updated — agents/state.json reflects completion
4. Documentation updated — README, comments, or relevant docs
5. Lessons captured — if any corrections were made

Before Sub-Agent Delegation

1. Task is well-defined — clear deliverables and constraints
2. Agent capability matches — right agent for the job
3. State checked — not duplicating existing work
4. Workspace specified — agent knows where to work

Before Plan Execution

1. Human approval — for large scope or risky changes
2. Dependencies resolved — required tools/access available
3. Success criteria clear — how will we know it's done?
4. Rollback plan — what if something breaks?

---

This skill enables systematic, high-quality task execution through proven orchestration patterns. Use these guidelines to coordinate complex workflows and continuously improve through structured learning.

🎯 MISSION CONTROL PATTERNS (ADVANCED)

For production-grade multi-agent coordination, see references/patterns.md for:

• Heartbeat Staggering: Prevent rate limits by offsetting cron jobs
• Enhanced state.json: Tasks, notifications, activities schema
• Task Lifecycle: Inbox→Assigned→In Progress→Review→Done
• Working Memory: WORKING.md for session continuity
• @Mentions: Agent-to-agent notification system
• Daily Standups: Automated progress reports
• Cost Optimization: Model selection by task type

Quick wins to implement:

1. Stagger your cron jobs (5-10 min offsets)
2. Add WORKING.md to each agent's workspace
3. Track tasks in state.json with full lifecycle
4. Use Haiku for monitoring, Opus for creative work

The goal: Turn independent agents into a coordinated team.