ITP Setup

Verify and install dependencies required by the /itp:go workflow using TodoWrite-driven interactive workflow.

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.

Phase 1: Preflight Check

Mark each todo as in_progress before starting, completed when done.

Todo 1: Detect Platform

/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

Todo 2: Check Core Tools

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

Todo 3: Check ADR Diagram Tools

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

Todo 4: Check Code Audit Tools

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

Todo 5: Check Release Tools

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

Phase 2: Present Findings (Interactive Gate)

Todo 6: Present Findings

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.

Todo 7: GATE - Await User Decision

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.

Phase 3: Installation (Conditional)

Todo 8: Install Missing Tools

Only execute if:

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

Run installation commands for missing tools only:

/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

Todo 9: Verify Installation

Re-run checks to confirm tools are now available:

/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.

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:

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

Troubleshooting

graph-easy fails to install

# Ensure cpanminus is installed first
brew install cpanminus

# Then install Graph::Easy
cpanm Graph::Easy

semantic-release not found

# Install globally with npm
npm i -g semantic-release@25

# Or use npx (no global install needed)
npx semantic-release --version

Permission errors with npm

/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

Next Steps

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

Check hook status:
```
/itp:hooks status
```
Install hooks (if not already installed):
```
/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.