@robosoft/skillhub-cli 0.1.1 → 0.3.2

package/skillhub-registry/skills/feature-dev/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: feature-dev
+description: End-to-end feature development workflow that orchestrates understanding, planning, building, refactoring, reviewing, and finalizing a feature. Use this skill whenever the user invokes /feature-dev, /feature, asks to "develop a feature", "ship a feature", "build a feature end-to-end", "implement a complete feature", or signals they want a structured multi-step development process. Apply when the work spans multiple files, multiple concerns, or is too large for a single /build invocation. Apply when the user wants the full lifecycle, not just one piece. Do NOT trigger for simple single-function tasks (use /build) or for code review only (use /review).
+---
+
+# Feature Development Workflow
+
+This is a **workflow**, not a single-purpose skill. It orchestrates the full feature development lifecycle, drawing on `/build`, `/refactor`, `/review`, and the always-on rules.
+
+Use this when a feature is non-trivial — meaning it touches multiple files, has user-visible behavior, will be code-reviewed by a human, and needs to ship cleanly.
+
+---
+
+## How This Workflow Differs From `/build`
+
+- **`/build`** is for one-shot implementation: write a function, write a component, write an endpoint.
+- **`/feature-dev`** is for shipping a feature: many files, design decisions, tests, review pass, validation.
+
+If the task is small, prefer `/build`. Use `/feature-dev` when the work has phases.
+
+---
+
+## The Six Phases
+
+The workflow has six phases. Don't skip phases unless explicitly justified. Be explicit when transitioning between phases — say "Moving to Phase N" so the user knows where things stand.
+
+### Phase 1: Understand
+
+**Goal:** Establish what the feature actually is, before any code.
+
+Produce:
+- A 2-3 sentence statement of what the feature does, in plain English
+- The user-visible behavior (input → output, or interaction → outcome)
+- The success criteria — how do we know it works?
+- What's explicitly out of scope
+
+**Stop and ask** if any of these are unclear. Don't proceed on assumptions for a multi-file feature — the cost of misunderstanding compounds.
+
+### Phase 2: Plan
+
+**Goal:** Decide the approach before writing code.
+
+Produce:
+- The files that will be created or modified
+- The shape of any new APIs (function signatures, props, endpoints, types)
+- The data flow (what calls what, in what order)
+- The edge cases identified (use the checklist from `skills/testing`)
+- One alternative considered and why it was rejected
+- Any open questions that block implementation
+
+**Show the plan to the user before writing code** for non-trivial features. Get a thumbs-up. This catches misalignment cheaply.
+
+For simple features, a brief plan inline is enough. Use judgment.
+
+### Phase 3: Build
+
+**Goal:** Implement the plan.
+
+Apply `skills/build` workflow within this phase. All `rules/` apply. Domain skills (`react`, etc.) layer on if relevant.
+
+Build incrementally:
+- Get the core path working first (happy path, no edge cases)
+- Add edge case handling next
+- Add error handling
+- Wire up to real data sources / dependencies last
+
+Don't build the whole thing in one shot if you can avoid it. Smaller increments are easier to debug if something goes wrong.
+
+### Phase 4: Test
+
+**Goal:** Verify the feature works as specified.
+
+Apply `skills/testing` rules:
+- Happy path tests
+- Edge case tests (the ones identified in Phase 2)
+- Failure path tests
+- Integration test if the feature crosses system boundaries
+
+If tests are skipped (Fast Mode, prototype, user explicitly waived), state that clearly. Skipping tests is a deliberate choice, not a default.
+
+### Phase 5: Refactor
+
+**Goal:** Clean up before review.
+
+Apply `skills/refactor` rules:
+- Re-read the code as a stranger would
+- Apply `rules/code-standards.md` strictly
+- Eliminate any anti-patterns that crept in
+- Remove dead code, debugging artifacts, commented-out code, TODOs that don't belong
+
+Behavior must not change in this phase. If you find a bug, that's a separate fix — not part of refactor.
+
+### Phase 6: Review
+
+**Goal:** Catch what self-review missed.
+
+Apply `skills/review` rules to the full feature:
+- Run the review checklist (correctness, security, performance, standards, maintainability, tests)
+- Categorize findings (Critical / Improvement / Minor)
+- Fix Critical and Improvement findings before declaring done
+- Note Minor findings for follow-up if they're not addressed
+
+If `/strict` mode is active, apply maximum rigor in this phase.
+
+---
+
+## Output Format
+
+Use phase headers to structure the response. The user should always know which phase you're in:
+
+Phase 1: Understand[Statement of what the feature does, success criteria, etc.]
+Phase 2: Plan[The plan, with files to touch, edge cases, alternatives.][Pause here for confirmation if non-trivial.]
+Phase 3: Build[Code, file by file.]
+Phase 4: Test[Test code.]
+Phase 5: Refactor[Cleanup notes; usually inline edits to the code above.]
+Phase 6: Review[Self-review findings, categorized.]
+
+For shorter features, phases can collapse together — but always label them so the user can follow the structure.
+
+---
+
+## When to Pause for User Input
+
+Pause and confirm in these situations:
+
+- **End of Phase 1** if the feature scope is fuzzy
+- **End of Phase 2** if the plan involves design decisions the user should approve
+- **Mid-Phase 3** if you hit an unexpected complication that changes the approach
+- **End of Phase 6** before declaring complete, if findings warrant user attention
+
+Don't pause for trivial confirmation ("Should I write the function now?"). Pause for decisions.
+
+---
+
+## When to Abandon the Workflow
+
+If during Phase 1 or Phase 2 it becomes clear that:
+
+- The feature is too small for this workflow → say so, switch to `/build`
+- The feature is actually a refactor in disguise → switch to `/refactor`
+- The requirements are too unclear to proceed → stop, gather requirements
+- The scope is too large for one session → break it into smaller features
+
+Don't grind through phases on a task that doesn't need them. The workflow is a tool, not a ritual.
+
+---
+
+## Composition With Other Skills
+
+This workflow naturally composes with:
+
+- **`/strict`** — applies maximum rigor at every phase, especially Phase 5 and 6
+- **`/fast`** — collapses phases (Plan → Build → minimal Test, skip rigorous Review). For prototypes only.
+- **Domain skills** (`react`, `testing`, `performance`) — layer in their rules during the relevant phases
+
+Multiple skills active simultaneously is normal. The workflow provides the structure; the skills provide the content.
+
+---
+
+## What This Workflow Does NOT Cover
+
+- **Architecture-level design** that needs discussion before any feature exists — that's a design conversation, not feature dev
+- **Bug fixes** — those have their own rhythm; don't force them through six phases
+- **Pure refactors** — use `/refactor`
+- **Code review of existing PRs** — use `/review`
+

package/skillhub-registry/skills/frontend/app/SKILL.md

@@ -0,0 +1,28 @@
+# Frontend App Development Skill
+
+## Purpose
+
+Use this skill when developing frontend web application features in React, Next.js, TypeScript, or similar UI stacks.
+
+## Workflow
+
+1. Read the requirement and identify the user flow.
+2. Inspect existing project structure before creating files.
+3. Reuse existing components, hooks, schemas, and services.
+4. Create a small implementation plan.
+5. Implement UI with loading, empty, error, and success states.
+6. Validate accessibility, typing, and responsive behavior.
+7. Summarize changed files and risks.
+
+## Development Rules
+
+- Do not put business logic directly inside JSX.
+- Do not invent APIs or data fields.
+- Keep server, client, and service responsibilities separate.
+- Prefer typed models and schema validation.
+- Avoid new dependencies unless clearly justified.
+- Follow attached rules and domain files before generic advice.
+
+## Expected Output
+
+The final implementation should include clear file changes, usage instructions, and validation steps.

package/skillhub-registry/skills/frontend/app/rules/main.md

@@ -0,0 +1,6 @@
+# Frontend App Skill Rules
+
+- Follow the installed frontend anti-pattern rules.
+- Keep components focused and typed.
+- Respect existing project architecture.
+- Add accessible labels and keyboard-friendly interactions.

package/skillhub-registry/skills/frontend/app/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "frontend/app",
+  "version": "1.0.0",
+  "type": "skill",
+  "section": "skills",
+  "description": "Develop production-ready frontend web application features with architecture, UI states, accessibility, and validation.",
+  "entry": "SKILL.md",
+  "category": "frontend",
+  "tags": ["frontend", "react", "nextjs", "typescript", "web-app"]
+}

package/skillhub-registry/skills/frontend/app/templates/feature/{{kebabName}}.tsx.hbs

@@ -0,0 +1,11 @@
+export type {{pascalName}}Props = {
+  title: string;
+};
+
+export function {{pascalName}}({ title }: {{pascalName}}Props) {
+  return (
+    <section aria-labelledby="{{kebabName}}-title">
+      <h1 id="{{kebabName}}-title">{title}</h1>
+    </section>
+  );
+}

package/skillhub-registry/skills/frontend-app/SKILL.md

@@ -0,0 +1,48 @@
+# Frontend App Development Skill
+
+## Description
+
+Use this skill when the user asks to build, modify, review, or debug a frontend application or frontend feature.
+
+## When to Use
+
+Trigger this skill for React, Next.js, UI screens, forms, dashboards, routing, API integration, state management, component design, accessibility, responsive layout, and frontend architecture tasks.
+
+## Workflow
+
+1. Understand the user story, target screen, data source, and acceptance criteria.
+2. Inspect the existing project structure before creating new folders.
+3. Prefer feature-based organization when the project supports it.
+4. Build the smallest complete implementation with clear loading, empty, error, and success states.
+5. Keep business logic outside presentational components.
+6. Validate with type-checking, linting, build, tests, or manual steps.
+7. Summarize changed files and risks clearly.
+
+## Frontend Rules
+
+- Use TypeScript types for props, API response contracts, and form values.
+- Do not hardcode API URLs inside components.
+- Keep reusable UI in shared/ui or components/ui depending on the project.
+- Use semantic HTML before custom div soup, because div soup is how frontend dignity dies.
+- Add accessible labels, keyboard flow, focus states, and readable error messages.
+- Avoid silent loading states. Every async flow needs loading, error, and empty handling.
+- Match the existing design system before introducing new styling patterns.
+- Avoid global state unless data is genuinely shared across unrelated screens.
+
+## Output Format
+
+When implementing, provide:
+
+- Files changed
+- Important decisions
+- Validation performed
+- Any assumptions or risks
+
+## Definition of Done
+
+- Requirement is implemented end-to-end
+- UI is responsive
+- Loading, empty, and error states exist
+- Accessibility basics are covered
+- Existing patterns are respected
+- Build or validation command is documented

package/skillhub-registry/skills/frontend-app/rules/main.md

@@ -0,0 +1,6 @@
+# Frontend App Skill Rules
+
+- Read installed rules before writing code.
+- Read installed domain knowledge if the feature touches business behavior.
+- Prefer small composable components over giant screen files.
+- Keep mutation and data fetching logic easy to test.

package/skillhub-registry/skills/frontend-app/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "frontend-app",
+  "version": "1.0.0",
+  "type": "skill",
+  "section": "skills",
+  "description": "Develop production-ready frontend applications using existing architecture, reusable components, validation, accessibility, and clean delivery flow.",
+  "category": "frontend",
+  "tags": ["frontend", "react", "nextjs", "architecture", "ui"],
+  "entry": "SKILL.md",
+  "compatibleWith": ["cursor", "claude", "codex", "gemini", "opencode"]
+}

package/skillhub-registry/skills/frontend-app/templates/feature/{{kebabName}}.tsx.hbs

@@ -0,0 +1,11 @@
+export type {{pascalName}}Props = {
+  title?: string;
+};
+
+export function {{pascalName}}({ title = "{{title}}" }: {{pascalName}}Props) {
+  return (
+    <section aria-labelledby="{{kebabName}}-title">
+      <h1 id="{{kebabName}}-title">{title}</h1>
+    </section>
+  );
+}

package/skillhub-registry/skills/performance/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: performance
+description: Performance optimization standards covering when to optimize, how to measure, common bottleneck patterns, frontend rendering performance, network optimization, bundle size, lazy loading, memoization, caching strategies, and database query performance. Use this skill whenever the user mentions performance, slow code, optimization, profiling, bottlenecks, page speed, render performance, lag, jank, bundle size, lazy loading, code splitting, memoization, caching, query optimization, N+1 queries, or asks why something is slow. Apply when the user reports an app feels slow, asks to make code faster, requests profiling help, mentions Lighthouse / Web Vitals / Core Web Vitals / FCP / LCP / TTI / CLS, or asks to reduce load times. Trigger even when performance is implied — for example, when the user complains about response times or asks if there's a faster way.
+---
+
+# Performance Skill
+
+This skill applies the org's performance standards. It loads when the task involves measuring, diagnosing, or optimizing performance.
+
+These rules layer on top of `rules/general.md`, `rules/code-standards.md`, and `rules/anti-patterns.md`.
+
+---
+
+## The Iron Rule: Measure Before Optimizing
+
+**No optimization without measurement.** This is non-negotiable.
+
+- Without measurement, you don't know where the bottleneck is — and intuition is wrong more often than not.
+- Without measurement, you can't prove the optimization helped (it often makes things slower).
+- Without measurement, you have no way to know if a regression sneaks in later.
+
+**Workflow:**
+1. Reproduce the slow scenario reliably.
+2. Profile it. Identify the actual bottleneck.
+3. Form a hypothesis about the cause.
+4. Make ONE change.
+5. Re-measure. Did it actually improve? By how much?
+6. Document the before/after numbers in the PR.
+
+If you skip steps 1-2 and jump to "I'll add memoization here," you are guessing.
+
+## Common False Bottlenecks
+
+These are the optimizations developers reach for first that usually don't matter:
+
+- **Adding `useMemo` / `useCallback` everywhere** — usually adds overhead without benefit
+- **Switching `forEach` to `for` loops** — negligible in modern JS engines
+- **Micro-optimizing a function** — when the bottleneck is actually network or rendering
+- **Replacing a library** — when your own code is the slow part
+
+The actual bottlenecks are usually:
+
+- **Network** — too many requests, slow endpoints, large payloads
+- **Rendering** — too many components re-rendering, large lists without virtualization
+- **Database** — N+1 queries, missing indexes, full table scans
+- **Bundle size** — shipping code that isn't needed yet
+- **Blocking the main thread** — synchronous heavy work in a UI context
+
+## Frontend Rendering Performance
+
+### Re-render avoidance
+
+Before reaching for memoization, ask:
+
+1. **Is the parent re-rendering unnecessarily?** Fix that instead.
+2. **Is state located too high in the tree?** Move it down.
+3. **Is the component pure?** Same input → same output. If not, fix that first.
+
+When memoization is genuinely needed:
+
+- Wrap the **child component** in `React.memo`
+- Use `useMemo` for **expensive calculations** (not primitives)
+- Use `useCallback` for **functions passed to memoized children**
+- Profile with React DevTools Profiler to confirm the wins
+
+### Large lists
+
+- **Virtualize** lists over ~100 items (`react-window`, `@tanstack/react-virtual`)
+- **Stable keys** — never use array index as key for dynamic lists (causes re-render of all items on reorder)
+- **Pagination or infinite scroll** for data sets you can't bound
+
+### Images and media
+
+- **Lazy load** below-the-fold images (`loading="lazy"`)
+- **Modern formats** (WebP, AVIF) with fallbacks
+- **Responsive images** (`srcset` / `<picture>`) — don't ship desktop images to mobile
+- **Compress** before upload; never trust raw uploads
+
+## Network Performance
+
+### Request reduction
+
+- **Batch requests** when an API supports it
+- **Cache aggressively** — both browser cache (HTTP headers) and in-memory (TanStack Query, SWR)
+- **Eliminate waterfalls** — parallelize independent requests with `Promise.all`
+- **Avoid over-fetching** — request only the fields you need (GraphQL, sparse fieldsets)
+- **Avoid under-fetching** — don't make 10 sequential calls when one batched call would do
+
+### Payload size
+
+- **Compress responses** (gzip/brotli at the server)
+- **Paginate** large collections
+- **Don't return what you don't render** — strip server-only fields
+
+### Critical path
+
+- **Defer non-critical JS** — `defer`/`async` script tags, dynamic imports
+- **Preload critical assets** — `<link rel="preload">` for the fonts/scripts that block render
+- **Inline critical CSS** if first paint is the bottleneck
+
+## Bundle Size
+
+- **Code-split by route.** Don't ship the admin dashboard JS to logged-out users.
+- **Code-split heavy components** — modals, charts, editors that aren't needed on initial render.
+- **Tree-shake aggressively** — import only what you use (`import { foo } from 'lib'` not `import lib from 'lib'`).
+- **Audit large dependencies.** Use `bundle-analyzer` or equivalent. A 200KB date library is rarely justified.
+- **Polyfill conditionally** — modern browsers don't need legacy polyfills.
+
+## Backend Performance
+
+### Database
+
+- **N+1 is the most common bottleneck.** If a request makes one query, then loops over results making more queries → that's N+1. Use joins, `IN` queries, or a DataLoader pattern.
+- **Index the columns you filter / sort by.** Missing indexes turn O(log n) lookups into O(n) scans.
+- **Don't `SELECT *`** — return the columns you need.
+- **Paginate.** Never return unbounded result sets.
+- **Watch for accidental table scans** — explain plan your slow queries.
+
+### Caching
+
+- **Cache the expensive thing, not the cheap thing.** Cache hits should save real work.
+- **Invalidation is the hard part** — design the invalidation strategy before adding the cache.
+- **Layer caches:** CDN → server cache → app-level cache → DB.
+- **Don't cache user-specific data in shared caches** without keying by user.
+
+### Concurrency
+
+- **Async everything that can be async.** Blocking I/O wastes the request thread.
+- **Don't await in a loop** when the calls are independent — use `Promise.all`.
+- **Backpressure matters** — unbounded concurrency exhausts connection pools.
+
+## Measurement Tools
+
+By environment:
+
+- **Browser frontend:** Chrome DevTools Performance tab, React DevTools Profiler, Lighthouse, Web Vitals (LCP, FID, CLS, INP)
+- **Node backend:** `--prof`, `clinic.js`, APM tools (Datadog, New Relic), distributed tracing
+- **Database:** `EXPLAIN ANALYZE`, slow query logs, query analyzers
+- **Network:** browser Network tab, Wireshark, server access logs
+
+Pick a baseline metric *before* optimizing. "It feels faster" is not data.
+
+## Performance Budgets
+
+For frontend, set explicit budgets and fail the build if exceeded:
+
+- **JS bundle:** target < 200KB gzipped for first load
+- **LCP (Largest Contentful Paint):** < 2.5s on 4G
+- **TTI (Time to Interactive):** < 3.5s on mid-range mobile
+- **CLS (Cumulative Layout Shift):** < 0.1
+
+These are starting points. Adjust to your product's actual users and devices.
+
+## When You're Unsure
+
+- **Don't guess what's slow.** Ask the user to share profiler output, network waterfall, or `EXPLAIN ANALYZE` output.
+- **Confirm the user's measurement approach.** "It feels slow" needs investigation before optimization.
+- **Confirm the target device / network.** Optimizing for a desktop on fiber and a phone on 3G are different problems.
+- **Don't apply backend wisdom to frontend** (or vice versa). Bottlenecks differ by environment.
+
+## What NOT to Do
+
+- ❌ Add memoization "just in case"
+- ❌ Replace simple code with "faster" cleverness without measurement
+- ❌ Optimize before code is correct and tested
+- ❌ Apply micro-optimizations to non-hot-path code
+- ❌ Cache without an invalidation strategy
+- ❌ Ship optimization PRs without before/after numbers