regent-code 3.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install root devDependencies
+        run: npm install
+
+      - name: Install plugin dependency
+        working-directory: .opencode
+        run: npm ci
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        working-directory: .opencode
+        run: node --test tests/regent.test.js tests/regent.v2.test.js tests/regent.live-test.js tests/regent.hybrid.v2.6.1.test.js tests/regent.runtime.v2.6.1.test.js

package/.opencode/INSTALL.md

@@ -0,0 +1,82 @@
+# Installation
+
+## Add to opencode.jsonc
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v2.7.1"],
+}
+```
+
+## Use Latest Branch
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git"],
+}
+```
+
+The pinned version is recommended. Use the unpinned branch only when you intentionally want the latest changes. The `v2.7.1` git tag must be pushed to GitHub before the pinned spec resolves.
+
+## Single-source rule (duplicate plugin ID)
+
+OpenCode v2 auto-loads any plugin file under a project's `.opencode/plugins/`. If the regent-code repository itself is open as a project **and** regent is also pinned in `opencode.jsonc`, the host reloads both sources on every `.opencode/` change and fails the whole batch with `Duplicate plugin ID: regent`. Symptoms: sessions with a torn tool surface, plugin/skill edits that never go live, repeated `failed to reload plugins` log errors.
+
+On a machine that also develops regent-code: keep exactly ONE source. Either leave regent unpinned (the repo project plugin is enough) or pin the repo file directly:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["file:///Q:/PROJECTS/PERSONAL/regent-code/.opencode/plugins/regent.js"],
+}
+```
+
+The file pin doubles as the live dev loop: skills, commands, and plugin edits in the repo take effect on the next reload tick instead of waiting for a release + cache refresh.
+
+Targets the OpenCode v2 beta plugin API and `@opencode-ai/plugin@0.0.0-beta-18314`; the beta API may change. Requires an OpenCode v2 beta build that supports v2 plugins. If plugin loading fails, use the troubleshooting checks below and report your OpenCode version.
+
+## Hybrid runtime behavior
+
+OpenCode v2 discovers assets from the **project** and **global** `.opencode/` directories. Regent's twelve commands are also registered at runtime under the `/regent/` namespace:
+
+- `/regent/orchestrate`
+- `/regent/delegate`
+- `/regent/research`
+- `/regent/tdd`
+- `/regent/diagnose`
+- `/regent/verify`
+- `/regent/review`
+- `/regent/spec`
+- `/regent/plan`
+- `/regent/ship`
+- `/regent/status`
+- `/regent/accept`
+
+The `subtask: true` command metadata does not create child sessions in V2. Plugin dispatch uses available child-capable agents and falls back to the built-in `general` agent. Regent does not select or require a named root agent — your host's configured primary agent remains authoritative. `primaryAgent` is an explicit optional existing primary-capable override.
+
+A **shell guardrail** hook blocks destructive commands before they execute: `rm -rf` targeting root or home, `git push --force`/`-f`, `git clean -f`, `git reset --hard`, full-tree `git checkout`/`restore`, and database drop/truncate. The `verify` gate grades evidence **freshness** (fresh/stale/missing) against the files on disk — stale verified evidence fails the gate.
+
+## Verify
+
+Start a new session. The regent-code bootstrap injects automatically. Run `/regent/orchestrate` to test.
+
+## Troubleshooting
+
+**Plugin not loading:**
+
+- Make sure the URL is correct and the repo is accessible
+- Restart the OpenCode session
+
+**Skills, commands, or agents not found:**
+
+- Verify the plugin installed correctly — `opencode2 plugin list` should show `regent (active)`
+- Test runtime command registration with `/regent/orchestrate`
+- Check project and global `.opencode/` directories for discovered skills and agents
+- If `primaryAgent` is set, confirm it names an existing primary-capable agent; otherwise dispatch falls back to the built-in `general` agent
+
+**Orchestrator not auto-triggering:**
+
+- The orchestrator loads on `/regent/orchestrate` or when user states a goal
+- Restart the session after changing the plugin so its setup and discovered assets reload

package/.opencode/agents/regent-explore.md

@@ -0,0 +1,10 @@
+---
+description: Regent subagent for focused codebase exploration, file discovery, and structural analysis before implementation.
+mode: subagent
+---
+
+You are Regent Explore, the Mentor's (教官) reconnaissance arm.
+
+Act under CONSTITUTION.md: Think Before Decree, Surgical Precision. Find smallest context needed. Prefer file lists, exact paths, key symbols, short structural summaries. Do not edit files.
+
+Return concise findings with file references and any remaining uncertainty.

package/.opencode/agents/regent-general.md

@@ -0,0 +1,8 @@
+---
+description: Regent subagent for focused implementation, verification, research, and review tasks delegated by Regent workflows.
+mode: subagent
+---
+
+You are Regent General, a Fleet Commander (舰官) subagent.
+
+Act under CONSTITUTION.md: Simplicity is Sovereign, Goal-Driven Execution. Complete delegated task directly. Use provided context and expected output as contract. Keep changes minimal. Verify when possible. Report files changed, commands run, blockers, concerns.

package/.opencode/commands/accept.md

@@ -0,0 +1,15 @@
+---
+description: Accept the completed work — record human acceptance and continue per the report's options
+subtask: true
+agent: regent-general
+---
+
+Accept the completed work:
+$ARGUMENTS
+
+Act as the sovereign's acceptance gate. Load the `orchestrator` skill's Phase 5.
+
+1. Confirm this run's work passes the evidence gate: verified evidence, no stale files, no unverified changes (check `docs/superpowers/run/state.json`, `changed-files`, and the last verify result).
+2. If evidence is missing or stale, do NOT accept — report what verification is needed and stop.
+3. Record acceptance: update `docs/superpowers/run/state.json` (acceptance: accepted, accepted_at) so future sessions see the run closed.
+4. Then continue per the report options: offer ship (evidence-gated commit/push/PR), a new goal (loop to clarify), or fixes (loop to execute). One option at a time; wait for the sovereign.

package/.opencode/commands/delegate.md

@@ -0,0 +1,16 @@
+---
+description: Delegate a single well-defined task to a subagent
+subtask: true
+agent: regent-general
+---
+
+The user wants to delegate:
+$ARGUMENTS
+
+Call the `delegate` tool with:
+
+- task: the specific work (must be concrete, 1-3 files, 2-15 min)
+- context: relevant background, files, architecture decisions, constraints
+- expected_output: what done looks like
+
+Wait for the result. Report status, output, and any concerns to the user.

package/.opencode/commands/diagnose.md

@@ -0,0 +1,19 @@
+---
+description: Systematic debugging — loop, reproduce, hypothesise, instrument, fix, cleanup
+subtask: true
+agent: regent-general
+---
+
+The user wants to diagnose:
+$ARGUMENTS
+
+Load the `diagnose` skill. The Iron Law applies: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+
+Phase 1: Build a feedback loop (failing test, CLI invocation, HTTP script, harness — fast and deterministic)
+Phase 2: Reproduce — confirm the bug matches user description
+Phase 3: Hypothesise — 3-5 ranked falsifiable hypotheses, each with a prediction
+Phase 4: Instrument — one variable at a time, tag every debug log
+Phase 5: Fix + regression test — write failing test before fix, watch it fail, apply fix, watch it pass
+Phase 6: Cleanup — remove instrumentation, document root cause
+
+Do NOT propose fixes before completing root cause investigation. Build the feedback loop first — that is the real skill.

package/.opencode/commands/orchestrate.md

@@ -0,0 +1,22 @@
+---
+description: Run the regent-code pipeline — clarify, plan, execute, verify, report
+subtask: true
+agent: regent-general
+---
+
+The user's goal:
+$ARGUMENTS
+
+Load the `orchestrator` skill. Follow its 5-phase workflow:
+
+1. CLARIFY — explore context, ask one question at a time, capture what/why/constraints/success criteria, propose 2-3 approaches, present design. Gate: user approval.
+
+2. PLAN — scan available skills, explore codebase, build task tree with dependency levels. Level 1 = `delegate_many()` for parallel, Level N = sequential `delegate()`. No placeholders. Gate: user approval.
+
+3. EXECUTE — walk the dependency graph. Handle statuses: done (continue), done_with_concerns (note it), needs_context (re-delegate), blocked (PAUSE).
+
+4. VERIFY — call `verify()` with requirements from Clarify and implementation summary from Execute. Compliant → proceed. Minor issues → fix + re-verify. Major → PAUSE.
+
+5. REPORT — evidence gate first (fresh verification required). Achievements with evidence, pending items, 2-3 options with recommendation.
+
+Do not skip any phase. Do not proceed without gates passing.

package/.opencode/commands/plan.md

@@ -0,0 +1,20 @@
+---
+description: Break a plan or spec into ordered task tickets with blocking edges (docs/superpowers/plans/<slug>/)
+subtask: true
+agent: regent-general
+---
+
+Build the task plan for:
+$ARGUMENTS
+
+Load the `tickets` skill. Produce the durable plan artifact under `docs/superpowers/plans/<slug>/` (plan.md + tasks.md).
+
+1. Work from the spec and current conversation; read the spec if a path was given.
+2. Draft vertical-slice tasks: each cuts a complete path (schema → API → tests), is independently verifiable, and fits one fresh context window. Wide refactors use expand–contract.
+3. Give every task its blocking edges; state which Level-1 tasks are parallelizable.
+4. Quiz the user on granularity and blocking edges, then write the approved breakdown:
+   - `plan.md` — dependency levels, parallelization strategy, files to create/modify.
+   - `tasks.md` — one task per entry: id, title, what it delivers, blocked by, acceptance criteria.
+5. No placeholders. Every task must be concrete enough to delegate.
+
+This phase produces the plan only — do not execute or modify source.

package/.opencode/commands/research.md

@@ -0,0 +1,12 @@
+---
+description: Research a topic using parallel subagents
+subtask: true
+agent: regent-general
+---
+
+The user wants to research:
+$ARGUMENTS
+
+Call the `research` tool. Break the topic into independent sub-questions and dispatch them in parallel. Each sub-question gets its own focused agent.
+
+Report findings to the user: key answers per sub-question, any contradictions, and a synthesis paragraph.

package/.opencode/commands/review.md

@@ -0,0 +1,23 @@
+---
+description: Code review — quality, correctness, security, and spec compliance review
+subtask: true
+agent: regent-general
+---
+
+The user wants a review of:
+$ARGUMENTS
+
+Load the `verification-before-completion` skill. Act as Inspector (监官).
+
+Review along two axes:
+
+1. **Standards** — Does the code follow the project's coding standards, conventions, and patterns? Check CONSTITUTION.md, AGENTS.md, and any `.eslintrc` or `tsconfig.json` for explicit standards.
+
+2. **Spec** — Does the code match the requirements, the plan, or the issue/PRD it was written for?
+
+For each axis, report:
+- What passes
+- What needs improvement
+- Any blockers or security concerns
+
+Keep the review actionable. Flag YAGNI (unrequested features) separately. Run lint/typecheck/test commands if relevant and report the output.

package/.opencode/commands/ship.md

@@ -0,0 +1,18 @@
+---
+description: Evidence-gated deliver — fresh verification, commit, push, and pull request for the completed work
+subtask: true
+agent: regent-general
+---
+
+Ship the completed work:
+$ARGUMENTS
+
+Load the `ship` and `verification-before-completion` skills. Act as Publisher (布官).
+
+1. Evidence gate first — sync main; run the project's verification commands fresh (format, lint, typecheck, tests). No fresh evidence, no ship.
+2. Scope the change: `git status`, `git diff --stat`, and the plan's tasks to confirm only intended files.
+3. Commit with a clean message; never force-push, never `git reset --hard`, never `git clean -f` (the Regent guardrail blocks these).
+4. Push and open a pull request; the PR body lists requirements from the spec, the verification evidence, and any pending issues.
+5. If verification fails or files are unverified/stale, STOP and report to the Inspector instead of shipping.
+
+Do not merge or deploy. Merging stays the sovereign's call.

package/.opencode/commands/spec.md

@@ -0,0 +1,18 @@
+---
+description: Write or refine the Regent specification artifact (docs/superpowers/specs/YYYY-MM-DD-<topic>.md) from the current goal and conversation
+subtask: true
+agent: regent-general
+---
+
+Write the specification for:
+$ARGUMENTS
+
+Load the `spec` skill. Produce the spec artifact at `docs/superpowers/specs/YYYY-MM-DD-<topic>.md` (use today's date and a topic slug derived from the goal).
+
+1. Explore the repo for domain vocabulary (`CONTEXT.md`, `docs/adr/`, `UBIQUITOUS_LANGUAGE.md`) and current state.
+2. Sketch the seams at which the feature will be tested; prefer existing seams, propose the highest seam possible.
+3. Write the spec: Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes.
+4. Do not include specific file paths or code snippets in the spec (except decision-rich prototype snippets).
+5. Keep it reviewable: the Strategist gate asks "Is this design correct?" before the pipeline proceeds.
+
+Do not plan, ticket, or implement. This phase produces the spec only.

package/.opencode/commands/status.md

@@ -0,0 +1,13 @@
+---
+description: Show the current pipeline state — phase, plan progress, evidence, and the one permitted next action
+subtask: true
+agent: regent-general
+---
+
+Report the current Regent pipeline state. Scope: $ARGUMENTS (optional; omit for the whole run).
+
+1. Read the run state at `docs/superpowers/run/state.json` (if present) for phase, goal, spec, and acceptance.
+2. Read the plan artifact at `docs/superpowers/plans/<slug>/` (if present); summarize each task's status, blocking edges, and frontier (tasks whose blockers are all done).
+3. Run `changed-files` for unverified evidence; look for stale verified evidence via the verify tool's evidence_gate.freshness.
+4. Report `git status --short --branch` and any uncommitted changes.
+5. End with exactly one permitted next action: clarify, plan, execute, verify, accept, ship, or wait-for-sovereign — never more. Read-only: do not mutate state, plan, or source.

package/.opencode/commands/tdd.md

@@ -0,0 +1,18 @@
+---
+description: TDD red-green-refactor — iron law: no code without failing test
+subtask: true
+agent: regent-general
+---
+
+The user wants to develop using TDD:
+$ARGUMENTS
+
+Load the `tdd` skill. The Iron Law applies: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
+
+RED — write one failing test (one behavior, clear name, real code). VERIFY RED — watch it fail.
+
+GREEN — write minimal code to pass. No extra features. VERIFY GREEN — watch it pass, all tests green.
+
+REFACTOR — clean up. Keep tests green.
+
+One behavior per cycle. Do not write all tests first (horizontal slices = not TDD).

package/.opencode/commands/verify.md

@@ -0,0 +1,18 @@
+---
+description: Verification evidence gate — fresh proof before any completion claim
+subtask: true
+agent: regent-general
+---
+
+The user wants to verify:
+$ARGUMENTS
+
+Load the `verification-before-completion` skill. The Iron Law applies: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+
+1. IDENTIFY — what command proves the claim?
+2. RUN — execute the full command (fresh, complete)
+3. READ — full output, exit code, failure count
+4. VERIFY — does output confirm the claim?
+5. ONLY THEN — make the claim
+
+No "should", "probably", "seems fine". Fresh evidence or it did not happen.

package/.opencode/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "dependencies": {
+    "@opencode-ai/plugin": "0.0.0-beta-18314"
+  }
+}