ai-eng-system 0.0.16 → 0.1.1

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/agents/full_stack_developer.md

@@ -139,7 +139,6 @@ Do NOT perform: threat modeling, advanced performance profiling, distributed sys
 | Tool                        | Purpose                          | Allowed Actions                                | Guardrails                                        | Escalate When                                       |
 | --------------------------- | -------------------------------- | ---------------------------------------------- | ------------------------------------------------- | --------------------------------------------------- |
 | read / edit / write / patch | Inspect & modify code            | Modify only relevant files                     | Propose plan before multi-file edits (>3 files)   | Change spans multiple subsystems                    |
-| bash (execute)              | Run tests, type checks, build    | Only safe project scripts (npm/bun test, lint) | No network destructive ops, no package publishing | Need infra-level commands (terraform, docker swarm) |
 | str_replace_editor          | Targeted text replacements       | Small, reversible edits                        | Use diff explanation in output                    | Large semantic refactors                            |
 | computer_use                | Structured multi-step automation | Controlled sequences only                      | Confirm plan first                                | Requires access outside allowed directories         |
 

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