claude-teammate 0.1.183 → 0.1.185

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-teammate",
-  "version": "0.1.183",
+  "version": "0.1.185",
   "description": "CLI bootstrapper for Claude Teammate.",
   "license": "MIT",
   "type": "module",

package/src/claude/prompts.js

@@ -349,6 +349,86 @@ Instructions:
 - If blocked, return result=stuck with that summary explaining why it did not work.`;
 }
 
+export function buildGitHubPRPlanBreakdownSystemPrompt() {
+  return [
+    "You are breaking a large GitHub pull request implementation plan into a sequenced list of small, atomic steps.",
+    "Each step must be self-contained: a single developer can implement it in isolation by reading only that step description.",
+    "Steps must be ordered by dependency — steps that others depend on come first.",
+    "Each step description must be specific enough to act on without reading the full PR body: name the exact files, classes, functions, or fields to change and what the change is.",
+    "Aim for 3-8 steps. Do not produce trivial steps or steps that only say 'test' or 'verify'.",
+    "Return only structured output matching the provided schema."
+  ].join(" ");
+}
+
+export function buildGitHubPRPlanBreakdownUserPrompt(input) {
+  return `Break this pull request plan into ordered implementation steps.
+
+Pull request title:
+${input.pullRequest.title}
+
+Pull request description:
+${input.pullRequest.body || "(none)"}
+
+Epic memory snapshot:
+${JSON.stringify(input.memory?.epic || {}, null, 2)}
+
+Instructions:
+- Produce an ordered list of atomic implementation steps.
+- Each step must be specific enough to implement without reading this full description again: name the exact files, classes, methods, or enum values involved.
+- Steps must be ordered by dependency (earlier steps must not depend on later ones).
+- Aim for 3-8 steps covering the full scope of the plan.
+- Do not include steps for committing, pushing, or testing unless the test is part of the plan.`;
+}
+
+export function buildGitHubPRImplementationStepSystemPrompt() {
+  return [
+    "You are implementing a single step of a larger GitHub pull request.",
+    "You must work directly in the provided repository path and branch.",
+    "If additional accessible repository paths are provided, you may read from them for source context, but only edit the primary repository unless the step explicitly says otherwise.",
+    "First ensure the repository is on the provided branch.",
+    "Implement only the specific step described — do not implement other parts of the larger plan.",
+    "Read the epic memory snapshot before making changes so you can reuse known repo-specific knowledge and avoid repeating past mistakes.",
+    "Run only the commands needed to inspect, edit, and test this specific step.",
+    "When editing code or markup, smart quotes and em/en dashes are not allowed; replace them if encountered.",
+    LANGUAGE_PRESERVATION_RULES,
+    "Do not run git add, git commit, or git push. The outer worker will handle all git operations.",
+    "If you are blocked on this step, return result=stuck with a concise reason.",
+    "Return only structured output matching the provided schema."
+  ].join(" ");
+}
+
+export function buildGitHubPRImplementationStepUserPrompt(input) {
+  return `Implement this specific step of a pull request.
+
+Pull request number: ${input.pullRequest.number}
+Pull request title:
+${input.pullRequest.title}
+
+Repository path:
+${input.repoPath}
+
+Additional accessible repository paths:
+${formatAdditionalRepoPaths(input.repoPaths, input.repoPath)}
+
+Branch to use:
+${input.branchName}
+
+Epic memory snapshot:
+${JSON.stringify(input.memory?.epic || {}, null, 2)}
+
+Step to implement:
+${input.step}
+
+Instructions:
+- Checkout the branch above in this repository.
+- Implement only the step described above. Do not implement other parts of the plan.
+- Smart quotes and em/en dashes are not allowed. Use: smart quotes -> ", em/en dashes -> -.
+- Do not commit or push; leave modified files in the working tree.
+- Return summary as 1-2 sentences describing what changed in this step.
+- If successful, return result=implemented.
+- If blocked, return result=stuck with a concise reason.`;
+}
+
 export function buildGitHubPRCommentReviewSystemPrompt() {
   return [
     "You are triaging a human comment on an existing GitHub pull request.",

package/src/claude.js

@@ -32,6 +32,10 @@ import {
   buildGitHubIssueReviewUserPrompt,
   buildGitHubPRImplementationSystemPrompt,
   buildGitHubPRImplementationUserPrompt,
+  buildGitHubPRPlanBreakdownSystemPrompt,
+  buildGitHubPRPlanBreakdownUserPrompt,
+  buildGitHubPRImplementationStepSystemPrompt,
+  buildGitHubPRImplementationStepUserPrompt,
   buildGitHubPRCommentReviewSystemPrompt,
   buildGitHubPRCommentReviewUserPrompt,
   buildGitHubPRReviewSystemPrompt,
@@ -614,6 +618,68 @@ export async function runClaudeImplementation(input) {
   );
 }
 
+const GITHUB_PR_PLAN_BREAKDOWN_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    steps: {
+      type: "array",
+      items: { type: "string" },
+      minItems: 1
+    }
+  },
+  required: ["steps"]
+};
+
+export async function runClaudeImplementationPlanBreakdown(input) {
+  return invokeClaudeTask(
+    GITHUB_PR_PLAN_BREAKDOWN_SCHEMA,
+    buildGitHubPRPlanBreakdownSystemPrompt(),
+    buildGitHubPRPlanBreakdownUserPrompt(input),
+    {
+      model: input.model,
+      permissionMode: "default",
+      effort: "low",
+      extraArgs: ["--strict-mcp-config", "--tools", ""],
+      runOpts: {
+        timeout: input.timeoutMs || DEFAULT_TIMEOUT_MS,
+        issueKey: input.issueKey,
+        logger: input.logger,
+        phase: "implementation-plan-breakdown"
+      }
+    }
+  );
+}
+
+export async function runClaudeImplementationStep(input) {
+  if (!input.repoPath) {
+    throw new Error("Claude implementation step requires a local repository path.");
+  }
+
+  await clearLocalPlaywrightMcpConfig(input.repoPath);
+
+  return invokeClaudeTask(
+    GITHUB_PR_IMPLEMENTATION_SCHEMA,
+    buildGitHubPRImplementationStepSystemPrompt(),
+    buildGitHubPRImplementationStepUserPrompt(input),
+    {
+      model: input.model,
+      permissionMode: input.permissionMode,
+      effort: "medium",
+      extraArgs: ["--tools", "Bash,Read,Grep,Glob,Edit,Write"],
+      validate: validateGitHubImplementationResult,
+      runOpts: {
+        cwd: input.repoPath,
+        timeout: input.timeoutMs || LONG_TASK_TIMEOUT_MS,
+        onSpawn: input.onSpawn,
+        issueKey: input.issueKey,
+        logger: input.logger,
+        phase: "implementation-step"
+      }
+    }
+  );
+}
+
 export async function runClaudePullRequestCommentReview(input) {
   if (!input.repoPath) {
     throw new Error("GitHub pull request comment review requires a local repository path.");

package/src/worker/jira-issue-support.js

@@ -0,0 +1,241 @@
+import { deriveEpicMemoryPath } from "../memory.js";
+import {
+  buildGitHubIssueBody,
+  buildGitHubIssueTitle,
+  ensureJiraComment,
+  getLatestHumanRepoSelectionReply,
+  isRepoSelectionPromptComment,
+  selectIssueCreationRepo
+} from "./jira-helpers.js";
+import { dedupeGitHubIssues } from "./forge-sync.js";
+import {
+  compareCommentsNewestFirst,
+  parseOptionalInt,
+  toErrorMessage
+} from "./utils.js";
+
+const REPO_SELECTION_HANDLED_PREFIX = "[tm8:repo-selection:handled-comment=";
+
+export function hasExpandedJiraDetail(issue) {
+  return typeof issue?.descriptionText === "string" && Array.isArray(issue?.comments);
+}
+
+export function shouldFetchJiraDetail(issue, { isToDoStatus, isInProgressStatus, isInReviewStatus }) {
+  return (
+    isToDoStatus(issue?.status) ||
+    isInProgressStatus(issue?.status) ||
+    isInReviewStatus(issue?.status)
+  );
+}
+
+export function getLatestHumanJiraComment(detail, botUser, jira) {
+  const comments = Array.isArray(detail?.comments) ? detail.comments : [];
+  return [...comments]
+    .filter((comment) => !String(comment?.bodyText || "").startsWith("[Status]"))
+    .sort(compareCommentsNewestFirst)
+    .find((comment) => !jira.isBotAuthor(comment.author, botUser)) || null;
+}
+
+export async function persistJiraCommentMemoryIfNeeded({
+  detail,
+  latestComment,
+  issueMemoryRecord,
+  issueMemory,
+  epicMemory,
+  projectRoot,
+  config,
+  logger,
+  services
+}) {
+  if (!latestComment?.id || !String(latestComment.bodyText || "").trim()) {
+    return { issueMemory, epicMemory };
+  }
+
+  if (String(issueMemory?.last_jira_memory_comment_id || "") === String(latestComment.id)) {
+    return { issueMemory, epicMemory };
+  }
+
+  epicMemory = await services.saveMaintainedEpicMemory({
+    filePath: deriveEpicMemoryPath(projectRoot, config.JIRA_BASE_URL, detail),
+    issue: detail,
+    epicMemory,
+    projectRoot,
+    permissionMode: config.CLAUDE_PERMISSION_MODE,
+    timeoutMs: parseOptionalInt(config.CLAUDE_TIMEOUT_MS),
+    reason: "Captured durable guidance from latest Jira human comment.",
+    candidateUpdates: {
+      epic_guardrails: [String(latestComment.bodyText || "").trim()]
+    },
+    logger
+  });
+
+  issueMemory.last_jira_memory_comment_id = String(latestComment.id);
+  issueMemory = await services.saveIssueMemory(issueMemoryRecord.filePath, detail, issueMemory);
+  return { issueMemory, epicMemory };
+}
+
+export async function handleJiraCliError({
+  error,
+  detail,
+  jira,
+  botUser,
+  issueMemoryRecord,
+  issueMemory,
+  saveMemory,
+  logger,
+  label,
+  jiraCliRetryIntervalMs,
+  markClaudeUsageLimit
+}) {
+  if (error.hitUsageLimit) {
+    markClaudeUsageLimit();
+  }
+  if (error.promptTooLong) {
+    await ensureJiraComment(detail, jira, botUser, "The task description or accumulated context is too large for Claude to process in one go. Please break this task into smaller subtasks or reduce the amount of data referenced.");
+    return issueMemory;
+  }
+  const retryAfter = new Date(Date.now() + jiraCliRetryIntervalMs).toISOString();
+  const next = { ...issueMemory, retry_after: retryAfter };
+  const saved = await saveMemory(issueMemoryRecord.filePath, detail, next);
+  await ensureJiraComment(detail, jira, botUser, "Claude CLI is temporarily unavailable (token limit or API error). This task will be retried automatically in 15 minutes. No action needed.");
+  await logger.error(`${label} (CLI error, retry scheduled)`, { issue: detail.key, error });
+  return saved;
+}
+
+export function formatClarificationQuestions(questions) {
+  const cleanedQuestions = questions.filter(Boolean);
+  if (cleanedQuestions.length === 0) {
+    return "I need a bit more detail before I can plan the implementation.";
+  }
+
+  return `I need a bit more detail before I can plan the implementation:\n\n${cleanedQuestions
+    .map((question) => `- ${question}`)
+    .join("\n")}`;
+}
+
+function buildRepoSelectionComment(repos) {
+  const choices = repos.map((repo) => `- ${repo.url}`).join("\n");
+  return `[tm8:repo-selection]\nI found multiple candidate repositories for this task. Please reply with the exact repo URL I should use:\n${choices}`;
+}
+
+function getLatestRepoSelectionPromptComment(detail, botUser, jira) {
+  const comments = Array.isArray(detail?.comments) ? [...detail.comments] : [];
+  return comments
+    .filter((comment) =>
+      jira.isBotAuthor(comment?.author, botUser) &&
+      isRepoSelectionPromptComment(comment?.bodyText || "")
+    )
+    .sort(compareCommentsNewestFirst)[0] || null;
+}
+
+function getHandledRepoSelectionCommentId(bodyText) {
+  const match = String(bodyText || "").match(/\[tm8:repo-selection:handled-comment=([^\]\s]+)\]/u);
+  return String(match?.[1] || "").trim();
+}
+
+async function markRepoSelectionReplyHandled(detail, jira, promptComment, repos, handledCommentId) {
+  if (!promptComment?.id || typeof jira.updateComment !== "function") {
+    return;
+  }
+
+  const handledId = String(handledCommentId || "").trim();
+  if (!handledId || getHandledRepoSelectionCommentId(promptComment.bodyText || "") === handledId) {
+    return;
+  }
+
+  const nextBody = `${buildRepoSelectionComment(repos)}\n${REPO_SELECTION_HANDLED_PREFIX}${handledId}]`;
+  await jira.updateComment(detail.key, promptComment.id, nextBody);
+  promptComment.bodyText = nextBody;
+  promptComment.updated = new Date().toISOString();
+}
+
+export async function continueGitHubIssueCreation({
+  detail,
+  jira,
+  botUser,
+  forgeRegistry,
+  projectRoot,
+  config,
+  issueMemoryRecord,
+  issueMemory,
+  repos,
+  logger,
+  claudeResult = null,
+  services
+}) {
+  if (!claudeResult) {
+    throw new Error("GitHub issue creation requires the live clarification result.");
+  }
+
+  const latestRepoSelectionReply = getLatestHumanRepoSelectionReply(detail, botUser, jira);
+  let selectedRepo = selectIssueCreationRepo({ detail, issueMemory, repos });
+  const latestRepoPrompt = getLatestRepoSelectionPromptComment(detail, botUser, jira);
+  if (!selectedRepo && latestRepoSelectionReply) {
+    const fallback = await services.runClaudeRepoSelection({
+      issue: detail,
+      repos,
+      cwd: projectRoot,
+      permissionMode: config.CLAUDE_PERMISSION_MODE,
+      timeoutMs: parseOptionalInt(config.CLAUDE_TIMEOUT_MS),
+      issueKey: detail.key,
+      logger
+    });
+    selectedRepo = repos.find((repo) => repo.url === fallback.repo_url) || null;
+  }
+
+  if (!selectedRepo) {
+    if (latestRepoSelectionReply && latestRepoPrompt) {
+      await markRepoSelectionReplyHandled(detail, jira, latestRepoPrompt, repos, latestRepoSelectionReply.id);
+    }
+    await ensureJiraComment(detail, jira, botUser, buildRepoSelectionComment(repos));
+    issueMemory.last_error = "Multiple repositories match this task. Waiting for explicit repo selection.";
+    return services.saveIssueMemory(issueMemoryRecord.filePath, detail, issueMemory);
+  }
+
+  try {
+    if (selectedRepo.local_path) {
+      await services.pullLatest(selectedRepo.local_path);
+    }
+    const provider = forgeRegistry.getClientForRepo(selectedRepo.url);
+    const existingGitHubIssue = await provider.findIssueByJiraKey(selectedRepo.url, detail.key);
+    const githubIssue = existingGitHubIssue ?? await provider.createIssue(selectedRepo.url, {
+      title: buildGitHubIssueTitle(detail, claudeResult),
+      body: buildGitHubIssueBody(detail, claudeResult, selectedRepo.url)
+    });
+
+    issueMemory.github_issues.push({
+      repo_url: selectedRepo.url,
+      local_path: selectedRepo.local_path || "",
+      url: githubIssue.url,
+      number: String(githubIssue.number),
+      branch_name: "",
+      pr_url: "",
+      pr_number: ""
+    });
+    issueMemory.epic_key = issueMemory.epic_key || detail.epicKey || detail.key;
+    issueMemory.epic_url = issueMemory.epic_url || detail.epicUrl || detail.url;
+    issueMemory.github_issues = dedupeGitHubIssues(issueMemory.github_issues);
+    issueMemory = await services.saveIssueMemory(issueMemoryRecord.filePath, detail, issueMemory);
+
+    const successComment = existingGitHubIssue
+      ? `Using existing repository issue: [#${githubIssue.number}](${githubIssue.url})`
+      : `Created repository issue: [#${githubIssue.number}](${githubIssue.url})`;
+    await ensureJiraComment(detail, jira, botUser, successComment);
+    issueMemory.last_error = "";
+    issueMemory = await services.saveIssueMemory(issueMemoryRecord.filePath, detail, issueMemory);
+
+    await logger.info(existingGitHubIssue ? "Repository issue already exists" : "Repository issue created", {
+      issue: detail.key,
+      repo: selectedRepo.url,
+      number: githubIssue.number
+    });
+  } catch (error) {
+    const message = toErrorMessage(error);
+    await ensureJiraComment(detail, jira, botUser, `Failed to create repository issue for ${selectedRepo.url}: ${message}`);
+    issueMemory.last_error = message;
+    issueMemory = await services.saveIssueMemory(issueMemoryRecord.filePath, detail, issueMemory);
+    throw error;
+  }
+
+  return issueMemory;
+}