opencode-autoresearch 3.1.0 → 3.3.0

package/.opencode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "autoresearch",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Auto Research for OpenCode. Run a structured autonomous iteration loop with a standing subagent pool.",
   "author": {
     "name": "Maleick",

package/AGENTS.md

@@ -0,0 +1,42 @@
+# Auto Research Agent Guide
+
+Auto Research is an OpenCode-only autonomous iteration engine with recursive self-improvement capabilities.
+
+## Runtime Policy
+
+- 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.
+
+## Local State
+
+`.autoresearch/` is runtime state and must not be committed.
+
+## Verification
+
+Before claiming work is complete, run:
+
+```bash
+npm run typecheck
+npm run build
+npm run verify:pack
+```
+
+## 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/README.md

@@ -1,43 +1,197 @@
 # Auto Research
 
-[![GitHub Release](https://img.shields.io/github/v/release/Maleick/AutoResearch?style=flat-square&label=release)](https://github.com/Maleick/AutoResearch/releases)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
-[![Runtime](https://img.shields.io/badge/runtime-OpenCode-0F766E?style=flat-square)](.)
+<p align="center">
+  <img src="assets/autoresearch-banner.svg" width="900" alt="Auto Research — Autonomous recursive self-improvement engine" />
+</p>
 
-> **v3.1.0** — OpenCode-only npm package
+<p align="center">
+  <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>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/Maleick/AutoResearch?style=flat" alt="License"></a>
+  <a href="https://autoresearch.teamoperator.red"><img src="https://img.shields.io/badge/docs-autoresearch.teamoperator.red-blue?style=flat" alt="Docs"></a>
+</p>
 
-Auto Research is a subagent-first autonomous iteration engine for OpenCode. It keeps the existing `/autoresearch` command surface intact and adds specialized mode workflows.
+<p align="center">
+  <a href="https://autoresearch.teamoperator.red">Docs</a> •
+  <a href="https://github.com/Maleick/AutoResearch/wiki">Wiki</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#runtime">Runtime</a> •
+  <a href="#self-improvement-loop">Self-Improvement</a>
+</p>
 
-Inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch). The core loop is still the same:
+<p align="center"><strong>Autonomous recursive self-improvement engine for OpenCode.</strong></p>
 
-**Modify -> Verify -> Keep or Discard -> Repeat**
+```text
+┌──────────────────────────────────────────────┐
+│  ITERATION MODEL        Subagent-first        │
+│  ORCHESTRATION          Standing pool         │
+│  VERIFICATION           Mechanical metrics    │
+│  PERSISTENCE            State + Memory        │
+│  META-LEARNING          Strategy adaptation   │
+└──────────────────────────────────────────────┘
+```
 
-## Runtime surfaces
+## What It Does
 
-| Surface | Entry point |
-| --- | --- |
-| OpenCode | `/autoresearch`, `/autoresearch:plan`, `/autoresearch:debug`, `/autoresearch:fix`, `/autoresearch:learn`, `/autoresearch:predict`, `/autoresearch:scenario`, `/autoresearch:security`, `/autoresearch:ship` |
+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.
+
+- **Plans** experiments from a measurable goal
+- **Modifies** one focused change per iteration
+- **Verifies** mechanically — never on intuition alone
+- **Keeps or discards** based on strict metric improvement
+- **Learns** from patterns across iterations
+- **Repeats** until the stop condition is met
+
+## The Core Loop
+
+```mermaid
+flowchart LR
+    A[Plan] --> B[Modify]
+    B --> C[Verify]
+    C --> D{Keep?}
+    D -->|yes| E[Learn]
+    D -->|no| B
+    E --> F[Memory]
+    F --> A
+```
+
+```mermaid
+flowchart TD
+    A[Goal + Metric + Verify] --> B[Baseline]
+    B --> C[Standing Pool Init]
+    C --> D[Iteration N]
+    D --> E[Subagent Context]
+    E --> F[Focused Change]
+    F --> G[Mechanical Verify]
+    G --> H{Strict Improvement?}
+    H -->|yes| I[Keep + Record]
+    H -->|no| J[Discard + Reset]
+    I --> K{Stop Condition?}
+    J --> K
+    K -->|no| D
+    K -->|yes| L[Report + Memory]
+```
+
+## The Self-Improvement Loop
+
+Auto Research can run on itself. The recursive loop adds a meta-orchestrator that:
+
+```mermaid
+flowchart TD
+    A[Meta-Goal: Improve AutoResearch] --> B[Run Child Loop]
+    B --> C[Measure: Tests pass? Docs improved?]
+    C --> D{Child Success?}
+    D -->|yes| E[Update Memory + Strategy]
+    D -->|no| F[Adapt Approach]
+    E --> G[Persist Learnings]
+    F --> B
+    G --> H[Meta-Report]
+    H --> I{Meta-Stop?}
+    I -->|no| B
+    I -->|yes| J[Archive Run]
+```
 
-## Install
+See [`skills/autoresearch/references/self-improve-loop.md`](skills/autoresearch/references/self-improve-loop.md) for the full recursive loop specification.
+
+## Installation
+
+Install the CLI globally if you want Auto Research available long-term on your PATH:
 
 ```bash
 npm install -g opencode-autoresearch
 opencode-autoresearch doctor
 ```
 
-See [docs/OPENCODE_INSTALL.md](docs/OPENCODE_INSTALL.md) for full install and verification steps.
+For a one-time install without keeping a global CLI, use `bunx` instead:
+
+```bash
+bunx opencode-autoresearch install
+bunx opencode-autoresearch doctor
+```
+
+Then start the setup wizard inside OpenCode:
+
+```text
+/autoresearch
+```
+
+## Quick Start
 
-## Core loop
+```bash
+# 1. Install the CLI globally
+npm install -g opencode-autoresearch
+
+# 2. Verify installation
+opencode-autoship doctor
 
-Auto Research requires a goal, scope, and a mechanical verification command. It then:
+# 3. Navigate to your project
+cd ~/Projects/my-project
 
-1. Baselines the current state.
-2. Makes one focused experiment.
-3. Verifies it mechanically.
-4. Keeps strict improvements and discards regressions.
-5. Records the result and continues until the stop condition is met.
+# 4. Start Auto Research in OpenCode
+/autoresearch
+```
 
-## Runtime artifacts
+## Runtime Surfaces
+
+| Surface | Entry point |
+| --- | --- |
+| OpenCode | `/autoresearch`, `/autoresearch:plan`, `/autoresearch:debug`, `/autoresearch:fix`, `/autoresearch:learn`, `/autoresearch:predict`, `/autoresearch:scenario`, `/autoresearch:security`, `/autoresearch:ship` |
+
+## 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 |
+
+## CLI Commands
+
+| Command | Purpose |
+| --- | --- |
+| `autoresearch init` | Initialize a run |
+| `autoresearch wizard` | Generate setup summary |
+| `autoresearch status` | Print run status |
+| `autoresearch explain` | Human-readable run state |
+| `autoresearch history` | Show recent iteration log |
+| `autoresearch config` | Show runtime configuration |
+| `autoresearch report` | Generate markdown report |
+| `autoresearch summary` | Aggregate stats across runs |
+| `autoresearch suggest` | Suggest next goal from memory |
+| `autoresearch launch` | Launch background run |
+| `autoresearch stop` | Request stop |
+| `autoresearch resume` | Resume background run |
+| `autoresearch complete` | Mark run complete |
+| `autoresearch record` | Record iteration result |
+| `autoresearch export` | Export run data (json/md) |
+| `autoresearch completion` | Generate shell completions |
+| `autoresearch doctor` | Verify installation |
+| `autoresearch help` | Show usage |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[OpenCode /autoresearch] --> B[CLI]
+    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]
+```
+
+## Runtime Artifacts
 
 | Artifact | Purpose |
 | --- | --- |
@@ -45,24 +199,81 @@ Auto Research requires a goal, scope, and a mechanical verification command. It
 | `autoresearch-results.tsv` | Iteration log |
 | `autoresearch-report.md` | End-of-run report |
 | `autoresearch-memory.md` | Reusable memory for later runs |
+| `.autoresearch/launch.json` | Background launch manifest |
+
+## Self-Improvement Mode
+
+Run Auto Research on its own codebase:
+
+```bash
+# Initialize a recursive self-improvement run
+autoresearch init \
+  --goal "Improve test coverage and documentation" \
+  --metric "coverage_pct" \
+  --direction "higher" \
+  --verify "npm run test:coverage" \
+  --guard "npm run typecheck" \
+  --mode "background" \
+  --iterations "20"
+
+# Check status
+autoresearch status
+
+# Resume if stopped
+autoresearch resume
+```
+
+The self-improvement loop:
+1. Baselines current state (tests, docs, metrics)
+2. Dispatches subagents to identify improvement opportunities
+3. Makes one focused change per iteration
+4. Verifies mechanically (tests, typechecks, lint)
+5. Keeps strict improvements, discards regressions
+6. Records patterns to `autoresearch-memory.md`
+7. Adapts strategy when repeated discards occur
+8. Continues until iteration cap or goal met
+
+## Subagent Pool
+
+The standing pool provides specialized roles reused across iterations:
+
+| Role | Purpose |
+| --- | --- |
+| `orchestrator` | Owns goal, state, and keep/discard decisions |
+| `scout` | Gathers context and surfaces opportunities |
+| `analyst` | Challenges hypotheses and identifies risks |
+| `verifier` | Runs mechanical verification independently |
+| `synthesizer` | Compiles findings into next iteration plan |
+| `security_reviewer` | Security-focused review variant |
+| `debugger` | Debug workflow specialization |
+| `release_guard` | Ship-readiness verification |
+| `research_tracker` | Pattern tracking across iterations |
 
 ## Development
 
 ```bash
-npm run typecheck   # Type check the TypeScript sources
+npm run typecheck   # TypeScript strict checks
 npm run build       # Compile TypeScript to dist/
-npm pack --dry-run # Preview shipped package contents
+npm run test        # Run test suite
+npm pack --dry-run  # Preview shipped package contents
 ```
 
-## Repository layout
+## Repository Layout
 
 ```text
-src/                          # TypeScript source (runtime helpers, CLI, subagent pool)
-dist/                         # Compiled JavaScript output
-commands/                     # OpenCode command surfaces
+src/                           # TypeScript source (runtime helpers, CLI, subagent pool)
+dist/                          # Compiled JavaScript output
+commands/                      # OpenCode command surfaces
 skills/autoresearch/           # Skill bundle with references
-hooks/                        # Shell hooks for session lifecycle
-docs/                         # Install and architecture docs
+  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
+hooks/                         # Shell hooks for session lifecycle
+docs/                          # Install and architecture docs
+wiki/                          # GitHub wiki pages
 .autoresearch/                 # Runtime state directory
 .opencode-plugin/              # Plugin manifest
 ```
@@ -71,4 +282,9 @@ docs/                         # Install and architecture docs
 
 - This is an **OpenCode-only** package. No Claude or Codex runtime is supported.
 - The CLI uses Node.js ESM modules.
-- Python scripts were used in earlier releases and are no longer shipped.
+- Self-improvement loops require `--mode background` for long-running unattended operation.
+- Memory files (`autoresearch-memory.md`) are portable across runs and repositories.
+
+## License
+
+MIT — See [LICENSE](LICENSE) for details.

package/VERSION

@@ -0,0 +1 @@
+3.3.0