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.