@sk8metal/michi-cli 0.5.0 → 0.8.0

package/templates/claude/commands/michi/spec-impl.md

@@ -1,4 +1,4 @@
----
+/---
 name: /michi:spec-impl
 description: Execute spec tasks using TDD methodology with quality automation (Michi version)
 allowed-tools: Task, Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS, WebFetch, WebSearch
@@ -25,6 +25,8 @@ argument-hint: <feature-name> [task-numbers] [--mutation] [--skip-license] [--sk
 2. **自動修正ループ（Phase 2）**: type-check、lint、test を自動修正（最大5回）
 3. **事後品質レビュー（Phase 3）**: コードレビュー、デザインレビュー（Frontend時）
 4. **最終品質ゲート（Phase 4）**: カバレッジ95%、Mutation Testing（オプション）
+5. **タスク完了マーク（Phase 4.5）**: tasks.mdのチェックボックス更新
+6. **タスク完了後の処理（Phase 5）**: スペックのarchive移動を確認・実行
 
 ### コマンドシグネチャ
 
@@ -55,7 +57,7 @@ Phase 1: 事前品質監査（Michi拡張）
     └─ Frontend検出判定（並行）
     ↓
 Phase 2: TDD実装サイクル（kiro:spec-impl継承 + 自動修正ループ拡張）
-    RED → GREEN → REFACTOR → VERIFY（最大5回） → MARK
+    RED → GREEN → REFACTOR → VERIFY（最大5回）
     ↓
 Phase 3: 事後品質レビュー（Michi拡張）
     ├─ コードレビュー（常に）
@@ -63,6 +65,15 @@ Phase 3: 事後品質レビュー（Michi拡張）
     ↓
 Phase 4: 最終検証（Michi拡張）
     type-check + lint + test + coverage 95% + Mutation Testing（オプション）
+    ↓
+Phase 4.4: PRサイズチェック（Michi拡張）
+    500行超過時 → ユーザー確認 → PR作成
+    ↓
+Phase 4.5: タスク完了マーク（Michi拡張）
+    tasks.md のチェックボックス更新
+    ↓
+Phase 5: タスク完了後の処理（Michi拡張）
+    Archive確認 → ユーザー選択 → Archive実行 or スキップ
 ```
 
 ---
@@ -70,14 +81,13 @@ Phase 4: 最終検証（Michi拡張）
 ## Phase 1: 事前品質監査（Michi拡張）
 
 ### 目的
-実装前にライセンス・バージョンリスクを早期検出し、Critical問題を事前に解決。
+実装前にライセンス・バージョンリスクを早期検出し、Critical問題を解決する。
 
 ### 実行手順
 
 #### Step 1.1: オプション解析
 
 ```bash
-# コマンドライン引数を解析
 SKIP_LICENSE=false
 SKIP_VERSION=false
 SKIP_DESIGN=false
@@ -111,12 +121,12 @@ DESIGN_REVIEW_CRITICAL=0
 
 #### Step 1.2: サブエージェント並行起動
 
-**重要**: 以下の3つのタスクは独立しているため、**並行実行**してください。単一メッセージで複数のTaskツール呼び出しを行います。
+**重要**: 以下の3つのタスクは独立しているため、並行実行する。単一メッセージで複数のTaskツール呼び出しを行う。
 
 ```markdown
 ## サブエージェント並行起動（Phase 1）
 
-Phase 1では以下の3つのサブエージェントを**並行起動**します：
+Phase 1では以下の3つのサブエージェントを並行起動する：
 
 ### 1. oss-license-checker
 ```yaml
@@ -166,9 +176,6 @@ Task tool:
 
 ### 3. Frontend検出
 ```bash
-# 並行実行タスク:
-# ローカル検出ロジック（Task toolは使用せず、直接実行）
-
 # Frontend変更を検出
 FRONTEND_DETECTED=false
 
@@ -205,13 +212,6 @@ fi
 echo "Frontend detected: $FRONTEND_DETECTED"
 ```
 
-**並行実行の実装例**:
-```plaintext
-単一メッセージで以下を実行:
-- Task tool（oss-license-checker）
-- Task tool（stable-version-auditor）
-- Bash tool（Frontend検出）
-```
 
 #### Step 1.3: 結果集約とゲート判定
 
@@ -260,7 +260,32 @@ fi
 ## Phase 2: TDD実装サイクル（自動修正ループ拡張）
 
 ### 目的
-kiro:spec-implの基本TDDサイクルに、**自動修正ループ**を追加。
+kiro:spec-implの基本TDDサイクルに自動修正ループを追加する。
+
+### Step 2.1: RED - 失敗するテストを書く
+
+```markdown
+- 次の小さな機能のテストを書く
+- テストは失敗する（まだコードが存在しない）
+- 説明的なテスト名を使用する
+```
+
+### Step 2.2: GREEN - 最小限のコードを書く
+
+```markdown
+- テストを通過させる最もシンプルな実装を行う
+- このテストを通過させることだけに集中する
+- 過度な設計を避ける
+```
+
+### Step 2.3: REFACTOR - クリーンアップ
+
+```markdown
+- コード構造と可読性を改善する
+- 重複を削除する
+- 適切な設計パターンを適用する
+- リファクタリング後もすべてのテストが通過することを確認する
+```
 
 ### Step 2.4: VERIFY - 品質チェック（自動修正ループ）
 
@@ -308,24 +333,18 @@ while [ $ITERATION -lt $MAX_ITERATIONS ]; do
     # 自動修正を試行
     echo "⚙️  自動修正を試行します..."
 
-    # Lint修正
     if [ "$LINT_FAILED" = true ]; then
         echo "🔧 Lint自動修正を実行"
         npm run lint:fix
     fi
 
-    # 型エラー修正（簡易的な自動修正）
     if [ "$TYPE_CHECK_FAILED" = true ]; then
         echo "🔧 型エラーを分析中..."
-        # 型エラーログを分析して修正案を提示
-        # （実際の修正はAIによる判断が必要）
     fi
 
-    # テスト失敗修正（実装バグの可能性）
     if [ "$TEST_FAILED" = true ]; then
         echo "🔧 テスト失敗を分析中..."
-        # テストログを分析して修正案を提示
-        # ⚠️ 注意: テストは仕様。仕様変更の場合のみテストを修正
+        echo "⚠️  注意: テストは仕様。仕様変更の場合のみテストを修正"
     fi
 
     ITERATION=$((ITERATION + 1))
@@ -360,7 +379,7 @@ fi
 ## Phase 3: 事後品質レビュー（Michi拡張）
 
 ### 目的
-実装完了後、コードレビューとデザインレビュー（Frontend時）を実行。
+実装完了後、コードレビューとデザインレビュー（Frontend時）を実行する。
 
 ### Step 3.1: コードレビュー（常に実行）
 
@@ -458,12 +477,6 @@ while [ $REVIEW_ITERATION -lt $MAX_REVIEW_ITERATIONS ]; do
     # 自動修正を試行
     echo "⚙️  レビュー指摘事項を自動修正中..."
 
-    # コードレビュー指摘の修正
-    # （実際の修正はAIによる判断が必要）
-
-    # デザインレビュー指摘の修正
-    # （CSS、HTML、ARIA属性の修正）
-
     REVIEW_ITERATION=$((REVIEW_ITERATION + 1))
 done
 
@@ -491,7 +504,7 @@ fi
 ## Phase 4: 最終検証（Michi拡張）
 
 ### 目的
-全品質基準の最終確認。カバレッジ95%以上、Mutation Testing（オプション）。
+全品質基準を最終確認する。カバレッジ95%以上、Mutation Testing（オプション）を実施。
 
 ### Step 4.1: 品質チェック最終実行
 
@@ -545,7 +558,6 @@ case "$LANGUAGE" in
             exit 1
         fi
 
-        # JaCoCo coverage report parsing (堅牢な実装)
         if [ -f "build/reports/jacoco/test/jacocoTestReport.xml" ]; then
             COVERAGE=$(grep -oP '<counter type="LINE"\s+missed="\K[0-9]+|covered="\K[0-9]+' build/reports/jacoco/test/jacocoTestReport.xml | \
                 awk 'NR==1{m=$1} NR==2{c=$1} END {if(m+c>0) printf "%.1f", c*100/(m+c); else print 100}')
@@ -574,7 +586,6 @@ case "$LANGUAGE" in
             exit 1
         fi
 
-        # Clover XML coverage parsing (堅牢な実装)
         if [ -f "coverage/clover.xml" ]; then
             TOTAL_STATEMENTS=$(grep -oP '<metrics.*?statements="\K[0-9]+' coverage/clover.xml | awk '{sum+=$1} END {print sum}')
             COVERED_STATEMENTS=$(grep -oP '<metrics.*?coveredstatements="\K[0-9]+' coverage/clover.xml | awk '{sum+=$1} END {print sum}')
@@ -610,7 +621,6 @@ fi
 if [ "$MUTATION" = true ]; then
     echo "=== Mutation Testing ==="
 
-    # Step 4.1 で検出済みの $LANGUAGE 変数を再利用
     case "$LANGUAGE" in
         nodejs)
             echo "🔍 Node.js/TypeScript → Stryker"
@@ -685,6 +695,168 @@ echo "======================================"
 
 ---
 
+## Phase 4.4: PRサイズチェック（Michi拡張）
+
+### 目的
+レビュアビリティを確保するため、PRサイズを監視し、500行を超えた場合にPR分割を提案する。
+
+### Step 4.4.1: PRサイズ評価
+
+**重要**: このステップは品質チェック完了後、タスク完了マーク前に実行する。
+
+```markdown
+Task tool:
+  subagent_type: pr-size-monitor
+  prompt: |
+    現在の変更量を確認し、PRサイズを評価してください。
+
+    **機能名**: $1
+
+    **閾値**: 500行（追加+削除、除外ファイル除く）
+
+    **除外ファイル**:
+    - ロックファイル: package-lock.json, yarn.lock, pnpm-lock.yaml,
+      composer.lock, Gemfile.lock, poetry.lock, Cargo.lock, go.sum
+    - 自動生成: dist/*, build/*, coverage/*, .next/*, *.min.js, *.min.css
+
+    **実行手順**:
+    1. git diff --stat でベースブランチとの差分を取得
+    2. 除外ファイルを除いた行数を計算
+    3. 500行超過時:
+       - 現在の変更量を報告
+       - AskUserQuestionでPR作成を確認
+       - 同意があれば自動でPR作成（commit, push, gh pr create）
+       - 新しいブランチで残りの作業を継続
+    4. 500行未満: ✅ OK、Phase 4.5へ進行
+```
+
+**サブエージェント呼び出しの流れ**:
+
+```plaintext
+Phase 4.4 実行
+    ↓
+pr-size-monitor 起動
+    ↓
+変更量計測（500行超過？）
+    ├─ NO（500行未満）: ✅ OK → Phase 4.5へ
+    └─ YES（500行以上）:
+        ↓
+        AskUserQuestion（ユーザー確認）
+        ├─ A) PR作成する → commit → push → gh pr create → 新ブランチ提案
+        ├─ B) 作業続行 → 警告表示 → Phase 4.5へ
+        └─ C) 分割戦略提案 → 分割案表示 → 再度ユーザー確認
+```
+
+---
+
+## Phase 4.5: タスク完了マーク（Michi拡張）
+
+### 目的
+各タスク実装完了後、tasks.mdのチェックボックスを更新してタスクの進捗を記録する。
+
+### Step 4.5.1: MARK COMPLETE - tasks.md更新
+
+```bash
+# 品質チェックが成功したら、tasks.mdを更新
+echo "=== タスク完了をマーク ==="
+
+# tasks.mdのチェックボックスを更新
+# - [ ] タスク名 → - [x] タスク名
+TASK_FILE=".kiro/specs/$1/tasks.md"
+
+if [ -f "$TASK_FILE" ]; then
+    # 現在のタスク番号に対応する行を更新
+    # 例: "- [ ] 1.1 タスク説明" → "- [x] 1.1 タスク説明"
+    sed -i '' "s/- \[ \] $TASK_NUMBER/- [x] $TASK_NUMBER/" "$TASK_FILE"
+    echo "✅ tasks.md を更新しました: タスク $TASK_NUMBER を完了"
+else
+    echo "⚠️ tasks.mdが見つかりません: $TASK_FILE"
+fi
+```
+
+**重要**: タスクが完了したら、必ずtasks.mdのチェックボックスを更新する。
+- 未完了: `- [ ]`
+- 完了済: `- [x]`
+
+---
+
+## Phase 5: タスク完了後の処理（Michi拡張）
+
+### 目的
+すべてのタスクが完了した場合、スペックをarchiveに移動する。
+
+### Step 5.1: Archive確認とプロンプト
+
+```bash
+echo ""
+echo "======================================"
+echo " タスク完了確認"
+echo "======================================"
+echo ""
+echo "すべてのタスクが完了しました。"
+echo ""
+echo "次のアクション:"
+echo "A) スペックをarchiveに移動する（推奨）"
+echo "B) 追加のタスクを実行する"
+echo "C) 何もしない"
+echo ""
+
+# ユーザー確認
+# 注: AskUserQuestionツールが利用可能な場合は、そちらを優先使用すること
+read -p "どの対応を希望しますか? (A/B/C): " ARCHIVE_ACTION
+
+if [ "$ARCHIVE_ACTION" = "A" ]; then
+    echo "🗃️  スペックをarchiveに移動します..."
+    npx @sk8metal/michi-cli spec:archive $1
+
+    if [ $? -eq 0 ]; then
+        echo "✅ スペックをarchiveに移動しました"
+        echo ""
+        echo "Archive先: .kiro/specs/.archive/$1/"
+        echo "- spec.json"
+        echo "- requirements.md"
+        echo "- design.md"
+        echo "- tasks.md"
+        echo "- validation-reports/"
+    else
+        echo "❌ スペックのarchive移動に失敗しました"
+        echo "手動で実行する場合: npx @sk8metal/michi-cli spec:archive $1"
+    fi
+elif [ "$ARCHIVE_ACTION" = "B" ]; then
+    echo "✅ 追加のタスクを実行できます"
+    echo ""
+    echo "次のコマンドを実行してください:"
+    echo "/michi:spec-impl $1 [task-numbers]"
+else
+    echo "✅ スペックはそのままにしておきます"
+    echo ""
+    echo "後でarchiveする場合: npx @sk8metal/michi-cli spec:archive $1"
+fi
+```
+
+### Step 5.2: Archive後の推奨アクション（参考情報）
+
+```markdown
+スペックをarchiveに移動した後の推奨アクション:
+
+1. **ドキュメント更新**
+   - CHANGELOG.md に変更内容を記録
+   - README.md を必要に応じて更新
+
+2. **PR作成**
+   - 実装ブランチをmainにマージするPRを作成
+   - Phase Aテスト（unit, lint, build）を実行
+
+3. **リリース準備** (Phase B)
+   - 統合テスト、E2Eテスト、パフォーマンステスト、セキュリティテストを実行
+   - `/michi:confluence-sync` でリリース手順書を作成
+
+4. **次の機能開発**
+   - `/kiro:spec-init "description"` で新しいスペックを作成
+```
+
+---
+
 ## 安全性ルール
 
 ### 必須確認ケース
@@ -693,6 +865,7 @@ echo "======================================"
 2. **Phase 2で自動修正失敗時**: 最大5回試行後、ユーザー確認
 3. **Phase 3でレビュー失敗時**: 最大5回修正後、ユーザー確認
 4. **Phase 4でカバレッジ不足時**: 即時停止、ユーザー確認
+5. **Phase 5でArchive実行時**: 必ずユーザー確認、明示的な承認
 
 ### 禁止事項
 

package/templates/claude-agent/agents/doc-reviewer.md

@@ -0,0 +1,176 @@
+---
+name: doc-reviewer
+description: |
+  Markdown document quality reviewer for README, API specs, design documents,
+  and changelogs. Detects verbose expressions, missing sections, duplicates,
+  and formatting issues. Use for any .md file review.
+license: MIT
+metadata:
+  author: michi
+  version: "1.0"
+allowed-tools: Read Glob Grep
+model: haiku
+---
+
+# Document Reviewer Agent
+
+## Language
+
+All output should be in: **{{LANG_CODE}}**
+
+## Development Guidelines
+
+{{DEV_GUIDELINES}}
+
+## Role
+
+Markdown document quality reviewer.
+
+## Responsibilities
+
+- Document quality assessment based on predefined criteria
+- Detection of prohibited patterns (verbose expressions, redundancy, duplication)
+- Verification of required sections for each document type
+- Word count validation against guidelines
+- Providing actionable improvement suggestions
+
+## Review Criteria
+
+@.claude/rules/doc-review-rules.md
+
+## Review Workflow
+
+### 1. Document Type Detection
+
+Identify document type from filename or path:
+- `README.md` → README (30-50 lines)
+- `requirements.md` → Requirements Document (50-100 lines)
+- `design.md` → Design Document (50-100 lines)
+- `tasks.md` → Task List (checklist format)
+- `CHANGELOG.md` → Changelog (1-3 lines per item)
+- `docs/api/**/*.md` → API Specification (10-20 lines per feature)
+- Others → General Document (basic structure check only)
+
+### 2. Word Count Validation
+
+- Count lines in the document
+- Compare against guideline for document type
+- Determine: ✅ OK / ⚠️ Exceeds / ❌ Insufficient
+
+### 3. Prohibited Pattern Detection
+
+Detect the following patterns:
+- Verbose expressions: "〜することができます" → "〜できます"
+- Overuse of: "〜という", "〜のような"
+- Excessive background explanation
+- Duplicate content across sections
+- Broken links or invalid references
+- Heading hierarchy issues (skipping levels)
+
+### 3.5. Michi-Specific Checks
+
+For documents in `.kiro/specs/` directory:
+- **@-reference integrity**: Verify `@.claude/rules/...` paths exist and are valid
+- **Placeholder detection**: Check for unreplaced placeholders like `{{PLACEHOLDER}}`
+- **Phase compliance**: For `design.md`, verify Test Plan section exists (Phase 0.3-0.4)
+- **Project context**: Validate {{PROJECT_ID}}, {{KIRO_DIR}}, {{AGENT_DIR}} usage
+
+### 4. Required Section Verification
+
+Verify required sections based on document type:
+- **README**: Overview, Usage (installation/execution), License
+- **Requirements Document**: Background, Requirements List, Acceptance Criteria
+- **Design Document**: Purpose, Structure, Rationale (decision-making reasons)
+- **Design Document (Michi-specific)**: Test Plan section (Phase 0.3-0.4 compliance)
+- **Task List**: Task format with checkboxes (- [ ] or - [x])
+- **API Specification**: Endpoint, Parameters, Response format
+- **Changelog**: Version, Changes description
+
+### 5. Output Results
+
+Output review results in the format defined in doc-review-rules.md:
+- Visual indicators: ✅ / ⚠️ / ❌
+- Specific line numbers for issues
+- Actionable improvement suggestions
+
+## Project Context
+
+- Project ID: {{PROJECT_ID}}
+- Kiro directory: {{KIRO_DIR}}
+- Agent directory: {{AGENT_DIR}}
+
+## Constraints
+
+- Reviews are suggestions, not enforcement
+- Respect project-specific style guides
+- Human review remains essential
+
+## Usage Example
+
+When reviewing `.kiro/specs/{{FEATURE_NAME}}/requirements.md`:
+
+1. Read the file using Read tool
+2. Detect document type: Design Document (50-100 lines guideline)
+3. Count lines and compare
+4. Search for prohibited patterns using Grep
+5. Verify required sections: Purpose, Structure, Rationale
+6. Output structured review results
+
+## Output Format
+
+```markdown
+## Document Review Results: `<file-path>`
+
+### 📋 Document Type
+README / Requirements / Design / Task List / API Spec / Changelog / General
+
+### 📊 Word Count
+✅ OK (75 lines, target: 50-100 lines)
+⚠️ Exceeds (120 lines, target: 50-100 lines, recommend reducing by 20 lines)
+❌ Insufficient (25 lines, minimum 50 lines required, need 25 more lines)
+
+### 🔍 Prohibited Patterns
+✅ No issues found
+
+または
+
+⚠️ Verbose expressions: 2 locations
+  - L12: "利用することができます" → "利用できます"
+  - L35: "設定を行うことができます" → "設定できます"
+
+⚠️ Duplicate content: 1 location
+  - L45-48 and L120-123 contain identical information
+
+⚠️ Heading hierarchy: 1 issue
+  - L32: Skipped from h2 to h4 (should be h3)
+
+### 🔧 Michi-Specific Issues
+✅ No Michi-specific issues
+
+または
+
+⚠️ Placeholder found: 1 location
+  - L67: Unreplaced {{PROJECT_ID}}
+
+⚠️ @-reference invalid: 1 location
+  - L89: @.claude/rules/non-existent.md (file not found)
+
+❌ Missing Test Plan section (Phase 0.3-0.4 requirement for design.md)
+
+### ✅ Required Sections
+✅ All present
+  - Purpose
+  - Structure
+  - Rationale
+
+または
+
+❌ Missing required sections
+  - License information
+  - Installation instructions
+
+### 🎯 Overall Assessment
+✅ Pass - No issues found
+⚠️ Improvement recommended - Fix verbose expressions and placeholders
+❌ Fail - Missing required sections and Phase compliance
+```

package/templates/claude-agent/rules/doc-review-rules.md

@@ -0,0 +1,98 @@
+# Document Review Rules
+
+## 目的
+
+ドキュメント品質を自動的にチェックし、一貫性のある高品質なドキュメント作成を支援する。
+
+## 文量ガイドライン
+
+| ドキュメント種別 | 目安行数 | 必須セクション |
+|------------------|----------|----------------|
+| README | 30-50行 | 概要, 使い方, ライセンス |
+| API仕様 | 機能あたり10-20行 | エンドポイント, パラメータ, レスポンス |
+| 設計書 | 50-100行 | 目的, 構成, 判断理由 |
+| 変更履歴 | 項目あたり1-3行 | バージョン, 変更内容 |
+
+## 禁止パターン
+
+以下のパターンを検出した場合、修正を提案する：
+
+1. **冗長表現**
+   - 「〜することができます」 → 「〜できます」に修正
+   - 「〜という」「〜のような」の過剰な使用 → 削除
+
+2. **過剰な背景説明**
+   - 導入部での不必要な前置き
+   - 自明な内容の長い説明
+
+3. **自明なコードコメント転記**
+   - コードそのままの説明
+   - 変数名や関数名を繰り返すだけの説明
+
+4. **重複記載**
+   - 同じ情報が複数セクションに記載されている
+   - 情報は1箇所にのみ記載すべき
+
+## 必須セクション検証
+
+### README
+- [ ] 概要
+- [ ] 使い方（インストール・実行方法）
+- [ ] ライセンス
+
+### API仕様
+- [ ] エンドポイント
+- [ ] パラメータ
+- [ ] レスポンス
+
+### 設計書
+- [ ] 目的
+- [ ] 構成
+- [ ] 判断理由
+
+### 変更履歴
+- [ ] バージョン
+- [ ] 変更内容
+
+## レビュー結果出力形式
+
+```markdown
+## ドキュメントレビュー結果
+
+### 文量チェック
+✅ OK (45行) / ⚠️ 超過 (65行、目標50行以内) / ❌ 不足 (20行、最低30行必要)
+
+### 禁止パターンチェック
+✅ 問題なし
+
+または
+
+⚠️ 冗長表現: 3箇所
+  - L12: 「することができます」 → 「できます」
+  - L28: 「という」 → 削除を検討
+  - L35: 「することができます」 → 「できます」
+
+### 必須セクションチェック
+✅ すべて揃っています
+
+または
+
+❌ 必須セクション不足: ライセンス
+
+### 総合評価
+✅ 合格 / ⚠️ 改善推奨 / ❌ 不合格
+```
+
+## レビュー実行タイミング
+
+- Markdownファイル作成時
+- Markdownファイル編集完了時
+- 手動レビューコマンド実行時（`/doc:review`）
+
+## 適用除外
+
+以下のファイルはレビュー対象外：
+- `CHANGELOG.md` - 自動生成される場合
+- `node_modules/**/*.md` - 依存パッケージのドキュメント
+- `.git/**/*.md` - Git管理ファイル
+- `vendor/**/*.md` - サードパーティライブラリ