verifying-agnosticism

name: verifying-agnosticism description: Scan and fix hardcoded paths, project-specific references, and environment-coupled values in agents, skills, hooks, and orchestration files to ensure portability across repos. Use when auditing or onboarding template files.

Verifying Agnosticism

Ensures agents, skills, hooks, and orchestration files are portable across repos by detecting and fixing hardcoded paths and project-specific references.

Quick Start

Scan for hardcoded paths

# Scan .claude/ and .codex/ for absolute paths
node .claude/skills/verifying-agnosticism/scripts/scan-hardcoded-paths.js

# Scan a specific directory
node .claude/skills/verifying-agnosticism/scripts/scan-hardcoded-paths.js --dir .claude/hooks

Manual grep check

grep -rn "C:\\\\coding\|C:/coding\|/home/\|/Users/" .claude/ .codex/ .adr/ \
  --include="*.js" --include="*.ps1" --include="*.sh" --include="*.json" --include="*.md"

Zero matches = fully agnostic.

What to Scan For

Blocking (Must Fix)

Pattern	Where	Fix
`C:\coding\apps\<project>`	`.js`, `.ps1`, `.sh` scripts	Derive from `__dirname` / `$PSScriptRoot` / `git rev-parse`
`"workdir": "C:\\..."`	`.json` queue/template files	Use empty string `""` (let consumer resolve)
`const BASE_DIR = '...'`	JS sync scripts	Accept `--base-dir` arg, fallback to `__dirname` resolution
`PROJECT_ROOT="C:/..."`	Shell scripts	Use `$(git rev-parse --show-toplevel)`

Portability (Should Fix)

Pattern	Where	Fix
Project names (`Hytale`, `wavz.fm`)	Docs, READMEs, CODEX.md	Use `<PROJECT_ROOT>` placeholder
Session names in templates	Queue templates	Use `<SESSION_KEY>` placeholder
`dryRun: true` in prod templates	JSON templates	Default to `false` for production use

Cosmetic (Nice to Fix)

Pattern	Where	Fix
Hardcoded paths in Mermaid diagrams	SKILL.md docs	Use `<PROJECT_ROOT>`
Project-specific examples	Code blocks in docs	Use generic examples

Fix Patterns

PowerShell — Derive repo root from script location

# Script at .claude/hooks/scripts/foo.ps1 → 3 levels up
$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path

Node.js — Accept CLI arg with __dirname fallback

// Script at .claude/skills/<skill>/scripts/foo.js → 4 levels up
function resolveBaseDir() {
  const idx = process.argv.indexOf('--base-dir');
  if (idx !== -1 && process.argv[idx + 1]) return path.resolve(process.argv[idx + 1]);
  return path.resolve(__dirname, '..', '..', '..', '..');
}

Shell — Use git root

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

JSON Templates — Empty workdir

{ "workdir": "" }

Consumer scripts should interpret empty workdir as "use the repo root".

Documentation — Placeholder

Main App: `<PROJECT_ROOT>/.claude/`

Verification Checklist

After fixing, verify:

grep -rn for absolute paths returns zero matches in scripts
Queue template has "workdir": ""
PowerShell scripts derive paths from $PSScriptRoot
Node.js scripts use __dirname or CLI args for base paths
Shell scripts use git rev-parse --show-toplevel
Documentation uses <PROJECT_ROOT> placeholders
No project-specific names remain in template files

Agent: .claude/agents/agnostic-verifier/agent.md
Scan script: .claude/skills/verifying-agnosticism/scripts/scan-hardcoded-paths.js