From 1ae753c930f5235f2925865b9929c446c4867627 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 02:43:29 -0700 Subject: [PATCH] feat: economy mode skill, governance proposals for #500 and #344 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .squad/skills/economy-mode/SKILL.md: Layer 3 cost modifier - Economy table shifts code tasks to gpt-4.1/gpt-5-mini, arch to sonnet - Activation: session phrase, config.json economyMode:true, or --economy flag - Layer 0/1/2 (user intent) always overrides economy mode - ๐Ÿ’ฐ indicator in spawn acknowledgments - Confidence: low (first implementation) - Add .squad/decisions/inbox/procedures-economy-mode-governance.md - Draft additions to squad.agent.md for Flight review - Economy mode paragraph after Layer 0, updated table, ๐Ÿ’ฐ convention - Valid models catalog audit findings (claude-sonnet-4.6 missing, etc.) - Add .squad/decisions/inbox/procedures-personal-squad-governance.md - Five gap analysis: Init Mode, consult mode detection, TEAM_ROOT semantics, charter templates, missing consult-mode skill - Proposed CONSULT_MODE spawn signal and ๐Ÿงณ acknowledgment format - Proposed new consult-mode skill (post-governance-approval) - Update procedures history.md with learnings Closes #500 References #344 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/procedures/history.md | 22 +++ .../procedures-economy-mode-governance.md | 126 ++++++++++++++ .../procedures-personal-squad-governance.md | 158 ++++++++++++++++++ .squad/skills/economy-mode/SKILL.md | 114 +++++++++++++ 4 files changed, 420 insertions(+) create mode 100644 .squad/decisions/inbox/procedures-economy-mode-governance.md create mode 100644 .squad/decisions/inbox/procedures-personal-squad-governance.md create mode 100644 .squad/skills/economy-mode/SKILL.md diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md index 2390dfc70..ea52095bf 100644 --- a/.squad/agents/procedures/history.md +++ b/.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. + diff --git a/.squad/decisions/inbox/procedures-economy-mode-governance.md b/.squad/decisions/inbox/procedures-economy-mode-governance.md new file mode 100644 index 000000000..4561be940 --- /dev/null +++ b/.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` diff --git a/.squad/decisions/inbox/procedures-personal-squad-governance.md b/.squad/decisions/inbox/procedures-personal-squad-governance.md new file mode 100644 index 000000000..b46bb17de --- /dev/null +++ b/.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` diff --git a/.squad/skills/economy-mode/SKILL.md b/.squad/skills/economy-mode/SKILL.md new file mode 100644 index 000000000..696e778c4 --- /dev/null +++ b/.squad/skills/economy-mode/SKILL.md @@ -0,0 +1,114 @@ +--- +name: "economy-mode" +description: "Shifts Layer 3 model selection to cost-optimized alternatives when economy mode is active." +domain: "model-selection" +confidence: "low" +source: "manual" +--- + +## SCOPE + +โœ… THIS SKILL PRODUCES: +- A modified Layer 3 model selection table applied when economy mode is active +- `economyMode: true` written to `.squad/config.json` when activated persistently +- Spawn acknowledgments with `๐Ÿ’ฐ` indicator when economy mode is active + +โŒ THIS SKILL DOES NOT PRODUCE: +- Code, tests, or documentation +- Cost reports or billing artifacts +- Changes to Layer 0, Layer 1, or Layer 2 resolution (user intent always wins) + +## Context + +Economy mode shifts Layer 3 (Task-Aware Auto-Selection) to lower-cost alternatives. It does NOT override persistent config (`defaultModel`, `agentModelOverrides`) or per-agent charter preferences โ€” those represent explicit user intent and always take priority. + +Use this skill when the user wants to reduce costs across an entire session or permanently, without manually specifying models for each agent. + +## Activation Methods + +| Method | How | +|--------|-----| +| Session phrase | "use economy mode", "save costs", "go cheap", "reduce costs" | +| Persistent config | `"economyMode": true` in `.squad/config.json` | +| CLI flag | `squad --economy` | + +**Deactivation:** "turn off economy mode", "disable economy mode", or remove `economyMode` from `config.json`. + +## Economy Model Selection Table + +When economy mode is **active**, Layer 3 auto-selection uses this table instead of the normal defaults: + +| 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`** when the task involves structured output or agentic tool use. Prefer `gpt-5-mini` for pure text generation tasks where latency matters. + +## AGENT WORKFLOW + +### On Session Start + +1. READ `.squad/config.json` +2. CHECK for `economyMode: true` โ€” if present, activate economy mode for the session +3. STORE economy mode state in session context + +### On User Phrase Trigger + +**Session-only (no config change):** "use economy mode", "save costs", "go cheap" + +1. SET economy mode active for this session +2. ACKNOWLEDGE: `โœ… Economy mode active โ€” using cost-optimized models this session. (Layer 0 and Layer 2 preferences still apply)` + +**Persistent:** "always use economy mode", "save economy mode" + +1. WRITE `economyMode: true` to `.squad/config.json` (merge, don't overwrite other fields) +2. ACKNOWLEDGE: `โœ… Economy mode saved โ€” cost-optimized models will be used until disabled.` + +### On Every Agent Spawn (Economy Mode Active) + +1. CHECK Layer 0a/0b first (agentModelOverrides, defaultModel) โ€” if set, use that. Economy mode does NOT override Layer 0. +2. CHECK Layer 1 (session directive for a specific model) โ€” if set, use that. Economy mode does NOT override explicit session directives. +3. CHECK Layer 2 (charter preference) โ€” if set, use that. Economy mode does NOT override charter preferences. +4. APPLY economy table at Layer 3 instead of normal table. +5. INCLUDE `๐Ÿ’ฐ` in spawn acknowledgment: `๐Ÿ”ง {Name} ({model} ยท ๐Ÿ’ฐ economy) โ€” {task}` + +### On Deactivation + +**Trigger phrases:** "turn off economy mode", "disable economy mode", "use normal models" + +1. REMOVE `economyMode` from `.squad/config.json` (if it was persisted) +2. CLEAR session economy mode state +3. ACKNOWLEDGE: `โœ… Economy mode disabled โ€” returning to standard model selection.` + +### STOP + +After updating economy mode state and including the `๐Ÿ’ฐ` indicator in spawn acknowledgments, this skill is done. Do NOT: +- Change Layer 0, Layer 1, or Layer 2 model choices +- Override charter-specified models +- Generate cost reports or comparisons +- Fall back to premium models via economy mode (economy mode never bumps UP) + +## Config Schema + +`.squad/config.json` economy-related fields: + +```json +{ + "version": 1, + "economyMode": true +} +``` + +- `economyMode` โ€” when `true`, Layer 3 uses the economy table. Optional; absent = economy mode off. +- Combines with `defaultModel` and `agentModelOverrides` โ€” Layer 0 always wins. + +## Anti-Patterns + +- **Don't override Layer 0 in economy mode.** If the user set `defaultModel: "claude-opus-4.6"`, they want quality. Economy mode only affects Layer 3 auto-selection. +- **Don't silently apply economy mode.** Always acknowledge when activated or deactivated. +- **Don't treat economy mode as permanent by default.** Session phrases activate session-only; only "always" or `config.json` persist it. +- **Don't bump premium tasks down too far.** Architecture and security reviews shift from opus to sonnet in economy mode โ€” they do NOT go to fast/cheap models.