opencode-autoresearch 3.1.0-beta.2

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+export interface RunConfig {
+    goal: string;
+    metric: string;
+    direction: string;
+    verify: string;
+    mode: string;
+    scope?: string;
+    guard?: string;
+    iterations?: number;
+    duration?: string;
+    memory_path?: string;
+    required_keep_labels?: string[];
+    required_stop_labels?: string[];
+    run_tag?: string;
+    stop_condition?: string;
+    baseline?: string;
+}
+export interface WizardConfig {
+    goal?: string;
+    scope?: string;
+    metric?: string;
+    direction?: string;
+    verify?: string;
+    guard?: string;
+    mode?: string;
+    iterations?: number;
+    duration?: string;
+    memory_path?: string;
+    required_keep_labels?: string[];
+    required_stop_labels?: string[];
+    stop_condition?: string;
+    rollback_strategy?: string;
+}
+export interface Metric {
+    name: string;
+    direction: string;
+    baseline?: string;
+    best?: string;
+    latest?: string;
+}
+export interface RunStats {
+    total_iterations: number;
+    kept: number;
+    discarded: number;
+    needs_human: number;
+    consecutive_discards: number;
+    best_iteration?: number;
+}
+export interface RunFlags {
+    stop_requested: boolean;
+    needs_human: boolean;
+    background_active: boolean;
+    stop_ready: boolean;
+}
+export interface LastIteration {
+    iteration: number;
+    decision: string;
+    metric_value?: string;
+    change_summary: string;
+    labels: string[];
+    timestamp: string;
+    keep_labels_satisfied: boolean;
+    stop_labels_satisfied: boolean;
+    missing_keep_labels: string[];
+    missing_stop_labels: string[];
+}
+export interface RunState {
+    schema_version: number;
+    run_id: string;
+    created_at: string;
+    updated_at: string;
+    status: string;
+    mode: string;
+    goal: string;
+    scope: string;
+    metric: Metric;
+    verify: string;
+    guard?: string;
+    iterations_cap?: number;
+    duration?: string;
+    duration_seconds?: number;
+    deadline_at?: string;
+    memory?: Record<string, unknown>;
+    subagent_pool?: Record<string, unknown>;
+    continuation_policy?: Record<string, unknown>;
+    label_requirements: {
+        keep: string[];
+        stop: string[];
+    };
+    stop_condition?: string;
+    artifact_paths: {
+        results: string;
+        state: string;
+    };
+    stats: RunStats;
+    flags: RunFlags;
+    last_iteration?: LastIteration;
+}
+export interface SupervisorSnapshot {
+    decision: string;
+    reason: string;
+    run_id: string;
+    status: string;
+    mode: string;
+    goal: string;
+    metric: Metric;
+    stats: RunStats;
+    last_iteration?: LastIteration;
+    results_rows: number;
+    artifact_paths: Record<string, string>;
+    flags: RunFlags;
+    label_requirements: Record<string, string[]>;
+    subagent_pool?: Record<string, unknown>;
+    continuation_policy?: Record<string, unknown>;
+    subagent_guidance?: Record<string, unknown>;
+}
+export interface Result {
+    timestamp: string;
+    iteration: string;
+    decision: string;
+    metric_value: string;
+    verify_status: string;
+    guard_status: string;
+    hypothesis: string;
+    change_summary: string;
+    labels: string;
+    note: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/wizard.d.ts

@@ -0,0 +1,3 @@
+import type { WizardConfig } from "./types.js";
+export declare function buildSetupSummary(repo: string | undefined, config: WizardConfig): Record<string, unknown>;
+//# sourceMappingURL=wizard.d.ts.map

package/dist/wizard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.d.ts","sourceRoot":"","sources":["../src/wizard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAW/C,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,EAAE,YAAY,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiDzB"}

package/dist/wizard.js

@@ -0,0 +1,56 @@
+import { resolveRepo, normalizeDirection, normalizeMode, parseDurationSeconds, normalizeLabels, inferVerifyCommand, } from "./helpers.js";
+import { buildSubagentPoolPlan, buildContinuationPolicy } from "./subagent-pool.js";
+export function buildSetupSummary(repo, config) {
+    const verify = config.verify ?? inferVerifyCommand(repo);
+    const direction = normalizeDirection(config.direction);
+    const mode = normalizeMode(config.mode);
+    const durationSeconds = parseDurationSeconds(config.duration);
+    const scope = config.scope ?? resolveRepo(repo).split("/").pop() ?? "current repository";
+    const subagentPool = buildSubagentPoolPlan({
+        goal: config.goal ?? "pending",
+        scope,
+        mode: config.mode ?? "foreground",
+    });
+    const continuationPolicy = buildContinuationPolicy(mode);
+    const missingRequired = [];
+    if (!config.goal)
+        missingRequired.push("goal");
+    if (verify === "<set verify command>")
+        missingRequired.push("verify");
+    const stopReasons = [];
+    if (verify !== "<set verify command>") {
+        stopReasons.push(`\`${verify}\` reaches the target metric`);
+    }
+    if (config.iterations != null)
+        stopReasons.push(`${config.iterations} iterations complete`);
+    if (config.duration)
+        stopReasons.push(`${config.duration} elapses`);
+    const questions = [];
+    if (!config.goal)
+        questions.push({ id: "goal", prompt: "What outcome should this run optimize for?", reason: "The loop needs one concrete result to chase." });
+    if (!config.verify)
+        questions.push({ id: "verify", prompt: "What command should mechanically verify the metric?", reason: "The loop should not keep changes on intuition alone." });
+    if (!config.mode)
+        questions.push({ id: "mode", prompt: "Should the run stay in `foreground` or move to `background`?", reason: "The skill requires an explicit run-mode choice." });
+    return {
+        goal: config.goal,
+        scope,
+        metric: config.metric ?? "primary verify metric",
+        direction,
+        verify,
+        guard: config.guard,
+        mode,
+        iterations_cap: config.iterations,
+        duration: config.duration,
+        duration_seconds: durationSeconds,
+        subagent_pool: subagentPool,
+        continuation_policy: continuationPolicy,
+        required_keep_labels: normalizeLabels(config.required_keep_labels ?? []),
+        required_stop_labels: normalizeLabels(config.required_stop_labels ?? []),
+        stop_condition: config.stop_condition ?? `stop when ${stopReasons.join(" or ")}`,
+        rollback_strategy: config.rollback_strategy ?? "discard current experiment and keep last verified state",
+        missing_required: missingRequired,
+        questions,
+    };
+}
+//# sourceMappingURL=wizard.js.map

package/dist/wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.js","sourceRoot":"","sources":["../src/wizard.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+# Auto Research Architecture
+
+> Current reference for v3.1.0.
+
+Auto Research is now an OpenCode-only npm package. The runtime is Node.js ESM. All workflow semantics are preserved from earlier releases.
+
+## Package layout
+
+```text
+src/index.ts                   # Main plugin entry
+src/cli.ts                    # CLI entry point
+src/constants.ts              # Package constants (version, names, paths)
+src/types.ts                  # TypeScript type definitions
+src/helpers.ts                # Runtime helpers (state, results, paths)
+src/wizard.ts                 # Setup wizard
+src/subagent-pool.ts           # Subagent pool builder
+src/run-manager.ts             # Run lifecycle (init, record, status, stop, resume, complete)
+commands/autoresearch.md        # Main command
+commands/autoresearch/*.md     # Mode commands (plan, debug, fix, learn, etc.)
+skills/autoresearch/            # OpenCode skill bundle
+skills/autoresearch/references/ # Workflow and runtime references
+hooks/init.sh                 # SessionStart hook
+hooks/status.sh               # Status hook
+hooks/stop.sh                # Stop hook
+docs/OPENCODE_INSTALL.md      # OpenCode install guide
+docs/RELEASE.md              # Release process
+.opencode-plugin/plugin.json  # OpenCode plugin manifest
+.autoresearch/                # Runtime state directory (created at runtime)
+```
+
+## Source of truth
+
+`src/` is authoritative for runtime behavior. `commands/` and `skills/` define the OpenCode surfaces.
+
+## Runtime artifacts
+
+| Artifact | Purpose |
+| --- | --- |
+| `.autoresearch/state.json` | Current run checkpoint |
+| `autoresearch-results.tsv` | Iteration log |
+| `autoresearch-launch.json` | Background launch request |
+| `autoresearch-report.md` | End-of-run report |
+| `autoresearch-memory.md` | Reusable run memory |
+
+## Command surface
+
+| Command | Workflow |
+| --- | --- |
+| `/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 launch` | Launch background run |
+| `autoresearch stop` | Request stop |
+| `autoresearch resume` | Resume background run |
+| `autoresearch complete` | Mark run complete |
+| `autoresearch record` | Record iteration result |
+
+## Subagent pool
+
+The standing pool provides: orchestrator, scout, analyst, verifier, synthesizer, and role-specialized variants (security_reviewer, debugger, release_guard, research_tracker). The pool is reused across iterations unless drift or repeated discards force a reset.
+
+## Validation
+
+1. `npm run typecheck` — TypeScript strict checks.
+2. `npm pack --dry-run` — Package contents preview.
+3. Package install and `autoresearch doctor` verification.
+
+## Migration from earlier releases
+
+- Results log is now `autoresearch-results.tsv` only (dropped `research-results.tsv`).
+- State is now in `.autoresearch/state.json` (was `autoresearch-state.json` at root).
+- Runtime helpers are TypeScript (`src/helpers.ts`) not Python.
+- Plugin format is `.opencode-plugin/plugin.json`.
+- The Claude and Codex plugin bundles (`plugins/autoresearch/`, `plugins/codex-autoresearch/`) are no longer shipped.

package/docs/CNAME

@@ -0,0 +1 @@
+autoresearch.teamoperator.red

package/docs/OPENCODE_INSTALL.md

@@ -0,0 +1,48 @@
+# OpenCode Install
+
+Install `opencode-autoresearch` as a global npm package.
+
+## Install
+
+```bash
+npm install -g opencode-autoresearch
+```
+
+## Verify Installation
+
+```bash
+opencode-autoresearch doctor
+```
+
+Should print the package version and confirm the plugin surfaces are in place.
+
+## OpenCode Plugin Registration
+
+After install, the plugin is available as `autoresearch`:
+
+- `/autoresearch` — Run the main 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
+
+## Runtime Artifacts
+
+After install, artifacts are stored in `.autoresearch/` under the working directory:
+
+| Artifact | Purpose |
+| --- | --- |
+| `.autoresearch/state.json` | Current run state |
+| `autoresearch-results.tsv` | Iteration log |
+| `autoresearch-report.md` | End-of-run report |
+| `autoresearch-memory.md` | Reusable memory |
+
+## Uninstall
+
+```bash
+npm uninstall -g opencode-autoresearch
+```

package/docs/RELEASE.md

@@ -0,0 +1,67 @@
+# Release Process
+
+This package uses npm publish for releases.
+
+## Version Alignment
+
+`VERSION` in `src/constants.ts` and `version` in `package.json` must stay aligned. The `package.json` version is the canonical source of truth for npm.
+
+## Release Steps
+
+### 1. Update version
+
+Bump the version in `package.json` and `src/constants.ts`.
+
+```bash
+# Update package.json
+npm version patch  # or minor, major
+
+# Sync to src/constants.ts
+sed -i '' 's/"3\.\([0-9]\+\)\.[0-9]*"/"3.\1.\1"/' src/constants.ts
+```
+
+### 2. Build
+
+```bash
+npm run build
+```
+
+### 3. Test
+
+```bash
+npm run typecheck
+```
+
+### 4. Dry-run pack
+
+```bash
+npm pack --dry-run
+```
+
+Verify the output includes: `dist/`, `commands/`, `skills/`, `hooks/`, `docs/`, `.opencode-plugin/`.
+
+### 5. Publish
+
+```bash
+npm publish
+```
+
+### 6. Tag
+
+```bash
+git tag v$(node -p "require('./package.json').version")
+git push origin v$(node -p "require('./package.json').version")
+```
+
+## Package Contents
+
+The shipped package includes:
+
+- `dist/` — Compiled TypeScript (CLI entry point, helpers, subagent pool, run manager)
+- `commands/` — OpenCode command surfaces (`autoresearch.md`, `autoresearch/*.md`)
+- `skills/autoresearch/` — Skill bundle with references
+- `hooks/` — Shell hooks for session lifecycle
+- `docs/` — Installation and architecture docs
+- `.opencode-plugin/plugin.json` — Plugin manifest
+
+Python scripts are **not** included in the shipped package.

package/docs/autoresearch-loop.svg

@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 400" width="1200" height="400">
+  <defs>
+    <style>
+      .ui { font-family: 'Segoe UI', system-ui, sans-serif; }
+      .mono { font-family: 'Cascadia Code', 'Fira Code', monospace; }
+    </style>
+    <marker id="arr" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="context-stroke"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="400" fill="#0d1117"/>
+
+  <!-- Section dividers -->
+  <line x1="390" y1="30" x2="390" y2="370" stroke="#21262d" stroke-width="1"/>
+  <line x1="830" y1="30" x2="830" y2="370" stroke="#21262d" stroke-width="1"/>
+
+  <!-- ===== LEFT: Title block ===== -->
+  <text x="56" y="138" class="ui" font-size="46" font-weight="700" fill="#e6edf3">autoresearch</text>
+  <text x="56" y="170" class="ui" font-size="14" fill="#8b949e">Cross-platform autonomous iteration engine</text>
+
+  <!-- v2.2.1 pill -->
+  <rect x="56" y="183" width="76" height="22" rx="11" fill="#1a2f1a"/>
+  <text x="94" y="198" class="ui" font-size="11" font-weight="600" fill="#30a14e" text-anchor="middle">v2.2.1</text>
+
+  <!-- Tagline -->
+  <text x="56" y="258" class="ui" font-size="15" fill="#c9d1d9">Fire it before bed.</text>
+  <text x="56" y="280" class="ui" font-size="15" fill="#c9d1d9">Review improvements in the morning.</text>
+
+  <!-- Core loop label -->
+  <text x="56" y="336" class="ui" font-size="11" fill="#58a6ff" letter-spacing="2">CORE LOOP</text>
+  <line x1="56" y1="342" x2="200" y2="342" stroke="#58a6ff" stroke-width="1" opacity="0.4"/>
+
+  <!-- ===== CENTER: Diamond loop diagram ===== -->
+  <!-- Arrow: MODIFY to VERIFY -->
+  <path d="M 658 108 Q 726 130 726 178" fill="none" stroke="#58a6ff" stroke-width="2" marker-end="url(#arr)"/>
+  <!-- Arrow: VERIFY to KEEP/DISCARD -->
+  <path d="M 726 222 Q 726 268 672 290" fill="none" stroke="#58a6ff" stroke-width="2" marker-end="url(#arr)"/>
+  <!-- Arrow: KEEP/DISCARD to REPEAT -->
+  <path d="M 548 300 Q 488 282 488 222" fill="none" stroke="#30a14e" stroke-width="2" marker-end="url(#arr)"/>
+  <!-- Arrow: REPEAT to MODIFY -->
+  <path d="M 488 178 Q 488 118 558 104" fill="none" stroke="#30a14e" stroke-width="2" marker-end="url(#arr)"/>
+
+  <!-- Node: MODIFY -->
+  <rect x="558" y="82" width="104" height="36" rx="8" fill="#161b22" stroke="#58a6ff" stroke-width="1.5"/>
+  <text x="610" y="105" class="ui" font-size="13" font-weight="700" fill="#58a6ff" text-anchor="middle">MODIFY</text>
+
+  <!-- Node: VERIFY -->
+  <rect x="674" y="182" width="104" height="36" rx="8" fill="#161b22" stroke="#58a6ff" stroke-width="1.5"/>
+  <text x="726" y="205" class="ui" font-size="13" font-weight="700" fill="#58a6ff" text-anchor="middle">VERIFY</text>
+
+  <!-- Node: KEEP / DISCARD -->
+  <rect x="524" y="282" width="172" height="36" rx="8" fill="#161b22" stroke="#30a14e" stroke-width="1.5"/>
+  <text x="610" y="300" class="ui" font-size="12" font-weight="700" fill="#30a14e" text-anchor="middle">KEEP</text>
+  <text x="610" y="313" class="ui" font-size="10" fill="#6e7681" text-anchor="middle">or discard + reset</text>
+
+  <!-- Node: REPEAT -->
+  <rect x="438" y="182" width="104" height="36" rx="8" fill="#161b22" stroke="#30a14e" stroke-width="1.5"/>
+  <text x="490" y="205" class="ui" font-size="13" font-weight="700" fill="#30a14e" text-anchor="middle">REPEAT</text>
+
+  <!-- Center label -->
+  <text x="610" y="194" class="ui" font-size="11" fill="#6e7681" text-anchor="middle">autonomous</text>
+  <text x="610" y="210" class="ui" font-size="11" fill="#6e7681" text-anchor="middle">loop</text>
+
+  <!-- ===== RIGHT: Terminal window ===== -->
+  <rect x="858" y="56" width="306" height="288" rx="10" fill="#161b22" stroke="#30363d" stroke-width="1"/>
+  <!-- Title bar: top-rounded only via path -->
+  <path d="M 868 56 Q 858 56 858 66 L 858 90 L 1164 90 L 1164 66 Q 1164 56 1154 56 Z" fill="#21262d"/>
+  <!-- Traffic lights -->
+  <circle cx="882" cy="73" r="5.5" fill="#ff5f57"/>
+  <circle cx="902" cy="73" r="5.5" fill="#ffbd2e"/>
+  <circle cx="922" cy="73" r="5.5" fill="#28c840"/>
+  <!-- Window title -->
+  <text x="1011" y="77" class="ui" font-size="11" fill="#6e7681" text-anchor="middle">autoresearch</text>
+
+  <!-- Column headers -->
+  <text x="874" y="116" class="mono" font-size="11" fill="#6e7681">iter   metric   result</text>
+  <line x1="874" y1="122" x2="1148" y2="122" stroke="#30363d" stroke-width="1"/>
+
+  <!-- Iteration rows -->
+  <text x="874" y="142" class="mono" font-size="11" fill="#30a14e">001    94.2     ✓ keep</text>
+  <text x="874" y="160" class="mono" font-size="11" fill="#f85149">002    93.8     ✗ discard</text>
+  <text x="874" y="178" class="mono" font-size="11" fill="#30a14e">003    96.1     ✓ keep</text>
+  <text x="874" y="196" class="mono" font-size="11" fill="#30a14e">004    97.4     ✓ keep</text>
+  <text x="874" y="214" class="mono" font-size="11" fill="#f85149">005    97.1     ✗ discard</text>
+  <text x="874" y="232" class="mono" font-size="11" fill="#30a14e">006    99.0     ✓ keep</text>
+  <text x="874" y="250" class="mono" font-size="11" fill="#6e7681">007    ...</text>
+
+  <!-- Best metric footer bar -->
+  <rect x="858" y="292" width="306" height="52" fill="#0d2818"/>
+  <rect x="867" y="300" width="3" height="28" rx="1.5" fill="#30a14e"/>
+  <text x="880" y="314" class="mono" font-size="11" fill="#30a14e">best: 99.0  (+5.1%)  4 kept</text>
+  <text x="880" y="330" class="mono" font-size="11" fill="#6e7681">→ autoresearch-report.md</text>
+</svg>