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-01-08

---

Prerequisites

• Understand context system principles (../context-system.md)
• Know your content domain
• Have content to organize

Estimated time: 30-45 min per category

---

Two Organizational Patterns

Pattern A: Function-Based

Use for: Repository-specific context

Structure: Organize by what the information does

• 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}/ - What you're working on
  • {approach}/ - How you're doing it
  • {tech}/ - What you're using

Example: development/

---

Decision Tree

Step 1: Is this repository-specific?

YES → Use Pattern A (Function-Based)

Examples:

• openagents-repo/ - OpenAgents Control repository work
• myproject-repo/ - Your project's repository

NO → Continue to Step 2

---

Step 2: Does content span multiple technologies?

YES → Use Pattern B (Concern-Based)

Examples:

• development/ - Frontend, backend, data, infrastructure
• ui/ - Web, terminal, mobile (future)

NO → Use Pattern A (Function-Based)

Examples:

• content/ - Copywriting frameworks (single domain)
• product/ - Product management (single domain)

---

Step 3: Is there a natural hierarchy of concerns?

YES → Use Pattern B (Concern-Based)

Example hierarchy:

development/
├── frontend/           # Concern
│   ├── react/          # Tech
│   └── vue/            # Tech
├── backend/            # Concern
│   ├── api-patterns/   # Approach
│   └── nodejs/         # Tech

NO → Use Pattern A (Function-Based)

---

Pattern A: Function-Based Organization

When to Use

✅ Repository-specific context (e.g., openagents-repo/) ✅ Single-domain content (e.g., content/, product/) ✅ Content naturally groups by information type ✅ Users need to find "how to do X" quickly

Structure

{category}/
├── navigation.md
├── quick-start.md              # Optional: orientation
│
├── core-concepts/              # Optional: foundational
│   ├── navigation.md
│   └── {concept}.md
│
├── concepts/                   # What it is
│   ├── navigation.md
│   └── {concept}.md
│
├── examples/                   # Working code
│   ├── navigation.md
│   └── {example}.md
│
├── guides/                     # How to do it
│   ├── navigation.md
│   └── {guide}.md
│
├── lookup/                     # Quick reference
│   ├── navigation.md
│   └── {lookup}.md
│
└── errors/                     # Troubleshooting
    ├── navigation.md
    └── {error}.md

Example: openagents-repo/

openagents-repo/
├── navigation.md
├── quick-start.md
│
├── core-concepts/              # Foundational (agents, evals, registry)
├── concepts/                   # Additional concepts
├── guides/                     # How to add agent, test, etc.
├── lookup/                     # Commands, file locations
├── examples/                   # Context bundles, prompts
└── errors/                     # Tool permissions, validation

Why this works:

• Repository-specific (not general development)
• Users need "how to add agent" (guide)
• Users need "where is X file" (lookup)
• Users need "fix this error" (errors)

---

Pattern B: Concern-Based Organization

When to Use

✅ Multi-technology content (e.g., development/) ✅ Content organized by "what you're doing" (concern) ✅ Multiple approaches/technologies per concern ✅ Need to support full-stack workflows

Structure

{category}/
├── navigation.md
├── {concern}-navigation.md     # Specialized (optional)
│
├── principles/                 # Universal (optional)
│   ├── navigation.md
│   └── {principle}.md
│
├── {concern}/                  # What you're doing
│   ├── navigation.md
│   │
│   ├── {approach}/             # How (approach-based)
│   │   ├── navigation.md
│   │   └── {pattern}.md
│   │
│   └── {tech}/                 # How (tech-specific)
│       ├── navigation.md
│       └── {pattern}.md

Example: development/

development/
├── navigation.md
├── ui-navigation.md            # Specialized
├── backend-navigation.md       # Specialized
│
├── principles/                 # Universal
│   ├── clean-code.md
│   └── api-design.md
│
├── frontend/                   # Concern: client-side
│   ├── react/                  # Tech
│   │   ├── hooks-patterns.md
│   │   └── tanstack/           # Sub-tech
│   └── vue/                    # Tech
│
├── backend/                    # Concern: server-side
│   ├── api-patterns/           # Approach
│   │   ├── rest-design.md
│   │   └── graphql-design.md
│   ├── nodejs/                 # Tech
│   └── authentication/         # Functional concern
│
└── data/                       # Concern: data layer
    ├── sql-patterns/           # Approach
    └── orm-patterns/           # Approach

Why this works:

• Multi-technology (React, Vue, Node, Python, etc.)
• Organized by concern (frontend, backend, data)
• Then by approach (REST, GraphQL) or tech (Node.js, React)
• Supports full-stack workflows

---

Hybrid Approach

When to Use

✅ Category has both repository-specific AND multi-tech content ✅ Need flexibility for different subcategories

Structure

{category}/
├── navigation.md
│
├── {subcategory-A}/            # Function-based
│   ├── concepts/
│   ├── guides/
│   └── examples/
│
└── {subcategory-B}/            # Concern-based
    ├── {concern}/
    │   ├── {approach}/
    │   └── {tech}/

Example: ui/

ui/
├── navigation.md
│
├── web/                        # Platform (concern-based)
│   ├── navigation.md
│   ├── animation-patterns.md
│   ├── ui-styling-standards.md
│   └── design/
│       ├── concepts/           # Function-based within
│       └── examples/
│
└── terminal/                   # Platform (concern-based)
    └── navigation.md

Why this works:

• Top level: Platform-based (web, terminal, mobile)
• Within platform: Mix of flat files + function folders
• Flexible for different needs

---

Organizing by Concern vs Tech

Concern First, Then Tech

Use when: Multiple technologies solve the same concern

backend/
├── api-patterns/               # Concern: API design
│   ├── rest-design.md          # Approach
│   ├── graphql-design.md       # Approach
│   └── grpc-patterns.md        # Approach
├── nodejs/                     # Tech
└── python/                     # Tech

Why: Principles (REST, GraphQL) are more important than implementation (Node, Python)

---

Tech First, Then Concern

Use when: Technology dictates the approach

frontend/
├── react/                      # Tech
│   ├── hooks-patterns.md       # Concern: state
│   ├── component-architecture.md # Concern: structure
│   └── tanstack/               # Sub-tech
│       ├── query-patterns.md   # Concern: data fetching
│       └── router-patterns.md  # Concern: routing
└── vue/                        # Tech

Why: React patterns differ significantly from Vue patterns

---

Specialized Navigation Files

When to Create

✅ Concern spans multiple subcategories ✅ Common workflows cross category boundaries ✅ Users need task-focused routes

Examples

ui-navigation.md (in development/):

• Spans development/frontend/ + ui/web/
• Task: "I need to build a UI"
• Routes to both code patterns and visual design

backend-navigation.md (in development/):

• Covers backend/api-patterns/, backend/nodejs/, backend/authentication/
• Task: "I need to build an API"
• Routes to approach, tech, and functional concerns

fullstack-navigation.md (in development/):

• Covers frontend + backend + data
• Task: "I need to build a full-stack app"
• Shows common tech stacks (MERN, T3, etc.)

---

Steps to Organize

1. Audit Existing Content

List all files:

find .opencode/context/{category} -name "*.md" | sort

Categorize each file:

• What concern does it address?
• What approach/tech does it cover?
• What type of information? (concept, guide, example, etc.)

---

2. Choose Pattern

Use decision tree above to choose:

• Pattern A (Function-Based)
• Pattern B (Concern-Based)
• Hybrid

---

3. Create Directory Structure

For Pattern A:

mkdir -p {category}/{concepts,examples,guides,lookup,errors}

For Pattern B:

mkdir -p {category}/{concern}/{approach}
mkdir -p {category}/{concern}/{tech}

---

4. Move Files

Move files to appropriate locations:

mv {category}/old-file.md {category}/{concern}/{tech}/new-file.md

Rename for clarity:

mv code.md code-quality.md
mv tests.md test-coverage.md

---

5. Create Navigation Files

Create navigation.md at each level:

• Category level
• Subcategory level
• Specialized navigation (if needed)

Follow navigation design guide (navigation-design.md)

---

6. Update References

Find and update all cross-references:

grep -r "old-path" .opencode/context/
# Update to new paths

---

Examples

Example 1: Organizing development/

Before (flat):

development/
├── clean-code.md
├── api-design.md
├── react-patterns.md
├── animation-patterns.md
├── design-systems.md

After (concern-based):

development/
├── navigation.md
├── ui-navigation.md
│
├── principles/
│   ├── clean-code.md
│   └── api-design.md
│
└── frontend/
    └── react/
        └── react-patterns.md

Moved to ui/:

ui/web/
├── animation-patterns.md
└── design-systems.md

---

Example 2: Organizing openagents-repo/

Before (mixed):

openagents-repo/
├── README.md
├── agents.md
├── evals.md
├── adding-agent.md
├── testing-agent.md
├── commands.md

After (function-based):

openagents-repo/
├── navigation.md
├── quick-start.md
│
├── core-concepts/
│   ├── agent-architecture.md
│   └── eval-framework.md
│
├── guides/
│   ├── adding-agent.md
│   └── testing-agent.md
│
└── lookup/
    └── commands.md

---

Verification

After organizing:

• Pattern chosen (A, B, or Hybrid)?
• Directory structure created?
• Files moved to appropriate locations?
• Files renamed for clarity?
• Navigation files created at each level?
• Cross-references updated?
• Token count for navigation files 200-300?

---

Troubleshooting

Issue	Solution
File fits multiple concerns	Choose primary concern, add cross-reference
Too many subcategories	Group by higher-level concern
Unclear where file goes	Ask: "What task does this support?"
Navigation too complex	Create specialized navigation file

---

Related

• ../context-system.md - Core principles
• navigation-design.md - How to create navigation files
• ../examples/navigation-examples.md - Good examples