@nanobpm/nano-workforce 0.108.0 → 0.109.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.109.0](https://github.com/nanobpm/nano-workforce/compare/v0.108.0...v0.109.0) (2026-08-20)
+
+
+### Features
+
+* **skill:** add nano-workforce operator bootstrap skill ([#382](https://github.com/nanobpm/nano-workforce/issues/382)) ([ef6701f](https://github.com/nanobpm/nano-workforce/commit/ef6701f4df76bcfc762ddec20d745bf5edd0ec1b))
+
 # [0.108.0](https://github.com/nanobpm/nano-workforce/compare/v0.107.2...v0.108.0) (2026-08-20)
 
 

package/app/agentSkill.ts

@@ -0,0 +1,54 @@
+// The Nano Workforce operator *skill* served by GET /app/api/agent/skill (operationId
+// `getAgentSkill`). Companion to the agent guide (app/agentGuide.ts): where the guide is the full,
+// instance-keyed playbook, the skill is a small, portable *bootstrap* an agent runtime (Copilot
+// CLI, Claude) loads on demand — it resolves which instance to drive and then fetches the live
+// guide. The user clicks "Agent Instructions" on the Overview tab, copies the prompt, and the agent
+// loads THIS skill from THIS instance.
+//
+// The skill is authored as plain markdown in `skills/nano-workforce/SKILL.md` (kept OUT of
+// `resources/` so the deploy-by-convention walk does NOT treat it as a deployable model, ADR 0062)
+// and read from the checkout at module load — same approach as agentGuide.ts / version.ts. A
+// `__BASE__` placeholder, if present, is substituted per request so any embedded example is
+// copy-pasteable against THIS instance.
+//
+// Reading is best-effort: a missing file yields a short built-in fallback rather than throwing, so
+// the endpoint never 500s just because the skill is absent from a stripped-down deploy.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SKILL_PATH = join(REPO_ROOT, "skills", "nano-workforce", "SKILL.md");
+
+// Read the raw skill once, at module load. Frozen for the life of the process.
+const RAW_SKILL: string = (() => {
+  try {
+    return readFileSync(SKILL_PATH, "utf8");
+  } catch {
+    return [
+      "---",
+      "name: nano-workforce",
+      "description: Drive and debug a running Nano Workforce instance.",
+      "---",
+      "",
+      "# Nano Workforce operator skill",
+      "",
+      "This skill could not be read from this deployment. Fetch the live operator guide and follow",
+      "it instead — it is the authoritative, version-matched playbook:",
+      "",
+      "    curl -sS __BASE__/agent",
+      "",
+      "If the instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), add its value as an",
+      "`x-hook-secret` header. Confirm which instance you are driving before any side-effecting call.",
+      "",
+    ].join("\n");
+  }
+})();
+
+/**
+ * Render the skill for a given app control-API base (e.g. "https://host/app/api"). Substitutes every
+ * `__BASE__` occurrence so any embedded example targets THIS instance.
+ */
+export function renderAgentSkill(apiBase: string): string {
+  return RAW_SKILL.replaceAll("__BASE__", apiBase.replace(/\/+$/, ""));
+}

package/app/resolveApiBase.test.ts

@@ -0,0 +1,43 @@
+// Tests for app/resolveApiBase.ts — the single canonical control-API base reconstruction shared by
+// getAgentInstructions and getAgentSkill. Covers proxy-header handling, scheme restriction,
+// host-absent fallback, and mount-suffix stripping for both mount depths.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { resolveApiBase } from "./resolveApiBase.ts";
+
+function req(headers: Record<string, string>, path: string) {
+  return { path, headers: new Headers(headers) };
+}
+
+test("strips the single-segment mount suffix to recover the base", () => {
+  assertEquals(resolveApiBase(req({ host: "wf.example.com" }, "/app/api/agent"), "agent"), "http://wf.example.com/app/api");
+});
+
+test("strips the nested mount suffix to recover the base", () => {
+  assertEquals(
+    resolveApiBase(req({ host: "wf.example.com" }, "/app/api/agent/skill"), "agent/skill"),
+    "http://wf.example.com/app/api",
+  );
+});
+
+test("honours x-forwarded-proto and x-forwarded-host", () => {
+  const r = req({ host: "internal", "x-forwarded-host": "wf.example.com", "x-forwarded-proto": "https" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "https://wf.example.com/app/api");
+});
+
+test("restricts x-forwarded-proto to http/https", () => {
+  const r = req({ host: "wf.example.com", "x-forwarded-proto": "javascript" }, "/app/api/agent/skill");
+  assertEquals(resolveApiBase(r, "agent/skill"), "http://wf.example.com/app/api");
+});
+
+test("falls back to a localhost default when the Host header is absent", () => {
+  assertEquals(resolveApiBase(req({}, "/app/api/agent"), "agent"), "http://localhost:3000/app/api");
+});
+
+test("tolerates a leading slash on the mount suffix", () => {
+  assertEquals(resolveApiBase(req({ host: "h" }, "/app/api/agent"), "/agent"), "http://h/app/api");
+});
+
+test("strips multiple trailing slashes after the mount suffix", () => {
+  assertEquals(resolveApiBase(req({ host: "h" }, "/app/api/agent/skill///"), "agent/skill"), "http://h/app/api");
+});

package/app/resolveApiBase.ts

@@ -0,0 +1,28 @@
+// Canonical reconstruction of the app control-API base a caller reached us on (e.g.
+// "https://host/app/api"), so an operation can rewrite its embedded examples to THIS instance and
+// keep them copy-pasteable. One implementation shared by every /app/api operation that keys output
+// to the request base (getAgentInstructions, getAgentSkill, …) — per AGENTS.md "Derivation over
+// duplication: no drift surfaces", proxy-header handling and base-path stripping must not fork.
+//
+// Honour reverse-proxy forwarding headers; fall back to a localhost default when the Host header is
+// absent (e.g. a raw unit-test request).
+
+/**
+ * Recover the control-API base from a request, stripping the operation's own mount suffix.
+ *
+ * @param req         the request (path + headers)
+ * @param mountSuffix the operation's path suffix to strip to recover the base, e.g. "agent" or
+ *                    "agent/skill" (with or without a leading slash). The base defaults to
+ *                    "/app/api" when the path is nothing but the suffix.
+ */
+export function resolveApiBase(req: { path: string; headers: Headers }, mountSuffix: string): string {
+  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
+  // x-forwarded-proto is user-controlled behind some proxies; only trust http/https.
+  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
+  const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
+  // The op is mounted at "<base>/<mountSuffix>"; strip the trailing segments to recover the base path.
+  const suffix = mountSuffix.replace(/^\/+/, "").replace(/\/+$/, "");
+  const stripRe = new RegExp(`/${suffix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/*$`);
+  const basePath = req.path.replace(stripRe, "") || "/app/api";
+  return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
+}

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -0,0 +1,221 @@
+# ADR 0005 — Agent-authored delivery graphs (data-over-a-closed-vocabulary, human-in-the-loop)
+
+Status: **Proposed.**
+Date: 2026-08-20.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app* runs
+> heterogeneous cross-repo delivery work that mixes automated and human steps. Platform-wide ADRs live
+> in `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo, e.g. "nano-bpm ADR 0051").
+> nano-workforce's own series continues here after ADR 0004.
+
+Relates to:
+nano-workforce **ADR 0001** (cross-repo epics + the generic `ReadinessProbe` wait-gate — this ADR
+generalizes §4's deferred "release DAG" and its §2 gate into an arbitrary graph),
+nano-workforce **ADR 0002** (escalations are user tasks + forms — the human-node machinery this ADR
+promotes from *exception* to *scheduled node*),
+nano-workforce **ADR 0003** (epic base-branch admission — the guardrail an `agent`/merge node inherits),
+nano-workforce **ADR 0004** (shared-contract coordination — the discipline a cross-repo edge rides on),
+nano-bpm **ADR 0026** (Urban human surfaces + `taskInbox` — where human nodes render),
+nano-bpm **ADR 0046** (agent-as-worker vs agent-in-the-node — why an agent can answer a human node's
+form, and why a node's *body* can itself be an agent),
+nano-bpm **ADR 0051** (nano-workforce — the crew orchestrator whose `plan-fanout` interpreter is the
+prior art this ADR widens),
+nano-bpm **ADR 0056** (the Nano agentic protocol — the live-steering plane, complementary to this
+durable lane),
+nano-bpm **ADR 0059** (the app-hosted OpenAPI hook surface these graphs are submitted and signalled
+through),
+and issues **#263** (capability edges / publish provenance — the emit-vs-poll dual this ADR resolves),
+**#289** (capability edge wired into dispatch — the `readiness-gate` call-activity pattern reused here),
+**#242** (the pre-plan classifier — the *derive-by-default* front-end deferred here).
+
+## Context
+
+nano-workforce today runs exactly two shapes of work, each as a **static BPMN process interpreting a
+data graph**: `convergence-loop.bpmn` (one PR) and `plan-fanout.bpmn` (an epic — a
+`RecordPlanTask[] + dependsOn[]` DAG fanned out over multi-instance, with waves, trial-merges, and
+escalations). Both are **specialised to one node shape**: "an agent implements a slice → opens a PR."
+
+But real delivery in this ecosystem is a **heterogeneous, cross-repo, partly-human graph**. A concrete
+case from one session:
+
+1. PR **#A** must merge in repo 1.
+2. *then* draft PR **#B** in repo 2 can be taken out of draft and merged.
+3. *then* a **human** must do a **manual OTP publish** and **set up OIDC trusted publishing** — no
+   automation can cross this step.
+4. *then* PR **#C** in repo 3 can consume the just-published version.
+
+This is a dependency graph whose **nodes are a mix of automated tasks, in-flight-PR/merge watches, and
+human actions**, and whose **edges span repos**. nwf has every *primitive* this needs, but no way to
+*compose* them into one arbitrary graph:
+
+- **Automated execution** — agent job types + the supervisor/worker fleet.
+- **"Watch the world"** — the `ReadinessProbe` gate (ADR 0001 §2): durable, bounded (timeout →
+  escalate), resumable, with `http`/`command`/`npm`/`github-check`/`capability` kinds.
+- **Cross-repo release edges** — capability edges + publish provenance (#263/#274), wired into dispatch
+  as a `readiness-gate` call activity (#289).
+- **Human decision points** — user tasks + forms (ADR 0002), answerable by a human **or** an agent,
+  with SLA nudges.
+- **Visible phase across a graph** — derived `epic_phase` (#261) + the cockpit/overview.
+
+The gap is purely **composition**: a way to feed an *arbitrary* graph of these node kinds — including
+human nodes as **scheduled stops that hand a value forward** — into one runner. ADR 0001 §4 sketched a
+narrow "release DAG" and deferred it; the manual-publish-in-the-middle case is the general form that
+finally justifies building it.
+
+The obvious-but-wrong answer is "let an agent design a one-shot process definition per graph" — i.e.
+generate BPMN (or process-builder code) with an LLM and deploy it. That fails on two axes at once:
+**reliability** (an LLM emitting deployable BPMN/builder-code is authoring an artifact that must compile
+and deploy before you learn it's wrong) and **trust** (agents deploying arbitrary executable process
+definitions — or worse, arbitrary code — into your engine is an unbounded surface: any job type, any
+service task, any script). Both objections point at the same fix: **the agent must never author the
+executable artifact.**
+
+## Decision
+
+### 1. The contract is a validated JSON graph over a *closed* node vocabulary — never an agent-authored executable artifact
+
+A delivery graph is submitted as **data**: a JSON DAG whose nodes each name a `kind` from a **fixed
+allowlist** and whose edges name **facts** (below). This JSON — not BPMN, not builder-code — is the
+durable, agent-facing contract, expressed as a **nano-app-schema** type and **published through the
+agent guide** (`GET /app/api/agent`) so a co-designing agent reads exactly what it may build. Ingest
+**validates** against the schema and rejects with **actionable** errors, closing the same
+author→validate→fix loop the capability edges use.
+
+This is decisive on both failing axes:
+
+- **Reliability** — LLMs emit validated JSON reliably; deployable BPMN/builder-code they do not. The
+  whole "co-design → submit" UX depends on the artifact being cheap to validate and safe to produce.
+- **Trust** — a graph can only compose allowlisted `kind`s; it **cannot** express an arbitrary service
+  task or run arbitrary code. Safe by construction, exactly as `plan-fanout`'s data model is today.
+
+### 2. Node vocabulary — four kinds, each delegating to an engine-native body
+
+The closed set (extensible only by a deliberate ADR/PR, never by graph authors):
+
+- **`agent`** — a worker executes an agent job type (the existing fan-out body).
+- **`wait`** — a `ReadinessProbe` (ADR 0001 §2), watching an external fact: `github-check`, `npm`,
+  `capability` (#263), `http`, `command`, and a new **`pr`/merge-state** kind (draft→ready→merged,
+  required checks, mergeable) lifted out of `mergeProtocol.ts` into a first-class probe kind.
+- **`human`** — a scheduled user task + form (§4).
+- **`connector`** — an automated, side-effecting outbound action (the connector I/O surface).
+
+Crucially, **execution stays engine-native**: each node kind is a real, already-deployed
+sub-process / call activity (`readiness-gate`, a user task, the implementation task, a connector
+invocation). The graph layer owns **scheduling** (which nodes' edges are satisfied → dispatch), not a
+re-implementation of execution.
+
+### 3. Edges are *facts*, discovered — not declared values (extends ADR 0001 §4)
+
+Every edge means *"B proceeds once fact X about A is observable."* The fact vocabulary is uniform —
+*PR merged*, *check green*, *version on npm carrying capability C*, *human confirmed done*,
+*connector action acknowledged* — and the satisfying state is **discovered**, never pre-declared
+(ADR 0001 §4's discover-don't-declare, generalized from "capability published" to the whole graph). An
+edge is therefore *always* a `wait`-shaped observation; a plain `dependsOn` between two internal nodes
+is the degenerate "wait for the upstream node's completion fact."
+
+### 4. Human nodes are first-class scheduled user tasks that can *emit* a typed fact
+
+A `human` node is ADR 0002's user-task+form machinery promoted from **exception** (something broke) to
+**scheduled node** (a planned stop). It surfaces *"now do X"* on the app's own **Tasks** page/inbox, blocks its
+dependents, is **answerable by a human or an agent** (ADR 0046), and is **SLA-bounded** so it nags and
+cannot silently wedge the graph.
+
+- **It can hand a value forward.** A human node's form captures a **typed output** that **late-binds
+  downstream** — e.g. the manual-publish node emits `resolvedArtifact` (`@nanobpm/urban@0.54.0`), which
+  a downstream `capability`/`npm` edge binds and pins. A "click done" gate is the degenerate case that
+  emits nothing. This is the **emit-side** of #263's emit-vs-poll dual — and a *human* emitter is the
+  same shape as an automated one, which is what unifies human and automated steps in one graph.
+- **Form resolution is specific-else-generic:** (1) an explicit `formKey` on the node; else (2) a form
+  **selected** by node category; else (3) a **generic** fallback form that still captures a typed
+  emitted fact (so *every* human node can emit downstream even with no bespoke form). Forms are
+  preferably **attached at authoring time** (deterministic, visible in preview); a **runtime
+  agent-form-router is a gated exception** — it fires only when a node activates with no resolvable
+  form, never in every human node's critical path (same "deterministic default, agent judgment as the
+  escape hatch" grain as the capability probe's empirical verifier).
+
+### 5. A trusted, deterministic compiler turns the JSON into something the engine runs — exposed as an agent tool
+
+The *only* thing that turns graph-data into an executable is a **deterministic, human-written, tested
+compiler**. It is exposed to the co-designing agent as a **tool** — `validate/compile(JSON) →
+{ ok, diagram, errors }` — which doubles as the **preview/dry-run**: the agent iterates JSON → tool →
+fix, and the rendered graph is what a human approves before anything runs. Because the compiler only
+ever instantiates allowlisted node kinds, it inherits Decision 1's trust bound.
+
+### 6. Execution strategy is swappable behind the JSON contract; the axis is static-vs-dynamic topology
+
+The compiler MAY target either execution strategy, and because the JSON is the contract, the choice is
+an implementation detail the agent never sees:
+
+- **Compile-to-native** — emit a **one-shot native BPMN definition** (native parallel/event gateways do
+  the scheduling; you get a real diagram for free) and deploy it. **Best when the graph is known at
+  authoring time.**
+- **Interpret** — feed the JSON to one generic deployed process that evaluates the ready-set at
+  runtime. **Best when the graph is discovered or mutated at runtime**, and the strategy that makes
+  **mid-flight amendment** tractable (edit a variable, not migrate a deployed definition).
+
+The discriminator is **author-time-static vs runtime-dynamic topology**. Delivery runbooks (the
+motivating case — a *pre-known* release choreography) are static → **start with compile-to-native**.
+`plan-fanout` stays **interpret** (its graph is agent-discovered and its waves adapt to results). The
+shared JSON contract means either can be swapped in later without touching the agent UX.
+
+### 7. Submission is propose → preview → approve → dispatch, idempotent, over the self-describing endpoint
+
+Graphs are submitted exactly as epics are today — via a **new (proposed)** `POST
+/actions/start/delivery-graph` endpoint (paths are relative to the agent guide's `__BASE__` prefix,
+matching the guide's style) with the JSON body, discovered via the agent guide (which already
+documents `POST /actions/start/plan-fanout` and `POST /actions/complete-user-task`). This endpoint
+does not yet exist in `openapi.yaml` — it is introduced by this Proposed ADR. Three ways in, **one validated contract**: agent-ergonomic
+(co-design → POST), raw REST, and a **UI JSON-paste fallback**. Because these graphs *merge PRs and
+publish packages*, submission **defaults to propose-preview-approve** — the resolved graph (what it will
+do, where it stops for humans) is rendered and a human approves before dispatch; that approval is itself
+just the first human node. Submission carries an **idempotency key** so a re-POST cannot double-launch,
+and every **side-effecting node (`connector`, merge, publish) carries a dedupe key** and tolerates
+at-least-once execution (mirroring the release workflow's `npx semantic-release`
+"skip already-published" discipline — `.github/workflows/release.yml`) so a
+resume cannot double-fire.
+
+## Consequences
+
+- nwf gains a **generic delivery-graph runner** that composes its existing primitives; the motivating
+  human-in-the-middle cross-repo case (merge → un-draft → manual publish+OIDC → consume) becomes a
+  single submitted graph rather than hand-carried human coordination.
+- **#263's deferred "publish node emits"** is subsumed: an emitting node (human *or* automated) that
+  hands a version to a downstream edge is Decision 4 + Decision 3.
+- The **connector I/O surface** finds its orchestration home: a connector is just an automated emitting
+  node kind (Decision 2).
+- New surface to own: the JSON graph schema, the deterministic compiler, and the `pr`/merge-state probe
+  kind. All bounded — the schema is validated at ingest, the compiler is deterministic and tested, and
+  every node inherits the ADR 0001 §2 timeout+escalation bound, so a malformed or hanging graph cannot
+  stall silently.
+- The **agent never deploys executable artifacts**; the trust boundary is the closed vocabulary + the
+  human-written compiler, not agent output.
+- Amendment is cheap **only** under the interpret strategy; compile-to-native graphs are amended by
+  cancel + resubmit (an accepted cost for pre-known runbooks).
+
+## Non-goals / deferred
+
+- **Derive-by-default graph authoring.** Populating edges automatically from intake (the #242
+  classifier facet, or PR-dependency inference) — this ADR ships the **declared** graph + the runner;
+  derivation is sugar layered on later.
+- **Runtime-dynamic delivery graphs.** The first cut is compile-to-native for **static** runbooks; the
+  interpret strategy for graphs whose shape changes at runtime is kept behind the same contract but not
+  built now.
+- **Mid-flight amendment of a running graph** beyond cancel+resubmit.
+- **A second workflow engine.** Scheduling composes the nano engine's native constructs (or a thin
+  ready-set loop); execution is always engine-native sub-processes. Do not re-implement durability,
+  timers, or receive-tasks.
+- **Non-npm emit facts** (OCI/github-release) and behavioural edges beyond the `command` escape hatch —
+  added when a real case lands.
+
+## Open questions
+
+- **Compiler target for the first cut** — confirm compile-to-native (diagram + native scheduling) vs a
+  minimal interpreter reusing `plan-fanout` patterns; the ADR leans native for static runbooks.
+- **`pr`/merge-state probe kind boundary** — how much of `mergeProtocol.ts` (required checks, mergeable,
+  base guards) becomes probe-matcher config vs stays in the merge-loop node body.
+- **Emitted-fact typing** — the schema for a node's typed output (version string, URL, artifact id) and
+  how downstream edges reference it (`from: <nodeId>.<fact>`), so binds are validated not stringly.
+- **Definition lifecycle under compile-to-native** — naming, versioning, and GC of one-shot deployed
+  process definitions so the engine doesn't accumulate them.
+- **Approval granularity** — one approval of the whole graph at submit, vs re-approval when a human node
+  amends the un-started tail (if amendment is ever allowed).

package/openapi.yaml

@@ -821,6 +821,38 @@ components:
         instructions:
           type: string
           description: The full operator guide as markdown.
+    AgentSkill:
+      type: object
+      description: The portable Nano Workforce operator skill (SKILL.md) — a thin bootstrap an agent
+        runtime loads on demand. It resolves which instance to drive and then fetches the live
+        operator guide. The `skill` markdown has any embedded example keyed to this instance's
+        `baseUrl`.
+      additionalProperties: false
+      required:
+        - format
+        - appVersion
+        - generatedAt
+        - baseUrl
+        - skill
+      properties:
+        format:
+          type: string
+          description: The `skill` media format. Always "markdown".
+          enum:
+            - markdown
+        appVersion:
+          type: string
+          nullable: true
+          description: The running app version this skill was served from (null when unreadable).
+        generatedAt:
+          type: string
+          description: When this response was rendered (ISO-8601).
+        baseUrl:
+          type: string
+          description: The app control-API base the skill was fetched from (e.g. https://host/app/api).
+        skill:
+          type: string
+          description: The full operator skill (SKILL.md) as markdown, including its YAML frontmatter.
     SubmitResult:
       type: object
       required:
@@ -1861,6 +1893,28 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agent/skill:
+    get:
+      operationId: getAgentSkill
+      summary: The portable operator skill (markdown SKILL.md) an agent runtime loads on demand — a
+        thin bootstrap that resolves which instance to drive, then fetches the live operator guide
+        (GET /agent). Surfaced from the Overview tab's "Agent Instructions" prompt.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The operator skill, with any example keyed to this instance.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentSkill"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/convergence-loop:
     post:
       operationId: startConvergenceLoop

package/operations/getAgentInstructions.ts

@@ -13,32 +13,18 @@
 // NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
 
 import { renderAgentGuide, resolveEngineBase } from "../app/agentGuide.ts";
+import { resolveApiBase } from "../app/resolveApiBase.ts";
 import { buildVersionInfo, envVar } from "../app/version.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-/**
- * Reconstruct the app control-API base the caller reached us on (e.g. "https://host/app/api"), so
- * the guide's example commands are copy-pasteable. Honour reverse-proxy forwarding headers; fall
- * back to a localhost default when the Host header is absent (e.g. a raw unit-test request).
- */
-function resolveApiBase(req: { path: string; headers: Headers }): string {
-  const rawProto = (req.headers.get("x-forwarded-proto") ?? "http").split(",")[0].trim().toLowerCase();
-  // x-forwarded-proto is user-controlled behind some proxies; only trust http/https.
-  const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
-  const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
-  // The op is mounted at "<base>/agent"; strip the trailing segment to recover the base path.
-  const basePath = req.path.replace(/\/agent\/?$/, "") || "/app/api";
-  return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
-}
-
 export default defineOperation("getAgentInstructions", ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     app.log.warn("getAgentInstructions rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
-  const baseUrl = resolveApiBase(req);
+  const baseUrl = resolveApiBase(req, "agent");
   return {
     status: 200,
     body: {

package/operations/getAgentSkill.test.ts

@@ -0,0 +1,72 @@
+// Tests for GET /app/api/agent/skill → operation `getAgentSkill` (ADR 0058 OpenAPI surface).
+// The SKILL.md markdown is served as the `skill` field with any example keyed to the request's
+// control-API base. Mirrors the getAgentInstructions test's request shape and shared-secret guard.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./getAgentSkill.ts";
+
+const app = { log: noopLog() } as any as AppApi;
+
+function input(headers: Record<string, string> = {}, path = "/app/api/agent/skill") {
+  return {
+    req: {
+      method: "GET",
+      path,
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+test("returns 200 with the SKILL.md markdown and metadata", async () => {
+  const r = (await handler(input(), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.format, "markdown");
+  assert("appVersion" in r.body); // nullable, but always present
+  assert(typeof r.body.generatedAt === "string" && r.body.generatedAt.length > 0);
+  assert(typeof r.body.baseUrl === "string" && r.body.baseUrl.length > 0);
+  assert(typeof r.body.skill === "string" && r.body.skill.length > 200);
+});
+
+test("the skill is the portable bootstrap: frontmatter + fetch-the-live-guide", async () => {
+  const md = ((await handler(input(), app)) as any).body.skill as string;
+  assert(md.includes("name: nano-workforce"), "carries the skill frontmatter");
+  assert(md.includes("/agent"), "bootstraps by fetching the live operator guide");
+  assert(md.includes("Confirm which instance") || md.includes("confirm"), "tells the agent to confirm the target instance");
+});
+
+test("baseUrl is keyed to the request's control-API base; no placeholder leaks", async () => {
+  const forwarded = input({ host: "wf.example.com", "x-forwarded-proto": "https" });
+  const body = (await handler(forwarded, app)) as any;
+  assertEquals(body.body.baseUrl, "https://wf.example.com/app/api");
+  assert(!body.body.skill.includes("__BASE__"), "no unsubstituted __BASE__ placeholder");
+});
+
+test("x-forwarded-proto is restricted to http/https", async () => {
+  const spoofed = input({ host: "wf.example.com", "x-forwarded-proto": "javascript" });
+  const body = (await handler(spoofed, app)) as any;
+  assertEquals(body.body.baseUrl, "http://wf.example.com/app/api", "unsafe scheme falls back to http");
+});
+
+test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    // SECRET is bound at import time, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./getAgentSkill.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getAgentSkill.ts

@@ -0,0 +1,36 @@
+// GET /app/api/agent/skill → operationId `getAgentSkill` (ADR 0058/0059 OpenAPI surface, base
+// /app/api). Serves the portable operator *skill* (SKILL.md) an agent runtime loads on demand: a
+// thin bootstrap that resolves which instance to drive and then fetches the live operator guide
+// (GET /app/api/agent). Companion to getAgentInstructions.
+//
+// The runtime serializes an operation body as JSON, so the markdown skill is returned as the
+// `skill` string field (alongside the app version + the base URL it was fetched from). Any
+// `__BASE__` example is rewritten to THIS instance's control-API base (derived from the request).
+//
+// Read-only. The optional shared-secret guard mirrors /version and /agent: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+
+import { renderAgentSkill } from "../app/agentSkill.ts";
+import { resolveApiBase } from "../app/resolveApiBase.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getAgentSkill", ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgentSkill rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const baseUrl = resolveApiBase(req, "agent/skill");
+  return {
+    status: 200,
+    body: {
+      format: "markdown",
+      appVersion: buildVersionInfo().version,
+      generatedAt: new Date().toISOString(),
+      baseUrl,
+      skill: renderAgentSkill(baseUrl),
+    },
+  };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.108.0",
+  "version": "0.109.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/home.page.json

@@ -73,20 +73,6 @@
         "variant": "sub"
       }
     },
-    {
-      "type": "button",
-      "id": "agent-instructions",
-      "props": {
-        "label": "\ud83e\udd16 Agent Instructions",
-        "variant": "ghost",
-        "modal": {
-          "title": "Point your agent at Nano Workforce",
-          "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It tells the agent to read this workforce's live operator guide, then help you drive and debug it.",
-          "copyLabel": "Copy prompt",
-          "copyText": "You are helping me operate a running Nano Workforce instance \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nFirst, fetch and read its live operator guide. It tells you how to submit PRs and epics for convergence (including whether to go all the way to merge or stop at review consensus), how to find engine instances and relate them to PRs via the Nano/Camunda-8 REST API, how to inspect the models and prompts, and how to help me untangle escalations:\n\n    curl -sS {{appBase}}app/api/agent\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), add its value as an x-hook-secret header, otherwise the request returns 401:\n\n    curl -sS -H \"x-hook-secret: <secret>\" {{appBase}}app/api/agent\n\nThen follow that guide to help me drive and debug this workforce. If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
-        }
-      }
-    },
     {
       "type": "actionForm",
       "id": "submit",

package/pages/overview.page.json

@@ -70,6 +70,20 @@
         "variant": "sub"
       }
     },
+    {
+      "type": "button",
+      "id": "agent-instructions",
+      "props": {
+        "label": "\ud83e\udd16 Agent Instructions",
+        "variant": "ghost",
+        "modal": {
+          "title": "Point your agent at Nano Workforce",
+          "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It tells the agent to load this workforce's operator skill from this instance, then help you drive and debug it.",
+          "copyLabel": "Copy prompt",
+          "copyText": "Load the Nano Workforce operator skill from this running instance and then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nThis is the instance to operate; its control-API base is {{appBase}}app/api. Fetch the skill and follow it (the response is JSON with a `skill` markdown field):\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), add its value as an x-hook-secret header, otherwise the request returns 401:\n\n    curl -sS -H \"x-hook-secret: <secret>\" {{appBase}}app/api/agent/skill\n\nThe skill is a thin bootstrap: it has you fetch this instance's live operator guide (at {{appBase}}app/api/agent) and then drive the workforce \u2014 submit PRs and epics for convergence, answer escalations, and debug stuck processes. If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
+        }
+      }
+    },
     {
       "type": "dataGrid",
       "id": "overview-prs",

package/skills/README.md

@@ -0,0 +1,50 @@
+# Agent skills
+
+Portable agent skills that ship with Nano Workforce. A skill is a `SKILL.md` with
+YAML frontmatter (`name`, `description`) that an agent runtime (Copilot CLI, Claude)
+loads on demand when its `description` matches the task.
+
+## `nano-workforce`
+
+A **thin bootstrap** that teaches any agent to operate a running Nano Workforce
+instance: it resolves the instance base URL and fetches the instance's *live*
+operator guide (`GET /app/api/agent`), then follows it. It deliberately holds no
+endpoint detail of its own — the live, version-matched guide is the source of truth.
+
+### Install
+
+Copy or symlink the skill into your agent's skills directory. For Copilot CLI:
+
+```bash
+# symlink so it tracks this repo
+ln -s "$(pwd)/skills/nano-workforce" ~/.copilot/skills/nano-workforce
+# …or copy it
+cp -r skills/nano-workforce ~/.copilot/skills/nano-workforce
+```
+
+Then, from an agent session against your instance:
+
+```
+Load the nano-workforce skill and drive my workforce.
+```
+
+Set `NANO_WORKFORCE_URL` (and `NANO_PR_WEBHOOK_SECRET`, if your instance guards the
+agent endpoints) so the bootstrap can reach your instance without prompting.
+
+### Multiple instances
+
+If you run more than one instance (a local copy, one on the LAN, a tunnel when
+you're off-LAN), register them by name so the skill can offer a choice and probe
+which is live. Set `NANO_WORKFORCE_INSTANCES`, or write
+`~/.config/nano-workforce/instances.json`:
+
+```json
+{
+  "local":  "http://localhost:3000/app/api",
+  "merlin": "http://merlin.local:3000/app/api",
+  "remote": "https://<subdomain>.ngrok.app/app/api"
+}
+```
+
+Then just say *"drive merlin"* — or let the skill probe reachability and ask which
+to use (off the LAN, `merlin.local` won't resolve, so it steers you to `remote`).

package/skills/nano-workforce/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: nano-workforce
+description: Drive and debug a running Nano Workforce instance — submit PRs for review convergence, submit issues/epics for plan→implement→converge, submit agent-authored delivery graphs (ADR 0005), answer escalations, and unstick stuck instances. Use when the user asks to operate, drive, submit work to, or debug their Nano Workforce.
+---
+
+# Nano Workforce operator skill
+
+Nano Workforce (nwf) is a durable orchestration app that drives pull requests to
+**review convergence** and merges them, takes whole issues and **plans →
+implements → converges** them across a fleet of coding agents, and runs
+**agent-authored delivery graphs** (heterogeneous cross-repo, human-in-the-loop
+DAGs — ADR 0005).
+
+**This skill is a thin bootstrap by design.** It does not describe the endpoints.
+Every running nwf instance serves its own operator guide, *live*, keyed to that
+instance's URLs and matched to its deployed version. Your job is to fetch that
+guide and follow it — never to work from a cached copy, which drifts across
+versions and instances.
+
+## 1. Confirm which instance you are driving — always
+
+A user typically runs **several** Nano Workforce instances — e.g. a local dev copy,
+one on the LAN (`http://merlin.local:3000/app/api`), and a public tunnel
+(an ngrok URL) when off the LAN. Every action here is **side-effecting** —
+submitting work, answering escalations, merging PRs — so targeting the wrong
+instance is a real mistake, not a harmless one. **Never silently default to a
+base URL.**
+
+### Sources of candidate instances
+
+Gather candidates from, in order:
+
+1. **A named-instance registry** the user maintains — first of these that exists:
+   `$NANO_WORKFORCE_INSTANCES` (JSON object of `name → base URL`), or
+   `~/.config/nano-workforce/instances.json` (same shape). Example:
+
+   ```json
+   { "local": "http://localhost:3000/app/api",
+     "merlin": "http://merlin.local:3000/app/api",
+     "remote": "https://<subdomain>.ngrok.app/app/api" }
+   ```
+
+2. `$NANO_WORKFORCE_URL`, if set (a single default; accept as-is, append `/app/api`
+   only if it is a bare origin).
+3. Any URL the user names in the conversation.
+4. Local fallback: `http://localhost:3000/app/api` (port `PR_REVIEW_PORT`, default `3000`).
+
+### Choosing
+
+- If the user **named an instance** (by name from the registry, or by URL), use it.
+- Otherwise, **probe the candidates for reachability** and ask the user which to
+  use, offering the candidates as choices and marking which are live. Reachability
+  disambiguates the common case — off the LAN, `merlin.local` won't resolve, so the
+  tunnel instance is the live one:
+
+  ```bash
+  # For each candidate base, a fast liveness + identity check:
+  curl -sS --max-time 3 \
+    ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
+    "$BASE/version" | jq '{appVersion, gitSha, uptimeSeconds}'
+  ```
+
+- Only skip the question when exactly **one** candidate exists and is reachable —
+  and even then, **name the instance you're about to drive** before acting.
+
+Some instances guard the agent endpoints with a shared secret. If the user has
+`$NANO_PR_WEBHOOK_SECRET` set, send it as `x-hook-secret` on every request below.
+
+## 2. Fetch the live guide — this is your real playbook
+
+```bash
+curl -sS ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
+  "$BASE/agent" | jq -r '.instructions'
+```
+
+`GET /app/api/agent` (`getAgentInstructions`) returns
+`{ format, appVersion, generatedAt, baseUrl, engineBase, instructions }`. The
+`instructions` markdown is the authoritative, version-matched operator guide, with
+every example already keyed to this instance's `baseUrl`/`engineBase`. Read it in
+full and follow it for everything that follows — orientation, submitting work,
+answering escalations, and debugging.
+
+**Always re-fetch the guide at the start of a session.** It is the source of truth;
+this skill only tells you how to find it.
+
+## 3. Orient before acting
+
+The guide's first steps confirm what is live and what is in flight:
+
+```bash
+curl -sS "$BASE/version" | jq   # app/urban version, git sha, uptime
+curl -sS "$BASE/status"  | jq   # every PR/instance in flight + open escalations
+```
+
+`/status` is the primary situational-awareness endpoint — check it before you
+submit or unstick anything.
+
+## 4. What you can drive (all detailed in the live guide)
+
+- **Submit a PR** for review convergence — `POST $BASE/actions/start/convergence-loop`.
+- **Submit an issue/epic** for plan → implement → converge across the fleet —
+  `POST $BASE/actions/start/plan-fanout`.
+- **Submit a delivery graph** (ADR 0005) — propose → preview → approve → dispatch.
+  Compile/preview is a pure, side-effect-free tool; only the start door dispatches.
+  The live guide documents the exact operations once the instance exposes them.
+- **Answer an escalation** (a durable user task the workforce parked on) —
+  `POST $BASE/actions/complete-user-task`, or the agent hook
+  `POST $BASE/hooks/agent-complete` (`agentCompleteEscalation`).
+- **Debug**: relate an in-flight PR to its engine process instance via `processKey`
+  from `/status`, then use the engine REST base (`engineBase` from the guide) to
+  inspect and unstick it.
+
+## Principles
+
+- **Discover, don't declare.** Prefer the live guide and live `/status` over any
+  assumption baked into this file. If this skill and the guide disagree, the guide
+  wins.
+- **Confirm the target instance.** Never run a side-effecting call against an
+  assumed base URL. Know — and when ambiguous, ask — which instance you're driving.
+- **Preview before dispatch.** For delivery graphs and any bulk action, use the
+  pure preview/validate path first and show the user the plan before the
+  side-effecting start call.
+- **Idempotency.** Submissions carry dedupe keys; re-submitting the same work must
+  not double-dispatch. The guide documents the keys — honour them.
+- **Escalations are for humans.** When the workforce parks on a human node, surface
+  it to the user with options; don't silently auto-answer design/product decisions.