specweave 0.21.2 → 0.22.0

package/plugins/specweave-ui/.mcp.json

@@ -5,16 +5,6 @@
       "args": ["-y", "@playwright/mcp@latest"],
       "description": "Local Playwright browser automation - PRIMARY choice for E2E testing and web interaction",
       "optional": false
-    },
-    "browserbase": {
-      "command": "npx",
-      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
-      "env": {
-        "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
-        "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
-      },
-      "description": "Cloud browser automation for running Playwright tests in scalable infrastructure - FALLBACK option",
-      "optional": true
     }
   }
 }

package/plugins/specweave-ui/README.md

@@ -292,9 +292,9 @@ mcp__plugin_specweave-ui_playwright__browser_fill({
 
 ---
 
-### Browserbase (FALLBACK - Cloud Browser Automation)
+### Browserbase (OPTIONAL - Cloud Browser Automation)
 
-**⚠️ Use only when Playwright MCP unavailable (CI/CD, cloud scenarios)**
+**⚠️ NOT loaded by default. Enable only when needed for CI/CD or cloud scenarios.**
 
 **What it does**:
 - Runs Playwright tests in cloud infrastructure
@@ -302,7 +302,7 @@ mcp__plugin_specweave-ui_playwright__browser_fill({
 - No local browser dependencies in CI
 - Automatic screenshots/videos
 
-**Setup**:
+**Manual Setup** (when needed):
 
 1. Get API key from [Browserbase](https://www.browserbase.com/)
 
@@ -312,26 +312,29 @@ mcp__plugin_specweave-ui_playwright__browser_fill({
    export BROWSERBASE_PROJECT_ID="proj_xxx"
    ```
 
-3. SpecWeave auto-configures MCP server (via `.mcp.json`)
+3. **Add to your project's `.claude/settings.json`**:
+   ```json
+   {
+     "mcpServers": {
+       "browserbase": {
+         "command": "npx",
+         "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
+         "env": {
+           "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
+           "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
+         }
+       }
+     }
+   }
+   ```
 
-4. Use in CI/CD pipelines
+4. Restart Claude Code
 
-**Configuration** (`.mcp.json`):
-```json
-{
-  "mcpServers": {
-    "browserbase": {
-      "command": "npx",
-      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
-      "env": {
-        "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
-        "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
-      },
-      "optional": true
-    }
-  }
-}
-```
+**Why not auto-loaded?**
+- Saves ~5,600 tokens per request
+- Most developers use Playwright locally, not Browserbase
+- Browserbase requires API keys (not needed for most users)
+- Can still enable when needed for CI/CD
 
 **Benefits**:
 - ✅ Parallel execution (10x faster)
@@ -392,11 +395,6 @@ npm run storybook
   "plugins": {
     "specweave-ui": {
       "enabled": true,
-      "mcp": {
-        "browserbase": {
-          "enabled": false
-        }
-      },
       "defaults": {
         "frontend_framework": "react",  // or "vue", "angular"
         "test_framework": "playwright",
@@ -407,6 +405,8 @@ npm run storybook
 }
 ```
 
+**Note**: Browserbase is NOT auto-loaded. See "Browserbase (OPTIONAL)" section above for manual setup.
+
 ---
 
 ## FAQ

package/plugins/specweave-ui/skills/browser-automation/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: browser-automation
 description: |
-  Browser automation and E2E testing using Playwright MCP (primary) or Browserbase (fallback).
+  Browser automation and E2E testing using Playwright MCP (always available).
   Auto-activates for: browser automation, web testing, E2E tests, Playwright, browser interaction,
   scraping, testing flows, user journeys, accessibility testing, screenshot capture.
 
   CRITICAL: ALWAYS use Playwright MCP (mcp__plugin_specweave-ui_playwright__*) as PRIMARY choice.
-  Only use Browserbase (mcp__plugin_specweave-ui_browserbase__*) as FALLBACK when Playwright unavailable.
+
+  NOTE: Browserbase tools (mcp__plugin_specweave-ui_browserbase__*) are NOT loaded by default.
+  They require manual setup and are only for CI/CD or cloud scenarios.
 allowed-tools:
   - mcp__plugin_specweave-ui_playwright__*
   - mcp__plugin_specweave-ui_browserbase__*
@@ -133,9 +135,11 @@ browser_console_messages()
 browser_close()
 ```
 
-### 2. Browserbase Integration (FALLBACK - Cloud Testing)
+### 2. Browserbase Integration (OPTIONAL - Cloud Testing)
+
+**⚠️ NOT LOADED BY DEFAULT - Manual setup required!**
 
-**⚠️ ONLY USE AS FALLBACK when Playwright MCP unavailable!**
+**Note**: Browserbase is NOT auto-loaded to save ~5,600 tokens per request. Enable only when needed for CI/CD or cloud scenarios.
 
 Browserbase provides cloud-based browser automation:
 
@@ -148,6 +152,8 @@ Browserbase provides cloud-based browser automation:
 
 #### Available Tools (mcp__plugin_specweave-ui_browserbase__*)
 
+**Note**: These tools are ONLY available after manual setup.
+
 - **browserbase_session_create** - Create cloud session
 - **browserbase_session_close** - Close session
 - **browserbase_stagehand_navigate** - Navigate to URL
@@ -158,7 +164,7 @@ Browserbase provides cloud-based browser automation:
 - **browserbase_stagehand_get_url** - Get current URL
 - **browserbase_stagehand_agent** - Run autonomous task
 
-#### Setup Requirements
+#### Manual Setup (when needed)
 
 1. Get API credentials from [Browserbase](https://www.browserbase.com/)
 2. Set environment variables:
@@ -166,7 +172,22 @@ Browserbase provides cloud-based browser automation:
    export BROWSERBASE_API_KEY="bb_xxx"
    export BROWSERBASE_PROJECT_ID="proj_xxx"
    ```
-3. Configuration is in `.mcp.json`
+3. Add to `.claude/settings.json`:
+   ```json
+   {
+     "mcpServers": {
+       "browserbase": {
+         "command": "npx",
+         "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
+         "env": {
+           "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
+           "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
+         }
+       }
+     }
+   }
+   ```
+4. Restart Claude Code
 
 #### Testing Workflow (Browserbase)
 
@@ -398,30 +419,22 @@ Are you running locally (dev machine or VM)?
 
 ## Configuration Files
 
-### .mcp.json (Plugin-Level)
+### .mcp.json (Plugin-Level - Auto-Loaded)
 ```json
 {
   "mcpServers": {
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@latest"],
+      "args": ["-y", "@playwright/mcp@latest"],
       "description": "Local Playwright - PRIMARY",
       "optional": false
-    },
-    "browserbase": {
-      "command": "npx",
-      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
-      "env": {
-        "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
-        "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
-      },
-      "description": "Cloud Browserbase - FALLBACK",
-      "optional": true
     }
   }
 }
 ```
 
+**Note**: Browserbase is NOT in `.mcp.json` (not auto-loaded). To enable Browserbase, add it to your project's `.claude/settings.json` as shown in the "Manual Setup" section above.
+
 ### playwright.config.ts (Project-Level)
 ```typescript
 import { defineConfig } from '@playwright/test';

package/src/templates/AGENTS.md.template

@@ -207,15 +207,36 @@ This is a **SpecWeave project** where specifications and documentation are the s
 ```
 ⛔ NEVER pollute project root with .md files!
 ⛔ Increment IDs must be unique (0001-9999)!
-⛔ All reports/scripts/logs go in increment folders!
+⛔ ONLY 3 files in increment root: spec.md, plan.md, tasks.md
+⛔ All reports/scripts/logs go in increment subfolders!
 ⛔ Always check: git status (before committing)!
 ```
 
 #### File Organization {#file-organization}
+
+**Increment Structure (MANDATORY)**:
+```
+.specweave/increments/0001-feature/
+├── spec.md              # ⚠️ ONLY THESE 3 FILES in root!
+├── plan.md
+├── tasks.md
+├── reports/             # ✅ ALL REPORTS HERE
+│   ├── SESSION-*.md
+│   ├── QUICK-START.md
+│   ├── ULTRATHINK-*.md
+│   └── ANALYSIS-*.md
+├── scripts/             # ✅ ALL SCRIPTS HERE
+│   └── *.{py,sh,ts}
+└── logs/                # ✅ ALL LOGS HERE
+    └── *.log
+```
+
+**File Placement Rules**:
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ NEVER in Root           ↔ ALWAYS in Increment Folder      │
 ├────────────────────────────────────────────────────────────┤
+│ ❌ QUICK-START.md       ↔ ✅ .../0001/reports/QUICK-START  │
 │ ❌ analysis.md          ↔ ✅ .../0001/reports/analysis.md  │
 │ ❌ migration.py         ↔ ✅ .../0001/scripts/migration.py │
 │ ❌ execution.log        ↔ ✅ .../0001/logs/execution.log   │

package/src/templates/tasks.md.template

@@ -23,16 +23,33 @@ Use this template for each task:
 **Priority**: P0 | P1 | P2 | P3
 **Estimate**: X hours
 **Status**: pending | in_progress | completed | blocked
+**AC-IDs**: AC-US-XXX-YY (links to spec.md acceptance criteria)
 **GitHub Issue**: #NNN (auto-populated after sync)
 **Assignee**: @username (optional)
 
 **Description**:
 Brief description of what this task accomplishes.
 
-**Subtasks** (optional):
-- [ ] S-XXX-01: Subtask description (Xmin)
-- [ ] S-XXX-02: Subtask description (Xmin)
-- [ ] S-XXX-03: Subtask description (Xmin)
+**Implementation**:
+- [ ] Create/update ClassName with method()
+- [ ] Implement core feature logic
+- [ ] Add error handling for edge cases
+- [ ] Add JSDoc comments
+- [ ] Update related type definitions
+
+**Test Plan** (BDD):
+- **Given** [precondition describing initial state]
+- **When** [action or event that triggers behavior]
+- **Then** [expected result or outcome]
+
+**Test Cases**:
+- Unit (`class-name.test.ts`):
+  - method_withValidInput_returnsExpectedResult
+  - method_withInvalidInput_throwsError
+  - Coverage: >95%
+- Integration (`feature.integration.test.ts`):
+  - fullWorkflow_happyPath_succeeds
+  - Coverage: >85%
 
 **Files to Create** (if applicable):
 - `path/to/new/file.ts`
@@ -42,20 +59,15 @@ Brief description of what this task accomplishes.
 - `path/to/existing/file.ts`
 - `path/to/another/existing.md`
 
-**Implementation** (optional - code snippets, examples):
+**Code Examples** (optional - snippets for clarity):
 ```typescript
-// Example implementation
+// Example implementation approach
 export function exampleFunction() {
   // Code here
 }
 ```
 ```
 
-**Acceptance Criteria**:
-- ✅ Criterion 1
-- ✅ Criterion 2
-- ✅ Criterion 3
-
 **Dependencies** (optional - tasks that must complete first):
 - T-001 (must complete first)
 - T-002 (must complete first)
@@ -75,25 +87,40 @@ export function exampleFunction() {
 **Priority**: P0
 **Estimate**: 2 hours
 **Status**: pending
+**AC-IDs**: AC-US1-01, AC-US1-02
 **GitHub Issue**: (will be populated after sync)
 **Assignee**: (assign in GitHub after sync)
 
 **Description**:
-This is an example task showing the enhanced template format with GitHub sync fields.
+This is an example task showing the canonical template format following ADR-0047.
 
-**Subtasks**:
-- [ ] S-001-01: First subtask (30min)
-- [ ] S-001-02: Second subtask (45min)
-- [ ] S-001-03: Third subtask (30min)
-- [ ] S-001-04: Final polish (15min)
+**Implementation**:
+- [ ] Define ExampleInterface with id and name fields
+- [ ] Create ExampleClass implementing ExampleInterface
+- [ ] Add constructor with parameter properties
+- [ ] Add JSDoc comments for interface and class
+- [ ] Export both interface and class
+
+**Test Plan** (BDD):
+- **Given** ExampleClass constructor receives valid id and name
+- **When** new ExampleClass('123', 'Test') is instantiated
+- **Then** instance has correct id and name properties
+
+**Test Cases**:
+- Unit (`example-class.test.ts`):
+  - constructor_withValidParams_createsInstance
+  - constructor_withEmptyId_throwsError
+  - interface_conformsToContract
+  - Coverage: >95%
 
 **Files to Create**:
 - `src/example/new-file.ts`
+- `tests/unit/example/example-class.test.ts`
 
 **Files to Modify**:
 - `src/example/existing-file.ts`
 
-**Implementation**:
+**Code Examples**:
 ```typescript
 export interface ExampleInterface {
   id: string;
@@ -105,12 +132,6 @@ export class ExampleClass implements ExampleInterface {
 }
 ```
 
-**Acceptance Criteria**:
-- ✅ All interfaces defined
-- ✅ TypeScript compiles without errors
-- ✅ Unit tests pass
-- ✅ Documentation comments added
-
 **Dependencies**:
 None (foundation task)
 
@@ -231,22 +252,19 @@ As you work on tasks:
 - **Priority**: P0 (critical), P1 (high), P2 (medium), P3 (low)
 - **Estimate**: Hours or days (e.g., "2 hours", "3 days")
 - **Status**: pending, in_progress, completed, blocked
+- **AC-IDs**: Links to spec.md acceptance criteria (e.g., "AC-US1-01, AC-US1-02")
 - **Description**: What this task accomplishes
-- **Acceptance Criteria**: How we know it's done
+- **Implementation**: Checkable technical steps to complete the task
+- **Test Plan (BDD)**: Given-When-Then test scenarios
+- **Test Cases**: Unit and integration test cases with coverage targets
 
 ### Optional Fields (Enhanced for GitHub Sync)
 - **GitHub Issue**: Auto-populated after `/specweave.github.sync-tasks`
 - **Assignee**: GitHub username (assign in GitHub UI or via `@username`)
-- **Subtasks**: Granular steps (15-60min each, shown as checkboxes in GitHub)
 - **Dependencies**: Tasks that must complete first (linked in GitHub via "depends on")
 - **Blocks**: Tasks waiting on this one (linked in GitHub via "blocks")
-- **Files to Create/Modify**: Context for reviewers
-- **Implementation**: Code snippets, examples, pseudocode
-
-### Subtask Naming Convention
-- Format: `S-{TASK_ID}-{SUBTASK_NUM}: Description (time)`
-- Example: `S-001-01: Define interfaces (30min)`
-- Numbering: Zero-padded 2 digits (01, 02, 03, ...)
+- **Files to Create/Modify**: Context for reviewers and developers
+- **Code Examples**: Snippets showing implementation approach (TypeScript, pseudocode, etc.)
 
 ### Task Status Lifecycle
 1. **pending** - Not started, in backlog

package/dist/plugins/specweave/lib/hooks/git-diff-analyzer.d.ts

@@ -1,89 +0,0 @@
-/**
- * Git Diff Analyzer
- *
- * Extracts modified files from git diff for reflection analysis
- * Parses git diff output to get file changes, line counts, and content
- *
- * @module git-diff-analyzer
- */
-import { GitDiffInfo } from './types/reflection-types';
-/**
- * Check if directory is a git repository
- * @param dir Directory to check (defaults to cwd)
- * @returns True if directory is in a git repository
- */
-export declare function isGitRepository(dir?: string): boolean;
-/**
- * Get list of modified files in the working directory
- * Includes both staged and unstaged changes
- *
- * @param cwd Working directory (optional, defaults to process.cwd())
- * @returns Array of file paths relative to git root
- */
-export declare function getModifiedFilesList(cwd?: string): string[];
-/**
- * Parse git diff numstat output to get line counts
- * Format: <added>\t<removed>\t<filename>
- *
- * @param numstatOutput Output from git diff --numstat
- * @returns Map of filename to {added, removed} counts
- */
-export declare function parseNumstat(numstatOutput: string): Map<string, {
-    added: number;
-    removed: number;
-}>;
-/**
- * Get diff content for a specific file
- * @param file File path relative to git root
- * @param cwd Working directory (optional)
- * @returns Diff content as string
- */
-export declare function getFileDiff(file: string, cwd?: string): string;
-/**
- * Get current file content
- * @param file File path (can be absolute or relative to cwd)
- * @param cwd Working directory (optional)
- * @returns File content as string, or empty string if file doesn't exist
- */
-export declare function getFileContent(file: string, cwd?: string): string;
-/**
- * Get modified files with diff information
- * Main function for reflection analysis
- *
- * @param cwd Working directory (optional, defaults to process.cwd())
- * @param maxFiles Maximum number of files to return (optional, defaults to 100)
- * @returns Array of GitDiffInfo objects with file changes
- */
-export declare function getModifiedFiles(cwd?: string, maxFiles?: number): GitDiffInfo[];
-/**
- * Get summary statistics for modified files
- * Useful for reflection metadata
- *
- * @param modifiedFiles Array of GitDiffInfo objects
- * @returns Summary with file count, total lines added/removed
- */
-export declare function getModifiedFilesSummary(modifiedFiles: GitDiffInfo[]): {
-    count: number;
-    linesAdded: number;
-    linesRemoved: number;
-    totalChanges: number;
-};
-/**
- * Filter files by extension
- * Useful for focusing reflection on specific file types
- *
- * @param modifiedFiles Array of GitDiffInfo objects
- * @param extensions Array of file extensions (e.g., ['.ts', '.js'])
- * @returns Filtered array of GitDiffInfo objects
- */
-export declare function filterFilesByExtension(modifiedFiles: GitDiffInfo[], extensions: string[]): GitDiffInfo[];
-/**
- * Exclude files matching patterns
- * Useful for excluding generated files, test files, etc.
- *
- * @param modifiedFiles Array of GitDiffInfo objects
- * @param patterns Array of glob patterns to exclude
- * @returns Filtered array of GitDiffInfo objects
- */
-export declare function excludeFilesByPattern(modifiedFiles: GitDiffInfo[], patterns: string[]): GitDiffInfo[];
-//# sourceMappingURL=git-diff-analyzer.d.ts.map

package/dist/plugins/specweave/lib/hooks/git-diff-analyzer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"git-diff-analyzer.d.ts","sourceRoot":"","sources":["../../../../../plugins/specweave/lib/hooks/git-diff-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAqBvD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAOpE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAqB3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBnG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAY9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAajE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAY,GACrB,WAAW,EAAE,CA8Cf;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,WAAW,EAAE,GAAG;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB,CAUA;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,WAAW,EAAE,EAC5B,UAAU,EAAE,MAAM,EAAE,GACnB,WAAW,EAAE,CAKf;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,WAAW,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAAE,GACjB,WAAW,EAAE,CAQf"}