OpenAgentsControl/.opencode/context/core/context-system/guides/organizing-context.md

Guide: Organizing Context by Concern

Purpose: How to choose and apply the right organizational pattern

Last Updated: 2026-02-15

---

Two Organizational Patterns

Pattern A: Function-Based

Use for: Repository-specific context

Structure: Organize by what the information does

{repo}/
├── concepts/     # What it is
├── examples/     # Working code
├── guides/       # How to do it
├── lookup/       # Quick reference
└── errors/       # Troubleshooting

Example: openagents-repo/

---

Pattern B: Concern-Based

Use for: Multi-technology development context

Structure: Organize by what you're doing (concern), then how (approach/tech)

{concern}/
├── {approach}/   # How you're doing it
└── {tech}/       # What you're using

Example: development/frontend/react/, ui/web/design/

---

Decision Tree

Question	Answer	Use Pattern
Is this repository-specific?	YES	Pattern A (Function-Based)
Does content span multiple technologies?	YES	Pattern B (Concern-Based)
Single domain/technology?	YES	Pattern A (Function-Based)

---

Quick Steps to Organize

1. Audit Existing Content

• List all files
• Identify natural groupings
• Note overlaps/duplicates

2. Choose Pattern

• Use decision tree above
• Consider future growth
• Check existing patterns in .opencode/context/

3. Create Directory Structure

mkdir -p {category}/{subcategory}

4. Move Files

• Move files to new structure
• Keep filenames descriptive
• Follow naming conventions

5. Create Navigation Files

• Add navigation.md to each directory
• Follow navigation template (see navigation-templates.md)
• Keep to 200-300 tokens

6. Update References

• Update links in moved files
• Update parent navigation.md
• Test navigation paths

---

Pattern Examples

Function-Based (openagents-repo/)

openagents-repo/
├── concepts/agents.md
├── examples/subagent-example.md
├── guides/creating-agents.md
├── lookup/commands.md
└── errors/tool-errors.md

Concern-Based (development/)

development/
├── frontend/
│   ├── react/
│   └── vue/
├── backend/
│   ├── node/
│   └── python/
└── data/
    └── postgres/

Hybrid (ui/)

ui/
├── web/
│   ├── design/
│   ├── animation/
│   └── react-patterns.md
└── terminal/
    └── cli-design.md

---

Verification Checklist

• Every directory has navigation.md?
• Navigation files follow template?
• All files have frontmatter?
• Links updated and working?
• Pattern is consistent?
• Files under line limits?

---

Troubleshooting

Issue	Solution
File fits multiple categories	Choose primary purpose, reference from others
Too many files in one directory	Create subcategories
Unclear hierarchy	Use concern-based pattern
Navigation too complex	Simplify structure, use specialized navigation

---

Related

• structure.md - Directory structure standards
• navigation-templates.md - Navigation file templates
• creation.md - Creating new context files