fix: Clean up agent YAML frontmatter and add standards (#156 )

* 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>

2026-01-31 13:11:24 +00:00

5.2 KiB

Raw Blame History

OpenAgents Control Repository Context

Purpose: Context files specific to the OpenAgents Control repository

Last Updated: 2026-01-31

Function	Files	Purpose
Standards	2 files	Agent creation standards
Concepts	2 files	Core ideas and principles
Examples	1 file	Working code samples
Guides	10 files	Step-by-step workflows
Lookup	4 files	Quick reference tables
Errors	1 file	Common issues + solutions

Standards (Agent Creation)

File	Topic	Priority
`standards/agent-frontmatter.md`	Valid OpenCode YAML frontmatter	⭐⭐⭐⭐⭐
`standards/subagent-structure.md`	Standard subagent file structure	⭐⭐⭐⭐⭐

When to read: Before creating or modifying any agent files

Concepts (Core Ideas)

File	Topic	Priority
`concepts/subagent-testing-modes.md`	Standalone vs delegation testing	⭐⭐⭐⭐⭐

When to read: Before testing any subagent

Examples (Working Code)

File	Topic	Priority
`examples/subagent-prompt-structure.md`	Optimized subagent prompt template	⭐⭐⭐⭐

When to read: When creating or optimizing subagent prompts

Guides (Step-by-Step)

File	Topic	Priority
`guides/testing-subagents.md`	How to test subagents standalone	⭐⭐⭐⭐⭐
`guides/adding-agent.md`	How to add new agents	⭐⭐⭐⭐
`guides/testing-agent.md`	How to test agents	⭐⭐⭐⭐
`guides/external-libraries-workflow.md`	How to handle external library dependencies	⭐⭐⭐⭐
`guides/github-issues-workflow.md`	How to work with GitHub issues and project board	⭐⭐⭐⭐
`guides/npm-publishing.md`	How to publish package to npm	⭐⭐⭐
`guides/updating-registry.md`	How to update registry	⭐⭐⭐
`guides/debugging.md`	How to debug issues	⭐⭐⭐
`guides/resolving-installer-wildcard-failures.md`	Fix wildcard context install failures	⭐⭐⭐
`guides/creating-release.md`	How to create releases	⭐⭐

When to read: When performing specific tasks

Lookup (Quick Reference)

File	Topic	Priority
`lookup/subagent-test-commands.md`	Subagent testing commands	⭐⭐⭐⭐⭐
`lookup/file-locations.md`	Where files are located	⭐⭐⭐⭐
`lookup/commands.md`	Available slash commands	⭐⭐⭐

When to read: Quick command lookups

Errors (Troubleshooting)

File	Topic	Priority
`errors/tool-permission-errors.md`	Tool permission issues	⭐⭐⭐⭐⭐

When to read: When tests fail with permission errors

Core Concepts (Foundational)

File	Topic	Priority
`core-concepts/agents.md`	How agents work	⭐⭐⭐⭐⭐
`core-concepts/evals.md`	How testing works	⭐⭐⭐⭐⭐
`core-concepts/registry.md`	How registry works	⭐⭐⭐⭐
`core-concepts/categories.md`	How organization works	⭐⭐⭐

When to read: First time working in this repo

Loading Strategy

For Subagent Testing:

Load concepts/subagent-testing-modes.md (understand modes)
Load guides/testing-subagents.md (step-by-step)
Reference lookup/subagent-test-commands.md (commands)
If errors: Load errors/tool-permission-errors.md

For Agent Creation:

Load standards/agent-frontmatter.md (valid YAML frontmatter)
Load standards/subagent-structure.md (file structure)
Load core-concepts/agents.md (understand system)
Load guides/adding-agent.md (step-by-step)
If using external libraries: Load guides/external-libraries-workflow.md (fetch docs)
Load examples/subagent-prompt-structure.md (if subagent)
Load guides/testing-agent.md (validate)

For Issue Management:

Load guides/github-issues-workflow.md (understand workflow)
Create issues with proper labels and templates
Add to project board for tracking
Process requests systematically

For Debugging:

Load guides/debugging.md (general approach)
Load specific error file from errors/
Reference lookup/file-locations.md (find files)

File Size Compliance

All files follow MVI principle (<200 lines):

✅ Standards: <200 lines
✅ Concepts: <100 lines
✅ Examples: <100 lines
✅ Guides: <150 lines
✅ Lookup: <100 lines
✅ Errors: <150 lines

../core/ - Core system context (standards, patterns)
../core/context-system/ - Context management system
quick-start.md - 2-minute repo orientation
../content-creation/navigation.md - Content creation principles
../to-be-consumed/claude-code-docs/plugins.md - Claude Code extension docs

Contributing

When adding new context files:

Follow MVI principle (<200 lines)
Use function-based organization (concepts/, examples/, guides/, lookup/, errors/)
Update this README.md navigation
Add cross-references to related files
Validate with /context validate

5.2 KiB Raw Blame History