opencode-plan-cards-plugin 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-02-16
+
+### Added
+
+- Initial plugin scaffold for original OpenCode desktop + CLI.
+- Session command handling for `/plan card on|off`.
+- Session-level card mode state isolation via `Map<sessionID, boolean>`.
+- `experimental.chat.system.transform` injection for plan card workflow guidance.
+- `tool.definition` enhancement for `question` tool card-format instructions.
+- README with `file://` and npm installation options.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sakura1175
+
+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.en.md

@@ -0,0 +1,87 @@
+# opencode-plan-cards-plugin
+
+A plugin that enhances card-based planning interactions for original OpenCode (Desktop + CLI), without replacing `opencode-cli.exe`.
+
+## Features
+
+- Provides session commands:
+  - `/plan card on`
+  - `/plan card off`
+- When enabled, it injects a stricter `plan` workflow: clarify first, confirm, then output a complete plan.
+- Enhances the `question` tool definition to encourage card questions with 2–3 options and clear tradeoff descriptions.
+- Disabled by default; controlled per session.
+
+## Compatibility
+
+- OpenCode: `1.2.x` (Desktop / CLI)
+- Plugin distribution: both `file://` and npm package
+
+## Installation (Method A: Git + file://, recommended first)
+
+```powershell
+git clone <your-repo-url> opencode-plan-cards-plugin
+cd opencode-plan-cards-plugin
+npm install
+npm run build
+```
+
+Configure plugin in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE_PATH_TO/opencode-plan-cards-plugin/dist/index.js"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+> On Windows, use `file:///` paths and encode spaces as `%20`.
+
+## Installation (Method B: npm)
+
+After publishing, user config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-plan-cards-plugin@0.1.0"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+## Usage
+
+1. In a target session, run `/plan card on`
+2. Continue describing requirements in `plan`; the model prioritizes card-based clarification and confirmation
+3. To restore default behavior, run `/plan card off`
+
+## Validation Checklist
+
+1. Desktop: card interaction appears after `/plan card on`
+2. CLI: same command works
+3. `/plan card off` restores default `plan` behavior
+4. `agent.ask.hidden=true` hides ask in UI by default
+
+## Publish to npm
+
+```powershell
+npm run build
+npm publish --access public
+```
+
+## Limitations
+
+- This plugin is a workflow-guidance enhancement, not a core-level hard enforcement.
+- For hard guards (for example, strict preconditions before `plan_exit`), maintain a core fork.

package/README.ja.md

@@ -0,0 +1,87 @@
+# opencode-plan-cards-plugin
+
+オリジナルの OpenCode（Desktop + CLI）で、`plan` エージェントのカード型質問フローを強化するプラグインです。`opencode-cli.exe` の差し替えは不要です。
+
+## 機能
+
+- セッションコマンドを提供：
+  - `/plan card on`
+  - `/plan card off`
+- 有効化時、`plan` セッションにのみ「要件確認 → 最終確認 → 完全な実行計画出力」の制約を注入。
+- `question` ツール定義を強化し、2〜3択 + トレードオフ説明のカード質問を促進。
+- デフォルトは無効。セッションごとのスイッチで制御。
+
+## 互換性
+
+- OpenCode: `1.2.x`（Desktop / CLI）
+- プラグイン配布形態：`file://` と npm の両対応
+
+## インストール（方式 A：Git + file://、初回推奨）
+
+```powershell
+git clone <your-repo-url> opencode-plan-cards-plugin
+cd opencode-plan-cards-plugin
+npm install
+npm run build
+```
+
+`~/.config/opencode/opencode.json` に以下を設定：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE_PATH_TO/opencode-plan-cards-plugin/dist/index.js"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+> Windows では `file:///` 形式を使用し、空白は `%20` にしてください。
+
+## インストール（方式 B：npm）
+
+公開後、ユーザー設定：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-plan-cards-plugin@0.1.0"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+## 使い方
+
+1. 対象セッションで `/plan card on` を入力
+2. `plan` で要件を入力すると、カードによる確認フローが優先される
+3. 既定動作に戻す場合は `/plan card off`
+
+## 動作確認チェックリスト
+
+1. Desktop：`/plan card on` 後にカード質問フローが表示される
+2. CLI：同様にコマンドが有効
+3. `/plan card off` 後に標準 `plan` 挙動へ復帰
+4. `agent.ask.hidden=true` で UI の ask を非表示化
+
+## npm 公開
+
+```powershell
+npm run build
+npm publish --access public
+```
+
+## 制限事項
+
+- プラグイン層は「フロー誘導の強化」であり、コアレベルの強制制約ではありません。
+- 例：`plan_exit` 前の厳格な必須チェックなどは、コア分岐の維持が必要です。

package/README.md

@@ -0,0 +1,92 @@
+# opencode-plan-cards-plugin
+
+Language / 语言 / 言語:
+- [English](./README.en.md)
+- [简体中文](./README.zh-CN.md)
+- [日本語](./README.ja.md)
+
+让原版 OpenCode（桌面端 + CLI）获得更强的 `plan` 卡片问答流程，无需替换 `opencode-cli.exe`。
+
+## 功能
+
+- 提供会话命令：
+  - `/plan card on`
+  - `/plan card off`
+- 开启后仅在 `plan` 会话注入“先澄清、再确认、再输出完整计划”的系统约束。
+- 强化 `question` 工具描述，推动 2–3 选项 + 权衡说明的卡片提问格式。
+- 默认不强开，按会话开关控制。
+
+## 兼容性
+
+- OpenCode: `1.2.x`（桌面端 / CLI）
+- 插件形态：`file://` 与 npm 包均可
+
+## 安装（方式 A：Git + file://，推荐首发）
+
+```powershell
+git clone <your-repo-url> opencode-plan-cards-plugin
+cd opencode-plan-cards-plugin
+npm install
+npm run build
+```
+
+在 `~/.config/opencode/opencode.json` 中配置插件：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE_PATH_TO/opencode-plan-cards-plugin/dist/index.js"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+> Windows 路径需要使用 `file:///`，空格写成 `%20`。
+
+## 安装（方式 B：npm）
+
+发布后，用户配置：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-plan-cards-plugin@0.1.0"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+## 使用
+
+1. 在目标会话输入：`/plan card on`
+2. 继续在 `plan` 中描述需求，模型会优先走卡片澄清与确认流程
+3. 需要恢复默认行为时输入：`/plan card off`
+
+## 验证清单
+
+1. 桌面端：`/plan card on` 后出现卡片问答流程
+2. CLI：同样命令生效
+3. `/plan card off` 后恢复原始 `plan` 行为
+4. `agent.ask.hidden=true` 后 UI 默认不展示 ask
+
+## 发布 npm
+
+```powershell
+npm run build
+npm publish --access public
+```
+
+## 限制说明
+
+- 插件层是“流程引导增强”，不等于内核级强约束。
+- 如需硬拦截（例如强制 plan_exit 前置条件），仍需维护内核分支。

package/README.zh-CN.md

@@ -0,0 +1,87 @@
+# opencode-plan-cards-plugin
+
+让原版 OpenCode（桌面端 + CLI）获得更强的 `plan` 卡片问答流程，无需替换 `opencode-cli.exe`。
+
+## 功能
+
+- 提供会话命令：
+  - `/plan card on`
+  - `/plan card off`
+- 开启后仅在 `plan` 会话注入“先澄清、再确认、再输出完整计划”的系统约束。
+- 强化 `question` 工具描述，推动 2–3 选项 + 权衡说明的卡片提问格式。
+- 默认不强开，按会话开关控制。
+
+## 兼容性
+
+- OpenCode: `1.2.x`（桌面端 / CLI）
+- 插件形态：`file://` 与 npm 包均可
+
+## 安装（方式 A：Git + file://，推荐首发）
+
+```powershell
+git clone <your-repo-url> opencode-plan-cards-plugin
+cd opencode-plan-cards-plugin
+npm install
+npm run build
+```
+
+在 `~/.config/opencode/opencode.json` 中配置插件：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///ABSOLUTE_PATH_TO/opencode-plan-cards-plugin/dist/index.js"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+> Windows 路径需要使用 `file:///`，空格写成 `%20`。
+
+## 安装（方式 B：npm）
+
+发布后，用户配置：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-plan-cards-plugin@0.1.0"
+  ],
+  "agent": {
+    "ask": {
+      "hidden": true
+    }
+  }
+}
+```
+
+## 使用
+
+1. 在目标会话输入：`/plan card on`
+2. 继续在 `plan` 中描述需求，模型会优先走卡片澄清与确认流程
+3. 需要恢复默认行为时输入：`/plan card off`
+
+## 验证清单
+
+1. 桌面端：`/plan card on` 后出现卡片问答流程
+2. CLI：同样命令生效
+3. `/plan card off` 后恢复原始 `plan` 行为
+4. `agent.ask.hidden=true` 后 UI 默认不显示 ask
+
+## 发布 npm
+
+```powershell
+npm run build
+npm publish --access public
+```
+
+## 限制说明
+
+- 插件层是“流程引导增强”，不等于内核级强约束。
+- 如需硬拦截（例如强制 `plan_exit` 前置条件），仍需维护内核分支。

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const PlanCardsPlugin: Plugin;
+export default PlanCardsPlugin;

package/dist/index.js

@@ -0,0 +1,115 @@
+const CARD_COMMAND_PATTERN = /^\/plan\s+card\s+(on|off)$/i;
+const cardModeBySession = new Map();
+const lastAgentBySession = new Map();
+const PLAN_CARD_SYSTEM_APPENDIX = `
+Plan card mode is enabled for this session.
+
+Mandatory workflow:
+1. Clarify missing requirements before generating a final plan.
+2. Use the question tool for clarification and confirmation gates.
+3. Ask 1-3 focused questions per round.
+4. Each question must represent one decision only, with a short header.
+5. Provide 2-3 options per question, each with a short tradeoff description.
+6. Keep custom input available (do not add catch-all "Other" options).
+7. After clarification, ask one final confirmation question before outputting the final plan.
+8. Output one complete actionable plan only after user confirmation.
+`.trim();
+const QUESTION_TOOL_APPENDIX = `
+Card interaction requirements:
+- Keep each question focused on one decision.
+- Keep header short (<= 30 chars).
+- Include 2-3 options with clear tradeoffs.
+- Put the recommended option first and suffix it with "(Recommended)" when applicable.
+- Do not add "Other" options; rely on custom input support.
+`.trim();
+function isTextPart(part) {
+    return part.type === "text";
+}
+function extractCardModeCommand(parts) {
+    const textParts = parts.filter(isTextPart).filter((part) => !part.synthetic);
+    if (textParts.length !== 1)
+        return;
+    const match = CARD_COMMAND_PATTERN.exec(textParts[0].text.trim());
+    if (!match)
+        return;
+    return match[1].toLowerCase();
+}
+function commandConfirmationPrompt(command) {
+    if (command === "on") {
+        return [
+            "The command /plan card on has already been applied for this session.",
+            "Reply with exactly one short confirmation sentence in the user's language.",
+            "Do not ask extra questions and do not produce a plan in this reply.",
+        ].join("\n");
+    }
+    return [
+        "The command /plan card off has already been applied for this session.",
+        "Reply with exactly one short confirmation sentence in the user's language.",
+        "Do not ask extra questions and do not produce a plan in this reply.",
+    ].join("\n");
+}
+function appendUniqueDescription(base, appendix) {
+    const normalized = appendix.trim();
+    if (!normalized)
+        return base;
+    if (base.includes(normalized))
+        return base;
+    if (!base.trim())
+        return normalized;
+    return `${base.trim()}\n\n${normalized}`;
+}
+function patchQuestionParameters(parameters) {
+    const questionItem = parameters?.properties?.questions?.items;
+    const questionProps = questionItem?.properties;
+    if (!questionProps || typeof questionProps !== "object")
+        return;
+    if (questionProps.header) {
+        questionProps.header.description = "Very short header (<=30 chars) for one decision.";
+    }
+    if (questionProps.question) {
+        questionProps.question.description = "Single clear question for one decision.";
+    }
+    if (questionProps.options) {
+        questionProps.options.description =
+            "Provide 2-3 options; each option must include a short tradeoff description.";
+    }
+}
+export const PlanCardsPlugin = async () => {
+    return {
+        event: async ({ event }) => {
+            if (event.type !== "session.deleted")
+                return;
+            const sessionID = event.properties?.sessionID;
+            if (!sessionID)
+                return;
+            cardModeBySession.delete(sessionID);
+            lastAgentBySession.delete(sessionID);
+        },
+        "chat.message": async (input, output) => {
+            const sessionID = input.sessionID;
+            const command = extractCardModeCommand(output.parts);
+            if (command) {
+                cardModeBySession.set(sessionID, command === "on");
+                output.message.agent = "ask";
+                output.message.system = appendUniqueDescription(output.message.system ?? "", commandConfirmationPrompt(command));
+            }
+            lastAgentBySession.set(sessionID, output.message.agent);
+        },
+        "experimental.chat.system.transform": async (input, output) => {
+            if (!input.sessionID)
+                return;
+            if (!cardModeBySession.get(input.sessionID))
+                return;
+            if (lastAgentBySession.get(input.sessionID) !== "plan")
+                return;
+            output.system.push(PLAN_CARD_SYSTEM_APPENDIX);
+        },
+        "tool.definition": async (input, output) => {
+            if (input.toolID !== "question")
+                return;
+            output.description = appendUniqueDescription(output.description, QUESTION_TOOL_APPENDIX);
+            patchQuestionParameters(output.parameters);
+        },
+    };
+};
+export default PlanCardsPlugin;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "opencode-plan-cards-plugin",
+  "version": "0.1.0",
+  "description": "Plan card interaction enhancement plugin for OpenCode",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "plan",
+    "cards"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.2.0 <2"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.2.0",
+    "@opencode-ai/sdk": "^1.2.0",
+    "typescript": "^5.7.3"
+  }
+}