Skip to content

AGENTS.md

Latest commit

 

History

History
336 lines (244 loc) · 10.4 KB

AGENTS.md

File metadata and controls

336 lines (244 loc) · 10.4 KB
Raw

AGENTS.md — Autoresearch

Drop this file into your project root. Any AI agent (Claude Code, Codex, OpenCode, Gemini CLI, etc.) can then use Autoresearch immediately.

What is Autoresearch?

Autonomous goal-directed iteration based on Karpathy's autoresearch. One metric, constrained scope, fast verification, automatic rollback, git as memory. Works on ANY domain — code, content, marketing, sales, DevOps — anything with a measurable metric.

Core loop: Modify → Verify → Keep/Discard → Repeat.

Installation

Claude Code (plugin)

/plugin marketplace add uditgoenka/autoresearch
/plugin install autoresearch@autoresearch

Restart session after install. All 14 commands become available as /autoresearch and /autoresearch:<subcommand>.

Codex (plugin)

git clone https://github.com/uditgoenka/autoresearch.git
cd autoresearch
./scripts/install.sh --codex --global

Invoke via the $autoresearch mention syntax: $autoresearch <subcommand> [flags].

Manual (any agent)

Copy the skill files into your agent's skill directory:

git clone https://github.com/uditgoenka/autoresearch.git

# Claude Code
cp -r autoresearch/claude-plugin/skills/autoresearch .claude/skills/autoresearch
cp -r autoresearch/claude-plugin/commands/autoresearch .claude/commands/autoresearch
cp autoresearch/claude-plugin/commands/autoresearch.md .claude/commands/autoresearch.md

# Codex
cp -r autoresearch/plugins/autoresearch ~/.agents/plugins/autoresearch

Commands

Command Purpose
autoresearch Autonomous iteration loop (unlimited or bounded with Iterations: N)
autoresearch:plan Interactive wizard: Goal → Scope, Metric, Direction, Verify config
autoresearch:debug Autonomous bug-hunting — scientific method + iterative investigation
autoresearch:fix Autonomous error repair — one fix per iteration until zero errors
autoresearch:security STRIDE + OWASP + red-team security audit (read-only unless --fix)
autoresearch:ship Universal shipping workflow — 8 phases, 9 shipment types
autoresearch:scenario Scenario exploration — 12 dimensions, edge cases, derivative scenarios
autoresearch:predict Multi-persona swarm — 5 expert perspectives before acting
autoresearch:learn Autonomous documentation engine — scout, generate, validate, fix
autoresearch:reason Adversarial refinement — blind judge panel for subjective domains
autoresearch:probe Adversarial requirement / assumption interrogation — 8 personas probe to mechanical saturation, emits ready-to-run autoresearch config

Quick Start

Basic autonomous loop

autoresearch
Goal: Increase test coverage from 72% to 90%
Scope: src/**/*.test.ts, src/**/*.ts
Metric: coverage % (higher is better)
Verify: npm test -- --coverage | grep "All files"
Iterations: 50

Don't know what metric to use?

autoresearch:plan
Goal: Make the API respond faster

The wizard walks you through scope, metric, direction, and verify — with dry-run validation.

Hunt all bugs

autoresearch:debug
Scope: src/api/**/*.ts
Symptom: API returns 500 on POST /users
Iterations: 20

Fix all errors

autoresearch:fix

Auto-detects broken tests/types/lint/build, fixes one at a time, stops at zero errors.

Security audit

autoresearch:security
Scope: src/**/*.ts
Iterations: 10

Ship a PR

autoresearch:ship --auto

Explore edge cases

autoresearch:scenario
Scenario: User attempts checkout with expired card
Iterations: 25

Get expert opinions before acting

autoresearch:predict --chain debug
Scope: src/auth/**/*.ts

Refine a subjective decision

autoresearch:reason
Task: Should we use event sourcing for order management?
Domain: software
Iterations: 8

Configuration Fields

Field Required Description
Goal Yes What you want to achieve (plain language)
Scope Yes Glob patterns for files the agent can modify
Metric Yes What number to optimize (higher/lower + unit)
Verify Yes Shell command that outputs the metric value
Guard No Safety command that must always pass (prevents regressions)
Iterations No Bounded run — stop after N iterations (default: unlimited)
Direction No higher or lower — which direction is better

Flags

Core loop (autoresearch)

Flag Purpose
--scope <glob> Override scope
--iterations <N> Bounded iteration count

Security (autoresearch:security)

Flag Purpose
--diff Only audit changed files
--fix Auto-fix Critical/High findings
--fail-on <severity> Non-zero exit for CI/CD gating

Ship (autoresearch:ship)

Flag Purpose
--auto Auto-approve if checklist passes
--dry-run Validate without shipping
--checklist-only Just check readiness
--rollback Undo last ship
--monitor <N> Post-ship monitoring (minutes)

Debug (autoresearch:debug)

Flag Purpose
--fix After hunting, auto-switch to fix mode
--scope <glob> Limit investigation scope
--symptom "<text>" Pre-fill symptom

Fix (autoresearch:fix)

Flag Purpose
--target <command> Explicit verify command
--guard <command> Safety command
--category <type> Only fix: test, type, lint, or build
--from-debug Read findings from latest debug session

Predict (autoresearch:predict)

Flag Purpose
--chain <commands> Chain output to other commands

Reason (autoresearch:reason)

Flag Purpose
--iterations <N> Bounded rounds
--judges <N> Judge count (3-7, odd preferred)
--convergence <N> Consecutive wins to converge (default: 3)
--mode <mode> convergent, creative, debate
--domain <type> software, product, business, security, research, content
--chain <targets> Chain converged output to other commands

Learn (autoresearch:learn)

Flag Purpose
--mode <mode> init, update, check, summarize
--depth <level> shallow, standard, deep
--file <path> Update single doc

Scenario (autoresearch:scenario)

Flag Purpose
--domain <type> software, product, business, security, marketing
--depth <level> shallow, standard, deep
--format <type> use-cases, user-stories, test-scenarios, threat-scenarios
--focus <area> edge-cases, failures, security, scale

Chaining Commands

Commands can be chained with --chain:

autoresearch:debug --fix                      # debug → auto-fix
autoresearch:predict --chain debug            # predict → debug
autoresearch:predict --chain scenario,debug,fix  # full quality pipeline
autoresearch:reason --chain predict           # converge → stress-test
autoresearch:reason --chain plan,fix          # converge → implement
autoresearch:probe --chain plan,autoresearch  # interrogate → config → loop
autoresearch:probe --chain reason             # interrogate → debate → converge

8 Critical Rules

  1. Loop until done — unbounded: forever. Bounded: N times then summarize.
  2. Read before write — understand full context before modifying.
  3. One change per iteration — atomic changes. If it breaks, you know why.
  4. Mechanical verification only — no subjective "looks good." Use metrics.
  5. Automatic rollback — failed changes revert instantly via git revert.
  6. Simplicity wins — equal results + less code = KEEP.
  7. Git is memory — experiments committed with experiment: prefix, agent reads git log + git diff before each iteration.
  8. When stuck, think harder — re-read, combine near-misses, try radical changes.

Results Tracking

Every iteration is logged in TSV format:

iteration  commit   metric  delta   status    description
0          a1b2c3d  85.2    0.0     baseline  initial state
1          b2c3d4e  87.1    +1.9    keep      add tests for auth edge cases
2          -        86.5    -0.6    discard   refactor test helpers (broke 2 tests)
3          c3d4e5f  88.3    +1.2    keep      add error handling tests

Agent-Specific Notes

Claude Code

  • Commands are invoked as /autoresearch and /autoresearch:<subcommand>
  • Interactive setup uses AskUserQuestion when context is missing
  • Skill files: .claude/skills/autoresearch/SKILL.md + references/*.md

Codex

  • Commands are invoked as plain text: autoresearch and autoresearch:<subcommand>
  • Interactive setup uses request_user_input or direct question batches
  • Plugin files: plugins/autoresearch/ with skills/
  • Command contracts live in each command file under plugins/autoresearch/skills/autoresearch/

Other Agents (OpenCode, Gemini CLI, etc.)

  • Read this file for the command surface and configuration contract
  • Use the core loop protocol: review → change → commit → verify → keep/revert → log
  • Git is required — the loop uses git commit, git revert, git log, git diff
  • Each iteration must be atomic (one change, one commit, one verification)
  • For detailed workflow references, see: claude-plugin/skills/autoresearch/references/*.md

Repository Structure

autoresearch/
├── AGENTS.md                          ← You are here
├── README.md                          ← Full documentation
├── COMPARISON.md                      ← Karpathy's vs Claude Autoresearch
├── guide/                             ← Comprehensive guides per command
├── claude-plugin/                     ← Claude Code distribution package
│   ├── skills/autoresearch/SKILL.md   ← Main skill + references/
│   └── commands/autoresearch/         ← Subcommand registrations
└── plugins/autoresearch/              ← Codex distribution package
    └── skills/autoresearch/SKILL.md   ← Codex skill router + references/

License

MIT — see LICENSE.

Credits