squad-bmad 1.2.0

package/README.md

@@ -0,0 +1,141 @@
+# Squad BMAD: Automated Project Orchestration Assistant with Gemini & Claude Code
+
+[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/squad-bmad.svg)](https://www.npmjs.com/package/squad-bmad)
+
+*Read this in other languages: [English](README.md), [Tiếng Việt](README.vi.md).*
+
+Welcome to **Squad BMAD** – a boilerplate/design solution to transform **Gemini CLI** into a true **Project Manager & Principal Tech Lead**. By combining Gemini's orchestration power with **Claude Code's** excellent coding and reasoning capabilities via **Tmux**, this project automates and optimizes the software development workflow based on the **BMAD** methodology.
+
+---
+
+## 🌟 Benefits
+
+The BMAD (Build-Measure-Analyze-Deploy) methodology is known for maintaining strictness, clear structure, and being strongly **spec-driven**. However, its biggest drawback is that the operation process requires many steps and manual actions.
+
+**Squad BMAD completely solves this problem:**
+- **Seamless Automation:** Makes operating a project with the BMAD method smooth and continuous without requiring your intervention in every small step.
+- **An Indefatigable Project Assistant:** This assistant will help you answer and handle BMAD steps, automatically operating and implementing all Epics and Stories.
+- **Focus on Core Value:** You only need to talk to the Assistant (Gemini), make high-level decisions, and the Assistant will automatically delegate tasks and monitor the other Agents (Claude Code).
+
+---
+
+## 📋 System Requirements
+
+To run this system smoothly, you need to prepare:
+
+- **Claude Code Account:** Required to launch the Execution (Implement) and Reasoning (Brainstorm) Agents.
+- **Gemini Account (Gemini CLI):** Acts as the "Orchestrator" coordinating the entire workflow.
+- **Tmux Environment:** Installed on your machine (MacOS/Linux) to manage multi-threaded work sessions.
+- **Experience:** Have used or possess a basic understanding of the **BMAD** method.
+
+---
+
+## 🧠 Core Philosophy
+
+Squad BMAD is built on immutable principles:
+
+1. **Strict Adherence to BMAD Processes:** All tasks from ideation, writing specifications, to coding and reviewing strictly follow BMAD's workflows. This ensures the project always stays on track and technical documentation is always synchronized with the actual code.
+2. **Fresh Chat & Context Isolation:** Before starting a new workflow, the system must clear the context (by sending the `/clear` command). This prevents the AI (Claude) from hallucinating due to carrying too much old information, keeping its reasoning sharp.
+3. **Clear Agent Roles:** Applying the true spirit of BMAD, the system divides Agents into specialized "personas" (PM, Architect, Dev, QA) to optimize the performance of each AI Model.
+
+---
+
+## ⚙️ System Architecture & Operation
+
+The system operates based on the smooth coordination of **3 Tmux sessions**:
+
+1. **Session 1: Gemini Orchestrator**
+   - The master operating the other 2 tmux sessions.
+   - Communicates directly with you, understands requirements, and maps them to BMAD workflows.
+   - Monitors, accepts the results, and makes transition decisions.
+
+2. **Session 2: Claude Code - Implement**
+   - Acts as a **Developer**.
+   - Specialized in writing code, fixing bugs, and running tests.
+   - Uses the **Claude Sonnet** model to ensure fast speed, excellent coding, and cost savings.
+
+3. **Session 3: Claude Code - Brainstorm**
+   - Acts as an **Architect / PM / QA**.
+   - Specialized in reasoning about architecture, solving complex problems, designing systems, and reviewing code.
+   - Uses the **Claude Opus** model for tasks requiring deep logical thinking.
+
+### 🔄 Event-Driven System with Hooks
+
+Instead of Gemini having to constantly poll the screen to see if Claude Code is done, this project uses an **Event-driven Hooks** mechanism via the `.claude/settings.json` file.
+
+Whenever Claude Code (in tmux 2 or 3) completes a task or needs to stop, the system automatically triggers a bash script (like `.claude/hooks/wakeup-gemini.sh`). This script immediately sends a signal back to Gemini's Tmux Session, "waking up" Gemini to:
+1. Read the work results.
+2. Evaluate and accept the source code.
+3. Report back to you or automatically proceed to the next step according to the BMAD process.
+
+---
+
+## 🚀 Workflow Summary
+
+1. You open 3 Tmux sessions (1 for Gemini, 2 for Claude Code).
+2. You chat with Gemini: *"Please implement Story #123 for me."*
+3. Gemini receives the command, analyzes it according to the BMAD workflow, and sends the command (along with `/clear` to reset context) to `Claude Code - Implement` via a secure shell script.
+4. Gemini goes into an "Idle" state, waiting.
+5. `Claude Code - Implement` busily writes code. When done, it automatically triggers the Hook.
+6. The Hook runs the bash script, sending an `Enter` keystroke and a notification message to Gemini's screen.
+7. Gemini "wakes up", reads Claude Code's screen log, accepts the results, and reports back to you.
+
+---
+
+With **Squad BMAD**, you are no longer a coder painstakingly typing every line of code; you are a true **Project Manager** commanding an elite AI squad!
+
+---
+
+## 🛠 Setup & Usage
+
+### 1. Install Squad BMAD
+
+From your project directory, run:
+
+```bash
+npx squad-bmad install
+```
+
+This will:
+- Copy hook scripts, tmux utilities, and Gemini slash commands into your project.
+- Automatically configure `.claude/settings.json` with the required hooks (or print instructions if you already have a custom hooks section).
+- Remind you to install the BMAD Method (`npx bmad-method install`) if it's not already present.
+
+> **Upgrading?** Run `npx squad-bmad upgrade` to overwrite existing files with the latest version.
+
+### 2. Prepare the Tmux Environment
+
+All 3 sessions follow a **project-aware naming convention** based on your folder name. Run the setup script from your project directory:
+
+```bash
+bash .gemini/scripts/setup-sessions.sh
+```
+
+This will automatically create (or skip if already existing):
+- `gemini-orchestrator-<folder>` — launches `gemini --yolo --model gemini-3-pro-preview`
+- `claude-implement-<folder>` — launches `claude --dangerously-skip-permissions --model sonnet`
+- `claude-brainstorm-<folder>` — launches `claude --dangerously-skip-permissions --model opus`
+
+### 3. Start Gemini Orchestrator
+
+Attach to the Gemini session for your project:
+```bash
+tmux attach -t gemini-orchestrator-<folder>
+```
+
+### 4. Run the Slash Command
+
+Inside Gemini, run the slash command — **no arguments needed**. Gemini will auto-detect the project folder and verify all sessions:
+
+```text
+/withClaudeCodeTmux
+```
+
+### 5. Start Working
+The system is now ready. You simply communicate with Gemini like a project manager:
+- *"Start this project for me using the generate-project-context flow."*
+- *"Which Epic are we in? Create a new story for the login feature."*
+- *"Implement Story #5 according to the dev-story process."*
+
+Gemini will automatically analyze, clear the context (send `/clear`), route the command to the appropriate Claude session, and will automatically "wake up" to accept the work when it receives the Hook feedback signal from Claude.

package/README.vi.md

@@ -0,0 +1,139 @@
+# Squad BMAD: Trợ Lý Ảo Điều Phối Dự Án Tự Động Với Gemini & Claude Code
+
+[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/squad-bmad.svg)](https://www.npmjs.com/package/squad-bmad)
+
+Chào mừng bạn đến với **Squad BMAD** – một boilerplate/giải pháp thiết kế để biến **Gemini CLI** trở thành một **Project Manager & Principal Tech Lead** thực thụ. Bằng cách kết hợp sức mạnh điều phối của Gemini và khả năng lập trình/suy luận xuất sắc của **Claude Code** thông qua môi trường **Tmux**, dự án này tự động hóa và tối ưu hóa luồng công việc phát triển phần mềm dựa trên nền tảng phương pháp luận **BMAD**.
+
+---
+
+## 🌟 Lợi Ích Đem Lại
+
+Phương pháp luận BMAD (Build-Measure-Analyze-Deploy) nổi tiếng với khả năng duy trì tính chặt chẽ, cấu trúc rõ ràng và luôn hướng tới **spec-driven** (làm việc dựa trên đặc tả kỹ thuật). Tuy nhiên, nhược điểm lớn nhất là quá trình vận hành tốn khá nhiều bước và thao tác thủ công. 
+
+**Squad BMAD giải quyết triệt để vấn đề đó:**
+- **Tự động hóa xuyên suốt:** Giúp quá trình vận hành project với phương pháp BMAD diễn ra trơn tru, liền mạch mà không cần bạn phải can thiệp vào từng bước nhỏ.
+- **Có ngay một trợ lý dự án mẫn cán:** Trợ lý này sẽ giúp bạn trả lời, xử lý các step của BMAD, tự động vận hành và implement toàn bộ Epics, Stories.
+- **Tập trung vào giá trị cốt lõi:** Bạn chỉ cần nói chuyện với Trợ lý (Gemini), đưa ra quyết định ở tầm cao, phần còn lại Trợ lý sẽ tự động giao việc và giám sát các Agent khác (Claude Code).
+
+---
+
+## 📋 Yêu Cầu Hệ Thống (Requirements)
+
+Để vận hành trơn tru hệ thống này, bạn cần chuẩn bị:
+
+- **Tài khoản Claude Code:** Cần thiết để khởi chạy các Agent thực thi (Implement) và tư duy (Brainstorm).
+- **Tài khoản Gemini (Gemini CLI):** Đóng vai trò là "Nhạc trưởng" điều phối toàn bộ luồng công việc.
+- **Môi trường Tmux:** Được cài đặt sẵn trên máy tính (MacOS/Linux) để quản lý đa luồng phiên làm việc.
+- **Kinh nghiệm:** Đã từng sử dụng hoặc có kiến thức nền tảng về phương pháp **BMAD**.
+
+---
+
+## 🧠 Hệ Tư Tưởng Cốt Lõi
+
+Squad BMAD được xây dựng dựa trên các nguyên tắc bất di bất dịch:
+
+1. **Bám sát quy trình BMAD:** Mọi tác vụ từ lên ý tưởng, viết đặc tả, đến code và review đều tuân thủ nghiêm ngặt các workflow của BMAD. Điều này đảm bảo dự án luôn đi đúng hướng và tài liệu kỹ thuật luôn đồng bộ với code thực tế.
+2. **Fresh Chat & Context Isolation (Cách ly Ngữ cảnh):** Trước khi bắt đầu một workflow mới, hệ thống bắt buộc phải dọn dẹp ngữ cảnh (gọi lệnh `/clear`). Việc này giúp AI (Claude) không bị ảo giác (hallucination) do ôm đồm quá nhiều thông tin cũ, giữ cho suy luận luôn sắc bén.
+3. **Phân chia vai trò rõ ràng (Agent Roles):** Áp dụng đúng tinh thần của BMAD, hệ thống chia các Agent thành các "persona" chuyên biệt (PM, Architect, Dev, QA) để tối ưu hóa hiệu suất của từng Model AI.
+
+---
+
+## ⚙️ Kiến Trúc Hệ Thống & Cách Vận Hành
+
+Hệ thống hoạt động dựa trên sự phối hợp nhịp nhàng của **3 phiên làm việc (sessions) Tmux**:
+
+1. **Session 1: Gemini Orchestrator (Nhạc trưởng)**
+   - Là người chủ vận hành 2 tmux còn lại.
+   - Giao tiếp trực tiếp với bạn, hiểu yêu cầu, ánh xạ vào workflow của BMAD.
+   - Theo dõi, nghiệm thu kết quả và ra quyết định chuyển tiếp.
+
+2. **Session 2: Claude Code - Implement (Thực thi)**
+   - Đóng vai trò là một **Developer**.
+   - Chuyên dùng để viết code, sửa lỗi, chạy test.
+   - Sử dụng model **Claude Sonnet** để đảm bảo tốc độ nhanh, code giỏi và tiết kiệm chi phí.
+
+3. **Session 3: Claude Code - Brainstorm (Suy luận)**
+   - Đóng vai trò là **Architect / PM / QA**.
+   - Chuyên dùng để suy luận kiến trúc, giải quyết các bài toán phức tạp, thiết kế hệ thống và review code.
+   - Sử dụng model **Claude Opus** cho các tác vụ cần tư duy logic sâu.
+
+### 🔄 Hệ Thống Event-Driven bằng Hooks
+
+Thay vì để Gemini phải liên tục kiểm tra màn hình xem Claude Code đã làm xong chưa (polling), dự án này sử dụng cơ chế **Hooks Event-driven** thông qua file `.claude/settings.json`.
+
+Mỗi khi Claude Code (ở tmux 2 hoặc 3) hoàn thành công việc hoặc cần dừng lại, hệ thống sẽ tự động kích hoạt một bash script (như `.claude/hooks/wakeup-gemini.sh`). Script này sẽ lập tức gửi tín hiệu ngược lại cho Session Tmux của Gemini, "đánh thức" Gemini dậy để:
+1. Đọc kết quả công việc.
+2. Đánh giá và nghiệm thu mã nguồn.
+3. Báo cáo lại cho bạn hoặc tự động đi tiếp bước tiếp theo theo quy trình BMAD.
+
+---
+
+## 🚀 Tóm Tắt Quy Trình Hoạt Động
+
+1. Bạn mở 3 session Tmux (1 cho Gemini, 2 cho Claude Code).
+2. Bạn chat với Gemini: *"Hãy implement Story #123 cho tôi."*
+3. Gemini nhận lệnh, phân tích theo workflow BMAD và gửi lệnh (kèm `/clear` để reset context) sang cho `Claude Code - Implement` thông qua shell script an toàn.
+4. Gemini rơi vào trạng thái "Idle" (nghỉ ngơi), chờ đợi.
+5. `Claude Code - Implement` hì hục viết code. Khi xong, nó tự động kích hoạt Hook.
+6. Hook chạy bash script, gửi phím `Enter` và dòng thông báo sang màn hình của Gemini.
+7. Gemini "tỉnh giấc", đọc log màn hình của Claude Code, nghiệm thu kết quả và báo cáo lại cho bạn.
+
+---
+
+Với **Squad BMAD**, bạn không còn là một coder cặm cụi gõ từng dòng lệnh, bạn là một **Người quản lý dự án** thực thụ điều hành một đội ngũ AI tinh nhuệ!
+
+---
+
+## 🛠 Cách Cài Đặt & Sử Dụng (How to use)
+
+### 1. Cài Đặt Squad BMAD
+
+Từ thư mục dự án của bạn, chạy:
+
+```bash
+npx squad-bmad install
+```
+
+Lệnh này sẽ:
+- Sao chép các hook script, tiện ích tmux, và Gemini slash command vào dự án của bạn.
+- Tự động cấu hình `.claude/settings.json` với các hooks cần thiết (hoặc in hướng dẫn nếu bạn đã có phần hooks tùy chỉnh).
+- Nhắc bạn cài đặt BMAD Method (`npx bmad-method install`) nếu chưa có.
+
+> **Nâng cấp?** Chạy `npx squad-bmad upgrade` để ghi đè các file hiện có bằng phiên bản mới nhất.
+
+### 2. Chuẩn Bị Môi Trường Tmux
+
+Tất cả 3 sessions đều được tạo tự động theo **quy chuẩn đặt tên dựa trên tên folder dự án**. Chạy script setup từ thư mục dự án:
+
+```bash
+bash .gemini/scripts/setup-sessions.sh
+```
+
+Script sẽ tự động tạo (hoặc bỏ qua nếu đã tồn tại):
+- `gemini-orchestrator-<folder>` — khởi chạy `gemini --yolo --model gemini-3-pro-preview`
+- `claude-implement-<folder>` — khởi chạy `claude --dangerously-skip-permissions --model sonnet`
+- `claude-brainstorm-<folder>` — khởi chạy `claude --dangerously-skip-permissions --model opus`
+
+### 3. Truy cập Gemini Orchestrator
+
+Attach vào session Gemini của dự án:
+```bash
+tmux attach -t gemini-orchestrator-<folder>
+```
+
+### 4. Chạy Slash Command
+
+Trong Gemini, gõ slash command — **không cần truyền argument**. Gemini sẽ tự detect folder và kiểm tra cả 3 sessions:
+
+```text
+/withClaudeCodeTmux
+```
+
+### 5. Bắt Đầu Công Việc
+Giờ đây hệ thống đã sẵn sàng. Bạn chỉ việc giao tiếp với Gemini như một người quản lý dự án:
+- *"Bắt đầu project này giúp tôi bằng luồng generate-project-context."*
+- *"Chúng ta đang ở Epic nào? Hãy tạo story mới cho tính năng đăng nhập."*
+- *"Hãy implement Story #5 theo quy trình dev-story."*
+
+Gemini sẽ tự động phân tích, dọn dẹp ngữ cảnh (gửi lệnh `/clear`), chuyển lệnh đến đúng session Claude phù hợp và sẽ tự động "thức dậy" để nghiệm thu khi nhận được tín hiệu Hook phản hồi từ Claude.

package/bin/cli.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * squad-bmad CLI
+ *
+ * Commands:
+ *   npx squad-bmad install   — Copy squad-bmad files into the current project
+ *   npx squad-bmad upgrade   — Update squad-bmad files to the latest version
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+// ── ANSI colour helpers ──────────────────────────────────────────────────────
+const c = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+    dim: '\x1b[2m',
+};
+const ok = (s) => console.log(`  ${c.green}✓${c.reset}  ${s}`);
+const warn = (s) => console.log(`  ${c.yellow}⚠${c.reset}  ${s}`);
+const info = (s) => console.log(`  ${c.cyan}→${c.reset}  ${s}`);
+const err = (s) => console.log(`  ${c.red}✗${c.reset}  ${s}`);
+const sep = () => console.log(`${c.dim}${'─'.repeat(60)}${c.reset}`);
+
+// ── Paths ────────────────────────────────────────────────────────────────────
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
+const TARGET_DIR = process.cwd();
+
+// ── Hooks that squad-bmad requires in .claude/settings.json ─────────────────
+const REQUIRED_HOOKS = {
+    Stop: [
+        {
+            matcher: '',
+            hooks: [{ type: 'command', command: 'bash .claude/hooks/wakeup-gemini.sh' }],
+        },
+    ],
+    Notification: [
+        {
+            matcher: 'permission_prompt',
+            hooks: [{ type: 'command', command: 'bash .claude/hooks/notify-gemini.sh "$CLAUDE_NOTIFICATION"' }],
+        },
+    ],
+};
+
+// ── Helper: recursively copy a directory, returning list of copied files ─────
+function copyDir(src, dest, { overwrite = false } = {}) {
+    const results = { copied: [], skipped: [] };
+
+    if (!fs.existsSync(src)) return results;
+
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    fs.mkdirSync(dest, { recursive: true });
+
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            const sub = copyDir(srcPath, destPath, { overwrite });
+            results.copied.push(...sub.copied);
+            results.skipped.push(...sub.skipped);
+        } else {
+            const rel = path.relative(TARGET_DIR, destPath);
+            if (!overwrite && fs.existsSync(destPath)) {
+                results.skipped.push(rel);
+            } else {
+                fs.cpSync(srcPath, destPath, { force: true });
+                results.copied.push(rel);
+            }
+        }
+    }
+
+    return results;
+}
+
+// ── Helper: smart-merge squad-bmad hooks into .claude/settings.json ──────────
+function mergeSettings() {
+    const settingsPath = path.join(TARGET_DIR, '.claude', 'settings.json');
+
+    /* Case 1: file doesn't exist — create it */
+    if (!fs.existsSync(settingsPath)) {
+        fs.mkdirSync(path.join(TARGET_DIR, '.claude'), { recursive: true });
+        fs.writeFileSync(settingsPath, JSON.stringify({ hooks: REQUIRED_HOOKS }, null, 2) + '\n');
+        ok('.claude/settings.json created with hooks section.');
+        return;
+    }
+
+    /* Case 2/3: file exists — read and inspect */
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+        err('Could not parse .claude/settings.json — please check it is valid JSON.');
+        return;
+    }
+
+    /* Case 2: no hooks key — safe to merge automatically */
+    if (!settings.hooks) {
+        settings.hooks = REQUIRED_HOOKS;
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        ok('.claude/settings.json — hooks section added automatically.');
+        return;
+    }
+
+    /* Case 3: hooks key already exists — print instructions, don't touch */
+    warn('.claude/settings.json already has a "hooks" section.');
+    console.log(`\n     Please ${c.bold}manually${c.reset} add the following entries:\n`);
+    console.log(`${c.dim}     ─── .claude/settings.json ────────────────────────────${c.reset}`);
+    console.log(JSON.stringify({ hooks: REQUIRED_HOOKS }, null, 2)
+        .split('\n')
+        .map(l => `     ${c.cyan}${l}${c.reset}`)
+        .join('\n'));
+    console.log(`${c.dim}     ────────────────────────────────────────────────────────${c.reset}\n`);
+}
+
+// ── BMAD Knowledge URL ──────────────────────────────────────────────────────
+const BMAD_KNOWLEDGE_URL = 'https://docs.bmad-method.org/llms-full.txt';
+const BMAD_KNOWLEDGE_DEST = path.join('references', 'bmad-knowledge', 'llm.md');
+
+// ── Helper: download BMAD knowledge file ────────────────────────────────────
+function downloadBmadKnowledge() {
+    const destPath = path.join(TARGET_DIR, BMAD_KNOWLEDGE_DEST);
+    const destDir = path.dirname(destPath);
+
+    return new Promise((resolve) => {
+        info(`Downloading latest BMAD knowledge from:\n     ${c.dim}${BMAD_KNOWLEDGE_URL}${c.reset}\n`);
+
+        https.get(BMAD_KNOWLEDGE_URL, (res) => {
+            if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                // Follow one redirect
+                https.get(res.headers.location, (redirectRes) => {
+                    handleResponse(redirectRes, destDir, destPath, resolve);
+                }).on('error', (e) => {
+                    err(`Download failed: ${e.message}`);
+                    warn('You can manually download it later from:');
+                    console.log(`     ${c.cyan}${BMAD_KNOWLEDGE_URL}${c.reset}`);
+                    console.log(`     Save to: ${c.cyan}${BMAD_KNOWLEDGE_DEST}${c.reset}\n`);
+                    resolve(false);
+                });
+                return;
+            }
+            handleResponse(res, destDir, destPath, resolve);
+        }).on('error', (e) => {
+            err(`Download failed: ${e.message}`);
+            warn('You can manually download it later from:');
+            console.log(`     ${c.cyan}${BMAD_KNOWLEDGE_URL}${c.reset}`);
+            console.log(`     Save to: ${c.cyan}${BMAD_KNOWLEDGE_DEST}${c.reset}\n`);
+            resolve(false);
+        });
+    });
+}
+
+function handleResponse(res, destDir, destPath, resolve) {
+    if (res.statusCode !== 200) {
+        err(`Download failed: HTTP ${res.statusCode}`);
+        warn('You can manually download it later from:');
+        console.log(`     ${c.cyan}${BMAD_KNOWLEDGE_URL}${c.reset}`);
+        console.log(`     Save to: ${c.cyan}${BMAD_KNOWLEDGE_DEST}${c.reset}\n`);
+        resolve(false);
+        return;
+    }
+
+    fs.mkdirSync(destDir, { recursive: true });
+    const file = fs.createWriteStream(destPath);
+    res.pipe(file);
+    file.on('finish', () => {
+        file.close();
+        ok(`${BMAD_KNOWLEDGE_DEST}  ${c.dim}(latest)${c.reset}`);
+        resolve(true);
+    });
+    file.on('error', (e) => {
+        err(`Failed to write file: ${e.message}`);
+        resolve(false);
+    });
+}
+
+// ── Helper: check if BMAD is installed ───────────────────────────────────────
+function checkBmad() {
+    const bmadDir = path.join(TARGET_DIR, '_bmad');
+    if (!fs.existsSync(bmadDir)) {
+        console.log();
+        sep();
+        warn(`${c.bold}BMAD Method is not installed${c.reset} in this project.`);
+        info('Squad BMAD requires BMAD to function. Install it with:\n');
+        console.log(`     ${c.bold}${c.cyan}npx bmad-method install${c.reset}\n`);
+        console.log(`     ${c.dim}(Choose "Claude Code" as your AI tool when prompted)${c.reset}`);
+        sep();
+        console.log();
+    }
+}
+
+// ── Command: install ─────────────────────────────────────────────────────────
+async function install() {
+    console.log(`\n${c.bold}  squad-bmad install${c.reset}\n`);
+    sep();
+
+    info('Copying files into your project...\n');
+
+    const { copied, skipped } = copyDir(TEMPLATE_DIR, TARGET_DIR, { overwrite: false });
+
+    copied.forEach(f => ok(f));
+    skipped.forEach(f => warn(`${f}  ${c.dim}(already exists — skipped)${c.reset}`));
+
+    console.log();
+    sep();
+    info('Downloading BMAD knowledge...\n');
+    await downloadBmadKnowledge();
+
+    sep();
+    info('Configuring .claude/settings.json...\n');
+    mergeSettings();
+
+    sep();
+    console.log();
+    checkBmad();
+
+    console.log(`${c.green}${c.bold}  ✓ Installation complete!${c.reset}\n`);
+    info(`Run ${c.bold}.gemini/scripts/setup-sessions.sh${c.reset} to create your tmux sessions.`);
+    info(`Then attach: ${c.bold}tmux attach -t gemini-orchestrator-<folder>${c.reset}`);
+    console.log();
+}
+
+// ── Command: upgrade ─────────────────────────────────────────────────────────
+async function upgrade() {
+    console.log(`\n${c.bold}  squad-bmad upgrade${c.reset}\n`);
+    sep();
+
+    info('Upgrading files (existing files will be overwritten)...\n');
+
+    const { copied, skipped } = copyDir(TEMPLATE_DIR, TARGET_DIR, { overwrite: true });
+
+    copied.forEach(f => ok(`${f}  ${c.dim}(updated)${c.reset}`));
+    skipped.forEach(f => warn(`${f}  ${c.dim}(skipped)${c.reset}`));
+
+    console.log();
+    sep();
+    info('Updating BMAD knowledge...\n');
+    await downloadBmadKnowledge();
+
+    sep();
+    info('Checking .claude/settings.json...\n');
+    mergeSettings();
+
+    sep();
+    console.log();
+    checkBmad();
+
+    console.log(`${c.green}${c.bold}  ✓ Upgrade complete!${c.reset}\n`);
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+const command = process.argv[2];
+
+if (command === 'install') {
+    install().catch(e => { err(e.message); process.exit(1); });
+} else if (command === 'upgrade') {
+    upgrade().catch(e => { err(e.message); process.exit(1); });
+} else {
+    console.log(`
+${c.bold}  squad-bmad${c.reset} — AI orchestration boilerplate for Gemini + Claude Code
+
+  ${c.bold}Usage:${c.reset}
+    npx squad-bmad install   Set up squad-bmad in the current project
+    npx squad-bmad upgrade   Update squad-bmad files to the latest version
+
+  ${c.bold}Docs:${c.reset}  https://github.com/thientranhung/squad-bmad
+`);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "squad-bmad",
+    "version": "1.2.0",
+    "description": "Automated project orchestration boilerplate with Gemini CLI & Claude Code via Tmux, following the BMAD methodology.",
+    "keywords": [
+        "gemini",
+        "claude",
+        "tmux",
+        "bmad",
+        "ai",
+        "orchestration",
+        "boilerplate"
+    ],
+    "homepage": "https://github.com/thientranhung/squad-bmad#readme",
+    "bugs": {
+        "url": "https://github.com/thientranhung/squad-bmad/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/thientranhung/squad-bmad.git"
+    },
+    "license": "MIT",
+    "author": "thientranhung",
+    "bin": {
+        "squad-bmad": "./bin/cli.js"
+    },
+    "files": [
+        "bin/",
+        "template/"
+    ],
+    "engines": {
+        "node": ">=18"
+    }
+}

package/template/.claude/hooks/notify-gemini.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+MSG="$1"
+if [ -z "$MSG" ]; then
+  MSG="Claude Code is waiting for confirmation/interaction."
+fi
+
+# --- Dynamic Gemini session target ---
+# Derive the tmux session name from the current project folder.
+# Convention: gemini-orchestrator-<folder-name>
+FOLDER_NAME=$(basename "$PWD")
+GEMINI_SESSION="gemini-orchestrator-${FOLDER_NAME}"
+
+# Check whether the target tmux session actually exists before sending
+if ! tmux has-session -t "$GEMINI_SESSION" 2>/dev/null; then
+  echo "[notify-gemini] Tmux session '${GEMINI_SESSION}' not found. Skipping notification." >&2
+  exit 0
+fi
+
+# Send notification to the Gemini session
+tmux send-keys -t "${GEMINI_SESSION}:0.0" "Claude Code Notification: $MSG . Please check and continue the work" C-m
+sleep 3
+tmux send-keys -t "${GEMINI_SESSION}:0.0" C-m
+
+exit 0

package/template/.claude/hooks/wakeup-gemini.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+set -e
+
+# Read the full JSON input from Claude Code
+HOOK_INPUT=$(cat)
+
+# Temporarily log to analyze the JSON structure of Agent Teams (helps improve the filter later)
+echo "$HOOK_INPUT" >> /tmp/claude_stop_hook_debug.jsonl
+
+# Extract the Agent name (if present in the Experimental Agent Teams payload)
+AGENT_NAME=$(echo "$HOOK_INPUT" | jq -r '.agent // empty')
+
+# Temporarily log to inspect the actual structure.
+# Once /tmp/claude_stop_hook_debug.jsonl has been analysed, enable the Sub-agent filter logic here.
+# Example: if [ -n "$AGENT_NAME" ] && [ "$AGENT_NAME" != "root" ]; then exit 0; fi
+
+# --- Dynamic Gemini session target ---
+# Derive the tmux session name from the project folder name in the hook's cwd.
+# Convention: gemini-orchestrator-<folder-name>  (e.g. cwd=/…/squad-bmad → gemini-orchestrator-squad-bmad)
+CWD=$(echo "$HOOK_INPUT" | jq -r '.cwd // empty')
+
+if [ -z "$CWD" ]; then
+  echo "[wakeup-gemini] Warning: cwd not found in hook payload. Skipping." >&2
+  exit 0
+fi
+
+FOLDER_NAME=$(basename "$CWD")
+GEMINI_SESSION="gemini-orchestrator-${FOLDER_NAME}"
+
+# Check whether the target tmux session actually exists before sending
+if ! tmux has-session -t "$GEMINI_SESSION" 2>/dev/null; then
+  echo "[wakeup-gemini] Tmux session '${GEMINI_SESSION}' not found. Skipping wake-up signal." >&2
+  exit 0
+fi
+
+# Send a wake-up signal to the Gemini session.
+# We use C-m to ensure Enter is sent safely.
+tmux send-keys -t "${GEMINI_SESSION}:0.0" "Claude Code has emitted a Stop signal (Task completed or Sub-agent completed). Please check and continue the work" C-m
+sleep 5
+tmux send-keys -t "${GEMINI_SESSION}:0.0" C-m
+
+exit 0

package/template/.gemini/commands/withClaudeCodeTmux.toml

@@ -0,0 +1,90 @@
+description = "Set up AI PM & Tech Lead role to manage, evaluate, and monitor Claude Code via Tmux."
+prompt = """
+In this session, you act as the "AI Project Manager & Principal Tech Lead". You DO NOT directly write code or modify files. You COORDINATE, MONITOR QUALITY, and EVALUATE the AI Agent (Claude Code) on my behalf.
+
+---
+
+**INITIALIZATION — Must be completed before taking any tasks:**
+
+> **PRE-FLIGHT (execute IMMEDIATELY, in parallel, before all other steps):**
+> - [ ] **IMMEDIATE**: Read and fully internalize `references/bmad-knowledge/llm.md` — this is the foundational BMAD knowledge. Do not skip or skim.
+> - [ ] **IMMEDIATE**: Read `GEMINI.md` — understand the current project architecture, tech stack, and conventions.
+> - [ ] Only proceed with the steps below after both files have been read.
+
+
+1. **Detect session names from current project folder:**
+   - Run `basename "$PWD"` to get the folder name (e.g. `squad-bmad`).
+   - Derive the 3 session names from this folder name:
+     - **Gemini Orchestrator**: `gemini-orchestrator-<folder>`
+     - **Implement Session** (Sonnet): `claude-implement-<folder>`
+     - **Brainstorm Session** (Opus): `claude-brainstorm-<folder>`
+   - Run `.gemini/scripts/setup-sessions.sh` (no arguments needed — it auto-detects from `$PWD`). This script creates any missing sessions and starts the correct CLI commands inside each one. If a session already exists, it is reused as-is.
+   - After the script completes, verify all 3 sessions exist by running `tmux list-sessions`.
+
+2. **Validate you are in the Gemini Orchestrator session:** Run `tmux display-message -p '#S'` — if the result is NOT `gemini-orchestrator-<folder>`, **STOP IMMEDIATELY** and report an error: *"Error: This command must be run from inside the 'gemini-orchestrator-<folder>' tmux session. Currently in session '[current session name]'."*
+
+3. **Resolve your pane ID (Gemini):** Run `tmux display-message -p '#S:#I.#P'` to get the pane ID. **Save this value** and use it throughout the session for the ping mechanism. Do not ask again.
+
+4. **Check git branch:** Run `git branch`. If currently on `develop` or `main/master`, remind the user to create a branch following the `epic/` or `feature/` standard before implementing.
+
+---
+
+**1. Tmux Operations — Core Rules:**
+
+- **Sending Principle (ALWAYS applies to ALL sends):**
+  - Use the `.gemini/scripts/tmux-send.sh` script to send any content to Claude Code:
+    ```
+    .gemini/scripts/tmux-send.sh "<pane-target>" "content" [wait-seconds]
+    ```
+    - `pane-target`: tmux target to the exact pane, e.g., `cc-implement:0` or `cc-implement:0.0`.
+    - `wait-seconds`: optional, default is **5 seconds** — decrease (e.g., `2`) for quick commands, keep or increase for long prompts.
+  - The script automatically handles the entire protocol: send text → wait → send `C-m`. **Do not manually call `tmux send-keys`.**
+- **Language:** Always use English in every prompt sent to Claude Code.
+- **Interrupt:** Send `tmux send-keys -t "<session>" Escape` to interrupt Claude Code processing (in this case, still use `send-keys` directly because only a key signal is needed, not Enter).
+
+---
+
+**2. Completion Notification (Automatic):**
+
+Claude Code has been configured with a stop hook (`.claude/hooks/wakeup-gemini.sh`) — when Claude Code completes a task, the hook will **automatically send a signal** back to Gemini's pane. You **DO NOT need to**:
+- Continuously poll `capture-pane` to track progress.
+- Insert ping instructions into the prompt sent to Claude Code.
+
+→ After assigning a task, **wait for the hook signal**. Only proactively check (`capture-pane`) if you suspect Claude Code is stuck or unresponsive for too long.
+
+---
+
+**3. Session Routing & Parallel Execution:**
+
+- Based on the nature of the work, independently decide the correct session to assign:
+  - **Reasoning, architecture, review** → Brainstorm Session.
+  - **Coding, implement, fix** → Implement Session.
+- **Parallelization:** Allowed to assign tasks to 2 sessions simultaneously **when tasks are independent** (e.g., Brainstorm reviews Story A while Implement codes Story B). **Do not parallelize** when the output of one session is the input of the other (e.g., Brainstorm finishes the plan → then Implement).
+
+---
+
+**4. BMAD Orchestration (Intelligent Orchestration):**
+
+- **BMAD knowledge is ready:** You have already read `references/bmad-knowledge/llm.md` in the PRE-FLIGHT step. Apply it directly without reading again.
+- **Independently decide command:** Analyze user requests → look up `.claude/commands/` → choose the most appropriate slash command. Do not wait for the user to specify.
+- **Fresh Chat before each Workflow (`/clear`):** BMAD requires *"Always start a fresh chat for each workflow"* and *"each story, repeat this cycle with fresh chats"*. In Claude Code, fresh chat = `/clear` command. **Rule:**
+  - **Mandatory to send `/clear` before starting any new workflow** (e.g., switching from `create-story` to `dev-story`, or starting the next story).
+  - **Do not `/clear` mid-way** while a workflow is running — only clear when starting a completely new workflow.
+  - Use: `.gemini/scripts/tmux-send.sh "<pane-target>" "/clear" 2`
+- **Follow BMAD suggested next steps:** After each task is completed, BMAD will suggest the next step. Gemini **reads and evaluates** that suggestion:
+  - If it fits the current scope → **send `/clear` → automatically continue** to the next workflow.
+  - If it requires a business decision or is out of scope → **report to the user** before proceeding.
+- Absolutely do not create or modify existing workflows.
+
+---
+
+**5. Monitoring & Acceptance (QA Gate):**
+
+- **Acceptance after completion:** When Claude Code reports completion, read the output files, check test results, and evaluate alignment with the project architecture (`GEMINI.md`).
+- **Handle mid-task errors:** If Claude Code reports an error or asks a technical question within the project architecture/context scope, you **answer it yourself** based on your understanding of the documentation. If the question exceeds your authority (changing requirements, business decisions), **forward it to the user**.
+- **Reporting:** Only report progress summaries, acceptance results, or ask for opinions when there are issues exceeding your authority.
+
+---
+
+If understood, execute all initialization steps (validate sessions, resolve pane ID, check branch), then confirm: "Ready. Implement Session: [name], Brainstorm Session: [name], Gemini pane: [ID]."
+"""

package/template/.gemini/commands/withClaudeCodeTmux.vi.toml

@@ -0,0 +1,91 @@
+description = "Set up AI PM & Tech Lead role to manage, evaluate, and monitor Claude Code via Tmux."
+prompt = """
+Trong phiên này, bạn đóng vai "AI Project Manager & Principal Tech Lead". Bạn KHÔNG trực tiếp viết code hay sửa file. Bạn ĐIỀU PHỐI, GIÁM SÁT CHẤT LƯỢNG và ĐÁNH GIÁ Agent AI (Claude Code) thay mặt tôi.
+
+---
+
+**KHỞI TẠO — Bắt buộc hoàn thành trước khi nhận task:**
+
+> **PRE-FLIGHT (thực hiện NGAY LẬP TỨC, song song, trước tất cả các bước khác):**
+> - [ ] **NGAY LẬP TỨC**: Đọc và nắm toàn bộ `references/bmad-knowledge/llm.md` — đây là nền tảng kiến thức BMAD. Không bỏ qua hay đọc lướt.
+> - [ ] **NGAY LẬP TỨC**: Đọc `GEMINI.md` — hiểu kiến trúc dự án, tech stack, và các quy ước hiện tại.
+> - [ ] Chỉ tiến hành các bước bên dưới sau khi cả hai file đã được đọc xong.
+
+
+1. **Xác định tên session từ folder dự án hiện tại:**
+   - Chạy `basename "$PWD"` để lấy tên folder (ví dụ: `squad-bmad`).
+   - Từ tên folder đó, suy ra 3 tên session theo quy chuẩn:
+     - **Gemini Orchestrator**: `gemini-orchestrator-<folder>`
+     - **Session Implement** (Sonnet): `claude-implement-<folder>`
+     - **Session Brainstorm** (Opus): `claude-brainstorm-<folder>`
+   - Chạy `.gemini/scripts/setup-sessions.sh` (không cần truyền argument — script tự detect từ `$PWD`). Script sẽ tạo các session còn thiếu và khởi chạy đúng lệnh CLI bên trong. Nếu session đã tồn tại, script giữ nguyên.
+   - Sau khi script chạy xong, xác minh cả 3 session tồn tại bằng `tmux list-sessions`.
+
+2. **Validate session hiện tại:** Chạy `tmux display-message -p '#S'` — nếu kết quả KHÔNG phải `gemini-orchestrator-<folder>`, **DỪNG NGAY** và báo lỗi: *"Lỗi: Command này phải được chạy từ bên trong tmux session 'gemini-orchestrator-<folder>'. Hiện đang ở session '[tên session hiện tại]'."*
+
+3. **Resolve pane ID của bạn (Gemini):** Chạy `tmux display-message -p '#S:#I.#P'` để lấy pane ID. **Lưu giá trị này** và dùng xuyên suốt phiên cho ping mechanism. Không hỏi lại.
+
+4. **Kiểm tra git branch:** Chạy `git branch`. Nếu đang ở `develop` hoặc `main/master`, nhắc người dùng tạo branch theo chuẩn `epic/` hoặc `feature/` trước khi implement.
+
+---
+
+**1. Thao tác Tmux — Quy tắc Cốt lõi:**
+
+- **Nguyên tắc Gửi (LUÔN áp dụng cho MỌI lần gửi):**
+  - Dùng script `.gemini/scripts/tmux-send.sh` để gửi mọi nội dung đến Claude Code:
+    ```
+    .gemini/scripts/tmux-send.sh "<pane-target>" "nội dung" [wait-seconds]
+    ```
+    - `pane-target`: tmux target đến đúng pane, ví dụ `cc-implement:0` hoặc `cc-implement:0.0`.
+    - `wait-seconds`: tùy chọn, mặc định **5 giây** — giảm xuống (ví dụ `2`) cho lệnh nhanh, giữ hoặc tăng cho prompt dài.
+  - Script tự động xử lý toàn bộ protocol: gửi text → chờ → gửi `C-m`. **Không tự gọi `tmux send-keys` thủ công.**
+- **Ngôn ngữ:** Luôn dùng tiếng Anh trong mọi prompt gửi đến Claude Code.
+- **Interrupt:** Gửi `tmux send-keys -t "<session>" Escape` để ngắt Claude Code đang xử lý (trường hợp này vẫn dùng `send-keys` trực tiếp vì chỉ cần key signal, không cần Enter).
+
+---
+
+**2. Thông báo hoàn thành (Tự động):**
+
+Claude Code đã được cấu hình stop hook (`.claude/hooks/wakeup-gemini.sh`) — khi Claude Code hoàn thành task, hook sẽ **tự động gửi tín hiệu** về pane của Gemini. Bạn **KHÔNG cần**:
+- Poll `capture-pane` liên tục để theo dõi tiến độ.
+- Chèn ping instruction vào prompt gửi cho Claude Code.
+
+→ Sau khi giao task, **chờ tín hiệu hook**. Chỉ chủ động kiểm tra (`capture-pane`) khi nghi ngờ Claude Code bị stuck hoặc quá lâu không phản hồi.
+
+---
+
+**3. Phân luồng Session & Thực thi Song song:**
+
+- Dựa vào tính chất công việc, tự quyết định giao đúng session:
+  - **Suy luận, kiến trúc, review** → Session Brainstorm.
+  - **Coding, implement, fix** → Session Implement.
+- **Song song hóa:** Được phép giao task cho 2 session đồng thời **khi task độc lập** (ví dụ: Brainstorm review Story A trong khi Implement code Story B). **Không song song** khi output của session này là input của session kia (ví dụ: Brainstorm xong plan → mới Implement).
+
+---
+
+**4. Điều phối theo BMAD (Intelligent Orchestration):**
+
+- **Kiến thức BMAD đã sẵn sàng:** Bạn đã đọc `references/bmad-knowledge/llm.md` ở bước PRE-FLIGHT. Áp dụng trực tiếp mà không cần đọc lại.
+- **Tự quyết định command:** Phân tích yêu cầu người dùng → tra cứu `.claude/commands/` → chọn slash command phù hợp nhất. Không chờ người dùng chỉ định.
+- **Fresh Chat trước mỗi Workflow (`/clear`):** BMAD yêu cầu *"Always start a fresh chat for each workflow"* và *"each story, repeat this cycle with fresh chats"*. Trong Claude Code, fresh chat = lệnh `/clear`. **Quy tắc:**
+  - **Bắt buộc gửi `/clear` trước khi bắt đầu bất kỳ workflow mới nào** (ví dụ: chuyển từ `create-story` sang `dev-story`, hoặc bắt đầu story tiếp theo).
+  - **Không `/clear` giữa chừng** khi workflow đang chạy — chỉ clear khi bắt đầu workflow mới hoàn toàn.
+  - Sử dụng: `.gemini/scripts/tmux-send.sh "<pane-target>" "/clear" 2`
+- **Follow BMAD suggested next steps:** Sau mỗi task hoàn thành, BMAD sẽ suggest bước tiếp theo. Gemini **đọc và đánh giá** suggestion đó:
+  - Nếu phù hợp với scope hiện tại → **gửi `/clear` → tự động tiếp tục** workflow tiếp theo.
+  - Nếu cần quyết định business hoặc ngoài scope → **báo người dùng** trước khi tiến hành.
+- Tuyệt đối không tự tạo hay chỉnh sửa workflow có sẵn.
+
+---
+
+**5. Giám sát & Nghiệm thu (QA Gate):**
+
+- **Nghiệm thu sau hoàn thành:** Khi Claude Code báo xong, đọc file output, kiểm tra test results, và đánh giá alignment với kiến trúc dự án (`GEMINI.md`).
+- **Xử lý lỗi mid-task:** Nếu Claude Code báo lỗi hoặc hỏi câu hỏi kỹ thuật trong phạm vi kiến trúc/context dự án, bạn **tự trả lời** dựa trên hiểu biết từ tài liệu. Nếu câu hỏi vượt thẩm quyền (thay đổi yêu cầu, quyết định business), **forward cho người dùng**.
+- **Cầu nối ngôn ngữ:** Claude Code làm việc bằng tiếng Anh. Khi báo cáo lại cho người dùng, Gemini **luôn giải thích bằng tiếng Việt** — tóm tắt kết quả, vấn đề, và đề xuất tiếp theo.
+- **Báo cáo:** Chỉ báo cáo tóm tắt tiến độ, kết quả nghiệm thu, hoặc xin ý kiến khi có vấn đề vượt thẩm quyền.
+
+---
+
+Nếu đã hiểu, hãy thực hiện toàn bộ bước khởi tạo (chạy setup-sessions.sh, validate session, resolve pane ID, check branch), sau đó xác nhận: "Sẵn sàng. Session Implement: [tên], Session Brainstorm: [tên], Gemini pane: [ID]."
+"""

package/template/.gemini/scripts/setup-sessions.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# setup-sessions.sh — Create (or reuse) the 3 standard tmux sessions for a project.
+#
+# CONVENTION:
+#   gemini-orchestrator-<folder>   → Gemini CLI  (yolo, gemini-3-pro-preview)
+#   claude-implement-<folder>      → Claude Code (sonnet, bypass-permissions)
+#   claude-brainstorm-<folder>     → Claude Code (opus,   bypass-permissions)
+#
+# USAGE:
+#   .gemini/scripts/setup-sessions.sh [folder-name]
+#
+#   If folder-name is omitted, the name of the current working directory is used.
+#
+# EXAMPLES:
+#   .gemini/scripts/setup-sessions.sh
+#   .gemini/scripts/setup-sessions.sh squad-bmad
+
+set -e
+
+# ── Resolve folder name ──────────────────────────────────────────────────────
+if [ -n "$1" ]; then
+  FOLDER="$1"
+else
+  FOLDER=$(basename "$PWD")
+fi
+
+# ── Derive session names ─────────────────────────────────────────────────────
+SESSION_GEMINI="gemini-orchestrator-${FOLDER}"
+SESSION_IMPLEMENT="claude-implement-${FOLDER}"
+SESSION_BRAINSTORM="claude-brainstorm-${FOLDER}"
+
+# ── Helper: create session only if it does not already exist ─────────────────
+create_session_if_missing() {
+  local session_name="$1"
+  local start_cmd="$2"     # command to run inside the new session
+  local label="$3"
+
+  if tmux has-session -t "$session_name" 2>/dev/null; then
+    echo "  [SKIP]   $label → session '${session_name}' already exists."
+  else
+    # -d  : start detached
+    # -s  : session name
+    # The shell command is passed via tmux's 'new-session' so it runs immediately
+    tmux new-session -d -s "$session_name" -x 220 -y 50
+    # Give the shell a moment to initialise before sending the startup command
+    sleep 0.5
+    tmux send-keys -t "${session_name}:0.0" "$start_cmd" C-m
+    echo "  [CREATE] $label → session '${session_name}' created and command sent."
+  fi
+}
+
+# ── Print plan ────────────────────────────────────────────────────────────────
+echo ""
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║         squad-bmad  •  Session Setup                        ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+echo "  Project folder : ${FOLDER}"
+echo ""
+echo "  Sessions to create:"
+echo "    1. ${SESSION_GEMINI}"
+echo "    2. ${SESSION_IMPLEMENT}"
+echo "    3. ${SESSION_BRAINSTORM}"
+echo ""
+
+# ── 1. Gemini Orchestrator ───────────────────────────────────────────────────
+create_session_if_missing \
+  "$SESSION_GEMINI" \
+  "gemini --yolo --model gemini-3-pro-preview" \
+  "Gemini Orchestrator"
+
+# ── 2. Claude Implement (Sonnet) ─────────────────────────────────────────────
+create_session_if_missing \
+  "$SESSION_IMPLEMENT" \
+  "claude --dangerously-skip-permissions --model sonnet" \
+  "Claude Implement (Sonnet)"
+
+# ── 3. Claude Brainstorm (Opus) ──────────────────────────────────────────────
+create_session_if_missing \
+  "$SESSION_BRAINSTORM" \
+  "claude --dangerously-skip-permissions --model opus" \
+  "Claude Brainstorm (Opus)"
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "Done. Active tmux sessions:"
+tmux list-sessions 2>/dev/null | sed 's/^/  /'
+echo ""
+echo "To attach:"
+echo "  tmux attach -t ${SESSION_GEMINI}"
+echo "  tmux attach -t ${SESSION_IMPLEMENT}"
+echo "  tmux attach -t ${SESSION_BRAINSTORM}"
+echo ""

package/template/.gemini/scripts/tmux-send.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# tmux-send.sh — Reliably send text to a tmux pane.
+#
+# USAGE:
+#   ./tmux-send.sh <pane-target> <message> [wait-seconds]
+#
+# ARGUMENTS:
+#   pane-target   — tmux target, e.g.: gemini-orchestrator:0.0
+#   message       — content to send (wrap in quotes if it contains spaces)
+#   wait-seconds  — (optional) seconds to wait between text and Enter, default: 5
+#
+# EXAMPLES:
+#   .gemini/scripts/tmux-send.sh "gemini-orchestrator:0.0" "Hello from Claude Code"
+#   .gemini/scripts/tmux-send.sh "cc-implement:0" "/dev-story" 3
+
+set -e
+
+PANE_TARGET="$1"
+MESSAGE="$2"
+WAIT_SECONDS="${3:-5}"
+
+# Validate required arguments
+if [ -z "$PANE_TARGET" ] || [ -z "$MESSAGE" ]; then
+  echo "Error: Missing arguments." >&2
+  echo "Usage: $0 <pane-target> <message> [wait-seconds]" >&2
+  exit 1
+fi
+
+# Check that the pane exists
+if ! tmux has-session -t "$PANE_TARGET" 2>/dev/null; then
+  echo "Error: Tmux target '$PANE_TARGET' does not exist." >&2
+  exit 1
+fi
+
+# Send the content
+tmux send-keys -t "$PANE_TARGET" "$MESSAGE"
+
+# Wait for the pane to receive and render the text
+sleep "$WAIT_SECONDS"
+
+# Send Enter (C-m) — do NOT use 'Enter' or '\n'
+tmux send-keys -t "$PANE_TARGET" C-m
+
+echo "✓ Sent to '$PANE_TARGET': $MESSAGE"