@schilling.mark.a/software-methodology 1.0.0 → 1.0.1

package/mcp-server/src/repository.ts

@@ -0,0 +1,254 @@
+import { promises as fs } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface Skill {
+  name: string;
+  displayName: string;
+  description: string;
+  path: string;
+}
+
+export interface Reference {
+  name: string;
+  path: string;
+  skill: string;
+}
+
+/**
+ * Repository for accessing methodology files
+ */
+export class MethodologyRepository {
+  private methodologyRoot: string;
+
+  constructor() {
+    // Point to parent directory from mcp-server
+    this.methodologyRoot = join(__dirname, "..", "..");
+  }
+
+  /**
+   * List all available skills
+   */
+  async listSkills(): Promise<Skill[]> {
+    const skills = [
+      "product-strategy",
+      "ux-research",
+      "story-mapping",
+      "bdd-specification",
+      "ux-design",
+      "ui-design-workflow",
+      "ui-design-system",
+      "atdd-workflow",
+      "clean-code",
+      "cicd-pipeline",
+      "continuous-improvement",
+    ];
+
+    const skillList: Skill[] = [];
+
+    for (const skillName of skills) {
+      const skillPath = join(this.methodologyRoot, skillName, "SKILL.md");
+      try {
+        const content = await fs.readFile(skillPath, "utf-8");
+        const description = this.extractDescription(content);
+        skillList.push({
+          name: skillName,
+          displayName: this.toDisplayName(skillName),
+          description,
+          path: skillPath,
+        });
+      } catch (error) {
+        // Skip skills that don't have SKILL.md yet
+        console.error(`Warning: Could not read ${skillPath}`);
+      }
+    }
+
+    return skillList;
+  }
+
+  /**
+   * Read a skill's main documentation
+   */
+  async readSkill(skillName: string): Promise<string> {
+    const skillPath = join(this.methodologyRoot, skillName, "SKILL.md");
+    return await fs.readFile(skillPath, "utf-8");
+  }
+
+  /**
+   * List references for a skill
+   */
+  async listReferences(skillName: string): Promise<Reference[]> {
+    const referencesDir = join(this.methodologyRoot, skillName, "references");
+    
+    try {
+      const files = await fs.readdir(referencesDir);
+      return files
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => ({
+          name: f,
+          path: join(referencesDir, f),
+          skill: skillName,
+        }));
+    } catch (error) {
+      return []; // No references directory
+    }
+  }
+
+  /**
+   * Read a reference document
+   */
+  async readReference(skillName: string, referenceName: string): Promise<string> {
+    const refPath = join(this.methodologyRoot, skillName, "references", referenceName);
+    return await fs.readFile(refPath, "utf-8");
+  }
+
+  /**
+   * Read VPC content
+   */
+  async readVPC(): Promise<string> {
+    const vpcPath = join(this.methodologyRoot, "docs", "value-proposition-canvas.md");
+    return await fs.readFile(vpcPath, "utf-8");
+  }
+
+  /**
+   * Read story map backbone
+   */
+  async readStoryMap(): Promise<string | null> {
+    const storyMapPath = join(this.methodologyRoot, "docs", "story-map", "backbone.md");
+    try {
+      return await fs.readFile(storyMapPath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * List feature files
+   */
+  async listFeatureFiles(projectPath?: string): Promise<string[]> {
+    const featuresDir = projectPath
+      ? join(projectPath, "features")
+      : join(this.methodologyRoot, "features");
+    
+    try {
+      const files = await this.walkDirectory(featuresDir);
+      return files.filter((f) => f.endsWith(".feature"));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Search all content
+   */
+  async searchContent(query: string): Promise<Array<{ file: string; content: string; relevance: number }>> {
+    const results: Array<{ file: string; content: string; relevance: number }> = [];
+    const skills = await this.listSkills();
+
+    const queryLower = query.toLowerCase();
+
+    for (const skill of skills) {
+      const content = await this.readSkill(skill.name);
+      const relevance = this.calculateRelevance(content, queryLower);
+      
+      if (relevance > 0) {
+        results.push({
+          file: `${skill.name}/SKILL.md`,
+          content: this.extractRelevantSection(content, queryLower),
+          relevance,
+        });
+      }
+
+      const references = await this.listReferences(skill.name);
+      for (const ref of references) {
+        const refContent = await this.readReference(skill.name, ref.name);
+        const refRelevance = this.calculateRelevance(refContent, queryLower);
+        
+        if (refRelevance > 0) {
+          results.push({
+            file: `${skill.name}/references/${ref.name}`,
+            content: this.extractRelevantSection(refContent, queryLower),
+            relevance: refRelevance,
+          });
+        }
+      }
+    }
+
+    return results.sort((a, b) => b.relevance - a.relevance);
+  }
+
+  private async walkDirectory(dir: string): Promise<string[]> {
+    const files: string[] = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...(await this.walkDirectory(fullPath)));
+      } else {
+        files.push(fullPath);
+      }
+    }
+
+    return files;
+  }
+
+  private extractDescription(content: string): string {
+    // Extract description from frontmatter if exists
+    const frontmatterMatch = content.match(/---\n.*?description:\s*(.+?)\n/s);
+    if (frontmatterMatch) {
+      return frontmatterMatch[1].trim();
+    }
+
+    // Otherwise get first paragraph
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (line.trim() && !line.startsWith("#") && !line.startsWith("---")) {
+        return line.trim();
+      }
+    }
+
+    return "";
+  }
+
+  private toDisplayName(skillName: string): string {
+    return skillName
+      .split("-")
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(" ");
+  }
+
+  private calculateRelevance(content: string, query: string): number {
+    const contentLower = content.toLowerCase();
+    const words = query.split(/\s+/);
+    
+    let score = 0;
+    for (const word of words) {
+      const count = (contentLower.match(new RegExp(word, "g")) || []).length;
+      score += count;
+    }
+    
+    return score;
+  }
+
+  private extractRelevantSection(content: string, query: string): string {
+    const lines = content.split("\n");
+    const queryWords = query.split(/\s+/);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const lineLower = lines[i].toLowerCase();
+      if (queryWords.some((word) => lineLower.includes(word))) {
+        // Extract context around match (5 lines before and after)
+        const start = Math.max(0, i - 5);
+        const end = Math.min(lines.length, i + 6);
+        return lines.slice(start, end).join("\n");
+      }
+    }
+    
+    // Fallback: return first 300 chars
+    return content.slice(0, 300) + "...";
+  }
+}

package/mcp-server/src/tools/gherkin-validator.ts

@@ -0,0 +1,206 @@
+import { MethodologyRepository } from "../repository.js";
+
+interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+  suggestions: string[];
+}
+
+export class GherkinValidator {
+  constructor(private repository: MethodologyRepository) {}
+
+  async validate(content: string) {
+    const result: ValidationResult = {
+      isValid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    // Check for feature header
+    if (!content.includes("Feature:")) {
+      result.isValid = false;
+      result.errors.push("Missing 'Feature:' declaration");
+    }
+
+    // Check for user story (As a... I want... So that...)
+    const hasAsA = /As an?/i.test(content);
+    const hasIWant = /I want/i.test(content);
+    const hasSoThat = /So that/i.test(content);
+
+    if (!hasAsA || !hasIWant || !hasSoThat) {
+      result.isValid = false;
+      result.errors.push(
+        "Missing user story format (As a... I want... So that...)"
+      );
+    }
+
+    // Check for VPC traceability
+    const vpcKeywords = [
+      "business value",
+      "pain",
+      "gain",
+      "user need",
+      "customer job",
+    ];
+    const hasSomeTrace = vpcKeywords.some((keyword) =>
+      content.toLowerCase().includes(keyword.toLowerCase())
+    );
+
+    if (!hasSomeTrace) {
+      result.warnings.push(
+        "No clear VPC traceability found. Consider referencing pains/gains in 'So that' clause"
+      );
+    }
+
+    // Check Given-When-Then structure
+    const scenarios = this.extractScenarios(content);
+    for (const scenario of scenarios) {
+      this.validateScenarioStructure(scenario, result);
+    }
+
+    // Check for repeated scenarios (suggest Scenario Outline)
+    if (scenarios.length >= 3) {
+      const structures = scenarios.map((s) => this.getScenarioStructure(s));
+      const hasSimilar = this.hasSimilarStructures(structures);
+      
+      if (hasSimilar) {
+        result.suggestions.push(
+          "Multiple scenarios have similar structure. Consider using Scenario Outline with Examples table. Reference: bdd-specification/gherkin-patterns.md"
+        );
+      }
+    }
+
+    // Format results
+    const text = this.formatValidationResults(result);
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text,
+        },
+      ],
+    };
+  }
+
+  private extractScenarios(content: string): string[] {
+    const scenarios: string[] = [];
+    const scenarioRegex = /Scenario(?: Outline)?:(.+?)(?=\n\s*Scenario|$)/gs;
+    
+    let match;
+    while ((match = scenarioRegex.exec(content)) !== null) {
+      scenarios.push(match[0]);
+    }
+    
+    return scenarios;
+  }
+
+  private validateScenarioStructure(
+    scenario: string,
+    result: ValidationResult
+  ): void {
+    const lines = scenario.split("\n").map((l) => l.trim());
+    
+    // Check for proper tense in Given
+    const givenLines = lines.filter((l) => l.startsWith("Given"));
+    for (const given of givenLines) {
+      if (/\bwill\b|\bshall\b/i.test(given)) {
+        result.warnings.push(
+          `Given step should be past tense, not future: "${given}". Reference: Given establishes existing state.`
+        );
+      }
+    }
+
+    // Check for single When action
+    const whenLines = lines.filter((l) => l.startsWith("When"));
+    if (whenLines.length > 1) {
+      const hasAnd = lines.some((l) => l.startsWith("And") && 
+        lines.indexOf(l) > lines.findIndex((l) => l.startsWith("When"))
+      );
+      
+      if (!hasAnd) {
+        result.warnings.push(
+          "Multiple When steps should use 'And' for readability"
+        );
+      }
+    }
+
+    // Check for observable outcomes in Then
+    const thenLines = lines.filter((l) => l.startsWith("Then"));
+    for (const then of thenLines) {
+      const nonObservable = [
+        "database",
+        "queue",
+        "log",
+        "internal state",
+        "cache",
+      ];
+      
+      for (const keyword of nonObservable) {
+        if (then.toLowerCase().includes(keyword)) {
+          result.warnings.push(
+            `Then step references internal state: "${then}". Then steps should verify user-observable outcomes only.`
+          );
+        }
+      }
+    }
+  }
+
+  private getScenarioStructure(scenario: string): string {
+    const lines = scenario.split("\n").map((l) => l.trim());
+    return lines
+      .filter((l) => l.startsWith("Given") || l.startsWith("When") || l.startsWith("Then"))
+      .map((l) => l.split(":")[0])
+      .join(" -> ");
+  }
+
+  private hasSimilarStructures(structures: string[]): boolean {
+    if (structures.length < 3) return false;
+    
+    const counts = structures.reduce((acc, s) => {
+      acc[s] = (acc[s] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+    
+    return Object.values(counts).some((count) => count >= 3);
+  }
+
+  private formatValidationResults(result: ValidationResult): string {
+    let text = "# Gherkin Validation Results\n\n";
+    
+    if (result.isValid && result.warnings.length === 0 && result.suggestions.length === 0) {
+      text += "✅ **Validation PASSED**\n\nYour feature file follows best practices!";
+      return text;
+    }
+
+    if (!result.isValid) {
+      text += "❌ **Validation FAILED**\n\n";
+    } else {
+      text += "⚠️ **Validation PASSED with warnings**\n\n";
+    }
+
+    if (result.errors.length > 0) {
+      text += "## Errors\n\n";
+      text += result.errors.map((e) => `- ❌ ${e}`).join("\n");
+      text += "\n\n";
+    }
+
+    if (result.warnings.length > 0) {
+      text += "## Warnings\n\n";
+      text += result.warnings.map((w) => `- ⚠️ ${w}`).join("\n");
+      text += "\n\n";
+    }
+
+    if (result.suggestions.length > 0) {
+      text += "## Suggestions\n\n";
+      text += result.suggestions.map((s) => `- 💡 ${s}`).join("\n");
+      text += "\n\n";
+    }
+
+    text += "\n**Reference:** bdd-specification/references/gherkin-patterns.md";
+
+    return text;
+  }
+}

package/mcp-server/src/tools/guidance-searcher.ts

@@ -0,0 +1,42 @@
+import { MethodologyRepository } from "../repository.js";
+
+export class GuidanceSearcher {
+  constructor(private repository: MethodologyRepository) {}
+
+  async search(query: string) {
+    const results = await this.repository.searchContent(query);
+    
+    if (results.length === 0) {
+      const skills = await this.repository.listSkills();
+      const skillList = skills.map((s) => s.name).join(", ");
+      
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `No results found for '${query}'.\n\nAvailable skills: ${skillList}`,
+          },
+        ],
+      };
+    }
+
+    // Take top 5 results
+    const topResults = results.slice(0, 5);
+    
+    const text = topResults
+      .map(
+        (r, i) =>
+          `### ${i + 1}. ${r.file} (relevance: ${r.relevance})\n\n${r.content}\n`
+      )
+      .join("\n---\n\n");
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `# Search Results for '${query}'\n\n${text}`,
+        },
+      ],
+    };
+  }
+}