OpenAgentsControl/.opencode/context/core/workflows/external-libraries-scenarios.md

External Libraries: Common Scenarios

Purpose: Real-world examples of using ExternalScout

---

Scenario 1: New Build with External Packages

Example: Next.js app with Drizzle + Better Auth

Process:

1. Check install scripts: ls scripts/install/
2. Identify packages: Next.js, Drizzle ORM, Better Auth
3. ExternalScout for each package
4. Check requirements: PostgreSQL? Env vars?
5. Verify version compatibility
6. Implement following current docs
7. Test integration points

ExternalScout calls:

// Drizzle ORM
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
  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
  Context: Commerce site w/ order processing"
)

---

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 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
2. ExternalScout: "Fetch TanStack Query docs: Next.js App Router setup"
3. Get: Install steps | Peer deps | Config | Patterns
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"
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 with Better Auth to Next.js commerce"

// 1. ContextScout: Project standards
task(
  subagent_type="ContextScout",
  description="Find auth standards",
  prompt="Find context files: Auth patterns | Security standards"
)
// 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 | Drizzle adapter | Session mgmt
  Context: Adding auth to Next.js commerce w/ Drizzle ORM"
)
// Returns: Installation | Integration patterns | Working examples

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

---

Error Handling Patterns

Error Type	Process
Package Installation	ExternalScout: installation docs → Verify package name/version → Check peer deps
Import/Module	ExternalScout: import patterns → Check current API exports
API/Configuration	ExternalScout: API docs → Check current signatures
Build Errors	Identify package → ExternalScout: relevant docs → Check known issues

---

Related

• external-libraries-workflow.md - Core workflow
• external-libraries-faq.md - Troubleshooting FAQ