cc-agentic-framework 1.14.1

package/framework/modules/coding/skills/coding/structuring-code/DRY-PRINCIPLES.md

@@ -0,0 +1,285 @@
+# DRY Principles
+
+This document provides detailed guidance on identifying and handling code duplication.
+
+---
+
+## Types of Duplication
+
+### Exact Duplication
+
+**Definition:** Identical or nearly identical code blocks in multiple locations.
+
+**How to spot:**
+- Copy-paste detector tools flag it
+- Same logic, same variable names
+- Bug fixes needed in multiple places
+- Obvious when reading code
+
+**Example scenario:**
+```
+// Found in OrderService
+if (order.total > 100) {
+    discount = order.total * 0.1;
+    order.total = order.total - discount;
+}
+
+// Same code in CartService
+if (cart.total > 100) {
+    discount = cart.total * 0.1;
+    cart.total = cart.total - discount;
+}
+```
+
+**Resolution:** Extract to shared function with parameterized entity.
+
+---
+
+### Structural Duplication
+
+**Definition:** Same pattern or structure with different data or types.
+
+**How to spot:**
+- Similar shape, different details
+- Repeated patterns across different domains
+- Same sequence of operations on different entities
+
+**Example scenario:**
+```
+// User validation
+function validateUser(user) {
+    if (!user.name) throw new Error('Name required');
+    if (!user.email) throw new Error('Email required');
+    if (!isValidEmail(user.email)) throw new Error('Invalid email');
+}
+
+// Product validation
+function validateProduct(product) {
+    if (!product.name) throw new Error('Name required');
+    if (!product.sku) throw new Error('SKU required');
+    if (!isValidSku(product.sku)) throw new Error('Invalid SKU');
+}
+```
+
+**Resolution:** Consider generic validation framework, schema validation, or accept as reasonable duplication if domains evolve differently.
+
+---
+
+### Conceptual Duplication
+
+**Definition:** Same concept implemented differently in multiple places.
+
+**How to spot:**
+- Same business rule, different code
+- Multiple ways to do the same thing
+- Inconsistent behavior for same operation
+
+**Example scenario:**
+```
+// In OrderService: checks user role inline
+if (user.role === 'admin' || user.role === 'manager') {
+    // allow action
+}
+
+// In ReportService: different role check
+if (user.permissions.includes('view-reports')) {
+    // allow action
+}
+
+// Same concept: "can user do this?" but implemented differently
+```
+
+**Resolution:** Establish single source of truth for the concept (authorization service, permission checker).
+
+---
+
+## When to Extract
+
+### Rule of Three
+
+**Principle:** Consider extraction on the third occurrence.
+
+**Rationale:**
+- First time: Just write it
+- Second time: Notice the similarity, but might be coincidence
+- Third time: Pattern confirmed, extract
+
+**Caveat:** Don't wait for three if:
+- Business concept clearly exists
+- Duplication is complex (many lines)
+- You're about to add more occurrences
+
+### Business Concept Exists
+
+**Extract when you can name it:**
+- "Calculate discount" → `calculateDiscount()`
+- "Format currency" → `formatCurrency()`
+- "Check permission" → `hasPermission()`
+
+**If you can't name it clearly, maybe don't extract:**
+- Vague names like `doThing()` or `processData()` suggest the abstraction isn't real
+- Forced abstraction creates confusion
+
+### Changes Propagate Together
+
+**Strong signal for extraction:**
+- When you change one copy, you change all copies
+- Bug in one means bug in all
+- Feature request affects all instances
+
+**This indicates true duplication, not coincidence.**
+
+---
+
+## When NOT to Extract
+
+### Incidental Similarity
+
+**Definition:** Code looks the same now but serves different purposes.
+
+**Indicators:**
+- Different business domains
+- Different expected evolution paths
+- Similar by coincidence, not by design
+
+**Example:**
+```
+// User registration validation
+function validateRegistration(data) {
+    if (!data.email) throw new Error('Email required');
+    if (!data.password) throw new Error('Password required');
+}
+
+// Newsletter signup validation
+function validateNewsletterSignup(data) {
+    if (!data.email) throw new Error('Email required');
+    if (!data.preferences) throw new Error('Preferences required');
+}
+```
+
+**Why not extract:** These will evolve differently. Registration may add phone number, newsletter may add frequency. Forcing them together creates awkward code.
+
+---
+
+### Different Evolution Paths
+
+**Ask:** Will these change together or separately?
+
+**Same evolution (extract):**
+- Tax calculation for orders and invoices (tax rules change together)
+- Date formatting across the app (format requirements are global)
+
+**Different evolution (keep separate):**
+- Admin form validation vs customer form validation
+- Internal API serialization vs external API serialization
+
+---
+
+### Abstraction Adds Complexity
+
+**"The wrong abstraction is worse than duplication."**
+
+**Signs of wrong abstraction:**
+- Parameters for every variation
+- Conditionals inside to handle cases
+- Difficult to understand what it does
+- Changes require understanding all use cases
+
+**Example of problematic extraction:**
+```
+// Trying to handle all cases
+function formatEntity(entity, options) {
+    if (options.type === 'user') {
+        // user-specific logic
+    } else if (options.type === 'order') {
+        // order-specific logic
+    } else if (options.type === 'product') {
+        // product-specific logic
+    }
+    // ... continues with many branches
+}
+```
+
+**Better:** Keep separate, focused functions until true common pattern emerges.
+
+---
+
+## Extraction Patterns
+
+### Extract Function
+
+**When:** Same logic in multiple functions.
+
+**How:**
+1. Identify the duplicated code
+2. Create new function with descriptive name
+3. Parameterize the differences
+4. Replace duplicates with calls to new function
+5. Run tests
+
+### Extract Class/Module
+
+**When:** Group of related functions that work together.
+
+**How:**
+1. Identify related functions and data
+2. Create class/module with clear responsibility
+3. Move functions as methods
+4. Update callers
+5. Run tests
+
+### Extract Constant/Configuration
+
+**When:** Same literal value in multiple places.
+
+**How:**
+1. Identify the repeated value
+2. Create named constant with meaningful name
+3. Replace literals with constant reference
+4. Document the constant if purpose isn't obvious
+
+### Parameterize
+
+**When:** Same logic, different data.
+
+**How:**
+1. Identify the varying parts
+2. Make them parameters
+3. Ensure parameter names communicate purpose
+4. Keep parameter count reasonable (use options object if many)
+
+---
+
+## Abstraction Quality
+
+### Good Abstractions
+
+**Characteristics:**
+- Hide complexity behind simple interface
+- Stable over time (implementation changes, interface doesn't)
+- Clear, descriptive name
+- Single responsibility
+- Easy to use correctly, hard to use incorrectly
+
+### Bad Abstractions
+
+**Characteristics:**
+- Leaky (implementation details escape)
+- Unstable (interface changes frequently)
+- Vague name
+- Does too many things
+- Requires understanding internals to use
+
+### Signs Abstraction Is Needed
+
+- Duplication is spreading
+- Same bugs fixed in multiple places
+- New team members implement same thing differently
+- Code reviews catch "we already have this"
+
+### Signs of Premature Abstraction
+
+- Only one use case exists
+- You're guessing future needs
+- Abstraction name is vague or forced
+- You're building "infrastructure" before features

package/framework/modules/coding/skills/coding/structuring-code/FILE-ORGANIZATION.md

@@ -0,0 +1,278 @@
+# File Organization Principles
+
+This document provides detailed guidance on organizing files and directories for maintainable codebases.
+
+---
+
+## One Responsibility Per File
+
+### Core Principle
+
+Each file should have a single, clear purpose that can be described in one sentence.
+
+**Good indicators:**
+- File name accurately describes its entire content
+- You can explain what the file does without saying "and"
+- Changes to one concept don't require editing this file
+
+**Problem indicators:**
+- File contains unrelated classes or functions
+- File name is vague (utils.ts, helpers.py, common.cs)
+- Multiple developers frequently edit the same file for unrelated reasons
+
+### What Belongs Together
+
+**Keep together:**
+- A class and its directly related types (enums, interfaces it implements)
+- A component and its local styles/types (if framework supports)
+- A function and its parameter/return types
+- Test utilities specific to one test file
+
+**Split apart:**
+- Classes with different responsibilities
+- Utilities used across multiple files (extract to shared location)
+- Configuration and implementation
+- Domain logic and infrastructure concerns
+
+### Naming Files
+
+**Match content to name:**
+- File `UserService.ts` exports `UserService` class
+- File `calculate-totals.py` exports `calculate_totals` function
+- File `OrderTypes.swift` contains Order-related type definitions
+
+**Avoid vague names:**
+- `utils.ts` - Instead, name by purpose: `string-utils.ts`, `date-formatting.ts`
+- `helpers.py` - Instead, name by domain: `order-helpers.py`, `validation.py`
+- `misc.cs` - Split into properly named files
+
+---
+
+## File Size Guidelines
+
+### Target Ranges
+
+| Size | Assessment | Action |
+|------|------------|--------|
+| < 30 lines | Possibly over-split | Consider if this could merge with related file |
+| 30-100 lines | Small, focused | Good for single-purpose utilities |
+| 100-300 lines | Typical, healthy | Normal range for most files |
+| 300-400 lines | Large but acceptable | Review for hidden complexity |
+| 400-500 lines | At limit | Proactively plan splitting |
+| 500+ lines | **Not allowed** | Must split before committing |
+
+### 500 Lines is the Hard Limit
+
+Files exceeding 500 lines are not acceptable in this codebase. If a file approaches this limit:
+
+1. **Identify responsibilities** - What distinct concerns does the file handle?
+2. **Plan the split** - How can these be separated into focused files?
+3. **Execute the refactor** - Split before the file grows further
+
+**No exceptions for:**
+- Generated code - Generate to multiple files if needed
+- Test suites - Split by test category or feature
+- Configuration - Use includes or split by domain
+
+**Only acceptable reasons for temporary >500:**
+- Active refactoring in progress (with TODO to complete)
+- Legacy code being actively migrated
+
+### When to Split a Large File
+
+**Split when:**
+- File contains distinct sections with different purposes
+- Two developers frequently need different parts
+- You can name the extracted parts clearly
+- Tests would be easier if split
+
+**Don't split when:**
+- Content is cohesive (single algorithm, single component)
+- Split would require excessive cross-file imports
+- You can't name the splits clearly
+- Split is purely to hit a line count target
+
+---
+
+## Directory Structure Principles
+
+### Feature-Based vs Layer-Based
+
+**Feature-based (preferred for most projects):**
+```
+src/
+  orders/
+    OrderList.tsx
+    OrderDetail.tsx
+    order-service.ts
+    order-types.ts
+    __tests__/
+  users/
+    UserProfile.tsx
+    user-service.ts
+    user-types.ts
+```
+
+**Layer-based (common but often problematic):**
+```
+src/
+  components/
+    OrderList.tsx
+    OrderDetail.tsx
+    UserProfile.tsx
+  services/
+    order-service.ts
+    user-service.ts
+  types/
+    order-types.ts
+    user-types.ts
+```
+
+**Why feature-based is often better:**
+- Related code stays together (colocation)
+- Easier to understand a feature in isolation
+- Simpler to extract features to separate packages
+- Reduces cross-directory navigation
+
+**When layer-based makes sense:**
+- Very small projects (few features)
+- Framework mandates it (some older MVC frameworks)
+- Truly shared layers (database, infrastructure)
+
+### Directory Depth
+
+| Depth | Example | Assessment |
+|-------|---------|------------|
+| 2 levels | `src/orders/` | Simple, easy to navigate |
+| 3 levels | `src/features/orders/` | Still manageable |
+| 4 levels | `src/app/features/orders/components/` | Getting deep |
+| 5+ levels | `src/app/modules/features/orders/components/list/` | Navigation burden |
+
+**Keep depth shallow by:**
+- Avoiding unnecessary grouping folders
+- Using flat structure within features
+- Extracting to separate packages instead of deeper nesting
+
+### Colocation Principle
+
+**Keep together things that change together:**
+- Component and its styles
+- Component and its tests
+- Feature and its types
+- Route and its loader/action
+
+**Benefits:**
+- Easier to find related files
+- Simpler imports (relative paths)
+- Clear ownership boundaries
+- Easier to move or delete features
+
+---
+
+## Index/Barrel Files
+
+### When to Use
+
+**Use barrel files (`index.ts`) for:**
+- Public API of a module/package
+- Explicit export of what's available externally
+- Re-exporting from multiple internal files
+
+**Avoid barrel files for:**
+- Every directory (creates maintenance burden)
+- Internal implementation details
+- When they cause circular dependencies
+
+### Barrel File Patterns
+
+**Good: Clear public API**
+```typescript
+// features/orders/index.ts
+export { OrderList } from './OrderList';
+export { OrderDetail } from './OrderDetail';
+export type { Order, OrderStatus } from './order-types';
+```
+
+**Problematic: Re-exporting everything**
+```typescript
+// Don't: barrel that hides structure
+export * from './OrderList';
+export * from './OrderDetail';
+export * from './order-service';
+export * from './order-types';
+// Consumer can't tell what's public vs internal
+```
+
+---
+
+## Common Organizational Patterns
+
+### Shared/Common Code
+
+**Organize by domain, not by type:**
+```
+src/
+  shared/
+    date-utils/        # Date formatting, parsing
+    validation/        # Validation helpers
+    api-client/        # HTTP client wrapper
+    ui-components/     # Truly shared UI
+```
+
+**Not by vague grouping:**
+```
+src/
+  shared/
+    utils/             # Unclear what's here
+    helpers/           # Same problem
+    common/            # Too vague
+```
+
+### Test File Placement
+
+**Option 1: Colocated (often preferred)**
+```
+src/
+  orders/
+    OrderList.tsx
+    OrderList.test.tsx    # Right next to source
+```
+
+**Option 2: Parallel structure**
+```
+src/
+  orders/
+    OrderList.tsx
+tests/
+  orders/
+    OrderList.test.tsx    # Mirrors source structure
+```
+
+**Colocated benefits:**
+- Obvious which tests exist
+- Easy to update tests with code
+- Clear when tests are missing
+
+**Parallel benefits:**
+- Clean separation of concerns
+- Easier to exclude from production builds
+- Some frameworks require it
+
+### Configuration Files
+
+**Project root for tool configs:**
+```
+project/
+  package.json
+  tsconfig.json
+  .eslintrc.js
+  .prettierrc
+  src/
+```
+
+**Feature config with feature:**
+```
+src/
+  orders/
+    order-config.ts    # Feature-specific configuration
+```