diff --git a/.config/hypr/hyprlock.conf b/.config/hypr/hyprlock.conf
index 9e466cf..8ee7573 100644
--- a/.config/hypr/hyprlock.conf
+++ b/.config/hypr/hyprlock.conf
@@ -1,4 +1,8 @@
# Hyprlock config with Catppuccin Mocha theme
+general {
+ grace = 0
+ no_input_trim = false
+}
# Background
background {
@@ -42,6 +46,7 @@ label {
# Password input
input-field {
+ ignore_empty_input = false
monitor =
size = 300, 50
outline_thickness = 2
@@ -49,21 +54,21 @@ input-field {
dots_spacing = 0.15
dots_center = true
dots_rounding = 2
- outer_color = rgba(180, 190, 254, 1.0) # Lavender
- inner_color = rgba(49, 50, 68, 1.0) # Surface0
- font_color = rgba(205, 214, 244, 1.0) # Text
+ outer_color = rgba(180, 190, 254, 1.0)
+ inner_color = rgba(49, 50, 68, 1.0)
+ font_color = rgba(205, 214, 244, 1.0)
fade_on_empty = false
- placeholder_text = Enter password...
+ placeholder_text = Touch YubiKey or enter password...
hide_input = false
- check_color = rgba(166, 227, 161, 1.0) # Green
- fail_color = rgba(243, 139, 168, 1.0) # Red
+ check_color = rgba(166, 227, 161, 1.0)
+ fail_color = rgba(243, 139, 168, 1.0)
fail_text = $FAIL ($ATTEMPTS)
- capslock_color = rgba(249, 226, 175, 1.0) # Yellow
+ fail_timeout = 3000
+ capslock_color = rgba(249, 226, 175, 1.0)
position = 0, -80
halign = center
valign = center
}
-
# Lock icon
label {
monitor =
diff --git a/.config/nvim/lazy-lock.json b/.config/nvim/lazy-lock.json
index 80a1dac..9de2e37 100644
--- a/.config/nvim/lazy-lock.json
+++ b/.config/nvim/lazy-lock.json
@@ -1,5 +1,6 @@
{
"LuaSnip": { "branch": "master", "commit": "dae4f5aaa3574bd0c2b9dd20fb9542a02c10471c" },
+ "blink.cmp": { "branch": "main", "commit": "f22f66eb7c4d037ed523a78b27ee235b7bc9a1f4" },
"catppuccin": { "branch": "main", "commit": "12c004cde3f36cb1d57242f1e6aac46b09a0e5b4" },
"cmp-buffer": { "branch": "main", "commit": "b74fab3656eea9de20a9b8116afa3cfc4ec09657" },
"cmp-nvim-lsp": { "branch": "main", "commit": "cbc7b02bb99fae35cb42f514762b89b5126651ef" },
@@ -19,6 +20,8 @@
"nvim-treesitter": { "branch": "main", "commit": "5cb05e1b0fa3c469958a2b26f36b3fe930af221c" },
"opencode.nvim": { "branch": "main", "commit": "1088ee70dd997d785a1757d351c07407f0abfc9f" },
"plenary.nvim": { "branch": "master", "commit": "b9fd5226c2f76c951fc8ed5923d85e4de065e509" },
+ "render-markdown.nvim": { "branch": "main", "commit": "e3c18ddd27a853f85a6f513a864cf4f2982b9f26" },
+ "snacks.nvim": { "branch": "main", "commit": "9912042fc8bca2209105526ac7534e9a0c2071b2" },
"telescope-fzf-native.nvim": { "branch": "main", "commit": "6fea601bd2b694c6f2ae08a6c6fab14930c60e2c" },
"telescope.nvim": { "branch": "master", "commit": "3333a52ff548ba0a68af6d8da1e54f9cd96e9179" }
}
diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md
index 7c419c5..968ea9c 100644
--- a/.config/opencode/AGENTS.md
+++ b/.config/opencode/AGENTS.md
@@ -16,7 +16,7 @@
| `planner` | primary | `github-copilot/gpt-5.4` | Produce approved specs and decide whether execution is ready |
| `builder` | primary | `github-copilot/gpt-5.4` | Execute approved specs and integrate delegated work |
| `researcher` | subagent | `github-copilot/gpt-5.4` | Deep research, external docs, tradeoff analysis |
-| `explorer` | subagent | `github-copilot/claude-sonner-4.6` | Fast read-only repo inspection and fact gathering |
+| `explorer` | subagent | `github-copilot/claude-sonnet-4.6` | Read-only repo inspection; reports facts only, never plans or recommendations |
| `reviewer` | subagent | `github-copilot/claude-opus-4.6` | Critique plans, code, tests, and release readiness |
| `coder` | subagent | `github-copilot/gpt-5.3-codex` | Implement narrowly scoped code changes |
| `tester` | subagent | `github-copilot/gpt-5.4` | Run verification, triage failures, capture evidence |
@@ -34,6 +34,15 @@
- `builder` must follow the approved plan exactly.
- `builder` must stop and escalate back to `planner` when it finds a spec contradiction, a hidden dependency that changes scope, or two failed verification attempts after recording root cause and evidence.
+### Builder Commits
+
+- `builder` automatically creates git commits at meaningful task checkpoints and at final completion when uncommitted changes remain.
+- A "meaningful checkpoint" is a completed implementation chunk from the approved plan, not every file save.
+- Skip commit creation when there are no new changes since the prior checkpoint.
+- Commit messages should reflect the intent of the completed task from the plan.
+- Standard git safety rules apply: review staged content, respect hooks, no force-push or destructive operations.
+- Push automation is out of scope; the user decides when to push.
+
## Commands
- `/init` initializes or refreshes repo memory and the project `AGENTS.md`.
@@ -99,6 +108,12 @@ Local skills live under `skills//SKILL.md` and are loaded on demand via th
| `dispatching-parallel-agents` | Safe parallelization with strict isolation tests and a single integrator |
| `test-driven-development` | Canonical red-green-refactor workflow for code changes |
+### Design & Domain Skills
+
+| Skill | Purpose |
+| --- | --- |
+| `frontend-design` | Distinctive, production-grade frontend UI with high design quality, accessibility, and performance |
+
### Ecosystem Skills
| Skill | Purpose |
@@ -111,11 +126,11 @@ Local skills live under `skills//SKILL.md` and are loaded on demand via th
Agents must proactively load applicable skills when their trigger conditions are met. Do not wait to be told.
-- **`planner`**: `brainstorming` (unclear requests, design work), `writing-plans` (authoring `plans/`), `dispatching-parallel-agents` (parallel lanes), `systematic-debugging` (unresolved bugs), `test-driven-development` (specifying code tasks), `docker-container-management` (repo uses Docker), `python-development` (Python repo/lane), `javascript-typescript-development` (JS/TS repo/lane).
-- **`builder`**: `dispatching-parallel-agents` (before parallel fan-out), `systematic-debugging` (bugs, regressions, flaky tests), `verification-before-completion` (before any completion claim), `test-driven-development` (before delegating or performing code changes), `docker-container-management` (containerized repo), `python-development` (Python lanes), `javascript-typescript-development` (JS/TS lanes).
+- **`planner`**: `brainstorming` (unclear requests, design work), `writing-plans` (authoring `plans/`), `dispatching-parallel-agents` (parallel lanes), `systematic-debugging` (unresolved bugs), `test-driven-development` (specifying code tasks), `frontend-design` (frontend UI/UX implementation or redesign), `docker-container-management` (repo uses Docker), `python-development` (Python repo/lane), `javascript-typescript-development` (JS/TS repo/lane).
+- **`builder`**: `dispatching-parallel-agents` (before parallel fan-out), `systematic-debugging` (bugs, regressions, flaky tests), `verification-before-completion` (before any completion claim), `test-driven-development` (before delegating or performing code changes), `frontend-design` (frontend UI/UX implementation lanes), `docker-container-management` (containerized repo), `python-development` (Python lanes), `javascript-typescript-development` (JS/TS lanes).
- **`tester`**: `systematic-debugging` (verification failure diagnosis), `verification-before-completion` (before declaring verification complete), `test-driven-development` (validating red/green cycles), `docker-container-management` (tests run in containers), `python-development` (Python verification), `javascript-typescript-development` (JS/TS verification).
- **`reviewer`**: `verification-before-completion` (evaluating completion evidence), `test-driven-development` (reviewing red/green discipline).
-- **`coder`**: `test-driven-development` (all code tasks), `docker-container-management` (Dockerfiles, compose files, containerized builds), `python-development` (Python code lanes), `javascript-typescript-development` (JS/TS code lanes); other skills when the assigned lane explicitly calls for them.
+- **`coder`**: `test-driven-development` (all code tasks), `frontend-design` (frontend component, page, or application implementation lanes), `docker-container-management` (Dockerfiles, compose files, containerized builds), `python-development` (Python code lanes), `javascript-typescript-development` (JS/TS code lanes); other skills when the assigned lane explicitly calls for them.
- **`librarian`**: Load relevant skills opportunistically when the assigned task calls for them; do not override planner/builder workflow ownership.
### TDD Default Policy
diff --git a/.config/opencode/agents/builder.md b/.config/opencode/agents/builder.md
index 1382a49..76554c4 100644
--- a/.config/opencode/agents/builder.md
+++ b/.config/opencode/agents/builder.md
@@ -29,6 +29,7 @@ You are the execution authority.
- `test-driven-development` before delegating or performing code changes.
- `docker-container-management` when executing tasks in a containerized repo.
- `python-development` when executing Python lanes.
+ - `frontend-design` when executing frontend UI/UX implementation lanes.
- `javascript-typescript-development` when executing JS/TS lanes.
- Read the latest approved plan before making changes.
@@ -37,4 +38,7 @@ You are the execution authority.
- Use parallel subagents when implementation lanes are isolated and can be verified independently.
- Maintain an execution log in basic-memory under `executions/` with `Status: in_progress|blocked|done`.
- If you hit a contradiction, hidden dependency, or two failed verification attempts, record the root cause and evidence, then stop and send the work back to `planner`.
-- Do not create commits unless the user explicitly asks.
+- Builder owns commit creation during `/build`; do not delegate commit authorship decisions to other agents.
+- Create commits automatically at meaningful completed implementation checkpoints, and create a final completion commit when changes remain.
+- Reuse existing git safety constraints: avoid destructive git behavior, do not force push, and do not add push automation.
+- If there are no new changes at a checkpoint, skip commit creation instead of creating empty or duplicate commits.
diff --git a/.config/opencode/agents/coder.md b/.config/opencode/agents/coder.md
index bfdf705..60a3775 100644
--- a/.config/opencode/agents/coder.md
+++ b/.config/opencode/agents/coder.md
@@ -16,6 +16,7 @@ Implement only the assigned lane.
- Proactively load `test-driven-development` for code development tasks.
- Load `docker-container-management` when the lane involves Dockerfiles, compose files, or containerized builds.
- Load `python-development` when the lane involves Python code.
+- Load `frontend-design` when the lane involves frontend component, page, or application implementation.
- Load `javascript-typescript-development` when the lane involves JS/TS code.
- Load other local skills only when the assigned lane explicitly calls for them.
diff --git a/.config/opencode/agents/explorer.md b/.config/opencode/agents/explorer.md
index 222d679..a6c1761 100644
--- a/.config/opencode/agents/explorer.md
+++ b/.config/opencode/agents/explorer.md
@@ -1,5 +1,5 @@
---
-description: Fast read-only repo explorer for locating files, symbols, patterns, and local facts
+description: Read-only repo inspector that reports observable facts only — never plans or recommendations
mode: subagent
model: github-copilot/claude-sonnet-4.6
temperature: 0.0
@@ -12,9 +12,17 @@ permission:
permalink: opencode-config/agents/explorer
---
-Focus on local discovery.
+You are a fact-gathering tool, not a planner.
-- Inspect the repository quickly and report only the relevant facts.
+- Inspect the repository quickly and report only observable facts.
- Prefer `glob`, `grep`, `read`, structural search, and memory lookups.
-- Return file paths, symbols, and constraints with minimal speculation.
+- Return file paths, symbols, code relationships, and constraints.
- Do not make changes.
+
+Forbidden output:
+- Plan drafts, task lists, or implementation steps.
+- Solution design or architecture proposals.
+- Speculative recommendations or subjective assessments.
+- Priority rankings or suggested next actions.
+
+If a finding has implications for planning, state the fact and stop. Let the caller draw conclusions.
diff --git a/.config/opencode/agents/planner.md b/.config/opencode/agents/planner.md
index 2e1f07b..097f146 100644
--- a/.config/opencode/agents/planner.md
+++ b/.config/opencode/agents/planner.md
@@ -29,6 +29,7 @@ You are the planning authority.
- `test-driven-development` when specifying implementation tasks that mutate code.
- `docker-container-management` when a repo uses Docker/docker-compose.
- `python-development` when a repo or lane is primarily Python.
+ - `frontend-design` when the task involves frontend UI/UX implementation or redesign.
- `javascript-typescript-development` when a repo or lane is primarily JS/TS.
## Clarification and the `question` tool
diff --git a/.config/opencode/commands/build.md b/.config/opencode/commands/build.md
index ae0161e..edabb1b 100644
--- a/.config/opencode/commands/build.md
+++ b/.config/opencode/commands/build.md
@@ -9,7 +9,10 @@ Execute the latest approved plan for: $ARGUMENTS
1. Read the latest matching `plans/` note with `Status: approved`.
2. Create or update `executions/` with `Status: in_progress` before changing code.
3. Delegate implementation to `coder`, verification to `tester`, review to `reviewer`, and docs or memory updates to `librarian` where appropriate.
-4. Follow the plan exactly. If the plan is contradictory, missing a dependency, or fails verification twice, stop, capture evidence, set the execution note to blocked, and send the work back to `planner`.
-5. Finish by updating the execution note to `Status: done` or `Status: blocked` and summarizing what changed.
+4. Builder owns commit creation during `/build`: create automatic commits at meaningful completed implementation checkpoints.
+5. Reuse existing git safety rules and avoid destructive git behavior; do not add push automation.
+6. If no new changes exist at a checkpoint, skip commit creation rather than creating empty or duplicate commits.
+7. Follow the plan exactly. If the plan is contradictory, missing a dependency, or fails verification twice, stop, capture evidence, set the execution note to blocked, and send the work back to `planner`.
+8. Finish by creating a final completion commit when changes remain, then update the execution note to `Status: done` or `Status: blocked` and summarize what changed.
-Do not create a commit unless the user explicitly asks.
+Automatic commits are required during `/build` as defined above.
diff --git a/.config/opencode/skills/frontend-design/SKILL.md b/.config/opencode/skills/frontend-design/SKILL.md
new file mode 100644
index 0000000..5cf4ee4
--- /dev/null
+++ b/.config/opencode/skills/frontend-design/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+permalink: opencode-config/skills/frontend-design/skill
+---
+
+# Frontend Design
+
+## When to Load
+
+Load this skill when the task involves building, redesigning, or significantly styling a frontend component, page, or application. Triggers include: user requests for UI/UX implementation, wireframe-to-code work, visual redesigns, and new web interfaces.
+
+## Design Thinking Checklist
+
+Before writing code, answer these:
+
+1. **Purpose** — What problem does this interface solve? Who is the audience?
+2. **Brand / product context** — Does the project have existing design tokens, a style guide, or brand constraints? Follow them first; extend only where gaps exist.
+3. **Aesthetic direction** — Commit to a clear direction (e.g., brutally minimal, maximalist, retro-futuristic, editorial, organic, luxury, playful, industrial). Intentionality matters more than intensity.
+4. **Differentiation** — Identify the single most memorable element of the design.
+5. **Constraints** — Note framework requirements, performance budgets, and accessibility targets (WCAG AA minimum).
+
+## Implementation Checklist
+
+- [ ] Produce production-grade, functional code (HTML/CSS/JS, React, Vue, etc.)
+- [ ] Ensure the result is visually cohesive with a clear aesthetic point of view
+- [ ] Respect accessibility: semantic HTML, sufficient contrast, keyboard navigation, focus management
+- [ ] Respect performance: avoid heavy unoptimized assets; prefer CSS-only solutions for animation where practical
+- [ ] Use CSS variables for color/theme consistency
+- [ ] Match implementation complexity to the aesthetic vision — maximalist designs need elaborate effects; minimal designs need precision and restraint
+
+## Aesthetic Guidance
+
+- **Typography** — Choose distinctive, characterful fonts. Pair a display font with a refined body font. Avoid defaulting to the same choices across projects; vary intentionally.
+- **Color & Theme** — Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Vary between light and dark themes across projects.
+- **Motion** — Prioritize high-impact moments: a well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use CSS animations where possible; use a motion library (e.g., Motion) for complex sequences. Include scroll-triggered and hover effects when they serve the design.
+- **Spatial Composition** — Explore asymmetry, overlap, diagonal flow, grid-breaking elements, generous negative space, or controlled density.
+- **Backgrounds & Atmosphere** — Build depth with gradient meshes, noise textures, geometric patterns, layered transparencies, shadows, grain overlays, or other contextual effects rather than defaulting to flat solid colors.
+
+Avoid converging on the same fonts, color schemes, or layout patterns across generations. Each design should feel context-specific and intentional.
+
+## TDD & Verification
+
+Frontend code changes follow the project's TDD default policy. When the skill is loaded alongside `test-driven-development`:
+
+- Write or update component/visual tests before implementation when a test harness exists.
+- If no frontend test harness is available, state the exception and describe alternative verification (e.g., manual browser check, screenshot comparison).
+- Satisfy `verification-before-completion` requirements before claiming the work is done.
diff --git a/.config/opencode/skills/using-superpowers/SKILL.md b/.config/opencode/skills/using-superpowers/SKILL.md
new file mode 100644
index 0000000..d813535
--- /dev/null
+++ b/.config/opencode/skills/using-superpowers/SKILL.md
@@ -0,0 +1,115 @@
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
+---
+
+
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+
+
+
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+
+
+## Instruction Priority
+
+Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
+
+1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
+2. **Superpowers skills** — override default system behavior where they conflict
+3. **Default system prompt** — lowest priority
+
+If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+## Platform Adaptation
+
+Skills use Claude Code tool names. Non-CC platforms: see `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+ "User message received" [shape=doublecircle];
+ "About to EnterPlanMode?" [shape=doublecircle];
+ "Already brainstormed?" [shape=diamond];
+ "Invoke brainstorming skill" [shape=box];
+ "Might any skill apply?" [shape=diamond];
+ "Invoke Skill tool" [shape=box];
+ "Announce: 'Using [skill] to [purpose]'" [shape=box];
+ "Has checklist?" [shape=diamond];
+ "Create TodoWrite todo per item" [shape=box];
+ "Follow skill exactly" [shape=box];
+ "Respond (including clarifications)" [shape=doublecircle];
+
+ "About to EnterPlanMode?" -> "Already brainstormed?";
+ "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+ "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+ "Invoke brainstorming skill" -> "Might any skill apply?";
+
+ "User message received" -> "Might any skill apply?";
+ "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+ "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+ "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+ "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+ "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
+ "Has checklist?" -> "Follow skill exactly" [label="no"];
+ "Create TodoWrite todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
diff --git a/.config/opencode/skills/using-superpowers/references/codex-tools.md b/.config/opencode/skills/using-superpowers/references/codex-tools.md
new file mode 100644
index 0000000..eb23075
--- /dev/null
+++ b/.config/opencode/skills/using-superpowers/references/codex-tools.md
@@ -0,0 +1,25 @@
+# Codex Tool Mapping
+
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
+
+| Skill references | Codex equivalent |
+|-----------------|------------------|
+| `Task` tool (dispatch subagent) | `spawn_agent` |
+| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
+| Task returns result | `wait` |
+| Task completes automatically | `close_agent` to free slot |
+| `TodoWrite` (task tracking) | `update_plan` |
+| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
+| `Read`, `Write`, `Edit` (files) | Use your native file tools |
+| `Bash` (run commands) | Use your native shell tools |
+
+## Subagent dispatch requires collab
+
+Add to your Codex config (`~/.codex/config.toml`):
+
+```toml
+[features]
+collab = true
+```
+
+This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
diff --git a/.config/opencode/skills/using-superpowers/references/gemini-tools.md b/.config/opencode/skills/using-superpowers/references/gemini-tools.md
new file mode 100644
index 0000000..f869803
--- /dev/null
+++ b/.config/opencode/skills/using-superpowers/references/gemini-tools.md
@@ -0,0 +1,33 @@
+# Gemini CLI Tool Mapping
+
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
+
+| Skill references | Gemini CLI equivalent |
+|-----------------|----------------------|
+| `Read` (file reading) | `read_file` |
+| `Write` (file creation) | `write_file` |
+| `Edit` (file editing) | `replace` |
+| `Bash` (run commands) | `run_shell_command` |
+| `Grep` (search file content) | `grep_search` |
+| `Glob` (search files by name) | `glob` |
+| `TodoWrite` (task tracking) | `write_todos` |
+| `Skill` tool (invoke a skill) | `activate_skill` |
+| `WebSearch` | `google_web_search` |
+| `WebFetch` | `web_fetch` |
+| `Task` tool (dispatch subagent) | No equivalent — Gemini CLI does not support subagents |
+
+## No subagent support
+
+Gemini CLI has no equivalent to Claude Code's `Task` tool. Skills that rely on subagent dispatch (`subagent-driven-development`, `dispatching-parallel-agents`) will fall back to single-session execution via `executing-plans`.
+
+## Additional Gemini CLI tools
+
+These tools are available in Gemini CLI but have no Claude Code equivalent:
+
+| Tool | Purpose |
+|------|---------|
+| `list_directory` | List files and subdirectories |
+| `save_memory` | Persist facts to GEMINI.md across sessions |
+| `ask_user` | Request structured input from the user |
+| `tracker_create_task` | Rich task management (create, update, list, visualize) |
+| `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes |