swain-session

セッション

エージェントセッション間で、セッションの識別情報、設定、コンテキストの継続性を管理します。このスキルはエージェントに依存せず、自動呼び出しには AGENTS.md を使用します。

自動実行の動作

このスキルはセッション開始時に自動的に呼び出されます（AGENTS.md を参照）。自動的に呼び出された場合：

1. タブ名を復元 — タブ名設定スクリプトを実行します
2. 設定を読み込む — session.json を読み取り、保存済みの設定を適用します
3. コンテキストのブックマークを表示 — 前回のセッションでコンテキストメモが残されている場合は、表示します

手動で呼び出すと、ユーザーは設定を変更したり、コンテキストをブックマークしたりできます。

セッション目的のテキスト

オペレーターが自由入力のテキストを指定して起動した場合（例：swain new bug about timestamps）、ランチャーは SWAIN_PURPOSE をエクスポートし、初期プロンプトを受け付けるランタイムには、/swain-session Session purpose: new bug about timestamps としてインラインでも渡します。

ランチャーは、そのブックマークを保存するチェックアウトを選択します。

• オペレーターがメインチェックアウトから開始した場合、ランチャーはセッション目的を渡す前に、新しいワークツリーを開きます。
• オペレーターがすでにブックマークのあるリンク済みワークツリー内から開始した場合、ランチャーは、その目的のテキストを再利用する前に、そのワークツリーの再開／完了、または別のワークツリーの作成を促す必要があります。

挨拶スクリプト（swain-session-greeting.sh）は $SWAIN_PURPOSE を読み取り、ブックマークを確定的に書き込みます（SPEC-297）。挨拶の JSON では、取得したテキストが purpose フィールドとして公開されます。

挨拶の JSON の purpose フィールドが null でない場合：

• オペレーターに表示します：**Session purpose:** <text>。

初期プロンプトを解析し直したり、自分で swain-bookmark.sh を呼び出したりしないでください。挨拶ですでに両方が行われています。インラインのプロンプトテキストは表示用のコンテキストにすぎず、正となる情報源は環境変数です。

事前確認

どの手順よりも先に、事前確認スクリプトを実行し、すべてのセッション状態を一度に取得します。これは、以前のサブプロセスチェーン（挨拶 → ブートストラップ → タブ名設定）に代わる、読み取り専用のスクリプトです。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
PREFLIGHT_SCRIPT="$(find "$REPO_ROOT" -path '*/swain-session/scripts/swain-session-preflight.sh' -print -quit 2>/dev/null)"
PREFLIGHT_JSON=$( bash "$PREFLIGHT_SCRIPT" --repo-root "$REPO_ROOT" 2>/dev/null )
echo "$PREFLIGHT_JSON"

以下のすべての手順で使用できるように PREFLIGHT_JSON を保存します。すべての判断は、この JSON のフィールドを参照します。変更を行う場合を除き、追加の確認コマンドは実行しないでください。

ステップ 1 — 簡易挨拶（SPEC-194）

挨拶スクリプトを実行します。このスクリプトは内部で事前確認を行い、軽量な変更（タブ名の設定、ロックのクリーンアップ、.agents ディレクトリの作成）を適用します。specgraph、GitHub API、または完全なステータスダッシュボードは呼び出しません。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-greeting.sh" --json

挨拶では、構造化された JSON が出力されます。

{
  "greeting": true,
  "branch": "trunk",
  "dirty": false,
  "isolated": false,
  "bookmark": "Left off implementing the bootstrap script",
  "focus": "VISION-001",
  "tab": "project @ branch",
  "warnings": []
}

事前確認の JSON には prev_session の下に前回のセッション状態も含まれているため、別途 swain-session-state.sh resume を呼び出す必要はありません。

{
  "prev_session": {
    "exists": true,
    "status": "closed",
    "session_id": "session-20260404-215204-9576",
    "focus_lane": "INITIATIVE-002",
    "phase": "closed",
    "start_time": "2026-04-05T01:52:04Z",
    "end_time": "2026-04-06T04:10:09Z",
    "decisions_made": 0,
    "walkaway": "Reviewed and fixed SPIKE-058"
  }
}

挨拶の JSON を受け取った後：

1. オペレーターに挨拶を提示します — ブランチ、変更の有無、ブックマーク（あれば）、フォーカスレーン（あれば）、警告。

2. prev_session.exists が true の場合、事前確認の JSON に含まれる前回のセッションコンテキストを表示し、続行するか最初から始めるかをオペレーターが判断できるようにします。

3. isolated が false で、オペレーターがまだ作業を開始していない場合、ここでワークツリーを作成しないでください — ワークツリーの作成は bin/swain の起動前処理で行われます（SPEC-245）。参照用にワークツリー名が必要な場合は、次のように生成します：

   bash "$REPO_ROOT/.agents/bin/swain-worktree-name.sh" "context"
   

   次に、--path を指定して挨拶を再実行し、タブ名とコンテキストを更新します：

   bash "$REPO_ROOT/.agents/bin/swain-session-greeting.sh" --path "$(pwd)" --json
   

4. bookmark が null でない場合は、表示します：

   セッションを再開 — 前回の内容：{bookmark}

5. これでセッションの作業を開始できます。完全なステータスダッシュボードは必要に応じて利用できます（ステータスダッシュボードを参照）。

$TMUX が設定されていない場合（JSON に tab がないことで検出）、tmux がインストールされているか確認します。

• tmux がインストールされていない場合： インストール（brew install tmux）を提案します。
• tmux はインストールされているが、セッション内にいない場合： 次のように表示します：[note] tmux セッション内ではありません — セッションのタブ機能とペイン機能は利用できません

オペレーターはいつでも「exit worktree」または「back to main」と言ってセッションを終了できます。ランタイムの終了後、bin/swain がワークツリーをクリーンアップします（SPEC-245）。

Worktree / ブランチの変更（エージェント非依存）

エージェントが worktree に入るとき、またはブランチを切り替えるときは、タブ名を更新するため、--path を指定してブートストラップを再実行します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-bootstrap.sh" --path "$NEW_WORKDIR" --skip-worktree --auto

これはエージェント非依存です。Claude Code、opencode、gemini cli、codex、copilot など、AGENTS.md を読み取り、bash コマンドを実行できるエージェントであれば動作します。

Session.json のスキーマ

{
  "lastBranch": "trunk",
  "lastContext": "Working on swain-session skill",
  "preferences": {
    "verbosity": "concise"
  },
  "bookmark": {
    "note": "Left off implementing the bootstrap script",
    "files": ["SKILL.md"],
    "timestamp": "2026-03-10T14:32:00Z"
  }
}

移行： .agents/session.json が存在せず、以前のグローバルな場所（~/.claude/projects/<project-path-slug>/memory/session.json）にファイルがある場合、ブートストラップスクリプトが自動的にコピーします。

README の整合性チェックポイント（SPEC-209）

あいさつの後、作業を開始する前に、README.md と成果物ツリーを比較します。これはフォーカスレーンの選択時に、セッションごとに一度実行されます。

トリガー

フォーカスレーンが設定され（前回のセッションから復元された場合、新たに選択された場合のいずれも）、README.md が存在するとき：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
[ -f "$REPO_ROOT/README.md" ] && echo "has_readme" || echo "no_readme"

README が存在しない場合は、整合性チェックを黙ってスキップします。README がないことは swain-doctor が通知します。

プロセス

1. README.md を読み、主張を抽出します。主張とは、プロジェクトの機能、対象ユーザー、仕組み、サポート内容、または示す動作に関する記述です。README 全体を文章として読み取ってください。マーカーやセクションの規約は必要ありません。
2. 主張を、現在の Active Visions、Designs、Journeys、Persona の成果物と比較します。次の点を確認します。
   • 古くなった約束 — README では機能や動作を謳っているものの、成果物では明示的に廃止または置き換えられている。
   • 記載漏れ — 成果物では機能について説明しているものの、README には記載されていない。
   • 矛盾 — README と成果物で、動作、対象ユーザー、または範囲についての記述が食い違っている。
3. 不一致ごとに、オペレーターに具体的な質問を提示します。

   "README says '{claim}' but {artifact-id} {describes the conflict}. Which is right?"

整合の方向性

双方向です。成果物が正しいとは限りません。

• 新しい Vision に合わせて README の更新が必要な場合があります。
• README が正しく、Vision の見直しが必要な場合があります。
• 約束が意図的に撤回され、両方から削除する必要がある場合があります。

保留の追跡

オペレーターは不一致を保留にできます。保留項目は .agents/session.json の readme_deferrals キーで追跡します。

{
  "readme_deferrals": [
    {
      "claim": "real-time sync",
      "conflict_artifact": "VISION-003",
      "deferred_at": "2026-03-31T14:00:00Z"
    }
  ]
}

保留項目は次回のセッション開始時に再度提示されます。オペレーターが保留を解消した場合（README または成果物を更新した場合）は、その項目をリストから削除します。

サイレントパス

ドリフトが検出されない場合、整合性チェックは黙って成功し、オペレーターには何も出力されません。

セッションのライフサイクル（SPEC-119）

swain-session は、範囲を限定したセッションのライフサイクルである 開始 → 作業 → 終了 → 再開 を管理します。セッション状態は、swain-session-state.sh スクリプトを使って .agents/session-state.json で追跡されます。

セッションの開始

ブートストラップが完了し、worktree の準備が整ったら、セッションのライフサイクルを初期化します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-state.sh" init --focus "<FOCUS-ID>" --session-roadmap "$(pwd)/SESSION-ROADMAP.md" --repo-root "$REPO_ROOT"

この処理では、次のことを行います。

1. フォーカスレーン、決定予算（デフォルトは 5）、開始時刻を含む .agents/session-state.json を作成します
2. chart.sh session --focus <ID> を使って SESSION-ROADMAP.md を生成します

フォーカスレーンは、前回のセッションのレーン（ブートストラップ JSON の session.focus）がデフォルトになります。オペレーターに確認するか、指定された変更を受け入れてください。

カスタムの決定予算：--budget 7

作業中 — 決定事項の記録

オペレーターまたはエージェントが決定を行ったとき（仕様を承認する、アプローチを選ぶ、方向性を定めるなど）は、その内容を記録します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-state.sh" record-decision --note "Approved SPEC-119 implementation approach"

セッションの終了

オペレーターが「done」「wrap up」「close session」と言ったとき、または決定予算に達したときは、この終了シーケンスを実行します。重要： swain-retro がセッション状態を読み取れるように、セッションがまだアクティブな間に実行する必要があります。retro の実行前にセッションを終了してはいけません。

ステップ 1 — セッションダイジェストと進捗ログの生成

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-digest.sh" --session-id "$(jq -r .session_id "$REPO_ROOT/.agents/session-state.json")" --output "$REPO_ROOT/.agents/session-log.jsonl"
bash "$REPO_ROOT/.agents/bin/swain-progress-log.sh" --digest "$REPO_ROOT/.agents/session-log.jsonl"

これにより、JSONL ダイジェストエントリーが追加され、変更のあった各 EPIC／Initiative の progress.md と ## Progress セクションが更新されます。

ステップ 2 — retro を実行する（セッションはアクティブなまま）

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SWAIN_RETRO_SKILL="$REPO_ROOT/.claude/skills/swain-retro/SKILL.md"
Skill("$SWAIN_RETRO_SKILL", "Session close — session is closing. Run /swain-retro to capture session learnings before the session state is cleared.")

重要： retro は、session.json と session-state.json にデータが残っている間に読み込みます。このステップの前に session-state.sh close を呼び出さないでください。

ステップ 3 — セッションを終了する

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-state.sh" close --walkaway "Completed SPEC-119 tests and state management" --session-roadmap "$(pwd)/SESSION-ROADMAP.md"

セッションのフェーズを終了時刻とともに closed に設定し、離席シグナルを SESSION-ROADMAP.md に追記します。

ステップ 4 — セッションのティアダウンを実行する

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SWAIN_TEARDOWN_SKILL="$REPO_ROOT/.claude/skills/swain-teardown/SKILL.md"
Skill("$SWAIN_TEARDOWN_SKILL", "Session teardown — --session-chain flag passed from swain-session close handler.")

孤立した worktree の確認、git のダーティ状態の確認、チケット同期のプロンプト表示を実行し、引き継ぎの概要を記録します。--session-chain フラグを指定すると、ハンドラーがすでにセッションの状態を確認しているため、重複するセッションアクティブ確認をティアダウンで省略します。

ステップ 5 — SESSION-ROADMAP.md をコミットする

最後に、SESSION-ROADMAP.md を git にコミットします。

セッションの再開

次のセッション開始時に、プリフライト JSON から prev_session を読み込みます（プリフライトを参照）。ここには、前回のセッションのフォーカスレーン、離席時のメモ、決定数、陳腐化ステータスが含まれています。別途スクリプトを呼び出す必要はありません。

session-state.sh を直接呼び出す必要がある場合（例：プリフライト JSON を持たないスクリプトから呼び出す場合）：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-state.sh" resume

前回のセッションのコンテキストを表示し、続行するか新しく開始するかをオペレーターが判断できるようにします。

セッション状態のスキーマ

{
  "session_id": "session-20260328-220634-4ad1",
  "focus_lane": "INITIATIVE-019",
  "phase": "active",
  "start_time": "2026-03-28T22:06:34Z",
  "last_activity_time": "2026-03-28T22:06:34Z",
  "end_time": null,
  "decision_budget": 5,
  "decisions_made": 0,
  "decisions": [],
  "walkaway": null
}

手動呼び出しコマンド

ユーザーから明示的に呼び出された場合は、次の操作に対応します。

タブ名の設定

ユーザーが「タブ名を X に設定して」や「タブ名を変更して」のように言った場合：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-tab-name.sh" "Custom Name"

コンテキストのブックマーク

ユーザーが「今の作業場所を記録して」や「ここをブックマークして」と言った場合：

• 会話のコンテキストから作業内容を推測するか、ユーザーが指定したメモを使います。ユーザーに尋ねないでください
• メモ、関連ファイル、タイムスタンプを含めて、session.json の bookmark フィールドに書き込みます
• すでにブックマークがある場合は、確認を求めずに黙って上書きします。swain-bookmark.sh がアトミックな書き込みを処理します

ブックマークのクリア

ユーザーが「ブックマークをクリアして」や「新しく始めて」と言った場合：

• session.json から bookmark フィールドを削除します

セッション情報の表示

ユーザーが「セッション情報」や「自分のセッションは何？」と言った場合：

• 現在のタブ名、ブランチ、設定、ブックマークの状態を表示します
• ブックマークのメモにアーティファクト ID（例：SPEC-052、EPIC-018）が含まれている場合は、戦略的なコンテキストとして Vision の祖先を示すパンくずリストを表示します。親チェーンを取得するには bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" scope <ID> 2>/dev/null | head -5 を実行します。次のように表示します：Context: Swain > Operator Situational Awareness > Vision-Rooted Chart Hierarchy

設定の変更

ユーザーが「設定 X を Y にして」と言った場合：

• session.json の preferences を更新します

操作後のブックマーク（自動更新プロトコル）

ほかの swain スキルでは、操作後にセッションのブックマークを更新します。プロトコル、呼び出しパターン、例については references/bookmark-protocol.md を参照してください。

Focus Lane

オペレーターはフォーカスレーンを設定して、単一のビジョンまたはイニシアチブ内に推奨事項の範囲を絞れます。これは方向付けの仕組みです。他の作業を隠すのではなく、オペレーターが現在注力している内容を軸に推奨事項を提示します。

フォーカスの設定： オペレーターが「セキュリティにフォーカスして」または「VISION-001に取り組んでいます」と言った場合は、名前をアーティファクトIDに解決し、フォーカススクリプトを実行します。

名前からIDへの解決： オペレーターがIDではなく名前（例：「VISION-001」ではなく「セキュリティ」）を使った場合は、swain chartを使用して、VisionおよびInitiativeアーティファクトのタイトルから最も一致するものを検索します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/chart.sh" --ids --flat 2>/dev/null | grep -i "<name>"

一致するものが1件だけの場合は、それを使用します。複数ある場合は、オペレーターに確認を求めます。一致するものがない場合は、その名前に一致するVisionまたはInitiativeがないことを伝え、作成を提案します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-focus.sh" set <RESOLVED-ID>

フォーカスの解除：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-focus.sh" clear

フォーカスの確認：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-focus.sh"

フォーカスIDに対してartifact-context.shを呼び出し、フォーカスアーティファクトをコンテキスト行として表示します。ユーティリティを利用できない場合は、IDのみを表示します。

フォーカスレーンは.agents/session.jsonのfocus_laneキーに保存されます。セッション内のステータス確認をまたいで保持されます。ステータスダッシュボードはこの情報を読み取り、推奨事項を絞り込み、フォーカス対象外のビジョンについても周辺状況を表示します。

ステータスダッシュボード（SPEC-122）

swain-sessionがプロジェクトのステータスダッシュボードを管理するようになりました。オペレーターが「ステータス」、「次は何をする」、「ダッシュボード」、「概要」、「進捗はどうなっている」、「何に取り組むべきか」、「優先事項を表示して」と言った場合は、ステータススクリプトを実行します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
STATUS_SCRIPT="$REPO_ROOT/.agents/bin/swain-status.sh"
[ -f "$STATUS_SCRIPT" ] && bash "$STATUS_SCRIPT" --refresh || echo "status dashboard script not found"

コンパクトモード（MOTD）では、bash "$STATUS_SCRIPT" --compactを実行します。

スクリプトの実行後、references/agent-summary-template.mdに従って、構造化されたエージェントの概要を提示します。

キャッシュ

ステータスは120秒のTTLで.agents/status-cache.jsonに書き込まれます。キャッシュを無視するには--refreshを、生の出力を取得するには--jsonを使用します。

推奨事項

JSONキャッシュから.priority.recommendations[0]を読み取ります。フォーカスレーンが設定されている場合、推奨事項はそのビジョン／イニシアチブに絞られます。

コンテキストを含む表示

推奨事項、フォーカスレーン、必要な決定事項などのアーティファクトをオペレーターに提示する際は、IDのみではなく、アーティファクトコンテキストユーティリティを使用します。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
CONTEXT=$(bash "$REPO_ROOT/.agents/bin/artifact-context.sh" <ARTIFACT-ID> 2>/dev/null)

ユーティリティを利用でき、出力が返される場合は、そのコンテキスト行を使用します。利用できない場合や出力が空の場合は、<ID> — <title>（現在の動作）を使用します。

表示形式：title ID — scope。progress。

モードの推定

1. 仕様がレビュー中で、戦略的な決定も保留中の場合 → オペレーターに確認します
2. 仕様がレビュー待ちの場合 → 詳細モード
3. フォーカスレーンがあり、決定事項が保留中の場合 → ビジョンモード
4. 対応が必要な項目がない場合 → ビジョンモード（マスタープランのミラー）

必要な決定事項（ロードマップとの統合）

chart.sh roadmap --jsonを使用してアイゼンハワー分類を行います。オペレーターの決定が必要な「Do First」と「Schedule」の各象限から、上位5件を表示します。

設定

このスキルは、swain.settings.json（プロジェクトルート）および~/.config/swain/settings.json（ユーザーによる上書き）を読み取ります。ユーザー設定が優先されます。

関連する設定：

• terminal.tabNameFormat — タブ名の書式文字列です。{project}と{branch}のプレースホルダーに対応しています。デフォルト：{project} @ {branch}

エラー処理

• jqが利用できない場合は、ユーザーに警告し、JSON操作をスキップします。タブ名の設定はjqがなくても機能します。
• gitが利用できない場合は、ディレクトリ名をプロジェクト名として使用し、ブランチの検出をスキップします。
• 決して致命的なエラーにしないでください。セッション管理は利便性のためのものであり、必須条件ではありません。