gproject-stack-advisor

Purpose

Select the right project level and technology stack based on problems, goals, constraints, and best practices. Every recommendation must be justified with trade-offs — not "use React because it's popular" but "use React because [specific reasons matching this project's constraints]."

Iron Laws

Red Flags

Input Contract

task: "Select project level and technology stack"
input_artifacts:
  - jobs/<job>/artifacts/problem-statement.md
decisions_so_far:
  D_core_problems: [...]
  D_goals: [...]
  D_non_goals: [...]
  D_target_users: "..."
  D_scale_estimate: "..."
  # For task_in_project:
  D_existing_stack: "<if detected by context-collector>"

Output Contract

status: "DONE" | "NEEDS_CONTEXT"
summary: "<3-5 sentences: level chosen, stack chosen, key trade-off>"
new_decisions:
  D_level: "mvp | pet | startup | production"
  D_frontend: "<framework + version>"
  D_backend: "<framework + version>"
  D_database: "<DB + version>"
  D_cache: "<if needed>"
  D_queue: "<if needed>"
  D_auth: "<approach>"
  D_deploy: "<strategy>"
  D_infra: "<approach>"
artifact_path: "jobs/<job>/artifacts/stack-decision.md"
next_phase_needs:
  - "Per-technology best practices research"
  - "Architecture pattern selection"

Workflow

Step 1: Determine Project Level

Evaluate against criteria matrix:

The level determines complexity ceiling:

• MVP: max simplicity, monolith, single deploy target, minimal infra
• Pet: developer experience priority, learning-friendly stack
• Startup: balance of speed and scalability, ready for growth
• Production: reliability, security, observability, scalability first

Step 2: Evaluate Stack Options

For each layer, evaluate 2-3 options against project-specific criteria:

Evaluation criteria (weight varies by project level):

1. Problem fit — does it solve our specific problems well?
2. Team match — does the team know it? Learning curve?
3. Ecosystem — libraries, tools, community for our use case
4. Scalability ceiling — will it handle our target scale?
5. Velocity — how fast can we ship with it?
6. Cost — licensing, hosting, operational cost
7. Maturity — production-proven? Active maintenance?
8. Integration — works well with other chosen components?

Step 3: Web Research (Best Practices)

For the shortlisted stack, research:

• Current best practices (2024-2025 sources preferred)
• Common pitfalls and antipatterns
• Production case studies at similar scale
• Performance benchmarks relevant to our use case

Step 4: task_in_project Mode Adjustments

If mode is task_in_project:

• Start from existing stack (detected by context-collector)
• Only recommend NEW technologies if:
  • Existing stack cannot solve the specific problem
  • New tech integrates cleanly with existing stack
  • Learning overhead is justified by benefit
• Flag any technology additions clearly as "NEW — requires team learning"

Step 5: Write Stack Decision

Write artifacts/stack-decision.md:

# Stack Decision: <Project/Task Name>

## Project Level: <LEVEL>
**Rationale**: <why this level, based on constraints>

## Technology Stack

### Frontend: <Choice>
**Version**: <specific>
**Rationale**: <tied to project constraints>
**Alternative considered**: <what and why rejected>
**Key libraries**: <essential deps>

### Backend: <Choice>
**Version**: <specific>
**Rationale**: <tied to project constraints>
**Alternative considered**: <what and why rejected>
**Key libraries**: <essential deps>

### Database: <Choice>
...

### Infrastructure & Deploy: <Choice>
...

### Additional Services (if any)
- Cache: <if needed, with rationale>
- Queue: <if needed, with rationale>
- Search: <if needed, with rationale>

## Stack Compatibility Matrix
| Component | Integrates With | Integration Quality |
|-----------|----------------|-------------------|
| <A> | <B> | proven / good / experimental |

## Trade-offs Accepted
| Trade-off | What We Gain | What We Give Up |
|-----------|-------------|-----------------|
| <choice> | <benefit> | <cost> |

## Complexity Budget
**Total new technologies**: <count>
**Team learning required**: <list what's new>
**Estimated ramp-up**: <time>

## Risk Assessment
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| <risk> | <H/M/L> | <H/M/L> | <plan> |

Step 6: Return Summary

Compact summary: level + core stack (one line) + biggest trade-off + confidence.