@nanobpm/nano-workforce 0.61.1 → 0.62.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.62.0](https://github.com/nanobpm/nano-workforce/compare/v0.61.1...v0.62.0) (2026-08-13)
+
+
+### Features
+
+* **feature-prompt:** claim the issue with a comment before starting work ([#207](https://github.com/nanobpm/nano-workforce/issues/207)) ([b1b23c9](https://github.com/nanobpm/nano-workforce/commit/b1b23c9928704616aa2173cfa056668a11d32e1c))
+
 ## [0.61.1](https://github.com/nanobpm/nano-workforce/compare/v0.61.0...v0.61.1) (2026-08-13)
 
 

package/app/feature.test.ts

@@ -104,6 +104,8 @@ test("startFeature: seeds the single task slice + base-branch brief onto the ins
   assertEquals(v.task.prompt.includes("owner/repo#42"), true);
   assertEquals(v.converge, true);
   assertEquals(v.autoMerge, false);
+  // A single-issue run owns its issue, so the agent is told it may claim it (epic slices never set this).
+  assertEquals(v.claimIssue, true);
   assertEquals(v.baseBranch, "epic/x");
   // The brief is the authoritative base-branch override the agent gets via appendPrompt.
   assertEquals(v.baseBranchBrief.includes("epic/x"), true);

package/app/feature.ts

@@ -202,6 +202,11 @@ export async function startFeature(
       // merge-loop. `converge=false` ⇒ merge is moot.
       converge,
       autoMerge,
+      // A single-issue feature run OWNS its issue (the whole issue is the slice), so the agent may
+      // claim it with a "starting work" comment on a first run (prompts/feature.md). Epic slices
+      // (plan-fanout) deliberately DO NOT set this — their `issue` is the shared parent epic, which
+      // must never be claimed per-slice.
+      claimIssue: true,
       // Seed the agent-result variables so the escalation loop + record worker can reference them
       // before the first `senior:feature` job completes (the harness merges the real values in).
       answer: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.61.1",
+  "version": "0.62.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/prompts/feature.md

@@ -22,16 +22,44 @@ You have `gh` / git authenticated for the target repository.
 
 Always use the branch **`feat/<task.id>`**. Because a resumed run gets a fresh
 process with no memory of your last run, the branch name MUST be derivable from
-`task.id` alone. On start, check whether it already exists on the remote
-(`git ls-remote --heads origin feat/<task.id>` or
-`gh pr list --head feat/<task.id> --state all`):
+`task.id` alone. On start, check whether it already exists on the remote with
+`git ls-remote --heads origin feat/<task.id>` — a non-empty result means the
+branch exists. Use this ref check as the authoritative first-run/resume signal:
+a remote branch can exist without any PR, so `gh pr list --head feat/<task.id> --state all`
+is reliable only as a *supplementary* PR lookup once `git ls-remote` has
+established the branch exists, never as the existence check itself:
 
 - **It does not exist** → this is a first run. Branch off the base branch (see
   the note below — usually the repository default branch, but an epic may pin an
-  integration branch in your appended task context).
+  integration branch in your appended task context). **Claim the issue now** — see
+  below.
 - **It exists** → this is a **resume**. `git fetch` and check it out, read its diff
   and any open (draft) PR, and **continue from there** — do not restart from
-  scratch. Fold in `variables.answer` as the guidance you were waiting on.
+  scratch. Fold in `variables.answer` as the guidance you were waiting on. Do
+  **not** re-claim — you already announced this run on your first pass.
+
+## Claim your issue on a first run (only when `variables.claimIssue` is true)
+
+So humans and other agents can see the work has been picked up, announce yourself
+on the issue **before implementing** — but ONLY on a first run (your
+`feat/<task.id>` branch did not yet exist, per the check above) AND only when
+**`variables.claimIssue` is true**:
+
+```sh
+gh issue comment <variables.issue> --body-file - <<'BODY'
+🤖 Starting work on this issue — branch `feat/<task.id>`.
+BODY
+```
+
+- `variables.claimIssue` is set **only for single-issue feature runs**, where
+  `variables.issue` IS the issue you implement and close, so claiming it is
+  correct. **Epic slices leave it unset** — their `variables.issue` is the shared
+  *parent epic*, which must never be claimed per-slice; when `claimIssue` is not
+  true, **skip this step entirely**.
+- The branch-existence check above is what makes this idempotent: a resumed run
+  (branch already exists) never re-claims, so the issue gets exactly one claim.
+- It is a courtesy claim, **not a gate** — if the comment fails (e.g. a transient
+  `gh` error), carry on and implement anyway.
 
 ## Your base branch (default branch, unless the epic pins one)
 
@@ -44,14 +72,16 @@ against the wrong base will not be merged into the epic.
 
 ## What to do
 
-1. Clone / check out your base branch (first run — the default branch, or the
+1. Claim your issue if `variables.claimIssue` is true and this is a first run (see
+   above).
+2. Clone / check out your base branch (first run — the default branch, or the
    pinned epic branch if your context names one) or your existing
    `feat/<task.id>` branch (resume — see above).
-2. Implement `task.prompt`. Keep the change scoped to this slice only.
-3. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the
+3. Implement `task.prompt`. Keep the change scoped to this slice only.
+4. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the
    branch, and open a pull request with `gh pr create` describing the slice and
    linking the parent issue (`Depends-on:`/`Closes` as appropriate).
-4. Clean up any scratch clone/worktree you created outside the commit.
+5. Clean up any scratch clone/worktree you created outside the commit.
 
 > **Do not request the Copilot review yourself.** When you open a *ready* PR the
 > app enrolls it into the review-convergence loop and requests the initial