claude-alfred 0.3.9 → 0.3.11

package/README.ja.md

@@ -4,287 +4,165 @@
 [![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![MIT License](https://img.shields.io/github/license/hir4ta/claude-alfred)](https://github.com/hir4ta/claude-alfred/blob/main/LICENSE)
 
-Claude Code の開発執事。
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) の開発執事。仕様、記憶、レビュー — 全部自動。
 
-[English README](README.md)
-
-## 何が辛いのか
-
-Claude Code で開発してると、3つの壁にぶつかる。
-
-**忘れる。** Compact するたび、セッション切れるたび、全部消える。20分かけた設計判断、もう一回聞かれる。
-
-**行き当たりばったり。** 仕様もなく、計画もなく、ノリで実装。動くけど、壊れる。
-
-**誰もレビューしない。** コードがそのまま出ていく。バグは本番で見つかる。
-
-alfred は3つとも潰す。
+**他のツールは提案する。alfred は強制する。**
 
-## アプローチ
+[English README](README.md)
 
-alfred は**仕様駆動の開発フロー**を強制する。全タスクが同じ構造に従う。例外はない。
+## 30秒で分かる alfred
 
 ```
-Spec > Wave > Task
-```
-
-**Spec** はこれから作るものを記述するドキュメント群。**Wave** は関連タスクをレビュー可能な塊にまとめたもの。**Task** は1つの作業単位。
-
-フローはこう進む。
-
-1. **Spec を作る** — 要件、設計、タスク、テスト仕様
-2. **セルフレビュー** — 3つの AI エージェントがアーキテクチャを議論する（S サイズ含む全サイズ）
-3. **承認を得る** — ブラウザダッシュボードでレビュー、任意の行にコメント（M/L/XL）
-4. **Wave ごとに実装** — 各 Wave 完了後にコミット、セルフレビュー、学びを保存
-5. **クローズ** — 最終レビューして `dossier complete`
-
-これは提案じゃない。Hook が強制する。Spec なしでコードを書こうとするとブロックされる。Wave レビューをスキップすると Edit/Write が使えなくなる。
-
-## 何ができるか
-
-### 消えない仕様
-
-要件、設計、決定、セッション状態 — 構造化された Markdown が Compact を跨いで生き残る。コンテキストは失われない。タスクの大きさに合わせてファイル数が変わる。バグ修正なら3ファイル、大規模機能なら6ファイル。
-
-### 積み重なる記憶
-
-「あの時こう決めた」「このバグ前にも見た」「X は試したけどダメだった」— 全てが `.alfred/knowledge/` に構造化 JSON として保存される。3分類のみ: **decision**、**pattern**、**rule**。Git フレンドリーで、チームで共有できる。矛盾は自動検出。次に似た問題に当たったとき、聞く前に alfred が出してくる。
-
-### ドリフトしない仕様
-
-コミットの度に、変更ファイルを Spec と照合。設計書にないコンポーネントを変更した？ 警告。メモリに保存した規約がコードと合わなくなった？ フラグ。
-
-### スケールするレビュー
-
-6つのレビュープロファイル（code, config, security, docs, architecture, testing）、それぞれにチェックリスト。並列エージェント、スコア付きレポート、具体的な修正案。
-
-### バイパスできない承認ゲート
-
-3層の enforcement で守る。
-- **Review gate** が spec/wave レビュー完了まで Edit/Write をブロック
-- **Approval gate** が未承認 M/L/XL をブロック
-- **Intent guard** が spec なし実装をブロック
-
-ステータスの手動書き換えでは突破できない。レビュー JSON ファイルの存在も検証する。
-
-### 能動的スキル提案
-
-調査中か、実装中か、バグ修正中か、PR マージ直後か、大きな PDF を読んでいるか — alfred が状況を検知して、適切なスキルを提案する。コマンドを覚える必要はない。
-
-### 日英切り替え対応のダッシュボード
+あなた: 「ユーザー認証を追加して」
 
-`localhost:7575` でリアルタイムにプロジェクト状態を確認。タスク進捗、ナレッジ健全性、アクティビティ。ワンクリックで日本語・英語を切り替え。設定はブラウザに保存される。
+alfred: spec を作成（要件 + 設計 + タスク）→
+        3つのエージェントがアーキテクチャを議論 →
+        ブラウザダッシュボードで承認 →
+        Wave ごとに実装、都度コミット＋レビュー →
+        学んだことを次回のために保存
+```
 
-## セットアップ
+何を作るか言うだけ。あとは alfred がやる。
 
-### 1. インストール
+## はじめる
 
 ```bash
 npm install -g claude-alfred
 ```
 
-SQLite データベースとユーザールールが自動セットアップされる。`alfred doctor` で確認。
-
-### 2. プラグイン
-
-Claude Code 内で:
+Claude Code で:
 
 ```
 /plugin marketplace add hir4ta/claude-alfred
 /plugin install alfred
+/init    # "alfred" を選択 — ステアリングドキュメント + ナレッジインデックスをセットアップ
 ```
 
-### 3. 環境変数
-
-`~/.zshrc` に追加:
-
-```bash
-export VOYAGE_API_KEY=your-key  # セマンティック検索が有効に（1セッション約$0.01）
-export ALFRED_LANG=ja           # 出力言語 (en/ja/zh/ko/fr/de/es/pt...)
-```
-
-Voyage のキーがなくても動く。FTS5 全文検索がフォールバックする。
+任意: `~/.zshrc` に `export VOYAGE_API_KEY=your-key` を追加するとセマンティック検索が有効に（1セッション約$0.01）。なくても FTS5 全文検索で動く。
 
-### 4. プロジェクトセットアップ
+## 何が違うのか
 
-Claude Code 内で、プロジェクトルートから:
+多くの spec ツールは「先に仕様を書いた方がいいですよ」と slash command で提案する。alfred は Claude Code の Hook システムで Edit/Write を**物理的にブロック**する。提案ではなく、ツールレベルでの強制 — それが根本的な違い。
 
-```
-/init    <- 候補から "alfred" を選択
-```
+**提案ではなく強制。** 3層のゲートがコード編集を制御する。spec なしの実装を防ぐインテントガード。前の Wave をレビューするまで次を止めるレビューゲート。ダッシュボードで人間が承認するまで M/L/XL の実装を止める承認ゲート。YAML を手で書き換えてもダメ — 署名済みレビューファイルまで検証する。
 
-ステアリングドキュメント、テンプレート、ナレッジインデックスを生成する。
+**記憶が育つ。** 「あの時なぜこう決めた」「このパターンは前もうまくいった」「X は試してダメだった」— `.alfred/knowledge/` に JSON で残る。15回以上検索ヒットしたパターンはルールに自動昇格。知識タイプごとに半減期が違う — ルールは120日、仮定は30日で鮮度が落ちる。矛盾は自動検出。Git に入れてチームで共有できる。次に似た状況が来たら、聞く前に出てくる。
 
-> **注意**: `/alfred:init` ではなく `/init` (短縮形) を使うこと。Claude Code の補完が `alfred:` プレフィックスを別スキルに誤ルーティングする場合がある。全スキル共通で `/brief`, `/attend`, `/mend` のように短縮形を推奨。
+**仕様がズレたら教えてくれる。** コミットの度に変更を設計ドキュメントと照合。spec にないコンポーネントを触ったら警告が飛ぶ。新しいソースファイルは該当コンポーネントのセクションに自動追記 — 手動で spec を更新する必要はない。
 
-## アップデート
+**コンテキストが適応する。** プロジェクトの成熟度に応じて注入量を調整する。新しいプロジェクトにはセッション開始時に spec 全体を注入。20件以上のナレッジがあるプロジェクトには現在のタスクとゴールだけ — コンテキストを膨らませない。
 
-両方を一緒に更新する。
+**スキルが勝手に出てくる。** 調べものしてたら `/brief` を提案。バグ直してたら `/mend`。PR マージしたら `/harvest`。覚えなくていい — 意図をセマンティック or キーワードで分類（日英バイリンガル）して、適切なスキルを出す。
 
-```bash
-npm update -g claude-alfred        # CLI、hooks、MCP サーバー、ダッシュボード
-```
-
-```
-/plugin update alfred              # skills、agents、rules（Claude Code 内で）
-```
-
-`alfred doctor` でバージョンの一致を確認できる。
+**ダッシュボードが使える。** `alfred dashboard` で `localhost:7575` が開く。タスク進捗、行レベルコメント付きレビュー、ファイル単位の承認、ナレッジの健全性、操作履歴。日英ワンクリック切替。
 
 ## スキル
 
-### コアワークフロー
-
-| スキル | やること |
+| スキル | ひとこと |
 |--------|----------|
-| `/alfred:brief` | Spec を生成。3エージェントがアーキテクチャを議論し、ダッシュボードで承認する |
-| `/alfred:attend` | 全自動。Spec 作成 → 承認ゲート → Wave ごとの実装 → レビュー → コミットまで放置でOK |
-| `/alfred:tdd` | テスト駆動開発。red → green → refactor のサイクルを自律的に回す |
-| `/alfred:mend` | バグ修正。再現 → 原因特定（過去バグの記憶も使う）→ 修正 → 検証 → コミット |
-| `/alfred:inspect` | 6プロファイル並列レビュー（code, config, security, docs, architecture, testing）。スコア付き |
-
-### 探索と設計
-
-| スキル | やること |
-|--------|----------|
-| `/alfred:survey` | 既存コードから Spec をリバースエンジニアリング。信頼度スコア付き |
-| `/alfred:salon` | ブレスト。3人の専門家が並列でアイデアを出して、トレードオフを議論する |
-| `/alfred:harvest` | PR レビューコメントからナレッジを抽出して永続メモリに保存 |
+| `/alfred:attend` | 全自動。spec → 承認 → 実装 → レビュー → コミット。放置でOK |
+| `/alfred:brief` | spec を生成。3エージェントがアーキテクチャを議論、ダッシュボードで承認 |
+| `/alfred:mend` | バグ修正。再現 → 原因特定（過去バグの記憶も使う）→ 修正 → 検証 |
+| `/alfred:tdd` | テスト駆動。red → green → refactor。パターンをセッション越しに記憶 |
+| `/alfred:inspect` | 6プロファイル並列レビュー。スコア付き |
+| `/alfred:survey` | 既存コードから spec をリバースエンジニアリング。信頼度スコア付き |
+| `/alfred:salon` | ブレスト。3人の専門家が並列で出して、トレードオフを議論 |
+| `/alfred:harvest` | PR レビューコメントからナレッジを抽出して永続化 |
 | `/alfred:archive` | 参照資料（PDF, CSV, 大きなテキスト）を検索可能なナレッジに変換 |
+| `/alfred:init` | プロジェクト初期化。マルチエージェントで探索 → ステアリングドキュメント生成 |
 
-### セットアップと保守
-
-| スキル | やること |
-|--------|----------|
-| `/alfred:init` | プロジェクト初期化。マルチエージェントでコードベースを探索し、ステアリングドキュメントを生成 |
-
-## MCP ツール
-
-| ツール | 役割 |
-|--------|------|
-| `dossier` | Spec のライフサイクル管理 — init, update, status, switch, complete, delete, history, rollback, review, validate, gate |
-| `roster` | エピック管理 — タスクのグループ化、依存関係、Spec 横断の進捗追跡 |
-| `ledger` | ナレッジ — search, save (decision/pattern/rule), promote (pattern → rule), reflect, audit-conventions |
-
-## Hook
-
-全自動。触らなくていい。
-
-| イベント | 動作 |
-|----------|------|
-| SessionStart | Spec コンテキスト復元、ナレッジ同期、セットアップ提案（`/alfred:init`） |
-| UserPromptSubmit | セマンティック検索 + スキル提案 + Spec enforcement（Spec なし実装ブロック、未承認 M/L/XL ブロック） |
-| PreToolUse | 3層 enforcement — review gate, intent guard, approval gate。ゲートが有効な間は Edit/Write をブロック |
-| PostToolUse | tasks.md / session.md の進捗自動更新。Wave 完了検知とレビューゲート設定。コミット後のドリフト検出。PR マージ後の `/alfred:harvest` 提案、大きな参照ファイル読み込み時の `/alfred:archive` 提案 |
-| PreCompact | セッションスナップショット保存、決定抽出、エピック進捗同期 |
-| Stop | review gate → ブロック。その他 → コンテキストリマインド（ブロックなし） |
-
-## ブラウザダッシュボード
+## 仕組み
 
-```bash
-alfred dashboard              # ブラウザで localhost:7575 を開く
-alfred dashboard --port 8080  # ポート指定
-alfred dashboard --url-only   # URLだけ出力
 ```
-
-4つのタブ: **Overview**（プロジェクト健全性、タスク進捗、メモリ統計）、**Tasks**（Spec の詳細表示、折りたたみセクション、インラインレビュー）、**Knowledge**（メモリの検索・閲覧、有効/無効切り替え）、**Activity**（操作タイムラインとフィルタ）。
-
-**日本語/英語のワンクリック切り替え**対応。設定はセッションを跨いで保持。
-
-着手中のタスクがシマーで光る。何が進行中か、一目でわかる。
-
-開発用: `ALFRED_DEV=1 alfred dashboard` + `task dev`（web/ 内）で Vite HMR が使える。
-
-## Steering 文書
-
-プロジェクトレベルのコンテキストを全 Spec に注入する。
-
-```bash
-/alfred:init
+あなた
+  |-- /alfred:brief    -> spec + 3エージェント議論 + ダッシュボード承認
+  |-- /alfred:attend   -> spec → 承認 → 実装（Wave ごと）→ レビュー → コミット
+  |-- /alfred:mend     -> 再現 → 原因分析（+ 過去バグ記憶）→ 修正 → 検証
+  v
+Hook（見えない）
+  |-- SessionStart     -> コンテキスト復元、ナレッジ同期
+  |-- UserPromptSubmit -> セマンティック検索 + スキル提案 + spec enforcement
+  |-- PreToolUse       -> review gate + intent guard + approval gate（3層）
+  |-- PostToolUse      -> 進捗自動更新、ステータス自動遷移、ドリフト検出
+  |-- PreCompact       -> タスクスナップショット、決定抽出、エピック進捗
+  |-- Stop             -> review gate ブロック + リマインド
+  v
+ストレージ
+  |-- .alfred/knowledge/   -> JSON（decisions/, patterns/, rules/）— ソースオブトゥルース
+  |-- .alfred/specs/       -> spec ファイル + バージョン履歴 + レビュー
+  |-- .alfred/epics/       -> エピック YAML + 依存関係
+  |-- .alfred/steering/    -> プロジェクトコンテキスト（product, structure, tech）
+  +-- ~/.claude-alfred/    -> SQLite 検索インデックス（再構築可能）
 ```
 
-`.alfred/steering/` に3ファイルを作成する。
-- `product.md` — プロジェクトの目的、対象ユーザー、スコープ境界
-- `structure.md` — パッケージ構成、モジュール境界、命名規約
-- `tech.md` — 技術スタック、依存関係、アーキテクチャ判断
-
-3ファイル全てが `dossier init` 時に読み込まれ、コンテキストとして注入される。AI は常にアーキテクチャを理解している。
-
-## 検索パイプライン
-
-3段階で、順にフォールバックする。
-
-1. **Voyage AI ベクトル検索** + リランキング（API キーがあるとき）
-2. **FTS5 全文検索** — タグエイリアス展開 + ファジーマッチ付き
-3. **キーワードフォールバック**（LIKE クエリ）
+## MCP ツール
 
-タグエイリアスが検索を自動拡張する。「auth」で「authentication」「login」「認証」もヒット。ファジーマッチがタイポを吸収する。
+| ツール | 管理対象 |
+|--------|----------|
+| `dossier` | spec ライフサイクル — init, update, complete, defer, cancel, review, gate など |
+| `roster` | エピック — タスクのグループ化、依存関係、spec 横断の進捗追跡 |
+| `ledger` | ナレッジ — 検索、保存、パターン → ルール昇格、ヘルスレポート |
 
-## ナレッジアーキテクチャ
+## ナレッジ
 
-ナレッジはプロジェクトディレクトリ内の構造化 JSON ファイル。3分類、曖昧さゼロ。
+JSON ファイルとして Git にコミットし、PR でレビューし、チームで共有できる。
 
 ```
 .alfred/knowledge/
-├── decisions/    # 一回きりの選択 + 理由 + 却下した代替案
-├── patterns/     # 繰り返し実践 + 適用条件 + 期待結果
-└── rules/        # 強制ルール + 優先度 + 根拠
+  decisions/    # 「X を選んだ。理由は Y。Z は却下」
+  patterns/     # 「A のとき B をやる。C が期待結果」
+  rules/        # 「常に X する。優先度: P0。根拠: Y」
 ```
 
-スキーマは厳密（[mneme](https://github.com/hir4ta/mneme) 互換）。テンプレート化されたパラメータで保存するので、セッション間のフォーマット揺れはゼロ。
+スキーマ厳密（[mneme](https://github.com/hir4ta/mneme) 互換）。15回以上検索ヒットしたパターンはルールに自動昇格。矛盾は自動検出。
 
-Git フレンドリー（コミットしてチームと共有、PR でレビュー）。アトミック書き込み（temp + rename）。再構築可能（SQLite インデックスを消しても次のセッションで再生成）。パターンは検索ヒット15回以上でルールに自動昇格。矛盾は自動検出。
+検索パイプライン: Voyage AI ベクトル + リランキング > FTS5 ファジーマッチ > キーワードフォールバック。「auth」で「authentication」「login」「認証」もヒット。
 
-## 適応的スペック
-
-全タスクに6ファイルは要らない。
+## spec サイズ
 
 | サイズ | ファイル数 | 用途 |
 |--------|-----------|------|
-| **S** | 3 (requirements, tasks, session) | バグ修正、設定変更、小さな変更 |
-| **M** | 5 (+ design, test-specs) | 新エンドポイント、リファクタ、中規模機能 |
-| **L/XL** | 6 (+ research) | アーキテクチャ変更、新サブシステム |
-| **D** (delta) | 2 (delta.md + session) | 既存コードへのブラウンフィールド変更 |
-| **Bugfix** | 3-4 (bugfix.md, tasks, session, +test-specs) | 再現手順付きバグ修正 |
+| **S** | 2 | バグ修正、設定変更 |
+| **M** | 4 | 新エンドポイント、リファクタ |
+| **L/XL** | 5 | アーキテクチャ変更、新サブシステム |
+| **D** | 1 | 既存コードへの差分変更 |
 
-サイズは説明文から自動判定、または `dossier action=init size=S` で明示指定。
+## アップデート
 
-## 仕組み
+```bash
+npm install -g claude-alfred        # CLI、hooks、MCP サーバー、ダッシュボード
+```
 
 ```
-あなた
-  |
-  |-- /alfred:brief    -> Spec + 3エージェント議論 + ダッシュボード承認
-  |-- /alfred:attend   -> Spec → 承認 → 実装（Wave ごと）→ レビュー → コミット
-  |-- /alfred:mend     -> 再現 → 原因分析（+ 過去バグ記憶）→ 修正 → 検証
-  |
-  v
-Hook（見えない）
-  |-- SessionStart     -> コンテキスト復元、ナレッジ同期、セットアップ提案
-  |-- UserPromptSubmit -> ベクトル検索 + スキル提案 + Spec enforcement
-  |-- PreToolUse       -> review gate + intent guard + approval gate（3層）
-  |-- PostToolUse      -> 進捗自動更新、Wave ゲート、ドリフト検出
-  |-- PreCompact       -> スナップショット、決定抽出、エピック進捗
-  |-- Stop             -> review gate ブロック + リマインド
-  |
-  v
-ストレージ
-  |-- .alfred/knowledge/   -> JSON（decisions/, patterns/, rules/）— 真のソース
-  |-- .alfred/specs/       -> Spec ファイル + バージョン履歴 + レビュー
-  |-- .alfred/epics/       -> エピック YAML + タスク依存関係
-  |-- .alfred/steering/    -> プロジェクトコンテキスト（product, structure, tech）
-  +-- ~/.claude-alfred/    -> SQLite 検索インデックス（再構築可能）
+/plugin update alfred              # skills、agents、rules（Claude Code 内で）
 ```
 
+`alfred doctor` で同期を確認。
+
 ## トラブルシューティング
 
 | 症状 | 対処 |
 |------|------|
-| メモリ検索で結果が出ない | `VOYAGE_API_KEY` を設定、または FTS5 フォールバックの動作確認 |
-| 出力が意図しない言語 | `ALFRED_LANG=ja`（または `en`, `zh` 等）を `~/.zshrc` に追加 |
+| メモリ検索で結果が出ない | `VOYAGE_API_KEY` を設定、または FTS5 の動作確認 |
+| 意図しない言語 | `export ALFRED_LANG=ja` を `~/.zshrc` に追加 |
 | Hook が動かない | `/plugin install alfred` して Claude Code を再起動 |
-| ダッシュボードが空 | `.alfred/specs/` があるディレクトリで `alfred dashboard` を実行 |
-| レート制限エラー | 対策済み。エージェントは段階的バッチ起動（最大2並列） |
+| ダッシュボードが空 | `.alfred/specs/` があるディレクトリで実行 |
+
+## アンインストール
+
+Claude Code で:
+
+```
+/plugin    # alfred を選択 → marketplace から削除（プラグインも一緒に消える）
+```
+
+```bash
+npm uninstall -g claude-alfred
+rm -rf ~/.claude-alfred/                          # SQLite 検索インデックス
+rm -f ~/.claude/rules/alfred.md                   # ユーザールール
+rm -rf ~/.claude/plugins/cache/claude-alfred/      # プラグインキャッシュ
+rm -rf .alfred/                                    # プロジェクトの spec、ナレッジ、ステアリング（プロジェクトごと）
+```
 
 ## ライセンス