chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
406
.opencode/context/core/workflows/external-context-management.md
Normal file
406
.opencode/context/core/workflows/external-context-management.md
Normal file
@@ -0,0 +1,406 @@
|
||||
<!-- Context: workflows/external-context | Priority: high | Version: 1.0 | Updated: 2026-01-28 -->
|
||||
# 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 bun --bun 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**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```markdown
|
||||
---
|
||||
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`:
|
||||
|
||||
```markdown
|
||||
## 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
```bash
|
||||
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`:
|
||||
```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**:
|
||||
```markdown
|
||||
## 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:
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user