specweave 0.28.0 → 0.28.1

package/plugins/specweave-github/lib/github-feature-sync-cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "fs";
+import * as path from "path";
+import { GitHubFeatureSync } from "./github-feature-sync.js";
+import { GitHubClientV2 } from "./github-client-v2.js";
+async function loadGitHubConfig() {
+  const projectRoot = process.cwd();
+  const configPath = path.join(projectRoot, ".specweave/config.json");
+  let owner = process.env.GITHUB_OWNER || "";
+  let repo = process.env.GITHUB_REPO || "";
+  const token = process.env.GITHUB_TOKEN || "";
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (config.sync?.github?.owner && config.sync?.github?.repo) {
+        owner = config.sync.github.owner;
+        repo = config.sync.github.repo;
+      } else if (config.multiProject?.enabled && config.multiProject?.activeProject) {
+        const activeProject = config.multiProject.activeProject;
+        const projectConfig = config.multiProject.projects?.[activeProject];
+        if (projectConfig?.externalTools?.github?.repository) {
+          const parts = projectConfig.externalTools.github.repository.split("/");
+          if (parts.length === 2) {
+            owner = parts[0];
+            repo = parts[1];
+          }
+        }
+      } else if (config.sync?.activeProfile && config.sync?.profiles) {
+        const profile = config.sync.profiles[config.sync.activeProfile];
+        if (profile?.config?.owner && profile?.config?.repo) {
+          owner = profile.config.owner;
+          repo = profile.config.repo;
+        }
+      }
+    } catch (error) {
+      console.error("\u26A0\uFE0F  Failed to parse config.json:", error);
+    }
+  }
+  if (!owner || !repo) {
+    try {
+      const { execSync } = await import("child_process");
+      const remoteUrl = execSync("git remote get-url origin 2>/dev/null", {
+        encoding: "utf-8",
+        cwd: projectRoot
+      }).trim();
+      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+      if (match) {
+        owner = owner || match[1];
+        repo = repo || match[2];
+      }
+    } catch {
+    }
+  }
+  if (!token) {
+    console.error("\u274C GITHUB_TOKEN not set");
+    console.error("   Set it in .env file or export GITHUB_TOKEN=ghp_xxx");
+    return null;
+  }
+  if (!owner || !repo) {
+    console.error("\u274C Could not detect GitHub owner/repo");
+    console.error("   Set sync.github.owner and sync.github.repo in .specweave/config.json");
+    return null;
+  }
+  return { owner, repo, token };
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    console.log("Usage: node github-feature-sync-cli.js <feature-id>");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  feature-id   Feature ID (e.g., FS-062)");
+    console.log("");
+    console.log("Environment:");
+    console.log("  GITHUB_TOKEN  Required - GitHub personal access token");
+    console.log("");
+    console.log("Example:");
+    console.log("  GITHUB_TOKEN=ghp_xxx node github-feature-sync-cli.js FS-062");
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const featureId = args[0];
+  if (!featureId.match(/^FS-\d+$/i)) {
+    console.error(`\u274C Invalid feature ID: ${featureId}`);
+    console.error("   Expected format: FS-XXX (e.g., FS-062)");
+    process.exit(1);
+  }
+  console.log(`
+\u{1F419} GitHub Feature Sync CLI`);
+  console.log(`   Feature: ${featureId}`);
+  const config = await loadGitHubConfig();
+  if (!config) {
+    process.exit(1);
+  }
+  console.log(`   Repository: ${config.owner}/${config.repo}`);
+  const projectRoot = process.cwd();
+  const specsDir = path.join(projectRoot, ".specweave/docs/internal/specs");
+  const profile = {
+    provider: "github",
+    displayName: "GitHub",
+    config: {
+      owner: config.owner,
+      repo: config.repo,
+      token: config.token
+    },
+    timeRange: {
+      default: "1M",
+      max: "3M"
+    }
+  };
+  const client = new GitHubClientV2(profile);
+  const sync = new GitHubFeatureSync(client, specsDir, projectRoot);
+  try {
+    console.log(`
+\u{1F504} Syncing ${featureId} to GitHub...`);
+    const result = await sync.syncFeatureToGitHub(featureId);
+    console.log(`
+\u2705 Sync complete!`);
+    console.log(`   \u{1F3AF} Milestone: #${result.milestoneNumber}`);
+    console.log(`   \u{1F4DD} Issues created: ${result.issuesCreated}`);
+    console.log(`   \u{1F504} Issues updated: ${result.issuesUpdated}`);
+    console.log(`   \u{1F4DA} User stories processed: ${result.userStoriesProcessed}`);
+    if (result.milestoneUrl) {
+      console.log(`   \u{1F517} ${result.milestoneUrl}`);
+    }
+    process.exit(0);
+  } catch (error) {
+    console.error(`
+\u274C Sync failed:`, error);
+    process.exit(1);
+  }
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/plugins/specweave-github/lib/github-feature-sync-cli.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * GitHub Feature Sync CLI
+ *
+ * CLI wrapper for GitHubFeatureSync.syncFeatureToGitHub()
+ * Called by post-increment-planning.sh hook to create GitHub issues
+ * after increment creation.
+ *
+ * Usage:
+ *   node github-feature-sync-cli.js <feature-id>
+ *   node github-feature-sync-cli.js FS-062
+ *
+ * Environment:
+ *   GITHUB_TOKEN - Required
+ *   GITHUB_OWNER - Optional (detected from config.json or git remote)
+ *   GITHUB_REPO  - Optional (detected from config.json or git remote)
+ *
+ * @see ADR-0139 (Unified Post-Increment Sync)
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import * as path from 'path';
+import { GitHubFeatureSync } from './github-feature-sync.js';
+import { GitHubClientV2 } from './github-client-v2.js';
+
+interface GitHubConfig {
+  owner: string;
+  repo: string;
+  token: string;
+}
+
+async function loadGitHubConfig(): Promise<GitHubConfig | null> {
+  const projectRoot = process.cwd();
+  const configPath = path.join(projectRoot, '.specweave/config.json');
+
+  let owner = process.env.GITHUB_OWNER || '';
+  let repo = process.env.GITHUB_REPO || '';
+  const token = process.env.GITHUB_TOKEN || '';
+
+  // Try to load from config.json
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+      // Method 1: sync.github
+      if (config.sync?.github?.owner && config.sync?.github?.repo) {
+        owner = config.sync.github.owner;
+        repo = config.sync.github.repo;
+      }
+      // Method 2: multiProject.projects[activeProject].externalTools.github
+      else if (config.multiProject?.enabled && config.multiProject?.activeProject) {
+        const activeProject = config.multiProject.activeProject;
+        const projectConfig = config.multiProject.projects?.[activeProject];
+        if (projectConfig?.externalTools?.github?.repository) {
+          const parts = projectConfig.externalTools.github.repository.split('/');
+          if (parts.length === 2) {
+            owner = parts[0];
+            repo = parts[1];
+          }
+        }
+      }
+      // Method 3: sync.profiles[activeProfile]
+      else if (config.sync?.activeProfile && config.sync?.profiles) {
+        const profile = config.sync.profiles[config.sync.activeProfile];
+        if (profile?.config?.owner && profile?.config?.repo) {
+          owner = profile.config.owner;
+          repo = profile.config.repo;
+        }
+      }
+    } catch (error) {
+      console.error('⚠️  Failed to parse config.json:', error);
+    }
+  }
+
+  // Fallback: detect from git remote
+  if (!owner || !repo) {
+    try {
+      const { execSync } = await import('child_process');
+      const remoteUrl = execSync('git remote get-url origin 2>/dev/null', {
+        encoding: 'utf-8',
+        cwd: projectRoot
+      }).trim();
+
+      // Parse GitHub URL (HTTPS or SSH)
+      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+      if (match) {
+        owner = owner || match[1];
+        repo = repo || match[2];
+      }
+    } catch {
+      // Git detection failed, continue with what we have
+    }
+  }
+
+  if (!token) {
+    console.error('❌ GITHUB_TOKEN not set');
+    console.error('   Set it in .env file or export GITHUB_TOKEN=ghp_xxx');
+    return null;
+  }
+
+  if (!owner || !repo) {
+    console.error('❌ Could not detect GitHub owner/repo');
+    console.error('   Set sync.github.owner and sync.github.repo in .specweave/config.json');
+    return null;
+  }
+
+  return { owner, repo, token };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log('Usage: node github-feature-sync-cli.js <feature-id>');
+    console.log('');
+    console.log('Arguments:');
+    console.log('  feature-id   Feature ID (e.g., FS-062)');
+    console.log('');
+    console.log('Environment:');
+    console.log('  GITHUB_TOKEN  Required - GitHub personal access token');
+    console.log('');
+    console.log('Example:');
+    console.log('  GITHUB_TOKEN=ghp_xxx node github-feature-sync-cli.js FS-062');
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  const featureId = args[0];
+
+  // Validate feature ID format
+  if (!featureId.match(/^FS-\d+$/i)) {
+    console.error(`❌ Invalid feature ID: ${featureId}`);
+    console.error('   Expected format: FS-XXX (e.g., FS-062)');
+    process.exit(1);
+  }
+
+  console.log(`\n🐙 GitHub Feature Sync CLI`);
+  console.log(`   Feature: ${featureId}`);
+
+  // Load config
+  const config = await loadGitHubConfig();
+  if (!config) {
+    process.exit(1);
+  }
+
+  console.log(`   Repository: ${config.owner}/${config.repo}`);
+
+  // Create client and sync
+  const projectRoot = process.cwd();
+  const specsDir = path.join(projectRoot, '.specweave/docs/internal/specs');
+
+  const profile = {
+    provider: 'github' as const,
+    displayName: 'GitHub',
+    config: {
+      owner: config.owner,
+      repo: config.repo,
+      token: config.token
+    },
+    timeRange: {
+      default: '1M' as const,
+      max: '3M' as const
+    }
+  };
+
+  const client = new GitHubClientV2(profile);
+  const sync = new GitHubFeatureSync(client, specsDir, projectRoot);
+
+  try {
+    console.log(`\n🔄 Syncing ${featureId} to GitHub...`);
+
+    const result = await sync.syncFeatureToGitHub(featureId);
+
+    console.log(`\n✅ Sync complete!`);
+    console.log(`   🎯 Milestone: #${result.milestoneNumber}`);
+    console.log(`   📝 Issues created: ${result.issuesCreated}`);
+    console.log(`   🔄 Issues updated: ${result.issuesUpdated}`);
+    console.log(`   📚 User stories processed: ${result.userStoriesProcessed}`);
+
+    if (result.milestoneUrl) {
+      console.log(`   🔗 ${result.milestoneUrl}`);
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(`\n❌ Sync failed:`, error);
+    process.exit(1);
+  }
+}
+
+// Run CLI
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/plugins/specweave-github/skills/github-issue-standard/SKILL.md

@@ -11,6 +11,49 @@ description: Standard format for ALL GitHub issues created by SpecWeave. Ensures
 - Increments (0001-* folders)
 - Specs (spec-*.md files)
 
+## Issue Title Format (MANDATORY)
+
+### ✅ ONLY Allowed Title Formats
+
+```
+[FS-XXX][US-YYY] User Story Title    ← STANDARD (User Stories)
+[FS-XXX] Feature Title               ← Rare (Feature-level only)
+```
+
+**Examples**:
+- ✅ `[FS-059][US-003] Hook Optimization (P0)`
+- ✅ `[FS-054][US-001] Fix Reopen Desync Bug (P0)`
+- ✅ `[FS-048] Smart Pagination Feature`
+
+### ❌ PROHIBITED Title Formats (NEVER USE)
+
+```
+[BUG] Title                          ← WRONG! Bug is a LABEL, not title prefix
+[HOTFIX] Title                       ← WRONG! Hotfix is a LABEL
+[FEATURE] Title                      ← WRONG! Feature is a LABEL
+[DOCS] Title                         ← WRONG! Docs is a LABEL
+[Increment XXXX] Title               ← DEPRECATED! Old format
+```
+
+**Why?** Type-based prefixes like `[BUG]` break traceability:
+- Cannot link to Feature Spec (FS-XXX)
+- Cannot link to User Story (US-YYY)
+- Violates SpecWeave's data flow: `Increment → Living Docs → GitHub`
+
+**What to do instead?**
+1. Link work to a Feature (FS-XXX) in living docs
+2. Create User Story (US-YYY) under that feature
+3. Use GitHub **labels** for categorization: `bug`, `enhancement`, `hotfix`
+
+### Validation
+
+The GitHub client (`github-client-v2.ts`) enforces this:
+- Rejects titles starting with `[BUG]`, `[HOTFIX]`, `[FEATURE]`, etc.
+- Rejects deprecated `[Increment XXXX]` format
+- Only allows `[FS-XXX][US-YYY]` or `[FS-XXX]` formats
+
+---
+
 ## The Standard Format
 
 ### ✅ Required Elements

package/plugins/specweave-infrastructure/agents/devops/AGENT.md

@@ -2,8 +2,8 @@
 name: devops
 description: DevOps and infrastructure expert that generates IaC ONE COMPONENT AT A TIME (VPC → Compute → Database → Monitoring) to prevent crashes. Handles Terraform, Kubernetes, Docker, CI/CD. **CRITICAL CHUNKING RULE - Large deployments (EKS + RDS + monitoring = 20+ files) done incrementally.** Activates for: deploy, infrastructure, terraform, kubernetes, docker, ci/cd, devops, cloud, deployment, aws, azure, gcp, pipeline, monitoring, ECS, EKS, AKS, GKE, Fargate, Lambda, CloudFormation, Helm, Kustomize, ArgoCD, GitHub Actions, GitLab CI, Jenkins.
 tools: Read, Write, Edit, Bash
-model: claude-sonnet-4-5-20250929
-model_preference: haiku
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: execution
 fallback_behavior: flexible
 max_response_tokens: 2000

package/src/templates/.env.example

@@ -53,35 +53,18 @@ VERCEL_TOKEN=your-vercel-token-here
 # ============================================================================
 
 # ----------------------------------------------------------------------------
-# GitHub - 3 Strategies for Team Organization
+# GitHub
 # ----------------------------------------------------------------------------
+# RECOMMENDED: Use gh CLI instead of tokens
+#   gh auth login
+#
+# Only use GITHUB_TOKEN if gh CLI is not available (e.g., CI/CD)
 # Guide: https://github.com/settings/tokens
-# Scopes: repo, read:org, workflow
+# Scopes: repo, read:org
 
-# Required for all strategies:
-GH_TOKEN=ghp_your-github-token-40-chars
-
-# Strategy 1: Repository-per-team (MOST COMMON)
-# Use when: Each team has separate repositories (microservices, multi-repo)
-# Example: Frontend team → frontend-app, Backend team → backend-api
-GITHUB_STRATEGY=repository-per-team
-GITHUB_OWNER=myorg
-GITHUB_REPOS=frontend-app,backend-api,mobile-app,qa-tools
-
-# Strategy 2: Team-based (MONOREPO)
-# Use when: Single repository with team-based filtering
-# Example: Monorepo with teams working on different parts
-# GITHUB_STRATEGY=team-based
-# GITHUB_OWNER=myorg
-# GITHUB_REPO=main-product
-# GITHUB_TEAMS=frontend-team,backend-team,mobile-team,qa-team
-
-# Strategy 3: Team-multi-repo (COMPLEX)
-# Use when: Teams own multiple repositories (platform teams)
-# Example: Platform team owns api-gateway + auth-service
-# GITHUB_STRATEGY=team-multi-repo
-# GITHUB_OWNER=myorg
-# GITHUB_TEAM_REPO_MAPPING='{"platform-team":["api-gateway","auth-service"],"frontend-team":["web-app","mobile-app"]}'
+GITHUB_TOKEN=ghp_your-github-token-40-chars
+
+# All other GitHub configuration is in .specweave/config.json
 
 # ----------------------------------------------------------------------------
 # Jira - 3 Strategies for Team Organization