opencode-autoresearch 3.3.1 → 3.4.1

package/.opencode/INSTALL.md

@@ -0,0 +1,85 @@
+# Installing Auto Research for OpenCode
+
+For the public raw install handoff, see [`../INSTALL.md`](../INSTALL.md).
+
+## Prerequisites
+
+- [OpenCode.ai](https://opencode.ai) installed
+
+## Recommended: OpenCode Plugin Install
+
+Add Auto Research to the `plugin` array in your global or project-level `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-autoresearch@latest"]
+}
+```
+
+Restart OpenCode. OpenCode installs npm plugins automatically and registers the Auto Research commands.
+
+Verify inside OpenCode by running:
+
+```text
+/autoresearch
+```
+
+## Optional: Global CLI Install
+
+Install the CLI globally if you also want `autoresearch` and `opencode-autoresearch` on your shell `PATH`:
+
+```bash
+npm install -g opencode-autoresearch
+opencode-autoresearch doctor
+```
+
+For one-time use without a global install:
+
+```bash
+npx opencode-autoresearch doctor
+```
+
+## Commands
+
+After installation, these commands are available in OpenCode:
+
+- `/autoresearch`
+- `/autoresearch:plan`
+- `/autoresearch:debug`
+- `/autoresearch:fix`
+- `/autoresearch:learn`
+- `/autoresearch:predict`
+- `/autoresearch:scenario`
+- `/autoresearch:security`
+- `/autoresearch:ship`
+
+## Updating
+
+OpenCode refreshes npm plugins when it starts. The `opencode-autoresearch@latest` plugin entry follows the current npm `latest` release. Restart OpenCode after changing `opencode.json` or after a new Auto Research package release is published.
+
+To pin a version:
+
+```json
+{
+  "plugin": ["opencode-autoresearch@3.3.3"]
+}
+```
+
+## Troubleshooting
+
+### Plugin not loading
+
+1. Verify the package name in `opencode.json` is `opencode-autoresearch`.
+2. Restart OpenCode after editing config.
+3. Check OpenCode logs with `opencode run --print-logs "hello"`.
+
+### CLI not found
+
+1. Run `npm install -g opencode-autoresearch`.
+2. Verify your npm global bin directory is on `PATH`.
+3. Run `opencode-autoresearch doctor`.
+
+## Getting Help
+
+- Issues: https://github.com/Maleick/AutoResearch/issues
+- Documentation: https://github.com/Maleick/AutoResearch#readme

package/.opencode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "autoresearch",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "Auto Research for OpenCode. Run a structured autonomous iteration loop with a standing subagent pool.",
   "author": {
     "name": "Maleick",
@@ -34,4 +34,4 @@
     "termsOfServiceURL": "https://github.com/Maleick/AutoResearch/blob/main/LICENSE",
     "brandColor": "#0F766E"
   }
-}
+}

package/AGENTS.md

@@ -0,0 +1,44 @@
+# Auto Research Agent Guide
+
+## Project Purpose
+
+Auto Research is an OpenCode and Hermes Agent workflow bundle plus npm package for structured autonomous improve-verify loops.
+
+## Source of Truth
+
+- Runtime source lives in `src/`.
+- OpenCode commands live in `commands/`.
+- The Auto Research skill bundle lives in `skills/autoresearch/`.
+- The Hermes Agent skill bundle and integration docs live in `skills/hermes/`.
+- Shell hooks live in `hooks/`.
+- OpenCode package metadata lives in `.opencode-plugin/plugin.json`.
+- Installation, architecture, and release docs live in `docs/` and `wiki/`.
+
+## Development Rules
+
+- Build context from existing files before changing behavior.
+- Prefer the smallest correct change.
+- Do not commit, tag, push, create releases, or publish packages unless the user explicitly asks.
+- Do not commit runtime artifacts from `.autoresearch/` or generated result files.
+- Keep `VERSION`, `package.json`, `package-lock.json`, `src/constants.ts`, and `.opencode-plugin/plugin.json` aligned for releases.
+- When Hermes cron, `delegate_task`, model routing, or install behavior changes, keep `README.md`, `INSTALL.md`, `docs/`, `wiki/`, and `skills/hermes/` aligned.
+
+## Security Rules
+
+- Do not add install flows that pipe remote scripts into a shell.
+- Keep package contents guarded by `hooks/verify-package.sh`.
+- Do not hardcode secrets, tokens, credentials, or private paths.
+- Pass shell variables into inline scripts through environment variables or argv, not by interpolating into source code.
+
+## Verification
+
+Run the focused relevant checks before claiming work is complete. Release-prep changes should run:
+
+```bash
+npm audit --audit-level=moderate
+npm run typecheck
+npm run build
+npm run verify:pack
+npm test
+npm pack --dry-run
+```

package/INSTALL.md

@@ -0,0 +1,275 @@
+# Install Auto Research
+
+Auto Research is a multi-runtime plugin and npm package for structured autonomous improve-verify loops. It keeps runtime state local to the target repository and gates changes with mechanical verification.
+
+## Supported Runtimes
+
+- **OpenCode** — Slash commands (`/autoresearch`) with standing subagent pool
+- **Hermes Agent** — Cron-based iteration loop with `delegate_task` subagents (max 3)
+
+Both runtimes share the same state format (`.autoresearch/state.json`) and CLI (`opencode-autoresearch`).
+
+---
+
+## OpenCode Install
+
+### One-Line OpenCode Install
+
+Paste this one line into OpenCode to install and verify Auto Research. This URL follows the latest `main` instructions:
+
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/Maleick/AutoResearch/refs/heads/main/INSTALL.md
+```
+
+### Prerequisites
+
+- OpenCode installed and available in your shell.
+- Node.js with npm available for the optional CLI path.
+- Git installed and available in your shell.
+- A target repository with a verification command such as `npm test`, `pytest`, or `go test ./...`.
+
+### Recommended OpenCode Plugin Install
+
+Add Auto Research to your global or project-level `opencode.json` plugin array:
+
+```json
+{
+  "plugin": ["opencode-autoresearch@latest"]
+}
+```
+
+Restart OpenCode after editing the configuration. The command family should then be available inside your target repository:
+
+```text
+/autoresearch
+/autoresearch:plan
+/autoresearch:debug
+/autoresearch:fix
+/autoresearch:learn
+/autoresearch:predict
+/autoresearch:scenario
+/autoresearch:security
+/autoresearch:ship
+```
+
+### npm Global Install
+
+If you also want the CLI available on your shell `PATH`:
+
+```bash
+npm install -g opencode-autoresearch
+opencode-autoresearch doctor
+opencode-autoresearch --version
+```
+
+Then restart OpenCode and run:
+
+```text
+/autoresearch
+```
+
+### One-Time CLI Path
+
+For one-time CLI use without a global install:
+
+```bash
+npx opencode-autoresearch doctor
+```
+
+Use the plugin-array install for normal OpenCode usage.
+
+---
+
+## Hermes Agent Install
+
+### Prerequisites
+
+- Hermes Agent installed and configured.
+- Node.js with npm available for the CLI path.
+- Git installed and available in your shell.
+
+### Install the Hermes Skill
+
+```bash
+# 1. Clone AutoResearch (or use an existing checkout)
+git clone https://github.com/Maleick/AutoResearch.git
+cd AutoResearch
+npm install
+
+# 2. Copy skill files to your Hermes skills directory
+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
+```
+
+### Create the 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'."
+```
+
+### Initialize a Run
+
+Initialize state from a trusted shell before enabling unattended cron:
+
+```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
+```
+
+Do not rely on cron to auto-init from repository config; the Hermes skill treats repository commands as untrusted unless they match operator-approved cron commands.
+
+### Start, Check, and Stop
+
+```bash
+# Start
+hermes cron resume autoresearch-loop
+
+# Check status
+cat .autoresearch/state.json | jq .
+
+# Stop
+hermes cron pause autoresearch-loop
+# Or set stop flag:
+jq '.flags.stop_requested = true' .autoresearch/state.json > tmp.json && mv tmp.json .autoresearch/state.json
+```
+
+See [`skills/hermes/README.md`](skills/hermes/README.md) for full Hermes setup, troubleshooting, and command mapping.
+
+---
+
+## Verification
+
+These checks do not require secrets:
+
+```bash
+npm view opencode-autoresearch version
+npm view opencode-autoresearch dist-tags
+opencode-autoresearch doctor
+```
+
+For a local clone:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm run verify:pack
+npm test
+```
+
+To verify command availability:
+
+- **OpenCode**: restart OpenCode in a Git repository and run `/autoresearch`.
+- **Hermes**: run `hermes cron list` and confirm `autoresearch-loop` is present.
+
+---
+
+## Updating
+
+### OpenCode
+
+For plugin-array installs, `opencode-autoresearch@latest` follows the current npm `latest` release. Restart OpenCode after a new Auto Research package release is available. To pin a fixed version instead:
+
+```json
+{
+  "plugin": ["opencode-autoresearch@3.3.3"]
+}
+```
+
+For npm global installs:
+
+```bash
+npm install -g opencode-autoresearch@latest
+npm list -g opencode-autoresearch --depth=0
+```
+
+### Hermes
+
+Update the skill files from the latest repo checkout:
+
+```bash
+cd AutoResearch
+git pull origin main
+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
+```
+
+Restart the cronjob if needed:
+
+```bash
+hermes cron resume autoresearch-loop
+```
+
+---
+
+## Troubleshooting
+
+### Plugin Not Loading (OpenCode)
+
+- Confirm `opencode.json` is valid JSON.
+- Confirm the plugin entry is in the top-level `plugin` array.
+- Restart OpenCode after changing the config.
+- Check OpenCode logs with `opencode run --print-logs "hello"`.
+
+### Commands Not Found (OpenCode)
+
+- Restart OpenCode so it reloads plugin commands.
+- Confirm the package installed successfully with `npm list -g opencode-autoresearch --depth=0` if using the global path.
+- Run `/autoresearch` from inside a Git repository, not from an empty directory.
+
+### Cron Not Running (Hermes)
+
+```bash
+hermes cron list
+hermes logs --component cron
+```
+
+### State File Corrupted (any runtime)
+
+```bash
+# Reset to baseline
+rm .autoresearch/state.json
+# Next run will re-init from config
+```
+
+### Subagent Failures (Hermes)
+
+Check `.autoresearch/state.json` for:
+- `flags.needs_human` — requires manual intervention
+- Last iteration's `error` field
+
+### Runtime Artifacts
+
+- Auto Research writes runtime state to `.autoresearch/` in the target repository.
+- Do not commit `.autoresearch/`, `autoresearch-results.tsv`, `autoresearch-report.md`, or `autoresearch-memory.md` unless you intentionally want to share run outputs.
+
+---
+
+## Safety Notes
+
+- Start with a measurable goal, metric, and verification command.
+- Review generated reports before relying on unattended background runs.
+- Keep verification mechanical; do not accept improvements based on intuition alone.
+- Do not pipe remote install scripts into a shell.
+
+---
+
+## Links
+
+- Documentation: https://github.com/Maleick/AutoResearch/tree/main/docs
+- Wiki: https://github.com/Maleick/AutoResearch/wiki
+- Releases: https://github.com/Maleick/AutoResearch/releases
+- Issues: https://github.com/Maleick/AutoResearch/issues
+- Hermes docs: https://hermes-agent.nousresearch.com/docs

package/README.md

@@ -1,10 +1,11 @@
 # Auto Research
 
 <p align="center">
-  <img src="assets/autoresearch-banner.svg" width="900" alt="Auto Research — Autonomous recursive self-improvement engine" />
+  <img src="assets/autoresearch-banner.svg" width="900" alt="Auto Research — Multi-runtime autonomous recursive self-improvement engine" />
 </p>
 
 <p align="center">
+  <img src="https://img.shields.io/badge/version-v3.4.1-58a6ff?style=flat" alt="v3.4.1">
   <a href="https://github.com/Maleick/AutoResearch/stargazers"><img src="https://img.shields.io/github/stars/Maleick/AutoResearch?style=flat&color=58a6ff" alt="Stars"></a>
   <a href="https://github.com/Maleick/AutoResearch/commits/main"><img src="https://img.shields.io/github/last-commit/Maleick/AutoResearch?style=flat" alt="Last Commit"></a>
   <a href="https://github.com/Maleick/AutoResearch/releases"><img src="https://img.shields.io/github/v/release/Maleick/AutoResearch?style=flat" alt="Version"></a>
@@ -20,7 +21,7 @@
   <a href="#self-improvement-loop">Self-Improvement</a>
 </p>
 
-<p align="center"><strong>Autonomous recursive self-improvement engine for OpenCode.</strong></p>
+<p align="center"><strong>Multi-runtime autonomous recursive self-improvement engine.</strong></p>
 
 ```text
 ┌──────────────────────────────────────────────┐
@@ -34,7 +35,7 @@
 
 ## What It Does
 
-Auto Research is a **subagent-first autonomous iteration engine** that runs structured improve-verify loops inside OpenCode. Unlike simple task runners, it maintains a standing pool of specialized subagents, persists learnings across iterations, and can run recursive self-improvement loops on its own codebase.
+Auto Research is a **subagent-first autonomous iteration engine** that runs structured improve-verify loops inside **OpenCode** or **Hermes Agent**. Unlike simple task runners, it maintains a pool of specialized subagents, persists learnings across iterations, and can run recursive self-improvement loops on its own codebase.
 
 - **Plans** experiments from a measurable goal
 - **Modifies** one focused change per iteration
@@ -59,7 +60,7 @@ flowchart LR
 ```mermaid
 flowchart TD
     A[Goal + Metric + Verify] --> B[Baseline]
-    B --> C[Standing Pool Init]
+    B --> C[Pool Init]
     C --> D[Iteration N]
     D --> E[Subagent Context]
     E --> F[Focused Change]
@@ -96,34 +97,79 @@ See [`skills/autoresearch/references/self-improve-loop.md`](skills/autoresearch/
 
 ## Installation
 
-Install the CLI globally if you want Auto Research available long-term on your PATH:
+### OpenCode
 
-```bash
-npm install -g opencode-autoresearch
-opencode-autoresearch doctor
+For OpenCode, paste this one-line install prompt into your agent. This URL follows the latest `main` instructions:
+
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/Maleick/AutoResearch/refs/heads/main/INSTALL.md
 ```
 
-For a one-time install without keeping a global CLI, use `bunx` instead:
+Recommended plugin install in `opencode.json`:
 
-```bash
-bunx opencode-autoresearch install
-bunx opencode-autoresearch doctor
+```json
+{
+  "plugin": ["opencode-autoresearch@latest"]
+}
 ```
 
-Then start the setup wizard inside OpenCode:
+Restart OpenCode, then run the setup wizard:
 
 ```text
 /autoresearch
 ```
 
-## Quick Start
+### Hermes Agent
+
+```bash
+# 1. Clone AutoResearch
+git clone https://github.com/Maleick/AutoResearch.git
+cd AutoResearch
+npm install
+
+# 2. Install the Hermes skill
+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
+
+# 3. Create a cronjob
+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\"."
+```
+
+See [`skills/hermes/README.md`](skills/hermes/README.md) for full Hermes setup, troubleshooting, and command mapping.
+
+### npm CLI (both runtimes)
+
+Global install path:
 
 ```bash
-# 1. Install the CLI globally
 npm install -g opencode-autoresearch
+autoresearch doctor
+autoresearch --version
+```
+
+One-time package runner path:
+
+```bash
+npx opencode-autoresearch doctor
+```
+
+See [`INSTALL.md`](INSTALL.md) for prerequisites, verification, updating, and troubleshooting.
+
+## Quick Start
 
-# 2. Verify installation
-opencode-autoresearch doctor
+### OpenCode
+
+```bash
+# 1. Add the plugin to opencode.json
+# { "plugin": ["opencode-autoresearch@latest"] }
+
+# 2. Restart OpenCode
 
 # 3. Navigate to your project
 cd ~/Projects/my-project
@@ -132,25 +178,48 @@ cd ~/Projects/my-project
 /autoresearch
 ```
 
+### Hermes Agent
+
+```bash
+# 1. Ensure the skill is installed (see Installation above)
+
+# 2. Initialize state from a trusted shell before enabling unattended cron
+autoresearch init \
+  --goal "Improve test coverage" \
+  --metric "coverage_pct" \
+  --direction "higher" \
+  --verify "npm run test:coverage" \
+  --guard "npm run typecheck" \
+  --iterations 20 \
+  --mode background
+
+# 3. Start the cronjob
+hermes cron resume autoresearch-loop
+
+# 4. Check progress
+cat .autoresearch/state.json | jq .
+```
+
 ## Runtime Surfaces
 
 | Surface | Entry point |
 | --- | --- |
 | OpenCode | `/autoresearch`, `/autoresearch:plan`, `/autoresearch:debug`, `/autoresearch:fix`, `/autoresearch:learn`, `/autoresearch:predict`, `/autoresearch:scenario`, `/autoresearch:security`, `/autoresearch:ship` |
+| Hermes | Cronjob `autoresearch-loop` (see `skills/hermes/README.md`) |
 
 ## Commands
 
-| Command | Purpose |
-| --- | --- |
-| `/autoresearch` | Default improve-verify loop |
-| `/autoresearch:plan` | Planning workflow |
-| `/autoresearch:debug` | Debugging workflow |
-| `/autoresearch:fix` | Fix workflow |
-| `/autoresearch:learn` | Learning workflow |
-| `/autoresearch:predict` | Prediction workflow |
-| `/autoresearch:scenario` | Scenario expansion |
-| `/autoresearch:security` | Security review |
-| `/autoresearch:ship` | Ship-readiness workflow |
+| Command | Purpose | Hermes Equivalent |
+| --- | --- | --- |
+| `/autoresearch` | Default improve-verify loop | Cron runs iteration loop |
+| `/autoresearch:plan` | Planning workflow | Subagent task: plan experiments |
+| `/autoresearch:debug` | Debugging workflow | Subagent task: debug failures |
+| `/autoresearch:fix` | Fix workflow | Subagent task: fix issues |
+| `/autoresearch:learn` | Learning workflow | Memory tool + pattern analysis |
+| `/autoresearch:predict` | Prediction workflow | Subagent task: predict outcomes |
+| `/autoresearch:scenario` | Scenario expansion | Subagent task: expand scenarios |
+| `/autoresearch:security` | Security review | Subagent task: security audit |
+| `/autoresearch:ship` | Ship-readiness workflow | Subagent task: ship checks |
 
 ## CLI Commands
 
@@ -180,15 +249,16 @@ cd ~/Projects/my-project
 ```mermaid
 flowchart LR
     A[OpenCode /autoresearch] --> B[CLI]
+    H[Hermes Cronjob] --> B
     B --> C[Run Manager]
     C --> D[State JSON]
     C --> E[Results TSV]
     C --> F[Subagent Pool]
     F --> G[Orchestrator]
-    F --> H[Scout]
-    F --> I[Analyst]
-    F --> J[Verifier]
-    F --> K[Synthesizer]
+    F --> I[Scout]
+    F --> J[Analyst]
+    F --> K[Verifier]
+    F --> L[Synthesizer]
 ```
 
 ## Runtime Artifacts
@@ -249,6 +319,19 @@ The standing pool provides specialized roles reused across iterations:
 | `release_guard` | Ship-readiness verification |
 | `research_tracker` | Pattern tracking across iterations |
 
+## Runtime Comparison
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/autoresearch` slash command | Cronjob or `delegate_task` |
+| Subagents | Standing pool (unlimited) | Batch via `delegate_task` (max 3) |
+| Real-time | Yes | 15-minute cron intervals |
+| Slash commands | 8 variants | Separate cron jobs or tasks |
+| State | `.autoresearch/state.json` | Same file format |
+| Memory | File-based (`autoresearch-memory.md`) | `memory` tool + file |
+| Background | `autoresearch launch` | Native cron |
+| Resume | `autoresearch resume` | Cron continues automatically |
+
 ## Development
 
 ```bash
@@ -264,13 +347,17 @@ npm pack --dry-run  # Preview shipped package contents
 src/                           # TypeScript source (runtime helpers, CLI, subagent pool)
 dist/                          # Compiled JavaScript output
 commands/                      # OpenCode command surfaces
-skills/autoresearch/           # Skill bundle with references
+skills/autoresearch/           # OpenCode skill bundle with references
   references/                  # Workflow and runtime references
     core-principles.md         # Loop discipline
     loop-workflow.md           # Main iteration workflow
     subagent-orchestration.md  # Pool management
     state-management.md        # State semantics
     self-improve-loop.md       # Recursive self-improvement
+skills/hermes/                 # Hermes Agent skill bundle
+  README.md                    # Hermes setup and usage
+  INTEGRATION.md               # Architecture and command mapping
+  autoresearch-prompt.md       # Cron prompt template
 hooks/                         # Shell hooks for session lifecycle
 docs/                          # Install and architecture docs
 wiki/                          # GitHub wiki pages
@@ -280,7 +367,8 @@ wiki/                          # GitHub wiki pages
 
 ## Notes
 
-- This is an **OpenCode-only** package. No Claude or Codex runtime is supported.
+- **OpenCode** users: install via `opencode.json` plugin array or `npm install -g opencode-autoresearch`.
+- **Hermes Agent** users: install via skill files in `skills/hermes/` and create a cronjob.
 - The CLI uses Node.js ESM modules.
 - Self-improvement loops require `--mode background` for long-running unattended operation.
 - Memory files (`autoresearch-memory.md`) are portable across runs and repositories.

package/VERSION

@@ -1 +1 @@
-3.3.1
+3.4.1

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "3.3.1";
+export declare const VERSION = "3.4.1";
 export declare const PACKAGE_NAME = "opencode-autoresearch";
 export declare const SKILL_NAME = "autoresearch";
 export declare const PRODUCT_BRAND = "Auto Research";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "3.3.1";
+export const VERSION = "3.4.1";
 export const PACKAGE_NAME = "opencode-autoresearch";
 export const SKILL_NAME = "autoresearch";
 export const PRODUCT_BRAND = "Auto Research";