📝 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_
|
_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
|
## The Golden Rule
|
||||||
|
|
||||||
**Context flows in one direction: Commands load context immediately, Agents can look up additional context deterministically.**
|
**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._
|
_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.
|
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
|
## Why Use This?
|
||||||
- 📱 **Telegram integration** for idle session notifications
|
|
||||||
- 🛡️ **Security-first** approach with configurable permissions
|
- ✅ **Plan-first workflow** - Agents propose plans before implementing
|
||||||
- 📚 **Comprehensive documentation** and examples
|
- ✅ **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
|
## Quick Start
|
||||||
|
|
||||||
### 1. Install OpenCode CLI
|
### Step 1: Install OpenCode CLI
|
||||||
Follow the [official OpenCode documentation](https://opencode.ai/docs) to install the CLI.
|
```bash
|
||||||
|
# Follow official guide
|
||||||
|
https://opencode.ai/docs
|
||||||
|
```
|
||||||
|
|
||||||
### 2. Setup Telegram Notifications (Optional)
|
### Step 2: Install Agents & Commands
|
||||||
Get notified when your OpenCode sessions become idle:
|
```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
|
```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
|
cp env.example .env
|
||||||
|
# Edit .env with TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Start Using Agents
|
**Get credentials:** Message @BotFather on Telegram → `/newbot` → Save token
|
||||||
```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
|
|
||||||
```
|
|
||||||
|
|
||||||
See [`.opencode/plugin/README.md`](.opencode/plugin/README.md) for detailed documentation.
|
See [`.opencode/plugin/README.md`](.opencode/plugin/README.md) for detailed documentation.
|
||||||
|
|
||||||
## Configuration
|
### 🎨 Gemini AI Image Tools
|
||||||
|
Generate and edit images using Gemini AI.
|
||||||
### Environment Variables
|
|
||||||
Copy `env.example` to `.env` and configure your Telegram bot:
|
|
||||||
|
|
||||||
```bash
|
```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
|
cp env.example .env
|
||||||
|
# Edit .env with GEMINI_API_KEY
|
||||||
# Edit .env with your credentials
|
|
||||||
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
|
||||||
TELEGRAM_CHAT_ID=your_chat_id_here
|
|
||||||
TELEGRAM_ENABLED=true
|
|
||||||
```
|
```
|
||||||
## Safety & Security
|
|
||||||
|
|
||||||
- **Approval-first workflow**: Each agent proposes a plan before execution
|
**Get API key:** https://makersuite.google.com/app/apikey
|
||||||
- **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
|
|
||||||
|
|
||||||
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
|
## Contributing
|
||||||
|
|
||||||
|
|
@ -100,6 +265,21 @@ A video on how this works:
|
||||||
3. Update documentation for any changes
|
3. Update documentation for any changes
|
||||||
4. Ensure security best practices are followed
|
4. Ensure security best practices are followed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
This project is licensed under the MIT 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