@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/_shared/.claude/rules/conventions/documentation.md

@@ -0,0 +1,324 @@
+---
+paths:
+  - "**/README.md"
+  - "**/CHANGELOG.md"
+  - "**/docs/**"
+  - "**/ADR/**"
+---
+
+# Documentation Standards
+
+## README Structure
+
+```markdown
+# Project Name
+
+Brief description (1-2 sentences).
+
+## Quick Start
+
+\`\`\`bash
+# Clone and setup
+git clone <repo>
+cd project
+npm install
+npm run dev
+\`\`\`
+
+## Prerequisites
+
+- Node.js 20+
+- Docker
+- PostgreSQL 16
+
+## Installation
+
+Step-by-step setup instructions.
+
+## Usage
+
+Basic usage examples.
+
+## API Reference
+
+Link to API docs or brief overview.
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | `3000` |
+| `DATABASE_URL` | DB connection | required |
+
+## Development
+
+\`\`\`bash
+npm run dev      # Start dev server
+npm run test     # Run tests
+npm run lint     # Lint code
+npm run build    # Build for production
+\`\`\`
+
+## Deployment
+
+How to deploy to production.
+
+## Contributing
+
+Link to CONTRIBUTING.md or brief guidelines.
+
+## License
+
+MIT / Apache-2.0 / etc.
+```
+
+## Architecture Decision Records (ADR)
+
+### Template
+
+```markdown
+# ADR-001: Use PostgreSQL as primary database
+
+## Status
+
+Accepted | Proposed | Deprecated | Superseded by ADR-XXX
+
+## Date
+
+2024-01-15
+
+## Context
+
+What is the issue we're facing? What are the constraints?
+
+## Decision
+
+What is the change we're making?
+
+## Consequences
+
+### Positive
+- Benefit 1
+- Benefit 2
+
+### Negative
+- Drawback 1
+- Drawback 2
+
+### Risks
+- Risk 1 and mitigation
+
+## Alternatives Considered
+
+1. **Alternative A**: Why rejected
+2. **Alternative B**: Why rejected
+```
+
+### Naming Convention
+
+```
+docs/adr/
+├── 001-use-postgresql.md
+├── 002-adopt-microservices.md
+├── 003-authentication-strategy.md
+└── README.md  # Index of all ADRs
+```
+
+## Changelog
+
+### Format (Keep a Changelog)
+
+```markdown
+# Changelog
+
+All notable changes to this project.
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Changed
+- Updated dependency Y
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- User authentication (#123)
+- Email notifications (#124)
+
+### Fixed
+- Login redirect issue (#125)
+
+### Security
+- Patched XSS vulnerability (#126)
+
+## [1.1.0] - 2024-01-01
+
+### Added
+- Initial release
+```
+
+### Categories
+
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Vulnerability fixes
+
+## API Documentation
+
+### OpenAPI/Swagger
+
+```yaml
+openapi: 3.0.3
+info:
+  title: My API
+  version: 1.0.0
+  description: API description
+
+paths:
+  /users:
+    get:
+      summary: List users
+      description: Returns paginated list of users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+```
+
+### Inline Documentation
+
+```typescript
+/**
+ * Creates a new user account.
+ *
+ * @param data - User registration data
+ * @returns Created user object
+ * @throws {ValidationError} When email is invalid
+ * @throws {ConflictError} When email already exists
+ *
+ * @example
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   password: 'secure123'
+ * });
+ */
+async function createUser(data: CreateUserDto): Promise<User> {
+  // Implementation
+}
+```
+
+## Code Comments
+
+### When to Comment
+
+```typescript
+// GOOD: Explains WHY, not WHAT
+// Using retry with exponential backoff because the external API
+// has rate limiting and occasional timeouts
+await retryWithBackoff(() => externalApi.call());
+
+// BAD: Explains WHAT (obvious from code)
+// Loop through users
+for (const user of users) { ... }
+
+// GOOD: Documents non-obvious behavior
+// Note: Returns null instead of throwing when user not found
+// to support optional user lookups in middleware
+async function findUser(id: string): Promise<User | null>
+
+// GOOD: TODO with context
+// TODO(#123): Replace with proper caching once Redis is available
+const cache = new Map();
+```
+
+### Comment Types
+
+```typescript
+// TODO: Feature to implement
+// FIXME: Known bug to fix
+// HACK: Temporary workaround
+// NOTE: Important information
+// WARN: Potential issue
+// DEPRECATED: Will be removed
+```
+
+## Project Structure Documentation
+
+```markdown
+# Project Structure
+
+\`\`\`
+src/
+├── modules/           # Feature modules
+│   ├── users/         # User management
+│   │   ├── dto/       # Data transfer objects
+│   │   ├── entities/  # Database entities
+│   │   └── users.service.ts
+│   └── orders/        # Order management
+├── common/            # Shared utilities
+│   ├── decorators/    # Custom decorators
+│   ├── filters/       # Exception filters
+│   └── guards/        # Auth guards
+├── config/            # Configuration
+└── main.ts            # Entry point
+\`\`\`
+```
+
+## Runbooks
+
+### Template
+
+```markdown
+# Runbook: Database Connection Issues
+
+## Symptoms
+- API returning 500 errors
+- Logs show "Connection refused"
+
+## Diagnosis
+1. Check database status: `docker ps | grep postgres`
+2. Check connections: `SELECT count(*) FROM pg_stat_activity;`
+3. Check logs: `docker logs postgres`
+
+## Resolution
+
+### If database is down
+\`\`\`bash
+docker-compose restart db
+\`\`\`
+
+### If too many connections
+\`\`\`bash
+# Kill idle connections
+SELECT pg_terminate_backend(pid)
+FROM pg_stat_activity
+WHERE state = 'idle' AND query_start < now() - interval '1 hour';
+\`\`\`
+
+## Escalation
+Contact: @database-team in #incidents
+```
+
+## Anti-patterns
+
+- No README
+- Outdated documentation
+- Documenting WHAT instead of WHY
+- No ADRs for major decisions
+- Missing changelog
+- Undocumented environment variables
+- No setup instructions

package/configs/_shared/.claude/rules/conventions/git.md

@@ -0,0 +1,265 @@
+---
+paths:
+  - "**/*"
+---
+
+# Git Rules
+
+## Commit Messages (Conventional Commits)
+
+Format: `type(scope): description`
+
+```bash
+# Types
+feat     # New feature
+fix      # Bug fix
+docs     # Documentation only
+style    # Formatting, no code change
+refactor # Code change, no feature/fix
+perf     # Performance improvement
+test     # Adding/updating tests
+chore    # Build, CI, dependencies
+```
+
+```bash
+# Good examples
+feat(auth): add OAuth2 login with Google
+fix(cart): resolve race condition in checkout
+refactor(api): simplify error handling middleware
+perf(db): add index on users.email column
+test(orders): add integration tests for payment flow
+chore(deps): upgrade typescript to 5.3
+
+# Bad examples
+fix: bug fix                    # Too vague
+updated stuff                   # No type, unclear
+feat: Add new feature for users # Capitalized, vague
+```
+
+## Branch Naming
+
+```bash
+# Pattern: type/description or type/TICKET-description
+feat/user-authentication
+feat/JIRA-123-oauth-login
+fix/cart-total-calculation
+fix/BUG-456-null-pointer
+refactor/api-error-handling
+chore/upgrade-dependencies
+```
+
+## Workflow
+
+```bash
+# Start new feature
+git checkout main
+git pull --rebase
+git checkout -b feat/my-feature
+
+# Regular commits during work
+git add -p                    # Stage interactively
+git commit -m "feat(scope): description"
+
+# Before pushing - rebase on main
+git fetch origin
+git rebase origin/main
+
+# Push (first time)
+git push -u origin feat/my-feature
+
+# Push (subsequent)
+git push
+```
+
+## Rebase vs Merge
+
+```bash
+# ALWAYS rebase local changes on remote
+git pull --rebase origin main
+
+# NEVER merge main into feature branch
+git merge main    # Creates ugly merge commits
+
+# Interactive rebase to clean up commits before PR
+git rebase -i HEAD~3
+```
+
+## Interactive Rebase
+
+```bash
+# Clean up last 3 commits
+git rebase -i HEAD~3
+
+# In editor:
+pick abc1234 feat(auth): add login endpoint
+squash def5678 fix typo              # Squash into previous
+fixup ghi9012 more fixes             # Squash, discard message
+reword jkl3456 wip                   # Edit commit message
+```
+
+## Stashing
+
+```bash
+# Save work in progress
+git stash push -m "WIP: feature description"
+
+# List stashes
+git stash list
+
+# Apply and drop
+git stash pop
+
+# Apply specific stash
+git stash apply stash@{2}
+
+# Drop stash
+git stash drop stash@{0}
+```
+
+## Undoing Changes
+
+```bash
+# Unstage file (keep changes)
+git restore --staged file.ts
+
+# Discard local changes (DESTRUCTIVE)
+git restore file.ts
+
+# Undo last commit (keep changes staged)
+git reset --soft HEAD~1
+
+# Undo last commit (keep changes unstaged)
+git reset HEAD~1
+
+# Completely undo last commit (DESTRUCTIVE)
+git reset --hard HEAD~1
+
+# Create new commit that undoes previous
+git revert abc1234
+```
+
+## Viewing History
+
+```bash
+# Compact log
+git log --oneline -20
+
+# With graph
+git log --oneline --graph --all
+
+# Changes in commit
+git show abc1234
+
+# Who changed this line
+git blame file.ts
+
+# Search commits by message
+git log --grep="fix auth"
+
+# Search commits by code change
+git log -S "functionName" --oneline
+```
+
+## Cherry-Pick
+
+```bash
+# Apply specific commit to current branch
+git cherry-pick abc1234
+
+# Cherry-pick without committing
+git cherry-pick --no-commit abc1234
+
+# Cherry-pick range
+git cherry-pick abc1234..def5678
+```
+
+## Tags
+
+```bash
+# Create annotated tag
+git tag -a v1.2.0 -m "Release 1.2.0"
+
+# Push tags
+git push origin v1.2.0
+git push origin --tags
+
+# List tags
+git tag -l "v1.*"
+
+# Delete tag
+git tag -d v1.2.0
+git push origin :refs/tags/v1.2.0
+```
+
+## Hooks (Husky)
+
+```bash
+# .husky/pre-commit
+npm run lint-staged
+
+# .husky/commit-msg
+npx commitlint --edit $1
+
+# .husky/pre-push
+npm run test
+```
+
+## .gitignore Essentials
+
+```gitignore
+# Dependencies
+node_modules/
+.venv/
+vendor/
+
+# Build
+dist/
+build/
+*.dll
+*.exe
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Environment
+.env
+.env.local
+*.local
+
+# Secrets (NEVER commit)
+*.pem
+*.key
+credentials.json
+secrets.yaml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test
+coverage/
+.nyc_output/
+```
+
+## PR Best Practices
+
+```bash
+# Keep PRs small and focused
+# - One feature/fix per PR
+# - <400 lines changed ideal
+# - Split large changes into stacked PRs
+
+# Before creating PR
+git rebase -i origin/main    # Clean history
+npm run lint                  # Pass lint
+npm run test                  # Pass tests
+
+# PR title follows commit convention
+feat(auth): add OAuth2 login with Google
+```

package/configs/_shared/.claude/rules/{performance.md → conventions/performance.md}

@@ -79,7 +79,7 @@ await cache.delete(`user:${userId}`);
 ### Memoization
 ```typescript
 // Memoize pure functions
-const memoize = <T>(fn: (...args: any[]) => T): ((...args: any[]) => T) => {
+const memoize = <T, Args extends unknown[]>(fn: (...args: Args) => T): ((...args: Args) => T) => {
   const cache = new Map();
   return (...args) => {
     const key = JSON.stringify(args);