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

package/README.md

@@ -50,6 +50,73 @@ Tools are called automatically by Claude based on natural language. You don't in
 | `start_work` | Start work on a ticket — creates branch via ADO, pushes spec file, sets in_progress |
 | `create_pr` | Create a pull request for a ticket — auto-assigns reviewer, moves ticket to pr_open |
 
+### Work items
+
+| Tool | What it does |
+|---|---|
+| `create_work_item` | Create a story, task or bug in the project this repo belongs to |
+| `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 |
+
+The project is resolved from the repository's git remote, so you are never asked for a
+project identifier.
+
+**Everything created lands in Draft** and still needs an SDM's approval before it can be
+worked on.
+
+**`update_work_item` can change three fields and no others.** Status, sprint, assignee and
+everything else are deliberately not on the schema — change those in Konductro. Sending
+`acceptanceCriteria` replaces the whole list rather than appending to it. The `changed`
+list it reports back is the fields that were written, not the ones that turned out to
+differ, so re-sending a value unchanged still shows up in it.
+
+**A task is created in the repository you are standing in.** Its parent story is the only
+thing you need to name. Set `repositoryId` yourself only for a task that will be built in a
+different repository on the same project.
+
+**Only a task may have a parent.** A story or a bug sent with a `parentKey` is refused and
+nothing is created, rather than being filed top-level as though it had worked. A bug is
+always standalone here — Konductro parents one to a story only when QA files it against a
+failed test criterion — so name the story in the description instead. A story is top-level
+by definition: the hierarchy is story → task, and work that belongs under a story is a task.
+
+**`create_work_item` returns the new item's id.** Use it for the follow-up call. Ticket
+keys are prefix plus number and the prefix is not returned, so a guessed key resolves to a
+different project's item of the same number instead of failing.
+
+#### Who can create and change stories
+
+Each project has a story access setting, which an SDM controls under Settings → General:
+
+| Setting | What a developer can do |
+|---|---|
+| **Planning roles only** | Cannot create or change stories. Filing bugs and editing tasks are unaffected. |
+| **Developers can, with review** | Changes apply straight away, then wait for an SDM to approve or reject. |
+| **Developers can, no review** | Creates and changes apply with nothing held for approval. |
+
+A new project starts on **planning roles only**.
+
+Under *with review*, a change to a story is applied and then held: the story will not move
+to Ready for QA until an SDM resolves it, even once every task is done. If it is rejected,
+the previous values are restored and you are notified.
+
+#### What a refusal means
+
+These are answers, not errors — none of them is worth retrying as-is.
+
+| You will see | What to do |
+|---|---|
+| The project's story access is set to planning roles only | A project setting. Ask an SDM to make the change, or to open story access for developers. |
+| You can only change work items assigned to you, that you are the developer on, or that you created | Ask whoever owns it, or ask an SDM. |
+| Stories cannot be deleted from the CLI | Deleting a story removes its tasks with it. Archive it in Konductro instead. |
+| QA filed this bug against a failed test criterion | It is QA's record of a failure, not yours to remove. |
+| Only a task can be created under a parent | Nothing was created. For a bug, re-run without `parentKey` and name the story in the description. For a story, you probably wanted `kind: "task"`. |
+| Work has already started on this item | It has a branch, or has moved past sprint planning. Only items still in draft, approved or in_sprint can be deleted. |
+| Your seat is a viewer seat | Read-only across the whole platform, not a project setting. Ask an admin for a contributor seat. |
+| Your role on this project is read-only | Ask an SDM for a writing role on the project. |
+| You are not a member of this project | Ask an SDM to add you to the project team. |
+| Not authenticated | A setup problem rather than a permissions one — your `KONDUCTRO_CLI_TOKEN` is missing, expired or revoked. Create a new one in Konductro under your profile. |
+
 ### Technical analysis
 
 | Tool | What it does |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konductro/claude-plugin",
-  "version": "2.1.1",
+  "version": "2.3.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

@@ -35,13 +35,156 @@ async function konductroFetch(path, options = {}) {
   });
 
   if (!response.ok) {
-    const body = await response.text().catch(() => '');
-    throw new Error(`Konductro API error (${response.status}): ${body}`);
+    const raw = await response.text().catch(() => '');
+    // KON-517: keep the machine-readable code and status on the error. The backend
+    // answers { error, code, details? }, and every tool should branch on CODE rather than
+    // on message text so a wording change server-side cannot break the plugin.
+    //
+    // NOTE this CHANGED err.message. It used to be the whole envelope —
+    // `Konductro API error (404): {"error":"Bug not found","code":"BUG_NOT_FOUND"}` — and
+    // is now just the `error` sentence. Anything that used to sniff the message for a
+    // status or a code no longer matches, so those call sites were moved onto err.code /
+    // err.status (get_bug_for_enrichment and submit_bug_enrichment). If you add a tool,
+    // read the code; do not go back to matching text.
+    let parsed = null;
+    try { parsed = JSON.parse(raw); } catch { /* not JSON — fall through to the raw body */ }
+    const err = new Error(
+      parsed?.error ? parsed.error : `Konductro API error (${response.status}): ${raw}`,
+    );
+    err.status = response.status;
+    err.code = parsed?.code ?? null;
+    // Zod's flatten() on a validation failure. Kept so a refusal can name the offending
+    // field instead of saying "Validation failed" and leaving the agent to guess.
+    err.details = parsed?.details ?? null;
+    throw err;
   }
 
   return response.json();
 }
 
+// ─── KON-517: work-item tools ────────────────────────────────────────────────
+
+/**
+ * Turn a backend refusal into a sentence a developer can act on.
+ *
+ * A bare 403 makes an agent retry or guess. Each of these says what to do instead, and
+ * the setting-related one NAMES the setting, because the developer's next move is to ask
+ * their SDM rather than to try again.
+ *
+ * Keyed on code, never on message text.
+ */
+function refusalText(err) {
+  switch (err.code) {
+    case 'STORY_ACCESS_DENIED':
+      return "Refused: this project's story access is set to planning roles only, so stories here can only be created or edited by an SDM, architect or UX lead. This is a project setting, not something to retry — ask an SDM to make the change, or to open story access for developers. Filing bugs and editing tasks are unaffected.";
+    case 'NOT_YOUR_WORK_ITEM':
+      return 'Refused: you can only change work items assigned to you, that you are the developer on, or that you created. Ask whoever owns it, or ask an SDM to make the change.';
+    case 'STORIES_NOT_DELETABLE':
+      return 'Refused: stories cannot be deleted from the CLI — deleting one removes its tasks with it and cannot be undone. Archive it in Konductro instead.';
+    case 'QA_FILED_BUG':
+      return "Refused: QA filed this bug against a failed test criterion, so it is their record of what went wrong and is not yours to remove. Fix it, or ask QA if it was raised in error.";
+    case 'WORK_ALREADY_STARTED':
+      // Mirrors DELETABLE_STATUSES in work-item-access.service.ts: draft, approved and
+      // in_sprint are all still deletable. Anything past those, or anything with a
+      // branch, is not.
+      return 'Refused: work has already started on this item — it has a branch, or has moved past sprint planning (only items still in draft, approved or in_sprint can be deleted). Deleting it would orphan the branch. Close it out in Konductro instead.';
+    case 'INSUFFICIENT_ROLE':
+      return 'Refused: your Konductro seat is a viewer seat, which is read-only across the whole platform. This is not a project setting — ask an admin to move you to a contributor seat.';
+    case 'READ_ONLY_ROLE':
+      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.';
+    default:
+      return null;
+  }
+}
+
+/**
+ * A missing token is a setup problem, not a permission problem — say so differently.
+ *
+ * The `setup` flag is what workItemCall branches on. It used to match these messages by
+ * their opening words, which meant a plugin whose setup wording differs (the codex and
+ * cursor ports name their own setup command) silently fell through and got the sentence
+ * wrapped in `Failed:`. Matching on our own wording is the same habit this change removes
+ * for BACKEND errors, so the flag is set explicitly here instead.
+ */
+function assertAuthConfigured() {
+  if (!CLI_TOKEN) {
+    const err = new Error(
+      'Not authenticated: KONDUCTRO_CLI_TOKEN is not set. Create a CLI token in Konductro under your profile, then set KONDUCTRO_CLI_TOKEN in this MCP server\'s environment. This is a setup problem, not a permissions one.',
+    );
+    err.setup = true;
+    throw err;
+  }
+  if (!KONDUCTRO_URL) {
+    const err = new Error('Not configured: KONDUCTRO_URL is not set. Point it at your Konductro instance.');
+    err.setup = true;
+    throw err;
+  }
+}
+
+/**
+ * Name the field a validation failure is actually about.
+ *
+ * The backend answers INVALID_BODY with Zod's flatten() attached. Dropping it leaves the
+ * agent holding "Validation failed" with nothing to correct, which it can only respond to
+ * by guessing — so the whole point of validating is lost on the way back.
+ */
+function validationText(err) {
+  const f = err.details?.fieldErrors ?? {};
+  const fields = Object.entries(f)
+    .map(([name, msgs]) => `${name} (${(msgs ?? []).join('; ')})`)
+    .join(', ');
+  const form = (err.details?.formErrors ?? []).join('; ');
+  const parts = [fields, form].filter(Boolean).join(' — ');
+  if (!parts) return err.message;
+  // The backend's sentence for this code is sometimes unpunctuated ('Validation failed'),
+  // so close it before appending rather than running the two together.
+  const lead = /[.!?]$/.test(err.message) ? err.message : `${err.message}.`;
+  return `${lead} Problem with: ${parts}.`;
+}
+
+/**
+ * Every work-item tool answers refusals the same way, so the cases read alike.
+ *
+ * ON isError. A REFUSAL is not an error — it is a correct, final answer to a question the
+ * developer was entitled to ask, and flagging it as an error is what makes an agent retry
+ * it or escalate around it. A genuine FAILURE (bad token, unreachable server, a 500, a
+ * shape the backend rejected) is an error, and is flagged, because the agent should stop
+ * and surface it rather than carry on as if the write landed.
+ *
+ * This is deliberately NOT "whatever the rest of the file does": most tools here flag
+ * nothing at all and report failures as ordinary prose, which is the weaker half of the
+ * convention. The two bug-enrichment tools already make the distinction this follows.
+ */
+async function workItemCall(fn) {
+  try {
+    assertAuthConfigured();
+    return { content: [{ type: 'text', text: await fn() }] };
+  } catch (err) {
+    if (err.status === 401) {
+      return {
+        content: [{ type: 'text', text: 'Not authenticated: Konductro rejected the CLI token. It may be expired or revoked — create a new one in Konductro under your profile and update KONDUCTRO_CLI_TOKEN. This is a setup problem, not a permissions one.' }],
+        isError: true,
+      };
+    }
+    const refusal = refusalText(err);
+    if (refusal) return { content: [{ type: 'text', text: refusal }] };
+
+    // Setup errors already read as full sentences; only wrap the ones that do not.
+    const text = err.setup
+      ? err.message
+      : `Failed: ${err.code === 'INVALID_BODY' ? validationText(err) : err.message}`;
+    return { content: [{ type: 'text', text }], isError: true };
+  }
+}
+
+/** Resolve the project from the repo's git remote, so no project id is ever asked for. */
+async function projectFromRepo(repoUrl) {
+  const repo = await konductroFetch(`/api/cli/repo-by-url?url=${encodeURIComponent(repoUrl)}`);
+  return repo;
+}
+
 const server = new McpServer({
   name: 'konductro',
   version: '1.0.0',
@@ -348,6 +491,30 @@ server.tool(
   }
 );
 
+// Tool: Submit a regenerated developer brief (KON-325)
+server.tool(
+  'submit_regenerated_brief',
+  "Submit a freshly regenerated developer brief for a task to Konductro. It becomes the task's current brief and is appended to the brief history (the previous version is preserved). Regenerate the brief tailored to Claude Code conventions before calling this.",
+  {
+    ticketId: z.string().describe('The ticket ID or key (e.g. KON-325) to update'),
+    content: z.string().describe('The full regenerated developer brief (markdown)'),
+    toolset: z.enum(['claude', 'q', 'codex', 'cursor']).default('claude').describe("Coding toolset that produced this brief (this plugin: 'claude')"),
+  },
+  async ({ ticketId, content, toolset }) => {
+    const result = await konductroFetch(`/api/cli/tickets/${ticketId}/regenerate-brief`, {
+      method: 'POST',
+      body: JSON.stringify({ content, toolset }),
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Developer brief regenerated for ${ticketId} — now version ${result.version} (${result.toolset}).`,
+      }],
+    };
+  }
+);
+
 // Tool: List my tickets
 server.tool(
   'list_my_tickets',
@@ -464,6 +631,12 @@ server.tool(
       text += `### Context Pack\n\n${ctx.ticket.contextPack}\n\n`;
     }
 
+    // Developer Notes — present when context is fetched on a story itself. For a
+    // task, the notes that matter are the parent story's, rendered below.
+    if (ctx.ticket.developerNotes) {
+      text += `### Developer Notes\n\n${ctx.ticket.developerNotes}\n\n`;
+    }
+
     // Parent Story
     if (ctx.parent) {
       text += `### Parent Story: ${ctx.parent.ticketKey} — ${ctx.parent.title}\n\n`;
@@ -476,6 +649,10 @@ server.tool(
       if (ctx.parent.contextPack) {
         text += `**Story Context Pack:**\n${ctx.parent.contextPack}\n\n`;
       }
+      // Story-level context accumulated by whoever worked the story's other tasks.
+      if (ctx.parent.developerNotes) {
+        text += `**Parent Story, Developer Notes:**\n${ctx.parent.developerNotes}\n\n`;
+      }
     }
 
     // Children tasks
@@ -521,6 +698,155 @@ server.tool(
   }
 );
 
+// Tool: Append a developer note to a story
+server.tool(
+  'append_story_developer_note',
+  "Append a note to a story's developer notes in Konductro, so context you worked out on one task is there for whoever picks up the next task on the same story. Notes live on the STORY, not the task: pass the parent story's key, which get_ticket_context prints in its Parent Story heading. Pass the current task's key as taskKey so the entry is attributable. Send only your new note — the endpoint appends it, and Konductro stamps the author, timestamp and task itself, so do not include a heading, a timestamp, a separator, or any notes you read earlier.",
+  {
+    storyId: z.string().describe('The story to append to — key (e.g. KON-283) or UUID. Not a task.'),
+    note: z.string().describe('The new note only, as markdown. No heading, timestamp or separator.'),
+    taskKey: z.string().optional().describe("The key of the task this note came from (e.g. KON-311), when there is one"),
+  },
+  async ({ storyId, note, taskKey }) => {
+    const result = await konductroFetch(`/api/cli/tickets/${storyId}/developer-notes`, {
+      method: 'POST',
+      body: JSON.stringify({ note, taskKey }),
+    });
+
+    // Deliberately not echoing result.developerNotes — it is the whole accumulated
+    // blob, and repeating it here invites a later call to send it back as a "new"
+    // note, which would duplicate every entry.
+    return {
+      content: [{
+        type: 'text',
+        text: `Note appended to ${result.ticketKey}'s developer notes.`,
+      }],
+    };
+  }
+);
+
+// Tool: Create a work item
+server.tool(
+  'create_work_item',
+  "Create a story, task or bug in the Konductro project this repository belongs to. Anything created this way lands in DRAFT and still needs an SDM's approval before it can be worked — say so when you report back, so nobody thinks it is ready to start. A task needs a parent story, and is created in the repository repoUrl resolves to; a bug needs no parent and is filed standalone. Creating STORIES is governed by the project's story access setting and may be refused; filing bugs and creating tasks are not affected by it. Pass the repository's git remote (git remote get-url origin) — the project is resolved from it, never asked for.",
+  {
+    repoUrl: z.string().describe('The git remote URL of this repository (run: git remote get-url origin)'),
+    kind: z.enum(['story', 'task', 'bug']).describe('What to create'),
+    title: z.string().describe('A short title, as a person would write it'),
+    description: z.string().describe('What this is and why, in markdown'),
+    acceptanceCriteria: z.array(z.string()).optional().describe('Observable behaviour, one per item. Omit for a bug unless you have them.'),
+    parentKey: z.string().optional().describe('For a TASK, the parent story key (e.g. KON-451). ONLY a task may have a parent. A story or a bug sent with a parentKey is REFUSED and nothing is created, rather than being filed top-level as though it had worked.'),
+    repositoryId: z.string().optional().describe('For a TASK, the repository UUID it will be built in. Leave this out — it defaults to the repository repoUrl resolves to, which is the one you are standing in. Only set it for a task that will be built in a DIFFERENT repository on the same project, and then you need that repo\'s UUID from Konductro.'),
+  },
+  async ({ repoUrl, kind, title, description, acceptanceCriteria, parentKey, repositoryId }) => workItemCall(async () => {
+    // KON-517 review: the backend's body schema DECLARES parentKey, so .strict() does not
+    // reject it — it is accepted and then dropped for anything that is not a task, because
+    // the route reads it only inside the task branch and calls createBug / createStory
+    // without it (routes/cli.ts). The item lands top-level and the 201 reports success, so
+    // asking for it under a story and being told it worked is exactly what happens. Refuse
+    // instead: a refusal is recoverable in the next turn, a misfiled item is found later
+    // by someone else, if at all.
+    //
+    // The two cases are dropped by the same code path but for different reasons, so the
+    // remedy differs and the message branches. A bug COULD have a parent — QA files bugs
+    // against the tested story that way — this endpoint just does not wire it through. A
+    // story could not: the hierarchy is story → task, so nothing sits above a story ever,
+    // and an agent sending one almost certainly meant to create a task.
+    if (kind !== 'task' && parentKey) {
+      const why = kind === 'bug'
+        ? `Konductro only parents a bug to a story when QA files it against a failed test criterion; a bug created from the CLI is always standalone in the project's Bugs phase. Re-run without parentKey, and name ${parentKey} in the description so the link to it is not lost.`
+        : `A story is top-level by definition — the hierarchy is story → task, so nothing sits above a story. If you meant to add work under ${parentKey}, re-run with kind "task". If you meant a new story, re-run without parentKey.`;
+      return `Refused: only a task can be created under a parent, and NOTHING WAS CREATED. ${why}`;
+    }
+
+    const repo = await projectFromRepo(repoUrl);
+
+    // KON-517 review, blocking: creating a task was a dead end. The backend requires
+    // repositoryId as a UUID, and nothing a developer can reach hands one out —
+    // get_decomposition_context is the only tool that returns one, and that needs an
+    // assigned decomposition task you do not have. So the agent was asked for a value it
+    // could not obtain, and a guess came back as a bare "Validation failed".
+    //
+    // It was in hand the whole time: repo-by-url returns the repository row (id, name,
+    // repoUrl, repoType, stacks, projectId, project) and the id was being discarded.
+    // Defaulting to it is also the right answer rather than merely an available one — the
+    // task is being written from inside the repo it will be built in.
+    //
+    // Tasks only. createStory ignores it, and defaulting it on a bug would silently start
+    // attributing bugs to a repository they were not attributed to before.
+    const resolvedRepositoryId = kind === 'task' ? (repositoryId ?? repo.id) : repositoryId;
+
+    const created = await konductroFetch(`/api/cli/projects/${repo.projectId}/work-items`, {
+      method: 'POST',
+      body: JSON.stringify({ kind, title, description, acceptanceCriteria, parentKey, repositoryId: resolvedRepositoryId }),
+    });
+    // KON-517 review, blocking: this used to print the ticketNumber alone and then say
+    // "use get_ticket_context with its key" — but a key is PREFIX-NUMBER, the prefix is
+    // nowhere in this tool's reach (repo-by-url does not return ticketPrefix), and so the
+    // agent was being invited to guess one. resolveTicketId matches prefix+number across
+    // the whole TENANT, not within the project, so a guessed prefix does not 404 — it
+    // resolves to another project's ticket of the same number, and the next
+    // update_work_item edits that one instead. The id closes it off: the UUID branch of
+    // resolveTicketId short-circuits with no lookup at all, so it can only be this row.
+    return `Created #${created.ticketNumber} — "${created.title}" (${created.kind}) in ${repo.project?.name ?? 'the project'}.\n\nid: ${created.id}\n\nIt is in ${created.status.toUpperCase()} and needs an SDM to approve it before it can be worked on. Use THAT id with get_ticket_context, update_work_item or delete_work_item. Do not build a key from #${created.ticketNumber} — the project's ticket prefix is not returned here, and a guessed prefix silently resolves to a different project's item of the same number rather than failing.`;
+  })
+);
+
+// Tool: Update a work item
+server.tool(
+  'update_work_item',
+  "Change the title, description or acceptance criteria of a work item you own in Konductro — one assigned to you, that you are the developer on, or that you created. THESE THREE FIELDS ARE ALL YOU CAN CHANGE: status, sprint, assignee and everything else are deliberately not available here and must be changed in Konductro. Editing a STORY is governed by the project's story access setting and may be refused, or may be applied and then held for an SDM to review; editing a task is not affected by it. Send only the fields you are actually changing.",
+  {
+    key: z.string().describe('The work item key (e.g. KON-451) or UUID'),
+    title: z.string().optional().describe('The new title'),
+    description: z.string().optional().describe('The new description, in markdown'),
+    acceptanceCriteria: z.array(z.string()).optional().describe('The FULL new list, not just the additions — it replaces what is there'),
+  },
+  async ({ key, title, description, acceptanceCriteria }) => workItemCall(async () => {
+    const body = {};
+    if (title !== undefined) body.title = title;
+    if (description !== undefined) body.description = description;
+    if (acceptanceCriteria !== undefined) body.acceptanceCriteria = acceptanceCriteria;
+    if (Object.keys(body).length === 0) {
+      return 'Nothing to change — pass at least one of title, description or acceptanceCriteria.';
+    }
+
+    const result = await konductroFetch(`/api/cli/tickets/${encodeURIComponent(key)}/work-item`, {
+      method: 'PATCH',
+      body: JSON.stringify(body),
+    });
+
+    // Deliberately NOT echoing the updated values back. Returning the item invites the
+    // next call to send them again as "new" values, re-submitting fields nobody changed
+    // and raising a review for a no-op. Same reason append_story_developer_note does not
+    // return the notes blob.
+    // `changed` echoes the fields that were WRITTEN, not the ones that turned out to
+    // differ — the server returns Object.keys of what it applied (routes/cli.ts). So
+    // re-sending a title with its existing value still reports "changed: title". Do not
+    // read it as a diff.
+    const changed = (result.changed ?? Object.keys(body)).join(', ');
+    let text = `Updated ${key} (#${result.ticketNumber}) — changed: ${changed}.`;
+    if (result.awaitingReview) {
+      text += '\n\nThis change is APPLIED but now waiting for an SDM to approve or reject it, because this project reviews story changes. Until it is resolved the story will not move to Ready for QA, even if every task is done. If it is rejected the previous values come back and you will be notified.';
+    }
+    return text;
+  })
+);
+
+// Tool: Delete a work item
+server.tool(
+  'delete_work_item',
+  "Delete a task or a bug from Konductro that has not been started. Bugs count: Konductro stores a bug as a task, so a developer's own unstarted bug can be deleted here. Stories cannot — deleting one takes its tasks with it and there is no restore, so archive a story in Konductro instead. Neither can a bug QA filed against a failed test criterion, which is part of that test record rather than yours. Nothing that has started can be deleted by anyone: that means anything carrying a branch, or anything past sprint planning, since only draft, approved and in_sprint items still qualify. Close those out in Konductro instead. Beyond that you may delete an item you are assigned to, are the developer on, or created; an SDM, architect or UX lead on the project may delete any item that qualifies. This is permanent and there is no undo, so be sure the developer asked for it.",
+  {
+    key: z.string().describe('The task or bug key (e.g. KON-452) or UUID'),
+  },
+  async ({ key }) => workItemCall(async () => {
+    const result = await konductroFetch(`/api/cli/tickets/${encodeURIComponent(key)}/work-item`, { method: 'DELETE' });
+    const extra = result.deleted > 1 ? ` (${result.deleted} rows, including its linked records)` : '';
+    return `Deleted ${key}${extra}. This cannot be undone.`;
+  })
+);
+
 // Tool: Start work on a ticket
 server.tool(
   'start_work',
@@ -917,7 +1243,13 @@ server.tool(
 
       return { content: [{ type: 'text', text }] };
     } catch (err) {
-      const msg = err.message?.includes('BUG_NOT_FOUND') || err.message?.includes('404')
+      // KON-517: these used to sniff err.message for 'BUG_NOT_FOUND' / '404', which
+      // worked only because the message was the whole raw envelope. konductroFetch now
+      // sets message to the backend's `error` sentence, so that match silently stopped
+      // firing and a missing bug reported as a generic failure. Read the code and the
+      // status instead — both are on the error and neither depends on wording.
+      const notABug = err.code === 'BUG_NOT_FOUND' || err.status === 404;
+      const msg = notABug
         ? `Ticket ${ticketId} not found or is not a bug.`
         : `Failed to load bug context: ${err.message}`;
       return { content: [{ type: 'text', text: msg }], isError: true };
@@ -953,9 +1285,11 @@ server.tool(
         : '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')
+      // Same fix as get_bug_for_enrichment above — match on err.code / err.status, not
+      // on message text, which konductroFetch no longer formats the way this expected.
+      const msg = (err.code === 'BUG_NOT_FOUND' || err.status === 404)
         ? `Ticket ${ticketId} not found or is not a bug.`
-        : err.message?.includes('INVALID_ENRICHMENT')
+        : err.code === 'INVALID_ENRICHMENT'
         ? 'At least one enrichment field must be provided.'
         : `Failed to submit enrichment: ${err.message}`;
       return { content: [{ type: 'text', text: msg }], isError: true };

package/skills/regenerate-brief/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: regenerate-brief
+description: Regenerate a task's developer brief using Claude Code, tailored to the current codebase, and submit it back to Konductro. Use when a developer wants a fresh, tool-tailored brief for an existing task.
+allowed-tools: Read, Grep, Glob, Bash, mcp__konductro__list_my_tickets, mcp__konductro__get_ticket_context, mcp__konductro__submit_regenerated_brief
+---
+
+# Regenerate Developer Brief
+
+Help a developer regenerate the developer brief for a Konductro task, tailored to Claude Code, then submit it back. The regenerated brief becomes the task's current brief; the previous version is preserved in the brief history (nothing is lost).
+
+## Workflow
+
+### Step 1: Pick the task
+
+Call `list_my_tickets` to show assigned tickets, or take a ticket key the developer gives you (e.g. `KON-325`). Choose the task whose brief to regenerate.
+
+### Step 2: Load current context
+
+Call `get_ticket_context` with the ticket ID. Review the **current brief** (context pack), description, acceptance criteria, architectural notes, and target repository — this is your starting point.
+
+### Step 3: Explore the codebase
+
+Use Read / Grep / Glob against the **local** repository to ground the brief in the actual code as it stands now — relevant files, existing patterns, entry points, and tests. A regenerated brief should reflect the current state of the code, not just the original decomposition.
+
+### Step 4: Regenerate the brief
+
+Write a fresh developer brief tailored to Claude Code conventions. Use clear, actionable sections:
+- **Architecture Context** — how this task fits, key constraints
+- **Files to Create / Files to Modify** — concrete paths + what changes
+- **Implementation Steps** — a numbered, ordered approach
+- **Out of Scope** — what this task explicitly does not cover
+
+Keep it focused on THIS task. Prefer concrete file paths and specifics over generic advice.
+
+### Step 5: Submit
+
+Call `submit_regenerated_brief` with the ticket ID and the regenerated brief as `content` (the `toolset` defaults to `claude` for this plugin). On success it becomes the current brief and is recorded as a new version.
+
+## Rules
+
+- This does not change the task's status or branch — it only updates the brief. To start work, use `/start-ticket`.
+- If `submit_regenerated_brief` fails (auth/validation), show the error clearly **and** show the brief you wrote so the developer can retry without losing it.
+- Regenerate against the real local code — don't just reword the existing brief.

package/skills/start-ticket/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: start-ticket
 description: Pick up an assigned ticket and start work — creates branch, pushes ticket spec, updates status. Use when a developer wants to begin working on a ticket.
-allowed-tools: Read, Grep, Glob, Bash, mcp__konductro__list_my_tickets, mcp__konductro__get_ticket_context, mcp__konductro__start_work
+allowed-tools: Read, Grep, Glob, Bash, mcp__konductro__list_my_tickets, mcp__konductro__get_ticket_context, mcp__konductro__submit_regenerated_brief, mcp__konductro__start_work
 ---
 
 # Start Ticket
@@ -24,6 +24,10 @@ Call `get_ticket_context` with the chosen ticket ID. Present a summary:
 - Target repository and default base branch
 - Any dependencies or architectural notes
 
+### Step 2.5 (optional): Regenerate the brief before starting
+
+Offer the developer the option to **regenerate the developer brief first**, tailored to Claude Code, so they start from a fresh, code-grounded brief. If they accept: explore the local codebase, write an updated brief, and submit it with `submit_regenerated_brief` (toolset `claude`) before moving on. If they decline, continue with the existing brief. (For a standalone regeneration without starting work, use `/regenerate-brief`.)
+
 ### Step 3: Confirm Branch Details
 
 Ask the developer: