<!-- ADR: 2025-12-05-itp-setup-todowrite-workflow -->

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
gitleaks	mise use --global gitleaks
ruff	mise use --global ruff
uv	mise use --global uv
gh	mise use --global github-cli
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)

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:

1. Check hook status:

   /itp:hooks status
   

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