Repository navigation
03 workflows session management
Doug Beard edited this page Aug 20, 2025
·
2 revisions
Effective session management in Coherence APM Framework v4.2.0 maintains unified context through the .apm/session_notes/ directory, preserving work progress and ensuring seamless collaboration across the 11 specialized personas. This workflow ensures no information is lost and every session builds upon previous work through the actual session management features.
-
Unified Context Engineering: Every action documented in
.apm/session_notes/directory -
Persistent Context: Work context maintained across sessions and persona transitions using
/switchand/handoffcommands - Seamless Knowledge Transfer: Information flows between personas through session notes
- Voice Integration: Audio notifications confirm session milestones using TTS system
- Recovery Capability: Resume work from any point using session note history
- Automatic Session Management: Framework automatically creates and manages session files
- Work Sessions: Active development, analysis, or planning work
- Handoff Sessions: Transitions between personas or team members
- Review Sessions: Progress review, stakeholder updates, quality assurance
- Planning Sessions: Sprint planning, architecture design, strategy sessions
# Session: [Descriptive Title]
Date: YYYY-MM-DD HH:MM:SS
Persona: [Active Persona/Role]
Session Type: [Work/Handoff/Review/Planning]
## Session Objectives
- [ ] Primary objective 1
- [ ] Primary objective 2
- [ ] Primary objective 3
## Context from Previous Session
[Brief summary of relevant context from previous work]
## Work Progress
### [HH:MM] - [Action/Task Description]
- Status: [In Progress/Completed/Blocked]
- Details: [Specific work done]
- Files Modified: [List of changed files]
- Decisions Made: [Important decisions]
- Issues Encountered: [Problems and resolutions]
### [HH:MM] - [Next Action/Task]
[Continue documenting work as it happens]
## Key Decisions Made
1. **Decision**: [What was decided]
- **Rationale**: [Why this decision was made]
- **Impact**: [How this affects project]
- **Alternatives Considered**: [Other options evaluated]
## Issues & Blockers
### Active Issues
- **Issue**: [Description of problem]
- **Impact**: [How it affects work]
- **Resolution Plan**: [Steps to resolve]
- **Owner**: [Who is responsible]
### Resolved Issues
- **Issue**: [Problem that was solved]
- **Resolution**: [How it was solved]
- **Lessons Learned**: [What we learned]
## Artifacts Created/Modified
- **File**: `/path/to/file.ext`
- **Changes**: [Description of changes made]
- **Purpose**: [Why changes were made]
## Next Session Preparation
### Immediate Next Steps
1. [Action item 1 - with owner and timeline]
2. [Action item 2 - with owner and timeline]
3. [Action item 3 - with owner and timeline]
### Context for Next Session
- **Current State**: [Where things stand now]
- **Priority Items**: [What should be tackled first next time]
- **Known Issues**: [Problems that need attention]
- **Dependencies**: [What we're waiting for]
## Session Metrics
- **Duration**: [How long session lasted]
- **Productivity Score**: [1-10 self-assessment]
- **Objectives Completed**: [X of Y objectives achieved]
- **Blocker Resolution**: [Issues resolved vs. new issues created]The Coherence framework automatically manages session notes in:
.apm/session_notes/
├── session_notes.md # Current active session
├── YYYY-MM-DD-HH-mm-ss-Persona-Action.md # Specific session files
└── pre_compact_archive/ # Archived sessions
└── YYYY-MM-DDTHH-mm-ss.nnnnnn/ # Timestamped archives
└── [archived session files]
Framework-Created Files:
-
session_notes.md- Main session file, continuously updated -
YYYY-MM-DD-HH-mm-ss-Coherence-Orchestrator-Activation.md- Orchestrator sessions - Archive files in
pre_compact_archive/when sessions reach capacity
Naming Convention Examples (Actual):
2025-08-16-19-42-03-AP-Orchestrator-Activation.mdsession_notes.md- Pre-compact archives with timestamp directories
Every session must begin with:
- Context Check: Read latest session notes for relevant context
- Session Note Creation: Create new session note with current timestamp
- Objective Setting: Define clear objectives for the session
- Previous Work Review: Understand what was accomplished previously
Coherence Session Initialization Pattern:
# 1. Initialize Coherence Orchestrator
/coherence
# 2. Automatic session note creation in .apm/session_notes/
# Framework automatically creates: YYYY-MM-DD-HH-mm-ss-Coherence-Orchestrator-Activation.md
# 3. Check existing session context
LS .apm/session_notes/
# 4. Read current session note (automatically managed)
Read .apm/session_notes/session_notes.md
# 5. Voice notification automatically provided
# Audio: "Coherence Orchestrator activated. Loading unified context engineering system."Available Session Commands:
-
/session-note-setup- Initialize session management -
/coherence- Launch with automatic session creation -
/switch <persona>- Transition with session continuity -
/handoff <persona>- Transfer with session documentation
Document in real-time when:
- ✅ Starting work on a new task or component
- ✅ Completing significant work or reaching milestones
- ✅ Making important decisions or architectural choices
- ✅ Encountering and resolving issues or blockers
- ✅ Every 15-20 minutes during active work (progress checkpoints)
- ✅ Modifying key files like backlog.md, requirements.md, etc.
- ✅ Before switching contexts or taking breaks
Documentation Update Pattern:
### [10:30] - Started User Authentication Implementation
- Status: In Progress
- Approach: Using JWT tokens with refresh token rotation
- Files: Created `auth.js`, `user-model.js`, `auth-middleware.js`
- Decision: Using bcrypt for password hashing (industry standard)
### [11:15] - Progress Checkpoint
- Status: 60% complete
- Completed: User model, password hashing, basic JWT creation
- Next: Token validation middleware and refresh token logic
- Issues: None currently
### [12:00] - Authentication Module Completed
- Status: Completed
- Files Modified: auth.js, user-model.js, auth-middleware.js, tests/auth.test.js
- Testing: All unit tests passing
- Integration: Ready for integration testingWhen switching personas or ending sessions:
- Complete Current Work Documentation: Ensure all recent work is documented
- Update Project Artifacts: Ensure backlog.md and other key files are current
- Handoff Summary: Create clear summary for next session/persona
- Context Preservation: Document current state and immediate next steps
Handoff Documentation Pattern:
## Handoff to [Next Persona/Session]
### Current State
- Authentication module implementation: 90% complete
- Remaining work: Integration testing and error handling
- All unit tests passing, ready for system testing
### Immediate Next Steps for [Next Persona]
1. Run integration tests with authentication module
2. Implement error handling for authentication failures
3. Update API documentation with authentication endpoints
### Context to Preserve
- JWT token expiration set to 15 minutes (security requirement)
- Refresh token rotation implemented per OWASP guidelines
- Database schema includes user roles for future authorization
### Files to Focus On
- `/src/auth/auth.js` - Main authentication logic
- `/tests/auth.test.js` - Unit tests (all passing)
- `/docs/api.md` - Needs update with auth endpointsWhen to Archive:
- Session is complete and documented
- All handoff information is captured
- No immediate follow-up work planned
- Session represents a logical completion point
Archiving Process:
- Final Review: Ensure session note is complete and accurate
-
Move to Archive: Move to
/session_notes/archive/directory - Create Archive Summary: Brief summary of session outcomes
- Update Session Index: Maintain searchable index of archived sessions
Context Layers:
- Immediate Context: Current session work and decisions
- Project Context: Overall project status and long-term decisions
- Historical Context: Previous sessions and lessons learned
- Environmental Context: Technical constraints and dependencies
Context Retrieval Process:
- Latest Session Review: Always check most recent session notes
- Related Work Search: Find sessions with related work or decisions
- Issue History: Review previous solutions to similar problems
- Decision History: Understand rationale behind past architectural choices
Context Documentation Points:
- Decision Rationale: Why decisions were made, not just what was decided
- Alternative Options: What other approaches were considered
- Environmental Factors: Technical, business, or resource constraints that influenced decisions
- Success Criteria: How to measure if decisions/implementations are successful
Session 1: Requirements analysis and architecture design Session 2: Core implementation and unit testing Session 3: Integration testing and bug fixes Session 4: User acceptance testing and documentation
Context Flow:
- Session 1 → Session 2: Architecture decisions and implementation plan
- Session 2 → Session 3: Implementation details and known issues
- Session 3 → Session 4: Test results and remaining work
Developer Session: Implement core functionality QA Session: Create test framework and execute tests Architect Session: Review implementation against architecture Product Session: Validate against business requirements
Context Handoffs:
- Developer → QA: Implementation details and test scenarios
- QA → Architect: Test results and architectural concerns
- Architect → Product: Technical recommendations and trade-offs
- Product → Developer: Requirements clarification and priorities
Analysis Session: Problem analysis and solution options Implementation Session: Initial implementation attempt Review Session: Review results and identify improvements Refinement Session: Implement improvements and finalize
- Problem: Starting new sessions without reviewing previous work
- Impact: Repeated work, inconsistent decisions, lost progress
- Solution: Always review recent session notes before starting new work
- Problem: Delaying documentation until end of session
- Impact: Lost details, incomplete context, poor handoffs
- Solution: Document continuously throughout session
- Problem: Single session file becomes too large or unfocused
- Impact: Difficult to find information, poor organization
- Solution: Keep sessions focused, create new session for different work
- Problem: Insufficient information for next session/persona
- Impact: Lost context, repeated analysis, delayed progress
- Solution: Structured handoff documentation with clear next steps
- Set Clear Objectives: Define what the session should accomplish
- Time Boxing: Allocate appropriate time for different activities
- Context Preparation: Review relevant previous sessions before starting
- Success Criteria: Define how to measure session success
- Continuous Updates: Document as work happens, not afterward
- Decision Capture: Record rationale behind decisions when made
- Issue Tracking: Document problems and solutions immediately
- Progress Markers: Regular checkpoint documentation
- Current State Summary: Clear description of where things stand
- Next Steps: Specific, actionable next steps for next session/persona
- Context Preservation: Key decisions, constraints, and requirements
- Issue Awareness: Known problems and potential solutions
- Documentation Completeness: Percentage of work properly documented
- Context Continuity: Success rate of session handoffs
- Objective Achievement: Percentage of session objectives met
- Issue Resolution Rate: Problems resolved vs. problems created
- Session Efficiency: Work completed per time invested
- Context Retrieval Time: Time spent getting up to speed each session
- Rework Rate: Percentage of work that needs to be redone
- Knowledge Transfer Success: Information successfully preserved across sessions
- Documentation Currency: How up-to-date project documentation is
- Decision Traceability: Ability to trace current state back to decisions
- Issue Resolution Time: Time from issue identification to resolution
- Team Alignment: Consistency of understanding across team members
- Session Note Templates: Standardized templates for different session types
- Context Search: Tools to find relevant previous sessions
- Progress Tracking: Integration with backlog.md and project tracking
- Handoff Automation: Automated handoff documentation generation
- Automatic Documentation: native Claude Code slash commands automatically update session notes
- Context Awareness: Commands check previous session context
- Progress Tracking: Commands update project progress automatically
- Voice Notifications: Audio feedback for session management actions
- Handoff Patterns - Specific patterns for persona transitions
- Team Collaboration - Multi-user session management
- Backlog Workflow - Integration with project tracking
- Parallel Development - Managing multiple concurrent sessions
- Reviewed latest relevant session notes
- Created new session note with clear objectives
- Understood context from previous work
- Set realistic time expectations
- Prepared necessary tools and resources
- Documenting work progress in real-time
- Recording important decisions and rationale
- Tracking issues and resolutions
- Updating project artifacts (backlog.md, etc.)
- Regular progress checkpoints every 15-20 minutes
- All work progress documented
- Important decisions recorded with rationale
- Issues and resolutions captured
- Next steps clearly defined
- Handoff information complete
- Project artifacts updated
- Session objectives reviewed and marked complete/incomplete
Master session management to ensure no context is lost and every session builds upon previous achievements.