@the-bearded-bear/claude-craft 7.0.0 → 7.1.0

package/Dev/i18n/en/Common/commands/ralph-run.md

@@ -221,6 +221,42 @@ Iteration 1 of 25 (Profile: medium_feature)
   Metrics exported:  .ralph/sessions/.../metrics-export.json
 ```
 
+## Failure Modes & Recovery
+
+### DoD Validator Failures
+
+When DoD validators fail repeatedly, Ralph applies escalating recovery:
+
+| Consecutive Failures | Action |
+|---------------------|--------|
+| 1-2 | Retry with context — Ralph includes previous error output |
+| 3 | Trigger circuit breaker check — evaluate if task is stuck |
+| 4+ | Circuit breaker trips — session stops with `exit_reason: circuit_breaker` |
+
+### Timeout Handling
+
+| Timeout Type | Default | Configuration |
+|-------------|---------|---------------|
+| Per-iteration | 5 min | `circuit_breaker.iteration_timeout` |
+| Total session | 30 min | `circuit_breaker.session_timeout` |
+| DoD command | 60 sec | `definition_of_done.timeout` |
+
+When a timeout fires:
+1. Current iteration is cancelled
+2. Partial progress is preserved in session state
+3. Circuit breaker counter increments
+4. Resume with `--continue=<session-id>` to retry
+
+### Common Exit Reasons
+
+| Exit Reason | Meaning | Recovery |
+|-------------|---------|----------|
+| `dod_complete` | All DoD criteria passed | Success — no action needed |
+| `circuit_breaker` | Too many failures | Review task scope, simplify DoD |
+| `max_iterations` | Iteration limit reached | Increase limit or break into subtasks |
+| `timeout` | Session timeout expired | Resume or increase timeout |
+| `user_abort` | User cancelled (Ctrl+C) | Resume with `--continue` |
+
 ## Best Practices
 
 1. **Use auto-detect**: Let Ralph configure DoD for your stack
@@ -228,6 +264,8 @@ Iteration 1 of 25 (Profile: medium_feature)
 3. **Use TDD**: Write tests first, let Ralph implement
 4. **Monitor dashboard**: Watch progress in real-time
 5. **Review metrics**: Analyze session metrics for optimization
+6. **Set realistic timeouts**: Match timeouts to task complexity
+7. **Use circuit breaker profiles**: Match profile to task type (quick_fix vs large_feature)
 
 ## Related
 

package/Dev/i18n/en/Common/templates/CLAUDE.md.template

@@ -13,23 +13,23 @@ This project uses **Claude Craft** rules for AI-assisted development.
 ```
 {{PROJECT_ROOT}}/
 ├── .claude/
-│   ├── rules/       # Coding standards (auto-loaded)
-│   ├── agents/      # Specialized AI agents
-│   ├── commands/    # Slash commands
-│   └── skills/      # Extended capabilities
-└── src/             # Application source code
+│   ├── references/   # Coding standards & architecture (auto-loaded)
+│   ├── agents/       # Specialized AI agents
+│   ├── commands/     # Slash commands (namespaced)
+│   └── skills/       # Extended capabilities
+└── src/              # Application source code
 ```
 
 ## Why (Purpose & Organization)
 
 ### Core Principles
-- **Analysis Before Action**: Always understand code before modifying (see `rules/01-workflow-analysis.md`)
-- **SOLID + KISS**: Clean, maintainable code (see `rules/04-solid-principles.md`)
-- **TDD/BDD**: Test-driven development (see `rules/07-testing.md`)
-- **Security First**: OWASP compliance (see `rules/11-security.md`)
+- **Analysis Before Action**: Always understand code before modifying (see `references/01-workflow-analysis.md`)
+- **SOLID + KISS**: Clean, maintainable code (see `references/04-solid-principles.md`)
+- **TDD/BDD**: Test-driven development (see `references/07-testing.md`)
+- **Security First**: OWASP compliance (see `references/11-security.md`)
 
 ### Architecture
-Refer to `.claude/rules/02-architecture*.md` for detailed patterns.
+Refer to `.claude/references/02-architecture*.md` for detailed patterns.
 
 ## How (Commands & Workflows)
 
@@ -56,15 +56,15 @@ make build             # Build project
 
 ## References
 
-| Topic | Rule File |
-|-------|-----------|
-| Workflow | `rules/01-workflow-analysis.md` |
-| Architecture | `rules/02-architecture*.md` |
-| Coding Standards | `rules/03-coding-standards.md` |
-| SOLID Principles | `rules/04-solid-principles.md` |
-| KISS/DRY/YAGNI | `rules/05-kiss-dry-yagni.md` |
-| Testing | `rules/07-testing.md` |
-| Security | `rules/11-security.md` |
+| Topic | Reference File |
+|-------|----------------|
+| Workflow | `references/01-workflow-analysis.md` |
+| Architecture | `references/02-architecture*.md` |
+| Coding Standards | `references/03-coding-standards.md` |
+| SOLID Principles | `references/04-solid-principles.md` |
+| KISS/DRY/YAGNI | `references/05-kiss-dry-yagni.md` |
+| Testing | `references/07-testing.md` |
+| Security | `references/11-security.md` |
 
 <!-- PROJECT-SPECIFIC-START -->
 ## Project Specifics

package/Dev/scripts/check-config.sh

@@ -244,175 +244,74 @@ check_common_installation() {
 }
 
 # ─────────────────────────────────────────────────────────────────────────────
-# Vérification Symfony
-# ─────────────────────────────────────────────────────────────────────────────
-check_symfony_installation() {
-    local path="$1"
-    local issues=0
-
-    if [[ ! -d "$path/.claude" ]]; then
-        log_error ".claude/: non trouvé"
-        return 1
-    fi
-
-    # Rules (obligatoire - generic + Symfony-specific, min 18)
-    # Generic: 7 files from Common/rules/ + Symfony: ~13 tech-specific
-    check_dir_count "$path/.claude/rules" "rules" 18 || ((issues++)) || true
-
-    # Commands/symfony (obligatoire, min 5)
-    check_dir_count "$path/.claude/commands/symfony" "commands/symfony" 5 || ((issues++)) || true
-
-    # Templates (obligatoire, min 5)
-    check_dir_count "$path/.claude/templates" "templates" 5 || ((issues++)) || true
-
-    # Checklists (obligatoire, min 3)
-    check_dir_count "$path/.claude/checklists" "checklists" 3 || ((issues++)) || true
-
-    # CLAUDE.md (obligatoire)
-    check_file_exists "$path/.claude/CLAUDE.md" "CLAUDE.md" || ((issues++)) || true
-
-    # Agents (obligatoire, min 1)
-    check_dir_count "$path/.claude/agents" "agents" 1 || ((issues++)) || true
-
-    # Optionnels
-    check_dir_optional "$path/.claude/adr" "adr"
-    check_dir_optional "$path/.claude/examples" "examples"
-
-    return $issues
-}
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Vérification Flutter
-# ─────────────────────────────────────────────────────────────────────────────
-check_flutter_installation() {
+# Technology Registry (data-driven validation)
+# Format: tech_name:cmd_namespace:min_rules:min_commands:min_templates:min_checklists
+# ─────────────────────────────────────────────────────────────────────────────
+TECH_REGISTRY=(
+    "symfony:symfony:18:5:5:3"
+    "flutter:flutter:14:5:3:2"
+    "react:react:12:5:2:2"
+    "reactnative:reactnative:15:5:2:2"
+    "python:python:10:5:2:2"
+    "angular:angular:10:5:2:2"
+    "csharp:csharp:10:5:2:2"
+    "laravel:laravel:10:5:2:2"
+    "vuejs:vuejs:10:5:2:2"
+    "php:php:10:5:2:2"
+)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Generic tech installation checker (data-driven)
+# ─────────────────────────────────────────────────────────────────────────────
+check_tech_installation() {
     local path="$1"
+    local tech="$2"
     local issues=0
 
-    if [[ ! -d "$path/.claude" ]]; then
-        log_error ".claude/: non trouvé"
-        return 1
-    fi
-
-    # Rules (obligatoire - generic + Flutter-specific, min 14)
-    # Generic: 7 files from Common/rules/ + Flutter: 8 tech-specific
-    check_dir_count "$path/.claude/rules" "rules" 14 || ((issues++)) || true
-
-    # Commands/flutter (obligatoire, min 5)
-    check_dir_count "$path/.claude/commands/flutter" "commands/flutter" 5 || ((issues++)) || true
-
-    # Templates (obligatoire, min 3)
-    check_dir_count "$path/.claude/templates" "templates" 3 || ((issues++)) || true
-
-    # Checklists (obligatoire, min 2)
-    check_dir_count "$path/.claude/checklists" "checklists" 2 || ((issues++)) || true
-
-    # CLAUDE.md (obligatoire)
-    check_file_exists "$path/.claude/CLAUDE.md" "CLAUDE.md" || ((issues++)) || true
-
-    # Agents (obligatoire, min 1)
-    check_dir_count "$path/.claude/agents" "agents" 1 || ((issues++)) || true
-
-    return $issues
-}
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Vérification React
-# ─────────────────────────────────────────────────────────────────────────────
-check_react_installation() {
-    local path="$1"
-    local issues=0
+    # Look up tech in registry
+    local entry=""
+    for reg in "${TECH_REGISTRY[@]}"; do
+        local reg_tech="${reg%%:*}"
+        if [[ "$reg_tech" == "$tech" ]]; then
+            entry="$reg"
+            break
+        fi
+    done
 
-    if [[ ! -d "$path/.claude" ]]; then
-        log_error ".claude/: non trouvé"
+    if [[ -z "$entry" ]]; then
+        log_warn "Technologie inconnue: $tech"
         return 1
     fi
 
-    # Rules (obligatoire - generic + React-specific, min 12)
-    # Generic: 7 files from Common/rules/ + React: 6 tech-specific
-    check_dir_count "$path/.claude/rules" "rules" 12 || ((issues++)) || true
-
-    # Commands/react (obligatoire, min 5)
-    check_dir_count "$path/.claude/commands/react" "commands/react" 5 || ((issues++)) || true
-
-    # Templates (obligatoire, min 2)
-    check_dir_count "$path/.claude/templates" "templates" 2 || ((issues++)) || true
-
-    # Checklists (obligatoire, min 2)
-    check_dir_count "$path/.claude/checklists" "checklists" 2 || ((issues++)) || true
-
-    # CLAUDE.md (obligatoire)
-    check_file_exists "$path/.claude/CLAUDE.md" "CLAUDE.md" || ((issues++)) || true
-
-    # Agents (obligatoire, min 1)
-    check_dir_count "$path/.claude/agents" "agents" 1 || ((issues++)) || true
-
-    return $issues
-}
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Vérification React Native
-# ─────────────────────────────────────────────────────────────────────────────
-check_reactnative_installation() {
-    local path="$1"
-    local issues=0
+    # Parse registry entry
+    IFS=':' read -r _ cmd_ns min_rules min_cmds min_templates min_checklists <<< "$entry"
 
     if [[ ! -d "$path/.claude" ]]; then
         log_error ".claude/: non trouvé"
         return 1
     fi
 
-    # Rules (obligatoire - generic + ReactNative-specific, min 15)
-    # Generic: 7 files from Common/rules/ + ReactNative: 9 tech-specific
-    check_dir_count "$path/.claude/rules" "rules" 15 || ((issues++)) || true
+    # Rules (generic + tech-specific)
+    check_dir_count "$path/.claude/rules" "rules" "$min_rules" || ((issues++)) || true
 
-    # Commands/reactnative (obligatoire, min 5)
-    check_dir_count "$path/.claude/commands/reactnative" "commands/reactnative" 5 || ((issues++)) || true
+    # Commands (tech namespace)
+    check_dir_count "$path/.claude/commands/${cmd_ns}" "commands/${cmd_ns}" "$min_cmds" || ((issues++)) || true
 
-    # Templates (obligatoire, min 2)
-    check_dir_count "$path/.claude/templates" "templates" 2 || ((issues++)) || true
+    # Templates
+    check_dir_count "$path/.claude/templates" "templates" "$min_templates" || ((issues++)) || true
 
-    # Checklists (obligatoire, min 2)
-    check_dir_count "$path/.claude/checklists" "checklists" 2 || ((issues++)) || true
+    # Checklists
+    check_dir_count "$path/.claude/checklists" "checklists" "$min_checklists" || ((issues++)) || true
 
-    # CLAUDE.md (obligatoire)
+    # CLAUDE.md
     check_file_exists "$path/.claude/CLAUDE.md" "CLAUDE.md" || ((issues++)) || true
 
-    # Agents (obligatoire, min 1)
+    # Agents
     check_dir_count "$path/.claude/agents" "agents" 1 || ((issues++)) || true
 
-    return $issues
-}
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Vérification Python
-# ─────────────────────────────────────────────────────────────────────────────
-check_python_installation() {
-    local path="$1"
-    local issues=0
-
-    if [[ ! -d "$path/.claude" ]]; then
-        log_error ".claude/: non trouvé"
-        return 1
-    fi
-
-    # Rules (obligatoire - generic + Python-specific, min 10)
-    # Generic: 7 files from Common/rules/ + Python: 4 tech-specific
-    check_dir_count "$path/.claude/rules" "rules" 10 || ((issues++)) || true
-
-    # Commands/python (obligatoire, min 5)
-    check_dir_count "$path/.claude/commands/python" "commands/python" 5 || ((issues++)) || true
-
-    # Templates (obligatoire, min 2)
-    check_dir_count "$path/.claude/templates" "templates" 2 || ((issues++)) || true
-
-    # Checklists (obligatoire, min 2)
-    check_dir_count "$path/.claude/checklists" "checklists" 2 || ((issues++)) || true
-
-    # CLAUDE.md (obligatoire)
-    check_file_exists "$path/.claude/CLAUDE.md" "CLAUDE.md" || ((issues++)) || true
-
-    # Agents (obligatoire, min 1)
-    check_dir_count "$path/.claude/agents" "agents" 1 || ((issues++)) || true
+    # Optional directories
+    check_dir_optional "$path/.claude/adr" "adr"
+    check_dir_optional "$path/.claude/examples" "examples"
 
     return $issues
 }
@@ -428,32 +327,8 @@ check_module() {
 
     echo -e "   ${BOLD}$label:${NC}"
 
-    case "$tech" in
-        symfony)
-            check_symfony_installation "$path"
-            issues=$?
-            ;;
-        flutter)
-            check_flutter_installation "$path"
-            issues=$?
-            ;;
-        react)
-            check_react_installation "$path"
-            issues=$?
-            ;;
-        reactnative)
-            check_reactnative_installation "$path"
-            issues=$?
-            ;;
-        python)
-            check_python_installation "$path"
-            issues=$?
-            ;;
-        *)
-            log_warn "Technologie inconnue: $tech"
-            issues=1
-            ;;
-    esac
+    check_tech_installation "$path" "$tech"
+    issues=$?
 
     return $issues
 }

package/Dev/scripts/lib/shell-ui.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# shell-ui.sh — Shared UI functions for Claude-Craft shell scripts
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# Provides consistent colors, logging, headers, and section formatting.
+# Source this file from any install/check script:
+#
+#   source "$(dirname "${BASH_SOURCE[0]}")/lib/shell-ui.sh"
+#
+# ═══════════════════════════════════════════════════════════════════════════
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ANSI Colors
+# ─────────────────────────────────────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m'
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Logging functions
+# ─────────────────────────────────────────────────────────────────────────────
+ui_info()    { echo -e "${BLUE}[INFO]${NC} $1"; }
+ui_success() { echo -e "${GREEN}[OK]${NC} $1"; }
+ui_warning() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+ui_error()   { echo -e "${RED}[ERROR]${NC} $1"; }
+ui_dry_run() { echo -e "${YELLOW}[DRY-RUN]${NC} $1"; }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Check-style logging (indented with icons)
+# ─────────────────────────────────────────────────────────────────────────────
+ui_check_ok()   { echo -e "     ${GREEN}✓${NC} $1"; }
+ui_check_warn() { echo -e "     ${YELLOW}⚠${NC} $1"; }
+ui_check_fail() { echo -e "     ${RED}✗${NC} $1"; }
+ui_check_info() { echo -e "     ${BLUE}ℹ${NC} $1"; }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Section headers
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Print a boxed header with icon
+# Usage: ui_header "Title text"
+ui_header() {
+    echo ""
+    echo -e "${BOLD}╔════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${BOLD}║${NC}  $1"
+    echo -e "${BOLD}╚════════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+}
+
+# Print a colored boxed header
+# Usage: ui_box "Title" "$CYAN"
+ui_box() {
+    local title="$1"
+    local color="${2:-$CYAN}"
+    echo -e "${color}╔════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${color}║${NC}  ${title}"
+    echo -e "${color}╚════════════════════════════════════════════════════════════╝${NC}"
+}
+
+# Print a separator line
+# Usage: ui_separator
+ui_separator() {
+    echo -e "${BOLD}══════════════════════════════════════════════════════════════${NC}"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Progress indicators
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Print a step indicator
+# Usage: ui_step 1 5 "Installing common rules..."
+ui_step() {
+    local current="$1"
+    local total="$2"
+    local message="$3"
+    echo -e "${CYAN}[${current}/${total}]${NC} ${message}"
+}

package/README.md

@@ -24,7 +24,7 @@ A comprehensive framework for AI-assisted development with [Claude Code](https:/
 - **155 Slash Commands**: Automated workflows, code generation, **sprint management, quality gates, batch processing, acceptance testing**
 - **BMAD v6 Framework**: Complete project management with status-based routing, quality gates, and batch execution
 - **Ralph Wiggum**: Continuous loop execution with Definition of Done validation
-- **249 Skills**: Best practices in official Claude Code format (architecture, testing, security)
+- **50 Skills**: Best practices in official Claude Code format (architecture, testing, security)
 - **33 Templates**: Code generation patterns + BMAD templates
 - **21 Checklists**: Quality gates for commits, features, releases
 - **Hooks System**: Pre/Post tool execution, quality gates, notifications, **BMAD context injection**

package/cli/lib/tech-registry.js

@@ -0,0 +1,140 @@
+/**
+ * Technology registry — Single Source of Truth for all supported stacks.
+ *
+ * This module centralizes technology metadata used across:
+ * - CLI constants (TECHNOLOGIES)
+ * - Install scripts (install-{tech}-rules.sh)
+ * - check-config.sh validation
+ * - Documentation references
+ *
+ * @module cli/lib/tech-registry
+ */
+
+/**
+ * @typedef {Object} TechEntry
+ * @property {string} name - Internal identifier (lowercase, no hyphens)
+ * @property {string} displayName - Human-readable name
+ * @property {string} desc - Short description for CLI display
+ * @property {string} namespace - Command namespace (used in commands/{namespace}/)
+ * @property {string} i18nDir - Directory name under Dev/i18n/{lang}/
+ * @property {string} installScript - Install script filename
+ * @property {string} version - Current supported version
+ */
+
+/** @type {Record<string, TechEntry>} */
+const TECH_REGISTRY = {
+  symfony: {
+    name: 'symfony',
+    displayName: 'Symfony / PHP',
+    desc: 'PHP backend with Clean Architecture, DDD, API Platform',
+    namespace: 'symfony',
+    i18nDir: 'Symfony',
+    installScript: 'install-symfony-rules.sh',
+    version: '8.0 / PHP 8.5',
+  },
+  flutter: {
+    name: 'flutter',
+    displayName: 'Flutter / Dart',
+    desc: 'Mobile Dart with BLoC pattern, Material/Cupertino',
+    namespace: 'flutter',
+    i18nDir: 'Flutter',
+    installScript: 'install-flutter-rules.sh',
+    version: '3.38 / Dart 3.10',
+  },
+  react: {
+    name: 'react',
+    displayName: 'React',
+    desc: 'Frontend JS/TS with Hooks, State management, A11y',
+    namespace: 'react',
+    i18nDir: 'React',
+    installScript: 'install-react-rules.sh',
+    version: '19.x',
+  },
+  reactnative: {
+    name: 'reactnative',
+    displayName: 'React Native',
+    desc: 'Mobile JS/TS with Navigation, Native modules',
+    namespace: 'reactnative',
+    i18nDir: 'ReactNative',
+    installScript: 'install-reactnative-rules.sh',
+    version: '0.76+',
+  },
+  angular: {
+    name: 'angular',
+    displayName: 'Angular',
+    desc: 'Frontend TS with Signals, Standalone components, RxJS',
+    namespace: 'angular',
+    i18nDir: 'Angular',
+    installScript: 'install-angular-rules.sh',
+    version: '19.x',
+  },
+  csharp: {
+    name: 'csharp',
+    displayName: 'C# / .NET',
+    desc: 'Backend with Clean Architecture, CQRS, MediatR, EF Core',
+    namespace: 'csharp',
+    i18nDir: 'CSharp',
+    installScript: 'install-csharp-rules.sh',
+    version: '10 LTS / C# 14',
+  },
+  laravel: {
+    name: 'laravel',
+    displayName: 'Laravel',
+    desc: 'PHP backend with Actions, Pest PHP, Sanctum',
+    namespace: 'laravel',
+    i18nDir: 'Laravel',
+    installScript: 'install-laravel-rules.sh',
+    version: '12.x / PHP 8.5',
+  },
+  vuejs: {
+    name: 'vuejs',
+    displayName: 'Vue.js',
+    desc: 'Frontend JS/TS with Composition API, Pinia, Vitest',
+    namespace: 'vuejs',
+    i18nDir: 'VueJS',
+    installScript: 'install-vuejs-rules.sh',
+    version: '3.5+',
+  },
+  php: {
+    name: 'php',
+    displayName: 'PHP',
+    desc: 'Backend PHP 8.5 with PSR-12, PHPStan, Pest PHP',
+    namespace: 'php',
+    i18nDir: 'PHP',
+    installScript: 'install-php-rules.sh',
+    version: '8.5',
+  },
+  python: {
+    name: 'python',
+    displayName: 'Python',
+    desc: 'Backend with FastAPI, async/await, Type hints',
+    namespace: 'python',
+    i18nDir: 'Python',
+    installScript: 'install-python-rules.sh',
+    version: '3.13+',
+  },
+  docker: {
+    name: 'docker',
+    displayName: 'Docker',
+    desc: 'Dockerfile, Compose, CI/CD, Debugging',
+    namespace: 'docker',
+    i18nDir: 'Docker',
+    installScript: 'install-infra-rules.sh',
+    version: 'latest',
+  },
+};
+
+/** All tech keys (excluding docker which is infra) */
+const INSTALLABLE_TECHS = Object.keys(TECH_REGISTRY).filter((k) => k !== 'docker');
+
+/** Get display name for a tech key */
+function getDisplayName(tech) {
+  return TECH_REGISTRY[tech]?.displayName ?? tech;
+}
+
+/** Get all tech keys */
+function getAllTechKeys() {
+  return Object.keys(TECH_REGISTRY);
+}
+
+export { TECH_REGISTRY, INSTALLABLE_TECHS, getDisplayName, getAllTechKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-bearded-bear/claude-craft",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "A comprehensive framework for AI-assisted development with Claude Code. Install standardized rules, agents, and commands for your projects.",
   "type": "module",
   "main": "cli/index.js",