@aku11i/phantom 0.3.0 → 0.5.0

package/README.ja.md

@@ -8,36 +8,46 @@
 [![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ナビゲーション体験
 - ⚡ **ゼロ設定** - 賢明なデフォルト設定ですぐに使用可能
+- 📦 **ゼロ依存** - 外部依存関係がなく軽量で高速
 
 ## 🤔 なぜPhantom？
 
-現代の開発ワークフローでは、複数の機能を同時に作業することがよくあります。AIコーディングエージェントを並行実行したり、開発しながらPRをレビューしたり、単純に複数の機能をマルチタスクで作業したりする場合、複数のGit worktreeの管理は面倒になりがちです。
+現代の開発ワークフローでは、複数の機能を同時に作業することが一般的になっています。Git worktreeは素晴らしい機能ですが、パスとブランチを個別に指定する必要があり、少し面倒です。
+
+### Git worktreeを使う際の問題点
+
+素のGit worktreeを使う場合、worktreeのパス、ブランチ名、ベースブランチなどを毎回指定する必要があります。また、作業を切り替える際はディレクトリを移動する必要があり、複数の作業を頻繁に切り替える場合は少し手間がかかります。
+
+### Phantomの解決策
+
+```bash
+# 従来の方法
+git worktree add -b feature ../project-feature origin/main
+cd ../project-feature
 
-**問題点：**
-- Git worktreeコマンドは冗長で複雑
-- ブランチとworktreeを別々に管理するのはエラーが起きやすい
-- コンテキストの切り替えには複数のコマンドが必要
-- 同じコードベースで並行してAIエージェントを実行するのは困難
+# 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をインストール
@@ -46,6 +56,9 @@ npm install -g @aku11i/phantom
 # 新しいworktreeを作成
 phantom create feature-awesome
 
+# 既存のブランチにアタッチ
+phantom attach existing-branch
+
 # worktreeにジャンプ
 phantom shell feature-awesome
 
@@ -88,10 +101,6 @@ npm link
 
 ## 📖 ドキュメント
 
-### コアコンセプト
-
-**Worktree** 🌳 - Phantomによって管理されるGit worktree。各worktreeは特定のブランチや機能のための独立したワークスペースで、競合なしに並行開発が可能です。
-
 ### コマンド概要
 
 #### Worktree管理
@@ -100,6 +109,9 @@ npm link
 # 対応するブランチを持つ新しいworktreeを作成
 phantom create <name>
 
+# 既存のブランチにworktreeとしてアタッチ
+phantom attach <branch-name>
+
 # すべてのworktreeとその現在のステータスをリスト表示
 phantom list
 
@@ -128,16 +140,61 @@ 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 --shell new-feature'
+```
+
+このたった1行のコマンドで：
+1. `new-feature`用の新しいGit worktreeを作成 ✨
+2. 新しいtmuxウィンドウを開く 🪟
+3. 新しいworktreeでインタラクティブシェルを起動 🚀
+
+複数の機能を並行して開発する際に、各機能を独立したtmuxウィンドウで管理できます。
+
+### VS Codeとの統合
+
+```bash
+# worktreeを作成してすぐにVS Codeで開く
+phantom create --exec "code ." new-feature
+phantom create --exec "cursor ." new-feature # Cursorでも動作します！
+
+# 既存のブランチにアタッチしてVS Codeで開く
+phantom attach --exec "code ." feature/existing-branch
+```
+
+### 並行開発ワークフロー
+
+```bash
+# 機能開発中にバグレポートが来た場合
+phantom create hotfix-critical  # バグ修正用のworktreeを作成
+phantom shell hotfix-critical   # すぐに作業開始
+
+# 修正後、元の機能開発に戻る
+exit  # hotfixシェルを終了
+phantom shell feature-awesome  # 機能開発を続行
+```
+
 ## 🔄 Phantom vs Git Worktree
 
 | 機能 | Git Worktree | Phantom |
 |---------|--------------|---------|
 | worktree + ブランチの作成 | `git worktree add -b feature ../project-feature` | `phantom create feature` |
+| 既存のブランチにアタッチ | `git worktree add ../project-feature feature` | `phantom attach feature` |
 | worktreeのリスト表示 | `git worktree list` | `phantom list` |
 | worktreeへの移動 | `cd ../project-feature` | `phantom shell feature` |
 | worktreeでコマンド実行 | `cd ../project-feature && npm test` | `phantom exec feature npm test` |
@@ -155,7 +212,7 @@ pnpm install
 pnpm test
 
 # 型チェック
-pnpm type-check
+pnpm typecheck
 
 # リンティング
 pnpm lint
@@ -183,10 +240,10 @@ Phantomの新しいバージョンをリリースするには：
    ```bash
    # パッチリリース（バグ修正）の場合
    npm version patch
-   
+
    # マイナーリリース（新機能）の場合
    npm version minor
-   
+
    # メジャーリリース（破壊的変更）の場合
    npm version major
    ```
@@ -208,7 +265,7 @@ Phantomの新しいバージョンをリリースするには：
      --title "Phantom v<version>" \
      --generate-notes \
      --target main
-   
+
    # v0.1.3の例:
    gh release create v0.1.3 \
      --title "Phantom v0.1.3" \
@@ -216,6 +273,33 @@ Phantomの新しいバージョンをリリースするには：
      --target main
    ```
 
+7. **リリースノートを分かりやすく更新**
+   - 自動生成されたリリースノートをレビュー
+   - 重要な詳細についてはPRの説明を確認
+   - リリースノートをよりユーザーフレンドリーに更新：
+     - 変更をカテゴリー別にグループ化（機能、バグ修正、改善）
+     - 新機能には使用例を追加
+     - 変更の影響を平易な言葉で説明
+     - セキュリティ修正と破壊的変更を強調
+   
+   ```bash
+   # リリースノートを編集
+   gh release edit v<version> --notes "$(cat <<'EOF'
+   ## 🚀 v<version> の新機能
+   
+   ### ✨ 新機能
+   - 使用例付きの機能説明
+   
+   ### 🐛 バグ修正
+   - 修正内容の明確な説明
+   
+   ### 🛠️ 改善
+   - パフォーマンス、セキュリティ、その他の改善
+   
+   EOF
+   )"
+   ```
+
 ビルドプロセスは`prepublishOnly`スクリプトによって自動的に処理され、以下を行います：
 - すべてのテストとチェックを実行
 - esbuildを使用してTypeScriptソースをJavaScriptにビルド
@@ -251,4 +335,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
@@ -20,24 +24,30 @@
 - 🎯 **Branch-Worktree Sync** - Automatically creates matching branches for each worktree
 - 🐚 **Interactive Shell** - SSH-like experience for worktree navigation
 - ⚡ **Zero Configuration** - Works out of the box with sensible defaults
+- 📦 **Zero Dependencies** - Lightweight and fast with no external dependencies
 
 ## 🤔 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 Phantom Solution
+
+```bash
+# Traditional approach
+git worktree add -b feature ../project-feature origin/main
+cd ../project-feature
 
-**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
+# 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
@@ -46,6 +56,9 @@ npm install -g @aku11i/phantom
 # Create a new worktree
 phantom create feature-awesome
 
+# Attach to an existing branch
+phantom attach existing-branch
+
 # Jump into the worktree
 phantom shell feature-awesome
 
@@ -88,10 +101,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
@@ -100,6 +109,9 @@ npm link
 # Create a new worktree with a matching branch
 phantom create <name>
 
+# Attach to an existing branch as a worktree
+phantom attach <branch-name>
+
 # List all worktrees with their current status
 phantom list
 
@@ -128,16 +140,61 @@ 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 --shell new-feature'
+```
+
+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 --exec "code ." new-feature
+phantom create --exec "cursor ." new-feature # also works with cursor!!
+
+# Attach to existing branch and open in VS Code
+phantom attach --exec "code ." feature/existing-branch
+```
+
+### 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 |
 |---------|--------------|---------|
 | Create worktree + branch | `git worktree add -b feature ../project-feature` | `phantom create feature` |
+| Attach to existing branch | `git worktree add ../project-feature feature` | `phantom attach feature` |
 | List worktrees | `git worktree list` | `phantom list` |
 | Navigate to worktree | `cd ../project-feature` | `phantom shell feature` |
 | Run command in worktree | `cd ../project-feature && npm test` | `phantom exec feature npm test` |
@@ -155,7 +212,7 @@ pnpm install
 pnpm test
 
 # Type checking
-pnpm type-check
+pnpm typecheck
 
 # Linting
 pnpm lint
@@ -183,10 +240,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 +265,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" \
@@ -216,6 +273,33 @@ To release a new version of Phantom:
      --target main
    ```
 
+7. **Update release notes for clarity**
+   - Review the auto-generated release notes
+   - Check PR descriptions for important details
+   - Update the release notes to be more user-friendly:
+     - Group changes by category (Features, Bug Fixes, Improvements)
+     - Add usage examples for new features
+     - Explain the impact of changes in plain language
+     - Highlight security fixes and breaking changes
+   
+   ```bash
+   # Edit the release notes
+   gh release edit v<version> --notes "$(cat <<'EOF'
+   ## 🚀 What's New in v<version>
+   
+   ### ✨ New Features
+   - Feature description with usage example
+   
+   ### 🐛 Bug Fixes
+   - Clear description of what was fixed
+   
+   ### 🛠️ Improvements
+   - Performance, security, or other improvements
+   
+   EOF
+   )"
+   ```
+
 The build process is automatically handled by the `prepublishOnly` script, which:
 - Runs all tests and checks
 - Builds the TypeScript source to JavaScript using esbuild