agentleFS
smallnestsmallnest/autoresearch/AGENTS.md

autoresearch

AGENTS.md571 starsChanged 7 months agoMITView on GitHub

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. autoresearch is a fully automated software development tool: given a GitHub Issue number, it implements the feature through multi-agent iterative review, then auto-creates a PR, merges it, and closes the Issue. The entire runtime is a single Bash script (run.sh). There are no build/test/lint commands for autoresearch itself. Shell-based regression tests live under tests/, including: - tests/test_extract_score.sh - tests/test_agent_logic.sh - tests/test_archive.sh - tests/test_context_overflow.sh - tests/test_cleanup.sh Before…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository5 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

10 rules. About 0 are common, 1 is distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before a new run starts (and not in continue mode), run.sh automatically archives old workflow data:

    line 34
  2. Very specific:

    If the target archive directory already exists, it appends a numeric suffix (e.g., -1, -2).

    line 37
  3. Very specific:

    If planning fails (no tasks.json generated), falls back to original mode: implement entire Issue in one go.

    line 50
  4. Very specific:

    No tasks.json (planning failure) → backward-compatible original mode

    line 79
  5. Very specific:

    When reviewing archived workflow iterations, treat .autoresearch/workflows/issue-N/planning.log as the source of truth for the original …

    line 80
  6. Very specific:

    When merge/cleanup operations are non-fatal by design, tests should mock gh/git failures and assert both log.md side effects and that later …

    line 116
  7. Very specific:

    Default passing score is 85/100, configurable via PASSING_SCORE env var

    line 123
  8. Distinctive:

    If browser tools unavailable: UI verification is disabled, continues with code review only

    line 145
  9. Very specific:

    If screenshot fails: Logs warning, returns pass: true with degraded feedback

    line 146
  10. Very specific:

    If LLM verification fails: Retries up to 3 times, then returns pass: true with warning

    line 147

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

autoresearch is a fully automated software development tool: given a GitHub Issue number, it implements the feature through multi-agent iterative review, then auto-creates a PR, merges it, and closes the Issue. The entire runtime is a single Bash script (run.sh).

Running

# Process Issue #N in the current directory's project
./run.sh 42

# With project path, max iterations, or continue mode
./run.sh -p /path/to/project 42 16
./run.sh -c 42 10              # Continue from last interrupted iteration

# Skip archiving of previous workflows (useful for debugging)
./run.sh --no-archive 42

There are no build/test/lint commands for autoresearch itself. Shell-based regression tests live under tests/, including:

  • tests/test_extract_score.sh
  • tests/test_agent_logic.sh
  • tests/test_archive.sh
  • tests/test_context_overflow.sh
  • tests/test_cleanup.sh

Architecture

Archiving Mechanism

Before a new run starts (and not in continue mode), run.sh automatically archives old workflow data:

  • Scans .autoresearch/workflows/ for issue-* directories.
  • Moves non-current issue directories to .autoresearch/archive/YYYY-MM-DD-issue-N/.
  • If the target archive directory already exists, it appends a numeric suffix (e.g., -1, -2).

Iteration Loop

Planning Phase: First agent reads Issue → outputs tasks.json with subtask breakdown
Iteration 1: Agent implements current subtask → tests run
Iteration 2+: Agent round-robin review + fix per subtask
    → Score >= 85? → mark subtask passed → advance to next subtask
    → Score < 85?  → agent fixes based on review feedback → next iteration
    → All subtasks passed? → auto commit/PR/merge/close Issue

If planning fails (no tasks.json generated), falls back to original mode: implement entire Issue in one go.

Agent rotation (from iteration 2): (iter - 1) % N where N = number of agents.

Global Cleanup / Traps

  • run.sh installs global EXIT, INT, TERM, and DEBUG traps near the spinner helpers.
  • cleanup() must stay idempotent because interrupt paths can otherwise re-enter during exit handling.
  • Signal traps should disable the EXIT trap before exiting, otherwise abnormal exits will append duplicate interruption records to log.md.
  • Child-process cleanup is recursive via collect_descendant_pids() and should keep a ps fallback because pgrep -P is not reliable in every macOS environment.
  • DEBUG trap records the last executed command in LAST_COMMAND to help identify which command triggered set -e exits.
  • cleanup() logs exit code, exit reason, and the last executed command to both log.md and console for debugging unexpected exits.

Subtask System (tasks.json)

Planning phase (before iteration 1) asks the first agent to split the Issue into subtasks, saved to .autoresearch/workflows/issue-N/tasks.json:

{
  "issueNumber": 42,
  "subtasks": [
    { "id": "T-001", "title": "...", "description": "...", "acceptanceCriteria": [...], "priority": 1, "passes": false }
  ]
}
  • Each iteration focuses on one passes: false subtask
  • Quality gate passes → mark_subtask_passed() sets passes: true
  • all_subtasks_passed() → enters PR/merge flow
  • No tasks.json (planning failure) → backward-compatible original mode
  • When reviewing archived workflow iterations, treat .autoresearch/workflows/issue-N/planning.log as the source of truth for the original subtask acceptance criteria. tasks.json inside the workflow can contain placeholder or truncated subtask text in later iterations and is not always reliable for audit scoring.

Agent Invocation

Agents are external CLIs called via run_with_retry() with exponential backoff:

  • Codex: Codex -p "$prompt" --dangerously-skip-permissions
  • Codex: codex exec --full-auto "$prompt"
  • OpenCode: opencode run "$prompt"

Prompt Assembly

Each agent prompt composes these parts:

  1. Task context (Issue info, project path, language, iteration)
  2. Subtask section (current subtask details + progress) — from get_subtask_section() / get_subtask_review_section()
  3. program.md content — global rules and constraints
  4. Agent-specific instructions from agents/<name>.md

For review prompts, only task context + subtask review section + agent instructions are included (no program.md).

Configuration Override (Two-Tier)

Project-level configs in $PROJECT_ROOT/.autoresearch/ take precedence over defaults in the autoresearch directory:

  • agents/<name>.md — agent persona and review rubric
  • program.md — implementation rules and code standards

Score Extraction

extract_score() parses free-text review output using 6 cascading regex patterns (X/100, 评分: X/100, 总分 table, X/10, 评分: X, 评分: X). If no score is found, defaults to 0; review functions fall back to 50 on extraction failure.

Continue Mode (-c)

Restores state from .autoresearch/workflows/issue-N/ log files: iteration count, last score, consecutive failure count, last review feedback, and subtask state (from tasks.json). MAX_ITERATIONS becomes last_iteration + new_count.

Git / GitHub Failure Paths

  • The final PR flow in run.sh is still set -e sensitive; gh pr merge must be wrapped with explicit failure handling rather than called bare.
  • When merge/cleanup operations are non-fatal by design, tests should mock gh/git failures and assert both log.md side effects and that later cleanup steps still execute.

Key Design Constraints

  • Agents cannot push to remote, close Issues, create PRs, or modify CI/CD — only run.sh performs those privileged operations after quality gates pass
  • program.md contains code standards for Go/Python/TypeScript/Rust/Frontend — the README advises trimming to only the target project's language to save tokens
  • Consecutive iteration failures >= 2 triggers a hard stop
  • Default passing score is 85/100, configurable via PASSING_SCORE env var

UI Verification

The UI verification system runs browser-based validation for UI-type subtasks ("type": "ui").

Configuration

Environment variables (can also be set in shell):

  • UI_VERIFY_ENABLED: Enable/disable UI verification (default: yes)
  • UI_VERIFY_TIMEOUT: Dev server wait timeout in seconds (default: 60)
  • UI_DEV_PORT: Dev server port (default: auto-detect or 3000)

Process

  1. Dependency Check: During check_dependencies(), detects if playwright or chrome-devtools MCP is available
  2. Dev Server Detection: Automatically detects dev server command based on project type
  3. Screenshot Capture: Uses multiple fallback tools (playwright → npx playwright → google-chrome → chromium → chromium-browser)
  4. LLM Verification: Sends screenshot to LLM for validation against UI standards

Fallback Behavior

  • If browser tools unavailable: UI verification is disabled, continues with code review only
  • If screenshot fails: Logs warning, returns pass: true with degraded feedback
  • If LLM verification fails: Retries up to 3 times, then returns pass: true with warning

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.