a468e96a71
* chore: bump version to v0.8.0
* chore: update version to 0.7.1 instead of 0.8.0
* docs: expand comparison table with Oh My OpenCode and additional features
* backup: development context before reorganization
* refactor(context): reorganize development folder
- Remove 7 duplicate files (ui/design files exist in ui/web/)
- Remove 2 redundant READMEs (use navigation.md instead)
- Move react-patterns.md to frontend/react/
- Create frontend/react/navigation.md
- Update 4 navigation files (development, ui, frontend, frontend/react)
- Update developer profile (4 path changes: ui-styling-standards, design-systems, design-assets, animation-patterns)
- Update 3 core context files (visual-development.md, design-iteration.md, file-locations.md)
Result: 29 context files (down from 36), no duplicates, clean structure
Refs: REORGANIZATION_PLAN.md, REORGANIZATION_SUMMARY.md
* docs(context): add frontend delegation guide
- Create when-to-delegate.md with clear decision criteria
- Decision matrix for when to delegate vs. handle directly
- Common patterns and examples
- Red flags and green flags
- Frontend-specialist capabilities reference
- Update frontend and development navigation files
Helps orchestrators decide when to delegate UI work to frontend-specialist subagent.
* feat: enhance developer and advanced profiles with UI, development, and system builder context
- Developer profile: Add UI/UX patterns, development principles, design systems, React patterns, animation patterns, styling standards, and design assets
- Full profile: Add same UI/development context as developer profile for consistency
- Advanced profile: Add comprehensive system builder context including templates, guides, context system standards, and repository management context
- Update profile descriptions to reflect new capabilities
- All context files verified to exist and are properly referenced
* fix: remove duplicate context entries with incorrect paths
- Remove duplicate design-assets, ui-styling-standards, clean-code, animation-patterns, design-systems, react-patterns, and api-design entries that pointed to wrong paths
- Remove non-existent development-readme and mastra-ai-readme entries
- Keep only correct entries with proper file paths
- All registry paths now validated and correct
* feat: add add-context command to registry and all profiles
- Register add-context command in registry.json
- Add command:add-context to all 5 profiles (essential, developer, business, full, advanced)
- Update add-context.md to mention external-context files in .tmp/ directory
- Fix command dependencies to use context IDs instead of full paths
- All registry paths and dependencies validated
* feat: enhance add-context with external context file management
- Add Stage 0: Detect external context files in .tmp/
- Offer options to extract, manage, or harvest external files
- Extract patterns from external context files for use in project intelligence
- Provide management options: update, remove, clean, or harvest
- Add examples showing external context extraction and management
- Update troubleshooting with external context file handling
- Integrate with /context harvest command for permanent context organization
* fix: comprehensive context system audit and restructuring
- Fix 6 command documentation inconsistencies in add-context.md
* Correct /add-context vs /context harvest command references
* Simplify Stage 0 workflow from 4 to 2 options
* Update examples to match actual behavior
* Remove non-existent operations from delegation section
* Fix troubleshooting Q&A section
- Restructure registry.json with 4 major improvements
* Replace 31 duplicate 'navigation' IDs with unique IDs per subfolder
- core-navigation, development-navigation, openagents-repo-navigation, etc.
* Add context:openagents-repo/* to developer and full profiles
- Developers now have repo-specific guides and examples
* Remove context:to-be-consumed/* from essential, developer, business, full
- Keep only in advanced profile for system builders
* Properly scope mastra-ai context via wildcard patterns
Validation Results:
- Registry: 220/220 paths valid, 0 missing dependencies
- Profiles: All appropriately scoped with no duplicate IDs
- Standards: MVI compliance, frontmatter, structure verified
- No regressions: All tests passing
Fixes issues with context organization, command consistency, and profile coverage.
* feat: add premium dark UI design system context
- Add comprehensive quick start guide for premium dark UI
- Add visual reference guide with ASCII diagrams
- Includes color palette, components, layouts, and best practices
- Provides glassmorphism and radial glow patterns
- Complete with accessibility guidelines and responsive design
- Ready-to-use code snippets and templates
* docs: update design navigation with premium dark UI guides
* fix: Clean up agent YAML frontmatter and add standards
Fixed YAML frontmatter issues in 18 agent files:
- Removed duplicate YAML keys (e.g., read: true followed by read: {})
- Removed orphaned list items without parent keys
- Fixed field names (permission: → permissions:)
- Removed extra --- delimiter blocks in content
- Cleaned up comments and invalid OpenCode fields
Changes:
- 14 subagent files fixed (core, code, development, system-builder)
- 4 primary/meta agent files fixed (openagent, opencoder, repo-manager, eval-runner)
- Net reduction: 439 lines removed, 116 lines added (cleaner YAML)
Added agent standards documentation:
- .opencode/context/openagents-repo/standards/agent-frontmatter.md
- .opencode/context/openagents-repo/standards/subagent-structure.md
- .opencode/context/openagents-repo/standards/navigation.md
- Updated main navigation.md with standards section
All files follow MVI principles (<200 lines) and document the 5 common
YAML mistakes that were fixed.
Fixes subagent recognition issues where agents were registered as 'all'
mode instead of 'subagent' mode due to malformed YAML.
---------
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
159 lines
4.5 KiB
Markdown
159 lines
4.5 KiB
Markdown
<!-- Context: openagents-repo/standards/navigation | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
|
|
# OpenAgents Repo Standards
|
|
|
|
**Purpose**: Standards for creating and maintaining agents in OpenAgents Control
|
|
**Last Updated**: 2026-01-31
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This directory contains standards for agent creation, focusing on:
|
|
- Valid OpenCode YAML frontmatter structure
|
|
- Subagent file organization and patterns
|
|
- Common mistakes and how to avoid them
|
|
|
|
These standards emerged from fixing YAML frontmatter issues across 18 agent files.
|
|
|
|
---
|
|
|
|
## Standards Files
|
|
|
|
| File | Description | Priority | Lines |
|
|
|------|-------------|----------|-------|
|
|
| [agent-frontmatter.md](agent-frontmatter.md) | Valid OpenCode frontmatter fields and common mistakes | critical | <200 |
|
|
| [subagent-structure.md](subagent-structure.md) | Standard structure for subagent files | critical | <200 |
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### Valid OpenCode Fields (Frontmatter)
|
|
|
|
**Required**:
|
|
- `name` - Display name
|
|
- `description` - When to use this agent
|
|
- `mode` - Agent type (primary, subagent, all)
|
|
|
|
**Optional**:
|
|
- `temperature` - Response randomness (0.0-1.0)
|
|
- `model` - Model override
|
|
- `maxSteps` - Max iterations
|
|
- `disable` - Disable agent
|
|
- `hidden` - Hide from autocomplete
|
|
- `prompt` - Custom prompt file
|
|
- `tools` - Tool access config
|
|
- `permissions` - Permission rules
|
|
- `skills` - Skills to load
|
|
|
|
### Invalid Fields (Move to agent-metadata.json)
|
|
|
|
These fields are NOT valid in OpenCode frontmatter:
|
|
- `id` - Agent identifier
|
|
- `category` - Agent category
|
|
- `type` - Component type
|
|
- `version` - Version number
|
|
- `author` - Author identifier
|
|
- `tags` - Discovery tags
|
|
- `dependencies` - Component dependencies
|
|
|
|
**Solution**: Move these to `.opencode/config/agent-metadata.json`
|
|
|
|
---
|
|
|
|
## Common Mistakes Fixed
|
|
|
|
### 1. Duplicate YAML Keys
|
|
**Problem**: `read: true` followed by `read: {"**/*": "allow"}`
|
|
**Fix**: Use only one declaration per key
|
|
|
|
### 2. Orphaned List Items
|
|
**Problem**: Lines without parent keys (e.g., `- write: false`)
|
|
**Fix**: Proper YAML structure with parent keys
|
|
|
|
### 3. Wrong Field Names
|
|
**Problem**: `permission:` instead of `permissions:`
|
|
**Fix**: Use correct field name `permissions:`
|
|
|
|
### 4. Extra Delimiter Blocks
|
|
**Problem**: Multiple `---` blocks in content
|
|
**Fix**: Only one frontmatter block at top
|
|
|
|
### 5. Invalid OpenCode Fields
|
|
**Problem**: Fields like `id`, `category`, `type` in frontmatter
|
|
**Fix**: Move to agent-metadata.json
|
|
|
|
---
|
|
|
|
## Loading Strategy
|
|
|
|
### For Creating New Agents
|
|
1. Load `agent-frontmatter.md` - Understand valid fields
|
|
2. Load `subagent-structure.md` - Follow structure pattern
|
|
3. Reference existing agents as examples
|
|
4. Validate YAML syntax before committing
|
|
|
|
### For Fixing Existing Agents
|
|
1. Load `agent-frontmatter.md` - Identify invalid fields
|
|
2. Check for common mistakes (duplicates, orphans, wrong names)
|
|
3. Move invalid fields to agent-metadata.json
|
|
4. Validate with YAML parser
|
|
|
|
### For Code Reviews
|
|
1. Load `agent-frontmatter.md` - Check frontmatter validity
|
|
2. Load `subagent-structure.md` - Verify structure compliance
|
|
3. Check for common mistakes
|
|
4. Validate YAML syntax
|
|
|
|
---
|
|
|
|
## Validation Commands
|
|
|
|
### Check YAML Syntax
|
|
```bash
|
|
yq eval '.opencode/agent/category/agent.md' > /dev/null
|
|
```
|
|
|
|
### Check for Duplicate Keys
|
|
```bash
|
|
grep -A 50 "^---$" .opencode/agent/category/agent.md | grep -E "^[a-z_]+:" | sort | uniq -d
|
|
```
|
|
|
|
### List All Frontmatter Keys
|
|
```bash
|
|
grep -A 50 "^---$" .opencode/agent/category/agent.md | grep -E "^[a-z_]+:" | cut -d: -f1
|
|
```
|
|
|
|
Valid keys: `name`, `description`, `mode`, `temperature`, `model`, `maxSteps`, `disable`, `hidden`, `prompt`, `tools`, `permissions`, `skills`
|
|
|
|
---
|
|
|
|
## Related Context
|
|
|
|
### Core Concepts
|
|
- [Agent Metadata System](../core-concepts/agent-metadata.md) - Centralized metadata management
|
|
- [Agents](../core-concepts/AGENTS.md) - Agent system overview
|
|
- [Categories](../core-concepts/categories.md) - Agent categorization
|
|
|
|
### Guides
|
|
- [Adding Agents](../guides/adding-agent.md) - How to create new agents
|
|
- [Testing Agents](../guides/testing-agent.md) - Agent testing workflow
|
|
|
|
### Lookup
|
|
- [File Locations](../lookup/file-locations.md) - Where files go
|
|
|
|
---
|
|
|
|
## History
|
|
|
|
**2026-01-31**: Initial standards created after fixing YAML frontmatter issues in 18 agent files. Issues fixed:
|
|
- Duplicate YAML keys (e.g., `read: true` + `read: {"**/*": "allow"}`)
|
|
- Orphaned list items (lines without parent keys)
|
|
- Wrong field names (`permission:` → `permissions:`)
|
|
- Extra `---` delimiter blocks in content
|
|
- Invalid OpenCode fields in frontmatter
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Maintainer**: OpenAgents Control Team
|