opencode-agent-skill 7.7.0

package/docs/DETERMINISTIC-TOOLS.md

@@ -0,0 +1,88 @@
+# Deterministic evidence and execution tools
+
+UES 6 uses dependency-light Node helpers for work that should not rely on a model guessing or remembering it.
+
+## Repository evidence
+
+```cmd
+ocskill inspect .
+ocskill detect-stack .
+ocskill detect-tests .
+ocskill impact calculateOrderTotal .
+ocskill evidence .
+ocskill working-tree .
+```
+
+These identify stack/package manager, project-native checks, bounded impact hits and Git state.
+
+## Repository graph
+
+```cmd
+ocskill repo-graph .
+```
+
+Builds a bounded import graph, local edges, external import frequencies and coupling hotspots. It is not a full language server/call graph.
+
+## Review scope
+
+```cmd
+ocskill review-scope main .
+```
+
+Enumerates changed files and deterministic risk hints for persistence/schema, auth/security, payments, public interfaces, dependencies and delivery/infrastructure.
+
+`coverageRequired` lets a reviewer account for every changed file instead of relying on memory.
+
+## Verification plan
+
+```cmd
+ocskill verification-plan .
+```
+
+Combines project-native commands, working-tree evidence and changed-file risk into recommended checks plus risk-specific acceptance prompts.
+
+## Task graph
+
+```cmd
+ocskill task-graph PLAN.json
+```
+
+Validates plan shape/dependencies/cycles and computes topological and safe waves. Same-wave tasks with overlapping/unknown declared files are serialized.
+
+## Durable work state
+
+```cmd
+ocskill work init <slug> . --goal "..."
+ocskill work plan <slug> PLAN.json .
+ocskill work approve-plan <slug> . --evidence "..."
+ocskill work start <slug> T1 .
+ocskill work complete <slug> T1 . --evidence "..."
+ocskill work fail <slug> T1 . --reason "..."
+ocskill work verify-integration <slug> . --verdict PASS --evidence "..."
+ocskill work finalize <slug> . --evidence "..."
+ocskill work resume <slug> .
+```
+
+State/evidence writes use a per-item lock and atomic replacement.
+
+## Context pack
+
+```cmd
+ocskill context-pack <slug> <task> .
+```
+
+Returns only the task, bounded spec, dependency reports, decisions, blockers and current task state required for a fresh executor.
+
+## Runtime dispatch on OpenCode V2
+
+The managed plugin exposes `ues.dispatch_task`, which combines `work start`, context pack, model policy and a fresh OpenCode executor session.
+
+## Constraints
+
+These helpers:
+
+- do not replace reading exact affected code
+- do not pretend text/import scans are complete semantic analysis
+- do not auto-merge/push/publish/deploy
+- preserve unrelated user work
+- use JSON outputs where machine consumption matters

package/docs/ENGINEERING-DESIGN.md

@@ -0,0 +1,176 @@
+# UES engineering design
+
+UES 6 evolves the project from an engineering workflow harness into a **long-horizon execution engine** designed to reduce context pressure on coding models.
+
+The selected model remains the selected model. UES improves orchestration, evidence, task boundaries, state persistence and verification; it does not claim model equivalence.
+
+## Core design
+
+### Thin orchestrator, durable artifacts, fresh workers
+
+For long work:
+
+```text
+main/orchestrator
+  ↓
+SPEC + PLAN + STATE
+  ↓
+fresh executor per approved task
+  ↓
+task report + evidence
+  ↓
+integration verifier
+```
+
+Conversation history is not the source of truth. Durable artifacts are.
+
+### Deterministic facts before probabilistic reasoning
+
+UES moves cheap/reliable work into code:
+
+- stack/test-command discovery
+- repository import graph
+- bounded impact search
+- Git state
+- changed-file review coverage
+- risk hints
+- verification recommendations
+- task dependency validation
+- safe-wave scheduling
+- persistent work state
+- completion gates
+
+Models still reason about semantics and read affected code.
+
+### Progressive disclosure
+
+The catalog remains 39 skills. UES prefers a small active skill set and loads deeper references only when needed.
+
+### Hard gates, not reminders
+
+Three V6 gates are machine-enforced:
+
+1. imported plans are not executable until plan-checker PASS is recorded;
+2. durable mutations are serialized with a per-work-item lock and atomic replacement;
+3. finalization requires integration PASS and an unchanged workspace fingerprint.
+
+These checks do not depend on a model remembering an instruction.
+
+## Long-task state model
+
+```text
+.ues-work/<slug>/
+  SPEC.md
+  PLAN.json
+  STATE.json
+  EVIDENCE.json
+  tasks/
+  reports/
+```
+
+The state contains operational facts only: task status, attempts, decisions, blockers, approvals and evidence. It is not chain-of-thought.
+
+`PLAN.json` is validated for task IDs, dependencies, cycles, acceptance criteria, verification and risk. Safe waves serialize overlapping or unknown declared file scopes.
+
+## Fresh-context execution
+
+On OpenCode V2, the managed plugin exposes `ues.dispatch_task`.
+
+It:
+
+1. calls the state engine to start one ready task;
+2. obtains the bounded context pack;
+3. resolves the configured model tier for the executor attempt;
+4. creates a fresh OpenCode session;
+5. switches to `ues-executor`;
+6. optionally switches to the configured model;
+7. prompts exactly the approved task;
+8. waits and returns child-session context.
+
+The parent is still responsible for inspecting the child diff and recording completion/failure evidence.
+
+## Model escalation
+
+Roles map to `light`, `standard`, or `heavy`. Attempt number can raise a role one tier up to the configured cap. Model IDs are always user-configured; UES never invents provider/model identifiers.
+
+Escalation follows evidence, not panic:
+
+```text
+attempt 1 fails
+→ diagnose
+→ fresh retry
+→ stronger tier if configured
+→ repeated causal failure
+→ re-plan / architecture review
+```
+
+## OpenCode runtime
+
+### V1
+
+Uses compatible file-based skills, commands and agents. V2-only plugin behavior is not installed.
+
+### V2
+
+The managed plugin uses current V2 domains for:
+
+- prompt admission skill routing
+- model-context guardrails
+- permission evaluation
+- custom tools
+- fresh session creation
+- agent/model switching
+- session waiting
+
+Only UES-managed resources are rewritten/removed.
+
+## Evaluation architecture
+
+UES separates:
+
+1. **static skill contract** — 34 scenarios covering the 39-skill catalog;
+2. **V2 router precision matrix** — 120 required-route/negative-guard cases;
+3. **standard live benchmark** — 20 executable hidden-graded tasks;
+4. **long-horizon benchmark** — 5 tasks, including one 15-source-file integration workload.
+
+For long-suite UES mode, final behavior alone is insufficient. A PASS also requires a completed durable work item with plan approval, at least two tasks, attempted/completed task records, integration PASS and finalization evidence.
+
+This prevents a strong model from bypassing the architecture and still being counted as proof that the long-horizon engine worked.
+
+## Package lifecycle and release safety
+
+npm owns package installation. UES owns only its marked/namespaced OpenCode resources.
+
+CI validates syntax, resource contracts, routing, hidden graders, unit tests, package contents and packed global installation. Update logic resolves npm's explicit `latest` tag and refuses accidental downgrade.
+
+## Deliberate limits
+
+UES deliberately avoids:
+
+- hundreds of agents/tools
+- loading every skill
+- treating keyword routing as truth
+- hidden chain-of-thought storage
+- automatic merge/push/publish/deploy
+- claiming success without fresh evidence
+- claiming that one benchmark proves general model equivalence
+
+The target is a small number of strong control loops: correct context, small tasks, durable state, deterministic checks and independent verification.
+
+
+## V7.7 intelligence runtime additions
+
+V7 adds four control loops around the V6 state machine:
+
+1. **runtime reliability** — task attempts carry run fencing, heartbeats and leases; expired `running` state can be recovered after process/session interruption;
+2. **evidence binding** — verification commands can emit structured receipts containing exit status, output digests and before/after workspace fingerprints;
+3. **context intelligence** — fresh executors receive a bounded manifest of declared files, import neighbors, likely tests, instruction/manifests and accepted learnings;
+4. **adaptive policy + learning** — deterministic task risk/complexity influences workflow/model tier and eval traces can produce explicit learning proposals.
+
+Parallelism is now read/write aware. Read/read overlap can share a wave; writers serialize against readers/writers unless the parent intentionally moves them into isolated Git worktree sandboxes.
+
+The V2 plugin probes actual session capabilities before dispatch rather than treating a major version number as sufficient proof that every runtime API exists.
+
+Hermes is deliberately adapter-only. UES can detect Hermes and generate a bounded task handoff, but does not embed Hermes' runtime, memory, scheduler or gateway into core.
+
+The local Control Center is observational. It reads durable artifacts and eval summaries; it does not bypass plan, verification, safety or finalization gates.

package/docs/EVALS.md

@@ -0,0 +1,136 @@
+# UES evaluations
+
+UES 6 separates catalog correctness, routing precision, benchmark integrity, final behavior and long-horizon orchestration.
+
+## 1. Static skill-routing contract
+
+`evals/routing.json` keeps 34 representative scenarios and covers all installed skills.
+
+```bash
+npm run evals
+# or
+ocskill eval
+```
+
+This checks catalog consistency, not model behavior.
+
+## 2. V2 router trigger matrix
+
+`evals/router-triggers.json` contains **120 cases** spanning positive routes, negative guards and wording variations.
+
+```bash
+npm run evals:router
+```
+
+The evaluator reports required-route recall and negative-guard success. It exists to catch deterministic router drift separately from LLM behavior.
+
+## 3. Standard live-suite integrity
+
+The standard live suite contains **20 executable hidden-graded tasks**.
+
+```bash
+npm run evals:live:validate
+```
+
+Each grader must reject its intentionally broken fixture with an assertion failure. A grader that already passes or fails for unrelated setup reasons invalidates the suite.
+
+## 4. Long-horizon suite integrity
+
+The long suite contains **5 tasks**. Four exercise coordinated 3–4 file domains; one combines all four domains into a **15-source-file** integration workload.
+
+```bash
+npm run evals:long:validate
+```
+
+The same broken-fixture rule applies.
+
+## 5. Live baseline vs UES
+
+```bash
+ocskill eval-live --model provider/model --trials 3
+ocskill eval-live --suite long --model provider/model --trials 3
+```
+
+Each task runs as:
+
+- **baseline** — isolated empty OpenCode config
+- **ues** — same model/task with repository UES resources installed
+
+Use multiple trials because coding-agent behavior is nondeterministic.
+
+### Long-suite orchestration gate
+
+For `--suite long`, a UES-mode result is PASS only if:
+
+1. OpenCode agent process exits successfully;
+2. hidden behavior grader passes;
+3. at least one `.ues-work/<slug>/` item is valid;
+4. the plan contains at least two tasks;
+5. plan approval status is `passed`;
+6. every planned task has an attempt and ends `completed`;
+7. integration verification is `PASS`;
+8. integration and finalization evidence exist;
+9. work item status is `completed`.
+
+Therefore a model that directly patches all files in its main context but bypasses the long-task engine is not counted as a successful UES long-horizon run.
+
+## Authentication isolation
+
+Default mode:
+
+```text
+--auth env-only
+```
+
+The harness isolates HOME, USERPROFILE, XDG config/data/cache/state and `OPENCODE_CONFIG_DIR`.
+
+If provider auth was established through OpenCode itself:
+
+```bash
+ocskill eval-live --model provider/model --auth current --trials 3
+```
+
+`current` copies only the current auth file, not the user's global UES configuration.
+
+## Telemetry
+
+Results may include:
+
+- pass/fail
+- process exit status
+- duration
+- changed files
+- bounded stdout/stderr
+- best-effort tool calls
+- loaded skills/subagent targets
+- token/cost data when exposed
+- long-suite orchestration inspection
+
+No hidden chain-of-thought is collected.
+
+## Report aggregation
+
+```bash
+ocskill eval-report .ues-evals
+```
+
+Compare the same model, variant, prompt, fixture, grader and environment. Report multiple trials.
+
+A benchmark result is evidence only for the measured workload. UES does not claim to turn one base model into another.
+
+
+## V7 live-run observability and evidence gate
+
+Live runs accept:
+
+```bash
+--heartbeat-ms 30000
+--idle-timeout-ms 300000
+--timeout-ms 900000
+```
+
+The harness prints a start line and heartbeat for an active model run. Hard timeout and idle timeout are recorded separately. Ctrl+C aborts the active OpenCode process tree and sets exit code 130 after the current result is recorded.
+
+V7 long-suite UES mode additionally requires **receipt-backed verification for every planned task**. A narrative completion entry is still preserved for backwards compatibility, but it does not satisfy the V7 long benchmark unless at least one successful structured verification receipt is bound to that task.
+
+This intentionally raises the benchmark bar: final code correctness + durable orchestration + machine-observable verification are all required.

package/docs/NPM-PUBLISH.md

@@ -0,0 +1,102 @@
+# Publishing to npm
+
+The package is published as:
+
+```text
+opencode-agent-skill
+```
+
+## Release prerequisites
+
+1. The npm account must have publish rights to the unscoped `opencode-agent-skill` package name.
+2. `package.json` and `package-lock.json` versions must match.
+3. `CHANGELOG.md` must contain the release.
+4. Run the complete local validation:
+
+```cmd
+npm run ci
+```
+
+V7.7 CI includes syntax validation, resource validation, static skill routing, the 120-case V2 router matrix, standard and long hidden-grader integrity checks, unit/integration tests, package dry-run, and an isolated packed global-install smoke.
+
+## Manual release-like test
+
+Do not use `npm install -g .` as a release simulation because npm may create a symlink/junction back to the checkout.
+
+Use:
+
+```cmd
+npm pack
+npm install -g .\opencode-agent-skill-7.7.0.tgz --allow-scripts=opencode-agent-skill
+ocskill status
+ocskill doctor
+```
+
+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
+
+```cmd
+npm login
+npm whoami
+npm run ci
+npm publish --access public
+```
+
+After publication verify:
+
+```cmd
+npm view opencode-agent-skill versions --json
+npm view opencode-agent-skill@7.7.0 version
+npm dist-tag ls opencode-agent-skill
+```
+
+The expected release tag is:
+
+```text
+latest: 7.7.0
+```
+
+## GitHub Actions publishing
+
+The repository's publish workflow is release-ready for token-based publishing and provenance. It runs the same package validation before `npm publish`.
+
+For stronger long-term supply-chain security, configure npm Trusted Publishing for:
+
+```text
+GitHub owner: laivannha0202
+Repository: opencode-agent-skill-
+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 that npm-side setup is complete, keep a valid publish credential configured as `NPM_TOKEN`.
+
+## Release checklist
+
+1. Confirm version/changelog/package-lock consistency.
+2. Run `npm run ci` locally on Windows and at least one Unix-like environment when practical.
+3. Run `npm pack` and inspect the tarball contents.
+4. Verify packed install/state/resource counts.
+5. When installer compatibility changed, exercise both forced V1 and V2 paths through tests.
+6. When updater behavior changed, test explicit latest-tag resolution, equal-version behavior, and downgrade refusal.
+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.
+11. Install the published package on a clean environment before announcing it.
+
+## One-command user install
+
+After publication:
+
+```cmd
+npm install -g opencode-agent-skill
+```
+
+If lifecycle execution is blocked by local npm policy:
+
+```cmd
+ocskill install
+```

package/docs/OPENCODE-COMPAT.md

@@ -0,0 +1,109 @@
+# OpenCode compatibility
+
+UES 6 ships one npm package for OpenCode 1.x and 2.x, while only enabling V2-native runtime features when V2 is detected.
+
+## Detection
+
+During resource sync, UES reads:
+
+```text
+opencode --version
+```
+
+Tests may override with:
+
+```text
+UES_OPENCODE_MAJOR=1
+UES_OPENCODE_MAJOR=2
+```
+
+The detected major is recorded in the managed state.
+
+## OpenCode 1.x
+
+UES installs:
+
+- 39 namespaced skills
+- 11 namespaced commands
+- 10 namespaced subagents using compatible V1 `permission` frontmatter
+- managed global `AGENTS.md` block
+
+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.
+
+## OpenCode 2.x
+
+UES converts managed agent permission frontmatter to V2 ordered `permissions` and installs:
+
+```text
+<global-config>/plugins/ues-router/
+```
+
+The plugin provides:
+
+- prompt-admission skill routing
+- long-task context guardrails
+- permission safety evaluation
+- read-only durable-state/task-graph/context-pack tools
+- `ues.dispatch_task` fresh executor runtime
+
+`ues.dispatch_task` uses V2 session APIs to create a fresh session, select `ues-executor`, optionally switch to the configured model tier, prompt one approved task and wait for completion.
+
+## Router control
+
+```cmd
+ocskill router status
+ocskill router on
+ocskill router on --max 3
+ocskill router off
+```
+
+Default maximum is 4 selected skills; supported range is 1–6.
+
+## Model routing
+
+```cmd
+ocskill models status
+ocskill models on
+ocskill models set standard provider/model
+ocskill models set heavy provider/strong-model
+```
+
+Re-run `ocskill install` after changing static managed-agent model frontmatter. Runtime `ues.dispatch_task` also reads the current model policy for attempt-based executor escalation.
+
+## Upgrading OpenCode
+
+After moving between V1/V2 lines:
+
+```cmd
+ocskill install
+ocskill status
+```
+
+Only UES-managed resources are rewritten/removed. Unrelated user plugins/resources are preserved.
+
+## Primary references
+
+- https://opencode.ai/v2/docs/build/plugins
+- https://opencode.ai/v2/docs/build/plugins/migrate-v1
+- https://opencode.ai/v2/docs/permissions
+- https://opencode.ai/v2/docs/plugins
+- https://opencode.ai/v2/docs/skills
+
+
+## V7 capability probing
+
+Version detection remains useful for install-time compatibility, but V7 runtime dispatch does not assume that a major version proves the availability of every session API.
+
+The managed V2 plugin probes for:
+
+- session creation
+- prompting
+- waiting
+- context retrieval
+- agent switching
+- model switching
+- session hooks
+
+`ues.capabilities` exposes the observed surface. `ues.dispatch_task` fails closed when the minimum fresh-dispatch capability set is unavailable instead of attempting a partially supported execution path.

package/docs/RESEARCH-SOURCES.md

@@ -0,0 +1,37 @@
+# Research sources
+
+UES is informed by public engineering-agent patterns and current primary platform documentation.
+
+## Engineering-agent and skill-system references
+
+- Alibaba OpenCodeReview: https://github.com/alibaba/open-code-review
+- Open GSD Core: https://github.com/open-gsd/gsd-core
+- Superpowers: https://github.com/obra/superpowers
+- Agent Skills open specification: https://github.com/agentskills/agentskills
+- Anthropic Skills: https://github.com/anthropics/skills
+- OpenAI Agents SDK: https://github.com/openai/openai-agents-python
+- NVIDIA Skills: https://github.com/NVIDIA/skills
+- Ruflo / Claude Flow: https://github.com/ruvnet/ruflo
+
+## OpenCode references
+
+V1/current installed-system references:
+- Skills: https://opencode.ai/docs/skills
+- Agents: https://opencode.ai/docs/agents
+- Commands: https://opencode.ai/docs/commands
+
+OpenCode V2 compatibility/runtime references:
+- Migration from V1: https://opencode.ai/v2/docs/migrate-v1
+- Agent permissions: https://opencode.ai/v2/docs/permissions
+- Agents: https://opencode.ai/v2/docs/agents
+- Skills: https://opencode.ai/v2/docs/skills
+- Plugin discovery/configuration: https://opencode.ai/v2/docs/plugins
+- Plugin API and prompt hooks: https://opencode.ai/v2/docs/build/plugins
+- V1 plugin migration: https://opencode.ai/v2/docs/build/plugins/migrate-v1
+
+## npm release references
+
+- Trusted Publishing: https://docs.npmjs.com/trusted-publishers/
+- Provenance: https://docs.npmjs.com/generating-provenance-statements/
+
+The project does not vendor or copy these projects. External documentation is used to verify platform behavior and inform UES's own implementation.