OpenAgentsControl/.opencode/context/core/workflows/external-context-integration.md

External Context Integration Guide

Overview

This guide explains how to integrate external context (fetched via ExternalScout) into the main agent workflow so that subagents can access it without re-fetching.

Key Principle: Main agents fetch external docs once → persist to disk → reference in session → subagents read (no re-fetching)

---

When to Use External Context

Use ExternalScout to fetch external context when:

1. User asks about external libraries (Drizzle, Better Auth, Next.js, etc.)
2. Task involves integration between multiple external libraries
3. Setup or configuration of external tools is needed
4. API patterns or best practices from external libraries are relevant

Don't use when:

• Question is about internal project code
• Answer is in .opencode/context/ (use ContextScout instead)
• User is asking for general programming concepts

---

Integration Workflow

Stage 1: Analyze & Discover (Before Approval)

Main Agent (OpenAgent, etc.)
  ↓
  1. Analyze user request
  ↓
  2. Identify external libraries mentioned
  ↓
  3. Call ContextScout for internal context
  ↓
  4. Call ExternalScout for external docs
     - ExternalScout fetches from Context7 API
     - ExternalScout persists to .tmp/external-context/
     - ExternalScout returns file paths
  ↓
  5. Capture returned file paths
  ↓
  6. Do NOT write anything to disk yet

Stage 2: Propose Plan (Before Approval)

Main Agent
  ↓
  1. Show user lightweight summary:
     - What will be done
     - Which external libraries involved
     - Which context files will be used
  ↓
  2. Include discovered external context files in proposal
  ↓
  3. Wait for user approval

Stage 3: Approve (User Gate)

User
  ↓
  Approves plan (or redirects)

Stage 4: Init Session (After Approval)

Main Agent
  ↓
  1. Create .tmp/sessions/{session-id}/context.md
  ↓
  2. Populate sections:
     - ## Context Files (from ContextScout)
     - ## Reference Files (project files)
     - ## External Context Fetched (from ExternalScout)
     - ## Components
     - ## Constraints
     - ## Exit Criteria
  ↓
  3. CRITICAL: Add "## External Context Fetched" section with:
     - File paths returned by ExternalScout
     - Brief description of each file
     - Note that files are read-only

Stage 5: Delegate with Context Path

Main Agent
  ↓
  1. Call TaskManager (or other subagent)
  ↓
  2. Pass session path in prompt:
     "Load context from .tmp/sessions/{session-id}/context.md"
  ↓
  3. TaskManager reads session context
  ↓
  4. TaskManager extracts external context files
  ↓
  5. TaskManager includes in subtask JSONs

Stage 6: Subagents Read External Context

TaskManager / CoderAgent / TestEngineer
  ↓
  1. Read session context file
  ↓
  2. Extract "## External Context Fetched" section
  ↓
  3. Read referenced files from .tmp/external-context/
  ↓
  4. Use external docs to inform implementation
  ↓
  5. NO RE-FETCHING ✅

---

Implementation Details

Step 1: Call ExternalScout

In your main agent (before approval):

// Detect external libraries from user request
const externalLibraries = ["drizzle-orm", "better-auth", "next.js"];

// Call ExternalScout
task(
  subagent_type="ExternalScout",
  description="Fetch external documentation",
  prompt="Fetch documentation for these libraries:
          - Drizzle ORM: modular schema organization
          - Better Auth: Next.js integration
          - Next.js: App Router setup
          
          Persist fetched docs to .tmp/external-context/
          Return file paths for each fetched document"
)

// Capture returned file paths
// Example return:
// - .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

Step 2: Propose Plan with External Context

## Implementation Plan

**Task**: Set up Drizzle + Better Auth in Next.js

**External Libraries Involved**:
- Drizzle ORM (database)
- Better Auth (authentication)
- Next.js (framework)

**External Context Discovered**:
- `.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`

**Approach**:
1. Set up Drizzle schema with modular organization
2. Configure Better Auth with Drizzle adapter
3. Integrate with Next.js App Router

**Approval needed before proceeding.**

Step 3: Create Session with External Context

After approval, create .tmp/sessions/{session-id}/context.md:

# Task Context: Drizzle + Better Auth Integration

Session ID: 2026-01-28-drizzle-auth
Created: 2026-01-28T14:30:22Z
Status: in_progress

## Current Request
Set up Drizzle ORM with Better Auth in a Next.js application

## Context Files (Standards to Follow)
- .opencode/context/core/standards/code-quality.md
- .opencode/context/core/standards/test-coverage.md

## Reference Files (Source Material)
- package.json
- src/db/schema.ts (existing)
- src/auth/config.ts (existing)

## 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 for modular architecture
- `.tmp/external-context/drizzle-orm/postgresql-setup.md` — PostgreSQL configuration and setup

### Better Auth
- `.tmp/external-context/better-auth/nextjs-integration.md` — Integration guide for Next.js App Router
- `.tmp/external-context/better-auth/drizzle-adapter.md` — Drizzle adapter setup and configuration

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

**Important**: These files are read-only and cached for reference. Do not modify them.

## Components
- Drizzle schema setup with modular organization
- Better Auth configuration with Drizzle adapter
- Next.js App Router integration

## Constraints
- TypeScript strict mode
- Must support PostgreSQL
- Backward compatible with existing auth system

## Exit Criteria
- [ ] Drizzle schema set up with modular organization
- [ ] Better Auth configured with Drizzle adapter
- [ ] Next.js App Router integration complete
- [ ] All tests passing
- [ ] Documentation updated

## Progress
- [ ] Session initialized
- [ ] Tasks created
- [ ] Implementation complete
- [ ] Tests passing
- [ ] Handoff complete

Step 4: Delegate to TaskManager

task(
  subagent_type="TaskManager",
  description="Break down Drizzle + Better Auth integration",
  prompt="Load context from .tmp/sessions/2026-01-28-drizzle-auth/context.md

          Read the context file for full requirements, standards, and external documentation.
          
          Break down this feature into atomic subtasks:
          1. Drizzle schema setup with modular organization
          2. Better Auth configuration with Drizzle adapter
          3. Next.js App Router integration
          4. Test suite
          
          For each subtask, include:
          - context_files: Standards from context.md
          - reference_files: Project files to understand
          - external_context: External docs to reference
          
          Create subtask files in tasks/subtasks/drizzle-auth-integration/"
)

Step 5: TaskManager Creates Subtasks with External Context

TaskManager creates subtask JSONs like:

{
  "id": "01-drizzle-schema-setup",
  "title": "Set up Drizzle schema with modular organization",
  "description": "Create modular Drizzle schema following best practices",
  "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. Reference .tmp/external-context/drizzle-orm/modular-schemas.md for best practices.",
  "acceptance_criteria": [
    "Schema organized into separate files by domain",
    "PostgreSQL configuration matches external docs",
    "TypeScript types properly exported",
    "Tests cover schema setup"
  ]
}

Step 6: CoderAgent Implements Using External Context

CoderAgent reads subtask JSON and:

1. Loads context_files (standards)
2. Reads reference_files (existing code)
3. Reads external_context files (external docs)
4. Implements following all standards and external docs
5. Returns completed subtask

---

Best Practices

For Main Agents

✅ DO:

• Call ExternalScout early in planning phase
• Capture returned file paths
• Add to session context under "## External Context Fetched"
• Pass session path to subagents
• Include external context in proposal to user

❌ DON'T:

• Forget to call ExternalScout when external libraries involved
• Skip adding external context to session
• Re-fetch external docs (trust ExternalScout persistence)
• Modify external context files

For ExternalScout

✅ DO:

• Always persist fetched docs to .tmp/external-context/
• Update .manifest.json after each fetch
• Include metadata header in every file
• Filter aggressively to relevant sections
• Cite sources and include official docs links

❌ DON'T:

• Forget to persist files
• Skip manifest updates
• Return entire documentation
• Fabricate documentation content
• Write outside .tmp/external-context/

For TaskManager

✅ DO:

• Extract external_context from session context
• Include in subtask JSONs
• Pass to downstream agents
• Document which external docs informed decisions

❌ DON'T:

• Forget to include external_context in subtasks
• Mix external_context with context_files
• Assume subagents will re-fetch

For Subagents (CoderAgent, TestEngineer, etc.)

✅ DO:

• Read external_context files from subtask JSON
• Use external docs to inform implementation
• Reference external docs in comments
• Follow patterns from external docs

❌ DON'T:

• Re-fetch external documentation
• Ignore external context files
• Modify external context files
• Assume external docs are optional

---

Example: Complete Flow

User Request

"Set up Drizzle ORM with Better Auth in Next.js, using modular schema organization"

Main Agent Flow

1. Analyze: Detect Drizzle, Better Auth, Next.js
2. Discover: Call ContextScout + ExternalScout
3. Propose: Show plan with external context files
4. Approve: User approves
5. Init Session: Create context.md with external context section
6. Delegate: Call TaskManager with session path
7. Validate: Check tests pass
8. Complete: Update docs, cleanup

ExternalScout Flow

1. Detect: Drizzle, Better Auth, Next.js
2. Fetch: Get docs from Context7 API
3. Filter: Extract relevant sections
4. Persist: Write to .tmp/external-context/{package}/{topic}.md
5. Update: Add to .manifest.json
6. Return: File paths to main agent

TaskManager Flow

1. Read: Session context.md
2. Extract: External context files
3. Create: Subtasks with external_context field
4. Delegate: Pass to CoderAgent

CoderAgent Flow

1. Read: Subtask JSON
2. Load: context_files (standards)
3. Reference: reference_files (existing code)
4. Read: external_context files (external docs)
5. Implement: Following all standards and external docs
6. Complete: Return implemented subtask

---

Troubleshooting

External Context Files Not Found

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

Solution:

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

Stale External Context

Problem: External docs are outdated

Solution:

1. Delete stale files: scripts/external-context/manage-external-context.sh delete-package {package}
2. Re-run ExternalScout to fetch fresh docs
3. Update session context with new file paths

Manifest Out of Sync

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

Solution:

1. Regenerate manifest: scripts/external-context/manage-external-context.sh regenerate-manifest
2. Verify all files have metadata headers

---

References

• ExternalScout: .opencode/agent/subagents/core/externalscout.md
• External Context Management: .opencode/context/core/workflows/external-context-management.md
• Task Delegation: .opencode/context/core/workflows/task-delegation-basics.md
• Management Script: scripts/external-context/manage-external-context.sh