feat: economy mode for cost-conscious model selection (#500)

.squad/agents/eecom/history.md

@@ -103,3 +103,22 @@ CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli
 Implemented Flight's privacy-first adoption monitoring strategy on PR #326 branch. Moved `.squad/adoption/` → `.github/adoption/` for better GitHub integration. Stripped tracking.md to aggregate-only metrics (removed all individual repo names/URLs). Updated GitHub Action workflow (adoption-report.yml) and monitoring script (scripts/adoption-monitor.mjs) to write reports to `.github/adoption/reports/`. Removed "Built with Squad" showcase link from README.md (deferred to Tier 2 opt-in feature). This honors the principle: collect aggregate metrics via public APIs, but never publish individual repo lists without explicit consent. Test discipline: verified npm run build passes; docs-build.test.ts passed structure tests (Astro build failure unrelated to changes). Committed with clear message explaining privacy rationale.
 
 📌 **Team update (2026-03-10T12-55-49Z):** Adoption tracking Tier 1 complete and merged to decisions.md. Privacy-first architecture confirmed: aggregate metrics only, opt-in for individual repos, public showcase only when 5+ projects opt in. Append-only file governance enforced (no deletions in history.md or decisions.md). Microsoft ampersand style guide adopted for documentation.
+
+### Economy Mode Implementation (#500) (2026-03-20)
+
+**Context:** Issue #500 requested economy mode — a session-level and persistent modifier that shifts model selection to cheaper alternatives.
+
+**Architecture decision:** Economy mode is a Layer 3/4 modifier only. Layers 0–2 (explicit user preferences: config.json, session directive, charter) are never downgraded. This preserves user intent while enabling cost savings on auto-selected tasks.
+
+**Implementation:**
+1. `ECONOMY_MODEL_MAP` + `applyEconomyMode()` in `config/models.ts` — pure mapping function for premium→standard and standard→fast downgrades
+2. `readEconomyMode()` + `writeEconomyMode()` — config.json read/write functions (same merge-without-clobber pattern as `writeModelPreference()`)
+3. `resolveModel()` in `config/models.ts` updated with `economyMode?: boolean` option; falls back to reading from `squadDir` if not provided
+4. `resolveModel()` in `agents/model-selector.ts` updated with `economyMode?: boolean` — both SDK resolvers are economy-aware
+5. `squad economy [on|off]` command in CLI for persistent toggle
+6. `--economy` global flag in `cli-entry.ts` sets `SQUAD_ECONOMY_MODE=1` env var for session scope
+7. 34 new tests in `test/economy-mode.test.ts` — all pass
+
+**Key pattern:** Both resolveModel implementations follow identical principle: explicit overrides (user choice) are sacred; economy only affects computed auto-selection.
+
+**PR:** #500 branch `squad/500-economy-mode`

.squad/agents/procedures/history.md

@@ -80,3 +80,25 @@
 
 **Pattern:** NEVER/ALWAYS sections in charters compress well — fold bullet lists into single-paragraph summaries. Essential workflow details (Scribe's commit steps) should stay verbose.
 
+### 2026-03-22: Economy mode skill and personal squad governance (#500, #344)
+
+**Task:** Two governance tasks — economy mode skill design and personal squad coordinator awareness.
+
+**Economy mode (SKILL.md):**
+- Created `.squad/skills/economy-mode/SKILL.md` as a Layer 3 modifier, not a new resolution layer
+- Key design decision: economy mode ONLY affects Layer 3 auto-selection — Layer 0/1/2 (user intent) always wins
+- `💰` indicator in spawn acknowledgments keeps it transparent
+- Activation via session phrase, persistent config (`economyMode: true` in config.json), or CLI flag
+- Architecture trips shift from opus → sonnet; code tasks shift from sonnet → gpt-4.1/gpt-5-mini
+- Confidence: `low` — first implementation, not yet validated
+
+**Personal squad governance (proposals):**
+- Gap analysis: coordinator has no consult mode awareness despite full SDK implementation
+- Five gaps identified: Init Mode missing personal squad resolution, no consult mode detection, TEAM_ROOT has no personal-squad semantics, charter templates lack consult-mode patterns, no consult-mode skill
+- Proposed `CONSULT_MODE: true` as spawn prompt signal, `🧳 consult` in acknowledgments
+- Proposed new consult-mode skill (after governance approval — skill after governance, not before)
+
+**Governance workflow pattern:** When proposals touch squad.agent.md (governance territory), write to `decisions/inbox/` for Flight review. Don't directly edit squad.agent.md — Flight reviews governance changes.
+
+**Catalog audit finding:** `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` appear in model-selection SKILL.md fallback chains but are absent from squad.agent.md's "Valid models" catalog. Documented in economy-mode governance proposal for Flight to address.
+

.squad/decisions/inbox/eecom-economy-mode.md

@@ -0,0 +1,37 @@
+# Economy Mode Design — #500
+
+**Date:** 2026-03-20  
+**Author:** EECOM  
+**Issue:** #500
+
+## Decision
+
+Economy mode is implemented as a modifier that shifts model selection at Layer 3 (task-aware auto) and Layer 4 (default fallback) only. Layers 0–2 (explicit user preferences) are never downgraded.
+
+## Model Map
+
+| Normal | Economy | Use case |
+|--------|---------|----------|
+| `claude-opus-4.6` | `claude-sonnet-4.5` | Architecture, review |
+| `claude-sonnet-4.6` | `gpt-4.1` | Code writing |
+| `claude-sonnet-4.5` | `gpt-4.1` | Code writing |
+| `claude-haiku-4.5` | `gpt-4.1` | Docs, planning, mechanical |
+
+## Activation
+
+1. **Persistent:** `"economyMode": true` in `.squad/config.json` (survives sessions)
+2. **Session:** `--economy` CLI flag (sets `SQUAD_ECONOMY_MODE=1` env var, current session only)
+3. **Toggle command:** `squad economy on|off` writes to config.json
+
+## Hierarchy Integration
+
+Economy mode is a Layer 3/4 modifier — it does NOT override explicit preferences (Layers 0–2). This is intentional: if a user said "always use opus", economy mode respects that choice.
+
+## Implementation Points
+
+- `ECONOMY_MODEL_MAP` + `applyEconomyMode()` in `packages/squad-sdk/src/config/models.ts`
+- `readEconomyMode()` + `writeEconomyMode()` in `packages/squad-sdk/src/config/models.ts`
+- `resolveModel()` in `config/models.ts` accepts `economyMode?: boolean` option; reads from config if not provided
+- `resolveModel()` in `agents/model-selector.ts` also supports `economyMode?: boolean`
+- `squad economy [on|off]` command in `packages/squad-cli/src/cli/commands/economy.ts`
+- `--economy` global flag in `cli-entry.ts`

.squad/decisions/inbox/procedures-economy-mode-governance.md

@@ -0,0 +1,126 @@
+# Proposal: Economy Mode Integration in squad.agent.md
+
+**By:** Procedures (Prompt Engineer)  
+**Date:** 2026-03-22  
+**Issues:** #500  
+**Status:** DRAFT — for Flight review before merging to squad.agent.md
+
+---
+
+## Summary
+
+Economy mode is a new session/persistent modifier that shifts Layer 3 (Task-Aware Auto-Selection) to cost-optimized alternatives. This proposal documents the governance additions needed in `squad.agent.md`.
+
+**Note to Flight:** Procedures owns the skill design. Squad.agent.md is governance — Flight reviews before commit.
+
+---
+
+## 1. New Paragraph After Layer 0 (Per-Agent Model Selection section)
+
+Insert after the existing Layer 0 bullet points and before "**Layer 1 — Session Directive**":
+
+---
+
+**Economy Mode — Cost Modifier (Layer 3 override):** Economy mode shifts all Layer 3 auto-selection to cost-optimized alternatives. It does NOT override Layer 0 (persistent config), Layer 1 (explicit session directive), or Layer 2 (charter preference) — user intent always wins.
+
+- **Activation (session):** User says "use economy mode", "save costs", "go cheap" → activate for this session only.
+- **Activation (persistent):** User says "always use economy mode" OR `"economyMode": true` in `.squad/config.json` → persists across sessions.
+- **Deactivation:** "turn off economy mode" or remove `economyMode` from `config.json`.
+- **On session start:** Read `.squad/config.json`. If `economyMode: true`, activate economy mode before any spawns.
+
+---
+
+## 2. Economy Model Selection Table
+
+Add after Layer 3 normal table:
+
+---
+
+**Economy Mode Layer 3 Table** (active when economy mode is on):
+
+| Task Output | Normal Mode | Economy Mode |
+|-------------|-------------|--------------|
+| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Writing prompts or agent designs | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Architecture, code review, security audits | `claude-opus-4.5` | `claude-sonnet-4.5` |
+| Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` |
+
+Prefer `gpt-4.1` over `gpt-5-mini` for structured output or tool use. Prefer `gpt-5-mini` for pure text generation.
+
+---
+
+## 3. Spawn Acknowledgment Convention
+
+Add to the spawn acknowledgment format guidance:
+
+---
+
+When economy mode is active, include `💰 economy` after the model name in spawn acknowledgments:
+
+```
+🔧 Fenster (gpt-4.1 · 💰 economy) — fixing auth bug
+📋 Scribe (gpt-4.1 · 💰 economy) — logging decision
+```
+
+This gives the user instant visibility that cost-optimized models are in use.
+
+---
+
+## 4. Valid Models Catalog Audit
+
+Current "Valid models" section lists:
+
+```
+Premium: claude-opus-4.6, claude-opus-4.6-fast, claude-opus-4.5
+Standard: claude-sonnet-4.5, claude-sonnet-4, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gemini-3-pro-preview
+Fast/Cheap: claude-haiku-4.5, gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1
+```
+
+**Audit findings:**
+- `claude-opus-4.6` and `claude-opus-4.6-fast` are listed but not used in the Layer 3 table (table uses `claude-opus-4.5`). The Layer 3 table should reference `claude-opus-4.6` as the premium default for consistency with the catalog.
+- `claude-sonnet-4.6` appears in the model-selection SKILL.md but is absent from the valid models list in squad.agent.md. Add it under Standard.
+- Economy mode introduces `gpt-4.1` and `gpt-5-mini` as primary alternatives — both are already in the Fast/Cheap catalog. No additions needed.
+
+**Proposed updated catalog:**
+
+```
+Premium: claude-opus-4.6, claude-opus-4.6-fast, claude-opus-4.5
+Standard: claude-sonnet-4.6, claude-sonnet-4.5, claude-sonnet-4, gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gemini-3-pro-preview
+Fast/Cheap: claude-haiku-4.5, gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1
+```
+
+(Added `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` which appear in the model-selection SKILL.md fallback chains but are missing from squad.agent.md's catalog.)
+
+---
+
+## 5. Config Schema Addition
+
+Add `economyMode` to the config schema reference in squad.agent.md (wherever `defaultModel` is documented):
+
+```json
+{
+  "version": 1,
+  "defaultModel": "claude-sonnet-4.6",
+  "economyMode": true,
+  "agentModelOverrides": {
+    "fenster": "claude-sonnet-4.6"
+  }
+}
+```
+
+---
+
+## Rationale
+
+Economy mode solves a real user need: "I want all agents to run cheaper, but I don't want to set each one individually." It's a session-level modifier that works orthogonally to the existing hierarchy — no layer gets changed, only Layer 3's lookup table swaps. The `💰` indicator keeps it transparent.
+
+The skill (`economy-mode/SKILL.md`) covers the coordinator behavior in detail. This proposal is the governance side — ensuring squad.agent.md is the authoritative source for the feature.
+
+---
+
+## References
+
+- Skill: `.squad/skills/economy-mode/SKILL.md`
+- Issue: #500
+- Model selection skill: `.squad/skills/model-selection/SKILL.md`

.squad/decisions/inbox/procedures-personal-squad-governance.md

@@ -0,0 +1,158 @@
+# Proposal: Personal Squad Governance Awareness in squad.agent.md
+
+**By:** Procedures (Prompt Engineer)  
+**Date:** 2026-03-22  
+**Issues:** #344  
+**Status:** DRAFT — for Flight review before merging to squad.agent.md
+
+---
+
+## Summary
+
+Squad has a consult mode (implemented, per `prd-consult-mode.md`) and personal squad semantics (via `resolveGlobalSquadPath()`), but `squad.agent.md` doesn't tell the coordinator how to reason about either. This proposal documents the gaps and the governance additions needed.
+
+---
+
+## Gap Analysis
+
+### Gap 1: Init Mode references `--global` without explaining personal squad resolution
+
+Current Init Mode says "run `squad init --global` for a personal squad" (implied by CLI docs) but squad.agent.md doesn't explain what a personal squad IS or how the coordinator should detect it.
+
+**What agents need to know:**
+- Personal squad = a squad at the global path (resolved via `resolveGlobalSquadPath()`)
+  - Linux/macOS: `~/.config/squad/.squad`
+  - macOS (alt): `~/Library/Application Support/squad/.squad`
+  - Windows: `%APPDATA%\squad\.squad`
+- If `.squad/config.json` contains `"consult": true`, the coordinator is working inside a consult session
+- `sourceSquad` in `config.json` points to the original personal squad (for Scribe extraction context)
+
+### Gap 2: No coordinator guidance for consult mode
+
+`squad.agent.md` mentions nothing about consult mode. The coordinator doesn't know:
+- How to recognize it's in a consult session
+- That writes go to the project `.squad/` (isolated copy) — NOT the personal squad
+- That Scribe's charter is patched with extraction instructions
+- That `.squad/extract/` is a staging area for generic learnings
+
+### Gap 3: TEAM_ROOT works, but personal squad semantics are absent
+
+The coordinator resolves `TEAM_ROOT` correctly (Worktree Awareness section), but:
+- No distinction between "project squad" vs "personal squad copy in consult mode"
+- No guidance on what to tell agents about their squad context when in consult mode
+
+### Gap 4: Charter templates have no personal-squad-aware patterns
+
+Agent charters have no concept of:
+- Consult mode restrictions (agents shouldn't commit to project, shouldn't pollute personal squad)
+- Extraction tagging (Scribe needs to flag decisions as generic vs project-specific)
+
+### Gap 5: No skill for consult-mode behavior
+
+There is no skill for consult-mode coordinator behavior, even though consult mode has distinct patterns (invisibility, extraction, isolation).
+
+---
+
+## Proposed squad.agent.md Additions
+
+### Addition 1: Consult Mode Detection (in Team Mode → On Session Start)
+
+After "resolve the team root" and before Issue Awareness, add:
+
+---
+
+**Consult Mode Detection:** After resolving team root, check `.squad/config.json` for `"consult": true`.
+
+- If `consult: true` → **Consult mode is active.** This is a personal squad consulting on a project.
+  - The `.squad/` directory is an isolated copy of the user's personal squad.
+  - `sourceSquad` in `config.json` contains the path to the original personal squad.
+  - Do NOT read or write to `sourceSquad` — it's out of scope. Only operate within TEAM_ROOT.
+  - Scribe's charter is already patched with extraction instructions — no coordinator action needed.
+  - Include `🧳 consult` in your session acknowledgment: `Squad v{version} (🧳 consult — {projectName})`
+  - Remind agents: decisions they make here are project-isolated until explicitly extracted.
+- If `consult: false` or absent → Normal mode. Team root is authoritative.
+
+---
+
+### Addition 2: Personal Squad Path Reference
+
+Add a new subsection under "Worktree Awareness":
+
+---
+
+**Personal Squad Paths:** The global squad path is resolved by `resolveGlobalSquadPath()`:
+
+| Platform | Path |
+|----------|------|
+| Linux | `~/.config/squad/.squad` |
+| macOS | `~/Library/Application Support/squad/.squad` |
+| Windows | `%APPDATA%\squad\.squad` |
+
+The coordinator should NEVER hard-code these paths. Use `squad --global` or `resolveGlobalSquadPath()` to resolve. Only relevant in consult mode (to understand the `sourceSquad` field) — the coordinator does NOT read the personal squad directly during a session.
+
+---
+
+### Addition 3: Consult Mode Spawn Guidance
+
+Add to the spawn template section:
+
+---
+
+**In consult mode:** Pass `CONSULT_MODE: true` and `PROJECT_NAME: {projectName}` in spawn prompts alongside `TEAM_ROOT`. This lets agents know:
+1. Their decisions will be reviewed for extraction — keep project-specific and generic reasoning separate
+2. They should NOT reference personal squad paths or personal squad agent names
+3. Scribe will classify their decisions — agents should write clear, extractable decision rationale
+
+---
+
+### Addition 4: Consult Mode Acknowledgment Format
+
+Add to spawn acknowledgment conventions:
+
+```
+🧳 consult mode active — Fenster (claude-sonnet-4.5) — refactoring auth module
+     ↳ decisions staged in .squad/extract/ for review before extraction
+```
+
+---
+
+## Proposed New Skill
+
+**Skill needed:** `.squad/skills/consult-mode/SKILL.md`
+
+Should cover:
+- Detecting consult mode from config.json
+- Coordinator behavior changes (CONSULT_MODE in spawn prompts)
+- Scribe extraction workflow (already documented in prd-consult-mode.md — condense into skill)
+- Acknowledgment format conventions
+- STOP: extraction is always user-driven via `squad extract` — coordinator never auto-extracts
+
+This skill should be authored after this governance proposal is approved, to avoid the skill getting ahead of the governance.
+
+---
+
+## Charter Template Additions
+
+All agent charter templates should include a note in "How I Work":
+
+```markdown
+**Consult Mode Awareness:** If `CONSULT_MODE: true` is in my spawn prompt, I'm working on a project outside my home squad. My decisions here are project-isolated. Write extractable rationale so Scribe can classify them for `squad extract` review.
+```
+
+This should be added to `.squad/templates/charter.md` (if it exists) and `.squad/agents/scribe/charter.md` (Scribe already has extraction logic, but clarifying the classification responsibility is valuable).
+
+---
+
+## Rationale
+
+Consult mode is fully implemented at the SDK level (`prd-consult-mode.md`, `squad consult` command) but the coordinator has no awareness of it. The result: agents running in a consult session have no context that they're in a temporary, isolated copy of a personal squad. They might make decisions as if they're permanent, or reference the project in ways that pollute the personal squad on extraction.
+
+These governance additions close the loop between the implementation (CLI + SDK) and the runtime behavior (coordinator + agents).
+
+---
+
+## References
+
+- Consult mode PRD: `.squad/identity/prd-consult-mode.md`
+- Issue: #344
+- Flight ambient personal squad note: `.squad/decisions/inbox/flight-ambient-personal-squad.md`