superartes

Superartes

Superartes ("super skills" in Latin) is a composable skills library that provides structured development workflows for AI coding agents (primarily Claude Code, Cursor, and OpenAI's Codex). It enforces discipline through skills that trigger automatically: brainstorming before coding leading to designs & plans, reviews, TDD, systematic debugging, subagent-driven development with two-stage review, and feature branch isolation.

How it works

It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it doesn't just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.

Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.

After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.

Next up, once you say "go", it launches a subagent-driven-development process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.

There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superartes.

Installation

Claude Code

Register this repository as a marketplace, then install:

/plugin marketplace add andybrandt/superartes
/plugin install superartes@superartes

To update after new commits are pushed:

/plugin marketplace update superartes

For local development/testing without pushing to GitHub:

claude --plugin-dir /path/to/superartes

Codex

Register this repository as a Codex plugin marketplace:

codex plugin marketplace add andybrandt/superartes

Then open the plugin directory and install Superartes:

/plugins

To update after new commits are pushed:

codex plugin marketplace upgrade superartes

OpenCode

Caveat: Superartes is not tested with OpenCode. No guarantees it will work.

Add to your opencode.json:

{
  "plugin": ["superartes@git+https://github.com/andybrandt/superartes.git"]
}

Gemini CLI

Caveat: Superartes is not tested with Gemini CLI and there are no guarantees it will work. Note also that Gemini CLI is no longer used as the external reviewer — reviews now run through Codex CLI (see the Skills Library).

gemini extensions install https://github.com/andybrandt/superartes

Verify Installation

Start a new session and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superartes skill.

The Basic Workflow

The agent walks through a sequence of skills, each triggering automatically at its phase. Spec, plan, and feature branch each sit at known points in the lifecycle:

1. brainstorming — Activates when you describe an idea or openly state that you begin brainstorming sessions. The AI will refine your idea / concept through one-question-at-a-time dialogue, explore 2-3 alternative approaches, then present the design in chunks short enough to read. The resulting specification is then written to docs/specs/ and committed on the trunk branch (main/master). External review (Codex CLI when available, or a Claude subagent if not) and a user review-gate happen before moving on.

2. writing-plans — Activates with the approved spec. Breaks the work into bite-sized tasks (2-5 minutes each), each with exact file paths, complete code, and verification steps — clear enough for an enthusiastic junior engineer with poor taste, no judgement, and no project context to follow. The plan is saved to docs/plans/ and committed on trunk, next to the spec. External review by Codex (or a Claude subagent if Codex is not available) and user review-gate again.

3. Execution handoff — After the plan is approved, you pick one of three execution modes:

   • Subagent-driven (recommended) — a fresh subagent implements each task, with two-stage review (spec compliance, then code quality) running after each. All in this session.
   • Inline execution — all tasks executed in this session with checkpoints for human review.
   • Handover to a fresh thread — the agent prints a copy-paste prompt that lets a new session pick up the plan with a clean context window. Useful when brainstorming and planning have consumed a lot of context.