@nanobpm/nano-workforce 0.73.1 → 0.74.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.74.0](https://github.com/nanobpm/nano-workforce/compare/v0.73.1...v0.74.0) (2026-08-16)
+
+
+### Features
+
+* **feature:** thread optional custom instructions to the implementation agent ([#247](https://github.com/nanobpm/nano-workforce/issues/247)) ([8b65495](https://github.com/nanobpm/nano-workforce/commit/8b65495a739b01560937fa108ed4def16c3ffd85))
+
 ## [0.73.1](https://github.com/nanobpm/nano-workforce/compare/v0.73.0...v0.73.1) (2026-08-16)
 
 

package/app/feature.test.ts

@@ -114,6 +114,42 @@ test("startFeature: seeds the single task slice + base-branch brief onto the ins
   assertEquals(v.status, null);
 });
 
+test("startFeature: custom instructions ride the instance as a variable (trimmed)", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-3" });
+    },
+  } as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "main",
+    false,
+    false,
+    "  prefer Deno; keep the diff small  ",
+  );
+  assertEquals(captured.variables.customInstructions, "prefer Deno; keep the diff small");
+});
+
+test("startFeature: blank/absent custom instructions are seeded as null", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-4" });
+    },
+  } as any;
+  // Absent (default arg) → null.
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false);
+  assertEquals(captured.variables.customInstructions, null);
+  // Whitespace-only → null (so the appendPrompt FEEL skips the block instead of appending an empty heading).
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false, "   ");
+  assertEquals(captured.variables.customInstructions, null);
+});
+
 test("startFeature: an already-running run short-circuits (no new instance)", async () => {
   const stores = {
     feature_runs: {

package/app/feature.ts

@@ -267,7 +267,14 @@ export async function startFeature(
   baseBranch: string,
   converge: boolean,
   autoMerge: boolean,
+  customInstructions: string | null = null,
 ) {
+  // Operator free-text steering for the implementation agent (issue #172 follow-on): blank/absent →
+  // null so the implement task's `appendPrompt` FEEL (`customInstructions = null`) skips the block
+  // rather than appending an empty "Operator custom instructions" heading.
+  const instructions = typeof customInstructions === "string" && customInstructions.trim() !== ""
+    ? customInstructions.trim()
+    : null;
   const table = featureRuns(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !FEATURE_TERMINAL_STATUSES.includes(existing.status)) {
@@ -356,6 +363,10 @@ export async function startFeature(
       // brief rides `appendPrompt` in the implement task, exactly like the epic implementer.
       baseBranch: base,
       baseBranchBrief: renderBaseBranchBrief(base),
+      // Optional operator steering, appended to the implement agent's prompt via the implement
+      // task's `appendPrompt` FEEL (feature.bpmn). Null when none was supplied; persists on the
+      // instance so it also rides the answer-loop redispatch back into the same implement task.
+      customInstructions: instructions,
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/openapi.yaml

@@ -668,6 +668,13 @@ components:
           description: >-
             Opt in to sharing a custom integration base branch with another already-active epic. See
             `PlanStartByIssue.allowSharedBase`.
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: >-
+            OPTIONAL free-text steering appended to the implementation agent's prompt for this run
+            (via the implement task's `appendPrompt`). Blank/whitespace is treated as absent. Persists
+            on the instance, so it also applies to the agent's answer-loop redispatch.
     FeatureStartByUrl:
       type: object
       additionalProperties: false
@@ -698,6 +705,12 @@ components:
         allowSharedBase:
           type: boolean
           description: Share a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: >-
+            OPTIONAL free-text steering appended to the implementation agent's prompt for this run.
+            See `FeatureStartByIssue.customInstructions`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startFeature.ts

@@ -115,12 +115,18 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
   // the persisted row and the process variable can't disagree.
   const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;
-  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge);
+  // Optional operator steering threaded to the implementation agent's prompt. Empty/whitespace is
+  // normalized to null downstream (startFeature) so it never appends an empty instruction block.
+  const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
+    ? body.customInstructions
+    : null;
+  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge, customInstructions);
   app.log.info("feature run started", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
+    hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
   });
   return { status: 202, body: result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.73.1",
+  "version": "0.74.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/feature.page.json

@@ -42,6 +42,7 @@
         "fields": [
           { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text", "required": true, "requiredMessage": "An issue reference is required (owner/repo#123 or an issue URL)" },
           { "key": "baseBranch", "label": "Base branch: the branch the PR targets, e.g. main. A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text", "required": true, "requiredMessage": "Name the branch the PR targets (e.g. main or epic/agent-protocol)" },
+          { "key": "customInstructions", "label": "Custom instructions (optional) \u2014 extra steering appended to the implementation agent's prompt, e.g. \u201cprefer Deno; keep the diff small; add integration tests\u201d", "type": "text" },
           { "key": "converge", "label": "Converge \u2014 hand the raised PR to the review-convergence loop", "type": "checkbox" },
           { "key": "autoMerge", "label": "Auto-merge \u2014 after convergence, drive the merge-loop (only applies when Converge is on)", "type": "checkbox" },
           { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default", "type": "checkbox" },

package/resources/processes/feature.bpmn

@@ -44,7 +44,7 @@
           <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
-          <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief)" target="appendPrompt" />
+          <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
           <zeebe:output source="=status" target="status" />
           <zeebe:output source="=question" target="question" />
         </zeebe:ioMapping>