spec-runner 1.1.7 → 1.1.9

package/spec-runner/templates/.github/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/.github/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/.github/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`

package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/202/267/343/202/271/343/203/206/343/203/240/345/205/250/344/275/223/344/277/257/347/236/260/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,80 @@
+---
+spec_runner:
+  node_id: overview.system_context
+  kind: overview
+  depends_on:
+    - req.{project_slug}
+    - overview.usecases
+  maps_to: []
+---
+
+# システム全体俯瞰
+
+## 目的
+
+{システムの目的と全体的なアーキテクチャを説明する}
+
+## 全体像
+
+```mermaid
+graph TB
+    subgraph Input["入力"]
+        A["{入力1}"]
+        B["{入力2}"]
+    end
+
+    subgraph Core["主要コンポーネント"]
+        C["{コンポーネント1}"]
+        D["{コンポーネント2}"]
+    end
+
+    subgraph External["外部 IF"]
+        E["{外部IF1}"]
+        F["{外部IF2}"]
+    end
+
+    A --> C
+    B --> D
+    C --> E
+    D --> F
+```
+
+## 主要コンポーネント
+
+| コンポーネント | 責務 | 実現するユースケース | 主な依存 |
+|---------------|------|-------------------|----------|
+| **{コンポーネント名}** | {責務の説明} | {UC一覧} | {依存一覧} |
+
+## ドメイン責務
+
+| ドメイン | 責務 | 主要な入出力 | 境界の根拠 |
+|---------|------|------------|-----------|
+| **{ドメイン名}** | {責務} | {入出力} | {根拠} |
+
+## 外部 IF / 連携先
+
+| IF名 | 相手先 | 目的 | 入力 | 出力 |
+|------|--------|------|------|------|
+| **{IF名}** | {相手先} | {目的} | {入力} | {出力} |
+
+## データフロー
+
+```mermaid
+sequenceDiagram
+    participant User as ユーザー
+    participant App as {主要コンポーネント}
+    participant Tool as {ツールまたは外部IF}
+
+    User->>App: {操作}
+    App->>Tool: {依頼}
+    Tool-->>App: {結果}
+    App-->>User: {応答}
+```
+
+## 非機能・運用方針
+
+| 項目 | 方針 | 根拠 |
+|------|------|------|
+| パフォーマンス | {方針} | {根拠} |
+| セキュリティ | {方針} | {根拠} |
+| 運用 | {方針} | {根拠} |

package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,57 @@
+---
+spec_runner:
+  node_id: overview.usecases
+  kind: overview
+  depends_on:
+    - req.{project_slug}
+  maps_to: []
+---
+
+# ユースケース一覧
+
+## ユースケースマップ
+
+```mermaid
+graph LR
+    subgraph Domain1["{Domain1}"]
+        D1Q1["UC-{日本語名1}"]
+        D1C1["UC-{日本語名2}"]
+    end
+
+    subgraph Domain2["{Domain2}"]
+        D2Q1["UC-{日本語名3}"]
+        D2C1["UC-{日本語名4}"]
+    end
+```
+
+## {Domain1}
+
+| ユースケース | 種別 | 概要 | アクター | 入力 | 出力 |
+|------------|------|------|---------|------|------|
+| **UC-{日本語名1}** | Query | {概要} | {アクター} | {入力} | {出力} |
+| **UC-{日本語名2}** | Command | {概要} | {アクター} | {入力} | {出力} |
+
+**特記事項**
+
+- {前提条件}
+- {例外条件}
+
+## {Domain2}
+
+| ユースケース | 種別 | 概要 | アクター | 入力 | 出力 |
+|------------|------|------|---------|------|------|
+| **UC-{日本語名3}** | Query | {概要} | {アクター} | {入力} | {出力} |
+| **UC-{日本語名4}** | Command | {概要} | {アクター} | {入力} | {出力} |
+
+**特記事項**
+
+- {前提条件}
+- {例外条件}
+
+## ユースケース間の依存関係
+
+```mermaid
+graph TD
+    UC1["UC-{日本語名1}"] -->|"{関係}"| UC2["UC-{日本語名2}"]
+    UC2 -->|"{関係}"| UC3["UC-{日本語名3}"]
+```

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/aws.md

@@ -0,0 +1,53 @@
+---
+spec_runner:
+  node_id: detail.infrastructure.aws.{stack_slug}
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+  maps_to:
+    - infra/{iac_path}
+    - src/infrastructure/{component_path}.py
+---
+
+# AWS構成: {サービス名・機能名}
+
+## アーキテクチャ図
+
+```mermaid
+graph LR
+    User[ユーザー] --> API[API Gateway]
+    API --> Lambda[Lambda]
+    Lambda --> RDS[(RDS)]
+    Lambda --> S3[S3]
+```
+
+## AWSサービス構成
+
+| サービス | リソース名 | 用途 | 設定値 |
+|----------|-----------|------|--------|
+| Lambda | `{function-name}` | {用途} | メモリ: {MB}, タイムアウト: {秒} |
+| RDS | `{db-instance}` | {用途} | インスタンス: {type}, ストレージ: {GB} |
+| S3 | `{bucket-name}` | {用途} | バージョニング: {有無} |
+
+## IAM / ネットワーク
+
+| 項目 | 設定 |
+|------|------|
+| IAMロール | {role-name} |
+| VPC | {vpc-id} |
+| サブネット | {subnet-ids} |
+| セキュリティグループ | {sg-id}: {ルール} |
+
+## デプロイ構成
+
+| 項目 | 設定 |
+|------|------|
+| デプロイ方法 | {CDK / Terraform / CloudFormation} |
+| デプロイ単位 | {スタック名} |
+| 環境 | {dev / staging / production} |
+
+## 監視・アラート
+
+| 監視項目 | 閾値 | 通知先 |
+|----------|------|--------|
+| {メトリクス名} | {閾値} | {通知先} |

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/database.md

@@ -0,0 +1,54 @@
+---
+spec_runner:
+  node_id: detail.infrastructure.database
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+  maps_to:
+    - src/infrastructure/{component_path}.py
+    - migrations/{migration_file}.sql
+---
+
+# データベース設計: {テーブル名・スキーマ名}
+
+## スキーマ定義
+
+**DBMLファイル**: `schema.dbml`
+
+## テーブル設計方針
+
+### {table_name}
+
+**責務**: {このテーブルが担う役割}
+
+**インデックス設計**
+
+- `idx_{table}_{column}`: {理由}
+- `idx_{table}_{column}`: {理由}
+
+## アクセスパターン
+
+| 操作 | クエリ | 頻度 | 使用インデックス |
+|------|--------|------|----------------|
+| {操作名} | `SELECT ...` | {高/中/低} | `idx_{table}_{column}` |
+| {操作名} | `INSERT ...` | {高/中/低} | - |
+
+## パフォーマンス考慮事項
+
+- 想定データ量: {件数}
+- 増加率: {増加件数}
+- アーカイブ戦略: {方針}
+
+## データ整合性
+
+| 項目 | 方法 |
+|------|------|
+| トランザクション分離レベル | {READ COMMITTED / REPEATABLE READ} |
+| 楽観的ロック | {使用有無・方法} |
+| 悲観的ロック | {使用有無・方法} |
+
+## テスト観点
+
+- 主要クエリの成立
+- インデックス前提の検索
+- マイグレーション後方互換

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/schema.dbml

@@ -0,0 +1,25 @@
+// maps_to:
+// - migrations/{migration_file}.sql
+// - src/infrastructure/{component_path}.py
+
+Table {table_name} {
+  id varchar(26) [pk, note: "ULID"]
+  {field_name} varchar(255) [not null, note: "{説明}"]
+  created_at timestamptz [not null, default: `now()`]
+  updated_at timestamptz [not null, default: `now()`]
+
+  indexes {
+    {field_name} [name: "idx_{table_name}_{field_name}"]
+  }
+
+  Note: "{テーブルの説明}"
+}
+
+Table {child_table_name} {
+  id varchar(26) [pk, note: "ULID"]
+  {table_name}_id varchar(26) [not null, note: "FK to {table_name}"]
+  {field_name} text [null, note: "{説明}"]
+  created_at timestamptz [not null, default: `now()`]
+}
+
+Ref: {child_table_name}.{table_name}_id > {table_name}.id [delete: cascade]

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/sequence//343/202/267/343/203/274/343/202/261/343/203/263/343/202/271/345/233/263/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md

@@ -0,0 +1,28 @@
+---
+spec_runner:
+  node_id: detail.infrastructure.sequence.{sequence_slug}
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+  maps_to:
+    - src/{related_path}
+---
+
+# {シーケンス名}
+
+```mermaid
+sequenceDiagram
+    participant U as ユーザー
+    participant A as {参加者A}
+    participant B as {参加者B}
+
+    U->>A: {操作}
+    A->>B: {依頼}
+    B-->>A: {結果}
+    A-->>U: {応答}
+```
+
+## 補足
+
+- 対象ユースケース: {UC}
+- 例外分岐: {分岐}

package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/agent.md

@@ -0,0 +1,56 @@
+---
+spec_runner:
+  node_id: detail.src.agents.{agent_name}.agent
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+    - use_case.{use_case_slug}
+  maps_to:
+    - src/agents/{agent_name}/agent.py
+    - tests/agents/{agent_name}/test_agent.py
+---
+
+# `src/agents/{agent_name}/agent.py` 詳細設計
+
+## 責務
+
+- {このモジュールが果たす役割}
+- 実現するユースケース: {UC一覧}
+- 呼び出す依存: {依存一覧}
+
+## 入力と出力
+
+| 種別 | 名前 | 型 | 説明 |
+|------|------|----|------|
+| 入力 | {入力名} | {型} | {説明} |
+| 出力 | {出力名} | {型} | {説明} |
+
+## 主要フロー
+
+1. {ステップ1}
+2. {ステップ2}
+3. {ステップ3}
+
+## 判断条件
+
+| 判断ポイント | 条件 | アクション |
+|------------|------|----------|
+| **{判断ポイント}** | {条件} | {アクション} |
+
+## エラーハンドリング
+
+| エラーケース | 検知方法 | 対応方法 |
+|------------|---------|---------|
+| **{エラーケース}** | {検知方法} | {対応方法} |
+
+## 依存モジュール
+
+| 依存 | 目的 | 呼び出しタイミング |
+|------|------|----------------|
+| **{依存モジュール}** | {目的} | {タイミング} |
+
+## テスト観点
+
+- {正常系の観点}
+- {異常系の観点}
+- {境界条件の観点}