@websitelabs/n8n-nodes-software-teams 0.12.3

package/README.md

@@ -0,0 +1,491 @@
+# @websitelabs/n8n-nodes-software-teams
+
+Software Teams specialist agents as first-class n8n community nodes.  
+Runs one Claude specialist per node, hands off via the canvas, and pauses for human review in Slack — no separate server required.
+
+---
+
+## ⚠️ Self-hosted n8n — required
+
+This package **only works on self-hosted n8n**. It executes the `claude` binary inline on the n8n worker process; n8n Cloud forbids arbitrary binary execution and is not supported.
+
+**Every n8n worker that will run these nodes must have:**
+
+| Requirement | How to satisfy |
+|-------------|----------------|
+| `claude` binary on `PATH` | `npm install -g @anthropic-ai/claude-code` (or your platform's package manager) |
+| `ANTHROPIC_API_KEY` available to the worker | Set in the **Software Teams API** credential (see below) |
+
+If the `claude` binary is missing at execution time the node fails fast with a descriptive error message — it will never silently degrade.
+
+> **Cost / latency note (R-03):** Each Agent node makes one full `claude -p` invocation against the Anthropic API. A multi-agent workflow (Orchestrator → 2 agents → HITL) can make 3–5 API calls, each potentially consuming hundreds of tokens. Model selection per node lets you trade quality for cost — use `claude-haiku-3-5` for cheap triage passes and `claude-sonnet-4-5` (default) or `claude-opus-4` for substantive work. Review Anthropic's pricing before deploying high-volume workflows.
+
+---
+
+## Install
+
+In your self-hosted n8n instance:
+
+1. Go to **Settings → Community Nodes → Install**.
+2. Enter the package name:
+
+   ```
+   @websitelabs/n8n-nodes-software-teams
+   ```
+
+3. Accept the security prompt and wait for the install to complete.
+4. The ten nodes (Agent, Trigger Ingestion, Orchestrator, Slack HITL, HITL, PR Feedback, Output, Workspace, Finaliser, Cleanup) appear in the **Software Teams** section of the node palette.
+5. Create and configure the **Software Teams API** credential (see below).
+
+> **CLI alternative:** on the worker host run `npm install @websitelabs/n8n-nodes-software-teams` in n8n's `~/.n8n/nodes/` custom-nodes directory, then restart n8n.
+
+---
+
+## Software Teams API credential
+
+All secrets are stored in n8n's encrypted credential store and injected into the `claude` child process at runtime. **Secrets are never accepted as node parameters** and are never written to node output, execution logs, or the data envelope (R-02).
+
+Create the credential at **Credentials → New → Software Teams API**.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Anthropic API Key** | **yes** | Your Anthropic API key from [console.anthropic.com](https://console.anthropic.com/). Injected as `ANTHROPIC_API_KEY` into the `claude` subprocess. |
+| **ClickUp API Token** | for ClickUp triggers | ClickUp personal API token. Used by the Trigger Ingestion node to fetch ticket context. |
+| **Datadog API Key** | for Datadog triggers | Datadog API key for issue context fetch. |
+| **Datadog Application Key** | for Datadog triggers | Required alongside the API key for certain Datadog endpoints. |
+| **GitHub Token** | for GitHub output + PR feedback + cleanup | Personal access token (or fine-grained PAT) with `repo` + PR write scopes. Used by the Output node to open PRs, the PR Feedback node to fetch review comments, and the Cleanup node to verify merge status. |
+| **Slack Bot Token** | for Slack HITL | Bot OAuth token (`xoxb-…`). Required by the Slack HITL and legacy Slack HITL nodes when the `slack` channel is selected. |
+| **Discord Bot Token** | for Discord HITL | Discord bot token (`Bot …`). Required by the HITL node when the `discord` channel is selected (the priority channel for the first live test). Injected as `DISCORD_BOT_TOKEN` — never on the envelope or in logs (AC8). |
+| **SMTP URL** | for Email HITL | SMTP connection string (e.g. `smtps://user:pass@smtp.example.com`). Required by the HITL node when the `email` channel is selected. Injected as `SMTP_URL` — never on the envelope or in logs (AC8). |
+
+After saving, n8n will test the Anthropic key by listing available models. A ✓ confirms connectivity.
+
+---
+
+## Nodes
+
+All ten nodes share the **Software Teams API** credential and pass a single typed `NodeEnvelope` object between them. See [`CONTRACT.md`](./CONTRACT.md) for the full inter-node data contract.
+
+### Software Teams Trigger Ingestion
+
+**Purpose:** Fetches context from a ClickUp ticket, Datadog issue, or a **plain free-text prompt** (AC6) and emits an initial `NodeEnvelope` — the starting point of every Software Teams workflow.
+
+Place this node **after** a native n8n ClickUp, Datadog, Schedule, or Form trigger; it enriches the upstream data with PII-scrubbed ticket/issue context, or passes through the raw prompt directly when using the `prompt` source.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| (none) | Input | — | No input port; receives data from n8n trigger node before it |
+| Main | Output | `NodeEnvelope` | Fresh envelope with `correlationId`, `status: 'ok'`, and `input.context` populated from the fetched ticket/issue or the raw prompt |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Source | `ClickUp`, `Datadog`, or **`Prompt`** (AC6 — a plain free-text prompt as a first-class trigger source) |
+| Prompt | Free-text task prompt (used when `Source = Prompt`; supports n8n expressions for Form Trigger integration) |
+| ClickUp Task Ref | Task URL or bare task ID (supports n8n expressions) |
+| Datadog Issue URL | Issue URL with `issueId` param (supports n8n expressions) |
+| Workflow Prompt | Initial task instruction for the first downstream Agent node |
+| First Agent ID | Specialist hint for the first downstream node (e.g. `software-teams-researcher`) |
+
+If the credential keys are missing or the ref is unreachable the node proceeds with `context: null` and logs a diagnostic — it does not block the workflow.
+
+**Prompt source (AC6):** when `Source = Prompt`, the node uses the literal `Prompt` parameter value as the task context — no external API call is made. This makes a plain free-text prompt a first-class trigger alongside ClickUp and Datadog, enabling simple Form Trigger → Trigger Ingestion → Orchestrator flows without any external ticket system.
+
+---
+
+### Software Teams Agent
+
+**Purpose:** Runs exactly **one** Software Teams specialist for **one** turn via the `claude` CLI (Task tool disabled — AC2). Wire multiple Agent nodes A → B for multi-agent handoff; each hop passes the upstream result in `input.context`.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` or any | When the input carries a valid envelope (has `correlationId` + `agentId` + `status`), the node folds the upstream `result`/`artifacts` into `input.context`. First-node mode uses the optional Context parameter. |
+| Main | Output | `NodeEnvelope` | Completed envelope; `status` is `ok`, `error`, or `needs-input`. Route on `{{ $json.status === 'needs-input' }}` to feed the Slack HITL node. |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Specialist | Which Software Teams specialist to invoke (dropdown — 33 options including Frontend Engineer, Researcher, Programmer, UX Designer, QA Tester, …) |
+| Prompt | Task instruction for this turn. Supports n8n expressions. |
+| Context (JSON) | Optional JSON context for the first node in a chain; ignored when an upstream envelope is present |
+| Model | `claude-sonnet-4-5` (default), `claude-opus-4`, or `claude-haiku-3-5` |
+
+---
+
+### Software Teams Orchestrator
+
+**Purpose:** Accepts an epic/sprint goal, runs a planning turn as `software-teams-planner`, and **emits one `NodeEnvelope` per wave-task** in dependency order — the canvas delegation mechanism. Downstream Agent nodes consume these items (static wiring or a Switch keyed on `agentId`). Also bubbles `needs-input` and `error` envelopes from sub-agents up to the HITL / error branch.
+
+Supports three operations selectable via the `Operation` parameter:
+
+| Operation | Description |
+|-----------|-------------|
+| `plan` (default) | Runs a planning turn and fans out one envelope per wave-task |
+| `review` | **Readiness gate (AC1):** runs a single-turn, Task-disabled `software-teams-quality` pass that validates the generated plan for one-shot readiness (clear briefs, deps, agent pins, acceptance criteria) BEFORE fan-out. On pass it allows fan-out; on fail it surfaces blocking gaps and either auto-refines within ≤2 attempts or parks via the HITL path. `planEpic()` behaviour is unchanged. |
+| `summary` | Reads aggregated run-state and emits a human-facing run summary (per-agent results + overall outcome) |
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` or plain | Upstream trigger/ingestion output. A `needs-input` or `error` envelope is passed through unchanged for HITL/error routing. |
+| Main | Output | `NodeEnvelope[]` | `plan`/`review` operations: one item per wave-task with `agentId` preset. `summary` operation: one summary envelope. |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Operation | `plan`, `review`, or `summary` |
+| Epic / Sprint Goal | The epic, user story, or project goal to plan. Supports n8n expressions. |
+| Correlation ID | Leave blank to auto-generate. Reuse an upstream envelope's `correlationId` to continue an existing run. |
+| Planner Model | Claude model for the planning turn |
+
+Run state (waves, task statuses) is persisted to workflow global static data keyed by `correlationId` so partial failures are resumable (R-05).
+
+---
+
+### Software Teams Slack HITL
+
+**Purpose:** Implements the ask → wait → resume state machine (AC7). When an upstream Agent emits `status: 'needs-input'`, this node posts the question to Slack (Block Kit, threaded, with the `correlationId`), pauses the n8n workflow execution, and on resume re-runs the same agent with the human's Slack reply folded into context.
+
+Three execution modes determined at runtime:
+
+| Mode | Trigger | What happens |
+|------|---------|--------------|
+| **Ask** | Input envelope `status === 'needs-input'` | Posts question to Slack, persists state, calls `putExecutionToWait()` |
+| **Resume** | Input has `hitlAnswer` + `correlationId` fields (from Slack interactivity webhook) | Loads stored state, re-invokes `runAgentTurn`, emits continued envelope |
+| **Pass-through** | `status === 'ok'` or `'error'` | Passes envelope unchanged |
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` | See modes above |
+| Main | Output | `NodeEnvelope` | Ask mode: waiting envelope with `hitl` state block. Resume mode: continued agent envelope. |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Slack Channel | Channel ID (`C0123456`) or name (`#ai-questions`) |
+| Wait Timeout (Hours) | Max hours to wait before execution times out (default 24) |
+
+> **Self-hosted requirement:** set `WEBHOOK_URL=https://n8n.yourdomain.com` on the n8n worker so the signed resume URL is reachable from Slack's servers. `localhost:5678` will not work.
+
+---
+
+### Software Teams Output
+
+**Purpose:** Terminal node — reads the final `NodeEnvelope` and opens a **GitHub PR** (default) or **GitHub issue** with the agents' result. Appends the created URL to `artifacts` and passes the envelope downstream for further processing or logging.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` | Must carry a valid envelope (`correlationId` required). PR mode also needs a `branch` artifact from an upstream agent; falls back to an issue if absent. |
+| Main | Output | `NodeEnvelope` | Envelope with the PR/issue URL appended to `artifacts`. `status: 'error'` if GitHub rejects the PR. |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Output Mode | `Pull Request (Default)` or `Issue` |
+| Target Repository | `owner/repo` format, e.g. `acme/myapp` |
+| Base Branch | Branch the PR merges into (default `main`; PR mode only) |
+| Title | PR/issue title. Defaults to `[Software Teams] {correlationId}` when blank. |
+| Issue Labels | Comma-separated labels (Issue mode only; must already exist in the repo) |
+
+---
+
+### Software Teams Workspace
+
+**Purpose:** Establishes the run's repository checkout and seeds the repo descriptor onto the
+`NodeEnvelope`, enabling downstream Agent nodes to make real file changes inside isolated git
+worktrees. Required as the first node in any repo-scoped execution flow.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` or plain | Inbound trigger or manual start |
+| Main | Output | `NodeEnvelope` | Envelope with additive `repo` descriptor (`cloneUrl`, `ownerRepo`, `baseBranch`) |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Target Repository | `owner/repo` (e.g. `acme/myapp`) or a full HTTPS/SSH clone URL |
+| Base Branch | Branch all agent worktrees fork from (default `main`) |
+| Correlation ID | Leave blank to auto-generate; reuse an upstream `correlationId` to continue an existing run |
+
+> **Self-hosted requirement:** the n8n worker must have `git` and `claude` on `PATH`. The node
+> fails fast with a clear error if either binary is absent. `gh` is required by the Finaliser node.
+
+---
+
+### Software Teams Finaliser
+
+**Purpose:** Terminal merge node for repo-scoped runs. Reads all agents' changes from workflow
+run-state, applies them onto a feature branch with a **bounded conflict-resolver** (≤3 claude
+turns), commits, pushes, and emits a `branch` artifact so the Output node opens a PR.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` | Must carry a `correlationId` matching agents that have written to run-state |
+| Main | Output | `NodeEnvelope` | Envelope with `branch` artifact + run summary in `result.text` |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Correlation ID | The run's `correlationId` (expression: `{{ $json.correlationId }}`). Used to read aggregated agent results from run-state. |
+
+**Conflict-resolution guarantee:** if git's automatic merge cannot resolve a conflict, a claude
+resolver turn runs — up to a maximum of 3 turns. Within the bound the merged branch is always
+marker-free before push. If the bound is exceeded the node fails cleanly with a structured error
+that includes the conflicting file list; no branch is pushed and no infinite loop runs.
+
+> **Self-hosted requirement:** the n8n worker must have `gh` on `PATH`. The node fails fast with
+> a clear error if the binary is absent.
+
+---
+
+### Software Teams PR Feedback
+
+**Purpose:** Ingests GitHub PR review comments back into a running Software Teams workflow. Triggered by a GitHub webhook (PR review or review-comment event), it fetches and categorises the review comments (reusing the `feedback --json` CLI), extracts the originating run's `correlationId` from the machine-parseable tag the Output node stamped into the PR body, and emits a continue-run `NodeEnvelope` that re-enters the Orchestrator's existing continue path (AC2).
+
+The tag in the PR body has the form:
+
+```
+<!-- software-teams:correlationId=run-2026-06-03-CU-4821 -->
+```
+
+The `parseCorrelationTag` helper (shared contract, `packages/cli/src/contract/envelope.ts`) extracts the id; the `buildCorrelationTag` helper (Output node, T11) writes it. The round-trip invariant `parseCorrelationTag(buildCorrelationTag(id)) === id` is asserted in the contract tests.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | any | Receives the GitHub webhook payload |
+| Main | Output | `NodeEnvelope` | Continue-run envelope carrying the original `correlationId` and categorised `feedback.comments` |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| PR Number | The PR number to fetch review comments from (supports n8n expressions from the webhook payload) |
+| Repository | `owner/repo` of the target repository |
+
+**Secrets:** uses the `GitHub Token` from the `SoftwareTeamsApi` credential. The token is injected into the child process env — never in node output, the envelope, or logs (AC8).
+
+---
+
+### Software Teams HITL
+
+**Purpose:** Multi-channel, multi-round Human-in-the-Loop node. Extends the original `SlackHitl` with support for four channels — **Slack, Email, n8n-notification, and Discord** (Discord is the priority channel for the first live test). Unlike the legacy Slack HITL node, it re-parks state on each resume for genuine multi-round back-and-forth: on resume it re-saves conversation state so a follow-up question can be posed without starting a new run.
+
+Three execution modes determined at runtime:
+
+| Mode | Trigger | What happens |
+|------|---------|--------------|
+| **Ask** | Input envelope `status === 'needs-input'` | Posts the question on the selected channel, persists multi-round conversation state keyed by `correlationId`, calls `putExecutionToWait()` |
+| **Resume** | Inbound resume payload with `hitlAnswer` + `correlationId` | Loads state, re-invokes `runAgentTurn`, re-parks for the next round or emits a terminal envelope |
+| **Pass-through** | `status === 'ok'` or `'error'` | Passes envelope unchanged |
+
+**Channel selection order:**
+
+1. The `Channel` node parameter (explicit override wins).
+2. The optional `hitlChannel` field on the inbound envelope (hint from an upstream node).
+3. Default: `discord`.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | `NodeEnvelope` | See modes above |
+| Main | Output | `NodeEnvelope` | Ask mode: waiting envelope. Resume mode: continued agent envelope, possibly re-parked. |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Channel | `auto` (use envelope hint or default), `slack`, `discord`, `email`, or `notify` |
+| Wait Timeout (Hours) | Max hours to wait before execution times out (default 24) |
+
+**Secrets:** the channel tokens (`discordBotToken`, `smtpUrl`, `slackBotToken`) are read from the `SoftwareTeamsApi` credential and injected into the channel delivery function. They are never written to the envelope, node output, or logs (AC8).
+
+> **Self-hosted requirement:** set `WEBHOOK_URL=https://n8n.yourdomain.com` on the n8n worker so the signed resume URL is reachable from your HITL channel's servers.
+
+---
+
+### Software Teams Cleanup
+
+**Purpose:** Post-merge teardown node. Triggered by a GitHub PR MERGE webhook, it idempotently and safely removes all state associated with a completed run — run-state, conversation state, git worktrees, repo clones, agent memories, and `.software-teams/` plan artefacts — so the workflow is immediately reusable for a new task (AC5).
+
+**Idempotency:** running the Cleanup node twice for the same `correlationId` is a no-op the second time. Each cleanup operation checks whether the resource exists before attempting removal.
+
+| Port | Direction | Type | Notes |
+|------|-----------|------|-------|
+| Main | Input | any | Receives the GitHub merge webhook payload |
+| Main | Output | `NodeEnvelope` | Cleanup result envelope with `status: 'ok'` + summary in `result.text` |
+
+**What gets cleaned up (in order):**
+
+| Resource | How |
+|----------|-----|
+| Run-state (`runs[correlationId]`) | `deleteRunState` — removes the entry from workflow global static data |
+| Conversation state | `deleteState` — removes the HITL resume record keyed by `correlationId` |
+| Git worktrees | Calls the `worktree-remove` CLI primitive for each registered worktree |
+| Repo clones | Removes the run-scoped clone directory |
+| Agent memories | Clears per-agent memory files scoped to the `correlationId` |
+| Plan / task artefacts | Removes `.software-teams/` plan and task files for the run |
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| Correlation ID | The run's `correlationId` — parse from the merged PR body using `parseCorrelationTag` |
+| Repository | `owner/repo` used to verify the PR was actually merged before cleanup |
+
+**Secrets:** uses the `GitHub Token` from the `SoftwareTeamsApi` credential for merge verification. Never written to node output or the envelope (AC8).
+
+---
+
+## Inter-node data contract
+
+Every node emits and accepts a single `NodeEnvelope` JSON object:
+
+```ts
+interface NodeEnvelope {
+  correlationId: string;               // Stable run ID — carried unchanged node-to-node
+  agentId: string;                     // e.g. "software-teams-frontend"
+  status: 'ok' | 'error' | 'needs-input';
+  input: { prompt: string; context: unknown };
+  result: { text: string };
+  artifacts: Array<{ type: string; url?: string }>;
+}
+```
+
+See **[`CONTRACT.md`](./CONTRACT.md)** for the full normative contract, field invariants, producer/consumer rules, the upstream-context merge strategy, and worked examples of A→B handoff.
+
+---
+
+## Node-load gate and CJS resolution boundary
+
+The package builds and loads under **Node.js** (not just Bun). A post-build verification gate runs every CI build to guard against regressions to the original mixed-format failure.
+
+### What the gate does
+
+After `bun run build`, the gate runs every entry in `n8n.nodes[]` and `n8n.credentials[]` through `node -e "require('<path>')"` with **CWD = `packages/n8n/`**. Any load failure (`ERR_MODULE_NOT_FOUND`, "require is not defined in ES module scope", "exports is not defined", or any throw) causes the gate to exit non-zero.
+
+Run it locally with the root alias:
+
+```sh
+bun run verify:node-load
+```
+
+Or from the package directory:
+
+```sh
+bun run --cwd packages/n8n verify:node-load
+```
+
+The gate builds first (`n8n-node build`), then loads all 11 entries (10 nodes + 1 credential) under Node.
+
+### Why it runs as a distinct CI step (not inside the Bun test run)
+
+The original failure mode — emitting mixed ESM `import`/`export` + CJS `require(...)` — passed the Bun test suite green because Bun tolerates mixed module format. Node does not. Running the gate as a **separate CI step after build** ensures that a future regression to the mixed-format problem is caught by the gate before it ships, regardless of the Bun test result.
+
+### CJS resolution boundary
+
+The gate runs with **CWD = `packages/n8n/`**. From that directory the workspace `node_modules` resolves:
+
+| Dependency | Resolved to | Why |
+|---|---|---|
+| `n8n-workflow` | `dist/cjs/index.js` | No `"type"` in `n8n-workflow/package.json`; `main` is CJS under Node. This is the same path a real n8n host uses. |
+| `@websitelabs/software-teams` | `lib/n8n-api.js` | The shared lib is `"type": "module"`. A CJS caller selects its `exports.require` condition → `./lib/n8n-api.js` (a real CJS build, `"use strict";`). The `import` condition (`./src/n8n-api.ts`) is TS source Node cannot execute — it is never selected. |
+
+This is the **host-equivalent CJS resolution boundary** — it reproduces locally how a real n8n host resolves both peers from its own Node-resolved `node_modules`. It is explicitly **not** the Bun-install ESM path (`.bun/.../dist/esm/index.js`) that was the original failure.
+
+The n8n package itself has no `"type"` key in its `package.json`, so every emitted `.js` in `dist/` is treated as CommonJS by Node. The `tsconfig.json` uses `module: "commonjs"` + `moduleResolution: "node"` — consistent with the official `@n8n/node-cli` template.
+
+---
+
+## Specialist routing and Orchestrator summary
+
+### Routing by `agentId` — no per-node Switch required
+
+The Orchestrator fans out one `NodeEnvelope` per planned task, each with `agentId` preset to the planned specialist (e.g. `"software-teams-backend"`). Each Agent node is configured with a `specialist` value (e.g. `software-teams-backend`).
+
+**When the inbound envelope's `agentId` matches the node's configured `specialist`**, the Agent node processes the item and emits its result. **When `agentId` does not match**, the item is not processed and is not emitted as work output from that node.
+
+This means you can **wire every specialist Agent node directly off the single Orchestrator output** — no Switch node in front of each agent. Each Agent node picks up only the fan-out items addressed to its configured specialist. Items with no `agentId` (e.g. first-node or single-agent flows) are processed exactly as before — the routing is a no-op when no `agentId` is present (behaviour-preserving).
+
+Example wiring on the canvas:
+
+```
+Orchestrator ──▶ Agent: Backend   (specialist = software-teams-backend)
+             └──▶ Agent: Frontend  (specialist = software-teams-frontend)
+             └──▶ Agent: Programmer (specialist = software-teams-programmer)
+```
+
+All three agent nodes are wired off the same Orchestrator output. Each node processes only the envelopes addressed to it.
+
+### Orchestrator `summary` mode
+
+The Orchestrator node supports an `operation: summary` mode. When triggered after agents have completed their turns, the Orchestrator reads the aggregated run-state (via `enumerateAgentResults`) and emits a single human-facing summary envelope — describing what each specialist did and the overall outcome — surfaced from the node that started the run.
+
+**This mode is purely additive and the DAG contract is intact:**
+
+- The Orchestrator's existing `plan-and-fan-out` behaviour is unchanged.
+- No return edge is introduced from an Agent node back to the Orchestrator — the forward-only aggregation topology of ADR-002 Decision F is preserved.
+- The Finaliser still owns the forward run summary (per-agent result + conflict resolution outcome) and the PR. The Orchestrator `summary` is an additional, Orchestrator-centric view of the run — not a replacement.
+
+---
+
+## Architecture
+
+See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design decision record covering node style, the single-turn execution model, and canvas handoff.
+
+---
+
+## Risks
+
+| ID | Risk | Mitigation |
+|----|------|------------|
+| R-01 | Inline `claude` execution requires the binary on the self-hosted worker | Documented above; node fails fast with a clear error on missing binary |
+| R-02 | API keys must not leak into node output/logs | All tokens stored in the `SoftwareTeamsApi` credential; never in node parameters or the envelope |
+| R-03 | One `claude` call per agent node → cost & latency per workflow run | Single-turn execution caps per-node work; per-node model selection; see cost/latency note above |
+
+---
+
+## Example workflows
+
+### IT-support ticket → GitHub PR (five-node canvas)
+
+See [`docs/example-workflow.md`](./docs/example-workflow.md) for a step-by-step walkthrough of
+the ClickUp label → Orchestrator → two agents → Slack HITL → GitHub PR end-to-end loop.
+
+Import the ready-made workflow from [`examples/it-support-pr.workflow.json`](./examples/it-support-pr.workflow.json).
+
+### Repo execution: repo + prompt → real code changes → PR (full canvas)
+
+For workflows that make real file changes against a target repository, use the two new nodes
+(**Workspace** and **Finaliser**) alongside the existing five.
+
+See [`docs/repo-execution.md`](./docs/repo-execution.md) for the full flow documentation,
+including:
+- Node-by-node parameter reference (Workspace and Finaliser)
+- The on-envelope `repo` descriptor handoff and `RepoContext` lifecycle
+- Queue-mode safety: portable `changeRef` patches (base64 `git format-patch`) with no shared volume required
+- Bounded conflict-resolution guarantee (≤3 resolver turns, or structured failure with conflicting file list)
+- Self-hosted prerequisites (`claude` + `git` + `gh` on the worker, fail-fast)
+- Cost and latency breakdown (clone + per-agent turns + optional resolver turns)
+
+Import the ready-made workflow from [`examples/repo-pr.workflow.json`](./examples/repo-pr.workflow.json).
+
+---
+
+## No-Install Alternative (Manual / CLI Recipe)
+
+If you **cannot install the community-node package** (n8n Cloud, locked worker node directory,
+or simply want to try Software Teams before committing to an install), use the
+**manual CLI recipe** instead:
+
+- **Docs:** [`n8n/MANUAL-RECIPE.md`](./MANUAL-RECIPE.md) — Execute Command command strings,
+  secrets-via-env, security notes, self-hosted constraint.
+- **Example workflow:** [`n8n/examples/manual-recipe.workflow.json`](./examples/manual-recipe.workflow.json)
+  — importable built-in-node-only workflow (Execute Command + Code + IF), no package required.
+
+The same underlying engine powers both modes; the manual recipe is a thin CLI surface
+(`software-teams ingest | agent-turn | orchestrator-turn | output`) over it.

package/dist/agents/software-teams-architect.md

@@ -0,0 +1,155 @@
+---
+name: software-teams-architect
+description: Designs system architecture with focus on maintainability and scalability
+model: opus
+tools:
+  - Bash
+  - Edit
+  - Glob
+  - Grep
+  - LSP
+  - Read
+  - Write
+---
+
+<!-- canonical frontmatter — converted to .claude/agents/{name}.md by software-teams sync-agents -->
+
+
+# Software Teams Architect Agent
+
+> **Decision (plan 03-02):** technical-director pattern lives here — no separate software-teams-tech-director agent. See plan 03-02 merge register for rationale.
+
+You design and review system architecture with focus on maintainability, scalability, and long-term technical decisions.
+
+## Key Actions
+
+### Analyse Existing Architecture
+
+<!-- T11: removed broken Architect:Analyse reference -->
+
+1. Map current system structure
+2. Identify architectural patterns in use
+3. Document component relationships
+4. Surface technical debt
+5. Note scaling limitations
+
+### Design New Architecture
+
+<!-- T11: removed broken Architect:Design reference -->
+
+1. Define system boundaries
+2. Design component interfaces
+3. Specify data flow patterns
+4. Document integration points
+5. Plan for failure modes
+
+### Review Architecture Decisions
+
+<!-- T11: removed broken Architect:Review reference -->
+
+1. Evaluate against requirements
+2. Assess trade-offs
+3. Check for anti-patterns
+4. Verify scalability assumptions
+5. Confirm maintainability
+
+### Technical Risk Register
+
+Maintain an ongoing register of technical risks that could threaten delivery, performance, or maintainability. Each entry captures the risk, its likelihood, impact, owner, and mitigation. Review the register at every milestone gate and surface unresolved high-severity items to the user.
+
+```yaml
+risk_id: R-{number}
+title: {short description}
+category: performance | security | scalability | integration | dependency | debt
+likelihood: low | medium | high
+impact: low | medium | high
+owner: {agent or role}
+mitigation: {action being taken}
+status: open | mitigating | accepted | resolved
+```
+
+---
+
+## Decision Framework
+
+| Dimension | Question |
+|-----------|----------|
+| Fit | Does it solve the actual problem? |
+| Simplicity | Is this the simplest solution? |
+| Scalability | Will it scale with growth? |
+| Maintainability | Can future devs understand it? |
+| Reversibility | How costly to change later? |
+| Risk | What could go wrong? |
+
+---
+
+## Strategic Decision Workflow
+
+When asked to make a high-level decision or resolve a cross-system conflict, work the steps in order. You present analysis and a recommendation; the user makes the final call.
+
+1. **Understand** — Gather full context. Read relevant ADRs, constraints, and prior decisions. Ask clarifying questions until you can name what is truly at stake (often deeper than the surface question).
+2. **Frame** — State the core question in one sentence. Explain why it matters and what it affects downstream. List the evaluation criteria (budget, quality, scope, reversibility, risk).
+3. **Options** — Present 2-3 viable strategic options. For each: what it means concretely, which goals it serves vs. sacrifices, downstream consequences (technical, schedule, scope), risks and mitigations.
+4. **Recommendation** — State your preferred option and why, using theory, precedent, and project context. Acknowledge the trade-offs you accept. Make it explicit that the final call is the user's.
+5. **Support** — Once the user decides, document the decision (ADR or risk register entry), cascade it to affected agents, and define validation criteria ("we'll know this was right if...").
+
+---
+
+## Outputs
+
+| Output | Purpose |
+|--------|---------|
+| Architecture Decision Record (ADR) | Document decisions and rationale |
+| Component Diagram | Visualise system structure |
+| Data Flow Diagram | Show information movement |
+| Integration Map | Document external dependencies |
+| Technical Debt Register | Track architectural issues |
+
+### ADR Template
+
+```markdown
+# ADR-{number}: {title}
+
+## Status
+Proposed | Accepted | Deprecated | Superseded
+
+## Context
+{What is the issue motivating this decision?}
+
+## Decision
+{What is the change being proposed?}
+
+## Consequences
+### Positive
+- {benefit}
+
+### Negative
+- {drawback}
+
+### Neutral
+- {implication}
+
+## Alternatives Considered
+| Option | Pros | Cons | Rejected Because |
+|--------|------|------|------------------|
+```
+
+---
+
+## Structured Returns
+
+```yaml
+status: complete | needs_decision | blocked
+analysis_type: new_design | review | assessment
+components_identified: {n}
+decisions_needed: [...]
+recommendations:
+  - action: {what to do}
+    rationale: {why}
+    priority: high | medium | low
+risks_identified: [...]
+outputs:
+  - {path to ADR or diagram}
+```
+
+**Scope**: Analyse architecture, design components, document ADRs, recommend patterns, run strategic decision workflows, maintain the technical risk register. Will NOT sprint-plan (delegate to software-teams-producer), write code (delegate to software-teams-programmer), make design decisions (delegate to software-teams-ux-designer / software-teams-product-lead).