📝 docs: improve documentation for new users with video, TL;DR, and clearer guidance

.opencode/AGENT-SYSTEM-BLUEPRINT.md

@@ -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._

README.md

@@ -2,96 +2,261 @@
 
 A set of OpenCode configurations, prompts, agents, and plugins for enhanced development workflows.
 
-## Features
+[![Watch Demo](https://img.youtube.com/vi/EOIzFMdmox8/maxresdefault.jpg)](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
+```
+
+### Step 2: Install Agents & Commands
+```bash
+# Clone this repository
+git clone https://github.com/darrenhinde/opencode-agents.git
+cd opencode-agents
 
-### 2. Setup Telegram Notifications (Optional)
-Get notified when your OpenCode sessions become idle:
+# 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
-# Copy the example environment file
-cp env.example .env
+# Start the main development agent (recommended for new users)
+opencode --agent codebase-agent
 
-# 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
+# Tell it what to build
+> "Create a React todo list with TypeScript"
 ```
 
-### 3. Start Using Agents
+**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
-# Start a planning session
-opencode --agent plan-project
+opencode --agent codebase-agent
+> "Create a user authentication system with email/password"
 
-# Run a specific task
-opencode run --agent mastra "Implement database schema"
+# 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
 ```
 
-## Agents
+### Make a Commit
+```bash
+# Make your changes
+git add .
+
+# Use the commit command
+/commit
 
-See [`.opencode/AGENT-SYSTEM-BLUEPRINT.md`](.opencode/AGENT-SYSTEM-BLUEPRINT.md) for detailed information about available agents:
+# Auto-generates: ✨ feat: add user authentication system
+```
 
-- **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
+### 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!
+```
 
-## Plugins
+---
 
-### Telegram Bot (Simple)
-Single-file Telegram bot that sends notifications when OpenCode sessions become idle.
+## Optional Add-ons
 
-**Features:**
-- 🕐 Configurable idle timeout (default: 5 minutes)
-- 📱 Real-time notifications via Telegram
-- 🔄 Session resume tracking
-- 🛡️ Automatic .env file loading
-- 📦 Single file, no dependencies
+### 📱 Telegram Notifications
+Get notified when OpenCode sessions go idle.
 
-**Quick Start:**
 ```bash
-# Run the bot
-node .opencode/plugin/telegram-bot.js
+# Copy plugin directory
+cp -r .opencode/plugin ~/.opencode/
 
-# Run example usage
-node .opencode/plugin/example-usage.js
+# Install dependencies
+cd ~/.opencode/plugin
+npm install
+
+# Configure
+cd ~/opencode-agents
+cp env.example .env
+# Edit .env with TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID
 ```
 
-See [`.opencode/plugin/README.md`](.opencode/plugin/README.md) for detailed documentation.
+**Get credentials:** Message @BotFather on Telegram → `/newbot` → Save token
 
-## Configuration
+See [`.opencode/plugin/README.md`](.opencode/plugin/README.md) for detailed documentation.
 
-### 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 GEMINI_API_KEY
+```
+
+**Get API key:** https://makersuite.google.com/app/apikey
+
+---
+
+## 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.
 
-# Edit .env with your credentials
-TELEGRAM_BOT_TOKEN=your_bot_token_here
-TELEGRAM_CHAT_ID=your_chat_id_here
-TELEGRAM_ENABLED=true
+**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
 ```
-## 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
+---
+
+## 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
 
-A video on how this works:
-[![Video Title](https://img.youtube.com/vi/EOIzFMdmox8/maxresdefault.jpg)](https://youtu.be/EOIzFMdmox8?si=4ZSsVlAkhMxVmF2R)
+### 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.