📝 docs: improve documentation for new users with video, TL;DR, and clearer guidance
This commit is contained in:
darrenhinde
parent
93b9bbc1a6
commit
88b3445f10
2 changed files with 470 additions and 71 deletions
|
|
@ -2,6 +2,86 @@
|
|||
|
||||
_Build Intelligent Workflow Systems with Context-Aware AI_
|
||||
|
||||
---
|
||||
|
||||
## ⚡ TL;DR - Quick Reference
|
||||
|
||||
**For New Users:**
|
||||
- Start with `opencode --agent codebase-agent` for all development work
|
||||
- The agent handles planning, implementation, testing, and review automatically
|
||||
- Add your coding patterns to `.opencode/context/project/project-context.md`
|
||||
- Let the agent delegate to specialized subagents when needed
|
||||
|
||||
**For Advanced Users:**
|
||||
- Read this document to understand how to create custom agents and commands
|
||||
- Learn how context loading works (the `@` symbol)
|
||||
- Extend the system with domain-specific context files
|
||||
- Build specialized workflows for repeated patterns
|
||||
|
||||
**Core Concept:**
|
||||
```
|
||||
Commands load context → Agents execute with that context → Subagents handle specialized tasks
|
||||
```
|
||||
|
||||
**When to read this document:**
|
||||
- ✅ You want to create custom agents or commands
|
||||
- ✅ You need to understand how context loading works
|
||||
- ✅ You want to extend the system for your specific needs
|
||||
- ❌ You just want to start building (use `codebase-agent` instead)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 About This Document
|
||||
|
||||
This blueprint is a **teaching document** that explains agent system architecture patterns. It uses examples to teach concepts like context loading, agent orchestration, and workflow management.
|
||||
|
||||
> **📖 Installation & Usage:** See [README.md](../../README.md) in the repository root.
|
||||
|
||||
### What You'll Learn
|
||||
|
||||
This document teaches:
|
||||
- ✅ How context loading works (the `@` symbol magic)
|
||||
- ✅ Agent architecture and role separation
|
||||
- ✅ Workflow orchestration patterns
|
||||
- ✅ How to extend the system with custom agents/commands
|
||||
- ✅ How to add domain-specific context files
|
||||
|
||||
### Understanding Examples in This Document
|
||||
|
||||
**When you see commands like `/workflow`, `/plan-task`, `/create-frontend-component`:**
|
||||
- These are **pattern examples** showing how you COULD structure commands
|
||||
- Most aren't implemented in the repository
|
||||
- The existing `codebase-agent` already handles these workflows
|
||||
- Create them only if you have specific repeated patterns
|
||||
|
||||
**When you see extensive context hierarchies:**
|
||||
- The repository includes `core/` and `project/` context files
|
||||
- Add domain-specific files (`frontend/`, `backend/`, `database/`) as needed
|
||||
- Start simple, expand based on your needs
|
||||
|
||||
**When you see task management structures:**
|
||||
- The `task-manager` agent creates `tasks/` directories automatically
|
||||
- No need to pre-create structures
|
||||
|
||||
### The Working System
|
||||
|
||||
The repository provides a complete working system:
|
||||
|
||||
```bash
|
||||
# This works right now:
|
||||
opencode --agent codebase-agent
|
||||
> "Create a user authentication system"
|
||||
|
||||
# The agent will:
|
||||
# 1. Plan implementation
|
||||
# 2. Ask for approval
|
||||
# 3. Delegate to @task-manager for complex features
|
||||
# 4. Use @tester for tests
|
||||
# 5. Use @reviewer for security
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Golden Rule
|
||||
|
||||
**Context flows in one direction: Commands load context immediately, Agents can look up additional context deterministically.**
|
||||
|
|
@ -757,4 +837,143 @@ if (!validated.success) return { error: "Validation failed" };
|
|||
|
||||
---
|
||||
|
||||
## Extending This System
|
||||
|
||||
You can extend this system by adding the example commands and agents mentioned throughout this blueprint. Here's how:
|
||||
|
||||
### Adding Workflow Commands (Optional)
|
||||
|
||||
If you want specialized commands like `/workflow` or `/create-frontend-component`:
|
||||
|
||||
1. **Create the command file:**
|
||||
```bash
|
||||
# Example: .opencode/command/workflow.md
|
||||
---
|
||||
name: workflow
|
||||
agent: workflow-orchestrator
|
||||
---
|
||||
|
||||
You are analyzing requests and routing to optimal workflows.
|
||||
|
||||
**Request:** $ARGUMENTS
|
||||
|
||||
@.opencode/context/core/essential-patterns.md
|
||||
@.opencode/context/project/project-context.md
|
||||
|
||||
Route to appropriate agent or handle directly.
|
||||
```
|
||||
|
||||
2. **Or just use `codebase-agent` directly:**
|
||||
```bash
|
||||
opencode --agent codebase-agent
|
||||
> "Your request here"
|
||||
```
|
||||
|
||||
### Adding Domain-Specific Context
|
||||
|
||||
Extend the context hierarchy for your tech stack:
|
||||
|
||||
```bash
|
||||
# Create domain-specific context files
|
||||
mkdir -p .opencode/context/frontend
|
||||
mkdir -p .opencode/context/backend
|
||||
mkdir -p .opencode/context/database
|
||||
|
||||
# Add your patterns
|
||||
cat > .opencode/context/frontend/react-patterns.md << 'EOF'
|
||||
**React Component Pattern:**
|
||||
```tsx
|
||||
export function MyComponent({ prop }: Props) {
|
||||
// Your pattern here
|
||||
}
|
||||
```
|
||||
EOF
|
||||
```
|
||||
|
||||
Then reference in your commands:
|
||||
```markdown
|
||||
@.opencode/context/frontend/react-patterns.md
|
||||
@.opencode/context/backend/api-patterns.md
|
||||
```
|
||||
|
||||
### Building Specialized Agents
|
||||
|
||||
Create domain-specific agents following the patterns:
|
||||
|
||||
```bash
|
||||
# Example: .opencode/agent/frontend-specialist.md
|
||||
---
|
||||
description: "React frontend development specialist"
|
||||
mode: primary
|
||||
tools: [read, edit, write, bash]
|
||||
---
|
||||
|
||||
You are a React frontend specialist.
|
||||
|
||||
**ANALYZE** the request and create components following patterns:
|
||||
@.opencode/context/frontend/react-patterns.md
|
||||
|
||||
Execute implementation now.
|
||||
```
|
||||
|
||||
### Recommended Extensions by Project Type:
|
||||
|
||||
**Frontend Project:**
|
||||
- Add `context/frontend/react-patterns.md`
|
||||
- Add `context/styling/design-system.md`
|
||||
- Create `/create-component` command
|
||||
- Use `codebase-agent` with frontend context
|
||||
|
||||
**Backend Project:**
|
||||
- Add `context/backend/api-patterns.md`
|
||||
- Add `context/database/query-patterns.md`
|
||||
- Create `/create-api-endpoint` command
|
||||
- Use `codebase-agent` with backend context
|
||||
|
||||
**Full-Stack Project:**
|
||||
- Use all context files
|
||||
- Create domain-specific commands
|
||||
- Let `codebase-agent` coordinate between domains
|
||||
|
||||
### The Simple Path (Recommended for Starters):
|
||||
|
||||
**Don't create specialized commands/agents right away. Instead:**
|
||||
|
||||
1. **Start with `codebase-agent`** for everything
|
||||
2. **Add context files** for your tech stack as needed
|
||||
3. **Use `@task-manager`** when features get complex
|
||||
4. **Let subagents** handle specialized work (@tester, @reviewer)
|
||||
5. **Create specialized commands** only when you have repeated workflows
|
||||
|
||||
**Example progression:**
|
||||
```bash
|
||||
# Week 1: Use codebase-agent for everything
|
||||
opencode --agent codebase-agent
|
||||
|
||||
# Week 2: Add project-specific context
|
||||
echo "Your patterns" > .opencode/context/project/api-patterns.md
|
||||
|
||||
# Week 3: Reference in codebase-agent
|
||||
# The agent will automatically pick up context from project/
|
||||
|
||||
# Week 4: Create a command if you have a repeated workflow
|
||||
# Only if you find yourself doing the same thing repeatedly
|
||||
```
|
||||
|
||||
### How to Improve This System
|
||||
|
||||
The system improves naturally as you:
|
||||
|
||||
1. **Add context files** - Capture your coding patterns
|
||||
2. **Refine agent prompts** - Improve instructions based on results
|
||||
3. **Create project-specific commands** - Automate repeated workflows
|
||||
4. **Build subagents** - Extract specialized capabilities
|
||||
5. **Document in context/** - Every pattern you discover
|
||||
|
||||
**The key principle:** Start simple, extend only when you have a clear need.
|
||||
|
||||
---
|
||||
|
||||
_Think of this system like a professional development team: each member has a specific role, they communicate clearly, they track their work systematically, and they validate quality at every step._
|
||||
|
||||
_The `codebase-agent` is your senior developer who can handle most tasks. Add specialists only when needed._
|
||||
|
|
|
|||
322
README.md
322
README.md
|
|
@ -2,96 +2,261 @@
|
|||
|
||||
A set of OpenCode configurations, prompts, agents, and plugins for enhanced development workflows.
|
||||
|
||||
## Features
|
||||
[](https://youtu.be/EOIzFMdmox8?si=4ZSsVlAkhMxVmF2R)
|
||||
|
||||
- 🤖 **Task-focused agents** for planning, implementation, review, and testing
|
||||
- 📱 **Telegram integration** for idle session notifications
|
||||
- 🛡️ **Security-first** approach with configurable permissions
|
||||
- 📚 **Comprehensive documentation** and examples
|
||||
## Why Use This?
|
||||
|
||||
- ✅ **Plan-first workflow** - Agents propose plans before implementing
|
||||
- ✅ **Incremental execution** - Step-by-step implementation with validation
|
||||
- ✅ **Quality built-in** - Automatic testing, type checking, and code review
|
||||
- ✅ **Your patterns** - Agents follow your coding standards from context files
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install OpenCode CLI
|
||||
Follow the [official OpenCode documentation](https://opencode.ai/docs) to install the CLI.
|
||||
### Step 1: Install OpenCode CLI
|
||||
```bash
|
||||
# Follow official guide
|
||||
https://opencode.ai/docs
|
||||
```
|
||||
|
||||
### 2. Setup Telegram Notifications (Optional)
|
||||
Get notified when your OpenCode sessions become idle:
|
||||
### Step 2: Install Agents & Commands
|
||||
```bash
|
||||
# Clone this repository
|
||||
git clone https://github.com/darrenhinde/opencode-agents.git
|
||||
cd opencode-agents
|
||||
|
||||
# Install to OpenCode directory (global)
|
||||
mkdir -p ~/.opencode
|
||||
cp -r .opencode/agent ~/.opencode/
|
||||
cp -r .opencode/command ~/.opencode/
|
||||
cp -r .opencode/context ~/.opencode/
|
||||
```
|
||||
|
||||
### Step 3: Start Building
|
||||
```bash
|
||||
# Start the main development agent (recommended for new users)
|
||||
opencode --agent codebase-agent
|
||||
|
||||
# Tell it what to build
|
||||
> "Create a React todo list with TypeScript"
|
||||
```
|
||||
|
||||
**What happens next:**
|
||||
1. Agent proposes an implementation plan
|
||||
2. Asks for your approval
|
||||
3. Implements step-by-step with validation
|
||||
4. Delegates to @task-manager for complex features
|
||||
5. Uses @tester and @reviewer for quality assurance
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
User Request
|
||||
↓
|
||||
codebase-agent (main coordinator)
|
||||
↓
|
||||
├─→ @task-manager (breaks down complex features)
|
||||
├─→ @tester (writes and runs tests)
|
||||
├─→ @reviewer (security and code review)
|
||||
├─→ @documentation (generates docs)
|
||||
└─→ @build-agent (type checking and validation)
|
||||
```
|
||||
|
||||
**The workflow:**
|
||||
1. **You describe** what you want to build
|
||||
2. **Agent plans** the implementation steps
|
||||
3. **You approve** the plan
|
||||
4. **Agent implements** incrementally with validation
|
||||
5. **Quality checks** run automatically (tests, types, linting)
|
||||
6. **Subagents handle** specialized tasks (testing, review, docs)
|
||||
|
||||
**Context-aware:** Agents automatically load patterns from `.opencode/context/` to follow your coding standards.
|
||||
|
||||
---
|
||||
|
||||
## What's Included
|
||||
|
||||
### 🤖 Main Agents
|
||||
- **codebase-agent** - Your main development partner (recommended for most tasks)
|
||||
- **task-manager** - Breaks complex features into manageable subtasks
|
||||
- **workflow-orchestrator** - Routes requests to appropriate workflows
|
||||
- **image-specialist** - Generates images with Gemini AI
|
||||
|
||||
### 🔧 Specialized Subagents (Auto-delegated)
|
||||
- **reviewer** - Code review and security analysis
|
||||
- **tester** - Test creation and validation
|
||||
- **coder-agent** - Quick implementation tasks
|
||||
- **documentation** - Documentation generation
|
||||
- **build-agent** - Build and type checking
|
||||
- **codebase-pattern-analyst** - Pattern discovery
|
||||
|
||||
### ⚡ Commands
|
||||
- **/commit** - Smart git commits with conventional format
|
||||
- **/optimize** - Code optimization
|
||||
- **/test** - Testing workflows
|
||||
- **/clean** - Cleanup operations
|
||||
- **/context** - Context management
|
||||
- **/prompt-enchancer** - Improve your prompts
|
||||
- **/worktrees** - Git worktree management
|
||||
|
||||
### 📚 Context Files
|
||||
- `core/essential-patterns.md` - Core coding patterns
|
||||
- `project/project-context.md` - Your project-specific patterns
|
||||
|
||||
---
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Build a Feature
|
||||
```bash
|
||||
opencode --agent codebase-agent
|
||||
> "Create a user authentication system with email/password"
|
||||
|
||||
# Agent will:
|
||||
# 1. Propose implementation plan
|
||||
# 2. Wait for your approval
|
||||
# 3. Delegate to @task-manager (creates tasks/subtasks/user-auth/)
|
||||
# 4. Implement step-by-step
|
||||
# 5. Use @tester for tests
|
||||
# 6. Use @reviewer for security review
|
||||
```
|
||||
|
||||
### Make a Commit
|
||||
```bash
|
||||
# Make your changes
|
||||
git add .
|
||||
|
||||
# Use the commit command
|
||||
/commit
|
||||
|
||||
# Auto-generates: ✨ feat: add user authentication system
|
||||
```
|
||||
|
||||
### Add Your Patterns
|
||||
```bash
|
||||
# Edit your project context
|
||||
nano ~/.opencode/context/project/project-context.md
|
||||
|
||||
# Add your patterns:
|
||||
# **API Endpoint Pattern:**
|
||||
# ```typescript
|
||||
# export async function POST(request: Request) {
|
||||
# // Your standard pattern
|
||||
# }
|
||||
# ```
|
||||
|
||||
# Agents will automatically use these patterns!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Optional Add-ons
|
||||
|
||||
### 📱 Telegram Notifications
|
||||
Get notified when OpenCode sessions go idle.
|
||||
|
||||
```bash
|
||||
# Copy the example environment file
|
||||
# Copy plugin directory
|
||||
cp -r .opencode/plugin ~/.opencode/
|
||||
|
||||
# Install dependencies
|
||||
cd ~/.opencode/plugin
|
||||
npm install
|
||||
|
||||
# Configure
|
||||
cd ~/opencode-agents
|
||||
cp env.example .env
|
||||
|
||||
# Edit .env with your Telegram bot credentials
|
||||
# Get bot token from @BotFather on Telegram
|
||||
# Get chat ID by messaging your bot and checking the API
|
||||
# Edit .env with TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID
|
||||
```
|
||||
|
||||
### 3. Start Using Agents
|
||||
```bash
|
||||
# Start a planning session
|
||||
opencode --agent plan-project
|
||||
|
||||
# Run a specific task
|
||||
opencode run --agent mastra "Implement database schema"
|
||||
```
|
||||
|
||||
## Agents
|
||||
|
||||
See [`.opencode/AGENT-SYSTEM-BLUEPRINT.md`](.opencode/AGENT-SYSTEM-BLUEPRINT.md) for detailed information about available agents:
|
||||
|
||||
- **plan-project**: Roadmaps, milestones, ADRs, risk register
|
||||
- **plan-analyse**: Repo survey, external research, dependency mapping
|
||||
- **mastra**: Implementation for ingestion, embeddings, LanceDB, retrieval
|
||||
- **review**: Code review with targeted feedback
|
||||
- **documentation**: Documentation updates and examples
|
||||
- **write-test**: Unit/integration tests and mocks
|
||||
|
||||
## Plugins
|
||||
|
||||
### Telegram Bot (Simple)
|
||||
Single-file Telegram bot that sends notifications when OpenCode sessions become idle.
|
||||
|
||||
**Features:**
|
||||
- 🕐 Configurable idle timeout (default: 5 minutes)
|
||||
- 📱 Real-time notifications via Telegram
|
||||
- 🔄 Session resume tracking
|
||||
- 🛡️ Automatic .env file loading
|
||||
- 📦 Single file, no dependencies
|
||||
|
||||
**Quick Start:**
|
||||
```bash
|
||||
# Run the bot
|
||||
node .opencode/plugin/telegram-bot.js
|
||||
|
||||
# Run example usage
|
||||
node .opencode/plugin/example-usage.js
|
||||
```
|
||||
**Get credentials:** Message @BotFather on Telegram → `/newbot` → Save token
|
||||
|
||||
See [`.opencode/plugin/README.md`](.opencode/plugin/README.md) for detailed documentation.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
Copy `env.example` to `.env` and configure your Telegram bot:
|
||||
### 🎨 Gemini AI Image Tools
|
||||
Generate and edit images using Gemini AI.
|
||||
|
||||
```bash
|
||||
# Copy example file
|
||||
# Copy tool directory
|
||||
cp -r .opencode/tool ~/.opencode/
|
||||
|
||||
# Install dependencies
|
||||
cd ~/.opencode/tool
|
||||
npm install
|
||||
|
||||
# Configure
|
||||
cd ~/opencode-agents
|
||||
cp env.example .env
|
||||
|
||||
# Edit .env with your credentials
|
||||
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
||||
TELEGRAM_CHAT_ID=your_chat_id_here
|
||||
TELEGRAM_ENABLED=true
|
||||
# Edit .env with GEMINI_API_KEY
|
||||
```
|
||||
## Safety & Security
|
||||
|
||||
- **Approval-first workflow**: Each agent proposes a plan before execution
|
||||
- **Configurable permissions**: Granular control over what agents can do
|
||||
- **Input sanitization**: Protection against XSS and injection attacks
|
||||
- **Secure credential management**: Environment variables for sensitive data
|
||||
**Get API key:** https://makersuite.google.com/app/apikey
|
||||
|
||||
A video on how this works:
|
||||
[](https://youtu.be/EOIzFMdmox8?si=4ZSsVlAkhMxVmF2R)
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
**Q: What's the main way to use this?**
|
||||
A: Use `opencode --agent codebase-agent` for development. It coordinates everything else.
|
||||
|
||||
**Q: Do I need to install plugins/tools?**
|
||||
A: No, they're optional. Only install if you want Telegram notifications or Gemini AI features.
|
||||
|
||||
**Q: Where should I install - globally or per-project?**
|
||||
A: Global (`~/.opencode/`) works for most. Project-specific (`.opencode/`) if you need different configs per project.
|
||||
|
||||
**Q: How do I add my own coding patterns?**
|
||||
A: Edit `~/.opencode/context/project/project-context.md` - agents automatically load this file.
|
||||
|
||||
**Q: What's the AGENT-SYSTEM-BLUEPRINT.md for?**
|
||||
A: It's a teaching document explaining architecture patterns and how to extend the system.
|
||||
|
||||
**Q: Can I use just one command or agent?**
|
||||
A: Yes! Cherry-pick individual files with curl:
|
||||
```bash
|
||||
curl -o ~/.opencode/agent/codebase-agent.md \
|
||||
https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/.opencode/agent/codebase-agent.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced
|
||||
|
||||
### Understanding the System
|
||||
Read [AGENT-SYSTEM-BLUEPRINT.md](.opencode/AGENT-SYSTEM-BLUEPRINT.md) to learn:
|
||||
- How context loading works (the `@` symbol)
|
||||
- Agent architecture patterns
|
||||
- How to create custom agents and commands
|
||||
- How to extend the system for your needs
|
||||
|
||||
### Safety & Security
|
||||
- **Approval-first workflow** - Agents propose plans before execution
|
||||
- **Configurable permissions** - Granular control over agent capabilities
|
||||
- **Secure credentials** - Environment variables for sensitive data
|
||||
- **Input sanitization** - Protection against injection attacks
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
.opencode/
|
||||
├── agent/ # AI agents
|
||||
│ ├── codebase-agent.md
|
||||
│ ├── task-manager.md
|
||||
│ └── subagents/ # Specialized helpers
|
||||
├── command/ # Slash commands
|
||||
│ ├── commit.md
|
||||
│ └── optimize.md
|
||||
├── context/ # Coding patterns
|
||||
│ ├── core/ # Essential patterns
|
||||
│ └── project/ # Your patterns
|
||||
├── plugin/ # Optional: Telegram
|
||||
└── tool/ # Optional: Gemini AI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -100,6 +265,21 @@ A video on how this works:
|
|||
3. Update documentation for any changes
|
||||
4. Ensure security best practices are followed
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License.
|
||||
|
||||
---
|
||||
|
||||
## Recommended for New Users
|
||||
|
||||
**Start with `codebase-agent`** - it's your main development partner that handles planning, implementation, and quality assurance. It automatically delegates to specialized subagents when needed, so you don't have to manage multiple agents yourself.
|
||||
|
||||
```bash
|
||||
opencode --agent codebase-agent
|
||||
> "Your development task here"
|
||||
```
|
||||
|
||||
The agent will guide you through the entire development workflow with a plan-first, approval-based approach.
|
||||
|
|
|
|||
Loading…
Reference in a new issue