| name | tech-stack-evaluator |
| description | Technology stack evaluation and comparison with TCO analysis, security assessment, and ecosystem health scoring. Use when comparing frameworks, evaluating technology stacks, calculating total cost of ownership, assessing migration paths, or analyzing ecosystem viability.
|
| license | MIT + Commons Clause |
| metadata | {"version":"1.0.0","author":"borghei","category":"engineering","domain":"technology-evaluation","updated":"2026-03-31T00:00:00.000Z","tags":["framework-comparison","tco-analysis","technology-evaluation"]} |
Technology Stack Evaluator
Evaluate and compare technologies, frameworks, and cloud providers with data-driven analysis and actionable recommendations.
Table of Contents
Capabilities
| Capability | Description |
|---|
| Technology Comparison | Compare frameworks and libraries with weighted scoring |
| TCO Analysis | Calculate 5-year total cost including hidden costs |
| Ecosystem Health | Assess GitHub metrics, npm adoption, community strength |
| Security Assessment | Evaluate vulnerabilities and compliance readiness |
| Migration Analysis | Estimate effort, risks, and timeline for migrations |
| Cloud Comparison | Compare AWS, Azure, GCP for specific workloads |
Quick Start
Compare Two Technologies
Compare React vs Vue for a SaaS dashboard.
Priorities: developer productivity (40%), ecosystem (30%), performance (30%).
Calculate TCO
Calculate 5-year TCO for Next.js on Vercel.
Team: 8 developers. Hosting: $2500/month. Growth: 40%/year.
Assess Migration
Evaluate migrating from Angular.js to React.
Codebase: 50,000 lines, 200 components. Team: 6 developers.
Input Formats
The evaluator accepts three input formats:
Text - Natural language queries
Compare PostgreSQL vs MongoDB for our e-commerce platform.
YAML - Structured input for automation
comparison:
technologies: ["React", "Vue"]
use_case: "SaaS dashboard"
weights:
ecosystem: 30
performance: 25
developer_experience: 45
JSON - Programmatic integration
{
"technologies": ["React", "Vue"],
"use_case": "SaaS dashboard"
}
Analysis Types
Quick Comparison (200-300 tokens)
- Weighted scores and recommendation
- Top 3 decision factors
- Confidence level
Standard Analysis (500-800 tokens)
- Comparison matrix
- TCO overview
- Security summary
Full Report (1200-1500 tokens)
- All metrics and calculations
- Migration analysis
- Detailed recommendations
Scripts
stack_comparator.py
Compare technologies with customizable weighted criteria.
python scripts/stack_comparator.py --help
tco_calculator.py
Calculate total cost of ownership over multi-year projections.
python scripts/tco_calculator.py --input assets/sample_input_tco.json
ecosystem_analyzer.py
Analyze ecosystem health from GitHub, npm, and community metrics.
python scripts/ecosystem_analyzer.py --technology react
security_assessor.py
Evaluate security posture and compliance readiness.
python scripts/security_assessor.py --technology express --compliance soc2,gdpr
migration_analyzer.py
Estimate migration complexity, effort, and risks.
python scripts/migration_analyzer.py --from angular-1.x --to react
References
| Document | Content |
|---|
references/metrics.md | Detailed scoring algorithms and calculation formulas |
references/examples.md | Input/output examples for all analysis types |
references/workflows.md | Step-by-step evaluation workflows |
Confidence Levels
| Level | Score | Interpretation |
|---|
| High | 80-100% | Clear winner, strong data |
| Medium | 50-79% | Trade-offs present, moderate uncertainty |
| Low | < 50% | Close call, limited data |
When to Use
- Comparing frontend/backend frameworks for new projects
- Evaluating cloud providers for specific workloads
- Planning technology migrations with risk assessment
- Calculating build vs. buy decisions with TCO
- Assessing open-source library viability
When NOT to Use
- Trivial decisions between similar tools (use team preference)
- Mandated technology choices (decision already made)
- Emergency production issues (use monitoring tools)
Troubleshooting
| Problem | Cause | Solution |
|---|
| Weighted scores all return 50.0 | Technology data dictionaries missing score keys under each category | Ensure each category dict contains a score key on a 0-100 scale (e.g., {"performance": {"score": 85}}) |
| TCO projections look unrealistically low | Default cost parameters used when operational_costs or initial_costs are empty | Populate monthly_hosting, annual_licensing, developer_hourly_rate, and maintenance_hours_per_dev_monthly with real figures |
| Ecosystem health score stuck at 50 for npm | npm_data dict is empty or not provided | Pass npm metrics (weekly_downloads, version, dependencies_count, days_since_last_publish); 50 is the neutral fallback when npm data is absent |
| Security compliance returns "Unknown standard" | Unsupported standard name passed to assess_compliance() | Use one of the supported keys: GDPR, SOC2, HIPAA, PCI_DSS (case-sensitive) |
| Migration complexity always shows moderate | architecture_change_level defaults to moderate when not specified | Set architecture_change_level explicitly to minimal, moderate, significant, or complete in codebase_stats |
| Report renders ASCII tables instead of markdown | ReportGenerator auto-detects CLI context when stdout is a TTY | Pass output_context='desktop' to force rich markdown output |
| Format detector misclassifies YAML as text | Fewer than 50% of lines match YAML key-value patterns | Ensure input uses standard YAML syntax with key: value pairs and proper indentation |
Success Criteria
- TCO variance under 15%: Calculated TCO deviates less than 15% from actual costs when validated against real-world spending data over the projection period.
- Security score above 80/100: Technologies recommended for production use achieve a minimum overall security score of 80, corresponding to grade B or higher.
- Ecosystem health score above 65/100: Recommended technologies demonstrate viable long-term ecosystem health with a risk level no worse than "Low-Medium."
- Migration effort estimate within 20%: Person-hours and timeline estimates land within 20% of actual migration effort when measured post-completion.
- Comparison confidence above 70%: Final technology recommendations carry a confidence score of 70% or higher, indicating a meaningful score gap between top candidates.
- Compliance readiness at "Mostly Ready" or above: Technologies targeting regulated environments achieve at least 70% feature coverage against required compliance standards (GDPR, SOC2, HIPAA, PCI-DSS).
- Report generation under 5 seconds: All report types (executive summary, full report) render within 5 seconds for evaluations comparing up to 5 technologies.
Scope & Limitations
Covers:
- Weighted multi-criteria comparison of frameworks, libraries, and cloud providers
- Multi-year TCO projections including hidden costs (technical debt, vendor lock-in, turnover)
- Ecosystem viability assessment using GitHub, npm, and community metrics
- Security posture scoring and compliance readiness for GDPR, SOC2, HIPAA, PCI-DSS
Does NOT cover:
- Live data fetching from GitHub API, npm registry, or vulnerability databases (all data must be provided as input dictionaries)
- Performance benchmarking or load testing (use
engineering/senior-qa for test execution)
- Licensing legal review or contract negotiation (use
ra-qm-team compliance skills for regulatory guidance)
- Team hiring or organizational design decisions (use
hr-operations/talent-acquisition for staffing analysis)
Integration Points
| Skill | Integration | Data Flow |
|---|
engineering/senior-security | Feed security assessor output into deeper vulnerability analysis | SecurityAssessor results → security review input |
engineering/senior-devops | Use TCO hosting projections to inform infrastructure planning | TCOCalculator hosting/scaling data → DevOps capacity models |
engineering/senior-qa | Migration test coverage scores inform QA test planning | MigrationAnalyzer testing_requirements → QA test strategy |
ra-qm-team/compliance-auditor | Compliance readiness gaps feed into formal audit preparation | SecurityAssessor.assess_compliance() missing features → audit checklist |
c-level-advisor/cto-advisor | Executive summaries and TCO reports support CTO decision-making | ReportGenerator executive summary → strategic technology decisions |
product-team/product-manager | Ecosystem viability and migration timelines inform product roadmaps | EcosystemAnalyzer + MigrationAnalyzer → roadmap planning |
Tool Reference
stack_comparator.py
Purpose: Compare technologies with customizable weighted criteria across 8 evaluation categories: performance, scalability, developer experience, ecosystem, learning curve, documentation, community support, and enterprise readiness.
Usage:
from stack_comparator import StackComparator
comparator = StackComparator({
"technologies": ["React", "Vue"],
"use_case": "SaaS dashboard",
"weights": {"developer_experience": 40, "performance": 30, "ecosystem": 30}
})
results = comparator.compare_technologies(tech_data_list)
Constructor Parameters (comparison_data dict):
| Key | Type | Default | Description |
|---|
technologies | list | [] | Names of technologies to compare |
use_case | str | "general" | Use case context (supports real-time, enterprise, startup bonuses) |
priorities | dict | {} | Priority overrides |
weights | dict | DEFAULT_WEIGHTS | Category weights (auto-normalized to 100) |
Default Weights: performance 15, scalability 15, developer_experience 20, ecosystem 15, learning_curve 10, documentation 10, community_support 10, enterprise_readiness 5.
Key Methods:
compare_technologies(tech_data_list) -- Full comparison with scores, recommendation, confidence, and decision factorsscore_technology(tech_name, tech_data) -- Score a single technology across all categoriescalculate_weighted_score(category_scores) -- Calculate weighted total from category scoresgenerate_pros_cons(tech_name, tech_scores) -- Generate pros/cons lists from scores
Example Output:
{
"technologies": {"React": {"weighted_total": 78.5, "strengths": [...], "weaknesses": [...]}},
"recommendation": "React",
"confidence": 72.0,
"decision_factors": [{"category": "developer_experience", "importance": "40.0%", "best_performer": "React"}],
"comparison_matrix": [{"category": "performance", "weight":
Output Format: Python dictionary (serialize with json.dumps() for JSON output).
tco_calculator.py
Purpose: Calculate comprehensive Total Cost of Ownership over multi-year projections, including initial costs, operational costs, scaling costs, hidden costs (technical debt, vendor lock-in, security incidents, downtime, turnover), and developer productivity impact.
Usage:
from tco_calculator import TCOCalculator
calculator = TCOCalculator({
"technology": "Next.js",
"team_size": 8,
"timeline_years": 5,
"initial_costs": {"licensing": 0, "migration": 15000, "developer_hourly_rate": 100},
"operational_costs": {"monthly_hosting": 2500, "annual_licensing": 0, "maintenance_hours_per_dev_monthly": 20},
"scaling_params": {"annual_growth_rate": 0.40, "initial_users": 5000}
})
tco = calculator.calculate_total_tco()
summary = calculator.generate_tco_summary()
Constructor Parameters (tco_data dict):
| Key | Type | Default | Description |
|---|
technology | str | "Unknown" | Technology name |
team_size | int | 5 | Number of developers |
timeline_years | int | 5 | Projection period in years |
initial_costs | dict | {} | One-time costs: licensing, migration, setup, tooling, training_hours_per_dev, developer_hourly_rate, training_materials |
operational_costs | dict | {} | Recurring costs: monthly_hosting, annual_licensing, annual_support, maintenance_hours_per_dev_monthly |
scaling_params | dict | {} | Growth params: annual_growth_rate, initial_users, initial_servers, cost_per_server_monthly |
productivity_factors | dict | {} | Productivity: productivity_multiplier, time_to_market_reduction_days, avg_feature_time_days, avg_feature_value, technical_debt_percentage, vendor_lock_in_risk, security_incidents_per_year, avg_security_incident_cost, downtime_hours_per_year, downtime_cost_per_hour, annual_turnover_rate, cost_per_new_hire |
Key Methods:
calculate_total_tco() -- Complete TCO with all cost componentsgenerate_tco_summary() -- Executive summary with formatted dollar amountscalculate_initial_costs() -- One-time cost breakdowncalculate_operational_costs() -- Year-by-year operational costscalculate_scaling_costs() -- User projections and cost-per-user analysiscalculate_hidden_costs() -- Technical debt, vendor lock-in, security, downtime, turnovercalculate_productivity_impact() -- Productivity gains and feature velocity
Output Format: Python dictionary (all monetary values as floats; generate_tco_summary() returns pre-formatted dollar strings).
ecosystem_analyzer.py
Purpose: Analyze technology ecosystem health and long-term viability by scoring GitHub activity, npm adoption, community strength, corporate backing, and maintenance responsiveness on a 0-100 scale.
Usage:
from ecosystem_analyzer import EcosystemAnalyzer
analyzer = EcosystemAnalyzer({
"technology": "React",
"github": {"stars": 220000, "forks": 45000, "contributors": 1500, "commits_last_month": 120},
"npm": {"weekly_downloads": 20000000, "version": "18.2.0", "dependencies_count": 3},
"community": {"stackoverflow_questions": 400000, "job_postings": 15000},
"corporate_backing": {"type": "major_tech_company"}
})
report = analyzer.generate_ecosystem_report()
viability = analyzer.assess_viability()
Constructor Parameters (ecosystem_data dict):
| Key | Type | Default | Description |
|---|
technology | str | "Unknown" | Technology name |
github | dict | {} | GitHub metrics: stars, forks, contributors, commits_last_month, avg_issue_response_hours, issue_resolution_rate, releases_per_year, active_maintainers, open_issues |
npm | dict | {} | npm metrics: weekly_downloads, version, dependencies_count, days_since_last_publish |
community | dict | {} | Community metrics: stackoverflow_questions, job_postings, tutorials_count, forum_members |
corporate_backing | dict | {} | Backing info: type (one of major_tech_company, established_company, startup_backed, community_led, none), funding_millions |
Health Score Weights: github_health 25%, npm_health 20%, community_health 20%, corporate_backing 15%, maintenance_health 20%.
Key Methods:
generate_ecosystem_report() -- Complete report with health scores, viability, and formatted metricscalculate_health_score() -- Component scores and weighted overall scoreassess_viability() -- Viability level, risk assessment, strengths, and recommendation
Output Format: Python dictionary with nested health scores, viability assessment, and formatted metrics.
security_assessor.py
Purpose: Evaluate security posture and compliance readiness for technology stacks. Scores vulnerabilities, patch responsiveness, built-in security features, and track record. Assesses compliance against GDPR, SOC2, HIPAA, and PCI-DSS.
Usage:
from security_assessor import SecurityAssessor
assessor = SecurityAssessor({
"technology": "Express",
"vulnerabilities": {
"critical_last_12m": 0, "high_last_12m": 2,
"avg_critical_patch_days": 7, "has_security_team": True
},
"security_features": {
"encryption_in_transit": True, "authentication": True,
"input_validation": True, "csrf_protection": True
},
"compliance_requirements": ["SOC2", "GDPR"]
})
report = assessor.generate_security_report()
compliance = assessor.assess_compliance(["SOC2", "GDPR"])
Constructor Parameters (security_data dict):
| Key | Type | Default | Description |
|---|
technology | str | "Unknown" | Technology name |
vulnerabilities | dict | {} | Vulnerability data: critical_last_12m, high_last_12m, medium_last_12m, low_last_12m, critical_last_3y, high_last_3y, medium_last_3y, low_last_3y, avg_critical_patch_days, avg_high_patch_days, has_security_team, years_since_major_incident, has_security_certifications, has_bug_bounty_program, security_audits_per_year, common_vulnerability_types |
security_features | dict | {} | Boolean feature flags: encryption_at_rest, encryption_in_transit, authentication, authorization, input_validation, rate_limiting, csrf_protection, xss_protection, sql_injection_protection, audit_logging, mfa_support, rbac, secrets_management, security_headers, cors_configuration |
compliance_requirements | list | [] | Standards to assess: GDPR, SOC2, HIPAA, PCI_DSS |
Security Score Weights: vulnerability_score 30%, patch_responsiveness 25%, security_features 30%, track_record 15%.
Key Methods:
generate_security_report() -- Full report with score, compliance, vulnerabilities, and recommendationscalculate_security_score() -- Component scores with letter grade (A-F)assess_compliance(standards) -- Per-standard readiness with missing features listidentify_vulnerabilities() -- Categorized vulnerability report with trend analysis
Output Format: Python dictionary with security scores, compliance assessments, and risk level.
migration_analyzer.py
Purpose: Analyze migration complexity, estimate effort in person-hours and calendar months, assess technical/business/team risks, and recommend a migration approach (direct, phased, or strangler pattern) based on complexity scoring.
Usage:
from migration_analyzer import MigrationAnalyzer
analyzer = MigrationAnalyzer({
"source_technology": "Angular 1.x",
"target_technology": "React",
"codebase_stats": {
"lines_of_code": 50000, "num_components": 200,
"architecture_change_level": "significant",
"current_test_coverage": 0.6
},
"team": {"team_size": 6, "target_tech_experience": "low"},
"constraints": {"downtime_tolerance": "low"}
})
plan = analyzer.generate_migration_plan()
effort = analyzer.estimate_effort()
risks = analyzer.assess_risks()
Constructor Parameters (migration_data dict):
| Key | Type | Default | Description |
|---|
source_technology | str | "Unknown" | Current technology |
target_technology | str | "Unknown" | Target technology |
codebase_stats | dict | {} | Codebase metrics: lines_of_code, num_files, num_components, architecture_change_level (minimal/moderate/significant/complete), has_database, database_size_gb, schema_changes_required, data_transformation_required, breaking_api_changes (none/minimal/some/many/complete), num_dependencies, dependencies_to_replace, current_test_coverage (0-1), num_tests |
team | dict | {} | Team info: team_size, hours_per_week, target_tech_experience (none/low/medium/high) |
constraints | dict | {} | Constraints: downtime_tolerance (none/low/medium/high) |
Complexity Score Weights: code_volume 20%, architecture_changes 25%, data_migration 20%, api_compatibility 15%, dependency_changes 10%, testing_requirements 10%.
Key Methods:
generate_migration_plan() -- Complete plan with complexity, effort, risks, approach, and success criteriacalculate_complexity_score() -- Per-factor complexity scores (1-10 scale)estimate_effort() -- Person-hours, person-months, phase breakdown, and calendar timelineassess_risks() -- Technical, business, and team risks with severity and mitigation strategies
Output Format: Python dictionary with nested complexity analysis, effort estimation, risk assessment, and recommended approach.
report_generator.py
Purpose: Generate context-aware evaluation reports with progressive disclosure. Auto-detects output context (Claude Desktop vs CLI) and renders rich markdown tables or ASCII-formatted output accordingly. Supports selective section generation.
Usage:
from report_generator import ReportGenerator
generator = ReportGenerator(report_data, output_context="desktop")
executive_summary = generator.generate_executive_summary(max_tokens=300)
full_report = generator.generate_full_report(sections=["executive_summary", "comparison_matrix", "tco_analysis"])
generator.export_to_file("evaluation_report.md")
Constructor Parameters:
| Parameter | Type | Default | Description |
|---|
report_data | dict | (required) | Complete evaluation data containing any combination of: technologies, recommendation, decision_factors, comparison_matrix, tco_analysis, ecosystem_health, security_assessment, migration_analysis, performance_benchmarks, use_case |
output_context | str | None (auto-detect) | Output format: "desktop" for rich markdown, "cli" for ASCII tables. Auto-detects via CLAUDE_DESKTOP env var and TTY check |
Available Report Sections: executive_summary, comparison_matrix, tco_analysis, ecosystem_health, security_assessment, migration_analysis, performance_benchmarks.
Key Methods:
generate_executive_summary(max_tokens=300) -- Concise summary with recommendation, strengths, concerns, and decision factorsgenerate_full_report(sections=None) -- Complete report with selected sections (all if None)export_to_file(filename, sections=None) -- Write report to file, returns file path
Output Format: Markdown string (desktop context) or ASCII-formatted string (CLI context).
format_detector.py
Purpose: Automatically detect and parse input format (JSON, YAML, URL, or natural language text) for technology evaluation requests. Extracts technology names, use cases, priorities, and analysis types from unstructured text input.
Usage:
from format_detector import FormatDetector
detector = FormatDetector('Compare React vs Vue for a SaaS dashboard. Priorities: performance, ecosystem.')
format_type = detector.detect_format()
parsed = detector.parse()
info = detector.get_format_info()
Constructor Parameters:
| Parameter | Type | Default | Description |
|---|
input_data | str | (required) | Raw input string in any supported format |
Supported Formats:
- JSON -- Valid JSON objects are detected and parsed directly
- YAML -- Detected when >50% of lines match key-value or list patterns (simplified parser, no PyYAML dependency)
- URL -- Detected when input contains
http:// or https:// URLs; categorizes GitHub, npm, and other URLs
- Text -- Natural language fallback; extracts technologies from 30+ known keywords, identifies use cases, priorities, and analysis types
Key Methods:
detect_format() -- Returns format string: "json", "yaml", "url", or "text"parse() -- Parse input and return normalized dictionary with standard keys: technologies, use_case, priorities, analysis_type, formatget_format_info() -- Detection metadata: detected_format, input_length, line_count, parsing_successful
Output Format: Python dictionary normalized to a standard structure with keys: technologies (list), use_case (str), priorities (list), analysis_type (str), format (str).
