context-snapshot-generator

Autonomous agent for generating minimal context snapshots that capture essential session state for efficient handoff, designed to fit under 500 tokens while preserving critical continuity information.

Capabilities

Generate token-optimized session snapshots
Capture current focus, progress, and blockers
Extract key decisions and modified files
Create resume commands for quick restart
Store snapshots for session recovery

Invocation

# Via /agent command
/agent context-snapshot-generator "Create handoff snapshot"

# Via Task tool
Task(subagent_type="general-purpose", prompt="Use context-snapshot-generator agent to create session snapshot for Track E")

# Via hook (automatic)
# Triggered by session-handoff hook at session end

Parameters

Parameter	Type	Required	Description
`tracks`	string[]	No	Specific tracks to include (default: all)
`token_limit`	integer	No	Target token count (default: 500)
`full`	boolean	No	Full snapshot ~1000 tokens
`save`	boolean	No	Save to context-storage
`format`	string	No	Output format (markdown, json)

Token Budget

Information	Tokens	Priority
Current focus	~50	P0 - Critical
Track status table	~100	P0 - Critical
Key files (5 max)	~75	P1 - Important
Critical decisions (3 max)	~100	P1 - Important
Resume command	~25	P0 - Critical
Context links	~50	P2 - Reference
Total	~400

Workflow

┌─────────────────────────────────────────────────────────────────┐
│               CONTEXT SNAPSHOT WORKFLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   1. EXTRACT                2. PRIORITIZE        3. COMPRESS    │
│   ┌──────────┐             ┌──────────┐         ┌──────────┐   │
│   │   Read   │────────────▶│  Rank by │────────▶│  Trim to │   │
│   │ Sources  │             │ Priority │         │  Budget  │   │
│   └──────────┘             └──────────┘         └──────────┘   │
│        │                        │                    │          │
│        ▼                        ▼                    ▼          │
│   ┌──────────┐             ┌──────────┐         ┌──────────┐   │
│   │  PILOT   │             │   P0:    │         │   500    │   │
│   │  Plan    │             │  Focus   │         │  Tokens  │   │
│   ├──────────┤             ├──────────┤         │   Max    │   │
│   │ Session  │             │   P1:    │         └──────────┘   │
│   │  Logs    │             │  Files   │                        │
│   ├──────────┤             ├──────────┤                        │
│   │   Git    │             │   P2:    │                        │
│   │  Status  │             │  Links   │                        │
│   └──────────┘             └──────────┘                        │
│                                                                  │
│   4. FORMAT                 5. VALIDATE          6. STORE       │
│   ┌──────────┐             ┌──────────┐         ┌──────────┐   │
│   │ Render   │────────────▶│  Token   │────────▶│   Save   │   │
│   │ Template │             │  Count   │         │ Snapshot │   │
│   └──────────┘             └──────────┘         └──────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Output Format (~400 tokens)

# Context Snapshot
**Generated:** 2026-01-02T00:30:00Z | **Session:** session-8-integration-deployment

## Current State
- **Focus:** Track E.1 Integration Testing
- **Last Completed:** E.1.5 (Activation limit test)
- **In Progress:** None
- **Blocked:** C.2.1 (SSL certificate pending)

## Track Summary
| Track | Status | Next Task |
|-------|--------|-----------|
| E | 80% | E.2.1 Rate limiting |
| C | 60% | C.1.3 SSL cert |
| D | 100% | Complete |

## Key Files Modified
- `tests/e2e/test_signup_activation_flow.py` (new)
- `tests/e2e/test_cross_platform_validation.py` (new)
- `tests/e2e/test_webhook_reliability.py` (new)
- `tests/e2e/test_offline_mode.py` (new)
- `tests/e2e/test_activation_limits.py` (new)

## Critical Decisions
1. Track E.1 complete - 5 E2E test files, 70 tests total
2. Integration Testing at 80% - E.2 Security Testing next
3. Production Deployment still blocking (60%)

## Resume Command
```bash
/pilot --track E --task E.2.1

Full Context

Session Log: docs/session-logs/SESSION-LOG-2026-01-01.md
PILOT Plan: internal/project/plans/PILOT-PARALLEL-EXECUTION-PLAN.md

## Storage Structure

context-storage/ ├── snapshots/ │ ├── SNAPSHOT-2026-01-01-220000.md │ ├── SNAPSHOT-2026-01-01-230000.md │ └── SNAPSHOT-2026-01-02-003000.md └── latest-snapshot.md # Symlink to most recent

## Algorithm

```python
def generate_snapshot(
    session_log: str,
    pilot_plan: str,
    token_limit: int = 500
) -> str:
    """Generate minimal context snapshot."""

    # Extract data from sources
    current_state = extract_current_state(session_log)
    track_summary = extract_track_status(pilot_plan)
    recent_files = get_recent_files(limit=5)
    decisions = get_critical_decisions(limit=3)
    resume_cmd = generate_resume_command(current_state)

    # Build snapshot with priority ordering
    snapshot = SnapshotBuilder(token_limit)
    snapshot.add(current_state, priority=0)      # P0 - Always include
    snapshot.add(track_summary, priority=0)      # P0 - Always include
    snapshot.add(resume_cmd, priority=0)         # P0 - Always include
    snapshot.add(recent_files, priority=1)       # P1 - Include if space
    snapshot.add(decisions, priority=1)          # P1 - Include if space
    snapshot.add(context_links, priority=2)      # P2 - Include if space

    # Render within token limit
    return snapshot.render()

def count_tokens(text: str) -> int:
    """Approximate token count (4 chars per token)."""
    return len(text) // 4

Integration

With session-handoff Hook

# hooks/session-handoff.py
def on_session_end():
    """Generate snapshot at session end."""
    snapshot = context_snapshot_generator.run(save=True)
    print(f"✅ Snapshot saved: {snapshot.path}")
    print(f"   Tokens: {snapshot.token_count}")

With /context-snapshot Command

# Command invokes this agent
/context-snapshot
# Internally: /agent context-snapshot-generator "save=true"

# With options
/context-snapshot --tracks E,C --full

Use Cases

Use Case	Description
Session Handoff	Pass context to new session or agent
Context Recovery	Resume after context window limit
Status Reporting	Quick project status summary
Checkpoint Creation	Pre-commit state capture

Command: /context-snapshot
Skill: efficiency-optimization
Hook: session-handoff
Command: /cx

Agent Version: 1.0.0 Created: 2026-01-02 Author: CODITECT Process Refinement

Success Output

When this agent completes successfully:

AGENT COMPLETE: context-snapshot-generator
Task: Generate minimal context snapshot for session handoff
Result: Token-optimized snapshot (~400-500 tokens) with current state, track summary, key files, critical decisions, and resume command

Completion Checklist

Before marking complete:

Snapshot fits within token budget (default 500, max 1000 for --full)
P0 sections included (current focus, track status, resume command)
Key files limited to 5 most recent/relevant
Critical decisions limited to 3 most important

Failure Indicators

This agent has FAILED if:

Snapshot exceeds token limit without explicit override
Missing resume command (required for session handoff)
Track status table absent or incomplete
Generated snapshot cannot be used to resume work in new session

When NOT to Use

Do NOT use this agent when:

Full context export needed (use /export command instead)
Analyzing context health (use context-health-analyst instead)
Compressing context for continued use (use context-compression skill instead)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Verbose snapshots	Exceeds token budget, defeats purpose	Strict priority ordering, trim P2 content first
Missing resume path	Cannot continue work in new session	Always include resume command with exact task ID
Stale track status	Misleading progress indicators	Extract from PILOT plan, not cached data

Principles

This agent embodies:

#4 Separation of Concerns - Snapshot generation separate from context analysis or compression
#9 Based on Facts - Track status derived from PILOT plan, files from git status, not assumptions

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Core Responsibilities

Analyze and assess memory-intelligence requirements within the Memory Intelligence domain
Provide expert guidance on context snapshot generator best practices and standards
Generate actionable recommendations with implementation specifics
Validate outputs against CODITECT quality standards and governance requirements
Integrate findings with existing project plans and track-based task management

Invocation Examples

Direct Agent Call

Task(subagent_type="context-snapshot-generator",
     description="Brief task description",
     prompt="Detailed instructions for the agent")

Via CODITECT Command

/agent context-snapshot-generator "Your task description here"

Via MoE Routing

/which Autonomous agent for generating minimal context snapshots th

Capabilities​

Invocation​

Parameters​

Token Budget​

Workflow​

Output Format (~400 tokens)​

Full Context​

Integration​

With session-handoff Hook​

With /context-snapshot Command​

Use Cases​

Related Components​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Core Responsibilities​

Invocation Examples​

Direct Agent Call​

Via CODITECT Command​

Via MoE Routing​