swain-design

仕様管理

状態を変更する操作を行う前に、アクティブなセッションがあるか確認してください。

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

JSON 出力の "status" が "active" 以外の場合は、オペレーターに「アクティブなセッションがありません — /swain-init で開始しますか？」と伝えてください。オペレーターがその提案を退けた場合は続行してください。

このスキルでは、標準となるアーティファクトの種類、フェーズ、階層を定義します。詳細な定義とテンプレートは、（このスキルのディレクトリを基準とした）references/ にあります。ホストリポジトリに AGENTS.md がある場合は、そこにあるアーティファクト関連のセクションを、このスキルの参照データと同期させてください。

アーティファクトの種類の定義

各アーティファクトの種類には、定義ファイル（ライフサイクルのフェーズ、規約、フォルダー構造）とテンプレート（フロントマターのフィールド、ドキュメントのひな形）があります。作成または移行するアーティファクトの種類に対応する定義を読んでください。

種類	内容	定義	テンプレート
製品ビジョン（VISION-NNN）	製品の最上位の方向性 — 競争力のある製品または個人向け製品の目標、対象者、成功指標です。	定義	テンプレート
イニシアチブ（INITIATIVE-NNN）	ビジョンのもとでエピックを戦略的にグループ化したもの — 優先順位付けや意思決定を追跡するための中間レベルのまとまりです。	定義	テンプレート
ユーザージャーニー（JOURNEY-NNN）	課題を含む、エンドツーエンドのユーザーワークフローです。その課題がエピックや仕様の立案につながります。	定義	テンプレート
エピック（EPIC-NNN）	ビジョンまたはイニシアチブのもとで実現する大規模な成果物 — 成功基準とともに、関連する仕様をまとめます。	定義	テンプレート
エージェント仕様（SPEC-NNN）	受け入れ基準を含む技術的な実装仕様です。type: feature | enhancement | bug に対応しています。親エピックは任意です。	定義	テンプレート
調査スパイク（SPIKE-NNN）	特定の問いと完了条件を設けた、期間限定の調査です。	定義	テンプレート
ペルソナ（PERSONA-NNN）	ジャーニーや仕様の指針となる、典型的なユーザープロフィールです。	定義	テンプレート
ADR（ADR-NNN）	単一のアーキテクチャ上の意思決定 — 背景、選択、代替案、結果を記録します（Nygard 形式）。	定義	テンプレート
ランブック（RUNBOOK-NNN）	明確なトリガーを定めた、エージェントによる、または手動の段階的な運用手順です。	定義	テンプレート
設計（DESIGN-NNN）	インタラクション（UI/UX）、データアーキテクチャ、またはシステム契約を扱う、継続的に参照される設計ドキュメントです。ドメインは、フロントマターの domain: interaction | data | system フィールドで選択します。	定義	テンプレート
トレーニングドキュメント（TRAIN-NNN）	機能やワークフローの使い方を人に教える、構成化された学習資料（ハウツー、リファレンス、クイックスタート）です。古さを検出できるよう、コミットを固定した linked-artifacts でソースアーティファクトと連携して追跡します。	定義	テンプレート
雑務（CHORE-NNN）	軽微な整理作業 — 小規模で範囲が限定され、単独で実行できます。機能コードはリリースしません。	定義	テンプレート

適切な成果物タイプの選択

ユーザーのリクエストで特定のタイプが指定されていない場合は、意図から推測します。

ユーザーの意図	成果物	シグナルとなる言葉
製品の方向性、存在意義	Vision	「製品の方向性」「何を作るべきか」「北極星」
戦略的な方向性、関連する作業のグループ化	Initiative	「〜に注力する」「セキュリティの取り組み」「これらのエピックをまとめる」「戦略的」「追跡する」
機能や成果物のリリース	Epic	「Xを作る」「Y機能を追加する」「Zを実装する」
1つの実装単位	Spec	「これを修正する」「フラグを追加する」「リファクタリングする」「小さな変更」「バグ」
小規模な整理	Chore	「整理」「構成を整える」「ファイルを移動する」「リンクを張り直す」「小さな修正」
調査課題	Spike	「〜すべきか」「調査する」「選択肢を比較する」「最善の方法は何か」
決定事項の記録	ADR	「〜に決めた」「選択肢のどちらにするか」「なぜ〜したのか」
トレーニングやドキュメントの作成	Train	「ハウツーガイド」「チュートリアル」「リファレンスドキュメント」「オンボーディング」「ウォークスルー」「トレーニング資料」「誰かに教える」

Initiative と Epic の違い — 重要な違いは次のとおりです。

• Initiative：複数の成果物を伴う 方向性 です。「セキュリティを強化する」は、スキャン、ゲート、ポリシーにまたがる Initiative です。オペレーターが方向を定めます。
• Epic：複数の Spec を伴う 成果物 です。「スキャンツールを構築する」は、明確な完了条件を持つ Epic です。エージェントが実行します。
• 経験則：作業を記述するのに Epic が2つ以上必要なら、Initiative です。Spec が2つ以上必要なら、Epic です。Spec が1つなら、Spec を作成するだけで十分です。

Initiative 配下の Spec（小規模作業のパス） — Initiative の方向性に関連するものの、Epic にするほどではないバグ、軽微な機能強化、雑務は、parent-initiative を介して Initiative に直接紐付けられます。小規模な作業がまとまってきたら、Epic への昇格を提案してください。

成果物のメタデータの更新

オペレーターが既存の成果物のフィールド更新を依頼した場合（例：「VISION-001 の優先度を高に設定する」「EPIC-017 の親を INITIATIVE-001 に変更する」）：

1. 成果物の定義ファイルを読み、フィールド名と有効な値を確認します
2. frontmatter のフィールドを直接編集します（例：priority-weight: high）
3. last-updated の日付を更新します
4. bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" build を実行して、グラフキャッシュを更新します
5. 変更をコミットします

一般的な更新：

• Vision、Initiative、Epic、Spec の priority-weight — high、medium、low を指定できます。値は引き継がれます：Vision → Initiative（上書き可能）→ Epic（上書き可能）→ Spec（上書き可能）。swain chart の下流の推奨スコアと兄弟項目のソート順に影響します。
• Epic と Spec の parent-initiative — Initiative の配下に付け替えます。Spec は parent-epic または parent-initiative のどちらか一方のみを設定でき、両方を設定することはできません。
• Initiative の parent-vision — Vision に紐付けます。

Vision または Initiative に関する文脈でオペレーターが「優先度」や「重み」と言った場合、frontmatter フィールドの priority-weight を指しています。

成果物の作成

エラー処理

操作が失敗した場合（親項目がない、番号が重複している、スクリプトエラーなど）は、復旧手順について references/troubleshooting.md を参照してください。場当たり的な回避策を考案しないでください。トラブルシューティングガイドに既知の失敗パターンが記載されています。

複雑度ティアの判定（SPEC-045）

本格的な作成手順を実行する前に、成果物を複雑度ティアに分類します。

低複雑度（ファストパスの対象）：

• type: bug または type: fix で、parent-epic がなく、下流に depends-on リンクがない SPEC
• parent-epic がない SPIKE
• ユーザーが「quick」「simple」「trivial」「fast」のような言葉を使っている成果物

中／高複雑度（すべての手順を実行）：

• 機能 SPEC（type: feature）
• parent-epic がある SPEC または SPIKE
• EPIC、INITIATIVE、Vision、Journey、ADR — 常にすべての手順を実行
• ユーザーが重要なアーキテクチャ上の決定について説明している成果物

ファストパスが適用される場合は、次のように出力します：[fast-path] Skipped: specwatch scan, scope check, index update

ワークフロー

1. 次の利用可能な番号を確認するには、次を実行します。

   bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/next-artifact-id.sh" <PREFIX>
   

   これにより、すべてのローカルブランチと作業ツリーをスキャンし、ワークツリーセッション間で ID が重複しないようにします（SPEC-193）。スクリプトを利用できない場合は、現在の HEAD にある docs/<type>/ をスキャンしてください。ただし、ワークツリーのワークフローでは重複が発生するリスクがあります。
2. VISION 成果物の場合： 草案を作成する前に、これが競争力のある製品なのか、個人向け製品なのかをユーザーに確認します。回答によって、含めるテンプレートセクションが決まり、その後の分解全体の方針が定まります。各製品タイプの詳細については、Vision の定義を参照してください。 2a. DESIGN 成果物の場合： まず、この設計が対象とするドメインを確認します。interaction（UI/UX — 画面、フロー、状態）、data（データアーキテクチャ — エンティティ、スキーマ、フロー、不変条件）、system（システム契約 — API 境界、動作保証、統合インターフェース）のいずれかです。不明な場合は、interaction をデフォルトにします。次に、Design Intent の内容を尋ねます。Context（設計の目的を示す一文）、Goals（実現を目指す体験または保証）、Constraints（レビュー可能な境界）、Non-goals（明示的に実施しないと決めたこと）です。このセクションは一度だけ記述し、作成時に設定した後、変更可能なセクションの更新に合わせて変更しません。DESIGN テンプレートから、ドメイン固有のセクションを使用してください。
3. 上記の参照表から、成果物の定義ファイルとテンプレートを読み込みます。
4. 成果物を正しいフェーズのサブディレクトリに作成します。フェーズディレクトリがまだ存在しない場合は、mkdir -p で作成します。正確なディレクトリ構造については、定義ファイルを参照してください。
5. そのタイプに必要なフィールド（テンプレートを参照）を frontmatter に記入します。authored-by には、システムプロンプトから特定したモデルの識別名（例：GLM-5.1）を設定します。サブエージェントが成果物の作成に関与した場合は、役割とともにすべてのモデルを記載します（例：GLM-5.1 (supervisor), Kimi-K2.5 (subagent)）。モデルの識別名を確認できない場合は、代わりに AI Assistant を使用します。
6. 適切なフェーズと現在の日付を使用して、ライフサイクルテーブルを初期化します。次のルールに従ってください。
   • ユーザーの依頼による場合 → Active：ユーザーが成果物を明示的に依頼した場合（例：「X についての新しい SPIKE」「Y の仕様書を作成して」）、最初から Active として作成します。ユーザーはすでにこの作業を望んでいるため、Proposed にする意味はありません。
   • エージェントの提案による場合 → Proposed：エージェントが独自の判断で成果物を作成する場合（例：ユーザーが EPIC を依頼したときに SPIKE を提案する、Vision を子 Epic に分解する）、Proposed として作成します。ユーザーはまだ明示的に合意していないため、Proposed は「これを推奨します。確認してください」という意味を示します。
   • セッション内で十分に完成している場合 → 後続のフェーズ：会話中に十分に完成していれば、成果物を後続のフェーズで直接作成できます（フェーズのスキップを参照）。 6.5. 本文中の単独の成果物 ID 参照にハイパーリンクを設定します — 成果物の本文を書いた後、frontmatter の閉じ区切り --- より下にあるテキストをすべて確認し、(SPEC|EPIC|INITIATIVE|VISION|SPIKE|ADR|PERSONA|RUNBOOK|DESIGN|JOURNEY|TRAIN|CHORE)-[0-9]+ に一致する単独の成果物 ID 参照を探します。次の条件を満たす ID ごとに対応します。
   • すでに Markdown リンク（[...](...)）内に含まれていない
   • コードフェンス（``` ブロック）またはインラインコード（`バッククォート`）内に含まれていない 次の方法で解決します。

   bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/resolve-artifact-link.sh" <ARTIFACT-ID> <SOURCE-FILE>
   

   裸の ID を [ARTIFACT-ID](relative-path) に置き換えます。スクリプトがゼロ以外の終了コードを返した場合、または出力が空の場合（アーティファクトが見つからない場合）は、操作を失敗させず、裸の ID のままにします。Frontmatter の値はプレーンな ID のままにしてください（YAML との互換性のため）。ハイパーリンクを設定するのは本文のみです。
7. 親参照が存在することを検証します（例：新しい Agent Spec が参照する Epic がすでに存在すること）。 7.5. 同一タイプの重複チェック — (継続管理タイプのみ：DESIGN、Persona、Runbook) docs/<type>/Active/ をスキャンし、同じタイプの既存の Active アーティファクトを確認します。次の場合は重複としてフラグを立てます。
   • 新しいアーティファクトの linked-artifacts が同じタイプの別のアーティファクトを参照している（これは直接的な置き換えのシグナルです）。
   • 新しいアーティファクトのスコープを示すセクション（DESIGN の Interaction Surface、Runbook の Trigger、Persona の Role）が、既存の Active アーティファクトのスコープと重複する、またはそのスコープを包含している。 重複が検出された場合は、オペレーターに「これは <EXISTING-ID>（<title>）と重複しています。新しいアーティファクトで置き換えますか？」と尋ねます。置き換える場合は、同じ操作の一環として既存のアーティファクトを Superseded に移行します（superseded-by を設定し、ステータスを更新し、Superseded/ ディレクトリに移動し、ライフサイクルエントリーを追加します）。
8. ADR 準拠チェック — bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/adr-check.sh" <artifact-path> を実行します。続行する前に、検出事項をユーザーと確認します。 8a. 整合性チェック — (高速処理パスのティアではスキップ) bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" scope <artifact-id> を実行し、references/alignment-checking.md に従って評価します。ブロッキングとなる検出事項（MISALIGNED）を報告し、推奨事項（SCOPE_LEAK、GOAL_DRIFT）は操作を止めずに伝えます。スコープチェーンや祖先をオペレーターに表示する際は、各ノードで artifact-context.sh を使い、ID とともに平易な名称を表示します。利用できない場合は、裸の ID にフォールバックします。 8b. 未接続チェック — 親参照を検証した後、新しいアーティファクトから親エッジをたどって Vision に到達できるか確認します。到達できない場合は、⚠ Vision ancestry なし — このアーティファクトは swain chart で Unanchored として表示されます と警告します。既存の Initiative または Epic に紐付けることを提案します。作成をブロックしてはいけません。
9. 操作後のスキャン — (高速処理パスのティアではスキップ) bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/specwatch.sh" scan を実行します。このスキャンでは、スキャンパイプラインの一部として design-check.sh も実行されます。コミットする前に、古い参照や設計の乖離に関する検出事項を修正します。
10. インデックス更新手順 — (高速処理パスのティアではスキップし、セッション終了時に rebuild-index.sh で一括更新) list-<type>.md を更新します（インデックスの保守を参照）。

Superpowers との統合

superpowers がインストールされている場合、以下の連鎖は必須です。スキルを呼び出し、スキップしたり、作業をインラインで行ったりしないでください。

1. Vision、Initiative、Persona の成果物を作成する前： ソクラテス式の探究を行うため、brainstorming スキルを呼び出します。成果物のコンテキスト（目標、対象者、制約）を渡します。ブレインストーミングの出力を、適切なフロントマターとライフサイクル表を含む swain の成果物形式にまとめます。

2. 新しい機能の作業を開始するとき（ブレインストーミング → 成果物 → 実装）： ブレインストーミングでアイデアを探り、設計ドキュメントを作成します。ブレインストーミングの最終段階では、正式な成果物（エピックと仕様）を作成するために swain-design を呼び出します。その後、実装に進む各 SPEC について、個別に writing-plans を呼び出します。writing-plans が計画ファイルを保存した後、計画を取り込むために swain-do を呼び出します。連鎖は、ブレインストーミング → swain-design → SPEC ごとの writing-plans → swain-do です。

2b. 既存の SPEC が実装に進むとき（ブレインストーミングは不要）： SPEC の受け入れ基準とスコープを指定して writing-plans を呼び出します。writing-plans が計画ファイルを保存した後、計画を取り込むために swain-do を呼び出します。

3. Testing → Implemented の遷移時： SPEC への準拠とコード品質をレビューするため、requesting-code-review を呼び出します（レビュー用スキルが利用可能な場合）。

検出： ls .agents/skills/brainstorming/SKILL.md .claude/skills/brainstorming/SKILL.md 2>/dev/null を実行し、少なくとも1つのパスが存在する場合、superpowers を利用できます。この結果はセッション中キャッシュしてください。

簡潔な SPEC 形式とルーティングの詳細については、references/superpowers-integration.md を参照してください。統合はすべて任意です。superpowers がなくても、swain は完全に機能します。

フェーズの遷移

フェーズは目安であり、必須のゲートではありません。成果物は先のフェーズへスキップできます。フェーズのスキップ規則、遷移ワークフロー（検証 → 移動 → コミット → ハッシュの記録）、検証／レビューのゲート、完了規則については、references/phase-transitions.md を参照してください。

Superseded 成果物の specwatch-ignore メンテナンス

フェーズ遷移ワークフロー（phase-transitions.md のステップ 5a）または成果物の作成時（同種の重複検出）のいずれの場合も、成果物が Superseded に遷移するたびに、その遷移によって作成される意図的な後方参照を .agents/specwatch-ignore にグロブパターンとして追記します。これにより、specwatch が由来を示すリンクに警告を出すのを防ぎます。

1. .agents/specwatch-ignore が存在しない場合は作成します。
2. 次のパターンを追記します：（a）Superseded になった成果物のパス、（b）それに取って代わる成果物のパス、（c）同じ操作の一環として作成され、Superseded になった成果物を参照する ADR。
3. 各エントリーにコメントを付けます：# <OLD-ID> superseded by <NEW-ID> (<YYYY-MM-DD>)。
4. 重複を避けます。ファイル内にすでに存在するパターンはスキップします。

# INITIATIVE-001 superseded by INITIATIVE-013 (2026-03-19)
docs/initiative/Superseded/(INITIATIVE-001)*
docs/initiative/Active/(INITIATIVE-013)*

この手順は、後方参照の更新（ステップ 5b）と specwatch のスキャン（作成ワークフローのステップ 9、phase-transitions.md のステップ 8）より前に実行し、スキャン結果をクリーンな状態に保ちます。

置き換え時のバックリファレンス更新

specwatch-ignore のメンテナンス（ステップ 5a）の後、フロントマター（linked-artifacts、depends-on-artifacts、addresses）で置き換えられたアーティファクトを参照している、終端状態ではないすべてのアーティファクトを更新します。手順の全容については、phase-transitions.md のステップ 5b を参照してください。主なポイントは次のとおりです。

• 更新前に整合性を確認する — 置き換えによってスコープが変わることはよくあります。参照元アーティファクトのコンテキストを読み、後継アーティファクトと照らし合わせます。後継アーティファクトとの関係が成立しない場合は、参照先を黙って変更するのではなく、オペレーターに知らせてください。
• 重複を避ける — 後継アーティファクトがすでにリストにある場合は、重複して追加せず、古いエントリーを削除します。
• コミットメッセージに変更元を記録する — 変更内容（例：「EPIC-031 linked-artifacts を更新：INITIATIVE-001 → INITIATIVE-013」）を記録し、Git の履歴に元の参照が残るようにします。
• 置き換えを行うアーティファクト自体の変更元リンクは、書き換えずに specwatch-ignore を参照します。

DESIGN のライフサイクルフック

これらのフックは、フェーズ遷移中の DESIGN アーティファクトに適用されます。

DESIGN の作成時：

• sourcecode-refs のパスがすべて HEAD に存在することを検証します（値が設定されている場合）。存在しないパスがあれば、作成完了前に警告します。

Proposed → Active への遷移時：

• DESIGN に対して design-check.sh を実行します。すべての参照が CURRENT である必要があります。
• STALE または BROKEN の参照がある場合は、遷移の完了前にオペレーターへ警告します。古い参照があるまま、黙って処理を進めないでください。

Active → Superseded への遷移時：

• 新しい（置き換えを行う）DESIGN は、古い DESIGN の sourcecode-refs を --repin で新しいピンに更新して引き継ぐ必要があります。

意思決定保護フック

これらのフックはエージェントレベルの動作ガイダンスです。スクリプトでは強制されず、このスキルファイルに従うエージェントによって適用されます。

SPEC の Implementation への遷移： SPEC が Implementation に遷移し、リンクされた DESIGN がある場合（どちらか一方の linked-artifacts または artifact-refs 経由）：

• DESIGN の Design Intent セクション（Goals、Constraints、Non-goals）を提示し、整合性を確認できるようにします。実装が設計の境界内に収まるよう、これをオペレーターに提示してください。

SPEC の完了時： SPEC が完了し、その実装によって DESIGN の sourcecode-refs で追跡されているファイルが変更された場合：

• 変更されたファイル（SPEC のコミットから取得）を、アクティブな DESIGN の sourcecode-refs と照合します。
• 重複が見つかった場合は、DESIGN を更新し、design-check.sh --repin でピンを更新するようオペレーターに促します。

整合性の連鎖確認： Epic に、DESIGN を指す rel: [aligned] の artifact-refs がある場合：

• 子 SPEC の作成時または変更時に、そのスコープを DESIGN の Constraints および Non-goals と照合します。
• たどる経路：SPEC → 親 EPIC → rel: [aligned] の artifact-refs → DESIGN → Design Intent。
• 違反がある場合のみ提示します。整合している SPEC は、問題がなければ何も提示しません。

設計からコードへのドリフト： DESIGN の変更可能なセクションが変更された一方で、sourcecode-refs の blob が変わっていない場合：

• 「DESIGN-NNN は更新されましたが、追跡対象のコードはまだ追従していません。」と伝えます。整合させるようオペレーターに促します。

ドリフトの解決（SPEC-307）

SPEC の作成、編集、またはフェーズ遷移時に、親（EPIC、Initiative、または Vision）がある場合は、ドリフトの解決を実行します。SPEC と親の両方を読みます。SPEC のスコープ、受け入れ基準、または制約が親の目標や成功基準からずれている場合は、修正を適用します。子を再整合させる（SPEC を編集する）か、親を更新します。

修正の方向は、シグナルと内容の判断によって決めます。親に対する過去のドリフト判断を数え（数が多いほど、親が古くなっている可能性が高くなります）、どちらの方向がより良い結果につながるかを評価します。修正を適用した後、その結果をオペレーターに提示し、承認、変更、または取り消しを選べるようにします。すべての結果は swain-session-state.sh record-decision によってドリフト判断として記録されます。

README の整合性に関する通知

Vision、Design、Journey、または Persona を新しいフェーズに移行する際、その移行によってプロジェクトの対外的な主張が変わる場合は、控えめな通知を表示します。

README.md を更新して、この変更を反映する必要があるかもしれません。

これは情報提供のみを目的としたもので、処理をブロックするものではありません。オペレーターは通知を閉じることができます。

トリガー条件 — 次の場合に通知します。

• Vision が Active（新しい方向性）または Abandoned（方向性の取り下げ）に移行する場合
• Design が Active（新しいインタラクションモデル、データアーキテクチャ、またはシステムコントラクト）または Superseded（置き換え）に移行する場合
• Journey が Active（新しいユーザーフロー）または Abandoned（非推奨となった経路）に移行する場合
• Persona が Active（新しい対象ユーザー）または Abandoned（対象ユーザーの取り下げ）に移行する場合

ブレインストーミングのコンテキスト — プロジェクトに README はあるもののアーティファクトがない場合（またはアーティファクトツリーが少ない場合 — Active の Vision、Design、Journey、Persona の合計が 3 未満）、brainstorming スキルの実行時に README をソクラテス式の探索の出発点として使用します。ゼロから始めるのではなく、README に記載された主張、対象ユーザー、説明されている動作をブレインストーミングの会話の種として使います。

ブレインストーミングのコンテキスト検出：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
ACTIVE_COUNT=$(find "$REPO_ROOT/docs" -path "*/Active/*" -name "*.md" 2>/dev/null | grep -cE "(VISION|DESIGN|JOURNEY|PERSONA)" || echo "0")
HAS_README=$( [ -f "$REPO_ROOT/README.md" ] && echo "yes" || echo "no" )

HAS_README=yes かつ ACTIVE_COUNT < 3 の場合、README の内容を主要なコンテキストとしてブレインストーミングに渡します。

Trove との統合

調査フェーズの移行（Spike Proposed -> Active、ADR Proposed -> Active、Vision/Epic の作成）時に、既存の trove があるか確認し、リンクまたは作成を提案します。フック、trove のスキャン、バックリンクの保守手順については、references/trove-integration.md を参照してください。

実行トラッキングの引き継ぎ

SPEC の実装を開始する際は、swain-do を呼び出します。4 階層のトラッキングモデル、swain-do: required フロントマターフィールド、意図のトリガー、調整アーティファクトの分解については、references/execution-tracking-handoff.md を参照してください。

GitHub Issues との統合

SPEC は source-issue フロントマターフィールドを介して GitHub Issues にリンクします。リンク済みの SPEC のフェーズ移行時に、コメントを投稿するか Issue をクローズします。プロモーションワークフロー、移行フック、バックエンドの抽象化については、references/github-issues-integration.md を参照してください。

ステータスの概要

プロジェクト全体のステータス、進捗、「次は何をする？」という問い合わせには、swain chart + tk + git + GitHub issues を集約する swain-session スキルを使用してください。アーティファクト固有のグラフに関する問い合わせには、bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" を使用してください。references/specgraph-guide.md を参照してください。デフォルトの出力は Vision をルートとする階層ツリーです。レンズ（ready、recommend、debt、unanchored など）を使うと、さまざまな意思決定のコンテキストに応じてツリーをフィルタリングし、注釈を付けられます。

アーティファクトの監査

ユーザーから監査を依頼された場合は、2 段階の手順（事前スキャン + ADR 準拠性を含む並列監査エージェント）について、references/auditing.md を参照してください。未連結チェックも実施してください。bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" unanchored を実行し、Vision の祖先を持たないアーティファクトがあれば、整合性と ADR 準拠性の結果とともにドメインレベルの所見として報告してください。

実装計画

実装計画は宣言的な仕様と実行トラッキングをつなぎます。実装を開始する際は、TDD 手法、superpowers との統合、計画ワークフロー、フォールバック手順について、references/implementation-plans.md を参照してください。

シナリオモデリング

シナリオモデリングは、Git のブランチ機能を使った、その時点での影響分析です。オペレーターが問いを提示し、エージェントがすべてを実行します。オペレーターが Git を操作することはありません。

目標は、ディスク上のファイルを実際に編集し、git diff で影響を確認できるようにすることです。変更されたアーティファクト、変化したロードマップ、コード参照などを確認できます。オペレーターの役割は、影響を確認して「承認」または「却下」と伝えることだけです。

これは swain-design 内で行う純粋な LLM 手順です。別個のスキル、スクリプト、新しい CLI フラグはありません。

トリガーフレーズ

オペレーターが次のいずれかを言った場合、シナリオモデリングを開始します。

• 「ADR-X が有効だったらどうなるか」
• 「Z ではなく Y を選んでいたらどうなるか」
• 「異なる ADR の前提でツリーを比較して」
• 「シナリオ：<説明>」
• 「A から B に切り替えた場合の影響を見せて」

手順

1. 意図を確認します。 オペレーターに反実仮想の前提を簡潔に確認します。「ADR-046 が Superseded ではなく Active だった場合のアーティファクトツリーを確認したい、ということですか？」

2. ブランチを作成します。

   git checkout -b scenario/<kebab-case-name>
   

   質問から名前を導きます（例：scenario/adr-046-active、scenario/pre-helm-refactor）。

3. 編集対象を特定します。 指定された ADR または決定事項から、置き換え関係のグラフをたどります。切り替えの影響を受ける各アーティファクトについて、次の項目を追跡します。

   • それを置き換えたアーティファクト（これらも切り替える必要があります）。
   • ADR と組み合わせられた設計（例：ADR-048 ↔ DESIGN-033）。
   • linked-artifacts、depends-on-artifacts、addresses 配列で切り替え対象のアーティファクトを参照しているイニシアチブおよびエピックのロードマップ。

   参照を解決するには、swain chart の出力とグラフキャッシュを使用します。

4. 編集を適用します。 シナリオブランチでフロントマターを編集します。

   • 主要な ADR と、それに対応する設計の status を切り替えます。
   • イニシアチブ／エピックのフロントマター配列（linked-artifacts など）の相互参照を更新します。
   • 本文は編集しません。フロントマターのフィールドのみ編集します。
   • アーティファクトファイルの作成や削除はしません。

5. 検証します。 ブランチで swain chart を実行します。参照切れがなく、ツリーが解決されることを確認します。代替ツリーをオペレーターに提示します。

6. 影響を提示します。 次を実行し、要約します。

   git diff trunk...HEAD --stat
   git diff trunk...HEAD -- docs/ | grep -oP 'sourcecode-refs:\K[^\n]+'
   

   変更されたアーティファクトの数、変更されたイニシアチブ／エピックのロードマップ、参照されるソースコードのパスをオペレーターに提示します。

7. 次の操作を提案します。

   • 承認： trunk にマージしてコミットします。
   • 並べて比較： trunk のワークツリーを追加し、両方で swain chart を実行して、差分を提示します。
   • 却下： ブランチを削除します。

オペレーターとのフィードバックループ

オペレーターが「DESIGN-034 も切り替えて」や「INITIATIVE-005 には触れないで」と言った場合は、編集対象を調整して再検証します。反復は会話を通じて行います。オペレーターが指示し、エージェントが実行します。

クリーンアップ

どちらの場合も、エージェントが処理します。

• 承認された場合： git checkout trunk && git merge scenario/<name> を実行し、コミットしてプッシュします。
• 却下された場合： git branch -D scenario/<name> を実行します。

例

オペレーター：「ADR-046 が有効だったらどうなるか？」

1. ブランチを作成：git checkout -b scenario/adr-046-active
2. 編集対象：ADR-046 を Active に、ADR-048 を Superseded に、DESIGN-032 を Active に、DESIGN-033 を Superseded に切り替えます。INITIATIVE-018 のロードマップで DESIGN-033 を DESIGN-032 に置き換えます。
3. 検証：swain chart — 成功。
4. 影響：4 個のアーティファクトを変更、1 個のイニシアチブのロードマップを変更、2 個のソースコードパスを参照。

---

参考資料

ワークフローの手順で参照されている場合は、次のファイルを確認してください。

• アーティファクトの関係： references/relationship-model.md — 型階層と相互参照を示す ER 図
• ライフサイクル表の形式： references/lifecycle-format.md — コミットハッシュの記録規約
• インデックスのメンテナンス： references/index-maintenance.md — list-<type>.md の更新ルール
• ツール： スクリプトは scripts/（このスキルのディレクトリからの相対パス）にあります。詳細は references/specwatch-guide.md、references/specgraph-guide.md、references/adr-check-guide.md を参照してください。

セッションのブックマーク

状態を変更する操作の後は、ブックマークを更新してください：bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/swain-bookmark.sh" "<action> <artifact-ids>" --files <paths>