Mode System

Not every session needs the full pipeline. Modes filter which skills, gates, and auditors are active — so you get exactly the workflow you need.

Why Modes Exist

The full Propel pipeline has five gates, two questioner checkpoints, a dozen skills, and eight auditor agents. That is the right amount of structure when you are building a new paper-derived component from scratch. But it is far too much when you just need to launch a training run or track down a NaN.

Modes solve this by filtering the pipeline down to what the current task actually requires. A Researcher does not need implementation gates. A Trainer does not need design reviews. A Debugger needs investigation and diagnosis, but not the full design-implement-validate cycle. Each mode activates only the phases, gates, and skills that match the work.

How to Switch Modes

There are two ways to select a mode:

At Session Start: /intro

When you start a new session, the /intro command presents all four modes and asks you to choose. If no mode is selected and you just describe a task, Propel defaults to Engineer Mode (the full pipeline).

Anytime: /switch

Switch modes at any point during a session with the /switch command:

/switch researcher
/switch engineer
/switch debugger
/switch trainer

The switch takes effect immediately — no /clear needed. The using-propel skill reads the updated mode file and routes accordingly.

Mode State Persistence

The current mode is stored in .propel/mode.json:

{
  "mode": "engineer",
  "switched_at": "2026-03-28T14:30:00Z",
  "previous_mode": "researcher"
}

This file survives /clear. When the session-start hook fires (on every session start, resume, and compaction), it reads .propel/mode.json and injects the current mode into Claude's context. Your mode choice persists across context resets.

If .propel/mode.json does not exist, the hook sets "mode_selection_needed": true and Claude presents the mode selection prompt before anything else.

Mode Comparison

Pipeline Phase Activation

Each mode activates different phases of the Propel pipeline. The diagram below shows which phases are active (filled) and inactive (empty) in each mode:

                    Researcher    Engineer      Debugger      Trainer
                    ----------    --------      --------      -------
Gate 0  Intake      [========]    [========]    [========]
  Q0    Grounding   [========]    [========]
        Investigation[========]   [========]    [========]
Gate 1  Post-Invest.[========]    [========]    [========]
  Q1    Details                   [========]
        Design                    [========]
Gate 2  Post-Design               [========]
        Implementation            [========]
Gate 3  Mid-Impl.                 [========]     classify
        Validation                [========]     evidence
        Training                  [========]                  [========]
        Debugging                 [========]    [========]
Gate 4  Post-Debug                [========]    [========]    (runtime)
        Retrospective [========]  [========]    [========]    [========]

Out-of-Scope Handling

When a request does not match the current mode, Propel does not silently fail or attempt the work anyway. Instead, it names the mismatch and suggests the correct mode: