setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ITP Setup

ITP 设置

Verify and install dependencies required by the

/itp:go

workflow using TodoWrite-driven interactive workflow.

使用TodoWrite驱动的交互式工作流，验证并安装

/itp:go

工作流所需的依赖。

MANDATORY FIRST ACTION

强制首步操作

YOUR FIRST ACTION MUST BE TodoWrite with the template below.

DO NOT:

Run any checks before TodoWrite
Skip the interactive gate
Install without user confirmation

Execute this TodoWrite template EXACTLY:

TodoWrite with todos:
- "Setup: Detect platform (macOS/Linux)" | pending | "Detecting platform"
- "Setup: Check Core Tools (uv, gh, prettier)" | pending | "Checking Core Tools"
- "Setup: Check ADR Diagram Tools (cpanm, graph-easy)" | pending | "Checking ADR Tools"
- "Setup: Check Code Audit Tools (ruff, semgrep, jscpd, gitleaks)" | pending | "Checking Audit Tools"
- "Setup: Check Release Tools (node, semantic-release)" | pending | "Checking Release Tools"
- "Setup: Present findings and disclaimer" | pending | "Presenting findings"
- "Setup: GATE - Await user decision" | pending | "Awaiting user decision"
- "Setup: Install missing tools (if confirmed)" | pending | "Installing missing tools"
- "Setup: Verify installation" | pending | "Verifying installation"

After TodoWrite completes, proceed to Phase 1 below.

你的第一个操作必须是使用下方模板执行TodoWrite。

禁止操作：

不要在执行TodoWrite前运行任何检查
不要跳过交互式确认关口
不要在未获得用户确认的情况下执行安装

请严格执行以下TodoWrite模板：

TodoWrite with todos:
- "Setup: Detect platform (macOS/Linux)" | pending | "Detecting platform"
- "Setup: Check Core Tools (uv, gh, prettier)" | pending | "Checking Core Tools"
- "Setup: Check ADR Diagram Tools (cpanm, graph-easy)" | pending | "Checking ADR Tools"
- "Setup: Check Code Audit Tools (ruff, semgrep, jscpd, gitleaks)" | pending | "Checking Audit Tools"
- "Setup: Check Release Tools (node, semantic-release)" | pending | "Checking Release Tools"
- "Setup: Present findings and disclaimer" | pending | "Presenting findings"
- "Setup: GATE - Await user decision" | pending | "Awaiting user decision"
- "Setup: Install missing tools (if confirmed)" | pending | "Installing missing tools"
- "Setup: Verify installation" | pending | "Verifying installation"

TodoWrite执行完成后，继续执行下方的第1阶段。

Phase 1: Preflight Check

第1阶段：预检

Mark each todo as

in_progress

before starting,

completed

when done.

在开始每个待办项前将其标记为

in_progress

，完成后标记为

completed

。

Todo 1: Detect Platform

待办1：检测平台

bash

/usr/bin/env bash << 'SETUP_EOF'
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/itp}"
source "$PLUGIN_DIR/scripts/install-dependencies.sh" --detect-only
SETUP_EOF

Platform detection sets:

OS

PM

(package manager),

HAS_MISE

bash

/usr/bin/env bash << 'SETUP_EOF'
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/itp}"
source "$PLUGIN_DIR/scripts/install-dependencies.sh" --detect-only
SETUP_EOF

平台检测会设置以下变量：

OS

、

PM

（包管理器）、

HAS_MISE

Todo 2: Check Core Tools

待办2：检查核心工具

Check each tool using

command -v

Tool	Check	Required
uv	`command -v uv`	Yes
gh	`command -v gh`	Yes
prettier	`command -v prettier`	Yes

Record findings:

Found:
```
[OK] uv (installed)
```
-> mark completed
Missing:
```
[x] prettier (missing)
```
-> note for Phase 3

使用

command -v

检查每个工具：

工具	检查命令	是否必填
uv	`command -v uv`	是
gh	`command -v gh`	是
prettier	`command -v prettier`	是

记录检查结果：

已安装：
```
[OK] uv (installed)
```
-> 标记为完成
缺失：
```
[x] prettier (missing)
```
-> 记录到第3阶段

Todo 3: Check ADR Diagram Tools

待办3：检查ADR绘图工具

Tool	Check	Required
cpanm	`command -v cpanm`	For diagrams
graph-easy	`echo "[A]" \| graph-easy` (test)	For diagrams

工具	检查命令	必填场景
cpanm	`command -v cpanm`	绘图功能
graph-easy	`echo "[A]" \| graph-easy` (测试)	绘图功能

Todo 4: Check Code Audit Tools

待办4：检查代码审计工具

Tool	Check	Required
ruff	`command -v ruff`	For code-audit
semgrep	`command -v semgrep`	For code-audit
jscpd	`command -v jscpd`	For code-audit
gitleaks	`command -v gitleaks`	For secret-scan

工具	检查命令	必填场景
ruff	`command -v ruff`	代码审计
semgrep	`command -v semgrep`	代码审计
jscpd	`command -v jscpd`	代码审计
gitleaks	`command -v gitleaks`	密钥扫描

Todo 5: Check Release Tools

待办5：检查发布工具

Tool	Check	Required
node	`command -v node`	For release
semantic-release	`npx semantic-release --version`	For release
doppler	`command -v doppler`	For PyPI only

工具	检查命令	必填场景
node	`command -v node`	发布功能
semantic-release	`npx semantic-release --version`	发布功能
doppler	`command -v doppler`	仅PyPI发布

Phase 2: Present Findings (Interactive Gate)

第2阶段：展示检查结果（交互式确认关口）

Todo 6: Present Findings

待办6：展示检查结果

IMPORTANT: Use mise-first commands when available

When presenting missing tool installation commands:

If
```
HAS_MISE=true
```
(detected in Todo 1): Show mise commands
If
```
HAS_MISE=false
```
: Show platform package manager commands (brew/apt)

Mise command reference (use when HAS_MISE=true):

Tool	mise command	Notes
gitleaks	`mise use --global gitleaks`
ruff	`mise use --global ruff`
uv	`mise use --global uv`
gh	`brew install gh`	NEVER mise (iTerm2 issues)
semgrep	`mise use --global semgrep`
node	`mise use --global node`
doppler	`mise use --global doppler`
prettier	`mise use --global npm:prettier`
jscpd	`npm i -g jscpd` (npm only)

Warning: gh CLI must be installed via Homebrew, not mise. mise-installed gh causes iTerm2 tab spawning issues with Claude Code. ADR

Display summary format (versions derived from actual tool output):

=== SETUP PREFLIGHT COMPLETE ===

Found: X tools | Missing: Y tools

Your existing installations:
[OK] uv (<derived from: uv --version>)
[OK] gh (<derived from: gh --version>)
[x] gitleaks (missing)
...

Note: This plugin is developed against latest tool versions.
Your existing installations are respected.

Missing tools will be installed via mise (detected):
  gitleaks -> mise use --global gitleaks

If HAS_MISE=false, show platform commands instead:

Missing tools will be installed via brew:
  gitleaks -> brew install gitleaks

IMPORTANT: Version numbers must be derived dynamically from running the actual tool's version command. Never hardcode version numbers.

重要提示：优先使用可用的mise命令

展示缺失工具的安装命令时：

如果
```
HAS_MISE=true
```
（在待办1中检测到）：展示mise命令
如果
```
HAS_MISE=false
```
：展示对应平台的包管理器命令（brew/apt）

Mise命令参考（当HAS_MISE=true时使用）：

工具	mise命令	备注
gitleaks	`mise use --global gitleaks`
ruff	`mise use --global ruff`
uv	`mise use --global uv`
gh	`brew install gh`	禁止使用mise（存在iTerm2兼容问题）
semgrep	`mise use --global semgrep`
node	`mise use --global node`
doppler	`mise use --global doppler`
prettier	`mise use --global npm:prettier`
jscpd	`npm i -g jscpd` (仅npm)

警告: gh CLI必须通过Homebrew安装，不能使用mise。通过mise安装的gh会导致Claude Code触发iTerm2标签页无限生成的问题。ADR

展示摘要格式（版本号从实际工具输出生成）：

=== 安装预检完成 ===

已找到：X个工具 | 缺失：Y个工具

你已安装的工具:
[OK] uv (<从uv --version命令输出获取>)
[OK] gh (<从gh --version命令输出获取>)
[x] gitleaks (缺失)
...

注意：本插件基于最新版本的工具开发，会保留你现有的安装版本。

缺失的工具将通过检测到的mise安装:
  gitleaks -> mise use --global gitleaks

如果HAS_MISE=false，请改为展示平台对应命令：

缺失的工具将通过brew安装:
  gitleaks -> brew install gitleaks

重要提示：版本号必须通过实际运行工具的版本命令动态获取，禁止硬编码版本号。

Todo 7: GATE - Await User Decision

待办7：确认关口 - 等待用户决策

If missing tools exist, STOP and ask user:

Use AskUserQuestion with these options:

question: "Would you like to install the missing tools?"
header: "Install"
options:
  - label: "Install missing"
    description: "Automatically install all missing tools"
  - label: "Skip"
    description: "Show manual install commands and exit"

IMPORTANT: Do NOT proceed to Phase 3 until user responds.

If ALL tools present: Mark todo completed, skip to "All set!" message, mark todos 8-9 as N/A.

如果存在缺失的工具，请停止流程并询问用户：

使用AskUserQuestion，附带以下选项：

question: "你是否想要安装缺失的工具？"
header: "安装"
options:
  - label: "安装缺失项"
    description: "自动安装所有缺失的工具"
  - label: "跳过"
    description: "展示手动安装命令并退出"

重要提示：在用户回复前，不要进入第3阶段。

如果所有工具都已安装：标记当前待办为完成，直接跳转到“全部就绪！”提示，将待办8-9标记为不适用（N/A）。

Phase 3: Installation (Conditional)

第3阶段：安装（条件执行）

Todo 8: Install Missing Tools

待办8：安装缺失工具

Only execute if:

User selected "Install missing"
OR
```
--install
```
flag was passed (skip interactive gate)

Run installation commands for missing tools only:

bash

/usr/bin/env bash << 'SETUP_EOF_2'
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/itp}"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --install
SETUP_EOF_2

If user selected "Skip":

Display manual install commands
Mark todo as skipped
Exit cleanly

仅在满足以下条件时执行：

用户选择了“安装缺失项”
或者传入了
```
--install
```
参数（跳过交互式确认关口）

仅运行缺失工具的安装命令：

bash

/usr/bin/env bash << 'SETUP_EOF_2'
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/itp}"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --install
SETUP_EOF_2

如果用户选择了“跳过”：

展示手动安装命令
将当前待办标记为跳过
正常退出流程

Todo 9: Verify Installation

待办9：验证安装

Re-run checks to confirm tools are now available:

bash

/usr/bin/env bash << 'PREFLIGHT_EOF'
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/itp}"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --check
PREFLIGHT_EOF

Mark todo completed only if verification passes.

重新运行检查确认工具现在可用：

bash

/usr/bin/env bash << 'PREFLIGHT_EOF'
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/itp}"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --check
PREFLIGHT_EOF

仅当验证通过时标记当前待办为完成。

Flag Handling

参数处理

Flag	Behavior
(none)	Default: Check -> Gate -> Ask permission
`--check`	Same as default (hidden alias)
`--install`	Check -> Skip gate -> Install automatically
`--yes`	Alias for `--install`

Parse

$ARGUMENTS

for flags:

bash

case "$ARGUMENTS" in
  *--install*|*--yes*)
    SKIP_GATE=true
    ;;
  *)
    SKIP_GATE=false
    ;;
esac

参数	行为
(无)	默认：检查 -> 确认关口 -> 征求用户许可
`--check`	和默认行为一致（隐藏别名）
`--install`	检查 -> 跳过确认关口 -> 自动安装
`--yes`	`--install` 的别名

解析

$ARGUMENTS

获取参数：

bash

case "$ARGUMENTS" in
  *--install*|*--yes*)
    SKIP_GATE=true
    ;;
  *)
    SKIP_GATE=false
    ;;
esac

Edge Cases

边界场景处理

Case	Handling
All tools present	Todos 1-6 complete, Todo 7 shows "All set!", Todos 8-9 marked N/A
Some missing, user says "install"	Todos 8-9 execute normally
Some missing, user says "skip"	Show manual commands, mark todos 8-9 as skipped
`--install` flag passed	Skip Todo 7 gate, proceed directly to install
macOS vs Linux	Todo 1 detects platform, install commands adapt

场景	处理方式
所有工具已安装	待办1-6完成，待办7展示“全部就绪！”，待办8-9标记为不适用
存在缺失工具，用户选择“安装”	待办8-9正常执行
存在缺失工具，用户选择“跳过”	展示手动安装命令，待办8-9标记为跳过
传入 `--install` 参数	跳过后待7的确认关口，直接进入安装流程
macOS vs Linux	待办1检测平台，安装命令自动适配对应系统

Troubleshooting

问题排查

graph-easy fails to install

graph-easy安装失败

bash

undefined

bash

undefined

Ensure cpanminus is installed first

brew install cpanminus

Then install Graph::Easy

cpanm Graph::Easy

undefined

cpanm Graph::Easy

undefined

semantic-release not found

semantic-release找不到

bash

undefined

bash

undefined

Install globally with npm

npm i -g semantic-release@25

Or use npx (no global install needed)

npx semantic-release --version

undefined

npx semantic-release --version

undefined

Permission errors with npm

npm权限错误

bash

/usr/bin/env bash << 'CONFIG_EOF'

bash

/usr/bin/env bash << 'CONFIG_EOF'

Fix npm permissions

mkdir -p ~~/.npm-global npm config set prefix '~~/.npm-global'

Add to your shell config

SHELL_RC="$([[ "$SHELL" == */zsh ]] && echo ~/.zshrc || echo ~~/.bashrc)" echo 'export PATH=~~/.npm-global/bin:$PATH' >> "$SHELL_RC" source "$SHELL_RC" CONFIG_EOF

---

SHELL_RC="$([[ "$SHELL" == */zsh ]] && echo ~/.zshrc || echo ~~/.bashrc)" echo 'export PATH=~~/.npm-global/bin:$PATH' >> "$SHELL_RC" source "$SHELL_RC" CONFIG_EOF

---

Next Steps

后续步骤

After setup completes, configure itp-hooks for enhanced workflow guidance:

Check hook status:
bash
```
/itp:hooks status
```
Install hooks (if not already installed):
bash
```
/itp:hooks install
```

设置完成后，配置itp-hooks以获得更完善的工作流指引：

检查钩子状态：
bash
```
/itp:hooks status
```
安装钩子（如果尚未安装）：
bash
```
/itp:hooks install
```

What hooks provide

钩子提供的能力

PreToolUse guard: Blocks Unicode box-drawing diagrams without
```
<details>
```
source blocks
PostToolUse reminder: Prompts ADR sync and graph-easy skill usage

IMPORTANT: Hooks require a Claude Code session restart after installation.

PreToolUse防护：拦截没有
```
<details>
```
源块的Unicode框线图
PostToolUse提醒：提示ADR同步和graph-easy skill使用

重要提示： 钩子安装后需要重启Claude Code会话才能生效。