ai-eng-system 0.0.15 → 0.1.0

package/README.md

@@ -6,7 +6,7 @@ Advanced development tools with context engineering, research orchestration, and
 
 ### Spec-Driven Development (Recommended)
 
-This toolkit follows the **spec-driven development methodology** from GitHub's official blog post: [Spec-driven development with AI: Get started with a new open source toolkit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/).
+This toolkit follows **spec-driven development methodology** from GitHub's official blog post: [Spec-driven development with AI: Get started with a new open source toolkit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/).
 
 **The 5-Phase Workflow** (always in this order):
 
@@ -17,16 +17,18 @@ flowchart LR
     E -.->|Repeat| D
 ```
 
-| Phase | Command | Output |
-|-------|---------|--------|
-| 1. Research | `/ai-eng/research` | Context and findings |
-| 2. Specify | `/ai-eng/specify` | Feature specification |
-| 3. Plan | `/ai-eng/plan` | Implementation plan |
-| 4. Work | `/ai-eng/work` | Quality-gated code |
-| 5. Review | `/ai-eng/review` | Multi-agent approval |
+| Phase | Command | Output | Ralph Wiggum 🔄 |
+|-------|---------|--------|-----------------|
+| 1. Research | `/ai-eng/research` | Context and findings | `--ralph` for iterative deepening |
+| 2. Specify | `/ai-eng/specify` | Feature specification | `--ralph` for requirement refinement |
+| 3. Plan | `/ai-eng/plan` | Implementation plan | `--ralph` for task completeness |
+| 4. Work | `/ai-eng/work` | Quality-gated code | `--ralph` for TDD cycles |
+| 5. Review | `/ai-eng/review` | Multi-agent approval | `--ralph` for thorough analysis |
 
 This approach ensures specifications are your "source of truth" for what gets built, reducing guesswork and enabling more reliable AI-assisted development.
 
+🔄 **New: Ralph Wiggum Iteration** - Add `--ralph` flag to any phase command for persistent refinement until quality standards are met. See [Ralph Wiggum Integration Guide](./docs/ralph-wiggum-integration-complete.md).
+
 See [docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md) for complete workflow guide with examples.
 
 ### Claude Code (Recommended)
@@ -51,16 +53,18 @@ See [docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md) for complete
 
 **Core workflow for systematic development** (always research → specify → plan → work → review):
 
-| Phase | Command | Purpose |
-|-------|---------|---------|
-| 1. Research | `/ai-eng/research` | Multi-phase research with codebase and external context |
-| 2. Specify | `/ai-eng/specify` | Create feature specifications with TCRO framework |
-| 3. Plan | `/ai-eng/plan` | Create detailed implementation plans from specs |
-| 4. Work | `/ai-eng/work` | Execute plans with quality gates and validation |
-| 5. Review | `/ai-eng/review` | Multi-perspective code review (28 agents) |
+| Phase | Command | Purpose | Ralph Wiggum 🔄 |
+|-------|---------|---------|-----------------|
+| 1. Research | `/ai-eng/research` | Multi-phase research with codebase and external context | Iterative deepening, gap analysis |
+| 2. Specify | `/ai-eng/specify` | Create feature specifications with TCRO framework | Requirement refinement, completeness |
+| 3. Plan | `/ai-eng/plan` | Create detailed implementation plans from specs | Task atomicity, dependency mapping |
+| 4. Work | `/ai-eng/work` | Execute plans with quality gates and validation | TDD cycles, implementation refinement |
+| 5. Review | `/ai-eng/review` | Multi-perspective code review (28 agents) | Escalating focus, thorough analysis |
 
 > **Methodology**: Based on [GitHub's spec-driven development approach](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
 
+> **🔄 Ralph Wiggum**: Add `--ralph` flag to any phase command for persistent iteration. Perfect for complex tasks requiring multiple refinement cycles. [Learn more →](./docs/ralph-wiggum-integration-complete.md)
+
 ### Additional Commands (13 total)
 - `/ai-eng/optimize` - Prompt enhancement (+45% quality)
 - `/ai-eng/deploy` - Pre-deployment checklists
@@ -86,12 +90,15 @@ See [docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md) for complete
 - **Content & SEO**: `seo-specialist`, `prompt-optimizer`
 - **Plugin Development**: `agent-creator`, `command-creator`, `skill-creator`, `tool-creator`, `plugin-validator`
 
-### Skills (7 files)
+### Skills (8 files)
 - `devops` - Coolify deployment, Git worktree workflows
 - `prompting` - Research-backed incentive prompting techniques
 - `research` - Comprehensive multi-phase research orchestration
 - `plugin-dev` - Plugin development knowledge base and references
 - `text-cleanup` - Pattern-based text cleanup (slop, comments)
+- **`workflow/ralph-wiggum`** - Persistent iteration patterns for quality refinement (NEW!)
+
+> **🔄 Ralph Wiggum Philosophy**: "Iteration > Perfection, Failures Are Data, Persistence Wins" - Now available across all phase commands with `--ralph` flag
 
 ## 🔄 Subagent Orchestrator Configuration
 
@@ -168,10 +175,39 @@ bun test             # Run test suite
 - Tests: ✅ Passing (21/21)
 
 ## 📚 Documentation
+
+### Online Documentation
+**Deploy with Coolify** (recommended):
+- 📖 [Coolify Deployment Guide](docs-site/COOLIFY-DEPLOYMENT.md) - Complete deployment instructions
+- 🚀 Deploy to Coolify in 5 minutes
+
+**Built Site**: `docs-site/` directory
+
+### Developer Documentation
 - [Installation Guide](INSTALLATION.md) - Detailed setup instructions
 - [Agent Coordination](AGENTS.md) - Agent usage patterns and coordination
 - [Plugin Documentation](PLUGIN.md) - Technical plugin details
 - [Research Guide](docs/research-command-guide.md) - Research orchestration usage
+- [Ralph Wiggum Integration](docs/ralph-wiggum-integration-complete.md) - Iterative refinement patterns (NEW!)
+
+### Documentation Site
+
+The documentation site is built with **Astro + Starlight** and ready for deployment:
+
+```bash
+# Local development
+cd docs-site
+bun install
+bun run dev  # http://localhost:4321
+
+# Build for production
+bun run build
+
+# Deploy to Coolify
+# Repository path: docs-site/
+# Build command: bun install && bun run build
+# Output directory: dist
+```
 
 ---
 ## 💻 Usage Example
@@ -202,12 +238,21 @@ npm install ai-eng-system
 ### Using Commands
 
 ```bash
+# Basic workflow
 /ai-eng/plan              # Create implementation plan
 /ai-eng/review             # Multi-agent code review
 /ai-eng/work               # Execute implementation plan
 /ai-eng/seo                # SEO audit
 /ai-eng/create-agent       # Generate new agent
-# ... and 11 more
+
+# Ralph Wiggum iteration (NEW!)
+/ai-eng/work "feature" --ralph                    # TDD cycles until complete
+/ai-eng/research "topic" --ralph --ralph-max-iterations 15  # Deep research
+/ai-eng/specify "feature" --ralph --ralph-quality-gate="rg '\[NEEDS CLARIFICATION\]'"
+/ai-eng/plan --from-spec=specs/feature.md --ralph  # Enhanced planning
+/ai-eng/review src/ --ralph --ralph-focus=security # Thorough review
+
+# ... and 11 more commands
 ```
 
 ### Using Agents

package/dist/.claude-plugin/commands/plan.md

@@ -40,6 +40,12 @@ Create a detailed implementation plan for: $ARGUMENTS
 
 # From research
 /ai-eng/plan --from-research=docs/research/2026-01-01-auth-patterns.md
+
+# Ralph Wiggum iteration for complex plans
+/ai-eng/plan "microservices migration" --ralph --ralph-show-progress
+
+# Ralph Wiggum with custom iterations and quality gate
+/ai-eng/plan --from-spec=specs/auth/spec.md --ralph --ralph-max-iterations 8 --ralph-quality-gate="rg 'Depends On:' specs/*/plan.md"
 ```
 
 ## Options
@@ -54,6 +60,14 @@ Create a detailed implementation plan for: $ARGUMENTS
 | `--from-spec <file>` | Create plan from specification file |
 | `--from-research <file>` | Create plan from research document |
 | `-v, --verbose` | Enable verbose output |
+| `--ralph` | Enable Ralph Wiggum iteration mode for persistent plan refinement |
+| `--ralph-max-iterations <n>` | Maximum iterations for Ralph Wiggum mode [default: 10] |
+| `--ralph-completion-promise <text>` | Custom completion promise text [default: "Plan is comprehensive and ready for execution"] |
+| `--ralph-quality-gate <command>` | Command to run after each iteration for quality validation |
+| `--ralph-stop-on-gate-fail` | Stop iterations when quality gate fails [default: continue] |
+| `--ralph-show-progress` | Show detailed iteration progress |
+| `--ralph-log-history <file>` | Log iteration history to JSON file |
+| `--ralph-verbose` | Enable verbose Ralph Wiggum iteration output |
 
 ## Phase 0: Prompt Refinement (CRITICAL - Do First)
 
@@ -77,6 +91,21 @@ If no spec is found:
 - If yes, gather requirements through clarifying questions
 - If no, exit and prompt user to run `/ai-eng/specify`
 
+### Ralph Wiggum Integration
+
+If `--ralph` flag is used, also invoke the `ralph-wiggum` skill:
+
+**Load Ralph Wiggum skill from:** `skills/workflow/ralph-wiggum/SKILL.md`
+
+**Ralph Wiggum Planning Cycle:**
+1. **Initial Plan** - Create comprehensive implementation plan
+2. **Gap Analysis** - Identify missing tasks, incomplete dependencies
+3. **Iterative Enhancement** - Add missing details, strengthen task definitions
+4. **Quality Validation** - Run quality gate if specified
+5. **Completion Check** - Continue until completion promise met or max iterations reached
+
+**Default Planning Completion Promise:** "Plan is comprehensive and ready for execution"
+
 ### Phase 2: Discovery (Research Mode)
 
 #### Subagent Communication Protocol (Minimal)
@@ -503,4 +532,86 @@ For example:
 - `bun run scripts/run-command.ts plan "implement auth" --from-spec=specs/auth/spec.md --output=plans/auth.yaml`
 - `bun run scripts/run-command.ts plan --from-research=docs/research/auth.md --scope=implementation`
 
+## Ralph Wiggum Iteration Mode
+
+When `--ralph` flag is enabled, the planning process follows a persistent refinement cycle:
+
+### Ralph Wiggum Planning Cycle
+
+**Iteration Process:**
+1. **Execute Planning Phases 1-7** - Run complete planning process
+2. **Gap Analysis** - Review plan for:
+   - Missing tasks or incomplete task definitions
+   - Unclear dependencies or integration points
+   - Insufficient testing coverage
+   - Incomplete risk assessment
+3. **Targeted Enhancement** - Focus next iteration on identified gaps:
+   - Add missing tasks or subtasks
+   - Strengthen dependency mapping
+   - Enhance testing strategy
+   - Improve risk mitigation strategies
+4. **Quality Gate** - Run quality gate command if specified
+5. **Progress Update** - Log iteration improvements and continue
+6. **Completion Check** - Stop when:
+   - Plan comprehensiveness promise is met
+   - Quality gates consistently pass
+   - Maximum iterations reached
+
+### Ralph Wiggum Quality Gates
+
+**Planning Quality Gate Examples:**
+```bash
+# Check task completeness
+rg "Acceptance Criteria:" specs/*/plan.md | wc -l
+
+# Validate dependencies mapping
+rg "Depends On:" specs/*/plan.md
+
+# Check risk assessment completeness
+rg "Impact.*Likelihood.*Mitigation" specs/*/plan.md
+```
+
+### Progress Tracking
+
+**Iteration Metrics:**
+- Iteration number and completion status
+- Tasks added or refined
+- Dependencies mapped or clarified
+- Risk mitigations added
+- Quality gate pass/fail status
+- Plan completeness score
+
+**Example Progress Output:**
+```
+🔄 Ralph Wiggum Planning Iteration 3/10
+📝 Tasks: 12 total (+2 this iteration)
+🔗 Dependencies: 8 mapped (+1 clarified this iteration)
+🛡️ Risk mitigations: 5 complete (+2 this iteration)
+🧪 Test coverage: 85% (+5% this iteration)
+✅ Quality gate: PASSED
+🎯 Plan completeness: 90% (improving)
+```
+
+### Ralph Wiggum Implementation Notes
+
+**Planning-Specific Considerations:**
+
+- **Task Atomicity**: Each iteration should ensure tasks are truly atomic
+- **Dependency Clarity**: Focus on making dependencies explicit and minimal
+- **Testing Integration**: Ensure comprehensive test coverage for all tasks
+- **Risk Coverage**: Each iteration should strengthen risk mitigation strategies
+
+**Default Settings:**
+- **Max Iterations**: 10 (sufficient for comprehensive planning refinement)
+- **Completion Promise**: "Plan is comprehensive and ready for execution"
+- **Quality Gate**: Check task completeness and dependency mapping
+- **Progress Tracking**: Always enabled in Ralph mode
+
+**Best Practices:**
+- Focus on making tasks more atomic each iteration
+- Strengthen dependency mapping to enable parallel execution
+- Enhance risk assessment with specific mitigations
+- Validate spec coverage (if spec exists) each iteration
+- Ensure all supporting artifacts are generated
+
 $ARGUMENTS

package/dist/.claude-plugin/commands/research.md

@@ -36,6 +36,12 @@ Conduct comprehensive research for: $ARGUMENTS
 
 # Feed results into planning
 /ai-eng/research "caching strategies" --feed-into plan
+
+# Ralph Wiggum iteration for complex topics
+/ai-eng/research "microservices architecture patterns" --ralph --ralph-show-progress
+
+# Ralph Wiggum with custom iterations
+/ai-eng/research "database optimization techniques" --ralph --ralph-max-iterations 15 --ralph-verbose
 ```
 
 ## Options
@@ -50,6 +56,14 @@ Conduct comprehensive research for: $ARGUMENTS
 | `--no-cache` | Disable research caching |
 | `--feed-into <command>` | After research, invoke specified command (specify\|plan) |
 | `-v, --verbose` | Enable verbose output |
+| `--ralph` | Enable Ralph Wiggum iteration mode for persistent research refinement |
+| `--ralph-max-iterations <n>` | Maximum iterations for Ralph Wiggum mode [default: 10] |
+| `--ralph-completion-promise <text>` | Custom completion promise text [default: "Research is complete and comprehensive"] |
+| `--ralph-quality-gate <command>` | Command to run after each iteration for quality validation |
+| `--ralph-stop-on-gate-fail` | Stop iterations when quality gate fails [default: continue] |
+| `--ralph-show-progress` | Show detailed iteration progress |
+| `--ralph-log-history <file>` | Log iteration history to JSON file |
+| `--ralph-verbose` | Enable verbose Ralph Wiggum iteration output |
 
 ## Phase 0: Prompt Refinement (CRITICAL - Do First)
 

package/dist/.claude-plugin/commands/review.md

@@ -27,6 +27,12 @@ Review code changes: $ARGUMENTS
 /ai-eng/review src/
 /ai-eng/review src/ --type=security --severity=high
 /ai-eng/review . --focus=performance --verbose
+
+# Ralph Wiggum iteration for thorough reviews
+/ai-eng/review src/ --ralph --ralph-show-progress
+
+# Ralph Wiggum with security focus and custom iterations
+/ai-eng/review . --focus=security --ralph --ralph-max-iterations 15 --ralph-verbose
 ```
 
 ## Options
@@ -39,6 +45,14 @@ Review code changes: $ARGUMENTS
 | `-f, --focus <focus>` | Focused review (security\|performance\|frontend\|general) |
 | `-o, --output <file>` | Output report file [default: code-review-report.json] |
 | `-v, --verbose` | Enable verbose output |
+| `--ralph` | Enable Ralph Wiggum iteration mode for persistent review refinement |
+| `--ralph-max-iterations <n>` | Maximum iterations for Ralph Wiggum mode [default: 10] |
+| `--ralph-completion-promise <text>` | Custom completion promise text [default: "Review is comprehensive and all findings addressed"] |
+| `--ralph-quality-gate <command>` | Command to run after each iteration for quality validation |
+| `--ralph-stop-on-gate-fail` | Stop iterations when quality gate fails [default: continue] |
+| `--ralph-show-progress` | Show detailed iteration progress |
+| `--ralph-log-history <file>` | Log iteration history to JSON file |
+| `--ralph-verbose` | Enable verbose Ralph Wiggum iteration output |
 
 ## Phase 0: Prompt Refinement (CRITICAL - Do First)
 
@@ -49,6 +63,21 @@ Review code changes: $ARGUMENTS
 2. Use phase: `review`
 3. Follow the TCRO framework: Task, Context, Requirements, Output
 
+### Ralph Wiggum Integration
+
+If `--ralph` flag is used, also invoke the `ralph-wiggum` skill:
+
+**Load Ralph Wiggum skill from:** `skills/workflow/ralph-wiggum/SKILL.md`
+
+**Ralph Wiggum Review Cycle:**
+1. **Initial Review** - Run comprehensive review with all perspectives
+2. **Gap Analysis** - Identify missed issues, insufficient coverage
+3. **Iterative Deepening** - Focus review on problematic areas or different perspectives
+4. **Quality Validation** - Run quality gate if specified
+5. **Completion Check** - Continue until completion promise met or max iterations reached
+
+**Default Review Completion Promise:** "Review is comprehensive and all findings addressed"
+
 ## Perspectives
 
 #### Subagent Communication Protocol (Minimal)
@@ -110,6 +139,88 @@ For example:
 - `bun run scripts/run-command.ts review "src/" --type=security --severity=high --output=security-review.json`
 - `bun run scripts/run-command.ts review "." --focus=performance --verbose`
 
+## Ralph Wiggum Iteration Mode
+
+When `--ralph` flag is enabled, the review process follows a persistent refinement cycle:
+
+### Ralph Wiggum Review Cycle
+
+**Iteration Process:**
+1. **Execute Standard Review** - Run complete review with all perspectives
+2. **Gap Analysis** - Review findings for:
+   - Critical issues that may have been missed
+   - Insufficient coverage of complex areas
+   - Areas needing deeper security or performance analysis
+   - Findings that lack clear recommendations
+3. **Targeted Deepening** - Focus next iteration on identified gaps:
+   - Add new perspectives (e.g., focus on accessibility, compliance)
+   - Deep-dive into complex components
+   - Re-review with different expert lenses
+   - Strengthen recommendations and remediation steps
+4. **Quality Gate** - Run quality gate command if specified
+5. **Progress Update** - Log iteration improvements and continue
+6. **Completion Check** - Stop when:
+   - Review comprehensiveness promise is met
+   - Quality gates consistently pass
+   - Maximum iterations reached
+
+### Ralph Wiggum Quality Gates
+
+**Review Quality Gate Examples:**
+```bash
+# Check for critical findings
+rg '"severity": "critical"' code-review-report.json
+
+# Validate recommendations completeness
+rg '"recommendation"' code-review-report.json | wc -l
+
+# Check file coverage
+rg '"location"' code-review-report.json | sort | uniq | wc -l
+```
+
+### Progress Tracking
+
+**Iteration Metrics:**
+- Iteration number and completion status
+- New findings discovered per iteration
+- Severity distribution (critical/major/minor)
+- Perspectives covered (security, performance, etc.)
+- Quality gate pass/fail status
+- Review comprehensiveness score
+
+**Example Progress Output:**
+```
+🔄 Ralph Wiggum Review Iteration 4/10
+🔍 Findings: 23 total (+4 this iteration)
+🚨 Critical issues: 2 (new this iteration)
+⚠️ Major issues: 8 (+1 this iteration)
+📁 Files reviewed: 15 (+2 deep-dived this iteration)
+✅ Quality gate: PASSED
+🎯 Review coverage: 95% (improving)
+```
+
+### Ralph Wiggum Implementation Notes
+
+**Review-Specific Considerations:**
+
+- **Escalating Focus**: Each iteration should examine different aspects or deepen analysis
+- **Severity Validation**: Critical findings should trigger immediate attention
+- **Recommendation Quality**: Each finding should have actionable, specific recommendations
+- **Cross-Perspective Coverage**: Ensure multiple expert lenses are applied
+
+**Default Settings:**
+- **Max Iterations**: 10 (sufficient for thorough review refinement)
+- **Completion Promise**: "Review is comprehensive and all findings addressed"
+- **Quality Gate**: Check for critical findings and recommendations completeness
+- **Progress Tracking**: Always enabled in Ralph mode
+
+**Best Practices:**
+- Start with broad review, then focus on high-risk areas
+- Add new perspectives each iteration (security → performance → accessibility)
+- Deep-dive into complex components that may hide issues
+- Strengthen recommendations with specific remediation steps
+- Validate that all critical findings have clear, actionable fixes
+
 ## Perspectives
 
 Review code from multiple expert perspectives:

package/dist/.claude-plugin/commands/specify.md

@@ -31,6 +31,12 @@ Create a comprehensive feature specification: $ARGUMENTS
 /ai-eng/specify "user authentication system"
 /ai-eng/specify "payment integration" --from-research=docs/research/payment.md
 /ai-eng/specify "api design" --template=api
+
+# Ralph Wiggum iteration for complex features
+/ai-eng/specify "multi-tenant architecture" --ralph --ralph-show-progress
+
+# Ralph Wiggum with custom quality gate
+/ai-eng/specify "real-time collaboration" --ralph --ralph-quality-gate="rg '\[NEEDS CLARIFICATION\]' specs/*/spec.md" --ralph-stop-on-gate-fail
 ```
 
 ## Options
@@ -42,6 +48,14 @@ Create a comprehensive feature specification: $ARGUMENTS
 | `--output <path>` | Custom output path [default: `specs/[feature]/spec.md`] |
 | `--no-confirmation` | Skip confirmation prompts |
 | `--verbose` | Show detailed process |
+| `--ralph` | Enable Ralph Wiggum iteration mode for persistent specification refinement |
+| `--ralph-max-iterations <n>` | Maximum iterations for Ralph Wiggum mode [default: 10] |
+| `--ralph-completion-promise <text>` | Custom completion promise text [default: "Specification is complete and ready for implementation"] |
+| `--ralph-quality-gate <command>` | Command to run after each iteration for quality validation |
+| `--ralph-stop-on-gate-fail` | Stop iterations when quality gate fails [default: continue] |
+| `--ralph-show-progress` | Show detailed iteration progress |
+| `--ralph-log-history <file>` | Log iteration history to JSON file |
+| `--ralph-verbose` | Enable verbose Ralph Wiggum iteration output |
 
 ## Phase 0: Prompt Refinement (CRITICAL - Do First)
 

package/dist/.claude-plugin/commands/work.md

@@ -31,6 +31,12 @@ Execute a plan or task: $ARGUMENTS
 /ai-eng/work "specs/auth/plan.yaml"
 /ai-eng/work --from-plan=plans/auth.yaml --continue
 /ai-eng/work "FEAT-001" --dry-run
+
+# Ralph Wiggum iteration for complex implementation
+/ai-eng/work "implement feature" --ralph --ralph-show-progress
+
+# Ralph Wiggum with custom quality gates
+/ai-eng/work "auth system" --ralph --ralph-max-iterations 20 --ralph-quality-gate="npm test && npm run security-scan"
 ```
 
 ## Options
@@ -42,6 +48,14 @@ Execute a plan or task: $ARGUMENTS
 | `--validate-only` | Run validation without implementation |
 | `--dry-run` | Show what would be done without executing |
 | `-v, --verbose` | Enable verbose output |
+| `--ralph` | Enable Ralph Wiggum iteration mode for TDD-driven implementation |
+| `--ralph-max-iterations <n>` | Maximum iterations for Ralph Wiggum mode [default: 10] |
+| `--ralph-completion-promise <text>` | Custom completion promise text [default: "Implementation meets all acceptance criteria and passes quality gates"] |
+| `--ralph-quality-gate <command>` | Command to run after each iteration for quality validation |
+| `--ralph-stop-on-gate-fail` | Stop iterations when quality gate fails [default: continue] |
+| `--ralph-show-progress` | Show detailed iteration progress |
+| `--ralph-log-history <file>` | Log iteration history to JSON file |
+| `--ralph-verbose` | Enable verbose Ralph Wiggum iteration output |
 
 ## Phase 0: Prompt Refinement (CRITICAL - Do First)
 
@@ -52,6 +66,21 @@ Execute a plan or task: $ARGUMENTS
 2. Use phase: `work`
 3. Follow the TCRO framework: Task, Context, Requirements, Output
 
+### Ralph Wiggum Integration
+
+If `--ralph` flag is used, also invoke the `ralph-wiggum` skill:
+
+**Load Ralph Wiggum skill from:** `skills/workflow/ralph-wiggum/SKILL.md`
+
+**Ralph Wiggum Work Cycle:**
+1. **Initial Implementation** - Apply TDD cycle to first task
+2. **Gap Analysis** - Identify failing tests, incomplete features
+3. **Iterative Development** - Focus on fixing failures and completing implementation
+4. **Quality Validation** - Run quality gate after each iteration
+5. **Completion Check** - Continue until completion promise met or max iterations reached
+
+**Default Work Completion Promise:** "Implementation meets all acceptance criteria and passes quality gates"
+
 ## Phase 1: Setup & Planning
 
 ### 1.1 Load Plan and Spec
@@ -578,4 +607,88 @@ For example:
 - Validates against `/ai-eng/specify` output (spec.md)
 - Feeds into `/ai-eng/review` for code review
 
+## Ralph Wiggum Iteration Mode
+
+When `--ralph` flag is enabled, the work execution follows a TDD-driven cycle:
+
+### Ralph Wiggum Work Cycle
+
+**Iteration Process:**
+1. **Execute Work Phase 1-6** - Run complete work process
+2. **Gap Analysis** - Review implementation for:
+   - Failing tests or incomplete test coverage
+   - Missing features or acceptance criteria
+   - Quality gate failures
+   - Insufficient implementation details
+3. **Targeted Development** - Focus next iteration on identified gaps:
+   - Fix failing tests
+   - Complete missing features
+   - Address quality gate failures
+   - Strengthen implementation
+4. **Quality Gate** - Run quality gate command if specified
+5. **Progress Update** - Log iteration improvements and continue
+6. **Completion Check** - Stop when:
+   - Implementation meets acceptance criteria
+   - Quality gates consistently pass
+   - Maximum iterations reached
+
+### Ralph Wiggum Quality Gates
+
+**Work Quality Gate Examples:**
+```bash
+# Check test execution
+npm test
+
+# Check linting
+npm run lint
+
+# Run security scans
+npm run security-scan
+
+# Check type checking
+bun tsc --noEmit
+```
+
+### Progress Tracking
+
+**Iteration Metrics:**
+- Iteration number and completion status
+- Tasks completed per iteration
+- Tests passing/total
+- Quality gate pass/fail status
+- Implementation progress
+- Confidence score
+
+**Example Progress Output:**
+```
+🔄 Ralph Wiggum Work Iteration 3/10
+✅ Tasks completed: 5 total (+2 this iteration)
+🧪 Tests passing: 18/20 (+3 this iteration)
+✅ Quality gate: PASSED (npm test && npm run lint)
+🎯 Implementation: 75% complete (+10% this iteration)
+📊 Confidence: 0.8 (improving)
+```
+
+### Ralph Wiggum Implementation Notes
+
+**Work-Specific Considerations:**
+
+- **TDD Cycle**: Each iteration follows Write Test → Implement → Test → Fix pattern
+- **Test Coverage**: Ensure all acceptance criteria have corresponding tests
+- **Quality Standards**: Run full quality suite after each iteration
+- **Progressive Development**: Each iteration should make measurable progress
+
+**Default Settings:**
+- **Max Iterations**: 10 (sufficient for most implementations)
+- **Completion Promise**: "Implementation meets all acceptance criteria and passes quality gates"
+- **Quality Gate**: Test execution + linting (recommended)
+- **Progress Tracking**: Always enabled in Ralph mode
+
+**Best Practices:**
+- Write failing tests before implementing features
+- Fix the immediate failing test, not hypothetical issues
+- Run quality gates after each iteration, not just at end
+- Track test coverage and improve it each iteration
+- Document any workarounds or temporary solutions for later cleanup
+
 $ARGUMENTS

package/dist/.claude-plugin/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "description": "Initialize ai-eng-system on session start",
+        "config": {},
+        "hooks": [
+          {
+            "type": "notification",
+            "config": {},
+            "message": "🔧 Ferg Engineering System loaded. Commands: /ai-eng/plan, /ai-eng/review, /ai-eng/seo, /ai-eng/work, /ai-eng/compound, /ai-eng/deploy, /ai-eng/optimize, /ai-eng/recursive-init, /ai-eng/create-plugin, /ai-eng/create-agent, /ai-eng/create-command, /ai-eng/create-skill, /ai-eng/create-tool, /ai-eng/research, /ai-eng/context"
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-eng-system",
-  "version": "0.0.15",
+  "version": "0.1.0",
   "description": "AI Engineering System with context engineering and research orchestration for Claude Code",
   "author": "v1truv1us",
   "license": "MIT",