mirror of
https://github.com/uditgoenka/autoresearch.git
synced 2026-09-14 20:07:09 +08:00
Merge pull request #118 from uditgoenka/release/v2.2.2-release-facts
PRGate: release/v2.2.2-release-facts
This commit is contained in:
Udit Goenka
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: autoresearch
|
||||
description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
|
||||
version: 2.2.1
|
||||
version: 2.2.2
|
||||
---
|
||||
|
||||
# Autoresearch — Autonomous Goal-directed Iteration
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
|
||||
"name": "autoresearch",
|
||||
"version": "2.2.1",
|
||||
"version": "2.2.2",
|
||||
"description": "Claude Autoresearch \u2014 autonomous goal-directed iteration for Claude Code. 14 commands: iterate, plan, debug, fix, security, ship, scenario, predict, learn, reason, probe, evals, improve, regression.",
|
||||
"owner": {
|
||||
"name": "Udit Goenka",
|
||||
@@ -11,7 +11,7 @@
|
||||
{
|
||||
"name": "autoresearch",
|
||||
"description": "Autonomous improvement engine. 14 commands with bounded defaults, chain handoff, and adaptive evals checkpoints. 95% token reduction via modular architecture.",
|
||||
"version": "2.2.1",
|
||||
"version": "2.2.2",
|
||||
"author": {
|
||||
"name": "Udit Goenka",
|
||||
"url": "https://github.com/uditgoenka"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: autoresearch
|
||||
description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
|
||||
version: 2.2.1
|
||||
version: 2.2.2
|
||||
---
|
||||
|
||||
# Autoresearch — Autonomous Goal-directed Iteration
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: autoresearch
|
||||
description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
|
||||
version: 2.2.1
|
||||
version: 2.2.2
|
||||
---
|
||||
|
||||
# Autoresearch — Autonomous Goal-directed Iteration
|
||||
|
||||
+16
-10
@@ -32,17 +32,17 @@ The canonical source is `.claude/`. After making changes, run the transform to s
|
||||
./scripts/transform.sh --codex # Codex only
|
||||
```
|
||||
|
||||
## Repository Structure (v2.1.0)
|
||||
## Repository Structure (v2.2.2)
|
||||
|
||||
```
|
||||
autoresearch/
|
||||
├── .claude/ ← CANONICAL SOURCE — edit here first
|
||||
│ ├── skills/autoresearch/
|
||||
│ │ ├── SKILL.md ← Thin routing table (41 lines)
|
||||
│ │ └── references/ ← 3 focused reference files
|
||||
│ │ ├── SKILL.md ← Thin routing table
|
||||
│ │ └── references/ ← Shared routing and review references
|
||||
│ └── commands/
|
||||
│ ├── autoresearch.md ← Core loop (self-contained, ~110 lines)
|
||||
│ └── autoresearch/ ← 12 subcommand files (self-contained)
|
||||
│ └── autoresearch/ ← 13 subcommand files (self-contained)
|
||||
├── .opencode/ ← OpenCode port (generated via transform.sh)
|
||||
├── .agents/ + plugins/ ← Codex port (generated via transform.sh)
|
||||
├── claude-plugin/ ← Distribution package (Claude Code plugin install)
|
||||
@@ -67,7 +67,7 @@ autoresearch/
|
||||
| `references/security-checklist.md` | STRIDE + OWASP checklist (loaded by security command) | Adding security checks |
|
||||
| `references/predict-personas.md` | 5 expert personas (loaded by predict command) | Adding/modifying personas |
|
||||
| `references/reason-judge-protocol.md` | Adversarial refinement protocol (loaded by reason command) | Changing judge/critic behavior |
|
||||
| `scripts/transform.sh` | Platform transform (.claude/ → .opencode/ + .agents/) | Adding new commands or reference files |
|
||||
| `scripts/transform.sh` | Canonical transform (.claude/ → .opencode/ + .agents/ + claude-plugin/) | Adding new commands, reference files, or generated helper updates |
|
||||
| `claude-plugin/` | Distribution package — synced from .claude/ during release | Don't edit directly — edit .claude/ |
|
||||
|
||||
## What to Contribute
|
||||
@@ -141,7 +141,7 @@ Update: README.md (commands table), guide/ (new guide file), COMPARISON.md (subc
|
||||
|
||||
## Testing
|
||||
|
||||
No automated tests — autoresearch is Markdown instructions. Testing means using it:
|
||||
The repo includes shell-based verification for the generated distributions and hook/runtime contracts:
|
||||
|
||||
1. Symlink your working tree (see Quick Start)
|
||||
2. Open Claude Code in a real project
|
||||
@@ -149,12 +149,18 @@ No automated tests — autoresearch is Markdown instructions. Testing means usin
|
||||
4. Verify behavior matches your changes
|
||||
5. Try edge cases — wrong metric? 0 files in scope? Guard always fails?
|
||||
|
||||
For maintainer workflows, the canonical checks are:
|
||||
|
||||
- `bash scripts/transform.sh` — regenerate platform distributions and bundled runtime helpers
|
||||
- `bash tests/test-maintenance.sh` — transform idempotence and release-prep guards
|
||||
- `bash tests/test-hooks.sh` — Claude hook contracts and fail-open behavior
|
||||
|
||||
## Release Process
|
||||
|
||||
Maintainers use `scripts/release.sh`. See `scripts/release.md` for details.
|
||||
|
||||
```bash
|
||||
./scripts/release.sh 2.2.0 --title "New Feature"
|
||||
./scripts/release.sh 2.2.2 --title "Release 2.2.2"
|
||||
```
|
||||
|
||||
Contributors don't need to bump versions.
|
||||
@@ -188,16 +194,16 @@ Thanks for contributing!
|
||||
}
|
||||
```
|
||||
4. Register in `hooks.json` under the correct event
|
||||
5. Run `bash scripts/transform.sh` to update the plugin distribution
|
||||
5. Run `bash scripts/transform.sh` to update the plugin distribution and bundled runtime helpers
|
||||
6. Run `bash tests/test-hooks.sh` to verify
|
||||
|
||||
### Hook Rules
|
||||
|
||||
- **Fail-open:** Always wrap in try/catch, always exit 0 on error
|
||||
- **Fail-open:** Always wrap in try/catch, always exit 0 on error, and emit a visible redacted diagnostic when available
|
||||
- **No console.log:** Corrupts stdout JSON. Use `process.stderr.write()` for debug
|
||||
- **No external deps:** Pure Node.js builtins only (exception: vendored `lib/ignore.cjs`)
|
||||
- **Exit codes:** 0 = allow/inject, 2 = block. No other exit codes
|
||||
- **State:** Use `/tmp/ar-session-{hash}.json` via `loadSessionState()` / `saveSessionState()`
|
||||
- **State:** Use the OS temporary directory via `loadSessionState()` / `saveSessionState()`; this is not a repo path
|
||||
|
||||
### Testing Hooks
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Based on [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) —
|
||||
[](https://docs.anthropic.com/en/docs/claude-code)
|
||||
[](https://opencode.ai)
|
||||
[](https://developers.openai.com/codex)
|
||||
[](https://github.com/uditgoenka/autoresearch/releases)
|
||||
[](https://github.com/uditgoenka/autoresearch/releases)
|
||||
[](LICENSE)
|
||||
|
||||
[](https://github.com/karpathy/autoresearch)
|
||||
@@ -22,7 +22,7 @@ Based on [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) —
|
||||
|
||||
*You don't need AGI. You need a goal, a metric, and a loop that never quits.*
|
||||
|
||||
**Supports Claude Code, OpenCode, and OpenAI Codex. 14 commands. 9 safety hooks. 95% fewer tokens per invocation.**
|
||||
**Supports Claude Code, OpenCode, and OpenAI Codex for the core skill, bundled runtime, installation, and verification surface. Hook guardrails are Claude Code-only.**
|
||||
|
||||
> **v2.2.0 — Autonomous Orchestrator:** Type a plain-language goal to `/autoresearch` and it classifies your goal, derives a Success predicate, confirms it once, then loops across subcommands until done. No manual chaining required. `Metric:`/`Verify:` invocations run the classic loop unchanged. See [guide/autoresearch-orchestrator.md](guide/autoresearch-orchestrator.md).
|
||||
|
||||
@@ -116,7 +116,7 @@ Before looping, Claude performs a one-time setup:
|
||||
|
||||
## Hooks & Safety
|
||||
|
||||
v2.1.1 ships a 9-hook safety system that protects your sessions automatically. Hooks fire on every session — not just during autoresearch commands.
|
||||
Hooks are defense-in-depth guardrails, not a security sandbox. Claude Code ships the hook surface; OpenCode and Codex ship the core skill/runtime/install surface without hook parity.
|
||||
|
||||
### What's Protected
|
||||
|
||||
@@ -134,7 +134,7 @@ v2.1.1 ships a 9-hook safety system that protects your sessions automatically. H
|
||||
|
||||
### Configuration
|
||||
|
||||
All hooks are **on by default**. Disable individually:
|
||||
All hooks are **on by default**. Disable individually only for troubleshooting:
|
||||
|
||||
```bash
|
||||
# Disable a specific hook
|
||||
@@ -154,6 +154,8 @@ Customize blocked directories with a `.ckignore` file (gitignore syntax) at your
|
||||
|
||||
See [guide/hooks.md](guide/hooks.md) for full reference.
|
||||
|
||||
Release preparation and contributor verification live in [scripts/release.md](scripts/release.md).
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
@@ -310,6 +312,7 @@ cp -r autoresearch/.agents/skills/autoresearch ~/.codex/skills/autoresearch
|
||||
```
|
||||
|
||||
> Invoke via `$autoresearch` mention syntax. Subcommands are keywords: `$autoresearch plan`, `$autoresearch debug`, `$autoresearch evals`, etc.
|
||||
> The installed Codex package includes the bundled orchestrator and regression helpers under `plugins/autoresearch/skills/autoresearch/` and `.agents/skills/autoresearch/`.
|
||||
|
||||
### Run It
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "autoresearch",
|
||||
"description": "Autonomous improvement engine. 14 commands: iterate, plan, debug, fix, security, ship, scenario, predict, learn, reason, probe, improve, evals, regression.",
|
||||
"version": "2.2.1",
|
||||
"version": "2.2.2",
|
||||
"author": {
|
||||
"name": "Udit Goenka",
|
||||
"url": "https://github.com/uditgoenka"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: autoresearch
|
||||
description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
|
||||
version: 2.2.1
|
||||
version: 2.2.2
|
||||
---
|
||||
|
||||
# Autoresearch — Autonomous Goal-directed Iteration
|
||||
|
||||
+2
-106
@@ -1,109 +1,5 @@
|
||||
# Changelog
|
||||
|
||||
Generated from git history. Grouped by type using conventional commit parsing.
|
||||
Historical archive. Current release notes live in [project-changelog.md](project-changelog.md).
|
||||
|
||||
## v2.1.0
|
||||
|
||||
### Features
|
||||
- `feat:` modular rebuild — thin SKILL.md routing table (41 lines) + 12 self-contained command files
|
||||
- `feat:` add `/autoresearch:evals` subcommand — one-shot TSV trend and plateau analysis
|
||||
- `feat:` `--evals` and `--evals-interval` flags on all looping commands
|
||||
- `feat:` TSV `# metric_direction` comment for auto-detection by evals
|
||||
- `feat:` 8 TSV status values — added `keep (reworked)`, `hook-blocked`, `metric-error`
|
||||
- `feat:` `scripts/transform.sh` single multi-platform transform script
|
||||
|
||||
### Removed
|
||||
- `chore:` remove `autoresearch-command-spec.json` — contracts live in command files
|
||||
- `chore:` remove `scripts/sync-opencode.sh` and `scripts/sync-codex.sh` — replaced by transform.sh
|
||||
- `chore:` remove Python wrapper CLI (`autoresearch_cli.py`)
|
||||
- `chore:` collapse 13 reference files down to 3 focused references
|
||||
|
||||
### Release
|
||||
- `release:` v2.1.0 — modular rebuild, evals, 95% token reduction
|
||||
|
||||
## v2.0.04
|
||||
|
||||
### Fixed
|
||||
- `fix:` YAML colon escape issues in SKILL.md frontmatter across platforms
|
||||
- `fix:` sync script path handling for edge cases with special characters
|
||||
|
||||
### Release
|
||||
- `release:` v2.0.04 — YAML and sync script stability
|
||||
|
||||
## v2.0.0
|
||||
|
||||
### Features
|
||||
- `feat:` multi-platform GA — Claude Code, OpenCode, Codex all fully supported
|
||||
- `feat:` `allowed-tools` declaration on all Claude Code and claude-plugin command files
|
||||
|
||||
### Fixed
|
||||
- `fix:` SKILL.md YAML frontmatter uses folded block scalars — strict parsers no longer reject description field
|
||||
- `fix:` sync scripts pass paths via argv instead of shell string interpolation
|
||||
- `fix:` install.sh validates destination path depth before rm -rf
|
||||
|
||||
### Release
|
||||
- `release:` v2.0.0 — multi-platform GA
|
||||
|
||||
## v1.10.0
|
||||
|
||||
### Features
|
||||
- `feat:` add `/autoresearch:probe` — adversarial multi-persona requirement interrogation engine
|
||||
- `feat:` 8 personas, mechanical saturation termination, constraint extraction
|
||||
|
||||
### Release
|
||||
- `release:` v1.10.0 — probe subcommand
|
||||
|
||||
## v1.8.0
|
||||
|
||||
### Features
|
||||
- `feat:` add `/autoresearch:learn` — autonomous codebase documentation engine
|
||||
- `feat:` 4 modes: init, update, check, summarize; diff-based targeting for update mode
|
||||
|
||||
### Release
|
||||
- `release:` v1.8.0 — learn subcommand
|
||||
|
||||
## v1.7.6
|
||||
|
||||
### Documentation
|
||||
- `docs:` add COMPARISON.md — Karpathy vs Claude Autoresearch
|
||||
- `docs:` add 10 scenario-based guide examples in guide/scenario/
|
||||
|
||||
### Release
|
||||
- `release:` v1.7.6 — scenario guides, comparison doc
|
||||
|
||||
## v1.7.0 — v1.7.5
|
||||
|
||||
### Features
|
||||
- `feat:` add `/autoresearch:predict` — multi-persona swarm prediction (v1.7.0)
|
||||
|
||||
### Fixed
|
||||
- `fix:` resolve ENAMETOOLONG recursive plugin caching
|
||||
- `fix:` address 8 stability bugs from debug audit
|
||||
- `fix:` streamline command files for faster trigger and live streaming
|
||||
|
||||
### Release
|
||||
- `release:` v1.7.0 — predict subcommand
|
||||
|
||||
## v1.6.0 — v1.6.2
|
||||
|
||||
### Features
|
||||
- `feat:` add `/autoresearch:scenario` subcommand
|
||||
- `feat:` release workflow with PR-first flow and doc review gate
|
||||
|
||||
### Fixed
|
||||
- `fix:` harden git-as-memory mechanism in autonomous loop
|
||||
|
||||
### Release
|
||||
- `release:` v1.6.x — scenario subcommand
|
||||
|
||||
## v1.3.0 — v1.5.0
|
||||
|
||||
### Features
|
||||
- `feat:` enforce mandatory AskUserQuestion gate for all commands
|
||||
- `feat:` batched AskUserQuestion setup — ask 3-4 questions at once
|
||||
- `feat:` add `/autoresearch:reason` adversarial refinement loop
|
||||
|
||||
### Fixed
|
||||
- `fix:` replace /loop N with native Iterations: N config
|
||||
|
||||
See also: [Development Roadmap](development-roadmap.md) | [Project Overview](project-overview-pdr.md)
|
||||
This file is retained for older git-history summaries only and should not be treated as the current source of release facts.
|
||||
|
||||
+10
-10
@@ -11,7 +11,7 @@ This project is entirely **markdown-based** with shell script helpers. There is
|
||||
- Command files match their command name: `debug.md` for `/autoresearch:debug`
|
||||
- OpenCode distribution uses underscores: `autoresearch_debug.md`
|
||||
|
||||
## SKILL.md Pattern (v2.1.0)
|
||||
## SKILL.md Pattern (v2.2.2)
|
||||
|
||||
The main skill file is a **thin routing table only** — not a protocol document:
|
||||
- YAML frontmatter: `name`, `description`, `version`
|
||||
@@ -22,13 +22,13 @@ The main skill file is a **thin routing table only** — not a protocol document
|
||||
|
||||
Target: ~41 lines. All protocol lives in the command files.
|
||||
|
||||
## Command File Pattern (v2.1.0)
|
||||
## Command File Pattern (v2.2.2)
|
||||
|
||||
Each command file (`.claude/commands/autoresearch/*.md`) is **self-contained**:
|
||||
- YAML frontmatter: `name`, `description`, `argument-hint`
|
||||
- `EXECUTE IMMEDIATELY` header — no deliberation before reading
|
||||
- Parse Arguments section — extract all flags inline
|
||||
- Setup section — AskUserQuestion batched call if config missing
|
||||
- Setup section — AskUserQuestion batched call in Claude, request_user_input in Codex, and question in OpenCode
|
||||
- Precondition checks
|
||||
- Full loop or workflow protocol with numbered phases
|
||||
- TSV logging format
|
||||
@@ -36,14 +36,14 @@ Each command file (`.claude/commands/autoresearch/*.md`) is **self-contained**:
|
||||
|
||||
Target: 94–120 lines per command file. Never split protocol across files unless content is truly shared across 3+ commands.
|
||||
|
||||
## Reference Files Pattern (v2.1.0)
|
||||
## Reference Files Pattern (v2.2.2)
|
||||
|
||||
Reference files (`.claude/skills/autoresearch/references/`) are for **shared content only**:
|
||||
- Loaded explicitly by the command file that needs them
|
||||
- Must be referenced by 3+ commands to justify existence as a reference
|
||||
- Current 3 references: `predict-personas.md`, `reason-judge-protocol.md`, `security-checklist.md`
|
||||
|
||||
Do not create per-command workflow reference files. That was the v2.0.x pattern (13 files). v2.1.0 embeds protocol directly.
|
||||
Do not create per-command workflow reference files. That was the v2.0.x pattern (13 files). v2.2.x embeds protocol directly.
|
||||
|
||||
## TSV Logging Format
|
||||
|
||||
@@ -62,8 +62,8 @@ The `# metric_direction` comment on line 1 enables the evals command to auto-det
|
||||
## Version Management
|
||||
|
||||
- Version tracked in **two** plugin.json files:
|
||||
- `claude-plugin/.claude-plugin/plugin.json` — Claude Code (e.g. `2.1.0`)
|
||||
- `plugins/autoresearch/.codex-plugin/plugin.json` — Codex (e.g. `2.1.0-codex.0`)
|
||||
- `claude-plugin/.claude-plugin/plugin.json` — Claude Code canonical manifest (e.g. `2.2.2`)
|
||||
- `plugins/autoresearch/.codex-plugin/plugin.json` — Codex manifest convention (e.g. `2.2.2-codex.0`)
|
||||
- Version also appears in SKILL.md frontmatter and README badges
|
||||
- `scripts/release.sh` automates version bumping across all touchpoints
|
||||
|
||||
@@ -73,13 +73,13 @@ The `# metric_direction` comment on line 1 enables the evals command to auto-det
|
||||
- Quote all variables: `"$VAR"` not `$VAR`
|
||||
- `set -euo pipefail` for strict error handling
|
||||
- Scripts live in `scripts/` — no scripts in plugin directories
|
||||
- `scripts/transform.sh` is the single source for all platform distributions; do not maintain separate sync scripts
|
||||
- `scripts/transform.sh` is the single source for all platform distributions and bundled runtime helpers; do not maintain separate sync scripts
|
||||
|
||||
## Platform Distribution
|
||||
|
||||
Source of truth is `.claude/`. To update OpenCode or Codex distributions:
|
||||
Source of truth is `.claude/`. To update OpenCode, Codex, or the checked-in Claude plugin distribution:
|
||||
1. Edit canonical files in `.claude/commands/` or `.claude/skills/`
|
||||
2. Run `scripts/transform.sh` to regenerate platform distributions
|
||||
2. Run `scripts/transform.sh` to regenerate platform distributions and bundled runtime helpers
|
||||
3. Commit all generated files together
|
||||
|
||||
Do not hand-edit `.opencode/` or `plugins/autoresearch/` files directly.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Autoresearch v2.1.0 ships as a modular, multi-platform autonomous iteration framework. The canonical source lives in `.claude/`; `scripts/transform.sh` produces OpenCode and Codex distributions. There is no compiled code and near-zero runtime dependencies.
|
||||
Autoresearch v2.2.2 ships as a modular, multi-platform autonomous iteration framework. The canonical source lives in `.claude/`; `scripts/transform.sh` produces OpenCode, Codex, and the checked-in Claude plugin distribution while refreshing bundled runtime helpers in each generated skill package. There is no compiled code and near-zero runtime dependencies.
|
||||
|
||||
## File Inventory
|
||||
|
||||
@@ -30,9 +30,9 @@ Autoresearch v2.1.0 ships as a modular, multi-platform autonomous iteration fram
|
||||
| `.claude/skills/autoresearch/references/predict-personas.md` | 5 default expert personas used by predict subcommand |
|
||||
| `.claude/skills/autoresearch/references/reason-judge-protocol.md` | Blind judge scoring protocol for reason subcommand |
|
||||
| `.claude/skills/autoresearch/references/security-checklist.md` | STRIDE + OWASP checklist used by security subcommand |
|
||||
| `claude-plugin/.claude-plugin/plugin.json` | Claude Code plugin metadata — version 2.1.0 |
|
||||
| `plugins/autoresearch/.codex-plugin/plugin.json` | Codex plugin metadata — version 2.1.0-codex.0 |
|
||||
| `scripts/transform.sh` | Single script that generates all platform distributions from `.claude/` source |
|
||||
| `claude-plugin/.claude-plugin/plugin.json` | Claude Code plugin metadata — version 2.2.2 |
|
||||
| `plugins/autoresearch/.codex-plugin/plugin.json` | Codex plugin metadata — version 2.2.2-codex.0 |
|
||||
| `scripts/transform.sh` | Canonical transform that generates all platform distributions from `.claude/` source |
|
||||
| `scripts/install.sh` | Guided interactive installer |
|
||||
| `README.md` | Project README with installation, usage, FAQ |
|
||||
| `COMPARISON.md` | Karpathy's autoresearch vs Claude Autoresearch |
|
||||
@@ -89,4 +89,10 @@ All subcommands write to `autoresearch/{subcommand}-{YYMMDD}-{HHMM}/`:
|
||||
|
||||
TSV files include a `# metric_direction: higher_is_better|lower_is_better` comment on line 1. Status values: `baseline`, `keep`, `keep (reworked)`, `discard`, `crash`, `no-op`, `hook-blocked`, `metric-error`.
|
||||
|
||||
The main verification routes live in the scripts themselves:
|
||||
|
||||
- `bash scripts/transform.sh` — regenerate all platform distributions and bundled runtime helpers
|
||||
- `bash tests/test-maintenance.sh` — transform idempotence, selective transforms, release-prep guards
|
||||
- `bash tests/test-hooks.sh` — Claude hook contracts, fail-open behavior, and redacted diagnostics
|
||||
|
||||
See also: [Project Overview](project-overview-pdr.md) | [System Architecture](system-architecture.md) | [Code Standards](code-standards.md)
|
||||
|
||||
@@ -2,6 +2,29 @@
|
||||
|
||||
All notable changes to the autoresearch project are documented here.
|
||||
|
||||
## v2.2.2 — Stabilization Release (2026-08-13)
|
||||
|
||||
**Theme:** Restore truthful platform support, self-contained installs, and release confidence without turning the patch into a feature drop.
|
||||
|
||||
### Added
|
||||
- Native Windows with Git Bash is now part of the verified support contract for the hook and release-gate surfaces.
|
||||
- Release preparation now documents the exact transform, parity, clean-install, and test gates that must pass before a PR is opened.
|
||||
- Immutable-tag recovery is documented: failed exact-release smoke checks move to remediation instead of retagging.
|
||||
|
||||
### Changed
|
||||
- Hook guardrails are documented as defense-in-depth checks, not a security sandbox.
|
||||
- Clear sensitive-file operations now go through the host permission boundary instead of a forgeable path prefix.
|
||||
- Self-contained runtime helpers and generated mirrors are treated as release artifacts, not independently maintained copies.
|
||||
- Release preparation stops after PR creation; merge, tag creation, and GitHub release publishing are separate owner actions.
|
||||
- The release note records contributor credit for the runtime-helper packaging work associated with the stabilization line; that credit belongs to MiaoDX.
|
||||
|
||||
### Fixed
|
||||
- Visible redacted diagnostics replace silent hook failure on supported platforms.
|
||||
- Operand-scoped remote-path handling prevents remote `ssh`, `tsh`, `scp`, and `rsync` operands from masking local inspection.
|
||||
- Canonical transform, parity, clean-install smoke, and four release suites are now release gates.
|
||||
- Canonical and generated version surfaces are aligned for the v2.2.2 stabilization release.
|
||||
|
||||
|
||||
## v2.2.1 — Orchestrator Seam Hardening (2026-06-23)
|
||||
|
||||
**Theme:** Harden the autonomous orchestrator's deterministic seam against the failure modes an unsupervised loop can hit — under-screened destructive commands, a re-derived or corrupted "done" definition, and a change that games its own metric.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Summary
|
||||
|
||||
Claude Autoresearch is a Claude Code skill/plugin that turns Claude Code into an autonomous improvement engine. Inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch), it generalizes the constraint-driven autonomous iteration pattern to any domain — code, content, marketing, sales, security, and more.
|
||||
Claude Autoresearch is a multi-platform skill/plugin for Claude Code, OpenCode, and Codex that turns the host into an autonomous improvement engine. Inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch), it generalizes the constraint-driven autonomous iteration pattern to any domain — code, content, marketing, sales, security, and more.
|
||||
|
||||
**Core idea:** Set a goal with a mechanical metric, define scope, and let Claude autonomously iterate — modify, verify, keep/discard, repeat — until the goal is achieved or the iteration limit is reached.
|
||||
|
||||
@@ -12,7 +12,7 @@ Claude Autoresearch is a Claude Code skill/plugin that turns Claude Code into an
|
||||
|-------|-------|
|
||||
| **Name** | Claude Autoresearch |
|
||||
| **Type** | Claude Code Skill/Plugin |
|
||||
| **Version** | 2.1.0 |
|
||||
| **Version** | 2.2.2 |
|
||||
| **License** | MIT |
|
||||
| **Author** | [Udit Goenka](https://github.com/uditgoenka) |
|
||||
| **Repository** | [github.com/uditgoenka/autoresearch](https://github.com/uditgoenka/autoresearch) |
|
||||
@@ -30,7 +30,7 @@ Autoresearch automates this entire loop with mechanical verification, automatic
|
||||
- **Bounded by default** — every looping command has a sane default iteration count; opt into unbounded with `Iterations: unlimited`
|
||||
- **Guard system** — optional safety net that reverts commits when quality regresses
|
||||
- **Git as memory** — every experiment committed; agent reads history to avoid repeating failures
|
||||
- **Interactive setup** — batched AskUserQuestion when invoked without full config
|
||||
- **Interactive setup** — batched AskUserQuestion in Claude, request_user_input in Codex, and question in OpenCode when invoked without full config
|
||||
- **Domain-agnostic** — works for any task with a measurable shell-accessible metric
|
||||
- **Chain integration** — pipe output between subcommands via `handoff.json`
|
||||
- **Evals** — built-in trend and plateau analysis for any `*-results.tsv` file
|
||||
@@ -54,6 +54,7 @@ Autoresearch automates this entire loop with mechanical verification, automatic
|
||||
| `/autoresearch:probe` | Requirement interrogation until saturation | 15 |
|
||||
| `/autoresearch:improve` | Research ICP challenges, discover improvements, generate PRDs | 15 |
|
||||
| `/autoresearch:evals` | Analyze `*-results.tsv`: trends, plateaus, regressions | N/A |
|
||||
| `/autoresearch:regression` | Compare baseline and candidate evidence; emit a stability verdict | N/A |
|
||||
|
||||
## Target Users
|
||||
|
||||
|
||||
+21
-19
@@ -2,13 +2,13 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Autoresearch v2.2.1 is a modular, markdown-driven autonomous iteration framework. The core architectural shift from v2.0.x is the **thin SKILL.md + self-contained command files** pattern: the skill file is a routing table; all protocol is embedded in 14 self-contained command files. Only the invoked command file loads per invocation, reducing token cost by ~95%.
|
||||
Autoresearch v2.2.2 is a modular, markdown-driven autonomous iteration framework. The core architectural shift from v2.0.x is the **thin SKILL.md + self-contained command files** pattern: the skill file is a routing table; all protocol is embedded in 14 self-contained command files. Only the invoked command file loads per invocation, reducing token cost by ~95%.
|
||||
|
||||
As of v2.2.0, bare `/autoresearch` is overloaded: a `Metric:`/`Verify:` config runs the classic metric loop unchanged, while a free-form natural-language goal dispatches an **autonomous orchestrator** that classifies the goal, derives a success predicate, and loops the right subcommands until it holds. All routing decisions live in one deterministic seam, `scripts/orchestrate.sh` (mirroring the `scripts/score-regression.sh` pattern), bounded by plateau detection and a hard cycle ceiling.
|
||||
|
||||
v2.2.1 hardens that seam with four orchestrator-safety additions: `screen-cmd` gains destructive-command coverage (netcat exfiltration, raw block-device writes across SD/eMMC·RAID·device-mapper families, `mkfs`, `find -delete`, `shred`, zero-`truncate`, recursive zero-mode `chmod`, curl/wget-into-interpreter via xargs) — including path-qualified invocations like `/sbin/mkfs.ext4`; the derived Success predicate is **pinned** verbatim into `orchestrator-state.json` and re-screened on resume via the new `screen-state-predicate` subcommand (extraction honors escaped quotes so a poisoned predicate cannot truncate the screen); a new `validate-state` subcommand gates the ledger (required fields + coarse types) before routing; and `next-hop` routes a high-impact accepted change through an independent **verify** hop (`pending_verify`) before declaring `DONE` or shipping. The seam now exposes eight subcommands: `classify`, `next-hop`, `units`, `plateau`, `screen-cmd`, `verdict`, `validate-state`, `screen-state-predicate`.
|
||||
|
||||
Multi-platform: Claude Code, OpenCode, and Codex are all supported via a single `scripts/transform.sh` that produces platform-specific distributions from the canonical `.claude/` source.
|
||||
Multi-platform: Claude Code, OpenCode, and Codex are all supported via a single `scripts/transform.sh` that produces platform-specific distributions from the canonical `.claude/` source and refreshes bundled runtime helpers inside each generated skill package.
|
||||
|
||||
## Component Diagram
|
||||
|
||||
@@ -29,10 +29,10 @@ graph TB
|
||||
end
|
||||
|
||||
subgraph "Canonical Source"
|
||||
SKILL[.claude/skills/autoresearch/SKILL.md\nthin routing table — 41 lines]
|
||||
SKILL[.claude/skills/autoresearch/SKILL.md\nthin routing table]
|
||||
CMD[.claude/commands/autoresearch.md]
|
||||
CMDS[.claude/commands/autoresearch/*.md\n14 self-contained command files]
|
||||
REF[.claude/skills/autoresearch/references/\n3 focused reference files]
|
||||
REF[.claude/skills/autoresearch/references/\nshared routing and review references]
|
||||
end
|
||||
|
||||
subgraph "Platform Distributions"
|
||||
@@ -101,6 +101,7 @@ flowchart TD
|
||||
│ ├── improve.md # Product improvement research + PRD generation
|
||||
│ ├── probe.md # Requirement interrogation loop
|
||||
│ ├── reason.md # Adversarial refinement loop
|
||||
│ ├── regression.md # Baseline/candidate stability gate
|
||||
│ ├── scenario.md # 12-dimension edge case loop
|
||||
│ ├── security.md # STRIDE + OWASP loop
|
||||
│ └── ship.md # 8-phase ship pipeline
|
||||
@@ -109,8 +110,9 @@ flowchart TD
|
||||
└── references/
|
||||
├── predict-personas.md # 5 default expert personas
|
||||
├── reason-judge-protocol.md # Blind judge scoring protocol
|
||||
└── security-checklist.md # STRIDE + OWASP checklist
|
||||
├── hooks/autoresearch/ # Hook system (NEW in v2.1.1)
|
||||
├── security-checklist.md # STRIDE + OWASP checklist
|
||||
└── orchestrator-routing.md # Goal archetypes and routing contract
|
||||
├── hooks/autoresearch/ # Claude-only hook system
|
||||
│ ├── hooks.json # Auto-registration
|
||||
│ ├── node-hook-runner.sh # Shell wrapper
|
||||
│ ├── .ckignore # Baseline blocked patterns
|
||||
@@ -122,20 +124,20 @@ plugins/autoresearch/ # Codex distribution
|
||||
.agents/skills/autoresearch/ # Codex agents distribution
|
||||
scripts/
|
||||
├── transform.sh # Single multi-platform transform script
|
||||
├── orchestrate.sh # Orchestrator routing seam (NEW in v2.2.0)
|
||||
├── score-regression.sh # Regression scoring backend (NEW in v2.1.4)
|
||||
├── orchestrate.sh # Orchestrator routing seam
|
||||
├── score-regression.sh # Regression scoring backend
|
||||
└── install.sh # Guided installer
|
||||
|
||||
claude-plugin/
|
||||
├── .claude-plugin/plugin.json # Claude Code metadata — v2.2.1
|
||||
└── hooks/ # Hook system (NEW in v2.1.1)
|
||||
├── .claude-plugin/plugin.json # Claude Code metadata — v2.2.2
|
||||
└── hooks/ # Claude-only hook system
|
||||
plugins/autoresearch/
|
||||
└── .codex-plugin/plugin.json # Codex metadata — v2.2.1-codex.0
|
||||
└── .codex-plugin/plugin.json # Codex metadata — v2.2.2-codex.0
|
||||
```
|
||||
|
||||
## Hook System Architecture
|
||||
|
||||
v2.1.1 adds a 9-hook safety and context injection system. Hooks ship as part of the Claude Code plugin via `hooks/hooks.json` and auto-register on install.
|
||||
The Claude Code distribution includes defense-in-depth hook guardrails via `hooks/hooks.json`. OpenCode and Codex support the core skill/runtime/install surface without claiming hook parity.
|
||||
|
||||
### Hook Lifecycle
|
||||
|
||||
@@ -159,7 +161,7 @@ graph LR
|
||||
SN[stop-notify<br/>SessionEnd]
|
||||
end
|
||||
|
||||
SI -->|creates| STATE["/tmp/ar-session-{hash}.json"]
|
||||
SI -->|creates| STATE["OS temp/ar-session-{hash}.json"]
|
||||
IC -->|reads/writes| STATE
|
||||
SC -->|reads| STATE
|
||||
DRR -->|reads| STATE
|
||||
@@ -168,14 +170,14 @@ graph LR
|
||||
|
||||
### State Management
|
||||
|
||||
Hooks share state via `/tmp/ar-session-{hash}.json` (hash = md5 of cwd + session_id). Created by `session-init` on SessionStart, consumed by context injection hooks, cleaned up by `stop-notify` on SessionEnd.
|
||||
Hooks share `ar-session-{hash}.json` through Node's operating-system temporary directory (hash = md5 of cwd + session_id). It is created by `session-init`, consumed by context injection hooks, and cleaned up by `stop-notify`. The hook runner preserves `TMPDIR`, `TEMP`, and `TMP` for native Windows with Git Bash as well as macOS and Linux.
|
||||
|
||||
### Plugin Distribution
|
||||
|
||||
```
|
||||
claude-plugin/
|
||||
├── .claude-plugin/plugin.json # v2.1.1
|
||||
├── hooks/ # NEW — auto-registers via hooks.json
|
||||
├── .claude-plugin/plugin.json # v2.2.2
|
||||
├── hooks/ # auto-registers via hooks.json
|
||||
│ ├── hooks.json
|
||||
│ ├── node-hook-runner.sh
|
||||
│ ├── lib/
|
||||
@@ -192,14 +194,14 @@ claude-plugin/
|
||||
|----------|-----------|
|
||||
| Thin SKILL.md routing table (41 lines) | ~95% token reduction vs monolith v2.0.x SKILL.md (813 lines) |
|
||||
| Self-contained command files | Each file embeds full protocol — no reference file loading unless needed |
|
||||
| 3 focused reference files (not 13) | Only truly shared content warrants a reference: personas, judge protocol, security checklist |
|
||||
| Focused shared references | Only routing, personas, judge protocol, and security material shared across command boundaries warrants a reference |
|
||||
| No autoresearch-command-spec.json | JSON spec removed; command contracts live in individual command files |
|
||||
| scripts/transform.sh replaces sync-opencode.sh + sync-codex.sh | Single script generates all platform distributions |
|
||||
| TSV with `# metric_direction` comment | Enables evals command to auto-detect direction without user prompt |
|
||||
| 8 TSV status values | baseline, keep, discard, crash, no-op, hook-blocked, metric-error, keep (reworked) |
|
||||
| handoff.json for chain integration | Structured handoff between subcommands; evals reads `*-results.tsv` directly |
|
||||
| Hook system with fail-open design | Hooks never block Claude due to crashes; safety without fragility |
|
||||
| Session state via temp file | Hooks are subprocesses — can't share env vars. `/tmp/ar-session-{hash}.json` persists across hook calls |
|
||||
| Hook system with fail-open design | Hooks never block Claude due to crashes; safety without fragility, with visible redacted diagnostics on failure paths |
|
||||
| Session state via OS temp file | Hooks are subprocesses and cannot share environment state; Node's OS temp directory persists the bounded session record across hook calls |
|
||||
| Iteration-based throttling (every 5th) | Autoresearch is loop-driven; time-based throttling doesn't match iteration cadence |
|
||||
|
||||
## Integration Points
|
||||
|
||||
+2
-2
@@ -4,8 +4,8 @@
|
||||
|
||||
**By [Udit Goenka](https://udit.co)**
|
||||
|
||||
[](https://github.com/uditgoenka/autoresearch/releases)
|
||||
[](LICENSE)
|
||||
[](https://github.com/uditgoenka/autoresearch/releases)
|
||||
[](../LICENSE)
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
+24
-21
@@ -1,4 +1,4 @@
|
||||
# Autoresearch for Codex — v2.1.0
|
||||
# Autoresearch for Codex
|
||||
|
||||
Codex distribution of autoresearch. Same 14 commands, same flags, same output contracts as the Claude Code version. Entry point: `$autoresearch <command>`.
|
||||
|
||||
@@ -7,14 +7,16 @@ Codex distribution of autoresearch. Same 14 commands, same flags, same output co
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npx skills add uditgoenka/autoresearch
|
||||
git clone https://github.com/uditgoenka/autoresearch.git
|
||||
cd autoresearch
|
||||
./scripts/install.sh --codex --global
|
||||
```
|
||||
|
||||
Or via transform script if self-hosting:
|
||||
Maintainers regenerate the checked-in Codex packages with:
|
||||
|
||||
```bash
|
||||
./scripts/transform.sh
|
||||
# Outputs Codex-ready files to codex/
|
||||
./scripts/transform.sh --codex
|
||||
# Outputs plugins/autoresearch/skills/autoresearch/ and .agents/skills/autoresearch/
|
||||
```
|
||||
|
||||
---
|
||||
@@ -35,7 +37,7 @@ All 14 commands follow the same pattern: `$autoresearch <command> [flags]`.
|
||||
|
||||
---
|
||||
|
||||
## All 12 Commands
|
||||
## All 14 Commands
|
||||
|
||||
| Command | Default Iterations | Purpose |
|
||||
|---------|-------------------|---------|
|
||||
@@ -51,6 +53,8 @@ All 14 commands follow the same pattern: `$autoresearch <command> [flags]`.
|
||||
| `$autoresearch reason` | 8 | Adversarial design refinement |
|
||||
| `$autoresearch probe` | 15 | Requirements interrogation |
|
||||
| `$autoresearch evals` | one-shot | Results TSV analysis |
|
||||
| `$autoresearch improve` | 15 | Product research and PRD generation |
|
||||
| `$autoresearch regression` | gate | Baseline/candidate stability verdict |
|
||||
|
||||
---
|
||||
|
||||
@@ -117,19 +121,15 @@ Goal: Full quality pipeline for v2.0 release
|
||||
After `transform.sh` or install:
|
||||
|
||||
```
|
||||
codex/
|
||||
├── autoresearch.sh
|
||||
├── autoresearch_debug.sh
|
||||
├── autoresearch_fix.sh
|
||||
├── autoresearch_security.sh
|
||||
├── autoresearch_ship.sh
|
||||
├── autoresearch_scenario.sh
|
||||
├── autoresearch_predict.sh
|
||||
├── autoresearch_learn.sh
|
||||
├── autoresearch_reason.sh
|
||||
├── autoresearch_probe.sh
|
||||
├── autoresearch_evals.sh
|
||||
└── autoresearch_plan.sh
|
||||
plugins/autoresearch/skills/autoresearch/ # plugin package
|
||||
.agents/skills/autoresearch/ # direct Codex skill package
|
||||
├── SKILL.md
|
||||
├── autoresearch.md
|
||||
├── debug.md ... regression.md
|
||||
├── references/
|
||||
└── scripts/
|
||||
├── orchestrate.sh
|
||||
└── score-regression.sh
|
||||
```
|
||||
|
||||
No `autoresearch-command-spec.json` — each command file is self-contained.
|
||||
@@ -141,14 +141,17 @@ No `autoresearch-command-spec.json` — each command file is self-contained.
|
||||
| Concept | Claude Code | Codex |
|
||||
|---------|-------------|-------|
|
||||
| Slash command | `/autoresearch:debug` | `$autoresearch debug` |
|
||||
| Skills dir | `.claude/skills/` | `codex/` |
|
||||
| User questions | `AskUserQuestion` | Direct question batch |
|
||||
| Skills dir | `.claude/skills/` | `plugins/autoresearch/skills/` or `.agents/skills/` |
|
||||
| User questions | `AskUserQuestion` | `request_user_input` or a direct question batch |
|
||||
| Chain handoff | `handoff.json` | `handoff.json` (identical) |
|
||||
| Results TSV | Same format | Same format |
|
||||
| Output dirs | Same structure | Same structure |
|
||||
|
||||
`handoff.json` and all `*-results.tsv` files are identical across platforms — cross-platform chains work without modification.
|
||||
|
||||
Codex supports the core skill, bundled runtime, installation, and verification
|
||||
surface. Claude Code hook guardrails are not claimed for Codex.
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
@@ -20,7 +20,7 @@ Works on anything with a measurable outcome — code coverage, bundle size, API
|
||||
npx skills add uditgoenka/autoresearch
|
||||
```
|
||||
|
||||
All 14 commands are immediately available. No restart needed.
|
||||
Start a new Claude Code session after installation so every command and reference resolves from the installed package.
|
||||
|
||||
### Manual — Project-Level
|
||||
|
||||
@@ -43,7 +43,7 @@ cp -r autoresearch/.claude/commands/autoresearch ~/.claude/commands/autoresearch
|
||||
```bash
|
||||
git clone https://github.com/uditgoenka/autoresearch.git
|
||||
cd autoresearch
|
||||
./scripts/transform.sh --opencode --global
|
||||
./scripts/install.sh --opencode --global
|
||||
```
|
||||
|
||||
> **OpenCode commands use underscores:** `/autoresearch_debug`, `/autoresearch_fix`, etc.
|
||||
@@ -53,16 +53,22 @@ cd autoresearch
|
||||
```bash
|
||||
git clone https://github.com/uditgoenka/autoresearch.git
|
||||
cd autoresearch
|
||||
./scripts/transform.sh --codex --global
|
||||
./scripts/install.sh --codex --global
|
||||
```
|
||||
|
||||
> **Codex uses `$` mention syntax:** `$autoresearch`, `$autoresearch debug`, `$autoresearch fix`, etc.
|
||||
|
||||
### Verify Installation
|
||||
|
||||
- **Claude Code:** Type `/autoresearch` — if the setup wizard appears, you are ready.
|
||||
- **OpenCode:** Type `/autoresearch` — same wizard, underscore subcommands.
|
||||
- **Codex:** Type `$autoresearch` or run `/skills` to confirm it is listed.
|
||||
- **Claude Code:** Start a new session, invoke `/autoresearch`, and confirm the guided install registered the hook surface.
|
||||
- **OpenCode:** Invoke `/autoresearch`; underscore subcommands such as `/autoresearch_debug` load from the installed package.
|
||||
- **Codex:** Invoke `$autoresearch` or run `/skills`; subcommands such as `$autoresearch debug` load from the installed package.
|
||||
|
||||
Each installed skill contains `scripts/orchestrate.sh` and
|
||||
`scripts/score-regression.sh`. The release gate proves both helpers execute from
|
||||
a disposable configuration root outside the checkout. Supported capabilities
|
||||
run on macOS, Linux, and native Windows with Git Bash. Hook guardrails are a
|
||||
Claude Code-only integration.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+16
-22
@@ -1,14 +1,14 @@
|
||||
# Hooks Reference
|
||||
|
||||
Autoresearch v2.1.1 ships 9 hooks that fire automatically on every Claude Code session. Three categories: safety gates, context injection, and quality + notifications.
|
||||
Autoresearch v2.2.2 ships Claude Code-only hook guardrails that fire automatically on every Claude Code session. They are defense in depth, not a security sandbox or a substitute for host permissions. Three categories: safety gates, context injection, and quality + notifications.
|
||||
|
||||
## How Hooks Work
|
||||
|
||||
Hooks are Node.js scripts that intercept Claude Code events. They read JSON from stdin, make a decision, and write JSON to stdout with an exit code:
|
||||
- **Exit 0** — allow (optionally inject context)
|
||||
- **Exit 0** — allow, ask through the native host boundary, or inject context
|
||||
- **Exit 2** — block (with error message)
|
||||
|
||||
All hooks follow a fail-open design: if a hook crashes, it exits 0 and never blocks your work.
|
||||
All hooks follow a fail-open design: if a hook crashes, it exits 0, emits a visible redacted diagnostic, and never blocks your work.
|
||||
|
||||
## Safety Gates (PreToolUse)
|
||||
|
||||
@@ -50,13 +50,13 @@ Blocks access to files that may contain secrets.
|
||||
**Allowed exceptions:** `.env.example`, `.env.sample`, `.env.template`, `.env.test`
|
||||
|
||||
**Approval flow:**
|
||||
1. Hook blocks the read with a message
|
||||
2. Claude asks you for permission via AskUserQuestion
|
||||
3. You approve
|
||||
4. Claude retries with `APPROVED:` prefix on the file path
|
||||
5. Hook allows the read and strips the prefix
|
||||
1. Hook detects a clear sensitive-file access
|
||||
2. Claude asks you for permission with the host's native `ask` decision
|
||||
3. You approve in the host permission UI
|
||||
4. The read, copy, upload, or mutation proceeds only after host approval
|
||||
5. If the host cannot represent `ask`, the operation is denied with safe remediation
|
||||
|
||||
**Bash:** Warn only (injects a context warning but doesn't block).
|
||||
**Bash:** Clear sensitive-file operations also ask; ambiguous sensitive-looking text warns only.
|
||||
|
||||
**Disable:** `export AR_DISABLE_PRIVACY_BLOCK=1`
|
||||
|
||||
@@ -64,13 +64,7 @@ Blocks access to files that may contain secrets.
|
||||
|
||||
Blocks destructive bash commands.
|
||||
|
||||
**Blocked:**
|
||||
- `git push --force`, `git push -f` (regular `git push` is allowed)
|
||||
- `git reset --hard`
|
||||
- `git clean -f`, `git clean -fd`
|
||||
- `git branch -D`
|
||||
- `git checkout .`, `git restore .`
|
||||
- `rm -rf /`, `rm -rf ~`, `rm -rf .`
|
||||
**Blocked:** destructive forms such as force-push, hard reset, forced clean, force-delete branches, and whole-tree restores/removals. Equivalent flag orderings and bundled variants are treated the same.
|
||||
|
||||
**Disable:** `export AR_DISABLE_DANGEROUS_CMD_BLOCK=1`
|
||||
|
||||
@@ -133,7 +127,7 @@ Sets up project context at the start of every session.
|
||||
|
||||
**What it does:**
|
||||
- Detects git root and current branch
|
||||
- Creates session state file (`/tmp/ar-session-{hash}.json`)
|
||||
- Creates `ar-session-{hash}.json` in the operating system's temporary directory
|
||||
- Cleans up stale session files older than 24 hours
|
||||
- Injects project root, branch, plans path, and reports path
|
||||
|
||||
@@ -165,12 +159,12 @@ Works with Slack, Discord, and any webhook that accepts JSON POST.
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `AR_DISABLE_{HOOK_NAME}` | Disable a specific hook (e.g., `AR_DISABLE_SCOUT_BLOCK=1`) | unset (enabled) |
|
||||
| `AR_DISABLE_{HOOK_NAME}` | Troubleshooting control that disables a specific hook; not a tamper-resistant security control | unset (enabled) |
|
||||
| `AR_NOTIFY_WEBHOOK` | Webhook URL for session completion notifications | unset (no webhook) |
|
||||
|
||||
## Session State
|
||||
|
||||
All hooks share state via `/tmp/ar-session-{hash}.json`. The hash is derived from your project directory and session ID. Fields:
|
||||
All hooks share `ar-session-{hash}.json` in the operating system's temporary directory (`os.tmpdir()` in Node). The hook runner preserves `TMPDIR`, `TEMP`, and `TMP`, so this works on macOS, Linux, and native Windows with Git Bash. The hash is derived from your project directory and session ID. Fields:
|
||||
|
||||
- `projectRoot` — git root or cwd
|
||||
- `plansPath` — plans/ directory
|
||||
@@ -187,12 +181,12 @@ The file is created by session-init and cleaned up by stop-notify.
|
||||
Hooks append one diagnostic JSON line per event (block / inject / skip decisions) to a per-project log under your **global** home directory, never inside the project repo:
|
||||
|
||||
```
|
||||
~/.claude/hooks/.logs/{project-name}-{hash}/hook-log.jsonl
|
||||
~/.claude/hooks/.logs/{project-hash}/hook-log.jsonl
|
||||
```
|
||||
|
||||
The directory is keyed by the project's working directory, so logs from every repo stay separated yet out of the repos themselves — nothing lands in a project's `.claude/` and nothing can be accidentally committed. Logging is fail-open (a write error never blocks a hook) and write-only (no part of autoresearch reads these back; they exist purely for debugging hook behavior). Safe to delete anytime.
|
||||
The directory is keyed by a hash of the project's working directory, so logs from every repo stay separated yet out of the repos themselves — nothing lands in a project's `.claude/` and nothing can be accidentally committed. Logging is fail-open (a write error never blocks a hook) and write-only (no part of autoresearch reads these back; they exist purely for debugging hook behavior). Safe to delete anytime.
|
||||
|
||||
Records from the safety-gate hooks (`dangerous-cmd-block`, `privacy-block`, `scout-block`) may include the blocked command text or file path, so treat `~/.claude/hooks/.logs/` as mildly sensitive — it stays on your own machine and is never written into a repo, but don't share it wholesale.
|
||||
Records contain bounded metadata only: timestamp, hook name, action, safe category, and remediation where applicable. Raw commands, tool inputs, paths, and secret values are intentionally excluded.
|
||||
|
||||
## File Structure
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "autoresearch",
|
||||
"version": "2.2.1-codex.0",
|
||||
"version": "2.2.2-codex.0",
|
||||
"description": "Autonomous improvement engine for Codex. 14 commands: iterate, plan, debug, fix, security, ship, scenario, predict, learn, reason, probe, evals, improve, regression.",
|
||||
"author": {
|
||||
"name": "Udit Goenka",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: autoresearch
|
||||
description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
|
||||
version: 2.2.1
|
||||
version: 2.2.2
|
||||
---
|
||||
|
||||
# Autoresearch — Autonomous Goal-directed Iteration
|
||||
|
||||
+32
-87
@@ -4,119 +4,64 @@
|
||||
|
||||
| Type | Pattern | When to use | Example |
|
||||
|------|---------|-------------|---------|
|
||||
| **Patch** | `v2.1.X` | Bugfixes, typos, small updates, dependency bumps | `v2.1.1` |
|
||||
| **Patch** | `vX.Y.Z` | Bugfixes, typos, small updates, dependency bumps | `v2.2.2` |
|
||||
| **Minor** | `v2.X.0` | New features, new commands, significant changes | `v2.2.0` |
|
||||
| **Major** | `vX.0.0` | Breaking changes, full rewrites | `v3.0.0` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Patch release (bugfix)
|
||||
./scripts/release.sh 2.1.1 --title "Fix scenario timeout handling"
|
||||
|
||||
# Minor release (new feature)
|
||||
./scripts/release.sh 2.2.0 --title "New Feature Name"
|
||||
# Stabilization release
|
||||
./scripts/release.sh 2.2.2 --title "Autoresearch v2.2.2 stabilization"
|
||||
```
|
||||
|
||||
## What the Script Does
|
||||
## Release Gates
|
||||
|
||||
```
|
||||
[1/7] Create release branch (release/X.Y.Z)
|
||||
[2/7] Bump versions:
|
||||
→ claude-plugin/.claude-plugin/plugin.json (version field)
|
||||
→ .claude-plugin/marketplace.json (version fields — top-level + plugins array)
|
||||
→ .claude/skills/autoresearch/SKILL.md (version frontmatter)
|
||||
→ README.md (version badge)
|
||||
→ guide/README.md (version badge)
|
||||
[3/7] Sync distribution files:
|
||||
→ Copies .claude/commands/autoresearch/ → claude-plugin/commands/autoresearch/
|
||||
→ Copies .claude/skills/autoresearch/ → claude-plugin/skills/autoresearch/
|
||||
→ Ensures claude-plugin/ distribution matches .claude/ source of truth
|
||||
[4/7] Pause for doc review:
|
||||
→ Shows changelog since last tag
|
||||
→ Prompts you to review README.md, guide/, CONTRIBUTING.md
|
||||
→ You can edit in another terminal, then continue
|
||||
[5/7] Commit all release changes
|
||||
[6/7] Push branch + create PR against master
|
||||
[7/7] Wait for your "merge" confirmation:
|
||||
→ Merges PR
|
||||
→ Tags the merge commit
|
||||
→ Creates GitHub release with auto-generated notes
|
||||
```
|
||||
The preparation script stops after the PR is opened. It does not merge, tag, or publish.
|
||||
|
||||
| Gate | Verified by |
|
||||
|------|-------------|
|
||||
| Identity and workspace | clean tree, `master`, `gh`, `uditgoenka` Git author, `uditgoenka` GitHub login |
|
||||
| Transform cleanliness | `bash scripts/transform.sh`, then `git diff --exit-code` and `git status --porcelain` |
|
||||
| Version alignment | `claude-plugin/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.claude/skills/autoresearch/SKILL.md`, `README.md`, `guide/README.md`, and the generated `SKILL.md` mirrors |
|
||||
| Release suites | `bash tests/test-hooks.sh`, `bash tests/test-orchestrator.sh`, `bash tests/test-regression.sh`, `bash tests/test-maintenance.sh` |
|
||||
| Clean-install smoke | disposable installs for Claude, OpenCode, and Codex run bundled `scripts/orchestrate.sh classify`, `scripts/score-regression.sh verdict`, and `scripts/score-regression.sh rubric` from outside the source checkout |
|
||||
| Publication boundary | PR creation only; merge, tag creation, and GitHub release creation are separate explicit owner actions |
|
||||
|
||||
## Pre-Release Checklist
|
||||
|
||||
Before running the script, verify:
|
||||
|
||||
- [ ] All tests pass
|
||||
- [ ] No uncommitted changes in working tree
|
||||
- [ ] You're on the `master` branch
|
||||
- [ ] `gh` CLI is authenticated
|
||||
- [ ] `git config user.name` is `uditgoenka`
|
||||
- [ ] `gh api user --jq .login` is `uditgoenka`
|
||||
- [ ] The working tree is clean and on `master`
|
||||
- [ ] `scripts/orchestrate.sh` and `scripts/score-regression.sh` are executable in every installed bundle
|
||||
- [ ] `bash tests/test-hooks.sh`
|
||||
- [ ] `bash tests/test-orchestrator.sh`
|
||||
- [ ] `bash tests/test-regression.sh`
|
||||
- [ ] `bash tests/test-maintenance.sh`
|
||||
|
||||
## Doc Review Guide
|
||||
## Release-Readiness Matrix
|
||||
|
||||
At step [4/7], the script pauses and shows the changelog. Review these files:
|
||||
The GitHub Actions matrix runs on Ubuntu, macOS, and Windows/Git Bash. Every
|
||||
job is required; do not mark a release candidate ready while any job is not
|
||||
green at the exact head.
|
||||
|
||||
### README.md
|
||||
- **Version badge** (auto-updated by script)
|
||||
- **Commands table** — any new commands added?
|
||||
- **Quick Decision Guide** — new use cases?
|
||||
- **Repository Structure** — new files in the tree?
|
||||
- **FAQ** — new questions from issues/discussions?
|
||||
## Release Flow
|
||||
|
||||
### guide/
|
||||
- **guide/README.md** — version badge (auto-updated by script)
|
||||
- **Individual command guides** — any new commands or flags?
|
||||
- **guide/examples-by-domain.md** — new domain examples to add?
|
||||
- **guide/chains-and-combinations.md** — new chain patterns possible?
|
||||
- **guide/advanced-patterns.md** — new verify commands, MCP patterns, FAQ?
|
||||
|
||||
### guide/scenario/
|
||||
- **guide/scenario/README.md** — scenario guide chain suggestions updated?
|
||||
- **Domain-specific guides** — new scenario domains or patterns?
|
||||
|
||||
### CONTRIBUTING.md
|
||||
- **Repository Structure** — does the tree reflect new files?
|
||||
- **What Each File Does** — any new files to document?
|
||||
- **Adding a New Sub-Command** — steps still accurate?
|
||||
- **High-Value Contributions** — new contribution types?
|
||||
|
||||
### COMPARISON.md
|
||||
- **Subcommand count** — does it match the current number?
|
||||
- **Feature comparison table** — any new capabilities to add?
|
||||
|
||||
### Tips
|
||||
- Edit docs in another terminal while the script is paused
|
||||
- Type `skip` at the prompt to continue without doc changes
|
||||
- The script stages any doc changes automatically (README.md, guide/, CONTRIBUTING.md, COMPARISON.md)
|
||||
The release script prepares the branch, verifies the release gates, commits, pushes, and opens the PR. It stops there.
|
||||
|
||||
## Distribution Sync
|
||||
|
||||
The `claude-plugin/` directory is the **distribution package** — what Claude Code downloads when users install the plugin. The `.claude/` versions are the development source of truth.
|
||||
|
||||
**Why `claude-plugin/` and not root?** Claude Code's plugin caching downloads the `source` directory. If `source` is `"./"` (the entire repo), the cached plugin contains its own `.claude-plugin/marketplace.json`, causing Claude Code to recursively cache the plugin inside itself — hitting macOS's 1024-char path limit (`ENAMETOOLONG`). Pointing `source` to `./claude-plugin` (an isolated distribution directory without `marketplace.json`) breaks this recursion.
|
||||
Before every release, `scripts/transform.sh` regenerates `claude-plugin/` and the generated mirrors from `.claude/`.
|
||||
|
||||
**Before every release**, the script syncs `claude-plugin/` from `.claude/`:
|
||||
```bash
|
||||
# What the sync step does:
|
||||
cp .claude/commands/autoresearch.md claude-plugin/commands/autoresearch.md
|
||||
cp .claude/commands/autoresearch/*.md claude-plugin/commands/autoresearch/
|
||||
cp .claude/skills/autoresearch/SKILL.md claude-plugin/skills/autoresearch/SKILL.md
|
||||
cp .claude/skills/autoresearch/references/*.md claude-plugin/skills/autoresearch/references/
|
||||
```
|
||||
## Merge and Recovery
|
||||
|
||||
If you add a new subcommand during development, it goes into `.claude/` first. The release script ensures `claude-plugin/` stays in sync.
|
||||
Merge, tag creation, and GitHub release creation are separate explicit owner actions after PR review.
|
||||
|
||||
## Abort and Resume
|
||||
|
||||
If you type `abort` at the merge prompt:
|
||||
```bash
|
||||
# The PR stays open. Merge later with:
|
||||
gh pr merge <PR_URL> --merge --delete-branch
|
||||
|
||||
# Or clean up:
|
||||
git checkout master && git branch -D release/X.Y.Z
|
||||
```
|
||||
If an exact-release smoke check fails after tagging, leave the existing tag immutable and cut a new patch version instead. Do not move `v2.2.2`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -526,9 +526,34 @@ for mirror in .claude claude-plugin .agents .opencode plugins/autoresearch; do
|
||||
fi
|
||||
done
|
||||
|
||||
# Canonical skill spec carries the 2.2.1 version stamp.
|
||||
assert_contains "2.2.1" "$(grep -m1 '^version:' "$REPO_ROOT/.claude/skills/autoresearch/SKILL.md")" \
|
||||
"parity: canonical SKILL.md version is 2.2.1"
|
||||
# Every skill distribution carries the canonical 2.2.2 version stamp.
|
||||
for skill in \
|
||||
.claude/skills/autoresearch/SKILL.md \
|
||||
claude-plugin/skills/autoresearch/SKILL.md \
|
||||
.opencode/skills/autoresearch/SKILL.md \
|
||||
.agents/skills/autoresearch/SKILL.md \
|
||||
plugins/autoresearch/skills/autoresearch/SKILL.md; do
|
||||
assert_eq "version: 2.2.2" "$(grep -m1 '^version:' "$REPO_ROOT/$skill")" \
|
||||
"parity: $skill version is 2.2.2"
|
||||
done
|
||||
|
||||
VERSION_SURFACES=$(node - "$REPO_ROOT" <<'NODE'
|
||||
const root = process.argv[2];
|
||||
const read = (file) => require(`${root}/${file}`);
|
||||
console.log([
|
||||
read('.claude-plugin/marketplace.json').version,
|
||||
read('.claude-plugin/marketplace.json').plugins[0].version,
|
||||
read('claude-plugin/.claude-plugin/plugin.json').version,
|
||||
read('plugins/autoresearch/.codex-plugin/plugin.json').version,
|
||||
].join('\n'));
|
||||
NODE
|
||||
)
|
||||
assert_eq $'2.2.2\n2.2.2\n2.2.2\n2.2.2-codex.0' "$VERSION_SURFACES" \
|
||||
"parity: release manifests use canonical and Codex package versions"
|
||||
for badge in README.md guide/README.md; do
|
||||
assert_contains "version-2.2.2-blue" "$(grep -m1 'img.shields.io/badge/version-' "$REPO_ROOT/$badge")" \
|
||||
"parity: $badge badge is 2.2.2"
|
||||
done
|
||||
|
||||
# No colon-form subcommand may leak into the space/underscore mirrors.
|
||||
for mirror in .agents .opencode plugins/autoresearch; do
|
||||
|
||||
Reference in New Issue
Block a user