@robosoft/skillhub-cli 0.1.2 → 0.3.3

package/skillhub-registry/domain/api.md

@@ -0,0 +1,303 @@
+# Org API Conventions
+
+**Status:** Org-specific decisions for our API surfaces. Layers on top of universal rules in `skills/api/SKILL.md`.
+**Last updated:** 2026-05-06
+**Owner:** [Your name / team]
+
+This file documents *our* specific API conventions — the choices we've made, where the universal skill says "pick one, be consistent."
+
+> **For developers:** When working on our APIs, both this file and `skills/api/SKILL.md` apply. Universal rules are the baseline; this file is the override.
+
+> **For Claude:** This file is loaded only when working in our codebase or on our APIs. Treat its contents as authoritative for any conflict with the universal skill.
+
+---
+
+## How to Use This File
+
+This is a **living document**. When the team decides on a new API convention, it gets added here. When a convention changes, it gets updated here. PRs should update this file when they introduce or modify a convention.
+
+The sections below are templates — fill in your org's actual decisions, or write `[Not yet decided]` until you do.
+
+---
+
+## JSON Field Naming
+
+**Our convention:** `[camelCase | snake_case | PascalCase]`
+
+**Example:**
+```json
+
+{
+"userId": "123",
+"createdAt": "2026-05-06T12:00:00Z"
+}
+
+**Rationale:** [Why we picked this — e.g., "matches our JS clients" or "consistency with database column names"]
+
+---
+
+## Error Response Envelope
+
+**Our shape:**
+
+```json
+
+{
+"error": {
+"code": "[example: INVALID_INPUT]",
+"message": "[example: Human-readable description]",
+"details": [
+{ "field": "[example: email]", "issue": "[example: must be valid]" }
+],
+"request_id": "[example: req_abc123]"
+}
+}
+
+**Error code naming:** `SCREAMING_SNAKE_CASE`, prefixed by domain when ambiguous (e.g., `AUTH_INVALID_TOKEN`, `USER_NOT_FOUND`).
+
+**Stable error codes maintained at:** `[link to error code registry, if any]`
+
+---
+
+## Authentication
+
+**Method:** [Bearer JWT | API Key | Session Cookie | OAuth | etc.]
+
+**Header:** `[example: Authorization: Bearer <token>]`
+
+**Token lifetime:** [e.g., access token: 1h, refresh token: 30d]
+
+**Where tokens come from:** [link to auth service docs]
+
+---
+
+## Versioning
+
+**Strategy:** [URI path | Header | Accept header]
+
+**Current version:** `[v1 | v2 | etc.]`
+
+**Deprecated versions:** [List + sunset dates]
+
+**Breaking change policy:** [e.g., "minimum 6-month deprecation window"]
+
+---
+
+## Pagination
+
+**Style:** [cursor-based | offset-based | hybrid]
+
+**Default page size:** [e.g., 20]
+**Max page size:** [e.g., 100]
+
+**Response shape:**
+```json
+
+{
+"data": [ ... ],
+"pagination": {
+"next_cursor": "[example value]",
+"has_more": true
+}
+}
+
+# Org API Conventions
+
+**Status:** Org-specific decisions for our API surfaces. Layers on top of universal rules in `skills/api/SKILL.md`.
+**Last updated:** 2026-05-06
+**Owner:** [Your name / team]
+
+This file documents *our* specific API conventions — the choices we've made, where the universal skill says "pick one, be consistent."
+
+> **For developers:** When working on our APIs, both this file and `skills/api/SKILL.md` apply. Universal rules are the baseline; this file is the override.
+
+> **For Claude:** This file is loaded only when working in our codebase or on our APIs. Treat its contents as authoritative for any conflict with the universal skill.
+
+---
+
+## How to Use This File
+
+This is a **living document**. When the team decides on a new API convention, it gets added here. When a convention changes, it gets updated here. PRs should update this file when they introduce or modify a convention.
+
+The sections below are templates — fill in your org's actual decisions, or write `[Not yet decided]` until you do.
+
+---
+
+## JSON Field Naming
+
+**Our convention:** `[camelCase | snake_case | PascalCase]`
+
+**Example:**
+```json
+{
+  "userId": "123",
+  "createdAt": "2026-05-06T12:00:00Z"
+}
+```
+
+**Rationale:** [Why we picked this — e.g., "matches our JS clients" or "consistency with database column names"]
+
+---
+
+## Error Response Envelope
+
+**Our shape:**
+
+```json
+{
+  "error": {
+    "code": "[example: INVALID_INPUT]",
+    "message": "[example: Human-readable description]",
+    "details": [
+      { "field": "[example: email]", "issue": "[example: must be valid]" }
+    ],
+    "request_id": "[example: req_abc123]"
+  }
+}
+```
+
+**Error code naming:** `SCREAMING_SNAKE_CASE`, prefixed by domain when ambiguous (e.g., `AUTH_INVALID_TOKEN`, `USER_NOT_FOUND`).
+
+**Stable error codes maintained at:** `[link to error code registry, if any]`
+
+---
+
+## Authentication
+
+**Method:** [Bearer JWT | API Key | Session Cookie | OAuth | etc.]
+
+**Header:** `[example: Authorization: Bearer <token>]`
+
+**Token lifetime:** [e.g., access token: 1h, refresh token: 30d]
+
+**Where tokens come from:** [link to auth service docs]
+
+---
+
+## Versioning
+
+**Strategy:** [URI path | Header | Accept header]
+
+**Current version:** `[v1 | v2 | etc.]`
+
+**Deprecated versions:** [List + sunset dates]
+
+**Breaking change policy:** [e.g., "minimum 6-month deprecation window"]
+
+---
+
+## Pagination
+
+**Style:** [cursor-based | offset-based | hybrid]
+
+**Default page size:** [e.g., 20]
+**Max page size:** [e.g., 100]
+
+**Response shape:**
+```json
+{
+  "data": [ ... ],
+  "pagination": {
+    "next_cursor": "[example value]",
+    "has_more": true
+  }
+}
+```
+
+---
+
+## Rate Limiting
+
+**Default limit:** [e.g., 100 requests / minute / user]
+
+**Limit headers we return:**
+- `X-RateLimit-Limit: 100`
+- `X-RateLimit-Remaining: 87`
+- `X-RateLimit-Reset: 1715000000`
+
+**Endpoints with stricter limits:** [list, e.g., `/auth/login`: 5/min]
+
+---
+
+## Idempotency
+
+**Idempotency-Key support:** [Which endpoints accept it — typically payment, order creation, anything destructive]
+
+**Key format:** [e.g., UUID v4]
+
+**Retention window:** [e.g., 24 hours]
+
+---
+
+## Standard Response Headers
+
+Every response from our APIs includes:
+
+- `X-Request-ID: <uuid>` — for tracing in logs
+- `[Other org-standard headers]`
+
+---
+
+## Endpoints We Never Expose
+
+Some endpoints exist for internal use only. These must:
+
+- Be on a separate base URL or behind internal-only auth
+- Never be linked from public docs
+- [List specific endpoints / patterns here as they get added]
+
+---
+
+## Webhook Conventions
+
+**Signing:** [HMAC-SHA256 with shared secret in `X-Org-Signature` header]
+
+**Retry policy:** [e.g., "5 retries with exponential backoff over 24h"]
+
+**Payload includes:**
+- `event_id` (UUID)
+- `event_type` (dot-namespaced, e.g., `order.created`)
+- `timestamp` (ISO-8601)
+- `data` (event-specific payload)
+
+---
+
+## Common Patterns Across Our APIs
+
+[As your team converges on patterns, document them here. Examples:]
+
+- **Soft deletes** — we use `deleted_at` timestamps, not hard deletes
+- **Timestamps** — all timestamps are ISO-8601 strings in UTC
+- **IDs** — prefixed by resource type (`user_abc123`, `order_xyz789`) — Stripe-style
+- **Currency** — always integer cents, never floating-point dollars
+
+---
+
+## Anti-Patterns Specific to Our Codebase
+
+[Things that have gone wrong before and we want to prevent. Examples:]
+
+- ❌ Don't add `?debug=true` to expose internal details — even gated behind staff auth
+- ❌ Don't return raw database errors in responses
+- ❌ Don't include user emails in URL paths
+
+---
+
+## Open Questions / Pending Decisions
+
+Document things the team hasn't decided yet, so devs know to ask:
+
+- [ ] [Example: "GraphQL adoption — currently REST-only, evaluating"]
+- [ ] [Example: "Federation pattern when we split services"]
+
+---
+
+## How to Propose a Change to These Conventions
+
+See `docs/exception-process.md` (or your org's standard).
+
+Quick version:
+1. Open a PR modifying this file
+2. Tag the API working group
+3. Discussion happens in PR review
+4. Merge requires approval from [designated approvers]

package/skillhub-registry/domain/frontend/web-app.md

@@ -0,0 +1,17 @@
+# Frontend Web App Domain Knowledge
+
+## Scope
+
+This domain file describes common frontend web-app expectations for SkillHub-generated work.
+
+## Architecture Expectations
+
+- Use a feature-first structure for business modules.
+- Keep infrastructure concerns in `lib`, `services`, or adapter folders.
+- Keep design-system components separate from feature components.
+- Use typed API contracts and schema validation where possible.
+- Align with the project router, state, styling, and testing conventions before adding new patterns.
+
+## Product Expectations
+
+Every production page should consider authentication state, permissions, loading state, empty state, error state, responsive layout, and accessibility.

package/skillhub-registry/domain/frontend-app.md

@@ -0,0 +1,46 @@
+# Frontend App Domain Knowledge
+
+## Purpose
+
+This domain file captures reusable product and engineering knowledge for frontend application work.
+
+## Standard Mental Model
+
+A production frontend feature usually has these parts:
+
+- Route or screen entry
+- Data fetching and mutation layer
+- UI components
+- Validation and error handling
+- Loading, empty, success, and failure states
+- Accessibility and responsive behavior
+- Analytics or event tracking when required
+
+## Architecture Guidance
+
+For Next.js or React apps, prefer:
+
+```txt
+src/
+  app/ or pages/
+  features/
+    feature-name/
+      components/
+      hooks/
+      services/
+      types.ts
+      index.ts
+  shared/
+    components/
+    hooks/
+    utils/
+    services/
+```
+
+## Common Risks
+
+- Building a beautiful screen with fake data and no integration path
+- Adding global state for local form state
+- Ignoring mobile layout until QA finds it, the traditional frontend festival
+- Hardcoding API contracts instead of using typed boundaries
+- Skipping loading and error states because the happy path looked cute

package/skillhub-registry/domain/frontend-architecture.md

@@ -0,0 +1,126 @@
+# Frontend Architecture
+
+**Status:** Standard for tech-enabled projects; recommended for others
+**Last updated:** 2026-05-06
+**Owner:** Raj Shah
+
+> **TL;DR:** Organize by features, not layers. Each feature is a folder with components, hooks, services, and a public API via `index.ts`. Shared code lives in `shared/`.
+
+This document describes the recommended folder structure and module boundaries for React projects. It is the standard on our tech-enabled projects and a recommended pattern others can adopt when refactoring or starting new projects. This is a target structure that we're working toward — not every project follows it today, and that's okay.
+
+---
+
+## Why This Structure
+
+Feature-based organization has proven to scale better than layer-based (all components in one folder, all services in another) as projects grow:
+
+- **Ownership is localized.** When you own a feature, all its code lives in one place. Changes don't ripple across the codebase.
+- **Module boundaries prevent spaghetti.** Public APIs via `index.ts` enforce what can and can't be imported, catching circular dependencies early.
+- **Shared code is visible.** When logic is used by 2+ features, it gets promoted to `shared/` and stops being duplicated.
+- **Easier to delete.** When a feature ships or gets retired, removing a feature folder is clean. Removing scattered services and components is error-prone.
+
+---
+
+## The Recommended Folder Structure
+
+```
+src/
+  app/
+    Entry point, routing, top-level providers (auth, theme, query client).
+    The integration layer — not a place for business logic.
+
+  features/
+    <feature-name>/
+      components/     UI components specific to this feature.
+      hooks/          State, side effects, data fetching — feature-scoped.
+      services/       API calls and business logic for this feature.
+      types.ts        Feature-level type definitions.
+      index.ts        Public API — only exports intended for outside the feature.
+
+  shared/
+    components/       Reusable UI across features (Button, Modal, etc.).
+    hooks/            Reusable stateful logic (useFetch, useLocalStorage, etc.).
+    utils/            Pure utility functions (formatDate, parseJson, etc.).
+    constants/        Shared magic-value-free constants.
+    config/           Centralized environment config (see rules/code-standards.md).
+    services/         Shared infrastructure (HTTP client wrapper, analytics SDK setup).
+```
+
+**Each directory's purpose:**
+
+- **`app/`** — Application shell. Routes, top-level component tree, global providers. No business logic lives here.
+- **`features/<feature-name>/`** — A feature is an independently useful piece of the app (a user dashboard, a checkout flow, a settings page). Folder structure mirrors the feature's organization.
+- **`shared/`** — Code used across multiple features. The first place to check before duplicating.
+
+---
+
+## Module Boundaries (Strong Recommendations)
+
+These boundaries make refactoring local and prevent the codebase from becoming a tangle:
+
+- **Features should not import from other features directly.** If Feature A needs something from Feature B, either:
+  - The code goes to `shared/` if it's truly shared.
+  - Feature B exports it via its `index.ts` as a public API.
+  - Or it's a sign that the feature boundary is wrong and should be reconsidered.
+
+- **Only `index.ts` is the public API.** Importing `features/checkout/utils/calculateTax.ts` from outside is a code smell — that's an implementation detail. The feature's `index.ts` should decide what's public.
+
+```typescript
+// features/checkout/index.ts
+export { CheckoutForm } from './components/CheckoutForm';
+export { useCheckoutState } from './hooks/useCheckoutState';
+export type { Order } from './types';
+// calculateTax stays private — not exported
+```
+
+- **Shared code in `shared/`.** If a utility, component, or hook is used by 2+ features, it doesn't live in either feature — it's promoted to `shared/`. This prevents duplication and makes updates centralized.
+
+- **`app/` is the integration layer.** Routing, providers, the root component tree. Business logic (state, side effects, calculations) does not live in `app/`. It lives in features or shared, then integrated in `app/`.
+
+> **Why:** These boundaries make refactoring local. When a feature's internal structure changes, only that feature's code needs to be updated. Without boundaries, refactoring becomes a codebase-wide hunt, and features start depending on each other's internals instead of their public APIs.
+
+---
+
+## When You Don't Need This Structure
+
+Smaller projects and prototypes should use simpler structures:
+
+- **Small projects** (~1-2 features, <~10 components) don't need feature folders. A flat `src/components/` and `src/services/` is clearer.
+- **Throwaway prototypes** don't need architectural discipline — they earn their complexity at real scale.
+- **The structure pays for itself around ~3+ features and ~50+ components.** Below that threshold, simpler is better. Premature structure is its own anti-pattern.
+
+If you're building something small, keep it flat until the need arises.
+
+---
+
+## Migration Guidance
+
+For projects that don't currently follow this structure:
+
+- **Don't refactor wholesale.** Converting an entire codebase to feature-based organization is a major project, not a cleanup task.
+- **Adopt for new features.** As you build new features, use the folder structure. New code sets a pattern.
+- **Refactor on touch.** When doing substantive work in an existing feature, consider promoting it to the structure as part of the change.
+- **Convergence is gradual.** Over time, the codebase drifts toward the structure without a single "big migration" effort.
+
+The goal is to make refactoring normal, not to land on a perfect structure immediately.
+
+---
+
+## What This Document Does NOT Cover
+
+This file is one piece of the architecture picture. Related decisions are documented elsewhere:
+
+- **React conventions** (component structure, hooks, state management patterns, accessibility) — see [`skills/react/SKILL.md`](../skills/react/SKILL.md)
+- **API design and contract conventions** — see [`skills/api/SKILL.md`](../skills/api/SKILL.md) and [`domain/api.md`](api.md)
+- **Styling system** (CSS-in-JS, Tailwind, BEM, etc.) — not yet standardized; project-specific for now
+- **State management library** (Redux, Zustand, Jotai, Signals, etc.) — not yet standardized; project-specific for now
+
+When styling and state-management decisions are standardized, they'll be added here and in the skills.
+
+---
+
+## Where to Go from Here
+
+- **React conventions and patterns** — [`skills/react/SKILL.md`](../skills/react/SKILL.md)
+- **Proposing a change to this standard** — [`docs/contributing.md`](../docs/contributing.md)
+- **Questions or feedback** — reach out to Raj Shah

package/skillhub-registry/rules/anti-patterns.md

@@ -0,0 +1,95 @@
+# Anti-Patterns
+
+Status: **Universal — applies to all coding tasks regardless of language**
+Last updated: 2026-05-06
+Owner: [Raj Shah]
+
+Patterns that consistently cause problems. Each entry explains what it is, why it's harmful, and what to do instead. Language-specific anti-patterns belong in the relevant skill file (e.g., React-specific issues in `skills/react/SKILL.md`).
+
+## God Objects / God Functions
+
+**What it is:** A single function, class, or module that does many unrelated things — handling validation, transformation, persistence, and notification all in one place.
+
+**Why it's harmful:** Touching one responsibility risks breaking the others. Tests become large and brittle. Reviewers can't tell what the change is actually about.
+
+**Do instead:** Each unit of code owns *one* clear job. If you struggle to name a function in 3-5 words without `and`, it's doing too much.
+
+## Premature Abstraction
+
+**What it is:** Building generic, configurable, "flexible" code before there are concrete use cases that require it.
+
+**Why it's harmful:** The flexibility usually doesn't match what's actually needed later. You end up with abstract layers that solve hypothetical problems while making real problems harder.
+
+**Do instead:** Write the concrete version first. Generalize only when you have **3 real use cases** with genuinely shared intent — not just shared syntax.
+
+## Speculative Flexibility
+
+**What it is:** Adding configuration options, plugins, hooks, or extension points "in case we need them later."
+
+**Why it's harmful:** Every option doubles the testing surface. Most options are never used. The ones that are used often need different shapes than originally guessed.
+
+**Do instead:** Build for *current* needs. Adding configuration later is cheaper than removing it.
+
+## Copy-Paste Duplication
+
+**What it is:** Copying a block of code and tweaking small parts, instead of factoring out shared logic.
+
+**Why it's harmful:** Bugs found in one copy don't get fixed in the others. Small tweaks accumulate into divergent versions of "the same" logic.
+
+**Do instead:** On the *third* occurrence, extract a shared helper. Before that, leave it alone — premature DRY-ing creates the wrong abstraction.
+
+## Magic Values
+
+**What it is:** Numeric or string literals scattered through code with no explanation (`if (x > 17)`, `setTimeout(fn, 5000)`).
+
+**Why it's harmful:** Readers must guess intent. Changing the value requires hunting through the codebase. Same value used in different places may mean different things.
+
+**Do instead:** Extract to a named constant whose name explains the *meaning*, not the *value*.
+
+## Inline Complex Logic
+
+**What it is:** Cramming complex expressions, conditional chains, or transformations directly inside templates, JSX, return statements, or function arguments.
+
+**Why it's harmful:** Hard to read, impossible to debug step-by-step, and breaks the visual structure of the surrounding code.
+
+**Do instead:** Extract complex expressions into named variables or helper functions before the place they're used.
+
+## Deeply Chained Conditionals
+
+**What it is:** Nested ternaries, long `if/else if/else if` chains, or boolean expressions with 5+ operands.
+
+**Why it's harmful:** Readers can't hold the logic in their head. Adding a new branch is risky. The "edge case" you missed is buried somewhere in the chain.
+
+**Do instead:** Use early returns, lookup tables/maps, or split into well-named predicate functions.
+
+## Silent Error Swallowing
+
+**What it is:** Catching errors and doing nothing with them. Empty catch blocks, ignored promise rejections, unchecked return codes.
+
+**Why it's harmful:** Failures become invisible. Bugs reach production and surface later as data corruption or mysterious behavior with no logs to trace.
+
+**Do instead:** Always log, transform, retry, or propagate. If you genuinely want to ignore an error, leave a comment explaining why.
+
+## Optimization Without Measurement
+
+**What it is:** Adding caches, memoization, indices, or "performance" code without first measuring that there's a real bottleneck.
+
+**Why it's harmful:** Adds complexity for imagined gains. Often the optimization makes things slower, breaks correctness, or hides a different bug. Real bottlenecks are rarely where you guess they are.
+
+**Do instead:** Profile first. Optimize only proven hot paths. Document the measured before/after numbers.
+
+## Comments That Restate the Code
+
+**What it is:** Comments that translate code into English without adding information (`// increment counter` above `counter++`).
+
+**Why it's harmful:** Adds noise. Goes stale when the code changes. Trains readers to ignore comments.
+
+**Do instead:** Comments should explain *why* — context, constraints, decisions, non-obvious trade-offs. Delete comments that just describe *what*.
+
+## Scope Creep in Edits
+
+**What it is:** Refactoring unrelated code, renaming things, or "fixing" tangential issues while making a focused change.
+
+**Why it's harmful:** Inflates diffs, makes review impossible, and mixes risky changes with safe ones. Reviewers can't approve the intended change without also approving everything else.
+
+**Do instead:** Stay in scope. If you spot an unrelated issue, mention it at the end of your response — don't fix it unsolicited.