@einja/dev-cli 0.1.40 → 0.1.44

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

@@ -0,0 +1,276 @@
+<!-- @einja:managed:start -->
+# `einja:issue-exec` コマンド
+
+## 概要
+
+GitHub Issue のタスクを Manager → Director → Worker の3階層プロセスで並列実行する Claude Code カスタムコマンド。tmux セッション、git worktree、ステータスファイルで全プロセスを管理する。
+
+**⚠️ 重要**: Vibe-Kanban（`pnpm task:loop`）は廃止され、`/einja:issue-exec` に移行しました。
+
+---
+
+## 使用方法
+
+### コマンド実行
+
+```bash
+# 基本
+/einja:issue-exec #123
+
+# オプション指定
+/einja:issue-exec #123 --merge-mode task-group-auto   # タスクPR自動マージ
+/einja:issue-exec #123 --merge-mode auto               # 全自動
+/einja:issue-exec #123 --max-phase 2                   # Phase 2 まで
+/einja:issue-exec #123 --base develop                  # ベースブランチ指定
+/einja:issue-exec #123 --resume                        # セッション復旧
+```
+
+### 事前準備
+
+- tmux がインストールされていること
+- GitHub CLI（`gh`）がインストール・認証済みであること
+- Docker が起動していること（必要な場合）
+
+---
+
+## アーキテクチャ
+
+### 3階層プロセス
+
+```
+Manager (Claude Code: /einja:issue-exec)
+│  メインリポ or Issue worktree
+│
+├─ tmux window → Director Phase1 (claude 対話モード)
+│  │  Phase worktree: ~/.einja/worktrees/issue-123/phase1/
+│  │
+│  ├─ tmux window → Worker 1.1 (claude 対話モード)
+│  │   Task worktree: ~/.einja/worktrees/issue-123/task-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 Skill: #123 1.2
+│  │
+│  └─ (依存タスクグループは先行完了後に起動)
+│
+├─ tmux window → Director Phase2 (Phase1完了後 or 並列)
+│  └─ ...
+│
+└─ 全Phase完了 → PR: issue/123 → main
+```
+
+### 各階層の責務
+
+| 階層 | 責務 | 実行方式 |
+|------|------|---------|
+| **Manager** | Issue パース、ブランチ管理、worktree 管理、tmux 管理、Director 起動、Phase マージ、質問エスカレーション、エラー監視 | Claude Code カスタムコマンド |
+| **Director** | Phase 内のタスクグループ管理、Worker 起動、並列制御、PR マージ検知、変更伝播、質問対応、worktree クリーンアップ | claude 対話モード（tmux window） |
+| **Worker** | einja-task-exec Skill 実行（executer→reviewer→qa→commit）、Phase 変更取り込み、PR 作成、完了報告 | claude 対話モード（tmux window） |
+
+### 各階層の通信方式
+
+| 階層間 | 方式 | 理由 |
+|--------|------|------|
+| Manager → Director | tmux + ステータスファイル + 質問エスカレーション | 別 worktree が必要 |
+| Director → Worker | tmux + ステータスファイル + 質問エスカレーション | 別 worktree が必要 |
+| Worker 内部（タスク間） | サブエージェント（Task ツール） | 既存 task-exec フローを活用 |
+
+---
+
+## ブランチ & worktree 構成
+
+### ブランチ階層
+
+```
+main (デフォルト)
+ └── issue/123                        Manager管理
+      ├── issue/123-phase1             Director1 worktree
+      │    ├── task/123-1.1            Worker1.1 worktree
+      │    ├── task/123-1.2            Worker1.2 worktree
+      │    └── task/123-1.3            Worker1.3 worktree（1.1完了後に作成）
+      └── issue/123-phase2             Director2 worktree
+           └── task/123-2.1            Worker2.1 worktree
+```
+
+### worktree 物理パス
+
+```
+~/.einja/worktrees/issue-123/
+├── phase1/                     ← Director1 cwd
+├── task-1.1/                   ← Worker1.1 cwd
+├── task-1.2/                   ← Worker1.2 cwd
+└── phase2/                     ← Director2 cwd
+```
+
+---
+
+## マージモード
+
+| モード | タスクPR (task→phase) | Phase PR (phase→issue) | 最終PR (issue→base) |
+|---|---|---|---|
+| `manual` | 人間マージ待ち | 人間マージ待ち | 人間マージ待ち |
+| `task-group-auto` | CI通過後に自動マージ | 人間マージ待ち | 人間マージ待ち |
+| `auto` | CI通過後に自動マージ | CI通過後に自動マージ | 人間マージ待ち（常に手動） |
+
+---
+
+## tmux セッション構成
+
+```
+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 4: Director-Phase2 (claude 対話モード)
+  window 5: Worker-2.1 (claude 対話モード → einja-task-exec: #123 2.1)
+```
+
+ユーザーは `tmux attach -t einja-123` で全プロセスを監視可能。
+
+---
+
+## ステータスファイル
+
+パス: `~/.einja/sessions/issue-123/`
+
+```
+session.json                    # セッション全体（Manager PID、開始時刻、マージモード等）
+phase-1/
+  status.json                   # Phase状態 + Director PID
+  task-1.1.json                 # { status, prNumber, branch }
+  task-1.2.json
+phase-2/
+  status.json
+questions/
+  q-{uuid}.json                 # 質問ファイル（1ファイル1質問）
+events.jsonl                    # JSON Lines 形式の追記型イベントログ
+```
+
+### ステータスファイル永続化
+
+- `~/.einja/sessions/` に配置し、システム再起動後も `--resume` で復元可能
+- 完了時に Manager が自動クリーンアップ
+- `status.json` の更新は `flock` による排他制御を使用
+- git push 対象外（純粋にローカル実行状態管理）
+
+---
+
+## 質問エスカレーション
+
+### チェーン
+
+```
+Worker（task-exec 実行中に疑問発生）
+  ↓ ステータスファイル（質問キュー）
+Director（spec/design/issue で回答可能？）
+  ├─ Yes → 回答をステータスファイルに書き込み
+  └─ No ↓ ステータスファイル（質問キュー）
+Manager（Claude Code カスタムコマンド）
+  ↓ AskUserQuestion で人間に質問
+Human（回答入力）
+  ↓ 回答をステータスファイルに書き込み → 逆順で伝播
+```
+
+### 質問ファイル形式
+
+```json
+{
+  "id": "q-001",
+  "from": "worker-1.1",
+  "question": "ユーザー認証にJWTとセッションのどちらを使うべきか？",
+  "context": "design.md にはどちらの記載もない",
+  "status": "pending",
+  "escalatedTo": null,
+  "answer": null,
+  "answeredBy": null
+}
+```
+
+### 回答のドキュメント還元
+
+回答のうちドキュメント未記載のものは適切なドキュメントに追記:
+
+| 回答の種類 | 追記先 |
+|-----------|--------|
+| 要件・仕様に関する判断 | requirements.md |
+| 技術的な設計判断 | design.md |
+| プロジェクト横断の方針 | docs/einja/memory/decisions.md |
+| 再利用可能なパターン | docs/einja/memory/patterns.md |
+
+---
+
+## タスク完了フロー
+
+```
+Worker-1.1 作業中
+ │
+ ├─ 0. git rebase origin/issue/123-phase1（最新取り込み）
+ ├─ 1. task-exec 完了 → task/123-1.1 に commit & push
+ ├─ 2. CI 完了待機（gh run list ポーリング）
+ ├─ 3. gh pr create --base issue/123-phase1 --head task/123-1.1
+ ├─ 4. ステータスファイル: { status: "pr_created", pr: 456 }
+ └─ 5. claude プロセス終了
+
+Director 検知（ステータスファイル + プロセス監視）
+ │
+ ├─ manual モード: gh pr list --state merged ポーリング → マージ検知まで待機
+ ├─ task-group-auto: gh pr merge --squash --auto 実行
+ ├─ auto: CI通過確認後に gh pr merge --squash 実行
+ │
+ ├─ マージ検知後:
+ │   ├─ 他 active Worker にステータスで sync_required 通知
+ │   ├─ タスク worktree 削除 + tmux window kill
+ │   ├─ GitHub Issue チェックボックス更新
+ │   └─ 依存タスク起動判定 → 新 Worker 起動
+ │
+ └─ Phase 全タスク完了 → ステータスで Manager に報告
+
+Manager 検知
+ │
+ ├─ Phase PR 作成: issue/123-phase1 → issue/123
+ ├─ マージモードに応じた処理
+ ├─ マージ後: Phase worktree 削除
+ ├─ 他 active Phase に変更伝播
+ └─ 次 Phase 起動 or 全完了 → 最終 PR 作成
+```
+
+---
+
+## エラーリカバリ
+
+| 障害 | 検知 | リカバリ |
+|---|---|---|
+| Worker 異常終了（PR作成前） | tmux window 消失 + ステータス未更新 | リトライ（最大2回）→ 失敗時は Manager に報告 → 人間判断 |
+| Worker 異常終了（PR作成済み） | tmux window 消失 + PR あり | スキップ（PR マージ待ちのまま継続） |
+| Director 異常終了 | tmux window 消失 + ステータス未更新 | 各 Worker のステータスを確認 → 未完了 Worker のみ再実行 |
+| Manager 異常終了 | ユーザー手動 | `--resume` でステータスファイルから復元 |
+| rebase コンフリクト | git rebase 失敗 | einja-conflict-resolver Skill で自力解消 |
+| CI 失敗 | gh run status | 修正 → 再push → 再CI待機 |
+| CI 待機タイムアウト | 30分超過 | Manager に通知 → 人間判断 |
+
+---
+
+## `einja-task-exec` Skill との使い分け
+
+| 実行方法 | 用途 | 対象 | 推奨シーン |
+|---------|------|------|----------|
+| **`/einja:issue-exec`** | Issue全体の並列実行 | 複数Phase・複数タスクグループ | 大規模機能実装 |
+| **`einja-task-exec` Skill** | 単一タスクグループの実行 | 1つのタスクグループ | 品質重視、複雑な実装 |
+
+---
+
+## 関連ドキュメント
+
+- [タスク実行ワークフロー](./task-execute.md)
+- [タスク管理ガイドライン](../steering/task-management.md)
+- [仕様書作成ワークフロー](./task-execute.md#フェーズ1-issue仕様書作成-einja-issue-spec-create-skill)
+- [ブランチ運用戦略](../steering/branch-strategy.md)
+<!-- @einja:managed:end -->
+
+<!-- @einja:project-private:start id="issue-exec-workflow-project" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private: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/)
 
@@ -530,7 +530,7 @@ pnpm build
 環境構築が完了したら、以下のドキュメントも参照してください：
 
 - **[タスク実行ガイド](./task-execute.md)**: /task-execコマンドの使用方法
-- **[コーディング規約](../../../.claude/skills/einja-coding-standards/SKILL.md)**: コードスタイルと規約
+- **[コーディング規約](../steering/development/coding-standards.md)**: コードスタイルと規約
 - **[テストガイドライン](../einja/steering/development/testing-strategy.md)**: Vitestを使用したテスト戦略
 
 ## 質問・サポート
@@ -626,13 +626,75 @@ for cmd in gh vercel neonctl dotenvx; do
   command -v $cmd >/dev/null 2>&1 && echo "✅ $cmd: $(command -v $cmd)" || echo "❌ $cmd: 未インストール"
 done
 ```
-<!-- @einja:managed:end -->
 
----
+### 7. MCP Server (Serena)
+
+Serena MCPサーバーは **1プロジェクト1インスタンス** で共有され、worktree間でも再利用されます。
+
+#### 自動起動の仕組み
+
+```
+cd プロジェクト → direnv → ensure-serena.sh → Serena起動 → .mcp.json(http)で接続
+```
+
+1. `direnv` が `.envrc` を読み込む
+2. `.envrc` が `scripts/ensure-serena.sh` を `source` する
+3. スクリプトが `.serena-port` を確認し、必要に応じて起動
+4. `SERENA_PORT` 環境変数がエクスポートされる
+5. `.mcp.json` の `http://127.0.0.1:${SERENA_PORT:-9850}/mcp` で接続
+
+#### `.serena-port` ファイル仕様
+
+プロジェクトルートに自動生成される管理ファイル（`.gitignore` 対象）。
+
+- **形式**: `PORT PID`（スペース区切り、例: `9850 12345`）
+- **PIDベース所有権管理**: `kill -0 PID` でプロセス生存を確認
+  - PID生存 → 再利用（ポートをエクスポートして終了）
+  - PID死亡 → ファイル削除 → 新規起動
+
+> **なぜcurlではなくPIDか**: MCP streamable-http の `/mcp` はPOST専用。GETの `curl -sf` は405を返し「未起動」と誤判定するため、PIDチェックでプロトコル非依存の判定を行う。
+
+#### ポート自動解決
+
+- デフォルト: `9850`
+- ポート衝突時: `+1` で10回まで試行（9850〜9859）
+- 全ポート使用中: 警告メッセージを出力（direnvはブロックしない）
 
-<!-- @einja:seed:start id="local-server-environment-and-worktree-project" -->
-## プロジェクト固有の設定
+#### 手動操作
+
+```bash
+# 状態確認
+cat .serena-port  # PORT PID を表示
+
+# 停止
+./scripts/stop-serena.sh
+
+# 再起動
+./scripts/stop-serena.sh && direnv reload
+
+# 再起動（direnv経由）
+direnv reload
+```
+
+#### トラブルシューティング
+
+| 症状 | 原因 | 対処 |
+|------|------|------|
+| Serena接続エラー | プロセスが停止している | `direnv reload` で再起動 |
+| ポートが意図と違う | 別プロセスが使用中 | `lsof -i :9850` で確認、不要なら停止 |
+| ゾンビ `.serena-port` | プロセスが異常終了 | `rm .serena-port && direnv reload` |
+| uvx not found | uv未インストール | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+
+#### `.env.personal` でのオーバーライド
+
+デフォルトポートを変更したい場合:
+
+```bash
+# .env.personal に追記
+SERENA_PORT=9851
+```
+<!-- @einja:managed:end -->
 
-<!-- このセクションはプロジェクト固有の内容を追記する場所です -->
-<!-- einja syncで上書きされません -->
-<!-- @einja:seed:end -->
+<!-- @einja:project-private:start id="local-server-environment-and-worktree-project" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private:end -->

package/presets/default/docs/einja/instructions/neon-cli-reference.md

@@ -595,11 +595,6 @@ neonctl branches delete $BRANCH_ID --project-id $PROJECT_ID
 - [neonctl CLI公式ドキュメント](https://neon.tech/docs/reference/neon-cli)
 <!-- @einja:managed:end -->
 
----
-
-<!-- @einja:seed:start id="neon-cli-reference-project" -->
-## プロジェクト固有の設定
-
-<!-- このセクションはプロジェクト固有の内容を追記する場合はここに記載 -->
-<!-- einja syncで上書きされません -->
-<!-- @einja:seed:end -->
+<!-- @einja:project-private:start id="neon-cli-reference-project" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private:end -->

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 から統合的に呼び出されます。