OpenAgentsControl/.opencode/context/core/context-system/guides/creation.md

Context File Creation Standards

Purpose: Ensure all context files follow the same format and structure

Last Updated: 2026-01-06

---

Critical Rules

Files MUST be <200 lines. No exceptions.

All files MUST follow MVI: 1-3 sentence core, 3-5 key points, minimal example, reference link.

Files MUST be in correct function folder: concepts/, examples/, guides/, lookup/, or errors/.

MUST update category README.md navigation when creating files.

---

Creation Workflow

Ask: Is this a concept, example, guide, lookup, or error?
→ Place in correct folder

Use standard template for file type (see templates.md)

- Core: 1-3 sentences
- Key points: 3-5 bullets
- Example: <10 lines
- Reference: Link to docs

Ensure file <200 lines. If not, split or reference external.

Link to related concepts/, examples/, guides/, errors/

MUST show full preview before writing ANY files:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Preview: File Creation Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CREATE file:
  {category}/{function}/{filename}.md ({line_count} lines)

Content preview:
┌─────────────────────────────────────────────────────────┐
│ # {Type}: {Name}                                        │
│                                                         │
│ **Purpose**: {1 sentence}                               │
│ **Last Updated**: {date}                                │
│                                                         │
│ ## Core Concept                                         │
│ {1-3 sentences}                                         │
│                                                         │
│ ## Key Points                                           │
│ {3-5 bullets}                                           │
│ ...                                                     │
└─────────────────────────────────────────────────────────┘

UPDATE navigation:
  {category}/navigation.md
    + | [{filename}.md]({function}/{filename}.md) | {desc} | {priority} |

Validation:
  ✓ {line_count} lines (limit: {max_lines} for {type})
  ✓ MVI format applied
  ✓ Correct folder: {function}/
  ✓ Cross-references: {count} links added

Approve? [y/n/edit]: _
```

If file already exists at target path:
```
⚠️  File already exists: {category}/{function}/{filename}.md

Options:
  1. Cancel (keep existing)
  2. Show diff (compare existing vs new)
  3. Overwrite (replace existing)
  4. Rename new file to {filename}-v2.md

Choose [1/2/3/4]: _
```

Only after approval:
1. Write file to disk
2. Update navigation.md
3. Show confirmation:

```
✅ Created: {category}/{function}/{filename}.md ({line_count} lines)
✅ Updated: {category}/navigation.md
```

- [ ] <200 lines?
- [ ] MVI format?
- [ ] Correct folder?
- [ ] navigation.md updated?
- [ ] Cross-refs added?

---

File Naming Conventions

Concepts

Format: {topic}.md Examples:

• authentication.md
• state-management.md
• mvi-principle.md

Rule: Lowercase, hyphenated, describes the concept

---

Examples

Format: {what-it-demonstrates}.md Examples:

• jwt-auth-example.md
• react-hooks-example.md
• api-call-example.md

Rule: End with -example.md, describes what it shows

---

Guides

Format: {action-being-done}.md Examples:

• setting-up-auth.md
• deploying-api.md
• migrating-to-v2.md

Rule: Gerund form (verbs ending in -ing), describes the task

---

Lookup

Format: {what-is-referenced}.md Examples:

• cli-commands.md
• file-locations.md
• api-endpoints.md

Rule: Plural noun, describes the reference type

---

Errors

Format: {framework-or-topic}-errors.md Examples:

• react-errors.md
• nextjs-build-errors.md
• auth-errors.md

Rule: End with -errors.md, group by framework/topic (NOT one file per error)

---

Standard Metadata

Every context file MUST start with:

# {Type}: {Name}

**Purpose**: [1 sentence describing what this file contains]

**Last Updated**: {YYYY-MM-DD}

---

Example:

# Concept: JWT Authentication

**Purpose**: Stateless authentication using signed JSON Web Tokens

**Last Updated**: 2026-01-06

---

---

Priority Assignment

When adding files to README.md, assign priority:

Priority	When to Use
critical	Must understand to work on project. Core concepts.
high	Commonly used. Important patterns.
medium	Occasionally needed. Reference material.
low	Rarely used. Edge cases.

Example:

### Concepts
| File | Description | Priority |
|------|-------------|----------|
| [auth.md](concepts/auth.md) | Authentication system | critical |
| [caching.md](concepts/caching.md) | Cache strategy | high |
| [logging.md](concepts/logging.md) | Logging patterns | medium |

---

Cross-Reference Guidelines

When to Link

Link to related files when:

• Concept uses another concept
• Example demonstrates a concept
• Guide references concepts/examples
• Error relates to specific concept

How to Link

Format: **Related**: type/file.md

Example:

**Related**:
- concepts/authentication.md
- examples/jwt-auth-example.md
- errors/auth-errors.md

Rule: Use relative paths from current location

---

README.md Update Process

When creating a new file:

1. Open category README.md
2. Find correct section (Concepts/Examples/Guides/Lookup/Errors)
3. Add table row: markdown | [file.md](folder/file.md) | Description | priority |
4. Sort by priority (critical → high → medium → low)
5. Update "Last Updated" date at top

---

Validation Before Commit

- [ ] File is <200 lines?
- [ ] Follows MVI format (1-3 sentences, 3-5 points, example, reference)?
- [ ] In correct function folder (concepts/examples/guides/lookup/errors)?
- [ ] Has standard metadata (Purpose, Last Updated)?
- [ ] Added to navigation.md navigation?
- [ ] Priority assigned (critical/high/medium/low)?
- [ ] Cross-references added?
- [ ] Scannable in <30 seconds?
- [ ] No duplication of existing content?

If any checkbox is unchecked, fix before committing.

---

Common Creation Mistakes

❌ Mistake 1: Wrong Folder

development/authentication.md  ❌ (flat structure)

development/concepts/authentication.md  ✅ (function-based)

❌ Mistake 2: Too Verbose

# Concept: JWT

[500 lines of explanation, examples, edge cases...]  ❌

# Concept: JWT

**Core Idea**: Stateless auth with signed tokens (1-3 sentences)  ✅

❌ Mistake 3: Missing README Update

Created: concepts/new-topic.md
README.md: Not updated  ❌

Created: concepts/new-topic.md
README.md: Updated with navigation entry  ✅

❌ Mistake 4: One Error Per File

errors/jwt-expired-error.md
errors/jwt-invalid-error.md
errors/jwt-missing-error.md  ❌ (too granular)

errors/auth-errors.md  ✅ (grouped by topic)

---

File Size Enforcement

If file exceeds line limit:

1. First: Apply more compression (see compact.md)
2. If still too large: Split into multiple files
3. If logically can't split: Move details to external docs, keep summary
   

DO NOT exceed 200 lines under any circumstance.

Example:

If concepts/authentication.md hits 250 lines:

Option 1: Compress (apply MVI more strictly)
Option 2: Split:
  - concepts/authentication.md (core)
  - concepts/jwt-tokens.md (specific type)
  - concepts/oauth.md (another type)
Option 3: Reference external:
  - Keep 100-line summary in concepts/authentication.md
  - Link to https://docs.company.com/auth (full details)

---

Template Selection

File Type	Template	Max Lines
Concept	templates.md → Concept Template	100
Example	templates.md → Example Template	80
Guide	templates.md → Guide Template	150
Lookup	templates.md → Lookup Template	100
Error	templates.md → Error Template	150
README	templates.md → README Template	100

---

Quality Standards

Every context file must be:

1. Minimal - <200 lines, no bloat
2. Scannable - Can grasp in <30 seconds
3. Functional - In correct function folder
4. Referenced - Cross-links to related files
5. Discoverable - Listed in README.md
6. Accurate - Facts only, no speculation
7. Current - Last Updated date maintained

---

Related

• templates.md - Standard file formats
• mvi-principle.md - What to include
• compact.md - How to minimize
• structure.md - Where files go