Skip to content

Core Concepts

Understanding SuperQode's core concepts is essential for effective quality engineering. This section explains the fundamental ideas that power SuperQode.

Quick Navigation

  • Three Execution Modes

    Learn about BYOK, ACP, and Local modes for connecting to AI models and agents.

    Explore modes

  • Ephemeral Workspace

    Understand how SuperQode isolates changes and protects your code during testing.

    Learn about workspaces

  • QE Roles

    Discover the different testing roles and how they work together.

    Explore roles

  • Quality Reports

    Learn about QRs - research-grade forensic reports with evidence and recommendations.

    Understand QRs

  • Allow Suggestions

    Understand the opt-in suggestion workflow where agents can demonstrate fixes.

    Learn about suggestions

  • What is SuperQE?

    Understand SuperQE (Agentic Quality Engineering) and how it relates to SuperQode.

    Learn about SuperQE

The SuperQode Philosophy

SuperQode is built on several key principles:

1. Sandbox-First

All testing happens in isolated ephemeral workspaces. Your production code is never modified without explicit consent.

┌─────────────────────────────────────────────────────────────┐
│                    SANDBOX GUARANTEE                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   Original Code        →        Snapshot Created            │
│         ↓                              ↓                     │
│   QE Sandbox           ←        Agents Test Freely          │
│         ↓                              ↓                     │
│   Session Ends         →        Changes Reverted            │
│         ↓                              ↓                     │
│   Original Restored    ←        Artifacts Preserved         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

2. Multi-Agent Validation

Multiple agents with different roles and models challenge each other, reducing blind spots:

  • Different models have different strengths and weaknesses
  • Cross-model validation increases finding confidence
  • Diverse perspectives catch more issues

3. Human-in-the-Loop

SuperQode suggests, never applies:

  • All findings require human review
  • Suggested fixes must be approved
  • Patches are preserved as artifacts
  • Final decisions remain with humans

4. Evidence-Based Reporting

QRs are research-grade forensic reports:

  • Every finding includes reproduction steps
  • Evidence is collected and documented
  • Root cause analysis is provided
  • Fix suggestions include verification results

How Concepts Connect

graph TB
    subgraph "Execution Layer"
        BYOK[BYOK Mode]
        ACP[ACP Mode]
        LOCAL[Local Mode]
    end

    subgraph "Workspace Layer"
        SNAPSHOT[Snapshot]
        SANDBOX[Sandbox Environment]
        REVERT[Revert Changes]
    end

    subgraph "Role Layer"
        EXEC[Execution Roles]
        DETECT[Detection Roles]
        HEUR[Heuristic Role]
    end

    subgraph "Output Layer"
        QR[Quality Report]
        PATCHES[Suggested Patches]
        TESTS[Generated Tests]
    end

    BYOK --> SANDBOX
    ACP --> SANDBOX
    LOCAL --> SANDBOX

    SNAPSHOT --> SANDBOX
    SANDBOX --> EXEC
    SANDBOX --> DETECT
    SANDBOX --> HEUR
    SANDBOX --> REVERT

    EXEC --> QR
    DETECT --> QR
    HEUR --> QR

    QR --> PATCHES
    QR --> TESTS

Key Terminology

Term Definition
BYOK Bring Your Own Key - Direct LLM API calls using your API keys
ACP Agent Client Protocol - Full coding agent integration
QE Quality Engineering - The process of ensuring software quality
QR Quality Report - Forensic quality report
Role A specialized testing persona (security_tester, api_tester, etc.)
Harness Validation system for patches and code changes
Sandbox Isolated environment for testing
Artifact Output from QE session (patches, tests, reports)

Concept Deep Dives

Execution Modes

SuperQode supports three ways to connect to AI:

Mode Description Best For
BYOK Direct API calls via LiteLLM Cloud providers (Anthropic, OpenAI)
ACP Full coding agent capabilities Advanced automation (OpenCode)
Local Self-hosted models Privacy, cost control

Learn more about modes

Ephemeral Workspace

The workspace system ensures safety:

  • Snapshot: Original state captured before testing
  • Isolation: Changes don't affect your repository
  • Revert: Automatic cleanup after testing
  • Artifacts: Patches and tests are preserved separately

Learn more about workspaces

QE Roles

Roles represent specialized testing personas:

  • Execution Roles: Run existing tests deterministically
  • Detection Roles: AI-powered issue discovery
  • Heuristic Role: Senior QE comprehensive review

Learn more about roles

Quality Reports

QRs transform QA outputs from tickets to decisions:

  • Investigation summary with methodology
  • Findings with evidence and reproduction steps
  • Root cause analysis
  • Verified fix suggestions

Learn more about QRs

Allow Suggestions

The opt-in workflow for demonstrating fixes:

  1. Agent detects issue
  2. Agent fixes in sandbox
  3. Fix is verified with tests
  4. Evidence is collected
  5. Changes are reverted
  6. Patches are preserved for review

Learn more about suggestions

Next Steps