@konductro/claude-plugin 2.0.0 → 2.1.0

package/README.md

@@ -35,6 +35,7 @@ Skills are guided, multi-step workflows invoked with a slash command:
 | `/find-prototype` | Find and download the approved UX prototype for the current project |
 | `/profile-repository` | Scan the current repo and submit its profile to Konductro |
 | `/start-ticket` | Pick up an assigned ticket — creates branch, pushes ticket spec, sets status |
+| `/bug-enrich` | Enrich a bug ticket with technical analysis — explores codebase and submits structured context |
 
 ## Tools
 
@@ -82,6 +83,8 @@ Tools are called automatically by Claude based on natural language. You don't in
 | Tool | What it does |
 |---|---|
 | `profile_repository` | Submit a repository profile (tech stack, APIs, dependencies) |
+| `get_bug_for_enrichment` | Load a bug ticket and project context for enrichment |
+| `submit_bug_enrichment` | Submit structured technical enrichment for a bug ticket |
 
 ### Examples
 

package/package.json

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

package/servers/konductro-api.js

@@ -882,6 +882,87 @@ server.tool(
   }
 );
 
+// Tool: Get bug context for enrichment
+server.tool(
+  'get_bug_for_enrichment',
+  'Load a bug ticket and its project context for enrichment. Returns the bug description, acceptance criteria, project name, and existing notes.',
+  {
+    ticketId: z.string().describe('The ticket ID or key (e.g. KON-42) of the bug to enrich'),
+  },
+  async ({ ticketId }) => {
+    try {
+      const ctx = await konductroFetch(`/api/cli/bugs/${encodeURIComponent(ticketId)}/context`);
+
+      let text = `## Bug Context\n\n`;
+      text += `**Ticket:** ${ctx.key} — ${ctx.title}\n`;
+      text += `**Project:** ${ctx.projectName ?? 'Unknown'}\n`;
+      text += `**Phase:** ${ctx.phaseName ?? 'Unknown'}\n`;
+      if (ctx.componentPath) text += `**Component:** ${ctx.componentPath}\n`;
+      if (ctx.repository) text += `**Repository:** ${ctx.repository.name} (${ctx.repository.repoType}) — ${ctx.repository.repoUrl}\n`;
+      text += `\n`;
+
+      text += `### Description\n\n${ctx.description}\n\n`;
+
+      if (ctx.acceptanceCriteria?.length > 0) {
+        text += `### Acceptance Criteria\n\n`;
+        ctx.acceptanceCriteria.forEach((ac, i) => { text += `${i + 1}. ${ac}\n`; });
+        text += `\n`;
+      }
+
+      if (ctx.architecturalNotes?.length > 0) {
+        text += `### Existing Notes\n\n`;
+        ctx.architecturalNotes.forEach(n => { text += `- ${n}\n`; });
+        text += `\n`;
+      }
+
+      return { content: [{ type: 'text', text }] };
+    } catch (err) {
+      const msg = err.message?.includes('BUG_NOT_FOUND') || err.message?.includes('404')
+        ? `Ticket ${ticketId} not found or is not a bug.`
+        : `Failed to load bug context: ${err.message}`;
+      return { content: [{ type: 'text', text: msg }], isError: true };
+    }
+  }
+);
+
+// Tool: Submit bug enrichment
+server.tool(
+  'submit_bug_enrichment',
+  'Submit structured technical enrichment for a bug ticket. At least one field must be provided. The enrichment is append-only — the original description is never modified.',
+  {
+    ticketId: z.string().describe('The ticket ID or key (e.g. KON-42) of the bug to enrich'),
+    suspectedRootCause: z.string().optional().describe('Your assessment of why the bug occurs'),
+    affectedComponents: z.array(z.string()).optional().describe('File paths or module names involved'),
+    stackTraceHints: z.array(z.string()).optional().describe('Relevant error origins, log lines, or exception paths'),
+    investigationSteps: z.array(z.string()).optional().describe('What you checked and what you found'),
+    verifyFixCriteria: z.array(z.string()).optional().describe('Conditions that confirm the bug is fixed (appended to acceptance criteria)'),
+  },
+  async ({ ticketId, suspectedRootCause, affectedComponents, stackTraceHints, investigationSteps, verifyFixCriteria }) => {
+    if (!suspectedRootCause && !affectedComponents?.length && !stackTraceHints?.length && !investigationSteps?.length && !verifyFixCriteria?.length) {
+      return { content: [{ type: 'text', text: 'At least one enrichment field must be provided.' }], isError: true };
+    }
+
+    try {
+      const result = await konductroFetch(`/api/cli/bugs/${encodeURIComponent(ticketId)}/enrich`, {
+        method: 'POST',
+        body: JSON.stringify({ suspectedRootCause, affectedComponents, stackTraceHints, investigationSteps, verifyFixCriteria }),
+      });
+
+      const applied = result.fieldsApplied?.length > 0
+        ? `Enrichment applied: ${result.fieldsApplied.join(', ')}`
+        : 'No new enrichment applied (fields may already exist on the ticket).';
+      return { content: [{ type: 'text', text: applied }] };
+    } catch (err) {
+      const msg = err.message?.includes('BUG_NOT_FOUND') || err.message?.includes('404')
+        ? `Ticket ${ticketId} not found or is not a bug.`
+        : err.message?.includes('INVALID_ENRICHMENT')
+        ? 'At least one enrichment field must be provided.'
+        : `Failed to submit enrichment: ${err.message}`;
+      return { content: [{ type: 'text', text: msg }], isError: true };
+    }
+  }
+);
+
 // Start the server
 async function main() {
   const transport = new StdioServerTransport();

package/skills/bug-enrich/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: bug-enrich
+description: Enrich an existing bug ticket with technical analysis. Use when assigned to triage a bug — fetches the ticket, explores the codebase locally, and submits structured technical context back to Konductro.
+allowed-tools: Read, Grep, Glob, Bash, mcp__konductro__get_bug_for_enrichment, mcp__konductro__submit_bug_enrichment
+---
+
+# Konductro Bug Enrichment
+
+You are enriching an existing bug ticket with technical context for the Konductro delivery platform. Your role is to add structured technical detail — never to rewrite or modify the user's original bug description.
+
+## Critical Constraint
+
+**DO NOT modify the original `description` of the ticket.** The enrichment is append-only. Your job is to add technical context (root cause, affected components, investigation steps) — the user's original report is preserved byte-for-byte by the server.
+
+## Workflow
+
+### Step 1: Accept Ticket ID
+
+The user provides a ticket ID (e.g. `KON-42` or a UUID) as a positional argument from `/bug-enrich <ticket-id>`.
+
+### Step 2: Load Bug Context
+
+Call `get_bug_for_enrichment` with the ticket ID. This returns:
+- The bug title, description, and existing acceptance criteria
+- Project and phase context
+- Any existing architectural notes or component path
+
+Review the bug report and share a summary with the user. Confirm you understand the issue.
+
+### Step 3: Explore the Codebase
+
+The user has the target repository cloned locally. Use Glob, Grep, and Read to investigate:
+
+- **Affected code paths** — trace the flow described in the bug report
+- **Potential root cause** — look for the code that could produce the described behaviour
+- **Related components** — what files/modules are involved
+- **Stack trace clues** — if error messages are mentioned, find where they originate
+- **Fix verification** — what would need to be true for the bug to be resolved
+
+Focus your exploration on what's relevant to the bug. Don't scan the entire codebase.
+
+### Step 4: Plan the Enrichment
+
+Based on your investigation, prepare structured enrichment fields:
+
+- **suspectedRootCause** — your best assessment of why the bug occurs (reference specific code)
+- **affectedComponents** — file paths or module names involved
+- **stackTraceHints** — relevant error origins, log lines, or exception paths
+- **investigationSteps** — what you checked and what you found
+- **verifyFixCriteria** — specific conditions that confirm the bug is fixed (these get appended to acceptance criteria)
+
+Present your findings to the user before submitting.
+
+### Step 5: Submit Enrichment
+
+After the user approves, call `submit_bug_enrichment` with the ticket ID and your structured findings. The server applies them using append-only rules:
+- `architecturalNotes` receives prefixed entries
+- `componentPath` is set only if currently empty
+- `acceptanceCriteria` receives verify-fix criteria (de-duplicated)
+
+Report success and summarise what was applied.
+
+## Important Rules
+
+- Always load the bug context first — don't assume or hallucinate ticket contents
+- Explore the ACTUAL local codebase — don't invent file paths or code snippets
+- Reference specific files, line numbers, and function names in your findings
+- Present findings for user review before submitting
+- Never modify the original description — enrichment is additive only
+- If you can't find relevant code, say so honestly rather than guessing