stack-selection

Tech Stack Selection

Philosophy: Choose tools based on context, requirements, and user preference. No "one size fits all" solutions. Core Principle: ASK user preferences, SUGGEST based on context, EXPLAIN trade-offs.

---

When to Use This Skill

Use this skill when:

• Starting a new project (no existing code)
• Adding a new feature that could use different stacks
• User asks "what stack should I use?"
• Migration between technologies is being considered

Do NOT use this skill when:

• Project already has established stack (maintain consistency)
• User explicitly specifies what to use
• Only minor adjustments are needed

---

Question Tool Protocol (MANDATORY)

ALWAYS use the question tool for stack selection decisions.

Multi-Option Format (Preferred)

question({
  questions: [{
      question: "Which backend framework would you like to use?",
      header: "Backend Framework",
      options: [
        {
          label: "Fullstack Blueprint (Recommended)",
          description: "FastAPI + SQLAlchemy + Alembic - battle-tested, includes Docker, Redis, Celery"
        },
        {
          label: "FastAPI (Custom)",
          description: "Fast, modern, async - great for APIs"
        },
        {
          label: "Express/​Node.js",
          description: "Flexible, huge ecosystem, good for fullstack JavaScript"
        },
        {
          label: "Hono",
          description: "Ultra-fast, edge-ready, TypeScript-first"
        },
        {
          label: "Other",
          description: "Let me know your preference"
        }
      ]
    }]
})

Preference Questions Format

When checking user preferences:

question({
  questions: [{
      question: "Do you have any tech stack preferences?",
      header: "Stack Preferences",
      multiple: true,
      options: [
        {
          label: "Use the Fullstack Blueprint",
          description: "I want the standard stack: React/​Vite + FastAPI + SQLAlchemy"
        },
        {
          label: "I have specific preferences",
          description: "I'll tell you exactly what I want"
        },
        {
          label: "Suggest based on my requirements",
          description: "Help me choose based on what I'm building"
        }
      ]
    }]
})

See .opencode/​rules/​MASTER.md for complete Question Tool Protocol.

---

Stack Selection Process

Phase 1: Context Analysis (ALWAYS FIRST)

Before suggesting anything, gather context:

Reference: See @blueprints/​fullstack/ for an example of a well-configured fullstack setup. Use it as reference, not requirement.

Phase 2: Check Existing Stack

Phase 2: Check Existing Stack

Before suggesting, check if stack exists:

# Check for existing backend
ls backend/​pyproject.toml backend/​package.json backend/​go.mod 2>/​dev/​null

# Check for existing frontend
ls frontend/​package.json package.json 2>/​dev/​null

# Check for config files
ls docker-compose.* vite.config.* next.config.* 2>/​dev/​null

If stack exists:

• Maintain consistency unless migration is explicitly requested
• Ask user: "You already use [X]. Should I continue with that stack, or are you considering changes?"

Phase 3: User Preferences

ALWAYS ask about preferences:

1. Primary question:

   question({
     questions: [{
         question: "Do you have any tech stack preferences?",
         header: "Stack Preferences",
         multiple: true,
         options: [
           {
             label: "I have specific preferences",
             description: "I'll tell you exactly what I want"
           },
           {
             label: "Suggest based on my requirements",
             description: "Help me choose based on what I'm building"
           }
         ]
       }]
   })
   

2. If user wants suggestions: Proceed to Phase 4 with decision trees

Phase 4: Suggest Based on Requirements

If user wants suggestions, provide options with trade-offs:

Example Backend Suggestion:

---

Fullstack Blueprint (Example Stack)

Blueprint Stack Details

Note: This is an example of a well-configured fullstack setup used in @blueprints/​fullstack/. It's not mandatory - use it as reference, not requirement.

Frontend:

- React 18: Modern, component-based
- Vite: Fast dev server, optimized builds
- TanStack Query: Server state management (caching, refetching)
- TanStack Router: Type-safe routing
- Tailwind CSS: Utility-first styling
- ShadcnUI: Accessible, customizable components

Backend:

- FastAPI: Async, modern Python, automatic OpenAPI docs
- SQLAlchemy: ORM, migrations via Alembic
- PostgreSQL: Robust relational database
- Redis: Caching, Celery broker
- Celery: Async task queue
- Docker: Containerization

Infrastructure:

- Docker Compose: Dev and production setups
- Poetry: Python dependency management

---

Backend Decision Tree

Framework Selection

What runtime do you prefer?
├── Python
│   ├── Need async/​high performance?
│   │   ├── Yes → FastAPI (recommended)
│   │   └── No → Django (batteries included) or Flask (lightweight)
│   └── Need full features?
│       ├── Yes → Django
│       └── No → FastAPI or Flask
├── Node.js
│   ├── Edge deployment?
│   │   ├── Yes → Hono or Bun
│   │   └── No → Fastify (performance) or Express (flexible)
│   └── TypeScript fullstack?
│       └── Consider tRPC with Next.js
└── Go/​Rust
    └── Performance critical → FastAPI is usually sufficient

Database Selection

What type of data?
├── Relational data, complex relationships
│   ├── Production → PostgreSQL (recommended)
│   ├── Edge/​Serverless → Neon (serverless PG)
│   └── Simple/​Local → SQLite
├── Vector search/​AI
│   └── PostgreSQL + pgvector or dedicated vector DB
├── Global distribution
│   └── Turso (edge SQLite) or PlanetScale (MySQL)
└── Key-value cache
    └── Redis or Upstash (serverless)

ORM Selection

Python:
├── FastAPI → SQLAlchemy (recommended) or Tortoise ORM
├── Django → Django ORM (built-in)
└── Simple → Pydantic models + direct SQL

Node.js:
├── PostgreSQL → Prisma or Drizzle
└── Performance → Drizzle (edge-ready)

---

Frontend Decision Tree

Framework Selection

What type of application?
├── Single Page App (SPA)
│   ├── React ecosystem?
│   │   ├── Yes → React + Vite (recommended in blueprint)
│   │   └── No → Svelte + SvelteKit or Vue + Vite
│   └── Build tools → Vite (fastest) or Next.js (SSR)
├── Server-Side Rendering (SSR)
│   ├── Need SEO/​crawling?
│   │   ├── Yes → Next.js (recommended)
│   │   └── No → Consider SPA
│   └── Fullstack TypeScript?
│       └── Next.js + tRPC (type-safe)
└── Static Site
    └── Next.js (static export) or Astro

State Management

What state do you need?
├── Server data (API calls)
│   └── TanStack Query (recommended) or SWR
├── Client state (UI state)
│   ├── Simple → React built-in (useState, useReducer)
│   ├── Complex but local → Zustand
│   └── Global/​shared → Context API or Redux Toolkit
└── URL state (shareable)
    └── URL params + useSearchParams

UI Library Selection

What do you need?
├── Blueprint default → ShadcnUI (recommended)
├── Full-featured component library
│   ├── Radix UI (unstyled primitives)
│   ├── Mantine (opinionated)
│   ├── Chakra UI (simple)
│   └── Material UI (Google design)
├── Design system building
│   └── Headless UI or Radix UI
└── Complete control
│   └── Custom CSS or Tailwind only

Styling

What approach?
├── Blueprint default → Tailwind CSS (recommended)
├── CSS-in-JS
│   ├── Styled Components
│   └── Emotion
├── CSS Modules
│   └── CSS file per component
└── Traditional CSS
│   └── Plain CSS with variables

---

Stack Decision Template

When documenting stack decisions, use this format:

Backend Stack

Frontend Stack

Infrastructure

---

Selection Checklist

Before finalizing stack selection:

• Asked user about preferences?
• Checked for existing stack?
• Offered blueprint as option?
• Explained trade-offs of options?
• Documented rationale?
• Team expertise considered?
• Constraints considered?

---

Anti-Patterns

DON'T:

• Force a stack without asking user
• Assume "modern" = "best" for every project
• Ignore existing code/​stack
• Choose based on trends instead of requirements
• Skip trade-off explanations

DO:

• Always ask user preferences first
• Explain why you're recommending each option
• Consider team expertise and constraints
• Document rationale for decisions
• Offer blueprint as default, not mandate

---

Related Skills

---

Usage Examples

Example 1: New Project, No Preferences

User: "I want to build a web application for task management"

Process:

1. Ask: "Do you want to use the Fullstack Blueprint (React + FastAPI + SQLAlchemy)?"
2. If yes → Use blueprint stack
3. If no → Ask about preferences or suggest based on requirements

Example 2: Existing Project

User: "Add a new feature to the existing app"

Process:

1. Check existing stack (e.g., FastAPI + React)
2. Maintain consistency
3. Ask: "You're using FastAPI + React. Continue with that stack?"

Example 3: Migration

User: "I want to migrate to a different stack"

Process:

1. Understand motivation (performance, team expertise, etc.)
2. Suggest alternatives with trade-offs
3. Document migration plan

---

Remember: There's no "perfect" stack. The best stack is the one that fits the project requirements, team expertise, and constraints. Always involve the user in decisions.