@flumecode/runner 0.0.1 → 0.2.0

package/dist/cli.js

@@ -175,6 +175,9 @@ var stepSchema = z2.object({
   files: z2.array(z2.string()).optional().describe("Affected file paths.")
 });
 var planInputSchema = {
+  title: z2.string().min(1).max(120).describe(
+    "A concise, descriptive name for THIS plan. Must be distinct from the request title and from any sibling plans on the same request. Keep it under 120 characters."
+  ),
   scope: z2.enum(["feat", "fix", "chore", "docs", "test", "refactor"]).describe("The primary intent of the change."),
   goal: z2.string().min(1).describe("One or two sentences stating the outcome."),
   assumptions: z2.array(z2.string()).describe("Anything decided during planning, including unanswered defaults."),
@@ -188,6 +191,8 @@ var planInputSchema = {
 var planSchema = z2.object(planInputSchema);
 function renderPlan(plan) {
   const lines = [];
+  lines.push(`# ${plan.title}`);
+  lines.push("");
   lines.push(`**Scope** \u2014 \`${plan.scope}\``);
   lines.push("");
   lines.push(`**Goal** \u2014 ${plan.goal}`);
@@ -235,7 +240,7 @@ function createPlanTooling() {
   let renderedPlan = null;
   const submitPlan = tool2(
     SUBMIT_PLAN,
-    "Submit the finished plan. Call this \u2014 and only this \u2014 when the plan is complete and ready to post. The runner renders your structured fields into the canonical plan markdown and posts it as your comment. acceptanceCriteria is required and must contain at least 2 observable, verifiable conditions (behaviors, tests, or states you could check) that together define 'done'. After calling this, end your turn.",
+    "Submit the finished plan. Call this \u2014 and only this \u2014 when the plan is complete and ready to post. The runner renders your structured fields into the canonical plan markdown and posts it as your comment. acceptanceCriteria is required and must contain at least 2 observable, verifiable conditions (behaviors, tests, or states you could check) that together define 'done'. After calling this, end your turn. The `title` field names this specific plan \u2014 make it concise and distinct from the request title.",
     planInputSchema,
     async (args) => {
       renderedPlan = renderPlan(planSchema.parse(args));
@@ -400,6 +405,41 @@ function buildPrompt(ctx) {
   );
   return lines.join("\n");
 }
+function buildRevisePrompt(ctx) {
+  const task = `Use the \`flumecode:revise-implementation\` skill to handle this turn. The plan below was already implemented (its report is included); the user is now asking to fine-tune that implementation. Decide how to respond to their latest message: if it's unclear, ask a clarifying question (as a widget); if it's a bad idea or not feasible, push back with your reasoning; if it warrants rethinking the plan, call \`submit_plan\` with a revised plan; otherwise implement the requested change. When you implement, you are the ORCHESTRATOR: delegate the work to subagents via the Task tool as the skill directs, and do not commit or push \u2014 the runner handles that, updating the existing pull request.`;
+  const orient = `Before investigating raw source, check for a FlumeCode wiki at \`.flumecode/wiki/\`. If it exists, read \`.flumecode/wiki/README.md\` first \u2014 it is the index \u2014 and follow its links to the pages and source paths relevant to this change. If there is no wiki, work from the code directly.`;
+  const widgets = `When you need the user to choose, ask it as a widget rather than writing the options as prose: call \`single_select\` for a one-of-N choice (radio buttons) or \`multi_select\` for a "select all that apply" choice (checkboxes). Don't add your own "Other" option \u2014 the UI always provides one. After calling a widget tool, end your turn \u2014 the user's answer comes back as their next message and starts a fresh run.`;
+  const lines = [
+    `You are "${ctx.agentName}", an autonomous coding agent fine-tuning an implemented FlumeCode plan in an ongoing thread with the user.`,
+    `The repository ${ctx.repo.fullName} is checked out in your current working directory on the plan's implementation branch "${ctx.repo.checkoutBranch}" \u2014 the same branch its open pull request is built from, so any change you push updates that PR.`,
+    task,
+    orient,
+    widgets,
+    "",
+    "These coding guidelines apply to all code produced in this run:",
+    "",
+    loadRule("coding-guideline"),
+    "",
+    `# Plan: ${ctx.request?.title ?? ""}`
+  ];
+  if (ctx.request?.body) {
+    lines.push("", ctx.request.body);
+  }
+  if (ctx.priorReport) {
+    lines.push("", "# Latest implementation report", "", ctx.priorReport);
+  }
+  if (ctx.thread && ctx.thread.length > 0) {
+    lines.push("", "# Conversation so far");
+    for (const turn of ctx.thread) {
+      lines.push("", `## ${turn.role === "agent" ? ctx.agentName : "User"}`, turn.content);
+    }
+  }
+  lines.push(
+    "",
+    "The last message above is the user's request for this turn. Your final reply is posted verbatim as your comment in the plan thread: if you implemented a change, make it a short report of what you changed (the runner appends the pull-request link); if you asked a question, called `submit_plan`, or pushed back, your reply text is posted as-is."
+  );
+  return lines.join("\n");
+}
 function buildDocumentPrompt(ctx) {
   const lines = [
     `You are "${ctx.agentName}" maintaining the repository wiki for ${ctx.repo.fullName}.`,
@@ -496,12 +536,23 @@ async function cloneAtSha(ctx, dir) {
   await git(["clone", "--quiet", cloneUrl(ctx), dir]);
   await git(["-C", dir, "checkout", "-B", ctx.repo.checkoutBranch, ctx.repo.checkoutSha]);
 }
+async function cloneResumingBranch(ctx, dir) {
+  await git(["clone", "--quiet", cloneUrl(ctx), dir]);
+  try {
+    await git(["-C", dir, "fetch", "--quiet", "origin", ctx.repo.checkoutBranch]);
+    await git(["-C", dir, "checkout", "-B", ctx.repo.checkoutBranch, "FETCH_HEAD"]);
+    return { resumed: true };
+  } catch {
+    await git(["-C", dir, "checkout", "-B", ctx.repo.checkoutBranch, ctx.repo.checkoutSha]);
+    return { resumed: false };
+  }
+}
 async function hasChanges(dir) {
   await git(["-C", dir, "add", "-A"]);
   const { stdout: stdout2 } = await git(["-C", dir, "status", "--porcelain"]);
   return stdout2.trim().length > 0;
 }
-async function commitAndPush(ctx, dir) {
+async function commitChanges(ctx, dir) {
   if (!await hasChanges(dir)) return false;
   await git([
     "-C",
@@ -515,9 +566,36 @@ async function commitAndPush(ctx, dir) {
     "-m",
     `FlumeCode: ${jobTitle(ctx)}`
   ]);
-  await git(["-C", dir, "push", "--quiet", "-u", "origin", ctx.repo.checkoutBranch]);
   return true;
 }
+async function pushBranch(ctx, dir) {
+  await git(["-C", dir, "push", "--quiet", "-u", "origin", ctx.repo.checkoutBranch]);
+}
+var RebaseConflictError = class extends Error {
+  constructor(mergeBranch, files) {
+    const list = files.length ? `: ${files.join(", ")}` : "";
+    super(`Rebase onto ${mergeBranch} hit conflicts in ${files.length} file(s)${list}`);
+    this.mergeBranch = mergeBranch;
+    this.files = files;
+    this.name = "RebaseConflictError";
+  }
+};
+async function rebaseOntoMergeBranch(ctx, dir) {
+  const { mergeBranch } = ctx.repo;
+  if (!mergeBranch) return;
+  await git(["-C", dir, "fetch", "--quiet", "origin", mergeBranch]);
+  try {
+    await git(["-C", dir, "rebase", "FETCH_HEAD"]);
+  } catch {
+    const conflicted = await git(["-C", dir, "diff", "--name-only", "--diff-filter=U"]).catch(
+      () => ({ stdout: "" })
+    );
+    const files = conflicted.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+    await git(["-C", dir, "rebase", "--abort"]).catch(() => {
+    });
+    throw new RebaseConflictError(mergeBranch, files);
+  }
+}
 async function openPullRequest(ctx) {
   const { owner, name, cloneToken, checkoutBranch, mergeBranch } = ctx.repo;
   if (!mergeBranch) return null;
@@ -568,9 +646,11 @@ var ORCHESTRATOR_MAX_TURNS = 80;
 var INIT_MAX_TURNS = 200;
 var DOCUMENT_MAX_TURNS = 120;
 var HEARTBEAT_MS = 5 * 6e4;
-async function pushAndOpenPr(ctx, dir) {
-  const pushed = await commitAndPush(ctx, dir);
-  if (!pushed) return { kind: "none" };
+async function pushAndOpenPr(ctx, dir, opts = { rebase: true }) {
+  const committed = await commitChanges(ctx, dir);
+  if (!committed) return { kind: "none" };
+  if (opts.rebase) await rebaseOntoMergeBranch(ctx, dir);
+  await pushBranch(ctx, dir);
   const pr = await openPullRequest(ctx);
   return pr ? { kind: "pr", pr } : { kind: "pushed" };
 }
@@ -599,6 +679,7 @@ async function processJob(ctx) {
   try {
     if (ctx.kind === "init") return await processInitJob(ctx, dir);
     if (ctx.kind === "implement") return await processImplementJob(ctx, dir);
+    if (ctx.kind === "revise") return await processReviseJob(ctx, dir);
     return await processChatJob(ctx, dir);
   } finally {
     await cleanup(dir);
@@ -670,7 +751,7 @@ async function processChatJob(ctx, dir) {
 async function processImplementJob(ctx, dir) {
   console.log(`
 \u25B6 Implement ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
-  await cloneAtSha(ctx, dir);
+  const { resumed } = await cloneResumingBranch(ctx, dir);
   const installResult = await installDependencies(dir);
   const result = await runClaudeCode({
     cwd: dir,
@@ -700,10 +781,55 @@ async function processImplementJob(ctx, dir) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir);
+  const outcome = await pushAndOpenPr(ctx, dir, { rebase: !resumed });
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
   return { text: reply, widgets: [], ...outcome.kind === "pr" ? { pr: outcome.pr } : {} };
 }
+async function processReviseJob(ctx, dir) {
+  console.log(`
+\u25B6 Revise ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
+  const { resumed } = await cloneResumingBranch(ctx, dir);
+  const installResult = await installDependencies(dir);
+  const result = await runClaudeCode({
+    cwd: dir,
+    prompt: buildRevisePrompt(ctx),
+    permissionMode: ctx.permissionMode,
+    model: ORCHESTRATOR_MODEL,
+    maxTurns: ORCHESTRATOR_MAX_TURNS
+  });
+  const summary = result.text.trim();
+  let reply = summary || "(the agent produced no reply)";
+  if (result.plan) reply = result.plan;
+  if (installResult.status === "failed") {
+    reply += `
+
+> \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
+  }
+  if (result.widgets.length > 0) {
+    console.log(`  \u2026revise ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
+    return { text: reply, widgets: result.widgets };
+  }
+  let documented = false;
+  if (await hasChanges(dir)) {
+    try {
+      console.log(`  \u2026updating wiki for revise ${ctx.jobId}`);
+      await runClaudeCode({
+        cwd: dir,
+        prompt: buildDocumentPrompt(ctx),
+        permissionMode: ctx.permissionMode,
+        maxTurns: DOCUMENT_MAX_TURNS
+      });
+      documented = true;
+    } catch (err) {
+      console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
+    }
+  }
+  const outcome = await pushAndOpenPr(ctx, dir, { rebase: !resumed });
+  if (outcome.kind !== "none") {
+    reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
+  }
+  return { text: reply, widgets: [], ...outcome.kind === "pr" ? { pr: outcome.pr } : {} };
+}
 async function heartbeat(config) {
   const health = await checkClaudeCode();
   if (health.ready) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -57,6 +57,8 @@ it as your comment — do **not** write the plan as your reply text.
 
 Field-by-field guidance:
 
+- **`title`** — a concise, descriptive name for this specific plan. Must be distinct from the
+  request title and from any sibling plans on the same request. Keep it under 120 characters.
 - **`scope`** — exactly one of `feat`, `fix`, `chore`, `docs`, `test`,
   `refactor`. Pick the one that best matches the primary intent of the request.
 - **`goal`** — one or two sentences stating the outcome, phrased so it directly
@@ -85,9 +87,10 @@ plan without re-deriving it.
 A single request can yield **several** plans — one thread can be accepted into
 many. If the work naturally splits into independent pieces, or the user asks for
 more than one plan, call `submit_plan` once for each finished plan so each can
-be accepted into its own GitHub issue. After a plan is accepted the user may
-keep commenting to refine it; treat a later turn as a fresh **Plan** phase and
-call `submit_plan` again with the revised fields.
+be accepted into its own GitHub issue. Give each plan its own distinct `title`
+so sibling plans don't collide. After a plan is accepted the user may keep
+commenting to refine it; treat a later turn as a fresh **Plan** phase and call
+`submit_plan` again with the revised fields.
 
 ## Always
 

package/skills-plugin/skills/revise-implementation/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: revise-implementation
+description: >-
+  Handle a follow-up turn on an already-implemented plan, where the user asks to
+  fine-tune the result. Use in edit-capable plan-thread runs. First decide how to
+  respond — clarify, push back, propose a revised plan, or implement the change —
+  then act: for code changes you are the orchestrator (delegate to subagents like
+  implement-plan) and the runner updates the existing pull request. Never commits,
+  pushes, or opens a PR yourself.
+---
+
+# revise-implementation
+
+The plan in the context above was **already implemented** — its latest report and
+the open pull request exist, and your working directory is checked out on that
+PR's branch. The user has now posted a follow-up message asking to fine-tune the
+result. Your job is to respond to that message well: sometimes by changing code,
+but just as often by asking, pushing back, or re-planning.
+
+## You are stateless — orient yourself first
+
+Each run you see the whole thread but keep **no memory** between turns. You cannot
+pause mid-run to wait for the user: to ask something, end your turn with the
+question and the user's reply starts a fresh run that re-enters this skill. So
+read the conversation first — the **last user message is this turn's request** —
+and note anything you already asked and they already answered (treat it settled).
+
+## Step 1 — Decide how to respond
+
+Read the latest user message against the plan, the implementation report, and the
+actual code. Pick exactly one:
+
+- **Clarify** — the request is ambiguous or under-specified. Ask the user, then
+  stop. When it's a clean choice, ask it as a widget: `single_select` for one-of-N,
+  `multi_select` for "select all that apply" (don't add your own "Other" — the UI
+  always offers one). Otherwise ask in prose. After asking, **end your turn**; make
+  no code changes.
+- **Push back** — the request is a bad idea, unsafe, or not feasible as asked.
+  Explain why in plain prose, offer an alternative if you have one, and end your
+  turn. Make no code changes.
+- **Re-plan** — the request meaningfully changes scope or direction, enough that a
+  fresh plan should be agreed before building. Call **`submit_plan`** with the
+  revised structured fields (same shape as the request-to-plan skill: `scope`,
+  `goal`, `assumptions`, `steps`, `acceptanceCriteria` — at least 2 —, `risks`,
+  `outOfScope`). The runner posts it as a revision the user can accept; make no
+  code changes this turn.
+- **Implement** — the request is clear and reasonable. Make the change (via
+  subagents — see Step 2). This is the common case for small fine-tuning.
+
+When in doubt between Clarify and Implement, prefer a quick clarifying question
+over guessing on anything that would be costly to redo.
+
+## Step 2 — Implement (only if you chose Implement)
+
+You are the **orchestrator**, exactly as in the `implement-plan` skill: do not
+write the code yourself — delegate each phase to **Task** subagents and pick the
+right model per phase. Read `implement-plan` if you need the full pipeline; the
+essentials:
+
+- **Subagents start blank.** Each Task subagent sees only the prompt you give it —
+  not this thread, the plan, or the prior report. Make every prompt self-contained:
+  include the specific change requested, the relevant plan/report excerpt, the code
+  context, and the coding guidelines (verbatim, from the `# Coding Guidelines`
+  section in the prompt).
+- **Scope the work to the request.** This is a fine-tune of an existing
+  implementation, not a rebuild. Change only what the user asked for plus what that
+  change strictly requires; don't regress the rest of the plan.
+- **Pipeline:** Implement (Task, `model: "sonnet"`) → acceptance/quality review of
+  the change (Task, `model: "opus"`, read-only) → fix loop if needed (≤2) → report
+  (Task, `model: "opus"`, read-only). Reviewers and the report writer never edit.
+- **No git side effects.** Never commit, push, or open a PR — leave the changes in
+  the working tree. The runner commits them and updates the existing pull request.
+
+## Your final reply
+
+Your last message **is** the comment posted to the plan thread — write it for the
+user:
+
+- **Implemented:** a short report — what you changed and why, which files, and how
+  it was verified (build/tests). The runner appends the pull-request link, so don't
+  add one.
+- **Clarify / push back:** your question or reasoning, as prose (plus any widget).
+- **Re-plan:** you called `submit_plan`; the rendered plan is posted automatically,
+  so keep any extra reply text minimal.
+
+## Always
+
+- Decide before you act; don't implement an ambiguous or ill-advised request.
+- Delegate code changes through Task subagents — don't write code yourself.
+- Keep the change scoped to this turn's request; don't regress the implementation.
+- Never commit, push, or open a PR.
+- Your final message is what the user reads.