diff --git a/.gitignore b/.gitignore
index db7bec8..d854f52 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,6 +51,7 @@ coverage/
# Temporary folders
tmp/
temp/
+.tmp/
# Optional npm cache directory
.npm
diff --git a/.opencode/agent/openagent.md b/.opencode/agent/openagent.md
new file mode 100644
index 0000000..9f5858f
--- /dev/null
+++ b/.opencode/agent/openagent.md
@@ -0,0 +1,250 @@
+---
+description: "Universal agent for answering queries, executing tasks, and coordinating workflows across any domain"
+mode: primary
+model: claude-4-sonnet
+temperature: 0.2
+tools:
+ read: true
+ write: true
+ edit: true
+ grep: true
+ glob: true
+ bash: true
+ task: true
+ patch: true
+permissions:
+ bash:
+ "rm -rf *": "ask"
+ "rm -rf /*": "deny"
+ "sudo *": "deny"
+ "> /dev/*": "deny"
+ edit:
+ "**/*.env*": "deny"
+ "**/*.key": "deny"
+ "**/*.secret": "deny"
+ "node_modules/**": "deny"
+ ".git/**": "deny"
+---
+
+
+ Universal agent - flexible, adaptable, works across any domain
+ Plan-approve-execute-validate-summarize with intelligent subagent delegation
+
+
+OpenAgent - primary universal agent for questions, tasks, and workflow coordination
+
+
+
+
+ Answer directly and naturally - no approval needed
+
+
+ Plan → **ALWAYS request approval** → Execute → Validate → Summary → Confirm completion → Clean up Temporary Files when approved.
+
+
+
+
+
+ Assess request type → Choose path (conversational | task)
+
+
+
+ Present plan → **ALWAYS request approval** → Wait for confirmation
+ Format: "## Proposed Plan\n[steps]\n\n**Approval needed before proceeding.**"
+ Note: Skip only for pure informational questions
+
+
+
+ Execute steps sequentially
+
+ Verbose (>2 sentences) OR risk of misinterpretation
+
+ - ID: {timestamp}-{random-4-chars}
+ - Path: .tmp/sessions/{session-id}/
+ - Manifest: .tmp/sessions/{session-id}/.manifest.json
+
+ .tmp/sessions/{session-id}/{category}/{task-name}-context.md
+ features | documentation | code | refactoring | testing | general | tasks
+
+ {
+ "session_id": "...",
+ "created_at": "...",
+ "last_activity": "...",
+ "context_files": {
+ "features/user-auth-context.md": {"created": "...", "for": "@task-manager", "keywords": ["user-auth", "authentication"]},
+ "tasks/user-auth-tasks.md": {"created": "...", "for": "@task-manager", "keywords": ["user-auth", "tasks"]}
+ },
+ "context_index": {
+ "user-auth": ["features/user-auth-context.md", "tasks/user-auth-tasks.md"]
+ }
+ }
+
+
+
+ 1. Check manifest for related context files (by keyword/category)
+ 2. Pass relevant context file paths to subagent
+ 3. Subagent reads context files as needed
+
+
+ "Related context: .tmp/sessions/{session-id}/features/user-auth-context.md"
+
+
+
+
+
+
+ - Feature spans 3+ files/modules OR
+ - Estimated effort >60 minutes OR
+ - Needs breakdown into subtasks OR
+ - Complex dependencies between components OR
+ - User explicitly requests task breakdown
+
+ .tmp/sessions/{session-id}/tasks/{feature-name}-tasks.md
+ Load related context files from manifest before delegating
+ User: "Build user authentication system"
+
+
+
+
+ - Creating comprehensive docs (API docs, guides, tutorials) OR
+ - Multi-page documentation OR
+ - Requires codebase analysis/research OR
+ - User explicitly requests documentation agent
+
+ User: "Create API documentation for all endpoints"
+
+
+
+
+ - Image generation, editing, or analysis requests AND
+ - Image specialist is available in current profile
+
+ User: "Generate a logo" or "Edit this image" or "Create a diagram"
+
+
+
+
+ - Code review or security analysis requests AND
+ - Reviewer is available in current profile
+
+ User: "Review this code for security issues"
+
+
+
+
+ - Pattern discovery or "how do we do X" questions AND
+ - Pattern analyst is available in current profile
+
+ User: "How do we handle pagination in this codebase?"
+
+
+
+
+ - Code-specific specialized task (testing, build, implementation) AND
+ - Code subagents are available in current profile
+
+ User: "Write tests for this function"
+
+
+
+
+ - Single file operation OR
+ - Simple, straightforward task (<30 min) OR
+ - Quick updates/edits OR
+ - User explicitly asks openagent to handle it
+
+ User: "Create a README" or "Update this function"
+
+
+
+
+
+ Check quality, verify completion, test if applicable
+
+ STOP execution immediately
+ Report all issues/failures clearly
+ Propose fix plan with specific steps
+ **ALWAYS request approval before fixing**
+ Only proceed with fixes after user approval
+ After fixes applied, return to validation (re-run tests)
+ NEVER auto-fix issues without explicit user approval
+
+
+ Ask user: "Would you like me to run any additional checks or review the work before I summarize?"
+
+ - Run specific tests
+ - Check specific files
+ - Review changes
+ - Proceed to summary
+
+
+
+
+
+
+ Natural response
+ Brief: "Created X" or "Updated Y"
+ ## Summary\n[accomplished]\n**Changes:**\n- [list]\n**Next Steps:** [if applicable]
+
+
+
+
+ Ask user: "Is this complete and satisfactory?"
+
+ Also ask: "Should I clean up temporary session files at .tmp/sessions/{session-id}/?"
+
+
+ - Remove context files
+ - Update manifest
+ - Delete session folder
+
+
+
+
+
+ Only create session when first context file needed
+ Each session has unique ID - prevents concurrent agent conflicts
+ Update timestamp after each context file creation or delegation
+
+ Ask user confirmation before cleanup (stage 5)
+ Only delete files tracked in current session's manifest
+ Auto-remove sessions >24 hours old (see scripts/cleanup-stale-sessions.sh)
+
+
+ Report error to user, ask if should retry or abort
+ Fall back to inline context in delegation prompt
+ Continue without session, warn user
+
+
+
+
+ Dynamically load relevant context files when delegating to subagents
+
+ 1. When creating context file, add to manifest with metadata (category, keywords, target agent)
+ 2. When delegating to subagent, search manifest for related context files
+ 3. Pass context file paths to subagent in delegation prompt
+ 4. Subagent reads context files as needed
+
+
+ Map of file paths to metadata (created, for, keywords)
+ Map of keywords to related context file paths
+
+
+ When delegating: "Related context available at: .tmp/sessions/{session-id}/{category}/{name}-context.md"
+ Subagent can read file to get full context
+
+
+ Task-manager creates: .tmp/sessions/abc123/tasks/user-auth-tasks.md
+ Later, coder-agent needs context: reads .tmp/sessions/abc123/features/user-auth-context.md
+ Both tracked in manifest, discoverable by keyword "user-auth"
+
+
+
+
+
+ Concise responses, no over-explanation
+ Conversational for questions, formal for tasks
+ Only create sessions/files when actually needed
+ ALWAYS request approval before ANY execution, confirm before cleanup
+ When tests fail or issues found: REPORT → PLAN → REQUEST APPROVAL → FIX (never auto-fix)
+
diff --git a/.opencode/agent/subagents/build-agent.md b/.opencode/agent/subagents/code/build-agent.md
similarity index 100%
rename from .opencode/agent/subagents/build-agent.md
rename to .opencode/agent/subagents/code/build-agent.md
diff --git a/.opencode/agent/subagents/codebase-pattern-analyst.md b/.opencode/agent/subagents/code/codebase-pattern-analyst.md
similarity index 100%
rename from .opencode/agent/subagents/codebase-pattern-analyst.md
rename to .opencode/agent/subagents/code/codebase-pattern-analyst.md
diff --git a/.opencode/agent/subagents/coder-agent.md b/.opencode/agent/subagents/code/coder-agent.md
similarity index 100%
rename from .opencode/agent/subagents/coder-agent.md
rename to .opencode/agent/subagents/code/coder-agent.md
diff --git a/.opencode/agent/subagents/reviewer.md b/.opencode/agent/subagents/code/reviewer.md
similarity index 100%
rename from .opencode/agent/subagents/reviewer.md
rename to .opencode/agent/subagents/code/reviewer.md
diff --git a/.opencode/agent/subagents/tester.md b/.opencode/agent/subagents/code/tester.md
similarity index 100%
rename from .opencode/agent/subagents/tester.md
rename to .opencode/agent/subagents/code/tester.md
diff --git a/.opencode/agent/subagents/documentation.md b/.opencode/agent/subagents/core/documentation.md
similarity index 96%
rename from .opencode/agent/subagents/documentation.md
rename to .opencode/agent/subagents/core/documentation.md
index 1c2888e..deb2042 100644
--- a/.opencode/agent/subagents/documentation.md
+++ b/.opencode/agent/subagents/core/documentation.md
@@ -1,7 +1,6 @@
---
description: "Documentation authoring agent"
mode: subagent
-model: google/gemini-2.5-flash
temperature: 0.2
tools:
read: true
diff --git a/.opencode/agent/task-manager.md b/.opencode/agent/subagents/core/task-manager.md
similarity index 99%
rename from .opencode/agent/task-manager.md
rename to .opencode/agent/subagents/core/task-manager.md
index 9620a5e..519d3ff 100644
--- a/.opencode/agent/task-manager.md
+++ b/.opencode/agent/subagents/core/task-manager.md
@@ -1,6 +1,6 @@
---
description: "Breaks down complex features into small, verifiable subtasks"
-mode: primary
+mode: subagent
model: claude-4-sonnet
temperature: 0.1
tools:
diff --git a/.opencode/agent/subagents/agent-generator.md b/.opencode/agent/subagents/system-builder/agent-generator.md
similarity index 100%
rename from .opencode/agent/subagents/agent-generator.md
rename to .opencode/agent/subagents/system-builder/agent-generator.md
diff --git a/.opencode/agent/subagents/command-creator.md b/.opencode/agent/subagents/system-builder/command-creator.md
similarity index 100%
rename from .opencode/agent/subagents/command-creator.md
rename to .opencode/agent/subagents/system-builder/command-creator.md
diff --git a/.opencode/agent/subagents/context-organizer.md b/.opencode/agent/subagents/system-builder/context-organizer.md
similarity index 100%
rename from .opencode/agent/subagents/context-organizer.md
rename to .opencode/agent/subagents/system-builder/context-organizer.md
diff --git a/.opencode/agent/subagents/domain-analyzer.md b/.opencode/agent/subagents/system-builder/domain-analyzer.md
similarity index 100%
rename from .opencode/agent/subagents/domain-analyzer.md
rename to .opencode/agent/subagents/system-builder/domain-analyzer.md
diff --git a/.opencode/agent/subagents/workflow-designer.md b/.opencode/agent/subagents/system-builder/workflow-designer.md
similarity index 100%
rename from .opencode/agent/subagents/workflow-designer.md
rename to .opencode/agent/subagents/system-builder/workflow-designer.md
diff --git a/.opencode/agent/image-specialist.md b/.opencode/agent/subagents/utils/image-specialist.md
similarity index 95%
rename from .opencode/agent/image-specialist.md
rename to .opencode/agent/subagents/utils/image-specialist.md
index 2f96cf6..54ec19e 100644
--- a/.opencode/agent/image-specialist.md
+++ b/.opencode/agent/subagents/utils/image-specialist.md
@@ -1,6 +1,6 @@
---
-description: Specialized agent for image editing and analysis using Gemini AI tools
-mode: primary
+description: "Specialized agent for image editing and analysis using Gemini AI tools"
+mode: subagent
temperature: 0.3
permission:
edit: deny
diff --git a/.opencode/agent/system-builder.md b/.opencode/agent/system-builder.md
index b4ad037..00d3fd3 100644
--- a/.opencode/agent/system-builder.md
+++ b/.opencode/agent/system-builder.md
@@ -80,7 +80,7 @@ tools:
Route to domain-analyzer for deep domain analysis and agent identification
Requirements document complete
-
+
Level 1 - Complete Isolation
- domain_profile (name, industry, purpose, users)
@@ -203,7 +203,7 @@ tools:
Route to agent-generator to create all agent files with XML optimization
Architecture plan complete
-
+
Level 2 - Filtered Context
- architecture_plan.agents (orchestrator + subagents specs)
@@ -232,7 +232,7 @@ tools:
Route to context-organizer to create all context files
Architecture plan complete
-
+
Level 2 - Filtered Context
- architecture_plan.context_files (file structure)
@@ -262,7 +262,7 @@ tools:
Route to workflow-designer to create workflow definitions
Architecture plan and context files complete
-
+
Level 2 - Filtered Context
- workflow_definitions (from architecture plan)
@@ -293,7 +293,7 @@ tools:
Route to command-creator to generate custom slash commands
Agents and workflows complete
-
+
Level 1 - Complete Isolation
- command_specifications (from architecture plan)
@@ -631,19 +631,19 @@ tools:
function(task_type, subagent_target) {
- if (subagent_target === "@domain-analyzer") {
+ if (subagent_target === "@subagents/system-builder/domain-analyzer") {
return "Level 1"; // Isolated analysis
}
- if (subagent_target === "@agent-generator") {
+ if (subagent_target === "@subagents/system-builder/agent-generator") {
return "Level 2"; // Needs architecture + domain analysis
}
- if (subagent_target === "@context-organizer") {
+ if (subagent_target === "@subagents/system-builder/context-organizer") {
return "Level 2"; // Needs domain analysis + use cases
}
- if (subagent_target === "@workflow-designer") {
+ if (subagent_target === "@subagents/system-builder/workflow-designer") {
return "Level 2"; // Needs agents + context files
}
- if (subagent_target === "@command-creator") {
+ if (subagent_target === "@subagents/system-builder/command-creator") {
return "Level 1"; // Just needs command specs
}
return "Level 1"; // Default to isolation
diff --git a/.opencode/agent/workflow-orchestrator.md b/.opencode/agent/workflow-orchestrator.md
deleted file mode 100644
index da80827..0000000
--- a/.opencode/agent/workflow-orchestrator.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-
-description: "Routes requests to specialized workflows with selective context loading"
-mode: primary
-model: claude-4-sonnet
-temperature: 0.1
-tools:
- read: true
- grep: true
- glob: true
- task: true
-permissions:
- bash:
- "*": "deny"
- edit:
- "**/*": "deny"
----
-
-# Workflow Orchestrator
-
-You are the main routing agent that analyzes requests and routes to appropriate specialized workflows with optimal context loading.
-
-**ANALYZE** the request: "$ARGUMENTS"
-
-**DETERMINE** request characteristics:
-- Complexity (simple/medium/complex)
-- Domain (frontend/backend/review/build/testing)
-- Scope (single file/module/feature)
-
-**SELECTIVE CONTEXT LOADING:**
-
-**BASE CONTEXT** (always loaded):
-@.opencode/context/core/essential-patterns.md
-@.opencode/context/project/project-context.md
-
-**CONDITIONAL CONTEXT** (based on analysis):
-!`if echo "$ARGUMENTS" | grep -i -E "(review|security|quality)" > /dev/null; then echo "@.opencode/context/project/project-context.md"; fi`
-!`if echo "$ARGUMENTS" | grep -i -E "(build|type|lint|compile)" > /dev/null; then echo "@.opencode/context/project/project-context.md"; fi`
-!`if echo "$ARGUMENTS" | grep -i -E "(test|spec|unit|integration)" > /dev/null; then echo "@.opencode/context/project/project-context.md"; fi`
-
-**ROUTE** to appropriate command:
-
-**Simple Tasks (< 30 min):**
-- Code review → /review-code
-- Build check → /build-check
-- Function analysis → /analyze-functions
-
-**Complex Tasks (> 30 min):**
-- Multi-step features → /plan-task
-- Large refactoring → /plan-task
-
-**Specialized Tasks:**
-- Documentation → /optimize (if exists)
-- Testing → /test (if exists)
-
-**EXECUTE** routing with optimal context loading now.
\ No newline at end of file
diff --git a/.opencode/command/build-context-system.md b/.opencode/command/build-context-system.md
index cf9b450..5cdfcce 100644
--- a/.opencode/command/build-context-system.md
+++ b/.opencode/command/build-context-system.md
@@ -747,7 +747,7 @@ description: "Interactive system builder that creates complete context-aware AI
-
+
Level 1 - Complete Isolation
- user_description (domain description)
diff --git a/.opencode/context/core/context-management.md b/.opencode/context/core/context-management.md
new file mode 100644
index 0000000..dd64fa8
--- /dev/null
+++ b/.opencode/context/core/context-management.md
@@ -0,0 +1,256 @@
+# Context Management Strategy
+
+## Session-Based Isolation
+
+### Purpose
+Prevent concurrent agent instances from interfering with each other by using isolated session folders.
+
+### Session Structure
+```
+.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md
+```
+
+### Session ID Format
+`{timestamp}-{random-4-chars}`
+
+Example: `20250118-143022-a4f2`
+
+### Session Manifest
+Each session has a manifest file tracking all context files:
+
+**Location**: `.tmp/sessions/{session-id}/.manifest.json`
+
+**Structure**:
+```json
+{
+ "session_id": "20250118-143022-a4f2",
+ "created_at": "2025-01-18T14:30:22Z",
+ "last_activity": "2025-01-18T14:35:10Z",
+ "context_files": {
+ "features/user-auth-context.md": {
+ "created": "2025-01-18T14:30:22Z",
+ "for": "@subagents/core/task-manager",
+ "keywords": ["user-auth", "authentication", "features"]
+ },
+ "tasks/user-auth-tasks.md": {
+ "created": "2025-01-18T14:32:15Z",
+ "for": "@subagents/core/task-manager",
+ "keywords": ["user-auth", "tasks", "breakdown"]
+ },
+ "documentation/api-docs-context.md": {
+ "created": "2025-01-18T14:35:10Z",
+ "for": "@subagents/core/documentation",
+ "keywords": ["api", "documentation"]
+ }
+ },
+ "context_index": {
+ "user-auth": [
+ "features/user-auth-context.md",
+ "tasks/user-auth-tasks.md"
+ ],
+ "api": [
+ "documentation/api-docs-context.md"
+ ]
+ }
+}
+```
+
+## Temporary Context Files
+
+### When to Create
+Only create context files when **ALL** of these apply:
+- Delegating to a subagent
+- Context description is verbose (>2 sentences) OR
+- Risk of misinterpretation without detailed context
+
+### File Structure
+```
+.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md
+```
+
+### Categories
+- `features/` - Feature development context
+- `documentation/` - Documentation tasks
+- `code/` - Code-related tasks
+- `refactoring/` - Refactoring tasks
+- `testing/` - Testing tasks
+- `tasks/` - Task breakdowns created by task-manager
+- `general/` - General tasks that don't fit other categories
+
+### Examples
+```
+.tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
+.tmp/sessions/20250118-143022-a4f2/documentation/api-docs-context.md
+.tmp/sessions/20250118-150000-b7k9/code/database-refactor-context.md
+.tmp/sessions/20250118-151500-c3x8/testing/integration-tests-context.md
+```
+
+### File Contents
+```markdown
+# Context: {Task Name}
+Session: {session-id}
+
+## Request Summary
+[Brief description of what needs to be done]
+
+## Background
+[Relevant context and information]
+
+## Expected Output
+[What the subagent should produce]
+
+## Constraints
+[Any limitations or requirements]
+```
+
+## Cleanup Strategy
+
+### During Session
+1. Remove individual context files after task completion
+2. Update manifest to remove file entry
+3. Update `last_activity` timestamp
+
+### End of Session
+1. Remove entire session folder: `.tmp/sessions/{session-id}/`
+2. Only delete files tracked in current session's manifest
+
+### Stale Session Cleanup
+- Automatically clean sessions older than 24 hours with no activity
+- Check `last_activity` timestamp in manifest
+- Safe to run periodically without affecting active sessions
+
+### Manual Cleanup
+Users can safely delete:
+- Entire `.tmp/` folder anytime
+- Individual session folders
+- Stale sessions (check `last_activity` timestamp)
+
+## Concurrent Safety
+
+### Isolation Guarantees
+✅ Each agent instance has unique session ID
+✅ Context files are isolated per session
+✅ Manifest tracks only files created by this session
+✅ Cleanup only affects current session's files
+✅ No risk of deleting another instance's context
+
+### Best Practices
+1. **Generate session ID early** - At first context file creation
+2. **Track all files** - Add every context file to manifest
+3. **Update activity** - Touch `last_activity` on each operation
+4. **Clean up promptly** - Remove files after task completion
+5. **Only clean own files** - Never delete files outside current session
+
+## Dynamic Context Loading
+
+### Purpose
+Allow subagents to discover and load relevant context files created earlier in the session.
+
+### How It Works
+
+**1. Context File Creation**
+When creating a context file, add metadata to manifest:
+```json
+"context_files": {
+ "features/user-auth-context.md": {
+ "created": "2025-01-18T14:30:22Z",
+ "for": "@subagents/core/task-manager",
+ "keywords": ["user-auth", "authentication", "features"]
+ }
+}
+```
+
+**2. Context Indexing**
+Manifest maintains keyword index for fast lookup:
+```json
+"context_index": {
+ "user-auth": [
+ "features/user-auth-context.md",
+ "tasks/user-auth-tasks.md"
+ ]
+}
+```
+
+**3. Context Discovery**
+When delegating to subagent:
+1. Search manifest for related context files (by keyword/category)
+2. Pass relevant context file paths to subagent
+3. Subagent reads context files as needed
+
+**4. Delegation Pattern**
+```
+Delegating to @subagents/code/coder-agent:
+"Implement user authentication login component.
+
+Related context available at:
+- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
+- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
+
+Read these files for full context on requirements and task breakdown."
+```
+
+### Example Workflow
+
+```
+1. User: "Build user authentication system"
+ → OpenAgent creates: features/user-auth-context.md
+ → Delegates to @task-manager
+
+2. Task-manager creates: tasks/user-auth-tasks.md
+ → Both files tracked in manifest with keyword "user-auth"
+
+3. User: "Implement the login component"
+ → OpenAgent searches manifest for "user-auth" context
+ → Finds both context files
+ → Delegates to @coder-agent with references to both files
+ → Coder-agent reads files to understand full context
+```
+
+### Benefits
+- **No context loss**: Information persists across subagent calls
+- **Automatic discovery**: Related context found by keywords
+- **Flexible**: Subagents read only what they need
+- **Traceable**: Manifest shows all context relationships
+
+---
+
+## Why This Approach?
+
+### Session Isolation
+- **Concurrent safety**: Multiple agents can run simultaneously
+- **No conflicts**: Each session has its own namespace
+- **Easy cleanup**: Delete entire session folder when done
+- **Traceable**: Manifest shows what belongs to each session
+
+### Dynamic Context
+- **Discoverable**: Context files indexed by keywords
+- **Reusable**: Later subagents can access earlier context
+- **Flexible**: Load only relevant context
+- **Persistent**: Context survives across subagent calls
+
+### Why `.tmp/sessions/`?
+- Standard `.tmp/` convention (commonly ignored)
+- `sessions/` subfolder makes purpose clear
+- Session ID provides unique namespace
+- Easy to identify and clean up stale sessions
+- Hidden folder (starts with `.`)
+
+## Example Workflow
+
+```bash
+# Agent Instance 1 starts
+Session ID: 20250118-143022-a4f2
+Creates: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
+
+# Agent Instance 2 starts (concurrent)
+Session ID: 20250118-143030-b7k9
+Creates: .tmp/sessions/20250118-143030-b7k9/features/payment-context.md
+
+# Both agents work independently without conflicts
+
+# Agent Instance 1 completes
+Deletes: .tmp/sessions/20250118-143022-a4f2/ (entire folder)
+
+# Agent Instance 2 continues unaffected
+Still has: .tmp/sessions/20250118-143030-b7k9/
+```
diff --git a/docs/agents/openagent.md b/docs/agents/openagent.md
new file mode 100644
index 0000000..7c2424b
--- /dev/null
+++ b/docs/agents/openagent.md
@@ -0,0 +1,943 @@
+# OpenAgent - Universal Agent Guide
+
+**Your intelligent assistant for questions, tasks, and workflows**
+
+OpenAgent is the primary universal agent in OpenCode that handles everything from simple questions to complex multi-step workflows. This guide explains how it works and how to get the most out of it.
+
+---
+
+## Table of Contents
+
+- [What is OpenAgent?](#what-is-openagent)
+- [How It Works](#how-it-works)
+- [The Two Paths](#the-two-paths)
+- [The 6-Stage Workflow](#the-6-stage-workflow)
+- [Session Management](#session-management)
+- [Dynamic Context Loading](#dynamic-context-loading)
+- [When OpenAgent Delegates](#when-openagent-delegates)
+- [Visual Workflows](#visual-workflows)
+- [Tips for Your Workflow](#tips-for-your-workflow)
+
+---
+
+## What is OpenAgent?
+
+OpenAgent is your **universal assistant** that:
+
+- ✅ **Answers questions** - Get explanations, comparisons, and guidance
+- ✅ **Executes tasks** - Create files, update code, run commands
+- ✅ **Coordinates workflows** - Breaks down complex features and delegates to specialists
+- ✅ **Preserves context** - Remembers information across multiple steps
+- ✅ **Keeps you in control** - Always asks for approval before taking action
+
+Think of OpenAgent as a **smart project manager** who:
+- Understands what you need
+- Plans how to do it
+- Asks for your approval
+- Executes the plan
+- Confirms everything is done right
+
+---
+
+## How It Works
+
+### The Simple Version
+
+```mermaid
+graph LR
+ A[You Ask] --> B{Question or Task?}
+ B -->|Question| C[Get Answer]
+ B -->|Task| D[See Plan]
+ D --> E[Approve Plan]
+ E --> F[Watch Execution]
+ F --> G[Confirm Done]
+
+ style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#000
+ style B fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style C fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+ style D fill:#50E3C2,stroke:#3AB89E,stroke-width:3px,color:#000
+ style E fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style F fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style G fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+```
+
+**For Questions**: You ask → You get an answer
+**For Tasks**: You ask → See plan → Approve → Watch it happen → Confirm done
+
+---
+
+## The Two Paths
+
+OpenAgent has two different ways of working, depending on what you need:
+
+### Path 1: Conversational (For Questions)
+
+```mermaid
+graph TD
+ A[Ask Question] --> B[OpenAgent Analyzes]
+ B --> C[Provides Answer]
+ C --> D[Done!]
+
+ style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#000
+ style B fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style C fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+ style D fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+```
+
+**When**: You ask informational questions
+**Examples**:
+- "What's the difference between REST and GraphQL?"
+- "How do I use async/await in JavaScript?"
+- "Explain what this code does"
+
+**What Happens**: You get a direct, helpful answer. No approval needed.
+
+---
+
+### Path 2: Task Execution (For Actions)
+
+```mermaid
+graph TD
+ A[Request Task] --> B[OpenAgent Creates Plan]
+ B --> C[Shows You Plan]
+ C --> D{Approve?}
+ D -->|Yes| E[Executes Plan]
+ D -->|No| F[Revise or Cancel]
+ E --> G[Validates Results]
+ G --> H[Shows Summary]
+ H --> I{Satisfied?}
+ I -->|Yes| J[Cleanup if Needed]
+ I -->|No| K[Fix Issues]
+ J --> L[Done!]
+
+ style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#000
+ style B fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style C fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style D fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style E fill:#50E3C2,stroke:#3AB89E,stroke-width:3px,color:#000
+ style F fill:#D0021B,stroke:#A00116,stroke-width:3px,color:#fff
+ style G fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style H fill:#50E3C2,stroke:#3AB89E,stroke-width:3px,color:#000
+ style I fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style J fill:#50E3C2,stroke:#3AB89E,stroke-width:3px,color:#000
+ style K fill:#D0021B,stroke:#A00116,stroke-width:3px,color:#fff
+ style L fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+```
+
+**When**: You want something done
+**Examples**:
+- "Create a README for this project"
+- "Build a user authentication system"
+- "Refactor this code to use TypeScript"
+
+**What Happens**:
+1. You see a plan
+2. You approve it
+3. OpenAgent executes it
+4. You confirm it's done right
+
+---
+
+## The 6-Stage Workflow
+
+When you request a task, OpenAgent follows a systematic 6-stage workflow:
+
+```mermaid
+graph TD
+ subgraph Stage1["Stage 1: Analyze"]
+ A1[Receive Request] --> A2[Assess Complexity]
+ A2 --> A3{Question or Task?}
+ end
+
+ subgraph Stage2["Stage 2: Approve"]
+ B1[Create Plan] --> B2[Present to User]
+ B2 --> B3[Wait for Approval]
+ end
+
+ subgraph Stage3["Stage 3: Execute"]
+ C1[Execute Steps] --> C2{Need Help?}
+ C2 -->|Yes| C3[Delegate to Specialist]
+ C2 -->|No| C4[Do It Directly]
+ C3 --> C5[Integrate Results]
+ C4 --> C5
+ end
+
+ subgraph Stage4["Stage 4: Validate"]
+ D1[Check Quality] --> D2[Run Tests if Applicable]
+ D2 --> D3{Issues Found?}
+ D3 -->|Yes| D4[Report & Propose Fixes]
+ D4 --> D5[Wait for Approval]
+ D5 --> D6[Apply Approved Fixes]
+ D6 --> D2
+ D3 -->|No| D7[Ask: Review Work?]
+ end
+
+ subgraph Stage5["Stage 5: Summarize"]
+ E1[Create Summary] --> E2[Show Changes]
+ E2 --> E3[Suggest Next Steps]
+ end
+
+ subgraph Stage6["Stage 6: Confirm Completion"]
+ F1[Ask if Satisfied] --> F2{Session Files?}
+ F2 -->|Yes| F3[Ask about Cleanup]
+ F2 -->|No| F4[Done]
+ F3 --> F5[Cleanup on Approval]
+ F5 --> F4
+ end
+
+ A3 -->|Question| Answer[Direct Answer]
+ A3 -->|Task| Stage2
+ Stage2 --> Stage3
+ Stage3 --> Stage4
+ Stage4 --> Stage5
+ Stage5 --> Stage6
+
+ style Stage1 fill:#4A90E2,stroke:#2E5C8A,stroke-width:4px,color:#fff
+ style Stage2 fill:#F5A623,stroke:#C17D11,stroke-width:4px,color:#000
+ style Stage3 fill:#50E3C2,stroke:#3AB89E,stroke-width:4px,color:#000
+ style Stage4 fill:#BD10E0,stroke:#9012B3,stroke-width:4px,color:#fff
+ style Stage5 fill:#9013B3,stroke:#7011A0,stroke-width:4px,color:#fff
+ style Stage6 fill:#7ED321,stroke:#5FA319,stroke-width:4px,color:#000
+ style Answer fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+```
+
+### Stage 1: Analyze
+**What happens**: OpenAgent reads your request and decides if it's a question or a task.
+
+**Your experience**: Instant - you don't see this happening.
+
+---
+
+### Stage 2: Approve ⚠️ (MANDATORY for tasks)
+**What happens**: OpenAgent creates a plan and shows it to you.
+
+**Your experience**: You see something like:
+```
+## Proposed Plan
+1. Create README.md file
+2. Add project overview section
+3. Add installation instructions
+4. Add usage examples
+
+**Approval needed before proceeding.**
+```
+
+**What you do**: Review the plan and say "yes" or "no" (or ask for changes).
+
+---
+
+### Stage 3: Execute
+**What happens**: OpenAgent carries out the plan, either directly or by delegating to specialist agents.
+
+**Your experience**: You might see:
+- Files being created or modified
+- Commands being run
+- Progress updates
+- Results from specialist agents
+
+**Behind the scenes**: OpenAgent might create temporary files to preserve context between steps.
+
+---
+
+### Stage 4: Validate ⚠️ (MANDATORY for tasks)
+**What happens**: OpenAgent checks the quality of the work, runs tests if applicable, and ensures everything works correctly.
+
+**Your experience when validation passes**: You see:
+```
+✅ Validation complete - all checks passed.
+
+Would you like me to run any additional checks or review the work before I summarize?
+- Run specific tests
+- Check specific files
+- Review changes
+- Proceed to summary
+```
+
+**What you do**: Choose to review further or proceed to summary.
+
+#### Special Case: Test Failures or Issues Found
+
+If OpenAgent runs tests or validation and finds issues, it follows a **strict protocol**:
+
+**What happens**:
+1. ⛔ **STOPS** execution immediately
+2. 📋 **REPORTS** all issues/failures clearly
+3. 📝 **PROPOSES** a fix plan with specific steps
+4. ⚠️ **REQUESTS APPROVAL** before fixing (mandatory)
+5. ✅ **PROCEEDS** only after you approve
+6. 🔄 **RE-VALIDATES** after fixes are applied
+
+**Your experience**: You see something like:
+```
+## Validation Results
+❌ 3 tests failed:
+- test_user_auth: Expected 200, got 401
+- test_login: Missing token in response
+- test_logout: Session not cleared
+
+## Proposed Fix Plan
+1. Update auth middleware to return proper status codes
+2. Add token generation to login endpoint
+3. Add session cleanup to logout handler
+
+**Approval needed before proceeding with fixes.**
+```
+
+**Important**: OpenAgent will **NEVER** auto-fix issues without your explicit approval. After fixes are applied, validation runs again to ensure everything passes.
+
+---
+
+### Stage 5: Summarize
+**What happens**: After validation passes and you're satisfied, OpenAgent creates a summary of what was accomplished.
+
+**Your experience**: You see a summary like:
+```
+## Summary
+Created README.md with project documentation.
+
+**Changes Made:**
+- Created README.md
+- Added project overview
+- Added installation guide
+- Added usage examples
+
+**Next Steps:** Review the README and update as needed.
+```
+
+---
+
+### Stage 6: Confirm Completion ⚠️ (MANDATORY for tasks)
+**What happens**: OpenAgent asks if you're satisfied and if temporary files should be cleaned up.
+
+**Your experience**: You see:
+```
+Is this complete and satisfactory?
+Should I clean up temporary session files at .tmp/sessions/20250118-143022-a4f2/?
+```
+
+**What you do**: Confirm you're happy with the results and approve cleanup if needed.
+
+---
+
+## Session Management
+
+When OpenAgent works on complex tasks, it creates a **session** to keep track of everything.
+
+### What is a Session?
+
+A session is like a **temporary workspace** where OpenAgent stores:
+- Context files (requirements, specifications)
+- Task breakdowns
+- Notes for specialist agents
+- Progress tracking
+
+### Session Structure
+
+```mermaid
+graph TD
+ A[Session Folder] --> B[manifest file]
+ A --> C[features folder]
+ A --> D[tasks folder]
+ A --> E[code folder]
+ A --> F[documentation folder]
+ A --> G[Other categories]
+
+ B --> B1[Tracks all files]
+ B --> B2[Keywords for search]
+ B --> B3[Creation timestamps]
+
+ C --> C1[Requirements and specs]
+ D --> D1[Task breakdowns]
+ E --> E1[Implementation notes]
+ F --> F1[Documentation context]
+
+ style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
+ style B fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style C fill:#50E3C2,stroke:#3AB89E,stroke-width:2px,color:#000
+ style D fill:#50E3C2,stroke:#3AB89E,stroke-width:2px,color:#000
+ style E fill:#50E3C2,stroke:#3AB89E,stroke-width:2px,color:#000
+ style F fill:#50E3C2,stroke:#3AB89E,stroke-width:2px,color:#000
+ style G fill:#50E3C2,stroke:#3AB89E,stroke-width:2px,color:#000
+```
+
+### Session Lifecycle
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant OpenAgent
+ participant Session
+
+ User->>OpenAgent: Request complex task
+ OpenAgent->>OpenAgent: Needs context file?
+ OpenAgent->>Session: Create session (lazy)
+ Session-->>OpenAgent: Session ID: abc123
+ OpenAgent->>Session: Create context files
+ OpenAgent->>OpenAgent: Execute task
+ OpenAgent->>User: Show results
+ User->>OpenAgent: Confirm done
+ OpenAgent->>User: Cleanup session files?
+ User->>OpenAgent: Yes
+ OpenAgent->>Session: Delete session
+ Session-->>OpenAgent: Cleaned up
+ OpenAgent->>User: All done!
+```
+
+### Key Features
+
+**Lazy Initialization**: Sessions are only created when actually needed (not for simple tasks).
+
+**Unique IDs**: Each session gets a unique ID like `20250118-143022-a4f2` to prevent conflicts.
+
+**Safe Cleanup**: OpenAgent only deletes files it created, and only after you approve.
+
+**Concurrent Safety**: Multiple users can work simultaneously without interfering with each other.
+
+---
+
+## Dynamic Context Loading
+
+One of OpenAgent's superpowers is **remembering context** across multiple steps.
+
+### The Problem It Solves
+
+Imagine this scenario:
+1. You ask: "Build a user authentication system"
+2. OpenAgent creates requirements and task breakdown
+3. Later, you ask: "Implement the login component"
+
+**Without context loading**: OpenAgent wouldn't remember the requirements from step 1.
+**With context loading**: OpenAgent finds and uses the requirements automatically.
+
+### How It Works
+
+```mermaid
+graph TD
+ subgraph Step1["Step 1: Create Context"]
+ A1[User requests auth system] --> A2[Create requirements file]
+ A2 --> A3[Add to manifest with keywords]
+ A3 --> A4[Keywords added]
+ end
+
+ subgraph Step2["Step 2: Create Tasks"]
+ B1[Delegate to task-manager] --> B2[Create task breakdown]
+ B2 --> B3[Add to manifest with keywords]
+ B3 --> B4[Keywords added]
+ end
+
+ subgraph Step3["Step 3: Use Context"]
+ C1[User requests login] --> C2[Search manifest]
+ C2 --> C3[Find related files]
+ C3 --> C4[Pass paths to specialist]
+ C4 --> C5[Specialist reads context]
+ end
+
+ Step1 --> Step2
+ Step2 --> Step3
+
+ style Step1 fill:#4A90E2,stroke:#2E5C8A,stroke-width:4px,color:#fff
+ style Step2 fill:#50E3C2,stroke:#3AB89E,stroke-width:4px,color:#000
+ style Step3 fill:#7ED321,stroke:#5FA319,stroke-width:4px,color:#000
+```
+
+### The Manifest
+
+The manifest is like an **index** that tracks all context files:
+
+```json
+{
+ "session_id": "20250118-143022-a4f2",
+ "context_files": {
+ "features/user-auth-context.md": {
+ "created": "2025-01-18T14:30:22Z",
+ "for": "@task-manager",
+ "keywords": ["user-auth", "authentication", "features"]
+ },
+ "tasks/user-auth-tasks.md": {
+ "created": "2025-01-18T14:32:15Z",
+ "for": "@task-manager",
+ "keywords": ["user-auth", "tasks", "breakdown"]
+ }
+ },
+ "context_index": {
+ "user-auth": [
+ "features/user-auth-context.md",
+ "tasks/user-auth-tasks.md"
+ ]
+ }
+}
+```
+
+**Benefits**:
+- ✅ No context loss across steps
+- ✅ Automatic discovery by keywords
+- ✅ Flexible - only loads what's needed
+- ✅ Traceable - you can see what context was used
+
+---
+
+## When OpenAgent Delegates
+
+OpenAgent knows when to do work itself and when to call in specialists.
+
+### Decision Tree
+
+```mermaid
+graph TD
+ A[Receive Task] --> B{What type?}
+
+ B -->|Question| C[Answer Directly]
+
+ B -->|Task| D{How complex?}
+
+ D -->|3+ files OR 60+ min OR complex| E[Delegate to task-manager]
+ E --> E1[Breaks down into subtasks]
+
+ D -->|Comprehensive docs OR multi-page| F[Delegate to documentation]
+ F --> F1[Creates structured docs]
+
+ D -->|Specialized code task| G[Delegate to code specialists]
+ G --> G1[Testing, review, build]
+
+ D -->|Simple OR single file OR under 30 min| H[Execute Directly]
+ H --> H1[OpenAgent handles it]
+
+ style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
+ style B fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style C fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+ style D fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#000
+ style E fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style F fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style G fill:#BD10E0,stroke:#9012B3,stroke-width:3px,color:#fff
+ style H fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000
+```
+
+### Delegation Criteria
+
+#### Delegate to @task-manager when:
+- ✅ Feature spans **3+ files/modules**
+- ✅ Estimated effort **>60 minutes**
+- ✅ Needs **breakdown into subtasks**
+- ✅ **Complex dependencies** between components
+- ✅ User **explicitly requests** task breakdown
+
+**Example**: "Build user authentication system"
+
+---
+
+#### Delegate to @documentation when:
+- ✅ Creating **comprehensive docs** (API docs, guides, tutorials)
+- ✅ **Multi-page** documentation
+- ✅ Requires **codebase analysis/research**
+- ✅ User **explicitly requests** documentation agent
+
+**Example**: "Create API documentation for all endpoints"
+
+---
+
+#### Delegate to @code/* when:
+- ✅ **Code-specific specialized task** (testing, review, build)
+- ✅ Code subagents are **available** in current profile
+
+**Examples**:
+- "Review this code for security issues" → @code/reviewer
+- "Write tests for this module" → @code/tester
+- "Run build and fix errors" → @code/build-agent
+
+---
+
+#### Execute directly when:
+- ✅ **Single file** operation
+- ✅ **Simple, straightforward** task (<30 min)
+- ✅ **Quick updates/edits**
+- ✅ User **explicitly asks** openagent to handle it
+
+**Examples**:
+- "Create a README"
+- "Update this function to use async/await"
+- "Add a comment to this code"
+
+---
+
+## Visual Workflows
+
+### Complete Task Workflow
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant OpenAgent
+ participant Session
+ participant Specialist
+
+ User->>OpenAgent: "Build authentication system"
+
+ Note over OpenAgent: Stage 1: Analyze
+ OpenAgent->>OpenAgent: Complex task, needs task-manager
+
+ Note over OpenAgent: Stage 2: Approve
+ OpenAgent->>User: ## Proposed Plan
1. Create requirements
2. Delegate to task-manager
3. Review breakdown
**Approval needed**
+ User->>OpenAgent: Approved
+
+ Note over OpenAgent: Stage 3: Execute
+ OpenAgent->>Session: Create session abc123
+ OpenAgent->>Session: Create features/user-auth-context.md
+ Session-->>OpenAgent: File created, added to manifest
+
+ OpenAgent->>Specialist: @task-manager: Break down auth system
Context: .tmp/sessions/abc123/features/user-auth-context.md
+ Specialist->>Session: Create tasks/user-auth-tasks.md
+ Specialist-->>OpenAgent: Task breakdown complete
+
+ OpenAgent->>Session: Update manifest with new file
+
+ Note over OpenAgent: Stage 4: Validate
+ OpenAgent->>OpenAgent: Check quality, run tests
+ OpenAgent->>User: ✅ Validation complete - all checks passed.
Would you like me to run any additional checks
or review the work before I summarize?
+ User->>OpenAgent: Proceed to summary
+
+ Note over OpenAgent: Stage 5: Summarize
+ OpenAgent->>User: ## Summary
Created task breakdown with 5 subtasks
**Changes:**
- Created context file
- Created task breakdown
+
+ Note over OpenAgent: Stage 6: Confirm
+ OpenAgent->>User: Is this complete and satisfactory?
Should I clean up session files?
+ User->>OpenAgent: Yes, looks good. Clean up.
+ OpenAgent->>Session: Delete session abc123
+ Session-->>OpenAgent: Cleaned up
+ OpenAgent->>User: ✓ All done!
+```
+
+### Multi-Step with Context Preservation
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant OpenAgent
+ participant Manifest
+ participant Specialist
+
+ Note over User,Specialist: Step 1: Initial Request
+ User->>OpenAgent: "Build auth system"
+ OpenAgent->>Manifest: Create features/user-auth-context.md
Keywords: [user-auth, authentication]
+ OpenAgent->>Specialist: @task-manager
+ Specialist->>Manifest: Create tasks/user-auth-tasks.md
Keywords: [user-auth, tasks]
+
+ Note over User,Specialist: Step 2: Later Request
+ User->>OpenAgent: "Implement login component"
+ OpenAgent->>Manifest: Search for "login" or "user-auth"
+ Manifest-->>OpenAgent: Found:
- features/user-auth-context.md
- tasks/user-auth-tasks.md
+ OpenAgent->>Specialist: @coder-agent: Implement login
Related context:
- features/user-auth-context.md
- tasks/user-auth-tasks.md
+ Specialist->>Manifest: Read context files
+ Specialist-->>OpenAgent: Login component implemented with full context
+
+ Note over OpenAgent: ✓ No context loss!
+```
+
+### Concurrent Sessions
+
+```mermaid
+graph TD
+ subgraph UserA["User A Session"]
+ A1[Request: Build auth] --> A2[Session abc123]
+ A2 --> A3[features context]
+ A2 --> A4[tasks context]
+ end
+
+ subgraph UserB["User B Session"]
+ B1[Request: Build payment] --> B2[Session def456]
+ B2 --> B3[features context]
+ B2 --> B4[tasks context]
+ end
+
+ subgraph Isolation["Session Isolation"]
+ I1[Unique Session IDs]
+ I2[Separate Folders]
+ I3[Independent Manifests]
+ I4[No Conflicts]
+ end
+
+ A2 -.->|Isolated| Isolation
+ B2 -.->|Isolated| Isolation
+
+ style UserA fill:#4A90E2,stroke:#2E5C8A,stroke-width:4px,color:#fff
+ style UserB fill:#7ED321,stroke:#5FA319,stroke-width:4px,color:#000
+ style Isolation fill:#F5A623,stroke:#C17D11,stroke-width:4px,color:#000
+```
+
+---
+
+## Tips for Your Workflow
+
+### 1. Be Specific in Your Requests
+
+**Instead of**: "Make this better"
+**Try**: "Refactor this function to use async/await and add error handling"
+
+**Why**: Specific requests help OpenAgent create better plans and get approval faster.
+
+---
+
+### 2. Review Plans Carefully
+
+When OpenAgent shows you a plan, take a moment to review it:
+- ✅ Does it match what you want?
+- ✅ Are there any steps you'd change?
+- ✅ Is anything missing?
+
+**Tip**: You can ask OpenAgent to revise the plan before approving.
+
+---
+
+### 3. Use Multi-Step Workflows
+
+For complex projects, break them into steps:
+
+```
+Step 1: "Build user authentication system"
+→ Review task breakdown
+
+Step 2: "Implement the registration component"
+→ OpenAgent uses context from Step 1
+
+Step 3: "Implement the login component"
+→ OpenAgent uses context from Steps 1 & 2
+```
+
+**Why**: OpenAgent preserves context across steps, making each step easier.
+
+---
+
+### 4. Leverage Specialist Agents
+
+Let OpenAgent delegate to specialists:
+- **Complex features** → Let task-manager break them down
+- **Documentation** → Let documentation agent create comprehensive docs
+- **Code review** → Let reviewer agent check for issues
+
+**Tip**: You can explicitly request a specialist: "Use the documentation agent to create API docs"
+
+---
+
+### 5. Clean Up Sessions Regularly
+
+After completing a workflow, approve session cleanup:
+- ✅ Keeps your workspace clean
+- ✅ Prevents accumulation of temporary files
+- ✅ Frees up disk space
+
+**Tip**: You can also manually clean up stale sessions:
+```bash
+./scripts/cleanup-stale-sessions.sh
+```
+
+---
+
+### 6. Use Keywords Consistently
+
+When working on related tasks, use consistent terminology:
+- "user authentication" (not "auth" in one request and "login system" in another)
+- "payment processing" (not "payments" and "checkout" interchangeably)
+
+**Why**: Helps OpenAgent find related context files more easily.
+
+---
+
+### 7. Provide Context for Follow-Up Requests
+
+When making follow-up requests, reference previous work:
+
+**Good**: "Implement the login component from the auth system we planned earlier"
+**Better**: "Implement the login component using the user-auth requirements"
+
+**Why**: Helps OpenAgent search for the right context files.
+
+---
+
+### 8. Customize Delegation Thresholds
+
+You can adjust when OpenAgent delegates by modifying the criteria in `.opencode/agent/openagent.md`:
+
+**Current defaults**:
+- 3+ files → Delegate to task-manager
+- >60 minutes → Delegate to task-manager
+- <30 minutes → Execute directly
+
+**To customize**: Edit the `` section to match your preferences.
+
+---
+
+### 9. Create Your Own Categories
+
+The default categories are:
+- features, documentation, code, refactoring, testing, tasks, general
+
+**To add custom categories**: Edit the `` line in openagent.md:
+```xml
+features | documentation | code | refactoring | testing | general | tasks | your-category
+```
+
+**Use case**: If you frequently work on "migrations" or "integrations", add those as categories.
+
+---
+
+### 10. Monitor Session Files
+
+Occasionally check `.tmp/sessions/` to see what context is being preserved:
+
+```bash
+ls -la .tmp/sessions/
+```
+
+**Why**: Helps you understand what context OpenAgent is using and identify any issues.
+
+---
+
+### 11. Use Explicit Approvals for Learning
+
+When learning a new codebase or technology, use OpenAgent's approval step as a learning opportunity:
+- Read the plan carefully
+- Ask questions about steps you don't understand
+- Request explanations before approving
+
+**Example**:
+```
+OpenAgent: "I'll refactor this to use dependency injection"
+You: "What is dependency injection and why is it better here?"
+OpenAgent: [Explains]
+You: "Got it, approved!"
+```
+
+---
+
+### 12. Combine with Other Agents
+
+OpenAgent works great with other agents in your profile:
+- Use OpenAgent for planning and coordination
+- Let specialists handle their domains
+- OpenAgent will preserve context between them
+
+**Example workflow**:
+1. OpenAgent plans the feature
+2. @coder-agent implements it
+3. @tester writes tests
+4. @reviewer checks quality
+5. @documentation documents it
+
+All coordinated by OpenAgent with preserved context!
+
+---
+
+## Advanced Tips
+
+### Create Reusable Context Templates
+
+For recurring workflows, create context templates:
+
+**Example**: `.opencode/templates/feature-context.md`
+```markdown
+# Feature: {FEATURE_NAME}
+
+## Requirements
+- [List requirements]
+
+## Constraints
+- [List constraints]
+
+## Success Criteria
+- [List criteria]
+```
+
+**Use**: "Create a new feature using the feature-context template"
+
+---
+
+### Use Session IDs for Debugging
+
+If something goes wrong, note the session ID:
+```
+Session: 20250118-143022-a4f2
+```
+
+You can inspect the session folder to see what context was created:
+```bash
+cat .tmp/sessions/20250118-143022-a4f2/.manifest.json
+```
+
+---
+
+### Batch Related Tasks
+
+Group related tasks in one session for better context:
+
+**Instead of**:
+- Request 1: "Create user model"
+- Request 2: "Create auth controller"
+- Request 3: "Create login route"
+
+**Try**:
+- Request: "Build user authentication with model, controller, and routes"
+
+**Why**: Single session, all context preserved, more efficient.
+
+---
+
+## Core Principles
+
+OpenAgent follows these core principles:
+
+### 🎯 Lean
+Concise responses, no over-explanation. Gets to the point quickly.
+
+### 🔄 Adaptive
+Conversational for questions, formal for tasks. Matches the context.
+
+### ⚡ Lazy
+Only creates sessions/files when actually needed. No unnecessary overhead.
+
+### 🔒 Safe
+**ALWAYS** requests approval before ANY execution. Confirms before cleanup.
+
+### 📋 Report First
+When tests fail or issues are found:
+1. **REPORT** the issues
+2. **PLAN** the fixes
+3. **REQUEST APPROVAL**
+4. **FIX** (only after approval)
+
+**Never auto-fixes** - you're always in control.
+
+---
+
+## Summary
+
+OpenAgent is your **intelligent project manager** that:
+
+✅ **Plans before acting** - Shows you the plan and waits for approval
+✅ **Preserves context** - Remembers information across multiple steps
+✅ **Delegates wisely** - Calls in specialists when needed
+✅ **Keeps you in control** - Always confirms before cleanup
+✅ **Handles complexity** - Breaks down big tasks into manageable pieces
+✅ **Reports before fixing** - Never auto-fixes issues without approval
+
+**Key Takeaways**:
+1. Be specific in your requests
+2. Review plans before approving
+3. Use multi-step workflows for complex projects
+4. Let OpenAgent delegate to specialists
+5. Clean up sessions when done
+6. Customize to fit your workflow
+7. Expect reports before fixes when issues are found
+
+**Ready to get started?** Just ask OpenAgent a question or request a task!
+
+---
+
+## Configuration
+
+OpenAgent is configured in `.opencode/agent/openagent.md`. You can customize:
+- Delegation thresholds
+- Categories
+- Error handling
+- Test failure protocol
+- And more!
+
+Happy building! 🚀
diff --git a/docs/features/system-builder/README.md b/docs/features/system-builder/README.md
index b869f55..11a0b57 100644
--- a/docs/features/system-builder/README.md
+++ b/docs/features/system-builder/README.md
@@ -13,9 +13,11 @@ curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/in
```
**What you get:**
-- ✅ All development tools (22 components)
+- ✅ All development tools (19 components)
+- ✅ Business tools (5 components)
- ✅ System builder (7 components)
-- ✅ **Total: 29 components**
+- ✅ Additional tools (1 component)
+- ✅ **Total: 32 components**
### Add to Existing Installation
diff --git a/docs/features/system-builder/quick-start.md b/docs/features/system-builder/quick-start.md
index b6ab628..036ac92 100644
--- a/docs/features/system-builder/quick-start.md
+++ b/docs/features/system-builder/quick-start.md
@@ -19,9 +19,11 @@ curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/in
```
**What you get:**
-- ✅ All development tools (22 components)
+- ✅ All development tools (19 components)
+- ✅ Business tools (5 components)
- ✅ System builder (7 components)
-- ✅ **Total: 29 components**
+- ✅ Additional tools (1 component)
+- ✅ **Total: 32 components**
---
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 eec327d..8b905d7 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
@@ -19,9 +19,11 @@ curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/in
```
**What you get:**
-- ✅ All development tools (22 components)
+- ✅ All development tools (19 components)
+- ✅ Business tools (5 components)
- ✅ System builder (7 components)
-- ✅ **Total: 29 components**
+- ✅ Additional tools (1 component)
+- ✅ **Total: 32 components**
---
diff --git a/docs/guides/building-with-opencode.md b/docs/guides/building-with-opencode.md
new file mode 100644
index 0000000..a91b1d9
--- /dev/null
+++ b/docs/guides/building-with-opencode.md
@@ -0,0 +1,515 @@
+# Building with OpenCode: The Power User Formula
+
+## Overview
+
+This guide teaches you how to build efficient, scalable OpenCode systems using the 4-layer architecture. Master this formula to create powerful AI workflows with minimal token usage and maximum reusability.
+
+## The 4-Layer Architecture
+
+```
+Layer 1: TOOLS → Atomic operations (read, test, lint)
+Layer 2: SUBAGENTS → Specialized skills (security, testing, refactoring)
+Layer 3: COMMANDS → User shortcuts + templates (slash commands)
+Layer 4: MAIN AGENTS → Orchestration (build, plan, general)
+```
+
+Each layer serves a specific purpose and builds upon the previous one.
+
+---
+
+## Layer 1: TOOLS - Build for Efficiency
+
+### The Rule
+Create tools for **frequent, verbose operations** that need output filtering or caching.
+
+### Structure
+```typescript
+// .opencode/tool/[operation].ts
+export default tool({
+ description: "One-line: what it does, when to use",
+ args: { /* minimal params */ },
+ async execute(args, ctx) {
+ // Run operation
+ // Parse output
+ // Return only what matters
+ return conciseResult
+ }
+})
+```
+
+### When to Build a Tool
+- ✅ Used 10+ times per session
+- ✅ Raw output >1KB, useful info <200 chars
+- ✅ Needs parsing/filtering/caching
+
+### Examples
+- `test-runner` - Run tests, return pass/fail + errors only
+- `lint-check` - Return only errors in changed files
+- `build-check` - Return warnings/errors, not full logs
+
+### Quick Start: Your First Tool
+```bash
+# Create your first efficient tool
+mkdir -p .opencode/tool
+cat > .opencode/tool/test.ts << 'EOF'
+import { tool } from "@opencode-ai/plugin"
+import { z } from "zod"
+
+export default tool({
+ description: "Run tests, return summary or failures only",
+ args: { path: z.string() },
+ async execute(args, ctx) {
+ const result = await ctx.$`npm test -- ${args.path}`.nothrow()
+ const output = await new Response(result.stdout).text()
+ return result.exitCode === 0
+ ? `✅ Tests passed`
+ : `❌ Failed:\n${output.split('\n').filter(l => l.includes('FAIL') || l.includes('●')).slice(0, 20).join('\n')}`
+ }
+})
+EOF
+
+# Test it
+opencode tui
+# Type: "run the tests"
+```
+
+---
+
+## Layer 2: SUBAGENTS - Build for Specialization
+
+### The Rule
+Create subagents for **complex, reusable workflows** that require domain expertise.
+
+### Structure
+```markdown
+# .opencode/agent/[domain]/[specialist].md
+---
+mode: "subagent"
+description: "Use WHEN/AFTER [trigger condition]"
+tools:
+ [essential-tool]: true
+ task: false # Prevent recursion
+---
+
+You are [role]. You specialize in:
+1. [Specific capability]
+2. [Specific capability]
+
+Always [output format/requirement].
+```
+
+### When to Build a Subagent
+- ✅ Multi-step process (3+ steps)
+- ✅ Requires domain expertise
+- ✅ Called by main agent OR user
+- ✅ Isolated context beneficial
+
+### Recommended Folder Structure
+```
+.opencode/agent/
+├── security/
+│ ├── code-scanner.md # Vulnerability detection
+│ ├── dependency-audit.md # Supply chain check
+│ └── secrets-detector.md # Credential scanning
+├── testing/
+│ ├── unit-generator.md # Generate unit tests
+│ ├── e2e-builder.md # E2E test creation
+│ └── test-fixer.md # Fix failing tests
+└── refactor/
+ ├── modernizer.md # Update legacy code
+ ├── optimizer.md # Performance improvements
+ └── simplifier.md # Reduce complexity
+```
+
+### Example: Security Scanner Subagent
+```markdown
+# .opencode/agent/security/code-scanner.md
+---
+mode: "subagent"
+description: "Use AFTER writing auth code to scan for vulnerabilities"
+tools:
+ lint-check: true
+ test-runner: true
+ task: false
+---
+
+You are a Security Specialist. You scan code for:
+1. SQL injection vulnerabilities
+2. XSS attack vectors
+3. Authentication/authorization flaws
+4. Insecure dependencies
+
+Always return a structured report with severity levels.
+```
+
+---
+
+## Layer 3: COMMANDS - Build for Convenience
+
+### The Rule
+Create commands for **common user workflows** that benefit from templates and context.
+
+### Structure
+```markdown
+# .opencode/command/[workflow]/[action].md
+---
+description: "What this does"
+agent: "[subagent-name]" # Routes to subagent
+---
+
+[Detailed prompt with context]
+@$1 # File references
+@AGENTS.md # Project standards
+Additional: $2
+```
+
+### When to Build a Command
+- ✅ User types it frequently
+- ✅ Needs specific context files
+- ✅ Benefits from template
+- ✅ Can reuse subagent
+
+### The Formula
+```
+Command = Subagent + Context Files + Template
+```
+
+### Examples
+```bash
+/security/scan file.ts # → security/code-scanner + project files
+/test/generate service.ts # → testing/unit-generator + test patterns
+/refactor/modernize legacy.js # → refactor/modernizer + standards
+```
+
+### Example: Security Audit Command
+```markdown
+# .opencode/command/security/audit.md
+---
+description: "Run comprehensive security audit on file"
+agent: "security/auditor"
+---
+
+Run a full security audit on @$1
+
+Include:
+- Vulnerability scanning
+- Dependency checks
+- Secret detection
+- Best practice validation
+
+Reference project standards: @AGENTS.md
+```
+
+---
+
+## Layer 4: MAIN AGENTS - Configure, Don't Create
+
+### The Rule
+**Customize builtin agents, rarely create new primary agents.**
+
+### Structure
+```markdown
+# .opencode/agent/build.md (override built-in)
+---
+mode: "primary"
+tools:
+ test-runner: true
+ lint-check: true
+---
+
+## Testing Protocol
+After code changes: use test-runner
+On failure: analyze and fix
+On complex failure: use Task(subagent_type="testing/test-fixer")
+
+## Quality Checks
+Before completing: lint-check
+If issues: fix automatically
+```
+
+### When to Create a New Primary Agent
+- ❌ Almost never - customize `build`, `plan`, `general` instead
+- ✅ Only for distinct modes (e.g., "code-review-only" mode)
+
+---
+
+## Complete Patterns
+
+### Pattern 1: Progressive Enhancement
+```
+User Request
+ ↓
+Main Agent (build) - uses tools for atomic ops
+ ↓ (if complex)
+Task Tool → Subagent - specialized workflow
+ ↓ (if needs helpers)
+Task Tool → More Subagents - parallel execution
+ ↓
+Return to Main Agent
+ ↓
+User Response
+```
+
+### Pattern 2: User Shortcuts
+```
+User: /security/full-audit auth.ts
+ ↓
+Command loads template + context files
+ ↓
+Routes to subagent (mode: "subagent")
+ ↓
+Subagent uses tools (test-runner, lint-check)
+ ↓
+Returns focused report
+```
+
+---
+
+## Real-World Example: Complete Setup
+
+### Tools (Efficiency)
+```
+.opencode/tool/
+├── test.ts # Smart test runner
+├── lint.ts # Filtered linter
+└── deps.ts # Dependency checker
+```
+
+### Subagents (Specialization)
+```
+.opencode/agent/
+├── security/
+│ └── auditor.md # Comprehensive security
+├── testing/
+│ ├── generator.md # Generate tests
+│ └── fixer.md # Fix failures
+└── code-review/
+ └── reviewer.md # Code quality
+```
+
+### Commands (Convenience)
+```
+.opencode/command/
+├── check.md # Quick health check
+├── security/
+│ └── audit.md # Full security audit
+└── test/
+ ├── generate.md # Generate tests
+ └── fix.md # Fix failing tests
+```
+
+### Main Agent (Orchestration)
+```
+.opencode/agent/
+└── build.md # Customized build agent
+```
+
+---
+
+## Decision Tree
+
+### "Should I build X?"
+
+#### TOOL?
+```
+Is it called 10+ times/session? → YES
+Does it need output filtering? → YES
+Can bash do it well enough? → NO if frequently used
+```
+
+#### SUBAGENT?
+```
+Is it 3+ step workflow? → YES
+Does it need isolated context? → YES
+Is it single atomic operation? → NO (make it a tool)
+```
+
+#### COMMAND?
+```
+Do users type this often? → YES
+Can it reuse existing subagent? → YES (just template it)
+Needs new capability? → NO (build subagent first)
+```
+
+#### MAIN AGENT?
+```
+Do you need a new mode? → Probably NO (customize existing)
+```
+
+---
+
+## The Winning Configuration
+
+### Minimal but Powerful
+```
+.opencode/
+├── tool/
+│ └── test.ts # 1 efficient test tool
+├── agent/
+│ ├── build.md # Customized with tool usage
+│ └── code-review/
+│ └── reviewer.md # 1 specialized subagent
+└── command/
+ └── review.md # 1 user shortcut
+```
+
+**This gives you:**
+- ✅ Efficient testing (90% token savings)
+- ✅ Code review capability
+- ✅ User convenience
+- ✅ Easy to maintain
+
+### Scale Up as Needed
+```
+.opencode/
+├── tool/ [2-5 tools max]
+│ ├── test.ts
+│ ├── lint.ts
+│ └── build.ts
+├── agent/ [5-15 subagents organized by domain]
+│ ├── security/
+│ ├── testing/
+│ ├── refactor/
+│ └── documentation/
+└── command/ [10-20 shortcuts]
+ ├── security/
+ ├── test/
+ └── refactor/
+```
+
+---
+
+## Pro Tips
+
+### 1. Start Small, Grow Organically
+```
+Week 1: Add test-runner tool
+Week 2: Add code-review subagent
+Week 3: Add shortcuts you use 3+ times
+```
+
+### 2. Make Subagents Discoverable
+```markdown
+description: "Use AFTER writing auth code to scan for vulnerabilities"
+```
+Main agent sees this in Task tool and knows when to call it.
+
+### 3. Template Everything
+```markdown
+# Command template
+@AGENTS.md # Always include standards
+@.cursorrules # Always include rules
+@$1 # Target file
+```
+
+### 4. Think in Layers
+- **Tools** = Efficiency
+- **Subagents** = Specialization
+- **Commands** = Convenience
+- **Main Agents** = Orchestration
+
+### 5. Avoid Redundancy
+```
+❌ Separate tool + subagent doing same thing
+✅ Tool for efficiency, subagent calls tool + adds intelligence
+```
+
+---
+
+## The Formula in One Diagram
+
+```
+┌─────────────────────────────────────────┐
+│ USER │
+│ /security/audit auth.ts │
+└──────────────┬──────────────────────────┘
+ │
+ ↓
+┌──────────────────────────────────────────┐
+│ COMMAND (Template + Context) │
+│ • Loads audit template │
+│ • Attaches @auth.ts, @AGENTS.md │
+│ • Routes to: security/auditor │
+└──────────────┬───────────────────────────┘
+ │
+ ↓
+┌──────────────────────────────────────────┐
+│ SUBAGENT (Specialized Workflow) │
+│ • Calls lint-check tool │
+│ • Calls test-runner tool │
+│ • Analyzes with domain expertise │
+│ • Returns focused report │
+└──────────────┬───────────────────────────┘
+ │
+ ↓
+┌──────────────────────────────────────────┐
+│ TOOLS (Efficient Operations) │
+│ • lint-check: 30K chars → 200 chars │
+│ • test-runner: 15K chars → 50 chars │
+│ • Total context: 250 chars vs 45K │
+└──────────────────────────────────────────┘
+```
+
+**Result:** 99% token savings, specialized analysis, user convenience.
+
+---
+
+## Getting Started
+
+### Step 1: Create Your First Tool
+```bash
+mkdir -p .opencode/tool
+cat > .opencode/tool/test.ts << 'EOF'
+import { tool } from "@opencode-ai/plugin"
+import { z } from "zod"
+
+export default tool({
+ description: "Run tests, return summary or failures only",
+ args: { path: z.string() },
+ async execute(args, ctx) {
+ const result = await ctx.$`npm test -- ${args.path}`.nothrow()
+ const output = await new Response(result.stdout).text()
+ return result.exitCode === 0
+ ? `✅ Tests passed`
+ : `❌ Failed:\n${output.split('\n').filter(l => l.includes('FAIL') || l.includes('●')).slice(0, 20).join('\n')}`
+ }
+})
+EOF
+```
+
+### Step 2: Test It
+```bash
+opencode tui
+# Type: "run the tests"
+# Agent will use your new tool
+```
+
+### Step 3: Add More Layers
+Once your tool works, add:
+1. A subagent that uses the tool
+2. A command that routes to the subagent
+3. Customize your main agent to use both
+
+---
+
+## Summary
+
+The Power User Formula is simple:
+
+1. **Tools** for efficiency (90% token savings)
+2. **Subagents** for specialization (domain expertise)
+3. **Commands** for convenience (user shortcuts)
+4. **Main Agents** for orchestration (customize, don't create)
+
+Start with one tool, grow organically, and always think in layers.
+
+**That's the formula.** Now go build something powerful.
+
+---
+
+## Related Documentation
+
+- [System Builder Guide](../features/system-builder/guide.md)
+- [Quick Start](../features/system-builder/quick-start.md)
+- [Agent System Blueprint](../features/agent-system-blueprint.md)
+- [Contributing Guide](../contributing/CONTRIBUTING.md)
diff --git a/install.sh b/install.sh
index daaa866..e602c7c 100755
--- a/install.sh
+++ b/install.sh
@@ -235,9 +235,9 @@ check_interactive_mode() {
echo "Or use a profile directly:"
echo ""
echo -e "${CYAN}# Quick install with profile${NC}"
- echo "curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh | bash -s core"
+ echo "curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh | bash -s essential"
echo ""
- echo "Available profiles: core, developer, full, advanced"
+ echo "Available profiles: essential, developer, business, full, advanced"
echo ""
cleanup_and_exit 1
fi
@@ -276,44 +276,61 @@ show_profile_menu() {
echo -e "${BOLD}Available Installation Profiles:${NC}\n"
- # Core profile
- local core_desc=$(jq -r '.profiles.core.description' "$TEMP_DIR/registry.json")
- local core_count=$(jq -r '.profiles.core.components | length' "$TEMP_DIR/registry.json")
- echo -e " ${GREEN}1) Core${NC}"
- echo -e " ${core_desc}"
- echo -e " Components: ${core_count}\n"
+ # Essential profile
+ local essential_name=$(jq -r '.profiles.essential.name' "$TEMP_DIR/registry.json")
+ local essential_desc=$(jq -r '.profiles.essential.description' "$TEMP_DIR/registry.json")
+ local essential_count=$(jq -r '.profiles.essential.components | length' "$TEMP_DIR/registry.json")
+ echo -e " ${GREEN}1) ${essential_name}${NC}"
+ echo -e " ${essential_desc}"
+ echo -e " Components: ${essential_count}\n"
# Developer profile
local dev_desc=$(jq -r '.profiles.developer.description' "$TEMP_DIR/registry.json")
local dev_count=$(jq -r '.profiles.developer.components | length' "$TEMP_DIR/registry.json")
- echo -e " ${BLUE}2) Developer${NC}"
+ local dev_badge=$(jq -r '.profiles.developer.badge // ""' "$TEMP_DIR/registry.json")
+ if [ -n "$dev_badge" ]; then
+ echo -e " ${BLUE}2) Developer ${GREEN}[${dev_badge}]${NC}"
+ else
+ echo -e " ${BLUE}2) Developer${NC}"
+ fi
echo -e " ${dev_desc}"
echo -e " Components: ${dev_count}\n"
+ # Business profile
+ local business_name=$(jq -r '.profiles.business.name' "$TEMP_DIR/registry.json")
+ local business_desc=$(jq -r '.profiles.business.description' "$TEMP_DIR/registry.json")
+ local business_count=$(jq -r '.profiles.business.components | length' "$TEMP_DIR/registry.json")
+ echo -e " ${CYAN}3) ${business_name}${NC}"
+ echo -e " ${business_desc}"
+ echo -e " Components: ${business_count}\n"
+
# Full profile
+ local full_name=$(jq -r '.profiles.full.name' "$TEMP_DIR/registry.json")
local full_desc=$(jq -r '.profiles.full.description' "$TEMP_DIR/registry.json")
local full_count=$(jq -r '.profiles.full.components | length' "$TEMP_DIR/registry.json")
- echo -e " ${MAGENTA}3) Full${NC}"
+ echo -e " ${MAGENTA}4) ${full_name}${NC}"
echo -e " ${full_desc}"
echo -e " Components: ${full_count}\n"
# Advanced profile
+ local adv_name=$(jq -r '.profiles.advanced.name' "$TEMP_DIR/registry.json")
local adv_desc=$(jq -r '.profiles.advanced.description' "$TEMP_DIR/registry.json")
local adv_count=$(jq -r '.profiles.advanced.components | length' "$TEMP_DIR/registry.json")
- echo -e " ${YELLOW}4) Advanced${NC}"
+ echo -e " ${YELLOW}5) ${adv_name}${NC}"
echo -e " ${adv_desc}"
echo -e " Components: ${adv_count}\n"
- echo " 5) Back to main menu"
+ echo " 6) Back to main menu"
echo ""
- read -p "Enter your choice [1-5]: " choice
+ read -p "Enter your choice [1-6]: " choice
case $choice in
- 1) PROFILE="core" ;;
+ 1) PROFILE="essential" ;;
2) PROFILE="developer" ;;
- 3) PROFILE="full" ;;
- 4) PROFILE="advanced" ;;
- 5) show_main_menu; return ;;
+ 3) PROFILE="business" ;;
+ 4) PROFILE="full" ;;
+ 5) PROFILE="advanced" ;;
+ 6) show_main_menu; return ;;
*) print_error "Invalid choice"; sleep 2; show_profile_menu; return ;;
esac
@@ -608,8 +625,8 @@ get_install_strategy() {
perform_installation() {
print_step "Preparing installation..."
- # Create directory structure if it doesn't exist
- mkdir -p "$INSTALL_DIR"/{agent/subagents,command,tool,plugin,context/{core,project}}
+ # Create base directory only - subdirectories created on-demand when files are installed
+ mkdir -p "$INSTALL_DIR"
# Check for collisions
local collisions=()
@@ -816,9 +833,9 @@ trap 'cleanup_and_exit 1' INT TERM
main() {
# Parse command line arguments
case "${1:-}" in
- core|--core)
+ essential|--essential)
INSTALL_MODE="profile"
- PROFILE="core"
+ PROFILE="essential"
NON_INTERACTIVE=true
;;
developer|--developer)
@@ -826,6 +843,11 @@ main() {
PROFILE="developer"
NON_INTERACTIVE=true
;;
+ business|--business)
+ INSTALL_MODE="profile"
+ PROFILE="business"
+ NON_INTERACTIVE=true
+ ;;
full|--full)
INSTALL_MODE="profile"
PROFILE="full"
@@ -847,17 +869,18 @@ main() {
echo "Usage: $0 [OPTIONS]"
echo ""
echo "Options:"
- echo " core, --core Install core profile"
- echo " developer, --developer Install developer profile"
- echo " full, --full Install full profile"
- echo " advanced, --advanced Install advanced profile"
+ echo " essential, --essential Install essential profile (minimal)"
+ echo " developer, --developer Install developer profile (code-focused)"
+ echo " business, --business Install business profile (content-focused)"
+ echo " full, --full Install full profile (everything except system-builder)"
+ echo " advanced, --advanced Install advanced profile (complete system)"
echo " list, --list List all available components"
echo " help, --help, -h Show this help message"
echo ""
echo "Examples:"
- echo " $0 core"
+ echo " $0 essential"
echo " $0 --developer"
- echo " curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh | bash -s core"
+ echo " curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh | bash -s essential"
echo ""
echo "Without options, runs in interactive mode"
exit 0
diff --git a/registry.json b/registry.json
index 3d080a7..5b634cd 100644
--- a/registry.json
+++ b/registry.json
@@ -1,22 +1,15 @@
{
"version": "1.0.0",
"repository": "https://github.com/darrenhinde/opencode-agents",
+ "categories": {
+ "essential": "Minimal components for basic functionality",
+ "standard": "Standard components for typical use",
+ "extended": "Extended components for advanced features",
+ "specialized": "Specialized components for specific domains",
+ "meta": "Meta-level components for system generation"
+ },
"components": {
"agents": [
- {
- "id": "task-manager",
- "name": "Task Manager",
- "type": "agent",
- "path": ".opencode/agent/task-manager.md",
- "description": "Breaks down complex features into small, verifiable subtasks",
- "tags": [
- "planning",
- "organization",
- "task-management"
- ],
- "dependencies": [],
- "category": "core"
- },
{
"id": "codebase-agent",
"name": "Codebase Agent",
@@ -28,38 +21,32 @@
"architecture",
"patterns"
],
- "dependencies": [],
- "category": "core"
+ "dependencies": [
+ "subagent:task-manager",
+ "subagent:documentation",
+ "subagent:coder-agent",
+ "subagent:tester",
+ "subagent:reviewer",
+ "subagent:build-agent"
+ ],
+ "category": "standard"
},
{
- "id": "image-specialist",
- "name": "Image Specialist",
+ "id": "openagent",
+ "name": "OpenAgent",
"type": "agent",
- "path": ".opencode/agent/image-specialist.md",
- "description": "Generates and edits images using Gemini AI",
+ "path": ".opencode/agent/openagent.md",
+ "description": "Universal agent for answering queries, executing tasks, and coordinating workflows across any domain",
"tags": [
- "images",
- "ai",
- "generation"
+ "universal",
+ "flexible",
+ "coordination"
],
"dependencies": [
- "tool:gemini"
+ "subagent:task-manager",
+ "subagent:documentation"
],
- "category": "extended"
- },
- {
- "id": "workflow-orchestrator",
- "name": "Workflow Orchestrator",
- "type": "agent",
- "path": ".opencode/agent/workflow-orchestrator.md",
- "description": "Orchestrates complex multi-agent workflows",
- "tags": [
- "orchestration",
- "workflow",
- "automation"
- ],
- "dependencies": [],
- "category": "extended"
+ "category": "essential"
},
{
"id": "system-builder",
@@ -80,15 +67,45 @@
"subagent:workflow-designer",
"subagent:command-creator"
],
- "category": "advanced"
+ "category": "meta"
}
],
"subagents": [
{
- "id": "reviewer",
- "name": "Code Reviewer",
+ "id": "task-manager",
+ "name": "Task Manager",
"type": "subagent",
- "path": ".opencode/agent/subagents/reviewer.md",
+ "path": ".opencode/agent/subagents/core/task-manager.md",
+ "description": "Breaks down complex features into small, verifiable subtasks",
+ "tags": [
+ "planning",
+ "organization",
+ "task-management"
+ ],
+ "dependencies": [],
+ "category": "essential"
+ },
+ {
+ "id": "image-specialist",
+ "name": "Image Specialist",
+ "type": "subagent",
+ "path": ".opencode/agent/subagents/utils/image-specialist.md",
+ "description": "Generates and edits images using Gemini AI",
+ "tags": [
+ "images",
+ "ai",
+ "generation"
+ ],
+ "dependencies": [
+ "tool:gemini"
+ ],
+ "category": "utils"
+ },
+ {
+ "id": "reviewer",
+ "name": "Reviewer",
+ "type": "subagent",
+ "path": ".opencode/agent/subagents/code/reviewer.md",
"description": "Performs code review with security and quality checks",
"tags": [
"review",
@@ -96,13 +113,13 @@
"quality"
],
"dependencies": [],
- "category": "core"
+ "category": "standard"
},
{
"id": "tester",
- "name": "Test Writer",
+ "name": "Tester",
"type": "subagent",
- "path": ".opencode/agent/subagents/tester.md",
+ "path": ".opencode/agent/subagents/code/tester.md",
"description": "Writes unit and integration tests",
"tags": [
"testing",
@@ -110,13 +127,13 @@
"quality"
],
"dependencies": [],
- "category": "core"
+ "category": "standard"
},
{
"id": "documentation",
"name": "Documentation Writer",
"type": "subagent",
- "path": ".opencode/agent/subagents/documentation.md",
+ "path": ".opencode/agent/subagents/core/documentation.md",
"description": "Creates and updates documentation",
"tags": [
"docs",
@@ -124,13 +141,13 @@
"writing"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
},
{
"id": "coder-agent",
"name": "Coder Agent",
"type": "subagent",
- "path": ".opencode/agent/subagents/coder-agent.md",
+ "path": ".opencode/agent/subagents/code/coder-agent.md",
"description": "Executes coding subtasks in sequence",
"tags": [
"coding",
@@ -138,13 +155,13 @@
"execution"
],
"dependencies": [],
- "category": "core"
+ "category": "standard"
},
{
"id": "build-agent",
"name": "Build Agent",
"type": "subagent",
- "path": ".opencode/agent/subagents/build-agent.md",
+ "path": ".opencode/agent/subagents/code/build-agent.md",
"description": "Type checks and validates builds",
"tags": [
"build",
@@ -152,13 +169,13 @@
"type-checking"
],
"dependencies": [],
- "category": "core"
+ "category": "standard"
},
{
"id": "codebase-pattern-analyst",
"name": "Codebase Pattern Analyst",
"type": "subagent",
- "path": ".opencode/agent/subagents/codebase-pattern-analyst.md",
+ "path": ".opencode/agent/subagents/code/codebase-pattern-analyst.md",
"description": "Analyzes and implements codebase patterns",
"tags": [
"patterns",
@@ -166,13 +183,13 @@
"architecture"
],
"dependencies": [],
- "category": "extended"
+ "category": "specialized"
},
{
"id": "domain-analyzer",
"name": "Domain Analyzer",
"type": "subagent",
- "path": ".opencode/agent/subagents/domain-analyzer.md",
+ "path": ".opencode/agent/subagents/system-builder/domain-analyzer.md",
"description": "Analyzes user domains and recommends agent architectures",
"tags": [
"analysis",
@@ -180,13 +197,13 @@
"architecture"
],
"dependencies": [],
- "category": "advanced"
+ "category": "meta"
},
{
"id": "agent-generator",
"name": "Agent Generator",
"type": "subagent",
- "path": ".opencode/agent/subagents/agent-generator.md",
+ "path": ".opencode/agent/subagents/system-builder/agent-generator.md",
"description": "Generates XML-optimized agent files following research-backed patterns",
"tags": [
"generation",
@@ -194,13 +211,13 @@
"agents"
],
"dependencies": [],
- "category": "advanced"
+ "category": "meta"
},
{
"id": "context-organizer",
"name": "Context Organizer",
"type": "subagent",
- "path": ".opencode/agent/subagents/context-organizer.md",
+ "path": ".opencode/agent/subagents/system-builder/context-organizer.md",
"description": "Organizes and generates modular context files",
"tags": [
"context",
@@ -208,13 +225,13 @@
"knowledge-management"
],
"dependencies": [],
- "category": "advanced"
+ "category": "meta"
},
{
"id": "workflow-designer",
"name": "Workflow Designer",
"type": "subagent",
- "path": ".opencode/agent/subagents/workflow-designer.md",
+ "path": ".opencode/agent/subagents/system-builder/workflow-designer.md",
"description": "Designs complete workflow definitions with context dependencies",
"tags": [
"workflows",
@@ -222,13 +239,13 @@
"orchestration"
],
"dependencies": [],
- "category": "advanced"
+ "category": "meta"
},
{
"id": "command-creator",
"name": "Command Creator",
"type": "subagent",
- "path": ".opencode/agent/subagents/command-creator.md",
+ "path": ".opencode/agent/subagents/system-builder/command-creator.md",
"description": "Creates custom slash commands with clear syntax and examples",
"tags": [
"commands",
@@ -236,7 +253,7 @@
"cli"
],
"dependencies": [],
- "category": "advanced"
+ "category": "meta"
}
],
"commands": [
@@ -252,7 +269,7 @@
"validation"
],
"dependencies": [],
- "category": "core"
+ "category": "standard"
},
{
"id": "commit",
@@ -266,7 +283,7 @@
"version-control"
],
"dependencies": [],
- "category": "core"
+ "category": "standard"
},
{
"id": "context",
@@ -280,7 +297,7 @@
"management"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
},
{
"id": "clean",
@@ -294,7 +311,7 @@
"build"
],
"dependencies": [],
- "category": "extended"
+ "category": "standard"
},
{
"id": "optimize",
@@ -308,7 +325,7 @@
"build"
],
"dependencies": [],
- "category": "extended"
+ "category": "standard"
},
{
"id": "prompt-enhancer",
@@ -322,7 +339,7 @@
"enhancement"
],
"dependencies": [],
- "category": "extended"
+ "category": "standard"
},
{
"id": "worktrees",
@@ -336,7 +353,7 @@
"workflow"
],
"dependencies": [],
- "category": "advanced"
+ "category": "specialized"
},
{
"id": "build-context-system",
@@ -353,7 +370,7 @@
"dependencies": [
"agent:system-builder"
],
- "category": "advanced"
+ "category": "meta"
}
],
"tools": [
@@ -371,7 +388,7 @@
"dependencies": [
"tool:env"
],
- "category": "extended"
+ "category": "specialized"
},
{
"id": "env",
@@ -385,7 +402,7 @@
"security"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
}
],
"plugins": [
@@ -403,7 +420,7 @@
"dependencies": [
"tool:env"
],
- "category": "extended"
+ "category": "specialized"
},
{
"id": "notify",
@@ -416,7 +433,7 @@
"alerts"
],
"dependencies": [],
- "category": "extended"
+ "category": "specialized"
}
],
"contexts": [
@@ -432,7 +449,7 @@
"guidelines"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
},
{
"id": "project-context",
@@ -446,7 +463,7 @@
"configuration"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
}
],
"config": [
@@ -462,7 +479,7 @@
"template"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
},
{
"id": "readme",
@@ -476,21 +493,21 @@
"guide"
],
"dependencies": [],
- "category": "core"
+ "category": "essential"
}
]
},
"profiles": {
- "core": {
- "name": "Core",
- "description": "Minimal essentials - main agent with basic subagents and commands",
+ "essential": {
+ "name": "Essential (Minimal)",
+ "description": "Minimal starter kit - universal agent with core subagents. Great for learning the system or lightweight tasks. Upgrade to Developer or Business for full features.",
"components": [
- "agent:task-manager",
- "agent:codebase-agent",
- "subagent:tester",
+ "agent:openagent",
+ "subagent:task-manager",
"subagent:documentation",
- "subagent:coder-agent",
- "command:commit",
+ "command:context",
+ "command:clean",
+ "tool:env",
"context:essential-patterns",
"context:project-context",
"config:env-example"
@@ -498,26 +515,45 @@
},
"developer": {
"name": "Developer",
- "description": "Recommended for daily development - includes testing, review, quality tools, and AI image generation",
+ "description": "Complete software development environment with code generation, testing, review, and build tools. Recommended for most developers.",
+ "badge": "RECOMMENDED",
"components": [
- "agent:task-manager",
+ "agent:openagent",
"agent:codebase-agent",
- "agent:image-specialist",
- "agent:workflow-orchestrator",
- "subagent:reviewer",
- "subagent:tester",
+ "subagent:task-manager",
"subagent:documentation",
"subagent:coder-agent",
+ "subagent:reviewer",
+ "subagent:tester",
"subagent:build-agent",
"subagent:codebase-pattern-analyst",
- "command:test",
"command:commit",
+ "command:test",
"command:context",
"command:clean",
"command:optimize",
+ "tool:env",
+ "context:essential-patterns",
+ "context:project-context",
+ "config:env-example",
+ "config:readme"
+ ]
+ },
+ "business": {
+ "name": "Business",
+ "description": "Business process automation, content creation, and visual workflows. Includes image generation, notifications, and documentation tools.",
+ "components": [
+ "agent:openagent",
+ "subagent:task-manager",
+ "subagent:documentation",
+ "subagent:image-specialist",
+ "command:context",
+ "command:clean",
"command:prompt-enhancer",
"tool:env",
"tool:gemini",
+ "plugin:notify",
+ "plugin:telegram-notify",
"context:essential-patterns",
"context:project-context",
"config:env-example",
@@ -526,18 +562,18 @@
},
"full": {
"name": "Full",
- "description": "Everything included - all agents, tools, and plugins for maximum functionality",
+ "description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.",
"components": [
- "agent:task-manager",
+ "agent:openagent",
"agent:codebase-agent",
- "agent:image-specialist",
- "agent:workflow-orchestrator",
- "subagent:reviewer",
- "subagent:tester",
+ "subagent:task-manager",
"subagent:documentation",
"subagent:coder-agent",
+ "subagent:reviewer",
+ "subagent:tester",
"subagent:build-agent",
"subagent:codebase-pattern-analyst",
+ "subagent:image-specialist",
"command:test",
"command:commit",
"command:context",
@@ -556,20 +592,20 @@
]
},
"advanced": {
- "name": "Advanced",
- "description": "Full installation plus system builder and experimental features",
+ "name": "Advanced (Meta-Level)",
+ "description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.",
"components": [
- "agent:task-manager",
+ "agent:openagent",
"agent:codebase-agent",
- "agent:image-specialist",
- "agent:workflow-orchestrator",
"agent:system-builder",
- "subagent:reviewer",
- "subagent:tester",
+ "subagent:task-manager",
"subagent:documentation",
"subagent:coder-agent",
+ "subagent:reviewer",
+ "subagent:tester",
"subagent:build-agent",
"subagent:codebase-pattern-analyst",
+ "subagent:image-specialist",
"subagent:domain-analyzer",
"subagent:agent-generator",
"subagent:context-organizer",
@@ -585,6 +621,8 @@
"command:build-context-system",
"tool:env",
"tool:gemini",
+ "plugin:notify",
+ "plugin:telegram-notify",
"context:essential-patterns",
"context:project-context",
"config:env-example",
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..2d240f1
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,49 @@
+# Scripts
+
+This directory contains utility scripts for the OpenCode Agents system.
+
+## Available Scripts
+
+### Component Management
+
+- `register-component.sh` - Register a new component in the registry
+- `validate-component.sh` - Validate component structure and metadata
+
+### Session Management
+
+- `cleanup-stale-sessions.sh` - Remove stale agent sessions older than 24 hours
+
+### Testing
+
+See `tests/` subdirectory for test scripts.
+
+## Session Cleanup
+
+Agent instances create temporary context files in `.tmp/sessions/{session-id}/` for subagent delegation. These sessions are automatically cleaned up, but you can manually remove stale sessions:
+
+```bash
+# Clean up sessions older than 24 hours
+./scripts/cleanup-stale-sessions.sh
+
+# Or manually delete all sessions
+rm -rf .tmp/sessions/
+```
+
+Sessions are safe to delete anytime - they only contain temporary context files for agent coordination.
+
+## Usage Examples
+
+### Register a Component
+```bash
+./scripts/register-component.sh path/to/component
+```
+
+### Validate a Component
+```bash
+./scripts/validate-component.sh path/to/component
+```
+
+### Clean Stale Sessions
+```bash
+./scripts/cleanup-stale-sessions.sh
+```
diff --git a/scripts/cleanup-stale-sessions.sh b/scripts/cleanup-stale-sessions.sh
new file mode 100755
index 0000000..811fbc4
--- /dev/null
+++ b/scripts/cleanup-stale-sessions.sh
@@ -0,0 +1,76 @@
+#!/bin/bash
+# Cleanup stale agent sessions older than 24 hours
+
+set -e
+
+SESSIONS_DIR=".tmp/sessions"
+STALE_HOURS=24
+
+# Check if sessions directory exists
+if [ ! -d "$SESSIONS_DIR" ]; then
+ echo "No sessions directory found at $SESSIONS_DIR"
+ exit 0
+fi
+
+echo "Checking for stale sessions (older than ${STALE_HOURS} hours)..."
+
+# Find all session directories
+session_count=0
+stale_count=0
+
+for session_dir in "$SESSIONS_DIR"/*; do
+ if [ ! -d "$session_dir" ]; then
+ continue
+ fi
+
+ session_count=$((session_count + 1))
+ session_id=$(basename "$session_dir")
+ manifest="$session_dir/.manifest.json"
+
+ # Check if manifest exists
+ if [ ! -f "$manifest" ]; then
+ echo "⚠️ Session $session_id has no manifest - removing"
+ rm -rf "$session_dir"
+ stale_count=$((stale_count + 1))
+ continue
+ fi
+
+ # Get last activity timestamp
+ last_activity=$(jq -r '.last_activity // .created_at' "$manifest" 2>/dev/null || echo "")
+
+ if [ -z "$last_activity" ]; then
+ echo "⚠️ Session $session_id has invalid manifest - removing"
+ rm -rf "$session_dir"
+ stale_count=$((stale_count + 1))
+ continue
+ fi
+
+ # Calculate age in hours
+ last_activity_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$last_activity" "+%s" 2>/dev/null || echo "0")
+ current_epoch=$(date "+%s")
+ age_hours=$(( (current_epoch - last_activity_epoch) / 3600 ))
+
+ if [ "$age_hours" -gt "$STALE_HOURS" ]; then
+ echo "🗑️ Removing stale session $session_id (${age_hours}h old)"
+ rm -rf "$session_dir"
+ stale_count=$((stale_count + 1))
+ else
+ echo "✅ Session $session_id is active (${age_hours}h old)"
+ fi
+done
+
+echo ""
+echo "Summary:"
+echo " Total sessions: $session_count"
+echo " Stale sessions removed: $stale_count"
+echo " Active sessions: $((session_count - stale_count))"
+
+# Remove sessions directory if empty
+if [ -d "$SESSIONS_DIR" ] && [ -z "$(ls -A "$SESSIONS_DIR")" ]; then
+ echo ""
+ echo "Sessions directory is empty - removing"
+ rmdir "$SESSIONS_DIR"
+fi
+
+echo ""
+echo "✨ Cleanup complete!"