v2/docs/architecture/workflow-architecture-diagram.md
Visual representation of current vs. optimized workflow architecture
┌─────────────────────────────────────────────────────────────────┐
│ CURRENT WORKFLOW STRUCTURE │
│ (Over-Engineered) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ ci.yml (15 minutes) - 7 JOBS - ❌ FAILING │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Security │ │ Lint Code │ │ Type Check │ │
│ │ npm ci (1) │ │ npm ci (2) │ │ npm ci (3) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────┬───────┴──────────────────┘ │
│ │ │
│ ┌──────────▼───────────┐ │
│ │ Test Suite (4) │ │
│ │ npm ci (4) │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────▼───────────┐ │
│ │ Documentation (5) │ │
│ │ npm ci (5) │ ← Just lists files! │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────▼───────────┐ │
│ │ Build & Package │ │
│ │ npm ci (6) │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────▼───────────┐ │
│ │ Deploy (7) │ │
│ │ npm ci (7) │ │
│ └──────────────────────┘ │
│ │
│ Problems: 7x npm ci, sequential execution, redundant checks │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ test.yml (10 minutes) - DUPLICATE - ❌ REDUNDANT │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Same as ci.yml but slightly different! │
│ Why does this exist? Nobody knows! │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ integration-tests.yml (25 min) - 880 LINES - ❌ FAILING │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Fake Test Setup (Creates fake SQLite DB) │ │
│ └──────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Simulated Agent Tests │ │
│ │ node -e "console.log │ ← Fake data! │
│ │ (Math.random())" │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Fake Memory Tests │ │
│ │ Generates random JSON │ ← Not real! │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Mock Performance Data │ │
│ │ Random throughput #s │ ← Meaningless! │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Generate Fake Report │ │
│ │ All tests "pass" ✅ │ ← False confidence! │
│ └────────────────────────┘ │
│ │
│ Problem: 880 lines of simulated tests provide ZERO value │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ rollback-manager.yml (662 lines) - DANGEROUS - ❌ FAILING │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Detect Failure (Complex logic, hard to debug) │ │
│ └──────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Validate Rollback │ │
│ │ Create backup bundle │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Execute Rollback │ │
│ │ git reset --hard │ ← DANGEROUS! │
│ │ git push --force │ ← VERY DANGEROUS! │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Create Tag & Report │ │
│ │ Pollute repo w/ files │ │
│ └────────────────────────┘ │
│ │
│ Problem: Automated force pushes to main are too risky │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ truth-scoring.yml (667 lines) - REDUNDANT - ❌ COMPLEX │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Same checks as ci.yml but with "scoring" │
│ • Code accuracy (lint/typecheck) - Already in CI! │
│ • Test coverage - Already in CI! │
│ • Performance - Flaky comparison! │
│ • Documentation - Just checks if files exist! │
│ │
│ Problem: Duplicates CI work, 667 lines for basic checks │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ verification-pipeline.yml (451 lines) - SLOW - ⚠️ COMPLEX │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ Multi-Platform Matrix Testing │ │
│ │ ubuntu × macos × windows × node18 × node20 │ │
│ │ = 6 jobs for cross-platform (unnecessary!) │ │
│ └───────────────────────────────────────────────┘ │
│ │
│ Problem: Node.js is cross-platform, don't need matrix │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ status-badges.yml - ✅ WORKING FINE │
├─────────────────────────────────────────────────────────────────┤
│ Keep this one! It's well designed. │
└─────────────────────────────────────────────────────────────────┘
┌────────────────┐
│ TOTAL METRICS │
├────────────────┤
│ 7 Workflows │
│ ~2500 lines │
│ 75% failing │
│ 60min wasted/day
└────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ OPTIMIZED WORKFLOW STRUCTURE │
│ (Fast, Reliable, Simple) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ ci.yml (5 minutes) - 3 JOBS - ✅ WORKING │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Quality & Security (3 min) │ │
│ │ • npm ci (once) │ │
│ │ • lint, typecheck, audit (parallel) │ │
│ │ • Non-blocking for non-critical issues │ │
│ └──────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Test & Build (3 min) │ │
│ │ • npm ci (once) │ │
│ │ • test:coverage │ │
│ │ • build:ts │ │
│ │ • verify CLI │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Deploy (if main) │ │
│ │ • Download artifacts │ │
│ │ • Deploy │ │
│ └────────────────────────┘ │
│ │
│ Benefits: Fast, simple, reliable │
│ • 3 jobs instead of 7 │
│ • Parallel execution within jobs │
│ • Smart caching │
│ • Clear failure reasons │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ integration-real.yml (5 min) - 50 LINES - ✅ REAL TESTS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────┐ │
│ │ Matrix: Real Test Suites │ │
│ │ ┌──────────┬─────────┬─────────┐ │ │
│ │ │ swarm │ coord │ memory │ │ ← Real tests! │
│ │ └──────────┴─────────┴─────────┘ │ │
│ └─────────────────┬──────────────────┘ │
│ │ │
│ ┌───────────▼──────────────┐ │
│ │ npm run test:integration│ ← Uses real CLI! │
│ │ • Tests actual commands │ │
│ │ • Catches real bugs │ │
│ │ • 5min timeout │ │
│ └──────────────────────────┘ │
│ │
│ Benefits: Real testing, catches real issues │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ ci-failure-notify.yml (30 lines) - ✅ SAFE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ On CI Failure: │ │
│ │ 1. Create GitHub issue │ │
│ │ 2. Label as "ci-failure" + "urgent" │ │
│ │ 3. Include failure details │ │
│ │ 4. Notify team │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ Benefits: Safe, simple, human oversight │
│ • No dangerous git operations │
│ • Team makes rollback decisions │
│ • Clear notification system │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ verification-simple.yml (100 lines) - ✅ FAST │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Single Platform Testing │ │
│ │ • ubuntu-latest only │ │
│ │ • node 20 only │ │
│ │ • No unnecessary matrix │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Performance (Weekly Schedule) │ │
│ │ • Runs Sunday 2am │ │
│ │ • Doesn't block PRs │ │
│ └──────────────────────────────────────┘ │
│ │
│ Benefits: Fast verification, scheduled perf tests │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ status-badges.yml - ✅ UNCHANGED (Already good!) │
└─────────────────────────────────────────────────────────────────┘
┌────────────────┐
│ NEW METRICS │
├────────────────┤
│ 4 Workflows │
│ ~800 lines │
│ >95% passing │
│ 10min/day usage│
│ │
│ 🎯 80% savings │
└────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ CURRENT DEPENDENCIES │
└─────────────────────────────────────────────────────────────────┘
git push ──────┬──────> ci.yml (failing) ────┐
│ │
├──────> test.yml (duplicate) │
│ │
├──────> integration.yml ──────┤
│ (fake tests) │
│ │
└──────> truth-scoring.yml ────┤
(redundant) │
│
▼
rollback-manager.yml
(dangerous automation)
│
▼
Automated force push
to main! (RISKY!)
Problem: Complex trigger chain, cascade failures, dangerous actions
┌─────────────────────────────────────────────────────────────────┐
│ OPTIMIZED DEPENDENCIES │
└─────────────────────────────────────────────────────────────────┘
git push ──────┬──────> ci.yml (fast, reliable) ────┐
│ 5 min, 3 jobs │
│ │
│ ▼
│ (IF FAIL on main)
│ │
├──────> integration-real.yml ───────┤
│ 5 min, real tests │
│ │
└──────> verification-simple.yml │
8 min, quality gates │
│
▼
ci-failure-notify.yml
(creates issue)
│
▼
Human reviews & decides
(safe manual rollback)
Benefits: Clear flow, no cascade failures, human oversight
Time (minutes)
0 5 10 15 20 25 30 35 40 45 50 55
|----|----|----|----|----|----|----|----|----|----|----|----|
[========== ci.yml (15min) ❌ FAILS ===========]
[===== test.yml (10min) ❌ DUPLICATE =====]
[============= integration.yml (25min) ❌ FAKE =============]
[=========== truth-scoring.yml (20min) ❌ REDUNDANT ===========]
↑
All start together, most fail, provide no value
Total wasted time: ~70 minutes per PR
None complete successfully!
Time (minutes)
0 5 10 15
|----|----|----|----|
[== ci.yml (5min) ✅ PASSES ==]
[== integration (5min) ✅ ==]
[== verification (8min) ✅ ==]
↑
Sequential execution, all pass, clear feedback
Total time: ~13 minutes per PR
All complete successfully!
Time saved: 57 minutes (81% improvement)
┌─────────────────────────────────────────────────────────────────┐
│ CURRENT RESOURCE USAGE (Daily) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CI Runs: 20 per day │
│ Success Rate: 25% (5 succeed, 15 fail) │
│ Avg Duration: 15 minutes │
│ Failed Run Time: 15 min × 15 = 225 minutes wasted │
│ Successful Runs: 15 min × 5 = 75 minutes useful │
│ Total Daily Time: 300 minutes │
│ Useful Work: 25% │
│ Wasted Work: 75% │
│ │
│ Monthly GitHub Actions Minutes: ~9,000 minutes │
│ Estimated Cost: $90/month (wasted: $67.50) │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ OPTIMIZED RESOURCE USAGE (Daily) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CI Runs: 20 per day │
│ Success Rate: 95% (19 succeed, 1 fail) │
│ Avg Duration: 5 minutes │
│ Failed Run Time: 5 min × 1 = 5 minutes wasted │
│ Successful Runs: 5 min × 19 = 95 minutes useful │
│ Total Daily Time: 100 minutes │
│ Useful Work: 95% │
│ Wasted Work: 5% │
│ │
│ Monthly GitHub Actions Minutes: ~3,000 minutes │
│ Estimated Cost: $30/month (wasted: $1.50) │
│ │
│ 💰 MONTHLY SAVINGS: $60 (67% cost reduction) │
│ ⏱️ TIME SAVINGS: 6,000 minutes/month (100 hours) │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ IMPLEMENTATION TIMELINE │
└─────────────────────────────────────────────────────────────────┘
Week 1: PHASE 1 - Critical Fixes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Day 1-2: Delete fake integration tests
✅ Remove 880 lines
✅ Add real tests
📊 Immediate 25min savings
Day 3-4: Replace rollback automation
✅ Remove dangerous operations
✅ Add notification workflow
🛡️ Safer, human oversight
Day 5: Remove duplicate test.yml
✅ Eliminate confusion
✅ Single source of truth
Result: 3 failing workflows → 0 failures
~40min savings per run
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 2: PHASE 2 - Consolidation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Day 1-3: Optimize CI pipeline
✅ 7 jobs → 3 jobs
✅ Parallel execution
⚡ 50% faster
Day 4: Delete truth scoring
✅ Remove duplication
✅ Merge into CI
Day 5: Simplify verification
✅ Single platform
✅ Scheduled performance
Result: 15min → 5min CI
67% faster feedback
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 3: PHASE 3 - Polish
━━━━━━━━━━━━━━━━━━━━━━━━
Day 1-2: Optimize caching
Day 3-4: Add retry logic
Day 5: Documentation
Result: Professional, maintainable
~800 total lines
>95% success rate
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┌──────────────────┐
│ FINAL OUTCOME │
├──────────────────┤
│ 80% faster │
│ 87% more reliable│
│ 68% less code │
│ 67% lower cost │
│ │
│ ✨ Much happier │
│ developers! │
└──────────────────┘
┌──────────┐
│ PR Push │
└─────┬────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ ci.yml │ │test.yml │ │ integ. │
│ ❌ FAIL │ │ ❌ FAIL │ │ ❌ FAIL │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└───────────────┼───────────────┘
│
┌────▼────┐
│rollback │
│ ❌ FAIL │ ← Makes it worse!
└─────────┘
Problem: Everything fails, no clear root cause,
automated rollback fails too!
┌──────────┐
│ PR Push │
└─────┬────┘
│
┌────▼────┐
│ ci.yml │
│ Stage 1 │
└─────┬───┘
│
┌────▼────┐
│ Quality │
│ ✅ PASS │
└────┬────┘
│
┌────▼────┐
│ Test │
│ ❌ FAIL │ ← Clear failure point!
└────┬────┘
│
▼
Workflow stops
Clear error message
Developer fixes tests
Benefit: Know exactly what failed,
no cascade, no confusion!
┌─────────────────────────────────────────────────────────────────┐
│ QUALITY GATES │
└─────────────────────────────────────────────────────────────────┘
Code Push
│
▼
┌───────────────┐
│ Gate 1: Lint │ ← Fast feedback (30 sec)
│ & TypeCheck │
└───────┬───────┘
│ PASS
▼
┌───────────────┐
│ Gate 2: Tests │ ← Comprehensive (2 min)
│ & Coverage │
└───────┬───────┘
│ PASS
▼
┌───────────────┐
│ Gate 3: Build │ ← Verification (1 min)
│ & CLI Check │
└───────┬───────┘
│ PASS
▼
┌───────────────┐
│ Gate 4: Real │ ← Integration (3 min)
│ Integration │
└───────┬───────┘
│ PASS
▼
✅ Ready to Merge!
Benefits:
✅ Fast feedback on basic issues
✅ Progressive validation
✅ Stop early if problems found
✅ Clear requirements for merge
Document Version: 1.0 Last Updated: 2025-11-24 See Also:
github-workflows-optimization-strategy.md (Full strategy)workflow-optimization-implementation-guide.md (Step-by-step guide)