OpenAgentsControl/.opencode/context/core/context-system/guides/navigation-design.md

Guide: Designing Navigation Files

Purpose: How to create token-efficient, scannable navigation files

Last Updated: 2026-01-08

---

Prerequisites

• Understand MVI principle (context-system/standards/mvi.md)
• Know your category's organizational pattern (function-based or concern-based)
• Have content files already created

Estimated time: 15-20 min per navigation file

---

Core Principles

1. Token Efficiency

Goal: 200-300 tokens per navigation file

Why:

• Faster AI loading
• Lower costs
• Quicker decision-making

How:

• Use ASCII trees (not verbose descriptions)
• Use tables (not paragraphs)
• Be concise (not comprehensive)

---

2. Scannable Structure

Goal: AI can find what it needs in <5 seconds

Format:

1. Structure (ASCII tree) - See what exists
2. Quick Routes (table) - Jump to common tasks
3. By Concern/Type (sections) - Browse by category

---

3. Self-Contained

Goal: Navigation file answers "where do I go?"

Include:

• ✅ Paths to files
• ✅ Brief descriptions (3-5 words)
• ✅ When to use each file

Exclude:

• ❌ File contents (that's what the files are for)
• ❌ Detailed explanations
• ❌ Duplicate information

---

Steps

1. Determine Navigation Type

Category-level navigation ({category}/navigation.md):

• Overview of entire category
• Points to subcategories
• Includes specialized navigation files

Subcategory-level navigation ({category}/{subcategory}/navigation.md):

• Overview of subcategory
• Lists files in this subcategory
• Points to related categories

Specialized navigation ({category}/{domain}-navigation.md):

• Cross-cutting concern (e.g., ui-navigation.md)
• Spans multiple subcategories
• Task-focused routes

---

2. Create Structure Section

Format: ASCII tree showing directory structure

Example (Function-based):

## Structure

openagents-repo/ ├── navigation.md ├── quick-start.md │ ├── concepts/ │ ├── navigation.md │ └── subagent-testing-modes.md │ ├── guides/ │ ├── navigation.md │ ├── adding-agent.md │ └── testing-agent.md │ └── lookup/

├── navigation.md
└── commands.md

Example (Concern-based):

## Structure

development/ ├── navigation.md ├── ui-navigation.md # Specialized │ ├── principles/ │ ├── clean-code.md │ └── api-design.md │ ├── frontend/ │ ├── react/ │ │ ├── hooks-patterns.md │ │ └── tanstack/ │ │ └── query-patterns.md │ └── vue/ │ └── backend/

├── api-patterns/
│   ├── rest-design.md
│   └── graphql-design.md
└── nodejs/

Token count: ~50-100 tokens

---

3. Create Quick Routes Table

Format: Task → Path mapping

Example:

## Quick Routes

| Task | Path |
|------|------|
| **Add agent** | `guides/adding-agent.md` |
| **Test agent** | `guides/testing-agent.md` |
| **Debug issue** | `guides/debugging-issues.md` |
| **Find files** | `lookup/file-locations.md` |

Guidelines:

• Use bold for task names
• Use relative paths
• 5-10 most common tasks
• Order by frequency of use

Token count: ~50-100 tokens

---

4. Create By Concern/Type Sections

Format: Group files by concern or type

Example (Function-based):

## By Type

**Concepts** → Core ideas and principles
**Guides** → Step-by-step workflows
**Lookup** → Quick reference tables
**Errors** → Troubleshooting

Example (Concern-based):

## By Concern

**Principles** → Universal development practices
**Frontend** → React, Vue, state management
**Backend** → APIs, Node.js, Python, auth
**Data** → SQL, NoSQL, ORMs

Token count: ~50-100 tokens

---

5. Add Related Context (Optional)

Format: Links to related categories

Example:

## Related Context

- **Core Standards** → `../core/standards/navigation.md`
- **UI Patterns** → `../ui/navigation.md`

Token count: ~20-50 tokens

---

6. Validate Token Count

Target: 200-300 tokens

Check:

# Count tokens (rough estimate: words * 1.3)
wc -w navigation.md
# Multiply by 1.3 for token estimate

If over 300 tokens:

• Remove verbose descriptions
• Shorten table entries
• Remove less-used routes

---

Templates

Category Navigation Template

# {Category} Navigation

**Purpose**: [1 sentence]

---

## Structure

{category}/ ├── navigation.md ├── {subcategory}/ │ ├── navigation.md │ └── {files}.md

---

## Quick Routes

| Task | Path |
|------|------|
| **{Task 1}** | `{path}` |
| **{Task 2}** | `{path}` |
| **{Task 3}** | `{path}` |

---

## By {Concern/Type}

**{Section 1}** → {description}
**{Section 2}** → {description}
**{Section 3}** → {description}

---

## Related Context

- **{Category}** → `../{category}/navigation.md`

Token count: ~200-250 tokens

---

Specialized Navigation Template

# {Domain} Navigation

**Scope**: [What this covers]

---

## Structure

{Relevant directories across multiple categories}

---

## Quick Routes

| Task | Path |
|------|------|
| **{Task 1}** | `{path}` |
| **{Task 2}** | `{path}` |

---

## By {Framework/Approach}

**{Tech 1}** → `{path}`
**{Tech 2}** → `{path}`

---

## Common Workflows

**{Workflow 1}**:
1. `{file1}` ({purpose})
2. `{file2}` ({purpose})

Token count: ~250-300 tokens

---

Examples

Good Navigation (Token-Efficient)

# Development Navigation

**Purpose**: Software development across all stacks

---

## Structure

development/ ├── navigation.md ├── ui-navigation.md ├── principles/ ├── frontend/ ├── backend/ └── data/

---

## Quick Routes

| Task | Path |
|------|------|
| **UI/Frontend** | `ui-navigation.md` |
| **Backend/API** | `backend-navigation.md` |
| **Clean code** | `principles/clean-code.md` |

---

## By Concern

**Principles** → Universal practices
**Frontend** → React, Vue, state
**Backend** → APIs, Node, auth
**Data** → SQL, NoSQL, ORMs

Token count: ~180 tokens ✅

---

Bad Navigation (Too Verbose)

# Development Navigation

**Purpose**: This navigation file helps you find software development patterns, standards, and best practices across all technology stacks including frontend, backend, databases, and infrastructure.

---

## Introduction

The development category contains comprehensive guides and patterns for building modern applications. Whether you're working on frontend user interfaces, backend APIs, database integrations, or infrastructure setup, you'll find relevant context here.

---

## Directory Structure

The development category is organized into several subcategories:

- **principles/** - This directory contains universal development principles that apply regardless of the technology stack you're using. Files include clean code practices, API design principles, and more.

- **frontend/** - This directory contains frontend development patterns including React, Vue, and state management solutions.

[... continues for 500+ tokens]

Token count: 500+ tokens ❌

---

Verification

After creating navigation file:

• Token count 200-300?
• ASCII tree included?
• Quick routes table included?
• By concern/type section included?
• Paths are relative?
• Descriptions are 3-5 words?
• No duplicate information?
• Links to related context?

---

Troubleshooting

Issue	Solution
Too many tokens	Remove verbose descriptions, shorten table entries
Hard to scan	Use tables instead of paragraphs
Missing files	Add to structure section and quick routes
Unclear paths	Use relative paths, add brief descriptions

---

Related

• ../standards/mvi.md - Minimal Viable Information principle
• organizing-context.md - How to choose organizational pattern
• ../examples/navigation-examples.md - More examples