playbooks

home / skills / chachamaru127 / claude-code-harness / session-state

session-state skill

/skills/session-state

This skill verifies and executes session state transitions according to internal rules to ensure reliable workflow progression.

npx playbooks add skill chachamaru127/claude-code-harness --skill session-state

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.4 KB
---
name: session-state
version: 1.0.0
description: "SESSION_ORCHESTRATION.mdに基づくセッション状態遷移管理。内部用。Do NOT load for: user session management, login state, app state handling."
description-en: "Manages session state transitions per SESSION_ORCHESTRATION.md. Internal use only. Do NOT load for: user session management, login state, app state handling."
description-ja: "SESSION_ORCHESTRATION.mdに基づくセッション状態遷移管理。内部用。Do NOT load for: user session management, login state, app state handling."
allowed-tools: ["Read", "Bash"]
user-invocable: false
dependencies: []
---

# Session State Skill

セッション状態の遷移を管理する内部スキル。
`docs/SESSION_ORCHESTRATION.md` に定義された状態機械に従って遷移を検証・実行する。

## 機能詳細

| 機能 | 詳細 |
|------|------|
| **状態遷移** | See [references/state-transition.md](references/state-transition.md) |

## 使用タイミング

- `/work` フェーズ境界での状態更新
- エラー発生時の `escalated` 遷移
- セッション終了時の `stopped` 遷移
- セッション再開時の `initialized` 復帰

## 注意事項

- このスキルは内部使用専用です
- ユーザーが直接呼び出すことは想定していません
- 状態遷移ルールは `docs/SESSION_ORCHESTRATION.md` で定義

Overview

This skill manages session state transitions for an internal orchestration engine. It validates and executes state changes according to the defined session state machine and is intended for use only within the runtime harness. Do not use this skill for user-facing session management, login state, or general application state handling.

How this skill works

The skill inspects incoming transition requests and checks them against the session orchestration rules to determine validity. When valid, it applies the transition, updates the session record, and emits the appropriate lifecycle events; when invalid, it rejects the change and returns diagnostics. It also supports special transitions for error escalation, stop, and resume flows.

When to use it

  • At phase boundaries in the internal work orchestration pipeline (e.g., before/after executing a work unit).
  • When an internal error requires escalating the session state to an error-handling workflow.
  • When terminating a session to ensure a clean 'stopped' state and resource release.
  • When resuming a paused session and needing to restore the 'initialized' or prior state.
  • When enforcing invariant checks on state transitions as part of automated coordination.

Best practices

  • Only invoke this skill from trusted internal components; avoid exposing it to external clients.
  • Always query the current session state before requesting a transition to prevent races.
  • Handle rejected transitions gracefully by logging diagnostics and triggering fallback logic.
  • Use emitted lifecycle events to drive side effects (metrics, cleanup, notifications) instead of embedding them here.
  • Keep transition requests idempotent where possible to tolerate retries.

Example use cases

  • Orchestrator triggers a transition from 'planning' to 'working' at the start of a work cycle.
  • Automatic escalation to an 'escalated' state when a worker encounters a non-recoverable error.
  • Graceful shutdown sequence switching sessions to 'stopped' and releasing allocated resources.
  • Resuming a suspended session by validating and moving it back to 'initialized' for review.

FAQ

Can this skill be used for user login or app-wide state?

No. This skill is designed strictly for internal session orchestration and not for user authentication or general application state management.

What happens if a requested transition is invalid?

The skill rejects the transition, returns diagnostic information, and emits an event so calling components can log, retry, or trigger fallback behavior.