claude-alfred 0.1.0

package/README.ja.md

@@ -0,0 +1,283 @@
+# alfred
+
+[![Version](https://img.shields.io/npm/v/claude-alfred)](https://www.npmjs.com/package/claude-alfred)
+[![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 の開発執事。
+
+[English README](README.md)
+
+## 何が辛いのか
+
+Claude Code で開発してると、こうなる:
+
+- **忘れる。** Compact するたび、セッション切れるたび、全部消える。20分かけた設計判断、もう一回聞かれる。
+- **行き当たりばったり。** 仕様もなく、計画もなく、ノリで実装。動くけど、壊れる。
+- **誰もレビューしない。** コードがそのまま出ていく。バグは本番で見つかる。
+
+alfred は3つとも潰す。
+
+## 何ができるか
+
+**消えない仕様。** 要件、設計、決定、セッション状態 — 構造化されたMarkdownファイルが Compact を跨いで生き残る。コンテキストは一度も失われない。
+
+**適応する仕様。** 小さなバグ修正なら3ファイル。中規模なら5。大規模なら7。タスクに応じてスペックの深さを自動調整。bugfix専用テンプレート（再現手順、原因分析、修正戦略）も。
+
+**積み重なる記憶。** 「あの時こう決めた」「このバグ前にも見た」「Xは試したけどダメだった」— 全てが `.alfred/knowledge/` にMarkdownファイルとして保存される。Git フレンドリーで、人間が読めて、チームで共有できる。SQLite検索インデックスがセマンティック検索を提供。矛盾は自動検出。次に似た問題に当たったとき、聞く前に alfred が出してくる。
+
+**信頼性シグナル。** 仕様の全項目にgrounding level（`verified`/`reviewed`/`inferred`/`speculative`）が付く。どの要件が実証済みで、どれが推測なのか一目でわかる。typoも検出する。
+
+**ブラウンフィールド対応。** 既存コード変更用のdelta specに`CHG-N`変更IDとBefore/After行動差分を追加。「どのファイルが変わった」だけでなく「どの振る舞いがなぜ変わった」まで追跡。3つの新バリデーションチェック付き。
+
+**ドリフトしない仕様。** コミットの度に、変更ファイルをスペックと照合。設計書にないコンポーネントを変更した？警告。メモリに保存したコーディング規約がコードと合わなくなった？フラグ。これをやるツールは他にない。
+
+**スケールするレビュー。** 6つのレビュープロファイル（code, config, security, docs, architecture, testing）、それぞれにチェックリスト。並列エージェント、スコア付きレポート、具体的な修正案。
+
+**能動的スキル提案。** alfred は呼ばれるのを待たない。調査中か、設計中か、実装中か、バグ修正中かを検出し、適切なタイミングで適切なスキルを提案する。コードを探索し続けてる？「`/alfred:survey` 使ったら？」。調査結果が出た？「`ledger` に保存しよう」。タスクが溜まってきた？「`roster` でまとめよう」。
+
+**バイパスできない承認ゲート。** 実装前に仕様のレビューサイクルを回す。ブラウザダッシュボードで任意の行にコメントして、承認か差し戻し — GitHub の PR レビューと同じ体験を、仕様に対してやる。ステータスの手動書き換えでは突破できない。レビューファイルの存在まで検証する。
+
+**張り付くプロジェクトコンテキスト。** Steering文書（プロダクトの目的、コード構造、技術スタック）がプロジェクトから自動生成され、すべての仕様に注入される。AIは常にアーキテクチャを理解している。
+
+## セットアップ
+
+### 1. インストール
+
+```bash
+npm install -g claude-alfred
+```
+
+SQLite データベースとユーザールールが自動セットアップされる。確認:
+
+```bash
+alfred doctor
+```
+
+### 2. プラグイン
+
+Claude Code 内で:
+
+```
+/plugin marketplace add hir4ta/claude-alfred
+/plugin install 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 全文検索がフォールバックする。
+
+### 4. プロジェクトセットアップ
+
+Claude Code 内で、プロジェクトルートから:
+
+```
+/init    ← 候補から "alfred" を選択
+```
+
+ステアリングドキュメント、テンプレート、ナレッジインデックスを生成する。
+
+> **注意**: `/alfred:init` ではなく `/init` (短縮形) を使うこと。Claude Code の補完が `alfred:` プレフィックスを別スキルに誤ルーティングする場合がある。全 alfred スキル共通: `/brief`, `/attend`, `/mend` のように短縮形を推奨。
+
+## アップデート
+
+両方を一緒に更新する:
+
+```bash
+npm update -g claude-alfred        # CLI、hooks、MCP サーバー、ダッシュボード
+```
+
+```
+/plugin update alfred              # skills、agents、rules（Claude Code 内で）
+```
+
+`alfred doctor` でバージョンの一致を確認できる。
+
+## スキル
+
+| スキル | やること |
+|--------|----------|
+| `/alfred:brief` | 仕様を設計する。3エージェントがアーキテクチャを議論し、ダッシュボードで承認する |
+| `/alfred:attend` | 全自動。仕様→レビュー→承認→実装→テスト→コミットまで放置でOK |
+| `/alfred:tdd` | テスト駆動。red→green→refactor を自律サイクルで回す。テストパターンも記憶する |
+| `/alfred:inspect` | 品質ゲート。6プロファイル並列レビュー、スコア付きレポート |
+| `/alfred:mend` | バグ修正。再現→原因特定（過去のバグ記憶も使う）→修正→検証→コミット |
+| `/alfred:survey` | 既存コードから仕様をリバースエンジニアリング。信頼度スコア付き |
+| `/alfred:salon` | ブレスト。3人の専門家が並列でアイデアを出して、議論する |
+| `/alfred:harvest` | PR レビューコメントからナレッジを抽出して永続メモリに保存 |
+| `/alfred:furnish` | 設定ファイルの作成・ブラッシュアップ |
+| `/alfred:quarters` | プロジェクト全体のセットアップウィザード |
+| `/alfred:archive` | 参照資料を検索可能なナレッジに変換 |
+| `/alfred:concierge` | 全機能のクイックリファレンス |
+
+## MCP ツール
+
+| ツール | 役割 |
+|--------|------|
+| `dossier` | 仕様のライフサイクル管理 — init（サイズ/タイプ指定可）, update, status, switch, complete, delete, history, rollback, review, validate |
+| `roster` | エピック管理 — タスクのグループ化、依存関係、進捗追跡 |
+| `ledger` | ナレッジ — search, save（Markdown+frontmatter）, promote, reflect, audit-conventions |
+
+## Hook
+
+全自動。触らなくていい。
+
+| イベント | 動作 |
+|----------|------|
+| SessionStart | 仕様コンテキスト復元 + CLAUDE.md 取込 + プロジェクト成熟度に応じた注入量調整 + ナレッジ健康チェック提案 |
+| PreCompact | 決定抽出 → 構造化チャプターメモリ (Markdown) 保存 → エピック進捗同期 → 調査パターン検出・保存リマインド |
+| UserPromptSubmit | セマンティック検索 + ファイルコンテキストブースト + **スキルナッジ**（意図検出 → 適切なスキル提案）|
+| PostToolUse | Bash エラー検出 → 過去の修正を検索。コミット後: スペックドリフト検出。Read/Grep 5回以上: survey 提案 |
+
+## ブラウザダッシュボード
+
+```bash
+alfred dashboard              # ブラウザで localhost:7575 を開く
+alfred dashboard --port 8080  # ポート指定
+alfred dashboard --url-only   # URLだけ出力
+```
+
+| タブ | 表示内容 |
+|------|----------|
+| **Overview** | プロジェクトの健康状態 — タスク進捗とバリデーション結果、メモリ健康度（陳腐化数・矛盾数）、仕様の信頼度分布、エピック進捗、最近の意思決定 |
+| **Tasks** | タスクカード: 現在のフォーカス、次のアクション、エピック、バリデーションバッジ。仕様ファイルの閲覧。Review タブでインラインコメント |
+| **Knowledge** | メモリ一覧（サブタイプ別タグ付き）。セマンティック検索（Voyage AI、300msデバウンス）。ローカルテキストフィルタ。メモリの有効/無効切り替え |
+| **Activity** | 操作タイムライン。イベントタイプ別フィルタ（init/complete/review）。エピックドリルダウン |
+
+インラインレビュー: 仕様ファイルを選択し、Review タブに切り替え。特定の行にコメントして、レビューラウンドを切り替えて、承認または差し戻し — ブラウザで完結。
+
+着手中のタスクがシマーで光る。何が進行中か、一目でわかる。
+
+開発用: `ALFRED_DEV=1 alfred dashboard` + `task dev`（web/ 内）で Vite HMR が使える。
+
+## 検索パイプライン
+
+キーワードマッチだけじゃない。3段階の検索パイプライン:
+
+1. **Voyage AI ベクトル検索** + リランキング（API キーがあるとき）
+2. **FTS5 全文検索** — タグエイリアス展開 + ファジーマッチ付き
+3. **キーワードフォールバック**（LIKE クエリ）
+
+タグエイリアスが検索を自動拡張する: 「auth」で「authentication」「login」「認証」もヒットする。
+
+ファジーマッチがタイポを吸収する:「authetication」でも「authentication」が見つかる。
+
+## ナレッジアーキテクチャ
+
+ナレッジはYAMLフロントマター付きのMarkdownファイルとして保存される。真のソースはプロジェクトディレクトリにあり、バイナリDBではない。
+
+```
+.alfred/knowledge/
+├── decisions/dec-auth-jwt.md    # 設計判断
+├── patterns/pat-error-handling.md  # 再利用パターン
+└── rules/rul-no-mock-db.md     # 強制ルール
+```
+
+- **Git フレンドリー**: ナレッジをコミットしてチームと共有、PRでレビュー
+- **人間が読める**: `cat` するだけで alfred が何を知っているか確認できる
+- **再構築可能**: SQLite検索インデックスはこれらのファイルから派生 — DB を削除しても次のセッションで再構築される
+- **サブタイプ減衰**: 仮定は30日で腐る。実証されたルールは120日持つ。メモリの種類ごとに半減期が違う。
+- **矛盾検出**: 2つのエントリが矛盾していたら（「JWT使え」vs「JWT避けろ」）、自動でフラグ。
+- **プロジェクト紐付け**: ナレッジは git リモートURLとブランチでタグ付けされ、プロジェクト横断検索が可能。
+
+## 適応的スペック
+
+全タスクに7ファイルは要らない。
+
+| サイズ | 生成ファイル | 用途 |
+|--------|------------|------|
+| **S** | 3: requirements, tasks, session | バグ修正、設定変更、小さな変更 |
+| **M** | 5: + design, test-specs | 新エンドポイント、リファクタ、中規模機能 |
+| **L/XL** | 7: + decisions, research | アーキテクチャ変更、新サブシステム |
+| **D** (delta) | 2: delta.md（CHG-N ID + Before/After付き）, session | 既存コードへのブラウンフィールド変更 |
+| **Bugfix** | 3-4: bugfix.md, tasks, session (+test-specs) | 外科的バグ修正（再現手順付き） |
+
+サイズは説明文から自動判定、または明示指定: `dossier action=init size=S`
+
+## スペック検証
+
+`dossier action=validate` で22項目の段階的チェック:
+
+- 必須セクション（Goal、Functional Requirements 等）の存在
+- サイズ別最小FR数（S: 1+, M: 3+, L: 5+）
+- トレーサビリティ完全性（全FR→タスク、全タスク→FRの双方向）
+- confidence + grounding annotation の存在
+- Closing Wave の存在
+- Grounding coverage — opt-in: speculative が30%超で失敗（L/XL）
+- Delta spec品質 — Files Affected に CHG-N ID、Before/After セクションの実質的内容
+
+## Steering 文書
+
+プロジェクトレベルのコンテキストを全仕様に注入:
+
+```bash
+/alfred:init
+```
+
+`.alfred/steering/` に作成:
+- `product.md` — プロジェクトの目的、対象ユーザー、ビジネスルール
+- `structure.md` — パッケージ構成、モジュール境界、命名規約
+- `tech.md` — 技術スタック、依存関係、API規約
+
+`dossier init` 時に読み込まれ、コンテキストとして注入。仕様は常にプロジェクトを理解している。
+
+## 仕組み
+
+```
+あなた
+  |
+  |-- /alfred:brief    -> 仕様 + 3エージェント議論 + ダッシュボード承認
+  |-- /alfred:attend   -> 全自動: 仕様 → 承認 → 実装 → レビュー → コミット
+  |-- /alfred:mend     -> 再現 → 原因分析（＋過去バグ記憶）→ 修正 → 検証
+  |
+  v
+Hook（見えない）
+  |-- SessionStart     -> コンテキスト復元、プロジェクト成熟度に適応
+  |-- PreCompact       -> 決定をMarkdown保存、チャプターメモリ、エピック進捗
+  |-- UserPromptSubmit -> ベクトル検索 + FTS5 + ファイルブースト → メモリ注入
+  |-- PostToolUse      -> エラー検出 → 関連する過去の修正を提示
+  |
+  v
+ストレージ
+  |-- .alfred/knowledge/   -> Markdown+frontmatter（真のソース、Git フレンドリー）
+  |-- .alfred/specs/       -> 仕様ファイル + バージョン履歴 + レビュー
+  |-- .alfred/epics/       -> エピック YAML + タスク依存関係
+  |-- .alfred/steering/    -> プロジェクトコンテキスト（product, structure, tech）
+  |-- .alfred/templates/   -> ユーザーカスタマイズ可能な仕様・Steeringテンプレート
+  +-- ~/.claude-alfred/    -> SQLite検索インデックス（knowledge_index + FTS5 + embeddings, スキーマ V8）
+```
+
+## ファイル生成タイミング
+
+インストール時には何も生成されない。使うと出てくる:
+
+| ファイル / ディレクトリ | 生成タイミング | トリガー |
+|---|---|---|
+| `~/.claude-alfred/alfred.db` | プラグインインストール後の最初の Claude Code セッション | SessionStart hook が DB を開く |
+| `.alfred/knowledge/` | 最初のナレッジ保存時（decision, pattern, rule） | `ledger action=save`、PreCompact 決定抽出、spec complete |
+| `.alfred/specs/` | 最初のタスク開始時 | `dossier action=init`（`/alfred:brief` や `/alfred:attend` 経由） |
+| `.alfred/epics/` | 最初のエピック作成時 | `roster action=init` |
+| `.alfred/steering/` | `/alfred:init` 実行時 | プロジェクト初期化スキル |
+| `.alfred/templates/` | ユーザーが仕様・Steeringテンプレートをカスタマイズする時 | テンプレートオーバーライド用に手動作成 |
+| `.alfred/audit.jsonl` | 最初の仕様操作時またはコミット後ドリフト検出時 | `dossier init`、レビュー送信、PostToolUse ドリフト |
+
+## トラブルシューティング
+
+| 症状 | 対処 |
+|------|------|
+| メモリ検索で結果が出ない | `export VOYAGE_API_KEY=your-key` — またはFTS5フォールバックの動作確認 |
+| 出力が意図しない言語 | `export ALFRED_LANG=ja`（または `en`, `zh`, `ko` 等）を `~/.zshrc` に追加 |
+| Hook が動かない | `/plugin install alfred` して再起動 |
+| ダッシュボードが空 | `.alfred/specs/` があるディレクトリで `alfred dash` |
+| レート制限エラー | 対策済み — エージェントは段階的バッチ起動（最大2並列） |
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,283 @@
+# alfred
+
+[![Version](https://img.shields.io/npm/v/claude-alfred)](https://www.npmjs.com/package/claude-alfred)
+[![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)
+
+Your development butler for Claude Code.
+
+[Japanese README](README.ja.md)
+
+## The problem
+
+You're building with Claude Code. It's fast, it's smart, but:
+
+- **It forgets.** Every compact, every new session — gone. That auth decision you spent 20 minutes debating? Ask again.
+- **It wings it.** No spec, no plan. Just vibes. Works until it doesn't.
+- **Nobody reviews.** The code ships without a second pair of eyes. You catch the bug in production.
+
+alfred fixes all three.
+
+## What it does
+
+**Specs that survive.** Requirements, design, decisions, session state — structured markdown files that persist across compacts, sessions, and even project restarts. Your context is never lost.
+
+**Specs that adapt.** Small bug? 3 files. Medium feature? 5. Large system? All 7. alfred auto-detects the right scope — or you can pick a bugfix template with surgical precision (reproduction steps, root cause, fix strategy).
+
+**Memory that compounds.** Every decision, every bug fix, every "we tried X and it didn't work" gets stored as Markdown files in `.alfred/knowledge/` — git-friendly, human-readable, team-shareable. A SQLite search index provides semantic search across all knowledge. Contradictions are detected automatically. Next time you hit a similar problem, alfred surfaces the relevant experience — before you even ask.
+
+**Reliability signals.** Every spec item gets a grounding level — `verified`, `reviewed`, `inferred`, or `speculative`. You can instantly see which requirements are battle-tested and which are guesswork. Typos in grounding values get caught, not silently ignored.
+
+**Brownfield-ready.** Delta specs for existing code changes get `CHG-N` change IDs and Before/After behavioral diffs. Not just "what file changed" but "what behavior changed and why." Three new validation checks enforce delta quality.
+
+**Specs that don't drift.** After every commit, alfred compares what changed against your spec. Modified a component not in the design? Warning. Convention in memory no longer matches code? Flagged. No other tool does this.
+
+**Reviews that scale.** Six review profiles (code, config, security, docs, architecture, testing), each with a curated checklist. Parallel agents, scored reports, actionable findings.
+
+**Proactive skill suggestions.** alfred doesn't wait to be asked. It detects what you're doing — researching, designing, implementing, fixing bugs — and suggests the right skill at the right time. Explored code for a while? "Try `/alfred:survey`." Got research findings? "Save them with `ledger`." Three tasks piling up? "Group them with `roster`."
+
+**Approval gates that can't be bypassed.** Specs go through a review cycle before implementation. Comment on any line in the browser dashboard, approve or request changes — like a GitHub PR review, but for your specs. The gate verifies both the review status *and* the existence of a signed review file, so manually editing the status won't get you past it.
+
+**Project context that sticks.** Steering documents (product purpose, code structure, tech stack) are auto-generated from your project and injected into every spec. Your AI always knows your architecture.
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install -g claude-alfred
+```
+
+This automatically sets up the SQLite database and user rules. Verify with:
+
+```bash
+alfred doctor
+```
+
+### 2. Plugin
+
+In Claude Code:
+
+```
+/plugin marketplace add hir4ta/claude-alfred
+/plugin install alfred
+```
+
+### 3. Environment
+
+Add to `~/.zshrc` (or equivalent):
+
+```bash
+export VOYAGE_API_KEY=your-key  # enables semantic search (~$0.01/session)
+export ALFRED_LANG=en           # output language (en/ja/zh/ko/fr/de/es/pt...)
+```
+
+No Voyage key? alfred still works — FTS5 full-text search handles the fallback.
+
+### 4. Project setup
+
+In Claude Code, from your project root:
+
+```
+/init    ← select "alfred" when prompted
+```
+
+This generates steering docs, templates, and indexes existing knowledge.
+
+> **Note**: Use `/init` (short form) instead of `/alfred:init` — Claude Code's autocomplete may misroute the `alfred:` prefix to another skill. This applies to all alfred skills: prefer `/brief`, `/attend`, `/mend` etc.
+
+## Updating
+
+Both need to be updated together:
+
+```bash
+npm update -g claude-alfred        # CLI, hooks, MCP server, dashboard
+```
+
+```
+/plugin update alfred              # skills, agents, rules (in Claude Code)
+```
+
+Run `alfred doctor` to verify both are in sync.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `/alfred:brief` | Design a spec. 3 agents debate your architecture, then you approve it in the dashboard |
+| `/alfred:attend` | Full autopilot. Spec, review, approve, implement, test, commit — no intervention |
+| `/alfred:tdd` | Test-driven. Red, green, refactor — autonomous cycles with pattern memory |
+| `/alfred:inspect` | Quality gate. 6 parallel review profiles, scored report |
+| `/alfred:mend` | Bug fix. Reproduce, root-cause (with past bug recall), fix, verify, commit |
+| `/alfred:survey` | Reverse-engineer specs from existing code, with confidence scores |
+| `/alfred:salon` | Brainstorm. 3 specialists generate ideas in parallel, then debate |
+| `/alfred:harvest` | Extract knowledge from PR review comments into permanent memory |
+| `/alfred:furnish` | Create or polish a config file |
+| `/alfred:quarters` | Project setup wizard |
+| `/alfred:archive` | Ingest reference docs into searchable knowledge |
+| `/alfred:concierge` | Quick reference |
+
+## MCP tools
+
+| Tool | Purpose |
+|------|---------|
+| `dossier` | Spec lifecycle — init (with size/type), update, status, switch, complete, delete, history, rollback, review, validate |
+| `roster` | Epic management — group tasks with dependencies, track progress |
+| `ledger` | Knowledge — search, save (Markdown+frontmatter), promote, reflect, audit-conventions |
+
+## Hooks
+
+Run automatically. You don't touch these.
+
+| Event | What happens |
+|-------|-------------|
+| SessionStart | Restores spec context, ingests CLAUDE.md, adapts injection depth to project maturity, suggests `ledger reflect` when knowledge base needs attention |
+| PreCompact | Extracts decisions, saves structured chapter memory (Markdown), syncs epic progress, detects research patterns and reminds to save knowledge |
+| UserPromptSubmit | Semantic search + file context boost + **skill nudge** (detects intent → suggests the right skill) |
+| PostToolUse | Detects Bash errors + searches memory for similar past fixes. After commits: spec drift detection. After 5+ Read/Grep: suggests `/alfred:survey` |
+
+## Browser dashboard
+
+```bash
+alfred dashboard              # opens browser at localhost:7575
+alfred dashboard --port 8080  # custom port
+alfred dashboard --url-only   # print URL only
+```
+
+| Tab | What you see |
+|-----|-------------|
+| **Overview** | Project health at a glance — task progress with validation badges, memory health (stale count, conflicts), confidence distribution across specs, epic progress, recent decisions |
+| **Tasks** | Enriched task cards: current focus, next action, epic context, validation status. Drill into spec files. Switch to Review tab for inline comments |
+| **Knowledge** | Browse all memories with sub-type tags. Semantic search (Voyage AI) with 300ms debounce. Local text filter. Toggle any memory on/off |
+| **Activity** | Timeline of all operations. Filter by event type (init/complete/review). Epic drill-down with task status badges |
+
+Inline review mode: click any spec file, switch to Review tab. Comment on specific lines, navigate review rounds, approve or request changes — all in the browser.
+
+The first unchecked task shimmers. You know exactly what's in progress.
+
+For development: `ALFRED_DEV=1 alfred dashboard` + `task dev` (in web/) enables Vite HMR.
+
+## Search pipeline
+
+alfred doesn't just do keyword matching. The search pipeline has three tiers:
+
+1. **Voyage AI vector search** + reranking (when API key is set)
+2. **FTS5 full-text search** with tag alias expansion and fuzzy matching
+3. **Keyword fallback** (LIKE queries)
+
+Tag aliases expand your searches automatically: "auth" finds results tagged "authentication", "login", and "認証".
+
+Fuzzy matching catches typos: "authetication" still finds "authentication".
+
+## Knowledge architecture
+
+Knowledge is stored as Markdown files with YAML frontmatter — the source of truth lives in your project directory, not a binary database.
+
+```
+.alfred/knowledge/
+├── decisions/dec-auth-jwt.md    # design decisions
+├── patterns/pat-error-handling.md  # reusable patterns
+└── rules/rul-no-mock-db.md     # enforced standards
+```
+
+- **Git-friendly**: commit knowledge to share with your team, review in PRs
+- **Human-readable**: `cat` any file to see exactly what alfred knows
+- **Rebuildable**: the SQLite search index is derived from these files — delete the DB, it rebuilds on next session
+- **Sub-type decay**: Assumptions decay in 30 days. Proven rules last 120 days. Each knowledge type has its own half-life.
+- **Contradiction detection**: When two entries say opposite things ("use JWT" vs "avoid JWT"), alfred flags the conflict.
+- **Project-aware**: knowledge is tagged with git remote URL and branch, enabling cross-project search.
+
+## Adaptive specs
+
+Not every task needs 7 spec files.
+
+| Size | Files generated | When |
+|------|----------------|------|
+| **S** (small) | 3: requirements, tasks, session | Bug fix, config change, small tweak |
+| **M** (medium) | 5: + design, test-specs | New endpoint, refactor, moderate feature |
+| **L/XL** (large) | 7: + decisions, research | Architecture change, new subsystem |
+| **D** (delta) | 2: delta.md (with CHG-N IDs + Before/After), session | Brownfield changes to existing code |
+| **Bugfix** | 3-4: bugfix.md, tasks, session (+ test-specs) | Surgical bug fix with reproduction steps |
+
+Size auto-detected from description, or set explicitly: `dossier action=init size=S`.
+
+## Spec validation
+
+`dossier action=validate` runs 22 progressive checks:
+
+- Required sections present (Goal, Functional Requirements, etc.)
+- Minimum FR count by size (S: 1+, M: 3+, L: 5+)
+- Traceability completeness (every FR mapped to a task, every task referencing an FR)
+- Confidence + grounding annotations on required sections
+- Closing wave present in tasks
+- Grounding coverage — opt-in check: fails when >30% of items are speculative (L/XL)
+- Delta spec quality — CHG-N identifiers in Files Affected, Before/After section with content
+
+## Steering documents
+
+Project-level context that gets injected into every spec:
+
+```bash
+/alfred:init
+```
+
+Creates `.alfred/steering/` with:
+- `product.md` — project purpose, target users, business rules
+- `structure.md` — package layout, module boundaries, naming conventions
+- `tech.md` — tech stack, dependencies, API conventions
+
+These docs are read during `dossier init` and injected as context, so specs are always project-aware.
+
+## How it works
+
+```
+You
+  |
+  |-- /alfred:brief    -> specs + 3-agent debate + dashboard approval
+  |-- /alfred:attend   -> full cycle: spec -> approve -> implement -> review -> commit
+  |-- /alfred:mend     -> reproduce -> root cause (+ past bug memory) -> fix -> verify
+  |
+  v
+Hooks (invisible)
+  |-- SessionStart     -> restore context, adapt to project maturity
+  |-- PreCompact       -> save decisions as JSON, chapter memory, epic progress
+  |-- UserPromptSubmit -> vector search + FTS5 + file boost -> inject memories
+  |-- PostToolUse      -> detect errors -> surface related past fixes
+  |
+  v
+Storage
+  |-- .alfred/knowledge/   -> Markdown+frontmatter (source of truth, git-friendly)
+  |-- .alfred/specs/       -> spec files + version history + reviews
+  |-- .alfred/epics/       -> epic YAML + task dependencies
+  |-- .alfred/steering/    -> project context (product, structure, tech)
+  |-- .alfred/templates/   -> user-customizable spec + steering templates
+  +-- ~/.claude-alfred/    -> SQLite search index (knowledge_index + FTS5 + embeddings, schema V8)
+```
+
+## When files are created
+
+Nothing is generated at install time. Files appear as you use alfred:
+
+| File / Directory | Created when | Trigger |
+|---|---|---|
+| `~/.claude-alfred/alfred.db` | First Claude Code session after plugin install | SessionStart hook opens the database |
+| `.alfred/knowledge/` | First knowledge save (decision, pattern, rule) | `ledger action=save`, PreCompact decision extraction, spec complete |
+| `.alfred/specs/` | First task is started | `dossier action=init` (via `/alfred:brief`, `/alfred:attend`, etc.) |
+| `.alfred/epics/` | First epic is created | `roster action=init` |
+| `.alfred/steering/` | Running `/alfred:init` | Project initialization skill |
+| `.alfred/templates/` | User customizes spec or steering templates | Manual creation for template override |
+| `.alfred/audit.jsonl` | First spec operation or commit drift detection | `dossier init`, `dossier delete`, review submission, PostToolUse drift |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| No memory results | `export VOYAGE_API_KEY=your-key` — or check FTS5 fallback is working |
+| Output in wrong language | `export ALFRED_LANG=ja` (or `en`, `zh`, `ko`, etc.) in `~/.zshrc` |
+| Hook not firing | `/plugin install alfred` and restart |
+| Dashboard empty | Run `alfred dash` from a project with `.alfred/specs/` |
+| Rate limit errors | Already mitigated — agents spawn in staggered batches (max 2 parallel) |
+
+## License
+
+MIT

package/content/hooks/hooks.json

@@ -0,0 +1,41 @@
+{
+  "description": "Proactive hooks — auto-import, memory injection, spec session persistence",
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "command": "alfred hook PreCompact",
+            "statusMessage": "alfred: saving session state...",
+            "timeout": 10,
+            "type": "command"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "alfred hook SessionStart",
+            "statusMessage": "alfred: restoring session context...",
+            "timeout": 5,
+            "type": "command"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "command": "alfred hook UserPromptSubmit",
+            "statusMessage": "alfred: searching memories...",
+            "timeout": 10,
+            "type": "command"
+          }
+        ]
+      }
+    ]
+  }
+}

package/content/mcp/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "alfred": {
+      "command": "alfred",
+      "args": ["serve"],
+      "env": {
+        "VOYAGE_API_KEY": "${VOYAGE_API_KEY}",
+        "ALFRED_LANG": "${ALFRED_LANG}"
+      }
+    }
+  }
+}

package/dist/audit-DujZ6YAy.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { u as rootDir } from "./types-C3butmI8.mjs";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+//#region src/spec/audit.ts
+function appendAudit(projectPath, entry) {
+	try {
+		const dir = rootDir(projectPath);
+		mkdirSync(dir, { recursive: true });
+		const line = JSON.stringify({
+			...entry,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		appendFileSync(join(dir, "audit.jsonl"), line + "\n");
+	} catch {}
+}
+//#endregion
+export { appendAudit as t };