feat: add context discovery and session management documentation
- Add context-discovery.md with dynamic context loading and manifest indexing - Add session-management.md with lazy initialization and cleanup policies - Implement keyword search and delegation patterns for context files - Define session isolation and error handling strategies
This commit is contained in:
darrenhinde
parent
9692d3a752
commit
5518a96f53
2 changed files with 370 additions and 0 deletions
226
.opencode/context/core/context-discovery.md
Normal file
226
.opencode/context/core/context-discovery.md
Normal file
|
|
@ -0,0 +1,226 @@
|
||||||
|
# Context Discovery
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
**Dynamically load relevant context files when delegating to subagents**
|
||||||
|
|
||||||
|
Allows subagents to discover and access context created earlier in the session, preventing information loss across delegation boundaries.
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
### 1. Context File Creation
|
||||||
|
|
||||||
|
When creating a context file, add metadata to manifest:
|
||||||
|
|
||||||
|
```json
|
||||||
|
"context_files": {
|
||||||
|
"features/user-auth-context.md": {
|
||||||
|
"created": "2025-01-18T14:30:22Z",
|
||||||
|
"for": "@subagents/core/task-manager",
|
||||||
|
"keywords": ["user-auth", "authentication", "features"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Metadata Fields**:
|
||||||
|
- `created`: Timestamp of file creation
|
||||||
|
- `for`: Target subagent (which agent will use this)
|
||||||
|
- `keywords`: Array of searchable keywords for discovery
|
||||||
|
|
||||||
|
### 2. Context Indexing
|
||||||
|
|
||||||
|
Manifest maintains keyword index for fast lookup:
|
||||||
|
|
||||||
|
```json
|
||||||
|
"context_index": {
|
||||||
|
"user-auth": [
|
||||||
|
"features/user-auth-context.md",
|
||||||
|
"tasks/user-auth-tasks.md"
|
||||||
|
],
|
||||||
|
"api": [
|
||||||
|
"documentation/api-docs-context.md"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Index Structure**:
|
||||||
|
- Key: Keyword (from context file metadata)
|
||||||
|
- Value: Array of file paths containing that keyword
|
||||||
|
|
||||||
|
### 3. Context Discovery Process
|
||||||
|
|
||||||
|
When delegating to subagent:
|
||||||
|
|
||||||
|
1. **Extract keywords** from user request or task context
|
||||||
|
2. **Search manifest** `context_index` for matching keywords
|
||||||
|
3. **Find related files** by category or keyword match
|
||||||
|
4. **Pass file paths** to subagent in delegation prompt
|
||||||
|
5. **Subagent reads** context files as needed
|
||||||
|
|
||||||
|
### 4. Delegation Pattern
|
||||||
|
|
||||||
|
**Context Reference Format**:
|
||||||
|
```
|
||||||
|
Related context available at: .tmp/sessions/{session-id}/features/user-auth-context.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Full Delegation Example**:
|
||||||
|
```
|
||||||
|
Delegating to @subagents/code/coder-agent:
|
||||||
|
|
||||||
|
"Implement user authentication login component.
|
||||||
|
|
||||||
|
Related context available at:
|
||||||
|
- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
||||||
|
- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
|
||||||
|
|
||||||
|
Read these files for full context on requirements and task breakdown."
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Create Context Files
|
||||||
|
|
||||||
|
**Only create when ALL of these apply**:
|
||||||
|
- Delegating to a subagent
|
||||||
|
- Context description is verbose (>2 sentences) OR
|
||||||
|
- Risk of misinterpretation without detailed context
|
||||||
|
|
||||||
|
**Don't create for**:
|
||||||
|
- Simple, one-line instructions
|
||||||
|
- Direct execution (no delegation)
|
||||||
|
- Conversational questions
|
||||||
|
|
||||||
|
## Context File Categories
|
||||||
|
|
||||||
|
```
|
||||||
|
features/ - Feature development context
|
||||||
|
documentation/ - Documentation tasks
|
||||||
|
code/ - Code-related tasks
|
||||||
|
refactoring/ - Refactoring tasks
|
||||||
|
testing/ - Testing tasks
|
||||||
|
tasks/ - Task breakdowns created by task-manager
|
||||||
|
general/ - General tasks that don't fit other categories
|
||||||
|
```
|
||||||
|
|
||||||
|
## Context File Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Context: {Task Name}
|
||||||
|
Session: {session-id}
|
||||||
|
|
||||||
|
## Request Summary
|
||||||
|
[Brief description of what needs to be done]
|
||||||
|
|
||||||
|
## Background
|
||||||
|
[Relevant context and information]
|
||||||
|
|
||||||
|
## Expected Output
|
||||||
|
[What the subagent should produce]
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
[Any limitations or requirements]
|
||||||
|
|
||||||
|
## Related Context
|
||||||
|
[Links to other context files if applicable]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Discovery Strategies
|
||||||
|
|
||||||
|
### By Keyword
|
||||||
|
Search `context_index` for exact keyword matches:
|
||||||
|
```
|
||||||
|
User: "Add login validation"
|
||||||
|
Keywords: ["login", "validation", "user-auth"]
|
||||||
|
→ Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### By Category
|
||||||
|
Search `context_files` for matching category:
|
||||||
|
```
|
||||||
|
Delegating to @documentation agent
|
||||||
|
Category: "documentation"
|
||||||
|
→ Finds all files in documentation/ folder
|
||||||
|
```
|
||||||
|
|
||||||
|
### By Target Agent
|
||||||
|
Search `context_files` for files created for specific agent:
|
||||||
|
```
|
||||||
|
Delegating to @task-manager
|
||||||
|
Filter: "for": "@subagents/core/task-manager"
|
||||||
|
→ Finds all context files created for task-manager
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example Workflow
|
||||||
|
|
||||||
|
```
|
||||||
|
1. User: "Build user authentication system"
|
||||||
|
→ OpenAgent creates: features/user-auth-context.md
|
||||||
|
→ Manifest updated with keywords: ["user-auth", "authentication", "features"]
|
||||||
|
→ Delegates to @task-manager with context file path
|
||||||
|
|
||||||
|
2. Task-manager creates: tasks/user-auth-tasks.md
|
||||||
|
→ Manifest updated with keywords: ["user-auth", "tasks", "breakdown"]
|
||||||
|
→ Both files now indexed under "user-auth"
|
||||||
|
|
||||||
|
3. User: "Implement the login component"
|
||||||
|
→ OpenAgent searches manifest for "user-auth" OR "login"
|
||||||
|
→ Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
|
||||||
|
→ Delegates to @coder-agent with references to BOTH files
|
||||||
|
→ Coder-agent reads both files to understand full context
|
||||||
|
|
||||||
|
4. User: "Add password reset feature"
|
||||||
|
→ OpenAgent searches manifest for "user-auth" OR "password"
|
||||||
|
→ Finds existing user-auth context
|
||||||
|
→ Creates new: features/password-reset-context.md
|
||||||
|
→ Links to existing user-auth context
|
||||||
|
→ Delegates with all related context files
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benefits
|
||||||
|
|
||||||
|
✅ **No context loss**: Information persists across subagent calls
|
||||||
|
✅ **Automatic discovery**: Related context found by keywords
|
||||||
|
✅ **Flexible**: Subagents read only what they need
|
||||||
|
✅ **Traceable**: Manifest shows all context relationships
|
||||||
|
✅ **Scalable**: Works with multiple context files per session
|
||||||
|
✅ **Reusable**: Later tasks can reference earlier context
|
||||||
|
|
||||||
|
## Context Inheritance
|
||||||
|
|
||||||
|
**Load related context files from manifest before delegating**
|
||||||
|
|
||||||
|
When delegating to a subagent:
|
||||||
|
1. Check if session exists
|
||||||
|
2. Read manifest if available
|
||||||
|
3. Search for related context by keyword/category
|
||||||
|
4. Include relevant context file paths in delegation
|
||||||
|
5. Subagent reads context files as first step
|
||||||
|
|
||||||
|
This ensures subagents have full context from earlier in the session.
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Manifest Not Found
|
||||||
|
- Session not initialized yet
|
||||||
|
- Continue without context discovery
|
||||||
|
- Create new session if context file needed
|
||||||
|
|
||||||
|
### Context File Missing
|
||||||
|
- File was deleted or moved
|
||||||
|
- Warn user about missing context
|
||||||
|
- Continue with available context
|
||||||
|
- Update manifest to remove missing file
|
||||||
|
|
||||||
|
### Keyword Collision
|
||||||
|
- Multiple files match same keyword
|
||||||
|
- Include all matching files in delegation
|
||||||
|
- Let subagent determine relevance
|
||||||
|
- Consider more specific keywords in future
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Use specific keywords**: "user-auth" better than "auth"
|
||||||
|
2. **Include category in keywords**: ["features", "user-auth"]
|
||||||
|
3. **Link related context**: Reference other context files
|
||||||
|
4. **Update manifest immediately**: Don't delay indexing
|
||||||
|
5. **Clean up stale context**: Remove when task complete
|
||||||
|
6. **Validate file exists**: Before passing to subagent
|
||||||
144
.opencode/context/core/session-management.md
Normal file
144
.opencode/context/core/session-management.md
Normal file
|
|
@ -0,0 +1,144 @@
|
||||||
|
# Session Management
|
||||||
|
|
||||||
|
## Lazy Initialization
|
||||||
|
|
||||||
|
**Only create session when first context file needed**
|
||||||
|
|
||||||
|
- Don't create sessions for simple questions or direct execution
|
||||||
|
- Initialize on first delegation that requires context file
|
||||||
|
- Session ID format: `{timestamp}-{random-4-chars}`
|
||||||
|
- Example: `20250118-143022-a4f2`
|
||||||
|
|
||||||
|
## Session Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.tmp/sessions/{session-id}/
|
||||||
|
├── .manifest.json
|
||||||
|
├── features/
|
||||||
|
│ └── {task-name}-context.md
|
||||||
|
├── documentation/
|
||||||
|
│ └── {task-name}-context.md
|
||||||
|
├── code/
|
||||||
|
│ └── {task-name}-context.md
|
||||||
|
├── tasks/
|
||||||
|
│ └── {task-name}-tasks.md
|
||||||
|
└── general/
|
||||||
|
└── {task-name}-context.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Session Isolation
|
||||||
|
|
||||||
|
**Each session has unique ID - prevents concurrent agent conflicts**
|
||||||
|
|
||||||
|
✅ Multiple agent instances can run simultaneously
|
||||||
|
✅ No file conflicts between sessions
|
||||||
|
✅ Each session tracks only its own files
|
||||||
|
✅ Safe cleanup - only deletes own session folder
|
||||||
|
|
||||||
|
## Manifest Structure
|
||||||
|
|
||||||
|
**Location**: `.tmp/sessions/{session-id}/.manifest.json`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"session_id": "20250118-143022-a4f2",
|
||||||
|
"created_at": "2025-01-18T14:30:22Z",
|
||||||
|
"last_activity": "2025-01-18T14:35:10Z",
|
||||||
|
"context_files": {
|
||||||
|
"features/user-auth-context.md": {
|
||||||
|
"created": "2025-01-18T14:30:22Z",
|
||||||
|
"for": "@subagents/core/task-manager",
|
||||||
|
"keywords": ["user-auth", "authentication", "features"]
|
||||||
|
},
|
||||||
|
"tasks/user-auth-tasks.md": {
|
||||||
|
"created": "2025-01-18T14:32:15Z",
|
||||||
|
"for": "@subagents/core/task-manager",
|
||||||
|
"keywords": ["user-auth", "tasks", "breakdown"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"context_index": {
|
||||||
|
"user-auth": [
|
||||||
|
"features/user-auth-context.md",
|
||||||
|
"tasks/user-auth-tasks.md"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Activity Tracking
|
||||||
|
|
||||||
|
**Update timestamp after each context file creation or delegation**
|
||||||
|
|
||||||
|
- Update `last_activity` field in manifest
|
||||||
|
- Used for stale session detection
|
||||||
|
- Helps identify active vs abandoned sessions
|
||||||
|
|
||||||
|
## Cleanup Policy
|
||||||
|
|
||||||
|
### Manual Cleanup (Preferred)
|
||||||
|
**Ask user confirmation before cleanup**
|
||||||
|
|
||||||
|
After task completion:
|
||||||
|
1. Ask: "Should I clean up temporary session files at `.tmp/sessions/{session-id}/`?"
|
||||||
|
2. Wait for user confirmation
|
||||||
|
3. Only delete files tracked in current session's manifest
|
||||||
|
4. Remove entire session folder: `.tmp/sessions/{session-id}/`
|
||||||
|
|
||||||
|
### Safety Rules
|
||||||
|
- **NEVER** delete files outside current session
|
||||||
|
- **ONLY** delete files tracked in manifest
|
||||||
|
- **ALWAYS** confirm with user before cleanup
|
||||||
|
|
||||||
|
### Stale Session Cleanup
|
||||||
|
**Auto-remove sessions >24 hours old**
|
||||||
|
|
||||||
|
- Check `last_activity` timestamp in manifest
|
||||||
|
- Safe to run periodically (see `scripts/cleanup-stale-sessions.sh`)
|
||||||
|
- Won't affect active sessions
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Subagent Failure
|
||||||
|
- Report error to user
|
||||||
|
- Ask if should retry or abort
|
||||||
|
- Don't auto-retry without approval
|
||||||
|
|
||||||
|
### Context File Error
|
||||||
|
- Fall back to inline context in delegation prompt
|
||||||
|
- Warn user that context file creation failed
|
||||||
|
- Continue with task if possible
|
||||||
|
|
||||||
|
### Session Creation Error
|
||||||
|
- Continue without session
|
||||||
|
- Warn user
|
||||||
|
- Use inline context for delegation
|
||||||
|
- Don't block task execution
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Lazy Init**: Only create session when actually needed
|
||||||
|
2. **Track Everything**: Add all context files to manifest
|
||||||
|
3. **Update Activity**: Touch `last_activity` on each operation
|
||||||
|
4. **Clean Promptly**: Remove files after task completion
|
||||||
|
5. **Isolate Sessions**: Never access files from other sessions
|
||||||
|
6. **Confirm Cleanup**: Always ask user before deleting
|
||||||
|
|
||||||
|
## Example Workflow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# User: "Build user authentication system"
|
||||||
|
# → Complex task, needs context file
|
||||||
|
# → Create session: 20250118-143022-a4f2
|
||||||
|
# → Create: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
||||||
|
# → Delegate to @task-manager
|
||||||
|
|
||||||
|
# User: "Implement login component"
|
||||||
|
# → Same session, add context
|
||||||
|
# → Create: .tmp/sessions/20250118-143022-a4f2/code/login-context.md
|
||||||
|
# → Delegate to @coder-agent
|
||||||
|
|
||||||
|
# Task complete
|
||||||
|
# → Ask: "Clean up session files?"
|
||||||
|
# → User confirms
|
||||||
|
# → Delete: .tmp/sessions/20250118-143022-a4f2/
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue