specweave 1.0.235 → 1.0.239

package/plugins/specweave-github/lib/github-us-auto-closer.ts

@@ -0,0 +1,226 @@
+/**
+ * GitHub US Auto-Closer — Closes GitHub issues when all ACs are complete
+ *
+ * For each affected user story, checks if ALL acceptance criteria are
+ * marked complete in spec.md. If so, posts a completion comment and
+ * closes the associated GitHub issue.
+ *
+ * @module github-us-auto-closer
+ */
+
+import { readFile } from 'fs/promises';
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+
+export interface AutoCloseOptions {
+  owner: string;
+  repo: string;
+  token?: string;
+}
+
+export interface AutoCloseResult {
+  closed: Array<{ usId: string; issueNumber: number }>;
+  skipped: Array<{ usId: string; reason: string }>;
+  errors: Array<{ usId: string; error: string }>;
+}
+
+interface ParsedACState {
+  id: string;
+  description: string;
+  completed: boolean;
+}
+
+interface ParsedUSIssueLink {
+  issueNumber: number;
+  issueUrl: string;
+}
+
+/**
+ * Auto-close GitHub issues for user stories with all ACs complete.
+ *
+ * For each affected US:
+ * 1. Parse AC states from spec.md
+ * 2. Skip if not all ACs complete
+ * 3. Look up GitHub issue link from frontmatter
+ * 4. Check if issue already closed (idempotent)
+ * 5. Post completion comment
+ * 6. Close issue via `gh issue close`
+ *
+ * Never throws — all errors captured in result.errors.
+ */
+export async function autoCloseCompletedUserStories(
+  incrementId: string,
+  affectedUSIds: string[],
+  specPath: string,
+  options: AutoCloseOptions,
+): Promise<AutoCloseResult> {
+  const result: AutoCloseResult = { closed: [], skipped: [], errors: [] };
+
+  if (affectedUSIds.length === 0) {
+    return result;
+  }
+
+  let content: string;
+  try {
+    content = await readFile(specPath, 'utf-8');
+  } catch (err) {
+    result.errors.push({
+      usId: affectedUSIds[0],
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return result;
+  }
+
+  const issueLinks = parseIssueLinks(content);
+  const repoSlug = `${options.owner}/${options.repo}`;
+  const env = options.token ? { GH_TOKEN: options.token } : undefined;
+  const execOpts = env ? { env } : {};
+
+  for (const usId of affectedUSIds) {
+    const acStates = parseACStatesForUS(content, usId);
+
+    // Skip if not all ACs complete
+    if (acStates.length === 0 || acStates.some(ac => !ac.completed)) {
+      result.skipped.push({ usId, reason: 'incomplete-acs' });
+      continue;
+    }
+
+    // Skip if no issue link
+    const link = issueLinks[usId];
+    if (!link) {
+      result.skipped.push({ usId, reason: 'no-issue-link' });
+      continue;
+    }
+
+    const issueNum = String(link.issueNumber);
+
+    // Check if already closed (idempotent)
+    const viewResult = await execFileNoThrow(
+      'gh',
+      ['issue', 'view', issueNum, '--json', 'state', '-R', repoSlug],
+      execOpts,
+    );
+
+    if (viewResult.success) {
+      try {
+        const issueState = JSON.parse(viewResult.stdout);
+        if (issueState.state === 'CLOSED') {
+          result.skipped.push({ usId, reason: 'already-closed' });
+          continue;
+        }
+      } catch {
+        // Parse error — proceed with close attempt
+      }
+    }
+
+    // Post completion comment
+    const commentBody = buildCompletionComment(incrementId, usId, acStates);
+    await execFileNoThrow(
+      'gh',
+      ['issue', 'comment', issueNum, '--body', commentBody, '-R', repoSlug],
+      execOpts,
+    );
+
+    // Close the issue
+    const closeResult = await execFileNoThrow(
+      'gh',
+      ['issue', 'close', issueNum, '-R', repoSlug],
+      execOpts,
+    );
+
+    if (closeResult.success) {
+      result.closed.push({ usId, issueNumber: link.issueNumber });
+    } else {
+      result.errors.push({
+        usId,
+        error: closeResult.stderr || 'Unknown error closing issue',
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a completion comment for a fully-complete user story.
+ */
+function buildCompletionComment(
+  incrementId: string,
+  usId: string,
+  acStates: ParsedACState[],
+): string {
+  const total = acStates.length;
+
+  let comment = `**All acceptance criteria completed** — ${usId} (Increment ${incrementId})\n\n`;
+  comment += `**Status**: ${total}/${total} ACs complete (100%)\n\n`;
+
+  comment += `**Completed**:\n`;
+  for (const ac of acStates) {
+    comment += `- [x] **${ac.id}**: ${ac.description}\n`;
+  }
+  comment += '\n';
+
+  comment += `---\n`;
+  comment += `Auto-closed by SpecWeave | ${new Date().toISOString().split('T')[0]}\n`;
+
+  return comment;
+}
+
+/**
+ * Parse issue links from spec.md YAML frontmatter.
+ */
+function parseIssueLinks(content: string): Record<string, ParsedUSIssueLink> {
+  const links: Record<string, ParsedUSIssueLink> = {};
+
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return links;
+
+  const frontmatter = fmMatch[1];
+
+  const usBlockMatch = frontmatter.match(/userStories:\s*\n((?:\s{6,}[\s\S]*?)(?=\n\s{0,3}\S|$))/);
+  if (!usBlockMatch) return links;
+
+  const usBlock = usBlockMatch[1];
+  const usEntries = usBlock.match(/^\s+(US-\d+):\s*\n((?:\s+\w[\s\S]*?)(?=\n\s+US-|\s*$))/gm);
+
+  if (!usEntries) return links;
+
+  for (const entry of usEntries) {
+    const idMatch = entry.match(/(US-\d+):/);
+    const numMatch = entry.match(/issueNumber:\s*(\d+)/);
+    const urlMatch = entry.match(/issueUrl:\s*"([^"]+)"/);
+
+    if (idMatch && numMatch) {
+      links[idMatch[1]] = {
+        issueNumber: parseInt(numMatch[1], 10),
+        issueUrl: urlMatch ? urlMatch[1] : '',
+      };
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Extract AC states for a specific user story from spec.md content.
+ */
+function parseACStatesForUS(content: string, usId: string): ParsedACState[] {
+  const states: ParsedACState[] = [];
+  // AC IDs use unpadded US number: US-001 → AC-US1-XX
+  const usNum = String(parseInt(usId.replace('US-', ''), 10));
+
+  const acPattern = new RegExp(
+    `- \\[([ x])\\] \\*\\*AC-US${usNum}-(\\d+)\\*\\*:\\s*(.+)`,
+    'g',
+  );
+
+  let match;
+  while ((match = acPattern.exec(content)) !== null) {
+    states.push({
+      id: `AC-US${usNum}-${match[2]}`,
+      description: match[3].trim(),
+      completed: match[1] === 'x',
+    });
+  }
+
+  return states;
+}

package/plugins/specweave-github/lib/index.js

@@ -1,11 +1,5 @@
 import { GitHubClient } from "./github-client";
-import { TaskParser } from "./task-parser";
-import { TaskSync } from "./task-sync";
-import { SubtaskSync } from "./subtask-sync";
 export * from "./types";
 export {
-  GitHubClient,
-  SubtaskSync,
-  TaskParser,
-  TaskSync
+  GitHubClient
 };

package/plugins/specweave-github/lib/index.ts

@@ -1,10 +1,7 @@
 /**
  * SpecWeave GitHub Plugin - Library Entry Point
- * Task-level GitHub synchronization
+ * Spec-based GitHub synchronization
  */
 
 export { GitHubClient } from './github-client';
-export { TaskParser } from './task-parser';
-export { TaskSync } from './task-sync';
-export { SubtaskSync } from './subtask-sync';
 export * from './types';

package/plugins/specweave-github/skills/github-sync/SKILL.md

@@ -457,14 +457,86 @@ For monorepos with multiple GitHub repositories:
 
 ---
 
+## Projects V2 Integration (v3.0.0+)
+
+### Enabling Projects V2
+
+Add `projectV2Enabled: true` to your sync config:
+
+```json
+{
+  "sync": {
+    "profiles": {
+      "myproject": {
+        "provider": "github",
+        "config": {
+          "owner": "myorg",
+          "repo": "myrepo",
+          "projectV2Enabled": true,
+          "projectV2Number": 5
+        }
+      }
+    }
+  }
+}
+```
+
+### What Happens with V2 Enabled
+
+1. **Push sync** creates/updates GitHub issues (same as before)
+2. **Issues are added to Projects V2 board** automatically
+3. **Status field** is set based on user story status (planned/in-progress/completed)
+4. **Priority field** is set based on user story priority (P1-P4)
+
+### Custom Field Mappings
+
+```json
+{
+  "statusFieldMapping": {
+    "planned": "Todo",
+    "in-progress": "In Progress",
+    "completed": "Done"
+  },
+  "priorityFieldMapping": {
+    "P1": "Urgent",
+    "P2": "High",
+    "P3": "Medium",
+    "P4": "Low"
+  }
+}
+```
+
+### Pull Sync (GitHub to Spec)
+
+Pull sync fetches issue state and compares with spec ACs:
+- AC checkbox toggles on GitHub are detected and applied to spec
+- Issue close/reopen is detected as status change
+- Conflicts are detected when both spec and GitHub changed the same field
+
+### Batch Sync
+
+Sync all specs at once:
+- Discovers all `spec-*.md` files in `.specweave/docs/internal/specs/`
+- Syncs each sequentially
+- Reports summary with created/updated/failed counts
+
+### Cross-Repo Sync
+
+For distributed strategies, issues can be created in different repos:
+- User stories specify target repos via `targetRepos` field
+- Cross-references added: "Also tracked in: org/other-repo#XX"
+- All cross-repo issues added to shared org-level Projects V2 board
+
+---
+
 ## Related
 
-- **github-issue-tracker**: Track individual tasks as issue comments (DEPRECATED - use spec sync instead)
-- **github-manager agent**: AI agent for GitHub operations
+- **github-issue-tracker**: DEPRECATED - use spec sync instead
 - **Commands**: `/sw-github:sync-spec`, `/sw-github:import-project`, `/sw-github:status`
+- **Team Skills**: `/sw:team-orchestrate`, `/sw:team-status`, `/sw:team-merge`
 
 ---
 
-**Version**: 2.0.0 (Spec-based architecture)
+**Version**: 3.0.0 (Projects V2 + Pull Sync + Cross-Repo)
 **Plugin**: specweave-github
-**Last Updated**: 2025-11-11
+**Last Updated**: 2026-02-06

package/plugins/specweave-testing/commands/e2e-setup.md

@@ -8,6 +8,24 @@ Set up comprehensive Playwright E2E testing with best practices, page objects, a
 
 You are an expert E2E testing engineer who implements production-ready Playwright test suites.
 
+## CLI vs MCP Mode
+
+SpecWeave supports two modes for Playwright browser automation:
+
+- **@playwright/cli** (recommended for test execution): Token-efficient, file-based output, CI-friendly
+- **@playwright/mcp** (for interactive exploration): Rich inline snapshots, good for debugging
+
+Install CLI mode: `npm install -g @playwright/cli@latest`
+
+Configure preference in `.specweave/config.json`:
+```json
+{
+  "testing": {
+    "playwright": { "preferCli": true }
+  }
+}
+```
+
 ## Your Task
 
 Set up a complete Playwright E2E testing framework with page objects, fixtures, and testing patterns.

package/plugins/specweave-testing/commands/ui-automate.md

@@ -21,6 +21,8 @@ Create and execute automated browser workflows using Playwright. Generate script
 
 > **Why Code-First?** Anthropic research shows [code execution beats MCP tool calls](https://www.anthropic.com/engineering/code-execution-with-mcp) with 98% token reduction. Playwright code is reusable, committable, CI-runnable, and deterministic.
 
+> **CLI Mode Available**: When `@playwright/cli` is installed, this command routes to the CLI by default for maximum token efficiency (~250 chars per interaction vs ~5K+ via MCP). The CLI keeps browser state external and returns file references instead of inline DOM trees. Install: `npm install -g @playwright/cli@latest`
+
 ## Workflow Types
 
 ### 1. Form Automation

package/plugins/specweave-testing/commands/ui-inspect.md

@@ -63,6 +63,14 @@ Provides:
 - **Accessibility Audit**: Check element accessibility
 - **Bug Investigation**: Debug element behavior and properties
 
+## Browser Mode
+
+This command **prefers MCP mode** for rich DOM introspection. When the Playwright MCP plugin provides inline accessibility tree snapshots, the AI can reason about page structure and find optimal selectors.
+
+If MCP is unavailable, falls back to `@playwright/cli snapshot` which saves the accessibility tree to a file (`.playwright-cli/*.yml`). The AI can then read the file, but loses the ability to iterate on snapshots without re-reading.
+
+**Recommended**: Keep the Playwright MCP plugin installed for best `ui-inspect` experience.
+
 ## Requirements
 
 - Playwright browser binaries (auto-installed on first use)

package/plugins/specweave-testing/lib/playwright-ci-defaults.d.ts

@@ -0,0 +1,6 @@
+export type CiConfig = {
+    headed: boolean;
+    isCI: boolean;
+    outputDir: string;
+};
+export declare function getCiDefaults(options?: Partial<CiConfig>): CiConfig;

package/plugins/specweave-testing/lib/playwright-ci-defaults.js

@@ -0,0 +1,14 @@
+function isRunningInCI() {
+    return !!(process.env.CI === 'true' ||
+        process.env.GITHUB_ACTIONS === 'true' ||
+        process.env.GITLAB_CI === 'true' ||
+        process.env.JENKINS_URL);
+}
+export function getCiDefaults(options) {
+    const isCI = isRunningInCI();
+    return {
+        isCI,
+        headed: isCI ? false : (options?.headed ?? false),
+        outputDir: options?.outputDir ?? '.playwright-cli',
+    };
+}

package/plugins/specweave-testing/lib/playwright-ci-defaults.ts

@@ -0,0 +1,24 @@
+export type CiConfig = {
+  headed: boolean;
+  isCI: boolean;
+  outputDir: string;
+};
+
+function isRunningInCI(): boolean {
+  return !!(
+    process.env.CI === 'true' ||
+    process.env.GITHUB_ACTIONS === 'true' ||
+    process.env.GITLAB_CI === 'true' ||
+    process.env.JENKINS_URL
+  );
+}
+
+export function getCiDefaults(options?: Partial<CiConfig>): CiConfig {
+  const isCI = isRunningInCI();
+
+  return {
+    isCI,
+    headed: isCI ? false : (options?.headed ?? false),
+    outputDir: options?.outputDir ?? '.playwright-cli',
+  };
+}

package/plugins/specweave-testing/lib/playwright-cli-detector.js

@@ -0,0 +1,33 @@
+import { execSync } from "child_process";
+let cachedResult = null;
+function detectPlaywrightCli(options = {}) {
+  const { useCache = false } = options;
+  if (useCache && cachedResult) {
+    return cachedResult;
+  }
+  let path;
+  let version;
+  try {
+    path = execSync("which playwright-cli", {
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+  } catch {
+    const result2 = { installed: false };
+    if (useCache) cachedResult = result2;
+    return result2;
+  }
+  try {
+    version = execSync("playwright-cli --version", {
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+  } catch {
+  }
+  const result = { installed: true, path, version };
+  if (useCache) cachedResult = result;
+  return result;
+}
+export {
+  detectPlaywrightCli
+};

package/plugins/specweave-testing/lib/playwright-cli-detector.ts

@@ -0,0 +1,48 @@
+import { execSync } from 'child_process';
+
+export interface CliDetectionResult {
+  installed: boolean;
+  version?: string;
+  path?: string;
+}
+
+export interface DetectOptions {
+  useCache?: boolean;
+}
+
+let cachedResult: CliDetectionResult | null = null;
+
+export function detectPlaywrightCli(options: DetectOptions = {}): CliDetectionResult {
+  const { useCache = false } = options;
+
+  if (useCache && cachedResult) {
+    return cachedResult;
+  }
+
+  let path: string | undefined;
+  let version: string | undefined;
+
+  try {
+    path = execSync('which playwright-cli', {
+      encoding: 'utf-8',
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    const result: CliDetectionResult = { installed: false };
+    if (useCache) cachedResult = result;
+    return result;
+  }
+
+  try {
+    version = execSync('playwright-cli --version', {
+      encoding: 'utf-8',
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    // Version check failed but binary exists
+  }
+
+  const result: CliDetectionResult = { installed: true, path, version };
+  if (useCache) cachedResult = result;
+  return result;
+}

package/plugins/specweave-testing/lib/playwright-cli-runner.js

@@ -0,0 +1,58 @@
+import { execSync } from "child_process";
+class PlaywrightCliRunner {
+  constructor(config = {}) {
+    this.config = {
+      headed: config.headed ?? false,
+      browser: config.browser ?? "chrome",
+      session: config.session,
+      timeout: config.timeout ?? 3e4,
+      ...config
+    };
+  }
+  exec(command) {
+    const sessionFlag = this.config.session ? `-s=${this.config.session} ` : "";
+    const fullCommand = `playwright-cli ${sessionFlag}${command}`;
+    try {
+      const output = execSync(fullCommand, {
+        encoding: "utf-8",
+        timeout: this.config.timeout
+      }).trim();
+      return { ok: true, output };
+    } catch (e) {
+      return { ok: false, output: e.message };
+    }
+  }
+  open(url) {
+    const headedFlag = this.config.headed ? " --headed" : "";
+    const urlPart = url ? ` ${url}` : "";
+    return this.exec(`open${urlPart}${headedFlag}`);
+  }
+  navigate(url) {
+    return this.exec(`goto ${url}`);
+  }
+  snapshot() {
+    return this.exec("snapshot");
+  }
+  screenshot(filename) {
+    const flag = filename ? ` --filename ${filename}` : "";
+    return this.exec(`screenshot${flag}`);
+  }
+  close() {
+    return this.exec("close");
+  }
+  click(ref) {
+    return this.exec(`click ${ref}`);
+  }
+  type(text) {
+    return this.exec(`type "${text}"`);
+  }
+  fill(ref, text) {
+    return this.exec(`fill ${ref} "${text}"`);
+  }
+  evaluate(fn) {
+    return this.exec(`eval "${fn}"`);
+  }
+}
+export {
+  PlaywrightCliRunner
+};

package/plugins/specweave-testing/lib/playwright-cli-runner.ts

@@ -0,0 +1,80 @@
+import { execSync } from 'child_process';
+
+export interface CliRunnerConfig {
+  headed?: boolean;
+  browser?: string;
+  session?: string;
+  timeout?: number;
+}
+
+export interface CliResult {
+  ok: boolean;
+  output: string;
+}
+
+export class PlaywrightCliRunner {
+  readonly config: Required<Pick<CliRunnerConfig, 'headed' | 'browser'>> & CliRunnerConfig;
+
+  constructor(config: CliRunnerConfig = {}) {
+    this.config = {
+      headed: config.headed ?? false,
+      browser: config.browser ?? 'chrome',
+      session: config.session,
+      timeout: config.timeout ?? 30_000,
+      ...config,
+    };
+  }
+
+  private exec(command: string): CliResult {
+    const sessionFlag = this.config.session ? `-s=${this.config.session} ` : '';
+    const fullCommand = `playwright-cli ${sessionFlag}${command}`;
+    try {
+      const output = execSync(fullCommand, {
+        encoding: 'utf-8',
+        timeout: this.config.timeout,
+      }).trim();
+      return { ok: true, output };
+    } catch (e: unknown) {
+      return { ok: false, output: (e as Error).message };
+    }
+  }
+
+  open(url?: string): CliResult {
+    const headedFlag = this.config.headed ? ' --headed' : '';
+    const urlPart = url ? ` ${url}` : '';
+    return this.exec(`open${urlPart}${headedFlag}`);
+  }
+
+  navigate(url: string): CliResult {
+    return this.exec(`goto ${url}`);
+  }
+
+  snapshot(): CliResult {
+    return this.exec('snapshot');
+  }
+
+  screenshot(filename?: string): CliResult {
+    const flag = filename ? ` --filename ${filename}` : '';
+    return this.exec(`screenshot${flag}`);
+  }
+
+  close(): CliResult {
+    return this.exec('close');
+  }
+
+  click(ref: string): CliResult {
+    return this.exec(`click ${ref}`);
+  }
+
+  type(text: string): CliResult {
+    return this.exec(`type "${text}"`);
+  }
+
+  fill(ref: string, text: string): CliResult {
+    return this.exec(`fill ${ref} "${text}"`);
+  }
+
+  evaluate(fn: string): CliResult {
+    return this.exec(`eval "${fn}"`);
+  }
+}

package/plugins/specweave-testing/lib/playwright-routing.js

@@ -0,0 +1,16 @@
+import { detectPlaywrightCli } from "./playwright-cli-detector.js";
+const MCP_PREFERRED_TASKS = /* @__PURE__ */ new Set([
+  "ui-inspect",
+  "page-exploration",
+  "self-healing-test"
+]);
+function resolvePlaywrightMode(task, config = {}) {
+  const { preferCli = true } = config;
+  if (!preferCli) return "mcp";
+  const detection = detectPlaywrightCli({ useCache: true });
+  if (!detection.installed) return "mcp";
+  return MCP_PREFERRED_TASKS.has(task) ? "mcp" : "cli";
+}
+export {
+  resolvePlaywrightMode
+};