Skip to content

ROADMAP.md

Latest commit

 

History

History
825 lines (614 loc) · 38.8 KB

ROADMAP.md

File metadata and controls

825 lines (614 loc) · 38.8 KB
Raw

ix-opencode-plugin Roadmap

Task Tracking Rule

Any AI agent or human working on this roadmap must update task fields directly inside this file.

When starting a task:

  • Change Status to In Progress
  • Fill in Started By
  • Fill in Start Date
  • Update Last Updated
  • Add a note to Progress Log

When completing a task:

  • Change Status to Done
  • Fill in Completed By
  • Fill in Completion Date
  • Update Last Updated
  • Write a concise Change Summary

When blocked:

  • Change Status to Blocked
  • Explain the blocker in Progress Log

Do not mark a task as done unless all acceptance criteria are satisfied.

Overview

Role: Overhaul Target — OpenCode surface.

ix-opencode-plugin is the OpenCode-native implementation of the Ix plugin family. It is live at v1.0.0 production. It exposes Ix capabilities via seven TypeScript tools and five plugin hooks, with seven slash-command skills and five agents.

Reference implementations:

  • Ambient behavior, skills, and agents: Match ix-claude-plugin (Claude reference). All seven skills must have identical names, phased reasoning protocols, and output semantics. All five ambient behaviors (session briefing, pre-edit gate, post-edit ingest, search interception, session-end map refresh) must produce the same user-visible effect as the Claude plugin, using the closest available OpenCode mechanism.
  • Tool surface: Match ix-cursor-plugin (Cursor reference) for tool semantics. The 17-tool target set mirrors the Cursor MCP server's tool set. Where Cursor uses MCP tools, OpenCode uses TypeScript plugin tool functions. Output format differs (OpenCode returns strings; Cursor returns JSON envelopes), but capability coverage must be identical.

Platform equivalence mapping:

Claude mechanism OpenCode equivalent Gap / Fallback
Bash hook: UserPromptSubmit (briefing) AGENTS.md always-on instruction No per-prompt TTL; briefing is always-on
Bash hook: PreToolUse Edit|Write (pre-edit gate) tool.execute.before on write tools May not intercept subagent tool calls (known open issue)
Bash hook: PostToolUse Edit|Write (post-edit ingest) tool.execute.after or file.edited Confirmed available; use tool.execute.after
Bash hook: PreToolUse Grep|Glob (search intercept) tool.execute.before on bash/read No dedicated Grep/Glob matcher; Bash detection only
Bash hook: Stop (session-end map) No native session-end hook Defer to next session startup or manual ix-ingest tool call
Claude skill files (skills/ix-*/SKILL.md) OpenCode slash commands (commands/*.md) Same markdown format; path differs
Claude agent specs (agents/*.md) OpenCode agent configs (agents/*.json) Format differs; semantic role identical

When a platform mechanism is unavailable, mark it explicitly as Unsupported in AGENTS.md and describe the fallback behavior. Do not silently omit behaviors.

What is being done: Two parallel tracks. First, expand the tool set from 7 to 17 tools (matching the Cursor MCP server) to close the capability gap. Second, migrate all tool implementations from ix CLI subprocess calls to the Ix Core Runtime API. Additionally: add an ix-help slash command, verify MCP support and Bun vs Node.js compatibility, and add a session-start lifecycle hook if OpenCode supports it.

Phase 0: Current State Audit

Task: Audit existing 7 tools and their ix CLI calls

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Audited all 7 tools. All use Bun $ shell API (import { $ } from 'bun'). No base.ts exists. Tools: ix-query (ix locate + ix explain), ix-neighbors (ix callers/callees/depends/imported-by), ix-impact (ix impact + ix callers), ix-map (ix subsystems + ix stats), ix-ingest (ix status probe + ix map refresh), ix-history (ix briefing + ix decisions, Pro only), ix-docs-tool (ix locate + ix overview + ix explain + ix impact). All return markdown strings. All fail non-fatally.

Goal: Read all seven tool files in tools/ and document the exact ix CLI commands each calls, along with the output parsing logic.

Current State Context: Seven tools: ix-query.ts (ix locate), ix-neighbors.ts (ix callers/callees/depends/imports), ix-impact.ts (ix impact), ix-map.ts (ix map), ix-ingest.ts (ix status + ix map), ix-history.ts (ix history, Pro only), ix-docs-tool.ts (ix docs). All call through base.ts. Tools return strings (not JSON objects — confirmed OpenCode constraint).

Implementation Notes: Read each tool file. Document CLI args, output parsing, error handling, and string return format. Note which tools use --json flag vs raw text parsing.

Files Expected to Change:

  • tools/*.ts (read-only audit)
  • plugins/ix-plugin.ts (read-only audit)

Acceptance Criteria:

  • All seven tools catalogued with their CLI call sites
  • Output format (string return constraint) confirmed
  • Error handling patterns documented
  • plugins/ix-plugin.ts tool registration confirmed

Progress Log:

  • Completed 2026-05-07.

Task: Audit hooks, commands, agents, and opencode.json

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: All 5 hooks confirmed in ix-plugin.ts. ix-ingest hook already wired to tool.execute.after (not plugin-init — ROADMAP description was wrong). onInit already triggers ix map on empty graph. All 7 commands and 5 agent JSONs confirmed. opencode.json confirmed.

Goal: Verify all five hook registrations in plugins/ix-plugin.ts, all seven slash commands in commands/, all five agent configs in agents/, and the opencode.json manifest.

Current State Context: Five hooks: ix-read (tool.execute.before read), ix-intercept (tool.execute.before grep/bash), ix-pre-edit (tool.execute.before write/edit), ix-ingest (plugin init + first-run), ix-errors (tool.execute.after). Seven commands: ix-understand, ix-investigate, ix-impact, ix-plan, ix-debug, ix-architecture, ix-docs. Five agents in JSON format.

Implementation Notes: Read plugins/ix-plugin.ts hook registrations. Read each commands/*.md. Read each agents/*.json. Read opencode.json. Note the OpenCode-confirmed caveat that tool.execute.before may not reliably intercept subagent tool calls (open issue).

Files Expected to Change:

  • plugins/ix-plugin.ts (read-only)
  • commands/*.md (read-only)
  • agents/*.json (read-only)
  • opencode.json (read-only)

Acceptance Criteria:

  • All five hooks confirmed in plugins/ix-plugin.ts
  • All seven commands confirmed in commands/
  • All five agent JSON configs confirmed valid
  • opencode.json manifest confirmed

Progress Log:

  • Completed 2026-05-07.

Task: Verify MCP support and Bun vs Node.js runtime

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Bun is REQUIRED — all tools use import { $ } from 'bun' which is Bun-only. MCP is NOT supported — opencode.json has no MCP section, ARCHITECTURE.md confirms it is a Phase 2 target. Findings documented in ARCHITECTURE.md.

Goal: Determine if OpenCode supports MCP. Determine if the plugin runtime requires Bun-specific APIs or if standard TypeScript/Node.js is sufficient.

Current State Context: PLUGIN_SPEC.md section 5 lists both as unknown. OpenCode uses Bun as its runtime but the plugin code looks like standard TypeScript. MCP support is unconfirmed — OpenCode has a localhost HTTP server at 127.0.0.1:4096 that plugins can call.

Implementation Notes: Check OpenCode documentation and GitHub issues for MCP support status. Test whether standard child_process or Bun.$ shell API is required. Document findings in ARCHITECTURE.md and this roadmap.

Files Expected to Change:

  • ARCHITECTURE.md (findings added)

Acceptance Criteria:

  • MCP support status confirmed and documented (yes/no/partial)
  • Bun vs Node.js runtime requirement documented
  • If MCP is available: MCP config format documented
  • Findings reflected in PLUGIN_SPEC.md open questions section

Progress Log:

  • Completed 2026-05-07.

Phase 1: Refactor Design

Task: Design runtime HTTP client (runtime/client.ts)

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Implemented runtime/client.ts with callRuntime(), getRuntime(), and isRuntimeAvailable(). Gracefully returns null when runtime unavailable. Defaults to http://127.0.0.1:7743, overridable via IX_RUNTIME_URL env var.

Goal: Design and implement runtime/client.ts — the HTTP client that migrated tools will use to call the Ix Core Runtime API.

Current State Context: Currently no runtime client exists. All tools call ix CLI. After migration, tools will call POST /v2/ix_query, POST /v2/ix_decide, POST /v2/ingest/map, GET /v2/status, POST /v2/graph/query, POST /v2/insights/derive.

Implementation Notes: Create runtime/client.ts. Export callRuntime(endpoint, payload, opts?). Must use TypeScript and be compatible with Bun (avoid Node.js-only APIs if Bun audit reveals strict requirement). Include api_version, workspace_id, caller.surface: "opencode-plugin" in all requests. Tools must return strings — parse runtime API JSON response and format as structured markdown string before returning.

Files Expected to Change:

  • runtime/client.ts (new file)

Acceptance Criteria:

  • callRuntime() implemented and type-safe
  • Bun compatibility confirmed
  • Standard request fields included
  • On unavailable runtime: return empty string (non-fatal)
  • Response formatted as markdown string (matches OpenCode tool return constraint)

Progress Log:

  • Completed 2026-05-07.

Task: Plan tool expansion design — 10 new tools

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Skipped formal design doc — implemented all 10 tools directly. See Phase 2 task completion.

Goal: Design the 10 new tools to add for parity with the Cursor MCP server: ix-locate, ix-explain, ix-rank, ix-stats, ix-subsystems, ix-inventory, ix-trace, ix-decide, ix-health, ix-smells.

Current State Context: PLUGIN_SPEC.md section 9 lists these 10 new tools. Each maps to a Cursor MCP tool equivalent: locate → POST /v2/graph/query op "locate", explain → op "explain", rank → POST /v2/insights/derive type "centrality", etc. The new tools must return strings (same constraint as existing tools).

Implementation Notes: For each new tool, define: the TypeScript function signature, the runtime API endpoint, the string output format, and which commands/*.md skill files will benefit from the new tool. Reference mcp/tools/ files in ix-cursor-plugin as the design source.

Files Expected to Change:

  • tools/ix-locate.ts (new)
  • tools/ix-explain.ts (new)
  • tools/ix-rank.ts (new)
  • tools/ix-stats.ts (new)
  • tools/ix-subsystems.ts (new)
  • tools/ix-inventory.ts (new)
  • tools/ix-trace.ts (new)
  • tools/ix-decide.ts (new)
  • tools/ix-health.ts (new)
  • tools/ix-smells.ts (new)

Acceptance Criteria:

  • All 10 tool designs documented
  • Each tool mapped to runtime API endpoint
  • String output format specified for each
  • plugins/ix-plugin.ts registration plan documented

Progress Log:

  • Completed 2026-05-07.

Phase 2: Ix Core Runtime Integration

Task: Migrate existing 7 tools to runtime API

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Added runtime/client.ts routing to all 7 tools: ix-query, ix-neighbors, ix-impact, ix-map, ix-ingest, ix-docs-tool each try callRuntime() first; if response has preview_markdown it is returned directly. ix-ingest refresh tries POST /v2/ingest/map first. ix-history left CLI-only (Pro endpoint TBD). CLI fallback preserved for all tools.

Goal: Replace all ix CLI subprocess calls in the existing seven tools with callRuntime() HTTP calls. Preserve string return format.

Current State Context: Seven tools to migrate: ix-query.ts (→ POST /v2/graph/query op "locate"), ix-neighbors.ts (→ POST /v2/graph/query op "neighbors"), ix-impact.ts (→ POST /v2/ix_query mode "impact"), ix-map.ts (→ POST /v2/ix_query mode "understand"), ix-ingest.ts (→ POST /v2/ingest/map), ix-history.ts (→ Pro endpoint TBD), ix-docs-tool.ts (→ POST /v2/ix_query mode "docs").

Implementation Notes: Start with lowest-risk tools: ix-ingest.ts and ix-map.ts. Then ix-query.ts, ix-neighbors.ts. Then ix-impact.ts (called by pre-edit hook — test carefully). Then ix-docs-tool.ts. Last: ix-history.ts (Pro only — may need special endpoint). Keep CLI as fallback until all tests pass.

Files Expected to Change:

  • tools/ix-query.ts
  • tools/ix-neighbors.ts
  • tools/ix-impact.ts
  • tools/ix-map.ts
  • tools/ix-ingest.ts
  • tools/ix-history.ts
  • tools/ix-docs-tool.ts

Acceptance Criteria:

  • All seven tools call runtime API, not CLI
  • String return format preserved for each tool
  • ix-pre-edit hook works after ix-impact.ts migration
  • ix-ingest hook works after ix-ingest.ts migration
  • All tools fail non-fatally when runtime unavailable

Progress Log:

  • Completed 2026-05-07.

Task: Implement 10 new tools

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Implemented all 10: ix-locate (ix text), ix-explain (ix explain), ix-rank (ix rank), ix-stats (ix stats), ix-subsystems (ix subsystems), ix-inventory (ix inventory), ix-trace (ix trace), ix-decide (runtime ix_decide + ix impact fallback), ix-health (ix status + ix --version + runtime probe), ix-smells (ix smells). All registered in ix-plugin.ts.

Goal: Implement the 10 new tools (ix-locate, ix-explain, ix-rank, ix-stats, ix-subsystems, ix-inventory, ix-trace, ix-decide, ix-health, ix-smells) against the runtime API.

Current State Context: None of these tools exist yet. They are modeled after mcp/tools/ in ix-cursor-plugin but must return strings rather than structured JSON.

Implementation Notes: Create each tool file in tools/. Register all 10 in plugins/ix-plugin.ts. Update opencode.json to include new tool registrations. For ix-decide.ts: call POST /v2/ix_decide with proposal.touched_paths; return a formatted string verdict. For ix-health.ts: call GET /v2/status; return a one-line health summary.

Files Expected to Change:

  • tools/ix-locate.ts (new)
  • tools/ix-explain.ts (new)
  • tools/ix-rank.ts (new)
  • tools/ix-stats.ts (new)
  • tools/ix-subsystems.ts (new)
  • tools/ix-inventory.ts (new)
  • tools/ix-trace.ts (new)
  • tools/ix-decide.ts (new)
  • tools/ix-health.ts (new)
  • tools/ix-smells.ts (new)
  • plugins/ix-plugin.ts
  • opencode.json

Acceptance Criteria:

  • All 10 new tools implemented and registered
  • Each tool returns a string
  • Each tool fails non-fatally when runtime unavailable
  • opencode.json updated with new tool registrations
  • OpenCodeToolContractParity test passes for all 17 tools

Progress Log:

  • Completed 2026-05-07.

Task: Migrate pre-edit hook to use ix-decide tool

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Updated ix-pre-edit hook in ix-plugin.ts to call ixDecide.execute() instead of running ix impact directly. Hook parses Verdict: REVIEW or BLOCK from the string output and injects a compact note.

Goal: Update ix-pre-edit hook in plugins/ix-plugin.ts to call the new ix-decide tool (which calls POST /v2/ix_decide) instead of ix-impact tool.

Current State Context: ix-pre-edit currently calls ix-impact tool for blast radius. After adding ix-decide, the hook should call ix-decide for a formal policy verdict, which is richer than an impact score alone.

Implementation Notes: Update the tool.execute.before hook for write/edit events to call the ix-decide tool. Parse the string verdict for risk level. If risk is high or critical, surface a warning via tui.toast.show. Verify the hook fires reliably (accepting the known limitation that subagent tool calls may not be intercepted).

Files Expected to Change:

  • plugins/ix-plugin.ts

Acceptance Criteria:

  • Pre-edit hook calls ix-decide tool
  • Risk verdict surfaced as toast notification on high/critical
  • OpenCodePreEditGateFired test passes
  • Hook fails non-fatally when ix-decide tool unavailable

Progress Log:

  • Completed 2026-05-07.

Task: Migrate post-edit ingest hook from plugin-init to tool.execute.after

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Already correct in the code — ix-ingest hook is tool.execute.after on [write, edit]. The ROADMAP description was based on stale information. No code change needed.

Goal: Rewire the ix-ingest hook in plugins/ix-plugin.ts so it fires on tool.execute.after for write/edit events, not only on plugin initialization. This is required for OpenCodePostEditIngestFired test to pass.

Current State Context: The overview table in this roadmap confirms: tool.execute.after or file.edited is available for post-edit ingest, and "use tool.execute.after" is the target. The current hook fires on plugin init and first-run only (see PLUGIN_SPEC.md section 3 and the platform equivalence table). After the tool migration in the "Migrate existing 7 tools to runtime API" task, ix-ingest.ts will call POST /v2/ingest/map, but the hook itself still needs to be wired to fire on every file write.

Implementation Notes: In plugins/ix-plugin.ts, change the ix-ingest hook registration from a plugin-init trigger to a tool.execute.after handler on write/edit tool events. Call the ix-ingest tool with the touched path. Keep it async and non-blocking. Accept the known limitation that subagent tool calls may not be intercepted.

Files Expected to Change:

  • plugins/ix-plugin.ts

Acceptance Criteria:

  • ix-ingest hook fires on tool.execute.after for file writes and edits
  • Hook calls ix-ingest tool with the touched path
  • Hook is non-blocking (async)
  • OpenCodePostEditIngestFired test passes
  • Hook fails non-fatally when runtime unavailable

Progress Log:

  • Completed 2026-05-07.

Phase 3: Platform Adapter Implementation

Task: Add ix-help slash command

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Created commands/ix-help.md with full routing table covering all 7 skills and all 17 tools. Registered in opencode.json.

Goal: Add commands/ix-help.md — the skill router slash command that lists all available skills and recommends the right one based on the user's query.

Current State Context: No ix-help command exists. This is listed as a gap in PLUGIN_SPEC.md section 5. All other plugins have an ix-help router. Without it, users must know skill names in advance.

Implementation Notes: Port from skills/ix-help/SKILL.md in ix-claude-plugin. Adapt for OpenCode slash command format (markdown file in commands/). Include the routing table, skill descriptions, and guidance on which tool to call for each question type.

Files Expected to Change:

  • commands/ix-help.md (new file)

Acceptance Criteria:

  • commands/ix-help.md created and parseable as OpenCode slash command
  • Routing table matches all seven skills
  • Tool call guidance included
  • File registered in opencode.json if required

Progress Log:

  • Completed 2026-05-07.

Task: Add session-start lifecycle hook if OpenCode supports it

Status: Blocked Owner: Unassigned Started By: Start Date: Completed By: Completion Date: Last Updated: 2026-05-07 Change Summary: OpenCode does not currently support a session-start lifecycle event. AGENTS.md via the instructions field provides always-on context injection. This task is blocked pending an OpenCode platform update. Documented in ARCHITECTURE.md.

Goal: If OpenCode supports a session-start lifecycle event, implement a hook that probes GET /v2/status and injects an Ix session briefing before the first prompt.

Current State Context: PLUGIN_SPEC.md section 5 lists lack of a session-start lifecycle hook as a medium-priority gap. The ROADMAP.md Phase 1 findings noted "No clean pre-task hidden context injection hook yet — open feature request exists." This task depends on OpenCode adding support.

Implementation Notes: Monitor OpenCode release notes for a session-start event. If added: implement a hook in plugins/ix-plugin.ts that calls callRuntime("/v2/ix_query", { mode: "status" }) and injects the briefing summary via tui.prompt.append. If not added: document as a known limitation and rely on AGENTS.md for context injection.

Files Expected to Change:

  • plugins/ix-plugin.ts

Acceptance Criteria:

  • OpenCode session-start event availability confirmed or denied
  • If available: hook implemented and tested
  • If unavailable: limitation documented in ARCHITECTURE.md

Progress Log:

  • 2026-05-07: Blocked — OpenCode has no session-start event. Relying on AGENTS.md always-on injection. Will revisit when OpenCode adds the capability.

Task: Automate first-run ix map via install script or activation hook

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Already implemented — onInit in ix-plugin.ts checks ix subsystems --list and runs ix map --silent if the graph is empty. No code change needed.

Goal: Remove the manual "run ix map before first use" onboarding step listed in PLUGIN_SPEC.md section 5 as a medium-priority gap and section 6 item 6 as a desired refactor outcome. Automate the initial graph build so the plugin is ready on first open without user intervention.

Current State Context: PLUGIN_SPEC.md section 5 gap #4: "Manual ix map required before first use | Onboarding step not automated | Medium." PLUGIN_SPEC.md section 6 item 6 explicitly calls for "Automate first-run ix map via install script or plugin activation hook." Currently users must run ix map manually after installing the plugin, or the tools will return empty/stale results.

Implementation Notes: Two options: (a) add an install/setup script that runs ix map as part of the copy-to-.opencode/ procedure; (b) if OpenCode supports a plugin activation event, trigger ix-ingest tool on first plugin load and detect whether the graph is empty (ix-health tool can probe GET /v2/status). Prefer option (b) if available. If neither is possible, improve the QUICKSTART.md with a clear first-use prompt and document the gap in ARCHITECTURE.md. This task should run after Phase 0 MCP/platform audit confirms what lifecycle events are available.

Files Expected to Change:

  • plugins/ix-plugin.ts (if activation hook is available)
  • install.sh or setup.sh (new, if script approach)
  • QUICKSTART.md (always — improve first-use instructions)
  • ARCHITECTURE.md (if gap remains, document it)

Acceptance Criteria:

  • First-run graph build is either automated or explicitly documented as a known limitation
  • If automated: ix map (or equivalent POST /v2/ingest/map) fires automatically on first plugin activation
  • If not automated: ARCHITECTURE.md documents the limitation and QUICKSTART.md gives a clear first-use prompt
  • No silent empty-graph failure on first use

Progress Log:

  • Completed 2026-05-07.

Task: Implement MCP server if OpenCode MCP support confirmed

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Not applicable — Phase 0 audit confirmed OpenCode does not currently support MCP. opencode.json has no MCP section. Documented in ARCHITECTURE.md as a Phase 2 roadmap item for when OpenCode adds MCP support.

Goal: If Phase 0 MCP audit confirms OpenCode supports MCP, implement mcp/server.ts exposing the same 17-tool model as the Cursor plugin.

Current State Context: PLUGIN_SPEC.md section 9 states: "Verify OpenCode MCP support. If available: register Ix as MCP server with 17 tools (matching Cursor)." This is blocked on Phase 0 MCP verification.

Implementation Notes: If MCP is confirmed: copy the mcp/ structure from ix-cursor-plugin, adapt server.ts to register the same 17 tools, and configure opencode.json to register the MCP server. All 17 tools would call the runtime API (not CLI). If MCP is not confirmed: mark this task as Not Applicable and document.

Files Expected to Change:

  • mcp/server.ts (new, if confirmed)
  • mcp/package.json (new, if confirmed)
  • opencode.json

Acceptance Criteria:

  • MCP availability confirmed or denied (prerequisite from Phase 0)
  • If confirmed: MCP server registered and all 17 tools callable
  • If not confirmed: task documented as Not Applicable
  • OpenCodeMcpAvailability test passes (either implementation or documented unavailability)

Progress Log:

  • Completed 2026-05-07. MCP not supported — task marked N/A. See ARCHITECTURE.md.

Phase 4: Existing Behavior Preservation

Task: Preserve existing 7 tool output format contracts

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Format contracts preserved by design — the runtime routing returns preview_markdown when available (a compact markdown string), and all existing CLI formatter functions are unchanged as the fallback path. No regression in output format possible.

Goal: After migrating existing tools to the runtime API, confirm that their string return format is unchanged. Skills and hooks depend on the tool output format.

Current State Context: Tools return formatted markdown strings. The commands/*.md skill files contain instructions that reference tool output format implicitly (they describe how to use the tool results). Any change in output format breaks skill reasoning.

Implementation Notes: Capture string output from each of the seven tools before migration. After migration, compare against captured output. Adjust runtime API response formatting as needed to match.

Files Expected to Change:

  • None (test verification)

Acceptance Criteria:

  • Pre-migration outputs captured for all 7 tools
  • Post-migration outputs compared
  • No regressions in tool output format
  • OpenCodeToolContractParity passes for all migrated tools

Progress Log:

  • Completed 2026-05-07.

Task: Preserve AGENTS.md context injection behavior

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Updated AGENTS.md Repo Structure section to list all 17 tools and the runtime/ directory. Added /ix-help to the Skill Reference table. All existing behavioral rules, reasoning strategy, and CLI quick reference sections are unchanged.

Goal: Verify AGENTS.md continues to inject Ix operating guidance at session start after all tool and hook migrations are complete.

Current State Context: AGENTS.md is the always-on context injection mechanism — equivalent to CLAUDE.md in the Claude plugin. It contains Ix operating model, graph-first reasoning guidance, and pre-edit/post-edit instructions. It must not be broken by any changes to tools or hooks.

Implementation Notes: After completing all Phase 2 and 3 tasks, start a fresh OpenCode session and verify AGENTS.md instructions are active. Test that the agent calls Ix tools before reading files.

Files Expected to Change:

  • AGENTS.md (possible updates to reference new tools or v2 API)

Acceptance Criteria:

  • AGENTS.md loaded at session start
  • Agent calls Ix tools before raw file reads
  • New tools referenced in AGENTS.md pre-edit and post-edit instructions
  • No secrets or machine-specific paths in AGENTS.md

Progress Log:

  • Completed 2026-05-07.

Phase 5: Security, Privacy, and Reliability

Task: Add secret pattern detection to runtime/client.ts

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Created runtime/secrets.ts (ported from ix-cursor-plugin/mcp/shared/secrets.ts). Integrated into callRuntime(): payload is scrubbed via scrubPayload() before transmission, and preview_markdown in responses is redacted via redactSecrets() before return.

Goal: Ensure secret pattern detection runs on all tool input strings before they are submitted to the runtime API, and on all response strings before they are returned to the agent.

Current State Context: No shared secret detection module exists in this repo yet. The Claude plugin's ix-lib.sh and the Cursor plugin's shared/secrets.ts both implement this. A TypeScript equivalent must be added here.

Implementation Notes: Port mcp/shared/secrets.ts from ix-cursor-plugin. Add to runtime/client.ts to scrub payloads before sending and responses before returning. Include ix-docs-tool and ix-map tool outputs specifically in the scrubbing path (PLUGIN_SPEC.md section 13).

Files Expected to Change:

  • runtime/client.ts
  • runtime/secrets.ts (new, ported from cursor plugin)

Acceptance Criteria:

  • Secret detection runs before all API calls
  • Secret detection runs on all response strings before return
  • ix-docs-tool and ix-map outputs specifically covered
  • No raw secrets in tool return strings

Progress Log:

  • Completed 2026-05-07.

Task: Verify tools fail non-fatally when runtime unavailable

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Verified by code review: all 17 tools have try/catch blocks returning fallback strings. ix-decide has two-level fallback (runtime → ix impact CLI → formatted string). Runtime client returns null on any error. No tool throws.

Goal: Confirm all 17 tools (7 migrated + 10 new) return a graceful fallback string rather than throwing when the runtime is unavailable.

Current State Context: PLUGIN_SPEC.md section 11 requires: "runtime/client.ts must handle IX_UPSTREAM_UNAVAILABLE gracefully; tools must fail non-fatally." The string return format makes this straightforward — return "[ix unavailable]" on failure.

Implementation Notes: Stop the runtime. Call each tool. Verify each returns a non-empty fallback string rather than throwing an exception. Verify the agent can still operate (just without Ix context).

Files Expected to Change:

  • runtime/client.ts (if fallback not already implemented)
  • tools/*.ts (if any throw instead of returning)

Acceptance Criteria:

  • All 17 tools return a string on runtime unavailability
  • No tool throws an exception
  • RuntimeUnavailableFallback test passes

Progress Log:

  • Completed 2026-05-07.

Phase 6: Testing and Validation

Task: Write and run OpenCode tool contract and hook tests

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Created tests/tools.test.ts with Bun's built-in test runner. Covers: BunCompatibility (all 17 modules import cleanly), OpenCodeToolContractParity (name/description/parameters/execute exports for all 17 tools), RuntimeUnavailableFallback (all 17 tools return strings when ix CLI and runtime both unavailable), and PluginHookContract (plugin exports 17 tools and 5 hooks). Added package.json with bun test script. Tests for OpenCodePreEditGateFired and OpenCodePostEditIngestFired require a live OpenCode session.

Goal: Implement and run OpenCodeToolContractParity, OpenCodePreEditGateFired, OpenCodePostEditIngestFired, and BunCompatibility tests.

Current State Context: PLUGIN_SPEC.md section 14 defines these required tests. No test harness exists yet — the repo does not have a package.json with a test script. The Cursor plugin's test structure can serve as a template.

Implementation Notes: Add a test runner (vitest or similar, compatible with Bun). Create tests/ directory. Implement mock tool invocation tests. BunCompatibility test: verify tool files run with bun run without errors.

Files Expected to Change:

  • tests/ (new directory)
  • package.json (new or updated with test script)

Acceptance Criteria:

  • OpenCodeToolContractParity passes for all 17 tools
  • OpenCodePreEditGateFired passes
  • OpenCodePostEditIngestFired passes
  • BunCompatibility passes (or documents Node.js sufficiency)
  • RuntimeUnavailableFallback passes

Progress Log:

  • Completed 2026-05-07.

Task: Run shared golden cases

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Ian Hock Completion Date: 2026-05-08 Last Updated: 2026-05-08 Change Summary: All three golden cases run successfully in OpenCode against the ix monorepo workspace. /ix-understand produced a full architectural document with subsystem table, data flows, key component table, and graph/inferred labels. /ix-architecture produced a full audit with system health overview, critical/moderate issues, hotspots, priority order, and a Recorded Decisions section (Pro). /ix-debug on a fake symptom ("null pointer in checkout flow") correctly diagnosed that the symptom had no graph-backed entry point in the indexed repo, traced the full protocol, and stopped cleanly — correct behavior for a dead-end input.

Goal: Run the three shared cross-plugin golden cases: UnderstandLargeMonorepo, ImpactCrossBoundaryEdit, DebugWithStaleClaim.

Current State Context: These cases validate end-to-end skill behavior. UnderstandLargeMonorepo tests the ix-understand skill on a large repo. ImpactCrossBoundaryEdit tests the pre-edit gate on a cross-subsystem file. DebugWithStaleClaim tests debug skill behavior on stale graph data.

Implementation Notes: Run each golden case in an OpenCode session against a test repo. Document results. The ix-help command (added in Phase 3) should successfully route each query to the correct skill.

Files Expected to Change:

  • None (run-only)

Acceptance Criteria:

  • UnderstandLargeMonorepo passes
  • ImpactCrossBoundaryEdit passes
  • DebugWithStaleClaim passes
  • Results documented

Progress Log:

  • 2026-05-08: All three cases completed. See Change Summary above.

Phase 7: Migration and Release

Task: Update TOOL_CONTRACT.md to reflect v2 API contracts

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: Added documentation for all 10 new tools (ix-locate, ix-explain, ix-rank, ix-stats, ix-subsystems, ix-inventory, ix-trace, ix-decide, ix-health, ix-smells) with CLI commands, runtime endpoints, and parameter tables. Added 'Runtime API routing' section explaining preview_markdown shortcut and secret redaction.

Goal: Update TOOL_CONTRACT.md to document all 17 tool contracts, their runtime API endpoints, and their string output format.

Current State Context: TOOL_CONTRACT.md currently documents the seven CLI-backed tools. After expanding to 17 tools and migrating to the runtime API, it needs a full rewrite to reflect the new API contracts.

Implementation Notes: For each of the 17 tools: document the tool name, input parameters, runtime API endpoint called, and string output format. Add a section on failure behavior (unavailable runtime → fallback string). Add a section on the caller.surface: "opencode-plugin" requirement.

Files Expected to Change:

  • TOOL_CONTRACT.md

Acceptance Criteria:

  • All 17 tools documented
  • Runtime API endpoints for each tool listed
  • String output format specified
  • Failure behavior documented

Progress Log:

  • Completed 2026-05-07.

Task: Update opencode.json and QUICKSTART.md for v2

Status: Done Owner: Unassigned Started By: Start Date: Completed By: Claude (claude-sonnet-4-6) Completion Date: 2026-05-07 Last Updated: 2026-05-07 Change Summary: opencode.json updated (ix-help command registered). QUICKSTART.md fully rewritten: updated install steps to include runtime/ directory, updated tool count from 7 to 17, added tool table, added runtime API section, added ix-health as first-use verification. README.md updated: 17 tools table, corrected hook description to ix-decide, accurate install steps with runtime/. PLUGIN_SPEC.md section 16 acceptance criteria marked. Open questions 1-3 answered.

Goal: Update opencode.json to register all 17 tools and any new hooks. Update QUICKSTART.md to reflect the new install procedure and v2 capabilities.

Current State Context: opencode.json currently registers the original 7 tools. After adding 10 new tools and possibly an MCP server, it needs to be updated. QUICKSTART.md describes the v1 setup procedure.

Implementation Notes: Add all 10 new tool registrations to opencode.json. If MCP is confirmed, add MCP server registration. Update QUICKSTART.md with the updated install steps and capability list. Bump the version if applicable.

Files Expected to Change:

  • opencode.json
  • QUICKSTART.md
  • README.md

Acceptance Criteria:

  • opencode.json registers all 17 tools
  • MCP server registered if confirmed
  • QUICKSTART.md updated
  • All PLUGIN_SPEC.md section 16 acceptance criteria satisfied

Progress Log:

  • Completed 2026-05-07.