showdar-skills 0.2.0

package/engine/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/engine/rank.mjs

@@ -0,0 +1,40 @@
+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/engine/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/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "showdar-skills",
+  "version": "0.2.0",
+  "description": "Production-grade software engineering lifecycle skills for coding agents.",
+  "type": "module",
+  "bin": { "showdar": "./bin/showdar.js" },
+  "scripts": {
+    "test": "node --test",
+    "validate": "node bin/showdar.js validate",
+    "sync:runtime": "node scripts/sync-runtime.mjs",
+    "eval": "node scripts/retrieval-eval.mjs",
+    "check": "npm test && npm run validate && npm pack --dry-run",
+    "smoke": "node scripts/package-smoke.mjs",
+    "release:check": "node scripts/check-release-version.mjs"
+  },
+  "engines": { "node": ">=20" },
+  "files": ["bin", "src", "skills", "commands", "router", "bundles", "profiles", "engine", "README.md", "LICENSE"],
+  "keywords": ["agent-skills", "coding-agents", "codex", "opencode", "claude-code", "software-engineering", "developer-tools", "requirements", "qa", "security", "devops", "workflow"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caongocquy/showdar-skills.git"
+  },
+  "homepage": "https://github.com/caongocquy/showdar-skills#readme",
+  "bugs": {
+    "url": "https://github.com/caongocquy/showdar-skills/issues"
+  }
+}

package/profiles/backend.json

@@ -0,0 +1 @@
+{"skills":["showdar-understand","showdar-plan","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-requirements","showdar-quality","showdar-security","showdar-ops"]}

package/profiles/developer.json

@@ -0,0 +1 @@
+{"skills":["showdar-understand","showdar-plan","showdar-design","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-security"]}

package/profiles/full.json

@@ -0,0 +1 @@
+{"skills":["showdar-understand","showdar-plan","showdar-design","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-requirements","showdar-quality","showdar-security","showdar-ops"]}

package/profiles/minimal.json

@@ -0,0 +1 @@
+{"skills":["showdar-understand","showdar-plan","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-recover","showdar-git"]}

package/profiles/product.json

@@ -0,0 +1 @@
+{"skills":["showdar-understand","showdar-requirements","showdar-plan","showdar-design","showdar-quality","showdar-review"]}

package/profiles/qa.json

@@ -0,0 +1 @@
+{"skills":["showdar-understand","showdar-requirements","showdar-quality","showdar-test","showdar-debug","showdar-review","showdar-ship","showdar-recover","showdar-git"]}

package/router/conflicts.yaml

@@ -0,0 +1,50 @@
+version: 2
+rules:
+  - showdar-review never performs deployment or publishing as part of review
+  - showdar-ship verifies delivery readiness by default and never creates or modifies CI/deployment/release infrastructure without explicit task intent
+  - showdar-ship never deploys publishes submits tags pushes or mutates production without explicit user intent and required approval
+  - showdar-debug does not patch before sufficient evidence and a falsifiable hypothesis
+  - showdar-recover never discards user or uncommitted work without explicit approval
+  - showdar-git owns local Git operations; showdar-review owns code/diff review, showdar-debug owns source failures, and showdar-recover owns interrupted implementation recovery
+  - showdar-git does not imply push, GitHub, CI/CD, deployment, or release execution
+  - showdar-plan does not invent product requirements to simplify architecture
+  - showdar-requirements owns what behavior is required or unresolved; showdar-plan owns how engineering will implement an agreed requirement
+  - showdar-requirements uses current repository behavior as evidence but does not replace showdar-understand's system discovery
+  - showdar-quality owns QA scenarios, risks, coverage, and acceptance confidence; showdar-test owns automated test-level selection and implementation
+  - showdar-quality reviews verification scope, not code defects (showdar-review) or overall delivery readiness (showdar-ship)
+  - showdar-requirements and showdar-quality do not invent stakeholder decisions or claim execution evidence that was not observed
+  - explicit security intent wins over showdar-review: showdar-security owns posture, threats, authz, secrets, exposure, attack surface, and exploitability; showdar-review owns general correctness, maintainability, architecture, performance, and tests
+  - showdar-debug owns the root cause of observed failures; showdar-security owns security risk even when no failure is observed; showdar-test owns automated test implementation; showdar-quality owns QA/QC planning
+  - showdar-ship verifies delivery or release readiness and does not create CI/deployment infrastructure by default; showdar-ops owns operational implementation and execution
+  - showdar-ops may inspect CI, containers, environments, deployments, observability, and rollback read-only; local config changes require an explicit request, and remote or production mutation requires explicit target/action intent and authorization
+  - showdar-ops never infers deploy, publish, production mutation, secret changes, resource deletion, CI creation, or release automation from ship, ready, release, fix CI, or prepare deploy alone
+  - showdar-build owns application feature implementation; showdar-ops owns operational configuration and runtime workflows; showdar-git owns local Git workflow and does not imply operational execution
+  - showdar-design preserves authoritative existing design tokens and product constraints
+  - explicit user instructions override automatic routing while safety and repository constraints remain in force
+overlap_matrix:
+  - pair: showdar-understand vs showdar-requirements
+    boundary: understand maps observed system behavior; requirements defines behavior that should exist or remains undecided
+  - pair: showdar-requirements vs showdar-plan
+    boundary: requirements establishes the product contract; plan chooses the engineering approach for an agreed contract
+  - pair: showdar-plan vs showdar-build
+    boundary: plan describes bounded implementation work; build performs the approved application change
+  - pair: showdar-design vs showdar-build
+    boundary: design decides product UI direction and experience; build implements the agreed UI change
+  - pair: showdar-debug vs showdar-recover
+    boundary: debug explains an observed failure; recover reconstructs interrupted work and its safest continuation
+  - pair: showdar-test vs showdar-quality
+    boundary: quality plans risk and verification scope; test implements automated proof at the appropriate test level
+  - pair: showdar-review vs showdar-security
+    boundary: review checks general code quality; security assesses security posture, threats, and exploitability
+  - pair: showdar-review vs showdar-ship
+    boundary: review evaluates change quality; ship evaluates delivery readiness and handoff evidence
+  - pair: showdar-ship vs showdar-ops
+    boundary: ship verifies readiness; ops changes or executes operational and deployment workflows
+  - pair: showdar-git vs showdar-ops
+    boundary: git handles repository history and local Git actions; ops handles runtime, deployment, and operational state
+  - pair: showdar-git vs showdar-recover
+    boundary: git performs an explicit Git operation; recover reconstructs interrupted work before choosing the next action
+  - pair: showdar-quality vs showdar-ship
+    boundary: quality plans scenario coverage and confidence; ship decides whether release or handoff evidence is sufficient
+  - pair: showdar-upgrade vs showdar-build
+    boundary: upgrade changes dependency or platform compatibility; build changes application behavior within the supported stack

package/router/skill-map.yaml

@@ -0,0 +1,54 @@
+version: 2
+principles:
+  - select the smallest sufficient flagship skill
+  - evidence before edits for unknown failures
+  - preserve user changes and repository instructions
+  - prefer bounded coherent changes over broad cleanup
+  - require fresh verification before completion claims
+  - require explicit approval before production-impacting actions
+routes:
+  understand:
+    triggers: ["understand repo", "architecture", "trace flow", "dependency", "impact analysis", "where should this live"]
+    skill: showdar-understand
+  plan:
+    triggers: ["plan feature", "implementation plan", "scope", "break down", "architecture approach"]
+    skill: showdar-plan
+  design:
+    triggers: ["design UI", "redesign", "UX", "responsive", "visual polish", "accessibility", "design system"]
+    skill: showdar-design
+  build:
+    triggers: ["implement", "build feature", "refactor", "minimal patch"]
+    skill: showdar-build
+  debug:
+    triggers: ["bug", "crash", "regression", "wrong behavior", "build failure", "jank", "memory leak", "intermittent"]
+    skill: showdar-debug
+  test:
+    triggers: ["test strategy", "regression test", "integration test", "E2E", "test coverage"]
+    skill: showdar-test
+  review:
+    triggers: ["review", "PR review", "code review", "maintainability review", "performance review"]
+    skill: showdar-review
+  upgrade:
+    triggers: ["upgrade dependency", "framework upgrade", "runtime upgrade", "migration", "breaking change"]
+    skill: showdar-upgrade
+  ship:
+    triggers: ["release readiness", "ready to release", "ship", "handoff", "package verification"]
+    skill: showdar-ship
+  recover:
+    triggers: ["resume interrupted implementation", "recover partial work", "session stopped", "continue partial work", "missing context"]
+    skill: showdar-recover
+  git:
+    triggers: ["commit", "stage only task files", "merge branch", "rebase branch", "cherry-pick commit", "git conflict", "push branch", "clean merged branches", "finish git workflow"]
+    skill: showdar-git
+  requirements:
+    triggers: ["requirements", "business rules", "acceptance criteria", "user stories", "use cases", "requirement matrix", "missing requirement", "ambiguity"]
+    skill: showdar-requirements
+  quality:
+    triggers: ["QA scenarios", "test scenarios", "regression scope", "risk-based testing", "quality plan", "compatibility matrix", "bug report"]
+    skill: showdar-quality
+  security:
+    triggers: ["threat model", "security review", "security risk", "authz", "authorization", "secrets", "attack surface", "data exposure", "vulnerability", "exploitability"]
+    skill: showdar-security
+  ops:
+    triggers: ["CI/CD", "GitHub Actions", "Docker", "container", "deployment", "deploy", "observability", "rollback", "runtime operations", "staging"]
+    skill: showdar-ops

package/router/triggers.yaml

@@ -0,0 +1,30 @@
+version: 2
+priority:
+  - explicit-user-skill
+  - safety-and-repository-instructions
+  - showdar-git
+  - showdar-recover
+  - showdar-debug
+  - showdar-security
+  - showdar-ops
+  - showdar-ship
+  - showdar-review
+  - showdar-quality
+  - showdar-requirements
+  - showdar-upgrade
+  - showdar-design
+  - showdar-plan
+  - showdar-understand
+  - showdar-test
+  - showdar-build
+rules:
+  - if root cause is unknown prefer showdar-debug over showdar-build
+  - if requirements or change surface are unresolved prefer showdar-plan over showdar-build
+  - if the task is read-only do not route into implementation or shipping actions
+  - one flagship skill should normally own the current phase; transition only when its stop condition is met
+  - local Git commit, staging, branch, merge, rebase, conflict, cleanup, and explicit push intent routes to showdar-git
+  - explicit rebase, cherry-pick, merge, or Git conflict operations route to showdar-git; interrupted implementation recovery routes to showdar-recover
+  - product or business input, missing requirements, business rules, user stories, use cases, acceptance criteria, and requirement readiness route to showdar-requirements
+  - QA scenarios, risk-based coverage, regression scope, compatibility matrices, exploratory checks, and bug-report quality route to showdar-quality
+  - explicit security, authz, secrets, exposure, attack-surface, threat, or exploitability intent routes to showdar-security before general review
+  - operational CI/CD, container, environment, deployment, observability, rollback, or runtime intent routes to showdar-ops; release readiness remains showdar-ship and Git-only work remains showdar-git

package/skills/showdar-build/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: showdar-build
+description: Use when implementing or refactoring an agreed application change within existing architecture and contracts.
+---
+
+# Showdar Build
+
+## Purpose
+
+- Convert an approved requirement/plan into maintainable production code.
+- Preserve existing ownership boundaries and public contracts unless change is explicitly required.
+- Minimize blast radius without cutting required correctness, error handling, or tests.
+- Make implementation decisions evidence-based and stack-native.
+- Read `references/minimal-change.md` and `references/architecture-boundaries.md` before introducing new abstractions.
+
+## When to use
+
+- Implementing a feature, refactor, bug fix after root cause is known, or architecture-safe change.
+- Applying an approved UI implementation after design decisions are clear.
+- Small migrations where the upgrade-specific analysis is already complete.
+- Completing a bounded task recovered from a previous session.
+
+## When not to use
+
+- Root cause is unknown; use showdar-debug.
+- Requirements/change surface are unclear and multiple approaches remain; use showdar-plan.
+- The work is only review or testing strategy.
+- Production deploy/release actions belong to showdar-ship.
+
+## Inputs and assumptions
+
+- User outcome and current repository conventions are understood.
+- Relevant tests/build/typecheck commands are known or discoverable.
+- Existing public interfaces and state ownership are constraints unless explicitly changed.
+- For dirty repositories, distinguish user work from this task before editing.
+- `scripts/change-surface.mjs` can summarize current git changes without mutation.
+
+## Non-negotiable rules
+
+- Change the smallest coherent surface that fully satisfies the behavior.
+- Never “fix” uncertainty with broad optional chaining, swallowed exceptions, retries, or cache clearing.
+- Preserve or improve type safety at external/data boundaries.
+- Handle expected error/recovery behavior explicitly using `references/error-handling.md`.
+- Do not introduce a generic abstraction for one use unless it creates a real ownership/volatility boundary.
+- Keep comments focused on why/non-obvious constraints, not restating code.
+- Add/adjust tests at the lowest level that can fail for the intended regression/behavior.
+- Do not rewrite unrelated formatting or files.
+
+## Workflow
+
+### Phase 1 — pre-change check
+- Read repository instructions and current relevant implementation/tests.
+- Confirm exact change surface and must-not-change contracts.
+- Inspect current diff/status so unrelated user changes are protected.
+
+### Phase 2 — define behavior proof
+- Identify the test or executable scenario that proves the requested behavior.
+- For a defect, reproduce the regression first where practical.
+- For new behavior, encode the smallest useful failing/acceptance test before implementation when the project supports it.
+
+### Phase 3 — implement minimal coherent change
+- Follow existing naming, dependency injection, state ownership, and error contracts.
+- Keep new code local until a true reusable boundary exists.
+- Update public types/contracts deliberately when required.
+- Use `references/feature-flags.md` only when rollout/reversibility justifies a flag.
+
+### Phase 4 — stack-specific pass
+- Read the matching file under `stacks/` for lifecycle, rendering, native, server/client, or event-loop hazards.
+- Check generated/native files only if the change requires them.
+
+### Phase 5 — verification
+- Run targeted test first, then relevant suite/typecheck/lint/build.
+- Inspect final diff for unrelated changes, duplicated policy, unsafe fallback, and missing edge behavior.
+- Verify all claims from fresh command output.
+
+## Decision points
+
+- One function change vs new service? Prefer local unless ownership/reuse demands a boundary.
+- Error can be recovered here? Handle with context; otherwise propagate without swallowing cause.
+- Behavior can race/retry? Model idempotency/concurrency explicitly rather than adding debounce blindly.
+- Existing design/system pattern safe? Follow it; otherwise document the targeted deviation.
+- Rollout risk high? Consider flag/staged path with explicit removal condition.
+
+## Stack detection
+
+- React: read `stacks/react.md` for state/effect/render/accessibility traps.
+- Next.js: read `stacks/nextjs.md` for server/client/cache/runtime boundaries.
+- React Native: read `stacks/react-native.md` for lifecycle/list/native-performance concerns.
+- Flutter: read `stacks/flutter.md` for rebuild/async/layout/state concerns.
+- Node/Fastify: read `stacks/node-fastify.md` for validation/event-loop/resource lifecycle.
+- TypeScript: read `stacks/typescript.md` for unknown-boundary validation, unions, and public contract typing.
+- NestJS: use `stacks/node-nestjs.md` for module/provider/request ownership and transaction/error boundaries.
+- Dart, Swift, Kotlin, and Rust/Tauri: read the matching stack file for lifecycle, concurrency, native, and release constraints.
+- Unsupported stacks: inspect project conventions and apply the same minimal/coherent contract.
+
+## Failure modes
+
+- Shotgun edits across layers because ownership was not identified.
+- “Defensive” null/error handling that hides the real contract violation.
+- Test passes only because a dependency is mocked away.
+- New abstraction increases indirection without reducing policy duplication or volatility.
+- Implementation changes public behavior without updated types/tests/docs.
+- Performance-sensitive loop/render path gets more allocations or I/O without measurement.
+- Native/build files changed by guesswork.
+
+## 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 requested behavior is implemented, the relevant tests/builds pass freshly, and final diff contains no unexplained changes.
+
+## Escalation conditions
+
+- Ask when implementation exposes an unresolved product choice or compatibility break not covered by the plan.
+- Escalate destructive migration, secret, publishing, or production action.
+- Return to debugging if the assumed root cause fails under the regression test.
+- Return to planning if the required change surface expands into independent subsystems.
+
+## Verification
+
+- Run the narrow behavior/regression test and read the result.
+- Run typecheck/analyzer/compiler as applicable.
+- Run relevant integration/build/platform checks for touched boundaries.
+- Inspect `git diff` or equivalent for unrelated edits and accidental generated files.
+- For performance-sensitive changes, compare measured path before/after when feasible.
+- Ensure no secrets/logged sensitive data were introduced.
+
+## Output contract
+
+- **Implemented** — concise behavior and exact change surface.
+- **Why this shape** — ownership/contract rationale when non-obvious.
+- **Tests/verification** — commands actually run and outcomes.
+- **Risks/unverified** — anything not proven locally.
+- **Follow-up** — only required follow-up; omit speculative cleanup.
+
+## Anti-patterns
+
+- Opportunistic repository-wide refactor during a feature fix.
+- Adding `try/catch` that returns null/default for unknown failures.
+- Threading booleans through layers instead of modeling real state.
+- Memoizing every React/Flutter subtree without measurement.
+- Duplicating existing token/config/business policy instead of using the owner.
+- Declaring done after code edits without fresh verification.
+
+## Example
+
+User request: “Prevent duplicate submit on payment confirmation.”
+- Confirm whether duplicate effect is UI re-entry, network retry, or backend idempotency before patching.
+- Add the lowest-level regression that reproduces the confirmed duplicate path.
+- Implement minimal guard/idempotency at the true owner, not every caller.
+- Verify normal retry/recovery still works.
+- See `examples/change-surface.md` for how to bound the patch.

package/skills/showdar-build/data/change-smells.csv

@@ -0,0 +1,24 @@
+id,category,pattern,signal,risk,preferred_response,verification,tags,reference,stack
+shotgun-policy,boundaries,shotgun change,same policy edited in many unrelated files,inconsistent behavior,find existing owner and change once,caller tests cover shared policy,ownership duplication,references/minimal-change.md,*
+wrong-owner,boundaries,symptom guard in caller,callers add null or retry guards around shared failure,sibling callers remain broken,patch shared boundary after tracing callers,regression through all callers,root cause boundary,references/architecture-boundaries.md,*
+layer-leak,boundaries,domain policy in UI,component decides persistence or authorization,unreusable and bypassable policy,move policy to domain/service owner,unit plus boundary test,layering policy,references/architecture-boundaries.md,react
+adapter-leak,boundaries,persistence details leak out,callers construct SQL or response DTO,storage change multiplies across callers,keep adapter contract and map at boundary,adapter integration test,persistence boundary,references/architecture-boundaries.md,node
+public-drift,contracts,public contract drift,caller behavior changes without type/schema update,downstream breakage,make contract change explicit and test consumers,compile plus contract fixture,api contract,references/architecture-boundaries.md,typescript
+serialization-drift,contracts,serialization shape drift,internal object passed as wire/storage data,missing fields or leaking internals,define serializer and compatibility cases,round-trip and old fixture,serialization,references/error-handling.md,node
+boolean-explosion,state,boolean explosion,new flags threaded through many layers,hidden invalid combinations,model explicit state only when combinations are real,table tests for allowed states,state machine,references/minimal-change.md,typescript
+mirrored-state,state,mirrored derived state,props/server data copied into local state,stale UI and extra synchronization,derive or name independent draft state,mutation then rerender test,state ownership,references/architecture-boundaries.md,react
+async-fire-forget,async,unobserved async work,promise started without owner or error path,unhandled failure or stale side effect,await or explicitly own/cancel task,test rejection and disposal,async ownership,references/error-handling.md,node
+disposed-context,async,disposed context use,await then UI/native context is used,crash or stale navigation,guard lifecycle or cancel operation,recreate disposal scenario,lifecycle async,references/error-handling.md,react-native
+retry-duplicate,async,unbounded retry,network retry repeats non-idempotent effect,duplicate side effect,add idempotency and bounded classified retry,duplicate request integration test,idempotency,references/error-handling.md,node
+swallowed-error,errors,silent fallback,catch returns default without evidence,masked production defect,preserve cause and expose actionable state,assert error path,errors,references/error-handling.md,*
+wrong-error-layer,errors,error handled at wrong layer,low layer invents UI message or high layer lacks context,poor recovery and inconsistent UX,handle where recovery context exists,error contract test,error ownership,references/error-handling.md,*
+validation-late,validation,late validation,untrusted input reaches domain or DB,ambiguous failures and injection risk,validate at trust boundary and preserve domain checks,invalid input boundary test,input validation,references/error-handling.md,node
+cache-without-owner,caching,cache without invalidation owner,write path updates source but not related cache,stale reads,define key/version/invalidation owner,mutation then read test,cache invalidation,references/minimal-change.md,*
+cache-clear-patch,caching,global cache clear,fix clears all cache after one mutation,latency and hides key ownership,repair affected key/version only,assert unrelated cache survives,cache scope,references/minimal-change.md,*
+race-last-write,concurrency,last response wins,concurrent requests update same state by completion order,stale result overwrites newer state,sequence/cancel/version writes,controlled ordering test,race ordering,references/minimal-change.md,*
+lock-too-wide,concurrency,global lock around unrelated work,one slow task blocks all accounts/items,throughput collapse,lock only shared invariant and document ceiling,parallel unrelated work test,lock scope,references/minimal-change.md,node
+transaction-split,data,transaction split,related writes commit in separate operations,partial state on failure,keep invariant writes in one transaction,integration rollback test,transaction,references/architecture-boundaries.md,node
+feature-flag-permanent,rollout,permanent feature flag,flag has no owner or removal condition,dead branches and untested behavior,record default owner and delete trigger,branch tests plus expiry check,feature flag,references/feature-flags.md,*
+native-guess,native,native file guess,project config changed without target build evidence,platform-only failure,inspect generated/owned config then build affected target,native build or analyzer,native configuration,references/architecture-boundaries.md,react-native
+type-assertion,type-safety,assertion chain,external data cast through any or non-null assertions,runtime crash and erased contract,narrow unknown with validation,malformed payload test,type safety,references/error-handling.md,typescript
+premature-abstraction,maintainability,premature abstraction,new generic layer has one consumer,indirection without leverage,keep local until reuse or volatility boundary,target behavior test,abstraction,references/minimal-change.md,*

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

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "skill": "showdar-build",
+  "datasets": [
+    {
+      "file": "data/change-smells.csv",
+      "idField": "id",
+      "requiredColumns": ["id", "category", "pattern", "signal", "risk", "preferred_response", "verification", "tags", "reference", "stack"],
+      "searchableFields": ["category", "pattern", "signal", "risk", "preferred_response", "verification", "tags"],
+      "filterFields": ["category", "stack"],
+      "reference": "references/minimal-change.md"
+    }
+  ]
+}

package/skills/showdar-build/examples/change-surface.md

@@ -0,0 +1,18 @@
+# Example change surface
+
+Request: add an optional `includeArchived` filter to the project list.
+
+Input evidence:
+- The route calls `ProjectService.list` and returns the existing DTO.
+- The repository already stores `archivedAt`; no migration is required.
+- Two callers use the service: the dashboard and the export job.
+
+Reasoning:
+1. Add the filter to the internal query input with a default of `false`.
+2. Keep the response shape and pagination cursor unchanged.
+3. Check both callers because the export job must intentionally opt in or out.
+4. Add a service test for default, true, and false values, plus a route test.
+
+Expected output: changed service/query code, caller proof, and a short list of
+files intentionally untouched. Verification must include the focused tests and
+the repository typecheck; a database schema change would be out of scope.

package/skills/showdar-build/references/architecture-boundaries.md

@@ -0,0 +1,3 @@
+# Architecture boundaries
+
+Follow existing dependency direction unless the requested change exposes a concrete defect. Keep domain policy out of UI glue, persistence details out of callers, and platform behavior behind explicit seams. Before adding a seam, name its owner, input/output contract, lifecycle, and second concrete consumer or volatility it isolates. Preserve public contracts unless change is requested; if they change, update types, serializers, consumers, and tests together.

package/skills/showdar-build/references/error-handling.md

@@ -0,0 +1,3 @@
+# Error handling
+
+Handle errors at the layer that can add recovery or context. Preserve original cause and correlation without secrets. Distinguish expected domain failures, cancellation, validation, programmer errors, and infrastructure failures. Map errors once at the boundary that owns the contract; do not catch to return an ambiguous default. User-visible states need a safe explanation, recovery action, and pending/disabled behavior where relevant. Test both success and failure paths.

package/skills/showdar-build/references/feature-flags.md

@@ -0,0 +1,3 @@
+# Feature flags
+
+Use a flag when rollout risk, compatibility, or staged migration justifies it. Define owner, default, evaluation boundary, exposure scope, telemetry, both branch contracts, rollback action, and removal condition. Test enabled, disabled, missing, and malformed configuration. Do not use a flag to hide unfinished code or create a permanent branch for a local refactor.

package/skills/showdar-build/references/minimal-change.md

@@ -0,0 +1,3 @@
+# Minimal coherent change
+
+Minimal does not mean fewest lines. It means the smallest change that completely preserves required invariants, error handling, tests, and ownership boundaries. Start by tracing every caller of the owning function, then write the narrowest behavior proof. Keep a change local unless a shared contract or true volatility boundary requires movement. Avoid unrelated cleanup, but do not omit a necessary boundary or regression test to keep the diff small.

package/skills/showdar-build/scripts/change-surface.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+const cwd=process.argv[2]??process.cwd();
+const run=(args)=>{const r=spawnSync('git',args,{cwd,encoding:'utf8'});return r.status===0?r.stdout.trim():null};
+console.log(JSON.stringify({status:run(['status','--short']),diffStat:run(['diff','--stat']),changed:run(['diff','--name-only'])?.split('\n').filter(Boolean)??[],staged:run(['diff','--cached','--name-only'])?.split('\n').filter(Boolean)??[]},null,2));

package/skills/showdar-build/stacks/dart.md

@@ -0,0 +1,3 @@
+# Dart build guidance
+
+Keep domain state distinct from widget state, make nullability meaningful, and model `Future` cancellation or stale-result behavior explicitly. Use immutable value objects at boundaries, keep expensive work out of build methods, and dispose streams/controllers at their owner. Run analyzer and tests with the pinned SDK before touching generated files.

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

@@ -0,0 +1,3 @@
+# Flutter build guidance
+
+Keep rebuild scope proportional to state changes and preserve one clear source of truth. Use lazy list/layout primitives, guard `mounted` and context across async gaps, dispose owned resources, and model platform-channel failures. Verify text scaling and release-like targets when layout or native behavior changes.

package/skills/showdar-build/stacks/kotlin.md

@@ -0,0 +1,3 @@
+# Kotlin build guidance
+
+Keep coroutine scope tied to lifecycle or service ownership, model cancellation and failure explicitly, and avoid blocking the main thread. Validate serialized input, keep state single-owned, and use stable identity in lists. Treat Gradle, manifest, resources, permissions, and release variants as part of the change surface when Android behavior changes.

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

@@ -0,0 +1,3 @@
+# Next.js build guidance
+
+Keep client boundaries narrow, make cache and freshness semantics intentional, and model loading/error states at route or data boundaries that can recover. Keep secrets and server-only modules out of the browser bundle. Verify server/client output, hydration, metadata, image cost, and production runtime behavior when those surfaces change.

package/skills/showdar-build/stacks/node-fastify.md

@@ -0,0 +1,3 @@
+# Node/Fastify build guidance
+
+Keep request validation and error contracts explicit at the Fastify boundary. Do not block the event loop with heavy synchronous work. Make plugin, pool, server, worker, and shutdown ownership clear. Keep related persistence side effects transactionally coherent, retries idempotent, and readiness distinct from liveness.

package/skills/showdar-build/stacks/node-nestjs.md

@@ -0,0 +1,3 @@
+# Node, Fastify, and NestJS build guidance
+
+Validate request input at the framework boundary, keep authorization in the service/owner boundary, and make response/error contracts explicit. Do not block the event loop with large synchronous work. Keep related persistence writes transactional, make retries idempotent, and close pools, servers, and workers from one lifecycle owner. Test the real HTTP and persistence boundary when those semantics change.

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

@@ -0,0 +1,3 @@
+# React Native build guidance
+
+Respect navigation and lifecycle; cancel or guard screen-owned async work. Keep heavy synchronous work off interaction paths, use virtualized lists for long content, size image decode to display, and treat keyboard, safe areas, accessibility, and native project/config changes as release-risk surfaces.

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

@@ -0,0 +1,3 @@
+# React build guidance
+
+Keep server, URL, draft, and derived state distinct. Use effects only to synchronize external systems; derive render state directly. Use stable domain keys and semantic HTML/native controls. Profile before memoization and test pending, error, focus, and stale-result paths.

package/skills/showdar-build/stacks/rust-tauri.md

@@ -0,0 +1,3 @@
+# Rust and Tauri build guidance
+
+Validate every command input at the Rust boundary, return typed safe errors, and grant the least capability needed by each window. Keep large payloads out of repeated IPC, make event listeners lifecycle-owned, and avoid blocking the UI path with filesystem or database work. Run Rust tests plus the actual bundle target when capabilities, updater, or native configuration changes.

package/skills/showdar-build/stacks/swift.md

@@ -0,0 +1,3 @@
+# Swift build guidance
+
+Prefer value semantics and explicit actor or queue ownership for shared mutable state. Treat async cancellation and view/task lifetime as part of the contract. Validate decoded external data, keep UI state separate from domain state, and preserve accessibility labels and Dynamic Type. Build the affected scheme when deployment target, capability, package, or native API changes.

package/skills/showdar-build/stacks/typescript.md

@@ -0,0 +1,3 @@
+# TypeScript build guidance
+
+Keep `unknown` at external boundaries until validated; avoid `any` and assertion chains that erase contracts. Model impossible states with discriminated unions, keep async error types explicit, and preserve public exports. Run the repository compiler with its actual `tsconfig` and test serialized inputs rather than trusting structural casts.