Merge pull request #931 from KT-lcz/main

docs: clarify multi-model command setup

.github/workflows/ci.yml

@@ -48,6 +48,13 @@ jobs:
         with:
           version: latest
 
+      - name: Setup Yarn (via Corepack)
+        if: matrix.pm == 'yarn'
+        shell: bash
+        run: |
+          corepack enable
+          corepack prepare yarn@stable --activate
+
       - name: Setup Bun
         if: matrix.pm == 'bun'
         uses: oven-sh/setup-bun@v2
@@ -114,14 +121,18 @@ jobs:
             ${{ runner.os }}-bun-
 
       # Install dependencies
+      # COREPACK_ENABLE_STRICT=0 allows pnpm to install even though
+      # package.json declares "packageManager": "yarn@..."
       - name: Install dependencies
         shell: bash
+        env:
+          COREPACK_ENABLE_STRICT: '0'
         run: |
           case "${{ matrix.pm }}" in
             npm) npm ci ;;
-            pnpm) pnpm install ;;
+            pnpm) pnpm install --no-frozen-lockfile ;;
-            # --ignore-engines required for Node 18 compat with some devDependencies (e.g., markdownlint-cli)
+            # Yarn Berry (v4+) removed --ignore-engines; engine checking is no longer a core feature
-            yarn) yarn install --ignore-engines ;;
+            yarn) yarn install ;;
             bun) bun install ;;
             *) echo "Unsupported package manager: ${{ matrix.pm }}" && exit 1 ;;
           esac

.github/workflows/reusable-test.yml

@@ -40,6 +40,13 @@ jobs:
         with:
           version: latest
 
+      - name: Setup Yarn (via Corepack)
+        if: inputs.package-manager == 'yarn'
+        shell: bash
+        run: |
+          corepack enable
+          corepack prepare yarn@stable --activate
+
       - name: Setup Bun
         if: inputs.package-manager == 'bun'
         uses: oven-sh/setup-bun@v2
@@ -104,13 +111,18 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-bun-
 
+      # COREPACK_ENABLE_STRICT=0 allows pnpm to install even though
+      # package.json declares "packageManager": "yarn@..."
       - name: Install dependencies
         shell: bash
+        env:
+          COREPACK_ENABLE_STRICT: '0'
         run: |
           case "${{ inputs.package-manager }}" in
             npm) npm ci ;;
-            pnpm) pnpm install ;;
+            pnpm) pnpm install --no-frozen-lockfile ;;
-            yarn) yarn install --ignore-engines ;;
+            # Yarn Berry (v4+) removed --ignore-engines; engine checking is no longer a core feature
+            yarn) yarn install ;;
             bun) bun install ;;
             *) echo "Unsupported package manager: ${{ inputs.package-manager }}" && exit 1 ;;
           esac

README.md

@@ -180,6 +180,11 @@ cd everything-claude-code
 npm install        # or: pnpm install | yarn install | bun install
 
 # macOS/Linux
+
+# Recommended: install everything (full profile)
+./install.sh --profile full
+
+# Or install for specific languages only
 ./install.sh typescript    # or python or golang or swift or php
 # ./install.sh typescript python golang swift php
 # ./install.sh --target cursor typescript
@@ -188,6 +193,11 @@ npm install        # or: pnpm install | yarn install | bun install
 
 ```powershell
 # Windows PowerShell
+
+# Recommended: install everything (full profile)
+.\install.ps1 --profile full
+
+# Or install for specific languages only
 .\install.ps1 typescript   # or python or golang or swift or php
 # .\install.ps1 typescript python golang swift php
 # .\install.ps1 --target cursor typescript
@@ -214,6 +224,20 @@ For manual install instructions see the README in the `rules/` folder.
 
 ✨ **That's it!** You now have access to 28 agents, 125 skills, and 60 commands.
 
+### Multi-model commands require additional setup
+
+> ⚠️ `multi-*` commands are **not** covered by the base plugin/rules install above.
+>
+> To use `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, and `/multi-workflow`, you must also install the `ccg-workflow` runtime.
+>
+> Initialize it with `npx ccg-workflow`.
+>
+> That runtime provides the external dependencies these commands expect, including:
+> - `~/.claude/bin/codeagent-wrapper`
+> - `~/.claude/.ccg/prompts/*`
+>
+> Without `ccg-workflow`, these `multi-*` commands will not run correctly.
+
 ---
 
 ## 🌐 Cross-Platform Support

README.zh-CN.md

@@ -105,6 +105,20 @@ cp -r everything-claude-code/rules/perl/* ~/.claude/rules/
 
 ✨ **完成！** 你现在可以使用 13 个代理、43 个技能和 31 个命令。
 
+### multi-* 命令需要额外配置
+
+> ⚠️ 上面的基础插件 / rules 安装**不包含** `multi-*` 命令所需的运行时。
+>
+> 如果要使用 `/multi-plan`、`/multi-execute`、`/multi-backend`、`/multi-frontend` 和 `/multi-workflow`，还需要额外安装 `ccg-workflow` 运行时。
+>
+> 可通过 `npx ccg-workflow` 完成初始化安装。
+>
+> 该运行时会提供这些命令依赖的关键组件，包括：
+> - `~/.claude/bin/codeagent-wrapper`
+> - `~/.claude/.ccg/prompts/*`
+>
+> 未安装 `ccg-workflow` 时，这些 `multi-*` 命令将无法正常运行。
+
 ---
 
 ## 🌐 跨平台支持

scripts/doctor.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const os = require('os');
 const { buildDoctorReport } = require('./lib/install-lifecycle');
 const { SUPPORTED_INSTALL_TARGETS } = require('./lib/install-manifests');
 
@@ -88,7 +89,7 @@ function main() {
 
     const report = buildDoctorReport({
       repoRoot: require('path').join(__dirname, '..'),
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
       projectRoot: process.cwd(),
       targets: options.targets,
     });

scripts/install-apply.js

@@ -6,6 +6,7 @@
  * target-specific mutation logic into testable Node code.
  */
 
+const os = require('os');
 const {
   SUPPORTED_INSTALL_TARGETS,
   listLegacyCompatibilityLanguages,
@@ -16,10 +17,10 @@ const {
   parseInstallArgs,
 } = require('./lib/install/request');
 
-function showHelp(exitCode = 0) {
+function getHelpText() {
   const languages = listLegacyCompatibilityLanguages();
 
-  console.log(`
+  return `
 Usage: install.sh [--target <${LEGACY_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] <language> [<language> ...]
        install.sh [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] --profile <name> [--with <component>]... [--without <component>]...
        install.sh [--target <${SUPPORTED_INSTALL_TARGETS.join('|')}>] [--dry-run] [--json] --modules <id,id,...> [--with <component>]... [--without <component>]...
@@ -43,8 +44,11 @@ Options:
 
 Available languages:
 ${languages.map(language => `  - ${language}`).join('\n')}
-`);
+`;
+}
 
+function showHelp(exitCode = 0) {
+  console.log(getHelpText());
   process.exit(exitCode);
 }
 
@@ -118,7 +122,7 @@ function main() {
     });
     const plan = createInstallPlanFromRequest(request, {
       projectRoot: process.cwd(),
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
       claudeRulesDir: process.env.CLAUDE_RULES_DIR || null,
     });
 
@@ -138,7 +142,7 @@ function main() {
       printHumanPlan(result, false);
     }
   } catch (error) {
-    console.error(`Error: ${error.message}`);
+    process.stderr.write(`Error: ${error.message}${getHelpText()}`);
     process.exit(1);
   }
 }

scripts/lib/install-executor.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
@@ -442,7 +443,7 @@ function planAntigravityLegacyInstall(context) {
 function createLegacyInstallPlan(options = {}) {
   const sourceRoot = options.sourceRoot || getSourceRoot();
   const projectRoot = options.projectRoot || process.cwd();
-  const homeDir = options.homeDir || process.env.HOME;
+  const homeDir = options.homeDir || process.env.HOME || os.homedir();
   const target = options.target || 'claude';
 
   validateLegacyTarget(target);

scripts/lib/install-lifecycle.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 const { resolveInstallPlan, loadInstallManifests } = require('./install-manifests');
@@ -696,7 +697,7 @@ function buildDiscoveryRecord(adapter, context) {
 
 function discoverInstalledStates(options = {}) {
   const context = {
-    homeDir: options.homeDir || process.env.HOME,
+    homeDir: options.homeDir || process.env.HOME || os.homedir(),
     projectRoot: options.projectRoot || process.cwd(),
   };
   const targets = normalizeTargets(options.targets);
@@ -904,7 +905,7 @@ function buildDoctorReport(options = {}) {
   }).filter(record => record.exists);
   const context = {
     repoRoot,
-    homeDir: options.homeDir || process.env.HOME,
+    homeDir: options.homeDir || process.env.HOME || os.homedir(),
     projectRoot: options.projectRoot || process.cwd(),
     manifestVersion: manifests.modulesVersion,
     packageVersion: readPackageVersion(repoRoot),
@@ -988,7 +989,7 @@ function repairInstalledStates(options = {}) {
   const manifests = loadInstallManifests({ repoRoot });
   const context = {
     repoRoot,
-    homeDir: options.homeDir || process.env.HOME,
+    homeDir: options.homeDir || process.env.HOME || os.homedir(),
     projectRoot: options.projectRoot || process.cwd(),
     manifestVersion: manifests.modulesVersion,
     packageVersion: readPackageVersion(repoRoot),

scripts/list-installed.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const os = require('os');
 const { discoverInstalledStates } = require('./lib/install-lifecycle');
 const { SUPPORTED_INSTALL_TARGETS } = require('./lib/install-manifests');
 
@@ -70,7 +71,7 @@ function main() {
     }
 
     const records = discoverInstalledStates({
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
       projectRoot: process.cwd(),
       targets: options.targets,
     }).filter(record => record.exists);

scripts/repair.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const os = require('os');
 const { repairInstalledStates } = require('./lib/install-lifecycle');
 const { SUPPORTED_INSTALL_TARGETS } = require('./lib/install-manifests');
 
@@ -74,7 +75,7 @@ function main() {
 
     const result = repairInstalledStates({
       repoRoot: require('path').join(__dirname, '..'),
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
       projectRoot: process.cwd(),
       targets: options.targets,
       dryRun: options.dryRun,

scripts/sessions-cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const os = require('os');
 const { createStateStore } = require('./lib/state-store');
 
 function showHelp(exitCode = 0) {
@@ -134,7 +135,7 @@ async function main() {
 
     store = await createStateStore({
       dbPath: options.dbPath,
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
     });
 
     if (!options.sessionId) {

scripts/status.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const os = require('os');
 const { createStateStore } = require('./lib/state-store');
 
 function showHelp(exitCode = 0) {
@@ -139,7 +140,7 @@ async function main() {
 
     store = await createStateStore({
       dbPath: options.dbPath,
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
     });
 
     const payload = {

scripts/uninstall.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const os = require('os');
 const { uninstallInstalledStates } = require('./lib/install-lifecycle');
 const { SUPPORTED_INSTALL_TARGETS } = require('./lib/install-manifests');
 
@@ -73,7 +74,7 @@ function main() {
     }
 
     const result = uninstallInstalledStates({
-      homeDir: process.env.HOME,
+      homeDir: process.env.HOME || os.homedir(),
       projectRoot: process.cwd(),
       targets: options.targets,
       dryRun: options.dryRun,