claude-teammate 0.1.2 → 0.1.3

package/README.md

@@ -85,7 +85,7 @@ memory/
 | `repos` | Target GitHub repositories |
 | `status` | Done, in-flight, blocked |
 | `notes` | Architectural decisions, reviewer preferences, conventions |
-| `known issues` | Recurring bugs, fragile areas, patterns to avoid |
+| `guardrails` | Recurring bugs, fragile areas, and what not to do |
 
 The bot carries context across tickets, PRs, and sessions.
 
@@ -100,7 +100,7 @@ npm install -g claude-teammate
 claude-teammate start
 ```
 
-The wizard asks for your Jira and GitHub credentials and writes a `.env` file in the current directory.
+`start` creates `.env` on the first run, runs a 5 second Claude CLI preflight check that expects a plain `OK`, then launches a background worker for the current project. If `.env` already exists with the required values, setup is skipped and your credentials are not prompted for again.
 
 To upgrade to latest version
 
@@ -108,12 +108,42 @@ To upgrade to latest version
 npm install -g claude-teammate@latest
 ```
 
+Check or stop the worker with:
+
+```bash
+claude-teammate status
+claude-teammate stop
+```
+
+Per-project runtime files are stored in:
+
+```text
+.claude-teammate/
+├── repos/
+├── worker.log
+├── worker.pid
+└── state.json
+```
+
+Issue memory is stored in:
+
+```text
+memory/
+└── {domain}/
+    └── {workspace}/
+        ├── epic-{id}.md
+        └── issue-{id}.md
+```
+
+`epic-{id}.md` stores shared epic facts such as related repositories. `issue-{id}.md` stores issue-specific workflow state, clarification history, and GitHub issue tracking.
+
+The worker polls Jira once per minute. It transitions `To Do` issues to `In Progress`, asks for repo URLs when epic memory lacks them, clones all referenced repos into `.claude-teammate/repos/`, uses Claude CLI to clarify requirements from Jira comments across those repos, and creates GitHub issues once the requirements are clear enough.
+
 ```env
 # .env file generated by `claude-teammate start`
 JIRA_BASE_URL=https://yourorg.atlassian.net
-JIRA_EMAIL=you@example.com
-JIRA_API_TOKEN=...
 JIRA_BOT_EMAIL=bot@yourorg.com
+JIRA_BOT_API_TOKEN=...
 GITHUB_PAT=ghp_...
 ```
 
@@ -138,7 +168,7 @@ It reads the actual repository before writing anything - structure, conventions,
 ## Roadmap
 
 - 🟢 Design the workflow
-- ⚪ Jira integration - read tickets, comment, detect assignee
+- 🟢 Jira integration - read tickets, comment, detect assignee
 - ⚪ GitHub integration - issues, PRs, review requests
 - ⚪ Epic memory - persistent context per epic
 - ⚪ End-to-end: Jira ticket → approved plan → merged PR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-teammate",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "CLI bootstrapper for Claude Teammate.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,8 @@
   },
   "scripts": {
     "lint": "eslint .",
-    "start": "node ./bin/claude-teammate.js start"
+    "start": "node ./bin/claude-teammate.js start",
+    "test": "node --test"
   },
   "keywords": [
     "cli",

package/src/claude.js

@@ -0,0 +1,356 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const STARTUP_CHECK_TIMEOUT_MS = 15 * 1000;
+const CHILD_CLEANUP_WAIT_MS = 1_000;
+const activeClaudeChildren = new Set();
+const DEFAULT_MODEL = "sonnet";
+
+const OUTPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    decision: {
+      type: "string",
+      enum: ["needs_clarification", "requirements_clear"]
+    },
+    clarification_summary: {
+      type: "string"
+    },
+    questions: {
+      type: "array",
+      items: {
+        type: "string"
+      }
+    },
+    plan_title: {
+      type: "string"
+    },
+    plan_body: {
+      type: "string"
+    }
+  },
+  required: ["decision", "clarification_summary", "questions", "plan_title", "plan_body"]
+};
+
+export async function runClaudeClarification(input) {
+  if (!Array.isArray(input.repoPaths) || input.repoPaths.length === 0) {
+    throw new Error("Claude clarification requires at least one local repository path.");
+  }
+
+  const args = [
+    "--print",
+    "--model",
+    input.model || DEFAULT_MODEL,
+    "--permission-mode",
+    input.permissionMode || "dontAsk",
+    "--strict-mcp-config",
+    "--tools",
+    "Read,Grep,Glob",
+    "--effort",
+    "low",
+    "--output-format",
+    "json",
+    "--json-schema",
+    JSON.stringify(OUTPUT_SCHEMA),
+    "--append-system-prompt",
+    buildSystemPrompt()
+  ];
+
+  args.push(
+    buildUserPrompt(input)
+  );
+
+  let stdout;
+  const workingDirectory = getClaudeWorkspaceRoot(input.repoPaths);
+
+  try {
+    ({ stdout } = await runClaudeCommand("claude", args, {
+      cwd: workingDirectory,
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: input.timeoutMs || DEFAULT_TIMEOUT_MS
+    }));
+  } catch (error) {
+    throw new Error(formatClaudeInvocationError(error, input.timeoutMs || DEFAULT_TIMEOUT_MS));
+  }
+
+  const parsed = parseClaudeOutput(stdout);
+  return validateClaudeResult(parsed);
+}
+
+export async function verifyClaudeCli(input = {}) {
+  const args = [
+    "--print",
+    "--output-format",
+    "text",
+    "Reply with exactly OK. Output only OK."
+  ];
+
+  let stdout;
+
+  try {
+    ({ stdout } = await runClaudeCommand("claude", args, {
+      cwd: input.cwd,
+      maxBuffer: 1024 * 1024,
+      timeout: input.timeoutMs || STARTUP_CHECK_TIMEOUT_MS
+    }));
+  } catch (error) {
+    throw new Error(formatClaudeInvocationError(error, input.timeoutMs || STARTUP_CHECK_TIMEOUT_MS));
+  }
+
+  const normalizedOutput = stdout.trim().replace(/[.!]+$/u, "");
+  if (normalizedOutput !== "OK") {
+    throw new Error(`Claude CLI startup check returned unexpected output: ${stdout.trim() || "(empty)"}`);
+  }
+}
+
+export function parseClaudeOutput(output) {
+  const trimmed = output.trim();
+  if (!trimmed) {
+    throw new Error("Claude CLI returned empty output.");
+  }
+
+  const direct = JSON.parse(trimmed);
+  if (direct && typeof direct === "object") {
+    if ("structured_output" in direct && direct.structured_output && typeof direct.structured_output === "object") {
+      return direct.structured_output;
+    }
+
+    if ("decision" in direct) {
+      return direct;
+    }
+
+    if ("result" in direct && typeof direct.result === "string") {
+      return JSON.parse(direct.result);
+    }
+
+    if ("content" in direct && typeof direct.content === "string") {
+      return JSON.parse(direct.content);
+    }
+  }
+
+  throw new Error("Claude CLI returned an unsupported JSON payload.");
+}
+
+export async function cleanupClaudeProcesses() {
+  const children = [...activeClaudeChildren];
+  if (children.length === 0) {
+    return;
+  }
+
+  await Promise.all(children.map((child) => terminateChildProcess(child)));
+}
+
+function validateClaudeResult(result) {
+  if (
+    !result ||
+    typeof result !== "object" ||
+    !["needs_clarification", "requirements_clear"].includes(result.decision)
+  ) {
+    throw new Error("Claude CLI returned an invalid decision payload.");
+  }
+
+  return {
+    decision: result.decision,
+    clarification_summary: String(result.clarification_summary ?? "").trim(),
+    questions: Array.isArray(result.questions)
+      ? result.questions.map((question) => String(question).trim()).filter(Boolean)
+      : [],
+    plan_title: String(result.plan_title ?? "").trim(),
+    plan_body: String(result.plan_body ?? "").trim()
+  };
+}
+
+function formatClaudeInvocationError(error, timeoutMs) {
+  const stderr = error instanceof Error && "stderr" in error ? String(error.stderr || "") : "";
+  const output = error instanceof Error && "stdout" in error ? String(error.stdout || "") : "";
+  const timeout = Boolean(error && typeof error === "object" && "killed" in error && error.killed);
+  const signal = error && typeof error === "object" && "signal" in error ? String(error.signal || "") : "";
+  const details = [stderr.trim(), output.trim()].filter(Boolean).join("\n").slice(0, 1000);
+  return `Claude CLI invocation failed${timeout ? ` after ${timeoutMs}ms` : ""}${signal ? ` (${signal})` : ""}${details ? `: ${details}` : "."}`;
+}
+
+function runClaudeCommand(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    activeClaudeChildren.add(child);
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let killedBySignal = "";
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, options.timeout);
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (stdout.length > options.maxBuffer) {
+        killedBySignal = "SIGTERM";
+        child.kill("SIGTERM");
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      if (stderr.length > options.maxBuffer) {
+        killedBySignal = "SIGTERM";
+        child.kill("SIGTERM");
+      }
+    });
+
+    child.on("error", (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      activeClaudeChildren.delete(child);
+      clearTimeout(timer);
+      reject({
+        ...error,
+        stdout,
+        stderr,
+        killed: timedOut,
+        signal: killedBySignal
+      });
+    });
+
+    child.on("close", (code, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      activeClaudeChildren.delete(child);
+      clearTimeout(timer);
+
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+
+      reject({
+        stdout,
+        stderr,
+        killed: timedOut,
+        signal: signal || killedBySignal
+      });
+    });
+  });
+}
+
+function terminateChildProcess(child) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.killed) {
+      activeClaudeChildren.delete(child);
+      resolve();
+      return;
+    }
+
+    let finished = false;
+    const finish = () => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      activeClaudeChildren.delete(child);
+      resolve();
+    };
+
+    child.once("close", finish);
+    child.kill("SIGTERM");
+
+    setTimeout(() => {
+      if (finished) {
+        return;
+      }
+      child.kill("SIGKILL");
+      finish();
+    }, CHILD_CLEANUP_WAIT_MS);
+  });
+}
+
+function buildSystemPrompt() {
+  return [
+    "You are clarifying a Jira ticket for an implementation planning workflow.",
+    "You may inspect the provided repository if that helps determine whether the requirement is clear enough or helps write a better implementation plan.",
+    "Use tools selectively; only inspect code when it materially helps the decision or plan.",
+    "Do not edit files, do not run mutating commands, and do not implement anything.",
+    "Return only structured output that matches the provided schema.",
+    "If requirements are unclear, ask concise clarification questions for the Jira user.",
+    "If requirements are clear, produce a concise implementation plan title and body suitable for a GitHub issue.",
+    "The plan_title must use exactly this format: <type>: <title> [issue-id].",
+    "Allowed types are only: feat, fix, docs, style, refactor, test, chore.",
+    "Use the provided Jira issue key as the issue-id suffix."
+  ].join(" ");
+}
+
+function buildUserPrompt(input) {
+  const recentComments = input.comments
+    .slice(-10)
+    .map(
+      (comment) =>
+        `- [${comment.id}] ${comment.author.displayName || comment.author.emailAddress || "Unknown"}: ${comment.bodyText}`
+    )
+    .join("\n");
+
+  return `Clarify this Jira issue.
+
+Issue key: ${input.issue.key}
+Issue URL: ${input.issue.url}
+Summary: ${input.issue.summary}
+Status: ${input.issue.status}
+Description:
+${input.issue.descriptionText || "(none)"}
+
+Memory snapshot:
+${JSON.stringify(input.memory, null, 2)}
+
+Recent Jira comments:
+${recentComments || "(none)"}
+
+Repository path:
+${input.repoPaths.join("\n")}
+
+Decide whether the requirements are clear enough to plan implementation. Read code only if it helps.`;
+}
+
+function getClaudeWorkspaceRoot(repoPaths) {
+  if (repoPaths.length === 1) {
+    return repoPaths[0];
+  }
+
+  let current = repoPaths[0];
+  for (const repoPath of repoPaths.slice(1)) {
+    current = commonAncestorPath(current, repoPath);
+  }
+  return current;
+}
+
+function commonAncestorPath(left, right) {
+  const leftParts = path.resolve(left).split(path.sep);
+  const rightParts = path.resolve(right).split(path.sep);
+  const shared = [];
+  const maxLength = Math.min(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < maxLength; index += 1) {
+    if (leftParts[index] !== rightParts[index]) {
+      break;
+    }
+    shared.push(leftParts[index]);
+  }
+
+  if (shared.length === 0) {
+    return path.parse(path.resolve(left)).root;
+  }
+
+  return shared.join(path.sep) || path.sep;
+}

package/src/cli.js

@@ -1,19 +1,28 @@
 import process from "node:process";
 
-import { runStartWizard } from "./commands/start.js";
+import { runStartCommand } from "./commands/start.js";
+import { runStatusCommand } from "./commands/status.js";
+import { runStopCommand } from "./commands/stop.js";
+import { runWorkerCommand } from "./commands/worker.js";
 
 const HELP_TEXT = `claude-teammate
 
 Usage:
   claude-teammate start
+  claude-teammate stop
+  claude-teammate status
   claude-teammate --help
 
 Commands:
-  start     Run the setup wizard and write configuration to .env
+  start     Start Claude Teammate in the background for this project
+  stop      Stop the background worker for this project
+  status    Show worker status, logs, and last Jira poll state
 `;
 
 export async function runCli(args) {
   const [command] = args;
+  const projectRoot = process.cwd();
+  const entrypointPath = process.argv[1];
 
   if (!command || command === "--help" || command === "-h") {
     process.stdout.write(`${HELP_TEXT}\n`);
@@ -21,7 +30,27 @@ export async function runCli(args) {
   }
 
   if (command === "start") {
-    await runStartWizard();
+    await runStartCommand({ projectRoot, entrypointPath });
+    return;
+  }
+
+  if (command === "stop") {
+    await runStopCommand({ projectRoot });
+    return;
+  }
+
+  if (command === "status") {
+    await runStatusCommand({ projectRoot });
+    return;
+  }
+
+  if (command === "run-worker") {
+    const workerProjectRoot = args[1];
+    if (!workerProjectRoot) {
+      throw new Error("Missing project root for run-worker.");
+    }
+
+    await runWorkerCommand({ projectRoot: workerProjectRoot });
     return;
   }