Epic: Code Quality - Embrace "Absolutely Pure & Simple" Design Philosophy

[kingdonb]

Vision: No Unnecessary Baggage

"We can't call it deis (or hephy) if the design isn't absolutely pure & simple with no unnecessary baggage!"

This epic tracks our commitment to the Deis/Hephy heritage of radical simplicity.

Current State Analysis

• ✅ DRY Achievement: Eliminated 600 lines of duplicate code (75% reduction)
• ✅ Unified Architecture: Single shared script for all build logic
• ✅ Clean Separation: Ko/Kaniko backends with clear responsibility boundaries

Purity Assessment Areas

1. Configuration Simplicity

• Current: build-config.yaml handles multiple backends
• Question: Is this the simplest possible interface?
• Action: Audit for unnecessary complexity

2. Build Script Elegance

• Current: hack/build_images.sh (130 lines)
• Question: Can we eliminate more complexity?
• Action: Review for unnecessary abstractions

3. Workflow Clarity

• Current: prepare → build → manifest → summary
• Question: Is each stage absolutely necessary?
• Action: Validate each stage adds essential value

4. Backend Selection Logic

• Current: Ko for Go apps, Kaniko for Docker
• Question: Can we simplify the decision matrix?
• Action: Test if Ko could handle all use cases

Deis Heritage Principles

1. Zero Configuration: "git push" should just work
2. Minimal Dependencies: Only essential components
3. Clear Mental Model: Obvious how it works
4. No Magic: Transparent operations

Success Criteria

• Zero unnecessary configuration options
• Clear single responsibility for each component
• Documentation explains "why" not just "what"
• Any developer can understand the full system in 15 minutes

Next Sprint Actions

1. Configuration audit: Remove unused options
2. Script simplification: Extract common patterns
3. Documentation clarity: Focus on essential concepts
4. User experience validation: Test with fresh eyes

Priority: High - Core to project identity

[kingdonb]

🔄 Vision Correction & Strategic Clarification

Correcting the "Simplify Decision Matrix" Direction

I need to correct my previous comment about testing if Ko could handle all use cases. This is opposite the direction we should take.

Our guiding principle: We're not trying to provide "the best" option, we're trying to provide options that cover a range of use cases.

The Real Strategy: Multi-Backend Excellence

Baseline Support for First Release

1. Ko: Go projects that can leverage its optimizations
2. Kaniko: Non-Go projects and universal Docker builds
3. BuildKit: For Kaniko itself (advanced Docker features)
4. Potential 4th: Slugbuilder/Pack CLI/other (TBD)

Interface Stability Priority

We need to ensure our first release has everything needed for the interface so we don't make breaking changes later. Users from column A shouldn't regret their choice when we add support for users in column B.

Critical Success Criteria

• Ko & Kaniko working by end of conversation ✅
• BuildKit working (stretch goal) 🎯
• At least one backend functional (minimum viable) ⭐

Dogfooding Strategy

Build an image (or GitHub Actions workflow) that:

• Contains all tools we need baked in
• Builds using one of our builders
• Enables iteration & testing
• Raises issues where reality doesn't match expectations

Architecture Goals

• GitHub Actions support without straying from GitLab workflow
• Address GitLab limitations: No shell in Kaniko, no git, script extraction issues
• Modular design: Extract scripts from YAML for reusability
• Shell & Git availability: GitHub Actions runners should solve these constraints

---

Priority: Start with multi-backend interface design, implement Ko + Kaniko, validate with dogfood builds

[kingdonb]

Implementation Strategy Update

Based on analysis of the existing GitHub Actions workflow and GitLab CI architecture:

Key Insight: Ko can create native multi-arch images in a single job, eliminating the need for complex manifest stitching that Kaniko requires.

Current Status:

• GitLab CI is "done" (builds local and remote images with Kaniko)
• GitHub Actions workflow exists with Ko + Kaniko backends
• Manifest stage is failing (likely missing manifest-tool image)

Implementation Plan:

1. Fix GitHub Actions manifest stage failure
2. Implement Ko native multi-arch builds (single job vs matrix)
3. Create dogfood mechanism to build hephy-builder with hephy-builder
4. Performance validation and documentation

Next Steps: Focus on GitHub Actions only until MVP delivered, then maintain GitLab CI compatibility.