workflows/_shared/workspace-committer.ts

@@ -10,16 +10,44 @@ export const committerMetaSchema = z.object({
 });
 export type CommitterMeta = z.infer<typeof committerMetaSchema>;
 
-function workspaceCommitterPrompt(threadId: string): string {
+export type BuildWorkspaceCommitterDeps = {
-  return `You are the committer agent. The coder finished with a passing build; your job is to branch, commit, and push.
+  extract: LlmExtractorConfig;
+  nerveRoot: string;
+  workflowName: string;
+  conventionalCommitScopeHint: string;
+  branchCheckoutExample: string;
+};
 
-1. Read the workflow thread: \`nerve thread show ${threadId}\` — understand what was planned, coded, and reviewed.
+function workspaceCommitterPrompt({
-2. Run \`git status\`. If nothing to commit, set committed=false.
+  threadId,
-3. Create a feature branch: infer a good \`fix/<slug>\` or \`feat/<slug>\` name from the thread context.
+  nerveRoot,
-4. \`git add -A\`
+  workflowName,
-5. Write a conventional commit message based on the thread context.
+  conventionalCommitScopeHint,
-6. \`git commit -m "<message>"\` — do NOT pass \`--author\`, use repo git config.
+  branchCheckoutExample,
-7. \`git push -u origin <branch>\`
+}: {
+  threadId: string;
+  nerveRoot: string;
+  workflowName: string;
+  conventionalCommitScopeHint: string;
+  branchCheckoutExample: string;
+}): string {
+  return `You are the **committer** agent (Hermes) for the **${workflowName}** workflow. The coder finished with a passing build; you branch, commit, and push workspace changes.
+
+## Context
+
+1. Read the workflow thread: \`nerve thread show ${threadId}\`
+2. Your git repository root is: \`${nerveRoot}\` — \`cd\` there for all git commands.
+
+## Steps (in order)
+
+1. Run \`git status\`. There should be uncommitted changes from the coder. If there is nothing to commit, set **committed** to false and explain.
+2. Create a short-lived branch (do not commit directly on the default branch if it would mix unrelated work):
+   - Prefer \`fix/<short-slug>\` or \`feat/<short-slug>\` with a lowercase hyphenated slug from the thread (planner/coder context).
+   - Example: \`${branchCheckoutExample}\`
+3. \`git add -A\`
+4. Write a **conventional commit** message summarizing what changed and why (scope may be \`${conventionalCommitScopeHint}\` or similar).
+5. \`git commit -m "<message>"\` (use multiple \`-m\` if you need a body). Do **not** pass \`--author\` — always use the repo's local git config identity.
+6. \`git push -u origin <branch-name>\`
 
 **committed=true** only if branch was created, commit succeeded, and **push** succeeded.
 
@@ -35,11 +63,24 @@ or
 
 export function createWorkspaceCommitterRole(
   adapter: AgentFn,
-  extract: LlmExtractorConfig,
+  {
+    extract,
+    nerveRoot,
+    workflowName,
+    conventionalCommitScopeHint,
+    branchCheckoutExample,
+  }: BuildWorkspaceCommitterDeps,
 ): Role<CommitterMeta> {
   const innerRole = createRole(
     adapter,
-    async (start: StartStep) => workspaceCommitterPrompt(start.meta.threadId),
+    async (start: StartStep) =>
+      workspaceCommitterPrompt({
+        threadId: start.meta.threadId,
+        nerveRoot,
+        workflowName,
+        conventionalCommitScopeHint,
+        branchCheckoutExample,
+      }),
     committerMetaSchema,
     extract,
   );
@@ -52,8 +93,13 @@ export function createWorkspaceCommitterRole(
       };
     }
 
+    const innerStart = {
+      ...start,
+      meta: { ...start.meta, workdir: nerveRoot },
+    } as StartStep;
+
     try {
-      return await innerRole(start, _messages);
+      return await innerRole(innerStart, _messages);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       return {

workflows/develop-sense/build.ts

@@ -28,7 +28,13 @@ export function createDevelopSenseWorkflow({
     coder: createCoderRole(a('coder'), extract),
     reviewer: createReviewerRole(a('reviewer'), extract, cwd),
     tester: createTesterRole(a('tester'), extract, cwd),
-    committer: createWorkspaceCommitterRole(a('committer'), extract),
+    committer: createWorkspaceCommitterRole(a('committer'), {
+      extract,
+      nerveRoot: cwd,
+      workflowName: "develop-sense",
+      conventionalCommitScopeHint: "sense",
+      branchCheckoutExample: "git checkout -b fix/sense-export-path",
+    }),
   };
 
   return {

workflows/develop-sense/roles/committer.ts

@@ -1,5 +1,6 @@
 export {
   createWorkspaceCommitterRole,
   committerMetaSchema,
+  type BuildWorkspaceCommitterDeps,
   type CommitterMeta,
 } from "../../_shared/workspace-committer.js";

workflows/develop-workflow/build.ts

@@ -28,7 +28,13 @@ export function createDevelopWorkflowWorkflow({
     coder: createCoderRole(a('coder'), extract),
     reviewer: createReviewerRole(a('reviewer'), extract, nerveRoot),
     tester: createTesterRole(a('tester'), extract, nerveRoot),
-    committer: createWorkspaceCommitterRole(a('committer'), extract),
+    committer: createWorkspaceCommitterRole(a('committer'), {
+      extract,
+      nerveRoot,
+      workflowName: "develop-workflow",
+      conventionalCommitScopeHint: "workflow",
+      branchCheckoutExample: "git checkout -b feat/workflow-new-step",
+    }),
   };
 
   return {

workflows/develop-workflow/roles/committer.ts

@@ -1,5 +1,6 @@
 export {
   createWorkspaceCommitterRole,
   committerMetaSchema,
+  type BuildWorkspaceCommitterDeps,
   type CommitterMeta,
 } from "../../_shared/workspace-committer.js";

workflows/solve-issue/build.ts

@@ -33,7 +33,7 @@ export function createSolveIssueWorkflow({
       prepare: createPrepareRole(a("prepare"), extract),
       plan: createPlanRole(a("plan"), { extract, nerveRoot }),
       implement: createImplementRole(a("implement"), { extract, nerveRoot }),
-      committer: createCommitterRole(a("committer"), extract),
+      committer: createCommitterRole(a("committer"), { extract, nerveRoot }),
       review: createReviewRole(a("review"), extract, nerveRoot),
       test: createTestRole(a("test"), extract),
       publish: createPublishRole(a("publish"), { extract, nerveRoot }),

workflows/solve-issue/roles/committer/index.ts

@@ -3,6 +3,7 @@ import type { LlmExtractorConfig } from "@uncaged/nerve-workflow-utils";
 import { createRole, isDryRun } from "@uncaged/nerve-workflow-utils";
 import { z } from "zod";
 
+import { resolveRepoCwd } from "../../lib/repo-context.js";
 import { committerPrompt } from "./prompt.js";
 
 export const committerMetaSchema = z.object({
@@ -12,18 +13,35 @@ export const committerMetaSchema = z.object({
 });
 export type CommitterMeta = z.infer<typeof committerMetaSchema>;
 
+export type CreateCommitterRoleDeps = {
+  extract: LlmExtractorConfig;
+  nerveRoot: string;
+};
+
 export function createCommitterRole(
   adapter: AgentFn,
-  extract: LlmExtractorConfig,
+  { extract, nerveRoot }: CreateCommitterRoleDeps,
 ): Role<CommitterMeta> {
   const innerRole = createRole(
     adapter,
-    async (start: StartStep) => committerPrompt({ threadId: start.meta.threadId }),
+    async (start: StartStep) =>
+      committerPrompt({
+        threadId: start.meta.threadId,
+        nerveRoot,
+      }),
     committerMetaSchema,
     extract,
   );
 
   return async (start: StartStep, messages: WorkflowMessage[]): Promise<RoleResult<CommitterMeta>> => {
+    const cwd = resolveRepoCwd(messages);
+    if (cwd === null) {
+      return {
+        content: "committer cannot run: missing repo path in thread markers",
+        meta: { committed: false },
+      };
+    }
+
     if (isDryRun(start)) {
       return {
         content: "[dry-run] committer skipped (no git branch/commit/push)",
@@ -31,8 +49,13 @@ export function createCommitterRole(
       };
     }
 
+    const innerStart = {
+      ...start,
+      meta: { ...start.meta, workdir: cwd },
+    } as StartStep;
+
     try {
-      return await innerRole(start, messages);
+      return await innerRole(innerStart, messages);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       return {

workflows/solve-issue/roles/committer/prompt.ts

@@ -1,21 +1,40 @@
-export function committerPrompt({ threadId }: { threadId: string }): string {
+export function committerPrompt({
-  return `You are the committer agent. The **implement** step finished with a passing build; your job is to branch, commit, and push.
+  threadId,
+  nerveRoot,
+}: {
+  threadId: string;
+  nerveRoot: string;
+}): string {
+  return `You are the **committer** agent (Hermes). The **implement** step finished with a passing build; your job is to put those changes on a feature branch and push to **origin**.
 
-1. Read the workflow thread: \`nerve thread show ${threadId}\` — understand what was planned, implemented, and reviewed.
+## Context
-2. In the thread, locate \`---SOLVE_ISSUE_PARSE---\` and \`---SOLVE_ISSUE_REPO---\`. From them you need issue **number**, **title** (for the branch slug), repo **path**, and **defaultBranch**.
+
-3. \`cd\` to the repo **path** from the markers. Optionally read \`CONVENTIONS.md\` in that repo root if present.
+- Read the full workflow thread: \`nerve thread show ${threadId}\`
-4. Run \`git rev-parse --abbrev-ref HEAD\` and compare with **defaultBranch** from the markers. Implement leaves changes uncommitted on the default branch — you should be on that branch with a dirty working tree. If you are not on the default branch, or the tree is clean when you expected changes, set **committed** to false and explain.
+- Optional workspace tone: \`cat ${nerveRoot}/CONVENTIONS.md\`
-5. Run \`git status\`. If there is nothing to commit, set **committed** to false and explain.
+
-6. Create a feature branch (do not commit directly on the default branch if it would mix unrelated work):
+## Find repo and issue markers
+
+In the thread, locate \`---SOLVE_ISSUE_PARSE---\` and \`---SOLVE_ISSUE_REPO---\`. From them you need:
+
+- Issue **number** and **title** (from PARSE; title for the branch slug)
+- Repo checkout **path** (from REPO \`path\`) — this is your working copy; your shell cwd should be this directory.
+
+## Steps (in order)
+
+1. \`cd\` to the repo **path** from SOLVE_ISSUE_REPO.
+2. Run \`git rev-parse --abbrev-ref HEAD\` and compare with **defaultBranch** from SOLVE_ISSUE_REPO. Implement leaves changes **uncommitted** on the default branch — you should be on that branch with a dirty working tree. If you are not on the default branch, or the tree is clean with nothing to commit when you expected changes, set **committed** to false and explain (avoids empty PRs from wrong state).
+3. Run \`git status\`. There should be **uncommitted** changes from implement. If the tree is clean with nothing to commit, set **committed** to false and explain.
+4. Create a feature branch (do not work on the default branch directly):
    - Name: \`fix/<number>-<short-slug>\` for fixes, or \`feat/<number>-<short-slug>\` if the issue is clearly a feature.
+   - **number** from SOLVE_ISSUE_PARSE.
    - **slug**: lowercase, hyphens only, short (from issue title words).
    - Example: \`git checkout -b fix/42-auth-timeout\`
-7. \`git add -A\`
+5. \`git add -A\`
-8. Write a **conventional commit** message describing what changed and why, using the thread context.
+6. Write a **conventional commit** message (e.g. \`fix(scope): summary\` or \`feat(scope): summary\`) describing **what** changed and **why**, using the thread (plan + implement context).
-9. \`git commit -m "<message>"\` — do NOT pass \`--author\`, use repo git config.
+7. \`git commit -m "<message>"\` — use a single \`-m\` for a one-line message, or multiple \`-m\` for body paragraphs if needed. Do **not** pass \`--author\` — always use the repo's local git config identity.
-10. \`git push -u origin <branch-name>\`
+8. \`git push -u origin <branch-name>\`
 
-**committed=true** only if branch was created, commit succeeded, and **push** succeeded.
+**committed=true** only if you created the branch, committed successfully, and **push** succeeded.
 
 End your reply with a JSON line:
 \`\`\`json