fix: replace tilde paths with $HOME in v3.0 markdown instructions

[m4nt0de4]

Summary

Claude Code's Write/Edit tools use fs.writeFile() internally — they do not shell-expand ~. When the AI follows markdown instructions containing ~/.claude/... paths and passes them to Write/Edit tools, a literal directory named ~ is created in the current working directory instead of writing to the user's home directory.

This PR fixes 11 files across v3.0 where Write-facing markdown instructions used ~/.claude/ shorthand, replacing them with $HOME/.claude/ (with resolution notes where appropriate).

Root cause: The PAI system has two path systems:

• TypeScript tools (paths.ts, hooks) — use homedir() + join() → correct, unaffected
• Markdown instructions — use ~/.claude/ shorthand that the AI passes verbatim to Write/Edit → broken on all platforms

This is platform-agnostic — affects Linux, macOS, and WSL equally since Write/Edit are API-level file operations, not shell commands.

Files Changed (11 files, 20 insertions, 18 deletions)

File	Lines	Change
PAI/Components/Algorithm/v1.6.0.md	287, 664	PRD creation path + PATH RULE warning
PAI/SKILL.md	326, 703	Same (built version of Algorithm)
WorldThreatModelHarness/Workflows/UpdateModels.md	82, 86	Save/write model paths
WorldThreatModelHarness/SKILL.md	42	Model storage reference
Evals/Workflows/CreateUseCase.md	42, 100, 124, 176	4× Create file instructions
Evals/Workflows/CreateJudge.md	36	Create judge config
Evals/Workflows/CompareModels.md	49	Create comparison config
Evals/Workflows/ComparePrompts.md	79	Create comparison config
Research/Workflows/ExtractAlpha.md	382, 385	Scratch workspace + history paths
Agents/AgentProfileSystem.md	184	Agent profile creation
PAI/THEHOOKSYSTEM.md	163	Ratings write path

What Was NOT Changed

• Shell commands (mkdir -p ~/.claude/... in bash blocks) — shell correctly expands ~
• Read-only references (Read ~/.claude/...) — Read tool handles ~ correctly
• TypeScript code — already uses homedir() + join() via paths.ts
• User-facing documentation — ~ is fine in human-readable contexts

Testing

# Verify no Write-facing tilde paths remain in v3.0 skills:
cd Releases/v3.0/.claude/skills
grep -rn '~/.claude/' --include='*.md' | grep -iE '(create|write|save|work in)' | grep -v '```bash' | grep -v 'mkdir'
# Should return 0 results

Related

• Relates to plansDirectory: tilde (~) in path not resolved, creates literal ~/ directories #699 (tilde path expansion in plansDirectory setting)
• plansDirectory: tilde (~) in path not resolved, creates literal ~/ directories #699 addresses the installer/settings.json side; this PR addresses the AI-facing markdown instruction side

🤖 Generated with Claude Code

[fayerman-source]

Ran the test on WSL2 (Ubuntu). Checked all 11 changed files against the grep criteria from the PR description — all pass, no Write-facing tilde paths remaining in the changed files.

The broader grep -rn '~/.claude/' across the full skills directory returns results, but those are all shell commands inside bash code blocks or Read references in unrelated files — correctly out of scope for this PR.

Looks good to me.

[danielmiessler]

Thanks for this contribution! PAI v4.0 significantly restructured the architecture — new directory layout, Algorithm v3.6.0 (up from v1.x), hooks/lib/paths.ts for path resolution, and many of the underlying systems this PR targets have been rewritten.

This PR targets the v3.0 architecture and can't be cleanly applied to v4.0.x. Closing as superseded.

The latest release is v4.0.2. We're actively working on platform compatibility and other bigger items. If there's still a gap not covered by the new releases, we'd welcome a fresh PR against the current codebase. Thanks again!