dependency-checker

What this skill does

# Dependency Checker

Analyze the Agent Alchemy plugin ecosystem to detect dependency issues, broken paths, orphaned components, and documentation drift. Produces a health report with severity-ranked findings.

**CRITICAL: Complete ALL 5 phases.** The workflow is not complete until Phase 5: Report is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

## Critical Rules

### AskUserQuestion is MANDATORY

**IMPORTANT**: You MUST use the `AskUserQuestion` tool for ALL questions to the user. Never ask questions through regular text output.

- Report presentation -> AskUserQuestion
- Action selection -> AskUserQuestion
- View mode selection -> AskUserQuestion

Text output should only be used for:
- Displaying progress updates between phases
- Presenting intermediate analysis summaries (inventory counts, graph stats)
- Phase transition markers

If you need the user to make a choice or provide input, use AskUserQuestion.

**NEVER do this** (asking via text output):
```
Would you like to view findings by severity or by plugin group?
1. By severity
2. By plugin group
```

**ALWAYS do this** (using AskUserQuestion tool):
```yaml
AskUserQuestion:
  questions:
    - header: "View Mode"
      question: "How would you like to view the findings?"
      options:
        - label: "By severity"
          description: "Group findings from critical to low"
        - label: "By plugin group"
          description: "Filter findings to a specific plugin group"
      multiSelect: false
```

### Plan Mode Behavior

**CRITICAL**: This skill performs an interactive analysis workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:

- **DO NOT** create an implementation plan for how to build the analysis
- **DO NOT** defer analysis to an "execution phase"
- **DO** proceed with the full analysis workflow immediately
- **DO** write report files as normal if `--report-file` is specified

## Phase Overview

Execute these phases in order, completing ALL of them:

1. **Load & Discover** — Parse arguments, load settings, build component inventory
2. **Build Dependency Graph** — Parse every component file to extract dependency edges
3. **Analyze** — Run 7 detection passes over the dependency graph
4. **Cross-Reference Documentation** — Compare graph against CLAUDE.md/README docs for drift
5. **Report** — Present findings interactively; optionally export

---

## Phase 1: Load & Discover

**Goal:** Parse arguments, load settings, build a complete component inventory of the plugin ecosystem.

### Step 1: Parse Arguments

Parse `$ARGUMENTS` for:
- `--plugin <group>` — Filter to one plugin group by short directory name (e.g., `core-tools`). Default: analyze all groups.
- `--verbose` — Include healthy/passing entries in the report, not just issues. Default: `false`.
- `--report-file <path>` — Export the full report as a markdown file to the given path. Default: none (interactive only).

Set variables:
- `FILTER_GROUP` from `--plugin` value (default: `null` = all groups)
- `VERBOSE_MODE` from `--verbose` flag (default: `false`)
- `REPORT_FILE` from `--report-file` value (default: `null`)

### Step 2: Load Settings

Read settings from `.claude/agent-alchemy.local.md` if it exists. Look for the `plugin-tools.dependency-checker` section in the YAML frontmatter.

| Setting | Default | Description |
|---------|---------|-------------|
| `severity-threshold` | `low` | Minimum severity to show: `critical`, `high`, `medium`, `low` |
| `check-docs-drift` | `true` | Whether to run Phase 4 documentation cross-referencing |
| `line-count-tolerance` | `10` | Percentage tolerance for line count drift in CLAUDE.md tables |

If the settings file doesn't exist or the section is missing, use defaults.

### Step 3: Load Marketplace Registry

Read the marketplace registry:
```
Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json
```

Build a registry map: `{ plugin_name -> { version, source_dir, description } }` for each entry in the `plugins` array. The `source_dir` is derived from the `source` field (strip leading `./`).

### Step 4: Discover Components

For each plugin group directory under `claude/` (or only `FILTER_GROUP` if set), enumerate all components using Glob:

**Skills:**
```
Glob: claude/{group}/skills/*/SKILL.md
```
For each found skill, read its YAML frontmatter to extract:
- `name`, `description`, `user-invocable`, `disable-model-invocation`
- `allowed-tools` list
- `skills` list (if present — for agent-like skill composition)

**Agents:**
```
Glob: claude/{group}/agents/*.md
```
For each found agent, read its YAML frontmatter to extract:
- `name`, `description`, `model`
- `tools` list
- `skills` list (these are skill bindings that must resolve to real skills)

**Shared references (plugin-level):**
```
Glob: claude/{group}/references/**/*.md
```

**Skill-local references:**
```
Glob: claude/{group}/skills/*/references/**/*.md
```

**Hooks:**
```
Glob: claude/{group}/hooks/hooks.json
```
If found, read and parse the JSON to extract hook entries.

**Hook scripts:**
```
Glob: claude/{group}/hooks/*.sh
```

### Step 5: Display Inventory Summary

Display a text summary of what was discovered:

```
[Phase 1/5] Plugin Ecosystem Inventory

| Group | Skills | Agents | Shared Refs | Skill Refs | Hooks | Scripts |
|-------|--------|--------|-------------|------------|-------|---------|
| core-tools | N | N | N | N | N | N |
| dev-tools | N | N | N | N | N | N |
| ... | ... | ... | ... | ... | ... | ... |
| **Total** | **N** | **N** | **N** | **N** | **N** | **N** |
```

---

## Phase 2: Build Dependency Graph

**Goal:** Parse every component file to extract all dependency edges, building a directed graph of the ecosystem.

### Step 1: Define Edge Types

The graph has the following edge types:

| Edge Type | Source | Target | Pattern |
|-----------|--------|--------|---------|
| `skill-loads-skill` | Skill | Skill (same plugin) | `${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.md` (without `/../`) |
| `skill-loads-skill-cross` | Skill | Skill (other plugin) | `${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.md` |
| `skill-loads-shared-ref` | Skill | Shared reference | `${CLAUDE_PLUGIN_ROOT}/references/{path}` |
| `skill-loads-local-ref` | Skill | Skill-local reference | `${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{path}` |
| `skill-loads-cross-ref` | Skill | Cross-plugin reference | `${CLAUDE_PLUGIN_ROOT}/../{group}/(skills/{name}/)?references/{path}` |
| `skill-spawns-agent` | Skill | Agent | `subagent_type` references in skill body |
| `skill-reads-registry` | Skill | Registry | `${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/` patterns |
| `agent-binds-skill` | Agent | Skill | `skills:` list in YAML frontmatter |
| `hook-runs-script` | Hook config | Hook script | `${CLAUDE_PLUGIN_ROOT}/hooks/{script}` in command strings |

### Step 2: Extract Edges from Skills

For each SKILL.md file discovered in Phase 1, scan the **full file content** (not just frontmatter) using these regex patterns:

**Cross-plugin skill loads:**
```regex
\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/skills/([^/]+)/SKILL\.md
```
Creates edge: `skill-loads-skill-cross` from current skill to `{group}:{skill_name}`

**Same-plugin skill loads:**
```regex
\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/SKILL\.md
```
Match only if the path does NOT contain `/../` before it. Creates edge: `skill-loads-skill` from current skill to `{skill_name}` within the same plugin.

**Shared reference loads (same plugin):**
```regex
\$\{CLAUDE_PLUGIN_ROOT\}/references/([^\s"'`)+]+\.md)
```
Creates edge: `skill-loads-shared-ref`

**Skill-local reference loads:**
```regex
\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/references/([^\s"'`)+]+\.md)
```
Creates edge: `skill-loads-local-ref`

**Cross-plugin reference loads:**
```regex
\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/(skills/[^/]+/)?references/([^\s"'`)+]+\.md)
```
Creates edge: `skill-loads-cross-ref`

**Agent spawning:**
```r