git:20260404.90bdf6c to git:20260410.f5a5165

1 added, 308 removed. Audit A to A.

---

name: session-management

description: Manages orchestration session state, tracking, and resumption

user-invocable: false

---

- # 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`/`Edit` 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`/`Edit`.

- ## Hook-Level Session State

- Maestro hooks maintain a separate, transient state directory at `/tmp/maestro-hooks/<session-id>/` that is distinct from orchestration state in `<MAESTRO_STATE_DIR>`:

- | Concern | Orchestration State | Hook State |

- | --- | --- | --- |

- | Location | `<MAESTRO_STATE_DIR>/state/` | `/tmp/maestro-hooks/<session-id>/` (Unix) or `<os.tmpdir()>/maestro-hooks/<session-id>/` (Windows) |

- | Lifecycle | Created in Phase 2, archived in Phase 4 | Directory created by `hooks system (SessionStart)` when an active session exists; active-agent file written by `hooks system (PreToolUse)` and cleared by `orchestrator inline validation (no hook — see SKIP_EVENTS_CLAUDE)`; stale directories pruned by both `hooks system (SessionStart)` and `hooks system (PreToolUse)` |

- | Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) |

- | Persistence | Survives session restarts (supports `/maestro:resume`) | Ephemeral — lost on session end or system reboot |

- | Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks |

- The `hooks system (PreToolUse)` 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 when beginning Phase 2 (Team Assembly & Planning) of orchestration, after the design document has been approved. 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. In procedural steps, `docs/maestro` represents the resolved value of this variable.

- ### State File Access

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

- Use `${CLAUDE_PLUGIN_ROOT}/scripts/` for script locations so these commands work even when the extension is installed outside the workspace root.

- **Reading state files:**

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

- `Bash`: `node ${CLAUDE_PLUGIN_ROOT}/scripts/read-state.js <relative-path>`

- **Writing state files:**

- Use `Write` directly. When content must be piped from a shell command, use the atomic write script:

- `Bash`: `echo '...' | node ${CLAUDE_PLUGIN_ROOT}/scripts/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 `docs/maestro/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 template from `templates/session-state.md`

- 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

- ```yaml

- ---

- 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: "docs/maestro/plans/<design-doc-filename>"

- implementation_plan: "docs/maestro/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

- ```yaml

- 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:

- ```markdown

- ## 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?"

- ### Archive Steps

- If `archive_session` appears in your available tools, use it — a single call handles all archival:

- 1. Call `archive_session` with the session ID. The MCP tool atomically:

- - Updates session status to `completed`

- - Moves `active-session.md` to `docs/maestro/state/archive/<session-id>.md`

- - Moves design document to `docs/maestro/plans/archive/` (if it exists and is non-null)

- - Moves implementation plan to `docs/maestro/plans/archive/` (if it exists and is non-null)

- 2. Confirm archival to user with summary of what was archived (use the `archived_files` array in the response)

- If `archive_session` is not available, fall back to manual file operations:

- 1. Create `docs/maestro/plans/archive/` directory if it does not exist

- 2. Create `docs/maestro/state/archive/` directory if it does not exist

- 3. **MOVE** (not copy) design document from `docs/maestro/plans/` to `docs/maestro/plans/archive/` — the original MUST be deleted. Use `Bash` with `mv` or read+write+delete. Do NOT leave the file in both locations. **Skip this step if `design_document` is `null` (Express sessions).**

- 4. **MOVE** (not copy) implementation plan from `docs/maestro/plans/` to `docs/maestro/plans/archive/` — same: delete the original. **Skip this step if `implementation_plan` is `null` (Express sessions).**

- 5. Update session state `status` to `completed`

- 6. Update `updated` timestamp

- 7. **MOVE** (not copy) `active-session.md` from `docs/maestro/state/` to `docs/maestro/state/archive/<session-id>.md` — delete the original.

- 8. Confirm archival to user with summary of what was archived

- ### Archive Verification

- After archival, verify ALL of the following (archive is incomplete if any check fails):

- - No `active-session.md` exists in `docs/maestro/state/`

- - No plan files remain in `docs/maestro/plans/` (only the `archive/` subdirectory should be present)

- - Archived files are readable at their new locations in `archive/`

- - If files still exist in the original locations, delete them now — the archive step used copy instead of move

- ## Resume Protocol

- ### When to Resume

- Resume is triggered by the `/maestro:resume` command or when `/maestro:orchestrate` detects an existing active session.

- ### Resume Steps

- 1. **Read State**: If session state was already injected into the prompt (e.g., via `/maestro:resume`), use that injected content instead of calling `get_session_status`. Otherwise, if `get_session_status` appears in your available tools, call it to read the active session. Otherwise, read state via `Bash`: `node ${CLAUDE_PLUGIN_ROOT}/scripts/read-active-session.js` (resolves `MAESTRO_STATE_DIR` internally)

- 2. **Parse Frontmatter**: Extract YAML frontmatter for session metadata

- 3. **Identify Position**: Determine:

- - Last completed phase (highest ID with `status: completed`)

- - Current active phase (first phase with `status: in_progress` or `pending`)

- - Any failed phases with unresolved errors

- 4. **Check Errors**: Identify unresolved errors from previous execution

- 5. **Present Summary**: Display status summary to user using the resume format defined in the orchestrator instructions

- 6. **Handle Errors**: If unresolved errors exist:

- - Present each error with context

- - Offer options: retry, skip, abort, or adjust parameters

- - Wait for user guidance before proceeding

- 7. **Continue Execution**: Resume from the first pending or failed phase

- 8. **Update State**: Mark resumed phase as `in_progress` and update timestamps

- ### Express Resume Branch

- When resuming a session with `workflow_mode: "express"` (read from session state via `get_session_status`), follow the Express workflow's resume protocol instead of the standard resume steps above:

- - If phase status is `pending`: re-generate and present the structured brief for approval. On approval, proceed to delegation.

- - If phase status is `in_progress`: the implementing agent was interrupted. Re-delegate with the same scope. Use the `agents` array to identify which agent was running.

- - If phase status is `completed` but session status is `in_progress`: code review or archival was interrupted. Run the code review step, then archive.

- Express sessions have a single phase. The phase status combined with the `agents` array contents determines the resume position.

- ### Conflict Detection

- When resuming, check for potential conflicts:

- - Files that were partially modified (phase started but not completed)

- - External modifications to files in the manifest since last session

- - Changes to the implementation plan since last execution

- Report any detected conflicts to the user before proceeding.

- ## Token Usage Tracking

- ### Collection

- After each subagent invocation, record:

- - Input tokens consumed

- - Output tokens generated

- - Cached tokens used (if available)

- ### Aggregation

- Maintain two levels of aggregation:

- 1. **Total**: Sum across all agents and phases

- 2. **By Agent**: Per-agent totals across all their invocations

- ### Format

- ```yaml

- token_usage:

- total_input: 15000

- total_output: 8000

- total_cached: 3000

- by_agent:

- coder:

- input: 8000

- output: 4000

- cached: 2000

- tester:

- input: 7000

- output: 4000

- cached: 1000

- ```

+ Methodology loaded via MCP. Call `get_skill_content(resources: ["session-management"])`.