mcp-ai-agent-guidelines/dist/strategies/speckit-strategy.d.ts

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * SpecKitStrategy - GitHub Spec-Kit output format
 *
 * Generates a complete "Spec Kit" folder structure with comprehensive
 * documentation for implementing a feature following GitHub's Spec-Kit methodology.
 * This is the premium output format - the signature output of the refactored project.
 *
 * Generates:
 * - README.md: Overview and navigation (primary)
 * - spec.md: Full specification with requirements
 * - plan.md: Implementation plan with phases
 * - tasks.md: Detailed task breakdown
 * - adr.md: Architecture decision record
 * - roadmap.md: Timeline and milestones
 *
 * @module strategies/speckit-strategy
 * @see {@link https://github.com/Anselmoo/mcp-ai-agent-guidelines/blob/development/plan-v0.13.x/specs/SPEC-001-output-strategy-layer.md SPEC-001} §4.5
 * @see {@link https://github.com/Anselmoo/mcp-ai-agent-guidelines/blob/development/plan-v0.13.x/specs/SPEC-005-speckit-integration.md SPEC-005}
 */
import type { SessionState } from "../domain/design/types.js";
import type { OutputArtifacts, OutputStrategy, RenderOptions } from "./output-strategy.js";
import { OutputApproach } from "./output-strategy.js";
import type { Constitution } from "./speckit/types.js";
/**
 * Rendering options specific to SpecKit output format.
 *
 * Extends the base RenderOptions with SpecKit-specific capabilities
 * like constitutional constraints and validation.
 *
 * @interface SpecKitRenderOptions
 */
export interface SpecKitRenderOptions extends Partial<RenderOptions> {
    /** Optional constitution to apply constraints from */
    constitution?: Constitution;
    /** Whether to include constitutional constraints in spec.md */
    includeConstitutionalConstraints?: boolean;
    /** Whether to validate spec against constitution before rendering */
    validateBeforeRender?: boolean;
    /** Whether to fail rendering if validation produces errors */
    failOnValidationErrors?: boolean;
}
/**
 * SpecKitStrategy implements GitHub's Spec-Kit output format.
 *
 * Generates a complete folder structure with 6 documents:
 * - README.md (primary): Navigation and quick start
 * - spec.md: Requirements and constraints
 * - plan.md: Implementation phases and timeline
 * - tasks.md: Detailed task breakdown
 * - adr.md: Architecture decision record
 * - roadmap.md: Milestones and deliverables
 *
 * Supports rendering:
 * - SessionState: Complete design session into Spec-Kit format
 *
 * @implements {OutputStrategy<SessionState>}
 */
export declare class SpecKitStrategy implements OutputStrategy<SessionState> {
    /** The output approach this strategy implements */
    readonly approach = OutputApproach.SPECKIT;
    /** Optional validator for spec validation */
    private validator?;
    /** Constitution used to create the current validator (for caching) */
    private cachedConstitution?;
    /**
     * Render a domain result to Spec-Kit artifacts.
     *
     * @param result - The SessionState to render
     * @param options - Optional SpecKit rendering options
     * @returns Output artifacts with README.md and 5 secondary documents
     * @throws {Error} If result is not a SessionState
     */
    render(result: SessionState, options?: SpecKitRenderOptions): OutputArtifacts;
    /**
     * Check if this strategy supports rendering a specific domain type.
     *
     * @param domainType - The domain type identifier
     * @returns True if this strategy can render the domain type
     */
    supports(domainType: string): boolean;
    /**
     * Generate README.md - primary navigation document.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @returns README document with navigation and quick start
     * @private
     */
    private generateReadme;
    /**
     * Generate spec.md - full specification document.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @param options - Optional SpecKit rendering options
     * @param validationResult - Optional validation result to include
     * @returns Specification document with requirements and constraints
     * @private
     */
    private generateSpec;
    /**
     * Generate tasks.md - detailed task breakdown.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @returns Task breakdown document with checklist
     * @private
     */
    private generateTasks;
    /**
     * Generate adr.md - architecture decision record.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @returns Architecture decision record
     * @private
     */
    private generateAdr;
    /**
     * Generate roadmap.md - timeline and milestones.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @returns Roadmap with milestones and deliverables
     * @private
     */
    private generateRoadmap;
    /**
     * Slugify a title for use as a folder name.
     *
     * Converts to lowercase, replaces non-alphanumeric with hyphens,
     * and truncates to 50 characters.
     *
     * @param title - The title to slugify
     * @returns Slugified string suitable for folder name
     * @private
     */
    private slugify;
    /**
     * Extract title from SessionState.
     *
     * @param result - The session state
     * @returns Title string
     * @private
     */
    private extractTitle;
    /**
     * Extract overview from SessionState.
     *
     * @param result - The session state
     * @returns Overview text
     * @private
     */
    private extractOverview;
    /**
     * Extract objectives from SessionState.
     *
     * @param result - The session state
     * @returns Formatted objectives list
     * @private
     */
    private extractObjectives;
    /**
     * Extract functional requirements from SessionState.
     *
     * @param result - The session state
     * @returns Formatted requirements list
     * @private
     */
    private extractFunctionalRequirements;
    /**
     * Extract non-functional requirements from SessionState.
     *
     * @param result - The session state
     * @returns Formatted non-functional requirements
     * @private
     */
    private extractNonFunctionalRequirements;
    /**
     * Extract constraints from SessionState.
     *
     * @param result - The session state
     * @returns Formatted constraints list
     * @private
     */
    private extractConstraints;
    /**
     * Extract acceptance criteria from SessionState.
     *
     * @param result - The session state
     * @returns Formatted acceptance criteria
     * @private
     */
    private extractAcceptanceCriteria;
    /**
     * Extract out-of-scope items from SessionState.
     *
     * @param result - The session state
     * @returns Formatted out-of-scope list
     * @private
     */
    private extractOutOfScope;
    /**
     * Extract task list from SessionState.
     *
     * @param result - The session state
     * @returns Formatted task list
     * @private
     */
    private extractTaskList;
    /**
     * Generate task dependencies description.
     *
     * @param result - The session state
     * @returns Task dependencies description
     * @private
     */
    private generateTaskDependencies;
    /**
     * Count total tasks.
     *
     * @param result - The session state
     * @returns Task count
     * @private
     */
    private countTasks;
    /**
     * Extract ADR context from SessionState.
     *
     * @param result - The session state
     * @returns ADR context description
     * @private
     */
    private extractAdrContext;
    /**
     * Extract ADR decision from SessionState.
     *
     * @param result - The session state
     * @returns ADR decision description
     * @private
     */
    private extractAdrDecision;
    /**
     * Extract ADR consequences from SessionState.
     *
     * @param result - The session state
     * @returns ADR consequences (positive, negative, neutral)
     * @private
     */
    private extractAdrConsequences;
    /**
     * Extract milestones from SessionState.
     *
     * @param result - The session state
     * @returns Formatted milestones
     * @private
     */
    private extractMilestones;
    /**
     * Extract deliverables from SessionState.
     *
     * @param result - The session state
     * @returns Formatted deliverables list
     * @private
     */
    private extractDeliverables;
    /**
     * Extract constraint references from SessionState.
     *
     * Looks for constraint references in the context that link to
     * constitutional constraints.
     *
     * @param result - The session state
     * @returns Array of constraint references
     * @private
     */
    private extractConstraintReferences;
    /**
     * Render constitutional constraints section.
     *
     * Generates a markdown section with constitutional constraints
     * referenced by this specification. Each constraint is looked up
     * in the constitution and rendered with its full details.
     *
     * @param constraints - Array of constraint references
     * @param constitution - The constitution to look up constraints from
     * @returns Formatted constitutional constraints section
     * @private
     */
    private renderConstraints;
    /**
     * Find a constitution item by ID.
     *
     * Searches through all constitution sections (principles, constraints,
     * architecture rules, design principles) to find an item with the
     * matching ID.
     *
     * @param id - The constitution item ID to find
     * @param constitution - The constitution to search
     * @returns The found constitution item or undefined
     * @private
     */
    private findConstitutionItem;
    /**
     * Render plan.md document with structured Plan data.
     *
     * This is the enhanced method that creates a structured Plan object
     * and renders it into the plan.md format as specified in P4-005.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @returns OutputDocument for plan.md
     * @private
     */
    private renderPlan;
    /**
     * Extract structured Plan data from SessionState.
     *
     * Maps the design session data to the Plan interface,
     * deriving phases, dependencies, risks, and timeline.
     *
     * @param result - The session state
     * @returns Structured Plan object
     * @private
     */
    private extractPlan;
    /**
     * Derive phases from SessionState.
     *
     * Maps design session phases to structured Phase objects
     * with IDs, names, descriptions, deliverables, and durations.
     *
     * @param result - The session state
     * @returns Array of Phase objects
     * @private
     */
    private derivePhases;
    /**
     * Derive dependencies from SessionState.
     *
     * Extracts project dependencies and formats them as Dependency objects.
     *
     * @param result - The session state
     * @returns Array of Dependency objects
     * @private
     */
    private deriveDependencies;
    /**
     * Derive risks from SessionState.
     *
     * Extracts project risks and formats them as Risk objects
     * with severity levels and mitigation strategies.
     *
     * @param result - The session state
     * @returns Array of Risk objects
     * @private
     */
    private deriveRisks;
    /**
     * Derive timeline from Phase array.
     *
     * Generates a timeline by assigning week numbers to each phase
     * based on their sequence and estimated durations.
     *
     * @param phases - Array of Phase objects
     * @returns Array of TimelineEntry objects
     * @private
     */
    private deriveTimeline;
    /**
     * Type guard for SessionState.
     *
     * @param result - The value to check
     * @returns True if result is a SessionState
     * @private
     */
    private isSessionState;
    /**
     * Extract ParsedSpec from SessionState.
     *
     * Transforms SessionState data into a ParsedSpec structure
     * for task derivation.
     *
     * @param result - The session state
     * @returns ParsedSpec object
     * @private
     */
    private extractSpec;
    /**
     * Render tasks.md with enhanced structure.
     *
     * Creates a comprehensive tasks document with grouped tasks,
     * dependency graph, and priority sections.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @param spec - Optional parsed spec (if available)
     * @returns OutputDocument for tasks.md
     * @private
     */
    private renderTasks;
    /**
     * Group tasks by phase.
     *
     * Organizes tasks into phase buckets, defaulting to "Unassigned"
     * for tasks without a phase.
     *
     * @param tasks - Array of derived tasks
     * @returns Tasks grouped by phase
     * @private
     */
    private groupTasksByPhase;
    /**
     * Generate Mermaid dependency graph.
     *
     * Creates a Mermaid graph showing task dependencies.
     *
     * @param tasks - Array of derived tasks
     * @returns Mermaid graph definition
     * @private
     */
    private generateDependencyGraph;
    /**
     * Calculate total estimate from tasks.
     *
     * Sums task estimates (in hours) and converts to days.
     * Note: Only parses estimates in "Xh" format (e.g., "3h", "8h").
     * Other formats like "1d", "2 days", or "1 week" are not supported
     * and will be ignored in the calculation.
     *
     * @param tasks - Array of derived tasks
     * @returns Total estimate string (e.g., "24h (~3 days)")
     * @private
     */
    private calculateTotalEstimate;
    /**
     * Derive actionable tasks from a parsed specification.
     *
     * Transforms requirements and acceptance criteria into concrete,
     * estimable tasks with verification tasks for each requirement.
     *
     * @param spec - The parsed specification
     * @returns Array of derived tasks with IDs, estimates, and dependencies
     * @throws {Error} If spec structure is invalid
     * @private
     */
    private deriveTasksFromSpec;
    /**
     * Derive an implementation task from a requirement.
     *
     * Converts a requirement into an actionable task with estimate
     * based on complexity keywords in the description.
     *
     * @param req - The requirement to derive a task from
     * @param id - Numeric task ID
     * @returns Implementation task
     * @private
     */
    private deriveTaskFromRequirement;
    /**
     * Derive a verification task for a requirement.
     *
     * Creates a testing/verification task that depends on the
     * implementation task for the same requirement.
     *
     * @param req - The requirement to verify
     * @param id - Numeric task ID
     * @returns Verification task with dependency
     * @private
     */
    private deriveVerificationTask;
    /**
     * Derive a validation task from an acceptance criterion.
     *
     * Creates a task to validate that an acceptance criterion is met,
     * with estimate based on verification method (automated vs manual).
     *
     * @param ac - The acceptance criterion to validate
     * @param id - Numeric task ID
     * @returns Validation task
     * @private
     */
    private deriveTaskFromAcceptanceCriterion;
    /**
     * Estimate task duration from description complexity.
     *
     * Uses keyword analysis to estimate work duration:
     * - "simple" or "basic" → 2h
     * - "complex" or "comprehensive" → 8h
     * - "integration" or "refactor" → 4h
     * - default → 3h
     *
     * @param description - Task or requirement description
     * @returns Estimated duration string
     * @private
     */
    private estimateFromDescription;
    /**
     * Extract a concise title from a description.
     *
     * Takes the first sentence or truncates to 50 characters,
     * suitable for task titles. Strips common action verbs
     * (Implement, Create, Add, Build, etc.) to avoid redundancy
     * when used with prefixes like "Implement:" or "Verify:".
     *
     * @param description - Full description text
     * @returns Truncated title without action verb prefix
     * @private
     */
    private extractTaskTitle;
    /**
     * Render progress.md document with progress tracking.
     *
     * Creates a progress tracking document with status indicators,
     * completion metrics, progress bar, recent updates, blockers,
     * and next steps.
     *
     * @param result - The session state
     * @param slug - The slugified folder name
     * @returns OutputDocument for progress.md
     * @private
     */
    private renderProgress;
    /**
     * Extract progress data from SessionState.
     *
     * Initializes a Progress object with default values for a new spec.
     * Derives total tasks from the spec's requirements and acceptance criteria.
     *
     * @param result - The session state
     * @returns Progress object with default values
     * @private
     */
    private extractProgress;
    /**
     * Extract spec content for validation.
     *
     * Prepares SpecContent from SessionState for validation against
     * constitutional constraints.
     *
     * @param result - The session state
     * @returns SpecContent object ready for validation
     * @private
     */
    private extractSpecContent;
    /**
     * Render validation results section.
     *
     * Formats validation results into a markdown section showing
     * score, constraints checked, and any issues found.
     *
     * @param result - The validation result
     * @returns Formatted validation section
     * @private
     */
    private renderValidationSection;
}
//# sourceMappingURL=speckit-strategy.d.ts.map