docs: fix asset migration canon and inventory#10
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the AI guardrails documentation canon and migration guidance for importing Claude-compatible assets, and adds scenario coverage to ensure .claude/skills/*/SKILL.md discovery remains compatible during migration.
Changes:
- Add a scenario test asserting both
.claude/skillsand.opencode/skillsskills are discoverable and exposed as skill-backed commands. - Define a “source canon” and migration discipline in
docs/ai-guardrails/README.mdto bind future implementation to upstream references and local ADRs/tests. - Add an initial Claude asset inventory, issue-pack guidance, and an ADR defining the role-based migration approach.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/opencode/test/scenario/guardrails.test.ts | Adds scenario coverage for Claude-compatible skill discovery and command listing. |
| docs/ai-guardrails/README.md | Establishes source canon, non-negotiables, and migration discipline for .claude vs .opencode. |
| docs/ai-guardrails/migration/claude-code-skills-inventory.md | Introduces an inventory/mapping of upstream assets into migration buckets. |
| docs/ai-guardrails/issues/README.md | Adds an “issue pack” index and working rule for issue completeness. |
| docs/ai-guardrails/issues/002-claude-asset-inventory-and-import.md | Adds the issue brief defining deliverables/acceptance for inventory + import. |
| docs/ai-guardrails/adr/003-claude-assets-migrate-by-role.md | Adds an accepted ADR describing role-based migration strategy. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,224 @@ | |||
| # Claude Asset Inventory | |||
|
|
|||
| This document maps the source assets in `/Users/teradakousuke/Developer/claude-code-skills` into the thin-distribution plan for OpenCode. | |||
There was a problem hiding this comment.
This doc hard-codes a local absolute filesystem path (/Users/.../claude-code-skills). That won’t be meaningful to other contributors/CI and can become stale. Replace with a repo URL/reference (e.g., the upstream GitHub repo) or a relative path description of where the source was audited from.
| This document maps the source assets in `/Users/teradakousuke/Developer/claude-code-skills` into the thin-distribution plan for OpenCode. | |
| This document maps the source assets from the `claude-code-skills` repository into the thin-distribution plan for OpenCode. |
| | Asset | Target | Notes | | ||
| |---|---|---| | ||
| | `adk-engineer` | direct keep | OpenCode-compatible `SKILL.md` asset. | | ||
| | `agent-orchestrator` | direct keep | High-value source for future safe-agent orchestration. | | ||
| | `brainstorming` | direct keep | Pure prompt asset. | |
There was a problem hiding this comment.
The markdown tables are formatted with a leading double pipe (|| ...), which renders as an extra empty column in GitHub-flavored Markdown. Use standard table syntax with a single leading | for the header and each row so the table renders correctly.
| - direct keep | ||
| - plugin rewrite | ||
| - command rewrite | ||
| - drop because OpenCode already covers it |
There was a problem hiding this comment.
ADR 003’s hook bucket list doesn’t match the inventory/issue brief buckets. Here it lists direct keep but omits CI gate, while the inventory defines plugin, command, CI gate, and drop. Align the ADR’s bucket definitions with the inventory so future implementation work doesn’t follow conflicting guidance.
| - direct keep | |
| - plugin rewrite | |
| - command rewrite | |
| - drop because OpenCode already covers it | |
| - plugin | |
| - command | |
| - CI gate | |
| - drop |
Summary
.claude/skills/*/SKILL.mddiscovery so direct-import compatibility stays verifiedPhilosophy
Verification
cd packages/opencode && bun test test/scenario/guardrails.test.tscd packages/opencode && bun typecheckNote
BDFinclaude-code-skillsor epic feat(guardrails): Wave 8 — review fixes + remaining hooks + multi-model delegation #130, so this PR fixes the canon around the documents that the source README and requirements actually cite.Closes #3