@eddacraft/anvil-adapters 0.1.0

package/dist/speckit/parser.js

@@ -0,0 +1,283 @@
+import { validateRelativePath } from '@eddacraft/anvil-core';
+/**
+ * Validate and sanitize a file path to prevent path traversal attacks.
+ * Returns undefined if the path is invalid (absolute, contains null bytes, or escapes parent directory).
+ */
+function safePath(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return validateRelativePath(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export class SpecKitParser {
+    static SPEC_SECTIONS = {
+        intent: ['intent', 'purpose', 'objective'],
+        overview: ['overview', 'summary', 'description'],
+        goals: ['goals', 'objectives', 'outcomes'],
+        requirements: ['requirements', 'prerequisites', 'dependencies'],
+        changes: ['changes', 'modifications', 'alterations', 'tasks'],
+    };
+    /** Maximum input size for SpecKit parsing (2MB) */
+    static MAX_INPUT_SIZE = 2 * 1024 * 1024;
+    parseSpecMarkdown(content) {
+        if (content.length > SpecKitParser.MAX_INPUT_SIZE) {
+            throw new Error(`Input exceeds maximum size of ${SpecKitParser.MAX_INPUT_SIZE} bytes`);
+        }
+        const sections = this.parseMarkdownSections(content);
+        const result = {
+            metadata: {},
+        };
+        for (const section of sections) {
+            this.extractSectionData(section, result);
+        }
+        return result;
+    }
+    parseMarkdownSections(content) {
+        const lines = content.split('\n');
+        const sections = [];
+        const stack = [];
+        let currentContent = [];
+        for (const line of lines) {
+            const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
+            if (headerMatch) {
+                if (currentContent.length > 0 && stack.length > 0) {
+                    stack[stack.length - 1].content = currentContent.join('\n').trim();
+                }
+                const level = headerMatch[1].length;
+                const title = headerMatch[2].trim();
+                const newSection = {
+                    title,
+                    level,
+                    content: '',
+                    subsections: [],
+                };
+                while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+                    stack.pop();
+                }
+                if (stack.length === 0) {
+                    sections.push(newSection);
+                }
+                else {
+                    stack[stack.length - 1].subsections.push(newSection);
+                }
+                stack.push(newSection);
+                currentContent = [];
+            }
+            else {
+                currentContent.push(line);
+            }
+        }
+        if (currentContent.length > 0 && stack.length > 0) {
+            stack[stack.length - 1].content = currentContent.join('\n').trim();
+        }
+        return sections;
+    }
+    extractSectionData(section, result) {
+        const sectionTitleLower = section.title.toLowerCase();
+        let sectionWasProcessed = false;
+        for (const [key, aliases] of Object.entries(SpecKitParser.SPEC_SECTIONS)) {
+            // Use word boundary matching to avoid partial matches (e.g., "objective" shouldn't match "objectives")
+            if (aliases.some((alias) => {
+                const regex = new RegExp(`\\b${alias}\\b`, 'i');
+                return regex.test(sectionTitleLower);
+            })) {
+                sectionWasProcessed = true;
+                switch (key) {
+                    case 'intent':
+                        // For intent, get only the paragraph text, not list items
+                        result.intent = this.extractParagraphText(section.content);
+                        break;
+                    case 'overview':
+                        // For overview, get only the paragraph text, not list items
+                        result.overview = this.extractParagraphText(section.content);
+                        break;
+                    case 'goals':
+                        result.goals = this.parseListItems(section.content);
+                        break;
+                    case 'requirements':
+                        result.requirements = this.parseListItems(section.content);
+                        break;
+                    case 'changes':
+                        // parseChanges handles all nested subsections, so don't recurse into them
+                        result.changes = this.parseChanges(section);
+                        return; // Exit early - changes section is fully processed
+                }
+            }
+        }
+        // Only recurse into subsections if this section wasn't fully processed by a specialized method
+        // or if the section didn't match any known section types
+        if (!sectionWasProcessed) {
+            for (const subsection of section.subsections) {
+                this.extractSectionData(subsection, result);
+            }
+        }
+    }
+    extractParagraphText(content) {
+        const lines = content.split('\n');
+        const paragraphLines = [];
+        let hasContent = false;
+        for (const line of lines) {
+            const trimmedLine = line.trim();
+            // Stop at list items
+            if (trimmedLine.match(/^[-*+]\s+/) || trimmedLine.match(/^\d+\.\s+/)) {
+                break;
+            }
+            // Add non-empty lines
+            if (trimmedLine) {
+                paragraphLines.push(trimmedLine);
+                hasContent = true;
+            }
+            else if (hasContent && paragraphLines.length > 0) {
+                // Stop at empty line after we've collected some content
+                break;
+            }
+        }
+        return paragraphLines.join(' ').trim();
+    }
+    parseListItems(content) {
+        const lines = content.split('\n');
+        const items = [];
+        let currentItem = '';
+        for (const line of lines) {
+            const listMatch = line.match(/^[\s]*[-*+]\s+(.+)$/);
+            const numberedMatch = line.match(/^[\s]*\d+\.\s+(.+)$/);
+            if (listMatch || numberedMatch) {
+                if (currentItem) {
+                    items.push(currentItem.trim());
+                }
+                currentItem = (listMatch?.[1] || numberedMatch?.[1] || '').trim();
+            }
+            else if (currentItem && line.trim()) {
+                currentItem += ' ' + line.trim();
+            }
+        }
+        if (currentItem) {
+            items.push(currentItem.trim());
+        }
+        return items;
+    }
+    parseChanges(section) {
+        const changes = [];
+        // Process direct subsections
+        for (const subsection of section.subsections) {
+            // Check if this subsection is a grouping section (like "Files to Create")
+            const subsectionTitleLower = subsection.title.toLowerCase();
+            const isGroupingSection = subsectionTitleLower.includes('files to') ||
+                subsectionTitleLower.includes('configuration') ||
+                subsectionTitleLower.includes('dependencies') ||
+                subsectionTitleLower.includes('scripts');
+            if (isGroupingSection && subsection.subsections.length > 0) {
+                // Process nested subsections within grouping sections
+                for (const nestedSection of subsection.subsections) {
+                    const change = this.parseChangeSection(nestedSection);
+                    if (change) {
+                        changes.push(change);
+                    }
+                }
+            }
+            else {
+                // Process as a direct change section
+                const change = this.parseChangeSection(subsection);
+                if (change) {
+                    changes.push(change);
+                }
+            }
+        }
+        // Fallback to parsing list items if no subsections found
+        if (changes.length === 0) {
+            const listItems = this.parseListItems(section.content);
+            for (const item of listItems) {
+                const change = this.parseChangeFromListItem(item);
+                if (change) {
+                    changes.push(change);
+                }
+            }
+        }
+        return changes;
+    }
+    parseChangeSection(section) {
+        const titleLower = section.title.toLowerCase();
+        let type = 'script_execute';
+        if (titleLower.includes('create') || titleLower.includes('new')) {
+            type = 'file_create';
+        }
+        else if (titleLower.includes('update') || titleLower.includes('modify')) {
+            type = 'file_update';
+        }
+        else if (titleLower.includes('delete') || titleLower.includes('remove')) {
+            type = 'file_delete';
+        }
+        else if (titleLower.includes('config')) {
+            type = 'config_update';
+        }
+        else if (titleLower.includes('dependency') || titleLower.includes('package')) {
+            if (titleLower.includes('add') || titleLower.includes('install')) {
+                type = 'dependency_add';
+            }
+            else if (titleLower.includes('remove') || titleLower.includes('uninstall')) {
+                type = 'dependency_remove';
+            }
+            else {
+                type = 'dependency_update';
+            }
+        }
+        // Look for path in title first, then in content
+        let pathMatch = section.title.match(/`([^`]+)`/);
+        if (!pathMatch && section.content) {
+            // Look for path in the first line of content
+            const firstLine = section.content.split('\n')[0];
+            pathMatch = firstLine.match(/`([^`]+)`/);
+        }
+        const path = safePath(pathMatch?.[1]);
+        const codeBlockMatch = section.content.match(/```[\w]*\n([\s\S]*?)```/);
+        const content = codeBlockMatch ? codeBlockMatch[1].trim() : undefined;
+        return {
+            type,
+            description: section.title,
+            path,
+            content,
+        };
+    }
+    parseChangeFromListItem(item) {
+        const itemLower = item.toLowerCase();
+        let type = 'script_execute';
+        // Check for script execution patterns first
+        if (itemLower.includes('run') ||
+            itemLower.includes('execute') ||
+            itemLower.includes('script')) {
+            type = 'script_execute';
+        }
+        else if (itemLower.includes('create') || itemLower.includes('new file')) {
+            type = 'file_create';
+        }
+        else if (itemLower.includes('delete') || itemLower.includes('remove file')) {
+            type = 'file_delete';
+        }
+        else if (itemLower.includes('update dependency')) {
+            type = 'dependency_update';
+        }
+        else if (itemLower.includes('install') || itemLower.includes('add dependency')) {
+            type = 'dependency_add';
+        }
+        else if (itemLower.includes('uninstall') || itemLower.includes('remove dependency')) {
+            type = 'dependency_remove';
+        }
+        else if (itemLower.includes('update') || itemLower.includes('modify')) {
+            type = 'file_update';
+        }
+        else if (itemLower.includes('config')) {
+            type = 'config_update';
+        }
+        const pathMatch = item.match(/`([^`]+)`/);
+        const path = safePath(pathMatch?.[1]);
+        return {
+            type,
+            description: item,
+            path,
+        };
+    }
+}

package/dist/speckit/parsers/plan-parser.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Parser for official GitHub Spec-Kit plan.md format
+ *
+ * Plan.md focuses on HOW (technical implementation):
+ * - Summary
+ * - Technical Context (stack, dependencies, constraints)
+ * - Constitution Check (compliance with project principles)
+ * - Project Structure (directories, files)
+ * - Implementation Details (API endpoints, database schema, etc.)
+ * - Complexity Tracking (design decisions)
+ */
+interface PlanMetadata {
+    feature?: string;
+    branch?: string;
+    date?: string;
+    spec?: string;
+    [key: string]: unknown;
+}
+interface TechnicalContext {
+    language?: string;
+    dependencies?: string[];
+    storage?: string;
+    testing?: string;
+    target?: string;
+    type?: string;
+    performanceGoals?: string[];
+    constraints?: string[];
+    scale?: string;
+}
+interface ConstitutionCheck {
+    modularity?: boolean | string;
+    testability?: boolean | string;
+    security?: boolean | string;
+    performance?: boolean | string;
+    maintainability?: boolean | string;
+    documentation?: boolean | string;
+    [key: string]: boolean | string | undefined;
+}
+interface ProjectStructure {
+    documentation?: string;
+    sourceCode?: string;
+    selectedOption?: string;
+}
+interface ComplexityDecision {
+    title: string;
+    problem: string;
+    solution: string;
+    justification: string;
+}
+export interface ParsedPlan {
+    metadata: PlanMetadata;
+    summary: string;
+    technicalContext: TechnicalContext;
+    constitutionCheck: ConstitutionCheck;
+    projectStructure: ProjectStructure;
+    implementationDetails: Map<string, string>;
+    complexityDecisions: ComplexityDecision[];
+}
+export declare class PlanParser {
+    parsePlan(content: string): ParsedPlan;
+    private extractMetadata;
+    private extractSummary;
+    private parseTechnicalContext;
+    private parseConstitutionCheck;
+    private parseProjectStructure;
+    private parseImplementationDetails;
+    private parseComplexityDecisions;
+    private parseComplexityDecision;
+}
+export {};
+//# sourceMappingURL=plan-parser.d.ts.map

package/dist/speckit/parsers/plan-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-parser.d.ts","sourceRoot":"","sources":["../../../src/speckit/parsers/plan-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,iBAAiB;IACzB,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,eAAe,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,UAAU,gBAAgB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,kBAAkB;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;CAC3C;AAED,qBAAa,UAAU;IACrB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAmCtC,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,qBAAqB;IAiF7B,OAAO,CAAC,sBAAsB;IA4B9B,OAAO,CAAC,qBAAqB;IAoC7B,OAAO,CAAC,0BAA0B;IA2BlC,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,uBAAuB;CAiBhC"}

package/dist/speckit/parsers/plan-parser.js

@@ -0,0 +1,216 @@
+/**
+ * Parser for official GitHub Spec-Kit plan.md format
+ *
+ * Plan.md focuses on HOW (technical implementation):
+ * - Summary
+ * - Technical Context (stack, dependencies, constraints)
+ * - Constitution Check (compliance with project principles)
+ * - Project Structure (directories, files)
+ * - Implementation Details (API endpoints, database schema, etc.)
+ * - Complexity Tracking (design decisions)
+ */
+export class PlanParser {
+    parsePlan(content) {
+        const result = {
+            metadata: {},
+            summary: '',
+            technicalContext: {},
+            constitutionCheck: {},
+            projectStructure: {},
+            implementationDetails: new Map(),
+            complexityDecisions: [],
+        };
+        // Extract metadata from first section
+        result.metadata = this.extractMetadata(content);
+        // Parse summary section
+        result.summary = this.extractSummary(content);
+        // Parse technical context
+        result.technicalContext = this.parseTechnicalContext(content);
+        // Parse constitution check
+        result.constitutionCheck = this.parseConstitutionCheck(content);
+        // Parse project structure
+        result.projectStructure = this.parseProjectStructure(content);
+        // Parse implementation details (flexible sections)
+        result.implementationDetails = this.parseImplementationDetails(content);
+        // Parse complexity tracking
+        result.complexityDecisions = this.parseComplexityDecisions(content);
+        return result;
+    }
+    extractMetadata(content) {
+        const metadata = {};
+        // Extract title (# Implementation Plan: ...)
+        const titleMatch = content.match(/^#\s+Implementation Plan:\s+(.+)$/m);
+        if (titleMatch) {
+            metadata.feature = titleMatch[1].trim();
+        }
+        // Extract bold key-value pairs
+        const metadataRegex = /\*\*([^*]+)\*\*:\s*(?:`([^`\n]+)`|\[([^\]]+)\]\(([^)]+)\)|([^\n]+))/g;
+        let match;
+        while ((match = metadataRegex.exec(content)) !== null) {
+            const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+            const value = match[2] || match[3] || match[5] || '';
+            metadata[key] = value.trim();
+        }
+        return metadata;
+    }
+    extractSummary(content) {
+        const summaryMatch = content.match(/##\s+Summary\s+([\s\S]*?)(?=\n##\s|$)/i);
+        return summaryMatch?.[1]?.trim() || '';
+    }
+    parseTechnicalContext(content) {
+        const context = {};
+        const contextMatch = content.match(/##\s+Technical Context([\s\S]*?)(?=\n##\s|$)/i);
+        if (!contextMatch) {
+            return context;
+        }
+        const contextSection = contextMatch[1];
+        // Parse bullet points with key-value pairs
+        const languageMatch = contextSection.match(/[-*]\s+\*\*Language\/Version\*\*:\s+(.+)/i);
+        if (languageMatch) {
+            context.language = languageMatch[1].trim();
+        }
+        const storageMatch = contextSection.match(/[-*]\s+\*\*Storage\*\*:\s+(.+)/i);
+        if (storageMatch) {
+            context.storage = storageMatch[1].trim();
+        }
+        const testingMatch = contextSection.match(/[-*]\s+\*\*Testing\*\*:\s+(.+)/i);
+        if (testingMatch) {
+            context.testing = testingMatch[1].trim();
+        }
+        const targetMatch = contextSection.match(/[-*]\s+\*\*Target\*\*:\s+(.+)/i);
+        if (targetMatch) {
+            context.target = targetMatch[1].trim();
+        }
+        const typeMatch = contextSection.match(/[-*]\s+\*\*Type\*\*:\s+(.+)/i);
+        if (typeMatch) {
+            context.type = typeMatch[1].trim();
+        }
+        const scaleMatch = contextSection.match(/[-*]\s+\*\*Scale\*\*:\s+(.+)/i);
+        if (scaleMatch) {
+            context.scale = scaleMatch[1].trim();
+        }
+        // Parse dependencies (multi-line list)
+        const depsMatch = contextSection.match(/[-*]\s+\*\*Dependencies\*\*:\s+([\s\S]*?)(?=\n[-*]\s+\*\*|$)/i);
+        if (depsMatch) {
+            const deps = depsMatch[1]
+                .split(/\n\s*[-*]\s+/)
+                .map((d) => d.trim())
+                .filter((d) => d.length > 0);
+            context.dependencies = deps;
+        }
+        // Parse performance goals
+        const perfMatch = contextSection.match(/[-*]\s+\*\*Performance Goals\*\*:\s+([\s\S]*?)(?=\n[-*]\s+\*\*|$)/i);
+        if (perfMatch) {
+            const goals = perfMatch[1]
+                .split(/\n\s*[-*]\s+/)
+                .map((g) => g.trim())
+                .filter((g) => g.length > 0);
+            context.performanceGoals = goals;
+        }
+        // Parse constraints
+        const constraintsMatch = contextSection.match(/[-*]\s+\*\*Constraints\*\*:\s+([\s\S]*?)(?=\n[-*]\s+\*\*|$)/i);
+        if (constraintsMatch) {
+            const constraints = constraintsMatch[1]
+                .split(/\n\s*[-*]\s+/)
+                .map((c) => c.trim())
+                .filter((c) => c.length > 0);
+            context.constraints = constraints;
+        }
+        return context;
+    }
+    parseConstitutionCheck(content) {
+        const check = {};
+        const checkMatch = content.match(/##\s+Constitution Check([\s\S]*?)(?=\n##\s|$)/i);
+        if (!checkMatch) {
+            return check;
+        }
+        const checkSection = checkMatch[1];
+        // Parse ✅ or ❌ followed by **Key**: Description
+        const checkRegex = /([✅❌✓✗×])\s+\*\*([^*]+)\*\*:\s+(.+)/g;
+        let match;
+        while ((match = checkRegex.exec(checkSection)) !== null) {
+            const status = match[1];
+            const key = match[2].trim().toLowerCase().replace(/\s+/g, '_');
+            const description = match[3].trim();
+            // Check if it passes or fails
+            const passes = status === '✅' || status === '✓';
+            check[key] = passes ? description : `FAIL: ${description}`;
+        }
+        return check;
+    }
+    parseProjectStructure(content) {
+        const structure = {};
+        const structureMatch = content.match(/##\s+Project Structure([\s\S]*?)(?=\n##\s|$)/i);
+        if (!structureMatch) {
+            return structure;
+        }
+        const structureSection = structureMatch[1];
+        // Extract documentation structure (code block)
+        const docsMatch = structureSection.match(/###\s+Documentation[\s\S]*?```[\s\S]*?\n([\s\S]*?)```/i);
+        if (docsMatch) {
+            structure.documentation = docsMatch[1].trim();
+        }
+        // Extract source code structure
+        const sourceMatch = structureSection.match(/###\s+Source Code Structure[\s\S]*?```[\s\S]*?\n([\s\S]*?)```/i);
+        if (sourceMatch) {
+            structure.sourceCode = sourceMatch[1].trim();
+        }
+        // Check for "Selected" or "(Selected)" marker
+        const selectedMatch = structureSection.match(/####\s+Option \d+:([^(]+)\(Selected\)/i);
+        if (selectedMatch) {
+            structure.selectedOption = selectedMatch[1].trim();
+        }
+        return structure;
+    }
+    parseImplementationDetails(content) {
+        const details = new Map();
+        // Find "Implementation Details" section
+        const detailsMatch = content.match(/##\s+Implementation Details([\s\S]*?)(?=\n##\s+Complexity|$)/i);
+        if (!detailsMatch) {
+            return details;
+        }
+        const detailsSection = detailsMatch[1];
+        // Split by ### headers
+        const subsectionRegex = /###\s+([^\n]+)\n([\s\S]*?)(?=\n###|$)/g;
+        let match;
+        while ((match = subsectionRegex.exec(detailsSection)) !== null) {
+            const title = match[1].trim();
+            const content = match[2].trim();
+            details.set(title, content);
+        }
+        return details;
+    }
+    parseComplexityDecisions(content) {
+        const decisions = [];
+        // Find "Complexity Tracking" section
+        const complexityMatch = content.match(/##\s+Complexity Tracking([\s\S]*?)$/i);
+        if (!complexityMatch) {
+            return decisions;
+        }
+        const complexitySection = complexityMatch[1];
+        // Split by ### headers (each decision)
+        const decisionBlocks = complexitySection.split(/###\s+/).slice(1);
+        for (const block of decisionBlocks) {
+            const decision = this.parseComplexityDecision(block);
+            if (decision) {
+                decisions.push(decision);
+            }
+        }
+        return decisions;
+    }
+    parseComplexityDecision(block) {
+        const titleMatch = block.match(/^([^\n]+)/);
+        const problemMatch = block.match(/\*\*Problem\*\*:\s+(.+?)(?=\n\*\*|$)/s);
+        const solutionMatch = block.match(/\*\*Solution\*\*:\s+([\s\S]+?)(?=\n\*\*|$)/);
+        const justificationMatch = block.match(/\*\*Justification\*\*:\s+([\s\S]+?)(?=\n###|$)/);
+        if (!titleMatch) {
+            return null;
+        }
+        return {
+            title: titleMatch[1].trim(),
+            problem: problemMatch?.[1]?.trim() || '',
+            solution: solutionMatch?.[1]?.trim() || '',
+            justification: justificationMatch?.[1]?.trim() || '',
+        };
+    }
+}

package/dist/speckit/parsers/spec-parser.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Parser for official GitHub Spec-Kit spec.md format
+ *
+ * Spec.md focuses on WHAT and WHY (not HOW):
+ * - Feature metadata
+ * - User Scenarios & Testing (prioritized user stories)
+ * - Requirements (functional requirements, key entities)
+ * - Success Criteria (measurable outcomes)
+ */
+interface SpecMetadata {
+    feature?: string;
+    branch?: string;
+    date?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+interface UserScenario {
+    priority: 'P1' | 'P2' | 'P3' | string;
+    title: string;
+    asA: string;
+    iWantTo: string;
+    soThat: string;
+    acceptanceScenarios: string[];
+    edgeCases: string[];
+}
+interface FunctionalRequirement {
+    code: string;
+    description: string;
+    needsClarification: boolean;
+    clarificationQuestion?: string;
+}
+interface EntityDefinition {
+    name: string;
+    represents: string;
+    keyAttributes: string[];
+    relationships: string[];
+}
+interface SuccessCriteria {
+    quantitative: string[];
+    qualitative: string[];
+    security?: string[];
+    performance?: string[];
+}
+export interface ParsedSpec {
+    metadata: SpecMetadata;
+    userScenarios: UserScenario[];
+    requirements: {
+        functional: FunctionalRequirement[];
+        entities: EntityDefinition[];
+    };
+    successCriteria: SuccessCriteria;
+    clarifications: string[];
+}
+export declare class SpecParser {
+    parseSpec(content: string): ParsedSpec;
+    private extractMetadata;
+    private parseUserScenarios;
+    private parseUserScenario;
+    private parseRequirements;
+    private parseFunctionalRequirements;
+    private parseEntities;
+    private parseEntity;
+    private parseSuccessCriteria;
+    private extractClarifications;
+}
+export {};
+//# sourceMappingURL=spec-parser.d.ts.map

package/dist/speckit/parsers/spec-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-parser.d.ts","sourceRoot":"","sources":["../../../src/speckit/parsers/spec-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,YAAY;IACpB,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,UAAU,eAAe;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,YAAY,EAAE;QACZ,UAAU,EAAE,qBAAqB,EAAE,CAAC;QACpC,QAAQ,EAAE,gBAAgB,EAAE,CAAC;KAC9B,CAAC;IACF,eAAe,EAAE,eAAe,CAAC;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,qBAAa,UAAU;IACrB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAiCtC,OAAO,CAAC,eAAe;IAsBvB,OAAO,CAAC,kBAAkB;IA2B1B,OAAO,CAAC,iBAAiB;IAkDzB,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,2BAA2B;IAkCnC,OAAO,CAAC,aAAa;IAgCrB,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,oBAAoB;IA4D5B,OAAO,CAAC,qBAAqB;CAW9B"}