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

> Discover LoopX presets, reusable configuration objects for common automation tasks. Learn how to use these starter packs via CLI commands to streamline your workflows.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py) ([source](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py#L11-L24)). 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](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py#L26-L96)).

## 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](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py#L199-L205)) 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](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py#L72-L81)) 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](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py#L12-L22)) 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/help_surface.py).

List all available presets:

```bash
$ loopx preset list

```

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

```bash
$ loopx preset show daily-triage

```

Execute a preset directly:

```bash
$ 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`](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py):

```python
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](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py#L22-L33)) 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/presets.py) | Core preset definitions (`BeginnerPreset`, `BEGINNER_PRESETS`, packet builder, markdown renderer) |
| [`loopx/help_surface.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/help_surface.py) | CLI entry points for preset discovery and inspection |
| [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.