メニュー
Manage a v3 Session — inspect status/resume-view, review knowledge candidates, complete, archive/unarchive
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/catlog22/maestro-flow --skill maestro-session-manageコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Quick execution for small tasks — minimal run lifecycle (start + done) with evidence recording. Full LLM capability, scoped to mechanically clear tasks.
Create or sync session worktree for parallel dev
Manage editing boundary restrictions
SKILL.md を表示中
| name | maestro-session-manage |
| disable-model-invocation | true |
| description | Manage a v3 Session — inspect status/resume-view, review knowledge candidates, complete, archive/unarchive |
| argument-hint | [--session <session_id>] [--complete|--archive|--unarchive|--knowledge] [-y] [--skip-knowledge] |
| allowed-tools | ["Bash","Edit","Glob","Grep","Read","Write","followup_task","interrupt_agent","list_agents","request_user_input","send_message","spawn_agent","spawn_agents_on_csv","wait_agent"] |
| session-mode | run |
| contract | {"discovery":"self-described","consumes":[],"produces":[]} |
| version | 0.5.83 |
<required_reading>
@/.maestro/workflows/run-mode.md
@/.maestro/workflows/codex-run-mode.md
</required_reading>
If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing any step.
Manage the lifecycle of a v3 Session (`session/3.0`) through its read-only projections, knowledge governance, and explicit lifecycle transitions.Session completion (maestro session complete) is part of the default Run loop — Ralph S_DONE, the orchestrator run loop, and Companion all execute it when the chain turns terminal. This command is the management surface: inspection, knowledge candidate review/promotion, and the explicit transitions the default loop does not perform (--complete for manual pipelines, --archive/--unarchive for optional freezing).
Run completion already stages accepted decisions, locked constraints, and explicit maestro knowledge stage entries. This command reviews those receipts; it does not re-extract the same artifacts or write project knowledge through a second path.
Actions (first match wins; default = inspect):
| Flag | Effect |
|---|---|
| (none) | Inspect: session status + session resume-view projection |
--complete | Readiness check → knowledge reconciliation → fenced maestro session complete → DAG progression |
--archive | Fenced maestro session archive (only from completed/failed; optional freeze) |
--unarchive | Fenced maestro session unarchive (only from archived; returns to open) |
--knowledge | Knowledge review/promotion only — no lifecycle mutation |
Shared flags:
| Flag | Effect | Default |
|---|---|---|
--session <id> | Target session (slug or full ID) |
active_session_id |
-y / --yes | Auto mode — skip confirmations | false |
--skip-knowledge | With --complete: leave candidate backlog pending | false |
<v3_lifecycle_reference>
open ──complete──> completed ──archive──> archived ──unarchive──> open
│
└──fail──> failed ──archive──> archived
Permissions: open = all mutations; completed/failed/archived = none.
--complete requires: no running Run, every chain step completed/skipped with evidence, no open decision gate (escalated gates pass as recorded concerns).--archive is optional: a completed Session identity stays durable either way; archived Sessions cannot host new Runs until --unarchive.run-response/1.2 envelope with an immutable transition receipt; never edit runtime-owned protocol JSON.
</v3_lifecycle_reference>--session flag or active_session_idmaestro session status --session {session_id} --json — capture status, orchestration_revision, activity_revision, active_run_idsmaestro session status --session {session_id} --json and maestro session resume-view --session {session_id} --jsonopenDecisions from the ResumeMap), pending publications, and nextActionsmaestro run decide; active runs → let the Run loop finish; completed → offer --archive; archived → offer --unarchive; open with terminal chain → offer --complete--complete) — manual-pipeline terminal stepNote: maestro-next suggests --complete when 'Tests green + active session'. Orchestrated flows (Ralph/orchestrator/Companion) complete the Session themselves; use this action only when driving the pipeline manually.
2a. Readiness check
open (a completed/archived Session needs no completion; archived requires --unarchive first)active_run_ids empty; all runs sealed)session status → decisions[]; open gates block session complete with DECISION_GATE_BLOCKED). If open gates exist → run maestro run decide <point> --verdict proceed|fix firstreview step first")2b. Knowledge reconciliation (skip to 2c with --skip-knowledge)
maestro knowledge review {session_id} --json. Treat its Run ledgers, reconciliation policies, diversified matches, and candidate IDs as authoritative; do not rescan outputs to recreate candidates. Use --refresh only when the review reports missing or stale source receiptscited, validated, and contradicted are explicit Run relationsreview_required candidates cannot be promoted--skip-knowledge, report the pending/promoting/review-required/suppressed counts and continue. The backlog and reconciliation receipts remain durable after completionmaestro knowledge review {session_id} --resolve <candidate-id> --as duplicate|related|conflict|supersede|unique [--target <knowledge-id>] --reason "<reason>". A target must come from that candidate's evidence-backed matchesrequest_user_input:
question: "以下知识候选项值得晋升到项目知识库吗？"
options:
- "晋升全部合格项" (promote all eligible candidates)
- "逐个选择" (review each candidate)
- "暂不晋升" (leave backlog pending)
maestro knowledge promote {session_id} --allmaestro knowledge promote {session_id} --candidate <candidate-id> for each selection (comma-separated compatibility remains supported)-y may run --all, which promotes all eligible candidates (observed-only emits a warning) and skips review-required and suppressed candidates. It MUST NOT auto-resolve a candidate without explicit user selection--as supersede and then promote it; promotion creates the successor and links the evolution chain. For coexisting valid rules, confirm related or conflict as appropriate. Never direct-write a candidate that was already promoted successfully2c. Complete the Session
orchestration_revision captured in Step 0 (re-read if any mutation happened since)maestro session complete command from run-mode.md, supplying the exact session_id, --participant, --actor, --request-id, --reason, --expected-orchestration-revision, and --json2d. DAG progression
state.json.sessions[] — find sessions that became dep-ready (all depends_on sealed)question: "Session {slug} 已完成。推荐激活下一个 session: {next-slug}，是否确认？"
options:
- "激活推荐 session"
- "选择其他 session"
- "暂不激活"
active_session_id to selected session--archive) — optional freezecompleted or failed (an open Session must --complete or fail first; archived is already archived)orchestration_revision:
maestro session archive --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {archive_request_id} --reason "<reason>" [--evidence <ref> ...] --expected-orchestration-revision {orchestration_revision} --jsonrun-response/1.2 receipt (status: archived, revision incremented). Archived Sessions reject all mutations (create_run/advance_chain/transition_run/add_evidence/decide) until --unarchive--unarchive) — return to openarchivedmaestro session unarchive --session {session_id} --participant {actor_id} --actor {actor_id} --request-id {unarchive_request_id} --reason "<reason>" [--evidence <ref> ...] --expected-orchestration-revision {orchestration_revision} --jsonstatus: open). The Session accepts Runs and chain mutations again; extend it with maestro session chain insert ... and maestro run next--knowledge)Run Step 2b (Knowledge reconciliation) without any lifecycle mutation. Leave the Session status unchanged.
| Condition | Suggestion |
|---|---|
| Next session activated | route step analyze through /maestro-next or the canonical receipt-chained session open -> session chain insert --command analyze --arg "<goal>" -> run next flow |
| Session archived, later extension needed | maestro-session-manage --session {session_id} --unarchive |
| Knowledge candidates pending | maestro knowledge review {session_id} |
| Knowledge health review needed | /maestro-knowledge audit |
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | Session not found | Check state.json.sessions[] / maestro session list --json |
| E002 | error | Session already completed / archived | Nothing to do; use inspect or --unarchive |
| E003 | error | Active runs exist | Complete or seal pending runs first |
| E004 | error | Critical gates failed | Run verify/review to resolve |
| E005 | error | ORCHESTRATION_REVISION_CONFLICT on archive/unarchive | Re-read session status, retry with fresh revision and new request-id |
| E006 | error | Open decision gate blocks session complete | maestro run decide <point> --verdict proceed|fix |
| W001 | warning | No knowledge candidates found | Proceed |
| W002 | warning | No verify/review run in session — gate check skipped | Consider running verify before completing |
| W003 | warning | Candidate backlog left pending | Review later with maestro knowledge review {session_id} |
| W004 | warning | Reconciliation review remains unresolved | Completion may continue; promotion stays blocked until maestro knowledge review --resolve |
| </error_codes> |
<success_criteria>
session status before any mutationopen; archive only from completed/failed; unarchive only from archived)maestro knowledge review (or deliberately skipped)maestro knowledge promote--participant/--actor/--request-id/--reason/--expected-orchestration-revision/--json) and the transition receipt was verified--complete)
</success_criteria>