Pairing Mode: Human-Supervised AI Coding Sessions

One AI agent under Liza’s behavioral contract: approval gates, seven collaboration modes, magic phrase interrupts, and Tier 0 rules that are never waived.

Pairing mode pairs you directly with one AI agent in an interactive terminal session. The agent operates under Liza’s behavioral contract — a strict state machine with approval gates, hard stops, and tiered rules — so you can collaborate with it as a disciplined engineering peer rather than a probabilistic autocomplete tool. It’s the right mode for exploratory work, incremental feature development, complex debugging, and any situation where you want full visibility and control over every change that lands in your codebase.

​

Starting a Pairing Session

1. Install Liza and run global setup

   Install the Liza binary and run one-time global setup to write contracts and skills to ~/.liza/:

   curl -fsSL https://raw.githubusercontent.com/liza-mas/liza/main/install.sh | bash
   liza setup --claude --codex
   
2. Initialize your project

   In your repository, run liza init to create contract discovery files and project-local settings:

   cd my-project
   liza init --claude
   

   This writes .claude/settings.json, creates CLAUDE.md (a symlink to ~/.liza/CORE.md), and adds GUARDRAILS.md if the file doesn’t already exist.

3. Start your agent and say hello

   Launch your coding agent CLI from the project directory:

   claude          # or: codex
   

   Greet the agent. This triggers the Hello Protocol: the agent reads your project, builds mental models of what “ready” and “done” mean for this codebase, and responds with:

   • The project purpose as it understands it
   • Project-specific stop conditions and red flags
   • A 5-bullet assessment of the behavioral contract — including genuine points of friction

   The assessment matters: an agent that finds “nothing to criticize” hasn’t truly engaged with the contract. Real friction points in the assessment signal that the contract is active.

​

The Task Cycle

Every task you give the agent flows through a fixed state machine. The agent cannot skip or reorder steps.

You: "Add retry logic to the API client"
                │
                ▼
        ┌──────────────┐
        │   ANALYSIS   │  Agent reads code, builds understanding,
        │              │  asks clarifying questions if anything
        │              │  is ambiguous. All assumptions are tagged.
        └──────┬───────┘
               │
               ▼
     ┌─────────────────┐
     │ APPROVAL_PENDING │  Agent presents a structured proposal:
     │                 │  intent, scope, risks, validation plan.
     └────────┬────────┘
              │
    You review and approve (or redirect)
              │
              ▼
       ┌────────────┐
       │  EXECUTION  │  Agent implements exactly what was approved.
       │             │  Discovers a problem mid-flight? It stops
       └──────┬──────┘  and re-proposes — no silent pivots.
              │
              ▼
      ┌─────────────┐
      │  VALIDATION  │  Agent runs tests, pre-commit, captures
      │              │  output — proves the change works.
      └──────┬───────┘
             │
             ▼
          ┌──────┐
          │ DONE │  Evidence required. Claims without proof
          └──────┘  are not accepted.

​

Approval Request Formats

The agent scales its proposal format to match the complexity and risk of the change:

Fast Path

Trivial, zero-risk changes. One-line intent plus a “Proceed?” prompt. No ceremony beyond confirmation.

Compact

Single-file changes with high confidence. Covers intent, scope, doc/test impact, validation plan, and risk level.

Full

Complex or multi-file changes. Adds understanding summary, success criteria, tagged assumptions, diff preview, failure modes, rollback path, and alternatives considered.

When you approve with a condition — "P, but also handle the empty-input edge case" — the agent classifies the addition as either a clarification within scope (it proceeds) or a scope expansion (it re-proposes with an updated plan). You always know which.

​

Collaboration Modes

The default mode is Autonomous. You can switch modes at any time without justification. The agent announces each switch: "Switching to [Mode] — [reason]".

Autonomous

The agent proposes, you approve, the agent executes. Every state change goes through a gate — not as a rubber stamp, but as a collaboration opportunity. You can redirect, challenge, or take over at any gate.

Best for: Clear requirements, low-risk changes, steady-state development.

Coach

The agent asks Socratic questions about purpose, not implementation. Why are you doing this? What problem does this solve? What would success look like? The agent does not propose solutions in this mode — it asks questions until your intent is precise.

Best for: When the what is clear but the why isn’t; early-stage thinking; weak or missing rationale.

Challenger

The agent stress-tests a finalized plan before execution. “What’s the strongest argument against this? What evidence would change your mind? What failure mode hasn’t been discussed?” This is adversarial review, not brainstorming.

Best for: Pre-execution gate for significant changes; when you want your plan attacked before it hits the codebase.

User Duck

The agent thinks aloud, surfacing hypotheses step-by-step as it forms them. You listen and redirect when it’s off track.

“Looking at the error… it fails at line 47 when score is None. The upstream caller is filter_jobs.py:82. I think the issue is…”

“Wait — check if the input validates that field.”

“Good catch. Let me look at the schema validation…”

Best for: Complex debugging; unfamiliar code; when the agent needs to work through a problem methodically.

Agent Duck

You explain what you’re trying to achieve. The agent asks probing questions and listens. It’s a smart rubber duck — its goal is to help you verbalize your intent clearly.

“I want to improve the scoring somehow.”

“What’s not working? False positives or false negatives?”

“Too many low-quality jobs scoring 6+.”

“Which criteria are they passing that they shouldn’t?”

Best for: Fuzzy requirements; design exploration; when you need to externalize your thinking.

True Pairing

Neither of you drives exclusively. Rapid back-and-forth hypothesis building. Incomplete thoughts are welcome — you might propose half an idea and the agent completes it, or vice versa.

Best for: High uncertainty; open exploration; when neither party has the full picture.

Spike

The deliverable is a specification, not production code. Code is scaffolding — written to test ideas and validate understanding. Quality gates on code are relaxed; spec completeness is required. The agent proposes spec updates as understanding crystallizes. Exit Spike mode and switch to Autonomous or True Pairing when the spec is solid.

Best for: Exploring new features; validating requirements through code simulation; spec-first development.

​

Magic Phrases

Magic phrases are interrupt signals. When you invoke one, the agent stops current work, executes the specified behavior, and waits for your confirmation before resuming. You never need to justify invoking a magic phrase — the phrase itself is sufficient authority.

Phrase	Effect
"Fresh eyes"	Discards current reasoning, re-reads sources, restarts from evidence
"Scope check"	Re-examines boundaries: what’s in scope, out of scope, and creeping
"5 Whys"	Runs a root-cause chain before any fix is proposed
"Show your assumptions"	Surfaces all tagged assumptions before proceeding
"Challenge the direction"	Questions the goal itself, not just the implementation
"Prepare to discuss"	Steps back from code for strategic thinking
"Recall your models"	Agent retrieves its mental models privately for recalibration
"State your models"	Agent surfaces its mental models for shared alignment
"Drift check"	Verifies shared understanding hasn’t drifted over a long session

Use "Drift check" proactively during long sessions. If the agent’s response reveals misalignment, use "Fresh eyes" to reset its reasoning before continuing.

​

Tier 0: The Safety Net

Five invariants are built into the contract and are never violated — not under context pressure, not in degraded mode, not for any reason. These are the behaviors the agent structurally cannot perform:

1. No unapproved state change

Every mutation to your codebase, filesystem, or environment requires your prior approval. The agent cannot act first and report later.

2. No fabrication

Every claim the agent makes must be verified against actual evidence — code it has read, tests it has run, output it has captured. The agent does not invent answers.

3. No test corruption

Tests are never modified to accept buggy behavior. When code is unknown and tests are red, the agent stops and investigates — it does not “fix” the test.

4. No unvalidated success

“Done” requires validation evidence. The agent runs tests, captures output, and verifies the changed behavior specifically — not just unrelated green tests.

5. No secrets exposure

API keys, tokens, and passwords are never logged, displayed, committed, or included in diffs under any circumstances.

If the agent violates any rule, it immediately announces "GUIDELINE VIOLATION: [Rule — description]", enters RESET state, and proposes options: Resume, Undo, or Abandon. A second violation of the same rule triggers a mandatory halt.

​

Grace Under Pressure

During long sessions or complex tasks, lower-priority rules are explicitly suspended rather than silently violated. When this happens the agent announces it:

"DEGRADED MODE — Enforcing Tier 0-1 only. Tier 2-3 suspended until context restored."

Tier	Category	Under Pressure
Tier 0	Hard invariants (no fabrication, no test corruption, no unapproved changes)	Never violated
Tier 1	Epistemic integrity (assumption tracking, source declarations)	Suspended only with explicit waiver
Tier 2	Process quality (complete checklists, retrospectives)	Best-effort
Tier 3	Collaboration quality (contrarian stance, mode discipline)	Degraded gracefully

When you see DEGRADED MODE, finish the current task cleanly and start a new session to restore full contract enforcement.

​

Compatible Agents

Liza’s behavioral contract is a capability test — it requires the agent to parse instructions as executable specifications, observe state, and pause at gates.

Provider	Model	Compatibility	Notes
Anthropic	Claude (Opus 4.5+)	✅ Fully compatible	Reference provider
OpenAI	Codex (GPT-5+)	✅ Fully compatible	Equally capable
Mistral	Devstral-2	🔶 Partial	Requires explicit activation and supervision
Google	Gemini	❌ Incompatible	Architectural limitation — no prompt-level fix

Gemini’s incompatibility is architectural, not a configuration issue. No amount of prompt tuning makes it a reliable Liza agent. Use Claude or Codex for pairing sessions where contract enforcement matters.