---
name: path-reference-auditor
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:**
```bash
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.

```bash
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.

```bash
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).

```bash
# 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.

```bash
# 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.

```bash
# 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
```bash
# 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)
```bash
# 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](https://github.com/richfrem/agent-plugins-skills/blob/main/INSTALL.md)

Then run from the skill directory:
```bash
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:

```bash
# 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:
```bash
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:
```bash
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:
```bash
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:**
```bash
# Inside skill, link to plugin-level resource
ln -s ../../templates ./templates
```

**Avoid:**
```bash
# 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.