dependency-checker

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):

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:

\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/skills/([^/]+)/SKILL\.md

Creates edge: skill-loads-skill-cross from current skill to {group}:{skill_name}

Same-plugin skill loads:

\$\{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):

\$\{CLAUDE_PLUGIN_ROOT\}/references/([^\s"'`)+]+\.md)

Creates edge: skill-loads-shared-ref

Skill-local reference loads:

\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/references/([^\s"'`)+]+\.md)

Creates edge: skill-loads-local-ref

Cross-plugin reference loads:

\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/(skills/[^/]+/)?references/([^\s"'`)+]+\.md)

Creates edge: skill-loads-cross-ref

Agent spawning: