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

Workflow: External Libraries

Purpose: Fetch current documentation for external packages before implementation

Last Updated: 2026-01-28

---

Quick Start

Golden Rule: NEVER rely on training data for external libraries → ALWAYS fetch current docs

Process: Detect package → Check install scripts → Use ExternalScout → Implement

When to use ExternalScout (MANDATORY):

• New builds w/ external packages
• First-time package setup
• Package/dependency errors
• Version upgrades
• ANY external library work

---

Core Principle

Training data is OUTDATED for external libraries. ALWAYS fetch current docs using ExternalScout before implementation.

Why:

• APIs change (new methods, deprecated features)
• Configuration patterns evolve
• Breaking changes happen frequently
• Version-specific features differ

Example:

Training data (2023): Next.js 13 uses pages/ directory
Current (2025): Next.js 15 uses app/ directory (App Router)

Training data = broken code ❌
ExternalScout = working code ✅

---

Workflow Stages

1. Detect External Package

Triggers: User mentions library | package.json deps | import statements | build errors | first-time setup

Action: Identify which external packages involved

---

2. Check Install Scripts (First-Time Builds)

Check for:

# Look for install scripts
ls scripts/install/ scripts/setup/ bin/install* setup.sh install.sh

# Check package-specific requirements
grep -r "postinstall\|preinstall" package.json

Read scripts if found:

• What does it do?
• Environment variables needed?
• Prerequisites (database, services)?

Why: Scripts may set up databases, generate files, configure services in specific order

---

3. Fetch Current Documentation (MANDATORY)

Basic Pattern:

task(
  subagent_type="ExternalScout",
  description="Fetch [Library] docs for [topic]",
  prompt="Fetch current documentation for [Library]: [specific question]
  
  Focus on:
  - Installation and setup steps
  - [Specific feature/API needed]
  - [Integration requirements]
  - Required environment variables
  - Database/service setup
  
  Context: [What you're building]"
)

Real Examples:

Drizzle ORM Setup:

task(
  subagent_type="ExternalScout",
  description="Fetch Drizzle PostgreSQL setup",
  prompt="Fetch Drizzle ORM docs: PostgreSQL setup w/ modular schemas
  
  Focus on: Installation | DB connection | Schema patterns | Migrations | TypeScript config
  Context: Next.js commerce site w/ PostgreSQL"
)

Next.js App Router:

task(
  subagent_type="ExternalScout",
  description="Fetch Next.js App Router docs",
  prompt="Fetch Next.js docs: App Router w/ Server Actions
  
  Focus on: Installation | Directory structure | Server Actions | Data fetching | Route handlers
  Context: Commerce site w/ order processing"
)

Better Auth Integration:

task(
  subagent_type="ExternalScout",
  description="Fetch Better Auth + Next.js integration",
  prompt="Fetch Better Auth docs: Next.js App Router integration w/ Drizzle
  
  Focus on: Installation | App Router setup | Drizzle adapter | Session mgmt | Route protection
  Context: Adding auth to Next.js commerce w/ Drizzle ORM"
)

ExternalScout Returns:

• Current, version-specific docs
• Installation steps + required packages
• Official API references
• Working code examples
• Current best practices
• Integration patterns
• Setup prerequisites
• Environment variables
• Common pitfalls + solutions

---

4. Verify Compatibility

Check: Version compatibility | Peer dependencies | Breaking changes | Platform requirements

If version mismatch: Note in plan → Request approval for upgrade → Fetch docs for specific version

---

5. Implement with Current Patterns

Apply docs:

• Use exact API signatures from docs
• Follow current best practices
• Use recommended config patterns
• Implement error handling as documented

Don't:

• ❌ Assume API based on training data
• ❌ Use deprecated patterns
• ❌ Skip version-specific requirements
• ❌ Ignore breaking changes

---

6. Test Integration

Verify: Package installs | Imports work | API calls match docs | Error handling | Integration w/ other packages

---

Decision Flow: ContextScout + ExternalScout

User Request: "Build Next.js commerce w/ Drizzle"
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 1: ContextScout                             │
│ → Search internal context (.opencode/context/)  │
│ → Find project standards, patterns, workflows   │
└──────────────────────────────────────────────────┘
                    ↓
         Internal context found?
                    ↓
        ┌───────────┴───────────┐
       YES                      NO
        │                        │
        ↓                        ↓
   Use internal          Is it external library?
   context                       ↓
                        ┌────────┴────────┐
                       YES               NO
                        │                 │
                        ↓                 ↓
              ┌─────────────────┐  Report: No context
              │ STEP 2:         │  available
              │ ExternalScout   │
              │ (MANDATORY)     │
              └─────────────────┘
                        ↓
              Fetch: Next.js docs
                     Drizzle docs
                     Integration patterns
                        ↓
              ┌─────────────────────────┐
              │ STEP 3: Combine         │
              │ Internal: Standards     │
              │ External: Library docs  │
              │ → Implement w/ both     │
              └─────────────────────────┘

When to Use Which:

Scenario	ContextScout	ExternalScout	Both
Project coding standards	✅	❌	❌
External library setup	❌	✅ MANDATORY	❌
Project-specific patterns	✅	❌	❌
External API usage	❌	✅ MANDATORY	❌
Feature w/ external lib	✅ standards	✅ lib docs	✅
Package installation	❌	✅ MANDATORY	❌
Security patterns	✅	❌	❌
External lib integration	✅ project	✅ lib docs	✅

Key Principle: ContextScout + ExternalScout = Complete Context

• ContextScout: "How we do things in THIS project"
• ExternalScout: "How to use THIS library (current version)"
• Combined: "How to use THIS library following OUR standards"

---

Common Scenarios

Scenario 1: New Build w/ External Packages

Example: Next.js app w/ Drizzle + Better Auth

Process:

1. Check install scripts: ls scripts/install/ scripts/setup/
2. Identify packages: Next.js, Drizzle ORM, Better Auth
3. ExternalScout for each: Installation | Setup | Integration
4. Check requirements: PostgreSQL? Env vars? Services?
5. Verify version compatibility
6. Run install scripts (if exist) OR create setup from docs
7. Implement following current docs
8. Test integration points

---

Scenario 2: Package Error During Build

Example: Error: Cannot find module 'drizzle-orm/pg-core'

Process:

1. Identify package: Drizzle ORM
2. ExternalScout: "Fetch Drizzle docs: PostgreSQL setup and imports"
3. Check current import patterns
4. Verify package.json has correct deps
5. Propose fix from current docs
6. Request approval → Apply fix

---

Scenario 3: First-Time Package Setup

Example: Setting up TanStack Query in Next.js

Process:

1. Check install scripts: ls scripts/install/ | grep -r "tanstack\|react-query" scripts/
2. ExternalScout: "Fetch TanStack Query docs: Installation, Next.js App Router setup w/ Server Components"
3. Get: Install steps | Peer deps | Config files | Current patterns | Best practices
4. If install script exists: Review → Run
5. If no script: Follow docs for manual setup
6. Implement → Test

---

Scenario 4: Version Upgrade

Example: Next.js 14 → 15

Process:

1. ExternalScout: "Fetch Next.js 15 docs: Breaking changes and migration guide"
2. Review breaking changes
3. Identify affected code
4. Plan migration steps
5. Request approval → Implement → Test

---

Real-World Example: Auth Implementation

Task: "Add authentication w/ Better Auth to Next.js commerce site"

// 1. ContextScout: Project standards
task(
  subagent_type="ContextScout",
  description="Find auth and security standards",
  prompt="Find context files: Auth patterns | Security standards | Code quality | Project structure"
)
// Returns: security-patterns.md, code-quality.md

// 2. ExternalScout: Better Auth docs (MANDATORY)
task(
  subagent_type="ExternalScout",
  description="Fetch Better Auth + Next.js docs",
  prompt="Fetch Better Auth docs: Next.js App Router integration
  
  Focus on: Installation | App Router setup | Session mgmt | Route protection | Drizzle adapter
  Context: Adding auth to Next.js commerce w/ Drizzle ORM"
)
// Returns: Current installation | Integration patterns | Drizzle config | Working examples

// 3. Combine and implement
// - Better Auth patterns (from ExternalScout)
// - Security standards (from ContextScout)
// - Code quality standards (from ContextScout)
// = Secure, well-structured auth implementation ✅

---

Error Handling

Error Type	Process
Package Installation	ExternalScout: installation docs → Verify package name/version → Check peer deps → Propose fix w/ current steps
Import/Module	ExternalScout: import patterns → Check current API exports → Verify import paths → Propose fix w/ current imports
API/Configuration	ExternalScout: API docs → Check current signatures → Verify config format → Propose fix w/ current patterns
Build Errors	Identify package → ExternalScout: relevant docs → Check known issues/breaking changes → Propose fix from current docs

---

Best Practices

Do ✅:

• Check install scripts first on new builds
• Always fetch current docs before implementing
• Use ExternalScout proactively on new builds
• Verify versions match (package.json vs docs)
• Check breaking changes when upgrading
• Read install scripts before running
• Check prerequisites (databases, services, env vars)
• Test integrations between packages
• Cache useful docs in .opencode/context/development/frameworks/ if frequently used

Don't ❌:

• Assume APIs based on training data
• Skip version checks (breaking changes are common)
• Ignore peer dependencies
• Mix patterns from different versions
• Run install scripts blindly
• Skip environment setup

---

Troubleshooting FAQ

"When exactly should I use ExternalScout?"

ALWAYS use ExternalScout when working with external packages.

Triggers: User mentions library | import/require statements | package.json deps | build errors | first-time setup | version upgrades

Rule: If it's not in .opencode/context/, use ExternalScout.

---

"What if I already know the library?"

DON'T rely on training data - it's outdated.

Example: You think "I know Next.js, I'll use pages/" → Reality: Next.js 15 uses app/ → Result: Broken code ❌

Always fetch current docs, even if you "know" the library.

---

"How do I know if something is external?"

External libraries: npm/pip/gem/cargo packages | Third-party frameworks | ORMs/databases | Auth libraries | UI libraries

NOT external: Your project's code | Project utilities | Internal modules

Check: Is it in package.json dependencies? → External → Use ExternalScout

---

"Can I use both ContextScout and ExternalScout?"

YES! Use both for most features.

// 1. ContextScout: Project standards
task(subagent_type="ContextScout", ...)
// Returns: code-quality.md, security-patterns.md

// 2. ExternalScout: Library docs
task(subagent_type="ExternalScout", ...)
// Returns: Current Next.js docs, Drizzle docs

// 3. Combine: Implement using both

---

"What if ExternalScout doesn't have the library?"

ExternalScout has two sources:

1. Context7 API (primary): 50+ popular libraries
2. Official docs (fallback): Any library w/ public docs

If library not in Context7: Auto-fallback to official docs via webfetch

You don't need to worry - ExternalScout handles it.

---

"How do I write a good ExternalScout prompt?"

Template:

task(
  subagent_type="ExternalScout",
  description="Fetch [Library] docs for [specific topic]",
  prompt="Fetch current documentation for [Library]: [specific question]
  
  Focus on:
  - [What you need - be specific]
  - [Related features/APIs]
  - [Integration requirements]
  
  Context: [What you're building]"
)

Good prompts: ✅ Specific | ✅ Focused (3-5 things) | ✅ Contextual | ✅ Current

Bad prompts: ❌ Vague | ❌ Too broad | ❌ No context

---

"What if I get an error after using ExternalScout?"

Normal - errors happen. Process:

1. Read error message carefully
2. ExternalScout again w/ specific error:

   task(
     subagent_type="ExternalScout",
     description="Fetch docs for error resolution",
     prompt="Fetch [Library] docs: [error message]
   
     Error: [paste actual error]
     Focus on: Common causes | Solutions | Correct API usage"
   )
   

3. Check install scripts (maybe setup incomplete)
4. Verify versions (package.json vs docs)

---

"Do I need approval to use ExternalScout?"

NO - ExternalScout is read-only, no approval required.

Approval required: ❌ Write code | ❌ Run commands | ❌ Install packages

Approval NOT required: ✅ ContextScout | ✅ ExternalScout | ✅ Read files | ✅ Search code

---

"ContextScout vs ExternalScout?"

Aspect	ContextScout	ExternalScout
Searches	Internal project files	External documentation
Location	.opencode/context/	Internet (Context7, official docs)
Returns	Project standards, patterns	Library APIs, installation
Use for	"How we do things here"	"How this library works"
Tools	glob, read, grep	webfetch, Context7 API
Speed	Fast (local)	Slower (network)
Currency	Static (project docs)	Live (current docs)

Use both together for best results.

---

"Quick Checklist: Am I doing it right?"

Before implementing w/ external libraries:

• Used ContextScout for project standards?
• Checked for install scripts first?
• Used ExternalScout for EACH external library?
• Asked for installation steps in ExternalScout prompt?
• Asked for current API patterns and examples?
• Specified what I'm building (context)?
• Read returned docs before coding?
• Following both project standards AND library docs?

All checked? → You're doing it right! ✅

---

Supported Libraries

See: .opencode/skill/context7/library-registry.md

Categories: Database/ORM (Drizzle, Prisma) | Auth (Better Auth, NextAuth, Clerk) | Frontend (Next.js, React, TanStack) | Infrastructure (Cloudflare, AWS, Vercel) | UI (Shadcn/ui, Radix, Tailwind) | State (Zustand, Jotai) | Validation (Zod, React Hook Form) | Testing (Vitest, Playwright)

Not listed? ExternalScout can still fetch from official docs via webfetch

---

References

• ExternalScout Agent: .opencode/agent/subagents/core/externalscout.md
• Library Registry: .opencode/skill/context7/library-registry.md
• ContextScout Agent: .opencode/agent/subagents/core/contextscout.md
• Code Standards: .opencode/context/core/standards/code-quality.md