@qazuor/claude-code-config 0.1.0

package/templates/docs/learnings/optimization-tips.md

@@ -0,0 +1,146 @@
+# Optimization Tips
+
+**Date:** 2024-10-28
+
+**Category:** Performance / Best Practices
+
+## Problem
+
+Inefficient development practices lead to:
+
+- Wasted time searching for documentation
+- Redundant work analyzing dependencies
+- Slow development cycles
+- Lost context between sessions
+
+## Solution
+
+**Development Optimization Strategies:**
+
+### 1. Use Context7 for Library Docs
+
+Saves tokens and gets up-to-date documentation:
+
+```typescript
+// Instead of searching Google, use MCP tools:
+mcp__context7__resolve-library-id("hono")
+mcp__context7__get-library-docs("/honojs/hono")
+```
+
+**Benefits:**
+
+- Always current documentation
+- Saves Claude context tokens
+- Faster than web search
+- Integrated into workflow
+
+**Works for:** Hono, Drizzle, React, TanStack, Zod, Vitest, Astro, etc.
+
+### 2. Use Dependency Mapper
+
+Track dependencies automatically instead of manual analysis:
+
+```bash
+# Analyze dependencies
+pnpm run dependency-map
+
+# Generate dependency graph
+# Shows: version conflicts, security issues, outdated packages
+```
+
+**Benefits:**
+
+- Automatic security scanning
+- Version conflict detection
+- Dependency tree visualization
+- Update recommendations
+
+### 3. Batch Related Changes
+
+Group related changes in single commits:
+
+```bash
+# ✅ GOOD - Logical grouping
+git commit -m "feat(db): add booking model, schema, and tests"
+# Files: booking.schema.ts, booking.model.ts, booking.model.test.ts
+
+# ❌ BAD - Separate commits for related changes
+git commit -m "add booking schema"
+git commit -m "add booking model"
+git commit -m "add booking tests"
+```
+
+**Benefits:**
+
+- Clearer git history
+- Easier code review
+- Atomic changes
+- Simpler rollbacks
+
+### 4. Group Tests by Feature
+
+Organize tests by feature instead of by type:
+
+```
+test/
+├── booking/              # Feature-based
+│   ├── create.test.ts
+│   ├── update.test.ts
+│   └── validation.test.ts
+└── user/                 # Feature-based
+    ├── auth.test.ts
+    └── profile.test.ts
+
+# Instead of type-based:
+test/
+├── unit/
+├── integration/
+└── e2e/
+```
+
+**Benefits:**
+
+- Easier to find related tests
+- Better feature coverage visibility
+- Simpler test maintenance
+- Clear test organization
+
+### 5. Use MCP Servers Effectively
+
+Leverage integrated MCP servers:
+
+- **Context7**: Library documentation
+- **Neon**: Database operations
+- **GitHub**: Issue tracking, PRs
+- **Vercel**: Deployment management
+- **Linear**: Project management
+
+**Example workflow:**
+
+```bash
+# Check database schema
+mcp__neon__describe_branch
+
+# Create GitHub issue
+mcp__github__create_issue
+
+# Deploy to Vercel
+mcp__vercel__deploy
+```
+
+## Impact
+
+- **Severity:** Medium - Improves efficiency, not critical
+- **Frequency:** Daily development
+- **Scope:** All developers
+- **Prevention:** Integrate optimization practices into daily workflow
+
+## Related
+
+- **MCP Servers:** [.claude/docs/mcp-servers.md](../mcp-servers.md)
+- **Development Workflow:** [CLAUDE.md](../../../CLAUDE.md#development-workflow)
+- **Related Learnings:** None yet
+
+---
+
+Last updated: 2024-10-28

package/templates/docs/learnings/planning-linear-sync-workflow.md

@@ -0,0 +1,70 @@
+# Planning and Linear Sync Workflow
+
+**Date:** 2024-10-28
+
+**Category:** Planning / GitHub / Linear / Workflow
+
+## Problem
+
+Manual planning synchronization causes:
+
+- Planning sessions not tracked in GitHub
+- Lost context when switching devices
+- No visibility into task progress
+- Forgotten task completions
+
+## Solution
+
+**Workflow Best Practices:**
+
+1. **Sync after planning approval** - Always offer to sync planning to Linear/GitHub
+
+   ```bash
+   pnpm planning:sync .claude/sessions/planning/P-XXX-feature-name/
+   ```
+
+2. **Commit before marking complete** - Code MUST be committed before task completion
+   - Prevents lost work
+   - Enables cross-device workflow
+   - Creates audit trail
+
+3. **Auto-generate commit suggestions** - Group files logically:
+   - Schemas (validation layer)
+   - Models + Tests (data layer)
+   - Services (business logic)
+   - API (routes and controllers)
+
+4. **Use conventional commits** - `feat/refactor/fix` with proper scope
+
+   ```bash
+   feat(db): add booking model and schema
+   refactor(api): consolidate error handlers
+   fix(auth): correct JWT validation
+   ```
+
+5. **Cross-device workflow:**
+   - Commit → Push → Access from anywhere
+   - .checkpoint.json tracks progress
+   - issues-sync.json maintains GitHub state
+
+6. **Three sync options:**
+   - **Execute**: Run suggested commits immediately
+   - **Modify**: Edit commit messages/groupings
+   - **Skip**: Skip with warning (not recommended)
+
+## Impact
+
+- **Severity:** High - Affects project tracking and collaboration
+- **Frequency:** Every feature development
+- **Scope:** All planning sessions (Level 3 workflows)
+- **Prevention:** Always sync after planning approval, commit before completion
+
+## Related
+
+- **Full Documentation:** [.claude/docs/workflows/task-completion-protocol.md](../workflows/task-completion-protocol.md)
+- **Planning Workflow:** [.claude/docs/workflows/phase-1-planning.md](../workflows/phase-1-planning.md)
+- **Related Learnings:** None yet
+
+---
+
+Last updated: 2024-10-28

package/templates/docs/learnings/shell-compatibility-fish.md

@@ -0,0 +1,46 @@
+# Shell Compatibility - Fish Shell
+
+**Date:** 2024-10-28
+
+**Category:** Shell / Terminal / DevOps
+
+## Problem
+
+Using `for` loops directly in the terminal causes Fish shell to hang indefinitely, blocking the entire development workflow.
+
+## Solution
+
+- **DON'T use `for` loops in terminal** - Fish shell hangs
+- Use alternatives like `find -exec` for batch operations
+- Use `xargs` for processing multiple items
+- Write shell scripts for complex loops instead of running directly in terminal
+
+**Example:**
+
+```bash
+# ❌ BAD - Hangs in Fish
+for file in *.md; do echo $file; done
+
+# ✅ GOOD - Works in Fish
+find . -name "*.md" -exec echo {} \;
+
+# ✅ GOOD - Alternative with xargs
+ls *.md | xargs -I {} echo {}
+```
+
+## Impact
+
+- **Severity:** High - Blocks development workflow
+- **Frequency:** Common when doing batch operations
+- **Scope:** All developers using Fish shell
+- **Prevention:** Use alternative commands documented above
+
+## Related
+
+- **Documentation:** Fish shell documentation on loops
+- **Best Practices:** [.claude/docs/standards/code-standards.md](../standards/code-standards.md)
+- **Related Learnings:** None yet
+
+---
+
+Last updated: 2024-10-28

package/templates/docs/learnings/test-organization-structure.md

@@ -0,0 +1,68 @@
+# Test Organization and Structure
+
+**Date:** 2024-10-28
+
+**Category:** Testing / Project Structure
+
+## Problem
+
+Tests placed incorrectly (e.g., in `src/` alongside source code) cause:
+
+- Import path confusion
+- Build artifacts including test files
+- Difficulty maintaining test/source separation
+- Inconsistent test discovery
+
+## Solution
+
+**Test Organization Rules:**
+
+1. **Tests go in `test/` folder at package/app root** - NOT in `src/`
+2. **Mirror source folder structure** - `src/models/user.model.ts` → `test/models/user.model.test.ts`
+3. **Use relative imports in tests** - Import from `../src/` not same-folder
+4. **Migrate gradually** - When editing a package, move its tests to correct structure
+
+**Example Structure:**
+
+```
+packages/db/
+├── src/
+│   ├── models/
+│   │   ├── user.model.ts
+│   │   └── booking.model.ts
+│   └── services/
+│       └── user.service.ts
+└── test/
+    ├── models/
+    │   ├── user.model.test.ts     # Mirrors src/models/
+    │   └── booking.model.test.ts
+    └── services/
+        └── user.service.test.ts   # Mirrors src/services/
+```
+
+**Import Example:**
+
+```typescript
+// ✅ CORRECT - test/models/user.model.test.ts
+import { UserModel } from '../../src/models/user.model.js';
+
+// ❌ WRONG - Don't import from same folder
+import { UserModel } from './user.model.js';
+```
+
+## Impact
+
+- **Severity:** Medium - Affects build and test reliability
+- **Frequency:** Common when creating new packages
+- **Scope:** All packages and apps
+- **Prevention:** Follow test/ structure from project start
+
+## Related
+
+- **Full Rules:** [.claude/docs/standards/testing-standards.md](../standards/testing-standards.md)
+- **Architecture:** [.claude/docs/standards/architecture-patterns.md](../standards/architecture-patterns.md)
+- **Related Learnings:** None yet
+
+---
+
+Last updated: 2024-10-28