From b0ac772f47c38dea3fe5ed1e9653a6e16182b357 Mon Sep 17 00:00:00 2001 From: Terada Kousuke Date: Fri, 3 Apr 2026 11:35:18 +0900 Subject: [PATCH] docs: fix asset migration canon and inventory --- docs/ai-guardrails/README.md | 70 +++++- .../adr/003-claude-assets-migrate-by-role.md | 52 ++++ .../002-claude-asset-inventory-and-import.md | 47 ++++ docs/ai-guardrails/issues/README.md | 22 ++ .../migration/claude-code-skills-inventory.md | 224 ++++++++++++++++++ .../opencode/test/scenario/guardrails.test.ts | 40 ++++ 6 files changed, 454 insertions(+), 1 deletion(-) create mode 100644 docs/ai-guardrails/adr/003-claude-assets-migrate-by-role.md create mode 100644 docs/ai-guardrails/issues/002-claude-asset-inventory-and-import.md create mode 100644 docs/ai-guardrails/issues/README.md create mode 100644 docs/ai-guardrails/migration/claude-code-skills-inventory.md diff --git a/docs/ai-guardrails/README.md b/docs/ai-guardrails/README.md index 3331c6795843..7f9aafa925c3 100644 --- a/docs/ai-guardrails/README.md +++ b/docs/ai-guardrails/README.md @@ -25,6 +25,48 @@ This plan inherits the key philosophy from `claude-code-skills` epic `#130`, its That means the migration target is not "copy Claude hooks as-is." It is "preserve the operating model using OpenCode-native config, plugins, commands, permissions, and CI." +## Source canon + +Future implementation work should treat the following sources as normative, in this order: + +1. current platform semantics from official product docs +2. `claude-code-skills` README, epic `#130`, and accepted ADRs +3. harness-engineering references and skill-construction references that the source README already cites +4. this repo's ADRs, issue briefs, and scenario tests + +The main source set for this migration is: + +- `terisuke/claude-code-skills` README +- `terisuke/claude-code-skills` epic `#130` +- `terisuke/claude-code-skills` ADRs `001` to `004` +- `terisuke/claude-code-skills/docs/references/harness-engineering-best-practices-2026.md` +- `terisuke/claude-code-skills/docs/references/anthropic-skill-guide-summary.md` +- `terisuke/claude-code-skills/docs/requirements/design-requirements-2026-03-24.md` +- Claude Code official hooks and settings docs +- Anthropic skill guide PDF and summary +- OpenCode rules, skills, commands, and plugins docs + +At the time of writing, the source repository does not expose a separate document explicitly titled `BDF`, so the canonical reference set above is anchored to the documents that the source README, requirements, and epic `#130` actually cite. + +When these sources disagree: + +- use official runtime docs for concrete platform behavior +- use epic `#130` and harness best practices for guardrail philosophy +- use this repo's ADRs to document local implementation choices + +## Non-negotiables + +The following rules are mandatory for guardrail work in this fork: + +- mechanism before prose +- fastest reliable feedback layer first +- pointer-based instructions instead of long always-loaded prompts +- "implemented" is not "working"; scenario or CI proof is required +- migrate assets by role, not by naive one-to-one copying +- reuse Claude-compatible `SKILL.md` assets directly before rewriting them +- keep OpenCode core close to upstream unless a missing extension point proves otherwise +- do not let merge, release, or review freshness depend on agent goodwill alone + ## Goal Bootstrap the first thin-distribution slice that keeps OpenCode upstream-friendly while adding: @@ -65,6 +107,15 @@ Bootstrap the first thin-distribution slice that keeps OpenCode upstream-friendl - Default server exposure to localhost-only and default sharing to disabled. - Prove config precedence and project-local compatibility with scenario tests. +### Asset migration discipline + +- keep third-party Claude-only frameworks in `.claude` during transition +- keep representative `.claude/skills/*/SKILL.md` fixtures as migration truth data +- move organization-owned reusable skills into `.opencode/skills` only when ownership and packaging are stable +- move long-form repo rules into `AGENTS.md` plus `instructions` +- redesign hooks as plugins, commands, or CI policy instead of cloning Claude hook mechanics +- refuse implementation work that has not first been classified in the migration inventory or explicitly justified as an exception + ## Delivery phases 1. Freeze architecture decisions in ADRs. @@ -75,9 +126,18 @@ Bootstrap the first thin-distribution slice that keeps OpenCode upstream-friendl ## Tracking - Epic: [#1](https://github.com/Cor-Incorporated/opencode/issues/1) -- Current issue: [#2](https://github.com/Cor-Incorporated/opencode/issues/2) +- Current issue: [#3](https://github.com/Cor-Incorporated/opencode/issues/3) - Future slices remain separate issues so implementation can stay one issue per pull request. +Issue `#2` is the merged bootstrap base. + +Issue `#3` is complete only when: + +- the inventory is committed and kept current +- repo docs explain `.claude` vs `.opencode` ownership rules +- a representative Claude-compatible skill fixture is exercised in scenario tests +- future implementation work can point back to this source canon instead of relying on memory + ## Session rule When continuing this work in future sessions: @@ -91,10 +151,18 @@ When continuing this work in future sessions: - ADRs: `docs/ai-guardrails/adr/` - Issue briefs: `docs/ai-guardrails/issues/` +- Migration inventory: `docs/ai-guardrails/migration/` - Scenario tests: `packages/opencode/test/scenario/` - Thin distribution package: `packages/guardrails/` ## Primary references - OpenCode config: https://opencode.ai/docs/config +- OpenCode rules: https://opencode.ai/docs/rules +- OpenCode skills: https://opencode.ai/docs/skills +- OpenCode commands: https://opencode.ai/docs/commands +- OpenCode plugins: https://opencode.ai/docs/plugins - OpenCode server: https://opencode.ai/docs/server +- Claude Code hooks: https://docs.anthropic.com/en/docs/claude-code/hooks +- Claude Code settings: https://docs.anthropic.com/en/docs/claude-code/settings +- Anthropic skills guide PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf diff --git a/docs/ai-guardrails/adr/003-claude-assets-migrate-by-role.md b/docs/ai-guardrails/adr/003-claude-assets-migrate-by-role.md new file mode 100644 index 000000000000..2ffbbdb10a6e --- /dev/null +++ b/docs/ai-guardrails/adr/003-claude-assets-migrate-by-role.md @@ -0,0 +1,52 @@ +# ADR 003: Claude Assets Migrate By Role + +- Status: Accepted +- Date: 2026-04-03 + +## Context + +The source Claude harness contains skills, rules, hooks, and scripts. OpenCode can already read Claude-compatible rule and skill locations, but it does not offer a one-to-one clone of Claude hook semantics. + +Trying to copy every hook as-is would create brittle behavior and duplicate platform capabilities that OpenCode already provides. + +The source philosophy is not optional. `claude-code-skills` epic `#130`, the harness-engineering best-practices summary, and the Anthropic skill guide all push the same conclusion: preserve the operating model, not the literal file layout. + +## Decision + +Migrate Claude assets by role: + +- skills: reuse directly through `.claude/skills/*/SKILL.md` and `.opencode/skills/*/SKILL.md` +- rules: move to `AGENTS.md` plus `instructions` +- hooks: redesign as plugins, commands, or CI workflow gates +- scripts: keep only when they remain the simplest implementation unit + +Hook classes should be triaged into four buckets: + +- direct keep +- plugin rewrite +- command rewrite +- drop because OpenCode already covers it + +No implementation slice should skip this triage step. + +## Consequences + +### Positive + +- high reuse for skill assets +- lower migration risk for repo instructions +- clearer ownership of runtime guardrails + +### Negative + +- hook inventory and mapping work becomes a dedicated migration task +- some Claude-only lifecycle semantics need workflow redesign + +## Evidence + +- `claude-code-skills` README and epic `#130` +- `claude-code-skills/docs/references/harness-engineering-best-practices-2026.md` +- `claude-code-skills/docs/references/anthropic-skill-guide-summary.md` +- OpenCode rules and Claude compatibility: https://opencode.ai/docs/rules +- OpenCode skills and Claude-compatible discovery: https://opencode.ai/docs/skills +- OpenCode plugins and commands: https://opencode.ai/docs/plugins and https://opencode.ai/docs/commands diff --git a/docs/ai-guardrails/issues/002-claude-asset-inventory-and-import.md b/docs/ai-guardrails/issues/002-claude-asset-inventory-and-import.md new file mode 100644 index 000000000000..cd52e5283011 --- /dev/null +++ b/docs/ai-guardrails/issues/002-claude-asset-inventory-and-import.md @@ -0,0 +1,47 @@ +# Issue 002: Claude Asset Inventory And Import + +## Problem + +The Claude harness contains reusable assets, but they are not yet classified by what OpenCode can consume directly versus what must be redesigned. + +## Deliverables + +- migration inventory for skills, rules, hooks, and scripts +- direct-import path for Claude-compatible skills +- `AGENTS.md` plus `instructions` layout for long-form rules +- hook mapping table with target implementation type: + - plugin + - command + - CI gate + - drop + +## Acceptance + +- the inventory names each hook and assigns a migration bucket +- at least one representative `.claude/skills/*/SKILL.md` fixture is exercised by scenario tests +- repo guidance explains when to keep assets in `.claude` versus move them into `.opencode` + +## Current artifact + +- `docs/ai-guardrails/migration/claude-code-skills-inventory.md` + +## Additional rule + +Do not start plugin, command, or provider-lane implementation from memory alone. Classify the source asset first, then implement against the target bucket. + +## Dependencies + +- ADR 003 +- Issue 001 + +## Sources + +- `claude-code-skills` README +- `claude-code-skills` epic `#130` +- `claude-code-skills/docs/references/harness-engineering-best-practices-2026.md` +- `claude-code-skills/docs/references/anthropic-skill-guide-summary.md` +- `claude-code-skills/docs/requirements/design-requirements-2026-03-24.md` +- https://opencode.ai/docs/rules +- https://opencode.ai/docs/skills +- https://opencode.ai/docs/commands +- https://opencode.ai/docs/plugins diff --git a/docs/ai-guardrails/issues/README.md b/docs/ai-guardrails/issues/README.md new file mode 100644 index 000000000000..d289204f931d --- /dev/null +++ b/docs/ai-guardrails/issues/README.md @@ -0,0 +1,22 @@ +# AI Guardrails Issue Pack + +These issue briefs are intentionally written as implementation slices that can be handed to humans or agents. + +## Order + +1. `001-bootstrap-thin-distribution.md` +2. `002-claude-asset-inventory-and-import.md` +3. `003-guardrail-plugin-mvp.md` +4. `004-safe-agents-and-commands.md` +5. `005-provider-admission-policy.md` +6. `006-scenario-and-replay-harness.md` + +## Working rule + +No issue is complete unless: + +- acceptance criteria are met +- linked scenario tests are green +- any required ADR updates are committed in the same change set +- the implementation follows the source canon fixed in `docs/ai-guardrails/README.md` +- the work can ship as a single issue-scoped pull request diff --git a/docs/ai-guardrails/migration/claude-code-skills-inventory.md b/docs/ai-guardrails/migration/claude-code-skills-inventory.md new file mode 100644 index 000000000000..18ba24f32963 --- /dev/null +++ b/docs/ai-guardrails/migration/claude-code-skills-inventory.md @@ -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. + +It is intentionally philosophy-first. The migration is not "copy Claude hooks into a new runtime." The goal is to preserve the operating model while moving enforcement onto OpenCode-native extension points. + +This inventory is a gating artifact, not a loose note. If a future implementation cannot point to a row or rule in this document, that implementation needs an explicit ADR or inventory update first. + +## Source canon + +The inventory is derived from these sources: + +- `claude-code-skills` README +- `claude-code-skills` epic `#130` +- `claude-code-skills` ADRs `001` to `004` +- `claude-code-skills/docs/references/harness-engineering-best-practices-2026.md` +- `claude-code-skills/docs/references/anthropic-skill-guide-summary.md` +- `claude-code-skills/docs/requirements/design-requirements-2026-03-24.md` +- OpenCode official docs for rules, skills, commands, plugins, and agents +- Claude Code official docs for hooks and settings + +## Source Philosophy To Preserve + +The migration must preserve these non-negotiable ideas from `claude-code-skills` README, epic `#130`, and the source ADRs: + +- deterministic quality gates via mechanism, not prompt prose +- feedback speed hierarchy: fastest possible layer first +- pointer-based instructions: keep always-loaded instructions short and move detail to ADRs/docs +- "implemented" is not "working": deployment/runtime integrity must be verified as a system +- Codex and heavyweight automation are for bounded, mechanical, long-running work +- GitHub and release gates must not rely on agent goodwill alone + +## Migration Rules + +### Keep In `.claude` + +- third-party Claude-only frameworks that OpenCode does not consume directly +- source-of-truth migration fixtures during the transition +- local reference assets used to compare behavior against the original harness + +### Move To `.opencode` + +- organization-owned `SKILL.md` assets that OpenCode can discover directly +- project-local commands, agents, and plugins +- runtime guardrails that belong in the OpenCode config/profile layer + +### Move To `AGENTS.md` And `instructions` + +- short routing rules +- prohibitions that point to plugins, commands, CI, or ADRs +- numeric thresholds and workflow entrypoints + +### Move To CI Or Git Provider Policy + +- merge gates +- review freshness requirements +- branch protection +- post-merge automations +- deployment verification that must remain authoritative outside the local client + +### Drop + +- Claude-specific hook deployment integrity logic +- settings-local hook override protection that exists only because of Claude's hook model +- features already covered by OpenCode runtime behavior or by the thin-distribution packaging model + +## Skills + +These skills are direct-reuse candidates. OpenCode already discovers `.claude/skills/*/SKILL.md`, so the first migration step is to keep them intact and only move them into `.opencode/skills/` when ownership, naming, and packaging are stable. + +| 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. | +| `bugfix` | direct keep | Pure prompt asset. | +| `changelog-generator` | direct keep | Pure prompt asset. | +| `classify-review` | direct keep | Pure prompt asset; may later pair with GitHub command. | +| `code-reviewer` | direct keep | Core review asset. | +| `codex-review` | direct keep | Review asset that may later pair with wrapper commands. | +| `context7-skills` | direct keep | Prompt asset; tool wiring is separate. | +| `developer-growth-analysis` | direct keep | Prompt asset. | +| `file-organizer` | direct keep | Prompt asset. | +| `gcp-deploy-guardian` | direct keep | Prompt asset; runtime enforcement is separate. | +| `git-commit-helper` | direct keep | Prompt asset; commit gate remains outside skill. | +| `gws-workspace` | direct keep | Prompt asset. | +| `modern-architecture` | direct keep | Prompt asset. | +| `review-loop` | direct keep | Prompt asset; may later call OpenCode commands. | +| `security-review` | direct keep | Prompt asset. | +| `senior-architect` | direct keep | Prompt asset. | +| `senior-backend` | direct keep | Prompt asset. | +| `senior-frontend` | direct keep | Prompt asset. | +| `senior-fullstack` | direct keep | Prompt asset. | +| `skill-creator` | direct keep | Prompt asset. | +| `supabase-nextjs-debugger` | direct keep | Prompt asset. | +| `tdd-workflow` | direct keep | Prompt asset; gate logic moves elsewhere. | +| `test-falsify` | direct keep | Prompt asset. | +| `ui-design-system` | direct keep | Prompt asset. | +| `ui-skills` | direct keep | Prompt asset. | +| `ux-researcher-designer` | direct keep | Prompt asset. | + +## Rules + +Rules should not be copied verbatim into always-loaded OpenCode instructions. They should be compressed into pointers, with enforcement moved into plugins, commands, or CI. + +| Asset | Target | Notes | +|---|---|---| +| `rules/coding-style.md` | `AGENTS.md` + plugin pointers | Keep short style constraints and point to plugin/CI for enforcement. | +| `rules/delegation.md` | `AGENTS.md` + commands | Turn routing into `/implement`, `/review`, `/handoff`, and safe-agent defaults. | +| `rules/git-workflow.md` | `AGENTS.md` + CI | Keep branch/PR policy as pointers; enforce in CI/provider policy. | +| `rules/hook-deployment.md` | ADR + tests | Keep the lesson from epic `#130`; do not recreate Claude deployment mechanics. | +| `rules/quality.md` | `AGENTS.md` + plugin + CI | Keep completion definition and fact-check rules as pointers. | +| `rules/testing.md` | `AGENTS.md` + commands + CI | Keep test doctrine short; enforce through `/ship` and CI. | + +## Hooks + +Bucket definitions: + +- `plugin`: rewrite onto OpenCode plugin hooks, permissions, or session lifecycle +- `command`: rewrite as explicit slash-command or wrapper workflow +- `CI gate`: move to GitHub Actions / branch protection / server-side workflow gate +- `drop`: do not port directly; either Claude-specific or replaced by packaging/native behavior + +| Hook | Target | Why | +|---|---|---| +| `audit-docker-build-args.sh` | plugin | Fast local shell policy check before risky docker commands. | +| `auto-init-permissions.sh` | drop | Replaced by managed config and packaged profile defaults. | +| `block-codex-mcp.sh` | drop | Codex-MCP-specific policy is not part of the target OpenCode runtime. | +| `block-local-hooks-write.sh` | plugin | Protect OpenCode config/profile files from unsafe local override edits. | +| `block-manual-merge-ops.sh` | command | Replace raw merge-path blocking with explicit `/ship` workflow. | +| `block-merge-without-ci.sh` | CI gate | Branch protection / Actions should remain authoritative. | +| `block-merge-without-review.sh` | CI gate | Review freshness belongs in GitHub policy, not local shell heuristics alone. | +| `block-state-file-tampering-bash.sh` | plugin | Direct safety block on shell writes to guardrail state. | +| `block-state-file-tampering.sh` | plugin | Direct safety block on edit/write access to guardrail state. | +| `block-version-downgrade.sh` | plugin | Fast local block before weakening runtime/package baselines. | +| `codex-task-gate.sh` | command | External Codex delegation should go through wrapper commands, not ad hoc shell. | +| `codex-task-release.sh` | command | Companion state transition for command-mediated Codex delegation. | +| `context-budget-agent-gate.sh` | plugin | Runtime decision at tool-call time. | +| `context-budget-edit-write-gate.sh` | plugin | Runtime decision at tool-call time. | +| `context-budget-read-gate.sh` | plugin | Runtime decision at tool-call time. | +| `context-budget-reset.sh` | plugin | Session lifecycle state reset belongs in plugin state. | +| `context-budget-write-gate.sh` | plugin | Runtime decision at tool-call time. | +| `enforce-architecture-layers.sh` | plugin | Fast local structural reminder after edits. | +| `enforce-branch-workflow.sh` | CI gate | Branch naming/protection should be authoritative in provider policy. | +| `enforce-codex-delegation.sh` | plugin | Advisory routing is best decided at runtime before agent/tool use. | +| `enforce-codex-for-impl.sh` | command | Use explicit `/implement` or delegation workflow instead of shell hooking. | +| `enforce-deploy-verify-on-pr.sh` | CI gate | Deployment verification should be server-side and reviewable. | +| `enforce-develop-base.sh` | CI gate | PR base enforcement belongs in provider workflow policy. | +| `enforce-doc-update-scope.sh` | plugin | Fast local reminder tied to changed files. | +| `enforce-domain-naming.sh` | plugin | Fast local reminder tied to edited paths. | +| `enforce-endpoint-dataflow.sh` | plugin | Immediate structural reminder after endpoint edits. | +| `enforce-factcheck-before-edit.sh` | plugin | Runtime guard before risky edits. | +| `enforce-factcheck-before-user-request.sh` | plugin | Runtime guard before requesting manual user actions. | +| `enforce-factcheck-github-ops.sh` | plugin | Runtime guard before GitHub write operations. | +| `enforce-follow-up-limit.sh` | CI gate | PR lineage policy should be authoritative in Git workflow automation. | +| `enforce-git-freshness.sh` | plugin | Session-start/runtime reminder in the local client. | +| `enforce-hook-deploy-after-merge.sh` | drop | Claude hook deployment concern disappears in packaged OpenCode profile model. | +| `enforce-hook-deploy-integrity.sh` | drop | Claude hook deployment concern disappears in packaged OpenCode profile model. | +| `enforce-issue-close-verification.sh` | command | Explicit close/ship workflow should require evidence-based acceptance checks. | +| `enforce-memory-update-on-commit.sh` | command | Commit workflow should carry this check explicitly. | +| `enforce-post-merge-validation.sh` | CI gate | Post-merge operational checks should survive local client differences. | +| `enforce-review-reading.sh` | plugin | Fast local reminder/block before risky merge-like operations. | +| `enforce-seed-data-verification.sh` | CI gate | Data-safety verification belongs in shared automation. | +| `enforce-soak-time.sh` | CI gate | Release timing policy belongs in server-side merge policy. | +| `git-commit-guard.sh` | command | Commit path should go through explicit workflow command. | +| `git-push-guard.sh` | CI gate | Push/branch enforcement should not rely on local hook presence. | +| `inject-claude-review-helper.py` | command | Keep as helper logic only if needed behind OpenCode review commands. | +| `inject-claude-review-on-checks.sh` | command | Rewrite as OpenCode/GitHub review workflow command. | +| `mark-factcheck-done.sh` | plugin | Runtime state transition after successful verification actions. | +| `post-deploy-verify.sh` | CI gate | Deployment verification must remain shared, visible automation. | +| `post-lint-format.sh` | plugin | Preserve fastest feedback layer with OpenCode-native hooks. | +| `post-merge-close-issues.sh` | CI gate | Post-merge GitHub automation belongs in Actions/app workflow. | +| `post-pr-create-review-trigger.sh` | CI gate | PR lifecycle automation belongs in Actions/app workflow. | +| `pr-ci-review-gate.sh` | CI gate | Central PR gate should move to GitHub workflow plus optional local preflight command. | +| `pr-guard.sh` | command | Local preflight belongs in explicit PR/ship command. | +| `pr-merge-claude-review-gate.sh` | CI gate | Merge gating belongs in provider workflow policy. | +| `pre-compact-context-save.sh` | plugin | OpenCode already exposes compaction hooks. | +| `protect-branches.sh` | CI gate | Branch protection should be authoritative in provider policy. | +| `protect-linter-config.sh` | plugin | Fast local block before config weakening edits. | +| `record-code-review.sh` | plugin | Runtime state recording after review agents complete. | +| `record-codex-review.sh` | plugin | Runtime state recording after delegated review completes. | +| `reset-factcheck.sh` | plugin | Session lifecycle reset belongs in plugin state. | +| `stop-test-gate.sh` | command | Rewrite as explicit completion/ship verification command. | +| `task-completion-gate.sh` | command | Rewrite as explicit completion/ship verification command. | +| `tool-failure-recovery.sh` | plugin | Runtime recovery assistance belongs in plugin lifecycle. | +| `track-agent-team.sh` | plugin | Runtime state tracking belongs in plugin lifecycle. | +| `validate-hook-deployment.sh` | drop | Claude hook deployment concern disappears in packaged OpenCode profile model. | +| `validate-no-local-hooks.sh` | drop | Claude settings-local hook override concern does not carry over directly. | +| `verify-agent-output.sh` | plugin | Runtime post-execution verification fits OpenCode plugin hooks. | +| `verify-codex-output.sh` | plugin | Runtime post-execution verification fits OpenCode plugin hooks. | +| `verify-state-file-integrity.sh` | plugin | Runtime post-execution verification fits OpenCode plugin hooks. | +| `verify-test-falsifiability.sh` | plugin | Fast local reminder after test file changes. | +| `workflow-sync-guard.sh` | CI gate | Workflow consistency is best enforced in shared CI. | + +## Utility Scripts + +| Asset | Target | Notes | +|---|---|---| +| `scripts/check-pr-reviews.sh` | CI gate | Server-side review freshness is more trustworthy. | +| `scripts/codex-orchestrate.sh` | command | Candidate backend for explicit delegation workflows. | +| `scripts/codex-parallel.sh` | command | Candidate backend for explicit delegation workflows. | +| `scripts/context-monitor.py` | drop | Useful as reference, not required for MVP OpenCode migration. | +| `scripts/delivery_score.py` | CI gate | Better as reporting/analytics than local runtime guard. | +| `scripts/verify-pr-review.sh` | CI gate | Server-side review verification should remain authoritative. | + +## Immediate Implications For This Repo + +- `Issue 001` should stay thin: wrapper, managed config, packaged profile. +- `Issue 002` is complete only when this inventory remains current and scenario coverage for `.claude/skills` stays green. +- `Issue 003` should focus on plugin rewrites that preserve fast feedback and system-level verifiability. +- `Issue 004` should turn command-bucket items into explicit safe workflows like `/implement`, `/review`, `/ship`, and `/handoff`. +- `Issue 005` should keep provider policy declarative and independent from one transient model brand. + +## What Success Looks Like + +Success is not "we copied most files." + +Success is: + +- OpenCode core remains close to upstream +- organization policy lives in profile/plugin/command/CI layers +- direct-reuse skills still work during migration +- important gates are verifiable in tests or CI +- no critical workflow depends on a hidden local hook deployment step diff --git a/packages/opencode/test/scenario/guardrails.test.ts b/packages/opencode/test/scenario/guardrails.test.ts index e4a0539af986..a678e66bd787 100644 --- a/packages/opencode/test/scenario/guardrails.test.ts +++ b/packages/opencode/test/scenario/guardrails.test.ts @@ -69,6 +69,46 @@ test("guardrails package pins the runtime to the packaged opencode version", asy expect(guardrails.dependencies.opencode).toBe(opencode.version) }) +test("claude-compatible skills remain discoverable and command-addressable", async () => { + await using tmp = await tmpdir({ + git: true, + init: async (dir) => { + await Bun.write( + path.join(dir, ".claude", "skills", "review-loop", "SKILL.md"), + `--- +name: review-loop +description: Review loop from Claude-compatible assets. +--- + +# Review Loop +`, + ) + await Bun.write( + path.join(dir, ".opencode", "skills", "ship-gate", "SKILL.md"), + `--- +name: ship-gate +description: Internal ship gate skill. +--- + +# Ship Gate +`, + ) + }, + }) + + await Instance.provide({ + directory: tmp.path, + fn: async () => { + const skills = await Skill.all() + const cmds = await Command.list() + + expect(skills.map((item) => item.name).sort()).toEqual(["review-loop", "ship-gate"]) + expect(cmds.some((item) => item.name === "review-loop" && item.source === "skill")).toBe(true) + expect(cmds.some((item) => item.name === "ship-gate" && item.source === "skill")).toBe(true) + }, + }) +}) + test("guardrail profile keeps defaults while allowing project-local commands, agents, and skills", async () => { const prev = process.env.OPENCODE_CONFIG_DIR process.env.OPENCODE_CONFIG_DIR = profile