claude-cli-advanced-starter-pack 1.1.0 → 1.8.0

package/templates/commands/refactor-prep.template.md

@@ -0,0 +1,192 @@
+---
+description: Pre-refactoring safety checklist - ensure safe refactoring conditions
+---
+
+# Refactor Prep
+
+Comprehensive safety checklist before starting any refactoring work. Ensures you can safely make changes and recover if needed.
+
+## Usage
+
+```
+/refactor-prep
+/refactor-prep --scope src/components
+/refactor-prep --quick  # Abbreviated checklist
+```
+
+## Safety Checklist
+
+### 1. Git Status
+- [ ] Working directory is clean
+- [ ] On correct branch (not main/master)
+- [ ] Remote is up to date
+
+### 2. Test Coverage
+- [ ] All tests passing
+- [ ] Affected code has test coverage
+- [ ] E2E tests available for critical paths
+
+### 3. Backup Points
+- [ ] Create rollback commit/tag
+- [ ] Document current behavior
+- [ ] Screenshot/record current UI state
+
+### 4. Dependencies
+- [ ] No pending dependency updates
+- [ ] Lock file is committed
+- [ ] Build succeeds
+
+### 5. Documentation
+- [ ] Refactoring scope defined
+- [ ] Breaking changes identified
+- [ ] Migration plan documented
+
+## Implementation
+
+### Step 1: Git Safety Check
+
+```bash
+# Check working directory
+git status
+
+# Verify branch
+git branch --show-current
+
+# Check sync with remote
+git fetch && git status -uno
+```
+
+### Step 2: Test Status
+
+```bash
+# Run full test suite
+npm test
+
+# Check coverage for affected files
+npm run coverage -- --collectCoverageFrom="src/components/**"
+```
+
+### Step 3: Create Rollback Point
+
+```bash
+# Tag current state
+git tag pre-refactor-$(date +%Y%m%d)
+
+# Create backup branch
+git branch backup/pre-refactor-$(date +%Y%m%d)
+```
+
+### Step 4: Build Verification
+
+```bash
+# Clean build
+rm -rf node_modules/.cache dist/
+npm run build
+
+# Type check
+npm run typecheck
+```
+
+## Output Report
+
+```
+Refactor Prep Checklist
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Git Status:
+  ✅ Working directory clean
+  ✅ On branch: feature/refactor-components
+  ✅ Up to date with origin
+
+Tests:
+  ✅ All 145 tests passing
+  ⚠️ Affected files have 67% coverage (target: 80%)
+  ✅ E2E tests passing
+
+Backup:
+  ✅ Created tag: pre-refactor-20260130
+  ✅ Created branch: backup/pre-refactor-20260130
+
+Build:
+  ✅ TypeScript: No errors
+  ✅ Build: Success
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Ready Score: 95%
+
+Recommendations:
+  1. Consider adding tests for src/components/Modal.tsx (0% coverage)
+  2. Document expected behavior changes
+
+Proceed with refactoring? [Y/N]
+```
+
+## Scope Analysis
+
+When `--scope` is provided:
+
+1. **Identify Files** - List all files in scope
+2. **Find Dependencies** - Map imports and exports
+3. **Calculate Impact** - Estimate affected components
+4. **Suggest Order** - Recommend refactoring sequence
+
+```
+Scope Analysis: src/components/
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Files in Scope: 23
+Direct Dependencies: 45
+Potential Impact: 67 files
+
+Dependency Graph:
+  Button.tsx
+    ├── Used by: 12 components
+    ├── Tests: 3 files
+    └── Risk: Medium
+
+  Modal.tsx
+    ├── Used by: 8 components
+    ├── Tests: 0 files
+    └── Risk: High (no tests!)
+
+Recommended Order:
+  1. Add tests for Modal.tsx (reduce risk)
+  2. Refactor leaf components first (Button, Icon)
+  3. Work up to container components
+  4. Update integration tests last
+```
+
+## Quick Mode
+
+Use `--quick` for abbreviated checklist:
+
+```
+Quick Refactor Prep
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Git clean
+✅ Tests passing
+✅ Backup created: pre-refactor-20260130
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Ready to refactor!
+```
+
+## Recovery Commands
+
+If refactoring goes wrong:
+
+```bash
+# Return to pre-refactor state
+git checkout pre-refactor-20260130
+
+# Or restore from backup branch
+git checkout backup/pre-refactor-20260130
+
+# Delete failed changes
+git reset --hard backup/pre-refactor-20260130
+```
+
+## Related Commands
+
+- `/refactor-check` - Pre-commit quality gate
+- `/refactor-cleanup` - Auto-fix common issues
+- `/refactor-analyze` - Deep code analysis

package/templates/docs/AI_ARCHITECTURE_CONSTITUTION.template.md

@@ -0,0 +1,198 @@
+# {{project.name}} - AI Architecture Constitution
+
+**Version**: 1.0.0
+**Created**: {{date}}
+**Status**: Active
+
+## Purpose
+
+This document defines non-negotiable rules that Claude must follow when working on this project. These laws protect data integrity, prevent architectural violations, and ensure code quality.
+
+---
+
+## Boot Sequence (MANDATORY)
+
+Before responding to any request, Claude must:
+
+1. Load this constitution file
+2. Enforce all laws - refuse or auto-refactor violations
+3. Reference project-specific documentation as needed
+
+---
+
+## Law 1: Data Storage
+
+**CRITICAL: All user data MUST follow the designated storage pattern.**
+
+| Data Type | Storage | Status |
+|-----------|---------|--------|
+| User preferences | Designated database | Required |
+| Session data | Designated storage | Required |
+| Configuration | Config files | Allowed |
+| Cached data | Cache directory | Temporary only |
+
+### Forbidden Patterns
+
+- Storing user data in flat files when database is available
+- Mixing storage approaches inconsistently
+- Bypassing repository/service layer for direct database access
+
+---
+
+## Law 2: Architecture Patterns
+
+### Required Patterns
+
+| Pattern | Rule |
+|---------|------|
+| **Repository** | All database access via repository layer |
+| **Service** | Business logic in service layer |
+| **Controller** | HTTP handling only in controller layer |
+| **Component** | UI logic in component layer |
+
+### Forbidden Patterns
+
+- Direct database queries in controllers/components
+- Business logic in UI components
+- Cross-layer dependencies that bypass layers
+
+---
+
+## Law 3: Code Quality
+
+### Must Do
+
+1. **Type Safety** - Use TypeScript/type hints strictly
+2. **Error Handling** - All async operations must have error handling
+3. **Testing** - New features require test coverage
+4. **Documentation** - Public APIs must be documented
+
+### Must Avoid
+
+1. **Any/unknown types** - Explicit types required
+2. **Silent failures** - All errors must be logged/handled
+3. **Magic strings** - Use constants/enums
+4. **Nested callbacks** - Use async/await
+
+---
+
+## Law 4: Security
+
+### Non-Negotiable
+
+1. **No secrets in code** - Use environment variables
+2. **No hardcoded credentials** - Use secret management
+3. **Validate all inputs** - Never trust user input
+4. **Sanitize outputs** - Prevent XSS/injection
+
+### Protected Files
+
+- `.env` files - Never commit
+- Credential files - Never read content aloud
+- Private keys - Never expose
+
+---
+
+## Law 5: Performance
+
+### Required
+
+1. **Lazy loading** - Load resources on demand
+2. **Pagination** - Never load unlimited records
+3. **Caching** - Cache expensive operations
+4. **Async operations** - Don't block main thread
+
+### Thresholds
+
+| Metric | Maximum |
+|--------|---------|
+| API response | 500ms |
+| Page load | 3s |
+| Database query | 100ms |
+| Bundle size | 500KB |
+
+---
+
+## Law 6: Git Workflow
+
+### Commit Standards
+
+1. **Message format**: `type(scope): description`
+2. **Types**: feat, fix, refactor, docs, test, chore
+3. **Atomic commits**: One logical change per commit
+
+### Forbidden
+
+- Committing to main/master directly (without review)
+- Force pushing to shared branches
+- Committing sensitive files
+
+---
+
+## Law 7: Dependency Management
+
+### Rules
+
+1. **Lock files** - Always commit package-lock.json/yarn.lock
+2. **Version pinning** - Use exact versions in production
+3. **Security updates** - Apply promptly
+4. **Minimal dependencies** - Avoid bloat
+
+### Forbidden
+
+- Installing deprecated packages
+- Using packages with known vulnerabilities
+- Adding dependencies without justification
+
+---
+
+## Enforcement
+
+### Violation Response
+
+When a violation is detected:
+
+1. **Stop** - Do not proceed with the violating action
+2. **Explain** - Describe why this violates the constitution
+3. **Suggest** - Provide compliant alternative
+4. **Refactor** - Auto-fix if possible
+
+### Auto-Refactor Triggers
+
+Claude will automatically refactor when:
+
+- Direct database access detected outside repository
+- Hardcoded secrets detected
+- Missing error handling detected
+- Type safety violations detected
+
+---
+
+## Amendment Process
+
+To modify this constitution:
+
+1. Create a proposal document
+2. Review impact on existing code
+3. Update this file with version bump
+4. Apply changes to codebase
+
+---
+
+## Quick Reference
+
+### Always Do
+- Use repository pattern for data access
+- Handle all errors explicitly
+- Use environment variables for config
+- Write tests for new features
+
+### Never Do
+- Store secrets in code
+- Bypass architectural layers
+- Commit to main directly
+- Use any/unknown types
+
+---
+
+*This constitution is enforced by Claude Code for {{project.name}}*

package/templates/docs/DETAILED_GOTCHAS.template.md

@@ -0,0 +1,347 @@
+# {{project.name}} - Detailed Gotchas
+
+Problem-solution patterns learned from development experience. Reference this before making changes.
+
+---
+
+## Quick Reference
+
+| Category | Common Issue | Solution |
+|----------|--------------|----------|
+| Async | Race conditions | Use proper await/locks |
+| State | Stale data | Invalidate caches properly |
+| UI | Flash of content | Add loading states |
+| API | Timeout errors | Implement retry logic |
+
+---
+
+## Async Operations
+
+### Problem: Race Conditions in State Updates
+
+**Symptoms:**
+- Intermittent bugs
+- Inconsistent state
+- "It works sometimes"
+
+**Root Cause:**
+Multiple async operations completing out of order.
+
+**Solution:**
+```typescript
+// BAD - race condition
+async function fetchBoth() {
+  fetchA().then(setA);
+  fetchB().then(setB);
+}
+
+// GOOD - controlled ordering
+async function fetchBoth() {
+  const [a, b] = await Promise.all([fetchA(), fetchB()]);
+  setA(a);
+  setB(b);
+}
+```
+
+### Problem: Unhandled Promise Rejections
+
+**Symptoms:**
+- Silent failures
+- Incomplete operations
+- No error messages
+
+**Solution:**
+```typescript
+// BAD - no error handling
+fetchData().then(process);
+
+// GOOD - explicit error handling
+fetchData()
+  .then(process)
+  .catch(error => {
+    console.error('Fetch failed:', error);
+    showUserError('Unable to load data');
+  });
+
+// BETTER - async/await with try/catch
+try {
+  const data = await fetchData();
+  process(data);
+} catch (error) {
+  handleError(error);
+}
+```
+
+---
+
+## State Management
+
+### Problem: Stale Closure Data
+
+**Symptoms:**
+- Event handlers use old values
+- Updates don't reflect current state
+
+**Root Cause:**
+Closures capturing stale variable references.
+
+**Solution:**
+```typescript
+// BAD - stale closure
+useEffect(() => {
+  const handler = () => console.log(count);
+  window.addEventListener('click', handler);
+}, []); // count will always be initial value
+
+// GOOD - use ref for current value
+const countRef = useRef(count);
+countRef.current = count;
+useEffect(() => {
+  const handler = () => console.log(countRef.current);
+  window.addEventListener('click', handler);
+  return () => window.removeEventListener('click', handler);
+}, []);
+```
+
+### Problem: Cache Invalidation
+
+**Symptoms:**
+- Old data displayed after updates
+- Refresh required to see changes
+
+**Solution:**
+```typescript
+// Implement proper cache invalidation
+async function updateItem(id, data) {
+  await api.update(id, data);
+  // Invalidate relevant caches
+  cache.delete(`item:${id}`);
+  cache.delete('items:list');
+  // Refetch if needed
+  await refetchQueries(['items']);
+}
+```
+
+---
+
+## UI Patterns
+
+### Problem: Flash of Unstyled/Wrong Content
+
+**Symptoms:**
+- Brief flicker on page load
+- Content shifts after hydration
+
+**Solution:**
+```typescript
+// Add loading states
+const [isLoading, setIsLoading] = useState(true);
+
+if (isLoading) {
+  return <Skeleton />;
+}
+
+// Use CSS for initial state
+// globals.css
+.app { opacity: 0; }
+.app.loaded { opacity: 1; transition: opacity 0.2s; }
+```
+
+### Problem: Layout Shift
+
+**Symptoms:**
+- Content jumps around
+- Poor CLS score
+
+**Solution:**
+```css
+/* Reserve space for dynamic content */
+.image-container {
+  aspect-ratio: 16/9;
+}
+
+.text-content {
+  min-height: 100px;
+}
+```
+
+---
+
+## API Integration
+
+### Problem: Timeout Errors
+
+**Symptoms:**
+- Requests fail on slow connections
+- Inconsistent availability
+
+**Solution:**
+```typescript
+// Implement retry with exponential backoff
+async function fetchWithRetry(url, options = {}, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const response = await fetch(url, {
+        ...options,
+        timeout: 5000 + (i * 2000) // Increase timeout with each retry
+      });
+      return response;
+    } catch (error) {
+      if (i === retries - 1) throw error;
+      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
+    }
+  }
+}
+```
+
+### Problem: Rate Limiting
+
+**Symptoms:**
+- 429 Too Many Requests
+- API blocks after burst traffic
+
+**Solution:**
+```typescript
+// Implement request queue with rate limiting
+const queue = new PQueue({
+  concurrency: 2,
+  intervalCap: 10,
+  interval: 1000
+});
+
+async function rateLimitedFetch(url) {
+  return queue.add(() => fetch(url));
+}
+```
+
+---
+
+## Testing
+
+### Problem: Flaky Tests
+
+**Symptoms:**
+- Tests pass locally, fail in CI
+- Intermittent failures
+
+**Common Causes & Solutions:**
+
+1. **Timing issues:**
+   ```typescript
+   // BAD
+   await click(button);
+   expect(modal).toBeVisible();
+
+   // GOOD
+   await click(button);
+   await waitFor(() => expect(modal).toBeVisible());
+   ```
+
+2. **Shared state:**
+   ```typescript
+   // Reset state between tests
+   beforeEach(() => {
+     resetTestDatabase();
+     clearMocks();
+   });
+   ```
+
+3. **Order dependency:**
+   ```typescript
+   // Make tests independent
+   // Don't rely on other tests' side effects
+   ```
+
+---
+
+## Performance
+
+### Problem: Memory Leaks
+
+**Symptoms:**
+- Increasing memory usage
+- Slowdown over time
+
+**Common Causes & Solutions:**
+
+```typescript
+// BAD - event listener not cleaned up
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+}, []);
+
+// GOOD - cleanup on unmount
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+```
+
+### Problem: Excessive Re-renders
+
+**Symptoms:**
+- Slow UI updates
+- Laggy interactions
+
+**Solution:**
+```typescript
+// Use memoization
+const MemoizedComponent = React.memo(ExpensiveComponent);
+
+// Memoize callbacks
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+
+// Memoize computed values
+const sortedItems = useMemo(() => {
+  return items.sort((a, b) => a.name.localeCompare(b.name));
+}, [items]);
+```
+
+---
+
+## Git Workflow
+
+### Problem: Merge Conflicts in Lock Files
+
+**Solution:**
+```bash
+# Don't try to manually merge lock files
+git checkout --theirs package-lock.json
+npm install
+git add package-lock.json
+```
+
+### Problem: Accidental Commit to Main
+
+**Solution:**
+```bash
+# Undo last commit (keep changes)
+git reset --soft HEAD~1
+
+# Create new branch with changes
+git checkout -b feature/my-changes
+
+# Commit on correct branch
+git commit -m "feat: my changes"
+```
+
+---
+
+## Debugging Checklist
+
+When something doesn't work:
+
+1. [ ] Check browser console for errors
+2. [ ] Check network tab for failed requests
+3. [ ] Verify environment variables are set
+4. [ ] Clear cache/hard refresh
+5. [ ] Check for type errors
+6. [ ] Review recent changes
+7. [ ] Check dependencies are installed
+8. [ ] Verify database/API is running
+
+---
+
+*Add new gotchas as you encounter them. Future you will thank you.*