[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71C72PTKRV481M975R3QDDE":3,"skill-same:01M71C72PTKRV481M975R3QDDE":52},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":26,"linkOnly":27,"markdownContent":28,"markdownBody":29,"frontMatter":30,"refName":31,"commitSha":32,"skillDirectory":33,"forksCount":14,"repositoryHtmlUrl":34,"repositoryHomepageUrl":6,"ownerHtmlUrl":35,"ownerBlogUrl":6,"ownerDescription":36,"updatedAt":37,"install":38,"resources":51},"01M71C72PTKRV481M975R3QDDE","session-management",null,"Manages orchestration session state, tracking, and resumption","yqecea\u002Fgem-swarm","yqecea","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F196189405?v=4","01M71C12KWH5QPTE12J69335KF","Yusuf","01M71C12MFS3BRGNE5SSHB4DY9",1,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fsession-management\u002FSKILL.md",[],[19,20,21,22,23,24,25],"session management","session","management","orchestration","state","tracking","session state","2026-11-10 10:12:30",false,"---\nname: session-management\ndescription: Manages orchestration session state, tracking, and resumption\n---\n\n# Session Management Skill\n\nActivate this skill for all session state operations during Maestro orchestration. This skill defines the protocols for creating, updating, resuming, and archiving orchestration sessions.\n\n## State Access Protocol\n\nWhen MCP state tools are available, prefer them for state operations:\n- **Preferred**: MCP tools (`initialize_workspace`, `create_session`, `update_session`, `transition_phase`, `get_session_status`, `archive_session`) — structured I\u002FO, atomic operations.\n- **Fallback**: `write_file`\u002F`replace` directly on state files — when MCP tools are not in the available tool list.\n- **Legacy**: Shell scripts (`write-state.js`, `read-state.js`) — remain available but are not the recommended path.\n\nDetection: check whether MCP state tools appear in your available tools. If they do, use them. If they do not, use `write_file`\u002F`replace`.\n\n## Hook-Level Session State\n\nMaestro hooks maintain a separate, transient state directory at `\u002Ftmp\u002Fmaestro-hooks\u002F\u003Csession-id>\u002F` that is distinct from orchestration state in `\u003CGEM_SWARM_STATE_DIR>`:\n\n| Concern | Orchestration State | Hook State |\n| --- | --- | --- |\n| Location | `\u003CGEM_SWARM_STATE_DIR>\u002Fstate\u002F` | `\u002Ftmp\u002Fmaestro-hooks\u002F\u003Csession-id>\u002F` (Unix) or `\u003Cos.tmpdir()>\u002Fmaestro-hooks\u002F\u003Csession-id>\u002F` (Windows) |\n| 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 |\n| Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) |\n| Persistence | Survives session restarts (supports `\u002Fmaestro:resume`) | Ephemeral — lost on session end or system reboot |\n| Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks |\n\nThe pre-delegation hook prunes stale hook state directories older than 2 hours to prevent accumulation from abnormal session terminations.\n\nThe orchestrator does not read or write hook-level state directly. It interacts only with `\u003CGEM_SWARM_STATE_DIR>` paths. The two state systems are independent and serve different concerns.\n\n## Session Creation Protocol\n\n### When to Create\nFor 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).\n\n### Session ID Format\n`YYYY-MM-DD-\u003Ctopic-slug>`\n\nWhere:\n- `YYYY-MM-DD` is the orchestration start date\n- `\u003Ctopic-slug>` is a lowercase, hyphenated summary matching the design document topic\n\n### File Location\n`\u003CGEM_SWARM_STATE_DIR>\u002Fstate\u002Factive-session.md`\n\nAll state paths in this skill use `\u003CGEM_SWARM_STATE_DIR>` as their base directory (default: `docs\u002Fmaestro`). In procedural steps, `\u003Cstate_dir>` represents the resolved value of this variable.\n\n### State File Access\n\nBoth `read_file` and `write_file` work on state paths inside `\u003CGEM_SWARM_STATE_DIR>`. The runtime's file-access configuration makes state paths accessible.\n\nUse the runtime's bundled `scripts\u002F` directory for these helper commands so they still work when the extension is installed outside the workspace root.\n\n**Reading state files:**\nUse `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:\n\n`run_shell_command`: `node \u003Cruntime-script-root>\u002Fread-state.js \u003Crelative-path>`\n\n**Writing state files:**\nUse `write_file` directly. When content must be piped from a shell command, use the atomic write script:\n\n`run_shell_command`: `echo '...' | node \u003Cruntime-script-root>\u002Fwrite-state.js \u003Crelative-path>`\n\n**Rules:**\n- The `write-state.js` script writes atomically (temp file + rename) to prevent partial writes\n- Both scripts validate against absolute paths and path traversal\n\n### Initialization Steps\n1. Resolve state directory from `GEM_SWARM_STATE_DIR`\n2. Create `\u003Cstate_dir>\u002Fstate\u002F` directory if it does not exist (defense-in-depth fallback — workspace readiness startup check is the primary mechanism)\n3. Verify no existing `active-session.md` — if one exists, alert the user and offer to archive or resume\n4. Generate session state using the `session-state` template loaded via `get_skill_content`\n5. Initialize all phases as `pending`\n6. Set overall status to `in_progress`\n7. Set `current_phase` to 1\n8. Record design document and implementation plan paths\n9. Initialize empty token_usage, file manifests, downstream_context, and errors sections\n\n### Initial State Template\n\n```yaml\n---\nsession_id: \"\u003CYYYY-MM-DD-topic-slug>\"\ntask: \"\u003Cuser's original task description>\"\ncreated: \"\u003CISO 8601 timestamp>\"\nupdated: \"\u003CISO 8601 timestamp>\"\nstatus: \"in_progress\"\nworkflow_mode: \"\u003Cstandard|express>\"\ndesign_document: \"\u003Cstate_dir>\u002Fplans\u002F\u003Cdesign-doc-filename>\"\nimplementation_plan: \"\u003Cstate_dir>\u002Fplans\u002F\u003Cimpl-plan-filename>\"\ncurrent_phase: 1\ntotal_phases: \u003Cinteger from impl plan>\nexecution_mode: null\nexecution_backend: null\ntask_complexity: null\n\ntoken_usage:\n  total_input: 0\n  total_output: 0\n  total_cached: 0\n  by_agent: {}\n\nphases:\n  - id: 1\n    name: \"\u003Cphase name from impl plan>\"\n    status: \"pending\"\n    agents: []\n    parallel: false\n    started: null\n    completed: null\n    blocked_by: []\n    files_created: []\n    files_modified: []\n    files_deleted: []\n    downstream_context:\n      key_interfaces_introduced: []\n      patterns_established: []\n      integration_points: []\n      assumptions: []\n      warnings: []\n    errors: []\n    retry_count: 0\n---\n\n# \u003CTopic> Orchestration Log\n```\n\nInclude `task_complexity` (from design document frontmatter) in the session state. Place after `execution_backend`, before `token_usage`. Default: `null`.\n\n## State Update Protocol\n\n### Update Triggers\nUpdate session state on every meaningful state change:\n- Phase status transitions\n- File manifest changes\n- Downstream context extraction from completed phases\n- Error occurrences\n- Token usage increments\n- Phase completion or failure\n\n### Update Rules\n\n1. **Timestamp**: Update `updated` field on every state change\n2. **Phase Status**: Transition phase status following valid transitions:\n   - `pending` -> `in_progress`\n   - `in_progress` -> `completed`\n   - `in_progress` -> `failed`\n   - `failed` -> `in_progress` (retry)\n   - `pending` -> `skipped` (user decision only)\n3. **Current Phase**: Update `current_phase` to the ID of the currently executing phase\n4. **File Manifest**: Append to `files_created`, `files_modified`, or `files_deleted` as subagents report changes\n5. **Downstream Context**: Persist parsed Handoff Report Part 2 fields into phase `downstream_context`\n6. **Token Usage**: Aggregate token counts from subagent responses into both `total_*` and `by_agent` sections\n7. **Error Recording**: Append to phase `errors` array with complete metadata\n\n### Error Recording Format\n\n```yaml\nerrors:\n  - agent: \"\u003Cagent-name>\"\n    timestamp: \"\u003CISO 8601>\"\n    type: \"\u003Cvalidation|timeout|file_conflict|runtime|dependency>\"\n    message: \"\u003Cfull error description>\"\n    resolution: \"\u003Cwhat was done to resolve, or 'pending'>\"\n    resolved: false\n```\n\n### Retry Tracking\n- Increment `retry_count` on each retry attempt\n- Maximum 2 retries per phase before escalating to user\n- Record each retry as a separate error entry with resolution details\n\n### Markdown Body Updates\nAfter updating YAML frontmatter, append to the Markdown body:\n\n```markdown\n## Phase N: \u003CPhase Name> \u003Cstatus indicator>\n\n### \u003CAgent Name> Output\n[Summary of agent output or full content]\n\n### Files Changed\n- Created: [list]\n- Modified: [list]\n\n### Downstream Context\n- Key Interfaces Introduced: [list]\n- Patterns Established: [list]\n- Integration Points: [list]\n- Assumptions: [list]\n- Warnings: [list]\n\n### Validation Result\n[Pass\u002FFail with details]\n```\n\nStatus indicators:\n- Completed: checkmark\n- In Progress: circle\n- Failed: cross\n- Pending: square\n- Skipped: dash\n\n## Archive Protocol\n\n### When to Archive\nArchive session state when:\n- All phases are completed successfully AND `GEM_SWARM_AUTO_ARCHIVE` is `true` (default)\n- User explicitly requests archival (regardless of `GEM_SWARM_AUTO_ARCHIVE` setting)\n- User starts a new orchestration (previous session must be archived first, regardless of setting)\n\nWhen `GEM_SWARM_AUTO_ARCHIVE` is `false`, prompt the user after successful completion: \"Session complete. Auto-archive is disabled. Would you like to archive this session?\"\n\n### Archive Steps\nIf `archive_session` appears in your available tools, use it — a single call handles all archival:\n\n1. Call `archive_session` with the session ID. The MCP tool atomically:\n   - Updates session status to `completed`\n   - Moves `active-session.md` to `\u003Cstate_dir>\u002Fstate\u002Farchive\u002F\u003Csession-id>.md`\n   - Moves design document to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` (if it exists and is non-null)\n   - Moves implementation plan to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` (if it exists and is non-null)\n2. Confirm archival to user with summary of what was archived (use the `archived_files` array in the response)\n\nIf `archive_session` is not available, fall back to manual file operations:\n1. Create `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` directory if it does not exist\n2. Create `\u003Cstate_dir>\u002Fstate\u002Farchive\u002F` directory if it does not exist\n3. **MOVE** (not copy) design document from `\u003Cstate_dir>\u002Fplans\u002F` to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` — 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).**\n4. **MOVE** (not copy) implementation plan from `\u003Cstate_dir>\u002Fplans\u002F` to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` — same: delete the original. **Skip this step if `implementation_plan` is `null` (Express sessions).**\n5. Update session state `status` to `completed`\n6. Update `updated` timestamp\n7. **MOVE** (not copy) `active-session.md` from `\u003Cstate_dir>\u002Fstate\u002F` to `\u003Cstate_dir>\u002Fstate\u002Farchive\u002F\u003Csession-id>.md` — delete the original.\n8. Confirm archival to user with summary of what was archived\n\n### Archive Verification\nAfter archival, verify ALL of the following (archive is incomplete if any check fails):\n- No `active-session.md` exists in `\u003Cstate_dir>\u002Fstate\u002F`\n- No plan files remain in `\u003Cstate_dir>\u002Fplans\u002F` (only the `archive\u002F` subdirectory should be present)\n- Archived files are readable at their new locations in `archive\u002F`\n- If files still exist in the original locations, delete them now — the archive step used copy instead of move\n\n## Resume Protocol\n\n### When to Resume\nResume is triggered by the `\u002Fmaestro:resume` command or when `\u002Fmaestro:orchestrate` detects an existing active session.\n\n### Resume Steps\n\n1. **Read State**: If session state was already injected into the prompt (e.g., via `\u002Fmaestro: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 \u003Cruntime-script-root>\u002Fread-active-session.js` (resolves `GEM_SWARM_STATE_DIR` internally)\n2. **Parse Frontmatter**: Extract YAML frontmatter for session metadata\n3. **Identify Position**: Determine:\n   - Last completed phase (highest ID with `status: completed`)\n   - Current active phase (first phase with `status: in_progress` or `pending`)\n   - Any failed phases with unresolved errors\n4. **Check Errors**: Identify unresolved errors from previous execution\n5. **Present Summary**: Display status summary to user using the resume format defined in the orchestrator instructions\n6. **Handle Errors**: If unresolved errors exist:\n   - Present each error with context\n   - Offer options: retry, skip, abort, or adjust parameters\n   - Wait for user guidance before proceeding\n7. **Continue Execution**: Resume from the first pending or failed phase\n8. **Update State**: Mark resumed phase as `in_progress` and update timestamps\n\n### Express Resume Branch\n\nWhen 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:\n\n- If phase status is `pending`: re-generate and present the structured brief for approval. On approval, proceed to delegation.\n- 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.\n- If phase status is `completed` but session status is `in_progress`: code review or archival was interrupted. Run the code review step, then archive.\n\nExpress sessions have a single phase. The phase status combined with the `agents` array contents determines the resume position.\n\n### Conflict Detection\nWhen resuming, check for potential conflicts:\n- Files that were partially modified (phase started but not completed)\n- External modifications to files in the manifest since last session\n- Changes to the implementation plan since last execution\n\nReport any detected conflicts to the user before proceeding.\n\n## Token Usage Tracking\n\n### Collection\nAfter each subagent invocation, record:\n- Input tokens consumed\n- Output tokens generated\n- Cached tokens used (if available)\n\n### Aggregation\nMaintain two levels of aggregation:\n1. **Total**: Sum across all agents and phases\n2. **By Agent**: Per-agent totals across all their invocations\n\n### Format\n\n```yaml\ntoken_usage:\n  total_input: 15000\n  total_output: 8000\n  total_cached: 3000\n  by_agent:\n    coder:\n      input: 8000\n      output: 4000\n      cached: 2000\n    tester:\n      input: 7000\n      output: 4000\n      cached: 1000\n```\n","# Session Management Skill\n\nActivate this skill for all session state operations during Maestro orchestration. This skill defines the protocols for creating, updating, resuming, and archiving orchestration sessions.\n\n## State Access Protocol\n\nWhen MCP state tools are available, prefer them for state operations:\n- **Preferred**: MCP tools (`initialize_workspace`, `create_session`, `update_session`, `transition_phase`, `get_session_status`, `archive_session`) — structured I\u002FO, atomic operations.\n- **Fallback**: `write_file`\u002F`replace` directly on state files — when MCP tools are not in the available tool list.\n- **Legacy**: Shell scripts (`write-state.js`, `read-state.js`) — remain available but are not the recommended path.\n\nDetection: check whether MCP state tools appear in your available tools. If they do, use them. If they do not, use `write_file`\u002F`replace`.\n\n## Hook-Level Session State\n\nMaestro hooks maintain a separate, transient state directory at `\u002Ftmp\u002Fmaestro-hooks\u002F\u003Csession-id>\u002F` that is distinct from orchestration state in `\u003CGEM_SWARM_STATE_DIR>`:\n\n| Concern | Orchestration State | Hook State |\n| --- | --- | --- |\n| Location | `\u003CGEM_SWARM_STATE_DIR>\u002Fstate\u002F` | `\u002Ftmp\u002Fmaestro-hooks\u002F\u003Csession-id>\u002F` (Unix) or `\u003Cos.tmpdir()>\u002Fmaestro-hooks\u002F\u003Csession-id>\u002F` (Windows) |\n| 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 |\n| Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) |\n| Persistence | Survives session restarts (supports `\u002Fmaestro:resume`) | Ephemeral — lost on session end or system reboot |\n| Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks |\n\nThe pre-delegation hook prunes stale hook state directories older than 2 hours to prevent accumulation from abnormal session terminations.\n\nThe orchestrator does not read or write hook-level state directly. It interacts only with `\u003CGEM_SWARM_STATE_DIR>` paths. The two state systems are independent and serve different concerns.\n\n## Session Creation Protocol\n\n### When to Create\nFor 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).\n\n### Session ID Format\n`YYYY-MM-DD-\u003Ctopic-slug>`\n\nWhere:\n- `YYYY-MM-DD` is the orchestration start date\n- `\u003Ctopic-slug>` is a lowercase, hyphenated summary matching the design document topic\n\n### File Location\n`\u003CGEM_SWARM_STATE_DIR>\u002Fstate\u002Factive-session.md`\n\nAll state paths in this skill use `\u003CGEM_SWARM_STATE_DIR>` as their base directory (default: `docs\u002Fmaestro`). In procedural steps, `\u003Cstate_dir>` represents the resolved value of this variable.\n\n### State File Access\n\nBoth `read_file` and `write_file` work on state paths inside `\u003CGEM_SWARM_STATE_DIR>`. The runtime's file-access configuration makes state paths accessible.\n\nUse the runtime's bundled `scripts\u002F` directory for these helper commands so they still work when the extension is installed outside the workspace root.\n\n**Reading state files:**\nUse `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:\n\n`run_shell_command`: `node \u003Cruntime-script-root>\u002Fread-state.js \u003Crelative-path>`\n\n**Writing state files:**\nUse `write_file` directly. When content must be piped from a shell command, use the atomic write script:\n\n`run_shell_command`: `echo '...' | node \u003Cruntime-script-root>\u002Fwrite-state.js \u003Crelative-path>`\n\n**Rules:**\n- The `write-state.js` script writes atomically (temp file + rename) to prevent partial writes\n- Both scripts validate against absolute paths and path traversal\n\n### Initialization Steps\n1. Resolve state directory from `GEM_SWARM_STATE_DIR`\n2. Create `\u003Cstate_dir>\u002Fstate\u002F` directory if it does not exist (defense-in-depth fallback — workspace readiness startup check is the primary mechanism)\n3. Verify no existing `active-session.md` — if one exists, alert the user and offer to archive or resume\n4. Generate session state using the `session-state` template loaded via `get_skill_content`\n5. Initialize all phases as `pending`\n6. Set overall status to `in_progress`\n7. Set `current_phase` to 1\n8. Record design document and implementation plan paths\n9. Initialize empty token_usage, file manifests, downstream_context, and errors sections\n\n### Initial State Template\n\n```yaml\n---\nsession_id: \"\u003CYYYY-MM-DD-topic-slug>\"\ntask: \"\u003Cuser's original task description>\"\ncreated: \"\u003CISO 8601 timestamp>\"\nupdated: \"\u003CISO 8601 timestamp>\"\nstatus: \"in_progress\"\nworkflow_mode: \"\u003Cstandard|express>\"\ndesign_document: \"\u003Cstate_dir>\u002Fplans\u002F\u003Cdesign-doc-filename>\"\nimplementation_plan: \"\u003Cstate_dir>\u002Fplans\u002F\u003Cimpl-plan-filename>\"\ncurrent_phase: 1\ntotal_phases: \u003Cinteger from impl plan>\nexecution_mode: null\nexecution_backend: null\ntask_complexity: null\n\ntoken_usage:\n  total_input: 0\n  total_output: 0\n  total_cached: 0\n  by_agent: {}\n\nphases:\n  - id: 1\n    name: \"\u003Cphase name from impl plan>\"\n    status: \"pending\"\n    agents: []\n    parallel: false\n    started: null\n    completed: null\n    blocked_by: []\n    files_created: []\n    files_modified: []\n    files_deleted: []\n    downstream_context:\n      key_interfaces_introduced: []\n      patterns_established: []\n      integration_points: []\n      assumptions: []\n      warnings: []\n    errors: []\n    retry_count: 0\n---\n\n# \u003CTopic> Orchestration Log\n```\n\nInclude `task_complexity` (from design document frontmatter) in the session state. Place after `execution_backend`, before `token_usage`. Default: `null`.\n\n## State Update Protocol\n\n### Update Triggers\nUpdate session state on every meaningful state change:\n- Phase status transitions\n- File manifest changes\n- Downstream context extraction from completed phases\n- Error occurrences\n- Token usage increments\n- Phase completion or failure\n\n### Update Rules\n\n1. **Timestamp**: Update `updated` field on every state change\n2. **Phase Status**: Transition phase status following valid transitions:\n   - `pending` -> `in_progress`\n   - `in_progress` -> `completed`\n   - `in_progress` -> `failed`\n   - `failed` -> `in_progress` (retry)\n   - `pending` -> `skipped` (user decision only)\n3. **Current Phase**: Update `current_phase` to the ID of the currently executing phase\n4. **File Manifest**: Append to `files_created`, `files_modified`, or `files_deleted` as subagents report changes\n5. **Downstream Context**: Persist parsed Handoff Report Part 2 fields into phase `downstream_context`\n6. **Token Usage**: Aggregate token counts from subagent responses into both `total_*` and `by_agent` sections\n7. **Error Recording**: Append to phase `errors` array with complete metadata\n\n### Error Recording Format\n\n```yaml\nerrors:\n  - agent: \"\u003Cagent-name>\"\n    timestamp: \"\u003CISO 8601>\"\n    type: \"\u003Cvalidation|timeout|file_conflict|runtime|dependency>\"\n    message: \"\u003Cfull error description>\"\n    resolution: \"\u003Cwhat was done to resolve, or 'pending'>\"\n    resolved: false\n```\n\n### Retry Tracking\n- Increment `retry_count` on each retry attempt\n- Maximum 2 retries per phase before escalating to user\n- Record each retry as a separate error entry with resolution details\n\n### Markdown Body Updates\nAfter updating YAML frontmatter, append to the Markdown body:\n\n```markdown\n## Phase N: \u003CPhase Name> \u003Cstatus indicator>\n\n### \u003CAgent Name> Output\n[Summary of agent output or full content]\n\n### Files Changed\n- Created: [list]\n- Modified: [list]\n\n### Downstream Context\n- Key Interfaces Introduced: [list]\n- Patterns Established: [list]\n- Integration Points: [list]\n- Assumptions: [list]\n- Warnings: [list]\n\n### Validation Result\n[Pass\u002FFail with details]\n```\n\nStatus indicators:\n- Completed: checkmark\n- In Progress: circle\n- Failed: cross\n- Pending: square\n- Skipped: dash\n\n## Archive Protocol\n\n### When to Archive\nArchive session state when:\n- All phases are completed successfully AND `GEM_SWARM_AUTO_ARCHIVE` is `true` (default)\n- User explicitly requests archival (regardless of `GEM_SWARM_AUTO_ARCHIVE` setting)\n- User starts a new orchestration (previous session must be archived first, regardless of setting)\n\nWhen `GEM_SWARM_AUTO_ARCHIVE` is `false`, prompt the user after successful completion: \"Session complete. Auto-archive is disabled. Would you like to archive this session?\"\n\n### Archive Steps\nIf `archive_session` appears in your available tools, use it — a single call handles all archival:\n\n1. Call `archive_session` with the session ID. The MCP tool atomically:\n   - Updates session status to `completed`\n   - Moves `active-session.md` to `\u003Cstate_dir>\u002Fstate\u002Farchive\u002F\u003Csession-id>.md`\n   - Moves design document to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` (if it exists and is non-null)\n   - Moves implementation plan to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` (if it exists and is non-null)\n2. Confirm archival to user with summary of what was archived (use the `archived_files` array in the response)\n\nIf `archive_session` is not available, fall back to manual file operations:\n1. Create `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` directory if it does not exist\n2. Create `\u003Cstate_dir>\u002Fstate\u002Farchive\u002F` directory if it does not exist\n3. **MOVE** (not copy) design document from `\u003Cstate_dir>\u002Fplans\u002F` to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` — 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).**\n4. **MOVE** (not copy) implementation plan from `\u003Cstate_dir>\u002Fplans\u002F` to `\u003Cstate_dir>\u002Fplans\u002Farchive\u002F` — same: delete the original. **Skip this step if `implementation_plan` is `null` (Express sessions).**\n5. Update session state `status` to `completed`\n6. Update `updated` timestamp\n7. **MOVE** (not copy) `active-session.md` from `\u003Cstate_dir>\u002Fstate\u002F` to `\u003Cstate_dir>\u002Fstate\u002Farchive\u002F\u003Csession-id>.md` — delete the original.\n8. Confirm archival to user with summary of what was archived\n\n### Archive Verification\nAfter archival, verify ALL of the following (archive is incomplete if any check fails):\n- No `active-session.md` exists in `\u003Cstate_dir>\u002Fstate\u002F`\n- No plan files remain in `\u003Cstate_dir>\u002Fplans\u002F` (only the `archive\u002F` subdirectory should be present)\n- Archived files are readable at their new locations in `archive\u002F`\n- If files still exist in the original locations, delete them now — the archive step used copy instead of move\n\n## Resume Protocol\n\n### When to Resume\nResume is triggered by the `\u002Fmaestro:resume` command or when `\u002Fmaestro:orchestrate` detects an existing active session.\n\n### Resume Steps\n\n1. **Read State**: If session state was already injected into the prompt (e.g., via `\u002Fmaestro: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 \u003Cruntime-script-root>\u002Fread-active-session.js` (resolves `GEM_SWARM_STATE_DIR` internally)\n2. **Parse Frontmatter**: Extract YAML frontmatter for session metadata\n3. **Identify Position**: Determine:\n   - Last completed phase (highest ID with `status: completed`)\n   - Current active phase (first phase with `status: in_progress` or `pending`)\n   - Any failed phases with unresolved errors\n4. **Check Errors**: Identify unresolved errors from previous execution\n5. **Present Summary**: Display status summary to user using the resume format defined in the orchestrator instructions\n6. **Handle Errors**: If unresolved errors exist:\n   - Present each error with context\n   - Offer options: retry, skip, abort, or adjust parameters\n   - Wait for user guidance before proceeding\n7. **Continue Execution**: Resume from the first pending or failed phase\n8. **Update State**: Mark resumed phase as `in_progress` and update timestamps\n\n### Express Resume Branch\n\nWhen 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:\n\n- If phase status is `pending`: re-generate and present the structured brief for approval. On approval, proceed to delegation.\n- 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.\n- If phase status is `completed` but session status is `in_progress`: code review or archival was interrupted. Run the code review step, then archive.\n\nExpress sessions have a single phase. The phase status combined with the `agents` array contents determines the resume position.\n\n### Conflict Detection\nWhen resuming, check for potential conflicts:\n- Files that were partially modified (phase started but not completed)\n- External modifications to files in the manifest since last session\n- Changes to the implementation plan since last execution\n\nReport any detected conflicts to the user before proceeding.\n\n## Token Usage Tracking\n\n### Collection\nAfter each subagent invocation, record:\n- Input tokens consumed\n- Output tokens generated\n- Cached tokens used (if available)\n\n### Aggregation\nMaintain two levels of aggregation:\n1. **Total**: Sum across all agents and phases\n2. **By Agent**: Per-agent totals across all their invocations\n\n### Format\n\n```yaml\ntoken_usage:\n  total_input: 15000\n  total_output: 8000\n  total_cached: 3000\n  by_agent:\n    coder:\n      input: 8000\n      output: 4000\n      cached: 2000\n    tester:\n      input: 7000\n      output: 4000\n      cached: 1000\n```\n",{"name":5,"description":7},"main","923c514d4d5e15bbfd65ec7eaf949a997679aa3e","src\u002Fskills\u002Fshared\u002Fsession-management","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm","https:\u002F\u002Fgithub.com\u002Fyqecea","15 y.o Data Science,Student","2026-04-26 20:00:27",{"source":8,"skillName":5,"commands":39,"prompt":49,"zipAvailable":50},[40,43,46],{"tool":41,"command":42},"npx","npx skills add yqecea\u002Fgem-swarm --skill session-management",{"tool":44,"command":45},"bunx","bunx skills add yqecea\u002Fgem-swarm --skill session-management",{"tool":47,"command":48},"pnpm","pnpm dlx skills add yqecea\u002Fgem-swarm --skill session-management","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fsession-management\u002FSKILL.md",true,[],[53,67,78,90,115,132],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":26},"01M71C74XVPP23ST10E8MYJZA0","validation","Cross-cutting validation methodology for verifying phase outputs and project integrity","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fvalidation\u002FSKILL.md",[],[55,60,61,62,63,64,65,66],"integrity","methodology","phase","outputs","project","for","validation methodology",{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":26},"01M71C6ZY1EGM4SGVYT4B2HHD7","implementation-planning","Generates detailed implementation plans from finalized designs","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fimplementation-planning\u002FSKILL.md",[],[74,75,76,77],"planning","implementation","implementation planning","plans",{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":26},"01M71C6XQVGMDFJ50BP5SBDS76","execution","Phase execution methodology for orchestration workflows with error handling and completion protocols","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fexecution\u002FSKILL.md",[],[80,22,62,85,65,86,87,61,88,89],"protocols","error handling","with","workflows","error",{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":106,"publishedAt":26},"01M71C6VY8APWMNK1XEJ3WP7A2","design-dialogue","Guides structured design conversations for complex engineering tasks","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fdesign-dialogue\u002FSKILL.md",[96,101],{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":102,"categoryName":103,"taxonomyType":104,"taxonomyTypeDesc":105},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[107,108,109,110,65,111,112,113,114],"design dialogue","design","dialogue","conversations","tasks","guides","engineering","structured",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":127,"publishedAt":26},"01M71C6R4RJWG3S2R26778TPD8","delegation","Agent delegation best practices for constructing effective subagent prompts with proper scoping","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fdelegation\u002FSKILL.md",[121,124],{"categoryNo":122,"categoryName":123,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":125,"categoryName":126,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000023","Skill与智能体开发",[117,128,129,130,65,87,131],"best practices","subagent","scoping","prompts",{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":144,"publishedAt":26},"01M71C6PFKHSVBPCES0VKGSD0Y","code-review","Standalone code review methodology for structured, severity-classified code assessment","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fcode-review\u002FSKILL.md",[138,141],{"categoryNo":139,"categoryName":140,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":142,"categoryName":143,"taxonomyType":104,"taxonomyTypeDesc":105},"01JBSEEDCAT000000000000030","开发工程师",[145,146,147,148,149,65,150,61,114],"code","code review","review","standalone","severity","assessment"]