AGENTS/AGENT_USAGE.md

# Agent Usage Guide

This guide documents the specialized non-coding subagents available in the Opencode environment. These agents are designed to handle specific types of requests through an auto-routing system based on trigger keywords.

## 🚀 Auto-Routing System

Opencode uses an intelligent routing system that analyzes your request and delegates it to the most appropriate specialized agent. When you use specific keywords (triggers), the system automatically invokes the corresponding subagent to handle your request.

## 🤖 Specialized Agents

### ✍️ Writing Agent
**Archetype**: Muse of Eloquence and Composition
**Role**: Long-form content creation specialist.

| Feature | Details |
|---------|---------|
| **Triggers** | `write`, `draft`, `compose`, `document`, `report` |
| **Scope** | Reports, documentation, proposals, articles, technical writing, project plans. |
| **Permissions** | Write access to `~/CODEX` for saving documents. |

**Example Requests:**
- "Draft a project proposal for the new API integration."
- "Write a technical report on the system architecture changes."
- "Compose an article about the benefits of NixOS for developers."

**Boundaries:**
- Focuses on long-form, structured content.
- **NOT** for brief emails or chat messages (use the communications skill for those).
- Does not execute code or perform system changes.

---

### 💡 Brainstorming Agent
**Archetype**: Muse of Creative Ideation
**Role**: Creative ideation specialist focused on divergent thinking.

| Feature | Details |
|---------|---------|
| **Triggers** | `brainstorm`, `ideate`, `creative`, `explore options`, `what if` |
| **Scope** | Idea generation, option exploration, lateral thinking, strategic ideation. |
| **Permissions** | Read-only (consultation). Can offer to save results to Obsidian. |

**Example Requests:**
- "Brainstorm some creative ideas for the upcoming marketing campaign."
- "What if we shifted our focus to a mobile-first strategy?"
- "Explore options for improving user engagement in the app."

**Boundaries:**
- Focuses on expanding the possibility space and generating options.
- **NOT** for implementation or execution of ideas.
- Provides recommendations but does not make final decisions.

---

### 🧘 Productivity Coach Agent
**Archetype**: Mentor and Strategic Advisor
**Role**: Productivity mentor for advice, prioritization, and workflow guidance.

| Feature | Details |
|---------|---------|
| **Triggers** | `coach`, `mentor`, `productivity advice`, `how should I`, `prioritize`, `focus` |
| **Scope** | Coaching conversations, PARA methodology guidance, prioritization advice. |
| **Permissions** | Read-only (coaching). |

**Example Requests:**
- "How should I prioritize my tasks for this week?"
- "Give me some productivity advice for managing deep work sessions."
- "Coach me on how to better organize my projects using PARA."

**Boundaries:**
- Focuses on guiding your thinking and decision-making.
- **NOT** for executing workflows or managing tasks directly (use `daily-routines` or `task-management`).
- Does not make decisions for you; helps you reach your own insights.

---

### 🎯 Strategy Agent
**Archetype**: Strategic Planning Specialist
**Role**: High-level strategic thinking for long-term planning and decision frameworks.

| Feature | Details |
|---------|---------|
| **Triggers** | `strategy`, `strategic planning`, `high-level plan`, `long-term vision`, `how should we approach` |
| **Scope** | Strategic analysis, long-term vision, decision frameworks, organizational strategy. |
| **Permissions** | Read-only (strategic planning). |

**Example Requests:**
- "What should be our long-term vision for the product ecosystem?"
- "How should we approach the market expansion into new regions?"
- "Develop a strategic framework for evaluating new project opportunities."

**Boundaries:**
- Focuses on high-level "what and why" rather than tactical "how".
- **NOT** for detailed project planning (use `plan-writing`) or tactical execution.
- Distinguishes between strategic goals and tactical tasks.

---

### 🤝 Meeting Facilitator Agent
**Archetype**: Master of Structured Collaboration
**Role**: Meeting facilitation specialist for agenda planning and structure guidance.

| Feature | Details |
|---------|---------|
| **Triggers** | `facilitate meeting`, `run meeting`, `meeting guidance`, `how to facilitate`, `agenda planning` |
| **Scope** | Agenda design, facilitation techniques, time management, inclusive participation. |
| **Permissions** | Read-only (facilitation guidance). |

**Example Requests:**
- "Help me plan an agenda for the upcoming team sync meeting."
- "How can I facilitate a decision-making meeting more effectively?"
- "Provide guidance on managing dominant voices during workshops."

**Boundaries:**
- Focuses on the *process* of running effective meetings.
- **NOT** for taking meeting notes (use `meeting-notes`) or scheduling (use `calendar-scheduling`).
- Does not execute action items resulting from meetings.

---

## 🛠️ Troubleshooting Routing Issues

If your request is not being routed to the correct agent:

1. **Check Keywords**: Ensure you are using one of the trigger keywords listed for the desired agent.
2. **Be Explicit**: If auto-routing fails, you can explicitly ask: "As the [Agent Name], help me with..."
3. **Clarify Intent**: If the request is too vague, the system might default to the primary assistant (Chiron). Provide more context about the type of help you need.

## ➕ Adding New Agents

To add a new specialized agent in the future:

1. **Define the Agent**: Add a new entry in `agents/agents.json` with its description, model, and triggers.
2. **Create System Prompt**: Create a new `.txt` file in the `prompts/` directory defining the agent's identity, responsibilities, and processes.
3. **Update Permissions**: Ensure the agent has the necessary permissions (read/write/bash) for its intended scope.
4. **Register Triggers**: Add the trigger keywords to the `triggers` array in `agents/agents.json` to enable auto-routing.
5. **Update Documentation**: Add the new agent to this `AGENT_USAGE.md` file.