superRA

superRA

⚠️ Breaking change (0.2.0): the three workflow phase skills were renamed — planning-workflow → superplan, implementation-workflow → superimplement, integration-workflow → superintegrate — to avoid colliding with Claude Code's Workflow tool / /workflows. Update any saved Skill(superRA:planning-workflow|implementation-workflow|integration-workflow) calls to the new ids, and refresh globally-installed Codex agents by rerunning codex-superra-setup. See RELEASE-NOTES for the migration note.

superRA turns AI coding agents into disciplined Research Assistants. It ships:

1. An adaptive plan-implement-integrate workflow that enforces reviewer sign-off at every step and keeps results reproducible long-term.
2. Domain skills that teach agents how to do research work properly — currently economic data analysis, theory-modeling, academic writing, and slide design; literature review and simulation remain on the roadmap.
3. Utility skills for technical reports in markdown, gated integration checklists, semantic branch merges, and data sync across git worktrees.

superRA is inspired by the Superpowers plugin, which centers on test-driven software development. superRA adapts the same spine to scientific research, which is exploratory, iterative, and fluid.

superRA is compatible with Claude Code, Codex, and any other harness that supports skills and subagents. See below for installation.

Why superRA?

AI agents are fast but undisciplined:

• Agents generate far more code than anyone will carefully review, often inconsistent with the existing codebase.
• As the context window fills, agents become more error-prone — but starting fresh loses the thread of what was done and why.
• After several iterations, the results quietly drift from the original, and neither you nor the agent can reconstruct why.
• Half the sample is silently dropped before a regression runs, while the agent declares "everything looks good".

superRA brings discipline to the agent on three fronts. An implementer–reviewer pair sits at every step so no result ships without adversarial review. Domain skills teach the agent the right protocol for the work at hand (for data analysis: always describe before you transform; for theory-modeling: define objects and assumptions before you manipulate the equations; for slide design: reason from the audience's context before optimizing the slide). And an explicit integration phase folds each task into the existing codebase and maturing documentation, so what lands on main is coherent rather than a pile of single-shot outputs.

The Plan-Implement-Integrate Workflow

This workflow assumes basic familiarity with git branch/PR workflow; worktrees help but are optional.

superRA organizes work into three phases: PLAN → IMPLEMENT → INTEGRATE. Each phase corresponds to a workflow skill to teach agents how to carry out in order, and a using-superra skill serves as the shared disciplines and knowledges across agents. The phases are domain-agnostic; the domain skill supplies the discipline that applies inside each phase. The phases form a cycle, not a pipeline: a discovery during IMPLEMENT, a reviewer request during INTEGRATE, or a scope change after merge all route back through superplan §User Feedback and Changing Plans, which walks the task DAG and resumes at the right re-entry point.

flowchart TB
    PLAN["<b>PLAN</b><br/>scope · task decomposition<br/>PLAN.md + RESULTS.md"]
    IMPLEMENT["<b>IMPLEMENT</b> (per task)<br/>implementer ⇄ reviewer loop<br/>APPROVE advances · REVISE loops back"]
    INTEGRATE["<b>INTEGRATE</b><br/>Protect results <br/>Sync with base<br/>Integrate/refactor<br/>Document<br/>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

To invoke the workflow, use the keywords: using superRA, make a plan on..., implement according to the plan, integrate it with the update on the main, ... — or name a phase skill directly: superplan, superimplement, superintegrate.

Key principles of the workflow