opencode-agent-skill 12.0.0-beta.0 → 13.0.0-beta.1

package/docs/NPM-PUBLISH.md

@@ -27,36 +27,50 @@ Use:
 
 ```cmd
 npm pack
-npm install -g .\opencode-agent-skill-11.0.0.tgz --allow-scripts=opencode-agent-skill
+npm install -g .\opencode-agent-skill-13.0.0-beta.1.tgz --allow-scripts=opencode-agent-skill
+ocskill install
 ocskill status
 ocskill doctor
 ```
 
+For the current V13 beta, also open a fresh OpenCode V2 session, check `/plugins`, and call `ues.capabilities`. Native parallel should only be exercised when `freshDispatch` is `true`.
+
 For routine development, the automated `smoke:pack` test uses an isolated npm prefix/OpenCode config so it does not replace the developer's currently installed UES.
 
 ## Manual publish
 
+Before publishing, verify the exact prerelease version is not already present:
+
+```cmd
+npm view opencode-agent-skill@13.0.0-beta.1 version --registry=https://registry.npmjs.org/
+```
+
+If it is not present, a manual prerelease publish uses `next`, not `latest`:
+
 ```cmd
 npm login
 npm whoami
 npm run ci
-npm publish --access public
+npm publish --access public --provenance --tag next
 ```
 
 After publication verify:
 
 ```cmd
 npm view opencode-agent-skill versions --json
-npm view opencode-agent-skill@11.0.0 version
+npm view opencode-agent-skill@13.0.0-beta.1 version
 npm dist-tag ls opencode-agent-skill
 ```
 
-The expected release tag is:
+For V13 beta the expected dist-tags are:
 
 ```text
 latest: 11.0.0
+next: 13.0.0-beta.1
 ```
 
+Do not move `latest` to V13 until the prerelease is intentionally promoted stable.
+
 ## GitHub Actions publishing
 
 The repository's publish workflow is OIDC/provenance-ready and runs the same package validation before `npm publish`.
@@ -71,7 +85,7 @@ Workflow: publish.yml
 
 Then the GitHub-hosted workflow can authenticate through OIDC instead of a long-lived npm publish token. npm Trusted Publishing requires the corresponding publisher relationship to be configured on npm; repository code alone cannot create that account-side trust relationship.
 
-Until the npm-side Trusted Publisher relationship is configured, the workflow can fall back to a valid `NPM_TOKEN`. After OIDC publishing is verified, remove long-lived publish-token access where practical.
+The current `publish.yml` is tag-only. A matching prerelease tag such as `v13.0.0-beta.1` runs the full package gate and publishes with npm dist-tag `next`; a stable version publishes to `latest`. The workflow first checks whether that exact version already exists and skips duplicate publication.
 
 ## Release checklist
 
@@ -84,7 +98,7 @@ Until the npm-side Trusted Publisher relationship is configured, the workflow ca
 7. Commit and push the release branch.
 8. Merge only after review/local validation is clean.
 9. Create/push the matching `vX.Y.Z` tag or run the publish workflow.
-10. Verify registry version and `latest` dist-tag.
+10. Verify registry version and dist-tags (`next` for prerelease, `latest` for stable).
 11. Install the published package on a clean environment before announcing it.
 
 ## One-command user install

package/docs/OPENCODE-COMPAT.md

@@ -1,6 +1,6 @@
 # OpenCode compatibility
 
-V11 ships one npm package for OpenCode 1.x and 2.x, while only enabling V2-native runtime features when V2 is detected.
+V13 ships one npm package for OpenCode 1.x and 2.x. CLI/state/verification features remain available on both lines, while V2-native fresh-session and parallel runtime features are enabled only when the required V2 capabilities are detected.
 
 ## Detection
 
@@ -30,7 +30,7 @@ UES installs:
 
 The V2 runtime plugin is not installed.
 
-Durable CLI state, task DAG, plan/integration gates and model-policy configuration remain available. V2-specific automatic fresh-session dispatch is unavailable.
+Durable CLI state, task DAG, plan/integration gates, Windows UTF text recovery and model-policy configuration remain available. `ues.dispatch_task` and `ues.dispatch_parallel` are unavailable because those tools live in the V2 router plugin.
 
 ## OpenCode 2.x
 
@@ -40,6 +40,8 @@ UES converts managed agent permission frontmatter to V2 ordered `permissions` an
 <global-config>/plugins/ues-router/
 ```
 
+V13 also installs the 11 UES slash-command templates inside the managed router as V2 **prompt aliases** instead of registering them as native global custom commands. Typing `/ues-run ...`, `/ues-fix ...`, and the other `/ues-*` aliases therefore travels through `session.prompt`; the router expands the same bundled command contract before routing skills. This is a compatibility workaround for V2 custom-command transport failures such as `UnsupportedContentType` from the `session.command` path. Re-syncing with `ocskill install` removes stale UES-managed native command files from older installs.
+
 The plugin provides:
 
 - prompt-admission skill routing
@@ -48,6 +50,7 @@ The plugin provides:
 - durable-state/task-graph/context-pack tools
 - `ues.dispatch_task` bounded fresh executor runtime
 - `ues.cancel_task` and `ues.recover_task` when session interruption is supported
+- `ues.dispatch_parallel` when the full fresh-dispatch surface is present; it runs independent approved tasks in isolated same-model sessions, verifies each task independently, and serializes integration
 
 `ues.dispatch_task` uses V2 session APIs to create a fresh session rooted at the selected execution directory, bind its session ID to the task lease, select `ues-executor`, optionally switch model tier, prompt one approved task, heartbeat while waiting, and interrupt on timeout. Concurrent writing tasks can be isolated in Git worktrees.
 
@@ -110,3 +113,10 @@ The managed V2 plugin probes for:
 - permission hooks
 
 `ues.capabilities` exposes the observed surface. Fresh dispatch fails closed when the minimum create/prompt/wait/interrupt/context/switch-agent surface is unavailable. Optional context/prompt/permission hooks degrade safely instead of preventing the plugin from loading.
+
+
+## V13 parallel compatibility
+
+`ues.dispatch_parallel` is capability-gated, not version-string-gated. It requires the complete fresh-dispatch surface reported by `ues.capabilities`: session create, prompt, wait, interrupt, context retrieval and agent switching. If any required API is missing, V13 fails closed and the durable CLI workflow remains usable in serial mode.
+
+OpenCode 1.x users can still use V13 CLI hardening, durable `.ues-work/<slug>/` state, receipts, task graphs and Windows text normalization. To use native multi-session parallel execution, use a runtime that exposes the V2 fresh-session APIs.

package/docs/V13-PARALLEL-WEAK-MODEL-RUNTIME.md

@@ -0,0 +1,75 @@
+# V13 Parallel Weak-Model Runtime
+
+Status: beta prerelease (`13.0.0-beta.1`).
+
+## Goal
+
+V13 reduces wall-clock time for large engineering work by letting multiple fresh sessions of the **same configured model** execute independent approved tasks concurrently without sharing mutable context.
+
+## Runtime contract
+
+- `ues.dispatch_parallel` defaults to one shared model for every worker and verifier.
+- The root must be a Git repository. A pre-existing dirty working tree is allowed: V13 snapshots that baseline into each sandbox and integrates only the task delta, so valid inherited/user changes are preserved.
+- Writers execute in isolated Git worktrees.
+- Resource leases serialize overlapping files, unknown scope and shared configuration surfaces.
+- The scheduler is event-driven: when one task is independently verified, transactionally integrated and completed, newly unblocked dependencies may start immediately.
+- Initial and downstream sandboxes inherit the current dirty root through an internal snapshot commit on the sandbox branch; the user's root branch is never auto-committed.
+- A fresh `ues-verifier` session using the same model must return PASS before integration.
+- Integration is serialized. If receipt/completion fails after patch application, V13 reverses that task patch before marking the run failed.
+- No parallel worker pushes, publishes or deploys.
+
+## Same-model execution
+
+One model is sufficient. Parallelism means multiple isolated sessions, not multiple model families:
+
+```text
+provider/weak-model
+  ├─ fresh session A
+  ├─ fresh session B
+  ├─ fresh session C
+  └─ fresh verifier sessions
+```
+
+If no explicit model is supplied, the configured executor model is shared. If no configured model is selected, all sessions keep the OpenCode default model.
+
+## Runtime compatibility
+
+V13 keeps CLI, durable state, receipts, task graphs and Windows text hardening available on OpenCode 1.x. Native `ues.dispatch_task` and `ues.dispatch_parallel` require the V2 router plugin plus the fresh-session capability surface. The router checks capabilities at runtime and fails closed if create/prompt/wait/interrupt/context/switch-agent are incomplete.
+
+When npm blocks lifecycle scripts (common with stricter npm 11+ `allowScripts` policy), install still leaves the CLI available; run `ocskill install` to perform the documented resource sync explicitly.
+
+## CLI hardening
+
+V13 parses `--help` before positional arguments, so commands such as these are safe:
+
+```cmd
+ocskill work init --help
+ocskill work status --help
+ocskill work gate-receipt --help
+```
+
+`ocskill work status .` now lists durable workspaces instead of treating `.` as a slug.
+
+For machine callers, append `--json` to receive structured errors.
+
+On Windows, prefer:
+
+```cmd
+ocskill diff . --out dirty.diff
+```
+
+This writes UTF-8 directly and avoids PowerShell 5 redirection producing UTF-16 text that generic readers may classify as binary. On OpenCode 1.x, where the V2 `ues.text_read` tool is unavailable, read known text safely without creating a converted copy:
+
+```cmd
+ocskill text-read .ues-work/<slug>/PLAN.json --json
+```
+
+Existing UTF-8/UTF-16 text can be normalized with:
+
+```cmd
+ocskill normalize-text dirty.diff
+```
+
+## Release evidence
+
+V13 remains beta until parallel execution demonstrates measurable wall-clock improvement without reducing correctness, and Windows/Linux CI proves help parsing, encoding, dirty-baseline worktree inheritance, rollback, verifier receipts and package installation.

package/global-config/AGENTS.md

@@ -34,8 +34,10 @@ Useful deterministic helpers include:
 
 - `ocskill inspect [dir]`
 - `ocskill impact <symbol-or-term> [dir]`
+- `ocskill repo-graph [dir] --compact` for an initial hotspot summary; request the full graph only when exact edge detail is needed
 - `ocskill aci search|refs|view|text ...`
 - `ocskill working-tree [dir]`
+- `ocskill text-read <file> --json` when OpenCode/generic readers classify known UTF text as binary
 - `ocskill verification-plan [dir]`
 - `ocskill context-pack <slug> <task> [dir]`
 - `ocskill work verify-command ... -- <command>`
@@ -111,6 +113,8 @@ Never claim a test, build, migration, deployment, push or release succeeded unle
 
 For interruption-prone or dependent multi-task work, use durable `.ues-work/<slug>/` state instead of relying on conversation memory.
 
+`.ues-work/<slug>/` is the only UES durable-state location. Never create or treat a top-level `ues-work/` directory (without the leading dot) as official UES state, even if an older/manual run left files there. On resume, prefer the initialized `.ues-work/<slug>/` item plus current Git evidence.
+
 The required sequence is:
 
 `SPEC -> PLAN -> plan check/receipt -> approved tasks -> fresh executor per task -> task verification receipts -> integration verification/receipt -> finalize`

package/global-config/commands/resume.md

@@ -7,10 +7,13 @@ Resume this UES work item: $ARGUMENTS
 
 Read the matching `.ues-work/<slug>/SPEC.md`, `PLAN.json`, `STATE.json`, `EVIDENCE.json`, task reports and current Git status. Run `ocskill work resume <slug> .` and revalidate assumptions that may have gone stale.
 
+Ignore a top-level `ues-work/` directory as official workflow state. Only `.ues-work/<slug>/` created/managed by `ocskill work` is canonical durable state.
+
 Trust durable task state and Git evidence over conversational recollection. Respect the machine gates:
 - if the plan is awaiting approval, run `ues-plan-checker` and record PASS with `ocskill work approve-plan`;
 - resume failed/pending work from the last verified boundary;
-- on OpenCode V2 prefer `ues.dispatch_task` for a fresh executor and configured model escalation;
+- on OpenCode V2, prefer `ues.dispatch_parallel` when two or more dependency-ready tasks have independent declared write/resource scopes; otherwise use `ues.dispatch_task` for a fresh executor. Keep one shared model for parallel worker/verifier sessions unless the user explicitly changes the design;
+- do not force-clean inherited user changes just to enable parallel resume; V13 snapshots an existing dirty Git baseline into isolated worktrees and integrates only each task delta;
 - do not repeat completed tasks unless fresh evidence invalidates them;
 - after all tasks complete, run `ues-integration-verifier`, record its verdict with `ocskill work verify-integration`, then finalize only after PASS and an unchanged workspace fingerprint.
 

package/global-config/commands/run.md

@@ -7,20 +7,22 @@ Run this task using the UES long-horizon workflow: $ARGUMENTS
 
 Treat this command as permission to create a repository-local, git-ignored `.ues-work/<slug>/` execution workspace for durable non-secret planning state.
 
+Never create or use `ues-work/` (without the leading dot) as durable UES state. If such a directory exists from an older/manual run, treat it as ordinary repository content unless the user explicitly asks to migrate it; official state must come from `ocskill work init` under `.ues-work/<slug>/`.
+
 Required workflow:
-1. Classify the request with `ocskill task-policy "$ARGUMENTS"`. Use the returned risk/mode/context guidance rather than assuming every non-trivial task needs the same workflow.
-2. Inspect repository instructions and deterministic evidence with `ocskill inspect`, `ocskill repo-graph`, and targeted impact searches.
+1. Classify the request with `ocskill task-policy "<concise task summary>"`. Do not duplicate the full user prompt into shell arguments; use the returned risk/mode/context guidance rather than assuming every non-trivial task needs the same workflow.
+2. Inspect repository instructions and deterministic evidence with `ocskill inspect`, `ocskill repo-graph . --compact`, and targeted impact searches. Expand to the full graph only when exact edge detail is needed.
 3. Create a concise SPEC with observable acceptance criteria.
 4. Initialize persistent state with `ocskill work init`.
 5. Produce a file-aware `PLAN.json` using the UES plan schema, then import it with `ocskill work plan`.
 6. Dispatch `ues-plan-checker` in fresh context. For long/high-risk work, bind the PASS to the current plan with a structured receipt, then approve it:
    `ocskill work gate-receipt <slug> plan . --verifier ues-plan-checker --evidence "<summary>" --out .ues-work/<slug>/reports/plan-receipt.json`
    followed by `ocskill work approve-plan <slug> . --evidence "<summary>" --receipt-file .ues-work/<slug>/reports/plan-receipt.json`.
-7. Use `ocskill task-graph` and execute only ready dependency-safe tasks. On OpenCode V2 prefer `ues.dispatch_task`: it starts the task, creates a fresh `ues-executor` session, applies configured attempt-based model escalation, waits for that executor, and returns its report. Inspect the diff and evidence, then record `ocskill work complete` or `ocskill work fail`.
-8. Independent tasks may run concurrently only when safe-wave analysis reports no write/read conflict. V8 can isolate concurrent writers in Git worktrees and integrate them with conflict detection; manual fallback is `ocskill sandbox create ...` followed by `ocskill sandbox integrate <worktree> .`. Never integrate over overlapping dirty root files.
-9. During long execution keep the task lease alive with `ocskill work heartbeat` (the V2 dispatcher does this automatically). On resume, `ocskill work recover` or `ocskill work resume` recovers expired leases instead of leaving tasks stuck in `running`.
-10. Run declared checks through `ocskill work verify-command <slug> <task> . --run-id <run-id> -- <command> [args...]`. For long/high-risk plans, a successful receipt for the active run is mandatory before `work complete`; narrative-only completion is rejected.
-11. On executor failure, diagnose from fresh evidence and retry in a fresh executor. Adaptive model policy may raise the model tier based on risk/complexity plus attempt count; do not escalate blindly.
+7. Use `ocskill task-graph` and execute only dependency-ready tasks. On OpenCode V2, when two or more independent tasks are ready, prefer `ues.dispatch_parallel`. V13 uses multiple fresh sessions of one shared model, not multiple model families. For a single task or a deliberately serial path, use `ues.dispatch_task`.
+8. `ues.dispatch_parallel` is event-driven rather than wave-barrier driven: as soon as a task is independently verified, transactionally integrated and durably completed, newly unblocked dependencies may start in the next free worker slot. Resource leases serialize overlapping writers, unknown scopes and shared configuration surfaces.
+9. Each parallel writer gets an isolated Git worktree. A pre-existing dirty root is treated as an inherited baseline, and downstream worktrees also inherit already integrated root changes through an internal sandbox snapshot; only task-local deltas are integrated and the user's root branch is not auto-committed. Integration is serialized and rolled back if post-integration verification/receipt/completion fails.
+10. For machine-checkable verification, add `verificationCommands` to the approved task, for example `{"command":"node","args":["--test","test/foo.test.mjs"]}`. V13 runs these exact commands after integration via `ocskill work verify-command`, records deterministic receipts, then also records the fresh independent verifier verdict. For long/high-risk plans, current-fingerprint receipt evidence remains mandatory.
+11. During long execution keep task leases alive (the V2 dispatcher does this automatically). On resume, `ocskill work recover` or `ocskill work resume` recovers expired leases instead of leaving tasks stuck in `running`. In parallel mode, keep one shared model for all worker/verifier sessions unless the user explicitly changes the run design.
 12. After all tasks complete, dispatch `ues-integration-verifier`. For PASS on long/high-risk work, create an integration receipt bound to the current workspace fingerprint:
    `ocskill work gate-receipt <slug> integration . --verifier ues-integration-verifier --verdict PASS --evidence "<summary>" --out .ues-work/<slug>/reports/integration-receipt.json`
    then record it with `ocskill work verify-integration <slug> . --verdict PASS --evidence "<summary>" --receipt-file .ues-work/<slug>/reports/integration-receipt.json`.

package/global-config/plugins/ues-router/capabilities.js

@@ -11,6 +11,7 @@ export function runtimeCapabilities(ctx) {
     sessionSwitchModel: typeof session.switchModel === "function",
     sessionHook: typeof session.hook === "function",
     permissionHook: typeof permission.hook === "function",
+    permissionRules: typeof permission.rules === "function",
   }
   capabilities.freshDispatch =
     capabilities.sessionCreate &&

package/global-config/plugins/ues-router/command-runtime.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+export const UES_PROMPT_ALIASES = Object.freeze([
+  "ues-audit",
+  "ues-critique",
+  "ues-debug",
+  "ues-feature",
+  "ues-fix",
+  "ues-plan",
+  "ues-research",
+  "ues-resume",
+  "ues-review",
+  "ues-run",
+  "ues-verify",
+])
+
+const ALIAS_SET = new Set(UES_PROMPT_ALIASES)
+
+export function normalizeUesPromptPaste(text) {
+  let value = String(text || "")
+    .replace(/^\uFEFF/, "")
+    .replace(/^[\u200B-\u200D]+/, "")
+
+  const trimmed = value.trim()
+  const fenced = trimmed.match(/^\`\`\`(?:text|txt|md|markdown|prompt|plaintext)?[ \t]*\r?\n([\s\S]*?)\r?\n\`\`\`\s*$/i)
+  if (fenced) value = fenced[1]
+
+  return value
+}
+
+export function policyPromptForCli(text, maxChars = 12_000) {
+  const raw = normalizeUesPromptPaste(text).trim()
+  const limit = Math.max(2_000, Number(maxChars) || 12_000)
+  if (raw.length <= limit) {
+    return { text: raw, truncated: false, originalChars: raw.length, cliChars: raw.length }
+  }
+
+  const marker = "\n\n[UES_POLICY_INPUT_TRUNCATED_FOR_CLI]\n\n"
+  const usable = Math.max(1, limit - marker.length)
+  const headChars = Math.floor(usable * 0.72)
+  const tailChars = usable - headChars
+  const bounded = raw.slice(0, headChars) + marker + raw.slice(-tailChars)
+  return {
+    text: bounded,
+    truncated: true,
+    originalChars: raw.length,
+    cliChars: bounded.length,
+  }
+}
+
+function parseFrontmatter(source) {
+  const text = String(source || "")
+  if (!text.startsWith("---")) return { metadata: {}, body: text }
+  const end = text.indexOf("\n---", 3)
+  if (end < 0) return { metadata: {}, body: text }
+
+  const block = text.slice(3, end).trim()
+  const metadata = {}
+  for (const line of block.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!match) continue
+    metadata[match[1]] = match[2].trim()
+  }
+
+  return {
+    metadata,
+    body: text.slice(end + 4).replace(/^\r?\n/, ""),
+  }
+}
+
+function splitArgs(input) {
+  const value = String(input || "")
+  const matches = value.match(/"[^"]*"|'[^']*'|\S+/g) || []
+  return matches.map((item) => item.replace(/^(['"])([\s\S]*)\1$/, "$2"))
+}
+
+export function expandUesPromptAlias(text, templateDir) {
+  const raw = normalizeUesPromptPaste(text)
+  const match = raw.match(/^\s*\/(ues-[a-z0-9]+(?:-[a-z0-9]+)*)(?:\s+([\s\S]*?))?\s*$/i)
+  if (!match) return null
+
+  const alias = match[1].toLowerCase()
+  if (!ALIAS_SET.has(alias)) return null
+
+  const args = String(match[2] || "").trim()
+  const sourceName = alias.slice("ues-".length) + ".md"
+  const file = path.join(templateDir, sourceName)
+  if (!existsSync(file)) return null
+
+  const { metadata, body } = parseFrontmatter(readFileSync(file, "utf8"))
+  const positional = splitArgs(args)
+  let expanded = body.replaceAll("$ARGUMENTS", args)
+  expanded = expanded.replace(/\$(\d+)/g, (_, value) => positional[Number(value) - 1] || "")
+
+  const agent = metadata.agent || null
+  const prelude = [
+    `UES V2 prompt alias: /${alias}. Preserve the command contract below while using the normal session.prompt path.`,
+    agent && agent !== "build"
+      ? `Preferred specialist: ${agent}. When fresh subagent dispatch is available, delegate to that specialist and preserve the command's read/write restrictions.`
+      : null,
+  ].filter(Boolean).join("\n")
+
+  return {
+    alias,
+    arguments: args,
+    agent,
+    sourceName,
+    text: `${prelude}\n\n${expanded.trim()}`,
+  }
+}