@kurokeita/add-skill 1.21.0 → 2.0.0

package/dist/skills/statusline-setup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: statusline-setup
-description: 'Set up the Claude Code statusline with cwd, git branch, model, context %, session token totals, and 5h/7d quota usage with ETA. Use when asked to "set up my statusline", "install statusline", "configure Claude Code statusline", or to add a colored status line showing rate limits and token usage. Detects OS and installs the appropriate variant (bash + jq on Linux/macOS, PowerShell on Windows).'
+description: 'Set up the Claude Code or Gemini/Antigravity CLI statusline with cwd, git branch, model, context %, session token totals, and 5h/7d quota usage with ETA. Use when asked to "set up my statusline", "install statusline", "configure statusline", or to add a colored status line showing rate limits and token usage. Detects OS and installs the appropriate variant (bash + jq on Linux/macOS, PowerShell on Windows).'
 ---
 
 # Statusline Setup
 
-Install a Claude Code statusline that renders, left to right, pipe-separated:
+Install a Claude Code or Gemini/Antigravity statusline that renders, left to right, pipe-separated:
 
 1. **cwd** — 24-bit ANSI `#5EFFFF` (`38;2;94;255;255`), with `$HOME` / `%USERPROFILE%` shortened to `~`.
 2. **git branch** in parentheses — 24-bit ANSI `#C24870` (`38;2;194;72;112`), only when inside a repo.
@@ -18,18 +18,25 @@ Segments are joined with ANSI `0;37` pipes (` | `).
 
 ## When to Use This Skill
 
-- "Set up my Claude Code statusline"
+- "Set up my Claude Code statusline" or "Set up my Antigravity statusline"
 - "Install the statusline"
 - "Configure my statusline with token counts and quota"
 - Any request to add a colored status line showing context %, rate limits, or session tokens.
 
-## OS Detection
+## OS & Platform Detection
 
-Detect the platform first and install only the matching variant:
+Detect the operating system and targeted platform first, then write and wire the corresponding configuration:
+
+### Claude Code
 
 - **Linux / macOS** → write `~/.claude/statusline-command.sh` (pure bash + `jq`), wire into `~/.claude/settings.json`.
 - **Windows** → write `%USERPROFILE%\.claude\statusline-command.ps1`, wire into `%USERPROFILE%\.claude\settings.json`.
 
+### Antigravity / Gemini CLI
+
+- **Linux / macOS** → write `~/.gemini/antigravity-cli/statusline-command.sh` (pure bash + `jq`), wire into `~/.gemini/antigravity-cli/settings.json`.
+- **Windows** → write `%USERPROFILE%\.gemini\antigravity-cli\statusline-command.ps1`, wire into `%USERPROFILE%\.gemini\antigravity-cli\settings.json`.
+
 ## Token Formatting
 
 - `< 1000` → raw integer (e.g. `↑850 ↓120`)
@@ -39,12 +46,14 @@ Detect the platform first and install only the matching variant:
 
 ## Token Source
 
-Claude Code does **not** include token totals in the statusline JSON. Read `transcript_path` (JSONL, one message per line) and sum across **assistant** messages:
+Tokens are calculated dynamically:
 
-- `input` = `message.usage.input_tokens` + `message.usage.cache_creation_input_tokens` + `message.usage.cache_read_input_tokens`
-- `output` = `message.usage.output_tokens`
-
-Skip lines that fail JSON parsing or lack `message.usage`. If `transcript_path` is missing or the file does not exist, omit the tokens segment.
+1. **Transcript Parsing (Claude Code / general)**: Sum across assistant messages in the JSONL `transcript_path` file:
+   - `input` = `message.usage.input_tokens` + `message.usage.cache_creation_input_tokens` + `message.usage.cache_read_input_tokens`
+   - `output` = `message.usage.output_tokens`
+2. **Payload Fallback (Antigravity / Gemini CLI)**: If transcript parsing yields `0` tokens (or the transcript doesn't store step token metrics), fallback to:
+   - `input` = `context_window.total_input_tokens`
+   - `output` = `context_window.total_output_tokens`
 
 ## Quota Colors (by REMAINING quota = 100 - used%)
 
@@ -57,7 +66,7 @@ Skip lines that fail JSON parsing or lack `message.usage`. If `transcript_path`
 
 The 5h and 7d windows must be colored **independently**.
 
-## ETA Format (from epoch seconds in `resets_at`)
+## ETA Format (from epoch seconds or reset duration in seconds)
 
 - `> 1 day` → `Xd Yh`
 - `> 1 hour` → `Xh Ym`
@@ -66,34 +75,57 @@ The 5h and 7d windows must be colored **independently**.
 
 ## Input Schema (stdin JSON)
 
-Any field may be missing:
+The input schema depends on the platform:
+
+### Claude Code Schema
 
+```json
+{
+  "cwd": "/path/to/cwd",
+  "transcript_path": "/path/to/transcript.jsonl",
+  "model": { "display_name": "Opus 4.7" },
+  "effort": { "level": "medium" },
+  "context_window": { "used_percentage": 42 },
+  "rate_limits": {
+    "five_hour": { "used_percentage": 80, "resets_at": 1719213265 },
+    "seven_day": { "used_percentage": 50, "resets_at": 1719213265 }
+  }
+}
 ```
-cwd
-transcript_path
-model.display_name
-effort.level
-context_window.used_percentage
-rate_limits.five_hour.used_percentage
-rate_limits.five_hour.resets_at
-rate_limits.seven_day.used_percentage
-rate_limits.seven_day.resets_at
+
+### Antigravity Schema
+
+```json
+{
+  "cwd": "/path/to/cwd",
+  "transcript_path": "/path/to/transcript.jsonl",
+  "model": { "display_name": "Gemini 3.5 Flash" },
+  "context_window": {
+    "used_percentage": 6.7,
+    "total_input_tokens": 70419,
+    "total_output_tokens": 16667
+  },
+  "quota": {
+    "gemini-5h": { "remaining_fraction": 0.87, "reset_in_seconds": 2515 },
+    "gemini-weekly": { "remaining_fraction": 0.97, "reset_in_seconds": 589315 }
+  }
+}
 ```
 
 ## Linux / macOS Implementation
 
-Write `~/.claude/statusline-command.sh` (chmod +x). Pure bash + `jq` — no Python. `jq` must be installed (`apt install jq`, `brew install jq`, etc.); if missing, the script prints a one-line hint and exits 0 so the statusline area stays clean.
+Write `statusline-command.sh` (chmod +x) to the targeted platform directory. Pure bash + `jq` — no Python. `jq` must be installed; if missing, the script prints a one-line hint and exits 0.
 
 JSON parsing rules:
 
 - Read the full stdin payload **once** with `cat`, parse all fields with a single `jq` call.
-- For the JSONL transcript, invoke `jq` **once over the whole file** (do not call `jq` per line) — use a streaming filter that reduces over `inputs`.
+- Use `fromjson?` to process JSONL files line-by-line resiliently to ignore malformed/plain-text entries.
 
-`~/.claude/statusline-command.sh`:
+`statusline-command.sh`:
 
 ```bash
 #!/usr/bin/env bash
-# Claude Code statusline — pure bash + jq.
+# Statusline — pure bash + jq. Supports Claude Code & Antigravity payload formats.
 
 set -u
 
@@ -127,10 +159,14 @@ quota_color() {
 
 fmt_eta() {
   local resets="$1"
-  [[ -z "$resets" || "$resets" == "null" ]] && { printf ''; return; }
+  [[ -z "$resets" || "$resets" == "null" || "$resets" == "" ]] && { printf ''; return; }
   local now delta days hours mins
-  now=$(date +%s)
-  delta=$(( resets - now ))
+  if (( resets < 10000000 )); then
+    delta=$resets
+  else
+    now=$(date +%s)
+    delta=$(( resets - now ))
+  fi
   if   (( delta <= 0 )); then printf 'now'
   elif (( delta >= 86400 )); then
     days=$(( delta / 86400 )); hours=$(( (delta % 86400) / 3600 ))
@@ -173,15 +209,41 @@ read_fields() {
       .model.display_name // "",
       .effort.level // "",
       (.context_window.used_percentage // "" | tostring),
-      (.rate_limits.five_hour.used_percentage // "" | tostring),
-      (.rate_limits.five_hour.resets_at // "" | tostring),
-      (.rate_limits.seven_day.used_percentage // "" | tostring),
-      (.rate_limits.seven_day.resets_at // "" | tostring)
+      (
+        .rate_limits.five_hour.used_percentage // 
+        (if .quota."gemini-5h" != null then ((1.0 - .quota."gemini-5h".remaining_fraction) * 100) 
+         elif .quota."3p-5h" != null then ((1.0 - .quota."3p-5h".remaining_fraction) * 100) 
+         else "" end)
+        | tostring
+      ),
+      (
+        .rate_limits.five_hour.resets_at // 
+        .quota."gemini-5h".reset_in_seconds // 
+        .quota."3p-5h".reset_in_seconds // 
+        ""
+        | tostring
+      ),
+      (
+        .rate_limits.seven_day.used_percentage // 
+        (if .quota."gemini-weekly" != null then ((1.0 - .quota."gemini-weekly".remaining_fraction) * 100) 
+         elif .quota."3p-weekly" != null then ((1.0 - .quota."3p-weekly".remaining_fraction) * 100) 
+         else "" end)
+        | tostring
+      ),
+      (
+        .rate_limits.seven_day.resets_at // 
+        .quota."gemini-weekly".reset_in_seconds // 
+        .quota."3p-weekly".reset_in_seconds // 
+        ""
+        | tostring
+      ),
+      (.context_window.total_input_tokens // "" | tostring),
+      (.context_window.total_output_tokens // "" | tostring)
     ] | join("\u001f")
   ' 2>/dev/null <<<"$payload"
 }
 
-IFS=$'\x1f' read -r cwd transcript model effort ctx five_used five_reset seven_used seven_reset < <(read_fields)
+IFS=$'\x1f' read -r cwd transcript model effort ctx five_used five_reset seven_used seven_reset payload_in payload_out < <(read_fields)
 
 segments=()
 
@@ -211,10 +273,23 @@ if [[ -n "$ctx" ]]; then
   segments+=("${C_CTX}ctx ${ctx_int}%${RESET}")
 fi
 
-# --- tokens: one jq pass over the whole JSONL transcript ---
+ti=0
+to=0
+
+# --- tokens: sum transcripts, fallback to context_window if needed ---
+if [[ -n "$transcript" ]]; then
+  # Resolve path mismatch (if it has .gemini/antigravity/ but it actually is at .gemini/antigravity-cli/)
+  if [[ ! -f "$transcript" && "$transcript" == *"/antigravity/"* ]]; then
+    corrected_transcript="${transcript//\/antigravity\//\/antigravity-cli\/}"
+    if [[ -f "$corrected_transcript" ]]; then
+      transcript="$corrected_transcript"
+    fi
+  fi
+fi
+
 if [[ -n "$transcript" && -f "$transcript" ]]; then
-  tok=$(jq -rs '
-    reduce .[] as $m ({i:0,o:0};
+  tok=$(jq -Rn '
+    reduce (inputs | fromjson?) as $m ({i:0,o:0};
       ($m.message.usage // null) as $u
       | if $u == null then .
         else
@@ -226,12 +301,21 @@ if [[ -n "$transcript" && -f "$transcript" ]]; then
   ' "$transcript" 2>/dev/null) || tok=""
   if [[ -n "$tok" ]]; then
     IFS=$'\t' read -r ti to <<<"$tok"
-    if (( ti > 0 || to > 0 )); then
-      segments+=("${C_TOK}↑$(fmt_tokens "$ti") ↓$(fmt_tokens "$to")${RESET}")
-    fi
   fi
 fi
 
+# Fallback to payload context_window tokens if transcript sum is 0
+if (( ti == 0 && to == 0 )); then
+  if [[ -n "$payload_in" && -n "$payload_out" ]]; then
+    ti=$payload_in
+    to=$payload_out
+  fi
+fi
+
+if (( ti > 0 || to > 0 )); then
+  segments+=("${C_TOK}↑$(fmt_tokens "$ti") ↓$(fmt_tokens "$to")${RESET}")
+fi
+
 if [[ -n "$five_used" ]]; then
   fu=$(awk -v n="$five_used" 'BEGIN{printf "%d", (n+0.5)}')
   eta=$(fmt_eta "$five_reset")
@@ -253,22 +337,11 @@ done
 printf '%s' "$out"
 ```
 
-Wire into `~/.claude/settings.json` (merge into existing JSON, don't clobber other keys):
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "bash ~/.claude/statusline-command.sh"
-  }
-}
-```
-
 ## Windows Implementation
 
-Write `%USERPROFILE%\.claude\statusline-command.ps1`. Use `ConvertFrom-Json` (no Python dep). Read the JSONL transcript with `Get-Content -ReadCount 0` and `ConvertFrom-Json` per line inside try/catch. Use `[char]27` for ANSI escapes (works on PS 5.1 and 7+). Read stdin with `[Console]::In.ReadToEnd()`.
+Write `statusline-command.ps1` to the targeted platform directory. Use `ConvertFrom-Json` (no Python dep). Read the JSONL transcript with `Get-Content -ReadCount 0` and `ConvertFrom-Json` per line inside try/catch. Use `[char]27` for ANSI escapes.
 
-`%USERPROFILE%\.claude\statusline-command.ps1`:
+`statusline-command.ps1`:
 
 ```powershell
 $ErrorActionPreference = 'SilentlyContinue'
@@ -298,8 +371,13 @@ function QuotaColor([double]$used) {
 }
 
 function FmtEta($resetsAt) {
-  if ($null -eq $resetsAt) { return "" }
-  $delta = [int64]$resetsAt - [int64](Get-Date -UFormat %s)
+  if ($null -eq $resetsAt -or $resetsAt -eq "") { return "" }
+  $val = [int64]$resetsAt
+  if ($val -lt 10000000) {
+    $delta = $val
+  } else {
+    $delta = $val - [int64](Get-Date -UFormat %s)
+  }
   if ($delta -le 0) { return "now" }
   $days = [math]::Floor($delta / 86400); $delta = $delta % 86400
   $hours = [math]::Floor($delta / 3600); $delta = $delta % 3600
@@ -334,6 +412,13 @@ function GetBranch($cwd) {
 
 function SumTokens($path) {
   if (-not $path) { return $null }
+  # Resolve path mismatch (if it has .gemini/antigravity/ but it actually is at .gemini/antigravity-cli/)
+  if (-not (Test-Path -LiteralPath $path) -and $path.Contains("/.gemini/antigravity/")) {
+    $corrected = $path.Replace(".gemini/antigravity/", ".gemini/antigravity-cli/").Replace(".gemini\antigravity\", ".gemini\antigravity-cli\")
+    if (Test-Path -LiteralPath $corrected) {
+      $path = $corrected
+    }
+  }
   if (-not (Test-Path -LiteralPath $path)) { return $null }
   $sumIn = 0; $sumOut = 0; $found = $false
   $lines = Get-Content -LiteralPath $path -ReadCount 0 -ErrorAction SilentlyContinue
@@ -377,39 +462,99 @@ $ctx = $data.context_window.used_percentage
 if ($null -ne $ctx) { $segments += "$C_CTX" + "ctx " + [int][math]::Round([double]$ctx) + "%$RESET" }
 
 $tokens = SumTokens $data.transcript_path
+$ti = 0
+$to = 0
 if ($null -ne $tokens) {
-  $segments += "$C_TOK↑$(FmtTokens $tokens[0]) ↓$(FmtTokens $tokens[1])$RESET"
+  $ti = $tokens[0]
+  $to = $tokens[1]
 }
 
-$five = $data.rate_limits.five_hour
-$seven = $data.rate_limits.seven_day
-if ($null -ne $five.used_percentage) {
-  $u = [double]$five.used_percentage
-  $segments += "$(QuotaColor $u)5h:$([int][math]::Round($u))%($(FmtEta $five.resets_at))$RESET"
+# Fallback to payload context_window tokens if transcript sum is 0
+if ($ti -eq 0 -and $to -eq 0) {
+  if ($null -ne $data.context_window.total_input_tokens -and $null -ne $data.context_window.total_output_tokens) {
+    $ti = [int64]$data.context_window.total_input_tokens
+    $to = [int64]$data.context_window.total_output_tokens
+  }
 }
-if ($null -ne $seven.used_percentage) {
-  $u = [double]$seven.used_percentage
-  $segments += "$(QuotaColor $u)7d:$([int][math]::Round($u))%($(FmtEta $seven.resets_at))$RESET"
+
+if ($ti -gt 0 -or $to -gt 0) {
+  $segments += "$C_TOK↑$(FmtTokens $ti) ↓$(FmtTokens $to)$RESET"
+}
+
+$five_used = $null
+$five_reset = $null
+$seven_used = $null
+$seven_reset = $null
+
+if ($null -ne $data.rate_limits.five_hour.used_percentage) {
+  $five_used = $data.rate_limits.five_hour.used_percentage
+  $five_reset = $data.rate_limits.five_hour.resets_at
+} elseif ($null -ne $data.quota) {
+  $q5 = if ($null -ne $data.quota."gemini-5h") { $data.quota."gemini-5h" } else { $data.quota."3p-5h" }
+  if ($null -ne $q5) {
+    $five_used = (1.0 - $q5.remaining_fraction) * 100
+    $five_reset = $q5.reset_in_seconds
+  }
+}
+
+if ($null -ne $data.rate_limits.seven_day.used_percentage) {
+  $seven_used = $data.rate_limits.seven_day.used_percentage
+  $seven_reset = $data.rate_limits.seven_day.resets_at
+} elseif ($null -ne $data.quota) {
+  $qw = if ($null -ne $data.quota."gemini-weekly") { $data.quota."gemini-weekly" } else { $data.quota."3p-weekly" }
+  if ($null -ne $qw) {
+    $seven_used = (1.0 - $qw.remaining_fraction) * 100
+    $seven_reset = $qw.reset_in_seconds
+  }
+}
+
+if ($null -ne $five_used) {
+  $segments += "$(QuotaColor $five_used)5h:$([int][math]::Round($five_used))%($(FmtEta $five_reset))$RESET"
+}
+if ($null -ne $seven_used) {
+  $segments += "$(QuotaColor $seven_used)7d:$([int][math]::Round($seven_used))%($(FmtEta $seven_reset))$RESET"
 }
 
 $sep = " $C_PIPE|$RESET "
 [Console]::Out.Write([string]::Join($sep, $segments))
 ```
 
-Wire into `%USERPROFILE%\.claude\settings.json`:
+## Settings Wiring
+
+### Claude Code
+
+Wire into `~/.claude/settings.json` (or `%USERPROFILE%\.claude\settings.json` on Windows):
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash ~/.claude/statusline-command.sh"
+  }
+}
+```
+
+(Or the `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\statusline-command.ps1"` variant on Windows).
+
+### Antigravity CLI
+
+Wire into `~/.gemini/antigravity-cli/settings.json` (or `%USERPROFILE%\.gemini\antigravity-cli\settings.json` on Windows):
 
 ```json
 {
   "statusLine": {
     "type": "command",
-    "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\\.claude\\statusline-command.ps1\""
+    "command": "bash ~/.gemini/antigravity-cli/statusline-command.sh",
+    "enabled": true
   }
 }
 ```
 
+(Or the `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.gemini\antigravity-cli\statusline-command.ps1"` variant on Windows).
+
 ## Smoke Test
 
-After installing, generate a fake JSON payload with 5h at 80% used, 7d at 50% used, both with future `resets_at`, plus a `transcript_path` pointing at a small fixture JSONL containing two assistant messages with `usage` blocks. Pipe it into the script and confirm:
+After installing, generate a fake JSON payload with 5h at 80% used, 7d at 50% used, both with future `resets_at`/`reset_in_seconds`, plus a `transcript_path` pointing at a small fixture JSONL containing two assistant messages with `usage` blocks. Pipe it into the script and confirm:
 
 - 5h renders **orange**, 7d renders **amber**.
 - cwd, model, and context % are present.

package/dist/skills/universalize-agents/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: universalize-agents
+description: Use when the user wants to consolidate or "universalize" their AI agent setup across platforms (Claude Code, Codex, Windsurf, GitHub Copilot, Gemini CLI, Antigravity). Discovers each platform's installed skills/agents/commands and master instructions, copies them into a single `.agents/` directory, migrates master instructions into a canonical `AGENTS.md`, and installs a per-platform session-start hook that symlinks `.agents/` back into each platform's directories.
+version: 0.1.0
+---
+
+# Universalize Agents
+
+Consolidate a multi-platform AI agent setup into one source of truth
+(`.agents/` + `AGENTS.md`) and wire every platform to re-materialize it via
+symlinks on each session start.
+
+This skill is the first step of a larger "universalize agent setup" feature.
+It performs discovery, consolidation, and hook installation. It does **not**
+modify this repository's `src/` or CLI.
+
+## Canonical references
+
+Read these before acting — they are the source of truth and must not drift
+from the codebase:
+
+- `reference/mapping.md` — reverse map of every platform's
+  skills/agents/commands directories (derived from `src/utils/paths.ts`),
+  the per-platform hook-config file locations, and the master-instruction
+  file names.
+- `scripts/agent-setup.sh` (macOS/Linux) and `scripts/agent-setup.ps1`
+  (Windows) — the idempotent symlink templates that get installed.
+- `reference/hook-templates/` — per-platform session-start hook snippets.
+
+## When to Use
+
+Invoke when the user asks to "universalize", "consolidate", "unify", or
+"centralize" their agent setup, skills, commands, or instructions across more
+than one AI coding platform.
+
+## Workflow
+
+Follow these phases in order. Stop and ask whenever a decision is the user's
+to make.
+
+### Phase 1 — Choose scope
+
+Ask the user: **universalize the setup for the current project, or globally?**
+
+- `project` → `.agents/` lives at the project root; platform targets are the
+  project-relative directories in `reference/mapping.md`.
+- `global` → `.agents/` lives at `$HOME/.agents`; platform targets are the
+  `~/...` directories in `reference/mapping.md`.
+
+Record the chosen scope and the resolved base directory (`BASE`). Everything
+downstream uses `BASE`.
+
+### Phase 2 — Discover existing setups
+
+For each of the six platforms, check whether its directories exist under
+`BASE` (per `reference/mapping.md`). Treat a platform as "in use" if any of
+its skills/agents/commands dirs or its master-instruction file exists.
+
+For each in-use platform, enumerate items in its `skills`, `agents`,
+`workflows`, and `rules` source dirs. Some platforms collapse multiple types into one
+directory (Codex puts skills + agents + workflows in `.codex/skills`; Claude
+Code puts workflows in `.claude/skills`). Disambiguate an item's real type by
+reading its frontmatter / the `x-ai-agents-type` metadata this toolchain
+writes when wrapping items — never by directory alone.
+
+Report a discovery summary (platforms in use, item counts per type) before
+continuing.
+
+### Phase 3 — Build `.agents/`
+
+Create the unified layout under `BASE`:
+
+```text
+.agents/
+  skills/    agents/    commands/    rules/    hooks/
+```
+
+Copy discovered items into `.agents/{skills,agents,commands,rules}`. When the
+same-named item is found on more than one platform, copy it once: prefer the
+first platform discovered and warn about the collision rather than silently
+overwriting. Never wipe an existing `.agents/` — merge into it.
+
+#### Format normalization
+
+The unified store is markdown-only. Normalize as you copy:
+
+- **Rules.** Collect standard markdown rule files from the platforms that
+  support them — Claude, Gemini, and Antigravity use `<agent-dir>/rules`;
+  GitHub Copilot uses `.github/instructions` (see `reference/mapping.md`) —
+  into `.agents/rules/`. Codex and Windsurf have none. These are per-platform
+  rule files, distinct from the master instruction files consolidated in
+  Phase 4. Rules are **not** symlinked back (not in `__LINK_MAP__`); Phase 4
+  wires the whole dir into `AGENTS.md`.
+- **Workflows → commands.** Treat every platform's "workflow" items as the
+  universal `commands` type and place them in `.agents/commands/`. If a prior
+  run left a `.agents/workflows/` directory, move its contents into
+  `.agents/commands/` and remove the now-empty `workflows/` dir.
+- **Gemini commands → skills.** Gemini stores commands as TOML
+  (`.gemini/commands/*.toml`), which cannot be symlinked back as markdown.
+  Convert each Gemini `*.toml` into a skill: parse its `description` and
+  `prompt = """..."""` fields, then write `.agents/skills/<name>/SKILL.md`
+  with the prompt as the body and this frontmatter:
+
+  ```markdown
+  ---
+  name: <toml file name without extension>
+  description: <value of the TOML `description` field>
+  ---
+
+  <contents of the TOML `prompt` field>
+  ```
+
+  This is the reverse of `convertToGeminiCommandTOML` in
+  `src/utils/toml.ts`. Gemini workflows therefore land in `.agents/skills/`,
+  not `.agents/commands/`.
+
+### Phase 4 — Migrate master instructions
+
+Detect every master-instruction file present in scope:
+
+| Platform | File |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Codex / Antigravity / Windsurf | `AGENTS.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+The canonical target is root `AGENTS.md` (already the native master file for
+Codex, Antigravity, and Windsurf).
+
+- **None found** → create a minimal `AGENTS.md`.
+- **Exactly one found** → use it as `AGENTS.md` directly, no prompt.
+- **Two or more distinct files found** → STOP and ask the user how to
+  consolidate:
+  1. **Keep one** — show each detected file with a short preview / line
+     count; the user picks which becomes `AGENTS.md`.
+  2. **Merge all + trim** — concatenate every source, then de-duplicate
+     overlapping instructions into one coherent `AGENTS.md` (semantic
+     de-duplication, preserving every unique directive). Surface any
+     conflicting directives to the user instead of dropping them silently.
+
+After producing `AGENTS.md` (at `BASE`), **replace the entire contents** of
+each non-`AGENTS.md` master file with a single import line — its original
+content now lives in `AGENTS.md`:
+
+```text
+@AGENTS.md
+```
+
+Always create `AGENTS.md` (with the migrated content) before overwriting any
+master file, so nothing is lost. Platforms that natively read `AGENTS.md`
+(Codex, Antigravity, Windsurf) need no such file.
+
+**Wiring rules into masters.** Rules are not symlinked into any platform dir.
+Instead, import the whole `.agents/rules/` directory into `AGENTS.md` with a
+single directory import, so every platform that reads `AGENTS.md` (directly, or
+via its `@AGENTS.md` master import) picks them up:
+
+```text
+@.agents/rules/
+```
+
+Add this import only when `.agents/rules/` is non-empty.
+
+### Phase 5 — Install and run the setup script
+
+Pick the script for the host OS — `scripts/agent-setup.sh` on macOS/Linux,
+`scripts/agent-setup.ps1` on Windows — copy it into `BASE/.agents/hooks/`
+(keeping its extension), make it executable, and fill its two placeholders:
+
+- `__AGENTS_DIR__` → path to `BASE/.agents`: **relative** (`.agents`) for
+  project scope, **absolute** for global scope.
+- `__LINK_MAP__` → one `SRC_SUBDIR|DEST_DIR` line per (in-use platform × type),
+  using the scope-correct destination dirs from `reference/mapping.md`.
+  `SRC_SUBDIR` is `skills`, `agents`, or `commands`. Use **relative** dest
+  dirs (e.g. `.claude/skills`) for project scope and **absolute** dirs for
+  global scope. The script detects the mode from `__AGENTS_DIR__` and emits
+  relative symlinks for project scope, absolute for global.
+
+The script symlinks each item individually (not whole directories) so that
+collapsed targets like `.codex/skills` can receive skills + agents + commands
+merged together without conflict. It is idempotent and refuses to clobber a
+real (non-symlink) path.
+
+In **project scope** the script keeps the generated symlinks out of git by
+writing a single `.gitignore` per platform at its base dir (the parent of the
+target dirs, e.g. `.claude/.gitignore`) that lists each symlink subdir
+(`skills/`, `commands/`, …). Only the canonical `.agents/` content (which you
+commit) is version-controlled. Global scope skips this (it is not inside a
+repo).
+
+Once `.agents/` holds every item and the script is installed, **delete the
+original item files/directories at each platform source dir**. The canonical
+copy now lives in `.agents/`, so the originals are redundant — and because the
+symlink step refuses to overwrite a real path, it cannot link until the
+original is gone. Then run the setup script once to create the symlinks; every
+later session-start run re-applies them idempotently.
+
+### Phase 6 — Install session-start hooks
+
+For each in-use platform, register a session-start hook that runs the
+installed setup script in `BASE/.agents/hooks/` (`agent-setup.sh` on
+macOS/Linux, `agent-setup.ps1` on Windows), writing to the config file in
+`reference/mapping.md`:
+
+| Platform | Project file | Global file | Format |
+|---|---|---|---|
+| Claude Code | `.claude/settings.json` | `~/.claude/settings.json` | JSON |
+| Gemini / Antigravity | `.gemini/settings.json` | `~/.gemini/settings.json` | JSON |
+| Codex | `.codex/config.toml` | `~/.codex/config.toml` | TOML |
+| Windsurf | — | — | no session-start hook (skip) |
+| GitHub Copilot | `.github/hooks/agent-setup.json` | `~/.copilot/hooks/agent-setup.json` | JSON |
+
+Rules for every write:
+
+- **Append, never overwrite.** Parse the existing file, inject the hook entry
+  only if an equivalent one is absent, then write back. Preserve all other
+  keys and formatting as much as the format allows.
+- **Path style follows scope.** The hook command points at the setup script:
+  use a **relative** path (`.agents/hooks/agent-setup.sh`) for project scope
+  and an **absolute** path for global scope — matching how `__AGENTS_DIR__`
+  was filled.
+- Back up the file (`<file>.bak`) before the first modification.
+- Use the verified template for each platform in `reference/hook-templates/`
+  (`claude-code.json`, `gemini.json`, `codex.toml`, `copilot.json`).
+  **Windsurf has no session-start hook**, so it gets no recurring hook. Keep
+  its dirs in the Phase 5 `__LINK_MAP__` so the one-time setup run symlinks
+  them, but tell the user the shared `.agents/` will not auto-refresh on
+  Windsurf — they re-run the setup script manually to pick up later changes.
+  Codex prompts for a trust review of project hooks on first use.
+
+### Phase 7 — Report
+
+Summarize: scope, platforms processed, items consolidated per type, how
+master instructions were resolved, which hooks were installed (and which were
+skipped/unverified), and any collisions or backups created.
+
+## Constraints
+
+- Append-only for existing config (settings/hook) files; back up first.
+  Master instruction files are the exception: replace their contents with the
+  `@AGENTS.md` import once the content is migrated into `AGENTS.md`.
+- Per-item symlinks, never whole-directory, never clobber real paths.
+- Do not fabricate hook schemas; verify unverified platforms at runtime.
+- Do not modify this repo's `src/`, CLI, or `paths.ts`.