fix: canonicalize doc paths and fix stale/hardcoded references

[striderZA]

Summary

Moves framework reference docs from .opencode/docs/ to docs/framework/ and fixes stale/hardcoded path references across the OCGS framework.

Changes

1. Framework docs relocated

.opencode/docs/ → docs/framework/ — 54 files (16 reference docs + 38 templates). Updates AGENTS.md project structure to document the directory.

2. Stale path fixes

• CLAUDE.md → AGENTS.md: 33 skills/agents referenced the non-existent CLAUDE.md instead of AGENTS.md
• .opencode/{agents,skills,commands}/ → .agents/: 21 files pointed at symlinked paths instead of canonical .agents/
• .claude/docs/ → docs/framework/: 3 workflow-catalog.yaml copies still referenced the original Claude Code path

3. Pi harness awareness

• MCP config sections (godot-mcp, unity-mcp) now show pi.json alongside opencode.json
• 5 Unity specialist agents updated to be harness-agnostic
• automated-smoke-test skill updated

Validation

• Zero stale .claude/, CLAUDE.md, .opencode/agents/, or .opencode/skills/ references remain (excluding intentional comparisons in README and historical docs)

[github-actions]

Now I have a thorough understanding of the PR. Here's my review:

---

PR Review: fix/doc-path-move

Overview

Large-scale path canonicalization PR (465 additions, 457 deletions, 100 files). Moves .opencode/docs/ → docs/framework/, replaces stale CLAUDE.md/.opencode/ symlink references with canonical .agents/ paths, and adds Pi harness awareness. Well-sequenced across 6 clean commits.

✅ What's done well

• Comprehensive coverage — zero stale .opencode/docs/, CLAUDE.md (excluding 3 intentional historical refs), .opencode/agents//.opencode/skills/ references remain
• Safe commit ordering — new docs first, then reference updates, then cleanup, preventing temporary breakage
• Dual-module sync — .agents/modules/ and .opencode/modules/ are both updated (45 refs each)
• Tests pass — agent validation (182 checks) passes cleanly

🔍 Issues

1. .opencode/{agents,skills,commands}/ are redundant copies, not symlinks
AGENTS.md documents these as → ../.agents/agents/ symlinks, but they're regular files (identical content verified by diff). This PR removes .opencode/docs/ (good) but leaves the other three stale directories intact. Not introduced here, but worth fixing while you're cleaning house. Pre-existing.

2. docs/framework/directory-structure.md:5 shows CLAUDE.md as root config
The PR exempts 3 CLAUDE.md references as "historical docs" — this file is a framework doc for OpenCode users, not original project history. Showing CLAUDE.md as the master config is misleading for new contributors. Should be AGENTS.md.

3. docs/framework/quick-start.md:216 — "Configures CLAUDE.md"
Same concern — this reads like an active instruction, not historical comparison. Could confuse someone following the quick-start guide.

4. .opencode/plugins/tests/test-validate-skill-change.mjs still references .opencode/skills/ paths
This test file wasn't included in the changeset. It tests detectSkillChange() which watches .opencode/skills/ — since those dirs still exist as copies, it won't break, but the test and function should arguably target .agents/skills/ instead.

💡 Suggestions

• Fix items 2 & 3 — update directory-structure.md and quick-start.md to reference AGENTS.md instead
• Fix item 4 or file a follow-up — the plugin test should target .agents/ paths
• Pre-existing: consider replacing .opencode/{agents,skills,commands}/ copies with actual symlinks to .agents/, as documented in AGENTS.md

Verdict

Good to merge. The core migration is thorough and well-executed. The issues above are minor (3 trivial doc fixes, 1 pre-existing pattern, 1 pre-existing test blind spot) — none are blocking.

opencode session  |  github run

[github-actions]

PR Review: fix/doc-path-move

Summary

✅ Good to merge. Clean, well-scoped canonicalization (501 additions, 486 deletions, 100 files). The previous review's concerns are largely addressed or inapplicable:

Verification results

Concern	Status
.opencode/{agents,skills,commands} copies vs symlinks	✅ Already symlinks — not copies
directory-structure.md references CLAUDE.md	✅ Already shows AGENTS.md (verified)
quick-start.md references CLAUDE.md	✅ Already shows AGENTS.md (line 216)
Plugin test references .opencode/skills/	✅ Intentional backward compat — function explicitly supports old paths for migration period

Remaining CLAUDE.md refs (all intentional)

• README.md (lines 73-78, 170-175) — migration comparison table
• docs/superpowers/plans/ & docs/superpowers/specs/ — historical design docs discussing .claude/ as a future-harness pattern

What's clean

• Zero stale CLAUDE.md in .agents/ skills, agents, or modules
• Zero stale .opencode/docs/ references
• Zero stale .opencode/agents/ or .opencode/skills/ refs in agent/skill files
• AGENTS.md project structure correctly shows docs/framework/ and .opencode/ symlinks
• docs/framework/directory-structure.md and quick-start.md reflect current layout
• automated-smoke-test skill updated with Pi harness awareness

Minor observation

The docs/superpowers/ .claude/ references (9 occurrences) are in design/spec documents for Pi agent support. They're forward-looking ("future harness"), not stale — but worth a cleanup pass if those docs ever graduate from spec to implementation. Not a blocker.

opencode session  |  github run