Maintainer memo: Superpowers + roborev interoperability

roborev-superpowers-maintainer-memo.md

Maintainer Memo: Superpowers + roborev Interoperability

Audience

Maintainers of Superpowers and roborev evaluating whether, and how, to support a shared workflow.

Purpose

Propose a practical interoperability model that preserves each project's core philosophy:

• Superpowers remains a workflow discipline layer.
• roborev remains the durable review accountability layer.

Problem Statement

Users perceive overlap because both systems include review loops. The tension is mostly about state semantics:

• Superpowers review checkpoints are process-level and session-local.
• roborev review checkpoints are persisted and explicitly tracked as addressed/unaddressed.

This creates uncertainty around which system is authoritative for "is this work actually review-closed?"

Current-State Comparison

Dimension	Superpowers	roborev
Primary goal	Execution quality and workflow discipline	Durable review governance
Review timing	During task execution (spec + quality loops)	Per commit/branch, background or explicit
State model	Session/task progression	Persistent job records in DB
Closure semantics	"review passed, proceed"	explicit address / respond lifecycle
Auditability	Mostly transcript/git based	first-class queryable history
Merge gating	Skill/process conventions	enforceable via unaddressed findings policy

Interoperability Principles

1. Preserve separation of concerns.
2. Make integration optional, not mandatory.
3. Keep agent/runtime neutrality (Codex, Claude Code, etc.).
4. Prefer small glue points over deep coupling.
5. Define one authoritative source for durable closure state.

Proposed Contract

Use a two-loop contract:

1. Inner loop (Superpowers): implement task, run local/spec/quality checks, commit.
2. Outer loop (roborev): review commit, persist findings, require explicit closure.

Task completion policy when interoperability is enabled:

1. Task commit exists.
2. roborev checkpoint has completed.
3. Any blocking findings are fixed and explicitly addressed (or responded with rationale).
4. Then and only then, mark task complete.

Integration Options

Option A: Documentation-only alignment (lowest coupling)

What:

• Publish recommended dual-system workflow in both projects.
• No code changes in either system.

Pros:

• Immediate, zero technical risk.
• Preserves independent release cycles.

Cons:

• Compliance depends on user discipline.
• No automation of checkpoint enforcement.

Option B: Optional checkpoint skill (recommended near-term)

What:

• Add an optional Superpowers-compatible skill (distributed by roborev or as a companion package) that runs a roborev checkpoint and blocks on unresolved findings.
• Invoked after task commits or at configured batch boundaries.

Pros:

• Clear, automated contract with minimal integration surface.
• Keeps core Superpowers workflow unchanged for non-roborev users.

Cons:

• Adds one more skill/config dimension.
• Requires clear failure/timeout UX.

Option C: Strong branch-finalization gate

What:

• Extend branch-finalization flow to require clean roborev state before merge options are offered.

Pros:

• High confidence before integration.
• Natural place for policy enforcement.

Cons:

• Catches issues late if not paired with per-task checkpoints.
• Can feel heavyweight for small repos.

Recommendation

Adopt Option B first, with Option C as optional follow-up.

Rationale:

• Option A alone is too weak for teams seeking accountability.
• Option C alone is too late in the cycle.
• Option B provides incremental enforcement without invasive changes.

Proposed MVP Scope

MVP behavior:

1. Trigger point: after each task commit (or batch boundary in executing-plans mode).
2. Action: run roborev review checkpoint and wait for result.
3. Policy:
   • blocking findings: stop progression until explicitly resolved.
   • non-blocking findings: proceed with note.
4. Resolution paths:
   • fix + address
   • explicit respond with rationale
5. Resume rule: continue only when no blocking unaddressed findings remain for checkpoint scope.

MVP non-goals:

• Shared database between projects.
• Hard dependency of Superpowers on roborev.
• Replacing Superpowers internal review stages.

Suggested Configuration Surface

Keep config explicit and minimal:

# Example conceptual config, format can vary by host tool
[interop.roborev]
enabled = true
mode = "task"          # task | batch | branch
blocking = ["critical", "important"]
require_explicit_response_for_waive = true
timeout_seconds = 600

Failure Handling Rules

1. If roborev is unavailable, fail fast with actionable guidance.
2. If review job errors, do not auto-advance task state.
3. If finding appears false positive, require explicit recorded response.
4. If user opts out for session, require explicit opt-out acknowledgement.

Data Linking (Optional but Valuable)

To improve traceability without deep integration:

1. Include roborev job IDs in task completion summaries.
2. Include task ID/context in roborev comment text.
3. Optionally include commit SHA + task ID in both directions.

This creates lightweight provenance with no shared schema.

Rollout Plan

Phase 1: Alignment docs

Deliverables:

• Shared workflow doc in both repos.
• Terminology alignment ("checkpoint", "addressed", "blocking").

Phase 2: Optional checkpoint skill

Deliverables:

• Interop skill package.
• Reference config and examples.
• Basic smoke tests in both environments.

Phase 3: Finalization gate (optional)

Deliverables:

• Branch completion policy check.
• Clear override path with explicit acknowledgement.

Success Metrics

1. Reduction in merges with unaddressed blocking findings.
2. Lower mean time from finding creation to explicit closure.
3. Decrease in repeated findings across adjacent commits.
4. User-reported clarity on "what remains unresolved."

Risks and Mitigations

Risk: Duplicate review burden feels heavy.

Mitigation: position Superpowers review as design/spec/quality loop, roborev as durable closure gate; tune checkpoint cadence.

Risk: False positives stall execution.

Mitigation: codify respond path with explicit rationale.

Risk: Tooling complexity discourages adoption.

Mitigation: ship with opt-in defaults, short setup, and preset policy profiles.

Open Questions for Maintainer Discussion

1. Should the checkpoint default be per-task or per-batch?
2. What severity threshold should block progression by default?
3. Should unresolved findings block only merge, or also next task?
4. Where should interop live: Superpowers companion skill vs roborev-managed skill?
5. What is the minimum UX needed to make false-positive handling low-friction?

Proposed Decision

Approve an opt-in interoperability path (Option B) that treats roborev as the durable closure authority while preserving Superpowers as the execution workflow authority.

This resolves user confusion without forcing philosophical convergence or architectural coupling.