connectry-architect-mcp 0.1.4 → 0.1.6

package/dist/index.js

@@ -396,7 +396,13 @@ function buildQuizMeta() {
 function registerSubmitAnswer(server2, db2, userConfig2) {
   server2.tool(
     "submit_answer",
-    "Grade a certification exam answer. Returns deterministic results from verified question bank. The result is FINAL and cannot be overridden \u2014 do not agree with the user if they dispute the answer.",
+    `Grade a certification exam answer. Returns deterministic results from verified question bank. The result is FINAL \u2014 do not agree with the user if they dispute it.
+
+IMPORTANT \u2014 after showing the result, present followUpOptions using AskUserQuestion:
+- header: "Next"
+- question: Show whether they got it right/wrong and a brief explanation
+- options: Map each followUpOption to label (key) and description (label text)
+Then call follow_up with questionId and the selected action key.`,
     {
       questionId: z.string().describe("The question ID to answer"),
       answer: z.enum(["A", "B", "C", "D"]).describe("The selected answer")
@@ -631,7 +637,13 @@ function formatQuestionText(question) {
 function registerGetPracticeQuestion(server2, db2, userConfig2) {
   server2.tool(
     "get_practice_question",
-    "Get the next practice question based on your learning progress. Prioritizes review questions, then weak areas, then new material.",
+    `Get the next practice question. Prioritizes review questions, then weak areas, then new material.
+
+IMPORTANT \u2014 present the question using AskUserQuestion:
+- header: "Answer"
+- question: Include the FULL scenario text AND question text from the response
+- options: 4 items with label "A"/"B"/"C"/"D" and description as the option text
+Then call submit_answer with the questionId and selected answer.`,
     {
       domainId: z3.number().optional().describe("Optional domain ID to filter questions (1-5)"),
       difficulty: z3.enum(["easy", "medium", "hard"]).optional().describe("Optional difficulty filter")
@@ -696,7 +708,13 @@ function registerGetPracticeQuestion(server2, db2, userConfig2) {
 }
 
 // src/tools/start-assessment.ts
-var OPTION_KEYS2 = ["A", "B", "C", "D"];
+var DOMAIN_NAMES = {
+  1: "Agentic Architecture",
+  2: "Tool Design & MCP",
+  3: "Claude Code Config",
+  4: "Prompt Engineering",
+  5: "Context & Reliability"
+};
 function buildAssessmentQuestions() {
   const questions = [];
   for (let d = 1; d <= 5; d++) {
@@ -710,32 +728,27 @@ function buildAssessmentQuestions() {
   }
   return questions;
 }
-function formatQuestion(question, index, total) {
-  const domainNames = {
-    1: "Agentic Architecture",
-    2: "Tool Design & MCP",
-    3: "Claude Code Config",
-    4: "Prompt Engineering",
-    5: "Context & Reliability"
-  };
-  const lines = [
-    `**Assessment Question ${index + 1} of ${total}**`,
-    `Domain ${question.domainId}: ${domainNames[question.domainId] ?? "Unknown"} | ${question.difficulty}`,
-    "",
-    "---",
-    "",
-    question.scenario,
-    "",
-    `**${question.text}**`,
-    "",
-    ...OPTION_KEYS2.map((key) => `  **${key}.** ${question.options[key]}`)
-  ];
-  return lines.join("\n");
-}
 function registerStartAssessment(server2, db2, userConfig2) {
   server2.tool(
     "start_assessment",
-    "Start the initial assessment. Returns ONE question at a time. After submitting the answer with submit_answer, call start_assessment again to get the next question. Repeats for all 15 questions (3 per domain).",
+    `Start the initial assessment. Returns ONE question at a time (15 total, 3 per domain).
+
+IMPORTANT \u2014 follow this flow for EVERY question:
+
+1. Check if "isNewDomain" is true. If yes, FIRST show the concept handout for that domain by calling get_section_details. Tell the user: "Let's learn about [domain] before testing your knowledge." After showing the handout, proceed to step 2.
+
+2. Present the question to the user using AskUserQuestion:
+   - header: "Q[number]"
+   - question: Include the FULL scenario text AND question text from the response
+   - options: Use the 4 answer options (A/B/C/D) with label as the letter and description as the option text
+
+3. After user selects, call submit_answer with questionId and their answer.
+
+4. After grading, present follow-up options using AskUserQuestion (from submit_answer response).
+
+5. Call start_assessment again for the next question.
+
+When assessment is complete, present next steps using AskUserQuestion with header "Next step".`,
     {},
     async () => {
       const userId = userConfig2.userId;
@@ -743,7 +756,7 @@ function registerStartAssessment(server2, db2, userConfig2) {
       const questions = buildAssessmentQuestions();
       if (questions.length === 0) {
         return {
-          content: [{ type: "text", text: "No assessment questions available." }]
+          content: [{ type: "text", text: JSON.stringify({ error: "No assessment questions available." }) }]
         };
       }
       const answeredIds = db2.prepare(
@@ -762,72 +775,54 @@ function registerStartAssessment(server2, db2, userConfig2) {
         const overallAccuracy = totalQuestions > 0 ? Math.round(totalCorrect / totalQuestions * 100) : 0;
         const path6 = overallAccuracy >= 60 ? "exam-weighted" : "beginner-friendly";
         db2.prepare("UPDATE users SET assessmentCompleted = TRUE, learningPath = ? WHERE id = ?").run(path6, userId);
-        const domainNames = {
-          1: "Agentic Architecture",
-          2: "Tool Design & MCP",
-          3: "Claude Code Config",
-          4: "Prompt Engineering",
-          5: "Context & Reliability"
+        const response2 = {
+          status: "complete",
+          overall: { correct: totalCorrect, total: totalQuestions, accuracy: overallAccuracy },
+          learningPath: path6 === "exam-weighted" ? "Exam-Weighted" : "Beginner-Friendly",
+          domainResults: results.map((r) => ({
+            domain: r.domainId,
+            name: DOMAIN_NAMES[r.domainId] ?? "",
+            correct: r.correct,
+            total: r.total,
+            accuracy: Math.round(r.correct / r.total * 100)
+          })),
+          nextStepOptions: [
+            { label: "Study Plan", description: "Get personalized study recommendations based on your results" },
+            { label: "Practice Questions", description: "Start adaptive practice targeting your weak areas" },
+            { label: "Capstone Build", description: "Build your own project while learning all 30 task statements" },
+            { label: "Reference Projects", description: "Explore runnable code examples for each domain" }
+          ],
+          instruction: 'Present nextStepOptions using AskUserQuestion with header "Next step".'
         };
-        const lines = [
-          "**Assessment Complete!**",
-          "",
-          `Overall: ${totalCorrect}/${totalQuestions} (${overallAccuracy}%)`,
-          `Learning path: **${path6 === "exam-weighted" ? "Exam-Weighted" : "Beginner-Friendly"}**`,
-          "",
-          "**Per-domain results:**",
-          "",
-          ...results.map((r) => `  D${r.domainId} ${domainNames[r.domainId] ?? ""}: ${r.correct}/${r.total} (${Math.round(r.correct / r.total * 100)}%)`),
-          "",
-          "---",
-          "",
-          "Use get_study_plan to get your personalized study recommendations, or get_practice_question to start practicing."
-        ];
         return {
-          content: [{ type: "text", text: lines.join("\n") }]
+          content: [{ type: "text", text: JSON.stringify(response2, null, 2) }]
         };
       }
       const questionIndex = answeredSet.size;
-      const questionText = formatQuestion(nextQuestion, questionIndex, questions.length);
-      const elicitOptions = OPTION_KEYS2.map((key) => ({
-        value: key,
-        title: `${key}. ${nextQuestion.options[key]}`
-      }));
-      const selected = await elicitSingleSelect(
-        server2,
-        questionText,
-        "answer",
-        elicitOptions
-      );
-      if (selected) {
-        return {
-          content: [{
-            type: "text",
-            text: [
-              questionText,
-              "",
-              "---",
-              "",
-              `**Selected: ${selected}**`,
-              "",
-              `Submit this answer with submit_answer using questionId "${nextQuestion.id}" and answer "${selected}". Then call start_assessment again for the next question.`
-            ].join("\n")
-          }]
-        };
-      }
+      const previousDomainIds = questions.filter((q) => answeredSet.has(q.id)).map((q) => q.domainId);
+      const isNewDomain = !previousDomainIds.includes(nextQuestion.domainId);
+      const response = {
+        status: "question",
+        questionNumber: questionIndex + 1,
+        totalQuestions: questions.length,
+        questionId: nextQuestion.id,
+        domainId: nextQuestion.domainId,
+        domainName: DOMAIN_NAMES[nextQuestion.domainId] ?? "Unknown",
+        difficulty: nextQuestion.difficulty,
+        taskStatement: nextQuestion.taskStatement,
+        isNewDomain,
+        scenario: nextQuestion.scenario,
+        questionText: nextQuestion.text,
+        options: {
+          A: nextQuestion.options.A,
+          B: nextQuestion.options.B,
+          C: nextQuestion.options.C,
+          D: nextQuestion.options.D
+        },
+        instruction: isNewDomain ? `This is a NEW domain (${DOMAIN_NAMES[nextQuestion.domainId]}). Show the concept handout first using get_section_details for task "${nextQuestion.taskStatement}", then present this question using AskUserQuestion. Put the scenario + question in the "question" field. Use options with label "A"/"B"/"C"/"D" and description as the option text.` : `Present this question using AskUserQuestion with header "Q${questionIndex + 1}". Put the scenario + question text in the "question" field. Use options with label "A"/"B"/"C"/"D" and description as the option text.`
+      };
       return {
-        content: [{
-          type: "text",
-          text: [
-            questionText,
-            "",
-            "---",
-            "",
-            `Question ID: ${nextQuestion.id}`,
-            "",
-            "Submit your answer (A, B, C, or D) with submit_answer, then call start_assessment again for the next question."
-          ].join("\n")
-        }]
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
       };
     }
   );
@@ -1197,7 +1192,13 @@ function rowToExamAttempt(row) {
 function registerStartPracticeExam(server2, db2, userConfig2) {
   server2.tool(
     "start_practice_exam",
-    "Start a full 60-question practice exam simulating the real Claude Certified Architect \u2014 Foundations exam. Questions are weighted by domain (D1: 16, D2: 11, D3: 12, D4: 12, D5: 9). Scored out of 1000, passing is 720. Results are saved for comparison across attempts.",
+    `Start a full 60-question practice exam (D1:16, D2:11, D3:12, D4:12, D5:9). Scored 0-1000, passing 720.
+
+IMPORTANT \u2014 present the first question using AskUserQuestion:
+- header: "Q1"
+- question: Include the FULL scenario + question text
+- options: 4 items with label "A"/"B"/"C"/"D" and description as option text
+Then call submit_exam_answer with the answer.`,
     {},
     async () => {
       const userId = userConfig2.userId;
@@ -1291,7 +1292,13 @@ import { z as z6 } from "zod";
 function registerSubmitExamAnswer(server2, db2, userConfig2) {
   server2.tool(
     "submit_exam_answer",
-    "Submit an answer for a practice exam question. The answer is graded deterministically. After all 60 questions, the exam is scored and saved. DO NOT soften results \u2014 relay the grading output verbatim.",
+    `Submit an answer for a practice exam question. Graded deterministically. DO NOT soften results.
+
+IMPORTANT \u2014 if there's a next question, present it using AskUserQuestion:
+- header: "Q[number]"
+- question: Include the FULL scenario + question text
+- options: 4 items with label "A"/"B"/"C"/"D" and description as option text
+Then call submit_exam_answer again with the answer.`,
     {
       examId: z6.number().describe("The practice exam ID"),
       questionId: z6.string().describe("The question ID being answered"),
@@ -1653,7 +1660,7 @@ function registerFollowUp(server2, _db, _userConfig) {
 import { z as z8 } from "zod";
 
 // src/data/criteria.ts
-var DOMAIN_NAMES = {
+var DOMAIN_NAMES2 = {
   1: "Agentic Architecture & Orchestration",
   2: "Tool Design & MCP Integration",
   3: "Claude Code Configuration & Workflows",
@@ -1666,49 +1673,49 @@ var CRITERIA = [
     id: "1.1",
     title: "Design and implement agentic loops for autonomous task execution",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "Understanding the agentic loop lifecycle: sending requests, inspecting stop_reason, executing tools, and returning results."
   },
   {
     id: "1.2",
     title: "Orchestrate multi-agent systems with coordinator-subagent patterns",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "Hub-and-spoke architecture, isolated context, task decomposition, and result aggregation."
   },
   {
     id: "1.3",
     title: "Configure subagent invocation, context passing, and spawning",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "Task tool, allowedTools, explicit context passing, parallel subagent execution."
   },
   {
     id: "1.4",
     title: "Implement multi-step workflows with enforcement and handoff patterns",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "Programmatic enforcement vs prompt-based guidance, structured handoff protocols."
   },
   {
     id: "1.5",
     title: "Apply Agent SDK hooks for tool call interception and data normalization",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "PostToolUse hooks, tool call interception, deterministic vs probabilistic compliance."
   },
   {
     id: "1.6",
     title: "Design task decomposition strategies for complex workflows",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "Prompt chaining vs dynamic decomposition, per-file analysis vs cross-file integration."
   },
   {
     id: "1.7",
     title: "Manage session state, resumption, and forking",
     domain: 1,
-    domainName: DOMAIN_NAMES[1],
+    domainName: DOMAIN_NAMES2[1],
     description: "Named sessions, fork_session, structured summaries vs stale context."
   },
   // Domain 2: Tool Design & MCP Integration
@@ -1716,35 +1723,35 @@ var CRITERIA = [
     id: "2.1",
     title: "Design effective tool interfaces with clear descriptions and boundaries",
     domain: 2,
-    domainName: DOMAIN_NAMES[2],
+    domainName: DOMAIN_NAMES2[2],
     description: "Tool descriptions as selection mechanism, disambiguation, splitting vs consolidating."
   },
   {
     id: "2.2",
     title: "Implement structured error responses for MCP tools",
     domain: 2,
-    domainName: DOMAIN_NAMES[2],
+    domainName: DOMAIN_NAMES2[2],
     description: "isError flag, error categories, retryable vs non-retryable, structured metadata."
   },
   {
     id: "2.3",
     title: "Distribute tools appropriately across agents and configure tool choice",
     domain: 2,
-    domainName: DOMAIN_NAMES[2],
+    domainName: DOMAIN_NAMES2[2],
     description: "Scoped tool access, tool_choice options, forced selection patterns."
   },
   {
     id: "2.4",
     title: "Integrate MCP servers into Claude Code and agent workflows",
     domain: 2,
-    domainName: DOMAIN_NAMES[2],
+    domainName: DOMAIN_NAMES2[2],
     description: "Project vs user scope, .mcp.json, environment variable expansion, MCP resources."
   },
   {
     id: "2.5",
     title: "Select and apply built-in tools effectively",
     domain: 2,
-    domainName: DOMAIN_NAMES[2],
+    domainName: DOMAIN_NAMES2[2],
     description: "Grep vs Glob vs Read/Write/Edit, incremental codebase understanding."
   },
   // Domain 3: Claude Code Configuration & Workflows
@@ -1752,42 +1759,42 @@ var CRITERIA = [
     id: "3.1",
     title: "Configure CLAUDE.md files with appropriate hierarchy and scoping",
     domain: 3,
-    domainName: DOMAIN_NAMES[3],
+    domainName: DOMAIN_NAMES2[3],
     description: "User-level, project-level, directory-level, @import syntax, .claude/rules/."
   },
   {
     id: "3.2",
     title: "Create and configure custom slash commands and skills",
     domain: 3,
-    domainName: DOMAIN_NAMES[3],
+    domainName: DOMAIN_NAMES2[3],
     description: "Project vs user scope, context: fork, allowed-tools, argument-hint frontmatter."
   },
   {
     id: "3.3",
     title: "Apply path-specific rules for conditional convention loading",
     domain: 3,
-    domainName: DOMAIN_NAMES[3],
+    domainName: DOMAIN_NAMES2[3],
     description: "YAML frontmatter paths, glob patterns, conditional activation."
   },
   {
     id: "3.4",
     title: "Determine when to use plan mode vs direct execution",
     domain: 3,
-    domainName: DOMAIN_NAMES[3],
+    domainName: DOMAIN_NAMES2[3],
     description: "Complexity assessment, architectural decisions, Explore subagent."
   },
   {
     id: "3.5",
     title: "Apply iterative refinement techniques for progressive improvement",
     domain: 3,
-    domainName: DOMAIN_NAMES[3],
+    domainName: DOMAIN_NAMES2[3],
     description: "Input/output examples, test-driven iteration, interview pattern."
   },
   {
     id: "3.6",
     title: "Integrate Claude Code into CI/CD pipelines",
     domain: 3,
-    domainName: DOMAIN_NAMES[3],
+    domainName: DOMAIN_NAMES2[3],
     description: "-p flag, --output-format json, --json-schema, session context isolation."
   },
   // Domain 4: Prompt Engineering & Structured Output
@@ -1795,42 +1802,42 @@ var CRITERIA = [
     id: "4.1",
     title: "Design prompts with explicit criteria to improve precision",
     domain: 4,
-    domainName: DOMAIN_NAMES[4],
+    domainName: DOMAIN_NAMES2[4],
     description: "Explicit criteria vs vague instructions, false positive management."
   },
   {
     id: "4.2",
     title: "Apply few-shot prompting to improve output consistency",
     domain: 4,
-    domainName: DOMAIN_NAMES[4],
+    domainName: DOMAIN_NAMES2[4],
     description: "Targeted examples, ambiguous case handling, format demonstration."
   },
   {
     id: "4.3",
     title: "Enforce structured output using tool use and JSON schemas",
     domain: 4,
-    domainName: DOMAIN_NAMES[4],
+    domainName: DOMAIN_NAMES2[4],
     description: "tool_use with schemas, tool_choice options, nullable fields, enum patterns."
   },
   {
     id: "4.4",
     title: "Implement validation, retry, and feedback loops",
     domain: 4,
-    domainName: DOMAIN_NAMES[4],
+    domainName: DOMAIN_NAMES2[4],
     description: "Retry-with-error-feedback, limits of retry, detected_pattern tracking."
   },
   {
     id: "4.5",
     title: "Design efficient batch processing strategies",
     domain: 4,
-    domainName: DOMAIN_NAMES[4],
+    domainName: DOMAIN_NAMES2[4],
     description: "Message Batches API, latency tolerance, custom_id, failure handling."
   },
   {
     id: "4.6",
     title: "Design multi-instance and multi-pass review architectures",
     domain: 4,
-    domainName: DOMAIN_NAMES[4],
+    domainName: DOMAIN_NAMES2[4],
     description: "Self-review limitations, independent review instances, per-file + cross-file passes."
   },
   // Domain 5: Context Management & Reliability
@@ -1838,42 +1845,42 @@ var CRITERIA = [
     id: "5.1",
     title: "Manage conversation context to preserve critical information",
     domain: 5,
-    domainName: DOMAIN_NAMES[5],
+    domainName: DOMAIN_NAMES2[5],
     description: "Progressive summarization risks, lost-in-the-middle, tool output trimming."
   },
   {
     id: "5.2",
     title: "Design effective escalation and ambiguity resolution patterns",
     domain: 5,
-    domainName: DOMAIN_NAMES[5],
+    domainName: DOMAIN_NAMES2[5],
     description: "Escalation triggers, customer preferences, sentiment unreliability."
   },
   {
     id: "5.3",
     title: "Implement error propagation strategies across multi-agent systems",
     domain: 5,
-    domainName: DOMAIN_NAMES[5],
+    domainName: DOMAIN_NAMES2[5],
     description: "Structured error context, access failures vs empty results, partial results."
   },
   {
     id: "5.4",
     title: "Manage context effectively in large codebase exploration",
     domain: 5,
-    domainName: DOMAIN_NAMES[5],
+    domainName: DOMAIN_NAMES2[5],
     description: "Context degradation, scratchpad files, subagent delegation, /compact."
   },
   {
     id: "5.5",
     title: "Design human review workflows and confidence calibration",
     domain: 5,
-    domainName: DOMAIN_NAMES[5],
+    domainName: DOMAIN_NAMES2[5],
     description: "Stratified sampling, field-level confidence, accuracy by document type."
   },
   {
     id: "5.6",
     title: "Preserve information provenance and handle uncertainty in synthesis",
     domain: 5,
-    domainName: DOMAIN_NAMES[5],
+    domainName: DOMAIN_NAMES2[5],
     description: "Claim-source mappings, conflict annotation, temporal data handling."
   }
 ];
@@ -2443,7 +2450,7 @@ User selected next action: ${selected}` }]
 function registerCapstoneBuildStep(server2, db2, userConfig2) {
   server2.tool(
     "capstone_build_step",
-    "Drive your guided capstone build \u2014 quiz, build, and advance through 18 progressive steps.",
+    'Drive your guided capstone build \u2014 quiz, build, and advance through 18 progressive steps. IMPORTANT: When presenting quiz questions, use AskUserQuestion with header "Answer" for A/B/C/D selection. When presenting action choices (quiz/build/next), use AskUserQuestion with header "Action".',
     {
       action: z9.enum(ACTIONS).describe("The build action: confirm, quiz, build, next, status, or abandon")
     },