oden-forge 2.4.0 → 3.0.0

package/.claude/commands/oden/adr.md

@@ -0,0 +1,241 @@
+---
+allowed-tools: Bash, Read, Write, LS, Glob, Grep, Task
+description: Living Architecture Decision Records (ADR) system with AI-suggested missing ADRs and compliance validation
+created: 2026-03-27T15:02:15Z
+updated: 2026-03-27T15:02:15Z
+---
+
+# Oden Forge - Architecture Decision Records (ADR)
+
+Sistema **Living ADR** con detección inteligente de decisiones faltantes, validación de compliance y mantenimiento automático.
+
+## Usage
+
+```bash
+/oden:adr                         # Lista ADRs existentes y sugiere faltantes
+/oden:adr create [título]         # Crear nuevo ADR interactivo
+/oden:adr suggest                 # AI-suggested missing ADRs
+/oden:adr validate               # Validar compliance con ADRs
+/oden:adr update [número]        # Actualizar ADR existente
+/oden:adr review                 # Revisar ADRs obsoletos
+```
+
+## 🎯 Living ADR Philosophy
+
+### Problema Resuelto
+- ❌ **Antes**: Decisiones arquitectónicas perdidas o desactualizadas
+- ❌ **Antes**: No hay sistema para detectar decisiones faltantes  
+- ❌ **Antes**: Compliance manual e inconsistente
+- ✅ **Ahora**: ADRs vivientes con AI-assisted management y validación automática
+
+### Living ADR Features
+1. **AI-Suggested Missing ADRs** - Detecta automáticamente decisiones no documentadas
+2. **Compliance Validation** - Verifica que el código sigue las decisiones registradas
+3. **Update Workflows** - Mantiene ADRs actualizados con cambios del proyecto
+4. **Cross-Reference Detection** - Encuentra conflictos entre ADRs
+5. **Template-Based Creation** - Templates inteligentes según tipo de decisión
+
+## Directory Structure
+
+```
+docs/reference/
+├── adrs/
+│   ├── 0001-record-architecture-decisions.md    # Meta-ADR
+│   ├── 0002-database-technology-choice.md        # Example ADR
+│   ├── 0003-api-authentication-strategy.md      # Example ADR
+│   └── template.md                               # ADR template
+└── adr-index.md                                  # Generated index
+```
+
+## Implementation
+
+### 1. List ADRs and Suggest Missing (`/oden:adr`)
+
+**Preflight:**
+- Crear `docs/reference/adrs/` si no existe
+- Verificar que existe template
+- Escanear technical-decisions.md para contexto
+
+**Main Algorithm:**
+```bash
+echo "📋 Architecture Decision Records Status"
+echo ""
+
+# Create directory if needed
+mkdir -p docs/reference/adrs/
+
+# List existing ADRs
+echo "## Existing ADRs"
+if ls docs/reference/adrs/*-*.md 2>/dev/null | grep -q .; then
+    ls -1 docs/reference/adrs/ | grep -E "^[0-9]{4}-.*\.md$" | while read adr; do
+        number=$(echo "$adr" | cut -d'-' -f1)
+        title=$(grep "^# " "docs/reference/adrs/$adr" | head -1 | sed 's/^# //' | sed "s/^ADR-[0-9]*: //")
+        status=$(grep "^Status:" "docs/reference/adrs/$adr" | head -1 | sed 's/^Status: //')
+        echo "- ADR-$number: $title [$status]"
+    done
+else
+    echo "No ADRs found. Use '/oden:adr create' to start."
+fi
+
+echo ""
+echo "## 🤖 AI-Suggested Missing ADRs"
+echo ""
+echo "Analyzing codebase for undocumented architectural decisions..."
+```
+
+### 2. Create ADR (`/oden:adr create [título]`)
+
+**Interactive Creation Process:**
+- Determine ADR type from title or interactive selection
+- Generate next sequential ADR number
+- Create from appropriate template
+- Auto-populate with project context
+
+### 3. Validate Compliance (`/oden:adr validate`)
+
+**Compliance Validation Engine:**
+```bash
+echo "🔍 Validating ADR Compliance"
+echo ""
+
+VIOLATIONS=0
+
+# Read all ADRs and extract compliance rules
+echo "Loading ADR compliance rules..."
+for adr in docs/reference/adrs/[0-9]*.md; do
+    if [ -f "$adr" ]; then
+        ADR_NUM=$(basename "$adr" | cut -d'-' -f1)
+        TITLE=$(grep "^# " "$adr" | head -1)
+        STATUS=$(grep "^Status:" "$adr" | head -1 | sed 's/^Status: //')
+        
+        # Only validate accepted ADRs
+        if [ "$STATUS" = "Accepted" ]; then
+            echo "  - Validating ADR-$ADR_NUM"
+            
+            # Extract validation rules from "Compliance" section
+            if grep -q "## Compliance" "$adr"; then
+                # Perform compliance validation
+                validate_adr_compliance "$adr" || VIOLATIONS=$((VIOLATIONS + 1))
+            fi
+        fi
+    fi
+done
+
+if [ $VIOLATIONS -eq 0 ]; then
+    echo "✅ All ADRs are in compliance"
+    echo "Compliance Score: 100%"
+else
+    echo "⚠️  Found $VIOLATIONS compliance violations"
+    echo "Compliance Score: $((100 - VIOLATIONS * 10))%"
+fi
+
+# Integration with Context Preservation System (Stream D)
+if command -v /oden:context >/dev/null 2>&1; then
+    echo ""
+    echo "📊 Recording compliance metrics in context system..."
+fi
+```
+
+### 4. AI-Suggested Missing ADRs (`/oden:adr suggest`)
+
+**Deep Gap Analysis:**
+Uses specialized AI agents to analyze:
+- Technical decisions documentation gaps
+- Code pattern analysis for undocumented decisions
+- Dependency analysis for technology choices
+- API design pattern gaps
+- Database and storage decision gaps
+
+### 5. Update and Review ADRs
+
+**Maintenance Workflows:**
+- Smart update suggestions based on codebase changes
+- Obsolescence detection for outdated decisions
+- Cross-reference validation
+- Status transition management
+
+## ADR Templates
+
+### Core Template Structure
+```markdown
+# ADR-{NNNN}: {Title}
+
+**Status**: {Proposed|Accepted|Deprecated|Superseded}  
+**Date**: {YYYY-MM-DD}  
+**Decision**: {Single sentence summary}  
+
+## Context and Problem Statement
+{Describe the architectural decision and problem}
+
+## Decision Drivers
+- {Driver 1}
+- {Driver 2}
+
+## Considered Options  
+### Option 1: {Name}
+**Pros**: {Benefits}
+**Cons**: {Drawbacks}
+
+## Decision Outcome
+**Chosen Option**: Option X
+**Rationale**: {Why selected}
+
+## Consequences
+### Positive
+- {Positive consequence 1}
+### Negative  
+- {Negative consequence 1}
+
+## Compliance
+### Validation Rules
+- {Rule 1: How to verify this decision is followed}
+### Implementation Requirements
+- {Requirement 1}
+
+## Related Decisions
+- ADR-{NNNN}: {Related decision}
+
+## Implementation Notes
+{Code links, configuration files, etc.}
+```
+
+## Integration with Quality Gates
+
+### Pre-commit Integration
+```bash
+# ADR Compliance Gate
+echo "📋 Checking ADR compliance..."
+/oden:adr validate --quiet
+if [ $? -ne 0 ]; then
+    echo "❌ ADR compliance violations detected"
+    echo "Run '/oden:adr validate' for details"
+    exit 1
+fi
+```
+
+### Stream Integration
+- **Stream B (Architecture)**: Enhanced architect command uses ADRs
+- **Stream C (Testing)**: Testing requirements defined in ADRs
+- **Stream D (Context)**: Architecture drift monitoring via ADR compliance
+
+## Living ADR Benefits
+
+### For Development Teams
+1. **Never lose architectural decisions** - Everything documented and maintained
+2. **AI-suggested missing ADRs** - Proactive decision documentation  
+3. **Automated compliance checking** - Ensure decisions are followed
+4. **Template-guided creation** - Consistent, high-quality ADRs
+5. **Cross-reference detection** - Avoid conflicting decisions
+
+### For Oden Forge Quality Gates
+1. **Measurable architecture compliance** - Foundation for quality gates
+2. **Decision impact tracking** - Understand architectural consequences
+3. **Evolution visibility** - Track how architecture changes over time
+4. **Knowledge preservation** - No lost institutional knowledge
+5. **Automated governance** - Remove manual architecture oversight
+
+---
+
+**Living ADRs transform architecture from invisible to visible, from static to dynamic, from forgotten to enforced.**
+
+They solve the real-world problem of "invisible architecture" - architectural decisions that exist in code but are never documented, leading to inconsistent implementations and lost knowledge between team members and across time.

package/.claude/commands/oden/architect.md

@@ -1,6 +1,7 @@
 ---
 allowed-tools: Bash, Read, Write, LS, Glob, Grep, Task, TodoWrite, WebSearch, WebFetch
 description: Crear/completar technical-decisions.md con arquitectura completa
+updated: 2026-03-27T07:08:49Z
 ---
 
 # Oden Forge - Technical Architect
@@ -28,7 +29,9 @@ Como Technical Architect, debes:
 2. **Diseñar schema de base de datos** completo
 3. **Definir interfaces TypeScript** para todos los modelos
 4. **Documentar patrones de arquitectura**
-5. **Identificar dependencias y riesgos**
+5. **Especificar estructura de código** y organización interna
+6. **Definir límites y restricciones** de calidad
+7. **Identificar dependencias y riesgos**
 
 ## Proceso
 
@@ -60,7 +63,239 @@ Basado en el stack, diseña:
    └── utils/          # Helper functions
    ```
 
-### Paso 3: Schema de Base de Datos
+### Paso 3: Especificaciones de Código y Estructura
+
+**🆕 CRÍTICO:** Define HOW el código debe estar organizado internamente para prevenir god files y inconsistencias.
+
+#### 3.1 Límites de Archivos y Módulos
+
+```markdown
+## Code Structure Guidelines
+
+### File Size Limits (ENFORCE STRICTLY)
+- **Components**: MAX 200 líneas (150 típico)
+- **Hooks**: MAX 100 líneas (50-75 típico)
+- **Services**: MAX 300 líneas (200 típico)
+- **Utils**: MAX 150 líneas (100 típico)
+- **Types**: MAX 200 líneas (split por dominio)
+- **Stores/State**: MAX 250 líneas (split por feature)
+
+### Module Organization (HIGH COHESION)
+```
+src/
+├── modules/           # Feature-based modules
+│   ├── auth/
+│   │   ├── components/    # Max 5 files
+│   │   ├── hooks/         # Max 3 files
+│   │   ├── services/      # Max 2 files
+│   │   ├── types.ts       # Single types file
+│   │   └── index.ts       # Public API only
+│   ├── orders/
+│   │   ├── components/
+│   │   ├── hooks/
+│   │   └── ...
+│   └── shared/        # Cross-module utilities
+│       ├── components/
+│       ├── hooks/
+│       └── utils/
+```
+
+### Layer Dependencies (ENFORCE DIRECTION)
+```
+UI Layer (components/)
+  ↓ can import
+Business Layer (hooks/, services/)
+  ↓ can import  
+Data Layer (types/, utils/)
+
+❌ FORBIDDEN: Data layer importing Business/UI
+❌ FORBIDDEN: Circular dependencies
+✅ ALLOWED: Same layer imports
+```
+
+#### 3.2 Internal File Structure Standards
+
+**Component Structure (MANDATORY)**
+```typescript
+// TEMPLATE: Component file structure
+import React from 'react';
+// 1. External imports first
+// 2. Internal imports second  
+// 3. Types last
+
+// Types (if small, <20 lines)
+interface Props {
+  // Max 8 props, use config object if more
+}
+
+// Main component (Max 150 lines)
+export function ComponentName({ ...props }: Props) {
+  // 1. Hooks first (max 5)
+  // 2. Derived state (max 3 computations)
+  // 3. Event handlers (max 5)
+  // 4. Effects last (max 3)
+  
+  // Early returns for loading/error states
+  if (loading) return <Loading />;
+  if (error) return <Error />;
+  
+  return (
+    // JSX (max 50 lines)
+  );
+}
+
+// Helper components (if needed, max 2)
+function HelperComponent() {
+  // Max 25 lines
+}
+
+// Exports last
+export type { Props };
+```
+
+**Service Structure (MANDATORY)**
+```typescript
+// TEMPLATE: Service file structure
+import { ApiClient } from '../shared';
+// External imports
+// Internal imports  
+// Types
+
+// Types for this service only
+interface ServiceConfig {
+  // Service-specific config
+}
+
+interface ServiceResponse<T> {
+  // Standardized response format
+}
+
+// Main service class (Max 200 lines)
+class FeatureService {
+  private config: ServiceConfig;
+  
+  constructor(config: ServiceConfig) {
+    this.config = config;
+  }
+  
+  // Public methods (max 8)
+  async getAll(): Promise<ServiceResponse<Item[]>> {
+    // Max 25 lines per method
+  }
+  
+  // Private methods last
+  private helper(): void {
+    // Max 15 lines per helper
+  }
+}
+
+// Factory function
+export function createFeatureService(config: ServiceConfig): FeatureService {
+  return new FeatureService(config);
+}
+
+// Export types
+export type { ServiceConfig, ServiceResponse };
+```
+
+#### 3.3 Code Quality Enforcement
+
+**Complexity Limits**
+- **Cyclomatic complexity**: Max 10 per function
+- **Nesting depth**: Max 4 levels
+- **Function parameters**: Max 5 (use config object)
+- **Class methods**: Max 12 public methods
+- **Import statements**: Max 15 per file
+
+**Naming Conventions**
+```typescript
+// Files: kebab-case
+user-profile.component.ts
+order-management.service.ts
+
+// Components: PascalCase
+UserProfile, OrderManagement
+
+// Functions/variables: camelCase
+getUserProfile, orderData
+
+// Constants: SCREAMING_SNAKE_CASE
+MAX_RETRY_ATTEMPTS, API_ENDPOINTS
+
+// Types/Interfaces: PascalCase
+interface UserProfile {}
+type OrderStatus = 'pending' | 'completed';
+```
+
+**Error Handling Patterns**
+```typescript
+// Service layer: Throw typed errors
+class ServiceError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public status?: number
+  ) {
+    super(message);
+  }
+}
+
+// Hook layer: Return error states
+function useFeature() {
+  const [state, setState] = useState<{
+    data: Data | null;
+    error: ServiceError | null;
+    loading: boolean;
+  }>({
+    data: null,
+    error: null,
+    loading: false
+  });
+  
+  // Error boundary at component level
+}
+```
+
+#### 3.4 Testing Requirements per Layer
+
+**Component Testing (MANDATORY)**
+```typescript
+// Every component MUST have:
+describe('ComponentName', () => {
+  // 1. Render test
+  it('renders without crashing', () => {});
+  
+  // 2. Props test
+  it('handles all prop variations', () => {});
+  
+  // 3. Interaction test  
+  it('handles user interactions', () => {});
+  
+  // 4. Error state test
+  it('handles error states', () => {});
+});
+```
+
+**Service Testing (MANDATORY)**
+```typescript
+// Every service MUST have:
+describe('FeatureService', () => {
+  // 1. Happy path tests
+  it('returns data successfully', () => {});
+  
+  // 2. Error handling tests
+  it('handles API errors gracefully', () => {});
+  
+  // 3. Edge case tests
+  it('handles empty responses', () => {});
+  
+  // 4. Integration tests
+  it('works with real API', () => {});
+});
+```
+```
+
+### Paso 4: Schema de Base de Datos
 
 Para cada entidad del sistema:
 
@@ -89,7 +324,7 @@ Para cada entidad del sistema:
 - updated_at: Auto-update on modification
 ```
 
-### Paso 4: Interfaces TypeScript
+### Paso 5: Interfaces TypeScript
 
 ```typescript
 // Types para cada entidad
@@ -120,7 +355,7 @@ interface ApiError {
 }
 ```
 
-### Paso 5: Patrones de Arquitectura
+### Paso 6: Patrones de Arquitectura
 
 Documenta patrones para:
 
@@ -144,7 +379,7 @@ Documenta patrones para:
    - Code splitting
    - Memoization
 
-### Paso 6: Seguridad
+### Paso 7: Seguridad
 
 Documenta:
 - Autenticación flow
@@ -153,7 +388,7 @@ Documenta:
 - CORS policy
 - Rate limiting
 
-### Paso 7: APIs
+### Paso 8: APIs
 
 Define endpoints principales:
 
@@ -178,11 +413,47 @@ Define endpoints principales:
 | DELETE | /api/{resource}/:id | Delete | Yes | Admin |
 ```
 
+### Paso 9: Quality Gates Integration
+
+**🆕 Para integración con quality gates:**
+
+```markdown
+## Measurable Requirements
+
+### Code Structure Metrics (ENFORCE)
+- File count per module: MAX 15 files
+- Lines per file: See limits above
+- Cyclomatic complexity: MAX 10
+- Import depth: MAX 3 levels
+- Duplicate code: MAX 3% similarity
+
+### Architecture Compliance (VALIDATE)
+- Layer dependency direction: STRICT
+- Circular dependencies: ZERO tolerance
+- Public API surface: Document all exports
+- Type coverage: MIN 95%
+
+### Testing Coverage (MEASURE)
+- Unit tests: MIN 85% coverage
+- Integration tests: All API endpoints
+- Component tests: All user interactions
+- E2E tests: Critical user flows
+
+### Performance Benchmarks (TRACK)
+- Bundle size: MAX defined per route
+- Initial load: MAX 2s
+- API response: MAX 500ms p95
+- Memory usage: Monitor growth
+```
+
 ## Output
 
 Al completar, el archivo `docs/reference/technical-decisions.md` debe tener:
 
 - [ ] 2000+ líneas de contenido
+- [ ] **🆕 Code structure guidelines** (300-500 líneas)
+- [ ] **🆕 Internal organization patterns** (200-300 líneas)
+- [ ] **🆕 Quality enforcement rules** (150-200 líneas)
 - [ ] Schema de BD completo para todas las entidades
 - [ ] Interfaces TypeScript para todos los modelos
 - [ ] Diagrama de arquitectura (ASCII o mermaid)
@@ -190,6 +461,7 @@ Al completar, el archivo `docs/reference/technical-decisions.md` debe tener:
 - [ ] APIs definidas
 - [ ] Consideraciones de seguridad
 - [ ] Performance targets
+- [ ] **🆕 Testing requirements per layer**
 
 ---
 
@@ -204,6 +476,9 @@ Crear especificaciones técnicas detalladas (800-1200 líneas) para módulos esp
 - **Edge cases** y manejo de errores
 - **APIs** y contratos de datos
 - **Testing scenarios**
+- **🆕 Internal code organization** para el módulo
+- **🆕 File structure and limits** específicos
+- **🆕 Quality requirements** del módulo
 
 ### Usage:
 ```bash
@@ -212,6 +487,29 @@ Crear especificaciones técnicas detalladas (800-1200 líneas) para módulos esp
 /oden:architect spec payments    # Procesamiento de pagos
 ```
 
+### 🆕 Enhanced Spec Output:
+```markdown
+## Module: {nombre}
+
+### Code Structure
+- Files organization: {specific to module}
+- Size limits: {adjusted for complexity}
+- Dependencies: {what can this import}
+- Public API: {exported interfaces}
+
+### Internal Architecture  
+- Layer organization
+- State management pattern
+- Error handling strategy
+- Testing approach
+
+### Quality Gates
+- Specific metrics for this module
+- Complexity thresholds
+- Coverage requirements
+- Performance targets
+```
+
 ---
 
 ## CHECKLIST MODE: /oden:architect checklist
@@ -220,28 +518,40 @@ Verificación automática antes de empezar a codificar.
 
 ### Verifica:
 - ✅ technical-decisions.md completo (>2000 líneas)
+- ✅ **🆕 Code structure guidelines** definidas
+- ✅ **🆕 Quality enforcement rules** establecidas
 - ✅ Schema de BD definido
 - ✅ Interfaces TypeScript creadas
 - ✅ Specs de módulos principales (>800 líneas c/u)
 - ✅ Patrones de arquitectura documentados
+- ✅ **🆕 Testing requirements** especificados
 - ✅ Total documentación >8000 líneas
 
-### Output:
+### 🆕 Enhanced Validation:
 ```
 🎯 CHECKLIST PRE-CÓDIGO
 ═══════════════════════════
 
 ✅ technical-decisions.md: 2,847 líneas
+✅ Code structure: 487 líneas
+✅ Quality rules: 156 líneas  
 ✅ auth-spec.md: 1,203 líneas
 ✅ orders-spec.md: 987 líneas
 ❌ payments-spec.md: FALTA
 ⚠️  Schema BD: 89% completo
 
-TOTAL: 7,234 / 8,000 líneas mínimas
+TOTAL: 8,234 / 8,000 líneas mínimas
 
 🚨 BLOQUEADORES:
 - Completar payments-spec.md
 - Finalizar schema de BD
+- Definir testing strategy
+
+📊 QUALITY READINESS:
+✅ File size limits defined
+✅ Layer dependencies mapped  
+❌ Complexity thresholds missing
+⚠️  Testing requirements 73% complete
 
 SIGUIENTE: /oden:architect spec payments
 ```
@@ -257,3 +567,17 @@ Después de completar arquitectura y specs:
 2. /oden:epic [feature]    → Epic + tasks + work streams
 3. /oden:work [epic]       → Desarrollo con Teams
 ```
+
+---
+
+## 🆕 Integration with Living Quality Gates
+
+Este comando ahora produce arquitectura que puede ser validada automáticamente por:
+
+- **Code structure compliance checkers**
+- **Dependency direction validators**  
+- **File size and complexity monitors**
+- **Testing coverage requirements**
+- **Performance benchmark definitions**
+
+La salida es **measurable** y **enforceable** durante el desarrollo.