Commit 6e9b20b8611f

@@ -0,0 +1,73 @@
+# Pi Model Modes Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace Pi's mixed model presets with a consistent fast/code/heavy matrix using Gemini for work, Claude for OSS, and explicit alternative families.
+
+**Architecture:** Keep the existing data-driven mode extension unchanged. Update only its `modes.json` configuration and accompanying design documentation; existing `PI_START_MODE` values remain valid.
+
+**Tech Stack:** JSON, Pi model registry, Git
+
+## Global Constraints
+
+- Each mode resolves to one explicit provider, model, and thinking level.
+- `work` defaults to Gemini through Google Vertex AI.
+- `oss` defaults to Claude through GitHub Copilot.
+- Thinking levels are `off` for fast, `low` for code, and `medium` for heavy.
+- Do not add Gemini-through-Copilot curated modes.
+- Keep `free-code` unchanged.
+
+---
+
+### Task 1: Update the curated model matrix
+
+**Files:**
+- Modify: `dots/pi/agent/modes.json`
+- Test: configuration validation commands
+
+**Interfaces:**
+- Consumes: the existing `ModesFile` schema in `dots/pi/agent/extensions/prompt-editor.ts`
+- Produces: named presets consumed by `/mode` and `PI_START_MODE`
+
+- [ ] **Step 1: Capture a failing matrix assertion**
+
+Run a Python assertion against the approved matrix before editing. It must fail because `code-work` currently selects Claude Opus instead of Gemini Flash.
+
+- [ ] **Step 2: Replace the mode definitions**
+
+Set `default` equal to `code-work`; add the approved Gemini/Claude/GPT fast, code, and heavy presets; retain `free-code`; remove `wide`, `flash`, previous, and super-fast presets.
+
+- [ ] **Step 3: Validate the matrix**
+
+Run a Python script that parses the JSON, compares every expected mode exactly, confirms the removed modes are absent, and confirms no unexpected modes exist.
+
+- [ ] **Step 4: Validate model availability**
+
+Compare every new or changed provider/model tuple with `pi --list-models` and fail if any tuple is unavailable. Preserve the unchanged `free-code` tuple even if it is absent from the current catalog.
+
+### Task 2: Verify, commit, and push
+
+**Files:**
+- Include: `dots/pi/agent/modes.json`
+- Include: `docs/superpowers/specs/2026-08-27-pi-model-modes-design.md`
+- Include: `docs/superpowers/plans/2026-08-27-pi-model-modes.md`
+
+**Interfaces:**
+- Consumes: validated configuration and documentation
+- Produces: one Conventional Commit on the current branch and an explicit push refspec
+
+- [ ] **Step 1: Review the complete diff and repository status**
+
+Confirm only the three intended files are part of this change and inspect the complete diff.
+
+- [ ] **Step 2: Run final verification**
+
+Repeat JSON matrix validation and provider/model availability checks from a clean command invocation.
+
+- [ ] **Step 3: Commit**
+
+Create one signed-off Conventional Commit describing why the modes were aligned with workload tiers and access paths.
+
+- [ ] **Step 4: Verify tracking and push explicitly**
+
+Run `git status`, identify the current branch, then push with `git push origin <branch>:<branch>`.

@@ -0,0 +1,112 @@
+# Pi model modes design
+
+## Goal
+
+Make Pi's curated modes simple and predictable. Each mode is an explicit provider, model, and thinking-level preset. Mode names communicate the workload tier and access path without runtime model resolution or fallback logic.
+
+## Naming
+
+Modes use:
+
+```text
+<tier>-<access>[-<family>]
+```
+
+Tiers:
+
+- `fast`: inexpensive, low-latency work
+- `code`: normal implementation and debugging
+- `heavy`: architecture, difficult debugging, and broad refactors
+
+Access paths:
+
+- `work`: Vertex AI
+- `oss`: GitHub Copilot
+
+The family suffix is omitted for the preferred family on each access path:
+
+- `work` defaults to Gemini through Google Vertex AI
+- `oss` defaults to Claude through GitHub Copilot
+
+Alternative families are explicit, such as `code-work-claude` and `code-oss-gpt`.
+
+## Thinking levels
+
+Thinking effort follows the workload tier consistently:
+
+| Tier | Thinking level |
+| --- | --- |
+| `fast` | `off` |
+| `code` | `low` |
+| `heavy` | `medium` |
+
+`high` and higher levels remain available as manual overrides but are not mode defaults, limiting unnecessary token usage and latency.
+
+## Mode matrix
+
+### Work defaults: Gemini through Vertex AI
+
+| Mode | Provider | Model | Thinking |
+| --- | --- | --- | --- |
+| `fast-work` | `google-vertex` | `gemini-3.1-flash-lite` | `off` |
+| `code-work` | `google-vertex` | `gemini-3.7-flash` | `low` |
+| `heavy-work` | `google-vertex` | `gemini-3.1-pro-preview` | `medium` |
+
+### OSS defaults: Claude through GitHub Copilot
+
+| Mode | Provider | Model | Thinking |
+| --- | --- | --- | --- |
+| `fast-oss` | `github-copilot` | `claude-haiku-4.5` | `off` |
+| `code-oss` | `github-copilot` | `claude-sonnet-5` | `low` |
+| `heavy-oss` | `github-copilot` | `claude-opus-5` | `medium` |
+
+### GPT alternatives through GitHub Copilot
+
+| Mode | Provider | Model | Thinking |
+| --- | --- | --- | --- |
+| `fast-oss-gpt` | `github-copilot` | `gpt-5.6-luna` | `off` |
+| `code-oss-gpt` | `github-copilot` | `gpt-5.6-terra` | `low` |
+| `heavy-oss-gpt` | `github-copilot` | `gpt-5.6-sol` | `medium` |
+
+### Claude alternatives through Vertex AI
+
+| Mode | Provider | Model | Thinking |
+| --- | --- | --- | --- |
+| `fast-work-claude` | `anthropic-vertex` | `claude-haiku-4-5` | `off` |
+| `code-work-claude` | `anthropic-vertex` | `claude-sonnet-5` | `low` |
+| `heavy-work-claude` | `anthropic-vertex` | `claude-opus-5` | `medium` |
+
+### Other modes
+
+- `default` points to the same provider, model, and thinking level as `code-work`.
+- `free-code` remains unchanged.
+
+Gemini models exposed through GitHub Copilot remain selectable with Pi's model selector but do not receive curated modes. Vertex AI is the preferred Gemini access path.
+
+## Removed modes
+
+Remove modes whose semantics are superseded or unclear:
+
+- `wide`
+- `flash`
+- `fast-oss-previous`
+- `code-oss-previous`
+- `super-fast-oss`
+- `super-fast-oss-gpt`
+
+## Configuration impact
+
+Update project `.envrc` generation so existing access-path defaults continue to use:
+
+- work repositories: `PI_START_MODE=code-work`
+- OSS repositories: `PI_START_MODE=code-oss` or `PI_START_MODE=code-oss-gpt`, according to the existing project policy
+
+No extension logic changes are required unless tests or documentation encode the old mode names. The primary implementation is a surgical update to `dots/pi/agent/modes.json` plus affected tests and documentation.
+
+## Validation
+
+1. Parse `modes.json` as valid JSON.
+2. Confirm every new or changed provider/model tuple appears in `pi --list-models`; preserve the unchanged `free-code` preset independently of current catalog availability.
+3. Verify removed modes no longer appear in the mode selector.
+4. Verify each new mode changes the provider, model, and thinking level as specified.
+5. Verify `PI_START_MODE=code-work` and `PI_START_MODE=code-oss` select the intended defaults without persisting them globally.

@@ -3,81 +3,81 @@
   "currentMode": "code-work",
   "modes": {
     "default": {
-      "provider": "anthropic-vertex",
-      "modelId": "claude-sonnet-4-6",
-      "thinkingLevel": "minimal"
+      "provider": "google-vertex",
+      "modelId": "gemini-3.7-flash",
+      "thinkingLevel": "low"
     },
     "fast-work": {
-      "provider": "anthropic-vertex",
-      "modelId": "claude-sonnet-4-6",
+      "provider": "google-vertex",
+      "modelId": "gemini-3.1-flash-lite",
       "thinkingLevel": "off",
-      "color": "#2e8b57"
+      "color": "#34a853"
     },
     "code-work": {
-      "provider": "anthropic-vertex",
-      "modelId": "claude-opus-4-6",
-      "thinkingLevel": "low",
-      "color": "#b45309"
-    },
-    "wide": {
-      "provider": "google",
-      "modelId": "gemini-3.1-pro-preview",
+      "provider": "google-vertex",
+      "modelId": "gemini-3.7-flash",
       "thinkingLevel": "low",
       "color": "#4285f4"
     },
-    "flash": {
-      "provider": "google",
-      "modelId": "gemini-3.6-flash",
-      "thinkingLevel": "minimal",
-      "color": "#34a853"
+    "heavy-work": {
+      "provider": "google-vertex",
+      "modelId": "gemini-3.1-pro-preview",
+      "thinkingLevel": "medium",
+      "color": "#1a73e8"
+    },
+    "fast-work-claude": {
+      "provider": "anthropic-vertex",
+      "modelId": "claude-haiku-4-5",
+      "thinkingLevel": "off",
+      "color": "#2e8b57"
+    },
+    "code-work-claude": {
+      "provider": "anthropic-vertex",
+      "modelId": "claude-sonnet-5",
+      "thinkingLevel": "low",
+      "color": "#b45309"
+    },
+    "heavy-work-claude": {
+      "provider": "anthropic-vertex",
+      "modelId": "claude-opus-5",
+      "thinkingLevel": "medium",
+      "color": "#c2410c"
     },
     "fast-oss": {
-      "provider": "github-copilot",
-      "modelId": "claude-sonnet-5",
-      "thinkingLevel": "off",
-      "color": "#22d3ee"
-    },
-    "fast-oss-previous": {
-      "provider": "github-copilot",
-      "modelId": "claude-sonnet-4.6",
-      "thinkingLevel": "off",
-      "color": "#22d3ee"
-    },
-    "code-oss": {
-      "provider": "github-copilot",
-      "modelId": "claude-opus-5",
-      "thinkingLevel": "low",
-      "color": "#f97316"
-    },
-    "code-oss-previous": {
-      "provider": "github-copilot",
-      "modelId": "claude-opus-4.8",
-      "thinkingLevel": "low",
-      "color": "#f97316"
-    },
-    "super-fast-oss": {
       "provider": "github-copilot",
       "modelId": "claude-haiku-4.5",
       "thinkingLevel": "off",
       "color": "#67e8f9"
     },
-    "code-oss-gpt": {
+    "code-oss": {
       "provider": "github-copilot",
-      "modelId": "gpt-5.6-sol",
+      "modelId": "claude-sonnet-5",
       "thinkingLevel": "low",
-      "color": "#fbbf24"
+      "color": "#22d3ee"
+    },
+    "heavy-oss": {
+      "provider": "github-copilot",
+      "modelId": "claude-opus-5",
+      "thinkingLevel": "medium",
+      "color": "#f97316"
     },
     "fast-oss-gpt": {
+      "provider": "github-copilot",
+      "modelId": "gpt-5.6-luna",
+      "thinkingLevel": "off",
+      "color": "#bef264"
+    },
+    "code-oss-gpt": {
       "provider": "github-copilot",
       "modelId": "gpt-5.6-terra",
       "thinkingLevel": "low",
       "color": "#a3e635"
     },
-    "super-fast-oss-gpt": {
+    "heavy-oss-gpt": {
       "provider": "github-copilot",
-      "modelId": "gpt-5.6-luna",
-      "thinkingLevel": "off",
-      "color": "#a3e635"
+      "modelId": "gpt-5.6-sol",
+      "thinkingLevel": "medium",
+      "color": "#fbbf24"
     },
     "free-code": {
       "provider": "openrouter",