Session Management

Session Management Skill

Activate this skill for all session state operations during Maestro orchestration. This skill defines the protocols for creating, updating, resuming, and archiving orchestration sessions.

State Access Protocol

When MCP state tools are available, prefer them for state operations:

• Preferred: MCP tools (initialize_workspace, create_session, update_session, transition_phase, get_session_status, archive_session) — structured I/O, atomic operations.
• Fallback: write_file/replace directly on state files — when MCP tools are not in the available tool list.
• Legacy: Shell scripts (write-state.js, read-state.js) — remain available but are not the recommended path.

Detection: check whether MCP state tools appear in your available tools. If they do, use them. If they do not, use write_file/replace.

Hook-Level Session State

Maestro hooks maintain a separate, transient state directory under ${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/ that is distinct from orchestration state in <MAESTRO_STATE_DIR>:

The pre-delegation hook prunes stale hook state directories older than 2 hours to prevent accumulation from abnormal session terminations.

The orchestrator does not read or write hook-level state directly. It interacts only with <MAESTRO_STATE_DIR> paths. The two state systems are independent and serve different concerns.

Session Creation Protocol

When to Create

For Standard workflow, create a new session at execution setup after the design document and implementation plan are approved and the execution mode gate has resolved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template).

Session ID Format

YYYY-MM-DD-<topic-slug>

Where:

• YYYY-MM-DD is the orchestration start date
• <topic-slug> is a lowercase, hyphenated summary matching the design document topic

File Location

<MAESTRO_STATE_DIR>/state/active-session.md

All state paths in this skill use <MAESTRO_STATE_DIR> as their base directory (default: docs/maestro). In procedural steps, <state_dir> represents the resolved value of this variable.

State File Access

Both read_file and write_file work on state paths inside <MAESTRO_STATE_DIR>. The runtime's file-access configuration makes state paths accessible.

Use the runtime's bundled scripts/ directory for these helper commands so they still work when the extension is installed outside the workspace root.

Reading state files: Use read_file directly. The read-state.js script remains available as an alternative for TOML shell blocks that inject state before the model's first turn:

run_shell_command: node <runtime-script-root>/read-state.js <relative-path>

Writing state files: Use write_file directly. When content must be piped from a shell command, use the atomic write script:

run_shell_command: echo '...' | node <runtime-script-root>/write-state.js <relative-path>

Rules:

• The write-state.js script writes atomically (temp file + rename) to prevent partial writes
• Both scripts validate against absolute paths and path traversal

Initialization Steps

1. Resolve state directory from MAESTRO_STATE_DIR
2. Create <state_dir>/state/ directory if it does not exist (defense-in-depth fallback — workspace readiness startup check is the primary mechanism)
3. Verify no existing active-session.md — if one exists, alert the user and offer to archive or resume
4. Generate session state using the session-state template loaded via get_skill_content
5. Initialize all phases as pending
6. Set overall status to in_progress
7. Set current_phase to 1
8. Record design document and implementation plan paths
9. Initialize empty token_usage, file manifests, downstream_context, and errors sections

Initial State Template

---
session_id: "<YYYY-MM-DD-topic-slug>"
task: "<user's original task description>"
created: "<ISO 8601 timestamp>"
updated: "<ISO 8601 timestamp>"
status: "in_progress"
workflow_mode: "<standard|express>"
design_document: "<state_dir>/plans/<design-doc-filename>"
implementation_plan: "<state_dir>/plans/<impl-plan-filename>"
current_phase: 1
total_phases: <integer from impl plan>
execution_mode: null
execution_backend: null
task_complexity: null

token_usage:
  total_input: 0
  total_output: 0
  total_cached: 0
  by_agent: {}

phases:
  - id: 1
    name: "<phase name from impl plan>"
    status: "pending"
    agents: []
    parallel: false
    started: null
    completed: null
    blocked_by: []
    files_created: []
    files_modified: []
    files_deleted: []
    downstream_context:
      key_interfaces_introduced: []
      patterns_established: []
      integration_points: []
      assumptions: []
      warnings: []
    errors: []
    retry_count: 0
---

# <Topic> Orchestration Log

Include task_complexity (from design document frontmatter) in the session state. Place after execution_backend, before token_usage. Default: null.

State Update Protocol

Update Triggers

Update session state on every meaningful state change:

• Phase status transitions
• File manifest changes
• Downstream context extraction from completed phases
• Error occurrences
• Token usage increments
• Phase completion or failure

Update Rules

1. Timestamp: Update updated field on every state change
2. Phase Status: Transition phase status following valid transitions:
   • pending -> in_progress
   • in_progress -> completed
   • in_progress -> failed
   • failed -> in_progress (retry)
   • pending -> skipped (user decision only)
3. Current Phase: Update current_phase to the ID of the currently executing phase
4. File Manifest: Append to files_created, files_modified, or files_deleted as subagents report changes
5. Downstream Context: Persist parsed Handoff Report Part 2 fields into phase downstream_context
6. Token Usage: Aggregate token counts from subagent responses into both total_* and by_agent sections
7. Error Recording: Append to phase errors array with complete metadata

Error Recording Format

errors:
  - agent: "<agent-name>"
    timestamp: "<ISO 8601>"
    type: "<validation|timeout|file_conflict|runtime|dependency>"
    message: "<full error description>"
    resolution: "<what was done to resolve, or 'pending'>"
    resolved: false

Retry Tracking

• Increment retry_count on each retry attempt
• Maximum 2 retries per phase before escalating to user
• Record each retry as a separate error entry with resolution details

Markdown Body Updates

After updating YAML frontmatter, append to the Markdown body:

## Phase N: <Phase Name> <status indicator>

### <Agent Name> Output
[Summary of agent output or full content]

### Files Changed
- Created: [list]
- Modified: [list]

### Downstream Context
- Key Interfaces Introduced: [list]
- Patterns Established: [list]
- Integration Points: [list]
- Assumptions: [list]
- Warnings: [list]

### Validation Result
[Pass/Fail with details]

Status indicators:

• Completed: checkmark
• In Progress: circle
• Failed: cross
• Pending: square
• Skipped: dash

Archive Protocol

When to Archive

Archive session state when:

• All phases are completed successfully AND MAESTRO_AUTO_ARCHIVE is true (default)
• User explicitly requests archival (regardless of MAESTRO_AUTO_ARCHIVE setting)
• User starts a new orchestration (previous session must be archived first, regardless of setting)

When MAESTRO_AUTO_ARCHIVE is false, prompt the user after successful completion: "Session complete. Auto-archive is disabled. Would you like to archive this session?"