@konductro/claude-plugin 2.4.0-rc.1 → 2.4.0-rc.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@konductro/claude-plugin",
-  "version": "2.4.0-rc.1",
-  "description": "Claude Code plugin for the Konductro platform — technical analysis and delivery tasks",
+  "version": "2.4.0-rc.2",
+  "description": "Claude Code plugin for the Konductro platform \u2014 technical analysis and delivery tasks",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/servers/konductro-api.js

@@ -11,6 +11,7 @@
  *   KONDUCTRO_CLI_TOKEN — Personal CLI access token
  */
 
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -18,10 +19,29 @@ import { z } from 'zod';
 const KONDUCTRO_URL = process.env.KONDUCTRO_URL?.replace(/\/$/, '') || '';
 const CLI_TOKEN = process.env.KONDUCTRO_CLI_TOKEN || '';
 
+/*
+ * 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 = `claude/${PLUGIN_VERSION}`;
+
 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
@@ -300,6 +320,8 @@ server.tool(
       }
     }
 
+    contextText += renderDocumentTemplate(context.documentTemplate);
+
     return {
       content: [{
         type: 'text',
@@ -309,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',

package/skills/technical-analysis/SKILL.md

@@ -28,7 +28,13 @@ Share a summary of the requirements with the user and confirm you're ready to be
 
 ### Step 3: Explore the Codebase
 
-Now analyse the local codebase. The user has the repository/repositories cloned in their current working directory. Use Glob, Grep, and Read to explore:
+**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.
+
+The user has the repository/repositories cloned in their current working directory. Use Glob, Grep, and Read to explore:
 
 - **Project structure** — folder layout, module organisation
 - **Tech stack** — frameworks, versions, build tools (check package.json, pom.xml, build.gradle, etc.)
@@ -44,6 +50,10 @@ Discuss your findings with the user as you go. Ask clarifying questions about de
 
 ### 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 need modification
@@ -54,7 +64,13 @@ Based on the requirements and your codebase exploration, assess:
 
 ### Step 5: Produce the Document
 
-When the user is satisfied with the analysis, produce a structured technical analysis document. The document must include:
+When the user is satisfied with the analysis, produce the document.
+
+**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 (structure, stack, patterns)
 2. **Technical Stack** — frameworks, versions, build tools, deployment
@@ -83,4 +99,5 @@ After submission, confirm success and let the user know the document is availabl
 - 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 that 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
 - The conversation summary should capture the "why" behind decisions, not just the findings