Superpipelines

Loop Engineering for AI coding agents, with real review boundaries.

Your AI reviewer cannot edit code. Structurally. And when a host cannot enforce that, Superpipelines tells you instead of pretending.

Superpipelines turns prompt-by-prompt AI coding into bounded engineering loops (spec, implement, verify, repair, resume, escalate) and runs the same pipeline scaffolds across Claude Code, OpenCode, Codex App/CLI, Cursor, Windsurf, and Cline.

Demo slot for launch: 90-second reviewer-denial clip plus same-pipeline cross-platform clip.

Why this exists

AI coding agents are starting to run loops. That is powerful, and dangerous.

A loop without a verifier is just autonomous guessing. A review loop without reviewer isolation is theater. A retry loop without a stop condition is a token bonfire.

Superpipelines gives AI coding loops engineering discipline:

• Write/review isolation: reviewers are constrained by host permissions where the platform supports it; Codex degrades honestly on unsandboxed hosts.
• One pipeline, many agents: scaffold once, run on Claude Code, OpenCode, Codex, and Tier 2 skill hosts.
• Crash-resumable execution: state is written locally throughout the run so interrupted work resumes from the last stable checkpoint.

How each loop-engineering ingredient maps to a Superpipelines feature: docs/LOOP-ENGINEERING.md. Want durable repo context before running pipelines? Pair with AIBoarding, the onboarding/context layer that keeps AGENTS.md alive.

Quick Start

Step 1: Install (universal, auto-detects your platform)

# POSIX (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/gustavo-meilus/superpipelines/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/gustavo-meilus/superpipelines/main/install.ps1 | iex

# Or via npm (any platform with Node ≥18)
npx -y superpipelines-install

Platform-specific install commands (generated from bin/install.js; run node scripts/generate-install-docs.js after changing the installer):

Tier 2 installs go through the third-party skills CLI (npx -y skills add …). If it fails or you prefer not to use it:

git clone https://github.com/gustavo-meilus/superpipelines

Then copy plugins/superpipelines/skills/ into the skills directory your tool documents (Cursor, Windsurf, and Cline each document their own skills location). The skills are plain SKILL.md folders per the Agent Skills open standard, with no build step.

Step 2: Create your first pipeline

/superpipelines:new-pipeline

Step 3: Run it

/superpipelines:run-pipeline

The system handles spec generation, agent coordination, state persistence, and crash recovery without requiring additional configuration.

Architecture

By operating with disallowedTools: Write, Edit, Bash, the reviewer agent cannot rationalize its way into modifying code. The only outputs it can produce are a passing verdict or an explicit failure that halts the pipeline. On platforms that support structural isolation (Claude Code, OpenCode, Codex), this constraint is enforced at the permission layer. On Cursor, Windsurf, and Cline (Tier 2), the same protocol runs as a convention, surfaced explicitly at run start and end so reviewers know reviews are advisory rather than structurally guaranteed.

Platform Tiers

Pipelines scaffolded on Tier 1 (Claude Code) or Tier 1d (Codex) run on Tier 2 platforms without modification: sk-platform-dispatch rewrites paths at read/write time.

Roadmap

Antigravity CLI 2.0 (Tier 1c) is supported on a best-effort basis: dispatch via Dynamic Subagents is implemented but not yet verified on a live host, and reviewer isolation there is convention-only until verification lands. Antigravity runs are always safe: the dispatcher falls back to the Tier 2 inline loop when the subagent primitive is absent, and every degradation is surfaced at run start and end.

Capabilities

Tasks decompose before execution into a precise specification and an itemized task list. This decomposition phase surfaces ambiguities and architectural gaps that would otherwise cause costly failures deep in the implementation cycle, especially when an agent encounters a constraint that never appeared in the initial intake. Pipeline creation opens with a brief-hardening interrogation, an adversarial crawl/grill/reconcile pass that confronts the stated intent against what the workspace and the host platform actually support, resolving contradictions before the architect commits them to a topology. Reviewer agents cannot modify the code they validate.

Isolation sits at the permission layer, not at the convention level. This distinction matters because a model under conventional role guidance can rationalize a targeted edit when the fix appears trivial, but a model under hard permission constraints cannot generate write operations at all. And most teams hit this failure mode only after a reviewer patches the audited file. Pipeline state persists to scope-aware temporary directories throughout execution, and a mid-session crash does not discard completed work because execution resumes automatically from the last stable checkpoint without triggering a full restart. Hard-coded iteration caps prevent runaway repair cycles. Human gates enforce additional stops at high-stakes transitions, requiring explicit approval before the pipeline advances to irreversible phases and blocking model rationalization from overriding defined stopping conditions.

Execution Workflow

Execution follows a nine-phase lifecycle, with mandatory validation between implementation and integration:

Execution Patterns

The framework selects the optimal pattern based on task complexity:

Slash Commands

Design Principles

Permission boundaries are enforced at the agent definition level, not by prompt instruction. The constraint preventing reviewers from modifying code sits in the tool allowlist (tools: + disallowedTools:), a schema a sufficiently confident model cannot talk itself around. Agents additionally declare a permissionMode; on Claude Code this is enforced for the per-pipeline agents materialized into your project, while for the plugin's own bundled agents Claude Code honors only the tool restrictions (a documented platform rule), so the tool allowlist is always the load-bearing barrier.

Pipeline state persists to a deterministic path at <scope-root>/superpipelines/temp/{P}/{runId}/pipeline-state.json. Resumption resets any in-progress phases to their initial state while preserving all completed work, which means a crashed session picks back up without re-running the intake or architecture phases that already passed validation. High-density reference documentation lives in companion *-references/ directories and loads on demand. This strategy prevents token-heavy reference payloads from bloating the active session window during phases that do not need deep technical detail. Practitioners commonly underestimate how quickly context saturation degrades output quality on long pipelines. Keeping reference data out of the primary context until it is needed is one of the highest-return optimizations available without modifying the underlying model configuration.

How It Compares

Superpowers and GSD are excellent frameworks. Both pioneered the discipline-first methodology this whole space runs on. Superpipelines differs on two specific, checkable axes:

If you want a methodology framework on Claude Code, both alternatives are great choices. If you need the reviewer structurally unable to edit the code it reviews, or the same pipeline running across hosts, that is what Superpipelines is for.

Repository Layout

superpipelines/
├── .claude-plugin/           # Claude Code manifest + marketplace data
├── .codex-plugin/            # Codex App/CLI manifest
├── .cursor-plugin/           # Cursor / Windsurf / Cline manifest
├── gemini-extension.json     # Antigravity CLI 2.0 extension manifest
├── agents/                   # Core agent definitions (zero-body; Lean Agent pattern)
├── skills/                   # Intelligence layer: skills hold the orchestration logic
│   ├── sk-platform-dispatch/ # Tier detection + DISPATCH contract + Tier 2 inline loop
│   ├── *-protocol/           # Per-agent protocol skills (companion to zero-body agents)
│   ├── *-references/         # Deep reference libraries (on-demand loading)
├── commands/                 # Slash command wrappers
├── hooks/                    # SessionStart hooks (per-platform variants)
├── bin/install.js            # Universal Node installer (7 platforms auto-detected)
├── install.sh / install.ps1  # POSIX + PowerShell installer wrappers
├── AGENTS.md                 # Universal context (any AGENTS.md-aware tool)
├── GEMINI.md                 # Antigravity session context (loaded by agy at start; roadmap tier)
├── CLAUDE.md                 # Claude Code project reference + invariants
│
│   ── Scope-local pipeline artifacts (generated at install / pipeline-create time) ──
│
├── .claude/                  # Claude Code scope root (Tier 1)
│   ├── agents/superpipelines/# Zero-body agent stubs per pipeline
│   ├── skills/superpipelines/# Entry skills + companion protocol skills
│   └── superpipelines/       # registry.json + pipelines/{P}/ (topology, SDD, launcher)
├── .opencode/                # OpenCode scope root (Tier 1b)
│   ├── agents/superpipelines/# Inline-body agents (≤150 lines)
│   ├── skills/superpipelines/# Entry skills
│   └── superpipelines/       # registry.json + pipelines/{P}/
├── .agents/antigravity/      # Antigravity CLI scope root (Tier 1c)
├── .codex/                   # Codex App/CLI scope root (Tier 1d)
│   └── agents/superpipelines/# TOML agent files
└── .superpipelines/          # Cursor / Windsurf / Cline scope root (Tier 2)
    └── skills/superpipelines/# Protocol skills only (no agent files on Tier 2)

Contributing

Contributions are managed via issues and PRs at gustavo-meilus/superpipelines.

License

MIT. See LICENSE.

Star History