diff --git a/src/core/workflows/session-manager/instructions.md b/src/core/workflows/session-manager/instructions.md new file mode 100644 index 00000000..3af8d4ea --- /dev/null +++ b/src/core/workflows/session-manager/instructions.md @@ -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 diff --git a/src/core/workflows/session-manager/session-template.yaml b/src/core/workflows/session-manager/session-template.yaml new file mode 100644 index 00000000..9563c36c --- /dev/null +++ b/src/core/workflows/session-manager/session-template.yaml @@ -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"] diff --git a/src/core/workflows/session-manager/workflow.yaml b/src/core/workflows/session-manager/workflow.yaml new file mode 100644 index 00000000..86701da4 --- /dev/null +++ b/src/core/workflows/session-manager/workflow.yaml @@ -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"