v2.1.0 is here — I rewrote EVERYTHING from scratch and tokens dropped 95%

[uditgoenka]

I deleted 813 lines and replaced them with 41. And everything got BETTER.

I just shipped v2.1.0 and this isn't a feature release. This is a ground-up architectural rebuild. Every file. Every guide. Every doc. Rewritten from scratch.

Let me tell you why.

---

The problem I couldn't ignore anymore

v2.0.x had one SKILL.md file: 813 lines, ~100K tokens. It loaded on EVERY. SINGLE. INVOCATION.

Want a quick /autoresearch:plan? 100K tokens loaded.
Just need /autoresearch:evals? 100K tokens loaded.
Running a 5-iteration debug? 100K tokens loaded.

That's like importing the entire React codebase to render a <div>. It worked — but it was wasteful, slow, and getting worse with every command I added.

---

The fix: thin routing + self-contained commands

Before (v2.0.x)

SKILL.md (813 lines, ~100K tokens) <- loaded EVERY invocation
├── 13 reference files (overlapping, tangled)
├── autoresearch-command-spec.json (JSON registry)
├── autoresearch_cli.py (Python wrapper)
├── sync-opencode.sh (manual sync)
└── sync-codex.sh (manual sync)

After (v2.1.0)

SKILL.md (41 lines, ~2K tokens) <- thin routing table ONLY
├── 12 self-contained command files (~100 lines each, ~5-8K tokens)
├── 3 focused reference files (loaded only when needed)
└── scripts/transform.sh (single multi-platform transform)

~95% token reduction. Not 20%. Not 50%. Ninety-five percent.

A /autoresearch:plan call now loads ~5K tokens instead of ~100K. The routing table is 41 lines — it literally just maps command names to files. Each command file embeds its FULL protocol — no external loading unless it genuinely needs a shared resource.

---

12 commands (evals is brand new)

Every command rewritten. Every one now has bounded defaults — no more "runs forever unless you stop it."

Command	Type	Default	What it does
/autoresearch	Loop	25	Core metric-driven improvement loop
/autoresearch:plan	One-shot	—	Goal → config wizard
/autoresearch:debug	Loop	15	Hypothesis-driven bug investigation
/autoresearch:fix	Loop	20	Error-count reduction (error → zero)
/autoresearch:security	Loop	15	STRIDE + OWASP audit with auto-fix
/autoresearch:ship	Linear	8 phases	Pre-merge quality pipeline
/autoresearch:scenario	Loop	20	12-dimension edge case exploration
/autoresearch:predict	One-shot	—	5-persona swarm analysis + debate
/autoresearch:learn	Loop	10	Autonomous documentation engine
/autoresearch:reason	Loop	8	Adversarial refinement (judge + critic)
/autoresearch:probe	Loop	15	Requirement interrogation (8 personas)
/autoresearch:evals	One-shot (NEW)	—	TSV analysis: trends, plateaus, anomalies

Bounded defaults mean you can just type /autoresearch:debug and it'll run 15 iterations and stop. Want more? Iterations: 50. Want unlimited? Iterations: unlimited. You have to explicitly ask for infinity now.

---

NEW: /autoresearch:evals — your iteration analytics dashboard

This one's been requested since v1.7.0. After any loop run, you've got a *-results.tsv file sitting there with all the data. But reading raw TSV? Painful.

Now:

/autoresearch:evals

One shot. It reads your TSV, dynamically detects columns, and tells you:

• Trends — is the metric actually improving?
• Plateaus — did you stop learning at iteration 12 but run 25?
• Velocity — how much improvement per iteration?
• Anomalies — which iterations regressed and why?
• Diminishing returns — should you have stopped earlier?

Even better: inline checkpoints. Add --evals to ANY looping command and it prints a 5-line checkpoint at floor(max_iterations/3). Running 30 iterations? You get a health check at iteration 10 and 20 automatically.

/autoresearch --evals
Iterations: 30
Goal: Increase test coverage to 95%
...

Backward compatible with v2.0.x TSV files — it just works.

---

Chain handoff via handoff.json

Commands now produce structured handoff files that downstream commands consume automatically:

/autoresearch:predict --chain debug,fix,ship

This runs:

1. predict — 5 personas analyze your code, debate findings
2. debug — receives ranked hypotheses, tests them in priority order
3. fix — receives confirmed root causes, fixes in cascade-aware order
4. ship — receives all changes, runs 8-phase quality pipeline

Zero manual context transfer. The handoff.json schema carries scope, findings, priorities, and constraints between commands.

---

Universal flags on every command

Flag	What it does
Iterations: N	Override the default
Iterations: unlimited	Remove the cap
--evals	Checkpoint at floor(N/3)
--evals-interval N	Custom checkpoint interval
--chain <targets>	Chain to downstream command(s)

These work on EVERY looping command. Consistency across the board.

---

3 focused reference files (was 13)

The old 13 workflow reference files — autonomous-loop-protocol, core-principles, debug-workflow, fix-workflow, learn-workflow, plan-workflow, predict-workflow, probe-workflow, reason-workflow, results-logging, scenario-workflow, security-workflow, ship-workflow — are GONE.

Replaced by 3 files that only load when their specific command needs them:

File	Loaded by
security-checklist.md	/autoresearch:security only
predict-personas.md	/autoresearch:predict only
reason-judge-protocol.md	/autoresearch:reason only

Everything else? Embedded in the command files themselves. Self-contained means self-contained.

---

Multi-platform from a single source

Platform	Syntax	How to sync
Claude Code	/autoresearch:debug	Source of truth
OpenCode	/autoresearch_debug	scripts/transform.sh --opencode
Codex	$autoresearch debug	scripts/transform.sh --codex

One script. scripts/transform.sh. Replaces the old sync-opencode.sh + sync-codex.sh pair. Run it once, all platforms sync.

---

Documentation: ALL rewritten from scratch

I'm not exaggerating. Every single doc file:

• README.md — rewritten
• docs/ (7 files) — system architecture, codebase summary, code standards, project overview, development roadmap, changelog, project changelog — ALL rewritten
• guide/ (18 files) — every command guide, getting started, chains, advanced patterns, examples by domain, Codex guide — ALL rewritten
• CONTRIBUTING.md — rewritten
• COMPARISON.md — rewritten

70 files changed. +4,083 lines added. -16,191 lines removed. Net reduction of 12,108 lines while adding a brand new command and more comprehensive docs.

The guides now have: flags tables, depth presets, chain patterns, practical examples, anti-patterns, and cross-links to related commands. Every guide follows the same structure so you always know where to find what you need.

---

Files I deleted (and don't miss)

Gone	Why
autoresearch-command-spec.json	Contracts live in command files now
autoresearch_cli.py	Python wrapper was dead weight
install_local_plugin.py	Replaced by scripts/install.sh
sync-opencode.sh	Replaced by transform.sh
sync-codex.sh	Replaced by transform.sh
13 old reference files	Replaced by 3 focused ones

---

The numbers

Metric	v2.0.x	v2.1.0	Change
SKILL.md lines	813	41	-95%
Tokens per invocation	~100K	~5-8K	-95%
Reference files	13	3	-77%
Commands	11	12	+1 (evals)
Platform sync scripts	2	1	-50%
Total docs lines	~16K	~4K	-75%

---

Get it now

npx skills add uditgoenka/autoresearch

If you're already installed, update and you're good. Your existing TSV files are backward compatible.

---

What's next?

With the modular architecture in place, adding new commands is trivial — create one ~100-line file, add one row to the routing table, run transform.sh. The monolith tax is gone.

I have ideas for what's coming, but I'd rather hear from you: what commands would make your workflow better?

Drop a comment. Start a discussion. Open an issue.

---

Full release notes | Guide | Getting started

This was the biggest single release in autoresearch history. And it's just the foundation.

— Udit