⚠️ Breaking change (0.3.0):PLAN.md/RESULTS.mdare replaced by thesuperRA/task tree. Existing projects are detected and offered migration automatically (or runsuperra task migrate from-plan); to stay on the previous model, pin the install to the frozenv0.1.2tag. See RELEASE-NOTES for the migration note and full history, including the 0.2.0 workflow-skill rename.
⚠️ Beta testing stage. superRA is under active development and updates land frequently. Bug reports are welcome — please open an issue.
📖 Read the documentation → — start with the Quickstart (one analysis end to end in ~20 min), then the Domain Skills and Utility Skills pages, the Workflows section, and a live task-tree Showcase.
superRA turns an AI coding agent into a disciplined research assistant. It runs on Claude Code and Codex, and ships:
- A task-tree dashboard — a live task tree of your project that keeps every important piece of state committed in your repo rather than trapped in an agent's context, so you can monitor progress in real time and hand any unfinished task to a fresh agent without losing the thread. The Showcase links a live export of a real one.
- An adaptive plan-implement-integrate workflow with autonomous implementer–reviewer execution by default, a closely steered interactive mode, and long-term reproducibility.
- Domain skills that teach agents the right discipline for the research at hand and enforce it as they go — currently data analysis, theory modeling, academic writing, and slide design, with literature review on the roadmap.
- Utility skills that teach agents practical mechanics — loading papers from Zotero, writing results in well-formed Markdown, syncing data across worktrees, and more.
AI agents are fast but undisciplined. They generate more code than anyone will carefully review. They drift as the context window fills, and starting fresh loses the thread of what was done and why. They drop half the sample before a regression runs, then report "everything looks good." superRA brings review discipline to every step, the domain skill enforces the right protocol as the work goes, and the integration phase folds each task into your codebase so what lands is coherent, not a pile of single-shot outputs.
Social-science research needs a different rhythm than software engineering: it is fluid and exploratory, ex-ante unit tests are often impossible to write, and the outputs need human judgement to evaluate. superRA adapts an agentic-coding workflow spine to that rhythm and keeps the human firmly in the loop.
A superRA project moves through three phases — PLAN → IMPLEMENT → INTEGRATE. In PLAN, the agent scopes your request and decomposes it into a task tree — a directory of small task.md files, each holding one unit of work — that you approve before any code is written. In IMPLEMENT, autonomous subagent mode runs implementer and reviewer seats and advances work only on APPROVE; interactive mode lets the main agent co-edit and execute with you, always self-reviewing and asking whether to run independent review now, defer it, or skip it. In INTEGRATE, you first choose which results belong in the permanent record, how that record should look, and whether documentation or additional drift tests should protect each result. The agent syncs with your base branch, writes the permanent record, proposes pruning and other refactoring in one temporary task, asks you to approve the finished record and proposal together, then executes and ships.
flowchart TB
PLAN["<b>PLAN</b><br/>scope · task decomposition<br/>superRA/ task tree"]
IMPLEMENT["<b>IMPLEMENT</b> (per task)<br/>implementer ⇄ reviewer loop<br/>APPROVE advances · REVISE loops back"]
INTEGRATE["<b>INTEGRATE</b><br/>Choose results & protection<br/>Sync with base<br/>Mature documentation & task tree<br/>Review refactoring proposal<br/>Execute & finish"]
FINISHED(["finished"])
PLAN --> IMPLEMENT
IMPLEMENT --> INTEGRATE
INTEGRATE --> FINISHED
IMPLEMENT -. "plan change" .-> PLAN
INTEGRATE -. "plan change" .-> PLAN
classDef phase fill:#eef7ff,stroke:#0366d6,color:#000
classDef terminal fill:#e8f5e9,stroke:#2e7d32,color:#000
class PLAN,IMPLEMENT,INTEGRATE phase
class FINISHED terminal
Research is rarely this linear: an unanticipated issue mid-implementation, or a scope change after integration, routes back to planning and resumes at the right point, leaving unrelated finished work untouched. Run ./superRA/superra dashboard from a project terminal to watch and steer any of it through the tree, DAG, and kanban views. The Quickstart walks a full cycle end to end, covering re-entry, the autonomy-with-human-in-the-loop model, and the dashboard's live serve and branch-snapshot sharing.
Claude Code (v2.1+) can install plugins directly from a GitHub repo. Add superRA as a marketplace and install the plugin:
claude plugin marketplace add FuZhiyu/superRA
claude plugin install superRA@superRAThat's it — restart Claude Code (or start a new session) and the skills, agents, and hooks are available.
To update later:
claude plugin marketplace update superRA
claude plugin update superRAFor Codex setup and a local-clone install (to track or modify superRA itself), see docs/README.codex.md. Any other harness that supports skills and subagents installs the same plugin sources.
This release replaces the legacy PLAN.md / RESULTS.md files with the superRA/ task tree. Existing projects keep working: superRA detects a legacy PLAN.md at session start and offers to migrate it (superra task migrate from-plan). See the superRA docs for details.
To stay on the previous version instead, pin the install to the frozen v0.1.2 tag:
claude plugin marketplace add FuZhiyu/superRA@v0.1.2
claude plugin install superRA@superRADesign principles, DRY / composability rules, skill-design patterns, and the extension path for adding a new domain vertical live in CLAUDE.md. Read it before modifying skills, hooks, or agent files.
superRA started as a fork of Superpowers by Jesse Vincent. The upstream project provides the plugin infrastructure, skill system, and several general-purpose skills that superRA inherits and extends. Superpowers and similar agentic-coding frameworks are built for software engineering, where tasks are verifiable against unit tests or objective metrics; superRA adapts the same workflow spine to scientific research instead — exploratory, iterative, and fluid.
MIT License — see the LICENSE file for details.