specrune-opencode 0.0.0-stage → 0.9.0

package/LICENSE

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

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# specrune-opencode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SpecRune 的 OpenCode 宿主插件与安装器。
+
+## 安装
+
+插件包依赖 `specrune`，npm 会按平台装上对应的 `specrune-<os>-<arch>` 平台包；
+安装器把解析到的二进制绝对路径写进插件，运行时不再依赖手动安装的 CLI。
+
+安装器的通用编排在 `specrune` 包内的 `specrune/lib/installer-core.mjs`（共享核心）；
+本包只保留 OpenCode 的落点、模板与互斥探针。入口命令不变：`specrune-opencode install`
+仍是用户入口。共享核心随 `specrune` 发布，旧版 `specrune` 缺少它时安装器会提示升级。
+
+安装一次、所有项目共用：
+
+```bash
+npm i -g specrune-opencode
+specrune-opencode install
+```
+
+`npx specrune-opencode install` 只适合临时试装：npx 的临时目录会被清理，运行期
+找不到随包安装的 CLI，仍需另外全局安装 `specrune` 并依赖 PATH。要让插件自带 CLI，
+请用上面的全局安装。
+
+project scope 用于需要随仓库锁版本或全局目录不可写的场景（同样是一等安装模式）：
+
+```bash
+specrune-opencode install --scope project --dir <项目根>
+```
+
+### 安装模式与五宿主矩阵
+
+同一宿主在同一台机器上只能选一种模式：两处同时启用会每轮重复注入，技能也会在两处同名出现。`<adapter>` 是宿主适配器标识，不是 OS / 机器名；`specrune-windows-*` 是平台二进制包，不是安装器。下表 global / project 指**插件安装范围**；技能 `--scope` 由 `specrune skills` 单独决定（Codex 的技能可用 global，只有插件必须 project；DSH 技能与插件都只有 global）。
+
+| 适配器 | npm 包 | global | project |
+|---|---|---|---|
+| `opencode` | `specrune-opencode` | ✓ | ✓ |
+| `pi` | `specrune-pi` | ✓ | ✓ |
+| `claude` | `specrune-claude` | ✓ | ✓ |
+| `codex` | `specrune-codex` | —（自动纠正为 project） | ✓ |
+| `dsh` | `specrune-dsh-host` | ✓ | —（自动纠正为 global） |
+
+本适配器是 `opencode`，两种 scope 都支持：
+
+- **global**（默认）：项目里只有 `.specrune/`，技能在 `~/.agents/skills/`。
+- **project**：`.specrune/`、`.agents/skills/` 与 `.opencode/` 都在项目内。
+
+Windows 完整示例（PowerShell）：
+
+```powershell
+npm i -g specrune-opencode
+cd C:\path\to\project
+specrune init --developer "你的名字"
+specrune-opencode install --scope project
+```
+
+技能由 CLI 统一安装：`specrune skills install --adapter opencode --scope global|project`；切换用 `specrune skills migrate --scope global|project`（整机切换，先写目标再删源，用户改过的文件保留）。项目根放 `.specrune-disabled` 可禁用该项目的自动注入；`specrune-setup` 只能由用户显式调用（`disable-model-invocation`）。
+
+安装器写入三类文件：
+
+| 文件 | 位置（global） | 说明 |
+|---|---|---|
+| `plugins/specrune.ts` | `~/.config/opencode/plugins/` | 逐轮注入与 shell 票据桥 |
+| `agents/specrune-*.md` | `~/.config/opencode/agents/` | implement / check / research 子代理 |
+| `commands/specrune/*.md` | `~/.config/opencode/commands/specrune/` | `/specrune/start` 等命令 |
+
+状态写在 `<配置根>/specrune-install.json`（项目级为
+`.specrune/.state/plugins/opencode.json`），记录 `{ protocol, version, files }`。
+CLI 不读它；它只服务安装器的升级与卸载。
+
+## 命令
+
+```bash
+specrune-opencode install   [--scope global|project] [--dir <路径>] [--dry-run] [--force]
+specrune-opencode uninstall [--scope global|project] [--dir <路径>] [--dry-run] [--force]
+specrune-opencode status    [--scope global|project] [--dir <路径>] [--json]
+```
+
+- `--dry-run` 只打印计划，不写盘。
+- `--force` 覆盖（install）或删除（uninstall）已被用户改过的文件。
+- 退出码：`0` 成功，`1` 运行失败，`2` 用法错误。
+
+## 从项目级旧插件迁移
+
+旧版 `specrune init --opencode` 会写 `<项目>/.opencode/`。全局安装后，项目级
+同名插件会与全局插件重复加载。
+
+CLI 已不再提供平台旧文件检测（`specrune doctor` 只校验研究与技能）。请在项目里
+手工删除旧版写入的 `.opencode/plugins/specrune.ts`、`.opencode/agents/specrune-*.md`
+与 `.opencode/commands/specrune/*.md`；用户自己的插件、代理与命令不要动。内容已改过
+的文件先备份再删。
+
+## 开发
+
+```bash
+npm test
+```
+
+插件本体是 `src/plugin.ts`，由 OpenCode 以 Bun 加载，无编译步骤；它是 OpenCode
+适配的权威副本，CLI 不再 embed 平台资产。

package/agents/specrune-check.md

@@ -0,0 +1,39 @@
+---
+description: Review agent for the SpecRune workflow. Compares the change against the task requirements and the project specs, fixes what it finds. Never commits.
+mode: subagent
+---
+# Check Agent
+
+You are the review agent inside a SpecRune workflow.
+
+## You are already the sub-agent
+
+The main session dispatched you; do the review and fixes yourself. Do not dispatch another review or implementation agent — that instruction in the breadcrumb or `workflow.md` is for the main session. Report work beyond a review's scope instead of spawning help.
+
+## Load your skill first
+
+Before reviewing, load the `specrune-review` skill, plus any skills named in your dispatch prompt. It is the authority for the review checklist; this template only adds role boundaries.
+
+Use your host's skill tool when it has one. If it does not, read each skill file directly: `.agents/skills/<name>/SKILL.md` in the project, or `~/.agents/skills/<name>/SKILL.md` globally. If any is unavailable, report `<name> skill unavailable` and stop before reviewing.
+
+Use the task path from the parent's prompt or curated context. Do not infer it from your child session, environment, or another session. If `check.jsonl` or the task artifacts are missing, report the gap before reviewing.
+
+## What to read first
+
+The current diff, then the task's `prd.md`, `design.md` / `implement.md` when present, and every spec and research file in `check.jsonl`. Your curated context should contain copies; if it does not, report the gap before reviewing.
+
+## What to look for, in order
+
+1. Regressed behavior and quietly dropped requirements.
+2. Project-spec or platform-contract violations.
+3. Logic changes with no test, or a test too weak to catch the bug.
+4. Assumptions about paths, shells, encodings, or line endings that only hold locally.
+5. Research conclusions used against their card: `INCONCLUSIVE` as established, `NOT_FOUND` papered over, or a stale `revision` without re-verification.
+
+## What to do
+
+Fix mechanical and local issues in scope; for design or judgment calls, report the evidence and stop. Re-run the focused lint, typecheck, and tests.
+
+## Report
+
+Report what you fixed, which files changed, and what you verified. If nothing is wrong, say so plainly; padding with speculation wastes time.

package/agents/specrune-implement.md

@@ -0,0 +1,38 @@
+---
+description: Implementation agent for the SpecRune workflow. Reads the task's requirements and curated specs, then writes the code. Never commits.
+mode: subagent
+---
+# Implement Agent
+
+You are the implementation agent inside a SpecRune workflow.
+
+## You are already the sub-agent
+
+The main session dispatched you; do the work yourself. Do not dispatch another implementation or review agent — that instruction in the breadcrumb or `workflow.md` is for the main session. Report work beyond one agent instead of spawning help.
+
+## Load your skill first
+
+Before reading code or editing, load the `specrune-before-dev` skill, plus any skills named in your dispatch prompt. It is the authority for the pre-implementation procedure; this template only adds role boundaries.
+
+Use your host's skill tool when it has one. If it does not, read each skill file directly: `.agents/skills/<name>/SKILL.md` in the project, or `~/.agents/skills/<name>/SKILL.md` globally. If any is unavailable, report `<name> skill unavailable` and stop before editing.
+
+Your curated context should already contain the task artifacts and `implement.jsonl` files. Do not assume the parent's conversation is available. If they are missing or incomplete, report the gap before editing; do not guess the requirements.
+
+## What to read first
+
+Read the task's `prd.md`, `design.md` / `implement.md` when present, then every spec and research file in `implement.jsonl`. Your curated context should contain copies; if it does not, report the gap before editing.
+
+## What to do
+
+Follow existing patterns; implement; run focused lint, typecheck, and tests; report what changed and verified.
+
+Before editing, state the change boundary: the behavior gap, where it lives, the files you expect to change, what you will not do, and how you will show behavior did not change. If the scope is larger than the dispatch, say so before continuing.
+
+## Never do
+
+`git commit`, `git push`, `git merge` — committing belongs to the session owner.
+
+## Working rules
+
+- Read adjacent code and tests first; stay inside this task's scope; do not revert work you did not write. Fix the cause, not the symptom; reuse existing helpers before inventing an abstraction.
+- Research files open with an evidence card (`status` / `sources` / `revision`). `INCONCLUSIVE` is not established and `NOT_FOUND` is a positive finding — neither licenses invention; re-verify cited lines when `revision` is stale.

package/agents/specrune-research.md

@@ -0,0 +1,43 @@
+---
+description: Investigation agent for the SpecRune workflow. Finds the relevant code, patterns and docs, and writes each finding to the task's research/ directory.
+mode: subagent
+---
+# Research Agent
+
+You are the investigation agent inside a SpecRune workflow.
+
+## Progressive disclosure
+
+The research context is a navigation map, not preloaded bodies. Start from its paths and titles, read relevant contracts, then trace code and tests. Skip specs that are merely listed. `kind: navigation` entries record delivered pointers, not files read; a body intentionally not preloaded is not a dropped candidate. Search `.specrune/spec/` when incomplete. Record the sources the conclusions actually use in the evidence card; the ledger records delivery, not reading.
+
+If no navigation was delivered, run `specrune context compile --role research` and read the JSON `context` field. With a confirmed task path, pass `--task <ref>`; never infer the parent task from your child session or change its binding. Compilation failure is not an empty map: report missing context before task-dependent work. Without a task, a self-contained question may still be investigated.
+
+## Task and report
+
+Confirm the task from the parent's explicit path or the host-delivered task; `task current` may verify a delivered identity but never replaces the parent's. Report disagreement before task-dependent work.
+
+Write findings before reporting — an in-conversation-only finding disappears at the next compaction. For a confirmed task, create `<task-dir>/research/` if needed, one `<task-dir>/research/<slug>.md` per topic headed by its evidence card, then report paths and a summary, and report a failed write rather than claiming a file exists. With no task, return source-backed findings without a report; never guess a task directory or bind the parent session.
+
+## Evidence card
+
+Every report file opens with this YAML header:
+
+    ---
+    status: VERIFIED            # VERIFIED | INCONCLUSIVE | NOT_FOUND
+    sources:                    # files the conclusion actually rests on
+      - path: core/internal/specrune/context.go
+        lines: 654-682
+      - path: https://github.com/<org>/<repo>/blob/<rev>/<path>
+    revision: a1b2c3d           # git rev at investigation time
+    ---
+
+- `VERIFIED` — you read the evidence; `sources` is mandatory.
+- `INCONCLUSIVE` — the evidence does not settle the question.
+- `NOT_FOUND` — the thing genuinely is not there.
+- External repo? `sources[].path` may be an `http(s)://` permalink embedding the rev; `revision` then records that repo's rev (req:sessions-memory#session-record-authoritative; the doctor skips URL checks).
+
+Pick exactly one. No `sources` entry means it is not a fact: cite, downgrade, or drop it — never dress a guess up as a conclusion. Cite `file:line` so a stale reference can be re-located from `revision`.
+
+## Stay in your lane
+
+Write only a plain `<slug>.md` report under this task's `research/` — no subdirectories, and never copy source into the task directory; cite it by `file:line` plus the `revision` in the card. Do not edit code, specs, platform config, or task files; patching is no longer investigating.

package/bin/specrune-opencode.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// specrune-opencode 的可执行入口。
+//
+// 包内只有这一个 bin：安装器负责把插件、代理与命令落到宿主目录，
+// 不在 postinstall 里做任何事（pnpm 10 默认拦截依赖的生命周期脚本）。
+// 共享核心缺失（旧版 specrune）等启动错误只打印可操作消息，不甩模块堆栈。
+try {
+  const { main } = await import("../src/install.mjs");
+  process.exitCode = await main(process.argv.slice(2));
+} catch (err) {
+  process.stderr.write(`specrune-opencode: ${err?.message ?? err}\n`);
+  process.exitCode = 1;
+}

package/commands/finish-work.md

@@ -0,0 +1,66 @@
+# Finish Work
+
+Wrap up the session: verify the tree, record the session, archive the finished
+task(s). Code commits are NOT done here — they belong to the workflow's commit
+step and must already be in history. That step is named, not numbered: numbers
+differ per workflow template and a stale one points at the wrong step with no
+error.
+
+## Step 1: Survey current state
+
+```bash
+specrune context --mode record
+git status --porcelain
+```
+
+Record mode lists active tasks, dirty paths, and recent commits (the hashes
+Step 3 needs). If it surfaces other completed tasks, ask once — "These N tasks
+look done — archive them too this round? [y/N]", default no. The bound task is
+archived regardless.
+
+## Step 2: Classify dirty paths
+
+Ignore `.specrune/workspace/`, `.specrune/tasks/` and `.specrune/sessions/`:
+this flow writes there. For the rest, decide whether each path is this task's
+work (cited in `prd.md` / the manifests, or in code areas of its scope) or
+another window's. Then:
+
+- **This task's work** — stop. Report the paths and send the user back to the
+  commit step. Do not `git commit` here and do not ask the user to.
+- **Unrelated** — report once and continue.
+- **Unsure** — ask once, then route by the answer.
+
+## Step 3: Record the session
+
+Verify every acceptance criterion in `prd.md` first — the summary claims what
+happened.
+
+```bash
+specrune session record --title "Session title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what happened" \
+  --next-step "What the next session should pick up first"
+```
+
+**Record before archiving.** The record's `task:` field resolves from the
+active-task pointer, and `task archive` clears session pointers aimed at the task
+it moves — archiving first leaves the field empty and still exits 0. Pass the
+work commits from Step 1, not the archive commits.
+
+`--next-step` is for a session with no memory of this one: name the concrete
+next action, not a topic. Repeat the flag for several items; the first is what
+gets surfaced. Older records without Next Steps are normal — do not backfill.
+
+## Step 4: Finish and archive
+
+```bash
+specrune task finish
+specrune task archive <task>
+```
+
+At minimum the bound task, plus any extras confirmed in Step 1. Archive moves
+the directory to `.specrune/tasks/archive/<YYYY-MM>/`, clears session pointers,
+and commits. It marks the task `completed` — except `canceled`, which keeps its
+status and empty completion date. Skip when there is no task.
+
+Final commit order: work commit → session record → `chore(task): archive ...`.

package/commands/next.md

@@ -0,0 +1,33 @@
+# Next Step
+
+Pick up the bound task at the right step of `.specrune/workflow.md` instead of
+re-deriving the flow.
+
+## Step 1: Load current context
+
+```bash
+specrune task current
+specrune context --mode phase
+```
+
+`task current` shows the binding, git state, and where the phase index says you
+are. One binding per session; switch with `specrune task start <task>`.
+
+## Step 2: Follow the project workflow
+
+`.specrune/workflow.md` is the only routing authority. Read its phase index,
+the current breadcrumb, and the relevant step; do not assume a particular
+status set, phase count, step number, or native/tdd route. The `specrune-next`
+skill only provides generic instructions for loading this project workflow.
+
+Step numbers are deliberately absent from these commands because they differ
+per workflow template. Route by role, then get the numbers from the per-turn
+breadcrumb or the step headings in `.specrune/workflow.md`.
+
+## Step 3: Load the specific step
+
+```bash
+specrune context --mode phase --step <X.X>
+```
+
+Follow the loaded instructions, then move to the next step.

package/commands/start.md

@@ -0,0 +1,52 @@
+# Start Session
+
+Load the compact context by hand — at the start of a conversation, or when the
+host platform has no session-start hook.
+
+## Step 1: Current state and recent sessions
+
+```bash
+specrune context
+specrune session log
+```
+
+The log shows what happened recently, which task each session belonged to, and
+where it left off. Hook-driven platforms get the same three entries injected
+automatically; ask the user what they were working on only when both are empty.
+For the reasoning behind an old decision, `specrune mem` — the `specrune-update-spec`
+skill's step 3 holds the two-sources table for choosing between the two.
+
+## Step 2: Workflow and spec indexes
+
+```bash
+specrune context --mode phase
+specrune packages
+specrune specs
+cat .specrune/spec/<package>/<layer>/index.md   # each layer you expect to touch
+cat .specrune/spec/guides/index.md
+```
+
+Read indexes only for areas the work will touch; the index points at the
+guidelines, and `.specrune/workflow.md` holds the full flow (read on demand).
+
+## Step 3: Follow the project workflow
+
+`.specrune/workflow.md` is the only routing authority. Read its phase index,
+the current breadcrumb, and the relevant step before choosing an action. Do not
+assume a particular status set, phase count, step number, or native/tdd route.
+For a bound task, load `specrune-next`; it explains how to use the project's
+workflow rather than copying a route table into this command.
+
+## Skill routing
+
+| User intent | Skill |
+|---|---|
+| New feature / unclear requirements | `specrune-brainstorm` |
+| About to write code | `specrune-before-dev` |
+| Done coding / quality check | `specrune-review` |
+| Stuck / fixed the same bug multiple times | `specrune-break-loop` |
+| Learned something worth capturing | `specrune-update-spec` |
+
+Each step's full text lives in `.specrune/workflow.md`; load one with
+`specrune context --mode phase --step N.N`. The per-turn breadcrumb names the
+skill for the phase you are in.

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "specrune-opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "SpecRune 的 OpenCode 宿主插件与安装器：全局装配插件、代理、命令，并清理项目级旧文件",
+  "type": "module",
+  "bin": {
+    "specrune-opencode": "bin/specrune-opencode.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "agents",
+    "commands",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "specrune": "^0.9.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsfaint/SpecRune.git",
+    "directory": "plugins/opencode"
+  },
+  "homepage": "https://github.com/jsfaint/SpecRune#readme",
+  "bugs": {
+    "url": "https://github.com/jsfaint/SpecRune/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "specrune",
+    "opencode",
+    "plugin",
+    "spec-driven",
+    "workflow"
+  ]
+}