specweave 1.0.593 → 2.0.3

package/plugins/specweave/skills/team-lead/reference/dynamic-workflows.md

@@ -1,144 +0,0 @@
-# Dynamic Workflows — Team Lead Reference
-
-Loaded on demand by §0.4 when team-lead routes work to the **Dynamic Workflow** engine, or when a
-domain agent enters **Workflow Mode** (`agents/_protocol.md`). Keep this OUT of the main reasoning
-loop unless a Workflow is actually being authored.
-
-## What it is
-
-`Workflow()` runs a **JavaScript script that HOLDS the orchestration plan in code**. A deterministic
-runtime executes it in the background; intermediate results live in **script variables (OFF the
-agent's context)** — only the `return` value lands back in context. It is resumable and background.
-
-| | Agent Teams | Dynamic Workflow |
-|---|---|---|
-| Driver | model, turn-by-turn | the script (deterministic) |
-| Domain awareness | full (specs/ACs/increments/gates) | **none** — domain-blind |
-| Intermediate results | agent context | script variables |
-| Scale | a handful of peers | ≤16 concurrent / ≤1000 total |
-| Best for | feature work, lifecycle, sync | homogeneous fan-out, verify, research |
-
-## Hard limits
-
-- **≤16 concurrent** subagents (fewer on low-CPU machines), **≤1000 total** per run.
-- **One nesting level only** — `workflow()` inside a leaf subagent THROWS.
-- `meta` export is **required** and must be a **pure literal** (no variables/among/calls/spreads).
-- **Forbidden in scripts**: `Date.now()`, `Math.random()`, argless `new Date()` (break resume).
-
-## Primitives
-
-| Primitive | Shape | Barrier? | Use |
-|---|---|---|---|
-| `agent(prompt, opts?)` | `→ Promise<string \| object>` | — | unit of work; with `schema` returns validated JSON (auto-retries on mismatch) |
-| `parallel(thunks)` | `Array<() => Promise> → Promise<(T\|null)[]>` | **YES** (waits for all) | fan-out-then-reduce, judge panels. Failed thunks → `null`; `.filter(Boolean)` |
-| `pipeline(items, ...stages)` | each stage `(prev, orig, idx)` | **NO** (streaming) | **default** multi-stage; item A in stage 3 while B in stage 1 |
-| `phase(title)` | `→ void` | — | name a progress group |
-| `log(msg)` | `→ void` | — | narrator line during the run |
-| `workflow(name, args?)` | inline sub-workflow | — | one level only |
-| `args` | global | — | structured input passed at launch |
-| `budget` | global | — | `budget.total` (null if unset), `budget.spent()`, `budget.remaining()` |
-
-`agent()` opts: `schema`, `label`, `phase`, `model`, `effort` (`low…max`), `isolation: "worktree"`
-(safe parallel file writes), `agentType` (e.g. `'general-purpose'`).
-
-**`parallel` vs `pipeline`**: barrier only when stage N genuinely needs ALL of stage N-1 (dedup,
-early-exit on zero, cross-item comparison). Otherwise `pipeline` — no wasted wall-clock.
-
-## Reusable quality patterns
-
-| Pattern | When |
-|---|---|
-| fan-out → reduce → synthesize | the base skeleton — gather then compile |
-| adversarial verify | N skeptics prompted to REFUTE a finding; keep only if a majority survive |
-| perspective-diverse verify | a distinct lens per verifier (correctness / security / perf / repro) |
-| judge panel / tournament | N attempts from different angles, scored by judges, synthesize the winner |
-| loop-until-dry | keep spawning finders until K rounds surface nothing new (dedupe vs a `seen` set) |
-| multi-modal sweep | parallel agents each searching a different way (by-container, by-content, by-time) |
-| completeness critic | a final agent asking "what's missing?" → next round of work |
-| deep-research pipeline | scope → fan-out searches → fetch → vote per claim → synthesize cited report |
-
-## Per-mode → engine + pattern (team-lead modes)
-
-| Mode | Engine | Pattern |
-|---|---|---|
-| brainstorm | Agent Teams (tmux steering) | perspective-diverse verify — advocate / critic / pragmatist fan out → synthesize |
-| plan | Agent Teams (PM + Architect) | fan-out then reduce — PM specs while Architect explores (~30s overlap) → one plan |
-| implement | Agent Teams outer; inner Workflow ×1 for a ≥25 same-shape domain batch | contract-first phasing; opt-in fan-out inside a batch-shaped domain |
-| review | `sw:code-reviewer` (unchanged) | adversarial verify / completeness critic — N reviewers + self-critique |
-| research | Dynamic Workflow (pipeline) when multi-source; Agent Teams for 2-3 steerable researchers | deep-research pipeline, results off-context |
-| test | Dynamic Workflow when many independent same-shape tests; Agent Teams when layers have setup deps | multi-modal sweep / loop-until-dry |
-
-## Nesting law (boxed)
-
-```
-LEGAL:    team-lead (orchestrator, NOT a Workflow) → Task member → Workflow ×1 → leaves (none)
-LEGAL:    top-level Workflow (team-lead fires it directly for pure batch work)
-ILLEGAL:  Workflow leaf → Workflow()        (throws)
-ILLEGAL:  team-lead rewritten AS a Workflow (members become leaves, lose the right to fan out)
-```
-
-For pure batch-class work prefer ONE top-level Workflow with `parallel()` over the items (one
-budget, one scheduler) instead of N domain agents each launching their own.
-
-## Config schema — `quality.workflows`
-
-Absent or `enabled:false` ⇒ classic Agent-Teams behavior (default-off, non-destructive).
-
-```json
-{
-  "quality": {
-    "workflows": {
-      "enabled": false,
-      "maxConcurrentWorkflows": 1,
-      "perRunTokenBudget": 250000,
-      "maxSubagentsPerWorkflow": 16,
-      "batchShapeThreshold": 25,
-      "agentBorrow": { "enabled": false },
-      "stuckDetection": {
-        "workflowNoProgressMin": 20,
-        "workflowTotalStuckMin": 60
-      },
-      "telemetry": { "logBatchRouteActivations": true }
-    }
-  }
-}
-```
-
-| Key | Default | Purpose |
-|---|---|---|
-| `enabled` | `false` | master switch; false ⇒ never auto-route to Workflow, never honor the borrow |
-| `maxConcurrentWorkflows` | `1` | caps N-fold token stacking when multiple domains qualify |
-| `perRunTokenBudget` | `250000` | ceiling per Workflow run; a projected batch over this must split or go sequential |
-| `maxSubagentsPerWorkflow` | `16` | per-Workflow concurrency (runtime hard max is 16) |
-| `batchShapeThreshold` | `25` | min same-shape independent tasks before a domain may borrow Workflow |
-| `agentBorrow.enabled` | `false` | opt-in inner borrow (Agent-Teams member → Workflow ×1) |
-| `stuckDetection.workflow*` | 20 / 60 min | extended windows while an agent is `state=workflow-delegating` (§8b) |
-| `telemetry.logBatchRouteActivations` | `true` | log batch-route firings so keep-vs-reposition is re-decidable on real data |
-
-## Triggers
-
-`ultracode` keyword or `/effort ultracode` ⇒ xhigh + auto workflow orchestration. Otherwise team-lead
-§0.4 auto-routes by work shape — it **never** requires the user to say "use a workflow".
-
-## When NOT to use a Workflow
-
-Dependency-laden feature work (sequential cross-domain deps defeat fan-out), <25 tasks, or
-single-domain work — use Agent Teams or inline instead. Workflow fan-out buys ~zero speedup on the
-median increment (10-20 tasks, 2-3 domains, frontend ⇐ OpenAPI ⇐ schema).
-
-## Ship order (why default-off matters)
-
-The enhancement is only non-destructive because every new path is gated on `quality.workflows`,
-which is **absent by default**. The intended activation sequence, if/when enabled in a config:
-
-1. Set `quality.workflows.enabled` + budget guards (`perRunTokenBudget`, `maxConcurrentWorkflows`).
-2. Confirm §8b Workflow-Aware Stuck Detection is live (it ships with this skill).
-3. Only then set `agentBorrow.enabled` (the inner borrow) — never before guards 1–2.
-4. Route pure batch-class work (migrations, audits) to a SINGLE top-level Workflow, not N nested.
-5. Keep `telemetry.logBatchRouteActivations` on so the keep-vs-reposition question is re-decidable
-   on real data (analytics is currently empty — this decision rests on architecture, not usage).
-
-> Deferred to a separate telemetry-backed increment (NOT this change): consolidating the `team-*`
-> sibling skills (`team-build` already deprecated, `team-merge` clones the closure phase) and
-> retiring generic modes to Workflow patterns. Correct in direction, but non-additive and unsupported
-> by telemetry today.

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

@@ -1,230 +0,0 @@
----
-description: Merge completed parallel agent work and trigger GitHub sync per increment. Activates for: team merge, merge agents, combine work, team finish.
-version: 1.0.0
----
-
-# Team Merge
-
-**Verify all teammates completed, run quality gates, close increments, and trigger sync.**
-
-## Usage
-
-```bash
-sw:team-merge
-sw:team-merge --dry-run            # Preview merge plan
-sw:team-merge --skip-sync          # Merge without GitHub/JIRA sync
-```
-
-## What This Skill Does
-
-1. **Verify all teammates completed** -- block if any are still running
-2. **Run quality gates per domain** -- `sw:grill` for each increment
-3. **Close increments in dependency order** -- `sw:done` per increment
-4. **Trigger sync** -- pushes to GitHub (`sw-github:sync`) or JIRA (`sw-jira:push`)
-
-## Workflow
-
-### Step 1: Pre-flight Check
-
-Native Agent Teams share the filesystem, so verification is straightforward:
-
-```
-For each teammate's increment:
-  - Check tasks.md is 100% complete
-  - Verify sw:grill quality gate passed
-  - If any teammate still running -> report and ask user to wait
-```
-
-### Step 2: Validate Repository Structure
-
-For multi-repo team sessions, verify all agent work follows the repository directory convention:
-
-```bash
-# Check for repos created outside repositories/ directory
-if [ -d "repositories" ]; then
-  for git_dir in ./*/.git; do
-    repo_name=$(dirname "$git_dir")
-    if [[ "$repo_name" != ./repositories/* && "$repo_name" != "./.git" ]]; then
-      echo "WARNING: Repository $repo_name found outside repositories/ directory"
-      echo "Expected: repositories/{org}/$(basename $repo_name)/"
-    fi
-  done
-fi
-```
-
-If repos are found outside `repositories/`, report as a warning with remediation instructions. The merge proceeds but the report flags the issue for cleanup.
-
-### Step 3: Determine Closure Order
-
-Dependencies flow: shared -> backend -> frontend (or as defined by team topology)
-
-```
-Closure order respects contract chain:
-1. shared/types (no dependencies)
-2. database (depends on shared types)
-3. backend (depends on database + shared)
-4. frontend (depends on backend API + shared types)
-5. devops/qa/security (independent, close last)
-```
-
-### Step 4: Close Each Increment
-
-For each teammate's increment, in dependency order:
-
-**PRE-CLOSURE**: Ensure increment is in "active" or "ready_for_review" status:
-```bash
-STATUS=$(jq -r '.status' .specweave/increments/<id>/metadata.json)
-if [ "$STATUS" = "planned" ] || [ "$STATUS" = "backlog" ]; then
-  # Edit metadata.json to set "status": "active"
-fi
-```
-
-#### Step 4a: Closure Routing — inline vs subagent
-
-Route by increment count to keep small merges fast and large merges context-safe:
-
-- **≤ 5 increments → inline closure (preferred for small batches)**. Run `sw:done <id> --auto` directly in the team-lead context for each increment, one at a time, in dependency order. Skip the Agent spawn. Rationale: fewer than 5 closures fit comfortably in context and avoid ~3–5s of per-agent coordination overhead per increment.
-- **> 5 increments → subagent closure (context-safe for large batches)**. Spawn one `sw-closer` subagent per increment via the `Agent` tool to isolate each closure in a fresh context window:
-
-  ```typescript
-  Agent({
-    subagent_type: "sw:sw-closer",
-    prompt: "Close increment <ID>. Increment path: .specweave/increments/<ID>/",
-    description: "Close increment <ID>"
-  })
-  ```
-
-Either way, wait for each closure to complete before starting the next (dependency order). If a closure fails, log the failure and continue to the next increment.
-
-#### Step 4b: Direct Closure (Non-cloud tools / fallback)
-
-If the `Agent` tool is NOT available, invoke closure directly:
-
-```bash
-sw:done <increment-id> --auto
-```
-
-If `sw:done` fails, fix root cause and retry (max 2 retries). Common fixes: sync ACs, update task counts, write missing reports.
-
-This ensures:
-- Increment is in correct lifecycle status before closure attempt
-- `sw:grill` runs for each increment
-- `tasks.md` and `spec.md` ACs are validated
-- `metadata.json` is updated to `completed`
-- Living docs are generated
-- Failures are retried rather than silently skipped
-
-### Step 5: Trigger Sync
-
-For each closed increment, trigger external sync:
-
-```bash
-# GitHub Issues sync
-sw-github:sync <increment-id>
-
-# JIRA sync (if configured)
-sw-jira:push <increment-id>
-```
-
-### Step 6: Execution Summary
-
-The team's durable artifacts are already in `.specweave/increments/` (spec.md, tasks.md, grill-report.json, metadata.json). No additional archival of ephemeral Claude Code state is needed.
-
-Print a structured execution summary as the final output:
-
-```
-Team Execution Summary
-═══════════════════════
-Team: {team_name}
-
-Agents:
-  {agent-1}: COMPLETED (T-8/8, tests passing)
-  {agent-2}: COMPLETED (T-12/12, tests passing)
-
-Increments closed: {list}
-Sync: {GitHub/JIRA status}
-```
-
-### Step 7: Shutdown Agents and Destroy Team
-
-**7a. Send shutdown_request to all agents** you know from the team session:
-
-```typescript
-SendMessage({ type: "shutdown_request", recipient: "<agent-1>", content: "Merge complete" });
-SendMessage({ type: "shutdown_request", recipient: "<agent-2>", content: "Merge complete" });
-// ... for every agent in this team
-```
-
-Harmless if agents already exited. **NOTE**: `shutdown_request` via `SendMessage` does NOT close the tmux pane — Phase 7c below is the ONLY mechanism that kills orphaned panes. **NEVER skip 7c.**
-
-**7b. Destroy team:**
-
-```typescript
-TeamDelete()
-```
-
-If `TeamDelete` fails (agents still shutting down), wait 3 seconds, retry once.
-
-**7c. Kill orphaned panes (MANDATORY — this is the ONLY thing that closes tmux panes):**
-
-`SendMessage` shutdown does NOT close tmux panes. **ALWAYS run this script.**
-
-```bash
-if command -v tmux >/dev/null 2>&1; then
-  CURRENT_PANE=$(tmux display-message -p '#{pane_id}' 2>/dev/null || echo "")
-  for pane_id in $(tmux list-panes -a -F '#{pane_id}' 2>/dev/null); do
-    [ -n "$CURRENT_PANE" ] && [ "$pane_id" = "$CURRENT_PANE" ] && continue
-    if tmux capture-pane -t "$pane_id" -p -S -50 2>/dev/null | grep -q "Resume this session"; then
-      tmux kill-pane -t "$pane_id" 2>/dev/null
-    fi
-  done
-fi
-```
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--dry-run` | Show merge plan without executing |
-| `--skip-sync` | Merge without triggering GitHub/JIRA sync |
-| `--skip-done` | Skip running sw:done (increments stay active) |
-
-## Example
-
-```
-User: sw:team-merge
-
-Checking teammates...
-  backend (0301-api-endpoints)   -- done, grill passed
-  frontend (0302-ui-components)  -- done, grill passed
-  shared (0300-shared-types)     -- done, grill passed
-
-Closure order: 0300 -> 0301 -> 0302
-
-Running sw:done 0300-shared-types...      done
-Running sw:done 0301-api-endpoints...     done
-Running sw:done 0302-ui-components...     done
-
-Syncing to GitHub...
-  0300 -> issue #45 closed
-  0301 -> issue #46 closed
-  0302 -> issue #47 closed
-
-Team Execution Summary
-═══════════════════════
-Team: feature-checkout
-Agents:
-  shared-agent:   COMPLETED (T-4/4, tests passing)
-  backend-agent:  COMPLETED (T-8/8, tests passing)
-  frontend-agent: COMPLETED (T-6/6, tests passing)
-Increments closed: 0300, 0301, 0302
-Sync: GitHub issues #45, #46, #47 closed
-
-Shutting down agents... done
-TeamDelete: team cleaned up.
-All increments merged and synced.
-```
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#team-merge)