Tech Stack Recommendations

{
  "kind": "clarification",
  "clarifying_question": "Do users need to log in and save their data, or is this a single-user tool?",
  "stack": null
}

{
  "kind": "stack",
  "clarifying_question": null,
  "stack": {
    "summary": "Real-time chat with user accounts and message history",
    "dev_tool": "Cursor (Plan Mode)",
    "core_tools": [
      {
        "name": "Supabase",
        "category": "database",
        "reason": "Real-time subscriptions and auth built-in for chat features"
      },
      {
        "name": "Vercel",
        "category": "deployment",
        "reason": "Deploy instantly from your AI agent's git commits"
      }
    ],
    "optional_later": [
      {
        "name": "OpenAI API",
        "category": "api",
        "reason": "Add AI-powered message suggestions or moderation"
      }
    ],
    "setup_note": "Open Cursor, describe your chat app, and ask it to scaffold a Next.js + Supabase project. Use Supabase dashboard to configure auth."
  }
}

'- Prefer planning-centric AI coding tools such as Cursor (Plan Mode), Claude Code, or Codex-style web agents.'
'- Default to these planning tools when in doubt, so the user builds a planning habit.'
'- Only choose a different dev tool when the user clearly wants something else (for example a no-/low-code visual builder).'
'- Never recommend bare frameworks such as "use React" or "use Spring Boot" as the primary dev_tool.'

function getSuggestStackToolList(): GuideToolSummary[] {
  return sections.flatMap((section) =>
    section.tools.map((tool) => ({
      name: tool.name,
      category: getSectionCategory(section.title),
      tagline: tool.tagline,
    }))
  )
}

function formatSuggestStackMarkdown(stack: SuggestStackStack): string {
  const lines: string[] = [stack.summary, '']
  lines.push(
    '- Start with a planning tool: Cursor (local repo & deep code work), ' +
    'Claude Code (browser-based multi-file editing), Codex web (fast experiments). ' +
    `For you, **${stack.dev_tool}** is a good default choice.`
  )
  for (const t of stack.core_tools) {
    lines.push(`- **${t.name}** (${t.category}): ${t.reason}`)
  }
  if (stack.optional_later.length > 0) {
    const later = stack.optional_later.map((t) => `${t.name} for ${t.reason}`).join('; ')
    lines.push(`- Later if needed: ${later}`)
  }
  lines.push(`- To get started: ${stack.setup_note}`)
  return lines.join('\n')
}

function buildSuggestStackFallbackResponse(latestUserMessage: string): string {
  const ranked = rankGuideToolsByQuery(latestUserMessage, 5)
  const devTool = ranked.find((t) => t.category === 'development') ?? ranked[0]
  if (!devTool) {
    return [
      'Start with your preferred AI dev tool and ask it to build a minimal version of your idea.',
      '- Open Cursor, Codex, or Replit and describe what you want to build.',
      '- Keep the first version to one core flow; add more after it works.',
    ].join('\n')
  }
  return [
    `Keep the first version lean. Start with **${devTool.name}** – ${devTool.tagline}.`,
    `- Open ${devTool.name} and ask it to build a minimal version of your idea.`,
    '- Use the agent for everything; no need to write code yourself.',
    '- Add a database or auth later only if you need saved data or user accounts.',
  ].join('\n')
}

export function rankGuideToolsByQuery(query: string, limit = 20): GuideTool[] {
  const queryNormalized = normalizeText(query)
  const queryTokens = tokenize(query)

  const scored = GUIDE_TOOLS.map((tool, index) => {
    let score = 0

    // Exact name match
    if (queryNormalized.includes(tool.normalizedName)) {
      score += 10
    }

    // Token matches in name
    for (const token of queryTokens) {
      if (tool.normalizedName.includes(token)) {
        score += 3
      }
      // Token matches in search text (description, bullets, etc.)
      if (tool.searchText.includes(token)) {
        score += 1
      }
    }

    return { tool, score, index }
  })

  // Sort by score, then by original index
  const ranked = scored.sort((a, b) => {
    if (b.score !== a.score) return b.score - a.score
    return a.index - b.index
  }).map((entry) => entry.tool)

  return ranked.slice(0, limit)
}

POST /api/chat
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "I want to build a recipe sharing app" }
  ],
  "mode": "suggest-stack"
}

{
  "id": "chatcmpl-clarify",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Do users need accounts to share recipes, or is it a public feed anyone can post to?"
      }
    }
  ]
}