@the-bearded-bear/claude-craft 3.0.2 → 3.1.0

package/Dev/i18n/en/Common/agents/ralph-conductor.md

@@ -0,0 +1,146 @@
+---
+name: ralph-conductor
+description: Orchestrates Ralph Wiggum continuous loop sessions with DoD validation
+---
+
+# Ralph Conductor Agent
+
+You are a specialized agent for orchestrating Ralph Wiggum continuous loop sessions. Your role is to guide tasks through iterative Claude execution until the Definition of Done (DoD) criteria are met.
+
+## Core Responsibilities
+
+### 1. Session Management
+- Initialize Ralph sessions with appropriate configuration
+- Track iteration progress and metrics
+- Manage session state and recovery
+
+### 2. Definition of Done Validation
+- Evaluate DoD criteria at each iteration
+- Provide feedback on which criteria are passing/failing
+- Suggest corrective actions when criteria fail
+
+### 3. Circuit Breaker Monitoring
+- Monitor for stall conditions (no progress)
+- Detect error loops and repeated failures
+- Recommend stopping when appropriate
+
+### 4. Progress Assessment
+- Evaluate if meaningful progress is being made
+- Identify when tasks are stuck
+- Suggest alternative approaches when needed
+
+## Working Mode
+
+When orchestrating a Ralph session:
+
+1. **Initial Assessment**
+   - Understand the task requirements
+   - Identify success criteria
+   - Configure appropriate DoD checklist
+
+2. **Iteration Guidance**
+   - Provide clear, actionable prompts
+   - Focus on one objective at a time
+   - Build incrementally on previous progress
+
+3. **Quality Gates**
+   - Verify tests pass before proceeding
+   - Check code quality metrics
+   - Validate documentation updates
+
+4. **Completion Signals**
+   - Clearly indicate when DoD is met
+   - Use completion marker: `<promise>COMPLETE</promise>`
+   - Summarize what was accomplished
+
+## DoD Validator Types
+
+| Type | When to Use |
+|------|-------------|
+| `command` | Running tests, linting, building |
+| `output_contains` | Checking for completion markers |
+| `file_changed` | Verifying documentation updates |
+| `hook` | Integrating with existing quality gates |
+| `human` | Critical decisions requiring approval |
+
+## Best Practices
+
+### Task Decomposition
+Break complex tasks into smaller, verifiable steps:
+1. Write failing test first (RED)
+2. Implement minimum code to pass (GREEN)
+3. Refactor while keeping tests passing (REFACTOR)
+4. Update documentation
+5. Signal completion
+
+### Progress Indicators
+Include clear progress markers in your output:
+- `[PROGRESS]` - Making forward progress
+- `[BLOCKED]` - Encountered obstacle
+- `[TESTING]` - Running verification
+- `[COMPLETE]` - Task finished
+
+### Error Handling
+When encountering errors:
+1. Describe the error clearly
+2. Analyze root cause
+3. Propose solution
+4. Implement fix
+5. Verify resolution
+
+## Example Session Flow
+
+```
+Session: ralph-1704067200-a1b2
+Task: Implement user authentication
+
+Iteration 1:
+[PROGRESS] Analyzing existing code structure
+- Found existing User entity
+- Authentication service needs creation
+- Tests directory ready
+
+Iteration 2:
+[TESTING] Writing authentication tests
+- Created AuthServiceTest.php
+- 3 test cases: login, logout, validateToken
+- Tests currently FAILING (expected)
+
+Iteration 3:
+[PROGRESS] Implementing AuthService
+- Created AuthService.php
+- Implemented JWT token generation
+- Tests now PASSING
+
+Iteration 4:
+[PROGRESS] Updating documentation
+- Added authentication section to README
+- Documented API endpoints
+
+<promise>COMPLETE</promise>
+
+Summary:
+- AuthService created with JWT support
+- 3 tests passing
+- Documentation updated
+```
+
+## Integration Points
+
+- Works with `/common:ralph-run` command
+- Integrates with existing hooks (quality-gate.sh)
+- Compatible with `/project:sprint-dev` workflow
+- Uses `@tdd-coach` principles
+
+## When to Stop
+
+Signal completion and stop iterating when:
+1. All required DoD criteria pass
+2. Task objectives are fully met
+3. Tests verify functionality
+4. Documentation is updated
+
+Do NOT continue if:
+- Circuit breaker thresholds reached
+- Repeated failures indicate fundamental issue
+- Human intervention is required

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

@@ -0,0 +1,171 @@
+---
+description: Run Claude in continuous loop until task completion (Ralph Wiggum)
+argument-hint: <task-description> [--auto|--full]
+---
+
+# Ralph Run - Continuous AI Agent Loop
+
+Execute Claude in a continuous loop until the task is complete or the Definition of Done (DoD) criteria are met.
+
+## Arguments
+
+**$ARGUMENTS**
+
+- `<task-description>`: The task for Claude to complete
+- `--auto`: Maximum auto-detection, minimal questions
+- `--full`: Comprehensive mode with all DoD checks
+
+## Process
+
+### 1. Session Initialization
+
+1. **Check prerequisites**:
+   - Verify Claude is available
+   - Check for `ralph.yml` configuration
+   - Initialize session directory (`.ralph/`)
+
+2. **Load configuration**:
+   - Read `ralph.yml` or `.claude/ralph.yml`
+   - Set max iterations, timeouts, DoD criteria
+
+### 2. Main Loop
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  RALPH LOOP                                                  │
+│                                                              │
+│  while (iterations < max && !DoD_passed) {                   │
+│      1. Check circuit breaker                                │
+│      2. Invoke Claude with current prompt                    │
+│      3. Process output                                       │
+│      4. Validate Definition of Done                          │
+│      5. Create checkpoint (git commit)                       │
+│      6. If DoD not met, feed response as next prompt         │
+│  }                                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. Definition of Done Validation
+
+The DoD system validates completion through multiple criteria:
+
+| Validator | Description |
+|-----------|-------------|
+| `command` | Run shell command (tests, lint, build) |
+| `output_contains` | Check for pattern in Claude output |
+| `file_changed` | Verify files were modified |
+| `hook` | Run existing Claude hook |
+| `human` | Interactive human validation |
+
+Example DoD from `ralph.yml`:
+
+```yaml
+definition_of_done:
+  checklist:
+    - id: tests
+      name: "All tests pass"
+      type: command
+      command: "docker compose exec app npm test"
+      required: true
+
+    - id: completion
+      name: "Claude signals completion"
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+```
+
+### 4. Circuit Breaker
+
+Safety mechanism to prevent infinite loops:
+
+| Trigger | Threshold | Action |
+|---------|-----------|--------|
+| No file changes | 3 iterations | Stop |
+| Repeated errors | 5 iterations | Stop |
+| Output decline | 70% | Stop |
+| Max iterations | 25 (default) | Stop |
+
+### 5. Checkpointing
+
+Git checkpoints are created after each iteration for:
+- **Recovery**: Restore to previous state if needed
+- **History**: Track progress through iterations
+- **Review**: Inspect what changed at each step
+
+## Output
+
+```
+╔════════════════════════════════════════════════════════════╗
+║     🔁 Ralph Wiggum - Continuous AI Agent Loop              ║
+╚════════════════════════════════════════════════════════════╝
+
+✓ Session created: ralph-1704067200-a1b2
+
+ℹ Starting Ralph loop...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Iteration 1 of 25
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ℹ Invoking Claude...
+ℹ Checking DoD criteria...
+  ✓ [tests] All tests pass - PASS
+  ✓ [lint] No lint errors - PASS
+  ✓ [completion] Claude signals completion - PASS
+
+  All required criteria passed!
+
+✓ DoD PASSED
+
+╔════════════════════════════════════════════════════════════╗
+║     📊 Session Summary                                      ║
+╚════════════════════════════════════════════════════════════╝
+
+  Session ID:        ralph-1704067200-a1b2
+  Total iterations:  3
+  Duration:          45s
+  DoD status:        PASSED
+  Exit reason:       dod_complete
+```
+
+## Configuration
+
+Create `ralph.yml` in your project root:
+
+```yaml
+version: "1.0"
+
+session:
+  max_iterations: 25
+  timeout: 600000
+
+circuit_breaker:
+  enabled: true
+  no_file_changes_threshold: 3
+
+definition_of_done:
+  checklist:
+    - id: tests
+      type: command
+      command: "npm test"
+      required: true
+    - id: completion
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+```
+
+## Best Practices
+
+1. **Clear task description**: Provide specific, actionable tasks
+2. **Configure DoD**: Define completion criteria in `ralph.yml`
+3. **Use TDD**: Write tests first, let Ralph implement
+4. **Monitor progress**: Watch iteration output for issues
+5. **Set reasonable limits**: Adjust max_iterations for task complexity
+
+## Related
+
+- `@ralph-conductor` - Agent for Ralph orchestration
+- `/common:fix-bug-tdd` - TDD-based bug fixing
+- `/project:sprint-dev` - Sprint development with TDD

package/Dev/i18n/en/Common/commands/setup-project-context.md

@@ -0,0 +1,286 @@
+---
+name: setup-project-context
+description: Analyze codebase and configure project context interactively
+arguments:
+  - name: mode
+    description: Detection mode (--auto minimal questions, --full comprehensive)
+    required: false
+---
+
+# Setup Project Context
+
+Configure `.claude/rules/00-project-context.md` by analyzing the codebase and asking targeted questions.
+
+## Execution
+
+### Phase 1: Automatic Detection
+
+Analyze the following files and directories:
+
+**Configuration Files:**
+- `package.json` → Node.js project name, dependencies, scripts
+- `composer.json` → PHP project name, dependencies, framework
+- `pubspec.yaml` → Flutter/Dart project name, dependencies
+- `requirements.txt` / `pyproject.toml` → Python dependencies
+- `Cargo.toml` → Rust project
+- `go.mod` → Go module
+
+**Environment & Config:**
+- `.env`, `.env.example` → Database, services
+- `config/` → Framework configuration
+- `docker-compose.yml` → Services (DB, Redis, etc.)
+
+**Structure:**
+- `src/`, `lib/`, `app/` → Source code location
+- `tests/`, `spec/` → Testing framework
+- `docs/`, `specifications/` → Documentation
+- `.github/`, `.gitlab-ci.yml` → CI/CD
+
+**Domain (if applicable):**
+- `src/Entity/`, `src/Domain/` → Business entities (PHP/Symfony)
+- `lib/models/`, `lib/domain/` → Models (Flutter/Dart)
+- `models/`, `schemas/` → Data models
+- `migrations/` → Database schema
+
+Display analysis results:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                 PROJECT ANALYSIS RESULTS                      ║
+╚══════════════════════════════════════════════════════════════╝
+
+✅ Detected Information:
+┌─────────────────┬────────────────────────────────┐
+│ Element         │ Value                          │
+├─────────────────┼────────────────────────────────┤
+│ Project Name    │ {detected_name}                │
+│ Language        │ {detected_language}            │
+│ Framework       │ {detected_framework}           │
+│ Database        │ {detected_database}            │
+│ Testing         │ {detected_testing}             │
+│ CI/CD           │ {detected_cicd}                │
+└─────────────────┴────────────────────────────────┘
+
+📁 Project Structure:
+{detected_structure}
+
+📄 Documentation Found:
+{detected_docs}
+
+❌ Not Detected (will ask):
+- {missing_items}
+```
+
+### Phase 2: Interactive Questions
+
+Ask only for information NOT detected in Phase 1.
+Skip questions if `--auto` mode is used and a reasonable default exists.
+
+**Essential Questions:**
+
+1. **Application Type** (if not detected):
+   ```
+   What type of application is this?
+   [ ] REST API      [ ] Web Application    [ ] Mobile App
+   [ ] CLI Tool      [ ] Library/Package    [ ] Monorepo
+   ```
+
+2. **Business Domain**:
+   ```
+   What is the business domain?
+   [ ] E-commerce    [ ] SaaS Platform      [ ] FinTech
+   [ ] HealthTech    [ ] EdTech             [ ] Social/Community
+   [ ] Media/Content [ ] IoT                [ ] Other: _____
+   ```
+
+3. **Target Users** (2-3 personas):
+   ```
+   Describe your main users:
+
+   Primary User:
+   > Role: _____
+   > Main goal: _____
+
+   Secondary User (optional):
+   > Role: _____
+   > Main goal: _____
+   ```
+
+4. **Compliance Requirements**:
+   ```
+   Which compliance requirements apply?
+   [ ] GDPR (EU data protection)
+   [ ] HIPAA (US healthcare)
+   [ ] PCI-DSS (Payment card)
+   [ ] SOC2 (Security)
+   [ ] None / Not applicable
+   ```
+
+**Extended Questions** (only with `--full` mode):
+
+5. **Business Goals**:
+   ```
+   Short-term goals (3-6 months):
+   > _____
+
+   Medium-term goals (6-12 months):
+   > _____
+   ```
+
+6. **Known Issues/Technical Debt**:
+   ```
+   Any known issues or technical debt to document?
+   > _____
+   ```
+
+7. **Glossary Terms**:
+   ```
+   Key business terms to define (comma-separated):
+   > _____
+   ```
+
+### Phase 3: Generate Context File
+
+Create `.claude/rules/00-project-context.md`:
+
+```markdown
+# Project Context - {PROJECT_NAME}
+
+> Auto-generated by `/common:setup-project-context` on {DATE}
+> Review and customize as needed.
+
+## Overview
+
+**{PROJECT_NAME}** is a {TYPE} application for the {DOMAIN} domain.
+
+{DESCRIPTION_FROM_README_OR_USER}
+
+## Technical Stack
+
+| Component    | Technology           |
+|--------------|----------------------|
+| Language     | {LANGUAGE}           |
+| Framework    | {FRAMEWORK}          |
+| Database     | {DATABASE}           |
+| Cache        | {CACHE_IF_DETECTED}  |
+| Testing      | {TESTING_FRAMEWORKS} |
+| CI/CD        | {CICD_PLATFORM}      |
+
+## Project Structure
+
+```
+{DETECTED_STRUCTURE}
+```
+
+## Business Domain
+
+### Core Concepts
+
+{ENTITIES_IF_DETECTED}
+
+### Bounded Contexts
+
+<!-- Add if using DDD -->
+- Context 1: ...
+- Context 2: ...
+
+## Users & Personas
+
+### {PRIMARY_USER_ROLE}
+- **Goal:** {PRIMARY_USER_GOAL}
+- **Pain points:** To be documented
+- **Key workflows:** To be documented
+
+### {SECONDARY_USER_ROLE}
+- **Goal:** {SECONDARY_USER_GOAL}
+- **Pain points:** To be documented
+- **Key workflows:** To be documented
+
+## Constraints
+
+### Compliance
+{COMPLIANCE_REQUIREMENTS}
+
+### Performance Targets
+- Page load time: < 3s
+- API response time: < 200ms
+- Availability: 99.9%
+
+### Security Requirements
+- OWASP Top 10 compliance
+- Input validation on all endpoints
+- Authentication required for protected resources
+
+## Goals
+
+### Short-term
+{SHORT_TERM_GOALS_OR_PLACEHOLDER}
+
+### Medium-term
+{MEDIUM_TERM_GOALS_OR_PLACEHOLDER}
+
+## Known Issues / Technical Debt
+
+{ISSUES_OR_PLACEHOLDER}
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+{GLOSSARY_TERMS_OR_EXAMPLES}
+```
+
+### Phase 4: Validation & Next Steps
+
+Display summary and recommendations:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║              PROJECT CONTEXT GENERATED                        ║
+╚══════════════════════════════════════════════════════════════╝
+
+✅ File created: .claude/rules/00-project-context.md
+
+Summary:
+┌─────────────────┬────────────────────────────────┐
+│ Project         │ {PROJECT_NAME}                 │
+│ Type            │ {TYPE}                         │
+│ Stack           │ {FRAMEWORK} + {DATABASE}       │
+│ Domain          │ {DOMAIN}                       │
+│ Compliance      │ {COMPLIANCE}                   │
+│ Personas        │ {COUNT} defined                │
+└─────────────────┴────────────────────────────────┘
+
+📋 Recommended Next Steps:
+
+1. Review generated file and complete placeholder sections
+2. Add detailed bounded contexts if using DDD
+3. Document key business workflows
+4. Consider running specialized agents:
+   - @database-architect → Document database schema
+   - @api-designer → Document API endpoints
+   - @security-reviewer → Review security constraints
+
+Would you like me to open the file for review?
+```
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| (default) | Detect + essential questions (type, domain, users, compliance) |
+| `--auto` | Maximum auto-detection, skip questions with reasonable defaults |
+| `--full` | All questions including goals, issues, and glossary |
+
+## Examples
+
+```bash
+# Standard mode - balanced detection and questions
+/common:setup-project-context
+
+# Auto mode - minimal interaction
+/common:setup-project-context --auto
+
+# Full mode - comprehensive questionnaire
+/common:setup-project-context --full
+```