create-einja-app 0.3.1 → 0.3.3

package/templates/default/CLAUDE.md

@@ -10,6 +10,16 @@
 3. **影響範囲の最小化**: 変更は必要な箇所のみ。関係ないコードに触れない
 4. **直接実装の禁止**: あなたは絶対に直接実装を行わない。すべての作業はsubagentに委託し、可能な限り並行で呼び出す。サブエージェントの出力はユーザにも見える場所に出力すること
 5. **実装品質の自己検証**: 複雑な変更では完了前に「よりエレガントな方法はないか」を自問する。ただし単純な修正には不要
+6. **Skill-First原則**: 実装着手前に `einja-skill-first` Skillで「Skillを先に作るべきか」を評価する。反復性のある作業はSkill化してから本作業を開始する
+
+## Agent Teams の使用制限
+
+**Agent Teams（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`）はユーザーが明示的にチーム編成を指示した場合のみ使用すること。**
+
+- 通常のタスクではサブエージェント（`Task`ツール）を使用する
+- 「チームで」「複数agentで並列に」等の明示的な指示があった場合のみAgent Teamsを起動する
+- チーム実行時は `einja-team-exec` Skillの手順に従う
+- 判断に迷う場合はサブエージェントを使用する（デフォルト動作）
 
 ## サブエージェント委託ルール
 
@@ -17,7 +27,6 @@
 
 | 作業 | 委託先 |
 |------|--------|
-| コンフリクト解消 | `conflict-resolver` |
 | Codex作業（レビュー・実装支援等） | `codex-agent` |
 | フロントエンド アーキテクチャ設計 | `frontend-architect` |
 | フロントエンド デザイン実装 | `design-engineer` |
@@ -31,9 +40,21 @@
 | `einja-task-commit` | コミット・プッシュ |
 | `einja-conflict-resolver` | gitコンフリクト解消 |
 | `einja-skill-creator` | Skill作成・更新 |
+| `einja-skill-first` | 作業前のSkill作成必要性評価（Plan/einja-issue-spec-create時に自動起動） |
 | `einja-infra-maintenance` | インフラ環境セットアップ・メンテナンス |
-| `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回まで）
 
 ## コード変更時の動作方針
 
@@ -41,9 +62,16 @@
 
 ### 必須フロー
 1. 問題・要件を調査・分析する
-2. 修正計画を `docs/plans/` に作成し提示する
-3. **ユーザーの明示的な承認を得る**
-4. 承認後、`docs/plans/todo-{plan名}.md` で進捗管理しながら実装を開始する
+2. 修正計画を `docs/plans/` に作成する
+3. `einja-skill-first` で「Skill を先に作るべきか」を評価する
+   - Plan mode中は `UserPromptSubmit` hookにより自動でリマインダーが注入される
+   - `.claude/skills/einja-skill-first/SKILL.md` を読み込んで評価を実施する
+   - 推奨判定 → AskUserQuestion でユーザーに提案
+   - 承認 → 計画の TODO-0 に Skill 作成を追加
+   - 不要判定 → そのまま次へ進む
+   - ※ スキップ基準に該当する場合は評価自体を省略
+4. 計画をユーザーに提示し、**明示的な承認を得る**
+5. 承認後、`docs/plans/todo-{plan名}.md` で進捗管理しながら実装を開始する（TODO-0 があれば Skill 作成から）
 
 ### 例外（承認不要）
 - 読み取り専用操作（質問への回答、情報調査、コード調査）
@@ -109,7 +137,7 @@
 
 Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は以下のSkillを参照:
 - `einja-project-overview` - 構成、技術スタック、頻出コマンド
-- `einja-coding-standards` - コーディング規約、インポートパス規約
+- `docs/einja/steering/development/coding-standards.md` - コーディング規約、インポートパス規約
 - `einja-infra-maintenance` - 開発環境セットアップ、サーバー管理
 
 ## マネージドディレクトリ（編集禁止）
@@ -147,6 +175,11 @@ Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は
 - 番号付きリスト: 詳細説明が必要な場合
 - 推奨オプションには `（推奨）` と理由を付記
 
+### 選択肢の記述ルール
+- 各選択肢の `description` に**必ず詳細説明・注意点・補足**を記載する
+- トレードオフ、影響範囲、前提条件など判断に必要な情報を含める
+- ラベルだけで選択させない。ユーザーが十分な情報に基づいて判断できるようにする
+
 ## 報告ルール
 
 ### 出力形式
@@ -189,6 +222,10 @@ Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は
 - サブエージェントの「完了」報告のみで完了判定しない
 - 検証をスキップして完了宣言しない
 
+<!-- @einja:project-private:start id="claude-md-project" -->
+<!-- プロジェクト固有の情報を記入 -->
+<!-- @einja:project-private:end -->
+
 <!-- @einja:excluded:start -->
 ## このリポジトリ限定の設定
 
@@ -200,9 +237,9 @@ Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は
 
 | キーワード | 使用するSkill |
 |-----------|--------------|
-| `einja cli` `@einja/dev-cli` `公開` `リリース` `publish` `release` | `.claude/skills/dev-cli-release/SKILL.md` |
-| `create-einja-app` | `.claude/skills/create-einja-app-release/SKILL.md` |
-| `インフラ` `環境変数管理` `Vercel` `Neon` `デプロイ設定` `GitHub Secrets` `環境セットアップ` `GitHub Actions` `CI/CD` `ワークフロー` | `.claude/skills/einja-infra-maintenance/SKILL.md` |
+| `einja cli` `@einja/dev-cli` `create-einja-app` `公開` `リリース` `publish` `release` | `.claude/skills/einja-npm-release/SKILL.md` |
+| `インフラ` `環境変数管理` `Vercel` `Neon` `デプロイ設定` `GitHub Secrets` `環境セットアップ` `ローカルセットアップ` `ローカル環境` `セットアップ` `GitHub Actions` `CI/CD` `ワークフロー` | `.claude/skills/einja-infra-maintenance/SKILL.md` |
+| `Skill作るべき？` `Skill化` `skill-first` `Skill-first` | `.claude/skills/einja-skill-first/SKILL.md` |
 
 ### CLIパッケージの二重管理禁止
 
@@ -218,6 +255,20 @@ Turborepoモノレポ構成（pnpm workspaces）。詳細が必要な場合は
 | `.vscode/settings.json` | `presets/default/.vscode/settings.json` | 単純コピー |
 | `docs/einja/` (memory,cli除く) | `presets/default/docs/einja/` | 単純コピー（sync + init対象） |
 | `CLAUDE.md` | `presets/default/CLAUDE.md.template` | **変換生成** |
+| `scripts/` (`_`プレフィクス除く) | `presets/default/scripts/` | 単純コピー |
 
 **コピー先のファイルは直接編集禁止**（ビルド時に上書きされる）
+
+### パッケージビルド仕様（テンプレートリポジトリ限定）
+
+`@einja/dev-cli` と `create-einja-app` の2パッケージのビルド・テンプレート仕様については、以下のSkillを参照すること:
+
+`.claude/skills/cli-package-specs/SKILL.md`
+
+### マネージドディレクトリの編集について（テンプレートリポジトリ限定）
+
+このリポジトリは `docs/einja/` の**原本（Single Source of Truth）**である。
+上記「マネージドディレクトリ（編集禁止）」ルールは下流リポジトリ（create-einja-appで生成されたプロジェクト）向けであり、
+**このリポジトリでは `docs/einja/` 配下の全ファイルを編集してよい**。
+変更はビルド時に `presets/default/` へ自動コピーされる。
 <!-- @einja:excluded:end -->

package/templates/default/README.md

@@ -14,13 +14,19 @@ Turborepo + Next.js 15 + Auth.js + Prisma 構成のプロジェクトテンプ
 ```
 einja-management-template/
 ├── apps/
-│   └── web/                      # メイン管理画面アプリ
+│   ├── web/                      # メイン管理画面アプリ
+│   │   ├── src/
+│   │   │   ├── app/              # Next.js App Router
+│   │   │   ├── components/       # アプリ固有のコンポーネント
+│   │   │   └── lib/
+│   │   │       ├── auth/         # アプリ固有の認証設定
+│   │   │       └── ...           # アプリ固有のユーティリティ
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   └── admin/                    # 管理者画面アプリ
 │       ├── src/
 │       │   ├── app/              # Next.js App Router
-│       │   ├── components/       # アプリ固有のコンポーネント
-│       │   └── lib/
-│       │       ├── auth/         # アプリ固有の認証設定
-│       │       └── ...           # アプリ固有のユーティリティ
+│       │   └── components/       # アプリ固有のコンポーネント
 │       ├── package.json
 │       └── tsconfig.json
 ├── packages/
@@ -38,7 +44,9 @@ einja-management-template/
 │   │   └── src/
 │   │       ├── domain/           # ドメイン層
 │   │       ├── infrastructure/   # Prismaクライアント等
-│   │       └── utils/            # 共通ユーティリティ
+│   │       ├── core/             # 共通コアモジュール
+│   │       └── testing/          # テストユーティリティ
+│   ├── admin-ui/                 # 管理者画面専用UIコンポーネント
 │   └── ui/                       # 共通UIコンポーネント（shadcn/ui）
 ├── turbo.json                    # Turborepoの設定
 ├── pnpm-workspace.yaml          # pnpmワークスペース設定
@@ -61,6 +69,8 @@ einja-management-template/
 
 ### 開発環境セットアップ
 
+> 📖 各コマンドで何が実行されるかの詳細は [セットアップフローガイド](docs/einja/instructions/setup-flow.md) を参照してください。
+
 #### 初回セットアップ（初めての方）
 
 ```bash
@@ -171,13 +181,14 @@ pnpm db:studio        # Prisma Studio起動
 # 特定のワークスペースでコマンド実行
 pnpm --filter @repo/web dev
 pnpm --filter @repo/web build
+pnpm --filter @repo/admin dev
 ```
 
 ### データベース設定
 
 #### Docker Compose サービス
 
-- **postgres**: PostgreSQL 15
+- **postgres**: PostgreSQL 16
   - ポート: `${POSTGRES_PORT:-25432}` (ホスト) → 5432 (コンテナ)
   - データベース: ブランチ名から自動生成（例: `main`, `feature_auth`）
   - ユーザー: `postgres`
@@ -190,7 +201,7 @@ pnpm --filter @repo/web build
 docker-compose logs -f postgres
 
 # データベースに直接接続
-docker-compose exec postgres psql -U postgres -d einja_management
+docker-compose exec postgres psql -U postgres -d main
 
 # データベースをリセット
 docker-compose down -v
@@ -220,6 +231,7 @@ pnpm db:studio
 - **@repo/config**: Biome, TypeScriptの共通設定
 - **@repo/front-core**: フロントエンド共通層（認証共通設定、hooks、utils、context）
 - **@repo/server-core**: バックエンド共通層（Prismaクライアント・スキーマ、ドメインロジック）
+- **@repo/admin-ui**: 管理者画面専用UIコンポーネント
 - **@repo/ui**: 共通UIコンポーネント（shadcn/ui）
 
 ### 開発ワークフロー
@@ -288,8 +300,8 @@ rm -rf .turbo apps/*/.turbo packages/*/.turbo
 
 詳細は以下のドキュメントを参照してください：
 
-- [コーディング規約](./.claude/skills/einja-coding-standards/SKILL.md)
-- [コンポーネント設計ガイドライン](./.claude/skills/einja-component-design/SKILL.md)
+- [コーディング規約](./docs/einja/steering/development/coding-standards.md)
+- [コンポーネント設計ガイドライン](./docs/einja/steering/development/component-design.md)
 - [テスト戦略](./docs/einja/steering/development/testing-strategy.md)
 - [コードレビューガイドライン](./docs/einja/steering/development/review-guidelines.md)
 - [コミットルール](./docs/einja/steering/commit-rules.md)

package/templates/default/apps/admin/package.json

@@ -28,7 +28,7 @@
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
     "lucide-react": "^0.523.0",
-    "next": "15.3.3",
+    "next": "15.3.9",
     "next-auth": "^5.0.0-beta.28",
     "next-themes": "^0.4.6",
     "postcss": "^8.5.6",

package/templates/default/apps/admin/tsconfig.json

@@ -8,7 +8,8 @@
     ],
     "paths": {
       "@/*": [
-        "./src/*"
+        "./src/*",
+        "../../packages/server-core/src/*"
       ],
       "@admin/*": [
         "./src/*",

package/templates/default/apps/web/package.json

@@ -28,7 +28,7 @@
     "bcryptjs": "^3.0.2",
     "clsx": "^2.1.1",
     "lucide-react": "^0.523.0",
-    "next": "15.3.3",
+    "next": "15.3.9",
     "next-auth": "^5.0.0-beta.28",
     "next-themes": "^0.4.6",
     "postcss": "^8.5.6",

package/templates/default/apps/web/tsconfig.json

@@ -8,7 +8,8 @@
     ],
     "paths": {
       "@/*": [
-        "./src/*"
+        "./src/*",
+        "../../packages/server-core/src/*"
       ],
       "@web/*": [
         "./src/*",

package/templates/default/docs/plans/agile-munching-knuth.md

@@ -0,0 +1,161 @@
+# Plan: create-einja-app を Claude Code から実行可能にする
+
+## Context
+
+`create-einja-app` CLI は inquirer v12 による対話的プロンプトを使用しているため、Claude Code の Bash ツール（非対話実行のみ）からは実行できない。AskUserQuestion で回答を収集し、CLI 引数として渡す方式で解決する。
+
+**2段階の実装:**
+1. CLI に非対話モード（全パラメータの CLI 引数化）を追加
+2. Claude Code コマンドを作成し、AskUserQuestion → CLI 引数変換の仲介を行う
+
+## スコープ
+
+- `create` コマンドのみ（`sync` コマンドは対象外 — 既に `einja:einja-sync` Skill が存在）
+- 既存の対話モードは完全に維持（後方互換）
+
+---
+
+## Step 1: `CliConfigOverrides` 型の追加
+
+**ファイル:** `packages/create-einja-app/src/types/index.ts`
+
+```typescript
+export type CliConfigOverrides = {
+  packageScope?: string;
+  authMethod?: "default" | "none";
+  setupEinjaCli?: boolean;
+  useCurrentDir?: boolean;
+  postgresPort?: number;
+  containerName?: string;
+  appId?: string;
+  portRangeStart?: number;
+  rangeSize?: number;
+};
+```
+
+## Step 2: commander オプション追加
+
+**ファイル:** `packages/create-einja-app/src/cli.ts`
+
+既存の `--skip-git`, `--skip-install` に加えて以下を追加:
+
+| フラグ | 説明 |
+|--------|------|
+| `-y, --yes` | 非対話モード（デフォルト値使用） |
+| `--scope <scope>` | パッケージスコープ |
+| `--auth <method>` | 認証方式: `default` \| `none` |
+| `--no-einja-cli` | einja CLI セットアップをスキップ |
+| `--use-current-dir` | カレントディレクトリに展開 |
+| `--postgres-port <port>` | PostgreSQL ポート |
+| `--container-name <name>` | Docker コンテナ名 |
+| `--app-id <id>` | アプリ ID |
+| `--port-range-start <port>` | ポート範囲開始 |
+| `--range-size <size>` | ポート範囲サイズ |
+
+## Step 3: `create.ts` の 3 パターン分岐
+
+**ファイル:** `packages/create-einja-app/src/commands/create.ts`
+
+### 3.1 `CreateOptions` 拡張
+
+CLI引数の全フィールドを受け取れるよう拡張。
+
+### 3.2 `validateCliOverrides()` 追加
+
+CLI 引数のバリデーション（scope 正規表現、auth 値チェック、ポート番号範囲）。エラー時は `process.exit(1)`。
+
+### 3.3 メインフロー変更
+
+```
+options.yes → パターンA: 完全非対話（デフォルト + overrides）
+overrides あり → パターンB: 部分指定（未指定フィールドのみ対話）
+それ以外 → パターンC: 完全対話（従来通り）
+```
+
+### 3.4 `buildConfigWithDefaults()` 追加
+
+`--yes` 時にデフォルト値 + overrides から `ProjectConfig` を構築。既存の L80-95 のハードコード部分をこの関数に統合。
+
+## Step 4: `project.ts` の overrides 対応
+
+**ファイル:** `packages/create-einja-app/src/prompts/project.ts`
+
+- `promptProjectConfig(defaultProjectName?, overrides?)` にシグネチャ変更
+- 各質問に `when: () => overrides?.xxx === undefined` を追加し、CLI 引数で指定済みの項目をスキップ
+- worktree 関連 overrides が 1 つでもある場合、`customizeWorktree` 質問をスキップ（カスタマイズ済みとみなす）
+- 最終的な return で `overrides?.xxx ?? answers.xxx` のマージ
+
+## Step 5: `post-setup.ts` の非対話対応
+
+**ファイル:** `packages/create-einja-app/src/generators/post-setup.ts`
+
+- `PostSetupOptions` に `yes?: boolean` を追加
+- `yes === true` 時は `promptAndExecuteDirenvAllow` の inquirer をスキップし、デフォルト動作（direnv allow 実行）
+
+## Step 6: Claude Code コマンド作成
+
+**ファイル:** `.claude/commands/einja/create-app.md`
+
+AskUserQuestion で回答を収集し、CLI 引数に変換して実行するコマンド。
+
+### フロー
+
+```
+1. AskUserQuestion: プロジェクト名（テキスト入力）
+2. AskUserQuestion: 基本設定 3問同時
+   - パッケージスコープ（@repo / @{プロジェクト名} / カスタム）
+   - 認証方式（NextAuth.js / なし）
+   - einja CLI セットアップ（はい / いいえ）
+3. AskUserQuestion: Worktree カスタマイズ（はい / いいえ）
+4. (条件付き) AskUserQuestion: Worktree 詳細設定
+5. ビルド + CLI 実行:
+   pnpm -F create-einja-app build
+   node packages/create-einja-app/dist/cli.js <name> --yes \
+     --scope <scope> --auth <auth> [--no-einja-cli] [worktree flags] \
+     --skip-install
+6. 結果報告
+```
+
+**注意:** `--skip-install` をデフォルトで付与（Claude Code 内でのインストールは別途制御）
+
+## Step 7: テスト
+
+### ユニットテスト
+- `overrides` マージの正確性
+- CLI 引数バリデーションのエラーケース
+
+### 統合テスト
+- `--yes` でデフォルト生成
+- `--yes --scope @custom --auth none` でカスタム生成
+- 部分指定（`--scope` のみ）で残りが対話入力されること
+
+### 手動検証
+```bash
+# 非対話モード
+node packages/create-einja-app/dist/cli.js test-proj --yes --skip-git --skip-install
+
+# 部分指定
+node packages/create-einja-app/dist/cli.js test-proj --scope @test --skip-git --skip-install
+```
+
+---
+
+## 変更ファイル一覧
+
+| ファイル | 変更内容 |
+|---------|---------|
+| `packages/create-einja-app/src/types/index.ts` | `CliConfigOverrides` 型追加 |
+| `packages/create-einja-app/src/cli.ts` | commander オプション追加 |
+| `packages/create-einja-app/src/commands/create.ts` | 3パターン分岐、バリデーション、デフォルト構築 |
+| `packages/create-einja-app/src/prompts/project.ts` | overrides 対応、`when` 条件追加 |
+| `packages/create-einja-app/src/generators/post-setup.ts` | `yes` オプション追加 |
+| `.claude/commands/einja/create-app.md` | 新規: AskUserQuestion 仲介コマンド |
+| テストファイル（既存 + 新規） | 非対話モードのテストケース追加 |
+
+## 検証方法
+
+1. `pnpm -F create-einja-app build` が成功すること
+2. `pnpm -F create-einja-app typecheck` が成功すること
+3. `pnpm -F create-einja-app test` が成功すること
+4. 手動で `--yes` モード実行し、プロジェクトが正しく生成されること
+5. Claude Code から `/einja:create-app` で実行できること

package/templates/default/docs/plans/agile-riding-nova.md

@@ -0,0 +1,158 @@
+# Plan: セットアップフロー統合ドキュメント作成
+
+## Context
+
+`scripts/init.sh`、`post-setup.ts`、`setup-dev.ts` など複数のセットアップ関連ファイルがあるが、
+**どの操作でどのファイルが呼ばれ何が起きるか**を横断的にまとめたドキュメントが存在しない。
+3つのシナリオ（create-einja-app初回 / einja sync / clone後セットアップ）ごとのフローを
+mermaid図 + テーブルで整理したドキュメントを作成する。
+
+## 変更ファイル
+
+| ファイル | 変更内容 |
+|---------|---------|
+| `docs/einja/instructions/setup-flow.md` | **新規作成** セットアップフロー統合ドキュメント |
+| `README.md` | 「パッケージ利用者向け」+「開発環境セットアップ」にドキュメント参照リンクを追加 |
+
+> **NOTE**: `docs/einja/instructions/` はこのリポジトリが原本。ビルド時に `presets/default/` へ自動コピーされ、`einja sync` で各プロジェクトに配布される。直接 `presets/default/` を編集する必要はない。
+
+## TODO
+
+### TODO-1: `docs/einja/instructions/setup-flow.md` 新規作成
+
+3シナリオのセットアップフローを網羅するドキュメントを作成する。
+
+#### ドキュメント構成
+
+```
+# セットアップフローガイド
+
+## 概要
+  - 3つのシナリオの簡潔な説明
+
+## シナリオ別フロー
+
+### 1. npx create-einja-app（新規プロジェクト作成）
+  - mermaid シーケンス図
+  - 処理テーブル（ファイル → 処理内容）
+
+### 2. git clone 後の環境構築（既存プロジェクトへの参加）
+  - mermaid シーケンス図
+  - 処理テーブル
+
+### 3. einja sync（テンプレート同期）
+  - mermaid シーケンス図
+  - 処理テーブル（dev-cli sync / create-einja-app sync）
+
+## ファイル別リファレンス
+  - 各スクリプト/ファイルの役割と呼び出し元の逆引きテーブル
+
+## 処理の重複と設計意図
+  - init.sh と dev:setup の重複箇所の説明（冪等性の意図）
+```
+
+#### シナリオ1: `npx create-einja-app` フロー
+
+```
+ユーザー: npx create-einja-app my-app
+  │
+  ├── cli.ts → createCommand()
+  │     ├── 対話プロンプト（プロジェクト名、スコープ、認証方式等）
+  │     ├── generateTemplate() ← generators/template.ts
+  │     │     └── テンプレートコピー + 変数置換 + リネーム
+  │     └── execPostSetup() ← generators/post-setup.ts
+  │           ├── Step 0: bash scripts/init.sh (stdio: inherit)
+  │           │     ├── Step 1: Volta インストール（未導入時のみ）
+  │           │     ├── Step 2: シェル設定（VOLTA_FEATURE_PNPM）
+  │           │     ├── Step 3: Node.js / pnpm インストール
+  │           │     ├── Step 4: pnpm install
+  │           │     └── Step 5: direnv allow（direnv存在時のみ）
+  │           ├── PATH補完（~/.volta/bin を process.env.PATH に追加）
+  │           ├── Step 1: pnpm install + pnpm db:generate
+  │           ├── Step 2: pnpm env:rotate-secrets --all --non-interactive
+  │           ├── Step 3: git init + git add . + git commit
+  │           ├── Step 4: npx @einja/dev-cli init（setupEinjaCli=true時のみ）
+  │           └── 完了メッセージ表示
+```
+
+#### シナリオ2: clone後の環境構築フロー
+
+```
+開発者: git clone → cd project
+  │
+  ├── ./scripts/init.sh（手動実行・初回のみ）
+  │     ├── Step 1: Volta インストール
+  │     ├── Step 2: シェル設定
+  │     ├── Step 3: Node.js / pnpm インストール
+  │     ├── Step 4: pnpm install
+  │     └── Step 5: direnv allow
+  │
+  ├── exec $SHELL（ターミナル再起動）
+  │
+  ├── pnpm dev:setup（= tsx scripts/setup-dev.ts）
+  │     ├── Step 1-3: Volta確認 / シェル設定 / Node.js・pnpm インストール
+  │     ├── Step 4: direnv インストール（macOS: brew install direnv）
+  │     ├── Step 5: direnv hook シェル追記
+  │     ├── Step 6: dotenvx インストール
+  │     ├── Step 7: .env 作成（.env.local + .env.keys で復号）
+  │     ├── Step 8: .env.personal 作成 + GITHUB_TOKEN（対話入力）
+  │     ├── Step 9: direnv allow → .envrc評価（Serena MCP自動起動含む）
+  │     ├── Step 10: PostgreSQL 起動（docker-compose up -d postgres）
+  │     └── Step 11: pnpm db:generate + pnpm db:push
+  │
+  └── pnpm dev:bg（開発サーバー起動）
+```
+
+#### シナリオ3: einja sync フロー
+
+```
+開発者: einja sync（Claude Code Skill経由）
+  │
+  ├── dev-cli sync
+  │     ├── 同期対象:
+  │     │     ├── .claude/commands/einja/, .claude/agents/einja/
+  │     │     ├── .claude/skills/einja-*/, .claude/hooks/
+  │     │     ├── docs/einja/, scripts/
+  │     │     ├── .envrc（envカテゴリ, 単一ファイル）
+  │     │     └── .vscode/settings.json（toolsカテゴリ, 単一ファイル）
+  │     ├── マージ: 3方向マージ + マーカーベース
+  │     ├── コンフリクト解消（対話式）
+  │     └── 依存関係チェック + インストール
+  │
+  └── create-einja-app sync
+        ├── 同期対象: CI/CD, docker, monorepo設定, root config, scripts/
+        ├── テンプレート変数置換あり
+        └── バックアップ作成 + マージ
+```
+
+#### ファイル別リファレンステーブル
+
+| ファイル | 役割 | 呼び出し元 |
+|---------|------|-----------|
+| `scripts/init.sh` | Volta/Node/pnpm/direnv 初期導入 | create-einja-app (post-setup.ts) / 手動実行 |
+| `scripts/setup-dev.ts` | 環境構築一式（.env, DB, direnv等） | `pnpm dev:setup` |
+| `scripts/ensure-serena.sh` | Serena MCP サーバー起動 | `.envrc` (direnv) |
+| `scripts/env-rotate-secrets.ts` | 秘密鍵ローテーション | create-einja-app (post-setup.ts) / `pnpm env:rotate-secrets` |
+| `.envrc` | dotenv読み込み + worktree間.env.personal共有 + Serena MCP起動 | direnv（シェルディレクトリ進入時に自動評価） |
+| `generators/post-setup.ts` | プロジェクト作成後のセットアップ | create-einja-app create コマンド |
+| `generators/template.ts` | テンプレート展開・変数置換 | create-einja-app create コマンド |
+| `generators/sync.ts` | テンプレート同期 | create-einja-app sync コマンド |
+| `packages/cli/src/commands/sync.ts` | Claude Code関連ファイル同期 | dev-cli sync コマンド |
+
+### TODO-2: README.md に参照リンク追加
+
+**対象**: `README.md` の「パッケージ利用者向け」セクション（L8付近）
+
+「使い分けガイド」の後に、セットアップフローガイドへの参照を1行追加:
+
+```markdown
+> 📖 各シナリオのセットアップで何が実行されるかの詳細は [セットアップフローガイド](docs/einja/instructions/setup-flow.md) を参照してください。
+```
+
+また「パッケージ開発者向け > 開発環境セットアップ」セクション（L158付近）にも同様のリンクを追加。
+
+## 検証
+
+1. ドキュメントのmermaid図がGitHubで正しくレンダリングされるか確認
+2. README.mdのリンクが正しいパスを指しているか確認
+3. `git diff --stat` で意図しないファイルが含まれていないこと