@aku11i/phantom 0.3.0 → 0.4.0

package/README.ja.md

@@ -8,14 +8,18 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/node/v/@aku11i/phantom.svg)](https://nodejs.org)
 
-[インストール](#-インストール) • [クイックスタート](#-クイックスタート) • [なぜPhantom？](#-なぜphantom) • [ドキュメント](#-ドキュメント)
+[インストール](#-インストール) • [基本的な使い方](#-基本的な使い方) • [なぜPhantom？](#-なぜphantom) • [ドキュメント](#-ドキュメント)
 
 </div>
 
-## ✨ 主な機能
+## ✨ 概要
+
+Phantomは、Git worktreeの管理を劇的にシンプルにするCLIツールです。複数の機能開発、バグ修正、PRレビューを並行して進める現代の開発ワークフローに最適化されています。
+
+### 主な特徴
 
 - 🚀 **シンプルなWorktree管理** - 直感的なコマンドでGit worktreeを作成・管理
-- 🔄 **シームレスなコンテキスト切り替え** - stashやcommitせずに異なる機能間をジャンプ
+- 🔄 **シームレスなコンテキスト切り替え** - stashやcommitせずに異なる作業間を瞬時に移動
 - 🤖 **AI対応** - 複数のAIコーディングエージェントを並行実行するのに最適
 - 🎯 **ブランチとWorktreeの同期** - 各worktreeに対応するブランチを自動作成
 - 🐚 **インタラクティブシェル** - SSH風のworktreeナビゲーション体験
@@ -23,21 +27,26 @@
 
 ## 🤔 なぜPhantom？
 
-現代の開発ワークフローでは、複数の機能を同時に作業することがよくあります。AIコーディングエージェントを並行実行したり、開発しながらPRをレビューしたり、単純に複数の機能をマルチタスクで作業したりする場合、複数のGit worktreeの管理は面倒になりがちです。
+現代の開発ワークフローでは、複数の機能を同時に作業することが一般的になっています。Git worktreeは素晴らしい機能ですが、パスとブランチを個別に指定する必要があり、少し面倒です。
+
+### Git worktreeを使う際の問題点
+
+素のGit worktreeを使う場合、worktreeのパス、ブランチ名、ベースブランチなどを毎回指定する必要があります。また、作業を切り替える際はディレクトリを移動する必要があり、複数の作業を頻繁に切り替える場合は少し手間がかかります。
 
-**問題点：**
-- Git worktreeコマンドは冗長で複雑
-- ブランチとworktreeを別々に管理するのはエラーが起きやすい
-- コンテキストの切り替えには複数のコマンドが必要
-- 同じコードベースで並行してAIエージェントを実行するのは困難
+### Phantomの解決策
+
+```bash
+# 従来の方法
+git worktree add -b feature ../project-feature origin/main
+cd ../project-feature
+
+# Phantomを使用
+phantom create feature --shell
+```
 
-**Phantomの解決策：**
-- 1つのコマンドでworktreeとブランチの両方を作成: `phantom create feature-x`
-- 即座にコンテキストを切り替え: `phantom shell feature-x`
-- ディレクトリを変更せずにコマンドを実行: `phantom exec feature-x npm test`
-- 複数のAIエージェントとの「並行バイブコーディング」に最適
+Phantomは、worktreeとブランチの作成を1つのコマンドにまとめ、作業スペース間の移動や操作を簡単にします。
 
-## 🚀 クイックスタート
+## 🚀 基本的な使い方
 
 ```bash
 # Phantomをインストール
@@ -88,10 +97,6 @@ npm link
 
 ## 📖 ドキュメント
 
-### コアコンセプト
-
-**Worktree** 🌳 - Phantomによって管理されるGit worktree。各worktreeは特定のブランチや機能のための独立したワークスペースで、競合なしに並行開発が可能です。
-
 ### コマンド概要
 
 #### Worktree管理
@@ -128,11 +133,52 @@ phantom shell <name>
 
 ### 環境変数
 
-Phantomで管理されたworktree内で作業する際、以下の環境変数が利用可能です：
+`phantom shell`でインタラクティブシェルを開いた際、以下の環境変数が設定されます：
 
+- `PHANTOM` - phantom shellから起動されたすべてのプロセスに"1"がセットされる
 - `PHANTOM_NAME` - 現在のworktreeの名前
 - `PHANTOM_PATH` - worktreeディレクトリへの絶対パス
 
+## 💡 ユースケース
+
+Phantomは単なるworktreeラッパーではなく、開発生産性を劇的に向上させるツールです。以下に実際の使用例を紹介します。
+
+### tmuxとの統合
+
+tmuxとPhantomを組み合わせることで、驚くほど効率的なワークフローを実現できます：
+
+```bash
+# 新しいtmuxウィンドウを開いて、同時にworktreeを作成
+tmux new-window 'phantom create new-feature --shell'
+```
+
+このたった1行のコマンドで：
+1. `new-feature`用の新しいGit worktreeを作成 ✨
+2. 新しいtmuxウィンドウを開く 🪟
+3. 新しいworktreeでインタラクティブシェルを起動 🚀
+
+複数の機能を並行して開発する際に、各機能を独立したtmuxウィンドウで管理できます。
+
+### VS Codeとの統合
+
+```bash
+# worktreeを作成してすぐにVS Codeで開く
+phantom create feature-auth
+phantom exec feature-auth code .
+```
+
+### 並行開発ワークフロー
+
+```bash
+# 機能開発中にバグレポートが来た場合
+phantom create hotfix-critical  # バグ修正用のworktreeを作成
+phantom shell hotfix-critical   # すぐに作業開始
+
+# 修正後、元の機能開発に戻る
+exit  # hotfixシェルを終了
+phantom shell feature-awesome  # 機能開発を続行
+```
+
 ## 🔄 Phantom vs Git Worktree
 
 | 機能 | Git Worktree | Phantom |
@@ -183,10 +229,10 @@ Phantomの新しいバージョンをリリースするには：
    ```bash
    # パッチリリース（バグ修正）の場合
    npm version patch
-   
+
    # マイナーリリース（新機能）の場合
    npm version minor
-   
+
    # メジャーリリース（破壊的変更）の場合
    npm version major
    ```
@@ -208,7 +254,7 @@ Phantomの新しいバージョンをリリースするには：
      --title "Phantom v<version>" \
      --generate-notes \
      --target main
-   
+
    # v0.1.3の例:
    gh release create v0.1.3 \
      --title "Phantom v0.1.3" \
@@ -251,4 +297,4 @@ Phantomの新しいバージョンをリリースするには：
 
 <div align="center">
 <a href="https://github.com/aku11i">aku11i</a>と<a href="https://claude.ai">Claude</a>により👻で作成
-</div>
+</div>

package/README.md

@@ -8,11 +8,15 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/node/v/@aku11i/phantom.svg)](https://nodejs.org)
 
-[Installation](#-installation) • [Quick Start](#-quick-start) • [Why Phantom?](#-why-phantom) • [Documentation](#-documentation) • [日本語](./README.ja.md)
+[Installation](#-installation) • [Basic Usage](#-basic-usage) • [Why Phantom?](#-why-phantom) • [Documentation](#-documentation) • [日本語](./README.ja.md)
 
 </div>
 
-## ✨ Key Features
+## ✨ Overview
+
+Phantom is a CLI tool that dramatically simplifies Git worktree management. It's optimized for modern development workflows where you need to work on multiple features, bug fixes, and PR reviews in parallel.
+
+### Key Features
 
 - 🚀 **Simplified Worktree Management** - Create and manage Git worktrees with intuitive commands
 - 🔄 **Seamless Context Switching** - Jump between different features without stashing or committing
@@ -23,21 +27,26 @@
 
 ## 🤔 Why Phantom?
 
-Modern development workflows often require working on multiple features simultaneously. Whether you're running AI coding agents in parallel, reviewing PRs while developing, or simply multitasking across features, managing multiple Git worktrees can be cumbersome.
+Modern development workflows often require working on multiple features simultaneously. While Git worktree is a powerful feature, it requires specifying paths and branches separately, which can be cumbersome.
+
+### The Manual Process
+
+When using Git worktree directly, you need to specify the worktree path, branch name, and base branch each time. Additionally, switching between tasks requires navigating directories, which can be a bit tedious when frequently switching between multiple parallel tasks.
 
-**The Problem:**
-- Git worktree commands are verbose and complex
-- Managing branches and worktrees separately is error-prone
-- Switching contexts requires multiple commands
-- Running parallel AI agents on the same codebase is challenging
+### The Phantom Solution
+
+```bash
+# Traditional approach
+git worktree add -b feature ../project-feature origin/main
+cd ../project-feature
+
+# With Phantom
+phantom create feature --shell
+```
 
-**The Phantom Solution:**
-- One command to create both worktree and branch: `phantom create feature-x`
-- Instant context switching: `phantom shell feature-x`
-- Execute commands without changing directories: `phantom exec feature-x npm test`
-- Perfect for "parallel vibe coding" with multiple AI agents
+Phantom combines worktree and branch creation into a single command, making it easy to switch between and work in different workspaces.
 
-## 🚀 Quick Start
+## 🚀 Basic Usage
 
 ```bash
 # Install Phantom
@@ -88,10 +97,6 @@ npm link
 
 ## 📖 Documentation
 
-### Core Concepts
-
-**Worktrees** 🌳 - Git worktrees managed by Phantom. Each worktree is an isolated workspace for a specific branch or feature, allowing parallel development without conflicts.
-
 ### Commands Overview
 
 #### Worktree Management
@@ -128,11 +133,52 @@ phantom shell <name>
 
 ### Environment Variables
 
-When working within a worktree managed by Phantom, these environment variables are available:
+When opening an interactive shell with `phantom shell`, these environment variables are set:
 
+- `PHANTOM` - Set to "1" for all processes spawned from phantom shell
 - `PHANTOM_NAME` - Name of the current worktree
 - `PHANTOM_PATH` - Absolute path to the worktree directory
 
+## 💡 Use Cases
+
+Phantom is more than just a worktree wrapper - it's a productivity multiplier. Here are some real-world examples:
+
+### tmux Integration
+
+Combine tmux with Phantom for an incredibly efficient workflow:
+
+```bash
+# Open a new tmux window and create a worktree in one command
+tmux new-window 'phantom create new-feature --shell'
+```
+
+This single line:
+1. Creates a new Git worktree for `new-feature` ✨
+2. Opens a new tmux window 🪟
+3. Starts an interactive shell in the new worktree 🚀
+
+When developing multiple features in parallel, you can manage each feature in its own tmux window.
+
+### VS Code Integration
+
+```bash
+# Create a worktree and immediately open it in VS Code
+phantom create feature-auth
+phantom exec feature-auth code .
+```
+
+### Parallel Development Workflow
+
+```bash
+# When a bug report comes in during feature development
+phantom create hotfix-critical  # Create worktree for the fix
+phantom shell hotfix-critical   # Start working immediately
+
+# After fixing, return to your feature
+exit  # Exit the hotfix shell
+phantom shell feature-awesome  # Continue feature development
+```
+
 ## 🔄 Phantom vs Git Worktree
 
 | Feature | Git Worktree | Phantom |
@@ -183,10 +229,10 @@ To release a new version of Phantom:
    ```bash
    # For patch releases (bug fixes)
    npm version patch
-   
+
    # For minor releases (new features)
    npm version minor
-   
+
    # For major releases (breaking changes)
    npm version major
    ```
@@ -208,7 +254,7 @@ To release a new version of Phantom:
      --title "Phantom v<version>" \
      --generate-notes \
      --target main
-   
+
    # Example for v0.1.3:
    gh release create v0.1.3 \
      --title "Phantom v0.1.3" \