@nanobpm/nano-workforce 0.108.0 → 0.110.0

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.110.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.