maestro-session-manage

Inspect, complete, archive, and govern knowledge candidates for Maestro v3 sessions.

544|67|Updated Mar 17, 2026
One-click install
npx skills add https://github.com/catlog22/Maestro-Flow --skill maestro-session-manage
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: maestro-session-manage
Source: https://github.com/catlog22/Maestro-Flow/tree/main/.codex/skills/maestro-session-manage
Command: npx skills add https://github.com/catlog22/Maestro-Flow --skill maestro-session-manage

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Managing the lifecycle of a Maestro v3 Session manually is error-prone: you must check readiness gates, reconcile knowledge candidates, and issue fenced lifecycle transitions with correct revisions. This Skill provides a single management surface for inspecting session state, promoting knowledge, and performing explicit complete/archive/unarchive transitions that the default Run loop does not handle.

Core Features & Use Cases

  • Session Inspection: Read session status and session resume-view projections to report status, revisions, active runs, open decision gates, and next actions.
  • Lifecycle Transitions: Execute fenced maestro session complete, archive, and unarchive commands with readiness checks, revision verification, and transition receipts.
  • Knowledge Governance: Review, resolve, and promote knowledge candidates through the receipt-aware maestro knowledge review/promote CLI without re-extracting artifacts.
  • Use Case: After a manually driven pipeline finishes with green tests, run the Skill with --complete to verify gates, promote eligible knowledge candidates, complete the session, and activate the next dep-ready session in the DAG.

Quick Start

Ask the assistant to inspect the current Maestro session status and complete it with knowledge promotion once all runs are sealed.

Frequently Asked Questions about maestro-session-manage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I complete a Maestro session manually?

Run the Skill with the --complete flag after verifying the session status is open, no active runs exist, critical gates passed, and no open decision gates remain. The Skill performs a readiness check, reconciles knowledge candidates, then issues the fenced maestro session complete command.

How do I review and promote knowledge candidates in a session?

Use the --knowledge flag to run maestro knowledge review without any lifecycle mutation. Resolve review-required candidates with --resolve and promote eligible ones via maestro knowledge promote, either in bulk with --all or per candidate.

When should I archive a Maestro session instead of leaving it completed?

Archive is an optional freeze for completed or failed sessions when you want to block all further mutations such as new runs or chain changes. A completed session identity stays durable without archiving, and archived sessions can be reopened with --unarchive.

Why does session complete fail with a decision gate error?

The complete transition is blocked when open decision gates exist in the session, returning DECISION_GATE_BLOCKED. Resolve each gate first with maestro run decide <point> --verdict proceed or fix, then retry the completion.

What happens if the orchestration revision conflicts during archive?

An ORCHESTRATION_REVISION_CONFLICT means the session state changed since you read it. Re-read maestro session status to get the fresh revision, generate a new request-id, and retry the fenced transition command.