@sk8metal/michi-cli 0.0.1

package/docs/customization-guide.md

@@ -0,0 +1,432 @@
+# カスタマイズ機能ガイド
+
+> **凡例について**: `<feature>` などの記号の意味は [README.md#凡例の記号説明](../README.md#凡例の記号説明) を参照してください。
+
+## 概要
+
+Michiでは、チームごとに異なる開発フローに対応するため、Confluence/JIRAの作成粒度やワークフロー設定をカスタマイズ可能にしています。
+
+## 設定ファイルの構造
+
+### デフォルト設定
+
+`scripts/config/default-config.json` - Michiリポジトリに含まれるデフォルト設定
+
+### プロジェクト固有設定
+
+`.kiro/config.json` - プロジェクトルートに配置（オプション）
+
+**重要**: `.kiro/config.json`は`.gitignore`に追加することを推奨します（チーム固有設定のため）
+
+### 設定のマージ順序
+
+1. デフォルト設定を読み込み
+2. プロジェクト固有設定があればマージ（深いマージ）
+3. 環境変数で最終上書き（既存の動作を維持）
+
+### 設定値の詳細
+
+すべての設定値の詳細は [設定値リファレンス](./config-reference.md) を参照してください。
+
+## Confluence階層構造のカスタマイズ
+
+### パターン1: フラット構造（デフォルト）
+
+**設定**: 設定ファイル不要、または`pageCreationGranularity: "single"`
+
+**動作**: 1ドキュメント = 1ページ（現在の動作を維持）
+
+```
+Confluenceスペース
+└── [Michi] health-check-endpoint 要件定義
+└── [Michi] health-check-endpoint 設計
+└── [Michi] health-check-endpoint タスク分割
+```
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "single"
+  }
+}
+```
+
+### パターン2: 機能ごとの親ページ（simple階層）
+
+**設定**: `pageCreationGranularity: "by-hierarchy"` + `hierarchy.mode: "simple"`
+
+**動作**: 親ページを作成し、要件定義/設計/タスク分割を子ページとして配置
+
+```
+Confluenceスペース
+└── [Michi] health-check-endpoint（親ページ）
+    ├── 要件定義
+    ├── 設計
+    └── タスク分割
+```
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "by-hierarchy",
+    "hierarchy": {
+      "mode": "simple",
+      "parentPageTitle": "[{projectName}] {featureName}"
+    }
+  }
+}
+```
+
+### パターン3: セクション分割
+
+**設定**: `pageCreationGranularity: "by-section"`
+
+**動作**: Markdownの`##`セクションごとにページを作成（フラット）
+
+```
+Confluenceスペース
+└── [Michi] health-check-endpoint 要件定義 - 概要
+└── [Michi] health-check-endpoint 要件定義 - 機能要件
+└── [Michi] health-check-endpoint 要件定義 - 非機能要件
+```
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "by-section",
+    "pageTitleFormat": "[{projectName}] {featureName} {docTypeLabel} - {sectionTitle}"
+  }
+}
+```
+
+### パターン4: 階層構造（nested階層）
+
+**設定**: `pageCreationGranularity: "by-hierarchy"` + `hierarchy.mode: "nested"`
+
+**動作**: 親ページ → ドキュメントタイプ親 → セクション子ページの3階層
+
+```
+Confluenceスペース
+└── [Michi] health-check-endpoint（親ページ）
+    ├── 要件定義（親）
+    │   ├── 概要
+    │   ├── 機能要件
+    │   └── 非機能要件
+    ├── 設計（親）
+    │   ├── アーキテクチャ
+    │   └── API仕様
+    └── タスク分割
+```
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "by-hierarchy",
+    "hierarchy": {
+      "mode": "nested",
+      "parentPageTitle": "[{projectName}] {featureName}",
+      "createDocTypeParents": true
+    }
+  }
+}
+```
+
+### パターン5: 手動指定（manual）
+
+**設定**: `pageCreationGranularity: "manual"` + `hierarchy.structure`で明示的に定義
+
+**動作**: 設定ファイルで指定した通りにページを作成
+
+```
+Confluenceスペース
+└── [Michi] health-check-endpoint（親ページ）
+    ├── 要件定義 - 概要
+    ├── 要件定義 - 機能要件
+    ├── 要件定義 - 非機能要件
+    ├── 設計 - アーキテクチャ
+    └── 設計 - API仕様
+```
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "manual",
+    "hierarchy": {
+      "parentPageTitle": "[{projectName}] {featureName}",
+      "structure": {
+        "requirements": {
+          "pages": [
+            {
+              "title": "[{projectName}] {featureName} 要件定義 - 概要",
+              "sections": ["## 1. 概要", "## 1.1 背景"],
+              "labels": ["requirements", "overview"]
+            },
+            {
+              "title": "[{projectName}] {featureName} 要件定義 - 機能要件",
+              "sections": ["## 2. 機能要件", "## 2.1 ユーザー機能"],
+              "labels": ["requirements", "functional"]
+            }
+          ]
+        },
+        "design": {
+          "pages": [
+            {
+              "title": "[{projectName}] {featureName} 設計 - アーキテクチャ",
+              "sections": ["## 1. アーキテクチャ概要"],
+              "labels": ["design", "architecture"]
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## タイトル形式のカスタマイズ
+
+`pageTitleFormat`でページタイトルの形式をカスタマイズできます。
+
+**利用可能な変数**:
+- `{projectName}` - プロジェクト名
+- `{featureName}` - 機能名
+- `{docTypeLabel}` - ドキュメントタイプ（要件定義、設計、タスク分割）
+- `{sectionTitle}` - セクションタイトル（by-sectionの場合）
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "pageTitleFormat": "{projectName} - {featureName} - {docTypeLabel}"
+  }
+}
+```
+
+## ラベルのカスタマイズ
+
+`autoLabels`で自動付与されるラベルをカスタマイズできます。
+
+**利用可能な変数**:
+- `{projectLabel}` - プロジェクトラベル（`.kiro/project.json`の`confluenceLabels[0]`）
+- `{docType}` - ドキュメントタイプ（requirements, design, tasks）
+- `{featureName}` - 機能名
+
+**設定例**:
+```json
+{
+  "confluence": {
+    "autoLabels": [
+      "{projectLabel}",
+      "{docType}",
+      "{featureName}",
+      "custom-label"
+    ]
+  }
+}
+```
+
+## JIRA設定のカスタマイズ
+
+### Story作成粒度
+
+**設定例1: 全Storyを作成（デフォルト）**
+```json
+{
+  "jira": {
+    "storyCreationGranularity": "all"
+  }
+}
+```
+
+**設定例2: 指定フェーズのみ作成**
+```json
+{
+  "jira": {
+    "storyCreationGranularity": "selected-phases",
+    "selectedPhases": ["implementation", "testing"]
+  }
+}
+```
+
+### Epic作成の制御
+
+**設定例: Epic作成をスキップ**
+```json
+{
+  "jira": {
+    "createEpic": false
+  }
+}
+```
+
+### Story Points設定
+
+**設定例1: 自動抽出（デフォルト）**
+```json
+{
+  "jira": {
+    "storyPoints": "auto"
+  }
+}
+```
+
+**設定例2: Story Pointsを設定しない**
+```json
+{
+  "jira": {
+    "storyPoints": "disabled"
+  }
+}
+```
+
+## ワークフロー設定のカスタマイズ
+
+### フェーズの有効化
+
+**設定例: 設計フェーズをスキップ**
+```json
+{
+  "workflow": {
+    "enabledPhases": ["requirements", "tasks"]
+  }
+}
+```
+
+### 承認ゲートの設定
+
+**設定例: 日本語ロール名を使用**
+```json
+{
+  "workflow": {
+    "approvalGates": {
+      "requirements": ["企画", "部長"],
+      "design": ["アーキテクト", "部長"],
+      "release": ["SM", "部長"]
+    }
+  }
+}
+```
+
+## 対話式設定ツール
+
+`.kiro/config.json`を対話的に作成・更新できます：
+
+```bash
+# 対話式設定ツールを実行
+npx @michi/cli config:interactive
+
+# または
+npm run config:interactive
+```
+
+### 使い方
+
+1. **コマンド実行**: `npx @michi/cli config:interactive`
+2. **設定項目を選択**: 
+   - Confluence設定のカスタマイズ
+   - JIRA設定のカスタマイズ
+   - ワークフロー設定のカスタマイズ
+3. **各設定を対話的に入力**: プロンプトに従って選択・入力
+4. **設定を確認**: 最終的な設定内容を確認
+5. **保存**: 設定ファイルを`.kiro/config.json`に保存
+
+### 設定項目
+
+- **Confluence階層構造**: 5つのパターンから選択
+- **ページタイトル形式**: カスタマイズ可能
+- **JIRA Story作成粒度**: 全作成/フェーズごと/選択フェーズのみ
+- **ワークフロー有効化フェーズ**: 要件定義/設計/タスク分割から選択
+- **承認ゲート**: 各フェーズの承認者を設定
+
+## 設定ファイルのバリデーション
+
+設定ファイルの妥当性をチェックするには、以下のコマンドを実行します：
+
+```bash
+# 設定ファイルのバリデーション
+npx @michi/cli config:validate
+
+# または
+npm run config:validate
+```
+
+## 完全な設定例
+
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "by-hierarchy",
+    "pageTitleFormat": "[{projectName}] {featureName} {docTypeLabel}",
+    "autoLabels": [
+      "{projectLabel}",
+      "{docType}",
+      "{featureName}",
+      "github-sync"
+    ],
+    "hierarchy": {
+      "mode": "simple",
+      "parentPageTitle": "[{projectName}] {featureName}"
+    }
+  },
+  "jira": {
+    "storyCreationGranularity": "all",
+    "createEpic": true,
+    "storyPoints": "auto",
+    "autoLabels": [
+      "{projectLabel}",
+      "{featureName}",
+      "{phaseLabel}"
+    ]
+  },
+  "workflow": {
+    "enabledPhases": [
+      "requirements",
+      "design",
+      "tasks"
+    ],
+    "approvalGates": {
+      "requirements": ["pm", "director"],
+      "design": ["architect", "director"],
+      "release": ["sm", "director"]
+    }
+  }
+}
+```
+
+## 後方互換性
+
+- 設定ファイルが存在しない場合はデフォルト設定を使用（既存動作を維持）
+- 環境変数は引き続き優先（既存の`.env`設定が動作）
+- 段階的な移行を可能にする
+
+## トラブルシューティング
+
+### 設定ファイルが読み込まれない
+
+1. `.kiro/config.json`がプロジェクトルートに存在するか確認
+2. JSONの構文エラーがないか確認
+3. 設定ファイルのパスが正しいか確認
+
+### 階層構造が作成されない
+
+1. `pageCreationGranularity`が正しく設定されているか確認
+2. `hierarchy`設定が適切に設定されているか確認
+3. Confluence APIの権限を確認
+
+### バリデーションエラー
+
+1. エラーメッセージを確認
+2. スキーマに準拠しているか確認
+3. 必須フィールドが設定されているか確認
+
+## 参考リンク
+
+- [セットアップガイド](./setup.md)
+- [ワークフローガイド](./workflow.md)
+- [新規プロジェクトセットアップ](./new-project-setup.md)
+

package/docs/multi-project.md

@@ -0,0 +1,233 @@
+# マルチプロジェクト管理ガイド
+
+> **凡例について**: `<feature>` などの記号の意味は [README.md#凡例の記号説明](../README.md#凡例の記号説明) を参照してください。
+
+## 概要
+
+Michiは、複数プロジェクト（3-5案件）を同時並行で管理できるように設計されています。
+
+## アーキテクチャ
+
+### マイクロサービス構成
+
+```
+organization/
+├── customer-a-service-1/  ← A社 サービス1
+│   └── .kiro/
+│       ├── project.json
+│       └── specs/
+├── customer-a-service-2/  ← A社 サービス2
+│   └── .kiro/
+├── customer-b-api/        ← B社 API
+│   └── .kiro/
+└── michi/                 ← 統合ハブ（本プロジェクト）
+    └── .kiro/
+```
+
+### 統合管理
+
+**Confluence**: 共有スペース（PRD, QA, RELEASE）
+- ラベルでプロジェクトを識別
+- プロジェクト横断ダッシュボード
+
+**JIRA**: プロジェクトキー別
+- PRJA（A社案件）
+- PRJB（B社案件）
+- MICHI（統合ハブ）
+
+## プロジェクトのセットアップ
+
+### 新規プロジェクト追加
+
+詳細な手順は [新規プロジェクトセットアップガイド](./new-project-setup.md) を参照してください。
+
+**クイックスタート**:
+1. 既存リポジトリに追加: `bash /path/to/michi/scripts/setup-existing.sh`
+2. 新規リポジトリ作成: `npm run create-project -- --name <id> --project-name <name> --jira-key <key>`
+
+**マルチプロジェクト特有の注意点**:
+- 各プロジェクトは独立したリポジトリで管理
+- `.kiro/project.json`でプロジェクトを識別
+- Confluenceラベルでプロジェクト横断検索が可能
+
+### 環境変数設定
+
+各プロジェクトで`.env`ファイルを設定します。詳細は [新規プロジェクトセットアップガイド](./new-project-setup.md#step-5-環境変数設定) を参照してください。
+
+### 動作確認
+
+セットアップ完了後、プロジェクト情報を確認します：
+
+```bash
+# プロジェクト情報を表示
+cat .kiro/project.json
+
+# テスト機能で確認（オプション）
+/kiro:spec-init テスト機能
+/kiro:spec-requirements test-feature
+npx @michi/cli phase:run test-feature requirements
+```
+
+## プロジェクト切り替え
+
+### Cursorで切り替え
+
+```
+/kiro:project-switch customer-a-service-1
+```
+
+### ターミナルで切り替え
+
+```bash
+cd ~/work/projects/customer-a-service-1
+cat .kiro/project.json
+```
+
+## プロジェクト横断操作
+
+### すべてのプロジェクトを一覧表示
+
+```bash
+npm run project:list
+```
+
+出力例：
+```
+📋 プロジェクト一覧:
+
+| プロジェクト | ID | ステータス | JIRA | チーム |
+|------------|-------|----------|------|--------|
+| Michi | michi | active | MICHI | @developer1 |
+| A社 サービス1 | customer-a-service-1 | active | PRJA | @dev1, @dev2 |
+| B社 API | customer-b-api | active | PRJB | @dev3 |
+
+合計: 3 プロジェクト
+```
+
+### リソースダッシュボード生成
+
+```bash
+npm run project:dashboard
+```
+
+Confluenceに「プロジェクトリソースダッシュボード」ページを作成します。
+
+### プロジェクト横断見積もり集計
+
+```bash
+npm run multi-estimate
+```
+
+すべてのプロジェクトの見積もりを集計し、Excelファイルに出力します。
+
+## Confluenceダッシュボード
+
+### プロジェクト一覧ページ
+
+Confluenceで作成：
+
+**ページタイトル**: プロジェクト一覧
+
+**コンテンツ**:
+```
+{report-table:space=PRD|label=requirements|columns=title,labels,status}
+```
+
+**フィルタ例**:
+- A社案件のみ: `label = "project:a"`
+- レビュー待ち: `status = "レビュー待ち"`
+- 設計フェーズ: `label = "design"`
+
+### JIRAダッシュボード
+
+**フィルタ**:
+```
+project IN (MICHI, PRJA, PRJB) AND status IN ("In Progress", "In Review")
+```
+
+**グルーピング**: プロジェクトキー別
+
+**集計**: ストーリーポイント合計
+
+## プロジェクト間の依存関係
+
+プロジェクトは基本的に独立していますが、共通基盤がある場合：
+
+### 共通ライブラリプロジェクト
+
+```
+shared-infrastructure/
+└── .kiro/
+    └── project.json
+        {
+          "projectId": "shared-infra",
+          "projectName": "共通基盤",
+          "jiraProjectKey": "INFRA",
+          ...
+        }
+```
+
+### 依存関係の記述
+
+各プロジェクトの `.kiro/project.json` に追加：
+```json
+{
+  "dependencies": ["shared-infra"],
+  "dependents": ["customer-a-service-1", "customer-b-api"]
+}
+```
+
+## ベストプラクティス
+
+### 命名規則の統一
+
+**プロジェクトID**: `customer-{id}-{service}`
+- 例: `customer-a-service-1`, `customer-b-api`
+
+**JIRA プロジェクトキー**: 3-4文字
+- 例: `PRJA`, `PRJB`, `MICHI`
+
+**Confluenceラベル**: `project:{projectId}, service:{service}`
+- 例: `project:customer-a-service-1, service:s1`
+
+**ラベル生成ロジック**: 詳細は [新規プロジェクトセットアップガイド](./new-project-setup.md#ラベル生成ロジック) を参照してください。
+### チーム構成の明確化
+
+各プロジェクトの `team` フィールドに担当者を記載：
+```json
+{
+  "team": ["@tech-lead", "@frontend-dev", "@backend-dev"]
+}
+```
+
+### ステータス管理
+
+プロジェクトのステータスを適切に更新：
+- `active`: 開発中
+- `maintenance`: 保守フェーズ
+- `completed`: 完了
+- `inactive`: 休止中
+
+## トラブルシューティング
+
+### プロジェクトが一覧に表示されない
+
+`.kiro/project.json` が正しく作成されているか確認：
+```bash
+cat .kiro/project.json
+```
+
+### Confluenceで他のプロジェクトが見える
+
+ラベルでフィルタリング：
+```
+label = "project:michi"
+```
+
+### JIRA チケットが混在
+
+プロジェクトキーでフィルタリング：
+```
+project = MICHI
+```
+