@fprad0/skill-master-mcp 0.0.9 → 0.0.11

package/docs/skill-candidates/v0.0.11/frontend-dev-guidelines/resources/typescript-standards.md

@@ -0,0 +1,418 @@
+# TypeScript Standards
+
+TypeScript best practices for type safety and maintainability in React frontend code.
+
+---
+
+## Strict Mode
+
+### Configuration
+
+TypeScript strict mode is **enabled** in the project:
+
+```json
+// tsconfig.json
+{
+    "compilerOptions": {
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true
+    }
+}
+```
+
+**This means:**
+- No implicit `any` types
+- Null/undefined must be handled explicitly
+- Type safety enforced
+
+---
+
+## No `any` Type
+
+### The Rule
+
+```typescript
+// ❌ NEVER use any
+function handleData(data: any) {
+    return data.something;
+}
+
+// ✅ Use specific types
+interface MyData {
+    something: string;
+}
+
+function handleData(data: MyData) {
+    return data.something;
+}
+
+// ✅ Or use unknown for truly unknown data
+function handleUnknown(data: unknown) {
+    if (typeof data === 'object' && data !== null && 'something' in data) {
+        return (data as MyData).something;
+    }
+}
+```
+
+**If you truly don't know the type:**
+- Use `unknown` (forces type checking)
+- Use type guards to narrow
+- Document why type is unknown
+
+---
+
+## Explicit Return Types
+
+### Function Return Types
+
+```typescript
+// ✅ CORRECT - Explicit return type
+function getUser(id: number): Promise<User> {
+    return apiClient.get(`/users/${id}`);
+}
+
+function calculateTotal(items: Item[]): number {
+    return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// ❌ AVOID - Implicit return type (less clear)
+function getUser(id: number) {
+    return apiClient.get(`/users/${id}`);
+}
+```
+
+### Component Return Types
+
+```typescript
+// React.FC already provides return type (ReactElement)
+export const MyComponent: React.FC<Props> = ({ prop }) => {
+    return <div>{prop}</div>;
+};
+
+// For custom hooks
+function useMyData(id: number): { data: Data; isLoading: boolean } {
+    const [data, setData] = useState<Data | null>(null);
+    const [isLoading, setIsLoading] = useState(true);
+
+    return { data: data!, isLoading };
+}
+```
+
+---
+
+## Type Imports
+
+### Use 'type' Keyword
+
+```typescript
+// ✅ CORRECT - Explicitly mark as type import
+import type { User } from '~types/user';
+import type { Post } from '~types/post';
+import type { SxProps, Theme } from '@mui/material';
+
+// ❌ AVOID - Mixed value and type imports
+import { User } from '~types/user';  // Unclear if type or value
+```
+
+**Benefits:**
+- Clearly separates types from values
+- Better tree-shaking
+- Prevents circular dependencies
+- TypeScript compiler optimization
+
+---
+
+## Component Prop Interfaces
+
+### Interface Pattern
+
+```typescript
+/**
+ * Props for MyComponent
+ */
+interface MyComponentProps {
+    /** The user ID to display */
+    userId: number;
+
+    /** Optional callback when action completes */
+    onComplete?: () => void;
+
+    /** Display mode for the component */
+    mode?: 'view' | 'edit';
+
+    /** Additional CSS classes */
+    className?: string;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({
+    userId,
+    onComplete,
+    mode = 'view',  // Default value
+    className,
+}) => {
+    return <div>...</div>;
+};
+```
+
+**Key Points:**
+- Separate interface for props
+- JSDoc comments for each prop
+- Optional props use `?`
+- Provide defaults in destructuring
+
+### Props with Children
+
+```typescript
+interface ContainerProps {
+    children: React.ReactNode;
+    title: string;
+}
+
+// React.FC automatically includes children type, but be explicit
+export const Container: React.FC<ContainerProps> = ({ children, title }) => {
+    return (
+        <div>
+            <h2>{title}</h2>
+            {children}
+        </div>
+    );
+};
+```
+
+---
+
+## Utility Types
+
+### Partial<T>
+
+```typescript
+// Make all properties optional
+type UserUpdate = Partial<User>;
+
+function updateUser(id: number, updates: Partial<User>) {
+    // updates can have any subset of User properties
+}
+```
+
+### Pick<T, K>
+
+```typescript
+// Select specific properties
+type UserPreview = Pick<User, 'id' | 'name' | 'email'>;
+
+const preview: UserPreview = {
+    id: 1,
+    name: 'John',
+    email: 'john@example.com',
+    // Other User properties not allowed
+};
+```
+
+### Omit<T, K>
+
+```typescript
+// Exclude specific properties
+type UserWithoutPassword = Omit<User, 'password' | 'passwordHash'>;
+
+const publicUser: UserWithoutPassword = {
+    id: 1,
+    name: 'John',
+    email: 'john@example.com',
+    // password and passwordHash not allowed
+};
+```
+
+### Required<T>
+
+```typescript
+// Make all properties required
+type RequiredConfig = Required<Config>;  // All optional props become required
+```
+
+### Record<K, V>
+
+```typescript
+// Type-safe object/map
+const userMap: Record<string, User> = {
+    'user1': { id: 1, name: 'John' },
+    'user2': { id: 2, name: 'Jane' },
+};
+
+// For styles
+import type { SxProps, Theme } from '@mui/material';
+
+const styles: Record<string, SxProps<Theme>> = {
+    container: { p: 2 },
+    header: { mb: 1 },
+};
+```
+
+---
+
+## Type Guards
+
+### Basic Type Guards
+
+```typescript
+function isUser(data: unknown): data is User {
+    return (
+        typeof data === 'object' &&
+        data !== null &&
+        'id' in data &&
+        'name' in data
+    );
+}
+
+// Usage
+if (isUser(response)) {
+    console.log(response.name);  // TypeScript knows it's User
+}
+```
+
+### Discriminated Unions
+
+```typescript
+type LoadingState =
+    | { status: 'idle' }
+    | { status: 'loading' }
+    | { status: 'success'; data: Data }
+    | { status: 'error'; error: Error };
+
+function Component({ state }: { state: LoadingState }) {
+    // TypeScript narrows type based on status
+    if (state.status === 'success') {
+        return <Display data={state.data} />;  // data available here
+    }
+
+    if (state.status === 'error') {
+        return <Error error={state.error} />;  // error available here
+    }
+
+    return <Loading />;
+}
+```
+
+---
+
+## Generic Types
+
+### Generic Functions
+
+```typescript
+function getById<T>(items: T[], id: number): T | undefined {
+    return items.find(item => (item as any).id === id);
+}
+
+// Usage with type inference
+const users: User[] = [...];
+const user = getById(users, 123);  // Type: User | undefined
+```
+
+### Generic Components
+
+```typescript
+interface ListProps<T> {
+    items: T[];
+    renderItem: (item: T) => React.ReactNode;
+}
+
+export function List<T>({ items, renderItem }: ListProps<T>): React.ReactElement {
+    return (
+        <div>
+            {items.map((item, index) => (
+                <div key={index}>{renderItem(item)}</div>
+            ))}
+        </div>
+    );
+}
+
+// Usage
+<List<User>
+    items={users}
+    renderItem={(user) => <UserCard user={user} />}
+/>
+```
+
+---
+
+## Type Assertions (Use Sparingly)
+
+### When to Use
+
+```typescript
+// ✅ OK - When you know more than TypeScript
+const element = document.getElementById('my-element') as HTMLInputElement;
+const value = element.value;
+
+// ✅ OK - API response that you've validated
+const response = await api.getData();
+const user = response.data as User;  // You know the shape
+```
+
+### When NOT to Use
+
+```typescript
+// ❌ AVOID - Circumventing type safety
+const data = getData() as any;  // WRONG - defeats TypeScript
+
+// ❌ AVOID - Unsafe assertion
+const value = unknownValue as string;  // Might not actually be string
+```
+
+---
+
+## Null/Undefined Handling
+
+### Optional Chaining
+
+```typescript
+// ✅ CORRECT
+const name = user?.profile?.name;
+
+// Equivalent to:
+const name = user && user.profile && user.profile.name;
+```
+
+### Nullish Coalescing
+
+```typescript
+// ✅ CORRECT
+const displayName = user?.name ?? 'Anonymous';
+
+// Only uses default if null or undefined
+// (Different from || which triggers on '', 0, false)
+```
+
+### Non-Null Assertion (Use Carefully)
+
+```typescript
+// ✅ OK - When you're certain value exists
+const data = queryClient.getQueryData<Data>(['data'])!;
+
+// ⚠️ CAREFUL - Only use when you KNOW it's not null
+// Better to check explicitly:
+const data = queryClient.getQueryData<Data>(['data']);
+if (data) {
+    // Use data
+}
+```
+
+---
+
+## Summary
+
+**TypeScript Checklist:**
+- ✅ Strict mode enabled
+- ✅ No `any` type (use `unknown` if needed)
+- ✅ Explicit return types on functions
+- ✅ Use `import type` for type imports
+- ✅ JSDoc comments on prop interfaces
+- ✅ Utility types (Partial, Pick, Omit, Required, Record)
+- ✅ Type guards for narrowing
+- ✅ Optional chaining and nullish coalescing
+- ❌ Avoid type assertions unless necessary
+
+**See Also:**
+- [component-patterns.md](component-patterns.md) - Component typing
+- [data-fetching.md](data-fetching.md) - API typing

package/docs/skill-candidates/v0.0.11/git-version-control-ops/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: git-version-control-ops
+description: "Operate Git histories, branches, diffs, merges, rebases and release flows with practical attention to safety, reviewability, recovery paths and team collaboration."
+---
+
+# Git Version Control Ops
+
+Use this skill when the task is mainly about Git rather than application code itself.
+
+## Workflow
+
+- Identify branch state, remote state and uncommitted work before acting.
+- Prefer reviewable, reversible moves over clever history surgery.
+- Keep commit intent explicit and scoped.
+- Explain impact before risky history operations.
+- Validate branch state after push, merge or release moves.
+
+## Coverage
+
+- Diffs, commits, branches, tags, merges, rebases, cherry-picks and release prep.
+- Recovery paths, conflict handling, remote sync and safe operator workflows.
+- Collaboration hygiene for Git-based delivery.
+
+## Reference Anchors
+
+- Git docs: `https://git-scm.com/docs`
+- Git book: `https://git-scm.com/book/en/v2`
+
+## Guardrails
+
+- Do not rewrite shared history casually.
+- Do not hide destructive commands behind vague wording.
+- Do not mix unrelated changes in one release commit.
+- Do not claim sync safety without checking remote state.

package/docs/skill-candidates/v0.0.11/go-engineering/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: go-engineering
+description: "Build and review Go services, CLIs and concurrent systems with focus on package design, interfaces, context handling, observability, testing and operational robustness."
+---
+
+# Go Engineering
+
+Use this skill when the task is primarily Go code, tooling or service design.
+
+## Workflow
+
+- Inspect module structure, package boundaries and entrypoints before editing.
+- Treat `context`, errors, interfaces and goroutine lifecycle as explicit design concerns.
+- Keep packages small, concrete and easy to test.
+- Favor predictable composition over deep abstraction trees.
+- Validate with build, tests and representative runtime paths.
+
+## Coverage
+
+- Go APIs, CLIs, workers, packages, modules and concurrency patterns.
+- Context propagation, cancellation, channels, HTTP, configuration and logging.
+- Refactors, debugging, code review and deployment-grade hardening.
+
+## Reference Anchors
+
+- Go docs: `https://go.dev/doc/`
+- Go language spec: `https://go.dev/ref/spec`
+
+## Guardrails
+
+- Do not leak goroutines or ignore cancellation.
+- Do not use interfaces prematurely.
+- Do not bury errors without context.
+- Do not overcomplicate package layout for small services.

package/docs/skill-candidates/v0.0.11/java-engineering/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: java-engineering
+description: "Design, implement and review Java applications, services and CLIs with attention to build tooling, JVM behavior, package boundaries, testing, dependency hygiene and production-grade maintainability."
+---
+
+# Java Engineering
+
+Use this skill when the task is centered on Java application code or JVM service design.
+
+## Workflow
+
+- Identify the build system first: Maven, Gradle or plain Java tooling.
+- Read package layout, dependency graph and runtime assumptions before changing code.
+- Keep domain logic separated from framework glue and infrastructure code.
+- Treat configuration, threading, serialization and resource lifecycle as first-class concerns.
+- Validate with compile, test and representative runtime entrypoints.
+
+## Coverage
+
+- Java services, libraries, CLIs, packaging, dependency management and test structure.
+- JVM runtime behavior, configuration, exceptions, concurrency and integration boundaries.
+- Refactors, code review, API design and deployment readiness.
+
+## Reference Anchors
+
+- Java learning docs: `https://dev.java/learn/`
+- OpenJDK docs: `https://openjdk.org/`
+
+## Guardrails
+
+- Do not hide checked/unchecked error boundaries.
+- Do not couple business logic tightly to framework annotations or containers.
+- Do not introduce build-tool drift without updating the whole workflow.
+- Do not claim thread safety without concrete reasoning.

package/docs/skill-candidates/v0.0.11/javascript-engineering/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: javascript-engineering
+description: "Implement and review JavaScript and Node.js applications with focus on modules, async flows, runtime behavior, APIs, tooling, compatibility and operational reliability across browser and server contexts."
+---
+
+# JavaScript Engineering
+
+Use this skill when the task is mainly JavaScript or Node.js rather than type-heavy TypeScript.
+
+## Workflow
+
+- Determine the runtime first: browser, Node.js, worker, edge or test harness.
+- Verify module mode, package boundaries and build assumptions before changing imports.
+- Keep async behavior explicit: promises, retries, streams, events and shutdown paths.
+- Separate transport, domain logic and persistence so the runtime stays testable.
+- Validate with direct execution paths and representative failure cases.
+
+## Coverage
+
+- JavaScript, Node.js, modules, packages, scripts, APIs, jobs and automation.
+- Async control flow, JSON payloads, process lifecycle, file system and child processes.
+- Runtime debugging, compatibility issues, migration and production hardening.
+
+## Reference Anchors
+
+- MDN JavaScript docs: `https://developer.mozilla.org/en-US/docs/Web/JavaScript`
+- Node.js docs: `https://nodejs.org/en/docs`
+
+## Guardrails
+
+- Do not confuse browser and server APIs.
+- Do not introduce silent promise failures or ignored rejections.
+- Do not change module systems casually in mixed ESM/CJS projects.
+- Do not hide runtime assumptions from the user.

package/docs/skill-candidates/v0.0.11/json-contract-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: json-contract-design
+description: "Define and review JSON payloads, schemas and machine-readable contracts with emphasis on compatibility, validation, naming consistency and integration safety across APIs and automation."
+---
+
+# JSON Contract Design
+
+Use this skill when the task is about JSON structures, schemas or exchange contracts between systems.
+
+## Workflow
+
+- Identify producers, consumers and compatibility expectations first.
+- Define required versus optional fields explicitly.
+- Keep naming, nullability, enums and nested structures consistent.
+- Add validation boundaries close to ingress and egress points.
+- Validate with realistic examples and edge cases.
+
+## Coverage
+
+- JSON payloads, schemas, API contracts, config files and event/message bodies.
+- Compatibility review, migration planning, serialization and validation strategy.
+- Human-readable examples for integration and debugging.
+
+## Reference Anchors
+
+- JSON RFC 8259: `https://www.rfc-editor.org/rfc/rfc8259`
+- JSON Schema: `https://json-schema.org/`
+
+## Guardrails
+
+- Do not introduce ambiguous null versus missing semantics.
+- Do not rename contract fields casually across active integrations.
+- Do not rely on informal examples when a schema is needed.
+- Do not hide breaking changes.

package/docs/skill-candidates/v0.0.11/multi-client-mcp-ops/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: multi-client-mcp-ops
+description: "Configure and validate MCP readiness across Codex, Claude, Gemini and Antigravity with practical focus on client config, transport, global registration and operator troubleshooting."
+---
+
+# Multi Client MCP Ops
+
+Use this skill when the task is about making MCP servers work consistently across multiple AI clients.
+
+## Workflow
+
+- Start from the target client and its real config file path.
+- Verify transport, command, args, working directory and environment requirements.
+- Keep registration reproducible and explain how the user can verify it.
+- Separate local clone execution from global npm-installed execution.
+- Validate readiness client by client instead of assuming parity.
+
+## Coverage
+
+- Codex, Claude, Gemini and Antigravity MCP registration and troubleshooting.
+- Global versus project-local config, stdio commands, PATH and restart requirements.
+- Operator-facing readiness checks and rollout hygiene.
+
+## Reference Anchors
+
+- OpenAI Codex MCP docs: `https://developers.openai.com/codex/mcp/`
+- Model Context Protocol docs: `https://modelcontextprotocol.io/docs/develop/connect-local-servers`
+- Gemini CLI MCP docs: `https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html`
+- Antigravity MCP docs: `https://cloud.google.com/gemini/enterprise/docs/antigravity/mcp-servers`
+
+## Guardrails
+
+- Do not assume one client config format works unchanged in another.
+- Do not claim readiness without checking the effective config path and command.
+- Do not hide restart requirements after config changes.
+- Do not mix package-global and repo-local command assumptions.