@papi-ai/server 0.7.59 → 0.7.60

package/dist/index.js

@@ -7527,6 +7527,9 @@ ${footer}`);
 function newTaskJoinKey(task, index) {
   return task.tempId ?? `new-${index + 1}`;
 }
+function isUnresolvedPlaceholder(taskId, map) {
+  return !map.has(taskId) && /^new-\d+$/i.test(taskId);
+}
 var NONE_PATTERN2 = /^none\b/i;
 function normalizeText2(text) {
   return text.trim().toLowerCase().replace(/[.,;:!]+$/, "").replace(/\s+/g, " ");
@@ -9010,7 +9013,7 @@ var PLAN_FRAGMENT_DESIGN_BRIEF = `
    **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Replace the standard SCOPE (DO THIS) section with these type-specific sections:
    - AUDIENCE: Who this design is for \u2014 persona and context of use (e.g. "non-technical Owner, first dashboard visit")
    - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` (dev patterns, anti-patterns, component rules) AND \`docs/branding/brand-book.html\` (brand identity, positioning, voice canon) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
-   - DELIVERABLE FORMAT: What the output looks like \u2014 Claude Design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
+   - DELIVERABLE FORMAT: What the output looks like \u2014 design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
    - REVIEW POINTS: What the Owner must approve before the design is considered done (e.g. layout, copy, colour, imagery).
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Deliverable format confirmed with Owner before starting" and "[ ] Design output is self-contained \u2014 includes enough context for a developer to implement without further clarification."`;
@@ -9209,6 +9212,21 @@ function buildPlanFullInstructionsConditional(flags, ctx) {
   if (!flags || !ctx) return PLAN_FULL_INSTRUCTIONS;
   return composeFullModeInstructions(flags, ctx);
 }
+var CYCLE_DENSITY_TARGETS = {
+  light: { label: "Light", range: "2-3" },
+  standard: { label: "Standard", range: "3-5" },
+  deep: { label: "Deep", range: "6-8" }
+};
+function buildCycleDensityDirective(density) {
+  if (!density) return "";
+  const target = CYCLE_DENSITY_TARGETS[density];
+  return [
+    `## CYCLE DENSITY: ${target.label}`,
+    "",
+    `The user set this cycle's density to **${density}** \u2014 aim for roughly **${target.range} tasks** this cycle.`,
+    `This is a TARGET to size toward, not a hard floor or cap: still honour explicit user direction, any pre-assigned tasks, and impact-based sizing. If fewer genuinely-valuable tasks exist, plan fewer \u2014 do NOT pad the cycle to hit the number.`
+  ].join("\n");
+}
 function buildPlanUserMessage(ctx) {
   const modeLabel = ctx.mode.toUpperCase();
   const parts = [
@@ -9226,6 +9244,10 @@ function buildPlanUserMessage(ctx) {
       ""
     );
   }
+  const densityDirective = buildCycleDensityDirective(ctx.density);
+  if (densityDirective) {
+    parts.push(densityDirective, "");
+  }
   if (ctx.mode === "bootstrap") {
     parts.push(PLAN_BOOTSTRAP_INSTRUCTIONS);
   } else {
@@ -10101,15 +10123,49 @@ phases:
 
 *No decisions locked yet. These are added as planning cycles confirm strategic choices.*`;
 }
+function buildPreScanInstruction(opts) {
+  const docRouting = opts.hosted ? "paste the relevant content (decision records, roadmap, spec excerpts) directly into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "pass local doc file paths as `sources` (comma-separated), or paste content into `description`.";
+  return [
+    `**\u{1F50E} Before you generate anything \u2014 scan the project and gather real context.**`,
+    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name. You (the agent running this) have local access that PAPI does not \u2014 do the gathering, then pass it back.`,
+    ``,
+    `1. **Confirm the environment.** Check that you are running from the root of this project's dev environment \u2014 the folder that holds its source, git history, and docs. If you are not there, or you are connected over a remote connector with no access to the user's files, say so and ask the user where the project lives before continuing.`,
+    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call.`,
+    `3. **Scan the docs.** Look through \`docs/\`, design notes, ADRs/decision records, and any roadmap or planning files \u2014 not just code.`,
+    `4. **Check for sibling / separate repos.** Many projects span more than one repo (a separate frontend, backend, infra, or mobile repo, or other packages in a monorepo). Ask the user whether any related repos or directories exist, and scan those too.`,
+    `5. **Ask the user to point you at extra context.** Prompt them: "Is there anything else I should read before setting this up \u2014 a PRD or spec, decision records, a roadmap, or links to related repos or docs?" Fold whatever they share into the scan.`,
+    `6. **Re-run \`setup\` with what you gathered:** pass the code scan as \`codebase_scan\`; for docs, decision records, and roadmap, ${docRouting} Then answer the prompts below.`,
+    ``,
+    `If there is genuinely no code and no docs yet, skip this and generate from what the user tells you \u2014 the zero-context path is fully supported.`
+  ].join("\n");
+}
+var PAPI_DOCS_QUICKSTART_URL = "https://getpapi.ai/docs/guide/quick-start";
+var PAPI_PUBLIC_REPO_URL = "https://github.com/getpapi/papi";
+function buildNewProjectSetupInstruction(opts) {
+  const visionRouting = opts.hosted ? "paste anything they share (notes, a PRD, links) into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "fold anything they share (notes, a PRD, a sketch, links) into `description`, or pass local doc paths as `sources`.";
+  return [
+    `**\u{1F331} New project \u2014 start from the vision.**`,
+    `There's no existing code to mine, so setup builds from what the user wants to create. Do two things before answering the prompts below.`,
+    ``,
+    `1. **Get oriented on PAPI.** So you can guide the user well \u2014 whatever assistant you are \u2014 skim the quick-start docs at ${PAPI_DOCS_QUICKSTART_URL} and the public repo at ${PAPI_PUBLIC_REPO_URL}. They explain the plan \u2192 build \u2192 review cycle the user will run after setup.`,
+    `2. **Draw out the vision with the user.** Ask what they're building and for whom, the core problem it solves, and what success looks like \u2014 enough to write a real brief, a North Star, and a starter backlog rather than a generic scaffold. If they already have a PRD, sketch, notes, or links, ${visionRouting}`,
+    ``,
+    `Then answer the prompts below to generate the brief, decisions, North Star, and a vision-first starter backlog.`
+  ].join("\n");
+}
 var AD_SEED_SYSTEM = `You are a technical architect seeding initial Active Decisions for a new software project managed by PAPI.
 
 Active Decisions (ADs) are documented architectural choices with confidence levels. They guide the planner and builder agents \u2014 without ADs, planning output is generic and unhelpful.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce decisions directly.
 
+## SOURCE OF TRUTH \u2014 extract real decisions first
+
+If the context includes decision records, ADRs, a roadmap, a README, or codebase analysis, your PRIMARY job is to EXTRACT the real, already-made decisions from that material \u2014 not to invent generic ones. Read the provided context and capture each load-bearing choice the project has actually made (its stack, data model, architecture, positioning, deployment posture). Only fall back to informed defaults for a project of this type when the context contains no evidenced decisions.
+
 ## OUTPUT FORMAT
 
-Return a JSON array of 3-5 Active Decisions. Each AD must have:
+Return a JSON array of Active Decisions \u2014 ONE per real decision you find. Each AD must have:
 - "id": "AD-1", "AD-2", etc.
 - "body": Full markdown block including ### heading, confidence tag, and body text
 
@@ -10123,17 +10179,20 @@ The body format for each AD:
 
 ## GUIDELINES
 
-- All seeded ADs should have Confidence: MEDIUM (they are informed defaults, not confirmed choices)
-- Focus on decisions that genuinely differ by project type \u2014 avoid generic truisms
-- Each AD should be actionable and falsifiable (something the team could decide differently)
+- **Count follows the evidence \u2014 there is NO fixed target.** Seed as many ADs as there are real, distinct decisions in the material. Do NOT pad to a number, and do NOT fabricate decisions to hit a count. When the context has no evidenced decisions, return a small set (2-4) of informed defaults for this project type.
+- **Confidence reflects evidence:** a decision explicitly documented as settled in the source may be HIGH; an informed default you inferred stays MEDIUM.
+- Never mint an AD that is not a genuine stance-with-alternatives \u2014 a preference, a fact, or a config value is NOT an AD.
+- Focus on decisions that genuinely differ by project \u2014 avoid generic truisms.
+- Each AD should be actionable and falsifiable (something the team could decide differently).
 - Cover different concerns: architecture, data, deployment, testing strategy, API design, etc.
-- Keep each AD body to 4-6 lines \u2014 concise and scannable
+- Keep each AD body to 4-6 lines \u2014 concise and scannable.
+- **Do NOT duplicate** any decision already listed as an existing Active Decision in the context \u2014 skip it entirely.
 - **Quality bar:** ADs are for product and architecture choices that constrain future work \u2014 technology selections, data model designs, UX principles, strategic positioning. They are NOT for process preferences, configuration choices, or temporary workarounds.
 
 Return ONLY valid JSON \u2014 no preamble, no code fences, no explanation.`;
 function buildAdSeedPrompt(ctx) {
   const parts = [
-    `Generate 3-5 Active Decisions for this project.`,
+    ctx.codebaseContext ? `Extract the real Active Decisions for this project from the context below. Seed one AD per genuine decision \u2014 do not cap the count, and do not fabricate.` : `Seed the informed default Active Decisions for this project (no decision docs were supplied \u2014 infer sensible MEDIUM-confidence defaults for this project type).`,
     "",
     `**Project:** ${ctx.projectName}`,
     `**Type:** ${ctx.projectType}`,
@@ -10146,12 +10205,57 @@ function buildAdSeedPrompt(ctx) {
   if (ctx.constraints) {
     parts.push(`**Constraints:** ${ctx.constraints}`);
   }
+  if (ctx.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract the real decisions from here",
+      ctx.codebaseContext
+    );
+  }
+  if (ctx.existingDecisions && ctx.existingDecisions.length > 0) {
+    parts.push(
+      "",
+      "## Existing Active Decisions \u2014 do NOT duplicate these",
+      ...ctx.existingDecisions.map((d) => `- ${d}`)
+    );
+  }
   parts.push(
     "",
     'Return a JSON array of AD objects with "id" and "body" fields. No other text.'
   );
   return parts.join("\n");
 }
+var NORTH_STAR_SYSTEM = `You are helping a builder define the North Star for a software project set up with PAPI.
+
+A North Star is the ONE outcome that best captures whether the project is succeeding \u2014 a single, measurable, user-centred statement the team can steer by. It is not a feature list and not a vision paragraph.
+
+IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions in your output.
+
+## HOW TO PRODUCE IT
+- If the provided context (brief, docs, decision records) ALREADY states a North Star, goal metric, or primary success measure, EXTRACT and restate it \u2014 do not invent a competing one.
+- Otherwise, PROPOSE the most fitting North Star from the project's purpose and users. (The calling agent will confirm it with the user before it is saved.)
+
+## OUTPUT FORMAT
+Return ONLY the North Star statement \u2014 one or two sentences, concrete and measurable where possible. No heading, no preamble, no quotes, no code fences.`;
+function buildNorthStarPrompt(inputs) {
+  const parts = [
+    `Define the North Star for this project.`,
+    "",
+    `**Project:** ${inputs.projectName}`,
+    `**Description:** ${inputs.description?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Target users:** ${inputs.targetUsers?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Problems solved:** ${inputs.problems}`
+  ];
+  if (inputs.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract an existing North Star from here if one is stated",
+      inputs.codebaseContext
+    );
+  }
+  parts.push("", "Return only the North Star statement.");
+  return parts.join("\n");
+}
 var CONVENTIONS_SYSTEM = `You are a senior software engineer generating CLAUDE.md coding conventions for a new project.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce conventions directly.
@@ -12327,10 +12431,10 @@ ${cleanContent}`;
     }
     for (const handoff of data.cycleHandoffs) {
       const resolvedId = newTaskIdMap.get(handoff.taskId) ?? handoff.taskId;
-      if (resolvedId === handoff.taskId && /^new-\d+$/i.test(handoff.taskId)) {
+      if (isUnresolvedPlaceholder(handoff.taskId, newTaskIdMap)) {
         const titleLine = handoff.buildHandoff.match(/^Task:\s*(.+)/m)?.[1] ?? "(unknown)";
-        console.error(
-          `[plan] UNRESOLVED handoff reference "${handoff.taskId}" (task: ${titleLine.slice(0, 80)}) \u2014 no newTask carries this tempId/index. Handoff NOT written. Ensure each newTasks entry has a tempId matching its cycleHandoffs taskId (task-2242).`
+        warnings.push(
+          `UNRESOLVED handoff "${handoff.taskId}" (task: ${titleLine.slice(0, 80)}) \u2014 no newTask carries this tempId/index; handoff NOT written and the task is missing from the cycle. Ensure each newTasks entry has a tempId matching its cycleHandoffs taskId (task-2242).`
         );
         continue;
       }
@@ -12596,7 +12700,7 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
     skippedCancellations
   };
 }
-async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker) {
+async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density) {
   const prepareTimer = startTimer();
   tracker?.mark("validate_and_prepare");
   let t = startTimer();
@@ -12657,6 +12761,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     throw new Error("TEMPLATE_BRIEF");
   }
   if (skipHandoffs) context.skipHandoffs = true;
+  if (density) context.density = density;
   tracker?.mark("codebase_scan");
   t = startTimer();
   try {
@@ -13297,11 +13402,6 @@ var planTool = {
         type: "string",
         description: 'Absolute path to a file containing the plan output (mode "apply" only). Use this when the response is too large to pass as a string parameter (some hosts cap inputs around 50KB). The file must be absolute, exist, and be \u2264500KB. Mutually exclusive with llm_response.'
       },
-      plan_mode: {
-        type: "string",
-        enum: ["bootstrap", "full"],
-        description: 'The plan mode returned from prepare phase (mode "apply" only).'
-      },
       cycle_number: {
         type: "number",
         description: 'The cycle number returned from prepare phase (mode "apply" only).'
@@ -13330,6 +13430,11 @@ var planTool = {
         type: "string",
         description: 'User direction for this cycle \u2014 what to focus on, which phase/tasks to prioritise, or constraints to respect. Overrides the autonomous priority tier system. Example: "Focus on Schema Model phase 9 tasks this cycle".'
       },
+      density: {
+        type: "string",
+        enum: ["light", "standard", "deep"],
+        description: 'Target cycle density \u2014 how many tasks the planner should aim to include. "light" \u2248 2-3 tasks, "standard" \u2248 3-5 (the default when omitted), "deep" \u2248 6-8. A TARGET, not a floor or cap: the planner still honours user direction, pre-assigned tasks, and impact sizing, and plans fewer if fewer genuinely-valuable tasks exist.'
+      },
       force: {
         type: "boolean",
         description: "Bypass planning guards (unreleased cycle block, strategy review hard-block). Only use when explicitly requested by the user."
@@ -13428,6 +13533,7 @@ async function handlePlan(adapter2, config2, args) {
   const focus = typeof args.focus === "string" ? args.focus : void 0;
   const force = args.force === true;
   const handoffsOnly = args.handoffs_only === true;
+  const density = args.density === "light" || args.density === "standard" || args.density === "deep" ? args.density : void 0;
   const tracker = new ProgressTracker(toolMode === "apply" ? "apply_validate" : "prepare_validate").bindStream(adapter2, { stage: "plan" });
   try {
     if (toolMode === "apply") {
@@ -13439,7 +13545,6 @@ async function handlePlan(adapter2, config2, args) {
         return errorResponse(resolved.error);
       }
       const llmResponse = resolved.llmResponse;
-      const planMode = args.plan_mode || "full";
       const rawCycleNumber = args.cycle_number != null ? Number(args.cycle_number) : NaN;
       const strategyReviewWarning = args.strategy_review_warning || "";
       const prep = planPrepareCache.peek(callerKey) ?? loadPrepareSpill(adapter2.getProjectId?.(), callerKey);
@@ -13469,6 +13574,7 @@ async function handlePlan(adapter2, config2, args) {
         );
       }
       const cycleNumber = newCycleNumber - 1;
+      const planMode = determineMode(cycleNumber);
       planPrepareCache.clear(callerKey);
       clearPrepareSpill(adapter2.getProjectId?.(), callerKey);
       let utilisation;
@@ -13500,7 +13606,7 @@ async function handlePlan(adapter2, config2, args) {
       } catch {
       }
       const skipHandoffs = args.skip_handoffs === true;
-      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker);
+      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density);
       const prepareState = {
         contextHashes: result.contextHashes,
         userMessage: result.userMessage,
@@ -13550,7 +13656,6 @@ Follow the system prompt and context below to generate a complete cycle plan.
 When done, call \`plan\` again with:
 - \`mode\`: "apply"
 - \`llm_response\`: your complete output (both parts)
-- \`plan_mode\`: "${result.mode}"
 - \`cycle_number\`: ${result.cycleNumber + 1}
 - \`strategy_review_warning\`: "${result.strategyReviewWarning.replace(/"/g, '\\"')}"
 
@@ -13575,7 +13680,9 @@ ${result.userMessage}
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (message === "TEMPLATE_BRIEF") {
-      return textResponse("Your Product Brief still contains template text. Run `setup` first to generate a real Product Brief for your project.");
+      return textResponse(
+        "Can't plan a full cycle yet \u2014 your Product Brief is still the placeholder template.\n\nPlan mode is derived automatically from your cycle count: your first-ever cycle runs in bootstrap mode (which tolerates a thin brief), and every cycle after that runs in full mode (which needs a real brief to scope work against). This project is past its first cycle, so full mode expected a real brief but found the template text.\n\nFix: run `setup` to generate a real Product Brief for your project, then run `plan` again."
+      );
     }
     const isKnownFriendly = /^(Cannot run plan|Strategy Review gate|No tasks assigned|llm_response is required|cycle_number|Merge conflicts|applyPlan timed out)/i.test(message);
     if (isKnownFriendly) {
@@ -18008,6 +18115,7 @@ async function prepareSetup(adapter2, config2, input) {
       codebaseContext: codebaseSummary
     })
   };
+  const existingDecisions = adapter2.getActiveDecisions ? (await adapter2.getActiveDecisions({ includeRetired: true }).catch(() => [])).filter((a) => !a.superseded).map((a) => `${a.displayId}: ${a.title}`) : [];
   const adSeedPrompt = input.projectType ? {
     system: AD_SEED_SYSTEM,
     user: buildAdSeedPrompt({
@@ -18018,7 +18126,11 @@ async function prepareSetup(adapter2, config2, input) {
       problems: input.problems,
       teamSize: input.teamSize,
       deploymentTarget: input.deploymentTarget,
-      constraints: input.constraints
+      constraints: input.constraints,
+      // task-2811: feed the pre-scanned codebase/decision-doc context so ADs are
+      // extracted from the project's real decisions, not invented generically.
+      codebaseContext: codebaseSummary,
+      existingDecisions: existingDecisions.length > 0 ? existingDecisions : void 0
     })
   } : void 0;
   const conventionsPrompt = input.projectType ? {
@@ -18052,6 +18164,21 @@ async function prepareSetup(adapter2, config2, input) {
       projectType: input.projectType
     })
   } : void 0;
+  const existingNorthStar = adapter2.getCurrentNorthStar ? await adapter2.getCurrentNorthStar().catch(() => null) : null;
+  const northStarAlreadyExists = Boolean(existingNorthStar && existingNorthStar.trim());
+  const northStarPrompt = northStarAlreadyExists ? void 0 : {
+    system: NORTH_STAR_SYSTEM,
+    user: buildNorthStarPrompt({
+      projectName: input.projectName,
+      description: input.description,
+      targetUsers: input.targetUsers,
+      problems: input.problems,
+      codebaseContext: codebaseSummary
+    })
+  };
+  const willGenerateBrief = !effectiveBriefAlreadyExists;
+  const preScanInstruction = willGenerateBrief && isExistingProject && !input.codebaseScan ? buildPreScanInstruction({ hosted: !canScanFilesystem, existingProject: true }) : void 0;
+  const newProjectInstruction = willGenerateBrief && !isExistingProject ? buildNewProjectSetupInstruction({ hosted: !canScanFilesystem }) : void 0;
   return {
     createdProject,
     projectName: input.projectName,
@@ -18059,17 +18186,21 @@ async function prepareSetup(adapter2, config2, input) {
     adSeedPrompt,
     conventionsPrompt,
     initialTasksPrompt,
+    northStarPrompt,
+    northStarAlreadyExists,
     codebaseSummary,
     detectedCodebaseType,
     autoDetected: autoDetected && detectedCodebaseType !== "new_project",
     briefAlreadyExists: effectiveBriefAlreadyExists,
     briefWillRegenerate,
     briefRegenReason,
+    preScanInstruction,
+    newProjectInstruction,
     warnings: warnings.length > 0 ? warnings : void 0,
     filesToWrite: prepareCollector.isEmpty() ? void 0 : prepareCollector
   };
 }
-async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText) {
+async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText, northStarText) {
   const collector = new FileWriteCollector();
   const createdProject = await scaffoldPapiDir(adapter2, config2, input, collector);
   let effectiveBriefText = briefText;
@@ -18096,6 +18227,21 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     }
   }
   const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, collector, effectiveBriefText, adSeedText, conventionsText);
+  let northStarSet = false;
+  const northStarStatement = northStarText?.trim();
+  if (northStarStatement && adapter2.upsertNorthStar) {
+    try {
+      const existing = adapter2.getCurrentNorthStar ? await adapter2.getCurrentNorthStar().catch(() => null) : null;
+      if (!(existing && existing.trim()) || input.force) {
+        await adapter2.upsertNorthStar(northStarStatement, 0);
+        northStarSet = true;
+      }
+    } catch (err) {
+      warnings.push(
+        `North Star not saved \u2014 ${err instanceof Error ? err.message : String(err)}. Set one later during your first \`plan\`.`
+      );
+    }
+  }
   let createdTasks = 0;
   let tasksSkipped = 0;
   if (initialTasksText?.trim()) {
@@ -18241,6 +18387,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     seededAds,
     createdTasks,
     tasksSkipped: tasksSkipped > 0 ? tasksSkipped : void 0,
+    northStarSet: northStarSet || void 0,
     briefRegenerated: briefRegenerated || void 0,
     cursorScaffolded,
     gitignoreNote,
@@ -18299,6 +18446,10 @@ var setupTool = {
         type: "string",
         description: 'Your generated conventions markdown to append to CLAUDE.md (mode "apply" only). Optional.'
       },
+      north_star_response: {
+        type: "string",
+        description: `The project's North Star statement \u2014 one or two sentences (mode "apply" only). Provide the statement you extracted from the docs or agreed with the user in response to the prepare-phase North Star prompt. Optional; omit when the project already has one.`
+      },
       project_name: {
         type: "string",
         description: "Name of the project."
@@ -18408,6 +18559,9 @@ function formatSuccessResponse(result, constraints, writesClaudeMd = true) {
   const adNote = result.seededAds > 0 ? `
 
 ${result.seededAds} Active Decision${result.seededAds > 1 ? "s" : ""} seeded based on project type \u2014 review them with \`strategy_review\` after your first cycle.` : "";
+  const northStarNote = result.northStarSet ? `
+
+\u2B50 North Star set \u2014 your project starts steered (no "define a North Star" warning on \`orient\`).` : "";
   const taskNote = result.createdTasks > 0 || (result.tasksSkipped ?? 0) > 0 ? (() => {
     const created = result.createdTasks > 0 ? `${result.createdTasks} initial backlog task${result.createdTasks > 1 ? "s" : ""} created` : "";
     const skipped = (result.tasksSkipped ?? 0) > 0 ? `${result.tasksSkipped} duplicate${(result.tasksSkipped ?? 0) > 1 ? "s" : ""} skipped` : "";
@@ -18427,7 +18581,7 @@ ${[created, skipped].filter(Boolean).join(", ")}.${idea}`;
 ${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
   const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
   return textResponse(
-    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}
+    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}
 
 **Important:** Setup created/modified files (${harnessFiles}, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.
 
@@ -18460,8 +18614,9 @@ PAPI needs the project name. Description and target users are optional \u2014 th
       const adSeedResponse = args.ad_seed_response;
       const conventionsResponse = args.conventions_response;
       const initialTasksResponse = args.initial_tasks_response;
+      const northStarResponse = args.north_star_response;
       tracker.mark("apply_setup_writeback");
-      const result = await applySetup(adapter2, config2, input, briefResponse, adSeedResponse, conventionsResponse, initialTasksResponse);
+      const result = await applySetup(adapter2, config2, input, briefResponse, adSeedResponse, conventionsResponse, initialTasksResponse, northStarResponse);
       tracker.mark("apply_format_response");
       return formatSuccessResponse(result, args.constraints, writesClaudeMd);
     }
@@ -18517,7 +18672,13 @@ PAPI needs the project name. Description and target users are optional \u2014 th
           ""
         );
       }
-      if (result.briefPrompt && !result.briefAlreadyExists) {
+      if (result.preScanInstruction) {
+        sections.push(result.preScanInstruction, "");
+      }
+      if (result.newProjectInstruction) {
+        sections.push(result.newProjectInstruction, "");
+      }
+      if (!result.preScanInstruction && !result.newProjectInstruction && result.briefPrompt && !result.briefAlreadyExists) {
         sections.push(
           `**\u{1F4C4} Before you write the brief \u2014 does the user already have a PRD, brief, spec, or design doc?**`,
           `A brief generated from the user's real spec produces a far better first plan than a generic scaffold.`,
@@ -18534,6 +18695,7 @@ PAPI needs the project name. Description and target users are optional \u2014 th
         result.briefPrompt ? `- \`brief_response\`: your Product Brief markdown` : "",
         result.adSeedPrompt ? `- \`ad_seed_response\`: your AD seed JSON array` : "",
         result.conventionsPrompt ? `- \`conventions_response\`: your conventions markdown` : "",
+        result.northStarPrompt ? `- \`north_star_response\`: the North Star statement (confirm it with the user first)` : "",
         result.initialTasksPrompt ? `- \`initial_tasks_response\`: your initial tasks JSON array` : "",
         `- Plus all the original setup fields (project_name, description, target_users${isExisting ? ", existing_project: true" : ""})`,
         "",
@@ -18586,6 +18748,25 @@ ${result.conventionsPrompt.system}
           "",
           `<context>
 ${result.conventionsPrompt.user}
+</context>`
+        );
+      }
+      if (result.northStarPrompt) {
+        sectionNum++;
+        sections.push(
+          "",
+          `---`,
+          "",
+          `### ${sectionNum}. North Star`,
+          "",
+          `This project has no North Star yet \u2014 define one now so it starts steered (otherwise \`orient\` will warn that none is set). Extract it from the docs if one is already stated there; otherwise propose one and **confirm it with the user** before applying. Return it as \`north_star_response\`.`,
+          "",
+          `<system_prompt>
+${result.northStarPrompt.system}
+</system_prompt>`,
+          "",
+          `<context>
+${result.northStarPrompt.user}
 </context>`
         );
       }

package/dist/prompts.js

@@ -236,7 +236,7 @@ var PLAN_FRAGMENT_DESIGN_BRIEF = `
    **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Replace the standard SCOPE (DO THIS) section with these type-specific sections:
    - AUDIENCE: Who this design is for \u2014 persona and context of use (e.g. "non-technical Owner, first dashboard visit")
    - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` (dev patterns, anti-patterns, component rules) AND \`docs/branding/brand-book.html\` (brand identity, positioning, voice canon) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
-   - DELIVERABLE FORMAT: What the output looks like \u2014 Claude Design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
+   - DELIVERABLE FORMAT: What the output looks like \u2014 design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
    - REVIEW POINTS: What the Owner must approve before the design is considered done (e.g. layout, copy, colour, imagery).
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Deliverable format confirmed with Owner before starting" and "[ ] Design output is self-contained \u2014 includes enough context for a developer to implement without further clarification."`;
@@ -435,6 +435,21 @@ function buildPlanFullInstructionsConditional(flags, ctx) {
   if (!flags || !ctx) return PLAN_FULL_INSTRUCTIONS;
   return composeFullModeInstructions(flags, ctx);
 }
+var CYCLE_DENSITY_TARGETS = {
+  light: { label: "Light", range: "2-3" },
+  standard: { label: "Standard", range: "3-5" },
+  deep: { label: "Deep", range: "6-8" }
+};
+function buildCycleDensityDirective(density) {
+  if (!density) return "";
+  const target = CYCLE_DENSITY_TARGETS[density];
+  return [
+    `## CYCLE DENSITY: ${target.label}`,
+    "",
+    `The user set this cycle's density to **${density}** \u2014 aim for roughly **${target.range} tasks** this cycle.`,
+    `This is a TARGET to size toward, not a hard floor or cap: still honour explicit user direction, any pre-assigned tasks, and impact-based sizing. If fewer genuinely-valuable tasks exist, plan fewer \u2014 do NOT pad the cycle to hit the number.`
+  ].join("\n");
+}
 function buildPlanUserMessage(ctx) {
   const modeLabel = ctx.mode.toUpperCase();
   const parts = [
@@ -452,6 +467,10 @@ function buildPlanUserMessage(ctx) {
       ""
     );
   }
+  const densityDirective = buildCycleDensityDirective(ctx.density);
+  if (densityDirective) {
+    parts.push(densityDirective, "");
+  }
   if (ctx.mode === "bootstrap") {
     parts.push(PLAN_BOOTSTRAP_INSTRUCTIONS);
   } else {
@@ -1327,15 +1346,49 @@ phases:
 
 *No decisions locked yet. These are added as planning cycles confirm strategic choices.*`;
 }
+function buildPreScanInstruction(opts) {
+  const docRouting = opts.hosted ? "paste the relevant content (decision records, roadmap, spec excerpts) directly into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "pass local doc file paths as `sources` (comma-separated), or paste content into `description`.";
+  return [
+    `**\u{1F50E} Before you generate anything \u2014 scan the project and gather real context.**`,
+    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name. You (the agent running this) have local access that PAPI does not \u2014 do the gathering, then pass it back.`,
+    ``,
+    `1. **Confirm the environment.** Check that you are running from the root of this project's dev environment \u2014 the folder that holds its source, git history, and docs. If you are not there, or you are connected over a remote connector with no access to the user's files, say so and ask the user where the project lives before continuing.`,
+    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call.`,
+    `3. **Scan the docs.** Look through \`docs/\`, design notes, ADRs/decision records, and any roadmap or planning files \u2014 not just code.`,
+    `4. **Check for sibling / separate repos.** Many projects span more than one repo (a separate frontend, backend, infra, or mobile repo, or other packages in a monorepo). Ask the user whether any related repos or directories exist, and scan those too.`,
+    `5. **Ask the user to point you at extra context.** Prompt them: "Is there anything else I should read before setting this up \u2014 a PRD or spec, decision records, a roadmap, or links to related repos or docs?" Fold whatever they share into the scan.`,
+    `6. **Re-run \`setup\` with what you gathered:** pass the code scan as \`codebase_scan\`; for docs, decision records, and roadmap, ${docRouting} Then answer the prompts below.`,
+    ``,
+    `If there is genuinely no code and no docs yet, skip this and generate from what the user tells you \u2014 the zero-context path is fully supported.`
+  ].join("\n");
+}
+var PAPI_DOCS_QUICKSTART_URL = "https://getpapi.ai/docs/guide/quick-start";
+var PAPI_PUBLIC_REPO_URL = "https://github.com/getpapi/papi";
+function buildNewProjectSetupInstruction(opts) {
+  const visionRouting = opts.hosted ? "paste anything they share (notes, a PRD, links) into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "fold anything they share (notes, a PRD, a sketch, links) into `description`, or pass local doc paths as `sources`.";
+  return [
+    `**\u{1F331} New project \u2014 start from the vision.**`,
+    `There's no existing code to mine, so setup builds from what the user wants to create. Do two things before answering the prompts below.`,
+    ``,
+    `1. **Get oriented on PAPI.** So you can guide the user well \u2014 whatever assistant you are \u2014 skim the quick-start docs at ${PAPI_DOCS_QUICKSTART_URL} and the public repo at ${PAPI_PUBLIC_REPO_URL}. They explain the plan \u2192 build \u2192 review cycle the user will run after setup.`,
+    `2. **Draw out the vision with the user.** Ask what they're building and for whom, the core problem it solves, and what success looks like \u2014 enough to write a real brief, a North Star, and a starter backlog rather than a generic scaffold. If they already have a PRD, sketch, notes, or links, ${visionRouting}`,
+    ``,
+    `Then answer the prompts below to generate the brief, decisions, North Star, and a vision-first starter backlog.`
+  ].join("\n");
+}
 var AD_SEED_SYSTEM = `You are a technical architect seeding initial Active Decisions for a new software project managed by PAPI.
 
 Active Decisions (ADs) are documented architectural choices with confidence levels. They guide the planner and builder agents \u2014 without ADs, planning output is generic and unhelpful.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce decisions directly.
 
+## SOURCE OF TRUTH \u2014 extract real decisions first
+
+If the context includes decision records, ADRs, a roadmap, a README, or codebase analysis, your PRIMARY job is to EXTRACT the real, already-made decisions from that material \u2014 not to invent generic ones. Read the provided context and capture each load-bearing choice the project has actually made (its stack, data model, architecture, positioning, deployment posture). Only fall back to informed defaults for a project of this type when the context contains no evidenced decisions.
+
 ## OUTPUT FORMAT
 
-Return a JSON array of 3-5 Active Decisions. Each AD must have:
+Return a JSON array of Active Decisions \u2014 ONE per real decision you find. Each AD must have:
 - "id": "AD-1", "AD-2", etc.
 - "body": Full markdown block including ### heading, confidence tag, and body text
 
@@ -1349,17 +1402,20 @@ The body format for each AD:
 
 ## GUIDELINES
 
-- All seeded ADs should have Confidence: MEDIUM (they are informed defaults, not confirmed choices)
-- Focus on decisions that genuinely differ by project type \u2014 avoid generic truisms
-- Each AD should be actionable and falsifiable (something the team could decide differently)
+- **Count follows the evidence \u2014 there is NO fixed target.** Seed as many ADs as there are real, distinct decisions in the material. Do NOT pad to a number, and do NOT fabricate decisions to hit a count. When the context has no evidenced decisions, return a small set (2-4) of informed defaults for this project type.
+- **Confidence reflects evidence:** a decision explicitly documented as settled in the source may be HIGH; an informed default you inferred stays MEDIUM.
+- Never mint an AD that is not a genuine stance-with-alternatives \u2014 a preference, a fact, or a config value is NOT an AD.
+- Focus on decisions that genuinely differ by project \u2014 avoid generic truisms.
+- Each AD should be actionable and falsifiable (something the team could decide differently).
 - Cover different concerns: architecture, data, deployment, testing strategy, API design, etc.
-- Keep each AD body to 4-6 lines \u2014 concise and scannable
+- Keep each AD body to 4-6 lines \u2014 concise and scannable.
+- **Do NOT duplicate** any decision already listed as an existing Active Decision in the context \u2014 skip it entirely.
 - **Quality bar:** ADs are for product and architecture choices that constrain future work \u2014 technology selections, data model designs, UX principles, strategic positioning. They are NOT for process preferences, configuration choices, or temporary workarounds.
 
 Return ONLY valid JSON \u2014 no preamble, no code fences, no explanation.`;
 function buildAdSeedPrompt(ctx) {
   const parts = [
-    `Generate 3-5 Active Decisions for this project.`,
+    ctx.codebaseContext ? `Extract the real Active Decisions for this project from the context below. Seed one AD per genuine decision \u2014 do not cap the count, and do not fabricate.` : `Seed the informed default Active Decisions for this project (no decision docs were supplied \u2014 infer sensible MEDIUM-confidence defaults for this project type).`,
     "",
     `**Project:** ${ctx.projectName}`,
     `**Type:** ${ctx.projectType}`,
@@ -1372,12 +1428,57 @@ function buildAdSeedPrompt(ctx) {
   if (ctx.constraints) {
     parts.push(`**Constraints:** ${ctx.constraints}`);
   }
+  if (ctx.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract the real decisions from here",
+      ctx.codebaseContext
+    );
+  }
+  if (ctx.existingDecisions && ctx.existingDecisions.length > 0) {
+    parts.push(
+      "",
+      "## Existing Active Decisions \u2014 do NOT duplicate these",
+      ...ctx.existingDecisions.map((d) => `- ${d}`)
+    );
+  }
   parts.push(
     "",
     'Return a JSON array of AD objects with "id" and "body" fields. No other text.'
   );
   return parts.join("\n");
 }
+var NORTH_STAR_SYSTEM = `You are helping a builder define the North Star for a software project set up with PAPI.
+
+A North Star is the ONE outcome that best captures whether the project is succeeding \u2014 a single, measurable, user-centred statement the team can steer by. It is not a feature list and not a vision paragraph.
+
+IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions in your output.
+
+## HOW TO PRODUCE IT
+- If the provided context (brief, docs, decision records) ALREADY states a North Star, goal metric, or primary success measure, EXTRACT and restate it \u2014 do not invent a competing one.
+- Otherwise, PROPOSE the most fitting North Star from the project's purpose and users. (The calling agent will confirm it with the user before it is saved.)
+
+## OUTPUT FORMAT
+Return ONLY the North Star statement \u2014 one or two sentences, concrete and measurable where possible. No heading, no preamble, no quotes, no code fences.`;
+function buildNorthStarPrompt(inputs) {
+  const parts = [
+    `Define the North Star for this project.`,
+    "",
+    `**Project:** ${inputs.projectName}`,
+    `**Description:** ${inputs.description?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Target users:** ${inputs.targetUsers?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Problems solved:** ${inputs.problems}`
+  ];
+  if (inputs.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract an existing North Star from here if one is stated",
+      inputs.codebaseContext
+    );
+  }
+  parts.push("", "Return only the North Star statement.");
+  return parts.join("\n");
+}
 var CONVENTIONS_SYSTEM = `You are a senior software engineer generating CLAUDE.md coding conventions for a new project.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce conventions directly.
@@ -1497,9 +1598,13 @@ export {
   AD_REJECTION_RULES,
   AD_SEED_SYSTEM,
   CONVENTIONS_SYSTEM,
+  CYCLE_DENSITY_TARGETS,
   HANDOFF_REGEN_SYSTEM,
   INITIAL_TASKS_SYSTEM,
+  NORTH_STAR_SYSTEM,
   OUTPUT_QUALITY_RUBRIC,
+  PAPI_DOCS_QUICKSTART_URL,
+  PAPI_PUBLIC_REPO_URL,
   PLAN_BOOTSTRAP_INSTRUCTIONS,
   PLAN_FULL_INSTRUCTIONS,
   PLAN_SYSTEM,
@@ -1509,11 +1614,15 @@ export {
   VISION_TASKS_SYSTEM,
   buildAdSeedPrompt,
   buildConventionsPrompt,
+  buildCycleDensityDirective,
   buildHandoffRegenMessage,
   buildHandoffsOnlyUserMessage,
   buildInitialTasksPrompt,
+  buildNewProjectSetupInstruction,
+  buildNorthStarPrompt,
   buildPlanFullInstructionsConditional,
   buildPlanUserMessage,
+  buildPreScanInstruction,
   buildProductBriefPrompt,
   buildReviewSystemPrompt,
   buildReviewUserMessage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.59",
+  "version": "0.7.60",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",