zcf 2.10.2 → 2.11.0

package/templates/en/workflow/git/commands/git-worktree.md

@@ -1,301 +1,225 @@
 ---
-description: Manage Git worktrees, support add/list/remove/migrate operations, create in .zcf/ directory by default, auto-configure git ignore rules, support IDE quick open and content migration
-allowed-tools: Read(**), Exec(git worktree add, git worktree list, git worktree remove, git worktree prune, git branch, git checkout, git rev-parse, git stash, git cp, code, cursor, webstorm), Write(.git/info/exclude)
+description: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration
+allowed-tools: Read(**), Exec(git worktree add, git worktree list, git worktree remove, git worktree prune, git branch, git checkout, git rev-parse, git stash, git cp, detect-ide, open-ide, which, command, basename, dirname)
 argument-hint: <add|list|remove|prune|migrate> [path] [-b <branch>] [-o|--open] [--track] [--guess-remote] [--detach] [--checkout] [--lock] [--migrate-from <source-path>] [--migrate-stash]
 # examples:
-#   - /git-worktree add feature-ui                     # create worktree, ask whether to open in IDE by default
+#   - /git-worktree add feature-ui                     # create new branch 'feature-ui' from main/master
 #   - /git-worktree add feature-ui -o                  # create worktree and open directly in IDE
-#   - /git-worktree add hotfix -b fix/login -o         # create new branch, worktree and open in IDE directly
-#   - /git-worktree migrate feature-ui --from main     # migrate uncommitted content from main branch to feature-ui worktree
-#   - /git-worktree migrate feature-ui --stash         # migrate current stash content to feature-ui worktree
+#   - /git-worktree add hotfix -b fix/login -o         # create new branch 'fix/login' with path 'hotfix'
+#   - /git-worktree migrate feature-ui --from main     # migrate uncommitted content from main to feature-ui
+#   - /git-worktree migrate feature-ui --stash         # migrate current stash to feature-ui
 ---
 
 # Claude Command: Git Worktree
 
-**Purpose**: Provide Git worktree quick operations, manage multiple working trees in `.zcf/` directory by default, auto-handle git ignore configuration, support IDE quick open and cross-worktree content migration.
+Manage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.
+
+Execute commands directly and provide concise results.
 
 ---
 
 ## Usage
 
 ```bash
-# Add worktree (default in .zcf/)
-/git-worktree add <path>                           # checkout same-name branch to .zcf/<path>, ask whether to open IDE
-/git-worktree add <path> -b <branch>               # create new branch and add worktree
+# Basic operations
+/git-worktree add <path>                           # create new branch named <path> from main/master
+/git-worktree add <path> -b <branch>               # create new branch with specified name
 /git-worktree add <path> -o                        # create and open directly in IDE
-/git-worktree add <path> -b <branch> --open        # create new branch, worktree and open directly
-
-# Content migration
-/git-worktree migrate <target-path> --from <source-path>  # migrate uncommitted content
-/git-worktree migrate <target-path> --stash               # migrate stash content
-
-# Other operations
 /git-worktree list                                 # show all worktree status
 /git-worktree remove <path>                        # remove specified worktree
-/git-worktree prune                                # clean invalid worktree records
+/git-worktree prune                                # clean invalid worktree references
+
+# Content migration
+/git-worktree migrate <target> --from <source>     # migrate uncommitted content
+/git-worktree migrate <target> --stash             # migrate stash content
 ```
 
 ### Options
 
-| Option | Description |
-|--------|-------------|
-| `add <path>` | Add new worktree in `.zcf/<path>` |
-| `migrate <target>` | Migrate content to specified worktree |
-| `list` | List all worktrees and their status |
-| `remove <path>` | Remove worktree at specified path |
-| `prune` | Clean invalid worktree references |
-| `-b <branch>` | Create new branch and checkout to worktree |
-| `-o, --open` | Open directly in IDE after creation (skip prompt) |
-| `--from <source>` | Specify migration source path (migrate only) |
-| `--stash` | Migrate current stash content (migrate only) |
-| `--track` | Set new branch to track corresponding remote branch |
-| `--guess-remote` | Auto guess remote branch for tracking |
-| `--detach` | Create detached HEAD worktree |
-| `--checkout` | Checkout immediately after creation (default behavior) |
-| `--lock` | Lock worktree after creation |
+| Option             | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `add [<path>]`     | Add new worktree in `../.zcf/project-name/<path>`      |
+| `migrate <target>` | Migrate content to specified worktree                  |
+| `list`             | List all worktrees and their status                    |
+| `remove <path>`    | Remove worktree at specified path                      |
+| `prune`            | Clean invalid worktree references                      |
+| `-b <branch>`      | Create new branch and checkout to worktree             |
+| `-o, --open`       | Open directly in IDE after creation (skip prompt)      |
+| `--from <source>`  | Specify migration source path (migrate only)           |
+| `--stash`          | Migrate current stash content (migrate only)           |
+| `--track`          | Set new branch to track corresponding remote branch    |
+| `--guess-remote`   | Auto guess remote branch for tracking                  |
+| `--detach`         | Create detached HEAD worktree                          |
+| `--checkout`       | Checkout immediately after creation (default behavior) |
+| `--lock`           | Lock worktree after creation                           |
 
 ---
 
 ## What This Command Does
 
-### 1. **Environment Check**
-   - Confirm in Git repository via `git rev-parse --is-inside-work-tree`
+1. **Environment Check**
+   - Verify Git repository using `git rev-parse --is-inside-work-tree`
+   - Detect whether in main repo or existing worktree for smart path calculation
 
-### 2. **Ignore Rules Configuration**
-   - Check if `.git/info/exclude` contains `/.zcf/` rule
-   - Auto-add `/.zcf/` to `.git/info/exclude` if not exists
+2. **Smart Path Management**
+   - Auto-calculate project name from main repository path using worktree detection
+   - Create worktrees in structured `../.zcf/project-name/<path>` directory
+   - Handle both main repo and worktree execution contexts correctly
 
-### 3. **Worktree Operations**
-   - **add**: Create new worktree in `.zcf/<path>`
-   - **list**: Show all worktree paths, branches and status
-   - **remove**: Safely remove specified worktree
-   - **prune**: Clean orphaned worktree records
+```bash
+# Core path calculation logic for worktree detection
+get_main_repo_path() {
+  local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+  local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)
+
+  # Check if in worktree
+  if [[ "$git_common_dir" != "$current_toplevel/.git" ]]; then
+    # In worktree, derive main repo path from git-common-dir
+    dirname "$git_common_dir"
+  else
+    # In main repository
+    echo "$current_toplevel"
+  fi
+}
 
-### 4. **🆕 IDE Quick Open Feature**
-   - **Default behavior**: Ask whether to open new worktree in IDE after `add` operation
-   - **Direct open**: Use `-o/--open` parameter to skip prompt and open directly
-   - **IDE detection**: Auto-detect common IDEs (VS Code, Cursor, WebStorm, etc.)
-   - **Smart selection**: Recommend best choice based on project type and installed IDEs
+MAIN_REPO_PATH=$(get_main_repo_path)
+PROJECT_NAME=$(basename "$MAIN_REPO_PATH")
+WORKTREE_BASE="$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME"
 
-### 5. **🆕 Content Migration Feature**
-   - **Uncommitted content migration**: Migrate uncommitted changes from one worktree to another
-   - **Stash migration**: Apply current stash content to target worktree
-   - **Safety check**: Check target worktree status before migration to avoid conflicts
+# Always use absolute path to prevent nesting issues
+ABSOLUTE_WORKTREE_PATH="$WORKTREE_BASE/<path>"
+```
 
-### 6. **Path Handling**
-   - Auto-add `.zcf/` prefix to all relative paths
-   - Keep absolute paths as-is
-   - Auto-create `.zcf/` directory if not exists
+**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.
 
-### 7. **Branch Management**
-   - Support checking out existing branches or creating new branches
-   - Auto-handle remote branch tracking
-   - Provide branch status and HEAD position info
+3. **Worktree Operations**
+   - **add**: Create new worktree with smart branch/path defaults
+   - **list**: Display all worktrees with branches and status
+   - **remove**: Safely remove worktree and clean references
+   - **prune**: Clean orphaned worktree records
 
----
+4. **Smart Defaults**
+   - **Branch creation**: When no `-b` specified, create new branch using path name
+   - **Base branch**: New branches created from main/master branch
+   - **Path resolution**: Use branch name as path when unspecified
+   - **IDE integration**: Auto-detect and prompt for IDE opening
 
-## Enhanced Features
+5. **Content Migration**
+   - Migrate uncommitted changes between worktrees
+   - Apply stash content to target worktree
+   - Safety checks to prevent conflicts
 
-### 🖥️ **IDE Integration**
+6. **Safety Features**
+   - **Path conflict prevention**: Check for existing directories before creation
+   - **Branch checkout validation**: Ensure branches aren't already in use
+   - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree
+   - **Auto-cleanup on removal**: Clean both directory and git references
+   - **Clear status reporting**: Display worktree locations and branch status
 
-**Supported IDEs**
-- **VS Code**: `code <path>`
-- **Cursor**: `cursor <path>`  
-- **WebStorm**: `webstorm <path>`
-- **Others**: Configurable custom IDE commands
+---
 
-**Open Modes**
-```bash
-# Default: ask whether to open after creation
-/git-worktree add feature-ui
-# Output: 🖥️  Open .zcf/feature-ui in IDE? [y/n]:
+## Enhanced Features
 
-# Direct open: skip prompt
-/git-worktree add feature-ui -o
-# Output: 🚀 Opening .zcf/feature-ui in VS Code...
-```
+### IDE Integration
 
-**Smart Detection Flow**
-1. Check installed IDEs in system
-2. Recommend based on project type (e.g., recommend VS Code for Node.js projects)
-3. Provide selection menu for user choice (default mode)
-4. Remember user preference for next time
+- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim
+- **Smart prompting**: Ask to open in IDE after worktree creation
+- **Direct open**: Use `-o` flag to skip prompt and open immediately
+- **Custom configuration**: Configurable via git config
 
-### 📦 **Content Migration System**
+### Content Migration System
 
-**Migration Types**
 ```bash
-# Migrate uncommitted content from main branch
+# Migrate uncommitted changes
 /git-worktree migrate feature-ui --from main
+/git-worktree migrate hotfix --from ../other-worktree
 
-# Migrate from other worktree
-/git-worktree migrate hotfix --from .zcf/feature-ui
-
-# Migrate current stash
+# Migrate stash content
 /git-worktree migrate feature-ui --stash
-
-# Migrate specific stash
-/git-worktree migrate feature-ui --stash stash@{2}
 ```
 
-**Migration Flow**
-1. **Source check**: Verify source path exists and has uncommitted content
-2. **Target check**: Ensure target worktree working directory is clean
-3. **Content analysis**: Show files and changes to be migrated
-4. **Safe migration**: Use git native commands to ensure data safety
-5. **Result confirmation**: Show migration results and follow-up suggestions
+**Migration Flow**:
 
----
-
-## Safety Features
-
-- **Path check**: Prevent creating worktree in existing directory
-- **Branch conflict check**: Avoid same branch being checked out by multiple worktrees
-- **Auto cleanup**: Remove operation cleans both directory and git references
-- **Status display**: Clearly show each worktree's branch, commit and status
-
-### **Migration Safety Protection**
-- **Conflict detection**: Check for potential file conflicts before migration
-- **Backup mechanism**: Auto-create stash backup before migration
-- **Rollback support**: Provide rollback solution when migration fails
-- **Status validation**: Ensure source and target worktrees are in correct state
-
-### **IDE Integration Safety**
-- **Path validation**: Ensure IDE commands use correct paths
-- **Permission check**: Verify IDE executable permissions
-- **Error handling**: Friendly error messages when IDE startup fails
+1. Verify source has uncommitted content
+2. Ensure target worktree is clean
+3. Show changes to be migrated
+4. Execute safe migration using git commands
+5. Confirm results and suggest next steps
 
 ---
 
 ## Examples
 
-### **Basic Usage + IDE Open**
 ```bash
-# Create worktree and ask for IDE open (default behavior)
-/git-worktree add feature-ui
-# Output:
-# ✅ Worktree created at .zcf/feature-ui
-# 🖥️  Detected IDEs:
-#    1. VS Code (recommended)
-#    2. Cursor
-# Open this worktree in IDE? [1/2/n]: 1
-# 🚀 Opening .zcf/feature-ui in VS Code...
-
-# Create worktree and open IDE directly
-/git-worktree add feature-ui -o
-# Output:
-# ✅ Worktree created at .zcf/feature-ui
-# 🚀 Opening .zcf/feature-ui in VS Code...
-
-# Create new branch and open directly
-/git-worktree add hotfix -b fix/login --open
-# Output:
-# ✅ Created branch 'fix/login' and worktree at .zcf/hotfix
-# 🚀 Opening .zcf/hotfix in VS Code...
+# Basic usage
+/git-worktree add feature-ui                       # create new branch 'feature-ui' from main/master
+/git-worktree add feature-ui -b my-feature         # create new branch 'my-feature' with path 'feature-ui'
+/git-worktree add feature-ui -o                    # create and open in IDE directly
+
+# Content migration scenarios
+/git-worktree add feature-ui -b feature/new-ui     # create new feature worktree
+/git-worktree migrate feature-ui --from main       # migrate uncommitted changes
+/git-worktree migrate hotfix --stash               # migrate stash content
+
+# Management operations
+/git-worktree list                                 # view all worktrees
+/git-worktree remove feature-ui                    # remove unneeded worktree
+/git-worktree prune                                # clean invalid references
 ```
 
-### **Content Migration Scenarios**
-```bash
-# Scenario: developed some features on main branch, want to move to new branch
-# 1. Create new feature worktree
-/git-worktree add feature-ui -b feature/new-ui
-
-# 2. Migrate uncommitted content from main
-/git-worktree migrate feature-ui --from main
-# Output:
-# 📦 Found uncommitted content:
-#    M  src/components/Button.tsx
-#    A  src/components/Modal.tsx
-#    ??  src/styles/new-theme.css
-# 🔄 Migrating to .zcf/feature-ui...
-# ✅ Migration completed! Suggest committing these changes in new worktree.
-
-# 3. Ask whether to open IDE (since -o wasn't used during creation)
-# 🖥️  Open .zcf/feature-ui in IDE? [y/n]: y
-```
+**Example Output**:
 
-### **Stash Migration**
-```bash
-# Have some stashes, want to apply to specific worktree
-/git-worktree migrate hotfix --stash
-# Output:
-# 📋 Found stashes:
-#    stash@{0}: WIP on main: fix user login
-#    stash@{1}: WIP on main: update docs
-# Select stash to migrate [0/1]: 0
-# 🔄 Applying stash@{0} to .zcf/hotfix...
-# ✅ Stash content applied successfully!
 ```
-
-### **List and Manage Worktrees**
-```bash
-# View all worktrees
-/git-worktree list
-# Output:
-# /path/to/project                    [main]     ← main working tree
-# /path/to/project/.zcf/feature-ui    [feature/new-ui]
-# /path/to/project/.zcf/hotfix        [fix/login]
-
-# Remove unneeded worktree
-/git-worktree remove feature-ui
-# Output:
-# ✅ Worktree .zcf/feature-ui removed successfully
-
-# Clean invalid references
-/git-worktree prune
-# Output:
-# 🧹 Pruned 0 worktree entries
+✅ Worktree created at ../.zcf/project-name/feature-ui
+🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y
+🚀 Opening ../.zcf/project-name/feature-ui in VS Code...
 ```
 
 ---
 
 ## Directory Structure
 
-After using this command, project structure will be:
 ```
-your-project/
-├── .git/
-├── .zcf/                    # worktree directory (ignored by git)
-│   ├── feature-ui/          # feature-ui branch working tree
-│   ├── hotfix/              # hotfix branch working tree
-│   ├── debug/               # debug working tree
-│   └── .worktree-config     # worktree config file
-├── src/                     # main working tree source
-└── package.json             # main working tree files
+parent-directory/
+├── your-project/            # main project
+│   ├── .git/
+│   └── src/
+└── .zcf/                    # worktree management
+    └── your-project/        # project worktrees
+        ├── feature-ui/      # feature branch
+        ├── hotfix/          # hotfix branch
+        └── debug/           # debug worktree
 ```
 
 ---
 
 ## Configuration
 
-### **IDE Preferences**
-Command saves user preferences in `.zcf/.worktree-config`:
-```json
-{
-  "preferredIDE": "code",
-  "autoOpenIDE": false,
-  "migrateBackup": true,
-  "defaultWorktreeDir": ".zcf"
-}
-```
+### IDE Configuration
+
+- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim
+- Configurable via git config for custom IDEs
+- Auto-detection with priority-based selection
+
+### Custom IDE Setup
 
-### **Custom IDE Commands**
 ```bash
-# Set custom IDE
-git config worktree.ide.custom "subl %s"  # Sublime Text
-git config worktree.ide.preferred "custom"
+# Configure custom IDE
+git config worktree.ide.custom.sublime "subl %s"
+git config worktree.ide.preferred "sublime"
+
+# Control auto-detection
+git config worktree.ide.autodetect true  # default
 ```
 
 ---
 
 ## Notes
 
-- **Performance optimization**: Worktrees share `.git` directory, saving disk space
-- **IDE support**: Most modern IDEs support multi-worktree projects
-- **Cleanup suggestion**: Regularly run `prune` to clean invalid references
-- **Branch protection**: Avoid operations on protected branches (like main/master)
-- **Migration limitation**: Can only migrate uncommitted changes, use `git cherry-pick` for committed content
-- **IDE requirement**: IDE command-line tools must be installed and in PATH
-- **Cross-platform support**: IDE detection and startup support Windows, macOS, Linux
+- **Performance**: Worktrees share `.git` directory, saving disk space
+- **Safety**: Path conflict prevention and branch checkout validation
+- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits
+- **IDE requirement**: Command-line tools must be in PATH
+- **Cross-platform**: Supports Windows, macOS, Linux
 
----
+---

package/templates/zh-CN/memory/mcp.md

@@ -1,6 +1,7 @@
 ## MCP 服务使用指南
 
 ### 文档与代码查询
+
 - **Context7**: 查询最新库文档和代码示例
   - 使用场景：需要了解新框架或库的用法时
   - 示例：查询 React Hooks、Vue Composition API 等
@@ -10,13 +11,15 @@
   - 示例：查看项目架构、贡献指南等
 
 ### 信息搜索
+
 - **Exa**: AI 驱动的网页搜索
   - 实时搜索最新技术资讯
   - 抓取特定 URL 的完整内容
   - 返回最相关的搜索结果
 
 ### 浏览器自动化
+
 - **Playwright**: 浏览器操控
   - 自动化网页操作和测试
   - 截图和页面分析
-  - 表单填写和交互测试
+  - 表单填写和交互测试

package/templates/zh-CN/memory/personality.md

@@ -1 +1 @@
-你是一名经验丰富的[专业领域，例如：软件开发工程师 / 系统设计师 / 代码架构师]，专注于构建[核心特长，例如：高性能 / 可维护 / 健壮 / 领域驱动]的解决方案。
+你是一名经验丰富的[专业领域，例如：软件开发工程师 / 系统设计师 / 代码架构师]，专注于构建[核心特长，例如：高性能 / 可维护 / 健壮 / 领域驱动]的解决方案。

package/templates/zh-CN/memory/rules.md

@@ -16,17 +16,14 @@
 **请严格遵循以下工作流程和输出要求：**
 
 1.  **深入理解与初步分析（理解阶段）：**
-
     - 详细审阅提供的[资料/代码/项目描述]，全面掌握其当前架构、核心组件、业务逻辑及痛点。
     - 在理解的基础上，初步识别项目中潜在的**KISS, YAGNI, DRY, SOLID**原则应用点或违背现象。
 
 2.  **明确目标与迭代规划（规划阶段）：**
-
     - 基于用户需求和对现有项目的理解，清晰定义本次迭代的具体任务范围和可衡量的预期成果。
     - 在规划解决方案时，优先考虑如何通过应用上述原则，实现更简洁、高效和可扩展的改进，而非盲目增加功能。
 
 3.  **分步实施与具体改进（执行阶段）：**
-
     - 详细说明你的改进方案，并将其拆解为逻辑清晰、可操作的步骤。
     - 针对每个步骤，具体阐述你将如何操作，以及这些操作如何体现**KISS, YAGNI, DRY, SOLID**原则。例如：
       - "将此模块拆分为更小的服务，以遵循 SRP 和 OCP。"
@@ -42,4 +39,4 @@
       - **本次迭代已完成的核心任务**及其具体成果。
       - **本次迭代中，你如何具体应用了** **KISS, YAGNI, DRY, SOLID** **原则**，并简要说明其带来的好处（例如，代码量减少、可读性提高、扩展性增强）。
       - **遇到的挑战**以及如何克服。
-      - **下一步的明确计划和建议。**
+      - **下一步的明确计划和建议。**