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