Setup

---
name: setup
description: Check and install dependencies for itp-hooks (bun runtime, jq, and the optional linters its checks call).
allowed-tools: Read, Bash, TodoWrite, TodoRead, AskUserQuestion
argument-hint: "[--install|--check]"
model: haiku
disable-model-invocation: false
---

> **Prerequisite — `cc-plugin-root`.** This skill resolves its scripts with `cc-plugin-root <plugin>`
> (the `CLAUDE_PLUGIN_ROOT` placeholder is not a shell variable and expands to empty). If the command is missing, run
> `/itp:setup` (its first step installs it), or link it directly:
>
> ```bash
> mkdir -p ~/.local/bin && ln -sfn \
>   ~/.claude/plugins/marketplaces/cc-skills/scripts/cc-plugin-root ~/.local/bin/cc-plugin-root
> ```

# ITP Hooks Setup

Verify and install dependencies for the itp-hooks plugin:

- **jq** (required) - JSON processing for hook input/output
- **bun** (required) - Runtime for every TypeScript hook in the plugin
- **proto ≥ 0.61.3** (required only when `bun` is a proto shim) - hook commands call `bun` bare, and older proto can make Claude Code discard hook decisions; checked by `scripts/proto-floor.sh`
- **ruff** (optional) - Python silent failure detection
- **shellcheck** (optional) - Shell script analysis
- **oxlint** (optional) - JavaScript/TypeScript linting

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## Quick Start

Run dependency check:

```bash
/usr/bin/env bash << 'SETUP_EOF'
PLUGIN_DIR="$(cc-plugin-root itp-hooks)"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --check
SETUP_EOF
```

## Interactive Setup Workflow

### Step 1: Check Dependencies

```bash
/usr/bin/env bash << 'CHECK_EOF'
PLUGIN_DIR="$(cc-plugin-root itp-hooks)"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --check
CHECK_EOF
```

### Step 2: Present Findings

After running the check, present the findings to the user:

| Tool       | Status | Purpose                       |
| ---------- | ------ | ----------------------------- |
| jq         | ?      | Required for hook I/O         |
| bun        | ?      | Required for every TS hook    |
| ruff       | ?      | Python silent failure rules   |
| shellcheck | ?      | Shell script analysis         |
| oxlint     | ?      | JavaScript/TypeScript linting |

### Step 3: User Decision (if missing tools)

If optional linters are missing, use AskUserQuestion:

```
question: "Install optional linters for full silent failure detection coverage?"
header: "Linters"
options:
  - label: "Install all"
    description: "Install ruff, shellcheck, and oxlint for Python, Shell, and JS/TS coverage"
  - label: "Skip"
    description: "Continue with graceful degradation (detection only for installed linters)"
```

### Step 4: Install (if confirmed)

```bash
/usr/bin/env bash << 'INSTALL_EOF'
PLUGIN_DIR="$(cc-plugin-root itp-hooks)"
bash "$PLUGIN_DIR/scripts/install-dependencies.sh" --install
INSTALL_EOF
```

## Flags

| Flag        | Behavior                             |
| ----------- | ------------------------------------ |
| (none)      | Check dependencies, show status      |
| `--check`   | Same as default                      |
| `--install` | Check then install all missing tools |

## Graceful Degradation

The hooks work with graceful degradation:

| Tool Missing | Effect                                 |
| ------------ | -------------------------------------- |
| bun/node     | Fake-data-guard hook fails             |
| ruff         | Python files skip silent failure check |
| shellcheck   | Shell scripts skip analysis            |
| oxlint       | JS/TS files skip linting               |
| jq           | All hooks fail (required for JSON I/O) |

## Next Steps

No hook installation step exists. `hooks/hooks.json` in this plugin is what Claude Code loads, so enabling the plugin is the installation. The `/itp:tether install` path was retired in issue #127 — injecting the same hooks into `~/.claude/settings.json` double-registered them, and its script had been inert since `posttooluse-reminder.sh` became `posttooluse-reminder.ts`.

**IMPORTANT**: Restart the Claude Code session for newly enabled plugin hooks to take effect.

## Troubleshooting

| Issue                | Cause                 | Solution                          |
| -------------------- | --------------------- | --------------------------------- |
| jq not found         | jq not installed      | `brew install jq`                 |
| bun/node not found   | Runtime not installed | `proto install bun`               |
| ruff version error   | Outdated ruff         | `brew upgrade ruff`               |
| Plugin dir not found | Plugin not installed  | Re-install plugin via marketplace |
| PATH issues          | Shims not in PATH     | Add proto shims to ~/.zshenv      |

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.