diff --git a/.opencode/command/validate-repo.md b/.opencode/command/validate-repo.md new file mode 100644 index 0000000..959f887 --- /dev/null +++ b/.opencode/command/validate-repo.md @@ -0,0 +1,347 @@ +# Validate Repository + +Comprehensive validation command that checks the entire OpenAgents repository for consistency between CLI, documentation, registry, and components. + +## Usage + +```bash +/validate-repo +``` + +## What It Checks + +This command performs a comprehensive validation of: + +1. **Registry Integrity** + - JSON syntax validation + - Component definitions completeness + - File path references + - Dependency declarations + +2. **Component Existence** + - All agents exist at specified paths + - All subagents exist at specified paths + - All commands exist at specified paths + - All tools exist at specified paths + - All plugins exist at specified paths + - All context files exist at specified paths + - All config files exist at specified paths + +3. **Profile Consistency** + - Component counts match documentation + - Profile descriptions are accurate + - Dependencies are satisfied + - No duplicate components + +4. **Documentation Accuracy** + - README component counts match registry + - OpenAgent documentation references are valid + - Context file references are correct + - Installation guide is up to date + +5. **Context File Structure** + - All referenced context files exist + - Context file organization is correct + - No orphaned context files + +6. **Cross-References** + - Agent dependencies exist + - Subagent references are valid + - Command references are valid + - Tool dependencies are satisfied + +## Output + +The command generates a detailed report showing: +- ✅ What's correct and validated +- ⚠️ Warnings for potential issues +- ❌ Errors that need fixing +- 📊 Summary statistics + +## Instructions + +You are a validation specialist. Your task is to comprehensively validate the OpenAgents repository for consistency and correctness. + +### Step 1: Validate Registry JSON + +1. Read and parse `registry.json` +2. Validate JSON syntax +3. Check schema structure: + - `version` field exists + - `repository` field exists + - `categories` object exists + - `components` object exists with all types + - `profiles` object exists + - `metadata` object exists + +### Step 2: Validate Component Definitions + +For each component type (agents, subagents, commands, tools, plugins, contexts, config): + +1. Check required fields: + - `id` (unique) + - `name` + - `type` + - `path` + - `description` + - `tags` (array) + - `dependencies` (array) + - `category` + +2. Verify file exists at `path` +3. Check for duplicate IDs +4. Validate category is in defined categories + +### Step 3: Validate Profiles + +For each profile (essential, developer, business, full, advanced): + +1. Count components in profile +2. Verify all component references exist in components section +3. Check dependencies are satisfied +4. Validate no duplicate components + +### Step 4: Cross-Reference with Documentation + +1. **README.md**: + - Extract component counts from profile descriptions + - Compare with actual registry counts + - Check profile descriptions match registry descriptions + +2. **docs/agents/openagent.md**: + - Verify delegation criteria mentioned + - Check context file references + - Validate workflow descriptions + +3. **docs/getting-started/installation.md**: + - Check profile descriptions + - Verify installation commands + +### Step 5: Validate Context File Structure + +1. List all files in `.opencode/context/` +2. Check against registry context entries +3. Identify orphaned files (exist but not in registry) +4. Identify missing files (in registry but don't exist) +5. Validate structure: + - `core/standards/` files + - `core/workflows/` files + - `core/system/` files + - `project/` files + +### Step 6: Validate Dependencies + +For each component with dependencies: + +1. Parse dependency string (format: `type:id`) +2. Verify referenced component exists +3. Check for circular dependencies +4. Validate dependency chain completeness + +### Step 7: Generate Report + +Create a comprehensive report with sections: + +#### ✅ Validated Successfully +- Registry JSON syntax +- Component file existence +- Profile integrity +- Documentation accuracy +- Context file structure +- Dependency chains + +#### ⚠️ Warnings +- Orphaned files (exist but not referenced) +- Unused components (defined but not in any profile) +- Missing descriptions or tags +- Outdated metadata dates + +#### ❌ Errors +- Missing files +- Broken dependencies +- Invalid JSON +- Component count mismatches +- Broken documentation references +- Duplicate component IDs + +#### 📊 Statistics +- Total components: X +- Total profiles: X +- Total context files: X +- Components per profile breakdown +- File coverage percentage + +### Step 8: Provide Recommendations + +Based on findings, suggest: +- Files to create +- Registry entries to add/remove +- Documentation to update +- Dependencies to fix + +## Example Report Format + +```markdown +# OpenAgents Repository Validation Report + +Generated: 2025-11-19 14:30:00 + +## Summary + +✅ 95% validation passed +⚠️ 3 warnings found +❌ 2 errors found + +--- + +## ✅ Validated Successfully + +### Registry Integrity +✅ JSON syntax valid +✅ All required fields present +✅ Schema structure correct + +### Component Existence (45/47 files found) +✅ Agents: 3/3 files exist +✅ Subagents: 15/15 files exist +✅ Commands: 8/8 files exist +✅ Tools: 2/2 files exist +✅ Plugins: 2/2 files exist +✅ Contexts: 13/15 files exist +✅ Config: 2/2 files exist + +### Profile Consistency +✅ Essential: 9 components (matches README) +✅ Developer: 29 components (matches README) +✅ Business: 15 components (matches README) +✅ Full: 35 components (matches README) +✅ Advanced: 42 components (matches README) + +### Documentation Accuracy +✅ README component counts match registry +✅ OpenAgent documentation up to date +✅ Installation guide accurate + +--- + +## ⚠️ Warnings (3) + +1. **Orphaned Context File** + - File: `.opencode/context/legacy/old-patterns.md` + - Issue: Exists but not referenced in registry + - Recommendation: Add to registry or remove file + +2. **Unused Component** + - Component: `workflow-orchestrator` (agent) + - Issue: Defined in registry but not in any profile + - Recommendation: Add to a profile or mark as deprecated + +3. **Outdated Metadata** + - Field: `metadata.lastUpdated` + - Current: 2025-11-15 + - Recommendation: Update to current date + +--- + +## ❌ Errors (2) + +1. **Missing Context File** + - Component: `context:advanced-patterns` + - Expected path: `.opencode/context/core/advanced-patterns.md` + - Referenced in: developer, full, advanced profiles + - Action: Create file or remove from registry + +2. **Broken Dependency** + - Component: `agent:codebase-agent` + - Dependency: `subagent:pattern-matcher` + - Issue: Dependency not found in registry + - Action: Add missing subagent or fix dependency reference + +--- + +## 📊 Statistics + +### Component Distribution +- Agents: 3 +- Subagents: 15 +- Commands: 8 +- Tools: 2 +- Plugins: 2 +- Contexts: 15 +- Config: 2 +- **Total: 47 components** + +### Profile Breakdown +- Essential: 9 components (19%) +- Developer: 29 components (62%) +- Business: 15 components (32%) +- Full: 35 components (74%) +- Advanced: 42 components (89%) + +### File Coverage +- Total files defined: 47 +- Files found: 45 (96%) +- Files missing: 2 (4%) +- Orphaned files: 1 + +### Dependency Health +- Total dependencies: 23 +- Valid dependencies: 22 (96%) +- Broken dependencies: 1 (4%) +- Circular dependencies: 0 + +--- + +## 🔧 Recommended Actions + +### High Priority (Errors) +1. Create missing file: `.opencode/context/core/advanced-patterns.md` +2. Fix broken dependency in `codebase-agent` + +### Medium Priority (Warnings) +1. Remove orphaned file or add to registry +2. Add `workflow-orchestrator` to a profile or deprecate +3. Update metadata.lastUpdated to 2025-11-19 + +### Low Priority (Improvements) +1. Add more tags to components for better searchability +2. Consider adding descriptions to all context files +3. Document component categories in README + +--- + +## Next Steps + +1. Review and fix all ❌ errors +2. Address ⚠️ warnings as needed +3. Re-run validation to confirm fixes +4. Update documentation if needed + +--- + +**Validation Complete** ✓ +``` + +## Implementation Notes + +The command should: +- Use bash/python for file system operations +- Parse JSON with proper error handling +- Generate markdown report +- Be non-destructive (read-only validation) +- Provide actionable recommendations +- Support verbose mode for detailed output + +## Error Handling + +- Gracefully handle missing files +- Continue validation even if errors found +- Collect all issues before reporting +- Provide clear error messages with context + +## Performance + +- Should complete in < 30 seconds +- Cache file reads where possible +- Parallel validation where safe +- Progress indicators for long operations diff --git a/.opencode/context/core/essential-patterns.md b/.opencode/context/core/essential-patterns.md new file mode 100644 index 0000000..7e828df --- /dev/null +++ b/.opencode/context/core/essential-patterns.md @@ -0,0 +1,208 @@ +# Essential Patterns - Core Development Guidelines + +## Quick Reference + +**Core Philosophy**: Modular, Functional, Maintainable + +**Critical Patterns**: Error Handling, Validation, Security, Logging, Pure Functions + +**ALWAYS**: Handle errors gracefully, validate input, use env vars for secrets, write pure functions + +**NEVER**: Expose sensitive info, hardcode credentials, skip input validation, mutate state + +**Language-agnostic**: Apply to all programming languages + +--- + +## Overview + +This file provides essential development patterns that apply across all programming languages. For detailed standards, see: +- `standards/code.md` - Modular, functional code patterns +- `standards/patterns.md` - Language-agnostic patterns +- `standards/tests.md` - Testing standards +- `standards/docs.md` - Documentation standards +- `standards/analysis.md` - Analysis framework + +--- + +## Core Philosophy + +**Modular**: Everything is a component - small, focused, reusable +**Functional**: Pure functions, immutability, composition over inheritance +**Maintainable**: Self-documenting, testable, predictable + +--- + +## Critical Patterns + +### 1. Pure Functions + +**ALWAYS** write pure functions: +- Same input = same output +- No side effects +- No mutation of external state +- Predictable and testable + +### 2. Error Handling + +**ALWAYS** handle errors gracefully: +- Catch specific errors, not generic ones +- Log errors with context +- Return meaningful error messages +- Don't expose internal implementation details +- Use language-specific error handling mechanisms (try/catch, Result, error returns) + +### 3. Input Validation + +**ALWAYS** validate input data: +- Check for null/nil/None values +- Validate data types +- Validate data ranges and constraints +- Sanitize user input +- Return clear validation error messages + +### 4. Security + +**NEVER** expose sensitive information: +- Don't log passwords, tokens, or API keys +- Use environment variables for secrets +- Sanitize all user input +- Use parameterized queries (prevent SQL injection) +- Validate and escape output (prevent XSS) + +### 5. Logging + +**USE** consistent logging levels: +- **Debug**: Detailed information for debugging (development only) +- **Info**: Important events and milestones +- **Warning**: Potential issues that don't stop execution +- **Error**: Failures and exceptions + +--- + +## Code Structure Patterns + +### Modular Design +- Single responsibility per module +- Clear interfaces (explicit inputs/outputs) +- Independent and composable +- < 100 lines per component (ideally < 50) + +### Functional Approach +- **Pure functions**: Same input = same output, no side effects +- **Immutability**: Create new data, don't modify existing +- **Composition**: Build complex from simple functions +- **Declarative**: Describe what, not how + +### Component Structure +``` +component/ +├── index.js # Public interface +├── core.js # Core logic (pure functions) +├── utils.js # Helpers +└── tests/ # Tests +``` + +--- + +## Anti-Patterns to Avoid + +**Code Smells**: +- ❌ Mutation and side effects +- ❌ Deep nesting (> 3 levels) +- ❌ God modules (> 200 lines) +- ❌ Global state +- ❌ Large functions (> 50 lines) +- ❌ Hardcoded values +- ❌ Tight coupling + +**Security Issues**: +- ❌ Hardcoded credentials +- ❌ Exposed sensitive data in logs +- ❌ Unvalidated user input +- ❌ SQL injection vulnerabilities +- ❌ XSS vulnerabilities + +--- + +## Testing Patterns + +**ALWAYS** write tests: +- Unit tests for pure functions +- Integration tests for components +- Test edge cases and error conditions +- Aim for > 80% coverage +- Use descriptive test names + +**Test Structure**: +``` +describe('Component', () => { + it('should handle valid input', () => { + // Arrange + const input = validData; + + // Act + const result = component(input); + + // Assert + expect(result).toBe(expected); + }); + + it('should handle invalid input', () => { + // Test error cases + }); +}); +``` + +--- + +## Documentation Patterns + +**ALWAYS** document: +- Public APIs and interfaces +- Complex logic and algorithms +- Non-obvious decisions +- Usage examples + +**Use clear, concise language**: +- Explain WHY, not just WHAT +- Include examples +- Keep it up to date +- Use consistent formatting + +--- + +## Language-Specific Implementations + +These patterns are language-agnostic. For language-specific implementations: + +**TypeScript/JavaScript**: See project context for Next.js, React, Node.js patterns +**Python**: See project context for FastAPI, Django patterns +**Go**: See project context for Go-specific patterns +**Rust**: See project context for Rust-specific patterns + +--- + +## Quick Checklist + +Before committing code, verify: +- ✅ Pure functions (no side effects) +- ✅ Input validation +- ✅ Error handling +- ✅ No hardcoded secrets +- ✅ Tests written and passing +- ✅ Documentation updated +- ✅ No security vulnerabilities +- ✅ Code is modular and maintainable + +--- + +## Additional Resources + +For more detailed guidelines, see: +- `standards/code.md` - Comprehensive code standards +- `standards/patterns.md` - Detailed pattern catalog +- `standards/tests.md` - Testing best practices +- `standards/docs.md` - Documentation guidelines +- `standards/analysis.md` - Code analysis framework +- `workflows/review.md` - Code review process diff --git a/README.md b/README.md index 239825b..09110e3 100644 --- a/README.md +++ b/README.md @@ -231,6 +231,7 @@ openagent (universal coordinator) - **/context** - Context management - **/prompt-enchancer** - Improve your prompts - **/worktrees** - Git worktree management +- **/validate-repo** - Validate repository consistency ### 📚 Context Files - `core/essential-patterns.md` - Universal coding patterns @@ -423,12 +424,13 @@ Minimal starter kit - universal agent with core subagents. - **Config**: env-example - **Best for**: Learning the system, lightweight tasks, minimal setup -### 💼 Developer (Recommended - 19 components) +### 💼 Developer (Recommended - 30 components) Complete software development environment with code generation, testing, review, and build tools. - Everything in Essential, plus: - **Agents**: codebase-agent - **Subagents**: coder-agent, reviewer, tester, build-agent, codebase-pattern-analyst -- **Commands**: commit, test, optimize +- **Commands**: commit, test, optimize, validate-repo +- **Context**: All standards and workflow files (code, patterns, tests, docs, analysis, delegation, sessions, task-breakdown, review, context-guide) - **Config**: readme - **Best for**: Most developers, daily use, full-featured development @@ -443,13 +445,13 @@ Business process automation, content creation, and visual workflows. - **Config**: env-example, readme - **Best for**: Business automation, content creation, non-developers -### 📦 Full (25 components) +### 📦 Full (36 components) Everything included - all agents, subagents, tools, and plugins. - Everything in Developer and Business combined, plus: -- **Commands**: worktrees (git worktree management) +- **Commands**: worktrees (git worktree management), validate-repo - **Best for**: Power users, exploring all features -### 🚀 Advanced (32 components) +### 🚀 Advanced (43 components) Full installation plus **System Builder** for creating custom AI architectures. - Everything in Full, plus: - **System Builder**: Interactive AI system generator diff --git a/docs/agents/openagent.md b/docs/agents/openagent.md index 3616066..9113928 100644 --- a/docs/agents/openagent.md +++ b/docs/agents/openagent.md @@ -26,7 +26,7 @@ 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 +- ✅ **Coordinates workflows** - Handles most tasks directly, delegates to specialists when needed - ✅ **Preserves context** - Remembers information across multiple steps - ✅ **Keeps you in control** - Always asks for approval before taking action @@ -34,7 +34,7 @@ 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 +- Executes the plan (directly or via delegation) - Confirms everything is done right --- @@ -64,6 +64,18 @@ graph LR **For Questions**: You ask → You get an answer **For Tasks**: You ask → See plan → Approve → Watch it happen → Confirm done +### Universal Agent Philosophy + +OpenAgent is a **universal agent** - it handles most tasks directly: + +**Capabilities**: Write code, docs, tests, reviews, analysis, debugging, research, bash operations, file operations + +**Default**: Execute directly, fetch context files as needed (lazy), keep it simple, don't over-delegate + +**Delegate only when**: 4+ files, specialized expertise needed, thorough multi-component review, complex dependencies, or user requests breakdown + +This means OpenAgent is your go-to agent for almost everything. It only calls in specialists when truly necessary. + --- ## The Two Paths @@ -234,7 +246,7 @@ graph TD --- -### Stage 2: Approve ⚠️ (MANDATORY for tasks) +### Stage 2: Approve ⚠️ (MANDATORY - CRITICAL RULE) ```mermaid graph TD @@ -262,6 +274,8 @@ graph TD **What happens**: OpenAgent creates a plan and shows it to you. +**Critical Rule**: OpenAgent **ALWAYS** requests approval before **ANY** execution (bash, write, edit, task delegation). This is absolute and strictly enforced. Read and list operations do not require approval. + **Your experience**: You see something like: ``` ## Proposed Plan @@ -327,7 +341,7 @@ graph TD --- -### Stage 4: Validate ⚠️ (MANDATORY for tasks) +### Stage 4: Validate ⚠️ (MANDATORY - CRITICAL RULE) ```mermaid graph TD @@ -379,6 +393,11 @@ graph TD **What happens**: OpenAgent checks the quality of the work, runs tests if applicable, and ensures everything works correctly. +**Critical Rules Enforced**: +1. **STOP on failure** - Immediately stops execution when tests fail or errors occur +2. **REPORT first** - Always reports issues before proposing fixes +3. **NEVER auto-fix** - Always requests approval before fixing issues + **Your experience when validation passes**: You see: ``` ✅ Validation complete - all checks passed. @@ -394,13 +413,13 @@ Would you like me to run any additional checks or review the work before I summa #### Special Case: Test Failures or Issues Found -If OpenAgent runs tests or validation and finds issues, it follows a **strict protocol**: +If OpenAgent runs tests or validation and finds issues, it follows a **strict protocol** (Critical Rule): **What happens**: -1. ⛔ **STOPS** execution immediately +1. ⛔ **STOPS** execution immediately (no auto-fix) 2. 📋 **REPORTS** all issues/failures clearly 3. 📝 **PROPOSES** a fix plan with specific steps -4. ⚠️ **REQUESTS APPROVAL** before fixing (mandatory) +4. ⚠️ **REQUESTS APPROVAL** before fixing (absolute requirement) 5. ✅ **PROCEEDS** only after you approve 6. 🔄 **RE-VALIDATES** after fixes are applied @@ -420,7 +439,7 @@ If OpenAgent runs tests or validation and finds issues, it follows a **strict pr **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. +**Critical**: OpenAgent will **NEVER** auto-fix issues without your explicit approval. This is an absolute rule with strict enforcement. After fixes are applied, validation runs again to ensure everything passes. --- @@ -470,7 +489,7 @@ Created README.md with project documentation. --- -### Stage 6: Confirm Completion ⚠️ (MANDATORY for tasks) +### Stage 6: Confirm Completion ⚠️ (MANDATORY - CRITICAL RULE) ```mermaid graph TD @@ -508,6 +527,8 @@ graph TD **What happens**: OpenAgent asks if you're satisfied and if temporary files should be cleaned up. +**Critical Rule**: OpenAgent **ALWAYS** confirms before deleting session files or cleanup operations. This is absolute and strictly enforced. + **Your experience**: You see: ``` Is this complete and satisfactory? @@ -584,11 +605,11 @@ sequenceDiagram ### Key Features -**Lazy Initialization**: Sessions are only created when actually needed (not for simple tasks). +**Lazy Initialization**: Sessions are only created when actually needed (not for simple tasks). OpenAgent follows a "lazy" philosophy - only creates sessions/files when truly necessary. **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. +**Safe Cleanup**: OpenAgent only deletes files it created, and only after you approve (Critical Rule). **Concurrent Safety**: Multiple users can work simultaneously without interfering with each other. @@ -677,7 +698,22 @@ The manifest is like an **index** that tracks all context files: ## When OpenAgent Delegates -OpenAgent knows when to do work itself and when to call in specialists. +OpenAgent is a **universal agent** that handles most tasks directly. It only delegates when truly needed. + +### Execution Philosophy + +**OpenAgent's Capabilities**: Write code, docs, tests, reviews, analysis, debugging, research, bash operations, file operations + +**Default Approach**: Execute directly, fetch context files as needed (lazy loading), keep it simple + +**Delegate Only When**: +- 4+ files to modify/create +- Specialized expertise needed (security, algorithms, architecture, performance) +- Thorough multi-component review required +- Complex dependencies and coordination +- Need fresh perspective or alternative approaches +- Testing scenarios, edge cases, what-if analysis +- User explicitly requests breakdown/delegation ### Decision Tree @@ -689,17 +725,20 @@ graph TD B -->|Task| D{How complex?} - D -->|3+ files OR 60+ min OR complex| E[Delegate to task-manager] + D -->|4+ files OR specialized expertise| 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 -->|Need perspective OR simulation| G[Delegate to general agent] + G --> G1[Fresh eyes, alternatives, testing] - D -->|Simple OR single file OR under 30 min| H[Execute Directly] - H --> H1[OpenAgent handles it] + D -->|Specialized code task| H[Delegate to code specialists] + H --> H1[Testing, review, build] + + D -->|Simple OR 1-3 files OR straightforward| I[Execute Directly] + I --> I1[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 @@ -708,19 +747,19 @@ graph TD style E fill:#6B7C93,stroke:#4A5568,stroke-width:3px,color:#fff style F fill:#6B7C93,stroke:#4A5568,stroke-width:3px,color:#fff style G fill:#6B7C93,stroke:#4A5568,stroke-width:3px,color:#fff - style H fill:#7ED321,stroke:#5FA319,stroke-width:3px,color:#000 + style H fill:#6B7C93,stroke:#4A5568,stroke-width:3px,color:#fff + style I 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** +- ✅ Feature spans **4+ files/modules** - ✅ **Complex dependencies** between components +- ✅ Needs **breakdown into subtasks** - ✅ User **explicitly requests** task breakdown -**Example**: "Build user authentication system" +**Example**: "Build user authentication system with 5+ components" --- @@ -734,8 +773,22 @@ graph TD --- +#### Delegate to @general agent when: +- ✅ Need **fresh perspective** or alternative approaches +- ✅ **Simulation** of scenarios, edge cases, what-if analysis +- ✅ **Brainstorming** different solutions +- ✅ **Complex research** requiring multiple rounds of search + +**Examples**: +- "Review this API design - what could go wrong?" → Fresh perspective +- "Simulate edge cases for this algorithm" → Testing scenarios +- "What are alternative approaches to solve X?" → Brainstorming + +--- + #### Delegate to @code/* when: -- ✅ **Code-specific specialized task** (testing, review, build) +- ✅ **Specialized code task** (testing, review, build) +- ✅ **Thorough review** across multiple components - ✅ Code subagents are **available** in current profile **Examples**: @@ -746,15 +799,16 @@ graph TD --- #### Execute directly when: -- ✅ **Single file** operation -- ✅ **Simple, straightforward** task (<30 min) +- ✅ **1-3 files** to modify/create +- ✅ **Straightforward** task with clear implementation - ✅ **Quick updates/edits** - ✅ User **explicitly asks** openagent to handle it **Examples**: - "Create a README" +- "Fix this bug in auth.ts" +- "Add input validation to this function" - "Update this function to use async/await" -- "Add a comment to this code" --- @@ -956,11 +1010,11 @@ When making follow-up requests, reference previous work: 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 +- 4+ files → Delegate to task-manager +- Specialized expertise needed → Delegate to appropriate specialist +- 1-3 files → Execute directly -**To customize**: Edit the `` section to match your preferences. +**To customize**: Edit the `` section to match your preferences. --- @@ -1090,41 +1144,48 @@ Concise responses, no over-explanation. Gets to the point quickly. Conversational for questions, formal for tasks. Matches the context. ### ⚡ Lazy -Only creates sessions/files when actually needed. No unnecessary overhead. +Only creates sessions/files when actually needed. No unnecessary overhead. Fetches context files on-demand. -### 🔒 Safe -**ALWAYS** requests approval before ANY execution. Confirms before cleanup. +### 🔒 Safe (CRITICAL RULE - Absolute & Strict) +**ALWAYS** requests approval before ANY execution (bash, write, edit, task delegation). Confirms before cleanup. This is an absolute rule with strict enforcement. -### 📋 Report First +### 📋 Report First (CRITICAL RULE - Absolute & Strict) When tests fail or issues are found: -1. **REPORT** the issues -2. **PLAN** the fixes -3. **REQUEST APPROVAL** -4. **FIX** (only after approval) +1. **STOP** immediately (no auto-fix) +2. **REPORT** the issues clearly +3. **PROPOSE** fix plan +4. **REQUEST APPROVAL** (mandatory) +5. **FIX** (only after approval) -**Never auto-fixes** - you're always in control. +**Never auto-fixes** - you're always in control. This is an absolute rule with strict enforcement. + +### 🛡️ Critical Rules Summary +Three critical rules are enforced with absolute priority: +1. **Approval Gate** - Always request approval before execution +2. **Stop on Failure** - Stop immediately on test failures or errors, never auto-fix +3. **Confirm Cleanup** - Always confirm before deleting session files --- ## Summary -OpenAgent is your **intelligent project manager** that: +OpenAgent is your **intelligent universal agent** that: -✅ **Plans before acting** - Shows you the plan and waits for approval +✅ **Plans before acting** - Shows you the plan and waits for approval (Critical Rule) ✅ **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 +✅ **Executes directly** - Handles most tasks itself, delegates only when needed +✅ **Keeps you in control** - Always confirms before cleanup (Critical Rule) +✅ **Handles complexity** - Capable of code, docs, tests, reviews, analysis, debugging +✅ **Reports before fixing** - Never auto-fixes issues without approval (Critical Rule) **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 +4. OpenAgent handles most tasks directly - delegation is the exception, not the rule 5. Clean up sessions when done 6. Customize to fit your workflow -7. Expect reports before fixes when issues are found +7. Expect reports before fixes when issues are found (never auto-fix) **Ready to get started?** Just ask OpenAgent a question or request a task! @@ -1133,32 +1194,48 @@ OpenAgent is your **intelligent project manager** that: ## Configuration OpenAgent is configured in `.opencode/agent/openagent.md`. You can customize: -- Delegation thresholds -- Categories -- Error handling -- Test failure protocol +- Delegation thresholds (when to delegate vs execute directly) +- Execution philosophy (universal agent approach) +- Critical rules enforcement +- Workflow stages +- Context loading behavior - And more! -### Recent Optimizations (Nov 2025) +### Architecture & Design (Nov 2025) OpenAgent has been optimized based on research-backed prompt engineering patterns: -✅ **Critical rules positioned early** - Safety rules now appear in the first 15% of the prompt (10.7% position) -✅ **Minimal nesting complexity** - Flattened XML structure to only 2 levels for maximum clarity -✅ **Modular design** - Session management and context discovery extracted to reference files -✅ **Explicit prioritization** - 3-tier priority system for conflict resolution +✅ **Critical rules positioned early** - Safety rules appear in the first 15% of the prompt with absolute priority +✅ **Minimal nesting complexity** - Flattened XML structure (max 2 levels) for maximum clarity +✅ **Modular design** - Context files loaded on-demand (lazy loading) +✅ **Explicit prioritization** - 3-tier priority system with conflict resolution ✅ **Single source of truth** - Critical rules defined once and referenced throughout +✅ **Universal agent philosophy** - Execute directly first, delegate only when truly needed + +**Key Principles**: +- **Tier 1 (Highest)**: Safety & Approval Gates - Always override other tiers +- **Tier 2**: Core Workflow - Stage progression and delegation routing +- **Tier 3**: Optimization - Lazy initialization, session management, context discovery **Effectiveness improvements are model- and task-specific.** These patterns are validated by Stanford/Anthropic research but actual performance gains vary based on your specific use case. -### Required Context Files +### Static Context Files -OpenAgent requires these context files to function properly: -- `.opencode/context/core/session-management.md` - Session lifecycle and cleanup policies -- `.opencode/context/core/context-discovery.md` - Dynamic context loading and discovery -- `.opencode/context/core/context-management.md` - Overall context management strategy -- `.opencode/context/core/essential-patterns.md` - Core coding patterns and best practices +OpenAgent uses context files from `.opencode/context/core/` on-demand (lazy loading): -These files are automatically loaded when OpenAgent starts. +**Standards** (quality guidelines): +- `standards/code.md` - Modular, functional code patterns +- `standards/docs.md` - Documentation standards +- `standards/tests.md` - Testing standards +- `standards/patterns.md` - Core patterns +- `standards/analysis.md` - Analysis framework + +**Workflows** (process templates): +- `workflows/delegation.md` - Delegation template and process +- `workflows/task-breakdown.md` - Task breakdown methodology +- `workflows/sessions.md` - Session lifecycle management +- `workflows/review.md` - Code review guidelines + +These files are fetched only when needed, keeping the system lean and efficient. OpenAgent references them without the `@` symbol (e.g., `standards/code.md` not `@standards/code.md`). Happy building! 🚀 diff --git a/registry.json b/registry.json index d6d9fb4..6fad7dc 100644 --- a/registry.json +++ b/registry.json @@ -371,6 +371,21 @@ "agent:system-builder" ], "category": "meta" + }, + { + "id": "validate-repo", + "name": "Validate Repository", + "type": "command", + "path": ".opencode/command/validate-repo.md", + "description": "Comprehensive validation of repository consistency between CLI, docs, registry, and components", + "tags": [ + "validation", + "quality", + "consistency", + "maintenance" + ], + "dependencies": [], + "category": "standard" } ], "tools": [ @@ -464,6 +479,146 @@ ], "dependencies": [], "category": "essential" + }, + { + "id": "standards-code", + "name": "Code Standards", + "type": "context", + "path": ".opencode/context/core/standards/code.md", + "description": "Modular, functional code standards", + "tags": [ + "standards", + "code", + "quality" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "standards-patterns", + "name": "Pattern Standards", + "type": "context", + "path": ".opencode/context/core/standards/patterns.md", + "description": "Language-agnostic pattern catalog", + "tags": [ + "standards", + "patterns", + "architecture" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "standards-tests", + "name": "Testing Standards", + "type": "context", + "path": ".opencode/context/core/standards/tests.md", + "description": "Testing best practices and guidelines", + "tags": [ + "standards", + "testing", + "quality" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "standards-docs", + "name": "Documentation Standards", + "type": "context", + "path": ".opencode/context/core/standards/docs.md", + "description": "Documentation guidelines and templates", + "tags": [ + "standards", + "documentation", + "writing" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "standards-analysis", + "name": "Analysis Standards", + "type": "context", + "path": ".opencode/context/core/standards/analysis.md", + "description": "Code analysis framework and guidelines", + "tags": [ + "standards", + "analysis", + "quality" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "workflows-delegation", + "name": "Delegation Workflow", + "type": "context", + "path": ".opencode/context/core/workflows/delegation.md", + "description": "Delegation template and process", + "tags": [ + "workflows", + "delegation", + "coordination" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "workflows-sessions", + "name": "Session Management Workflow", + "type": "context", + "path": ".opencode/context/core/workflows/sessions.md", + "description": "Session lifecycle and management", + "tags": [ + "workflows", + "sessions", + "management" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "workflows-task-breakdown", + "name": "Task Breakdown Workflow", + "type": "context", + "path": ".opencode/context/core/workflows/task-breakdown.md", + "description": "Task breakdown methodology", + "tags": [ + "workflows", + "tasks", + "planning" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "workflows-review", + "name": "Code Review Workflow", + "type": "context", + "path": ".opencode/context/core/workflows/review.md", + "description": "Code review process and guidelines", + "tags": [ + "workflows", + "review", + "quality" + ], + "dependencies": [], + "category": "standard" + }, + { + "id": "system-context-guide", + "name": "Context System Guide", + "type": "context", + "path": ".opencode/context/core/system/context-guide.md", + "description": "Guide to the context system and file organization", + "tags": [ + "system", + "guide", + "context" + ], + "dependencies": [], + "category": "standard" } ], "config": [ @@ -532,9 +687,20 @@ "command:context", "command:clean", "command:optimize", + "command:validate-repo", "tool:env", "context:essential-patterns", "context:project-context", + "context:standards-code", + "context:standards-patterns", + "context:standards-tests", + "context:standards-docs", + "context:standards-analysis", + "context:workflows-delegation", + "context:workflows-sessions", + "context:workflows-task-breakdown", + "context:workflows-review", + "context:system-context-guide", "config:env-example", "config:readme" ] @@ -581,12 +747,23 @@ "command:optimize", "command:prompt-enhancer", "command:worktrees", + "command:validate-repo", "tool:env", "tool:gemini", "plugin:notify", "plugin:telegram-notify", "context:essential-patterns", "context:project-context", + "context:standards-code", + "context:standards-patterns", + "context:standards-tests", + "context:standards-docs", + "context:standards-analysis", + "context:workflows-delegation", + "context:workflows-sessions", + "context:workflows-task-breakdown", + "context:workflows-review", + "context:system-context-guide", "config:env-example", "config:readme" ] @@ -619,12 +796,23 @@ "command:prompt-enhancer", "command:worktrees", "command:build-context-system", + "command:validate-repo", "tool:env", "tool:gemini", "plugin:notify", "plugin:telegram-notify", "context:essential-patterns", "context:project-context", + "context:standards-code", + "context:standards-patterns", + "context:standards-tests", + "context:standards-docs", + "context:standards-analysis", + "context:workflows-delegation", + "context:workflows-sessions", + "context:workflows-task-breakdown", + "context:workflows-review", + "context:system-context-guide", "config:env-example", "config:readme" ],