chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
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
|
||||
Reference in New Issue
Block a user