@sk8metal/michi-cli 0.0.1

package/docs/phase-automation.md

@@ -0,0 +1,361 @@
+# フェーズ自動化ガイド
+
+> **凡例について**: `<feature>` などの記号の意味は [README.md#凡例の記号説明](../README.md#凡例の記号説明) を参照してください。
+
+## 概要
+
+AI-DLC（AI Development Life Cycle）の各フェーズで、Confluence/JIRA作成を**確実に実行**するためのスクリプトガイドです。
+
+## 問題: AIだけでは抜け漏れが発生する
+
+**従来の問題**:
+- AIが要件定義書（requirements.md）を作成
+- しかし、Confluenceページ作成を忘れる ❌
+- PMや部長がレビューできない状態で設計フェーズへ進んでしまう
+
+**解決策**:
+- **スクリプトによる自動化**で、Confluence/JIRA作成を確実に実行
+- **バリデーション**で、必須項目の抜け漏れをチェック
+
+## 使い方
+
+### Phase 1: 要件定義
+
+```bash
+# Step 1: AIで requirements.md を作成
+# 凡例
+/kiro:spec-requirements <feature>
+
+# 具体例
+/kiro:spec-requirements user-auth
+
+# Step 2: スクリプトでConfluence作成＋バリデーション（必須）
+# 凡例
+npm run phase:run <feature> requirements
+
+# 具体例
+npm run phase:run user-auth requirements
+
+# 実行内容:
+#  ✅ requirements.md 存在確認
+#  ✅ Confluenceページ自動作成（要件定義）
+#  ✅ spec.json自動更新
+#  ✅ バリデーション実行
+#
+# 成功時:
+#  🎉 要件定義フェーズが完了しました！
+#  📢 PMや部長にConfluenceでレビューを依頼してください
+```
+
+### Phase 2: 設計
+
+```bash
+# Step 1: AIで design.md を作成
+# 凡例
+/kiro:spec-design <feature>
+
+# 具体例
+/kiro:spec-design user-auth
+
+# Step 2: スクリプトでConfluence作成＋バリデーション（必須）
+# 凡例
+npm run phase:run <feature> design
+
+# 具体例
+npm run phase:run user-auth design
+
+# 実行内容:
+#  ✅ design.md 存在確認
+#  ✅ 要件定義完了チェック（前提条件）
+#  ✅ Confluenceページ自動作成（設計書）
+#  ✅ spec.json自動更新
+#  ✅ バリデーション実行
+#
+# 成功時:
+#  🎉 設計フェーズが完了しました！
+#  📢 PMや部長にConfluenceでレビューを依頼してください
+```
+
+### Phase 3: タスク分割
+
+```bash
+# Step 1: AIで tasks.md を作成（営業日ベース）
+# 凡例
+/kiro:spec-tasks <feature>
+
+# 具体例
+/kiro:spec-tasks user-auth
+
+# Step 2: スクリプトでJIRA作成＋バリデーション（必須）
+# 凡例
+npm run phase:run <feature> tasks
+
+# 具体例
+npm run phase:run user-auth tasks
+
+# 実行内容:
+#  ✅ tasks.md 存在確認（営業日表記チェック）
+#  ✅ 設計完了チェック（前提条件）
+#  ✅ JIRA Epic自動作成
+#  ✅ JIRA Story自動作成（全ストーリー）
+#  ✅ spec.json自動更新
+#  ✅ バリデーション実行
+#
+# 成功時:
+#  🎉 タスク分割フェーズが完了しました！
+#  📢 開発チームに実装開始を通知してください
+#  🚀 次のステップ: /kiro:spec-impl <feature>
+```
+
+## バリデーションスクリプト
+
+フェーズが完了しているか確認するだけの場合：
+
+```bash
+# 凡例
+npm run validate:phase <feature> <phase>
+
+# 具体例
+npm run validate:phase user-auth requirements  # 要件定義のバリデーション
+npm run validate:phase user-auth design         # 設計のバリデーション
+npm run validate:phase user-auth tasks          # タスク分割のバリデーション
+```
+
+### バリデーション項目
+
+#### 要件定義
+
+- [ ] requirements.md作成済み
+- [ ] **Confluenceページ作成済み** ← 重要
+- [ ] spec.jsonにconfluence.requirementsPageId記録
+- [ ] spec.jsonにconfluence.spaceKey記録
+
+#### 設計
+
+- [ ] design.md作成済み
+- [ ] 要件定義完了（前提条件）
+- [ ] **Confluenceページ作成済み** ← 重要
+- [ ] spec.jsonにconfluence.designPageId記録
+
+#### タスク分割
+
+- [ ] tasks.md作成済み
+- [ ] tasks.mdに営業日表記（月、火、水...）
+- [ ] tasks.mdに営業日カウント（Day 1, Day 2...）
+- [ ] tasks.mdに土日休みの明記
+- [ ] 設計完了（前提条件）
+- [ ] **JIRA Epic作成済み** ← 重要
+- [ ] **JIRA Story作成済み** ← 重要
+- [ ] spec.jsonにjira.epicKey記録
+- [ ] spec.jsonにjira.stories記録
+
+## エラー時の対処
+
+### Confluenceスペース不在エラー
+
+```text
+❌ Confluenceスペースが存在しません: PRD
+   → Confluenceで新しいスペースを作成: https://0kuri0n.atlassian.net/wiki/spaces
+   → または、.envのCONFLUENCE_PRD_SPACEを修正してください
+```
+
+**対処法1**: Confluenceでスペースを作成
+1. [Confluenceスペース一覧](https://0kuri0n.atlassian.net/wiki/spaces) にアクセス
+2. 「スペースを作成」をクリック
+3. スペースキーを「PRD」または「Michi」で作成
+
+**対処法2**: .envを修正
+```bash
+vim .env
+# 既存のスペースキーに変更
+CONFLUENCE_PRD_SPACE=Michi  # ← 実際に存在するスペース
+```
+
+### Confluenceページ作成エラー
+
+```text
+❌ Confluenceページ（要件定義）が作成されていません
+   → 実行: npm run confluence:sync <feature> requirements
+```
+
+**対処**:
+```bash
+# 個別に実行
+npm run confluence:sync calculator-app requirements
+```
+
+### JIRAプロジェクト不在エラー
+
+```text
+❌ JIRAプロジェクトが存在しません: PRAC1
+   → JIRAプロジェクト作成: https://0kuri0n.atlassian.net/jira/projects/create
+   → プロジェクト一覧: https://0kuri0n.atlassian.net/jira/settings/projects
+   → または、.kiro/project.jsonのjiraProjectKeyを修正してください
+      現在の設定: "PRAC1" → 実際に存在するキーに変更
+```
+
+**対処法1**: JIRAでプロジェクトを作成
+1. [JIRAプロジェクト作成](https://0kuri0n.atlassian.net/jira/projects/create) にアクセス
+2. プロジェクト名とキーを入力
+   - 名前: michi-practice1
+   - キー: PRAC1（または任意）
+3. プロジェクトタイプ: ソフトウェア開発
+
+**対処法2**: project.jsonを修正
+```bash
+vim .kiro/project.json
+# 既存のプロジェクトキーに変更
+{
+  "jiraProjectKey": "MP"  # ← 実際に存在するプロジェクトキー
+}
+```
+
+### JIRA作成エラー
+
+```text
+❌ JIRA Epicが作成されていません
+   → 実行: npm run jira:sync <feature>
+```
+
+**対処**:
+```bash
+# 個別に実行
+npm run jira:sync calculator-app
+```
+
+### 認証エラー
+
+```text
+Authentication failed: {"code":401,"message":"Unauthorized"}
+```
+
+**対処**:
+1. Cursorを再起動（Cmd+Q → 再起動）
+2. Atlassian MCP認証トークンがリフレッシュされる
+3. 再度スクリプトを実行
+
+## 推奨ワークフロー（確実な方法）
+
+```bash
+# 1. 要件定義
+/kiro:spec-requirements calculator-app  # AI実行
+npm run phase:run calculator-app requirements  # スクリプト実行（必須）
+
+# 2. 設計
+/kiro:spec-design calculator-app  # AI実行
+npm run phase:run calculator-app design  # スクリプト実行（必須）
+
+# 3. タスク分割
+/kiro:spec-tasks calculator-app  # AI実行
+npm run phase:run calculator-app tasks  # スクリプト実行（必須）
+
+# 4. バリデーション（全フェーズ）
+npm run validate:phase calculator-app requirements
+npm run validate:phase calculator-app design
+npm run validate:phase calculator-app tasks
+
+# 5. 実装開始
+/kiro:spec-impl calculator-app
+```
+
+## メリット
+
+### 1. 抜け漏れ防止
+
+- スクリプトが確実にConfluence/JIRAを作成
+- AIの判断ミスをカバー
+
+### 2. 自動バリデーション
+
+- 必須項目の完了チェック
+- エラーメッセージで対処法を表示
+
+### 3. Exit Code対応
+
+- スクリプトの成功/失敗がExit Codeで判定可能
+- CI/CDパイプラインに組み込み可能
+
+### 4. 再実行安全（冪等性）
+
+**Confluence**:
+- 既存ページがあれば更新（バージョン番号が上がる）
+- 何度実行しても重複ページは作成されない
+
+**JIRA**:
+- spec.jsonに記録されたEpic/Storyキーをチェック
+- 既存のEpic/Storyがあればスキップ
+- 新しいStoryのみ作成
+
+## 2回実行した場合の動作（冪等性）
+
+### Confluence（requirements/design）
+
+```bash
+# 1回目
+npm run phase:run calculator-app requirements
+  → Confluenceページ新規作成（version 1）
+
+# 2回目（誤って再実行）
+npm run phase:run calculator-app requirements
+  → 既存ページを検索
+  → 既存ページ更新（version 1 → 2）
+  → ✅ 重複なし
+```
+
+**結果**: 最新の内容で上書き更新されるだけ ✅
+
+### JIRA（tasks）
+
+```bash
+# 1回目
+npm run phase:run calculator-app tasks
+  → spec.jsonをチェック（Epic未記録）
+  → JQL検索（既存Epicなし）
+  → Epic作成: MP-1
+  → Story作成: MP-2〜MP-14（13個）
+  → spec.jsonに記録
+
+# 2回目（誤って再実行）
+npm run phase:run calculator-app tasks
+  → spec.jsonをチェック（Epic: MP-1記録済み）
+  → 既存Epic検出: MP-1
+  → Epic作成スキップ ✅
+  → JQL検索（既存Story: MP-2〜MP-14）
+  → 既存Storyをスキップ ✅
+  → 新しいStoryのみ作成（0個）
+  → ✅ 重複なし
+```
+
+**結果**: 既存のEpic/Storyはスキップされ、重複作成されない ✅
+
+### tasks.mdを修正した場合
+
+```bash
+# tasks.mdに新しいStoryを追加
+# Story 8.1: 新機能を追加
+
+# 再実行
+npm run phase:run calculator-app tasks
+  → 既存Epic: MP-1（スキップ）
+  → 既存Story: MP-2〜MP-14（スキップ）
+  → 新しいStory: MP-15（作成） ← 新規のみ作成
+```
+
+**結果**: 追加分のみが作成される ✅
+
+## まとめ
+
+**AIだけ**: 抜け漏れの可能性あり ❌  
+**AI + スクリプト**: 確実に実行 ✅
+
+**冪等性**: 何度実行しても安全 ✅
+- Confluence: 既存ページを更新
+- JIRA: 既存Epic/Storyをスキップ
+
+**今後の開発フロー**:
+1. AIでMarkdownファイル作成
+2. **スクリプトでConfluence/JIRA作成（必須）**
+3. バリデーションで確認
+4. レビュー依頼
+5. 次のフェーズへ
+

package/docs/quick-reference.md

@@ -0,0 +1,291 @@
+# クイックリファレンス
+
+> **凡例について**: `<feature>` などの記号の意味は [README.md#凡例の記号説明](../README.md#凡例の記号説明) を参照してください。
+
+## 新規プロジェクト作成
+
+### パターンA: 既存リポジトリにMichiワークフローを追加（最も簡単 ⭐）
+
+```bash
+# 既存プロジェクトに移動
+cd /path/to/existing-repo
+
+# 対話式セットアップスクリプト実行
+bash /path/to/michi/scripts/setup-existing.sh
+```
+
+プロジェクト名、JIRAキーを入力するだけで完了！
+
+### パターンB: 新規リポジトリを作成してセットアップ
+
+```bash
+# Michiから実行
+cd /path/to/michi
+
+# 凡例
+npm run create-project -- \
+  --name "<project-id>" \
+  --project-name "<project-name>" \
+  --jira-key "<jira-key>"
+
+# 具体例
+npm run create-project -- \
+  --name "customer-a-service-1" \
+  --project-name "A社 サービス1" \
+  --jira-key "PRJA"
+```
+
+**リポジトリ名**: `--name`で指定した値がそのままGitHubリポジトリ名として使用されます。
+
+**例**:
+- `--name "customer-a-service-1"` → GitHubリポジトリ: `org/customer-a-service-1`
+- `--name "payment-api"` → GitHubリポジトリ: `org/payment-api`
+
+**注意**: リポジトリ名はkebab-case（小文字、ハイフン区切り）を推奨します。
+
+### パターンC: 完全手動セットアップ
+
+```bash
+# 1. リポジトリ作成・クローン
+gh repo create org/repo-name --private
+jj git clone https://github.com/org/repo-name
+cd repo-name
+
+# 2. cc-sdd導入
+npx cc-sdd@latest --cursor --lang ja --yes
+
+# 3. プロジェクトメタデータ作成
+cat > .kiro/project.json << 'EOF'
+{
+  "projectId": "repo-name",
+  "projectName": "プロジェクト名",
+  "jiraProjectKey": "PRJX",
+  "confluenceLabels": ["project:x", "service:y"]
+}
+EOF
+
+# 4. Michiから共通ファイルコピー（自動スクリプト推奨）
+npx tsx /path/to/michi/scripts/setup-existing-project.ts \
+  --michi-path /path/to/michi \
+  --project-name "プロジェクト名" \
+  --jira-key "PRJX"
+
+# 5. npm install
+# 6. 初期コミット
+```
+
+詳細: [新規プロジェクトセットアップガイド](./new-project-setup.md)
+
+## 開発フロー
+
+詳細なワークフローは [AI開発ワークフローガイド](./workflow.md) を参照してください。
+
+### クイックコマンド一覧
+
+**要件定義**:
+```bash
+/kiro:spec-init <機能説明>
+/kiro:spec-requirements <feature>
+jj commit -m "docs: 要件定義" && jj git push
+npx @michi/cli phase:run <feature> requirements
+```
+
+**設計**:
+```bash
+/kiro:spec-design <feature>
+jj commit -m "docs: 設計" && jj git push
+npx @michi/cli phase:run <feature> design
+```
+
+**タスク分割**:
+```bash
+/kiro:spec-tasks <feature>
+jj commit -m "docs: タスク分割" && jj git push
+npx @michi/cli phase:run <feature> tasks
+```
+
+**実装**:
+```bash
+/kiro:spec-impl <feature> <tasks>
+jj commit -m "feat: 実装 [<jira-key>-XXX]"
+jj bookmark create <project-id>/feature/<feature> -r '@-'
+jj git push --bookmark <project-id>/feature/<feature> --allow-new
+gh pr create --head <project-id>/feature/<feature> --base init
+```
+
+## Cursorコマンド一覧
+
+| コマンド | 説明 |
+|---------|------|
+| `/kiro:spec-init <description>` | 仕様初期化 |
+| `/kiro:spec-requirements <feature>` | 要件定義生成 |
+| `/kiro:spec-design <feature>` | 設計生成 |
+| `/kiro:spec-tasks <feature>` | タスク分割 |
+| `/kiro:spec-impl <feature> <tasks>` | TDD実装 |
+| `/kiro:spec-status <feature>` | 進捗確認 |
+| `/kiro:steering` | Steering作成/更新 |
+| `/kiro:confluence-sync <feature> [type]` | Confluence同期 |
+| `/kiro:project-switch <project_id>` | プロジェクト切り替え |
+
+## Michi CLIコマンド一覧
+
+**使用方法**: `npx @michi/cli <command>` または `michi <command>`（グローバルインストール後）
+
+| コマンド | 説明 |
+|---------|------|
+| `michi jira:sync <feature>` | JIRA連携（tasks.md → Epic/Stories） |
+| `michi confluence:sync <feature> [type]` | Confluence同期（requirements/design） |
+| `michi phase:run <feature> <phase>` | フェーズ実行（requirements/design/tasks） |
+| `michi validate:phase <feature> <phase>` | フェーズ完了バリデーション |
+| `michi preflight [phase]` | プリフライトチェック |
+| `michi project:list` | プロジェクト一覧 |
+| `michi project:dashboard` | リソースダッシュボード生成 |
+| `michi workflow:run --feature <name>` | 統合ワークフロー実行 |
+| `michi config:interactive` | 対話式設定ツール（.kiro/config.json作成） |
+| `michi config:validate` | 設定ファイルのバリデーション |
+| `michi --help` | ヘルプ表示 |
+| `michi --version` | バージョン表示 |
+
+**インストール方法**:
+- **npx実行（推奨）**: `npx @michi/cli <command>` - 常に最新版を使用
+- **グローバルインストール**: `npm install -g @michi/cli` 後、`michi <command>`
+- **ローカル開発**: `npm run michi <command>` または `tsx src/cli.ts <command>`
+
+## npmスクリプト一覧（michiリポジトリ内）
+
+| コマンド | 説明 |
+|---------|------|
+| `npm run setup:env` | .env テンプレート作成 |
+| `npm run create-project` | 新規プロジェクト作成 |
+| `npm run multi-estimate` | 見積もり集計 |
+| `npm run michi` | ローカルCLIツール実行 |
+
+## プロジェクト切り替え
+
+### 方法1: Cursorコマンド
+
+```
+/kiro:project-switch <project-id>
+```
+
+### 方法2: ターミナル
+
+```bash
+cd ~/work/projects/<project-name>
+cat .kiro/project.json
+```
+
+## プロジェクト横断操作
+
+### すべてのプロジェクトを確認
+
+```bash
+cd /path/to/michi
+# 全プロジェクトの一覧を表示
+npx @michi/cli project:list
+```
+
+### リソースダッシュボード
+
+```bash
+# Confluenceにプロジェクト横断ダッシュボードを作成
+npx @michi/cli project:dashboard
+```
+
+### 見積もり集計
+
+```bash
+npm run multi-estimate
+```
+
+## Git/Jujutsuコマンド
+
+### 基本フロー
+
+```bash
+# 作業開始
+jj new main
+
+# コミット
+jj commit -m "message"
+
+# ブックマーク作成（PR用）
+jj bookmark create <project-id>/feature/<name> -r '@-'
+
+# プッシュ
+jj git push --bookmark <project-id>/feature/<name> --allow-new
+
+# PR作成
+gh pr create --head <bookmark> --base main
+```
+
+### ブランチ命名規則
+
+```
+<project-id>/feature/<feature-name>
+```
+
+例:
+- `michi/feature/user-auth`
+- `customer-a-service-1/feature/payment`
+- `customer-b-api/feature/user-endpoint`
+
+## トラブルシューティング
+
+### GitHub認証エラー
+
+```bash
+gh auth status
+gh auth login
+gh auth setup-git
+```
+
+### Confluence/JIRA認証エラー
+
+`.env` の認証情報を確認：
+```bash
+cat .env | grep ATLASSIAN
+```
+
+### MCP接続エラー
+
+1. Cursor 再起動
+2. `~/.cursor/mcp.json` 確認
+3. Atlassian API Token 再生成
+
+### npm installエラー
+
+```bash
+npm cache clean --force
+rm -rf node_modules package-lock.json
+npm install
+```
+
+## ファイルパス
+
+### プロジェクトメタデータ
+- `.kiro/project.json`
+
+### テンプレート
+- `.kiro/settings/templates/requirements.md`
+- `.kiro/settings/templates/design.md`
+- `.kiro/settings/templates/tasks.md`
+
+### 仕様書（GitHub SSoT）
+- `.kiro/specs/<feature>/requirements.md`
+- `.kiro/specs/<feature>/design.md`
+- `.kiro/specs/<feature>/tasks.md`
+
+### Steering
+- `.kiro/steering/product.md`
+- `.kiro/steering/tech.md`
+- `.kiro/steering/structure.md`
+
+## 参考リンク
+
+- [セットアップガイド](./setup.md)
+- [新規プロジェクトセットアップ](./new-project-setup.md)
+- [ワークフローガイド](./workflow.md)
+- [マルチプロジェクト管理](./multi-project.md)
+- [テスト・検証](./testing.md)
+