> ## Documentation Index > Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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/`: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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. ```text theme={null} 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: > [card] Fast Path > > Trivial, zero-risk changes. One-line intent plus a "Proceed?" prompt. No ceremony beyond confirmation. > [card] Compact > > Single-file changes with high confidence. Covers intent, scope, doc/test impact, validation plan, and risk level. > [card] 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]"`. > [tab] 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. > [tab] 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. > [tab] 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. > [tab] 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. > [tab] 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. > [tab] 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. > [tab] 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 | > [!TIP] > > 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: > [card] 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. > [card] 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. > [card] 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. > [card] 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. > [card] 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 | > [!WARNING] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.