# Context System

**Purpose**: Minimal, concern-based knowledge organization for AI agents

**Last Updated**: 2026-01-08

---

## Core Principles

### 1. Minimal Viable Information (MVI)
Extract only core concepts (1-3 sentences), key points (3-5 bullets), minimal example, and reference link. 
**Goal**: Scannable in <30 seconds. Reference full docs, don't duplicate them.

### 2. Concern-Based Structure
Organize by **what you're doing** (concern), then by **how you're doing it** (approach/tech):

**Two organizational patterns**:

#### Pattern A: Function-Based (for repository-specific context)
```
category/
├── navigation.md
├── concepts/              # What it is
├── examples/              # Working code
├── guides/                # How to do it
├── lookup/                # Quick reference
└── errors/                # Common issues
```

**Use when**: Content is repository-specific (e.g., `openagents-repo/`)

#### Pattern B: Concern-Based (for development context)
```
category/
├── navigation.md
├── {concern}/             # Organize by what you're doing
│   ├── navigation.md
│   ├── {approach}/        # Then by approach/tech
│   │   ├── navigation.md
│   │   └── {files}.md
```

**Use when**: Content spans multiple technologies (e.g., `development/`)

**Examples**:
- `development/backend/api-patterns/` - Concern: backend, Approach: API patterns
- `development/backend/nodejs/` - Concern: backend, Tech: Node.js
- `development/frontend/react/` - Concern: frontend, Tech: React

### 3. Token-Efficient Navigation
Every category/subcategory has `navigation.md` with:
- **ASCII tree** for quick structure scan (~50 tokens)
- **Quick routes table** for common tasks (~100 tokens)
- **By concern/type** sections (~50 tokens)
- **Total**: ~200-300 tokens per navigation file

**Why**: Faster loading, less cost, quicker AI decisions

### 4. Specialized Navigation Files
For cross-cutting concerns, create specialized navigation:
- `development/ui-navigation.md` - Spans frontend/ + ui/
- `development/backend-navigation.md` - Covers APIs, auth, middleware
- `development/fullstack-navigation.md` - Common tech stacks

**Why**: Real workflows don't fit neat categories

### 5. Self-Describing Filenames
Filenames should tell you what's inside:
- ❌ `code.md` → ✅ `code-quality.md`
- ❌ `tests.md` → ✅ `test-coverage.md`
- ❌ `review.md` → ✅ `code-review.md`

**Why**: No need to open files to understand content

### 6. Knowledge Harvesting
Extract valuable context from AI summaries/overviews, then delete them. Workspace stays clean, knowledge persists.

### 5. Technology Context Organization

**Purpose**: Ensure consistent placement of new technologies (frameworks, libraries, tools) to maintain discoverability.

**Frameworks vs Architectural Layers**:

- **Full-Stack Frameworks** (e.g., Tanstack Start, Next.js): Add under `development/frameworks/{tech}/`. These are "meta-frameworks" that span multiple layers.
- **Specialized Concerns** (e.g., AI, Data): Add under `development/{concern}/{tech}/`.
- **Layer-Specific Tech** (e.g., React, Node.js): Add under `development/{frontend|backend}/{tech}/`.

**Decision Process**:
1. Is it a full-stack framework? → `development/frameworks/`
2. Is it a specialized domain (AI, Data)? → `development/{domain}/`
3. Is it layer-specific? → `development/{frontend|backend}/`

---

## Directory Patterns

### Pattern A: Function-Based (Repository-Specific)

**Use for**: Repository-specific context (e.g., `openagents-repo/`)

```
.opencode/context/{category}/
├── navigation.md              # Fast, token-efficient navigation
├── quick-start.md             # Optional: 2-minute orientation
│
├── core-concepts/             # Foundational concepts (optional)
│   ├── 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/                    # Common issues
    ├── navigation.md
    └── {error}.md
```

---

### Pattern B: Concern-Based (Development Context)

**Use for**: Multi-technology development context (e.g., `development/`)

```
.opencode/context/{category}/
├── navigation.md                       # Main navigation
├── {concern}-navigation.md             # Specialized navigation (optional)
│
├── principles/                         # Universal principles (optional)
│   ├── navigation.md
│   └── {principle}.md
│
├── {concern}/                          # Organize by concern
│   ├── navigation.md
│   │
│   ├── {approach}/                     # Then by approach
│   │   ├── navigation.md
│   │   └── {pattern}.md
│   │
│   └── {tech}/                         # Or by tech
│       ├── navigation.md
│       └── {pattern}.md
```

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

---

## Navigation File Format

### Token-Efficient Template

```markdown
# {Category} Navigation

**Purpose**: [1 sentence]

---

## Structure

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

---

## Quick Routes

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

---

## By {Concern/Type}

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

**Target**: 200-300 tokens

---

## Organizing Principles

### 1. Core Standards (Universal)

Location: `.opencode/context/core/standards/`

**Purpose**: Universal standards that apply to ALL development

**Content**:
- Code quality principles (all languages)
- Test coverage standards
- Documentation standards
- Security patterns
- Code analysis approaches

**Used by**: All agents, all projects

**Effect on other categories**: 
- Other categories can reference these standards
- Users can edit core standards to affect context flow globally
- Development-specific standards go in `development/principles/`

---

### 2. Development Principles vs Core Standards

| Location | Scope | Examples |
|----------|-------|----------|
| `core/standards/` | **Universal** (all projects, all languages) | Code quality, testing, docs, security |
| `development/principles/` | **Development-specific** (software engineering) | Clean code, API design, error handling |

**Both exist**: Core standards are universal, development principles are domain-specific

---

### 3. Data Context Location

**Decision**: Data patterns live in `development/data/` (not top-level)

**Rationale**: Data layer is part of development workflow

**Structure**:
```
development/data/
├── navigation.md
├── sql-patterns/
├── nosql-patterns/
└── orm-patterns/
```

**Top-level `data/` category**: Reserved for data engineering/analytics (different concern)

---

### 4. Specialized Navigation Strategy

**Full-stack navigation includes**:
- Quick routes (table format)
- Common stack patterns (MERN, T3, etc.)

**Example**:
```markdown
## Quick Routes
| Task | Path |
|------|------|
| **Frontend** | `ui-navigation.md` |

## Common Stacks

### MERN Stack
Frontend: development/frontend/react/
Backend:  development/backend/nodejs/
Data:     development/data/nosql-patterns/mongodb.md
```

---

## Operations

### Harvest (`/context harvest`)

**Purpose**: Extract knowledge from summary files → permanent context, then clean up.

**Process**:
1. Scan for patterns: `*OVERVIEW.md`, `*SUMMARY.md`, `SESSION-*.md`, `CONTEXT-*.md`
2. Analyze content:
   - Design decisions → `concepts/`
   - Solutions/patterns → `examples/`
   - Workflows → `guides/`
   - Errors encountered → `errors/`
   - Reference data → `lookup/`
3. Present approval UI (letter-based: `A B C` or `all`)
4. Extract + minimize (apply MVI)
5. Archive/delete summaries
6. Report results

---

### Extract (`/context extract`)

**Purpose**: Extract context from docs/code/URLs.

**Process**:
1. Read source
2. Extract core concepts (1-3 sentences each)
3. Find minimal examples
4. Identify workflows (numbered steps)
5. Build lookup tables
6. Capture errors/gotchas
7. Create references

**Output**: Follow MVI template

---

### Organize (`/context organize`)

**Purpose**: Restructure existing files into appropriate pattern.

**Process**:
1. Scan category
2. Determine pattern (function-based or concern-based)
3. Create missing directories
4. Move/refactor files
5. Update navigation.md
6. Fix references

---

### Update (`/context update`)

**Purpose**: Update context when APIs/frameworks change.

**Process**:
1. Identify what changed
2. Find affected files
3. Update concepts, examples, guides, lookups
4. Add migration notes to errors/
5. Validate references

---

## File Naming Conventions

### Navigation Files
- `navigation.md` - Main navigation for category/subcategory
- `{domain}-navigation.md` - Specialized cross-cutting navigation

### Content Files
- Use descriptive names: `code-quality.md` not `code.md`
- Include type when helpful: `rest-design.md`, `jwt-patterns.md`
- Use kebab-case: `scroll-linked-animations.md`

---

## Extraction Rules

### ✅ Extract:
- Core concepts (minimal)
- Essential patterns
- Step-by-step workflows
- Critical errors
- Quick reference data
- Links to detailed docs

### ❌ Don't Extract:
- Verbose explanations
- Complete API docs
- Implementation details
- Historical context
- Marketing content
- Duplicate info

---

## Success Criteria

✅ **Minimal** - Core info only, <200 lines per file
✅ **Navigable** - navigation.md at every level
✅ **Organized** - Appropriate pattern (function-based or concern-based)
✅ **Token-efficient** - Navigation files ~200-300 tokens
✅ **Self-describing** - Filenames tell you what's inside
✅ **Referenceable** - Links to full docs
✅ **Searchable** - Easy to find via navigation
✅ **Maintainable** - Easy to update

---

## Related Documentation

- `context-system/guides/navigation-design.md` - How to create navigation files
- `context-system/guides/organizing-context.md` - How to choose organizational pattern
- `context-system/examples/navigation-examples.md` - Good navigation examples
- `context-system/standards/templates.md` - File templates

---

## Quick Commands

```bash
/context harvest              # Clean up summaries
/context extract {source}     # From docs/code
/context organize {category}  # Restructure
/context update {what}        # When APIs change
```