specweave 1.0.590 → 1.0.592

package/plugins/specweave/lib/integrations/jira/jira-spec-sync.js

@@ -9,8 +9,6 @@ import { toDescription } from "./content-format-adapter.js";
 import { getEpicLinkFieldForProject } from "./jira-field-discovery.js";
 import { searchAllIssues } from "./jira-paginated-search.js";
 import axios from "axios";
-import { CircuitBreakerRegistry } from "../../../../../src/core/sync/circuit-breaker-registry.js";
-import { SyncRetryQueue } from "../../../../../src/core/sync/sync-retry-queue.js";
 import { SyncError } from "../../../../../src/core/errors/sync-error.js";
 import { LockManager } from "../../../../../src/utils/lock-manager.js";
 function buildStoryDescription(us) {
@@ -55,6 +53,9 @@ class JiraSpecSync {
       }
     });
   }
+  /**
+   * Execute fn under file lock (if lockManager configured).
+   */
   async withLock(fn) {
     if (!this.lockManager) return fn();
     const acquired = await this.lockManager.acquire();
@@ -67,6 +68,9 @@ class JiraSpecSync {
       await this.lockManager.release();
     }
   }
+  /**
+   * Check circuit breaker before making API calls.
+   */
   checkCircuitBreaker() {
     if (!this.circuitBreakerRegistry) return;
     const breaker = this.circuitBreakerRegistry.get("jira");
@@ -74,10 +78,16 @@ class JiraSpecSync {
       throw new SyncError("jira", 0, "", "Circuit breaker open for jira");
     }
   }
+  /**
+   * Record success on circuit breaker.
+   */
   recordApiSuccess() {
     if (!this.circuitBreakerRegistry) return;
     this.circuitBreakerRegistry.get("jira").recordSuccess();
   }
+  /**
+   * Record failure on circuit breaker and optionally enqueue retry.
+   */
   async recordApiFailure(error, operation) {
     const httpStatus = error?.response?.status ?? 0;
     if (this.circuitBreakerRegistry) {
@@ -111,56 +121,56 @@ class JiraSpecSync {
     console.log(`
 \u{1F504} Syncing spec ${specId} to Jira Epic...`);
     return this.withLock(async () => {
-    this.checkCircuitBreaker();
-    try {
-      const spec = await this.specManager.loadSpec(specId);
-      if (!spec) {
+      this.checkCircuitBreaker();
+      try {
+        const spec = await this.specManager.loadSpec(specId);
+        if (!spec) {
+          return {
+            success: false,
+            specId,
+            provider: "jira",
+            error: `Spec ${specId} not found`
+          };
+        }
+        const existingLink = spec.metadata.externalLinks?.jira;
+        let epic;
+        if (existingLink?.epicKey) {
+          console.log(`   Found existing Jira Epic ${existingLink.epicKey}`);
+          epic = await this.updateJiraEpic(existingLink.epicKey, spec);
+        } else {
+          console.log("   Creating new Jira Epic...");
+          epic = await this.createJiraEpic(spec);
+          await this.specManager.linkToExternal(specId, "jira", {
+            id: epic.key,
+            url: epic.url,
+            projectKey: this.config.projectKey,
+            domain: this.config.domain
+          });
+        }
+        const changes = await this.syncUserStories(epic.key, spec);
+        this.recordApiSuccess();
+        console.log("\u2705 Sync complete!");
+        return {
+          success: true,
+          specId,
+          provider: "jira",
+          externalId: epic.key,
+          url: epic.url,
+          changes
+        };
+      } catch (error) {
+        await this.recordApiFailure(error, "syncSpecToJira");
+        const axiosData = error?.response?.data;
+        const detail = axiosData ? JSON.stringify(axiosData) : "";
+        console.error("\u274C Error syncing to Jira:", error?.message || error, detail ? `
+   Response: ${detail}` : "");
         return {
           success: false,
           specId,
           provider: "jira",
-          error: `Spec ${specId} not found`
+          error: error instanceof Error ? error.message : "Unknown error"
         };
       }
-      const existingLink = spec.metadata.externalLinks?.jira;
-      let epic;
-      if (existingLink?.epicKey) {
-        console.log(`   Found existing Jira Epic ${existingLink.epicKey}`);
-        epic = await this.updateJiraEpic(existingLink.epicKey, spec);
-      } else {
-        console.log("   Creating new Jira Epic...");
-        epic = await this.createJiraEpic(spec);
-        await this.specManager.linkToExternal(specId, "jira", {
-          id: epic.key,
-          url: epic.url,
-          projectKey: this.config.projectKey,
-          domain: this.config.domain
-        });
-      }
-      const changes = await this.syncUserStories(epic.key, spec);
-      this.recordApiSuccess();
-      console.log("\u2705 Sync complete!");
-      return {
-        success: true,
-        specId,
-        provider: "jira",
-        externalId: epic.key,
-        url: epic.url,
-        changes
-      };
-    } catch (error) {
-      await this.recordApiFailure(error, "syncSpecToJira");
-      const axiosData = error?.response?.data;
-      const detail = axiosData ? JSON.stringify(axiosData) : "";
-      console.error("\u274C Error syncing to Jira:", error?.message || error, detail ? `
-   Response: ${detail}` : "");
-      return {
-        success: false,
-        specId,
-        provider: "jira",
-        error: error instanceof Error ? error.message : "Unknown error"
-      };
-    }
     });
   }
   /**
@@ -170,60 +180,60 @@ class JiraSpecSync {
     console.log(`
 \u{1F504} Syncing FROM Jira to spec ${specId}...`);
     return this.withLock(async () => {
-    this.checkCircuitBreaker();
-    try {
-      const spec = await this.specManager.loadSpec(specId);
-      if (!spec) {
+      this.checkCircuitBreaker();
+      try {
+        const spec = await this.specManager.loadSpec(specId);
+        if (!spec) {
+          return {
+            success: false,
+            specId,
+            provider: "jira",
+            error: `Spec ${specId} not found`
+          };
+        }
+        const jiraLink = spec.metadata.externalLinks?.jira;
+        if (!jiraLink?.epicKey) {
+          return {
+            success: false,
+            specId,
+            provider: "jira",
+            error: "Spec not linked to Jira Epic"
+          };
+        }
+        const epic = await this.fetchJiraEpic(jiraLink.epicKey);
+        const conflicts = await this.detectConflicts(spec, epic);
+        if (conflicts.length === 0) {
+          console.log("\u2705 No conflicts - spec and Jira in sync");
+          return {
+            success: true,
+            specId,
+            provider: "jira",
+            externalId: epic.key,
+            url: epic.url
+          };
+        }
+        console.log(`\u26A0\uFE0F  Detected ${conflicts.length} conflict(s)`);
+        await this.writeConflictReport(specId, conflicts);
+        await this.resolveConflicts(spec, conflicts);
+        console.log("\u2705 Sync FROM Jira complete!");
         return {
-          success: false,
+          success: true,
           specId,
           provider: "jira",
-          error: `Spec ${specId} not found`
+          externalId: epic.key,
+          url: epic.url,
+          conflicts
         };
-      }
-      const jiraLink = spec.metadata.externalLinks?.jira;
-      if (!jiraLink?.epicKey) {
+      } catch (error) {
+        await this.recordApiFailure(error, "syncFromJira");
+        console.error("\u274C Error syncing FROM Jira:", error);
         return {
           success: false,
           specId,
           provider: "jira",
-          error: "Spec not linked to Jira Epic"
+          error: error instanceof Error ? error.message : "Unknown error"
         };
       }
-      const epic = await this.fetchJiraEpic(jiraLink.epicKey);
-      const conflicts = await this.detectConflicts(spec, epic);
-      if (conflicts.length === 0) {
-        console.log("\u2705 No conflicts - spec and Jira in sync");
-        return {
-          success: true,
-          specId,
-          provider: "jira",
-          externalId: epic.key,
-          url: epic.url
-        };
-      }
-      console.log(`\u26A0\uFE0F  Detected ${conflicts.length} conflict(s)`);
-      await this.writeConflictReport(specId, conflicts);
-      await this.resolveConflicts(spec, conflicts);
-      console.log("\u2705 Sync FROM Jira complete!");
-      return {
-        success: true,
-        specId,
-        provider: "jira",
-        externalId: epic.key,
-        url: epic.url,
-        conflicts
-      };
-    } catch (error) {
-      await this.recordApiFailure(error, "syncFromJira");
-      console.error("\u274C Error syncing FROM Jira:", error);
-      return {
-        success: false,
-        specId,
-        provider: "jira",
-        error: error instanceof Error ? error.message : "Unknown error"
-      };
-    }
     });
   }
   /**

package/plugins/specweave/lib/integrations/jira/jira-status-sync.js

@@ -1,8 +1,6 @@
 import axios from "axios";
 import { detectDeploymentType, getApiBaseUrl } from "./jira-deployment-detector.js";
 import { toCommentBody } from "./content-format-adapter.js";
-import { CircuitBreakerRegistry } from "../../../../../src/core/sync/circuit-breaker-registry.js";
-import { SyncRetryQueue } from "../../../../../src/core/sync/sync-retry-queue.js";
 import { SyncError } from "../../../../../src/core/errors/sync-error.js";
 import { LockManager } from "../../../../../src/utils/lock-manager.js";
 class JiraStatusSync {
@@ -30,6 +28,9 @@ class JiraStatusSync {
       }
     });
   }
+  /**
+   * Execute fn under file lock (if lockManager configured).
+   */
   async withLock(fn) {
     if (!this.lockManager) return fn();
     const acquired = await this.lockManager.acquire();
@@ -42,6 +43,10 @@ class JiraStatusSync {
       await this.lockManager.release();
     }
   }
+  /**
+   * Check circuit breaker before making API calls.
+   * Throws if breaker is open.
+   */
   checkCircuitBreaker() {
     if (!this.circuitBreakerRegistry) return;
     const breaker = this.circuitBreakerRegistry.get("jira");
@@ -49,10 +54,16 @@ class JiraStatusSync {
       throw new SyncError("jira", 0, "", "Circuit breaker open for jira");
     }
   }
+  /**
+   * Record success on circuit breaker.
+   */
   recordSuccess() {
     if (!this.circuitBreakerRegistry) return;
     this.circuitBreakerRegistry.get("jira").recordSuccess();
   }
+  /**
+   * Handle API error: record failure on circuit breaker, enqueue retry, throw SyncError.
+   */
   async handleApiError(error, operation) {
     const httpStatus = error?.response?.status ?? 0;
     const responseBody = JSON.stringify(error?.response?.data ?? "");
@@ -72,6 +83,9 @@ class JiraStatusSync {
     }
     throw new SyncError("jira", httpStatus, responseBody, detail);
   }
+  /**
+   * Initialize: detect deployment type and update client baseURL
+   */
   async init() {
     const deployment = await detectDeploymentType(this.domain, {
       email: this.client.defaults.auth?.username || "",
@@ -79,6 +93,12 @@ class JiraStatusSync {
     });
     this.client.defaults.baseURL = deployment.baseUrl;
   }
+  /**
+   * Get current status from JIRA issue
+   *
+   * @param issueKey - JIRA issue key (e.g., PROJ-123)
+   * @returns Current issue status
+   */
   async getStatus(issueKey) {
     return this.withLock(async () => {
       this.checkCircuitBreaker();
@@ -93,6 +113,19 @@ class JiraStatusSync {
       }
     });
   }
+  /**
+   * Update JIRA issue status via transitions
+   *
+   * JIRA requires using transitions to change status.
+   * Cannot directly set status field.
+   *
+   * Handles missing transitions gracefully by logging a warning
+   * instead of throwing an error.
+   *
+   * @param issueKey - JIRA issue key (e.g., PROJ-123)
+   * @param status - Desired status
+   * @returns true if transition succeeded, false if not available
+   */
   async updateStatus(issueKey, status) {
     return this.withLock(async () => {
       this.checkCircuitBreaker();
@@ -120,6 +153,13 @@ class JiraStatusSync {
       }
     });
   }
+  /**
+   * Post comment about status change to JIRA issue
+   *
+   * @param issueKey - JIRA issue key (e.g., PROJ-123)
+   * @param oldStatus - Previous SpecWeave status
+   * @param newStatus - New SpecWeave status
+   */
   async postStatusComment(issueKey, oldStatus, newStatus) {
     return this.withLock(async () => {
       this.checkCircuitBreaker();
@@ -142,6 +182,18 @@ _Synced from SpecWeave_`;
       }
     });
   }
+  /**
+   * Post AC progress comment with proper ADF formatting and dedup.
+   *
+   * Builds native ADF with:
+   * - Bold header showing completion percentage
+   * - Bullet list with checkmark/cross emojis per AC
+   * - Fingerprint marker to prevent duplicate comments
+   *
+   * @param issueKey - JIRA issue key (e.g., PROJ-123)
+   * @param acStates - Array of AC states with id, description, completed
+   * @returns true if comment was posted, false if skipped (duplicate)
+   */
   async postProgressComment(issueKey, acStates) {
     return this.withLock(async () => {
       this.checkCircuitBreaker();

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -1,6 +1,6 @@
 ---
-description: Phase-agnostic orchestrator for parallel multi-agent work — brainstorm, plan, implement, review, research, or test. Auto-detects mode from intent. Use for implementation (3+ domains or 15+ tasks), brainstorming (multiple perspectives), parallel planning (PM + Architect), code review (delegates to sw:code-reviewer), research (multiple topics), or testing (parallel test layers). Also use when user says "team setup", "parallel agents", "team lead", "agent teams", "brainstorm with agents", "plan in parallel", "review code", "research this".
-version: 1.0.0
+description: Phase-agnostic orchestrator for parallel multi-agent work — brainstorm, plan, implement, review, research, or test. Auto-detects mode from intent. Use for implementation (3+ domains or 15+ tasks), brainstorming (multiple perspectives), parallel planning (PM + Architect), code review (delegates to sw:code-reviewer), research (multiple topics), or testing (parallel test layers). Also use when user says "team setup", "parallel agents", "team lead", "agent teams", "brainstorm with agents", "plan in parallel", "review code", "research this". Also auto-selects a dynamic Workflow for batch-class work (migrations, repo-wide audits, deep research, high-stakes verification) without being asked.
+version: 1.1.0
 ---
 
 # Team Lead
@@ -12,6 +12,7 @@ version: 1.0.0
 - **Read**: Load the master `spec.md` once for fan-out decisions and read agent prompt templates under `plugins/specweave/skills/team-lead/agents/`. During the active phase, prefer `PLAN_READY` summaries from agents over re-reading full plan files.
 - **Bash**: Inspect team state (`specweave doctor`, `ls ~/.claude/teams/`, grep metadata.json) and run CLI-only operations — never to implement code.
 - **TeamCreate / Task / SendMessage**: Core orchestration primitives for spawning agents, routing messages, and handling heartbeats.
+- **Workflow**: Dynamic-workflow engine for batch-class fan-out (migrations, repo-wide audits, high-stakes verification, deep research) — auto-selected per §0.4, never requires the user to ask. See `reference/dynamic-workflows.md`.
 
 ## MANDATORY: Orchestrator Identity (NEVER SKIP)
 
@@ -22,9 +23,10 @@ version: 1.0.0
 - **NEVER** say "I'll do this directly" — that defeats the purpose of team-lead
 - Even if you just finished a previous team-lead session in this conversation, you MUST create a **new** team and spawn **new** agents
 - **Fan-out threshold**: Spawn agents when **domains ≥ 3** OR **tasks ≥ 15** OR `--parallel` flag is set. For 1-domain or <15-task work, execute directly without spawning.
-- Your only tools are: `TeamCreate`, `Task`, `SendMessage`, `Read` (for agent templates; during active phase use PLAN_READY summaries instead of reading full plan files), `Bash` (only for team state inspection), and `Skill()` (only during closure phase for grill/done)
+- Your only tools are: `TeamCreate`, `Task`, `SendMessage`, `Workflow` (for batch-class fan-out per §0.4), `Read` (for agent templates; during active phase use PLAN_READY summaries instead of reading full plan files), `Bash` (only for team state inspection), and `Skill()` (only during closure phase for grill/done)
+- **`Workflow` IS orchestration, not implementation** — per §0.4 you MAY launch a `Workflow()` for batch-class work (migrations, repo-wide audits, high-stakes verification, deep research). Delegating to a Workflow does NOT violate this rule; writing the code yourself does.
 
-**The test**: If you're about to call `Edit()` or write code, STOP — you're violating this rule.
+**The test**: If you're about to call `Edit()` or write code yourself, STOP — you're violating this rule. (Launching a `Workflow()` that spawns agents to do the work is fine.)
 
 ---
 
@@ -128,6 +130,8 @@ sw:team-lead --preset api-only --max-agents 4 "Add payments API"
 
 **team_name**: `brainstorm-{topic-slug}`
 
+**Engine** (per §0.4): Agent Teams — brainstorm needs interactive steering + the idea tree, not a deterministic batch. Pattern: perspective-diverse verify (advocate / critic / pragmatist fan out → synthesize).
+
 Skip increment pre-flight entirely. Brainstorm doesn't need a spec — it explores possibilities.
 
 1. Create team: `TeamCreate({ team_name: "brainstorm-{slug}", description: "Brainstorm: {topic}" })`
@@ -249,6 +253,8 @@ Pass through any arguments the user provided (--pr N, --changes, --cross-repo, p
 
 **team_name**: `research-{topic-slug}`
 
+**Engine** (per §0.4): prefer a **Dynamic Workflow** deep-research pipeline (fan-out searches → fetch → adversarially verify → synthesize a cited report, results held off-context) for multi-source / multi-subtopic research; use Agent Teams only for 2-3 steerable researchers. Falls back to Agent Teams when `quality.workflows.enabled` is off.
+
 Skip increment pre-flight. Research is exploratory — no spec needed.
 
 1. Create team: `TeamCreate({ team_name: "research-{slug}", description: "Research: {topic}" })`
@@ -285,6 +291,8 @@ Skip increment pre-flight. Research is exploratory — no spec needed.
 
 **team_name**: `test-{increment-id}`
 
+**Engine** (per §0.4): route **many independent same-shape tests** to a **Dynamic Workflow** (generate → run → fix-loop until green); keep Agent Teams when test layers have setup dependencies. Falls back to Agent Teams when `quality.workflows.enabled` is off.
+
 Testing mode requires an increment (it needs to know WHAT to test).
 
 1. **Verify increment exists** (same as implementation mode — see below)
@@ -321,6 +329,48 @@ Testing mode requires an increment (it needs to know WHAT to test).
 
 ---
 
+## 0.4. Orchestration Engine Selection (AUTO-DETECT — never wait for a flag)
+
+**Run AFTER §0 Mode Detection, BEFORE §0.5 Increment Pre-Flight.** Pick the engine from the *shape* of the work, not from the user's words. The user must NEVER have to say "use a workflow" — you infer it.
+
+Three engines:
+
+| Engine | What it is | Owns |
+|--------|-----------|------|
+| **Dynamic Workflow** | `Workflow()` — deterministic JS scheduler, ≤16 concurrent / 1000 total subagents, results in script vars (off context), resumable, background | Large homogeneous fan-out: migrations, repo-wide audits, many-similar-tests, adversarial/judge verification |
+| **Agent Teams** (default) | `TeamCreate` + `Task` + `SendMessage` + tmux — model-driven, domain-aware, SpecWeave-lifecycle owner | Feature work: 3+ domains or 15+ tasks with cross-domain contracts + closure + sync |
+| **Inline** | This orchestrator, no spawn | <15 tasks, single domain, sequential |
+
+### Decision table (first match wins)
+
+| Signal in the work | Engine | Why |
+|--------------------|--------|-----|
+| ≥~25 **same-shape** tasks, no cross-task deps (rename X→Y across N files, add header to N modules, port N tests) | **Dynamic Workflow** (top-level, bypass team-lead) | Pure fan-out under ONE budget + ONE scheduler — no glue needed |
+| Codebase **migration** / repo-wide **audit** / lint-sweep / dependency-bump across many files | **Dynamic Workflow** (top-level) | Domain-blind batch; team-lead's lifecycle is dead weight here |
+| High-stakes **verification** needing N independent checks (adversarial-verify, judge-panel, completeness-critic) | **Dynamic Workflow** (top-level) | Built-in reusable patterns; deterministic reduce |
+| **Deep research** spanning many sources/subtopics | **Dynamic Workflow** (pipeline) | fan-out → fetch → verify → synthesize, results off-context |
+| 3+ domains OR 15+ tasks **with cross-domain contracts** (frontend ⇐ OpenAPI ⇐ schema), needs increment activation + closure + GitHub/Jira/ADO sync | **Agent Teams** | Phased dependencies defeat fan-out; only team-lead owns the SpecWeave contract |
+| A single Agent-Teams **domain agent** discovers its OWN task list is a ≥~25 same-shape batch | Agent Teams **+ inner Workflow ×1** (see `agents/_protocol.md` Workflow Mode) | Legal one-level borrow; team-lead stays outer coordinator |
+| <15 tasks, 1 domain, sequential | **Inline** | Spawning overhead unjustified |
+
+### AUTO-DETECT signals (no flag required)
+
+- **→ Dynamic Workflow**: `migrate`, `migration`, `port`, `rename across`, `repo-wide`, `codebase-wide`, `audit`, `sweep`, `bulk`, `every file`, `all <N> …`, `double-check`, `verify independently`, `judge`, `tournament`, `deep research`, `survey the literature`, `ultracode` keyword / `/effort ultracode`.
+- **→ Agent Teams**: `build <feature>`, `team`, `parallel agents`, `multi-domain`, increment with 3+ domains, contracts (Prisma/OpenAPI/shared types) in scope, anything needing `sw:done`/sync.
+- **→ Inline**: small single-domain change, hotfix, one-file edit.
+
+### Guards (CHECK before routing to any Workflow)
+
+1. **Default-off** — if `quality.workflows.enabled` is absent or `false`, do NOT auto-fire a Workflow and do NOT honor the inner borrow; fall back to Agent Teams / inline (classic behavior, byte-for-byte). This is what keeps the enhancement non-destructive.
+2. **Budget gate** — read `quality.workflows.perRunTokenBudget` + `maxConcurrentWorkflows` from config. If a route would exceed either, DOWNGRADE to inline/sequential and tell the user.
+3. **Nesting law** — `Workflow()` allows ONE nesting level and THROWS inside a leaf subagent. Legal chain: `team-lead (orchestrator, not a Workflow) → Task member → Workflow ×1 → leaves (cannot nest)`. team-lead may fire a top-level Workflow OR delegate the borrow to a member — never both for the same work.
+4. **One top-level Workflow beats N nested ones** — for pure batch-class work, prefer a SINGLE top-level `Workflow` with `parallel()` over the items (one budget, one scheduler) instead of N domain agents each launching their own.
+5. **Inject SpecWeave context** — Workflow is domain-blind (zero knowledge of specs/ACs/increments/gates). Every Workflow-routed agent prompt MUST carry the increment path, file-ownership patterns, AC list, and contract artifacts, or it produces unanchored code.
+
+See `reference/dynamic-workflows.md` for primitives, quality patterns, and the full `quality.workflows` config schema.
+
+---
+
 ## 0.5. Increment Pre-Flight (IMPLEMENTATION and TESTING modes only)
 
 **This section applies only to IMPLEMENTATION mode (default) and TESTING mode.**
@@ -402,6 +452,7 @@ fi
 | Spawn agent | `Task` | `team_name`, `name`, `subagent_type`, `prompt`, `mode: "bypassPermissions"` |
 | Send message | `SendMessage` | `type`, `recipient`, `content`, `summary` |
 | Shutdown agent | `SendMessage` | `type: "shutdown_request"`, `recipient` |
+| Run batch fan-out | `Workflow` | `script` (a `meta` literal + `agent()`/`parallel()`/`pipeline()`) — for batch-class work per §0.4; see `reference/dynamic-workflows.md` |
 
 ---
 
@@ -993,6 +1044,18 @@ When an agent is declared stuck:
 - Heartbeat STATUS messages let team-lead detect problems early instead of after long silences
 - If an agent's task count exceeds 40 despite the cap, split before spawning
 
+### Workflow-Aware Stuck Detection (agent borrowing a Workflow)
+
+A domain agent that borrows a Workflow (see `agents/_protocol.md` Workflow Mode) goes **silent for minutes** while the background run executes — the normal 5min/20min windows would false-kill a healthy agent. Additive handling:
+
+1. **Delegation state** — when an agent's STATUS contains `DELEGATING … workflow_id=`, mark it `state=workflow-delegating` and record the `workflow_id`. SUSPEND the normal 5/20 windows.
+2. **Extended windows** — while delegating, apply `quality.workflows.stuckDetection.{workflowNoProgressMin, workflowTotalStuckMin}` (defaults 20min / 60min) instead. Silence here is expected, not stuck.
+3. **Clear on completion** — a `STATUS: WORKFLOW_DONE` (or a `BLOCKING_ISSUE` citing the same `workflow_id`) restores `state=active` and the normal 5/20 windows from the next heartbeat.
+4. **Probe before kill** — if `workflowTotalStuckMin` elapses with no `WORKFLOW_DONE`, send ONE `STATUS_CHECK` asking the agent to report the Workflow's own progress (it is resumable/background). Declare stuck only after a second unanswered probe; prefer leaving the increment open over killing mid-batch.
+5. **Loop-detection unchanged** — the "same task number 3+ heartbeats = stuck loop" rule still applies to NON-delegating agents; a delegating agent emits no task-number heartbeats and is exempt by construction.
+
+**Default-off**: with no `quality.workflows` config, no agent ever enters `state=workflow-delegating`, so behavior is identical to today.
+
 ---
 
 ## 9. Workflow Summary

package/plugins/specweave/skills/team-lead/agents/_protocol.md

@@ -86,3 +86,47 @@ Approve only if you have no unsaved state. Approving terminates your process.
 - Do NOT wait for team-lead response to PLAN_READY — proceed immediately
 - ALL repository operations MUST use `repositories/{ORG}/` directory structure
 - Create `.specweave/increments/` in YOUR assigned repo, NOT in the umbrella project root
+- **Workflow Mode** (below) is OPT-IN and default-off — only borrow a `Workflow()` for a ≥~25 same-shape independent-task batch, exactly once, and only if `quality.workflows.agentBorrow.enabled` is true
+
+## Workflow Mode (OPT-IN — large homogeneous batch only)
+
+You normally implement tasks sequentially. **IF AND ONLY IF** your assigned task list is a **large homogeneous batch** — **≥~25 tasks of the same shape with no cross-task dependencies** (e.g. apply the same rename/migration/edit to N files, port N similar tests, audit N modules) — you MAY call `Workflow()` **EXACTLY ONCE** to fan them out.
+
+**Gate (ALL must hold, else implement sequentially):**
+- `quality.workflows.enabled === true` AND `quality.workflows.agentBorrow.enabled === true` in `.specweave/config.json` (both default **off** — if absent/false, do NOT use Workflow).
+- ≥~25 same-shape, independent tasks (`quality.workflows.batchShapeThreshold`, default 25).
+- Projected concurrency ≤ `quality.workflows.maxSubagentsPerWorkflow` (≤16) and projected tokens ≤ `quality.workflows.perRunTokenBudget`.
+
+**Nesting law (HARD):** You were spawned by team-lead via the `Task` tool, so you ARE allowed ONE `Workflow()` call. The subagents your Workflow spawns are **leaves** — they CANNOT call `Workflow()` (it throws). One borrow, one level down. Never nest.
+
+**Heartbeat-before-Workflow (MANDATORY — prevents false-kill):** A background Workflow makes you silent for minutes. BEFORE the call, emit a STATUS that declares the delegation so team-lead extends its stuck-detection window (see SKILL.md §8b Workflow-Aware Stuck Detection):
+
+```
+SendMessage({ type: "message", recipient: "team-lead",
+  content: "STATUS: T-{N}/{total} — DELEGATING {batchCount} tasks to background Workflow (workflow_id={id}). Expect silence until WORKFLOW_DONE.",
+  summary: "[Domain] entering Workflow Mode — {batchCount} tasks" })
+```
+On completion emit `STATUS: WORKFLOW_DONE — {done}/{batchCount} ok, {failed} failed. Resuming T-{M}.` then resume normal heartbeats.
+
+**Template** (one call; results stay in script vars, NOT your context). Inject SpecWeave context (spec/AC refs, file paths) into every agent prompt — Workflow is domain-blind:
+
+```js
+export const meta = {
+  name: "batch-fanout",
+  description: "Fan out a homogeneous batch of same-shape tasks",
+  phases: [{ title: "batch" }],
+};
+const items = [/* the >=25 same-shape task descriptors: { target, acRef, file } */];
+const results = await parallel(
+  items.map((it) => () => agent(
+    `Apply <the same transform> to ${it.target}. Spec: ${it.acRef}. Write ONLY ${it.file}.`,
+    { label: it.target, phase: "batch", isolation: "worktree" }
+  ))
+);
+log(`batch complete: ${results.filter(Boolean).length}/${items.length}`);
+return results;
+```
+
+**Budget guard:** Keep projected tokens under `quality.workflows.perRunTokenBudget`. If your batch would exceed it, split into fewer items or fall back to sequential — do NOT raise the cap yourself.
+
+**If the gate fails for any reason → implement the tasks sequentially as usual.** Workflow Mode is an optimization, never a requirement.

package/plugins/specweave/skills/team-lead/agents/backend.md

@@ -35,3 +35,5 @@ DOMAIN RULES:
   - Every new API endpoint needs request/response validation
   - Error handling follows project conventions
   - All services must have unit tests
+  - Workflow Mode: for >=~25 independent same-shape endpoints/DTOs,
+    you MAY borrow a Workflow() ONCE (see _protocol.md; gated on quality.workflows.agentBorrow.enabled)

package/plugins/specweave/skills/team-lead/agents/database.md

@@ -30,3 +30,5 @@ DOMAIN RULES:
   - Always create migrations (never modify schema without a migration)
   - Seed data must be idempotent
   - Schema changes should be backward-compatible when possible
+  - Workflow Mode: for a bulk migration touching >=~25 independent tables/files,
+    you MAY borrow a Workflow() ONCE (see _protocol.md; gated on quality.workflows.agentBorrow.enabled)

package/plugins/specweave/skills/team-lead/agents/testing.md

@@ -33,3 +33,5 @@ DOMAIN RULES:
   - Tests must cover all ACs from spec.md
   - Follow existing test patterns and utilities
   - E2E tests include a11y checks when applicable
+  - Workflow Mode: if you must generate/port >=~25 independent same-shape test files,
+    you MAY borrow a Workflow() ONCE (see _protocol.md; gated on quality.workflows.agentBorrow.enabled)