@qazuor/claude-code-config 0.1.0

package/templates/docs/learnings/README.md

@@ -0,0 +1,250 @@
+# Learnings Archive
+
+Documented learnings and best practices discovered during development.
+
+---
+
+## Purpose
+
+This directory contains individual learning files extracted from CLAUDE.md's "Recent Learnings" section. Each learning is documented with:
+
+- **Title**: Clear, descriptive name
+- **Date**: When the learning was discovered/documented
+- **Category**: Classification (e.g., Testing, Architecture, DevOps)
+- **Problem**: What issue prompted this learning
+- **Solution**: How to handle/solve the problem
+- **Impact**: Severity, frequency, scope, prevention
+- **Related**: Links to documentation and related learnings
+
+---
+
+## Structure
+
+Each learning is a standalone markdown file with kebab-case naming:
+
+```
+learnings/
+├── README.md (this file)
+├── shell-compatibility-fish.md
+├── monorepo-command-execution.md
+├── test-organization-structure.md
+├── markdown-formatting-standards.md
+├── planning-linear-sync-workflow.md
+├── common-architectural-patterns.md
+├── common-mistakes-to-avoid.md
+└── optimization-tips.md
+```
+
+---
+
+## Available Learnings
+
+### Shell & Terminal (1)
+
+**[shell-compatibility-fish.md](shell-compatibility-fish.md)**
+
+- **Category:** Shell / Terminal / DevOps
+- **Problem:** `for` loops hang Fish shell
+- **Solution:** Use `find -exec` or `xargs` alternatives
+- **Impact:** High severity, blocks workflow
+- **Date:** 2024-10-28
+
+### Monorepo & Build (1)
+
+**[monorepo-command-execution.md](monorepo-command-execution.md)**
+
+- **Category:** Monorepo / PNPM / Development
+- **Problem:** Incorrect command execution in monorepo packages
+- **Solution:** Always use `cd packageName && pnpm run <command>`
+- **Impact:** High severity, causes build failures
+- **Date:** 2024-10-28
+
+### Testing (1)
+
+**[test-organization-structure.md](test-organization-structure.md)**
+
+- **Category:** Testing / Project Structure
+- **Problem:** Tests in wrong locations cause import/build issues
+- **Solution:** Use `test/` folder, mirror `src/` structure
+- **Impact:** Medium severity, affects reliability
+- **Date:** 2024-10-28
+
+### Documentation (1)
+
+**[markdown-formatting-standards.md](markdown-formatting-standards.md)**
+
+- **Category:** Documentation / Formatting
+- **Problem:** Inconsistent markdown fails CI/CD checks
+- **Solution:** Run `pnpm format:md` before commits
+- **Impact:** Medium severity, blocks CI/CD
+- **Date:** 2024-10-28
+
+### Planning & Workflow (1)
+
+**[planning-linear-sync-workflow.md](planning-linear-sync-workflow.md)**
+
+- **Category:** Planning / GitHub / Linear / Workflow
+- **Problem:** Manual planning sync loses context
+- **Solution:** Sync after approval, commit before completion
+- **Impact:** High severity, affects tracking
+- **Date:** 2024-10-28
+
+### Architecture & Patterns (2)
+
+**[common-architectural-patterns.md](common-architectural-patterns.md)**
+
+- **Category:** Architecture / Best Practices
+- **Problem:** Inconsistent patterns across codebase
+- **Solution:** Always use factories, base classes, RO-RO pattern
+- **Impact:** High severity, affects maintainability
+- **Date:** 2024-10-28
+
+**[common-mistakes-to-avoid.md](common-mistakes-to-avoid.md)**
+
+- **Category:** Best Practices / Code Quality
+- **Problem:** Repeated mistakes slow development
+- **Solution:** Never use `any`, default exports, skip tests, etc.
+- **Impact:** High severity, compounds over time
+- **Date:** 2024-10-28
+
+### Optimization (1)
+
+**[optimization-tips.md](optimization-tips.md)**
+
+- **Category:** Performance / Best Practices
+- **Problem:** Inefficient development practices
+- **Solution:** Use Context7, dependency mapper, batch changes
+- **Impact:** Medium severity, improves efficiency
+- **Date:** 2024-10-28
+
+---
+
+## Usage
+
+### For Claude
+
+**Latest 10 learnings stay inline in CLAUDE.md** for quick reference.
+
+When adding new learnings:
+
+1. Add to CLAUDE.md "Recent Learnings" section (inline)
+2. Create individual file in `.claude/docs/learnings/`
+3. If > 10 learnings in CLAUDE.md, move oldest to "Archived Learnings" section (keep file)
+
+**Finding learnings:**
+
+- Check CLAUDE.md for latest 10 (quick reference)
+- Check this directory for full archive (detailed information)
+
+### For Developers
+
+**When encountering errors or discovering patterns:**
+
+1. Document immediately in CLAUDE.md "Recent Learnings"
+2. Create detailed file in this directory
+3. Include problem, solution, impact, related links
+
+**When looking for solutions:**
+
+1. Check CLAUDE.md first (latest 10 learnings)
+2. Search this directory by category
+3. Review related learnings for context
+
+---
+
+## Categories
+
+Learnings are organized into these categories:
+
+- **Shell / Terminal** - Shell compatibility, command usage
+- **Monorepo / Build** - Build system, package management
+- **Testing** - Test organization, TDD practices
+- **Documentation** - Docs formatting, standards
+- **Planning / Workflow** - Project planning, task tracking
+- **Architecture / Patterns** - Code architecture, design patterns
+- **Best Practices** - General development practices
+- **Performance / Optimization** - Development efficiency
+
+---
+
+## Adding New Learnings
+
+### Template
+
+```markdown
+# Learning Title
+
+**Date:** YYYY-MM-DD
+
+**Category:** Category / Subcategory
+
+## Problem
+
+[Describe what issue prompted this learning]
+
+## Solution
+
+[Describe how to handle/solve the problem with examples]
+
+## Impact
+
+- **Severity:** High/Medium/Low
+- **Frequency:** How often this occurs
+- **Scope:** Who is affected
+- **Prevention:** How to avoid in future
+
+## Related
+
+- **Documentation:** [Link to relevant docs]
+- **Related Learnings:** [Link to related learning files]
+
+---
+
+*Last updated: YYYY-MM-DD*
+```
+
+### Naming Convention
+
+Use kebab-case with descriptive names:
+
+- ✅ `shell-compatibility-fish.md`
+- ✅ `monorepo-command-execution.md`
+- ✅ `test-organization-structure.md`
+- ❌ `learning-1.md`
+- ❌ `2024-10-shell.md`
+
+---
+
+## Maintenance
+
+### When to Archive
+
+When CLAUDE.md "Recent Learnings" exceeds 10 items:
+
+1. Move oldest learning from inline to "Archived Learnings" section
+2. Add link to the individual file in "Archived Learnings"
+3. Keep the individual file in this directory (don't delete)
+
+### When to Update
+
+Update learning files when:
+
+- New information discovered about the problem
+- Better solutions found
+- Impact changes (severity/frequency)
+- Related learnings added
+
+**Always update the "Last updated" date at bottom of file.**
+
+---
+
+## Statistics
+
+- **Total Learnings:** 8
+- **Categories:** 8
+- **Latest Addition:** 2024-10-28
+- **Most Critical:** Shell Compatibility, Monorepo Execution, Planning Sync (High severity)
+
+---
+
+Last updated: 2024-10-31

package/templates/docs/learnings/common-architectural-patterns.md

@@ -0,0 +1,123 @@
+# Common Architectural Patterns
+
+**Date:** 2024-10-28
+
+**Category:** Architecture / Best Practices
+
+## Problem
+
+Inconsistent code patterns across the codebase cause:
+
+- Difficult code reviews
+- Higher cognitive load for developers
+- Harder to onboard new team members
+- Bugs from inconsistent implementations
+
+## Solution
+
+**Always Follow These Patterns:**
+
+### 1. Factory Patterns for Routes
+
+```typescript
+// ✅ CORRECT - Use createCRUDRoute factory
+import { createCRUDRoute } from '@repo/api-factories';
+
+const userRoutes = createCRUDRoute({
+  path: '/users',
+  service: userService,
+  schema: userSchema,
+});
+
+// ❌ WRONG - Manual route creation
+app.get('/users', async (c) => { /* ... */ });
+app.post('/users', async (c) => { /* ... */ });
+```
+
+### 2. Extend Base Classes
+
+```typescript
+// ✅ CORRECT - Extend BaseModel
+export class UserModel extends BaseModel<User> {
+  constructor() {
+    super('users');
+  }
+}
+
+// ✅ CORRECT - Extend BaseCrudService
+export class UserService extends BaseCrudService<User> {
+  constructor() {
+    super(userModel);
+  }
+}
+
+// ❌ WRONG - Custom implementations
+export class UserModel { /* manual CRUD */ }
+```
+
+### 3. RO-RO Pattern (Receive Object / Return Object)
+
+```typescript
+// ✅ CORRECT - RO-RO pattern
+export async function createUser({ data, context }: CreateUserParams): Promise<CreateUserResult> {
+  return { user, status: 'created' };
+}
+
+// ❌ WRONG - Multiple parameters
+export async function createUser(email: string, name: string, age: number) {
+  return user;
+}
+```
+
+### 4. Barrel Files (index.ts)
+
+```typescript
+// ✅ CORRECT - models/index.ts
+export { UserModel } from './user.model.js';
+export { BookingModel } from './booking.model.js';
+
+// Import usage
+import { UserModel, BookingModel } from '@repo/db/models';
+```
+
+### 5. Named Exports Only
+
+```typescript
+// ✅ CORRECT - Named export
+export const userService = new UserService();
+export function validateUser() { /* ... */ }
+
+// ❌ WRONG - Default export
+export default userService;
+```
+
+### 6. Types from Zod Schemas
+
+```typescript
+// ✅ CORRECT - Infer from schema
+import { userSchema } from '@repo/schemas';
+export type User = z.infer<typeof userSchema>;
+
+// ❌ WRONG - Separate type file
+export interface User {
+  id: string;
+  email: string;
+}
+```
+
+## Impact
+
+- **Severity:** High - Affects codebase maintainability
+- **Frequency:** Every new feature/component
+- **Scope:** All developers
+- **Prevention:** Follow patterns exactly, use factories and base classes
+
+## Related
+
+- **Full Patterns:** [.claude/docs/standards/architecture-patterns.md](../standards/architecture-patterns.md)
+- **Code Standards:** [.claude/docs/standards/code-standards.md](../standards/code-standards.md)
+- **Related Learnings:** `common-mistakes-to-avoid.md`
+
+---
+
+Last updated: 2024-10-28

package/templates/docs/learnings/common-mistakes-to-avoid.md

@@ -0,0 +1,149 @@
+# Common Mistakes to Avoid
+
+**Date:** 2024-10-28
+
+**Category:** Best Practices / Code Quality
+
+## Problem
+
+Repeated mistakes slow down development and introduce bugs:
+
+- Type safety violations
+- Skipped tests leading to bugs
+- Pattern violations causing inconsistency
+- Quality issues from skipped checks
+
+## Solution
+
+**Never Do These Things:**
+
+### 1. Using `any` Type
+
+```typescript
+// ❌ WRONG - Loses all type safety
+function processData(data: any) {
+  return data.value;  // No autocomplete, no errors
+}
+
+// ✅ CORRECT - Use unknown with type guards
+function processData(data: unknown) {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return (data as { value: string }).value;
+  }
+  throw new Error('Invalid data');
+}
+
+// ✅ BETTER - Proper typing
+interface DataWithValue {
+  value: string;
+}
+function processData(data: DataWithValue) {
+  return data.value;
+}
+```
+
+### 2. Using Default Exports
+
+```typescript
+// ❌ WRONG - Default export
+export default class UserService { }
+
+// Import becomes inconsistent
+import UserService from './user.service';     // Could be named anything
+import MyService from './user.service';       // No consistency
+
+// ✅ CORRECT - Named export
+export class UserService { }
+
+// Import is consistent
+import { UserService } from './user.service';
+```
+
+### 3. Skipping Tests in TDD
+
+```typescript
+// ❌ WRONG - Implement first
+export function calculateTotal(items: Item[]) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+// Then write tests later (often forgotten)
+
+// ✅ CORRECT - Test first (RED)
+it('should calculate total of items', () => {
+  const items = [{ price: 10 }, { price: 20 }];
+  expect(calculateTotal(items)).toBe(30);
+});
+// Result: FAIL - calculateTotal is not defined
+
+// Then implement (GREEN)
+export function calculateTotal(items: Item[]) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+// Result: PASS ✓
+```
+
+### 4. Not Running Quality Checks
+
+```bash
+# ❌ WRONG - Skip directly to commit
+git add .
+git commit -m "Add feature"
+
+# ✅ CORRECT - Always run quality checks
+pnpm typecheck
+pnpm lint
+pnpm test
+# Then commit if all pass
+```
+
+### 5. Making Autonomous Decisions
+
+```typescript
+// ❌ WRONG - Choose approach without consulting
+// "I'll use Redis for caching"
+await redis.set(key, value);
+
+// ✅ CORRECT - Present options
+// "I have 3 caching options:
+// 1. In-memory (fast, simple, limited)
+// 2. Redis (scalable, complex)
+// 3. Database (simple, slower)
+// Which do you prefer?"
+```
+
+### 6. Creating Separate Type Files
+
+```typescript
+// ❌ WRONG - Separate type file
+// types/user.ts
+export interface User {
+  id: string;
+  email: string;
+}
+
+// ✅ CORRECT - Infer from Zod schema
+// schemas/user.schema.ts
+export const userSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+});
+
+export type User = z.infer<typeof userSchema>;
+```
+
+## Impact
+
+- **Severity:** High - Each mistake compounds over time
+- **Frequency:** Common for new developers or under time pressure
+- **Scope:** All codebase contributors
+- **Prevention:** Code reviews, automated checks, following standards
+
+## Related
+
+- **Standards:** [.claude/docs/standards/code-standards.md](../standards/code-standards.md)
+- **TDD Guide:** [.claude/skills/patterns/tdd-methodology.md](../../skills/patterns/tdd-methodology.md)
+- **Related Learnings:** `common-architectural-patterns.md`
+
+---
+
+Last updated: 2024-10-28

package/templates/docs/learnings/markdown-formatting-standards.md

@@ -0,0 +1,104 @@
+# Markdown Formatting Standards
+
+**Date:** 2024-10-28
+
+**Category:** Documentation / Formatting
+
+## Problem
+
+Inconsistent markdown formatting causes:
+
+- Failed CI/CD checks (markdownlint errors)
+- Difficult-to-read documentation
+- Merge conflicts in documentation files
+- Unprofessional appearance
+
+## Solution
+
+**Always format markdown before committing:**
+
+```bash
+# Format all markdown files
+pnpm format:md
+
+# Format only .claude docs
+pnpm format:md:claude
+
+# Check without fixing
+pnpm lint:md
+```
+
+**Key Rules:**
+
+1. **Add language to code blocks** - Never leave code blocks without language specification
+
+   ```markdown
+   ✅ CORRECT
+   ```javascript
+   const foo = 'bar';
+   ```
+
+   ❌ WRONG
+
+   ```
+   const foo = 'bar';
+   ```
+
+   ```
+
+2. **Use 2-space indentation for lists** - Consistent nested list formatting
+
+   ```markdown
+   ✅ CORRECT
+   - Item 1
+     - Nested item
+       - Double nested
+
+   ❌ WRONG
+   - Item 1
+       - Nested (4 spaces)
+   ```
+
+3. **Add blank lines around blocks** - Headings, code blocks, lists, tables need spacing
+
+   ```markdown
+   ✅ CORRECT
+   Some text.
+
+   ## Heading
+
+   More text.
+
+   ❌ WRONG
+   Some text.
+   ## Heading
+   More text.
+   ```
+
+4. **No trailing punctuation in headings**
+
+   ```markdown
+   ✅ CORRECT
+   ## My Heading
+
+   ❌ WRONG
+   ## My Heading:
+   ## My Heading.
+   ```
+
+## Impact
+
+- **Severity:** Medium - Blocks CI/CD, affects readability
+- **Frequency:** Common when writing documentation
+- **Scope:** All documentation contributors
+- **Prevention:** Run `pnpm format:md` before every commit
+
+## Related
+
+- **Full Documentation:** `docs/development/markdown-formatting.md`
+- **CI/CD Hooks:** `.claude/hooks/` configuration
+- **Related Learnings:** None yet
+
+---
+
+Last updated: 2024-10-28

package/templates/docs/learnings/monorepo-command-execution.md

@@ -0,0 +1,64 @@
+# Monorepo Command Execution
+
+**Date:** 2024-10-28
+
+**Category:** Monorepo / PNPM / Development
+
+## Problem
+
+Running package-specific commands (lint, typecheck, test) incorrectly leads to:
+
+- Commands not finding workspace dependencies
+- Inconsistent environment setup
+- Path resolution errors
+- Build failures
+
+## Solution
+
+**ALWAYS run package/app commands from project root** using `cd packageName && pnpm run <command>`
+
+**Examples:**
+
+```bash
+# ✅ CORRECT - Lint individual package
+cd packages/db && pnpm run lint
+
+# ✅ CORRECT - Test individual app
+cd apps/api && pnpm run test
+
+# ✅ CORRECT - TypeCheck individual package
+cd packages/db && pnpm run typecheck
+
+# ❌ WRONG - Don't use filters for individual checks
+pnpm --filter @repo/db run lint  # Doesn't work as expected
+
+# ❌ WRONG - Don't run from package directory
+cd packages/db
+pnpm run lint  # May fail due to workspace context
+```
+
+**When to use from root:**
+
+```bash
+# For entire monorepo checks only
+pnpm run lint        # All packages/apps
+pnpm run typecheck   # All packages/apps
+pnpm run test        # All packages/apps
+```
+
+## Impact
+
+- **Severity:** High - Causes build/test failures
+- **Frequency:** Very common in monorepo development
+- **Scope:** All developers
+- **Prevention:** Always use `cd packageName && pnpm run <command>` pattern
+
+## Related
+
+- **Documentation:** [CLAUDE.md](../../../CLAUDE.md#quick-command-reference)
+- **Monorepo Structure:** [CLAUDE.md](../../../CLAUDE.md#monorepo-structure-full)
+- **Related Learnings:** None yet
+
+---
+
+Last updated: 2024-10-28