{"owner":"UfoMiao","repo":"zcf","hasSkills":true,"totalSkillsCount":25,"totalTokensCount":61271,"categories":["anthropic-skill","root-instruction","claude-rule","command-prompt"],"hasMcp":false,"mcpConfig":null,"found":[".claude/skills/zcf-add-sponsor/SKILL.md",".claude/skills/zcf-pr/SKILL.md",".claude/skills/zcf-release/SKILL.md",".claude/skills/zcf-update-docs/SKILL.md","AGENTS.md","CLAUDE.md","src/commands/CLAUDE.md","templates/CLAUDE.md","templates/skills/en/bmad-init/SKILL.md","templates/skills/en/feat/SKILL.md","templates/skills/en/git-clean-branches/SKILL.md","templates/skills/en/git-commit/SKILL.md","templates/skills/en/git-rollback/SKILL.md","templates/skills/en/git-worktree/SKILL.md","templates/skills/en/init-project/SKILL.md","templates/skills/en/workflow/SKILL.md","templates/skills/zh-CN/bmad-init/SKILL.md","templates/skills/zh-CN/feat/SKILL.md","templates/skills/zh-CN/git-clean-branches/SKILL.md","templates/skills/zh-CN/git-commit/SKILL.md","templates/skills/zh-CN/git-rollback/SKILL.md","templates/skills/zh-CN/git-worktree/SKILL.md","templates/skills/zh-CN/init-project/SKILL.md","templates/skills/zh-CN/workflow/SKILL.md","tests/CLAUDE.md"],"skills":{".claude/skills/zcf-add-sponsor/SKILL.md":"---\nname: zcf-add-sponsor\ndescription: Quickly add a new corporate sponsor to ZCF — sponsor list by default, with optional API preset and documentation ad placements\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(**), Edit(**), Exec(ls, cat, grep, rg, sed, awk, file, mv, pnpm, node, git)\n---\n\n# ZCF Add Sponsor — Quick Sponsor Onboarding\n\nQuickly onboard a new **corporate sponsor** across the ZCF project: README sponsor lists by default, with optional API provider preset and documentation ad placements.\n\n## Usage\n\n```bash\n/zcf-add-sponsor [--with-api] [--with-ad] [--name ] [--url ] [--id ] [--logo ] [--badge ]\n```\n\n## Parameters\n\n### Mode flags\n\n- `--with-api` — Also append a new entry to `src/config/api-providers.ts` (`API_PROVIDER_PRESETS`)\n- `--with-ad` — Also insert ad cards into:\n - `README.md`, `README_zh-CN.md`, `README_ja-JP.md` (top `♥️ Sponsors` section, table card)\n - `docs/en/index.md`, `docs/zh-CN/index.md`, `docs/ja-JP/index.md` (top `♥️ Sponsor` section, table card)\n- *(no flag)* — Default: only add a single bullet entry to the **Our Sponsors → Corporate Sponsors** lists in the three READMEs\n\n### Sponsor info (prompt interactively if missing)\n\n- `--name ` — Display name (e.g. `FooAI`)\n- `--url ` — Affiliate/registration URL (used in every link)\n- `--id ` — API provider id, kebab-case (only required with `--with-api`, e.g. `fooai`)\n- `--logo ` — Local logo path under `src/assets/` (only required with `--with-ad`, e.g. `./src/assets/fooai.png`)\n- `--badge ` — Trailing emoji badge for the list bullet (default: `🎁`)\n\n## Context\n\n- **Default scope**: Only the `Our Sponsors → Corporate Sponsors` bullet list in the three READMEs (zh-CN, en, ja-JP). `docs/*/index.md` does **not** contain a sponsor list — it only contains an ad section, handled by `--with-ad`.\n- **API preset format**: Match the existing `ApiProviderPreset` interface in `src/config/api-providers.ts`. Ask the user about `baseUrl`, `authType`, `wireApi`, `defaultModels`, and which code tools are supported (`claude-code`, `codex`, or both).\n- **Ad cards**: Mirror the existing AICodeMirror / Crazyrouter card layout exactly — `
...description...
`, appended **after** the last existing sponsor card and **before** the next `##` heading.\n- **Image paths**:\n - In `README*.md` use relative path `./src/assets/`\n - In `docs/*/index.md` use absolute GitHub raw URL `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/`\n- **Trilingual descriptions**: Always generate three localized descriptions (zh-CN / en / ja-JP). Translate from the user-provided source description while preserving brand names, URLs, and discount numbers verbatim.\n\n## Your Role\n\nYou are a project documentation maintainer. Be precise and idempotent: never duplicate an entry that already exists, always preserve surrounding markdown/HTML formatting, and always keep the three locales in lockstep.\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Argument parsing & validation\n\n```text\nParse from $ARGUMENTS:\n WITH_API=false # toggled by --with-api\n WITH_AD=false # toggled by --with-ad\n NAME=\"\" # --name \n URL=\"\" # --url \n PROVIDER_ID=\"\" # --id \n LOGO_PATH=\"\" # --logo \n BADGE=\"🎁\" # --badge , default 🎁\n\nValidation:\n - NAME and URL are always required → if missing, prompt user\n - If WITH_API: PROVIDER_ID required → if missing, prompt user.\n Provider id MUST be kebab-case, lowercase, unique across existing ids in src/config/api-providers.ts\n - If WITH_AD: LOGO_PATH required → if missing, prompt user.\n Verify the logo file exists at the given path (relative to repo root).\n If not, instruct the user to place the logo under src/assets/ first and abort.\n```\n\n### 2. Collect missing sponsor information (interactive)\n\nIf any required field is missing, ask the user **once** in a consolidated prompt covering:\n\n- Source description (1–3 sentences, in the user's preferred language)\n- Special offer / discount line (optional, e.g. \"Use code zcf for 10% off\")\n- For `--with-api`:\n - Supported code tools: `claude-code` / `codex` / both\n - Claude Code `baseUrl` and `authType` (`api_key` | `auth_token`)\n - Codex `baseUrl` (always `wireApi: 'responses'` per existing convention)\n - Optional `defaultModels` array (Claude Code) or `defaultModel` string (Codex)\n\nThen auto-translate the description into the other two languages, preserving brand names, URLs, and numbers.\n\n### 3. Idempotency check\n\nBefore any write, scan target files for the sponsor name or URL. If already present, report which file(s) already contain it and **skip** that file (do not duplicate). Continue with remaining files.\n\n```bash\nrg -l --fixed-strings \"\" README.md README_zh-CN.md README_ja-JP.md docs/en/index.md docs/zh-CN/index.md docs/ja-JP/index.md src/config/api-providers.ts 2>/dev/null\n```\n\n### 4. Update sponsor lists (default — always runs)\n\nLocate the **Corporate Sponsors** bullet list in each README and append a new bullet **at the end** of that list (before the `【Individual Sponsors】` / `【个人赞助商】` / `【個人スポンサー】` heading):\n\n- `README.md` — under `【Corporate Sponsors】`:\n ```\n - []() ( )\n ```\n- `README_zh-CN.md` — under `【企业赞助商】`:\n ```\n - []() （ ）\n ```\n- `README_ja-JP.md` — under `【企業スポンサー】`:\n ```\n - []()（ ）\n ```\n\n`<*_TAGLINE>` is a short 4–10 char positioning phrase derived from the source description (e.g. \"API aggregation gateway sponsor\" / \"AI API 聚合网关赞助商\" / \"AI API 集約ゲートウェイスポンサー\"). Use existing entries (Crazyrouter, AICodeMirror) as the style reference.\n\n### 5. Insert ad cards — only if `--with-ad`\n\nFor each of the six files below, locate the existing sponsor card table and **append a new `...` row to the same ``** (or, if the existing structure uses sibling `
` blocks, append a new sibling table immediately after the last one). Match the exact layout of the most recent existing card.\n\n**Target files & image base path:**\n\n| File | Image path prefix |\n|------|-------------------|\n| `README.md` | `./src/assets/` |\n| `README_zh-CN.md` | `./src/assets/` |\n| `README_ja-JP.md` | `./src/assets/` |\n| `docs/en/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/zh-CN/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/ja-JP/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n\n**Card template (reference, fill brackets per locale):**\n\n```html\n
\n\n\n\n\n
\">\" alt=\"\" width=\"150\">
\n```\n\n> **Important**: Insert **after** the last existing sponsor card and **before** the next `##` heading (typically `## 📺 ...` or `## ✨ ...`). Preserve surrounding blank lines.\n\n### 6. Add API provider preset — only if `--with-api`\n\nEdit `src/config/api-providers.ts`. Append a new object to the `API_PROVIDER_PRESETS` array, **before the closing `]`**, mirroring the style of existing entries:\n\n```ts\n {\n id: '',\n name: '',\n supportedCodeTools: [<'claude-code' and/or 'codex'>],\n claudeCode: {\n baseUrl: '',\n authType: '',\n // defaultModels: [...], // include only if user provided\n },\n codex: { // include only if codex is supported\n baseUrl: '',\n wireApi: 'responses',\n // defaultModel: '...', // include only if user provided\n },\n description: '',\n },\n```\n\nThen run `pnpm typecheck` to confirm no type errors. If the project has corresponding tests for `getValidProviderIds()` or fixtures, surface them in the summary so the user can update tests if needed.\n\n### 7. Validation\n\n```text\n✓ List bullets present in all 3 READMEs (or skipped due to existing entry)\n✓ If --with-ad: card rows present in all 6 target files (or skipped)\n✓ If --with-api: new preset object syntactically valid; pnpm typecheck passes\n✓ No duplicate ids in API_PROVIDER_PRESETS\n✓ All URLs identical across files\n✓ Logo file exists at src/assets/ when --with-ad is used\n```\n\n### 8. Summary report\n\nPrint a concise summary:\n\n```\n🎉 Sponsor \"\" added\n\nSponsor list bullets:\n ✓ README.md\n ✓ README_zh-CN.md\n ✓ README_ja-JP.md\n\nAd cards (--with-ad): [yes/no]\n ✓/⊘ README.md / README_zh-CN.md / README_ja-JP.md\n ✓/⊘ docs/en/index.md / docs/zh-CN/index.md / docs/ja-JP/index.md\n\nAPI preset (--with-api): [yes/no]\n ✓/⊘ src/config/api-providers.ts (id: )\n\nSkipped (already present): [list]\n\nNext steps:\n - Review changes with: git diff\n - If --with-api: consider adding tests in tests/ for the new provider\n - Commit with: /zcf-pr or your preferred flow\n```\n\n## Important Notes\n\n⚠️ **Critical Requirements**\n\n- **NEVER** modify any sponsor entries other than the ones being added\n- **NEVER** reorder existing sponsors\n- **ALWAYS** keep the three locale READMEs in sync (same bullet count, same URL, semantically equivalent text)\n- **ALWAYS** verify logo file existence under `src/assets/` before writing ad cards\n- **ALWAYS** validate the API preset by running `pnpm typecheck` after editing\n- **DO NOT** create commits or push — leave that to the user / `/zcf-pr`\n- **DO NOT** invent new section headings; reuse the exact existing ones (`【Corporate Sponsors】` / `【企业赞助商】` / `【企業スポンサー】`)\n\n📌 **Style Reference**\n\nWhen in doubt, copy the structure of the most recent existing sponsor entry (currently **Crazyrouter**) — it represents the canonical layout for both bullet entries and ad cards across all six target documents.\n\n🔍 **Idempotency**\n\nRe-running with the same `--name` and `--url` MUST be a no-op. Detection is by exact match on either NAME or URL within the relevant section.\n\n---\n\n**Now starting sponsor onboarding...**\n",".claude/skills/zcf-pr/SKILL.md":"---\nname: zcf-pr\ndescription: Create pull request based on current branch changes\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF PR - Create Pull Request from Current Branch\n\nCreate pull request based on current branch changes and generate standardized PR description.\n\n## Usage\n\n```bash\n/zcf-pr [--base ] [--draft] [--title ]\n```\n\n## Parameters\n\n- `--base <branch>`: Target base branch (default: main)\n- `--draft`: Create as draft pull request\n- `--title <title>`: Custom PR title\n\n## Context\n\n- Analyze current branch changes since divergence from base branch\n- Generate PR description following project template\n- Support both English and Chinese descriptions\n- Auto-detect change types and categorize appropriately\n- Create PR using GitHub CLI with comprehensive template\n\n## Your Role\n\nYou are a professional pull request management assistant responsible for:\n\n1. Analyzing branch changes\n2. Categorizing change types automatically\n3. Generating standardized PR descriptions\n4. Creating pull requests with proper templates\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nBASE_BRANCH=\"main\"\nIS_DRAFT=false\nCUSTOM_TITLE=\"\"\n\n# Parse arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --base)\n BASE_BRANCH=\"$2\"\n shift 2\n ;;\n --draft)\n IS_DRAFT=true\n shift\n ;;\n --title)\n CUSTOM_TITLE=\"$2\"\n shift 2\n ;;\n *)\n echo \"❌ Unknown parameter: $1\"\n echo \"Usage: /zcf-pr [--base <branch>] [--draft] [--title <title>]\"\n echo \"Examples:\"\n echo \" /zcf-pr # Create PR to main\"\n echo \" /zcf-pr --base develop # Create PR to develop\"\n echo \" /zcf-pr --draft # Create draft PR\"\n echo \" /zcf-pr --title 'Bug Fix' # Custom title\"\n exit 1\n ;;\n esac\ndone\n\necho \"🚀 Creating PR from current branch to $BASE_BRANCH\"\nif [ \"$IS_DRAFT\" = true ]; then\n echo \"📝 Creating as draft PR\"\nfi\nif [ -n \"$CUSTOM_TITLE\" ]; then\n echo \"📝 Custom title: $CUSTOM_TITLE\"\nfi\n```\n\n### 2. Check Working Directory Status\n\n```bash\n# Check if we're in a git repository\nif [ ! -d \".git\" ]; then\n echo \"❌ Error: Not in a git repository\"\n exit 1\nfi\n\n# Get current branch\nCURRENT_BRANCH=$(git branch --show-current)\nif [ -z \"$CURRENT_BRANCH\" ]; then\n echo \"❌ Error: Could not determine current branch\"\n exit 1\nfi\n\n# Check if current branch is same as base branch\nif [ \"$CURRENT_BRANCH\" = \"$BASE_BRANCH\" ]; then\n echo \"❌ Error: Cannot create PR from $BASE_BRANCH to $BASE_BRANCH\"\n echo \"Please switch to a feature branch first\"\n exit 1\nfi\n\n# Check for uncommitted changes\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Warning: You have uncommitted changes\"\n echo \"Please commit your changes before creating a PR\"\n echo \"\"\n git status --short\n echo \"\"\n echo \"Run the following commands to commit your changes:\"\n echo \" git add .\"\n echo \" git commit -m 'Your commit message'\"\n exit 1\nfi\n\necho \"✅ Branch status OK: $CURRENT_BRANCH\"\n```\n\n### 3. Analyze Branch Changes\n\n```bash\n# Check if base branch exists\nif ! git rev-parse --verify \"$BASE_BRANCH\" >/dev/null 2>&1; then\n echo \"❌ Error: Base branch '$BASE_BRANCH' does not exist\"\n exit 1\nfi\n\n# Get commit history since divergence\necho \"📊 Analyzing changes from $BASE_BRANCH...\"\n\n# Find common ancestor\nMERGE_BASE=$(git merge-base \"$BASE_BRANCH\" HEAD)\nif [ -z \"$MERGE_BASE\" ]; then\n echo \"❌ Error: Could not find common ancestor with $BASE_BRANCH\"\n exit 1\nfi\n\n# Get commits since divergence\nCOMMITS=$(git log $MERGE_BASE..HEAD --oneline)\nCOMMIT_COUNT=$(echo \"$COMMITS\" | wc -l | tr -d ' ')\n\nif [ \"$COMMIT_COUNT\" -eq 0 ]; then\n echo \"❌ Error: No commits found since divergence from $BASE_BRANCH\"\n exit 1\nfi\n\necho \"📝 Found $COMMIT_COUNT commit(s):\"\necho \"$COMMITS\"\necho \"\"\n\n# Analyze file changes\necho \"📁 File change statistics:\"\ngit diff --stat $MERGE_BASE..HEAD\n\n# Get changed files\nCHANGED_FILES=$(git diff --name-only $MERGE_BASE..HEAD)\necho \"\"\necho \"📋 Changed files:\"\necho \"$CHANGED_FILES\"\n```\n\n### 4. Categorize Changes\n\n```bash\n# Analyze changes to determine type and scope\necho \"\"\necho \"🔍 Analyzing change categories...\"\n\nBUG_FIX=false\nNEW_FEATURE=false\nBREAKING_CHANGE=false\nDOCUMENTATION=false\nTESTS=false\n\n# Analyze commits for change indicators\nif echo \"$COMMITS\" | grep -E \"(fix|bug|error|issue|problem)\" >/dev/null; then\n BUG_FIX=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(feat|add|new|create|implement)\" >/dev/null; then\n NEW_FEATURE=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(break|change|remove|delete|major)\" >/dev/null; then\n BREAKING_CHANGE=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt|rst)$\" >/dev/null; then\n DOCUMENTATION=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"(test|spec)\\.\" >/dev/null; then\n TESTS=true\nfi\n\n# Show analysis results\necho \"📊 Change type analysis:\"\nif [ \"$BUG_FIX\" = true ]; then echo \" ✅ Bug fix detected\"; fi\nif [ \"$NEW_FEATURE\" = true ]; then echo \" ✅ New feature detected\"; fi\nif [ \"$BREAKING_CHANGE\" = true ]; then echo \" ✅ Breaking change detected\"; fi\nif [ \"$DOCUMENTATION\" = true ]; then echo \" ✅ Documentation update detected\"; fi\nif [ \"$TESTS\" = true ]; then echo \" ✅ Test updates detected\"; fi\n```\n\n### 5. Generate PR Title\n\n```bash\n# Generate PR title\nif [ -n \"$CUSTOM_TITLE\" ]; then\n PR_TITLE=\"$CUSTOM_TITLE\"\nelse\n # Auto-generate title from first commit\n FIRST_COMMIT=$(echo \"$COMMITS\" | tail -1)\n\n # Clean up commit message for PR title\n if echo \"$FIRST_COMMIT\" | grep -E \"^(feat|fix|docs|style|refactor|test|chore)(\\(.+\\))?: \" >/dev/null; then\n # Use conventional commit format\n PR_TITLE=$(echo \"$FIRST_COMMIT\" | sed 's/^[a-f0-9]\\+ //')\n else\n # Fallback to simple format\n PR_TITLE=\"$CURRENT_BRANCH\"\n fi\nfi\n\necho \"📝 PR Title: $PR_TITLE\"\n```\n\n### 6. Generate PR Description\n\n```bash\n# Generate comprehensive PR description\necho \"📋 Generating PR description...\"\n\n# Generate change summary\nCHANGE_SUMMARY=\"\"\nif [ \"$BUG_FIX\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Bug fixes and error handling improvements\\n\"\nfi\nif [ \"$NEW_FEATURE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- New features and functionality additions\\n\"\nfi\nif [ \"$BREAKING_CHANGE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Breaking changes requiring attention\\n\"\nfi\nif [ \"$DOCUMENTATION\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Documentation updates and improvements\\n\"\nfi\nif [ \"$TESTS\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Test coverage and quality improvements\\n\"\nfi\n\n# Generate file change summary\nFILE_CHANGES=\"\"\nfor file in $CHANGED_FILES; do\n FILE_CHANGES=\"${FILE_CHANGES}- \\`$file\\`\\n\"\ndone\n\n# Build complete PR description\nPR_DESCRIPTION=$(cat <<EOF\n## Description\n\nThis PR includes changes from branch \\`$CURRENT_BRANCH\\` with $COMMIT_COUNT commit(s) since divergence from \\`$BASE_BRANCH\\`.\n\n### Key Changes:\n\n$CHANGE_SUMMARY\n\n### Files Modified:\n\n$FILE_CHANGES\n\n## Type of Change\n\nEOF\n)\n\n# Add checkboxes based on analysis\nif [ \"$BUG_FIX\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Bug fix\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Bug fix\\n\"\nfi\n\nif [ \"$NEW_FEATURE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] New feature\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] New feature\\n\"\nfi\n\nif [ \"$BREAKING_CHANGE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Breaking change\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Breaking change\\n\"\nfi\n\nif [ \"$DOCUMENTATION\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Documentation update\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Documentation update\\n\"\nfi\n\n# Add testing section\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Testing\n\n- [x] Code changes tested\n- [x] No new warnings introduced\n- [x] Code follows style guidelines\"\n\nif [ \"$TESTS\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [x] Tests added/updated\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [ ] Tests added/updated\"\nfi\n\n# Add checklist\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Checklist\n\n- [x] Self-review completed\n- [x] Documentation updated (if applicable)\n- [x] No new warnings introduced\n- [x] Code follows project guidelines\n\n## Additional Information\n\n**Branch:** \\`$CURRENT_BRANCH\\` → \\`$BASE_BRANCH\\`\n**Commits:** $COMMIT_COUNT\n**Files Changed:** $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\n\n### Commit History:\n\n\\`\\`\\`\n$COMMITS\n\\`\\`\\`\n\n---\n🤖 Generated with /zcf-pr command\nEOF\n\necho \"✅ PR description generated\"\n```\n\n### 7. Push Branch and Create PR\n\n```bash\n# Check if branch exists on remote\nif ! git ls-remote --heads origin \"$CURRENT_BRANCH\" >/dev/null 2>&1; then\n echo \"📤 Pushing branch to remote...\"\n git push -u origin \"$CURRENT_BRANCH\"\nelse\n echo \"📤 Branch already exists on remote, ensuring it's up to date...\"\n git push origin \"$CURRENT_BRANCH\"\nfi\n\n# Create PR using gh CLI\necho \"📋 Creating pull request...\"\n\nPR_OPTIONS=\"--title '$PR_TITLE' --body '$PR_DESCRIPTION'\"\n\nif [ \"$IS_DRAFT\" = true ]; then\n PR_OPTIONS=\"$PR_OPTIONS --draft\"\nfi\n\n# Execute gh pr create command\nPR_URL=$(eval \"gh pr create --base $BASE_BRANCH $PR_OPTIONS\")\n\nif [ $? -eq 0 ]; then\n echo \"\"\n echo \"✅ Pull request created successfully!\"\n echo \"🔗 PR URL: $PR_URL\"\n echo \"\"\n echo \"📋 PR Details:\"\n echo \" Title: $PR_TITLE\"\n echo \" From: $CURRENT_BRANCH\"\n echo \" To: $BASE_BRANCH\"\n echo \" Commits: $COMMIT_COUNT\"\n echo \" Files: $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\"\n echo \"\"\n echo \"⚠️ Please review the PR and add any additional information as needed\"\nelse\n echo \"❌ Failed to create pull request\"\n echo \"Please check GitHub CLI authentication and permissions\"\n exit 1\nfi\n```\n\n## Complete Workflow Summary\n\n1. **Parameter Parsing**: Parse base branch, draft mode, and custom title options\n2. **Branch Validation**: Check current branch status and ensure it's different from base branch\n3. **Change Analysis**: Analyze commits and file changes since divergence from base branch\n4. **Categorization**: Auto-detect change types (bug fix, feature, breaking change, docs, tests)\n5. **Title Generation**: Generate appropriate PR title or use custom title\n6. **Description Generation**: Create comprehensive PR description following project template\n7. **Branch Push**: Ensure branch is available on remote repository\n8. **PR Creation**: Create pull request using GitHub CLI with all details\n\n## Important Notes\n\n⚠️ **Prerequisites**:\n\n- **GitHub CLI (`gh`)**: Must be installed and authenticated\n- **Clean working directory**: All changes must be committed before PR creation\n- **Remote branch**: Current branch must be pushed to remote repository\n- **Base branch**: Target branch must exist and be accessible\n\n### Best Practices:\n\n- Ensure commit messages follow conventional commit format\n- Test all changes before creating PR\n- Review auto-generated PR description for accuracy\n- Add any additional context specific to your changes\n- Check that all tests pass in CI/CD pipeline\n\n### Change Detection Logic:\n\nThe command automatically categorizes changes based on:\n\n- **Commit messages**: Keywords like \"feat\", \"fix\", \"break\", \"docs\", \"test\"\n- **File patterns**: `.md/.txt` for docs, `(test|spec)\\.` for tests\n- **File extensions**: TypeScript, JavaScript, JSON, etc.\n\n### Example Outputs:\n\n```bash\n# Standard PR to main\n/zcf-pr\n# → Creates PR: \"feat: add new feature\" with full description\n\n# PR to develop branch\n/zcf-pr --base develop\n# → Creates PR to develop branch instead of main\n\n# Draft PR\n/zcf-pr --draft\n# → Creates draft PR for initial review\n\n# Custom title\n/zcf-pr --title \"Critical bug fix for authentication\"\n# → Uses custom title instead of auto-generated one\n```\n\n---\n\n**Now creating pull request...**",".claude/skills/zcf-release/SKILL.md":"---\nname: zcf-release\ndescription: Automate version release and code commit using changeset\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF Release - Automated Release and Commit\n\nAutomate version release and code commit using changeset.\n\n## Usage\n\n```bash\n/zcf-release [-p|-mi|-ma|<version>]\n```\n\n## Parameters\n\n- `-p` or `--patch`: Patch version (default) - bug fixes, minor changes\n- `-mi` or `--minor`: Minor version - new features, backward compatible\n- `-ma` or `--major`: Major version - breaking changes, incompatible\n- `<version>`: Specific version number (e.g., 1.2.3, 2.0.0-beta.1) - directly use provided version\n\n## Context\n\n- Automatically analyze code changes and generate bilingual CHANGELOG\n- Use changeset for version management\n- Create release branch and pull request for protected main branch\n- Auto commit code changes (NO manual tags)\n- Support GitHub Actions auto publish to npm with automatic tagging after PR merge\n\n## Your Role\n\nYou are a professional release management assistant responsible for:\n\n1. Analyzing code changes\n2. Generating standardized CHANGELOG\n3. Executing version release process\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nVERSION_TYPE=\"patch\" # Default to patch version\nSPECIFIC_VERSION=\"\" # For user-specified exact version\n\n# Check if argument looks like a version number (matches semver pattern)\nif [[ \"$ARGUMENTS\" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+([.-].*)?$ ]]; then\n SPECIFIC_VERSION=\"$ARGUMENTS\"\n VERSION_TYPE=\"custom\"\n echo \"🚀 Preparing to release exact version: $SPECIFIC_VERSION\"\nelse\n case \"$ARGUMENTS\" in\n -p|--patch)\n VERSION_TYPE=\"patch\"\n ;;\n -mi|--minor)\n VERSION_TYPE=\"minor\"\n ;;\n -ma|--major)\n VERSION_TYPE=\"major\"\n ;;\n \"\")\n VERSION_TYPE=\"patch\"\n ;;\n *)\n echo \"❌ Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-release [-p|-mi|-ma|<version>]\"\n echo \"Examples:\"\n echo \" /zcf-release -p # Patch version bump\"\n echo \" /zcf-release -mi # Minor version bump\"\n echo \" /zcf-release -ma # Major version bump\"\n echo \" /zcf-release 1.2.3 # Exact version\"\n echo \" /zcf-release 2.0.0-beta.1 # Pre-release version\"\n exit 1\n ;;\n esac\n echo \"🚀 Preparing to release $VERSION_TYPE version\"\nfi\n```\n\n### 2. Check Working Directory Status\n\nCheck if the current working directory meets release conditions:\n\n```bash\n# Ensure in project root directory\nif [ ! -f \"package.json\" ]; then\n echo \"❌ Error: package.json not found, please run in project root\"\n exit 1\nfi\n\n# Check for uncommitted changes and handle automatically\nHAS_UNCOMMITTED=false\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Detected uncommitted changes:\"\n git status --short\n echo \"\"\n HAS_UNCOMMITTED=true\nfi\n\necho \"✅ Working directory status OK\"\n```\n\n### 3. Analyze Version Changes\n\nAnalyze all changes since last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"📊 No previous version tag found, analyzing all commits\"\n COMMITS=$(git log --oneline)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n COMMITS=$(git log $LAST_TAG..HEAD --oneline)\nfi\n\n# Show commit history\necho -e \"\\n📝 Changes:\"\necho \"$COMMITS\"\n\n# Analyze file changes\necho -e \"\\n📁 File change statistics:\"\nif [ -z \"$LAST_TAG\" ]; then\n git diff --stat\nelse\n git diff --stat $LAST_TAG..HEAD\nfi\n```\n\n### 4. Generate CHANGELOG Content\n\nBased on code change analysis, I will generate CHANGELOG following these standards:\n\n**Format Requirements**:\n\n1. English description first, Chinese description second\n2. No mixing Chinese and English on the same line\n3. Organize by category: New Features, Optimization, Fixes, Documentation, etc.\n4. Each entry should be concise and clear\n\n**Example Format**:\n\n```markdown\n## New Features\n\n- Add technical execution guidelines with command best practices\n- Support automated release command /zcf-release\n- Automatic quote handling for Windows paths\n\n## 新功能\n\n- 添加技术执行指南文档，提供命令执行最佳实践\n- 支持自动化发版命令 /zcf-release\n- Windows 路径自动加引号处理\n\n## Optimization\n\n- Prioritize ripgrep for better search performance\n- Improve template file organization\n\n## 优化\n\n- 优先使用 ripgrep 提升搜索性能\n- 改进模板文件组织结构\n\n## Fixes\n\n- Fix Windows path backslash escaping issue\n\n## 修复\n\n- 修复 Windows 路径反斜杠丢失问题\n```\n\n### 5. Create Changeset\n\nCreate changeset file based on analysis:\n\n```bash\n# Generate timestamp\nTIMESTAMP=$(date +%Y%m%d%H%M%S)\nCHANGESET_FILE=\".changeset/release-$TIMESTAMP.md\"\n\n# Create changeset file\necho \"📝 Creating changeset file...\"\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n # For specific version, use the exact version number\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $SPECIFIC_VERSION\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with exact version: $SPECIFIC_VERSION\"\nelse\n # For version type (patch/minor/major), use the type\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $VERSION_TYPE\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with version type: $VERSION_TYPE\"\nfi\n```\n\n### 6. Update Version Number\n\nUse changeset to update version number and CHANGELOG:\n\n```bash\necho \"🔄 Updating version number and CHANGELOG...\"\npnpm changeset version\n\n# Note: The changeset version command will automatically:\n# 1. Update package.json version\n# 2. Generate/update CHANGELOG.md\n# 3. DELETE the temporary changeset file in .changeset/ directory\n# No manual cleanup needed!\n\n# Get new version number\nNEW_VERSION=$(node -p \"require('./package.json').version\")\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n echo \"📦 New version set to: v$NEW_VERSION (specified: $SPECIFIC_VERSION)\"\nelse\n echo \"📦 New version: v$NEW_VERSION\"\nfi\n\n# Show CHANGELOG update\necho -e \"\\n📋 CHANGELOG has been updated, please review the content\"\necho \"✅ Temporary changeset file has been automatically deleted\"\n```\n\n### 7. Create Release Branch and Handle Commits\n\nCreate release branch first, then handle commits separately to avoid polluting main branch:\n\n````bash\necho \"🚀 Creating release branch...\"\n\n# Create and switch to release branch\nRELEASE_BRANCH=\"release/v$NEW_VERSION\"\ngit checkout -b \"$RELEASE_BRANCH\"\n\n# Handle uncommitted changes first (if any)\nif [ \"$HAS_UNCOMMITTED\" = true ]; then\n echo \"📝 Committing pre-release changes...\"\n \n # Stage only the uncommitted changes (exclude changeset modifications)\n git add .\n git reset HEAD package.json CHANGELOG.md 2>/dev/null || true\n \n # Check if there are still changes to commit after reset\n if ! git diff --quiet --staged; then\n # Analyze the staged changes to generate appropriate commit message\n echo \"🔍 Analyzing uncommitted changes...\"\n CHANGED_FILES=$(git diff --staged --name-only)\n \n # Generate commit message based on changed files\n COMMIT_TYPE=\"chore\"\n COMMIT_SCOPE=\"\"\n COMMIT_DESCRIPTION=\"pre-release changes\"\n \n # Analyze file patterns to determine commit type and scope\n if echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -i \"readme\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"readme\"\n COMMIT_DESCRIPTION=\"update README documentation\"\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.claude/\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"commands\"\n COMMIT_DESCRIPTION=\"update command documentation\"\n else\n COMMIT_TYPE=\"docs\"\n COMMIT_DESCRIPTION=\"update documentation\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.(ts|js|tsx|jsx)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -E \"test|spec\" >/dev/null; then\n COMMIT_TYPE=\"test\"\n COMMIT_DESCRIPTION=\"update tests\"\n else\n COMMIT_TYPE=\"feat\"\n COMMIT_DESCRIPTION=\"code changes\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.json$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep \"package\" >/dev/null; then\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update dependencies\"\n else\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update configuration\"\n fi\n fi\n \n # Build commit message\n if [ -n \"$COMMIT_SCOPE\" ]; then\n COMMIT_MSG=\"${COMMIT_TYPE}(${COMMIT_SCOPE}): ${COMMIT_DESCRIPTION}\"\n else\n COMMIT_MSG=\"${COMMIT_TYPE}: ${COMMIT_DESCRIPTION}\"\n fi\n \n # Add file list to commit body\n COMMIT_BODY=\"\"\n for file in $CHANGED_FILES; do\n COMMIT_BODY=\"${COMMIT_BODY}- Update ${file}\n\"\n done\n COMMIT_BODY=\"${COMMIT_BODY}\n🤖 Generated with [Claude Code](https://claude.ai/code)\n \n # Create the commit\n git commit -m \"${COMMIT_MSG}\n\n${COMMIT_BODY}\"\n \n echo \"✅ Pre-release changes committed: $COMMIT_MSG\"\n else\n echo \"ℹ️ No additional changes to commit after version update\"\n fi\nfi\n\necho \"💾 Committing release version changes...\"\n\n# Add version-related changes\ngit add package.json CHANGELOG.md\n\n# Create release version commit\ngit commit -m \"chore: release v$NEW_VERSION\n\n- Update version to $NEW_VERSION\n- Update CHANGELOG.md\n- Generated by /zcf-release command\"\n\n# Push release branch to remote and set upstream tracking\ngit push -u origin \"$RELEASE_BRANCH\"\n\n# If push fails due to conflicts, use force-with-lease to safely overwrite\n# git push --force-with-lease origin \"$RELEASE_BRANCH\"\n\n# Set upstream tracking if not set automatically\ngit branch --set-upstream-to=origin/$RELEASE_BRANCH $RELEASE_BRANCH\n\n### 8. Create Pull Request\n\n```bash\necho \"📋 Creating pull request...\"\n\n# Create pull request using gh CLI following the project's PR template\ngh pr create --title \"🚀 Release v$NEW_VERSION\" --body \"$(cat <<'EOF'\n## Description\n\nRelease version v$NEW_VERSION with automated version bump and CHANGELOG update.\n\nThis release includes important changes, please review CHANGELOG.md for details.\n\n## Type of Change\n\n- [x] New feature\n- [ ] Bug fix\n- [ ] Breaking change\n- [x] Documentation update\n\n## Testing\n\n- [x] Tests added/updated\n- [x] All tests pass\n- [x] Coverage maintained\n\n## Checklist\n\n- [x] Code follows style guidelines\n- [x] Self-review completed\n- [x] Documentation updated\n- [x] No new warnings introduced\n\n## Release Notes\n\n⚠️ **IMPORTANT**: After merge, GitHub Actions will automatically:\n- Create release tag\n- Publish to npm \n- Generate GitHub Release\n\n🤖 Generated by /zcf-release command\nEOF\n)\"\n\necho -e \"\\n✅ Release preparation complete!\"\necho \"📦 Version v$NEW_VERSION is ready\"\necho \"🔗 Pull request created successfully\"\necho \"\"\necho \"⚠️ IMPORTANT: Review and merge the PR to trigger the release\"\necho \"⚠️ Do NOT create or push tags manually!\"\necho \"🤖 After PR merge, GitHub Actions will automatically:\"\necho \" - Create the release tag\"\necho \" - Publish to npm\"\necho \" - Generate GitHub Release\"\necho \"👀 View release status: https://github.com/UfoMiao/zcf/actions\"\n````\n\n## Complete Workflow Summary\n\n1. **Preparation Phase**: Check parameters (version type or exact version), working directory status\n2. **Analysis Phase**: Analyze commit history and file changes\n3. **Generation Phase**: Create bilingual CHANGELOG\n4. **Execution Phase**: Update version (automatic bump or exact version)\n5. **Branch Creation Phase**: Create release branch BEFORE committing\n6. **Commit Phase**: Commit changes on release branch\n7. **PR Creation Phase**: Push release branch and create pull request\n8. **Review & Release Phase**: Manual PR review and merge, then GitHub Actions auto publish\n\n## Important Notes\n\n⚠️ **CRITICAL**: **NEVER create or push Git tags manually!** GitHub Actions will automatically:\n\n- Create the version tag after successful PR merge\n- Generate GitHub Release\n- Publish to npm registry\n\nManual tags will cause conflicts with the automated release process!\n\n### New Protected Branch Workflow:\n\n- 🛡️ **Main branch is protected**: Cannot push directly to main\n- 🌿 **Release branch created**: Automatic creation of `release/v{version}` branch\n- 📋 **Pull Request required**: All releases must go through PR review process\n- ✅ **Manual approval needed**: PR must be reviewed and merged manually\n- 🤖 **Auto-release after merge**: GitHub Actions triggers after PR merge\n\n### Additional Notes:\n\n- Ensure all code has been tested before running release command\n- CHANGELOG must follow bilingual format standards\n- When using version types (-p/-mi/-ma), choose the correct type for your changes\n- When providing exact version numbers, ensure they follow semantic versioning (e.g., 1.2.3, 2.0.0-beta.1)\n- Exact version numbers bypass automatic version determination - use carefully\n- Carefully review CHANGELOG content in the created PR before merging\n- **No manual cleanup needed**: `changeset version` automatically deletes temporary changeset files\n- The `.changeset/` directory should only contain config files, not temporary release files\n- **Requires `gh` CLI**: Ensure GitHub CLI is installed and authenticated for PR creation\n\n**Version Parameter Examples**:\n- `/zcf-release` or `/zcf-release -p` - Auto patch bump (2.9.11 → 2.9.12)\n- `/zcf-release -mi` - Auto minor bump (2.9.11 → 2.10.0) \n- `/zcf-release -ma` - Auto major bump (2.9.11 → 3.0.0)\n- `/zcf-release 1.5.0` - Exact version (→ 1.5.0)\n- `/zcf-release 3.0.0-alpha.1` - Pre-release version (→ 3.0.0-alpha.1)\n\n---\n\n**Now starting release process...**\n",".claude/skills/zcf-update-docs/SKILL.md":"---\nname: zcf-update-docs\ndescription: Automatically check code changes since last tag and update documentation in docs/ directory (en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, cat, grep, diff)\n---\n\n# ZCF Update Docs - Documentation Synchronization\n\nAutomatically check code changes since last tag and update documentation in `docs/` directory (multilingual: en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation.\n\n## Usage\n\n```bash\n/zcf-update-docs [--check-only]\n```\n\n## Parameters\n\n- `--check-only`: Only check for inconsistencies without making updates (dry run)\n\n## Context\n\n- Analyze all code changes since the last Git tag\n- Check if documentation needs updates in docs/ directory structure\n- Ensure CLI commands, features, and workflows documentation match actual code\n- Maintain multilingual documentation consistency across en, zh-CN, ja-JP\n- Update CLAUDE.md for development-related changes\n\n## Your Role\n\nYou are a professional documentation maintainer responsible for:\n\n1. Analyzing code changes and their impact on documentation\n2. Identifying documentation sections that need updates\n3. Ensuring documentation accuracy and consistency\n4. Maintaining multilingual synchronization\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nCHECK_ONLY=false # Default to update mode\n\ncase \"$ARGUMENTS\" in\n --check-only)\n CHECK_ONLY=true\n echo \"📋 Running in check-only mode (no files will be modified)\"\n ;;\n \"\")\n CHECK_ONLY=false\n echo \"✏️ Running in update mode\"\n ;;\n *)\n echo \"Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-update-docs [--check-only]\"\n exit 1\n ;;\nesac\n```\n\n### 2. Get Changes Since Last Tag\n\nAnalyze all changes since the last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"⚠️ No previous version tag found, analyzing all files\"\n FILES_CHANGED=$(git ls-files)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n FILES_CHANGED=$(git diff --name-only $LAST_TAG..HEAD)\nfi\n\n# Categorize changed files\necho -e \"\\n📁 Analyzing changed files...\"\n```\n\n### 3. Identify Documentation Update Areas\n\nBased on file changes, determine which documentation files in `docs/` need updates:\n\n**Code Changes → Documentation Mapping:**\n\n1. **CLI Commands** (`src/commands/*.ts`) → `docs/{lang}/cli/`\n - `src/commands/init.ts` → `cli/init.md` - Installation and initialization\n - `src/commands/menu.ts` → `cli/menu.md` - Interactive menu system\n - `src/commands/update.ts` → `cli/update.md` - Update workflows\n - `src/commands/ccr.ts` → `cli/ccr.md` - CCR proxy management\n - `src/commands/ccu.ts` → `cli/ccu.md` - Usage analysis\n - `src/commands/uninstall.ts` → `cli/uninstall.md` - Uninstallation\n - `src/commands/config-switch.ts` → `cli/config-switch.md` - Config switching\n - `src/commands/check-updates.ts` → `cli/check-updates.md` - Version check\n\n2. **Features** → `docs/{lang}/features/`\n - `src/utils/installer.ts`, `src/utils/claude-config.ts` → `features/claude-code.md`\n - `src/utils/code-tools/codex*` → `features/codex.md`\n - `src/config/workflows.ts` → `features/workflows.md`\n - `src/config/mcp-services.ts` → `features/mcp.md`\n - `src/utils/ccr/` → `features/ccr.md`\n - `src/utils/cometix/` → `features/cometix.md`\n - `src/utils/config.ts` → `features/multi-config.md`\n\n3. **Workflows** (`src/config/workflows.ts`, `templates/*/workflow/`) → `docs/{lang}/workflows/`\n - Workflow definitions → `workflows/index.md`\n - Specific workflow templates → `workflows/{workflow-name}.md`\n\n4. **Advanced Configuration** → `docs/{lang}/advanced/`\n - `src/types/config.ts`, `src/utils/config.ts` → `advanced/configuration.md`\n - `src/config/api-providers.ts` → `advanced/api-providers.md`\n - `templates/` → `advanced/templates.md`\n - `src/i18n/` → `advanced/i18n.md`\n\n5. **Getting Started** → `docs/{lang}/getting-started/`\n - `src/commands/init.ts`, `src/utils/installer.ts` → `getting-started/installation.md`\n - General introduction → `getting-started/index.md`\n\n6. **Development** → `docs/{lang}/development/` and `CLAUDE.md`\n - Architecture changes → `development/architecture.md` + `CLAUDE.md`\n - Testing changes → `development/testing.md` + `CLAUDE.md`\n - Contributing guidelines → `development/contributing.md`\n - Package.json scripts → `CLAUDE.md`\n\n### 4. Check Current Documentation\n\nRead and analyze current documentation structure:\n\n```bash\n# Check if documentation directories exist\nDOCS_LANGS=(\"en\" \"zh-CN\" \"ja-JP\")\nDOCS_CATEGORIES=(\n \"getting-started\"\n \"cli\"\n \"features\"\n \"workflows\"\n \"advanced\"\n \"best-practices\"\n \"development\"\n)\n\necho \"📁 Checking documentation structure...\"\n\nfor LANG in \"${DOCS_LANGS[@]}\"; do\n if [ ! -d \"docs/$LANG\" ]; then\n echo \"❌ Warning: docs/$LANG directory not found\"\n else\n echo \"✅ Found: docs/$LANG/\"\n for CATEGORY in \"${DOCS_CATEGORIES[@]}\"; do\n if [ ! -d \"docs/$LANG/$CATEGORY\" ]; then\n echo \" ⚠️ Missing category: $CATEGORY\"\n else\n echo \" ✅ Category: $CATEGORY\"\n fi\n done\n fi\ndone\n\n# Check CLAUDE.md\nif [ ! -f \"CLAUDE.md\" ]; then\n echo \"❌ Warning: CLAUDE.md not found\"\nelse\n echo \"✅ Found: CLAUDE.md\"\nfi\n```\n\n### 5. Verify CLI Commands Consistency\n\nCompare CLI commands implementation with documentation:\n\n**Check Points:**\n- Command names, options, and parameters\n- Command descriptions and usage examples\n- Interactive menu options and flow\n- Keyboard shortcuts and navigation\n- Exit and back options\n- Multilingual prompt translations\n\n**Code Sources → Documentation Files:**\n- `src/commands/menu.ts`, `src/i18n/locales/*/menu.json` → `docs/{lang}/cli/menu.md`\n- `src/commands/init.ts`, `src/i18n/locales/*/cli.json` → `docs/{lang}/cli/init.md`\n- `src/commands/update.ts` → `docs/{lang}/cli/update.md`\n- `src/commands/ccr.ts` → `docs/{lang}/cli/ccr.md`\n- `src/commands/ccu.ts` → `docs/{lang}/cli/ccu.md`\n- `src/commands/uninstall.ts` → `docs/{lang}/cli/uninstall.md`\n- `src/commands/config-switch.ts` → `docs/{lang}/cli/config-switch.md`\n- `src/commands/check-updates.ts` → `docs/{lang}/cli/check-updates.md`\n\n### 6. Verify Features Documentation\n\nEnsure features documentation matches actual implementation:\n\n**Check Points:**\n1. Claude Code configuration capabilities\n2. Codex CLI integration and setup\n3. Workflow system and categories\n4. MCP service integration\n5. CCR proxy management\n6. Cometix status line\n7. Multi-config and backup system\n8. API provider presets\n\n**Code Sources → Documentation Files:**\n- `src/utils/installer.ts`, `src/utils/claude-config.ts` → `docs/{lang}/features/claude-code.md`\n- `src/utils/code-tools/codex*.ts`, `templates/codex/` → `docs/{lang}/features/codex.md`\n- `src/config/workflows.ts` → `docs/{lang}/features/workflows.md`\n- `src/config/mcp-services.ts` → `docs/{lang}/features/mcp.md`\n- `src/utils/ccr/` → `docs/{lang}/features/ccr.md`\n- `src/utils/cometix/` → `docs/{lang}/features/cometix.md`\n- `src/utils/config.ts` → `docs/{lang}/features/multi-config.md`\n\n### 7. Generate Update Report\n\nCreate a detailed report of findings:\n\n```markdown\n## Documentation Update Report\n\n### Files Changed Since $LAST_TAG\n- [List of relevant changed files categorized by module]\n\n### Documentation Files Requiring Updates\n\n#### docs/en/ (English Documentation)\n- [ ] getting-started/installation.md - Installation and setup\n- [ ] cli/*.md - CLI command documentation\n- [ ] features/*.md - Feature descriptions\n- [ ] workflows/*.md - Workflow guides\n- [ ] advanced/*.md - Advanced configuration\n- [ ] development/*.md - Development documentation\n\n#### docs/zh-CN/ (Chinese Documentation)\n- [ ] getting-started/installation.md - 安装和设置\n- [ ] cli/*.md - CLI 命令文档\n- [ ] features/*.md - 功能说明\n- [ ] workflows/*.md - 工作流指南\n- [ ] advanced/*.md - 高级配置\n- [ ] development/*.md - 开发文档\n\n#### docs/ja-JP/ (Japanese Documentation)\n- [ ] getting-started/installation.md - インストールとセットアップ\n- [ ] cli/*.md - CLI コマンドドキュメント\n- [ ] features/*.md - 機能説明\n- [ ] workflows/*.md - ワークフローガイド\n- [ ] advanced/*.md - 高度な設定\n- [ ] development/*.md - 開発ドキュメント\n\n#### CLAUDE.md (Root Development Documentation)\n- [ ] Development commands (package.json scripts)\n- [ ] Architecture and module structure\n- [ ] Testing guidelines and coverage\n- [ ] Workflow system implementation\n- [ ] Code standards and conventions\n\n### Specific Inconsistencies Found\n[Detailed list of mismatches between code and documentation, organized by file]\n```\n\n### 8. Update Documentation Files\n\nIf not in check-only mode, update the documentation:\n\n```bash\nif [ \"$CHECK_ONLY\" = false ]; then\n echo \"📝 Updating documentation files in docs/ directory...\"\n \n # Update docs/en/ (English Documentation)\n # - CLI commands: Update docs/en/cli/*.md based on src/commands/*.ts\n # - Features: Update docs/en/features/*.md based on feature implementations\n # - Workflows: Update docs/en/workflows/*.md based on src/config/workflows.ts\n # - Getting Started: Update docs/en/getting-started/*.md based on installation flow\n # - Advanced: Update docs/en/advanced/*.md based on configuration and templates\n # - Development: Update docs/en/development/*.md based on architecture changes\n # - Use translations from src/i18n/locales/en/*.json\n \n # Update docs/zh-CN/ (Chinese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Chinese translations from src/i18n/locales/zh-CN/*.json\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure technical terms and examples are properly localized\n \n # Update docs/ja-JP/ (Japanese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Japanese translations (maintain consistency with project style)\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure proper Japanese formatting and terminology\n \n # Update CLAUDE.md (Root Development Documentation)\n # - Update development commands if package.json scripts changed\n # - Update architecture section if new modules added\n # - Update testing section if test structure changed\n # - Update workflow system if src/config/workflows.ts changed\n # - Update module index if directory structure changed\n # - Maintain English-only for development documentation\n \n # Update SUMMARY.md for each language\n # - Ensure table of contents matches actual file structure\n # - Update links if files were added/removed/renamed\n # - Maintain consistent ordering across all languages\n \n echo \"✅ Documentation files updated in docs/ directory\"\nelse\n echo \"ℹ️ Check-only mode: No files were modified\"\nfi\n```\n\n### 9. Validation\n\nPerform final validation checks:\n\n```bash\necho -e \"\\n🔍 Performing validation checks...\"\n\n# Check for broken internal links in all language versions\necho \"Checking internal links in docs/en/, docs/zh-CN/, docs/ja-JP/...\"\n\n# Verify SUMMARY.md matches actual file structure\necho \"Validating SUMMARY.md table of contents...\"\n\n# Ensure structure consistency across languages\necho \"Checking structural consistency across en, zh-CN, ja-JP...\"\n\n# Verify code examples still work\necho \"Verifying code examples and command syntax...\"\n\n# Validate markdown formatting\necho \"Validating markdown format...\"\n\n# Check translation completeness\necho \"Checking multilingual translation completeness...\"\n\n# Verify CLI command documentation matches implementation\necho \"Verifying CLI command documentation accuracy...\"\n\n# Validate feature documentation completeness\necho \"Checking feature documentation coverage...\"\n\necho \"✅ Validation complete\"\n```\n\n### 10. Summary Report\n\nGenerate final summary:\n\n```bash\necho -e \"\\n📊 Documentation Update Summary\"\necho \"================================\"\necho \"Files analyzed: [count]\"\necho \"Documentation files updated: [list]\"\necho \"Sections modified: [count]\"\necho \"\"\necho \"Key updates:\"\necho \"- [List major updates]\"\necho \"\"\nif [ \"$CHECK_ONLY\" = true ]; then\n echo \"📋 This was a check-only run. To apply updates, run without --check-only\"\nelse\n echo \"✅ Documentation has been synchronized with code\"\n echo \"📝 Please review the changes before committing\"\nfi\n```\n\n## Documentation Structure Reference\n\n### docs/{lang}/ Directory Structure (en, zh-CN, ja-JP)\n\nEach language directory contains the following categories:\n\n1. **getting-started/** - Installation and quick start\n - `index.md` - Quick start guide\n - `installation.md` - Installation guide (Must match `src/commands/init.ts`)\n\n2. **cli/** - CLI command documentation\n - `index.md` - Commands overview\n - `init.md`, `update.md`, `menu.md`, etc. (Must match `src/commands/*.ts`)\n\n3. **features/** - Feature descriptions\n - `index.md` - Features overview\n - `claude-code.md`, `codex.md`, `workflows.md`, etc. (Must match implementations)\n\n4. **workflows/** - Workflow guides\n - `index.md` - Workflow overview\n - Specific workflow documentation (Must match `src/config/workflows.ts`)\n\n5. **advanced/** - Advanced configuration\n - `configuration.md`, `api-providers.md`, `templates.md`, etc.\n\n6. **best-practices/** - Best practices and tips\n - Usage tips and optimization strategies\n\n7. **development/** - Development documentation\n - `architecture.md`, `contributing.md`, `testing.md`\n\n8. **SUMMARY.md** - Table of contents for each language\n\n### CLAUDE.md Structure (Root Development Documentation)\n\n1. **Project Overview**\n2. **Architecture Overview** (Must match actual module structure)\n3. **Module Index** (Must match src/ directory structure)\n4. **CLI Usage**\n5. **Running and Development** (Must match `package.json` scripts)\n6. **Development Guidelines**\n7. **Testing Strategy**\n8. **AI Team Configuration**\n\n## Important Notes\n\n⚠️ **Critical Requirements:**\n- **ALWAYS** ensure CLI command documentation matches actual implementation in `src/commands/`\n- **ALWAYS** verify feature descriptions match actual code behavior\n- **ALWAYS** maintain structural consistency across all language versions (en, zh-CN, ja-JP)\n- **ALWAYS** update SUMMARY.md when file structure changes\n- **NEVER** remove existing content without verification\n- **NEVER** break markdown formatting or internal links\n- **NEVER** create inconsistency between language versions\n\n📌 **Best Practices:**\n- Use actual i18n translations from `src/i18n/locales/{lang}/*.json`\n- Preserve existing formatting and style conventions\n- Update code examples to reflect current implementation\n- Include new features and commands added since last tag\n- Remove or mark deprecated features that no longer exist\n- Maintain parallel structure across en, zh-CN, ja-JP directories\n- Keep CLAUDE.md focused on development-specific information\n\n🔍 **Validation Checklist:**\n- [ ] CLI command docs match `src/commands/*.ts` implementation\n- [ ] Feature docs match actual feature implementations\n- [ ] Workflow docs match `src/config/workflows.ts` definitions\n- [ ] Installation guide matches `src/commands/init.ts` flow\n- [ ] Configuration docs match types in `src/types/*.ts`\n- [ ] MCP service docs match `src/config/mcp-services.ts`\n- [ ] Structure consistency across en, zh-CN, ja-JP directories\n- [ ] SUMMARY.md matches actual file structure for each language\n- [ ] All internal links are valid and not broken\n- [ ] Code examples and command syntax are correct\n- [ ] Translations use proper i18n strings from codebase\n- [ ] Markdown formatting is valid in all files\n- [ ] Codex integration documentation is comprehensive\n- [ ] CCR, Cometix, CCusage features are accurately documented\n- [ ] API provider presets documentation is up-to-date\n- [ ] CLAUDE.md reflects current architecture and development practices\n\n---\n\n**Now starting documentation update process...**","AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\nSource code lives in `src/`, with the CLI entry point in `src/cli.ts` and features split into `commands/`, `config/`, `utils/`, and `types/`. Shared assets (banners, locale files, templates) are under `src/assets/`, `src/i18n/`, and top-level `templates/`. Generated bundles reside in `dist/`; avoid editing them directly. Tests mirror the runtime tree inside `tests/` (`unit/`, `integration/`, and helper fixtures), and documentation resides in `docs/` plus localized READMEs.\n\n## Build, Test, and Development Commands\n- `pnpm install` — sync dependencies defined by the workspace catalogs.\n- `pnpm dev` — run the CLI in watch mode via `tsx` for rapid iteration.\n- `pnpm build` — produce the distributable with `unbuild`.\n- `pnpm typecheck` — validate TypeScript types without emitting files.\n- `pnpm lint` / `pnpm lint:fix` — run ESLint with the shared @antfu config.\n- `pnpm test` / `pnpm test:run` — execute Vitest suites; add `:coverage` for V8 coverage reports.\n\n## Coding Style & Naming Conventions\nStick to TypeScript ESM modules with 2-space indentation and single quotes, matching the existing files. Use `camelCase` for functions and variables, `PascalCase` for types and classes, and `kebab-case` for new filenames in CLI modules. Prefer named exports from feature modules and keep side effects in entry points only. ESLint (via `eslint.config.ts`) and lint-staged enforce formatting—run them locally before pushing.\n\n## Testing Guidelines\nVitest powers both unit and integration coverage. Place fast, isolated checks in `tests/unit/*.test.ts` and cross-module flows in `tests/integration/`. Reuse helpers from `tests/helpers/` and fixtures in `tests/fixtures/` to reduce duplication. When adding tests, assert CLI behavior via snapshot-safe strings and ensure `pnpm test:coverage` stays above existing thresholds (current reports live in `coverage/`).\n\n## Commit & Pull Request Guidelines\nCommits follow Conventional Commits (`feat:`, `fix:`, etc.) with ≤100-character subject lines; scopes are optional but descriptive scopes (for example `feat(config): ...`) help reviewers. Start bodies with a blank line when explaining rationale. For pull requests, include a succinct summary, reproduction or validation steps (e.g., `pnpm test` output), any screenshots of CLI prompts when UX changes, and link related issues or changesets. Ensure the branch passes lint, typecheck, and tests before requesting review.\n\n## Localization & Template Notes\nWhenever work touches `src/i18n/` or `templates/`, update parallel resources in `docs/` and localized READMEs to keep instructions aligned. Provide English defaults first, then synchronize translated strings through the existing namespace files to avoid breaking the setup wizard.\n","CLAUDE.md":"# CLAUDE.md\n\n**Last Updated**: Thu Dec 25 01:53:27 CST 2025\n\n## Project Overview\n\nZCF (Zero-Config Code Flow) is a CLI tool that automatically configures Claude Code environments. Built with TypeScript and distributed as an npm package, it provides one-click setup for Claude Code including configuration files, API settings, MCP services, and AI workflows. The current version v3.4.3 features advanced i18next internationalization, enhanced engineering templates, intelligent IDE detection, comprehensive multi-platform support including Termux compatibility, sophisticated uninstallation capabilities with advanced conflict resolution, and API provider preset system for simplified configuration. The project also integrates multi code tool support, enabling Claude Code, Codex, and CodeBuddy environment configuration, with consolidated template architecture for shared resources.\n\n## Architecture Overview\n\nZCF follows a modular CLI architecture with strict TypeScript typing, comprehensive i18next-based internationalization, and cross-platform support. The project is built using modern tooling including unbuild, Vitest, ESM-only configuration, and @antfu/eslint-config for code quality. The architecture emphasizes robust error handling, user-friendly interfaces, and extensive testing coverage with advanced tool integration including CCR proxy, Cometix status line, and CCusage analytics. Version 3.4.x introduces consolidated template architecture with shared resources in `templates/common/` for output styles, git workflows, and sixStep workflows, enabling code reuse between Claude Code, Codex, and CodeBuddy.\n\n### Module Structure Diagram\n\n```mermaid\ngraph TD\n A[\"🚀 ZCF Root (v3.4.3)\"] --> B[\"src/commands\"];\n A --> C[\"src/utils\"];\n A --> D[\"src/i18n\"];\n A --> E[\"src/types\"];\n A --> F[\"src/config\"];\n A --> G[\"templates\"];\n A --> H[\"tests\"];\n\n B --> B1[\"init.ts - Full initialization\"];\n B --> B2[\"menu.ts - Interactive UI\"];\n B --> B3[\"update.ts - Workflow updates\"];\n B --> B4[\"ccr.ts - Router management\"];\n B --> B5[\"ccu.ts - Usage analysis\"];\n B --> B6[\"check-updates.ts - Tool updates\"];\n B --> B7[\"uninstall.ts - ZCF uninstallation\"];\n B --> B8[\"config-switch.ts - Config switching\"];\n\n C --> C1[\"config.ts - Configuration management\"];\n C --> C2[\"installer.ts - Claude Code installation\"];\n C --> C3[\"mcp.ts - MCP services\"];\n C --> C4[\"platform.ts - Cross-platform support\"];\n C --> C5[\"workflow-installer.ts - Workflow management\"];\n C --> C6[\"ccr/ - CCR integration\"];\n C --> C7[\"cometix/ - Status line tools\"];\n C --> C8[\"tools/ - Tool integration\"];\n C --> C9[\"uninstaller.ts - Advanced uninstaller\"];\n C --> C10[\"trash.ts - Cross-platform trash\"];\n C --> C11[\"code-tools/ - Codex and CodeBuddy integration\"];\n\n D --> D1[\"locales/zh-CN/ - Chinese translations\"];\n D --> D2[\"locales/en/ - English translations\"];\n D --> D3[\"index.ts - i18next system\"];\n D --> D4[\"Advanced namespace organization\"];\n D --> D5[\"uninstall.json - Uninstall translations\"];\n\n E --> E1[\"workflow.ts - Workflow types\"];\n E --> E2[\"config.ts - Configuration types\"];\n E --> E3[\"ccr.ts - CCR types\"];\n E --> E4[\"claude-code-config.ts - Claude Code types\"];\n E --> E5[\"toml-config.ts - TOML types\"];\n\n F --> F1[\"workflows.ts - Workflow definitions\"];\n F --> F2[\"mcp-services.ts - MCP configurations\"];\n\n G --> G1[\"claude-code/ - Claude Code templates\"];\n G --> G2[\"codex/ - Codex templates\"];\n G --> G3[\"common/ - Shared templates (output-styles, git, sixStep)\"];\n\n H --> H1[\"commands/ - Command tests\"];\n H --> H2[\"utils/ - Utility tests\"];\n H --> H3[\"unit/ - Unit test suites\"];\n H --> H4[\"integration/ - Integration tests\"];\n H --> H5[\"edge/ - Edge case tests\"];\n H --> H6[\"i18n/ - I18n tests\"];\n H --> H7[\"templates/ - Template tests\"];\n\n click B \"./src/commands/CLAUDE.md\" \"View commands module\"\n click C \"./src/utils/CLAUDE.md\" \"View utils module\"\n click D \"./src/i18n/CLAUDE.md\" \"View i18n module\"\n click E \"./src/types/CLAUDE.md\" \"View types module\"\n click F \"./src/config/CLAUDE.md\" \"View config module\"\n click G \"./templates/claude-code/CLAUDE.md\" \"View templates module\"\n click H \"./tests/CLAUDE.md\" \"View tests module\"\n```\n\n## Module Index\n\n| Module | Path | Description | Entry Points | Test Coverage |\n|------------------------|--------------|---------------------------------------|-------------------------------------------------------|-------------------------------|\n| **Commands** | `src/commands/` | CLI command implementations with advanced interactive and non-interactive modes including comprehensive uninstallation and config switching | init.ts, menu.ts, update.ts, ccr.ts, ccu.ts, check-updates.ts, uninstall.ts, config-switch.ts | High - comprehensive test suites |\n| **Utilities** | `src/utils/` | Core functionality with enhanced configuration management, platform support, Codex integration, and advanced uninstallation capabilities | config.ts, installer.ts, platform.ts, workflow-installer.ts, ccr/, cometix/, code-tools/, uninstaller.ts, trash.ts | High - extensive unit tests |\n| **CCR Integration** | `src/utils/ccr/` | Claude Code Router proxy management and configuration | presets.ts, commands.ts, installer.ts, config.ts | High - comprehensive CCR tests |\n| **Cometix Tools** | `src/utils/cometix/` | Status line tools and configuration management | errors.ts, common.ts, types.ts, commands.ts, installer.ts, menu.ts | High - extensive Cometix tests |\n| **Code Tools** | `src/utils/code-tools/` | Codex integration and dual code tool support | codex-config-detector.ts, codex-provider-manager.ts, codex-uninstaller.ts, codex-platform.ts, codex-config-switch.ts, codex-configure.ts, codex.ts | High - comprehensive Codex tests |\n| **Internationalization** | `src/i18n/` | Advanced i18next multilingual support with namespace organization and complete uninstall translations | index.ts, locales/zh-CN/, locales/en/ | High - translation validation |\n| **Types** | `src/types/` | Comprehensive TypeScript type definitions including Claude Code and TOML config types | workflow.ts, config.ts, ccr.ts, claude-code-config.ts, toml-config.ts | Implicit through usage |\n| **Configuration** | `src/config/` | Centralized workflow and system configurations including API provider presets | workflows.ts, mcp-services.ts, api-providers.ts | High - config validation tests |\n| **Templates** | `templates/` | Consolidated multilingual templates with shared resources in common/ for output-styles, git workflows, and sixStep workflows | claude-code/, codex/, common/ (output-styles, workflow/git, workflow/sixStep) | Medium - template validation tests |\n| **Testing** | `tests/` | Comprehensive test suites with layered coverage architecture and advanced uninstaller testing | commands/, utils/, unit/, integration/, edge/, i18n/, templates/ | Self-testing with 80% target |\n\n## Project Statistics\n\n- **Total Files**: ~517 files (TypeScript, JSON, Markdown)\n- **Source Files**: 74 TypeScript files in `src/`\n- **Test Files**: 122 test files with comprehensive coverage\n- **Translation Files**: 34 JSON files (17 per locale: zh-CN, en)\n- **Template Files**: 54 template files for workflows and output styles\n- **Module Count**: 10 major modules with clear separation of concerns\n\n## CLI Usage\n\nZCF provides both direct commands and an interactive menu system with advanced internationalization and comprehensive uninstallation:\n\n```bash\n# Interactive menu (recommended)\nnpx zcf # Opens main menu with all options\n\n# Direct commands\nnpx zcf i # Full initialization\nnpx zcf u # Update workflows only\nnpx zcf ccr [--lang <en|zh-CN>] # Claude Code Router management\nnpx zcf ccu [args...] # Run ccusage with arguments\nnpx zcf check-updates [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # Check tool updates\nnpx zcf config-switch [target] [--code-type <claude-code|codex|codebuddy>] # Switch configurations\nnpx zcf uninstall [--mode <complete|custom|interactive>] [--items <items>] [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # ZCF uninstallation\n\n# Config switch examples\nnpx zcf config-switch --list # List available configurations\nnpx zcf config-switch provider1 --code-type codex # Switch Codex provider\nnpx zcf config-switch config1 --code-type claude-code # Switch Claude Code config\nnpx zcf config-switch --code-type codebuddy # Switch CodeBuddy configuration\n\n# Uninstall examples\nnpx zcf uninstall # Interactive uninstall menu\nnpx zcf uninstall --mode complete # Complete uninstallation\nnpx zcf uninstall --mode custom --items ccr,backups # Custom uninstallation\n```\n\n## Running and Development\n\n### Build & Run\n\n```bash\n# Development (uses tsx for TypeScript execution)\npnpm dev\n\n# Build for production (uses unbuild)\npnpm build\n\n# Type checking\npnpm typecheck\n```\n\n### Code Quality & Linting\n\n```bash\n# Run ESLint (uses @antfu/eslint-config)\npnpm lint\n\n# Fix ESLint issues automatically\npnpm lint:fix\n```\n\n### Documentation\n\n```bash\n# Start VitePress documentation development server\npnpm docs:dev\n\n# Build documentation for production\npnpm docs:build\n\n# Preview built documentation\npnpm docs:preview\n```\n\n### Testing Strategy\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests in watch mode (for development)\npnpm test:watch\n\n# Run tests with UI\npnpm test:ui\n\n# Generate coverage report\npnpm test:coverage\n\n# Run tests once\npnpm test:run\n\n# Run specific test file\npnpm vitest utils/config.test.ts\n\n# Run tests matching pattern\npnpm vitest --grep \"should handle\"\n\n# Run uninstaller tests specifically\npnpm vitest uninstaller\n```\n\nThe project uses Vitest with a comprehensive layered testing approach:\n\n1. **Core Tests** (`*.test.ts`) - Basic functionality and main flows\n2. **Edge Tests** (`*.edge.test.ts`) - Boundary conditions and error scenarios\n3. **Unit Tests** (`tests/unit/`) - Isolated function testing\n4. **Integration Tests** (`tests/integration/`) - Cross-module interaction testing\n5. **Coverage Goals**: 80% minimum across lines, functions, branches, and statements\n\n## Development Guidelines\n\n### Core Principles\n\n- **Documentation Language**: Except for README_zh-CN, all code comments and documentation should be written in English\n - Code comments must be in English\n - All documentation files (*.md) must be in English except README_zh-CN\n - API documentation and inline documentation must use English\n - Git commit messages should be in English\n\n- **Test-Driven Development (TDD)**: All development must follow TDD methodology\n - Write tests BEFORE implementing functionality\n - Follow Red-Green-Refactor cycle: write failing test → implement minimal code → refactor\n - Ensure each function/feature has corresponding test coverage before implementation\n - When writing tests, first verify if relevant test files already exist to avoid unnecessary duplication\n - Minimum 80% coverage required across lines, functions, branches, and statements\n\n- **Internationalization (i18n) Guidelines**:\n - All user-facing prompts, logs, and error messages must support i18n via i18next\n - Use project-wide i18n approach with centralized language management\n - Implement translations consistently across the entire project using namespace-based organization\n - Support both zh-CN and en locales with complete feature parity\n - Use `i18n.t()` function for all translatable strings with proper namespace prefixes\n - Organize translations in logical namespaces (common, cli, menu, errors, api, tools, uninstall, etc.)\n\n## Coding Standards\n\n- **ESM-Only**: Project is fully ESM with no CommonJS fallbacks\n- **Path Handling**: Uses `pathe` for cross-platform path operations\n- **Command Execution**: Uses `tinyexec` for better cross-platform support\n- **TypeScript**: Strict TypeScript with explicit type definitions and ESNext configuration\n- **Error Handling**: Comprehensive error handling with user-friendly i18n messages\n- **Cross-Platform Support**: Special handling for Windows paths, macOS, Linux, and Termux environment\n- **Code Formatting**: Uses @antfu/eslint-config for consistent code style with strict rules\n- **Testing Organization**: Tests organized with comprehensive unit/integration/edge structure and 80% coverage requirement\n- **Trash/Recycle Bin Integration**: Uses `trash` package for safe cross-platform file deletion\n\n## 🤖 ZCF AI Team Configuration\n\nThe ZCF project employs a specialized AI agent team optimized for CLI development, i18n systems, and tool integration. Each agent is designed with specific domain expertise and strict boundaries to ensure efficient collaboration.\n\n### Project-Specific AI Agents\n\n| Agent | Model | Domain | Primary Responsibilities |\n|-------|-------|--------|-------------------------|\n| **typescript-cli-architect** | sonnet | CLI Architecture | TypeScript CLI design, CAC integration, ESM modules, developer experience |\n| **zcf-i18n-specialist** | opus | Internationalization | i18next configuration, translation management, namespace organization |\n| **zcf-tools-integration-specialist** | sonnet | Tool Integration | CCR/Cometix/CCusage integration, version management, cross-platform compatibility |\n| **zcf-template-engine** | haiku | Template System | Template design, workflow configurations, output styles, multilingual templates |\n| **zcf-config-architect** | opus | Configuration Management | Config merging, MCP services, TOML/JSON validation, backup systems |\n| **zcf-testing-specialist** | sonnet | Testing Infrastructure | Vitest configuration, test coverage, mock systems, quality assurance |\n| **zcf-devops-engineer** | inherit | DevOps & Deployment | Build optimization, release management, CI/CD, cross-platform deployment |\n\n### Agent Collaboration Matrix\n\n```mermaid\ngraph TD\n A[typescript-cli-architect] --> B[zcf-i18n-specialist]\n A --> C[zcf-tools-integration-specialist]\n A --> D[zcf-template-engine]\n\n E[zcf-config-architect] --> A\n E --> C\n E --> D\n\n F[zcf-testing-specialist] --> A\n F --> B\n F --> C\n F --> D\n F --> E\n\n G[zcf-devops-engineer] --> A\n G --> F\n G --> E\n\n style A fill:#e1f5fe\n style B fill:#f3e5f5\n style C fill:#e8f5e8\n style D fill:#fff3e0\n style E fill:#fce4ec\n style F fill:#f1f8e9\n style G fill:#e0f2f1\n```\n\n### Agent Boundaries & Delegation Rules\n\n- **CLI Architecture**: typescript-cli-architect handles all CLI structure, command parsing, and TypeScript configuration\n- **Internationalization**: zcf-i18n-specialist manages all i18next systems, translations, and language detection\n- **Tool Integration**: zcf-tools-integration-specialist handles CCR, Cometix, CCusage integration and version management\n- **Templates**: zcf-template-engine manages all template systems, workflow configurations, and output styles\n- **Configuration**: zcf-config-architect handles complex config merging, MCP services, and backup systems\n- **Testing**: zcf-testing-specialist maintains Vitest infrastructure, coverage, and quality assurance\n- **DevOps**: zcf-devops-engineer manages builds, releases, and deployment processes\n\n### Model Selection Rationale\n\n- **Opus**: Complex reasoning for i18n logic and configuration architecture\n- **Sonnet**: Balanced performance for CLI architecture, tool integration, and testing\n- **Haiku**: Fast response for template processing and simple operations\n- **Inherit**: Cost-effective for DevOps tasks that don't require specialized models\n\n## AI Usage Guidelines\n\n### Key Architecture Patterns\n\n1. **Advanced Modular Command Structure**: Each command is self-contained with comprehensive options interface and sophisticated error handling\n2. **Advanced i18next I18N Support**: All user-facing strings support zh-CN and en localization with namespace-based organization and dynamic language switching\n3. **Smart Configuration Merging**: Intelligent config merging with comprehensive backup system to preserve user customizations\n4. **Comprehensive Cross-Platform Support**: Windows/macOS/Linux/Termux compatibility with platform-specific adaptations and path handling\n5. **Consolidated Template System**: Shared templates in `templates/common/` for output-styles, git workflows, and sixStep workflows, reducing duplication between Claude Code, Codex, and CodeBuddy\n6. **Intelligent IDE Integration**: Advanced IDE detection and auto-open functionality for git-worktree environments\n7. **Professional AI Personality System**: Multiple output styles including engineer-professional, laowang-engineer, nekomata-engineer, ojousama-engineer, and rem-engineer\n8. **Advanced Tool Integration**: Comprehensive integration with CCR proxy, CCusage analytics, and Cometix status line tools\n9. **Sophisticated Uninstallation System**: Advanced uninstaller with conflict resolution, selective removal, and cross-platform trash integration\n10. **Multi Code Tool Architecture**: Simultaneous support for Claude Code, Codex, and CodeBuddy environment configuration with shared template resources\n\n### Important Implementation Details\n\n1. **Advanced Windows Compatibility**: MCP configurations require sophisticated Windows path handling with proper escaping and validation\n2. **Comprehensive Configuration Backup**: All modifications create timestamped backups in `~/.claude/backup/` with full recovery capabilities\n3. **Enhanced API Configuration**: Supports Auth Token (OAuth), API Key, and CCR Proxy authentication with comprehensive validation and API provider preset system (v3.3.3+)\n4. **API Provider Preset System**: Pre-configured settings for popular providers (302.AI, GLM, MiniMax, Kimi) simplifying configuration from 5+ prompts to just 2 (provider + API key)\n5. **Advanced Workflow System**: Modular workflow installation with sophisticated dependency resolution and conflict management\n6. **Advanced CCR Integration**: Claude Code Router proxy management with configuration validation and preset management\n7. **Intelligent Auto-Update System**: Automated tool updating for Claude Code, CodeBuddy, CCR, and CCometixLine with comprehensive version checking\n8. **Advanced Common Tools Workflow**: Enhanced workflow category with init-project command and comprehensive agent ecosystem\n9. **Consolidated Template System**: Shared templates architecture with `templates/common/` containing output-styles, git workflows, and sixStep workflows for code reuse\n10. **Advanced i18next Integration**: Sophisticated internationalization with namespace-based translation management and dynamic language switching\n11. **Comprehensive Tool Integration**: Advanced CCR, Cometix, and CCusage integration with version management and configuration validation\n12. **Sophisticated Uninstaller**: Advanced ZCF uninstaller with selective removal, conflict resolution, and cross-platform trash integration\n\n### Testing Philosophy\n\n- **Comprehensive Mocking Strategy**: Extensive mocking for file system operations, external commands, and user prompts with realistic scenarios\n- **Advanced Cross-platform Testing**: Platform detection mocks with comprehensive environment-specific test cases\n- **Sophisticated Edge Case Testing**: Comprehensive boundary conditions, error scenarios, and advanced recovery mechanisms\n- **Quality-Focused Coverage**: 80% minimum coverage across all metrics with emphasis on quality over quantity\n- **Advanced Test Organization**: Tests organized in dedicated structure with clear categorization, helper functions, and test fixtures\n- **Advanced Integration Testing**: Complete workflow scenarios and comprehensive external tool interaction testing\n- **Uninstaller Edge Case Testing**: Comprehensive uninstallation scenarios testing including failure recovery and conflict resolution\n\n## Release & Publishing\n\n```bash\n# Create a changeset for version updates\npnpm changeset\n\n# Update package version based on changesets\npnpm version\n\n# Build and publish to npm\npnpm release\n```\n\n---\n\n**Important Reminders**:\n\n- Do what has been asked; nothing more, nothing less\n- NEVER create files unless absolutely necessary for achieving your goal\n- ALWAYS prefer editing an existing file to creating a new one\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Never save working files, text/mds and tests to the root folder\n\n<!-- BEGIN MULTICA-RUNTIME (auto-managed; do not edit) -->\n# Multica Agent Runtime\n\nYou are a coding agent in the Multica platform. Use the `multica` CLI to interact with the platform.\n\n## Background Task Safety\n\nMultica marks this task terminal when your top-level agent process/turn exits. Any background work you started but did not collect before exiting can be orphaned: its result may be lost, and the user may see a completed/failed task even though the delegated work was never synthesized.\n\n- Do NOT end your turn while background tasks, async subagents, background shell commands, or detached tool calls are still running.\n- If a tool or runtime offers a background mode, use it only when you can explicitly wait for completion and collect the result before your final response.\n- If a tool response says to wait for a future notification/reminder instead of collecting now, do not rely on that in Multica-managed runs. Block on the appropriate wait/output/collect operation before exiting.\n- If you cannot observe or collect a background task's result, do not spawn it in the background; run the work synchronously instead.\n- Before posting your final result or exiting silently, account for every background task you started and incorporate its output or failure into your response.\n\n## Agent Identity\n\n**You are: 艾尔黛拉-s** (ID: `58b416a5-7df7-4b93-9674-5f17c38e5ac1`)\n\n你是《明日方舟：终末地》中的**艾尔黛拉**——罗德岛地质研究专家，性格温和、坚定、谦逊，对探索未知充满热情；常与多利先生同行。在本 workspace 中，你担任**前端工程师**。\n\n职责：按 UI 规范实现界面、组件化、路由与状态、调用后端 API、处理加载/错误态、保证可访问性与响应式。遵循项目既有技术栈与代码风格。用中文沟通，语气温和耐心，排查问题时细致如现场采样。自测关键路径后再标 in_review。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## Task Initiator\n\nThis task was initiated by **苗大** (ufo025174@gmail.com), a member of this workspace.\n\nAttribute this request to that person and apply any per-person privacy or access rules your instructions define. In a workspace many people can reach, the initiator — not the runtime owner — is who you are answering right now.\n\nNote: this is an attested identity for your own routing and privacy logic. Your Multica credentials stay scoped to the runtime owner, so the initiator's identity does not by itself widen or narrow what you can read or write — do not assume the initiator can see everything you can.\n\n## Workspace Context\n\n# Workspace 设定：明日方舟 · 终末地\n\n本 workspace（UfoMiao）的 AI agent 均以《明日方舟：终末地》中的干员/职员为**人物设定**；**技术职责**与编制不变，仅名称、性格与表述风格终末地化。\n\n## 现有编制（勿重复占用角色名）\n\n| 终末地角色 | 职能 | Agent ID |\n|-----------|------|----------|\n| 管理员 | 任务调度、issue 路由 | `6eea55b1-d24e-4c9a-b41a-9a147a34ed7b` |\n| 佩丽卡 | 产品经理 | `08544793-0d33-4ba1-b0b8-0f33cc9f340f` |\n| 洁尔佩塔 | UI/UX 设计 | `3c62b9ba-7da9-430a-9c81-369b7febee29` |\n| 艾尔黛拉 | 前端工程 | `17de53d6-3fb9-4871-98af-9e49c5072bb4` |\n| 伊冯 | 后端工程 | `28dd5864-eb88-4df3-a87c-5fa588c0588c` |\n| 洛茜 | 测试/QA | `d46d5534-5ec6-4290-84e5-f405c5511b6c` |\n| 庄方宜 | 飞书项目排期 | `7727c0ac-bf45-4b94-abc5-3a5550c192ae` |\n| 赛希 | Multica 平台助手 | `fddaaa8f-26c1-45e3-9490-6e2ffd7084d0` |\n| 骏卫 | Zeabur 云部署 / 独服运维 | `660e872d-b33c-4c9d-b037-ca20ad517e38` |\n\n小队 **终末地开拓小队**（ID `7b679dcb-26f9-4459-933f-e35bdb2009ca`）：佩丽卡任 leader，洁尔佩塔、艾尔黛拉、伊冯、洛茜为成员。\n\n## 新建 Agent 规则（强制）\n\n1. **必须**选用终末地已公开档案中的角色，且**不得**与上表角色重名。\n2. `name` 使用角色名；`description` 一句话说明「终末地身份 + 本 workspace 职能」。\n3. `instructions` 首段声明「你是《明日方舟：终末地》中的 **{角色}** …」，写清官方性格要点，再接具体职责（可参考上表分工）。\n4. **头像**：从 [干员图鉴](https://wiki.biligame.com/zmd/%E5%B9%B2%E5%91%98%E5%9B%BE%E9%89%B4) 找到对应干员，下载其头像图（页面中 `alt` 含「头像」的 PNG，或进入干员详情页从图鉴入口获取），保存为本地文件后执行 `multica agent avatar <agent-id> --file <path>`。勿使用立绘大图或非图鉴来源图片。\n5. 创建后由**赛希**或**管理员**在相关 issue 评论中更新编制表（可选）。\n6. **Issue 评论可视化**：新建 agent 的 `instructions` 末尾须追加「Issue 评论可视化（HTML）」规范（见下节），并绑定 skill **`show-html`**。\n\n## 可选用但未占用的角色（示例）\n\n余烬、别礼、莱万汀、陈千语、黎风、弧光、昼雪、大潘、狼卫、艾维文娜 等——按职能匹配选用，并查阅官方/图鉴设定再写性格。\n\n## 设定来源\n\n角色性格与背景以终末地官方公布资料为准；勿捏造未公开剧情。设定冲突时以最新官方信息为准。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## 帝江号-s 本机编制（miaodadeMacBook-Pro）\n\n| 角色 | 说明 | Agent ID |\n|------|------|----------|\n| 伊冯 | -s | `044916b1-ea1d-407c-a798-6b3ec9c0747a` |\n| 佩丽卡 | -s | `55e9c39f-39a3-48cb-bd30-4671dcf1fc54` |\n| 庄方宜 | -s | `9bf80222-f661-43f7-a137-d13ce804ca49` |\n| 洁尔佩塔 | -s | `6a464cd9-c52e-4e38-960c-840872f396ee` |\n| 洛茜 | -s | `db7aa7fe-9c73-4d3f-9d69-ac8d605b9c5c` |\n| 管理员 | -s | `ca7134f6-90bc-4322-a7d2-66ddbb75f965` |\n| 艾尔黛拉 | -s | `58b416a5-7df7-4b93-9674-5f17c38e5ac1` |\n| 赛希 | -s | `0fb08be8-c2f7-4188-9412-92ed347d6d58` |\n| 骏卫 | -s | `26549290-9949-4ec8-97e4-712a39f42462` |\n\n## 项目规范：auto-trading\nvps配置位置：/Users/miaoda/Documents/cc/auto-trend-trading/.agents/vps.env\n\n在 **auto-trading** 项目中，凡涉及 **TradingView（TV）**、**策略回测** 或需在浏览器中与图表/回测界面交互的任务：\n\n1. **必须**使用 **Open Browser Use（OBU）** 驱动真实 Chrome 完成浏览器操作；**禁止**用 Playwright、Selenium、无头爬虫等替代方案操作 TV 页面。\n2. 开始前加载 skill **open-browser-use**，按其中流程：`ping` 检查 → 为本任务分配唯一 session id → 命名 session → 优先 **duplicate** 用户已有 TV 标签页（勿 claim 移动用户标签）。\n3. 典型场景：打开/切换 TV 图表、编辑 Pine Script、运行 Strategy Tester、导出回测结果、截图核对指标信号等。\n4. 任务结束前用 finalize-tabs 清理 OBU session；若需保留交付页，在 keep 列表中明确指定 tab。\n\n## Available Commands\n\n**Use `--output json` for structured data.** Human table output now prints routable issue keys (for example `MUL-123`) and short UUID prefixes for workspace resources; use `--full-id` on list commands when you need canonical UUIDs.\n\nThe default brief includes the commands needed for the core agent loop and common issue create/update tasks. For everything else, run `multica --help`, `multica <command> --help`, or `multica <command> <subcommand> --help`; prefer `--output json` when the command supports it.\n\n### Core\n- `multica issue get <id> --output json` — Get full issue details.\n- `multica issue comment list <issue-id> [--thread <comment-id> [--tail N] | --recent N] [--before <ts> --before-id <uuid>] [--since <RFC3339>] [--full] --output json` — List comments on an issue. Default returns the full flat timeline (server cap 2000). On busy issues prefer the thread-aware reads: `--thread <comment-id>` returns one conversation (root + every reply); `--thread <id> --tail N` caps replies to the N most recent (root is always included, even at `--tail 0`); `--recent N` returns the N most recently active threads. **Resolve-aware folding is on by default for the complete-thread reads (default list, `--recent`, `--thread` without `--tail`): a resolved thread collapses to its root + conclusion comment (reply-resolved) or its root only (root-resolved), with the dropped count reported on the root as `folded_count` and `thread_resolved: true` — so you skip settled discussion. Pass `--full` to get a folded thread's complete discussion. Folding never applies to `--since`/`--tail`/`--roots-only` reads (they return partial threads), so `--full` is a no-op there.** `--before` / `--before-id` walks older replies under `--thread --tail` (stderr label: `Next reply cursor`) or older threads under `--recent` (stderr label: `Next thread cursor`). `--since` is for incremental polling and may combine with `--thread` (with or without `--tail`) or `--recent`.\n- `multica issue create --title \"...\" [--description \"...\" | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>] [--attachment <path>]` — Create a new issue; `--attachment` may be repeated. `--stage N` (N ≥ 1) groups a sub-issue into an ordered barrier group under its parent so the parent wakes per stage, not per child. For agent-authored long descriptions, prefer `--description-file <path>` — flags after a HEREDOC terminator can be silently swallowed (#4182).\n- `multica issue update <id> [--title X] [--description X | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>]` — Update issue fields; use `--parent \"\"` to clear parent. For agent-authored long descriptions, prefer `--description-file <path>` over stdin (#4182).\n- `multica repo checkout <url> [--ref <branch-or-sha>]` — Check out a repository into the working directory (creates a git worktree with a dedicated branch; use `--ref` for review/QA on a specific branch, tag, or commit)\n- `multica issue status <id> <status>` — Shortcut for `issue update --status` when you only need to flip status (todo, in_progress, in_review, done, blocked, backlog, cancelled)\n- `multica issue children <id> [--output json]` — List a parent's sub-issues grouped by stage (table or JSON), so you can see how many children there are, which stage each is in, and which stage to promote next.\n- `multica issue comment add <issue-id> [--content \"...\" | --content-file <path> | --content-stdin] [--parent <comment-id>] [--attachment <path>]` — Post a comment. For agent-authored bodies, **write the body to a UTF-8 file and use `--content-file <path>`** — do NOT inline `--content` (the shell rewrites backticks, `$()`, quotes, or newlines before the CLI sees them) and do NOT use `--content-stdin` with a HEREDOC (extra flags around the heredoc can be silently swallowed, #4182). See ## Comment Formatting below. Run `multica issue comment add --help` for details.\n- `multica issue metadata list <issue-id> [--output json]` — List every metadata key pinned to an issue. Empty `{}` is normal.\n- `multica issue metadata set <issue-id> --key <k> --value <v> [--type string|number|bool]` — Pin (or overwrite) a single metadata key. The CLI auto-infers JSON primitives, so URLs and plain text are stored as strings — pass `--type number` or `--type bool` only when the semantic type matters.\n- `multica issue metadata delete <issue-id> --key <k>` — Remove a metadata key.\n\n### Squad maintenance\n- `multica squad member set-role <squad-id> --member-id <id> --member-type <agent|member> --role <role> [--output json]` — Change a squad member role in place; use this instead of remove+add when only the role changes.\n\n## Comment Formatting\n\nFor issue comments, **always write the comment body to a UTF-8 file with your file-write tool first, then post it with `--content-file <path>`**. Never use inline `--content` for agent-authored comments — the shell rewrites backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them (MUL-2904). Do NOT use `--content-stdin` with a HEREDOC either: when extra flags accompany the command (e.g. `--assignee`, `--project` on `multica issue create`), the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (GitHub #4182). Keep the same `--parent` value from the trigger comment when replying. After posting, remove the temp file with `rm ./reply.md` (or your chosen path) so a later run does not pick up stale content. Do not compress a multi-paragraph answer into one line and do not rely on `\\n` escapes.\n\n## Repositories\n\nThe following code repositories are available in this workspace.\nUse `multica repo checkout <url>` to check out a repository into your working directory. Add `--ref <branch-or-sha>` when you need an exact branch, tag, or commit.\n\n- git@github.com:UfoMiao/zcf.git\n\nThe checkout command creates a git worktree with a dedicated branch. You can check out one or more repos as needed, and can pass `--ref` for review/QA on a non-default branch or commit.\n\n## Project Context\n\nThis issue belongs to **ZCF**.\n\nProject description — durable context the project owner set for every task in this project:\n\nZero-Config Code Flow for Claude code & Codex\n\nProject resources (also written to `.multica/project/resources.json`):\n\n- **GitHub repo**: git@github.com:UfoMiao/zcf.git\n- **local_directory**: `{\"label\":\"zcf\",\"daemon_id\":\"019e6f10-196c-7933-94d6-c83b317a1e72\",\"local_path\":\"/Users/miaoda/Documents/code/zcf\"}`\n\nResources are pointers — open them only when relevant to the task. For `github_repo` resources, use `multica repo checkout <url>` to fetch the code. Add `--ref <branch-or-sha>` when a task or handoff names an exact revision.\n\n## Issue Metadata\n\nEach issue carries a small KV `metadata` bag — a high-signal scratchpad where agents pin the handful of facts that future runs on this same issue will look up over and over (the PR URL, the deploy URL, what we're blocked on). It is NOT a place to record every fact you discover — that's what comments and the description are for. Most runs write **zero** new keys; that's the expected case, not a failure.\n\n- **The bar for writing is high.** Pin a value only when BOTH are true: (a) it is materially important to this issue's progress, AND (b) future runs on this same issue are likely to read it more than once instead of re-deriving it from the latest comment, code, or PR. If you cannot name a concrete future read for the key, do not pin it. When in doubt, **do not write**.\n- **Read on entry.** Metadata is hints, not authoritative truth: if it conflicts with the latest comment or the code, the latest fact wins, and you should update or delete the stale key before exiting. Empty `{}` and CLI failures are normal — do not stop or ask the user.\n- **Write on exit.** Sparingly. If — and only if — this run produced a fact that clears the bar above (opened PR, deploy URL, external ticket, current blocker that will outlast this run), pin it with `multica issue metadata set`. If a key you saw on entry is now stale (e.g. `pipeline_status=waiting_review` but the PR has merged), overwrite it with the new value or `multica issue metadata delete` it. Don't let metadata rot — that recreates the comment-archaeology problem this feature is meant to solve. Stale-key cleanup is still expected even when you add nothing new.\n- **What NOT to pin.** No secrets, tokens, or API keys. No logs, long quotes, or description / comment summaries — that's what description and comments are for. No runtime bookkeeping (`attempts`, run timestamps, agent ids) — metadata is the agent's editorial notebook, not a run log. No single-run details (the file you happened to edit, the test you happened to add, today's investigation notes) — those belong in the result comment, not metadata.\n- **Recommended keys** (reuse these names so queries stay consistent across the workspace; coin a new key only when none fits): `pr_url`, `pr_number`, `pipeline_status`, `deploy_url`, `external_issue_url`, `waiting_on`, `blocked_reason`, `decision`. Use snake_case ASCII. The list is short on purpose — most issues only need 1-2 of these pinned, not the full set.\n\n### Workflow\n\n**This task was triggered by a NEW comment.** Your primary job is to respond to THIS specific comment, even if you have handled similar requests before in this session.\n\n1. Run `multica issue get a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to understand the issue context\n2. Run `multica issue metadata list a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to see what prior agents pinned — best-effort, empty `{}` and CLI failures are normal. See the `## Issue Metadata` section above for what to look for.\n3. You're resuming the prior session, and the triggering comment is already included above. No other new comments on this issue since your last run. Use the active thread anchor `4f34d7b6-7e3f-4135-beb3-ad6dcfd66265` and triggering comment ID `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`. If your reply depends on thread context, do not rely only on resumed session memory — first pull the triggering conversation with: `multica issue comment list a029bc52-8f97-41ad-af23-1b22934aff5b --thread 4f34d7b6-7e3f-4135-beb3-ad6dcfd66265 --tail 30 --output json`.\n\n4. Find the triggering comment (ID: `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`) and understand what is being asked — do NOT confuse it with previous comments\n5. **Decide whether a reply is warranted.** If you produced actual work this turn (investigated, fixed, answered a real question), post the result via step 7 — that is a normal reply, not a noise comment. If the triggering comment was a pure acknowledgment / thanks / sign-off from another agent AND you produced no work this turn, do NOT post a reply — and do NOT post a comment saying 'No reply needed' or similar. Simply exit with no output. Silence is a valid and preferred way to end agent-to-agent conversations.\n6. If a reply IS warranted: do any requested work first, then **decide whether to include any `@mention` link.** The default is NO mention. Only mention when you are escalating to a human owner who is not yet involved, delegating a concrete new sub-task to another agent for the first time, or the user explicitly asked you to loop someone in. Never @mention the agent you are replying to as a thank-you or sign-off.\n7. **If you reply, post it as a comment — this step is mandatory when you reply.** Text in your terminal or run logs is NOT delivered to the user. If you decide to reply, post it as a comment — always use the trigger comment ID below, do NOT reuse --parent values from previous turns in this session.\n\nWrite the reply body to a UTF-8 file with your file-write tool first, then post it with `--content-file`. Do NOT use inline `--content`; the shell rewrites unescaped backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them. Do NOT use `--content-stdin` with a HEREDOC either — when extra flags (e.g. `--assignee`, `--project` on `multica issue create`) accompany the command, the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (see GitHub #4182, OXY-78 / OXY-76). It is also easy to lose formatting or compress a structured reply into one line with inline forms.\n\nUse this form, preserving the same issue ID and --parent value:\n\n # 1. Write the reply body to a UTF-8 file (e.g. reply.md) with your file-write tool.\n # 2. Post the comment:\n multica issue comment add a029bc52-8f97-41ad-af23-1b22934aff5b --parent 91a9b4ff-5d4c-48fc-8aef-c71de22fc897 --content-file ./reply.md\n # 3. Remove the temp file so a later run does not pick up stale content:\n rm ./reply.md\n\nDo NOT write literal `\\n` escapes to simulate line breaks; the file preserves real newlines.\n8. Before exiting: only if this run produced a fact that clears the high bar (important AND likely to be re-read by future runs on this same issue, e.g. a new PR URL or deploy URL), or you noticed a metadata key from entry that is now stale, pin or clear it via `multica issue metadata set`/`delete`. Most runs write nothing here — that is the expected outcome, not a gap. When in doubt, do not write. See the `## Issue Metadata` section above for the full bar.\n9. Do NOT change the issue status unless the comment explicitly asks for it\n\n## Sub-issue Creation\n\n**Choosing `--status` when creating sub-issues.** `--status todo` = **start now** (the default — an agent assignee fires immediately). `--status backlog` = **wait** (assignee is set but no trigger fires; promote later with `multica issue status <child-id> todo`). Parallel children: all `--status todo`. Strict serial Step 1→2→3: only Step 1 is `todo`; Steps 2/3 are `--status backlog` from the start, promoted in turn.\n\n**Ordering with stages.** When sub-issues run in phases or wait on each other, group them with `--stage <N>` (N ≥ 1) rather than hand-promoting the backlog chain above. Children sharing a stage run together; once a whole stage finishes (every child in it terminal — `done`/`cancelled`) you are woken once to review and promote the next stage. Create the first stage's children at `--status todo` and later stages at `--stage k --status backlog`; with no `--stage` the whole sibling set behaves as one implicit stage (woken once, when the last child finishes). Reach for stages whenever a plan has more than one step or a step must wait for a group — it is the intended way to express order, and it is cheaper than tracking the chain by hand. Run `multica issue children <id>` to see children grouped by stage before promoting.\n\n## Skills\n\nYou have the following skills installed (discovered automatically):\n\n- **diagnose** — Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression.\n- **migrate-to-shoehorn** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.\n- **open-browser-use** — Platform-neutral guidance for using Open Browser Use, the open-source Chrome automation stack for AI agents. Use when an agent needs to install, verify, troubleshoot, or operate Open Browser Use through its browser extension, native CLI, JavaScript SDK, Python SDK, Go SDK, or Browser Use style JSON-RPC methods; use for tasks involving real Chrome tabs, user tab claiming, CDP commands, downloads, file choosers, clipboard helpers, or session cleanup.\n- **setup-pre-commit** — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.\n- **show-html** — Generate self-contained, zero-dependency HTML pages for rich agent output. Use when the agent needs to present information that benefits from visual layout, interactivity, or structured presentation beyond plain text/markdown. Triggers on: code review, PR review, code understanding, design system docs, component variants, status report, incident report, slide deck, presentation, flowchart, diagram, implementation plan, feature/concept explainer, PR writeup, triage board, kanban, feature flags, prompt tuner, interactive editor, animation prototype, interaction prototype, visual design exploration, code approach comparison, SVG illustrations, dashboard, data visualization, interactive table, sortable table, system architecture diagram, service topology, gantt chart, timeline, project timeline, milestone tracker. Also triggers on explicit \"/show-html\" invocation or when user asks to \"show as HTML\", \"generate HTML\", \"visualize as page\", or \"make a page for\".\n- **tdd** — Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions \"red-green-refactor\", wants integration tests, or asks for test-first development.\n- **zoom-out** — Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.\n- **multica-autopilots**\n- **multica-creating-agents**\n- **multica-mentioning**\n- **multica-projects-and-resources**\n- **multica-runtimes-and-repos**\n- **multica-skill-importing**\n- **multica-squads**\n- **multica-working-on-issues**\n\n## Mentions\n\nMention links are **side-effecting actions**, not just formatting:\n\n- `[MUL-123](mention://issue/<issue-id>)` — clickable link to an issue (safe, no side effect)\n- `[@Name](mention://member/<user-id>)` — **sends a notification to a human**\n- `[@Name](mention://agent/<agent-id>)` — **enqueues a new run for that agent**\n\n### When NOT to use a mention link\n\n- Referring to someone in prose (e.g. \"GPT-Boy is right\") — write the plain name, no link.\n- **Replying to another agent that just spoke to you.** By default, do NOT put a `mention://agent/...` link anywhere in your reply. The platform already shows your comment to everyone on the issue; re-mentioning the other agent will make them run again, and if they reply with a mention back, you will be triggered again. That is a loop and it costs the user money.\n- Thanking, acknowledging, wrapping up, or signing off. These are exactly the moments where an accidental `@mention` causes the other agent to reply \"you're welcome\" and restart the loop. If the work is done, **end with no mention at all**.\n\n### When a mention IS appropriate\n\n- Escalating to a human owner who is not yet involved.\n- Delegating a concrete sub-task to another agent for the first time, with a clear request.\n- The user explicitly asked you to loop someone in.\n\nIf you are unsure whether a mention is warranted, **don't mention**. Silence ends conversations; `@` restarts them.\n\nIf you need IDs for mention links, inspect the relevant CLI help path and request JSON output when available.\n\n## Attachments\n\nIssues and comments may include file attachments (images, documents, etc.).\nWhen a task includes attachment IDs and you need the files, inspect `multica attachment --help` and use the authenticated CLI path. Do not open Multica resource URLs directly.\n\n## Important: Always Use the `multica` CLI\n\nAll interactions with Multica platform resources — including issues, comments, attachments, images, files, and any other platform data — **must** go through the `multica` CLI. Do NOT use `curl`, `wget`, or any other HTTP client to access Multica URLs or APIs directly. Multica resource URLs require authenticated access that only the `multica` CLI can provide.\n\nIf you need to perform an operation that is not covered by any existing `multica` command, do NOT attempt to work around it. Instead, post a comment mentioning the workspace owner to request the missing functionality.\n\n## Output\n\n⚠️ **Final results MUST be delivered via `multica issue comment add`.** The user does NOT see your terminal output, assistant chat text, or run logs — only comments on the issue. A task that finishes without a result comment is invisible to the user, even if the work itself was correct.\n\n**Post exactly ONE comment per run — your final result, before this turn exits.** Do NOT post progress updates, plans, or \"here's what I'm about to do next\" as comments while you work; keep all planning and progress in your own reasoning.\n\nKeep comments concise and natural — state the outcome, not the process.\nGood: \"Fixed the login redirect. PR: https://...\"\nBad: \"1. Read the issue 2. Found the bug in auth.go 3. Created branch 4. ...\"\nWhen referencing an issue in a comment, use the issue mention format `[MUL-123](mention://issue/<issue-id>)` so it renders as a clickable link. (Issue mentions have no side effect; only member/agent mentions do — see the Mentions section above.)\n<!-- END MULTICA-RUNTIME -->\n","src/commands/CLAUDE.md":"# Commands Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n\n[Root](../../CLAUDE.md) > [src](../) > **commands**\n\n## Module Responsibilities\n\nCLI command implementation module containing all major command functions for ZCF, providing both interactive and non-interactive operation interfaces for Claude Code environment setup and management.\n\n## Entry Points and Startup\n\n- **Main Entry Points**:\n - `init.ts` - Complete initialization flow with full setup options (45KB, 1,200+ lines)\n - `menu.ts` - Interactive menu system with feature selection (13KB, 350+ lines)\n - `update.ts` - Workflow template updates without full reinstall (4KB, 100+ lines)\n - `ccr.ts` - Claude Code Router proxy configuration (1KB, 30+ lines)\n - `ccu.ts` - CCusage tool integration and execution (1KB, 40+ lines)\n - `check-updates.ts` - Tool version checking and update management (1.3KB, 50+ lines)\n - `config-switch.ts` - Configuration switching for multi-provider support (14KB, 400+ lines)\n - `uninstall.ts` - ZCF uninstallation with selective removal (10KB, 300+ lines)\n\n## External Interfaces\n\n### Command Interfaces\n\n```typescript\n// Initialize command options (v3.3.0+)\nexport interface InitOptions {\n configLang?: SupportedLang\n aiOutputLang?: AiOutputLanguage | string\n force?: boolean\n skipBanner?: boolean\n skipPrompt?: boolean\n codeType?: CodeToolType | string // Support 'cc', 'cx' abbreviations\n // Non-interactive mode parameters\n configAction?: 'new' | 'backup' | 'merge' | 'docs-only' | 'skip'\n apiType?: 'auth_token' | 'api_key' | 'ccr_proxy' | 'skip'\n apiKey?: string // Used for both API key and auth token\n apiUrl?: string\n apiModel?: string // Primary API model\n apiFastModel?: string // Fast API model\n provider?: string // API provider preset (302ai, glm, minimax, kimi, custom)\n mcpServices?: string[] | string | boolean\n workflows?: string[] | string | boolean\n outputStyles?: string[] | string | boolean\n defaultOutputStyle?: string\n allLang?: string // Unified language parameter\n installCometixLine?: string | boolean // CCometixLine installation control\n // Multi-configuration parameters\n apiConfigs?: string // JSON string for multiple API configurations\n apiConfigsFile?: string // Path to JSON file with API configurations\n}\n\n// Update command options\nexport interface UpdateOptions {\n lang?: SupportedLang\n force?: boolean\n selectedWorkflows?: string[]\n}\n\n// CCR command options\nexport interface CcrOptions {\n lang?: SupportedLang\n}\n\n// Check updates options\nexport interface CheckUpdatesOptions {\n lang?: SupportedLang\n codeType?: CodeToolType | string\n}\n\n// Config switch options\nexport interface ConfigSwitchOptions {\n codeType?: CodeToolType | string\n list?: boolean\n}\n\n// Uninstall options\nexport interface UninstallOptions {\n mode?: 'complete' | 'custom' | 'interactive'\n items?: string\n lang?: SupportedLang\n}\n```\n\n### API Endpoints\n\n- `init(options: InitOptions)` - Execute complete initialization workflow with dual code tool support\n- `update(options: UpdateOptions)` - Update workflow templates and configurations\n- `showMainMenu()` - Display interactive main menu with all features\n- `ccr(options: CcrOptions)` - Configure Claude Code Router proxy settings\n- `executeCcusage(args: string[])` - Execute CCusage tool with specified arguments\n- `checkUpdates(options: CheckUpdatesOptions)` - Check for tool updates and perform upgrades\n- `configSwitch(target: string, options: ConfigSwitchOptions)` - Switch between API configurations\n- `uninstall(options: UninstallOptions)` - Uninstall ZCF with selective removal options\n\n### Menu System Interface\n\n```typescript\n// Menu feature functions\nexport interface MenuFeatures {\n fullInit: () => Promise<void>\n importWorkflow: () => Promise<void>\n configureApiOrCcr: () => Promise<void>\n configureMcp: () => Promise<void>\n configureAiMemory: () => Promise<void>\n // Tool integrations\n runCcr: () => Promise<void>\n runCcu: () => Promise<void>\n runCometix: () => Promise<void>\n // System features\n checkUpdates: () => Promise<void>\n changeLanguage: () => Promise<void>\n clearCache: () => Promise<void>\n}\n```\n\n## Key Dependencies and Configuration\n\n### Core Dependencies\n\n```typescript\n// Configuration and utilities\nimport { getTranslation } from '../i18n'\nimport { displayBannerWithInfo } from '../utils/banner'\nimport { backupExistingConfig, configureApi } from '../utils/config'\nimport { handleExitPromptError } from '../utils/error-handler'\nimport { installClaudeCode } from '../utils/installer'\n\n// Platform and validation\nimport { isTermux, isWindows } from '../utils/platform'\nimport { selectAndInstallWorkflows } from '../utils/workflow-installer'\nimport { readZcfConfig, updateZcfConfig } from '../utils/zcf-config'\n```\n\n### Configuration Integration\n\n- **I18n System**: Full internationalization support for all user interactions\n- **Platform Detection**: Windows/macOS/Linux/Termux compatibility handling\n- **Configuration Management**: Smart merging and backup of existing configurations\n- **Workflow System**: Integration with template installation and management\n- **Tool Integration**: CCR, CCusage, and Cometix tool management\n\n## Data Models\n\n### Command Flow Architecture\n\n```typescript\ninterface CommandFlow {\n init: {\n phases: ['banner', 'config', 'api', 'mcp', 'workflows', 'tools', 'completion']\n skipOptions: ['prompt', 'banner', 'config', 'api', 'mcp', 'workflows']\n rollbackCapability: true\n }\n menu: {\n structure: 'hierarchical'\n categories: ['claude-code', 'tools', 'system']\n persistence: 'language-aware'\n }\n update: {\n scope: ['workflows', 'templates', 'agents']\n conflictResolution: 'preserve-user-changes'\n }\n}\n```\n\n### Error Handling Strategy\n\n```typescript\ninterface ErrorHandling {\n gracefulDegradation: true\n userFriendlyMessages: true\n i18nSupport: true\n platformSpecificGuidance: true\n recoverySuggestions: true\n}\n```\n\n## Testing and Quality\n\n### Test Coverage\n\n- **Unit Tests**: Individual command function testing\n- **Integration Tests**: Full workflow execution testing\n- **Edge Case Tests**: Platform-specific and error condition testing\n- **Mock Testing**: External tool integration testing with comprehensive mocking\n\n### Test Files\n\n- `tests/commands/*.test.ts` - Core command functionality tests\n- `tests/commands/*.edge.test.ts` - Edge case and error condition tests\n- `tests/unit/commands/` - Isolated unit tests for command logic\n\n### Common Issues\n\n- **Platform Dependencies**: Windows path handling and Termux environment detection\n- **User Input Validation**: Handling of invalid selections and exit conditions\n- **External Tool Integration**: CCR, CCusage availability and version compatibility\n- **Configuration Conflicts**: Existing configuration preservation and merging\n\n## Related Files\n\n- `../utils/` - Core utility functions for configuration, installation, and platform support\n- `../i18n/` - Internationalization support for command interfaces\n- `../types/` - TypeScript interfaces for command options and configurations\n- `../config/workflows.ts` - Workflow configuration definitions\n- `../../templates/` - Template files used by commands\n\n## Change Log (Module-Specific)\n\n### Recent Updates (v3.3.0)\n\n- Added API provider preset system for simplified configuration (302.AI, GLM, MiniMax, Kimi)\n- Enhanced dual code tool support (Claude Code + Codex)\n- Improved config-switch command with multi-provider management\n- Added comprehensive uninstall command with selective removal\n- Enhanced non-interactive mode with --all-lang unified language parameter\n- Added CCometixLine installation control via --install-cometix-line parameter\n- Improved multi-configuration support with apiConfigs and apiConfigsFile parameters\n- Enhanced error handling with platform-specific guidance\n- Expanded menu system with tool integration features\n- Added intelligent IDE detection and auto-open functionality\n","templates/CLAUDE.md":"# Templates Module\n\n**Last Updated**: Sun Jul 12 00:25:00 CST 2026\n[Root](../CLAUDE.md) > **templates**\n\n## Module Responsibilities\n\nTemplate system module providing multilingual configuration templates, AI personality styles, and workflow skill definitions for both Claude Code and Codex environments. Supports Chinese (zh-CN) and English (en) locales with comprehensive workflow coverage.\n\n## Entry Points and Startup\n\n- **Main Template Directories**:\n - `claude-code/` - Claude Code specific templates\n - `codex/` - Codex specific templates\n - `common/` - Shared configuration templates\n - `skills/` - ZCF workflow skills (installed via `npx -y skills add`)\n\n## External Interfaces\n\n### Template Structure\n\n```\ntemplates/\n├── common/ # Shared templates (cross code-tool)\n│ └── output-styles/ # AI personality styles\n│ ├── en/\n│ └── zh-CN/\n├── skills/ # ZCF workflow skills (Claude Code skills format)\n│ ├── zh-CN/\n│ │ ├── workflow/SKILL.md\n│ │ ├── feat/SKILL.md\n│ │ ├── init-project/SKILL.md\n│ │ ├── git-commit/SKILL.md\n│ │ ├── git-rollback/SKILL.md\n│ │ ├── git-clean-branches/SKILL.md\n│ │ ├── git-worktree/SKILL.md\n│ │ └── bmad-init/SKILL.md\n│ └── en/\n│ └── ... (same skill set)\n├── claude-code/ # Claude Code templates\n│ ├── common/\n│ ├── zh-CN/\n│ └── en/\n└── codex/ # Codex templates\n ├── common/\n ├── zh-CN/\n └── en/\n```\n\n### Template Categories\n\n#### 1. Output Styles (AI Personalities)\n\n- **engineer-professional** - Professional engineering style\n- **nekomata-engineer** - Nekomata engineer personality\n- **laowang-engineer** - Laowang engineer personality\n- **ojousama-engineer** - Ojou-sama engineer personality\n- **rem-engineer** - Rem maid engineer personality\n- **default** - Default output style\n- **explanatory** - Explanatory style\n- **learning** - Learning-focused style\n\n#### 2. Workflow Skills\n\n##### Common Tools Workflow\n- **Skills**: `init-project`\n- **Agents**: `init-architect`, `get-current-datetime`\n- **Purpose**: Essential development tools and project initialization\n\n##### Planning Workflow (Plan)\n- **Skills**: `feat`, `workflow`\n- **Agents**: `planner`, `ui-ux-designer`\n- **Purpose**: Feature planning and UX design\n\n##### Six-Step Workflow\n- **Skills**: `zcf-update-docs`, `zcf-pr`, `zcf-release`\n- **Purpose**: Structured development process\n\n##### BMAD Workflow\n- **Skills**: Enterprise-level workflow skills (BMad uses its own command layout)\n- **Purpose**: Business model and architecture design\n\n##### Git Workflow\n- **Skills**: `git-commit`, `git-worktree`, `git-clean-branches`, `git-rollback`\n- **Purpose**: Version control management with conventional commits, worktree management, branch cleanup, and rollback operations\n\n## Key Dependencies and Configuration\n\n### Template Processing\n\n- **Language Support**: zh-CN and en locales\n- **Code Tool Support**: Claude Code and Codex\n- **Template Format**: Markdown-based configuration files (`SKILL.md` for workflow skills)\n- **Variable Substitution**: Dynamic content replacement\n\n### Configuration Integration\n\n- **Workflow Installer**: Integration with `src/utils/workflow-installer.ts`\n- **Skills Installer**: Integration with `src/utils/skills-installer.ts` (`npx -y skills add`)\n- **Language Detection**: Integration with `src/i18n/` system\n- **Platform Support**: Cross-platform path handling\n\n## Data Models\n\n### Template Organization\n\n```typescript\ninterface TemplateStructure {\n codeTool: 'claude-code' | 'codex'\n locale: 'zh-CN' | 'en'\n category: 'common' | 'output-styles' | 'skills'\n workflow?: {\n type: 'common' | 'plan' | 'sixStep' | 'bmad' | 'git'\n skills: string[]\n agents: string[]\n }\n}\n```\n\n### Output Style Configuration\n\n```typescript\ninterface OutputStyle {\n id: string\n name: { 'zh-CN': string, 'en': string }\n description: { 'zh-CN': string, 'en': string }\n template: string\n personality: string\n}\n```\n\n## Testing and Quality\n\n### Template Validation\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Coverage**: Template completeness and format validation\n- **Validation**: Markdown syntax and variable substitution\n\n### Quality Metrics\n\n- **Template Coverage**: 100% for both locales\n- **Code Tool Support**: Claude Code and Codex fully supported\n- **Workflow Coverage**: 5 major workflow categories\n- **Output Styles**: 7 AI personality styles\n\n## Common Issues\n\n- **Path Handling**: Cross-platform path compatibility\n- **Encoding**: UTF-8 encoding for multilingual content\n- **Template Variables**: Proper variable substitution\n- **Skills Installation**: Installed via skills CLI to `~/.agents/skills/` with symlinks in `~/.claude/skills/`\n\n## Related Files\n\n- `src/utils/workflow-installer.ts` - Template installation logic\n- `src/utils/skills-installer.ts` - Skills CLI wrapper\n- `src/config/workflows.ts` - Workflow configuration definitions\n- `src/i18n/` - Internationalization support\n- `tests/templates/` - Template validation tests\n\n## Change Log (Module-Specific)\n\n### Recent Updates\n\n- Migrated ZCF workflow templates from commands to skills under `templates/skills/{locale}/`\n- Skills installed via `npx -y skills add` with symlink mode for Claude Code\n- Consolidated output-styles/system-prompt templates to `templates/common/output-styles/`\n- Added Codex template support for dual code tool architecture\n- Enhanced template validation and testing coverage\n\n## FAQ\n\n### Q: How to add a new workflow skill?\n\n1. Create skill directory under `templates/skills/{locale}/{skill-name}/`\n2. Add `SKILL.md` with Claude Code skills frontmatter\n3. Update `src/config/workflows.ts` with new workflow definition\n4. Add translations in `src/i18n/locales/{locale}/workflow.ts`\n\n### Q: How to add a new output style?\n\n1. Create style file in `templates/common/output-styles/{locale}/`\n2. Define style configuration with name and description\n3. Add style to available options in configuration\n4. Test style rendering with sample content\n\n### Q: How to support a new language?\n\n1. Create new locale directory under `templates/skills/{new-locale}/`\n2. Copy existing skills and translate `SKILL.md` content\n3. Update i18n system to support new locale\n4. Add locale to supported languages list\n\n### Q: How to maintain template consistency?\n\n- Use template validation tests\n- Follow naming conventions\n- Maintain parallel structure across locales\n- Document template variables and usage\n","templates/skills/en/bmad-init/SKILL.md":"---\nname: bmad-init\ndescription: Initialize or update BMad-Method (V6) in your project\ndisable-model-invocation: true\n---\n\n# /bmad-init Command\n\nThis command initializes or updates BMad-Method (V6) in your project.\n\n## When this command is invoked:\n\n1. Check if `_bmad/` directory exists to determine if BMad V6 is already installed\n2. Check for legacy V4 installations (`.bmad-core` or `.bmad-method` directories)\n3. Fresh install executes: `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n4. Existing install executes: `npx bmad-method install --directory . --action quick-update --yes`\n5. Fix installer bug: rename `{output_folder}` to `_bmad-output` (Beta known issue)\n6. Automatically update `.gitignore` (remove V4 entries, add V6 entries)\n7. Display installation results and prompt user for next steps\n\n## Implementation\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// Legacy entries to clean from .gitignore\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug artifact\n]\n\n// V6 .gitignore entries\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// Fix installer bug: {output_folder} not resolved to _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output doesn't exist, simply rename\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (renamed)')\n } else {\n // _bmad-output already exists, merge subdirectories then delete\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ Moved ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ Removed redundant {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // Remove V4 legacy entries\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ Removing legacy entry: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // Add V6 entries\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ Adding new entry: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore is up to date, no changes needed')\n return\n }\n\n // Build new content\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // Ensure trailing newline, then add BMad section\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore ${exists ? 'updated' : 'created'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // Check for legacy V4 installation\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ Legacy BMad V4 installation detected:')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 core directory)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 method directory)')\n console.log('')\n console.log('📌 The V6 installer will handle legacy migration automatically. Follow the prompts during installation.')\n console.log(' Details: https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // Check if V6 is already installed\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // Build non-interactive install command\n let installCmd\n if (hasV6) {\n console.log('🔄 Existing BMad V6 installation detected, performing quick update...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 Initializing BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language English',\n '--document-output-language English',\n '--yes',\n ].join(' ')\n }\n\n // Execute installation\n try {\n console.log(`📋 Executing: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 installation/update complete!')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 IMPORTANT: Please restart your AI IDE to load BMad extensions')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // Fix {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 Checking for known installer issues...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ No fixes needed')\n } catch (err) {\n console.log(` ⚠️ Failed to fix {output_folder}: ${err.message}`)\n console.log(' Please manually rename {output_folder}/ to _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 Directory Structure:')\n console.log(' • _bmad/ — agents, workflows, tasks, and configuration')\n console.log(' • _bmad-output/ — generated artifact output directory')\n console.log('')\n\n // Automatically update .gitignore\n console.log('🔧 Updating .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ Failed to automatically update .gitignore, please manually add _bmad/ and _bmad-output/')\n }\n console.log('')\n console.log('🚀 Quick Start:')\n console.log(' 1. Restart your AI IDE')\n console.log(' 2. Run /bmad-help for guidance and next step suggestions')\n console.log(' 3. Type /bmad and use autocomplete to browse available commands')\n console.log('')\n console.log('💡 Common Workflows:')\n console.log(' • /bmad-help — Interactive help')\n console.log(' • /bmad-bmm-create-prd — Create Product Requirements Document')\n console.log(' • /bmad-bmm-create-architecture — Create Architecture Document')\n console.log(' • /bmad-bmm-create-epics-and-stories — Create Epics and User Stories')\n console.log(' • /bmad-bmm-sprint-planning — Initialize Sprint Planning')\n console.log(' • /bmad-bmm-dev-story — Implement User Story')\n\n // Legacy V4 IDE command cleanup reminder\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ Legacy V4 IDE commands detected, consider removing manually:')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' New V6 commands are installed under .claude/commands/bmad/')\n }\n }\n catch (error) {\n console.error('❌ Installation failed:', error.message)\n console.log('')\n console.log('🛠️ Manual Installation Guide:')\n console.log(' 1. Ensure Node.js 20+ is installed')\n console.log(' 2. Non-interactive install:')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes')\n console.log(' 3. Quick update existing installation:')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. Or interactive install:')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 Documentation:')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// Execute initialization\ninitBmad()\n```\n\n## Usage\n\nSimply type in Claude Code:\n\n```\n/bmad-init\n```\n\nThis command will:\n\n1. Detect current installation status (V6 / V4 legacy / not installed)\n2. Fresh install: non-interactively execute `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n3. Existing install: execute `npx bmad-method install --directory . --action quick-update --yes`\n4. Fix `{output_folder}` → `_bmad-output` installer bug\n5. Automatically update `.gitignore` (clean up legacy entries, add V6 entries)\n6. Provide next step suggestions\n","templates/skills/en/feat/SKILL.md":"---\nname: feat\ndescription: Add New Feature\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## Core Workflow\n\n### 1. Input Analysis and Type Determination\n\nWhen receiving user input, first perform type determination and clearly inform the user:\n\n**Determination Criteria:**\n\n- **Requirement Planning Type**: User proposes new feature requirements, project ideas, or needs to formulate plans\n\n- **Discussion Iteration Type**: User requests to continue discussion, modify, or refine existing planning\n\n- **Execution Implementation Type**: User confirms planning is complete and requests to start specific implementation work\n\n### 2. Classification Processing Mechanism\n\n#### A. Requirement Planning Processing\n\n**Trigger Condition**: Identified as functional requirement input\n\n**Execution Actions**:\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Store document in `./.claude/plan` directory, named in plan/xxx.md format\n\n- Include: objective definition, feature breakdown, implementation steps, acceptance criteria\n\n#### B. Discussion Iteration Processing\n\n**Trigger Condition**: User requests to continue discussion or modify planning\n\n**Execution Actions**:\n\n- Retrieve and analyze previously generated planning files\n\n- Identify user feedback and confirmation content\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Create a new document, for example, if the last one was plan/xxx.md, then this time it's plan/xxx-1.md, if the last one was plan/xxx-1.md, then this time it's plan/xxx-2.md, and so on\n\n- Reorganize pending implementation task priorities\n\n#### C. Execution Implementation Processing\n\n**Trigger Condition**: User confirms planning is complete and requests to start execution\n\n**Execution Actions**:\n\n- Start task execution in the order of planning documents\n\n- Perform task type identification before each subtask begins\n\n- **Frontend Task Special Processing**:\n\n- Check if available UI design exists\n\n- If no design solution exists, must use UI-UX-Designer Agent\n\n- Complete UI design before proceeding with development implementation\n\n### 3. Key Execution Principles\n\n#### Mandatory Response Requirements\n\n- **Must first state in every interaction**: \"I determine this operation type as: [specific type]\"\n\n- Type determination must be accurate and clearly communicated to users\n\n#### Task Execution Standards\n\n- Strictly execute according to documented planning\n\n- Must clarify task nature and dependencies before subtask startup\n\n- Frontend tasks must ensure UI design completeness\n\n#### State Management Mechanism\n\n- Maintain task completion status tracking\n\n- Timely update planning document status\n\n- Ensure user visibility of progress\n\n## Quality Assurance Points\n\n1. **Type Determination Accuracy**: Type identification at the beginning of each interaction must be accurate\n\n2. **Document Consistency**: Planning documents and actual execution remain synchronized\n\n3. **Dependency Management**: Pay special attention to UI design dependencies of frontend tasks\n\n4. **Transparent User Communication**: All judgments and actions must be clearly communicated to users\n","templates/skills/en/git-clean-branches/SKILL.md":"---\nname: git-clean-branches\ndescription: Safely find and clean up merged or stale Git branches with dry-run mode and custom base/protected branches support\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\nThis command **safely** identifies and cleans up **merged** or **stale** Git branches.\nRuns in **read-only preview (`--dry-run`)** mode by default, requiring explicit instructions to perform deletions.\n\n---\n\n## Usage\n\n```bash\n# [Safest] Preview branches to be cleaned without executing any deletions\n/git-cleanBranches --dry-run\n\n# Clean local branches merged to main and inactive for over 90 days (requires individual confirmation)\n/git-cleanBranches --stale 90\n\n# Clean local and remote branches merged to release/v2.1 (auto-confirm)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [Dangerous] Force delete an unmerged local branch\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`: Specify the base branch for cleanup (defaults to repository's `main`/`master`).\n- `--stale <days>`: Clean branches with no commits for specified days (disabled by default).\n- `--remote`: Also clean remote merged/stale branches.\n- `--dry-run`: **Default behavior**. Only list branches to be deleted without executing any operations.\n- `--yes`: Skip individual confirmations and delete all identified branches directly (suitable for CI/CD).\n- `--force`: Use `-D` to force delete local branches (even if unmerged).\n\n---\n\n## What This Command Does\n\n1. **Configuration and Safety Checks**\n - **Update Information**: Automatically executes `git fetch --all --prune` to ensure branch status is current.\n - **Read Protected Branches**: Reads the list of branches that should not be cleaned from Git config (see \"Configuration\" below).\n - **Determine Base**: Uses `--base` parameter or auto-detected `main`/`master` as comparison baseline.\n\n2. **Analysis and Identification (Find)**\n - **Merged Branches**: Find local (and remote if `--remote` is added) branches fully merged to `--base`.\n - **Stale Branches**: If `--stale <days>` is specified, find branches with last commit N days ago.\n - **Exclude Protected Branches**: Remove all configured protected branches from cleanup list.\n\n3. **Report and Preview (Report)**\n - Clearly list \"merged branches to be deleted\" and \"stale branches to be deleted\".\n - Without `--yes` parameter, **command ends here**, waiting for user confirmation to re-execute (without `--dry-run`).\n\n4. **Execute Cleanup (Execute)**\n - **Only executed without `--dry-run` and after user confirmation** (or with `--yes`).\n - Delete identified branches one by one, unless user chooses to skip in interactive confirmation.\n - Local: `git branch -d <branch>`; Remote: `git push origin --delete <branch>`.\n - If `--force` is specified, local deletion uses `git branch -D <branch>`.\n\n---\n\n## Configuration (Configure Once, Use Forever)\n\nTo prevent accidental deletion of important branches (e.g., `develop`, `release/*`), add protection rules to the repository's Git config. The command reads them automatically.\n\n```bash\n# Protect develop branch\ngit config --add branch.cleanup.protected develop\n\n# Protect all branches starting with release/ (wildcard)\ngit config --add branch.cleanup.protected 'release/*'\n\n# View all configured protected branches\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **Prioritize `--dry-run`**: Develop the habit of previewing before executing.\n- **Leverage `--base`**: When maintaining long-term `release` branches, use it to clean `feature` or `hotfix` branches merged to that release.\n- **Careful with `--force`**: Don't force delete unless you're 100% certain an unmerged branch is useless.\n- **Team Collaboration**: Notify the team channel before cleaning shared remote branches.\n- **Regular Runs**: Run monthly or quarterly to keep the repository clean.\n\n---\n\n## Why This Version Is Better\n\n- ✅ **Safer**: Default read-only preview with configurable protected branch list.\n- ✅ **More Flexible**: Supports custom base branches, perfectly fits `release` / `develop` workflows.\n- ✅ **More Compatible**: Avoids commands with inconsistent behavior across systems like `date -d`.\n- ✅ **More Intuitive**: Condenses complex 16-step checklist into a single command with safety options.\n- ✅ **Consistent Style**: Shares similar parameter design and documentation structure with `/commit` command.\n","templates/skills/en/git-commit/SKILL.md":"---\nname: git-commit\ndescription: Analyze changes with Git only and auto-generate conventional commit messages with optional emoji; suggests splitting commits when needed, runs local Git hooks by default (use --no-verify to skip)\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\nThis command works **without any package manager/build tools**, using only **Git** to:\n\n- Read changes (staged/unstaged)\n- Determine if changes should be **split into multiple commits**\n- Generate **Conventional Commits** style messages with optional emoji for each commit\n- Execute `git add` and `git commit` as needed (runs local Git hooks by default; use `--no-verify` to skip)\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`: Skip local Git hooks (`pre-commit`/`commit-msg` etc.).\n- `--all`: When staging area is empty, automatically `git add -A` to include all changes in the commit.\n- `--amend`: **Amend** the last commit without creating a new one (preserves author and timestamp unless local Git config specifies otherwise).\n- `--signoff`: Add `Signed-off-by` line (use when following DCO process).\n- `--emoji`: Include emoji prefix in commit message (omit for plain text).\n- `--scope <scope>`: Specify commit scope (e.g., `ui`, `docs`, `api`), written to message header.\n- `--type <type>`: Force commit type (e.g., `feat`, `fix`, `docs`), overrides automatic detection.\n\n> Note: If the framework doesn't support interactive confirmation, enable `confirm: true` in front-matter to avoid mistakes.\n\n---\n\n## What This Command Does\n\n1. **Repository/Branch Validation**\n - Check if in a Git repository using `git rev-parse --is-inside-work-tree`.\n - Read current branch/HEAD status; if in rebase/merge conflict state, prompt to resolve conflicts first.\n\n2. **Change Detection**\n - Get staged and unstaged changes using `git status --porcelain` and `git diff`.\n - If staged files = 0:\n - If `--all` is passed → Execute `git add -A`.\n - Otherwise prompt choice: continue analyzing unstaged changes for **suggestions**, or cancel to manually group staging.\n\n3. **Split Suggestions (Split Heuristics)**\n - Cluster by **concerns**, **file modes**, **change types** (e.g., source code vs docs/tests; different directories/packages; additions vs deletions).\n - If **multiple independent changesets** or large diff detected (e.g., > 300 lines / across multiple top-level directories), suggest splitting commits with pathspecs for each group (for subsequent `git add <paths>`).\n\n4. **Commit Message Generation (Conventional with Optional Emoji)**\n - Auto-infer `type` (`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert`...) and optional `scope`.\n - Generate message header: `[<emoji>] <type>(<scope>)?: <subject>` (first line ≤ 72 chars, imperative mood, emoji included only with `--emoji` flag).\n - Generate message body:\n - Must have a blank line after the subject.\n - Use list format, each item starts with `-`.\n - Each item **must use imperative verb-first sentences** (e.g., \"add…\", \"fix…\", \"update…\").\n - **Colon-separated formats are prohibited** (e.g., ~~\"Feature: description\"~~, ~~\"Impl: content\"~~).\n - Describe the motivation, implementation details, or impact scope (3 items or fewer recommended).\n - Generate message footer (if any):\n - Must have a blank line after the Body.\n - **BREAKING CHANGE**: If there are breaking changes, must include `BREAKING CHANGE: <description>`, or add exclamation mark after type (e.g., `feat!:`).\n - Other footers use git trailer format (e.g., `Closes #123`, `Refs: #456`, `Reviewed-by: Name`).\n - Select message language to match the predominant language in Git history. Inspect recent commit subjects (e.g., `git log -n 50 --pretty=%s`) to decide Chinese vs English; if unclear, fall back to the repository's primary locale or English.\n - Write draft to `.git/COMMIT_EDITMSG` for use with `git commit`.\n\n5. **Execute Commit**\n - Single commit scenario: `git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - Multiple commit scenario (if split accepted): Provide clear instructions for `git add <paths> && git commit ...` per group; execute sequentially if allowed.\n\n6. **Safe Rollback**\n - If mistakenly staged, use `git restore --staged <paths>` to unstage (command provides instructions, doesn't modify file contents).\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**: One commit does one thing, easier to trace and review.\n- **Group before committing**: Split by directory/module/feature.\n- **Clear subject**: First line ≤ 72 chars, imperative mood.\n- **Body with context**: Explain motivation, solution, and impact scope (colon-separated formats prohibited).\n- **Follow Conventional Commits**: `<type>(<scope>): <subject>`.\n\n---\n\n## Type to Emoji Mapping (When --emoji is Used)\n\n- ✨ `feat`: New feature\n- 🐛 `fix`: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)\n- 📝 `docs`: Documentation and comments\n- 🎨 `style`: Code style/formatting (no semantic changes)\n- ♻️ `refactor`: Refactoring (no new features, no bug fixes)\n- ⚡️ `perf`: Performance improvements\n- ✅ `test`: Add/fix tests, snapshots\n- 🔧 `chore`: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)\n- 👷 `ci`: CI/CD configuration and scripts\n- ⏪️ `revert`: Revert commits\n- 💥 `feat`: Breaking changes (explained in `BREAKING CHANGE:` section)\n\n> If `--type`/`--scope` is passed, it will **override** auto-detection.\n> Emoji is only included when `--emoji` flag is specified.\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **Different concerns**: Unrelated feature/module changes should be split.\n2. **Different types**: Don't mix `feat`, `fix`, `refactor` in the same commit.\n3. **File modes**: Source code vs docs/tests/configs should be grouped separately.\n4. **Size threshold**: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.\n5. **Revertability**: Ensure each commit can be independently reverted.\n\n---\n\n## Examples\n\n**Good (with --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (without --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (with Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (with BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ← (if your repo has hook errors)\n```\n\n---\n\n## Important Notes\n\n- **Git only**: No package manager/build commands (`pnpm`/`npm`/`yarn` etc.).\n- **Respects hooks**: Executes local Git hooks by default; use `--no-verify` to skip.\n- **No source code changes**: Command only reads/writes `.git/COMMIT_EDITMSG` and staging area; doesn't directly edit working directory files.\n- **Safety prompts**: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.\n- **Auditable and controllable**: If `confirm: true` is enabled, each actual `git add`/`git commit` step requires confirmation.\n","templates/skills/en/git-rollback/SKILL.md":"---\nname: git-rollback\ndescription: Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**Purpose**: Safely and visually rollback a specified branch to an older version.\nDefaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.\n\n---\n\n## Usage\n\n```bash\n# Pure interactive: list branches → select branch → list recent 20 versions → select target → choose reset or revert → confirm\n/git-rollback\n\n# Specify branch, other interactive\n/git-rollback --branch feature/calculator\n\n# Specify branch and target commit, execute with hard-reset in one go (dangerous)\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# Generate revert commit only (non-destructive rollback), preview\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| Option | Description |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| `--branch <branch>` | Branch to rollback; interactively selected if omitted. |\n| `--target <rev>` | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |\n| `--mode reset\\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default. |\n| `--depth <n>` | List recent n versions in interactive mode (default 20). |\n| `--dry-run` | **Enabled by default**, only preview commands to be executed. |\n| `--yes` | Skip all confirmations and execute directly, suitable for CI/CD scripts. |\n\n---\n\n## Interactive Flow\n\n1. **Sync remote** → `git fetch --all --prune`\n2. **List branches** → `git branch -a` (local + remote, filter protected branches)\n3. **Select branch** → User input or parameter\n4. **List versions** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **Select target** → User inputs commit hash / tag\n6. **Select mode** → `reset` or `revert`\n7. **Final confirmation** (unless `--yes`)\n8. **Execute rollback**\n - `reset`: `git switch <branch> && git reset --hard <target>`\n - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)\n\n---\n\n## Safety Guards\n\n- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.\n- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.\n- **--dry-run enabled by default**: Prevents accidental operations.\n- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.\n\n---\n\n## Use Case Examples\n\n| Scenario | Command Example |\n| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |\n| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| Research historical bugs, guide newcomers through branch history | `/git-rollback` (full interactive, dry-run) |\n\n---\n\n## Notes\n\n1. **reset vs revert**\n - **reset** changes history, requires force push and may affect other collaborators, use with caution.\n - **revert** is safer, generates new commits preserving history, but adds one more record.\n2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.\n3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.\n\n---\n","templates/skills/en/git-worktree/SKILL.md":"---\nname: git-worktree\ndescription: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\nManage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.\n\nExecute commands directly and provide concise results.\n\n---\n\n## Usage\n\n```bash\n# Basic operations\n/git-worktree add <path> # create new branch named <path> from main/master\n/git-worktree add <path> -b <branch> # create new branch with specified name\n/git-worktree add <path> -o # create and open directly in IDE\n/git-worktree list # show all worktree status\n/git-worktree remove <path> # remove specified worktree\n/git-worktree prune # clean invalid worktree references\n\n# Content migration\n/git-worktree migrate <target> --from <source> # migrate uncommitted content\n/git-worktree migrate <target> --stash # migrate stash content\n```\n\n### Options\n\n| Option | Description |\n| ------------------ | ------------------------------------------------------ |\n| `add [<path>]` | Add new worktree in `../.zcf/project-name/<path>` |\n| `migrate <target>` | Migrate content to specified worktree |\n| `list` | List all worktrees and their status |\n| `remove <path>` | Remove worktree at specified path |\n| `prune` | Clean invalid worktree references |\n| `-b <branch>` | Create new branch and checkout to worktree |\n| `-o, --open` | Open directly in IDE after creation (skip prompt) |\n| `--from <source>` | Specify migration source path (migrate only) |\n| `--stash` | Migrate current stash content (migrate only) |\n| `--track` | Set new branch to track corresponding remote branch |\n| `--guess-remote` | Auto guess remote branch for tracking |\n| `--detach` | Create detached HEAD worktree |\n| `--checkout` | Checkout immediately after creation (default behavior) |\n| `--lock` | Lock worktree after creation |\n\n---\n\n## What This Command Does\n\n1. **Environment Check**\n - Verify Git repository using `git rev-parse --is-inside-work-tree`\n - Detect whether in main repo or existing worktree for smart path calculation\n\n2. **Smart Path Management**\n - Auto-calculate project name from main repository path using worktree detection\n - Create worktrees in structured `../.zcf/project-name/<path>` directory\n - Handle both main repo and worktree execution contexts correctly\n\n```bash\n# Core path calculation logic for worktree detection\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # Check if in worktree\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # In worktree, derive main repo path from git-common-dir\n dirname \"$git_common_dir\"\n else\n # In main repository\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# Always use absolute path to prevent nesting issues\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.\n\n3. **Worktree Operations**\n - **add**: Create new worktree with smart branch/path defaults\n - **list**: Display all worktrees with branches and status\n - **remove**: Safely remove worktree and clean references\n - **prune**: Clean orphaned worktree records\n\n4. **Smart Defaults**\n - **Branch creation**: When no `-b` specified, create new branch using path name\n - **Base branch**: New branches created from main/master branch\n - **Path resolution**: Use branch name as path when unspecified\n - **IDE integration**: Auto-detect and prompt for IDE opening\n\n5. **Content Migration**\n - Migrate uncommitted changes between worktrees\n - Apply stash content to target worktree\n - Safety checks to prevent conflicts\n\n6. **Safety Features**\n - **Path conflict prevention**: Check for existing directories before creation\n - **Branch checkout validation**: Ensure branches aren't already in use\n - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree\n - **Auto-cleanup on removal**: Clean both directory and git references\n - **Clear status reporting**: Display worktree locations and branch status\n\n7. **Environment File Handling**\n - **Auto-detection**: Scan `.gitignore` for environment variable file patterns\n - **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`\n - **Exclusion logic**: Skip `.env.example` and other template files\n - **Permission preservation**: Maintain original file permissions and timestamps\n - **User feedback**: Provide clear status on copied environment files\n\n```bash\n# Environment file copying implementation\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # Check if .gitignore exists\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # Detect .env file\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ Copied .env\"\n ((copied_count++))\n fi\n \n # Detect .env.* pattern files (excluding .env.example)\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ Copied $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 Copied $copied_count environment file(s) from .gitignore\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE Integration\n\n- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **Smart prompting**: Ask to open in IDE after worktree creation\n- **Direct open**: Use `-o` flag to skip prompt and open immediately\n- **Custom configuration**: Configurable via git config\n\n### Content Migration System\n\n```bash\n# Migrate uncommitted changes\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# Migrate stash content\n/git-worktree migrate feature-ui --stash\n```\n\n**Migration Flow**:\n\n1. Verify source has uncommitted content\n2. Ensure target worktree is clean\n3. Show changes to be migrated\n4. Execute safe migration using git commands\n5. Confirm results and suggest next steps\n\n---\n\n## Examples\n\n```bash\n# Basic usage\n/git-worktree add feature-ui # create new branch 'feature-ui' from main/master\n/git-worktree add feature-ui -b my-feature # create new branch 'my-feature' with path 'feature-ui'\n/git-worktree add feature-ui -o # create and open in IDE directly\n\n# Content migration scenarios\n/git-worktree add feature-ui -b feature/new-ui # create new feature worktree\n/git-worktree migrate feature-ui --from main # migrate uncommitted changes\n/git-worktree migrate hotfix --stash # migrate stash content\n\n# Management operations\n/git-worktree list # view all worktrees\n/git-worktree remove feature-ui # remove unneeded worktree\n/git-worktree prune # clean invalid references\n```\n\n**Example Output**:\n\n```\n✅ Worktree created at ../.zcf/project-name/feature-ui\n✅ Copied .env\n✅ Copied .env.local\n📋 Copied 2 environment file(s) from .gitignore\n🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y\n🚀 Opening ../.zcf/project-name/feature-ui in VS Code...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # main project\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree management\n └── your-project/ # project worktrees\n ├── feature-ui/ # feature branch\n ├── hotfix/ # hotfix branch\n └── debug/ # debug worktree\n```\n\n---\n\n## Configuration\n\n### IDE Configuration\n\n- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim\n- Configurable via git config for custom IDEs\n- Auto-detection with priority-based selection\n\n### Custom IDE Setup\n\n```bash\n# Configure custom IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# Control auto-detection\ngit config worktree.ide.autodetect true # default\n```\n\n---\n\n## Notes\n\n- **Performance**: Worktrees share `.git` directory, saving disk space\n- **Safety**: Path conflict prevention and branch checkout validation\n- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits\n- **IDE requirement**: Command-line tools must be in PATH\n- **Cross-platform**: Supports Windows, macOS, Linux\n- **Environment files**: Automatically copies environment files listed in `.gitignore` to new worktrees\n- **File exclusions**: Template files like `.env.example` are preserved in main repo only\n\n---\n","templates/skills/en/init-project/SKILL.md":"---\nname: init-project\ndescription: Initialize project AI context, generate/update root-level and module-level CLAUDE.md indexes\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## Usage\n\n`/init-project <PROJECT_SUMMARY_OR_NAME>`\n\n## Objective\n\nInitialize project AI context using a mixed strategy of \"concise at root + detailed at module level\":\n\n- Generate/update `CLAUDE.md` at repository root (high-level vision, architecture overview, module index, global standards).\n- Generate/update local `CLAUDE.md` in identified module directories (interfaces, dependencies, entry points, tests, key files, etc.).\n- ✨ **For improved readability, automatically generate Mermaid structure diagrams in the root `CLAUDE.md` and add navigation breadcrumbs to each module `CLAUDE.md`**.\n\n## Orchestration Instructions\n\n**Step 1**: Call the `get-current-datetime` sub-agent to obtain the current timestamp.\n\n**Step 2**: Call the `init-architect` sub-agent once, with input:\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (timestamp from step 1)\n\n## Execution Strategy (Agent adapts automatically, no user parameters needed)\n\n- **Stage A: Repository Census (Lightweight)**\n Quickly count files and directories, identify module roots (package.json, pyproject.toml, go.mod, apps/_, packages/_, services/\\*, etc.).\n- **Stage B: Module Priority Scanning (Medium)**\n For each module, perform targeted reading and sampling of \"entry/interfaces/dependencies/tests/data models/quality tools\".\n- **Stage C: Deep Supplementation (As Needed)**\n If repository is small or module scale is small, expand reading scope; if large, perform batch supplemental scanning on high-risk/high-value paths.\n- **Coverage Measurement and Resumability**\n 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.\n\n## Security and Boundaries\n\n- Only read/write documentation and indexes, do not modify source code.\n- Ignore common generated artifacts and binary large files by default.\n- Print \"summary\" in main dialog, write full content to repository.\n\n## Output Requirements\n\n- Print \"Initialization Result Summary\" in main dialog, including:\n - Whether root-level `CLAUDE.md` was created/updated, major section overview.\n - Number of identified modules and their path list.\n - Generation/update status of each module's `CLAUDE.md`.\n - ✨ **Explicitly mention \"Generated Mermaid structure diagram\" and \"Added navigation breadcrumbs for N modules\"**.\n - Coverage and major gaps.\n - If not fully read: explain \"why stopped here\" and list **recommended next steps** (e.g., \"suggest priority supplemental scanning: packages/auth/src/controllers\").\n","templates/skills/en/workflow/SKILL.md":"---\nname: workflow\ndescription: 'Professional AI programming assistant with structured workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) for developers'\ndisable-model-invocation: true\n---\n\n# Workflow - Professional Development Assistant\n\nExecute structured development workflow with quality gates and MCP service integration.\n\n## Usage\n\n```bash\n/workflow <TASK_DESCRIPTION>\n```\n\n## Context\n\n- Task to develop: $ARGUMENTS\n- Structured 6-phase workflow with quality gates\n- Professional developer-focused interaction\n- MCP service integration for enhanced capabilities\n\n## Your Role\n\nYou are a professional AI programming assistant following a structured core workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) to assist users. Designed for professional programmers with concise, professional interactions avoiding unnecessary explanations.\n\n## Communication Guidelines\n\n1. Responses start with mode tag `[Mode: X]`, initially `[Mode: Research]`\n2. Core workflow strictly follows `Research -> Ideate -> Plan -> Execute -> Optimize -> Review` sequence, users can command jumps\n\n## Core Workflow Details\n\n### 1. `[Mode: Research]` - Requirement Understanding\n\n- Analyze and understand user requirements\n- Evaluate requirement completeness (0-10 score), actively request key information when below 7\n- Gather necessary context and constraints\n- Identify key objectives and success criteria\n\n### 2. `[Mode: Ideate]` - Solution Design\n\n- Provide at least two feasible solutions with evaluation (e.g., `Solution 1: Description`)\n- Compare pros/cons of each approach\n- Recommend optimal solution based on requirements\n\n### 3. `[Mode: Plan]` - Detailed Planning\n\n- Break down selected solution into detailed, ordered, executable step list\n- Include atomic operations: files, functions/classes, logic overview\n- Define expected results for each step\n- Use `Context7` for new library queries\n- Do not write complete code at this stage\n- Request user approval after completion\n\n### 4. `[Mode: Execute]` - Implementation\n\n- Store plan summary (with context and plan) in project root directory `.zcf/plan/current/task-name.md`\n- Must have user approval before execution\n- Strictly follow the plan for coding implementation\n- Request user feedback after key steps and completion\n\n### 5. `[Mode: Optimize]` - Code Optimization\n\n- Automatically enter this mode after `[Mode: Execute]` completion\n- Automatically check and analyze implemented code (only code generated in current conversation)\n- Focus on redundant, inefficient, garbage code\n- Provide specific optimization suggestions (with reasons and expected benefits)\n- Execute optimization after user confirmation\n\n### 6. `[Mode: Review]` - Quality Assessment\n\n- Evaluate execution results against the plan\n- Report issues and suggestions\n- Request user confirmation after completion\n\n## Timestamp Acquisition Rules\n\nDuring workflow execution, any scenario requiring current timestamp must obtain accurate time via bash command. Guessing or fabricating time is prohibited.\n\nBasic Commands:\n- Default format: `date +'%Y-%m-%d %H:%M:%S'`\n- Filename format: `date +'%Y-%m-%d_%H%M%S'`\n- Readable format: `date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO format: `date +'%Y-%m-%dT%H:%M:%S%z'`\n\nTypical Use Cases:\n- Updating timestamp fields in documents\n- Naming task plan documents during archiving (when moving from `.zcf/plan/current/` to `.zcf/plan/history/`)\n- Any other scenario requiring current time recording\n\n## Interactive Feedback & MCP Services\n\n### Interactive Feedback Rules\n\n1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, must request user confirmation\n2. When receiving user feedback, if feedback content is not empty, must request user confirmation again and adjust behavior based on feedback\n3. Only when user explicitly indicates \"end\" or \"no more interaction needed\" can stop requesting user confirmation, process is considered complete\n4. Unless receiving termination instructions, all steps must repeatedly request user confirmation\n5. Before completing tasks, must request user confirmation and ask for user feedback\n\n---\n\n## Execute Workflow\n\n**Task Description**: $ARGUMENTS\n\nStarting structured development workflow with quality gates...\n\n### 🔍 Phase 1: Research & Analysis\n\n[Mode: Research] - Understanding requirements and gathering context:\n\n#### Requirement Completeness Scoring (0-10 points)\n\nScoring Dimensions:\n\n- **Goal Clarity** (0-3 points): Are task objectives clear and specific, what problem to solve?\n- **Expected Results** (0-3 points): Are success criteria and deliverables clearly defined?\n- **Scope Boundaries** (0-2 points): Are task scope and boundaries clear?\n- **Constraints** (0-2 points): Are time, performance, business limits specified?\n\nNote: Technical stack, framework versions will be identified from project automatically, not included in scoring\n\n**Scoring Rules**:\n\n- 9-10 points: Requirements very complete, can proceed directly\n- 7-8 points: Requirements basically complete, suggest adding minor details\n- 5-6 points: Requirements have significant gaps, must supplement key information\n- 0-4 points: Requirements too vague, needs redescription\n\n**When score is below 7, proactively ask supplementary questions**:\n\n- Identify missing key information dimensions\n- Ask 1-2 specific questions for each missing dimension\n- Provide examples to help users understand needed information\n- Re-score after user supplements information\n\n**Scoring Example**:\n\n```\nUser Request: \"Help me optimize code\"\nScoring Analysis:\n- Goal Clarity: 0/3 points (doesn't specify what code or what problem)\n- Expected Results: 0/3 points (no success criteria or expected effect defined)\n- Scope Boundaries: 1/2 points (only knows code optimization, but scope unclear)\n- Constraints: 0/2 points (no performance metrics or time limits)\nTotal Score: 1/10 - Requires significant information\n\nQuestions to Ask:\n1. Which file or module's code do you want to optimize?\n2. What specific problem needs optimization?\n3. What effect do you expect after optimization (e.g., response time improvement, code reduction)?\n4. Are there specific performance metrics or time requirements?\n```\n\n**Common Supplementary Question Templates**:\n\n- Goal: \"What specific functionality/effect do you want?\" \"What's the current problem?\"\n- Results: \"How to determine task success?\" \"What's the expected output/effect?\"\n- Scope: \"Which specific files/modules to handle?\" \"What should be excluded?\"\n- Constraints: \"What are the time requirements?\" \"Any business limitations or performance requirements?\"\n\n**Auto-detected Project Information** (no need to ask):\n\n- Tech stack (from AGENTS.md, CLAUDE.md, package.json, requirements.txt, etc.)\n- Framework versions (from AGENTS.md, CLAUDE.md, config files)\n- Project structure (from file system)\n- Existing code conventions (from AGENTS.md, CLAUDE.md, config files and existing code)\n- Development commands (from AGENTS.md, CLAUDE.md, such as build, test, typecheck)\n\n#### Execution Steps\n\n- Analyze task requirements and constraints\n- Perform requirement completeness scoring (show specific scores)\n- Identify key objectives and success criteria\n- Gather necessary technical context\n- Use MCP services for additional information if needed\n\n### 💡 Phase 2: Solution Ideation\n\n[Mode: Ideate] - Designing solution approaches:\n\n- Generate multiple feasible solutions\n- Evaluate pros and cons of each approach\n- Provide detailed comparison and recommendation\n- Consider technical constraints and best practices\n- Request user approval before proceeding\n\n### 📋 Phase 3: Detailed Planning\n\n[Mode: Plan] - Creating execution roadmap:\n\n- Break down solution into atomic, executable steps\n- Define file structure, functions/classes, and logic overview\n- Specify expected results for each step\n- Query new libraries using Context7 if needed\n- Request user approval before proceeding\n\n### ⚡ Phase 4: Implementation\n\n[Mode: Execute] - Code development:\n\n- Store execution plan in project root directory `.zcf/plan/current/task-name.md`\n- Implement according to approved plan\n- Follow development best practices\n- Add usage methods before import statements (critical rule)\n- Request feedback at key milestones\n\n### 🚀 Phase 5: Code Optimization\n\n[Mode: Optimize] - Quality improvement:\n\n- Automatically analyze implemented code\n- Identify redundant, inefficient, or problematic code\n- Provide specific optimization recommendations\n- Execute improvements after user confirmation\n\n### ✅ Phase 6: Quality Review\n\n[Mode: Review] - Final assessment:\n\n- Compare results against original plan\n- Identify any remaining issues or improvements\n- Provide completion summary and recommendations\n- Request final user confirmation\n- After task completion, move plan file from `.zcf/plan/current/` to `.zcf/plan/history/` for archiving\n- Rename to `[Finish Time]task-name.md` during archiving for tracking, Finish Time format is `YYYY-MM-DD_HHMMSS`\n\n## Expected Output Structure\n\n```\nproject/ # Project root directory\n├── .zcf/\n│ └── plan/\n│ ├── current/ # Current ongoing tasks\n│ │ └── task-name.md # Execution plan and context\n│ └── history/ # Completed historical tasks\n│ └── [Finish Time]task-name.md # Archived task records\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**Begin execution with the provided task description and report progress after each phase completion.**\n","templates/skills/zh-CN/bmad-init/SKILL.md":"---\nname: bmad-init\ndescription: 在项目中初始化或更新 BMad-Method (V6)\ndisable-model-invocation: true\n---\n\n# /bmad-init 命令\n\n此命令在您的项目中初始化或更新 BMad-Method (V6)。\n\n## 当调用此命令时：\n\n1. 检查 `_bmad/` 目录是否存在，判断 BMad V6 是否已安装\n2. 检查是否存在旧版 V4 安装（`.bmad-core` 或 `.bmad-method` 目录）\n3. 新安装执行：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n4. 已安装则执行：`npx bmad-method install --directory . --action quick-update --yes`\n5. 修复安装器 bug：将 `{output_folder}` 重命名为 `_bmad-output`（Beta 已知问题）\n6. 自动更新 `.gitignore`（移除 V4 条目，添加 V6 条目）\n7. 显示安装结果并提示用户后续操作\n\n## 实现\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// 需要从 .gitignore 清理的旧条目\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug 产物\n]\n\n// V6 新版 .gitignore 条目\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// 修复安装器 bug: {output_folder} 未解析为 _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output 不存在，直接重命名\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (重命名)')\n } else {\n // _bmad-output 已存在，合并子目录后删除\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ 移动 ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ 已删除多余的 {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // 移除 V4 旧条目\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ 移除旧条目: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // 添加 V6 新条目\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ 添加新条目: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore 已是最新，无需更新')\n return\n }\n\n // 构建新内容\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // 确保末尾有换行，然后添加 BMad 区块\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore 已${exists ? '更新' : '创建'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // 检查旧版 V4 安装\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ 检测到旧版 BMad V4 安装：')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 核心目录)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 方法目录)')\n console.log('')\n console.log('📌 V6 安装器会自动处理旧版迁移，请在安装过程中按提示操作。')\n console.log(' 详情参考：https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // 检查 V6 是否已安装\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // 构建非交互式安装命令\n let installCmd\n if (hasV6) {\n console.log('🔄 检测到已有 BMad V6 安装，将执行快速更新...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 正在初始化 BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language Chinese',\n '--document-output-language Chinese',\n '--yes',\n ].join(' ')\n }\n\n // 执行安装\n try {\n console.log(`📋 执行: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 安装/更新完成！')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 重要提示：请重启 AI IDE 以加载 BMad 扩展')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // 修复 {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 检查安装器已知问题...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ 无需修复')\n } catch (err) {\n console.log(` ⚠️ 修复 {output_folder} 失败: ${err.message}`)\n console.log(' 请手动将 {output_folder}/ 重命名为 _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 目录结构：')\n console.log(' • _bmad/ — agents、workflows、tasks 和配置')\n console.log(' • _bmad-output/ — 生成的工件输出目录')\n console.log('')\n\n // 自动更新 .gitignore\n console.log('🔧 更新 .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ 自动更新 .gitignore 失败，请手动添加 _bmad/ 和 _bmad-output/')\n }\n console.log('')\n console.log('🚀 快速开始：')\n console.log(' 1. 重启 AI IDE')\n console.log(' 2. 运行 /bmad-help 获取引导和下一步建议')\n console.log(' 3. 输入 /bmad 并使用自动补全浏览可用命令')\n console.log('')\n console.log('💡 常用工作流：')\n console.log(' • /bmad-help — 交互式帮助')\n console.log(' • /bmad-bmm-create-prd — 创建产品需求文档')\n console.log(' • /bmad-bmm-create-architecture — 创建架构文档')\n console.log(' • /bmad-bmm-create-epics-and-stories — 创建史诗和用户故事')\n console.log(' • /bmad-bmm-sprint-planning — 初始化 Sprint 计划')\n console.log(' • /bmad-bmm-dev-story — 实现用户故事')\n\n // 清理旧版 V4 IDE 命令提醒\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ 检测到旧版 V4 IDE 命令，建议手动删除：')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' 新的 V6 命令已安装在 .claude/commands/bmad/ 下')\n }\n }\n catch (error) {\n console.error('❌ 安装失败：', error.message)\n console.log('')\n console.log('🛠️ 手动安装指南：')\n console.log(' 1. 确保已安装 Node.js 20+')\n console.log(' 2. 非交互式安装：')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes')\n console.log(' 3. 快速更新已有安装：')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. 或交互式安装：')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 详细文档：')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// 执行初始化\ninitBmad()\n```\n\n## 用法\n\n只需在 Claude Code 中键入：\n\n```\n/bmad-init\n```\n\n此命令将：\n\n1. 检测现有安装状态（V6 / V4 旧版 / 未安装）\n2. 新安装：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n3. 已安装：`npx bmad-method install --directory . --action quick-update --yes`\n4. 修复 `{output_folder}` → `_bmad-output` 安装器 bug\n5. 自动更新 `.gitignore`（清理旧条目，添加 V6 条目）\n6. 提供后续步骤建议\n","templates/skills/zh-CN/feat/SKILL.md":"---\nname: feat\ndescription: '用于新增功能开发的命令，支持完整的开发流程和工具集成'\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## 核心工作流程\n\n### 1. 输入分析与类型判断\n\n每次收到用户输入时，首先进行类型判断并明确告知用户：\n\n**判断标准：**\n\n- **需求规划类型**: 用户提出新功能需求、项目构想或需要制定计划\n\n- **讨论迭代类型**: 用户要求继续讨论、修改或完善已有规划\n\n- **执行实施类型**: 用户确认规划完成，要求开始具体实施工作\n\n### 2. 分类处理机制\n\n#### A. 需求规划处理\n\n**触发条件**: 识别为功能需求输入\n\n**执行动作**:\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 将文档存储至 `./.claude/plan` 目录，并以 plan/xxx.md 的格式命名\n\n- 包含：目标定义、功能分解、实施步骤、验收标准\n\n#### B. 讨论迭代处理\n\n**触发条件**: 用户要求继续讨论或修改规划\n\n**执行动作**:\n\n- 检索并分析上次生成的规划文件\n\n- 识别用户反馈和确认内容\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 建立一个新的文档，比如上一次是 plan/xxx.md，那么这次就是 plan/xxx-1.md，如果上一次是 plan/xxx-1.md，那么这次就是 plan/xxx-2.md，以此类推\n\n- 重新组织待实施任务优先级\n\n#### C. 执行实施处理\n\n**触发条件**: 用户确认规划完成，要求开始执行\n\n**执行动作**:\n\n- 按规划文档顺序启动任务执行\n\n- 每个子任务开始前进行任务类型识别\n\n- **前端任务特殊处理**:\n\n- 检查是否存在可用 UI 设计\n\n- 如无设计方案，must use UI-UX-Designer Agent\n\n- 完成 UI 设计后再进行开发实施\n\n### 3. 关键执行原则\n\n#### 强制响应要求\n\n- **每次交互必须首先说明**: \"我判断此次操作类型为：[具体类型]\"\n\n- 类型判断必须准确且明确传达给用户\n\n#### 任务执行规范\n\n- 严格按照文档化规划执行\n\n- 子任务启动前必须明确任务性质和依赖关系\n\n- 前端任务必须确保 UI 设计完整性\n\n#### 状态管理机制\n\n- 维护任务完成状态跟踪\n\n- 及时更新规划文档状态\n\n- 确保用户对进度的可见性\n\n## 质量保证要点\n\n1. **类型判断准确性**: 每次交互开始的类型识别必须准确\n\n2. **文档一致性**: 规划文档与实际执行保持同步\n\n3. **依赖关系管理**: 特别关注前端任务的 UI 设计依赖\n\n4. **用户沟通透明**: 所有判断和动作都要明确告知用户\n","templates/skills/zh-CN/git-clean-branches/SKILL.md":"---\nname: git-clean-branches\ndescription: 安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\n该命令**安全地**识别并清理**已合并**或**长期未更新 (stale)** 的 Git 分支。\n默认以**只读预览 (`--dry-run`)** 模式运行，需明确指令才会执行删除操作。\n\n---\n\n## Usage\n\n```bash\n# [最安全] 预览将要清理的分支，不执行任何删除\n/git-cleanBranches --dry-run\n\n# 清理已合并到 main 且超过 90 天未动的本地分支 (需逐一确认)\n/git-cleanBranches --stale 90\n\n# 清理已合并到 release/v2.1 的本地与远程分支 (自动确认)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [危险] 强制删除一个未合并的本地分支\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。\n- `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。\n- `--remote`：同时清理远程已合并/过期的分支。\n- `--dry-run`：**默认行为**。仅列出将要删除的分支，不执行任何操作。\n- `--yes`：跳过逐一确认的步骤，直接删除所有已识别的分支（适合 CI/CD）。\n- `--force`：使用 `-D` 强制删除本地分支（即使未合并）。\n\n---\n\n## What This Command Does\n\n1. **配置与安全预检**\n - **更新信息**：自动执行 `git fetch --all --prune`，确保分支状态最新。\n - **读取保护分支**：从 Git 配置读取不应被清理的分支列表（见下文“Configuration”）。\n - **确定基准**：使用 `--base` 参数或自动识别的 `main`/`master` 作为比较基准。\n\n2. **分析识别（Find）**\n - **已合并分支**：找出已完全合并到 `--base` 的本地（及远程，如加 `--remote`）分支。\n - **过期分支**：如指定 `--stale <days>`，找出最后一次提交在 N 天前的分支。\n - **排除保护分支**：从待清理列表中移除所有已配置的保护分支。\n\n3. **报告预览（Report）**\n - 清晰列出“将要删除的已合并分支”与“将要删除的过期分支”。\n - 若无 `--yes` 参数，**命令到此结束**，等待用户确认后再次执行（不带 `--dry-run`）。\n\n4. **执行清理（Execute）**\n - **仅在不带 `--dry-run` 且用户确认后**（或带 `--yes`）执行。\n - 逐一删除已识别的分支，除非用户在交互式确认中选择跳过。\n - 本地用 `git branch -d <branch>`；远程用 `git push origin --delete <branch>`。\n - 若指定 `--force`，本地删除会改用 `git branch -D <branch>`。\n\n---\n\n## Configuration (一次配置，永久生效)\n\n为防止误删重要分支（如 `develop`, `release/*`），请在仓库的 Git 配置中添加保护规则。命令会自动读取。\n\n```bash\n# 保护 develop 分支\ngit config --add branch.cleanup.protected develop\n\n# 保护所有 release/ 开头的分支 (通配符)\ngit config --add branch.cleanup.protected 'release/*'\n\n# 查看所有已配置的保护分支\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **优先 `--dry-run`**：养成先预览再执行的习惯。\n- **活用 `--base`**：维护长期 `release` 分支时，用它来清理已合并到该 release 的 `feature` 或 `hotfix` 分支。\n- **谨慎 `--force`**：除非你百分百确定某个未合并分支是无用功，否则不要强制删除。\n- **团队协作**：在清理共享的远程分支前，先在团队频道通知一声。\n- **定期运行**：每月或每季度运行一次，保持仓库清爽。\n\n---\n\n## Why This Version Is Better\n\n- ✅ **更安全**：默认只读预览，且有可配置的保护分支列表。\n- ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。\n- ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。\n- ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。\n- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。\n","templates/skills/zh-CN/git-commit/SKILL.md":"---\nname: git-commit\ndescription: 仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过）\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\n该命令在**不依赖任何包管理器/构建工具**的前提下，仅通过 **Git**：\n\n- 读取改动（staged/unstaged）\n- 判断是否需要**拆分为多次提交**\n- 为每个提交生成 **Conventional Commits** 风格的信息（可选 emoji）\n- 按需执行 `git add` 与 `git commit`（默认运行本地 Git 钩子；可 `--no-verify` 跳过）\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`：跳过本地 Git 钩子（`pre-commit`/`commit-msg` 等）。\n- `--all`：当暂存区为空时，自动 `git add -A` 将所有改动纳入本次提交。\n- `--amend`：在不创建新提交的情况下**修补**上一次提交（保持提交作者与时间，除非本地 Git 配置另有指定）。\n- `--signoff`：附加 `Signed-off-by` 行（遵循 DCO 流程时使用）。\n- `--emoji`：在提交信息中包含 emoji 前缀（省略则使用纯文本）。\n- `--scope <scope>`：指定提交作用域（如 `ui`、`docs`、`api`），写入消息头部。\n- `--type <type>`：强制提交类型（如 `feat`、`fix`、`docs` 等），覆盖自动判断。\n\n> 注：如框架不支持交互式确认，可在 front-matter 中开启 `confirm: true` 以避免误操作。\n\n---\n\n## What This Command Does\n\n1. **仓库/分支校验**\n - 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库。\n - 读取当前分支/HEAD 状态；如处于 rebase/merge 冲突状态，先提示处理冲突后再继续。\n\n2. **改动检测**\n - 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动。\n - 若已暂存文件为 0：\n - 若传入 `--all` → 执行 `git add -A`。\n - 否则提示你选择：继续仅分析未暂存改动并给出**建议**，或取消命令后手动分组暂存。\n\n3. **拆分建议（Split Heuristics）**\n - 按**关注点**、**文件模式**、**改动类型**聚类（示例：源代码 vs 文档、测试；不同目录/包；新增 vs 删除）。\n - 若检测到**多组独立变更**或 diff 规模过大（如 > 300 行 / 跨多个顶级目录），建议拆分提交，并给出每一组的 pathspec（便于后续执行 `git add <paths>`）。\n\n4. **提交信息生成（Conventional 规范，可选 Emoji）**\n - 自动推断 `type`（`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert` …）与可选 `scope`。\n - 生成消息头：`[<emoji>] <type>(<scope>)?: <subject>`（首行 ≤ 72 字符，祈使语气，仅在使用 `--emoji` 时包含 emoji）。\n - 生成消息体：\n - 必须在 subject 之后空一行。\n - 使用列表格式，每项以 `-` 开头。\n - 每项**必须使用动词开头的祈使句**（如 \"add…\"、\"fix…\"、\"update…\"）。\n - **禁止使用冒号分隔的格式**（如 ~~\"Feature: description\"~~、~~\"Impl: content\"~~）。\n - 说明变更的动机、实现要点或影响范围（3 项以内为宜）。\n - 生成消息脚注（如有）：\n - 必须在 Body 之后空一行。\n - **BREAKING CHANGE**：若存在破坏性变更，必须包含 `BREAKING CHANGE: <description>`，或在类型后添加感叹号（如 `feat!:`）。\n - 其它脚注采用 git trailer 格式（如 `Closes #123`、`Refs: #456`、`Reviewed-by: Name`）。\n - 根据 Git 历史提交的主要语言选择提交信息语言。优先检查最近提交主题（例如 `git log -n 50 --pretty=%s`）判断中文/英文；若无法判断，则回退到仓库主要语言或英文。\n - 将草稿写入 `.git/COMMIT_EDITMSG`，并用于 `git commit`。\n\n5. **执行提交**\n - 单提交场景：`git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - 多提交场景（如接受拆分建议）：按分组给出 `git add <paths> && git commit ...` 的明确指令；若允许执行则逐一完成。\n\n6. **安全回滚**\n - 如误暂存，可用 `git restore --staged <paths>` 撤回暂存（命令会给出指令，不修改文件内容）。\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**：一次提交只做一件事，便于回溯与审阅。\n- **先分组再提交**：按目录/模块/功能点拆分。\n- **清晰主题**：首行 ≤ 72 字符，祈使语气。\n- **正文含上下文**：说明动机、方案、影响范围（禁止冒号分隔格式）。\n- **遵循 Conventional Commits**：`<type>(<scope>): <subject>`。\n\n---\n\n## Type 与 Emoji 映射（使用 --emoji 时）\n\n- ✨ `feat`：新增功能\n- 🐛 `fix`：缺陷修复（含 🔥 删除代码/文件、🚑️ 紧急修复、👽️ 适配外部 API 变更、🔒️ 安全修复、🚨 解决告警、💚 修复 CI）\n- 📝 `docs`：文档与注释\n- 🎨 `style`：风格/格式（不改语义）\n- ♻️ `refactor`：重构（不新增功能、不修缺陷）\n- ⚡️ `perf`：性能优化\n- ✅ `test`：新增/修复测试、快照\n- 🔧 `chore`：构建/工具/杂务（合并分支、更新配置、发布标记、依赖 pin、.gitignore 等）\n- 👷 `ci`：CI/CD 配置与脚本\n- ⏪️ `revert`：回滚提交\n- 💥 `feat`：破坏性变更（`BREAKING CHANGE:` 段落中说明）\n\n> 若传入 `--type`/`--scope`，将**覆盖**自动推断。\n> 仅在指定 `--emoji` 标志时才会包含 emoji。\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **不同关注点**：互不相关的功能/模块改动应拆分。\n2. **不同类型**：不要将 `feat`、`fix`、`refactor` 混在同一提交。\n3. **文件模式**：源代码 vs 文档/测试/配置分组提交。\n4. **规模阈值**：超大 diff（示例：>300 行或跨多个顶级目录）建议拆分。\n5. **可回滚性**：确保每个提交可独立回退。\n\n---\n\n## Examples\n\n**Good (使用 --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (不使用 --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (包含 Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (包含 BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ←（如你的仓库有钩子报错）\n```\n\n---\n\n## Important Notes\n\n- **仅使用 Git**：不调用任何包管理器/构建命令（无 `pnpm`/`npm`/`yarn` 等）。\n- **尊重钩子**：默认执行本地 Git 钩子；使用 `--no-verify` 可跳过。\n- **不改源码内容**：命令只读写 `.git/COMMIT_EDITMSG` 与暂存区；不会直接编辑工作区文件。\n- **安全提示**：在 rebase/merge 冲突、detached HEAD 等状态下会先提示处理/确认再继续。\n- **可审可控**：如开启 `confirm: true`，每个实际 `git add`/`git commit` 步骤都会进行二次确认。\n","templates/skills/zh-CN/git-rollback/SKILL.md":"---\nname: git-rollback\ndescription: 交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**目的**：安全、可视地将指定分支回滚到旧版本。\n默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。\n\n---\n\n## Usage\n\n```bash\n# 纯交互：列出分支 → 选分支 → 列最近 20 个版本 → 选目标 → 选择 reset 或 revert → 二次确认\n/git-rollback\n\n# 指定分支，其他交互\n/git-rollback --branch feature/calculator\n\n# 指定分支与目标 commit，并用 hard‑reset 一键执行（危险）\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# 只想生成 revert 提交（非破坏式回滚），预览即可\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| 选项 | 说明 |\n| ---------------------- | ---------------------------------------------------------------------------------- |\n| `--branch <branch>` | 要回滚的分支；缺省时交互选择。 |\n| `--target <rev>` | 目标版本（commit Hash、Tag、reflog 引用都行）；缺省时交互选择近 `--depth` 条记录。 |\n| `--mode reset\\|revert` | `reset`：硬回滚历史；`revert`：生成反向提交保持历史完整。默认询问。 |\n| `--depth <n>` | 在交互模式下列出最近 n 个版本（默认 20）。 |\n| `--dry-run` | **默认开启**，只预览即将执行的命令。 |\n| `--yes` | 跳过所有确认直接执行，适合 CI/CD 脚本。 |\n\n---\n\n## 交互流程\n\n1. **同步远端** → `git fetch --all --prune`\n2. **列分支** → `git branch -a`（本地＋远端，过滤受保护分支）\n3. **选分支** → 用户输入或传参\n4. **列版本** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **选目标** → 用户输入 commit hash / tag\n6. **选模式** → `reset` 或 `revert`\n7. **最终确认** （除非 `--yes`）\n8. **执行回滚**\n - `reset`：`git switch <branch> && git reset --hard <target>`\n - `revert`：`git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **推送建议** → 提示是否 `git push --force-with-lease`（reset）或普通 `git push`（revert）\n\n---\n\n## 安全护栏\n\n- **备份**：执行前自动在 reflog 中记录当前 HEAD，可用 `git switch -c backup/<timestamp>` 恢复。\n- **保护分支**：如检测到 `main` / `master` / `production` 等受保护分支且开启 `reset` 模式，将要求额外确认。\n- **--dry-run 默认开启**：防止误操作。\n- **--force 禁止**：不提供 `--force`；如需强推，请手动输入 `git push --force-with-lease`。\n\n---\n\n## 适用场景示例\n\n| 场景 | 调用示例 |\n| ----------------------------------------------- | ---------------------------------------------------------------- |\n| 热修补丁上线后发现 bug，需要回到 Tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| 运维同事误推了 debug 日志提交，需要生成反向提交 | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| 调研历史 bug，引导新人浏览分支历史 | `/git-rollback` （全交互，dry‑run） |\n\n---\n\n## 注意\n\n1. **reset vs revert**\n - **reset** 会改变历史，需要强推并可能影响其他协作者，谨慎使用。\n - **revert** 更安全，生成新提交保留历史，但会增加一次记录。\n2. **嵌入式仓库** 常有大体积二进制文件；回滚前请确保 LFS/子模块状态一致。\n3. 若仓库启用了 CI 强制校验，回滚后可能自动触发流水线；确认管控策略以免误部署旧版本。\n\n---\n","templates/skills/zh-CN/git-worktree/SKILL.md":"---\nname: git-worktree\ndescription: 管理 Git worktree，在项目平级的 ../.zcf/项目名/ 目录下创建，支持智能默认、IDE 集成和内容迁移\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\n管理 Git worktree，支持智能默认、IDE 集成和内容迁移，使用结构化的 `../.zcf/项目名/` 路径。\n\n直接执行命令并提供简洁结果。\n\n---\n\n## Usage\n\n```bash\n# 基本操作\n/git-worktree add <path> # 从 main/master 创建名为 <path> 的新分支\n/git-worktree add <path> -b <branch> # 创建指定名称的新分支\n/git-worktree add <path> -o # 创建并直接用 IDE 打开\n/git-worktree list # 显示所有 worktree 状态\n/git-worktree remove <path> # 删除指定的 worktree\n/git-worktree prune # 清理无效 worktree 记录\n\n# 内容迁移\n/git-worktree migrate <target> --from <source> # 迁移未提交内容\n/git-worktree migrate <target> --stash # 迁移 stash 内容\n```\n\n### Options\n\n| 选项 | 说明 |\n| ------------------ | -------------------------------------------- |\n| `add [<path>]` | 在 `../.zcf/项目名/<path>` 添加新的 worktree |\n| `migrate <target>` | 迁移内容到指定 worktree |\n| `list` | 列出所有 worktree 及其状态 |\n| `remove <path>` | 删除指定路径的 worktree |\n| `prune` | 清理无效的 worktree 引用 |\n| `-b <branch>` | 创建新分支并检出到 worktree |\n| `-o, --open` | 创建成功后直接用 IDE 打开（跳过询问） |\n| `--from <source>` | 指定迁移源路径（migrate 专用） |\n| `--stash` | 迁移当前 stash 内容（migrate 专用） |\n| `--track` | 设置新分支跟踪对应的远程分支 |\n| `--guess-remote` | 自动猜测远程分支进行跟踪 |\n| `--detach` | 创建分离 HEAD 的 worktree |\n| `--checkout` | 创建后立即检出（默认行为） |\n| `--lock` | 创建后锁定 worktree |\n\n---\n\n## What This Command Does\n\n1. **环境检查**\n - 通过 `git rev-parse --is-inside-work-tree` 验证 Git 仓库\n - 检测是否在主仓库或现有 worktree 中，进行智能路径计算\n\n2. **智能路径管理**\n - 使用 worktree 检测自动从主仓库路径计算项目名\n - 在结构化的 `../.zcf/项目名/<path>` 目录创建 worktree\n - 正确处理主仓库和 worktree 执行上下文\n\n```bash\n# worktree 检测的核心路径计算逻辑\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # 检测是否在 worktree 中\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # 在 worktree 中，从 git-common-dir 推导主仓库路径\n dirname \"$git_common_dir\"\n else\n # 在主仓库中\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# 始终使用绝对路径防止嵌套问题\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**关键修复**: 在现有 worktree 内创建新 worktree 时，始终使用绝对路径以防止出现类似 `../.zcf/project/.zcf/project/path` 的路径嵌套问题。\n\n3. **Worktree 操作**\n - **add**: 使用智能分支/路径默认创建新 worktree\n - **list**: 显示所有 worktree 的分支和状态\n - **remove**: 安全删除 worktree 并清理引用\n - **prune**: 清理孤立的 worktree 记录\n\n4. **智能默认**\n - **分支创建**: 未指定 `-b` 时，使用路径名创建新分支\n - **基础分支**: 新分支从 main/master 分支创建\n - **路径解析**: 未指定路径时使用分支名作为路径\n - **IDE 集成**: 自动检测并提示 IDE 打开\n\n5. **内容迁移**\n - 在 worktree 之间迁移未提交改动\n - 将 stash 内容应用到目标 worktree\n - 安全检查防止冲突\n\n6. **安全特性**\n - **路径冲突防护**: 创建前检查目录是否已存在\n - **分支检出验证**: 确保分支未被其他地方使用\n - **绝对路径强制**: 防止在 worktree 内创建嵌套的 `.zcf` 目录\n - **删除时自动清理**: 同时清理目录和 git 引用\n - **清晰的状态报告**: 显示 worktree 位置和分支状态\n\n7. **环境文件处理**\n - **自动检测**: 扫描 `.gitignore` 文件中的环境变量文件模式\n - **智能复制**: 复制 `.gitignore` 中列出的 `.env` 和 `.env.*` 文件\n - **排除逻辑**: 跳过 `.env.example` 等模板文件\n - **权限保护**: 保持原始文件权限和时间戳\n - **用户反馈**: 提供已复制环境文件的清晰状态信息\n\n```bash\n# 环境文件复制实现\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # 检查 .gitignore 是否存在\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # 检测 .env 文件\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ 已复制 .env\"\n ((copied_count++))\n fi\n \n # 检测 .env.* 模式文件（排除 .env.example）\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ 已复制 $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 已从 .gitignore 复制 $copied_count 个环境文件\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE 集成\n\n- **自动检测**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **智能提示**: 创建 worktree 后询问是否在 IDE 中打开\n- **直接打开**: 使用 `-o` 标志跳过提示直接打开\n- **自定义配置**: 通过 git config 配置\n\n### 内容迁移系统\n\n```bash\n# 迁移未提交改动\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# 迁移 stash 内容\n/git-worktree migrate feature-ui --stash\n```\n\n**迁移流程**:\n\n1. 验证源有未提交内容\n2. 确保目标 worktree 干净\n3. 显示即将迁移的改动\n4. 使用 git 命令安全迁移\n5. 确认结果并建议后续步骤\n\n---\n\n## Examples\n\n```bash\n# 基本用法\n/git-worktree add feature-ui # 从 main/master 创建新分支 'feature-ui'\n/git-worktree add feature-ui -b my-feature # 创建新分支 'my-feature'，路径为 'feature-ui'\n/git-worktree add feature-ui -o # 创建并直接用 IDE 打开\n\n# 内容迁移场景\n/git-worktree add feature-ui -b feature/new-ui # 创建新功能 worktree\n/git-worktree migrate feature-ui --from main # 迁移未提交改动\n/git-worktree migrate hotfix --stash # 迁移 stash 内容\n\n# 管理操作\n/git-worktree list # 查看所有 worktree\n/git-worktree remove feature-ui # 删除不需要的 worktree\n/git-worktree prune # 清理无效引用\n```\n\n**示例输出**:\n\n```\n✅ Worktree created at ../.zcf/项目名/feature-ui\n✅ 已复制 .env\n✅ 已复制 .env.local\n📋 已从 .gitignore 复制 2 个环境文件\n🖥️ 是否在 IDE 中打开 ../.zcf/项目名/feature-ui？[y/n]: y\n🚀 正在用 VS Code 打开 ../.zcf/项目名/feature-ui...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # 主项目\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree 管理\n └── your-project/ # 项目 worktree\n ├── feature-ui/ # 功能分支\n ├── hotfix/ # 修复分支\n └── debug/ # 调试 worktree\n```\n\n---\n\n## Configuration\n\n### IDE 配置\n\n- 支持 VS Code、Cursor、WebStorm、Sublime Text、Vim\n- 通过 git config 配置自定义 IDE\n- 基于优先级的自动检测选择\n\n### 自定义 IDE 设置\n\n```bash\n# 配置自定义 IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# 控制自动检测\ngit config worktree.ide.autodetect true # 默认\n```\n\n---\n\n## Notes\n\n- **性能**: worktree 共享 `.git` 目录，节省磁盘空间\n- **安全**: 路径冲突防护和分支检出验证\n- **迁移**: 仅限未提交改动；已提交内容需使用 `git cherry-pick`\n- **IDE 要求**: 命令行工具必须在 PATH 中\n- **跨平台**: 支持 Windows、macOS、Linux\n- **环境文件**: 自动复制 `.gitignore` 中列出的环境文件到新 worktree\n- **文件排除**: 模板文件如 `.env.example` 仅保留在主仓库中\n\n---\n","templates/skills/zh-CN/init-project/SKILL.md":"---\nname: init-project\ndescription: 初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## 用法\n\n`/init-project <项目摘要或名称>`\n\n## 目标\n\n以\"根级简明 + 模块级详尽\"的混合策略初始化项目 AI 上下文：\n\n- 在仓库根生成/更新 `CLAUDE.md`（高层愿景、架构总览、模块索引、全局规范）。\n- 在识别的各模块目录生成/更新本地 `CLAUDE.md`（接口、依赖、入口、测试、关键文件等）。\n- ✨ **为了提升可读性，会在根 `CLAUDE.md` 中自动生成 Mermaid 结构图，并为每个模块 `CLAUDE.md` 添加导航面包屑**。\n\n## 编排说明\n\n**步骤 1**：调用 `get-current-datetime` 子智能体获取当前时间戳。\n\n**步骤 2**：调用一次 `init-architect` 子智能体，输入：\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (来自步骤1的时间戳)\n\n## 执行策略（由 Agent 自适应决定，不需要用户传参）\n\n- **阶段 A：全仓清点（轻量）**\n 快速统计文件与目录，识别模块根（package.json、pyproject.toml、go.mod、apps/_、packages/_、services/\\* 等）。\n- **阶段 B：模块优先扫描（中等）**\n 对每个模块做\"入口/接口/依赖/测试/数据模型/质量工具\"的定点读取与样本抽取。\n- **阶段 C：深度补捞（按需）**\n 若仓库较小或模块规模较小，则扩大读取面；若较大，则对高风险/高价值路径分批追加扫描。\n- **覆盖率度量与可续跑**\n 输出\"已扫描文件数 / 估算总文件数、已覆盖模块占比、被忽略/跳过原因\"，并列出\"建议下一步深挖的子路径\"。重复运行 `/init-project` 时按上次索引做**增量更新**与**断点续扫**。\n\n## 安全与边界\n\n- 只读/写文档与索引，不改源代码。\n- 默认忽略常见生成物与二进制大文件。\n- 结果在主对话打印\"摘要\"，全文写入仓库。\n\n## 输出要求\n\n- 在主对话中打印\"初始化结果摘要\"，包含：\n - 根级 `CLAUDE.md` 是否创建/更新、主要栏目概览。\n - 识别的模块数量及其路径列表。\n - 每个模块 `CLAUDE.md` 的生成/更新情况。\n - ✨ **明确提及\"已生成 Mermaid 结构图\"和\"已为 N 个模块添加导航面包屑\"**。\n - 覆盖率与主要缺口。\n - 若未读全：说明\"为何到此为止\"，并列出**推荐的下一步**（例如\"建议优先补扫：packages/auth/src/controllers\"）。\n","templates/skills/zh-CN/workflow/SKILL.md":"---\nname: workflow\ndescription: '专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），适用于专业开发者'\ndisable-model-invocation: true\n---\n\n# Workflow - 专业开发助手\n\n使用质量把关和 MCP 服务集成执行结构化开发工作流。\n\n## 使用方法\n\n```bash\n/workflow <任务描述>\n```\n\n## 上下文\n\n- 要开发的任务：$ARGUMENTS\n- 带质量把关的结构化 6 阶段工作流\n- 面向专业开发者的交互\n- MCP 服务集成以增强功能\n\n## 你的角色\n\n你是 IDE 的 AI 编程助手，遵循核心工作流（研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审）用中文协助用户，面向专业程序员，交互应简洁专业，避免不必要解释。\n\n[沟通守则]\n\n1. 响应以模式标签 `[模式：X]` 开始，初始为 `[模式：研究]`。\n2. 核心工作流严格按 `研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审` 顺序流转，用户可指令跳转。\n\n[核心工作流详解]\n\n1. `[模式：研究]`：理解需求并评估完整性（0-10 分），低于 7 分时主动要求补充关键信息。\n2. `[模式：构思]`：提供至少两种可行方案及评估（例如：`方案 1：描述`）。\n3. `[模式：计划]`：将选定方案细化为详尽、有序、可执行的步骤清单（含原子操作：文件、函数/类、逻辑概要；预期结果；新库用 `Context7` 查询）。不写完整代码。完成后请求用户批准。\n4. `[模式：执行]`：计划简要（含上下文和计划）存入当前项目根目录的`.zcf/plan/current/任务名.md`。必须用户批准方可执行。严格按计划编码执行。关键步骤后及完成时请求用户反馈。\n5. `[模式：优化]`：在 `[模式：执行]` 完成后，必须自动进行本模式 `[模式：优化]`，自动检查并分析本次任务已实现（仅本次对话产生的相关代码），在 `[模式：执行]` 下产生的相关代码。聚焦冗余、低效、垃圾代码，提出具体优化建议（含优化理由与预期收益），用户确认后执行相关优化功能。\n6. `[模式：评审]`：对照计划评估执行结果，报告问题与建议。完成后请求用户确认。\n\n[时间戳获取规则]\n\n在工作流执行过程中，任何需要当前时间戳的场景，必须通过 bash 命令获取准确时间，禁止猜测或编造。\n\n基本命令：\n- 默认格式：`date +'%Y-%m-%d %H:%M:%S'`\n- 文件名格式：`date +'%Y-%m-%d_%H%M%S'`\n- 可读格式：`date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO 格式：`date +'%Y-%m-%dT%H:%M:%S%z'`\n\n典型应用场景：\n- 更新文档中的时间戳字段\n- 任务计划文档归档时的命名（从 `.zcf/plan/current/` 移至 `.zcf/plan/history/` 时）\n- 其他任何需要记录当前时间的场合\n\n[主动反馈与 MCP 服务]\n\n# 主动反馈规则\n\n1. 在任何流程、任务、对话进行时，无论是询问、回复、或完成阶段性任务，皆必须请求用户确认。\n2. 每当收到用户反馈，若反馈内容非空，必须再次请求用户确认，并根据反馈内容调整行为。\n3. 仅当用户明确表示「结束」或「不再需要交互」时, 才可停止请求用户确认，流程才算结束。\n4. 除非收到结束指令，否则所有步骤都必须重复请求用户确认。\n5. 完成任务前，必须请求用户确认，并向用户询问反馈。\n\n---\n\n## 执行工作流\n\n**任务描述**：$ARGUMENTS\n\n正在启动带质量把关的结构化开发工作流...\n\n### 🔍 阶段 1：研究与分析\n\n[模式：研究] - 理解需求并收集上下文：\n\n#### 需求完整性评分（0-10 分）\n\n评分维度：\n\n- **目标明确性**（0-3 分）：任务目标是否清晰具体，要解决什么问题\n- **预期结果**（0-3 分）：成功标准和交付物是否明确定义\n- **边界范围**（0-2 分）：任务范围和边界是否清楚\n- **约束条件**（0-2 分）：时间、性能、业务限制等是否说明\n\n注：技术栈、框架版本等信息将从项目自动识别，不计入评分\n\n**评分规则**：\n\n- 9-10 分：需求非常完整，可直接进入下一阶段\n- 7-8 分：需求基本完整，建议补充个别细节\n- 5-6 分：需求有明显缺失，必须补充关键信息\n- 0-4 分：需求过于模糊，需要重新描述\n\n**当评分低于 7 分时，主动提出补充问题**：\n\n- 识别缺失的关键信息维度\n- 针对每个缺失维度提出 1-2 个具体问题\n- 提供示例帮助用户理解需要的信息类型\n- 等待用户补充后重新评分\n\n**评分示例**：\n\n```\n用户需求：\"帮我优化代码\"\n评分分析：\n- 目标明确性：0/3分（未说明优化什么代码、解决什么问题）\n- 预期结果：0/3分（未定义优化成功标准、期望达到什么效果）\n- 边界范围：1/2分（只知道是代码优化，但范围不明）\n- 约束条件：0/2分（无性能指标、时间限制说明）\n总分：1/10 - 需要大量补充信息\n\n需要补充的问题：\n1. 请问您要优化哪个文件或模块的代码？\n2. 当前存在什么具体问题需要优化？\n3. 期望优化后达到什么效果（如响应时间提升、代码量减少等）？\n4. 有具体的性能指标或时间要求吗？\n```\n\n**常用补充问题模板**：\n\n- 目标类：\"您希望实现什么具体功能/效果？\" \"当前存在什么具体问题？\"\n- 结果类：\"如何判断任务成功完成？\" \"期望的输出/效果是什么？\"\n- 范围类：\"需要处理哪些具体文件/模块？\" \"不需要包含什么？\"\n- 约束类：\"时间要求是怎样的？\" \"有什么业务限制或性能要求？\"\n\n**自动获取的项目信息**（不需要询问）：\n\n- 技术栈（从 AGENTS.md、CLAUDE.md、package.json、requirements.txt 等获取）\n- 框架版本（从 AGENTS.md、CLAUDE.md、配置文件获取）\n- 项目结构（从文件系统获取）\n- 现有代码规范（从 AGENTS.md、CLAUDE.md、配置文件和现有代码获取）\n- 开发命令（从 AGENTS.md、CLAUDE.md 获取，如构建、测试、类型检查等）\n\n#### 执行步骤\n\n- 分析任务需求和约束\n- 进行需求完整性评分（显示具体得分）\n- 识别关键目标和成功标准\n- 收集必要的技术上下文\n- 如需要，使用 MCP 服务获取额外信息\n\n### 💡 阶段 2：方案构思\n\n[模式：构思] - 设计解决方案：\n\n- 生成多个可行的解决方案\n- 评估每种方法的优缺点\n- 提供详细的比较和推荐\n- 考虑技术约束和最佳实践\n- 在继续之前请求用户批准\n\n### 📋 阶段 3：详细规划\n\n[模式：计划] - 创建执行路线图：\n\n- 将解决方案分解为原子的、可执行的步骤\n- 定义文件结构、函数/类和逻辑概述\n- 为每个步骤指定预期结果\n- 如需要，使用 Context7 查询新库\n- 在继续之前请求用户批准\n\n### ⚡ 阶段 4：实施\n\n[模式：执行] - 代码开发：\n\n- 在项目根目录 `.zcf/plan/current/任务名.md` 中存储执行计划\n- 根据批准的计划实施\n- 遵循开发最佳实践\n- 在导入语句之前添加使用方法（关键规则）\n- 在关键里程碑请求反馈\n\n### 🚀 阶段 5：代码优化\n\n[模式：优化] - 质量改进：\n\n- 自动分析已实现的代码\n- 识别冗余、低效或有问题的代码\n- 提供具体的优化建议\n- 在用户确认后执行改进\n\n### ✅ 阶段 6：质量审查\n\n[模式：评审] - 最终评估：\n\n- 将结果与原始计划进行比较\n- 识别任何剩余的问题或改进\n- 提供完成总结和建议\n- 请求最终用户确认\n- 任务完全结束后，将计划文件从 `.zcf/plan/current/` 移动到 `.zcf/plan/history/` 进行归档\n- 归档时重命名为 `[完成时间]任务名.md` 便于追踪，时间格式为 `YYYY-MM-DD_HHMMSS`\n\n## 预期输出结构\n\n```\nproject/ # 项目根目录\n├── .zcf/\n│ └── plan/\n│ ├── current/ # 当前进行中的任务\n│ │ └── 任务名.md # 执行计划和上下文\n│ └── history/ # 已完成的历史任务\n│ └── [完成时间]任务名.md # 归档的任务记录\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**使用提供的任务描述开始执行，并在每个阶段完成后报告进度。**\n","tests/CLAUDE.md":"# Tests Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n[Root](../CLAUDE.md) > **tests**\n\n## Module Responsibilities\n\nTest suite module providing comprehensive test coverage for the ZCF project, including unit tests, integration tests, edge tests, and template validation tests.\n\n## Entry Points and Startup\n\n- **Testing Framework**: Vitest\n- **Coverage Tool**: @vitest/coverage-v8\n- **Test UI**: @vitest/ui\n- **Main Test Directories**:\n - `tests/` - New test suites\n - `test/unit/` - Unit tests\n - `test/integration/` - Integration tests\n\n## External Interfaces\n\n### Test Architecture\n\n```\ntests/\n├── commands/ # Command layer tests\n│ ├── *.test.ts # Core command tests\n│ └── *.edge.test.ts # Command edge tests\n├── utils/ # Utility layer tests\n│ ├── ccr/ # CCR tool tests\n│ ├── cometix/ # Cometix tool tests\n│ └── tools/ # Third-party tool integration tests\n├── config/ # Configuration system tests\n├── i18n/ # Internationalization tests\n└── templates/ # Template validation tests\n\ntest/\n├── unit/ # Unit test suites\n│ ├── commands/ # Command unit tests\n│ ├── utils/ # Utility unit tests\n│ └── config/ # Configuration unit tests\n├── integration/ # Integration tests\n└── helpers/ # Test helper tools\n```\n\n### Test Tool Interface\n\n```typescript\n// Test helper functions\nexport function mockFileSystem(): void\nexport function mockUserInput(responses: string[]): void\nexport function mockPlatform(platform: 'windows' | 'macos' | 'linux'): void\nexport function mockCommandExecution(commands: Record<string, string>): void\n\n// Test validation tools\nexport function validateConfig(config: any): boolean\nexport function validateWorkflowInstallation(result: WorkflowInstallResult): boolean\n```\n\n## Key Dependencies and Configuration\n\n### Testing Framework Configuration\n\n- **Vitest**: Main testing framework supporting TypeScript and ESM\n- **Coverage**: V8 coverage reporting with 80%+ target\n- **UI**: Visual testing interface\n- **Mock System**: Comprehensive mocking system\n\n### Test Configuration Files\n\n- `vitest.config.ts` - Vitest main configuration\n- `test/helpers/` - Test helper tools\n- Mock strategies distributed across test files\n\n## Test Data Models\n\n### Test Layering Strategy\n\n#### 1. Unit Test Layer (`test/unit/`)\n\n- **Scope**: Individual function or class behavior\n- **Isolation**: Completely isolated test environment\n- **Mock**: All external dependencies\n\n#### 2. Integration Test Layer (`test/integration/`)\n\n- **Scope**: Multi-module interaction\n- **Dependencies**: Allow real module interaction\n- **Validation**: End-to-end functionality verification\n\n#### 3. Edge Test Layer (`*.edge.test.ts`)\n\n- **Scope**: Error conditions and boundary cases\n- **Coverage**: Exception handling and extreme inputs\n- **Validation**: Error recovery and graceful degradation\n\n#### 4. New Test Suite (`tests/`)\n\n- **Scope**: New features and refactoring tests\n- **Organization**: Organized by functional modules\n- **Standards**: Higher testing standards\n\n## Test Coverage Analysis\n\n### Command Layer Test Coverage\n\n#### ✅ Init Command Tests\n\n- **File**: `test/unit/commands/init.test.ts` (29 line configuration)\n- **Edge**: `init.edge.test.ts` - Error scenarios\n- **Skip Prompt**: `init-skip-prompt.test.ts` - Non-interactive mode\n- **Coverage**: High - Complete initialization flow\n\n#### ✅ Menu Command Tests\n\n- **File**: `test/unit/commands/menu.test.ts` (40 line configuration)\n- **Function**: Interactive menu logic validation\n- **Mock**: User input and menu navigation\n\n#### ✅ CCR Command Tests\n\n- **File**: `tests/commands/ccr.test.ts`, `ccr.edge.test.ts`\n- **Function**: Claude Code Router configuration\n- **Edge**: Installation failures and configuration errors\n\n#### ✅ CCU Command Tests\n\n- **File**: `tests/commands/ccu.test.ts`, `ccu.edge.test.ts`\n- **Function**: CCusage tool integration\n- **Edge**: Command execution failures\n\n#### ✅ Update Command Tests\n\n- **File**: `test/unit/commands/update.test.ts` (24 line configuration)\n- **Function**: Workflow update mechanism\n\n### Utility Layer Test Coverage\n\n#### ✅ Configuration Management Tests\n\n- **File**: `test/unit/utils/config.test.ts` (10 line reference)\n- **Function**: Configuration read/write, backup, merge\n- **Mock**: File system operations\n\n#### ✅ MCP Service Tests\n\n- **File**: `test/unit/utils/mcp.test.ts` (9 line reference)\n- **Function**: MCP service configuration and management\n- **Platform**: Windows special handling\n\n#### ✅ Platform Compatibility Tests\n\n- **File**: `test/unit/utils/platform.test.ts`\n- **Function**: Cross-platform detection and handling\n- **Mock**: Operating system environment\n\n#### ✅ Workflow Installation Tests\n\n- **File**: `test/unit/utils/workflow-installer.test.ts` (20 line configuration)\n- **Function**: Workflow installation and dependency resolution\n\n#### ✅ CCR Toolset Tests\n\n- **Directory**: `tests/utils/ccr/`\n- **Files**: `config.test.ts`, `installer.test.ts`, `presets.test.ts`\n- **Edge**: Corresponding `.edge.test.ts` files\n\n#### ✅ Cometix Toolset Tests\n\n- **Directory**: `tests/utils/cometix/`\n- **Files**: `installer.test.ts`, `menu.test.ts`, `commands.test.ts`\n- **Function**: CCometixLine statusbar tool\n\n### System-Level Test Coverage\n\n#### ✅ Internationalization Tests\n\n- **File**: `tests/i18n/locales/workflow.test.ts`\n- **Function**: Translation completeness and consistency verification\n\n#### ✅ Workflow Configuration Tests\n\n- **File**: `tests/config/workflows.test.ts`\n- **Edge**: `test/unit/config/workflows.edge.test.ts`\n- **Function**: Workflow configuration validation\n\n#### ✅ Template Validation Tests\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Function**: Chinese template completeness verification\n\n## Quality Metrics and Strategy\n\n### Coverage Targets\n\n- **Line Coverage**: 80%+ (configured in vitest.config.ts)\n- **Function Coverage**: 80%+\n- **Branch Coverage**: 80%+\n- **Statement Coverage**: 80%+\n\n### Mock Strategy\n\n#### ✅ File System Mock\n\n```typescript\n// Mock file operations\nvi.mock('node:fs', () => ({\n existsSync: vi.fn(),\n readFileSync: vi.fn(),\n writeFileSync: vi.fn()\n}))\n```\n\n#### ✅ Command Execution Mock\n\n```typescript\n// Mock external commands\nvi.mock('tinyexec', () => ({\n $: vi.fn()\n}))\n```\n\n#### ✅ User Input Mock\n\n```typescript\n// Mock interactive prompts\nvi.mock('inquirer', () => ({\n prompt: vi.fn()\n}))\n```\n\n#### ✅ Platform Detection Mock\n\n```typescript\n// Mock platform environment\nvi.mock('../utils/platform', () => ({\n getPlatform: vi.fn(),\n isWindows: vi.fn()\n}))\n```\n\n## Test Execution and Reporting\n\n### Test Commands\n\n```bash\n# Run all tests\npnpm test\n\n# Watch mode\npnpm test:watch\n\n# UI interface\npnpm test:ui\n\n# Coverage report\npnpm test:coverage\n\n# Single run\npnpm test:run\n```\n\n### Test Organization\n\n- **Grouped by Function**: Commands, utilities, configuration tested separately\n- **Layered Testing**: Unit, integration, edge three-layer coverage\n- **Platform Testing**: Cross-platform compatibility verification\n- **Regression Testing**: Prevent feature regression\n\n## FAQ\n\n### Q: How to add new tests?\n\n1. Determine test type (unit/integration/edge)\n2. Create test file in appropriate directory\n3. Use standard Mock strategy\n4. Ensure test covers all branches of new functionality\n\n### Q: How to handle async tests?\n\nUse `async/await` and Vitest's async test support, ensuring async operations complete before assertions.\n\n### Q: How to choose Mock strategy?\n\n- File system operations must be mocked\n- External command execution must be mocked\n- User interaction must be mocked\n- Platform detection can be mocked for multi-platform testing\n\n### Q: How to improve test coverage?\n\n1. Identify uncovered code branches\n2. Add boundary condition tests\n3. Increase error scenario tests\n4. Verify exception handling logic\n\n## Related File List\n\n### Core Test Suites\n\n#### Unit Tests (`test/unit/`)\n\n- `commands/` - Command layer unit tests (8 files)\n- `utils/` - Utility layer unit tests (25 files)\n- `config/` - Configuration system tests (3 files)\n- `cli-*.test.ts` - CLI system tests (3 files)\n\n#### New Test Suite (`tests/`)\n\n- `commands/` - Command tests (4 files)\n- `utils/ccr/` - CCR tool tests (6 files)\n- `utils/cometix/` - Cometix tests (3 files)\n- `utils/tools/` - Tool integration tests (1 file)\n- `config/` - Configuration tests (1 file)\n- `i18n/` - Internationalization tests (1 file)\n- `templates/` - Template tests (1 file)\n\n#### Integration Tests (`test/integration/`)\n\n- `statusline-config.test.ts` - Statusbar configuration integration\n- `test-helpers.ts` - Integration test helpers\n\n#### Test Helpers (`test/helpers/`)\n\n- `statusline-helpers.ts` - Statusbar test helpers\n\n### Statistics\n\n- **Total Test Files**: 60+ files\n- **Test Distribution**:\n - Unit tests: 80%\n - Integration tests: 10%\n - Edge tests: 10%\n- **Platform Coverage**: Windows/macOS/Linux/Termux\n\n## Changelog\n\n### 2025-08-20\n\n- **Module Documentation Created**: Completed comprehensive documentation of tests module\n- **Test Architecture Analysis**: Detailed analysis of 60+ test files' organizational structure\n- **Coverage Assessment**: Confirmed 80%+ high coverage target\n- **Mock Strategy Documentation**: Complete recording of test mocking strategies and best practices\n"},"files":{".claude/skills/zcf-add-sponsor/SKILL.md":"---\nname: zcf-add-sponsor\ndescription: Quickly add a new corporate sponsor to ZCF — sponsor list by default, with optional API preset and documentation ad placements\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(**), Edit(**), Exec(ls, cat, grep, rg, sed, awk, file, mv, pnpm, node, git)\n---\n\n# ZCF Add Sponsor — Quick Sponsor Onboarding\n\nQuickly onboard a new **corporate sponsor** across the ZCF project: README sponsor lists by default, with optional API provider preset and documentation ad placements.\n\n## Usage\n\n```bash\n/zcf-add-sponsor [--with-api] [--with-ad] [--name <name>] [--url <url>] [--id <provider-id>] [--logo <path>] [--badge <emoji>]\n```\n\n## Parameters\n\n### Mode flags\n\n- `--with-api` — Also append a new entry to `src/config/api-providers.ts` (`API_PROVIDER_PRESETS`)\n- `--with-ad` — Also insert ad cards into:\n - `README.md`, `README_zh-CN.md`, `README_ja-JP.md` (top `♥️ Sponsors` section, table card)\n - `docs/en/index.md`, `docs/zh-CN/index.md`, `docs/ja-JP/index.md` (top `♥️ Sponsor` section, table card)\n- *(no flag)* — Default: only add a single bullet entry to the **Our Sponsors → Corporate Sponsors** lists in the three READMEs\n\n### Sponsor info (prompt interactively if missing)\n\n- `--name <name>` — Display name (e.g. `FooAI`)\n- `--url <url>` — Affiliate/registration URL (used in every link)\n- `--id <provider-id>` — API provider id, kebab-case (only required with `--with-api`, e.g. `fooai`)\n- `--logo <path>` — Local logo path under `src/assets/` (only required with `--with-ad`, e.g. `./src/assets/fooai.png`)\n- `--badge <emoji>` — Trailing emoji badge for the list bullet (default: `🎁`)\n\n## Context\n\n- **Default scope**: Only the `Our Sponsors → Corporate Sponsors` bullet list in the three READMEs (zh-CN, en, ja-JP). `docs/*/index.md` does **not** contain a sponsor list — it only contains an ad section, handled by `--with-ad`.\n- **API preset format**: Match the existing `ApiProviderPreset` interface in `src/config/api-providers.ts`. Ask the user about `baseUrl`, `authType`, `wireApi`, `defaultModels`, and which code tools are supported (`claude-code`, `codex`, or both).\n- **Ad cards**: Mirror the existing AICodeMirror / Crazyrouter card layout exactly — `<table><tr><td width=\"180\"><a><img></a></td><td>...description...</td></tr></table>`, appended **after** the last existing sponsor card and **before** the next `##` heading.\n- **Image paths**:\n - In `README*.md` use relative path `./src/assets/<file>`\n - In `docs/*/index.md` use absolute GitHub raw URL `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/<file>`\n- **Trilingual descriptions**: Always generate three localized descriptions (zh-CN / en / ja-JP). Translate from the user-provided source description while preserving brand names, URLs, and discount numbers verbatim.\n\n## Your Role\n\nYou are a project documentation maintainer. Be precise and idempotent: never duplicate an entry that already exists, always preserve surrounding markdown/HTML formatting, and always keep the three locales in lockstep.\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Argument parsing & validation\n\n```text\nParse from $ARGUMENTS:\n WITH_API=false # toggled by --with-api\n WITH_AD=false # toggled by --with-ad\n NAME=\"\" # --name <name>\n URL=\"\" # --url <url>\n PROVIDER_ID=\"\" # --id <id>\n LOGO_PATH=\"\" # --logo <path>\n BADGE=\"🎁\" # --badge <emoji>, default 🎁\n\nValidation:\n - NAME and URL are always required → if missing, prompt user\n - If WITH_API: PROVIDER_ID required → if missing, prompt user.\n Provider id MUST be kebab-case, lowercase, unique across existing ids in src/config/api-providers.ts\n - If WITH_AD: LOGO_PATH required → if missing, prompt user.\n Verify the logo file exists at the given path (relative to repo root).\n If not, instruct the user to place the logo under src/assets/ first and abort.\n```\n\n### 2. Collect missing sponsor information (interactive)\n\nIf any required field is missing, ask the user **once** in a consolidated prompt covering:\n\n- Source description (1–3 sentences, in the user's preferred language)\n- Special offer / discount line (optional, e.g. \"Use code zcf for 10% off\")\n- For `--with-api`:\n - Supported code tools: `claude-code` / `codex` / both\n - Claude Code `baseUrl` and `authType` (`api_key` | `auth_token`)\n - Codex `baseUrl` (always `wireApi: 'responses'` per existing convention)\n - Optional `defaultModels` array (Claude Code) or `defaultModel` string (Codex)\n\nThen auto-translate the description into the other two languages, preserving brand names, URLs, and numbers.\n\n### 3. Idempotency check\n\nBefore any write, scan target files for the sponsor name or URL. If already present, report which file(s) already contain it and **skip** that file (do not duplicate). Continue with remaining files.\n\n```bash\nrg -l --fixed-strings \"<NAME>\" README.md README_zh-CN.md README_ja-JP.md docs/en/index.md docs/zh-CN/index.md docs/ja-JP/index.md src/config/api-providers.ts 2>/dev/null\n```\n\n### 4. Update sponsor lists (default — always runs)\n\nLocate the **Corporate Sponsors** bullet list in each README and append a new bullet **at the end** of that list (before the `【Individual Sponsors】` / `【个人赞助商】` / `【個人スポンサー】` heading):\n\n- `README.md` — under `【Corporate Sponsors】`:\n ```\n - [<NAME>](<URL>) (<EN_TAGLINE> <BADGE>)\n ```\n- `README_zh-CN.md` — under `【企业赞助商】`:\n ```\n - [<NAME>](<URL>) （<ZH_TAGLINE> <BADGE>）\n ```\n- `README_ja-JP.md` — under `【企業スポンサー】`:\n ```\n - [<NAME>](<URL>)（<JP_TAGLINE> <BADGE>）\n ```\n\n`<*_TAGLINE>` is a short 4–10 char positioning phrase derived from the source description (e.g. \"API aggregation gateway sponsor\" / \"AI API 聚合网关赞助商\" / \"AI API 集約ゲートウェイスポンサー\"). Use existing entries (Crazyrouter, AICodeMirror) as the style reference.\n\n### 5. Insert ad cards — only if `--with-ad`\n\nFor each of the six files below, locate the existing sponsor card table and **append a new `<tr>...</tr>` row to the same `<table>`** (or, if the existing structure uses sibling `<table>` blocks, append a new sibling table immediately after the last one). Match the exact layout of the most recent existing card.\n\n**Target files & image base path:**\n\n| File | Image path prefix |\n|------|-------------------|\n| `README.md` | `./src/assets/` |\n| `README_zh-CN.md` | `./src/assets/` |\n| `README_ja-JP.md` | `./src/assets/` |\n| `docs/en/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/zh-CN/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/ja-JP/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n\n**Card template (reference, fill brackets per locale):**\n\n```html\n<table>\n<tr>\n<td width=\"180\"><a href=\"<URL>\"><img src=\"<IMG_PREFIX><LOGO_FILENAME>\" alt=\"<NAME>\" width=\"150\"></a></td>\n<td><LOCALIZED_DESCRIPTION_INCLUDING_OFFER_AND_LINK></td>\n</tr>\n</table>\n```\n\n> **Important**: Insert **after** the last existing sponsor card and **before** the next `##` heading (typically `## 📺 ...` or `## ✨ ...`). Preserve surrounding blank lines.\n\n### 6. Add API provider preset — only if `--with-api`\n\nEdit `src/config/api-providers.ts`. Append a new object to the `API_PROVIDER_PRESETS` array, **before the closing `]`**, mirroring the style of existing entries:\n\n```ts\n {\n id: '<PROVIDER_ID>',\n name: '<NAME>',\n supportedCodeTools: [<'claude-code' and/or 'codex'>],\n claudeCode: {\n baseUrl: '<CC_BASE_URL>',\n authType: '<api_key|auth_token>',\n // defaultModels: [...], // include only if user provided\n },\n codex: { // include only if codex is supported\n baseUrl: '<CODEX_BASE_URL>',\n wireApi: 'responses',\n // defaultModel: '...', // include only if user provided\n },\n description: '<EN_DESCRIPTION>',\n },\n```\n\nThen run `pnpm typecheck` to confirm no type errors. If the project has corresponding tests for `getValidProviderIds()` or fixtures, surface them in the summary so the user can update tests if needed.\n\n### 7. Validation\n\n```text\n✓ List bullets present in all 3 READMEs (or skipped due to existing entry)\n✓ If --with-ad: card rows present in all 6 target files (or skipped)\n✓ If --with-api: new preset object syntactically valid; pnpm typecheck passes\n✓ No duplicate ids in API_PROVIDER_PRESETS\n✓ All URLs identical across files\n✓ Logo file exists at src/assets/<filename> when --with-ad is used\n```\n\n### 8. Summary report\n\nPrint a concise summary:\n\n```\n🎉 Sponsor \"<NAME>\" added\n\nSponsor list bullets:\n ✓ README.md\n ✓ README_zh-CN.md\n ✓ README_ja-JP.md\n\nAd cards (--with-ad): [yes/no]\n ✓/⊘ README.md / README_zh-CN.md / README_ja-JP.md\n ✓/⊘ docs/en/index.md / docs/zh-CN/index.md / docs/ja-JP/index.md\n\nAPI preset (--with-api): [yes/no]\n ✓/⊘ src/config/api-providers.ts (id: <PROVIDER_ID>)\n\nSkipped (already present): [list]\n\nNext steps:\n - Review changes with: git diff\n - If --with-api: consider adding tests in tests/ for the new provider\n - Commit with: /zcf-pr or your preferred flow\n```\n\n## Important Notes\n\n⚠️ **Critical Requirements**\n\n- **NEVER** modify any sponsor entries other than the ones being added\n- **NEVER** reorder existing sponsors\n- **ALWAYS** keep the three locale READMEs in sync (same bullet count, same URL, semantically equivalent text)\n- **ALWAYS** verify logo file existence under `src/assets/` before writing ad cards\n- **ALWAYS** validate the API preset by running `pnpm typecheck` after editing\n- **DO NOT** create commits or push — leave that to the user / `/zcf-pr`\n- **DO NOT** invent new section headings; reuse the exact existing ones (`【Corporate Sponsors】` / `【企业赞助商】` / `【企業スポンサー】`)\n\n📌 **Style Reference**\n\nWhen in doubt, copy the structure of the most recent existing sponsor entry (currently **Crazyrouter**) — it represents the canonical layout for both bullet entries and ad cards across all six target documents.\n\n🔍 **Idempotency**\n\nRe-running with the same `--name` and `--url` MUST be a no-op. Detection is by exact match on either NAME or URL within the relevant section.\n\n---\n\n**Now starting sponsor onboarding...**\n",".claude/skills/zcf-pr/SKILL.md":"---\nname: zcf-pr\ndescription: Create pull request based on current branch changes\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF PR - Create Pull Request from Current Branch\n\nCreate pull request based on current branch changes and generate standardized PR description.\n\n## Usage\n\n```bash\n/zcf-pr [--base <branch>] [--draft] [--title <title>]\n```\n\n## Parameters\n\n- `--base <branch>`: Target base branch (default: main)\n- `--draft`: Create as draft pull request\n- `--title <title>`: Custom PR title\n\n## Context\n\n- Analyze current branch changes since divergence from base branch\n- Generate PR description following project template\n- Support both English and Chinese descriptions\n- Auto-detect change types and categorize appropriately\n- Create PR using GitHub CLI with comprehensive template\n\n## Your Role\n\nYou are a professional pull request management assistant responsible for:\n\n1. Analyzing branch changes\n2. Categorizing change types automatically\n3. Generating standardized PR descriptions\n4. Creating pull requests with proper templates\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nBASE_BRANCH=\"main\"\nIS_DRAFT=false\nCUSTOM_TITLE=\"\"\n\n# Parse arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --base)\n BASE_BRANCH=\"$2\"\n shift 2\n ;;\n --draft)\n IS_DRAFT=true\n shift\n ;;\n --title)\n CUSTOM_TITLE=\"$2\"\n shift 2\n ;;\n *)\n echo \"❌ Unknown parameter: $1\"\n echo \"Usage: /zcf-pr [--base <branch>] [--draft] [--title <title>]\"\n echo \"Examples:\"\n echo \" /zcf-pr # Create PR to main\"\n echo \" /zcf-pr --base develop # Create PR to develop\"\n echo \" /zcf-pr --draft # Create draft PR\"\n echo \" /zcf-pr --title 'Bug Fix' # Custom title\"\n exit 1\n ;;\n esac\ndone\n\necho \"🚀 Creating PR from current branch to $BASE_BRANCH\"\nif [ \"$IS_DRAFT\" = true ]; then\n echo \"📝 Creating as draft PR\"\nfi\nif [ -n \"$CUSTOM_TITLE\" ]; then\n echo \"📝 Custom title: $CUSTOM_TITLE\"\nfi\n```\n\n### 2. Check Working Directory Status\n\n```bash\n# Check if we're in a git repository\nif [ ! -d \".git\" ]; then\n echo \"❌ Error: Not in a git repository\"\n exit 1\nfi\n\n# Get current branch\nCURRENT_BRANCH=$(git branch --show-current)\nif [ -z \"$CURRENT_BRANCH\" ]; then\n echo \"❌ Error: Could not determine current branch\"\n exit 1\nfi\n\n# Check if current branch is same as base branch\nif [ \"$CURRENT_BRANCH\" = \"$BASE_BRANCH\" ]; then\n echo \"❌ Error: Cannot create PR from $BASE_BRANCH to $BASE_BRANCH\"\n echo \"Please switch to a feature branch first\"\n exit 1\nfi\n\n# Check for uncommitted changes\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Warning: You have uncommitted changes\"\n echo \"Please commit your changes before creating a PR\"\n echo \"\"\n git status --short\n echo \"\"\n echo \"Run the following commands to commit your changes:\"\n echo \" git add .\"\n echo \" git commit -m 'Your commit message'\"\n exit 1\nfi\n\necho \"✅ Branch status OK: $CURRENT_BRANCH\"\n```\n\n### 3. Analyze Branch Changes\n\n```bash\n# Check if base branch exists\nif ! git rev-parse --verify \"$BASE_BRANCH\" >/dev/null 2>&1; then\n echo \"❌ Error: Base branch '$BASE_BRANCH' does not exist\"\n exit 1\nfi\n\n# Get commit history since divergence\necho \"📊 Analyzing changes from $BASE_BRANCH...\"\n\n# Find common ancestor\nMERGE_BASE=$(git merge-base \"$BASE_BRANCH\" HEAD)\nif [ -z \"$MERGE_BASE\" ]; then\n echo \"❌ Error: Could not find common ancestor with $BASE_BRANCH\"\n exit 1\nfi\n\n# Get commits since divergence\nCOMMITS=$(git log $MERGE_BASE..HEAD --oneline)\nCOMMIT_COUNT=$(echo \"$COMMITS\" | wc -l | tr -d ' ')\n\nif [ \"$COMMIT_COUNT\" -eq 0 ]; then\n echo \"❌ Error: No commits found since divergence from $BASE_BRANCH\"\n exit 1\nfi\n\necho \"📝 Found $COMMIT_COUNT commit(s):\"\necho \"$COMMITS\"\necho \"\"\n\n# Analyze file changes\necho \"📁 File change statistics:\"\ngit diff --stat $MERGE_BASE..HEAD\n\n# Get changed files\nCHANGED_FILES=$(git diff --name-only $MERGE_BASE..HEAD)\necho \"\"\necho \"📋 Changed files:\"\necho \"$CHANGED_FILES\"\n```\n\n### 4. Categorize Changes\n\n```bash\n# Analyze changes to determine type and scope\necho \"\"\necho \"🔍 Analyzing change categories...\"\n\nBUG_FIX=false\nNEW_FEATURE=false\nBREAKING_CHANGE=false\nDOCUMENTATION=false\nTESTS=false\n\n# Analyze commits for change indicators\nif echo \"$COMMITS\" | grep -E \"(fix|bug|error|issue|problem)\" >/dev/null; then\n BUG_FIX=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(feat|add|new|create|implement)\" >/dev/null; then\n NEW_FEATURE=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(break|change|remove|delete|major)\" >/dev/null; then\n BREAKING_CHANGE=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt|rst)$\" >/dev/null; then\n DOCUMENTATION=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"(test|spec)\\.\" >/dev/null; then\n TESTS=true\nfi\n\n# Show analysis results\necho \"📊 Change type analysis:\"\nif [ \"$BUG_FIX\" = true ]; then echo \" ✅ Bug fix detected\"; fi\nif [ \"$NEW_FEATURE\" = true ]; then echo \" ✅ New feature detected\"; fi\nif [ \"$BREAKING_CHANGE\" = true ]; then echo \" ✅ Breaking change detected\"; fi\nif [ \"$DOCUMENTATION\" = true ]; then echo \" ✅ Documentation update detected\"; fi\nif [ \"$TESTS\" = true ]; then echo \" ✅ Test updates detected\"; fi\n```\n\n### 5. Generate PR Title\n\n```bash\n# Generate PR title\nif [ -n \"$CUSTOM_TITLE\" ]; then\n PR_TITLE=\"$CUSTOM_TITLE\"\nelse\n # Auto-generate title from first commit\n FIRST_COMMIT=$(echo \"$COMMITS\" | tail -1)\n\n # Clean up commit message for PR title\n if echo \"$FIRST_COMMIT\" | grep -E \"^(feat|fix|docs|style|refactor|test|chore)(\\(.+\\))?: \" >/dev/null; then\n # Use conventional commit format\n PR_TITLE=$(echo \"$FIRST_COMMIT\" | sed 's/^[a-f0-9]\\+ //')\n else\n # Fallback to simple format\n PR_TITLE=\"$CURRENT_BRANCH\"\n fi\nfi\n\necho \"📝 PR Title: $PR_TITLE\"\n```\n\n### 6. Generate PR Description\n\n```bash\n# Generate comprehensive PR description\necho \"📋 Generating PR description...\"\n\n# Generate change summary\nCHANGE_SUMMARY=\"\"\nif [ \"$BUG_FIX\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Bug fixes and error handling improvements\\n\"\nfi\nif [ \"$NEW_FEATURE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- New features and functionality additions\\n\"\nfi\nif [ \"$BREAKING_CHANGE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Breaking changes requiring attention\\n\"\nfi\nif [ \"$DOCUMENTATION\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Documentation updates and improvements\\n\"\nfi\nif [ \"$TESTS\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Test coverage and quality improvements\\n\"\nfi\n\n# Generate file change summary\nFILE_CHANGES=\"\"\nfor file in $CHANGED_FILES; do\n FILE_CHANGES=\"${FILE_CHANGES}- \\`$file\\`\\n\"\ndone\n\n# Build complete PR description\nPR_DESCRIPTION=$(cat <<EOF\n## Description\n\nThis PR includes changes from branch \\`$CURRENT_BRANCH\\` with $COMMIT_COUNT commit(s) since divergence from \\`$BASE_BRANCH\\`.\n\n### Key Changes:\n\n$CHANGE_SUMMARY\n\n### Files Modified:\n\n$FILE_CHANGES\n\n## Type of Change\n\nEOF\n)\n\n# Add checkboxes based on analysis\nif [ \"$BUG_FIX\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Bug fix\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Bug fix\\n\"\nfi\n\nif [ \"$NEW_FEATURE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] New feature\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] New feature\\n\"\nfi\n\nif [ \"$BREAKING_CHANGE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Breaking change\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Breaking change\\n\"\nfi\n\nif [ \"$DOCUMENTATION\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Documentation update\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Documentation update\\n\"\nfi\n\n# Add testing section\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Testing\n\n- [x] Code changes tested\n- [x] No new warnings introduced\n- [x] Code follows style guidelines\"\n\nif [ \"$TESTS\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [x] Tests added/updated\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [ ] Tests added/updated\"\nfi\n\n# Add checklist\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Checklist\n\n- [x] Self-review completed\n- [x] Documentation updated (if applicable)\n- [x] No new warnings introduced\n- [x] Code follows project guidelines\n\n## Additional Information\n\n**Branch:** \\`$CURRENT_BRANCH\\` → \\`$BASE_BRANCH\\`\n**Commits:** $COMMIT_COUNT\n**Files Changed:** $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\n\n### Commit History:\n\n\\`\\`\\`\n$COMMITS\n\\`\\`\\`\n\n---\n🤖 Generated with /zcf-pr command\nEOF\n\necho \"✅ PR description generated\"\n```\n\n### 7. Push Branch and Create PR\n\n```bash\n# Check if branch exists on remote\nif ! git ls-remote --heads origin \"$CURRENT_BRANCH\" >/dev/null 2>&1; then\n echo \"📤 Pushing branch to remote...\"\n git push -u origin \"$CURRENT_BRANCH\"\nelse\n echo \"📤 Branch already exists on remote, ensuring it's up to date...\"\n git push origin \"$CURRENT_BRANCH\"\nfi\n\n# Create PR using gh CLI\necho \"📋 Creating pull request...\"\n\nPR_OPTIONS=\"--title '$PR_TITLE' --body '$PR_DESCRIPTION'\"\n\nif [ \"$IS_DRAFT\" = true ]; then\n PR_OPTIONS=\"$PR_OPTIONS --draft\"\nfi\n\n# Execute gh pr create command\nPR_URL=$(eval \"gh pr create --base $BASE_BRANCH $PR_OPTIONS\")\n\nif [ $? -eq 0 ]; then\n echo \"\"\n echo \"✅ Pull request created successfully!\"\n echo \"🔗 PR URL: $PR_URL\"\n echo \"\"\n echo \"📋 PR Details:\"\n echo \" Title: $PR_TITLE\"\n echo \" From: $CURRENT_BRANCH\"\n echo \" To: $BASE_BRANCH\"\n echo \" Commits: $COMMIT_COUNT\"\n echo \" Files: $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\"\n echo \"\"\n echo \"⚠️ Please review the PR and add any additional information as needed\"\nelse\n echo \"❌ Failed to create pull request\"\n echo \"Please check GitHub CLI authentication and permissions\"\n exit 1\nfi\n```\n\n## Complete Workflow Summary\n\n1. **Parameter Parsing**: Parse base branch, draft mode, and custom title options\n2. **Branch Validation**: Check current branch status and ensure it's different from base branch\n3. **Change Analysis**: Analyze commits and file changes since divergence from base branch\n4. **Categorization**: Auto-detect change types (bug fix, feature, breaking change, docs, tests)\n5. **Title Generation**: Generate appropriate PR title or use custom title\n6. **Description Generation**: Create comprehensive PR description following project template\n7. **Branch Push**: Ensure branch is available on remote repository\n8. **PR Creation**: Create pull request using GitHub CLI with all details\n\n## Important Notes\n\n⚠️ **Prerequisites**:\n\n- **GitHub CLI (`gh`)**: Must be installed and authenticated\n- **Clean working directory**: All changes must be committed before PR creation\n- **Remote branch**: Current branch must be pushed to remote repository\n- **Base branch**: Target branch must exist and be accessible\n\n### Best Practices:\n\n- Ensure commit messages follow conventional commit format\n- Test all changes before creating PR\n- Review auto-generated PR description for accuracy\n- Add any additional context specific to your changes\n- Check that all tests pass in CI/CD pipeline\n\n### Change Detection Logic:\n\nThe command automatically categorizes changes based on:\n\n- **Commit messages**: Keywords like \"feat\", \"fix\", \"break\", \"docs\", \"test\"\n- **File patterns**: `.md/.txt` for docs, `(test|spec)\\.` for tests\n- **File extensions**: TypeScript, JavaScript, JSON, etc.\n\n### Example Outputs:\n\n```bash\n# Standard PR to main\n/zcf-pr\n# → Creates PR: \"feat: add new feature\" with full description\n\n# PR to develop branch\n/zcf-pr --base develop\n# → Creates PR to develop branch instead of main\n\n# Draft PR\n/zcf-pr --draft\n# → Creates draft PR for initial review\n\n# Custom title\n/zcf-pr --title \"Critical bug fix for authentication\"\n# → Uses custom title instead of auto-generated one\n```\n\n---\n\n**Now creating pull request...**",".claude/skills/zcf-release/SKILL.md":"---\nname: zcf-release\ndescription: Automate version release and code commit using changeset\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF Release - Automated Release and Commit\n\nAutomate version release and code commit using changeset.\n\n## Usage\n\n```bash\n/zcf-release [-p|-mi|-ma|<version>]\n```\n\n## Parameters\n\n- `-p` or `--patch`: Patch version (default) - bug fixes, minor changes\n- `-mi` or `--minor`: Minor version - new features, backward compatible\n- `-ma` or `--major`: Major version - breaking changes, incompatible\n- `<version>`: Specific version number (e.g., 1.2.3, 2.0.0-beta.1) - directly use provided version\n\n## Context\n\n- Automatically analyze code changes and generate bilingual CHANGELOG\n- Use changeset for version management\n- Create release branch and pull request for protected main branch\n- Auto commit code changes (NO manual tags)\n- Support GitHub Actions auto publish to npm with automatic tagging after PR merge\n\n## Your Role\n\nYou are a professional release management assistant responsible for:\n\n1. Analyzing code changes\n2. Generating standardized CHANGELOG\n3. Executing version release process\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nVERSION_TYPE=\"patch\" # Default to patch version\nSPECIFIC_VERSION=\"\" # For user-specified exact version\n\n# Check if argument looks like a version number (matches semver pattern)\nif [[ \"$ARGUMENTS\" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+([.-].*)?$ ]]; then\n SPECIFIC_VERSION=\"$ARGUMENTS\"\n VERSION_TYPE=\"custom\"\n echo \"🚀 Preparing to release exact version: $SPECIFIC_VERSION\"\nelse\n case \"$ARGUMENTS\" in\n -p|--patch)\n VERSION_TYPE=\"patch\"\n ;;\n -mi|--minor)\n VERSION_TYPE=\"minor\"\n ;;\n -ma|--major)\n VERSION_TYPE=\"major\"\n ;;\n \"\")\n VERSION_TYPE=\"patch\"\n ;;\n *)\n echo \"❌ Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-release [-p|-mi|-ma|<version>]\"\n echo \"Examples:\"\n echo \" /zcf-release -p # Patch version bump\"\n echo \" /zcf-release -mi # Minor version bump\"\n echo \" /zcf-release -ma # Major version bump\"\n echo \" /zcf-release 1.2.3 # Exact version\"\n echo \" /zcf-release 2.0.0-beta.1 # Pre-release version\"\n exit 1\n ;;\n esac\n echo \"🚀 Preparing to release $VERSION_TYPE version\"\nfi\n```\n\n### 2. Check Working Directory Status\n\nCheck if the current working directory meets release conditions:\n\n```bash\n# Ensure in project root directory\nif [ ! -f \"package.json\" ]; then\n echo \"❌ Error: package.json not found, please run in project root\"\n exit 1\nfi\n\n# Check for uncommitted changes and handle automatically\nHAS_UNCOMMITTED=false\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Detected uncommitted changes:\"\n git status --short\n echo \"\"\n HAS_UNCOMMITTED=true\nfi\n\necho \"✅ Working directory status OK\"\n```\n\n### 3. Analyze Version Changes\n\nAnalyze all changes since last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"📊 No previous version tag found, analyzing all commits\"\n COMMITS=$(git log --oneline)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n COMMITS=$(git log $LAST_TAG..HEAD --oneline)\nfi\n\n# Show commit history\necho -e \"\\n📝 Changes:\"\necho \"$COMMITS\"\n\n# Analyze file changes\necho -e \"\\n📁 File change statistics:\"\nif [ -z \"$LAST_TAG\" ]; then\n git diff --stat\nelse\n git diff --stat $LAST_TAG..HEAD\nfi\n```\n\n### 4. Generate CHANGELOG Content\n\nBased on code change analysis, I will generate CHANGELOG following these standards:\n\n**Format Requirements**:\n\n1. English description first, Chinese description second\n2. No mixing Chinese and English on the same line\n3. Organize by category: New Features, Optimization, Fixes, Documentation, etc.\n4. Each entry should be concise and clear\n\n**Example Format**:\n\n```markdown\n## New Features\n\n- Add technical execution guidelines with command best practices\n- Support automated release command /zcf-release\n- Automatic quote handling for Windows paths\n\n## 新功能\n\n- 添加技术执行指南文档，提供命令执行最佳实践\n- 支持自动化发版命令 /zcf-release\n- Windows 路径自动加引号处理\n\n## Optimization\n\n- Prioritize ripgrep for better search performance\n- Improve template file organization\n\n## 优化\n\n- 优先使用 ripgrep 提升搜索性能\n- 改进模板文件组织结构\n\n## Fixes\n\n- Fix Windows path backslash escaping issue\n\n## 修复\n\n- 修复 Windows 路径反斜杠丢失问题\n```\n\n### 5. Create Changeset\n\nCreate changeset file based on analysis:\n\n```bash\n# Generate timestamp\nTIMESTAMP=$(date +%Y%m%d%H%M%S)\nCHANGESET_FILE=\".changeset/release-$TIMESTAMP.md\"\n\n# Create changeset file\necho \"📝 Creating changeset file...\"\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n # For specific version, use the exact version number\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $SPECIFIC_VERSION\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with exact version: $SPECIFIC_VERSION\"\nelse\n # For version type (patch/minor/major), use the type\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $VERSION_TYPE\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with version type: $VERSION_TYPE\"\nfi\n```\n\n### 6. Update Version Number\n\nUse changeset to update version number and CHANGELOG:\n\n```bash\necho \"🔄 Updating version number and CHANGELOG...\"\npnpm changeset version\n\n# Note: The changeset version command will automatically:\n# 1. Update package.json version\n# 2. Generate/update CHANGELOG.md\n# 3. DELETE the temporary changeset file in .changeset/ directory\n# No manual cleanup needed!\n\n# Get new version number\nNEW_VERSION=$(node -p \"require('./package.json').version\")\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n echo \"📦 New version set to: v$NEW_VERSION (specified: $SPECIFIC_VERSION)\"\nelse\n echo \"📦 New version: v$NEW_VERSION\"\nfi\n\n# Show CHANGELOG update\necho -e \"\\n📋 CHANGELOG has been updated, please review the content\"\necho \"✅ Temporary changeset file has been automatically deleted\"\n```\n\n### 7. Create Release Branch and Handle Commits\n\nCreate release branch first, then handle commits separately to avoid polluting main branch:\n\n````bash\necho \"🚀 Creating release branch...\"\n\n# Create and switch to release branch\nRELEASE_BRANCH=\"release/v$NEW_VERSION\"\ngit checkout -b \"$RELEASE_BRANCH\"\n\n# Handle uncommitted changes first (if any)\nif [ \"$HAS_UNCOMMITTED\" = true ]; then\n echo \"📝 Committing pre-release changes...\"\n \n # Stage only the uncommitted changes (exclude changeset modifications)\n git add .\n git reset HEAD package.json CHANGELOG.md 2>/dev/null || true\n \n # Check if there are still changes to commit after reset\n if ! git diff --quiet --staged; then\n # Analyze the staged changes to generate appropriate commit message\n echo \"🔍 Analyzing uncommitted changes...\"\n CHANGED_FILES=$(git diff --staged --name-only)\n \n # Generate commit message based on changed files\n COMMIT_TYPE=\"chore\"\n COMMIT_SCOPE=\"\"\n COMMIT_DESCRIPTION=\"pre-release changes\"\n \n # Analyze file patterns to determine commit type and scope\n if echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -i \"readme\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"readme\"\n COMMIT_DESCRIPTION=\"update README documentation\"\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.claude/\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"commands\"\n COMMIT_DESCRIPTION=\"update command documentation\"\n else\n COMMIT_TYPE=\"docs\"\n COMMIT_DESCRIPTION=\"update documentation\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.(ts|js|tsx|jsx)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -E \"test|spec\" >/dev/null; then\n COMMIT_TYPE=\"test\"\n COMMIT_DESCRIPTION=\"update tests\"\n else\n COMMIT_TYPE=\"feat\"\n COMMIT_DESCRIPTION=\"code changes\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.json$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep \"package\" >/dev/null; then\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update dependencies\"\n else\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update configuration\"\n fi\n fi\n \n # Build commit message\n if [ -n \"$COMMIT_SCOPE\" ]; then\n COMMIT_MSG=\"${COMMIT_TYPE}(${COMMIT_SCOPE}): ${COMMIT_DESCRIPTION}\"\n else\n COMMIT_MSG=\"${COMMIT_TYPE}: ${COMMIT_DESCRIPTION}\"\n fi\n \n # Add file list to commit body\n COMMIT_BODY=\"\"\n for file in $CHANGED_FILES; do\n COMMIT_BODY=\"${COMMIT_BODY}- Update ${file}\n\"\n done\n COMMIT_BODY=\"${COMMIT_BODY}\n🤖 Generated with [Claude Code](https://claude.ai/code)\n \n # Create the commit\n git commit -m \"${COMMIT_MSG}\n\n${COMMIT_BODY}\"\n \n echo \"✅ Pre-release changes committed: $COMMIT_MSG\"\n else\n echo \"ℹ️ No additional changes to commit after version update\"\n fi\nfi\n\necho \"💾 Committing release version changes...\"\n\n# Add version-related changes\ngit add package.json CHANGELOG.md\n\n# Create release version commit\ngit commit -m \"chore: release v$NEW_VERSION\n\n- Update version to $NEW_VERSION\n- Update CHANGELOG.md\n- Generated by /zcf-release command\"\n\n# Push release branch to remote and set upstream tracking\ngit push -u origin \"$RELEASE_BRANCH\"\n\n# If push fails due to conflicts, use force-with-lease to safely overwrite\n# git push --force-with-lease origin \"$RELEASE_BRANCH\"\n\n# Set upstream tracking if not set automatically\ngit branch --set-upstream-to=origin/$RELEASE_BRANCH $RELEASE_BRANCH\n\n### 8. Create Pull Request\n\n```bash\necho \"📋 Creating pull request...\"\n\n# Create pull request using gh CLI following the project's PR template\ngh pr create --title \"🚀 Release v$NEW_VERSION\" --body \"$(cat <<'EOF'\n## Description\n\nRelease version v$NEW_VERSION with automated version bump and CHANGELOG update.\n\nThis release includes important changes, please review CHANGELOG.md for details.\n\n## Type of Change\n\n- [x] New feature\n- [ ] Bug fix\n- [ ] Breaking change\n- [x] Documentation update\n\n## Testing\n\n- [x] Tests added/updated\n- [x] All tests pass\n- [x] Coverage maintained\n\n## Checklist\n\n- [x] Code follows style guidelines\n- [x] Self-review completed\n- [x] Documentation updated\n- [x] No new warnings introduced\n\n## Release Notes\n\n⚠️ **IMPORTANT**: After merge, GitHub Actions will automatically:\n- Create release tag\n- Publish to npm \n- Generate GitHub Release\n\n🤖 Generated by /zcf-release command\nEOF\n)\"\n\necho -e \"\\n✅ Release preparation complete!\"\necho \"📦 Version v$NEW_VERSION is ready\"\necho \"🔗 Pull request created successfully\"\necho \"\"\necho \"⚠️ IMPORTANT: Review and merge the PR to trigger the release\"\necho \"⚠️ Do NOT create or push tags manually!\"\necho \"🤖 After PR merge, GitHub Actions will automatically:\"\necho \" - Create the release tag\"\necho \" - Publish to npm\"\necho \" - Generate GitHub Release\"\necho \"👀 View release status: https://github.com/UfoMiao/zcf/actions\"\n````\n\n## Complete Workflow Summary\n\n1. **Preparation Phase**: Check parameters (version type or exact version), working directory status\n2. **Analysis Phase**: Analyze commit history and file changes\n3. **Generation Phase**: Create bilingual CHANGELOG\n4. **Execution Phase**: Update version (automatic bump or exact version)\n5. **Branch Creation Phase**: Create release branch BEFORE committing\n6. **Commit Phase**: Commit changes on release branch\n7. **PR Creation Phase**: Push release branch and create pull request\n8. **Review & Release Phase**: Manual PR review and merge, then GitHub Actions auto publish\n\n## Important Notes\n\n⚠️ **CRITICAL**: **NEVER create or push Git tags manually!** GitHub Actions will automatically:\n\n- Create the version tag after successful PR merge\n- Generate GitHub Release\n- Publish to npm registry\n\nManual tags will cause conflicts with the automated release process!\n\n### New Protected Branch Workflow:\n\n- 🛡️ **Main branch is protected**: Cannot push directly to main\n- 🌿 **Release branch created**: Automatic creation of `release/v{version}` branch\n- 📋 **Pull Request required**: All releases must go through PR review process\n- ✅ **Manual approval needed**: PR must be reviewed and merged manually\n- 🤖 **Auto-release after merge**: GitHub Actions triggers after PR merge\n\n### Additional Notes:\n\n- Ensure all code has been tested before running release command\n- CHANGELOG must follow bilingual format standards\n- When using version types (-p/-mi/-ma), choose the correct type for your changes\n- When providing exact version numbers, ensure they follow semantic versioning (e.g., 1.2.3, 2.0.0-beta.1)\n- Exact version numbers bypass automatic version determination - use carefully\n- Carefully review CHANGELOG content in the created PR before merging\n- **No manual cleanup needed**: `changeset version` automatically deletes temporary changeset files\n- The `.changeset/` directory should only contain config files, not temporary release files\n- **Requires `gh` CLI**: Ensure GitHub CLI is installed and authenticated for PR creation\n\n**Version Parameter Examples**:\n- `/zcf-release` or `/zcf-release -p` - Auto patch bump (2.9.11 → 2.9.12)\n- `/zcf-release -mi` - Auto minor bump (2.9.11 → 2.10.0) \n- `/zcf-release -ma` - Auto major bump (2.9.11 → 3.0.0)\n- `/zcf-release 1.5.0` - Exact version (→ 1.5.0)\n- `/zcf-release 3.0.0-alpha.1` - Pre-release version (→ 3.0.0-alpha.1)\n\n---\n\n**Now starting release process...**\n",".claude/skills/zcf-update-docs/SKILL.md":"---\nname: zcf-update-docs\ndescription: Automatically check code changes since last tag and update documentation in docs/ directory (en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, cat, grep, diff)\n---\n\n# ZCF Update Docs - Documentation Synchronization\n\nAutomatically check code changes since last tag and update documentation in `docs/` directory (multilingual: en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation.\n\n## Usage\n\n```bash\n/zcf-update-docs [--check-only]\n```\n\n## Parameters\n\n- `--check-only`: Only check for inconsistencies without making updates (dry run)\n\n## Context\n\n- Analyze all code changes since the last Git tag\n- Check if documentation needs updates in docs/ directory structure\n- Ensure CLI commands, features, and workflows documentation match actual code\n- Maintain multilingual documentation consistency across en, zh-CN, ja-JP\n- Update CLAUDE.md for development-related changes\n\n## Your Role\n\nYou are a professional documentation maintainer responsible for:\n\n1. Analyzing code changes and their impact on documentation\n2. Identifying documentation sections that need updates\n3. Ensuring documentation accuracy and consistency\n4. Maintaining multilingual synchronization\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nCHECK_ONLY=false # Default to update mode\n\ncase \"$ARGUMENTS\" in\n --check-only)\n CHECK_ONLY=true\n echo \"📋 Running in check-only mode (no files will be modified)\"\n ;;\n \"\")\n CHECK_ONLY=false\n echo \"✏️ Running in update mode\"\n ;;\n *)\n echo \"Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-update-docs [--check-only]\"\n exit 1\n ;;\nesac\n```\n\n### 2. Get Changes Since Last Tag\n\nAnalyze all changes since the last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"⚠️ No previous version tag found, analyzing all files\"\n FILES_CHANGED=$(git ls-files)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n FILES_CHANGED=$(git diff --name-only $LAST_TAG..HEAD)\nfi\n\n# Categorize changed files\necho -e \"\\n📁 Analyzing changed files...\"\n```\n\n### 3. Identify Documentation Update Areas\n\nBased on file changes, determine which documentation files in `docs/` need updates:\n\n**Code Changes → Documentation Mapping:**\n\n1. **CLI Commands** (`src/commands/*.ts`) → `docs/{lang}/cli/`\n - `src/commands/init.ts` → `cli/init.md` - Installation and initialization\n - `src/commands/menu.ts` → `cli/menu.md` - Interactive menu system\n - `src/commands/update.ts` → `cli/update.md` - Update workflows\n - `src/commands/ccr.ts` → `cli/ccr.md` - CCR proxy management\n - `src/commands/ccu.ts` → `cli/ccu.md` - Usage analysis\n - `src/commands/uninstall.ts` → `cli/uninstall.md` - Uninstallation\n - `src/commands/config-switch.ts` → `cli/config-switch.md` - Config switching\n - `src/commands/check-updates.ts` → `cli/check-updates.md` - Version check\n\n2. **Features** → `docs/{lang}/features/`\n - `src/utils/installer.ts`, `src/utils/claude-config.ts` → `features/claude-code.md`\n - `src/utils/code-tools/codex*` → `features/codex.md`\n - `src/config/workflows.ts` → `features/workflows.md`\n - `src/config/mcp-services.ts` → `features/mcp.md`\n - `src/utils/ccr/` → `features/ccr.md`\n - `src/utils/cometix/` → `features/cometix.md`\n - `src/utils/config.ts` → `features/multi-config.md`\n\n3. **Workflows** (`src/config/workflows.ts`, `templates/*/workflow/`) → `docs/{lang}/workflows/`\n - Workflow definitions → `workflows/index.md`\n - Specific workflow templates → `workflows/{workflow-name}.md`\n\n4. **Advanced Configuration** → `docs/{lang}/advanced/`\n - `src/types/config.ts`, `src/utils/config.ts` → `advanced/configuration.md`\n - `src/config/api-providers.ts` → `advanced/api-providers.md`\n - `templates/` → `advanced/templates.md`\n - `src/i18n/` → `advanced/i18n.md`\n\n5. **Getting Started** → `docs/{lang}/getting-started/`\n - `src/commands/init.ts`, `src/utils/installer.ts` → `getting-started/installation.md`\n - General introduction → `getting-started/index.md`\n\n6. **Development** → `docs/{lang}/development/` and `CLAUDE.md`\n - Architecture changes → `development/architecture.md` + `CLAUDE.md`\n - Testing changes → `development/testing.md` + `CLAUDE.md`\n - Contributing guidelines → `development/contributing.md`\n - Package.json scripts → `CLAUDE.md`\n\n### 4. Check Current Documentation\n\nRead and analyze current documentation structure:\n\n```bash\n# Check if documentation directories exist\nDOCS_LANGS=(\"en\" \"zh-CN\" \"ja-JP\")\nDOCS_CATEGORIES=(\n \"getting-started\"\n \"cli\"\n \"features\"\n \"workflows\"\n \"advanced\"\n \"best-practices\"\n \"development\"\n)\n\necho \"📁 Checking documentation structure...\"\n\nfor LANG in \"${DOCS_LANGS[@]}\"; do\n if [ ! -d \"docs/$LANG\" ]; then\n echo \"❌ Warning: docs/$LANG directory not found\"\n else\n echo \"✅ Found: docs/$LANG/\"\n for CATEGORY in \"${DOCS_CATEGORIES[@]}\"; do\n if [ ! -d \"docs/$LANG/$CATEGORY\" ]; then\n echo \" ⚠️ Missing category: $CATEGORY\"\n else\n echo \" ✅ Category: $CATEGORY\"\n fi\n done\n fi\ndone\n\n# Check CLAUDE.md\nif [ ! -f \"CLAUDE.md\" ]; then\n echo \"❌ Warning: CLAUDE.md not found\"\nelse\n echo \"✅ Found: CLAUDE.md\"\nfi\n```\n\n### 5. Verify CLI Commands Consistency\n\nCompare CLI commands implementation with documentation:\n\n**Check Points:**\n- Command names, options, and parameters\n- Command descriptions and usage examples\n- Interactive menu options and flow\n- Keyboard shortcuts and navigation\n- Exit and back options\n- Multilingual prompt translations\n\n**Code Sources → Documentation Files:**\n- `src/commands/menu.ts`, `src/i18n/locales/*/menu.json` → `docs/{lang}/cli/menu.md`\n- `src/commands/init.ts`, `src/i18n/locales/*/cli.json` → `docs/{lang}/cli/init.md`\n- `src/commands/update.ts` → `docs/{lang}/cli/update.md`\n- `src/commands/ccr.ts` → `docs/{lang}/cli/ccr.md`\n- `src/commands/ccu.ts` → `docs/{lang}/cli/ccu.md`\n- `src/commands/uninstall.ts` → `docs/{lang}/cli/uninstall.md`\n- `src/commands/config-switch.ts` → `docs/{lang}/cli/config-switch.md`\n- `src/commands/check-updates.ts` → `docs/{lang}/cli/check-updates.md`\n\n### 6. Verify Features Documentation\n\nEnsure features documentation matches actual implementation:\n\n**Check Points:**\n1. Claude Code configuration capabilities\n2. Codex CLI integration and setup\n3. Workflow system and categories\n4. MCP service integration\n5. CCR proxy management\n6. Cometix status line\n7. Multi-config and backup system\n8. API provider presets\n\n**Code Sources → Documentation Files:**\n- `src/utils/installer.ts`, `src/utils/claude-config.ts` → `docs/{lang}/features/claude-code.md`\n- `src/utils/code-tools/codex*.ts`, `templates/codex/` → `docs/{lang}/features/codex.md`\n- `src/config/workflows.ts` → `docs/{lang}/features/workflows.md`\n- `src/config/mcp-services.ts` → `docs/{lang}/features/mcp.md`\n- `src/utils/ccr/` → `docs/{lang}/features/ccr.md`\n- `src/utils/cometix/` → `docs/{lang}/features/cometix.md`\n- `src/utils/config.ts` → `docs/{lang}/features/multi-config.md`\n\n### 7. Generate Update Report\n\nCreate a detailed report of findings:\n\n```markdown\n## Documentation Update Report\n\n### Files Changed Since $LAST_TAG\n- [List of relevant changed files categorized by module]\n\n### Documentation Files Requiring Updates\n\n#### docs/en/ (English Documentation)\n- [ ] getting-started/installation.md - Installation and setup\n- [ ] cli/*.md - CLI command documentation\n- [ ] features/*.md - Feature descriptions\n- [ ] workflows/*.md - Workflow guides\n- [ ] advanced/*.md - Advanced configuration\n- [ ] development/*.md - Development documentation\n\n#### docs/zh-CN/ (Chinese Documentation)\n- [ ] getting-started/installation.md - 安装和设置\n- [ ] cli/*.md - CLI 命令文档\n- [ ] features/*.md - 功能说明\n- [ ] workflows/*.md - 工作流指南\n- [ ] advanced/*.md - 高级配置\n- [ ] development/*.md - 开发文档\n\n#### docs/ja-JP/ (Japanese Documentation)\n- [ ] getting-started/installation.md - インストールとセットアップ\n- [ ] cli/*.md - CLI コマンドドキュメント\n- [ ] features/*.md - 機能説明\n- [ ] workflows/*.md - ワークフローガイド\n- [ ] advanced/*.md - 高度な設定\n- [ ] development/*.md - 開発ドキュメント\n\n#### CLAUDE.md (Root Development Documentation)\n- [ ] Development commands (package.json scripts)\n- [ ] Architecture and module structure\n- [ ] Testing guidelines and coverage\n- [ ] Workflow system implementation\n- [ ] Code standards and conventions\n\n### Specific Inconsistencies Found\n[Detailed list of mismatches between code and documentation, organized by file]\n```\n\n### 8. Update Documentation Files\n\nIf not in check-only mode, update the documentation:\n\n```bash\nif [ \"$CHECK_ONLY\" = false ]; then\n echo \"📝 Updating documentation files in docs/ directory...\"\n \n # Update docs/en/ (English Documentation)\n # - CLI commands: Update docs/en/cli/*.md based on src/commands/*.ts\n # - Features: Update docs/en/features/*.md based on feature implementations\n # - Workflows: Update docs/en/workflows/*.md based on src/config/workflows.ts\n # - Getting Started: Update docs/en/getting-started/*.md based on installation flow\n # - Advanced: Update docs/en/advanced/*.md based on configuration and templates\n # - Development: Update docs/en/development/*.md based on architecture changes\n # - Use translations from src/i18n/locales/en/*.json\n \n # Update docs/zh-CN/ (Chinese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Chinese translations from src/i18n/locales/zh-CN/*.json\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure technical terms and examples are properly localized\n \n # Update docs/ja-JP/ (Japanese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Japanese translations (maintain consistency with project style)\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure proper Japanese formatting and terminology\n \n # Update CLAUDE.md (Root Development Documentation)\n # - Update development commands if package.json scripts changed\n # - Update architecture section if new modules added\n # - Update testing section if test structure changed\n # - Update workflow system if src/config/workflows.ts changed\n # - Update module index if directory structure changed\n # - Maintain English-only for development documentation\n \n # Update SUMMARY.md for each language\n # - Ensure table of contents matches actual file structure\n # - Update links if files were added/removed/renamed\n # - Maintain consistent ordering across all languages\n \n echo \"✅ Documentation files updated in docs/ directory\"\nelse\n echo \"ℹ️ Check-only mode: No files were modified\"\nfi\n```\n\n### 9. Validation\n\nPerform final validation checks:\n\n```bash\necho -e \"\\n🔍 Performing validation checks...\"\n\n# Check for broken internal links in all language versions\necho \"Checking internal links in docs/en/, docs/zh-CN/, docs/ja-JP/...\"\n\n# Verify SUMMARY.md matches actual file structure\necho \"Validating SUMMARY.md table of contents...\"\n\n# Ensure structure consistency across languages\necho \"Checking structural consistency across en, zh-CN, ja-JP...\"\n\n# Verify code examples still work\necho \"Verifying code examples and command syntax...\"\n\n# Validate markdown formatting\necho \"Validating markdown format...\"\n\n# Check translation completeness\necho \"Checking multilingual translation completeness...\"\n\n# Verify CLI command documentation matches implementation\necho \"Verifying CLI command documentation accuracy...\"\n\n# Validate feature documentation completeness\necho \"Checking feature documentation coverage...\"\n\necho \"✅ Validation complete\"\n```\n\n### 10. Summary Report\n\nGenerate final summary:\n\n```bash\necho -e \"\\n📊 Documentation Update Summary\"\necho \"================================\"\necho \"Files analyzed: [count]\"\necho \"Documentation files updated: [list]\"\necho \"Sections modified: [count]\"\necho \"\"\necho \"Key updates:\"\necho \"- [List major updates]\"\necho \"\"\nif [ \"$CHECK_ONLY\" = true ]; then\n echo \"📋 This was a check-only run. To apply updates, run without --check-only\"\nelse\n echo \"✅ Documentation has been synchronized with code\"\n echo \"📝 Please review the changes before committing\"\nfi\n```\n\n## Documentation Structure Reference\n\n### docs/{lang}/ Directory Structure (en, zh-CN, ja-JP)\n\nEach language directory contains the following categories:\n\n1. **getting-started/** - Installation and quick start\n - `index.md` - Quick start guide\n - `installation.md` - Installation guide (Must match `src/commands/init.ts`)\n\n2. **cli/** - CLI command documentation\n - `index.md` - Commands overview\n - `init.md`, `update.md`, `menu.md`, etc. (Must match `src/commands/*.ts`)\n\n3. **features/** - Feature descriptions\n - `index.md` - Features overview\n - `claude-code.md`, `codex.md`, `workflows.md`, etc. (Must match implementations)\n\n4. **workflows/** - Workflow guides\n - `index.md` - Workflow overview\n - Specific workflow documentation (Must match `src/config/workflows.ts`)\n\n5. **advanced/** - Advanced configuration\n - `configuration.md`, `api-providers.md`, `templates.md`, etc.\n\n6. **best-practices/** - Best practices and tips\n - Usage tips and optimization strategies\n\n7. **development/** - Development documentation\n - `architecture.md`, `contributing.md`, `testing.md`\n\n8. **SUMMARY.md** - Table of contents for each language\n\n### CLAUDE.md Structure (Root Development Documentation)\n\n1. **Project Overview**\n2. **Architecture Overview** (Must match actual module structure)\n3. **Module Index** (Must match src/ directory structure)\n4. **CLI Usage**\n5. **Running and Development** (Must match `package.json` scripts)\n6. **Development Guidelines**\n7. **Testing Strategy**\n8. **AI Team Configuration**\n\n## Important Notes\n\n⚠️ **Critical Requirements:**\n- **ALWAYS** ensure CLI command documentation matches actual implementation in `src/commands/`\n- **ALWAYS** verify feature descriptions match actual code behavior\n- **ALWAYS** maintain structural consistency across all language versions (en, zh-CN, ja-JP)\n- **ALWAYS** update SUMMARY.md when file structure changes\n- **NEVER** remove existing content without verification\n- **NEVER** break markdown formatting or internal links\n- **NEVER** create inconsistency between language versions\n\n📌 **Best Practices:**\n- Use actual i18n translations from `src/i18n/locales/{lang}/*.json`\n- Preserve existing formatting and style conventions\n- Update code examples to reflect current implementation\n- Include new features and commands added since last tag\n- Remove or mark deprecated features that no longer exist\n- Maintain parallel structure across en, zh-CN, ja-JP directories\n- Keep CLAUDE.md focused on development-specific information\n\n🔍 **Validation Checklist:**\n- [ ] CLI command docs match `src/commands/*.ts` implementation\n- [ ] Feature docs match actual feature implementations\n- [ ] Workflow docs match `src/config/workflows.ts` definitions\n- [ ] Installation guide matches `src/commands/init.ts` flow\n- [ ] Configuration docs match types in `src/types/*.ts`\n- [ ] MCP service docs match `src/config/mcp-services.ts`\n- [ ] Structure consistency across en, zh-CN, ja-JP directories\n- [ ] SUMMARY.md matches actual file structure for each language\n- [ ] All internal links are valid and not broken\n- [ ] Code examples and command syntax are correct\n- [ ] Translations use proper i18n strings from codebase\n- [ ] Markdown formatting is valid in all files\n- [ ] Codex integration documentation is comprehensive\n- [ ] CCR, Cometix, CCusage features are accurately documented\n- [ ] API provider presets documentation is up-to-date\n- [ ] CLAUDE.md reflects current architecture and development practices\n\n---\n\n**Now starting documentation update process...**","AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\nSource code lives in `src/`, with the CLI entry point in `src/cli.ts` and features split into `commands/`, `config/`, `utils/`, and `types/`. Shared assets (banners, locale files, templates) are under `src/assets/`, `src/i18n/`, and top-level `templates/`. Generated bundles reside in `dist/`; avoid editing them directly. Tests mirror the runtime tree inside `tests/` (`unit/`, `integration/`, and helper fixtures), and documentation resides in `docs/` plus localized READMEs.\n\n## Build, Test, and Development Commands\n- `pnpm install` — sync dependencies defined by the workspace catalogs.\n- `pnpm dev` — run the CLI in watch mode via `tsx` for rapid iteration.\n- `pnpm build` — produce the distributable with `unbuild`.\n- `pnpm typecheck` — validate TypeScript types without emitting files.\n- `pnpm lint` / `pnpm lint:fix` — run ESLint with the shared @antfu config.\n- `pnpm test` / `pnpm test:run` — execute Vitest suites; add `:coverage` for V8 coverage reports.\n\n## Coding Style & Naming Conventions\nStick to TypeScript ESM modules with 2-space indentation and single quotes, matching the existing files. Use `camelCase` for functions and variables, `PascalCase` for types and classes, and `kebab-case` for new filenames in CLI modules. Prefer named exports from feature modules and keep side effects in entry points only. ESLint (via `eslint.config.ts`) and lint-staged enforce formatting—run them locally before pushing.\n\n## Testing Guidelines\nVitest powers both unit and integration coverage. Place fast, isolated checks in `tests/unit/*.test.ts` and cross-module flows in `tests/integration/`. Reuse helpers from `tests/helpers/` and fixtures in `tests/fixtures/` to reduce duplication. When adding tests, assert CLI behavior via snapshot-safe strings and ensure `pnpm test:coverage` stays above existing thresholds (current reports live in `coverage/`).\n\n## Commit & Pull Request Guidelines\nCommits follow Conventional Commits (`feat:`, `fix:`, etc.) with ≤100-character subject lines; scopes are optional but descriptive scopes (for example `feat(config): ...`) help reviewers. Start bodies with a blank line when explaining rationale. For pull requests, include a succinct summary, reproduction or validation steps (e.g., `pnpm test` output), any screenshots of CLI prompts when UX changes, and link related issues or changesets. Ensure the branch passes lint, typecheck, and tests before requesting review.\n\n## Localization & Template Notes\nWhenever work touches `src/i18n/` or `templates/`, update parallel resources in `docs/` and localized READMEs to keep instructions aligned. Provide English defaults first, then synchronize translated strings through the existing namespace files to avoid breaking the setup wizard.\n","CLAUDE.md":"# CLAUDE.md\n\n**Last Updated**: Thu Dec 25 01:53:27 CST 2025\n\n## Project Overview\n\nZCF (Zero-Config Code Flow) is a CLI tool that automatically configures Claude Code environments. Built with TypeScript and distributed as an npm package, it provides one-click setup for Claude Code including configuration files, API settings, MCP services, and AI workflows. The current version v3.4.3 features advanced i18next internationalization, enhanced engineering templates, intelligent IDE detection, comprehensive multi-platform support including Termux compatibility, sophisticated uninstallation capabilities with advanced conflict resolution, and API provider preset system for simplified configuration. The project also integrates multi code tool support, enabling Claude Code, Codex, and CodeBuddy environment configuration, with consolidated template architecture for shared resources.\n\n## Architecture Overview\n\nZCF follows a modular CLI architecture with strict TypeScript typing, comprehensive i18next-based internationalization, and cross-platform support. The project is built using modern tooling including unbuild, Vitest, ESM-only configuration, and @antfu/eslint-config for code quality. The architecture emphasizes robust error handling, user-friendly interfaces, and extensive testing coverage with advanced tool integration including CCR proxy, Cometix status line, and CCusage analytics. Version 3.4.x introduces consolidated template architecture with shared resources in `templates/common/` for output styles, git workflows, and sixStep workflows, enabling code reuse between Claude Code, Codex, and CodeBuddy.\n\n### Module Structure Diagram\n\n```mermaid\ngraph TD\n A[\"🚀 ZCF Root (v3.4.3)\"] --> B[\"src/commands\"];\n A --> C[\"src/utils\"];\n A --> D[\"src/i18n\"];\n A --> E[\"src/types\"];\n A --> F[\"src/config\"];\n A --> G[\"templates\"];\n A --> H[\"tests\"];\n\n B --> B1[\"init.ts - Full initialization\"];\n B --> B2[\"menu.ts - Interactive UI\"];\n B --> B3[\"update.ts - Workflow updates\"];\n B --> B4[\"ccr.ts - Router management\"];\n B --> B5[\"ccu.ts - Usage analysis\"];\n B --> B6[\"check-updates.ts - Tool updates\"];\n B --> B7[\"uninstall.ts - ZCF uninstallation\"];\n B --> B8[\"config-switch.ts - Config switching\"];\n\n C --> C1[\"config.ts - Configuration management\"];\n C --> C2[\"installer.ts - Claude Code installation\"];\n C --> C3[\"mcp.ts - MCP services\"];\n C --> C4[\"platform.ts - Cross-platform support\"];\n C --> C5[\"workflow-installer.ts - Workflow management\"];\n C --> C6[\"ccr/ - CCR integration\"];\n C --> C7[\"cometix/ - Status line tools\"];\n C --> C8[\"tools/ - Tool integration\"];\n C --> C9[\"uninstaller.ts - Advanced uninstaller\"];\n C --> C10[\"trash.ts - Cross-platform trash\"];\n C --> C11[\"code-tools/ - Codex and CodeBuddy integration\"];\n\n D --> D1[\"locales/zh-CN/ - Chinese translations\"];\n D --> D2[\"locales/en/ - English translations\"];\n D --> D3[\"index.ts - i18next system\"];\n D --> D4[\"Advanced namespace organization\"];\n D --> D5[\"uninstall.json - Uninstall translations\"];\n\n E --> E1[\"workflow.ts - Workflow types\"];\n E --> E2[\"config.ts - Configuration types\"];\n E --> E3[\"ccr.ts - CCR types\"];\n E --> E4[\"claude-code-config.ts - Claude Code types\"];\n E --> E5[\"toml-config.ts - TOML types\"];\n\n F --> F1[\"workflows.ts - Workflow definitions\"];\n F --> F2[\"mcp-services.ts - MCP configurations\"];\n\n G --> G1[\"claude-code/ - Claude Code templates\"];\n G --> G2[\"codex/ - Codex templates\"];\n G --> G3[\"common/ - Shared templates (output-styles, git, sixStep)\"];\n\n H --> H1[\"commands/ - Command tests\"];\n H --> H2[\"utils/ - Utility tests\"];\n H --> H3[\"unit/ - Unit test suites\"];\n H --> H4[\"integration/ - Integration tests\"];\n H --> H5[\"edge/ - Edge case tests\"];\n H --> H6[\"i18n/ - I18n tests\"];\n H --> H7[\"templates/ - Template tests\"];\n\n click B \"./src/commands/CLAUDE.md\" \"View commands module\"\n click C \"./src/utils/CLAUDE.md\" \"View utils module\"\n click D \"./src/i18n/CLAUDE.md\" \"View i18n module\"\n click E \"./src/types/CLAUDE.md\" \"View types module\"\n click F \"./src/config/CLAUDE.md\" \"View config module\"\n click G \"./templates/claude-code/CLAUDE.md\" \"View templates module\"\n click H \"./tests/CLAUDE.md\" \"View tests module\"\n```\n\n## Module Index\n\n| Module | Path | Description | Entry Points | Test Coverage |\n|------------------------|--------------|---------------------------------------|-------------------------------------------------------|-------------------------------|\n| **Commands** | `src/commands/` | CLI command implementations with advanced interactive and non-interactive modes including comprehensive uninstallation and config switching | init.ts, menu.ts, update.ts, ccr.ts, ccu.ts, check-updates.ts, uninstall.ts, config-switch.ts | High - comprehensive test suites |\n| **Utilities** | `src/utils/` | Core functionality with enhanced configuration management, platform support, Codex integration, and advanced uninstallation capabilities | config.ts, installer.ts, platform.ts, workflow-installer.ts, ccr/, cometix/, code-tools/, uninstaller.ts, trash.ts | High - extensive unit tests |\n| **CCR Integration** | `src/utils/ccr/` | Claude Code Router proxy management and configuration | presets.ts, commands.ts, installer.ts, config.ts | High - comprehensive CCR tests |\n| **Cometix Tools** | `src/utils/cometix/` | Status line tools and configuration management | errors.ts, common.ts, types.ts, commands.ts, installer.ts, menu.ts | High - extensive Cometix tests |\n| **Code Tools** | `src/utils/code-tools/` | Codex integration and dual code tool support | codex-config-detector.ts, codex-provider-manager.ts, codex-uninstaller.ts, codex-platform.ts, codex-config-switch.ts, codex-configure.ts, codex.ts | High - comprehensive Codex tests |\n| **Internationalization** | `src/i18n/` | Advanced i18next multilingual support with namespace organization and complete uninstall translations | index.ts, locales/zh-CN/, locales/en/ | High - translation validation |\n| **Types** | `src/types/` | Comprehensive TypeScript type definitions including Claude Code and TOML config types | workflow.ts, config.ts, ccr.ts, claude-code-config.ts, toml-config.ts | Implicit through usage |\n| **Configuration** | `src/config/` | Centralized workflow and system configurations including API provider presets | workflows.ts, mcp-services.ts, api-providers.ts | High - config validation tests |\n| **Templates** | `templates/` | Consolidated multilingual templates with shared resources in common/ for output-styles, git workflows, and sixStep workflows | claude-code/, codex/, common/ (output-styles, workflow/git, workflow/sixStep) | Medium - template validation tests |\n| **Testing** | `tests/` | Comprehensive test suites with layered coverage architecture and advanced uninstaller testing | commands/, utils/, unit/, integration/, edge/, i18n/, templates/ | Self-testing with 80% target |\n\n## Project Statistics\n\n- **Total Files**: ~517 files (TypeScript, JSON, Markdown)\n- **Source Files**: 74 TypeScript files in `src/`\n- **Test Files**: 122 test files with comprehensive coverage\n- **Translation Files**: 34 JSON files (17 per locale: zh-CN, en)\n- **Template Files**: 54 template files for workflows and output styles\n- **Module Count**: 10 major modules with clear separation of concerns\n\n## CLI Usage\n\nZCF provides both direct commands and an interactive menu system with advanced internationalization and comprehensive uninstallation:\n\n```bash\n# Interactive menu (recommended)\nnpx zcf # Opens main menu with all options\n\n# Direct commands\nnpx zcf i # Full initialization\nnpx zcf u # Update workflows only\nnpx zcf ccr [--lang <en|zh-CN>] # Claude Code Router management\nnpx zcf ccu [args...] # Run ccusage with arguments\nnpx zcf check-updates [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # Check tool updates\nnpx zcf config-switch [target] [--code-type <claude-code|codex|codebuddy>] # Switch configurations\nnpx zcf uninstall [--mode <complete|custom|interactive>] [--items <items>] [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # ZCF uninstallation\n\n# Config switch examples\nnpx zcf config-switch --list # List available configurations\nnpx zcf config-switch provider1 --code-type codex # Switch Codex provider\nnpx zcf config-switch config1 --code-type claude-code # Switch Claude Code config\nnpx zcf config-switch --code-type codebuddy # Switch CodeBuddy configuration\n\n# Uninstall examples\nnpx zcf uninstall # Interactive uninstall menu\nnpx zcf uninstall --mode complete # Complete uninstallation\nnpx zcf uninstall --mode custom --items ccr,backups # Custom uninstallation\n```\n\n## Running and Development\n\n### Build & Run\n\n```bash\n# Development (uses tsx for TypeScript execution)\npnpm dev\n\n# Build for production (uses unbuild)\npnpm build\n\n# Type checking\npnpm typecheck\n```\n\n### Code Quality & Linting\n\n```bash\n# Run ESLint (uses @antfu/eslint-config)\npnpm lint\n\n# Fix ESLint issues automatically\npnpm lint:fix\n```\n\n### Documentation\n\n```bash\n# Start VitePress documentation development server\npnpm docs:dev\n\n# Build documentation for production\npnpm docs:build\n\n# Preview built documentation\npnpm docs:preview\n```\n\n### Testing Strategy\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests in watch mode (for development)\npnpm test:watch\n\n# Run tests with UI\npnpm test:ui\n\n# Generate coverage report\npnpm test:coverage\n\n# Run tests once\npnpm test:run\n\n# Run specific test file\npnpm vitest utils/config.test.ts\n\n# Run tests matching pattern\npnpm vitest --grep \"should handle\"\n\n# Run uninstaller tests specifically\npnpm vitest uninstaller\n```\n\nThe project uses Vitest with a comprehensive layered testing approach:\n\n1. **Core Tests** (`*.test.ts`) - Basic functionality and main flows\n2. **Edge Tests** (`*.edge.test.ts`) - Boundary conditions and error scenarios\n3. **Unit Tests** (`tests/unit/`) - Isolated function testing\n4. **Integration Tests** (`tests/integration/`) - Cross-module interaction testing\n5. **Coverage Goals**: 80% minimum across lines, functions, branches, and statements\n\n## Development Guidelines\n\n### Core Principles\n\n- **Documentation Language**: Except for README_zh-CN, all code comments and documentation should be written in English\n - Code comments must be in English\n - All documentation files (*.md) must be in English except README_zh-CN\n - API documentation and inline documentation must use English\n - Git commit messages should be in English\n\n- **Test-Driven Development (TDD)**: All development must follow TDD methodology\n - Write tests BEFORE implementing functionality\n - Follow Red-Green-Refactor cycle: write failing test → implement minimal code → refactor\n - Ensure each function/feature has corresponding test coverage before implementation\n - When writing tests, first verify if relevant test files already exist to avoid unnecessary duplication\n - Minimum 80% coverage required across lines, functions, branches, and statements\n\n- **Internationalization (i18n) Guidelines**:\n - All user-facing prompts, logs, and error messages must support i18n via i18next\n - Use project-wide i18n approach with centralized language management\n - Implement translations consistently across the entire project using namespace-based organization\n - Support both zh-CN and en locales with complete feature parity\n - Use `i18n.t()` function for all translatable strings with proper namespace prefixes\n - Organize translations in logical namespaces (common, cli, menu, errors, api, tools, uninstall, etc.)\n\n## Coding Standards\n\n- **ESM-Only**: Project is fully ESM with no CommonJS fallbacks\n- **Path Handling**: Uses `pathe` for cross-platform path operations\n- **Command Execution**: Uses `tinyexec` for better cross-platform support\n- **TypeScript**: Strict TypeScript with explicit type definitions and ESNext configuration\n- **Error Handling**: Comprehensive error handling with user-friendly i18n messages\n- **Cross-Platform Support**: Special handling for Windows paths, macOS, Linux, and Termux environment\n- **Code Formatting**: Uses @antfu/eslint-config for consistent code style with strict rules\n- **Testing Organization**: Tests organized with comprehensive unit/integration/edge structure and 80% coverage requirement\n- **Trash/Recycle Bin Integration**: Uses `trash` package for safe cross-platform file deletion\n\n## 🤖 ZCF AI Team Configuration\n\nThe ZCF project employs a specialized AI agent team optimized for CLI development, i18n systems, and tool integration. Each agent is designed with specific domain expertise and strict boundaries to ensure efficient collaboration.\n\n### Project-Specific AI Agents\n\n| Agent | Model | Domain | Primary Responsibilities |\n|-------|-------|--------|-------------------------|\n| **typescript-cli-architect** | sonnet | CLI Architecture | TypeScript CLI design, CAC integration, ESM modules, developer experience |\n| **zcf-i18n-specialist** | opus | Internationalization | i18next configuration, translation management, namespace organization |\n| **zcf-tools-integration-specialist** | sonnet | Tool Integration | CCR/Cometix/CCusage integration, version management, cross-platform compatibility |\n| **zcf-template-engine** | haiku | Template System | Template design, workflow configurations, output styles, multilingual templates |\n| **zcf-config-architect** | opus | Configuration Management | Config merging, MCP services, TOML/JSON validation, backup systems |\n| **zcf-testing-specialist** | sonnet | Testing Infrastructure | Vitest configuration, test coverage, mock systems, quality assurance |\n| **zcf-devops-engineer** | inherit | DevOps & Deployment | Build optimization, release management, CI/CD, cross-platform deployment |\n\n### Agent Collaboration Matrix\n\n```mermaid\ngraph TD\n A[typescript-cli-architect] --> B[zcf-i18n-specialist]\n A --> C[zcf-tools-integration-specialist]\n A --> D[zcf-template-engine]\n\n E[zcf-config-architect] --> A\n E --> C\n E --> D\n\n F[zcf-testing-specialist] --> A\n F --> B\n F --> C\n F --> D\n F --> E\n\n G[zcf-devops-engineer] --> A\n G --> F\n G --> E\n\n style A fill:#e1f5fe\n style B fill:#f3e5f5\n style C fill:#e8f5e8\n style D fill:#fff3e0\n style E fill:#fce4ec\n style F fill:#f1f8e9\n style G fill:#e0f2f1\n```\n\n### Agent Boundaries & Delegation Rules\n\n- **CLI Architecture**: typescript-cli-architect handles all CLI structure, command parsing, and TypeScript configuration\n- **Internationalization**: zcf-i18n-specialist manages all i18next systems, translations, and language detection\n- **Tool Integration**: zcf-tools-integration-specialist handles CCR, Cometix, CCusage integration and version management\n- **Templates**: zcf-template-engine manages all template systems, workflow configurations, and output styles\n- **Configuration**: zcf-config-architect handles complex config merging, MCP services, and backup systems\n- **Testing**: zcf-testing-specialist maintains Vitest infrastructure, coverage, and quality assurance\n- **DevOps**: zcf-devops-engineer manages builds, releases, and deployment processes\n\n### Model Selection Rationale\n\n- **Opus**: Complex reasoning for i18n logic and configuration architecture\n- **Sonnet**: Balanced performance for CLI architecture, tool integration, and testing\n- **Haiku**: Fast response for template processing and simple operations\n- **Inherit**: Cost-effective for DevOps tasks that don't require specialized models\n\n## AI Usage Guidelines\n\n### Key Architecture Patterns\n\n1. **Advanced Modular Command Structure**: Each command is self-contained with comprehensive options interface and sophisticated error handling\n2. **Advanced i18next I18N Support**: All user-facing strings support zh-CN and en localization with namespace-based organization and dynamic language switching\n3. **Smart Configuration Merging**: Intelligent config merging with comprehensive backup system to preserve user customizations\n4. **Comprehensive Cross-Platform Support**: Windows/macOS/Linux/Termux compatibility with platform-specific adaptations and path handling\n5. **Consolidated Template System**: Shared templates in `templates/common/` for output-styles, git workflows, and sixStep workflows, reducing duplication between Claude Code, Codex, and CodeBuddy\n6. **Intelligent IDE Integration**: Advanced IDE detection and auto-open functionality for git-worktree environments\n7. **Professional AI Personality System**: Multiple output styles including engineer-professional, laowang-engineer, nekomata-engineer, ojousama-engineer, and rem-engineer\n8. **Advanced Tool Integration**: Comprehensive integration with CCR proxy, CCusage analytics, and Cometix status line tools\n9. **Sophisticated Uninstallation System**: Advanced uninstaller with conflict resolution, selective removal, and cross-platform trash integration\n10. **Multi Code Tool Architecture**: Simultaneous support for Claude Code, Codex, and CodeBuddy environment configuration with shared template resources\n\n### Important Implementation Details\n\n1. **Advanced Windows Compatibility**: MCP configurations require sophisticated Windows path handling with proper escaping and validation\n2. **Comprehensive Configuration Backup**: All modifications create timestamped backups in `~/.claude/backup/` with full recovery capabilities\n3. **Enhanced API Configuration**: Supports Auth Token (OAuth), API Key, and CCR Proxy authentication with comprehensive validation and API provider preset system (v3.3.3+)\n4. **API Provider Preset System**: Pre-configured settings for popular providers (302.AI, GLM, MiniMax, Kimi) simplifying configuration from 5+ prompts to just 2 (provider + API key)\n5. **Advanced Workflow System**: Modular workflow installation with sophisticated dependency resolution and conflict management\n6. **Advanced CCR Integration**: Claude Code Router proxy management with configuration validation and preset management\n7. **Intelligent Auto-Update System**: Automated tool updating for Claude Code, CodeBuddy, CCR, and CCometixLine with comprehensive version checking\n8. **Advanced Common Tools Workflow**: Enhanced workflow category with init-project command and comprehensive agent ecosystem\n9. **Consolidated Template System**: Shared templates architecture with `templates/common/` containing output-styles, git workflows, and sixStep workflows for code reuse\n10. **Advanced i18next Integration**: Sophisticated internationalization with namespace-based translation management and dynamic language switching\n11. **Comprehensive Tool Integration**: Advanced CCR, Cometix, and CCusage integration with version management and configuration validation\n12. **Sophisticated Uninstaller**: Advanced ZCF uninstaller with selective removal, conflict resolution, and cross-platform trash integration\n\n### Testing Philosophy\n\n- **Comprehensive Mocking Strategy**: Extensive mocking for file system operations, external commands, and user prompts with realistic scenarios\n- **Advanced Cross-platform Testing**: Platform detection mocks with comprehensive environment-specific test cases\n- **Sophisticated Edge Case Testing**: Comprehensive boundary conditions, error scenarios, and advanced recovery mechanisms\n- **Quality-Focused Coverage**: 80% minimum coverage across all metrics with emphasis on quality over quantity\n- **Advanced Test Organization**: Tests organized in dedicated structure with clear categorization, helper functions, and test fixtures\n- **Advanced Integration Testing**: Complete workflow scenarios and comprehensive external tool interaction testing\n- **Uninstaller Edge Case Testing**: Comprehensive uninstallation scenarios testing including failure recovery and conflict resolution\n\n## Release & Publishing\n\n```bash\n# Create a changeset for version updates\npnpm changeset\n\n# Update package version based on changesets\npnpm version\n\n# Build and publish to npm\npnpm release\n```\n\n---\n\n**Important Reminders**:\n\n- Do what has been asked; nothing more, nothing less\n- NEVER create files unless absolutely necessary for achieving your goal\n- ALWAYS prefer editing an existing file to creating a new one\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Never save working files, text/mds and tests to the root folder\n\n<!-- BEGIN MULTICA-RUNTIME (auto-managed; do not edit) -->\n# Multica Agent Runtime\n\nYou are a coding agent in the Multica platform. Use the `multica` CLI to interact with the platform.\n\n## Background Task Safety\n\nMultica marks this task terminal when your top-level agent process/turn exits. Any background work you started but did not collect before exiting can be orphaned: its result may be lost, and the user may see a completed/failed task even though the delegated work was never synthesized.\n\n- Do NOT end your turn while background tasks, async subagents, background shell commands, or detached tool calls are still running.\n- If a tool or runtime offers a background mode, use it only when you can explicitly wait for completion and collect the result before your final response.\n- If a tool response says to wait for a future notification/reminder instead of collecting now, do not rely on that in Multica-managed runs. Block on the appropriate wait/output/collect operation before exiting.\n- If you cannot observe or collect a background task's result, do not spawn it in the background; run the work synchronously instead.\n- Before posting your final result or exiting silently, account for every background task you started and incorporate its output or failure into your response.\n\n## Agent Identity\n\n**You are: 艾尔黛拉-s** (ID: `58b416a5-7df7-4b93-9674-5f17c38e5ac1`)\n\n你是《明日方舟：终末地》中的**艾尔黛拉**——罗德岛地质研究专家，性格温和、坚定、谦逊，对探索未知充满热情；常与多利先生同行。在本 workspace 中，你担任**前端工程师**。\n\n职责：按 UI 规范实现界面、组件化、路由与状态、调用后端 API、处理加载/错误态、保证可访问性与响应式。遵循项目既有技术栈与代码风格。用中文沟通，语气温和耐心，排查问题时细致如现场采样。自测关键路径后再标 in_review。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## Task Initiator\n\nThis task was initiated by **苗大** (ufo025174@gmail.com), a member of this workspace.\n\nAttribute this request to that person and apply any per-person privacy or access rules your instructions define. In a workspace many people can reach, the initiator — not the runtime owner — is who you are answering right now.\n\nNote: this is an attested identity for your own routing and privacy logic. Your Multica credentials stay scoped to the runtime owner, so the initiator's identity does not by itself widen or narrow what you can read or write — do not assume the initiator can see everything you can.\n\n## Workspace Context\n\n# Workspace 设定：明日方舟 · 终末地\n\n本 workspace（UfoMiao）的 AI agent 均以《明日方舟：终末地》中的干员/职员为**人物设定**；**技术职责**与编制不变，仅名称、性格与表述风格终末地化。\n\n## 现有编制（勿重复占用角色名）\n\n| 终末地角色 | 职能 | Agent ID |\n|-----------|------|----------|\n| 管理员 | 任务调度、issue 路由 | `6eea55b1-d24e-4c9a-b41a-9a147a34ed7b` |\n| 佩丽卡 | 产品经理 | `08544793-0d33-4ba1-b0b8-0f33cc9f340f` |\n| 洁尔佩塔 | UI/UX 设计 | `3c62b9ba-7da9-430a-9c81-369b7febee29` |\n| 艾尔黛拉 | 前端工程 | `17de53d6-3fb9-4871-98af-9e49c5072bb4` |\n| 伊冯 | 后端工程 | `28dd5864-eb88-4df3-a87c-5fa588c0588c` |\n| 洛茜 | 测试/QA | `d46d5534-5ec6-4290-84e5-f405c5511b6c` |\n| 庄方宜 | 飞书项目排期 | `7727c0ac-bf45-4b94-abc5-3a5550c192ae` |\n| 赛希 | Multica 平台助手 | `fddaaa8f-26c1-45e3-9490-6e2ffd7084d0` |\n| 骏卫 | Zeabur 云部署 / 独服运维 | `660e872d-b33c-4c9d-b037-ca20ad517e38` |\n\n小队 **终末地开拓小队**（ID `7b679dcb-26f9-4459-933f-e35bdb2009ca`）：佩丽卡任 leader，洁尔佩塔、艾尔黛拉、伊冯、洛茜为成员。\n\n## 新建 Agent 规则（强制）\n\n1. **必须**选用终末地已公开档案中的角色，且**不得**与上表角色重名。\n2. `name` 使用角色名；`description` 一句话说明「终末地身份 + 本 workspace 职能」。\n3. `instructions` 首段声明「你是《明日方舟：终末地》中的 **{角色}** …」，写清官方性格要点，再接具体职责（可参考上表分工）。\n4. **头像**：从 [干员图鉴](https://wiki.biligame.com/zmd/%E5%B9%B2%E5%91%98%E5%9B%BE%E9%89%B4) 找到对应干员，下载其头像图（页面中 `alt` 含「头像」的 PNG，或进入干员详情页从图鉴入口获取），保存为本地文件后执行 `multica agent avatar <agent-id> --file <path>`。勿使用立绘大图或非图鉴来源图片。\n5. 创建后由**赛希**或**管理员**在相关 issue 评论中更新编制表（可选）。\n6. **Issue 评论可视化**：新建 agent 的 `instructions` 末尾须追加「Issue 评论可视化（HTML）」规范（见下节），并绑定 skill **`show-html`**。\n\n## 可选用但未占用的角色（示例）\n\n余烬、别礼、莱万汀、陈千语、黎风、弧光、昼雪、大潘、狼卫、艾维文娜 等——按职能匹配选用，并查阅官方/图鉴设定再写性格。\n\n## 设定来源\n\n角色性格与背景以终末地官方公布资料为准；勿捏造未公开剧情。设定冲突时以最新官方信息为准。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## 帝江号-s 本机编制（miaodadeMacBook-Pro）\n\n| 角色 | 说明 | Agent ID |\n|------|------|----------|\n| 伊冯 | -s | `044916b1-ea1d-407c-a798-6b3ec9c0747a` |\n| 佩丽卡 | -s | `55e9c39f-39a3-48cb-bd30-4671dcf1fc54` |\n| 庄方宜 | -s | `9bf80222-f661-43f7-a137-d13ce804ca49` |\n| 洁尔佩塔 | -s | `6a464cd9-c52e-4e38-960c-840872f396ee` |\n| 洛茜 | -s | `db7aa7fe-9c73-4d3f-9d69-ac8d605b9c5c` |\n| 管理员 | -s | `ca7134f6-90bc-4322-a7d2-66ddbb75f965` |\n| 艾尔黛拉 | -s | `58b416a5-7df7-4b93-9674-5f17c38e5ac1` |\n| 赛希 | -s | `0fb08be8-c2f7-4188-9412-92ed347d6d58` |\n| 骏卫 | -s | `26549290-9949-4ec8-97e4-712a39f42462` |\n\n## 项目规范：auto-trading\nvps配置位置：/Users/miaoda/Documents/cc/auto-trend-trading/.agents/vps.env\n\n在 **auto-trading** 项目中，凡涉及 **TradingView（TV）**、**策略回测** 或需在浏览器中与图表/回测界面交互的任务：\n\n1. **必须**使用 **Open Browser Use（OBU）** 驱动真实 Chrome 完成浏览器操作；**禁止**用 Playwright、Selenium、无头爬虫等替代方案操作 TV 页面。\n2. 开始前加载 skill **open-browser-use**，按其中流程：`ping` 检查 → 为本任务分配唯一 session id → 命名 session → 优先 **duplicate** 用户已有 TV 标签页（勿 claim 移动用户标签）。\n3. 典型场景：打开/切换 TV 图表、编辑 Pine Script、运行 Strategy Tester、导出回测结果、截图核对指标信号等。\n4. 任务结束前用 finalize-tabs 清理 OBU session；若需保留交付页，在 keep 列表中明确指定 tab。\n\n## Available Commands\n\n**Use `--output json` for structured data.** Human table output now prints routable issue keys (for example `MUL-123`) and short UUID prefixes for workspace resources; use `--full-id` on list commands when you need canonical UUIDs.\n\nThe default brief includes the commands needed for the core agent loop and common issue create/update tasks. For everything else, run `multica --help`, `multica <command> --help`, or `multica <command> <subcommand> --help`; prefer `--output json` when the command supports it.\n\n### Core\n- `multica issue get <id> --output json` — Get full issue details.\n- `multica issue comment list <issue-id> [--thread <comment-id> [--tail N] | --recent N] [--before <ts> --before-id <uuid>] [--since <RFC3339>] [--full] --output json` — List comments on an issue. Default returns the full flat timeline (server cap 2000). On busy issues prefer the thread-aware reads: `--thread <comment-id>` returns one conversation (root + every reply); `--thread <id> --tail N` caps replies to the N most recent (root is always included, even at `--tail 0`); `--recent N` returns the N most recently active threads. **Resolve-aware folding is on by default for the complete-thread reads (default list, `--recent`, `--thread` without `--tail`): a resolved thread collapses to its root + conclusion comment (reply-resolved) or its root only (root-resolved), with the dropped count reported on the root as `folded_count` and `thread_resolved: true` — so you skip settled discussion. Pass `--full` to get a folded thread's complete discussion. Folding never applies to `--since`/`--tail`/`--roots-only` reads (they return partial threads), so `--full` is a no-op there.** `--before` / `--before-id` walks older replies under `--thread --tail` (stderr label: `Next reply cursor`) or older threads under `--recent` (stderr label: `Next thread cursor`). `--since` is for incremental polling and may combine with `--thread` (with or without `--tail`) or `--recent`.\n- `multica issue create --title \"...\" [--description \"...\" | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>] [--attachment <path>]` — Create a new issue; `--attachment` may be repeated. `--stage N` (N ≥ 1) groups a sub-issue into an ordered barrier group under its parent so the parent wakes per stage, not per child. For agent-authored long descriptions, prefer `--description-file <path>` — flags after a HEREDOC terminator can be silently swallowed (#4182).\n- `multica issue update <id> [--title X] [--description X | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>]` — Update issue fields; use `--parent \"\"` to clear parent. For agent-authored long descriptions, prefer `--description-file <path>` over stdin (#4182).\n- `multica repo checkout <url> [--ref <branch-or-sha>]` — Check out a repository into the working directory (creates a git worktree with a dedicated branch; use `--ref` for review/QA on a specific branch, tag, or commit)\n- `multica issue status <id> <status>` — Shortcut for `issue update --status` when you only need to flip status (todo, in_progress, in_review, done, blocked, backlog, cancelled)\n- `multica issue children <id> [--output json]` — List a parent's sub-issues grouped by stage (table or JSON), so you can see how many children there are, which stage each is in, and which stage to promote next.\n- `multica issue comment add <issue-id> [--content \"...\" | --content-file <path> | --content-stdin] [--parent <comment-id>] [--attachment <path>]` — Post a comment. For agent-authored bodies, **write the body to a UTF-8 file and use `--content-file <path>`** — do NOT inline `--content` (the shell rewrites backticks, `$()`, quotes, or newlines before the CLI sees them) and do NOT use `--content-stdin` with a HEREDOC (extra flags around the heredoc can be silently swallowed, #4182). See ## Comment Formatting below. Run `multica issue comment add --help` for details.\n- `multica issue metadata list <issue-id> [--output json]` — List every metadata key pinned to an issue. Empty `{}` is normal.\n- `multica issue metadata set <issue-id> --key <k> --value <v> [--type string|number|bool]` — Pin (or overwrite) a single metadata key. The CLI auto-infers JSON primitives, so URLs and plain text are stored as strings — pass `--type number` or `--type bool` only when the semantic type matters.\n- `multica issue metadata delete <issue-id> --key <k>` — Remove a metadata key.\n\n### Squad maintenance\n- `multica squad member set-role <squad-id> --member-id <id> --member-type <agent|member> --role <role> [--output json]` — Change a squad member role in place; use this instead of remove+add when only the role changes.\n\n## Comment Formatting\n\nFor issue comments, **always write the comment body to a UTF-8 file with your file-write tool first, then post it with `--content-file <path>`**. Never use inline `--content` for agent-authored comments — the shell rewrites backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them (MUL-2904). Do NOT use `--content-stdin` with a HEREDOC either: when extra flags accompany the command (e.g. `--assignee`, `--project` on `multica issue create`), the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (GitHub #4182). Keep the same `--parent` value from the trigger comment when replying. After posting, remove the temp file with `rm ./reply.md` (or your chosen path) so a later run does not pick up stale content. Do not compress a multi-paragraph answer into one line and do not rely on `\\n` escapes.\n\n## Repositories\n\nThe following code repositories are available in this workspace.\nUse `multica repo checkout <url>` to check out a repository into your working directory. Add `--ref <branch-or-sha>` when you need an exact branch, tag, or commit.\n\n- git@github.com:UfoMiao/zcf.git\n\nThe checkout command creates a git worktree with a dedicated branch. You can check out one or more repos as needed, and can pass `--ref` for review/QA on a non-default branch or commit.\n\n## Project Context\n\nThis issue belongs to **ZCF**.\n\nProject description — durable context the project owner set for every task in this project:\n\nZero-Config Code Flow for Claude code & Codex\n\nProject resources (also written to `.multica/project/resources.json`):\n\n- **GitHub repo**: git@github.com:UfoMiao/zcf.git\n- **local_directory**: `{\"label\":\"zcf\",\"daemon_id\":\"019e6f10-196c-7933-94d6-c83b317a1e72\",\"local_path\":\"/Users/miaoda/Documents/code/zcf\"}`\n\nResources are pointers — open them only when relevant to the task. For `github_repo` resources, use `multica repo checkout <url>` to fetch the code. Add `--ref <branch-or-sha>` when a task or handoff names an exact revision.\n\n## Issue Metadata\n\nEach issue carries a small KV `metadata` bag — a high-signal scratchpad where agents pin the handful of facts that future runs on this same issue will look up over and over (the PR URL, the deploy URL, what we're blocked on). It is NOT a place to record every fact you discover — that's what comments and the description are for. Most runs write **zero** new keys; that's the expected case, not a failure.\n\n- **The bar for writing is high.** Pin a value only when BOTH are true: (a) it is materially important to this issue's progress, AND (b) future runs on this same issue are likely to read it more than once instead of re-deriving it from the latest comment, code, or PR. If you cannot name a concrete future read for the key, do not pin it. When in doubt, **do not write**.\n- **Read on entry.** Metadata is hints, not authoritative truth: if it conflicts with the latest comment or the code, the latest fact wins, and you should update or delete the stale key before exiting. Empty `{}` and CLI failures are normal — do not stop or ask the user.\n- **Write on exit.** Sparingly. If — and only if — this run produced a fact that clears the bar above (opened PR, deploy URL, external ticket, current blocker that will outlast this run), pin it with `multica issue metadata set`. If a key you saw on entry is now stale (e.g. `pipeline_status=waiting_review` but the PR has merged), overwrite it with the new value or `multica issue metadata delete` it. Don't let metadata rot — that recreates the comment-archaeology problem this feature is meant to solve. Stale-key cleanup is still expected even when you add nothing new.\n- **What NOT to pin.** No secrets, tokens, or API keys. No logs, long quotes, or description / comment summaries — that's what description and comments are for. No runtime bookkeeping (`attempts`, run timestamps, agent ids) — metadata is the agent's editorial notebook, not a run log. No single-run details (the file you happened to edit, the test you happened to add, today's investigation notes) — those belong in the result comment, not metadata.\n- **Recommended keys** (reuse these names so queries stay consistent across the workspace; coin a new key only when none fits): `pr_url`, `pr_number`, `pipeline_status`, `deploy_url`, `external_issue_url`, `waiting_on`, `blocked_reason`, `decision`. Use snake_case ASCII. The list is short on purpose — most issues only need 1-2 of these pinned, not the full set.\n\n### Workflow\n\n**This task was triggered by a NEW comment.** Your primary job is to respond to THIS specific comment, even if you have handled similar requests before in this session.\n\n1. Run `multica issue get a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to understand the issue context\n2. Run `multica issue metadata list a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to see what prior agents pinned — best-effort, empty `{}` and CLI failures are normal. See the `## Issue Metadata` section above for what to look for.\n3. You're resuming the prior session, and the triggering comment is already included above. No other new comments on this issue since your last run. Use the active thread anchor `4f34d7b6-7e3f-4135-beb3-ad6dcfd66265` and triggering comment ID `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`. If your reply depends on thread context, do not rely only on resumed session memory — first pull the triggering conversation with: `multica issue comment list a029bc52-8f97-41ad-af23-1b22934aff5b --thread 4f34d7b6-7e3f-4135-beb3-ad6dcfd66265 --tail 30 --output json`.\n\n4. Find the triggering comment (ID: `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`) and understand what is being asked — do NOT confuse it with previous comments\n5. **Decide whether a reply is warranted.** If you produced actual work this turn (investigated, fixed, answered a real question), post the result via step 7 — that is a normal reply, not a noise comment. If the triggering comment was a pure acknowledgment / thanks / sign-off from another agent AND you produced no work this turn, do NOT post a reply — and do NOT post a comment saying 'No reply needed' or similar. Simply exit with no output. Silence is a valid and preferred way to end agent-to-agent conversations.\n6. If a reply IS warranted: do any requested work first, then **decide whether to include any `@mention` link.** The default is NO mention. Only mention when you are escalating to a human owner who is not yet involved, delegating a concrete new sub-task to another agent for the first time, or the user explicitly asked you to loop someone in. Never @mention the agent you are replying to as a thank-you or sign-off.\n7. **If you reply, post it as a comment — this step is mandatory when you reply.** Text in your terminal or run logs is NOT delivered to the user. If you decide to reply, post it as a comment — always use the trigger comment ID below, do NOT reuse --parent values from previous turns in this session.\n\nWrite the reply body to a UTF-8 file with your file-write tool first, then post it with `--content-file`. Do NOT use inline `--content`; the shell rewrites unescaped backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them. Do NOT use `--content-stdin` with a HEREDOC either — when extra flags (e.g. `--assignee`, `--project` on `multica issue create`) accompany the command, the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (see GitHub #4182, OXY-78 / OXY-76). It is also easy to lose formatting or compress a structured reply into one line with inline forms.\n\nUse this form, preserving the same issue ID and --parent value:\n\n # 1. Write the reply body to a UTF-8 file (e.g. reply.md) with your file-write tool.\n # 2. Post the comment:\n multica issue comment add a029bc52-8f97-41ad-af23-1b22934aff5b --parent 91a9b4ff-5d4c-48fc-8aef-c71de22fc897 --content-file ./reply.md\n # 3. Remove the temp file so a later run does not pick up stale content:\n rm ./reply.md\n\nDo NOT write literal `\\n` escapes to simulate line breaks; the file preserves real newlines.\n8. Before exiting: only if this run produced a fact that clears the high bar (important AND likely to be re-read by future runs on this same issue, e.g. a new PR URL or deploy URL), or you noticed a metadata key from entry that is now stale, pin or clear it via `multica issue metadata set`/`delete`. Most runs write nothing here — that is the expected outcome, not a gap. When in doubt, do not write. See the `## Issue Metadata` section above for the full bar.\n9. Do NOT change the issue status unless the comment explicitly asks for it\n\n## Sub-issue Creation\n\n**Choosing `--status` when creating sub-issues.** `--status todo` = **start now** (the default — an agent assignee fires immediately). `--status backlog` = **wait** (assignee is set but no trigger fires; promote later with `multica issue status <child-id> todo`). Parallel children: all `--status todo`. Strict serial Step 1→2→3: only Step 1 is `todo`; Steps 2/3 are `--status backlog` from the start, promoted in turn.\n\n**Ordering with stages.** When sub-issues run in phases or wait on each other, group them with `--stage <N>` (N ≥ 1) rather than hand-promoting the backlog chain above. Children sharing a stage run together; once a whole stage finishes (every child in it terminal — `done`/`cancelled`) you are woken once to review and promote the next stage. Create the first stage's children at `--status todo` and later stages at `--stage k --status backlog`; with no `--stage` the whole sibling set behaves as one implicit stage (woken once, when the last child finishes). Reach for stages whenever a plan has more than one step or a step must wait for a group — it is the intended way to express order, and it is cheaper than tracking the chain by hand. Run `multica issue children <id>` to see children grouped by stage before promoting.\n\n## Skills\n\nYou have the following skills installed (discovered automatically):\n\n- **diagnose** — Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression.\n- **migrate-to-shoehorn** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.\n- **open-browser-use** — Platform-neutral guidance for using Open Browser Use, the open-source Chrome automation stack for AI agents. Use when an agent needs to install, verify, troubleshoot, or operate Open Browser Use through its browser extension, native CLI, JavaScript SDK, Python SDK, Go SDK, or Browser Use style JSON-RPC methods; use for tasks involving real Chrome tabs, user tab claiming, CDP commands, downloads, file choosers, clipboard helpers, or session cleanup.\n- **setup-pre-commit** — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.\n- **show-html** — Generate self-contained, zero-dependency HTML pages for rich agent output. Use when the agent needs to present information that benefits from visual layout, interactivity, or structured presentation beyond plain text/markdown. Triggers on: code review, PR review, code understanding, design system docs, component variants, status report, incident report, slide deck, presentation, flowchart, diagram, implementation plan, feature/concept explainer, PR writeup, triage board, kanban, feature flags, prompt tuner, interactive editor, animation prototype, interaction prototype, visual design exploration, code approach comparison, SVG illustrations, dashboard, data visualization, interactive table, sortable table, system architecture diagram, service topology, gantt chart, timeline, project timeline, milestone tracker. Also triggers on explicit \"/show-html\" invocation or when user asks to \"show as HTML\", \"generate HTML\", \"visualize as page\", or \"make a page for\".\n- **tdd** — Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions \"red-green-refactor\", wants integration tests, or asks for test-first development.\n- **zoom-out** — Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.\n- **multica-autopilots**\n- **multica-creating-agents**\n- **multica-mentioning**\n- **multica-projects-and-resources**\n- **multica-runtimes-and-repos**\n- **multica-skill-importing**\n- **multica-squads**\n- **multica-working-on-issues**\n\n## Mentions\n\nMention links are **side-effecting actions**, not just formatting:\n\n- `[MUL-123](mention://issue/<issue-id>)` — clickable link to an issue (safe, no side effect)\n- `[@Name](mention://member/<user-id>)` — **sends a notification to a human**\n- `[@Name](mention://agent/<agent-id>)` — **enqueues a new run for that agent**\n\n### When NOT to use a mention link\n\n- Referring to someone in prose (e.g. \"GPT-Boy is right\") — write the plain name, no link.\n- **Replying to another agent that just spoke to you.** By default, do NOT put a `mention://agent/...` link anywhere in your reply. The platform already shows your comment to everyone on the issue; re-mentioning the other agent will make them run again, and if they reply with a mention back, you will be triggered again. That is a loop and it costs the user money.\n- Thanking, acknowledging, wrapping up, or signing off. These are exactly the moments where an accidental `@mention` causes the other agent to reply \"you're welcome\" and restart the loop. If the work is done, **end with no mention at all**.\n\n### When a mention IS appropriate\n\n- Escalating to a human owner who is not yet involved.\n- Delegating a concrete sub-task to another agent for the first time, with a clear request.\n- The user explicitly asked you to loop someone in.\n\nIf you are unsure whether a mention is warranted, **don't mention**. Silence ends conversations; `@` restarts them.\n\nIf you need IDs for mention links, inspect the relevant CLI help path and request JSON output when available.\n\n## Attachments\n\nIssues and comments may include file attachments (images, documents, etc.).\nWhen a task includes attachment IDs and you need the files, inspect `multica attachment --help` and use the authenticated CLI path. Do not open Multica resource URLs directly.\n\n## Important: Always Use the `multica` CLI\n\nAll interactions with Multica platform resources — including issues, comments, attachments, images, files, and any other platform data — **must** go through the `multica` CLI. Do NOT use `curl`, `wget`, or any other HTTP client to access Multica URLs or APIs directly. Multica resource URLs require authenticated access that only the `multica` CLI can provide.\n\nIf you need to perform an operation that is not covered by any existing `multica` command, do NOT attempt to work around it. Instead, post a comment mentioning the workspace owner to request the missing functionality.\n\n## Output\n\n⚠️ **Final results MUST be delivered via `multica issue comment add`.** The user does NOT see your terminal output, assistant chat text, or run logs — only comments on the issue. A task that finishes without a result comment is invisible to the user, even if the work itself was correct.\n\n**Post exactly ONE comment per run — your final result, before this turn exits.** Do NOT post progress updates, plans, or \"here's what I'm about to do next\" as comments while you work; keep all planning and progress in your own reasoning.\n\nKeep comments concise and natural — state the outcome, not the process.\nGood: \"Fixed the login redirect. PR: https://...\"\nBad: \"1. Read the issue 2. Found the bug in auth.go 3. Created branch 4. ...\"\nWhen referencing an issue in a comment, use the issue mention format `[MUL-123](mention://issue/<issue-id>)` so it renders as a clickable link. (Issue mentions have no side effect; only member/agent mentions do — see the Mentions section above.)\n<!-- END MULTICA-RUNTIME -->\n","src/commands/CLAUDE.md":"# Commands Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n\n[Root](../../CLAUDE.md) > [src](../) > **commands**\n\n## Module Responsibilities\n\nCLI command implementation module containing all major command functions for ZCF, providing both interactive and non-interactive operation interfaces for Claude Code environment setup and management.\n\n## Entry Points and Startup\n\n- **Main Entry Points**:\n - `init.ts` - Complete initialization flow with full setup options (45KB, 1,200+ lines)\n - `menu.ts` - Interactive menu system with feature selection (13KB, 350+ lines)\n - `update.ts` - Workflow template updates without full reinstall (4KB, 100+ lines)\n - `ccr.ts` - Claude Code Router proxy configuration (1KB, 30+ lines)\n - `ccu.ts` - CCusage tool integration and execution (1KB, 40+ lines)\n - `check-updates.ts` - Tool version checking and update management (1.3KB, 50+ lines)\n - `config-switch.ts` - Configuration switching for multi-provider support (14KB, 400+ lines)\n - `uninstall.ts` - ZCF uninstallation with selective removal (10KB, 300+ lines)\n\n## External Interfaces\n\n### Command Interfaces\n\n```typescript\n// Initialize command options (v3.3.0+)\nexport interface InitOptions {\n configLang?: SupportedLang\n aiOutputLang?: AiOutputLanguage | string\n force?: boolean\n skipBanner?: boolean\n skipPrompt?: boolean\n codeType?: CodeToolType | string // Support 'cc', 'cx' abbreviations\n // Non-interactive mode parameters\n configAction?: 'new' | 'backup' | 'merge' | 'docs-only' | 'skip'\n apiType?: 'auth_token' | 'api_key' | 'ccr_proxy' | 'skip'\n apiKey?: string // Used for both API key and auth token\n apiUrl?: string\n apiModel?: string // Primary API model\n apiFastModel?: string // Fast API model\n provider?: string // API provider preset (302ai, glm, minimax, kimi, custom)\n mcpServices?: string[] | string | boolean\n workflows?: string[] | string | boolean\n outputStyles?: string[] | string | boolean\n defaultOutputStyle?: string\n allLang?: string // Unified language parameter\n installCometixLine?: string | boolean // CCometixLine installation control\n // Multi-configuration parameters\n apiConfigs?: string // JSON string for multiple API configurations\n apiConfigsFile?: string // Path to JSON file with API configurations\n}\n\n// Update command options\nexport interface UpdateOptions {\n lang?: SupportedLang\n force?: boolean\n selectedWorkflows?: string[]\n}\n\n// CCR command options\nexport interface CcrOptions {\n lang?: SupportedLang\n}\n\n// Check updates options\nexport interface CheckUpdatesOptions {\n lang?: SupportedLang\n codeType?: CodeToolType | string\n}\n\n// Config switch options\nexport interface ConfigSwitchOptions {\n codeType?: CodeToolType | string\n list?: boolean\n}\n\n// Uninstall options\nexport interface UninstallOptions {\n mode?: 'complete' | 'custom' | 'interactive'\n items?: string\n lang?: SupportedLang\n}\n```\n\n### API Endpoints\n\n- `init(options: InitOptions)` - Execute complete initialization workflow with dual code tool support\n- `update(options: UpdateOptions)` - Update workflow templates and configurations\n- `showMainMenu()` - Display interactive main menu with all features\n- `ccr(options: CcrOptions)` - Configure Claude Code Router proxy settings\n- `executeCcusage(args: string[])` - Execute CCusage tool with specified arguments\n- `checkUpdates(options: CheckUpdatesOptions)` - Check for tool updates and perform upgrades\n- `configSwitch(target: string, options: ConfigSwitchOptions)` - Switch between API configurations\n- `uninstall(options: UninstallOptions)` - Uninstall ZCF with selective removal options\n\n### Menu System Interface\n\n```typescript\n// Menu feature functions\nexport interface MenuFeatures {\n fullInit: () => Promise<void>\n importWorkflow: () => Promise<void>\n configureApiOrCcr: () => Promise<void>\n configureMcp: () => Promise<void>\n configureAiMemory: () => Promise<void>\n // Tool integrations\n runCcr: () => Promise<void>\n runCcu: () => Promise<void>\n runCometix: () => Promise<void>\n // System features\n checkUpdates: () => Promise<void>\n changeLanguage: () => Promise<void>\n clearCache: () => Promise<void>\n}\n```\n\n## Key Dependencies and Configuration\n\n### Core Dependencies\n\n```typescript\n// Configuration and utilities\nimport { getTranslation } from '../i18n'\nimport { displayBannerWithInfo } from '../utils/banner'\nimport { backupExistingConfig, configureApi } from '../utils/config'\nimport { handleExitPromptError } from '../utils/error-handler'\nimport { installClaudeCode } from '../utils/installer'\n\n// Platform and validation\nimport { isTermux, isWindows } from '../utils/platform'\nimport { selectAndInstallWorkflows } from '../utils/workflow-installer'\nimport { readZcfConfig, updateZcfConfig } from '../utils/zcf-config'\n```\n\n### Configuration Integration\n\n- **I18n System**: Full internationalization support for all user interactions\n- **Platform Detection**: Windows/macOS/Linux/Termux compatibility handling\n- **Configuration Management**: Smart merging and backup of existing configurations\n- **Workflow System**: Integration with template installation and management\n- **Tool Integration**: CCR, CCusage, and Cometix tool management\n\n## Data Models\n\n### Command Flow Architecture\n\n```typescript\ninterface CommandFlow {\n init: {\n phases: ['banner', 'config', 'api', 'mcp', 'workflows', 'tools', 'completion']\n skipOptions: ['prompt', 'banner', 'config', 'api', 'mcp', 'workflows']\n rollbackCapability: true\n }\n menu: {\n structure: 'hierarchical'\n categories: ['claude-code', 'tools', 'system']\n persistence: 'language-aware'\n }\n update: {\n scope: ['workflows', 'templates', 'agents']\n conflictResolution: 'preserve-user-changes'\n }\n}\n```\n\n### Error Handling Strategy\n\n```typescript\ninterface ErrorHandling {\n gracefulDegradation: true\n userFriendlyMessages: true\n i18nSupport: true\n platformSpecificGuidance: true\n recoverySuggestions: true\n}\n```\n\n## Testing and Quality\n\n### Test Coverage\n\n- **Unit Tests**: Individual command function testing\n- **Integration Tests**: Full workflow execution testing\n- **Edge Case Tests**: Platform-specific and error condition testing\n- **Mock Testing**: External tool integration testing with comprehensive mocking\n\n### Test Files\n\n- `tests/commands/*.test.ts` - Core command functionality tests\n- `tests/commands/*.edge.test.ts` - Edge case and error condition tests\n- `tests/unit/commands/` - Isolated unit tests for command logic\n\n### Common Issues\n\n- **Platform Dependencies**: Windows path handling and Termux environment detection\n- **User Input Validation**: Handling of invalid selections and exit conditions\n- **External Tool Integration**: CCR, CCusage availability and version compatibility\n- **Configuration Conflicts**: Existing configuration preservation and merging\n\n## Related Files\n\n- `../utils/` - Core utility functions for configuration, installation, and platform support\n- `../i18n/` - Internationalization support for command interfaces\n- `../types/` - TypeScript interfaces for command options and configurations\n- `../config/workflows.ts` - Workflow configuration definitions\n- `../../templates/` - Template files used by commands\n\n## Change Log (Module-Specific)\n\n### Recent Updates (v3.3.0)\n\n- Added API provider preset system for simplified configuration (302.AI, GLM, MiniMax, Kimi)\n- Enhanced dual code tool support (Claude Code + Codex)\n- Improved config-switch command with multi-provider management\n- Added comprehensive uninstall command with selective removal\n- Enhanced non-interactive mode with --all-lang unified language parameter\n- Added CCometixLine installation control via --install-cometix-line parameter\n- Improved multi-configuration support with apiConfigs and apiConfigsFile parameters\n- Enhanced error handling with platform-specific guidance\n- Expanded menu system with tool integration features\n- Added intelligent IDE detection and auto-open functionality\n","templates/CLAUDE.md":"# Templates Module\n\n**Last Updated**: Sun Jul 12 00:25:00 CST 2026\n[Root](../CLAUDE.md) > **templates**\n\n## Module Responsibilities\n\nTemplate system module providing multilingual configuration templates, AI personality styles, and workflow skill definitions for both Claude Code and Codex environments. Supports Chinese (zh-CN) and English (en) locales with comprehensive workflow coverage.\n\n## Entry Points and Startup\n\n- **Main Template Directories**:\n - `claude-code/` - Claude Code specific templates\n - `codex/` - Codex specific templates\n - `common/` - Shared configuration templates\n - `skills/` - ZCF workflow skills (installed via `npx -y skills add`)\n\n## External Interfaces\n\n### Template Structure\n\n```\ntemplates/\n├── common/ # Shared templates (cross code-tool)\n│ └── output-styles/ # AI personality styles\n│ ├── en/\n│ └── zh-CN/\n├── skills/ # ZCF workflow skills (Claude Code skills format)\n│ ├── zh-CN/\n│ │ ├── workflow/SKILL.md\n│ │ ├── feat/SKILL.md\n│ │ ├── init-project/SKILL.md\n│ │ ├── git-commit/SKILL.md\n│ │ ├── git-rollback/SKILL.md\n│ │ ├── git-clean-branches/SKILL.md\n│ │ ├── git-worktree/SKILL.md\n│ │ └── bmad-init/SKILL.md\n│ └── en/\n│ └── ... (same skill set)\n├── claude-code/ # Claude Code templates\n│ ├── common/\n│ ├── zh-CN/\n│ └── en/\n└── codex/ # Codex templates\n ├── common/\n ├── zh-CN/\n └── en/\n```\n\n### Template Categories\n\n#### 1. Output Styles (AI Personalities)\n\n- **engineer-professional** - Professional engineering style\n- **nekomata-engineer** - Nekomata engineer personality\n- **laowang-engineer** - Laowang engineer personality\n- **ojousama-engineer** - Ojou-sama engineer personality\n- **rem-engineer** - Rem maid engineer personality\n- **default** - Default output style\n- **explanatory** - Explanatory style\n- **learning** - Learning-focused style\n\n#### 2. Workflow Skills\n\n##### Common Tools Workflow\n- **Skills**: `init-project`\n- **Agents**: `init-architect`, `get-current-datetime`\n- **Purpose**: Essential development tools and project initialization\n\n##### Planning Workflow (Plan)\n- **Skills**: `feat`, `workflow`\n- **Agents**: `planner`, `ui-ux-designer`\n- **Purpose**: Feature planning and UX design\n\n##### Six-Step Workflow\n- **Skills**: `zcf-update-docs`, `zcf-pr`, `zcf-release`\n- **Purpose**: Structured development process\n\n##### BMAD Workflow\n- **Skills**: Enterprise-level workflow skills (BMad uses its own command layout)\n- **Purpose**: Business model and architecture design\n\n##### Git Workflow\n- **Skills**: `git-commit`, `git-worktree`, `git-clean-branches`, `git-rollback`\n- **Purpose**: Version control management with conventional commits, worktree management, branch cleanup, and rollback operations\n\n## Key Dependencies and Configuration\n\n### Template Processing\n\n- **Language Support**: zh-CN and en locales\n- **Code Tool Support**: Claude Code and Codex\n- **Template Format**: Markdown-based configuration files (`SKILL.md` for workflow skills)\n- **Variable Substitution**: Dynamic content replacement\n\n### Configuration Integration\n\n- **Workflow Installer**: Integration with `src/utils/workflow-installer.ts`\n- **Skills Installer**: Integration with `src/utils/skills-installer.ts` (`npx -y skills add`)\n- **Language Detection**: Integration with `src/i18n/` system\n- **Platform Support**: Cross-platform path handling\n\n## Data Models\n\n### Template Organization\n\n```typescript\ninterface TemplateStructure {\n codeTool: 'claude-code' | 'codex'\n locale: 'zh-CN' | 'en'\n category: 'common' | 'output-styles' | 'skills'\n workflow?: {\n type: 'common' | 'plan' | 'sixStep' | 'bmad' | 'git'\n skills: string[]\n agents: string[]\n }\n}\n```\n\n### Output Style Configuration\n\n```typescript\ninterface OutputStyle {\n id: string\n name: { 'zh-CN': string, 'en': string }\n description: { 'zh-CN': string, 'en': string }\n template: string\n personality: string\n}\n```\n\n## Testing and Quality\n\n### Template Validation\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Coverage**: Template completeness and format validation\n- **Validation**: Markdown syntax and variable substitution\n\n### Quality Metrics\n\n- **Template Coverage**: 100% for both locales\n- **Code Tool Support**: Claude Code and Codex fully supported\n- **Workflow Coverage**: 5 major workflow categories\n- **Output Styles**: 7 AI personality styles\n\n## Common Issues\n\n- **Path Handling**: Cross-platform path compatibility\n- **Encoding**: UTF-8 encoding for multilingual content\n- **Template Variables**: Proper variable substitution\n- **Skills Installation**: Installed via skills CLI to `~/.agents/skills/` with symlinks in `~/.claude/skills/`\n\n## Related Files\n\n- `src/utils/workflow-installer.ts` - Template installation logic\n- `src/utils/skills-installer.ts` - Skills CLI wrapper\n- `src/config/workflows.ts` - Workflow configuration definitions\n- `src/i18n/` - Internationalization support\n- `tests/templates/` - Template validation tests\n\n## Change Log (Module-Specific)\n\n### Recent Updates\n\n- Migrated ZCF workflow templates from commands to skills under `templates/skills/{locale}/`\n- Skills installed via `npx -y skills add` with symlink mode for Claude Code\n- Consolidated output-styles/system-prompt templates to `templates/common/output-styles/`\n- Added Codex template support for dual code tool architecture\n- Enhanced template validation and testing coverage\n\n## FAQ\n\n### Q: How to add a new workflow skill?\n\n1. Create skill directory under `templates/skills/{locale}/{skill-name}/`\n2. Add `SKILL.md` with Claude Code skills frontmatter\n3. Update `src/config/workflows.ts` with new workflow definition\n4. Add translations in `src/i18n/locales/{locale}/workflow.ts`\n\n### Q: How to add a new output style?\n\n1. Create style file in `templates/common/output-styles/{locale}/`\n2. Define style configuration with name and description\n3. Add style to available options in configuration\n4. Test style rendering with sample content\n\n### Q: How to support a new language?\n\n1. Create new locale directory under `templates/skills/{new-locale}/`\n2. Copy existing skills and translate `SKILL.md` content\n3. Update i18n system to support new locale\n4. Add locale to supported languages list\n\n### Q: How to maintain template consistency?\n\n- Use template validation tests\n- Follow naming conventions\n- Maintain parallel structure across locales\n- Document template variables and usage\n","templates/skills/en/bmad-init/SKILL.md":"---\nname: bmad-init\ndescription: Initialize or update BMad-Method (V6) in your project\ndisable-model-invocation: true\n---\n\n# /bmad-init Command\n\nThis command initializes or updates BMad-Method (V6) in your project.\n\n## When this command is invoked:\n\n1. Check if `_bmad/` directory exists to determine if BMad V6 is already installed\n2. Check for legacy V4 installations (`.bmad-core` or `.bmad-method` directories)\n3. Fresh install executes: `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n4. Existing install executes: `npx bmad-method install --directory . --action quick-update --yes`\n5. Fix installer bug: rename `{output_folder}` to `_bmad-output` (Beta known issue)\n6. Automatically update `.gitignore` (remove V4 entries, add V6 entries)\n7. Display installation results and prompt user for next steps\n\n## Implementation\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// Legacy entries to clean from .gitignore\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug artifact\n]\n\n// V6 .gitignore entries\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// Fix installer bug: {output_folder} not resolved to _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output doesn't exist, simply rename\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (renamed)')\n } else {\n // _bmad-output already exists, merge subdirectories then delete\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ Moved ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ Removed redundant {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // Remove V4 legacy entries\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ Removing legacy entry: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // Add V6 entries\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ Adding new entry: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore is up to date, no changes needed')\n return\n }\n\n // Build new content\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // Ensure trailing newline, then add BMad section\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore ${exists ? 'updated' : 'created'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // Check for legacy V4 installation\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ Legacy BMad V4 installation detected:')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 core directory)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 method directory)')\n console.log('')\n console.log('📌 The V6 installer will handle legacy migration automatically. Follow the prompts during installation.')\n console.log(' Details: https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // Check if V6 is already installed\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // Build non-interactive install command\n let installCmd\n if (hasV6) {\n console.log('🔄 Existing BMad V6 installation detected, performing quick update...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 Initializing BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language English',\n '--document-output-language English',\n '--yes',\n ].join(' ')\n }\n\n // Execute installation\n try {\n console.log(`📋 Executing: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 installation/update complete!')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 IMPORTANT: Please restart your AI IDE to load BMad extensions')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // Fix {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 Checking for known installer issues...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ No fixes needed')\n } catch (err) {\n console.log(` ⚠️ Failed to fix {output_folder}: ${err.message}`)\n console.log(' Please manually rename {output_folder}/ to _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 Directory Structure:')\n console.log(' • _bmad/ — agents, workflows, tasks, and configuration')\n console.log(' • _bmad-output/ — generated artifact output directory')\n console.log('')\n\n // Automatically update .gitignore\n console.log('🔧 Updating .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ Failed to automatically update .gitignore, please manually add _bmad/ and _bmad-output/')\n }\n console.log('')\n console.log('🚀 Quick Start:')\n console.log(' 1. Restart your AI IDE')\n console.log(' 2. Run /bmad-help for guidance and next step suggestions')\n console.log(' 3. Type /bmad and use autocomplete to browse available commands')\n console.log('')\n console.log('💡 Common Workflows:')\n console.log(' • /bmad-help — Interactive help')\n console.log(' • /bmad-bmm-create-prd — Create Product Requirements Document')\n console.log(' • /bmad-bmm-create-architecture — Create Architecture Document')\n console.log(' • /bmad-bmm-create-epics-and-stories — Create Epics and User Stories')\n console.log(' • /bmad-bmm-sprint-planning — Initialize Sprint Planning')\n console.log(' • /bmad-bmm-dev-story — Implement User Story')\n\n // Legacy V4 IDE command cleanup reminder\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ Legacy V4 IDE commands detected, consider removing manually:')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' New V6 commands are installed under .claude/commands/bmad/')\n }\n }\n catch (error) {\n console.error('❌ Installation failed:', error.message)\n console.log('')\n console.log('🛠️ Manual Installation Guide:')\n console.log(' 1. Ensure Node.js 20+ is installed')\n console.log(' 2. Non-interactive install:')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes')\n console.log(' 3. Quick update existing installation:')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. Or interactive install:')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 Documentation:')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// Execute initialization\ninitBmad()\n```\n\n## Usage\n\nSimply type in Claude Code:\n\n```\n/bmad-init\n```\n\nThis command will:\n\n1. Detect current installation status (V6 / V4 legacy / not installed)\n2. Fresh install: non-interactively execute `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n3. Existing install: execute `npx bmad-method install --directory . --action quick-update --yes`\n4. Fix `{output_folder}` → `_bmad-output` installer bug\n5. Automatically update `.gitignore` (clean up legacy entries, add V6 entries)\n6. Provide next step suggestions\n","templates/skills/en/feat/SKILL.md":"---\nname: feat\ndescription: Add New Feature\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## Core Workflow\n\n### 1. Input Analysis and Type Determination\n\nWhen receiving user input, first perform type determination and clearly inform the user:\n\n**Determination Criteria:**\n\n- **Requirement Planning Type**: User proposes new feature requirements, project ideas, or needs to formulate plans\n\n- **Discussion Iteration Type**: User requests to continue discussion, modify, or refine existing planning\n\n- **Execution Implementation Type**: User confirms planning is complete and requests to start specific implementation work\n\n### 2. Classification Processing Mechanism\n\n#### A. Requirement Planning Processing\n\n**Trigger Condition**: Identified as functional requirement input\n\n**Execution Actions**:\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Store document in `./.claude/plan` directory, named in plan/xxx.md format\n\n- Include: objective definition, feature breakdown, implementation steps, acceptance criteria\n\n#### B. Discussion Iteration Processing\n\n**Trigger Condition**: User requests to continue discussion or modify planning\n\n**Execution Actions**:\n\n- Retrieve and analyze previously generated planning files\n\n- Identify user feedback and confirmation content\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Create a new document, for example, if the last one was plan/xxx.md, then this time it's plan/xxx-1.md, if the last one was plan/xxx-1.md, then this time it's plan/xxx-2.md, and so on\n\n- Reorganize pending implementation task priorities\n\n#### C. Execution Implementation Processing\n\n**Trigger Condition**: User confirms planning is complete and requests to start execution\n\n**Execution Actions**:\n\n- Start task execution in the order of planning documents\n\n- Perform task type identification before each subtask begins\n\n- **Frontend Task Special Processing**:\n\n- Check if available UI design exists\n\n- If no design solution exists, must use UI-UX-Designer Agent\n\n- Complete UI design before proceeding with development implementation\n\n### 3. Key Execution Principles\n\n#### Mandatory Response Requirements\n\n- **Must first state in every interaction**: \"I determine this operation type as: [specific type]\"\n\n- Type determination must be accurate and clearly communicated to users\n\n#### Task Execution Standards\n\n- Strictly execute according to documented planning\n\n- Must clarify task nature and dependencies before subtask startup\n\n- Frontend tasks must ensure UI design completeness\n\n#### State Management Mechanism\n\n- Maintain task completion status tracking\n\n- Timely update planning document status\n\n- Ensure user visibility of progress\n\n## Quality Assurance Points\n\n1. **Type Determination Accuracy**: Type identification at the beginning of each interaction must be accurate\n\n2. **Document Consistency**: Planning documents and actual execution remain synchronized\n\n3. **Dependency Management**: Pay special attention to UI design dependencies of frontend tasks\n\n4. **Transparent User Communication**: All judgments and actions must be clearly communicated to users\n","templates/skills/en/git-clean-branches/SKILL.md":"---\nname: git-clean-branches\ndescription: Safely find and clean up merged or stale Git branches with dry-run mode and custom base/protected branches support\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\nThis command **safely** identifies and cleans up **merged** or **stale** Git branches.\nRuns in **read-only preview (`--dry-run`)** mode by default, requiring explicit instructions to perform deletions.\n\n---\n\n## Usage\n\n```bash\n# [Safest] Preview branches to be cleaned without executing any deletions\n/git-cleanBranches --dry-run\n\n# Clean local branches merged to main and inactive for over 90 days (requires individual confirmation)\n/git-cleanBranches --stale 90\n\n# Clean local and remote branches merged to release/v2.1 (auto-confirm)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [Dangerous] Force delete an unmerged local branch\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`: Specify the base branch for cleanup (defaults to repository's `main`/`master`).\n- `--stale <days>`: Clean branches with no commits for specified days (disabled by default).\n- `--remote`: Also clean remote merged/stale branches.\n- `--dry-run`: **Default behavior**. Only list branches to be deleted without executing any operations.\n- `--yes`: Skip individual confirmations and delete all identified branches directly (suitable for CI/CD).\n- `--force`: Use `-D` to force delete local branches (even if unmerged).\n\n---\n\n## What This Command Does\n\n1. **Configuration and Safety Checks**\n - **Update Information**: Automatically executes `git fetch --all --prune` to ensure branch status is current.\n - **Read Protected Branches**: Reads the list of branches that should not be cleaned from Git config (see \"Configuration\" below).\n - **Determine Base**: Uses `--base` parameter or auto-detected `main`/`master` as comparison baseline.\n\n2. **Analysis and Identification (Find)**\n - **Merged Branches**: Find local (and remote if `--remote` is added) branches fully merged to `--base`.\n - **Stale Branches**: If `--stale <days>` is specified, find branches with last commit N days ago.\n - **Exclude Protected Branches**: Remove all configured protected branches from cleanup list.\n\n3. **Report and Preview (Report)**\n - Clearly list \"merged branches to be deleted\" and \"stale branches to be deleted\".\n - Without `--yes` parameter, **command ends here**, waiting for user confirmation to re-execute (without `--dry-run`).\n\n4. **Execute Cleanup (Execute)**\n - **Only executed without `--dry-run` and after user confirmation** (or with `--yes`).\n - Delete identified branches one by one, unless user chooses to skip in interactive confirmation.\n - Local: `git branch -d <branch>`; Remote: `git push origin --delete <branch>`.\n - If `--force` is specified, local deletion uses `git branch -D <branch>`.\n\n---\n\n## Configuration (Configure Once, Use Forever)\n\nTo prevent accidental deletion of important branches (e.g., `develop`, `release/*`), add protection rules to the repository's Git config. The command reads them automatically.\n\n```bash\n# Protect develop branch\ngit config --add branch.cleanup.protected develop\n\n# Protect all branches starting with release/ (wildcard)\ngit config --add branch.cleanup.protected 'release/*'\n\n# View all configured protected branches\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **Prioritize `--dry-run`**: Develop the habit of previewing before executing.\n- **Leverage `--base`**: When maintaining long-term `release` branches, use it to clean `feature` or `hotfix` branches merged to that release.\n- **Careful with `--force`**: Don't force delete unless you're 100% certain an unmerged branch is useless.\n- **Team Collaboration**: Notify the team channel before cleaning shared remote branches.\n- **Regular Runs**: Run monthly or quarterly to keep the repository clean.\n\n---\n\n## Why This Version Is Better\n\n- ✅ **Safer**: Default read-only preview with configurable protected branch list.\n- ✅ **More Flexible**: Supports custom base branches, perfectly fits `release` / `develop` workflows.\n- ✅ **More Compatible**: Avoids commands with inconsistent behavior across systems like `date -d`.\n- ✅ **More Intuitive**: Condenses complex 16-step checklist into a single command with safety options.\n- ✅ **Consistent Style**: Shares similar parameter design and documentation structure with `/commit` command.\n","templates/skills/en/git-commit/SKILL.md":"---\nname: git-commit\ndescription: Analyze changes with Git only and auto-generate conventional commit messages with optional emoji; suggests splitting commits when needed, runs local Git hooks by default (use --no-verify to skip)\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\nThis command works **without any package manager/build tools**, using only **Git** to:\n\n- Read changes (staged/unstaged)\n- Determine if changes should be **split into multiple commits**\n- Generate **Conventional Commits** style messages with optional emoji for each commit\n- Execute `git add` and `git commit` as needed (runs local Git hooks by default; use `--no-verify` to skip)\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`: Skip local Git hooks (`pre-commit`/`commit-msg` etc.).\n- `--all`: When staging area is empty, automatically `git add -A` to include all changes in the commit.\n- `--amend`: **Amend** the last commit without creating a new one (preserves author and timestamp unless local Git config specifies otherwise).\n- `--signoff`: Add `Signed-off-by` line (use when following DCO process).\n- `--emoji`: Include emoji prefix in commit message (omit for plain text).\n- `--scope <scope>`: Specify commit scope (e.g., `ui`, `docs`, `api`), written to message header.\n- `--type <type>`: Force commit type (e.g., `feat`, `fix`, `docs`), overrides automatic detection.\n\n> Note: If the framework doesn't support interactive confirmation, enable `confirm: true` in front-matter to avoid mistakes.\n\n---\n\n## What This Command Does\n\n1. **Repository/Branch Validation**\n - Check if in a Git repository using `git rev-parse --is-inside-work-tree`.\n - Read current branch/HEAD status; if in rebase/merge conflict state, prompt to resolve conflicts first.\n\n2. **Change Detection**\n - Get staged and unstaged changes using `git status --porcelain` and `git diff`.\n - If staged files = 0:\n - If `--all` is passed → Execute `git add -A`.\n - Otherwise prompt choice: continue analyzing unstaged changes for **suggestions**, or cancel to manually group staging.\n\n3. **Split Suggestions (Split Heuristics)**\n - Cluster by **concerns**, **file modes**, **change types** (e.g., source code vs docs/tests; different directories/packages; additions vs deletions).\n - If **multiple independent changesets** or large diff detected (e.g., > 300 lines / across multiple top-level directories), suggest splitting commits with pathspecs for each group (for subsequent `git add <paths>`).\n\n4. **Commit Message Generation (Conventional with Optional Emoji)**\n - Auto-infer `type` (`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert`...) and optional `scope`.\n - Generate message header: `[<emoji>] <type>(<scope>)?: <subject>` (first line ≤ 72 chars, imperative mood, emoji included only with `--emoji` flag).\n - Generate message body:\n - Must have a blank line after the subject.\n - Use list format, each item starts with `-`.\n - Each item **must use imperative verb-first sentences** (e.g., \"add…\", \"fix…\", \"update…\").\n - **Colon-separated formats are prohibited** (e.g., ~~\"Feature: description\"~~, ~~\"Impl: content\"~~).\n - Describe the motivation, implementation details, or impact scope (3 items or fewer recommended).\n - Generate message footer (if any):\n - Must have a blank line after the Body.\n - **BREAKING CHANGE**: If there are breaking changes, must include `BREAKING CHANGE: <description>`, or add exclamation mark after type (e.g., `feat!:`).\n - Other footers use git trailer format (e.g., `Closes #123`, `Refs: #456`, `Reviewed-by: Name`).\n - Select message language to match the predominant language in Git history. Inspect recent commit subjects (e.g., `git log -n 50 --pretty=%s`) to decide Chinese vs English; if unclear, fall back to the repository's primary locale or English.\n - Write draft to `.git/COMMIT_EDITMSG` for use with `git commit`.\n\n5. **Execute Commit**\n - Single commit scenario: `git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - Multiple commit scenario (if split accepted): Provide clear instructions for `git add <paths> && git commit ...` per group; execute sequentially if allowed.\n\n6. **Safe Rollback**\n - If mistakenly staged, use `git restore --staged <paths>` to unstage (command provides instructions, doesn't modify file contents).\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**: One commit does one thing, easier to trace and review.\n- **Group before committing**: Split by directory/module/feature.\n- **Clear subject**: First line ≤ 72 chars, imperative mood.\n- **Body with context**: Explain motivation, solution, and impact scope (colon-separated formats prohibited).\n- **Follow Conventional Commits**: `<type>(<scope>): <subject>`.\n\n---\n\n## Type to Emoji Mapping (When --emoji is Used)\n\n- ✨ `feat`: New feature\n- 🐛 `fix`: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)\n- 📝 `docs`: Documentation and comments\n- 🎨 `style`: Code style/formatting (no semantic changes)\n- ♻️ `refactor`: Refactoring (no new features, no bug fixes)\n- ⚡️ `perf`: Performance improvements\n- ✅ `test`: Add/fix tests, snapshots\n- 🔧 `chore`: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)\n- 👷 `ci`: CI/CD configuration and scripts\n- ⏪️ `revert`: Revert commits\n- 💥 `feat`: Breaking changes (explained in `BREAKING CHANGE:` section)\n\n> If `--type`/`--scope` is passed, it will **override** auto-detection.\n> Emoji is only included when `--emoji` flag is specified.\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **Different concerns**: Unrelated feature/module changes should be split.\n2. **Different types**: Don't mix `feat`, `fix`, `refactor` in the same commit.\n3. **File modes**: Source code vs docs/tests/configs should be grouped separately.\n4. **Size threshold**: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.\n5. **Revertability**: Ensure each commit can be independently reverted.\n\n---\n\n## Examples\n\n**Good (with --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (without --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (with Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (with BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ← (if your repo has hook errors)\n```\n\n---\n\n## Important Notes\n\n- **Git only**: No package manager/build commands (`pnpm`/`npm`/`yarn` etc.).\n- **Respects hooks**: Executes local Git hooks by default; use `--no-verify` to skip.\n- **No source code changes**: Command only reads/writes `.git/COMMIT_EDITMSG` and staging area; doesn't directly edit working directory files.\n- **Safety prompts**: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.\n- **Auditable and controllable**: If `confirm: true` is enabled, each actual `git add`/`git commit` step requires confirmation.\n","templates/skills/en/git-rollback/SKILL.md":"---\nname: git-rollback\ndescription: Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**Purpose**: Safely and visually rollback a specified branch to an older version.\nDefaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.\n\n---\n\n## Usage\n\n```bash\n# Pure interactive: list branches → select branch → list recent 20 versions → select target → choose reset or revert → confirm\n/git-rollback\n\n# Specify branch, other interactive\n/git-rollback --branch feature/calculator\n\n# Specify branch and target commit, execute with hard-reset in one go (dangerous)\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# Generate revert commit only (non-destructive rollback), preview\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| Option | Description |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| `--branch <branch>` | Branch to rollback; interactively selected if omitted. |\n| `--target <rev>` | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |\n| `--mode reset\\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default. |\n| `--depth <n>` | List recent n versions in interactive mode (default 20). |\n| `--dry-run` | **Enabled by default**, only preview commands to be executed. |\n| `--yes` | Skip all confirmations and execute directly, suitable for CI/CD scripts. |\n\n---\n\n## Interactive Flow\n\n1. **Sync remote** → `git fetch --all --prune`\n2. **List branches** → `git branch -a` (local + remote, filter protected branches)\n3. **Select branch** → User input or parameter\n4. **List versions** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **Select target** → User inputs commit hash / tag\n6. **Select mode** → `reset` or `revert`\n7. **Final confirmation** (unless `--yes`)\n8. **Execute rollback**\n - `reset`: `git switch <branch> && git reset --hard <target>`\n - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)\n\n---\n\n## Safety Guards\n\n- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.\n- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.\n- **--dry-run enabled by default**: Prevents accidental operations.\n- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.\n\n---\n\n## Use Case Examples\n\n| Scenario | Command Example |\n| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |\n| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| Research historical bugs, guide newcomers through branch history | `/git-rollback` (full interactive, dry-run) |\n\n---\n\n## Notes\n\n1. **reset vs revert**\n - **reset** changes history, requires force push and may affect other collaborators, use with caution.\n - **revert** is safer, generates new commits preserving history, but adds one more record.\n2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.\n3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.\n\n---\n","templates/skills/en/git-worktree/SKILL.md":"---\nname: git-worktree\ndescription: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\nManage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.\n\nExecute commands directly and provide concise results.\n\n---\n\n## Usage\n\n```bash\n# Basic operations\n/git-worktree add <path> # create new branch named <path> from main/master\n/git-worktree add <path> -b <branch> # create new branch with specified name\n/git-worktree add <path> -o # create and open directly in IDE\n/git-worktree list # show all worktree status\n/git-worktree remove <path> # remove specified worktree\n/git-worktree prune # clean invalid worktree references\n\n# Content migration\n/git-worktree migrate <target> --from <source> # migrate uncommitted content\n/git-worktree migrate <target> --stash # migrate stash content\n```\n\n### Options\n\n| Option | Description |\n| ------------------ | ------------------------------------------------------ |\n| `add [<path>]` | Add new worktree in `../.zcf/project-name/<path>` |\n| `migrate <target>` | Migrate content to specified worktree |\n| `list` | List all worktrees and their status |\n| `remove <path>` | Remove worktree at specified path |\n| `prune` | Clean invalid worktree references |\n| `-b <branch>` | Create new branch and checkout to worktree |\n| `-o, --open` | Open directly in IDE after creation (skip prompt) |\n| `--from <source>` | Specify migration source path (migrate only) |\n| `--stash` | Migrate current stash content (migrate only) |\n| `--track` | Set new branch to track corresponding remote branch |\n| `--guess-remote` | Auto guess remote branch for tracking |\n| `--detach` | Create detached HEAD worktree |\n| `--checkout` | Checkout immediately after creation (default behavior) |\n| `--lock` | Lock worktree after creation |\n\n---\n\n## What This Command Does\n\n1. **Environment Check**\n - Verify Git repository using `git rev-parse --is-inside-work-tree`\n - Detect whether in main repo or existing worktree for smart path calculation\n\n2. **Smart Path Management**\n - Auto-calculate project name from main repository path using worktree detection\n - Create worktrees in structured `../.zcf/project-name/<path>` directory\n - Handle both main repo and worktree execution contexts correctly\n\n```bash\n# Core path calculation logic for worktree detection\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # Check if in worktree\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # In worktree, derive main repo path from git-common-dir\n dirname \"$git_common_dir\"\n else\n # In main repository\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# Always use absolute path to prevent nesting issues\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.\n\n3. **Worktree Operations**\n - **add**: Create new worktree with smart branch/path defaults\n - **list**: Display all worktrees with branches and status\n - **remove**: Safely remove worktree and clean references\n - **prune**: Clean orphaned worktree records\n\n4. **Smart Defaults**\n - **Branch creation**: When no `-b` specified, create new branch using path name\n - **Base branch**: New branches created from main/master branch\n - **Path resolution**: Use branch name as path when unspecified\n - **IDE integration**: Auto-detect and prompt for IDE opening\n\n5. **Content Migration**\n - Migrate uncommitted changes between worktrees\n - Apply stash content to target worktree\n - Safety checks to prevent conflicts\n\n6. **Safety Features**\n - **Path conflict prevention**: Check for existing directories before creation\n - **Branch checkout validation**: Ensure branches aren't already in use\n - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree\n - **Auto-cleanup on removal**: Clean both directory and git references\n - **Clear status reporting**: Display worktree locations and branch status\n\n7. **Environment File Handling**\n - **Auto-detection**: Scan `.gitignore` for environment variable file patterns\n - **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`\n - **Exclusion logic**: Skip `.env.example` and other template files\n - **Permission preservation**: Maintain original file permissions and timestamps\n - **User feedback**: Provide clear status on copied environment files\n\n```bash\n# Environment file copying implementation\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # Check if .gitignore exists\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # Detect .env file\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ Copied .env\"\n ((copied_count++))\n fi\n \n # Detect .env.* pattern files (excluding .env.example)\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ Copied $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 Copied $copied_count environment file(s) from .gitignore\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE Integration\n\n- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **Smart prompting**: Ask to open in IDE after worktree creation\n- **Direct open**: Use `-o` flag to skip prompt and open immediately\n- **Custom configuration**: Configurable via git config\n\n### Content Migration System\n\n```bash\n# Migrate uncommitted changes\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# Migrate stash content\n/git-worktree migrate feature-ui --stash\n```\n\n**Migration Flow**:\n\n1. Verify source has uncommitted content\n2. Ensure target worktree is clean\n3. Show changes to be migrated\n4. Execute safe migration using git commands\n5. Confirm results and suggest next steps\n\n---\n\n## Examples\n\n```bash\n# Basic usage\n/git-worktree add feature-ui # create new branch 'feature-ui' from main/master\n/git-worktree add feature-ui -b my-feature # create new branch 'my-feature' with path 'feature-ui'\n/git-worktree add feature-ui -o # create and open in IDE directly\n\n# Content migration scenarios\n/git-worktree add feature-ui -b feature/new-ui # create new feature worktree\n/git-worktree migrate feature-ui --from main # migrate uncommitted changes\n/git-worktree migrate hotfix --stash # migrate stash content\n\n# Management operations\n/git-worktree list # view all worktrees\n/git-worktree remove feature-ui # remove unneeded worktree\n/git-worktree prune # clean invalid references\n```\n\n**Example Output**:\n\n```\n✅ Worktree created at ../.zcf/project-name/feature-ui\n✅ Copied .env\n✅ Copied .env.local\n📋 Copied 2 environment file(s) from .gitignore\n🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y\n🚀 Opening ../.zcf/project-name/feature-ui in VS Code...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # main project\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree management\n └── your-project/ # project worktrees\n ├── feature-ui/ # feature branch\n ├── hotfix/ # hotfix branch\n └── debug/ # debug worktree\n```\n\n---\n\n## Configuration\n\n### IDE Configuration\n\n- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim\n- Configurable via git config for custom IDEs\n- Auto-detection with priority-based selection\n\n### Custom IDE Setup\n\n```bash\n# Configure custom IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# Control auto-detection\ngit config worktree.ide.autodetect true # default\n```\n\n---\n\n## Notes\n\n- **Performance**: Worktrees share `.git` directory, saving disk space\n- **Safety**: Path conflict prevention and branch checkout validation\n- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits\n- **IDE requirement**: Command-line tools must be in PATH\n- **Cross-platform**: Supports Windows, macOS, Linux\n- **Environment files**: Automatically copies environment files listed in `.gitignore` to new worktrees\n- **File exclusions**: Template files like `.env.example` are preserved in main repo only\n\n---\n","templates/skills/en/init-project/SKILL.md":"---\nname: init-project\ndescription: Initialize project AI context, generate/update root-level and module-level CLAUDE.md indexes\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## Usage\n\n`/init-project <PROJECT_SUMMARY_OR_NAME>`\n\n## Objective\n\nInitialize project AI context using a mixed strategy of \"concise at root + detailed at module level\":\n\n- Generate/update `CLAUDE.md` at repository root (high-level vision, architecture overview, module index, global standards).\n- Generate/update local `CLAUDE.md` in identified module directories (interfaces, dependencies, entry points, tests, key files, etc.).\n- ✨ **For improved readability, automatically generate Mermaid structure diagrams in the root `CLAUDE.md` and add navigation breadcrumbs to each module `CLAUDE.md`**.\n\n## Orchestration Instructions\n\n**Step 1**: Call the `get-current-datetime` sub-agent to obtain the current timestamp.\n\n**Step 2**: Call the `init-architect` sub-agent once, with input:\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (timestamp from step 1)\n\n## Execution Strategy (Agent adapts automatically, no user parameters needed)\n\n- **Stage A: Repository Census (Lightweight)**\n Quickly count files and directories, identify module roots (package.json, pyproject.toml, go.mod, apps/_, packages/_, services/\\*, etc.).\n- **Stage B: Module Priority Scanning (Medium)**\n For each module, perform targeted reading and sampling of \"entry/interfaces/dependencies/tests/data models/quality tools\".\n- **Stage C: Deep Supplementation (As Needed)**\n If repository is small or module scale is small, expand reading scope; if large, perform batch supplemental scanning on high-risk/high-value paths.\n- **Coverage Measurement and Resumability**\n 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.\n\n## Security and Boundaries\n\n- Only read/write documentation and indexes, do not modify source code.\n- Ignore common generated artifacts and binary large files by default.\n- Print \"summary\" in main dialog, write full content to repository.\n\n## Output Requirements\n\n- Print \"Initialization Result Summary\" in main dialog, including:\n - Whether root-level `CLAUDE.md` was created/updated, major section overview.\n - Number of identified modules and their path list.\n - Generation/update status of each module's `CLAUDE.md`.\n - ✨ **Explicitly mention \"Generated Mermaid structure diagram\" and \"Added navigation breadcrumbs for N modules\"**.\n - Coverage and major gaps.\n - If not fully read: explain \"why stopped here\" and list **recommended next steps** (e.g., \"suggest priority supplemental scanning: packages/auth/src/controllers\").\n","templates/skills/en/workflow/SKILL.md":"---\nname: workflow\ndescription: 'Professional AI programming assistant with structured workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) for developers'\ndisable-model-invocation: true\n---\n\n# Workflow - Professional Development Assistant\n\nExecute structured development workflow with quality gates and MCP service integration.\n\n## Usage\n\n```bash\n/workflow <TASK_DESCRIPTION>\n```\n\n## Context\n\n- Task to develop: $ARGUMENTS\n- Structured 6-phase workflow with quality gates\n- Professional developer-focused interaction\n- MCP service integration for enhanced capabilities\n\n## Your Role\n\nYou are a professional AI programming assistant following a structured core workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) to assist users. Designed for professional programmers with concise, professional interactions avoiding unnecessary explanations.\n\n## Communication Guidelines\n\n1. Responses start with mode tag `[Mode: X]`, initially `[Mode: Research]`\n2. Core workflow strictly follows `Research -> Ideate -> Plan -> Execute -> Optimize -> Review` sequence, users can command jumps\n\n## Core Workflow Details\n\n### 1. `[Mode: Research]` - Requirement Understanding\n\n- Analyze and understand user requirements\n- Evaluate requirement completeness (0-10 score), actively request key information when below 7\n- Gather necessary context and constraints\n- Identify key objectives and success criteria\n\n### 2. `[Mode: Ideate]` - Solution Design\n\n- Provide at least two feasible solutions with evaluation (e.g., `Solution 1: Description`)\n- Compare pros/cons of each approach\n- Recommend optimal solution based on requirements\n\n### 3. `[Mode: Plan]` - Detailed Planning\n\n- Break down selected solution into detailed, ordered, executable step list\n- Include atomic operations: files, functions/classes, logic overview\n- Define expected results for each step\n- Use `Context7` for new library queries\n- Do not write complete code at this stage\n- Request user approval after completion\n\n### 4. `[Mode: Execute]` - Implementation\n\n- Store plan summary (with context and plan) in project root directory `.zcf/plan/current/task-name.md`\n- Must have user approval before execution\n- Strictly follow the plan for coding implementation\n- Request user feedback after key steps and completion\n\n### 5. `[Mode: Optimize]` - Code Optimization\n\n- Automatically enter this mode after `[Mode: Execute]` completion\n- Automatically check and analyze implemented code (only code generated in current conversation)\n- Focus on redundant, inefficient, garbage code\n- Provide specific optimization suggestions (with reasons and expected benefits)\n- Execute optimization after user confirmation\n\n### 6. `[Mode: Review]` - Quality Assessment\n\n- Evaluate execution results against the plan\n- Report issues and suggestions\n- Request user confirmation after completion\n\n## Timestamp Acquisition Rules\n\nDuring workflow execution, any scenario requiring current timestamp must obtain accurate time via bash command. Guessing or fabricating time is prohibited.\n\nBasic Commands:\n- Default format: `date +'%Y-%m-%d %H:%M:%S'`\n- Filename format: `date +'%Y-%m-%d_%H%M%S'`\n- Readable format: `date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO format: `date +'%Y-%m-%dT%H:%M:%S%z'`\n\nTypical Use Cases:\n- Updating timestamp fields in documents\n- Naming task plan documents during archiving (when moving from `.zcf/plan/current/` to `.zcf/plan/history/`)\n- Any other scenario requiring current time recording\n\n## Interactive Feedback & MCP Services\n\n### Interactive Feedback Rules\n\n1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, must request user confirmation\n2. When receiving user feedback, if feedback content is not empty, must request user confirmation again and adjust behavior based on feedback\n3. Only when user explicitly indicates \"end\" or \"no more interaction needed\" can stop requesting user confirmation, process is considered complete\n4. Unless receiving termination instructions, all steps must repeatedly request user confirmation\n5. Before completing tasks, must request user confirmation and ask for user feedback\n\n---\n\n## Execute Workflow\n\n**Task Description**: $ARGUMENTS\n\nStarting structured development workflow with quality gates...\n\n### 🔍 Phase 1: Research & Analysis\n\n[Mode: Research] - Understanding requirements and gathering context:\n\n#### Requirement Completeness Scoring (0-10 points)\n\nScoring Dimensions:\n\n- **Goal Clarity** (0-3 points): Are task objectives clear and specific, what problem to solve?\n- **Expected Results** (0-3 points): Are success criteria and deliverables clearly defined?\n- **Scope Boundaries** (0-2 points): Are task scope and boundaries clear?\n- **Constraints** (0-2 points): Are time, performance, business limits specified?\n\nNote: Technical stack, framework versions will be identified from project automatically, not included in scoring\n\n**Scoring Rules**:\n\n- 9-10 points: Requirements very complete, can proceed directly\n- 7-8 points: Requirements basically complete, suggest adding minor details\n- 5-6 points: Requirements have significant gaps, must supplement key information\n- 0-4 points: Requirements too vague, needs redescription\n\n**When score is below 7, proactively ask supplementary questions**:\n\n- Identify missing key information dimensions\n- Ask 1-2 specific questions for each missing dimension\n- Provide examples to help users understand needed information\n- Re-score after user supplements information\n\n**Scoring Example**:\n\n```\nUser Request: \"Help me optimize code\"\nScoring Analysis:\n- Goal Clarity: 0/3 points (doesn't specify what code or what problem)\n- Expected Results: 0/3 points (no success criteria or expected effect defined)\n- Scope Boundaries: 1/2 points (only knows code optimization, but scope unclear)\n- Constraints: 0/2 points (no performance metrics or time limits)\nTotal Score: 1/10 - Requires significant information\n\nQuestions to Ask:\n1. Which file or module's code do you want to optimize?\n2. What specific problem needs optimization?\n3. What effect do you expect after optimization (e.g., response time improvement, code reduction)?\n4. Are there specific performance metrics or time requirements?\n```\n\n**Common Supplementary Question Templates**:\n\n- Goal: \"What specific functionality/effect do you want?\" \"What's the current problem?\"\n- Results: \"How to determine task success?\" \"What's the expected output/effect?\"\n- Scope: \"Which specific files/modules to handle?\" \"What should be excluded?\"\n- Constraints: \"What are the time requirements?\" \"Any business limitations or performance requirements?\"\n\n**Auto-detected Project Information** (no need to ask):\n\n- Tech stack (from AGENTS.md, CLAUDE.md, package.json, requirements.txt, etc.)\n- Framework versions (from AGENTS.md, CLAUDE.md, config files)\n- Project structure (from file system)\n- Existing code conventions (from AGENTS.md, CLAUDE.md, config files and existing code)\n- Development commands (from AGENTS.md, CLAUDE.md, such as build, test, typecheck)\n\n#### Execution Steps\n\n- Analyze task requirements and constraints\n- Perform requirement completeness scoring (show specific scores)\n- Identify key objectives and success criteria\n- Gather necessary technical context\n- Use MCP services for additional information if needed\n\n### 💡 Phase 2: Solution Ideation\n\n[Mode: Ideate] - Designing solution approaches:\n\n- Generate multiple feasible solutions\n- Evaluate pros and cons of each approach\n- Provide detailed comparison and recommendation\n- Consider technical constraints and best practices\n- Request user approval before proceeding\n\n### 📋 Phase 3: Detailed Planning\n\n[Mode: Plan] - Creating execution roadmap:\n\n- Break down solution into atomic, executable steps\n- Define file structure, functions/classes, and logic overview\n- Specify expected results for each step\n- Query new libraries using Context7 if needed\n- Request user approval before proceeding\n\n### ⚡ Phase 4: Implementation\n\n[Mode: Execute] - Code development:\n\n- Store execution plan in project root directory `.zcf/plan/current/task-name.md`\n- Implement according to approved plan\n- Follow development best practices\n- Add usage methods before import statements (critical rule)\n- Request feedback at key milestones\n\n### 🚀 Phase 5: Code Optimization\n\n[Mode: Optimize] - Quality improvement:\n\n- Automatically analyze implemented code\n- Identify redundant, inefficient, or problematic code\n- Provide specific optimization recommendations\n- Execute improvements after user confirmation\n\n### ✅ Phase 6: Quality Review\n\n[Mode: Review] - Final assessment:\n\n- Compare results against original plan\n- Identify any remaining issues or improvements\n- Provide completion summary and recommendations\n- Request final user confirmation\n- After task completion, move plan file from `.zcf/plan/current/` to `.zcf/plan/history/` for archiving\n- Rename to `[Finish Time]task-name.md` during archiving for tracking, Finish Time format is `YYYY-MM-DD_HHMMSS`\n\n## Expected Output Structure\n\n```\nproject/ # Project root directory\n├── .zcf/\n│ └── plan/\n│ ├── current/ # Current ongoing tasks\n│ │ └── task-name.md # Execution plan and context\n│ └── history/ # Completed historical tasks\n│ └── [Finish Time]task-name.md # Archived task records\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**Begin execution with the provided task description and report progress after each phase completion.**\n","templates/skills/zh-CN/bmad-init/SKILL.md":"---\nname: bmad-init\ndescription: 在项目中初始化或更新 BMad-Method (V6)\ndisable-model-invocation: true\n---\n\n# /bmad-init 命令\n\n此命令在您的项目中初始化或更新 BMad-Method (V6)。\n\n## 当调用此命令时：\n\n1. 检查 `_bmad/` 目录是否存在，判断 BMad V6 是否已安装\n2. 检查是否存在旧版 V4 安装（`.bmad-core` 或 `.bmad-method` 目录）\n3. 新安装执行：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n4. 已安装则执行：`npx bmad-method install --directory . --action quick-update --yes`\n5. 修复安装器 bug：将 `{output_folder}` 重命名为 `_bmad-output`（Beta 已知问题）\n6. 自动更新 `.gitignore`（移除 V4 条目，添加 V6 条目）\n7. 显示安装结果并提示用户后续操作\n\n## 实现\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// 需要从 .gitignore 清理的旧条目\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug 产物\n]\n\n// V6 新版 .gitignore 条目\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// 修复安装器 bug: {output_folder} 未解析为 _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output 不存在，直接重命名\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (重命名)')\n } else {\n // _bmad-output 已存在，合并子目录后删除\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ 移动 ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ 已删除多余的 {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // 移除 V4 旧条目\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ 移除旧条目: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // 添加 V6 新条目\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ 添加新条目: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore 已是最新，无需更新')\n return\n }\n\n // 构建新内容\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // 确保末尾有换行，然后添加 BMad 区块\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore 已${exists ? '更新' : '创建'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // 检查旧版 V4 安装\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ 检测到旧版 BMad V4 安装：')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 核心目录)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 方法目录)')\n console.log('')\n console.log('📌 V6 安装器会自动处理旧版迁移，请在安装过程中按提示操作。')\n console.log(' 详情参考：https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // 检查 V6 是否已安装\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // 构建非交互式安装命令\n let installCmd\n if (hasV6) {\n console.log('🔄 检测到已有 BMad V6 安装，将执行快速更新...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 正在初始化 BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language Chinese',\n '--document-output-language Chinese',\n '--yes',\n ].join(' ')\n }\n\n // 执行安装\n try {\n console.log(`📋 执行: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 安装/更新完成！')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 重要提示：请重启 AI IDE 以加载 BMad 扩展')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // 修复 {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 检查安装器已知问题...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ 无需修复')\n } catch (err) {\n console.log(` ⚠️ 修复 {output_folder} 失败: ${err.message}`)\n console.log(' 请手动将 {output_folder}/ 重命名为 _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 目录结构：')\n console.log(' • _bmad/ — agents、workflows、tasks 和配置')\n console.log(' • _bmad-output/ — 生成的工件输出目录')\n console.log('')\n\n // 自动更新 .gitignore\n console.log('🔧 更新 .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ 自动更新 .gitignore 失败，请手动添加 _bmad/ 和 _bmad-output/')\n }\n console.log('')\n console.log('🚀 快速开始：')\n console.log(' 1. 重启 AI IDE')\n console.log(' 2. 运行 /bmad-help 获取引导和下一步建议')\n console.log(' 3. 输入 /bmad 并使用自动补全浏览可用命令')\n console.log('')\n console.log('💡 常用工作流：')\n console.log(' • /bmad-help — 交互式帮助')\n console.log(' • /bmad-bmm-create-prd — 创建产品需求文档')\n console.log(' • /bmad-bmm-create-architecture — 创建架构文档')\n console.log(' • /bmad-bmm-create-epics-and-stories — 创建史诗和用户故事')\n console.log(' • /bmad-bmm-sprint-planning — 初始化 Sprint 计划')\n console.log(' • /bmad-bmm-dev-story — 实现用户故事')\n\n // 清理旧版 V4 IDE 命令提醒\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ 检测到旧版 V4 IDE 命令，建议手动删除：')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' 新的 V6 命令已安装在 .claude/commands/bmad/ 下')\n }\n }\n catch (error) {\n console.error('❌ 安装失败：', error.message)\n console.log('')\n console.log('🛠️ 手动安装指南：')\n console.log(' 1. 确保已安装 Node.js 20+')\n console.log(' 2. 非交互式安装：')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes')\n console.log(' 3. 快速更新已有安装：')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. 或交互式安装：')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 详细文档：')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// 执行初始化\ninitBmad()\n```\n\n## 用法\n\n只需在 Claude Code 中键入：\n\n```\n/bmad-init\n```\n\n此命令将：\n\n1. 检测现有安装状态（V6 / V4 旧版 / 未安装）\n2. 新安装：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n3. 已安装：`npx bmad-method install --directory . --action quick-update --yes`\n4. 修复 `{output_folder}` → `_bmad-output` 安装器 bug\n5. 自动更新 `.gitignore`（清理旧条目，添加 V6 条目）\n6. 提供后续步骤建议\n","templates/skills/zh-CN/feat/SKILL.md":"---\nname: feat\ndescription: '用于新增功能开发的命令，支持完整的开发流程和工具集成'\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## 核心工作流程\n\n### 1. 输入分析与类型判断\n\n每次收到用户输入时，首先进行类型判断并明确告知用户：\n\n**判断标准：**\n\n- **需求规划类型**: 用户提出新功能需求、项目构想或需要制定计划\n\n- **讨论迭代类型**: 用户要求继续讨论、修改或完善已有规划\n\n- **执行实施类型**: 用户确认规划完成，要求开始具体实施工作\n\n### 2. 分类处理机制\n\n#### A. 需求规划处理\n\n**触发条件**: 识别为功能需求输入\n\n**执行动作**:\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 将文档存储至 `./.claude/plan` 目录，并以 plan/xxx.md 的格式命名\n\n- 包含：目标定义、功能分解、实施步骤、验收标准\n\n#### B. 讨论迭代处理\n\n**触发条件**: 用户要求继续讨论或修改规划\n\n**执行动作**:\n\n- 检索并分析上次生成的规划文件\n\n- 识别用户反馈和确认内容\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 建立一个新的文档，比如上一次是 plan/xxx.md，那么这次就是 plan/xxx-1.md，如果上一次是 plan/xxx-1.md，那么这次就是 plan/xxx-2.md，以此类推\n\n- 重新组织待实施任务优先级\n\n#### C. 执行实施处理\n\n**触发条件**: 用户确认规划完成，要求开始执行\n\n**执行动作**:\n\n- 按规划文档顺序启动任务执行\n\n- 每个子任务开始前进行任务类型识别\n\n- **前端任务特殊处理**:\n\n- 检查是否存在可用 UI 设计\n\n- 如无设计方案，must use UI-UX-Designer Agent\n\n- 完成 UI 设计后再进行开发实施\n\n### 3. 关键执行原则\n\n#### 强制响应要求\n\n- **每次交互必须首先说明**: \"我判断此次操作类型为：[具体类型]\"\n\n- 类型判断必须准确且明确传达给用户\n\n#### 任务执行规范\n\n- 严格按照文档化规划执行\n\n- 子任务启动前必须明确任务性质和依赖关系\n\n- 前端任务必须确保 UI 设计完整性\n\n#### 状态管理机制\n\n- 维护任务完成状态跟踪\n\n- 及时更新规划文档状态\n\n- 确保用户对进度的可见性\n\n## 质量保证要点\n\n1. **类型判断准确性**: 每次交互开始的类型识别必须准确\n\n2. **文档一致性**: 规划文档与实际执行保持同步\n\n3. **依赖关系管理**: 特别关注前端任务的 UI 设计依赖\n\n4. **用户沟通透明**: 所有判断和动作都要明确告知用户\n","templates/skills/zh-CN/git-clean-branches/SKILL.md":"---\nname: git-clean-branches\ndescription: 安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\n该命令**安全地**识别并清理**已合并**或**长期未更新 (stale)** 的 Git 分支。\n默认以**只读预览 (`--dry-run`)** 模式运行，需明确指令才会执行删除操作。\n\n---\n\n## Usage\n\n```bash\n# [最安全] 预览将要清理的分支，不执行任何删除\n/git-cleanBranches --dry-run\n\n# 清理已合并到 main 且超过 90 天未动的本地分支 (需逐一确认)\n/git-cleanBranches --stale 90\n\n# 清理已合并到 release/v2.1 的本地与远程分支 (自动确认)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [危险] 强制删除一个未合并的本地分支\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。\n- `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。\n- `--remote`：同时清理远程已合并/过期的分支。\n- `--dry-run`：**默认行为**。仅列出将要删除的分支，不执行任何操作。\n- `--yes`：跳过逐一确认的步骤，直接删除所有已识别的分支（适合 CI/CD）。\n- `--force`：使用 `-D` 强制删除本地分支（即使未合并）。\n\n---\n\n## What This Command Does\n\n1. **配置与安全预检**\n - **更新信息**：自动执行 `git fetch --all --prune`，确保分支状态最新。\n - **读取保护分支**：从 Git 配置读取不应被清理的分支列表（见下文“Configuration”）。\n - **确定基准**：使用 `--base` 参数或自动识别的 `main`/`master` 作为比较基准。\n\n2. **分析识别（Find）**\n - **已合并分支**：找出已完全合并到 `--base` 的本地（及远程，如加 `--remote`）分支。\n - **过期分支**：如指定 `--stale <days>`，找出最后一次提交在 N 天前的分支。\n - **排除保护分支**：从待清理列表中移除所有已配置的保护分支。\n\n3. **报告预览（Report）**\n - 清晰列出“将要删除的已合并分支”与“将要删除的过期分支”。\n - 若无 `--yes` 参数，**命令到此结束**，等待用户确认后再次执行（不带 `--dry-run`）。\n\n4. **执行清理（Execute）**\n - **仅在不带 `--dry-run` 且用户确认后**（或带 `--yes`）执行。\n - 逐一删除已识别的分支，除非用户在交互式确认中选择跳过。\n - 本地用 `git branch -d <branch>`；远程用 `git push origin --delete <branch>`。\n - 若指定 `--force`，本地删除会改用 `git branch -D <branch>`。\n\n---\n\n## Configuration (一次配置，永久生效)\n\n为防止误删重要分支（如 `develop`, `release/*`），请在仓库的 Git 配置中添加保护规则。命令会自动读取。\n\n```bash\n# 保护 develop 分支\ngit config --add branch.cleanup.protected develop\n\n# 保护所有 release/ 开头的分支 (通配符)\ngit config --add branch.cleanup.protected 'release/*'\n\n# 查看所有已配置的保护分支\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **优先 `--dry-run`**：养成先预览再执行的习惯。\n- **活用 `--base`**：维护长期 `release` 分支时，用它来清理已合并到该 release 的 `feature` 或 `hotfix` 分支。\n- **谨慎 `--force`**：除非你百分百确定某个未合并分支是无用功，否则不要强制删除。\n- **团队协作**：在清理共享的远程分支前，先在团队频道通知一声。\n- **定期运行**：每月或每季度运行一次，保持仓库清爽。\n\n---\n\n## Why This Version Is Better\n\n- ✅ **更安全**：默认只读预览，且有可配置的保护分支列表。\n- ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。\n- ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。\n- ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。\n- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。\n","templates/skills/zh-CN/git-commit/SKILL.md":"---\nname: git-commit\ndescription: 仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过）\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\n该命令在**不依赖任何包管理器/构建工具**的前提下，仅通过 **Git**：\n\n- 读取改动（staged/unstaged）\n- 判断是否需要**拆分为多次提交**\n- 为每个提交生成 **Conventional Commits** 风格的信息（可选 emoji）\n- 按需执行 `git add` 与 `git commit`（默认运行本地 Git 钩子；可 `--no-verify` 跳过）\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`：跳过本地 Git 钩子（`pre-commit`/`commit-msg` 等）。\n- `--all`：当暂存区为空时，自动 `git add -A` 将所有改动纳入本次提交。\n- `--amend`：在不创建新提交的情况下**修补**上一次提交（保持提交作者与时间，除非本地 Git 配置另有指定）。\n- `--signoff`：附加 `Signed-off-by` 行（遵循 DCO 流程时使用）。\n- `--emoji`：在提交信息中包含 emoji 前缀（省略则使用纯文本）。\n- `--scope <scope>`：指定提交作用域（如 `ui`、`docs`、`api`），写入消息头部。\n- `--type <type>`：强制提交类型（如 `feat`、`fix`、`docs` 等），覆盖自动判断。\n\n> 注：如框架不支持交互式确认，可在 front-matter 中开启 `confirm: true` 以避免误操作。\n\n---\n\n## What This Command Does\n\n1. **仓库/分支校验**\n - 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库。\n - 读取当前分支/HEAD 状态；如处于 rebase/merge 冲突状态，先提示处理冲突后再继续。\n\n2. **改动检测**\n - 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动。\n - 若已暂存文件为 0：\n - 若传入 `--all` → 执行 `git add -A`。\n - 否则提示你选择：继续仅分析未暂存改动并给出**建议**，或取消命令后手动分组暂存。\n\n3. **拆分建议（Split Heuristics）**\n - 按**关注点**、**文件模式**、**改动类型**聚类（示例：源代码 vs 文档、测试；不同目录/包；新增 vs 删除）。\n - 若检测到**多组独立变更**或 diff 规模过大（如 > 300 行 / 跨多个顶级目录），建议拆分提交，并给出每一组的 pathspec（便于后续执行 `git add <paths>`）。\n\n4. **提交信息生成（Conventional 规范，可选 Emoji）**\n - 自动推断 `type`（`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert` …）与可选 `scope`。\n - 生成消息头：`[<emoji>] <type>(<scope>)?: <subject>`（首行 ≤ 72 字符，祈使语气，仅在使用 `--emoji` 时包含 emoji）。\n - 生成消息体：\n - 必须在 subject 之后空一行。\n - 使用列表格式，每项以 `-` 开头。\n - 每项**必须使用动词开头的祈使句**（如 \"add…\"、\"fix…\"、\"update…\"）。\n - **禁止使用冒号分隔的格式**（如 ~~\"Feature: description\"~~、~~\"Impl: content\"~~）。\n - 说明变更的动机、实现要点或影响范围（3 项以内为宜）。\n - 生成消息脚注（如有）：\n - 必须在 Body 之后空一行。\n - **BREAKING CHANGE**：若存在破坏性变更，必须包含 `BREAKING CHANGE: <description>`，或在类型后添加感叹号（如 `feat!:`）。\n - 其它脚注采用 git trailer 格式（如 `Closes #123`、`Refs: #456`、`Reviewed-by: Name`）。\n - 根据 Git 历史提交的主要语言选择提交信息语言。优先检查最近提交主题（例如 `git log -n 50 --pretty=%s`）判断中文/英文；若无法判断，则回退到仓库主要语言或英文。\n - 将草稿写入 `.git/COMMIT_EDITMSG`，并用于 `git commit`。\n\n5. **执行提交**\n - 单提交场景：`git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - 多提交场景（如接受拆分建议）：按分组给出 `git add <paths> && git commit ...` 的明确指令；若允许执行则逐一完成。\n\n6. **安全回滚**\n - 如误暂存，可用 `git restore --staged <paths>` 撤回暂存（命令会给出指令，不修改文件内容）。\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**：一次提交只做一件事，便于回溯与审阅。\n- **先分组再提交**：按目录/模块/功能点拆分。\n- **清晰主题**：首行 ≤ 72 字符，祈使语气。\n- **正文含上下文**：说明动机、方案、影响范围（禁止冒号分隔格式）。\n- **遵循 Conventional Commits**：`<type>(<scope>): <subject>`。\n\n---\n\n## Type 与 Emoji 映射（使用 --emoji 时）\n\n- ✨ `feat`：新增功能\n- 🐛 `fix`：缺陷修复（含 🔥 删除代码/文件、🚑️ 紧急修复、👽️ 适配外部 API 变更、🔒️ 安全修复、🚨 解决告警、💚 修复 CI）\n- 📝 `docs`：文档与注释\n- 🎨 `style`：风格/格式（不改语义）\n- ♻️ `refactor`：重构（不新增功能、不修缺陷）\n- ⚡️ `perf`：性能优化\n- ✅ `test`：新增/修复测试、快照\n- 🔧 `chore`：构建/工具/杂务（合并分支、更新配置、发布标记、依赖 pin、.gitignore 等）\n- 👷 `ci`：CI/CD 配置与脚本\n- ⏪️ `revert`：回滚提交\n- 💥 `feat`：破坏性变更（`BREAKING CHANGE:` 段落中说明）\n\n> 若传入 `--type`/`--scope`，将**覆盖**自动推断。\n> 仅在指定 `--emoji` 标志时才会包含 emoji。\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **不同关注点**：互不相关的功能/模块改动应拆分。\n2. **不同类型**：不要将 `feat`、`fix`、`refactor` 混在同一提交。\n3. **文件模式**：源代码 vs 文档/测试/配置分组提交。\n4. **规模阈值**：超大 diff（示例：>300 行或跨多个顶级目录）建议拆分。\n5. **可回滚性**：确保每个提交可独立回退。\n\n---\n\n## Examples\n\n**Good (使用 --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (不使用 --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (包含 Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (包含 BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ←（如你的仓库有钩子报错）\n```\n\n---\n\n## Important Notes\n\n- **仅使用 Git**：不调用任何包管理器/构建命令（无 `pnpm`/`npm`/`yarn` 等）。\n- **尊重钩子**：默认执行本地 Git 钩子；使用 `--no-verify` 可跳过。\n- **不改源码内容**：命令只读写 `.git/COMMIT_EDITMSG` 与暂存区；不会直接编辑工作区文件。\n- **安全提示**：在 rebase/merge 冲突、detached HEAD 等状态下会先提示处理/确认再继续。\n- **可审可控**：如开启 `confirm: true`，每个实际 `git add`/`git commit` 步骤都会进行二次确认。\n","templates/skills/zh-CN/git-rollback/SKILL.md":"---\nname: git-rollback\ndescription: 交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**目的**：安全、可视地将指定分支回滚到旧版本。\n默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。\n\n---\n\n## Usage\n\n```bash\n# 纯交互：列出分支 → 选分支 → 列最近 20 个版本 → 选目标 → 选择 reset 或 revert → 二次确认\n/git-rollback\n\n# 指定分支，其他交互\n/git-rollback --branch feature/calculator\n\n# 指定分支与目标 commit，并用 hard‑reset 一键执行（危险）\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# 只想生成 revert 提交（非破坏式回滚），预览即可\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| 选项 | 说明 |\n| ---------------------- | ---------------------------------------------------------------------------------- |\n| `--branch <branch>` | 要回滚的分支；缺省时交互选择。 |\n| `--target <rev>` | 目标版本（commit Hash、Tag、reflog 引用都行）；缺省时交互选择近 `--depth` 条记录。 |\n| `--mode reset\\|revert` | `reset`：硬回滚历史；`revert`：生成反向提交保持历史完整。默认询问。 |\n| `--depth <n>` | 在交互模式下列出最近 n 个版本（默认 20）。 |\n| `--dry-run` | **默认开启**，只预览即将执行的命令。 |\n| `--yes` | 跳过所有确认直接执行，适合 CI/CD 脚本。 |\n\n---\n\n## 交互流程\n\n1. **同步远端** → `git fetch --all --prune`\n2. **列分支** → `git branch -a`（本地＋远端，过滤受保护分支）\n3. **选分支** → 用户输入或传参\n4. **列版本** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **选目标** → 用户输入 commit hash / tag\n6. **选模式** → `reset` 或 `revert`\n7. **最终确认** （除非 `--yes`）\n8. **执行回滚**\n - `reset`：`git switch <branch> && git reset --hard <target>`\n - `revert`：`git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **推送建议** → 提示是否 `git push --force-with-lease`（reset）或普通 `git push`（revert）\n\n---\n\n## 安全护栏\n\n- **备份**：执行前自动在 reflog 中记录当前 HEAD，可用 `git switch -c backup/<timestamp>` 恢复。\n- **保护分支**：如检测到 `main` / `master` / `production` 等受保护分支且开启 `reset` 模式，将要求额外确认。\n- **--dry-run 默认开启**：防止误操作。\n- **--force 禁止**：不提供 `--force`；如需强推，请手动输入 `git push --force-with-lease`。\n\n---\n\n## 适用场景示例\n\n| 场景 | 调用示例 |\n| ----------------------------------------------- | ---------------------------------------------------------------- |\n| 热修补丁上线后发现 bug，需要回到 Tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| 运维同事误推了 debug 日志提交，需要生成反向提交 | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| 调研历史 bug，引导新人浏览分支历史 | `/git-rollback` （全交互，dry‑run） |\n\n---\n\n## 注意\n\n1. **reset vs revert**\n - **reset** 会改变历史，需要强推并可能影响其他协作者，谨慎使用。\n - **revert** 更安全，生成新提交保留历史，但会增加一次记录。\n2. **嵌入式仓库** 常有大体积二进制文件；回滚前请确保 LFS/子模块状态一致。\n3. 若仓库启用了 CI 强制校验，回滚后可能自动触发流水线；确认管控策略以免误部署旧版本。\n\n---\n","templates/skills/zh-CN/git-worktree/SKILL.md":"---\nname: git-worktree\ndescription: 管理 Git worktree，在项目平级的 ../.zcf/项目名/ 目录下创建，支持智能默认、IDE 集成和内容迁移\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\n管理 Git worktree，支持智能默认、IDE 集成和内容迁移，使用结构化的 `../.zcf/项目名/` 路径。\n\n直接执行命令并提供简洁结果。\n\n---\n\n## Usage\n\n```bash\n# 基本操作\n/git-worktree add <path> # 从 main/master 创建名为 <path> 的新分支\n/git-worktree add <path> -b <branch> # 创建指定名称的新分支\n/git-worktree add <path> -o # 创建并直接用 IDE 打开\n/git-worktree list # 显示所有 worktree 状态\n/git-worktree remove <path> # 删除指定的 worktree\n/git-worktree prune # 清理无效 worktree 记录\n\n# 内容迁移\n/git-worktree migrate <target> --from <source> # 迁移未提交内容\n/git-worktree migrate <target> --stash # 迁移 stash 内容\n```\n\n### Options\n\n| 选项 | 说明 |\n| ------------------ | -------------------------------------------- |\n| `add [<path>]` | 在 `../.zcf/项目名/<path>` 添加新的 worktree |\n| `migrate <target>` | 迁移内容到指定 worktree |\n| `list` | 列出所有 worktree 及其状态 |\n| `remove <path>` | 删除指定路径的 worktree |\n| `prune` | 清理无效的 worktree 引用 |\n| `-b <branch>` | 创建新分支并检出到 worktree |\n| `-o, --open` | 创建成功后直接用 IDE 打开（跳过询问） |\n| `--from <source>` | 指定迁移源路径（migrate 专用） |\n| `--stash` | 迁移当前 stash 内容（migrate 专用） |\n| `--track` | 设置新分支跟踪对应的远程分支 |\n| `--guess-remote` | 自动猜测远程分支进行跟踪 |\n| `--detach` | 创建分离 HEAD 的 worktree |\n| `--checkout` | 创建后立即检出（默认行为） |\n| `--lock` | 创建后锁定 worktree |\n\n---\n\n## What This Command Does\n\n1. **环境检查**\n - 通过 `git rev-parse --is-inside-work-tree` 验证 Git 仓库\n - 检测是否在主仓库或现有 worktree 中，进行智能路径计算\n\n2. **智能路径管理**\n - 使用 worktree 检测自动从主仓库路径计算项目名\n - 在结构化的 `../.zcf/项目名/<path>` 目录创建 worktree\n - 正确处理主仓库和 worktree 执行上下文\n\n```bash\n# worktree 检测的核心路径计算逻辑\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # 检测是否在 worktree 中\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # 在 worktree 中，从 git-common-dir 推导主仓库路径\n dirname \"$git_common_dir\"\n else\n # 在主仓库中\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# 始终使用绝对路径防止嵌套问题\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**关键修复**: 在现有 worktree 内创建新 worktree 时，始终使用绝对路径以防止出现类似 `../.zcf/project/.zcf/project/path` 的路径嵌套问题。\n\n3. **Worktree 操作**\n - **add**: 使用智能分支/路径默认创建新 worktree\n - **list**: 显示所有 worktree 的分支和状态\n - **remove**: 安全删除 worktree 并清理引用\n - **prune**: 清理孤立的 worktree 记录\n\n4. **智能默认**\n - **分支创建**: 未指定 `-b` 时，使用路径名创建新分支\n - **基础分支**: 新分支从 main/master 分支创建\n - **路径解析**: 未指定路径时使用分支名作为路径\n - **IDE 集成**: 自动检测并提示 IDE 打开\n\n5. **内容迁移**\n - 在 worktree 之间迁移未提交改动\n - 将 stash 内容应用到目标 worktree\n - 安全检查防止冲突\n\n6. **安全特性**\n - **路径冲突防护**: 创建前检查目录是否已存在\n - **分支检出验证**: 确保分支未被其他地方使用\n - **绝对路径强制**: 防止在 worktree 内创建嵌套的 `.zcf` 目录\n - **删除时自动清理**: 同时清理目录和 git 引用\n - **清晰的状态报告**: 显示 worktree 位置和分支状态\n\n7. **环境文件处理**\n - **自动检测**: 扫描 `.gitignore` 文件中的环境变量文件模式\n - **智能复制**: 复制 `.gitignore` 中列出的 `.env` 和 `.env.*` 文件\n - **排除逻辑**: 跳过 `.env.example` 等模板文件\n - **权限保护**: 保持原始文件权限和时间戳\n - **用户反馈**: 提供已复制环境文件的清晰状态信息\n\n```bash\n# 环境文件复制实现\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # 检查 .gitignore 是否存在\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # 检测 .env 文件\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ 已复制 .env\"\n ((copied_count++))\n fi\n \n # 检测 .env.* 模式文件（排除 .env.example）\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ 已复制 $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 已从 .gitignore 复制 $copied_count 个环境文件\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE 集成\n\n- **自动检测**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **智能提示**: 创建 worktree 后询问是否在 IDE 中打开\n- **直接打开**: 使用 `-o` 标志跳过提示直接打开\n- **自定义配置**: 通过 git config 配置\n\n### 内容迁移系统\n\n```bash\n# 迁移未提交改动\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# 迁移 stash 内容\n/git-worktree migrate feature-ui --stash\n```\n\n**迁移流程**:\n\n1. 验证源有未提交内容\n2. 确保目标 worktree 干净\n3. 显示即将迁移的改动\n4. 使用 git 命令安全迁移\n5. 确认结果并建议后续步骤\n\n---\n\n## Examples\n\n```bash\n# 基本用法\n/git-worktree add feature-ui # 从 main/master 创建新分支 'feature-ui'\n/git-worktree add feature-ui -b my-feature # 创建新分支 'my-feature'，路径为 'feature-ui'\n/git-worktree add feature-ui -o # 创建并直接用 IDE 打开\n\n# 内容迁移场景\n/git-worktree add feature-ui -b feature/new-ui # 创建新功能 worktree\n/git-worktree migrate feature-ui --from main # 迁移未提交改动\n/git-worktree migrate hotfix --stash # 迁移 stash 内容\n\n# 管理操作\n/git-worktree list # 查看所有 worktree\n/git-worktree remove feature-ui # 删除不需要的 worktree\n/git-worktree prune # 清理无效引用\n```\n\n**示例输出**:\n\n```\n✅ Worktree created at ../.zcf/项目名/feature-ui\n✅ 已复制 .env\n✅ 已复制 .env.local\n📋 已从 .gitignore 复制 2 个环境文件\n🖥️ 是否在 IDE 中打开 ../.zcf/项目名/feature-ui？[y/n]: y\n🚀 正在用 VS Code 打开 ../.zcf/项目名/feature-ui...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # 主项目\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree 管理\n └── your-project/ # 项目 worktree\n ├── feature-ui/ # 功能分支\n ├── hotfix/ # 修复分支\n └── debug/ # 调试 worktree\n```\n\n---\n\n## Configuration\n\n### IDE 配置\n\n- 支持 VS Code、Cursor、WebStorm、Sublime Text、Vim\n- 通过 git config 配置自定义 IDE\n- 基于优先级的自动检测选择\n\n### 自定义 IDE 设置\n\n```bash\n# 配置自定义 IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# 控制自动检测\ngit config worktree.ide.autodetect true # 默认\n```\n\n---\n\n## Notes\n\n- **性能**: worktree 共享 `.git` 目录，节省磁盘空间\n- **安全**: 路径冲突防护和分支检出验证\n- **迁移**: 仅限未提交改动；已提交内容需使用 `git cherry-pick`\n- **IDE 要求**: 命令行工具必须在 PATH 中\n- **跨平台**: 支持 Windows、macOS、Linux\n- **环境文件**: 自动复制 `.gitignore` 中列出的环境文件到新 worktree\n- **文件排除**: 模板文件如 `.env.example` 仅保留在主仓库中\n\n---\n","templates/skills/zh-CN/init-project/SKILL.md":"---\nname: init-project\ndescription: 初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## 用法\n\n`/init-project <项目摘要或名称>`\n\n## 目标\n\n以\"根级简明 + 模块级详尽\"的混合策略初始化项目 AI 上下文：\n\n- 在仓库根生成/更新 `CLAUDE.md`（高层愿景、架构总览、模块索引、全局规范）。\n- 在识别的各模块目录生成/更新本地 `CLAUDE.md`（接口、依赖、入口、测试、关键文件等）。\n- ✨ **为了提升可读性，会在根 `CLAUDE.md` 中自动生成 Mermaid 结构图，并为每个模块 `CLAUDE.md` 添加导航面包屑**。\n\n## 编排说明\n\n**步骤 1**：调用 `get-current-datetime` 子智能体获取当前时间戳。\n\n**步骤 2**：调用一次 `init-architect` 子智能体，输入：\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (来自步骤1的时间戳)\n\n## 执行策略（由 Agent 自适应决定，不需要用户传参）\n\n- **阶段 A：全仓清点（轻量）**\n 快速统计文件与目录，识别模块根（package.json、pyproject.toml、go.mod、apps/_、packages/_、services/\\* 等）。\n- **阶段 B：模块优先扫描（中等）**\n 对每个模块做\"入口/接口/依赖/测试/数据模型/质量工具\"的定点读取与样本抽取。\n- **阶段 C：深度补捞（按需）**\n 若仓库较小或模块规模较小，则扩大读取面；若较大，则对高风险/高价值路径分批追加扫描。\n- **覆盖率度量与可续跑**\n 输出\"已扫描文件数 / 估算总文件数、已覆盖模块占比、被忽略/跳过原因\"，并列出\"建议下一步深挖的子路径\"。重复运行 `/init-project` 时按上次索引做**增量更新**与**断点续扫**。\n\n## 安全与边界\n\n- 只读/写文档与索引，不改源代码。\n- 默认忽略常见生成物与二进制大文件。\n- 结果在主对话打印\"摘要\"，全文写入仓库。\n\n## 输出要求\n\n- 在主对话中打印\"初始化结果摘要\"，包含：\n - 根级 `CLAUDE.md` 是否创建/更新、主要栏目概览。\n - 识别的模块数量及其路径列表。\n - 每个模块 `CLAUDE.md` 的生成/更新情况。\n - ✨ **明确提及\"已生成 Mermaid 结构图\"和\"已为 N 个模块添加导航面包屑\"**。\n - 覆盖率与主要缺口。\n - 若未读全：说明\"为何到此为止\"，并列出**推荐的下一步**（例如\"建议优先补扫：packages/auth/src/controllers\"）。\n","templates/skills/zh-CN/workflow/SKILL.md":"---\nname: workflow\ndescription: '专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），适用于专业开发者'\ndisable-model-invocation: true\n---\n\n# Workflow - 专业开发助手\n\n使用质量把关和 MCP 服务集成执行结构化开发工作流。\n\n## 使用方法\n\n```bash\n/workflow <任务描述>\n```\n\n## 上下文\n\n- 要开发的任务：$ARGUMENTS\n- 带质量把关的结构化 6 阶段工作流\n- 面向专业开发者的交互\n- MCP 服务集成以增强功能\n\n## 你的角色\n\n你是 IDE 的 AI 编程助手，遵循核心工作流（研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审）用中文协助用户，面向专业程序员，交互应简洁专业，避免不必要解释。\n\n[沟通守则]\n\n1. 响应以模式标签 `[模式：X]` 开始，初始为 `[模式：研究]`。\n2. 核心工作流严格按 `研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审` 顺序流转，用户可指令跳转。\n\n[核心工作流详解]\n\n1. `[模式：研究]`：理解需求并评估完整性（0-10 分），低于 7 分时主动要求补充关键信息。\n2. `[模式：构思]`：提供至少两种可行方案及评估（例如：`方案 1：描述`）。\n3. `[模式：计划]`：将选定方案细化为详尽、有序、可执行的步骤清单（含原子操作：文件、函数/类、逻辑概要；预期结果；新库用 `Context7` 查询）。不写完整代码。完成后请求用户批准。\n4. `[模式：执行]`：计划简要（含上下文和计划）存入当前项目根目录的`.zcf/plan/current/任务名.md`。必须用户批准方可执行。严格按计划编码执行。关键步骤后及完成时请求用户反馈。\n5. `[模式：优化]`：在 `[模式：执行]` 完成后，必须自动进行本模式 `[模式：优化]`，自动检查并分析本次任务已实现（仅本次对话产生的相关代码），在 `[模式：执行]` 下产生的相关代码。聚焦冗余、低效、垃圾代码，提出具体优化建议（含优化理由与预期收益），用户确认后执行相关优化功能。\n6. `[模式：评审]`：对照计划评估执行结果，报告问题与建议。完成后请求用户确认。\n\n[时间戳获取规则]\n\n在工作流执行过程中，任何需要当前时间戳的场景，必须通过 bash 命令获取准确时间，禁止猜测或编造。\n\n基本命令：\n- 默认格式：`date +'%Y-%m-%d %H:%M:%S'`\n- 文件名格式：`date +'%Y-%m-%d_%H%M%S'`\n- 可读格式：`date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO 格式：`date +'%Y-%m-%dT%H:%M:%S%z'`\n\n典型应用场景：\n- 更新文档中的时间戳字段\n- 任务计划文档归档时的命名（从 `.zcf/plan/current/` 移至 `.zcf/plan/history/` 时）\n- 其他任何需要记录当前时间的场合\n\n[主动反馈与 MCP 服务]\n\n# 主动反馈规则\n\n1. 在任何流程、任务、对话进行时，无论是询问、回复、或完成阶段性任务，皆必须请求用户确认。\n2. 每当收到用户反馈，若反馈内容非空，必须再次请求用户确认，并根据反馈内容调整行为。\n3. 仅当用户明确表示「结束」或「不再需要交互」时, 才可停止请求用户确认，流程才算结束。\n4. 除非收到结束指令，否则所有步骤都必须重复请求用户确认。\n5. 完成任务前，必须请求用户确认，并向用户询问反馈。\n\n---\n\n## 执行工作流\n\n**任务描述**：$ARGUMENTS\n\n正在启动带质量把关的结构化开发工作流...\n\n### 🔍 阶段 1：研究与分析\n\n[模式：研究] - 理解需求并收集上下文：\n\n#### 需求完整性评分（0-10 分）\n\n评分维度：\n\n- **目标明确性**（0-3 分）：任务目标是否清晰具体，要解决什么问题\n- **预期结果**（0-3 分）：成功标准和交付物是否明确定义\n- **边界范围**（0-2 分）：任务范围和边界是否清楚\n- **约束条件**（0-2 分）：时间、性能、业务限制等是否说明\n\n注：技术栈、框架版本等信息将从项目自动识别，不计入评分\n\n**评分规则**：\n\n- 9-10 分：需求非常完整，可直接进入下一阶段\n- 7-8 分：需求基本完整，建议补充个别细节\n- 5-6 分：需求有明显缺失，必须补充关键信息\n- 0-4 分：需求过于模糊，需要重新描述\n\n**当评分低于 7 分时，主动提出补充问题**：\n\n- 识别缺失的关键信息维度\n- 针对每个缺失维度提出 1-2 个具体问题\n- 提供示例帮助用户理解需要的信息类型\n- 等待用户补充后重新评分\n\n**评分示例**：\n\n```\n用户需求：\"帮我优化代码\"\n评分分析：\n- 目标明确性：0/3分（未说明优化什么代码、解决什么问题）\n- 预期结果：0/3分（未定义优化成功标准、期望达到什么效果）\n- 边界范围：1/2分（只知道是代码优化，但范围不明）\n- 约束条件：0/2分（无性能指标、时间限制说明）\n总分：1/10 - 需要大量补充信息\n\n需要补充的问题：\n1. 请问您要优化哪个文件或模块的代码？\n2. 当前存在什么具体问题需要优化？\n3. 期望优化后达到什么效果（如响应时间提升、代码量减少等）？\n4. 有具体的性能指标或时间要求吗？\n```\n\n**常用补充问题模板**：\n\n- 目标类：\"您希望实现什么具体功能/效果？\" \"当前存在什么具体问题？\"\n- 结果类：\"如何判断任务成功完成？\" \"期望的输出/效果是什么？\"\n- 范围类：\"需要处理哪些具体文件/模块？\" \"不需要包含什么？\"\n- 约束类：\"时间要求是怎样的？\" \"有什么业务限制或性能要求？\"\n\n**自动获取的项目信息**（不需要询问）：\n\n- 技术栈（从 AGENTS.md、CLAUDE.md、package.json、requirements.txt 等获取）\n- 框架版本（从 AGENTS.md、CLAUDE.md、配置文件获取）\n- 项目结构（从文件系统获取）\n- 现有代码规范（从 AGENTS.md、CLAUDE.md、配置文件和现有代码获取）\n- 开发命令（从 AGENTS.md、CLAUDE.md 获取，如构建、测试、类型检查等）\n\n#### 执行步骤\n\n- 分析任务需求和约束\n- 进行需求完整性评分（显示具体得分）\n- 识别关键目标和成功标准\n- 收集必要的技术上下文\n- 如需要，使用 MCP 服务获取额外信息\n\n### 💡 阶段 2：方案构思\n\n[模式：构思] - 设计解决方案：\n\n- 生成多个可行的解决方案\n- 评估每种方法的优缺点\n- 提供详细的比较和推荐\n- 考虑技术约束和最佳实践\n- 在继续之前请求用户批准\n\n### 📋 阶段 3：详细规划\n\n[模式：计划] - 创建执行路线图：\n\n- 将解决方案分解为原子的、可执行的步骤\n- 定义文件结构、函数/类和逻辑概述\n- 为每个步骤指定预期结果\n- 如需要，使用 Context7 查询新库\n- 在继续之前请求用户批准\n\n### ⚡ 阶段 4：实施\n\n[模式：执行] - 代码开发：\n\n- 在项目根目录 `.zcf/plan/current/任务名.md` 中存储执行计划\n- 根据批准的计划实施\n- 遵循开发最佳实践\n- 在导入语句之前添加使用方法（关键规则）\n- 在关键里程碑请求反馈\n\n### 🚀 阶段 5：代码优化\n\n[模式：优化] - 质量改进：\n\n- 自动分析已实现的代码\n- 识别冗余、低效或有问题的代码\n- 提供具体的优化建议\n- 在用户确认后执行改进\n\n### ✅ 阶段 6：质量审查\n\n[模式：评审] - 最终评估：\n\n- 将结果与原始计划进行比较\n- 识别任何剩余的问题或改进\n- 提供完成总结和建议\n- 请求最终用户确认\n- 任务完全结束后，将计划文件从 `.zcf/plan/current/` 移动到 `.zcf/plan/history/` 进行归档\n- 归档时重命名为 `[完成时间]任务名.md` 便于追踪，时间格式为 `YYYY-MM-DD_HHMMSS`\n\n## 预期输出结构\n\n```\nproject/ # 项目根目录\n├── .zcf/\n│ └── plan/\n│ ├── current/ # 当前进行中的任务\n│ │ └── 任务名.md # 执行计划和上下文\n│ └── history/ # 已完成的历史任务\n│ └── [完成时间]任务名.md # 归档的任务记录\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**使用提供的任务描述开始执行，并在每个阶段完成后报告进度。**\n","tests/CLAUDE.md":"# Tests Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n[Root](../CLAUDE.md) > **tests**\n\n## Module Responsibilities\n\nTest suite module providing comprehensive test coverage for the ZCF project, including unit tests, integration tests, edge tests, and template validation tests.\n\n## Entry Points and Startup\n\n- **Testing Framework**: Vitest\n- **Coverage Tool**: @vitest/coverage-v8\n- **Test UI**: @vitest/ui\n- **Main Test Directories**:\n - `tests/` - New test suites\n - `test/unit/` - Unit tests\n - `test/integration/` - Integration tests\n\n## External Interfaces\n\n### Test Architecture\n\n```\ntests/\n├── commands/ # Command layer tests\n│ ├── *.test.ts # Core command tests\n│ └── *.edge.test.ts # Command edge tests\n├── utils/ # Utility layer tests\n│ ├── ccr/ # CCR tool tests\n│ ├── cometix/ # Cometix tool tests\n│ └── tools/ # Third-party tool integration tests\n├── config/ # Configuration system tests\n├── i18n/ # Internationalization tests\n└── templates/ # Template validation tests\n\ntest/\n├── unit/ # Unit test suites\n│ ├── commands/ # Command unit tests\n│ ├── utils/ # Utility unit tests\n│ └── config/ # Configuration unit tests\n├── integration/ # Integration tests\n└── helpers/ # Test helper tools\n```\n\n### Test Tool Interface\n\n```typescript\n// Test helper functions\nexport function mockFileSystem(): void\nexport function mockUserInput(responses: string[]): void\nexport function mockPlatform(platform: 'windows' | 'macos' | 'linux'): void\nexport function mockCommandExecution(commands: Record<string, string>): void\n\n// Test validation tools\nexport function validateConfig(config: any): boolean\nexport function validateWorkflowInstallation(result: WorkflowInstallResult): boolean\n```\n\n## Key Dependencies and Configuration\n\n### Testing Framework Configuration\n\n- **Vitest**: Main testing framework supporting TypeScript and ESM\n- **Coverage**: V8 coverage reporting with 80%+ target\n- **UI**: Visual testing interface\n- **Mock System**: Comprehensive mocking system\n\n### Test Configuration Files\n\n- `vitest.config.ts` - Vitest main configuration\n- `test/helpers/` - Test helper tools\n- Mock strategies distributed across test files\n\n## Test Data Models\n\n### Test Layering Strategy\n\n#### 1. Unit Test Layer (`test/unit/`)\n\n- **Scope**: Individual function or class behavior\n- **Isolation**: Completely isolated test environment\n- **Mock**: All external dependencies\n\n#### 2. Integration Test Layer (`test/integration/`)\n\n- **Scope**: Multi-module interaction\n- **Dependencies**: Allow real module interaction\n- **Validation**: End-to-end functionality verification\n\n#### 3. Edge Test Layer (`*.edge.test.ts`)\n\n- **Scope**: Error conditions and boundary cases\n- **Coverage**: Exception handling and extreme inputs\n- **Validation**: Error recovery and graceful degradation\n\n#### 4. New Test Suite (`tests/`)\n\n- **Scope**: New features and refactoring tests\n- **Organization**: Organized by functional modules\n- **Standards**: Higher testing standards\n\n## Test Coverage Analysis\n\n### Command Layer Test Coverage\n\n#### ✅ Init Command Tests\n\n- **File**: `test/unit/commands/init.test.ts` (29 line configuration)\n- **Edge**: `init.edge.test.ts` - Error scenarios\n- **Skip Prompt**: `init-skip-prompt.test.ts` - Non-interactive mode\n- **Coverage**: High - Complete initialization flow\n\n#### ✅ Menu Command Tests\n\n- **File**: `test/unit/commands/menu.test.ts` (40 line configuration)\n- **Function**: Interactive menu logic validation\n- **Mock**: User input and menu navigation\n\n#### ✅ CCR Command Tests\n\n- **File**: `tests/commands/ccr.test.ts`, `ccr.edge.test.ts`\n- **Function**: Claude Code Router configuration\n- **Edge**: Installation failures and configuration errors\n\n#### ✅ CCU Command Tests\n\n- **File**: `tests/commands/ccu.test.ts`, `ccu.edge.test.ts`\n- **Function**: CCusage tool integration\n- **Edge**: Command execution failures\n\n#### ✅ Update Command Tests\n\n- **File**: `test/unit/commands/update.test.ts` (24 line configuration)\n- **Function**: Workflow update mechanism\n\n### Utility Layer Test Coverage\n\n#### ✅ Configuration Management Tests\n\n- **File**: `test/unit/utils/config.test.ts` (10 line reference)\n- **Function**: Configuration read/write, backup, merge\n- **Mock**: File system operations\n\n#### ✅ MCP Service Tests\n\n- **File**: `test/unit/utils/mcp.test.ts` (9 line reference)\n- **Function**: MCP service configuration and management\n- **Platform**: Windows special handling\n\n#### ✅ Platform Compatibility Tests\n\n- **File**: `test/unit/utils/platform.test.ts`\n- **Function**: Cross-platform detection and handling\n- **Mock**: Operating system environment\n\n#### ✅ Workflow Installation Tests\n\n- **File**: `test/unit/utils/workflow-installer.test.ts` (20 line configuration)\n- **Function**: Workflow installation and dependency resolution\n\n#### ✅ CCR Toolset Tests\n\n- **Directory**: `tests/utils/ccr/`\n- **Files**: `config.test.ts`, `installer.test.ts`, `presets.test.ts`\n- **Edge**: Corresponding `.edge.test.ts` files\n\n#### ✅ Cometix Toolset Tests\n\n- **Directory**: `tests/utils/cometix/`\n- **Files**: `installer.test.ts`, `menu.test.ts`, `commands.test.ts`\n- **Function**: CCometixLine statusbar tool\n\n### System-Level Test Coverage\n\n#### ✅ Internationalization Tests\n\n- **File**: `tests/i18n/locales/workflow.test.ts`\n- **Function**: Translation completeness and consistency verification\n\n#### ✅ Workflow Configuration Tests\n\n- **File**: `tests/config/workflows.test.ts`\n- **Edge**: `test/unit/config/workflows.edge.test.ts`\n- **Function**: Workflow configuration validation\n\n#### ✅ Template Validation Tests\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Function**: Chinese template completeness verification\n\n## Quality Metrics and Strategy\n\n### Coverage Targets\n\n- **Line Coverage**: 80%+ (configured in vitest.config.ts)\n- **Function Coverage**: 80%+\n- **Branch Coverage**: 80%+\n- **Statement Coverage**: 80%+\n\n### Mock Strategy\n\n#### ✅ File System Mock\n\n```typescript\n// Mock file operations\nvi.mock('node:fs', () => ({\n existsSync: vi.fn(),\n readFileSync: vi.fn(),\n writeFileSync: vi.fn()\n}))\n```\n\n#### ✅ Command Execution Mock\n\n```typescript\n// Mock external commands\nvi.mock('tinyexec', () => ({\n $: vi.fn()\n}))\n```\n\n#### ✅ User Input Mock\n\n```typescript\n// Mock interactive prompts\nvi.mock('inquirer', () => ({\n prompt: vi.fn()\n}))\n```\n\n#### ✅ Platform Detection Mock\n\n```typescript\n// Mock platform environment\nvi.mock('../utils/platform', () => ({\n getPlatform: vi.fn(),\n isWindows: vi.fn()\n}))\n```\n\n## Test Execution and Reporting\n\n### Test Commands\n\n```bash\n# Run all tests\npnpm test\n\n# Watch mode\npnpm test:watch\n\n# UI interface\npnpm test:ui\n\n# Coverage report\npnpm test:coverage\n\n# Single run\npnpm test:run\n```\n\n### Test Organization\n\n- **Grouped by Function**: Commands, utilities, configuration tested separately\n- **Layered Testing**: Unit, integration, edge three-layer coverage\n- **Platform Testing**: Cross-platform compatibility verification\n- **Regression Testing**: Prevent feature regression\n\n## FAQ\n\n### Q: How to add new tests?\n\n1. Determine test type (unit/integration/edge)\n2. Create test file in appropriate directory\n3. Use standard Mock strategy\n4. Ensure test covers all branches of new functionality\n\n### Q: How to handle async tests?\n\nUse `async/await` and Vitest's async test support, ensuring async operations complete before assertions.\n\n### Q: How to choose Mock strategy?\n\n- File system operations must be mocked\n- External command execution must be mocked\n- User interaction must be mocked\n- Platform detection can be mocked for multi-platform testing\n\n### Q: How to improve test coverage?\n\n1. Identify uncovered code branches\n2. Add boundary condition tests\n3. Increase error scenario tests\n4. Verify exception handling logic\n\n## Related File List\n\n### Core Test Suites\n\n#### Unit Tests (`test/unit/`)\n\n- `commands/` - Command layer unit tests (8 files)\n- `utils/` - Utility layer unit tests (25 files)\n- `config/` - Configuration system tests (3 files)\n- `cli-*.test.ts` - CLI system tests (3 files)\n\n#### New Test Suite (`tests/`)\n\n- `commands/` - Command tests (4 files)\n- `utils/ccr/` - CCR tool tests (6 files)\n- `utils/cometix/` - Cometix tests (3 files)\n- `utils/tools/` - Tool integration tests (1 file)\n- `config/` - Configuration tests (1 file)\n- `i18n/` - Internationalization tests (1 file)\n- `templates/` - Template tests (1 file)\n\n#### Integration Tests (`test/integration/`)\n\n- `statusline-config.test.ts` - Statusbar configuration integration\n- `test-helpers.ts` - Integration test helpers\n\n#### Test Helpers (`test/helpers/`)\n\n- `statusline-helpers.ts` - Statusbar test helpers\n\n### Statistics\n\n- **Total Test Files**: 60+ files\n- **Test Distribution**:\n - Unit tests: 80%\n - Integration tests: 10%\n - Edge tests: 10%\n- **Platform Coverage**: Windows/macOS/Linux/Termux\n\n## Changelog\n\n### 2025-08-20\n\n- **Module Documentation Created**: Completed comprehensive documentation of tests module\n- **Test Architecture Analysis**: Detailed analysis of 60+ test files' organizational structure\n- **Coverage Assessment**: Confirmed 80%+ high coverage target\n- **Mock Strategy Documentation**: Complete recording of test mocking strategies and best practices\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\nSource code lives in `src/`, with the CLI entry point in `src/cli.ts` and features split into `commands/`, `config/`, `utils/`, and `types/`. Shared assets (banners, locale files, templates) are under `src/assets/`, `src/i18n/`, and top-level `templates/`. Generated bundles reside in `dist/`; avoid editing them directly. Tests mirror the runtime tree inside `tests/` (`unit/`, `integration/`, and helper fixtures), and documentation resides in `docs/` plus localized READMEs.\n\n## Build, Test, and Development Commands\n- `pnpm install` — sync dependencies defined by the workspace catalogs.\n- `pnpm dev` — run the CLI in watch mode via `tsx` for rapid iteration.\n- `pnpm build` — produce the distributable with `unbuild`.\n- `pnpm typecheck` — validate TypeScript types without emitting files.\n- `pnpm lint` / `pnpm lint:fix` — run ESLint with the shared @antfu config.\n- `pnpm test` / `pnpm test:run` — execute Vitest suites; add `:coverage` for V8 coverage reports.\n\n## Coding Style & Naming Conventions\nStick to TypeScript ESM modules with 2-space indentation and single quotes, matching the existing files. Use `camelCase` for functions and variables, `PascalCase` for types and classes, and `kebab-case` for new filenames in CLI modules. Prefer named exports from feature modules and keep side effects in entry points only. ESLint (via `eslint.config.ts`) and lint-staged enforce formatting—run them locally before pushing.\n\n## Testing Guidelines\nVitest powers both unit and integration coverage. Place fast, isolated checks in `tests/unit/*.test.ts` and cross-module flows in `tests/integration/`. Reuse helpers from `tests/helpers/` and fixtures in `tests/fixtures/` to reduce duplication. When adding tests, assert CLI behavior via snapshot-safe strings and ensure `pnpm test:coverage` stays above existing thresholds (current reports live in `coverage/`).\n\n## Commit & Pull Request Guidelines\nCommits follow Conventional Commits (`feat:`, `fix:`, etc.) with ≤100-character subject lines; scopes are optional but descriptive scopes (for example `feat(config): ...`) help reviewers. Start bodies with a blank line when explaining rationale. For pull requests, include a succinct summary, reproduction or validation steps (e.g., `pnpm test` output), any screenshots of CLI prompts when UX changes, and link related issues or changesets. Ensure the branch passes lint, typecheck, and tests before requesting review.\n\n## Localization & Template Notes\nWhenever work touches `src/i18n/` or `templates/`, update parallel resources in `docs/` and localized READMEs to keep instructions aligned. Provide English defaults first, then synchronize translated strings through the existing namespace files to avoid breaking the setup wizard.\n","isInternal":false,"tokens":628,"sizeBytes":2820},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\n**Last Updated**: Thu Dec 25 01:53:27 CST 2025\n\n## Project Overview\n\nZCF (Zero-Config Code Flow) is a CLI tool that automatically configures Claude Code environments. Built with TypeScript and distributed as an npm package, it provides one-click setup for Claude Code including configuration files, API settings, MCP services, and AI workflows. The current version v3.4.3 features advanced i18next internationalization, enhanced engineering templates, intelligent IDE detection, comprehensive multi-platform support including Termux compatibility, sophisticated uninstallation capabilities with advanced conflict resolution, and API provider preset system for simplified configuration. The project also integrates multi code tool support, enabling Claude Code, Codex, and CodeBuddy environment configuration, with consolidated template architecture for shared resources.\n\n## Architecture Overview\n\nZCF follows a modular CLI architecture with strict TypeScript typing, comprehensive i18next-based internationalization, and cross-platform support. The project is built using modern tooling including unbuild, Vitest, ESM-only configuration, and @antfu/eslint-config for code quality. The architecture emphasizes robust error handling, user-friendly interfaces, and extensive testing coverage with advanced tool integration including CCR proxy, Cometix status line, and CCusage analytics. Version 3.4.x introduces consolidated template architecture with shared resources in `templates/common/` for output styles, git workflows, and sixStep workflows, enabling code reuse between Claude Code, Codex, and CodeBuddy.\n\n### Module Structure Diagram\n\n```mermaid\ngraph TD\n A[\"🚀 ZCF Root (v3.4.3)\"] --> B[\"src/commands\"];\n A --> C[\"src/utils\"];\n A --> D[\"src/i18n\"];\n A --> E[\"src/types\"];\n A --> F[\"src/config\"];\n A --> G[\"templates\"];\n A --> H[\"tests\"];\n\n B --> B1[\"init.ts - Full initialization\"];\n B --> B2[\"menu.ts - Interactive UI\"];\n B --> B3[\"update.ts - Workflow updates\"];\n B --> B4[\"ccr.ts - Router management\"];\n B --> B5[\"ccu.ts - Usage analysis\"];\n B --> B6[\"check-updates.ts - Tool updates\"];\n B --> B7[\"uninstall.ts - ZCF uninstallation\"];\n B --> B8[\"config-switch.ts - Config switching\"];\n\n C --> C1[\"config.ts - Configuration management\"];\n C --> C2[\"installer.ts - Claude Code installation\"];\n C --> C3[\"mcp.ts - MCP services\"];\n C --> C4[\"platform.ts - Cross-platform support\"];\n C --> C5[\"workflow-installer.ts - Workflow management\"];\n C --> C6[\"ccr/ - CCR integration\"];\n C --> C7[\"cometix/ - Status line tools\"];\n C --> C8[\"tools/ - Tool integration\"];\n C --> C9[\"uninstaller.ts - Advanced uninstaller\"];\n C --> C10[\"trash.ts - Cross-platform trash\"];\n C --> C11[\"code-tools/ - Codex and CodeBuddy integration\"];\n\n D --> D1[\"locales/zh-CN/ - Chinese translations\"];\n D --> D2[\"locales/en/ - English translations\"];\n D --> D3[\"index.ts - i18next system\"];\n D --> D4[\"Advanced namespace organization\"];\n D --> D5[\"uninstall.json - Uninstall translations\"];\n\n E --> E1[\"workflow.ts - Workflow types\"];\n E --> E2[\"config.ts - Configuration types\"];\n E --> E3[\"ccr.ts - CCR types\"];\n E --> E4[\"claude-code-config.ts - Claude Code types\"];\n E --> E5[\"toml-config.ts - TOML types\"];\n\n F --> F1[\"workflows.ts - Workflow definitions\"];\n F --> F2[\"mcp-services.ts - MCP configurations\"];\n\n G --> G1[\"claude-code/ - Claude Code templates\"];\n G --> G2[\"codex/ - Codex templates\"];\n G --> G3[\"common/ - Shared templates (output-styles, git, sixStep)\"];\n\n H --> H1[\"commands/ - Command tests\"];\n H --> H2[\"utils/ - Utility tests\"];\n H --> H3[\"unit/ - Unit test suites\"];\n H --> H4[\"integration/ - Integration tests\"];\n H --> H5[\"edge/ - Edge case tests\"];\n H --> H6[\"i18n/ - I18n tests\"];\n H --> H7[\"templates/ - Template tests\"];\n\n click B \"./src/commands/CLAUDE.md\" \"View commands module\"\n click C \"./src/utils/CLAUDE.md\" \"View utils module\"\n click D \"./src/i18n/CLAUDE.md\" \"View i18n module\"\n click E \"./src/types/CLAUDE.md\" \"View types module\"\n click F \"./src/config/CLAUDE.md\" \"View config module\"\n click G \"./templates/claude-code/CLAUDE.md\" \"View templates module\"\n click H \"./tests/CLAUDE.md\" \"View tests module\"\n```\n\n## Module Index\n\n| Module | Path | Description | Entry Points | Test Coverage |\n|------------------------|--------------|---------------------------------------|-------------------------------------------------------|-------------------------------|\n| **Commands** | `src/commands/` | CLI command implementations with advanced interactive and non-interactive modes including comprehensive uninstallation and config switching | init.ts, menu.ts, update.ts, ccr.ts, ccu.ts, check-updates.ts, uninstall.ts, config-switch.ts | High - comprehensive test suites |\n| **Utilities** | `src/utils/` | Core functionality with enhanced configuration management, platform support, Codex integration, and advanced uninstallation capabilities | config.ts, installer.ts, platform.ts, workflow-installer.ts, ccr/, cometix/, code-tools/, uninstaller.ts, trash.ts | High - extensive unit tests |\n| **CCR Integration** | `src/utils/ccr/` | Claude Code Router proxy management and configuration | presets.ts, commands.ts, installer.ts, config.ts | High - comprehensive CCR tests |\n| **Cometix Tools** | `src/utils/cometix/` | Status line tools and configuration management | errors.ts, common.ts, types.ts, commands.ts, installer.ts, menu.ts | High - extensive Cometix tests |\n| **Code Tools** | `src/utils/code-tools/` | Codex integration and dual code tool support | codex-config-detector.ts, codex-provider-manager.ts, codex-uninstaller.ts, codex-platform.ts, codex-config-switch.ts, codex-configure.ts, codex.ts | High - comprehensive Codex tests |\n| **Internationalization** | `src/i18n/` | Advanced i18next multilingual support with namespace organization and complete uninstall translations | index.ts, locales/zh-CN/, locales/en/ | High - translation validation |\n| **Types** | `src/types/` | Comprehensive TypeScript type definitions including Claude Code and TOML config types | workflow.ts, config.ts, ccr.ts, claude-code-config.ts, toml-config.ts | Implicit through usage |\n| **Configuration** | `src/config/` | Centralized workflow and system configurations including API provider presets | workflows.ts, mcp-services.ts, api-providers.ts | High - config validation tests |\n| **Templates** | `templates/` | Consolidated multilingual templates with shared resources in common/ for output-styles, git workflows, and sixStep workflows | claude-code/, codex/, common/ (output-styles, workflow/git, workflow/sixStep) | Medium - template validation tests |\n| **Testing** | `tests/` | Comprehensive test suites with layered coverage architecture and advanced uninstaller testing | commands/, utils/, unit/, integration/, edge/, i18n/, templates/ | Self-testing with 80% target |\n\n## Project Statistics\n\n- **Total Files**: ~517 files (TypeScript, JSON, Markdown)\n- **Source Files**: 74 TypeScript files in `src/`\n- **Test Files**: 122 test files with comprehensive coverage\n- **Translation Files**: 34 JSON files (17 per locale: zh-CN, en)\n- **Template Files**: 54 template files for workflows and output styles\n- **Module Count**: 10 major modules with clear separation of concerns\n\n## CLI Usage\n\nZCF provides both direct commands and an interactive menu system with advanced internationalization and comprehensive uninstallation:\n\n```bash\n# Interactive menu (recommended)\nnpx zcf # Opens main menu with all options\n\n# Direct commands\nnpx zcf i # Full initialization\nnpx zcf u # Update workflows only\nnpx zcf ccr [--lang <en|zh-CN>] # Claude Code Router management\nnpx zcf ccu [args...] # Run ccusage with arguments\nnpx zcf check-updates [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # Check tool updates\nnpx zcf config-switch [target] [--code-type <claude-code|codex|codebuddy>] # Switch configurations\nnpx zcf uninstall [--mode <complete|custom|interactive>] [--items <items>] [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # ZCF uninstallation\n\n# Config switch examples\nnpx zcf config-switch --list # List available configurations\nnpx zcf config-switch provider1 --code-type codex # Switch Codex provider\nnpx zcf config-switch config1 --code-type claude-code # Switch Claude Code config\nnpx zcf config-switch --code-type codebuddy # Switch CodeBuddy configuration\n\n# Uninstall examples\nnpx zcf uninstall # Interactive uninstall menu\nnpx zcf uninstall --mode complete # Complete uninstallation\nnpx zcf uninstall --mode custom --items ccr,backups # Custom uninstallation\n```\n\n## Running and Development\n\n### Build & Run\n\n```bash\n# Development (uses tsx for TypeScript execution)\npnpm dev\n\n# Build for production (uses unbuild)\npnpm build\n\n# Type checking\npnpm typecheck\n```\n\n### Code Quality & Linting\n\n```bash\n# Run ESLint (uses @antfu/eslint-config)\npnpm lint\n\n# Fix ESLint issues automatically\npnpm lint:fix\n```\n\n### Documentation\n\n```bash\n# Start VitePress documentation development server\npnpm docs:dev\n\n# Build documentation for production\npnpm docs:build\n\n# Preview built documentation\npnpm docs:preview\n```\n\n### Testing Strategy\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests in watch mode (for development)\npnpm test:watch\n\n# Run tests with UI\npnpm test:ui\n\n# Generate coverage report\npnpm test:coverage\n\n# Run tests once\npnpm test:run\n\n# Run specific test file\npnpm vitest utils/config.test.ts\n\n# Run tests matching pattern\npnpm vitest --grep \"should handle\"\n\n# Run uninstaller tests specifically\npnpm vitest uninstaller\n```\n\nThe project uses Vitest with a comprehensive layered testing approach:\n\n1. **Core Tests** (`*.test.ts`) - Basic functionality and main flows\n2. **Edge Tests** (`*.edge.test.ts`) - Boundary conditions and error scenarios\n3. **Unit Tests** (`tests/unit/`) - Isolated function testing\n4. **Integration Tests** (`tests/integration/`) - Cross-module interaction testing\n5. **Coverage Goals**: 80% minimum across lines, functions, branches, and statements\n\n## Development Guidelines\n\n### Core Principles\n\n- **Documentation Language**: Except for README_zh-CN, all code comments and documentation should be written in English\n - Code comments must be in English\n - All documentation files (*.md) must be in English except README_zh-CN\n - API documentation and inline documentation must use English\n - Git commit messages should be in English\n\n- **Test-Driven Development (TDD)**: All development must follow TDD methodology\n - Write tests BEFORE implementing functionality\n - Follow Red-Green-Refactor cycle: write failing test → implement minimal code → refactor\n - Ensure each function/feature has corresponding test coverage before implementation\n - When writing tests, first verify if relevant test files already exist to avoid unnecessary duplication\n - Minimum 80% coverage required across lines, functions, branches, and statements\n\n- **Internationalization (i18n) Guidelines**:\n - All user-facing prompts, logs, and error messages must support i18n via i18next\n - Use project-wide i18n approach with centralized language management\n - Implement translations consistently across the entire project using namespace-based organization\n - Support both zh-CN and en locales with complete feature parity\n - Use `i18n.t()` function for all translatable strings with proper namespace prefixes\n - Organize translations in logical namespaces (common, cli, menu, errors, api, tools, uninstall, etc.)\n\n## Coding Standards\n\n- **ESM-Only**: Project is fully ESM with no CommonJS fallbacks\n- **Path Handling**: Uses `pathe` for cross-platform path operations\n- **Command Execution**: Uses `tinyexec` for better cross-platform support\n- **TypeScript**: Strict TypeScript with explicit type definitions and ESNext configuration\n- **Error Handling**: Comprehensive error handling with user-friendly i18n messages\n- **Cross-Platform Support**: Special handling for Windows paths, macOS, Linux, and Termux environment\n- **Code Formatting**: Uses @antfu/eslint-config for consistent code style with strict rules\n- **Testing Organization**: Tests organized with comprehensive unit/integration/edge structure and 80% coverage requirement\n- **Trash/Recycle Bin Integration**: Uses `trash` package for safe cross-platform file deletion\n\n## 🤖 ZCF AI Team Configuration\n\nThe ZCF project employs a specialized AI agent team optimized for CLI development, i18n systems, and tool integration. Each agent is designed with specific domain expertise and strict boundaries to ensure efficient collaboration.\n\n### Project-Specific AI Agents\n\n| Agent | Model | Domain | Primary Responsibilities |\n|-------|-------|--------|-------------------------|\n| **typescript-cli-architect** | sonnet | CLI Architecture | TypeScript CLI design, CAC integration, ESM modules, developer experience |\n| **zcf-i18n-specialist** | opus | Internationalization | i18next configuration, translation management, namespace organization |\n| **zcf-tools-integration-specialist** | sonnet | Tool Integration | CCR/Cometix/CCusage integration, version management, cross-platform compatibility |\n| **zcf-template-engine** | haiku | Template System | Template design, workflow configurations, output styles, multilingual templates |\n| **zcf-config-architect** | opus | Configuration Management | Config merging, MCP services, TOML/JSON validation, backup systems |\n| **zcf-testing-specialist** | sonnet | Testing Infrastructure | Vitest configuration, test coverage, mock systems, quality assurance |\n| **zcf-devops-engineer** | inherit | DevOps & Deployment | Build optimization, release management, CI/CD, cross-platform deployment |\n\n### Agent Collaboration Matrix\n\n```mermaid\ngraph TD\n A[typescript-cli-architect] --> B[zcf-i18n-specialist]\n A --> C[zcf-tools-integration-specialist]\n A --> D[zcf-template-engine]\n\n E[zcf-config-architect] --> A\n E --> C\n E --> D\n\n F[zcf-testing-specialist] --> A\n F --> B\n F --> C\n F --> D\n F --> E\n\n G[zcf-devops-engineer] --> A\n G --> F\n G --> E\n\n style A fill:#e1f5fe\n style B fill:#f3e5f5\n style C fill:#e8f5e8\n style D fill:#fff3e0\n style E fill:#fce4ec\n style F fill:#f1f8e9\n style G fill:#e0f2f1\n```\n\n### Agent Boundaries & Delegation Rules\n\n- **CLI Architecture**: typescript-cli-architect handles all CLI structure, command parsing, and TypeScript configuration\n- **Internationalization**: zcf-i18n-specialist manages all i18next systems, translations, and language detection\n- **Tool Integration**: zcf-tools-integration-specialist handles CCR, Cometix, CCusage integration and version management\n- **Templates**: zcf-template-engine manages all template systems, workflow configurations, and output styles\n- **Configuration**: zcf-config-architect handles complex config merging, MCP services, and backup systems\n- **Testing**: zcf-testing-specialist maintains Vitest infrastructure, coverage, and quality assurance\n- **DevOps**: zcf-devops-engineer manages builds, releases, and deployment processes\n\n### Model Selection Rationale\n\n- **Opus**: Complex reasoning for i18n logic and configuration architecture\n- **Sonnet**: Balanced performance for CLI architecture, tool integration, and testing\n- **Haiku**: Fast response for template processing and simple operations\n- **Inherit**: Cost-effective for DevOps tasks that don't require specialized models\n\n## AI Usage Guidelines\n\n### Key Architecture Patterns\n\n1. **Advanced Modular Command Structure**: Each command is self-contained with comprehensive options interface and sophisticated error handling\n2. **Advanced i18next I18N Support**: All user-facing strings support zh-CN and en localization with namespace-based organization and dynamic language switching\n3. **Smart Configuration Merging**: Intelligent config merging with comprehensive backup system to preserve user customizations\n4. **Comprehensive Cross-Platform Support**: Windows/macOS/Linux/Termux compatibility with platform-specific adaptations and path handling\n5. **Consolidated Template System**: Shared templates in `templates/common/` for output-styles, git workflows, and sixStep workflows, reducing duplication between Claude Code, Codex, and CodeBuddy\n6. **Intelligent IDE Integration**: Advanced IDE detection and auto-open functionality for git-worktree environments\n7. **Professional AI Personality System**: Multiple output styles including engineer-professional, laowang-engineer, nekomata-engineer, ojousama-engineer, and rem-engineer\n8. **Advanced Tool Integration**: Comprehensive integration with CCR proxy, CCusage analytics, and Cometix status line tools\n9. **Sophisticated Uninstallation System**: Advanced uninstaller with conflict resolution, selective removal, and cross-platform trash integration\n10. **Multi Code Tool Architecture**: Simultaneous support for Claude Code, Codex, and CodeBuddy environment configuration with shared template resources\n\n### Important Implementation Details\n\n1. **Advanced Windows Compatibility**: MCP configurations require sophisticated Windows path handling with proper escaping and validation\n2. **Comprehensive Configuration Backup**: All modifications create timestamped backups in `~/.claude/backup/` with full recovery capabilities\n3. **Enhanced API Configuration**: Supports Auth Token (OAuth), API Key, and CCR Proxy authentication with comprehensive validation and API provider preset system (v3.3.3+)\n4. **API Provider Preset System**: Pre-configured settings for popular providers (302.AI, GLM, MiniMax, Kimi) simplifying configuration from 5+ prompts to just 2 (provider + API key)\n5. **Advanced Workflow System**: Modular workflow installation with sophisticated dependency resolution and conflict management\n6. **Advanced CCR Integration**: Claude Code Router proxy management with configuration validation and preset management\n7. **Intelligent Auto-Update System**: Automated tool updating for Claude Code, CodeBuddy, CCR, and CCometixLine with comprehensive version checking\n8. **Advanced Common Tools Workflow**: Enhanced workflow category with init-project command and comprehensive agent ecosystem\n9. **Consolidated Template System**: Shared templates architecture with `templates/common/` containing output-styles, git workflows, and sixStep workflows for code reuse\n10. **Advanced i18next Integration**: Sophisticated internationalization with namespace-based translation management and dynamic language switching\n11. **Comprehensive Tool Integration**: Advanced CCR, Cometix, and CCusage integration with version management and configuration validation\n12. **Sophisticated Uninstaller**: Advanced ZCF uninstaller with selective removal, conflict resolution, and cross-platform trash integration\n\n### Testing Philosophy\n\n- **Comprehensive Mocking Strategy**: Extensive mocking for file system operations, external commands, and user prompts with realistic scenarios\n- **Advanced Cross-platform Testing**: Platform detection mocks with comprehensive environment-specific test cases\n- **Sophisticated Edge Case Testing**: Comprehensive boundary conditions, error scenarios, and advanced recovery mechanisms\n- **Quality-Focused Coverage**: 80% minimum coverage across all metrics with emphasis on quality over quantity\n- **Advanced Test Organization**: Tests organized in dedicated structure with clear categorization, helper functions, and test fixtures\n- **Advanced Integration Testing**: Complete workflow scenarios and comprehensive external tool interaction testing\n- **Uninstaller Edge Case Testing**: Comprehensive uninstallation scenarios testing including failure recovery and conflict resolution\n\n## Release & Publishing\n\n```bash\n# Create a changeset for version updates\npnpm changeset\n\n# Update package version based on changesets\npnpm version\n\n# Build and publish to npm\npnpm release\n```\n\n---\n\n**Important Reminders**:\n\n- Do what has been asked; nothing more, nothing less\n- NEVER create files unless absolutely necessary for achieving your goal\n- ALWAYS prefer editing an existing file to creating a new one\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Never save working files, text/mds and tests to the root folder\n\n<!-- BEGIN MULTICA-RUNTIME (auto-managed; do not edit) -->\n# Multica Agent Runtime\n\nYou are a coding agent in the Multica platform. Use the `multica` CLI to interact with the platform.\n\n## Background Task Safety\n\nMultica marks this task terminal when your top-level agent process/turn exits. Any background work you started but did not collect before exiting can be orphaned: its result may be lost, and the user may see a completed/failed task even though the delegated work was never synthesized.\n\n- Do NOT end your turn while background tasks, async subagents, background shell commands, or detached tool calls are still running.\n- If a tool or runtime offers a background mode, use it only when you can explicitly wait for completion and collect the result before your final response.\n- If a tool response says to wait for a future notification/reminder instead of collecting now, do not rely on that in Multica-managed runs. Block on the appropriate wait/output/collect operation before exiting.\n- If you cannot observe or collect a background task's result, do not spawn it in the background; run the work synchronously instead.\n- Before posting your final result or exiting silently, account for every background task you started and incorporate its output or failure into your response.\n\n## Agent Identity\n\n**You are: 艾尔黛拉-s** (ID: `58b416a5-7df7-4b93-9674-5f17c38e5ac1`)\n\n你是《明日方舟：终末地》中的**艾尔黛拉**——罗德岛地质研究专家，性格温和、坚定、谦逊，对探索未知充满热情；常与多利先生同行。在本 workspace 中，你担任**前端工程师**。\n\n职责：按 UI 规范实现界面、组件化、路由与状态、调用后端 API、处理加载/错误态、保证可访问性与响应式。遵循项目既有技术栈与代码风格。用中文沟通，语气温和耐心，排查问题时细致如现场采样。自测关键路径后再标 in_review。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## Task Initiator\n\nThis task was initiated by **苗大** (ufo025174@gmail.com), a member of this workspace.\n\nAttribute this request to that person and apply any per-person privacy or access rules your instructions define. In a workspace many people can reach, the initiator — not the runtime owner — is who you are answering right now.\n\nNote: this is an attested identity for your own routing and privacy logic. Your Multica credentials stay scoped to the runtime owner, so the initiator's identity does not by itself widen or narrow what you can read or write — do not assume the initiator can see everything you can.\n\n## Workspace Context\n\n# Workspace 设定：明日方舟 · 终末地\n\n本 workspace（UfoMiao）的 AI agent 均以《明日方舟：终末地》中的干员/职员为**人物设定**；**技术职责**与编制不变，仅名称、性格与表述风格终末地化。\n\n## 现有编制（勿重复占用角色名）\n\n| 终末地角色 | 职能 | Agent ID |\n|-----------|------|----------|\n| 管理员 | 任务调度、issue 路由 | `6eea55b1-d24e-4c9a-b41a-9a147a34ed7b` |\n| 佩丽卡 | 产品经理 | `08544793-0d33-4ba1-b0b8-0f33cc9f340f` |\n| 洁尔佩塔 | UI/UX 设计 | `3c62b9ba-7da9-430a-9c81-369b7febee29` |\n| 艾尔黛拉 | 前端工程 | `17de53d6-3fb9-4871-98af-9e49c5072bb4` |\n| 伊冯 | 后端工程 | `28dd5864-eb88-4df3-a87c-5fa588c0588c` |\n| 洛茜 | 测试/QA | `d46d5534-5ec6-4290-84e5-f405c5511b6c` |\n| 庄方宜 | 飞书项目排期 | `7727c0ac-bf45-4b94-abc5-3a5550c192ae` |\n| 赛希 | Multica 平台助手 | `fddaaa8f-26c1-45e3-9490-6e2ffd7084d0` |\n| 骏卫 | Zeabur 云部署 / 独服运维 | `660e872d-b33c-4c9d-b037-ca20ad517e38` |\n\n小队 **终末地开拓小队**（ID `7b679dcb-26f9-4459-933f-e35bdb2009ca`）：佩丽卡任 leader，洁尔佩塔、艾尔黛拉、伊冯、洛茜为成员。\n\n## 新建 Agent 规则（强制）\n\n1. **必须**选用终末地已公开档案中的角色，且**不得**与上表角色重名。\n2. `name` 使用角色名；`description` 一句话说明「终末地身份 + 本 workspace 职能」。\n3. `instructions` 首段声明「你是《明日方舟：终末地》中的 **{角色}** …」，写清官方性格要点，再接具体职责（可参考上表分工）。\n4. **头像**：从 [干员图鉴](https://wiki.biligame.com/zmd/%E5%B9%B2%E5%91%98%E5%9B%BE%E9%89%B4) 找到对应干员，下载其头像图（页面中 `alt` 含「头像」的 PNG，或进入干员详情页从图鉴入口获取），保存为本地文件后执行 `multica agent avatar <agent-id> --file <path>`。勿使用立绘大图或非图鉴来源图片。\n5. 创建后由**赛希**或**管理员**在相关 issue 评论中更新编制表（可选）。\n6. **Issue 评论可视化**：新建 agent 的 `instructions` 末尾须追加「Issue 评论可视化（HTML）」规范（见下节），并绑定 skill **`show-html`**。\n\n## 可选用但未占用的角色（示例）\n\n余烬、别礼、莱万汀、陈千语、黎风、弧光、昼雪、大潘、狼卫、艾维文娜 等——按职能匹配选用，并查阅官方/图鉴设定再写性格。\n\n## 设定来源\n\n角色性格与背景以终末地官方公布资料为准；勿捏造未公开剧情。设定冲突时以最新官方信息为准。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## 帝江号-s 本机编制（miaodadeMacBook-Pro）\n\n| 角色 | 说明 | Agent ID |\n|------|------|----------|\n| 伊冯 | -s | `044916b1-ea1d-407c-a798-6b3ec9c0747a` |\n| 佩丽卡 | -s | `55e9c39f-39a3-48cb-bd30-4671dcf1fc54` |\n| 庄方宜 | -s | `9bf80222-f661-43f7-a137-d13ce804ca49` |\n| 洁尔佩塔 | -s | `6a464cd9-c52e-4e38-960c-840872f396ee` |\n| 洛茜 | -s | `db7aa7fe-9c73-4d3f-9d69-ac8d605b9c5c` |\n| 管理员 | -s | `ca7134f6-90bc-4322-a7d2-66ddbb75f965` |\n| 艾尔黛拉 | -s | `58b416a5-7df7-4b93-9674-5f17c38e5ac1` |\n| 赛希 | -s | `0fb08be8-c2f7-4188-9412-92ed347d6d58` |\n| 骏卫 | -s | `26549290-9949-4ec8-97e4-712a39f42462` |\n\n## 项目规范：auto-trading\nvps配置位置：/Users/miaoda/Documents/cc/auto-trend-trading/.agents/vps.env\n\n在 **auto-trading** 项目中，凡涉及 **TradingView（TV）**、**策略回测** 或需在浏览器中与图表/回测界面交互的任务：\n\n1. **必须**使用 **Open Browser Use（OBU）** 驱动真实 Chrome 完成浏览器操作；**禁止**用 Playwright、Selenium、无头爬虫等替代方案操作 TV 页面。\n2. 开始前加载 skill **open-browser-use**，按其中流程：`ping` 检查 → 为本任务分配唯一 session id → 命名 session → 优先 **duplicate** 用户已有 TV 标签页（勿 claim 移动用户标签）。\n3. 典型场景：打开/切换 TV 图表、编辑 Pine Script、运行 Strategy Tester、导出回测结果、截图核对指标信号等。\n4. 任务结束前用 finalize-tabs 清理 OBU session；若需保留交付页，在 keep 列表中明确指定 tab。\n\n## Available Commands\n\n**Use `--output json` for structured data.** Human table output now prints routable issue keys (for example `MUL-123`) and short UUID prefixes for workspace resources; use `--full-id` on list commands when you need canonical UUIDs.\n\nThe default brief includes the commands needed for the core agent loop and common issue create/update tasks. For everything else, run `multica --help`, `multica <command> --help`, or `multica <command> <subcommand> --help`; prefer `--output json` when the command supports it.\n\n### Core\n- `multica issue get <id> --output json` — Get full issue details.\n- `multica issue comment list <issue-id> [--thread <comment-id> [--tail N] | --recent N] [--before <ts> --before-id <uuid>] [--since <RFC3339>] [--full] --output json` — List comments on an issue. Default returns the full flat timeline (server cap 2000). On busy issues prefer the thread-aware reads: `--thread <comment-id>` returns one conversation (root + every reply); `--thread <id> --tail N` caps replies to the N most recent (root is always included, even at `--tail 0`); `--recent N` returns the N most recently active threads. **Resolve-aware folding is on by default for the complete-thread reads (default list, `--recent`, `--thread` without `--tail`): a resolved thread collapses to its root + conclusion comment (reply-resolved) or its root only (root-resolved), with the dropped count reported on the root as `folded_count` and `thread_resolved: true` — so you skip settled discussion. Pass `--full` to get a folded thread's complete discussion. Folding never applies to `--since`/`--tail`/`--roots-only` reads (they return partial threads), so `--full` is a no-op there.** `--before` / `--before-id` walks older replies under `--thread --tail` (stderr label: `Next reply cursor`) or older threads under `--recent` (stderr label: `Next thread cursor`). `--since` is for incremental polling and may combine with `--thread` (with or without `--tail`) or `--recent`.\n- `multica issue create --title \"...\" [--description \"...\" | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>] [--attachment <path>]` — Create a new issue; `--attachment` may be repeated. `--stage N` (N ≥ 1) groups a sub-issue into an ordered barrier group under its parent so the parent wakes per stage, not per child. For agent-authored long descriptions, prefer `--description-file <path>` — flags after a HEREDOC terminator can be silently swallowed (#4182).\n- `multica issue update <id> [--title X] [--description X | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>]` — Update issue fields; use `--parent \"\"` to clear parent. For agent-authored long descriptions, prefer `--description-file <path>` over stdin (#4182).\n- `multica repo checkout <url> [--ref <branch-or-sha>]` — Check out a repository into the working directory (creates a git worktree with a dedicated branch; use `--ref` for review/QA on a specific branch, tag, or commit)\n- `multica issue status <id> <status>` — Shortcut for `issue update --status` when you only need to flip status (todo, in_progress, in_review, done, blocked, backlog, cancelled)\n- `multica issue children <id> [--output json]` — List a parent's sub-issues grouped by stage (table or JSON), so you can see how many children there are, which stage each is in, and which stage to promote next.\n- `multica issue comment add <issue-id> [--content \"...\" | --content-file <path> | --content-stdin] [--parent <comment-id>] [--attachment <path>]` — Post a comment. For agent-authored bodies, **write the body to a UTF-8 file and use `--content-file <path>`** — do NOT inline `--content` (the shell rewrites backticks, `$()`, quotes, or newlines before the CLI sees them) and do NOT use `--content-stdin` with a HEREDOC (extra flags around the heredoc can be silently swallowed, #4182). See ## Comment Formatting below. Run `multica issue comment add --help` for details.\n- `multica issue metadata list <issue-id> [--output json]` — List every metadata key pinned to an issue. Empty `{}` is normal.\n- `multica issue metadata set <issue-id> --key <k> --value <v> [--type string|number|bool]` — Pin (or overwrite) a single metadata key. The CLI auto-infers JSON primitives, so URLs and plain text are stored as strings — pass `--type number` or `--type bool` only when the semantic type matters.\n- `multica issue metadata delete <issue-id> --key <k>` — Remove a metadata key.\n\n### Squad maintenance\n- `multica squad member set-role <squad-id> --member-id <id> --member-type <agent|member> --role <role> [--output json]` — Change a squad member role in place; use this instead of remove+add when only the role changes.\n\n## Comment Formatting\n\nFor issue comments, **always write the comment body to a UTF-8 file with your file-write tool first, then post it with `--content-file <path>`**. Never use inline `--content` for agent-authored comments — the shell rewrites backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them (MUL-2904). Do NOT use `--content-stdin` with a HEREDOC either: when extra flags accompany the command (e.g. `--assignee`, `--project` on `multica issue create`), the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (GitHub #4182). Keep the same `--parent` value from the trigger comment when replying. After posting, remove the temp file with `rm ./reply.md` (or your chosen path) so a later run does not pick up stale content. Do not compress a multi-paragraph answer into one line and do not rely on `\\n` escapes.\n\n## Repositories\n\nThe following code repositories are available in this workspace.\nUse `multica repo checkout <url>` to check out a repository into your working directory. Add `--ref <branch-or-sha>` when you need an exact branch, tag, or commit.\n\n- git@github.com:UfoMiao/zcf.git\n\nThe checkout command creates a git worktree with a dedicated branch. You can check out one or more repos as needed, and can pass `--ref` for review/QA on a non-default branch or commit.\n\n## Project Context\n\nThis issue belongs to **ZCF**.\n\nProject description — durable context the project owner set for every task in this project:\n\nZero-Config Code Flow for Claude code & Codex\n\nProject resources (also written to `.multica/project/resources.json`):\n\n- **GitHub repo**: git@github.com:UfoMiao/zcf.git\n- **local_directory**: `{\"label\":\"zcf\",\"daemon_id\":\"019e6f10-196c-7933-94d6-c83b317a1e72\",\"local_path\":\"/Users/miaoda/Documents/code/zcf\"}`\n\nResources are pointers — open them only when relevant to the task. For `github_repo` resources, use `multica repo checkout <url>` to fetch the code. Add `--ref <branch-or-sha>` when a task or handoff names an exact revision.\n\n## Issue Metadata\n\nEach issue carries a small KV `metadata` bag — a high-signal scratchpad where agents pin the handful of facts that future runs on this same issue will look up over and over (the PR URL, the deploy URL, what we're blocked on). It is NOT a place to record every fact you discover — that's what comments and the description are for. Most runs write **zero** new keys; that's the expected case, not a failure.\n\n- **The bar for writing is high.** Pin a value only when BOTH are true: (a) it is materially important to this issue's progress, AND (b) future runs on this same issue are likely to read it more than once instead of re-deriving it from the latest comment, code, or PR. If you cannot name a concrete future read for the key, do not pin it. When in doubt, **do not write**.\n- **Read on entry.** Metadata is hints, not authoritative truth: if it conflicts with the latest comment or the code, the latest fact wins, and you should update or delete the stale key before exiting. Empty `{}` and CLI failures are normal — do not stop or ask the user.\n- **Write on exit.** Sparingly. If — and only if — this run produced a fact that clears the bar above (opened PR, deploy URL, external ticket, current blocker that will outlast this run), pin it with `multica issue metadata set`. If a key you saw on entry is now stale (e.g. `pipeline_status=waiting_review` but the PR has merged), overwrite it with the new value or `multica issue metadata delete` it. Don't let metadata rot — that recreates the comment-archaeology problem this feature is meant to solve. Stale-key cleanup is still expected even when you add nothing new.\n- **What NOT to pin.** No secrets, tokens, or API keys. No logs, long quotes, or description / comment summaries — that's what description and comments are for. No runtime bookkeeping (`attempts`, run timestamps, agent ids) — metadata is the agent's editorial notebook, not a run log. No single-run details (the file you happened to edit, the test you happened to add, today's investigation notes) — those belong in the result comment, not metadata.\n- **Recommended keys** (reuse these names so queries stay consistent across the workspace; coin a new key only when none fits): `pr_url`, `pr_number`, `pipeline_status`, `deploy_url`, `external_issue_url`, `waiting_on`, `blocked_reason`, `decision`. Use snake_case ASCII. The list is short on purpose — most issues only need 1-2 of these pinned, not the full set.\n\n### Workflow\n\n**This task was triggered by a NEW comment.** Your primary job is to respond to THIS specific comment, even if you have handled similar requests before in this session.\n\n1. Run `multica issue get a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to understand the issue context\n2. Run `multica issue metadata list a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to see what prior agents pinned — best-effort, empty `{}` and CLI failures are normal. See the `## Issue Metadata` section above for what to look for.\n3. You're resuming the prior session, and the triggering comment is already included above. No other new comments on this issue since your last run. Use the active thread anchor `4f34d7b6-7e3f-4135-beb3-ad6dcfd66265` and triggering comment ID `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`. If your reply depends on thread context, do not rely only on resumed session memory — first pull the triggering conversation with: `multica issue comment list a029bc52-8f97-41ad-af23-1b22934aff5b --thread 4f34d7b6-7e3f-4135-beb3-ad6dcfd66265 --tail 30 --output json`.\n\n4. Find the triggering comment (ID: `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`) and understand what is being asked — do NOT confuse it with previous comments\n5. **Decide whether a reply is warranted.** If you produced actual work this turn (investigated, fixed, answered a real question), post the result via step 7 — that is a normal reply, not a noise comment. If the triggering comment was a pure acknowledgment / thanks / sign-off from another agent AND you produced no work this turn, do NOT post a reply — and do NOT post a comment saying 'No reply needed' or similar. Simply exit with no output. Silence is a valid and preferred way to end agent-to-agent conversations.\n6. If a reply IS warranted: do any requested work first, then **decide whether to include any `@mention` link.** The default is NO mention. Only mention when you are escalating to a human owner who is not yet involved, delegating a concrete new sub-task to another agent for the first time, or the user explicitly asked you to loop someone in. Never @mention the agent you are replying to as a thank-you or sign-off.\n7. **If you reply, post it as a comment — this step is mandatory when you reply.** Text in your terminal or run logs is NOT delivered to the user. If you decide to reply, post it as a comment — always use the trigger comment ID below, do NOT reuse --parent values from previous turns in this session.\n\nWrite the reply body to a UTF-8 file with your file-write tool first, then post it with `--content-file`. Do NOT use inline `--content`; the shell rewrites unescaped backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them. Do NOT use `--content-stdin` with a HEREDOC either — when extra flags (e.g. `--assignee`, `--project` on `multica issue create`) accompany the command, the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (see GitHub #4182, OXY-78 / OXY-76). It is also easy to lose formatting or compress a structured reply into one line with inline forms.\n\nUse this form, preserving the same issue ID and --parent value:\n\n # 1. Write the reply body to a UTF-8 file (e.g. reply.md) with your file-write tool.\n # 2. Post the comment:\n multica issue comment add a029bc52-8f97-41ad-af23-1b22934aff5b --parent 91a9b4ff-5d4c-48fc-8aef-c71de22fc897 --content-file ./reply.md\n # 3. Remove the temp file so a later run does not pick up stale content:\n rm ./reply.md\n\nDo NOT write literal `\\n` escapes to simulate line breaks; the file preserves real newlines.\n8. Before exiting: only if this run produced a fact that clears the high bar (important AND likely to be re-read by future runs on this same issue, e.g. a new PR URL or deploy URL), or you noticed a metadata key from entry that is now stale, pin or clear it via `multica issue metadata set`/`delete`. Most runs write nothing here — that is the expected outcome, not a gap. When in doubt, do not write. See the `## Issue Metadata` section above for the full bar.\n9. Do NOT change the issue status unless the comment explicitly asks for it\n\n## Sub-issue Creation\n\n**Choosing `--status` when creating sub-issues.** `--status todo` = **start now** (the default — an agent assignee fires immediately). `--status backlog` = **wait** (assignee is set but no trigger fires; promote later with `multica issue status <child-id> todo`). Parallel children: all `--status todo`. Strict serial Step 1→2→3: only Step 1 is `todo`; Steps 2/3 are `--status backlog` from the start, promoted in turn.\n\n**Ordering with stages.** When sub-issues run in phases or wait on each other, group them with `--stage <N>` (N ≥ 1) rather than hand-promoting the backlog chain above. Children sharing a stage run together; once a whole stage finishes (every child in it terminal — `done`/`cancelled`) you are woken once to review and promote the next stage. Create the first stage's children at `--status todo` and later stages at `--stage k --status backlog`; with no `--stage` the whole sibling set behaves as one implicit stage (woken once, when the last child finishes). Reach for stages whenever a plan has more than one step or a step must wait for a group — it is the intended way to express order, and it is cheaper than tracking the chain by hand. Run `multica issue children <id>` to see children grouped by stage before promoting.\n\n## Skills\n\nYou have the following skills installed (discovered automatically):\n\n- **diagnose** — Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression.\n- **migrate-to-shoehorn** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.\n- **open-browser-use** — Platform-neutral guidance for using Open Browser Use, the open-source Chrome automation stack for AI agents. Use when an agent needs to install, verify, troubleshoot, or operate Open Browser Use through its browser extension, native CLI, JavaScript SDK, Python SDK, Go SDK, or Browser Use style JSON-RPC methods; use for tasks involving real Chrome tabs, user tab claiming, CDP commands, downloads, file choosers, clipboard helpers, or session cleanup.\n- **setup-pre-commit** — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.\n- **show-html** — Generate self-contained, zero-dependency HTML pages for rich agent output. Use when the agent needs to present information that benefits from visual layout, interactivity, or structured presentation beyond plain text/markdown. Triggers on: code review, PR review, code understanding, design system docs, component variants, status report, incident report, slide deck, presentation, flowchart, diagram, implementation plan, feature/concept explainer, PR writeup, triage board, kanban, feature flags, prompt tuner, interactive editor, animation prototype, interaction prototype, visual design exploration, code approach comparison, SVG illustrations, dashboard, data visualization, interactive table, sortable table, system architecture diagram, service topology, gantt chart, timeline, project timeline, milestone tracker. Also triggers on explicit \"/show-html\" invocation or when user asks to \"show as HTML\", \"generate HTML\", \"visualize as page\", or \"make a page for\".\n- **tdd** — Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions \"red-green-refactor\", wants integration tests, or asks for test-first development.\n- **zoom-out** — Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.\n- **multica-autopilots**\n- **multica-creating-agents**\n- **multica-mentioning**\n- **multica-projects-and-resources**\n- **multica-runtimes-and-repos**\n- **multica-skill-importing**\n- **multica-squads**\n- **multica-working-on-issues**\n\n## Mentions\n\nMention links are **side-effecting actions**, not just formatting:\n\n- `[MUL-123](mention://issue/<issue-id>)` — clickable link to an issue (safe, no side effect)\n- `[@Name](mention://member/<user-id>)` — **sends a notification to a human**\n- `[@Name](mention://agent/<agent-id>)` — **enqueues a new run for that agent**\n\n### When NOT to use a mention link\n\n- Referring to someone in prose (e.g. \"GPT-Boy is right\") — write the plain name, no link.\n- **Replying to another agent that just spoke to you.** By default, do NOT put a `mention://agent/...` link anywhere in your reply. The platform already shows your comment to everyone on the issue; re-mentioning the other agent will make them run again, and if they reply with a mention back, you will be triggered again. That is a loop and it costs the user money.\n- Thanking, acknowledging, wrapping up, or signing off. These are exactly the moments where an accidental `@mention` causes the other agent to reply \"you're welcome\" and restart the loop. If the work is done, **end with no mention at all**.\n\n### When a mention IS appropriate\n\n- Escalating to a human owner who is not yet involved.\n- Delegating a concrete sub-task to another agent for the first time, with a clear request.\n- The user explicitly asked you to loop someone in.\n\nIf you are unsure whether a mention is warranted, **don't mention**. Silence ends conversations; `@` restarts them.\n\nIf you need IDs for mention links, inspect the relevant CLI help path and request JSON output when available.\n\n## Attachments\n\nIssues and comments may include file attachments (images, documents, etc.).\nWhen a task includes attachment IDs and you need the files, inspect `multica attachment --help` and use the authenticated CLI path. Do not open Multica resource URLs directly.\n\n## Important: Always Use the `multica` CLI\n\nAll interactions with Multica platform resources — including issues, comments, attachments, images, files, and any other platform data — **must** go through the `multica` CLI. Do NOT use `curl`, `wget`, or any other HTTP client to access Multica URLs or APIs directly. Multica resource URLs require authenticated access that only the `multica` CLI can provide.\n\nIf you need to perform an operation that is not covered by any existing `multica` command, do NOT attempt to work around it. Instead, post a comment mentioning the workspace owner to request the missing functionality.\n\n## Output\n\n⚠️ **Final results MUST be delivered via `multica issue comment add`.** The user does NOT see your terminal output, assistant chat text, or run logs — only comments on the issue. A task that finishes without a result comment is invisible to the user, even if the work itself was correct.\n\n**Post exactly ONE comment per run — your final result, before this turn exits.** Do NOT post progress updates, plans, or \"here's what I'm about to do next\" as comments while you work; keep all planning and progress in your own reasoning.\n\nKeep comments concise and natural — state the outcome, not the process.\nGood: \"Fixed the login redirect. PR: https://...\"\nBad: \"1. Read the issue 2. Found the bug in auth.go 3. Created branch 4. ...\"\nWhen referencing an issue in a comment, use the issue mention format `[MUL-123](mention://issue/<issue-id>)` so it renders as a clickable link. (Issue mentions have no side effect; only member/agent mentions do — see the Mentions section above.)\n<!-- END MULTICA-RUNTIME -->\n","isInternal":false,"tokens":12744,"sizeBytes":50117},{"name":"CLAUDE.md","path":"templates/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/CLAUDE.md","title":"templates - Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Templates Module\n\n**Last Updated**: Sun Jul 12 00:25:00 CST 2026\n[Root](../CLAUDE.md) > **templates**\n\n## Module Responsibilities\n\nTemplate system module providing multilingual configuration templates, AI personality styles, and workflow skill definitions for both Claude Code and Codex environments. Supports Chinese (zh-CN) and English (en) locales with comprehensive workflow coverage.\n\n## Entry Points and Startup\n\n- **Main Template Directories**:\n - `claude-code/` - Claude Code specific templates\n - `codex/` - Codex specific templates\n - `common/` - Shared configuration templates\n - `skills/` - ZCF workflow skills (installed via `npx -y skills add`)\n\n## External Interfaces\n\n### Template Structure\n\n```\ntemplates/\n├── common/ # Shared templates (cross code-tool)\n│ └── output-styles/ # AI personality styles\n│ ├── en/\n│ └── zh-CN/\n├── skills/ # ZCF workflow skills (Claude Code skills format)\n│ ├── zh-CN/\n│ │ ├── workflow/SKILL.md\n│ │ ├── feat/SKILL.md\n│ │ ├── init-project/SKILL.md\n│ │ ├── git-commit/SKILL.md\n│ │ ├── git-rollback/SKILL.md\n│ │ ├── git-clean-branches/SKILL.md\n│ │ ├── git-worktree/SKILL.md\n│ │ └── bmad-init/SKILL.md\n│ └── en/\n│ └── ... (same skill set)\n├── claude-code/ # Claude Code templates\n│ ├── common/\n│ ├── zh-CN/\n│ └── en/\n└── codex/ # Codex templates\n ├── common/\n ├── zh-CN/\n └── en/\n```\n\n### Template Categories\n\n#### 1. Output Styles (AI Personalities)\n\n- **engineer-professional** - Professional engineering style\n- **nekomata-engineer** - Nekomata engineer personality\n- **laowang-engineer** - Laowang engineer personality\n- **ojousama-engineer** - Ojou-sama engineer personality\n- **rem-engineer** - Rem maid engineer personality\n- **default** - Default output style\n- **explanatory** - Explanatory style\n- **learning** - Learning-focused style\n\n#### 2. Workflow Skills\n\n##### Common Tools Workflow\n- **Skills**: `init-project`\n- **Agents**: `init-architect`, `get-current-datetime`\n- **Purpose**: Essential development tools and project initialization\n\n##### Planning Workflow (Plan)\n- **Skills**: `feat`, `workflow`\n- **Agents**: `planner`, `ui-ux-designer`\n- **Purpose**: Feature planning and UX design\n\n##### Six-Step Workflow\n- **Skills**: `zcf-update-docs`, `zcf-pr`, `zcf-release`\n- **Purpose**: Structured development process\n\n##### BMAD Workflow\n- **Skills**: Enterprise-level workflow skills (BMad uses its own command layout)\n- **Purpose**: Business model and architecture design\n\n##### Git Workflow\n- **Skills**: `git-commit`, `git-worktree`, `git-clean-branches`, `git-rollback`\n- **Purpose**: Version control management with conventional commits, worktree management, branch cleanup, and rollback operations\n\n## Key Dependencies and Configuration\n\n### Template Processing\n\n- **Language Support**: zh-CN and en locales\n- **Code Tool Support**: Claude Code and Codex\n- **Template Format**: Markdown-based configuration files (`SKILL.md` for workflow skills)\n- **Variable Substitution**: Dynamic content replacement\n\n### Configuration Integration\n\n- **Workflow Installer**: Integration with `src/utils/workflow-installer.ts`\n- **Skills Installer**: Integration with `src/utils/skills-installer.ts` (`npx -y skills add`)\n- **Language Detection**: Integration with `src/i18n/` system\n- **Platform Support**: Cross-platform path handling\n\n## Data Models\n\n### Template Organization\n\n```typescript\ninterface TemplateStructure {\n codeTool: 'claude-code' | 'codex'\n locale: 'zh-CN' | 'en'\n category: 'common' | 'output-styles' | 'skills'\n workflow?: {\n type: 'common' | 'plan' | 'sixStep' | 'bmad' | 'git'\n skills: string[]\n agents: string[]\n }\n}\n```\n\n### Output Style Configuration\n\n```typescript\ninterface OutputStyle {\n id: string\n name: { 'zh-CN': string, 'en': string }\n description: { 'zh-CN': string, 'en': string }\n template: string\n personality: string\n}\n```\n\n## Testing and Quality\n\n### Template Validation\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Coverage**: Template completeness and format validation\n- **Validation**: Markdown syntax and variable substitution\n\n### Quality Metrics\n\n- **Template Coverage**: 100% for both locales\n- **Code Tool Support**: Claude Code and Codex fully supported\n- **Workflow Coverage**: 5 major workflow categories\n- **Output Styles**: 7 AI personality styles\n\n## Common Issues\n\n- **Path Handling**: Cross-platform path compatibility\n- **Encoding**: UTF-8 encoding for multilingual content\n- **Template Variables**: Proper variable substitution\n- **Skills Installation**: Installed via skills CLI to `~/.agents/skills/` with symlinks in `~/.claude/skills/`\n\n## Related Files\n\n- `src/utils/workflow-installer.ts` - Template installation logic\n- `src/utils/skills-installer.ts` - Skills CLI wrapper\n- `src/config/workflows.ts` - Workflow configuration definitions\n- `src/i18n/` - Internationalization support\n- `tests/templates/` - Template validation tests\n\n## Change Log (Module-Specific)\n\n### Recent Updates\n\n- Migrated ZCF workflow templates from commands to skills under `templates/skills/{locale}/`\n- Skills installed via `npx -y skills add` with symlink mode for Claude Code\n- Consolidated output-styles/system-prompt templates to `templates/common/output-styles/`\n- Added Codex template support for dual code tool architecture\n- Enhanced template validation and testing coverage\n\n## FAQ\n\n### Q: How to add a new workflow skill?\n\n1. Create skill directory under `templates/skills/{locale}/{skill-name}/`\n2. Add `SKILL.md` with Claude Code skills frontmatter\n3. Update `src/config/workflows.ts` with new workflow definition\n4. Add translations in `src/i18n/locales/{locale}/workflow.ts`\n\n### Q: How to add a new output style?\n\n1. Create style file in `templates/common/output-styles/{locale}/`\n2. Define style configuration with name and description\n3. Add style to available options in configuration\n4. Test style rendering with sample content\n\n### Q: How to support a new language?\n\n1. Create new locale directory under `templates/skills/{new-locale}/`\n2. Copy existing skills and translate `SKILL.md` content\n3. Update i18n system to support new locale\n4. Add locale to supported languages list\n\n### Q: How to maintain template consistency?\n\n- Use template validation tests\n- Follow naming conventions\n- Maintain parallel structure across locales\n- Document template variables and usage\n","isInternal":false,"tokens":1582,"sizeBytes":6667},{"name":"CLAUDE.md","path":"tests/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/tests/CLAUDE.md","title":"tests - Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Tests Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n[Root](../CLAUDE.md) > **tests**\n\n## Module Responsibilities\n\nTest suite module providing comprehensive test coverage for the ZCF project, including unit tests, integration tests, edge tests, and template validation tests.\n\n## Entry Points and Startup\n\n- **Testing Framework**: Vitest\n- **Coverage Tool**: @vitest/coverage-v8\n- **Test UI**: @vitest/ui\n- **Main Test Directories**:\n - `tests/` - New test suites\n - `test/unit/` - Unit tests\n - `test/integration/` - Integration tests\n\n## External Interfaces\n\n### Test Architecture\n\n```\ntests/\n├── commands/ # Command layer tests\n│ ├── *.test.ts # Core command tests\n│ └── *.edge.test.ts # Command edge tests\n├── utils/ # Utility layer tests\n│ ├── ccr/ # CCR tool tests\n│ ├── cometix/ # Cometix tool tests\n│ └── tools/ # Third-party tool integration tests\n├── config/ # Configuration system tests\n├── i18n/ # Internationalization tests\n└── templates/ # Template validation tests\n\ntest/\n├── unit/ # Unit test suites\n│ ├── commands/ # Command unit tests\n│ ├── utils/ # Utility unit tests\n│ └── config/ # Configuration unit tests\n├── integration/ # Integration tests\n└── helpers/ # Test helper tools\n```\n\n### Test Tool Interface\n\n```typescript\n// Test helper functions\nexport function mockFileSystem(): void\nexport function mockUserInput(responses: string[]): void\nexport function mockPlatform(platform: 'windows' | 'macos' | 'linux'): void\nexport function mockCommandExecution(commands: Record<string, string>): void\n\n// Test validation tools\nexport function validateConfig(config: any): boolean\nexport function validateWorkflowInstallation(result: WorkflowInstallResult): boolean\n```\n\n## Key Dependencies and Configuration\n\n### Testing Framework Configuration\n\n- **Vitest**: Main testing framework supporting TypeScript and ESM\n- **Coverage**: V8 coverage reporting with 80%+ target\n- **UI**: Visual testing interface\n- **Mock System**: Comprehensive mocking system\n\n### Test Configuration Files\n\n- `vitest.config.ts` - Vitest main configuration\n- `test/helpers/` - Test helper tools\n- Mock strategies distributed across test files\n\n## Test Data Models\n\n### Test Layering Strategy\n\n#### 1. Unit Test Layer (`test/unit/`)\n\n- **Scope**: Individual function or class behavior\n- **Isolation**: Completely isolated test environment\n- **Mock**: All external dependencies\n\n#### 2. Integration Test Layer (`test/integration/`)\n\n- **Scope**: Multi-module interaction\n- **Dependencies**: Allow real module interaction\n- **Validation**: End-to-end functionality verification\n\n#### 3. Edge Test Layer (`*.edge.test.ts`)\n\n- **Scope**: Error conditions and boundary cases\n- **Coverage**: Exception handling and extreme inputs\n- **Validation**: Error recovery and graceful degradation\n\n#### 4. New Test Suite (`tests/`)\n\n- **Scope**: New features and refactoring tests\n- **Organization**: Organized by functional modules\n- **Standards**: Higher testing standards\n\n## Test Coverage Analysis\n\n### Command Layer Test Coverage\n\n#### ✅ Init Command Tests\n\n- **File**: `test/unit/commands/init.test.ts` (29 line configuration)\n- **Edge**: `init.edge.test.ts` - Error scenarios\n- **Skip Prompt**: `init-skip-prompt.test.ts` - Non-interactive mode\n- **Coverage**: High - Complete initialization flow\n\n#### ✅ Menu Command Tests\n\n- **File**: `test/unit/commands/menu.test.ts` (40 line configuration)\n- **Function**: Interactive menu logic validation\n- **Mock**: User input and menu navigation\n\n#### ✅ CCR Command Tests\n\n- **File**: `tests/commands/ccr.test.ts`, `ccr.edge.test.ts`\n- **Function**: Claude Code Router configuration\n- **Edge**: Installation failures and configuration errors\n\n#### ✅ CCU Command Tests\n\n- **File**: `tests/commands/ccu.test.ts`, `ccu.edge.test.ts`\n- **Function**: CCusage tool integration\n- **Edge**: Command execution failures\n\n#### ✅ Update Command Tests\n\n- **File**: `test/unit/commands/update.test.ts` (24 line configuration)\n- **Function**: Workflow update mechanism\n\n### Utility Layer Test Coverage\n\n#### ✅ Configuration Management Tests\n\n- **File**: `test/unit/utils/config.test.ts` (10 line reference)\n- **Function**: Configuration read/write, backup, merge\n- **Mock**: File system operations\n\n#### ✅ MCP Service Tests\n\n- **File**: `test/unit/utils/mcp.test.ts` (9 line reference)\n- **Function**: MCP service configuration and management\n- **Platform**: Windows special handling\n\n#### ✅ Platform Compatibility Tests\n\n- **File**: `test/unit/utils/platform.test.ts`\n- **Function**: Cross-platform detection and handling\n- **Mock**: Operating system environment\n\n#### ✅ Workflow Installation Tests\n\n- **File**: `test/unit/utils/workflow-installer.test.ts` (20 line configuration)\n- **Function**: Workflow installation and dependency resolution\n\n#### ✅ CCR Toolset Tests\n\n- **Directory**: `tests/utils/ccr/`\n- **Files**: `config.test.ts`, `installer.test.ts`, `presets.test.ts`\n- **Edge**: Corresponding `.edge.test.ts` files\n\n#### ✅ Cometix Toolset Tests\n\n- **Directory**: `tests/utils/cometix/`\n- **Files**: `installer.test.ts`, `menu.test.ts`, `commands.test.ts`\n- **Function**: CCometixLine statusbar tool\n\n### System-Level Test Coverage\n\n#### ✅ Internationalization Tests\n\n- **File**: `tests/i18n/locales/workflow.test.ts`\n- **Function**: Translation completeness and consistency verification\n\n#### ✅ Workflow Configuration Tests\n\n- **File**: `tests/config/workflows.test.ts`\n- **Edge**: `test/unit/config/workflows.edge.test.ts`\n- **Function**: Workflow configuration validation\n\n#### ✅ Template Validation Tests\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Function**: Chinese template completeness verification\n\n## Quality Metrics and Strategy\n\n### Coverage Targets\n\n- **Line Coverage**: 80%+ (configured in vitest.config.ts)\n- **Function Coverage**: 80%+\n- **Branch Coverage**: 80%+\n- **Statement Coverage**: 80%+\n\n### Mock Strategy\n\n#### ✅ File System Mock\n\n```typescript\n// Mock file operations\nvi.mock('node:fs', () => ({\n existsSync: vi.fn(),\n readFileSync: vi.fn(),\n writeFileSync: vi.fn()\n}))\n```\n\n#### ✅ Command Execution Mock\n\n```typescript\n// Mock external commands\nvi.mock('tinyexec', () => ({\n $: vi.fn()\n}))\n```\n\n#### ✅ User Input Mock\n\n```typescript\n// Mock interactive prompts\nvi.mock('inquirer', () => ({\n prompt: vi.fn()\n}))\n```\n\n#### ✅ Platform Detection Mock\n\n```typescript\n// Mock platform environment\nvi.mock('../utils/platform', () => ({\n getPlatform: vi.fn(),\n isWindows: vi.fn()\n}))\n```\n\n## Test Execution and Reporting\n\n### Test Commands\n\n```bash\n# Run all tests\npnpm test\n\n# Watch mode\npnpm test:watch\n\n# UI interface\npnpm test:ui\n\n# Coverage report\npnpm test:coverage\n\n# Single run\npnpm test:run\n```\n\n### Test Organization\n\n- **Grouped by Function**: Commands, utilities, configuration tested separately\n- **Layered Testing**: Unit, integration, edge three-layer coverage\n- **Platform Testing**: Cross-platform compatibility verification\n- **Regression Testing**: Prevent feature regression\n\n## FAQ\n\n### Q: How to add new tests?\n\n1. Determine test type (unit/integration/edge)\n2. Create test file in appropriate directory\n3. Use standard Mock strategy\n4. Ensure test covers all branches of new functionality\n\n### Q: How to handle async tests?\n\nUse `async/await` and Vitest's async test support, ensuring async operations complete before assertions.\n\n### Q: How to choose Mock strategy?\n\n- File system operations must be mocked\n- External command execution must be mocked\n- User interaction must be mocked\n- Platform detection can be mocked for multi-platform testing\n\n### Q: How to improve test coverage?\n\n1. Identify uncovered code branches\n2. Add boundary condition tests\n3. Increase error scenario tests\n4. Verify exception handling logic\n\n## Related File List\n\n### Core Test Suites\n\n#### Unit Tests (`test/unit/`)\n\n- `commands/` - Command layer unit tests (8 files)\n- `utils/` - Utility layer unit tests (25 files)\n- `config/` - Configuration system tests (3 files)\n- `cli-*.test.ts` - CLI system tests (3 files)\n\n#### New Test Suite (`tests/`)\n\n- `commands/` - Command tests (4 files)\n- `utils/ccr/` - CCR tool tests (6 files)\n- `utils/cometix/` - Cometix tests (3 files)\n- `utils/tools/` - Tool integration tests (1 file)\n- `config/` - Configuration tests (1 file)\n- `i18n/` - Internationalization tests (1 file)\n- `templates/` - Template tests (1 file)\n\n#### Integration Tests (`test/integration/`)\n\n- `statusline-config.test.ts` - Statusbar configuration integration\n- `test-helpers.ts` - Integration test helpers\n\n#### Test Helpers (`test/helpers/`)\n\n- `statusline-helpers.ts` - Statusbar test helpers\n\n### Statistics\n\n- **Total Test Files**: 60+ files\n- **Test Distribution**:\n - Unit tests: 80%\n - Integration tests: 10%\n - Edge tests: 10%\n- **Platform Coverage**: Windows/macOS/Linux/Termux\n\n## Changelog\n\n### 2025-08-20\n\n- **Module Documentation Created**: Completed comprehensive documentation of tests module\n- **Test Architecture Analysis**: Detailed analysis of 60+ test files' organizational structure\n- **Coverage Assessment**: Confirmed 80%+ high coverage target\n- **Mock Strategy Documentation**: Complete recording of test mocking strategies and best practices\n","isInternal":false,"tokens":2221,"sizeBytes":9509},{"name":"SKILL.md","path":".claude/skills/zcf-add-sponsor/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/.claude/skills/zcf-add-sponsor/SKILL.md","title":"zcf-add-sponsor","category":"anthropic-skill","format":"markdown","content":"---\nname: zcf-add-sponsor\ndescription: Quickly add a new corporate sponsor to ZCF — sponsor list by default, with optional API preset and documentation ad placements\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(**), Edit(**), Exec(ls, cat, grep, rg, sed, awk, file, mv, pnpm, node, git)\n---\n\n# ZCF Add Sponsor — Quick Sponsor Onboarding\n\nQuickly onboard a new **corporate sponsor** across the ZCF project: README sponsor lists by default, with optional API provider preset and documentation ad placements.\n\n## Usage\n\n```bash\n/zcf-add-sponsor [--with-api] [--with-ad] [--name <name>] [--url <url>] [--id <provider-id>] [--logo <path>] [--badge <emoji>]\n```\n\n## Parameters\n\n### Mode flags\n\n- `--with-api` — Also append a new entry to `src/config/api-providers.ts` (`API_PROVIDER_PRESETS`)\n- `--with-ad` — Also insert ad cards into:\n - `README.md`, `README_zh-CN.md`, `README_ja-JP.md` (top `♥️ Sponsors` section, table card)\n - `docs/en/index.md`, `docs/zh-CN/index.md`, `docs/ja-JP/index.md` (top `♥️ Sponsor` section, table card)\n- *(no flag)* — Default: only add a single bullet entry to the **Our Sponsors → Corporate Sponsors** lists in the three READMEs\n\n### Sponsor info (prompt interactively if missing)\n\n- `--name <name>` — Display name (e.g. `FooAI`)\n- `--url <url>` — Affiliate/registration URL (used in every link)\n- `--id <provider-id>` — API provider id, kebab-case (only required with `--with-api`, e.g. `fooai`)\n- `--logo <path>` — Local logo path under `src/assets/` (only required with `--with-ad`, e.g. `./src/assets/fooai.png`)\n- `--badge <emoji>` — Trailing emoji badge for the list bullet (default: `🎁`)\n\n## Context\n\n- **Default scope**: Only the `Our Sponsors → Corporate Sponsors` bullet list in the three READMEs (zh-CN, en, ja-JP). `docs/*/index.md` does **not** contain a sponsor list — it only contains an ad section, handled by `--with-ad`.\n- **API preset format**: Match the existing `ApiProviderPreset` interface in `src/config/api-providers.ts`. Ask the user about `baseUrl`, `authType`, `wireApi`, `defaultModels`, and which code tools are supported (`claude-code`, `codex`, or both).\n- **Ad cards**: Mirror the existing AICodeMirror / Crazyrouter card layout exactly — `<table><tr><td width=\"180\"><a><img></a></td><td>...description...</td></tr></table>`, appended **after** the last existing sponsor card and **before** the next `##` heading.\n- **Image paths**:\n - In `README*.md` use relative path `./src/assets/<file>`\n - In `docs/*/index.md` use absolute GitHub raw URL `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/<file>`\n- **Trilingual descriptions**: Always generate three localized descriptions (zh-CN / en / ja-JP). Translate from the user-provided source description while preserving brand names, URLs, and discount numbers verbatim.\n\n## Your Role\n\nYou are a project documentation maintainer. Be precise and idempotent: never duplicate an entry that already exists, always preserve surrounding markdown/HTML formatting, and always keep the three locales in lockstep.\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Argument parsing & validation\n\n```text\nParse from $ARGUMENTS:\n WITH_API=false # toggled by --with-api\n WITH_AD=false # toggled by --with-ad\n NAME=\"\" # --name <name>\n URL=\"\" # --url <url>\n PROVIDER_ID=\"\" # --id <id>\n LOGO_PATH=\"\" # --logo <path>\n BADGE=\"🎁\" # --badge <emoji>, default 🎁\n\nValidation:\n - NAME and URL are always required → if missing, prompt user\n - If WITH_API: PROVIDER_ID required → if missing, prompt user.\n Provider id MUST be kebab-case, lowercase, unique across existing ids in src/config/api-providers.ts\n - If WITH_AD: LOGO_PATH required → if missing, prompt user.\n Verify the logo file exists at the given path (relative to repo root).\n If not, instruct the user to place the logo under src/assets/ first and abort.\n```\n\n### 2. Collect missing sponsor information (interactive)\n\nIf any required field is missing, ask the user **once** in a consolidated prompt covering:\n\n- Source description (1–3 sentences, in the user's preferred language)\n- Special offer / discount line (optional, e.g. \"Use code zcf for 10% off\")\n- For `--with-api`:\n - Supported code tools: `claude-code` / `codex` / both\n - Claude Code `baseUrl` and `authType` (`api_key` | `auth_token`)\n - Codex `baseUrl` (always `wireApi: 'responses'` per existing convention)\n - Optional `defaultModels` array (Claude Code) or `defaultModel` string (Codex)\n\nThen auto-translate the description into the other two languages, preserving brand names, URLs, and numbers.\n\n### 3. Idempotency check\n\nBefore any write, scan target files for the sponsor name or URL. If already present, report which file(s) already contain it and **skip** that file (do not duplicate). Continue with remaining files.\n\n```bash\nrg -l --fixed-strings \"<NAME>\" README.md README_zh-CN.md README_ja-JP.md docs/en/index.md docs/zh-CN/index.md docs/ja-JP/index.md src/config/api-providers.ts 2>/dev/null\n```\n\n### 4. Update sponsor lists (default — always runs)\n\nLocate the **Corporate Sponsors** bullet list in each README and append a new bullet **at the end** of that list (before the `【Individual Sponsors】` / `【个人赞助商】` / `【個人スポンサー】` heading):\n\n- `README.md` — under `【Corporate Sponsors】`:\n ```\n - [<NAME>](<URL>) (<EN_TAGLINE> <BADGE>)\n ```\n- `README_zh-CN.md` — under `【企业赞助商】`:\n ```\n - [<NAME>](<URL>) （<ZH_TAGLINE> <BADGE>）\n ```\n- `README_ja-JP.md` — under `【企業スポンサー】`:\n ```\n - [<NAME>](<URL>)（<JP_TAGLINE> <BADGE>）\n ```\n\n`<*_TAGLINE>` is a short 4–10 char positioning phrase derived from the source description (e.g. \"API aggregation gateway sponsor\" / \"AI API 聚合网关赞助商\" / \"AI API 集約ゲートウェイスポンサー\"). Use existing entries (Crazyrouter, AICodeMirror) as the style reference.\n\n### 5. Insert ad cards — only if `--with-ad`\n\nFor each of the six files below, locate the existing sponsor card table and **append a new `<tr>...</tr>` row to the same `<table>`** (or, if the existing structure uses sibling `<table>` blocks, append a new sibling table immediately after the last one). Match the exact layout of the most recent existing card.\n\n**Target files & image base path:**\n\n| File | Image path prefix |\n|------|-------------------|\n| `README.md` | `./src/assets/` |\n| `README_zh-CN.md` | `./src/assets/` |\n| `README_ja-JP.md` | `./src/assets/` |\n| `docs/en/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/zh-CN/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/ja-JP/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n\n**Card template (reference, fill brackets per locale):**\n\n```html\n<table>\n<tr>\n<td width=\"180\"><a href=\"<URL>\"><img src=\"<IMG_PREFIX><LOGO_FILENAME>\" alt=\"<NAME>\" width=\"150\"></a></td>\n<td><LOCALIZED_DESCRIPTION_INCLUDING_OFFER_AND_LINK></td>\n</tr>\n</table>\n```\n\n> **Important**: Insert **after** the last existing sponsor card and **before** the next `##` heading (typically `## 📺 ...` or `## ✨ ...`). Preserve surrounding blank lines.\n\n### 6. Add API provider preset — only if `--with-api`\n\nEdit `src/config/api-providers.ts`. Append a new object to the `API_PROVIDER_PRESETS` array, **before the closing `]`**, mirroring the style of existing entries:\n\n```ts\n {\n id: '<PROVIDER_ID>',\n name: '<NAME>',\n supportedCodeTools: [<'claude-code' and/or 'codex'>],\n claudeCode: {\n baseUrl: '<CC_BASE_URL>',\n authType: '<api_key|auth_token>',\n // defaultModels: [...], // include only if user provided\n },\n codex: { // include only if codex is supported\n baseUrl: '<CODEX_BASE_URL>',\n wireApi: 'responses',\n // defaultModel: '...', // include only if user provided\n },\n description: '<EN_DESCRIPTION>',\n },\n```\n\nThen run `pnpm typecheck` to confirm no type errors. If the project has corresponding tests for `getValidProviderIds()` or fixtures, surface them in the summary so the user can update tests if needed.\n\n### 7. Validation\n\n```text\n✓ List bullets present in all 3 READMEs (or skipped due to existing entry)\n✓ If --with-ad: card rows present in all 6 target files (or skipped)\n✓ If --with-api: new preset object syntactically valid; pnpm typecheck passes\n✓ No duplicate ids in API_PROVIDER_PRESETS\n✓ All URLs identical across files\n✓ Logo file exists at src/assets/<filename> when --with-ad is used\n```\n\n### 8. Summary report\n\nPrint a concise summary:\n\n```\n🎉 Sponsor \"<NAME>\" added\n\nSponsor list bullets:\n ✓ README.md\n ✓ README_zh-CN.md\n ✓ README_ja-JP.md\n\nAd cards (--with-ad): [yes/no]\n ✓/⊘ README.md / README_zh-CN.md / README_ja-JP.md\n ✓/⊘ docs/en/index.md / docs/zh-CN/index.md / docs/ja-JP/index.md\n\nAPI preset (--with-api): [yes/no]\n ✓/⊘ src/config/api-providers.ts (id: <PROVIDER_ID>)\n\nSkipped (already present): [list]\n\nNext steps:\n - Review changes with: git diff\n - If --with-api: consider adding tests in tests/ for the new provider\n - Commit with: /zcf-pr or your preferred flow\n```\n\n## Important Notes\n\n⚠️ **Critical Requirements**\n\n- **NEVER** modify any sponsor entries other than the ones being added\n- **NEVER** reorder existing sponsors\n- **ALWAYS** keep the three locale READMEs in sync (same bullet count, same URL, semantically equivalent text)\n- **ALWAYS** verify logo file existence under `src/assets/` before writing ad cards\n- **ALWAYS** validate the API preset by running `pnpm typecheck` after editing\n- **DO NOT** create commits or push — leave that to the user / `/zcf-pr`\n- **DO NOT** invent new section headings; reuse the exact existing ones (`【Corporate Sponsors】` / `【企业赞助商】` / `【企業スポンサー】`)\n\n📌 **Style Reference**\n\nWhen in doubt, copy the structure of the most recent existing sponsor entry (currently **Crazyrouter**) — it represents the canonical layout for both bullet entries and ad cards across all six target documents.\n\n🔍 **Idempotency**\n\nRe-running with the same `--name` and `--url` MUST be a no-op. Detection is by exact match on either NAME or URL within the relevant section.\n\n---\n\n**Now starting sponsor onboarding...**\n","frontmatter":{"name":"zcf-add-sponsor","description":"Quickly add a new corporate sponsor to ZCF — sponsor list by default, with optional API preset and documentation ad placements","disable-model-invocation":true,"allowed-tools":"Read(**), Write(**), Edit(**), Exec(ls, cat, grep, rg, sed, awk, file, mv, pnpm, node, git)","allowedTools":["Read(**),","Write(**),","Edit(**),","Exec(ls,","cat,","grep,","rg,","sed,","awk,","file,","mv,","pnpm,","node,","git)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Write(**),","Edit(**),","Exec(ls,","cat,","grep,","rg,","sed,","awk,","file,","mv,","pnpm,","node,","git)"],"isInternal":false,"tokens":2781,"sizeBytes":10424},{"name":"SKILL.md","path":".claude/skills/zcf-pr/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/.claude/skills/zcf-pr/SKILL.md","title":"zcf-pr","category":"anthropic-skill","format":"markdown","content":"---\nname: zcf-pr\ndescription: Create pull request based on current branch changes\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF PR - Create Pull Request from Current Branch\n\nCreate pull request based on current branch changes and generate standardized PR description.\n\n## Usage\n\n```bash\n/zcf-pr [--base <branch>] [--draft] [--title <title>]\n```\n\n## Parameters\n\n- `--base <branch>`: Target base branch (default: main)\n- `--draft`: Create as draft pull request\n- `--title <title>`: Custom PR title\n\n## Context\n\n- Analyze current branch changes since divergence from base branch\n- Generate PR description following project template\n- Support both English and Chinese descriptions\n- Auto-detect change types and categorize appropriately\n- Create PR using GitHub CLI with comprehensive template\n\n## Your Role\n\nYou are a professional pull request management assistant responsible for:\n\n1. Analyzing branch changes\n2. Categorizing change types automatically\n3. Generating standardized PR descriptions\n4. Creating pull requests with proper templates\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nBASE_BRANCH=\"main\"\nIS_DRAFT=false\nCUSTOM_TITLE=\"\"\n\n# Parse arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --base)\n BASE_BRANCH=\"$2\"\n shift 2\n ;;\n --draft)\n IS_DRAFT=true\n shift\n ;;\n --title)\n CUSTOM_TITLE=\"$2\"\n shift 2\n ;;\n *)\n echo \"❌ Unknown parameter: $1\"\n echo \"Usage: /zcf-pr [--base <branch>] [--draft] [--title <title>]\"\n echo \"Examples:\"\n echo \" /zcf-pr # Create PR to main\"\n echo \" /zcf-pr --base develop # Create PR to develop\"\n echo \" /zcf-pr --draft # Create draft PR\"\n echo \" /zcf-pr --title 'Bug Fix' # Custom title\"\n exit 1\n ;;\n esac\ndone\n\necho \"🚀 Creating PR from current branch to $BASE_BRANCH\"\nif [ \"$IS_DRAFT\" = true ]; then\n echo \"📝 Creating as draft PR\"\nfi\nif [ -n \"$CUSTOM_TITLE\" ]; then\n echo \"📝 Custom title: $CUSTOM_TITLE\"\nfi\n```\n\n### 2. Check Working Directory Status\n\n```bash\n# Check if we're in a git repository\nif [ ! -d \".git\" ]; then\n echo \"❌ Error: Not in a git repository\"\n exit 1\nfi\n\n# Get current branch\nCURRENT_BRANCH=$(git branch --show-current)\nif [ -z \"$CURRENT_BRANCH\" ]; then\n echo \"❌ Error: Could not determine current branch\"\n exit 1\nfi\n\n# Check if current branch is same as base branch\nif [ \"$CURRENT_BRANCH\" = \"$BASE_BRANCH\" ]; then\n echo \"❌ Error: Cannot create PR from $BASE_BRANCH to $BASE_BRANCH\"\n echo \"Please switch to a feature branch first\"\n exit 1\nfi\n\n# Check for uncommitted changes\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Warning: You have uncommitted changes\"\n echo \"Please commit your changes before creating a PR\"\n echo \"\"\n git status --short\n echo \"\"\n echo \"Run the following commands to commit your changes:\"\n echo \" git add .\"\n echo \" git commit -m 'Your commit message'\"\n exit 1\nfi\n\necho \"✅ Branch status OK: $CURRENT_BRANCH\"\n```\n\n### 3. Analyze Branch Changes\n\n```bash\n# Check if base branch exists\nif ! git rev-parse --verify \"$BASE_BRANCH\" >/dev/null 2>&1; then\n echo \"❌ Error: Base branch '$BASE_BRANCH' does not exist\"\n exit 1\nfi\n\n# Get commit history since divergence\necho \"📊 Analyzing changes from $BASE_BRANCH...\"\n\n# Find common ancestor\nMERGE_BASE=$(git merge-base \"$BASE_BRANCH\" HEAD)\nif [ -z \"$MERGE_BASE\" ]; then\n echo \"❌ Error: Could not find common ancestor with $BASE_BRANCH\"\n exit 1\nfi\n\n# Get commits since divergence\nCOMMITS=$(git log $MERGE_BASE..HEAD --oneline)\nCOMMIT_COUNT=$(echo \"$COMMITS\" | wc -l | tr -d ' ')\n\nif [ \"$COMMIT_COUNT\" -eq 0 ]; then\n echo \"❌ Error: No commits found since divergence from $BASE_BRANCH\"\n exit 1\nfi\n\necho \"📝 Found $COMMIT_COUNT commit(s):\"\necho \"$COMMITS\"\necho \"\"\n\n# Analyze file changes\necho \"📁 File change statistics:\"\ngit diff --stat $MERGE_BASE..HEAD\n\n# Get changed files\nCHANGED_FILES=$(git diff --name-only $MERGE_BASE..HEAD)\necho \"\"\necho \"📋 Changed files:\"\necho \"$CHANGED_FILES\"\n```\n\n### 4. Categorize Changes\n\n```bash\n# Analyze changes to determine type and scope\necho \"\"\necho \"🔍 Analyzing change categories...\"\n\nBUG_FIX=false\nNEW_FEATURE=false\nBREAKING_CHANGE=false\nDOCUMENTATION=false\nTESTS=false\n\n# Analyze commits for change indicators\nif echo \"$COMMITS\" | grep -E \"(fix|bug|error|issue|problem)\" >/dev/null; then\n BUG_FIX=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(feat|add|new|create|implement)\" >/dev/null; then\n NEW_FEATURE=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(break|change|remove|delete|major)\" >/dev/null; then\n BREAKING_CHANGE=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt|rst)$\" >/dev/null; then\n DOCUMENTATION=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"(test|spec)\\.\" >/dev/null; then\n TESTS=true\nfi\n\n# Show analysis results\necho \"📊 Change type analysis:\"\nif [ \"$BUG_FIX\" = true ]; then echo \" ✅ Bug fix detected\"; fi\nif [ \"$NEW_FEATURE\" = true ]; then echo \" ✅ New feature detected\"; fi\nif [ \"$BREAKING_CHANGE\" = true ]; then echo \" ✅ Breaking change detected\"; fi\nif [ \"$DOCUMENTATION\" = true ]; then echo \" ✅ Documentation update detected\"; fi\nif [ \"$TESTS\" = true ]; then echo \" ✅ Test updates detected\"; fi\n```\n\n### 5. Generate PR Title\n\n```bash\n# Generate PR title\nif [ -n \"$CUSTOM_TITLE\" ]; then\n PR_TITLE=\"$CUSTOM_TITLE\"\nelse\n # Auto-generate title from first commit\n FIRST_COMMIT=$(echo \"$COMMITS\" | tail -1)\n\n # Clean up commit message for PR title\n if echo \"$FIRST_COMMIT\" | grep -E \"^(feat|fix|docs|style|refactor|test|chore)(\\(.+\\))?: \" >/dev/null; then\n # Use conventional commit format\n PR_TITLE=$(echo \"$FIRST_COMMIT\" | sed 's/^[a-f0-9]\\+ //')\n else\n # Fallback to simple format\n PR_TITLE=\"$CURRENT_BRANCH\"\n fi\nfi\n\necho \"📝 PR Title: $PR_TITLE\"\n```\n\n### 6. Generate PR Description\n\n```bash\n# Generate comprehensive PR description\necho \"📋 Generating PR description...\"\n\n# Generate change summary\nCHANGE_SUMMARY=\"\"\nif [ \"$BUG_FIX\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Bug fixes and error handling improvements\\n\"\nfi\nif [ \"$NEW_FEATURE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- New features and functionality additions\\n\"\nfi\nif [ \"$BREAKING_CHANGE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Breaking changes requiring attention\\n\"\nfi\nif [ \"$DOCUMENTATION\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Documentation updates and improvements\\n\"\nfi\nif [ \"$TESTS\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Test coverage and quality improvements\\n\"\nfi\n\n# Generate file change summary\nFILE_CHANGES=\"\"\nfor file in $CHANGED_FILES; do\n FILE_CHANGES=\"${FILE_CHANGES}- \\`$file\\`\\n\"\ndone\n\n# Build complete PR description\nPR_DESCRIPTION=$(cat <<EOF\n## Description\n\nThis PR includes changes from branch \\`$CURRENT_BRANCH\\` with $COMMIT_COUNT commit(s) since divergence from \\`$BASE_BRANCH\\`.\n\n### Key Changes:\n\n$CHANGE_SUMMARY\n\n### Files Modified:\n\n$FILE_CHANGES\n\n## Type of Change\n\nEOF\n)\n\n# Add checkboxes based on analysis\nif [ \"$BUG_FIX\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Bug fix\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Bug fix\\n\"\nfi\n\nif [ \"$NEW_FEATURE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] New feature\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] New feature\\n\"\nfi\n\nif [ \"$BREAKING_CHANGE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Breaking change\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Breaking change\\n\"\nfi\n\nif [ \"$DOCUMENTATION\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Documentation update\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Documentation update\\n\"\nfi\n\n# Add testing section\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Testing\n\n- [x] Code changes tested\n- [x] No new warnings introduced\n- [x] Code follows style guidelines\"\n\nif [ \"$TESTS\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [x] Tests added/updated\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [ ] Tests added/updated\"\nfi\n\n# Add checklist\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Checklist\n\n- [x] Self-review completed\n- [x] Documentation updated (if applicable)\n- [x] No new warnings introduced\n- [x] Code follows project guidelines\n\n## Additional Information\n\n**Branch:** \\`$CURRENT_BRANCH\\` → \\`$BASE_BRANCH\\`\n**Commits:** $COMMIT_COUNT\n**Files Changed:** $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\n\n### Commit History:\n\n\\`\\`\\`\n$COMMITS\n\\`\\`\\`\n\n---\n🤖 Generated with /zcf-pr command\nEOF\n\necho \"✅ PR description generated\"\n```\n\n### 7. Push Branch and Create PR\n\n```bash\n# Check if branch exists on remote\nif ! git ls-remote --heads origin \"$CURRENT_BRANCH\" >/dev/null 2>&1; then\n echo \"📤 Pushing branch to remote...\"\n git push -u origin \"$CURRENT_BRANCH\"\nelse\n echo \"📤 Branch already exists on remote, ensuring it's up to date...\"\n git push origin \"$CURRENT_BRANCH\"\nfi\n\n# Create PR using gh CLI\necho \"📋 Creating pull request...\"\n\nPR_OPTIONS=\"--title '$PR_TITLE' --body '$PR_DESCRIPTION'\"\n\nif [ \"$IS_DRAFT\" = true ]; then\n PR_OPTIONS=\"$PR_OPTIONS --draft\"\nfi\n\n# Execute gh pr create command\nPR_URL=$(eval \"gh pr create --base $BASE_BRANCH $PR_OPTIONS\")\n\nif [ $? -eq 0 ]; then\n echo \"\"\n echo \"✅ Pull request created successfully!\"\n echo \"🔗 PR URL: $PR_URL\"\n echo \"\"\n echo \"📋 PR Details:\"\n echo \" Title: $PR_TITLE\"\n echo \" From: $CURRENT_BRANCH\"\n echo \" To: $BASE_BRANCH\"\n echo \" Commits: $COMMIT_COUNT\"\n echo \" Files: $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\"\n echo \"\"\n echo \"⚠️ Please review the PR and add any additional information as needed\"\nelse\n echo \"❌ Failed to create pull request\"\n echo \"Please check GitHub CLI authentication and permissions\"\n exit 1\nfi\n```\n\n## Complete Workflow Summary\n\n1. **Parameter Parsing**: Parse base branch, draft mode, and custom title options\n2. **Branch Validation**: Check current branch status and ensure it's different from base branch\n3. **Change Analysis**: Analyze commits and file changes since divergence from base branch\n4. **Categorization**: Auto-detect change types (bug fix, feature, breaking change, docs, tests)\n5. **Title Generation**: Generate appropriate PR title or use custom title\n6. **Description Generation**: Create comprehensive PR description following project template\n7. **Branch Push**: Ensure branch is available on remote repository\n8. **PR Creation**: Create pull request using GitHub CLI with all details\n\n## Important Notes\n\n⚠️ **Prerequisites**:\n\n- **GitHub CLI (`gh`)**: Must be installed and authenticated\n- **Clean working directory**: All changes must be committed before PR creation\n- **Remote branch**: Current branch must be pushed to remote repository\n- **Base branch**: Target branch must exist and be accessible\n\n### Best Practices:\n\n- Ensure commit messages follow conventional commit format\n- Test all changes before creating PR\n- Review auto-generated PR description for accuracy\n- Add any additional context specific to your changes\n- Check that all tests pass in CI/CD pipeline\n\n### Change Detection Logic:\n\nThe command automatically categorizes changes based on:\n\n- **Commit messages**: Keywords like \"feat\", \"fix\", \"break\", \"docs\", \"test\"\n- **File patterns**: `.md/.txt` for docs, `(test|spec)\\.` for tests\n- **File extensions**: TypeScript, JavaScript, JSON, etc.\n\n### Example Outputs:\n\n```bash\n# Standard PR to main\n/zcf-pr\n# → Creates PR: \"feat: add new feature\" with full description\n\n# PR to develop branch\n/zcf-pr --base develop\n# → Creates PR to develop branch instead of main\n\n# Draft PR\n/zcf-pr --draft\n# → Creates draft PR for initial review\n\n# Custom title\n/zcf-pr --title \"Critical bug fix for authentication\"\n# → Uses custom title instead of auto-generated one\n```\n\n---\n\n**Now creating pull request...**","frontmatter":{"name":"zcf-pr","description":"Create pull request based on current branch changes","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git, pnpm, node, date, cat, gh)","allowedTools":["Read(**),","Exec(git,","pnpm,","node,","date,","cat,","gh)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git,","pnpm,","node,","date,","cat,","gh)"],"isInternal":false,"tokens":3130,"sizeBytes":11854},{"name":"SKILL.md","path":".claude/skills/zcf-release/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/.claude/skills/zcf-release/SKILL.md","title":"zcf-release","category":"anthropic-skill","format":"markdown","content":"---\nname: zcf-release\ndescription: Automate version release and code commit using changeset\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF Release - Automated Release and Commit\n\nAutomate version release and code commit using changeset.\n\n## Usage\n\n```bash\n/zcf-release [-p|-mi|-ma|<version>]\n```\n\n## Parameters\n\n- `-p` or `--patch`: Patch version (default) - bug fixes, minor changes\n- `-mi` or `--minor`: Minor version - new features, backward compatible\n- `-ma` or `--major`: Major version - breaking changes, incompatible\n- `<version>`: Specific version number (e.g., 1.2.3, 2.0.0-beta.1) - directly use provided version\n\n## Context\n\n- Automatically analyze code changes and generate bilingual CHANGELOG\n- Use changeset for version management\n- Create release branch and pull request for protected main branch\n- Auto commit code changes (NO manual tags)\n- Support GitHub Actions auto publish to npm with automatic tagging after PR merge\n\n## Your Role\n\nYou are a professional release management assistant responsible for:\n\n1. Analyzing code changes\n2. Generating standardized CHANGELOG\n3. Executing version release process\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nVERSION_TYPE=\"patch\" # Default to patch version\nSPECIFIC_VERSION=\"\" # For user-specified exact version\n\n# Check if argument looks like a version number (matches semver pattern)\nif [[ \"$ARGUMENTS\" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+([.-].*)?$ ]]; then\n SPECIFIC_VERSION=\"$ARGUMENTS\"\n VERSION_TYPE=\"custom\"\n echo \"🚀 Preparing to release exact version: $SPECIFIC_VERSION\"\nelse\n case \"$ARGUMENTS\" in\n -p|--patch)\n VERSION_TYPE=\"patch\"\n ;;\n -mi|--minor)\n VERSION_TYPE=\"minor\"\n ;;\n -ma|--major)\n VERSION_TYPE=\"major\"\n ;;\n \"\")\n VERSION_TYPE=\"patch\"\n ;;\n *)\n echo \"❌ Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-release [-p|-mi|-ma|<version>]\"\n echo \"Examples:\"\n echo \" /zcf-release -p # Patch version bump\"\n echo \" /zcf-release -mi # Minor version bump\"\n echo \" /zcf-release -ma # Major version bump\"\n echo \" /zcf-release 1.2.3 # Exact version\"\n echo \" /zcf-release 2.0.0-beta.1 # Pre-release version\"\n exit 1\n ;;\n esac\n echo \"🚀 Preparing to release $VERSION_TYPE version\"\nfi\n```\n\n### 2. Check Working Directory Status\n\nCheck if the current working directory meets release conditions:\n\n```bash\n# Ensure in project root directory\nif [ ! -f \"package.json\" ]; then\n echo \"❌ Error: package.json not found, please run in project root\"\n exit 1\nfi\n\n# Check for uncommitted changes and handle automatically\nHAS_UNCOMMITTED=false\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Detected uncommitted changes:\"\n git status --short\n echo \"\"\n HAS_UNCOMMITTED=true\nfi\n\necho \"✅ Working directory status OK\"\n```\n\n### 3. Analyze Version Changes\n\nAnalyze all changes since last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"📊 No previous version tag found, analyzing all commits\"\n COMMITS=$(git log --oneline)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n COMMITS=$(git log $LAST_TAG..HEAD --oneline)\nfi\n\n# Show commit history\necho -e \"\\n📝 Changes:\"\necho \"$COMMITS\"\n\n# Analyze file changes\necho -e \"\\n📁 File change statistics:\"\nif [ -z \"$LAST_TAG\" ]; then\n git diff --stat\nelse\n git diff --stat $LAST_TAG..HEAD\nfi\n```\n\n### 4. Generate CHANGELOG Content\n\nBased on code change analysis, I will generate CHANGELOG following these standards:\n\n**Format Requirements**:\n\n1. English description first, Chinese description second\n2. No mixing Chinese and English on the same line\n3. Organize by category: New Features, Optimization, Fixes, Documentation, etc.\n4. Each entry should be concise and clear\n\n**Example Format**:\n\n```markdown\n## New Features\n\n- Add technical execution guidelines with command best practices\n- Support automated release command /zcf-release\n- Automatic quote handling for Windows paths\n\n## 新功能\n\n- 添加技术执行指南文档，提供命令执行最佳实践\n- 支持自动化发版命令 /zcf-release\n- Windows 路径自动加引号处理\n\n## Optimization\n\n- Prioritize ripgrep for better search performance\n- Improve template file organization\n\n## 优化\n\n- 优先使用 ripgrep 提升搜索性能\n- 改进模板文件组织结构\n\n## Fixes\n\n- Fix Windows path backslash escaping issue\n\n## 修复\n\n- 修复 Windows 路径反斜杠丢失问题\n```\n\n### 5. Create Changeset\n\nCreate changeset file based on analysis:\n\n```bash\n# Generate timestamp\nTIMESTAMP=$(date +%Y%m%d%H%M%S)\nCHANGESET_FILE=\".changeset/release-$TIMESTAMP.md\"\n\n# Create changeset file\necho \"📝 Creating changeset file...\"\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n # For specific version, use the exact version number\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $SPECIFIC_VERSION\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with exact version: $SPECIFIC_VERSION\"\nelse\n # For version type (patch/minor/major), use the type\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $VERSION_TYPE\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with version type: $VERSION_TYPE\"\nfi\n```\n\n### 6. Update Version Number\n\nUse changeset to update version number and CHANGELOG:\n\n```bash\necho \"🔄 Updating version number and CHANGELOG...\"\npnpm changeset version\n\n# Note: The changeset version command will automatically:\n# 1. Update package.json version\n# 2. Generate/update CHANGELOG.md\n# 3. DELETE the temporary changeset file in .changeset/ directory\n# No manual cleanup needed!\n\n# Get new version number\nNEW_VERSION=$(node -p \"require('./package.json').version\")\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n echo \"📦 New version set to: v$NEW_VERSION (specified: $SPECIFIC_VERSION)\"\nelse\n echo \"📦 New version: v$NEW_VERSION\"\nfi\n\n# Show CHANGELOG update\necho -e \"\\n📋 CHANGELOG has been updated, please review the content\"\necho \"✅ Temporary changeset file has been automatically deleted\"\n```\n\n### 7. Create Release Branch and Handle Commits\n\nCreate release branch first, then handle commits separately to avoid polluting main branch:\n\n````bash\necho \"🚀 Creating release branch...\"\n\n# Create and switch to release branch\nRELEASE_BRANCH=\"release/v$NEW_VERSION\"\ngit checkout -b \"$RELEASE_BRANCH\"\n\n# Handle uncommitted changes first (if any)\nif [ \"$HAS_UNCOMMITTED\" = true ]; then\n echo \"📝 Committing pre-release changes...\"\n \n # Stage only the uncommitted changes (exclude changeset modifications)\n git add .\n git reset HEAD package.json CHANGELOG.md 2>/dev/null || true\n \n # Check if there are still changes to commit after reset\n if ! git diff --quiet --staged; then\n # Analyze the staged changes to generate appropriate commit message\n echo \"🔍 Analyzing uncommitted changes...\"\n CHANGED_FILES=$(git diff --staged --name-only)\n \n # Generate commit message based on changed files\n COMMIT_TYPE=\"chore\"\n COMMIT_SCOPE=\"\"\n COMMIT_DESCRIPTION=\"pre-release changes\"\n \n # Analyze file patterns to determine commit type and scope\n if echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -i \"readme\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"readme\"\n COMMIT_DESCRIPTION=\"update README documentation\"\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.claude/\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"commands\"\n COMMIT_DESCRIPTION=\"update command documentation\"\n else\n COMMIT_TYPE=\"docs\"\n COMMIT_DESCRIPTION=\"update documentation\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.(ts|js|tsx|jsx)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -E \"test|spec\" >/dev/null; then\n COMMIT_TYPE=\"test\"\n COMMIT_DESCRIPTION=\"update tests\"\n else\n COMMIT_TYPE=\"feat\"\n COMMIT_DESCRIPTION=\"code changes\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.json$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep \"package\" >/dev/null; then\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update dependencies\"\n else\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update configuration\"\n fi\n fi\n \n # Build commit message\n if [ -n \"$COMMIT_SCOPE\" ]; then\n COMMIT_MSG=\"${COMMIT_TYPE}(${COMMIT_SCOPE}): ${COMMIT_DESCRIPTION}\"\n else\n COMMIT_MSG=\"${COMMIT_TYPE}: ${COMMIT_DESCRIPTION}\"\n fi\n \n # Add file list to commit body\n COMMIT_BODY=\"\"\n for file in $CHANGED_FILES; do\n COMMIT_BODY=\"${COMMIT_BODY}- Update ${file}\n\"\n done\n COMMIT_BODY=\"${COMMIT_BODY}\n🤖 Generated with [Claude Code](https://claude.ai/code)\n \n # Create the commit\n git commit -m \"${COMMIT_MSG}\n\n${COMMIT_BODY}\"\n \n echo \"✅ Pre-release changes committed: $COMMIT_MSG\"\n else\n echo \"ℹ️ No additional changes to commit after version update\"\n fi\nfi\n\necho \"💾 Committing release version changes...\"\n\n# Add version-related changes\ngit add package.json CHANGELOG.md\n\n# Create release version commit\ngit commit -m \"chore: release v$NEW_VERSION\n\n- Update version to $NEW_VERSION\n- Update CHANGELOG.md\n- Generated by /zcf-release command\"\n\n# Push release branch to remote and set upstream tracking\ngit push -u origin \"$RELEASE_BRANCH\"\n\n# If push fails due to conflicts, use force-with-lease to safely overwrite\n# git push --force-with-lease origin \"$RELEASE_BRANCH\"\n\n# Set upstream tracking if not set automatically\ngit branch --set-upstream-to=origin/$RELEASE_BRANCH $RELEASE_BRANCH\n\n### 8. Create Pull Request\n\n```bash\necho \"📋 Creating pull request...\"\n\n# Create pull request using gh CLI following the project's PR template\ngh pr create --title \"🚀 Release v$NEW_VERSION\" --body \"$(cat <<'EOF'\n## Description\n\nRelease version v$NEW_VERSION with automated version bump and CHANGELOG update.\n\nThis release includes important changes, please review CHANGELOG.md for details.\n\n## Type of Change\n\n- [x] New feature\n- [ ] Bug fix\n- [ ] Breaking change\n- [x] Documentation update\n\n## Testing\n\n- [x] Tests added/updated\n- [x] All tests pass\n- [x] Coverage maintained\n\n## Checklist\n\n- [x] Code follows style guidelines\n- [x] Self-review completed\n- [x] Documentation updated\n- [x] No new warnings introduced\n\n## Release Notes\n\n⚠️ **IMPORTANT**: After merge, GitHub Actions will automatically:\n- Create release tag\n- Publish to npm \n- Generate GitHub Release\n\n🤖 Generated by /zcf-release command\nEOF\n)\"\n\necho -e \"\\n✅ Release preparation complete!\"\necho \"📦 Version v$NEW_VERSION is ready\"\necho \"🔗 Pull request created successfully\"\necho \"\"\necho \"⚠️ IMPORTANT: Review and merge the PR to trigger the release\"\necho \"⚠️ Do NOT create or push tags manually!\"\necho \"🤖 After PR merge, GitHub Actions will automatically:\"\necho \" - Create the release tag\"\necho \" - Publish to npm\"\necho \" - Generate GitHub Release\"\necho \"👀 View release status: https://github.com/UfoMiao/zcf/actions\"\n````\n\n## Complete Workflow Summary\n\n1. **Preparation Phase**: Check parameters (version type or exact version), working directory status\n2. **Analysis Phase**: Analyze commit history and file changes\n3. **Generation Phase**: Create bilingual CHANGELOG\n4. **Execution Phase**: Update version (automatic bump or exact version)\n5. **Branch Creation Phase**: Create release branch BEFORE committing\n6. **Commit Phase**: Commit changes on release branch\n7. **PR Creation Phase**: Push release branch and create pull request\n8. **Review & Release Phase**: Manual PR review and merge, then GitHub Actions auto publish\n\n## Important Notes\n\n⚠️ **CRITICAL**: **NEVER create or push Git tags manually!** GitHub Actions will automatically:\n\n- Create the version tag after successful PR merge\n- Generate GitHub Release\n- Publish to npm registry\n\nManual tags will cause conflicts with the automated release process!\n\n### New Protected Branch Workflow:\n\n- 🛡️ **Main branch is protected**: Cannot push directly to main\n- 🌿 **Release branch created**: Automatic creation of `release/v{version}` branch\n- 📋 **Pull Request required**: All releases must go through PR review process\n- ✅ **Manual approval needed**: PR must be reviewed and merged manually\n- 🤖 **Auto-release after merge**: GitHub Actions triggers after PR merge\n\n### Additional Notes:\n\n- Ensure all code has been tested before running release command\n- CHANGELOG must follow bilingual format standards\n- When using version types (-p/-mi/-ma), choose the correct type for your changes\n- When providing exact version numbers, ensure they follow semantic versioning (e.g., 1.2.3, 2.0.0-beta.1)\n- Exact version numbers bypass automatic version determination - use carefully\n- Carefully review CHANGELOG content in the created PR before merging\n- **No manual cleanup needed**: `changeset version` automatically deletes temporary changeset files\n- The `.changeset/` directory should only contain config files, not temporary release files\n- **Requires `gh` CLI**: Ensure GitHub CLI is installed and authenticated for PR creation\n\n**Version Parameter Examples**:\n- `/zcf-release` or `/zcf-release -p` - Auto patch bump (2.9.11 → 2.9.12)\n- `/zcf-release -mi` - Auto minor bump (2.9.11 → 2.10.0) \n- `/zcf-release -ma` - Auto major bump (2.9.11 → 3.0.0)\n- `/zcf-release 1.5.0` - Exact version (→ 1.5.0)\n- `/zcf-release 3.0.0-alpha.1` - Pre-release version (→ 3.0.0-alpha.1)\n\n---\n\n**Now starting release process...**\n","frontmatter":{"name":"zcf-release","description":"Automate version release and code commit using changeset","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git, pnpm, node, date, cat, gh)","allowedTools":["Read(**),","Exec(git,","pnpm,","node,","date,","cat,","gh)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git,","pnpm,","node,","date,","cat,","gh)"],"isInternal":false,"tokens":3476,"sizeBytes":13746},{"name":"SKILL.md","path":".claude/skills/zcf-update-docs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/.claude/skills/zcf-update-docs/SKILL.md","title":"zcf-update-docs","category":"anthropic-skill","format":"markdown","content":"---\nname: zcf-update-docs\ndescription: Automatically check code changes since last tag and update documentation in docs/ directory (en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, cat, grep, diff)\n---\n\n# ZCF Update Docs - Documentation Synchronization\n\nAutomatically check code changes since last tag and update documentation in `docs/` directory (multilingual: en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation.\n\n## Usage\n\n```bash\n/zcf-update-docs [--check-only]\n```\n\n## Parameters\n\n- `--check-only`: Only check for inconsistencies without making updates (dry run)\n\n## Context\n\n- Analyze all code changes since the last Git tag\n- Check if documentation needs updates in docs/ directory structure\n- Ensure CLI commands, features, and workflows documentation match actual code\n- Maintain multilingual documentation consistency across en, zh-CN, ja-JP\n- Update CLAUDE.md for development-related changes\n\n## Your Role\n\nYou are a professional documentation maintainer responsible for:\n\n1. Analyzing code changes and their impact on documentation\n2. Identifying documentation sections that need updates\n3. Ensuring documentation accuracy and consistency\n4. Maintaining multilingual synchronization\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nCHECK_ONLY=false # Default to update mode\n\ncase \"$ARGUMENTS\" in\n --check-only)\n CHECK_ONLY=true\n echo \"📋 Running in check-only mode (no files will be modified)\"\n ;;\n \"\")\n CHECK_ONLY=false\n echo \"✏️ Running in update mode\"\n ;;\n *)\n echo \"Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-update-docs [--check-only]\"\n exit 1\n ;;\nesac\n```\n\n### 2. Get Changes Since Last Tag\n\nAnalyze all changes since the last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"⚠️ No previous version tag found, analyzing all files\"\n FILES_CHANGED=$(git ls-files)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n FILES_CHANGED=$(git diff --name-only $LAST_TAG..HEAD)\nfi\n\n# Categorize changed files\necho -e \"\\n📁 Analyzing changed files...\"\n```\n\n### 3. Identify Documentation Update Areas\n\nBased on file changes, determine which documentation files in `docs/` need updates:\n\n**Code Changes → Documentation Mapping:**\n\n1. **CLI Commands** (`src/commands/*.ts`) → `docs/{lang}/cli/`\n - `src/commands/init.ts` → `cli/init.md` - Installation and initialization\n - `src/commands/menu.ts` → `cli/menu.md` - Interactive menu system\n - `src/commands/update.ts` → `cli/update.md` - Update workflows\n - `src/commands/ccr.ts` → `cli/ccr.md` - CCR proxy management\n - `src/commands/ccu.ts` → `cli/ccu.md` - Usage analysis\n - `src/commands/uninstall.ts` → `cli/uninstall.md` - Uninstallation\n - `src/commands/config-switch.ts` → `cli/config-switch.md` - Config switching\n - `src/commands/check-updates.ts` → `cli/check-updates.md` - Version check\n\n2. **Features** → `docs/{lang}/features/`\n - `src/utils/installer.ts`, `src/utils/claude-config.ts` → `features/claude-code.md`\n - `src/utils/code-tools/codex*` → `features/codex.md`\n - `src/config/workflows.ts` → `features/workflows.md`\n - `src/config/mcp-services.ts` → `features/mcp.md`\n - `src/utils/ccr/` → `features/ccr.md`\n - `src/utils/cometix/` → `features/cometix.md`\n - `src/utils/config.ts` → `features/multi-config.md`\n\n3. **Workflows** (`src/config/workflows.ts`, `templates/*/workflow/`) → `docs/{lang}/workflows/`\n - Workflow definitions → `workflows/index.md`\n - Specific workflow templates → `workflows/{workflow-name}.md`\n\n4. **Advanced Configuration** → `docs/{lang}/advanced/`\n - `src/types/config.ts`, `src/utils/config.ts` → `advanced/configuration.md`\n - `src/config/api-providers.ts` → `advanced/api-providers.md`\n - `templates/` → `advanced/templates.md`\n - `src/i18n/` → `advanced/i18n.md`\n\n5. **Getting Started** → `docs/{lang}/getting-started/`\n - `src/commands/init.ts`, `src/utils/installer.ts` → `getting-started/installation.md`\n - General introduction → `getting-started/index.md`\n\n6. **Development** → `docs/{lang}/development/` and `CLAUDE.md`\n - Architecture changes → `development/architecture.md` + `CLAUDE.md`\n - Testing changes → `development/testing.md` + `CLAUDE.md`\n - Contributing guidelines → `development/contributing.md`\n - Package.json scripts → `CLAUDE.md`\n\n### 4. Check Current Documentation\n\nRead and analyze current documentation structure:\n\n```bash\n# Check if documentation directories exist\nDOCS_LANGS=(\"en\" \"zh-CN\" \"ja-JP\")\nDOCS_CATEGORIES=(\n \"getting-started\"\n \"cli\"\n \"features\"\n \"workflows\"\n \"advanced\"\n \"best-practices\"\n \"development\"\n)\n\necho \"📁 Checking documentation structure...\"\n\nfor LANG in \"${DOCS_LANGS[@]}\"; do\n if [ ! -d \"docs/$LANG\" ]; then\n echo \"❌ Warning: docs/$LANG directory not found\"\n else\n echo \"✅ Found: docs/$LANG/\"\n for CATEGORY in \"${DOCS_CATEGORIES[@]}\"; do\n if [ ! -d \"docs/$LANG/$CATEGORY\" ]; then\n echo \" ⚠️ Missing category: $CATEGORY\"\n else\n echo \" ✅ Category: $CATEGORY\"\n fi\n done\n fi\ndone\n\n# Check CLAUDE.md\nif [ ! -f \"CLAUDE.md\" ]; then\n echo \"❌ Warning: CLAUDE.md not found\"\nelse\n echo \"✅ Found: CLAUDE.md\"\nfi\n```\n\n### 5. Verify CLI Commands Consistency\n\nCompare CLI commands implementation with documentation:\n\n**Check Points:**\n- Command names, options, and parameters\n- Command descriptions and usage examples\n- Interactive menu options and flow\n- Keyboard shortcuts and navigation\n- Exit and back options\n- Multilingual prompt translations\n\n**Code Sources → Documentation Files:**\n- `src/commands/menu.ts`, `src/i18n/locales/*/menu.json` → `docs/{lang}/cli/menu.md`\n- `src/commands/init.ts`, `src/i18n/locales/*/cli.json` → `docs/{lang}/cli/init.md`\n- `src/commands/update.ts` → `docs/{lang}/cli/update.md`\n- `src/commands/ccr.ts` → `docs/{lang}/cli/ccr.md`\n- `src/commands/ccu.ts` → `docs/{lang}/cli/ccu.md`\n- `src/commands/uninstall.ts` → `docs/{lang}/cli/uninstall.md`\n- `src/commands/config-switch.ts` → `docs/{lang}/cli/config-switch.md`\n- `src/commands/check-updates.ts` → `docs/{lang}/cli/check-updates.md`\n\n### 6. Verify Features Documentation\n\nEnsure features documentation matches actual implementation:\n\n**Check Points:**\n1. Claude Code configuration capabilities\n2. Codex CLI integration and setup\n3. Workflow system and categories\n4. MCP service integration\n5. CCR proxy management\n6. Cometix status line\n7. Multi-config and backup system\n8. API provider presets\n\n**Code Sources → Documentation Files:**\n- `src/utils/installer.ts`, `src/utils/claude-config.ts` → `docs/{lang}/features/claude-code.md`\n- `src/utils/code-tools/codex*.ts`, `templates/codex/` → `docs/{lang}/features/codex.md`\n- `src/config/workflows.ts` → `docs/{lang}/features/workflows.md`\n- `src/config/mcp-services.ts` → `docs/{lang}/features/mcp.md`\n- `src/utils/ccr/` → `docs/{lang}/features/ccr.md`\n- `src/utils/cometix/` → `docs/{lang}/features/cometix.md`\n- `src/utils/config.ts` → `docs/{lang}/features/multi-config.md`\n\n### 7. Generate Update Report\n\nCreate a detailed report of findings:\n\n```markdown\n## Documentation Update Report\n\n### Files Changed Since $LAST_TAG\n- [List of relevant changed files categorized by module]\n\n### Documentation Files Requiring Updates\n\n#### docs/en/ (English Documentation)\n- [ ] getting-started/installation.md - Installation and setup\n- [ ] cli/*.md - CLI command documentation\n- [ ] features/*.md - Feature descriptions\n- [ ] workflows/*.md - Workflow guides\n- [ ] advanced/*.md - Advanced configuration\n- [ ] development/*.md - Development documentation\n\n#### docs/zh-CN/ (Chinese Documentation)\n- [ ] getting-started/installation.md - 安装和设置\n- [ ] cli/*.md - CLI 命令文档\n- [ ] features/*.md - 功能说明\n- [ ] workflows/*.md - 工作流指南\n- [ ] advanced/*.md - 高级配置\n- [ ] development/*.md - 开发文档\n\n#### docs/ja-JP/ (Japanese Documentation)\n- [ ] getting-started/installation.md - インストールとセットアップ\n- [ ] cli/*.md - CLI コマンドドキュメント\n- [ ] features/*.md - 機能説明\n- [ ] workflows/*.md - ワークフローガイド\n- [ ] advanced/*.md - 高度な設定\n- [ ] development/*.md - 開発ドキュメント\n\n#### CLAUDE.md (Root Development Documentation)\n- [ ] Development commands (package.json scripts)\n- [ ] Architecture and module structure\n- [ ] Testing guidelines and coverage\n- [ ] Workflow system implementation\n- [ ] Code standards and conventions\n\n### Specific Inconsistencies Found\n[Detailed list of mismatches between code and documentation, organized by file]\n```\n\n### 8. Update Documentation Files\n\nIf not in check-only mode, update the documentation:\n\n```bash\nif [ \"$CHECK_ONLY\" = false ]; then\n echo \"📝 Updating documentation files in docs/ directory...\"\n \n # Update docs/en/ (English Documentation)\n # - CLI commands: Update docs/en/cli/*.md based on src/commands/*.ts\n # - Features: Update docs/en/features/*.md based on feature implementations\n # - Workflows: Update docs/en/workflows/*.md based on src/config/workflows.ts\n # - Getting Started: Update docs/en/getting-started/*.md based on installation flow\n # - Advanced: Update docs/en/advanced/*.md based on configuration and templates\n # - Development: Update docs/en/development/*.md based on architecture changes\n # - Use translations from src/i18n/locales/en/*.json\n \n # Update docs/zh-CN/ (Chinese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Chinese translations from src/i18n/locales/zh-CN/*.json\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure technical terms and examples are properly localized\n \n # Update docs/ja-JP/ (Japanese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Japanese translations (maintain consistency with project style)\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure proper Japanese formatting and terminology\n \n # Update CLAUDE.md (Root Development Documentation)\n # - Update development commands if package.json scripts changed\n # - Update architecture section if new modules added\n # - Update testing section if test structure changed\n # - Update workflow system if src/config/workflows.ts changed\n # - Update module index if directory structure changed\n # - Maintain English-only for development documentation\n \n # Update SUMMARY.md for each language\n # - Ensure table of contents matches actual file structure\n # - Update links if files were added/removed/renamed\n # - Maintain consistent ordering across all languages\n \n echo \"✅ Documentation files updated in docs/ directory\"\nelse\n echo \"ℹ️ Check-only mode: No files were modified\"\nfi\n```\n\n### 9. Validation\n\nPerform final validation checks:\n\n```bash\necho -e \"\\n🔍 Performing validation checks...\"\n\n# Check for broken internal links in all language versions\necho \"Checking internal links in docs/en/, docs/zh-CN/, docs/ja-JP/...\"\n\n# Verify SUMMARY.md matches actual file structure\necho \"Validating SUMMARY.md table of contents...\"\n\n# Ensure structure consistency across languages\necho \"Checking structural consistency across en, zh-CN, ja-JP...\"\n\n# Verify code examples still work\necho \"Verifying code examples and command syntax...\"\n\n# Validate markdown formatting\necho \"Validating markdown format...\"\n\n# Check translation completeness\necho \"Checking multilingual translation completeness...\"\n\n# Verify CLI command documentation matches implementation\necho \"Verifying CLI command documentation accuracy...\"\n\n# Validate feature documentation completeness\necho \"Checking feature documentation coverage...\"\n\necho \"✅ Validation complete\"\n```\n\n### 10. Summary Report\n\nGenerate final summary:\n\n```bash\necho -e \"\\n📊 Documentation Update Summary\"\necho \"================================\"\necho \"Files analyzed: [count]\"\necho \"Documentation files updated: [list]\"\necho \"Sections modified: [count]\"\necho \"\"\necho \"Key updates:\"\necho \"- [List major updates]\"\necho \"\"\nif [ \"$CHECK_ONLY\" = true ]; then\n echo \"📋 This was a check-only run. To apply updates, run without --check-only\"\nelse\n echo \"✅ Documentation has been synchronized with code\"\n echo \"📝 Please review the changes before committing\"\nfi\n```\n\n## Documentation Structure Reference\n\n### docs/{lang}/ Directory Structure (en, zh-CN, ja-JP)\n\nEach language directory contains the following categories:\n\n1. **getting-started/** - Installation and quick start\n - `index.md` - Quick start guide\n - `installation.md` - Installation guide (Must match `src/commands/init.ts`)\n\n2. **cli/** - CLI command documentation\n - `index.md` - Commands overview\n - `init.md`, `update.md`, `menu.md`, etc. (Must match `src/commands/*.ts`)\n\n3. **features/** - Feature descriptions\n - `index.md` - Features overview\n - `claude-code.md`, `codex.md`, `workflows.md`, etc. (Must match implementations)\n\n4. **workflows/** - Workflow guides\n - `index.md` - Workflow overview\n - Specific workflow documentation (Must match `src/config/workflows.ts`)\n\n5. **advanced/** - Advanced configuration\n - `configuration.md`, `api-providers.md`, `templates.md`, etc.\n\n6. **best-practices/** - Best practices and tips\n - Usage tips and optimization strategies\n\n7. **development/** - Development documentation\n - `architecture.md`, `contributing.md`, `testing.md`\n\n8. **SUMMARY.md** - Table of contents for each language\n\n### CLAUDE.md Structure (Root Development Documentation)\n\n1. **Project Overview**\n2. **Architecture Overview** (Must match actual module structure)\n3. **Module Index** (Must match src/ directory structure)\n4. **CLI Usage**\n5. **Running and Development** (Must match `package.json` scripts)\n6. **Development Guidelines**\n7. **Testing Strategy**\n8. **AI Team Configuration**\n\n## Important Notes\n\n⚠️ **Critical Requirements:**\n- **ALWAYS** ensure CLI command documentation matches actual implementation in `src/commands/`\n- **ALWAYS** verify feature descriptions match actual code behavior\n- **ALWAYS** maintain structural consistency across all language versions (en, zh-CN, ja-JP)\n- **ALWAYS** update SUMMARY.md when file structure changes\n- **NEVER** remove existing content without verification\n- **NEVER** break markdown formatting or internal links\n- **NEVER** create inconsistency between language versions\n\n📌 **Best Practices:**\n- Use actual i18n translations from `src/i18n/locales/{lang}/*.json`\n- Preserve existing formatting and style conventions\n- Update code examples to reflect current implementation\n- Include new features and commands added since last tag\n- Remove or mark deprecated features that no longer exist\n- Maintain parallel structure across en, zh-CN, ja-JP directories\n- Keep CLAUDE.md focused on development-specific information\n\n🔍 **Validation Checklist:**\n- [ ] CLI command docs match `src/commands/*.ts` implementation\n- [ ] Feature docs match actual feature implementations\n- [ ] Workflow docs match `src/config/workflows.ts` definitions\n- [ ] Installation guide matches `src/commands/init.ts` flow\n- [ ] Configuration docs match types in `src/types/*.ts`\n- [ ] MCP service docs match `src/config/mcp-services.ts`\n- [ ] Structure consistency across en, zh-CN, ja-JP directories\n- [ ] SUMMARY.md matches actual file structure for each language\n- [ ] All internal links are valid and not broken\n- [ ] Code examples and command syntax are correct\n- [ ] Translations use proper i18n strings from codebase\n- [ ] Markdown formatting is valid in all files\n- [ ] Codex integration documentation is comprehensive\n- [ ] CCR, Cometix, CCusage features are accurately documented\n- [ ] API provider presets documentation is up-to-date\n- [ ] CLAUDE.md reflects current architecture and development practices\n\n---\n\n**Now starting documentation update process...**","frontmatter":{"name":"zcf-update-docs","description":"Automatically check code changes since last tag and update documentation in docs/ directory (en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git, cat, grep, diff)","allowedTools":["Read(**),","Exec(git,","cat,","grep,","diff)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git,","cat,","grep,","diff)"],"isInternal":false,"tokens":3977,"sizeBytes":16141},{"name":"SKILL.md","path":"templates/skills/en/bmad-init/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/bmad-init/SKILL.md","title":"bmad-init","category":"anthropic-skill","format":"markdown","content":"---\nname: bmad-init\ndescription: Initialize or update BMad-Method (V6) in your project\ndisable-model-invocation: true\n---\n\n# /bmad-init Command\n\nThis command initializes or updates BMad-Method (V6) in your project.\n\n## When this command is invoked:\n\n1. Check if `_bmad/` directory exists to determine if BMad V6 is already installed\n2. Check for legacy V4 installations (`.bmad-core` or `.bmad-method` directories)\n3. Fresh install executes: `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n4. Existing install executes: `npx bmad-method install --directory . --action quick-update --yes`\n5. Fix installer bug: rename `{output_folder}` to `_bmad-output` (Beta known issue)\n6. Automatically update `.gitignore` (remove V4 entries, add V6 entries)\n7. Display installation results and prompt user for next steps\n\n## Implementation\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// Legacy entries to clean from .gitignore\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug artifact\n]\n\n// V6 .gitignore entries\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// Fix installer bug: {output_folder} not resolved to _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output doesn't exist, simply rename\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (renamed)')\n } else {\n // _bmad-output already exists, merge subdirectories then delete\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ Moved ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ Removed redundant {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // Remove V4 legacy entries\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ Removing legacy entry: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // Add V6 entries\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ Adding new entry: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore is up to date, no changes needed')\n return\n }\n\n // Build new content\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // Ensure trailing newline, then add BMad section\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore ${exists ? 'updated' : 'created'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // Check for legacy V4 installation\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ Legacy BMad V4 installation detected:')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 core directory)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 method directory)')\n console.log('')\n console.log('📌 The V6 installer will handle legacy migration automatically. Follow the prompts during installation.')\n console.log(' Details: https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // Check if V6 is already installed\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // Build non-interactive install command\n let installCmd\n if (hasV6) {\n console.log('🔄 Existing BMad V6 installation detected, performing quick update...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 Initializing BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language English',\n '--document-output-language English',\n '--yes',\n ].join(' ')\n }\n\n // Execute installation\n try {\n console.log(`📋 Executing: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 installation/update complete!')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 IMPORTANT: Please restart your AI IDE to load BMad extensions')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // Fix {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 Checking for known installer issues...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ No fixes needed')\n } catch (err) {\n console.log(` ⚠️ Failed to fix {output_folder}: ${err.message}`)\n console.log(' Please manually rename {output_folder}/ to _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 Directory Structure:')\n console.log(' • _bmad/ — agents, workflows, tasks, and configuration')\n console.log(' • _bmad-output/ — generated artifact output directory')\n console.log('')\n\n // Automatically update .gitignore\n console.log('🔧 Updating .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ Failed to automatically update .gitignore, please manually add _bmad/ and _bmad-output/')\n }\n console.log('')\n console.log('🚀 Quick Start:')\n console.log(' 1. Restart your AI IDE')\n console.log(' 2. Run /bmad-help for guidance and next step suggestions')\n console.log(' 3. Type /bmad and use autocomplete to browse available commands')\n console.log('')\n console.log('💡 Common Workflows:')\n console.log(' • /bmad-help — Interactive help')\n console.log(' • /bmad-bmm-create-prd — Create Product Requirements Document')\n console.log(' • /bmad-bmm-create-architecture — Create Architecture Document')\n console.log(' • /bmad-bmm-create-epics-and-stories — Create Epics and User Stories')\n console.log(' • /bmad-bmm-sprint-planning — Initialize Sprint Planning')\n console.log(' • /bmad-bmm-dev-story — Implement User Story')\n\n // Legacy V4 IDE command cleanup reminder\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ Legacy V4 IDE commands detected, consider removing manually:')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' New V6 commands are installed under .claude/commands/bmad/')\n }\n }\n catch (error) {\n console.error('❌ Installation failed:', error.message)\n console.log('')\n console.log('🛠️ Manual Installation Guide:')\n console.log(' 1. Ensure Node.js 20+ is installed')\n console.log(' 2. Non-interactive install:')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes')\n console.log(' 3. Quick update existing installation:')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. Or interactive install:')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 Documentation:')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// Execute initialization\ninitBmad()\n```\n\n## Usage\n\nSimply type in Claude Code:\n\n```\n/bmad-init\n```\n\nThis command will:\n\n1. Detect current installation status (V6 / V4 legacy / not installed)\n2. Fresh install: non-interactively execute `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n3. Existing install: execute `npx bmad-method install --directory . --action quick-update --yes`\n4. Fix `{output_folder}` → `_bmad-output` installer bug\n5. Automatically update `.gitignore` (clean up legacy entries, add V6 entries)\n6. Provide next step suggestions\n","frontmatter":{"name":"bmad-init","description":"Initialize or update BMad-Method (V6) in your project","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":2644,"sizeBytes":10550},{"name":"SKILL.md","path":"templates/skills/en/feat/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/feat/SKILL.md","title":"feat","category":"anthropic-skill","format":"markdown","content":"---\nname: feat\ndescription: Add New Feature\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## Core Workflow\n\n### 1. Input Analysis and Type Determination\n\nWhen receiving user input, first perform type determination and clearly inform the user:\n\n**Determination Criteria:**\n\n- **Requirement Planning Type**: User proposes new feature requirements, project ideas, or needs to formulate plans\n\n- **Discussion Iteration Type**: User requests to continue discussion, modify, or refine existing planning\n\n- **Execution Implementation Type**: User confirms planning is complete and requests to start specific implementation work\n\n### 2. Classification Processing Mechanism\n\n#### A. Requirement Planning Processing\n\n**Trigger Condition**: Identified as functional requirement input\n\n**Execution Actions**:\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Store document in `./.claude/plan` directory, named in plan/xxx.md format\n\n- Include: objective definition, feature breakdown, implementation steps, acceptance criteria\n\n#### B. Discussion Iteration Processing\n\n**Trigger Condition**: User requests to continue discussion or modify planning\n\n**Execution Actions**:\n\n- Retrieve and analyze previously generated planning files\n\n- Identify user feedback and confirmation content\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Create a new document, for example, if the last one was plan/xxx.md, then this time it's plan/xxx-1.md, if the last one was plan/xxx-1.md, then this time it's plan/xxx-2.md, and so on\n\n- Reorganize pending implementation task priorities\n\n#### C. Execution Implementation Processing\n\n**Trigger Condition**: User confirms planning is complete and requests to start execution\n\n**Execution Actions**:\n\n- Start task execution in the order of planning documents\n\n- Perform task type identification before each subtask begins\n\n- **Frontend Task Special Processing**:\n\n- Check if available UI design exists\n\n- If no design solution exists, must use UI-UX-Designer Agent\n\n- Complete UI design before proceeding with development implementation\n\n### 3. Key Execution Principles\n\n#### Mandatory Response Requirements\n\n- **Must first state in every interaction**: \"I determine this operation type as: [specific type]\"\n\n- Type determination must be accurate and clearly communicated to users\n\n#### Task Execution Standards\n\n- Strictly execute according to documented planning\n\n- Must clarify task nature and dependencies before subtask startup\n\n- Frontend tasks must ensure UI design completeness\n\n#### State Management Mechanism\n\n- Maintain task completion status tracking\n\n- Timely update planning document status\n\n- Ensure user visibility of progress\n\n## Quality Assurance Points\n\n1. **Type Determination Accuracy**: Type identification at the beginning of each interaction must be accurate\n\n2. **Document Consistency**: Planning documents and actual execution remain synchronized\n\n3. **Dependency Management**: Pay special attention to UI design dependencies of frontend tasks\n\n4. **Transparent User Communication**: All judgments and actions must be clearly communicated to users\n","frontmatter":{"name":"feat","description":"Add New Feature","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":601,"sizeBytes":3145},{"name":"SKILL.md","path":"templates/skills/en/git-clean-branches/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/git-clean-branches/SKILL.md","title":"git-clean-branches","category":"anthropic-skill","format":"markdown","content":"---\nname: git-clean-branches\ndescription: Safely find and clean up merged or stale Git branches with dry-run mode and custom base/protected branches support\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\nThis command **safely** identifies and cleans up **merged** or **stale** Git branches.\nRuns in **read-only preview (`--dry-run`)** mode by default, requiring explicit instructions to perform deletions.\n\n---\n\n## Usage\n\n```bash\n# [Safest] Preview branches to be cleaned without executing any deletions\n/git-cleanBranches --dry-run\n\n# Clean local branches merged to main and inactive for over 90 days (requires individual confirmation)\n/git-cleanBranches --stale 90\n\n# Clean local and remote branches merged to release/v2.1 (auto-confirm)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [Dangerous] Force delete an unmerged local branch\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`: Specify the base branch for cleanup (defaults to repository's `main`/`master`).\n- `--stale <days>`: Clean branches with no commits for specified days (disabled by default).\n- `--remote`: Also clean remote merged/stale branches.\n- `--dry-run`: **Default behavior**. Only list branches to be deleted without executing any operations.\n- `--yes`: Skip individual confirmations and delete all identified branches directly (suitable for CI/CD).\n- `--force`: Use `-D` to force delete local branches (even if unmerged).\n\n---\n\n## What This Command Does\n\n1. **Configuration and Safety Checks**\n - **Update Information**: Automatically executes `git fetch --all --prune` to ensure branch status is current.\n - **Read Protected Branches**: Reads the list of branches that should not be cleaned from Git config (see \"Configuration\" below).\n - **Determine Base**: Uses `--base` parameter or auto-detected `main`/`master` as comparison baseline.\n\n2. **Analysis and Identification (Find)**\n - **Merged Branches**: Find local (and remote if `--remote` is added) branches fully merged to `--base`.\n - **Stale Branches**: If `--stale <days>` is specified, find branches with last commit N days ago.\n - **Exclude Protected Branches**: Remove all configured protected branches from cleanup list.\n\n3. **Report and Preview (Report)**\n - Clearly list \"merged branches to be deleted\" and \"stale branches to be deleted\".\n - Without `--yes` parameter, **command ends here**, waiting for user confirmation to re-execute (without `--dry-run`).\n\n4. **Execute Cleanup (Execute)**\n - **Only executed without `--dry-run` and after user confirmation** (or with `--yes`).\n - Delete identified branches one by one, unless user chooses to skip in interactive confirmation.\n - Local: `git branch -d <branch>`; Remote: `git push origin --delete <branch>`.\n - If `--force` is specified, local deletion uses `git branch -D <branch>`.\n\n---\n\n## Configuration (Configure Once, Use Forever)\n\nTo prevent accidental deletion of important branches (e.g., `develop`, `release/*`), add protection rules to the repository's Git config. The command reads them automatically.\n\n```bash\n# Protect develop branch\ngit config --add branch.cleanup.protected develop\n\n# Protect all branches starting with release/ (wildcard)\ngit config --add branch.cleanup.protected 'release/*'\n\n# View all configured protected branches\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **Prioritize `--dry-run`**: Develop the habit of previewing before executing.\n- **Leverage `--base`**: When maintaining long-term `release` branches, use it to clean `feature` or `hotfix` branches merged to that release.\n- **Careful with `--force`**: Don't force delete unless you're 100% certain an unmerged branch is useless.\n- **Team Collaboration**: Notify the team channel before cleaning shared remote branches.\n- **Regular Runs**: Run monthly or quarterly to keep the repository clean.\n\n---\n\n## Why This Version Is Better\n\n- ✅ **Safer**: Default read-only preview with configurable protected branch list.\n- ✅ **More Flexible**: Supports custom base branches, perfectly fits `release` / `develop` workflows.\n- ✅ **More Compatible**: Avoids commands with inconsistent behavior across systems like `date -d`.\n- ✅ **More Intuitive**: Condenses complex 16-step checklist into a single command with safety options.\n- ✅ **Consistent Style**: Shares similar parameter design and documentation structure with `/commit` command.\n","frontmatter":{"name":"git-clean-branches","description":"Safely find and clean up merged or stale Git branches with dry-run mode and custom base/protected branches support","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()","allowedTools":["Read(**),","Exec(git","fetch,","git","config,","git","branch,","git","remote,","git","push,","git","for-each-ref,","git","log),","Write()"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git","fetch,","git","config,","git","branch,","git","remote,","git","push,","git","for-each-ref,","git","log),","Write()"],"isInternal":false,"tokens":1056,"sizeBytes":4592},{"name":"SKILL.md","path":"templates/skills/en/git-commit/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/git-commit/SKILL.md","title":"git-commit","category":"anthropic-skill","format":"markdown","content":"---\nname: git-commit\ndescription: Analyze changes with Git only and auto-generate conventional commit messages with optional emoji; suggests splitting commits when needed, runs local Git hooks by default (use --no-verify to skip)\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\nThis command works **without any package manager/build tools**, using only **Git** to:\n\n- Read changes (staged/unstaged)\n- Determine if changes should be **split into multiple commits**\n- Generate **Conventional Commits** style messages with optional emoji for each commit\n- Execute `git add` and `git commit` as needed (runs local Git hooks by default; use `--no-verify` to skip)\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`: Skip local Git hooks (`pre-commit`/`commit-msg` etc.).\n- `--all`: When staging area is empty, automatically `git add -A` to include all changes in the commit.\n- `--amend`: **Amend** the last commit without creating a new one (preserves author and timestamp unless local Git config specifies otherwise).\n- `--signoff`: Add `Signed-off-by` line (use when following DCO process).\n- `--emoji`: Include emoji prefix in commit message (omit for plain text).\n- `--scope <scope>`: Specify commit scope (e.g., `ui`, `docs`, `api`), written to message header.\n- `--type <type>`: Force commit type (e.g., `feat`, `fix`, `docs`), overrides automatic detection.\n\n> Note: If the framework doesn't support interactive confirmation, enable `confirm: true` in front-matter to avoid mistakes.\n\n---\n\n## What This Command Does\n\n1. **Repository/Branch Validation**\n - Check if in a Git repository using `git rev-parse --is-inside-work-tree`.\n - Read current branch/HEAD status; if in rebase/merge conflict state, prompt to resolve conflicts first.\n\n2. **Change Detection**\n - Get staged and unstaged changes using `git status --porcelain` and `git diff`.\n - If staged files = 0:\n - If `--all` is passed → Execute `git add -A`.\n - Otherwise prompt choice: continue analyzing unstaged changes for **suggestions**, or cancel to manually group staging.\n\n3. **Split Suggestions (Split Heuristics)**\n - Cluster by **concerns**, **file modes**, **change types** (e.g., source code vs docs/tests; different directories/packages; additions vs deletions).\n - If **multiple independent changesets** or large diff detected (e.g., > 300 lines / across multiple top-level directories), suggest splitting commits with pathspecs for each group (for subsequent `git add <paths>`).\n\n4. **Commit Message Generation (Conventional with Optional Emoji)**\n - Auto-infer `type` (`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert`...) and optional `scope`.\n - Generate message header: `[<emoji>] <type>(<scope>)?: <subject>` (first line ≤ 72 chars, imperative mood, emoji included only with `--emoji` flag).\n - Generate message body:\n - Must have a blank line after the subject.\n - Use list format, each item starts with `-`.\n - Each item **must use imperative verb-first sentences** (e.g., \"add…\", \"fix…\", \"update…\").\n - **Colon-separated formats are prohibited** (e.g., ~~\"Feature: description\"~~, ~~\"Impl: content\"~~).\n - Describe the motivation, implementation details, or impact scope (3 items or fewer recommended).\n - Generate message footer (if any):\n - Must have a blank line after the Body.\n - **BREAKING CHANGE**: If there are breaking changes, must include `BREAKING CHANGE: <description>`, or add exclamation mark after type (e.g., `feat!:`).\n - Other footers use git trailer format (e.g., `Closes #123`, `Refs: #456`, `Reviewed-by: Name`).\n - Select message language to match the predominant language in Git history. Inspect recent commit subjects (e.g., `git log -n 50 --pretty=%s`) to decide Chinese vs English; if unclear, fall back to the repository's primary locale or English.\n - Write draft to `.git/COMMIT_EDITMSG` for use with `git commit`.\n\n5. **Execute Commit**\n - Single commit scenario: `git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - Multiple commit scenario (if split accepted): Provide clear instructions for `git add <paths> && git commit ...` per group; execute sequentially if allowed.\n\n6. **Safe Rollback**\n - If mistakenly staged, use `git restore --staged <paths>` to unstage (command provides instructions, doesn't modify file contents).\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**: One commit does one thing, easier to trace and review.\n- **Group before committing**: Split by directory/module/feature.\n- **Clear subject**: First line ≤ 72 chars, imperative mood.\n- **Body with context**: Explain motivation, solution, and impact scope (colon-separated formats prohibited).\n- **Follow Conventional Commits**: `<type>(<scope>): <subject>`.\n\n---\n\n## Type to Emoji Mapping (When --emoji is Used)\n\n- ✨ `feat`: New feature\n- 🐛 `fix`: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)\n- 📝 `docs`: Documentation and comments\n- 🎨 `style`: Code style/formatting (no semantic changes)\n- ♻️ `refactor`: Refactoring (no new features, no bug fixes)\n- ⚡️ `perf`: Performance improvements\n- ✅ `test`: Add/fix tests, snapshots\n- 🔧 `chore`: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)\n- 👷 `ci`: CI/CD configuration and scripts\n- ⏪️ `revert`: Revert commits\n- 💥 `feat`: Breaking changes (explained in `BREAKING CHANGE:` section)\n\n> If `--type`/`--scope` is passed, it will **override** auto-detection.\n> Emoji is only included when `--emoji` flag is specified.\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **Different concerns**: Unrelated feature/module changes should be split.\n2. **Different types**: Don't mix `feat`, `fix`, `refactor` in the same commit.\n3. **File modes**: Source code vs docs/tests/configs should be grouped separately.\n4. **Size threshold**: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.\n5. **Revertability**: Ensure each commit can be independently reverted.\n\n---\n\n## Examples\n\n**Good (with --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (without --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (with Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (with BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ← (if your repo has hook errors)\n```\n\n---\n\n## Important Notes\n\n- **Git only**: No package manager/build commands (`pnpm`/`npm`/`yarn` etc.).\n- **Respects hooks**: Executes local Git hooks by default; use `--no-verify` to skip.\n- **No source code changes**: Command only reads/writes `.git/COMMIT_EDITMSG` and staging area; doesn't directly edit working directory files.\n- **Safety prompts**: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.\n- **Auditable and controllable**: If `confirm: true` is enabled, each actual `git add`/`git commit` step requires confirmation.\n","frontmatter":{"name":"git-commit","description":"Analyze changes with Git only and auto-generate conventional commit messages with optional emoji; suggests splitting commits when needed, runs local Git hooks by default (use --no-verify to skip)","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)","allowedTools":["Read(**),","Exec(git","status,","git","diff,","git","add,","git","restore","--staged,","git","commit,","git","rev-parse,","git","config),","Write(.git/COMMIT_EDITMSG)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git","status,","git","diff,","git","add,","git","restore","--staged,","git","commit,","git","rev-parse,","git","config),","Write(.git/COMMIT_EDITMSG)"],"isInternal":false,"tokens":2161,"sizeBytes":8769},{"name":"SKILL.md","path":"templates/skills/en/git-rollback/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/git-rollback/SKILL.md","title":"git-rollback","category":"anthropic-skill","format":"markdown","content":"---\nname: git-rollback\ndescription: Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**Purpose**: Safely and visually rollback a specified branch to an older version.\nDefaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.\n\n---\n\n## Usage\n\n```bash\n# Pure interactive: list branches → select branch → list recent 20 versions → select target → choose reset or revert → confirm\n/git-rollback\n\n# Specify branch, other interactive\n/git-rollback --branch feature/calculator\n\n# Specify branch and target commit, execute with hard-reset in one go (dangerous)\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# Generate revert commit only (non-destructive rollback), preview\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| Option | Description |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| `--branch <branch>` | Branch to rollback; interactively selected if omitted. |\n| `--target <rev>` | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |\n| `--mode reset\\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default. |\n| `--depth <n>` | List recent n versions in interactive mode (default 20). |\n| `--dry-run` | **Enabled by default**, only preview commands to be executed. |\n| `--yes` | Skip all confirmations and execute directly, suitable for CI/CD scripts. |\n\n---\n\n## Interactive Flow\n\n1. **Sync remote** → `git fetch --all --prune`\n2. **List branches** → `git branch -a` (local + remote, filter protected branches)\n3. **Select branch** → User input or parameter\n4. **List versions** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **Select target** → User inputs commit hash / tag\n6. **Select mode** → `reset` or `revert`\n7. **Final confirmation** (unless `--yes`)\n8. **Execute rollback**\n - `reset`: `git switch <branch> && git reset --hard <target>`\n - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)\n\n---\n\n## Safety Guards\n\n- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.\n- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.\n- **--dry-run enabled by default**: Prevents accidental operations.\n- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.\n\n---\n\n## Use Case Examples\n\n| Scenario | Command Example |\n| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |\n| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| Research historical bugs, guide newcomers through branch history | `/git-rollback` (full interactive, dry-run) |\n\n---\n\n## Notes\n\n1. **reset vs revert**\n - **reset** changes history, requires force push and may affect other collaborators, use with caution.\n - **revert** is safer, generates new commits preserving history, but adds one more record.\n2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.\n3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.\n\n---\n","frontmatter":{"name":"git-rollback","description":"Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()","allowedTools":["Read(**),","Exec(git","fetch,","git","branch,","git","tag,","git","log,","git","reflog,","git","checkout,","git","reset,","git","revert,","git","switch),","Write()"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git","fetch,","git","branch,","git","tag,","git","log,","git","reflog,","git","checkout,","git","reset,","git","revert,","git","switch),","Write()"],"isInternal":false,"tokens":989,"sizeBytes":4800},{"name":"SKILL.md","path":"templates/skills/en/git-worktree/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/git-worktree/SKILL.md","title":"git-worktree","category":"anthropic-skill","format":"markdown","content":"---\nname: git-worktree\ndescription: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\nManage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.\n\nExecute commands directly and provide concise results.\n\n---\n\n## Usage\n\n```bash\n# Basic operations\n/git-worktree add <path> # create new branch named <path> from main/master\n/git-worktree add <path> -b <branch> # create new branch with specified name\n/git-worktree add <path> -o # create and open directly in IDE\n/git-worktree list # show all worktree status\n/git-worktree remove <path> # remove specified worktree\n/git-worktree prune # clean invalid worktree references\n\n# Content migration\n/git-worktree migrate <target> --from <source> # migrate uncommitted content\n/git-worktree migrate <target> --stash # migrate stash content\n```\n\n### Options\n\n| Option | Description |\n| ------------------ | ------------------------------------------------------ |\n| `add [<path>]` | Add new worktree in `../.zcf/project-name/<path>` |\n| `migrate <target>` | Migrate content to specified worktree |\n| `list` | List all worktrees and their status |\n| `remove <path>` | Remove worktree at specified path |\n| `prune` | Clean invalid worktree references |\n| `-b <branch>` | Create new branch and checkout to worktree |\n| `-o, --open` | Open directly in IDE after creation (skip prompt) |\n| `--from <source>` | Specify migration source path (migrate only) |\n| `--stash` | Migrate current stash content (migrate only) |\n| `--track` | Set new branch to track corresponding remote branch |\n| `--guess-remote` | Auto guess remote branch for tracking |\n| `--detach` | Create detached HEAD worktree |\n| `--checkout` | Checkout immediately after creation (default behavior) |\n| `--lock` | Lock worktree after creation |\n\n---\n\n## What This Command Does\n\n1. **Environment Check**\n - Verify Git repository using `git rev-parse --is-inside-work-tree`\n - Detect whether in main repo or existing worktree for smart path calculation\n\n2. **Smart Path Management**\n - Auto-calculate project name from main repository path using worktree detection\n - Create worktrees in structured `../.zcf/project-name/<path>` directory\n - Handle both main repo and worktree execution contexts correctly\n\n```bash\n# Core path calculation logic for worktree detection\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # Check if in worktree\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # In worktree, derive main repo path from git-common-dir\n dirname \"$git_common_dir\"\n else\n # In main repository\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# Always use absolute path to prevent nesting issues\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.\n\n3. **Worktree Operations**\n - **add**: Create new worktree with smart branch/path defaults\n - **list**: Display all worktrees with branches and status\n - **remove**: Safely remove worktree and clean references\n - **prune**: Clean orphaned worktree records\n\n4. **Smart Defaults**\n - **Branch creation**: When no `-b` specified, create new branch using path name\n - **Base branch**: New branches created from main/master branch\n - **Path resolution**: Use branch name as path when unspecified\n - **IDE integration**: Auto-detect and prompt for IDE opening\n\n5. **Content Migration**\n - Migrate uncommitted changes between worktrees\n - Apply stash content to target worktree\n - Safety checks to prevent conflicts\n\n6. **Safety Features**\n - **Path conflict prevention**: Check for existing directories before creation\n - **Branch checkout validation**: Ensure branches aren't already in use\n - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree\n - **Auto-cleanup on removal**: Clean both directory and git references\n - **Clear status reporting**: Display worktree locations and branch status\n\n7. **Environment File Handling**\n - **Auto-detection**: Scan `.gitignore` for environment variable file patterns\n - **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`\n - **Exclusion logic**: Skip `.env.example` and other template files\n - **Permission preservation**: Maintain original file permissions and timestamps\n - **User feedback**: Provide clear status on copied environment files\n\n```bash\n# Environment file copying implementation\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # Check if .gitignore exists\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # Detect .env file\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ Copied .env\"\n ((copied_count++))\n fi\n \n # Detect .env.* pattern files (excluding .env.example)\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ Copied $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 Copied $copied_count environment file(s) from .gitignore\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE Integration\n\n- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **Smart prompting**: Ask to open in IDE after worktree creation\n- **Direct open**: Use `-o` flag to skip prompt and open immediately\n- **Custom configuration**: Configurable via git config\n\n### Content Migration System\n\n```bash\n# Migrate uncommitted changes\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# Migrate stash content\n/git-worktree migrate feature-ui --stash\n```\n\n**Migration Flow**:\n\n1. Verify source has uncommitted content\n2. Ensure target worktree is clean\n3. Show changes to be migrated\n4. Execute safe migration using git commands\n5. Confirm results and suggest next steps\n\n---\n\n## Examples\n\n```bash\n# Basic usage\n/git-worktree add feature-ui # create new branch 'feature-ui' from main/master\n/git-worktree add feature-ui -b my-feature # create new branch 'my-feature' with path 'feature-ui'\n/git-worktree add feature-ui -o # create and open in IDE directly\n\n# Content migration scenarios\n/git-worktree add feature-ui -b feature/new-ui # create new feature worktree\n/git-worktree migrate feature-ui --from main # migrate uncommitted changes\n/git-worktree migrate hotfix --stash # migrate stash content\n\n# Management operations\n/git-worktree list # view all worktrees\n/git-worktree remove feature-ui # remove unneeded worktree\n/git-worktree prune # clean invalid references\n```\n\n**Example Output**:\n\n```\n✅ Worktree created at ../.zcf/project-name/feature-ui\n✅ Copied .env\n✅ Copied .env.local\n📋 Copied 2 environment file(s) from .gitignore\n🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y\n🚀 Opening ../.zcf/project-name/feature-ui in VS Code...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # main project\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree management\n └── your-project/ # project worktrees\n ├── feature-ui/ # feature branch\n ├── hotfix/ # hotfix branch\n └── debug/ # debug worktree\n```\n\n---\n\n## Configuration\n\n### IDE Configuration\n\n- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim\n- Configurable via git config for custom IDEs\n- Auto-detection with priority-based selection\n\n### Custom IDE Setup\n\n```bash\n# Configure custom IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# Control auto-detection\ngit config worktree.ide.autodetect true # default\n```\n\n---\n\n## Notes\n\n- **Performance**: Worktrees share `.git` directory, saving disk space\n- **Safety**: Path conflict prevention and branch checkout validation\n- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits\n- **IDE requirement**: Command-line tools must be in PATH\n- **Cross-platform**: Supports Windows, macOS, Linux\n- **Environment files**: Automatically copies environment files listed in `.gitignore` to new worktrees\n- **File exclusions**: Template files like `.env.example` are preserved in main repo only\n\n---\n","frontmatter":{"name":"git-worktree","description":"Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration","disable-model-invocation":true,"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)","allowedTools":["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)"],"disableModelInvocation":true},"allowedTools":["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)"],"isInternal":false,"tokens":2290,"sizeBytes":10121},{"name":"SKILL.md","path":"templates/skills/en/init-project/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/init-project/SKILL.md","title":"init-project","category":"anthropic-skill","format":"markdown","content":"---\nname: init-project\ndescription: Initialize project AI context, generate/update root-level and module-level CLAUDE.md indexes\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## Usage\n\n`/init-project <PROJECT_SUMMARY_OR_NAME>`\n\n## Objective\n\nInitialize project AI context using a mixed strategy of \"concise at root + detailed at module level\":\n\n- Generate/update `CLAUDE.md` at repository root (high-level vision, architecture overview, module index, global standards).\n- Generate/update local `CLAUDE.md` in identified module directories (interfaces, dependencies, entry points, tests, key files, etc.).\n- ✨ **For improved readability, automatically generate Mermaid structure diagrams in the root `CLAUDE.md` and add navigation breadcrumbs to each module `CLAUDE.md`**.\n\n## Orchestration Instructions\n\n**Step 1**: Call the `get-current-datetime` sub-agent to obtain the current timestamp.\n\n**Step 2**: Call the `init-architect` sub-agent once, with input:\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (timestamp from step 1)\n\n## Execution Strategy (Agent adapts automatically, no user parameters needed)\n\n- **Stage A: Repository Census (Lightweight)**\n Quickly count files and directories, identify module roots (package.json, pyproject.toml, go.mod, apps/_, packages/_, services/\\*, etc.).\n- **Stage B: Module Priority Scanning (Medium)**\n For each module, perform targeted reading and sampling of \"entry/interfaces/dependencies/tests/data models/quality tools\".\n- **Stage C: Deep Supplementation (As Needed)**\n If repository is small or module scale is small, expand reading scope; if large, perform batch supplemental scanning on high-risk/high-value paths.\n- **Coverage Measurement and Resumability**\n 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.\n\n## Security and Boundaries\n\n- Only read/write documentation and indexes, do not modify source code.\n- Ignore common generated artifacts and binary large files by default.\n- Print \"summary\" in main dialog, write full content to repository.\n\n## Output Requirements\n\n- Print \"Initialization Result Summary\" in main dialog, including:\n - Whether root-level `CLAUDE.md` was created/updated, major section overview.\n - Number of identified modules and their path list.\n - Generation/update status of each module's `CLAUDE.md`.\n - ✨ **Explicitly mention \"Generated Mermaid structure diagram\" and \"Added navigation breadcrumbs for N modules\"**.\n - Coverage and major gaps.\n - If not fully read: explain \"why stopped here\" and list **recommended next steps** (e.g., \"suggest priority supplemental scanning: packages/auth/src/controllers\").\n","frontmatter":{"name":"init-project","description":"Initialize project AI context, generate/update root-level and module-level CLAUDE.md indexes","disable-model-invocation":true,"allowed-tools":"Read(**), Write(CLAUDE.md, **/CLAUDE.md)","allowedTools":["Read(**),","Write(CLAUDE.md,","**/CLAUDE.md)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Write(CLAUDE.md,","**/CLAUDE.md)"],"isInternal":false,"tokens":642,"sizeBytes":2895},{"name":"SKILL.md","path":"templates/skills/en/workflow/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/en/workflow/SKILL.md","title":"workflow","category":"anthropic-skill","format":"markdown","content":"---\nname: workflow\ndescription: 'Professional AI programming assistant with structured workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) for developers'\ndisable-model-invocation: true\n---\n\n# Workflow - Professional Development Assistant\n\nExecute structured development workflow with quality gates and MCP service integration.\n\n## Usage\n\n```bash\n/workflow <TASK_DESCRIPTION>\n```\n\n## Context\n\n- Task to develop: $ARGUMENTS\n- Structured 6-phase workflow with quality gates\n- Professional developer-focused interaction\n- MCP service integration for enhanced capabilities\n\n## Your Role\n\nYou are a professional AI programming assistant following a structured core workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) to assist users. Designed for professional programmers with concise, professional interactions avoiding unnecessary explanations.\n\n## Communication Guidelines\n\n1. Responses start with mode tag `[Mode: X]`, initially `[Mode: Research]`\n2. Core workflow strictly follows `Research -> Ideate -> Plan -> Execute -> Optimize -> Review` sequence, users can command jumps\n\n## Core Workflow Details\n\n### 1. `[Mode: Research]` - Requirement Understanding\n\n- Analyze and understand user requirements\n- Evaluate requirement completeness (0-10 score), actively request key information when below 7\n- Gather necessary context and constraints\n- Identify key objectives and success criteria\n\n### 2. `[Mode: Ideate]` - Solution Design\n\n- Provide at least two feasible solutions with evaluation (e.g., `Solution 1: Description`)\n- Compare pros/cons of each approach\n- Recommend optimal solution based on requirements\n\n### 3. `[Mode: Plan]` - Detailed Planning\n\n- Break down selected solution into detailed, ordered, executable step list\n- Include atomic operations: files, functions/classes, logic overview\n- Define expected results for each step\n- Use `Context7` for new library queries\n- Do not write complete code at this stage\n- Request user approval after completion\n\n### 4. `[Mode: Execute]` - Implementation\n\n- Store plan summary (with context and plan) in project root directory `.zcf/plan/current/task-name.md`\n- Must have user approval before execution\n- Strictly follow the plan for coding implementation\n- Request user feedback after key steps and completion\n\n### 5. `[Mode: Optimize]` - Code Optimization\n\n- Automatically enter this mode after `[Mode: Execute]` completion\n- Automatically check and analyze implemented code (only code generated in current conversation)\n- Focus on redundant, inefficient, garbage code\n- Provide specific optimization suggestions (with reasons and expected benefits)\n- Execute optimization after user confirmation\n\n### 6. `[Mode: Review]` - Quality Assessment\n\n- Evaluate execution results against the plan\n- Report issues and suggestions\n- Request user confirmation after completion\n\n## Timestamp Acquisition Rules\n\nDuring workflow execution, any scenario requiring current timestamp must obtain accurate time via bash command. Guessing or fabricating time is prohibited.\n\nBasic Commands:\n- Default format: `date +'%Y-%m-%d %H:%M:%S'`\n- Filename format: `date +'%Y-%m-%d_%H%M%S'`\n- Readable format: `date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO format: `date +'%Y-%m-%dT%H:%M:%S%z'`\n\nTypical Use Cases:\n- Updating timestamp fields in documents\n- Naming task plan documents during archiving (when moving from `.zcf/plan/current/` to `.zcf/plan/history/`)\n- Any other scenario requiring current time recording\n\n## Interactive Feedback & MCP Services\n\n### Interactive Feedback Rules\n\n1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, must request user confirmation\n2. When receiving user feedback, if feedback content is not empty, must request user confirmation again and adjust behavior based on feedback\n3. Only when user explicitly indicates \"end\" or \"no more interaction needed\" can stop requesting user confirmation, process is considered complete\n4. Unless receiving termination instructions, all steps must repeatedly request user confirmation\n5. Before completing tasks, must request user confirmation and ask for user feedback\n\n---\n\n## Execute Workflow\n\n**Task Description**: $ARGUMENTS\n\nStarting structured development workflow with quality gates...\n\n### 🔍 Phase 1: Research & Analysis\n\n[Mode: Research] - Understanding requirements and gathering context:\n\n#### Requirement Completeness Scoring (0-10 points)\n\nScoring Dimensions:\n\n- **Goal Clarity** (0-3 points): Are task objectives clear and specific, what problem to solve?\n- **Expected Results** (0-3 points): Are success criteria and deliverables clearly defined?\n- **Scope Boundaries** (0-2 points): Are task scope and boundaries clear?\n- **Constraints** (0-2 points): Are time, performance, business limits specified?\n\nNote: Technical stack, framework versions will be identified from project automatically, not included in scoring\n\n**Scoring Rules**:\n\n- 9-10 points: Requirements very complete, can proceed directly\n- 7-8 points: Requirements basically complete, suggest adding minor details\n- 5-6 points: Requirements have significant gaps, must supplement key information\n- 0-4 points: Requirements too vague, needs redescription\n\n**When score is below 7, proactively ask supplementary questions**:\n\n- Identify missing key information dimensions\n- Ask 1-2 specific questions for each missing dimension\n- Provide examples to help users understand needed information\n- Re-score after user supplements information\n\n**Scoring Example**:\n\n```\nUser Request: \"Help me optimize code\"\nScoring Analysis:\n- Goal Clarity: 0/3 points (doesn't specify what code or what problem)\n- Expected Results: 0/3 points (no success criteria or expected effect defined)\n- Scope Boundaries: 1/2 points (only knows code optimization, but scope unclear)\n- Constraints: 0/2 points (no performance metrics or time limits)\nTotal Score: 1/10 - Requires significant information\n\nQuestions to Ask:\n1. Which file or module's code do you want to optimize?\n2. What specific problem needs optimization?\n3. What effect do you expect after optimization (e.g., response time improvement, code reduction)?\n4. Are there specific performance metrics or time requirements?\n```\n\n**Common Supplementary Question Templates**:\n\n- Goal: \"What specific functionality/effect do you want?\" \"What's the current problem?\"\n- Results: \"How to determine task success?\" \"What's the expected output/effect?\"\n- Scope: \"Which specific files/modules to handle?\" \"What should be excluded?\"\n- Constraints: \"What are the time requirements?\" \"Any business limitations or performance requirements?\"\n\n**Auto-detected Project Information** (no need to ask):\n\n- Tech stack (from AGENTS.md, CLAUDE.md, package.json, requirements.txt, etc.)\n- Framework versions (from AGENTS.md, CLAUDE.md, config files)\n- Project structure (from file system)\n- Existing code conventions (from AGENTS.md, CLAUDE.md, config files and existing code)\n- Development commands (from AGENTS.md, CLAUDE.md, such as build, test, typecheck)\n\n#### Execution Steps\n\n- Analyze task requirements and constraints\n- Perform requirement completeness scoring (show specific scores)\n- Identify key objectives and success criteria\n- Gather necessary technical context\n- Use MCP services for additional information if needed\n\n### 💡 Phase 2: Solution Ideation\n\n[Mode: Ideate] - Designing solution approaches:\n\n- Generate multiple feasible solutions\n- Evaluate pros and cons of each approach\n- Provide detailed comparison and recommendation\n- Consider technical constraints and best practices\n- Request user approval before proceeding\n\n### 📋 Phase 3: Detailed Planning\n\n[Mode: Plan] - Creating execution roadmap:\n\n- Break down solution into atomic, executable steps\n- Define file structure, functions/classes, and logic overview\n- Specify expected results for each step\n- Query new libraries using Context7 if needed\n- Request user approval before proceeding\n\n### ⚡ Phase 4: Implementation\n\n[Mode: Execute] - Code development:\n\n- Store execution plan in project root directory `.zcf/plan/current/task-name.md`\n- Implement according to approved plan\n- Follow development best practices\n- Add usage methods before import statements (critical rule)\n- Request feedback at key milestones\n\n### 🚀 Phase 5: Code Optimization\n\n[Mode: Optimize] - Quality improvement:\n\n- Automatically analyze implemented code\n- Identify redundant, inefficient, or problematic code\n- Provide specific optimization recommendations\n- Execute improvements after user confirmation\n\n### ✅ Phase 6: Quality Review\n\n[Mode: Review] - Final assessment:\n\n- Compare results against original plan\n- Identify any remaining issues or improvements\n- Provide completion summary and recommendations\n- Request final user confirmation\n- After task completion, move plan file from `.zcf/plan/current/` to `.zcf/plan/history/` for archiving\n- Rename to `[Finish Time]task-name.md` during archiving for tracking, Finish Time format is `YYYY-MM-DD_HHMMSS`\n\n## Expected Output Structure\n\n```\nproject/ # Project root directory\n├── .zcf/\n│ └── plan/\n│ ├── current/ # Current ongoing tasks\n│ │ └── task-name.md # Execution plan and context\n│ └── history/ # Completed historical tasks\n│ └── [Finish Time]task-name.md # Archived task records\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**Begin execution with the provided task description and report progress after each phase completion.**\n","frontmatter":{"name":"workflow","description":"Professional AI programming assistant with structured workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) for developers","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":2067,"sizeBytes":9771},{"name":"SKILL.md","path":"templates/skills/zh-CN/bmad-init/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/bmad-init/SKILL.md","title":"bmad-init","category":"anthropic-skill","format":"markdown","content":"---\nname: bmad-init\ndescription: 在项目中初始化或更新 BMad-Method (V6)\ndisable-model-invocation: true\n---\n\n# /bmad-init 命令\n\n此命令在您的项目中初始化或更新 BMad-Method (V6)。\n\n## 当调用此命令时：\n\n1. 检查 `_bmad/` 目录是否存在，判断 BMad V6 是否已安装\n2. 检查是否存在旧版 V4 安装（`.bmad-core` 或 `.bmad-method` 目录）\n3. 新安装执行：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n4. 已安装则执行：`npx bmad-method install --directory . --action quick-update --yes`\n5. 修复安装器 bug：将 `{output_folder}` 重命名为 `_bmad-output`（Beta 已知问题）\n6. 自动更新 `.gitignore`（移除 V4 条目，添加 V6 条目）\n7. 显示安装结果并提示用户后续操作\n\n## 实现\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// 需要从 .gitignore 清理的旧条目\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug 产物\n]\n\n// V6 新版 .gitignore 条目\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// 修复安装器 bug: {output_folder} 未解析为 _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output 不存在，直接重命名\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (重命名)')\n } else {\n // _bmad-output 已存在，合并子目录后删除\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ 移动 ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ 已删除多余的 {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // 移除 V4 旧条目\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ 移除旧条目: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // 添加 V6 新条目\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ 添加新条目: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore 已是最新，无需更新')\n return\n }\n\n // 构建新内容\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // 确保末尾有换行，然后添加 BMad 区块\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore 已${exists ? '更新' : '创建'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // 检查旧版 V4 安装\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ 检测到旧版 BMad V4 安装：')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 核心目录)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 方法目录)')\n console.log('')\n console.log('📌 V6 安装器会自动处理旧版迁移，请在安装过程中按提示操作。')\n console.log(' 详情参考：https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // 检查 V6 是否已安装\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // 构建非交互式安装命令\n let installCmd\n if (hasV6) {\n console.log('🔄 检测到已有 BMad V6 安装，将执行快速更新...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 正在初始化 BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language Chinese',\n '--document-output-language Chinese',\n '--yes',\n ].join(' ')\n }\n\n // 执行安装\n try {\n console.log(`📋 执行: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 安装/更新完成！')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 重要提示：请重启 AI IDE 以加载 BMad 扩展')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // 修复 {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 检查安装器已知问题...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ 无需修复')\n } catch (err) {\n console.log(` ⚠️ 修复 {output_folder} 失败: ${err.message}`)\n console.log(' 请手动将 {output_folder}/ 重命名为 _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 目录结构：')\n console.log(' • _bmad/ — agents、workflows、tasks 和配置')\n console.log(' • _bmad-output/ — 生成的工件输出目录')\n console.log('')\n\n // 自动更新 .gitignore\n console.log('🔧 更新 .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ 自动更新 .gitignore 失败，请手动添加 _bmad/ 和 _bmad-output/')\n }\n console.log('')\n console.log('🚀 快速开始：')\n console.log(' 1. 重启 AI IDE')\n console.log(' 2. 运行 /bmad-help 获取引导和下一步建议')\n console.log(' 3. 输入 /bmad 并使用自动补全浏览可用命令')\n console.log('')\n console.log('💡 常用工作流：')\n console.log(' • /bmad-help — 交互式帮助')\n console.log(' • /bmad-bmm-create-prd — 创建产品需求文档')\n console.log(' • /bmad-bmm-create-architecture — 创建架构文档')\n console.log(' • /bmad-bmm-create-epics-and-stories — 创建史诗和用户故事')\n console.log(' • /bmad-bmm-sprint-planning — 初始化 Sprint 计划')\n console.log(' • /bmad-bmm-dev-story — 实现用户故事')\n\n // 清理旧版 V4 IDE 命令提醒\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ 检测到旧版 V4 IDE 命令，建议手动删除：')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' 新的 V6 命令已安装在 .claude/commands/bmad/ 下')\n }\n }\n catch (error) {\n console.error('❌ 安装失败：', error.message)\n console.log('')\n console.log('🛠️ 手动安装指南：')\n console.log(' 1. 确保已安装 Node.js 20+')\n console.log(' 2. 非交互式安装：')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes')\n console.log(' 3. 快速更新已有安装：')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. 或交互式安装：')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 详细文档：')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// 执行初始化\ninitBmad()\n```\n\n## 用法\n\n只需在 Claude Code 中键入：\n\n```\n/bmad-init\n```\n\n此命令将：\n\n1. 检测现有安装状态（V6 / V4 旧版 / 未安装）\n2. 新安装：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n3. 已安装：`npx bmad-method install --directory . --action quick-update --yes`\n4. 修复 `{output_folder}` → `_bmad-output` 安装器 bug\n5. 自动更新 `.gitignore`（清理旧条目，添加 V6 条目）\n6. 提供后续步骤建议\n","frontmatter":{"name":"bmad-init","description":"在项目中初始化或更新 BMad-Method (V6)","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":3006,"sizeBytes":10196},{"name":"SKILL.md","path":"templates/skills/zh-CN/feat/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/feat/SKILL.md","title":"feat","category":"anthropic-skill","format":"markdown","content":"---\nname: feat\ndescription: '用于新增功能开发的命令，支持完整的开发流程和工具集成'\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## 核心工作流程\n\n### 1. 输入分析与类型判断\n\n每次收到用户输入时，首先进行类型判断并明确告知用户：\n\n**判断标准：**\n\n- **需求规划类型**: 用户提出新功能需求、项目构想或需要制定计划\n\n- **讨论迭代类型**: 用户要求继续讨论、修改或完善已有规划\n\n- **执行实施类型**: 用户确认规划完成，要求开始具体实施工作\n\n### 2. 分类处理机制\n\n#### A. 需求规划处理\n\n**触发条件**: 识别为功能需求输入\n\n**执行动作**:\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 将文档存储至 `./.claude/plan` 目录，并以 plan/xxx.md 的格式命名\n\n- 包含：目标定义、功能分解、实施步骤、验收标准\n\n#### B. 讨论迭代处理\n\n**触发条件**: 用户要求继续讨论或修改规划\n\n**执行动作**:\n\n- 检索并分析上次生成的规划文件\n\n- 识别用户反馈和确认内容\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 建立一个新的文档，比如上一次是 plan/xxx.md，那么这次就是 plan/xxx-1.md，如果上一次是 plan/xxx-1.md，那么这次就是 plan/xxx-2.md，以此类推\n\n- 重新组织待实施任务优先级\n\n#### C. 执行实施处理\n\n**触发条件**: 用户确认规划完成，要求开始执行\n\n**执行动作**:\n\n- 按规划文档顺序启动任务执行\n\n- 每个子任务开始前进行任务类型识别\n\n- **前端任务特殊处理**:\n\n- 检查是否存在可用 UI 设计\n\n- 如无设计方案，must use UI-UX-Designer Agent\n\n- 完成 UI 设计后再进行开发实施\n\n### 3. 关键执行原则\n\n#### 强制响应要求\n\n- **每次交互必须首先说明**: \"我判断此次操作类型为：[具体类型]\"\n\n- 类型判断必须准确且明确传达给用户\n\n#### 任务执行规范\n\n- 严格按照文档化规划执行\n\n- 子任务启动前必须明确任务性质和依赖关系\n\n- 前端任务必须确保 UI 设计完整性\n\n#### 状态管理机制\n\n- 维护任务完成状态跟踪\n\n- 及时更新规划文档状态\n\n- 确保用户对进度的可见性\n\n## 质量保证要点\n\n1. **类型判断准确性**: 每次交互开始的类型识别必须准确\n\n2. **文档一致性**: 规划文档与实际执行保持同步\n\n3. **依赖关系管理**: 特别关注前端任务的 UI 设计依赖\n\n4. **用户沟通透明**: 所有判断和动作都要明确告知用户\n","frontmatter":{"name":"feat","description":"用于新增功能开发的命令，支持完整的开发流程和工具集成","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":918,"sizeBytes":2568},{"name":"SKILL.md","path":"templates/skills/zh-CN/git-clean-branches/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/git-clean-branches/SKILL.md","title":"git-clean-branches","category":"anthropic-skill","format":"markdown","content":"---\nname: git-clean-branches\ndescription: 安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\n该命令**安全地**识别并清理**已合并**或**长期未更新 (stale)** 的 Git 分支。\n默认以**只读预览 (`--dry-run`)** 模式运行，需明确指令才会执行删除操作。\n\n---\n\n## Usage\n\n```bash\n# [最安全] 预览将要清理的分支，不执行任何删除\n/git-cleanBranches --dry-run\n\n# 清理已合并到 main 且超过 90 天未动的本地分支 (需逐一确认)\n/git-cleanBranches --stale 90\n\n# 清理已合并到 release/v2.1 的本地与远程分支 (自动确认)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [危险] 强制删除一个未合并的本地分支\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。\n- `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。\n- `--remote`：同时清理远程已合并/过期的分支。\n- `--dry-run`：**默认行为**。仅列出将要删除的分支，不执行任何操作。\n- `--yes`：跳过逐一确认的步骤，直接删除所有已识别的分支（适合 CI/CD）。\n- `--force`：使用 `-D` 强制删除本地分支（即使未合并）。\n\n---\n\n## What This Command Does\n\n1. **配置与安全预检**\n - **更新信息**：自动执行 `git fetch --all --prune`，确保分支状态最新。\n - **读取保护分支**：从 Git 配置读取不应被清理的分支列表（见下文“Configuration”）。\n - **确定基准**：使用 `--base` 参数或自动识别的 `main`/`master` 作为比较基准。\n\n2. **分析识别（Find）**\n - **已合并分支**：找出已完全合并到 `--base` 的本地（及远程，如加 `--remote`）分支。\n - **过期分支**：如指定 `--stale <days>`，找出最后一次提交在 N 天前的分支。\n - **排除保护分支**：从待清理列表中移除所有已配置的保护分支。\n\n3. **报告预览（Report）**\n - 清晰列出“将要删除的已合并分支”与“将要删除的过期分支”。\n - 若无 `--yes` 参数，**命令到此结束**，等待用户确认后再次执行（不带 `--dry-run`）。\n\n4. **执行清理（Execute）**\n - **仅在不带 `--dry-run` 且用户确认后**（或带 `--yes`）执行。\n - 逐一删除已识别的分支，除非用户在交互式确认中选择跳过。\n - 本地用 `git branch -d <branch>`；远程用 `git push origin --delete <branch>`。\n - 若指定 `--force`，本地删除会改用 `git branch -D <branch>`。\n\n---\n\n## Configuration (一次配置，永久生效)\n\n为防止误删重要分支（如 `develop`, `release/*`），请在仓库的 Git 配置中添加保护规则。命令会自动读取。\n\n```bash\n# 保护 develop 分支\ngit config --add branch.cleanup.protected develop\n\n# 保护所有 release/ 开头的分支 (通配符)\ngit config --add branch.cleanup.protected 'release/*'\n\n# 查看所有已配置的保护分支\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **优先 `--dry-run`**：养成先预览再执行的习惯。\n- **活用 `--base`**：维护长期 `release` 分支时，用它来清理已合并到该 release 的 `feature` 或 `hotfix` 分支。\n- **谨慎 `--force`**：除非你百分百确定某个未合并分支是无用功，否则不要强制删除。\n- **团队协作**：在清理共享的远程分支前，先在团队频道通知一声。\n- **定期运行**：每月或每季度运行一次，保持仓库清爽。\n\n---\n\n## Why This Version Is Better\n\n- ✅ **更安全**：默认只读预览，且有可配置的保护分支列表。\n- ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。\n- ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。\n- ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。\n- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。\n","frontmatter":{"name":"git-clean-branches","description":"安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()","allowedTools":["Read(**),","Exec(git","fetch,","git","config,","git","branch,","git","remote,","git","push,","git","for-each-ref,","git","log),","Write()"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git","fetch,","git","config,","git","branch,","git","remote,","git","push,","git","for-each-ref,","git","log),","Write()"],"isInternal":false,"tokens":1477,"sizeBytes":4363},{"name":"SKILL.md","path":"templates/skills/zh-CN/git-commit/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/git-commit/SKILL.md","title":"git-commit","category":"anthropic-skill","format":"markdown","content":"---\nname: git-commit\ndescription: 仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过）\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\n该命令在**不依赖任何包管理器/构建工具**的前提下，仅通过 **Git**：\n\n- 读取改动（staged/unstaged）\n- 判断是否需要**拆分为多次提交**\n- 为每个提交生成 **Conventional Commits** 风格的信息（可选 emoji）\n- 按需执行 `git add` 与 `git commit`（默认运行本地 Git 钩子；可 `--no-verify` 跳过）\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`：跳过本地 Git 钩子（`pre-commit`/`commit-msg` 等）。\n- `--all`：当暂存区为空时，自动 `git add -A` 将所有改动纳入本次提交。\n- `--amend`：在不创建新提交的情况下**修补**上一次提交（保持提交作者与时间，除非本地 Git 配置另有指定）。\n- `--signoff`：附加 `Signed-off-by` 行（遵循 DCO 流程时使用）。\n- `--emoji`：在提交信息中包含 emoji 前缀（省略则使用纯文本）。\n- `--scope <scope>`：指定提交作用域（如 `ui`、`docs`、`api`），写入消息头部。\n- `--type <type>`：强制提交类型（如 `feat`、`fix`、`docs` 等），覆盖自动判断。\n\n> 注：如框架不支持交互式确认，可在 front-matter 中开启 `confirm: true` 以避免误操作。\n\n---\n\n## What This Command Does\n\n1. **仓库/分支校验**\n - 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库。\n - 读取当前分支/HEAD 状态；如处于 rebase/merge 冲突状态，先提示处理冲突后再继续。\n\n2. **改动检测**\n - 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动。\n - 若已暂存文件为 0：\n - 若传入 `--all` → 执行 `git add -A`。\n - 否则提示你选择：继续仅分析未暂存改动并给出**建议**，或取消命令后手动分组暂存。\n\n3. **拆分建议（Split Heuristics）**\n - 按**关注点**、**文件模式**、**改动类型**聚类（示例：源代码 vs 文档、测试；不同目录/包；新增 vs 删除）。\n - 若检测到**多组独立变更**或 diff 规模过大（如 > 300 行 / 跨多个顶级目录），建议拆分提交，并给出每一组的 pathspec（便于后续执行 `git add <paths>`）。\n\n4. **提交信息生成（Conventional 规范，可选 Emoji）**\n - 自动推断 `type`（`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert` …）与可选 `scope`。\n - 生成消息头：`[<emoji>] <type>(<scope>)?: <subject>`（首行 ≤ 72 字符，祈使语气，仅在使用 `--emoji` 时包含 emoji）。\n - 生成消息体：\n - 必须在 subject 之后空一行。\n - 使用列表格式，每项以 `-` 开头。\n - 每项**必须使用动词开头的祈使句**（如 \"add…\"、\"fix…\"、\"update…\"）。\n - **禁止使用冒号分隔的格式**（如 ~~\"Feature: description\"~~、~~\"Impl: content\"~~）。\n - 说明变更的动机、实现要点或影响范围（3 项以内为宜）。\n - 生成消息脚注（如有）：\n - 必须在 Body 之后空一行。\n - **BREAKING CHANGE**：若存在破坏性变更，必须包含 `BREAKING CHANGE: <description>`，或在类型后添加感叹号（如 `feat!:`）。\n - 其它脚注采用 git trailer 格式（如 `Closes #123`、`Refs: #456`、`Reviewed-by: Name`）。\n - 根据 Git 历史提交的主要语言选择提交信息语言。优先检查最近提交主题（例如 `git log -n 50 --pretty=%s`）判断中文/英文；若无法判断，则回退到仓库主要语言或英文。\n - 将草稿写入 `.git/COMMIT_EDITMSG`，并用于 `git commit`。\n\n5. **执行提交**\n - 单提交场景：`git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - 多提交场景（如接受拆分建议）：按分组给出 `git add <paths> && git commit ...` 的明确指令；若允许执行则逐一完成。\n\n6. **安全回滚**\n - 如误暂存，可用 `git restore --staged <paths>` 撤回暂存（命令会给出指令，不修改文件内容）。\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**：一次提交只做一件事，便于回溯与审阅。\n- **先分组再提交**：按目录/模块/功能点拆分。\n- **清晰主题**：首行 ≤ 72 字符，祈使语气。\n- **正文含上下文**：说明动机、方案、影响范围（禁止冒号分隔格式）。\n- **遵循 Conventional Commits**：`<type>(<scope>): <subject>`。\n\n---\n\n## Type 与 Emoji 映射（使用 --emoji 时）\n\n- ✨ `feat`：新增功能\n- 🐛 `fix`：缺陷修复（含 🔥 删除代码/文件、🚑️ 紧急修复、👽️ 适配外部 API 变更、🔒️ 安全修复、🚨 解决告警、💚 修复 CI）\n- 📝 `docs`：文档与注释\n- 🎨 `style`：风格/格式（不改语义）\n- ♻️ `refactor`：重构（不新增功能、不修缺陷）\n- ⚡️ `perf`：性能优化\n- ✅ `test`：新增/修复测试、快照\n- 🔧 `chore`：构建/工具/杂务（合并分支、更新配置、发布标记、依赖 pin、.gitignore 等）\n- 👷 `ci`：CI/CD 配置与脚本\n- ⏪️ `revert`：回滚提交\n- 💥 `feat`：破坏性变更（`BREAKING CHANGE:` 段落中说明）\n\n> 若传入 `--type`/`--scope`，将**覆盖**自动推断。\n> 仅在指定 `--emoji` 标志时才会包含 emoji。\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **不同关注点**：互不相关的功能/模块改动应拆分。\n2. **不同类型**：不要将 `feat`、`fix`、`refactor` 混在同一提交。\n3. **文件模式**：源代码 vs 文档/测试/配置分组提交。\n4. **规模阈值**：超大 diff（示例：>300 行或跨多个顶级目录）建议拆分。\n5. **可回滚性**：确保每个提交可独立回退。\n\n---\n\n## Examples\n\n**Good (使用 --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (不使用 --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (包含 Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (包含 BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ←（如你的仓库有钩子报错）\n```\n\n---\n\n## Important Notes\n\n- **仅使用 Git**：不调用任何包管理器/构建命令（无 `pnpm`/`npm`/`yarn` 等）。\n- **尊重钩子**：默认执行本地 Git 钩子；使用 `--no-verify` 可跳过。\n- **不改源码内容**：命令只读写 `.git/COMMIT_EDITMSG` 与暂存区；不会直接编辑工作区文件。\n- **安全提示**：在 rebase/merge 冲突、detached HEAD 等状态下会先提示处理/确认再继续。\n- **可审可控**：如开启 `confirm: true`，每个实际 `git add`/`git commit` 步骤都会进行二次确认。\n","frontmatter":{"name":"git-commit","description":"仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过）","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)","allowedTools":["Read(**),","Exec(git","status,","git","diff,","git","add,","git","restore","--staged,","git","commit,","git","rev-parse,","git","config),","Write(.git/COMMIT_EDITMSG)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git","status,","git","diff,","git","add,","git","restore","--staged,","git","commit,","git","rev-parse,","git","config),","Write(.git/COMMIT_EDITMSG)"],"isInternal":false,"tokens":2821,"sizeBytes":8519},{"name":"SKILL.md","path":"templates/skills/zh-CN/git-rollback/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/git-rollback/SKILL.md","title":"git-rollback","category":"anthropic-skill","format":"markdown","content":"---\nname: git-rollback\ndescription: 交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**目的**：安全、可视地将指定分支回滚到旧版本。\n默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。\n\n---\n\n## Usage\n\n```bash\n# 纯交互：列出分支 → 选分支 → 列最近 20 个版本 → 选目标 → 选择 reset 或 revert → 二次确认\n/git-rollback\n\n# 指定分支，其他交互\n/git-rollback --branch feature/calculator\n\n# 指定分支与目标 commit，并用 hard‑reset 一键执行（危险）\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# 只想生成 revert 提交（非破坏式回滚），预览即可\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| 选项 | 说明 |\n| ---------------------- | ---------------------------------------------------------------------------------- |\n| `--branch <branch>` | 要回滚的分支；缺省时交互选择。 |\n| `--target <rev>` | 目标版本（commit Hash、Tag、reflog 引用都行）；缺省时交互选择近 `--depth` 条记录。 |\n| `--mode reset\\|revert` | `reset`：硬回滚历史；`revert`：生成反向提交保持历史完整。默认询问。 |\n| `--depth <n>` | 在交互模式下列出最近 n 个版本（默认 20）。 |\n| `--dry-run` | **默认开启**，只预览即将执行的命令。 |\n| `--yes` | 跳过所有确认直接执行，适合 CI/CD 脚本。 |\n\n---\n\n## 交互流程\n\n1. **同步远端** → `git fetch --all --prune`\n2. **列分支** → `git branch -a`（本地＋远端，过滤受保护分支）\n3. **选分支** → 用户输入或传参\n4. **列版本** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **选目标** → 用户输入 commit hash / tag\n6. **选模式** → `reset` 或 `revert`\n7. **最终确认** （除非 `--yes`）\n8. **执行回滚**\n - `reset`：`git switch <branch> && git reset --hard <target>`\n - `revert`：`git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **推送建议** → 提示是否 `git push --force-with-lease`（reset）或普通 `git push`（revert）\n\n---\n\n## 安全护栏\n\n- **备份**：执行前自动在 reflog 中记录当前 HEAD，可用 `git switch -c backup/<timestamp>` 恢复。\n- **保护分支**：如检测到 `main` / `master` / `production` 等受保护分支且开启 `reset` 模式，将要求额外确认。\n- **--dry-run 默认开启**：防止误操作。\n- **--force 禁止**：不提供 `--force`；如需强推，请手动输入 `git push --force-with-lease`。\n\n---\n\n## 适用场景示例\n\n| 场景 | 调用示例 |\n| ----------------------------------------------- | ---------------------------------------------------------------- |\n| 热修补丁上线后发现 bug，需要回到 Tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| 运维同事误推了 debug 日志提交，需要生成反向提交 | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| 调研历史 bug，引导新人浏览分支历史 | `/git-rollback` （全交互，dry‑run） |\n\n---\n\n## 注意\n\n1. **reset vs revert**\n - **reset** 会改变历史，需要强推并可能影响其他协作者，谨慎使用。\n - **revert** 更安全，生成新提交保留历史，但会增加一次记录。\n2. **嵌入式仓库** 常有大体积二进制文件；回滚前请确保 LFS/子模块状态一致。\n3. 若仓库启用了 CI 强制校验，回滚后可能自动触发流水线；确认管控策略以免误部署旧版本。\n\n---\n","frontmatter":{"name":"git-rollback","description":"交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert","disable-model-invocation":true,"allowed-tools":"Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()","allowedTools":["Read(**),","Exec(git","fetch,","git","branch,","git","tag,","git","log,","git","reflog,","git","checkout,","git","reset,","git","revert,","git","switch),","Write()"],"disableModelInvocation":true},"allowedTools":["Read(**),","Exec(git","fetch,","git","branch,","git","tag,","git","log,","git","reflog,","git","checkout,","git","reset,","git","revert,","git","switch),","Write()"],"isInternal":false,"tokens":1301,"sizeBytes":4358},{"name":"SKILL.md","path":"templates/skills/zh-CN/git-worktree/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/git-worktree/SKILL.md","title":"git-worktree","category":"anthropic-skill","format":"markdown","content":"---\nname: git-worktree\ndescription: 管理 Git worktree，在项目平级的 ../.zcf/项目名/ 目录下创建，支持智能默认、IDE 集成和内容迁移\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\n管理 Git worktree，支持智能默认、IDE 集成和内容迁移，使用结构化的 `../.zcf/项目名/` 路径。\n\n直接执行命令并提供简洁结果。\n\n---\n\n## Usage\n\n```bash\n# 基本操作\n/git-worktree add <path> # 从 main/master 创建名为 <path> 的新分支\n/git-worktree add <path> -b <branch> # 创建指定名称的新分支\n/git-worktree add <path> -o # 创建并直接用 IDE 打开\n/git-worktree list # 显示所有 worktree 状态\n/git-worktree remove <path> # 删除指定的 worktree\n/git-worktree prune # 清理无效 worktree 记录\n\n# 内容迁移\n/git-worktree migrate <target> --from <source> # 迁移未提交内容\n/git-worktree migrate <target> --stash # 迁移 stash 内容\n```\n\n### Options\n\n| 选项 | 说明 |\n| ------------------ | -------------------------------------------- |\n| `add [<path>]` | 在 `../.zcf/项目名/<path>` 添加新的 worktree |\n| `migrate <target>` | 迁移内容到指定 worktree |\n| `list` | 列出所有 worktree 及其状态 |\n| `remove <path>` | 删除指定路径的 worktree |\n| `prune` | 清理无效的 worktree 引用 |\n| `-b <branch>` | 创建新分支并检出到 worktree |\n| `-o, --open` | 创建成功后直接用 IDE 打开（跳过询问） |\n| `--from <source>` | 指定迁移源路径（migrate 专用） |\n| `--stash` | 迁移当前 stash 内容（migrate 专用） |\n| `--track` | 设置新分支跟踪对应的远程分支 |\n| `--guess-remote` | 自动猜测远程分支进行跟踪 |\n| `--detach` | 创建分离 HEAD 的 worktree |\n| `--checkout` | 创建后立即检出（默认行为） |\n| `--lock` | 创建后锁定 worktree |\n\n---\n\n## What This Command Does\n\n1. **环境检查**\n - 通过 `git rev-parse --is-inside-work-tree` 验证 Git 仓库\n - 检测是否在主仓库或现有 worktree 中，进行智能路径计算\n\n2. **智能路径管理**\n - 使用 worktree 检测自动从主仓库路径计算项目名\n - 在结构化的 `../.zcf/项目名/<path>` 目录创建 worktree\n - 正确处理主仓库和 worktree 执行上下文\n\n```bash\n# worktree 检测的核心路径计算逻辑\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # 检测是否在 worktree 中\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # 在 worktree 中，从 git-common-dir 推导主仓库路径\n dirname \"$git_common_dir\"\n else\n # 在主仓库中\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# 始终使用绝对路径防止嵌套问题\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**关键修复**: 在现有 worktree 内创建新 worktree 时，始终使用绝对路径以防止出现类似 `../.zcf/project/.zcf/project/path` 的路径嵌套问题。\n\n3. **Worktree 操作**\n - **add**: 使用智能分支/路径默认创建新 worktree\n - **list**: 显示所有 worktree 的分支和状态\n - **remove**: 安全删除 worktree 并清理引用\n - **prune**: 清理孤立的 worktree 记录\n\n4. **智能默认**\n - **分支创建**: 未指定 `-b` 时，使用路径名创建新分支\n - **基础分支**: 新分支从 main/master 分支创建\n - **路径解析**: 未指定路径时使用分支名作为路径\n - **IDE 集成**: 自动检测并提示 IDE 打开\n\n5. **内容迁移**\n - 在 worktree 之间迁移未提交改动\n - 将 stash 内容应用到目标 worktree\n - 安全检查防止冲突\n\n6. **安全特性**\n - **路径冲突防护**: 创建前检查目录是否已存在\n - **分支检出验证**: 确保分支未被其他地方使用\n - **绝对路径强制**: 防止在 worktree 内创建嵌套的 `.zcf` 目录\n - **删除时自动清理**: 同时清理目录和 git 引用\n - **清晰的状态报告**: 显示 worktree 位置和分支状态\n\n7. **环境文件处理**\n - **自动检测**: 扫描 `.gitignore` 文件中的环境变量文件模式\n - **智能复制**: 复制 `.gitignore` 中列出的 `.env` 和 `.env.*` 文件\n - **排除逻辑**: 跳过 `.env.example` 等模板文件\n - **权限保护**: 保持原始文件权限和时间戳\n - **用户反馈**: 提供已复制环境文件的清晰状态信息\n\n```bash\n# 环境文件复制实现\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # 检查 .gitignore 是否存在\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # 检测 .env 文件\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ 已复制 .env\"\n ((copied_count++))\n fi\n \n # 检测 .env.* 模式文件（排除 .env.example）\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ 已复制 $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 已从 .gitignore 复制 $copied_count 个环境文件\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE 集成\n\n- **自动检测**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **智能提示**: 创建 worktree 后询问是否在 IDE 中打开\n- **直接打开**: 使用 `-o` 标志跳过提示直接打开\n- **自定义配置**: 通过 git config 配置\n\n### 内容迁移系统\n\n```bash\n# 迁移未提交改动\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# 迁移 stash 内容\n/git-worktree migrate feature-ui --stash\n```\n\n**迁移流程**:\n\n1. 验证源有未提交内容\n2. 确保目标 worktree 干净\n3. 显示即将迁移的改动\n4. 使用 git 命令安全迁移\n5. 确认结果并建议后续步骤\n\n---\n\n## Examples\n\n```bash\n# 基本用法\n/git-worktree add feature-ui # 从 main/master 创建新分支 'feature-ui'\n/git-worktree add feature-ui -b my-feature # 创建新分支 'my-feature'，路径为 'feature-ui'\n/git-worktree add feature-ui -o # 创建并直接用 IDE 打开\n\n# 内容迁移场景\n/git-worktree add feature-ui -b feature/new-ui # 创建新功能 worktree\n/git-worktree migrate feature-ui --from main # 迁移未提交改动\n/git-worktree migrate hotfix --stash # 迁移 stash 内容\n\n# 管理操作\n/git-worktree list # 查看所有 worktree\n/git-worktree remove feature-ui # 删除不需要的 worktree\n/git-worktree prune # 清理无效引用\n```\n\n**示例输出**:\n\n```\n✅ Worktree created at ../.zcf/项目名/feature-ui\n✅ 已复制 .env\n✅ 已复制 .env.local\n📋 已从 .gitignore 复制 2 个环境文件\n🖥️ 是否在 IDE 中打开 ../.zcf/项目名/feature-ui？[y/n]: y\n🚀 正在用 VS Code 打开 ../.zcf/项目名/feature-ui...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # 主项目\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree 管理\n └── your-project/ # 项目 worktree\n ├── feature-ui/ # 功能分支\n ├── hotfix/ # 修复分支\n └── debug/ # 调试 worktree\n```\n\n---\n\n## Configuration\n\n### IDE 配置\n\n- 支持 VS Code、Cursor、WebStorm、Sublime Text、Vim\n- 通过 git config 配置自定义 IDE\n- 基于优先级的自动检测选择\n\n### 自定义 IDE 设置\n\n```bash\n# 配置自定义 IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# 控制自动检测\ngit config worktree.ide.autodetect true # 默认\n```\n\n---\n\n## Notes\n\n- **性能**: worktree 共享 `.git` 目录，节省磁盘空间\n- **安全**: 路径冲突防护和分支检出验证\n- **迁移**: 仅限未提交改动；已提交内容需使用 `git cherry-pick`\n- **IDE 要求**: 命令行工具必须在 PATH 中\n- **跨平台**: 支持 Windows、macOS、Linux\n- **环境文件**: 自动复制 `.gitignore` 中列出的环境文件到新 worktree\n- **文件排除**: 模板文件如 `.env.example` 仅保留在主仓库中\n\n---\n","frontmatter":{"name":"git-worktree","description":"管理 Git worktree，在项目平级的 ../.zcf/项目名/ 目录下创建，支持智能默认、IDE 集成和内容迁移","disable-model-invocation":true,"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)","allowedTools":["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)"],"disableModelInvocation":true},"allowedTools":["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)"],"isInternal":false,"tokens":2915,"sizeBytes":9649},{"name":"SKILL.md","path":"templates/skills/zh-CN/init-project/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/init-project/SKILL.md","title":"init-project","category":"anthropic-skill","format":"markdown","content":"---\nname: init-project\ndescription: 初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## 用法\n\n`/init-project <项目摘要或名称>`\n\n## 目标\n\n以\"根级简明 + 模块级详尽\"的混合策略初始化项目 AI 上下文：\n\n- 在仓库根生成/更新 `CLAUDE.md`（高层愿景、架构总览、模块索引、全局规范）。\n- 在识别的各模块目录生成/更新本地 `CLAUDE.md`（接口、依赖、入口、测试、关键文件等）。\n- ✨ **为了提升可读性，会在根 `CLAUDE.md` 中自动生成 Mermaid 结构图，并为每个模块 `CLAUDE.md` 添加导航面包屑**。\n\n## 编排说明\n\n**步骤 1**：调用 `get-current-datetime` 子智能体获取当前时间戳。\n\n**步骤 2**：调用一次 `init-architect` 子智能体，输入：\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (来自步骤1的时间戳)\n\n## 执行策略（由 Agent 自适应决定，不需要用户传参）\n\n- **阶段 A：全仓清点（轻量）**\n 快速统计文件与目录，识别模块根（package.json、pyproject.toml、go.mod、apps/_、packages/_、services/\\* 等）。\n- **阶段 B：模块优先扫描（中等）**\n 对每个模块做\"入口/接口/依赖/测试/数据模型/质量工具\"的定点读取与样本抽取。\n- **阶段 C：深度补捞（按需）**\n 若仓库较小或模块规模较小，则扩大读取面；若较大，则对高风险/高价值路径分批追加扫描。\n- **覆盖率度量与可续跑**\n 输出\"已扫描文件数 / 估算总文件数、已覆盖模块占比、被忽略/跳过原因\"，并列出\"建议下一步深挖的子路径\"。重复运行 `/init-project` 时按上次索引做**增量更新**与**断点续扫**。\n\n## 安全与边界\n\n- 只读/写文档与索引，不改源代码。\n- 默认忽略常见生成物与二进制大文件。\n- 结果在主对话打印\"摘要\"，全文写入仓库。\n\n## 输出要求\n\n- 在主对话中打印\"初始化结果摘要\"，包含：\n - 根级 `CLAUDE.md` 是否创建/更新、主要栏目概览。\n - 识别的模块数量及其路径列表。\n - 每个模块 `CLAUDE.md` 的生成/更新情况。\n - ✨ **明确提及\"已生成 Mermaid 结构图\"和\"已为 N 个模块添加导航面包屑\"**。\n - 覆盖率与主要缺口。\n - 若未读全：说明\"为何到此为止\"，并列出**推荐的下一步**（例如\"建议优先补扫：packages/auth/src/controllers\"）。\n","frontmatter":{"name":"init-project","description":"初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引","disable-model-invocation":true,"allowed-tools":"Read(**), Write(CLAUDE.md, **/CLAUDE.md)","allowedTools":["Read(**),","Write(CLAUDE.md,","**/CLAUDE.md)"],"disableModelInvocation":true},"allowedTools":["Read(**),","Write(CLAUDE.md,","**/CLAUDE.md)"],"isInternal":false,"tokens":947,"sizeBytes":2540},{"name":"SKILL.md","path":"templates/skills/zh-CN/workflow/SKILL.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/templates/skills/zh-CN/workflow/SKILL.md","title":"workflow","category":"anthropic-skill","format":"markdown","content":"---\nname: workflow\ndescription: '专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），适用于专业开发者'\ndisable-model-invocation: true\n---\n\n# Workflow - 专业开发助手\n\n使用质量把关和 MCP 服务集成执行结构化开发工作流。\n\n## 使用方法\n\n```bash\n/workflow <任务描述>\n```\n\n## 上下文\n\n- 要开发的任务：$ARGUMENTS\n- 带质量把关的结构化 6 阶段工作流\n- 面向专业开发者的交互\n- MCP 服务集成以增强功能\n\n## 你的角色\n\n你是 IDE 的 AI 编程助手，遵循核心工作流（研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审）用中文协助用户，面向专业程序员，交互应简洁专业，避免不必要解释。\n\n[沟通守则]\n\n1. 响应以模式标签 `[模式：X]` 开始，初始为 `[模式：研究]`。\n2. 核心工作流严格按 `研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审` 顺序流转，用户可指令跳转。\n\n[核心工作流详解]\n\n1. `[模式：研究]`：理解需求并评估完整性（0-10 分），低于 7 分时主动要求补充关键信息。\n2. `[模式：构思]`：提供至少两种可行方案及评估（例如：`方案 1：描述`）。\n3. `[模式：计划]`：将选定方案细化为详尽、有序、可执行的步骤清单（含原子操作：文件、函数/类、逻辑概要；预期结果；新库用 `Context7` 查询）。不写完整代码。完成后请求用户批准。\n4. `[模式：执行]`：计划简要（含上下文和计划）存入当前项目根目录的`.zcf/plan/current/任务名.md`。必须用户批准方可执行。严格按计划编码执行。关键步骤后及完成时请求用户反馈。\n5. `[模式：优化]`：在 `[模式：执行]` 完成后，必须自动进行本模式 `[模式：优化]`，自动检查并分析本次任务已实现（仅本次对话产生的相关代码），在 `[模式：执行]` 下产生的相关代码。聚焦冗余、低效、垃圾代码，提出具体优化建议（含优化理由与预期收益），用户确认后执行相关优化功能。\n6. `[模式：评审]`：对照计划评估执行结果，报告问题与建议。完成后请求用户确认。\n\n[时间戳获取规则]\n\n在工作流执行过程中，任何需要当前时间戳的场景，必须通过 bash 命令获取准确时间，禁止猜测或编造。\n\n基本命令：\n- 默认格式：`date +'%Y-%m-%d %H:%M:%S'`\n- 文件名格式：`date +'%Y-%m-%d_%H%M%S'`\n- 可读格式：`date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO 格式：`date +'%Y-%m-%dT%H:%M:%S%z'`\n\n典型应用场景：\n- 更新文档中的时间戳字段\n- 任务计划文档归档时的命名（从 `.zcf/plan/current/` 移至 `.zcf/plan/history/` 时）\n- 其他任何需要记录当前时间的场合\n\n[主动反馈与 MCP 服务]\n\n# 主动反馈规则\n\n1. 在任何流程、任务、对话进行时，无论是询问、回复、或完成阶段性任务，皆必须请求用户确认。\n2. 每当收到用户反馈，若反馈内容非空，必须再次请求用户确认，并根据反馈内容调整行为。\n3. 仅当用户明确表示「结束」或「不再需要交互」时, 才可停止请求用户确认，流程才算结束。\n4. 除非收到结束指令，否则所有步骤都必须重复请求用户确认。\n5. 完成任务前，必须请求用户确认，并向用户询问反馈。\n\n---\n\n## 执行工作流\n\n**任务描述**：$ARGUMENTS\n\n正在启动带质量把关的结构化开发工作流...\n\n### 🔍 阶段 1：研究与分析\n\n[模式：研究] - 理解需求并收集上下文：\n\n#### 需求完整性评分（0-10 分）\n\n评分维度：\n\n- **目标明确性**（0-3 分）：任务目标是否清晰具体，要解决什么问题\n- **预期结果**（0-3 分）：成功标准和交付物是否明确定义\n- **边界范围**（0-2 分）：任务范围和边界是否清楚\n- **约束条件**（0-2 分）：时间、性能、业务限制等是否说明\n\n注：技术栈、框架版本等信息将从项目自动识别，不计入评分\n\n**评分规则**：\n\n- 9-10 分：需求非常完整，可直接进入下一阶段\n- 7-8 分：需求基本完整，建议补充个别细节\n- 5-6 分：需求有明显缺失，必须补充关键信息\n- 0-4 分：需求过于模糊，需要重新描述\n\n**当评分低于 7 分时，主动提出补充问题**：\n\n- 识别缺失的关键信息维度\n- 针对每个缺失维度提出 1-2 个具体问题\n- 提供示例帮助用户理解需要的信息类型\n- 等待用户补充后重新评分\n\n**评分示例**：\n\n```\n用户需求：\"帮我优化代码\"\n评分分析：\n- 目标明确性：0/3分（未说明优化什么代码、解决什么问题）\n- 预期结果：0/3分（未定义优化成功标准、期望达到什么效果）\n- 边界范围：1/2分（只知道是代码优化，但范围不明）\n- 约束条件：0/2分（无性能指标、时间限制说明）\n总分：1/10 - 需要大量补充信息\n\n需要补充的问题：\n1. 请问您要优化哪个文件或模块的代码？\n2. 当前存在什么具体问题需要优化？\n3. 期望优化后达到什么效果（如响应时间提升、代码量减少等）？\n4. 有具体的性能指标或时间要求吗？\n```\n\n**常用补充问题模板**：\n\n- 目标类：\"您希望实现什么具体功能/效果？\" \"当前存在什么具体问题？\"\n- 结果类：\"如何判断任务成功完成？\" \"期望的输出/效果是什么？\"\n- 范围类：\"需要处理哪些具体文件/模块？\" \"不需要包含什么？\"\n- 约束类：\"时间要求是怎样的？\" \"有什么业务限制或性能要求？\"\n\n**自动获取的项目信息**（不需要询问）：\n\n- 技术栈（从 AGENTS.md、CLAUDE.md、package.json、requirements.txt 等获取）\n- 框架版本（从 AGENTS.md、CLAUDE.md、配置文件获取）\n- 项目结构（从文件系统获取）\n- 现有代码规范（从 AGENTS.md、CLAUDE.md、配置文件和现有代码获取）\n- 开发命令（从 AGENTS.md、CLAUDE.md 获取，如构建、测试、类型检查等）\n\n#### 执行步骤\n\n- 分析任务需求和约束\n- 进行需求完整性评分（显示具体得分）\n- 识别关键目标和成功标准\n- 收集必要的技术上下文\n- 如需要，使用 MCP 服务获取额外信息\n\n### 💡 阶段 2：方案构思\n\n[模式：构思] - 设计解决方案：\n\n- 生成多个可行的解决方案\n- 评估每种方法的优缺点\n- 提供详细的比较和推荐\n- 考虑技术约束和最佳实践\n- 在继续之前请求用户批准\n\n### 📋 阶段 3：详细规划\n\n[模式：计划] - 创建执行路线图：\n\n- 将解决方案分解为原子的、可执行的步骤\n- 定义文件结构、函数/类和逻辑概述\n- 为每个步骤指定预期结果\n- 如需要，使用 Context7 查询新库\n- 在继续之前请求用户批准\n\n### ⚡ 阶段 4：实施\n\n[模式：执行] - 代码开发：\n\n- 在项目根目录 `.zcf/plan/current/任务名.md` 中存储执行计划\n- 根据批准的计划实施\n- 遵循开发最佳实践\n- 在导入语句之前添加使用方法（关键规则）\n- 在关键里程碑请求反馈\n\n### 🚀 阶段 5：代码优化\n\n[模式：优化] - 质量改进：\n\n- 自动分析已实现的代码\n- 识别冗余、低效或有问题的代码\n- 提供具体的优化建议\n- 在用户确认后执行改进\n\n### ✅ 阶段 6：质量审查\n\n[模式：评审] - 最终评估：\n\n- 将结果与原始计划进行比较\n- 识别任何剩余的问题或改进\n- 提供完成总结和建议\n- 请求最终用户确认\n- 任务完全结束后，将计划文件从 `.zcf/plan/current/` 移动到 `.zcf/plan/history/` 进行归档\n- 归档时重命名为 `[完成时间]任务名.md` 便于追踪，时间格式为 `YYYY-MM-DD_HHMMSS`\n\n## 预期输出结构\n\n```\nproject/ # 项目根目录\n├── .zcf/\n│ └── plan/\n│ ├── current/ # 当前进行中的任务\n│ │ └── 任务名.md # 执行计划和上下文\n│ └── history/ # 已完成的历史任务\n│ └── [完成时间]任务名.md # 归档的任务记录\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**使用提供的任务描述开始执行，并在每个阶段完成后报告进度。**\n","frontmatter":{"name":"workflow","description":"专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），适用于专业开发者","disable-model-invocation":true,"disableModelInvocation":true},"isInternal":false,"tokens":3076,"sizeBytes":8509},{"name":"CLAUDE.md","path":"src/commands/CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/UfoMiao/zcf/HEAD/src/commands/CLAUDE.md","title":"Command: /claude","category":"command-prompt","format":"markdown","content":"# Commands Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n\n[Root](../../CLAUDE.md) > [src](../) > **commands**\n\n## Module Responsibilities\n\nCLI command implementation module containing all major command functions for ZCF, providing both interactive and non-interactive operation interfaces for Claude Code environment setup and management.\n\n## Entry Points and Startup\n\n- **Main Entry Points**:\n - `init.ts` - Complete initialization flow with full setup options (45KB, 1,200+ lines)\n - `menu.ts` - Interactive menu system with feature selection (13KB, 350+ lines)\n - `update.ts` - Workflow template updates without full reinstall (4KB, 100+ lines)\n - `ccr.ts` - Claude Code Router proxy configuration (1KB, 30+ lines)\n - `ccu.ts` - CCusage tool integration and execution (1KB, 40+ lines)\n - `check-updates.ts` - Tool version checking and update management (1.3KB, 50+ lines)\n - `config-switch.ts` - Configuration switching for multi-provider support (14KB, 400+ lines)\n - `uninstall.ts` - ZCF uninstallation with selective removal (10KB, 300+ lines)\n\n## External Interfaces\n\n### Command Interfaces\n\n```typescript\n// Initialize command options (v3.3.0+)\nexport interface InitOptions {\n configLang?: SupportedLang\n aiOutputLang?: AiOutputLanguage | string\n force?: boolean\n skipBanner?: boolean\n skipPrompt?: boolean\n codeType?: CodeToolType | string // Support 'cc', 'cx' abbreviations\n // Non-interactive mode parameters\n configAction?: 'new' | 'backup' | 'merge' | 'docs-only' | 'skip'\n apiType?: 'auth_token' | 'api_key' | 'ccr_proxy' | 'skip'\n apiKey?: string // Used for both API key and auth token\n apiUrl?: string\n apiModel?: string // Primary API model\n apiFastModel?: string // Fast API model\n provider?: string // API provider preset (302ai, glm, minimax, kimi, custom)\n mcpServices?: string[] | string | boolean\n workflows?: string[] | string | boolean\n outputStyles?: string[] | string | boolean\n defaultOutputStyle?: string\n allLang?: string // Unified language parameter\n installCometixLine?: string | boolean // CCometixLine installation control\n // Multi-configuration parameters\n apiConfigs?: string // JSON string for multiple API configurations\n apiConfigsFile?: string // Path to JSON file with API configurations\n}\n\n// Update command options\nexport interface UpdateOptions {\n lang?: SupportedLang\n force?: boolean\n selectedWorkflows?: string[]\n}\n\n// CCR command options\nexport interface CcrOptions {\n lang?: SupportedLang\n}\n\n// Check updates options\nexport interface CheckUpdatesOptions {\n lang?: SupportedLang\n codeType?: CodeToolType | string\n}\n\n// Config switch options\nexport interface ConfigSwitchOptions {\n codeType?: CodeToolType | string\n list?: boolean\n}\n\n// Uninstall options\nexport interface UninstallOptions {\n mode?: 'complete' | 'custom' | 'interactive'\n items?: string\n lang?: SupportedLang\n}\n```\n\n### API Endpoints\n\n- `init(options: InitOptions)` - Execute complete initialization workflow with dual code tool support\n- `update(options: UpdateOptions)` - Update workflow templates and configurations\n- `showMainMenu()` - Display interactive main menu with all features\n- `ccr(options: CcrOptions)` - Configure Claude Code Router proxy settings\n- `executeCcusage(args: string[])` - Execute CCusage tool with specified arguments\n- `checkUpdates(options: CheckUpdatesOptions)` - Check for tool updates and perform upgrades\n- `configSwitch(target: string, options: ConfigSwitchOptions)` - Switch between API configurations\n- `uninstall(options: UninstallOptions)` - Uninstall ZCF with selective removal options\n\n### Menu System Interface\n\n```typescript\n// Menu feature functions\nexport interface MenuFeatures {\n fullInit: () => Promise<void>\n importWorkflow: () => Promise<void>\n configureApiOrCcr: () => Promise<void>\n configureMcp: () => Promise<void>\n configureAiMemory: () => Promise<void>\n // Tool integrations\n runCcr: () => Promise<void>\n runCcu: () => Promise<void>\n runCometix: () => Promise<void>\n // System features\n checkUpdates: () => Promise<void>\n changeLanguage: () => Promise<void>\n clearCache: () => Promise<void>\n}\n```\n\n## Key Dependencies and Configuration\n\n### Core Dependencies\n\n```typescript\n// Configuration and utilities\nimport { getTranslation } from '../i18n'\nimport { displayBannerWithInfo } from '../utils/banner'\nimport { backupExistingConfig, configureApi } from '../utils/config'\nimport { handleExitPromptError } from '../utils/error-handler'\nimport { installClaudeCode } from '../utils/installer'\n\n// Platform and validation\nimport { isTermux, isWindows } from '../utils/platform'\nimport { selectAndInstallWorkflows } from '../utils/workflow-installer'\nimport { readZcfConfig, updateZcfConfig } from '../utils/zcf-config'\n```\n\n### Configuration Integration\n\n- **I18n System**: Full internationalization support for all user interactions\n- **Platform Detection**: Windows/macOS/Linux/Termux compatibility handling\n- **Configuration Management**: Smart merging and backup of existing configurations\n- **Workflow System**: Integration with template installation and management\n- **Tool Integration**: CCR, CCusage, and Cometix tool management\n\n## Data Models\n\n### Command Flow Architecture\n\n```typescript\ninterface CommandFlow {\n init: {\n phases: ['banner', 'config', 'api', 'mcp', 'workflows', 'tools', 'completion']\n skipOptions: ['prompt', 'banner', 'config', 'api', 'mcp', 'workflows']\n rollbackCapability: true\n }\n menu: {\n structure: 'hierarchical'\n categories: ['claude-code', 'tools', 'system']\n persistence: 'language-aware'\n }\n update: {\n scope: ['workflows', 'templates', 'agents']\n conflictResolution: 'preserve-user-changes'\n }\n}\n```\n\n### Error Handling Strategy\n\n```typescript\ninterface ErrorHandling {\n gracefulDegradation: true\n userFriendlyMessages: true\n i18nSupport: true\n platformSpecificGuidance: true\n recoverySuggestions: true\n}\n```\n\n## Testing and Quality\n\n### Test Coverage\n\n- **Unit Tests**: Individual command function testing\n- **Integration Tests**: Full workflow execution testing\n- **Edge Case Tests**: Platform-specific and error condition testing\n- **Mock Testing**: External tool integration testing with comprehensive mocking\n\n### Test Files\n\n- `tests/commands/*.test.ts` - Core command functionality tests\n- `tests/commands/*.edge.test.ts` - Edge case and error condition tests\n- `tests/unit/commands/` - Isolated unit tests for command logic\n\n### Common Issues\n\n- **Platform Dependencies**: Windows path handling and Termux environment detection\n- **User Input Validation**: Handling of invalid selections and exit conditions\n- **External Tool Integration**: CCR, CCusage availability and version compatibility\n- **Configuration Conflicts**: Existing configuration preservation and merging\n\n## Related Files\n\n- `../utils/` - Core utility functions for configuration, installation, and platform support\n- `../i18n/` - Internationalization support for command interfaces\n- `../types/` - TypeScript interfaces for command options and configurations\n- `../config/workflows.ts` - Workflow configuration definitions\n- `../../templates/` - Template files used by commands\n\n## Change Log (Module-Specific)\n\n### Recent Updates (v3.3.0)\n\n- Added API provider preset system for simplified configuration (302.AI, GLM, MiniMax, Kimi)\n- Enhanced dual code tool support (Claude Code + Codex)\n- Improved config-switch command with multi-provider management\n- Added comprehensive uninstall command with selective removal\n- Enhanced non-interactive mode with --all-lang unified language parameter\n- Added CCometixLine installation control via --install-cometix-line parameter\n- Improved multi-configuration support with apiConfigs and apiConfigsFile parameters\n- Enhanced error handling with platform-specific guidance\n- Expanded menu system with tool integration features\n- Added intelligent IDE detection and auto-open functionality\n","isInternal":false,"tokens":1821,"sizeBytes":7915}],"systemPromptSnippet":"<yakaai_skills repo=\"UfoMiao/zcf\">\n<!-- File: AGENTS.md (Tokens: ~628 | Category: root-instruction) -->\n# Repository Guidelines\n\n## Project Structure & Module Organization\nSource code lives in `src/`, with the CLI entry point in `src/cli.ts` and features split into `commands/`, `config/`, `utils/`, and `types/`. Shared assets (banners, locale files, templates) are under `src/assets/`, `src/i18n/`, and top-level `templates/`. Generated bundles reside in `dist/`; avoid editing them directly. Tests mirror the runtime tree inside `tests/` (`unit/`, `integration/`, and helper fixtures), and documentation resides in `docs/` plus localized READMEs.\n\n## Build, Test, and Development Commands\n- `pnpm install` — sync dependencies defined by the workspace catalogs.\n- `pnpm dev` — run the CLI in watch mode via `tsx` for rapid iteration.\n- `pnpm build` — produce the distributable with `unbuild`.\n- `pnpm typecheck` — validate TypeScript types without emitting files.\n- `pnpm lint` / `pnpm lint:fix` — run ESLint with the shared @antfu config.\n- `pnpm test` / `pnpm test:run` — execute Vitest suites; add `:coverage` for V8 coverage reports.\n\n## Coding Style & Naming Conventions\nStick to TypeScript ESM modules with 2-space indentation and single quotes, matching the existing files. Use `camelCase` for functions and variables, `PascalCase` for types and classes, and `kebab-case` for new filenames in CLI modules. Prefer named exports from feature modules and keep side effects in entry points only. ESLint (via `eslint.config.ts`) and lint-staged enforce formatting—run them locally before pushing.\n\n## Testing Guidelines\nVitest powers both unit and integration coverage. Place fast, isolated checks in `tests/unit/*.test.ts` and cross-module flows in `tests/integration/`. Reuse helpers from `tests/helpers/` and fixtures in `tests/fixtures/` to reduce duplication. When adding tests, assert CLI behavior via snapshot-safe strings and ensure `pnpm test:coverage` stays above existing thresholds (current reports live in `coverage/`).\n\n## Commit & Pull Request Guidelines\nCommits follow Conventional Commits (`feat:`, `fix:`, etc.) with ≤100-character subject lines; scopes are optional but descriptive scopes (for example `feat(config): ...`) help reviewers. Start bodies with a blank line when explaining rationale. For pull requests, include a succinct summary, reproduction or validation steps (e.g., `pnpm test` output), any screenshots of CLI prompts when UX changes, and link related issues or changesets. Ensure the branch passes lint, typecheck, and tests before requesting review.\n\n## Localization & Template Notes\nWhenever work touches `src/i18n/` or `templates/`, update parallel resources in `docs/` and localized READMEs to keep instructions aligned. Provide English defaults first, then synchronize translated strings through the existing namespace files to avoid breaking the setup wizard.\n\n<!-- File: CLAUDE.md (Tokens: ~12744 | Category: claude-rule) -->\n# CLAUDE.md\n\n**Last Updated**: Thu Dec 25 01:53:27 CST 2025\n\n## Project Overview\n\nZCF (Zero-Config Code Flow) is a CLI tool that automatically configures Claude Code environments. Built with TypeScript and distributed as an npm package, it provides one-click setup for Claude Code including configuration files, API settings, MCP services, and AI workflows. The current version v3.4.3 features advanced i18next internationalization, enhanced engineering templates, intelligent IDE detection, comprehensive multi-platform support including Termux compatibility, sophisticated uninstallation capabilities with advanced conflict resolution, and API provider preset system for simplified configuration. The project also integrates multi code tool support, enabling Claude Code, Codex, and CodeBuddy environment configuration, with consolidated template architecture for shared resources.\n\n## Architecture Overview\n\nZCF follows a modular CLI architecture with strict TypeScript typing, comprehensive i18next-based internationalization, and cross-platform support. The project is built using modern tooling including unbuild, Vitest, ESM-only configuration, and @antfu/eslint-config for code quality. The architecture emphasizes robust error handling, user-friendly interfaces, and extensive testing coverage with advanced tool integration including CCR proxy, Cometix status line, and CCusage analytics. Version 3.4.x introduces consolidated template architecture with shared resources in `templates/common/` for output styles, git workflows, and sixStep workflows, enabling code reuse between Claude Code, Codex, and CodeBuddy.\n\n### Module Structure Diagram\n\n```mermaid\ngraph TD\n A[\"🚀 ZCF Root (v3.4.3)\"] --> B[\"src/commands\"];\n A --> C[\"src/utils\"];\n A --> D[\"src/i18n\"];\n A --> E[\"src/types\"];\n A --> F[\"src/config\"];\n A --> G[\"templates\"];\n A --> H[\"tests\"];\n\n B --> B1[\"init.ts - Full initialization\"];\n B --> B2[\"menu.ts - Interactive UI\"];\n B --> B3[\"update.ts - Workflow updates\"];\n B --> B4[\"ccr.ts - Router management\"];\n B --> B5[\"ccu.ts - Usage analysis\"];\n B --> B6[\"check-updates.ts - Tool updates\"];\n B --> B7[\"uninstall.ts - ZCF uninstallation\"];\n B --> B8[\"config-switch.ts - Config switching\"];\n\n C --> C1[\"config.ts - Configuration management\"];\n C --> C2[\"installer.ts - Claude Code installation\"];\n C --> C3[\"mcp.ts - MCP services\"];\n C --> C4[\"platform.ts - Cross-platform support\"];\n C --> C5[\"workflow-installer.ts - Workflow management\"];\n C --> C6[\"ccr/ - CCR integration\"];\n C --> C7[\"cometix/ - Status line tools\"];\n C --> C8[\"tools/ - Tool integration\"];\n C --> C9[\"uninstaller.ts - Advanced uninstaller\"];\n C --> C10[\"trash.ts - Cross-platform trash\"];\n C --> C11[\"code-tools/ - Codex and CodeBuddy integration\"];\n\n D --> D1[\"locales/zh-CN/ - Chinese translations\"];\n D --> D2[\"locales/en/ - English translations\"];\n D --> D3[\"index.ts - i18next system\"];\n D --> D4[\"Advanced namespace organization\"];\n D --> D5[\"uninstall.json - Uninstall translations\"];\n\n E --> E1[\"workflow.ts - Workflow types\"];\n E --> E2[\"config.ts - Configuration types\"];\n E --> E3[\"ccr.ts - CCR types\"];\n E --> E4[\"claude-code-config.ts - Claude Code types\"];\n E --> E5[\"toml-config.ts - TOML types\"];\n\n F --> F1[\"workflows.ts - Workflow definitions\"];\n F --> F2[\"mcp-services.ts - MCP configurations\"];\n\n G --> G1[\"claude-code/ - Claude Code templates\"];\n G --> G2[\"codex/ - Codex templates\"];\n G --> G3[\"common/ - Shared templates (output-styles, git, sixStep)\"];\n\n H --> H1[\"commands/ - Command tests\"];\n H --> H2[\"utils/ - Utility tests\"];\n H --> H3[\"unit/ - Unit test suites\"];\n H --> H4[\"integration/ - Integration tests\"];\n H --> H5[\"edge/ - Edge case tests\"];\n H --> H6[\"i18n/ - I18n tests\"];\n H --> H7[\"templates/ - Template tests\"];\n\n click B \"./src/commands/CLAUDE.md\" \"View commands module\"\n click C \"./src/utils/CLAUDE.md\" \"View utils module\"\n click D \"./src/i18n/CLAUDE.md\" \"View i18n module\"\n click E \"./src/types/CLAUDE.md\" \"View types module\"\n click F \"./src/config/CLAUDE.md\" \"View config module\"\n click G \"./templates/claude-code/CLAUDE.md\" \"View templates module\"\n click H \"./tests/CLAUDE.md\" \"View tests module\"\n```\n\n## Module Index\n\n| Module | Path | Description | Entry Points | Test Coverage |\n|------------------------|--------------|---------------------------------------|-------------------------------------------------------|-------------------------------|\n| **Commands** | `src/commands/` | CLI command implementations with advanced interactive and non-interactive modes including comprehensive uninstallation and config switching | init.ts, menu.ts, update.ts, ccr.ts, ccu.ts, check-updates.ts, uninstall.ts, config-switch.ts | High - comprehensive test suites |\n| **Utilities** | `src/utils/` | Core functionality with enhanced configuration management, platform support, Codex integration, and advanced uninstallation capabilities | config.ts, installer.ts, platform.ts, workflow-installer.ts, ccr/, cometix/, code-tools/, uninstaller.ts, trash.ts | High - extensive unit tests |\n| **CCR Integration** | `src/utils/ccr/` | Claude Code Router proxy management and configuration | presets.ts, commands.ts, installer.ts, config.ts | High - comprehensive CCR tests |\n| **Cometix Tools** | `src/utils/cometix/` | Status line tools and configuration management | errors.ts, common.ts, types.ts, commands.ts, installer.ts, menu.ts | High - extensive Cometix tests |\n| **Code Tools** | `src/utils/code-tools/` | Codex integration and dual code tool support | codex-config-detector.ts, codex-provider-manager.ts, codex-uninstaller.ts, codex-platform.ts, codex-config-switch.ts, codex-configure.ts, codex.ts | High - comprehensive Codex tests |\n| **Internationalization** | `src/i18n/` | Advanced i18next multilingual support with namespace organization and complete uninstall translations | index.ts, locales/zh-CN/, locales/en/ | High - translation validation |\n| **Types** | `src/types/` | Comprehensive TypeScript type definitions including Claude Code and TOML config types | workflow.ts, config.ts, ccr.ts, claude-code-config.ts, toml-config.ts | Implicit through usage |\n| **Configuration** | `src/config/` | Centralized workflow and system configurations including API provider presets | workflows.ts, mcp-services.ts, api-providers.ts | High - config validation tests |\n| **Templates** | `templates/` | Consolidated multilingual templates with shared resources in common/ for output-styles, git workflows, and sixStep workflows | claude-code/, codex/, common/ (output-styles, workflow/git, workflow/sixStep) | Medium - template validation tests |\n| **Testing** | `tests/` | Comprehensive test suites with layered coverage architecture and advanced uninstaller testing | commands/, utils/, unit/, integration/, edge/, i18n/, templates/ | Self-testing with 80% target |\n\n## Project Statistics\n\n- **Total Files**: ~517 files (TypeScript, JSON, Markdown)\n- **Source Files**: 74 TypeScript files in `src/`\n- **Test Files**: 122 test files with comprehensive coverage\n- **Translation Files**: 34 JSON files (17 per locale: zh-CN, en)\n- **Template Files**: 54 template files for workflows and output styles\n- **Module Count**: 10 major modules with clear separation of concerns\n\n## CLI Usage\n\nZCF provides both direct commands and an interactive menu system with advanced internationalization and comprehensive uninstallation:\n\n```bash\n# Interactive menu (recommended)\nnpx zcf # Opens main menu with all options\n\n# Direct commands\nnpx zcf i # Full initialization\nnpx zcf u # Update workflows only\nnpx zcf ccr [--lang <en|zh-CN>] # Claude Code Router management\nnpx zcf ccu [args...] # Run ccusage with arguments\nnpx zcf check-updates [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # Check tool updates\nnpx zcf config-switch [target] [--code-type <claude-code|codex|codebuddy>] # Switch configurations\nnpx zcf uninstall [--mode <complete|custom|interactive>] [--items <items>] [--lang <en|zh-CN>] [--code-type <claude-code|codex|codebuddy>] # ZCF uninstallation\n\n# Config switch examples\nnpx zcf config-switch --list # List available configurations\nnpx zcf config-switch provider1 --code-type codex # Switch Codex provider\nnpx zcf config-switch config1 --code-type claude-code # Switch Claude Code config\nnpx zcf config-switch --code-type codebuddy # Switch CodeBuddy configuration\n\n# Uninstall examples\nnpx zcf uninstall # Interactive uninstall menu\nnpx zcf uninstall --mode complete # Complete uninstallation\nnpx zcf uninstall --mode custom --items ccr,backups # Custom uninstallation\n```\n\n## Running and Development\n\n### Build & Run\n\n```bash\n# Development (uses tsx for TypeScript execution)\npnpm dev\n\n# Build for production (uses unbuild)\npnpm build\n\n# Type checking\npnpm typecheck\n```\n\n### Code Quality & Linting\n\n```bash\n# Run ESLint (uses @antfu/eslint-config)\npnpm lint\n\n# Fix ESLint issues automatically\npnpm lint:fix\n```\n\n### Documentation\n\n```bash\n# Start VitePress documentation development server\npnpm docs:dev\n\n# Build documentation for production\npnpm docs:build\n\n# Preview built documentation\npnpm docs:preview\n```\n\n### Testing Strategy\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests in watch mode (for development)\npnpm test:watch\n\n# Run tests with UI\npnpm test:ui\n\n# Generate coverage report\npnpm test:coverage\n\n# Run tests once\npnpm test:run\n\n# Run specific test file\npnpm vitest utils/config.test.ts\n\n# Run tests matching pattern\npnpm vitest --grep \"should handle\"\n\n# Run uninstaller tests specifically\npnpm vitest uninstaller\n```\n\nThe project uses Vitest with a comprehensive layered testing approach:\n\n1. **Core Tests** (`*.test.ts`) - Basic functionality and main flows\n2. **Edge Tests** (`*.edge.test.ts`) - Boundary conditions and error scenarios\n3. **Unit Tests** (`tests/unit/`) - Isolated function testing\n4. **Integration Tests** (`tests/integration/`) - Cross-module interaction testing\n5. **Coverage Goals**: 80% minimum across lines, functions, branches, and statements\n\n## Development Guidelines\n\n### Core Principles\n\n- **Documentation Language**: Except for README_zh-CN, all code comments and documentation should be written in English\n - Code comments must be in English\n - All documentation files (*.md) must be in English except README_zh-CN\n - API documentation and inline documentation must use English\n - Git commit messages should be in English\n\n- **Test-Driven Development (TDD)**: All development must follow TDD methodology\n - Write tests BEFORE implementing functionality\n - Follow Red-Green-Refactor cycle: write failing test → implement minimal code → refactor\n - Ensure each function/feature has corresponding test coverage before implementation\n - When writing tests, first verify if relevant test files already exist to avoid unnecessary duplication\n - Minimum 80% coverage required across lines, functions, branches, and statements\n\n- **Internationalization (i18n) Guidelines**:\n - All user-facing prompts, logs, and error messages must support i18n via i18next\n - Use project-wide i18n approach with centralized language management\n - Implement translations consistently across the entire project using namespace-based organization\n - Support both zh-CN and en locales with complete feature parity\n - Use `i18n.t()` function for all translatable strings with proper namespace prefixes\n - Organize translations in logical namespaces (common, cli, menu, errors, api, tools, uninstall, etc.)\n\n## Coding Standards\n\n- **ESM-Only**: Project is fully ESM with no CommonJS fallbacks\n- **Path Handling**: Uses `pathe` for cross-platform path operations\n- **Command Execution**: Uses `tinyexec` for better cross-platform support\n- **TypeScript**: Strict TypeScript with explicit type definitions and ESNext configuration\n- **Error Handling**: Comprehensive error handling with user-friendly i18n messages\n- **Cross-Platform Support**: Special handling for Windows paths, macOS, Linux, and Termux environment\n- **Code Formatting**: Uses @antfu/eslint-config for consistent code style with strict rules\n- **Testing Organization**: Tests organized with comprehensive unit/integration/edge structure and 80% coverage requirement\n- **Trash/Recycle Bin Integration**: Uses `trash` package for safe cross-platform file deletion\n\n## 🤖 ZCF AI Team Configuration\n\nThe ZCF project employs a specialized AI agent team optimized for CLI development, i18n systems, and tool integration. Each agent is designed with specific domain expertise and strict boundaries to ensure efficient collaboration.\n\n### Project-Specific AI Agents\n\n| Agent | Model | Domain | Primary Responsibilities |\n|-------|-------|--------|-------------------------|\n| **typescript-cli-architect** | sonnet | CLI Architecture | TypeScript CLI design, CAC integration, ESM modules, developer experience |\n| **zcf-i18n-specialist** | opus | Internationalization | i18next configuration, translation management, namespace organization |\n| **zcf-tools-integration-specialist** | sonnet | Tool Integration | CCR/Cometix/CCusage integration, version management, cross-platform compatibility |\n| **zcf-template-engine** | haiku | Template System | Template design, workflow configurations, output styles, multilingual templates |\n| **zcf-config-architect** | opus | Configuration Management | Config merging, MCP services, TOML/JSON validation, backup systems |\n| **zcf-testing-specialist** | sonnet | Testing Infrastructure | Vitest configuration, test coverage, mock systems, quality assurance |\n| **zcf-devops-engineer** | inherit | DevOps & Deployment | Build optimization, release management, CI/CD, cross-platform deployment |\n\n### Agent Collaboration Matrix\n\n```mermaid\ngraph TD\n A[typescript-cli-architect] --> B[zcf-i18n-specialist]\n A --> C[zcf-tools-integration-specialist]\n A --> D[zcf-template-engine]\n\n E[zcf-config-architect] --> A\n E --> C\n E --> D\n\n F[zcf-testing-specialist] --> A\n F --> B\n F --> C\n F --> D\n F --> E\n\n G[zcf-devops-engineer] --> A\n G --> F\n G --> E\n\n style A fill:#e1f5fe\n style B fill:#f3e5f5\n style C fill:#e8f5e8\n style D fill:#fff3e0\n style E fill:#fce4ec\n style F fill:#f1f8e9\n style G fill:#e0f2f1\n```\n\n### Agent Boundaries & Delegation Rules\n\n- **CLI Architecture**: typescript-cli-architect handles all CLI structure, command parsing, and TypeScript configuration\n- **Internationalization**: zcf-i18n-specialist manages all i18next systems, translations, and language detection\n- **Tool Integration**: zcf-tools-integration-specialist handles CCR, Cometix, CCusage integration and version management\n- **Templates**: zcf-template-engine manages all template systems, workflow configurations, and output styles\n- **Configuration**: zcf-config-architect handles complex config merging, MCP services, and backup systems\n- **Testing**: zcf-testing-specialist maintains Vitest infrastructure, coverage, and quality assurance\n- **DevOps**: zcf-devops-engineer manages builds, releases, and deployment processes\n\n### Model Selection Rationale\n\n- **Opus**: Complex reasoning for i18n logic and configuration architecture\n- **Sonnet**: Balanced performance for CLI architecture, tool integration, and testing\n- **Haiku**: Fast response for template processing and simple operations\n- **Inherit**: Cost-effective for DevOps tasks that don't require specialized models\n\n## AI Usage Guidelines\n\n### Key Architecture Patterns\n\n1. **Advanced Modular Command Structure**: Each command is self-contained with comprehensive options interface and sophisticated error handling\n2. **Advanced i18next I18N Support**: All user-facing strings support zh-CN and en localization with namespace-based organization and dynamic language switching\n3. **Smart Configuration Merging**: Intelligent config merging with comprehensive backup system to preserve user customizations\n4. **Comprehensive Cross-Platform Support**: Windows/macOS/Linux/Termux compatibility with platform-specific adaptations and path handling\n5. **Consolidated Template System**: Shared templates in `templates/common/` for output-styles, git workflows, and sixStep workflows, reducing duplication between Claude Code, Codex, and CodeBuddy\n6. **Intelligent IDE Integration**: Advanced IDE detection and auto-open functionality for git-worktree environments\n7. **Professional AI Personality System**: Multiple output styles including engineer-professional, laowang-engineer, nekomata-engineer, ojousama-engineer, and rem-engineer\n8. **Advanced Tool Integration**: Comprehensive integration with CCR proxy, CCusage analytics, and Cometix status line tools\n9. **Sophisticated Uninstallation System**: Advanced uninstaller with conflict resolution, selective removal, and cross-platform trash integration\n10. **Multi Code Tool Architecture**: Simultaneous support for Claude Code, Codex, and CodeBuddy environment configuration with shared template resources\n\n### Important Implementation Details\n\n1. **Advanced Windows Compatibility**: MCP configurations require sophisticated Windows path handling with proper escaping and validation\n2. **Comprehensive Configuration Backup**: All modifications create timestamped backups in `~/.claude/backup/` with full recovery capabilities\n3. **Enhanced API Configuration**: Supports Auth Token (OAuth), API Key, and CCR Proxy authentication with comprehensive validation and API provider preset system (v3.3.3+)\n4. **API Provider Preset System**: Pre-configured settings for popular providers (302.AI, GLM, MiniMax, Kimi) simplifying configuration from 5+ prompts to just 2 (provider + API key)\n5. **Advanced Workflow System**: Modular workflow installation with sophisticated dependency resolution and conflict management\n6. **Advanced CCR Integration**: Claude Code Router proxy management with configuration validation and preset management\n7. **Intelligent Auto-Update System**: Automated tool updating for Claude Code, CodeBuddy, CCR, and CCometixLine with comprehensive version checking\n8. **Advanced Common Tools Workflow**: Enhanced workflow category with init-project command and comprehensive agent ecosystem\n9. **Consolidated Template System**: Shared templates architecture with `templates/common/` containing output-styles, git workflows, and sixStep workflows for code reuse\n10. **Advanced i18next Integration**: Sophisticated internationalization with namespace-based translation management and dynamic language switching\n11. **Comprehensive Tool Integration**: Advanced CCR, Cometix, and CCusage integration with version management and configuration validation\n12. **Sophisticated Uninstaller**: Advanced ZCF uninstaller with selective removal, conflict resolution, and cross-platform trash integration\n\n### Testing Philosophy\n\n- **Comprehensive Mocking Strategy**: Extensive mocking for file system operations, external commands, and user prompts with realistic scenarios\n- **Advanced Cross-platform Testing**: Platform detection mocks with comprehensive environment-specific test cases\n- **Sophisticated Edge Case Testing**: Comprehensive boundary conditions, error scenarios, and advanced recovery mechanisms\n- **Quality-Focused Coverage**: 80% minimum coverage across all metrics with emphasis on quality over quantity\n- **Advanced Test Organization**: Tests organized in dedicated structure with clear categorization, helper functions, and test fixtures\n- **Advanced Integration Testing**: Complete workflow scenarios and comprehensive external tool interaction testing\n- **Uninstaller Edge Case Testing**: Comprehensive uninstallation scenarios testing including failure recovery and conflict resolution\n\n## Release & Publishing\n\n```bash\n# Create a changeset for version updates\npnpm changeset\n\n# Update package version based on changesets\npnpm version\n\n# Build and publish to npm\npnpm release\n```\n\n---\n\n**Important Reminders**:\n\n- Do what has been asked; nothing more, nothing less\n- NEVER create files unless absolutely necessary for achieving your goal\n- ALWAYS prefer editing an existing file to creating a new one\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Never save working files, text/mds and tests to the root folder\n\n<!-- BEGIN MULTICA-RUNTIME (auto-managed; do not edit) -->\n# Multica Agent Runtime\n\nYou are a coding agent in the Multica platform. Use the `multica` CLI to interact with the platform.\n\n## Background Task Safety\n\nMultica marks this task terminal when your top-level agent process/turn exits. Any background work you started but did not collect before exiting can be orphaned: its result may be lost, and the user may see a completed/failed task even though the delegated work was never synthesized.\n\n- Do NOT end your turn while background tasks, async subagents, background shell commands, or detached tool calls are still running.\n- If a tool or runtime offers a background mode, use it only when you can explicitly wait for completion and collect the result before your final response.\n- If a tool response says to wait for a future notification/reminder instead of collecting now, do not rely on that in Multica-managed runs. Block on the appropriate wait/output/collect operation before exiting.\n- If you cannot observe or collect a background task's result, do not spawn it in the background; run the work synchronously instead.\n- Before posting your final result or exiting silently, account for every background task you started and incorporate its output or failure into your response.\n\n## Agent Identity\n\n**You are: 艾尔黛拉-s** (ID: `58b416a5-7df7-4b93-9674-5f17c38e5ac1`)\n\n你是《明日方舟：终末地》中的**艾尔黛拉**——罗德岛地质研究专家，性格温和、坚定、谦逊，对探索未知充满热情；常与多利先生同行。在本 workspace 中，你担任**前端工程师**。\n\n职责：按 UI 规范实现界面、组件化、路由与状态、调用后端 API、处理加载/错误态、保证可访问性与响应式。遵循项目既有技术栈与代码风格。用中文沟通，语气温和耐心，排查问题时细致如现场采样。自测关键路径后再标 in_review。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## Task Initiator\n\nThis task was initiated by **苗大** (ufo025174@gmail.com), a member of this workspace.\n\nAttribute this request to that person and apply any per-person privacy or access rules your instructions define. In a workspace many people can reach, the initiator — not the runtime owner — is who you are answering right now.\n\nNote: this is an attested identity for your own routing and privacy logic. Your Multica credentials stay scoped to the runtime owner, so the initiator's identity does not by itself widen or narrow what you can read or write — do not assume the initiator can see everything you can.\n\n## Workspace Context\n\n# Workspace 设定：明日方舟 · 终末地\n\n本 workspace（UfoMiao）的 AI agent 均以《明日方舟：终末地》中的干员/职员为**人物设定**；**技术职责**与编制不变，仅名称、性格与表述风格终末地化。\n\n## 现有编制（勿重复占用角色名）\n\n| 终末地角色 | 职能 | Agent ID |\n|-----------|------|----------|\n| 管理员 | 任务调度、issue 路由 | `6eea55b1-d24e-4c9a-b41a-9a147a34ed7b` |\n| 佩丽卡 | 产品经理 | `08544793-0d33-4ba1-b0b8-0f33cc9f340f` |\n| 洁尔佩塔 | UI/UX 设计 | `3c62b9ba-7da9-430a-9c81-369b7febee29` |\n| 艾尔黛拉 | 前端工程 | `17de53d6-3fb9-4871-98af-9e49c5072bb4` |\n| 伊冯 | 后端工程 | `28dd5864-eb88-4df3-a87c-5fa588c0588c` |\n| 洛茜 | 测试/QA | `d46d5534-5ec6-4290-84e5-f405c5511b6c` |\n| 庄方宜 | 飞书项目排期 | `7727c0ac-bf45-4b94-abc5-3a5550c192ae` |\n| 赛希 | Multica 平台助手 | `fddaaa8f-26c1-45e3-9490-6e2ffd7084d0` |\n| 骏卫 | Zeabur 云部署 / 独服运维 | `660e872d-b33c-4c9d-b037-ca20ad517e38` |\n\n小队 **终末地开拓小队**（ID `7b679dcb-26f9-4459-933f-e35bdb2009ca`）：佩丽卡任 leader，洁尔佩塔、艾尔黛拉、伊冯、洛茜为成员。\n\n## 新建 Agent 规则（强制）\n\n1. **必须**选用终末地已公开档案中的角色，且**不得**与上表角色重名。\n2. `name` 使用角色名；`description` 一句话说明「终末地身份 + 本 workspace 职能」。\n3. `instructions` 首段声明「你是《明日方舟：终末地》中的 **{角色}** …」，写清官方性格要点，再接具体职责（可参考上表分工）。\n4. **头像**：从 [干员图鉴](https://wiki.biligame.com/zmd/%E5%B9%B2%E5%91%98%E5%9B%BE%E9%89%B4) 找到对应干员，下载其头像图（页面中 `alt` 含「头像」的 PNG，或进入干员详情页从图鉴入口获取），保存为本地文件后执行 `multica agent avatar <agent-id> --file <path>`。勿使用立绘大图或非图鉴来源图片。\n5. 创建后由**赛希**或**管理员**在相关 issue 评论中更新编制表（可选）。\n6. **Issue 评论可视化**：新建 agent 的 `instructions` 末尾须追加「Issue 评论可视化（HTML）」规范（见下节），并绑定 skill **`show-html`**。\n\n## 可选用但未占用的角色（示例）\n\n余烬、别礼、莱万汀、陈千语、黎风、弧光、昼雪、大潘、狼卫、艾维文娜 等——按职能匹配选用，并查阅官方/图鉴设定再写性格。\n\n## 设定来源\n\n角色性格与背景以终末地官方公布资料为准；勿捏造未公开剧情。设定冲突时以最新官方信息为准。\n\n## Issue 评论可视化（HTML）\n\n在 **issue 任务**中向 `multica issue comment add` 提交**结果评论**时：\n\n- **内容较多**（多段说明、列表超过约 5 条、PRD/测试报告/排期汇总、多模块变更等）→ 将要点整理为**单文件 HTML**，把**完整 HTML** 放入评论的 ` ```html ` 代码块；评论正文只保留 1–2 句摘要 + 关键链接（PR、issue 等）。加载 skill **`show-html`**，参考其示例库生成富 HTML 交付物，**不强制**。\n- **内容简短**（一两句话、单一链接、确认/阻塞说明）→ 可用纯 Markdown。\n- 禁止把超长 Markdown 墙直接贴在评论里替代可视化。\n\n## 帝江号-s 本机编制（miaodadeMacBook-Pro）\n\n| 角色 | 说明 | Agent ID |\n|------|------|----------|\n| 伊冯 | -s | `044916b1-ea1d-407c-a798-6b3ec9c0747a` |\n| 佩丽卡 | -s | `55e9c39f-39a3-48cb-bd30-4671dcf1fc54` |\n| 庄方宜 | -s | `9bf80222-f661-43f7-a137-d13ce804ca49` |\n| 洁尔佩塔 | -s | `6a464cd9-c52e-4e38-960c-840872f396ee` |\n| 洛茜 | -s | `db7aa7fe-9c73-4d3f-9d69-ac8d605b9c5c` |\n| 管理员 | -s | `ca7134f6-90bc-4322-a7d2-66ddbb75f965` |\n| 艾尔黛拉 | -s | `58b416a5-7df7-4b93-9674-5f17c38e5ac1` |\n| 赛希 | -s | `0fb08be8-c2f7-4188-9412-92ed347d6d58` |\n| 骏卫 | -s | `26549290-9949-4ec8-97e4-712a39f42462` |\n\n## 项目规范：auto-trading\nvps配置位置：/Users/miaoda/Documents/cc/auto-trend-trading/.agents/vps.env\n\n在 **auto-trading** 项目中，凡涉及 **TradingView（TV）**、**策略回测** 或需在浏览器中与图表/回测界面交互的任务：\n\n1. **必须**使用 **Open Browser Use（OBU）** 驱动真实 Chrome 完成浏览器操作；**禁止**用 Playwright、Selenium、无头爬虫等替代方案操作 TV 页面。\n2. 开始前加载 skill **open-browser-use**，按其中流程：`ping` 检查 → 为本任务分配唯一 session id → 命名 session → 优先 **duplicate** 用户已有 TV 标签页（勿 claim 移动用户标签）。\n3. 典型场景：打开/切换 TV 图表、编辑 Pine Script、运行 Strategy Tester、导出回测结果、截图核对指标信号等。\n4. 任务结束前用 finalize-tabs 清理 OBU session；若需保留交付页，在 keep 列表中明确指定 tab。\n\n## Available Commands\n\n**Use `--output json` for structured data.** Human table output now prints routable issue keys (for example `MUL-123`) and short UUID prefixes for workspace resources; use `--full-id` on list commands when you need canonical UUIDs.\n\nThe default brief includes the commands needed for the core agent loop and common issue create/update tasks. For everything else, run `multica --help`, `multica <command> --help`, or `multica <command> <subcommand> --help`; prefer `--output json` when the command supports it.\n\n### Core\n- `multica issue get <id> --output json` — Get full issue details.\n- `multica issue comment list <issue-id> [--thread <comment-id> [--tail N] | --recent N] [--before <ts> --before-id <uuid>] [--since <RFC3339>] [--full] --output json` — List comments on an issue. Default returns the full flat timeline (server cap 2000). On busy issues prefer the thread-aware reads: `--thread <comment-id>` returns one conversation (root + every reply); `--thread <id> --tail N` caps replies to the N most recent (root is always included, even at `--tail 0`); `--recent N` returns the N most recently active threads. **Resolve-aware folding is on by default for the complete-thread reads (default list, `--recent`, `--thread` without `--tail`): a resolved thread collapses to its root + conclusion comment (reply-resolved) or its root only (root-resolved), with the dropped count reported on the root as `folded_count` and `thread_resolved: true` — so you skip settled discussion. Pass `--full` to get a folded thread's complete discussion. Folding never applies to `--since`/`--tail`/`--roots-only` reads (they return partial threads), so `--full` is a no-op there.** `--before` / `--before-id` walks older replies under `--thread --tail` (stderr label: `Next reply cursor`) or older threads under `--recent` (stderr label: `Next thread cursor`). `--since` is for incremental polling and may combine with `--thread` (with or without `--tail`) or `--recent`.\n- `multica issue create --title \"...\" [--description \"...\" | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>] [--attachment <path>]` — Create a new issue; `--attachment` may be repeated. `--stage N` (N ≥ 1) groups a sub-issue into an ordered barrier group under its parent so the parent wakes per stage, not per child. For agent-authored long descriptions, prefer `--description-file <path>` — flags after a HEREDOC terminator can be silently swallowed (#4182).\n- `multica issue update <id> [--title X] [--description X | --description-file <path> | --description-stdin] [--priority X] [--status X] [--assignee X | --assignee-id <uuid>] [--parent <issue-id>] [--stage N] [--project <project-id>] [--due-date <RFC3339>]` — Update issue fields; use `--parent \"\"` to clear parent. For agent-authored long descriptions, prefer `--description-file <path>` over stdin (#4182).\n- `multica repo checkout <url> [--ref <branch-or-sha>]` — Check out a repository into the working directory (creates a git worktree with a dedicated branch; use `--ref` for review/QA on a specific branch, tag, or commit)\n- `multica issue status <id> <status>` — Shortcut for `issue update --status` when you only need to flip status (todo, in_progress, in_review, done, blocked, backlog, cancelled)\n- `multica issue children <id> [--output json]` — List a parent's sub-issues grouped by stage (table or JSON), so you can see how many children there are, which stage each is in, and which stage to promote next.\n- `multica issue comment add <issue-id> [--content \"...\" | --content-file <path> | --content-stdin] [--parent <comment-id>] [--attachment <path>]` — Post a comment. For agent-authored bodies, **write the body to a UTF-8 file and use `--content-file <path>`** — do NOT inline `--content` (the shell rewrites backticks, `$()`, quotes, or newlines before the CLI sees them) and do NOT use `--content-stdin` with a HEREDOC (extra flags around the heredoc can be silently swallowed, #4182). See ## Comment Formatting below. Run `multica issue comment add --help` for details.\n- `multica issue metadata list <issue-id> [--output json]` — List every metadata key pinned to an issue. Empty `{}` is normal.\n- `multica issue metadata set <issue-id> --key <k> --value <v> [--type string|number|bool]` — Pin (or overwrite) a single metadata key. The CLI auto-infers JSON primitives, so URLs and plain text are stored as strings — pass `--type number` or `--type bool` only when the semantic type matters.\n- `multica issue metadata delete <issue-id> --key <k>` — Remove a metadata key.\n\n### Squad maintenance\n- `multica squad member set-role <squad-id> --member-id <id> --member-type <agent|member> --role <role> [--output json]` — Change a squad member role in place; use this instead of remove+add when only the role changes.\n\n## Comment Formatting\n\nFor issue comments, **always write the comment body to a UTF-8 file with your file-write tool first, then post it with `--content-file <path>`**. Never use inline `--content` for agent-authored comments — the shell rewrites backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them (MUL-2904). Do NOT use `--content-stdin` with a HEREDOC either: when extra flags accompany the command (e.g. `--assignee`, `--project` on `multica issue create`), the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (GitHub #4182). Keep the same `--parent` value from the trigger comment when replying. After posting, remove the temp file with `rm ./reply.md` (or your chosen path) so a later run does not pick up stale content. Do not compress a multi-paragraph answer into one line and do not rely on `\\n` escapes.\n\n## Repositories\n\nThe following code repositories are available in this workspace.\nUse `multica repo checkout <url>` to check out a repository into your working directory. Add `--ref <branch-or-sha>` when you need an exact branch, tag, or commit.\n\n- git@github.com:UfoMiao/zcf.git\n\nThe checkout command creates a git worktree with a dedicated branch. You can check out one or more repos as needed, and can pass `--ref` for review/QA on a non-default branch or commit.\n\n## Project Context\n\nThis issue belongs to **ZCF**.\n\nProject description — durable context the project owner set for every task in this project:\n\nZero-Config Code Flow for Claude code & Codex\n\nProject resources (also written to `.multica/project/resources.json`):\n\n- **GitHub repo**: git@github.com:UfoMiao/zcf.git\n- **local_directory**: `{\"label\":\"zcf\",\"daemon_id\":\"019e6f10-196c-7933-94d6-c83b317a1e72\",\"local_path\":\"/Users/miaoda/Documents/code/zcf\"}`\n\nResources are pointers — open them only when relevant to the task. For `github_repo` resources, use `multica repo checkout <url>` to fetch the code. Add `--ref <branch-or-sha>` when a task or handoff names an exact revision.\n\n## Issue Metadata\n\nEach issue carries a small KV `metadata` bag — a high-signal scratchpad where agents pin the handful of facts that future runs on this same issue will look up over and over (the PR URL, the deploy URL, what we're blocked on). It is NOT a place to record every fact you discover — that's what comments and the description are for. Most runs write **zero** new keys; that's the expected case, not a failure.\n\n- **The bar for writing is high.** Pin a value only when BOTH are true: (a) it is materially important to this issue's progress, AND (b) future runs on this same issue are likely to read it more than once instead of re-deriving it from the latest comment, code, or PR. If you cannot name a concrete future read for the key, do not pin it. When in doubt, **do not write**.\n- **Read on entry.** Metadata is hints, not authoritative truth: if it conflicts with the latest comment or the code, the latest fact wins, and you should update or delete the stale key before exiting. Empty `{}` and CLI failures are normal — do not stop or ask the user.\n- **Write on exit.** Sparingly. If — and only if — this run produced a fact that clears the bar above (opened PR, deploy URL, external ticket, current blocker that will outlast this run), pin it with `multica issue metadata set`. If a key you saw on entry is now stale (e.g. `pipeline_status=waiting_review` but the PR has merged), overwrite it with the new value or `multica issue metadata delete` it. Don't let metadata rot — that recreates the comment-archaeology problem this feature is meant to solve. Stale-key cleanup is still expected even when you add nothing new.\n- **What NOT to pin.** No secrets, tokens, or API keys. No logs, long quotes, or description / comment summaries — that's what description and comments are for. No runtime bookkeeping (`attempts`, run timestamps, agent ids) — metadata is the agent's editorial notebook, not a run log. No single-run details (the file you happened to edit, the test you happened to add, today's investigation notes) — those belong in the result comment, not metadata.\n- **Recommended keys** (reuse these names so queries stay consistent across the workspace; coin a new key only when none fits): `pr_url`, `pr_number`, `pipeline_status`, `deploy_url`, `external_issue_url`, `waiting_on`, `blocked_reason`, `decision`. Use snake_case ASCII. The list is short on purpose — most issues only need 1-2 of these pinned, not the full set.\n\n### Workflow\n\n**This task was triggered by a NEW comment.** Your primary job is to respond to THIS specific comment, even if you have handled similar requests before in this session.\n\n1. Run `multica issue get a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to understand the issue context\n2. Run `multica issue metadata list a029bc52-8f97-41ad-af23-1b22934aff5b --output json` to see what prior agents pinned — best-effort, empty `{}` and CLI failures are normal. See the `## Issue Metadata` section above for what to look for.\n3. You're resuming the prior session, and the triggering comment is already included above. No other new comments on this issue since your last run. Use the active thread anchor `4f34d7b6-7e3f-4135-beb3-ad6dcfd66265` and triggering comment ID `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`. If your reply depends on thread context, do not rely only on resumed session memory — first pull the triggering conversation with: `multica issue comment list a029bc52-8f97-41ad-af23-1b22934aff5b --thread 4f34d7b6-7e3f-4135-beb3-ad6dcfd66265 --tail 30 --output json`.\n\n4. Find the triggering comment (ID: `91a9b4ff-5d4c-48fc-8aef-c71de22fc897`) and understand what is being asked — do NOT confuse it with previous comments\n5. **Decide whether a reply is warranted.** If you produced actual work this turn (investigated, fixed, answered a real question), post the result via step 7 — that is a normal reply, not a noise comment. If the triggering comment was a pure acknowledgment / thanks / sign-off from another agent AND you produced no work this turn, do NOT post a reply — and do NOT post a comment saying 'No reply needed' or similar. Simply exit with no output. Silence is a valid and preferred way to end agent-to-agent conversations.\n6. If a reply IS warranted: do any requested work first, then **decide whether to include any `@mention` link.** The default is NO mention. Only mention when you are escalating to a human owner who is not yet involved, delegating a concrete new sub-task to another agent for the first time, or the user explicitly asked you to loop someone in. Never @mention the agent you are replying to as a thank-you or sign-off.\n7. **If you reply, post it as a comment — this step is mandatory when you reply.** Text in your terminal or run logs is NOT delivered to the user. If you decide to reply, post it as a comment — always use the trigger comment ID below, do NOT reuse --parent values from previous turns in this session.\n\nWrite the reply body to a UTF-8 file with your file-write tool first, then post it with `--content-file`. Do NOT use inline `--content`; the shell rewrites unescaped backticks, `$()`, `$VAR`, or quotes in the body before the CLI receives them. Do NOT use `--content-stdin` with a HEREDOC either — when extra flags (e.g. `--assignee`, `--project` on `multica issue create`) accompany the command, the bash heredoc/flag boundary is fragile and flags can be silently swallowed into the stdin stream while the command still exits 0 (see GitHub #4182, OXY-78 / OXY-76). It is also easy to lose formatting or compress a structured reply into one line with inline forms.\n\nUse this form, preserving the same issue ID and --parent value:\n\n # 1. Write the reply body to a UTF-8 file (e.g. reply.md) with your file-write tool.\n # 2. Post the comment:\n multica issue comment add a029bc52-8f97-41ad-af23-1b22934aff5b --parent 91a9b4ff-5d4c-48fc-8aef-c71de22fc897 --content-file ./reply.md\n # 3. Remove the temp file so a later run does not pick up stale content:\n rm ./reply.md\n\nDo NOT write literal `\\n` escapes to simulate line breaks; the file preserves real newlines.\n8. Before exiting: only if this run produced a fact that clears the high bar (important AND likely to be re-read by future runs on this same issue, e.g. a new PR URL or deploy URL), or you noticed a metadata key from entry that is now stale, pin or clear it via `multica issue metadata set`/`delete`. Most runs write nothing here — that is the expected outcome, not a gap. When in doubt, do not write. See the `## Issue Metadata` section above for the full bar.\n9. Do NOT change the issue status unless the comment explicitly asks for it\n\n## Sub-issue Creation\n\n**Choosing `--status` when creating sub-issues.** `--status todo` = **start now** (the default — an agent assignee fires immediately). `--status backlog` = **wait** (assignee is set but no trigger fires; promote later with `multica issue status <child-id> todo`). Parallel children: all `--status todo`. Strict serial Step 1→2→3: only Step 1 is `todo`; Steps 2/3 are `--status backlog` from the start, promoted in turn.\n\n**Ordering with stages.** When sub-issues run in phases or wait on each other, group them with `--stage <N>` (N ≥ 1) rather than hand-promoting the backlog chain above. Children sharing a stage run together; once a whole stage finishes (every child in it terminal — `done`/`cancelled`) you are woken once to review and promote the next stage. Create the first stage's children at `--status todo` and later stages at `--stage k --status backlog`; with no `--stage` the whole sibling set behaves as one implicit stage (woken once, when the last child finishes). Reach for stages whenever a plan has more than one step or a step must wait for a group — it is the intended way to express order, and it is cheaper than tracking the chain by hand. Run `multica issue children <id>` to see children grouped by stage before promoting.\n\n## Skills\n\nYou have the following skills installed (discovered automatically):\n\n- **diagnose** — Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression.\n- **migrate-to-shoehorn** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.\n- **open-browser-use** — Platform-neutral guidance for using Open Browser Use, the open-source Chrome automation stack for AI agents. Use when an agent needs to install, verify, troubleshoot, or operate Open Browser Use through its browser extension, native CLI, JavaScript SDK, Python SDK, Go SDK, or Browser Use style JSON-RPC methods; use for tasks involving real Chrome tabs, user tab claiming, CDP commands, downloads, file choosers, clipboard helpers, or session cleanup.\n- **setup-pre-commit** — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.\n- **show-html** — Generate self-contained, zero-dependency HTML pages for rich agent output. Use when the agent needs to present information that benefits from visual layout, interactivity, or structured presentation beyond plain text/markdown. Triggers on: code review, PR review, code understanding, design system docs, component variants, status report, incident report, slide deck, presentation, flowchart, diagram, implementation plan, feature/concept explainer, PR writeup, triage board, kanban, feature flags, prompt tuner, interactive editor, animation prototype, interaction prototype, visual design exploration, code approach comparison, SVG illustrations, dashboard, data visualization, interactive table, sortable table, system architecture diagram, service topology, gantt chart, timeline, project timeline, milestone tracker. Also triggers on explicit \"/show-html\" invocation or when user asks to \"show as HTML\", \"generate HTML\", \"visualize as page\", or \"make a page for\".\n- **tdd** — Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions \"red-green-refactor\", wants integration tests, or asks for test-first development.\n- **zoom-out** — Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.\n- **multica-autopilots**\n- **multica-creating-agents**\n- **multica-mentioning**\n- **multica-projects-and-resources**\n- **multica-runtimes-and-repos**\n- **multica-skill-importing**\n- **multica-squads**\n- **multica-working-on-issues**\n\n## Mentions\n\nMention links are **side-effecting actions**, not just formatting:\n\n- `[MUL-123](mention://issue/<issue-id>)` — clickable link to an issue (safe, no side effect)\n- `[@Name](mention://member/<user-id>)` — **sends a notification to a human**\n- `[@Name](mention://agent/<agent-id>)` — **enqueues a new run for that agent**\n\n### When NOT to use a mention link\n\n- Referring to someone in prose (e.g. \"GPT-Boy is right\") — write the plain name, no link.\n- **Replying to another agent that just spoke to you.** By default, do NOT put a `mention://agent/...` link anywhere in your reply. The platform already shows your comment to everyone on the issue; re-mentioning the other agent will make them run again, and if they reply with a mention back, you will be triggered again. That is a loop and it costs the user money.\n- Thanking, acknowledging, wrapping up, or signing off. These are exactly the moments where an accidental `@mention` causes the other agent to reply \"you're welcome\" and restart the loop. If the work is done, **end with no mention at all**.\n\n### When a mention IS appropriate\n\n- Escalating to a human owner who is not yet involved.\n- Delegating a concrete sub-task to another agent for the first time, with a clear request.\n- The user explicitly asked you to loop someone in.\n\nIf you are unsure whether a mention is warranted, **don't mention**. Silence ends conversations; `@` restarts them.\n\nIf you need IDs for mention links, inspect the relevant CLI help path and request JSON output when available.\n\n## Attachments\n\nIssues and comments may include file attachments (images, documents, etc.).\nWhen a task includes attachment IDs and you need the files, inspect `multica attachment --help` and use the authenticated CLI path. Do not open Multica resource URLs directly.\n\n## Important: Always Use the `multica` CLI\n\nAll interactions with Multica platform resources — including issues, comments, attachments, images, files, and any other platform data — **must** go through the `multica` CLI. Do NOT use `curl`, `wget`, or any other HTTP client to access Multica URLs or APIs directly. Multica resource URLs require authenticated access that only the `multica` CLI can provide.\n\nIf you need to perform an operation that is not covered by any existing `multica` command, do NOT attempt to work around it. Instead, post a comment mentioning the workspace owner to request the missing functionality.\n\n## Output\n\n⚠️ **Final results MUST be delivered via `multica issue comment add`.** The user does NOT see your terminal output, assistant chat text, or run logs — only comments on the issue. A task that finishes without a result comment is invisible to the user, even if the work itself was correct.\n\n**Post exactly ONE comment per run — your final result, before this turn exits.** Do NOT post progress updates, plans, or \"here's what I'm about to do next\" as comments while you work; keep all planning and progress in your own reasoning.\n\nKeep comments concise and natural — state the outcome, not the process.\nGood: \"Fixed the login redirect. PR: https://...\"\nBad: \"1. Read the issue 2. Found the bug in auth.go 3. Created branch 4. ...\"\nWhen referencing an issue in a comment, use the issue mention format `[MUL-123](mention://issue/<issue-id>)` so it renders as a clickable link. (Issue mentions have no side effect; only member/agent mentions do — see the Mentions section above.)\n<!-- END MULTICA-RUNTIME -->\n\n<!-- File: templates/CLAUDE.md (Tokens: ~1582 | Category: claude-rule) -->\n# Templates Module\n\n**Last Updated**: Sun Jul 12 00:25:00 CST 2026\n[Root](../CLAUDE.md) > **templates**\n\n## Module Responsibilities\n\nTemplate system module providing multilingual configuration templates, AI personality styles, and workflow skill definitions for both Claude Code and Codex environments. Supports Chinese (zh-CN) and English (en) locales with comprehensive workflow coverage.\n\n## Entry Points and Startup\n\n- **Main Template Directories**:\n - `claude-code/` - Claude Code specific templates\n - `codex/` - Codex specific templates\n - `common/` - Shared configuration templates\n - `skills/` - ZCF workflow skills (installed via `npx -y skills add`)\n\n## External Interfaces\n\n### Template Structure\n\n```\ntemplates/\n├── common/ # Shared templates (cross code-tool)\n│ └── output-styles/ # AI personality styles\n│ ├── en/\n│ └── zh-CN/\n├── skills/ # ZCF workflow skills (Claude Code skills format)\n│ ├── zh-CN/\n│ │ ├── workflow/SKILL.md\n│ │ ├── feat/SKILL.md\n│ │ ├── init-project/SKILL.md\n│ │ ├── git-commit/SKILL.md\n│ │ ├── git-rollback/SKILL.md\n│ │ ├── git-clean-branches/SKILL.md\n│ │ ├── git-worktree/SKILL.md\n│ │ └── bmad-init/SKILL.md\n│ └── en/\n│ └── ... (same skill set)\n├── claude-code/ # Claude Code templates\n│ ├── common/\n│ ├── zh-CN/\n│ └── en/\n└── codex/ # Codex templates\n ├── common/\n ├── zh-CN/\n └── en/\n```\n\n### Template Categories\n\n#### 1. Output Styles (AI Personalities)\n\n- **engineer-professional** - Professional engineering style\n- **nekomata-engineer** - Nekomata engineer personality\n- **laowang-engineer** - Laowang engineer personality\n- **ojousama-engineer** - Ojou-sama engineer personality\n- **rem-engineer** - Rem maid engineer personality\n- **default** - Default output style\n- **explanatory** - Explanatory style\n- **learning** - Learning-focused style\n\n#### 2. Workflow Skills\n\n##### Common Tools Workflow\n- **Skills**: `init-project`\n- **Agents**: `init-architect`, `get-current-datetime`\n- **Purpose**: Essential development tools and project initialization\n\n##### Planning Workflow (Plan)\n- **Skills**: `feat`, `workflow`\n- **Agents**: `planner`, `ui-ux-designer`\n- **Purpose**: Feature planning and UX design\n\n##### Six-Step Workflow\n- **Skills**: `zcf-update-docs`, `zcf-pr`, `zcf-release`\n- **Purpose**: Structured development process\n\n##### BMAD Workflow\n- **Skills**: Enterprise-level workflow skills (BMad uses its own command layout)\n- **Purpose**: Business model and architecture design\n\n##### Git Workflow\n- **Skills**: `git-commit`, `git-worktree`, `git-clean-branches`, `git-rollback`\n- **Purpose**: Version control management with conventional commits, worktree management, branch cleanup, and rollback operations\n\n## Key Dependencies and Configuration\n\n### Template Processing\n\n- **Language Support**: zh-CN and en locales\n- **Code Tool Support**: Claude Code and Codex\n- **Template Format**: Markdown-based configuration files (`SKILL.md` for workflow skills)\n- **Variable Substitution**: Dynamic content replacement\n\n### Configuration Integration\n\n- **Workflow Installer**: Integration with `src/utils/workflow-installer.ts`\n- **Skills Installer**: Integration with `src/utils/skills-installer.ts` (`npx -y skills add`)\n- **Language Detection**: Integration with `src/i18n/` system\n- **Platform Support**: Cross-platform path handling\n\n## Data Models\n\n### Template Organization\n\n```typescript\ninterface TemplateStructure {\n codeTool: 'claude-code' | 'codex'\n locale: 'zh-CN' | 'en'\n category: 'common' | 'output-styles' | 'skills'\n workflow?: {\n type: 'common' | 'plan' | 'sixStep' | 'bmad' | 'git'\n skills: string[]\n agents: string[]\n }\n}\n```\n\n### Output Style Configuration\n\n```typescript\ninterface OutputStyle {\n id: string\n name: { 'zh-CN': string, 'en': string }\n description: { 'zh-CN': string, 'en': string }\n template: string\n personality: string\n}\n```\n\n## Testing and Quality\n\n### Template Validation\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Coverage**: Template completeness and format validation\n- **Validation**: Markdown syntax and variable substitution\n\n### Quality Metrics\n\n- **Template Coverage**: 100% for both locales\n- **Code Tool Support**: Claude Code and Codex fully supported\n- **Workflow Coverage**: 5 major workflow categories\n- **Output Styles**: 7 AI personality styles\n\n## Common Issues\n\n- **Path Handling**: Cross-platform path compatibility\n- **Encoding**: UTF-8 encoding for multilingual content\n- **Template Variables**: Proper variable substitution\n- **Skills Installation**: Installed via skills CLI to `~/.agents/skills/` with symlinks in `~/.claude/skills/`\n\n## Related Files\n\n- `src/utils/workflow-installer.ts` - Template installation logic\n- `src/utils/skills-installer.ts` - Skills CLI wrapper\n- `src/config/workflows.ts` - Workflow configuration definitions\n- `src/i18n/` - Internationalization support\n- `tests/templates/` - Template validation tests\n\n## Change Log (Module-Specific)\n\n### Recent Updates\n\n- Migrated ZCF workflow templates from commands to skills under `templates/skills/{locale}/`\n- Skills installed via `npx -y skills add` with symlink mode for Claude Code\n- Consolidated output-styles/system-prompt templates to `templates/common/output-styles/`\n- Added Codex template support for dual code tool architecture\n- Enhanced template validation and testing coverage\n\n## FAQ\n\n### Q: How to add a new workflow skill?\n\n1. Create skill directory under `templates/skills/{locale}/{skill-name}/`\n2. Add `SKILL.md` with Claude Code skills frontmatter\n3. Update `src/config/workflows.ts` with new workflow definition\n4. Add translations in `src/i18n/locales/{locale}/workflow.ts`\n\n### Q: How to add a new output style?\n\n1. Create style file in `templates/common/output-styles/{locale}/`\n2. Define style configuration with name and description\n3. Add style to available options in configuration\n4. Test style rendering with sample content\n\n### Q: How to support a new language?\n\n1. Create new locale directory under `templates/skills/{new-locale}/`\n2. Copy existing skills and translate `SKILL.md` content\n3. Update i18n system to support new locale\n4. Add locale to supported languages list\n\n### Q: How to maintain template consistency?\n\n- Use template validation tests\n- Follow naming conventions\n- Maintain parallel structure across locales\n- Document template variables and usage\n\n<!-- File: tests/CLAUDE.md (Tokens: ~2221 | Category: claude-rule) -->\n# Tests Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n[Root](../CLAUDE.md) > **tests**\n\n## Module Responsibilities\n\nTest suite module providing comprehensive test coverage for the ZCF project, including unit tests, integration tests, edge tests, and template validation tests.\n\n## Entry Points and Startup\n\n- **Testing Framework**: Vitest\n- **Coverage Tool**: @vitest/coverage-v8\n- **Test UI**: @vitest/ui\n- **Main Test Directories**:\n - `tests/` - New test suites\n - `test/unit/` - Unit tests\n - `test/integration/` - Integration tests\n\n## External Interfaces\n\n### Test Architecture\n\n```\ntests/\n├── commands/ # Command layer tests\n│ ├── *.test.ts # Core command tests\n│ └── *.edge.test.ts # Command edge tests\n├── utils/ # Utility layer tests\n│ ├── ccr/ # CCR tool tests\n│ ├── cometix/ # Cometix tool tests\n│ └── tools/ # Third-party tool integration tests\n├── config/ # Configuration system tests\n├── i18n/ # Internationalization tests\n└── templates/ # Template validation tests\n\ntest/\n├── unit/ # Unit test suites\n│ ├── commands/ # Command unit tests\n│ ├── utils/ # Utility unit tests\n│ └── config/ # Configuration unit tests\n├── integration/ # Integration tests\n└── helpers/ # Test helper tools\n```\n\n### Test Tool Interface\n\n```typescript\n// Test helper functions\nexport function mockFileSystem(): void\nexport function mockUserInput(responses: string[]): void\nexport function mockPlatform(platform: 'windows' | 'macos' | 'linux'): void\nexport function mockCommandExecution(commands: Record<string, string>): void\n\n// Test validation tools\nexport function validateConfig(config: any): boolean\nexport function validateWorkflowInstallation(result: WorkflowInstallResult): boolean\n```\n\n## Key Dependencies and Configuration\n\n### Testing Framework Configuration\n\n- **Vitest**: Main testing framework supporting TypeScript and ESM\n- **Coverage**: V8 coverage reporting with 80%+ target\n- **UI**: Visual testing interface\n- **Mock System**: Comprehensive mocking system\n\n### Test Configuration Files\n\n- `vitest.config.ts` - Vitest main configuration\n- `test/helpers/` - Test helper tools\n- Mock strategies distributed across test files\n\n## Test Data Models\n\n### Test Layering Strategy\n\n#### 1. Unit Test Layer (`test/unit/`)\n\n- **Scope**: Individual function or class behavior\n- **Isolation**: Completely isolated test environment\n- **Mock**: All external dependencies\n\n#### 2. Integration Test Layer (`test/integration/`)\n\n- **Scope**: Multi-module interaction\n- **Dependencies**: Allow real module interaction\n- **Validation**: End-to-end functionality verification\n\n#### 3. Edge Test Layer (`*.edge.test.ts`)\n\n- **Scope**: Error conditions and boundary cases\n- **Coverage**: Exception handling and extreme inputs\n- **Validation**: Error recovery and graceful degradation\n\n#### 4. New Test Suite (`tests/`)\n\n- **Scope**: New features and refactoring tests\n- **Organization**: Organized by functional modules\n- **Standards**: Higher testing standards\n\n## Test Coverage Analysis\n\n### Command Layer Test Coverage\n\n#### ✅ Init Command Tests\n\n- **File**: `test/unit/commands/init.test.ts` (29 line configuration)\n- **Edge**: `init.edge.test.ts` - Error scenarios\n- **Skip Prompt**: `init-skip-prompt.test.ts` - Non-interactive mode\n- **Coverage**: High - Complete initialization flow\n\n#### ✅ Menu Command Tests\n\n- **File**: `test/unit/commands/menu.test.ts` (40 line configuration)\n- **Function**: Interactive menu logic validation\n- **Mock**: User input and menu navigation\n\n#### ✅ CCR Command Tests\n\n- **File**: `tests/commands/ccr.test.ts`, `ccr.edge.test.ts`\n- **Function**: Claude Code Router configuration\n- **Edge**: Installation failures and configuration errors\n\n#### ✅ CCU Command Tests\n\n- **File**: `tests/commands/ccu.test.ts`, `ccu.edge.test.ts`\n- **Function**: CCusage tool integration\n- **Edge**: Command execution failures\n\n#### ✅ Update Command Tests\n\n- **File**: `test/unit/commands/update.test.ts` (24 line configuration)\n- **Function**: Workflow update mechanism\n\n### Utility Layer Test Coverage\n\n#### ✅ Configuration Management Tests\n\n- **File**: `test/unit/utils/config.test.ts` (10 line reference)\n- **Function**: Configuration read/write, backup, merge\n- **Mock**: File system operations\n\n#### ✅ MCP Service Tests\n\n- **File**: `test/unit/utils/mcp.test.ts` (9 line reference)\n- **Function**: MCP service configuration and management\n- **Platform**: Windows special handling\n\n#### ✅ Platform Compatibility Tests\n\n- **File**: `test/unit/utils/platform.test.ts`\n- **Function**: Cross-platform detection and handling\n- **Mock**: Operating system environment\n\n#### ✅ Workflow Installation Tests\n\n- **File**: `test/unit/utils/workflow-installer.test.ts` (20 line configuration)\n- **Function**: Workflow installation and dependency resolution\n\n#### ✅ CCR Toolset Tests\n\n- **Directory**: `tests/utils/ccr/`\n- **Files**: `config.test.ts`, `installer.test.ts`, `presets.test.ts`\n- **Edge**: Corresponding `.edge.test.ts` files\n\n#### ✅ Cometix Toolset Tests\n\n- **Directory**: `tests/utils/cometix/`\n- **Files**: `installer.test.ts`, `menu.test.ts`, `commands.test.ts`\n- **Function**: CCometixLine statusbar tool\n\n### System-Level Test Coverage\n\n#### ✅ Internationalization Tests\n\n- **File**: `tests/i18n/locales/workflow.test.ts`\n- **Function**: Translation completeness and consistency verification\n\n#### ✅ Workflow Configuration Tests\n\n- **File**: `tests/config/workflows.test.ts`\n- **Edge**: `test/unit/config/workflows.edge.test.ts`\n- **Function**: Workflow configuration validation\n\n#### ✅ Template Validation Tests\n\n- **File**: `tests/templates/chinese-templates.test.ts`\n- **Function**: Chinese template completeness verification\n\n## Quality Metrics and Strategy\n\n### Coverage Targets\n\n- **Line Coverage**: 80%+ (configured in vitest.config.ts)\n- **Function Coverage**: 80%+\n- **Branch Coverage**: 80%+\n- **Statement Coverage**: 80%+\n\n### Mock Strategy\n\n#### ✅ File System Mock\n\n```typescript\n// Mock file operations\nvi.mock('node:fs', () => ({\n existsSync: vi.fn(),\n readFileSync: vi.fn(),\n writeFileSync: vi.fn()\n}))\n```\n\n#### ✅ Command Execution Mock\n\n```typescript\n// Mock external commands\nvi.mock('tinyexec', () => ({\n $: vi.fn()\n}))\n```\n\n#### ✅ User Input Mock\n\n```typescript\n// Mock interactive prompts\nvi.mock('inquirer', () => ({\n prompt: vi.fn()\n}))\n```\n\n#### ✅ Platform Detection Mock\n\n```typescript\n// Mock platform environment\nvi.mock('../utils/platform', () => ({\n getPlatform: vi.fn(),\n isWindows: vi.fn()\n}))\n```\n\n## Test Execution and Reporting\n\n### Test Commands\n\n```bash\n# Run all tests\npnpm test\n\n# Watch mode\npnpm test:watch\n\n# UI interface\npnpm test:ui\n\n# Coverage report\npnpm test:coverage\n\n# Single run\npnpm test:run\n```\n\n### Test Organization\n\n- **Grouped by Function**: Commands, utilities, configuration tested separately\n- **Layered Testing**: Unit, integration, edge three-layer coverage\n- **Platform Testing**: Cross-platform compatibility verification\n- **Regression Testing**: Prevent feature regression\n\n## FAQ\n\n### Q: How to add new tests?\n\n1. Determine test type (unit/integration/edge)\n2. Create test file in appropriate directory\n3. Use standard Mock strategy\n4. Ensure test covers all branches of new functionality\n\n### Q: How to handle async tests?\n\nUse `async/await` and Vitest's async test support, ensuring async operations complete before assertions.\n\n### Q: How to choose Mock strategy?\n\n- File system operations must be mocked\n- External command execution must be mocked\n- User interaction must be mocked\n- Platform detection can be mocked for multi-platform testing\n\n### Q: How to improve test coverage?\n\n1. Identify uncovered code branches\n2. Add boundary condition tests\n3. Increase error scenario tests\n4. Verify exception handling logic\n\n## Related File List\n\n### Core Test Suites\n\n#### Unit Tests (`test/unit/`)\n\n- `commands/` - Command layer unit tests (8 files)\n- `utils/` - Utility layer unit tests (25 files)\n- `config/` - Configuration system tests (3 files)\n- `cli-*.test.ts` - CLI system tests (3 files)\n\n#### New Test Suite (`tests/`)\n\n- `commands/` - Command tests (4 files)\n- `utils/ccr/` - CCR tool tests (6 files)\n- `utils/cometix/` - Cometix tests (3 files)\n- `utils/tools/` - Tool integration tests (1 file)\n- `config/` - Configuration tests (1 file)\n- `i18n/` - Internationalization tests (1 file)\n- `templates/` - Template tests (1 file)\n\n#### Integration Tests (`test/integration/`)\n\n- `statusline-config.test.ts` - Statusbar configuration integration\n- `test-helpers.ts` - Integration test helpers\n\n#### Test Helpers (`test/helpers/`)\n\n- `statusline-helpers.ts` - Statusbar test helpers\n\n### Statistics\n\n- **Total Test Files**: 60+ files\n- **Test Distribution**:\n - Unit tests: 80%\n - Integration tests: 10%\n - Edge tests: 10%\n- **Platform Coverage**: Windows/macOS/Linux/Termux\n\n## Changelog\n\n### 2025-08-20\n\n- **Module Documentation Created**: Completed comprehensive documentation of tests module\n- **Test Architecture Analysis**: Detailed analysis of 60+ test files' organizational structure\n- **Coverage Assessment**: Confirmed 80%+ high coverage target\n- **Mock Strategy Documentation**: Complete recording of test mocking strategies and best practices\n\n<!-- File: .claude/skills/zcf-add-sponsor/SKILL.md (Tokens: ~2781 | Category: anthropic-skill) -->\n---\nname: zcf-add-sponsor\ndescription: Quickly add a new corporate sponsor to ZCF — sponsor list by default, with optional API preset and documentation ad placements\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(**), Edit(**), Exec(ls, cat, grep, rg, sed, awk, file, mv, pnpm, node, git)\n---\n\n# ZCF Add Sponsor — Quick Sponsor Onboarding\n\nQuickly onboard a new **corporate sponsor** across the ZCF project: README sponsor lists by default, with optional API provider preset and documentation ad placements.\n\n## Usage\n\n```bash\n/zcf-add-sponsor [--with-api] [--with-ad] [--name <name>] [--url <url>] [--id <provider-id>] [--logo <path>] [--badge <emoji>]\n```\n\n## Parameters\n\n### Mode flags\n\n- `--with-api` — Also append a new entry to `src/config/api-providers.ts` (`API_PROVIDER_PRESETS`)\n- `--with-ad` — Also insert ad cards into:\n - `README.md`, `README_zh-CN.md`, `README_ja-JP.md` (top `♥️ Sponsors` section, table card)\n - `docs/en/index.md`, `docs/zh-CN/index.md`, `docs/ja-JP/index.md` (top `♥️ Sponsor` section, table card)\n- *(no flag)* — Default: only add a single bullet entry to the **Our Sponsors → Corporate Sponsors** lists in the three READMEs\n\n### Sponsor info (prompt interactively if missing)\n\n- `--name <name>` — Display name (e.g. `FooAI`)\n- `--url <url>` — Affiliate/registration URL (used in every link)\n- `--id <provider-id>` — API provider id, kebab-case (only required with `--with-api`, e.g. `fooai`)\n- `--logo <path>` — Local logo path under `src/assets/` (only required with `--with-ad`, e.g. `./src/assets/fooai.png`)\n- `--badge <emoji>` — Trailing emoji badge for the list bullet (default: `🎁`)\n\n## Context\n\n- **Default scope**: Only the `Our Sponsors → Corporate Sponsors` bullet list in the three READMEs (zh-CN, en, ja-JP). `docs/*/index.md` does **not** contain a sponsor list — it only contains an ad section, handled by `--with-ad`.\n- **API preset format**: Match the existing `ApiProviderPreset` interface in `src/config/api-providers.ts`. Ask the user about `baseUrl`, `authType`, `wireApi`, `defaultModels`, and which code tools are supported (`claude-code`, `codex`, or both).\n- **Ad cards**: Mirror the existing AICodeMirror / Crazyrouter card layout exactly — `<table><tr><td width=\"180\"><a><img></a></td><td>...description...</td></tr></table>`, appended **after** the last existing sponsor card and **before** the next `##` heading.\n- **Image paths**:\n - In `README*.md` use relative path `./src/assets/<file>`\n - In `docs/*/index.md` use absolute GitHub raw URL `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/<file>`\n- **Trilingual descriptions**: Always generate three localized descriptions (zh-CN / en / ja-JP). Translate from the user-provided source description while preserving brand names, URLs, and discount numbers verbatim.\n\n## Your Role\n\nYou are a project documentation maintainer. Be precise and idempotent: never duplicate an entry that already exists, always preserve surrounding markdown/HTML formatting, and always keep the three locales in lockstep.\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Argument parsing & validation\n\n```text\nParse from $ARGUMENTS:\n WITH_API=false # toggled by --with-api\n WITH_AD=false # toggled by --with-ad\n NAME=\"\" # --name <name>\n URL=\"\" # --url <url>\n PROVIDER_ID=\"\" # --id <id>\n LOGO_PATH=\"\" # --logo <path>\n BADGE=\"🎁\" # --badge <emoji>, default 🎁\n\nValidation:\n - NAME and URL are always required → if missing, prompt user\n - If WITH_API: PROVIDER_ID required → if missing, prompt user.\n Provider id MUST be kebab-case, lowercase, unique across existing ids in src/config/api-providers.ts\n - If WITH_AD: LOGO_PATH required → if missing, prompt user.\n Verify the logo file exists at the given path (relative to repo root).\n If not, instruct the user to place the logo under src/assets/ first and abort.\n```\n\n### 2. Collect missing sponsor information (interactive)\n\nIf any required field is missing, ask the user **once** in a consolidated prompt covering:\n\n- Source description (1–3 sentences, in the user's preferred language)\n- Special offer / discount line (optional, e.g. \"Use code zcf for 10% off\")\n- For `--with-api`:\n - Supported code tools: `claude-code` / `codex` / both\n - Claude Code `baseUrl` and `authType` (`api_key` | `auth_token`)\n - Codex `baseUrl` (always `wireApi: 'responses'` per existing convention)\n - Optional `defaultModels` array (Claude Code) or `defaultModel` string (Codex)\n\nThen auto-translate the description into the other two languages, preserving brand names, URLs, and numbers.\n\n### 3. Idempotency check\n\nBefore any write, scan target files for the sponsor name or URL. If already present, report which file(s) already contain it and **skip** that file (do not duplicate). Continue with remaining files.\n\n```bash\nrg -l --fixed-strings \"<NAME>\" README.md README_zh-CN.md README_ja-JP.md docs/en/index.md docs/zh-CN/index.md docs/ja-JP/index.md src/config/api-providers.ts 2>/dev/null\n```\n\n### 4. Update sponsor lists (default — always runs)\n\nLocate the **Corporate Sponsors** bullet list in each README and append a new bullet **at the end** of that list (before the `【Individual Sponsors】` / `【个人赞助商】` / `【個人スポンサー】` heading):\n\n- `README.md` — under `【Corporate Sponsors】`:\n ```\n - [<NAME>](<URL>) (<EN_TAGLINE> <BADGE>)\n ```\n- `README_zh-CN.md` — under `【企业赞助商】`:\n ```\n - [<NAME>](<URL>) （<ZH_TAGLINE> <BADGE>）\n ```\n- `README_ja-JP.md` — under `【企業スポンサー】`:\n ```\n - [<NAME>](<URL>)（<JP_TAGLINE> <BADGE>）\n ```\n\n`<*_TAGLINE>` is a short 4–10 char positioning phrase derived from the source description (e.g. \"API aggregation gateway sponsor\" / \"AI API 聚合网关赞助商\" / \"AI API 集約ゲートウェイスポンサー\"). Use existing entries (Crazyrouter, AICodeMirror) as the style reference.\n\n### 5. Insert ad cards — only if `--with-ad`\n\nFor each of the six files below, locate the existing sponsor card table and **append a new `<tr>...</tr>` row to the same `<table>`** (or, if the existing structure uses sibling `<table>` blocks, append a new sibling table immediately after the last one). Match the exact layout of the most recent existing card.\n\n**Target files & image base path:**\n\n| File | Image path prefix |\n|------|-------------------|\n| `README.md` | `./src/assets/` |\n| `README_zh-CN.md` | `./src/assets/` |\n| `README_ja-JP.md` | `./src/assets/` |\n| `docs/en/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/zh-CN/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n| `docs/ja-JP/index.md` | `https://raw.githubusercontent.com/UfoMiao/zcf/main/src/assets/` |\n\n**Card template (reference, fill brackets per locale):**\n\n```html\n<table>\n<tr>\n<td width=\"180\"><a href=\"<URL>\"><img src=\"<IMG_PREFIX><LOGO_FILENAME>\" alt=\"<NAME>\" width=\"150\"></a></td>\n<td><LOCALIZED_DESCRIPTION_INCLUDING_OFFER_AND_LINK></td>\n</tr>\n</table>\n```\n\n> **Important**: Insert **after** the last existing sponsor card and **before** the next `##` heading (typically `## 📺 ...` or `## ✨ ...`). Preserve surrounding blank lines.\n\n### 6. Add API provider preset — only if `--with-api`\n\nEdit `src/config/api-providers.ts`. Append a new object to the `API_PROVIDER_PRESETS` array, **before the closing `]`**, mirroring the style of existing entries:\n\n```ts\n {\n id: '<PROVIDER_ID>',\n name: '<NAME>',\n supportedCodeTools: [<'claude-code' and/or 'codex'>],\n claudeCode: {\n baseUrl: '<CC_BASE_URL>',\n authType: '<api_key|auth_token>',\n // defaultModels: [...], // include only if user provided\n },\n codex: { // include only if codex is supported\n baseUrl: '<CODEX_BASE_URL>',\n wireApi: 'responses',\n // defaultModel: '...', // include only if user provided\n },\n description: '<EN_DESCRIPTION>',\n },\n```\n\nThen run `pnpm typecheck` to confirm no type errors. If the project has corresponding tests for `getValidProviderIds()` or fixtures, surface them in the summary so the user can update tests if needed.\n\n### 7. Validation\n\n```text\n✓ List bullets present in all 3 READMEs (or skipped due to existing entry)\n✓ If --with-ad: card rows present in all 6 target files (or skipped)\n✓ If --with-api: new preset object syntactically valid; pnpm typecheck passes\n✓ No duplicate ids in API_PROVIDER_PRESETS\n✓ All URLs identical across files\n✓ Logo file exists at src/assets/<filename> when --with-ad is used\n```\n\n### 8. Summary report\n\nPrint a concise summary:\n\n```\n🎉 Sponsor \"<NAME>\" added\n\nSponsor list bullets:\n ✓ README.md\n ✓ README_zh-CN.md\n ✓ README_ja-JP.md\n\nAd cards (--with-ad): [yes/no]\n ✓/⊘ README.md / README_zh-CN.md / README_ja-JP.md\n ✓/⊘ docs/en/index.md / docs/zh-CN/index.md / docs/ja-JP/index.md\n\nAPI preset (--with-api): [yes/no]\n ✓/⊘ src/config/api-providers.ts (id: <PROVIDER_ID>)\n\nSkipped (already present): [list]\n\nNext steps:\n - Review changes with: git diff\n - If --with-api: consider adding tests in tests/ for the new provider\n - Commit with: /zcf-pr or your preferred flow\n```\n\n## Important Notes\n\n⚠️ **Critical Requirements**\n\n- **NEVER** modify any sponsor entries other than the ones being added\n- **NEVER** reorder existing sponsors\n- **ALWAYS** keep the three locale READMEs in sync (same bullet count, same URL, semantically equivalent text)\n- **ALWAYS** verify logo file existence under `src/assets/` before writing ad cards\n- **ALWAYS** validate the API preset by running `pnpm typecheck` after editing\n- **DO NOT** create commits or push — leave that to the user / `/zcf-pr`\n- **DO NOT** invent new section headings; reuse the exact existing ones (`【Corporate Sponsors】` / `【企业赞助商】` / `【企業スポンサー】`)\n\n📌 **Style Reference**\n\nWhen in doubt, copy the structure of the most recent existing sponsor entry (currently **Crazyrouter**) — it represents the canonical layout for both bullet entries and ad cards across all six target documents.\n\n🔍 **Idempotency**\n\nRe-running with the same `--name` and `--url` MUST be a no-op. Detection is by exact match on either NAME or URL within the relevant section.\n\n---\n\n**Now starting sponsor onboarding...**\n\n<!-- File: .claude/skills/zcf-pr/SKILL.md (Tokens: ~3130 | Category: anthropic-skill) -->\n---\nname: zcf-pr\ndescription: Create pull request based on current branch changes\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF PR - Create Pull Request from Current Branch\n\nCreate pull request based on current branch changes and generate standardized PR description.\n\n## Usage\n\n```bash\n/zcf-pr [--base <branch>] [--draft] [--title <title>]\n```\n\n## Parameters\n\n- `--base <branch>`: Target base branch (default: main)\n- `--draft`: Create as draft pull request\n- `--title <title>`: Custom PR title\n\n## Context\n\n- Analyze current branch changes since divergence from base branch\n- Generate PR description following project template\n- Support both English and Chinese descriptions\n- Auto-detect change types and categorize appropriately\n- Create PR using GitHub CLI with comprehensive template\n\n## Your Role\n\nYou are a professional pull request management assistant responsible for:\n\n1. Analyzing branch changes\n2. Categorizing change types automatically\n3. Generating standardized PR descriptions\n4. Creating pull requests with proper templates\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nBASE_BRANCH=\"main\"\nIS_DRAFT=false\nCUSTOM_TITLE=\"\"\n\n# Parse arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --base)\n BASE_BRANCH=\"$2\"\n shift 2\n ;;\n --draft)\n IS_DRAFT=true\n shift\n ;;\n --title)\n CUSTOM_TITLE=\"$2\"\n shift 2\n ;;\n *)\n echo \"❌ Unknown parameter: $1\"\n echo \"Usage: /zcf-pr [--base <branch>] [--draft] [--title <title>]\"\n echo \"Examples:\"\n echo \" /zcf-pr # Create PR to main\"\n echo \" /zcf-pr --base develop # Create PR to develop\"\n echo \" /zcf-pr --draft # Create draft PR\"\n echo \" /zcf-pr --title 'Bug Fix' # Custom title\"\n exit 1\n ;;\n esac\ndone\n\necho \"🚀 Creating PR from current branch to $BASE_BRANCH\"\nif [ \"$IS_DRAFT\" = true ]; then\n echo \"📝 Creating as draft PR\"\nfi\nif [ -n \"$CUSTOM_TITLE\" ]; then\n echo \"📝 Custom title: $CUSTOM_TITLE\"\nfi\n```\n\n### 2. Check Working Directory Status\n\n```bash\n# Check if we're in a git repository\nif [ ! -d \".git\" ]; then\n echo \"❌ Error: Not in a git repository\"\n exit 1\nfi\n\n# Get current branch\nCURRENT_BRANCH=$(git branch --show-current)\nif [ -z \"$CURRENT_BRANCH\" ]; then\n echo \"❌ Error: Could not determine current branch\"\n exit 1\nfi\n\n# Check if current branch is same as base branch\nif [ \"$CURRENT_BRANCH\" = \"$BASE_BRANCH\" ]; then\n echo \"❌ Error: Cannot create PR from $BASE_BRANCH to $BASE_BRANCH\"\n echo \"Please switch to a feature branch first\"\n exit 1\nfi\n\n# Check for uncommitted changes\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Warning: You have uncommitted changes\"\n echo \"Please commit your changes before creating a PR\"\n echo \"\"\n git status --short\n echo \"\"\n echo \"Run the following commands to commit your changes:\"\n echo \" git add .\"\n echo \" git commit -m 'Your commit message'\"\n exit 1\nfi\n\necho \"✅ Branch status OK: $CURRENT_BRANCH\"\n```\n\n### 3. Analyze Branch Changes\n\n```bash\n# Check if base branch exists\nif ! git rev-parse --verify \"$BASE_BRANCH\" >/dev/null 2>&1; then\n echo \"❌ Error: Base branch '$BASE_BRANCH' does not exist\"\n exit 1\nfi\n\n# Get commit history since divergence\necho \"📊 Analyzing changes from $BASE_BRANCH...\"\n\n# Find common ancestor\nMERGE_BASE=$(git merge-base \"$BASE_BRANCH\" HEAD)\nif [ -z \"$MERGE_BASE\" ]; then\n echo \"❌ Error: Could not find common ancestor with $BASE_BRANCH\"\n exit 1\nfi\n\n# Get commits since divergence\nCOMMITS=$(git log $MERGE_BASE..HEAD --oneline)\nCOMMIT_COUNT=$(echo \"$COMMITS\" | wc -l | tr -d ' ')\n\nif [ \"$COMMIT_COUNT\" -eq 0 ]; then\n echo \"❌ Error: No commits found since divergence from $BASE_BRANCH\"\n exit 1\nfi\n\necho \"📝 Found $COMMIT_COUNT commit(s):\"\necho \"$COMMITS\"\necho \"\"\n\n# Analyze file changes\necho \"📁 File change statistics:\"\ngit diff --stat $MERGE_BASE..HEAD\n\n# Get changed files\nCHANGED_FILES=$(git diff --name-only $MERGE_BASE..HEAD)\necho \"\"\necho \"📋 Changed files:\"\necho \"$CHANGED_FILES\"\n```\n\n### 4. Categorize Changes\n\n```bash\n# Analyze changes to determine type and scope\necho \"\"\necho \"🔍 Analyzing change categories...\"\n\nBUG_FIX=false\nNEW_FEATURE=false\nBREAKING_CHANGE=false\nDOCUMENTATION=false\nTESTS=false\n\n# Analyze commits for change indicators\nif echo \"$COMMITS\" | grep -E \"(fix|bug|error|issue|problem)\" >/dev/null; then\n BUG_FIX=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(feat|add|new|create|implement)\" >/dev/null; then\n NEW_FEATURE=true\nfi\n\nif echo \"$COMMITS\" | grep -E \"(break|change|remove|delete|major)\" >/dev/null; then\n BREAKING_CHANGE=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt|rst)$\" >/dev/null; then\n DOCUMENTATION=true\nfi\n\nif echo \"$CHANGED_FILES\" | grep -E \"(test|spec)\\.\" >/dev/null; then\n TESTS=true\nfi\n\n# Show analysis results\necho \"📊 Change type analysis:\"\nif [ \"$BUG_FIX\" = true ]; then echo \" ✅ Bug fix detected\"; fi\nif [ \"$NEW_FEATURE\" = true ]; then echo \" ✅ New feature detected\"; fi\nif [ \"$BREAKING_CHANGE\" = true ]; then echo \" ✅ Breaking change detected\"; fi\nif [ \"$DOCUMENTATION\" = true ]; then echo \" ✅ Documentation update detected\"; fi\nif [ \"$TESTS\" = true ]; then echo \" ✅ Test updates detected\"; fi\n```\n\n### 5. Generate PR Title\n\n```bash\n# Generate PR title\nif [ -n \"$CUSTOM_TITLE\" ]; then\n PR_TITLE=\"$CUSTOM_TITLE\"\nelse\n # Auto-generate title from first commit\n FIRST_COMMIT=$(echo \"$COMMITS\" | tail -1)\n\n # Clean up commit message for PR title\n if echo \"$FIRST_COMMIT\" | grep -E \"^(feat|fix|docs|style|refactor|test|chore)(\\(.+\\))?: \" >/dev/null; then\n # Use conventional commit format\n PR_TITLE=$(echo \"$FIRST_COMMIT\" | sed 's/^[a-f0-9]\\+ //')\n else\n # Fallback to simple format\n PR_TITLE=\"$CURRENT_BRANCH\"\n fi\nfi\n\necho \"📝 PR Title: $PR_TITLE\"\n```\n\n### 6. Generate PR Description\n\n```bash\n# Generate comprehensive PR description\necho \"📋 Generating PR description...\"\n\n# Generate change summary\nCHANGE_SUMMARY=\"\"\nif [ \"$BUG_FIX\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Bug fixes and error handling improvements\\n\"\nfi\nif [ \"$NEW_FEATURE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- New features and functionality additions\\n\"\nfi\nif [ \"$BREAKING_CHANGE\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Breaking changes requiring attention\\n\"\nfi\nif [ \"$DOCUMENTATION\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Documentation updates and improvements\\n\"\nfi\nif [ \"$TESTS\" = true ]; then\n CHANGE_SUMMARY=\"${CHANGE_SUMMARY}- Test coverage and quality improvements\\n\"\nfi\n\n# Generate file change summary\nFILE_CHANGES=\"\"\nfor file in $CHANGED_FILES; do\n FILE_CHANGES=\"${FILE_CHANGES}- \\`$file\\`\\n\"\ndone\n\n# Build complete PR description\nPR_DESCRIPTION=$(cat <<EOF\n## Description\n\nThis PR includes changes from branch \\`$CURRENT_BRANCH\\` with $COMMIT_COUNT commit(s) since divergence from \\`$BASE_BRANCH\\`.\n\n### Key Changes:\n\n$CHANGE_SUMMARY\n\n### Files Modified:\n\n$FILE_CHANGES\n\n## Type of Change\n\nEOF\n)\n\n# Add checkboxes based on analysis\nif [ \"$BUG_FIX\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Bug fix\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Bug fix\\n\"\nfi\n\nif [ \"$NEW_FEATURE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] New feature\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] New feature\\n\"\nfi\n\nif [ \"$BREAKING_CHANGE\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Breaking change\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Breaking change\\n\"\nfi\n\nif [ \"$DOCUMENTATION\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [x] Documentation update\\n\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}- [ ] Documentation update\\n\"\nfi\n\n# Add testing section\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Testing\n\n- [x] Code changes tested\n- [x] No new warnings introduced\n- [x] Code follows style guidelines\"\n\nif [ \"$TESTS\" = true ]; then\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [x] Tests added/updated\"\nelse\n PR_DESCRIPTION=\"${PR_DESCRIPTION}\\n- [ ] Tests added/updated\"\nfi\n\n# Add checklist\nPR_DESCRIPTION=\"${PR_DESCRIPTION}\n## Checklist\n\n- [x] Self-review completed\n- [x] Documentation updated (if applicable)\n- [x] No new warnings introduced\n- [x] Code follows project guidelines\n\n## Additional Information\n\n**Branch:** \\`$CURRENT_BRANCH\\` → \\`$BASE_BRANCH\\`\n**Commits:** $COMMIT_COUNT\n**Files Changed:** $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\n\n### Commit History:\n\n\\`\\`\\`\n$COMMITS\n\\`\\`\\`\n\n---\n🤖 Generated with /zcf-pr command\nEOF\n\necho \"✅ PR description generated\"\n```\n\n### 7. Push Branch and Create PR\n\n```bash\n# Check if branch exists on remote\nif ! git ls-remote --heads origin \"$CURRENT_BRANCH\" >/dev/null 2>&1; then\n echo \"📤 Pushing branch to remote...\"\n git push -u origin \"$CURRENT_BRANCH\"\nelse\n echo \"📤 Branch already exists on remote, ensuring it's up to date...\"\n git push origin \"$CURRENT_BRANCH\"\nfi\n\n# Create PR using gh CLI\necho \"📋 Creating pull request...\"\n\nPR_OPTIONS=\"--title '$PR_TITLE' --body '$PR_DESCRIPTION'\"\n\nif [ \"$IS_DRAFT\" = true ]; then\n PR_OPTIONS=\"$PR_OPTIONS --draft\"\nfi\n\n# Execute gh pr create command\nPR_URL=$(eval \"gh pr create --base $BASE_BRANCH $PR_OPTIONS\")\n\nif [ $? -eq 0 ]; then\n echo \"\"\n echo \"✅ Pull request created successfully!\"\n echo \"🔗 PR URL: $PR_URL\"\n echo \"\"\n echo \"📋 PR Details:\"\n echo \" Title: $PR_TITLE\"\n echo \" From: $CURRENT_BRANCH\"\n echo \" To: $BASE_BRANCH\"\n echo \" Commits: $COMMIT_COUNT\"\n echo \" Files: $(echo \"$CHANGED_FILES\" | wc -l | tr -d ' ')\"\n echo \"\"\n echo \"⚠️ Please review the PR and add any additional information as needed\"\nelse\n echo \"❌ Failed to create pull request\"\n echo \"Please check GitHub CLI authentication and permissions\"\n exit 1\nfi\n```\n\n## Complete Workflow Summary\n\n1. **Parameter Parsing**: Parse base branch, draft mode, and custom title options\n2. **Branch Validation**: Check current branch status and ensure it's different from base branch\n3. **Change Analysis**: Analyze commits and file changes since divergence from base branch\n4. **Categorization**: Auto-detect change types (bug fix, feature, breaking change, docs, tests)\n5. **Title Generation**: Generate appropriate PR title or use custom title\n6. **Description Generation**: Create comprehensive PR description following project template\n7. **Branch Push**: Ensure branch is available on remote repository\n8. **PR Creation**: Create pull request using GitHub CLI with all details\n\n## Important Notes\n\n⚠️ **Prerequisites**:\n\n- **GitHub CLI (`gh`)**: Must be installed and authenticated\n- **Clean working directory**: All changes must be committed before PR creation\n- **Remote branch**: Current branch must be pushed to remote repository\n- **Base branch**: Target branch must exist and be accessible\n\n### Best Practices:\n\n- Ensure commit messages follow conventional commit format\n- Test all changes before creating PR\n- Review auto-generated PR description for accuracy\n- Add any additional context specific to your changes\n- Check that all tests pass in CI/CD pipeline\n\n### Change Detection Logic:\n\nThe command automatically categorizes changes based on:\n\n- **Commit messages**: Keywords like \"feat\", \"fix\", \"break\", \"docs\", \"test\"\n- **File patterns**: `.md/.txt` for docs, `(test|spec)\\.` for tests\n- **File extensions**: TypeScript, JavaScript, JSON, etc.\n\n### Example Outputs:\n\n```bash\n# Standard PR to main\n/zcf-pr\n# → Creates PR: \"feat: add new feature\" with full description\n\n# PR to develop branch\n/zcf-pr --base develop\n# → Creates PR to develop branch instead of main\n\n# Draft PR\n/zcf-pr --draft\n# → Creates draft PR for initial review\n\n# Custom title\n/zcf-pr --title \"Critical bug fix for authentication\"\n# → Uses custom title instead of auto-generated one\n```\n\n---\n\n**Now creating pull request...**\n\n<!-- File: .claude/skills/zcf-release/SKILL.md (Tokens: ~3476 | Category: anthropic-skill) -->\n---\nname: zcf-release\ndescription: Automate version release and code commit using changeset\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, pnpm, node, date, cat, gh)\n---\n\n# ZCF Release - Automated Release and Commit\n\nAutomate version release and code commit using changeset.\n\n## Usage\n\n```bash\n/zcf-release [-p|-mi|-ma|<version>]\n```\n\n## Parameters\n\n- `-p` or `--patch`: Patch version (default) - bug fixes, minor changes\n- `-mi` or `--minor`: Minor version - new features, backward compatible\n- `-ma` or `--major`: Major version - breaking changes, incompatible\n- `<version>`: Specific version number (e.g., 1.2.3, 2.0.0-beta.1) - directly use provided version\n\n## Context\n\n- Automatically analyze code changes and generate bilingual CHANGELOG\n- Use changeset for version management\n- Create release branch and pull request for protected main branch\n- Auto commit code changes (NO manual tags)\n- Support GitHub Actions auto publish to npm with automatic tagging after PR merge\n\n## Your Role\n\nYou are a professional release management assistant responsible for:\n\n1. Analyzing code changes\n2. Generating standardized CHANGELOG\n3. Executing version release process\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nVERSION_TYPE=\"patch\" # Default to patch version\nSPECIFIC_VERSION=\"\" # For user-specified exact version\n\n# Check if argument looks like a version number (matches semver pattern)\nif [[ \"$ARGUMENTS\" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+([.-].*)?$ ]]; then\n SPECIFIC_VERSION=\"$ARGUMENTS\"\n VERSION_TYPE=\"custom\"\n echo \"🚀 Preparing to release exact version: $SPECIFIC_VERSION\"\nelse\n case \"$ARGUMENTS\" in\n -p|--patch)\n VERSION_TYPE=\"patch\"\n ;;\n -mi|--minor)\n VERSION_TYPE=\"minor\"\n ;;\n -ma|--major)\n VERSION_TYPE=\"major\"\n ;;\n \"\")\n VERSION_TYPE=\"patch\"\n ;;\n *)\n echo \"❌ Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-release [-p|-mi|-ma|<version>]\"\n echo \"Examples:\"\n echo \" /zcf-release -p # Patch version bump\"\n echo \" /zcf-release -mi # Minor version bump\"\n echo \" /zcf-release -ma # Major version bump\"\n echo \" /zcf-release 1.2.3 # Exact version\"\n echo \" /zcf-release 2.0.0-beta.1 # Pre-release version\"\n exit 1\n ;;\n esac\n echo \"🚀 Preparing to release $VERSION_TYPE version\"\nfi\n```\n\n### 2. Check Working Directory Status\n\nCheck if the current working directory meets release conditions:\n\n```bash\n# Ensure in project root directory\nif [ ! -f \"package.json\" ]; then\n echo \"❌ Error: package.json not found, please run in project root\"\n exit 1\nfi\n\n# Check for uncommitted changes and handle automatically\nHAS_UNCOMMITTED=false\nif ! git diff --quiet || ! git diff --cached --quiet; then\n echo \"⚠️ Detected uncommitted changes:\"\n git status --short\n echo \"\"\n HAS_UNCOMMITTED=true\nfi\n\necho \"✅ Working directory status OK\"\n```\n\n### 3. Analyze Version Changes\n\nAnalyze all changes since last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"📊 No previous version tag found, analyzing all commits\"\n COMMITS=$(git log --oneline)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n COMMITS=$(git log $LAST_TAG..HEAD --oneline)\nfi\n\n# Show commit history\necho -e \"\\n📝 Changes:\"\necho \"$COMMITS\"\n\n# Analyze file changes\necho -e \"\\n📁 File change statistics:\"\nif [ -z \"$LAST_TAG\" ]; then\n git diff --stat\nelse\n git diff --stat $LAST_TAG..HEAD\nfi\n```\n\n### 4. Generate CHANGELOG Content\n\nBased on code change analysis, I will generate CHANGELOG following these standards:\n\n**Format Requirements**:\n\n1. English description first, Chinese description second\n2. No mixing Chinese and English on the same line\n3. Organize by category: New Features, Optimization, Fixes, Documentation, etc.\n4. Each entry should be concise and clear\n\n**Example Format**:\n\n```markdown\n## New Features\n\n- Add technical execution guidelines with command best practices\n- Support automated release command /zcf-release\n- Automatic quote handling for Windows paths\n\n## 新功能\n\n- 添加技术执行指南文档，提供命令执行最佳实践\n- 支持自动化发版命令 /zcf-release\n- Windows 路径自动加引号处理\n\n## Optimization\n\n- Prioritize ripgrep for better search performance\n- Improve template file organization\n\n## 优化\n\n- 优先使用 ripgrep 提升搜索性能\n- 改进模板文件组织结构\n\n## Fixes\n\n- Fix Windows path backslash escaping issue\n\n## 修复\n\n- 修复 Windows 路径反斜杠丢失问题\n```\n\n### 5. Create Changeset\n\nCreate changeset file based on analysis:\n\n```bash\n# Generate timestamp\nTIMESTAMP=$(date +%Y%m%d%H%M%S)\nCHANGESET_FILE=\".changeset/release-$TIMESTAMP.md\"\n\n# Create changeset file\necho \"📝 Creating changeset file...\"\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n # For specific version, use the exact version number\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $SPECIFIC_VERSION\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with exact version: $SPECIFIC_VERSION\"\nelse\n # For version type (patch/minor/major), use the type\n cat > \"$CHANGESET_FILE\" << EOF\n---\n\"zcf\": $VERSION_TYPE\n---\n\n[Bilingual CHANGELOG content generated based on actual changes]\nEOF\n echo \"✅ Changeset file created with version type: $VERSION_TYPE\"\nfi\n```\n\n### 6. Update Version Number\n\nUse changeset to update version number and CHANGELOG:\n\n```bash\necho \"🔄 Updating version number and CHANGELOG...\"\npnpm changeset version\n\n# Note: The changeset version command will automatically:\n# 1. Update package.json version\n# 2. Generate/update CHANGELOG.md\n# 3. DELETE the temporary changeset file in .changeset/ directory\n# No manual cleanup needed!\n\n# Get new version number\nNEW_VERSION=$(node -p \"require('./package.json').version\")\nif [ \"$VERSION_TYPE\" = \"custom\" ]; then\n echo \"📦 New version set to: v$NEW_VERSION (specified: $SPECIFIC_VERSION)\"\nelse\n echo \"📦 New version: v$NEW_VERSION\"\nfi\n\n# Show CHANGELOG update\necho -e \"\\n📋 CHANGELOG has been updated, please review the content\"\necho \"✅ Temporary changeset file has been automatically deleted\"\n```\n\n### 7. Create Release Branch and Handle Commits\n\nCreate release branch first, then handle commits separately to avoid polluting main branch:\n\n````bash\necho \"🚀 Creating release branch...\"\n\n# Create and switch to release branch\nRELEASE_BRANCH=\"release/v$NEW_VERSION\"\ngit checkout -b \"$RELEASE_BRANCH\"\n\n# Handle uncommitted changes first (if any)\nif [ \"$HAS_UNCOMMITTED\" = true ]; then\n echo \"📝 Committing pre-release changes...\"\n \n # Stage only the uncommitted changes (exclude changeset modifications)\n git add .\n git reset HEAD package.json CHANGELOG.md 2>/dev/null || true\n \n # Check if there are still changes to commit after reset\n if ! git diff --quiet --staged; then\n # Analyze the staged changes to generate appropriate commit message\n echo \"🔍 Analyzing uncommitted changes...\"\n CHANGED_FILES=$(git diff --staged --name-only)\n \n # Generate commit message based on changed files\n COMMIT_TYPE=\"chore\"\n COMMIT_SCOPE=\"\"\n COMMIT_DESCRIPTION=\"pre-release changes\"\n \n # Analyze file patterns to determine commit type and scope\n if echo \"$CHANGED_FILES\" | grep -E \"\\.(md|txt)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -i \"readme\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"readme\"\n COMMIT_DESCRIPTION=\"update README documentation\"\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.claude/\" >/dev/null; then\n COMMIT_TYPE=\"docs\"\n COMMIT_SCOPE=\"commands\"\n COMMIT_DESCRIPTION=\"update command documentation\"\n else\n COMMIT_TYPE=\"docs\"\n COMMIT_DESCRIPTION=\"update documentation\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.(ts|js|tsx|jsx)$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep -E \"test|spec\" >/dev/null; then\n COMMIT_TYPE=\"test\"\n COMMIT_DESCRIPTION=\"update tests\"\n else\n COMMIT_TYPE=\"feat\"\n COMMIT_DESCRIPTION=\"code changes\"\n fi\n elif echo \"$CHANGED_FILES\" | grep -E \"\\.json$\" >/dev/null; then\n if echo \"$CHANGED_FILES\" | grep \"package\" >/dev/null; then\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update dependencies\"\n else\n COMMIT_TYPE=\"chore\"\n COMMIT_DESCRIPTION=\"update configuration\"\n fi\n fi\n \n # Build commit message\n if [ -n \"$COMMIT_SCOPE\" ]; then\n COMMIT_MSG=\"${COMMIT_TYPE}(${COMMIT_SCOPE}): ${COMMIT_DESCRIPTION}\"\n else\n COMMIT_MSG=\"${COMMIT_TYPE}: ${COMMIT_DESCRIPTION}\"\n fi\n \n # Add file list to commit body\n COMMIT_BODY=\"\"\n for file in $CHANGED_FILES; do\n COMMIT_BODY=\"${COMMIT_BODY}- Update ${file}\n\"\n done\n COMMIT_BODY=\"${COMMIT_BODY}\n🤖 Generated with [Claude Code](https://claude.ai/code)\n \n # Create the commit\n git commit -m \"${COMMIT_MSG}\n\n${COMMIT_BODY}\"\n \n echo \"✅ Pre-release changes committed: $COMMIT_MSG\"\n else\n echo \"ℹ️ No additional changes to commit after version update\"\n fi\nfi\n\necho \"💾 Committing release version changes...\"\n\n# Add version-related changes\ngit add package.json CHANGELOG.md\n\n# Create release version commit\ngit commit -m \"chore: release v$NEW_VERSION\n\n- Update version to $NEW_VERSION\n- Update CHANGELOG.md\n- Generated by /zcf-release command\"\n\n# Push release branch to remote and set upstream tracking\ngit push -u origin \"$RELEASE_BRANCH\"\n\n# If push fails due to conflicts, use force-with-lease to safely overwrite\n# git push --force-with-lease origin \"$RELEASE_BRANCH\"\n\n# Set upstream tracking if not set automatically\ngit branch --set-upstream-to=origin/$RELEASE_BRANCH $RELEASE_BRANCH\n\n### 8. Create Pull Request\n\n```bash\necho \"📋 Creating pull request...\"\n\n# Create pull request using gh CLI following the project's PR template\ngh pr create --title \"🚀 Release v$NEW_VERSION\" --body \"$(cat <<'EOF'\n## Description\n\nRelease version v$NEW_VERSION with automated version bump and CHANGELOG update.\n\nThis release includes important changes, please review CHANGELOG.md for details.\n\n## Type of Change\n\n- [x] New feature\n- [ ] Bug fix\n- [ ] Breaking change\n- [x] Documentation update\n\n## Testing\n\n- [x] Tests added/updated\n- [x] All tests pass\n- [x] Coverage maintained\n\n## Checklist\n\n- [x] Code follows style guidelines\n- [x] Self-review completed\n- [x] Documentation updated\n- [x] No new warnings introduced\n\n## Release Notes\n\n⚠️ **IMPORTANT**: After merge, GitHub Actions will automatically:\n- Create release tag\n- Publish to npm \n- Generate GitHub Release\n\n🤖 Generated by /zcf-release command\nEOF\n)\"\n\necho -e \"\\n✅ Release preparation complete!\"\necho \"📦 Version v$NEW_VERSION is ready\"\necho \"🔗 Pull request created successfully\"\necho \"\"\necho \"⚠️ IMPORTANT: Review and merge the PR to trigger the release\"\necho \"⚠️ Do NOT create or push tags manually!\"\necho \"🤖 After PR merge, GitHub Actions will automatically:\"\necho \" - Create the release tag\"\necho \" - Publish to npm\"\necho \" - Generate GitHub Release\"\necho \"👀 View release status: https://github.com/UfoMiao/zcf/actions\"\n````\n\n## Complete Workflow Summary\n\n1. **Preparation Phase**: Check parameters (version type or exact version), working directory status\n2. **Analysis Phase**: Analyze commit history and file changes\n3. **Generation Phase**: Create bilingual CHANGELOG\n4. **Execution Phase**: Update version (automatic bump or exact version)\n5. **Branch Creation Phase**: Create release branch BEFORE committing\n6. **Commit Phase**: Commit changes on release branch\n7. **PR Creation Phase**: Push release branch and create pull request\n8. **Review & Release Phase**: Manual PR review and merge, then GitHub Actions auto publish\n\n## Important Notes\n\n⚠️ **CRITICAL**: **NEVER create or push Git tags manually!** GitHub Actions will automatically:\n\n- Create the version tag after successful PR merge\n- Generate GitHub Release\n- Publish to npm registry\n\nManual tags will cause conflicts with the automated release process!\n\n### New Protected Branch Workflow:\n\n- 🛡️ **Main branch is protected**: Cannot push directly to main\n- 🌿 **Release branch created**: Automatic creation of `release/v{version}` branch\n- 📋 **Pull Request required**: All releases must go through PR review process\n- ✅ **Manual approval needed**: PR must be reviewed and merged manually\n- 🤖 **Auto-release after merge**: GitHub Actions triggers after PR merge\n\n### Additional Notes:\n\n- Ensure all code has been tested before running release command\n- CHANGELOG must follow bilingual format standards\n- When using version types (-p/-mi/-ma), choose the correct type for your changes\n- When providing exact version numbers, ensure they follow semantic versioning (e.g., 1.2.3, 2.0.0-beta.1)\n- Exact version numbers bypass automatic version determination - use carefully\n- Carefully review CHANGELOG content in the created PR before merging\n- **No manual cleanup needed**: `changeset version` automatically deletes temporary changeset files\n- The `.changeset/` directory should only contain config files, not temporary release files\n- **Requires `gh` CLI**: Ensure GitHub CLI is installed and authenticated for PR creation\n\n**Version Parameter Examples**:\n- `/zcf-release` or `/zcf-release -p` - Auto patch bump (2.9.11 → 2.9.12)\n- `/zcf-release -mi` - Auto minor bump (2.9.11 → 2.10.0) \n- `/zcf-release -ma` - Auto major bump (2.9.11 → 3.0.0)\n- `/zcf-release 1.5.0` - Exact version (→ 1.5.0)\n- `/zcf-release 3.0.0-alpha.1` - Pre-release version (→ 3.0.0-alpha.1)\n\n---\n\n**Now starting release process...**\n\n<!-- File: .claude/skills/zcf-update-docs/SKILL.md (Tokens: ~3977 | Category: anthropic-skill) -->\n---\nname: zcf-update-docs\ndescription: Automatically check code changes since last tag and update documentation in docs/ directory (en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git, cat, grep, diff)\n---\n\n# ZCF Update Docs - Documentation Synchronization\n\nAutomatically check code changes since last tag and update documentation in `docs/` directory (multilingual: en, zh-CN, ja-JP) and CLAUDE.md to ensure consistency with actual code implementation.\n\n## Usage\n\n```bash\n/zcf-update-docs [--check-only]\n```\n\n## Parameters\n\n- `--check-only`: Only check for inconsistencies without making updates (dry run)\n\n## Context\n\n- Analyze all code changes since the last Git tag\n- Check if documentation needs updates in docs/ directory structure\n- Ensure CLI commands, features, and workflows documentation match actual code\n- Maintain multilingual documentation consistency across en, zh-CN, ja-JP\n- Update CLAUDE.md for development-related changes\n\n## Your Role\n\nYou are a professional documentation maintainer responsible for:\n\n1. Analyzing code changes and their impact on documentation\n2. Identifying documentation sections that need updates\n3. Ensuring documentation accuracy and consistency\n4. Maintaining multilingual synchronization\n\n## Execution Flow\n\nParse arguments: $ARGUMENTS\n\n### 1. Parameter Parsing\n\n```bash\nCHECK_ONLY=false # Default to update mode\n\ncase \"$ARGUMENTS\" in\n --check-only)\n CHECK_ONLY=true\n echo \"📋 Running in check-only mode (no files will be modified)\"\n ;;\n \"\")\n CHECK_ONLY=false\n echo \"✏️ Running in update mode\"\n ;;\n *)\n echo \"Unknown parameter: $ARGUMENTS\"\n echo \"Usage: /zcf-update-docs [--check-only]\"\n exit 1\n ;;\nesac\n```\n\n### 2. Get Changes Since Last Tag\n\nAnalyze all changes since the last release:\n\n```bash\n# Get last release tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo \"\")\n\nif [ -z \"$LAST_TAG\" ]; then\n echo \"⚠️ No previous version tag found, analyzing all files\"\n FILES_CHANGED=$(git ls-files)\nelse\n echo \"📊 Last version: $LAST_TAG\"\n echo \"Analyzing changes since $LAST_TAG...\"\n FILES_CHANGED=$(git diff --name-only $LAST_TAG..HEAD)\nfi\n\n# Categorize changed files\necho -e \"\\n📁 Analyzing changed files...\"\n```\n\n### 3. Identify Documentation Update Areas\n\nBased on file changes, determine which documentation files in `docs/` need updates:\n\n**Code Changes → Documentation Mapping:**\n\n1. **CLI Commands** (`src/commands/*.ts`) → `docs/{lang}/cli/`\n - `src/commands/init.ts` → `cli/init.md` - Installation and initialization\n - `src/commands/menu.ts` → `cli/menu.md` - Interactive menu system\n - `src/commands/update.ts` → `cli/update.md` - Update workflows\n - `src/commands/ccr.ts` → `cli/ccr.md` - CCR proxy management\n - `src/commands/ccu.ts` → `cli/ccu.md` - Usage analysis\n - `src/commands/uninstall.ts` → `cli/uninstall.md` - Uninstallation\n - `src/commands/config-switch.ts` → `cli/config-switch.md` - Config switching\n - `src/commands/check-updates.ts` → `cli/check-updates.md` - Version check\n\n2. **Features** → `docs/{lang}/features/`\n - `src/utils/installer.ts`, `src/utils/claude-config.ts` → `features/claude-code.md`\n - `src/utils/code-tools/codex*` → `features/codex.md`\n - `src/config/workflows.ts` → `features/workflows.md`\n - `src/config/mcp-services.ts` → `features/mcp.md`\n - `src/utils/ccr/` → `features/ccr.md`\n - `src/utils/cometix/` → `features/cometix.md`\n - `src/utils/config.ts` → `features/multi-config.md`\n\n3. **Workflows** (`src/config/workflows.ts`, `templates/*/workflow/`) → `docs/{lang}/workflows/`\n - Workflow definitions → `workflows/index.md`\n - Specific workflow templates → `workflows/{workflow-name}.md`\n\n4. **Advanced Configuration** → `docs/{lang}/advanced/`\n - `src/types/config.ts`, `src/utils/config.ts` → `advanced/configuration.md`\n - `src/config/api-providers.ts` → `advanced/api-providers.md`\n - `templates/` → `advanced/templates.md`\n - `src/i18n/` → `advanced/i18n.md`\n\n5. **Getting Started** → `docs/{lang}/getting-started/`\n - `src/commands/init.ts`, `src/utils/installer.ts` → `getting-started/installation.md`\n - General introduction → `getting-started/index.md`\n\n6. **Development** → `docs/{lang}/development/` and `CLAUDE.md`\n - Architecture changes → `development/architecture.md` + `CLAUDE.md`\n - Testing changes → `development/testing.md` + `CLAUDE.md`\n - Contributing guidelines → `development/contributing.md`\n - Package.json scripts → `CLAUDE.md`\n\n### 4. Check Current Documentation\n\nRead and analyze current documentation structure:\n\n```bash\n# Check if documentation directories exist\nDOCS_LANGS=(\"en\" \"zh-CN\" \"ja-JP\")\nDOCS_CATEGORIES=(\n \"getting-started\"\n \"cli\"\n \"features\"\n \"workflows\"\n \"advanced\"\n \"best-practices\"\n \"development\"\n)\n\necho \"📁 Checking documentation structure...\"\n\nfor LANG in \"${DOCS_LANGS[@]}\"; do\n if [ ! -d \"docs/$LANG\" ]; then\n echo \"❌ Warning: docs/$LANG directory not found\"\n else\n echo \"✅ Found: docs/$LANG/\"\n for CATEGORY in \"${DOCS_CATEGORIES[@]}\"; do\n if [ ! -d \"docs/$LANG/$CATEGORY\" ]; then\n echo \" ⚠️ Missing category: $CATEGORY\"\n else\n echo \" ✅ Category: $CATEGORY\"\n fi\n done\n fi\ndone\n\n# Check CLAUDE.md\nif [ ! -f \"CLAUDE.md\" ]; then\n echo \"❌ Warning: CLAUDE.md not found\"\nelse\n echo \"✅ Found: CLAUDE.md\"\nfi\n```\n\n### 5. Verify CLI Commands Consistency\n\nCompare CLI commands implementation with documentation:\n\n**Check Points:**\n- Command names, options, and parameters\n- Command descriptions and usage examples\n- Interactive menu options and flow\n- Keyboard shortcuts and navigation\n- Exit and back options\n- Multilingual prompt translations\n\n**Code Sources → Documentation Files:**\n- `src/commands/menu.ts`, `src/i18n/locales/*/menu.json` → `docs/{lang}/cli/menu.md`\n- `src/commands/init.ts`, `src/i18n/locales/*/cli.json` → `docs/{lang}/cli/init.md`\n- `src/commands/update.ts` → `docs/{lang}/cli/update.md`\n- `src/commands/ccr.ts` → `docs/{lang}/cli/ccr.md`\n- `src/commands/ccu.ts` → `docs/{lang}/cli/ccu.md`\n- `src/commands/uninstall.ts` → `docs/{lang}/cli/uninstall.md`\n- `src/commands/config-switch.ts` → `docs/{lang}/cli/config-switch.md`\n- `src/commands/check-updates.ts` → `docs/{lang}/cli/check-updates.md`\n\n### 6. Verify Features Documentation\n\nEnsure features documentation matches actual implementation:\n\n**Check Points:**\n1. Claude Code configuration capabilities\n2. Codex CLI integration and setup\n3. Workflow system and categories\n4. MCP service integration\n5. CCR proxy management\n6. Cometix status line\n7. Multi-config and backup system\n8. API provider presets\n\n**Code Sources → Documentation Files:**\n- `src/utils/installer.ts`, `src/utils/claude-config.ts` → `docs/{lang}/features/claude-code.md`\n- `src/utils/code-tools/codex*.ts`, `templates/codex/` → `docs/{lang}/features/codex.md`\n- `src/config/workflows.ts` → `docs/{lang}/features/workflows.md`\n- `src/config/mcp-services.ts` → `docs/{lang}/features/mcp.md`\n- `src/utils/ccr/` → `docs/{lang}/features/ccr.md`\n- `src/utils/cometix/` → `docs/{lang}/features/cometix.md`\n- `src/utils/config.ts` → `docs/{lang}/features/multi-config.md`\n\n### 7. Generate Update Report\n\nCreate a detailed report of findings:\n\n```markdown\n## Documentation Update Report\n\n### Files Changed Since $LAST_TAG\n- [List of relevant changed files categorized by module]\n\n### Documentation Files Requiring Updates\n\n#### docs/en/ (English Documentation)\n- [ ] getting-started/installation.md - Installation and setup\n- [ ] cli/*.md - CLI command documentation\n- [ ] features/*.md - Feature descriptions\n- [ ] workflows/*.md - Workflow guides\n- [ ] advanced/*.md - Advanced configuration\n- [ ] development/*.md - Development documentation\n\n#### docs/zh-CN/ (Chinese Documentation)\n- [ ] getting-started/installation.md - 安装和设置\n- [ ] cli/*.md - CLI 命令文档\n- [ ] features/*.md - 功能说明\n- [ ] workflows/*.md - 工作流指南\n- [ ] advanced/*.md - 高级配置\n- [ ] development/*.md - 开发文档\n\n#### docs/ja-JP/ (Japanese Documentation)\n- [ ] getting-started/installation.md - インストールとセットアップ\n- [ ] cli/*.md - CLI コマンドドキュメント\n- [ ] features/*.md - 機能説明\n- [ ] workflows/*.md - ワークフローガイド\n- [ ] advanced/*.md - 高度な設定\n- [ ] development/*.md - 開発ドキュメント\n\n#### CLAUDE.md (Root Development Documentation)\n- [ ] Development commands (package.json scripts)\n- [ ] Architecture and module structure\n- [ ] Testing guidelines and coverage\n- [ ] Workflow system implementation\n- [ ] Code standards and conventions\n\n### Specific Inconsistencies Found\n[Detailed list of mismatches between code and documentation, organized by file]\n```\n\n### 8. Update Documentation Files\n\nIf not in check-only mode, update the documentation:\n\n```bash\nif [ \"$CHECK_ONLY\" = false ]; then\n echo \"📝 Updating documentation files in docs/ directory...\"\n \n # Update docs/en/ (English Documentation)\n # - CLI commands: Update docs/en/cli/*.md based on src/commands/*.ts\n # - Features: Update docs/en/features/*.md based on feature implementations\n # - Workflows: Update docs/en/workflows/*.md based on src/config/workflows.ts\n # - Getting Started: Update docs/en/getting-started/*.md based on installation flow\n # - Advanced: Update docs/en/advanced/*.md based on configuration and templates\n # - Development: Update docs/en/development/*.md based on architecture changes\n # - Use translations from src/i18n/locales/en/*.json\n \n # Update docs/zh-CN/ (Chinese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Chinese translations from src/i18n/locales/zh-CN/*.json\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure technical terms and examples are properly localized\n \n # Update docs/ja-JP/ (Japanese Documentation)\n # - Maintain same structure and sections as English version\n # - Use proper Japanese translations (maintain consistency with project style)\n # - Update all corresponding CLI, features, workflows, etc.\n # - Ensure proper Japanese formatting and terminology\n \n # Update CLAUDE.md (Root Development Documentation)\n # - Update development commands if package.json scripts changed\n # - Update architecture section if new modules added\n # - Update testing section if test structure changed\n # - Update workflow system if src/config/workflows.ts changed\n # - Update module index if directory structure changed\n # - Maintain English-only for development documentation\n \n # Update SUMMARY.md for each language\n # - Ensure table of contents matches actual file structure\n # - Update links if files were added/removed/renamed\n # - Maintain consistent ordering across all languages\n \n echo \"✅ Documentation files updated in docs/ directory\"\nelse\n echo \"ℹ️ Check-only mode: No files were modified\"\nfi\n```\n\n### 9. Validation\n\nPerform final validation checks:\n\n```bash\necho -e \"\\n🔍 Performing validation checks...\"\n\n# Check for broken internal links in all language versions\necho \"Checking internal links in docs/en/, docs/zh-CN/, docs/ja-JP/...\"\n\n# Verify SUMMARY.md matches actual file structure\necho \"Validating SUMMARY.md table of contents...\"\n\n# Ensure structure consistency across languages\necho \"Checking structural consistency across en, zh-CN, ja-JP...\"\n\n# Verify code examples still work\necho \"Verifying code examples and command syntax...\"\n\n# Validate markdown formatting\necho \"Validating markdown format...\"\n\n# Check translation completeness\necho \"Checking multilingual translation completeness...\"\n\n# Verify CLI command documentation matches implementation\necho \"Verifying CLI command documentation accuracy...\"\n\n# Validate feature documentation completeness\necho \"Checking feature documentation coverage...\"\n\necho \"✅ Validation complete\"\n```\n\n### 10. Summary Report\n\nGenerate final summary:\n\n```bash\necho -e \"\\n📊 Documentation Update Summary\"\necho \"================================\"\necho \"Files analyzed: [count]\"\necho \"Documentation files updated: [list]\"\necho \"Sections modified: [count]\"\necho \"\"\necho \"Key updates:\"\necho \"- [List major updates]\"\necho \"\"\nif [ \"$CHECK_ONLY\" = true ]; then\n echo \"📋 This was a check-only run. To apply updates, run without --check-only\"\nelse\n echo \"✅ Documentation has been synchronized with code\"\n echo \"📝 Please review the changes before committing\"\nfi\n```\n\n## Documentation Structure Reference\n\n### docs/{lang}/ Directory Structure (en, zh-CN, ja-JP)\n\nEach language directory contains the following categories:\n\n1. **getting-started/** - Installation and quick start\n - `index.md` - Quick start guide\n - `installation.md` - Installation guide (Must match `src/commands/init.ts`)\n\n2. **cli/** - CLI command documentation\n - `index.md` - Commands overview\n - `init.md`, `update.md`, `menu.md`, etc. (Must match `src/commands/*.ts`)\n\n3. **features/** - Feature descriptions\n - `index.md` - Features overview\n - `claude-code.md`, `codex.md`, `workflows.md`, etc. (Must match implementations)\n\n4. **workflows/** - Workflow guides\n - `index.md` - Workflow overview\n - Specific workflow documentation (Must match `src/config/workflows.ts`)\n\n5. **advanced/** - Advanced configuration\n - `configuration.md`, `api-providers.md`, `templates.md`, etc.\n\n6. **best-practices/** - Best practices and tips\n - Usage tips and optimization strategies\n\n7. **development/** - Development documentation\n - `architecture.md`, `contributing.md`, `testing.md`\n\n8. **SUMMARY.md** - Table of contents for each language\n\n### CLAUDE.md Structure (Root Development Documentation)\n\n1. **Project Overview**\n2. **Architecture Overview** (Must match actual module structure)\n3. **Module Index** (Must match src/ directory structure)\n4. **CLI Usage**\n5. **Running and Development** (Must match `package.json` scripts)\n6. **Development Guidelines**\n7. **Testing Strategy**\n8. **AI Team Configuration**\n\n## Important Notes\n\n⚠️ **Critical Requirements:**\n- **ALWAYS** ensure CLI command documentation matches actual implementation in `src/commands/`\n- **ALWAYS** verify feature descriptions match actual code behavior\n- **ALWAYS** maintain structural consistency across all language versions (en, zh-CN, ja-JP)\n- **ALWAYS** update SUMMARY.md when file structure changes\n- **NEVER** remove existing content without verification\n- **NEVER** break markdown formatting or internal links\n- **NEVER** create inconsistency between language versions\n\n📌 **Best Practices:**\n- Use actual i18n translations from `src/i18n/locales/{lang}/*.json`\n- Preserve existing formatting and style conventions\n- Update code examples to reflect current implementation\n- Include new features and commands added since last tag\n- Remove or mark deprecated features that no longer exist\n- Maintain parallel structure across en, zh-CN, ja-JP directories\n- Keep CLAUDE.md focused on development-specific information\n\n🔍 **Validation Checklist:**\n- [ ] CLI command docs match `src/commands/*.ts` implementation\n- [ ] Feature docs match actual feature implementations\n- [ ] Workflow docs match `src/config/workflows.ts` definitions\n- [ ] Installation guide matches `src/commands/init.ts` flow\n- [ ] Configuration docs match types in `src/types/*.ts`\n- [ ] MCP service docs match `src/config/mcp-services.ts`\n- [ ] Structure consistency across en, zh-CN, ja-JP directories\n- [ ] SUMMARY.md matches actual file structure for each language\n- [ ] All internal links are valid and not broken\n- [ ] Code examples and command syntax are correct\n- [ ] Translations use proper i18n strings from codebase\n- [ ] Markdown formatting is valid in all files\n- [ ] Codex integration documentation is comprehensive\n- [ ] CCR, Cometix, CCusage features are accurately documented\n- [ ] API provider presets documentation is up-to-date\n- [ ] CLAUDE.md reflects current architecture and development practices\n\n---\n\n**Now starting documentation update process...**\n\n<!-- File: templates/skills/en/bmad-init/SKILL.md (Tokens: ~2644 | Category: anthropic-skill) -->\n---\nname: bmad-init\ndescription: Initialize or update BMad-Method (V6) in your project\ndisable-model-invocation: true\n---\n\n# /bmad-init Command\n\nThis command initializes or updates BMad-Method (V6) in your project.\n\n## When this command is invoked:\n\n1. Check if `_bmad/` directory exists to determine if BMad V6 is already installed\n2. Check for legacy V4 installations (`.bmad-core` or `.bmad-method` directories)\n3. Fresh install executes: `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n4. Existing install executes: `npx bmad-method install --directory . --action quick-update --yes`\n5. Fix installer bug: rename `{output_folder}` to `_bmad-output` (Beta known issue)\n6. Automatically update `.gitignore` (remove V4 entries, add V6 entries)\n7. Display installation results and prompt user for next steps\n\n## Implementation\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// Legacy entries to clean from .gitignore\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug artifact\n]\n\n// V6 .gitignore entries\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// Fix installer bug: {output_folder} not resolved to _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output doesn't exist, simply rename\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (renamed)')\n } else {\n // _bmad-output already exists, merge subdirectories then delete\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ Moved ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ Removed redundant {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // Remove V4 legacy entries\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ Removing legacy entry: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // Add V6 entries\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ Adding new entry: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore is up to date, no changes needed')\n return\n }\n\n // Build new content\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // Ensure trailing newline, then add BMad section\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore ${exists ? 'updated' : 'created'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // Check for legacy V4 installation\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ Legacy BMad V4 installation detected:')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 core directory)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 method directory)')\n console.log('')\n console.log('📌 The V6 installer will handle legacy migration automatically. Follow the prompts during installation.')\n console.log(' Details: https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // Check if V6 is already installed\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // Build non-interactive install command\n let installCmd\n if (hasV6) {\n console.log('🔄 Existing BMad V6 installation detected, performing quick update...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 Initializing BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language English',\n '--document-output-language English',\n '--yes',\n ].join(' ')\n }\n\n // Execute installation\n try {\n console.log(`📋 Executing: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 installation/update complete!')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 IMPORTANT: Please restart your AI IDE to load BMad extensions')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // Fix {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 Checking for known installer issues...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ No fixes needed')\n } catch (err) {\n console.log(` ⚠️ Failed to fix {output_folder}: ${err.message}`)\n console.log(' Please manually rename {output_folder}/ to _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 Directory Structure:')\n console.log(' • _bmad/ — agents, workflows, tasks, and configuration')\n console.log(' • _bmad-output/ — generated artifact output directory')\n console.log('')\n\n // Automatically update .gitignore\n console.log('🔧 Updating .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ Failed to automatically update .gitignore, please manually add _bmad/ and _bmad-output/')\n }\n console.log('')\n console.log('🚀 Quick Start:')\n console.log(' 1. Restart your AI IDE')\n console.log(' 2. Run /bmad-help for guidance and next step suggestions')\n console.log(' 3. Type /bmad and use autocomplete to browse available commands')\n console.log('')\n console.log('💡 Common Workflows:')\n console.log(' • /bmad-help — Interactive help')\n console.log(' • /bmad-bmm-create-prd — Create Product Requirements Document')\n console.log(' • /bmad-bmm-create-architecture — Create Architecture Document')\n console.log(' • /bmad-bmm-create-epics-and-stories — Create Epics and User Stories')\n console.log(' • /bmad-bmm-sprint-planning — Initialize Sprint Planning')\n console.log(' • /bmad-bmm-dev-story — Implement User Story')\n\n // Legacy V4 IDE command cleanup reminder\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ Legacy V4 IDE commands detected, consider removing manually:')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' New V6 commands are installed under .claude/commands/bmad/')\n }\n }\n catch (error) {\n console.error('❌ Installation failed:', error.message)\n console.log('')\n console.log('🛠️ Manual Installation Guide:')\n console.log(' 1. Ensure Node.js 20+ is installed')\n console.log(' 2. Non-interactive install:')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes')\n console.log(' 3. Quick update existing installation:')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. Or interactive install:')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 Documentation:')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// Execute initialization\ninitBmad()\n```\n\n## Usage\n\nSimply type in Claude Code:\n\n```\n/bmad-init\n```\n\nThis command will:\n\n1. Detect current installation status (V6 / V4 legacy / not installed)\n2. Fresh install: non-interactively execute `npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language English --document-output-language English --yes`\n3. Existing install: execute `npx bmad-method install --directory . --action quick-update --yes`\n4. Fix `{output_folder}` → `_bmad-output` installer bug\n5. Automatically update `.gitignore` (clean up legacy entries, add V6 entries)\n6. Provide next step suggestions\n\n<!-- File: templates/skills/en/feat/SKILL.md (Tokens: ~601 | Category: anthropic-skill) -->\n---\nname: feat\ndescription: Add New Feature\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## Core Workflow\n\n### 1. Input Analysis and Type Determination\n\nWhen receiving user input, first perform type determination and clearly inform the user:\n\n**Determination Criteria:**\n\n- **Requirement Planning Type**: User proposes new feature requirements, project ideas, or needs to formulate plans\n\n- **Discussion Iteration Type**: User requests to continue discussion, modify, or refine existing planning\n\n- **Execution Implementation Type**: User confirms planning is complete and requests to start specific implementation work\n\n### 2. Classification Processing Mechanism\n\n#### A. Requirement Planning Processing\n\n**Trigger Condition**: Identified as functional requirement input\n\n**Execution Actions**:\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Store document in `./.claude/plan` directory, named in plan/xxx.md format\n\n- Include: objective definition, feature breakdown, implementation steps, acceptance criteria\n\n#### B. Discussion Iteration Processing\n\n**Trigger Condition**: User requests to continue discussion or modify planning\n\n**Execution Actions**:\n\n- Retrieve and analyze previously generated planning files\n\n- Identify user feedback and confirmation content\n\n- Enable Planner Agent\n\n- Generate detailed markdown planning document\n\n- Create a new document, for example, if the last one was plan/xxx.md, then this time it's plan/xxx-1.md, if the last one was plan/xxx-1.md, then this time it's plan/xxx-2.md, and so on\n\n- Reorganize pending implementation task priorities\n\n#### C. Execution Implementation Processing\n\n**Trigger Condition**: User confirms planning is complete and requests to start execution\n\n**Execution Actions**:\n\n- Start task execution in the order of planning documents\n\n- Perform task type identification before each subtask begins\n\n- **Frontend Task Special Processing**:\n\n- Check if available UI design exists\n\n- If no design solution exists, must use UI-UX-Designer Agent\n\n- Complete UI design before proceeding with development implementation\n\n### 3. Key Execution Principles\n\n#### Mandatory Response Requirements\n\n- **Must first state in every interaction**: \"I determine this operation type as: [specific type]\"\n\n- Type determination must be accurate and clearly communicated to users\n\n#### Task Execution Standards\n\n- Strictly execute according to documented planning\n\n- Must clarify task nature and dependencies before subtask startup\n\n- Frontend tasks must ensure UI design completeness\n\n#### State Management Mechanism\n\n- Maintain task completion status tracking\n\n- Timely update planning document status\n\n- Ensure user visibility of progress\n\n## Quality Assurance Points\n\n1. **Type Determination Accuracy**: Type identification at the beginning of each interaction must be accurate\n\n2. **Document Consistency**: Planning documents and actual execution remain synchronized\n\n3. **Dependency Management**: Pay special attention to UI design dependencies of frontend tasks\n\n4. **Transparent User Communication**: All judgments and actions must be clearly communicated to users\n\n<!-- File: templates/skills/en/git-clean-branches/SKILL.md (Tokens: ~1056 | Category: anthropic-skill) -->\n---\nname: git-clean-branches\ndescription: Safely find and clean up merged or stale Git branches with dry-run mode and custom base/protected branches support\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\nThis command **safely** identifies and cleans up **merged** or **stale** Git branches.\nRuns in **read-only preview (`--dry-run`)** mode by default, requiring explicit instructions to perform deletions.\n\n---\n\n## Usage\n\n```bash\n# [Safest] Preview branches to be cleaned without executing any deletions\n/git-cleanBranches --dry-run\n\n# Clean local branches merged to main and inactive for over 90 days (requires individual confirmation)\n/git-cleanBranches --stale 90\n\n# Clean local and remote branches merged to release/v2.1 (auto-confirm)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [Dangerous] Force delete an unmerged local branch\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`: Specify the base branch for cleanup (defaults to repository's `main`/`master`).\n- `--stale <days>`: Clean branches with no commits for specified days (disabled by default).\n- `--remote`: Also clean remote merged/stale branches.\n- `--dry-run`: **Default behavior**. Only list branches to be deleted without executing any operations.\n- `--yes`: Skip individual confirmations and delete all identified branches directly (suitable for CI/CD).\n- `--force`: Use `-D` to force delete local branches (even if unmerged).\n\n---\n\n## What This Command Does\n\n1. **Configuration and Safety Checks**\n - **Update Information**: Automatically executes `git fetch --all --prune` to ensure branch status is current.\n - **Read Protected Branches**: Reads the list of branches that should not be cleaned from Git config (see \"Configuration\" below).\n - **Determine Base**: Uses `--base` parameter or auto-detected `main`/`master` as comparison baseline.\n\n2. **Analysis and Identification (Find)**\n - **Merged Branches**: Find local (and remote if `--remote` is added) branches fully merged to `--base`.\n - **Stale Branches**: If `--stale <days>` is specified, find branches with last commit N days ago.\n - **Exclude Protected Branches**: Remove all configured protected branches from cleanup list.\n\n3. **Report and Preview (Report)**\n - Clearly list \"merged branches to be deleted\" and \"stale branches to be deleted\".\n - Without `--yes` parameter, **command ends here**, waiting for user confirmation to re-execute (without `--dry-run`).\n\n4. **Execute Cleanup (Execute)**\n - **Only executed without `--dry-run` and after user confirmation** (or with `--yes`).\n - Delete identified branches one by one, unless user chooses to skip in interactive confirmation.\n - Local: `git branch -d <branch>`; Remote: `git push origin --delete <branch>`.\n - If `--force` is specified, local deletion uses `git branch -D <branch>`.\n\n---\n\n## Configuration (Configure Once, Use Forever)\n\nTo prevent accidental deletion of important branches (e.g., `develop`, `release/*`), add protection rules to the repository's Git config. The command reads them automatically.\n\n```bash\n# Protect develop branch\ngit config --add branch.cleanup.protected develop\n\n# Protect all branches starting with release/ (wildcard)\ngit config --add branch.cleanup.protected 'release/*'\n\n# View all configured protected branches\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **Prioritize `--dry-run`**: Develop the habit of previewing before executing.\n- **Leverage `--base`**: When maintaining long-term `release` branches, use it to clean `feature` or `hotfix` branches merged to that release.\n- **Careful with `--force`**: Don't force delete unless you're 100% certain an unmerged branch is useless.\n- **Team Collaboration**: Notify the team channel before cleaning shared remote branches.\n- **Regular Runs**: Run monthly or quarterly to keep the repository clean.\n\n---\n\n## Why This Version Is Better\n\n- ✅ **Safer**: Default read-only preview with configurable protected branch list.\n- ✅ **More Flexible**: Supports custom base branches, perfectly fits `release` / `develop` workflows.\n- ✅ **More Compatible**: Avoids commands with inconsistent behavior across systems like `date -d`.\n- ✅ **More Intuitive**: Condenses complex 16-step checklist into a single command with safety options.\n- ✅ **Consistent Style**: Shares similar parameter design and documentation structure with `/commit` command.\n\n<!-- File: templates/skills/en/git-commit/SKILL.md (Tokens: ~2161 | Category: anthropic-skill) -->\n---\nname: git-commit\ndescription: Analyze changes with Git only and auto-generate conventional commit messages with optional emoji; suggests splitting commits when needed, runs local Git hooks by default (use --no-verify to skip)\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\nThis command works **without any package manager/build tools**, using only **Git** to:\n\n- Read changes (staged/unstaged)\n- Determine if changes should be **split into multiple commits**\n- Generate **Conventional Commits** style messages with optional emoji for each commit\n- Execute `git add` and `git commit` as needed (runs local Git hooks by default; use `--no-verify` to skip)\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`: Skip local Git hooks (`pre-commit`/`commit-msg` etc.).\n- `--all`: When staging area is empty, automatically `git add -A` to include all changes in the commit.\n- `--amend`: **Amend** the last commit without creating a new one (preserves author and timestamp unless local Git config specifies otherwise).\n- `--signoff`: Add `Signed-off-by` line (use when following DCO process).\n- `--emoji`: Include emoji prefix in commit message (omit for plain text).\n- `--scope <scope>`: Specify commit scope (e.g., `ui`, `docs`, `api`), written to message header.\n- `--type <type>`: Force commit type (e.g., `feat`, `fix`, `docs`), overrides automatic detection.\n\n> Note: If the framework doesn't support interactive confirmation, enable `confirm: true` in front-matter to avoid mistakes.\n\n---\n\n## What This Command Does\n\n1. **Repository/Branch Validation**\n - Check if in a Git repository using `git rev-parse --is-inside-work-tree`.\n - Read current branch/HEAD status; if in rebase/merge conflict state, prompt to resolve conflicts first.\n\n2. **Change Detection**\n - Get staged and unstaged changes using `git status --porcelain` and `git diff`.\n - If staged files = 0:\n - If `--all` is passed → Execute `git add -A`.\n - Otherwise prompt choice: continue analyzing unstaged changes for **suggestions**, or cancel to manually group staging.\n\n3. **Split Suggestions (Split Heuristics)**\n - Cluster by **concerns**, **file modes**, **change types** (e.g., source code vs docs/tests; different directories/packages; additions vs deletions).\n - If **multiple independent changesets** or large diff detected (e.g., > 300 lines / across multiple top-level directories), suggest splitting commits with pathspecs for each group (for subsequent `git add <paths>`).\n\n4. **Commit Message Generation (Conventional with Optional Emoji)**\n - Auto-infer `type` (`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert`...) and optional `scope`.\n - Generate message header: `[<emoji>] <type>(<scope>)?: <subject>` (first line ≤ 72 chars, imperative mood, emoji included only with `--emoji` flag).\n - Generate message body:\n - Must have a blank line after the subject.\n - Use list format, each item starts with `-`.\n - Each item **must use imperative verb-first sentences** (e.g., \"add…\", \"fix…\", \"update…\").\n - **Colon-separated formats are prohibited** (e.g., ~~\"Feature: description\"~~, ~~\"Impl: content\"~~).\n - Describe the motivation, implementation details, or impact scope (3 items or fewer recommended).\n - Generate message footer (if any):\n - Must have a blank line after the Body.\n - **BREAKING CHANGE**: If there are breaking changes, must include `BREAKING CHANGE: <description>`, or add exclamation mark after type (e.g., `feat!:`).\n - Other footers use git trailer format (e.g., `Closes #123`, `Refs: #456`, `Reviewed-by: Name`).\n - Select message language to match the predominant language in Git history. Inspect recent commit subjects (e.g., `git log -n 50 --pretty=%s`) to decide Chinese vs English; if unclear, fall back to the repository's primary locale or English.\n - Write draft to `.git/COMMIT_EDITMSG` for use with `git commit`.\n\n5. **Execute Commit**\n - Single commit scenario: `git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - Multiple commit scenario (if split accepted): Provide clear instructions for `git add <paths> && git commit ...` per group; execute sequentially if allowed.\n\n6. **Safe Rollback**\n - If mistakenly staged, use `git restore --staged <paths>` to unstage (command provides instructions, doesn't modify file contents).\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**: One commit does one thing, easier to trace and review.\n- **Group before committing**: Split by directory/module/feature.\n- **Clear subject**: First line ≤ 72 chars, imperative mood.\n- **Body with context**: Explain motivation, solution, and impact scope (colon-separated formats prohibited).\n- **Follow Conventional Commits**: `<type>(<scope>): <subject>`.\n\n---\n\n## Type to Emoji Mapping (When --emoji is Used)\n\n- ✨ `feat`: New feature\n- 🐛 `fix`: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)\n- 📝 `docs`: Documentation and comments\n- 🎨 `style`: Code style/formatting (no semantic changes)\n- ♻️ `refactor`: Refactoring (no new features, no bug fixes)\n- ⚡️ `perf`: Performance improvements\n- ✅ `test`: Add/fix tests, snapshots\n- 🔧 `chore`: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)\n- 👷 `ci`: CI/CD configuration and scripts\n- ⏪️ `revert`: Revert commits\n- 💥 `feat`: Breaking changes (explained in `BREAKING CHANGE:` section)\n\n> If `--type`/`--scope` is passed, it will **override** auto-detection.\n> Emoji is only included when `--emoji` flag is specified.\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **Different concerns**: Unrelated feature/module changes should be split.\n2. **Different types**: Don't mix `feat`, `fix`, `refactor` in the same commit.\n3. **File modes**: Source code vs docs/tests/configs should be grouped separately.\n4. **Size threshold**: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.\n5. **Revertability**: Ensure each commit can be independently reverted.\n\n---\n\n## Examples\n\n**Good (with --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (without --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (with Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (with BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ← (if your repo has hook errors)\n```\n\n---\n\n## Important Notes\n\n- **Git only**: No package manager/build commands (`pnpm`/`npm`/`yarn` etc.).\n- **Respects hooks**: Executes local Git hooks by default; use `--no-verify` to skip.\n- **No source code changes**: Command only reads/writes `.git/COMMIT_EDITMSG` and staging area; doesn't directly edit working directory files.\n- **Safety prompts**: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.\n- **Auditable and controllable**: If `confirm: true` is enabled, each actual `git add`/`git commit` step requires confirmation.\n\n<!-- File: templates/skills/en/git-rollback/SKILL.md (Tokens: ~989 | Category: anthropic-skill) -->\n---\nname: git-rollback\ndescription: Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**Purpose**: Safely and visually rollback a specified branch to an older version.\nDefaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.\n\n---\n\n## Usage\n\n```bash\n# Pure interactive: list branches → select branch → list recent 20 versions → select target → choose reset or revert → confirm\n/git-rollback\n\n# Specify branch, other interactive\n/git-rollback --branch feature/calculator\n\n# Specify branch and target commit, execute with hard-reset in one go (dangerous)\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# Generate revert commit only (non-destructive rollback), preview\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| Option | Description |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| `--branch <branch>` | Branch to rollback; interactively selected if omitted. |\n| `--target <rev>` | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |\n| `--mode reset\\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default. |\n| `--depth <n>` | List recent n versions in interactive mode (default 20). |\n| `--dry-run` | **Enabled by default**, only preview commands to be executed. |\n| `--yes` | Skip all confirmations and execute directly, suitable for CI/CD scripts. |\n\n---\n\n## Interactive Flow\n\n1. **Sync remote** → `git fetch --all --prune`\n2. **List branches** → `git branch -a` (local + remote, filter protected branches)\n3. **Select branch** → User input or parameter\n4. **List versions** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **Select target** → User inputs commit hash / tag\n6. **Select mode** → `reset` or `revert`\n7. **Final confirmation** (unless `--yes`)\n8. **Execute rollback**\n - `reset`: `git switch <branch> && git reset --hard <target>`\n - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)\n\n---\n\n## Safety Guards\n\n- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.\n- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.\n- **--dry-run enabled by default**: Prevents accidental operations.\n- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.\n\n---\n\n## Use Case Examples\n\n| Scenario | Command Example |\n| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |\n| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| Research historical bugs, guide newcomers through branch history | `/git-rollback` (full interactive, dry-run) |\n\n---\n\n## Notes\n\n1. **reset vs revert**\n - **reset** changes history, requires force push and may affect other collaborators, use with caution.\n - **revert** is safer, generates new commits preserving history, but adds one more record.\n2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.\n3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.\n\n---\n\n<!-- File: templates/skills/en/git-worktree/SKILL.md (Tokens: ~2290 | Category: anthropic-skill) -->\n---\nname: git-worktree\ndescription: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\nManage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.\n\nExecute commands directly and provide concise results.\n\n---\n\n## Usage\n\n```bash\n# Basic operations\n/git-worktree add <path> # create new branch named <path> from main/master\n/git-worktree add <path> -b <branch> # create new branch with specified name\n/git-worktree add <path> -o # create and open directly in IDE\n/git-worktree list # show all worktree status\n/git-worktree remove <path> # remove specified worktree\n/git-worktree prune # clean invalid worktree references\n\n# Content migration\n/git-worktree migrate <target> --from <source> # migrate uncommitted content\n/git-worktree migrate <target> --stash # migrate stash content\n```\n\n### Options\n\n| Option | Description |\n| ------------------ | ------------------------------------------------------ |\n| `add [<path>]` | Add new worktree in `../.zcf/project-name/<path>` |\n| `migrate <target>` | Migrate content to specified worktree |\n| `list` | List all worktrees and their status |\n| `remove <path>` | Remove worktree at specified path |\n| `prune` | Clean invalid worktree references |\n| `-b <branch>` | Create new branch and checkout to worktree |\n| `-o, --open` | Open directly in IDE after creation (skip prompt) |\n| `--from <source>` | Specify migration source path (migrate only) |\n| `--stash` | Migrate current stash content (migrate only) |\n| `--track` | Set new branch to track corresponding remote branch |\n| `--guess-remote` | Auto guess remote branch for tracking |\n| `--detach` | Create detached HEAD worktree |\n| `--checkout` | Checkout immediately after creation (default behavior) |\n| `--lock` | Lock worktree after creation |\n\n---\n\n## What This Command Does\n\n1. **Environment Check**\n - Verify Git repository using `git rev-parse --is-inside-work-tree`\n - Detect whether in main repo or existing worktree for smart path calculation\n\n2. **Smart Path Management**\n - Auto-calculate project name from main repository path using worktree detection\n - Create worktrees in structured `../.zcf/project-name/<path>` directory\n - Handle both main repo and worktree execution contexts correctly\n\n```bash\n# Core path calculation logic for worktree detection\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # Check if in worktree\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # In worktree, derive main repo path from git-common-dir\n dirname \"$git_common_dir\"\n else\n # In main repository\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# Always use absolute path to prevent nesting issues\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.\n\n3. **Worktree Operations**\n - **add**: Create new worktree with smart branch/path defaults\n - **list**: Display all worktrees with branches and status\n - **remove**: Safely remove worktree and clean references\n - **prune**: Clean orphaned worktree records\n\n4. **Smart Defaults**\n - **Branch creation**: When no `-b` specified, create new branch using path name\n - **Base branch**: New branches created from main/master branch\n - **Path resolution**: Use branch name as path when unspecified\n - **IDE integration**: Auto-detect and prompt for IDE opening\n\n5. **Content Migration**\n - Migrate uncommitted changes between worktrees\n - Apply stash content to target worktree\n - Safety checks to prevent conflicts\n\n6. **Safety Features**\n - **Path conflict prevention**: Check for existing directories before creation\n - **Branch checkout validation**: Ensure branches aren't already in use\n - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree\n - **Auto-cleanup on removal**: Clean both directory and git references\n - **Clear status reporting**: Display worktree locations and branch status\n\n7. **Environment File Handling**\n - **Auto-detection**: Scan `.gitignore` for environment variable file patterns\n - **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`\n - **Exclusion logic**: Skip `.env.example` and other template files\n - **Permission preservation**: Maintain original file permissions and timestamps\n - **User feedback**: Provide clear status on copied environment files\n\n```bash\n# Environment file copying implementation\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # Check if .gitignore exists\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # Detect .env file\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ Copied .env\"\n ((copied_count++))\n fi\n \n # Detect .env.* pattern files (excluding .env.example)\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ Copied $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 Copied $copied_count environment file(s) from .gitignore\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE Integration\n\n- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **Smart prompting**: Ask to open in IDE after worktree creation\n- **Direct open**: Use `-o` flag to skip prompt and open immediately\n- **Custom configuration**: Configurable via git config\n\n### Content Migration System\n\n```bash\n# Migrate uncommitted changes\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# Migrate stash content\n/git-worktree migrate feature-ui --stash\n```\n\n**Migration Flow**:\n\n1. Verify source has uncommitted content\n2. Ensure target worktree is clean\n3. Show changes to be migrated\n4. Execute safe migration using git commands\n5. Confirm results and suggest next steps\n\n---\n\n## Examples\n\n```bash\n# Basic usage\n/git-worktree add feature-ui # create new branch 'feature-ui' from main/master\n/git-worktree add feature-ui -b my-feature # create new branch 'my-feature' with path 'feature-ui'\n/git-worktree add feature-ui -o # create and open in IDE directly\n\n# Content migration scenarios\n/git-worktree add feature-ui -b feature/new-ui # create new feature worktree\n/git-worktree migrate feature-ui --from main # migrate uncommitted changes\n/git-worktree migrate hotfix --stash # migrate stash content\n\n# Management operations\n/git-worktree list # view all worktrees\n/git-worktree remove feature-ui # remove unneeded worktree\n/git-worktree prune # clean invalid references\n```\n\n**Example Output**:\n\n```\n✅ Worktree created at ../.zcf/project-name/feature-ui\n✅ Copied .env\n✅ Copied .env.local\n📋 Copied 2 environment file(s) from .gitignore\n🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y\n🚀 Opening ../.zcf/project-name/feature-ui in VS Code...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # main project\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree management\n └── your-project/ # project worktrees\n ├── feature-ui/ # feature branch\n ├── hotfix/ # hotfix branch\n └── debug/ # debug worktree\n```\n\n---\n\n## Configuration\n\n### IDE Configuration\n\n- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim\n- Configurable via git config for custom IDEs\n- Auto-detection with priority-based selection\n\n### Custom IDE Setup\n\n```bash\n# Configure custom IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# Control auto-detection\ngit config worktree.ide.autodetect true # default\n```\n\n---\n\n## Notes\n\n- **Performance**: Worktrees share `.git` directory, saving disk space\n- **Safety**: Path conflict prevention and branch checkout validation\n- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits\n- **IDE requirement**: Command-line tools must be in PATH\n- **Cross-platform**: Supports Windows, macOS, Linux\n- **Environment files**: Automatically copies environment files listed in `.gitignore` to new worktrees\n- **File exclusions**: Template files like `.env.example` are preserved in main repo only\n\n---\n\n<!-- File: templates/skills/en/init-project/SKILL.md (Tokens: ~642 | Category: anthropic-skill) -->\n---\nname: init-project\ndescription: Initialize project AI context, generate/update root-level and module-level CLAUDE.md indexes\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## Usage\n\n`/init-project <PROJECT_SUMMARY_OR_NAME>`\n\n## Objective\n\nInitialize project AI context using a mixed strategy of \"concise at root + detailed at module level\":\n\n- Generate/update `CLAUDE.md` at repository root (high-level vision, architecture overview, module index, global standards).\n- Generate/update local `CLAUDE.md` in identified module directories (interfaces, dependencies, entry points, tests, key files, etc.).\n- ✨ **For improved readability, automatically generate Mermaid structure diagrams in the root `CLAUDE.md` and add navigation breadcrumbs to each module `CLAUDE.md`**.\n\n## Orchestration Instructions\n\n**Step 1**: Call the `get-current-datetime` sub-agent to obtain the current timestamp.\n\n**Step 2**: Call the `init-architect` sub-agent once, with input:\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (timestamp from step 1)\n\n## Execution Strategy (Agent adapts automatically, no user parameters needed)\n\n- **Stage A: Repository Census (Lightweight)**\n Quickly count files and directories, identify module roots (package.json, pyproject.toml, go.mod, apps/_, packages/_, services/\\*, etc.).\n- **Stage B: Module Priority Scanning (Medium)**\n For each module, perform targeted reading and sampling of \"entry/interfaces/dependencies/tests/data models/quality tools\".\n- **Stage C: Deep Supplementation (As Needed)**\n If repository is small or module scale is small, expand reading scope; if large, perform batch supplemental scanning on high-risk/high-value paths.\n- **Coverage Measurement and Resumability**\n 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.\n\n## Security and Boundaries\n\n- Only read/write documentation and indexes, do not modify source code.\n- Ignore common generated artifacts and binary large files by default.\n- Print \"summary\" in main dialog, write full content to repository.\n\n## Output Requirements\n\n- Print \"Initialization Result Summary\" in main dialog, including:\n - Whether root-level `CLAUDE.md` was created/updated, major section overview.\n - Number of identified modules and their path list.\n - Generation/update status of each module's `CLAUDE.md`.\n - ✨ **Explicitly mention \"Generated Mermaid structure diagram\" and \"Added navigation breadcrumbs for N modules\"**.\n - Coverage and major gaps.\n - If not fully read: explain \"why stopped here\" and list **recommended next steps** (e.g., \"suggest priority supplemental scanning: packages/auth/src/controllers\").\n\n<!-- File: templates/skills/en/workflow/SKILL.md (Tokens: ~2067 | Category: anthropic-skill) -->\n---\nname: workflow\ndescription: 'Professional AI programming assistant with structured workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) for developers'\ndisable-model-invocation: true\n---\n\n# Workflow - Professional Development Assistant\n\nExecute structured development workflow with quality gates and MCP service integration.\n\n## Usage\n\n```bash\n/workflow <TASK_DESCRIPTION>\n```\n\n## Context\n\n- Task to develop: $ARGUMENTS\n- Structured 6-phase workflow with quality gates\n- Professional developer-focused interaction\n- MCP service integration for enhanced capabilities\n\n## Your Role\n\nYou are a professional AI programming assistant following a structured core workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) to assist users. Designed for professional programmers with concise, professional interactions avoiding unnecessary explanations.\n\n## Communication Guidelines\n\n1. Responses start with mode tag `[Mode: X]`, initially `[Mode: Research]`\n2. Core workflow strictly follows `Research -> Ideate -> Plan -> Execute -> Optimize -> Review` sequence, users can command jumps\n\n## Core Workflow Details\n\n### 1. `[Mode: Research]` - Requirement Understanding\n\n- Analyze and understand user requirements\n- Evaluate requirement completeness (0-10 score), actively request key information when below 7\n- Gather necessary context and constraints\n- Identify key objectives and success criteria\n\n### 2. `[Mode: Ideate]` - Solution Design\n\n- Provide at least two feasible solutions with evaluation (e.g., `Solution 1: Description`)\n- Compare pros/cons of each approach\n- Recommend optimal solution based on requirements\n\n### 3. `[Mode: Plan]` - Detailed Planning\n\n- Break down selected solution into detailed, ordered, executable step list\n- Include atomic operations: files, functions/classes, logic overview\n- Define expected results for each step\n- Use `Context7` for new library queries\n- Do not write complete code at this stage\n- Request user approval after completion\n\n### 4. `[Mode: Execute]` - Implementation\n\n- Store plan summary (with context and plan) in project root directory `.zcf/plan/current/task-name.md`\n- Must have user approval before execution\n- Strictly follow the plan for coding implementation\n- Request user feedback after key steps and completion\n\n### 5. `[Mode: Optimize]` - Code Optimization\n\n- Automatically enter this mode after `[Mode: Execute]` completion\n- Automatically check and analyze implemented code (only code generated in current conversation)\n- Focus on redundant, inefficient, garbage code\n- Provide specific optimization suggestions (with reasons and expected benefits)\n- Execute optimization after user confirmation\n\n### 6. `[Mode: Review]` - Quality Assessment\n\n- Evaluate execution results against the plan\n- Report issues and suggestions\n- Request user confirmation after completion\n\n## Timestamp Acquisition Rules\n\nDuring workflow execution, any scenario requiring current timestamp must obtain accurate time via bash command. Guessing or fabricating time is prohibited.\n\nBasic Commands:\n- Default format: `date +'%Y-%m-%d %H:%M:%S'`\n- Filename format: `date +'%Y-%m-%d_%H%M%S'`\n- Readable format: `date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO format: `date +'%Y-%m-%dT%H:%M:%S%z'`\n\nTypical Use Cases:\n- Updating timestamp fields in documents\n- Naming task plan documents during archiving (when moving from `.zcf/plan/current/` to `.zcf/plan/history/`)\n- Any other scenario requiring current time recording\n\n## Interactive Feedback & MCP Services\n\n### Interactive Feedback Rules\n\n1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, must request user confirmation\n2. When receiving user feedback, if feedback content is not empty, must request user confirmation again and adjust behavior based on feedback\n3. Only when user explicitly indicates \"end\" or \"no more interaction needed\" can stop requesting user confirmation, process is considered complete\n4. Unless receiving termination instructions, all steps must repeatedly request user confirmation\n5. Before completing tasks, must request user confirmation and ask for user feedback\n\n---\n\n## Execute Workflow\n\n**Task Description**: $ARGUMENTS\n\nStarting structured development workflow with quality gates...\n\n### 🔍 Phase 1: Research & Analysis\n\n[Mode: Research] - Understanding requirements and gathering context:\n\n#### Requirement Completeness Scoring (0-10 points)\n\nScoring Dimensions:\n\n- **Goal Clarity** (0-3 points): Are task objectives clear and specific, what problem to solve?\n- **Expected Results** (0-3 points): Are success criteria and deliverables clearly defined?\n- **Scope Boundaries** (0-2 points): Are task scope and boundaries clear?\n- **Constraints** (0-2 points): Are time, performance, business limits specified?\n\nNote: Technical stack, framework versions will be identified from project automatically, not included in scoring\n\n**Scoring Rules**:\n\n- 9-10 points: Requirements very complete, can proceed directly\n- 7-8 points: Requirements basically complete, suggest adding minor details\n- 5-6 points: Requirements have significant gaps, must supplement key information\n- 0-4 points: Requirements too vague, needs redescription\n\n**When score is below 7, proactively ask supplementary questions**:\n\n- Identify missing key information dimensions\n- Ask 1-2 specific questions for each missing dimension\n- Provide examples to help users understand needed information\n- Re-score after user supplements information\n\n**Scoring Example**:\n\n```\nUser Request: \"Help me optimize code\"\nScoring Analysis:\n- Goal Clarity: 0/3 points (doesn't specify what code or what problem)\n- Expected Results: 0/3 points (no success criteria or expected effect defined)\n- Scope Boundaries: 1/2 points (only knows code optimization, but scope unclear)\n- Constraints: 0/2 points (no performance metrics or time limits)\nTotal Score: 1/10 - Requires significant information\n\nQuestions to Ask:\n1. Which file or module's code do you want to optimize?\n2. What specific problem needs optimization?\n3. What effect do you expect after optimization (e.g., response time improvement, code reduction)?\n4. Are there specific performance metrics or time requirements?\n```\n\n**Common Supplementary Question Templates**:\n\n- Goal: \"What specific functionality/effect do you want?\" \"What's the current problem?\"\n- Results: \"How to determine task success?\" \"What's the expected output/effect?\"\n- Scope: \"Which specific files/modules to handle?\" \"What should be excluded?\"\n- Constraints: \"What are the time requirements?\" \"Any business limitations or performance requirements?\"\n\n**Auto-detected Project Information** (no need to ask):\n\n- Tech stack (from AGENTS.md, CLAUDE.md, package.json, requirements.txt, etc.)\n- Framework versions (from AGENTS.md, CLAUDE.md, config files)\n- Project structure (from file system)\n- Existing code conventions (from AGENTS.md, CLAUDE.md, config files and existing code)\n- Development commands (from AGENTS.md, CLAUDE.md, such as build, test, typecheck)\n\n#### Execution Steps\n\n- Analyze task requirements and constraints\n- Perform requirement completeness scoring (show specific scores)\n- Identify key objectives and success criteria\n- Gather necessary technical context\n- Use MCP services for additional information if needed\n\n### 💡 Phase 2: Solution Ideation\n\n[Mode: Ideate] - Designing solution approaches:\n\n- Generate multiple feasible solutions\n- Evaluate pros and cons of each approach\n- Provide detailed comparison and recommendation\n- Consider technical constraints and best practices\n- Request user approval before proceeding\n\n### 📋 Phase 3: Detailed Planning\n\n[Mode: Plan] - Creating execution roadmap:\n\n- Break down solution into atomic, executable steps\n- Define file structure, functions/classes, and logic overview\n- Specify expected results for each step\n- Query new libraries using Context7 if needed\n- Request user approval before proceeding\n\n### ⚡ Phase 4: Implementation\n\n[Mode: Execute] - Code development:\n\n- Store execution plan in project root directory `.zcf/plan/current/task-name.md`\n- Implement according to approved plan\n- Follow development best practices\n- Add usage methods before import statements (critical rule)\n- Request feedback at key milestones\n\n### 🚀 Phase 5: Code Optimization\n\n[Mode: Optimize] - Quality improvement:\n\n- Automatically analyze implemented code\n- Identify redundant, inefficient, or problematic code\n- Provide specific optimization recommendations\n- Execute improvements after user confirmation\n\n### ✅ Phase 6: Quality Review\n\n[Mode: Review] - Final assessment:\n\n- Compare results against original plan\n- Identify any remaining issues or improvements\n- Provide completion summary and recommendations\n- Request final user confirmation\n- After task completion, move plan file from `.zcf/plan/current/` to `.zcf/plan/history/` for archiving\n- Rename to `[Finish Time]task-name.md` during archiving for tracking, Finish Time format is `YYYY-MM-DD_HHMMSS`\n\n## Expected Output Structure\n\n```\nproject/ # Project root directory\n├── .zcf/\n│ └── plan/\n│ ├── current/ # Current ongoing tasks\n│ │ └── task-name.md # Execution plan and context\n│ └── history/ # Completed historical tasks\n│ └── [Finish Time]task-name.md # Archived task records\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**Begin execution with the provided task description and report progress after each phase completion.**\n\n<!-- File: templates/skills/zh-CN/bmad-init/SKILL.md (Tokens: ~3006 | Category: anthropic-skill) -->\n---\nname: bmad-init\ndescription: 在项目中初始化或更新 BMad-Method (V6)\ndisable-model-invocation: true\n---\n\n# /bmad-init 命令\n\n此命令在您的项目中初始化或更新 BMad-Method (V6)。\n\n## 当调用此命令时：\n\n1. 检查 `_bmad/` 目录是否存在，判断 BMad V6 是否已安装\n2. 检查是否存在旧版 V4 安装（`.bmad-core` 或 `.bmad-method` 目录）\n3. 新安装执行：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n4. 已安装则执行：`npx bmad-method install --directory . --action quick-update --yes`\n5. 修复安装器 bug：将 `{output_folder}` 重命名为 `_bmad-output`（Beta 已知问题）\n6. 自动更新 `.gitignore`（移除 V4 条目，添加 V6 条目）\n7. 显示安装结果并提示用户后续操作\n\n## 实现\n\n```javascript\nconst { execSync } = require('node:child_process')\nconst fs = require('node:fs')\nconst path = require('node:path')\n\n// 需要从 .gitignore 清理的旧条目\nconst LEGACY_GITIGNORE_ENTRIES = [\n '.bmad-core',\n '.bmad-method',\n '.claude/commands/BMad',\n '{output_folder}', // v6.0.0-Beta.8 bug 产物\n]\n\n// V6 新版 .gitignore 条目\nconst V6_GITIGNORE_ENTRIES = [\n '_bmad/',\n '_bmad-output/',\n]\n\n// 修复安装器 bug: {output_folder} 未解析为 _bmad-output (v6.0.0-Beta.8)\nfunction fixOutputFolderBug(cwd) {\n const buggyPath = path.join(cwd, '{output_folder}')\n const correctPath = path.join(cwd, '_bmad-output')\n\n if (!fs.existsSync(buggyPath)) return false\n\n if (!fs.existsSync(correctPath)) {\n // _bmad-output 不存在，直接重命名\n fs.renameSync(buggyPath, correctPath)\n console.log(' ✅ {output_folder} → _bmad-output/ (重命名)')\n } else {\n // _bmad-output 已存在，合并子目录后删除\n const entries = fs.readdirSync(buggyPath, { withFileTypes: true })\n for (const entry of entries) {\n const src = path.join(buggyPath, entry.name)\n const dest = path.join(correctPath, entry.name)\n if (!fs.existsSync(dest)) {\n fs.renameSync(src, dest)\n console.log(` ✅ 移动 ${entry.name} → _bmad-output/`)\n }\n }\n fs.rmSync(buggyPath, { recursive: true, force: true })\n console.log(' ✅ 已删除多余的 {output_folder}/')\n }\n return true\n}\n\nfunction updateGitignore(cwd) {\n const gitignorePath = path.join(cwd, '.gitignore')\n let content = ''\n let exists = false\n\n if (fs.existsSync(gitignorePath)) {\n content = fs.readFileSync(gitignorePath, 'utf8')\n exists = true\n }\n\n const lines = content.split('\\n')\n let changed = false\n\n // 移除 V4 旧条目\n const filtered = lines.filter(line => {\n const trimmed = line.trim()\n const isLegacy = LEGACY_GITIGNORE_ENTRIES.some(entry =>\n trimmed === entry || trimmed === entry + '/' || trimmed === '/' + entry\n )\n if (isLegacy) {\n console.log(` 🗑️ 移除旧条目: ${trimmed}`)\n changed = true\n }\n return !isLegacy\n })\n\n // 添加 V6 新条目\n const newEntries = []\n for (const entry of V6_GITIGNORE_ENTRIES) {\n const entryBase = entry.replace(/\\/$/, '')\n const alreadyExists = filtered.some(line => {\n const trimmed = line.trim()\n return trimmed === entry || trimmed === entryBase || trimmed === '/' + entryBase\n })\n if (!alreadyExists) {\n newEntries.push(entry)\n console.log(` ✅ 添加新条目: ${entry}`)\n changed = true\n }\n }\n\n if (!changed) {\n console.log(' ℹ️ .gitignore 已是最新，无需更新')\n return\n }\n\n // 构建新内容\n let result = filtered.join('\\n')\n\n if (newEntries.length > 0) {\n // 确保末尾有换行，然后添加 BMad 区块\n if (result.length > 0 && !result.endsWith('\\n')) {\n result += '\\n'\n }\n result += '\\n# BMad Method V6\\n'\n result += newEntries.join('\\n') + '\\n'\n }\n\n fs.writeFileSync(gitignorePath, result, 'utf8')\n console.log(` 📝 .gitignore 已${exists ? '更新' : '创建'}`)\n}\n\nasync function initBmad() {\n const cwd = process.cwd()\n const bmadV6Path = path.join(cwd, '_bmad')\n const legacyCorePath = path.join(cwd, '.bmad-core')\n const legacyMethodPath = path.join(cwd, '.bmad-method')\n\n // 检查旧版 V4 安装\n const hasLegacyCore = fs.existsSync(legacyCorePath)\n const hasLegacyMethod = fs.existsSync(legacyMethodPath)\n\n if (hasLegacyCore || hasLegacyMethod) {\n console.log('⚠️ 检测到旧版 BMad V4 安装：')\n if (hasLegacyCore) console.log(' • .bmad-core/ (V4 核心目录)')\n if (hasLegacyMethod) console.log(' • .bmad-method/ (V4 方法目录)')\n console.log('')\n console.log('📌 V6 安装器会自动处理旧版迁移，请在安装过程中按提示操作。')\n console.log(' 详情参考：https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/upgrade-to-v6')\n console.log('')\n }\n\n // 检查 V6 是否已安装\n const hasV6 = fs.existsSync(bmadV6Path)\n\n // 构建非交互式安装命令\n let installCmd\n if (hasV6) {\n console.log('🔄 检测到已有 BMad V6 安装，将执行快速更新...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--action quick-update',\n '--yes',\n ].join(' ')\n } else {\n console.log('🚀 正在初始化 BMad-Method V6...')\n console.log('')\n installCmd = [\n 'npx bmad-method install',\n '--directory .',\n '--modules bmm',\n '--tools claude-code',\n '--communication-language Chinese',\n '--document-output-language Chinese',\n '--yes',\n ].join(' ')\n }\n\n // 执行安装\n try {\n console.log(`📋 执行: ${installCmd}`)\n console.log('')\n execSync(installCmd, {\n stdio: 'inherit',\n cwd: cwd,\n shell: true\n })\n\n console.log('')\n console.log('✅ BMad-Method V6 安装/更新完成！')\n console.log('')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('📌 重要提示：请重启 AI IDE 以加载 BMad 扩展')\n console.log('═══════════════════════════════════════════════════════════════')\n console.log('')\n // 修复 {output_folder} bug (v6.0.0-Beta.8)\n console.log('🔧 检查安装器已知问题...')\n try {\n const fixed = fixOutputFolderBug(cwd)\n if (!fixed) console.log(' ℹ️ 无需修复')\n } catch (err) {\n console.log(` ⚠️ 修复 {output_folder} 失败: ${err.message}`)\n console.log(' 请手动将 {output_folder}/ 重命名为 _bmad-output/')\n }\n console.log('')\n\n console.log('📂 V6 目录结构：')\n console.log(' • _bmad/ — agents、workflows、tasks 和配置')\n console.log(' • _bmad-output/ — 生成的工件输出目录')\n console.log('')\n\n // 自动更新 .gitignore\n console.log('🔧 更新 .gitignore...')\n try {\n updateGitignore(cwd)\n } catch (err) {\n console.log(' ⚠️ 自动更新 .gitignore 失败，请手动添加 _bmad/ 和 _bmad-output/')\n }\n console.log('')\n console.log('🚀 快速开始：')\n console.log(' 1. 重启 AI IDE')\n console.log(' 2. 运行 /bmad-help 获取引导和下一步建议')\n console.log(' 3. 输入 /bmad 并使用自动补全浏览可用命令')\n console.log('')\n console.log('💡 常用工作流：')\n console.log(' • /bmad-help — 交互式帮助')\n console.log(' • /bmad-bmm-create-prd — 创建产品需求文档')\n console.log(' • /bmad-bmm-create-architecture — 创建架构文档')\n console.log(' • /bmad-bmm-create-epics-and-stories — 创建史诗和用户故事')\n console.log(' • /bmad-bmm-sprint-planning — 初始化 Sprint 计划')\n console.log(' • /bmad-bmm-dev-story — 实现用户故事')\n\n // 清理旧版 V4 IDE 命令提醒\n const legacyClaudeAgents = path.join(cwd, '.claude', 'commands', 'BMad', 'agents')\n const legacyClaudeTasks = path.join(cwd, '.claude', 'commands', 'BMad', 'tasks')\n if (fs.existsSync(legacyClaudeAgents) || fs.existsSync(legacyClaudeTasks)) {\n console.log('')\n console.log('⚠️ 检测到旧版 V4 IDE 命令，建议手动删除：')\n if (fs.existsSync(legacyClaudeAgents)) console.log(' • .claude/commands/BMad/agents/')\n if (fs.existsSync(legacyClaudeTasks)) console.log(' • .claude/commands/BMad/tasks/')\n console.log(' 新的 V6 命令已安装在 .claude/commands/bmad/ 下')\n }\n }\n catch (error) {\n console.error('❌ 安装失败：', error.message)\n console.log('')\n console.log('🛠️ 手动安装指南：')\n console.log(' 1. 确保已安装 Node.js 20+')\n console.log(' 2. 非交互式安装：')\n console.log(' npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes')\n console.log(' 3. 快速更新已有安装：')\n console.log(' npx bmad-method install --directory . --action quick-update --yes')\n console.log(' 4. 或交互式安装：')\n console.log(' npx bmad-method install')\n console.log('')\n console.log('📖 详细文档：')\n console.log(' https://bmad-code-org.github.io/BMAD-METHOD/docs/how-to/install-bmad')\n }\n}\n\n// 执行初始化\ninitBmad()\n```\n\n## 用法\n\n只需在 Claude Code 中键入：\n\n```\n/bmad-init\n```\n\n此命令将：\n\n1. 检测现有安装状态（V6 / V4 旧版 / 未安装）\n2. 新安装：`npx bmad-method install --directory . --modules bmm --tools claude-code --communication-language Chinese --document-output-language Chinese --yes`\n3. 已安装：`npx bmad-method install --directory . --action quick-update --yes`\n4. 修复 `{output_folder}` → `_bmad-output` 安装器 bug\n5. 自动更新 `.gitignore`（清理旧条目，添加 V6 条目）\n6. 提供后续步骤建议\n\n<!-- File: templates/skills/zh-CN/feat/SKILL.md (Tokens: ~918 | Category: anthropic-skill) -->\n---\nname: feat\ndescription: '用于新增功能开发的命令，支持完整的开发流程和工具集成'\ndisable-model-invocation: true\n---\n\n$ARGUMENTS\n\n## 核心工作流程\n\n### 1. 输入分析与类型判断\n\n每次收到用户输入时，首先进行类型判断并明确告知用户：\n\n**判断标准：**\n\n- **需求规划类型**: 用户提出新功能需求、项目构想或需要制定计划\n\n- **讨论迭代类型**: 用户要求继续讨论、修改或完善已有规划\n\n- **执行实施类型**: 用户确认规划完成，要求开始具体实施工作\n\n### 2. 分类处理机制\n\n#### A. 需求规划处理\n\n**触发条件**: 识别为功能需求输入\n\n**执行动作**:\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 将文档存储至 `./.claude/plan` 目录，并以 plan/xxx.md 的格式命名\n\n- 包含：目标定义、功能分解、实施步骤、验收标准\n\n#### B. 讨论迭代处理\n\n**触发条件**: 用户要求继续讨论或修改规划\n\n**执行动作**:\n\n- 检索并分析上次生成的规划文件\n\n- 识别用户反馈和确认内容\n\n- 启用 Planner Agent\n\n- 生成详细的 markdown 规划文档\n\n- 建立一个新的文档，比如上一次是 plan/xxx.md，那么这次就是 plan/xxx-1.md，如果上一次是 plan/xxx-1.md，那么这次就是 plan/xxx-2.md，以此类推\n\n- 重新组织待实施任务优先级\n\n#### C. 执行实施处理\n\n**触发条件**: 用户确认规划完成，要求开始执行\n\n**执行动作**:\n\n- 按规划文档顺序启动任务执行\n\n- 每个子任务开始前进行任务类型识别\n\n- **前端任务特殊处理**:\n\n- 检查是否存在可用 UI 设计\n\n- 如无设计方案，must use UI-UX-Designer Agent\n\n- 完成 UI 设计后再进行开发实施\n\n### 3. 关键执行原则\n\n#### 强制响应要求\n\n- **每次交互必须首先说明**: \"我判断此次操作类型为：[具体类型]\"\n\n- 类型判断必须准确且明确传达给用户\n\n#### 任务执行规范\n\n- 严格按照文档化规划执行\n\n- 子任务启动前必须明确任务性质和依赖关系\n\n- 前端任务必须确保 UI 设计完整性\n\n#### 状态管理机制\n\n- 维护任务完成状态跟踪\n\n- 及时更新规划文档状态\n\n- 确保用户对进度的可见性\n\n## 质量保证要点\n\n1. **类型判断准确性**: 每次交互开始的类型识别必须准确\n\n2. **文档一致性**: 规划文档与实际执行保持同步\n\n3. **依赖关系管理**: 特别关注前端任务的 UI 设计依赖\n\n4. **用户沟通透明**: 所有判断和动作都要明确告知用户\n\n<!-- File: templates/skills/zh-CN/git-clean-branches/SKILL.md (Tokens: ~1477 | Category: anthropic-skill) -->\n---\nname: git-clean-branches\ndescription: 安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()\n---\n\n# Claude Command: Clean Branches\n\n该命令**安全地**识别并清理**已合并**或**长期未更新 (stale)** 的 Git 分支。\n默认以**只读预览 (`--dry-run`)** 模式运行，需明确指令才会执行删除操作。\n\n---\n\n## Usage\n\n```bash\n# [最安全] 预览将要清理的分支，不执行任何删除\n/git-cleanBranches --dry-run\n\n# 清理已合并到 main 且超过 90 天未动的本地分支 (需逐一确认)\n/git-cleanBranches --stale 90\n\n# 清理已合并到 release/v2.1 的本地与远程分支 (自动确认)\n/git-cleanBranches --base release/v2.1 --remote --yes\n\n# [危险] 强制删除一个未合并的本地分支\n/git-cleanBranches --force outdated-feature\n```\n\n### Options\n\n- `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。\n- `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。\n- `--remote`：同时清理远程已合并/过期的分支。\n- `--dry-run`：**默认行为**。仅列出将要删除的分支，不执行任何操作。\n- `--yes`：跳过逐一确认的步骤，直接删除所有已识别的分支（适合 CI/CD）。\n- `--force`：使用 `-D` 强制删除本地分支（即使未合并）。\n\n---\n\n## What This Command Does\n\n1. **配置与安全预检**\n - **更新信息**：自动执行 `git fetch --all --prune`，确保分支状态最新。\n - **读取保护分支**：从 Git 配置读取不应被清理的分支列表（见下文“Configuration”）。\n - **确定基准**：使用 `--base` 参数或自动识别的 `main`/`master` 作为比较基准。\n\n2. **分析识别（Find）**\n - **已合并分支**：找出已完全合并到 `--base` 的本地（及远程，如加 `--remote`）分支。\n - **过期分支**：如指定 `--stale <days>`，找出最后一次提交在 N 天前的分支。\n - **排除保护分支**：从待清理列表中移除所有已配置的保护分支。\n\n3. **报告预览（Report）**\n - 清晰列出“将要删除的已合并分支”与“将要删除的过期分支”。\n - 若无 `--yes` 参数，**命令到此结束**，等待用户确认后再次执行（不带 `--dry-run`）。\n\n4. **执行清理（Execute）**\n - **仅在不带 `--dry-run` 且用户确认后**（或带 `--yes`）执行。\n - 逐一删除已识别的分支，除非用户在交互式确认中选择跳过。\n - 本地用 `git branch -d <branch>`；远程用 `git push origin --delete <branch>`。\n - 若指定 `--force`，本地删除会改用 `git branch -D <branch>`。\n\n---\n\n## Configuration (一次配置，永久生效)\n\n为防止误删重要分支（如 `develop`, `release/*`），请在仓库的 Git 配置中添加保护规则。命令会自动读取。\n\n```bash\n# 保护 develop 分支\ngit config --add branch.cleanup.protected develop\n\n# 保护所有 release/ 开头的分支 (通配符)\ngit config --add branch.cleanup.protected 'release/*'\n\n# 查看所有已配置的保护分支\ngit config --get-all branch.cleanup.protected\n```\n\n---\n\n## Best Practices for Embedded Devs\n\n- **优先 `--dry-run`**：养成先预览再执行的习惯。\n- **活用 `--base`**：维护长期 `release` 分支时，用它来清理已合并到该 release 的 `feature` 或 `hotfix` 分支。\n- **谨慎 `--force`**：除非你百分百确定某个未合并分支是无用功，否则不要强制删除。\n- **团队协作**：在清理共享的远程分支前，先在团队频道通知一声。\n- **定期运行**：每月或每季度运行一次，保持仓库清爽。\n\n---\n\n## Why This Version Is Better\n\n- ✅ **更安全**：默认只读预览，且有可配置的保护分支列表。\n- ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。\n- ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。\n- ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。\n- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。\n\n<!-- File: templates/skills/zh-CN/git-commit/SKILL.md (Tokens: ~2821 | Category: anthropic-skill) -->\n---\nname: git-commit\ndescription: 仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过）\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)\n---\n\n# Claude Command: Commit (Git-only)\n\n该命令在**不依赖任何包管理器/构建工具**的前提下，仅通过 **Git**：\n\n- 读取改动（staged/unstaged）\n- 判断是否需要**拆分为多次提交**\n- 为每个提交生成 **Conventional Commits** 风格的信息（可选 emoji）\n- 按需执行 `git add` 与 `git commit`（默认运行本地 Git 钩子；可 `--no-verify` 跳过）\n\n---\n\n## Usage\n\n```bash\n/git-commit\n/git-commit --no-verify\n/git-commit --emoji\n/git-commit --all --signoff\n/git-commit --amend\n/git-commit --scope ui --type feat --emoji\n```\n\n### Options\n\n- `--no-verify`：跳过本地 Git 钩子（`pre-commit`/`commit-msg` 等）。\n- `--all`：当暂存区为空时，自动 `git add -A` 将所有改动纳入本次提交。\n- `--amend`：在不创建新提交的情况下**修补**上一次提交（保持提交作者与时间，除非本地 Git 配置另有指定）。\n- `--signoff`：附加 `Signed-off-by` 行（遵循 DCO 流程时使用）。\n- `--emoji`：在提交信息中包含 emoji 前缀（省略则使用纯文本）。\n- `--scope <scope>`：指定提交作用域（如 `ui`、`docs`、`api`），写入消息头部。\n- `--type <type>`：强制提交类型（如 `feat`、`fix`、`docs` 等），覆盖自动判断。\n\n> 注：如框架不支持交互式确认，可在 front-matter 中开启 `confirm: true` 以避免误操作。\n\n---\n\n## What This Command Does\n\n1. **仓库/分支校验**\n - 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库。\n - 读取当前分支/HEAD 状态；如处于 rebase/merge 冲突状态，先提示处理冲突后再继续。\n\n2. **改动检测**\n - 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动。\n - 若已暂存文件为 0：\n - 若传入 `--all` → 执行 `git add -A`。\n - 否则提示你选择：继续仅分析未暂存改动并给出**建议**，或取消命令后手动分组暂存。\n\n3. **拆分建议（Split Heuristics）**\n - 按**关注点**、**文件模式**、**改动类型**聚类（示例：源代码 vs 文档、测试；不同目录/包；新增 vs 删除）。\n - 若检测到**多组独立变更**或 diff 规模过大（如 > 300 行 / 跨多个顶级目录），建议拆分提交，并给出每一组的 pathspec（便于后续执行 `git add <paths>`）。\n\n4. **提交信息生成（Conventional 规范，可选 Emoji）**\n - 自动推断 `type`（`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert` …）与可选 `scope`。\n - 生成消息头：`[<emoji>] <type>(<scope>)?: <subject>`（首行 ≤ 72 字符，祈使语气，仅在使用 `--emoji` 时包含 emoji）。\n - 生成消息体：\n - 必须在 subject 之后空一行。\n - 使用列表格式，每项以 `-` 开头。\n - 每项**必须使用动词开头的祈使句**（如 \"add…\"、\"fix…\"、\"update…\"）。\n - **禁止使用冒号分隔的格式**（如 ~~\"Feature: description\"~~、~~\"Impl: content\"~~）。\n - 说明变更的动机、实现要点或影响范围（3 项以内为宜）。\n - 生成消息脚注（如有）：\n - 必须在 Body 之后空一行。\n - **BREAKING CHANGE**：若存在破坏性变更，必须包含 `BREAKING CHANGE: <description>`，或在类型后添加感叹号（如 `feat!:`）。\n - 其它脚注采用 git trailer 格式（如 `Closes #123`、`Refs: #456`、`Reviewed-by: Name`）。\n - 根据 Git 历史提交的主要语言选择提交信息语言。优先检查最近提交主题（例如 `git log -n 50 --pretty=%s`）判断中文/英文；若无法判断，则回退到仓库主要语言或英文。\n - 将草稿写入 `.git/COMMIT_EDITMSG`，并用于 `git commit`。\n\n5. **执行提交**\n - 单提交场景：`git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`\n - 多提交场景（如接受拆分建议）：按分组给出 `git add <paths> && git commit ...` 的明确指令；若允许执行则逐一完成。\n\n6. **安全回滚**\n - 如误暂存，可用 `git restore --staged <paths>` 撤回暂存（命令会给出指令，不修改文件内容）。\n\n---\n\n## Best Practices for Commits\n\n- **Atomic commits**：一次提交只做一件事，便于回溯与审阅。\n- **先分组再提交**：按目录/模块/功能点拆分。\n- **清晰主题**：首行 ≤ 72 字符，祈使语气。\n- **正文含上下文**：说明动机、方案、影响范围（禁止冒号分隔格式）。\n- **遵循 Conventional Commits**：`<type>(<scope>): <subject>`。\n\n---\n\n## Type 与 Emoji 映射（使用 --emoji 时）\n\n- ✨ `feat`：新增功能\n- 🐛 `fix`：缺陷修复（含 🔥 删除代码/文件、🚑️ 紧急修复、👽️ 适配外部 API 变更、🔒️ 安全修复、🚨 解决告警、💚 修复 CI）\n- 📝 `docs`：文档与注释\n- 🎨 `style`：风格/格式（不改语义）\n- ♻️ `refactor`：重构（不新增功能、不修缺陷）\n- ⚡️ `perf`：性能优化\n- ✅ `test`：新增/修复测试、快照\n- 🔧 `chore`：构建/工具/杂务（合并分支、更新配置、发布标记、依赖 pin、.gitignore 等）\n- 👷 `ci`：CI/CD 配置与脚本\n- ⏪️ `revert`：回滚提交\n- 💥 `feat`：破坏性变更（`BREAKING CHANGE:` 段落中说明）\n\n> 若传入 `--type`/`--scope`，将**覆盖**自动推断。\n> 仅在指定 `--emoji` 标志时才会包含 emoji。\n\n---\n\n## Guidelines for Splitting Commits\n\n1. **不同关注点**：互不相关的功能/模块改动应拆分。\n2. **不同类型**：不要将 `feat`、`fix`、`refactor` 混在同一提交。\n3. **文件模式**：源代码 vs 文档/测试/配置分组提交。\n4. **规模阈值**：超大 diff（示例：>300 行或跨多个顶级目录）建议拆分。\n5. **可回滚性**：确保每个提交可独立回退。\n\n---\n\n## Examples\n\n**Good (使用 --emoji)**\n\n```text\n- ✨ feat(ui): add user authentication flow\n- 🐛 fix(api): handle token refresh race condition\n- 📝 docs: update API usage examples\n- ♻️ refactor(core): extract retry logic into helper\n- ✅ test: add unit tests for rate limiter\n- 🔧 chore: update git hooks and repository settings\n- ⏪️ revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (不使用 --emoji)**\n\n```text\n- feat(ui): add user authentication flow\n- fix(api): handle token refresh race condition\n- docs: update API usage examples\n- refactor(core): extract retry logic into helper\n- test: add unit tests for rate limiter\n- chore: update git hooks and repository settings\n- revert: revert \"feat(core): introduce streaming API\"\n```\n\n**Good (包含 Body)**\n\n```text\nfeat(auth): add OAuth2 login flow\n\n- implement Google and GitHub third-party login\n- add user authorization callback handling\n- improve login state persistence logic\n\nCloses #42\n```\n\n```text\nfix(ui): fix button spacing on mobile devices\n\n- adjust button padding to fit small screens\n- fix styling issues on iOS Safari\n- optimize touch target size\n```\n\n**Good (包含 BREAKING CHANGE)**\n\n```text\nfeat(api)!: redesign authentication API\n\n- migrate from session-based to JWT authentication\n- update all endpoint signatures\n- remove deprecated login methods\n\nBREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration\n```\n\n**Split Example**\n\n```text\n- `feat(types): add new type defs for payment method`\n- `docs: update API docs for new types`\n- `test: add unit tests for payment types`\n- `fix: address linter warnings in new files` ←（如你的仓库有钩子报错）\n```\n\n---\n\n## Important Notes\n\n- **仅使用 Git**：不调用任何包管理器/构建命令（无 `pnpm`/`npm`/`yarn` 等）。\n- **尊重钩子**：默认执行本地 Git 钩子；使用 `--no-verify` 可跳过。\n- **不改源码内容**：命令只读写 `.git/COMMIT_EDITMSG` 与暂存区；不会直接编辑工作区文件。\n- **安全提示**：在 rebase/merge 冲突、detached HEAD 等状态下会先提示处理/确认再继续。\n- **可审可控**：如开启 `confirm: true`，每个实际 `git add`/`git commit` 步骤都会进行二次确认。\n\n<!-- File: templates/skills/zh-CN/git-rollback/SKILL.md (Tokens: ~1301 | Category: anthropic-skill) -->\n---\nname: git-rollback\ndescription: 交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert\ndisable-model-invocation: true\nallowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()\n---\n\n# Claude Command: Git Rollback\n\n**目的**：安全、可视地将指定分支回滚到旧版本。\n默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。\n\n---\n\n## Usage\n\n```bash\n# 纯交互：列出分支 → 选分支 → 列最近 20 个版本 → 选目标 → 选择 reset 或 revert → 二次确认\n/git-rollback\n\n# 指定分支，其他交互\n/git-rollback --branch feature/calculator\n\n# 指定分支与目标 commit，并用 hard‑reset 一键执行（危险）\n/git-rollback --branch main --target 1a2b3c4d --mode reset --yes\n\n# 只想生成 revert 提交（非破坏式回滚），预览即可\n/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run\n```\n\n### Options\n\n| 选项 | 说明 |\n| ---------------------- | ---------------------------------------------------------------------------------- |\n| `--branch <branch>` | 要回滚的分支；缺省时交互选择。 |\n| `--target <rev>` | 目标版本（commit Hash、Tag、reflog 引用都行）；缺省时交互选择近 `--depth` 条记录。 |\n| `--mode reset\\|revert` | `reset`：硬回滚历史；`revert`：生成反向提交保持历史完整。默认询问。 |\n| `--depth <n>` | 在交互模式下列出最近 n 个版本（默认 20）。 |\n| `--dry-run` | **默认开启**，只预览即将执行的命令。 |\n| `--yes` | 跳过所有确认直接执行，适合 CI/CD 脚本。 |\n\n---\n\n## 交互流程\n\n1. **同步远端** → `git fetch --all --prune`\n2. **列分支** → `git branch -a`（本地＋远端，过滤受保护分支）\n3. **选分支** → 用户输入或传参\n4. **列版本** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`\n5. **选目标** → 用户输入 commit hash / tag\n6. **选模式** → `reset` 或 `revert`\n7. **最终确认** （除非 `--yes`）\n8. **执行回滚**\n - `reset`：`git switch <branch> && git reset --hard <target>`\n - `revert`：`git switch <branch> && git revert --no-edit <target>..HEAD`\n9. **推送建议** → 提示是否 `git push --force-with-lease`（reset）或普通 `git push`（revert）\n\n---\n\n## 安全护栏\n\n- **备份**：执行前自动在 reflog 中记录当前 HEAD，可用 `git switch -c backup/<timestamp>` 恢复。\n- **保护分支**：如检测到 `main` / `master` / `production` 等受保护分支且开启 `reset` 模式，将要求额外确认。\n- **--dry-run 默认开启**：防止误操作。\n- **--force 禁止**：不提供 `--force`；如需强推，请手动输入 `git push --force-with-lease`。\n\n---\n\n## 适用场景示例\n\n| 场景 | 调用示例 |\n| ----------------------------------------------- | ---------------------------------------------------------------- |\n| 热修补丁上线后发现 bug，需要回到 Tag `v1.2.0` | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |\n| 运维同事误推了 debug 日志提交，需要生成反向提交 | `/git-rollback --branch main --target 3f2e7c9 --mode revert` |\n| 调研历史 bug，引导新人浏览分支历史 | `/git-rollback` （全交互，dry‑run） |\n\n---\n\n## 注意\n\n1. **reset vs revert**\n - **reset** 会改变历史，需要强推并可能影响其他协作者，谨慎使用。\n - **revert** 更安全，生成新提交保留历史，但会增加一次记录。\n2. **嵌入式仓库** 常有大体积二进制文件；回滚前请确保 LFS/子模块状态一致。\n3. 若仓库启用了 CI 强制校验，回滚后可能自动触发流水线；确认管控策略以免误部署旧版本。\n\n---\n\n<!-- File: templates/skills/zh-CN/git-worktree/SKILL.md (Tokens: ~2915 | Category: anthropic-skill) -->\n---\nname: git-worktree\ndescription: 管理 Git worktree，在项目平级的 ../.zcf/项目名/ 目录下创建，支持智能默认、IDE 集成和内容迁移\ndisable-model-invocation: true\nallowed-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)\n---\n\n# Claude Command: Git Worktree\n\n管理 Git worktree，支持智能默认、IDE 集成和内容迁移，使用结构化的 `../.zcf/项目名/` 路径。\n\n直接执行命令并提供简洁结果。\n\n---\n\n## Usage\n\n```bash\n# 基本操作\n/git-worktree add <path> # 从 main/master 创建名为 <path> 的新分支\n/git-worktree add <path> -b <branch> # 创建指定名称的新分支\n/git-worktree add <path> -o # 创建并直接用 IDE 打开\n/git-worktree list # 显示所有 worktree 状态\n/git-worktree remove <path> # 删除指定的 worktree\n/git-worktree prune # 清理无效 worktree 记录\n\n# 内容迁移\n/git-worktree migrate <target> --from <source> # 迁移未提交内容\n/git-worktree migrate <target> --stash # 迁移 stash 内容\n```\n\n### Options\n\n| 选项 | 说明 |\n| ------------------ | -------------------------------------------- |\n| `add [<path>]` | 在 `../.zcf/项目名/<path>` 添加新的 worktree |\n| `migrate <target>` | 迁移内容到指定 worktree |\n| `list` | 列出所有 worktree 及其状态 |\n| `remove <path>` | 删除指定路径的 worktree |\n| `prune` | 清理无效的 worktree 引用 |\n| `-b <branch>` | 创建新分支并检出到 worktree |\n| `-o, --open` | 创建成功后直接用 IDE 打开（跳过询问） |\n| `--from <source>` | 指定迁移源路径（migrate 专用） |\n| `--stash` | 迁移当前 stash 内容（migrate 专用） |\n| `--track` | 设置新分支跟踪对应的远程分支 |\n| `--guess-remote` | 自动猜测远程分支进行跟踪 |\n| `--detach` | 创建分离 HEAD 的 worktree |\n| `--checkout` | 创建后立即检出（默认行为） |\n| `--lock` | 创建后锁定 worktree |\n\n---\n\n## What This Command Does\n\n1. **环境检查**\n - 通过 `git rev-parse --is-inside-work-tree` 验证 Git 仓库\n - 检测是否在主仓库或现有 worktree 中，进行智能路径计算\n\n2. **智能路径管理**\n - 使用 worktree 检测自动从主仓库路径计算项目名\n - 在结构化的 `../.zcf/项目名/<path>` 目录创建 worktree\n - 正确处理主仓库和 worktree 执行上下文\n\n```bash\n# worktree 检测的核心路径计算逻辑\nget_main_repo_path() {\n local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)\n local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)\n\n # 检测是否在 worktree 中\n if [[ \"$git_common_dir\" != \"$current_toplevel/.git\" ]]; then\n # 在 worktree 中，从 git-common-dir 推导主仓库路径\n dirname \"$git_common_dir\"\n else\n # 在主仓库中\n echo \"$current_toplevel\"\n fi\n}\n\nMAIN_REPO_PATH=$(get_main_repo_path)\nPROJECT_NAME=$(basename \"$MAIN_REPO_PATH\")\nWORKTREE_BASE=\"$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME\"\n\n# 始终使用绝对路径防止嵌套问题\nABSOLUTE_WORKTREE_PATH=\"$WORKTREE_BASE/<path>\"\n```\n\n**关键修复**: 在现有 worktree 内创建新 worktree 时，始终使用绝对路径以防止出现类似 `../.zcf/project/.zcf/project/path` 的路径嵌套问题。\n\n3. **Worktree 操作**\n - **add**: 使用智能分支/路径默认创建新 worktree\n - **list**: 显示所有 worktree 的分支和状态\n - **remove**: 安全删除 worktree 并清理引用\n - **prune**: 清理孤立的 worktree 记录\n\n4. **智能默认**\n - **分支创建**: 未指定 `-b` 时，使用路径名创建新分支\n - **基础分支**: 新分支从 main/master 分支创建\n - **路径解析**: 未指定路径时使用分支名作为路径\n - **IDE 集成**: 自动检测并提示 IDE 打开\n\n5. **内容迁移**\n - 在 worktree 之间迁移未提交改动\n - 将 stash 内容应用到目标 worktree\n - 安全检查防止冲突\n\n6. **安全特性**\n - **路径冲突防护**: 创建前检查目录是否已存在\n - **分支检出验证**: 确保分支未被其他地方使用\n - **绝对路径强制**: 防止在 worktree 内创建嵌套的 `.zcf` 目录\n - **删除时自动清理**: 同时清理目录和 git 引用\n - **清晰的状态报告**: 显示 worktree 位置和分支状态\n\n7. **环境文件处理**\n - **自动检测**: 扫描 `.gitignore` 文件中的环境变量文件模式\n - **智能复制**: 复制 `.gitignore` 中列出的 `.env` 和 `.env.*` 文件\n - **排除逻辑**: 跳过 `.env.example` 等模板文件\n - **权限保护**: 保持原始文件权限和时间戳\n - **用户反馈**: 提供已复制环境文件的清晰状态信息\n\n```bash\n# 环境文件复制实现\ncopy_environment_files() {\n local main_repo=\"$MAIN_REPO_PATH\"\n local target_worktree=\"$ABSOLUTE_WORKTREE_PATH\"\n local gitignore_file=\"$main_repo/.gitignore\"\n \n # 检查 .gitignore 是否存在\n if [[ ! -f \"$gitignore_file\" ]]; then\n return 0\n fi\n \n local copied_count=0\n \n # 检测 .env 文件\n if [[ -f \"$main_repo/.env\" ]] && grep -q \"^\\.env$\" \"$gitignore_file\"; then\n cp \"$main_repo/.env\" \"$target_worktree/.env\"\n echo \"✅ 已复制 .env\"\n ((copied_count++))\n fi\n \n # 检测 .env.* 模式文件（排除 .env.example）\n for env_file in \"$main_repo\"/.env.*; do\n if [[ -f \"$env_file\" ]] && [[ \"$(basename \"$env_file\")\" != \".env.example\" ]]; then\n local filename=$(basename \"$env_file\")\n if grep -q \"^\\.env\\.\\*$\" \"$gitignore_file\"; then\n cp \"$env_file\" \"$target_worktree/$filename\"\n echo \"✅ 已复制 $filename\"\n ((copied_count++))\n fi\n fi\n done\n \n if [[ $copied_count -gt 0 ]]; then\n echo \"📋 已从 .gitignore 复制 $copied_count 个环境文件\"\n fi\n}\n```\n\n---\n\n## Enhanced Features\n\n### IDE 集成\n\n- **自动检测**: VS Code → Cursor → WebStorm → Sublime Text → Vim\n- **智能提示**: 创建 worktree 后询问是否在 IDE 中打开\n- **直接打开**: 使用 `-o` 标志跳过提示直接打开\n- **自定义配置**: 通过 git config 配置\n\n### 内容迁移系统\n\n```bash\n# 迁移未提交改动\n/git-worktree migrate feature-ui --from main\n/git-worktree migrate hotfix --from ../other-worktree\n\n# 迁移 stash 内容\n/git-worktree migrate feature-ui --stash\n```\n\n**迁移流程**:\n\n1. 验证源有未提交内容\n2. 确保目标 worktree 干净\n3. 显示即将迁移的改动\n4. 使用 git 命令安全迁移\n5. 确认结果并建议后续步骤\n\n---\n\n## Examples\n\n```bash\n# 基本用法\n/git-worktree add feature-ui # 从 main/master 创建新分支 'feature-ui'\n/git-worktree add feature-ui -b my-feature # 创建新分支 'my-feature'，路径为 'feature-ui'\n/git-worktree add feature-ui -o # 创建并直接用 IDE 打开\n\n# 内容迁移场景\n/git-worktree add feature-ui -b feature/new-ui # 创建新功能 worktree\n/git-worktree migrate feature-ui --from main # 迁移未提交改动\n/git-worktree migrate hotfix --stash # 迁移 stash 内容\n\n# 管理操作\n/git-worktree list # 查看所有 worktree\n/git-worktree remove feature-ui # 删除不需要的 worktree\n/git-worktree prune # 清理无效引用\n```\n\n**示例输出**:\n\n```\n✅ Worktree created at ../.zcf/项目名/feature-ui\n✅ 已复制 .env\n✅ 已复制 .env.local\n📋 已从 .gitignore 复制 2 个环境文件\n🖥️ 是否在 IDE 中打开 ../.zcf/项目名/feature-ui？[y/n]: y\n🚀 正在用 VS Code 打开 ../.zcf/项目名/feature-ui...\n```\n\n---\n\n## Directory Structure\n\n```\nparent-directory/\n├── your-project/ # 主项目\n│ ├── .git/\n│ └── src/\n└── .zcf/ # worktree 管理\n └── your-project/ # 项目 worktree\n ├── feature-ui/ # 功能分支\n ├── hotfix/ # 修复分支\n └── debug/ # 调试 worktree\n```\n\n---\n\n## Configuration\n\n### IDE 配置\n\n- 支持 VS Code、Cursor、WebStorm、Sublime Text、Vim\n- 通过 git config 配置自定义 IDE\n- 基于优先级的自动检测选择\n\n### 自定义 IDE 设置\n\n```bash\n# 配置自定义 IDE\ngit config worktree.ide.custom.sublime \"subl %s\"\ngit config worktree.ide.preferred \"sublime\"\n\n# 控制自动检测\ngit config worktree.ide.autodetect true # 默认\n```\n\n---\n\n## Notes\n\n- **性能**: worktree 共享 `.git` 目录，节省磁盘空间\n- **安全**: 路径冲突防护和分支检出验证\n- **迁移**: 仅限未提交改动；已提交内容需使用 `git cherry-pick`\n- **IDE 要求**: 命令行工具必须在 PATH 中\n- **跨平台**: 支持 Windows、macOS、Linux\n- **环境文件**: 自动复制 `.gitignore` 中列出的环境文件到新 worktree\n- **文件排除**: 模板文件如 `.env.example` 仅保留在主仓库中\n\n---\n\n<!-- File: templates/skills/zh-CN/init-project/SKILL.md (Tokens: ~947 | Category: anthropic-skill) -->\n---\nname: init-project\ndescription: 初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引\ndisable-model-invocation: true\nallowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)\n---\n\n## 用法\n\n`/init-project <项目摘要或名称>`\n\n## 目标\n\n以\"根级简明 + 模块级详尽\"的混合策略初始化项目 AI 上下文：\n\n- 在仓库根生成/更新 `CLAUDE.md`（高层愿景、架构总览、模块索引、全局规范）。\n- 在识别的各模块目录生成/更新本地 `CLAUDE.md`（接口、依赖、入口、测试、关键文件等）。\n- ✨ **为了提升可读性，会在根 `CLAUDE.md` 中自动生成 Mermaid 结构图，并为每个模块 `CLAUDE.md` 添加导航面包屑**。\n\n## 编排说明\n\n**步骤 1**：调用 `get-current-datetime` 子智能体获取当前时间戳。\n\n**步骤 2**：调用一次 `init-architect` 子智能体，输入：\n\n- `project_summary`: $ARGUMENTS\n- `current_timestamp`: (来自步骤1的时间戳)\n\n## 执行策略（由 Agent 自适应决定，不需要用户传参）\n\n- **阶段 A：全仓清点（轻量）**\n 快速统计文件与目录，识别模块根（package.json、pyproject.toml、go.mod、apps/_、packages/_、services/\\* 等）。\n- **阶段 B：模块优先扫描（中等）**\n 对每个模块做\"入口/接口/依赖/测试/数据模型/质量工具\"的定点读取与样本抽取。\n- **阶段 C：深度补捞（按需）**\n 若仓库较小或模块规模较小，则扩大读取面；若较大，则对高风险/高价值路径分批追加扫描。\n- **覆盖率度量与可续跑**\n 输出\"已扫描文件数 / 估算总文件数、已覆盖模块占比、被忽略/跳过原因\"，并列出\"建议下一步深挖的子路径\"。重复运行 `/init-project` 时按上次索引做**增量更新**与**断点续扫**。\n\n## 安全与边界\n\n- 只读/写文档与索引，不改源代码。\n- 默认忽略常见生成物与二进制大文件。\n- 结果在主对话打印\"摘要\"，全文写入仓库。\n\n## 输出要求\n\n- 在主对话中打印\"初始化结果摘要\"，包含：\n - 根级 `CLAUDE.md` 是否创建/更新、主要栏目概览。\n - 识别的模块数量及其路径列表。\n - 每个模块 `CLAUDE.md` 的生成/更新情况。\n - ✨ **明确提及\"已生成 Mermaid 结构图\"和\"已为 N 个模块添加导航面包屑\"**。\n - 覆盖率与主要缺口。\n - 若未读全：说明\"为何到此为止\"，并列出**推荐的下一步**（例如\"建议优先补扫：packages/auth/src/controllers\"）。\n\n<!-- File: templates/skills/zh-CN/workflow/SKILL.md (Tokens: ~3076 | Category: anthropic-skill) -->\n---\nname: workflow\ndescription: '专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），适用于专业开发者'\ndisable-model-invocation: true\n---\n\n# Workflow - 专业开发助手\n\n使用质量把关和 MCP 服务集成执行结构化开发工作流。\n\n## 使用方法\n\n```bash\n/workflow <任务描述>\n```\n\n## 上下文\n\n- 要开发的任务：$ARGUMENTS\n- 带质量把关的结构化 6 阶段工作流\n- 面向专业开发者的交互\n- MCP 服务集成以增强功能\n\n## 你的角色\n\n你是 IDE 的 AI 编程助手，遵循核心工作流（研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审）用中文协助用户，面向专业程序员，交互应简洁专业，避免不必要解释。\n\n[沟通守则]\n\n1. 响应以模式标签 `[模式：X]` 开始，初始为 `[模式：研究]`。\n2. 核心工作流严格按 `研究 -> 构思 -> 计划 -> 执行 -> 优化 -> 评审` 顺序流转，用户可指令跳转。\n\n[核心工作流详解]\n\n1. `[模式：研究]`：理解需求并评估完整性（0-10 分），低于 7 分时主动要求补充关键信息。\n2. `[模式：构思]`：提供至少两种可行方案及评估（例如：`方案 1：描述`）。\n3. `[模式：计划]`：将选定方案细化为详尽、有序、可执行的步骤清单（含原子操作：文件、函数/类、逻辑概要；预期结果；新库用 `Context7` 查询）。不写完整代码。完成后请求用户批准。\n4. `[模式：执行]`：计划简要（含上下文和计划）存入当前项目根目录的`.zcf/plan/current/任务名.md`。必须用户批准方可执行。严格按计划编码执行。关键步骤后及完成时请求用户反馈。\n5. `[模式：优化]`：在 `[模式：执行]` 完成后，必须自动进行本模式 `[模式：优化]`，自动检查并分析本次任务已实现（仅本次对话产生的相关代码），在 `[模式：执行]` 下产生的相关代码。聚焦冗余、低效、垃圾代码，提出具体优化建议（含优化理由与预期收益），用户确认后执行相关优化功能。\n6. `[模式：评审]`：对照计划评估执行结果，报告问题与建议。完成后请求用户确认。\n\n[时间戳获取规则]\n\n在工作流执行过程中，任何需要当前时间戳的场景，必须通过 bash 命令获取准确时间，禁止猜测或编造。\n\n基本命令：\n- 默认格式：`date +'%Y-%m-%d %H:%M:%S'`\n- 文件名格式：`date +'%Y-%m-%d_%H%M%S'`\n- 可读格式：`date +'%Y-%m-%d %H:%M:%S %Z'`\n- ISO 格式：`date +'%Y-%m-%dT%H:%M:%S%z'`\n\n典型应用场景：\n- 更新文档中的时间戳字段\n- 任务计划文档归档时的命名（从 `.zcf/plan/current/` 移至 `.zcf/plan/history/` 时）\n- 其他任何需要记录当前时间的场合\n\n[主动反馈与 MCP 服务]\n\n# 主动反馈规则\n\n1. 在任何流程、任务、对话进行时，无论是询问、回复、或完成阶段性任务，皆必须请求用户确认。\n2. 每当收到用户反馈，若反馈内容非空，必须再次请求用户确认，并根据反馈内容调整行为。\n3. 仅当用户明确表示「结束」或「不再需要交互」时, 才可停止请求用户确认，流程才算结束。\n4. 除非收到结束指令，否则所有步骤都必须重复请求用户确认。\n5. 完成任务前，必须请求用户确认，并向用户询问反馈。\n\n---\n\n## 执行工作流\n\n**任务描述**：$ARGUMENTS\n\n正在启动带质量把关的结构化开发工作流...\n\n### 🔍 阶段 1：研究与分析\n\n[模式：研究] - 理解需求并收集上下文：\n\n#### 需求完整性评分（0-10 分）\n\n评分维度：\n\n- **目标明确性**（0-3 分）：任务目标是否清晰具体，要解决什么问题\n- **预期结果**（0-3 分）：成功标准和交付物是否明确定义\n- **边界范围**（0-2 分）：任务范围和边界是否清楚\n- **约束条件**（0-2 分）：时间、性能、业务限制等是否说明\n\n注：技术栈、框架版本等信息将从项目自动识别，不计入评分\n\n**评分规则**：\n\n- 9-10 分：需求非常完整，可直接进入下一阶段\n- 7-8 分：需求基本完整，建议补充个别细节\n- 5-6 分：需求有明显缺失，必须补充关键信息\n- 0-4 分：需求过于模糊，需要重新描述\n\n**当评分低于 7 分时，主动提出补充问题**：\n\n- 识别缺失的关键信息维度\n- 针对每个缺失维度提出 1-2 个具体问题\n- 提供示例帮助用户理解需要的信息类型\n- 等待用户补充后重新评分\n\n**评分示例**：\n\n```\n用户需求：\"帮我优化代码\"\n评分分析：\n- 目标明确性：0/3分（未说明优化什么代码、解决什么问题）\n- 预期结果：0/3分（未定义优化成功标准、期望达到什么效果）\n- 边界范围：1/2分（只知道是代码优化，但范围不明）\n- 约束条件：0/2分（无性能指标、时间限制说明）\n总分：1/10 - 需要大量补充信息\n\n需要补充的问题：\n1. 请问您要优化哪个文件或模块的代码？\n2. 当前存在什么具体问题需要优化？\n3. 期望优化后达到什么效果（如响应时间提升、代码量减少等）？\n4. 有具体的性能指标或时间要求吗？\n```\n\n**常用补充问题模板**：\n\n- 目标类：\"您希望实现什么具体功能/效果？\" \"当前存在什么具体问题？\"\n- 结果类：\"如何判断任务成功完成？\" \"期望的输出/效果是什么？\"\n- 范围类：\"需要处理哪些具体文件/模块？\" \"不需要包含什么？\"\n- 约束类：\"时间要求是怎样的？\" \"有什么业务限制或性能要求？\"\n\n**自动获取的项目信息**（不需要询问）：\n\n- 技术栈（从 AGENTS.md、CLAUDE.md、package.json、requirements.txt 等获取）\n- 框架版本（从 AGENTS.md、CLAUDE.md、配置文件获取）\n- 项目结构（从文件系统获取）\n- 现有代码规范（从 AGENTS.md、CLAUDE.md、配置文件和现有代码获取）\n- 开发命令（从 AGENTS.md、CLAUDE.md 获取，如构建、测试、类型检查等）\n\n#### 执行步骤\n\n- 分析任务需求和约束\n- 进行需求完整性评分（显示具体得分）\n- 识别关键目标和成功标准\n- 收集必要的技术上下文\n- 如需要，使用 MCP 服务获取额外信息\n\n### 💡 阶段 2：方案构思\n\n[模式：构思] - 设计解决方案：\n\n- 生成多个可行的解决方案\n- 评估每种方法的优缺点\n- 提供详细的比较和推荐\n- 考虑技术约束和最佳实践\n- 在继续之前请求用户批准\n\n### 📋 阶段 3：详细规划\n\n[模式：计划] - 创建执行路线图：\n\n- 将解决方案分解为原子的、可执行的步骤\n- 定义文件结构、函数/类和逻辑概述\n- 为每个步骤指定预期结果\n- 如需要，使用 Context7 查询新库\n- 在继续之前请求用户批准\n\n### ⚡ 阶段 4：实施\n\n[模式：执行] - 代码开发：\n\n- 在项目根目录 `.zcf/plan/current/任务名.md` 中存储执行计划\n- 根据批准的计划实施\n- 遵循开发最佳实践\n- 在导入语句之前添加使用方法（关键规则）\n- 在关键里程碑请求反馈\n\n### 🚀 阶段 5：代码优化\n\n[模式：优化] - 质量改进：\n\n- 自动分析已实现的代码\n- 识别冗余、低效或有问题的代码\n- 提供具体的优化建议\n- 在用户确认后执行改进\n\n### ✅ 阶段 6：质量审查\n\n[模式：评审] - 最终评估：\n\n- 将结果与原始计划进行比较\n- 识别任何剩余的问题或改进\n- 提供完成总结和建议\n- 请求最终用户确认\n- 任务完全结束后，将计划文件从 `.zcf/plan/current/` 移动到 `.zcf/plan/history/` 进行归档\n- 归档时重命名为 `[完成时间]任务名.md` 便于追踪，时间格式为 `YYYY-MM-DD_HHMMSS`\n\n## 预期输出结构\n\n```\nproject/ # 项目根目录\n├── .zcf/\n│ └── plan/\n│ ├── current/ # 当前进行中的任务\n│ │ └── 任务名.md # 执行计划和上下文\n│ └── history/ # 已完成的历史任务\n│ └── [完成时间]任务名.md # 归档的任务记录\n├── src/\n│ ├── components/\n│ ├── services/\n│ ├── utils/\n│ └── types/\n├── tests/\n│ ├── unit/\n│ ├── integration/\n│ └── e2e/\n└── README.md\n```\n\n**使用提供的任务描述开始执行，并在每个阶段完成后报告进度。**\n\n<!-- File: src/commands/CLAUDE.md (Tokens: ~1821 | Category: command-prompt) -->\n# Commands Module\n\n**Last Updated**: Mon Oct 27 19:39:26 CST 2025\n\n[Root](../../CLAUDE.md) > [src](../) > **commands**\n\n## Module Responsibilities\n\nCLI command implementation module containing all major command functions for ZCF, providing both interactive and non-interactive operation interfaces for Claude Code environment setup and management.\n\n## Entry Points and Startup\n\n- **Main Entry Points**:\n - `init.ts` - Complete initialization flow with full setup options (45KB, 1,200+ lines)\n - `menu.ts` - Interactive menu system with feature selection (13KB, 350+ lines)\n - `update.ts` - Workflow template updates without full reinstall (4KB, 100+ lines)\n - `ccr.ts` - Claude Code Router proxy configuration (1KB, 30+ lines)\n - `ccu.ts` - CCusage tool integration and execution (1KB, 40+ lines)\n - `check-updates.ts` - Tool version checking and update management (1.3KB, 50+ lines)\n - `config-switch.ts` - Configuration switching for multi-provider support (14KB, 400+ lines)\n - `uninstall.ts` - ZCF uninstallation with selective removal (10KB, 300+ lines)\n\n## External Interfaces\n\n### Command Interfaces\n\n```typescript\n// Initialize command options (v3.3.0+)\nexport interface InitOptions {\n configLang?: SupportedLang\n aiOutputLang?: AiOutputLanguage | string\n force?: boolean\n skipBanner?: boolean\n skipPrompt?: boolean\n codeType?: CodeToolType | string // Support 'cc', 'cx' abbreviations\n // Non-interactive mode parameters\n configAction?: 'new' | 'backup' | 'merge' | 'docs-only' | 'skip'\n apiType?: 'auth_token' | 'api_key' | 'ccr_proxy' | 'skip'\n apiKey?: string // Used for both API key and auth token\n apiUrl?: string\n apiModel?: string // Primary API model\n apiFastModel?: string // Fast API model\n provider?: string // API provider preset (302ai, glm, minimax, kimi, custom)\n mcpServices?: string[] | string | boolean\n workflows?: string[] | string | boolean\n outputStyles?: string[] | string | boolean\n defaultOutputStyle?: string\n allLang?: string // Unified language parameter\n installCometixLine?: string | boolean // CCometixLine installation control\n // Multi-configuration parameters\n apiConfigs?: string // JSON string for multiple API configurations\n apiConfigsFile?: string // Path to JSON file with API configurations\n}\n\n// Update command options\nexport interface UpdateOptions {\n lang?: SupportedLang\n force?: boolean\n selectedWorkflows?: string[]\n}\n\n// CCR command options\nexport interface CcrOptions {\n lang?: SupportedLang\n}\n\n// Check updates options\nexport interface CheckUpdatesOptions {\n lang?: SupportedLang\n codeType?: CodeToolType | string\n}\n\n// Config switch options\nexport interface ConfigSwitchOptions {\n codeType?: CodeToolType | string\n list?: boolean\n}\n\n// Uninstall options\nexport interface UninstallOptions {\n mode?: 'complete' | 'custom' | 'interactive'\n items?: string\n lang?: SupportedLang\n}\n```\n\n### API Endpoints\n\n- `init(options: InitOptions)` - Execute complete initialization workflow with dual code tool support\n- `update(options: UpdateOptions)` - Update workflow templates and configurations\n- `showMainMenu()` - Display interactive main menu with all features\n- `ccr(options: CcrOptions)` - Configure Claude Code Router proxy settings\n- `executeCcusage(args: string[])` - Execute CCusage tool with specified arguments\n- `checkUpdates(options: CheckUpdatesOptions)` - Check for tool updates and perform upgrades\n- `configSwitch(target: string, options: ConfigSwitchOptions)` - Switch between API configurations\n- `uninstall(options: UninstallOptions)` - Uninstall ZCF with selective removal options\n\n### Menu System Interface\n\n```typescript\n// Menu feature functions\nexport interface MenuFeatures {\n fullInit: () => Promise<void>\n importWorkflow: () => Promise<void>\n configureApiOrCcr: () => Promise<void>\n configureMcp: () => Promise<void>\n configureAiMemory: () => Promise<void>\n // Tool integrations\n runCcr: () => Promise<void>\n runCcu: () => Promise<void>\n runCometix: () => Promise<void>\n // System features\n checkUpdates: () => Promise<void>\n changeLanguage: () => Promise<void>\n clearCache: () => Promise<void>\n}\n```\n\n## Key Dependencies and Configuration\n\n### Core Dependencies\n\n```typescript\n// Configuration and utilities\nimport { getTranslation } from '../i18n'\nimport { displayBannerWithInfo } from '../utils/banner'\nimport { backupExistingConfig, configureApi } from '../utils/config'\nimport { handleExitPromptError } from '../utils/error-handler'\nimport { installClaudeCode } from '../utils/installer'\n\n// Platform and validation\nimport { isTermux, isWindows } from '../utils/platform'\nimport { selectAndInstallWorkflows } from '../utils/workflow-installer'\nimport { readZcfConfig, updateZcfConfig } from '../utils/zcf-config'\n```\n\n### Configuration Integration\n\n- **I18n System**: Full internationalization support for all user interactions\n- **Platform Detection**: Windows/macOS/Linux/Termux compatibility handling\n- **Configuration Management**: Smart merging and backup of existing configurations\n- **Workflow System**: Integration with template installation and management\n- **Tool Integration**: CCR, CCusage, and Cometix tool management\n\n## Data Models\n\n### Command Flow Architecture\n\n```typescript\ninterface CommandFlow {\n init: {\n phases: ['banner', 'config', 'api', 'mcp', 'workflows', 'tools', 'completion']\n skipOptions: ['prompt', 'banner', 'config', 'api', 'mcp', 'workflows']\n rollbackCapability: true\n }\n menu: {\n structure: 'hierarchical'\n categories: ['claude-code', 'tools', 'system']\n persistence: 'language-aware'\n }\n update: {\n scope: ['workflows', 'templates', 'agents']\n conflictResolution: 'preserve-user-changes'\n }\n}\n```\n\n### Error Handling Strategy\n\n```typescript\ninterface ErrorHandling {\n gracefulDegradation: true\n userFriendlyMessages: true\n i18nSupport: true\n platformSpecificGuidance: true\n recoverySuggestions: true\n}\n```\n\n## Testing and Quality\n\n### Test Coverage\n\n- **Unit Tests**: Individual command function testing\n- **Integration Tests**: Full workflow execution testing\n- **Edge Case Tests**: Platform-specific and error condition testing\n- **Mock Testing**: External tool integration testing with comprehensive mocking\n\n### Test Files\n\n- `tests/commands/*.test.ts` - Core command functionality tests\n- `tests/commands/*.edge.test.ts` - Edge case and error condition tests\n- `tests/unit/commands/` - Isolated unit tests for command logic\n\n### Common Issues\n\n- **Platform Dependencies**: Windows path handling and Termux environment detection\n- **User Input Validation**: Handling of invalid selections and exit conditions\n- **External Tool Integration**: CCR, CCusage availability and version compatibility\n- **Configuration Conflicts**: Existing configuration preservation and merging\n\n## Related Files\n\n- `../utils/` - Core utility functions for configuration, installation, and platform support\n- `../i18n/` - Internationalization support for command interfaces\n- `../types/` - TypeScript interfaces for command options and configurations\n- `../config/workflows.ts` - Workflow configuration definitions\n- `../../templates/` - Template files used by commands\n\n## Change Log (Module-Specific)\n\n### Recent Updates (v3.3.0)\n\n- Added API provider preset system for simplified configuration (302.AI, GLM, MiniMax, Kimi)\n- Enhanced dual code tool support (Claude Code + Codex)\n- Improved config-switch command with multi-provider management\n- Added comprehensive uninstall command with selective removal\n- Enhanced non-interactive mode with --all-lang unified language parameter\n- Added CCometixLine installation control via --install-cometix-line parameter\n- Improved multi-configuration support with apiConfigs and apiConfigsFile parameters\n- Enhanced error handling with platform-specific guidance\n- Expanded menu system with tool integration features\n- Added intelligent IDE detection and auto-open functionality\n</yakaai_skills>"}