What Are LoopX Presets and How to Use Them for Common Workflows?

LoopX presets are frozen configuration objects that bundle reusable "starter-pack" settings for frequent automation tasks, accessible via CLI commands like loopx preset list and loopx start-goal.

LoopX presets eliminate boilerplate setup by packaging proven engineering workflows into ready-to-run configurations. Each preset captures a specific operational pattern—such as daily repository triage or pull request monitoring—together with safety guardrails, capability requirements, and executable commands. This guide explains the preset data model in loopx/presets.py and demonstrates how to discover, inspect, and execute presets for your projects.

Understanding the LoopX Preset Data Model

A preset is defined by the BeginnerPreset dataclass in loopx/presets.py (source). This immutable structure contains eight key fields that determine how the preset behaves:

• preset_id – Unique identifier (e.g., daily-triage, pr-watch)
• title and summary – Human-readable purpose description
• tier – Either beginner_default (safe-by-default) or advanced_opt_in (requires explicit consent)
• maturity – Automation level label such as L1 report-only or L2 opt-in patch lane
• cadence – Recommended execution frequency
• default_mode – Initial runtime mode (report_only, dry_run_report_first, etc.)
• capability_path – Tuple of LoopX subsystem identifiers the preset will invoke
• safety_defaults – Read-only and human-review policies enforced by default

The concrete preset catalog lives in the immutable tuple BEGINNER_PRESETS (source).

Preset Tiers: Default vs. Advanced

LoopX separates presets into two safety categories to prevent accidental high-impact automation:

DEFAULT_PRESET_IDS – Safe-by-default presets suitable for new users. These enforce read-only policies and require explicit upgrades for any mutating operations.

ADVANCED_PRESET_IDS – Opt-in presets that target higher-risk automation lanes. These may interact with external systems, create patches, or modify repository state.

The CLI uses this separation when surfacing available presets. Running loopx preset list (source) respects your current tier settings and filters accordingly.

The Preset Packet: From Configuration to Execution

When you select a preset, LoopX constructs a preset packet—a JSON-compatible dictionary combining metadata with executable commands. The build_beginner_preset_packet() function (source) generates this packet with four built-in commands:

Command	Purpose
slash_start	Initiates the preset via slash command (/loopx …)
cli_start	Runs the goal directly from CLI (loopx start-goal …)
quota_guard	Validates quota availability (loopx quota should-run …)
heartbeat_prompt	Drives the LoopX engine with minimal overhead (loopx heartbeat-prompt …)

These commands are assembled in _preset_commands() (source) and embedded under the packet's commands key.

Safety Defaults in the Packet

The packet's top-level mutation_policy field reflects the preset's safety posture. As implemented in loopx/presets.py lines 92-95, beginner presets default to "read_only; renders commands only …"—ensuring no unintended mutations occur without explicit user escalation.

Discovering and Running Presets via CLI

LoopX exposes preset operations through the loopx preset command group, registered in loopx/help_surface.py.

List all available presets:

$ loopx preset list

Inspect a specific preset's full packet (JSON output):

$ loopx preset show daily-triage

Execute a preset directly:

$ loopx start-goal --guided --project . \
    --goal-text "Run Daily Triage L1 for this repository: inspect LoopX status, active todos, open gates, stale signals, and next actions; write a compact report and ask before code edits or external writes."

The --guided flag ensures human confirmation before any state-changing operations, respecting the preset's safety_defaults even when running in default_mode.

Programmatic Preset Access

For tooling integrations or documentation generation, import preset functions directly from loopx/presets.py:

from loopx.presets import build_beginner_preset_packet, render_beginner_preset_markdown

# Build a complete preset packet for the "pr-watch" preset

packet = build_beginner_preset_packet(
    preset_id="pr-watch",
    project=".",
    cli_bin="loopx"
)

# Access raw dictionary for programmatic use

print(packet["commands"]["cli_start"])

# Generate human-readable markdown documentation

print(render_beginner_preset_markdown(packet))

The render_beginner_preset_markdown() function (source) produces formatted documentation suitable for wikis, runbooks, or team onboarding materials.

How Presets Integrate with LoopX Architecture

Capability Path Routing

The capability_path field declares which LoopX subsystems a preset requires—such as status introspection, todo projection, CI/review monitoring, or dependency intake. This path drives the evidence and quota flows that determine whether a goal can proceed. The runtime uses capability requirements to validate environment readiness before execution.

Registry Isolation

According to the source architecture, presets operate independently of loopx/registry.py. The preset packet's mutation_policy explicitly prevents unintended registry mutations, ensuring that preset-driven workflows remain sandboxed unless explicitly escalated.

Common Preset Workflows

Based on the preset catalog structure, typical use cases include:

• Daily Triage (daily-triage) – L1 maturity, report-only inspection of repository health, active todos, and stale signals
• PR Watch (pr-watch) – Monitor open pull requests, CI status, and review gates
• Changelog Drafting – Automated changelog generation with human review gates
• Dependency Sweeping – Scan and report outdated dependencies without automatic updates
• CI Sweeping – Detect and report flaky or long-running CI jobs

Each workflow inherits the tier and maturity model, allowing teams to progressively adopt higher-automation presets as operational comfort increases.

Key Files in the Preset Ecosystem

File	Purpose
loopx/presets.py	Core preset definitions (BeginnerPreset, BEGINNER_PRESETS, packet builder, markdown renderer)
loopx/help_surface.py	CLI entry points for preset discovery and inspection
loopx/registry.py	Mutable registry that presets explicitly avoid touching
tests/test_skillbench_*.py	Verification suites ensuring preset workflows respect quota and safety policies

Summary

• LoopX presets are immutable BeginnerPreset objects defining reusable automation configurations with built-in safety controls
• Tier system separates beginner_default (safe-by-default) from advanced_opt_in (explicit consent required) presets
• Preset packets generated by build_beginner_preset_packet() bundle metadata with four executable CLI commands
• Safety defaults enforce read-only mutation_policy unless explicitly upgraded by the user
• Discovery and execution available via loopx preset list, loopx preset show, and loopx start-goal
• Programmatic access supported through imports from loopx/presets.py for tooling and documentation workflows

Frequently Asked Questions

How do I know if a preset is safe to run?

Check the tier and maturity fields in the preset packet. Presets with tier="beginner_default" and maturity="L1 report-only" enforce read-only policies by default. The mutation_policy field in the packet explicitly states whether the preset renders commands only or permits mutations. Run loopx preset show <id> to inspect these fields before execution.

Can I modify a preset's safety settings?

Presets are immutable configurations, but you can escalate permissions at runtime. The --guided flag with loopx start-goal enables step-by-step confirmation. For permanent changes, create a custom preset with your desired safety_defaults and add it to your local configuration—though this requires understanding the BeginnerPreset structure in loopx/presets.py.

What happens if my quota is insufficient for a preset?

The quota_guard command in every preset packet validates available quota before execution. If insufficient, it returns a structured error with guidance on quota acquisition. The LoopX engine uses this guard to prevent partial or failed workflow executions that could leave repositories in inconsistent states.

How do presets differ from custom LoopX goals?

Presets are pre-validated, community-tested configurations with fixed capability_path and safety guarantees. Custom goals accept arbitrary --goal-text and dynamically negotiate capabilities, offering flexibility at the cost of predictable behavior. Presets are recommended for team standardization; custom goals suit exploratory or one-off automation tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}