zcf 2.10.2 → 2.11.0

package/templates/en/workflow/bmad/commands/bmad-init.md

@@ -12,87 +12,89 @@ This command initializes BMad Method in your project.
 ## Implementation
 
 ```javascript
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
+const { execSync } = require('node:child_process')
+const fs = require('node:fs')
+const path = require('node:path')
 
 async function initBmad() {
   // Check if already installed and get version
-  const manifestPath = path.join(process.cwd(), '.bmad-core', 'install-manifest.yaml');
-  let needsInstall = true;
-  let currentVersion = null;
-  
+  const manifestPath = path.join(process.cwd(), '.bmad-core', 'install-manifest.yaml')
+  let needsInstall = true
+  let currentVersion = null
+
   if (fs.existsSync(manifestPath)) {
     try {
       // Simple version check - just check if file exists
       // Full YAML parsing would require js-yaml package
-      const manifestContent = fs.readFileSync(manifestPath, 'utf8');
-      const versionMatch = manifestContent.match(/version:\s*(.+)/);
+      const manifestContent = fs.readFileSync(manifestPath, 'utf8')
+      const versionMatch = manifestContent.match(/version:\s*(.+)/)
       if (versionMatch) {
-        currentVersion = versionMatch[1].trim();
+        currentVersion = versionMatch[1].trim()
       }
-      
+
       // Get latest version from npm
-      const latestVersion = execSync('npm view bmad-method version', { encoding: 'utf8' }).trim();
-      
+      const latestVersion = execSync('npm view bmad-method version', { encoding: 'utf8' }).trim()
+
       if (currentVersion === latestVersion) {
-        console.log(`✅ BMad Method is up to date (v${currentVersion})`);
-        console.log('You can use BMad commands to begin your workflow');
-        needsInstall = false;
-      } else {
-        console.log(`🔄 BMad Method update available: v${currentVersion} → v${latestVersion}`);
+        console.log(`✅ BMad Method is up to date (v${currentVersion})`)
+        console.log('You can use BMad commands to begin your workflow')
+        needsInstall = false
       }
-    } catch (error) {
-      console.log('⚠️  Could not verify BMad version, will reinstall');
+      else {
+        console.log(`🔄 BMad Method update available: v${currentVersion} → v${latestVersion}`)
+      }
+    }
+    catch (error) {
+      console.log('⚠️  Could not verify BMad version, will reinstall')
     }
   }
-  
+
   if (needsInstall === false) {
-    return;
+    return
   }
-  
+
   // Install BMad
-  console.log('🚀 Installing BMad Method...');
+  console.log('🚀 Installing BMad Method...')
   try {
     execSync('echo -e "1\\n" | npx bmad-method@latest install -f -d . -i claude-code', {
       stdio: 'inherit',
       cwd: process.cwd(),
       shell: true
-    });
-    
-    console.log('✅ BMad Method installed successfully!');
-    console.log('');
-    console.log('═══════════════════════════════════════════════════════════════');
-    console.log('📌 IMPORTANT: Please restart Claude Code to load BMad agents');
-    console.log('═══════════════════════════════════════════════════════════════');
-    console.log('');
-    console.log('📂 Installation Details:');
-    console.log('   • All agents and task commands are installed in:');
-    console.log('     .claude/commands/BMad/');
-    console.log('');
-    console.log('🔧 Git Configuration (Optional):');
-    console.log('   If you prefer not to commit BMad workflow files, add these to .gitignore:');
-    console.log('     • .bmad-core');
-    console.log('     • .claude/commands/BMad');
-    console.log('     • docs/');
-    console.log('');
-    console.log('🚀 Getting Started:');
-    console.log('   1. Restart Claude Code');
-    console.log('   2. For first-time users, run:');
-    console.log('      /BMad:agents:bmad-orchestrator *help');
-    console.log('      This will start the BMad workflow guidance system');
-    console.log('');
-    console.log('💡 Tip: The BMad Orchestrator will help you choose the right workflow');
-    console.log('       and guide you through the entire development process.');
-    
-  } catch (error) {
-    console.error('❌ Failed to install BMad:', error.message);
-    process.exit(1);
+    })
+
+    console.log('✅ BMad Method installed successfully!')
+    console.log('')
+    console.log('═══════════════════════════════════════════════════════════════')
+    console.log('📌 IMPORTANT: Please restart Claude Code to load BMad agents')
+    console.log('═══════════════════════════════════════════════════════════════')
+    console.log('')
+    console.log('📂 Installation Details:')
+    console.log('   • All agents and task commands are installed in:')
+    console.log('     .claude/commands/BMad/')
+    console.log('')
+    console.log('🔧 Git Configuration (Optional):')
+    console.log('   If you prefer not to commit BMad workflow files, add these to .gitignore:')
+    console.log('     • .bmad-core')
+    console.log('     • .claude/commands/BMad')
+    console.log('     • docs/')
+    console.log('')
+    console.log('🚀 Getting Started:')
+    console.log('   1. Restart Claude Code')
+    console.log('   2. For first-time users, run:')
+    console.log('      /BMad:agents:bmad-orchestrator *help')
+    console.log('      This will start the BMad workflow guidance system')
+    console.log('')
+    console.log('💡 Tip: The BMad Orchestrator will help you choose the right workflow')
+    console.log('       and guide you through the entire development process.')
+  }
+  catch (error) {
+    console.error('❌ Failed to install BMad:', error.message)
+    process.exit(1)
   }
 }
 
 // Execute
-initBmad();
+initBmad()
 ```
 
 ## Notes
@@ -100,4 +102,4 @@ initBmad();
 - This command requires npm/npx to be available
 - The installation will download the latest BMad Method package
 - User must restart Claude Code after installation for agents to load properly
-- BMad Method includes its own built-in state tracking system
+- BMad Method includes its own built-in state tracking system

package/templates/en/workflow/common/agents/get-current-datetime.md

@@ -0,0 +1,29 @@
+---
+name: get-current-datetime
+description: Execute date command and return ONLY the raw output. No formatting, headers, explanations, or parallel agents.
+tools: Bash, Read, Write
+color: cyan
+---
+
+Execute `date` and return ONLY the command output.
+
+```bash
+date
+```
+
+DO NOT add any text, headers, formatting, or explanations.
+DO NOT add markdown formatting or code blocks.
+DO NOT add "Current date and time is:" or similar phrases.
+DO NOT use parallel agents.
+
+Just return the raw bash command output exactly as it appears.
+
+Example response: `Mon 28 Jul 2025 23:59:42 CST`
+
+Format options if requested:
+
+- Filename: Add `+"%Y-%m-%d_%H%M%S"`
+- Readable: Add `+"%Y-%m-%d %H:%M:%S %Z"`
+- ISO: Add `+"%Y-%m-%dT%H:%M:%S%z"`
+
+Use the get-current-datetime agent to get accurate timestamps instead of manually writing time information.

package/templates/en/workflow/common/agents/init-architect.md

@@ -0,0 +1,114 @@
+---
+name: init-architect
+description: Adaptive initialization: concise at root + detailed at module level; staged traversal with coverage reporting
+tools: Read, Write, Glob, Grep
+color: orange
+---
+
+# Initialization Architect (Adaptive Version)
+
+> No exposed parameters; internal adaptive three levels: quick summary / module scanning / deep supplementation. Ensures incremental updates and resumable runs with coverage reporting and next-step recommendations.
+
+## I. General Constraints
+
+- Do not modify source code; only generate/update documentation and `.claude/index.json`.
+- **Ignore Rules Retrieval Strategy**:
+  1. Prioritize reading the `.gitignore` file from the project root directory
+  2. If `.gitignore` does not exist, use the following default ignore rules: `node_modules/**,.git/**,.github/**,dist/**,build/**,.next/**,__pycache__/**,*.lock,*.log,*.bin,*.pdf,*.png,*.jpg,*.jpeg,*.gif,*.mp4,*.zip,*.tar,*.gz`
+  3. Merge ignore patterns from `.gitignore` with default rules
+- For large files/binaries, only record paths without reading content.
+
+## II. Staged Strategy (Automatic Intensity Selection)
+
+1. **Stage A: Repository Census (Lightweight)**
+   - Use multiple `Glob` calls in batches to get file inventory (avoid single-call limits), doing:
+     - File counting, language proportions, directory topology, module candidate discovery (package.json, pyproject.toml, go.mod, Cargo.toml, apps/_, packages/_, services/_, cmd/_, etc.).
+   - Generate `Module Candidate List`, annotating each candidate module with: language, entry file guesses, test directory existence, config file existence.
+2. **Stage B: Module Priority Scanning (Medium)**
+   - For each module, try reading in the following order (batched, paginated):
+     - Entry and startup: `main.ts`/`index.ts`/`cmd/*/main.go`/`app.py`/`src/main.rs`, etc.
+     - External interfaces: routes, controllers, API definitions, proto/openapi
+     - Dependencies and scripts: `package.json scripts`, `pyproject.toml`, `go.mod`, `Cargo.toml`, config directories
+     - Data layer: `schema.sql`, `prisma/schema.prisma`, ORM models, migration directories
+     - Testing: `tests/**`, `__tests__/**`, `*_test.go`, `*.spec.ts`, etc.
+     - Quality tools: `eslint/ruff/golangci` configurations
+   - Form "module snapshots", extracting only high-signal fragments and paths, not pasting large code blocks.
+3. **Stage C: Deep Supplementation (Triggered As Needed)**
+   - Trigger conditions (any one suffices):
+     - Repository overall small (fewer files) or single module small file count;
+     - After Stage B, still cannot determine key interfaces/data models/testing strategies;
+     - Root or module `CLAUDE.md` missing information items.
+   - Action: **Additional paginated reading** for target directories, filling gaps.
+
+> Note: If pagination/attempts reach tool or time limits, must **write partial results early** and explain in summary "why stopped here" and "next-step recommended directory list".
+
+## III. Artifacts and Incremental Updates
+
+1.  **Write Root-level `CLAUDE.md`**
+    - If exists, insert/update `Change Log (Changelog)` at the top.
+    - Root structure (concise yet global):
+      - Project Vision
+      - Architecture Overview
+      - **✨ New: Module Structure Diagram (Mermaid)**
+        - Above the "Module Index" table, generate a Mermaid `graph TD` tree diagram based on identified module paths.
+        - Each node should be clickable and link to the corresponding module's `CLAUDE.md` file.
+        - Example syntax:
+
+          ```mermaid
+          graph TD
+              A["(Root) My Project"] --> B["packages"];
+              B --> C["auth"];
+              B --> D["ui-library"];
+              A --> E["services"];
+              E --> F["audit-log"];
+
+              click C "./packages/auth/CLAUDE.md" "View auth module docs"
+              click D "./packages/ui-library/CLAUDE.md" "View ui-library module docs"
+              click F "./services/audit-log/CLAUDE.md" "View audit-log module docs"
+          ```
+
+      - Module Index (table format)
+      - Running and Development
+      - Testing Strategy
+      - Coding Standards
+      - AI Usage Guidelines
+      - Change Log (Changelog)
+
+2.  **Write Module-level `CLAUDE.md`**
+    - Place in each module directory, suggested structure:
+      - **✨ New: Relative Path Breadcrumbs**
+        - At the **top** of each module `CLAUDE.md`, insert a relative path breadcrumb line linking to parent directories and root `CLAUDE.md`.
+        - Example (located at `packages/auth/CLAUDE.md`):
+          `[Root Directory](../../CLAUDE.md) > [packages](../) > **auth**`
+      - Module Responsibilities
+      - Entry and Startup
+      - External Interfaces
+      - Key Dependencies and Configuration
+      - Data Models
+      - Testing and Quality
+      - Frequently Asked Questions (FAQ)
+      - Related File List
+      - Change Log (Changelog)
+3.  **`.claude/index.json`**
+    - Record: current timestamp (provided via parameters), root/module lists, entry/interface/test/important paths for each module, **scan coverage**, ignore statistics, whether truncated due to limits (`truncated: true`).
+
+## IV. Coverage and Resumability
+
+- Calculate and print each run:
+  - Estimated total files, scanned file count, coverage percentage;
+  - Coverage summary and gaps for each module (missing interfaces, tests, data models, etc.);
+  - Top ignored/skipped directories and reasons (ignore rules/large files/time or call limits).
+- Write "gap list" to `index.json`, prioritize filling gaps on next run (**breakpoint resumable scanning**).
+
+## V. Result Summary (Print to Main Dialog)
+
+- Root/module `CLAUDE.md` creation or update status;
+- Module list (path + one-sentence responsibility);
+- Coverage and major gaps;
+- If not fully read: explain "why stopped here" and list **recommended next steps** (e.g., "suggest priority supplemental scanning: packages/auth/src/controllers, services/audit/migrations").
+
+## VI. Time Format and Usage
+
+- Use relative paths;
+- Time information: Use the timestamp provided via command parameters and write in ISO-8601 format in `index.json`.
+- Do not manually write time information; use the provided timestamp parameter to ensure time accuracy.

package/templates/en/workflow/common/commands/init-project.md

@@ -0,0 +1,53 @@
+---
+description: Initialize project AI context, generate/update root-level and module-level CLAUDE.md indexes
+allowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)
+argument-hint: <PROJECT_SUMMARY_OR_NAME>
+---
+
+## Usage
+
+`/init-project <PROJECT_SUMMARY_OR_NAME>`
+
+## Objective
+
+Initialize project AI context using a mixed strategy of "concise at root + detailed at module level":
+
+- Generate/update `CLAUDE.md` at repository root (high-level vision, architecture overview, module index, global standards).
+- Generate/update local `CLAUDE.md` in identified module directories (interfaces, dependencies, entry points, tests, key files, etc.).
+- ✨ **For improved readability, automatically generate Mermaid structure diagrams in the root `CLAUDE.md` and add navigation breadcrumbs to each module `CLAUDE.md`**.
+
+## Orchestration Instructions
+
+**Step 1**: Call the `get-current-datetime` sub-agent to obtain the current timestamp.
+
+**Step 2**: Call the `init-architect` sub-agent once, with input:
+
+- `project_summary`: $ARGUMENTS
+- `current_timestamp`: (timestamp from step 1)
+
+## Execution Strategy (Agent adapts automatically, no user parameters needed)
+
+- **Stage A: Repository Census (Lightweight)**
+  Quickly count files and directories, identify module roots (package.json, pyproject.toml, go.mod, apps/_, packages/_, services/\*, etc.).
+- **Stage B: Module Priority Scanning (Medium)**
+  For each module, perform targeted reading and sampling of "entry/interfaces/dependencies/tests/data models/quality tools".
+- **Stage C: Deep Supplementation (As Needed)**
+  If repository is small or module scale is small, expand reading scope; if large, perform batch supplemental scanning on high-risk/high-value paths.
+- **Coverage Measurement and Resumability**
+  Output "scanned files / estimated total files, covered module ratio, ignored/skipped reasons" and list "recommended next-step deep-dive sub-paths". When running `/init-project` repeatedly, perform **incremental updates** and **breakpoint resumable scanning** based on previous index.
+
+## Security and Boundaries
+
+- Only read/write documentation and indexes, do not modify source code.
+- Ignore common generated artifacts and binary large files by default.
+- Print "summary" in main dialog, write full content to repository.
+
+## Output Requirements
+
+- Print "Initialization Result Summary" in main dialog, including:
+  - Whether root-level `CLAUDE.md` was created/updated, major section overview.
+  - Number of identified modules and their path list.
+  - Generation/update status of each module's `CLAUDE.md`.
+  - ✨ **Explicitly mention "Generated Mermaid structure diagram" and "Added navigation breadcrumbs for N modules"**.
+  - Coverage and major gaps.
+  - If not fully read: explain "why stopped here" and list **recommended next steps** (e.g., "suggest priority supplemental scanning: packages/auth/src/controllers").

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

@@ -32,6 +32,7 @@ Runs in **read-only preview (`--dry-run`)** mode by default, requiring explicit
 ```
 
 ### Options
+
 - `--base <branch>`: Specify the base branch for cleanup (defaults to repository's `main`/`master`).
 - `--stale <days>`: Clean branches with no commits for specified days (disabled by default).
 - `--remote`: Also clean remote merged/stale branches.
@@ -98,4 +99,4 @@ git config --get-all branch.cleanup.protected
 - ✅ **More Flexible**: Supports custom base branches, perfectly fits `release` / `develop` workflows.
 - ✅ **More Compatible**: Avoids commands with inconsistent behavior across systems like `date -d`.
 - ✅ **More Intuitive**: Condenses complex 16-step checklist into a single command with safety options.
-- ✅ **Consistent Style**: Shares similar parameter design and documentation structure with `/commit` command.
+- ✅ **Consistent Style**: Shares similar parameter design and documentation structure with `/commit` command.

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

@@ -14,6 +14,7 @@ argument-hint: [--no-verify] [--all] [--amend] [--signoff] [--emoji] [--scope <s
 # Claude Command: Commit (Git-only)
 
 This command works **without any package manager/build tools**, using only **Git** to:
+
 - Read changes (staged/unstaged)
 - Determine if changes should be **split into multiple commits**
 - Generate **Conventional Commits** style messages with optional emoji for each commit
@@ -33,6 +34,7 @@ This command works **without any package manager/build tools**, using only **Git
 ```
 
 ### Options
+
 - `--no-verify`: Skip local Git hooks (`pre-commit`/`commit-msg` etc.).
 - `--all`: When staging area is empty, automatically `git add -A` to include all changes in the commit.
 - `--amend`: **Amend** the last commit without creating a new one (preserves author and timestamp unless local Git config specifies otherwise).
@@ -88,16 +90,16 @@ This command works **without any package manager/build tools**, using only **Git
 
 ## Type to Emoji Mapping (When --emoji is Used)
 
-- ✨ `feat`: New feature  
-- 🐛 `fix`: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)  
-- 📝 `docs`: Documentation and comments  
-- 🎨 `style`: Code style/formatting (no semantic changes)  
-- ♻️ `refactor`: Refactoring (no new features, no bug fixes)  
-- ⚡️ `perf`: Performance improvements  
-- ✅ `test`: Add/fix tests, snapshots  
-- 🔧 `chore`: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)  
-- 👷 `ci`: CI/CD configuration and scripts  
-- ⏪️ `revert`: Revert commits  
+- ✨ `feat`: New feature
+- 🐛 `fix`: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)
+- 📝 `docs`: Documentation and comments
+- 🎨 `style`: Code style/formatting (no semantic changes)
+- ♻️ `refactor`: Refactoring (no new features, no bug fixes)
+- ⚡️ `perf`: Performance improvements
+- ✅ `test`: Add/fix tests, snapshots
+- 🔧 `chore`: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)
+- 👷 `ci`: CI/CD configuration and scripts
+- ⏪️ `revert`: Revert commits
 - 💥 `feat`: Breaking changes (explained in `BREAKING CHANGE:` section)
 
 > If `--type`/`--scope` is passed, it will **override** auto-detection.
@@ -107,10 +109,10 @@ This command works **without any package manager/build tools**, using only **Git
 
 ## Guidelines for Splitting Commits
 
-1. **Different concerns**: Unrelated feature/module changes should be split.  
-2. **Different types**: Don't mix `feat`, `fix`, `refactor` in the same commit.  
-3. **File modes**: Source code vs docs/tests/configs should be grouped separately.  
-4. **Size threshold**: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.  
+1. **Different concerns**: Unrelated feature/module changes should be split.
+2. **Different types**: Don't mix `feat`, `fix`, `refactor` in the same commit.
+3. **File modes**: Source code vs docs/tests/configs should be grouped separately.
+4. **Size threshold**: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.
 5. **Revertability**: Ensure each commit can be independently reverted.
 
 ---
@@ -118,24 +120,27 @@ This command works **without any package manager/build tools**, using only **Git
 ## Examples
 
 **Good (with --emoji)**
-- ✨ feat(ui): add user authentication flow  
-- 🐛 fix(api): handle token refresh race condition  
-- 📝 docs: update API usage examples  
-- ♻️ refactor(core): extract retry logic into helper  
-- ✅ test: add unit tests for rate limiter  
-- 🔧 chore: update git hooks and repository settings  
+
+- ✨ feat(ui): add user authentication flow
+- 🐛 fix(api): handle token refresh race condition
+- 📝 docs: update API usage examples
+- ♻️ refactor(core): extract retry logic into helper
+- ✅ test: add unit tests for rate limiter
+- 🔧 chore: update git hooks and repository settings
 - ⏪️ revert: revert "feat(core): introduce streaming API"
 
 **Good (without --emoji)**
-- feat(ui): add user authentication flow  
-- fix(api): handle token refresh race condition  
-- docs: update API usage examples  
-- refactor(core): extract retry logic into helper  
-- test: add unit tests for rate limiter  
-- chore: update git hooks and repository settings  
+
+- feat(ui): add user authentication flow
+- fix(api): handle token refresh race condition
+- docs: update API usage examples
+- refactor(core): extract retry logic into helper
+- test: add unit tests for rate limiter
+- chore: update git hooks and repository settings
 - revert: revert "feat(core): introduce streaming API"
 
 **Split Example**
+
 - `feat(types): add new type defs for payment method`
 - `docs: update API docs for new types`
 - `test: add unit tests for payment types`
@@ -145,8 +150,8 @@ This command works **without any package manager/build tools**, using only **Git
 
 ## Important Notes
 
-- **Git only**: No package manager/build commands (`pnpm`/`npm`/`yarn` etc.).  
-- **Respects hooks**: Executes local Git hooks by default; use `--no-verify` to skip.  
-- **No source code changes**: Command only reads/writes `.git/COMMIT_EDITMSG` and staging area; doesn't directly edit working directory files.  
-- **Safety prompts**: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.  
-- **Auditable and controllable**: If `confirm: true` is enabled, each actual `git add`/`git commit` step requires confirmation.
+- **Git only**: No package manager/build commands (`pnpm`/`npm`/`yarn` etc.).
+- **Respects hooks**: Executes local Git hooks by default; use `--no-verify` to skip.
+- **No source code changes**: Command only reads/writes `.git/COMMIT_EDITMSG` and staging area; doesn't directly edit working directory files.
+- **Safety prompts**: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.
+- **Auditable and controllable**: If `confirm: true` is enabled, each actual `git add`/`git commit` step requires confirmation.

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

@@ -7,9 +7,10 @@ argument-hint: [--branch <branch>] [--target <rev>] [--mode reset|revert] [--dep
 #   - /git-rollback --branch dev   # Select dev directly, other interactive
 #   - /git-rollback --branch dev --target v1.2.0 --mode reset --yes
 ---
+
 # Claude Command: Git Rollback
 
-**Purpose**: Safely and visually rollback a specified branch to an older version.  
+**Purpose**: Safely and visually rollback a specified branch to an older version.
 Defaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.
 
 ---
@@ -32,14 +33,14 @@ Defaults to **read-only preview (`--dry-run`)**; actual execution requires `--ye
 
 ### Options
 
-| Option | Description |
-|------|------|
-| `--branch <branch>` | Branch to rollback; interactively selected if omitted. |
-| `--target <rev>` | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |
-| `--mode reset\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default. |
-| `--depth <n>` | List recent n versions in interactive mode (default 20). |
-| `--dry-run` | **Enabled by default**, only preview commands to be executed. |
-| `--yes` | Skip all confirmations and execute directly, suitable for CI/CD scripts. |
+| Option                 | Description                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--branch <branch>`    | Branch to rollback; interactively selected if omitted.                                                             |
+| `--target <rev>`       | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |
+| `--mode reset\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default.     |
+| `--depth <n>`          | List recent n versions in interactive mode (default 20).                                                           |
+| `--dry-run`            | **Enabled by default**, only preview commands to be executed.                                                      |
+| `--yes`                | Skip all confirmations and execute directly, suitable for CI/CD scripts.                                           |
 
 ---
 
@@ -52,38 +53,38 @@ Defaults to **read-only preview (`--dry-run`)**; actual execution requires `--ye
 5. **Select target** → User inputs commit hash / tag
 6. **Select mode** → `reset` or `revert`
 7. **Final confirmation** (unless `--yes`)
-8. **Execute rollback**  
-   * `reset`: `git switch <branch> && git reset --hard <target>`  
-   * `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`
+8. **Execute rollback**
+   - `reset`: `git switch <branch> && git reset --hard <target>`
+   - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`
 9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)
 
 ---
 
 ## Safety Guards
 
-* **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.  
-* **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.  
-* **--dry-run enabled by default**: Prevents accidental operations.  
-* **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.
+- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.
+- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.
+- **--dry-run enabled by default**: Prevents accidental operations.
+- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.
 
 ---
 
 ## Use Case Examples
 
-| Scenario | Command Example |
-|------|---------|
-| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |
-| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |
-| Research historical bugs, guide newcomers through branch history | `/git-rollback` (full interactive, dry-run) |
+| Scenario                                                                    | Command Example                                                  |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0`            | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |
+| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert`     |
+| Research historical bugs, guide newcomers through branch history            | `/git-rollback` (full interactive, dry-run)                      |
 
 ---
 
 ## Notes
 
-1. **reset vs revert**  
-   * **reset** changes history, requires force push and may affect other collaborators, use with caution.  
-   * **revert** is safer, generates new commits preserving history, but adds one more record.  
-2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.  
+1. **reset vs revert**
+   - **reset** changes history, requires force push and may affect other collaborators, use with caution.
+   - **revert** is safer, generates new commits preserving history, but adds one more record.
+2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.
 3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.
 
----
+---