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,5 +1,4 @@
 ---
-
 description: "Type check and build validation agent"
 mode: subagent
 temperature: 0.1

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)
+# Start the universal agent (recommended for new users)
-opencode --agent codebase-agent
+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
+1. OpenAgent analyzes your request (question or task)
-2. Asks for your approval
+2. For tasks: proposes a plan and asks for approval
-3. Implements step-by-step with validation
+3. Executes step-by-step with validation
-4. Delegates to @task-manager for complex features
+4. Delegates to specialists (@task-manager, @tester, @reviewer) when needed
-5. Uses @tester and @reviewer for quality assurance
+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:
+# OpenAgent will:
-# 1. Propose implementation plan
+# 1. Analyze the request (complex task)
-# 2. Wait for your approval
+# 2. Propose implementation plan
-# 3. Delegate to @task-manager (creates tasks/subtasks/user-auth/)
+# 3. Wait for your approval
-# 4. Implement step-by-step
+# 4. Delegate to @task-manager (creates task breakdown)
-# 5. Use @tester for tests
+# 5. Coordinate implementation step-by-step
-# 6. Use @reviewer for security review
+# 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
+opencode --agent openagent
-> "Your development task here"
+> "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

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)

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
+3. **Use `@task-manager`** when features get complex (openagent delegates automatically)
-4. **Let subagents** handle specialized work (@tester, @reviewer)
+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`)

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

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

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

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