opencode-autoresearch 3.3.0 → 3.4.0

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.0",
+  "version": "3.4.0",
   "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

@@ -1,42 +1,44 @@
 # Auto Research Agent Guide
 
-Auto Research is an OpenCode-only autonomous iteration engine with recursive self-improvement capabilities.
+## Project Purpose
 
-## Runtime Policy
+Auto Research is an OpenCode and Hermes Agent workflow bundle plus npm package for structured autonomous improve-verify loops.
 
-- OpenCode is the only supported runtime.
-- The iteration engine is subagent-first: a standing pool of specialized subagents supports the orchestrator.
-- Mechanical verification is mandatory — no keep decisions on intuition alone.
-- Background runs support overnight unattended operation.
+## Source of Truth
 
-## Local State
+- 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/`.
 
-`.autoresearch/` is runtime state and must not be committed.
+## 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
 
-Before claiming work is complete, run:
+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
 ```
-
-## Self-Improvement
-
-Auto Research can run on itself. See `skills/autoresearch/references/self-improve-loop.md` for recursive loop semantics.
-
-When running self-improvement:
-
-1. Define a measurable meta-goal.
-2. Use `--mode background` for long runs.
-3. Always set a `--guard` command to catch regressions.
-4. Review `autoresearch-memory.md` between meta-iterations.
-
-## Docs
-
-- [README.md](README.md) — Product overview
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — Architecture reference
-- [docs/RELEASE.md](docs/RELEASE.md) — Release process
-- [wiki/Home.md](wiki/Home.md) — Wiki index

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