opencode-autoresearch 3.1.0 → 3.3.1

package/docs/superpowers/specs/2026-05-03-install-release-security-design.md

@@ -0,0 +1,80 @@
+# Install, Release, and Security Update Design
+
+## Goal
+
+Prepare Auto Research for the next patch release by adding a native OpenCode install guide, aligning release/package documentation, and fixing security issues found during the audit.
+
+## Current Context
+
+Auto Research is distributed as the `opencode-autoresearch` npm package and exposes an OpenCode plugin surface through `.opencode-plugin/plugin.json`, `plugins/autoresearch.ts`, `commands/`, `skills/`, and `hooks/`. The repo already documents npm global installation, but it does not provide a repo-level `.opencode/INSTALL.md` like the Superpowers OpenCode guide.
+
+The audit found these release-readiness issues:
+
+- `AGENTS.md` is ignored and absent, but package metadata and release docs reference it.
+- `docs/ARCHITECTURE.md` still says the current reference is v3.3.0 while released metadata is v3.3.1.
+- `docs/RELEASE.md` says CI runs tests, but `.github/workflows/release.yml` currently runs build, typecheck, and package verification only.
+- `hooks/status.sh` and `hooks/stop.sh` interpolate `AUTORESEARCH_STATE` directly into inline JavaScript, which can break the JavaScript string if the environment variable contains quotes.
+- Dependencies are clean: `npm audit --audit-level=moderate` found 0 vulnerabilities and `npm outdated` reported no outdated packages.
+
+## Approach
+
+Use both supported install paths:
+
+- Primary: OpenCode native plugin install through `opencode.json` using the npm package name.
+- Alternative: npm global CLI install for users who want the `autoresearch` and `opencode-autoresearch` commands on `PATH`.
+
+This matches current OpenCode plugin documentation, which supports npm package entries in the `plugin` array and automatically installs them at startup. It also keeps the current npm CLI distribution intact.
+
+## Files and Responsibilities
+
+- `.opencode/INSTALL.md`: New concise OpenCode install guide modeled after the Superpowers install guide.
+- `README.md`: Main install section should show the OpenCode plugin path first and npm global CLI path second.
+- `docs/OPENCODE_INSTALL.md`: Full install guide should mirror the new install flow and include verification/troubleshooting.
+- `wiki/Installation.md`: Wiki install page should point users to the native plugin path and CLI alternative.
+- `AGENTS.md`: New tracked agent guide with repository-specific working, validation, security, and release rules.
+- `.gitignore`: Stop ignoring tracked `AGENTS.md` while continuing to ignore private local instruction files that should not ship.
+- `package.json`: Include `.opencode/INSTALL.md` in package contents and bump the patch version.
+- `package-lock.json`: Keep npm lock metadata aligned with `package.json`.
+- `.opencode-plugin/plugin.json`: Bump plugin manifest version.
+- `src/constants.ts`: Bump runtime version constant.
+- `VERSION`: Bump canonical version marker.
+- `CHANGELOG.md`: Add the new release entry.
+- `docs/ARCHITECTURE.md`: Align current version and package layout references.
+- `docs/RELEASE.md`: Align release docs with current version surfaces and trusted npm publishing workflow.
+- `.github/workflows/release.yml`: Add `npm test` to match documented release gates.
+- `hooks/status.sh`: Pass state path safely to Node without JavaScript string interpolation.
+- `hooks/stop.sh`: Pass state path safely to Node without JavaScript string interpolation.
+- `hooks/verify-package.sh`: Allow and require `.opencode/INSTALL.md`; keep package allowlist explicit.
+
+## Security Design
+
+The hook hardening should pass `STATUS_FILE` through Node's `process.env` instead of embedding it in JavaScript source. This prevents an environment value from changing the JavaScript program text and keeps shell quoting simple.
+
+The install docs must avoid `curl | sh` and destructive migration commands. They should show an explicit `opencode.json` plugin entry and a separate npm global CLI path.
+
+The package verifier remains allowlist-based. Adding `.opencode/INSTALL.md` must be explicit so unexpected files still fail `npm run verify:pack`.
+
+## Versioning
+
+This is a patch release because it adds install documentation, fixes release packaging metadata, and hardens hooks without changing the command surface or runtime data format.
+
+Target version: `3.3.2`.
+
+## Verification
+
+Run these gates before claiming release readiness:
+
+```bash
+npm audit --audit-level=moderate
+npm run typecheck
+npm run build
+npm run verify:pack
+npm test
+npm pack --dry-run
+```
+
+Also inspect the package dry-run output enough to confirm `.opencode/INSTALL.md`, `AGENTS.md`, `README.md`, `VERSION`, `.opencode-plugin/plugin.json`, `commands/`, `skills/`, `hooks/`, `plugins/`, and `docs/` are present while `.autoresearch/` and local context files are absent.
+
+## Release Boundary
+
+This work prepares the repository for release. Creating the git commit, tag, push, GitHub release, or npm publish requires explicit user approval after verification passes.

package/hooks/init.sh

@@ -14,8 +14,12 @@ checklist() {
 }
 
 if [ -f ".autoresearch/state.json" ]; then
-  status=$(node -e "try{const s=require('.autoresearch/state.json');console.log(s.status||'')}catch{e}''" 2>/dev/null || true)
+  status=$(node --input-type=module -e "
+    import { readFileSync } from 'fs';
+    const s = JSON.parse(readFileSync('.autoresearch/state.json', 'utf8'));
+    console.log(s.status || '');
+  " 2>/dev/null || true)
   if [ "$status" = "running" ] || [ "$status" = "initialized" ]; then
     checklist
   fi
-fi
+fi

package/hooks/status.sh

@@ -7,8 +7,9 @@ set -e
 STATUS_FILE="${AUTORESEARCH_STATE:-.autoresearch/state.json}"
 
 if [ -f "$STATUS_FILE" ]; then
-  node -e "
-    const s = require('$STATUS_FILE');
+  node --input-type=module -e "
+    import { readFileSync } from 'fs';
+    const s = JSON.parse(readFileSync('$STATUS_FILE', 'utf8'));
     console.log('Auto Research run: ' + s.run_id);
     console.log('Status: ' + s.status);
     console.log('Mode: ' + s.mode);
@@ -20,4 +21,4 @@ if [ -f "$STATUS_FILE" ]; then
   " 2>/dev/null || echo "No active run."
 else
   echo "No active run."
-fi
+fi

package/hooks/stop.sh

@@ -7,16 +7,20 @@ set -e
 STATUS_FILE="${AUTORESEARCH_STATE:-.autoresearch/state.json}"
 
 if [ -f "$STATUS_FILE" ]; then
-  mode=$(node -e "try{const s=require('$STATUS_FILE');console.log(s.mode||'')}catch{e}''" 2>/dev/null || true)
+  mode=$(node --input-type=module -e "
+    import { readFileSync } from 'fs';
+    const s = JSON.parse(readFileSync('$STATUS_FILE', 'utf8'));
+    console.log(s.mode || '');
+  " 2>/dev/null || true)
   if [ "$mode" = "background" ]; then
-    node -e "
-      const fs = require('fs');
-      const s = JSON.parse(fs.readFileSync('$STATUS_FILE','utf8'));
+    node --input-type=module -e "
+      import { readFileSync, writeFileSync } from 'fs';
+      const s = JSON.parse(readFileSync('$STATUS_FILE', 'utf8'));
       s.updated_at = new Date().toISOString();
       s.flags.stop_requested = true;
       s.flags.background_active = false;
       s.status = 'stopping';
-      fs.writeFileSync('$STATUS_FILE', JSON.stringify(s, null, 2) + '\n');
+      writeFileSync('$STATUS_FILE', JSON.stringify(s, null, 2) + '\n');
       console.log('Stop requested for run: ' + s.run_id);
     " 2>/dev/null || echo "Could not update state."
   else
@@ -24,4 +28,4 @@ if [ -f "$STATUS_FILE" ]; then
   fi
 else
   echo "No active run."
-fi
+fi

package/hooks/verify-package.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+PACK_JSON="$TMP_DIR/npm-pack-dry-run.json"
+npm pack --dry-run --json --ignore-scripts > "$PACK_JSON"
+
+node --input-type=module - "$PACK_JSON" <<'NODE'
+import fs from "fs";
+
+const packJsonPath = process.argv[2];
+const raw = fs.readFileSync(packJsonPath, "utf8");
+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 requiredFiles = [
+  ".opencode-plugin/plugin.json",
+  "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 isAllowed = (filePath) => {
+  if (allowedFiles.has(filePath)) return true;
+  const [root] = filePath.split("/");
+  return allowedRoots.has(root);
+};
+
+const violations = [];
+const packageJson = JSON.parse(fs.readFileSync("package.json", "utf8"));
+
+if (packageJson.bin?.["opencode-autoresearch"] !== "dist/cli.js") {
+  violations.push("package.json bin.opencode-autoresearch must be dist/cli.js for npm global installs");
+}
+
+if (packageJson.repository?.url !== "git+https://github.com/Maleick/AutoResearch.git") {
+  violations.push("package.json repository.url must use the npm-normalized git+https URL");
+}
+
+for (const file of files) {
+  const filePath = normalizePath(String(file.path || ""));
+  if (!filePath) continue;
+
+  if (isForbidden(filePath)) {
+    violations.push(`${filePath} is runtime state and must not be published`);
+  } else if (!isAllowed(filePath)) {
+    violations.push(`${filePath} is not in the package allowlist`);
+  }
+}
+
+if (files.length === 0) {
+  violations.push("npm pack dry-run returned no package files");
+}
+
+const packagedPaths = new Set(files.map((file) => normalizePath(String(file.path || ""))).filter(Boolean));
+for (const requiredFile of requiredFiles) {
+  if (!packagedPaths.has(requiredFile)) {
+    violations.push(`${requiredFile} is required in the package`);
+  }
+}
+
+if (violations.length > 0) {
+  console.error("FAIL: npm package contains unexpected files:");
+  for (const violation of violations) {
+    console.error(`- ${violation}`);
+  }
+  process.exit(1);
+}
+
+console.log(`Package dry-run verified ${files.length} files`);
+NODE

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-autoresearch",
-  "version": "3.1.0",
-  "description": "Auto Research for OpenCode. Subagent-first autonomous iteration loop with standing-pool orchestration and mechanical verification.",
+  "version": "3.3.1",
+  "description": "Autonomous recursive self-improvement engine for OpenCode. Subagent-first iteration loop with standing-pool orchestration and mechanical verification.",
   "author": {
     "name": "Maleick",
     "url": "https://github.com/Maleick"
@@ -11,36 +11,57 @@
     "type": "git",
     "url": "git+https://github.com/Maleick/AutoResearch.git"
   },
+  "bugs": {
+    "url": "https://github.com/Maleick/AutoResearch/issues"
+  },
   "license": "MIT",
   "keywords": [
     "opencode",
     "plugin",
     "autoresearch",
     "automation",
-    "workflows"
+    "workflows",
+    "self-improvement",
+    "iteration"
   ],
   "type": "module",
-  "main": "dist/index.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "bin": {
-    "autoresearch": "dist/cli.js"
+    "autoresearch": "dist/cli.js",
+    "opencode-autoresearch": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
-    "dist/",
-    "commands/",
-    "skills/",
-    "hooks/",
-    "docs/",
-    ".opencode-plugin/"
+    "dist",
+    "hooks",
+    "commands",
+    "skills",
+    "plugins",
+    "docs",
+    ".opencode-plugin",
+    "AGENTS.md",
+    "VERSION",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "pack": "npm pack --dry-run",
-    "lint": "echo 'TODO: add lint'"
+    "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"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9",
     "typescript": "^5.9.3"
   },
   "engines": {

package/plugins/autoresearch.ts

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

package/skills/autoresearch/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: autoresearch
-description: "Run a subagent-first structured improve-verify loop in OpenCode. Activate with /autoresearch or specialized modes like /autoresearch:plan, /autoresearch:debug, /autoresearch:fix, /autoresearch:learn, /autoresearch:predict, /autoresearch:scenario, /autoresearch:security, /autoresearch:ship."
+description: "Run a subagent-first structured improve-verify loop in OpenCode. Activate with /autoresearch or specialized modes like /autoresearch:plan, /autoresearch:debug, /autoresearch:fix, /autoresearch:learn, /autoresearch:predict, /autoresearch:scenario, /autoresearch:security, /autoresearch:ship. Supports recursive self-improvement loops."
 metadata:
-  short-description: "Subagent-first autonomous iteration loop for OpenCode"
+  short-description: "Subagent-first autonomous iteration loop for OpenCode with recursive self-improvement"
 ---
 
 # Auto Research for OpenCode
@@ -18,7 +18,8 @@ When invoked:
 3. Read `references/subagent-orchestration.md`
 4. For new interactive runs, read `references/interaction-wizard.md`, `references/plan-workflow.md`, and `references/loop-workflow.md`
 5. For state and results semantics, read `references/state-management.md` and `references/results-logging.md`
-6. For specialized modes, read the matching workflow reference:
+6. For self-improvement and recursive loops, read `references/self-improve-loop.md`
+7. For specialized modes, read the matching workflow reference:
    - `references/debug-workflow.md`
    - `references/fix-workflow.md`
    - `references/learn-workflow.md`
@@ -37,6 +38,27 @@ The main agent is the orchestrator. Subagents are the standing execution pool.
 - The main agent owns the final decision, the edit, and the run state.
 - Approval belongs before launch. After launch, continue by default unless the user stops the run.
 
+## Recursive Self-Improvement
+
+Auto Research can run on itself:
+
+```mermaid
+flowchart TD
+    A[Meta-Goal] --> B[Child Loop]
+    B --> C[Evaluate]
+    C --> D{Improve?}
+    D -->|yes| E[Learn + Memory]
+    D -->|no| F[Adapt Strategy]
+    E --> G[Next Child]
+    F --> G
+    G --> B
+```
+
+- Use `references/self-improve-loop.md` for recursive run semantics.
+- Meta-iterations spawn child loops that inherit the meta-goal.
+- Patterns extracted from child results guide strategy adaptation.
+- Memory persists across meta-iterations in `autoresearch-memory.md`.
+
 ## Required Internal Fields
 
 Infer or confirm before launching:
@@ -61,6 +83,7 @@ Strongly recommended:
 5. Record every iteration before the next one starts.
 6. Keep strict improvements, discard regressions.
 7. Continue until the stop condition is met.
+8. For self-improvement runs, archive state before each meta-iteration.
 
 ## Background Control
 
@@ -74,4 +97,6 @@ autoresearch complete
 
 ## Output
 
-Follow `references/structured-output-spec.md`. Print a setup summary before the first iteration, short progress updates during the loop, and a completion summary when done.
+Follow `references/structured-output-spec.md`. Print a setup summary before the first iteration, short progress updates during the loop, and a completion summary when done.
+
+For recursive runs, emit meta-iteration summaries in addition to standard progress.

package/skills/autoresearch/references/core-principles.md

@@ -13,8 +13,8 @@ The loop exists to make disciplined progress, not noisy activity.
 
 ## Artifact Discipline
 
-- `autoresearch-state.json` is the current run snapshot.
-- `research-results.tsv` is the append-only experiment log.
-- `autoresearch-launch.json` is the last background launch request.
+- `.autoresearch/state.json` is the current run snapshot.
+- `autoresearch-results.tsv` is the append-only experiment log.
+- `.autoresearch/launch.json` is the last background launch request.
 
 Only helper scripts should mutate these files when possible.

package/skills/autoresearch/references/interaction-wizard.md

@@ -14,7 +14,7 @@ Confirm or infer:
 6. Should the run stay in `foreground` or move to `background`?
 7. Which standing subagent pool should stay active for the run?
 
-Use `python scripts/autoresearch_wizard.py` to build the first setup summary, then only ask about fields that are still missing or risky.
+Use `autoresearch wizard` to build the first setup summary, then only ask about fields that are still missing or risky.
 
 ## Launch Rule
 

package/skills/autoresearch/references/loop-workflow.md

@@ -4,10 +4,10 @@
 
 1. Read the relevant code and repo configuration.
 2. Read `references/subagent-orchestration.md` so the standing subagent pool and task split are clear before the first iteration.
-3. Generate the initial setup summary with `scripts/autoresearch_wizard.py` when the request is incomplete.
+3. Generate the initial setup summary with `autoresearch wizard` when the request is incomplete.
 4. Summarize the goal, scope, metric, direction, verify command, guard, and subagent plan.
 5. Ask one grounded clarification round if needed.
-6. Initialize artifacts with `scripts/autoresearch_init_run.py`.
+6. Initialize artifacts with `autoresearch init`.
 
 ## Phase 2: Iterate
 
@@ -19,7 +19,7 @@ For each iteration:
 4. Run verify and guard commands.
 5. Feed subagent findings back into the next iteration plan.
 6. Keep or discard the experiment.
-7. Record the outcome with `scripts/autoresearch_record_iteration.py`.
+7. Record the outcome with `autoresearch record`.
 
 ## Phase 3: Decide
 
@@ -32,4 +32,4 @@ Stop when:
 
 Once the user approves launch, continue by default until one of those stop conditions is true. Do not restart the approval cycle on every pass; re-anchor the same standing pool and keep iterating.
 
-Background supervisors should use `scripts/autoresearch_supervisor_status.py` to make the relaunch decision from the same artifacts.
+Background supervisors should use `autoresearch status` to make the relaunch decision from the same artifacts.

package/skills/autoresearch/references/plan-workflow.md

@@ -1,6 +1,6 @@
 # Plan Workflow
 
-Use this when the user invokes `$codex-autoresearch` without a complete setup or explicitly asks for a wizard.
+Use this when the user invokes `/autoresearch:plan` without a complete setup or explicitly asks for a wizard.
 
 ## Goal
 
@@ -19,7 +19,7 @@ Turn a vague request into a launch-ready setup summary with:
 
 1. Read the repo before asking anything.
 2. Infer defaults where the repo makes them obvious.
-3. Generate the setup summary with `python scripts/autoresearch_wizard.py`.
+3. Generate the setup summary with `autoresearch wizard`.
 4. Ask only the missing or risky questions.
 5. Let the user correct the setup once before launch.
 6. If the user approves, initialize artifacts and start the loop.
@@ -38,5 +38,5 @@ Ask these in order when missing:
 ## Defaults
 
 - If the repo has `pytest.ini` or a `tests/` directory, default `verify` to `pytest`.
-- If the repo contains `scripts/autoresearch_supervisor_status.py`, offer it as the default guard.
+- If the repo contains `autoresearch status`, offer it as the default guard.
 - Default metric direction to `lower` unless the user clearly wants to maximize a score.

package/skills/autoresearch/references/results-logging.md

@@ -1,8 +1,8 @@
 # Results Logging
 
-`research-results.tsv` is the primary append-only results log per run.
+`autoresearch-results.tsv` is the primary append-only results log per run.
 
-For Claude compatibility, the runtime also maintains `autoresearch-results.tsv` as a synchronized alias.
+The runtime maintains `autoresearch-results.tsv` as the canonical iteration log.
 
 ## Required Columns