specweave 0.28.17 → 0.28.19

package/plugins/specweave-github/lib/increment-issue-builder.ts

@@ -0,0 +1,471 @@
+/**
+ * Increment Issue Builder - Generate GitHub issues from increment spec.md
+ *
+ * For brownfield projects without full living docs structure,
+ * this builder extracts User Stories and ACs directly from spec.md
+ * and generates properly formatted GitHub issues.
+ *
+ * Correct format: [FS-XXX][US-YYY] User Story Title
+ * With ACs as checkable items in issue body.
+ *
+ * @see ADR-0143 (GitHub Issue Format)
+ */
+
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+
+export interface IncrementFrontmatter {
+  increment: string;
+  feature_id?: string;
+  type?: string;
+  status?: string;
+  created?: string;
+}
+
+export interface AcceptanceCriterion {
+  id: string;
+  description: string;
+  completed: boolean;
+}
+
+export interface UserStory {
+  id: string;
+  title: string;
+  asA: string;
+  iWant: string;
+  soThat: string;
+  acceptanceCriteria: AcceptanceCriterion[];
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  completed: boolean;
+  userStories: string[];
+  priority?: string;
+  description?: string;
+}
+
+export interface IncrementData {
+  frontmatter: IncrementFrontmatter;
+  title: string;
+  problemStatement: string;
+  userStories: UserStory[];
+  tasks: Task[];
+  outOfScope: string[];
+}
+
+export interface GitHubIssueContent {
+  title: string;
+  body: string;
+  labels: string[];
+}
+
+export class IncrementIssueBuilder {
+  private incrementPath: string;
+  private projectRoot: string;
+
+  constructor(incrementPath: string, projectRoot: string) {
+    this.incrementPath = incrementPath;
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * Parse increment spec.md and extract all data
+   */
+  async parse(): Promise<IncrementData> {
+    const specPath = path.join(this.incrementPath, 'spec.md');
+
+    if (!existsSync(specPath)) {
+      throw new Error(`spec.md not found at ${specPath}`);
+    }
+
+    const content = await readFile(specPath, 'utf-8');
+
+    // Extract YAML frontmatter
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+      throw new Error('spec.md missing YAML frontmatter');
+    }
+
+    const frontmatter = yaml.parse(frontmatterMatch[1]) as IncrementFrontmatter;
+    const bodyContent = content.slice(frontmatterMatch[0].length).trim();
+
+    // Extract main title
+    const titleMatch = bodyContent.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : frontmatter.increment;
+
+    // Extract problem statement
+    const problemStatement = this.extractSection(bodyContent, 'Problem Statement');
+
+    // Extract user stories
+    const userStories = this.extractUserStories(bodyContent);
+
+    // Extract out of scope
+    const outOfScopeSection = this.extractSection(bodyContent, 'Out of Scope');
+    const outOfScope = outOfScopeSection
+      .split('\n')
+      .filter(line => line.startsWith('-'))
+      .map(line => line.replace(/^-\s*/, '').trim());
+
+    // Extract tasks from tasks.md
+    const tasks = await this.extractTasks();
+
+    return {
+      frontmatter,
+      title,
+      problemStatement,
+      userStories,
+      tasks,
+      outOfScope,
+    };
+  }
+
+  /**
+   * Extract tasks from tasks.md
+   */
+  private async extractTasks(): Promise<Task[]> {
+    const tasksPath = path.join(this.incrementPath, 'tasks.md');
+
+    if (!existsSync(tasksPath)) {
+      return [];
+    }
+
+    try {
+      const content = await readFile(tasksPath, 'utf-8');
+      const tasks: Task[] = [];
+
+      // Split by task headers: ### T-XXX: Title
+      const taskBlocks = content.split(/(?=###\s+T-\d+)/);
+
+      for (const block of taskBlocks) {
+        const headerMatch = block.match(/###\s+(T-\d+):\s*(.+)/);
+        if (!headerMatch) continue;
+
+        const id = headerMatch[1];
+        const title = headerMatch[2].trim();
+
+        // Extract status: **Status**: [x] completed or **Status**: [ ] pending
+        const statusMatch = block.match(/\*\*Status\*\*:\s*\[([x\s])\]/i);
+        const completed = statusMatch ? statusMatch[1].toLowerCase() === 'x' : false;
+
+        // Extract user stories: **User Story**: US-001 or **Satisfies ACs**: AC-US1-01
+        const userStoryMatch = block.match(/\*\*User Story\*\*:\s*([^\n]+)/i);
+        const satisfiesMatch = block.match(/\*\*Satisfies ACs?\*\*:\s*([^\n]+)/i);
+
+        let userStories: string[] = [];
+        if (userStoryMatch) {
+          userStories = userStoryMatch[1].split(',').map(s => s.trim());
+        } else if (satisfiesMatch) {
+          // Extract US IDs from AC IDs (AC-US1-01 → US-001)
+          const acIds = satisfiesMatch[1].split(',').map(s => s.trim());
+          const usIds = new Set<string>();
+          for (const ac of acIds) {
+            const usMatch = ac.match(/AC-(US\d+)-/i);
+            if (usMatch) {
+              usIds.add(usMatch[1]);
+            }
+          }
+          userStories = Array.from(usIds);
+        }
+
+        // Extract priority
+        const priorityMatch = block.match(/\*\*Priority\*\*:\s*(P\d)/i);
+        const priority = priorityMatch ? priorityMatch[1] : undefined;
+
+        tasks.push({
+          id,
+          title,
+          completed,
+          userStories,
+          priority,
+        });
+      }
+
+      return tasks;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Extract a section by heading
+   */
+  private extractSection(content: string, heading: string): string {
+    const regex = new RegExp(`##\\s+${heading}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`, 'i');
+    const match = content.match(regex);
+    return match ? match[1].trim() : '';
+  }
+
+  /**
+   * Extract user stories from spec.md
+   */
+  private extractUserStories(content: string): UserStory[] {
+    const stories: UserStory[] = [];
+
+    // Find User Stories section
+    const userStoriesSection = this.extractSection(content, 'User Stories');
+    if (!userStoriesSection) {
+      return stories;
+    }
+
+    // Split by ### US-XXX headers
+    const storyBlocks = userStoriesSection.split(/(?=###\s+US-\d+)/);
+
+    for (const block of storyBlocks) {
+      const headerMatch = block.match(/###\s+(US-\d+):\s*(.+)/);
+      if (!headerMatch) continue;
+
+      const id = headerMatch[1];
+      const title = headerMatch[2].trim();
+
+      // Extract As a/I want/So that
+      const asAMatch = block.match(/\*\*As a\*\*\s+([^\n]+)/i);
+      const iWantMatch = block.match(/\*\*I want\*\*\s+([^\n]+)/i);
+      const soThatMatch = block.match(/\*\*So that\*\*\s+([^\n]+)/i);
+
+      // Extract Acceptance Criteria
+      const acceptanceCriteria = this.extractAcceptanceCriteria(block, id);
+
+      stories.push({
+        id,
+        title,
+        asA: asAMatch ? asAMatch[1].trim().replace(/,$/, '') : '',
+        iWant: iWantMatch ? iWantMatch[1].trim().replace(/,$/, '') : '',
+        soThat: soThatMatch ? soThatMatch[1].trim().replace(/\.$/, '') : '',
+        acceptanceCriteria,
+      });
+    }
+
+    return stories;
+  }
+
+  /**
+   * Extract acceptance criteria from a user story block
+   */
+  private extractAcceptanceCriteria(block: string, userStoryId: string): AcceptanceCriterion[] {
+    const criteria: AcceptanceCriterion[] = [];
+
+    // Pattern: - [x] **AC-US1-01**: Description or - [ ] **AC-US1-01**: Description
+    const acPattern = /-\s*\[([ x])\]\s*\*\*AC-(US\d+)-(\d+)\*\*:\s*(.+)/gi;
+
+    let match;
+    while ((match = acPattern.exec(block)) !== null) {
+      const completed = match[1].toLowerCase() === 'x';
+      const usNum = match[2];
+      const acNum = match[3];
+      const description = match[4].trim();
+
+      criteria.push({
+        id: `AC-${usNum}-${acNum}`,
+        description,
+        completed,
+      });
+    }
+
+    return criteria;
+  }
+
+  /**
+   * Build GitHub issue for a single user story
+   */
+  buildUserStoryIssue(
+    story: UserStory,
+    incrementData: IncrementData,
+    githubRepo?: string
+  ): GitHubIssueContent {
+    const featureId = incrementData.frontmatter.feature_id || this.generateFeatureId(incrementData);
+    const incrementId = incrementData.frontmatter.increment;
+
+    // Title format: [FS-XXX][US-YYY] User Story Title
+    const title = `[${featureId}][${story.id}] ${story.title}`;
+
+    // Build body
+    let body = '';
+
+    // Header with metadata
+    body += `**Feature**: ${featureId}\n`;
+    body += `**Status**: ${incrementData.frontmatter.status || 'planning'}\n`;
+    body += `**Priority**: P1\n`;
+    body += `\n---\n\n`;
+
+    // User Story description
+    body += `## User Story\n\n`;
+    if (story.asA && story.iWant && story.soThat) {
+      body += `**As a** ${story.asA}\n`;
+      body += `**I want** ${story.iWant}\n`;
+      body += `**So that** ${story.soThat}\n\n`;
+    } else {
+      body += `${story.title}\n\n`;
+    }
+
+    body += `---\n\n`;
+
+    // Acceptance Criteria (checkable!)
+    body += `## Acceptance Criteria\n\n`;
+    if (story.acceptanceCriteria.length > 0) {
+      const completed = story.acceptanceCriteria.filter(ac => ac.completed).length;
+      const total = story.acceptanceCriteria.length;
+      const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+      body += `Progress: ${completed}/${total} criteria met (${percentage}%)\n\n`;
+
+      for (const ac of story.acceptanceCriteria) {
+        const checkbox = ac.completed ? '[x]' : '[ ]';
+        body += `- ${checkbox} **${ac.id}**: ${ac.description}\n`;
+      }
+      body += '\n';
+    } else {
+      body += `*No acceptance criteria defined*\n\n`;
+    }
+
+    body += `---\n\n`;
+
+    // Link to increment
+    body += `## Implementation\n\n`;
+    if (githubRepo) {
+      body += `**Increment**: [${incrementId}](https://github.com/${githubRepo}/tree/develop/.specweave/increments/${incrementId})\n\n`;
+    } else {
+      body += `**Increment**: ${incrementId}\n\n`;
+    }
+
+    body += `---\n\n`;
+    body += `🤖 Auto-synced by SpecWeave Increment Sync`;
+
+    // Labels
+    const labels = ['specweave', 'user-story'];
+    if (incrementData.frontmatter.type) {
+      labels.push(incrementData.frontmatter.type);
+    }
+
+    return { title, body, labels };
+  }
+
+  /**
+   * Build GitHub issue for the entire increment (epic-style)
+   */
+  buildIncrementIssue(
+    incrementData: IncrementData,
+    githubRepo?: string
+  ): GitHubIssueContent {
+    const featureId = incrementData.frontmatter.feature_id || this.generateFeatureId(incrementData);
+    const incrementId = incrementData.frontmatter.increment;
+
+    // Title format: [FS-XXX] Increment Title
+    const title = `[${featureId}] ${incrementData.title}`;
+
+    // Build body
+    let body = '';
+
+    // Header with metadata
+    body += `**Increment**: ${incrementId}\n`;
+    body += `**Status**: ${incrementData.frontmatter.status || 'planning'}\n`;
+    body += `**Priority**: P0 (Critical)\n`;
+
+    // Calculate progress
+    const totalACs = incrementData.userStories.reduce((sum, us) => sum + us.acceptanceCriteria.length, 0);
+    const completedACs = incrementData.userStories.reduce(
+      (sum, us) => sum + us.acceptanceCriteria.filter(ac => ac.completed).length, 0
+    );
+    const percentage = totalACs > 0 ? Math.round((completedACs / totalACs) * 100) : 0;
+    body += `**Progress**: ${completedACs}/${totalACs} ACs (${percentage}%)\n`;
+
+    body += `\n---\n\n`;
+
+    // Overview
+    body += `## Overview\n\n`;
+    body += incrementData.problemStatement || incrementData.title;
+    body += `\n\n---\n\n`;
+
+    // User Stories with ACs
+    body += `## User Stories\n\n`;
+    for (const story of incrementData.userStories) {
+      const usCompleted = story.acceptanceCriteria.filter(ac => ac.completed).length;
+      const usTotal = story.acceptanceCriteria.length;
+      const usCheckbox = usCompleted === usTotal && usTotal > 0 ? '[x]' : '[ ]';
+
+      body += `### ${usCheckbox} ${story.id}: ${story.title}\n\n`;
+
+      if (story.asA && story.iWant && story.soThat) {
+        body += `> **As a** ${story.asA}, **I want** ${story.iWant}, **So that** ${story.soThat}\n\n`;
+      }
+
+      body += `**Acceptance Criteria:**\n`;
+      for (const ac of story.acceptanceCriteria) {
+        const checkbox = ac.completed ? '[x]' : '[ ]';
+        body += `- ${checkbox} **${ac.id}**: ${ac.description}\n`;
+      }
+      body += '\n';
+    }
+
+    body += `---\n\n`;
+
+    // Tasks section
+    if (incrementData.tasks.length > 0) {
+      body += `## Tasks\n\n`;
+      const completedTasks = incrementData.tasks.filter(t => t.completed).length;
+      const totalTasks = incrementData.tasks.length;
+      const taskPercentage = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+      body += `Progress: ${completedTasks}/${totalTasks} tasks (${taskPercentage}%)\n\n`;
+
+      for (const task of incrementData.tasks) {
+        const checkbox = task.completed ? '[x]' : '[ ]';
+        body += `- ${checkbox} **${task.id}**: ${task.title}\n`;
+        if (task.priority || task.userStories.length > 0) {
+          const parts: string[] = [];
+          if (task.priority) parts.push(`Priority: ${task.priority}`);
+          if (task.userStories.length > 0) parts.push(`User ${task.userStories.length === 1 ? 'Story' : 'Stories'}: ${task.userStories.join(', ')}`);
+          body += `  - ${parts.join(' | ')}\n`;
+        }
+      }
+      body += '\n---\n\n';
+    }
+
+    // Links to increment files
+    body += `## SpecWeave Increment\n\n`;
+    if (githubRepo) {
+      body += `- **Spec**: [\`spec.md\`](https://github.com/${githubRepo}/blob/develop/.specweave/increments/${incrementId}/spec.md)\n`;
+      body += `- **Plan**: [\`plan.md\`](https://github.com/${githubRepo}/blob/develop/.specweave/increments/${incrementId}/plan.md)\n`;
+      body += `- **Tasks**: [\`tasks.md\`](https://github.com/${githubRepo}/blob/develop/.specweave/increments/${incrementId}/tasks.md)\n`;
+    } else {
+      body += `- **Spec**: \`spec.md\`\n`;
+      body += `- **Plan**: \`plan.md\`\n`;
+      body += `- **Tasks**: \`tasks.md\`\n`;
+    }
+
+    body += `\n---\n\n`;
+    body += `🤖 Auto-synced by SpecWeave Increment Sync`;
+
+    // Labels
+    const labels = ['specweave', 'increment', 'enhancement'];
+    if (incrementData.frontmatter.type) {
+      labels.push(incrementData.frontmatter.type);
+    }
+
+    return { title, body, labels };
+  }
+
+  /**
+   * Generate a feature ID if not present in frontmatter
+   * Uses date-based format: FS-YY-MM-DD
+   */
+  private generateFeatureId(incrementData: IncrementData): string {
+    // Try to extract increment number
+    const incrementNum = incrementData.frontmatter.increment.match(/^(\d+)/)?.[1];
+    if (incrementNum) {
+      return `FS-${incrementNum.padStart(3, '0')}`;
+    }
+
+    // Fallback to date-based
+    const created = incrementData.frontmatter.created;
+    if (created) {
+      const match = created.match(/^(\d{4})-(\d{2})-(\d{2})/);
+      if (match) {
+        return `FS-${match[1].slice(2)}-${match[2]}-${match[3]}`;
+      }
+    }
+
+    return 'FS-UNKNOWN';
+  }
+}

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

@@ -167,35 +167,30 @@ Progress: 3/6 tasks complete (50%)
 🤖 Auto-synced by SpecWeave
 ```
 
-## Migration Guide
-
-### Update Existing Builders
+## Implementation
 
-All content builders must be updated to follow this standard:
+### Content Builders
 
-1. **EpicContentBuilder** (`plugins/specweave-github/lib/epic-content-builder.ts`)
-   - ✅ TODO: Add `githubRepo` parameter
-   - ✅ TODO: Use GitHub URLs instead of relative paths
-   - ✅ TODO: Extract priority from ACs
-   - ✅ TODO: Remove Project field
+All GitHub issue content is generated by these builders:
 
-2. **SpecContentSync** (`src/core/spec-content-sync.ts`)
-   - ✅ TODO: Update `buildExternalDescription` to use GitHub URLs
-   - ✅ TODO: Pass repo parameter to builders
+1. **UserStoryIssueBuilder** (`plugins/specweave-github/lib/user-story-issue-builder.ts`)
+   - Creates issues from `us-*.md` files
+   - Generates `[FS-XXX][US-YYY] Title` format
+   - Extracts ACs and tasks as checkboxes
+   - Uses GitHub URLs (not relative paths)
 
-3. **Increment Sync** (bash scripts and TypeScript)
-   - ✅ TODO: Use UserStoryContentBuilder as reference
-   - ✅ TODO: Ensure all issue creation uses this format
+2. **GitHubFeatureSync** (`plugins/specweave-github/lib/github-feature-sync.ts`)
+   - Syncs Features as GitHub Milestones
+   - Syncs User Stories as GitHub Issues via UserStoryIssueBuilder
+   - Universal Hierarchy: Feature → Milestone, User Story → Issue
 
-### Update Commands
+### Commands
 
-All commands that create GitHub issues must use this standard:
+All GitHub sync commands use the Universal Hierarchy:
 
-- `/specweave-github:create-issue` - Use standard format
-- `/specweave-github:sync` - Use standard format
-- `/specweave-github:sync-epic` - Use standard format
-- `/specweave-github:sync-spec` - Use standard format
-- `/specweave-github:update-user-story` - Already uses standard ✅
+- `/specweave-github:sync` - Sync increments via Feature/UserStory hierarchy
+- `/specweave-github:create-issue` - Create issue using standard format
+- `/specweave-github:update-user-story` - Update user story issue
 
 ## Validation Checklist
 
@@ -227,6 +222,6 @@ No exceptions. No shortcuts. Every issue follows this standard.
 
 ## Related Files
 
-- **Reference Implementation**: `plugins/specweave-github/lib/user-story-content-builder.ts`
-- **Test Script**: `.specweave/increments/0032-*/scripts/update-us-004-fixed.mjs`
+- **User Story Builder**: `plugins/specweave-github/lib/user-story-issue-builder.ts`
+- **Feature Sync**: `plugins/specweave-github/lib/github-feature-sync.ts`
 - **Example Issue**: https://github.com/anton-abyzov/specweave/issues/501

package/plugins/specweave-infrastructure/agents/observability-engineer/AGENT.md

@@ -1,6 +1,6 @@
 ---
 name: observability-engineer
-description: Build production-ready monitoring, logging, and tracing systems. Implements comprehensive observability strategies, SLI/SLO management, and incident response workflows. Use PROACTIVELY for monitoring infrastructure, performance optimization, or production reliability.
+description: Production observability architect - metrics, logs, traces, SLOs. Opinionated on OpenTelemetry-first, Prometheus+Grafana stack, alert fatigue prevention. Activates for monitoring, observability, SLI/SLO, alerting, Prometheus, Grafana, tracing, logging, Datadog, New Relic.
 model: claude-sonnet-4-5-20250929
 model_preference: haiku
 cost_profile: execution
@@ -8,40 +8,32 @@ fallback_behavior: flexible
 max_response_tokens: 2000
 ---
 
-## ⚠️ Chunking for Large Monitoring Setups
+## ⚠️ Chunking Rule
 
-When generating comprehensive monitoring and observability setups that exceed 1000 lines (e.g., complete observability stack with Prometheus, Grafana, OpenTelemetry, log aggregation, and distributed tracing), generate output **incrementally** to prevent crashes. Break large monitoring implementations into logical components (e.g., Metrics Collection → Dashboards → Alerting → Distributed Tracing → Log Aggregation) and ask the user which component to implement next. This ensures reliable delivery of observability infrastructure without overwhelming the system.
+Large monitoring stacks (Prometheus + Grafana + OpenTelemetry + logs) = 1000+ lines. Generate ONE component per response: Metrics → Dashboards → Alerting → Tracing → Logs.
 
-You are an observability engineer specializing in production-grade monitoring, logging, tracing, and reliability systems for enterprise-scale applications.
+## How to Invoke This Agent
 
-## 🚀 How to Invoke This Agent
-
-**Subagent Type**: `specweave-infrastructure:observability-engineer:observability-engineer`
-
-**Usage Example**:
+**Agent**: `specweave-infrastructure:observability-engineer:observability-engineer`
 
 ```typescript
 Task({
   subagent_type: "specweave-infrastructure:observability-engineer:observability-engineer",
-  prompt: "Design comprehensive monitoring stack with Prometheus, Grafana, and OpenTelemetry for microservices with SLI/SLO tracking",
-  model: "haiku" // optional: haiku, sonnet, opus
+  prompt: "Design monitoring for microservices with SLI/SLO tracking"
 });
 ```
 
-**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
-- **Plugin**: specweave-infrastructure
-- **Directory**: observability-engineer
-- **Agent Name**: observability-engineer
+**Use When**: Monitoring architecture, distributed tracing, alerting, SLO tracking, log aggregation.
+
+## Philosophy: Opinionated Observability
 
-**When to Use**:
-- You need to design monitoring and observability architecture
-- You want to set up distributed tracing for microservices
-- You need to configure alerting and SLO tracking
-- You're troubleshooting performance issues or anomalies
-- You want to implement comprehensive log aggregation and analysis
+**I follow the "Three Pillars" model but with strong opinions:**
 
-## Purpose
-Expert observability engineer specializing in comprehensive monitoring strategies, distributed tracing, and production reliability systems. Masters both traditional monitoring approaches and cutting-edge observability patterns, with deep knowledge of modern observability stacks, SRE practices, and enterprise-scale monitoring architectures.
+1. **OpenTelemetry First** - Vendor-neutral instrumentation. Don't lock into proprietary agents.
+2. **Prometheus + Grafana Default** - Unless you need managed (then DataDog/New Relic).
+3. **SLOs Before Alerts** - Define what "good" means before alerting on "bad".
+4. **Alert on Symptoms, Not Causes** - "Users see errors" not "CPU high".
+5. **Fewer, Louder Alerts** - Alert fatigue kills on-call. Max 5 critical alerts per service.
 
 ## Capabilities