@konductro/cursor-plugin 1.2.0 → 1.3.0

package/README.md

@@ -63,7 +63,7 @@ Tools are called automatically by Cursor's agent based on your requests:
 | `update_work_item` | Change the title, description or acceptance criteria of a work item you own |
 | `delete_work_item` | Delete a task or bug that has not been started |
 | `list_tech_analysis_tasks` | List tech analysis assignments |
-| `get_task_context` | Load tech analysis context |
+| `get_task_context` | Load tech analysis context, plus the requester's message when a refresh was asked for |
 | `submit_tech_analysis` | Submit analysis document |
 | `list_decomposition_tasks` | List story decomposition assignments |
 | `get_decomposition_context` | Load story context |

package/bin/setup.js

@@ -136,6 +136,7 @@ function main() {
   console.log('  prototype            — build a UX prototype');
   console.log('  find-prototype       — find and download prototypes');
   console.log('  bug-enrich           — enrich a bug report');
+  console.log('  demand-analysis      — size a demand against the real code');
   console.log('');
   console.log('Reload Cursor to activate (Cmd+Shift+P → "Developer: Reload Window").');
   console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konductro/cursor-plugin",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Cursor IDE plugin for the Konductro platform: technical analysis, delivery tasks, repository profiling, and prototype workflows.",
   "license": "UNLICENSED",
   "type": "module",

package/servers/konductro-api.js

@@ -32,6 +32,24 @@ function loadFileConfig() {
 const fileConfig = loadFileConfig();
 const KONDUCTRO_URL = (process.env.KONDUCTRO_URL || fileConfig.url || fileConfig.konductroUrl || '').replace(/\/$/, '');
 const CLI_TOKEN = process.env.KONDUCTRO_CLI_TOKEN || fileConfig.token || fileConfig.cliToken || '';
+
+/*
+ * What this plugin tells the server it is, on every request.
+ *
+ * READ FROM package.json, never a constant. The server's refusal of an outdated plugin is
+ * based on this string, so a hand-maintained copy that drifts from the published version
+ * is worse than no header at all: it would be believed.
+ *
+ * `readFileSync` rather than a JSON import assertion, whose syntax differs between Node 18
+ * and 20 and would break for whichever developers are on the other one.
+ *
+ * The shape is `<plugin>/<version>` and is identical across all four plugins, so the
+ * server parses one format rather than four.
+ */
+const PLUGIN_VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+const PLUGIN_ID = `cursor/${PLUGIN_VERSION}`;
 const NOT_CONFIGURED_MESSAGE =
   'Konductro is not configured. Run `konductro-cursor-setup --url <URL> --token <TOKEN>`, or set KONDUCTRO_URL and KONDUCTRO_CLI_TOKEN in the MCP server environment.';
 
@@ -39,6 +57,7 @@ async function konductroFetch(path, options = {}) {
   const url = `${KONDUCTRO_URL}${path}`;
   const headers = {
     'Authorization': `Bearer ${CLI_TOKEN}`,
+    'X-Konductro-Plugin': PLUGIN_ID,
     ...options.headers,
   };
   // Only set Content-Type and default body for methods that send JSON
@@ -226,7 +245,7 @@ server.tool(
     }
 
     const taskList = tasks.map((t, i) =>
-      `${i + 1}. **${t.projectName}** — ${t.phaseName}\n   Client: ${t.clientName}\n   Phase ID: ${t.phaseId}\n   ${t.hasExistingDraft ? '(has existing draft)' : '(new analysis)'}`
+      `${i + 1}. **${t.projectName}** — ${t.phaseName}\n   Client: ${t.clientName}\n   Phase ID: ${t.phaseId}\n   ${t.refreshRequested ? '(refresh requested)' : t.hasExistingDraft ? '(has existing draft)' : '(new analysis)'}`
     ).join('\n\n');
 
     return {
@@ -256,6 +275,25 @@ server.tool(
     if (context.phase.description) contextText += `**Description:** ${context.phase.description}\n`;
     contextText += `\n`;
 
+    // KON-321: a refresh was requested, so this is a revision of an approved
+    // analysis rather than a first pass. Sits above the repositories and the
+    // previous document deliberately — it changes what is being asked for, so
+    // it has to be read before the material it applies to. Absent on a normal
+    // task, in which case the output is exactly what it was before.
+    if (context.refreshContext) {
+      const { requestedBy, message } = context.refreshContext;
+      contextText += `### Refresh Requested\n\n`;
+      contextText += `A refresh of this technical analysis was requested`;
+      if (requestedBy) contextText += ` by ${requestedBy}`;
+      contextText += `.\n\n`;
+      if (message) {
+        contextText += `**Context from the requester:**\n\n${message}\n\n`;
+      } else {
+        contextText += `No further context was given.\n\n`;
+      }
+      contextText += `Revise the existing analysis below rather than starting over.\n\n`;
+    }
+
     if (context.repositories.length > 0) {
       contextText += `### Repositories\n\n`;
       for (const repo of context.repositories) {
@@ -282,6 +320,8 @@ server.tool(
       }
     }
 
+    contextText += renderDocumentTemplate(context.documentTemplate);
+
     return {
       content: [{
         type: 'text',
@@ -291,6 +331,51 @@ server.tool(
   }
 );
 
+/**
+ * The document structure this workspace requires, as the agent must read it.
+ *
+ * APPENDED, never woven into the blob above. Four plugins share that server response and
+ * the agent's prompt is sensitive to its shape, so everything before this point is
+ * byte-identical to what it has always been. A workspace with no template gets an empty
+ * string here and therefore exactly today's context.
+ *
+ * THE WORDING IS IDENTICAL IN ALL FOUR PLUGINS, deliberately. The story this belongs to
+ * requires the same behaviour from Claude, Amazon Q, Codex and Cursor, and four separately
+ * worded prompts is precisely how that stops being true. Change it here and copy it, do
+ * not improve it in one place.
+ *
+ * Standing content is reproduced WORD FOR WORD rather than summarised. It is usually a
+ * compliance clause the workspace requires verbatim, which is the whole reason the field
+ * exists.
+ */
+function renderDocumentTemplate(template) {
+  if (!template) return '';
+
+  let text = `### Required Document Structure\n\n`;
+  text += `This workspace requires technical analysis documents to follow **${template.name}** `;
+  text += `(v${template.version}). Produce these sections, in this order, using these exact headings.\n\n`;
+
+  for (const [index, section] of template.sections.entries()) {
+    text += `${index + 1}. **${section.title}**`;
+    if (section.intent) text += ` — ${section.intent}`;
+    if (section.mustCover) text += ` _(must cover: do not produce the document until you can answer this)_`;
+    text += `\n`;
+    if (section.diagram && section.diagram !== 'none') {
+      const kind = section.diagram === 'any' ? 'a Mermaid diagram of whichever type fits' : `a Mermaid ${section.diagram} diagram`;
+      text += `   Include ${kind} inside this section.\n`;
+    }
+    if (section.standingContent) {
+      text += `   Reproduce this text inside the section, word for word:\n`;
+      text += `   > ${section.standingContent.split('\n').join('\n   > ')}\n`;
+    }
+  }
+
+  text += `\nThis structure replaces any default you would otherwise use. `;
+  text += `The sections marked "must cover" are what your exploration and your questions `;
+  text += `must be able to answer before you produce the document.\n\n`;
+  return text;
+}
+
 // Tool: Submit tech analysis
 server.tool(
   'submit_tech_analysis',
@@ -315,6 +400,216 @@ server.tool(
   }
 );
 
+// ══ DEMAND ANALYSIS ════════════════════════════════════════════════════════
+//
+// The demand-level counterpart of the three tools above. A DEMAND has no project yet —
+// which projects it lands in is decided at IT Eval, from what this analysis finds — so
+// the context carries the whole workspace's repositories and the submission reports
+// which of them the change actually touches.
+
+// Tool: List pending demand analyses
+server.tool(
+  'list_demand_analyses',
+  'List demand technical analyses assigned to you in Konductro. A demand sits above projects: it is a business request that has passed the demand forum and now needs sizing against the real code.',
+  {},
+  async () => {
+    if (!KONDUCTRO_URL || !CLI_TOKEN) {
+      return {
+        content: [{
+          type: 'text',
+          text: 'Konductro is not configured. Please set your Konductro URL and CLI token in the plugin settings.',
+        }],
+      };
+    }
+
+    const { tasks } = await konductroFetch('/api/cli/demand-analyses');
+
+    if (!tasks || tasks.length === 0) {
+      return {
+        content: [{ type: 'text', text: 'No demand analyses assigned to you.' }],
+      };
+    }
+
+    const lines = tasks.map((t) => {
+      const parts = [`### ${t.key} — ${t.title}`];
+      if (t.businessUnit) parts.push(`**Business unit:** ${t.businessUnit}`);
+      if (t.nextSitting) parts.push(`**Back at the forum:** ${new Date(t.nextSitting).toISOString().slice(0, 10)}`);
+      if (t.startWith && t.startWith.length) parts.push(`**Start with:** ${t.startWith.join(', ')}`);
+      if (t.askedFor) parts.push(`**They asked:** ${t.askedFor}`);
+      parts.push(`\`get_demand_analysis_context\` with demandId ${t.key} to load it.`);
+      return parts.join('\n');
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: `## Demand analyses assigned to you (${tasks.length})\n\n${lines.join('\n\n')}`,
+      }],
+    };
+  }
+);
+
+// Tool: Load one demand's analysis context
+server.tool(
+  'get_demand_analysis_context',
+  'Load everything needed to run a demand technical analysis: the pitch as the business wrote it, the value case, what the forum asked to have answered, the repositories to start with, and every repository in the workspace.',
+  {
+    demandId: z.string().describe('The demand key (e.g. DEM-4) or its UUID'),
+  },
+  async ({ demandId }) => {
+    if (!KONDUCTRO_URL || !CLI_TOKEN) {
+      return {
+        content: [{
+          type: 'text',
+          text: 'Konductro is not configured. Please set your Konductro URL and CLI token in the plugin settings.',
+        }],
+      };
+    }
+
+    const ctx = await konductroFetch(`/api/cli/demand-analyses/${demandId}/context`);
+    const d = ctx && ctx.demand;
+    if (!d) {
+      return {
+        content: [{
+          type: 'text',
+          text: `No demand context came back for ${demandId}. Check the key, and that the analysis is assigned to you.`,
+        }],
+      };
+    }
+
+    const cost = Object.entries(d.cost || {})
+      .filter(([, v]) => v)
+      .map(([k, v]) => `- **${k}:** ${v}`)
+      .join('\n') || '- Not given';
+
+    // THE PROJECT ID IS THE POINT OF THIS LIST, not decoration. `submit_demand_analysis`
+    // takes a `projectId` per proposed phase, and its description says to take it from
+    // here. Rendering only the project NAME left the analyst nowhere to get it: either
+    // the phase is submitted with no project, so the green light creates no real Phase
+    // and IT Eval prefills with nothing, or the agent invents a uuid and the whole
+    // submission is refused with PROJECT_NOT_FOUND.
+    const repos = (ctx.repositories || [])
+      .map((r) => `- \`${r.name}\` (${r.projectName}${r.type ? `, ${r.type}` : ''}) — ${r.url}\n  projectId: \`${r.projectId}\``)
+      .join('\n') || '- None linked to any project yet';
+
+    const conversation = (ctx.conversation || [])
+      .map((c) => `- **${c.by}**${c.kind === 'amendment' ? ' (amendment)' : ''}: ${c.body}`)
+      .join('\n');
+
+    // THE WORKSPACE'S OWN QUESTIONS, which the block above does not carry.
+    //
+    // The fields rendered above are the nine Konductro ships. A workspace that added
+    // "Which regulator requires this?" has that question and its answer here and
+    // NOWHERE ELSE in this payload, so without this the analysis never learns it was
+    // asked — the one thing the whole templating feature exists for.
+    //
+    // Read off the PINNED template, so a question a later template deleted still shows
+    // on the demands that answered it. Unanswered questions are kept rather than
+    // dropped: that the forum asked and got nothing is itself worth knowing.
+    const tpl = ctx.template;
+    const templateBlock = tpl
+      ? [
+          `## The form they filled in — ${tpl.name} v${tpl.version}`,
+          '',
+          ...(tpl.sections || []).flatMap((section) => [
+            `### ${section.name}`,
+            ...(section.help ? ['', `_${section.help}_`] : []),
+            '',
+            ...(section.questions || []).map((q) =>
+              `**${q.question}**\n\n${q.answer || '_Not answered._'}\n`
+            ),
+          ]),
+        ].join('\n')
+      : '';
+
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `# ${d.key} — ${d.title}`,
+          '',
+          `**Raised by:** ${d.raisedBy}${d.businessUnit ? ` (${d.businessUnit})` : ''}`,
+          '',
+          '## What they need',
+          d.need,
+          '',
+          '## What happens today',
+          d.currentState || 'Not given',
+          '',
+          '## Who it affects',
+          [d.affects, d.affectsWho].filter(Boolean).join(' — ') || 'Not given',
+          '',
+          '## What it costs to not have it',
+          cost,
+          '',
+          '## Tied to a date',
+          d.date?.type ? `${d.date.type}${d.date.by ? ` — ${String(d.date.by).slice(0, 10)}` : ''}${d.date.why ? ` (${d.date.why})` : ''}` : 'No fixed date',
+          '',
+          '## How they would know it worked',
+          d.successLooksLike || 'Not given',
+          '',
+          '## What the forum asked you to answer',
+          ctx.askedFor || 'Nothing specific. Answer the pitch.',
+          '',
+          '## Where to start looking',
+          (ctx.startWith && ctx.startWith.length) ? ctx.startWith.map((r) => `\`${r}\``).join(', ') : 'Nothing named — use your judgement.',
+          '',
+          '## Every repository in this workspace',
+          'The starting point above is a hint, not a boundary. Report what the change ACTUALLY touches.',
+          '',
+          repos,
+          templateBlock ? `\n${templateBlock}` : '',
+          conversation ? `\n## Conversation on the demand\n${conversation}` : '',
+        ].join('\n'),
+      }],
+    };
+  }
+);
+
+// Tool: Submit a demand analysis
+server.tool(
+  'submit_demand_analysis',
+  'Push a finished demand technical analysis back to Konductro: what you found, which repositories the change actually touches, and the phase breakdown you propose. The breakdown is a PROPOSAL — the demand forum decides at IT Eval.',
+  {
+    demandId: z.string().describe('The demand key (e.g. DEM-4) or its UUID'),
+    summary: z.string().describe('What the analysis found, in markdown. What is already there, what has to change, the risks, and the assumptions the estimate rests on.'),
+    // BOTH OF THESE ARE CLEARED WHEN OMITTED, server-side and deliberately: a
+    // resubmission that dropped them used to keep the OLD proposal while the repos
+    // beside it reset to empty, leaving an analysis half from one run and half from
+    // another — which IT Eval then prefills from. So a second submission has to send
+    // all three fields or lose the two it leaves out.
+    foundRepos: z.array(z.string()).optional().describe('The repositories the change actually touches, by name. Not the ones you were told to start with. Resubmitting without this CLEARS it.'),
+    proposedPhases: z.array(z.object({
+      name: z.string().describe('What this phase delivers'),
+      projectId: z.string().uuid().optional().describe('The project it lands in, from the context. Omit if it genuinely belongs nowhere yet.'),
+      points: z.number().int().min(0).max(1000).describe('Story points for this phase alone. Never send a total; Konductro derives it.'),
+      why: z.string().optional().describe('Why it is its own phase rather than part of another'),
+    })).optional().describe('The phases you propose. A phase belongs to ONE project; work spanning two projects is two phases. Resubmitting without this CLEARS it.'),
+  },
+  async ({ demandId, summary, foundRepos, proposedPhases }) => {
+    if (!KONDUCTRO_URL || !CLI_TOKEN) {
+      return {
+        content: [{
+          type: 'text',
+          text: 'Konductro is not configured. Please set your Konductro URL and CLI token in the plugin settings.',
+        }],
+      };
+    }
+
+    const result = await konductroFetch(`/api/cli/demand-analyses/${demandId}/submit`, {
+      method: 'POST',
+      body: JSON.stringify({ summary, foundRepos, proposedPhases }),
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: `## Demand analysis submitted\n\n${result.message}\n\n- Demand: ${result.key}\n- Submitted: ${result.submittedAt}\n\nThe demand forum has been notified and can now record the IT Eval.`,
+      }],
+    };
+  }
+);
+
 // Tool: List pending decomposition tasks
 server.tool(
   'list_decomposition_tasks',

package/skills/demand-analysis.mdc

@@ -0,0 +1,107 @@
+---
+description: USE WHEN an architect has been assigned a Konductro DEMAND technical analysis — a business request that has passed the demand forum and needs sizing against the real code before the forum will commit to it
+globs:
+alwaysApply: false
+---
+
+# Konductro Demand Analysis
+
+A demand is a business request that sits ABOVE projects. It has passed the demand forum,
+and the forum will not commit to it until somebody has read the actual code and said what
+it entails. That is this job.
+
+## What makes this different from a phase's technical analysis
+
+A phase already belongs to a project, so its repositories are known. **A demand does not.**
+Which projects the work lands in is decided at IT Eval, FROM WHAT YOU FIND. So:
+
+- The context lists **every repository in the workspace**, not a project's few.
+- The "start with" list is a hint from whoever assigned it. It is not a boundary, and it
+  is regularly wrong: the work turns out to be in a repository nobody expected.
+- You report which repositories the change **actually touches**. That is what the forum
+  reads, and it is stored separately from the hint you were given.
+
+## Workflow
+
+### Step 1: See what is assigned
+
+Call `list_demand_analyses`. Present the list and ask which one to work on. Each shows
+what the forum asked to have answered and when it is next sitting — that date is the
+deadline, so say it out loud.
+
+### Step 2: Load the context
+
+Call `get_demand_analysis_context` with the demand key. Read the whole thing before
+touching any code. It carries:
+
+- The pitch, in the business's own words, and what happens today
+- The value case: who it affects, and what it costs to not have it
+- **The form they actually filled in**, which is the workspace's own template rather
+  than a fixed set of questions. A workspace that asks "Which regulator requires this?"
+  has that question and its answer here and nowhere else, and it is usually the one that
+  changes the estimate. Read it.
+- What the forum specifically asked you to answer
+- Every repository in the workspace, with its project
+
+**Say the value case back to the user in one line.** An estimate has to be proportionate
+to the thing being bought, and this is the only place that number appears.
+
+### Step 3: Read the code
+
+The repositories are on this machine. Use Glob, Grep and Read. Konductro never clones
+anything and neither do you: if a repository named in the context is not present locally,
+say so rather than guessing at it.
+
+Start with the repositories you were pointed at, then follow the work wherever it goes.
+
+What you are trying to establish, in this order:
+
+1. **What already exists.** Half of every demand turns out to be built. Say what is there
+   before you say what is needed.
+2. **What actually has to change**, per repository, concretely enough that somebody could
+   argue with it.
+3. **What is in the way.** Missing data, an integration nobody has written, a migration
+   with no way back.
+4. **What the estimate rests on.** Every assumption you make is a way the number could be
+   wrong, and the forum is told which one when it is.
+
+### Step 4: Propose the phases
+
+This is the part the forum needs most, and the part it cannot do itself.
+
+- **A phase belongs to ONE project.** Work spanning two projects is two phases. This is
+  not a formality: each phase becomes a real Phase in that project when the demand is
+  green lit.
+- **Order them by what has to land first.** If phase two cannot start until phase one is
+  deployed, say so in its `why`.
+- **Points per phase, never a total.** Konductro derives the total. Sending your own is
+  how the headline number and the breakdown behind it end up disagreeing.
+- **A phase with no obvious home** is allowed: omit `projectId` and say why in the `why`.
+  A visible gap beats a phase filed in whichever project came first.
+
+### Step 5: Submit
+
+Call `submit_demand_analysis` with:
+
+- `summary` — what you found. Structure it as: what exists, what has to change, risks,
+  assumptions. Markdown.
+- `foundRepos` — the repositories the change actually touches. Not the hint you were given.
+- `proposedPhases` — the breakdown above.
+
+The forum is notified and records the IT Eval from your proposal. They can change any of
+it; you are advising, not deciding.
+
+**If you submit a second time, send all three again.** `foundRepos` and `proposedPhases`
+are cleared when they are left out, deliberately: a resubmission that kept the old
+proposal beside freshly reset repositories would be half one run and half another, and
+IT Eval prefills from it.
+
+## The bar
+
+**Never estimate something you have not read.** An unfamiliar name is a reason to go and
+look, never a reason to assume it is small. If a repository you need is not on this
+machine, the honest output is a summary that says which one and what it blocks — not a
+number with a shrug behind it.
+
+**Say what you did not check.** The forum is about to commit money against this. A gap you
+name costs an hour; a gap you paper over costs the quarter.

package/skills/technical-analysis.mdc

@@ -20,11 +20,20 @@ Call `get_task_context` with the phase ID. This loads:
 - The approved requirements document (what needs to be built)
 - Project and client context
 - Repository information
+- A "Refresh Requested" section, when someone has asked for an existing analysis
+  to be redone. Read it first: it carries the requester's reason, and the job is
+  to revise the previous analysis rather than start from scratch.
 
 Share a summary of the requirements with the user and confirm you're ready to begin.
 
 ### Step 3: Explore the Codebase
 
+**If the context carried a "Required Document Structure", that is your brief.** Every section in it is something you must be able to answer by the end of this step, and the ones marked "must cover" are not optional. Explore with those sections in mind rather than working through the generic list below and hoping it covers them — a workspace that asks for a Regulatory Impact section is telling you what to go and find out, and nothing in the generic list will lead you there.
+
+Where the structure asks for something the generic list does not cover, go and look for it. Where it omits something, you do not need to chase it.
+
+If no structure was supplied, use the list below as-is.
+
 Analyse the local codebase using file reading and search tools:
 - **Project structure** — folder layout, module organisation
 - **Tech stack** — frameworks, versions, build tools
@@ -40,6 +49,10 @@ Discuss findings with the user as you go. Ask clarifying questions.
 
 ### Step 4: Impact Analysis
 
+**Before moving on, check yourself against the required structure.** Take each section, and each "must cover" section especially, and ask whether you could write it now from what you have found. Where you could not, that is a question for the user or another pass over the codebase — ask it now rather than discovering the gap while writing the document, when the honest options are guessing or going back.
+
+This is the step that makes the structure mean something. Producing the right headings over content that does not answer them is worse than the default document, because it looks like compliance.
+
 Based on the requirements and your codebase exploration, assess:
 - **What needs to change** — which files, modules, or services
 - **What needs to be created** — new components, services, APIs
@@ -49,7 +62,12 @@ Based on the requirements and your codebase exploration, assess:
 
 ### Step 5: Produce the Document
 
-Produce a structured technical analysis document including:
+**If the context carried a "Required Document Structure", follow it exactly** — those sections, in that order, under those headings. It replaces the default list below rather than supplementing it: do not add the default sections alongside it, and do not reorder it to something you find more natural. Where a section carries standing content, reproduce that text word for word; it is usually a clause the workspace is required to publish, and paraphrasing it defeats the point of it being there. Where a section asks for a diagram, draw one, as Mermaid, inside that section.
+
+A document produced here must be indistinguishable from one produced for the same workspace in Konductro itself. That is the whole purpose of the structure being sent.
+
+**If no structure was supplied**, use this default list:
+
 1. **Codebase Overview** — what exists today
 2. **Technical Stack** — frameworks, versions, build tools, deployment
 3. **Architecture Patterns** — structure, key design decisions
@@ -72,3 +90,4 @@ Ask the user to review the document. When approved, call `submit_tech_analysis`
 - Be thorough but focused — analyse what's relevant to the requirements
 - Ask the user questions — they know the codebase context you don't
 - Produce a complete, standalone document an architect can use without additional context
+- When a required document structure is supplied, it wins over anything in this file. It is the workspace's own standard, and your job is to meet it, not to improve on it