# docs: add gemini packaging design and plan

## Changes

2

- docs/plans

- A2026-04-10-gemini-packaging-design.md+70

- A2026-04-10-gemini-packaging-implementation.md+162

# Gemini Packaging Design

**Date:** 2026-04-10

## Goal

Make this repository's Gemini integration match the upstream `obra/superpowers` pattern by exposing a root-level `gemini-extension.json` manifest and a root-level `GEMINI.md` entrypoint, while removing the legacy Gemini-specific install document.

## Current State

- Gemini support is currently documented only through [`.gemini/INSTALL.md`](/Users/alisha/Projects/agent-plugins/.gemini/INSTALL.md).
- Other agent integrations already use package or manifest-style entrypoints at predictable locations.
- Upstream Superpowers exposes Gemini through:
  - root `gemini-extension.json`
  - root `GEMINI.md`

## Chosen Approach

Adopt the upstream root-level manifest approach directly.

### Files to add

- `gemini-extension.json`
- `GEMINI.md`

### Files to update

- `README.md`

### Files to remove

- `.gemini/INSTALL.md`

## Design Details

### `gemini-extension.json`

Create a root manifest shaped like the upstream file:

- `name`
- `description`
- `version`
- `contextFileName`

The values should use this repository's metadata, with `contextFileName` set to `GEMINI.md`.

### `GEMINI.md`

Create a root Gemini entrypoint that points Gemini at this repo's skill bootstrap path. Since this repo does not mirror Superpowers' `skills/using-superpowers` tree, the file should reference the actual local skill entrypoint:

- `@./plugins/entire/skills/session-handoff/SKILL.md`

This keeps the Gemini experience aligned with the upstream packaging model while remaining correct for this repository's structure.

### README changes

Update the Gemini installation guidance so it no longer points to `.gemini/INSTALL.md`. The README should describe Gemini as using the root-level manifest and entrypoint, consistent with the Superpowers layout.

## Non-Goals

- No changes to the `session-handoff` skill behavior.
- No changes to Codex, Claude, Cursor, or OpenCode packaging.
- No attempt to preserve the old `.gemini/INSTALL.md` flow.

## Verification

- Confirm `gemini-extension.json` exists at the repository root.
- Confirm `GEMINI.md` exists at the repository root.
- Confirm `README.md` no longer references `.gemini/INSTALL.md`.
- Confirm `.gemini/INSTALL.md` has been removed.

# Gemini Packaging Implementation Plan

**Goal:** Replace the legacy Gemini install-doc flow with a root-level `gemini-extension.json` and `GEMINI.md` that match the Superpowers packaging pattern.

**Architecture:** Gemini packaging will be expressed entirely through two repository-root files: a lightweight manifest and a context entrypoint. Existing skill content remains in `plugins/entire/skills`, and `README.md` becomes the only human-readable install surface still mentioning Gemini.

**Tech Stack:** Markdown, JSON, existing repo documentation layout

---

### Task 1: Add Root Gemini Manifest And Entrypoint

**Files:**
- Create: `gemini-extension.json`
- Create: `GEMINI.md`

**Step 1: Write the failing test**

Run: `test -f gemini-extension.json; echo $?`
Expected: `1`

Run: `test -f GEMINI.md; echo $?`
Expected: `1`

**Step 2: Run test to verify it fails**

Run: `ls gemini-extension.json GEMINI.md`
Expected: `No such file or directory`

**Step 3: Write minimal implementation**

Create `gemini-extension.json` with:

```json
{
"name": "entire",
"description": "Cross-agent skills and commands powered by Entire.",
"version": "0.1.0",
"contextFileName": "GEMINI.md"
}
```

Create `GEMINI.md` with:

```md
@./plugins/entire/skills/session-handoff/SKILL.md
```

**Step 4: Run test to verify it passes**

Run: `sed -n '1,120p' gemini-extension.json GEMINI.md`
Expected: both files exist and contain the manifest plus the single `@./plugins/entire/skills/session-handoff/SKILL.md` reference

**Step 5: Commit**

```bash
git add gemini-extension.json GEMINI.md
git commit -m "feat: add gemini root packaging"
```

### Task 2: Update README Gemini Guidance

**Files:**
- Modify: `README.md`

**Step 1: Write the failing test**

Run: `rg -n '\.gemini/INSTALL\.md|Open `\.gemini/INSTALL\.md`' README.md`
Expected: one matching Gemini install reference

**Step 2: Run test to verify it fails**

Run: `sed -n '1,220p' README.md`
Expected: Gemini installation section still points to `.gemini/INSTALL.md`

**Step 3: Write minimal implementation**

Update the Gemini installation section so it describes the root-level `gemini-extension.json` and `GEMINI.md` flow instead of a separate `.gemini/INSTALL.md` document.

**Step 4: Run test to verify it passes**

Run: `rg -n '\.gemini/INSTALL\.md' README.md`
Expected: no output

Run: `rg -n 'gemini-extension\.json|GEMINI\.md' README.md`
Expected: Gemini references now point at the root-level files

**Step 5: Commit**

```bash
git add README.md
git commit -m "docs: update gemini packaging docs"
```

### Task 3: Remove Legacy Gemini Install Doc

**Files:**
- Delete: `.gemini/INSTALL.md`

**Step 1: Write the failing test**

Run: `test -f .gemini/INSTALL.md; echo $?`
Expected: `0`

**Step 2: Run test to verify it fails**

Run: `sed -n '1,160p' .gemini/INSTALL.md`
Expected: file contents are shown

**Step 3: Write minimal implementation**

Delete `.gemini/INSTALL.md`.

**Step 4: Run test to verify it passes**

Run: `test -f .gemini/INSTALL.md; echo $?`
Expected: `1`

Run: `rg -n '\.gemini/INSTALL\.md' .`
Expected: no output

**Step 5: Commit**

```bash
git add .gemini/INSTALL.md README.md
git commit -m "refactor: remove legacy gemini install doc"
```

### Task 4: Final Verification

**Files:**
- Verify: `gemini-extension.json`
- Verify: `GEMINI.md`
- Verify: `README.md`

**Step 1: Write the failing test**

Run: `rg -n '\.gemini/INSTALL\.md' README.md .`
Expected: no output after Tasks 2 and 3; if there is output, work is incomplete

**Step 2: Run test to verify the final state**

Run: `sed -n '1,220p' gemini-extension.json README.md GEMINI.md`
Expected: root Gemini files exist and README matches the new packaging model

**Step 3: Write minimal implementation**

If verification fails, fix only the mismatched file and rerun the verification commands.

**Step 4: Run test to verify it passes**

Run: `git status --short`
Expected: only intended Gemini packaging changes are present

**Step 5: Commit**

```bash
git add gemini-extension.json GEMINI.md README.md .gemini/INSTALL.md
git commit -m "feat: align gemini packaging with superpowers"
```