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