Skip to content

Stateless Agent Pattern

Advanced workflow design

This page is for readers who want to understand how resumable interview workflows are built. Most users only need to know that interrupted guided workflows can resume from saved progress.

The Stateless Agent pattern enables resumable interview workflows in rp1. When you're interrupted during a guided interview (like charter creation), you can pick up exactly where you left off. The agent reads its state from a visible "scratch pad" section rather than relying on conversation memory.

How It Works

In the standard command-agent pattern, agents execute autonomously and maintain state in conversation context. This works well for single-pass workflows but breaks down when:

  • The session is interrupted (timeout, crash, user pause)
  • The workflow spans multiple invocations
  • Users need visibility into accumulated state

The Stateless Agent pattern solves this by separating orchestration (the caller) from analysis (the agent):

flowchart TB
    subgraph "Caller (Orchestrator)"
        CMD["/blueprint command"]
        STATE["State Management<br/>(scratch pad in file)"]
        ASK["User Interaction<br/>(AskUserQuestion)"]
    end

    subgraph "Stateless Agent"
        AGENT["charter-interviewer<br/>(returns JSON)"]
    end

    CMD -->|"1. Invoke"| AGENT
    AGENT -->|"2. Read state"| STATE
    AGENT -->|"3. Return JSON response"| CMD
    CMD -->|"4. Ask question"| ASK
    ASK -->|"5. User answers"| CMD
    CMD -->|"6. Write to scratch pad"| STATE
    CMD -->|"7. Loop until done"| AGENT

    style CMD fill:#1565c0,color:#fff
    style AGENT fill:#e65100,color:#fff
    style STATE fill:#c2185b,color:#fff

User-Visible Behavior

When you run a command that uses the Stateless Agent pattern (like /blueprint), you'll notice a Scratch Pad section at the bottom of the document being created:

## Scratch Pad

<!-- Interview state - will be removed upon completion -->
<!-- Mode: CREATE -->
<!-- Started: 2025-12-27T10:30:00Z -->

### Q1: Brain Dump
**Asked**: Tell me everything about this project...
**Answer**: We're building a task management app for remote teams...

### Q2: Target Users
**Asked**: Who are the primary users?
**Answer**: Product managers and team leads in companies with 10-50 employees.

This scratch pad:

  • Shows your progress: See all questions asked and answers given
  • Persists to disk: Survives crashes, timeouts, and session interruptions
  • Enables resume: Re-running the command continues where you left off
  • Gets cleaned up: Removed automatically when the interview completes successfully

Resume Capability

If your session is interrupted, simply re-run the same command:

# Session 1: Start blueprint, interrupted after Q2
/rp1-dev:blueprint

# Session 2: Resume from where you left off
/rp1-dev:blueprint

When you resume:

  1. The command detects the existing scratch pad
  2. The agent reads prior Q&A history
  3. Interview continues from the next question
  4. Previously answered questions are not re-asked
flowchart LR
    START[Run command] --> CHECK{Scratch pad<br/>exists?}
    CHECK -->|No| CREATE[Start fresh interview]
    CHECK -->|Yes| RESUME[Resume from last Q&A]
    CREATE --> LOOP[Interview loop]
    RESUME --> LOOP
    LOOP --> DONE[Complete & clean up]

    style RESUME fill:#e65100,color:#fff

Comparison with Standard Agents

Aspect Standard Agent Stateless Agent
State storage Conversation context File-based scratch pad
Resumability No Yes
User visibility Hidden Visible scratch pad
Session dependency Tied to session Session-independent
Complexity Lower Higher (orchestration loop)

Example: Charter Interview

The /blueprint command uses the Stateless Agent pattern for charter creation:

  1. Mode Detection: Command checks if charter.md exists, has scratch pad
  2. Initialize: Creates charter with scratch pad section
  3. Interview Loop: Repeatedly invokes charter-interviewer agent
  4. Response Handling: Agent returns JSON with next question or completion
  5. User Interaction: Command asks user, writes answer to scratch pad
  6. Completion: Scratch pad removed, charter finalized

The charter-interviewer agent is stateless—it reads the scratch pad, analyzes gaps, and returns a JSON response. It never asks questions directly.

Key Benefits

  • Resumability

    Interrupted sessions can continue from where they left off.

  • Transparency

    Users see accumulated state in the scratch pad during interviews.

  • Robustness

    State persists even if the AI session crashes.

  • Testability

    Agents are pure functions: input state, output JSON response.

Learn More