richfrem/path-reference-auditor

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.