opencode-import

name	opencode-import
description	Scan real OpenCode artifacts (~/.config/opencode/, .opencode/, ~/.opencode/) for skills (full trees), commands, agents, and rules. Perform high-fidelity import into this opencode-bridge plugin so everything appears as [plugin: opencode-bridge]. Commands become real skills (providing /slash commands). Rules go to the working ~/.grok/rules/ side-channel (clean bodies + original .mdc frontmatter preserved as comments). Supports /opencode-import, --sync, --validate. Interactive, idempotent, review-gated, no injected prefixes on your content.
when-to-use	Use when the user mentions OpenCode, .opencode, opencode-import, opencode-sync, or asks to import/convert/migrate OpenCode agents/skills/commands/rules into Grok. Also auto-suggested by the SessionStart hook when artifacts are present.
argument-hint	[--sync | --validate | --help] [source-path]

opencode-import (Grok OpenCode Bridge — Proper Plugin Edition)

You are the orchestrator for the correct opencode-bridge plugin.

Core rules (non-negotiable):

• Never inject the old verbose "Grok OpenCode Bridge — Converted Artifact", Import ID, or "do not edit directly" text into any imported SKILL.md, command file, agent, or rule body. Imported content must remain clean originals.
• Traceability is provided by: (1) living inside plugins/opencode-bridge/, (2) MAPPING.md + IMPORTS.json + IMPORT_REPORT_*.md, (3) the one-line source comment only where strictly necessary for rules.
• Walk the actual filesystem tree from the user's real OpenCode locations. Do not assume folder layouts.
• command/*.md become first-class Grok skills (so they appear as real slash commands like /opencode-build).
• Full skill trees (including scripts/, schemas/, subdirectories like avular/*) are copied exactly via cp -a after user approval.
• Rules (.mdc + AGENTS.md) are emitted clean to ~/.grok/rules/opencode-<...>.md with original frontmatter preserved in a leading HTML comment block.
• Every multi-step import uses todo_write for visibility.
• Large plans use secure body extraction under GROK_PLUGIN_DATA to keep context small.
• Always resolve ~/.grok via $HOME (never construct paths that can produce .grok/.grok/).

Discovery (exact real structure)

1. Locate sources in priority order:

   • $(pwd)/.opencode or $(pwd)/.config/opencode (project)
   • ~/.config/opencode (primary for this user)
   • ~/.opencode
   • Any explicit path passed as argument.

2. Read opencode.json (if present) for the instructions array (respects ordering/selection).

3. Walk and classify exactly what exists:

   • skills/<name>/ — every directory containing a SKILL.md (capture the full subtree: scripts/, *.md, schemas/, subdirs, etc.).
   • command/*.md — each becomes a skill (name derived as opencode-<kebab>).
   • agent/*.md — converted into proper Grok agent definitions (inside the plugin) and matching roles in ~/.grok/roles/opencode-*.toml. This makes them appear in Ctrl+Shift+A (subagent catalog) and usable via subagent_type, similar to builtins.
   • rules/<category>/*.mdc + root AGENTS.md — rules.
   • Record real relative paths for the plan.

4. Compute content hashes (full tree for skills, body for others) for idempotent sync.

Commands

• /opencode-import --validate or --dry-run → produce and display the plan only. No writes.
• /opencode-import (default) or with explicit source → interactive review (show todo plan, counts, warnings, sample diffs) then (on explicit user approval) apply.
• /opencode-import --sync → same as above but only act on changed artifacts (hash or mtime diff).
• /opencode-import --help → this document.

Review & Apply Flow (use todo_write)

1. Build plan (via Python helpers in scripts/).

2. Present summary + todo_write board:

   • Skills to import (with tree size)
   • Commands → skills
   • Agents
   • Rules (with .mdc frontmatter note)
   • Collisions / warnings (native skills are skipped with clear message)

3. User reviews. Use ask_user_question for any blocking decisions.

4. On approval:

   • For skills: use run_terminal_command with cp -a --preserve of the entire source skill directory into plugins/opencode-bridge/skills/<name>/ (exact).
   • For commands: synthesize a clean SKILL.md (original content + "Use when the user invokes the original OpenCode command or asks to " in description) under this plugin's skills/.
   • For agents: convert to Grok-native format (in plugin) + create corresponding role in ~/.grok/roles/ + prepare [subagents.roles] entries for config.toml (with diff + confirmation step so they appear in Ctrl+Shift+A).
   • For rules: emit clean bodies to ~/.grok/rules/opencode-<category>-<name>.md (one leading <!-- original .mdc frontmatter ... --> block only; no other injection).

5. Special step for agents: After the Python helper creates the roles in ~/.grok/roles/, check the import data directory (GROK_PLUGIN_DATA/imports/<id>/) for config_roles_to_append.txt and proposed_config_roles_diff.txt.

   • If present, display the diff to the user.
   • Use ask_user_question to get explicit confirmation before appending the [subagents.roles] entries to ~/.grok/config.toml (using search_replace or a safe append).
   • This is the step that makes the new agents appear in Ctrl+Shift+A.

6. Update this plugin's IMPORTS.json, MAPPING.md, and write IMPORT_REPORT_<id>.md inside the plugin.

7. Record last-sync timestamp + import_id under GROK_PLUGIN_DATA.

Path Safety & Hygiene

• Always compute Grok home as $HOME/.grok.
• Never write anything that would create .grok/.grok/.
• Use GROK_PLUGIN_ROOT and GROK_PLUGIN_DATA (available to hooks and via env in terminal helpers).
• After any write phase, run grok plugin validate . and grok inspect (or instruct user) as final gate.

Post-Import Verification (the user will run these)

• grok plugin validate ~/.grok/plugins/opencode-bridge → must pass cleanly.
• grok plugin details opencode-bridge → shows the imported skills/agents.
• ls ~/.grok/roles/opencode-* → shows generated roles for the imported agents (enables them in Ctrl+Shift+A).
• After confirmation, your config.toml will contain the new [subagents.roles.opencode-*] entries.
• /skills and /<imported-name> work for both native OpenCode skills and command-derived ones.
• New session shows rules from the bridged set in context.
• grep -r "Grok OpenCode Bridge" plugins/opencode-bridge/skills/ ~/.grok/rules/opencode-* → finds nothing (clean guarantee).

Implementation Helpers

All heavy logic lives in scripts/ (see scan.py, convert.py, etc.). The model invokes them via run_terminal_command exactly as other complex skills do (e.g. cd .../opencode-import && python3 -m scripts scan --plan ...).

You have access to the full suite of tools (write, search_replace, run_terminal_command, todo_write, spawn_subagent, ask_user_question, etc.).

Execute the plan with the smallest correct changes, maximum fidelity to the real source tree on disk, and zero pollution of imported content.