spec-runner 1.1.7 → 1.1.8

package/spec-runner/templates/.claude/skills/design-change/references//345/275/261/351/237/277/347/257/204/345/233/262/343/203/201/343/202/247/343/203/203/343/202/257/343/203/252/343/202/271/343/203/210.md

@@ -0,0 +1,66 @@
+# 影響範囲チェックリスト
+
+design-change の Phase 3（影響ドキュメントの特定）で参照する。
+変更の種類に応じて、修正が必要なドキュメントを網羅的に特定する。
+
+## 変更種別ごとのチェック項目
+
+### エージェントの追加・変更・削除
+
+| ドキュメント | パス | チェック |
+|------------|------|------|
+| ユースケース一覧 | `docs/02_概要設計/ユースケース一覧.md` | エージェントが担当する UC の追加・修正・削除を反映 |
+| システム全体俯瞰 | `docs/02_概要設計/システム全体俯瞰.md` | エージェント構成・責務分割への影響 |
+| エージェント設計 | `docs/03_詳細設計/src/agents/{agent_name}/agent.md` | オーケストレーション、利用プラグイン、I/O の変更 |
+| ドメイン設計 | `docs/03_詳細設計/src/agents/{agent_name}/domain.md` | エンティティ・値オブジェクト・不変条件の変更 |
+| プロンプト設計 | `docs/03_詳細設計/src/agents/{agent_name}/prompts.md` | プロンプト構成・指示内容の変更 |
+| 設定 | `docs/03_詳細設計/src/agents/{agent_name}/config.md` | 設定パラメータ・閾値の変更 |
+
+### ドメインモデル（エンティティ・値オブジェクト）の変更
+
+| ドキュメント | パス | チェック |
+|------------|------|------|
+| ドメイン設計 | `docs/03_詳細設計/src/agents/{agent_name}/domain.md` | フィールド・ルール・不変条件の変更 |
+| システム全体俯瞰 | `docs/02_概要設計/システム全体俯瞰.md` | 責務境界や共有概念への影響 |
+| プロンプト設計 | `docs/03_詳細設計/src/agents/{agent_name}/prompts.md` | ドメイン変更がプロンプトに影響する場合 |
+| データベース設計 | `docs/03_詳細設計/infrastructure/database.md` | テーブル構造・保存方針への影響 |
+| スキーマ定義 | `docs/03_詳細設計/infrastructure/schema.dbml` | カラム・型・制約の変更 |
+| スキル設計 | `docs/03_詳細設計/src/plugins/skills/{skill_name}/skill.md` | スキルの入出力・判定ロジックへの影響 |
+| ツール設計 | `docs/03_詳細設計/src/plugins/tools/{tool_name}/tool.md` | ツールの入出力への影響 |
+
+### プラグイン（スキル・ツール）の追加・変更・削除
+
+| ドキュメント | パス | チェック |
+|------------|------|------|
+| スキル設計 | `docs/03_詳細設計/src/plugins/skills/{skill_name}/skill.md` | スキルの追加・修正・削除 |
+| ツール設計 | `docs/03_詳細設計/src/plugins/tools/{tool_name}/tool.md` | ツールの追加・修正・削除 |
+| エージェント設計 | `docs/03_詳細設計/src/agents/{agent_name}/agent.md` | 利用プラグイン一覧と呼び出し順の更新 |
+| ユースケース一覧 | `docs/02_概要設計/ユースケース一覧.md` | 対応する UC がある場合 |
+| システム全体俯瞰 | `docs/02_概要設計/システム全体俯瞰.md` | プラグイン構成の変更が全体構造に影響する場合 |
+
+### データベーススキーマの変更
+
+| ドキュメント | パス | チェック |
+|------------|------|------|
+| データベース設計 | `docs/03_詳細設計/infrastructure/database.md` | テーブル定義・インデックス・リレーション |
+| スキーマ定義 | `docs/03_詳細設計/infrastructure/schema.dbml` | dbml ファイルの更新 |
+| ドメイン設計 | `docs/03_詳細設計/src/agents/{agent_name}/domain.md` | ドメインモデルへの影響 |
+| エージェント設計 | `docs/03_詳細設計/src/agents/{agent_name}/agent.md` | 保存フローやトランザクションへの影響 |
+
+### アーキテクチャ・設計方針の変更
+
+| ドキュメント | パス | チェック |
+|------------|------|------|
+| ADR | `docs/02_概要設計/90_ADR/` | 横断的な決定 |
+| ADR（ドメインローカル） | `docs/02_概要設計/<ドメイン>/90_ADR/` | 特定ドメインの決定 |
+| システム全体俯瞰 | `docs/02_概要設計/システム全体俯瞰.md` | 技術方針・全体構成の変更 |
+| 要件定義 | `docs/01_要件定義/要件定義.md` | 要件レベルの変更がある場合 |
+| 詳細設計一式 | `docs/03_詳細設計/src/**` | 方針変更の具体反映 |
+
+## 二次影響の確認観点
+
+- **ユースケース一覧 ↔ エージェント設計**: 一覧に記載の UC がエージェントとプラグインでカバーされているか
+- **システム全体俯瞰 ↔ 詳細設計**: 責務分割が `docs/03_詳細設計/src/**` に落ちているか
+- **ドメイン設計 ↔ DBスキーマ**: ドメインのフィールドが DB カラムと対応しているか
+- **schema.dbml ↔ database.md**: dbml と設計書の内容が一致しているか
+- **frontmatter ↔ 実ファイル**: `depends_on` と `maps_to` が現状に追随しているか

package/spec-runner/templates/.claude/skills/design-change/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,81 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+  depends_on:
+    - overview.system_context
+  maps_to: []
+---
+
+# ADR-0001 {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+**決定者**: {名前}
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 選択肢
+
+### 案1: {案1の名前}
+
+- 概要: {何をするか}
+- メリット:
+  - {メリット}
+- デメリット:
+  - {デメリット}
+- 適合性: {このプロジェクトにどう合うか}
+
+### 案2: {案2の名前}
+
+- 概要: {何をするか}
+- メリット:
+  - {メリット}
+- デメリット:
+  - {デメリット}
+- 適合性: {このプロジェクトにどう合うか}
+
+### 案3: {案3の名前}
+
+- 概要: {何をするか}
+- メリット:
+  - {メリット}
+- デメリット:
+  - {デメリット}
+- 適合性: {このプロジェクトにどう合うか}
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/02_概要設計/{対象文書}.md`
+- `docs/03_詳細設計/src/{対象パス}.md`

package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: existing-project-to-docs
+description: 既存プロジェクトを読み解き、docs の draft と architecture contract を起こすリバース設計フロー。
+---
+
+# existing-project-to-docs
+
+既存コードから docs を起こすフロー。
+コード、テスト、設定、インフラ定義を読み、`docs/` と `.spec-runner/` の最初の土台を作る。
+
+## 全体フロー
+
+```
+Phase 1: 現状把握
+Phase 2: 要件とユースケースの抽出
+Phase 3: 概要設計の draft 化
+Phase 4: 詳細設計の draft 化
+Phase 5: architecture contract 化
+```
+
+## Phase 1: 現状把握
+
+1. `src/`、`tests/`、設定ファイル、README、IaC を読む
+2. 現状システムの入口、主要フロー、外部依存を一覧化する
+3. `.spec-runner/intake/current-system-inventory.md` を作る
+4. ユーザーに確認・承認を得る
+
+## Phase 2: 要件とユースケースの抽出
+
+1. 既存機能からユースケースを逆算する
+2. `docs/01_要件定義/要件定義.md` と `docs/02_概要設計/ユースケース一覧.md` の draft を作る
+3. ユーザーに確認・承認を得る
+
+## Phase 3: 概要設計の draft 化
+
+1. `docs/02_概要設計/システム全体俯瞰.md` を作る
+2. 必要なら ADR 候補も洗い出す
+3. ユーザーに確認・承認を得る
+
+## Phase 4: 詳細設計の draft 化
+
+1. `docs/03_詳細設計/src/**` を `src/` ミラーで作る
+2. `maps_to` に対応コードとテストを入れる
+3. 補助設計が必要なら `docs/03_詳細設計/infrastructure/**` を作る
+4. ユーザーに確認・承認を得る
+
+## Phase 5: architecture contract 化
+
+1. `.spec-runner/architecture/architecture.yaml` を作る
+2. 現状構造を project 専用 skill へ渡せる粒度に整える
+3. `architecture-skill-development` へ引き渡す
+
+## 原則
+
+- 既存コードを正として観測し、推測は明示する
+- docs は最初から完璧を目指さず、draft として起こす
+- `maps_to` と `depends_on` を使って後続変更に耐える形へ整える

package/spec-runner/templates/.claude/skills/harness-engineering/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: harness-engineering
+description: AI 開発運用の skills・rules・agents・テンプレートを改善・保守するためのメタスキル。別の作業を進めた結果、繰り返し発生する手戻り、ルール不足、責務の曖昧さ、テンプレートの重複が見つかったときに使用する。通常の機能実装やアプリコードの TDD には使わない。
+---
+
+# harness-engineering
+
+skills・rules・agents・テンプレートを改善するためのメタスキル。
+**主目的の作業を先に進め、再利用価値のある改善が必要なときだけ使う。**
+
+## 使うタイミング
+
+以下のいずれかに当てはまるときに使う。
+
+1. 同じ補足説明や修正が繰り返し必要になった
+2. 複数の skill / rule / agent の責務が曖昧で、手戻りや重複が発生した
+3. 既存の skill / rule / agent が不足しており、品質または作業速度を継続的に落としている
+4. ユーザーが skill / rule / agent 自体の改善を求めた
+
+## 使わないタイミング
+
+- 1 回限りの例外対応
+- 通常の機能実装やバグ修正
+- アプリケーションコードに対する TDD
+- 単なる言い回しの微調整で済む変更
+
+**TDD はこのスキルの対象ではない。**
+TDD は `test-driven-development` スキルに従い、対象プロダクトのコード品質を上げるために行う。
+
+## 全体フロー
+
+```
+Phase 1: 問題の抽出
+Phase 2: 対応方針の決定
+Phase 3: skill / rule / agent / template の修正
+Phase 4: 影響範囲の反映確認
+```
+
+## Phase 1: 問題の抽出
+
+### 手順
+
+1. 今回の作業で何が詰まり、どこに無駄が出たかを整理する
+2. その問題が一時的なものか、再発しうる構造的な問題かを判定する
+3. 改善対象を特定する
+   - skill
+   - rule
+   - agent
+   - template
+
+### 出力
+
+- 問題の要約
+- 再発条件
+- 変更対象の候補一覧
+
+## Phase 2: 対応方針の決定
+
+1. 最小変更で解決できる対象を選ぶ
+2. 新しい skill を増やすべきか、既存 skill / rule / agent の修正で十分かを判断する
+3. Claude / Copilot の両テンプレートに影響するか確認する
+
+### 判断原則
+
+- まず既存の資産を直す
+- 新しい skill は、繰り返し使う独立したワークフローがある場合だけ追加する
+- 一時的な事情を恒久ルールにしない
+
+## Phase 3: skill / rule / agent / template の修正
+
+1. 対象ファイルを特定する
+2. 意図が変わらない最小差分で修正する
+3. 片系だけでなく、対応するテンプレートも揃えて更新する
+   - `.claude/`
+   - `.github/`
+4. references や templates を参照している場合、必要な範囲だけ更新する
+
+### 修正時の注意
+
+- 役割の重複を増やさない
+- 既存スキルの主要フローを壊さない
+- ユーザー承認が前提のフローは勝手に短絡しない
+- アプリコード向けの TDD ルールを、このスキルの改善目的と混同しない
+
+## Phase 4: 影響範囲の反映確認
+
+### 確認項目
+
+- 問題の原因に対して、変更箇所が直接効いているか
+- 関連する skill / rule / agent / template の記述が矛盾していないか
+- Claude / Copilot の対応ファイルに反映漏れがないか
+- 今回限りのノイズをルール化していないか
+
+## 原則
+
+- **ハーネス改善は常時実行しない。必要なときだけ行う**
+- **主目的の作業を優先する**
+- **最小変更で改善する**
+- **新しい skill の追加は慎重に行う**
+- **TDD の責務を skill 改善と混同しない**

package/spec-runner/templates/.claude/skills/plugin-development/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: plugin-development
+description: プラグイン型アーキテクチャ向けの reference workflow。docs を正本にし、概要設計から `src/` ミラーの詳細設計、TDD、実装へ進める。
+---
+
+# plugin-development
+
+プラグイン型アーキテクチャ向けの新規開発フロー。
+`architecture-definition` や `architecture-skill-development` が未整備な段階でも使える reference implementation として扱う。
+
+## 全体フロー
+
+```
+Phase 1: 要件定義
+Phase 2: 概要設計
+Phase 3: ADR（必要時のみ）
+Phase 4: 詳細設計
+Phase 5: TDD → 実装
+```
+
+## 前提ルール
+
+- docs は正本とし、各ドキュメントに `spec_runner` frontmatter を付ける
+- `docs/03_詳細設計/src/**` は原則として `src/` をミラーする
+- `docs/03_詳細設計/infrastructure/**` は例外文書として扱い、必ず `maps_to` で対応先を明示する
+- ユーザー承認なしに次フェーズへ進めない
+
+## Phase 1: 要件定義
+
+### 手順
+
+1. 以下をユーザーにヒアリングする
+   - 解決すべき課題
+   - 提供価値
+   - 対象ユーザー
+   - 非機能要件
+   - スコープ外
+   - 技術・ビジネス制約
+2. テンプレート `templates/01_要件定義/概要テンプレート.md` をコピーして `docs/01_要件定義/要件定義.md` を作る
+3. frontmatter の `node_id` / `kind` / `depends_on` / `maps_to` を埋める
+4. ユーザーに確認・承認を得る
+
+### 出力
+
+```text
+docs/
+  01_要件定義/
+    要件定義.md
+```
+
+## Phase 2: 概要設計
+
+### 2-1. ユースケース一覧
+
+1. Phase 1 の要件定義からユースケースを洗い出す
+2. Query / Command を意識して一覧化する
+3. テンプレート `templates/02_概要設計/ユースケース一覧テンプレート.md` をコピーして作る
+4. 必要なら `docs/02_概要設計/ユースケース/` 配下に個別 UC も作る
+5. ユーザーに確認・承認を得る
+
+### 2-2. システム全体俯瞰
+
+1. ユースケース一覧から責務境界、主要コンポーネント、外部 IF を整理する
+2. テンプレート `templates/02_概要設計/システム全体俯瞰テンプレート.md` をコピーして作る
+3. 必要なら `ドメイン責務マップ.md` / `外部IF一覧.md` / `非機能・運用方針.md` を追加する
+4. ユーザーに確認・承認を得る
+
+### 出力
+
+```text
+docs/
+  02_概要設計/
+    ユースケース一覧.md
+    システム全体俯瞰.md
+    ユースケース/
+      UC-*.md
+    90_ADR/
+```
+
+## Phase 3: ADR（必要時のみ）
+
+1. 実装方針に意思決定が必要な場合だけ ADR を作る
+2. **必ず 3 案を比較する**
+3. テンプレート `templates/02_概要設計/90_ADR/ADRテンプレート.md` をコピーして生成する
+4. 配置先は `docs/02_概要設計/90_ADR/ADR-0001-{slug}.md` を原則とする
+5. 採用案を概要設計へ反映してから次へ進む
+
+## Phase 4: 詳細設計
+
+**各ドキュメントは `src/` と決定的に対応づける。**
+
+### 4-1. エージェント
+
+テンプレート:
+- `templates/03_詳細設計/src/agents/{agent_name}/agent.md`
+- `templates/03_詳細設計/src/agents/{agent_name}/domain.md`
+- `templates/03_詳細設計/src/agents/{agent_name}/prompts.md`
+- `templates/03_詳細設計/src/agents/{agent_name}/config.md`
+
+出力:
+
+```text
+docs/
+  03_詳細設計/
+    src/
+      agents/
+        {agent_name}/
+          agent.md
+          domain.md
+          prompts.md
+          config.md
+```
+
+### 4-2. プラグイン
+
+テンプレート:
+- `templates/03_詳細設計/src/plugins/skills/{skill_name}/skill.md`
+- `templates/03_詳細設計/src/plugins/tools/{tool_name}/tool.md`
+
+出力:
+
+```text
+docs/
+  03_詳細設計/
+    src/
+      plugins/
+        skills/
+          {skill_name}/
+            skill.md
+        tools/
+          {tool_name}/
+            tool.md
+```
+
+### 4-3. インフラ補助設計
+
+`src` ミラーだけでは表現しきれない DB / IaC / 運用構成だけ、例外として補助設計を置く。
+
+テンプレート:
+- `templates/03_詳細設計/infrastructure/database.md`
+- `templates/03_詳細設計/infrastructure/schema.dbml`
+- `templates/03_詳細設計/infrastructure/aws.md`
+- `templates/03_詳細設計/infrastructure/sequence/シーケンス図テンプレート.md`
+
+出力:
+
+```text
+docs/
+  03_詳細設計/
+    infrastructure/
+      database.md
+      schema.dbml
+      aws.md
+      sequence/
+```
+
+ユーザーに確認・承認を得る
+
+## Phase 5: TDD → 実装
+
+詳細設計が承認されたら `test-driven-development` スキルへ移行する。
+
+### 実装完了後のレビュー
+
+- `@design-reviewer` — frontmatter と `maps_to` を起点に設計書⇔実装の整合性チェック
+- `@code-reviewer` — コーディング規約への適合チェック
+
+## 原則
+
+- **ユースケースは途中で止めずに洗い出す**
+- **詳細設計は `src/` ミラーを優先する**
+- **補助設計を置く場合も `maps_to` で対応先を残す**
+- **`plugin-development` を最終形とみなさず、project 専用 skill の種として扱う**

package/spec-runner/templates/.claude/skills/plugin-development/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//346/246/202/350/246/201/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,88 @@
+---
+spec_runner:
+  node_id: req.{project_slug}
+  kind: requirements
+  depends_on: []
+  maps_to: []
+---
+
+# {プロジェクト名} 要件定義
+
+## 背景・問題提起
+
+### 解決すべき課題
+
+**課題1: {課題名}**
+
+- {問題の詳細}
+- {現状の問題点}
+- {影響範囲}
+
+**課題2: {課題名}**
+
+- {問題の詳細}
+- {現状の問題点}
+- {影響範囲}
+
+## 提供価値
+
+### 主要機能
+
+1. **{機能名}**
+   - {機能の概要}
+   - {提供価値}
+
+2. **{機能名}**
+   - {機能の概要}
+   - {提供価値}
+
+### 対象ユーザー
+
+- **{ユーザー種別}**: {ニーズ・利用シーン}
+- **{ユーザー種別}**: {ニーズ・利用シーン}
+
+## 非機能要件
+
+### パフォーマンス
+
+- {指標名}: {目標値}
+- {指標名}: {目標値}
+
+### スケーラビリティ
+
+- {要件}
+- {要件}
+
+### セキュリティ
+
+- {要件}
+- {要件}
+
+### 運用性
+
+- {要件}
+- {要件}
+
+## スコープ外
+
+### {機能カテゴリ}
+
+- **理由**: {なぜ作らないか}
+- **将来**: {いつ・どのように実装するか}
+
+### {機能カテゴリ}
+
+- **理由**: {なぜ作らないか}
+- **将来**: {いつ・どのように実装するか}
+
+## 制約・前提条件
+
+### 技術制約
+
+- {制約内容}
+- {制約内容}
+
+### ビジネス制約
+
+- {制約内容}
+- {制約内容}

package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,81 @@
+---
+spec_runner:
+  node_id: adr.{decision_slug}
+  kind: adr
+  depends_on:
+    - overview.system_context
+  maps_to: []
+---
+
+# ADR-0001 {決定内容のタイトル}
+
+**ステータス**: 提案 / 採用 / 廃止 / 置換
+**日付**: YYYY-MM-DD
+**決定者**: {名前}
+
+## コンテキスト
+
+| 項目 | 内容 |
+|------|------|
+| 現在の状況 | {問題・課題} |
+| 要件 | {実現する必要があること} |
+| 制約 | {技術的・ビジネス的制約} |
+
+## 選択肢
+
+### 案1: {案1の名前}
+
+- 概要: {何をするか}
+- メリット:
+  - {メリット}
+- デメリット:
+  - {デメリット}
+- 適合性: {このプロジェクトにどう合うか}
+
+### 案2: {案2の名前}
+
+- 概要: {何をするか}
+- メリット:
+  - {メリット}
+- デメリット:
+  - {デメリット}
+- 適合性: {このプロジェクトにどう合うか}
+
+### 案3: {案3の名前}
+
+- 概要: {何をするか}
+- メリット:
+  - {メリット}
+- デメリット:
+  - {デメリット}
+- 適合性: {このプロジェクトにどう合うか}
+
+## 決定
+
+**採用案**: {案名}
+
+### 採用理由
+
+- {理由1}
+- {理由2}
+
+### 実装方針
+
+1. {方針1}
+2. {方針2}
+3. {方針3}
+
+## 影響
+
+| カテゴリ | 項目 | 内容 |
+|----------|------|------|
+| システム | 新規追加 | {コンポーネント} |
+| システム | 変更 | {コンポーネント} |
+| パフォーマンス | 処理速度 | {変化} |
+| コスト | 追加コスト | {影響} |
+| 制約 | 将来課題 | {課題} |
+
+### 反映が必要な文書
+
+- `docs/02_概要設計/{対象文書}.md`
+- `docs/03_詳細設計/src/{対象パス}.md`