@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/red-statusline/HOST-NOTES.md

@@ -0,0 +1,180 @@
+# Host Notes
+
+Reference material for the host branches in `SKILL.md`. Read only the section for
+the branch you are wiring; these notes preserve the recipes, line-shape rules,
+and rationale outside the hot path.
+
+## Shared Architecture And Line Shapes
+
+Install or inspect the RedSkills statusline for this repository. The shared producer renders the project name, branch, model/context data when the host provides it, repo counters, and live AFK state. **The two hosts get two shapes (per-runner split, ADR 0003):**
+
+- **Claude Code — multi-line.** Claude Code's `statusLine` renders multiple rows, so the themed producer emits a repo-global **header line** — always shown, even with no live workers: project (branch) + version, model·effort + context, open PRs + open issues, local diff vs `origin/main`, and (Pro/Max only, when the payload exposes them) the 5-hour and weekly usage windows `5h=…% 7d=…%` — **then one line per live AFK worker**. The worker line is a **terse, colored `k=v` form** that reads as a visual sibling of the header — every token follows the header's `key=value` colour convention:
+
+  ```
+  w82UX  run=claude opus high  iss=1173  tests  00:04:41  loc=+10 -11  tks=34k  tls=11 rsn=13 txt=0
+  ```
+
+  Every `k=v` key on this line is **exactly 3 letters** (house rule). The `wID` is **bold + red**; then `run=<runner> <model> <effort>` (model shortened, e.g. `claude-opus-4-8` → `opus`; the effort word is omitted when unavailable), `iss=<issue-number>` (the bare ISSUE NUMBER from the worker's `current.number`, populated for BOTH `/afk` and `/go` lanes — not a `done/total` counter), the bare `<phase>` word (no `phase:` prefix, no standalone `#<n>` token), the required `HH:MM:SS` elapsed, `loc=+A -R`, `tks=<humanized>` (SI k/M/B token total), and the vitals as INDIVIDUAL 3-letter `k=v` pairs `tls=<t> rsn=<r> txt=<x>` (never a nested `stats=…:…` blob). The `/afk monitor` dashboard uses the same vitals vocabulary (`tls`/`rsn`/`txt`) while keeping its fuller row shape. The truncated issue TITLE, the live `activity`, the `[live]`/`[quiet]` badge, `wait`, and `log` are **dropped** here — that verbosity stays on the fuller `/afk monitor` line. The two surfaces share only the per-worker FIELD DATA (`workerFields`), never a renderer, so the terse statusline form never bleeds into the monitor. Zero live workers → only the header line.
+
+  The **`/afk monitor` dashboard keeps its fuller per-worker row** (title, `[live]`/`[quiet]`, `wait`, `log`) — it is a full dashboard, not a compact statusline — but its vitals tokens are the same `tls`/`rsn`/`txt` vocabulary as the statusline.
+
+  For an on-demand decode table, run `red-skills-dev statusline --legend` or `red-skills-dev monitor --legend`. The legend prints `token / name / gloss` rows and exits without rendering the live statusline or monitor surface.
+- **Codex — single line.** The `tui.status_line` footer is single-line only, so the plain producer stays ONE aggregate line (project · model · context · usage · repo counts · the AFK block). The multi-line layout is Claude-Code-only.
+
+The AFK rows are quiet when no worker is active. Hosts that cannot run a command-backed statusline still get a useful native footer plus `/afk monitor` for live AFK visibility.
+
+**Host capabilities differ; the product architecture should not.** Treat the RedSkills statusline as:
+
+1. A shared producer: the dev bundle's `statusline` subcommand.
+2. Host adapters: Claude Code's command-backed `statusLine`; Codex's global `tui.status_line` list and plugin `SessionStart` hook.
+3. Fallback visibility: `/afk monitor`, which works when a host has no command-backed footer.
+
+This mirrors how Codex itself organizes customization: skills define reusable workflows, plugins distribute skills plus hooks/MCP/apps, `config.toml` stores host settings, and hooks attach lifecycle behavior next to the active plugin/config layer. Keep RedSkills logic in the bundle and keep host-specific wiring in the host sections below.
+
+## Claude Code Adapter Recipe
+
+1. Inspect the repo: `.red/config.yaml`, `.claude/settings.json`, and whether `jq` is available.
+
+2. **Early exit — opt-out:** if `.red/config.yaml` has top-level `statusline: false` or nested `afk.statusline: false`, stop and tell the user it is disabled. Do not proceed.
+
+3. **Early exit — already configured:** if `.claude/settings.json` already has `statusLine`, do not overwrite it unless the user explicitly asked to replace it (then replace only `statusLine`, preserving all other keys).
+
+4. Write the RedSkills statusline:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "sh -c 'N=$(command -v node 2>/dev/null || ls -1 /usr/local/bin/node /opt/homebrew/bin/node /usr/bin/node \"$HOME\"/.volta/bin/node \"$HOME\"/.asdf/shims/node \"$HOME\"/.nodenv/shims/node \"$HOME\"/.nvm/versions/node/*/bin/node \"$HOME\"/.local/share/fnm/node-versions/*/installation/bin/node \"$HOME\"/.fnm/node-versions/*/installation/bin/node 2>/dev/null | sort -V | tail -1); b=$(ls -1 \"$HOME\"/.cache/red-skills/bundles/dev-*.bundle.min.mjs 2>/dev/null | sort -V | tail -1); [ -z \"$b\" ] && b=$(ls -1 \"$HOME\"/.claude/plugins/cache/red-skills/dev/*/skills/engineering/afk/bin/afk.mjs 2>/dev/null | sort -V | tail -1); [ -n \"$b\" ] && [ -n \"$N\" ] && exec \"$N\" \"$b\" statusline'",
+    "refreshInterval": 60
+  }
+}
+```
+
+**Why this shape (cached-bundle-first, not `$CLAUDE_PLUGIN_ROOT`, not `afk.mjs` directly):** the command above is cached-bundle-first by design (ADR 0084) — never alter it to fetch synchronously in the render path.
+
+Use a 60s refresh interval because the producer reads cached state: 5s ticks burn CPU and repeat calls without new information at that cadence, while 60s matches the real rate of change of fleet/PR state.
+
+Use `jq` to merge when `.claude/settings.json` already exists; create `.claude/`
+and a fresh file when it is missing. Keep unrelated settings intact.
+
+5. Verify: confirm `.claude/settings.json` is valid JSON and has `.statusLine.command`. Unlike the old `$CLAUDE_PLUGIN_ROOT` form, you **can** prove this one renders by piping a minimal session JSON into the **same `sh -c '…'` command from step 4** (no need to re-type it):
+
+```bash
+printf '{"workspace":{"project_dir":"%s"},"model":{"display_name":"Opus"}}' "$PWD" \
+  | <the step-4 statusLine command>
+```
+
+It should print the themed **header line** (e.g. `» red-skills (main) v… Opus·high …`); when AFK workers are live it prints one additional row per worker below it. Under `NO_COLOR` the same command collapses to the single-line plain form `red-skills (main) · Opus·high · …`.
+
+## Claude Code Rationale
+
+**Why this shape, not `$CLAUDE_PLUGIN_ROOT`.** Claude Code does **not** export
+`CLAUDE_PLUGIN_ROOT` (nor `CLAUDE_PROJECT_DIR`) to a `statusLine` command — those
+are only set for plugin hooks and MCP/LSP subprocesses. A statusLine that
+references `$CLAUDE_PLUGIN_ROOT` expands it to an empty string and fails with
+`Cannot find module` — the statusline then silently renders blank.
+
+**Why resolve `node` explicitly, not bare `exec node`.** Claude Code runs the
+`statusLine` command in a **non-interactive shell** that does not source the
+user's `~/.bashrc`/`~/.zshrc`, so a Node installed through a **version manager**
+(nvm, fnm, volta, asdf, nodenv, …) is not on `PATH` — a bare `exec node …` then
+fails with `node: not found` (exit 127) and the statusline silently renders
+blank. The command resolves the interpreter itself, manager-agnostic:
+**`command -v node` first** — which already covers every host with Node on `PATH`
+(system package, Homebrew, or no version manager at all) — and only when that
+misses does it scan the common install roots (nvm, fnm, volta, asdf, nodenv,
+Homebrew, `/usr/local`, `/usr`), newest wins. So the line renders regardless of
+how Node was installed or how the host shell was launched.
+
+**Why the cached bundle, not `afk.mjs` directly.** Since ADR 0038, the installed
+`afk.mjs` is a tiny **launcher that fetches** the real runtime bundle from the
+GitHub release on first use (caching it at
+`~/.cache/red-skills/bundles/dev-<version>.bundle.min.mjs`). Pointing the
+statusLine straight at the launcher means **every plugin update** lands a new
+version whose bundle is not cached yet, so the launcher tries a **synchronous
+network download inside the statusline render** — which blows the render's tight
+timeout (blank statusline), or fails outright if that version's release asset is
+not published yet. The command instead runs the **highest-version
+already-fetched bundle** (`ls -1 …/.cache/red-skills/bundles/dev-*.bundle.min.mjs | sort -V | tail -1`
+— `sort -V` picks the highest semver, NOT `ls -t` which picks newest-by-mtime and
+can resolve an OLD version when an older dir was touched/re-extracted more recently) —
+no network in the hot path, so an update never blanks the line; it keeps showing
+the last good bundle until a normal `afk` run (or a SessionStart pre-fetch)
+caches the new one. It falls back to the launcher only when the cache is empty
+(first-ever install), to bootstrap. The project root is **not** passed as an
+argument: the AFK `statusline` subcommand reads it from `workspace.project_dir`
+in the JSON Claude Code pipes on stdin, which the `sh -c` wrapper forwards
+intact.
+
+This respects ADR 0084: the documented command stays cached-bundle-first and
+never fetches synchronously in a render path.
+
+## Codex Adapter Recipe
+
+Codex configures its footer through the `tui.status_line` key in `config.toml`
+— an ordered list of **built-in** item identifiers (`project`, `git-branch`,
+`model-with-reasoning`, `context-remaining`, `task-progress`, `current-dir`,
+…). When unset, Codex currently uses `["model-with-reasoning",
+"context-remaining", "current-dir"]`; set it to `[]` to hide the footer.
+This skill offers the **global** `~/.codex/config.toml` path because the footer
+is a personal host preference, not repo state. There is no command hook, so the
+shared RedSkills `statusline` producer cannot be injected into the footer yet.
+
+Codex has a native `/statusline` command for picking and reordering these
+footer items and persisting them to `config.toml`. The dev bundle also exposes
+an explicit inspector/fixer:
+
+```bash
+red-skills-dev codex-statusline
+red-skills-dev codex-statusline --fix
+```
+
+The inspector reports the active `tui.status_line`, flags a missing
+`task-progress` widget, prints the recommended order, and reminds the operator
+that rich AFK worker state still lives in `/afk monitor`. `--fix` is explicit:
+it appends `task-progress` to an existing visible footer or installs the
+recommended footer when `status_line` is absent. If the user already has a
+custom `tui.status_line`, preserve it unless they explicitly ask for `--fix`;
+that custom value is the operator's host preference, not repo state.
+
+Offer to set a useful footer (note: this is **global** Codex config, not
+per-repo like the Claude path):
+
+```toml
+[tui]
+status_line = ["project", "git-branch", "model-with-reasoning", "context-remaining", "task-progress"]
+```
+
+**Surviving Codex config resets.** A global `tui.status_line` gets dropped when Codex rewrites `~/.codex/config.toml`, but the dev plugin's Codex `SessionStart` hook re-asserts it so a reset self-heals on the next session start — why and how (the additive, atomic, absent-only re-write) is described below.
+
+This is intentionally host-global and plugin-gated. Codex stores footer
+preferences in `~/.codex/config.toml`, while RedSkills gates global hook side
+effects on the repo's `.red/config.yaml` `plugins.dev.enabled: true` flag. That
+keeps the installed plugin available everywhere but inert outside opted-in
+repos, matching the rest of the RedSkills hook model.
+
+For live AFK visibility under Codex, `/afk monitor` remains the canonical
+dashboard. Normal `/afk run` launches and `/afk fleet` launches also try to
+attach one read-only Codex monitor agent when the host exposes a sub-agent
+primitive; the prompt comes from `afk codex-monitor-agent --mode run|fleet`.
+When the primitive is unavailable, Codex falls back to the monitor dashboard.
+When Codex ships a command-backed statusline (openai/codex#17827 / #20244), this
+skill can add a `{ type = "command", command = … }` entry pointing at the same
+AFK bundle so the line matches Claude Code's.
+
+## Codex Rationale
+
+That global `tui.status_line` gets dropped whenever Codex rewrites
+`~/.codex/config.toml` (e.g. re-syncing plugin `[hooks.state]` on update),
+blanking the footer "every update". The dev plugin's Codex `SessionStart` hook
+re-asserts it: `hooks/ensure-codex-statusline.mjs` inserts `status_line` **only
+when absent** (never clobbers an operator's own value) via an **atomic** write
+(temp + rename — a race with Codex's writer can lose the update but never corrupt
+the file). So a reset self-heals on the next session start. The hook is additive
+and idempotent; disable it by removing the second `SessionStart` entry in
+`hooks/codex.hooks.json`.
+
+## OpenCode Adapter
+
+Nothing to install: OpenCode is an AFK API-auth runner lane (`--runner opencode`), not an interactive host UI, so it has no footer/statusline adapter — observe it through `/afk monitor`, `/afk dashboard`, and Actions output like any other runner.

package/skills/engineering/red-statusline/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: red-statusline
+description: Install or inspect the RedSkills statusline for the active host. RedSkills has one shared `statusline` producer in the dev bundle; Claude Code wires it through `.claude/settings.json` as a command-backed statusLine, while Codex configures the built-in `tui.status_line` footer and the dev plugin's SessionStart self-heal hook. Preserves existing config unless replacement is explicitly requested.
+disable-model-invocation: true
+---
+
+# Statusline
+
+**Wire the RedSkills statusline surface for the current host — stop as soon as a gate condition is met.** Keep the host branch hot here; read [HOST-NOTES.md](HOST-NOTES.md) only for the exact adapter recipe, shared line shape, or rationale needed by the selected host.
+
+<what-to-do>
+
+## 1. Identify The Host
+
+**Pick one branch.** Use Claude Code when `.claude/` or Claude plugin state is the active surface, Codex when the active client is Codex CLI, and OpenCode only when the user asks about the OpenCode runner lane.
+
+**Respect explicit intent.** Install only when the user asks to install, fix, replace, or configure. Otherwise inspect and report the current state.
+
+## 2. Claude Code
+
+1. Inspect `.red/config.yaml`, `.claude/settings.json`, and whether `jq` is available.
+2. **Opt-out gate** — if `.red/config.yaml` has top-level `statusline: false` or nested `afk.statusline: false`, stop and tell the user it is disabled.
+3. **Existing-config gate** — if `.claude/settings.json` already has `statusLine`, preserve it unless the user explicitly asked to replace it. Replacement touches only `statusLine`; keep every other key.
+4. **Apply the adapter recipe** — read [HOST-NOTES.md](HOST-NOTES.md#claude-code-adapter-recipe), then write or merge the cached-bundle-first `statusLine` block exactly as documented there.
+5. **Verify the write** — confirm `.claude/settings.json` is valid JSON, contains `.statusLine.command`, and renders by piping minimal session JSON into the same command from the recipe.
+
+## 3. Codex
+
+1. Inspect the active `~/.codex/config.toml` footer preference with `red-skills-dev codex-statusline`.
+2. **Preserve host preference** — if `tui.status_line` is already custom, leave it alone unless the user explicitly asks to fix or replace it.
+3. **Apply the adapter recipe only on request** — read [HOST-NOTES.md](HOST-NOTES.md#codex-adapter-recipe), then run the explicit fixer or write the recommended global footer. Treat this as host-global config, not repo state.
+4. **Report AFK visibility honestly** — Codex gets native footer widgets plus `/afk monitor`; it cannot inject the shared command-backed producer into the footer yet.
+
+## 4. OpenCode
+
+**Install nothing.** OpenCode is a runner lane, not an interactive host UI with a footer adapter. Point the user to `/afk monitor`, `/afk dashboard`, and Actions output. The full note is in [HOST-NOTES.md](HOST-NOTES.md#opencode-adapter).
+
+## 5. Finish
+
+Tell the user which host branch you used, what changed or why nothing changed, and how to observe live AFK state.
+
+</what-to-do>
+
+<supporting-info>
+
+## Reference Map
+
+- **Shared architecture and line shapes:** [HOST-NOTES.md](HOST-NOTES.md#shared-architecture-and-line-shapes).
+- **Claude Code command-backed adapter:** [HOST-NOTES.md](HOST-NOTES.md#claude-code-adapter-recipe).
+- **Codex native footer adapter:** [HOST-NOTES.md](HOST-NOTES.md#codex-adapter-recipe).
+- **OpenCode no-install note:** [HOST-NOTES.md](HOST-NOTES.md#opencode-adapter).
+
+## Invocation Notes
+
+- Invoke as `/red-statusline` (Claude Code) or `$red-statusline` (Codex). Wire the host you are running under; do not imply the statusline feature belongs to only one client.
+- `/red-setup` may offer the Claude Code command-backed adapter during project bootstrap. Under Codex, use this skill to inspect or configure the native footer path.
+
+</supporting-info>

package/skills/engineering/report-bug/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: report-bug
+description: Interview the user about a bug they hit, then file a structured `type:bug needs-triage` issue on the project tracker. Pulls seed material from the conversation context when invoked with no arguments, or from the argument when one is provided. Use when the user says "report a bug", "open a bug", "this is broken — file it", "/report-bug ...", or otherwise wants a bug captured on the tracker without going through full triage themselves.
+argument-hint: "[symptom — leave empty to seed from conversation]"
+---
+
+<what-to-do>
+
+**You file, /triage routes. Never pre-label or guess priority.**
+
+Conduct a short, focused interview that fills in every field of the issue template in `<supporting-info>`, then open the issue on the project tracker.
+
+**Boot behavior (turn 1):**
+
+The argument is optional.
+
+- **Argument present** → treat it as the seed for "What's happening". Emit a single-line receipt confirming the seed (`Seed: <first 80 chars>…`), then jump to the next missing field.
+- **Argument empty** → silently mine the current conversation context for: what the user was doing, error messages, file paths, stack traces, recent commands, anything that smells like the symptom of the bug. Emit a one-line receipt (`Seeded from conversation: <one-sentence summary>.`) and start the interview with whichever field is still least clear.
+- **No useful context AND no argument** → open with `Q01: What's the bug? Describe what you observed.`
+
+**The loop:**
+
+1. Pick the next unresolved field from the template in `<supporting-info>`.
+2. Ask **one** question using the format below. Include a recommended answer or `[branches]` whenever the field has a finite shape (severity, repro type), otherwise ask open-ended.
+3. Wait for the user's reply. Do not stack questions.
+4. When their answer changes the picture (e.g. severity escalates from "low" to "blocker" because they mention prod), re-evaluate before asking the next question.
+5. Once every field is filled, summarise the issue as it will be filed (title + body), ask `Q##: Open this issue on the tracker? (y/n / edit)`. On `y` or `yes`, proceed. On `edit`, ask which field to revise. On `n`, abort cleanly.
+
+**Filing:**
+
+1. Build the issue title per **Title rules** in `<supporting-info>` (lowercase, ≤72 chars, imperative/noun phrase derived from "What's happening").
+2. Render the body using the exact template in `<supporting-info>`. Leave no `[…]` placeholders.
+3. `gh issue create --title "<title>" --body "<body>" --label type:bug --label needs-triage`. Pass body via heredoc/tempfile, not inline, to preserve newlines.
+4. Read the URL from the gh output and present it to the user with one of: open URL, run `/triage`, or stop.
+
+**Hard rules:**
+
+- ❌ Do **not** invent reproduction steps, error text, or file paths. If the user can't supply them, write `no clean repro yet` and `unknown` rather than fabricating.
+- ❌ Do **not** apply any label beyond `type:bug` + `needs-triage` — see **Labels** in `<supporting-info>`; `/triage` owns priority, slice tagging, and agent-readiness.
+- ❌ Do **not** close the issue, comment after creation, or run any AFK action. This skill ends with the URL.
+- ❌ Do **not** open more than one issue per invocation. If the user describes two unrelated bugs, suggest running `/report-bug` again for the second.
+- ✅ **Do** number every question `Q##:` (zero-padded, session-scoped, same convention as `/start`).
+- ✅ **Do** use `gh` (not the GitHub web UI) — the user invoked a CLI skill, they want the issue handle in the terminal.
+- ✅ **Do** sanitise the body before filing: strip ANSI escapes, mask anything that looks like a secret (API keys, tokens) — when in doubt, ask the user to confirm.
+- ✅ **Do** route the user to `/triage` after creating the issue — see **After creation** in `<supporting-info>` for the exact receipt. The reporter's job ends at "captured".
+
+**Question format template:**
+
+> **Q##:** [the question]
+> **Branches:** _(omit when the field is open-ended free text)_
+> (a) [answer option A]
+> (b) [answer option B]
+> [if more options, add more branches]
+> **Recommend:** (a), because [one-sentence reason].
+> *(answer, redirect, or push back — I'll wait)*
+
+</what-to-do>
+
+<supporting-info>
+
+## Issue body template
+
+````markdown
+## What's happening
+
+<one to three sentences describing the observed behaviour, verbatim from the user where possible>
+
+## What should happen instead
+
+<one or two sentences describing the expected behaviour>
+
+## Reproduction
+
+<numbered steps, or `no clean repro yet — observed in <context>`>
+
+## Context
+
+- **when:** <date/time the user noticed, ISO format if known>
+- **where:** <file path, route, URL, component name>
+- **what i was doing:** <one sentence>
+- **environment:** <OS, runtime version, branch/commit if relevant; "n/a" otherwise>
+
+## Severity
+
+<one of: blocker | high | medium | low | unknown>
+
+## Source
+
+Filed via `/report-bug`. <"Seeded from inline argument." | "Seeded from conversation context." | "No prior context.">
+````
+
+Fields that the interview must fill, in order of priority:
+
+1. **What's happening** — symptom, observed behaviour.
+2. **What should happen instead** — expected behaviour. If user can't articulate, ask "what made you think this was a bug and not the design?"
+3. **Reproduction** — numbered steps if the user can produce them; otherwise the rough conditions (`no clean repro yet — observed when X`).
+4. **Context** — `when`, `where`, `what i was doing`, `environment`. Pull from conversation if mined; ask only for what's missing.
+5. **Severity** — branches: blocker / high / medium / low / unknown.
+6. **Source** — auto-filled from boot mode.
+
+## Severity branches
+
+Use these when asking `Q##: Severity?`:
+
+- **blocker** — production is down or data is at risk now.
+- **high** — a core flow is broken; workaround is awkward or partial.
+- **medium** — broken in a non-core path or has a clean workaround.
+- **low** — cosmetic, minor, or rare edge.
+- **unknown** — pick this freely; `/triage` will assign properly.
+
+## Title rules
+
+- Lowercase, ≤72 chars.
+- Imperative or noun phrase: `monitor crashes on empty history.jsonl`, `wiki ingest mangles assets folder`, `afk loses claim when worker_id collides`.
+- Avoid prefixes like `Bug:`, `[BUG]`, `Issue:` — the `type:bug` label already conveys this.
+- Avoid clickbait — `WTF`, `???`, `please fix` waste tokens for the next reader.
+
+## Labels
+
+Apply exactly two on creation:
+
+- `type:bug`
+- `needs-triage`
+
+The `/triage` skill is responsible for adding the rest (`priority:*`, `prd:*`, eventually `ready-for-agent`). Pre-emptively labelling here breaks that contract.
+
+If `type:bug` or `needs-triage` don't exist in the repo (fresh checkout), stop and tell the user to run `/red-setup` first — same precondition as `/triage`.
+
+## Conversation-mining heuristic
+
+When invoked with no argument, scan the conversation transcript (most recent ~50 turns) for:
+
+- Error messages, stack traces, non-zero exit codes.
+- File paths the user just opened or edited.
+- Recently failing test names.
+- Commands the user ran that produced unexpected output.
+- Explicit phrases: "this is weird", "shouldn't this …", "why is it doing …", "I expected … but got …".
+
+Pick the strongest signal as the seed for "What's happening" and surface what's still missing for the rest of the fields.
+
+If nothing useful is in the transcript, say so in the receipt (`Seeded from conversation: no clear symptom found, starting open.`) and open with `Q01`.
+
+## After creation
+
+When the issue is filed, print exactly:
+
+```
+✓ filed #<N>: <title>
+  <url>
+  next: /triage to assign priority and route to /afk.
+```
+
+Then stop. Do not call `/triage` yourself unless the user explicitly asks.
+
+</supporting-info>

package/skills/engineering/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: resolving-merge-conflicts
+description: Guided merge-conflict resolution loop. Inspect state → find each side's intent → resolve every hunk preserving both intents → run the project's checks. Never abort. Use when a merge, rebase, or cherry-pick leaves conflict markers in tracked files.
+---
+
+# Resolving Merge Conflicts
+
+**Intent preservation is the only goal — not picking a winner.** Each side touched that line for a reason; your job is to honour both reasons in the resolved output.
+
+<what-to-do>
+
+### Step 1 — Inspect state
+
+Before touching any file, understand what kind of operation produced the conflicts:
+
+```bash
+git status          # lists every file with conflict markers
+git log --merge     # shows the two commits being reconciled
+```
+
+Identify the operation type — `MERGE_HEAD` means a merge, `REBASE_HEAD` means a rebase, `CHERRY_PICK_HEAD` means a cherry-pick. The semantics differ:
+
+- **Merge**: two independent branches are being joined. Both sides' changes are equally valid.
+- **Rebase**: commits are being replayed on top of a new base. The "ours" side is the base, the "theirs" side is the patch being applied.
+- **Cherry-pick**: a single commit is being applied. "Theirs" is the patch; "ours" is the current state.
+
+### Step 2 — Find each side's primary source and original intent
+
+For each conflicted file, read the full diff for each branch **before** looking at the conflict markers. Use:
+
+```bash
+git diff ORIG_HEAD...HEAD -- <file>     # what "ours" changed vs the merge base
+git diff MERGE_HEAD...HEAD -- <file>    # what "theirs" changed vs the merge base (merge)
+git show REBASE_HEAD -- <file>          # theirs during rebase
+```
+
+For each conflict block, answer two questions before resolving it:
+
+1. *Why did "ours" change this?* — find the commit message, PR, or issue that explains it.
+2. *Why did "theirs" change this?* — same.
+
+**Never resolve a hunk you cannot explain both sides of.** If the intent is unclear, read the surrounding commit history (`git log --oneline -10 -- <file>`) or the linked PR/issue rather than guessing.
+
+### Step 3 — Resolve every hunk, preserving both intents
+
+For each conflict block (`<<<<<<<` … `=======` … `>>>>>>>`):
+
+1. **If both sides changed different things** (different lines, no semantic overlap): include both changes. Edit the block so both modifications appear in the output; order them to maintain the file's logical flow.
+2. **If both sides changed the same lines** (semantic overlap): produce a version that achieves both intentions. Write the merged result explicitly — do not just pick one side.
+3. **If one side deleted what the other modified**: include the modification, not the deletion, unless the deletion's intent makes the modification meaningless. Explain your reasoning in the commit message.
+
+Hard rules:
+
+- ❌ Do **not** run `git merge --abort`, `git rebase --abort`, or `git cherry-pick --abort`. Aborting discards work; resolve instead.
+- ❌ Do **not** accept "ours" or "theirs" wholesale with `git checkout --ours` / `--theirs` without verifying the other side's intent is preserved.
+- ❌ Do **not** leave conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) in any file when you are done.
+- ✅ **Do** remove the markers and all three sections, replacing them with a single coherent resolution.
+
+### Step 4 — Discover and run the project's automated checks
+
+After resolving all hunks, find the project's test and lint commands. Look for them in this order:
+
+1. `package.json` → `scripts` block (`test`, `lint`, `typecheck`, `build`)
+2. `Makefile` → `make test`, `make lint`
+3. `README.md` → "how to run tests" section
+4. CI config (`.github/workflows/`, `.circleci/config.yml`, etc.) — the commands the pipeline runs
+
+Run every check that covers the conflicted files. A resolution that breaks a test is not a resolution.
+
+### Step 5 — Complete the operation
+
+Once all conflicts are resolved and all checks pass:
+
+```bash
+git add -- <each resolved file>   # stage by name, never git add -A
+git merge --continue              # or git rebase --continue / git cherry-pick --continue
+```
+
+Write a commit message that names both intents that were reconciled, e.g.:
+
+> "Merge: preserve both the cache-invalidation fix (#42) and the retry-backoff refactor (#67)"
+
+</what-to-do>
+
+<supporting-info>
+
+## Reading conflict markers
+
+```
+<<<<<<< HEAD (ours)
+  const timeout = 5000
+=======
+  const timeout = retryConfig.timeoutMs
+>>>>>>> feature/retry-backoff (theirs)
+```
+
+- `HEAD` / `ours` — the branch you were on when you ran `git merge`/`git cherry-pick`, or the new base during a rebase.
+- `theirs` — the branch being merged in, the patch being applied, or the commit being replayed.
+- The merge base (the common ancestor) is visible via `git merge-base HEAD MERGE_HEAD` and can be checked out to a temp file with `git show $(git merge-base HEAD MERGE_HEAD):<file>`.
+
+## Diff3 style for three-way context
+
+Enable extended conflict markers to see the merge-base version alongside both sides:
+
+```bash
+git config merge.conflictstyle diff3
+```
+
+With `diff3`, conflict blocks show three sections:
+
+```
+<<<<<<< HEAD
+  const timeout = 5000
+||||||| merged common ancestors
+  const timeout = 3000
+=======
+  const timeout = retryConfig.timeoutMs
+>>>>>>> feature/retry-backoff
+```
+
+The middle `|||||||` section is the merge base — it shows what the file looked like before either branch touched it. This makes each side's intent immediately clear.
+
+## When a file is marked "both deleted" or "both added"
+
+- **Both deleted**: the file is already gone on both sides. Stage with `git rm -- <file>` and move on.
+- **Both added** (same path, different content): treat the whole file as one large conflict block. Follow Step 3 to produce a single merged file.
+
+## When a binary file conflicts
+
+Git cannot produce text conflict markers for binary files. Inspect the two versions:
+
+```bash
+git show HEAD:<file> > /tmp/ours.<ext>
+git show MERGE_HEAD:<file> > /tmp/theirs.<ext>
+```
+
+Choose the correct version or produce a new merged binary through the appropriate tool (image editor, compiled output, etc.), then stage the result.
+
+## Handling renames
+
+If one side renamed a file while the other modified it, Git may detect this as `both modified` on the **new** path. Confirm with `git status` and check that the resolved file lives at the correct path before staging.
+
+</supporting-info>