specweave 1.0.363 → 1.0.367

package/plugins/specweave/agents/sw-pm.md

@@ -3,115 +3,21 @@ name: sw-pm
 description: Product Manager for writing spec.md with user stories and acceptance criteria. Use for increment specification creation during /sw:increment orchestration.
 model: opus
 memory: project
+skills:
+  - sw:pm
 ---
 
-# Product Manager Agent
-
-## Project Overrides
-
-!`s="pm"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
-
-## Identity
+# Product Manager Subagent
 
 You are a Product Manager specializing in spec-driven development. You create product specifications with user stories and acceptance criteria following SpecWeave conventions.
 
 Your prompt will contain: increment ID, increment path, feature description, and plugin root path.
 
-## Progressive Disclosure
-
-Load phases via Read() as needed — do NOT try to generate content without loading the relevant phase first.
-
-| Phase | When to Load | File (relative to plugin root) |
-|-------|--------------|------|
-| Deep Interview | **CHECK FIRST!** If enabled in config | `skills/pm/phases/00-deep-interview.md` |
-| Research | Gathering requirements | `skills/pm/phases/01-research.md` |
-| Spec Creation | Writing spec.md | `skills/pm/phases/02-spec-creation.md` |
-| Templates | Need spec template | `skills/pm/templates/spec-template.md` |
-| Validation | Final quality check | `skills/pm/phases/03-validation.md` |
-
-**How to find phase files**: Extract the plugin root from your prompt, then Read the phase file:
-```
-Read({ file_path: "<plugin_root>/skills/pm/phases/01-research.md" })
-```
-
-## Deep Interview Mode Check (MANDATORY)
-
-**Before starting any spec work, check if Deep Interview Mode is enabled:**
-
-```bash
-jq -r '.planning.deepInterview.enabled // false' .specweave/config.json
-```
-
-If `true`:
-1. Load `skills/pm/phases/00-deep-interview.md` from plugin root
-2. **THINK about complexity first** — don't blindly ask questions:
-   - Trivial features: 0-3 questions
-   - Small features: 4-8 questions
-   - Medium features: 9-18 questions
-   - Large features: 19-40 questions
-3. Check `minQuestions` config: `jq -r '.planning.deepInterview.minQuestions // 5' .specweave/config.json`
-4. Cover relevant categories (skip those that don't apply)
-5. Only proceed to Research phase after sufficient clarity
-
-### Writing Interview State to Disk (CRITICAL)
-
-You MUST write the interview state file so the enforcement guard can find it:
-
-```bash
-mkdir -p .specweave/state
-echo '{"incrementId":"XXXX-name","startedAt":"'$(date -Iseconds)'","coveredCategories":{}}' \
-  > .specweave/state/interview-XXXX-name.json
-```
-
-After covering each category, update the state file:
-```bash
-jq '.coveredCategories.architecture = {"coveredAt": "'$(date -Iseconds)'", "summary": "..."}' \
-  .specweave/state/interview-XXXX-name.json > tmp && mv tmp .specweave/state/interview-XXXX-name.json
-```
-
-## Core Principles
-
-1. **Phased Approach**: Work in phases, not all at once
-2. **Chunking**: Large specs (6+ user stories) must be chunked
-3. **Validation**: Every spec needs acceptance criteria
-4. **Traceability**: User stories link to acceptance criteria
-
-## Spec Structure
-
-```
-.specweave/increments/####-name/
-├── spec.md    # You create this
-├── plan.md    # Architect creates
-├── tasks.md   # Planner creates
-└── metadata.json
-```
-
-## User Story Format
-
-```markdown
-### US-001: [Title]
-**Project**: [project-name]
-**As a** [role]
-**I want** [capability]
-**So that** [benefit]
-
-**Acceptance Criteria**:
-- [ ] **AC-US1-01**: [Criterion 1]
-- [ ] **AC-US1-02**: [Criterion 2]
-```
-
-## Workflow
-
-0. **Check Deep Interview Mode** → If enabled, load phase 00 and interview FIRST
-1. **Read feature description from prompt** → Read `phases/01-research.md`
-2. **Requirements clear** → Read `phases/02-spec-creation.md` + `templates/spec-template.md`
-3. **Spec written** → Read `phases/03-validation.md`
-4. **Return** → spec.md is complete, control returns to increment orchestrator
-
-## Token Budget Per Response
+The `sw:pm` skill is preloaded with full domain logic including progressive phases, templates, and validation rules. Follow its instructions for spec creation workflow.
 
-- **Research phase**: < 500 tokens
-- **Spec creation**: < 600 tokens per chunk
-- **Validation**: < 400 tokens
+## Critical Reminders
 
-**NEVER exceed 2000 tokens in a single response!**
+- **Check Deep Interview Mode first** — `jq -r '.planning.deepInterview.enabled // false' .specweave/config.json`
+- **Register skill-chain marker** (STEP 0 in preloaded skill) before writing spec.md
+- **Chunking discipline** — never exceed 2000 tokens per response
+- **One user story at a time** for large specs (6+ stories)

package/plugins/specweave/hooks/.specweave/logs/auto-iterations.log

@@ -0,0 +1 @@
+{"timestamp":"2026-01-04T16:11:43Z","event":"session_stop","reason":"No auto session active","details":"approve_called:main","success":false,"iteration":0,"increment":"none"}

package/plugins/specweave/hooks/.specweave/logs/auto-stop-reasons.log

@@ -0,0 +1 @@
+{"timestamp":"2026-01-04T16:11:43Z","sessionId":"unknown","reason":"No auto session active","details":"approve_called:main","success":false,"iteration":0,"increment":"none","testsRun":false,"testsPassed":0,"testsFailed":0}

package/plugins/specweave/skills/.specweave/logs/reflect/auto-reflect.log

@@ -0,0 +1,15 @@
+{
+  "ran": false,
+  "inputSummary": {
+    "transcriptLines": 266
+  },
+  "extracted": {
+    "skillLearnings": []
+  },
+  "written": {
+    "learningsAdded": 0,
+    "learningsSkippedDuplicate": 0
+  },
+  "durationMs": 1.4448749999999997,
+  "reason": "CLAUDE.md not found in project"
+}

package/plugins/specweave/skills/.specweave/logs/reflect/reflect.log

@@ -0,0 +1,3 @@
+[2026-02-03T22:03:06Z] [info] Starting reflection (265 lines)
+[2026-02-03T22:03:06Z] [info] Reflection started in background
+[2026-02-03T22:03:06Z] [info] Reflection completed - no learnings

package/plugins/specweave/skills/.specweave/logs/stop-auto.log

@@ -0,0 +1 @@
+[2026-02-03T22:03:06Z] APPROVE: No increments directory

package/plugins/specweave/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 description: Multi-perspective ideation with selectable cognitive lenses, persistent idea trees, and native handoff to sw:increment. Use when saying "brainstorm", "ideate", "explore ideas", "what are our options", "think about approaches", "compare approaches", "tree of thought", or "let's explore alternatives".
-argument-hint: "<topic> [--depth quick|standard|deep] [--lens default|six-hats|scamper|triz|adjacent]"
+argument-hint: "<topic> [--depth quick|standard|deep] [--lens default|six-hats|scamper|triz|adjacent] [--resume] [--criteria c1,c2,c3]"
 context: fork
 model: opus
 ---
@@ -62,15 +62,17 @@ digraph brainstorm {
   node [shape=box, style="rounded"];
 
   start [label="START\nsw:brainstorm <topic>"];
+  resume_check [label="RESUME CHECK\n--resume flag?"];
   step0 [label="STEP 0\nState Registration"];
-  parse [label="PARSE ARGS\n--depth, --lens"];
+  parse [label="PARSE ARGS\n--depth, --lens, --criteria"];
+  resume_load [label="LOAD STATE\nRead previous session\nResume from last phase"];
 
   frame [label="PHASE 1: FRAME\nProblem statement\nStarbursting (5W1H)\n1-2 questions"];
 
   lens_select [label="LENS SELECTION\nAskUserQuestion\n(deep: multi-select)"];
   diverge [label="PHASE 2: DIVERGE\nGenerate approaches\nvia selected lens"];
 
-  evaluate [label="PHASE 3: EVALUATE\nComparison matrix\nRecommendation"];
+  evaluate [label="PHASE 3: EVALUATE\nComparison matrix\n(default or custom criteria)\nRecommendation"];
 
   deepen [label="PHASE 4: DEEPEN\nAbstraction laddering\nAnalogies + Pre-mortem"];
 
@@ -78,7 +80,13 @@ digraph brainstorm {
 
   done [label="DONE"];
 
-  start -> step0;
+  start -> resume_check;
+  resume_check -> step0 [label="new session"];
+  resume_check -> resume_load [label="--resume"];
+  resume_load -> frame [label="phase was: frame"];
+  resume_load -> lens_select [label="phase was: diverge"];
+  resume_load -> evaluate [label="phase was: evaluate"];
+  resume_load -> output [label="phase was: complete\n(explore abandoned branches)"];
   step0 -> parse;
   parse -> frame;
 
@@ -90,6 +98,7 @@ digraph brainstorm {
 
   evaluate -> output [label="quick / standard"];
   evaluate -> deepen [label="deep"];
+  evaluate -> lens_select [label="user picks:\nrun more lenses"];
 
   deepen -> output;
 
@@ -113,11 +122,51 @@ Parse the user's input for:
 |-----|---------|--------|
 | `--depth` | `standard` | `quick`, `standard`, `deep` |
 | `--lens` | `default` | `default`, `six-hats`, `scamper`, `triz`, `adjacent` |
+| `--resume` | `false` | Flag — resume a previous brainstorm session |
+| `--criteria` | (default set) | Comma-separated custom evaluation criteria |
 
 Everything else is the **topic** (the problem statement to brainstorm about).
 
 If no topic is provided, ask the user: "What would you like to brainstorm about?"
 
+### Resume Mode (`--resume`)
+
+When `--resume` is passed:
+
+1. **Find the most recent state file** matching the topic:
+   ```bash
+   ls -t .specweave/state/brainstorm-*-${TOPIC_SLUG}*.json 2>/dev/null | head -1
+   ```
+2. **Read the state file** to determine where the session left off
+3. **Read the brainstorm document** (if one was partially saved)
+4. **Resume from the last completed phase**:
+   - If `phase: "frame"` → resume at Phase 2 (Diverge)
+   - If `phase: "evaluate"` → show the existing matrix, ask if user wants to re-evaluate or proceed
+   - If `phase: "complete"` → show the saved document, offer to explore abandoned branches from the idea tree
+5. **Present abandoned branches**: If the idea tree has approaches marked as abandoned or unexplored, offer to dig into those with a different lens
+
+This enables iterative brainstorming — start with quick mode, then `--resume --depth deep` to go deeper on the same topic.
+
+### Custom Evaluation Criteria (`--criteria`)
+
+Override the default evaluation criteria with domain-specific ones:
+
+```bash
+/sw:brainstorm "marketing strategy" --criteria "brand-fit,audience-reach,cost,differentiation"
+/sw:brainstorm "database choice" --criteria "read-perf,write-perf,operational-complexity,cost,ecosystem"
+```
+
+**Preset criteria sets** (auto-detected from context when `--criteria` is not provided):
+
+| Context | Criteria |
+|---------|----------|
+| **Engineering** (default) | Complexity, Time, Risk, Extensibility, Alignment |
+| **Marketing/Product** | Brand Fit, Audience Reach, Cost, Differentiation, Time-to-Market |
+| **Infrastructure** | Performance, Reliability, Cost, Operational Complexity, Scalability |
+| **Business** | Revenue Impact, Cost, Time-to-Value, Strategic Alignment, Risk |
+
+When custom criteria are provided, use them instead of the defaults in the Phase 3 Evaluation Matrix. Each criterion is still scored on a 1-5 scale.
+
 ---
 
 ## Phase 1: Frame
@@ -424,32 +473,81 @@ Generate 4-6 independent approaches, each with a different strategic orientation
 
 **Deep mode dispatch**: 7 parallel `Agent()` calls, one per transformation.
 
-### Lens: TRIZ / Constraint Inversion
+### Lens: TRIZ / Inventive Principles + Constraint Inversion
 
-Single-threaded structured analysis:
+Two-part structured analysis combining TRIZ inventive principles with assumption negation.
+
+**Part 1: Apply TRIZ Inventive Principles** (select 5-7 most relevant from the 40):
+
+| # | Principle | Software Adaptation |
+|---|-----------|-------------------|
+| 1 | Segmentation | Break monolith into microservices; split large features into independent modules |
+| 2 | Taking Out / Extraction | Extract cross-cutting concerns (auth, logging) into middleware or services |
+| 5 | Merging | Combine multiple API calls into batch endpoints; merge related microservices |
+| 10 | Preliminary Action | Pre-compute, cache, warm up; generate at build time instead of runtime |
+| 13 | The Other Way Round | Invert control flow (push vs pull, server-driven vs client-driven, event sourcing) |
+| 15 | Dynamicity | Feature flags, A/B testing, config-driven behavior instead of hardcoded |
+| 17 | Another Dimension | Add time dimension (versioning, audit trails); add abstraction layer |
+| 22 | Blessing in Disguise | Turn a constraint into a feature (rate limiting → fair usage; downtime → maintenance window) |
+| 24 | Intermediary | Add proxy, gateway, adapter, or anti-corruption layer |
+| 25 | Self-Service | User-facing admin panels, self-serve onboarding, API key management |
+| 28 | Mechanics Substitution | Replace manual process with automation; replace polling with webhooks |
+| 35 | Parameter Change | Change data format (JSON→protobuf), protocol (REST→gRPC), storage engine |
+| 40 | Composite Materials | Polyglot persistence, hybrid architectures, best-of-breed tool selection |
+
+For each relevant principle, generate ONE approach that applies it to the problem.
+
+**Part 2: Constraint Inversion** (the original approach, now enhanced):
 
 1. **List 3-5 core assumptions** about the problem
 2. **For each assumption**, generate an approach where that assumption is **negated**
 3. **Evaluate** which inversions produce viable alternatives
-4. **Output**: The most promising inversion-based approaches (typically 2-3)
+4. **Cross-reference** with Part 1 — do any TRIZ principles align with the inversions?
+5. **Output**: The 3-4 most promising combined approaches
 
 Example:
 - Assumption: "Users must authenticate before accessing data"
-- Inversion: "What if data were public by default with audit trails?"
-- Viable? → Assess trade-offs
+- TRIZ #13 (The Other Way Round): Invert the flow — data is public by default with audit trails
+- TRIZ #25 (Self-Service): Users manage their own access permissions
+- Inversion viable? → Assess trade-offs — this is literally how Google Docs sharing works
+
+**Deep mode dispatch**: Can dispatch Part 1 (principles) and Part 2 (inversions) as 2 parallel `Agent()` calls, then synthesize.
 
 ### Lens: Adjacent Possible
 
-What recently became feasible? Single-threaded analysis:
+What recently became feasible? Web-search-enhanced analysis:
+
+1. **Research phase** — Use `WebSearch` to ground ideas in reality:
+   ```
+   WebSearch({ query: "[topic] new tools frameworks 2025 2026" })
+   WebSearch({ query: "[topic] emerging approaches trends" })
+   ```
+   Extract: new APIs, frameworks, cost changes, AI capabilities, regulatory shifts.
 
-1. **Scan recent developments**: New APIs, frameworks, AI capabilities, cost reductions, regulatory changes
-2. **Generate 4-6 approaches** that leverage these newly-possible capabilities
-3. **Focus**: "What was impossible or impractical 12 months ago but is now viable?"
+2. **Scan recent developments**: Combine web search results with model knowledge about:
+   - New APIs and services launched in the last 12 months
+   - AI capabilities that crossed a quality/cost threshold
+   - Infrastructure cost drops (storage, compute, bandwidth)
+   - Regulatory changes that enable/restrict approaches
+   - Open-source projects that matured to production-ready
+
+3. **Generate 4-6 approaches** that leverage these newly-possible capabilities
+
+4. **Focus**: "What was impossible or impractical 12 months ago but is now viable?"
+
+5. **Ground each approach** — cite the specific development that enables it:
+   ```
+   ### Approach: LLM-Powered Classification
+   **Enabled by**: Claude 4/GPT-4o quality + sub-$1/1M token pricing (2025)
+   **Previously**: Required custom ML models, labeled datasets, training infra
+   **Now**: Zero-shot classification via API call, 95%+ accuracy for most use cases
+   ```
 
 Example prompts:
 - "What if we used LLMs for [X] instead of building rules?"
 - "What if we used edge computing for [Y] instead of centralized?"
 - "What if the cost of [Z] dropped 10x — how would our approach change?"
+- "What open-source tool launched recently that solves [Y] out of the box?"
 
 ---
 
@@ -569,19 +667,23 @@ Example prompts:
 
 ---
 
-## Token Budgets
-
-| Phase | Budget | Notes |
-|-------|--------|-------|
-| Frame | 400 tokens | Problem + 5W1H + questions |
-| Diverge (per approach) | 600 tokens | Name + summary + steps + trade-offs |
-| Diverge (total) | 3600 tokens max | 6 approaches max |
-| Evaluate | 500 tokens | Matrix + recommendation |
-| Deepen | 500 tokens | Ladder + analogies + assumptions + pre-mortem |
-| Output | 400 tokens | Summary + handoff |
-| **Quick total** | ~1300 tokens | Frame + 3 approaches + Evaluate |
-| **Standard total** | ~3500 tokens | Frame + Diverge + Evaluate + Output |
-| **Deep total** | ~5400 tokens | All 5 phases |
+## Token Budgets (Guidelines)
+
+These are targets, not hard limits. Prefer conciseness, but expand when the problem demands it.
+
+| Phase | Target | Hard Max | Notes |
+|-------|--------|----------|-------|
+| Frame | ~400 tokens | 800 | Problem + 5W1H + questions |
+| Diverge (per approach) | ~600 tokens | 1000 | Name + summary + steps + trade-offs |
+| Diverge (total) | ~3600 tokens | 6000 | 6 approaches max |
+| Evaluate | ~500 tokens | 800 | Matrix + recommendation |
+| Deepen | ~500 tokens | 1000 | Ladder + analogies + assumptions + pre-mortem |
+| Output | ~400 tokens | 600 | Summary + handoff |
+| **Quick total** | ~1300 | ~2600 | Frame + 3 approaches + Evaluate |
+| **Standard total** | ~3500 | ~5200 | Frame + Diverge + Evaluate + Output |
+| **Deep total** | ~5400 | ~9200 | All 5 phases |
+
+**When to exceed targets**: Complex problems with many stakeholders, deeply technical domains requiring precise terminology, or when the user explicitly asks for more detail.
 
 ---
 

package/plugins/specweave/skills/increment/SKILL.md

@@ -170,14 +170,20 @@ Every US MUST have `**Project**:` field. For 2-level structures, also `**Board**
 
 ### 3a. Determine Increment Location
 
-**CRITICAL for multi-repo setups:**
+**CRITICAL for umbrella vs single-repo:**
 
 ```bash
-# Check if this is a multi-repo umbrella project
-if [ -d "repositories" ]; then
-  echo "MULTI-REPO: Increments belong in EACH repo's .specweave/"
+# Check umbrella mode
+UMBRELLA_ENABLED=$(jq -r '.umbrella.enabled // false' .specweave/config.json 2>/dev/null)
+
+if [ "$UMBRELLA_ENABLED" = "true" ]; then
+  echo "UMBRELLA MODE: Increments go in UMBRELLA ROOT .specweave/increments/"
+  echo "The **Project**: field in each user story controls sync routing to child repos."
+  # List available child repos for context
+  jq -r '.umbrella.childRepos[]? | "\(.name) (\(.path))"' .specweave/config.json 2>/dev/null
+elif [ -d "repositories" ]; then
+  echo "MULTI-REPO (no umbrella): Increments belong in EACH repo's .specweave/"
   ORG=$(jq -r '.repository.organization // empty' .specweave/config.json 2>/dev/null)
-  [ -z "$ORG" ] && ORG=$(jq -r '[.sync.profiles[].config.owner // .sync.profiles[].config.organization] | map(select(. != null)) | first // empty' .specweave/config.json 2>/dev/null)
   [ -z "$ORG" ] && ORG=$(ls -d repositories/*/ 2>/dev/null | head -1 | xargs basename 2>/dev/null)
   echo "Organization: $ORG"
   ls -d repositories/*/* 2>/dev/null | head -20
@@ -186,12 +192,15 @@ else
 fi
 ```
 
-**Multi-repo rules:**
+**Umbrella mode (`umbrella.enabled: true`):**
+- ALL increments go in the umbrella root `.specweave/increments/` — NOT in child repos
+- The `**Project**:` field in each user story controls which repo receives sync (GitHub issues, JIRA tickets)
+- Cross-cutting increments can span multiple child repos — each US targets a different project
+- Repos MUST be at `repositories/{ORG}/{repo-name}/` — NEVER directly under `repositories/`
+
+**Non-umbrella multi-repo (legacy):**
 - Each repository has its OWN `.specweave/increments/` directory
-- Team agents MUST create increments in their assigned repo's `.specweave/`
-- The umbrella root `.specweave/` is for umbrella-level config ONLY
 - Run `specweave init` in each repo if `.specweave/` doesn't exist
-- Repos MUST be at `repositories/{ORG}/{repo-name}/` — NEVER directly under `repositories/`
 
 ### 3b. Get Unique ID
 
@@ -259,41 +268,42 @@ Create files in order: metadata.json FIRST, then spec.md, plan.md, tasks.md.
 
 ## Critical Rules
 
-1. **NEVER write spec.md/plan.md/tasks.md directly** — ALWAYS delegate via Skill() calls to plugin agents
+1. **NEVER write spec.md/plan.md/tasks.md directly** — ALWAYS delegate via Agent() calls to custom subagents
 2. **Project field is MANDATORY** — Every US MUST have `**Project**:` field
 3. **Use Template Creator CLI** (REQUIRED): `specweave create-increment --id "XXXX-name" --title "Title" --description "Desc" --project "my-app"`
-4. **Agent delegation is the ONLY way** to produce spec.md/plan.md/tasks.md — invoke `sw:agents:sw-pm`, `sw:agents:sw-architect`, `sw:agents:sw-planner` via Skill() calls
+4. **Agent delegation is the ONLY way** to produce spec.md/plan.md/tasks.md — spawn `sw:sw-pm`, `sw:sw-architect`, `sw:sw-planner` subagents via Agent() calls
 5. **Increment naming** — Format: `####-descriptive-kebab-case`
-6. **Multi-repo** — In umbrella projects with `repositories/` folder, create increments in EACH repo's `.specweave/`, not the umbrella root
+6. **Umbrella mode** — When `umbrella.enabled: true`, ALL increments go in the umbrella root `.specweave/increments/`. The `**Project**:` field per user story routes sync to child repos. Do NOT create increments in child repos.
 
-## CRITICAL: Mandatory Agent Delegation
+## CRITICAL: Mandatory Subagent Delegation
 
 **This skill MUST NOT write spec.md, plan.md, or tasks.md directly.**
-Delegate to plugin agents via Skill() calls.
+Delegate to custom subagents via Agent() calls. Each subagent preloads its corresponding skill with full domain logic.
 
-**You MUST invoke these plugin agents:**
+**You MUST spawn these subagents:**
 
-| File | Agent Skill | Invocation |
-|------|-------------|------------|
-| spec.md | sw:agents:sw-pm | `Skill({ skill: "sw:agents:sw-pm", args: "Write spec for increment XXXX-name: <description>. Increment path: <path>" })` |
-| plan.md | sw:agents:sw-architect | `Skill({ skill: "sw:agents:sw-architect", args: "Design architecture for increment XXXX-name. Read spec.md at <path>/spec.md" })` |
-| tasks.md | sw:agents:sw-planner | `Skill({ skill: "sw:agents:sw-planner", args: "Generate tasks for increment XXXX-name. Read spec.md at <path>/spec.md and plan.md at <path>/plan.md" })` |
+| File | Subagent | Invocation |
+|------|----------|------------|
+| spec.md | sw:sw-pm | `Agent({ subagent_type: "sw:sw-pm", prompt: "Write spec for increment XXXX-name: <description>. Increment path: <path>. [UMBRELLA: child repos list if enabled]", description: "PM writes spec.md" })` |
+| plan.md | sw:sw-architect | `Agent({ subagent_type: "sw:sw-architect", prompt: "Design architecture for increment XXXX-name. Read spec.md at <path>/spec.md", description: "Architect writes plan.md" })` |
+| tasks.md | sw:sw-planner | `Agent({ subagent_type: "sw:sw-planner", prompt: "Generate tasks for increment XXXX-name. Read spec.md at <path>/spec.md and plan.md at <path>/plan.md", description: "Planner writes tasks.md" })` |
 
 **DO NOT:**
 - Write user stories, architecture, or tasks inline
 - Copy/paste spec content into Write() calls
 - "Summarize" what an agent would produce
-- Skip any of the 3 Skill() calls
+- Skip any of the 3 Agent() calls
+- Use Skill() for these — subagents provide memory + resumability
 
 ## Step 3a: Deep Interview Mode (if enabled)
 
 **IMPORTANT**: This step runs AFTER the increment folder is created (Step 3), so the
 interview state file can reference the real increment ID.
 
-**If deep interview is enabled, delegate to PM agent:**
+**If deep interview is enabled, delegate to PM subagent:**
 
 ```typescript
-Skill({ skill: "sw:agents:sw-pm", args: "Deep interview for increment XXXX-name: <user description>. Increment path: <path>" })
+Agent({ subagent_type: "sw:sw-pm", prompt: "Deep interview for increment XXXX-name: <user description>. Increment path: <path>", description: "PM deep interview" })
 ```
 
 The PM agent will:
@@ -305,23 +315,31 @@ The PM agent will:
 **After PM agent returns**, read the interview state file to confirm all categories are covered
 before proceeding to spec.md creation (especially when `enforcement: "strict"`).
 
-## Step 4: Delegation (MANDATORY - Plugin Agent Based)
+## Step 4: Delegation (MANDATORY - Custom Subagent Based)
 
-**After increment folder + metadata.json are created, you MUST invoke all 3 plugin agents sequentially.**
+**After increment folder + metadata.json are created, you MUST spawn all 3 subagents sequentially.**
 
-### 4a. Invoke PM Agent for spec.md (REQUIRED)
+Each subagent preloads its corresponding skill (with full domain logic, phases, templates). The subagent provides: isolated context, persistent memory, resumability, auto-compaction.
+
+### 4a. Spawn PM Subagent for spec.md (REQUIRED)
+
+**Include umbrella context when `umbrella.enabled: true`:**
 ```typescript
-Skill({ skill: "sw:agents:sw-pm", args: "Write spec for increment XXXX-name: <user's feature description>. Increment path: .specweave/increments/XXXX-name/" })
+// Umbrella mode — pass child repos so PM can assign **Project**: per user story
+Agent({ subagent_type: "sw:sw-pm", prompt: "Write spec for increment XXXX-name: <description>. Increment path: .specweave/increments/XXXX-name/. UMBRELLA MODE: Child repos: [repo1, repo2, ...]. Design cross-cutting stories — assign **Project**: to each US based on which repo owns that work.", description: "PM writes spec.md" })
+
+// Single-project mode — standard invocation
+Agent({ subagent_type: "sw:sw-pm", prompt: "Write spec for increment XXXX-name: <description>. Increment path: .specweave/increments/XXXX-name/", description: "PM writes spec.md" })
 ```
 
-### 4b. Invoke Architect Agent for plan.md (REQUIRED)
+### 4b. Spawn Architect Subagent for plan.md (REQUIRED)
 ```typescript
-Skill({ skill: "sw:agents:sw-architect", args: "Design architecture for increment XXXX-name. Read spec.md at .specweave/increments/XXXX-name/spec.md. ADR directory: .specweave/docs/internal/architecture/adr/" })
+Agent({ subagent_type: "sw:sw-architect", prompt: "Design architecture for increment XXXX-name. Read spec.md at .specweave/increments/XXXX-name/spec.md. ADR directory: .specweave/docs/internal/architecture/adr/", description: "Architect writes plan.md" })
 ```
 
-### 4c. Invoke Planner Agent for tasks.md (REQUIRED)
+### 4c. Spawn Planner Subagent for tasks.md (REQUIRED)
 ```typescript
-Skill({ skill: "sw:agents:sw-planner", args: "Generate tasks for increment XXXX-name. Read spec.md at .specweave/increments/XXXX-name/spec.md and plan.md at .specweave/increments/XXXX-name/plan.md" })
+Agent({ subagent_type: "sw:sw-planner", prompt: "Generate tasks for increment XXXX-name. Read spec.md at .specweave/increments/XXXX-name/spec.md and plan.md at .specweave/increments/XXXX-name/plan.md", description: "Planner writes tasks.md" })
 ```
 
 **Order matters**: PM first (spec.md) -> Architect second (plan.md) -> Planner last (tasks.md).
@@ -431,7 +449,7 @@ Created increment 0003-user-authentication
 
 - `.specweave/` not found: "Run specweave init first"
 - Vague description: Ask clarifying questions
-- Agent fails: Fall back to invoking `/sw:pm` or `/sw:architect` skills directly
+- Subagent fails: Fall back to invoking `/sw:pm` or `/sw:architect` skills directly (skills still work standalone)
 
 ---
 

package/plugins/specweave/skills/pm/SKILL.md

@@ -72,7 +72,7 @@ If `true`:
 
 ### Writing Interview State to Disk (CRITICAL)
 
-**This skill runs with `context: fork` (isolated LLM context), but file writes persist.**
+**When invoked via subagent (sw:sw-pm), this runs in an isolated context, but file writes persist.**
 
 When invoked from `sw:increment` with an increment ID (e.g., "Deep interview for increment 0266-foo: ..."),
 you MUST write the interview state file to disk so the enforcement guard can find it:
@@ -95,6 +95,33 @@ jq '.coveredCategories.architecture = {"coveredAt": "'$(date -Iseconds)'", "summ
 `.specweave/state/interview-{increment-id}.json` before allowing spec.md writes. If this file
 is missing or incomplete, spec.md creation is BLOCKED in strict mode.
 
+## Umbrella Mode (Cross-Cutting Specs)
+
+When your invocation args include **UMBRELLA MODE**, the project uses an umbrella workspace with multiple child repos. This changes how you design specs:
+
+**Umbrella mode (`umbrella.enabled: true`):**
+- Design **cross-cutting** user stories that span multiple repos
+- Each US gets `**Project**: <child-repo-name>` based on which repo owns that work
+- Think at a higher level: a "login feature" may need US for frontend (UI) AND backend (API)
+- A single increment can contain stories targeting different child repos
+- Use prefixed IDs when multi-project is detected: `US-FE-001`, `US-BE-001`
+- For umbrella-scoped work (CI, shared config), use the umbrella project name
+
+**Example — umbrella increment with 2 child repos (frontend, backend):**
+```markdown
+### US-FE-001: Login Page UI
+**Project**: frontend
+**As a** user **I want** a login form **So that** I can authenticate
+
+### US-BE-001: Authentication API
+**Project**: backend
+**As a** user **I want** a /login endpoint **So that** the frontend can authenticate
+```
+
+**Single-project mode (no umbrella context in args):**
+- All user stories get the same `**Project**: <project-name>` value
+- Standard single-project spec design
+
 ## Core Principles
 
 1. **Phased Approach**: Work in phases, not all at once

package/plugins/specweave/skills/pm/phases/02-spec-creation.md

@@ -68,6 +68,23 @@ Edit spec.md to append remaining user stories.
 Report completion.
 ```
 
+## Umbrella Mode: Multi-Project Story Assignment
+
+When the increment uses **umbrella mode** (args contain "UMBRELLA MODE" with child repo list):
+
+1. **Decompose by repo ownership**: Each user story targets ONE child repo via `**Project**:`
+2. **Cross-cutting features**: Split into separate stories per repo (e.g., frontend UI + backend API)
+3. **Use prefixed IDs**: `US-FE-001`, `US-BE-002` — prefix from `specweave context projects`
+4. **Shared/infra work**: Set `**Project**:` to the umbrella project name
+5. **Every US must have exactly one `**Project**:`** — never omit, never assign multiple
+
+**Example split for "user login":**
+- `US-FE-001: Login Page` → `**Project**: frontend`
+- `US-BE-001: Auth API Endpoint` → `**Project**: backend`
+- `US-BE-002: JWT Token Service` → `**Project**: backend`
+
+When NOT in umbrella mode, all stories get the same `**Project**: <project-name>`.
+
 ## User Story Guidelines
 
 ### Good User Story

package/plugins/specweave/skills/test-aware-planner/SKILL.md

@@ -1,7 +1,7 @@
 ---
 description: Generate tasks.md with embedded test plans in BDD format, one user story at a time to prevent crashes. Use for test-first task planning where each task includes Given/When/Then scenarios. Produces implementation tasks with inline test specifications.
 context: fork
-model: opus
+model: sonnet
 ---
 
 # Test-Aware Planner Skill

package/plugins/specweave-ado/lib/ado-multi-project-sync.js

@@ -373,7 +373,6 @@ ${userStory.technicalContext}
         return mapping.task || "Task";
       case "Subtask":
         return mapping.task || "Task";
-      // ADO doesn't have subtasks, use Task
       default:
         return "User Story";
     }