From 8b75f128d33205374b9de425360b28176688c309 Mon Sep 17 00:00:00 2001 From: darrenhinde <107584450+darrenhinde@users.noreply.github.com> Date: Tue, 18 Nov 2025 23:15:44 +0000 Subject: [PATCH] docs: update to recommend OpenAgent as default with enhanced workflow diagrams - Position OpenAgent as recommended default for new users - Add detailed stage diagrams for all 6 workflow stages - Replace bright purple colors with softer slate blue for better accessibility - Update all documentation to show OpenAgent as universal coordinator - Keep codebase-agent as specialized development alternative --- .opencode/agent/subagents/code/build-agent.md | 1 - README.md | 52 +++++++++++-------- docs/README.md | 3 +- docs/features/agent-system-blueprint.md | 20 +++---- docs/features/system-builder/README.md | 7 +-- docs/features/system-builder/quick-start.md | 2 +- .../QUICK_START_SYSTEM_BUILDER.md | 2 +- docs/getting-started/installation.md | 2 +- 8 files changed, 49 insertions(+), 40 deletions(-) diff --git a/.opencode/agent/subagents/code/build-agent.md b/.opencode/agent/subagents/code/build-agent.md index 9bd4a50..4e1833d 100644 --- a/.opencode/agent/subagents/code/build-agent.md +++ b/.opencode/agent/subagents/code/build-agent.md @@ -1,5 +1,4 @@ --- - description: "Type check and build validation agent" mode: subagent temperature: 0.1 diff --git a/README.md b/README.md index 57e1ec2..239825b 100644 --- a/README.md +++ b/README.md @@ -163,19 +163,19 @@ cp -r .opencode/context ~/.opencode/ ### Step 3: Start Building ```bash -# Start the main development agent (recommended for new users) -opencode --agent codebase-agent +# Start the universal agent (recommended for new users) +opencode --agent openagent -# Tell it what to build +# Ask questions or request tasks > "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 +1. OpenAgent analyzes your request (question or task) +2. For tasks: proposes a plan and asks for approval +3. Executes step-by-step with validation +4. Delegates to specialists (@task-manager, @tester, @reviewer) when needed +5. Confirms completion and offers cleanup --- @@ -184,12 +184,13 @@ opencode --agent codebase-agent ``` User Request ↓ -codebase-agent (main coordinator) +openagent (universal coordinator) ↓ ├─→ @task-manager (breaks down complex features) ├─→ @tester (writes and runs tests) ├─→ @reviewer (security and code review) ├─→ @documentation (generates docs) + ├─→ @coder-agent (implementation tasks) └─→ @build-agent (type checking and validation) ``` @@ -208,7 +209,8 @@ codebase-agent (main coordinator) ## What's Included ### 🤖 Main Agents -- **codebase-agent** - Your main development partner (recommended for most tasks) +- **openagent** - Universal agent for questions and tasks (recommended default) +- **codebase-agent** - Specialized development agent for code-focused workflows - **task-manager** - Breaks complex features into manageable subtasks - **workflow-orchestrator** - Routes requests to appropriate workflows - **image-specialist** - Generates images with Gemini AI @@ -240,16 +242,17 @@ codebase-agent (main coordinator) ### Build a Feature ```bash -opencode --agent codebase-agent +opencode --agent openagent > "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 +# OpenAgent will: +# 1. Analyze the request (complex task) +# 2. Propose implementation plan +# 3. Wait for your approval +# 4. Delegate to @task-manager (creates task breakdown) +# 5. Coordinate implementation step-by-step +# 6. Use @tester for tests and @reviewer for security +# 7. Validate, summarize, and confirm completion ``` ### Make a Commit @@ -370,7 +373,7 @@ cp env.example .env ## Common Questions **Q: What's the main way to use this?** -A: Use `opencode --agent codebase-agent` for development. It coordinates everything else. +A: Use `opencode --agent openagent` as your default. It handles both questions and tasks, coordinating with specialists as needed. **Q: Does this work on Windows?** A: Yes! Use Git Bash (recommended) or WSL. See [Platform Compatibility Guide](docs/getting-started/platform-compatibility.md) for details. @@ -524,14 +527,17 @@ 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. +**Start with `openagent`** - it's your universal assistant that handles everything from simple questions to complex multi-step workflows. It follows a systematic 6-stage workflow (Analyze → Approve → Execute → Validate → Summarize → Confirm) and automatically delegates to specialized subagents when needed. ```bash -opencode --agent codebase-agent -> "Your development task here" +opencode --agent openagent +> "How do I implement authentication in Next.js?" # Questions +> "Create a user authentication system" # Tasks ``` -The agent will guide you through the entire development workflow with a plan-first, approval-based approach. +OpenAgent will guide you through with a plan-first, approval-based approach. For questions, you get direct answers. For tasks, you see the plan before execution. + +**Learn more:** See the [OpenAgent Guide](docs/agents/openagent.md) for detailed workflow diagrams and tips. --- ## Support This Work diff --git a/docs/README.md b/docs/README.md index 0d75a70..47809fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,7 +30,8 @@ Welcome to the OpenAgents documentation! This directory contains all documentati ### For New Users - Start with the main [README](../README.md) in the repository root - Follow the [Installation Guide](getting-started/installation.md) -- Use `opencode --agent codebase-agent` to start building +- Use `opencode --agent openagent` to start building +- Read the [OpenAgent Guide](agents/openagent.md) to understand the workflow ### For Contributors - Read the [Contributing Guide](contributing/CONTRIBUTING.md) diff --git a/docs/features/agent-system-blueprint.md b/docs/features/agent-system-blueprint.md index 16fdc98..4e773aa 100644 --- a/docs/features/agent-system-blueprint.md +++ b/docs/features/agent-system-blueprint.md @@ -14,14 +14,14 @@ _Build Intelligent Workflow Systems with Context-Aware AI_ - Extend the system with domain-specific patterns - Learn how context loading and agent coordination works -**If you just want to start building**, skip this document and use `codebase-agent` instead. See the [README.md](../../README.md) for quick start instructions. +**If you just want to start building**, skip this document and use `openagent` instead. See the [README.md](../../README.md) for quick start instructions. --- ## ⚡ TL;DR - Quick Reference **For New Users:** -- Start with `opencode --agent codebase-agent` for all development work +- Start with `opencode --agent openagent` for all questions and tasks - 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 @@ -41,7 +41,7 @@ Commands load context → Agents execute with that context → Subagents handle - ✅ 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) +- ❌ You just want to start building (use `openagent` instead) --- @@ -63,7 +63,7 @@ This blueprint explains the architecture patterns behind the OpenCode agent syst **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 +- The existing `openagent` and `codebase-agent` already handle these workflows - Create them only if you have specific repeated patterns **When you see extensive context hierarchies:** @@ -73,6 +73,7 @@ This blueprint explains the architecture patterns behind the OpenCode agent syst **When you see task management structures:** - The `task-manager` agent creates `tasks/` directories automatically +- `openagent` creates session files in `.tmp/sessions/` for context preservation - No need to pre-create structures --- @@ -175,7 +176,8 @@ OpenCode processes `@` references only in command templates, NOT recursively in **What they do:** AI workers with specific capabilities and predictable behavior **Main agents in this repo:** -- `codebase-agent` - Main development partner +- `openagent` - Universal agent for questions and tasks (recommended default) +- `codebase-agent` - Specialized development partner - `task-manager` - Breaks down complex features - `workflow-orchestrator` - Routes requests - `image-specialist` - Image generation @@ -417,16 +419,16 @@ Don't create custom agents when: **Don't create specialized commands/agents right away. Instead:** -1. **Start with `codebase-agent`** for everything +1. **Start with `openagent`** for everything (questions and tasks) 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) +3. **Use `@task-manager`** when features get complex (openagent delegates automatically) +4. **Let subagents** handle specialized work (@tester, @reviewer, @coder-agent) 5. **Create specialized commands** only when you have repeated workflows 6. **Use `/prompt-enchancer`** when building custom agents ### Example Progression -**Week 1:** Use `codebase-agent` for everything +**Week 1:** Use `openagent` for everything (questions and tasks) **Week 2:** Add project-specific context to `project/project-context.md` **Week 3:** Agent automatically picks up your patterns **Week 4:** Create a command if you have repeated workflows (use `/prompt-enchancer`) diff --git a/docs/features/system-builder/README.md b/docs/features/system-builder/README.md index 0fbd18e..86e4735 100644 --- a/docs/features/system-builder/README.md +++ b/docs/features/system-builder/README.md @@ -150,7 +150,7 @@ Integrates with existing agents - test-validator (subagent) - Commands: /review-code, /scan-security -**Integration**: Leverages existing codebase-agent, reviewer, tester +**Integration**: Leverages existing openagent, codebase-agent, reviewer, tester --- @@ -178,7 +178,7 @@ Integrates with existing agents ### Example 3: Extend Existing Project -**Existing**: Dev tools (codebase-agent, build-agent, tester) +**Existing**: Dev tools (openagent, codebase-agent, build-agent, tester) **Command**: `/build-context-system "Add documentation generation"` @@ -186,7 +186,7 @@ Integrates with existing agents 1. Detects existing project 2. User chooses: "Extend existing" 3. Domain type: Hybrid (dev + content) -4. Reuses: codebase-agent, documentation +4. Reuses: openagent, codebase-agent, documentation 5. Adds: doc-orchestrator, api-doc-generator 6. Result: Unified system with dev + docs @@ -237,6 +237,7 @@ All generated systems implement proven patterns: The system detects and integrates with existing agents: **Development Agents**: +- `openagent` - Universal agent for questions and tasks - `codebase-agent` - Code analysis, file operations - `build-agent` - Build validation, type checking - `tester` - Test authoring, TDD diff --git a/docs/features/system-builder/quick-start.md b/docs/features/system-builder/quick-start.md index b69c216..f128040 100644 --- a/docs/features/system-builder/quick-start.md +++ b/docs/features/system-builder/quick-start.md @@ -158,7 +158,7 @@ When you install **advanced** profile, you get: 7. `build-context-system` (command) - Interactive interface **Plus all development tools:** -- task-manager, codebase-agent +- openagent, task-manager, codebase-agent - All core subagents (reviewer, tester, etc.) - All development commands - Tools and plugins diff --git a/docs/getting-started/context-aware-system/QUICK_START_SYSTEM_BUILDER.md b/docs/getting-started/context-aware-system/QUICK_START_SYSTEM_BUILDER.md index c0194b8..852c358 100644 --- a/docs/getting-started/context-aware-system/QUICK_START_SYSTEM_BUILDER.md +++ b/docs/getting-started/context-aware-system/QUICK_START_SYSTEM_BUILDER.md @@ -341,7 +341,7 @@ When you install **advanced** profile, you get: 7. `build-context-system` (command) - Interactive interface **Plus all development tools:** -- task-manager, codebase-agent +- openagent, task-manager, codebase-agent - All core subagents (reviewer, tester, etc.) - All development commands - Tools and plugins diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index f51f101..3ee7b8d 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -304,7 +304,7 @@ Components: **Code-focused development tools** Components: -- Development agents: codebase-agent, task-manager +- Development agents: openagent, codebase-agent, task-manager - Code subagents: reviewer, tester, coder-agent, build-agent - Development commands: test, commit, context - Development tools and contexts