Maestro-orchestrate session-management

Manages orchestration session state, tracking, and resumption

install

source · Clone the upstream repo

git clone https://github.com/josstei/maestro-orchestrate

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/josstei/maestro-orchestrate "$T" && mkdir -p ~/.claude/skills && cp -r "$T/claude/src/skills/shared/session-management" ~/.claude/skills/josstei-maestro-orchestrate-session-management-384ec8 && rm -rf "$T"

manifest: claude/src/skills/shared/session-management/SKILL.md

source content

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 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 the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks
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 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 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 (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

Resolve state directory from
```
MAESTRO_STATE_DIR
```
Create
```
<state_dir>/state/
```
directory if it does not exist (defense-in-depth fallback — workspace readiness startup check is the primary mechanism)
Verify no existing
```
active-session.md
```
— if one exists, alert the user and offer to archive or resume
Generate session state using the
```
session-state
```
template loaded via
```
get_skill_content
```
Initialize all phases as
```
pending
```
Set overall status to
```
in_progress
```
Set
```
current_phase
```
to 1
Record design document and implementation plan paths
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

Timestamp: Update
```
updated
```
field on every state change
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)
Current Phase: Update
```
current_phase
```
to the ID of the currently executing phase
File Manifest: Append to
```
files_created
```
,
```
files_modified
```
, or
```
files_deleted
```
as subagents report changes
Downstream Context: Persist parsed Handoff Report Part 2 fields into phase
```
downstream_context
```
Token Usage: Aggregate token counts from subagent responses into both
```
total_*
```
and
```
by_agent
```
sections
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

false

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

Archive Steps

archive_session

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

Call
```
archive_session
```
with the session ID. The MCP tool atomically:
- Updates session status to
```
completed
```
- Moves
```
active-session.md
```
  to
```
<state_dir>/state/archive/<session-id>.md
```
- Moves design document to
```
<state_dir>/plans/archive/
```
  (if it exists and is non-null)
- Moves implementation plan to
```
<state_dir>/plans/archive/
```
  (if it exists and is non-null)
Confirm archival to user with summary of what was archived (use the
```
archived_files
```
array in the response)

archive_session

is not available, fall back to manual file operations:

Create
```
<state_dir>/plans/archive/
```
directory if it does not exist
Create
```
<state_dir>/state/archive/
```
directory if it does not exist
MOVE (not copy) design document from
```
<state_dir>/plans/
```
to
```
<state_dir>/plans/archive/
```
— the original MUST be deleted. Use the shell-command tool from runtime context with
```
mv
```
or read+write+delete. Do NOT leave the file in both locations. Skip this step if
design_document
is
null
(Express sessions).
MOVE (not copy) implementation plan from
```
<state_dir>/plans/
```
to
```
<state_dir>/plans/archive/
```
— same: delete the original. Skip this step if
implementation_plan
is
null
(Express sessions).
Update session state
```
status
```
to
```
completed
```
Update
```
updated
```
timestamp

MOVE (not copy)

active-session.md

from

<state_dir>/state/

<state_dir>/state/archive/<session-id>.md

— delete the original.

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
```
<state_dir>/state/
```
No plan files remain in
```
<state_dir>/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

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
```
run_shell_command
```
:
```
node <runtime-script-root>/read-active-session.js
```
(resolves
```
MAESTRO_STATE_DIR
```
internally)
Parse Frontmatter: Extract YAML frontmatter for session metadata
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
Check Errors: Identify unresolved errors from previous execution
Present Summary: Display status summary to user using the resume format defined in the orchestrator instructions
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
Continue Execution: Resume from the first pending or failed phase
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:

Total: Sum across all agents and phases
By Agent: Per-agent totals across all their invocations

Format

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