@alis-build/opencode-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alis Build
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# Alis Build opencode Plugin
+
+**Connect [opencode](https://opencode.ai) to Alis Build.**
+
+Use this plugin to let opencode inspect Alis Build landing zones, products, neurons,
+builds, deploys, and related workspace context — the opencode counterpart of the
+[Alis Build Claude Code plugin](https://github.com/alis-build/claude-plugin).
+
+## What You Get
+
+- A preconfigured opencode MCP server for `https://mcp.alis.build`
+- OAuth sign-in through Alis Build identity (handled by opencode)
+- Alis Build tools available inside opencode after sign-in
+- A standing Define → Build → Deploy primer loaded into every session via opencode
+  `instructions`, so the agent knows the workflow, how to route requests, and to run
+  the `alis` CLI — no trigger word required
+- `/build-it` and `/fix-it` workflow commands
+- The `alis` CLI auto-approved via opencode `permission.bash`, so command-line calls
+  run without a permission prompt each time
+
+## How this maps from the Claude Code plugin
+
+opencode and Claude Code expose the same capabilities through different mechanisms.
+Most of the Claude plugin is **config** in opencode; only the session-id injection
+needs plugin code.
+
+| Claude Code plugin | opencode equivalent | Lives in |
+| --- | --- | --- |
+| `.mcp.json` (HTTP MCP + OAuth) | `mcp.api` (`type: "remote"`) | `opencode.json` |
+| `commands/*.md` | `command/*.md` or `command` config key | this repo / config |
+| `context/dbd-primer.md` via `SessionStart` hook | `instructions` array | `opencode.json` |
+| `allow-alis-cli.sh` (`PreToolUse` Bash hook) | `permission.bash` patterns | `opencode.json` |
+| `inject-skill-session-id.sh` (`PreToolUse` hook) | `tool.execute.before` plugin hook | `src/index.ts` |
+| `.claude-plugin/marketplace.json` | npm package + config snippet | `package.json` |
+
+> opencode has **no `config` hook**, so a plugin cannot register MCP servers,
+> instructions, or commands programmatically. That is why those are config, and why
+> install is a config snippet plus an npm package rather than a single command.
+
+## Before You Start
+
+You need:
+
+- opencode installed
+- An Alis Build account with access to the landing zones and products you want to use
+- Network access to `https://mcp.alis.build` and the Alis Build identity provider
+
+## Install
+
+### 1. Add the config
+
+Merge the contents of [`opencode.example.json`](./opencode.example.json) into your
+opencode config — `~/.config/opencode/opencode.json` for a global install, or
+`.opencode/opencode.json` (or `opencode.json` at the repo root) for a project install.
+
+It wires up four things: the `@alis-build/opencode-plugin` npm plugin, the `api` MCP
+server, the `/build-it` + `/fix-it` commands, and the `alis` CLI permission allow.
+opencode installs the npm plugin automatically with Bun on next start.
+
+### 2. Install the primer file
+
+The DBD primer loads via the `instructions` array, which references a file path.
+Copy the bundled primer to the path used in the config:
+
+```sh
+mkdir -p ~/.config/opencode/alis-build
+curl -fsSL https://raw.githubusercontent.com/alis-build/opencode-plugin/main/instructions/dbd-primer.md \
+  -o ~/.config/opencode/alis-build/dbd-primer.md
+```
+
+(Or clone this repo and point the `instructions` path at `instructions/dbd-primer.md`.)
+
+### 3. (Optional) Install the commands as files
+
+The `command` block in the config defines `/build-it` and `/fix-it` inline, so this
+step is optional. If you prefer file-based commands, copy `command/build-it.md` and
+`command/fix-it.md` into `~/.config/opencode/command/` (global) or `.opencode/command/`
+(project) and drop the `command` block from your config.
+
+### 4. Start opencode
+
+```sh
+opencode
+```
+
+## Sign In
+
+opencode handles the MCP OAuth flow. On first use of an Alis tool it will prompt you to
+authenticate, or you can trigger it explicitly:
+
+```sh
+opencode mcp auth api
+```
+
+## Use It
+
+After sign-in, ask opencode to use Alis Build:
+
+```text
+build it
+```
+
+```text
+fix it
+```
+
+```text
+Use Alis Build to list the landing zones I can access.
+```
+
+```text
+Show recent builds for product os in landing zone alis.
+```
+
+The `/build-it` and `/fix-it` commands run the same skill-discovery router.
+
+### `alis` CLI auto-approval
+
+The `permission.bash` block approves `alis ...` invocations so the CLI runs without a
+prompt. opencode's bash permission matching is glob-based and **less strict than the
+Claude plugin's shell hook**, which explicitly rejected chained/redirected commands
+(`alis define && rm -rf`). If you want that stricter guarantee, tighten the pattern to
+specific subcommands (e.g. `"alis define *": "allow"`, `"alis build *": "allow"`) and
+leave everything else at the default `ask`.
+
+## Verify before relying on this
+
+opencode's plugin hook surface is newer and less documented than Claude Code's. Two
+things should be confirmed against your installed opencode / `@opencode-ai/plugin`
+version before treating this as production-ready:
+
+1. **Session-id injection** (`src/index.ts`) — the exact hook field names (`input.tool`,
+   `output.args`, and where the session id is exposed) need verifying. The handler fails
+   safe: if it can't find the session id it leaves the call untouched, and the skill
+   falls back to its own in-markdown discovery.
+2. **Command directory name** — opencode versions have used both `command/` and
+   `commands/`. The inline `command` config block avoids this ambiguity; prefer it if the
+   file-based commands don't register.
+
+## Repository layout
+
+```
+opencode-plugin/
+├── README.md
+├── LICENSE
+├── package.json            # @alis-build/opencode-plugin (npm)
+├── tsconfig.json
+├── opencode.example.json   # config snippet to merge into opencode.json
+├── src/
+│   └── index.ts            # plugin: session-id injection hook
+├── instructions/
+│   └── dbd-primer.md       # always-loaded DBD primer
+└── command/
+    ├── build-it.md
+    └── fix-it.md
+```
+
+## License
+
+MIT © Alis Build

package/command/build-it.md

@@ -0,0 +1,5 @@
+---
+description: Find the right Alis Build skill for what you want to build.
+---
+
+Run the Alis Build "build it" router as described in the Alis Build MCP server instructions: infer what I want built from the current request and workspace context (ask exactly one concise clarification only if the goal is ambiguous), call SearchSkills with the clarified goal, present the matching skills, and load the one I choose. Do not run Define, Build, Deploy, commits, or code edits from this router step — only the loaded skill does that, and only when its workflow requires it.

package/command/fix-it.md

@@ -0,0 +1,5 @@
+---
+description: Alias for build-it: find the right Alis Build skill to fix or build something.
+---
+
+Run the Alis Build "fix it" router (the fix-it alias of "build it") as described in the Alis Build MCP server instructions: infer what I want fixed or built from the current request, visible errors, and workspace context (ask exactly one concise clarification only if the goal is ambiguous), call SearchSkills with the clarified goal, present the matching skills, and load the one I choose. Do not run Define, Build, Deploy, commits, or code edits from this router step — only the loaded skill does that, and only when its workflow requires it.

package/instructions/dbd-primer.md

@@ -0,0 +1,123 @@
+# Alis Build — Define, Build, Deploy (DBD)
+
+The core workflow on the Alis Build platform is **Define, Build, Deploy (DBD)**. Most
+development flows touch one or more of these steps — use this framing when helping with any
+Alis Build task, and walk the user through DBD rather than handing over a disconnected checklist.
+
+This primer is the standing how-to guide for Alis Build work. It carries three things:
+
+1. The **mental model** — what DBD is and where things live on disk.
+2. The **routing contract** — when to discover a skill, when to run a command directly.
+3. The **execution contract** — how to actually run Define / Build / Deploy.
+
+> The Alis Build MCP provides the *tools*; this primer provides *how to operate*. When a
+> specific tool description is more precise than this primer (exact arguments, hard
+> constraints), follow the tool description.
+
+## Define — lock the API / platform contract
+
+- Edit protobuf files in the landing zone `define` repo: `~/alis.build/<organisation-id>/define`.
+- Commit and push, then Define against a specific, reviewed commit — the contract pins to that
+  exact commit, so it has to be deliberate.
+- Define pins the definition to that commit and generates consumable language packages
+  (Go, JavaScript, Python, Dart, .NET, public ECMAScript when configured) and may sync platform
+  artifacts such as Spanner protobundles or Pub/Sub topics.
+- This is the source-of-truth step: it makes the contract reviewable, repeatable, and consumable.
+
+## Build — implement the service and produce a deployable artifact
+
+- Work in the product build repo: `~/alis.build/<organisation-id>/build/<product-id>`.
+- Install/update the generated packages from Define, then write or edit the business logic
+  (usually Go).
+- Build a container image from a product repo commit. Docker build paths are relative to the
+  neuron folder (e.g. a top-level Dockerfile uses `.`, not `demo/v1`).
+- This connects the locked contract to real behavior.
+
+## Deploy — provision and update the runtime
+
+- Review the neuron's Terraform under its `infra/` folder.
+- Deploy the successful build version to a real environment (e.g. DEV). The environment comes
+  from the product context, not a guess.
+- Deploy makes the service reachable infrastructure (commonly Cloud Run plus supporting resources).
+- Validate end-to-end via the generated playground, usually `<neuron>/.playground/main_test.go`.
+
+## Routing — discover a skill vs run a command directly
+
+Not every Alis Build request is the same kind of work. Classify first, then act.
+
+- **Routers — discover a skill before acting.** For an ambiguous *functional* request — the
+  user wants to build, fix, add, or change something and the agent needs to know *how* — treat
+  it as a router, not a direct task. Triggers: "build it", "fix it", "add X", "change Y", and
+  capability questions ("can you help with tracing?", "are you able to add X?").
+  - Work out the intended outcome (ask ONE concise question only if it is genuinely ambiguous),
+    then call the Alis Build MCP `SearchSkills` tool FIRST with that outcome as the query (fall
+    back to `ListSkills` if it returns nothing).
+  - Present the matching skills (id, what each does, when to choose it), ask which to use, and
+    only then call `LoadSkill` and follow that skill's workflow — the loaded skill owns
+    execution.
+  - **Do NOT inspect, write, or edit code, run Define / Build / Deploy, or make commits before
+    a skill is loaded.** If no skill fits, say so and offer `RequestSkill`.
+  - For a capability question, briefly confirm it is Alis Build work, then ask the user to name
+    the specific change so you can route it through `SearchSkills`. Do not dive into the
+    codebase or give a generic how-to before they name the concrete change.
+
+- **Direct DBD commands — run the CLI, no skill needed.** When the user asks to run a *DBD
+  step* on an already-known target service, just run it (see **Executing DBD**). Triggers:
+  "define it", "deploy it", "ship it", "run define/build/deploy", "define and install". These
+  are deterministic; they do not need skill reasoning.
+
+- **Spec it — call `SpecIt` directly.** "spec it" / "spec it up", or a request to turn the
+  current session into a build specification → call the `SpecIt` tool DIRECTLY (do not route
+  through `SearchSkills`). It needs no arguments (session context is resolved server-side);
+  pass `build_spec` only when the user names an existing one to append to. Report the returned
+  BuildSpec back to the user.
+
+- **"alis" (vocative) / "dbd"** engage Alis Build context generally — then disambiguate with
+  the cases above.
+
+- **"build it" is overloaded.** It can mean "construct this feature" (a router) or "run the
+  Build step" (the `alis build` command). If a build target/context is already established and
+  the user means the DBD step, run `alis build`; if it is a functional request, route via
+  `SearchSkills`; when genuinely unclear, ask one concise question.
+
+Whenever a later request in the session would benefit from an Alis Build skill, use
+`SearchSkills` to discover one before doing the work yourself.
+
+## Executing DBD — prefer the `alis` CLI
+
+When you have a shell and the `alis` CLI is on `PATH`, **execute DBD through the CLI**, not the
+MCP `RunDefine` / `RunBuild` / `RunDeploy` tools. The CLI is deterministic, auto-detects
+context, and chains deterministic steps into one call:
+
+- **Define** (and publish packages): `alis define <pkg> --json --install`
+- **Build** (optionally deploy): `alis build <pkg> --json --deploy -e <env>`
+- **Deploy**: `alis deploy <pkg> --json` (add `--version` / `-e <env>` as needed)
+
+`<pkg>` is the package id, e.g. `alis.os.cli.v1`; it may be omitted when you are inside the
+service's directory.
+
+- **Pass `--json` for agent-driven calls.** `stdout` then carries the operation as a single
+  structured JSON object — parse `version`, `state` / `done`, `logs_uri`, and `error` from it
+  rather than scraping prose. Progress streams on `stderr`; the human one-liner (no `--json`)
+  is only for narrating to the user.
+- **Let the CLI resolve context.** It auto-detects the latest commit, Dockerfile build/retag
+  paths, and a single-environment target. Don't hand-orchestrate these or ask the user for a
+  commit SHA the CLI will pick.
+- **Long-running operations** stream to completion by default. Use `--async` to start one and
+  print its name, then re-attach with `alis operations wait <name> --json`. Never use shell
+  `sleep` / `git ls-remote` loops to pass time.
+- **The CLI is self-documenting — consult it, don't memorise it.** This primer names only the
+  DBD core. For the full command surface (e.g. `service new`, `packages`, `product`,
+  `environment`, `operations`, `login`) run `alis -h`; for a command's flags run
+  `alis <cmd> --help`. Treat that output as the source of truth; this primer and the skills
+  deliberately do not restate it.
+
+**Fallback.** Use the MCP `RunDefine` / `RunBuild` / `RunDeploy` tools only when there is no
+shell available (remote / headless agents). They run the same operation server-side; `RunDefine`
+needs an explicit commit (never `HEAD`).
+
+## Getting deeper
+
+For onboarding or the full step-by-step Simple API quickstart, load the `getting-started` skill
+via `LoadSkill`. For an ambiguous "build it" / "fix it" request, route through skill discovery
+(`SearchSkills`) before executing any DBD step.

package/opencode.example.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+
+  "plugin": ["@alis-build/opencode-plugin"],
+
+  "mcp": {
+    "api": {
+      "type": "remote",
+      "url": "https://mcp.alis.build",
+      "enabled": true
+    }
+  },
+
+  "instructions": ["~/.config/opencode/alis-build/dbd-primer.md"],
+
+  "command": {
+    "build-it": {
+      "description": "Find the right Alis Build skill for what you want to build.",
+      "template": "Run the Alis Build \"build it\" router as described in the Alis Build MCP server instructions: infer what I want built from the current request and workspace context (ask exactly one concise clarification only if the goal is ambiguous), call SearchSkills with the clarified goal, present the matching skills, and load the one I choose. Do not run Define, Build, Deploy, commits, or code edits from this router step — only the loaded skill does that, and only when its workflow requires it."
+    },
+    "fix-it": {
+      "description": "Alias for build-it: find the right Alis Build skill to fix or build something.",
+      "template": "Run the Alis Build \"fix it\" router (the fix-it alias of \"build it\") as described in the Alis Build MCP server instructions: infer what I want fixed or built from the current request, visible errors, and workspace context (ask exactly one concise clarification only if the goal is ambiguous), call SearchSkills with the clarified goal, present the matching skills, and load the one I choose. Do not run Define, Build, Deploy, commits, or code edits from this router step — only the loaded skill does that, and only when its workflow requires it."
+    }
+  },
+
+  "permission": {
+    "bash": {
+      "alis *": "allow",
+      "alis": "allow"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@alis-build/opencode-plugin",
+  "version": "0.1.0",
+  "description": "Connect opencode to Alis Build through MCP, workflow commands, and the Define-Build-Deploy primer.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "instructions",
+    "command",
+    "opencode.example.json"
+  ],
+  "keywords": [
+    "opencode",
+    "alis",
+    "build",
+    "mcp",
+    "dbd",
+    "deploys",
+    "workspaces"
+  ],
+  "author": {
+    "name": "Alis Build"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/alis-build/opencode-plugin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alis-build/opencode-plugin.git"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+/**
+ * Alis Build plugin for opencode.
+ *
+ * This file ships the one piece of behaviour that genuinely needs code: injecting
+ * the opencode session id into Alis MCP calls. Everything else the Claude Code
+ * plugin did is config in opencode (see opencode.example.json and the README):
+ *
+ *   - the MCP server            -> `mcp.api`        in opencode.json
+ *   - the always-loaded primer  -> `instructions`   in opencode.json
+ *   - the build-it / fix-it cmds -> `command/*.md`   (or the `command` config key)
+ *   - auto-approving `alis ...`  -> `permission.bash` in opencode.json
+ *
+ * opencode has no "config" hook, so a plugin cannot register MCP servers,
+ * instructions, or commands programmatically — that is why those live in config.
+ *
+ * ---------------------------------------------------------------------------
+ * Session-id injection (mirror of the Claude `inject-skill-session-id` hook)
+ * ---------------------------------------------------------------------------
+ * The Alis MCP server uses the caller's session id to resolve the active Context
+ * and prepend an <alis-runtime-context> block to LoadSkill / SpecIt results. The
+ * model never supplies it; we merge it into the outgoing tool arguments here.
+ *
+ * NOTE: opencode's plugin hook surface is younger and less documented than Claude
+ * Code's. The exact field names below (`input.tool`, `output.args`, and where the
+ * session id is exposed) MUST be verified against the installed @opencode-ai/plugin
+ * version before relying on this in production — see the README "Verify" section.
+ */
+
+// Matches the Alis MCP tools that resolve server-side Context from the session id.
+// MCP tools are exposed to opencode with a server-name prefix, so match the suffix.
+const SESSION_AWARE_TOOL = /(?:^|[._-])(LoadSkill|SpecIt)$/
+
+export const AlisBuildPlugin: Plugin = async ({ client }) => {
+  return {
+    "tool.execute.before": async (input: any, output: any) => {
+      const toolName: string = input?.tool ?? ""
+      if (!SESSION_AWARE_TOOL.test(toolName)) return
+
+      // Resolve the current session id. The precise accessor depends on the
+      // opencode plugin API version; try the documented shapes in order.
+      const sessionID: string | undefined =
+        input?.sessionID ?? input?.sessionId ?? output?.sessionID
+
+      if (!sessionID) return
+
+      // Merge session_id into the outgoing MCP arguments without clobbering
+      // anything the model already set.
+      const args = (output.args ??= {})
+      if (args.session_id == null) args.session_id = sessionID
+    },
+  }
+}
+
+export default AlisBuildPlugin