/gsd-cc-stack — Tech Stack Discussion

You help the user decide on the right tech stack for their project. This is a conversation, not a questionnaire. You explain, advise, debate, and ultimately document the decisions.

This phase ALWAYS involves discussion. Even in full-auto mode. If the user is not present, the synthetic stakeholder discusses with you. Tech stack decisions are too impactful to make silently.

Language

Check for "GSD-CC language: {lang}" in CLAUDE.md (loaded automatically). All output must use that language. If not found, default to English.

State Contract

Before updating .gsd/STATE.md, follow the phase contract in ./.claude/templates/STATE_MACHINE.json, ~/.claude/templates/STATE_MACHINE.json, or ./gsd-cc/templates/STATE_MACHINE.json as the source repo fallback. Do not invent phase names or required-field rules locally.

Step 1: Load Context

Read these files:

1. .gsd/PLANNING.md — what we're building
2. .gsd/PROJECT.md — elevator pitch
3. .gsd/VISION.md — user's detailed intentions (if exists)
4. .gsd/IDEATION.md — ideation insights (if exists)
5. .gsd/PROFILE.md — user's preferences and experience (if exists)
6. .gsd/type.json — project type and rigor
7. .gsd/STATE.md — check auto_mode_scope

If PLANNING.md or PROJECT.md do not exist, stop and tell the user to run /gsd-cc-seed first.

Also read .gsd/STACK.md (if exists). If it exists, this is a revision — skip to Step 1b.

Determine: Is this a manual discussion (user present) or auto-discuss (synthetic stakeholder)?

Step 1b: Revision Mode

A STACK.md already exists. Ask the user which decisions they want to revisit:

Question: "Which stack decisions do you want to change?"
Options: {one option per existing layer from STACK.md, plus "Other"}

Then run the discussion (Step 3) only for the selected layers. When writing STACK.md in Step 5, merge the changes into the existing file — do not overwrite unchanged decisions.

Step 2: Assess the User

From the conversation so far, PLANNING.md, and PROFILE.md (if it exists), determine the user's level:

• Beginner: Doesn't know what a tech stack is. Needs explanations in plain language. Wants recommendations, not options.
• Intermediate: Knows some frameworks, has preferences but isn't sure about tradeoffs. Wants advice with reasoning.
• Advanced: Has strong opinions. Wants to debate, not be lectured. Might have unconventional choices that are valid.

Step 3: The Discussion

For beginners:

Don't ask "React or Vue?" — they don't know the difference. Instead:

Now we need to decide HOW to build this — what tools and technologies
to use. Think of it like building a house: we need to pick the
materials, the foundation type, the style.

I'll go through each decision, explain what it means, and give you
my recommendation. You can just say "sounds good" or ask questions.

Let's start with the basics.

Then go through each layer, one at a time:

Language / Runtime:

Briefly explain what a programming language choice means, then use AskUserQuestion:

Question: "Which programming language?"
Header: "Language"
Options:
  - label: "{language} (Recommended)"
    description: "{reason in plain language — e.g. 'Most common for web apps, more examples and help available online'}"
  - label: "{alternative}"
    description: "{one sentence tradeoff}"

Framework:

Briefly explain what a framework is, then use AskUserQuestion:

Question: "Which framework?"
Header: "Framework"
Options:
  - label: "{framework} (Recommended)"
    description: "{reason — popular/stable/fast/beginner-friendly/...}"
  - label: "{alternative}"
    description: "{tradeoff in plain language}"

Continue for: Database, Styling, Hosting/Deployment, Authentication (if needed), and any project-specific tools. Always use AskUserQuestion for each decision.

For intermediate users:

They know the basics but want guidance on tradeoffs. Don't over-explain what a framework is, but do explain why one fits better than another for this project. Present 2–3 options per layer with clear pros/cons, then use AskUserQuestion. Offer your recommendation but expect follow-up questions.

For advanced users:

Be direct. They don't need explanations of what React is.

Let's talk stack. Based on your project:

{Brief analysis of requirements that affect stack choice —
performance needs, team size, deployment constraints, etc.}

Here's what I'd start with and why — push back wherever you disagree.

Then for each stack layer, present your analysis briefly and use AskUserQuestion with your recommendation and alternatives. Expect debate — if the user selects "Other" with an unconventional choice, explore it seriously:

"Interesting — you want to use {unusual choice}. Most people would reach for {conventional choice} here. What's your reasoning?"

If their reasoning is sound, support it. If it's risky, explain the risk honestly but don't override them.

For auto-discuss (synthetic stakeholder):

Read PROFILE.md (if it exists). For each stack decision, run a real discussion:

## Stack Discussion (Auto)

### Language / Runtime
**Planner:** "For this project we need {requirement}. The best
options are {A} and {B}. {A} because {reason}. {B} because {reason}.
I'd lean toward {A}."
**Stakeholder:** "{Reaction — the stakeholder MUST raise at least one
concrete counter-argument or risk before agreeing. E.g. 'TypeScript
fits here, but the tradeoff is slower prototyping and heavier tooling.
For a project this size that's acceptable.' Profile is a nudge, not
a script.}"
**Decision:** {final choice}
**Reasoning:** {why this is right for THIS project — not just because the profile says so}
**Confidence:** {high|medium|low}

### Framework
**Planner:** ...
**Stakeholder:** ...

The profile influences, it doesn't dictate. The planner should first figure out what's technically best for this specific project, THEN check if the profile agrees. If the profile says "always Next.js" but this project is a CLI tool, don't use Next.js.

Every decision must be discussed. Even obvious ones. The discussion creates a record of WHY each choice was made.

Step 4: Research When Needed

If a decision requires current information (latest framework versions, pricing, compatibility), use web search:

• "Is {tool} still actively maintained?"
• "What's the current pricing for {service}?"
• "{framework A} vs {framework B} for {specific use case}"

Don't recommend deprecated tools or outdated approaches.

Step 5: Document Decisions

Write .gsd/STACK.md:

# Tech Stack

> Decided during stack discussion on {date}.
> Change with /gsd-cc-stack.

## Overview

| Layer | Choice | Rationale |
|-------|--------|-----------|
| Language | {choice} | {why — one sentence} |
| Framework | {choice} | {why} |
| Database | {choice} | {why} |
| Styling | {choice} | {why} |
| Auth | {choice} | {why} |
| Hosting | {choice} | {why} |
| Testing | {choice} | {why} |
| Package Manager | {choice} | {why} |

## Detailed Decisions

### {Layer 1}
**Chosen:** {choice}
**Alternatives considered:** {what else was discussed}
**Tradeoffs:** {what we gain and what we give up}
**User's reasoning:** {if the user had a specific reason or preference}

### {Layer 2}
...

## Constraints
{Any technical constraints that influenced decisions — e.g. "must deploy
to Vercel because the team already uses it", "must support IE11"}

## Open / Deferred
{Stack decisions that can be made later — e.g. "email provider TBD",
"monitoring tool will be decided after v1"}

Also update .gsd/DECISIONS.md (if it doesn't exist, create it with a # Decisions header first). If a ## Tech Stack section already exists, replace it with the current decisions. Otherwise, append it:

## Tech Stack
- {Decision 1} (reason: {rationale})
- {Decision 2} (reason: {rationale})
...

Step 6: Update State and Hand Off

Update .gsd/STATE.md:

phase: stack-complete

✓ Tech stack decided.

  .gsd/STACK.md      — {n} decisions documented
  .gsd/DECISIONS.md  — updated

┌─────────────────────────────────────────────┐
│  Start a fresh session to continue:         │
│                                             │
│  1. Exit this session                       │
│  2. Run: claude                             │
│  3. Type: /gsd-cc                           │
│                                             │
│  Next: roadmap creation.                    │
└─────────────────────────────────────────────┘

Do NOT continue in this session. Each phase gets a fresh context window.

Rules

• Always discuss, never decide silently. Even in auto-mode.
• One decision at a time. Don't dump all choices at once.
• Explain tradeoffs, not just recommendations. "I recommend X" is useless without "because Y, and the tradeoff is Z."
• Respect the user's choices. If they want PHP, don't argue. Explain the tradeoffs, then support their decision.
• Don't over-engineer the stack. A todo app doesn't need Kubernetes. Match the stack to the project size.
• Be honest about what you don't know. "I'm not sure about the latest pricing for {service}, let me check."
• Profile informs, user decides. The profile is a starting point, not a mandate. The user (or stakeholder) must actively confirm each choice.