path-reference-auditor

name	path-reference-auditor
plugin	agent-scaffolders
description	Audit file path references in plugins and skills. Trigger with "audit path references", "check file references", "find broken references", "path reference audit", "verify paths", or when you need to validate that all ./references in code actually exist in the skill/plugin. Three-phase audit: (1) SCAN all files for references, (2) VERIFY each exists, (3) REPORT issues. Generates inventory.json for reuse across multiple checks.
allowed-tools	Bash, Read, Write

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See requirements.txt for the dependency lockfile (currently empty — standard library only).

---

Path Reference Auditor

Complete path reference audit system for plugins and skills. Ensures all ./file references in code actually exist.

What This Skill Does

Validates that file references in plugins and skills are:

• Skill-local: References in .agents/skills/Y/ stay within Y/
• Plugin-local: References in plugins/X/ (root level) stay within X/
• Resolvable: All ./ paths point to actual files (or symlinks)

Generates an inventory.json database of all references for reuse in multiple checks.

Three-Phase Audit

Phase 1: SCAN

Find all ./reference patterns in .py, .md, .mmd, .json, .sh files. Populates temp/inventory.json with raw reference data.

python ./scripts/path_reference_auditor.py --project . --phase scan

Output: temp/inventory.json with all references found

Phase 2: VERIFY

Read inventory.json and check if each reference exists in the skill/plugin. Updates inventory with status: exists/missing/symlink/broken.

python ./scripts/path_reference_auditor.py --project . --phase verify

Output: temp/inventory.json with status information

Phase 3: REPORT

Generate analysis reports from verified inventory (no rescanning needed).

# Summary
python ./scripts/path_reference_auditor.py --project . --phase report --report summary

# Missing files
python ./scripts/path_reference_auditor.py --project . --phase report --report missing

# Broken symlinks
python ./scripts/path_reference_auditor.py --project . --phase report --report broken_symlinks

Inventory location: All reports read from temp/inventory.json (generated by Phase 1 & 2)

Boundary Checks

Skill Boundary Violations

Flags references that point OUTSIDE a skill directory.

# All skills
python ./scripts/check_skill_boundaries.py temp/inventory.json --batch all

# Single skill (fast testing)
python ./scripts/check_skill_boundaries.py temp/inventory.json --skill adr-management

Example violation:

FILE: .agents/skills/adr-management/SKILL.md:45
  REF: ../../templates/adr-template.md  ❌ OUTSIDE SKILL
  FIX: Create symlink inside skill

Plugin Boundary Violations

Flags references in plugin root level that point OUTSIDE the plugin.

# All plugins
python ./scripts/check_plugin_boundaries.py temp/inventory.json --batch all

# Single plugin (fast testing)
python ./scripts/check_plugin_boundaries.py temp/inventory.json --plugin plugin-installer

Example violation:

FILE: plugins/adr-manager/commands/adr-management.md:8
  REF: ../../../docs/guide.md  ❌ OUTSIDE PLUGIN
  FIX: Copy/symlink file into plugin

Workflow

Complete Audit

# Step 1: Generate inventory (from project root)
python ./scripts/path_reference_auditor.py --project . --phase scan

# Step 2: Verify all references exist
python ./scripts/path_reference_auditor.py --project . --phase verify

# Step 3: Check skill boundaries
python ./scripts/check_skill_boundaries.py temp/inventory.json --batch all

# Step 4: Check plugin boundaries
python ./scripts/check_plugin_boundaries.py temp/inventory.json --batch all

# Step 5: Review violations and fix

Quick Test (Single Skill/Plugin)

# Test one skill during development
python ./scripts/check_skill_boundaries.py temp/inventory.json --skill my-skill

# Test one plugin after changes
python ./scripts/check_plugin_boundaries.py temp/inventory.json --plugin my-plugin

Scripts

• path_reference_auditor.py: Three-phase audit (scan → verify → report)
• check_skill_boundaries.py: Validate skill-level references stay internal
• check_plugin_boundaries.py: Validate plugin-level references stay internal

See references/ for detailed usage guide.

Key Features

✅ Inventory-based: Scan once, analyze multiple times ✅ Filtered testing: Test single skill/plugin without scanning all ✅ Boundary validation: Skill and plugin scope checks ✅ Portable: All paths relative to project root ✅ JSON output: Machine-parseable inventory for automation

Expected Triggers

• "Audit path references in my skills"
• "Find broken file references"
• "Verify all ./paths exist"
• "Check if skill references are contained"
• "Find references pointing outside plugin"
• "Path reference audit"
• "Validate skill boundaries"

---

Installation

Option 1: Install Single Skill (GitHub Hub)

For end users who want just this skill, consult the authoritative installation hub for current deployment logic:

👉 INSTALL.md

Then run from the skill directory:

python ./scripts/path_reference_auditor.py --project . --phase scan

Option 2: Install Full Plugin (Bridge Installer)

For developers who want all agent-scaffolders skills + commands + hooks:

# From project root, use the bridge installer
python ./scripts/plugin_installer.py plugins/agent-scaffolders

# Or manually
cp -r plugins/agent-scaffolders /path/to/target/plugins/

Then run from project root:

python .agents/skills/path-reference-auditor/./path_reference_auditor.py --project . --phase scan

---

Core Principles

Skill Boundary Rule

All file references inside .agents/skills/Y/ must resolve within Y/.

Valid:

• ./scripts/tool.py → .agents/skills/Y/scripts/tool.py ✅
• ./references/guide.md → .agents/skills/Y/references/guide.md ✅

Invalid:

• ../../templates/file.md → plugins/X/templates/file.md (outside skill) ❌
• ../other-skill/file.md → .agents/skills/other-skill/file.md (sibling skill) ❌

Fix: Create symlink inside the skill:

cd plugins/X/skills/Y
ln -s ../../templates templates

Plugin Boundary Rule

All file references inside plugins/X/ (root level, non-skill files) must resolve within X/.

Valid:

• ./commands/file.md → plugins/X/commands/file.md ✅
• ./skills/Y/SKILL.md → .agents/skills/Y/SKILL.md ✅

Invalid:

• ../other-plugin/file.md → plugins/other-plugin/file.md (sibling plugin) ❌
• ../../docs/guide.md → docs/guide.md (project root) ❌

Fix: Copy or symlink into plugin:

cd plugins/X
cp -r ../../docs ./docs
# or symlink
ln -s ../../docs ./docs

Symlink Strategy

Prefer symlinks over duplicating files:

1. Reduces redundancy
2. Keeps a single source of truth
3. Maintains correct boundaries (skill-local, plugin-local)
4. Fast to create, easy to maintain

Good:

# Inside skill, link to plugin-level resource
ln -s ../../templates ./templates

Avoid:

# Copying creates duplication
cp -r ../../templates ./templates

Inventory as Persistent Database

• Phase 1 (SCAN): Generate inventory.json once (30-60 seconds)
• Phase 2 (VERIFY): Check all references once (10-30 seconds)
• Phase 3 (REPORT): Run unlimited reports against inventory (< 1 second each)

Never rescan unnecessarily. Reuse inventory.json across multiple checks.