feat: refactor framework to stack terminology across the application; update related data structures and templates

Author: spivx

README.md

@@ -6,13 +6,13 @@ Build high-signal agent and instruction files from community-proven best practic
 
 ## What devcontext does
 - Transforms curated community knowledge into ready-to-use instructions for agents, coding copilots, and repo guides.
-- Guides you through a multi-step wizard that selects files, frameworks, and scenario-specific topics.
+- Guides you through a multi-step wizard that selects files, stacks, and scenario-specific topics.
 - Surfaces examples, trade-offs, and documentation links so every choice is backed by trusted references.
 
 ## How the wizard works
 1. Launch the app and switch from the landing hero to the Instructions Wizard.
 2. Pick the instruction file you want to assemble (from templates defined in `data/files.json`).
-3. Choose your framework and automatically load its follow-up question set (dynamic imports from `data/questions/<framework>.json`).
+3. Choose your stack and automatically load its follow-up question set (dynamic imports from `data/questions/<stack>.json`).
 4. Answer topic prompts across general, architecture, performance, security, commits, and more—or lean on the recommended defaults when you need a fast decision.
 5. Review a completion summary that highlights what made it into your file and which areas still need decisions.
 
@@ -38,7 +38,7 @@ Then open the printed local URL in your browser to explore the wizard.
 
 ## Contribute back to the community
 - Add or improve topics in `data/*.json` with clear labels, examples, and `docs` links.
-- Propose new framework questionnaires under `data/questions/`, keeping the schema consistent.
+- Propose new stack questionnaires under `data/questions/`, keeping the schema consistent.
 - Share hooks, utilities, or UI refinements that make the wizard easier to reason about for first-time contributors.
 
 Every addition helps the community build better instruction files faster.

agents.md

@@ -8,8 +8,8 @@
 - Entry point at `app/page.tsx` toggles between a marketing hero and the instructions wizard.
 - Wizard steps currently cover:
   - Instructions file selection (`data/files.json`).
-  - Framework selection (`data/frameworks.json`) with branching into framework-specific question sets (e.g., `data/questions/react.json`).
-  - Dynamic question sets loaded via `import()` based on the chosen framework.
+  - Stack selection (`data/stacks.json`) with branching into stack-specific question sets (e.g., `data/questions/react.json`).
+  - Dynamic question sets loaded via `import()` based on the chosen stack.
 - User actions per question:
   - Select single or multiple answers, or apply the recommended default when unsure.
   - Review hover tooltips with examples, pros/cons, tags, and documentation links.
@@ -18,8 +18,8 @@
 ## Data Conventions
 - Every answer object may define: `value`, `label`, `icon`, `example`, `infoLines` (derived from `pros`/`cons`), `tags`, `isDefault`, `disabled`, `disabledLabel`, and `docs`.
 - JSON files in `data/` supply domain-specific options:
-  - `files.json`, `frameworks.json`, `general.json`, `architecture.json`, `performance.json`, `security.json`, `commits.json`.
-  - Framework-specific questionnaires live in `data/questions/<framework>.json`.
+  - `files.json`, `stacks.json`, `general.json`, `architecture.json`, `performance.json`, `security.json`, `commits.json`.
+  - Stack-specific questionnaires live in `data/questions/<stack>.json`.
 - Newly added `docs` fields should point to authoritative resources and are surfaced in tooltips as external links.
 
 ## Visual & Interaction Details (components/instructions-wizard.tsx)
@@ -31,7 +31,7 @@
 
 ## Extending the Wizard
 1. Add new answer sets to relevant JSON files with `docs` links when possible.
-2. For additional frameworks, create `data/questions/<framework>.json` and ensure the `docs` field on the framework entry is populated.
+2. For additional stacks, create `data/questions/<stack>.json` and ensure the `docs` field on the stack entry is populated.
 3. The wizard automatically consumes new questions when they follow the existing schema.
 
 ## Development Workflow

app/api/generate/[framework]/[fileName]/route.ts

@@ -31,15 +31,15 @@ export async function POST(
 
         const templateKeyFromParams: TemplateKey = {
             templateType: mapOutputFileToTemplateType(fileName),
-            framework: frameworkFromPath,
+            stack: frameworkFromPath,
         }
 
         let templateConfig = getTemplateConfig(templateKeyFromParams)
 
         if (!templateConfig && responses.outputFile) {
             const templateKeyFromBody: TemplateKey = {
                 templateType: mapOutputFileToTemplateType(responses.outputFile),
-                framework: responses.frameworkSelection || undefined,
+                stack: responses.stackSelection || undefined,
             }
 
             templateConfig = getTemplateConfig(templateKeyFromBody)
@@ -86,7 +86,7 @@ export async function POST(
             }
         }
 
-        replaceVariable('frameworkSelection')
+        replaceVariable('stackSelection')
         replaceVariable('tooling')
         replaceVariable('language')
         replaceVariable('projectPriority')

app/new/page.tsx

@@ -83,7 +83,7 @@ export default function NewInstructionsPage() {
                   </p>
                   <div className="mx-auto max-w-2xl text-left text-sm text-muted-foreground/90 md:text-base">
                     <ul className="list-disc space-y-2 pl-5">
-                      <li>Pick a preset to load framework, architecture, and workflow prompts.</li>
+                      <li>Pick a preset to load stack, architecture, and workflow prompts.</li>
                       <li>Answer or skip questions — you can revisit any step before exporting.</li>
                       <li>Download the generated file once every section shows as complete.</li>
                     </ul>

components/instructions-wizard.tsx

@@ -5,7 +5,7 @@ import { Button } from "@/components/ui/button"
 import { Undo2 } from "lucide-react"
 
 import type { DataQuestionSource, FileOutputConfig, InstructionsWizardProps, Responses, WizardAnswer, WizardConfirmationIntent, WizardQuestion, WizardStep } from "@/types/wizard"
-import frameworksData from "@/data/frameworks.json"
+import stacksData from "@/data/stacks.json"
 import generalData from "@/data/general.json"
 import architectureData from "@/data/architecture.json"
 import performanceData from "@/data/performance.json"
@@ -24,17 +24,17 @@ import { serializeWizardResponses } from "@/lib/wizard-response"
 import { buildFileOptionsFromQuestion, buildStepFromQuestionSet, getFormatLabel, mapAnswerSourceToWizard } from "@/lib/wizard-utils"
 import type { GeneratedFileResult } from "@/types/output"
 
-const FRAMEWORK_STEP_ID = "frameworks"
-const FRAMEWORK_QUESTION_ID = "frameworkSelection"
+const STACK_STEP_ID = "stacks"
+const STACK_QUESTION_ID = "stackSelection"
 const DEVCONTEXT_ROOT_URL = "https://devcontext.xyz/"
 
-const frameworkQuestionSet = frameworksData as DataQuestionSource[]
-const frameworksStep = buildStepFromQuestionSet(
-  FRAMEWORK_STEP_ID,
-  "Choose Your Framework",
-  frameworkQuestionSet
+const stackQuestionSet = stacksData as DataQuestionSource[]
+const stacksStep = buildStepFromQuestionSet(
+  STACK_STEP_ID,
+  "Choose Your Stack",
+  stackQuestionSet
 )
-const frameworkQuestion = frameworksStep.questions.find((question) => question.id === FRAMEWORK_QUESTION_ID) ?? null
+const stackQuestion = stacksStep.questions.find((question) => question.id === STACK_QUESTION_ID) ?? null
 
 const fileQuestionSet = filesData as DataQuestionSource[]
 const fileQuestion = fileQuestionSet[0] ?? null
@@ -98,7 +98,7 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
   const [pendingConfirmation, setPendingConfirmation] = useState<WizardConfirmationIntent | null>(null)
   const [generatedFile, setGeneratedFile] = useState<GeneratedFileResult | null>(null)
   const [isGenerating, setIsGenerating] = useState(false)
-  const [isFrameworkFastTrackPromptVisible, setIsFrameworkFastTrackPromptVisible] = useState(false)
+  const [isStackFastTrackPromptVisible, setIsStackFastTrackPromptVisible] = useState(false)
   const [autoFilledQuestionMap, setAutoFilledQuestionMap] = useState<Record<string, boolean>>({})
   const [autoFillNotice, setAutoFillNotice] = useState<string | null>(null)
   const [activeEditQuestionId, setActiveEditQuestionId] = useState<string | null>(null)
@@ -126,12 +126,12 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
   )
 
   const wizardSteps = useMemo(
-    () => [frameworksStep, ...dynamicSteps, ...suffixSteps],
+    () => [stacksStep, ...dynamicSteps, ...suffixSteps],
     [dynamicSteps]
   )
 
-  const nonFrameworkSteps = useMemo(
-    () => wizardSteps.filter((step) => step.id !== FRAMEWORK_STEP_ID),
+  const nonStackSteps = useMemo(
+    () => wizardSteps.filter((step) => step.id !== STACK_STEP_ID),
     [wizardSteps]
   )
 
@@ -159,8 +159,8 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
   )
 
   const remainingQuestionCount = useMemo(
-    () => nonFrameworkSteps.reduce((count, step) => count + step.questions.length, 0),
-    [nonFrameworkSteps]
+    () => nonStackSteps.reduce((count, step) => count + step.questions.length, 0),
+    [nonStackSteps]
   )
 
   const completionSummary = useMemo(
@@ -207,8 +207,8 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
     ? `Use default (${defaultAnswer.label})`
     : "Use default"
 
-  const showFrameworkPivot = !isComplete && isFrameworkFastTrackPromptVisible
-  const showQuestionControls = !isComplete && !isFrameworkFastTrackPromptVisible
+  const showStackPivot = !isComplete && isStackFastTrackPromptVisible
+  const showQuestionControls = !isComplete && !isStackFastTrackPromptVisible
 
   const markQuestionsAutoFilled = useCallback((questionIds: string[]) => {
     if (questionIds.length === 0) {
@@ -218,7 +218,7 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
     setAutoFilledQuestionMap((prev) => {
       const next = { ...prev }
       questionIds.forEach((id) => {
-        if (id !== FRAMEWORK_QUESTION_ID) {
+        if (id !== STACK_QUESTION_ID) {
           next[id] = true
         }
       })
@@ -273,8 +273,8 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
   }
 
   const goToPrevious = () => {
-    if (isFrameworkFastTrackPromptVisible) {
-      setIsFrameworkFastTrackPromptVisible(false)
+    if (isStackFastTrackPromptVisible) {
+      setIsStackFastTrackPromptVisible(false)
     }
 
     const isFirstQuestionInStep = currentQuestionIndex === 0
@@ -297,11 +297,11 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
     setIsComplete(false)
   }
 
-  const loadFrameworkQuestions = async (frameworkId: string, frameworkLabel?: string) => {
+  const loadStackQuestions = async (stackId: string, stackLabel?: string) => {
     try {
       setGeneratedFile(null)
 
-      const questionsModule = await import(`@/data/questions/${frameworkId}.json`)
+      const questionsModule = await import(`@/data/questions/${stackId}.json`)
       const questionsData = (questionsModule.default ?? questionsModule) as DataQuestionSource[]
 
       const mappedQuestions: WizardQuestion[] = questionsData.map((question) => ({
@@ -318,18 +318,18 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
       setAutoFilledQuestionMap({})
       setAutoFillNotice(null)
 
-      const resolvedFrameworkLabel =
-        frameworkLabel ?? frameworkQuestion?.answers.find((answer) => answer.value === frameworkId)?.label ?? frameworkId
+      const resolvedStackLabel =
+        stackLabel ?? stackQuestion?.answers.find((answer) => answer.value === stackId)?.label ?? stackId
 
       setDynamicSteps([
         {
-          id: `framework-${frameworkId}`,
-          title: `${resolvedFrameworkLabel} Preferences`,
+          id: `stack-${stackId}`,
+          title: `${resolvedStackLabel} Preferences`,
           questions: mappedQuestions,
         },
       ])
 
-      setIsFrameworkFastTrackPromptVisible(followUpQuestionCount > 0)
+      setIsStackFastTrackPromptVisible(followUpQuestionCount > 0)
 
       setResponses((prev) => {
         const next = { ...prev }
@@ -343,9 +343,9 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
       setCurrentQuestionIndex(0)
       setIsComplete(false)
     } catch (error) {
-      console.error(`Unable to load questions for framework "${frameworkId}"`, error)
+      console.error(`Unable to load questions for stack "${stackId}"`, error)
       setDynamicSteps([])
-      setIsFrameworkFastTrackPromptVisible(false)
+      setIsStackFastTrackPromptVisible(false)
     } finally {
     }
   }
@@ -361,7 +361,7 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
 
       wizardSteps.forEach((step) => {
         step.questions.forEach((question) => {
-          if (question.id === FRAMEWORK_QUESTION_ID) {
+          if (question.id === STACK_QUESTION_ID) {
             return
           }
 
@@ -390,7 +390,7 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
       setAutoFillNotice(null)
     }
 
-    setIsFrameworkFastTrackPromptVisible(false)
+    setIsStackFastTrackPromptVisible(false)
 
     const lastStepIndex = Math.max(wizardSteps.length - 1, 0)
     const lastStep = wizardSteps[lastStepIndex]
@@ -402,14 +402,14 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
   }
 
   const beginStepByStepFlow = () => {
-    const firstNonFrameworkIndex = wizardSteps.findIndex((step) => step.id !== FRAMEWORK_STEP_ID)
+    const firstNonStackIndex = wizardSteps.findIndex((step) => step.id !== STACK_STEP_ID)
 
-    if (firstNonFrameworkIndex !== -1) {
-      setCurrentStepIndex(firstNonFrameworkIndex)
+    if (firstNonStackIndex !== -1) {
+      setCurrentStepIndex(firstNonStackIndex)
       setCurrentQuestionIndex(0)
     }
 
-    setIsFrameworkFastTrackPromptVisible(false)
+    setIsStackFastTrackPromptVisible(false)
     setIsComplete(false)
     setAutoFillNotice(null)
   }
@@ -471,11 +471,11 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
 
     clearAutoFilledFlag(question.id)
 
-    const isFrameworkQuestion = question.id === FRAMEWORK_QUESTION_ID
+    const isStackQuestion = question.id === STACK_QUESTION_ID
 
     const shouldAutoAdvance =
       !skipAutoAdvance &&
-      !isFrameworkQuestion &&
+      !isStackQuestion &&
       ((question.allowMultiple && Array.isArray(nextValue) && nextValue.length > 0 && didAddSelection) ||
         (!question.allowMultiple && nextValue !== undefined && nextValue !== null && didAddSelection))
 
@@ -485,12 +485,12 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
       }, 0)
     }
 
-    if (isFrameworkQuestion) {
+    if (isStackQuestion) {
       if (nextValue === answer.value) {
-        await loadFrameworkQuestions(answer.value, answer.label)
+        await loadStackQuestions(answer.value, answer.label)
       } else {
         setDynamicSteps([])
-        setIsFrameworkFastTrackPromptVisible(false)
+        setIsStackFastTrackPromptVisible(false)
       }
     }
   }
@@ -521,10 +521,10 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
 
     clearAutoFilledFlag(currentQuestion.id)
 
-    const isFrameworkQuestion = currentQuestion.id === FRAMEWORK_QUESTION_ID
+    const isStackQuestion = currentQuestion.id === STACK_QUESTION_ID
 
-    if (isFrameworkQuestion) {
-      await loadFrameworkQuestions(defaultAnswer.value, defaultAnswer.label)
+    if (isStackQuestion) {
+      await loadStackQuestions(defaultAnswer.value, defaultAnswer.label)
       return
     }
 
@@ -540,7 +540,7 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
     setIsComplete(false)
     setGeneratedFile(null)
     setIsGenerating(false)
-    setIsFrameworkFastTrackPromptVisible(false)
+    setIsStackFastTrackPromptVisible(false)
     setAutoFilledQuestionMap({})
     setAutoFillNotice(null)
   }
@@ -609,14 +609,14 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
 
       console.log("Template combination data:", {
         outputFile: questionsAndAnswers.outputFile,
-        framework: questionsAndAnswers.frameworkSelection,
+        stack: questionsAndAnswers.stackSelection,
       })
 
-      const frameworkSegment = questionsAndAnswers.frameworkSelection ?? "general"
+      const stackSegment = questionsAndAnswers.stackSelection ?? "general"
       const fileConfig = fileOptions.find((file) => file.id === outputFileId)
 
       const result = await generateInstructions({
-        frameworkSegment,
+        stackSegment,
         outputFileId,
         responses: questionsAndAnswers,
         fileFormat: fileConfig?.format,
@@ -651,8 +651,8 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
     : undefined
   const showChangeFile = Boolean(onClose && selectedFile)
 
-  const topButtonLabel = showFrameworkPivot ? "Choose a different network" : "Start Over"
-  const topButtonHandler = showFrameworkPivot ? () => goToPrevious() : () => requestResetWizard()
+  const topButtonLabel = showStackPivot ? "Choose a different stack" : "Start Over"
+  const topButtonHandler = showStackPivot ? () => goToPrevious() : () => requestResetWizard()
 
   const wizardLayout = (
     <div className="mx-auto flex w-full max-w-4xl flex-col gap-6">
@@ -682,7 +682,7 @@ export function InstructionsWizard({ onClose, selectedFileId }: InstructionsWiza
         </section>
       ) : null}
 
-      {showFrameworkPivot ? (
+      {showStackPivot ? (
         <section className="rounded-3xl border border-border/80 bg-card/95 p-6 shadow-lg">
           <div className="flex flex-col gap-6">
             <div className="space-y-4">

data/frameworks.json data/stacks.jsondata/frameworks.json renamed to data/stacks.json

@@ -1,8 +1,8 @@
 [
     {
-        "id": "frameworkSelection",
-        "question": "Which framework are you working with?",
-        "responseKey": "frameworkSelection",
+        "id": "stackSelection",
+        "question": "Which stack are you working with?",
+        "responseKey": "stackSelection",
         "isReadOnlyOnSummary": true,
         "answers": [
             {
@@ -26,4 +26,4 @@
             }
         ]
     }
-]
+]

file-templates/agents-template.md

@@ -6,7 +6,7 @@ This guide provides conventions and best practices for building AI agent applica
 
 ## 1. Project Overview
 
-- Framework/Language: **{{frameworkSelection}}** / **{{language}}**
+- Stack/Language: **{{stackSelection}}** / **{{language}}**
 - Build tooling: **{{tooling}}**
 - Primary focus: **{{projectPriority}}**