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

package/README.md

@@ -122,7 +122,7 @@ These are answers, not errors — none of them is worth retrying as-is.
 | Tool | What it does |
 |---|---|
 | `list_tech_analysis_tasks` | List your pending technical analysis assignments |
-| `get_task_context` | Load requirements and project context for a tech analysis task |
+| `get_task_context` | Load requirements and project context for a tech analysis task, plus the requester's context message when a refresh was asked for |
 | `submit_tech_analysis` | Submit your analysis document back to Konductro |
 
 ### Story decomposition

package/package.json

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

package/servers/konductro-api.js

@@ -94,6 +94,14 @@ function refusalText(err) {
       return 'Refused: your role on this project is read-only (viewer or stakeholder), so you cannot create or change work items here. Ask an SDM to give you a writing role on the project.';
     case 'NOT_PROJECT_MEMBER':
       return 'Refused: you are not a member of this project, so you cannot create or change work items in it. Ask an SDM to add you to the project team.';
+    // ── demand analysis (KON-606) ──
+    case 'NOT_YOUR_DEMAND':
+      return 'Refused: the technical analysis for this demand is assigned to somebody else. Only they, or the chair of the demand forum, can submit it. Ask the chair to reassign it if it should be yours.';
+    case 'WRONG_STAGE':
+      // Two different situations behind one code, and the backend says which in its
+      // message: the demand has moved past `pitched`, or nobody has been assigned the
+      // analysis yet. Neither is worth retrying, so pass its sentence through.
+      return null;
     default:
       return null;
   }
@@ -217,7 +225,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 {
@@ -247,6 +255,25 @@ server.tool(
     if (context.phase.description) contextText += `**Description:** ${context.phase.description}\n`;
     contextText += `\n`;
 
+    // KON-318: 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) {
@@ -306,6 +333,177 @@ 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.',
+  {},
+  // workItemCall, not a hand-rolled config check: it asserts the token, turns a 401 into
+  // a setup sentence, routes a refusal through refusalText keyed on CODE (KON-517), and
+  // FLAGS a genuine failure with isError so the agent stops rather than carrying on. The
+  // config check this replaces returned a plain success result, so an unconfigured plugin
+  // read to the agent as "no work assigned".
+  async () => workItemCall(async () => {
+    const { tasks } = await konductroFetch('/api/cli/demand-analyses');
+
+    if (!tasks || tasks.length === 0) {
+      return '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 `## 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 }) => workItemCall(async () => {
+    const ctx = await konductroFetch(`/api/cli/demand-analyses/${encodeURIComponent(demandId)}/context`);
+    const d = ctx && ctx.demand;
+    if (!d) {
+      return `No demand context came back for ${demandId}. Check the key, and that the analysis is assigned to you.`;
+    }
+
+    const tpl = ctx.template;
+
+    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 a phase without one creates no real
+    // Phase at green light. Rendering only the project NAME left the analyst with no way
+    // to supply it, so every phase would have landed homeless and the green light would
+    // have created nothing.
+    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');
+
+    return [
+          `# ${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',
+          '',
+          // THE WORKSPACE'S OWN QUESTIONS. The endpoint returns the PINNED template —
+          // the one this demand was actually raised on, so a question a later template
+          // deleted still appears here. Dropping it meant a workspace that asks "Which
+          // regulator requires this?" had that answer invisible to the analyst, which is
+          // the entire point of the templating feature.
+          ...(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}** ${q.answer ? `\n  ${q.answer}` : '\n  _Left blank._'}`),
+                ]),
+              ]
+            : []),
+          '',
+          '## 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,
+          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.'),
+    foundRepos: z.array(z.string()).optional().describe('The repositories the change actually touches, by name. Not the ones you were told to start with.'),
+    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.'),
+  },
+  async ({ demandId, summary, foundRepos, proposedPhases }) => workItemCall(async () => {
+    const result = await konductroFetch(`/api/cli/demand-analyses/${encodeURIComponent(demandId)}/submit`, {
+      method: 'POST',
+      body: JSON.stringify({ summary, foundRepos, proposedPhases }),
+    });
+
+    const homeless = (proposedPhases ?? []).filter((ph) => !ph.projectId).length;
+
+    return [
+      '## Demand analysis submitted',
+      '',
+      result.message,
+      '',
+      `- Demand: ${result.key}`,
+      `- Submitted: ${result.submittedAt}`,
+      // A phase with no project creates no real Phase at green light. That is allowed
+      // and is sometimes the honest answer, but it is worth saying out loud here rather
+      // than letting the forum discover it when nothing gets created.
+      ...(homeless
+        ? ['', `**${homeless} phase${homeless === 1 ? '' : 's'} named no project**, so ${homeless === 1 ? 'it' : 'they'} will not create real work at green light until the forum assigns one.`]
+        : []),
+      '',
+      'The demand forum has been notified and can now record the IT Eval.',
+    ].join('\n');
+  })
+);
+
 // Tool: List pending decomposition tasks
 server.tool(
   'list_decomposition_tasks',

package/skills/demand-analysis/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: demand-analysis
+description: Size a Konductro DEMAND against the real code. Use when an architect has been assigned a demand technical analysis — a business request that has passed the demand forum and now needs to be broken into phases and estimated before the forum will commit to it.
+allowed-tools: Read, Grep, Glob, Bash, mcp__konductro__list_demand_analyses, mcp__konductro__get_demand_analysis_context, mcp__konductro__submit_demand_analysis
+---
+
+# 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**, question by question, on the template the demand
+  was RAISED against — so a question this workspace added appears, and one a later
+  template deleted still appears on the demands that answered it
+- What the forum specifically asked you to answer
+- Every repository in the workspace, with its project and that project's `projectId`
+
+**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.
+- **Take `projectId` from the repository list in the context**, where it is printed under
+  each repository. A phase without one creates no real Phase at green light, so guessing
+  is worse than omitting.
+- **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.
+
+## 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/SKILL.md

@@ -20,6 +20,9 @@ Once the user picks a task, call `get_task_context` with the phase ID. This load
 - 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.