OpenWriterControle/.opencode/context/core/workflows/external-context-management.md

External Context Management

Overview

External context is live documentation fetched from external libraries and frameworks (via Context7 API or official docs). Instead of re-fetching on every task, we persist external context to .tmp/external-context/ so main agents can pass it to subagents.

Key Principle: ExternalScout fetches once → persists to disk → main agents reference → subagents read (no re-fetching)

---

Directory Structure

.tmp/external-context/
├── .manifest.json                    # Metadata about all cached external docs
├── drizzle-orm/
│   ├── modular-schemas.md           # Fetched: "How to organize schemas modularly"
│   ├── postgresql-setup.md          # Fetched: "PostgreSQL setup with Drizzle"
│   └── typescript-config.md         # Fetched: "TypeScript configuration"
├── better-auth/
│   ├── nextjs-integration.md        # Fetched: "Better Auth + Next.js setup"
│   ├── drizzle-adapter.md           # Fetched: "Drizzle adapter for Better Auth"
│   └── session-management.md        # Fetched: "Session handling"
├── next.js/
│   ├── app-router-setup.md          # Fetched: "App Router basics"
│   ├── server-actions.md            # Fetched: "Server Actions patterns"
│   └── middleware.md                # Fetched: "Middleware configuration"
└── tanstack-query/
    ├── server-components.md         # Fetched: "TanStack Query + Server Components"
    └── prefetching.md               # Fetched: "Prefetching strategies"

Naming Conventions

• Package name (directory): Exact npm package name (kebab-case)

  • ✅ drizzle-orm, better-auth, next.js, @tanstack/react-query
  • ❌ drizzle, nextjs, tanstack-query

• File name (topic): Kebab-case description of the topic

  • ✅ modular-schemas.md, nextjs-integration.md, server-components.md
  • ❌ modular schemas.md, NextJS Integration.md, ServerComponents.md

---

Manifest File

Location: .tmp/external-context/.manifest.json

Purpose: Track what's cached, when it was fetched, and from which source

Structure:

{
  "last_updated": "2026-01-28T14:30:22Z",
  "packages": {
    "drizzle-orm": {
      "files": [
        "modular-schemas.md",
        "postgresql-setup.md",
        "typescript-config.md"
      ],
      "last_updated": "2026-01-28T14:30:22Z",
      "source": "Context7 API",
      "official_docs": "https://orm.drizzle.team"
    },
    "better-auth": {
      "files": [
        "nextjs-integration.md",
        "drizzle-adapter.md",
        "session-management.md"
      ],
      "last_updated": "2026-01-28T14:25:10Z",
      "source": "Context7 API",
      "official_docs": "https://better-auth.com"
    },
    "next.js": {
      "files": [
        "app-router-setup.md",
        "server-actions.md",
        "middleware.md"
      ],
      "last_updated": "2026-01-28T14:20:05Z",
      "source": "Context7 API",
      "official_docs": "https://nextjs.org"
    }
  }
}

---

File Format

Each external context file has a metadata header followed by the documentation content.

Template:

---
source: Context7 API
library: Drizzle ORM
package: drizzle-orm
topic: modular-schemas
fetched: 2026-01-28T14:30:22Z
official_docs: https://orm.drizzle.team/docs/goodies#multi-file-schemas
---

# Modular Schemas in Drizzle ORM

[Filtered documentation content from Context7 API]

## Key Concepts

[Relevant sections only]

## Code Examples

[Practical examples from official docs]

---

**Source**: Context7 API (live, version-specific)
**Official Docs**: https://orm.drizzle.team/docs/goodies#multi-file-schemas
**Fetched**: 2026-01-28T14:30:22Z

---

Workflow: How External Context Flows

Stage 1: Main Agent Needs External Context

Main Agent (e.g., OpenAgent)
  ↓
  Detects: "User is asking about Drizzle + Better Auth + Next.js"
  ↓
  Calls: ExternalScout to fetch live docs

Stage 2: ExternalScout Fetches & Persists

ExternalScout
  ↓
  1. Detects libraries: Drizzle, Better Auth, Next.js
  ↓
  2. Fetches from Context7 API (primary) or official docs (fallback)
  ↓
  3. Filters to relevant sections
  ↓
  4. Persists to .tmp/external-context/{package-name}/{topic}.md
  ↓
  5. Updates .manifest.json
  ↓
  Returns: File paths + formatted documentation

Stage 3: Main Agent References in Session Context

Main Agent
  ↓
  Creates session: .tmp/sessions/{session-id}/context.md
  ↓
  Adds section: "## External Context Fetched"
  ↓
  Lists files:
    - .tmp/external-context/drizzle-orm/modular-schemas.md
    - .tmp/external-context/better-auth/nextjs-integration.md
    - .tmp/external-context/next.js/app-router-setup.md
  ↓
  Delegates to TaskManager with session path

Stage 4: Subagents Read External Context

TaskManager (or CoderAgent, TestEngineer, etc.)
  ↓
  Reads: .tmp/sessions/{session-id}/context.md
  ↓
  Extracts: "## External Context Fetched" section
  ↓
  Reads: .tmp/external-context/{package-name}/{topic}.md files
  ↓
  Uses: External docs to inform implementation
  ↓
  NO RE-FETCHING needed ✅

---

Integration with Task Delegation

In Session Context File

Add this section to .tmp/sessions/{session-id}/context.md:

## External Context Fetched

These are live documentation files fetched from external libraries. Subagents should reference these instead of re-fetching.

### Drizzle ORM
- `.tmp/external-context/drizzle-orm/modular-schemas.md` — Schema organization patterns
- `.tmp/external-context/drizzle-orm/postgresql-setup.md` — PostgreSQL configuration

### Better Auth
- `.tmp/external-context/better-auth/nextjs-integration.md` — Next.js integration guide
- `.tmp/external-context/better-auth/drizzle-adapter.md` — Drizzle adapter setup

### Next.js
- `.tmp/external-context/next.js/app-router-setup.md` — App Router basics
- `.tmp/external-context/next.js/server-actions.md` — Server Actions patterns

**Important**: These files are read-only and should not be modified. They're cached for reference only.

In Subtask JSONs (Created by TaskManager)

When TaskManager creates subtask JSONs, it should include external context files:

{
  "id": "01-drizzle-schema-setup",
  "title": "Set up Drizzle schema with modular organization",
  "context_files": [
    ".opencode/context/core/standards/code-quality.md",
    ".opencode/context/core/standards/test-coverage.md"
  ],
  "reference_files": [
    "package.json",
    "src/db/schema.ts"
  ],
  "external_context": [
    ".tmp/external-context/drizzle-orm/modular-schemas.md",
    ".tmp/external-context/drizzle-orm/postgresql-setup.md"
  ],
  "instructions": "Set up Drizzle schema following modular patterns from external context..."
}

---

Cleanup & Maintenance

When to Clean Up

External context files should be cleaned up when:

1. Task is complete and session is deleted
2. External docs become stale (>7 days old)
3. User explicitly requests cleanup
4. Disk space is needed

How to Clean Up

Manual cleanup (ask user first):

rm -rf .tmp/external-context/{package-name}/
# Update .manifest.json to remove package entry

Automatic cleanup (future enhancement):

• Add cleanup script that removes files older than 7 days
• Run as part of session cleanup process
• Update manifest after cleanup

Manifest Cleanup

After deleting external context files, update .manifest.json:

{
  "last_updated": "2026-01-28T15:00:00Z",
  "packages": {
    // Remove entries for deleted packages
  }
}

---

Best Practices

For Main Agents (OpenAgent, etc.)

1. Call ExternalScout early in the planning phase
2. Capture returned file paths from ExternalScout
3. Add to session context in "## External Context Fetched" section
4. Pass session path to subagents so they know where to find external docs
5. Don't re-fetch — trust that ExternalScout persisted correctly

For ExternalScout

1. Always persist fetched documentation to .tmp/external-context/
2. Update manifest after each fetch
3. Include metadata header in every file (source, library, package, topic, fetched timestamp)
4. Filter aggressively — only include relevant sections
5. Cite sources — include official docs links

For Subagents (TaskManager, CoderAgent, etc.)

1. Read external context files from session context
2. Don't re-fetch — use persisted files
3. Reference in implementation — cite which external docs informed decisions
4. Don't modify external context files — they're read-only
5. Include in subtask JSONs — pass external_context to downstream agents

---

Examples

Example 1: Drizzle + Better Auth Integration

Main Agent Flow:

1. User asks: "Set up Drizzle + Better Auth in Next.js"
2. Main agent calls ExternalScout
3. ExternalScout fetches:
   - drizzle-orm/modular-schemas.md
   - drizzle-orm/postgresql-setup.md
   - better-auth/nextjs-integration.md
   - better-auth/drizzle-adapter.md
   - next.js/app-router-setup.md
4. ExternalScout persists all files to .tmp/external-context/
5. Main agent creates session with "## External Context Fetched" section
6. Main agent delegates to TaskManager with session path
7. TaskManager reads external context, creates subtasks
8. CoderAgent implements using external docs (no re-fetching)

Session Context File:

## External Context Fetched

### Drizzle ORM
- `.tmp/external-context/drizzle-orm/modular-schemas.md`
- `.tmp/external-context/drizzle-orm/postgresql-setup.md`

### Better Auth
- `.tmp/external-context/better-auth/nextjs-integration.md`
- `.tmp/external-context/better-auth/drizzle-adapter.md`

### Next.js
- `.tmp/external-context/next.js/app-router-setup.md`

Example 2: TanStack Query + Server Components

Main Agent Flow:

1. User asks: "How do I use TanStack Query with Next.js Server Components?"
2. Main agent calls ExternalScout
3. ExternalScout fetches:
   - tanstack-query/server-components.md
   - tanstack-query/prefetching.md
   - next.js/server-components.md
4. ExternalScout persists to .tmp/external-context/
5. Main agent creates session with external context references
6. Subagents read and implement using external docs

---

Troubleshooting

External Context Files Not Found

Problem: Subagent can't find .tmp/external-context/{package-name}/{topic}.md

Solution:

1. Check that ExternalScout ran successfully
2. Verify file path in session context matches actual file location
3. Check .manifest.json to see what's cached
4. If missing, re-run ExternalScout to fetch and persist

Stale External Context

Problem: External docs are outdated (>7 days old)

Solution:

1. Delete stale files: rm -rf .tmp/external-context/{package-name}/
2. Update .manifest.json
3. Re-run ExternalScout to fetch fresh docs
4. Update session context with new file paths

Manifest Out of Sync

Problem: .manifest.json doesn't match actual files

Solution:

1. Regenerate manifest by listing actual files:

   find .tmp/external-context -name "*.md" | sort
   

2. Update .manifest.json to match
3. Verify all files have metadata headers

---

References

• ExternalScout: .opencode/agent/subagents/core/externalscout.md — Fetches and persists external docs
• Task Delegation: .opencode/context/core/workflows/task-delegation-basics.md — How to reference external context in sessions
• Session Management: .opencode/context/core/workflows/session-management.md — Session lifecycle
• Library Registry: .opencode/skills/context7/library-registry.md — Supported libraries and query patterns