chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
87
.opencode/context/core/context-system/CHANGELOG.md
Normal file
87
.opencode/context/core/context-system/CHANGELOG.md
Normal file
@@ -0,0 +1,87 @@
|
||||
<!-- Context: core/CHANGELOG | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context System Changelog
|
||||
|
||||
**Purpose**: Track major changes to the context system
|
||||
|
||||
---
|
||||
|
||||
## 2026-01-08: Navigation System Redesign
|
||||
|
||||
### Major Changes
|
||||
|
||||
1. **Renamed README.md → navigation.md**
|
||||
- More descriptive filename
|
||||
- Better discoverability
|
||||
- Self-describing purpose
|
||||
|
||||
2. **Added Concern-Based Organization Pattern**
|
||||
- Pattern A: Function-Based (repository-specific)
|
||||
- Pattern B: Concern-Based (multi-technology)
|
||||
- Hybrid approach supported
|
||||
|
||||
3. **Token-Efficient Navigation**
|
||||
- Target: 200-300 tokens per navigation file
|
||||
- ASCII trees for structure
|
||||
- Tables for quick routes
|
||||
- Concise descriptions (3-5 words)
|
||||
|
||||
4. **Specialized Navigation Files**
|
||||
- Cross-cutting concerns (e.g., `ui-navigation.md`)
|
||||
- Task-focused routes
|
||||
- Workflow-oriented
|
||||
|
||||
5. **Self-Describing Filenames**
|
||||
- `code.md` → `code-quality.md`
|
||||
- `tests.md` → `test-coverage.md`
|
||||
- `review.md` → `code-review.md`
|
||||
|
||||
### New Documentation
|
||||
|
||||
**Created**:
|
||||
- `guides/navigation-design.md` - How to create navigation files
|
||||
- `guides/organizing-context.md` - How to choose organizational pattern
|
||||
- `examples/navigation-examples.md` - Real-world examples
|
||||
|
||||
**Updated**:
|
||||
- `context-system.md` - Added concern-based pattern, navigation principles
|
||||
- `standards/templates.md` - Added navigation templates
|
||||
|
||||
### Organizational Decisions
|
||||
|
||||
1. **Core Standards (Universal)**
|
||||
- Location: `core/standards/`
|
||||
- Scope: All projects, all languages
|
||||
- Users can edit to affect global context flow
|
||||
|
||||
2. **Development Principles (Domain-Specific)**
|
||||
- Location: `development/principles/`
|
||||
- Scope: Software engineering
|
||||
- Both core standards and dev principles exist
|
||||
|
||||
3. **Data Context**
|
||||
- Location: `development/data/` (not top-level)
|
||||
- Rationale: Data layer is part of development workflow
|
||||
|
||||
4. **Specialized Navigation**
|
||||
- Includes quick routes + common patterns
|
||||
- Example: `fullstack-navigation.md` shows MERN, T3 stacks
|
||||
|
||||
### Migration Path
|
||||
|
||||
**Phase 0**: ✅ Update context system documentation (DONE)
|
||||
**Phase 1**: Rename navigation files, update core/
|
||||
**Phase 2**: Restructure development/ category
|
||||
**Phase 3**: Organize New-context-to-sort/
|
||||
**Phase 4**: Update all references
|
||||
|
||||
---
|
||||
|
||||
## Previous Changes
|
||||
|
||||
### 2026-01-06: Initial Context System
|
||||
|
||||
- Established MVI principle
|
||||
- Created function-based structure
|
||||
- Added file templates
|
||||
- Defined operations (harvest, extract, organize, update)
|
||||
@@ -0,0 +1,493 @@
|
||||
<!-- Context: core/navigation-examples | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Examples: Navigation Files
|
||||
|
||||
**Purpose**: Real-world examples of good navigation files
|
||||
|
||||
**Last Updated**: 2026-01-08
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Category Navigation (Function-Based)
|
||||
|
||||
**File**: `openagents-repo/navigation.md`
|
||||
|
||||
**Pattern**: Function-Based (repository-specific)
|
||||
|
||||
**Token count**: ~250 tokens
|
||||
|
||||
```markdown
|
||||
# OpenAgents Control Repository Navigation
|
||||
|
||||
**Purpose**: Navigate OpenAgents Control repository context
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/
|
||||
├── navigation.md
|
||||
├── quick-start.md
|
||||
│
|
||||
├── core-concepts/
|
||||
│ ├── agent-architecture.md
|
||||
│ ├── eval-framework.md
|
||||
│ └── registry-system.md
|
||||
│
|
||||
├── guides/
|
||||
│ ├── adding-agent.md
|
||||
│ ├── testing-agent.md
|
||||
│ └── debugging-issues.md
|
||||
│
|
||||
├── lookup/
|
||||
│ ├── commands.md
|
||||
│ └── file-locations.md
|
||||
│
|
||||
└── errors/
|
||||
└── tool-permission-errors.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **New here** | `quick-start.md` |
|
||||
| **Add agent** | `guides/adding-agent.md` |
|
||||
| **Test agent** | `guides/testing-agent.md` |
|
||||
| **Debug issue** | `guides/debugging-issues.md` |
|
||||
| **Find files** | `lookup/file-locations.md` |
|
||||
| **Fix error** | `errors/tool-permission-errors.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Core Concepts** → Foundational understanding (agents, evals, registry)
|
||||
**Guides** → Step-by-step workflows
|
||||
**Lookup** → Quick reference tables
|
||||
**Errors** → Troubleshooting
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- ✅ Token-efficient (~250 tokens)
|
||||
- ✅ ASCII tree shows structure
|
||||
- ✅ Quick routes for common tasks
|
||||
- ✅ Organized by information type
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Category Navigation (Concern-Based)
|
||||
|
||||
**File**: `development/navigation.md`
|
||||
|
||||
**Pattern**: Concern-Based (multi-technology)
|
||||
|
||||
**Token count**: ~280 tokens
|
||||
|
||||
```markdown
|
||||
# Development Navigation
|
||||
|
||||
**Purpose**: Software development across all stacks
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
development/
|
||||
├── navigation.md
|
||||
├── ui-navigation.md # Specialized
|
||||
├── backend-navigation.md # Specialized
|
||||
│
|
||||
├── principles/
|
||||
│ ├── clean-code.md
|
||||
│ └── api-design.md
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── react/
|
||||
│ └── vue/
|
||||
│
|
||||
├── backend/
|
||||
│ ├── api-patterns/
|
||||
│ ├── nodejs/
|
||||
│ └── authentication/
|
||||
│
|
||||
└── data/
|
||||
├── sql-patterns/
|
||||
└── orm-patterns/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **UI/Frontend** | `ui-navigation.md` |
|
||||
| **Backend/API** | `backend-navigation.md` |
|
||||
| **Clean code** | `principles/clean-code.md` |
|
||||
| **API design** | `principles/api-design.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Concern
|
||||
|
||||
**Principles** → Universal development practices
|
||||
**Frontend** → React, Vue, state management
|
||||
**Backend** → APIs, Node.js, Python, auth
|
||||
**Data** → SQL, NoSQL, ORMs
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- ✅ Token-efficient (~280 tokens)
|
||||
- ✅ Shows specialized navigation files
|
||||
- ✅ Organized by concern (frontend, backend, data)
|
||||
- ✅ Points to specialized navigation for complex workflows
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Specialized Navigation
|
||||
|
||||
**File**: `development/ui-navigation.md`
|
||||
|
||||
**Pattern**: Cross-cutting (spans multiple categories)
|
||||
|
||||
**Token count**: ~270 tokens
|
||||
|
||||
```markdown
|
||||
# UI Development Navigation
|
||||
|
||||
**Scope**: Frontend code + visual design
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
Frontend Code (development/frontend/):
|
||||
├── react/
|
||||
│ ├── hooks-patterns.md
|
||||
│ ├── component-architecture.md
|
||||
│ └── tanstack/
|
||||
│ ├── query-patterns.md
|
||||
│ └── router-patterns.md
|
||||
└── vue/
|
||||
|
||||
Visual Design (ui/web/):
|
||||
├── animation-patterns.md
|
||||
├── ui-styling-standards.md
|
||||
└── design-systems.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **React patterns** | `frontend/react/hooks-patterns.md` |
|
||||
| **TanStack Query** | `frontend/react/tanstack/query-patterns.md` |
|
||||
| **Animations** | `../../ui/web/animation-patterns.md` |
|
||||
| **Styling** | `../../ui/web/ui-styling-standards.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Framework
|
||||
|
||||
**React** → `frontend/react/`
|
||||
**Vue** → `frontend/vue/`
|
||||
**TanStack** → `frontend/react/tanstack/`
|
||||
|
||||
## By Concern
|
||||
|
||||
**Code patterns** → `development/frontend/`
|
||||
**Visual design** → `ui/web/`
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- ✅ Token-efficient (~270 tokens)
|
||||
- ✅ Spans multiple categories (development/ + ui/)
|
||||
- ✅ Task-focused (UI development)
|
||||
- ✅ Shows both code and design paths
|
||||
|
||||
---
|
||||
|
||||
## Example 4: Subcategory Navigation
|
||||
|
||||
**File**: `development/backend/navigation.md`
|
||||
|
||||
**Pattern**: Concern-based subcategory
|
||||
|
||||
**Token count**: ~240 tokens
|
||||
|
||||
```markdown
|
||||
# Backend Development Navigation
|
||||
|
||||
**Scope**: Server-side, APIs, databases, auth
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
backend/
|
||||
├── navigation.md
|
||||
│
|
||||
├── api-patterns/
|
||||
│ ├── rest-design.md
|
||||
│ ├── graphql-design.md
|
||||
│ └── grpc-patterns.md
|
||||
│
|
||||
├── nodejs/
|
||||
│ ├── express-patterns.md
|
||||
│ └── fastify-patterns.md
|
||||
│
|
||||
├── python/
|
||||
│ └── fastapi-patterns.md
|
||||
│
|
||||
└── authentication/
|
||||
├── jwt-patterns.md
|
||||
└── oauth-patterns.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **REST API** | `api-patterns/rest-design.md` |
|
||||
| **GraphQL** | `api-patterns/graphql-design.md` |
|
||||
| **Node.js** | `nodejs/express-patterns.md` |
|
||||
| **Auth (JWT)** | `authentication/jwt-patterns.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Approach
|
||||
|
||||
**REST** → `api-patterns/rest-design.md`
|
||||
**GraphQL** → `api-patterns/graphql-design.md`
|
||||
|
||||
## By Language
|
||||
|
||||
**Node.js** → `nodejs/`
|
||||
**Python** → `python/`
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- ✅ Token-efficient (~240 tokens)
|
||||
- ✅ Organized by approach first (REST, GraphQL)
|
||||
- ✅ Then by tech (Node.js, Python)
|
||||
- ✅ Functional concerns separate (authentication/)
|
||||
|
||||
---
|
||||
|
||||
## Example 5: Full-Stack Navigation
|
||||
|
||||
**File**: `development/fullstack-navigation.md`
|
||||
|
||||
**Pattern**: Workflow-focused
|
||||
|
||||
**Token count**: ~300 tokens
|
||||
|
||||
```markdown
|
||||
# Full-Stack Development Navigation
|
||||
|
||||
**Scope**: End-to-end application development
|
||||
|
||||
---
|
||||
|
||||
## Common Stacks
|
||||
|
||||
### MERN (MongoDB, Express, React, Node)
|
||||
```
|
||||
Frontend: development/frontend/react/
|
||||
Backend: development/backend/nodejs/express-patterns.md
|
||||
Data: development/data/nosql-patterns/mongodb.md
|
||||
API: development/backend/api-patterns/rest-design.md
|
||||
```
|
||||
|
||||
### T3 Stack (Next.js, tRPC, Prisma, Tailwind)
|
||||
```
|
||||
Frontend: development/frontend/react/ + ui/web/ui-styling-standards.md
|
||||
Backend: development/backend/nodejs/ + api-patterns/trpc-patterns.md
|
||||
Data: development/data/orm-patterns/prisma.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Layer | Navigate To |
|
||||
|-------|-------------|
|
||||
| **Frontend** | `ui-navigation.md` |
|
||||
| **Backend** | `backend-navigation.md` |
|
||||
| **Data** | `data/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
**New API endpoint**:
|
||||
1. `principles/api-design.md` (principles)
|
||||
2. `backend/api-patterns/rest-design.md` (approach)
|
||||
3. `backend/nodejs/express-patterns.md` (implementation)
|
||||
|
||||
**New React feature**:
|
||||
1. `frontend/react/component-architecture.md` (structure)
|
||||
2. `frontend/react/hooks-patterns.md` (logic)
|
||||
3. `ui/web/ui-styling-standards.md` (styling)
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- ✅ Token-efficient (~300 tokens)
|
||||
- ✅ Shows common tech stacks
|
||||
- ✅ Workflow-focused (how to build features)
|
||||
- ✅ Points to layer-specific navigation
|
||||
|
||||
---
|
||||
|
||||
## Example 6: Minimal Navigation
|
||||
|
||||
**File**: `content/navigation.md`
|
||||
|
||||
**Pattern**: Simple category (few files)
|
||||
|
||||
**Token count**: ~150 tokens
|
||||
|
||||
```markdown
|
||||
# Content Navigation
|
||||
|
||||
**Purpose**: Copywriting and content creation
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
content/
|
||||
├── navigation.md
|
||||
├── copywriting-frameworks.md
|
||||
└── tone-voice.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **Write copy** | `copywriting-frameworks.md` |
|
||||
| **Set tone** | `tone-voice.md` |
|
||||
|
||||
---
|
||||
|
||||
## Files
|
||||
|
||||
**copywriting-frameworks.md** → AIDA, PAS, persuasive writing
|
||||
**tone-voice.md** → Brand voice, tone guidelines
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- ✅ Token-efficient (~150 tokens)
|
||||
- ✅ Simple structure (only 2 files)
|
||||
- ✅ No unnecessary complexity
|
||||
- ✅ Clear and scannable
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns (What NOT to Do)
|
||||
|
||||
### ❌ Too Verbose
|
||||
|
||||
```markdown
|
||||
# Development Navigation
|
||||
|
||||
**Purpose**: This comprehensive navigation file is designed to help you navigate the extensive collection of software development patterns, standards, and best practices that we have carefully curated across all technology stacks including frontend frameworks like React and Vue, backend technologies such as Node.js and Python, database systems both SQL and NoSQL, and infrastructure tools for deployment and operations.
|
||||
|
||||
## Introduction
|
||||
|
||||
The development category represents a significant portion of our context system...
|
||||
|
||||
[Continues for 800+ tokens]
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- ❌ 800+ tokens (should be 200-300)
|
||||
- ❌ Verbose explanations (should be concise)
|
||||
- ❌ Hard to scan (should use tables/trees)
|
||||
|
||||
---
|
||||
|
||||
### ❌ Missing Structure
|
||||
|
||||
```markdown
|
||||
# Development Navigation
|
||||
|
||||
Here are the files:
|
||||
- clean-code.md
|
||||
- api-design.md
|
||||
- react-patterns.md
|
||||
- express-patterns.md
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- ❌ No ASCII tree (hard to see hierarchy)
|
||||
- ❌ No quick routes (hard to find tasks)
|
||||
- ❌ No organization (just a list)
|
||||
|
||||
---
|
||||
|
||||
### ❌ Too Detailed
|
||||
|
||||
```markdown
|
||||
# Development Navigation
|
||||
|
||||
## React Patterns
|
||||
|
||||
### Hooks
|
||||
React hooks allow you to use state and lifecycle features in functional components. The most common hooks are:
|
||||
|
||||
1. useState - For managing component state
|
||||
- Syntax: const [state, setState] = useState(initialValue)
|
||||
- Example: const [count, setCount] = useState(0)
|
||||
|
||||
2. useEffect - For side effects
|
||||
[... continues with full documentation]
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- ❌ Contains file contents (should just point to files)
|
||||
- ❌ Duplicates information (should reference, not repeat)
|
||||
- ❌ Too detailed (navigation, not documentation)
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
### ✅ Good Navigation Files
|
||||
|
||||
1. **Token-efficient** (200-300 tokens)
|
||||
2. **Scannable** (ASCII trees, tables)
|
||||
3. **Task-focused** (quick routes)
|
||||
4. **Organized** (by concern/type)
|
||||
5. **Concise** (3-5 word descriptions)
|
||||
|
||||
### ❌ Bad Navigation Files
|
||||
|
||||
1. **Verbose** (500+ tokens)
|
||||
2. **Hard to scan** (paragraphs)
|
||||
3. **Unfocused** (no clear routes)
|
||||
4. **Unorganized** (just lists)
|
||||
5. **Detailed** (duplicates content)
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `../guides/navigation-design.md` - How to create navigation files
|
||||
- `../guides/organizing-context.md` - How to choose organizational pattern
|
||||
- `../standards/mvi.md` - Minimal Viable Information principle
|
||||
122
.opencode/context/core/context-system/guides/compact.md
Normal file
122
.opencode/context/core/context-system/guides/compact.md
Normal file
@@ -0,0 +1,122 @@
|
||||
<!-- Context: core/compact | Priority: high | Version: 1.1 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Compaction (Minimization)
|
||||
|
||||
**Purpose**: Compress verbose content into minimal viable information
|
||||
|
||||
**Last Updated**: 2026-02-15
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
|
||||
Transform verbose explanations → core concepts following MVI principle.
|
||||
|
||||
**Formula**: Verbose Content → Core Concept (1-3 sentences) → Key Points (3-5 bullets) → Minimal Example (<10 lines) → Reference Link → Compact File
|
||||
|
||||
---
|
||||
|
||||
## 5 Compression Techniques
|
||||
|
||||
### 1. Extract Core Concept
|
||||
**From**: Paragraphs → **To**: 1-3 sentences
|
||||
**Rule**: If you can't explain it in 3 sentences, simplify further.
|
||||
|
||||
### 2. Bulletize Key Points
|
||||
**From**: Long paragraphs → **To**: 3-5 bullet points
|
||||
**Rule**: Each bullet = one key fact. No sub-bullets.
|
||||
|
||||
### 3. Minimize Examples
|
||||
**From**: Full implementations → **To**: Smallest working example (<10 lines)
|
||||
**Rule**: Show the simplest case. Link to full examples.
|
||||
|
||||
### 4. Replace Repetition with References
|
||||
**From**: Same info repeated → **To**: Define once, reference with links
|
||||
**Rule**: Say it once in concepts/, reference everywhere else.
|
||||
|
||||
### 5. Convert Prose to Tables
|
||||
**From**: Paragraphs listing things → **To**: Scannable tables
|
||||
**Rule**: If listing >3 items, use a table or bullets.
|
||||
|
||||
---
|
||||
|
||||
## Compaction Checklist
|
||||
|
||||
- [ ] Core concept is 1-3 sentences?
|
||||
- [ ] Key points are 3-5 bullets (no sub-bullets)?
|
||||
- [ ] Example is <10 lines of code?
|
||||
- [ ] No repeated explanations?
|
||||
- [ ] Reference link added for deep dive?
|
||||
- [ ] File is under line limit?
|
||||
- [ ] Can be scanned in <30 seconds?
|
||||
|
||||
---
|
||||
|
||||
## Common Bloat Patterns to Remove
|
||||
|
||||
| Bloat Type | ❌ Avoid | ✅ Use Instead |
|
||||
|------------|---------|---------------|
|
||||
| Over-Explaining | "This is important because it allows you to manage state in a more efficient way..." | "Manages state efficiently" |
|
||||
| Historical Context | "Before React 16.8, we used class components..." | Skip history unless critical |
|
||||
| Multiple Examples | Example 1, 2, 3, 4... | ONE simple example + link |
|
||||
| Implementation Details | "The internal implementation uses a fiber architecture..." | Skip internals, show usage |
|
||||
|
||||
---
|
||||
|
||||
## Target Line Counts
|
||||
|
||||
| File Type | Target | Max |
|
||||
|-----------|--------|-----|
|
||||
| Concept | 40-60 | 100 |
|
||||
| Example | 30-50 | 80 |
|
||||
| Guide | 60-100 | 150 |
|
||||
| Lookup | 20-40 | 100 |
|
||||
| Error | 50-80 | 150 |
|
||||
|
||||
**Philosophy**: If you hit max lines, split into multiple files or reference external docs.
|
||||
|
||||
---
|
||||
|
||||
## The 30-Second Rule
|
||||
|
||||
<rule id="thirty_second_rule" enforcement="strict">
|
||||
Every context file must be scannable in <30 seconds.
|
||||
</rule>
|
||||
|
||||
**Test**: Can someone unfamiliar explain it back in 30 seconds?
|
||||
|
||||
---
|
||||
|
||||
## Quick Example
|
||||
|
||||
**Before (150 lines)**: Long authentication system explanation with edge cases, examples, etc.
|
||||
|
||||
**After (45 lines)**:
|
||||
```markdown
|
||||
# Concept: Authentication
|
||||
|
||||
**Core Idea**: JWT-based stateless auth. Token in httpOnly cookie, verified on every request.
|
||||
|
||||
**Key Points**:
|
||||
- Token has userId + role claims
|
||||
- Expires in 1 hour (refresh token for renewal)
|
||||
- Stored in httpOnly cookie (XSS protection)
|
||||
- Verified via middleware on protected routes
|
||||
|
||||
**Quick Example**:
|
||||
```js
|
||||
const token = jwt.sign({ userId: 123 }, SECRET, { expiresIn: '1h' })
|
||||
res.cookie('auth', token, { httpOnly: true })
|
||||
```
|
||||
|
||||
**Reference**: https://docs.company.com/auth
|
||||
**Related**: examples/jwt-auth.md, errors/auth-errors.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- mvi.md - MVI principle
|
||||
- harvest.md - When to compact
|
||||
- templates.md - Standard formats
|
||||
173
.opencode/context/core/context-system/guides/creation.md
Normal file
173
.opencode/context/core/context-system/guides/creation.md
Normal file
@@ -0,0 +1,173 @@
|
||||
<!-- Context: core/creation | Priority: high | Version: 1.1 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context File Creation Standards
|
||||
|
||||
**Purpose**: Ensure all context files follow the same format and structure
|
||||
|
||||
**Last Updated**: 2026-02-15
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="size_limit">Files MUST be under line limits (see below)</rule>
|
||||
<rule id="mvi_required">All files MUST follow MVI principle</rule>
|
||||
<rule id="function_placement">Files MUST be in correct folder</rule>
|
||||
<rule id="navigation_update">MUST update navigation.md when creating files</rule>
|
||||
</critical_rules>
|
||||
|
||||
---
|
||||
|
||||
## Creation Workflow
|
||||
|
||||
### 1. Determine Function
|
||||
Ask: Is this a concept, example, guide, lookup, or error?
|
||||
→ Place in correct folder
|
||||
|
||||
### 2. Apply Template
|
||||
Use standard template for file type (see templates.md)
|
||||
|
||||
### 3. Apply MVI
|
||||
- Core: 1-3 sentences
|
||||
- Key points: 3-5 bullets
|
||||
- Example: <10 lines
|
||||
- Reference: Link to docs
|
||||
|
||||
### 4. Validate Size
|
||||
Ensure file under limit. If not, split or reference external.
|
||||
|
||||
### 5. Add Cross-References
|
||||
Link to related concepts/, examples/, guides/, errors/
|
||||
|
||||
### 6. Update Navigation
|
||||
Add entry to navigation.md in parent directory
|
||||
|
||||
---
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
| Type | Format | Example |
|
||||
|------|--------|---------|
|
||||
| Concept | `{concept-name}.md` | `authentication.md` |
|
||||
| Example | `{example-name}.md` | `jwt-example.md` |
|
||||
| Guide | `{action-name}.md` | `creating-agents.md` |
|
||||
| Lookup | `{reference-name}.md` | `commands.md` |
|
||||
| Error | `{error-category}.md` | `auth-errors.md` |
|
||||
|
||||
**Rules**:
|
||||
- Use kebab-case (lowercase with hyphens)
|
||||
- Be descriptive but concise
|
||||
- Avoid redundant category in name (not `concept-authentication.md`)
|
||||
|
||||
---
|
||||
|
||||
## Standard Metadata (Frontmatter)
|
||||
|
||||
```html
|
||||
<!-- Context: {path} | Priority: {level} | Version: {X.Y} | Updated: {YYYY-MM-DD} -->
|
||||
```
|
||||
|
||||
**Priority levels**: critical, high, medium, low
|
||||
|
||||
**When to use**:
|
||||
- critical: Core system files, always needed
|
||||
- high: Frequently referenced, important patterns
|
||||
- medium: Useful but not essential
|
||||
- low: Nice-to-have, rarely needed
|
||||
|
||||
---
|
||||
|
||||
## File Size Limits
|
||||
|
||||
| File Type | Max Lines |
|
||||
|-----------|-----------|
|
||||
| Concept | 100 |
|
||||
| Example | 80 |
|
||||
| Guide | 150 |
|
||||
| Lookup | 100 |
|
||||
| Error | 150 |
|
||||
|
||||
**Enforcement**: Strict. If over limit, split into multiple files or reference external docs.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference Guidelines
|
||||
|
||||
**Format**: `See {type}/{filename}.md for {what}`
|
||||
|
||||
**Examples**:
|
||||
- `See concepts/authentication.md for JWT details`
|
||||
- `See examples/jwt-example.md for working code`
|
||||
- `See errors/auth-errors.md for troubleshooting`
|
||||
|
||||
**Best practices**:
|
||||
- Link to related concepts
|
||||
- Link to examples from guides
|
||||
- Link to errors from guides
|
||||
- Create bidirectional links when relevant
|
||||
|
||||
---
|
||||
|
||||
## Navigation Update Process
|
||||
|
||||
When creating a file, update parent `navigation.md`:
|
||||
|
||||
```markdown
|
||||
| File | Description | Priority |
|
||||
|------|-------------|----------|
|
||||
| new-file.md | Brief description | high |
|
||||
```
|
||||
|
||||
**Keep navigation**:
|
||||
- Alphabetical within priority groups
|
||||
- Grouped by priority (critical → high → medium → low)
|
||||
- Descriptions <10 words
|
||||
|
||||
---
|
||||
|
||||
## Validation Before Commit
|
||||
|
||||
- [ ] File under line limit?
|
||||
- [ ] MVI format applied?
|
||||
- [ ] Frontmatter added?
|
||||
- [ ] In correct folder?
|
||||
- [ ] Navigation.md updated?
|
||||
- [ ] Cross-references added?
|
||||
- [ ] Can be scanned in <30 seconds?
|
||||
|
||||
---
|
||||
|
||||
## Common Creation Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| File too long | Split into multiple files or compress |
|
||||
| Missing frontmatter | Add HTML comment at top |
|
||||
| Wrong folder | Move to correct function folder |
|
||||
| No cross-references | Add links to related files |
|
||||
| Verbose explanations | Apply MVI compression |
|
||||
| Missing from navigation | Update navigation.md |
|
||||
|
||||
---
|
||||
|
||||
## Template Selection
|
||||
|
||||
| File Type | Template | Use When |
|
||||
|-----------|----------|----------|
|
||||
| Concept | Concept template | Explaining what something is |
|
||||
| Example | Example template | Showing working code |
|
||||
| Guide | Guide template | Step-by-step instructions |
|
||||
| Lookup | Lookup template | Quick reference data |
|
||||
| Error | Error template | Troubleshooting issues |
|
||||
|
||||
See templates.md for full templates.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- templates.md - File templates
|
||||
- mvi.md - MVI principle
|
||||
- compact.md - Compression techniques
|
||||
- structure.md - Directory structure
|
||||
@@ -0,0 +1,133 @@
|
||||
<!-- Context: core/navigation-design-basics | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Designing Navigation Files
|
||||
|
||||
**Purpose**: How to create token-efficient, scannable navigation files
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Understand MVI principle (`context-system/standards/mvi.md`)
|
||||
- Know your category's organizational pattern
|
||||
- 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
|
||||
|
||||
**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
|
||||
**Include**: ✅ Paths | ✅ Brief descriptions (3-5 words) | ✅ When to use
|
||||
**Exclude**: ❌ File contents | ❌ Detailed explanations | ❌ Duplicates
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Determine Navigation Type
|
||||
|
||||
| Type | Path | Purpose |
|
||||
|------|------|---------|
|
||||
| Category-level | `{category}/navigation.md` | Overview of category |
|
||||
| Subcategory-level | `{category}/{sub}/navigation.md` | Files in subcategory |
|
||||
| Specialized | `{category}/{domain}-navigation.md` | Cross-cutting (e.g., ui-navigation.md) |
|
||||
|
||||
### 2. Create Structure Section
|
||||
|
||||
```markdown
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/
|
||||
├── navigation.md
|
||||
├── quick-start.md
|
||||
├── concepts/
|
||||
│ └── subagent-testing-modes.md
|
||||
├── guides/
|
||||
│ ├── adding-agent.md
|
||||
│ └── testing-agent.md
|
||||
└── lookup/
|
||||
└── commands.md
|
||||
```
|
||||
```
|
||||
|
||||
**Token count**: ~50-100 tokens
|
||||
|
||||
### 3. Create Quick Routes Table
|
||||
|
||||
```markdown
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **Add agent** | `guides/adding-agent.md` |
|
||||
| **Test agent** | `guides/testing-agent.md` |
|
||||
| **Find files** | `lookup/file-locations.md` |
|
||||
```
|
||||
|
||||
**Guidelines**: Use **bold** for tasks | Relative paths | 5-10 common tasks
|
||||
|
||||
### 4. Create By Concern/Type Sections
|
||||
|
||||
```markdown
|
||||
## By Type
|
||||
|
||||
**Concepts** → Core ideas and principles
|
||||
**Guides** → Step-by-step workflows
|
||||
**Lookup** → Quick reference tables
|
||||
**Errors** → Troubleshooting
|
||||
```
|
||||
|
||||
### 5. Add Related Context (Optional)
|
||||
|
||||
```markdown
|
||||
## Related Context
|
||||
|
||||
- **Core Standards** → `../core/standards/navigation.md`
|
||||
```
|
||||
|
||||
### 6. Validate Token Count
|
||||
|
||||
**Target**: 200-300 tokens
|
||||
|
||||
```bash
|
||||
wc -w navigation.md # Multiply by 1.3 for token estimate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Token count 200-300?
|
||||
- [ ] ASCII tree included?
|
||||
- [ ] Quick routes table?
|
||||
- [ ] By concern/type section?
|
||||
- [ ] Relative paths?
|
||||
- [ ] Descriptions 3-5 words?
|
||||
- [ ] No duplicate information?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `navigation-templates.md` - Ready-to-use templates
|
||||
- `../standards/mvi.md` - MVI principle
|
||||
- `../examples/navigation-examples.md` - More examples
|
||||
@@ -0,0 +1,185 @@
|
||||
<!-- Context: core/navigation-templates | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Navigation File Templates
|
||||
|
||||
**Purpose**: Ready-to-use templates for navigation files
|
||||
|
||||
---
|
||||
|
||||
## Category Navigation 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}` |
|
||||
| **{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
|
||||
|
||||
```markdown
|
||||
# {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
|
||||
|
||||
---
|
||||
|
||||
## Good Example (Token-Efficient)
|
||||
|
||||
```markdown
|
||||
# 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 Example (Too Verbose)
|
||||
|
||||
```markdown
|
||||
# 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...
|
||||
|
||||
[... continues for 500+ tokens]
|
||||
```
|
||||
|
||||
**Token count**: 500+ tokens ❌
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Too many tokens | Remove verbose descriptions, shorten entries |
|
||||
| Hard to scan | Use tables instead of paragraphs |
|
||||
| Missing files | Add to structure and quick routes |
|
||||
| Unclear paths | Use relative paths, add brief descriptions |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `navigation-design-basics.md` - Core principles and steps
|
||||
- `../standards/mvi.md` - MVI principle
|
||||
- `../examples/navigation-examples.md` - More examples
|
||||
@@ -0,0 +1,152 @@
|
||||
<!-- Context: core/organizing-context | Priority: high | Version: 1.1 | Updated: 2026-02-15 -->
|
||||
|
||||
# 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
|
||||
```bash
|
||||
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
|
||||
573
.opencode/context/core/context-system/guides/workflows.md
Normal file
573
.opencode/context/core/context-system/guides/workflows.md
Normal file
@@ -0,0 +1,573 @@
|
||||
<!-- Context: core/workflows | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Operation Workflows
|
||||
|
||||
**Purpose**: Detailed interactive workflows for all context operations
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## Extract Workflow (Interactive)
|
||||
|
||||
### Stage 1: Read Source
|
||||
```
|
||||
/context extract from https://react.dev/hooks
|
||||
↓
|
||||
Agent: "Reading source (8,500 lines)...
|
||||
Analyzing content for extractable items..."
|
||||
```
|
||||
|
||||
### Stage 2: Analyze & Categorize
|
||||
```
|
||||
Agent: "Analysis complete.
|
||||
|
||||
Found 12 core concepts:
|
||||
- useState (state management)
|
||||
- useEffect (side effects)
|
||||
- useContext (context consumption)
|
||||
... (9 more)
|
||||
|
||||
Found 8 common errors:
|
||||
- Hooks called conditionally
|
||||
- Hooks in loops
|
||||
- Hooks outside components
|
||||
... (5 more)
|
||||
|
||||
Found 3 workflows:
|
||||
- Setting up custom hooks
|
||||
- Debugging hook issues
|
||||
- Testing components with hooks"
|
||||
```
|
||||
|
||||
### Stage 3: Select Category (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Which category should this go in?
|
||||
[1] development/
|
||||
[2] core/
|
||||
[3] Create new category: ___
|
||||
|
||||
Select items to extract:
|
||||
Concepts:
|
||||
✓ [A] useState
|
||||
✓ [B] useEffect
|
||||
✓ [C] useContext
|
||||
... [D-L] (9 more)
|
||||
|
||||
Errors:
|
||||
✓ [M] Hooks called conditionally
|
||||
✓ [N] Hooks in loops
|
||||
... [O-T] (6 more)
|
||||
|
||||
Guides:
|
||||
✓ [U] Setting up custom hooks
|
||||
✓ [V] Debugging hook issues
|
||||
✓ [W] Testing components
|
||||
|
||||
Type items (A B M or 'all') + category (1/2/3):"
|
||||
|
||||
User: "all 1"
|
||||
```
|
||||
|
||||
### Stage 4: Preview (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Would create in development/:
|
||||
|
||||
concepts/use-state.md (45 lines)
|
||||
concepts/use-effect.md (52 lines)
|
||||
concepts/use-context.md (38 lines)
|
||||
... (9 more concept files)
|
||||
|
||||
errors/react-hooks-errors.md (124 lines)
|
||||
- 8 errors grouped in one file
|
||||
|
||||
guides/custom-hooks.md (87 lines)
|
||||
guides/debugging-hooks.md (65 lines)
|
||||
guides/testing-hooks.md (72 lines)
|
||||
|
||||
Total: 15 files, ~850 lines
|
||||
|
||||
Preview specific file? (type filename or 'skip')
|
||||
Approve? (yes/no/preview):"
|
||||
|
||||
User: "preview use-state.md"
|
||||
|
||||
Agent: [Shows first 30 lines of use-state.md]
|
||||
|
||||
User: "yes"
|
||||
```
|
||||
|
||||
### Stage 5-7: Create, Update, Report
|
||||
```
|
||||
Agent: "Creating files...
|
||||
✅ Extracted 20 items into development/
|
||||
📄 Created 15 files
|
||||
📊 Updated development/README.md
|
||||
|
||||
Files created:
|
||||
- development/concepts/ (12 files)
|
||||
- development/errors/react-hooks-errors.md
|
||||
- development/guides/ (3 files)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Organize Workflow (Interactive)
|
||||
|
||||
### Stage 1-2: Scan & Categorize
|
||||
```
|
||||
/context organize development/
|
||||
↓
|
||||
Agent: "Scanning development/ (23 files, flat structure)...
|
||||
|
||||
Categorizing by function..."
|
||||
```
|
||||
|
||||
### Stage 3: Resolve Conflicts (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Categorization plan:
|
||||
|
||||
Clear categorization (18 files):
|
||||
concepts/ (8 files):
|
||||
✓ authentication.md → concepts/authentication.md
|
||||
✓ state-management.md → concepts/state-management.md
|
||||
✓ caching.md → concepts/caching.md
|
||||
... (5 more)
|
||||
|
||||
examples/ (5 files):
|
||||
✓ jwt-example.md → examples/jwt-example.md
|
||||
✓ hooks-example.md → examples/hooks-example.md
|
||||
... (3 more)
|
||||
|
||||
guides/ (5 files):
|
||||
✓ setting-up-auth.md → guides/setting-up-auth.md
|
||||
... (4 more)
|
||||
|
||||
Ambiguous files (5 - need your input):
|
||||
|
||||
[?] api-design.md (contains concepts AND step-by-step guide)
|
||||
Content: Explains REST principles (concept) + how to design endpoints (guide)
|
||||
→ [A] Split into:
|
||||
concepts/api-design.md (REST principles)
|
||||
guides/api-design-guide.md (how to design)
|
||||
→ [B] Keep as concepts/api-design.md (primary: concepts)
|
||||
→ [C] Keep as guides/api-design.md (primary: guide)
|
||||
|
||||
[?] error-handling.md (contains guide AND error examples)
|
||||
Content: How to handle errors (guide) + common error patterns (errors)
|
||||
→ [D] Split into:
|
||||
guides/error-handling.md (how to handle)
|
||||
errors/common-errors.md (error patterns)
|
||||
→ [E] Keep as guides/error-handling.md
|
||||
→ [F] Keep as errors/error-handling.md
|
||||
|
||||
[?] testing-patterns.md (contains concepts AND examples)
|
||||
→ [G] Split into concepts/ + examples/
|
||||
→ [H] Keep as concepts/testing-patterns.md
|
||||
→ [I] Keep as examples/testing-patterns.md
|
||||
|
||||
Conflicts (2):
|
||||
|
||||
[!] authentication.md → concepts/auth.md
|
||||
Target concepts/auth.md already exists (120 lines)
|
||||
→ [J] Merge authentication.md into existing auth.md
|
||||
→ [K] Rename to concepts/authentication-v2.md
|
||||
→ [L] Skip (keep flat)
|
||||
|
||||
[!] jwt-example.md → examples/jwt.md
|
||||
Target examples/jwt.md already exists (65 lines)
|
||||
→ [M] Merge jwt-example.md into existing jwt.md
|
||||
→ [N] Rename to examples/jwt-example-v2.md
|
||||
→ [O] Skip (keep flat)
|
||||
|
||||
Select resolutions (A D G J M or 'auto' for AI suggestions):"
|
||||
|
||||
User: "A D G J M"
|
||||
```
|
||||
|
||||
### Stage 4: Preview (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Preview of changes:
|
||||
|
||||
CREATE directories:
|
||||
development/concepts/
|
||||
development/examples/
|
||||
development/guides/
|
||||
development/lookup/
|
||||
development/errors/
|
||||
|
||||
MOVE files (18):
|
||||
authentication.md → concepts/authentication.md
|
||||
state-management.md → concepts/state-management.md
|
||||
... (16 more)
|
||||
|
||||
SPLIT files (3):
|
||||
api-design.md →
|
||||
concepts/api-design.md (concepts section)
|
||||
guides/api-design-guide.md (guide section)
|
||||
|
||||
error-handling.md →
|
||||
guides/error-handling.md (guide section)
|
||||
errors/common-errors.md (error examples)
|
||||
|
||||
testing-patterns.md →
|
||||
concepts/testing-patterns.md (concepts)
|
||||
examples/testing-examples.md (examples)
|
||||
|
||||
MERGE files (2):
|
||||
authentication.md → concepts/auth.md (merge content)
|
||||
jwt-example.md → examples/jwt.md (merge content)
|
||||
|
||||
UPDATE:
|
||||
development/README.md (create navigation tables)
|
||||
Fix 47 internal references
|
||||
|
||||
Dry-run? (yes/no/show-diff):"
|
||||
|
||||
User: "dry-run"
|
||||
|
||||
Agent: [Simulates changes without executing, shows what would happen]
|
||||
|
||||
User: "yes"
|
||||
```
|
||||
|
||||
### Stage 5-8: Backup, Execute, Update, Report
|
||||
```
|
||||
Agent: "Creating backup...
|
||||
💾 Backup: .tmp/backup/organize-development-2026-01-06-143022/
|
||||
|
||||
Executing changes...
|
||||
✅ Organized 23 files into function folders
|
||||
📁 Created 5 new folders
|
||||
🔀 Split 3 ambiguous files
|
||||
🔗 Fixed 47 references
|
||||
📊 Updated development/README.md
|
||||
|
||||
Rollback available at: .tmp/backup/organize-development-2026-01-06-143022/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Update Workflow (Interactive)
|
||||
|
||||
### Stage 1: Identify Changes (APPROVAL REQUIRED)
|
||||
```
|
||||
/context update for Next.js 15
|
||||
↓
|
||||
Agent: "What changed in Next.js 15?
|
||||
[A] API changes
|
||||
[B] Deprecations
|
||||
[C] New features
|
||||
[D] Breaking changes
|
||||
[E] Other (describe)
|
||||
|
||||
Select all that apply (A B C D or describe):"
|
||||
|
||||
User: "A C D"
|
||||
|
||||
Agent: "Please describe the changes:
|
||||
API changes: ___
|
||||
New features: ___
|
||||
Breaking changes: ___"
|
||||
|
||||
User: "API changes: App router is now default
|
||||
New features: New metadata API, Server Actions stable
|
||||
Breaking changes: Pages router requires explicit opt-in"
|
||||
```
|
||||
|
||||
### Stage 2: Find Affected Files
|
||||
```
|
||||
Agent: "Searching for files referencing Next.js...
|
||||
|
||||
Found 5 files with 17 references:
|
||||
📄 concepts/routing.md (3 references, 145 lines)
|
||||
📄 examples/app-router-example.md (7 references, 78 lines)
|
||||
📄 guides/setting-up-nextjs.md (2 references, 132 lines)
|
||||
📄 errors/nextjs-errors.md (1 reference, 98 lines)
|
||||
📄 lookup/nextjs-commands.md (4 references, 54 lines)
|
||||
|
||||
Total impact: 17 references across 5 files"
|
||||
```
|
||||
|
||||
### Stage 3: Preview Changes (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Proposed updates:
|
||||
|
||||
━━━ concepts/routing.md ━━━
|
||||
|
||||
Line 15:
|
||||
- App router is optional (use pages/ or app/ directory)
|
||||
+ App router is now default in Next.js 15 (pages/ still supported with opt-in)
|
||||
|
||||
Line 42:
|
||||
+ ## Metadata API (New in v15)
|
||||
+
|
||||
+ Next.js 15 introduces new metadata API for SEO optimization.
|
||||
+ Replaces Head component with metadata exports.
|
||||
|
||||
Line 87:
|
||||
- **Reference**: https://nextjs.org/docs/app
|
||||
+ **Reference**: https://nextjs.org/docs/15/app
|
||||
|
||||
━━━ examples/app-router-example.md ━━━
|
||||
|
||||
Line 8:
|
||||
- // Optional: use app router
|
||||
+ // Default in Next.js 15+
|
||||
|
||||
Line 23:
|
||||
+ // New: Metadata API
|
||||
+ export const metadata = {
|
||||
+ title: 'My App',
|
||||
+ description: 'App description'
|
||||
+ }
|
||||
|
||||
━━━ guides/setting-up-nextjs.md ━━━
|
||||
|
||||
Line 45:
|
||||
- 3. Choose router: pages/ or app/
|
||||
+ 3. App router is default (use --pages flag for pages router)
|
||||
|
||||
━━━ errors/nextjs-errors.md ━━━
|
||||
|
||||
Line 67:
|
||||
+ ## Migration: Next.js 14 → 15
|
||||
+
|
||||
+ **Breaking Changes**:
|
||||
+ - App router is now default
|
||||
+ - Pages router requires explicit opt-in
|
||||
+
|
||||
+ **Migration Steps**:
|
||||
+ 1. Update to Next.js 15: `bun --bun install next@15`
|
||||
+ 2. For pages router: Add `pages: true` to next.config.js
|
||||
+ 3. Update metadata: Replace Head with metadata exports
|
||||
+
|
||||
+ **Reference**: https://nextjs.org/docs/15/upgrade-guide
|
||||
|
||||
━━━ lookup/nextjs-commands.md ━━━
|
||||
|
||||
Line 12:
|
||||
- bunx --bun create-next-app@latest
|
||||
+ bunx --bun create-next-app@latest # App router default
|
||||
+ bunx --bun create-next-app@latest --pages # Pages router
|
||||
|
||||
Preview next file? (yes/no/show-all)
|
||||
Approve changes? (yes/no/edit):"
|
||||
|
||||
User: "edit"
|
||||
|
||||
Agent: "Line-by-line approval mode.
|
||||
|
||||
concepts/routing.md - Line 15 change?
|
||||
- App router is optional (use pages/ or app/ directory)
|
||||
+ App router is now default in Next.js 15 (pages/ still supported with opt-in)
|
||||
|
||||
Approve? (yes/no/modify):"
|
||||
|
||||
User: "yes"
|
||||
|
||||
[... continues for each change ...]
|
||||
```
|
||||
|
||||
### Stage 4-8: Backup, Update, Add Migration, Validate, Report
|
||||
```
|
||||
Agent: "Creating backup...
|
||||
💾 Backup: .tmp/backup/update-nextjs-2026-01-06-143530/
|
||||
|
||||
Updating files...
|
||||
✅ Updated 5 files
|
||||
📝 Modified 17 references
|
||||
🔄 Added migration notes to errors/nextjs-errors.md
|
||||
🔗 Validated all references (0 broken links)
|
||||
|
||||
Summary of changes:
|
||||
- concepts/routing.md: 3 updates (145 → 162 lines)
|
||||
- examples/app-router-example.md: 4 updates (78 → 89 lines)
|
||||
- guides/setting-up-nextjs.md: 1 update (132 → 133 lines)
|
||||
- errors/nextjs-errors.md: Added migration section (98 → 125 lines)
|
||||
- lookup/nextjs-commands.md: 2 updates (54 → 56 lines)
|
||||
|
||||
All files still under 200 line limit ✓
|
||||
|
||||
Rollback available at: .tmp/backup/update-nextjs-2026-01-06-143530/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Workflow (Interactive)
|
||||
|
||||
### Stage 1: Search Existing
|
||||
```
|
||||
/context error for "Cannot read property 'map' of undefined"
|
||||
↓
|
||||
Agent: "Searching existing errors for similar issues...
|
||||
|
||||
Found 1 similar error:
|
||||
📄 development/errors/react-errors.md (Line 45)
|
||||
## Error: Cannot read property 'X' of undefined
|
||||
Covers: General undefined property access in React
|
||||
Frequency: common
|
||||
|
||||
Found 2 related errors:
|
||||
📄 development/errors/react-errors.md
|
||||
## Error: Cannot read property 'length' of undefined
|
||||
## Error: Undefined is not an object"
|
||||
```
|
||||
|
||||
### Stage 2: Check Duplication (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Options:
|
||||
[A] Add as new error to react-errors.md
|
||||
(Specific case: 'map' on undefined array)
|
||||
|
||||
[B] Update existing 'Cannot read property X' error
|
||||
(Add 'map' as common example)
|
||||
|
||||
[C] Skip (already covered sufficiently)
|
||||
|
||||
Which framework/category?
|
||||
[1] React (react-errors.md)
|
||||
[2] JavaScript (js-errors.md)
|
||||
[3] General (common-errors.md)
|
||||
[4] Create new: ___
|
||||
|
||||
Select option + category (e.g., 'B 1'):"
|
||||
|
||||
User: "B 1"
|
||||
```
|
||||
|
||||
### Stage 3: Preview (APPROVAL REQUIRED)
|
||||
```
|
||||
Agent: "Would update development/errors/react-errors.md:
|
||||
|
||||
Current (Line 45):
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
## Error: Cannot read property 'X' of undefined
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
TypeError: Cannot read property 'X' of undefined
|
||||
```
|
||||
|
||||
**Cause**: Attempting to access property on undefined/null object.
|
||||
|
||||
**Solution**:
|
||||
1. Add null check before accessing property
|
||||
2. Use optional chaining (?.)
|
||||
3. Provide default value
|
||||
|
||||
**Code**:
|
||||
```jsx
|
||||
// ❌ Before
|
||||
const value = obj.property
|
||||
|
||||
// ✅ After
|
||||
const value = obj?.property ?? 'default'
|
||||
```
|
||||
|
||||
**Prevention**: Always validate data exists before accessing
|
||||
**Frequency**: common
|
||||
**Reference**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_property
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Proposed update:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
## Error: Cannot read property 'X' of undefined
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
TypeError: Cannot read property 'X' of undefined
|
||||
TypeError: Cannot read property 'map' of undefined ← NEW
|
||||
TypeError: Cannot read property 'length' of undefined ← NEW
|
||||
```
|
||||
|
||||
**Cause**: Attempting to access property on undefined/null object.
|
||||
Common with array methods (map, filter) when data hasn't loaded. ← NEW
|
||||
|
||||
**Solution**:
|
||||
1. Add null check before accessing property
|
||||
2. Use optional chaining (?.)
|
||||
3. Provide default value (especially for arrays) ← UPDATED
|
||||
|
||||
**Code**:
|
||||
```jsx
|
||||
// ❌ Before
|
||||
const value = obj.property
|
||||
const items = data.map(item => item.name) ← NEW
|
||||
|
||||
// ✅ After
|
||||
const value = obj?.property ?? 'default'
|
||||
const items = (data || []).map(item => item.name) ← NEW
|
||||
// Or with optional chaining:
|
||||
const items = data?.map(item => item.name) ?? [] ← NEW
|
||||
```
|
||||
|
||||
**Prevention**: Always validate data exists before accessing.
|
||||
For arrays, provide empty array default. ← UPDATED
|
||||
|
||||
**Frequency**: common
|
||||
**Reference**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_property
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
File size: 98 lines → 105 lines (under 150 limit ✓)
|
||||
|
||||
Approve? (yes/no/edit):"
|
||||
|
||||
User: "yes"
|
||||
```
|
||||
|
||||
### Stage 4-6: Add, Update, Report
|
||||
```
|
||||
Agent: "Updating development/errors/react-errors.md...
|
||||
|
||||
✅ Updated error in development/errors/react-errors.md
|
||||
🔗 Cross-referenced with 2 related errors
|
||||
📊 File size: 105 lines (under 150 limit)
|
||||
|
||||
Changes:
|
||||
- Added 'map' and 'length' to symptom examples
|
||||
- Updated cause to mention array methods
|
||||
- Added array-specific code examples
|
||||
- Updated prevention guidance"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Approval Gates
|
||||
All operations with `enforce="@critical_rules.approval_gate"` MUST:
|
||||
1. Show clear preview of what will happen
|
||||
2. Wait for explicit user input
|
||||
3. Provide options (yes/no/edit/preview/dry-run)
|
||||
4. Never proceed without confirmation
|
||||
|
||||
### Conflict Resolution
|
||||
When conflicts detected:
|
||||
1. Present all options clearly
|
||||
2. Use letter-based selection (A/B/C)
|
||||
3. Show impact of each option
|
||||
4. Allow user to choose resolution
|
||||
|
||||
### Previews
|
||||
All previews should show:
|
||||
1. What will be created/modified/deleted
|
||||
2. File sizes (before → after)
|
||||
3. Line-by-line diffs for updates
|
||||
4. Validation status (under limits, no broken links)
|
||||
|
||||
### Backups
|
||||
Operations that modify files MUST:
|
||||
1. Create backup before changes
|
||||
2. Store in `.tmp/backup/{operation}-{topic}-{timestamp}/`
|
||||
3. Report backup location
|
||||
4. Keep backups for rollback
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- context.md - Main command interface
|
||||
- harvest.md - Harvest workflow details
|
||||
- mvi-principle.md - What to extract
|
||||
- compact.md - How to minimize
|
||||
53
.opencode/context/core/context-system/navigation.md
Normal file
53
.opencode/context/core/context-system/navigation.md
Normal file
@@ -0,0 +1,53 @@
|
||||
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context System
|
||||
|
||||
**Purpose**: Documentation for the context system architecture and operations
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
core/context-system/
|
||||
├── navigation.md (this file)
|
||||
├── examples/
|
||||
│ └── navigation.md
|
||||
├── guides/
|
||||
│ └── navigation.md
|
||||
├── operations/
|
||||
│ └── navigation.md
|
||||
├── standards/
|
||||
│ └── navigation.md
|
||||
└── [overview files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **Understand context system** | `../context-system.md` |
|
||||
| **Operations & procedures** | `operations/navigation.md` |
|
||||
| **Implementation guides** | `guides/navigation.md` |
|
||||
| **Standards & templates** | `standards/navigation.md` |
|
||||
| **Examples** | `examples/navigation.md` |
|
||||
| **Migrate global → local** | `operations/migrate.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Examples** → Working examples of navigation files
|
||||
**Guides** → Step-by-step guides for working with context
|
||||
**Operations** → How to operate and maintain the context system
|
||||
**Standards** → Templates and standards for context files
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **Core Navigation** → `../navigation.md`
|
||||
- **Core Standards** → `../standards/navigation.md`
|
||||
- **Core System** → `../system/navigation.md`
|
||||
275
.opencode/context/core/context-system/operations/error.md
Normal file
275
.opencode/context/core/context-system/operations/error.md
Normal file
@@ -0,0 +1,275 @@
|
||||
<!-- Context: core/error | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Error Operation
|
||||
|
||||
**Purpose**: Add recurring errors to knowledge base with deduplication
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Encountered same error multiple times
|
||||
- Want to document solution for team
|
||||
- Building error knowledge base
|
||||
- Preventing repeated debugging
|
||||
|
||||
---
|
||||
|
||||
## 6-Stage Workflow
|
||||
|
||||
### Stage 1: Search Existing
|
||||
**Action**: Search for similar/related errors
|
||||
|
||||
**Process**:
|
||||
1. Search error message across all errors/ files
|
||||
2. Find similar errors (fuzzy matching)
|
||||
3. Find related errors (same category)
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Searching for: "Cannot read property 'map' of undefined"
|
||||
|
||||
Found 1 similar error:
|
||||
📄 development/errors/react-errors.md (Line 45)
|
||||
## Error: Cannot read property 'X' of undefined
|
||||
Covers: General undefined property access
|
||||
Frequency: common
|
||||
|
||||
Found 2 related errors:
|
||||
📄 development/errors/react-errors.md
|
||||
## Error: Cannot read property 'length' of undefined
|
||||
## Error: Undefined is not an object
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Check Duplication (APPROVAL REQUIRED)
|
||||
**Action**: Present deduplication options
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Options:
|
||||
[A] Add as new error to react-errors.md
|
||||
(Specific case: 'map' on undefined array)
|
||||
|
||||
[B] Update existing 'Cannot read property X' error
|
||||
(Add 'map' as common example)
|
||||
|
||||
[C] Skip (already covered sufficiently)
|
||||
|
||||
Which framework/category?
|
||||
[1] React (react-errors.md)
|
||||
[2] JavaScript (js-errors.md)
|
||||
[3] General (common-errors.md)
|
||||
[4] Create new: ___
|
||||
|
||||
Select option + category (e.g., 'B 1'):
|
||||
```
|
||||
|
||||
**Validation**: MUST wait for user input
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Preview (APPROVAL REQUIRED)
|
||||
**Action**: Show full error entry before adding
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Would update development/errors/react-errors.md:
|
||||
|
||||
Current (Line 45):
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
## Error: Cannot read property 'X' of undefined
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
TypeError: Cannot read property 'X' of undefined
|
||||
```
|
||||
|
||||
**Cause**: Attempting to access property on undefined/null object.
|
||||
|
||||
**Solution**:
|
||||
1. Add null check
|
||||
2. Use optional chaining (?.)
|
||||
3. Provide default value
|
||||
|
||||
**Code**:
|
||||
```jsx
|
||||
// ❌ Before
|
||||
const value = obj.property
|
||||
|
||||
// ✅ After
|
||||
const value = obj?.property ?? 'default'
|
||||
```
|
||||
|
||||
**Prevention**: Always validate data exists
|
||||
**Frequency**: common
|
||||
**Reference**: [Link]
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Proposed update:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
## Error: Cannot read property 'X' of undefined
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
TypeError: Cannot read property 'X' of undefined
|
||||
TypeError: Cannot read property 'map' of undefined ← NEW
|
||||
TypeError: Cannot read property 'length' of undefined ← NEW
|
||||
```
|
||||
|
||||
**Cause**: Attempting to access property on undefined/null object.
|
||||
Common with array methods (map, filter) when data hasn't loaded. ← NEW
|
||||
|
||||
**Solution**:
|
||||
1. Add null check
|
||||
2. Use optional chaining (?.)
|
||||
3. Provide default value (especially for arrays) ← UPDATED
|
||||
|
||||
**Code**:
|
||||
```jsx
|
||||
// ❌ Before
|
||||
const value = obj.property
|
||||
const items = data.map(item => item.name) ← NEW
|
||||
|
||||
// ✅ After
|
||||
const value = obj?.property ?? 'default'
|
||||
const items = (data || []).map(item => item.name) ← NEW
|
||||
```
|
||||
|
||||
**Prevention**: Always validate data exists. For arrays, provide empty array default. ← UPDATED
|
||||
**Frequency**: common
|
||||
**Reference**: [Link]
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
File size: 98 lines → 105 lines (under 150 limit ✓)
|
||||
|
||||
Approve? (yes/no/edit):
|
||||
```
|
||||
|
||||
**Edit mode**: Allow modification before adding
|
||||
|
||||
**Validation**: MUST get approval before proceeding
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Add/Update
|
||||
**Action**: Add or update error entry
|
||||
|
||||
**Process**:
|
||||
1. Add/update error in target file
|
||||
2. Follow error template format
|
||||
3. Maintain file size <150 lines
|
||||
4. Update "Last Updated" date
|
||||
|
||||
**Template Format**:
|
||||
```markdown
|
||||
## Error: {Name}
|
||||
|
||||
**Symptom**: [Error message]
|
||||
**Cause**: [Why - 1-2 sentences]
|
||||
**Solution**: [Steps]
|
||||
**Code**: [Before/After example]
|
||||
**Prevention**: [How to avoid]
|
||||
**Frequency**: common/occasional/rare
|
||||
**Reference**: [Link]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Update Navigation
|
||||
**Action**: Update README.md and add cross-references
|
||||
|
||||
**Process**:
|
||||
1. Update README.md if new file created
|
||||
2. Add cross-references to related errors
|
||||
3. Link from related concepts/examples
|
||||
|
||||
---
|
||||
|
||||
### Stage 6: Report
|
||||
**Action**: Show results
|
||||
|
||||
**Format**:
|
||||
```
|
||||
✅ Added error to {category}/errors/{file}.md
|
||||
🔗 Cross-referenced with X related errors
|
||||
📊 Updated README.md (if needed)
|
||||
|
||||
Changes:
|
||||
- Updated existing error entry
|
||||
- Added 'map' and 'length' examples
|
||||
- File size: 105 lines (under 150 limit)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deduplication Strategy
|
||||
|
||||
### Similar Errors
|
||||
Same root cause, different manifestations
|
||||
→ **Update existing** to include new examples
|
||||
|
||||
### Related Errors
|
||||
Different causes, same category
|
||||
→ **Cross-reference** between errors
|
||||
|
||||
### Duplicate Errors
|
||||
Exact same error already documented
|
||||
→ **Skip** (already covered)
|
||||
|
||||
### New Errors
|
||||
Unique error not yet documented
|
||||
→ **Add as new** error entry
|
||||
|
||||
---
|
||||
|
||||
## Error Grouping
|
||||
|
||||
Group errors by framework/topic in single file:
|
||||
- `react-errors.md` - All React errors
|
||||
- `nextjs-errors.md` - All Next.js errors
|
||||
- `auth-errors.md` - All authentication errors
|
||||
|
||||
**Don't create**: One file per error (too granular)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Add New Error
|
||||
```bash
|
||||
/context error for "hooks can only be called inside components"
|
||||
```
|
||||
|
||||
### Add Common Error
|
||||
```bash
|
||||
/context error for "Cannot read property 'map' of undefined"
|
||||
```
|
||||
|
||||
### Add Framework Error
|
||||
```bash
|
||||
/context error for "Hydration failed in Next.js"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Searched for similar errors?
|
||||
- [ ] Deduplication options presented?
|
||||
- [ ] Preview shown?
|
||||
- [ ] User approved?
|
||||
- [ ] Error follows template format?
|
||||
- [ ] File size <150 lines?
|
||||
- [ ] Cross-references added?
|
||||
- [ ] README.md updated (if new file)?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- standards/templates.md - Error template format
|
||||
- guides/workflows.md - Interactive examples
|
||||
202
.opencode/context/core/context-system/operations/extract.md
Normal file
202
.opencode/context/core/context-system/operations/extract.md
Normal file
@@ -0,0 +1,202 @@
|
||||
<!-- Context: core/extract | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Extract Operation
|
||||
|
||||
**Purpose**: Extract context from docs, code, or URLs into organized context files
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Extracting from documentation (React docs, API docs, etc.)
|
||||
- Extracting from codebase (patterns, conventions)
|
||||
- Extracting from URLs (blog posts, guides)
|
||||
- Creating initial context for new topics
|
||||
|
||||
---
|
||||
|
||||
## 7-Stage Workflow
|
||||
|
||||
### Stage 1: Read Source
|
||||
```
|
||||
/context extract from https://react.dev/hooks
|
||||
↓
|
||||
Agent: "Reading source (8,500 lines)...
|
||||
Analyzing content for extractable items..."
|
||||
```
|
||||
|
||||
**Action**: Read and analyze source material
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Analyze & Categorize
|
||||
**Action**: Extract and categorize content by function
|
||||
|
||||
**Categorization**:
|
||||
- Design decisions → `concepts/`
|
||||
- Working code → `examples/`
|
||||
- Step-by-step workflows → `guides/`
|
||||
- Reference data (commands, paths) → `lookup/`
|
||||
- Errors/gotchas → `errors/`
|
||||
|
||||
**Output**: List of extractable items with previews
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Select Category (APPROVAL REQUIRED)
|
||||
**Action**: User chooses target category and items
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Found 12 extractable items from {source}:
|
||||
|
||||
Concepts (8):
|
||||
✓ [A] useState - State management hook
|
||||
✓ [B] useEffect - Side effects hook
|
||||
... (6 more)
|
||||
|
||||
Errors (4):
|
||||
✓ [I] Hooks called conditionally
|
||||
✓ [J] Hooks in loops
|
||||
... (2 more)
|
||||
|
||||
Which category?
|
||||
[1] development/
|
||||
[2] core/
|
||||
[3] Create new category: ___
|
||||
|
||||
Select items (A B I or 'all') + category (1/2/3):
|
||||
```
|
||||
|
||||
**Validation**: MUST wait for user input before proceeding
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Preview (APPROVAL REQUIRED)
|
||||
**Action**: Show what will be created, check for conflicts
|
||||
|
||||
**Format**:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Extraction Plan: development/
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
CREATE (new files):
|
||||
concepts/use-state.md (45 lines)
|
||||
concepts/use-effect.md (52 lines)
|
||||
concepts/use-context.md (38 lines)
|
||||
... (6 more)
|
||||
guides/custom-hooks.md (87 lines)
|
||||
guides/debugging-hooks.md (65 lines)
|
||||
|
||||
ADD TO (existing files):
|
||||
errors/react-hooks-errors.md (98 → 124 lines)
|
||||
+ 4 new error entries
|
||||
|
||||
⚠️ CONFLICT (file already exists):
|
||||
concepts/use-memo.md already exists (42 lines)
|
||||
Options:
|
||||
[A] Skip — keep existing file
|
||||
[B] Overwrite — replace with extracted version
|
||||
[C] Merge — add new content to existing file (42 → 58 lines)
|
||||
Choose [A/B/C]: _
|
||||
|
||||
NAVIGATION UPDATE:
|
||||
development/navigation.md
|
||||
+ 9 new entries in Concepts table
|
||||
+ 2 new entries in Guides table
|
||||
+ 1 updated entry in Errors table
|
||||
|
||||
Total: 12 files, ~650 lines
|
||||
|
||||
Preview content? (type filename, 'all' for batch, or 'skip')
|
||||
Approve? [y/n/edit]: _
|
||||
```
|
||||
|
||||
**If user types 'all'**: Show first 10 lines of each file in sequence
|
||||
**If user types filename**: Show full content of that file
|
||||
**If user types 'skip'**: Proceed to approval
|
||||
|
||||
**Validation**: MUST get approval before proceeding
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Create
|
||||
**Action**: Create files in function folders
|
||||
|
||||
**Process**:
|
||||
1. Apply MVI format (1-3 sentences, 3-5 key points, minimal example)
|
||||
2. Create files in correct function folders
|
||||
3. Ensure all files <200 lines
|
||||
4. Add cross-references
|
||||
|
||||
**Enforcement**: `@critical_rules.mvi_strict` + `@critical_rules.function_structure`
|
||||
|
||||
---
|
||||
|
||||
### Stage 6: Update Navigation (preview included in Stage 4)
|
||||
**Action**: Update navigation.md and add cross-references
|
||||
|
||||
**Process**:
|
||||
1. Update category navigation.md with new files (as previewed in Stage 4)
|
||||
2. Add priority levels (critical/high/medium/low)
|
||||
3. Add cross-references between related files
|
||||
4. Update "Last Updated" dates
|
||||
|
||||
---
|
||||
|
||||
### Stage 7: Report
|
||||
**Action**: Show comprehensive results
|
||||
|
||||
**Format**:
|
||||
```
|
||||
✅ Extracted X items into {category}
|
||||
📄 Created Y files
|
||||
📊 Updated {category}/README.md
|
||||
|
||||
Files created:
|
||||
- {category}/concepts/ (N files)
|
||||
- {category}/examples/ (N files)
|
||||
- {category}/errors/ (N files)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Extract from URL
|
||||
```bash
|
||||
/context extract from https://react.dev/hooks
|
||||
```
|
||||
|
||||
### Extract from Local Docs
|
||||
```bash
|
||||
/context extract from docs/api.md
|
||||
/context extract from docs/architecture/
|
||||
```
|
||||
|
||||
### Extract from Code
|
||||
```bash
|
||||
/context extract from src/utils/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All files <200 lines?
|
||||
- [ ] MVI format applied (1-3 sentences, 3-5 points, example, reference)?
|
||||
- [ ] Files in correct function folders?
|
||||
- [ ] README.md updated?
|
||||
- [ ] Cross-references added?
|
||||
- [ ] User approved before creation?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- standards/mvi.md - What to extract
|
||||
- guides/compact.md - How to minimize
|
||||
- guides/workflows.md - Interactive examples
|
||||
342
.opencode/context/core/context-system/operations/harvest.md
Normal file
342
.opencode/context/core/context-system/operations/harvest.md
Normal file
@@ -0,0 +1,342 @@
|
||||
<!-- Context: core/harvest | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Harvest Operation
|
||||
|
||||
**Purpose**: Extract knowledge from AI summaries → permanent context, then clean workspace
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## Core Problem
|
||||
|
||||
AI agents create summary files (OVERVIEW.md, SESSION-*.md, SUMMARY.md) that contain valuable knowledge but clutter the workspace. These files "plague" the codebase.
|
||||
|
||||
**Solution**: Harvest the knowledge → permanent context, then delete the summaries.
|
||||
|
||||
---
|
||||
|
||||
## Auto-Detection Patterns
|
||||
|
||||
<rule id="summary_patterns" enforcement="strict">
|
||||
Harvest automatically detects these patterns:
|
||||
|
||||
Filename patterns:
|
||||
- *OVERVIEW.md
|
||||
- *SUMMARY.md
|
||||
- SESSION-*.md
|
||||
- CONTEXT-*.md
|
||||
- *NOTES.md
|
||||
|
||||
Location patterns:
|
||||
- Files in .tmp/ directory
|
||||
- Files with "Summary", "Overview", "Session" in title
|
||||
- Files >2KB in root directory (likely summaries)
|
||||
</rule>
|
||||
|
||||
---
|
||||
|
||||
## 6-Stage Workflow
|
||||
|
||||
<workflow id="harvest" enforce="@critical_rules">
|
||||
|
||||
### Stage 1: Scan
|
||||
**Action**: Find all summary files in workspace
|
||||
|
||||
**Process**:
|
||||
1. Search for auto-detection patterns
|
||||
2. Check .tmp/ directory
|
||||
3. List files with sizes
|
||||
4. Sort by modification date (newest first)
|
||||
|
||||
**Output**: List of candidate files
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Found 3 summary documents:
|
||||
1. CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB, modified 1 hour ago)
|
||||
2. SESSION-auth-work.md (1.8 KB, modified today)
|
||||
3. .tmp/IMPLEMENTATION-NOTES.md (800 bytes, modified today)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Analyze
|
||||
**Action**: Categorize content by function
|
||||
|
||||
**Mapping Rules**:
|
||||
| Content Type | Target Folder | How to Identify |
|
||||
|--------------|---------------|-----------------|
|
||||
| Design decisions | `concepts/` | "We decided to...", "Architecture", "Pattern" |
|
||||
| Solutions/patterns | `examples/` | Code snippets, "Here's how we..." |
|
||||
| Workflows | `guides/` | Numbered steps, "How to...", "Setup" |
|
||||
| Errors encountered | `errors/` | Error messages, "Fixed issue", "Gotcha" |
|
||||
| Reference data | `lookup/` | Tables, lists, paths, commands |
|
||||
|
||||
**Process**:
|
||||
1. Read each file
|
||||
2. Identify valuable sections (skip planning/conversation)
|
||||
3. Categorize by function
|
||||
4. Determine target file path
|
||||
5. Generate preview (first 60 chars)
|
||||
|
||||
**Output**: Categorized items with letter IDs
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Approve (CRITICAL)
|
||||
**Action**: Present approval UI with letter-based selection
|
||||
|
||||
<rule id="approval_gate" enforcement="strict">
|
||||
ALWAYS show approval UI before extracting/deleting.
|
||||
NEVER auto-harvest without user confirmation.
|
||||
</rule>
|
||||
|
||||
**Format**:
|
||||
```
|
||||
### CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
|
||||
|
||||
✓ [A] Design: Function-based context organization
|
||||
→ Would add to: core/concepts/context-organization.md
|
||||
Preview: "Organize by function (concepts/, examples/...)..."
|
||||
|
||||
✓ [B] Pattern: Minimal Viable Information
|
||||
→ Would add to: core/concepts/mvi-principle.md
|
||||
Preview: "Extract core only (1-3 sentences), 3-5 key points..."
|
||||
|
||||
✓ [C] Workflow: Harvesting summary documents
|
||||
→ Would create: core/guides/harvesting.md
|
||||
Preview: "Scan for summaries → Extract → Approve → Delete"
|
||||
|
||||
✗ [D] Skip: Planning discussion notes (temporary knowledge)
|
||||
|
||||
---
|
||||
|
||||
### SESSION-auth-work.md (1.8 KB)
|
||||
|
||||
✓ [E] Error: JWT token expiration not handled
|
||||
→ Would add to: development/errors/auth-errors.md
|
||||
Preview: "Symptom: 401 after 1 hour. Cause: No refresh flow..."
|
||||
|
||||
✓ [F] Example: JWT refresh token implementation
|
||||
→ Would create: development/examples/jwt-refresh.md
|
||||
Preview: "Store refresh token → Check expiry → Request new..."
|
||||
|
||||
---
|
||||
|
||||
### .tmp/IMPLEMENTATION-NOTES.md (800 bytes)
|
||||
|
||||
✗ [G] Skip: Duplicate info (already in development/concepts/api-design.md)
|
||||
|
||||
---
|
||||
|
||||
**Quick options**:
|
||||
- Type 'A B C E F' - Approve specific items
|
||||
- Type 'all' - Approve all ✓ items (A B C E F)
|
||||
- Type 'none' - Skip harvesting, delete files anyway
|
||||
- Type 'cancel' - Keep files, don't harvest
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- MUST wait for user input
|
||||
- MUST not proceed without approval
|
||||
- If user types 'cancel', stop immediately
|
||||
|
||||
**Output**: List of approved items
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Extract
|
||||
**Action**: Extract and minimize approved items
|
||||
|
||||
<rule id="extraction" enforce="@mvi_principle">
|
||||
Apply MVI to all extracted content:
|
||||
- Core concept: 1-3 sentences
|
||||
- Key points: 3-5 bullets
|
||||
- Minimal example: <10 lines
|
||||
- Reference link: to original source
|
||||
- Files: <200 lines each
|
||||
</rule>
|
||||
|
||||
**Process**:
|
||||
1. For each approved item:
|
||||
- Extract core content
|
||||
- Apply MVI minimization (see compact.md)
|
||||
- Generate preview of final content
|
||||
2. Show extraction preview (APPROVAL REQUIRED):
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Extraction Preview
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
[A] → core/concepts/context-organization.md (CREATE, 45 lines)
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ # Concept: Context Organization │
|
||||
│ │
|
||||
│ **Purpose**: Function-based knowledge organization │
|
||||
│ │
|
||||
│ ## Core Concept │
|
||||
│ Organize context by function: concepts/, examples/... │
|
||||
│ ... │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
[E] → development/errors/auth-errors.md (ADD to existing, 98 → 112 lines)
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ + ## Error: JWT Token Expiration Not Handled │
|
||||
│ + │
|
||||
│ + **Symptom**: 401 after 1 hour │
|
||||
│ + **Cause**: No refresh token flow │
|
||||
│ + ... │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
... ({remaining_count} more items)
|
||||
|
||||
Show all? [y/n] | Approve extraction? [y/n/edit]: _
|
||||
```
|
||||
|
||||
3. On approval:
|
||||
- Write files to disk
|
||||
- Add cross-references
|
||||
- Update navigation.md maps
|
||||
|
||||
**Output**: List of created/updated files
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Cleanup (APPROVAL REQUIRED)
|
||||
**Action**: Archive or delete source summary files
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Cleanup: Source Files
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Successfully harvested from:
|
||||
CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
|
||||
SESSION-auth-work.md (1.8 KB)
|
||||
|
||||
Skipped (no valuable content):
|
||||
.tmp/IMPLEMENTATION-NOTES.md (800 bytes)
|
||||
|
||||
How should we handle these source files?
|
||||
|
||||
1. Archive (safe) — move to .tmp/archive/harvested/{date}/
|
||||
→ Can restore later if needed
|
||||
|
||||
2. Delete — permanently remove harvested files
|
||||
→ Frees disk space, no undo
|
||||
|
||||
3. Keep — leave source files in place
|
||||
→ No cleanup, files remain where they are
|
||||
|
||||
Choose [1/2/3] (default: 1): _
|
||||
```
|
||||
|
||||
<rule id="cleanup_safety" enforcement="strict">
|
||||
ONLY cleanup files that had content successfully harvested.
|
||||
If extraction failed, keep the original file.
|
||||
</rule>
|
||||
|
||||
**Output**: Cleanup report
|
||||
|
||||
---
|
||||
|
||||
### Stage 6: Report
|
||||
**Action**: Show comprehensive results summary
|
||||
|
||||
**Format**:
|
||||
```
|
||||
✅ Harvested 5 items into permanent context:
|
||||
- Added to core/concepts/context-organization.md
|
||||
- Added to core/concepts/mvi-principle.md
|
||||
- Created core/guides/harvesting.md
|
||||
- Added to development/errors/auth-errors.md
|
||||
- Created development/examples/jwt-refresh.md
|
||||
|
||||
🗑️ Cleaned up workspace:
|
||||
- Archived: CONTEXT-SYSTEM-OVERVIEW.md → .tmp/archive/harvested/2026-01-06/
|
||||
- Archived: SESSION-auth-work.md → .tmp/archive/harvested/2026-01-06/
|
||||
- Deleted: .tmp/IMPLEMENTATION-NOTES.md (no valuable content)
|
||||
|
||||
📊 Updated navigation maps:
|
||||
- .opencode/context/core/navigation.md
|
||||
- .opencode/context/development/navigation.md
|
||||
|
||||
💾 Disk space freed: 6.8 KB
|
||||
```
|
||||
|
||||
</workflow>
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Scan entire workspace
|
||||
```bash
|
||||
/context harvest
|
||||
```
|
||||
|
||||
### Scan specific directory
|
||||
```bash
|
||||
/context harvest .tmp/
|
||||
/context harvest docs/sessions/
|
||||
```
|
||||
|
||||
### Harvest specific file
|
||||
```bash
|
||||
/context harvest OVERVIEW.md
|
||||
/context harvest SESSION-2026-01-06.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Smart Content Detection
|
||||
|
||||
### ✅ Extract (Valuable Knowledge)
|
||||
- Design decisions ("We chose X because...")
|
||||
- Patterns that worked ("This pattern solved...")
|
||||
- Errors encountered + solutions
|
||||
- API changes ("Updated from v1 to v2...")
|
||||
- Performance findings ("Optimization reduced...")
|
||||
- Core concepts explained
|
||||
|
||||
### ❌ Skip (Temporary/Noise)
|
||||
- Planning discussion ("Should we...?", "Maybe try...")
|
||||
- Conversational notes ("I think...", "We talked about...")
|
||||
- Duplicate info (already in context)
|
||||
- TODO lists (move to task system instead)
|
||||
- Timestamps and session metadata
|
||||
|
||||
---
|
||||
|
||||
## Safety Features
|
||||
|
||||
1. **Approval gate** - Never auto-delete without confirmation
|
||||
2. **Archive by default** - Move to .tmp/archive/, not permanent delete
|
||||
3. **Validation** - Check file sizes, structure before committing
|
||||
4. **Rollback** - Can restore from archive if needed
|
||||
5. **Dry run** - Show what would happen before doing it
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
After harvest operation:
|
||||
|
||||
- [ ] Valuable knowledge extracted to permanent context?
|
||||
- [ ] All extracted files <200 lines?
|
||||
- [ ] Files in correct function folders?
|
||||
- [ ] navigation.md navigation updated?
|
||||
- [ ] Summary files archived/deleted?
|
||||
- [ ] Workspace cleaner than before?
|
||||
- [ ] No knowledge lost?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- compact.md - How to minimize extracted content
|
||||
- mvi-principle.md - What to extract
|
||||
- structure.md - Where files go
|
||||
- creation.md - File creation rules
|
||||
223
.opencode/context/core/context-system/operations/migrate.md
Normal file
223
.opencode/context/core/context-system/operations/migrate.md
Normal file
@@ -0,0 +1,223 @@
|
||||
<!-- Context: core/migrate | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Migrate Operation
|
||||
|
||||
**Purpose**: Copy context files from global (`~/.config/opencode/context/`) to local (`.opencode/context/`) so they're project-specific and git-committed.
|
||||
|
||||
**Last Updated**: 2026-02-06
|
||||
|
||||
---
|
||||
|
||||
## Core Problem
|
||||
|
||||
Users who installed OAC globally have project-intelligence files at `~/.config/opencode/context/project-intelligence/`. These files are project-specific patterns but aren't committed to git or shared with the team.
|
||||
|
||||
**Solution**: Migrate project-intelligence from global → local, so patterns are version-controlled and team-shared.
|
||||
|
||||
---
|
||||
|
||||
## 4-Stage Workflow
|
||||
|
||||
<workflow id="migrate" enforce="@critical_rules">
|
||||
|
||||
### Stage 1: Detect Sources
|
||||
|
||||
Scan for context files in the global config directory:
|
||||
|
||||
```
|
||||
Scanning global context...
|
||||
|
||||
Global location: ~/.config/opencode/context/
|
||||
|
||||
Found:
|
||||
project-intelligence/
|
||||
technical-domain.md (1.2 KB, Version: 1.3)
|
||||
navigation.md (800 bytes, Version: 1.0)
|
||||
business-domain.md (1.5 KB, Version: 1.1)
|
||||
|
||||
Local location: .opencode/context/
|
||||
|
||||
Status: No local project-intelligence/ found
|
||||
```
|
||||
|
||||
**If no global context found:**
|
||||
```
|
||||
No global context found at ~/.config/opencode/context/
|
||||
|
||||
Nothing to migrate. Use /add-context to create project intelligence.
|
||||
```
|
||||
→ Exit
|
||||
|
||||
**If no global project-intelligence found (but other global context exists):**
|
||||
```
|
||||
Global context found at ~/.config/opencode/context/ but no project-intelligence/ directory.
|
||||
|
||||
Only project-intelligence files are migrated (project-specific patterns).
|
||||
Core standards stay in global (they're universal, not project-specific).
|
||||
|
||||
Nothing to migrate. Use /add-context to create project intelligence.
|
||||
```
|
||||
→ Exit
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Check for Conflicts
|
||||
|
||||
If local `.opencode/context/project-intelligence/` already exists:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Conflict: Local project-intelligence already exists
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Global files: Local files:
|
||||
technical-domain.md technical-domain.md
|
||||
Version: 1.3, Updated: 2026-01-15 Version: 1.0, Updated: 2026-02-01
|
||||
navigation.md navigation.md
|
||||
Version: 1.0, Updated: 2026-01-10 Version: 1.0, Updated: 2026-02-01
|
||||
business-domain.md (not present locally)
|
||||
Version: 1.1, Updated: 2026-01-12
|
||||
|
||||
Options:
|
||||
1. Skip existing — only copy files that don't exist locally
|
||||
→ Will copy: business-domain.md
|
||||
→ Will skip: technical-domain.md, navigation.md (local kept)
|
||||
|
||||
2. Overwrite all — replace local with global versions
|
||||
→ Will overwrite: technical-domain.md, navigation.md
|
||||
→ Will copy: business-domain.md
|
||||
→ Local backup created first
|
||||
|
||||
3. Cancel
|
||||
|
||||
Choose [1/2/3]: _
|
||||
```
|
||||
|
||||
**If user chooses 2 (Overwrite), show content diff first:**
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Diff: technical-domain.md
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Local (current): Global (incoming):
|
||||
Version: 1.0 Version: 1.3
|
||||
Tech Stack: Next.js 14 Tech Stack: Next.js 15 ← different
|
||||
API: basic validation API: Zod validation ← different
|
||||
Component: same Component: same
|
||||
Naming: same Naming: same
|
||||
|
||||
Show full diff? [y/n]: _
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Backup local files to .tmp/backup/migrate-{timestamp}/ before overwriting?
|
||||
[y/n] (default: y): _
|
||||
```
|
||||
|
||||
If no conflicts → proceed directly to Stage 3.
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Approval & Copy
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Migration Plan
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Will copy from: ~/.config/opencode/context/project-intelligence/
|
||||
Will copy to: .opencode/context/project-intelligence/
|
||||
|
||||
Files to copy:
|
||||
✓ technical-domain.md (1.2 KB)
|
||||
✓ navigation.md (800 bytes)
|
||||
✓ business-domain.md (1.5 KB)
|
||||
|
||||
After migration:
|
||||
→ Local files committed to git = team gets your patterns
|
||||
→ Agents load local (overrides global)
|
||||
→ Global files remain as fallback for other projects
|
||||
|
||||
Proceed? [y/n]: _
|
||||
```
|
||||
|
||||
**Actions on approval:**
|
||||
1. Create `.opencode/context/project-intelligence/` if it doesn't exist
|
||||
2. Copy each file from global → local
|
||||
3. Validate copied files (frontmatter, MVI compliance)
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Cleanup & Confirmation
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Migration Complete
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Copied 3 files to .opencode/context/project-intelligence/
|
||||
|
||||
✓ technical-domain.md
|
||||
✓ navigation.md
|
||||
✓ business-domain.md
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Clean up global project-intelligence?
|
||||
|
||||
The global files are no longer needed for THIS project (local takes priority).
|
||||
Keeping them means they still apply as fallback to other projects.
|
||||
|
||||
1. Keep global files (safe default)
|
||||
2. Remove global project-intelligence/ (only affects this user)
|
||||
|
||||
Choose [1/2] (default: 1): _
|
||||
```
|
||||
|
||||
**If user chooses 2 (Remove):**
|
||||
- Delete `~/.config/opencode/context/project-intelligence/` only
|
||||
- Do NOT touch `~/.config/opencode/context/core/` or any other global context
|
||||
|
||||
</workflow>
|
||||
|
||||
---
|
||||
|
||||
## What Gets Migrated
|
||||
|
||||
| Migrated (project-specific) | NOT Migrated (universal) |
|
||||
|---|---|
|
||||
| `project-intelligence/` | `core/standards/` |
|
||||
| `project-intelligence/technical-domain.md` | `core/context-system/` |
|
||||
| `project-intelligence/business-domain.md` | `core/workflows/` |
|
||||
| `project-intelligence/navigation.md` | `core/guides/` |
|
||||
| `project-intelligence/decisions-log.md` | Any other `core/` files |
|
||||
| `project-intelligence/living-notes.md` | |
|
||||
|
||||
**Rationale**: Project intelligence is project-specific (YOUR tech stack, YOUR patterns). Core standards are universal (code quality, documentation standards) and should stay global.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Permission denied:**
|
||||
```
|
||||
Error: Cannot write to .opencode/context/project-intelligence/
|
||||
Check directory permissions and try again.
|
||||
```
|
||||
|
||||
**Global path not found:**
|
||||
```
|
||||
No global OpenCode config found at ~/.config/opencode/
|
||||
|
||||
If you installed to a custom location, set OPENCODE_INSTALL_DIR:
|
||||
export OPENCODE_INSTALL_DIR=/your/custom/path
|
||||
/context migrate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `/add-context` — Create new project intelligence (interactive wizard)
|
||||
- `/context harvest` — Extract knowledge from summaries
|
||||
- Context path resolution: `.opencode/context/core/system/context-paths.md`
|
||||
224
.opencode/context/core/context-system/operations/organize.md
Normal file
224
.opencode/context/core/context-system/operations/organize.md
Normal file
@@ -0,0 +1,224 @@
|
||||
<!-- Context: core/organize | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Organize Operation
|
||||
|
||||
**Purpose**: Restructure flat context files into function-based folder structure
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Migrating from flat structure to function-based
|
||||
- Cleaning up disorganized context directories
|
||||
- Splitting ambiguous files into proper categories
|
||||
- Resolving duplicate/conflicting files
|
||||
|
||||
---
|
||||
|
||||
## 8-Stage Workflow
|
||||
|
||||
### Stage 1: Scan
|
||||
**Action**: Scan category for all files and detect structure
|
||||
|
||||
**Output**: List of files with current structure type (flat vs organized)
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Categorize
|
||||
**Action**: Categorize each file by function
|
||||
|
||||
**Categorization Rules**:
|
||||
- Explains concept? → `concepts/`
|
||||
- Shows working code? → `examples/`
|
||||
- Step-by-step instructions? → `guides/`
|
||||
- Reference data (tables, commands)? → `lookup/`
|
||||
- Errors/issues? → `errors/`
|
||||
|
||||
**Output**: Categorization plan with flagged ambiguous files
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Resolve Conflicts (APPROVAL REQUIRED)
|
||||
**Action**: Present categorization plan and handle conflicts
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Organizing {category}/ (23 files, flat structure)
|
||||
|
||||
Clear categorization (18 files):
|
||||
concepts/ (8):
|
||||
✓ authentication.md → concepts/authentication.md
|
||||
|
||||
examples/ (5):
|
||||
✓ jwt-example.md → examples/jwt-example.md
|
||||
|
||||
Ambiguous files (5 - need your input):
|
||||
|
||||
[?] api-design.md (contains concepts AND steps)
|
||||
→ [A] Split: concepts/api-design.md + guides/api-design-guide.md
|
||||
→ [B] Keep as concepts/api-design.md
|
||||
→ [C] Keep as guides/api-design.md
|
||||
|
||||
Conflicts (2):
|
||||
|
||||
[!] authentication.md → concepts/auth.md
|
||||
Target already exists (120 lines)
|
||||
→ [J] Merge into existing
|
||||
→ [K] Rename to concepts/authentication-v2.md
|
||||
→ [L] Skip (keep flat)
|
||||
|
||||
Select resolutions (A J or 'auto'):
|
||||
```
|
||||
|
||||
**Validation**: MUST wait for user input
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Preview (APPROVAL REQUIRED)
|
||||
**Action**: Show preview of all changes
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Preview changes:
|
||||
|
||||
CREATE directories:
|
||||
{category}/concepts/
|
||||
{category}/examples/
|
||||
{category}/guides/
|
||||
{category}/lookup/
|
||||
{category}/errors/
|
||||
|
||||
MOVE files (18):
|
||||
authentication.md → concepts/authentication.md
|
||||
... (17 more)
|
||||
|
||||
SPLIT files (3):
|
||||
api-design.md → concepts/api-design.md + guides/api-design-guide.md
|
||||
|
||||
MERGE files (2):
|
||||
authentication.md → concepts/auth.md (merge content)
|
||||
|
||||
UPDATE:
|
||||
{category}/README.md
|
||||
Fix 47 internal references
|
||||
|
||||
Dry-run? (yes/no/show-diff):
|
||||
```
|
||||
|
||||
**Dry-run**: Simulates changes without executing
|
||||
|
||||
**Validation**: MUST get approval before proceeding
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Backup
|
||||
**Action**: Create backup before making changes
|
||||
|
||||
**Location**: `.tmp/backup/organize-{category}-{timestamp}/`
|
||||
|
||||
**Purpose**: Enable rollback if needed
|
||||
|
||||
---
|
||||
|
||||
### Stage 6: Execute
|
||||
**Action**: Perform the reorganization
|
||||
|
||||
**Process**:
|
||||
1. Create function folders
|
||||
2. Move files to correct locations
|
||||
3. Split ambiguous files if requested
|
||||
4. Merge conflicts if requested
|
||||
|
||||
---
|
||||
|
||||
### Stage 7: Update
|
||||
**Action**: Update navigation and fix references
|
||||
|
||||
**Process**:
|
||||
1. Update README.md with navigation tables
|
||||
2. Fix all internal references to moved files
|
||||
3. Validate all links work
|
||||
4. Update "Last Updated" dates
|
||||
|
||||
---
|
||||
|
||||
### Stage 8: Report
|
||||
**Action**: Show comprehensive results
|
||||
|
||||
**Format**:
|
||||
```
|
||||
✅ Organized X files into function folders
|
||||
📁 Created Y new folders
|
||||
🔀 Split Z ambiguous files
|
||||
🔗 Fixed N references
|
||||
💾 Backup: .tmp/backup/organize-{category}-{timestamp}/
|
||||
|
||||
Rollback available if needed.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### Ambiguous Files
|
||||
File fits multiple categories (e.g., has concepts AND steps)
|
||||
|
||||
**Options**:
|
||||
- Split into multiple files (recommended)
|
||||
- Keep in primary category
|
||||
- User decides which is primary
|
||||
|
||||
### Duplicate Targets
|
||||
Target file already exists
|
||||
|
||||
**Options**:
|
||||
- Merge content into existing file
|
||||
- Rename to avoid conflict (e.g., -v2)
|
||||
- Skip (keep in flat structure)
|
||||
|
||||
### Auto-Resolution
|
||||
Agent suggests best option based on:
|
||||
- File size
|
||||
- Content analysis
|
||||
- Existing structure
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Organize Flat Directory
|
||||
```bash
|
||||
/context organize development/
|
||||
```
|
||||
|
||||
### Dry-Run First
|
||||
```bash
|
||||
/context organize development/ --dry-run
|
||||
```
|
||||
|
||||
### Organize Multiple
|
||||
```bash
|
||||
/context organize development/
|
||||
/context organize core/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All files in function folders (not flat)?
|
||||
- [ ] Ambiguous files resolved?
|
||||
- [ ] Conflicts handled?
|
||||
- [ ] README.md created/updated?
|
||||
- [ ] All references fixed?
|
||||
- [ ] Backup created?
|
||||
- [ ] User approved changes?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- standards/structure.md - Folder organization rules
|
||||
- guides/workflows.md - Interactive examples
|
||||
237
.opencode/context/core/context-system/operations/update.md
Normal file
237
.opencode/context/core/context-system/operations/update.md
Normal file
@@ -0,0 +1,237 @@
|
||||
<!-- Context: core/update | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Update Operation
|
||||
|
||||
**Purpose**: Update context when APIs, frameworks, or contracts change
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Framework version updates (Next.js 14 → 15)
|
||||
- API changes (breaking changes, deprecations)
|
||||
- New features added to existing topics
|
||||
- Migration guides needed
|
||||
|
||||
---
|
||||
|
||||
## 8-Stage Workflow
|
||||
|
||||
### Stage 1: Identify Changes (APPROVAL REQUIRED)
|
||||
**Action**: User describes what changed
|
||||
|
||||
**Format**:
|
||||
```
|
||||
What changed in {topic}?
|
||||
[A] API changes
|
||||
[B] Deprecations
|
||||
[C] New features
|
||||
[D] Breaking changes
|
||||
[E] Other (describe)
|
||||
|
||||
Select all that apply (A B C D or describe):
|
||||
```
|
||||
|
||||
**Follow-up**: Get specific details for each selected type
|
||||
|
||||
**Validation**: MUST get user input before proceeding
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Find Affected Files
|
||||
**Action**: Search for files referencing the topic
|
||||
|
||||
**Process**:
|
||||
1. Grep for topic references across all context
|
||||
2. Count references per file
|
||||
3. Show impact analysis
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Found 5 files referencing {topic}:
|
||||
📄 concepts/routing.md (3 references, 145 lines)
|
||||
📄 examples/app-router-example.md (7 references, 78 lines)
|
||||
📄 guides/setting-up-nextjs.md (2 references, 132 lines)
|
||||
📄 errors/nextjs-errors.md (1 reference, 98 lines)
|
||||
📄 lookup/nextjs-commands.md (4 references, 54 lines)
|
||||
|
||||
Total impact: 17 references across 5 files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Preview Changes (APPROVAL REQUIRED)
|
||||
**Action**: Show line-by-line diff for each file
|
||||
|
||||
**Format**:
|
||||
```
|
||||
Proposed updates:
|
||||
|
||||
━━━ concepts/routing.md ━━━
|
||||
|
||||
Line 15:
|
||||
- App router is optional (use pages/ or app/)
|
||||
+ App router is now default in Next.js 15 (pages/ still supported)
|
||||
|
||||
Line 42:
|
||||
+ ## Metadata API (New in v15)
|
||||
+ Next.js 15 introduces new metadata API...
|
||||
|
||||
━━━ examples/app-router-example.md ━━━
|
||||
|
||||
Line 8:
|
||||
- // Optional: use app router
|
||||
+ // Default in Next.js 15+
|
||||
|
||||
Preview next file? (yes/no/show-all)
|
||||
Approve changes? (yes/no/edit):
|
||||
```
|
||||
|
||||
**Edit mode**: Line-by-line approval for each change
|
||||
|
||||
**Validation**: MUST get approval before proceeding
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Backup
|
||||
**Action**: Create backup before updating
|
||||
|
||||
**Location**: `.tmp/backup/update-{topic}-{timestamp}/`
|
||||
|
||||
**Purpose**: Enable rollback if updates cause issues
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Update Files
|
||||
**Action**: Apply approved changes
|
||||
|
||||
**Process**:
|
||||
1. Update concepts, examples, guides, lookups
|
||||
2. Maintain MVI format (<200 lines)
|
||||
3. Update "Last Updated" dates
|
||||
4. Preserve file structure
|
||||
|
||||
**Enforcement**: `@critical_rules.mvi_strict`
|
||||
|
||||
---
|
||||
|
||||
### Stage 6: Add Migration Notes
|
||||
**Action**: Add migration guide to errors/
|
||||
|
||||
**Format**:
|
||||
```markdown
|
||||
## Migration: {Old Version} → {New Version}
|
||||
|
||||
**Breaking Changes**:
|
||||
- Change 1
|
||||
- Change 2
|
||||
|
||||
**Migration Steps**:
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
|
||||
**Reference**: [Link to changelog]
|
||||
```
|
||||
|
||||
**Location**: `{category}/errors/{topic}-errors.md`
|
||||
|
||||
---
|
||||
|
||||
### Stage 7: Validate
|
||||
**Action**: Check all references and links
|
||||
|
||||
**Checks**:
|
||||
- All internal references still work
|
||||
- No broken links
|
||||
- All files still <200 lines
|
||||
- MVI format maintained
|
||||
|
||||
---
|
||||
|
||||
### Stage 8: Report
|
||||
**Action**: Show comprehensive results
|
||||
|
||||
**Format**:
|
||||
```
|
||||
✅ Updated X files
|
||||
📝 Modified Y references
|
||||
🔄 Added migration notes to errors/
|
||||
💾 Backup: .tmp/backup/update-{topic}-{timestamp}/
|
||||
|
||||
Summary of changes:
|
||||
- concepts/routing.md: 2 updates (145 → 162 lines)
|
||||
- examples/app-router-example.md: 4 updates (78 → 89 lines)
|
||||
- guides/setting-up-nextjs.md: 1 update (132 → 133 lines)
|
||||
|
||||
All files still under 200 line limit ✓
|
||||
|
||||
Rollback available if needed.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Change Types
|
||||
|
||||
### API Changes
|
||||
- Method signatures changed
|
||||
- Parameters added/removed
|
||||
- Return types changed
|
||||
|
||||
### Deprecations
|
||||
- Features marked deprecated
|
||||
- Replacement APIs available
|
||||
- Timeline for removal
|
||||
|
||||
### New Features
|
||||
- New capabilities added
|
||||
- New APIs introduced
|
||||
- New patterns available
|
||||
|
||||
### Breaking Changes
|
||||
- Incompatible changes
|
||||
- Migration required
|
||||
- Old code won't work
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Framework Update
|
||||
```bash
|
||||
/context update for Next.js 15
|
||||
/context update for React 19
|
||||
```
|
||||
|
||||
### API Changes
|
||||
```bash
|
||||
/context update for Stripe API v2024
|
||||
/context update for OpenAI API breaking changes
|
||||
```
|
||||
|
||||
### Library Update
|
||||
```bash
|
||||
/context update for Tailwind CSS v4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] User described changes?
|
||||
- [ ] All affected files found?
|
||||
- [ ] Diff preview shown?
|
||||
- [ ] User approved changes?
|
||||
- [ ] Backup created?
|
||||
- [ ] Migration notes added?
|
||||
- [ ] All references validated?
|
||||
- [ ] All files still <200 lines?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- guides/workflows.md - Interactive diff examples
|
||||
- standards/mvi.md - Maintain MVI format
|
||||
- operations/error.md - Adding migration notes
|
||||
@@ -0,0 +1,145 @@
|
||||
<!-- Context: core/codebase-references | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Codebase References
|
||||
|
||||
**Purpose**: Link context files to actual code implementation
|
||||
|
||||
**Last Updated**: 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
<rule id="link_to_code" enforcement="critical">
|
||||
ALL context files SHOULD include `📂 Codebase References` section linking to relevant code.
|
||||
Use sections that apply to your context type (not all files need all sections).
|
||||
</rule>
|
||||
|
||||
**Why**: Agents need to find actual implementation, not just read about it.
|
||||
|
||||
---
|
||||
|
||||
## Section Types (Use What's Relevant)
|
||||
|
||||
### Business Domain Context
|
||||
```markdown
|
||||
**Business Logic**: (MOST IMPORTANT for business domains)
|
||||
- `src/orders/rules/validation-rules.ts` - Order validation business rules
|
||||
|
||||
**Implementation**:
|
||||
- `src/orders/order-processor.ts` - Main order processing logic
|
||||
|
||||
**Models/Types**:
|
||||
- `src/orders/models/order.model.ts` - Order data model
|
||||
|
||||
**Tests**:
|
||||
- `src/orders/__tests__/processor.test.ts` - Order processing tests
|
||||
|
||||
**Configuration**:
|
||||
- `config/orders.config.ts` - Order processing config
|
||||
```
|
||||
|
||||
### Technical/Code Context
|
||||
```markdown
|
||||
**Implementation**: (MOST IMPORTANT for technical contexts)
|
||||
- `src/auth/jwt-handler.ts` - JWT authentication implementation
|
||||
|
||||
**Examples**:
|
||||
- `src/auth/examples/jwt-example.ts` - Working JWT example
|
||||
|
||||
**Types**:
|
||||
- `src/auth/types/jwt-payload.ts` - JWT payload types
|
||||
|
||||
**Tests**:
|
||||
- `src/auth/__tests__/jwt.test.ts` - JWT tests
|
||||
```
|
||||
|
||||
### Standards/Quality Context
|
||||
```markdown
|
||||
**Validation/Enforcement**: (MOST IMPORTANT for standards)
|
||||
- `scripts/validate-code-quality.ts` - Code quality validator
|
||||
- `eslint.config.js` - ESLint rules
|
||||
|
||||
**Examples**:
|
||||
- `examples/good-code.ts` - Good code example
|
||||
- `examples/bad-code.ts` - Anti-pattern example
|
||||
|
||||
**Tests**:
|
||||
- `tests/code-quality.test.ts` - Quality validation tests
|
||||
```
|
||||
|
||||
### Operational Context
|
||||
```markdown
|
||||
**Scripts/Tools**: (MOST IMPORTANT for operations)
|
||||
- `scripts/deploy.sh` - Deployment script
|
||||
- `scripts/monitor.ts` - Monitoring setup
|
||||
|
||||
**Configuration**:
|
||||
- `config/deployment.config.ts` - Deployment configuration
|
||||
- `.github/workflows/deploy.yml` - CI/CD workflow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
<rule id="path_format" enforcement="strict">
|
||||
1. Use project-relative paths (src/..., not /Users/...)
|
||||
2. Use forward slashes (/)
|
||||
3. Include file extension (.ts, .js, .sh)
|
||||
4. Brief description (3-10 words) for each file
|
||||
5. Verify files exist (warn if not found)
|
||||
6. Use relevant sections only (not all files need all sections)
|
||||
</rule>
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Business Context**:
|
||||
```markdown
|
||||
## 📂 Codebase References
|
||||
|
||||
**Business Logic**:
|
||||
- `src/payments/rules/validation-rules.ts` - Card validation rules
|
||||
- `src/payments/rules/fraud-detection.ts` - Fraud detection logic
|
||||
|
||||
**Implementation**:
|
||||
- `src/payments/payment-processor.ts` - Main payment processing
|
||||
|
||||
**Tests**:
|
||||
- `src/payments/__tests__/processor.test.ts` - Payment tests
|
||||
```
|
||||
|
||||
**Technical Context**:
|
||||
```markdown
|
||||
## 📂 Codebase References
|
||||
|
||||
**Implementation**:
|
||||
- `src/auth/jwt-handler.ts` - JWT authentication
|
||||
|
||||
**Examples**:
|
||||
- `examples/jwt-auth.ts` - Working example
|
||||
|
||||
**Tests**:
|
||||
- `src/auth/__tests__/jwt.test.ts` - JWT tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] Has "📂 Codebase References" section?
|
||||
- [ ] Most important section for context type included?
|
||||
- [ ] Paths are project-relative?
|
||||
- [ ] Paths include extensions?
|
||||
- [ ] Each path has 3-10 word description?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- frontmatter.md - Frontmatter format
|
||||
- templates.md - File templates
|
||||
- structure.md - File organization
|
||||
- templates/ - File templates with codebase references
|
||||
@@ -0,0 +1,64 @@
|
||||
# Frontmatter Format
|
||||
|
||||
**Purpose**: HTML comment frontmatter format for all context files
|
||||
|
||||
**Last Updated**: 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Format
|
||||
|
||||
<rule id="frontmatter_required" enforcement="strict">
|
||||
ALL context files MUST start with:
|
||||
|
||||
```markdown
|
||||
<!-- Context: {category}/{function} | Priority: {level} | Version: X.Y | Updated: YYYY-MM-DD -->
|
||||
```
|
||||
</rule>
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
**Category/Function**: `{category}/{function}`
|
||||
- Examples: `ecommerce/concepts`, `development/examples`, `core/standards`
|
||||
- Category = domain (ecommerce, payments, development)
|
||||
- Function = file type (concepts, examples, guides, lookup, errors)
|
||||
|
||||
**Priority**: `critical` | `high` | `medium` | `low`
|
||||
- critical: 80% of use cases (business logic, core concepts)
|
||||
- high: 15% of use cases (common workflows, examples)
|
||||
- medium: 4% of use cases (edge cases)
|
||||
- low: 1% of use cases (rare scenarios)
|
||||
|
||||
**Version**: `X.Y` (start 1.0, increment on changes)
|
||||
|
||||
**Updated**: `YYYY-MM-DD` (ISO 8601, must match metadata section)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
```markdown
|
||||
<!-- Context: ecommerce/concepts | Priority: critical | Version: 1.0 | Updated: 2026-01-27 -->
|
||||
<!-- Context: payments/guides | Priority: high | Version: 1.2 | Updated: 2026-01-27 -->
|
||||
<!-- Context: development/examples | Priority: medium | Version: 1.0 | Updated: 2026-01-27 -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] Frontmatter is first line?
|
||||
- [ ] Format exact: `<!-- Context: ... -->`?
|
||||
- [ ] Priority is critical|high|medium|low?
|
||||
- [ ] Version is X.Y?
|
||||
- [ ] Date is YYYY-MM-DD?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- structure.md - File organization
|
||||
- templates.md - File templates
|
||||
- codebase-references.md - Linking to code
|
||||
151
.opencode/context/core/context-system/standards/mvi.md
Normal file
151
.opencode/context/core/context-system/standards/mvi.md
Normal file
@@ -0,0 +1,151 @@
|
||||
<!-- Context: core/mvi | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# MVI Principle (Minimal Viable Information)
|
||||
|
||||
**Purpose**: Extract only core concepts, not verbose explanations
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
|
||||
Extract the **minimum information** needed for an AI agent to understand and use a concept:
|
||||
- Core concept (1-3 sentences)
|
||||
- Key points (3-5 bullets)
|
||||
- Minimal working example
|
||||
- Reference link to full docs
|
||||
|
||||
**Goal**: Scannable in <30 seconds. Reference full docs, don't duplicate them.
|
||||
|
||||
---
|
||||
|
||||
## The Formula
|
||||
|
||||
```
|
||||
Core Concept (1-3 sentences)
|
||||
↓
|
||||
Key Points (3-5 bullets)
|
||||
↓
|
||||
Quick Example (5-10 lines)
|
||||
↓
|
||||
Reference Link (full docs)
|
||||
↓
|
||||
Related Files (cross-refs)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What to Extract ✅
|
||||
|
||||
- **Core definitions** - What it is (1-3 sentences)
|
||||
- **Key properties** - Essential characteristics (3-5 bullets)
|
||||
- **Minimal example** - Simplest working code (5-10 lines)
|
||||
- **Common patterns** - How it's typically used (2-3 bullets)
|
||||
- **Critical gotchas** - Must-know issues (1-2 bullets)
|
||||
- **Reference links** - Where to learn more
|
||||
|
||||
---
|
||||
|
||||
## What to Skip ❌
|
||||
|
||||
- **Verbose explanations** - Link to docs instead
|
||||
- **Complete API docs** - Summarize + reference
|
||||
- **Implementation details** - Show minimal example + reference
|
||||
- **Historical context** - Unless critical to understanding
|
||||
- **Marketing content** - Just the facts
|
||||
- **Duplicate information** - Say it once, reference elsewhere
|
||||
|
||||
---
|
||||
|
||||
## Example: JWT Authentication
|
||||
|
||||
### ❌ Too Verbose (400+ lines)
|
||||
```markdown
|
||||
# JWT Authentication
|
||||
|
||||
JSON Web Tokens (JWT) are an open standard (RFC 7519) that defines
|
||||
a compact and self-contained way for securely transmitting information
|
||||
between parties as a JSON object. This information can be verified and
|
||||
trusted because it is digitally signed. JWTs can be signed using a
|
||||
secret (with the HMAC algorithm) or a public/private key pair using RSA
|
||||
or ECDSA.
|
||||
|
||||
[... 400 more lines of explanation, examples, edge cases ...]
|
||||
```
|
||||
|
||||
### ✅ MVI Compliant (~50 lines)
|
||||
```markdown
|
||||
# Concept: JWT Authentication
|
||||
|
||||
**Core Idea**: Stateless authentication using JSON Web Tokens signed
|
||||
with a secret key. Token contains user data (payload) that server can
|
||||
trust because signature is verified.
|
||||
|
||||
**Key Points**:
|
||||
- Token has 3 parts: header.payload.signature (Base64 encoded)
|
||||
- Server verifies signature to trust payload without database lookup
|
||||
- No session storage needed (stateless)
|
||||
- Tokens expire (include `exp` claim)
|
||||
- Store in httpOnly cookie or Authorization header
|
||||
|
||||
**Quick Example**:
|
||||
```js
|
||||
// Sign token
|
||||
const token = jwt.sign(
|
||||
{ userId: 123, role: 'admin' },
|
||||
SECRET_KEY,
|
||||
{ expiresIn: '1h' }
|
||||
)
|
||||
|
||||
// Verify token
|
||||
const decoded = jwt.verify(token, SECRET_KEY)
|
||||
console.log(decoded.userId) // 123
|
||||
```
|
||||
|
||||
**Reference**: https://jwt.io/introduction
|
||||
|
||||
**Related**:
|
||||
- examples/jwt-auth-example.md
|
||||
- guides/implementing-jwt.md
|
||||
- errors/auth-errors.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Size Limits
|
||||
|
||||
<rule id="size_limits" enforcement="strict">
|
||||
- Concept files: max 100 lines
|
||||
- Example files: max 80 lines
|
||||
- Guide files: max 150 lines
|
||||
- Lookup files: max 100 lines
|
||||
- Error files: max 150 lines
|
||||
- README files: max 100 lines
|
||||
</rule>
|
||||
|
||||
**Why**: Forces brevity. If you need more, split into multiple files or reference external docs.
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before creating a context file, verify:
|
||||
|
||||
- [ ] Core concept is 1-3 sentences?
|
||||
- [ ] Key points are 3-5 bullets?
|
||||
- [ ] Example is <10 lines of code?
|
||||
- [ ] Reference link is included?
|
||||
- [ ] File is <200 lines total?
|
||||
- [ ] Can be scanned in <30 seconds?
|
||||
|
||||
If any answer is "no", apply more compression.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- structure.md - Where files go
|
||||
- compact.md - How to minimize
|
||||
- templates.md - Standard formats
|
||||
- creation.md - File creation rules
|
||||
240
.opencode/context/core/context-system/standards/structure.md
Normal file
240
.opencode/context/core/context-system/standards/structure.md
Normal file
@@ -0,0 +1,240 @@
|
||||
<!-- Context: core/structure | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Structure
|
||||
|
||||
**Purpose**: Function-based folder organization for easy discovery
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## Core Structure
|
||||
|
||||
<rule id="function_structure" enforcement="strict">
|
||||
ALWAYS organize by function (what info does), not just by topic.
|
||||
|
||||
Required folders:
|
||||
- concepts/ - Core ideas, definitions, "what is it?"
|
||||
- examples/ - Minimal working code
|
||||
- guides/ - Step-by-step workflows
|
||||
- lookup/ - Quick reference tables, commands, paths
|
||||
- errors/ - Common issues, gotchas, fixes
|
||||
</rule>
|
||||
|
||||
```
|
||||
.opencode/context/{category}/
|
||||
├── navigation.md # Navigation map (REQUIRED)
|
||||
├── concepts/ # What it is
|
||||
│ └── {topic}.md
|
||||
├── examples/ # Working code
|
||||
│ └── {example}.md
|
||||
├── guides/ # How to do it
|
||||
│ └── {guide}.md
|
||||
├── lookup/ # Quick reference
|
||||
│ └── {reference}.md
|
||||
└── errors/ # Common issues
|
||||
└── {framework}.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Folder Purposes
|
||||
|
||||
### concepts/
|
||||
**Purpose**: Core ideas, definitions, "what is it?"
|
||||
|
||||
**Contains**:
|
||||
- Fundamental concepts
|
||||
- Design patterns
|
||||
- Architecture decisions
|
||||
- System principles
|
||||
|
||||
**Examples**:
|
||||
- `concepts/authentication.md`
|
||||
- `concepts/state-management.md`
|
||||
- `concepts/mvi-principle.md`
|
||||
|
||||
---
|
||||
|
||||
### examples/
|
||||
**Purpose**: Minimal working code examples
|
||||
|
||||
**Contains**:
|
||||
- Code snippets that work as-is
|
||||
- Minimal reproductions
|
||||
- Common patterns in action
|
||||
|
||||
**Examples**:
|
||||
- `examples/jwt-auth-example.md`
|
||||
- `examples/react-hooks-example.md`
|
||||
- `examples/api-call-example.md`
|
||||
|
||||
**Rule**: Examples should be <30 lines of code, fully functional
|
||||
|
||||
---
|
||||
|
||||
### guides/
|
||||
**Purpose**: Step-by-step workflows, "how to do X"
|
||||
|
||||
**Contains**:
|
||||
- Numbered procedures
|
||||
- Setup instructions
|
||||
- Implementation workflows
|
||||
- Migration guides
|
||||
|
||||
**Examples**:
|
||||
- `guides/setting-up-auth.md`
|
||||
- `guides/deploying-api.md`
|
||||
- `guides/migrating-to-v2.md`
|
||||
|
||||
**Rule**: Steps should be actionable (not theoretical)
|
||||
|
||||
---
|
||||
|
||||
### lookup/
|
||||
**Purpose**: Quick reference tables, commands, paths
|
||||
|
||||
**Contains**:
|
||||
- Command lists
|
||||
- File locations
|
||||
- API endpoints
|
||||
- Configuration options
|
||||
- Keyboard shortcuts
|
||||
|
||||
**Examples**:
|
||||
- `lookup/cli-commands.md`
|
||||
- `lookup/file-locations.md`
|
||||
- `lookup/api-endpoints.md`
|
||||
|
||||
**Rule**: Must be in table/list format (scannable)
|
||||
|
||||
---
|
||||
|
||||
### errors/
|
||||
**Purpose**: Common errors, gotchas, edge cases
|
||||
|
||||
**Contains**:
|
||||
- Error messages + fixes
|
||||
- Common pitfalls
|
||||
- Edge cases
|
||||
- Troubleshooting
|
||||
|
||||
**Examples**:
|
||||
- `errors/react-errors.md`
|
||||
- `errors/nextjs-build-errors.md`
|
||||
- `errors/auth-errors.md`
|
||||
|
||||
**Rule**: Group by framework/topic, not one file per error
|
||||
|
||||
---
|
||||
|
||||
## navigation.md Requirement
|
||||
|
||||
<rule id="readme_required" enforcement="strict">
|
||||
Every context category MUST have navigation.md at its root with:
|
||||
1. Purpose (1-2 sentences)
|
||||
2. Navigation tables for each function folder
|
||||
3. Priority levels (critical/high/medium/low)
|
||||
4. Loading strategy (what to load for common tasks)
|
||||
</rule>
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
# Development Context
|
||||
|
||||
**Purpose**: Core development patterns, errors, and examples
|
||||
|
||||
---
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### Concepts
|
||||
| File | Description | Priority |
|
||||
|------|-------------|----------|
|
||||
| concepts/auth.md | Authentication patterns | critical |
|
||||
|
||||
### Examples
|
||||
| File | Description | Priority |
|
||||
|------|-------------|----------|
|
||||
| examples/jwt.md | JWT auth example | high |
|
||||
|
||||
### Errors
|
||||
| File | Description | Priority |
|
||||
|------|-------------|----------|
|
||||
| errors/react.md | Common React errors | high |
|
||||
|
||||
---
|
||||
|
||||
## Loading Strategy
|
||||
|
||||
**For auth work**:
|
||||
1. Load concepts/auth.md
|
||||
2. Load examples/jwt.md
|
||||
3. Reference guides/setup-auth.md if needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Categorization Rules
|
||||
|
||||
When organizing a file, ask:
|
||||
|
||||
| Question | Folder |
|
||||
|----------|--------|
|
||||
| Does it explain **what** something is? | `concepts/` |
|
||||
| Does it show **working code**? | `examples/` |
|
||||
| Does it explain **how to do** something? | `guides/` |
|
||||
| Is it **quick reference** data? | `lookup/` |
|
||||
| Does it document an **error/issue**? | `errors/` |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns ❌
|
||||
|
||||
### ❌ Flat Structure
|
||||
```
|
||||
development/
|
||||
├── authentication.md
|
||||
├── jwt-example.md
|
||||
├── setting-up-auth.md
|
||||
├── auth-errors.md
|
||||
└── api-endpoints.md
|
||||
```
|
||||
**Problem**: Hard to discover. Is authentication.md a concept or guide?
|
||||
|
||||
### ✅ Function-Based
|
||||
```
|
||||
development/
|
||||
├── navigation.md
|
||||
├── concepts/
|
||||
│ └── authentication.md
|
||||
├── examples/
|
||||
│ └── jwt-example.md
|
||||
├── guides/
|
||||
│ └── setting-up-auth.md
|
||||
├── lookup/
|
||||
│ └── api-endpoints.md
|
||||
└── errors/
|
||||
└── auth-errors.md
|
||||
```
|
||||
**Benefit**: Instantly know file purpose by location
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
Before committing context structure:
|
||||
|
||||
- [ ] All categories have navigation.md?
|
||||
- [ ] Files are in function folders (not flat)?
|
||||
- [ ] README has navigation tables?
|
||||
- [ ] Priority levels assigned?
|
||||
- [ ] Loading strategy documented?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- mvi-principle.md - What to extract
|
||||
- templates.md - File formats
|
||||
- creation.md - How to create files
|
||||
396
.opencode/context/core/context-system/standards/templates.md
Normal file
396
.opencode/context/core/context-system/standards/templates.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# Context File Templates
|
||||
|
||||
**Purpose**: Standard formats for all context file types
|
||||
|
||||
**Last Updated**: 2026-01-06
|
||||
|
||||
---
|
||||
|
||||
## Template Selection
|
||||
|
||||
| Type | Max Lines | Required Sections |
|
||||
|------|-----------|-------------------|
|
||||
| Concept | 100 | Purpose, Core Idea (1-3 sentences), Key Points (3-5), Example (<10 lines), Reference, Related |
|
||||
| Example | 80 | Purpose, Use Case, Code (10-30 lines), Explanation, Related |
|
||||
| Guide | 150 | Purpose, Prerequisites, Steps (4-7), Verification, Related |
|
||||
| Lookup | 100 | Purpose, Tables/Lists, Commands, Related |
|
||||
| Error | 150 | Purpose, Per-error: Symptom, Cause, Solution, Prevention, Reference, Related |
|
||||
| README | 100 | Purpose, Navigation tables (all 5 folders), Loading Strategy, Statistics |
|
||||
|
||||
---
|
||||
|
||||
## 1. Concept Template
|
||||
|
||||
```markdown
|
||||
<!-- Context: {category}/concepts | Priority: {critical|high|medium|low} | Version: 1.0 | Updated: YYYY-MM-DD -->
|
||||
# Concept: {Name}
|
||||
|
||||
**Purpose**: [1 sentence]
|
||||
**Last Updated**: {YYYY-MM-DD}
|
||||
|
||||
## Core Idea
|
||||
[1-3 sentences]
|
||||
|
||||
## Key Points
|
||||
- Point 1
|
||||
- Point 2
|
||||
- Point 3
|
||||
|
||||
## When to Use
|
||||
- Use case 1
|
||||
- Use case 2
|
||||
|
||||
## Quick Example
|
||||
```lang
|
||||
[<10 lines]
|
||||
```
|
||||
|
||||
## 📂 Codebase References
|
||||
|
||||
**Business Logic** (if business domain):
|
||||
- `path/to/rules.ts` - {3-10 word description}
|
||||
|
||||
**Implementation**:
|
||||
- `path/to/main.ts` - {3-10 word description}
|
||||
|
||||
**Models/Types**:
|
||||
- `path/to/model.ts` - {3-10 word description}
|
||||
|
||||
**Tests**:
|
||||
- `path/to/test.ts` - {3-10 word description}
|
||||
|
||||
## Deep Dive
|
||||
**Reference**: [Link or "See implementation above"]
|
||||
|
||||
## Related
|
||||
- concepts/x.md
|
||||
- examples/y.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Example Template
|
||||
|
||||
```markdown
|
||||
<!-- Context: {category}/examples | Priority: {high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
|
||||
# Example: {What It Shows}
|
||||
|
||||
**Purpose**: [1 sentence]
|
||||
**Last Updated**: {YYYY-MM-DD}
|
||||
|
||||
## Use Case
|
||||
[2-3 sentences]
|
||||
|
||||
## Code
|
||||
```lang
|
||||
[10-30 lines]
|
||||
```
|
||||
|
||||
## Explanation
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Step 3
|
||||
|
||||
**Key points**:
|
||||
- Detail 1
|
||||
- Detail 2
|
||||
|
||||
## 📂 Codebase References
|
||||
|
||||
**Full Implementation**:
|
||||
- `path/to/real-implementation.ts` - {Production version}
|
||||
|
||||
**Related Code**:
|
||||
- `path/to/helper.ts` - {Helper utilities}
|
||||
|
||||
**Tests**:
|
||||
- `path/to/test.ts` - {Tests demonstrating pattern}
|
||||
|
||||
## Related
|
||||
- concepts/x.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Guide Template
|
||||
|
||||
```markdown
|
||||
<!-- Context: {category}/guides | Priority: {critical|high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
|
||||
# Guide: {Action}
|
||||
|
||||
**Purpose**: [1 sentence]
|
||||
**Last Updated**: {YYYY-MM-DD}
|
||||
|
||||
## Prerequisites
|
||||
- Requirement 1
|
||||
- Requirement 2
|
||||
|
||||
**Estimated time**: X min
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. {Step}
|
||||
```bash
|
||||
{command}
|
||||
```
|
||||
**Expected**: [result]
|
||||
**Implementation**: `path/to/step.ts`
|
||||
|
||||
### 2. {Step}
|
||||
[Repeat 4-7 steps]
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
{verify command}
|
||||
```
|
||||
|
||||
## 📂 Codebase References
|
||||
|
||||
**Workflow Orchestration**:
|
||||
- `path/to/workflow.ts` - {Main workflow coordinator}
|
||||
|
||||
**Business Logic** (if applicable):
|
||||
- `path/to/rules.ts` - {Process validation rules}
|
||||
|
||||
**Integration Points**:
|
||||
- `path/to/api-client.ts` - {External integration}
|
||||
|
||||
**Tests**:
|
||||
- `path/to/workflow.test.ts` - {End-to-end tests}
|
||||
|
||||
## Troubleshooting
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Problem | Fix |
|
||||
|
||||
## Related
|
||||
- concepts/x.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Lookup Template
|
||||
|
||||
```markdown
|
||||
<!-- Context: {category}/lookup | Priority: {high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
|
||||
# Lookup: {Reference Type}
|
||||
|
||||
**Purpose**: Quick reference for {desc}
|
||||
**Last Updated**: {YYYY-MM-DD}
|
||||
|
||||
## {Section}
|
||||
| Item | Value | Desc | Code |
|
||||
|------|-------|------|------|
|
||||
| x | y | z | `path/to/file.ts` |
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
# Description
|
||||
{command}
|
||||
```
|
||||
|
||||
## Paths
|
||||
```
|
||||
{path} - {desc}
|
||||
```
|
||||
|
||||
## 📂 Codebase References
|
||||
|
||||
**Validation/Enforcement**:
|
||||
- `path/to/validator.ts` - {Validation logic}
|
||||
|
||||
**Configuration**:
|
||||
- `path/to/config.ts` - {Configuration settings}
|
||||
|
||||
**Tests**:
|
||||
- `path/to/test.ts` - {Validation tests}
|
||||
|
||||
## Related
|
||||
- concepts/x.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Error Template
|
||||
|
||||
```markdown
|
||||
<!-- Context: {category}/errors | Priority: {high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
|
||||
# Errors: {Framework}
|
||||
|
||||
**Purpose**: Common errors for {framework}
|
||||
**Last Updated**: {YYYY-MM-DD}
|
||||
|
||||
## Error: {Name}
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
{error message}
|
||||
```
|
||||
|
||||
**Cause**: [1-2 sentences]
|
||||
|
||||
**Solution**:
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
|
||||
**Code**:
|
||||
```lang
|
||||
// ❌ Before
|
||||
{bad}
|
||||
|
||||
// ✅ After
|
||||
{fixed}
|
||||
```
|
||||
|
||||
**Prevention**: [how to avoid]
|
||||
**Frequency**: common/occasional/rare
|
||||
|
||||
**Code References**:
|
||||
- Error thrown: `path/to/error-source.ts`
|
||||
- Error handler: `path/to/error-handler.ts`
|
||||
- Prevention: `path/to/validator.ts`
|
||||
|
||||
---
|
||||
|
||||
[Repeat for 5-10 errors]
|
||||
|
||||
## 📂 Codebase References
|
||||
|
||||
**Error Definitions**:
|
||||
- `path/to/error-types.ts` - {Error class definitions}
|
||||
|
||||
**Error Handling**:
|
||||
- `path/to/error-handler.ts` - {Error handler}
|
||||
|
||||
**Prevention Logic**:
|
||||
- `path/to/validator.ts` - {Validation preventing errors}
|
||||
|
||||
**Tests**:
|
||||
- `path/to/error-handling.test.ts` - {Error handling tests}
|
||||
|
||||
## Related
|
||||
- concepts/x.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Navigation Template (Replaces README.md)
|
||||
|
||||
**Note**: Use `navigation.md` instead of `README.md` for better discoverability
|
||||
|
||||
**Target**: 200-300 tokens
|
||||
|
||||
```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}` |
|
||||
| **{Task 3}** | `{path}` |
|
||||
|
||||
---
|
||||
|
||||
## By {Concern/Type}
|
||||
|
||||
**{Section 1}** → {description}
|
||||
**{Section 2}** → {description}
|
||||
**{Section 3}** → {description}
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **{Category}** → `../{category}/navigation.md`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Specialized Navigation Template
|
||||
|
||||
**Use for**: Cross-cutting concerns (e.g., `ui-navigation.md`)
|
||||
|
||||
**Target**: 250-300 tokens
|
||||
|
||||
```markdown
|
||||
# {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})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## All Templates Must Have
|
||||
|
||||
1. Title with type prefix (# Concept:, # Example:, etc.)
|
||||
2. **Purpose** (1 sentence)
|
||||
3. **Last Updated** (YYYY-MM-DD)
|
||||
4. **Related** section (cross-references)
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] Correct template for file type?
|
||||
- [ ] Has required sections?
|
||||
- [ ] Under max line limit?
|
||||
- [ ] Cross-references added?
|
||||
- [ ] Added to README.md?
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- creation.md - When to use each template
|
||||
- mvi-principle.md - How to fill templates
|
||||
- compact.md - How to stay under limits
|
||||
Reference in New Issue
Block a user