@malamute/ai-rules 1.0.0

package/configs/_shared/.claude/skills/learning/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: learning
+description: Pedagogical coding mode - explains everything before implementing, sources all decisions, shows alternatives. Use when learning a new framework or when you want to understand the code being generated.
+argument-hint: [framework-name]
+---
+
+# Learning Mode Activated
+
+You are now in **learning mode**. The user wants to understand everything before implementation.
+
+## Core Rules
+
+### 1. NEVER Implement Without Explicit Approval
+
+Before writing ANY code, you MUST:
+
+1. Explain the approach in detail
+2. Show the planned code with comments
+3. **Wait for explicit validation** ("ok", "go", "approved", "let's do it")
+
+Format your proposals like this:
+
+````
+## Proposed Implementation
+
+**What we're building**: [clear description]
+
+**Approach**: [detailed explanation of the strategy]
+
+**Files to create/modify**:
+- `path/to/file1.ts` - [purpose]
+- `path/to/file2.ts` - [purpose]
+
+**Code preview**:
+```[language]
+// Commented code showing what will be created
+````
+
+**Why this approach?**
+
+- Reason 1
+  - Source: [official doc link]
+- Reason 2
+  - Source: [official doc link]
+
+**Alternative approaches**:
+
+| Approach       | Pros | Cons | When to use |
+| -------------- | ---- | ---- | ----------- |
+| Current choice | ...  | ...  | ...         |
+| Alternative A  | ...  | ...  | ...         |
+
+---
+
+👉 **Do you approve this implementation?** (reply "go" to proceed)
+
+````
+
+### 2. Source EVERYTHING
+
+Every technical decision must include a source. Acceptable sources (in order of preference):
+
+1. **Official documentation** (always preferred)
+2. **Official blog posts** (Vercel blog, Angular blog, etc.)
+3. **GitHub issues/discussions** (for edge cases)
+4. **Reputable tech blogs** (when official docs are lacking)
+
+Format:
+```typescript
+// Server Components are default in App Router
+// Source: https://nextjs.org/docs/app/building-your-application/rendering/server-components
+
+// Use 'use client' directive for client-side interactivity
+// Source: https://nextjs.org/docs/app/building-your-application/rendering/client-components
+````
+
+### 3. Always Show Alternatives
+
+For every significant decision, present at least ONE alternative:
+
+```
+**Chosen**: Server Components with native fetch
+- Built-in caching and deduplication
+- Source: https://nextjs.org/docs/app/building-your-application/data-fetching
+
+**Alternative**: React Query with Client Components
+- Better for: real-time data, optimistic updates, complex client state
+- Source: https://tanstack.com/query/latest/docs/framework/react/overview
+
+**Why I chose the first**: [specific reason for this use case]
+```
+
+### 4. Comment Code Extensively
+
+When showing code, add explanatory comments:
+
+```typescript
+// app/users/page.tsx
+
+// No 'use client' = Server Component (default in App Router)
+// Server Components can use async/await directly
+// Source: https://nextjs.org/docs/app/building-your-application/rendering/server-components
+export default async function UsersPage() {
+
+  // fetch() in Server Components has automatic caching
+  // Default: cache: 'force-cache' (static data)
+  // Options: 'no-store' (dynamic), { next: { revalidate: N } } (ISR)
+  // Source: https://nextjs.org/docs/app/api-reference/functions/fetch
+  const users = await fetch('https://api.example.com/users', {
+    cache: 'no-store', // Real-time data, no caching
+  }).then(res => res.json());
+
+  return (
+    <ul>
+      {/* key is required for React reconciliation */}
+      {users.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### 5. Use Checkpoints for Complex Tasks
+
+Break large implementations into validated steps:
+
+```
+## Implementation Plan
+
+### Checkpoint 1: Project Setup ⏳
+- [ ] Initialize project structure
+- [ ] Configure TypeScript
+- [ ] Setup routing
+
+### Checkpoint 2: Data Layer
+- [ ] Create API routes
+- [ ] Setup data fetching
+- [ ] Add error handling
+
+### Checkpoint 3: UI Components
+- [ ] Build page layouts
+- [ ] Create reusable components
+- [ ] Add styling
+
+---
+
+👉 **Ready to start Checkpoint 1?**
+```
+
+After completing each checkpoint, summarize what was done and ask before proceeding.
+
+### 6. Explain Errors Pedagogically
+
+When errors occur:
+
+````
+## Error Explanation
+
+**Error message**:
+`TypeError: Cannot read properties of undefined (reading 'name')`
+
+**What happened**:
+We tried to access `.name` on a variable that was `undefined`
+
+**Why this happens**:
+In JavaScript/TypeScript, accessing properties on `undefined` throws this error.
+Common causes:
+- Data not loaded yet
+- API returned empty/null
+- Typo in property name
+
+**The fix**:
+```typescript
+// Option 1: Optional chaining
+user?.name
+
+// Option 2: Nullish coalescing
+user?.name ?? 'Default Name'
+
+// Option 3: Early return / guard clause
+if (!user) return null;
+````
+
+**How to prevent this**:
+
+- Enable TypeScript strict mode
+- Always handle loading/error states
+- Use proper typing
+
+Source: https://www.typescriptlang.org/tsconfig#strictNullChecks
+
+```
+
+### 7. Check Understanding (Optional)
+
+Periodically offer comprehension checks:
+
+```
+
+**Quick check** (skip if clear):
+
+- Do you understand why we use 'use client' here but not on the page?
+- Any questions about the caching strategy?
+
+```
+
+## Framework-Specific Context
+
+If the user specified a framework with `/learning [framework]`:
+
+- **$ARGUMENTS** contains the framework name
+- Focus explanations on that framework's conventions
+- Prioritize that framework's official documentation
+
+## Deactivation
+
+The user can exit learning mode by saying:
+- "exit learning mode"
+- "mode normal"
+- "stop explaining"
+
+Then return to standard implementation behavior.
+```

package/configs/_shared/.claude/skills/review/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: review
+description: Code review workflow with structured checklist
+argument-hint: [file-or-folder]
+---
+
+# Code Review Skill
+
+You are now in **code review mode**. Review the code systematically and provide actionable feedback.
+
+## Target
+
+If an argument is provided, review that specific file or folder: `$ARGUMENTS`
+If no argument, ask the user what to review.
+
+## Review Checklist
+
+Go through each category and report findings:
+
+### 1. Correctness
+- [ ] Logic errors or bugs
+- [ ] Edge cases not handled
+- [ ] Null/undefined checks missing
+- [ ] Error handling gaps
+
+### 2. Security
+- [ ] Input validation
+- [ ] SQL/NoSQL injection risks
+- [ ] XSS vulnerabilities
+- [ ] Secrets or credentials exposed
+- [ ] Authentication/authorization issues
+
+### 3. Performance
+- [ ] N+1 queries
+- [ ] Unnecessary re-renders (frontend)
+- [ ] Missing indexes (database)
+- [ ] Large payloads or memory leaks
+- [ ] Blocking operations in async code
+
+### 4. Code Quality
+- [ ] Naming clarity
+- [ ] Function/method length (< 30 lines ideal)
+- [ ] Single responsibility principle
+- [ ] Dead code
+- [ ] Duplicated logic
+
+### 5. Testing
+- [ ] Critical paths covered
+- [ ] Edge cases tested
+- [ ] Mocks used appropriately
+
+### 6. Project Conventions
+- [ ] Follows project CLAUDE.md rules
+- [ ] Consistent with existing patterns
+- [ ] Proper file/folder structure
+
+## Output Format
+
+Structure your review as:
+
+```
+## Summary
+[1-2 sentences overall assessment]
+
+## Critical Issues
+[Must fix before merge]
+
+## Suggestions
+[Nice to have improvements]
+
+## Good Practices
+[What's done well - be specific]
+```
+
+## Behavior
+
+1. Read the target files thoroughly
+2. Check each category in the checklist
+3. Be specific: include file paths and line numbers
+4. Prioritize: critical > suggestions > praise
+5. Be constructive, not just critical
+6. If everything looks good, say so confidently
+
+## Exit
+
+When done, ask: "Want me to fix any of these issues?"

package/configs/_shared/.claude/skills/spec/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: spec
+description: Generate technical specification before implementing
+argument-hint: [feature-description]
+---
+
+# Technical Specification Skill
+
+You are now in **specification mode**. Before writing any code, create a clear technical spec.
+
+## Input
+
+Feature to specify: `$ARGUMENTS`
+
+If no argument provided, ask: "What feature should I specify?"
+
+## Process
+
+### Step 1: Understand Requirements
+
+Ask clarifying questions if needed:
+- What problem does this solve?
+- Who are the users?
+- What are the acceptance criteria?
+- Any constraints (tech, time, dependencies)?
+
+### Step 2: Research Codebase
+
+Before writing the spec:
+1. Search for similar existing patterns
+2. Identify files that will be affected
+3. Check for dependencies or conflicts
+4. Understand current architecture
+
+### Step 3: Write Specification
+
+## Spec Template
+
+```markdown
+# [Feature Name] - Technical Specification
+
+## Overview
+[2-3 sentences describing the feature]
+
+## Goals
+- [ ] Goal 1
+- [ ] Goal 2
+
+## Non-Goals
+- What this feature will NOT do
+
+## Technical Approach
+
+### Architecture
+[How it fits into existing system]
+
+### Files to Create/Modify
+| File | Action | Description |
+|------|--------|-------------|
+| path/to/file.ts | Create | New service for X |
+| path/to/other.ts | Modify | Add method Y |
+
+### Data Model
+[If applicable: new entities, schemas, migrations]
+
+### API Changes
+[If applicable: new endpoints, request/response shapes]
+
+### Dependencies
+- External packages needed
+- Internal modules to import
+
+## Implementation Steps
+1. [ ] Step 1
+2. [ ] Step 2
+3. [ ] Step 3
+
+## Testing Strategy
+- Unit tests for: ...
+- Integration tests for: ...
+- E2E tests for: ...
+
+## Risks & Mitigations
+| Risk | Mitigation |
+|------|------------|
+| Risk 1 | How to handle |
+
+## Open Questions
+- [ ] Question 1
+- [ ] Question 2
+```
+
+## Behavior
+
+1. Never start coding without user approval of the spec
+2. Be thorough but concise
+3. Identify risks early
+4. Break down into small, testable steps
+5. Reference existing code patterns
+
+## Validation
+
+After presenting the spec, ask:
+- "Does this approach make sense?"
+- "Any requirements I missed?"
+- "Ready to implement?"
+
+## Exit
+
+Only exit spec mode and start implementation when user explicitly approves.
+
+Say: "Spec approved. Starting implementation..." before writing code.

package/configs/_shared/CLAUDE.md

@@ -0,0 +1,174 @@
+# Shared Conventions
+
+## Git Workflow
+
+### Branch Naming
+
+```
+feature/[ticket-id]-short-description
+fix/[ticket-id]-short-description
+refactor/description
+chore/description
+```
+
+### Commit Messages (Conventional Commits)
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, no code change
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Performance improvement
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat(users): add user profile page
+fix(auth): resolve token refresh race condition
+refactor(api): simplify error handling
+test(cart): add unit tests for checkout flow
+```
+
+### Pull Requests
+
+- Keep PRs small and focused
+- One feature/fix per PR
+- Write meaningful descriptions
+- Link related issues
+
+## TypeScript Guidelines
+
+### Strict Mode
+
+Always use strict TypeScript configuration:
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitReturns": true
+  }
+}
+```
+
+### Type Definitions
+
+```typescript
+// Prefer interfaces for object shapes
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// Use type for unions, intersections, utility types
+type Status = 'pending' | 'active' | 'inactive';
+type UserWithRole = User & { role: Role };
+
+// Avoid 'any' - use 'unknown' if type is truly unknown
+function parse(input: unknown): Result {
+  // ...
+}
+```
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Classes | PascalCase | `UserService` |
+| Interfaces | PascalCase | `UserProfile` |
+| Functions | camelCase | `getUserById` |
+| Variables | camelCase | `currentUser` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Files | kebab-case | `user-profile.service.ts` |
+| Folders | kebab-case | `user-management/` |
+
+### Explicit Return Types
+
+Always declare return types on public methods:
+
+```typescript
+// Good
+function getUser(id: string): User | null {
+  // ...
+}
+
+// Avoid
+function getUser(id: string) {
+  // ...
+}
+```
+
+## Code Quality
+
+### Avoid
+
+- `any` type
+- Magic numbers (use named constants)
+- Deep nesting (max 3 levels)
+- Long functions (max ~50 lines)
+- Commented-out code
+- Useless comments (code should be self-documenting)
+- Cryptic variable names (`c`, `x`, `tmp`, `data`)
+
+### Prefer
+
+- Early returns
+- Descriptive variable names
+- Single responsibility principle
+- Composition over inheritance
+- Immutable data patterns
+
+### Naming - Be Explicit
+
+```typescript
+// BAD
+const c = getConfig();
+users.filter(u => u.a);
+const handleClick = (e) => { ... };
+
+// GOOD
+const appConfig = getConfig();
+users.filter(user => user.isActive);
+const handleUserSelection = (event: MouseEvent) => { ... };
+```
+
+### Lint Rules - Never Disable Without Justification
+
+```typescript
+// FORBIDDEN
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const data: any = response;
+
+// ONLY IF ABSOLUTELY NECESSARY - with explicit reason
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Legacy API returns untyped, see ticket TECH-456
+const legacyData: any = legacyApi.fetch();
+```
+
+## Documentation
+
+- Write self-documenting code first
+- Add JSDoc only when intent isn't obvious
+- Keep comments up-to-date or remove them
+- Document "why", not "what"
+
+```typescript
+// Bad: describes what code does
+// Increment counter by 1
+counter++;
+
+// Good: explains why
+// Compensate for 0-based index in display
+counter++;
+```