@sk8metal/michi-cli 0.8.7 → 0.11.0

package/docs/README.md

@@ -1,96 +1,33 @@
-# Michiドキュメント
+# Michi (道)
 
-Michiは、AI駆動開発ワークフロー自動化プラットフォームです。このドキュメントでは、Michiの使い方と開発方法を説明します。
+**M**anaged **I**ntelligent **C**omprehensive **H**ub for **I**ntegration
 
-## ドキュメント構造
+AI駆動開発ワークフロー自動化プラットフォーム
 
-Michiのドキュメントは、目的別に以下のカテゴリに整理されています。
+[![npm version](https://badge.fury.io/js/@sk8metal%2Fmichi-cli.svg?icon=si%3Anpm)](https://badge.fury.io/js/@sk8metal%2Fmichi-cli)
+[![CI](https://github.com/sk8metalme/michi/actions/workflows/ci.yml/badge.svg)](https://github.com/sk8metalme/michi/actions/workflows/ci.yml)
+[![Test Setup](https://github.com/sk8metalme/michi/actions/workflows/test-setup.yml/badge.svg)](https://github.com/sk8metalme/michi/actions/workflows/test-setup.yml)
+[![Security](https://github.com/sk8metalme/michi/actions/workflows/security.yml/badge.svg)](https://github.com/sk8metalme/michi/actions/workflows/security.yml)
+[![codecov](https://codecov.io/gh/sk8metalme/michi/branch/main/graph/badge.svg)](https://codecov.io/gh/sk8metalme/michi)
 
-### 🚀 はじめに ([getting-started/](./getting-started/))
+## 概要
 
-初めてMichiを使う方向けのガイドです。
+Michiは、開発フロー全体（要件定義→設計→タスク分割→実装→テスト→リリース）をAIで自動化するプラットフォームです。
 
-| ドキュメント | 説明 |
-|------------|------|
-| [セットアップガイド](./getting-started/setup.md) | Michiのインストールと設定手順 |
-| [クイックスタート](./getting-started/quick-start.md) | 5分で始めるMichi |
-| [新規リポジトリ作成](./getting-started/new-repository-setup.md) | 新規リポジトリを作成してMichiを使い始める方法 |
-| **[ハンズオンガイド](./hands-on/README.md)** ⭐ | 実際に手を動かして学ぶ1時間のチュートリアル |
+**Powered by [cc-sdd](https://github.com/gotalab/cc-sdd)**
 
-### 📖 実践ガイド ([guides/](./guides/))
+### はじめに
 
-Michiを使った開発の実践的なガイドです。
+- [5分で始めるMichi](getting-started/quick-start.md) - クイックスタートガイド
+- [インストール](getting-started/installation.md) - インストール方法
+- [環境設定](getting-started/configuration.md) - 環境変数とMCP設定
 
-| ドキュメント | 説明 |
-|------------|------|
-| [ワークフローガイド](./guides/workflow.md) ⭐ | AI開発フローの詳細 |
-| [フェーズ自動化ガイド](./guides/phase-automation.md) ⭐ | Confluence/JIRA自動作成 |
-| [Multi-Repo管理ガイド](./guides/multi-repo-guide.md) | マイクロサービス等複数リポジトリの統合管理、AI支援初期化・要件定義・設計 |
-| [マルチプロジェクト管理](./guides/multi-project.md) | 複数プロジェクトの同時管理 |
-| [カスタマイズガイド](./guides/customization.md) | Confluence/JIRA階層構造のカスタマイズ |
+### リファレンス
 
-### 📚 リファレンス ([reference/](./reference/))
+- [CLIコマンドリファレンス](reference/cli.md) - 全CLIコマンドの詳細
 
-コマンドや設定値のリファレンス資料です。
+## 対象読者
 
-| ドキュメント | 説明 |
-|------------|------|
-| [クイックリファレンス](./reference/quick-reference.md) ⭐ | コマンド一覧・チートシート |
-| [設定値リファレンス](./reference/config.md) | `.michi/config.json`の全設定値 |
-| [タスクテンプレート](./reference/tasks-template.md) | タスク記述のテンプレート |
+このドキュメントは、Michiを利用してプロジェクト開発を行う**ユーザー向け**です。
 
-### 🛠️ コントリビューター向け ([contributing/](./contributing/))
-
-Michiプロジェクトに貢献したい開発者向けのガイドです。
-
-| ドキュメント | 説明 |
-|------------|------|
-| [開発環境セットアップ](./contributing/development.md) | 開発者向けセットアップ手順 |
-| [リリース手順](./contributing/release.md) | バージョンアップ・NPM公開 |
-| [CI/CD設定](./contributing/ci-cd.md) | CI/CD整備計画 |
-
-### 📝 一時ドキュメント ([tmp/](./tmp/))
-
-プロジェクト管理や計画のための一時的なドキュメントです（gitで管理されません）。
-
-## おすすめの読み方
-
-### Michiを初めて使う場合
-
-1. [セットアップガイド](./getting-started/setup.md) - Michiをインストール
-2. [クイックスタート](./getting-started/quick-start.md) - 5分で基本的な使い方を習得
-3. **[ハンズオンガイド](./hands-on/README.md)** ⭐ - 1時間で全ワークフローを体験
-4. [ワークフローガイド](./guides/workflow.md) - AI開発フローを理解
-
-### Michiを別のプロジェクトで使う場合
-
-1. [新規リポジトリ作成](./getting-started/new-repository-setup.md) - 新規リポジトリでの始め方
-2. [クイックリファレンス](./reference/quick-reference.md) - コマンド一覧を確認
-
-### Confluence/JIRAの設定をカスタマイズする場合
-
-1. [カスタマイズガイド](./guides/customization.md) - カスタマイズ方法
-2. [設定値リファレンス](./reference/config.md) - 全設定値の詳細
-
-### Michiの開発に貢献する場合
-
-1. [コントリビューションガイド](../CONTRIBUTING.md) - 貢献方法の概要
-2. [開発環境セットアップ](./contributing/development.md) - 開発環境の構築
-3. [リリース手順](./contributing/release.md) - リリースプロセス
-
-## アイコンの意味
-
-- ⭐: 重要度が高いドキュメント
-- 🚧: 作成中のドキュメント
-- 📦: 外部リンク
-
-## 質問・フィードバック
-
-ドキュメントに関する質問やフィードバックがある場合は、[issue](https://github.com/sk8metalme/michi/issues)を作成してください。
-
-## 参考リンク
-
-- [Michiリポジトリ](https://github.com/sk8metalme/michi)
-- [cc-sdd公式ドキュメント](https://github.com/gotalab/cc-sdd)
-- [Cursor IDE](https://cursor.sh/)
-- [Atlassian MCP Server](https://www.atlassian.com/ja/platform/remote-mcp-server)
+Michi自体の開発に貢献する場合は、[CONTRIBUTING.md](../CONTRIBUTING.md) を参照してください。

package/docs/getting-started/configuration.md

@@ -0,0 +1,379 @@
+# 環境設定
+
+Michiを使用するための環境設定について説明します。
+
+## 設定ファイル構成
+
+Michiは以下の設定ファイルを使用します：
+
+| ファイル | 用途 | 必須 | スコープ |
+|---------|------|------|----------|
+| `.env` | 認証情報・環境変数 | はい | プロジェクト |
+| `~/.michi/.env` | グローバル環境変数 | いいえ | 全プロジェクト |
+| `~/.michi/config.json` | グローバルワークフロー設定 | いいえ | 全プロジェクト |
+| `.kiro/project.json` | プロジェクトメタデータ | 自動生成 | プロジェクト |
+| `.michi/config.json` | プロジェクト固有ワークフロー設定 | いいえ | プロジェクト |
+| `mcp.json` | MCP設定（Cursor用） | いいえ | プロジェクト |
+
+**設定の優先順位**（高い順）:
+1. `.env`（プロジェクト環境変数）- 最高優先度
+2. `.michi/config.json`（プロジェクト固有ワークフロー設定）
+3. `.kiro/project.json`（プロジェクトメタデータ）
+4. `~/.michi/config.json`（グローバルワークフロー設定）
+5. `~/.michi/.env`（グローバル環境変数）
+6. デフォルト設定
+
+## グローバル環境変数（~/.michi/.env）
+
+すべてのプロジェクトで共通する認証情報や環境変数を、ホームディレクトリに保存できます。
+
+### 用途
+
+複数のプロジェクトで同じAtlassian組織やGitHub組織を使用する場合、グローバル `.env` に認証情報を一度設定するだけで、すべてのプロジェクトで利用できます。
+
+### セットアップ方法
+
+```bash
+mkdir -p ~/.michi
+touch ~/.michi/.env
+```
+
+その後、以下のような共通の認証情報を記載します：
+
+```bash
+# Atlassian認証（組織共通）
+ATLASSIAN_URL=https://your-domain.atlassian.net
+ATLASSIAN_EMAIL=your-email@company.com
+ATLASSIAN_API_TOKEN=your-token-here
+
+# GitHub設定（組織共通）
+GITHUB_ORG=your-github-org
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+
+# Confluenceスペース（組織共通）
+CONFLUENCE_PRD_SPACE=PRD
+CONFLUENCE_QA_SPACE=QA
+CONFLUENCE_RELEASE_SPACE=RELEASE
+
+# JIRAプロジェクトキー（組織共通）
+JIRA_PROJECT_KEYS=PROJECT
+
+# JIRA Issue Type ID（組織共通）
+JIRA_ISSUE_TYPE_STORY=10036
+JIRA_ISSUE_TYPE_SUBTASK=10037
+```
+
+### メリット
+
+- すべてのプロジェクトで共通の認証情報を一度だけ定義
+- 新しいプロジェクトでも認証情報の再入力が不要
+- プロジェクト固有の `.env` で必要に応じて上書き可能
+
+### セキュリティ上の注意
+
+**⚠️ 重要**：複数の組織/クライアントで作業する場合は注意が必要です。
+
+- **単一組織の場合**：グローバル `.env` に認証情報を保存すると便利
+- **複数組織の場合**：プロジェクトごとに `.env` を設定することを推奨
+  - 誤って違う組織の認証情報を使ってしまうリスクを回避
+
+### 配置場所
+
+- **macOS/Linux**: `~/.michi/.env`
+- **Windows**: `%USERPROFILE%\.michi\.env`
+
+## .env ファイル設定（プロジェクト固有）
+
+プロジェクトルートに `.env` ファイルを作成します。このファイルはグローバル `.env` より優先されます。
+
+### 必須設定
+
+#### Atlassian認証
+
+```bash
+ATLASSIAN_URL=https://your-domain.atlassian.net
+ATLASSIAN_EMAIL=your-email@company.com
+ATLASSIAN_API_TOKEN=your-token-here
+```
+
+**APIトークン取得方法**:
+1. [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) にアクセス
+2. "Create API token" をクリック
+3. トークン名を入力（例: "Michi CLI"）
+4. 生成されたトークンをコピーして `ATLASSIAN_API_TOKEN` に設定
+
+#### JIRA Issue Type ID（必須）
+
+```bash
+JIRA_ISSUE_TYPE_STORY=10036
+JIRA_ISSUE_TYPE_SUBTASK=10037
+```
+
+**Issue Type ID確認方法**:
+
+##### 方法1: JIRA REST API（推奨）
+
+```bash
+curl -u your-email@company.com:your-token \
+  https://your-domain.atlassian.net/rest/api/3/issuetype
+```
+
+結果から `"id"` フィールドを確認します。
+
+##### 方法2: JIRA管理画面
+
+1. JIRA設定 > Issues > Issue types を開く
+2. StoryとSub-taskのIssue Type IDを確認
+
+**注意**: Issue Type IDはJIRAインスタンス固有の値です。上記の例（10036, 10037）をそのまま使用せず、必ず実際の環境のIDを確認してください。
+
+### オプション設定
+
+#### GitHub設定
+
+```bash
+GITHUB_ORG=your-github-org
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+```
+
+#### Confluenceスペース
+
+```bash
+CONFLUENCE_PRD_SPACE=PRD
+CONFLUENCE_QA_SPACE=QA
+CONFLUENCE_RELEASE_SPACE=RELEASE
+```
+
+#### JIRAプロジェクトキー
+
+```bash
+JIRA_PROJECT_KEYS=PROJECT
+```
+
+#### カスタムフィールド（JIRAプロジェクト固有）
+
+```bash
+JIRA_STORY_POINTS_FIELD=customfield_10016
+JIRA_EPIC_LINK_FIELD=customfield_10014
+```
+
+**カスタムフィールドID確認方法**:
+
+```bash
+curl -u your-email@company.com:your-token \
+  https://your-domain.atlassian.net/rest/api/3/field
+```
+
+結果から該当フィールドの `"id"` を確認します。
+
+#### レートリミット対策
+
+```bash
+ATLASSIAN_REQUEST_DELAY=500
+```
+
+リクエスト間隔をミリ秒で指定します（デフォルト: 500ms）。
+
+#### Slack通知
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
+```
+
+#### ワークフロー承認ゲート
+
+```bash
+APPROVAL_GATES_REQUIREMENTS=pm,director
+APPROVAL_GATES_DESIGN=architect,director
+APPROVAL_GATES_RELEASE=sm,director
+```
+
+## グローバル設定（~/.michi/config.json）
+
+すべてのプロジェクトに共通する設定を、ホームディレクトリに保存できます。
+
+### 推奨セットアップ手順
+
+新しいプロジェクトで作業を開始する前に、グローバル設定を作成することを推奨します。
+
+グローバル設定ディレクトリを作成し、設定ファイルを手動で作成します：
+
+```bash
+mkdir -p ~/.michi
+touch ~/.michi/config.json
+```
+
+その後、エディタで `~/.michi/config.json` を開き、以下の設定を記述します：
+- Confluence設定（ページ作成単位など）
+- JIRA設定（Epic作成、Story Points設定など）
+- ワークフロー設定（有効化するフェーズなど）
+
+設定例は下記の「設定例」セクションを参照してください。
+
+### グローバル設定のメリット
+
+- すべてのプロジェクトで共通の設定を一度だけ定義
+- 新しいプロジェクトでも即座に利用可能
+- プロジェクト固有の設定（`.michi/config.json`）で必要に応じて上書き可能
+
+### 設定例
+
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "single"
+  },
+  "jira": {
+    "createEpic": true,
+    "storyCreationGranularity": "all",
+    "storyPoints": "auto"
+  },
+  "workflow": {
+    "enabledPhases": ["requirements", "design", "tasks"]
+  }
+}
+```
+
+### 配置場所
+
+- **macOS/Linux**: `~/.michi/config.json`
+- **Windows**: `%USERPROFILE%\.michi\config.json`
+
+### 手動作成
+
+対話的ツールを使わず、直接ファイルを作成することもできます：
+
+```bash
+mkdir -p ~/.michi
+touch ~/.michi/config.json
+```
+
+その後、上記の設定例を参考に編集してください。
+
+## .michi/config.json 設定（プロジェクト固有）
+
+ワークフロー設定をカスタマイズする場合に使用します。
+
+### 初期設定
+
+`michi init` 実行時に、対話的に設定するか、デフォルト設定が作成されます。
+
+### デフォルト設定例
+
+```json
+{
+  "confluence": {
+    "pageCreationGranularity": "single"
+  },
+  "jira": {
+    "createEpic": true,
+    "storyCreationGranularity": "all",
+    "storyPoints": "auto"
+  },
+  "workflow": {
+    "enabledPhases": ["requirements", "design", "tasks"]
+  }
+}
+```
+
+### 設定項目
+
+#### confluence
+
+- `pageCreationGranularity`: ページ作成単位（`"single"` または `"multiple"`）
+
+#### jira
+
+- `createEpic`: Epic作成の有無（`true` または `false`）
+- `storyCreationGranularity`: Story作成単位（`"all"` または `"phase"`）
+- `storyPoints`: Story Points設定（`"auto"` または数値）
+
+#### workflow
+
+- `enabledPhases`: 有効化するフェーズリスト
+
+## mcp.json 設定（Cursor用）
+
+CursorでAtlassian MCPサーバーを使用する場合に設定します。
+
+### 設定例
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["-y", "@atlassian/mcp-server-atlassian"],
+      "env": {
+        "ATLASSIAN_URL": "https://your-domain.atlassian.net",
+        "ATLASSIAN_EMAIL": "your-email@company.com",
+        "ATLASSIAN_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### 配置場所
+
+- Windows: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\mcp.json`
+- macOS: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/mcp.json`
+- Linux: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/mcp.json`
+
+## 設定検証
+
+設定が正しいことを確認します。
+
+### 基本検証
+
+```bash
+michi preflight
+```
+
+すべての設定を確認します。
+
+### 個別検証
+
+#### JIRA接続確認
+
+```bash
+michi preflight jira
+```
+
+#### Confluence接続確認
+
+```bash
+michi preflight confluence
+```
+
+### セキュリティチェック
+
+```bash
+michi config:check-security
+```
+
+## トラブルシューティング
+
+### JIRA Issue Type IDが見つからない
+
+```
+❌ Invalid JIRA Issue Type ID
+```
+
+原因: `JIRA_ISSUE_TYPE_STORY` または `JIRA_ISSUE_TYPE_SUBTASK` の値が実際のJIRA環境のIssue Type IDと一致していません。
+
+解決策: 上記の「JIRA Issue Type ID確認方法」を参照して、正しいIDを取得してください。
+
+### Atlassian認証エラー
+
+```
+❌ Authentication failed
+```
+
+原因: ATLASSIAN_API_TOKENが無効、または有効期限切れです。
+
+解決策: 新しいAPIトークンを生成し、`.env` を更新してください。
+
+## 次のステップ
+
+- [CLIコマンドリファレンス](../reference/cli.md) - 使用可能なコマンド

package/docs/getting-started/installation.md

@@ -0,0 +1,59 @@
+# インストール
+
+Michiをインストールする3つの方法を説明します。
+
+## 前提条件
+
+- **Node.js**: 20.0.0以上
+- **npm**: 10.0.0以上
+
+バージョン確認：
+
+```bash
+node --version
+npm --version
+```
+
+## 推奨：npmグローバルインストール
+
+最も推奨される方法です。`michi` コマンドがグローバルに利用可能になります。
+
+```bash
+npm install -g @sk8metal/michi-cli
+```
+
+インストール確認：
+
+```bash
+michi --version
+```
+
+## npx実行（常に最新版）
+
+インストールせずに、常に最新版を実行できます。
+
+```bash
+npx @sk8metal/michi-cli init
+```
+
+**利点**: 常に最新版を使用
+**欠点**: 実行のたびにダウンロードが発生する可能性がある
+
+## アップデート
+
+グローバルインストールしたMichiをアップデート：
+
+```bash
+npm update -g @sk8metal/michi-cli
+```
+
+## アンインストール
+
+```bash
+npm uninstall -g @sk8metal/michi-cli
+```
+
+## 次のステップ
+
+- [クイックスタート](quick-start.md) - 5分で始める
+- [環境設定](configuration.md) - 詳細な環境設定

package/docs/getting-started/quick-start.md

@@ -0,0 +1,76 @@
+# 5分で始めるMichi
+
+Michiをインストールして、最初のプロジェクトを初期化するまでの最短ガイドです。
+
+## 前提条件
+
+- Node.js 20以上
+- npm 10以上
+- AIツール（Claude Code、Cursor、Gemini CLI、Codex CLI、またはCline）
+
+## インストール
+
+```bash
+npm install -g @sk8metal/michi-cli
+```
+
+## グローバル設定（推奨）
+
+新しいプロジェクトで作業を開始する前に、グローバル設定を行うことを推奨します。
+
+グローバル設定ディレクトリを作成します：
+
+```bash
+mkdir -p ~/.michi
+```
+
+その後、`~/.michi/config.json` と `~/.michi/.env` を手動で作成し、共通設定を記述します。
+
+**メリット**: すべてのプロジェクトで共通の設定を一度だけ定義でき、新しいプロジェクトでも即座に利用可能になります。
+
+詳細は [環境設定ガイド - グローバル設定](configuration.md#グローバル設定michichconfigjson) を参照してください。
+
+## プロジェクト初期化
+
+### 新規プロジェクトの場合
+
+```bash
+michi init --claude-agent
+```
+
+### 既存プロジェクトの場合
+
+プロジェクトディレクトリで実行：
+
+```bash
+michi init --existing --claude-agent
+```
+
+**注**: `--claude-agent` は環境オプションです（推奨）。他に `--claude`, `--cursor`, `--gemini`, `--codex`, `--cline` も選択可能です。
+
+## 環境設定
+
+プロジェクトの `.env` ファイルを編集して、認証情報を設定します：
+
+```bash
+ATLASSIAN_URL=https://your-domain.atlassian.net
+ATLASSIAN_EMAIL=your-email@company.com
+ATLASSIAN_API_TOKEN=your-token-here
+```
+
+**ヒント**: 複数プロジェクトで共通の認証情報を使う場合は、グローバル環境変数（`~/.michi/.env`）の利用も検討してください。
+
+詳細は [環境設定ガイド](configuration.md) を参照してください。
+
+## 初回確認
+
+事前チェックを実行して、設定が正しいことを確認します：
+
+```bash
+michi preflight
+```
+
+## 次のステップ
+
+- [環境設定の詳細](configuration.md) - JIRA Issue Type IDなどの詳細設定
+- [CLIコマンドリファレンス](../reference/cli.md) - 使用可能なコマンド一覧