showdar-skills 0.2.0

package/skills/showdar-understand/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: showdar-understand
+description: Use when mapping an unfamiliar repository, architecture, dependencies, or impact before deciding what to change.
+---
+
+# Showdar Understand
+
+## Purpose
+
+- Build a trustworthy mental model of a repository before changing it.
+- Identify runtime entrypoints, ownership boundaries, state/data flow, dependencies, build/test systems, and platform surfaces.
+- Separate facts observed in files from architectural inferences.
+- Reduce random file reading by following high-signal configuration and representative runtime paths.
+- Read `references/repository-analysis.md` for the default inspection sequence.
+- Use `references/architecture-signals.md` when directory names and actual dependency direction disagree.
+- Use `references/dependency-analysis.md` when the task crosses packages, native modules, persistence, queues, or external services.
+
+## When to use
+
+- Entering a repository or subsystem you do not already understand.
+- Before planning a feature whose change surface is unclear.
+- Before a refactor or migration that may cross package/module boundaries.
+- When the user asks for an architecture overview, dependency map, ownership map, or “where should this change go?”
+- When a bug appears to cross layers and you need a minimal map before debugging.
+- When agent context was compacted and repository structure must be re-established.
+
+## When not to use
+
+- The task is a tiny, already-localized edit and the exact owning file/contract is known.
+- The user only asks a conceptual question unrelated to the repository.
+- A production incident requires immediate evidence collection from runtime systems; use the relevant incident/debug tooling first.
+- Do not turn this into a comprehensive documentation project unless the user requested one.
+
+## Inputs and assumptions
+
+- Repository root or a clearly identified subproject is available.
+- Read repository instructions such as AGENTS.md/CLAUDE.md before source analysis.
+- Prefer current executable config, imports, tests, and build files over stale prose.
+- Generated files can reveal tooling but normally do not define source ownership.
+- If multiple apps/packages exist, record which one the user task targets before expanding analysis.
+- The read-only inspector `scripts/inspect-repo.mjs` may be used to collect deterministic signals.
+
+## Non-negotiable rules
+
+- Do not edit implementation files while running this skill unless the user explicitly changed the task.
+- Never claim an architecture pattern solely because folders are named domain, core, clean, feature, or shared.
+- Cite concrete files/symbols in the working notes that support each important architectural conclusion.
+- Mark uncertainty instead of filling missing links with a familiar architecture pattern.
+- Trace at least one representative runtime flow before declaring the repository understood.
+- Keep the map proportional to the user task; avoid exploring unrelated subsystems.
+- Never expose secrets found in configuration. Refer to secret names only.
+
+## Workflow
+
+### Phase 1 — establish repository context
+- Read instructions, manifests, lockfiles, workspace files, build scripts, CI, and platform folders.
+- Run `node scripts/inspect-repo.mjs <repo>` when deterministic stack/top-level signals are useful.
+- Record language, package manager, framework/runtime, workspace layout, test tooling, and build entrypoints.
+
+### Phase 2 — locate runtime entrypoints
+- Find app/server/worker/native entrypoints and route/navigation registration.
+- Identify configuration loading, dependency wiring, state stores, persistence adapters, and external integration seams.
+- Prefer symbols that create or register dependencies over leaf utility files.
+
+### Phase 3 — trace one representative flow
+- Select a flow relevant to the task: a screen transition, request handler, background job, or persistence write.
+- Trace input -> state/policy -> side effects -> output.
+- Record where errors propagate, where state is owned, and where platform boundaries occur.
+
+### Phase 4 — map boundaries and dependencies
+- Distinguish package boundary, runtime boundary, persistence boundary, UI/state boundary, and native/platform boundary.
+- Use `data/architecture-signals.csv` as a checklist, not as proof by itself.
+- Expand dependencies only until the likely change/verification surface is clear.
+
+### Phase 5 — synthesize
+- Produce a concise current-state map, relevant flow, change-relevant boundaries, risks, and unresolved questions.
+- Name the smallest set of files/symbols that should be read next for the user task.
+
+## Decision points
+
+- Monorepo? Map package ownership before source internals.
+- Multiple state systems? Identify which owns the task’s state instead of documenting all of them.
+- README contradicts source? Treat source/build configuration as current evidence and flag documentation drift.
+- Cross-platform mobile? Map shared code and native iOS/Android responsibilities separately.
+- Backend with workers/queues? Trace request and background execution as separate lifecycles.
+- If dependency direction is cyclic, report the cycle rather than forcing a clean-layer interpretation.
+
+## Stack detection
+
+- Use manifest and directory evidence; the shared engine can detect common stacks.
+- For mobile, read `stacks/mobile.md` and include navigation, lifecycle, native projects, permissions, and release surfaces.
+- For backend, read `stacks/backend.md` and include process entrypoint, persistence, jobs, health, and shutdown.
+- For React/Next.js, inspect render/router, server-client, cache, and state ownership using `stacks/react.md` or `stacks/nextjs.md`.
+- For Node/Fastify/NestJS, inspect bootstrap, plugin/module graph, request contracts, persistence, jobs, and shutdown using the matching stack file.
+- For React Native/Flutter/iOS/Android, separate shared state from native lifecycle, build, signing, and permissions using the matching stack file.
+- For Tauri/Electron, separate frontend, IPC/preload/commands, capabilities, host lifecycle, and packaging using `stacks/tauri.md` or `stacks/electron.md`.
+- Query `data/index.json` and `data/architecture-signals.csv` for stable signal IDs instead of treating folder names as proof.
+- For unsupported stacks, infer from build/config files and keep claims evidence-based.
+- Stack detection changes what to inspect; it does not change the core evidence-first workflow.
+
+## Failure modes
+
+- Over-reading every directory instead of following entrypoints and task-relevant flows.
+- Treating architecture diagrams or README prose as more current than executable code.
+- Confusing generated/vendor code with owned source.
+- Missing a second runtime such as worker, extension, native host, or CLI.
+- Describing folder taxonomy without explaining data/state/call flow.
+- Producing a map so broad that it does not reduce the next implementation decision.
+
+## Stop conditions
+
+- Stop when the requested outcome is outside this skill and hand off to the more appropriate workflow.
+- Stop before destructive, irreversible, production, credential, publishing, or deployment actions unless the user explicitly approved them.
+- Stop when required evidence is unavailable and proceeding would require guessing about behavior, ownership, or safety.
+- Stop when a repository instruction conflicts with this playbook; repository/user instructions win.
+- Stop when the task-relevant runtime flow, ownership boundaries, and verification surfaces are clear enough to plan or debug.
+
+## Escalation conditions
+
+- Ask the user when multiple apps/packages plausibly match the requested task and repository evidence cannot select one.
+- Escalate when required source is generated externally or missing from the checkout.
+- Escalate when repository instructions prohibit reading or executing a needed command.
+- For very large systems, propose narrowing to one user flow or service boundary before continuing.
+
+## Verification
+
+- Re-check every architecture claim against at least one executable/source signal.
+- Confirm the representative flow reaches a real entrypoint and observable output/side effect.
+- Confirm identified test/build commands actually exist before recommending them.
+- Verify that no unrelated subsystem was included merely because it looked architecturally interesting.
+- If using the inspector script, treat its output as inventory and manually verify important conclusions.
+
+## Output contract
+
+- **Stack and project shape** — languages, runtimes, package/workspace structure.
+- **Entrypoints** — app/server/worker/native entrypoints relevant to the task.
+- **Architecture map** — ownership boundaries and dependency direction with evidence.
+- **Representative flow** — input to output/side effect.
+- **Change-relevant surface** — files/symbols likely involved in the next task.
+- **Verification surface** — tests/builds/platforms that can prove a later change.
+- **Uncertainties** — explicit unknowns and the evidence needed to resolve them.
+
+## Anti-patterns
+
+- “This looks like Clean Architecture” without import/runtime proof.
+- Opening hundreds of files alphabetically.
+- Producing a generic technology inventory but no ownership or flow map.
+- Suggesting refactors while the task is only understanding.
+- Hiding uncertainty with confident architecture jargon.
+- Copying sensitive configuration values into notes or output.
+
+## Example
+
+User request: “Where should offline caching for the transactions screen live?”
+- Inspect manifests/navigation/state/data clients and trace transactions screen -> state/query -> API.
+- Determine whether cache ownership belongs to query/data layer or screen state based on existing boundaries.
+- Report exact source of truth, invalidation path, persistence options already present, and affected tests.
+- Do not implement caching during this skill.
+- See `examples/repository-audit.md` for a compact output shape.

package/skills/showdar-understand/data/architecture-signals.csv

@@ -0,0 +1,28 @@
+id,category,signal,evidence,interpretation,confidence,tags,reference,stack
+topology-workspace,topology,workspace manifest,pnpm-workspace.yaml; package.json workspaces; melos.yaml,packages have explicit ownership boundaries,high,topology monorepo ownership,references/architecture-signals.md,*
+topology-apps-packages,topology,apps and packages directories,package manifests below apps or packages,possible multi-runtime graph; verify package scripts,medium,topology packages apps,references/repository-analysis.md,*
+topology-generated,topology,generated/vendor directory,codegen output or vendored source markers,inspect generation owner before editing,medium,topology generated ownership,references/repository-analysis.md,*
+monorepo-task-runner,monorepo,task runner config,turbo.json; nx.json; moon.yml; lage.config.js,build and test commands may be graph-aware,high,monorepo task runner,references/dependency-analysis.md,*
+monorepo-local-package,monorepo,workspace dependency,workspace protocol or local package reference,source change can affect multiple consumers,high,monorepo dependency graph,references/dependency-analysis.md,*
+monorepo-boundary,monorepo,package exports,package.json exports or public barrel,public surface is narrower than filesystem,high,monorepo public API,references/architecture-signals.md,*
+entrypoint-web,entrypoint,web entrypoint,app router; pages; main.tsx; index.html,web runtime starts from route or root mount,high,entrypoint frontend,references/repository-analysis.md,react
+entrypoint-next,entrypoint,Next route entry,app or pages directory plus next script,server and client entrypoints coexist,high,entrypoint server client,references/repository-analysis.md,nextjs
+entrypoint-node,entrypoint,Node process entrypoint,bin field; main; start script; src/server.ts,process lifecycle and shutdown owner is here,high,entrypoint backend,references/repository-analysis.md,node
+entrypoint-fastify,entrypoint,Fastify registration,fastify() call and listen() boundary,plugins/routes/hooks form request lifecycle,high,entrypoint http,references/repository-analysis.md,fastify
+entrypoint-nest,entrypoint,Nest bootstrap,NestFactory.create and module graph,module metadata controls provider and route ownership,high,entrypoint dependency injection,references/repository-analysis.md,nestjs
+entrypoint-mobile,mobile,mobile app root,App.tsx; main.dart; SceneDelegate; MainActivity,platform lifecycle begins outside feature folders,high,entrypoint mobile,references/repository-analysis.md,react-native
+entrypoint-desktop,desktop,desktop host entry,src-tauri/src/main.rs; electron main process,frontend and host lifecycles are separate,high,entrypoint desktop,references/repository-analysis.md,tauri
+dependency-direction,dependency,import direction,feature imports shared policy but shared does not import feature,observed direction supports ownership boundary,high,dependency direction,references/architecture-signals.md,*
+dependency-inversion,dependency,injection seam,constructor parameters; provider bindings; get_it registrations,policy can be tested without concrete infrastructure,medium,dependency injection seam,references/dependency-analysis.md,*
+dependency-cycle,dependency,cyclic imports,dependency graph shows A -> B -> A,change surface and initialization order are coupled,high,dependency cycle,references/dependency-analysis.md,*
+dependency-runtime,dependency,runtime dependency,imported package is used in shipped path,upgrade affects behavior and artifact,high,dependency runtime,references/dependency-analysis.md,*
+dependency-build,dependency,build-only dependency,compiler plugin; bundler; codegen tool,upgrade affects build without runtime import,medium,dependency build tooling,references/dependency-analysis.md,*
+dependency-native,dependency,native dependency,Podfile; Package.swift; Gradle; Maven; plugin registration,shared source change may require platform builds,high,dependency native,references/dependency-analysis.md,ios
+package-manager-lock,tooling,lockfile,package-lock.json; yarn.lock; pnpm-lock.yaml; pubspec.lock,resolved versions are evidence; manifest alone is insufficient,high,tooling lockfile,references/dependency-analysis.md,package-manager
+build-script,build,build script,package scripts; Makefile; justfile; Fastlane; Gradle task,verification must use repository-owned command,high,build verification,references/repository-analysis.md,*
+build-config,build,build configuration,tsconfig; vite; webpack; metro; Xcode scheme,configuration can move behavior across environments,high,build configuration,references/repository-analysis.md,typescript
+ci-workflow,ci,CI workflow,.github/workflows; .gitlab-ci.yml; Buildkite config,remote verification may differ from local environment,high,ci environment,references/repository-analysis.md,ci
+ci-gate,ci,required status check,branch protection or CI job dependency,completion requires the named gate rather than a local substitute,medium,ci gate,references/repository-analysis.md,ci
+backend-boundary,backend,persistence or queue adapter,db client; migration folder; queue producer,request and worker lifecycles need separate tracing,high,backend persistence queue,references/dependency-analysis.md,node
+mobile-native-boundary,mobile,native bridge,TurboModule; MethodChannel; JNI; Swift/Kotlin bridge,shared UI behavior crosses platform-owned lifecycle,high,mobile native bridge,references/architecture-signals.md,react-native
+desktop-native-boundary,desktop,desktop IPC command,invoke handler; preload bridge; Tauri command,capability and serialization boundaries need explicit review,high,desktop ipc,references/architecture-signals.md,electron

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

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-understand",
+  "datasets": [
+    {
+      "file": "data/architecture-signals.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "signal", "evidence", "interpretation", "confidence", "tags", "reference", "stack"],
+      "searchableFields": ["category", "signal", "evidence", "interpretation", "tags"],
+      "filterFields": ["category", "confidence", "stack"],
+      "reference": "references/architecture-signals.md"
+    }
+  ]
+}

package/skills/showdar-understand/examples/repository-audit.md

@@ -0,0 +1,17 @@
+# Example: repository audit output
+
+Request: explain where dashboard data comes from and where a stale metric could
+be introduced.
+
+Detected stack: Next.js + TypeScript + PostgreSQL; package manager is pnpm; CI
+runs the web test and build jobs. Entrypoints are `app/` routes and
+`src/jobs/worker.ts`. Persistence lives under `src/db/`, with migrations in
+`drizzle/`; client state is limited to local interaction.
+
+Critical flow traced: sign-in -> session lookup -> dashboard query -> server
+render -> metric cards. The query cache is a boundary because it can outlive a
+request; the sync worker is the writer that must invalidate it.
+
+Uncertainty: queue ownership is split across two packages. Recommended next
+read: package exports plus every queue producer/consumer call site. Output must
+separate observed facts from inferred ownership.

package/skills/showdar-understand/references/architecture-signals.md

@@ -0,0 +1,25 @@
+# Architecture signals
+
+Architecture is inferred from repeated dependency direction, state ownership, public interfaces, and runtime entrypoints—not from folder names alone.
+
+## Signal strength
+
+- Strong: workspace/package manifests; route registration; process bootstrap; dependency injection bindings; public exports; repository/service protocols; database migrations; queue registration; native bridges; test providers.
+- Medium: repeated import direction; feature module boundaries; state store ownership; serializer/DTO seams; build targets; separate worker commands.
+- Weak: names such as `core`, `shared`, `utils`, `domain`, or `clean`. Verify these against imports and call paths.
+
+## How to read a signal
+
+1. Record the exact file and symbol that emits the signal.
+2. Find at least one caller and one owned side effect.
+3. Check whether another path bypasses the apparent owner.
+4. Mark the conclusion as observed, inferred, or uncertain.
+
+## Common conflicts
+
+- A `repositories/` folder is weak evidence if UI code constructs queries directly.
+- A public barrel is a supported API only when package exports and consumers agree.
+- A state store is the owner only if writes and invalidation route through it.
+- A generated file is evidence of tooling, not necessarily the source of truth.
+
+When boundaries conflict, report both intended and observed dependency direction. Do not silently normalize a tangled codebase into textbook architecture.

package/skills/showdar-understand/references/dependency-analysis.md

@@ -0,0 +1,9 @@
+# Dependency analysis
+
+Classify dependencies as runtime, build-time, test-only, platform/native, generated, or tooling. For a proposed change, identify direct dependencies first, then only expand transitive dependencies that can alter behavior, build output, or deployment.
+
+For each relevant edge record the owner manifest and lockfile; direct importer and exported contract; resolved version or platform constraint; initialization/lifecycle impact; and verification command that exercises the edge.
+
+For monorepos, distinguish package graph edges from source imports and task-runner graph edges. For mobile projects, include CocoaPods/SwiftPM/Gradle/Maven, native modules, permissions, and signing configuration. For backend systems, include database, queue, cache, and external service contracts. For desktop hosts, include IPC, capabilities, preload, and updater dependencies.
+
+Do not report a long dependency list. A dependency finding is useful only if it changes the change surface, verification plan, or risk assessment.

package/skills/showdar-understand/references/repository-analysis.md

@@ -0,0 +1,24 @@
+# Repository analysis
+
+## Entry sequence
+1. Read repository-level instructions before source code.
+2. Identify package/workspace manifests, lockfiles, build files, CI definitions, and native project files.
+3. Find runtime entrypoints and public interfaces before leaf utilities.
+4. Trace one representative user or request flow end-to-end.
+5. Confirm architecture by evidence from imports, routing, dependency injection, tests, and build configuration.
+
+## Inventory questions
+
+- What starts in development, production, CI, background work, and native hosts?
+- Which manifest and lockfile owns each dependency graph?
+- Which scripts are authoritative for build, test, lint, code generation, migration, and release?
+- Which directories are generated, vendored, ignored, or platform-owned?
+- Where are environment variables loaded, validated, and redacted?
+
+## Evidence hierarchy
+Prefer executable configuration and source imports over directory names. Prefer current code over README claims when they disagree. Treat generated files as evidence of tooling, not ownership boundaries. Treat tests as behavior evidence, not always as architecture truth.
+
+## Output discipline
+Separate observed facts from inferred architecture. Mark uncertain claims and name the file or symbol that would resolve them.
+
+Do not inventory every file. Stop once the task-relevant entrypoint, owner, side-effect boundary, failure path, and verification command are evidenced.

package/skills/showdar-understand/scripts/inspect-repo.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { access, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { detectStacks } from './lib/detect-stack.mjs';
+
+const root = path.resolve(process.argv[2] ?? process.cwd());
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+const candidates = ['package.json','pnpm-workspace.yaml','yarn.lock','pnpm-lock.yaml','package-lock.json','pubspec.yaml','Cargo.toml','go.mod','pyproject.toml','Dockerfile','docker-compose.yml','compose.yaml','.github/workflows'];
+const present = [];
+for (const name of candidates) if (await exists(path.join(root,name))) present.push(name);
+let packageSummary = null;
+if (await exists(path.join(root,'package.json'))) {
+  try { const p=JSON.parse(await readFile(path.join(root,'package.json'),'utf8')); packageSummary={name:p.name??null,scripts:Object.keys(p.scripts??{}),workspaces:p.workspaces??null}; } catch {}
+}
+const top = (await readdir(root,{withFileTypes:true})).filter(e=>!e.name.startsWith('.')||e.name==='.github').slice(0,80).map(e=>({name:e.name,type:e.isDirectory()?'dir':'file'}));
+console.log(JSON.stringify({root,stacks:await detectStacks(root),signals:present,package:packageSummary,topLevel:top},null,2));

package/skills/showdar-understand/scripts/lib/detect-stack.mjs

@@ -0,0 +1,48 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+async function exists(target) { try { await access(target); return true; } catch { return false; } }
+
+export async function detectStacks(projectRoot) {
+  const found = new Set();
+  try {
+    const names = await readdir(projectRoot);
+    if (names.some((name) => ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb'].includes(name))) found.add('package-manager');
+    if (names.some((name) => ['pnpm-workspace.yaml', 'lerna.json', 'turbo.json', 'nx.json'].includes(name))) found.add('workspace');
+    if (names.some((name) => name.endsWith('.xcodeproj') || name.endsWith('.xcworkspace'))) found.add('ios');
+  } catch { /* inaccessible repository is reported by the caller */ }
+  const packageFile = path.join(projectRoot, 'package.json');
+  if (await exists(packageFile)) {
+    try {
+      const pkg = JSON.parse(await readFile(packageFile, 'utf8'));
+      const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
+      if (pkg.packageManager) found.add('package-manager');
+      if (pkg.workspaces) found.add('workspace');
+      if (deps.next) found.add('nextjs');
+      if (deps.react) found.add('react');
+      if (deps['react-native']) found.add('react-native');
+      if (deps.vue) found.add('vue');
+      if (deps.svelte) found.add('svelte');
+      if (deps.tailwindcss) found.add('html-tailwind');
+      if (deps.fastify || deps['@fastify/core']) found.add('fastify');
+      if (deps['@nestjs/core']) found.add('nestjs');
+      if (deps['@tauri-apps/api']) found.add('tauri');
+      if (deps.electron) found.add('electron');
+      if (deps.expo || deps['expo-router']) found.add('expo');
+      found.add('node');
+    } catch { /* malformed package is reported by higher-level skills */ }
+  }
+  if (await exists(path.join(projectRoot, 'pubspec.yaml'))) {
+    const pubspec = await readFile(path.join(projectRoot, 'pubspec.yaml'), 'utf8');
+    if (/\bflutter\s*:/m.test(pubspec)) found.add('flutter');
+    found.add('dart');
+  }
+  if (await exists(path.join(projectRoot, 'ios'))) found.add('ios');
+  if (await exists(path.join(projectRoot, 'android'))) found.add('android');
+  if (await exists(path.join(projectRoot, 'Package.swift'))) { found.add('swift'); found.add('spm'); }
+  if (await exists(path.join(projectRoot, 'Cargo.toml'))) found.add('rust');
+  if (await exists(path.join(projectRoot, 'go.mod'))) found.add('go');
+  if (await exists(path.join(projectRoot, 'pyproject.toml')) || await exists(path.join(projectRoot, 'requirements.txt'))) found.add('python');
+  if (await exists(path.join(projectRoot, '.github', 'workflows')) || await exists(path.join(projectRoot, '.gitlab-ci.yml')) || await exists(path.join(projectRoot, 'Jenkinsfile'))) found.add('ci');
+  return [...found].sort();
+}

package/skills/showdar-understand/stacks/android.md

@@ -0,0 +1,3 @@
+# Android repository signals
+
+Locate application/activity or Compose root, navigation, ViewModel/state owner, Gradle modules, manifest, flavors, and resource source sets. Trace a user action through lifecycle-aware state, repository, and rendered output. Record Gradle/AGP/JDK and min/target/compile SDK evidence. Separate debug behavior from release, R8, signing, and process-death behavior.

package/skills/showdar-understand/stacks/backend.md

@@ -0,0 +1,5 @@
+# Backend repository signals
+
+Find the process entrypoint, HTTP/RPC registration, dependency wiring, configuration loader, persistence adapters, migrations, jobs/queues, health endpoints, observability hooks, and shutdown path. Separate request lifecycle from background workers and one-off migration tooling.
+
+Trace one request as `input -> validation/auth -> handler -> service policy -> persistence or queue -> serializer -> response`. Trace one background job as `enqueue -> durable payload -> worker claim -> side effect -> retry/dead-letter -> completion`. Record transaction and idempotency owners, connection-pool lifecycle, readiness versus liveness, and graceful shutdown behavior. A health endpoint that does not exercise required dependencies is a weak signal.

package/skills/showdar-understand/stacks/electron.md

@@ -0,0 +1,3 @@
+# Electron repository signals
+
+Locate the main process, preload bridge, renderer entry, IPC handlers, context isolation/sandbox settings, and packaging config. Trace renderer action through typed IPC, main-process validation, side effect, and result. Identify filesystem and shell authority in the main process. Check platform packaging, signing, auto-update, and clean-install paths separately from renderer tests.

package/skills/showdar-understand/stacks/fastify.md

@@ -0,0 +1,3 @@
+# Fastify repository signals
+
+Locate the Fastify factory, plugin registration order, route schemas, hooks, decorators, error handler, and `listen`/close ownership. Treat plugin encapsulation as a boundary and inspect where validation and auth are registered. Trace one request through hook, schema, handler, service, and response serializer. Check readiness and graceful shutdown paths separately from route behavior.

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

@@ -0,0 +1,3 @@
+# Flutter repository signals
+
+Inspect `main`, router, dependency injection, state management, repositories, platform channels, and Android/iOS runners. Trace widget action to state/event, async repository work, and rebuild. Identify isolate/background work and lifecycle disposal. Read `pubspec.lock`, flavors, signing, and native project config when the task can affect release behavior.

package/skills/showdar-understand/stacks/ios.md

@@ -0,0 +1,3 @@
+# iOS repository signals
+
+Locate App/Scene delegate, navigation root, targets/schemes, Swift package or CocoaPods ownership, capabilities, entitlements, and persistence. Trace one user flow across view/controller, model/service, and native lifecycle. Record deployment target and build configuration. Treat signing, privacy manifests, push, deep links, and background modes as separate release surfaces.

package/skills/showdar-understand/stacks/mobile.md

@@ -0,0 +1,5 @@
+# Mobile repository signals
+
+Inspect app entrypoint, navigation root, state container, native `ios/` and `android/` integration, build flavors/schemes, permissions, deep links, push setup, and release configuration. React Native and Flutter may share business code while native projects still own signing, capabilities, and platform lifecycle behavior.
+
+Trace one cold-start flow and one resumed/deep-link flow. Record where navigation state, server/cache state, draft state, and native lifecycle state live. Check keyboard/safe-area behavior, background/foreground transitions, process death restoration, platform-channel/native-module contracts, and release-only configuration. A shared component test does not prove native permissions, signing, lifecycle, or store artifact behavior.

package/skills/showdar-understand/stacks/nestjs.md

@@ -0,0 +1,3 @@
+# NestJS repository signals
+
+Start at `NestFactory` bootstrap and map root, feature, global, and dynamic modules. Locate controllers, guards, pipes, interceptors, providers, repositories, and exception filters. Record module import/export direction rather than assuming folder names. Trace one request through guard, pipe, controller, service, persistence, and filter. Identify scheduled jobs or queues that bypass HTTP.

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

@@ -0,0 +1,3 @@
+# Next.js repository signals
+
+Inspect `app/` or `pages/`, route handlers, middleware, server/client boundaries, loading/error files, metadata, and deployment config. Locate data fetching and cache/revalidation ownership. Separate build-time, request-time, and browser-only code. Trace one route from URL to server handler/query to rendered output and one mutation back to invalidation. Check runtime selection and environment variable names without printing values.

package/skills/showdar-understand/stacks/node.md

@@ -0,0 +1,3 @@
+# Node.js repository signals
+
+Find the process entrypoint, scripts, module format, configuration loader, HTTP server, worker/queue startup, database pool, and shutdown hooks. Identify whether one process owns multiple lifecycles. Trace request input through validation, service policy, persistence, response serialization, and error mapping. Record runtime and package-manager evidence from the lockfile and container/build files.

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

@@ -0,0 +1,3 @@
+# React Native repository signals
+
+Inspect the JS entry, navigation root, state/query providers, Metro/Babel config, native module registration, and `ios/`/`android/` projects. Trace a screen action through JS state, network/native bridge, and rendered result. Record lifecycle ownership for subscriptions and navigation. Separate shared source changes from native build/signing/configuration evidence.

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

@@ -0,0 +1,3 @@
+# React repository signals
+
+Locate the root render entry, route registry, context/provider composition, query/cache owner, and test setup. Distinguish server data, URL state, draft state, and derived render state. Follow imports from a route to its feature and from feature to API/client boundary. Check whether a component package is public through exports or only internal. Verify state ownership by tracing a user action through event handler, reducer/store, side effect, and rendered result.

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

@@ -0,0 +1,3 @@
+# Tauri repository signals
+
+Map the web frontend entry and routes separately from Rust `main`, commands, events, state, capabilities, and updater configuration. Trace a UI action across serialization, command validation, Rust side effect, and event/result. Identify filesystem, shell, window, and network permissions. Record frontend build, Rust target, bundle, signing, and update artifacts as separate boundaries.

package/skills/showdar-upgrade/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: showdar-upgrade
+description: Use when upgrading dependencies, frameworks, runtimes, or native platforms and compatibility or rollback risk matters.
+---
+
+# Showdar Upgrade
+
+## Purpose
+
+- Make upgrades controlled engineering changes rather than version-number edits.
+- Identify compatibility across runtime, framework, peers, native toolchains, build plugins, and deployment environment.
+- Search repository usage for breaking/deprecated APIs before modifying versions.
+- Keep rollback boundaries explicit.
+- Read `references/compatibility.md`, `references/breaking-changes.md`, and `references/migration-strategy.md` for nontrivial upgrades.
+
+## When to use
+
+- Dependency, framework, runtime, SDK, build plugin, iOS/Android platform, or language upgrade.
+- Migration across deprecated APIs or project template/toolchain changes.
+- Resolving peer/toolchain compatibility before installing a new version.
+- Planning staged upgrades across multiple coupled packages.
+
+## When not to use
+
+- Installing a new small dependency with no version migration or compatibility question.
+- Debugging an unknown build failure without evidence that version compatibility is causal.
+- Production deploy belongs to showdar-ship after the upgrade is verified.
+- Do not blindly “upgrade everything to latest” unless explicitly requested.
+
+## Inputs and assumptions
+
+- Current and target versions (or target policy such as latest supported).
+- Current runtime/toolchain/native platform versions.
+- Lockfile/package manager ownership.
+- Official release/migration information should be checked when freshness matters.
+- `scripts/inspect-dependencies.mjs` can collect current dependency/runtime signals without changes.
+
+## Non-negotiable rules
+
+- Record current state before changing versions.
+- Do not assume latest versions are mutually compatible.
+- Separate package resolution, source migration, generated/codegen changes, native/build changes, and release changes.
+- Search current repository usage for removed/changed APIs.
+- Preserve a real rollback path before irreversible migration steps.
+- Change one compatibility layer at a time when that yields diagnosable failures.
+- Build affected native/platform targets after native/toolchain upgrades.
+- Never discard a lockfile just to force resolution without understanding why.
+
+## Workflow
+
+### Phase 1 — inventory
+- Run `node scripts/inspect-dependencies.mjs <repo>` or equivalent package-manager commands.
+- Record framework/runtime, direct/peer deps, lockfile, native toolchain, deployment/runtime constraints.
+
+### Phase 2 — compatibility matrix
+- Use `data/compatibility-checklist.csv` to ensure runtime, peers, native, codegen, and public API surfaces are covered.
+- Verify documented supported combinations for the target version.
+- Identify unknown/unsupported combinations explicitly.
+
+### Phase 3 — breaking-change search
+- Read relevant official release/migration notes for crossed boundaries.
+- Search repository for removed/deprecated APIs and config keys.
+- Identify generated/template diffs separately from source changes.
+
+### Phase 4 — choose migration sequence
+- Decide direct versus staged upgrade based on compatibility and diagnosability.
+- Define package/version order, source edits, codegen, native/project edits, and lockfile regeneration.
+- Define rollback point using `references/rollback.md`.
+
+### Phase 5 — execute controlled changes
+- Update version/config at the owner.
+- Apply required source migrations with minimal unrelated refactor.
+- Regenerate only artifacts owned by the upgraded tooling.
+
+### Phase 6 — verification
+- Install/resolve dependencies cleanly.
+- Run typecheck/analyzer/tests/builds.
+- Build native/release targets touched by toolchain changes.
+- Inspect lockfile/generated diff for unexpected package churn.
+
+## Decision points
+
+- Major framework jump with many coupled APIs? Prefer staged if intermediate support reduces ambiguity.
+- Security patch with narrow backport available? Prefer smallest supported safe upgrade when user goal is risk remediation.
+- Peer conflict? Determine which package owns the incompatible range; do not use force/legacy-peer flags as final solution.
+- Native minimum OS/SDK changes? Treat as product/release decision, not invisible build detail.
+- Codegen format changes? Verify source-of-truth inputs and generated ownership before committing churn.
+
+## Stack detection
+
+- React: `stacks/react.md` for React/React DOM, renderer, peer, and API migration surfaces.
+- React Native: `stacks/react-native.md`.
+- Flutter: `stacks/flutter.md`.
+- Next.js: `stacks/nextjs.md`.
+- Node runtime: `stacks/node.md`.
+- iOS/Xcode/Swift: `stacks/ios.md`.
+- Android/JDK/Gradle/AGP: `stacks/android.md`.
+- Expo: `stacks/expo.md` for SDK/config-plugin/generated-native coupling.
+- CocoaPods/SPM and Gradle: read `stacks/cocoapods-spm.md` or `stacks/gradle.md` for native lock/build boundaries.
+- Tauri/Rust: `stacks/tauri-rust.md` for capability, crate, target, bundle, and updater coupling.
+
+## Failure modes
+
+- Editing package version and waiting for compiler errors to reveal migration plan.
+- Forcing dependency resolution with flags while peers remain incompatible.
+- Deleting lockfile and accepting broad unrelated dependency churn.
+- Updating native project template blindly and overwriting app-specific settings.
+- Missing runtime/deployment version mismatch after local build succeeds.
+- No rollback for schema/minimum-OS/codegen changes.
+- Claiming success after unit tests while native/release build was affected.
+
+## Stop conditions
+
+- Stop when the requested outcome is outside this skill and hand off to the more appropriate workflow.
+- Stop before destructive, irreversible, production, credential, publishing, or deployment actions unless the user explicitly approved them.
+- Stop when required evidence is unavailable and proceeding would require guessing about behavior, ownership, or safety.
+- Stop when a repository instruction conflicts with this playbook; repository/user instructions win.
+- Stop when target versions are resolved, breaking usages migrated, lock/generated changes explained, and affected test/build/platform verification passes.
+
+## Escalation conditions
+
+- Ask when target version is unspecified and “latest” would materially change support requirements.
+- Escalate minimum OS/SDK/browser/runtime support changes to the user/product owner.
+- Escalate destructive database/data migrations and production rollout decisions.
+- If official compatibility information is unavailable, state risk instead of guessing support.
+
+## Verification
+
+- Confirm resolved versions from package manager/tooling, not only manifest text.
+- Run repository search for known removed/deprecated APIs after migration.
+- Run static analysis/tests/builds appropriate to touched stack.
+- Build iOS/Android release targets when native toolchain/project files changed.
+- Inspect lockfile/generated/native project diff for unexplained churn.
+- Document exact environment and any platform not verified.
+
+## Output contract
+
+- **Current -> target** versions.
+- **Compatibility matrix** and constraints.
+- **Breaking changes found in this repository**.
+- **Migration sequence** including source/native/generated steps.
+- **Rollback boundary**.
+- **Verification results** by stack/platform.
+- **Unverified/remaining risks**.
+
+## Anti-patterns
+
+- `--force` as compatibility strategy.
+- “Upgrade all dependencies while we are here.”
+- Blind template overwrite for native projects.
+- Ignoring lockfile diff.
+- Mixing unrelated refactor with migration so failures are hard to localize.
+- Treating local dev startup as release-build verification.
+
+## Example
+
+User request: “Upgrade React Native to the next supported release.”
+- Inventory React/Metro/Babel/Node/JDK/Gradle/AGP/Xcode/CocoaPods and native modules.
+- Check target RN compatibility and template/migration notes.
+- Search deprecated RN APIs and native project changes.
+- Migrate source/native config in controlled steps, inspect lockfile/template diff, build Android+iOS.
+- See `examples/upgrade-report.md`.