Initialize Tier Protocol plan and update tasks

Author: apiad

.gemini/commands/brainstorm.toml

@@ -0,0 +1,31 @@
+description = "Interactive brainstorming session to challenge ideas, identify risks, and explore alternatives without making changes."
+
+prompt = """
+You are an expert critical thinking partner and strategic advisor. You are executing the custom `/brainstorm` command.
+
+**CRITICAL MANDATE:** This command is strictly for exploration, risk assessment, and creative problem-solving. You MUST NOT modify, create, or delete any files in the repository. Your goal is to provide high-signal feedback and challenging questions.
+
+Follow this interactive workflow:
+
+### Phase 1: Context & Discovery (Optional)
+1. If the brainstorming topic relates to existing code or documentation, use `list_directory`, `read_file`, `grep_search`, or `glob` to gather relevant context.
+2. If external information is needed, use `web_search` and `web_fetch` to research state-of-the-art practices or similar problems.
+3. Use `run_shell_command` only for read-only operations (e.g., `find`, `grep`, `ls`).
+
+NOTE: Keep this phase very short and focused, no more than 2-3 tool calls. If more context is necessary, instruct the user to provide it or suggest they use /research to gather it themselves before returning to brainstorming.
+
+### Phase 2: Critical Exploration (The Loop)
+1. **Analyze:** Evaluate the user's idea or problem statement. Look for hidden assumptions, potential edge cases, and architectural risks.
+2. **Challenge:** Do not simply agree. Provide critical advice. If an idea seems flawed, explain why and suggest alternatives.
+3. **Question:** Ask 1-3 hard, targeted follow-up questions to push the user's thinking further.
+4. **Interactive Dialogue:** Use `ask_user` to present your critique and questions. Keep the interaction fast and focused. Continue this loop until the user is satisfied or a natural conclusion is reached.
+
+### Phase 3: Synthesis & Next Steps
+1. Once the brainstorming session concludes, provide a concise summary of:
+    - **Key Insights:** The most valuable takeaways from the session.
+    - **Identified Risks:** Potential pitfalls or blockers discovered.
+    - **Recommendations:** Actionable advice for the next phase.
+2. **Propose Action:** Suggest that the user transition from brainstorming to planning by using the `/plan` command to turn these insights into a concrete technical strategy.
+
+Start by asking the user for the topic or idea they want to brainstorm.
+"""

README.md

@@ -59,6 +59,7 @@ The `.gemini/commands/` directory defines specialized workflows that automate ev
 ### 🔍 Phase 1: Planning & Discovery
 *   **`/research <topic>`**: A deep, 3-phase investigation (Planning -> Data Gathering -> Reporting) that produces exhaustive Markdown reports in the `research/` directory. **Crucial for gathering technical requirements and state-of-the-art context.**
 *   **`/learn <topic>`**: A grounded learning lifecycle (Audit -> Strategic Mapping -> Execution -> Codification) for mastering new technologies and building a permanent, machine-readable knowledge base in `.gemini/skills/` using the specialized `learner` subagent.
+*   **`/brainstorm`**: An interactive, high-signal brainstorming session. The agent acts as a critical partner—challenging your assumptions, identifying architectural risks, and asking hard follow-up questions—without making any changes to the codebase.
 *   **`/plan`**: The **Architectural Bridge**. This interactive workflow translates ideas into actionable execution plans:
     *   **Phase 1 (Clarification):** The agent interviews you to resolve ambiguities before planning.
     *   **Phase 2 (Agentic Analysis):** A specialized `planner` subagent scans the codebase and generates a detailed technical strategy.

TASKS.md

@@ -18,10 +18,14 @@ Put done tasks into the Archive.
 
 ## Active Tasks
 
+- [ ] Implement the three-tier model routing protocol (Orchestrator, Thinker, Executioner) with semantic signaling and automated tier switching. (See plan: plans/tier-protocol-implementation.md)
+
 ---
 
 ## Archive
 
+- [x] Implement the new `/brainstorm` command to facilitate interactive, critical-thinking sessions and architectural risk assessment. (2026-03-24) (See plan: plans/add-brainstorm-command.md)
+
 - [x] Integrate `coder` subagent into `/task work` workflow to delegate granular implementation steps. (2026-03-23) (See plan: plans/implement-coder-agent.md)
 
 - [x] Implement dynamic structural testing suite and finalize documentation sync. (2026-03-23) (See plan: plans/implement-maintenance-v2.md)

docs/user-guide.md

@@ -34,6 +34,13 @@ Your primary tool for forensic, scientific investigation.
 - **How it works:** When a bug is detected, the `/debug` command implements a principled approach to problem-solving using the specialized `debugger` subagent. It moves through four distinct phases: Context Analysis, Hypothesis Formulation, Isolated Testing on a temporary branch (`debug/hyp-*`), and finally a Synthesis of the findings into a **Root Cause Analysis (RCA)** report.
 - **Why it works:** It forces the agent to identify the root cause *before* attempting a fix, preventing "guess-and-check" coding that can lead to regressions.
 
+### `/brainstorm`
+
+Your tool for interactive, critical-thinking sessions.
+
+- **How it works:** You present an idea, problem, or architectural choice. The agent uses discovery tools to gather context and then enters a "challenge loop" where it pushes back on weak points, identifies hidden risks, and asks tough questions.
+- **Why it works:** It forces you to defend your ideas and refine them *before* they even reach the planning stage, ensuring higher-quality strategies.
+
 ---
 
 ## 🌉 Phase 2: Strategy & Planning

journal/2026-03-24.md

@@ -0,0 +1 @@
+[2026-03-24T10:45:17] - Plan: Tier Protocol Model Routing System and brainstorm command

plans/add-brainstorm-command.md

@@ -0,0 +1,101 @@
+# Execution Plan: Add `/brainstorm` Command
+
+This plan outlines the steps to add a new `/brainstorm` command to the Gemini CLI framework. This command is designed for high-signal, critical-thinking sessions, providing a dedicated space for exploration and risk assessment without making any changes to the codebase.
+
+## Objective
+Implement a new `/brainstorm` command in `.gemini/commands/brainstorm.toml` that acts as a critical thinking partner, challenging ideas and identifying risks while strictly adhering to a "no side effects" mandate.
+
+## Architectural Impact
+- **Discovery Layer Enhancement**: Adds a dedicated tool for the "Discovery & Audit" phase of the project lifecycle.
+- **Safety**: Reinforces the framework's philosophy of separating discovery/analysis from implementation/execution.
+- **Documentation**: Updates the project's documentation to reflect the new capability.
+
+## File Operations
+
+### Create
+- **`.gemini/commands/brainstorm.toml`**: The command definition file.
+
+### Modify
+- **`README.md`**: Update the "Phase 1: Planning & Discovery" section.
+- **`docs/user-guide.md`**: Update the "Phase 1: Discovery & Audit" section.
+
+---
+
+## Step-by-Step Execution
+
+### Step 1: Create the Command Definition
+Create the file `.gemini/commands/brainstorm.toml` with the following content:
+
+```toml
+description = "Interactive brainstorming session to challenge ideas, identify risks, and explore alternatives without making changes."
+
+prompt = \"\"\"
+You are an expert critical thinking partner and strategic advisor. You are executing the custom `/brainstorm` command.
+
+**CRITICAL MANDATE:** This command is strictly for exploration, risk assessment, and creative problem-solving. You MUST NOT modify, create, or delete any files in the repository. Your goal is to provide high-signal feedback and challenging questions.
+
+Follow this interactive workflow:
+
+### Phase 1: Context & Discovery (Optional)
+1. If the brainstorming topic relates to existing code or documentation, use `list_directory`, `read_file`, `grep_search`, or `glob` to gather relevant context.
+2. If external information is needed, use `web_search` and `web_fetch` to research state-of-the-art practices or similar problems.
+3. Use `run_shell_command` only for read-only operations (e.g., `find`, `grep`, `ls`).
+
+### Phase 2: Critical Exploration (The Loop)
+1. **Analyze:** Evaluate the user's idea or problem statement. Look for hidden assumptions, potential edge cases, and architectural risks.
+2. **Challenge:** Do not simply agree. Provide critical advice. If an idea seems flawed, explain why and suggest alternatives.
+3. **Question:** Ask 1-3 hard, targeted follow-up questions to push the user's thinking further.
+4. **Interactive Dialogue:** Use `ask_user` to present your critique and questions if they are structured. Or ask general questions. Keep the interaction fast and focused. Continue this loop until the user is satisfied or a natural conclusion is reached.
+
+### Phase 3: Synthesis & Next Steps
+1. Once the brainstorming session concludes, provide a concise summary of:
+    - **Key Insights:** The most valuable takeaways from the session.
+    - **Identified Risks:** Potential pitfalls or blockers discovered.
+    - **Recommendations:** Actionable advice for the next phase.
+2. **Propose Action:** Suggest that the user transition from brainstorming to planning by using the `/plan` command to turn these insights into a concrete technical strategy.
+
+Start by asking the user for the topic or idea they want to brainstorm or infer from context if provided.
+\"\"\"
+```
+
+### Step 2: Update Main README
+Modify `README.md` to include `/brainstorm` in the "Phase 1: Planning & Discovery" section, after `/learn`:
+
+```markdown
+*   **`/brainstorm`**: An interactive, high-signal brainstorming session. The agent acts as a critical partner—challenging your assumptions, identifying architectural risks, and asking hard follow-up questions—without making any changes to the codebase.
+```
+
+### Step 3: Update User Guide
+Modify `docs/user-guide.md` to include `/brainstorm` in the "Phase 1: Discovery & Audit" section, after `/debug`:
+
+```markdown
+### `/brainstorm`
+
+Your tool for interactive, critical-thinking sessions.
+
+- **How it works:** You present an idea, problem, or architectural choice. The agent uses discovery tools to gather context and then enters a "challenge loop" where it pushes back on weak points, identifies hidden risks, and asks tough questions.
+- **Why it works:** It forces you to defend your ideas and refine them *before* they even reach the planning stage, ensuring higher-quality strategies.
+```
+
+---
+
+## Testing Strategy
+
+### 1. Functional Verification
+Invoke the command:
+```bash
+gemini /brainstorm "Adding a new caching layer to the API"
+```
+**Expected Results:**
+- The agent asks for more details or begins analyzing existing code using `list_directory` or `read_file`.
+- The agent provides at least one critical observation (e.g., cache invalidation risks).
+- The agent asks targeted follow-up questions.
+- The agent *never* attempts to create or modify files.
+
+### 2. Workflow Verification
+- Ensure the session ends with a summary of insights and risks.
+- Ensure the agent explicitly suggests using `/plan` at the end of the summary.
+
+### 3. Documentation Verification
+- Verify that the new command is listed correctly in the `README.md` and `docs/user-guide.md`.
+- Verify that `gemini --help` (or equivalent) correctly displays the new command description if the CLI supports it.

plans/tier-protocol-implementation.md

@@ -0,0 +1,159 @@
+# Implementation Plan: Tier Protocol Model Routing System
+
+This plan outlines the implementation of the "Tier Protocol" for the Gemini CLI, enabling dynamic model routing based on task complexity (Orchestration, Thinking, Execution).
+
+## Objective
+Establish a three-tier model routing system to optimize performance, cost, and reasoning quality by using specialized models for different phases of the agent's workflow.
+
+## Architectural Impact
+- **Middleware Integration**: Adds a `BeforeModel` hook (`tier_router.py`) that acts as a traffic controller for model selection.
+- **Semantic Signaling**: Uses explicit `[Tier: *]` tags in assistant messages to communicate routing intent to the framework.
+- **Centralized Configuration**: Standardizes model mapping and default settings in `.gemini/settings.json`.
+- **System-level Feedback**: Integrates `notify-send` for real-time user visibility of tier switches.
+
+## File Operations
+
+| Action | File | Description |
+| :--- | :--- | :--- |
+| **Modify** | `GEMINI.md` | Define the Tier Protocol, models, signals, and usage guidelines. |
+| **Create** | `.gemini/hooks/tier_router.py` | Implement the logic to parse signals and route models. |
+| **Modify** | `.gemini/settings.json` | Register the `BeforeModel` hook and set the default model. |
+| **Modify** | `.gemini/commands/*.toml` | Update command prompts to include tier signaling instructions. |
+
+## Step-by-Step Execution
+
+### Step 1: Document the Tier Protocol in `GEMINI.md`
+Add a new section to `GEMINI.md` defining the protocol:
+
+```markdown
+## Tier Protocol
+
+To optimize reasoning and execution, this project uses a multi-tier model routing system:
+
+| Tier | Model | Use Case | Signal |
+| :--- | :--- | :--- | :--- |
+| **Orchestrator** | `gemini-3-flash-preview` | Default routing, task management, and fast orchestration. | `[Tier: Orchestrator]` |
+| **Thinker** | `gemini-3.1-pro-preview` | Deep architectural planning, RCA, and complex logic. | `[Tier: Thinker]` |
+| **Executioner** | `gemini-2.5-flash` | High-velocity coding, boilerplate, and tool-heavy tasks. | `[Tier: Executioner]` |
+
+**Guidelines:**
+- **Implicit Default:** All sessions start in Orchestrator tier.
+- **Explicit Switching:** Always emit the signal (e.g., `[Tier: Thinker]`) at the end of your response to route the *next* turn to that model.
+- **Phase Transition:** Switch to **Thinker** for discovery/planning and **Executioner** for task implementation.
+```
+
+### Step 2: Implement the `tier_router` Hook
+Create `.gemini/hooks/tier_router.py` with the following logic:
+
+```python
+import sys
+import json
+import re
+import os
+import subprocess
+
+# Model Mapping
+TIER_MAPPING = {
+    "Orchestrator": "gemini-3-flash-preview",
+    "Thinker": "gemini-3.1-pro-preview",
+    "Executioner": "gemini-2.5-flash"
+}
+
+def main():
+    try:
+        input_data = sys.stdin.read()
+        if not input_data:
+            print(json.dumps({"decision": "allow"}))
+            return
+        
+        data = json.loads(input_data)
+        history = data.get("history", [])
+        
+        # Identify target tier from last assistant message
+        target_tier = None
+        for message in reversed(history):
+            if message.get("role") == "assistant":
+                content = message.get("content", "")
+                match = re.search(r"\[Tier:\s*(Orchestrator|Thinker|Executioner)\]", content)
+                if match:
+                    target_tier = match.group(1)
+                    break
+        
+        # Prepare response
+        response = {"decision": "allow"}
+        
+        if target_tier and target_tier in TIER_MAPPING:
+            model_id = TIER_MAPPING[target_tier]
+            response["model"] = model_id
+            response["systemMessage"] = f"Tier Protocol: Active ({target_tier})"
+            
+            # User Notification
+            try:
+                subprocess.run([
+                    "notify-send", 
+                    "Gemini Tier Switch", 
+                    f"Routing to {target_tier}: {model_id}", 
+                    "-i", "dialog-information", "-t", "2000"
+                ], check=False)
+            except:
+                pass
+
+        print(json.dumps(response))
+            
+    except Exception as e:
+        sys.stderr.write(f"Error in tier_router: {str(e)}\n")
+        print(json.dumps({"decision": "allow"}))
+
+if __name__ == "__main__":
+    main()
+```
+
+### Step 3: Update `settings.json` Configuration
+Register the hook and set the default model:
+
+```json
+{
+  "model": "gemini-3-flash-preview",
+  "hooks": {
+    "BeforeModel": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "tier-router",
+            "type": "command",
+            "command": "python3 .gemini/hooks/tier_router.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Step 4: Update Command Prompts for Signaling
+Update `.gemini/commands/*.toml` to incorporate tier instructions.
+
+#### Thinker-Heavy Commands
+Add `[Tier: Thinker]` requirement to:
+- `brainstorm.toml`: "Start by switching to `[Tier: Thinker]` to engage deep reasoning."
+- `plan.toml`: "Use `[Tier: Thinker]` for architectural analysis phases."
+- `research.toml`, `review.toml`, `learn.toml`, `issues.toml`, `document.toml`, `draft.toml`: Update to prioritize Thinker.
+
+#### Executioner-Heavy Commands
+Add `[Tier: Executioner]` requirement to:
+- `commit.toml`: "Switch to `[Tier: Executioner]` for rapid change grouping and committing."
+- `scaffold.toml`: "Use `[Tier: Executioner]` for boilerplate generation."
+
+#### Hybrid Commands (Phase-based Routing)
+- `debug.toml`:
+  - **Phase 2 (Hypothesis):** Switch to `[Tier: Thinker]`.
+  - **Phase 3 (Testing):** Switch to `[Tier: Executioner]` for diagnostic branch work.
+- `task.toml`:
+  - **Phase 3 (TCR Loop):** Instruct the Orchestrator to switch to `[Tier: Executioner]` for implementation steps.
+
+## Testing Strategy
+1. **Routing Logic Validation**: Use a mock session JSON (containing `[Tier: Thinker]`) and pipe it into `tier_router.py` to verify the output contains `"model": "gemini-3.1-pro-preview"`.
+2. **Notification Test**: Trigger the hook and verify the `notify-send` desktop alert appears.
+3. **End-to-End Command Test**: Run `/plan` and verify the first assistant turn ends with `[Tier: Thinker]`, followed by the model switch in the subsequent turn.
+4. **Integration Test**: Verify `settings.json` registration doesn't interfere with existing hooks (e.g., `log.py`, `notify.py`).