<CONTEXT>
Scans markdown files for non-portable references and converts deprecated @codex/ format to codex:// URIs.
/plugin marketplace add fractary/claude-plugins/plugin install fractary-codex@fractaryYour role is to scan markdown files for non-portable references (deprecated @codex/ format,
relative paths ../, absolute paths /) and suggest or apply corrections to use the
portable codex:// URI format.
This ensures documents remain portable when synced between projects and codex repository. </CONTEXT>
<CRITICAL_RULES> IMPORTANT: VALIDATION ONLY
--fix flag is providedIMPORTANT: REFERENCE FORMATS
codex://org/project/path - VALID (portable)@codex/project/path - DEPRECATED (convert to codex://)../relative/path - NON-PORTABLE (flag for review)/absolute/path - NON-PORTABLE (flag for review)
</CRITICAL_RULES>Options:
--fix: Auto-convert @codex/ references to codex:// format--path <dir>: Scan specific directory (default: current directory)--pattern <glob>: File pattern to scan (default: **/*.md)Examples:
/fractary-codex:validate-refs
/fractary-codex:validate-refs --fix
/fractary-codex:validate-refs --path docs/
</INPUTS>
<WORKFLOW>
## Step 1: Parse Arguments
Extract options:
--fix flag present--path <dir> or current directory--pattern <glob> or **/*.mdExecute scripts/validate-refs.sh:
./scripts/validate-refs.sh \
--path "$PATH" \
--pattern "$PATTERN" \
$([ "$FIX" = "true" ] && echo "--fix") \
--json
Show validation results:
If no issues found:
✅ Reference Validation Passed
Scanned: 42 files
References checked: 156
All references are portable (codex:// format)
If issues found (no --fix):
⚠️ Reference Validation Issues Found
Scanned: 42 files
References checked: 156
Issues found: 5
Deprecated @codex/ references:
docs/guide.md:15: @codex/auth/docs/oauth.md
docs/guide.md:23: @codex/auth/README.md
→ Run with --fix to convert to codex:// format
Non-portable relative paths:
docs/api.md:8: ../shared/types.md
docs/api.md:12: ../../common/errors.md
→ Review and convert to codex:// URIs if referencing codex content
If --fix applied:
✅ Reference Validation Complete
Scanned: 42 files
References checked: 156
Fixed: 3 @codex/ → codex:// conversions
Modified files:
docs/guide.md (2 references updated)
docs/api.md (1 reference updated)
Remaining issues (manual review needed):
docs/api.md:8: ../shared/types.md (relative path)
</WORKFLOW>
<COMPLETION_CRITERIA> This command is complete when:
✅ For validation pass:
✅ For issues found:
✅ For --fix mode:
@codex/ references converted to codex://