Pattern-021: Development Session Management Pattern

Status

Proven

Context

⚠️ Disambiguation Note: This pattern covers development workflow session logging and tracking. For database/user application sessions, see Pattern-013: Session Management Pattern.

Development teams need to track progress across complex, multi-step development tasks that span multiple sessions and agents. Without systematic session management, development work lacks accountability, progress tracking, and historical context. The Development Session Management Pattern addresses:

Pattern Description

The Development Session Management Pattern manages development session logging and progress tracking for workflow accountability, agent coordination, and development audit trails.

Core concept:

Implementation

Development Session Manager

from pathlib import Path
from datetime import datetime
from typing import List, Dict, Any, Optional
import json

class DevelopmentSessionManager:
    """Manages development session logging and progress tracking"""

    def __init__(self, session_logs_dir: Path):
        self.logs_dir = Path(session_logs_dir)
        self.logs_dir.mkdir(exist_ok=True)
        self.current_session: Optional[Dict[str, Any]] = None

    def start_session(self, agent_name: str, mission: str, issue_ref: str = None) -> str:
        """Start new development session"""
        timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
        session_id = f"{timestamp}-{agent_name.lower().replace(' ', '-')}-log"

        session_data = {
            "session_id": session_id,
            "agent": agent_name,
            "mission": mission,
            "issue_ref": issue_ref,
            "started_at": datetime.now().isoformat(),
            "phases": [],
            "evidence": [],
            "deliverables": [],
            "status": "active"
        }

        self.current_session = session_data
        self._save_session()
        return session_id

    def log_phase(self, phase_name: str, description: str, evidence: Dict[str, Any] = None):
        """Log development phase with evidence"""
        if not self.current_session:
            raise ValueError("No active session. Call start_session() first.")

        phase_data = {
            "phase": phase_name,
            "description": description,
            "timestamp": datetime.now().isoformat(),
            "evidence": evidence or {}
        }

        self.current_session["phases"].append(phase_data)
        if evidence:
            self.current_session["evidence"].append({
                "phase": phase_name,
                "timestamp": datetime.now().isoformat(),
                **evidence
            })

        self._save_session()

    def log_terminal_output(self, command: str, output: str, phase: str = None):
        """Log terminal command and output as evidence"""
        evidence = {
            "type": "terminal_output",
            "command": command,
            "output": output,
            "phase": phase or "current"
        }

        if self.current_session:
            self.current_session["evidence"].append({
                "timestamp": datetime.now().isoformat(),
                **evidence
            })
            self._save_session()

    def add_deliverable(self, file_path: str, description: str, type: str = "file"):
        """Add deliverable to current session"""
        if not self.current_session:
            raise ValueError("No active session")

        deliverable = {
            "path": file_path,
            "description": description,
            "type": type,
            "timestamp": datetime.now().isoformat()
        }

        self.current_session["deliverables"].append(deliverable)
        self._save_session()

    def complete_session(self, summary: str, next_steps: List[str] = None):
        """Complete development session"""
        if not self.current_session:
            raise ValueError("No active session")

        self.current_session.update({
            "completed_at": datetime.now().isoformat(),
            "status": "completed",
            "summary": summary,
            "next_steps": next_steps or [],
            "total_phases": len(self.current_session["phases"]),
            "total_evidence": len(self.current_session["evidence"])
        })

        self._save_session()
        completed_session = self.current_session
        self.current_session = None
        return completed_session

    def create_handoff_prompt(self, target_agent: str, context: str = None) -> str:
        """Create handoff prompt for next agent"""
        if not self.current_session:
            raise ValueError("No active session")

        handoff_data = {
            "from_agent": self.current_session["agent"],
            "to_agent": target_agent,
            "session_id": self.current_session["session_id"],
            "mission": self.current_session["mission"],
            "completed_phases": self.current_session["phases"],
            "deliverables": self.current_session["deliverables"],
            "context": context,
            "handoff_time": datetime.now().isoformat()
        }

        # Save handoff documentation
        handoff_file = self.logs_dir / f"{self.current_session['session_id']}-handoff.json"
        with open(handoff_file, 'w') as f:
            json.dump(handoff_data, f, indent=2)

        return self._format_handoff_prompt(handoff_data)

    def _format_handoff_prompt(self, handoff_data: Dict[str, Any]) -> str:
        """Format handoff data into prompt"""
        phases_summary = "\n".join([
            f"- {phase['phase']}: {phase['description']}"
            for phase in handoff_data["completed_phases"]
        ])

        deliverables_summary = "\n".join([
            f"- {d['path']}: {d['description']}"
            for d in handoff_data["deliverables"]
        ])

        return f"""
# Agent Handoff: {handoff_data['from_agent']} → {handoff_data['to_agent']}

## Mission
{handoff_data['mission']}

## Completed Work
{phases_summary}

## Deliverables
{deliverables_summary}

## Context
{handoff_data.get('context', 'No additional context provided')}

## Session Reference
{handoff_data['session_id']}

Please continue from where {handoff_data['from_agent']} left off.
"""

    def _save_session(self):
        """Save session to file"""
        if not self.current_session:
            return

        session_file = self.logs_dir / f"{self.current_session['session_id']}.json"
        with open(session_file, 'w') as f:
            json.dump(self.current_session, f, indent=2)

    def get_session_history(self, days: int = 30) -> List[Dict[str, Any]]:
        """Get recent session history"""
        cutoff_date = datetime.now() - timedelta(days=days)
        sessions = []

        for session_file in self.logs_dir.glob("*.json"):
            if session_file.name.endswith("-handoff.json"):
                continue

            try:
                with open(session_file, 'r') as f:
                    session = json.load(f)

                session_date = datetime.fromisoformat(session["started_at"])
                if session_date >= cutoff_date:
                    sessions.append(session)
            except (json.JSONDecodeError, KeyError):
                continue

        return sorted(sessions, key=lambda s: s["started_at"], reverse=True)

Session Integration with Agents

class AgentSessionIntegration:
    """Integration layer for agents to use session management"""

    def __init__(self, session_manager: DevelopmentSessionManager):
        self.session_manager = session_manager

    def start_agent_session(self, agent_name: str, task_description: str, issue_ref: str = None):
        """Start session for agent work"""
        session_id = self.session_manager.start_session(
            agent_name=agent_name,
            mission=task_description,
            issue_ref=issue_ref
        )

        self.session_manager.log_phase(
            "initialization",
            f"Agent {agent_name} started work on: {task_description}"
        )

        return session_id

    def log_work_phase(self, phase_name: str, description: str, files_modified: List[str] = None):
        """Log a work phase with file modifications"""
        evidence = {}
        if files_modified:
            evidence["files_modified"] = files_modified

        self.session_manager.log_phase(phase_name, description, evidence)

    def log_verification_step(self, verification_type: str, result: bool, details: str = None):
        """Log verification steps for accountability"""
        self.session_manager.log_phase(
            "verification",
            f"{verification_type}: {'✅ PASSED' if result else '❌ FAILED'}",
            {
                "verification_type": verification_type,
                "result": result,
                "details": details or "No additional details"
            }
        )

# Usage example
session_manager = DevelopmentSessionManager(Path("docs/development/session-logs"))
agent_integration = AgentSessionIntegration(session_manager)

# Agent starts work
session_id = agent_integration.start_agent_session(
    "Code Agent",
    "Extract patterns 011-015 from dual pattern systems",
    "PM-170"
)

# Log work phases
agent_integration.log_work_phase(
    "pattern_extraction",
    "Extracted Pattern-011: Context Resolution Pattern",
    ["docs/patterns/pattern-011-context-resolution.md"]
)

# Log verification
agent_integration.log_verification_step(
    "template_compliance",
    True,
    "Pattern follows established template structure"
)

# Complete session
session_manager.complete_session(
    "Successfully extracted and documented patterns 011-015",
    ["Cross-validate with Cursor agent", "Update GitHub issue status"]
)

Usage Guidelines

Session Lifecycle Management

Evidence Collection

Agent Coordination

Benefits

Trade-offs

Anti-patterns to Avoid

References

Migration Notes

Split from Pattern-013 Session Management Pattern to focus specifically on development workflow tracking. For database/user sessions, see Pattern-013: Database Session Management Pattern.