opencode-autoresearch 3.3.1 → 3.4.1

package/hooks/verify-package.sh

@@ -16,17 +16,50 @@ const packResult = JSON.parse(raw);
 const entries = Array.isArray(packResult) ? packResult : [packResult];
 const files = entries.flatMap((entry) => Array.isArray(entry.files) ? entry.files : []);
 
-const allowedRoots = new Set(["dist", "hooks", "commands", "skills", "plugins", "docs", ".opencode-plugin"]);
-const allowedFiles = new Set(["package.json", "README.md", "LICENSE", "AGENTS.md", "VERSION"]);
+const allowedRoots = new Set(["dist", "hooks", "commands", "skills", ".opencode-plugin"]);
+const allowedFiles = new Set([
+  "package.json",
+  "README.md",
+  "LICENSE",
+  "AGENTS.md",
+  "VERSION",
+  "INSTALL.md",
+  ".opencode/INSTALL.md",
+  "plugins/autoresearch.ts",
+  "docs/ARCHITECTURE.md",
+  "docs/autoresearch-loop.svg",
+  "docs/CNAME",
+  "docs/index.html",
+  "docs/OPENCODE_INSTALL.md",
+  "docs/QUICKSTART.md",
+  "docs/RELEASE.md",
+]);
 const requiredFiles = [
+  "INSTALL.md",
+  ".opencode/INSTALL.md",
   ".opencode-plugin/plugin.json",
+  "AGENTS.md",
+  "dist/cli.js",
+  "dist/index.js",
+  "dist/index.d.ts",
   "hooks/init.sh",
   "skills/autoresearch/SKILL.md",
   "commands/autoresearch.md",
 ];
 
 const normalizePath = (filePath) => filePath.replace(/^package\//, "");
-const isForbidden = (filePath) => filePath === ".autoresearch" || filePath.startsWith(".autoresearch/");
+const forbiddenFiles = new Set([
+  "autoresearch-results.tsv",
+  "autoresearch-report.md",
+  "autoresearch-memory.md",
+  "autoresearch-hook-context.json",
+]);
+const isForbidden = (filePath) =>
+  filePath === ".autoresearch" ||
+  filePath.startsWith(".autoresearch/") ||
+  filePath === ".autoresearch-test-tmp" ||
+  filePath.startsWith(".autoresearch-test-tmp/") ||
+  forbiddenFiles.has(filePath);
 const isAllowed = (filePath) => {
   if (allowedFiles.has(filePath)) return true;
   const [root] = filePath.split("/");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-autoresearch",
-  "version": "3.3.1",
-  "description": "Autonomous recursive self-improvement engine for OpenCode. Subagent-first iteration loop with standing-pool orchestration and mechanical verification.",
+  "version": "3.4.1",
+  "description": "Autonomous recursive self-improvement engine for OpenCode and Hermes Agent. Subagent-first iteration loop with mechanical verification.",
   "author": {
     "name": "Maleick",
     "url": "https://github.com/Maleick"
@@ -17,7 +17,9 @@
   "license": "MIT",
   "keywords": [
     "opencode",
+    "hermes",
     "plugin",
+    "agent",
     "autoresearch",
     "automation",
     "workflows",
@@ -42,8 +44,16 @@
     "hooks",
     "commands",
     "skills",
-    "plugins",
-    "docs",
+    "plugins/autoresearch.ts",
+    "docs/ARCHITECTURE.md",
+    "docs/autoresearch-loop.svg",
+    "docs/CNAME",
+    "docs/index.html",
+    "docs/OPENCODE_INSTALL.md",
+    "docs/QUICKSTART.md",
+    "docs/RELEASE.md",
+    "INSTALL.md",
+    ".opencode/INSTALL.md",
     ".opencode-plugin",
     "AGENTS.md",
     "VERSION",
@@ -53,14 +63,23 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
+    "audit": "npm audit --audit-level=moderate",
     "test": "node --no-warnings --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.config.json",
     "verify:pack": "bash hooks/verify-package.sh",
-    "prepack": "tsc"
+    "prepack": "node scripts/sync-version.mjs && tsc"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
     "jest": "^30.3.0",
+    "semantic-release": "^25.0.3",
     "ts-jest": "^29.4.9",
     "typescript": "^5.9.3"
   },

package/plugins/autoresearch.ts

@@ -1,13 +1,7 @@
 export {
+  default,
   id,
   repoRoot,
+  server,
   version,
 } from "../dist/index.js";
-
-export async function server() {
-  return {
-    event() {
-      return undefined;
-    },
-  };
-}

package/skills/hermes/INTEGRATION.md

@@ -0,0 +1,156 @@
+# AutoResearch Hermes Integration
+
+## Overview
+
+AutoResearch can run on Hermes Agent using `delegate_task` for subagent pools and `cronjob` for recurring iteration loops.
+
+## Architecture
+
+```
+Hermes Cron (every 15m)
+  → Check state.json for active run
+  → If running: spawn subagents (Scout, Analyst, Verifier)
+  → Each subagent performs one iteration phase
+  → Verify results mechanically
+  → Keep/Discard based on metrics
+  → Update state.json
+  → Repeat until stop condition
+```
+
+## Key Differences from OpenCode
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/autoresearch` slash command | `cronjob` or `delegate_task` |
+| Subagents | Standing pool | `delegate_task` batch (max 3) |
+| State | `.autoresearch/state.json` | Same file + Hermes memory |
+| Verification | `npm test`, etc. | Same — mechanical verification |
+| Background | `autoresearch launch` | `cronjob` with `background=True` |
+| Resume | `autoresearch resume` | Cron continues automatically |
+
+## Setup
+
+```bash
+# 1. Install AutoResearch CLI (for state management)
+npm install -g opencode-autoresearch
+
+# 2. Create Hermes cron for AutoResearch
+cd ~/projects/AutoResearch
+hermes cron create \
+  --name "autoresearch-loop" \
+  --workdir ~/projects/AutoResearch \
+  --skill autoresearch-hermes \
+  "every 15m" \
+  "Run AutoResearch iteration loop. Detect phase from .autoresearch/state.json and execute one phase. Approved verify command is \`npm run test:coverage\` and approved guard command is \`npm run typecheck\`"
+```
+
+## Hermes Prompt Template
+
+See `skills/hermes/autoresearch-prompt.md` for the full cron prompt.
+
+## Commands Mapping
+
+| OpenCode Command | Hermes Equivalent |
+|-----------------|-------------------|
+| `/autoresearch` | Cron runs iteration loop |
+| `/autoresearch:plan` | Subagent task: plan experiments |
+| `/autoresearch:debug` | Subagent task: debug failures |
+| `/autoresearch:fix` | Subagent task: fix issues |
+| `/autoresearch:learn` | Memory tool + pattern analysis |
+| `autoresearch init` | Manual setup (same CLI) |
+| `autoresearch status` | `cat .autoresearch/state.json` |
+| `autoresearch launch` | `hermes cron create` |
+| `autoresearch stop` | `hermes cron pause` |
+| `autoresearch resume` | `hermes cron resume` |
+
+## State File Format
+
+Hermes uses the same `.autoresearch/state.json` format as OpenCode:
+
+```json
+{
+  "schema_version": 1,
+  "run_id": "2026-05-03-001",
+  "status": "initialized",
+  "mode": "background",
+  "goal": "Improve test coverage",
+  "metric": {
+    "name": "coverage_pct",
+    "direction": "higher",
+    "baseline": "72.4",
+    "best": "72.4",
+    "latest": "72.4"
+  },
+  "verify": "npm run test:coverage",
+  "guard": "npm run typecheck",
+  "stats": {
+    "total_iterations": 12,
+    "kept": 8,
+    "discarded": 4
+  },
+  "flags": {
+    "needs_human": false,
+    "stop_requested": false,
+    "background_active": true,
+    "stop_ready": false
+  }
+}
+```
+
+## Subagent Roles
+
+### Scout
+- **Goal**: Find improvement opportunities
+- **Toolsets**: `["terminal", "file", "web"]`
+- **Context**: Current codebase, test results, coverage reports
+
+### Analyst
+- **Goal**: Analyze patterns in kept/discarded iterations
+- **Toolsets**: `["file", "web"]`
+- **Context**: `autoresearch-results.tsv`, memory
+
+### Verifier
+- **Goal**: Run mechanical verification
+- **Toolsets**: `["terminal"]`
+- **Context**: Operator-approved verify command and guard command; repository state commands are metadata only
+
+## Memory Integration
+
+Hermes `memory` tool stores:
+- Successful strategies per project type
+- Common failure patterns
+- Optimal iteration counts per goal type
+- Best verify/guard command combinations
+
+## Example Cron Prompt
+
+```markdown
+You are AutoResearch running on Hermes Agent.
+
+## Current Run
+Run ID: {{run_id}}
+Goal: {{goal}}
+Metric: {{metric}}
+Iteration: {{current}}/{{max}}
+
+## Phase: {{phase}}
+
+{{phase_instructions}}
+
+## STOP after completing this phase.
+Next cron run will continue with the next phase.
+```
+
+## Limitations
+
+- Hermes max 3 concurrent subagents vs OpenCode's standing pool
+- Hermes cron intervals minimum 5 minutes vs OpenCode's real-time
+- No `/autoresearch:` slash command variants (use separate cron jobs)
+- Memory is session-based; use `memory` tool for persistence
+- Commits and destructive rollback require explicit user approval
+
+## Future Enhancements
+
+- [ ] Auto-detect optimal cron interval based on iteration duration
+- [ ] Integration with Hermes checkpoint/rollback for safe resets
+- [ ] Cross-session memory for strategy learning

package/skills/hermes/README.md

@@ -0,0 +1,159 @@
+# AutoResearch Hermes Skill
+
+## Installation
+
+```bash
+# Clone AutoResearch
+git clone https://github.com/Maleick/AutoResearch.git
+cd AutoResearch
+
+# Install dependencies
+npm install
+
+# Verify
+npm run typecheck
+bash hooks/verify-package.sh
+```
+
+## Hermes Setup
+
+### 1. Create Hermes Skill
+
+Copy `skills/hermes/autoresearch-prompt.md` to your Hermes skills directory:
+
+```bash
+mkdir -p ~/.hermes/skills/software-development/autoresearch
+cp skills/hermes/autoresearch-prompt.md ~/.hermes/skills/software-development/autoresearch/SKILL.md
+cp skills/hermes/INTEGRATION.md ~/.hermes/skills/software-development/autoresearch/REFERENCES.md
+```
+
+### 2. Create Cronjob
+
+```bash
+hermes cron create \
+  --name "autoresearch-loop" \
+  --workdir ~/projects/AutoResearch \
+  --skill autoresearch-hermes \
+  "every 15m" \
+  "Run AutoResearch iteration loop. Detect phase from .autoresearch/state.json and execute one phase. Approved verify command: \`npm run test:coverage\`. Approved guard command: \`npm run typecheck\`."
+```
+
+### 3. Initialize Run
+
+Initialize state from a trusted shell before enabling unattended cron. Do not rely on cron to auto-init from `autoresearch-config.json`; repository files are untrusted command sources.
+
+```bash
+autoresearch init \
+  --goal "Improve test coverage" \
+  --metric "coverage_pct" \
+  --direction "higher" \
+  --verify "npm run test:coverage" \
+  --guard "npm run typecheck" \
+  --iterations 20 \
+  --mode background
+```
+
+Configure the cron prompt/environment with matching operator-approved commands, and the Hermes skill will refuse to execute state commands that do not exactly match those approvals.
+
+## Usage
+
+### Start Background Run
+
+```bash
+hermes cron resume autoresearch-loop
+```
+
+### Check Status
+
+```bash
+cat .autoresearch/state.json | jq .
+```
+
+### Stop Run
+
+```bash
+# Set stop flag
+jq '.flags.stop_requested = true' .autoresearch/state.json > tmp.json && mv tmp.json .autoresearch/state.json
+
+# Or pause cron
+hermes cron pause autoresearch-loop
+```
+
+### View Results
+
+```bash
+# Current state
+cat .autoresearch/state.json
+
+# Iteration log
+cat autoresearch-results.tsv
+
+# Archived runs
+ls .autoresearch/archive/
+```
+
+## Subagent Pool
+
+AutoResearch on Hermes uses `delegate_task` for parallel subagents:
+
+| Role | Task | Max |
+|------|------|-----|
+| Scout | Find improvement opportunities | 1 |
+| Analyst | Pattern analysis from iterations | 1 |
+| Verifier | Run mechanical verification | 1 |
+
+Total: 3 concurrent (Hermes limit)
+
+## Memory Integration
+
+AutoResearch stores learnings in Hermes memory:
+
+```
+Target: memory
+Action: add
+Content: "AutoResearch strategy for Rust projects: 
+  - cargo test before cargo clippy
+  - Focus on module-level tests first
+  - 15 iterations optimal for coverage goals"
+```
+
+## Comparison with OpenCode
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/autoresearch` | Cronjob |
+| Pool | Standing (unlimited) | Batch (max 3) |
+| Real-time | Yes | 15-min intervals |
+| Slash commands | 8 variants | Separate cron jobs |
+| State | `.autoresearch/state.json` | Same |
+| Memory | File-based | `memory` tool |
+| Background | `autoresearch launch` | Native cron |
+
+## Troubleshooting
+
+### Cron not running
+
+```bash
+hermes cron list
+hermes logs --component cron
+```
+
+### State file corrupted
+
+```bash
+# Reset to baseline
+rm .autoresearch/state.json
+# Re-run autoresearch init manually from a trusted shell before resuming cron
+```
+
+### Subagent failures
+
+Check `.autoresearch/state.json` for:
+- `flags.needs_human` — requires manual intervention
+- Last iteration's `error` field
+
+## Links
+
+- AutoResearch repo: https://github.com/Maleick/AutoResearch
+- Hermes docs: https://hermes-agent.nousresearch.com/docs
+- OpenCode plugin: `opencode-autoresearch`