feat(core): add session manager workflow for persistent state
- Add workflow.yaml with session commands (start, resume, status, close) - Add instructions.md with detailed command documentation - Add session-template.yaml for consistent session structure - Support token tracking, milestone progress, and context preservation
This commit is contained in:
Ibrahim Elsahafy
parent
b59fcc7d55
commit
28b4e7a8ee
|
|
@ -0,0 +1,263 @@
|
||||||
|
# Session Manager Instructions
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Session Manager provides persistent state management across conversations with token isolation, progress tracking, and context preservation.
|
||||||
|
|
||||||
|
## Session ID Format
|
||||||
|
|
||||||
|
```
|
||||||
|
{PREFIX}{YYYYMM}-{CLIENT}-{PROJECT}
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
- `SES202501-ACME-AUDIT` - Default session for ACME audit project
|
||||||
|
- `ENG202501-TESLA-API` - Engineering session for Tesla API project
|
||||||
|
- `TST202501-INTERNAL-REWRITE` - Testing session for internal rewrite
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
### SESSION start
|
||||||
|
|
||||||
|
Start a new session with structured identification.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```
|
||||||
|
SESSION start
|
||||||
|
SESSION start --client ACME --project AUDIT
|
||||||
|
SESSION start --prefix ENG --client TESLA --project API
|
||||||
|
```
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Check if active session exists
|
||||||
|
- If yes, prompt: "Active session found: {id}. Close it first? [y/n]"
|
||||||
|
2. Generate session ID using format: `{PREFIX}{YYYYMM}-{CLIENT}-{PROJECT}`
|
||||||
|
3. Create session file at `{sessions_dir}/{session_id}.yaml`
|
||||||
|
4. Set as active session in `active-session.yaml`
|
||||||
|
5. Initialize session state:
|
||||||
|
```yaml
|
||||||
|
session_id: "{session_id}"
|
||||||
|
created: "{timestamp}"
|
||||||
|
status: "active"
|
||||||
|
client: "{client}"
|
||||||
|
project: "{project}"
|
||||||
|
tokens:
|
||||||
|
initial: 0
|
||||||
|
current: 0
|
||||||
|
saved: 0
|
||||||
|
agents_spawned: []
|
||||||
|
artifacts: []
|
||||||
|
milestones: []
|
||||||
|
context_summary: ""
|
||||||
|
```
|
||||||
|
6. Display confirmation with session ID
|
||||||
|
|
||||||
|
### SESSION resume
|
||||||
|
|
||||||
|
Resume an existing session with context restoration.
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Load `active-session.yaml` to get current session ID
|
||||||
|
2. If no active session, prompt: "No active session. Start new? [y/n]"
|
||||||
|
3. Load session file `{sessions_dir}/{session_id}.yaml`
|
||||||
|
4. Display session summary:
|
||||||
|
```
|
||||||
|
Resuming Session: {session_id}
|
||||||
|
Status: {status}
|
||||||
|
Started: {created}
|
||||||
|
Milestones: {milestone_count}
|
||||||
|
Artifacts: {artifact_count}
|
||||||
|
Token Usage: {current}/{max}
|
||||||
|
|
||||||
|
Last Context:
|
||||||
|
{context_summary}
|
||||||
|
```
|
||||||
|
5. Restore session variables to working memory
|
||||||
|
|
||||||
|
### SESSION status
|
||||||
|
|
||||||
|
Show current session status with visual indicators.
|
||||||
|
|
||||||
|
**Visual Status Indicators:**
|
||||||
|
| Indicator | Meaning |
|
||||||
|
|-----------|---------|
|
||||||
|
| :green_circle: | Active / On Track |
|
||||||
|
| :yellow_circle: | At Risk / Warning (>80% tokens) |
|
||||||
|
| :red_circle: | Blocked / Failed |
|
||||||
|
| :pause_button: | Paused |
|
||||||
|
| :white_check_mark: | Completed |
|
||||||
|
|
||||||
|
**Output Format:**
|
||||||
|
```
|
||||||
|
Session: {session_id} {status_indicator}
|
||||||
|
Duration: {duration}
|
||||||
|
Tokens: {current}/{max} ({percentage}%)
|
||||||
|
Progress Bar: [████████░░] 80%
|
||||||
|
|
||||||
|
Milestones:
|
||||||
|
- [x] Initial setup
|
||||||
|
- [x] Requirements gathered
|
||||||
|
- [ ] Implementation started
|
||||||
|
|
||||||
|
Recent Artifacts:
|
||||||
|
- docs/prd.md (created 2h ago)
|
||||||
|
- docs/architecture.md (modified 1h ago)
|
||||||
|
|
||||||
|
Agents Spawned This Session: {count}
|
||||||
|
Token Savings from Isolation: {saved_tokens}
|
||||||
|
```
|
||||||
|
|
||||||
|
### SESSION close
|
||||||
|
|
||||||
|
Close current session and archive.
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Load active session
|
||||||
|
2. Generate context summary (key decisions, outcomes, next steps)
|
||||||
|
3. Update session status to "closed"
|
||||||
|
4. Move session file to `{session_archive_dir}/`
|
||||||
|
5. Clear `active-session.yaml`
|
||||||
|
6. Display closure summary with learnings
|
||||||
|
|
||||||
|
### SESSION list
|
||||||
|
|
||||||
|
List all sessions with status.
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
```
|
||||||
|
Active Sessions:
|
||||||
|
SES202501-ACME-AUDIT :green_circle: (3 days)
|
||||||
|
|
||||||
|
Archived Sessions:
|
||||||
|
ENG202412-TESLA-API :white_check_mark: (closed 2024-12-28)
|
||||||
|
TST202412-INTERNAL-MVP :white_check_mark: (closed 2024-12-15)
|
||||||
|
```
|
||||||
|
|
||||||
|
### SESSION tokens
|
||||||
|
|
||||||
|
Show detailed token usage report.
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
```
|
||||||
|
Token Usage Report: {session_id}
|
||||||
|
|
||||||
|
Main Session:
|
||||||
|
Used: 45,000 / 150,000 (30%)
|
||||||
|
Remaining: 105,000
|
||||||
|
|
||||||
|
Subprocess Agents:
|
||||||
|
analyst: 32,000 tokens (isolated)
|
||||||
|
architect: 28,000 tokens (isolated)
|
||||||
|
dev: 85,000 tokens (isolated)
|
||||||
|
|
||||||
|
Total Consumed (if no isolation): 190,000
|
||||||
|
Actual Main Session: 45,000
|
||||||
|
Tokens Saved: 145,000 (76% savings)
|
||||||
|
```
|
||||||
|
|
||||||
|
### SESSION savings
|
||||||
|
|
||||||
|
Show token savings from isolation architecture.
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
```
|
||||||
|
Token Isolation Savings
|
||||||
|
|
||||||
|
Without Isolation:
|
||||||
|
All agent work in main context: 190,000 tokens
|
||||||
|
Would exceed limit by: 40,000 tokens
|
||||||
|
|
||||||
|
With Isolation:
|
||||||
|
Main session: 45,000 tokens
|
||||||
|
Agents in subprocesses: 145,000 tokens (not counted)
|
||||||
|
|
||||||
|
Savings: 145,000 tokens (76%)
|
||||||
|
Status: :green_circle: Within budget
|
||||||
|
```
|
||||||
|
|
||||||
|
### SESSION switch
|
||||||
|
|
||||||
|
Switch to a different session.
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Save current session state
|
||||||
|
2. Load specified session
|
||||||
|
3. Restore context
|
||||||
|
4. Update active-session.yaml
|
||||||
|
|
||||||
|
## Session File Structure
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# {session_id}.yaml
|
||||||
|
session_id: "SES202501-ACME-AUDIT"
|
||||||
|
created: "2025-01-15T10:30:00Z"
|
||||||
|
last_updated: "2025-01-15T14:45:00Z"
|
||||||
|
status: "active" # active, paused, closed
|
||||||
|
|
||||||
|
# Identification
|
||||||
|
client: "ACME"
|
||||||
|
project: "AUDIT"
|
||||||
|
prefix: "SES"
|
||||||
|
|
||||||
|
# Token tracking
|
||||||
|
tokens:
|
||||||
|
initial: 0
|
||||||
|
current: 45000
|
||||||
|
peak: 52000
|
||||||
|
saved_by_isolation: 145000
|
||||||
|
|
||||||
|
# Agent tracking
|
||||||
|
agents_spawned:
|
||||||
|
- id: "agent-123"
|
||||||
|
type: "analyst"
|
||||||
|
started: "2025-01-15T10:35:00Z"
|
||||||
|
completed: "2025-01-15T10:42:00Z"
|
||||||
|
tokens_used: 32000
|
||||||
|
output_file: "_bmad-output/temp/analyst-123.md"
|
||||||
|
|
||||||
|
# Artifacts produced
|
||||||
|
artifacts:
|
||||||
|
- path: "docs/prd.md"
|
||||||
|
created: "2025-01-15T11:00:00Z"
|
||||||
|
agent: "pm"
|
||||||
|
- path: "docs/architecture.md"
|
||||||
|
created: "2025-01-15T12:30:00Z"
|
||||||
|
agent: "architect"
|
||||||
|
|
||||||
|
# Progress tracking
|
||||||
|
milestones:
|
||||||
|
- name: "Requirements Complete"
|
||||||
|
completed: "2025-01-15T11:30:00Z"
|
||||||
|
- name: "Architecture Approved"
|
||||||
|
completed: "2025-01-15T13:00:00Z"
|
||||||
|
- name: "Implementation Started"
|
||||||
|
completed: null
|
||||||
|
|
||||||
|
# Context for resume
|
||||||
|
context_summary: |
|
||||||
|
Working on ACME security audit project.
|
||||||
|
PRD complete, architecture approved.
|
||||||
|
Currently implementing Epic 1: User Authentication.
|
||||||
|
Next: Complete story 1-2-user-login.
|
||||||
|
|
||||||
|
# Session notes
|
||||||
|
notes:
|
||||||
|
- "Client prefers OAuth2 over JWT"
|
||||||
|
- "Performance requirement: <200ms response time"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration with Token Isolation
|
||||||
|
|
||||||
|
When spawning agents via Task tool:
|
||||||
|
1. Record agent spawn in session
|
||||||
|
2. Track output file location
|
||||||
|
3. Calculate token savings
|
||||||
|
4. Update session totals
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Always start a session** before beginning substantial work
|
||||||
|
2. **Update milestones** as you complete major phases
|
||||||
|
3. **Close sessions** when work is complete to maintain clean state
|
||||||
|
4. **Use meaningful names** for client/project identification
|
||||||
|
5. **Review savings** periodically to understand isolation benefits
|
||||||
|
|
@ -0,0 +1,81 @@
|
||||||
|
# Session Template
|
||||||
|
# Copy and customize for new sessions
|
||||||
|
|
||||||
|
session_id: "{PREFIX}{YYYYMM}-{CLIENT}-{PROJECT}"
|
||||||
|
created: "{timestamp}"
|
||||||
|
last_updated: "{timestamp}"
|
||||||
|
status: "active"
|
||||||
|
|
||||||
|
# Identification
|
||||||
|
client: "{CLIENT}"
|
||||||
|
project: "{PROJECT}"
|
||||||
|
prefix: "{PREFIX}"
|
||||||
|
description: ""
|
||||||
|
|
||||||
|
# Token tracking
|
||||||
|
tokens:
|
||||||
|
initial: 0
|
||||||
|
current: 0
|
||||||
|
peak: 0
|
||||||
|
saved_by_isolation: 0
|
||||||
|
warning_threshold: 120000
|
||||||
|
max_limit: 150000
|
||||||
|
|
||||||
|
# Agent tracking
|
||||||
|
agents_spawned: []
|
||||||
|
# Example entry:
|
||||||
|
# - id: "agent-abc123"
|
||||||
|
# type: "analyst"
|
||||||
|
# started: "2025-01-15T10:35:00Z"
|
||||||
|
# completed: "2025-01-15T10:42:00Z"
|
||||||
|
# tokens_used: 32000
|
||||||
|
# output_file: "_bmad-output/temp/analyst-abc123.md"
|
||||||
|
# status: "completed" # running, completed, failed
|
||||||
|
|
||||||
|
# Artifacts produced
|
||||||
|
artifacts: []
|
||||||
|
# Example entry:
|
||||||
|
# - path: "docs/prd.md"
|
||||||
|
# type: "document"
|
||||||
|
# created: "2025-01-15T11:00:00Z"
|
||||||
|
# modified: "2025-01-15T11:30:00Z"
|
||||||
|
# agent: "pm"
|
||||||
|
# description: "Product Requirements Document"
|
||||||
|
|
||||||
|
# Progress tracking
|
||||||
|
milestones: []
|
||||||
|
# Example entry:
|
||||||
|
# - name: "Requirements Complete"
|
||||||
|
# target_date: "2025-01-15"
|
||||||
|
# completed: "2025-01-15T11:30:00Z"
|
||||||
|
# notes: "All stakeholder requirements gathered"
|
||||||
|
|
||||||
|
# Current work context
|
||||||
|
current_focus:
|
||||||
|
epic: ""
|
||||||
|
story: ""
|
||||||
|
task: ""
|
||||||
|
blocker: ""
|
||||||
|
|
||||||
|
# Context for resume (AI-generated summary)
|
||||||
|
context_summary: |
|
||||||
|
Session initialized. Ready to begin work.
|
||||||
|
|
||||||
|
# Decision log
|
||||||
|
decisions: []
|
||||||
|
# Example entry:
|
||||||
|
# - date: "2025-01-15"
|
||||||
|
# decision: "Use PostgreSQL for primary database"
|
||||||
|
# rationale: "Team expertise, ACID compliance needs"
|
||||||
|
# made_by: "architect"
|
||||||
|
|
||||||
|
# Session notes
|
||||||
|
notes: []
|
||||||
|
# Example entry:
|
||||||
|
# - timestamp: "2025-01-15T10:30:00Z"
|
||||||
|
# note: "Client prefers OAuth2 over JWT"
|
||||||
|
# source: "user"
|
||||||
|
|
||||||
|
# Tags for filtering
|
||||||
|
tags: []
|
||||||
|
# Example: ["security", "audit", "enterprise"]
|
||||||
|
|
@ -0,0 +1,52 @@
|
||||||
|
# Session Manager Workflow
|
||||||
|
name: session-manager
|
||||||
|
description: "Persistent session management with token isolation, state tracking, and context preservation across conversations"
|
||||||
|
author: "BMAD"
|
||||||
|
version: "1.0.0"
|
||||||
|
|
||||||
|
# Configuration sources
|
||||||
|
config_source: "{project-root}/_bmad/core/config.yaml"
|
||||||
|
user_name: "{config_source}:user_name"
|
||||||
|
communication_language: "{config_source}:communication_language"
|
||||||
|
output_folder: "{config_source}:output_folder"
|
||||||
|
date: system-generated
|
||||||
|
|
||||||
|
# Session storage
|
||||||
|
sessions_dir: "{project-root}/_bmad-output/sessions"
|
||||||
|
active_session_file: "{sessions_dir}/active-session.yaml"
|
||||||
|
session_archive_dir: "{sessions_dir}/archive"
|
||||||
|
|
||||||
|
# Workflow components
|
||||||
|
installed_path: "{project-root}/_bmad/core/workflows/session-manager"
|
||||||
|
instructions: "{installed_path}/instructions.md"
|
||||||
|
|
||||||
|
# Session ID format: {PREFIX}{YYYYMM}-{CLIENT}-{PROJECT}
|
||||||
|
session_prefixes:
|
||||||
|
default: "SES"
|
||||||
|
engineering: "ENG"
|
||||||
|
analysis: "ANA"
|
||||||
|
design: "DES"
|
||||||
|
testing: "TST"
|
||||||
|
|
||||||
|
standalone: true
|
||||||
|
|
||||||
|
# Commands
|
||||||
|
commands:
|
||||||
|
- name: "start"
|
||||||
|
description: "Start a new session"
|
||||||
|
args: "--client NAME --project NAME --prefix PREFIX"
|
||||||
|
- name: "resume"
|
||||||
|
description: "Resume the active session"
|
||||||
|
- name: "status"
|
||||||
|
description: "Show current session status and token usage"
|
||||||
|
- name: "close"
|
||||||
|
description: "Close current session and archive"
|
||||||
|
- name: "list"
|
||||||
|
description: "List all sessions (active and archived)"
|
||||||
|
- name: "tokens"
|
||||||
|
description: "Show detailed token usage report"
|
||||||
|
- name: "savings"
|
||||||
|
description: "Show token savings from isolation"
|
||||||
|
- name: "switch"
|
||||||
|
description: "Switch to a different session"
|
||||||
|
args: "SESSION_ID"
|
||||||
Loading…
Reference in New Issue