showdar-skills 0.2.0

package/skills/showdar-design/references/release-readiness.md

@@ -0,0 +1,12 @@
+# Design release readiness
+
+Treat UI as release behavior when it changes navigation, forms, accessibility, loading/error states, or platform integration.
+
+- Test the critical task at narrow and wide layouts with long real content, localization-like strings, and large text settings.
+- Verify loading, empty, error, retry, disabled, offline, focus, keyboard, and reduced-motion states; a screenshot of the happy path is not proof.
+- Confirm semantic roles, accessible names, focus order, contrast, touch target size, and screen-reader announcements on the affected platform.
+- Check image/font licensing and loading behavior, metadata/social previews for web, and bundle/performance impact for large media.
+- For native or desktop UI, test back behavior, safe areas, window resizing, permissions, and clean install/update paths as applicable.
+- Record unverified devices, browsers, OS versions, and external design approvals instead of implying they passed.
+
+Release readiness means the user task remains understandable and recoverable without animation or ideal content.

package/skills/showdar-design/references/responsive.md

@@ -0,0 +1,5 @@
+# Responsive design
+
+Responsive behavior is a priority decision, not proportional shrinking. Define what remains, moves, collapses, scrolls, or becomes a different pattern at narrow widths. Preserve task completion and reading order.
+
+Test at content-driven breakpoints, long translations, browser zoom, text scaling, keyboard presence, and safe areas. Avoid device-name branching when layout constraints can express the rule.

package/skills/showdar-design/references/security.md

@@ -0,0 +1,12 @@
+# Design security boundaries
+
+UI is an input and disclosure boundary. Visual polish must not weaken authorization, secret handling, or safe rendering.
+
+- Client-side visibility, disabled buttons, and route guards are UX; authoritative authorization belongs in the server, domain, or native owner.
+- Treat user content, URLs, filenames, markdown, HTML, and rich text as untrusted. Use the repository’s safe renderer and escaping boundary.
+- Do not display tokens, secret values, private identifiers, or debug payloads merely to make a screen easier to diagnose.
+- Make destructive actions explicit, scoped, and recoverable. Show target, consequence, confirmation, and completion/error state.
+- Avoid autocomplete or persistence that stores sensitive values outside the intended secure owner.
+- For desktop IPC and mobile deep links, validate and constrain every value that crosses from the UI into privileged code.
+
+Verify with an accessibility and security review of the changed path; a visually hidden element is not a security control.

package/skills/showdar-design/references/visual-hierarchy.md

@@ -0,0 +1,7 @@
+# Visual hierarchy
+
+Hierarchy should communicate importance before decoration. Establish one dominant focal point, a clear reading order, and predictable levels for page title, section title, body, metadata, and actions. Use size, weight, spacing, position, and contrast together; do not solve hierarchy by adding more colors.
+
+Dense tools need compact rhythm and aligned data. Editorial experiences can use larger type and whitespace. Mobile screens need fewer simultaneous hierarchy levels because viewport and attention are constrained.
+
+Audit at 50% zoom or blurred view: the primary action, primary content, and major sections should still be obvious.

package/skills/showdar-design/scripts/lib/csv.mjs

@@ -0,0 +1,40 @@
+export function parseCsv(text, { strict = true } = {}) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let quoted = false;
+  const pushRow = () => { row.push(field); rows.push(row); row = []; field = ''; };
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') { field += '"'; i += 1; }
+      else if (ch === '"') quoted = false;
+      else field += ch;
+      continue;
+    }
+    if (ch === '"') quoted = true;
+    else if (ch === ',') { row.push(field); field = ''; }
+    else if (ch === '\n') pushRow();
+    else if (ch !== '\r') field += ch;
+  }
+  if (quoted && strict) throw new Error('unterminated quoted field');
+  if (field.length || row.length) pushRow();
+  const clean = rows.filter((r) => r.some((value) => value.trim() !== ''));
+  if (!clean.length) return [];
+  const headers = clean[0].map((value) => value.trim());
+  if (strict && headers.some((header) => !header)) throw new Error('blank CSV header');
+  if (strict && new Set(headers.map((header) => header.toLowerCase())).size !== headers.length) throw new Error('duplicate CSV header');
+  return clean.slice(1).map((values) => {
+    if (strict && values.length !== headers.length) throw new Error(`CSV column count ${values.length} does not match header count ${headers.length}`);
+    return Object.fromEntries(headers.map((header, index) => [header, values[index] ?? '']));
+  });
+}
+
+export function stringifyCsv(rows, headers = rows.length ? Object.keys(rows[0]) : []) {
+  const escape = (value) => {
+    const raw = String(value ?? '');
+    if (!/[",\n\r]/.test(raw)) return raw;
+    return `"${raw.replaceAll('"', '""')}"`;
+  };
+  return [headers.map(escape).join(','), ...rows.map((row) => headers.map((header) => escape(row[header])).join(','))].join('\n') + '\n';
+}

package/skills/showdar-design/scripts/lib/rank.mjs

@@ -0,0 +1,35 @@
+const STOP = new Set(['a','an','and','are','as','at','be','by','for','from','in','is','it','of','on','or','the','to','use','with']);
+
+export function tokenize(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[^a-z0-9+#.-]+/g, ' ')
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 1 && !STOP.has(token));
+}
+
+export function rankRows(rows, query, fieldsOrOptions = []) {
+  const options = Array.isArray(fieldsOrOptions) ? { fields: fieldsOrOptions } : (fieldsOrOptions ?? {});
+  const fields = options.fields ?? [];
+  const weights = options.weights ?? {};
+  const queryTokens = tokenize(query);
+  const querySet = new Set(queryTokens);
+  return rows.map((row, index) => {
+    const selected = fields.length ? fields : Object.keys(row);
+    const fieldTokens = selected.flatMap((field) => tokenize(row[field]));
+    const fieldSet = new Set(fieldTokens);
+    let score = 0;
+    const matchedTokens = [];
+    for (const token of querySet) {
+      const exactField = selected.find((field) => tokenize(row[field]).includes(token));
+      if (exactField) { score += 4 * Number(weights[exactField] ?? 1); matchedTokens.push(token); }
+      else if ([...fieldSet].some((candidate) => candidate.includes(token) || token.includes(candidate))) { score += 1; matchedTokens.push(token); }
+    }
+    const phrase = query.trim().toLowerCase();
+    const phraseField = selected.find((field) => String(row[field] ?? '').toLowerCase().includes(phrase));
+    if (phrase && phraseField) score += 8 * Number(weights[phraseField] ?? 1);
+    return { row, score, index, matchedTokens: [...new Set(matchedTokens)] };
+  }).sort((a, b) => b.score - a.score || a.index - b.index);
+}

package/skills/showdar-design/scripts/lib/search.mjs

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import { parseCsv } from './csv.mjs';
+import { rankRows } from './rank.mjs';
+
+export function searchRows(rows, query, { fields = [], weights = {}, filters = {}, limit = 8, includeZero = true } = {}) {
+  const matches = (actual, expected) => {
+    const actualValues = String(actual ?? '').split(/[,|;]/).map((value) => value.trim().toLowerCase()).filter(Boolean);
+    const expectedValues = (Array.isArray(expected) ? expected : [expected]).flatMap((value) => String(value).split(/[,|;]/)).map((value) => value.trim().toLowerCase()).filter(Boolean);
+    return expectedValues.length > 0 && expectedValues.every((value) => actualValues.includes(value));
+  };
+  const filtered = rows.filter((row) => Object.entries(filters).every(([key, value]) => matches(row[key], value)));
+  const ranked = rankRows(filtered, query, { fields, weights });
+  const candidates = includeZero ? ranked : ranked.filter((entry) => entry.score > 0);
+  return candidates.slice(0, Math.max(0, limit));
+}
+
+export async function searchCsv(file, query, options = {}) {
+  const rows = parseCsv(await readFile(file, 'utf8'));
+  return searchRows(rows, query, options);
+}

package/skills/showdar-design/scripts/search.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { searchCsv } from './lib/search.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const dataRoot = path.resolve(here, '..', 'data');
+const args = process.argv.slice(2);
+
+function value(flag, fallback = null) {
+  const i = args.indexOf(flag);
+  return i === -1 ? fallback : args[i + 1];
+}
+
+const query = value('--query') ?? args.filter((arg) => !arg.startsWith('--') && !['domain','stack','limit'].includes(arg)).join(' ');
+const domain = value('--domain', 'styles');
+const stack = value('--stack');
+const limit = Number(value('--limit', '8'));
+if (!query) {
+  console.error('Usage: node scripts/search.mjs --query "..." [--domain products|styles|colors|typography|motion|accessibility|components|ui-patterns] [--stack react-native] [--limit 8]');
+  process.exit(1);
+}
+
+try {
+  const index = JSON.parse(await readFile(path.join(dataRoot, 'index.json'), 'utf8'));
+  const relative = stack ? `data/stacks/${stack}.csv` : `data/${domain}.csv`;
+  const dataset = index.datasets.find((entry) => entry.file === relative);
+  if (!dataset) throw new Error(`unknown dataset ${relative}; inspect data/index.json`);
+  const weights = Object.fromEntries((dataset.searchableFields ?? []).map((field) => [field, ['id', 'tags', 'category', 'product', 'style'].includes(field) ? 2 : 1]));
+  const results = await searchCsv(path.join(path.dirname(dataRoot), dataset.file), query, {
+    fields: dataset.searchableFields, weights, filters: stack ? { stack } : {}, limit, includeZero: false,
+  });
+  console.log(JSON.stringify(results.map(({ row, score, matchedTokens }) => ({ score, matchedTokens, ...row })), null, 2));
+} catch (error) {
+  console.error(`showdar-design search: ${error.message}`);
+  process.exit(1);
+}

package/skills/showdar-design/stacks/flutter.md

@@ -0,0 +1,13 @@
+# Flutter design guidance
+
+Flutter UI decisions should follow constraints and lifecycle ownership rather than device-specific screenshots.
+
+- Keep domain state separate from ephemeral widget state and name the source of truth.
+- Use lazy slivers or builders for collections whose size is not bounded.
+- After an async gap, check `mounted` before using `context` or changing screen-owned UI.
+- Let constraints and flexible layout determine size; test text scale and narrow widths.
+- Dispose controllers, focus nodes, streams, and animation resources at their owner.
+- Add `Semantics` only where custom visuals remove native meaning; test order and labels.
+- Treat platform-channel calls as fallible and model unavailable capability states.
+
+Version note: verify Dart, Flutter, plugin, and platform support from the repository lockfile and current Flutter documentation.

package/skills/showdar-design/stacks/html-tailwind.md

@@ -0,0 +1,12 @@
+# HTML and Tailwind design guidance
+
+HTML/Tailwind should use CSS and native semantics as the primary behavior engine.
+
+- Define semantic color and spacing tokens with CSS variables before composing utilities.
+- Use buttons, links, labels, inputs, headings, and lists for their native interaction and reading behavior.
+- Treat breakpoints as priority/reflow decisions; test long labels, zoom, and localization.
+- Define focus, invalid, disabled, active, and reduced-motion states explicitly.
+- Extract a component only when behavior or a stable variant contract repeats.
+- Keep arbitrary values rare and explain a value that is a deliberate design token exception.
+
+Version note: validate utility names and configuration against the pinned Tailwind version.

package/skills/showdar-design/stacks/jetpack-compose.md

@@ -0,0 +1,13 @@
+# Jetpack Compose design guidance
+
+Compose screens should make state ownership, recomposition cost, window adaptation, and semantics explicit.
+
+- Hoist state only to the lowest common owner; keep transient input local.
+- Use lazy containers for unbounded content and stable domain keys for rows.
+- Treat `LaunchedEffect` and related APIs as lifecycle boundaries; keys must describe the work identity.
+- Use window size and insets for adaptive layouts instead of device-model branches.
+- Give custom controls role, label, state, and testable semantics; verify TalkBack focus order.
+- Keep expensive parsing, image work, and database reads outside composition.
+- Verify loading, empty, error, large-font, landscape, and back-navigation states.
+
+Version note: confirm APIs and Material guidance against the project’s pinned Compose BOM and Android documentation before implementation.

package/skills/showdar-design/stacks/nextjs.md

@@ -0,0 +1,12 @@
+# Next.js design guidance
+
+Next.js UI must make server/client, cache, loading, error, and metadata boundaries visible.
+
+- Keep client components narrow and use server rendering for static or data presentation when appropriate.
+- Co-locate fetching with the owner and state freshness or invalidation explicitly.
+- Give route segments meaningful loading and error states whose geometry matches final content.
+- Treat URL state, metadata, social previews, and accessible route transitions as product behavior.
+- Size responsive images and provide meaningful alt text; do not ship decorative payloads as critical content.
+- Test a cold route, client navigation, stale data, invalid data, and narrow viewport.
+
+Version note: check the pinned Next.js and React release notes before relying on cache or routing semantics.

package/skills/showdar-design/stacks/nuxt.md

@@ -0,0 +1,11 @@
+# Nuxt design guidance
+
+Nuxt designs must account for SSR hydration, route middleware, server handlers, and data freshness.
+
+- Keep browser-only APIs in client boundaries and make the first render deterministic.
+- Key data fetching by route/resource identity and define invalidation instead of duplicate fetches.
+- Enforce authorization in server handlers; client middleware is navigation UX, not policy.
+- Produce route-specific metadata and verify canonical/social output.
+- Give server and route failures actionable error states with retry or safe navigation.
+
+Version note: verify rendering, data, and cache behavior against the pinned Nuxt/Nitro version.

package/skills/showdar-design/stacks/react-native.md

@@ -0,0 +1,13 @@
+# React Native design guidance
+
+React Native design must account for JS/UI/native threads, navigation lifecycle, keyboard, safe areas, and platform semantics.
+
+- Use virtualized lists with stable keys and measured item strategy for long content.
+- Keep heavy parsing and synchronous work off gesture, typing, and scroll paths.
+- Pass serializable identifiers through navigation; keep business state in its owning store or query layer.
+- Size hit areas independently from icon artwork and set accessibility role, label, and state.
+- Make keyboard avoidance, safe-area insets, back behavior, loading, and offline states explicit.
+- Control image decode size and cache policy for list cells.
+- Test both iOS and Android when navigation, permissions, native modules, or layout differ.
+
+Version note: confirm behavior against the pinned React Native, Hermes, navigation, and platform toolchain versions.

package/skills/showdar-design/stacks/react.md

@@ -0,0 +1,12 @@
+# React design guidance
+
+React interfaces should preserve a small state graph and semantic browser behavior.
+
+- Keep server, URL, draft, and derived state distinct; do not mirror values through effect chains.
+- Use semantic HTML and native controls before custom interaction primitives.
+- Use stable keys from domain identity and profile render churn before adding memoization.
+- Model pending, error, empty, and retry states where the boundary can recover.
+- Keep context scopes aligned to consumers and avoid one provider for unrelated high-churn state.
+- Test keyboard navigation, focus return, long content, and asynchronous stale-result ordering.
+
+Version note: confirm concurrent rendering and framework integration behavior against the pinned React version.

package/skills/showdar-design/stacks/svelte.md

@@ -0,0 +1,11 @@
+# Svelte design guidance
+
+Svelte interfaces should make reactive ownership, lifecycle cleanup, and server/client boundaries explicit.
+
+- Derive display values rather than mutating shared module state from unrelated components.
+- Use effects for external synchronization and clean up timers, listeners, and subscriptions.
+- Use keyed each blocks by domain identity and virtualize genuinely large collections.
+- Preserve semantic HTML and verify compiler accessibility warnings with user behavior tests.
+- Represent pending, failure, cancellation, and stale-result states instead of relying on a spinner.
+
+Version note: check the pinned Svelte and SvelteKit version for runes, SSR, and routing behavior.

package/skills/showdar-design/stacks/swiftui.md

@@ -0,0 +1,12 @@
+# SwiftUI design guidance
+
+SwiftUI screens should make identity, observation, task cancellation, and Dynamic Type behavior explicit.
+
+- Select `State`, `Binding`, or observable model ownership based on who creates the value.
+- Use stable domain IDs in `ForEach`; never create random identity during body evaluation.
+- Keep expensive transformations out of `body` and scope tasks to the view lifecycle.
+- Prefer content-driven layout over fixed frames; test Dynamic Type, safe areas, and split view widths.
+- Use native controls and explicit labels, values, hints, and focus state for accessibility.
+- Model navigation as data when the flow benefits from restoration and deep links.
+
+Version note: verify APIs against the pinned Swift/Xcode SDK and minimum deployment target.

package/skills/showdar-design/stacks/tauri.md

@@ -0,0 +1,12 @@
+# Tauri design guidance
+
+Tauri UI is a desktop client over an IPC and capability boundary, not only a web page in a window.
+
+- Keep commands typed and validate every frontend-supplied argument in Rust.
+- Grant the smallest window capability set and review permission changes as security-sensitive.
+- Keep large data local or streamed; avoid moving whole documents across IPC on every interaction.
+- Scope event listeners to window lifetime and unsubscribe them on teardown.
+- Design keyboard shortcuts, window size, focus, and OS-specific behavior deliberately.
+- Verify signing, updater compatibility, and clean-machine install separately from UI correctness.
+
+Version note: confirm command, capability, and updater APIs against the pinned Tauri and Rust versions.

package/skills/showdar-design/stacks/vue.md

@@ -0,0 +1,12 @@
+# Vue design guidance
+
+Vue interfaces should keep reactivity and ownership legible across components and composables.
+
+- Use computed derivation for values that are not independent user state.
+- Keep watchers for synchronization with external systems, not render-state calculation.
+- Use stable keys and lazy list strategies for large collections.
+- Preserve native semantics and manage focus after route, dialog, and validation changes.
+- Abort or version asynchronous work so late results cannot overwrite newer state.
+- Keep form errors associated with controls and test keyboard behavior.
+
+Version note: check the pinned Vue and router version for reactivity, SSR, and suspense semantics.

package/skills/showdar-git/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: showdar-git
+description: Use when performing local Git inspection, staging, commits, branch integration, conflicts, cleanup, or explicitly requested remote Git actions.
+---
+
+# Showdar Git
+
+## Purpose
+
+Complete local Git workflows with evidence, narrow ownership, and a verifiable handoff.
+This skill owns repository state transitions, not source-code review or GitHub administration.
+
+## When to use
+
+- The user asks to inspect Git state or finish a local Git workflow.
+- A task needs selective staging, a commit, branch switching, merging, rebasing, or cherry-picking.
+- A merge, rebase, or cherry-pick has conflicts.
+- The user explicitly asks to push, pull, or remove a safely merged branch.
+- A previous Git operation was interrupted and repository state is ambiguous.
+
+## When not to use
+
+- Use `showdar-review` for reviewing implementation quality or a diff without a Git mutation.
+- Use `showdar-ship` for delivery-readiness verification; Ship does not imply Git mutation.
+- Use `showdar-recover` for an interrupted coding task when Git itself is not the recovery boundary.
+- Use `showdar-debug` for a source defect, test failure, or runtime regression.
+- Do not turn a local Git request into GitHub, CI/CD, deployment, or release work.
+
+## Inputs and assumptions
+
+- The repository path, current branch, requested operation, and target branch are known or inspectable.
+- The working tree may contain user changes that are unrelated to the current task.
+- Existing repository instructions and commit-message conventions are authoritative.
+- A remote is evidence only; its presence does not authorize a remote mutation.
+- A published/shared branch is treated as history that must not be rewritten silently.
+
+## Non-negotiable rules
+
+- Run `git status` before every mutation and inspect the relevant diff.
+- Classify task-owned, unrelated, generated, and ambiguous paths before staging.
+- Never stage unrelated work just to make the tree clean.
+- Stage explicit paths; `git add .` and `git add -A` are unsafe defaults in a mixed tree.
+- Inspect `git diff --cached --check` and `git diff --cached` before committing.
+- Preserve user work; never use `git reset --hard` or `git clean -fd` as convenience cleanup.
+- Never force-push, delete an unmerged branch, amend, squash, or rewrite published history by default.
+- Push, tag, remote deletion, pull with mutation, GitHub operations, and release actions require explicit intent.
+- Report exactly what changed after each Git mutation.
+
+## Workflow
+
+### 1. Inspect Git state
+
+Start with:
+
+```bash
+git status --short
+git branch -vv
+git remote -v
+git log -5 --oneline --decorate
+```
+
+Use the read-only helper `scripts/inspect-git-state.mjs` when a deterministic JSON snapshot is useful.
+Check for detached HEAD, upstream divergence, merge/rebase/cherry-pick state, staged paths, unstaged paths, and untracked paths.
+
+### 2. Establish ownership
+
+Read the task, current diff, and nearby repository instructions together.
+Classify every changed path:
+
+```text
+FEATURE/TASK:
+README.md
+src/foo.js
+
+EXCLUDED:
+AGENTS.md
+.agents/
+```
+
+If ownership is ambiguous, stop and ask; do not stage, revert, clean, or overwrite that path.
+An ignored or generated-looking path is not automatically safe to delete.
+
+### 3. Stage safely
+
+Stage only the confirmed task paths, including intended deletions:
+
+```bash
+git add README.md src/foo.js
+git add -u -- profiles/old.json
+```
+
+Then verify the index, not just the worktree:
+
+```bash
+git diff --cached --check
+git diff --cached --stat
+git diff --cached
+```
+
+Confirm excluded paths are absent from the staged diff. Unstage a mistaken path with `git restore --staged -- <path>` without changing its worktree content.
+
+### 4. Commit locally
+
+Use the repository's existing message convention when discoverable.
+The subject must describe only the staged change.
+Do not amend an existing commit unless explicitly requested.
+
+Before commit, verify staged paths, staged content, and cached whitespace.
+After commit, capture `git rev-parse HEAD`, inspect `git status --short`, and verify the commit contains the intended paths.
+
+### 5. Merge, rebase, or cherry-pick
+
+For a requested merge, inspect source and target branches first, protect dirty work, switch to the target, and use the repository convention.
+Preserve history unless the user explicitly chooses another strategy.
+Use `--no-ff` only when requested or established by repository convention.
+
+Treat rebase as history rewriting: determine whether commits are published before starting and never infer a force-push afterward.
+For cherry-pick, verify the commit identity and intent, then inspect the resulting diff and tests.
+
+### 6. Handle conflicts
+
+List the conflict set with `git status` and read both sides plus the surrounding history.
+Classify each conflict as textual, ownership, semantic, or generated.
+Do not blindly choose ours/theirs.
+Preserve both intents where appropriate, stage only resolved paths, and run relevant verification before continuing.
+If intent cannot be established, stop with the conflict set and the required decision.
+
+### 7. Pull and push safely
+
+A pull may alter local history or files; inspect status and upstream first.
+Use fast-forward-only when updating a branch that should not create an inferred merge.
+Push only after the user explicitly requests it and local verification is complete.
+Confirm branch, upstream, commit range, and whether a force update would be needed.
+Never force-push silently, especially after rebase.
+
+### 8. Clean up conservatively
+
+Delete a local branch only when it is merged into the intended target and cleanup is requested or clearly part of the completed Git task.
+Do not bulk-delete branches, delete remote branches, or remove unmerged work by inference.
+Verify the branch and merge base before deletion, then verify the remaining refs.
+
+## Decision points
+
+- Dirty tree plus mixed ownership -> classify and selectively stage; do not clean.
+- Detached HEAD -> inspect recent commits and ask where work should continue before branch mutation.
+- Published branch plus rebase request -> explain history-rewrite consequences before proceeding.
+- Existing conflict markers or operation metadata -> finish or abort only with explicit intent and understood recovery path.
+- Merge target is main/default/protected -> require explicit target intent; local Git does not grant release approval.
+- Push requested after failed verification -> report blockers and stop before remote mutation.
+
+## Git state inspection
+
+Inspect `HEAD`, branch, upstream, ahead/behind counts, staged/unstaged/untracked paths, and operation markers.
+Operation markers include `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `rebase-merge`, and `rebase-apply` under `.git`.
+The helper emits these facts without changing the repository.
+
+## Staging safety
+
+The index is the commit boundary. A clean or partially clean worktree does not prove the staged set is correct.
+Review renames, deletions, ignored files, submodules, symlinks, and generated files explicitly.
+Use pathspecs and `git add -u -- <path>` for intended deletions; never use broad staging in a mixed tree.
+
+## Commit workflow
+
+Commit only after cached diff review, whitespace validation, and relevant checks.
+If checks create generated files, classify them before staging.
+Record commit SHA, subject, staged path set, verification, and remaining exclusions.
+
+## Merge/rebase/cherry-pick guidance
+
+Prefer a normal merge when no convention is known.
+Preserve a merge commit with `--no-ff` when explicitly requested.
+Rebase only with clear authorization and a known unpublished/private history.
+Cherry-pick one verified commit at a time when its dependencies and ownership are understood.
+
+## Conflict handling
+
+Conflict resolution is a semantic edit, not a marker-removal exercise.
+Read the base, current side, incoming side, task requirements, and tests.
+Do not run `git checkout --ours`, `git checkout --theirs`, or equivalent bulk resolution without explicit, path-specific justification.
+
+## Push/pull safety
+
+`commit` does not imply `push`; `merge` does not imply `push`; `ship` does not imply `push`.
+GitHub Actions, workflow files, pull requests, branch protection, CI/CD, deployment, tags, releases, and provider configuration are outside this skill's default boundary.
+
+## Cleanup behavior
+
+Cleanup means verified local branch housekeeping, not making unrelated files disappear.
+Keep excluded files and unmerged branches visible in the final report.
+When a safe cleanup cannot be proven, leave it untouched and report the evidence needed.
+
+## Stack detection
+
+Git operations are stack-agnostic.
+Inspect the project stack only to choose existing local verification commands; do not invent CI or deployment commands.
+For native/generated projects, include relevant generated-file and lockfile changes in ownership review.
+
+## Failure modes
+
+- Broad staging captures user or generated files.
+- A commit is made from `git diff` while the index contains a different change set.
+- A merge resolves text but breaks the behavior owned by one side.
+- A rebase silently rewrites shared history.
+- A push is inferred from “finish”, “ship”, or “merge”.
+- Branch cleanup deletes a branch before merged-state evidence is checked.
+- GitHub or CI configuration is changed during an ordinary local Git task.
+
+## Stop conditions
+
+- Ownership of any staged candidate is ambiguous.
+- The target branch, commit range, or operation intent is unclear.
+- A destructive command is proposed without explicit authorization and a safe target.
+- A conflict's semantic intent cannot be inferred from task/source/history evidence.
+- Verification fails before a requested push, merge completion, or cleanup.
+
+## Escalation conditions
+
+- Ask before remote mutation, force-push, tag, remote deletion, or protected/default branch changes.
+- Ask when a rebase would rewrite published/shared history.
+- Ask when untracked or ignored files may be user-owned or generated by another tool.
+- Hand off source defects to `showdar-debug`, code review to `showdar-review`, and delivery readiness to `showdar-ship`.
+
+## Verification
+
+After local mutations, run:
+
+```bash
+git status
+git branch -vv
+git diff --check
+git log -1 --oneline --decorate
+```
+
+After staging, also run `git diff --cached --check` and inspect `git diff --cached`.
+After merge/rebase/cherry-pick, run relevant repository tests and checks, then verify no operation remains in progress.
+After push, verify the upstream and remote commit only when push was explicitly requested.
+
+## Output contract
+
+Report:
+
+- operation requested and operation actually performed
+- task-owned paths staged/committed and excluded paths preserved
+- commit, merge, rebase, or cherry-pick SHA(s)
+- branch, upstream, ahead/behind, and conflict state
+- verification commands and results
+- remote mutation status, explicitly stating “not performed” when not requested
+- remaining blockers or cleanup candidates
+
+## Anti-patterns
+
+- `git add .` or `git add -A` in a mixed worktree
+- reset, clean, checkout, or restore used to hide unrelated work
+- commit before reading the cached diff
+- automatic amend, squash, force-push, or remote deletion
+- choosing ours/theirs without semantic review
+- merging into main because it is convenient
+- treating GitHub, Actions, CI/CD, deploy, or release as part of local Git
+
+## Example
+
+### Commit only task-owned files
+
+```text
+status -> README.md and src/foo.js are task-owned; AGENTS.md and .agents/ are excluded
+stage -> git add README.md src/foo.js
+verify -> git diff --cached --check && git diff --cached
+commit -> commit only after the staged diff and relevant checks pass
+report -> SHA, staged paths, exclusions, and clean/dirty final state
+```
+
+### Feature completion without push
+
+```text
+feature branch -> selective commit -> switch develop -> merge using repository convention -> verify
+remote -> not touched because no push request was given
+```
+
+### Explicit push
+
+```text
+verify branch/upstream and checks -> confirm exact branch -> git push origin feature/name -> verify upstream
+```
+
+### Conflict
+
+```text
+merge reports conflicts -> inspect base/ours/theirs and task intent -> stop if ownership is unclear
+do not choose ours/theirs or abort/continue by inference
+```

package/skills/showdar-git/data/git-workflows.csv

@@ -0,0 +1,7 @@
+id,category,summary,evidence,approach,avoid,tags,reference,stack
+selective-staging,staging,Separate task-owned changes from unrelated work before a commit,git status and worktree diff show mixed paths,stage explicit paths and inspect the cached diff,git add . or git add -A in a mixed tree,selective staging; mixed worktree,references/operation-safety.md,*
+local-commit,commit,Create a commit from a verified index and actual task scope,git diff --cached matches the ownership classification,run cached whitespace checks and relevant local tests before commit,commit from an unreviewed index,commit; cached diff; task scope,references/operation-safety.md,*
+branch-merge,merge,Integrate a completed feature branch into a named local target,source and target branch state plus merge intent,protect dirty work merge with the local convention and verify history,infer push or merge into an unspecified protected branch,merge; branch; develop; local,references/operation-safety.md,*
+conflict-resolution,conflict,Resolve merge rebase or cherry-pick conflicts from both semantic sides,conflict paths operation metadata task intent and merge base,read both sides resolve narrowly test then continue,choose ours or theirs blindly,conflict; merge base; rebase; cherry-pick,references/operation-safety.md,*
+explicit-push,remote,Push only after explicit intent and local verification,current branch upstream commit and checks,user names the remote or branch then verify the result,infer push from commit merge or ship,remote; push; explicit intent; upstream,references/operation-safety.md,*
+merged-branch-cleanup,cleanup,Delete only a local branch proven merged into the intended target,merge base branch refs and cleanup request,verify merged state delete one safe local branch and recheck refs,bulk delete unmerged or remote branches,cleanup; merged branch; safe deletion,references/operation-safety.md,*

package/skills/showdar-git/data/index.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-git",
+  "datasets": [
+    {
+      "file": "data/git-workflows.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "summary", "evidence", "approach", "avoid", "tags", "reference", "stack"],
+      "searchableFields": ["category", "summary", "evidence", "approach", "avoid", "tags"],
+      "filterFields": ["category", "stack"],
+      "reference": "references/operation-safety.md"
+    }
+  ]
+}