@einja/dev-cli 0.1.41 → 0.1.44

package/presets/default/.claude/skills/einja-team-exec/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: einja-team-exec
+description: "Agent Teamsによるチーム並列実行を行うSkill。ユーザーが「チームで」「Teamで」「Agent Teamsで」「並列チームで」等と明示的にチーム実行を指示した場合に使用。通常のサブエージェント委託とは異なり、独立したClaude Codeインスタンスによるチーム協調を行う"
+---
+<!-- 参考: https://code.claude.com/docs/en/agent-teams -->
+
+# Agent Teams チーム実行
+
+## 概要
+
+Agent Teams機能を使い、複数のteammateを編成してタスクを並列実行する。各teammateは独立したClaude Codeインスタンスとして動作し、自身のコンテキストウィンドウを持つ。サブエージェント（`Task`ツール）とは根本的に異なるアーキテクチャ。
+
+### サブエージェントとの違い
+
+| 項目 | Agent Teams (Teammates) | サブエージェント (Task) |
+|------|------------------------|----------------------|
+| 実体 | 独立したClaude Codeインスタンス | メインセッション内の子プロセス |
+| コンテキスト | 各自独立（リードの会話履歴は引き継がない） | メインの指示を引き継ぎ |
+| 通信 | メンバー間で直接メッセージ可能 | メインにのみ結果を報告 |
+| 協調 | 共有タスクリストで自己調整 | メインが全作業を管理 |
+| 適用場面 | 議論・協調が必要な複雑な作業 | 結果のみが重要な集中タスク |
+| トークンコスト | 高い（各自が独立コンテキスト） | 低い（結果がメインに要約される） |
+
+### 有効なユースケース
+
+- **リサーチ・レビュー**: 複数の観点から同時に調査し、知見を共有・検証
+- **新規モジュール・機能開発**: 各teammateが異なるファイル群を担当
+- **競合仮説のデバッグ**: 異なる理論を並行検証し、議論で収束
+- **クロスレイヤー変更**: フロントエンド・バックエンド・テストを各teammateが担当
+
+## 前提条件
+
+`settings.json`に以下が設定されていること:
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+## ワークフロー
+
+### 1. チーム構成の設計
+
+タスク内容を分析し、以下を決定する:
+
+- **teammate数**: 3-5名が推奨（コスト・協調のバランス）
+- **役割分担**: 各teammateの担当範囲と責務を明確化
+- **タスク粒度**: 5-6タスク/teammateが目安
+- **ファイル分割**: 各teammateが異なるファイル群を担当するよう分割
+
+### 2. 自然言語でチーム起動を指示
+
+リードに対して、タスク内容とチーム構成を自然言語で指示する。`subagent_type`等のパラメータ指定は不要。
+
+**プロンプト例:**
+
+```
+Create an agent team for [タスク名].
+Spawn teammates:
+- [役割1]: [担当範囲と具体的な指示]
+- [役割2]: [担当範囲と具体的な指示]
+- [役割3]: [担当範囲と具体的な指示]
+```
+
+**具体例（フルスタック機能開発）:**
+
+```
+認証機能を実装するチームを作成してください。
+teammateを3名spawn:
+- frontend: src/app/auth/ 配下のログインフォーム・認証画面を実装。NextAuth.jsを使用
+- backend: src/server/auth/ 配下のAPI・ミドルウェアを実装。JWT + httpOnly Cookie方式
+- testing: 認証機能のE2Eテスト・ユニットテストを作成。Playwright + Vitest使用
+各teammateは担当ファイル以外を編集しないこと。
+```
+
+**具体例（コードレビュー）:**
+
+```
+PR #142をレビューするチームを作成してください。
+3名のレビュアーをspawn:
+- セキュリティ観点でのレビュー
+- パフォーマンス影響のチェック
+- テストカバレッジの検証
+各自レビュー後に発見事項を報告してください。
+```
+
+### 3. spawn時のプロンプト設計ガイド
+
+teammateはリードの会話履歴を引き継がないため、spawn時のプロンプトに十分なコンテキストを含める。
+
+#### 含めるべき情報
+- **担当範囲**: 具体的なファイルパスやディレクトリ
+- **技術的コンテキスト**: 使用するライブラリ・フレームワーク・パターン
+- **制約**: 編集してはいけないファイル、守るべきルール
+- **成果物**: 何を完了とするか
+
+#### 含めなくてよい情報
+- プロジェクトの基本構成（CLAUDE.md経由で自動ロードされる）
+- git操作安全ルール（CLAUDE.md経由で自動適用される）
+- MCP設定（自動的に引き継がれる）
+
+### 4. 実行と監視
+
+- teammateはタスク完了時に自動的にリードにメッセージを送信する
+- idle通知は自動配信されるため、手動チェック不要
+- 必要に応じてteammateに追加指示を送る:
+  - **個別指示**: `SendMessage`（type: `message`）で特定のteammateに
+  - **全体通知**: `SendMessage`（type: `broadcast`）で全員に（コスト高、緊急時のみ）
+- `Shift+Down`でteammate間を切り替え（in-processモード）
+- ブロッカー発生時は即座にユーザーに報告する
+
+### 5. 完了とシャットダウン
+
+1. 全タスクの完了を`TaskList`で確認
+2. 各teammateに`SendMessage`（type: `shutdown_request`）を送信
+3. 各teammateがシャットダウンを承認するまで待機
+4. 全teammate停止後、`TeamDelete`でチームリソースをクリーンアップ
+5. ユーザーに最終結果を報告
+
+**重要**: クリーンアップは必ずリードが実行する。teammateからのクリーンアップは不整合を招く。
+
+## ファイル競合の防止
+
+Agent Teamsにおける最大のリスクはファイル競合。2つのteammateが同じファイルを編集すると上書きが発生する。
+
+### 防止策
+
+- **チーム設計時にファイル担当を明確に分割する**
+- 各teammateのspawnプロンプトに担当ファイル/ディレクトリを明記
+- 共有ファイル（設定ファイル等）の編集は1名のteammateに限定
+
+## コミット管理
+
+CLAUDE.mdの「サブエージェントのgit操作安全ルール」がCLAUDE.md経由で全teammateに自動適用される。
+
+### 追加の注意点
+
+- `einja-task-commit` Skill経由でコミットを一元管理するのが望ましい
+- teammateに直接コミットさせる場合は、変更対象ファイルをspawnプロンプトで明示的に指定
+- 完了検証: teammateの「完了」報告を鵜呑みにせず、`Read`や`Grep`で変更がディスク上に存在することを確認
+
+## チーム設計のベストプラクティス
+
+- **3-5名で開始**: バランスの良い並列度。それ以上はコスト対効果が下がる
+- **1 teammateあたり5-6タスク**: 生産性とコンテキスト切り替えのバランス
+- **リサーチ・レビューから始める**: 実装より低リスクで、並列探索の効果を確認しやすい
+- **タスク粒度を適切に**: 小さすぎ→協調オーバーヘッドが上回る / 大きすぎ→チェックインなく進行し、リスク増大
+- **定期的に進捗を確認**: 放置すると無駄な作業が蓄積する
+- **plan approval活用**: 複雑・リスクの高いタスクではteammateにplan mode必須を設定
+
+## 制限事項（実験機能）
+
+- セッション再開（`/resume`）でin-processのteammateは復元されない
+- タスクステータスの更新が遅延することがある
+- シャットダウンに時間がかかる場合がある（現在のリクエスト完了を待つ）
+- 1セッションにつき1チームのみ
+- nested teams（teammateが自身のチームを作る）は不可
+- リードは固定（交代不可）
+- split panesはtmux/iTerm2が必要
+
+<!-- @einja:project-private:start id="einja-team-exec-project" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private:end -->

package/presets/default/CLAUDE.md.template

@@ -10,6 +10,7 @@
 3. **影響範囲の最小化**: 変更は必要な箇所のみ。関係ないコードに触れない
 4. **直接実装の禁止**: あなたは絶対に直接実装を行わない。すべての作業はsubagentに委託し、可能な限り並行で呼び出す。サブエージェントの出力はユーザにも見える場所に出力すること
 5. **実装品質の自己検証**: 複雑な変更では完了前に「よりエレガントな方法はないか」を自問する。ただし単純な修正には不要
+6. **Skill-First原則**: 実装着手前に `einja-skill-first` Skillで「Skillを先に作るべきか」を評価する。反復性のある作業はSkill化してから本作業を開始する
 
 ## Agent Teams の使用制限
 
@@ -26,7 +27,6 @@
 
 | 作業 | 委託先 |
 |------|--------|
-| コンフリクト解消 | `conflict-resolver` |
 | Codex作業（レビュー・実装支援等） | `codex-agent` |
 | フロントエンド アーキテクチャ設計 | `frontend-architect` |
 | フロントエンド デザイン実装 | `design-engineer` |
@@ -40,11 +40,21 @@
 | `einja-task-commit` | コミット・プッシュ |
 | `einja-conflict-resolver` | gitコンフリクト解消 |
 | `einja-skill-creator` | Skill作成・更新 |
-| `einja-skill-first` | 作業前のSkill作成必要性評価（Plan/spec-create時に自動起動） |
+| `einja-skill-first` | 作業前のSkill作成必要性評価（Plan/einja-issue-spec-create時に自動起動） |
 | `einja-infra-maintenance` | インフラ環境セットアップ・メンテナンス |
-| `einja:issue-exec` | Issue全体の階層的並列実行（Manager→Director→Worker） |
-| `einja:task-exec` | タスクグループ実行 |
-| `einja:spec-create` | 仕様書作成 |
+| `einja:issue-exec` | Issue全体の階層的並列実行（Command） |
+| `einja-task-exec` | タスクグループ実行（Skill tool） |
+| `einja-issue-spec-create` | Issue仕様書作成（Skill tool） |
+
+#### サブエージェント質問プロトコル（PENDING_QUESTIONS）
+
+サブエージェントではAskUserQuestionが動作しないため、質問が必要な場合は `## PENDING_QUESTIONS` 形式で返却される。
+
+サブエージェント出力に `## PENDING_QUESTIONS` が含まれている場合:
+1. 質問内容を解析し、AskUserQuestionでユーザーに確認する
+2. Agent toolの `resume` パラメータで同じサブエージェントを再開（コンテキスト維持）
+3. プロンプトにユーザーの回答を含めて渡す（例: `ユーザーの回答: Q1→A、Q2→B。これを踏まえて作業を継続してください。`）
+4. 再度PENDING_QUESTIONSがある場合は同様に処理（最大2回まで）
 
 ## コード変更時の動作方針
 
@@ -126,7 +136,7 @@
 ## プロジェクト概要
 
 Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は以下のSkillを参照:
-- `einja-project-overview` - 構成、技術スタック、頻出コマンド
+- `_einja-project-overview` - 構成、技術スタック、頻出コマンド
 - `docs/einja/steering/development/coding-standards.md` - コーディング規約、インポートパス規約
 - `einja-infra-maintenance` - 開発環境セットアップ、サーバー管理
 
@@ -165,6 +175,11 @@ Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は
 - 番号付きリスト: 詳細説明が必要な場合
 - 推奨オプションには `（推奨）` と理由を付記
 
+### 選択肢の記述ルール
+- 各選択肢の `description` に**必ず詳細説明・注意点・補足**を記載する
+- トレードオフ、影響範囲、前提条件など判断に必要な情報を含める
+- ラベルだけで選択させない。ユーザーが十分な情報に基づいて判断できるようにする
+
 ## 報告ルール
 
 ### 出力形式

package/presets/default/docs/einja/instructions/deployment-setup.md

@@ -35,7 +35,7 @@
 |--------|----------------|------|
 | Volta | `curl https://get.volta.sh \| bash` | Node.jsバージョン管理 |
 | pnpm | `volta install pnpm` | パッケージ管理 |
-| Docker | [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL実行 |
+| Docker | macOS: [OrbStack](https://orbstack.dev/)（推奨）/ その他: [Docker Engine](https://docs.docker.com/engine/install/) | PostgreSQL実行 |
 | GitHub CLI (`gh`) | `brew install gh` | GitHub操作 |
 | Vercel CLI | `pnpm add -g vercel` | Vercelデプロイ |
 | Neon CLI (`neonctl`) | `npm install -g neonctl` | Neonデータベース管理 |

package/presets/default/docs/einja/instructions/issue-exec-workflow.md

@@ -46,13 +46,13 @@ Manager (Claude Code: /einja:issue-exec)
 │  │
 │  ├─ tmux window → Worker 1.1 (claude 対話モード)
 │  │   Task worktree: ~/.einja/worktrees/issue-123/task-1.1/
-│  │   → /einja:task-exec #123 1.1
+│  │   → einja-task-exec Skill: #123 1.1
 │  │     ├─ サブエージェント: Task 1.1.1 実装（run_in_background）
 │  │     ├─ サブエージェント: Task 1.1.2 実装（run_in_background）
 │  │     └─ reviewer → QA → commit
 │  │
 │  ├─ tmux window → Worker 1.2 (claude 対話モード)
-│  │   → /einja:task-exec #123 1.2
+│  │   → einja-task-exec Skill: #123 1.2
 │  │
 │  └─ (依存タスクグループは先行完了後に起動)
 │
@@ -68,7 +68,7 @@ Manager (Claude Code: /einja:issue-exec)
 |------|------|---------|
 | **Manager** | Issue パース、ブランチ管理、worktree 管理、tmux 管理、Director 起動、Phase マージ、質問エスカレーション、エラー監視 | Claude Code カスタムコマンド |
 | **Director** | Phase 内のタスクグループ管理、Worker 起動、並列制御、PR マージ検知、変更伝播、質問対応、worktree クリーンアップ | claude 対話モード（tmux window） |
-| **Worker** | task-exec 実行（executer→reviewer→qa→commit）、Phase 変更取り込み、PR 作成、完了報告 | claude 対話モード（tmux window） |
+| **Worker** | einja-task-exec Skill 実行（executer→reviewer→qa→commit）、Phase 変更取り込み、PR 作成、完了報告 | claude 対話モード（tmux window） |
 
 ### 各階層の通信方式
 
@@ -123,10 +123,10 @@ main (デフォルト)
 tmux session: einja-123
   window 0: Manager (メインプロセスのログ表示)
   window 1: Director-Phase1 (claude 対話モード)
-  window 2: Worker-1.1 (claude 対話モード → /einja:task-exec #123 1.1)
-  window 3: Worker-1.2 (claude 対話モード → /einja:task-exec #123 1.2)
+  window 2: Worker-1.1 (claude 対話モード → einja-task-exec: #123 1.1)
+  window 3: Worker-1.2 (claude 対話モード → einja-task-exec: #123 1.2)
   window 4: Director-Phase2 (claude 対話モード)
-  window 5: Worker-2.1 (claude 対話モード → /einja:task-exec #123 2.1)
+  window 5: Worker-2.1 (claude 対話モード → einja-task-exec: #123 2.1)
 ```
 
 ユーザーは `tmux attach -t einja-123` で全プロセスを監視可能。
@@ -248,18 +248,18 @@ Manager 検知
 | Worker 異常終了（PR作成済み） | tmux window 消失 + PR あり | スキップ（PR マージ待ちのまま継続） |
 | Director 異常終了 | tmux window 消失 + ステータス未更新 | 各 Worker のステータスを確認 → 未完了 Worker のみ再実行 |
 | Manager 異常終了 | ユーザー手動 | `--resume` でステータスファイルから復元 |
-| rebase コンフリクト | git rebase 失敗 | conflict-resolver で自力解消 |
+| rebase コンフリクト | git rebase 失敗 | einja-conflict-resolver Skill で自力解消 |
 | CI 失敗 | gh run status | 修正 → 再push → 再CI待機 |
 | CI 待機タイムアウト | 30分超過 | Manager に通知 → 人間判断 |
 
 ---
 
-## `/einja:task-exec` との使い分け
+## `einja-task-exec` Skill との使い分け
 
-| コマンド | 用途 | 対象 | 推奨シーン |
+| 実行方法 | 用途 | 対象 | 推奨シーン |
 |---------|------|------|----------|
 | **`/einja:issue-exec`** | Issue全体の並列実行 | 複数Phase・複数タスクグループ | 大規模機能実装 |
-| **`/einja:task-exec`** | 単一タスクグループの実行 | 1つのタスクグループ | 品質重視、複雑な実装 |
+| **`einja-task-exec` Skill** | 単一タスクグループの実行 | 1つのタスクグループ | 品質重視、複雑な実装 |
 
 ---
 
@@ -267,7 +267,7 @@ Manager 検知
 
 - [タスク実行ワークフロー](./task-execute.md)
 - [タスク管理ガイドライン](../steering/task-management.md)
-- [仕様書作成ワークフロー](./einja:spec-create.md)
+- [仕様書作成ワークフロー](./task-execute.md#フェーズ1-issue仕様書作成-einja-issue-spec-create-skill)
 - [ブランチ運用戦略](../steering/branch-strategy.md)
 <!-- @einja:managed:end -->
 

package/presets/default/docs/einja/instructions/local-server-environment-and-worktree.md

@@ -59,7 +59,7 @@ npm install -g pnpm@10
 ```
 
 #### Docker
-- macOS: [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)
+- macOS: [OrbStack](https://orbstack.dev/)（推奨。`brew install orbstack`）
 - Windows: [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
 - Linux: [Docker Engine](https://docs.docker.com/engine/install/)
 

package/presets/default/docs/einja/instructions/setup-flow.md

@@ -0,0 +1,279 @@
+# セットアップフローガイド
+
+## 概要
+
+このドキュメントでは、einja プロジェクトにおける3つの主要セットアップシナリオのフローを解説します。
+
+| シナリオ | 対象者 | 目的 |
+|---------|--------|------|
+| **1. `npx create-einja-app`** | 新規プロジェクト作成者 | テンプレートからプロジェクトを一括生成 |
+| **2. `git clone` 後の環境構築** | 既存プロジェクトへの参加者 | 開発環境を手元に再現 |
+| **3. `einja sync`** | 既存プロジェクト運用者 | テンプレートの最新変更をプロジェクトに同期 |
+
+---
+
+## シナリオ別フロー
+
+### 1. `npx create-einja-app`（新規プロジェクト作成）
+
+テンプレートからプロジェクトを新規作成し、初回セットアップまで自動で完了するフローです。
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant CLI as create-einja-app<br/>cli.ts
+    participant Tmpl as generators/<br/>template.ts
+    participant Post as generators/<br/>post-setup.ts
+    participant Init as scripts/<br/>init.sh
+    participant Rotate as scripts/<br/>env-rotate-secrets.ts
+    participant DevCLI as @einja/dev-cli
+
+    User->>CLI: npx create-einja-app my-app
+    Note over CLI: 対話プロンプト<br/>（プロジェクト名・スコープ・認証方式等）
+
+    CLI->>Tmpl: generateTemplate(config, targetPath)
+    activate Tmpl
+    Note over Tmpl: 1. テンプレートディレクトリをコピー<br/>2. 認証方式に応じたファイル除外<br/>3. .template ファイルのリネーム<br/>4. gitignore → .gitignore リネーム<br/>5. プレースホルダー変数置換<br/>6. .sh ファイルに実行権限付与
+    Tmpl-->>CLI: 完了
+    deactivate Tmpl
+
+    CLI->>Post: execPostSetup(config, targetPath, options)
+    activate Post
+
+    Post->>Init: bash scripts/init.sh
+    activate Init
+    Note over Init: Step 1: Volta インストール<br/>Step 2: シェル設定（VOLTA_FEATURE_PNPM）<br/>Step 3: Node.js / pnpm インストール<br/>Step 4: direnv allow
+    Init-->>Post: 完了
+    deactivate Init
+
+    Note over Post: PATH補完<br/>（~/.volta/bin を process.env.PATH に追加）
+
+    Post->>Post: pnpm install
+    Post->>Post: pnpm db:generate
+
+    Post->>Rotate: pnpm env:rotate-secrets --all --non-interactive
+    activate Rotate
+    Note over Rotate: 全環境の AUTH_SECRET +<br/>DOTENV_PRIVATE_KEY をローテーション<br/>（バックアップ付き自動復元）
+    Rotate-->>Post: 完了
+    deactivate Rotate
+
+    Post->>Post: git init + git add . + git commit
+
+    opt setupEinjaCli=true の場合
+        Post->>DevCLI: npx --yes @einja/dev-cli init --force --no-backup
+    end
+
+    Post-->>User: 完了メッセージ表示
+    deactivate Post
+```
+
+#### 処理詳細テーブル
+
+| ステップ | 実行元 | 処理内容 |
+|---------|--------|---------|
+| 対話プロンプト | `cli.ts` | プロジェクト名、パッケージスコープ、認証方式等を対話的に入力 |
+| テンプレート展開 | `generators/template.ts` | テンプレートコピー → `{{projectName}}` `{{packageName}}` `{{description}}` `@repo/` 等の変数置換 → `.template` リネーム → `gitignore` → `.gitignore` リネーム → 認証方式に応じたファイル除外 → `.sh` に実行権限付与 |
+| Step 0: init.sh | `generators/post-setup.ts` | Volta/Node.js/pnpm/direnv の初期導入（`stdio: inherit` で出力をそのまま表示） |
+| PATH補完 | `generators/post-setup.ts` | `~/.volta/bin` を `process.env.PATH` に追加（init.sh で導入した Volta を後続ステップで利用可能にする） |
+| Step 1: 依存関係 | `generators/post-setup.ts` | `pnpm install` + `pnpm db:generate`（Prisma クライアント生成） |
+| Step 2: 秘密鍵ローテーション | `env-rotate-secrets.ts` | `--all --non-interactive` モードで全環境の AUTH_SECRET と DOTENV_PRIVATE_KEY を自動ローテーション |
+| Step 3: Git初期化 | `generators/post-setup.ts` | `git init` → `git add .` → `git commit -m "Initial commit"` |
+| Step 4: dev-cli 初期化 | `generators/post-setup.ts` | `setupEinjaCli=true` 時のみ `npx --yes @einja/dev-cli@latest init --force --no-backup` を実行 |
+
+---
+
+### 2. `git clone` 後の環境構築（既存プロジェクトへの参加）
+
+既存プロジェクトに新たに参加する開発者が、ローカル環境を構築するフローです。
+
+```mermaid
+flowchart TD
+    A[git clone → cd project] --> B[./scripts/init.sh]
+
+    subgraph init ["scripts/init.sh（初回のみ手動実行）"]
+        B --> B1[Step 1: Volta インストール]
+        B1 --> B2[Step 2: シェル設定<br/>VOLTA_FEATURE_PNPM=1]
+        B2 --> B3[Step 3: Node.js / pnpm インストール]
+        B3 --> B4[Step 4: direnv allow]
+    end
+
+    B4 --> C["exec $SHELL（ターミナル再起動）"]
+    C --> D[pnpm dev:setup]
+
+    subgraph devsetup ["scripts/setup-dev.ts（= pnpm dev:setup）"]
+        D --> D1[Step 1-3: Volta 確認 / シェル設定 / Node.js・pnpm]
+        D1 --> D4[Step 4: direnv インストール<br/>macOS: brew install direnv]
+        D4 --> D5[Step 5: シェルに direnv hook 追加]
+        D5 --> D6[Step 6: dotenvx インストール]
+        D6 --> D7["Step 7: .env 作成<br/>（.env.local + .env.keys で復号）"]
+        D7 --> D8["Step 8: .env.personal 作成<br/>+ GITHUB_TOKEN 設定（対話的）"]
+        D8 --> D9["Step 9: direnv allow<br/>→ .envrc 評価（Serena MCP 自動起動）"]
+        D9 --> D10["Step 10: PostgreSQL 起動<br/>（docker-compose up -d postgres）"]
+        D10 --> D11["Step 11: DB 初期化<br/>（pnpm db:generate + pnpm db:push）"]
+    end
+
+    D11 --> E[pnpm dev で開発開始]
+
+    style init fill:#e8f4fd,stroke:#2196F3
+    style devsetup fill:#e8f5e9,stroke:#4CAF50
+```
+
+#### 処理詳細テーブル
+
+| ステップ | 実行ファイル | 処理内容 |
+|---------|-------------|---------|
+| Step 1: Volta | `init.sh` → `setup-dev.ts` | Volta 未インストール時は `curl` で導入。macOS 以外では手動インストールを案内 |
+| Step 2: シェル設定 | `init.sh` → `setup-dev.ts` | `~/.zshrc` 等に `VOLTA_FEATURE_PNPM=1` を追記（既存なら冪等にスキップ） |
+| Step 3: Node.js/pnpm | `init.sh` → `setup-dev.ts` | `package.json` の `volta` フィールドからバージョンを読み取り `volta install` |
+| Step 4: direnv | `setup-dev.ts` | macOS では `brew install direnv` を自動実行。他 OS は手動案内 |
+| Step 5: direnv hook | `setup-dev.ts` | `~/.zshrc` 等に `eval "$(direnv hook zsh)"` を追記 |
+| Step 6: dotenvx | `setup-dev.ts` | `curl -sfS https://dotenvx.sh/install.sh` で導入。失敗時は `npm install -g @dotenvx/dotenvx` にフォールバック |
+| Step 7: .env 作成 | `setup-dev.ts` | `.env.local`（暗号化済み） + `.env.keys`（秘密鍵）から `dotenvx decrypt` で `.env` を生成。worktree 環境では親リポジトリから `.env.keys` を自動コピー。失敗時は `.env.example` にフォールバック |
+| Step 8: .env.personal | `setup-dev.ts` | `.env.personal.example` からコピー → GITHUB_TOKEN を対話的に入力（スキップ可） |
+| Step 9: direnv 有効化 | `setup-dev.ts` | `direnv allow` 実行 → `.envrc` が評価される → Serena MCP サーバー自動起動 |
+| Step 10: DB 起動 | `setup-dev.ts` | `docker-compose up -d postgres` + 3秒の起動待機 |
+| Step 11: DB 初期化 | `setup-dev.ts` | `pnpm db:generate`（Prisma クライアント生成） + `pnpm db:push`（スキーマ適用） |
+
+#### .envrc の役割
+
+`.envrc` は direnv によりディレクトリ進入時に自動評価され、以下の処理を行います。
+
+| 処理 | 条件 | 詳細 |
+|------|------|------|
+| dotenv 読み込み | 常時 | `dotenv_if_exists .env` で環境変数をロード |
+| worktree 間 .env.personal 共有 | `$MAIN_WORKTREE` が設定済みの場合 | メインワークツリーの `.env.personal` を `dotenv_if_exists` で読み込み（worktree 環境でも個人トークンを共有） |
+| Serena MCP 自動起動 | `$MAIN_WORKTREE` が設定済み かつ `ensure-serena.sh` が存在する場合 | メインワークツリーの `scripts/ensure-serena.sh` を `source` で実行 |
+
+#### ensure-serena.sh の動作
+
+| 処理 | 詳細 |
+|------|------|
+| 既存インスタンスチェック | `.serena-port` ファイルから PID を読み取り、生存確認。生存中ならポート番号を再利用して即座に `return` |
+| uvx 確認 | `uvx` コマンドの存在チェック。未インストール時は警告のみでブロックしない |
+| 空きポート検出 | デフォルトポート 9850 から最大10ポートを `nc -z` で試行 |
+| バックグラウンド起動 | `uvx --from git+https://github.com/oraios/serena serena start-mcp-server` を `--transport streamable-http` で起動、`disown` で切り離し |
+| 起動待機 | PID 生存 + ポート LISTEN を最大30秒（0.5秒間隔）で確認。成功時に `.serena-port` にポート番号と PID を記録 |
+
+---
+
+### 3. `einja sync`（テンプレート同期）
+
+テンプレートの最新変更を既存プロジェクトに同期するフローです。2つの CLI ツールがそれぞれ異なる対象を担当します。
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Skill as einja:einja-sync<br/>Skill
+    participant DevCLI as @einja/dev-cli<br/>sync
+    participant CEA as create-einja-app<br/>sync
+
+    User->>Skill: einja sync（Skill経由）
+
+    rect rgb(232, 244, 253)
+        Note over DevCLI: dev-cli sync — Claude Code 関連ファイル
+        Skill->>DevCLI: einja sync [--only categories]
+        activate DevCLI
+        Note over DevCLI: 1. カテゴリ指定（--only）のパース<br/>2. メタデータ読み込み<br/>3. 同期対象スキャン<br/>4. ハッシュベース差分計算<br/>5. dry-run / 確認プロンプト<br/>6. バックアップ作成<br/>7. ファイルマージ（マーカー / 3方向 / JSON）<br/>8. 孤児ファイル検出・削除<br/>9. メタデータ保存<br/>10. 依存関係チェック + インストール
+        DevCLI-->>Skill: 結果レポート
+        deactivate DevCLI
+    end
+
+    rect rgb(232, 245, 233)
+        Note over CEA: create-einja-app sync — プロジェクト構成ファイル
+        Skill->>CEA: npx create-einja-app sync
+        activate CEA
+        Note over CEA: 1. Git状態チェック<br/>2. カテゴリ選択（対話 / --all / --categories）<br/>3. プロジェクト設定検出（変数置換用）<br/>4. ファイル収集（globパターン）<br/>5. バックアップ作成<br/>6. マージ・コピー処理<br/>7. テンプレート変数置換<br/>8. 置換漏れ検証<br/>9. 結果レポート
+        CEA-->>Skill: 結果レポート
+        deactivate CEA
+    end
+
+    Skill-->>User: 同期完了報告
+```
+
+#### dev-cli sync の同期対象とマージ方式
+
+| カテゴリ | 対象パス | 説明 |
+|---------|---------|------|
+| `commands` | `.claude/commands/einja/` | Claude Code コマンド定義 |
+| `agents` | `.claude/agents/einja/` | サブエージェント定義 |
+| `skills` | `.claude/skills/einja-*/`, `_einja-*/` | Skill 定義（`einja-` / `_einja-` プレフィックス） |
+| `hooks` | `.claude/hooks/` | フック定義 |
+| `docs` | `docs/einja/` | ステアリングドキュメント |
+| `scripts` | `scripts/` | ユーティリティスクリプト（`_` プレフィックスは除外） |
+| `env` | `.envrc` | direnv 設定 |
+| `tools` | `.vscode/settings.json` | VS Code 設定 |
+
+**マージ方式:**
+
+| 方式 | 適用条件 | 動作 |
+|------|---------|------|
+| マーカーベースマージ | `@einja:managed:[start/end]`、`@einja:project-private:[start/end]` マーカーを含むファイル | managed セクションをテンプレートで置換し、project-private セクションはローカルを保持 |
+| レガシーマーカー自動マイグレーション | `@einja:seed:[start/end]` マーカーを含むファイル | レガシー `@einja:seed:` マーカーを `@einja:managed:` に自動変換した上でマーカーベースマージを実行 |
+| project-private のみマージ | `@einja:project-private` のみで `@einja:managed` を含まないファイル | project-private セクションをローカルから保持し、それ以外をテンプレートで上書き（`syncProjectPrivateOnlyFile`） |
+| JSON マージ | `.json` 拡張子のファイル | managed/project-private の JSON パス指定に基づきマージ |
+| 3方向マージ | マーカーなしの通常ファイル | base（前回テンプレート）・local・template の3方向差分で自動マージ。コンフリクト時はマーカー付きで出力 |
+
+#### create-einja-app sync の同期対象カテゴリ
+
+| カテゴリ | 対象パターン | デフォルト選択 |
+|---------|-------------|--------------|
+| `env` | `.env*`, `.envrc`, `.volta`, `.node-version` | ON |
+| `tools` | `biome.json`, `.prettierrc*`, `.editorconfig`, `.vscode/` | ON |
+| `git` | `.gitignore`, `.gitattributes` | OFF |
+| `git-hooks` | `.husky/` | OFF |
+| `github` | `.github/workflows/`, `.github/actions/`, `.github/dependabot.yml` | OFF |
+| `docker` | `Dockerfile*`, `docker-compose*.yml`, `.dockerignore` | OFF |
+| `monorepo` | `turbo.json`, `pnpm-workspace.yaml` | OFF |
+| `root-config` | `package.json`, `tsconfig.json` | OFF |
+| `scripts` | `scripts/` 配下 | OFF |
+| `apps` | `apps/` 配下（個別選択可） | OFF |
+| `packages` | `packages/` 配下（個別選択可） | OFF |
+| `docs` | `README.md`, `docs/` | OFF |
+
+**保護対象ファイル（同期から除外）:**
+- `.env.keys`, `.env.personal`, `.env.develop`, `.env.local`, `.env.production`, `.env.staging`, `.env.preview`
+- `**/prisma/schema.prisma`, `**/prisma/migrations/**`, `pnpm-lock.yaml`
+
+---
+
+## ファイル別リファレンス
+
+各スクリプト/ファイルの役割と呼び出し元を逆引きテーブルで示します。
+
+| ファイル | 役割 | 呼び出し元 |
+|---------|------|-----------|
+| `scripts/init.sh` | Volta/Node.js/pnpm/direnv 初期導入（初回のみ） | `create-einja-app`（`post-setup.ts` から `bash scripts/init.sh`） / 手動実行 |
+| `scripts/setup-dev.ts` | 環境構築一式（Volta確認・direnv・dotenvx・.env復号・DB起動） | `pnpm dev:setup` |
+| `scripts/ensure-serena.sh` | Serena MCP サーバーの冪等起動（PIDベース） | `.envrc` から `source`（direnv 評価時に自動実行） |
+| `scripts/env-rotate-secrets.ts` | AUTH_SECRET / DOTENV_PRIVATE_KEY のローテーション | `create-einja-app`（`post-setup.ts` から `--all --non-interactive`） / `pnpm env:rotate-secrets` |
+| `.envrc` | dotenv 読み込み + worktree 間 .env.personal 共有 + Serena MCP 起動 | direnv（シェルでディレクトリ進入時に自動評価） |
+| `packages/create-einja-app/src/generators/post-setup.ts` | プロジェクト作成後のセットアップ（init.sh → install → rotate → git → dev-cli） | `create-einja-app` create コマンド |
+| `packages/create-einja-app/src/generators/template.ts` | テンプレート展開・変数置換・リネーム処理 | `create-einja-app` create コマンド |
+| `packages/create-einja-app/src/generators/sync.ts` | create-einja-app 用同期ファイル収集（カテゴリ → glob パターン → フィルタリング） | `create-einja-app` sync コマンド |
+| `packages/create-einja-app/src/commands/sync.ts` | create-einja-app sync のメインフロー（バックアップ・マージ・検証） | `npx create-einja-app sync` |
+| `packages/cli/src/commands/sync.ts` | dev-cli sync のメインフロー（ハッシュ差分・マーカーマージ・孤児管理） | `einja sync` コマンド |
+| `packages/cli/src/lib/sync/file-filter.ts` | dev-cli sync の同期対象スキャン・カテゴリマッピング | `packages/cli/src/commands/sync.ts` |
+
+---
+
+## 処理の重複と設計意図
+
+### init.sh と setup-dev.ts の重複
+
+`init.sh` と `setup-dev.ts` の Step 1-3（Volta/シェル設定/Node.js・pnpm インストール）は意図的に重複しています。
+
+| 観点 | 説明 |
+|------|------|
+| **冪等性** | 両スクリプトともに「既にインストール済み」を検出するガードがあり、何度実行しても安全 |
+| **init.sh の位置づけ** | 最小限の初期導入スクリプト。`create-einja-app` からは `bash scripts/init.sh` で一括実行。手動実行も可能 |
+| **setup-dev.ts の位置づけ** | 環境構築の包括スクリプト。init.sh 相当の処理を内包した上で、direnv/dotenvx/.env/DB 等の追加セットアップを実行 |
+| **分離の理由** | `init.sh` は bash スクリプトで Node.js 不要。`setup-dev.ts` は TypeScript で Node.js 必須。初回セットアップ時は Node.js がまだ存在しない可能性があるため、`init.sh` で Node.js 導入 → `setup-dev.ts` で残りの処理という順序が必要 |
+
+### dev-cli sync と create-einja-app sync の分担
+
+| ツール | 同期対象 | マージ方式 |
+|--------|---------|-----------|
+| **dev-cli sync** | Claude Code 関連（`.claude/`、`docs/einja/`、`scripts/`、`.envrc`、`.vscode/settings.json`） | マーカーベース + 3方向マージ + JSON マージ。ハッシュキャッシュによる差分検出 |
+| **create-einja-app sync** | プロジェクト構成全般（CI/CD、Docker、モノレポ設定、apps/、packages/ 等） | カテゴリ選択式。テンプレート変数置換 + マーカーベースマージ。置換漏れ検証つき |
+
+両ツールは対象領域が異なり、通常は競合しません。`einja:einja-sync` Skill から統合的に呼び出されます。