specweave 1.0.340 → 1.0.342

package/plugins/specweave/hooks/hooks.json

@@ -9,6 +9,15 @@
             "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/dispatchers/pre-tool-use.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
+      },
+      {
+        "matcher": "TeamCreate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/increment-existence-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
       }
     ],
     "SessionStart": [

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

@@ -0,0 +1,150 @@
+#!/bin/bash
+# increment-existence-guard.sh - Enforces spec-first principle 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)
+#
+# 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.
+#
+# DETECTION:
+# - 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:
+#   1. File exists and has >500 bytes of content
+#   2. No template markers (exact strings or {{VAR}} patterns)
+#   3. At least one acceptance criterion (AC- pattern)
+# - BLOCKS if no qualifying increment found
+# - ALLOWS if at least one passes all checks
+#
+# @since 1.0.342
+
+set -e
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // .toolName // ""')
+
+# Only check TeamCreate
+if [[ "$TOOL_NAME" != "TeamCreate" ]]; then
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# Template markers — spec.md with these is a template, not a real spec
+TEMPLATE_MARKERS=(
+  "[Story Title]"
+  "[user type]"
+  "[goal]"
+  "[benefit]"
+  "[Specific, testable criterion]"
+  "[Component 1]"
+  "[High-level description"
+  "{{RESOLVED_PROJECT}}"
+  "TEMPLATE FILE"
+)
+
+check_spec() {
+  local spec_path="$1"
+  if [[ ! -f "$spec_path" ]]; then
+    return 1
+  fi
+
+  # Check 1: Minimum size (500 bytes — a real spec with user stories and ACs)
+  local size
+  size=$(wc -c < "$spec_path" 2>/dev/null || echo "0")
+  size=$(echo "$size" | tr -d '[:space:]')
+  if [[ "$size" -le 500 ]]; then
+    return 1
+  fi
+
+  # Check 2: Scan FULL file for template markers (not just first 10 lines)
+  local content
+  content=$(cat "$spec_path" 2>/dev/null || echo "")
+
+  # Exact template marker strings
+  for marker in "${TEMPLATE_MARKERS[@]}"; do
+    if [[ "$content" == *"$marker"* ]]; then
+      return 1
+    fi
+  done
+
+  # Regex: {{UPPERCASE_VAR}} mustache placeholders (e.g., {{FEATURE_NAME}})
+  if echo "$content" | grep -qE '\{\{[A-Z_]+\}\}' 2>/dev/null; then
+    return 1
+  fi
+
+  # Regex: High count of [Bracket Placeholders] suggests unfilled template
+  # (threshold: 4+ to avoid false positives from markdown links [text](url))
+  local bracket_count
+  bracket_count=$(echo "$content" | grep -cE '\[[A-Z][^]]{2,}\]' 2>/dev/null || true)
+  bracket_count=$(echo "$bracket_count" | tail -1 | tr -d '[:space:]')
+  if [[ -n "$bracket_count" ]] && [[ "$bracket_count" -ge 4 ]]; then
+    return 1
+  fi
+
+  # Check 3: Structural completeness — at least one acceptance criterion
+  if ! grep -qE 'AC-US[0-9]+-[0-9]+|AC-[0-9]+' "$spec_path" 2>/dev/null; then
+    return 1
+  fi
+
+  return 0
+}
+
+# Search for qualifying increments
+FOUND=false
+
+# Single-repo increments
+if [[ -d ".specweave/increments" ]]; then
+  while IFS= read -r spec; do
+    if check_spec "$spec"; then
+      FOUND=true
+      break
+    fi
+  done < <(find .specweave/increments -maxdepth 2 -name "spec.md" 2>/dev/null)
+fi
+
+# Multi-repo increments
+if [[ "$FOUND" == "false" ]] && [[ -d "repositories" ]]; then
+  while IFS= read -r spec; do
+    if check_spec "$spec"; then
+      FOUND=true
+      break
+    fi
+  done < <(find repositories -path "*/.specweave/increments/*/spec.md" -maxdepth 6 2>/dev/null)
+fi
+
+if [[ "$FOUND" == "true" ]]; then
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# BLOCK — no qualifying increment found
+REASON="SPEC-FIRST ENFORCEMENT: Increment Required Before Team Creation
+
+TeamCreate CANNOT proceed without an existing increment with a substantive spec.md.
+
+No qualifying increment found. A valid spec.md must have:
+  - At least 500 bytes of real content (not templates)
+  - No unfilled template markers or {{PLACEHOLDER}} patterns
+  - At least one acceptance criterion (AC-USx-xx pattern)
+
+Searched:
+  - .specweave/increments/*/spec.md
+  - repositories/*/*/.specweave/increments/*/spec.md
+
+REQUIRED ACTION:
+  1. Run: /sw:increment \"your feature description\"
+  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.
+
+Workflow: /sw:increment → /sw:team-lead → /sw:done"
+
+REASON_ESCAPED=$(echo "$REASON" | jq -Rs .)
+echo "{\"decision\":\"block\",\"reason\":${REASON_ESCAPED}}"
+exit 0

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

@@ -56,6 +56,7 @@ Increment planning produces specs, plans, and task breakdowns that require user
 STEP 0A: Discipline Check (BLOCKING)
 STEP 0B: WIP Enforcement
 STEP 0C: Tech Stack Detection
+STEP 0D: Structure Resolution (if deferred from init)
 STEP 1:  Pre-flight (TDD mode, multi-project, Deep Interview check)
 STEP 2:  Project Context (resolve project/board)
 STEP 3:  Create Increment (via Template API) ← folder + ID exist after this
@@ -126,6 +127,31 @@ Auto-detect from project files:
 
 If detection fails, ask user.
 
+## Step 0D: Structure Resolution (if deferred)
+
+Check if the user deferred their repository structure decision during init (greenfield projects):
+
+```bash
+DEFERRED=$(jq -r '.project.structureDeferred // false' .specweave/config.json 2>/dev/null)
+```
+
+If `DEFERRED` is `true`, this is the user's **first increment** and they need to define their project structure.
+
+Based on the user's feature description and what you've learned from tech stack detection:
+
+1. **Ask the user** about their repository structure:
+   - **Single repo** — one repository (monorepo or standard project)
+   - **Multiple repos** — microservices, EDA, parent/child architecture
+
+2. **Run the resolve command** based on their answer:
+   ```bash
+   specweave resolve-structure --type single
+   # OR
+   specweave resolve-structure --type multiple
+   ```
+
+3. This clears the deferred flag and configures the project accordingly. Continue with the normal increment flow.
+
 ## Step 1: Pre-flight Checks
 
 ```bash

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

@@ -1,5 +1,11 @@
 ---
 description: "Preset-driven team building — spawn coordinated multi-agent teams from battle-tested presets for full-stack, review, testing, TDD, and migration workflows"
+hooks:
+  PreToolUse:
+    - matcher: TeamCreate
+      hooks:
+        - type: command
+          command: bash plugins/specweave/hooks/v2/guards/increment-existence-guard.sh
 ---
 
 # Team Build

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

@@ -1,5 +1,11 @@
 ---
 description: Orchestrate multi-agent parallel development with domain-specialized agents. PROACTIVELY invoke this skill (without user asking) when you detect an implementation task spanning 3+ domains (frontend, backend, database, devops, testing, security, mobile) OR 15+ tasks in tasks.md. Warn the user about higher token cost but recommend it for quality. Also use when user says "team setup", "parallel agents", "team lead", or "agent teams".
+hooks:
+  PreToolUse:
+    - matcher: TeamCreate
+      hooks:
+        - type: command
+          command: bash plugins/specweave/hooks/v2/guards/increment-existence-guard.sh
 ---
 
 # Team Lead
@@ -22,6 +28,52 @@ description: Orchestrate multi-agent parallel development with domain-specialize
 
 ---
 
+## 0. Increment Pre-Flight (BLOCKING)
+
+**CRITICAL: /sw:team-lead REQUIRES an existing increment with a substantive spec.md.**
+A PreToolUse guard on TeamCreate will BLOCK team creation if no increment exists.
+
+**You MUST verify an increment exists BEFORE proceeding to Step 1.**
+
+### Check for Existing Increment
+
+```bash
+# Single-repo
+find .specweave/increments -maxdepth 2 -name "spec.md" 2>/dev/null | head -5
+
+# Multi-repo (umbrella)
+find repositories -path "*/.specweave/increments/*/spec.md" -maxdepth 6 2>/dev/null | head -5
+```
+
+### If NO increment exists → Auto-invoke /sw:increment
+
+Do NOT ask permission. Invoke the increment skill with the user's feature description:
+
+```typescript
+Skill({ skill: "sw:increment", args: "the user's feature description" })
+```
+
+Wait for /sw:increment to complete (spec.md, plan.md, tasks.md created and approved).
+Then continue to Step 1.
+
+If /sw:increment fails (user rejects plan, skill errors, etc.): **STOP. Do NOT proceed.**
+Report the failure to the user and ask them to run `/sw:increment` manually.
+
+### If increment exists → Read the master spec
+
+Read the increment's spec.md. This is the **source of truth** for all agent work:
+- Scope and boundaries
+- User stories and acceptance criteria
+- Task breakdown and dependencies
+
+Store the increment path as `MASTER_INCREMENT_PATH` — you will reference it in agent prompts.
+
+**WHY THIS MATTERS**: Without a spec, agents infer scope from natural language alone.
+This leads to uncoordinated implementation, scope creep, and missing acceptance criteria.
+The spec-first principle exists because specs are the contract between user intent and agent execution.
+
+---
+
 ## 1. Tool Reference
 
 | Action | Tool | Parameters |
@@ -275,6 +327,12 @@ Each agent receives a detailed prompt that includes its skill invocations, file
 ```
 You are the FRONTEND agent for increment [INCREMENT_ID].
 
+MASTER SPEC (SOURCE OF TRUTH):
+  The feature is fully specified in [MASTER_INCREMENT_PATH]/spec.md.
+  This spec defines scope, user stories, and acceptance criteria.
+  Your work MUST satisfy the ACs relevant to your domain.
+  Read the master spec BEFORE planning any work.
+
 SKILLS TO INVOKE:
   Skill({ skill: "frontend:architect" })
   Skill({ skill: "frontend:nextjs" })         // if Next.js project
@@ -302,7 +360,7 @@ WORKFLOW:
   1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
-  4. Read the increment spec and tasks
+  4. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   5. Verify services are running and accessible (check dev server, API endpoints)
   6. Wait for contract artifacts if Phase 1 is active:
      - Read src/types/ for shared interfaces
@@ -335,6 +393,12 @@ RULES:
 ```
 You are the BACKEND agent for increment [INCREMENT_ID].
 
+MASTER SPEC (SOURCE OF TRUTH):
+  The feature is fully specified in [MASTER_INCREMENT_PATH]/spec.md.
+  This spec defines scope, user stories, and acceptance criteria.
+  Your work MUST satisfy the ACs relevant to your domain.
+  Read the master spec BEFORE planning any work.
+
 SKILLS TO INVOKE:
   Skill({ skill: "sw:architect" })
   Skill({ skill: "infra:devops" })          // if deployment config needed
@@ -360,7 +424,7 @@ WORKFLOW:
   1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
-  4. Read the increment spec and tasks
+  4. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   5. Verify services are running and accessible (database, auth provider, external APIs)
   6. Wait for contract artifacts if Phase 1 is active:
      - Read prisma/schema.prisma for database schema
@@ -394,6 +458,12 @@ RULES:
 ```
 You are the DATABASE agent for increment [INCREMENT_ID].
 
+MASTER SPEC (SOURCE OF TRUTH):
+  The feature is fully specified in [MASTER_INCREMENT_PATH]/spec.md.
+  This spec defines scope, user stories, and acceptance criteria.
+  Your work MUST satisfy the ACs relevant to your domain.
+  Read the master spec BEFORE planning any work.
+
 SKILLS TO INVOKE:
   Skill({ skill: "sw:architect" })
 
@@ -411,7 +481,7 @@ WORKFLOW:
   1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
-  4. Read the increment spec and tasks
+  4. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   5. Design database schema changes
   6. Create plan files (plan.md, tasks.md) for your increment
   7. Send plan to team-lead and WAIT for approval:
@@ -444,6 +514,12 @@ RULES:
 ```
 You are the TESTING agent for increment [INCREMENT_ID].
 
+MASTER SPEC (SOURCE OF TRUTH):
+  The feature is fully specified in [MASTER_INCREMENT_PATH]/spec.md.
+  This spec defines scope, user stories, and acceptance criteria.
+  Your tests MUST cover ALL ACs from the master spec.
+  Read the master spec BEFORE planning any work.
+
 SKILLS TO INVOKE:
   Skill({ skill: "testing:qa" })
   Skill({ skill: "testing:e2e" })        // for E2E test suites
@@ -467,7 +543,7 @@ WORKFLOW:
   1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
-  4. Read the increment spec and tasks
+  4. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   5. Wait for ALL other agents to produce initial code
   6. Create plan files (plan.md, tasks.md) for your increment
   7. Send plan to team-lead and WAIT for approval:
@@ -500,6 +576,12 @@ RULES:
 ```
 You are the SECURITY agent for increment [INCREMENT_ID].
 
+MASTER SPEC (SOURCE OF TRUTH):
+  The feature is fully specified in [MASTER_INCREMENT_PATH]/spec.md.
+  This spec defines scope, user stories, and acceptance criteria.
+  Your security hardening MUST address all ACs from the master spec.
+  Read the master spec BEFORE planning any work.
+
 SKILLS TO INVOKE:
   Skill({ skill: "sw:security" })
   Skill({ skill: "sw:security-patterns" })
@@ -519,7 +601,7 @@ WORKFLOW:
   1. Set working directory to your assigned repo: cd repositories/{ORG}/{repo-name}
   2. If .specweave/ doesn't exist in your repo, run: specweave init
   3. Create YOUR increment in YOUR repo: .specweave/increments/[ID]/
-  4. Read the increment spec and tasks
+  4. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   5. Audit code produced by other agents for security issues
   6. Create plan files (plan.md, tasks.md) for your increment
   7. Send plan to team-lead and WAIT for approval:
@@ -739,9 +821,12 @@ Orchestrator Final Check:
 ```
 /sw:team-lead "Build checkout flow"
   │
-  ├── Step 1: Analyze feature -> identify domains -> decide increment split
+  ├── Step 0: VERIFY INCREMENT EXISTS (BLOCKING)
+  │     ├── Found? → Read master spec.md as source of truth
+  │     └── Missing? → Auto-invoke /sw:increment, wait for completion
+  ├── Step 1: Analyze feature (from master spec) -> identify domains -> decide increment split
   ├── Step 2: Create team via TeamCreate
-  ├── Step 3: Create per-domain increments
+  ├── Step 3: Create per-domain increments (derived from master spec)
   ├── Step 4: Contract-first spawning (all agents with mode: "bypassPermissions")
   │     ├── Phase 1: Spawn shared + database
   │     │     └── Receive PLAN_READY, review & approve via SendMessage (Section 3b)
@@ -753,9 +838,13 @@ Orchestrator Final Check:
   └── Step 7: Merge and close (/sw:team-merge)
 ```
 
+**IMPORTANT**: The intended entry point is: `/sw:increment` → `/sw:do` (detects 3+ domains) → `/sw:team-lead`.
+Direct invocation of `/sw:team-lead` without an existing increment will trigger the guard and auto-invoke `/sw:increment`.
+
 ### --dry-run Output
 
-When `--dry-run` is specified, display the proposed plan without executing:
+When `--dry-run` is specified, display the proposed plan without executing.
+**Do NOT call TeamCreate in dry-run mode** — just show the formatted plan text.
 
 ```
 Team Orchestration Plan (DRY RUN)
@@ -780,6 +869,7 @@ To execute, run without --dry-run.
 
 | Issue | Cause | Fix |
 |-------|-------|-----|
+| **TeamCreate blocked by guard** | No increment with spec.md exists | Run `/sw:increment "feature"` first, then retry `/sw:team-lead`. The guard requires a substantive spec.md (>200 bytes, not a template) |
 | **Agent stuck on trust folder** | Agent spawned without `bypassPermissions` | ALWAYS use `mode: "bypassPermissions"` — NEVER `mode: "plan"`. Trust prompts require interactive input agents cannot provide |
 | **Agents editing same files** | Overlapping file ownership patterns | Review ownership map; reassign conflicting files to a single owner; use `--dry-run` to validate before launch |
 | **Token cost too high** | Too many agents or overly large prompts | Reduce `--max-agents`; use `--domains` to limit scope; split feature into smaller increments |