📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
+175
@@ -0,0 +1,175 @@
|
||||
# Cross-Session Patterns
|
||||
|
||||
Persisting state across conversation sessions using episodic memory.
|
||||
|
||||
## The Session Boundary Problem
|
||||
|
||||
Tasks survive **context compaction** but not **session boundaries**. When a conversation ends:
|
||||
- Task state is gone
|
||||
- Agent IDs are invalid
|
||||
- Decisions are forgotten
|
||||
|
||||
For work spanning multiple sessions, use episodic memory MCP server.
|
||||
|
||||
## When to Use Cross-Session Persistence
|
||||
|
||||
**Use episodic memory when**:
|
||||
- Project spans multiple days
|
||||
- Complex refactor with many steps
|
||||
- Work will be interrupted (meetings, context switches)
|
||||
- Handing off to another agent or future self
|
||||
- Key decisions need to survive sessions
|
||||
|
||||
**Just use Tasks when**:
|
||||
- Single-session task
|
||||
- Work completes within conversation
|
||||
- No significant decisions to preserve
|
||||
|
||||
## Saving Session State
|
||||
|
||||
At session end or before extended pause:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "episodic-memory:save",
|
||||
"content": {
|
||||
"project": "auth-refresh-implementation",
|
||||
"timestamp": "2024-01-15T14:30:00Z",
|
||||
"status": "in_progress",
|
||||
"completed": [
|
||||
"JWT validation logic",
|
||||
"Refresh endpoint structure",
|
||||
"Token claims extraction"
|
||||
],
|
||||
"remaining": [
|
||||
"Token rotation logic",
|
||||
"Refresh window handling",
|
||||
"Integration tests",
|
||||
"Security review"
|
||||
],
|
||||
"decisions": {
|
||||
"library": "jose (already in deps)",
|
||||
"algorithm": "RS256 (per existing patterns)",
|
||||
"refresh_window": "5 minutes before expiry",
|
||||
"rotation": "enabled (single-use refresh tokens)"
|
||||
},
|
||||
"files_modified": [
|
||||
"src/auth/refresh.ts",
|
||||
"src/auth/middleware.ts",
|
||||
"src/auth/types.ts"
|
||||
],
|
||||
"current_focus": {
|
||||
"file": "src/auth/refresh.ts",
|
||||
"line": 42,
|
||||
"task": "Implement rotateToken() function"
|
||||
},
|
||||
"blockers": [],
|
||||
"notes": "Using existing JWKS endpoint at /api/auth/.well-known/jwks.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Restoring Session State
|
||||
|
||||
At new session start:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "episodic-memory:search",
|
||||
"query": "auth refresh implementation"
|
||||
}
|
||||
```
|
||||
|
||||
Then:
|
||||
1. Read the returned state
|
||||
2. Reconstruct tasks from saved data using `TaskCreate`
|
||||
3. Resume from `current_focus`
|
||||
|
||||
## What to Save
|
||||
|
||||
| Category | Why |
|
||||
|----------|-----|
|
||||
| Completed work | Know what's done |
|
||||
| Remaining work | Know what's left |
|
||||
| Decisions made | Don't re-decide |
|
||||
| Files modified | Know where changes live |
|
||||
| Current focus | Resume exactly |
|
||||
| Blockers | Know what's blocking |
|
||||
| Notes | Context that might be needed |
|
||||
|
||||
## What NOT to Save
|
||||
|
||||
- Full file contents (they're in the repo)
|
||||
- Detailed reasoning (too verbose)
|
||||
- Every intermediate step (only milestones)
|
||||
- Transient state (temp variables, debug output)
|
||||
|
||||
Save the **minimum needed to resume**.
|
||||
|
||||
## Hooks for Auto-Persistence
|
||||
|
||||
Configure hooks to auto-save state at session boundaries:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": {
|
||||
"tool": "exit"
|
||||
},
|
||||
"action": "Save session state to episodic memory"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See outfitter's **claude-hooks** skill for hook configuration details.
|
||||
|
||||
## Multi-Day Project Pattern
|
||||
|
||||
For longer projects:
|
||||
|
||||
**Day 1 (end)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "api-redesign",
|
||||
"stage": "research",
|
||||
"completed": ["Identified 12 endpoints", "Documented current patterns"],
|
||||
"remaining": ["Design new patterns", "Plan migration"],
|
||||
"key_findings": "Inconsistent error handling across endpoints"
|
||||
}
|
||||
```
|
||||
|
||||
**Day 2 (start)**: Search for "api-redesign"
|
||||
**Day 2 (end)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "api-redesign",
|
||||
"stage": "design",
|
||||
"completed": ["New error pattern designed", "Migration strategy outlined"],
|
||||
"remaining": ["Implement error utilities", "Migrate endpoints"],
|
||||
"decisions": {"error_format": "RFC 7807 Problem Details"}
|
||||
}
|
||||
```
|
||||
|
||||
**Day 3**: Search, see full history, continue implementation.
|
||||
|
||||
## Integration with External Trackers
|
||||
|
||||
Episodic memory is your **session-level** state. External trackers handle **project-level** state:
|
||||
|
||||
| Tool | Scope | When to Update |
|
||||
|------|-------|----------------|
|
||||
| Tasks | Within conversation | Every task completion |
|
||||
| Episodic memory | Across sessions | Session boundaries |
|
||||
| Linear/GitHub | Project lifetime | Stage completions |
|
||||
|
||||
Workflow:
|
||||
1. Pull task from Linear/GitHub
|
||||
2. Track in Tasks during session
|
||||
3. Save to episodic memory at session end
|
||||
4. Update Linear/GitHub at stage completion
|
||||
+172
@@ -0,0 +1,172 @@
|
||||
# Delegation Patterns for Context Preservation
|
||||
|
||||
How to delegate work to preserve main conversation context.
|
||||
|
||||
> **TL;DR**: Subagents run in isolated contexts—only their summary returns. Delegate: 5+ file reads, codebase searches, specialized reviews. Keep in main: user Q&A, simple edits, files already in context. Use `run_in_background: true` for parallel work. Track delegated tasks with Tasks and agent IDs.
|
||||
|
||||
## The Context Problem
|
||||
|
||||
Main conversation context is ~128K tokens. Every operation consumes it:
|
||||
- Reading a file: file contents enter context
|
||||
- Search results: matches enter context
|
||||
- Reasoning: your analysis consumes tokens
|
||||
- Tool results: outputs accumulate
|
||||
|
||||
Subagents run in **isolated contexts**. When they complete, only their final output (summary, findings, results) returns to main context. The files they read, searches they ran, reasoning they did — all stay in their isolated context.
|
||||
|
||||
## Delegation Decision Matrix
|
||||
|
||||
| Task Type | Delegate? | Agent | Why |
|
||||
|-----------|-----------|-------|-----|
|
||||
| Read 1-2 files | No | Main | Already focused |
|
||||
| Read 5+ files | Yes | Explore | Preserves main context |
|
||||
| Codebase search | Yes | Explore | Returns summary, not raw results |
|
||||
| Security review | Yes | outfitter:reviewer | Specialized + isolated |
|
||||
| Performance analysis | Yes | outfitter:analyst | Research-heavy |
|
||||
| Simple edit | No | Main | Quick, in-context |
|
||||
| Multi-file refactor | Yes | outfitter:engineer | Coordinates changes |
|
||||
| Test validation | Yes | outfitter:tester | Isolated execution |
|
||||
| User Q&A | No | Main | Needs conversation history |
|
||||
|
||||
## Pattern: Research Delegation
|
||||
|
||||
Instead of reading many files yourself:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Find auth implementation",
|
||||
"prompt": "Locate all authentication-related files. Summarize: (1) auth flow, (2) libraries used, (3) key entry points",
|
||||
"subagent_type": "Explore"
|
||||
}
|
||||
```
|
||||
|
||||
**Returns to main context**: ~50 lines of summary
|
||||
**Stayed in subagent context**: contents of 15 files
|
||||
|
||||
## Pattern: Parallel Independent Reviews
|
||||
|
||||
When multiple concerns need analysis:
|
||||
|
||||
```json
|
||||
// All in single message, all run_in_background: true
|
||||
{
|
||||
"description": "Security review",
|
||||
"prompt": "Review src/auth/ for security vulnerabilities",
|
||||
"subagent_type": "outfitter:reviewer",
|
||||
"run_in_background": true
|
||||
}
|
||||
{
|
||||
"description": "Performance review",
|
||||
"prompt": "Analyze src/auth/ for performance issues",
|
||||
"subagent_type": "outfitter:analyst",
|
||||
"run_in_background": true
|
||||
}
|
||||
{
|
||||
"description": "Test coverage",
|
||||
"prompt": "Assess test coverage for src/auth/",
|
||||
"subagent_type": "outfitter:tester",
|
||||
"run_in_background": true
|
||||
}
|
||||
```
|
||||
|
||||
Three reviews run simultaneously. Main agent stays responsive. Collect results with `TaskOutput` when ready.
|
||||
|
||||
## Pattern: Sequential Handoff with Context
|
||||
|
||||
When later agents need earlier agents' output:
|
||||
|
||||
```
|
||||
1. outfitter:analyst researches → returns findings
|
||||
2. Main agent extracts key points
|
||||
3. outfitter:engineer implements → receives key points in prompt
|
||||
4. outfitter:reviewer reviews → receives implementation summary
|
||||
```
|
||||
|
||||
Don't pass full agent output to next agent. Extract and summarize.
|
||||
|
||||
## Pattern: Resumable Long-Running Work
|
||||
|
||||
For multi-stage work:
|
||||
|
||||
```json
|
||||
// Stage 1
|
||||
{
|
||||
"description": "Begin auth analysis",
|
||||
"prompt": "Analyze authentication patterns in src/auth/",
|
||||
"subagent_type": "outfitter:analyst"
|
||||
}
|
||||
// Returns agent-id: abc123
|
||||
|
||||
// Stage 2 (later)
|
||||
{
|
||||
"description": "Continue auth analysis",
|
||||
"prompt": "Now examine the session management aspect",
|
||||
"subagent_type": "outfitter:analyst",
|
||||
"resume": "abc123"
|
||||
}
|
||||
```
|
||||
|
||||
Agent preserves its full context across invocations. Main agent stays lean.
|
||||
|
||||
## What to Keep in Main Context
|
||||
|
||||
Not everything should be delegated:
|
||||
|
||||
**Keep in main**:
|
||||
- Direct user interaction
|
||||
- Final synthesis and decisions
|
||||
- Coordination logic
|
||||
- Files already read (don't re-delegate)
|
||||
- Simple, quick operations
|
||||
|
||||
**Delegate**:
|
||||
- Exploratory research
|
||||
- Multi-file analysis
|
||||
- Specialized reviews
|
||||
- Test execution
|
||||
- Background validation
|
||||
|
||||
## Task Integration
|
||||
|
||||
Track delegated work with Tasks:
|
||||
|
||||
```
|
||||
#1: "[analyst] Research caching patterns" - pending, metadata: {agentId: "abc123", background: true}
|
||||
#2: "Wait for analyst results" - pending, blockedBy: #1
|
||||
#3: "[engineer] Implement cache layer" - pending, blockedBy: #2
|
||||
#4: "[reviewer] Review implementation" - pending, blockedBy: #3
|
||||
```
|
||||
|
||||
Update when agents complete:
|
||||
|
||||
```
|
||||
#1: "[analyst] Research caching patterns" - completed, description: "Redis recommended"
|
||||
#2: "Wait for analyst results" - completed, description: "Redis approach confirmed"
|
||||
#3: "[engineer] Implement Redis cache layer" - in_progress
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Delegating simple work**: Single file edit doesn't need an agent.
|
||||
|
||||
**Over-parallelization**: Don't run 10 agents when 3 would do.
|
||||
|
||||
**Missing handoff context**: Agents need enough info to act independently.
|
||||
|
||||
**Forgetting to collect**: Background agents finish but results never retrieved.
|
||||
|
||||
**Re-delegating**: If file already in context, don't send agent to read it again.
|
||||
|
||||
## Context Budget Mental Model
|
||||
|
||||
Think of context as a budget:
|
||||
|
||||
```
|
||||
Total: 128K tokens
|
||||
System prompts: ~10K
|
||||
User messages: ~5K
|
||||
Your reasoning: ~20K
|
||||
Tool results: ~???
|
||||
```
|
||||
|
||||
Every file read, search result, and agent output draws from `tool results`. Delegation shifts that cost to isolated contexts, keeping main budget available for synthesis and user interaction.
|
||||
+218
@@ -0,0 +1,218 @@
|
||||
# Task Patterns
|
||||
|
||||
Deep patterns for using Tasks as your persistent state layer.
|
||||
|
||||
> **TL;DR**: Tasks survive compaction—your reasoning doesn't. One `in_progress` at a time. Mark completed immediately. Encode decisions in task descriptions. Before compaction, detail your current state. Track background agents with IDs in metadata.
|
||||
|
||||
## Why Tasks Matter for Context Management
|
||||
|
||||
Tasks survive context compaction. When context resets, you lose:
|
||||
- Your reasoning chains
|
||||
- Files you read
|
||||
- Intermediate conclusions
|
||||
- Decisions you made
|
||||
|
||||
But Tasks persist. They're your memory across compaction events.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Create immediately** — When scope is clear, `TaskCreate`
|
||||
2. **One in_progress** — Only one active task at a time
|
||||
3. **Complete as you go** — `TaskUpdate` to completed immediately, don't batch
|
||||
4. **Expand dynamically** — `TaskCreate` as you discover work
|
||||
5. **Reflect reality** — `TaskList` should match actual work remaining
|
||||
6. **Encode decisions** — Completed task descriptions should capture what was decided
|
||||
|
||||
## Initial Pattern
|
||||
|
||||
Start with baseline tasks, expand as scope becomes clear:
|
||||
|
||||
```
|
||||
TaskCreate: "Understand request and determine scope"
|
||||
TaskCreate: "Execute primary task"
|
||||
TaskCreate: "Synthesize and report"
|
||||
```
|
||||
|
||||
Expand dynamically as you discover specific work items.
|
||||
|
||||
## Evolution Example
|
||||
|
||||
**Initial** (after reading request):
|
||||
|
||||
```
|
||||
#1: "Understand request" → completed, description: "security review of auth module"
|
||||
#2: "Identify files to review" → in_progress
|
||||
```
|
||||
|
||||
**After scope discovery**:
|
||||
|
||||
```
|
||||
#1: completed - "Understand request → security review of auth module"
|
||||
#2: completed - "Identify files → 3 files in src/auth/"
|
||||
#3: pending - "Load security skill"
|
||||
#4: pending - "Check JWT token handling"
|
||||
#5: pending - "Check session management"
|
||||
#6: pending - "Check password hashing"
|
||||
#7: pending - "Synthesize findings"
|
||||
#8: pending - "Compile report"
|
||||
```
|
||||
|
||||
**During execution** (discovered issue):
|
||||
|
||||
```
|
||||
#5: completed - "Check session management → found issue"
|
||||
#9: pending - "Investigate session fixation vulnerability" ← TaskCreate for discovery
|
||||
```
|
||||
|
||||
## Agent-Specific Templates
|
||||
|
||||
### Implementation Tasks
|
||||
|
||||
```
|
||||
- Understand requirements
|
||||
- Explore existing patterns
|
||||
- Plan implementation approach
|
||||
- { expand: per-component tasks }
|
||||
- Write tests (TDD: tests first)
|
||||
- Implement
|
||||
- Verify tests pass
|
||||
- Self-review for quality
|
||||
```
|
||||
|
||||
### Review Tasks
|
||||
|
||||
```
|
||||
- Detect review type and scope
|
||||
- Load primary skill
|
||||
- { expand: per-concern tasks }
|
||||
- Load additional skills if needed
|
||||
- Synthesize findings
|
||||
- Compile report with severity ranking
|
||||
```
|
||||
|
||||
### Research Tasks
|
||||
|
||||
```
|
||||
- Clarify research question
|
||||
- Identify sources
|
||||
- { expand: per-source tasks }
|
||||
- Cross-reference findings
|
||||
- Synthesize with citations
|
||||
```
|
||||
|
||||
### Debugging Tasks
|
||||
|
||||
```
|
||||
- Reproduce the issue
|
||||
- Gather evidence (logs, errors, state)
|
||||
- Form hypothesis
|
||||
- { expand: investigation steps }
|
||||
- Validate root cause
|
||||
- Implement fix
|
||||
- Verify fix resolves issue
|
||||
```
|
||||
|
||||
### Multi-Agent Tasks
|
||||
|
||||
Use `[agent-name]` prefix in task subjects and `blockedBy` for dependencies:
|
||||
|
||||
```
|
||||
#1: "[analyst] Research stage" - pending
|
||||
#2: "[engineer] Implementation stage" - pending, blockedBy: #1
|
||||
#3: "[reviewer] Review stage" - pending, blockedBy: #2
|
||||
#4: "[tester] Validation stage" - pending, blockedBy: #3
|
||||
#5: "Synthesize results" - pending, blockedBy: #4
|
||||
```
|
||||
|
||||
## Encoding Decisions
|
||||
|
||||
Completed task descriptions should capture what was decided, not just what was done.
|
||||
|
||||
**Bad** (no decision context):
|
||||
|
||||
```
|
||||
Task: "Research auth libraries" - completed
|
||||
Description: (empty)
|
||||
```
|
||||
|
||||
**Good** (decision encoded):
|
||||
|
||||
```
|
||||
Task: "Research auth libraries" - completed
|
||||
Description: "Selected jose (already in deps, ES module support)"
|
||||
```
|
||||
|
||||
## Pre-Compaction State Capture
|
||||
|
||||
When context is filling, `TaskUpdate` your `in_progress` task with maximum detail:
|
||||
|
||||
```
|
||||
Task: "Implementing token refresh flow" - in_progress
|
||||
Description:
|
||||
- File: src/auth/refresh.ts
|
||||
- Current line: 42
|
||||
- Done: validateToken(), extractClaims()
|
||||
- Next: rotateToken() implementation
|
||||
- Note: Using jose library, RS256 algorithm
|
||||
- Blocked: Need JWKS endpoint URL from config
|
||||
```
|
||||
|
||||
This level of detail lets you resume exactly where you left off.
|
||||
|
||||
## Tracking Background Agents
|
||||
|
||||
Include agent IDs in task metadata so you can resume them later:
|
||||
|
||||
```
|
||||
Task: "[reviewer] Security review auth module"
|
||||
Status: pending
|
||||
Metadata: { agentId: "abc123", background: true }
|
||||
```
|
||||
|
||||
When agents complete, `TaskUpdate`:
|
||||
|
||||
```
|
||||
Task: "[reviewer] Security review auth module" - completed
|
||||
Description: "2 issues found"
|
||||
Metadata: { agentId: "abc123" }
|
||||
```
|
||||
|
||||
Then `TaskCreate` for follow-up:
|
||||
|
||||
```
|
||||
Task: "Address security issues from reviewer"
|
||||
Status: pending
|
||||
```
|
||||
|
||||
## When to TaskCreate
|
||||
|
||||
Add tasks when you discover:
|
||||
- **New files** to process
|
||||
- **New concerns** to address
|
||||
- **Follow-up investigations** from findings
|
||||
- **Dependencies** that must complete first (use `addBlockedBy`)
|
||||
- **Validation steps** needed
|
||||
- **Blockers** requiring resolution
|
||||
|
||||
## Status Management
|
||||
|
||||
```
|
||||
pending → Work not started
|
||||
in_progress → Currently working (one at a time)
|
||||
completed → Done (mark immediately)
|
||||
```
|
||||
|
||||
If blocked:
|
||||
1. `TaskCreate` for the blocker
|
||||
2. Use `addBlockedBy` to link
|
||||
3. Either keep blocked task `in_progress` or revert to `pending`
|
||||
4. Never mark a blocked task completed
|
||||
|
||||
## Visibility Goal
|
||||
|
||||
**Anyone reading your task list should understand:**
|
||||
- What you're currently doing (in_progress task)
|
||||
- What remains to be done (pending tasks)
|
||||
- What you've completed (completed tasks with descriptions)
|
||||
- What decisions were made (in descriptions)
|
||||
- What's blocking progress (blockedBy relationships)
|
||||
Reference in New Issue
Block a user