@aryaminus/controlkeel-opencode 0.1.0

package/.opencode/agents/controlkeel-operator.md

@@ -0,0 +1,25 @@
+---
+description: ControlKeel governed code review agent — validates changes against security, budget, and compliance policies.
+model: anthropic/claude-sonnet-4-5
+tools:
+  write: false
+  edit: false
+---
+
+You are the ControlKeel governance operator. Your role is to review code changes
+and validate them against the project's security, budget, and compliance policies.
+
+## Instructions
+
+1. Use the `ck-validate` tool to run governance checks before providing feedback.
+2. Report findings by severity: critical > high > medium > low.
+3. Never approve changes that have unresolved critical or high findings.
+4. Reference specific policy rules when flagging issues.
+5. Summarize budget impact if token/cost tracking is enabled.
+
+## Available MCP Tools
+
+- `ck_validate` — Run full governance validation
+- `ck_budget` — Check remaining budget and spend history
+- `ck_findings` — List open findings for the current session
+- `ck_approve` — Approve a finding (requires operator confirmation)

package/.opencode/commands/controlkeel-annotate.md

@@ -0,0 +1,8 @@
+# /controlkeel-annotate <file>
+
+Use this command in OpenCode when a specific file needs focused human notes.
+
+Suggested flow:
+1. Save the file path, risks, and requested annotation context to `.opencode/annotate.md`.
+2. Run `controlkeel review plan submit --title "File annotation review" --body-file .opencode/annotate.md --submitted-by opencode --json`
+3. Wait for the response before applying risky edits.

package/.opencode/commands/controlkeel-last.md

@@ -0,0 +1,8 @@
+# /controlkeel-last
+
+Use this command in OpenCode to reopen the latest ControlKeel review you are tracking for the current task.
+
+Suggested flow:
+1. Read the last stored review id from your notes or prior command output.
+2. Run `controlkeel review plan open --id <review_id> --json`
+3. If the review is still pending, run `controlkeel review plan wait --id <review_id> --json`

package/.opencode/commands/controlkeel-review.md

@@ -0,0 +1,14 @@
+---
+description: Run ControlKeel governance review on the current project
+agent: controlkeel-operator
+---
+
+Review the current project for governance compliance. Run `ck-validate` to check
+for security findings, budget status, and proof readiness. Summarize the results
+and highlight any blockers that need attention before shipping.
+
+Focus on:
+1. Open findings by severity
+2. Budget remaining vs. spent
+3. Proof coverage for completed tasks
+4. Any policy violations that block release

package/.opencode/commands/controlkeel-submit-plan.md

@@ -0,0 +1,12 @@
+---
+description: Submit the current plan to ControlKeel browser review and wait for approval
+---
+
+Save the current plan to a markdown file, then submit it through ControlKeel.
+
+Recommended flow:
+1. Save the plan to `.opencode/review-plan.md`
+2. Run `controlkeel review plan submit --body-file .opencode/review-plan.md --submitted-by opencode --json`
+3. Read the returned `review.id` and `browser_url`
+4. Wait with `controlkeel review plan wait --id <review_id> --json`
+4. Do not execute until the review is approved

package/.opencode/mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "controlkeel": {
+      "args": [
+        "mcp",
+        "--project-root",
+        "."
+      ],
+      "command": "controlkeel"
+    }
+  }
+}

package/.opencode/plugins/controlkeel-governance.ts

@@ -0,0 +1,85 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+
+/**
+ * ControlKeel Review Bridge for OpenCode
+ *
+ * Host-specific adapter behavior:
+ * - injects a submit_plan review tool for planning agents
+ * - suppresses plan_exit in favor of ControlKeel browser review
+ * - keeps the review tool primary-agent only by default
+ * - routes plan submission and wait decisions through the CK CLI
+ */
+export const ControlKeelGovernance: Plugin = async ({ project, client, $, directory }) => {
+  const parseJson = (output: string) => {
+    try {
+      return JSON.parse(output)
+    } catch (_error) {
+      throw new Error(`ControlKeel returned invalid JSON: ${output}`)
+    }
+  }
+
+  const submitPlan = async (body: string, submittedBy: string) => {
+    const result = await $`controlkeel review plan submit --stdin --submitted-by ${submittedBy} --json`
+      .text(body)
+    const submitPayload = parseJson(result)
+    const reviewId = submitPayload?.review?.id
+    if (!reviewId) {
+      throw new Error("ControlKeel did not return a review id")
+    }
+    const waitPayload = parseJson(await $`controlkeel review plan wait --id ${reviewId} --json`)
+    return {
+      reviewId,
+      submitPayload,
+      waitPayload,
+      browserUrl: submitPayload?.browser_url,
+      status: waitPayload?.review?.status,
+      feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
+    }
+  }
+
+  return {
+    "shell.env": async (_input, output) => {
+      output.env.CONTROLKEEL_PROJECT_ROOT = directory
+      output.env.CONTROLKEEL_AGENT_ID = "opencode"
+    },
+
+    config: async (config) => {
+      const primaryTools = config.experimental?.primary_tools ?? []
+      if (!primaryTools.includes("submit_plan")) {
+        config.experimental = {
+          ...config.experimental,
+          primary_tools: [...primaryTools, "submit_plan"],
+        }
+      }
+    },
+
+    "tool.definition": async (input, output) => {
+      if (input.toolID === "plan_exit") {
+        output.description =
+          "Do not call this tool. Use submit_plan so ControlKeel can collect approval in the browser review flow."
+      }
+    },
+
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(
+        "Use submit_plan when you are ready for human review. Do not proceed with implementation until ControlKeel approves the plan."
+      )
+    },
+
+    tool: {
+      "submit_plan": tool({
+        description:
+          "Submit a plan to ControlKeel for browser review. The tool waits for approval before execution continues.",
+        args: {
+          plan: tool.schema.string().describe("Markdown plan body to submit for review."),
+          title: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          const result = await submitPlan(args.plan, "opencode")
+          return JSON.stringify(result, null, 2)
+        },
+      }),
+    },
+  }
+}

package/AGENTS.md

@@ -0,0 +1,25 @@
+# ControlKeel Companion Instructions
+
+This project is governed by ControlKeel. Prefer the ControlKeel MCP server for validation, findings, budgets, proof context, and routing.
+
+Project root: `.`
+Target: `opencode`
+
+Required workflow:
+1. Call `ck_context` at the start of a task.
+2. Call `ck_validate` before writing code, config, shell, or deploy content.
+3. Submit plans or approval packets with `ck_review_submit` and check `ck_review_status` before execution.
+4. Record any human-review issue with `ck_finding`.
+5. Check `ck_budget` before expensive model or multi-agent work.
+6. Use `ck_route`, `ck_skill_list`, and `ck_skill_load` to delegate or activate specialized CK workflows.
+
+Install ControlKeel:
+- Homebrew: `brew tap aryaminus/controlkeel && brew install controlkeel`
+- npm bootstrap: `npm i -g @aryaminus/controlkeel`
+- Unix installer: `curl -fsSL https://github.com/aryaminus/controlkeel/releases/latest/download/install.sh | sh`
+- Raw GitHub shell installer: `curl -fsSL https://raw.githubusercontent.com/aryaminus/controlkeel/main/scripts/install.sh | sh`
+- PowerShell installer: `irm https://github.com/aryaminus/controlkeel/releases/latest/download/install.ps1 | iex`
+- Raw GitHub PowerShell installer: `irm https://raw.githubusercontent.com/aryaminus/controlkeel/main/scripts/install.ps1 | iex`
+- GitHub Releases: `https://github.com/aryaminus/controlkeel/releases`
+
+ControlKeel auto-bootstraps project binding on first use. Provider access resolves through agent bridge, CK-owned provider profiles, local Ollama, then heuristic fallback.

package/README.md

@@ -0,0 +1,22 @@
+# ControlKeel OpenCode plugin
+
+Direct install:
+
+```json
+{
+  "plugin": ["@aryaminus/controlkeel-opencode"]
+}
+```
+
+This npm package exposes the ControlKeel OpenCode governance plugin entrypoint.
+For the full repo-local experience with commands, agents, and MCP config, also run:
+
+```bash
+controlkeel attach opencode
+```
+
+The repo-local command bundle now includes:
+- `/controlkeel-review`
+- `/controlkeel-submit-plan`
+- `/controlkeel-annotate`
+- `/controlkeel-last`

package/index.js

@@ -0,0 +1,92 @@
+/**
+ * Published OpenCode package entrypoint for ControlKeel.
+ *
+ * This mirrors the repo-local plugin in `.opencode/plugins/controlkeel-governance.ts`
+ * but ships as plain JavaScript for npm-based installs.
+ */
+export const ControlKeelGovernance = async ({ $, directory }) => {
+  const parseJson = (output) => {
+    try {
+      return JSON.parse(output)
+    } catch (_error) {
+      throw new Error(`ControlKeel returned invalid JSON: ${output}`)
+    }
+  }
+
+  const submitPlan = async (body, submittedBy) => {
+    const result = await $`controlkeel review plan submit --stdin --submitted-by ${submittedBy} --json`
+      .text(body)
+    const submitPayload = parseJson(result)
+    const reviewId = submitPayload?.review?.id
+    if (!reviewId) {
+      throw new Error("ControlKeel did not return a review id")
+    }
+    const waitPayload = parseJson(await $`controlkeel review plan wait --id ${reviewId} --json`)
+    return {
+      reviewId,
+      submitPayload,
+      waitPayload,
+      browserUrl: submitPayload?.browser_url,
+      status: waitPayload?.review?.status,
+      feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
+    }
+  }
+
+  return {
+    "shell.env": async (_input, output) => {
+      output.env.CONTROLKEEL_PROJECT_ROOT = directory
+      output.env.CONTROLKEEL_AGENT_ID = "opencode"
+    },
+
+    config: async (config) => {
+      const primaryTools = config.experimental?.primary_tools ?? []
+      if (!primaryTools.includes("submit_plan")) {
+        config.experimental = {
+          ...config.experimental,
+          primary_tools: [...primaryTools, "submit_plan"],
+        }
+      }
+    },
+
+    "tool.definition": async (input, output) => {
+      if (input.toolID === "plan_exit") {
+        output.description =
+          "Do not call this tool. Use submit_plan so ControlKeel can collect approval in the browser review flow."
+      }
+    },
+
+    "tool.execute": async (input, output) => {
+      if (input.toolID !== "submit_plan") {
+        return
+      }
+
+      const planBody = typeof input.args?.plan === "string" ? input.args.plan : ""
+      const review = await submitPlan(planBody, "opencode")
+      output.metadata = {
+        reviewId: review.reviewId,
+        browserUrl: review.browserUrl,
+        status: review.status,
+        feedbackNotes: review.feedbackNotes,
+      }
+      output.result = JSON.stringify(output.metadata, null, 2)
+    },
+
+    tools: async () => ({
+      submit_plan: {
+        description: "Submit the current plan to ControlKeel and wait for browser review approval.",
+        parameters: {
+          type: "object",
+          properties: {
+            plan: {
+              type: "string",
+              description: "Markdown plan body to submit to ControlKeel review.",
+            },
+          },
+          required: ["plan"],
+        },
+      },
+    }),
+  }
+}
+
+export default ControlKeelGovernance

package/package.json

@@ -0,0 +1,36 @@
+{
+  "bugs": {
+    "url": "https://github.com/aryaminus/controlkeel/issues"
+  },
+  "description": "ControlKeel OpenCode adapter bundle",
+  "exports": {
+    ".": "./index.js",
+    "./plugin": "./index.js"
+  },
+  "files": [
+    ".opencode",
+    "AGENTS.md",
+    "README.md",
+    "index.js"
+  ],
+  "homepage": "https://github.com/aryaminus/controlkeel",
+  "keywords": [
+    "controlkeel",
+    "opencode",
+    "plugin",
+    "governance",
+    "mcp"
+  ],
+  "license": "Apache-2.0",
+  "main": "./index.js",
+  "name": "@aryaminus/controlkeel-opencode",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aryaminus/controlkeel.git"
+  },
+  "type": "module",
+  "version": "0.1.0"
+}