specweave 1.0.423 → 1.0.425

package/plugins/specweave/commands/save.md

@@ -1,6 +1,6 @@
 ---
 disable-model-invocation: true
-description: Smart auto-commit with remote sync (handles pull/rebase/stash, auto-generates messages, supports multi-repo).
+description: Smart auto-commit with remote sync (handles pull/rebase/stash, auto-generates messages, supports multi-repo). Ensures clean working tree — every file committed or gitignored.
 argument-hint: "[message]"
 ---
 
@@ -19,8 +19,17 @@ argument-hint: "[message]"
 /sw:save --dry-run # Preview without executing
 ```
 
+## Core Guarantee
+
+**After `/sw:save` completes, `git status` must be clean in every repo** — zero untracked files, zero unstaged changes. Achieved by:
+- Committing all important files (source, config, docs, specs, lock files)
+- Gitignoring all unimportant files (build output, deps, OS junk, secrets)
+- Applying this per-repo for both umbrella and all nested repositories
+
 ## Execution Order (MANDATORY)
 
+Steps 2–7 run **per repo** — first all nested repos (innermost first), then the umbrella/parent project last.
+
 ### 1. Scan for Nested Repos (ALWAYS FIRST)
 
 ```bash
@@ -52,9 +61,88 @@ Determine state: `up-to-date` | `ahead` | `behind` | `diverged` | `no-tracking`.
 - **no-tracking**: `git push -u origin HEAD`
 - **up-to-date/ahead**: No sync needed, proceed
 
-### 4. Auto-Commit Message (if none provided)
+### 4. Smart Staging (MANDATORY — replaces `git add -A`)
+
+**Goal**: Every file in the repo is accounted for — either staged for commit or covered by `.gitignore`. Nothing left dangling.
+
+#### Phase 1: Stage all tracked modifications
+
+```bash
+git add -u   # Modified/deleted files already under source control — always safe
+```
+
+This handles: edited source files, updated configs, deleted files, submodule pointer changes.
+
+#### Phase 2: Classify untracked files
+
+```bash
+git ls-files --others --exclude-standard
+```
+
+This lists files that are (a) not tracked and (b) not already covered by `.gitignore`. For each, classify using the table below. Match **top-down** — first match wins.
+
+| Class | Patterns | Action |
+|-------|----------|--------|
+| **Dependencies** | `node_modules/`, `vendor/`, `bower_components/`, `.pnp.*`, `__pypackages__/`, `.venv/`, `venv/`, `env/` (Python) | `.gitignore` |
+| **Build output** | `dist/`, `build/`, `.next/`, `.nuxt/`, `.output/`, `out/`, `.svelte-kit/`, `.vercel/`, `.netlify/`, `.turbo/`, `storybook-static/`, `*.tsbuildinfo` | `.gitignore` |
+| **Cache** | `.cache/`, `.parcel-cache/`, `.eslintcache`, `.stylelintcache`, `tsconfig.tsbuildinfo` | `.gitignore` |
+| **Coverage** | `coverage/`, `.nyc_output/`, `lcov.info` | `.gitignore` |
+| **Logs** | `*.log`, `npm-debug.log*`, `yarn-debug.log*`, `pnpm-debug.log*`, `lerna-debug.log*` | `.gitignore` |
+| **OS artifacts** | `.DS_Store`, `Thumbs.db`, `desktop.ini`, `._*`, `ehthumbs.db` | `.gitignore` |
+| **Editor/IDE** | `.idea/`, `*.iml`, `*.swp`, `*.swo`, `*~`, `.project`, `.classpath`, `.settings/` | `.gitignore` |
+| **Runtime** | `.wrangler/`, `.dev.vars`, `*.pid`, `*.seed`, `.env.sentry-build-plugin` | `.gitignore` |
+| **Package artifacts** | `*.tgz`, `*.tar.gz` (in repo root or release dirs) | `.gitignore` |
+| **Secrets** | `.env`, `.env.local`, `.env.*.local` (**NOT** `.env.example`, `.env.template`, `.env.sample`), `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore` | `.gitignore` + **warn user** |
+| **Large binaries** | Any single file > 5 MB not inside `src/` or `assets/` | **skip** + **warn user** (don't gitignore — let user decide) |
+| **Source (default)** | Everything else: source files, configs, docs, specs, tests, lock files, CI files, `.specweave/`, `.github/`, `*.md` | `git add <file>` |
+
+**Critical**: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` are **Source** — always commit.
+
+#### Phase 3: Update .gitignore (if patterns were added)
+
+For each pattern classified as `.gitignore` in Phase 2:
+
+1. **Check if .gitignore exists** — if not, create it
+2. **Check if pattern already present** — `grep -qxF '<pattern>' .gitignore` (exact line match) or check if a parent pattern already covers it (e.g., `node_modules/` covers `node_modules/foo/`)
+3. **Append missing patterns** under a clearly marked section:
+
+```gitignore
+# Auto-managed by sw:save — do not edit this section manually
+.DS_Store
+node_modules/
+dist/
+.env
+```
+
+If the `# Auto-managed by sw:save` section already exists, append new patterns there. Otherwise create it at the end of the file.
+
+4. **Stage .gitignore**: `git add .gitignore`
+
+#### Phase 4: Stage remaining approved source files
 
-Run `git status --porcelain` and categorize files:
+```bash
+git add <each file classified as Source in Phase 2>
+```
+
+Use `git add` with explicit file paths — **never** `git add -A` or `git add .`.
+
+#### Phase 5: Verify clean state
+
+```bash
+untracked=$(git ls-files --others --exclude-standard)
+if [ -n "$untracked" ]; then
+  echo "WARNING: Remaining untracked files (not staged, not gitignored):"
+  echo "$untracked"
+fi
+```
+
+- If **zero untracked** remain → clean state achieved, proceed
+- If **untracked remain** (missed by classification) → warn, but still proceed with commit. These files carry forward to next save.
+- In `--interactive` mode: prompt user for each remaining untracked file (stage / gitignore / skip)
+
+### 5. Auto-Commit Message (if none provided)
+
+Analyze **staged files only** using `git diff --cached --name-only` and categorize:
 
 | Pattern | Type |
 |---------|------|
@@ -64,22 +152,44 @@ Run `git status --porcelain` and categorize files:
 | `package.json`, `*.config.*` | `chore:` |
 | `.github/`, CI files | `ci:` |
 | `.specweave/increments/*/` | use increment name |
+| `.gitignore` (only change) | `chore: update gitignore` |
+| Mixed (many categories) | `chore: sync changes` or most dominant type |
 
-**Format**: `type(scope): action description` -- scope from common path, action from most common status (add/update/remove). If active increment and increment files changed, reference it.
+**Format**: `type(scope): action description` — scope from common path, action from most common status (add/update/remove). If active increment and increment files changed, reference it.
 
-### 5. Commit and Push
+### 6. Commit and Push
 
 ```bash
-git add -A
 git commit -m "<message>"
 git push origin <branch>
 ```
 
-For multi-repo: generate per-repo messages and commit/push each repo with changes.
+**No `git add` here** — all staging was completed in Step 4.
+
+For multi-repo: Steps 2–6 run per repo. Nested repos commit/push first (innermost first), umbrella project last (so submodule pointers reflect the latest nested commits).
+
+### 7. Report Summary
 
-### 6. Report Summary
+Show per repo:
+
+```
+=== Save Report ===
+
+repo: repositories/org/my-app
+  committed: 12 files (8 source, 2 config, 1 test, 1 doc)
+  gitignored: 3 patterns added (.DS_Store, dist/, .env)
+  warnings: .env detected — added to .gitignore
+  push: origin/main ✓
+
+repo: . (umbrella)
+  committed: 4 files (3 specs, 1 submodule ref)
+  gitignored: 0 patterns (already covered)
+  push: origin/main ✓
+
+All repos clean ✓
+```
 
-Show repos synced, committed, skipped, and commit messages used.
+If `--dry-run`: show what WOULD be committed, gitignored, and warned — execute nothing.
 
 ## Conflict Handling
 

package/plugins/specweave/hooks/v2/guards/increment-existence-guard.sh

@@ -1,16 +1,23 @@
 #!/bin/bash
-# increment-existence-guard.sh - Enforces spec-first principle for team creation
+# increment-existence-guard.sh - Mode-aware guard for team creation
 #
 # PURPOSE:
-# Team creation (TeamCreate) MUST NOT proceed until at least one increment
-# exists with a substantive spec.md. This enforces the core SpecWeave principle:
-#   /sw:increment → /sw:team-lead (never skip the spec phase)
+# Enforces spec-first principle for IMPLEMENTATION teams while allowing
+# non-implementation teams (review, brainstorm, analysis) to proceed freely.
 #
-# Without a spec, agents have no source of truth for scope, acceptance criteria,
-# or task boundaries. Skipping /sw:increment leads to uncoordinated implementation
-# where agents infer scope from natural language alone.
+# MODES:
+# - implementation (default): Requires increment with substantive spec.md
+# - review: PR reviews, code audits, architecture reviews — no increment needed
+# - brainstorm: Multi-perspective ideation sessions — no increment needed
+# - analysis: Codebase research, exploration, audits — no increment needed
 #
-# DETECTION:
+# MODE DETECTION (in priority order):
+# 1. team_name prefix: review-*, brainstorm-*, analysis-*, audit-*
+# 2. description keywords: "review", "brainstorm", "analyze", "audit", "explore",
+#    "ideate", "pr #", "pull request", "code review", "architecture review"
+# 3. Default: implementation mode (requires increment)
+#
+# DETECTION (implementation mode only):
 # - Fires on TeamCreate tool calls (global via hooks.json + skill-scoped via frontmatter)
 # - Scans .specweave/increments/ and repositories/*/*/.specweave/increments/
 # - Requires spec.md to pass ALL checks:
@@ -21,6 +28,7 @@
 # - ALLOWS if at least one passes all checks
 #
 # @since 1.0.342
+# @updated 1.0.417 — multi-mode support
 
 set -e
 
@@ -33,6 +41,64 @@ if [[ "$TOOL_NAME" != "TeamCreate" ]]; then
   exit 0
 fi
 
+# --- MODE DETECTION ---
+# Extract team_name and description from the tool input
+TEAM_NAME=$(echo "$INPUT" | jq -r '.tool_input.team_name // .input.team_name // ""' 2>/dev/null)
+DESCRIPTION=$(echo "$INPUT" | jq -r '.tool_input.description // .input.description // ""' 2>/dev/null)
+
+# Lowercase for matching
+TEAM_NAME_LC=$(echo "$TEAM_NAME" | tr '[:upper:]' '[:lower:]')
+DESCRIPTION_LC=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]')
+
+# Check 1: team_name prefix
+NON_IMPL_MODE=false
+case "$TEAM_NAME_LC" in
+  review-*|brainstorm-*|analysis-*|audit-*|explore-*|ideate-*)
+    NON_IMPL_MODE=true
+    ;;
+esac
+
+# Check 2: description keywords (only if prefix didn't match)
+if [[ "$NON_IMPL_MODE" == "false" ]]; then
+  NON_IMPL_KEYWORDS=(
+    "review"
+    "brainstorm"
+    "analyze"
+    "audit"
+    "explore"
+    "ideate"
+    "pull request"
+    "pr #"
+    "pr review"
+    "code review"
+    "architecture review"
+    "security audit"
+    "performance audit"
+    "code audit"
+    "ideation"
+    "exploration"
+    "research"
+    "perspectives"
+    "devil's advocate"
+    "pros and cons"
+  )
+
+  for keyword in "${NON_IMPL_KEYWORDS[@]}"; do
+    if [[ "$DESCRIPTION_LC" == *"$keyword"* ]]; then
+      NON_IMPL_MODE=true
+      break
+    fi
+  done
+fi
+
+# Non-implementation modes bypass the spec check entirely
+if [[ "$NON_IMPL_MODE" == "true" ]]; then
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# --- IMPLEMENTATION MODE: Require increment with spec ---
+
 # Template markers — spec.md with these is a template, not a real spec
 TEMPLATE_MARKERS=(
   "[Story Title]"
@@ -121,10 +187,11 @@ if [[ "$FOUND" == "true" ]]; then
   exit 0
 fi
 
-# BLOCK — no qualifying increment found
+# BLOCK — no qualifying increment found (implementation mode only)
 REASON="SPEC-FIRST ENFORCEMENT: Increment Required Before Team Creation
 
 TeamCreate CANNOT proceed without an existing increment with a substantive spec.md.
+This requirement applies to IMPLEMENTATION teams only.
 
 No qualifying increment found. A valid spec.md must have:
   - At least 500 bytes of real content (not templates)
@@ -140,8 +207,10 @@ REQUIRED ACTION:
   2. Review and approve the spec, plan, and tasks
   3. THEN run: /sw:team-lead to parallelize execution
 
-WHY: Without a spec, agents have no source of truth for scope, acceptance criteria,
-or task boundaries. Skipping /sw:increment leads to uncoordinated implementation.
+ALTERNATIVE: For non-implementation work, use a mode-prefixed team name:
+  - review-*     → PR reviews, code audits (no increment needed)
+  - brainstorm-* → Ideation sessions (no increment needed)
+  - analysis-*   → Research and exploration (no increment needed)
 
 Workflow: /sw:increment → /sw:team-lead → /sw:done"
 

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

@@ -1,5 +1,5 @@
 ---
-description: "Preset-driven team building — spawn coordinated multi-agent teams from battle-tested presets for full-stack, review, testing, TDD, and migration workflows"
+description: "Preset-driven team building — spawn coordinated multi-agent teams from battle-tested presets for full-stack, review, brainstorm, testing, TDD, and migration workflows. Review and brainstorm presets work without an increment."
 hooks:
   PreToolUse:
     - matcher: TeamCreate
@@ -17,21 +17,35 @@ Spawn a coordinated team of agents from a preset configuration. Each preset defi
 ```
 /sw:team-build --preset full-stack "Build checkout flow"
 /sw:team-build --preset review "Review auth module"
+/sw:team-build --preset brainstorm "Brainstorm payment architecture"
 /sw:team-build --preset testing "Test payment service"
 /sw:team-build --preset tdd "Implement rate limiter"
 /sw:team-build --preset migration "Migrate users to v2 schema"
 ```
 
-**Note:** For the complete 9-domain skill mapping table, see `/sw:team-lead`.
+**Note:** For the complete mode documentation and 9-domain skill mapping, see `/sw:team-lead`.
 
 ## How It Works
 
 1. Parse the `--preset` flag to select a team configuration
-2. Read the active increment from `.specweave/increments/` for context
-3. Spawn agents with assigned skills, ownership scopes, and dependencies
-4. Coordinate execution order (sequential gates or parallel fan-out)
-5. Each agent operates via `/sw:do` or `/sw:auto` within its ownership boundary
-6. Quality gates run `/sw:grill` before any agent marks work complete
+2. Determine team mode from preset (implementation vs review vs brainstorm)
+3. For implementation presets (`full-stack`, `testing`, `tdd`, `migration`): read the active increment
+4. For non-implementation presets (`review`, `brainstorm`): proceed without increment
+5. Spawn agents with assigned roles and dependencies
+6. Coordinate execution order (sequential gates or parallel fan-out)
+
+### Preset-to-Mode Mapping
+
+| Preset | Mode | Increment Required? | team_name prefix |
+|--------|------|-------------------|-----------------|
+| `full-stack` | implementation | Yes | `impl-*` or any |
+| `review` | review | **No** | `review-*` |
+| `brainstorm` | brainstorm | **No** | `brainstorm-*` |
+| `testing` | implementation | Yes | `impl-*` or any |
+| `tdd` | implementation | Yes | `impl-*` or any |
+| `migration` | implementation | Yes | `impl-*` or any |
+
+**CRITICAL**: `review` and `brainstorm` presets MUST use their mode-prefixed team_name to bypass the spec-first guard.
 
 ---
 
@@ -89,46 +103,50 @@ This spawns:
 
 **Agents**: 3
 **Execution order**: All parallel (independent, no dependencies)
+**Mode**: review (NO increment required)
+**team_name**: MUST use `review-*` prefix (e.g., `review-auth-module`)
 
-Three specialized reviewers examine the codebase simultaneously from different angles. Each agent produces findings independently — no agent blocks another.
+Three specialized reviewers examine the codebase simultaneously from different angles. Each agent produces findings independently — no agent blocks another. Uses agent templates from `agents/reviewer-*.md`.
 
 #### Agent Composition
 
-| # | Role | Skill(s) | Owns | Responsibility |
-|---|------|----------|------|----------------|
-| 1 | Security | `sw:security` + `sw:security-patterns` | All files (read-only analysis) | Audit for vulnerabilities, injection vectors, auth flaws, secrets exposure, dependency CVEs |
-| 2 | Quality | `sw:grill` + `sw:code-simplifier` | All files (read-only analysis) | Review code quality, complexity, naming, duplication, SOLID violations, performance anti-patterns |
-| 3 | Docs | `sw:docs-updater` | All files (read-only analysis) | Check doc coverage, stale comments, missing JSDoc, README accuracy, spec-to-code alignment |
+| # | Role | Agent Template | Focus | Responsibility |
+|---|------|---------------|-------|----------------|
+| 1 | Security Reviewer | `agents/reviewer-security.md` | All files (read-only) | Vulnerabilities, injection, auth flaws, secrets, OWASP Top 10 |
+| 2 | Logic Reviewer | `agents/reviewer-logic.md` | All files (read-only) | Correctness, edge cases, error handling, race conditions, logic bugs |
+| 3 | Performance Reviewer | `agents/reviewer-performance.md` | All files (read-only) | N+1 queries, memory leaks, algorithmic complexity, scalability |
 
 #### Execution Chain
 
 ```
-+---------------+---------------+---------------+
-|               |               |               |
-v               v               v               |
-Agent 1         Agent 2         Agent 3         |
-(Security)      (Quality)       (Docs)          |
-|               |               |               |
-v               v               v               |
-Report          Report          Report          |
-+---------------+---------------+---------------+
-                |
-                v
-        Merged review summary
++-------------------+-------------------+-------------------+
+|                   |                   |                   |
+v                   v                   v                   |
+Agent 1             Agent 2             Agent 3             |
+(Security)          (Logic)             (Performance)       |
+|                   |                   |                   |
+v                   v                   v                   |
+REVIEW_COMPLETE     REVIEW_COMPLETE     REVIEW_COMPLETE     |
++-------------------+-------------------+-------------------+
+                    |
+                    v
+            Merged review summary
+            (Must Fix / Should Fix / Consider)
 ```
 
-**All agents run in parallel.** Each produces an independent report. Reports are merged into a single review summary upon completion.
+**All agents run in parallel.** Each uses its agent template and signals `REVIEW_COMPLETE:`. Team-lead merges, deduplicates, and prioritizes by severity.
 
 #### Example
 
 ```
 /sw:team-build --preset review "Review auth module before release"
+/sw:team-build --preset review "Review PR #63"
 ```
 
 This spawns three parallel reviewers:
-- **Security** agent checks for token leakage, CSRF, injection, and insecure defaults
-- **Quality** agent evaluates code structure, test coverage gaps, and complexity hotspots
-- **Docs** agent verifies API docs, inline comments, and spec alignment
+- **Security** reviewer checks for token leakage, CSRF, injection, and insecure defaults
+- **Logic** reviewer verifies correctness, edge cases, and error handling
+- **Performance** reviewer identifies N+1 queries, memory leaks, and scalability issues
 
 ---
 
@@ -284,27 +302,80 @@ This spawns:
 
 ---
 
+### 6. `brainstorm` — Multi-Perspective Ideation
+
+**Agents**: 3
+**Execution order**: All parallel (independent, no dependencies)
+**Mode**: brainstorm (NO increment required)
+**team_name**: MUST use `brainstorm-*` prefix (e.g., `brainstorm-arch-decision`)
+
+Three perspective agents explore a question simultaneously from different angles. Uses agent templates from `agents/brainstorm-*.md`.
+
+#### Agent Composition
+
+| # | Role | Agent Template | Perspective | Responsibility |
+|---|------|---------------|-------------|----------------|
+| 1 | Advocate | `agents/brainstorm-advocate.md` | Innovation | Champions the most ambitious approach, pushes boundaries |
+| 2 | Critic | `agents/brainstorm-critic.md` | Risk | Devil's advocate — finds failure modes, hidden costs, red lines |
+| 3 | Pragmatist | `agents/brainstorm-pragmatist.md` | Feasibility | Practical realist — timelines, team skills, maintenance burden |
+
+#### Execution Chain
+
+```
++-------------------+-------------------+-------------------+
+|                   |                   |                   |
+v                   v                   v                   |
+Agent 1             Agent 2             Agent 3             |
+(Advocate)          (Critic)            (Pragmatist)        |
+|                   |                   |                   |
+v                   v                   v                   |
+PERSPECTIVE_COMPLETE PERSPECTIVE_COMPLETE PERSPECTIVE_COMPLETE|
++-------------------+-------------------+-------------------+
+                    |
+                    v
+            Decision matrix + recommendation
+            → /sw:increment if proceeding
+```
+
+**All agents run in parallel.** Each signals `PERSPECTIVE_COMPLETE:`. Team-lead synthesizes into a decision matrix with scored options.
+
+#### Example
+
+```
+/sw:team-build --preset brainstorm "Microservices vs monolith for our growing app"
+```
+
+This spawns:
+- **Advocate** champions microservices — independent scaling, team autonomy, polyglot support
+- **Critic** warns about distributed complexity, network latency, operational overhead
+- **Pragmatist** evaluates team size, current traffic, migration cost, and timeline
+
+---
+
 ## Flags
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `--preset` | Yes | One of: `full-stack`, `review`, `testing`, `tdd`, `migration` |
-| `--increment` | No | Increment ID to operate on (defaults to active increment) |
+| `--preset` | Yes | One of: `full-stack`, `review`, `brainstorm`, `testing`, `tdd`, `migration` |
+| `--increment` | No | Increment ID to operate on (defaults to active increment; ignored for review/brainstorm) |
 | `--dry-run` | No | Show what agents would be spawned without actually spawning them |
 | `--max-agents` | No | Override max concurrent agents (default: 3) |
 
 ## Execution Order Summary
 
-| Preset | Order | Pattern |
-|--------|-------|---------|
-| `full-stack` | Sequential gate + parallel | Agent 1 first, then [Agent 2 + Agent 3] in parallel |
-| `review` | All parallel | [Agent 1 + Agent 2 + Agent 3] simultaneously |
-| `testing` | All parallel | [Agent 1 + Agent 2 + Agent 3] simultaneously |
-| `tdd` | Strict sequential | Agent 1 -> Agent 2 -> Agent 3 (no parallelism) |
-| `migration` | Sequential gate + parallel | Agent 1 first, then [Agent 2 + Agent 3] in parallel |
+| Preset | Order | Pattern | Increment? |
+|--------|-------|---------|-----------|
+| `full-stack` | Sequential gate + parallel | Agent 1 first, then [Agent 2 + Agent 3] in parallel | Yes |
+| `review` | All parallel | [Agent 1 + Agent 2 + Agent 3] simultaneously | **No** |
+| `brainstorm` | All parallel | [Agent 1 + Agent 2 + Agent 3] simultaneously | **No** |
+| `testing` | All parallel | [Agent 1 + Agent 2 + Agent 3] simultaneously | Yes |
+| `tdd` | Strict sequential | Agent 1 -> Agent 2 -> Agent 3 (no parallelism) | Yes |
+| `migration` | Sequential gate + parallel | Agent 1 first, then [Agent 2 + Agent 3] in parallel | Yes |
 
 ## SpecWeave Workflow Integration
 
+### Implementation Presets (full-stack, testing, tdd, migration)
+
 Each spawned agent integrates with the standard SpecWeave workflow:
 
 1. **Increment context** — agents read `spec.md` and `tasks.md` from the active increment
@@ -314,6 +385,16 @@ Each spawned agent integrates with the standard SpecWeave workflow:
 5. **Ownership boundaries** — agents only modify files within their assigned directories
 6. **Conflict prevention** — ownership scopes are non-overlapping to prevent merge conflicts
 
+### Non-Implementation Presets (review, brainstorm)
+
+These presets operate without increments:
+
+1. **Read-only analysis** — agents examine code but do not modify it
+2. **Independent reports** — each agent produces findings independently
+3. **Team-lead synthesis** — team-lead merges and deduplicates agent outputs
+4. **No closure needed** — no `/sw:done` or `/sw:grill` required
+5. **Follow-up bridge** — if actionable items found, suggest `/sw:increment` to formalize
+
 ### Organization Discovery (resolve BEFORE spawning agents)
 
 Resolve the `{ORG}` placeholder from `.specweave/config.json` (in priority order):
@@ -349,7 +430,7 @@ Spawn → Load increment context → Claim tasks → /sw:do or /sw:auto → /sw:
 If user provides an unknown preset name:
 
 ```
-Error: Unknown preset "xyz". Available presets: full-stack, review, testing, tdd, migration.
+Error: Unknown preset "xyz". Available presets: full-stack, review, brainstorm, testing, tdd, migration.
 Use /sw:team-build --help to see preset details.
 ```
 

package/plugins/specweave/skills/team-lead/agents/brainstorm-advocate.md

@@ -0,0 +1,65 @@
+You are the ADVOCATE agent in a brainstorm session.
+
+QUESTION: [BRAINSTORM_QUESTION]
+
+ROLE:
+  You champion the most ambitious, innovative approach. You push boundaries,
+  explore cutting-edge solutions, and argue for the option that maximizes
+  long-term value — even if it's harder to build. You are the voice of
+  "what if we did this RIGHT?"
+
+APPROACH:
+  1. Read the codebase to understand the current state and constraints
+  2. Research the most innovative solution to the question
+  3. Build a compelling case for the ambitious approach
+  4. Acknowledge trade-offs honestly but argue why they're worth it
+
+YOUR ANALYSIS MUST INCLUDE:
+
+  ### Proposed Approach
+  A clear description of the innovative solution you're advocating for.
+
+  ### Why This Is The Right Move
+  - Technical advantages (scalability, maintainability, performance)
+  - Business advantages (competitive edge, user experience, future-proofing)
+  - Team advantages (developer experience, testability, debuggability)
+
+  ### Architecture Sketch
+  High-level design showing key components and interactions.
+  Use ASCII diagrams where helpful.
+
+  ### Trade-offs (Honest Assessment)
+  - What's harder about this approach
+  - What risks exist
+  - What the timeline implications are
+  - BUT: why these trade-offs are acceptable
+
+  ### Precedents
+  Examples of successful projects/companies that took this approach.
+
+  ### Migration Path
+  If this requires changing existing code, outline the migration strategy.
+
+COMMUNICATION:
+  When done, signal completion:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "PERSPECTIVE_COMPLETE: Advocate perspective ready. Recommends: [1-sentence summary of proposed approach]. Key argument: [strongest point].",
+    summary: "Advocate perspective complete"
+  })
+
+  If you discover something important during analysis:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "INSIGHT: [important discovery that affects the brainstorm]",
+    summary: "Advocate found insight"
+  })
+
+RULES:
+  - READ-ONLY: Do not modify any files
+  - Be bold but honest: advocate strongly but don't hide real trade-offs
+  - Ground in reality: reference actual codebase patterns and constraints
+  - Be specific: "use event sourcing with CQRS" not "use a better architecture"
+  - Consider the FULL picture: technical, business, and team dimensions