golden-hoop-spell-opencode 0.1.0 → 0.1.1

package/README.md

@@ -147,6 +147,23 @@ codegraph 是本插件的上下文提取后端，提供符号级代码图谱（c
 
 > `ghs-code` 的编码子代理同样由 Task tool 派发，但它是临时的（由 `ghs-code` 返回的 feature-impl 提示即时构造），不是随包发布的固定模板，故不在本表。
 
+## Slash Commands（8 个 `/ghs-*` 命令）
+
+插件安装后，8 个 `/ghs-*` 斜杠命令在**首次启动时自动注册**——通过 Plugin 的 `config` hook 注入 `cfg.command`，无需手动创建 `.md` 文件或额外重启。
+
+| 命令 | 用法 | 说明 |
+|---|---|---|
+| `/ghs-init` | `/ghs-init <项目名>` | 初始化 ghs 追踪文件 |
+| `/ghs-config` | `/ghs-config` | 重新生成子代理 markdown |
+| `/ghs-plan-start` | `/ghs-plan-start` | 启动计划生成流程 |
+| `/ghs-sprint` | `/ghs-sprint "<名称>" "<目标>"` | 创建新 sprint |
+| `/ghs-code` | `/ghs-code [feature_id] [--parallel]` | 派发 feature 实现 |
+| `/ghs-status` | `/ghs-status` | 查看项目状态 |
+| `/ghs-archive` | `/ghs-archive [--dry-run\|--list]` | 归档已完成 sprint |
+| `/ghs-force-archive` | `/ghs-force-archive <nonce>` | 强制归档所有 sprint |
+
+> 内部 dispatcher 工具 `ghs-plan-review` 和 `ghs-plan-finalize` 不提供斜杠命令——它们由 plan 工作流自动衔接，不直接面向用户。
+
 ## 工作流
 
 OpenCode 会话中的主 AI 驱动每一次状态转移，**通过 Task tool 派发隔离子代理完成 LLM 工作**。完整顺序：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golden-hoop-spell-opencode",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "src/index.ts",
   "devDependencies": {
     "@opencode-ai/plugin": "1.4.3",

package/src/lib/commands.ts

@@ -0,0 +1,101 @@
+// Slash command definitions for the ghs-* workflow tools.
+//
+// These are injected into the OpenCode Config object's `command` field via
+// the plugin's `config` hook (see src/plugin.ts). OpenCode reads
+// `cfg.command` when the TUI requests `GET /command`, so the commands are
+// available on the very first startup — no file writes or restart needed.
+//
+// Each entry conforms to the OpenCode Command shape:
+//   - `template`:  The prompt sent to the LLM when the user types the command.
+//                  Supports `$ARGUMENTS`, `$1`, `$2`, … for argument passing.
+//   - `description`: Shown in the TUI command palette.
+//
+// Commands map 1:1 to the 8 user-facing ghs-* tools. The two internal
+// dispatcher tools (ghs-plan-review, ghs-plan-finalize) are intentionally
+// excluded — they consume raw delimited subagent output and are never
+// invoked directly by the user.
+
+/**
+ * A single slash command definition matching OpenCode's Config.command shape.
+ */
+export interface GhCommand {
+  template: string;
+  description: string;
+}
+
+/**
+ * The 8 user-facing `/ghs-*` slash commands, keyed by command name.
+ *
+ * Injected into `cfg.command` by the plugin's `config` hook. When the user
+ * types `/ghs-status` (etc.) in the TUI, OpenCode sends the corresponding
+ * `template` string to the LLM, which then calls the matching tool.
+ *
+ * Argument-passing commands use OpenCode's built-in placeholders:
+ *   - `$ARGUMENTS` — the entire argument string
+ *   - `$1`, `$2`, … — positional arguments
+ */
+export const GHS_COMMANDS: Record<string, GhCommand> = {
+  "ghs-init": {
+    description: "初始化 ghs 追踪文件（.ghs/ + .opencode/agents/）",
+    template:
+      'Call the `ghs-init` tool to initialise the Golden Hoop Spell tracking files for this project.\n\n' +
+      'Arguments: $ARGUMENTS\n\n' +
+      "If arguments are provided, use the first argument as `project_name`. " +
+      "If `--description` is followed by a quoted string, pass it as `description`. " +
+      "If `--force` is present, set `force: true`. " +
+      "If no project name is given, ask the user for one before calling the tool.",
+  },
+  "ghs-config": {
+    description: "重新生成 ghs 子代理 markdown（编辑 .ghs/ghs.json 后调用）",
+    template:
+      "Call the `ghs-config` tool to regenerate the ghs subagent markdown files " +
+      "from the current `.ghs/ghs.json` config.\n\n" +
+      "If `--dry-run` is present in the arguments, pass `dry_run: true`.",
+  },
+  "ghs-plan-start": {
+    description: "启动 ghs 计划生成流程（上下文快照 → 计划设计 → 评审）",
+    template:
+      "Call the `ghs-plan-start` tool to start a new Golden Hoop Spell " +
+      "plan-generation loop.",
+  },
+  "ghs-sprint": {
+    description: "创建新的 ghs sprint（分解为原子 feature）",
+    template:
+      "Call the `ghs-sprint` tool to create a new sprint skeleton in features.json.\n\n" +
+      "Arguments: $ARGUMENTS\n\n" +
+      "Parse the arguments as: the first quoted string as `sprint_name`, " +
+      "and the remainder (or second quoted string) as `goal`. " +
+      "If either is missing, ask the user for the missing value(s) before calling the tool.",
+  },
+  "ghs-code": {
+    description: "派发 ghs feature 实现（单个或并行批次）",
+    template:
+      "Call the `ghs-code` tool to dispatch feature implementation.\n\n" +
+      "Arguments: $ARGUMENTS\n\n" +
+      "If a feature ID (e.g. `s5-feat-003`) is provided, pass it as `feature_id`. " +
+      "If `--parallel` is present, set `parallel: true`. " +
+      "If no arguments are given, call without `feature_id` to get the next ready feature.",
+  },
+  "ghs-status": {
+    description: "显示 ghs 项目状态（sprint/feature 进度）",
+    template:
+      "Call the `ghs-status` tool to display the current Golden Hoop Spell project status.",
+  },
+  "ghs-archive": {
+    description: "归档已完成的 ghs sprint",
+    template:
+      "Call the `ghs-archive` tool to archive completed sprints.\n\n" +
+      "Arguments: $ARGUMENTS\n\n" +
+      "If `--dry-run` is present, pass `dry_run: true` for a preview. " +
+      "If `--list` is present, pass `list: true` to list without archiving.",
+  },
+  "ghs-force-archive": {
+    description: "强制归档所有 ghs sprint（含未完成的）",
+    template:
+      "Call the `ghs-force-archive` tool to force-archive all sprints regardless of status.\n\n" +
+      "This requires a `transcription` nonce token — call `ghs-archive` first " +
+      "to obtain one, then pass it here.\n\n" +
+      "Arguments: $ARGUMENTS\n\n" +
+      "Use the first argument as the `transcription` value.",
+  },
+};

package/src/plugin.ts

@@ -7,6 +7,14 @@
 //     ghs-status / ghs-archive / ghs-force-archive) under their hyphenated
 //     keys — the complete plan §3.4 D2 tool surface (Phase 0 spike 001
 //     confirmed hyphenated keys load + round-trip correctly).
+//   - Injects 8 `/ghs-*` slash commands into the OpenCode Config via the
+//     `config` hook. Source analysis of OpenCode's plugin/index.ts +
+//     config/config.ts + command/index.ts confirmed that the `config` hook
+//     receives the same mutable Config object reference that the Command
+//     service later reads via `config.get()`. The hook runs during plugin
+//     initialization (before the HTTP server accepts requests), so the
+//     injected commands are available on the very first startup — no file
+//     writes or restart needed.
 //   - Pushes a single-line workflow hint into the AI's system prompt via the
 //     `experimental.chat.system.transform` hook (Phase 0 spike 001 confirmed
 //     strings pushed here land in the system prompt verbatim).
@@ -29,6 +37,7 @@ import { planStartTool } from "./tools/plan-start.ts";
 import { planReviewTool } from "./tools/plan-review.ts";
 import { planFinalizeTool } from "./tools/plan-finalize.ts";
 import { codeTool } from "./tools/code.ts";
+import { GHS_COMMANDS } from "./lib/commands.ts";
 
 /**
  * Single-line hint pushed into the AI's system prompt on every chat. Lists
@@ -47,7 +56,8 @@ const SYSTEM_HINT_TEXT =
   "Golden Hoop Spell (ghs) plugin — orchestrates a structured init → plan → sprint → code → status → archive workflow. " +
   "Tools implemented: ghs-init, ghs-config, ghs-plan-start, ghs-plan-review, ghs-plan-finalize, ghs-sprint, ghs-code, ghs-status, ghs-archive, ghs-force-archive. " +
   "Workflow order: ghs-init → ghs-config → ghs-plan-start → ghs-plan-review → ghs-plan-finalize → ghs-sprint → ghs-code → ghs-status → ghs-archive. " +
-  "Model IDs for the 3 plan-dispatcher subagents are user-configurable via `.ghs/ghs.json`; after editing run `ghs-config` then restart OpenCode.";
+  "Model IDs for the 3 plan-dispatcher subagents are user-configurable via `.ghs/ghs.json`; after editing run `ghs-config` then restart OpenCode. " +
+  "Slash commands /ghs-init, /ghs-config, /ghs-plan-start, /ghs-sprint, /ghs-code, /ghs-status, /ghs-archive, /ghs-force-archive are auto-registered on startup.";
 
 /**
  * The ghs OpenCode plugin. Default-exported from `src/index.ts`.
@@ -70,6 +80,10 @@ export const ghsPlugin: Plugin = async () => ({
     "ghs-archive": archiveTool,
     "ghs-force-archive": forceArchiveTool,
   },
+  config: async (cfg) => {
+    cfg.command ??= {};
+    Object.assign(cfg.command, GHS_COMMANDS);
+  },
   "experimental.chat.system.transform": async (_input, output) => {
     output.system.push(SYSTEM_HINT_TEXT);
   },