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

package/mcp-server/dist/repository.js

@@ -0,0 +1,211 @@
+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);
+/**
+ * Repository for accessing methodology files
+ */
+export class MethodologyRepository {
+    methodologyRoot;
+    constructor() {
+        // Point to parent directory from mcp-server
+        this.methodologyRoot = join(__dirname, "..", "..");
+    }
+    /**
+     * List all available skills
+     */
+    async listSkills() {
+        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 = [];
+        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) {
+        const skillPath = join(this.methodologyRoot, skillName, "SKILL.md");
+        return await fs.readFile(skillPath, "utf-8");
+    }
+    /**
+     * List references for a skill
+     */
+    async listReferences(skillName) {
+        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, referenceName) {
+        const refPath = join(this.methodologyRoot, skillName, "references", referenceName);
+        return await fs.readFile(refPath, "utf-8");
+    }
+    /**
+     * Read VPC content
+     */
+    async readVPC() {
+        const vpcPath = join(this.methodologyRoot, "docs", "value-proposition-canvas.md");
+        return await fs.readFile(vpcPath, "utf-8");
+    }
+    /**
+     * Read story map backbone
+     */
+    async readStoryMap() {
+        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) {
+        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) {
+        const results = [];
+        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);
+    }
+    async walkDirectory(dir) {
+        const files = [];
+        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;
+    }
+    extractDescription(content) {
+        // 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 "";
+    }
+    toDisplayName(skillName) {
+        return skillName
+            .split("-")
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(" ");
+    }
+    calculateRelevance(content, query) {
+        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;
+    }
+    extractRelevantSection(content, query) {
+        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/dist/tools/gherkin-validator.d.ts

@@ -0,0 +1,16 @@
+import { MethodologyRepository } from "../repository.js";
+export declare class GherkinValidator {
+    private repository;
+    constructor(repository: MethodologyRepository);
+    validate(content: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    private extractScenarios;
+    private validateScenarioStructure;
+    private getScenarioStructure;
+    private hasSimilarStructures;
+    private formatValidationResults;
+}

package/mcp-server/dist/tools/gherkin-validator.js

@@ -0,0 +1,152 @@
+export class GherkinValidator {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async validate(content) {
+        const result = {
+            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",
+                    text,
+                },
+            ],
+        };
+    }
+    extractScenarios(content) {
+        const scenarios = [];
+        const scenarioRegex = /Scenario(?: Outline)?:(.+?)(?=\n\s*Scenario|$)/gs;
+        let match;
+        while ((match = scenarioRegex.exec(content)) !== null) {
+            scenarios.push(match[0]);
+        }
+        return scenarios;
+    }
+    validateScenarioStructure(scenario, result) {
+        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.`);
+                }
+            }
+        }
+    }
+    getScenarioStructure(scenario) {
+        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(" -> ");
+    }
+    hasSimilarStructures(structures) {
+        if (structures.length < 3)
+            return false;
+        const counts = structures.reduce((acc, s) => {
+            acc[s] = (acc[s] || 0) + 1;
+            return acc;
+        }, {});
+        return Object.values(counts).some((count) => count >= 3);
+    }
+    formatValidationResults(result) {
+        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/dist/tools/guidance-searcher.d.ts

@@ -0,0 +1,11 @@
+import { MethodologyRepository } from "../repository.js";
+export declare class GuidanceSearcher {
+    private repository;
+    constructor(repository: MethodologyRepository);
+    search(query: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+}

package/mcp-server/dist/tools/guidance-searcher.js

@@ -0,0 +1,34 @@
+export class GuidanceSearcher {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async search(query) {
+        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",
+                        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",
+                    text: `# Search Results for '${query}'\n\n${text}`,
+                },
+            ],
+        };
+    }
+}

package/mcp-server/dist/tools/next-step-suggester.d.ts

@@ -0,0 +1,16 @@
+import { MethodologyRepository } from "../repository.js";
+export declare class NextStepSuggester {
+    private repository;
+    constructor(repository: MethodologyRepository);
+    suggest(projectPath?: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    private analyzeProjectContext;
+    private determineSuggestion;
+    private fileExists;
+    private hasTestFiles;
+    private hasPipelineConfig;
+}

package/mcp-server/dist/tools/next-step-suggester.js

@@ -0,0 +1,210 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+export class NextStepSuggester {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async suggest(projectPath) {
+        const context = await this.analyzeProjectContext(projectPath);
+        const suggestion = this.determineSuggestion(context);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: suggestion,
+                },
+            ],
+        };
+    }
+    async analyzeProjectContext(projectPath) {
+        const docsPath = projectPath ? join(projectPath, "docs") : join(process.cwd(), "docs");
+        try {
+            const vpcContent = await this.repository.readVPC();
+            const storyMapContent = await this.repository.readStoryMap();
+            const featureFiles = await this.repository.listFeatureFiles(projectPath);
+            return {
+                hasVPC: !!vpcContent,
+                hasBMC: await this.fileExists(join(docsPath, "business-model-canvas.md")),
+                hasStoryMap: !!storyMapContent,
+                hasFeatureFiles: featureFiles.length > 0,
+                hasTests: await this.hasTestFiles(projectPath),
+                testsPassing: false, // TODO: Implement test execution check
+                hasPipeline: await this.hasPipelineConfig(projectPath),
+            };
+        }
+        catch {
+            return {
+                hasVPC: false,
+                hasBMC: false,
+                hasStoryMap: false,
+                hasFeatureFiles: false,
+                hasTests: false,
+                testsPassing: false,
+                hasPipeline: false,
+            };
+        }
+    }
+    determineSuggestion(context) {
+        if (!context.hasVPC) {
+            return `# Next Step: Create Value Proposition Canvas
+
+You should start by defining business value using the Value Proposition Canvas.
+
+**Why:** The VPC establishes the foundation for all downstream work. It defines customer segments, jobs, pains, and gains that inform every feature decision.
+
+**Reference:** product-strategy/SKILL.md
+
+**What to create:** /docs/value-proposition-canvas.md
+
+The VPC should include:
+- Customer segments (who are your users?)
+- Customer jobs (what are they trying to accomplish?)
+- Pains (what frustrates them?)
+- Gains (what success looks like)
+- Pain relievers (how your product helps)
+- Gain creators (how your product delivers value)`;
+        }
+        if (!context.hasStoryMap) {
+            return `# Next Step: Create Story Map Backbone
+
+You have a Value Proposition Canvas. Now organize user activities into a story map.
+
+**Why:** The story map backbone organizes work by user activities (derived from VPC customer jobs) rather than technical components.
+
+**Reference:** story-mapping/SKILL.md
+
+**What to create:** /docs/story-map/backbone.md
+
+Each customer job from the VPC becomes one user activity in the backbone.`;
+        }
+        if (!context.hasFeatureFiles) {
+            return `# Next Step: Write Gherkin Scenarios
+
+You have a story map. Now specify behavior using concrete examples.
+
+**Why:** Gherkin scenarios define "done" before implementation starts. They become executable acceptance tests.
+
+**Reference:** bdd-specification/SKILL.md
+
+**What to create:** /features/*.feature
+
+Each scenario should:
+- Use Given-When-Then format
+- Trace "So that" clause to a VPC gain
+- Specify observable user outcomes`;
+        }
+        if (!context.hasTests) {
+            return `# Next Step: Write Failing Acceptance Test (RED Phase)
+
+You have Gherkin scenarios. Now write automated tests that verify them.
+
+**Why:** Test-first development defines success criteria before implementation. Tests fail initially because the feature doesn't exist yet.
+
+**Reference:** atdd-workflow/red-phase.md
+
+**What to do:**
+1. Pick one Gherkin scenario
+2. Write automated test that verifies it
+3. Run test and confirm it fails with clear error message
+4. Proceed to GREEN phase once RED phase passes`;
+        }
+        if (context.hasTests && !context.testsPassing) {
+            return `# Next Step: Make Tests Pass (GREEN Phase)
+
+You have failing tests. Now implement minimum code to make them pass.
+
+**Why:** GREEN phase focuses on making it work, not making it perfect. Simplicity first, optimization later.
+
+**Reference:** atdd-workflow/green-phase.md
+
+**What to do:**
+1. Write simplest implementation that passes the test
+2. No premature optimization
+3. No "future-proofing"
+4. Run tests until they pass
+5. Proceed to REFACTOR phase once tests are green`;
+        }
+        if (context.testsPassing) {
+            return `# Next Step: Refactor for Maintainability
+
+You have passing tests. Now improve code structure.
+
+**Why:** REFACTOR phase is where clean code principles apply. With tests protecting you, safely improve structure.
+
+**References:**
+- atdd-workflow/refactor-phase.md
+- clean-code/solid.md
+
+**What to do:**
+1. Keep tests green throughout refactoring
+2. Apply SOLID principles
+3. Extract duplications
+4. Use ubiquitous language
+5. Reference clean-code patterns as needed`;
+        }
+        if (!context.hasPipeline) {
+            return `# Next Step: Set Up CI/CD Pipeline
+
+You have tested code. Now automate deployment.
+
+**Why:** Automated pipeline builds, tests, and deploys code without manual steps. Makes frequent delivery safe and easy.
+
+**Reference:** cicd-pipeline/SKILL.md
+
+**What to create:** Pipeline configuration (e.g., .github/workflows/ci.yml)
+
+Pipeline should include:
+- Build stage
+- Test stage (runs all tests)
+- Deploy stage (on successful tests)`;
+        }
+        return `# Next Step: Measure and Improve
+
+You have a complete delivery workflow. Now collect data and iterate.
+
+**Why:** Continuous improvement validates that delivered features create expected value and identifies process improvements.
+
+**Reference:** continuous-improvement/SKILL.md
+
+**What to do:**
+1. Define success metrics (connects to VPC gains)
+2. Collect measurement data
+3. Perform root cause analysis when issues arise
+4. Update upstream artifacts based on learnings`;
+    }
+    async fileExists(path) {
+        try {
+            await fs.access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async hasTestFiles(projectPath) {
+        const testDirs = ["test", "tests", "spec", "__tests__"];
+        const basePath = projectPath || process.cwd();
+        for (const dir of testDirs) {
+            if (await this.fileExists(join(basePath, dir))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    async hasPipelineConfig(projectPath) {
+        const pipelineFiles = [
+            ".github/workflows",
+            ".gitlab-ci.yml",
+            "Jenkinsfile",
+            ".circleci/config.yml",
+        ];
+        const basePath = projectPath || process.cwd();
+        for (const file of pipelineFiles) {
+            if (await this.fileExists(join(basePath, file))) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/mcp-server/dist/tools/reference-reader.d.ts

@@ -0,0 +1,17 @@
+import { MethodologyRepository } from "../repository.js";
+export declare class ReferenceReader {
+    private repository;
+    constructor(repository: MethodologyRepository);
+    readReference(referencePath: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    listReferences(skillName: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+}