opencode-gemiterm-skills 0.5.0

package/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md - opencode-gemiterm-skills
+
+<critical_rules priority="highest">
+1. The bundled `debate-with-gemini` skill depends on the `gemiterm` Python CLI being installed and authenticated on the host.
+2. This package ships a real installer (`src/installer.ts`) that copies skill assets to the consumer's `.opencode/skills/` and registers them in `opencode.json`. The `src/cli.ts` is the CLI entry point (install/uninstall/status subcommands), resolved by `package.json#bin`. Only add code under `src/` that supports the install/uninstall/status commands.
+3. Skill frontmatter is the source of truth. Do not edit `assets/skills/*/SKILL.md` frontmatter in ways that break the `name` / `description` contract.
+4. The `metadata.requires: gemiterm` link on `debate-with-gemini` must remain so consumers know to install the Python CLI first.
+</critical_rules>
+
+<context_hierarchy>
+<system>OpenCode plugin loader</system>
+<domain>OpenCode skill packaging</domain>
+<task>Bundle markdown skills into a publishable plugin package</task>
+<execution>npm distribution (opencode-gemiterm-skills) with file:// reference as a development fallback</execution>
+</context_hierarchy>
+
+<role>
+<identity>opencode-gemiterm-skills package maintainer</identity>
+<scope>This repository only</scope>
+<constraints>Markdown-only bundle, no build step, no runtime dependencies</constraints>
+</role>
+
+<bundled_skills>
+<skill name="gemiterm" path="assets/skills/gemiterm/SKILL.md" requires="Python CLI gemiterm" />
+<skill name="debate-with-gemini" path="assets/skills/debate-with-gemini/SKILL.md" requires="gemiterm skill + Python CLI gemiterm" />
+</bundled_skills>
+
+<self_config>
+<location>.opencode/opencode.json</location>
+<purpose>Register assets/skills/ as a skill path and pre-allow both skills</purpose>
+<pointer_in_package_json>opencode.plugin → .opencode/opencode.json</pointer_in_package_json>
+</self_config>
+
+<consumer_install>
+<npm>
+<command>npm install opencode-gemiterm-skills</command>
+<opencode_json_snippet>
+{
+  "plugins": [
+    "opencode-gemiterm-skills"
+  ]
+}
+</opencode_json_snippet>
+</npm>
+<file_fallback>
+<opencode_json_snippet>
+{
+  "plugins": [
+    "file:///ABSOLUTE/PATH/TO/opencode-gemiterm-skills"
+  ]
+}
+</opencode_json_snippet>
+<use_case>Local development against a checkout of this repo</use_case>
+</file_fallback>
+<prerequisites>
+  - pip install gemiterm
+  - gemiterm install-browser
+  - gemiterm auth
+</prerequisites>
+</consumer_install>
+
+<testing>
+<runner>bun test</runner>
+<file>tests/skills.test.ts</file>
+<coverage>Frontmatter validation, skill-path self-config, package.json pointer, cross-skill dependency link</coverage>
+</testing>

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to `opencode-gemiterm-skills` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-06-07
+
+_Initial public release._
+
+### Added
+- npm distribution support: `bin` field exposes `opencode-gemiterm-skills` CLI via `bunx` / `npx` (`install`, `uninstall`, `status` subcommands)
+- `engines: { "bun": ">=1.0.0" }` and `sideEffects: false` metadata in `package.json`
+- `homepage` and `author` fields in `package.json`
+- `prepublishOnly` script that runs `tsc --noEmit` and `bun test` before publish
+- Bun shebang (`#!/usr/bin/env bun`) on `index.ts` so the CLI stub is executable
+- README: **Example use cases** section demonstrating both `gemiterm` and `debate-with-gemini` skills with sample prompts and agent responses
+- README: introduction blurb linking to the [`gemiterm` CLI repository](https://github.com/Expert-Vision-Software/gemiterm)
+- README: `gemiterm` CLI link in the Requirements table
+
+### Changed
+- `package.json` `files` array whitelists `.opencode/opencode.json` instead of the entire `.opencode/` directory, preventing dev-only artifacts from shipping
+- `.opencode/opencode.json` (self-config) stripped of dev-only entries (extra skills path, plugin array, empty MCP block)
+- Module/CLI refactor: `index.ts` is a one-line re-export of `plugin.ts`; CLI entry moved to `src/cli.ts` with dynamic version read from `package.json`; `package.json#bin` points at `./src/cli.ts`; `package.json#files` includes `"src"`; `tsconfig.json#include` includes `"src/**/*.ts"`
+- `package.json` version bumped to `0.5.0`
+
+## [0.1.0] - 2026-06-06
+
+### Added
+- Initial bundle of the `gemiterm` skill (SKILL.md + REFERENCE.md)
+- Initial bundle of the `debate-with-gemini` skill (SKILL.md + REFERENCE.md)
+- Self-config at `.opencode/opencode.json` registering `assets/skills/` as a skill path
+- Pre-configured `permission.skill` entries for both bundled skills
+- `opencode.plugin` pointer in `package.json` to `.opencode/opencode.json`
+- Minimal `plugin.ts` and `index.ts` stubs (markdown-only, no TypeScript logic)
+- Smoke test suite at `tests/skills.test.ts` validating frontmatter and self-config

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-gemiterm-skills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# opencode-gemiterm-skills
+
+[![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-blue?link=https://opencode.ai)](https://opencode.ai)
+[![npm version](https://img.shields.io/npm/v/opencode-gemiterm-skills?label=npm)](https://www.npmjs.com/package/opencode-gemiterm-skills)
+[![MIT License](https://img.shields.io/badge/License-MIT-green?link=LICENSE)](LICENSE)
+
+Local OpenCode plugin package that bundles the `gemiterm` and `debate-with-gemini` skills for OpenCode agents. Install once and the skills are available to every OpenCode session on the machine.
+
+[`gemiterm`](https://github.com/Expert-Vision-Software/gemiterm) is a CLI for interacting with Google Gemini from the terminal — listing, fetching, exporting, and managing Gemini chat history. This plugin wraps it into OpenCode skills so agents can use Gemini conversational data directly in workflows.
+
+## Bundled skills
+
+| Skill | Purpose |
+|-------|---------|
+| `gemiterm` | Google Gemini Terminal CLI wrapper for listing, fetching, exporting, and managing Gemini chat history. |
+| `debate-with-gemini` | Conducts structured multi-turn technical debates with Gemini AI via the `gemiterm` CLI, delegating the back-and-forth to a subagent. |
+
+Both skills are loaded on demand via the native `skill` tool. The metadata of each skill (name + description) is pre-loaded at session start; the full `SKILL.md` body is loaded only when the agent decides the skill is relevant.
+
+## Quick start
+
+```bash
+# Install skills and register them with OpenCode
+bunx opencode-gemiterm-skills install
+
+# Or globally (for all projects on this machine)
+bunx opencode-gemiterm-skills install --scope global
+```
+
+That's it. After install, both `gemiterm` and `debate-with-gemini` appear in the `skill` tool's `<available_skills>` list. No restart needed — OpenCode loads skills on demand.
+
+For global install, skills are placed in `~/.config/opencode/skills/`. For local install (default), they are placed in `{project}/.opencode/skills/`.
+
+## Example use cases
+
+### List and search Gemini chats (`gemiterm` skill)
+
+> **You:** "Find my Gemini chats about React Server Components and export them."
+
+Agent loads the `gemiterm` skill, then:
+
+```bash
+gemiterm list --all-profiles --format json
+# → filters chats by title/keyword "React Server Components"
+gemiterm export <chat_id> --output ./exports/rsc-chat.md
+```
+
+**Agent:** "Found 3 matching chats. Exported all to `./exports/` — here's a summary of each…"
+
+---
+
+### Bulk export for analysis (`gemiterm` skill)
+
+> **You:** "Export all my recent Gemini chats so I can grep through them."
+
+Agent loads the `gemiterm` skill, then:
+
+```bash
+gemiterm list --limit 20 --sort recent --format json
+gemiterm export-all --output ./gemini-exports --format md --parallel 4
+```
+
+**Agent:** "Exported 18 chats to `./gemini-exports/` in Markdown. You can search them with `grep -r "topic" ./gemini-exports/`."
+
+---
+
+### Structured debate with Gemini (`debate-with-gemini` skill)
+
+> **You:** "Debate Gemini for/against using SQLite as the primary database for a SaaS app. Context: docs/arch.md. 5 turns."
+
+Agent loads both skills, verifies auth, reads context, seeds a new Gemini chat with the opposing stance, and spawns a subagent that runs 5 rounds of back-and-forth autonomously.
+
+**Agent:** "Debate complete (5 turns). Gemini argued **for** SQLite (simplicity, zero-config, adequate for early-stage). I argued **against** (concurrency limits, no network access, scaling ceiling). Key agreements: fine for prototyping, migrate to Postgres before 100+ concurrent users. Full transcript saved via `gemiterm export`."
+
+---
+
+### Continue a previous debate (`debate-with-gemini` skill)
+
+> **You:** "Continue that SQLite debate for 3 more turns. Here's the chat_id: c_abc123."
+
+Agent loads the `debate-with-gemini` skill, fetches the existing chat to resume context, and picks up where the last round left off.
+
+**Agent:** "Resumed debate on chat `c_abc123`. Ran 3 additional turns. Gemini conceded on the replication point but raised WAL-mode mitigations. Updated debate report ready."
+
+## Requirements
+
+| | Component | Notes |
+| --- | --- | --- |
+| **Runtime** | [`gemiterm`](https://github.com/Expert-Vision-Software/gemiterm) CLI | Must be installed and authenticated. Both bundled skills depend on it. |
+| **Optional** | Bun `>=1.0.0` | Required only for the CLI installer (`bunx opencode-gemiterm-skills install`) and the test suite (`bun test`). |
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Skill not in `<available_skills>` list | Not installed yet | Run `bunx opencode-gemiterm-skills install` (or `--scope global`) |
+| Skill not in `<available_skills>` list after install | `gemiterm` auth expired or incomplete | Run `gemiterm status` and re-authenticate if needed |
+| `bunx opencode-gemiterm-skills` not found | Bun `<1.0.0` or package not in PATH | Ensure Bun `>=1.0.0` is installed; try `npx opencode-gemiterm-skills` as fallback |
+
+## Install (file:// reference)
+
+For local development against a checkout of this repo, reference the package directory directly from the consumer's `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    "file:///absolute/path/to/opencode-gemiterm-skills"
+  ]
+}
+```
+
+This skips the npm install. OpenCode will auto-install skills from the local checkout on first load.
+
+## File layout
+
+```
+opencode-gemiterm-skills/
+├── .opencode/
+│   └── opencode.json              # self-config: skills.paths + permission.skill
+├── assets/
+│   └── skills/
+│       ├── gemiterm/
+│       │   ├── SKILL.md
+│       │   └── REFERENCE.md
+│       └── debate-with-gemini/
+│           ├── SKILL.md
+│           └── REFERENCE.md
+├── src/
+│   ├── cli.ts                     # CLI entry: install / uninstall / status
+│   ├── commands/
+│   │   ├── install.ts
+│   │   ├── uninstall.ts
+│   │   └── status.ts
+│   └── installer.ts               # core install logic
+├── tests/
+│   └── skills.test.ts             # smoke test
+├── .gitignore
+├── AGENTS.md
+├── CHANGELOG.md
+├── LICENSE
+├── README.md
+├── index.ts                       # module entry: re-exports plugin.ts
+├── package.json
+├── plugin.ts                      # plugin entry with config hook (auto-install on load)
+└── tsconfig.json
+```
+
+## How it works
+
+### Install command
+
+`bunx opencode-gemiterm-skills install` copies skill files to the target `skills/` directory and registers the package in `opencode.json`:
+
+- **Local** (default): copies to `{project}/.opencode/skills/{gemiterm,debate-with-gemini}/` and updates `{project}/.opencode/opencode.json`
+- **Global**: copies to `~/.config/opencode/skills/{gemiterm,debate-with-gemini}/` and updates `~/.config/opencode/opencode.json`
+
+It also pre-grants `permission.skill: "allow"` for both skills and writes a `.version` marker to skip re-install on subsequent loads.
+
+### Plugin auto-install
+
+When OpenCode loads the package via `opencode.json` plugins array, `plugin.ts` runs the same (local) install logic with a version-marker check — so the package auto-installs skills on first use if not already installed.
+
+### CLI commands
+
+| Command | Description |
+| --- | --- |
+| `bunx opencode-gemiterm-skills install` | Install skills locally (or `--scope global`) |
+| `bunx opencode-gemiterm-skills uninstall` | Remove installed skills |
+| `bunx opencode-gemiterm-skills status` | Check install status and version |
+
+`index.ts` is the module entry, a one-line re-export of `plugin.ts`.
+
+## Development
+
+Run the test suite:
+
+```bash
+bun test
+```
+
+The smoke test verifies:
+
+- Both `assets/skills/*/SKILL.md` files exist and parse as valid YAML frontmatter.
+- `name` matches the directory name.
+- `description` is non-empty and within the 1024-character limit.
+- The `metadata.requires: gemiterm` link on `debate-with-gemini` is preserved.
+- The `metadata.tool: gemiterm` link on `gemiterm` is preserved.
+- `.opencode/opencode.json` exists and registers at least one skill path.
+- `package.json` points `opencode.plugin` at `.opencode/opencode.json`.
+
+## Notes for consumers
+
+- The `metadata.requires: gemiterm` field is preserved verbatim on `debate-with-gemini`. OpenCode does not enforce skill-to-skill dependencies — the agent must check `metadata.requires` and the prerequisites above before invoking `debate-with-gemini`.
+- The `metadata.tool`, `metadata.requires`, and `metadata.workflow` fields are stored under the `metadata` map (which OpenCode recognises). Sub-keys beyond `metadata` itself are not formally specified in the OpenCode skill schema, so they may be ignored by some agents — this package treats them as documentation only.
+- The CLI is exposed as `opencode-gemiterm-skills` via the `bin` field, implemented in `src/cli.ts`. Run it with `bunx opencode-gemiterm-skills` or `npx opencode-gemiterm-skills`.
+
+## Acknowledgments
+
+- [OpenCode](https://opencode.ai) — plugin architecture and skill loader
+- [Bun](https://bun.sh) — fast JS runtime used as the package's CLI host
+- [DeepWiki](https://deepwiki.com) — research and context tool for codebase exploration
+
+## Publishing
+
+This package is published to npm as `opencode-gemiterm-skills`. To cut a new release:
+
+```bash
+npm version patch   # or minor / major
+npm publish --access public
+```
+
+The `prepublishOnly` script runs `tsc --noEmit` and `bun test` before publishing.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/assets/skills/debate-with-gemini/REFERENCE.md

@@ -0,0 +1,119 @@
+# Debate with Gemini — Reference
+
+Subagent prompt template, tactical patterns, and report format for the `debate-with-gemini` skill.
+
+---
+
+## Subagent Prompt Template
+
+Copy this template when spawning the `<SUBAGENT_TYPE>` subagent. Fill all `{{...}}` slots.
+
+> Replace `<SUBAGENT_TYPE>` with the subagent type defined in your `opencode.json` (default: `general`).
+
+```
+You are arguing {{AGENT_STANCE}} the following topic: "{{TOPIC}}"
+
+## Conversation
+- Gemini chat_id: "{{GEMINI_CHAT_ID}}"
+- Your stance: "{{AGENT_STANCE}}"
+- Gemini's stance: "{{GEMINI_STANCE}}"
+- Turn limit: {{TURN_LIMIT}}
+
+## Context
+{{BG_CONTEXT_SUMMARY}}
+
+## Your Opening Argument
+{{OPENING_ARGUMENT}}
+
+## Execution Loop
+For each turn:
+1. Send your message:
+   gemiterm continue "{{GEMINI_CHAT_ID}}" "your message here"
+
+   Wait for Gemini's response written to the console.
+2. Analyze the response — concessions? New arguments? Weaknesses?
+3. Craft next response using Tactical Patterns below
+4. Repeat until turn limit or stop condition
+
+Prefer `gemiterm continue` because it returns Gemini's last response inline and avoids an extra round-trip.
+
+Use `gemiterm fetch "{{GEMINI_CHAT_ID}}" --format json` ONLY if console output has parsing issues or times out.
+
+## Stopping Criteria
+- {{TURN_LIMIT}} turns completed
+- Gemini explicitly concedes the core question
+- Gemini repeats the same argument twice (declare convergence, summarize)
+- New factual information emerges that changes the calculus (return to user with the info)
+
+## Tactical Patterns
+
+| Pattern | When to Use | How It Works |
+|---------|-------------|-------------|
+| **Concede-and-Counter** | Opponent has a valid minor point | Concede the minor point explicitly (builds credibility), then counter-attack on the main argument with stronger evidence |
+| **Force Concrete Example** | Opponent argues hypothetically | Demand production evidence: "Do you have a concrete example where X caused Y?" If they can't produce one, their argument is hypothetical |
+| **Decision Matrix** | Debate going in circles | Force a comparison table on specific dimensions: "Let's lock the comparison on [criteria]" |
+| **Reframe the Question** | Opponent frames debate on their terms | Change the frame: "The real question isn't X, it's Y" — shift to ground where your evidence is strongest |
+| **Line-in-the-Sand** | Need a quantifiable claim to test | Pick a number/claim and dare the opponent to break it: "X costs Y lines of code. Prove otherwise" |
+
+## Rules
+- Stay technical and concrete — no marketing language
+- If Gemini makes a valid point, concede it explicitly, then counter on the main argument
+- Token budget: 300-500 words per turn, no essays
+- Do not re-argue points already conceded by either side
+- Do not be sycophantic
+- Run autonomously — do NOT ask the user questions mid-debate
+
+## Return Format
+After completing the debate (or hitting a stop condition), return the Debate Report as your final message (format below).
+```
+
+---
+
+## Debate Report Format
+
+The subagent MUST return this structured report:
+
+```markdown
+## Debate Report — {{TOPIC}}
+
+### 1. Turns Completed
+<number> of <limit> turns. <early stop reason if applicable>
+
+### 2. Final Opponent Position
+<What the opponent conceded / held firm on>
+
+### 3. Verbatim Transcript (Last 2 Turns)
+<Your last message> → <Opponent's last reply>
+
+### 4. Tactical Assessment
+**Won on:** <points where opponent conceded>
+**Conceded:** <points where you accepted opponent's argument>
+**Lost ground:** <points where opponent strengthened their position>
+**Key turning point:** <which move shifted the debate>
+
+### 5. Recommendation
+<One paragraph: what should the human do next?>
+
+### 6. New Evidence
+<Any new factual information the opponent introduced>
+```
+
+---
+
+## Permissions
+
+If the opencode config lacks bash permissions for `gemiterm`, add:
+
+```json
+{
+  "permission": {
+    "bash": {
+      "gemiterm *": "allow"
+    }
+  }
+}
+```
+
+This allows the subagent to run `gemiterm new`, `gemiterm continue`, `gemiterm fetch`, and `gemiterm list` without prompting.
+
+Drop this into the top-level `permission` object in `opencode.json`. For per-agent override, nest it under `agent.<name>.permission`.

package/assets/skills/debate-with-gemini/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: debate-with-gemini
+description: Conduct structured multi-turn technical debates with Gemini AI via gemiterm CLI. Delegates a subagent to argue a position (for/against) autonomously for up to N turns. Use when user says "debate gemini", "argue with gemini", "have gemini defend/attack X", "continue debate", or wants a technical position stress-tested against Gemini. Triggers on: debate, argue, gemini, position, for/against, stress-test, counter-argument. Requires gemiterm CLI installed and authenticated.
+license: MIT
+compatibility: opencode
+metadata:
+  requires: gemiterm
+  workflow: debate
+---
+
+# Debate with Gemini
+
+## Quick Start
+
+```
+User: "Debate gemini on for/against using X. Context: docs/arch.md. 5 turns."
+
+1. skill("gemiterm")                              — load CLI commands
+2. gemiterm status                                — verify auth
+3. Read docs/arch.md, build seeding prompt
+4. gemiterm new "You argue AGAINST X. [context]"  — seed Gemini, capture chat_id
+5. Build opening argument for the FOR position
+6. Spawn subagent with template from REFERENCE.md
+7. Subagent runs N turns, returns Debate Report
+```
+
+## Prerequisites
+
+```bash
+gemiterm status
+```
+
+If not connected: `pipx install gemiterm && gemiterm install-browser && gemiterm auth`
+
+## Inputs
+
+If any required input is missing, ask the user via the standard opencode chat interface before continuing.
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `{{TOPIC}}` | Yes | Two-sided topic (e.g., "for/against using Mastra as foundation SDK") |
+| `{{BG_CONTEXT}}` | Yes | File paths, URLs, or text for debate context |
+| `{{GEMINI_CHAT_ID}}` | No | Existing chat_id. If absent, create a new chat. |
+| `{{AGENT_STANCE}}` | No | "for" or "against". Randomly assigned if omitted. |
+| `{{GEMINI_STANCE}}` | No | Opposite of `{{AGENT_STANCE}}` if omitted. Inferred from transcript if chat_id provided. |
+| `{{TURN_LIMIT}}` | No | Max rounds. Default: 10. |
+
+## Phase 1: Setup
+
+### Flow A — New Chat (no chat_id)
+
+1. Read `{{BG_CONTEXT}}` (files, URLs, text)
+2. Build the seeding prompt with these parts:
+   - Share context (≤2000 words)
+   - Assign Gemini its stance
+   - Set debate rules (technical claims only, acknowledge valid points, numbered arguments)
+   - Request an opening argument
+3. `gemiterm new "seeding prompt"` — creates a chat, sends the first message, writes the response to the console, and returns the chat_id (`c_XXXXXXXXXXXX`); read Gemini's opening response from the same console output
+
+**Fallback:** If `gemiterm new` fails, ask the user to create a chat in the Gemini UI, paste the seeding prompt, and provide the chat_id. Then continue with Flow B.
+
+### Flow B — Existing Chat (chat_id provided)
+
+1. `gemiterm fetch {{GEMINI_CHAT_ID}} --format json`
+2. Parse Gemini's position (last model message)
+3. Read `{{BG_CONTEXT}}`
+4. Build position map: what Gemini argues, evidence for/against
+
+## Phase 2: Strategy & Execution
+
+1. **Analyze** — identify opponent's main arguments, evidence, weaknesses
+2. **Build opening argument** — address each opponent point, cite `{{BG_CONTEXT}}` evidence
+3. **Spawn subagent** — see [REFERENCE.md](REFERENCE.md) for the prompt template
+
+Fill template slots: `{{TOPIC}}`, `{{AGENT_STANCE}}`, `{{GEMINI_STANCE}}`, `{{GEMINI_CHAT_ID}}`, `{{TURN_LIMIT}}`, `{{BG_CONTEXT_SUMMARY}}`, `{{OPENING_ARGUMENT}}`.
+
+The subagent runs autonomously. It returns a structured Debate Report (format in REFERENCE.md).
+
+**Stopping criteria** (hardcoded in template):
+- Turn limit reached
+- Opponent concedes core question
+- Opponent repeats same argument twice → declare convergence, summarize
+- New factual information changes the calculus → stop, return to user
+
+**No pre-planned counter-responses.** Debate proceeds in real-time.
+
+## Edge Cases
+
+| Situation | Action |
+|-----------|--------|
+| `gemiterm new` fails | User creates a chat in the Gemini UI, provides the chat_id |
+| chat_id not in `gemiterm list` | Ask user to verify; may need a moment to appear |
+| Gemini concedes turn 1-2 | Accept, produce short report, stop |
+| New factual information | Stop, return to user with info + recommendation |
+| Auth expired | Stop, user runs `gemiterm auth` |
+| Rate limits | Wait 10s between turns; if persistent, stop and report |