@gordon.gan/specflow 1.0.0

package/dist/core/templates/types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Valid template identifiers corresponding to markdown files in the templates/ directory.
+ */
+export type TemplateId = 'proposal' | 'spec' | 'design' | 'tasks';

package/dist/core/templates/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/validation/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validation constants.
+ *
+ * Regex patterns and heading markers used during spec validation.
+ */
+export declare const SECTION_HEADER: RegExp;
+export declare const REQUIREMENT_HEADER: RegExp;
+export declare const SCENARIO_HEADER_CORRECT: RegExp;
+export declare const SCENARIO_HEADER_WRONG_LEVEL: RegExp;
+export declare const WHEN_LINE: RegExp;
+export declare const THEN_LINE: RegExp;
+export declare const REASON_LINE: RegExp;
+export declare const FROM_LINE: RegExp;
+export declare const TO_LINE: RegExp;

package/dist/core/validation/constants.js

@@ -0,0 +1,14 @@
+/**
+ * Validation constants.
+ *
+ * Regex patterns and heading markers used during spec validation.
+ */
+export const SECTION_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
+export const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+export const SCENARIO_HEADER_CORRECT = /^####\s+Scenario:\s*(.+)\s*$/;
+export const SCENARIO_HEADER_WRONG_LEVEL = /^###\s+Scenario:\s*(.+)\s*$/;
+export const WHEN_LINE = /^-\s+\*\*WHEN\*\*\s+(.+)$/;
+export const THEN_LINE = /^-\s+\*\*THEN\*\*\s+(.+)$/;
+export const REASON_LINE = /^\*\*Reason\*\*:\s*(.+)$/;
+export const FROM_LINE = /^FROM:\s*(.+)$/;
+export const TO_LINE = /^TO:\s*(.+)$/;

package/dist/core/validation/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation types.
+ *
+ * Defines the result and error shapes returned by spec validation.
+ */
+export interface ValidationError {
+    readonly message: string;
+    readonly line?: number;
+}
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+}

package/dist/core/validation/types.js

@@ -0,0 +1,6 @@
+/**
+ * Validation types.
+ *
+ * Defines the result and error shapes returned by spec validation.
+ */
+export {};

package/dist/core/validation/validator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Spec validator.
+ *
+ * Validates delta-spec markdown content for structural correctness:
+ * - ADDED/MODIFIED sections must have requirements with scenarios
+ * - Scenarios must use #### heading (not ###)
+ * - Scenarios must have WHEN and THEN clauses
+ * - REMOVED sections must have a Reason
+ * - RENAMED sections must have FROM and TO lines
+ */
+import type { ValidationResult } from './types.js';
+/**
+ * Validate a delta-spec markdown content string.
+ *
+ * Checks structural rules including:
+ * - ADDED/MODIFIED requirements must have scenarios with WHEN/THEN
+ * - Scenarios must use #### heading level
+ * - REMOVED requirements must have a Reason
+ * - RENAMED entries must have FROM and TO
+ *
+ * @param content - The raw markdown content of a delta spec
+ * @returns A ValidationResult with valid flag and any errors found
+ */
+export declare function validateSpec(content: string): ValidationResult;

package/dist/core/validation/validator.js

@@ -0,0 +1,250 @@
+/**
+ * Spec validator.
+ *
+ * Validates delta-spec markdown content for structural correctness:
+ * - ADDED/MODIFIED sections must have requirements with scenarios
+ * - Scenarios must use #### heading (not ###)
+ * - Scenarios must have WHEN and THEN clauses
+ * - REMOVED sections must have a Reason
+ * - RENAMED sections must have FROM and TO lines
+ */
+import { SECTION_HEADER, REQUIREMENT_HEADER, SCENARIO_HEADER_CORRECT, SCENARIO_HEADER_WRONG_LEVEL, WHEN_LINE, THEN_LINE, REASON_LINE, FROM_LINE, TO_LINE, } from './constants.js';
+function splitIntoSections(allLines) {
+    const sections = [];
+    let current = null;
+    for (let i = 0; i < allLines.length; i++) {
+        const match = SECTION_HEADER.exec(allLines[i]);
+        if (match) {
+            if (current) {
+                sections.push({ kind: current.kind, startLine: current.startLine, lines: current.lines });
+            }
+            current = {
+                kind: match[1].toUpperCase(),
+                startLine: i,
+                lines: [],
+            };
+            continue;
+        }
+        if (current) {
+            current.lines.push(allLines[i]);
+        }
+    }
+    if (current) {
+        sections.push({ kind: current.kind, startLine: current.startLine, lines: current.lines });
+    }
+    return sections;
+}
+function validateRequirementSection(section, errors) {
+    const { lines, startLine } = section;
+    // Check for scenarios at wrong heading level (### instead of ####)
+    for (let i = 0; i < lines.length; i++) {
+        if (SCENARIO_HEADER_WRONG_LEVEL.test(lines[i])) {
+            errors.push({
+                message: `Scenario has incorrect heading level (use #### not ###)`,
+                line: startLine + 1 + i + 1,
+            });
+        }
+    }
+    // Check for orphan scenarios before any requirement header
+    let foundFirstReq = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (REQUIREMENT_HEADER.test(lines[i])) {
+            foundFirstReq = true;
+            break;
+        }
+        if (SCENARIO_HEADER_CORRECT.test(lines[i])) {
+            errors.push({
+                message: `Scenario found with missing requirement header`,
+                line: startLine + 1 + i + 1,
+            });
+            break;
+        }
+    }
+    // If section has no requirement headers at all but has content, skip req parsing
+    const hasAnyRequirement = lines.some((l) => REQUIREMENT_HEADER.test(l));
+    if (!hasAnyRequirement) {
+        // If there are scenarios without a requirement, we already flagged it above
+        return;
+    }
+    // Parse requirements and validate each has at least one scenario with WHEN/THEN
+    let currentReqName = null;
+    let currentReqLine = 0;
+    let scenarioCount = 0;
+    let scenariosForCurrent = [];
+    const flushReq = () => {
+        if (currentReqName !== null) {
+            if (scenarioCount === 0) {
+                errors.push({
+                    message: `Requirement "${currentReqName}" has no scenarios`,
+                    line: currentReqLine,
+                });
+            }
+            for (const sc of scenariosForCurrent) {
+                if (!sc.hasWhen) {
+                    errors.push({
+                        message: `Scenario "${sc.name}" is missing WHEN clause`,
+                        line: sc.line,
+                    });
+                }
+                if (!sc.hasThen) {
+                    errors.push({
+                        message: `Scenario "${sc.name}" is missing THEN clause`,
+                        line: sc.line,
+                    });
+                }
+            }
+        }
+    };
+    let currentScenario = null;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNum = startLine + 1 + i + 1;
+        const line = lines[i];
+        const reqMatch = REQUIREMENT_HEADER.exec(line);
+        if (reqMatch) {
+            // Flush previous scenario into list
+            if (currentScenario) {
+                scenariosForCurrent.push(currentScenario);
+                currentScenario = null;
+            }
+            flushReq();
+            currentReqName = reqMatch[1].trim();
+            currentReqLine = lineNum;
+            scenarioCount = 0;
+            scenariosForCurrent = [];
+            continue;
+        }
+        const scMatch = SCENARIO_HEADER_CORRECT.exec(line);
+        if (scMatch && currentReqName !== null) {
+            if (currentScenario) {
+                scenariosForCurrent.push(currentScenario);
+            }
+            scenarioCount++;
+            currentScenario = { name: scMatch[1].trim(), line: lineNum, hasWhen: false, hasThen: false };
+            continue;
+        }
+        if (currentScenario !== null) {
+            const hasWhen = currentScenario.hasWhen || WHEN_LINE.test(line);
+            const hasThen = currentScenario.hasThen || THEN_LINE.test(line);
+            if (hasWhen !== currentScenario.hasWhen || hasThen !== currentScenario.hasThen) {
+                currentScenario = {
+                    name: currentScenario.name,
+                    line: currentScenario.line,
+                    hasWhen,
+                    hasThen,
+                };
+            }
+        }
+    }
+    // Flush last scenario and requirement
+    if (currentScenario) {
+        scenariosForCurrent.push(currentScenario);
+    }
+    flushReq();
+}
+function validateRemovedSection(section, errors) {
+    const { lines, startLine } = section;
+    let currentReqName = null;
+    let currentReqLine = 0;
+    let hasReason = false;
+    const flushRemoved = () => {
+        if (currentReqName !== null && !hasReason) {
+            errors.push({
+                message: `REMOVED requirement "${currentReqName}" is missing Reason`,
+                line: currentReqLine,
+            });
+        }
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const lineNum = startLine + 1 + i + 1;
+        const line = lines[i];
+        const reqMatch = REQUIREMENT_HEADER.exec(line);
+        if (reqMatch) {
+            flushRemoved();
+            currentReqName = reqMatch[1].trim();
+            currentReqLine = lineNum;
+            hasReason = false;
+            continue;
+        }
+        if (REASON_LINE.test(line)) {
+            hasReason = true;
+        }
+    }
+    flushRemoved();
+}
+function validateRenamedSection(section, errors) {
+    const { lines, startLine } = section;
+    let hasFrom = false;
+    let hasTo = false;
+    let fromLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (FROM_LINE.test(line)) {
+            // If we had a previous FROM without TO, report it
+            if (hasFrom && !hasTo) {
+                errors.push({
+                    message: `RENAMED entry is missing TO (has FROM but no TO)`,
+                    line: startLine + 1 + fromLine + 1,
+                });
+            }
+            hasFrom = true;
+            hasTo = false;
+            fromLine = i;
+        }
+        if (TO_LINE.test(line)) {
+            hasTo = true;
+        }
+    }
+    // Check last pair
+    if (hasFrom && !hasTo) {
+        errors.push({
+            message: `RENAMED entry is missing TO (has FROM but no TO)`,
+            line: startLine + 1 + fromLine + 1,
+        });
+    }
+    // If no FROM found at all
+    if (!hasFrom) {
+        const hasContent = lines.some((l) => l.trim().length > 0);
+        if (hasContent) {
+            errors.push({
+                message: `RENAMED section is missing FROM/TO entries`,
+                line: startLine + 1,
+            });
+        }
+    }
+}
+/**
+ * Validate a delta-spec markdown content string.
+ *
+ * Checks structural rules including:
+ * - ADDED/MODIFIED requirements must have scenarios with WHEN/THEN
+ * - Scenarios must use #### heading level
+ * - REMOVED requirements must have a Reason
+ * - RENAMED entries must have FROM and TO
+ *
+ * @param content - The raw markdown content of a delta spec
+ * @returns A ValidationResult with valid flag and any errors found
+ */
+export function validateSpec(content) {
+    const normalized = content.replace(/\r\n?/g, '\n');
+    const allLines = normalized.split('\n');
+    const errors = [];
+    const sections = splitIntoSections(allLines);
+    for (const section of sections) {
+        switch (section.kind) {
+            case 'ADDED':
+            case 'MODIFIED':
+                validateRequirementSection(section, errors);
+                break;
+            case 'REMOVED':
+                validateRemovedSection(section, errors);
+                break;
+            case 'RENAMED':
+                validateRenamedSection(section, errors);
+                break;
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/integrations/claude/adapter.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from '../shared/types.js';
+export declare const claudeAdapter: Adapter;

package/dist/integrations/claude/adapter.js

@@ -0,0 +1,106 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { COMMAND_CATALOG } from '../shared/command-catalog.js';
+import { directoryExists, hashDirectoryTree } from '../shared/asset-hash.js';
+import { deriveCapabilityIds } from '../shared/capability-evidence.js';
+import { copyRuntimeAssets } from '../shared/runtime-assets.js';
+import { renderIdeContent } from '../shared/skill-renderer.js';
+function extractSkillDescription(content, fallback) {
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+        return fallback;
+    }
+    const descMatch = frontmatterMatch[1].match(/description:\s*["']?(.+?)["']?\s*$/m);
+    return descMatch ? descMatch[1] : fallback;
+}
+function generateCommandAlias(commandName, description) {
+    return [
+        '---',
+        `description: "${description}"`,
+        '---',
+        `Invoke the specflow:${commandName} skill.`,
+        '',
+    ].join('\n');
+}
+async function generateClaude(ctx) {
+    const { projectRoot, packageRoot } = ctx;
+    const skillsSourceDir = join(packageRoot, 'skills');
+    const skillsDestDir = join(projectRoot, '.claude', 'skills');
+    const commandsDestDir = join(projectRoot, '.claude', 'commands', 'specflow');
+    await fs.mkdir(commandsDestDir, { recursive: true });
+    for (const command of COMMAND_CATALOG) {
+        const skillDirName = `specflow-${command.id}`;
+        const srcSkillMd = join(skillsSourceDir, skillDirName, 'SKILL.md');
+        const destSkillDir = join(skillsDestDir, skillDirName);
+        await fs.mkdir(destSkillDir, { recursive: true });
+        let description = command.description;
+        try {
+            const content = await fs.readFile(srcSkillMd, 'utf-8');
+            await fs.writeFile(join(destSkillDir, 'SKILL.md'), renderIdeContent(content, 'claude'), 'utf-8');
+            description = extractSkillDescription(content, command.description);
+        }
+        catch {
+            const placeholder = [
+                '---',
+                `name: ${skillDirName}`,
+                `description: "${command.description}"`,
+                '---',
+                '',
+                `# SpecFlow: ${command.id}`,
+                '',
+                'Skill content pending.',
+                '',
+            ].join('\n');
+            await fs.writeFile(join(destSkillDir, 'SKILL.md'), renderIdeContent(placeholder, 'claude'), 'utf-8');
+        }
+        await fs.writeFile(join(commandsDestDir, `${command.id}.md`), generateCommandAlias(command.id, description), 'utf-8');
+    }
+    const runtimePaths = await copyRuntimeAssets(packageRoot, projectRoot, 'claude');
+    return {
+        ide: 'claude',
+        generatedPaths: ['.claude/skills', '.claude/commands/specflow', ...runtimePaths],
+    };
+}
+async function inspectClaude(projectRoot) {
+    const commandDir = join(projectRoot, '.claude', 'commands', 'specflow');
+    const skillDir = join(projectRoot, '.claude', 'skills');
+    const promptsDir = join(projectRoot, '.claude', 'specflow', 'prompts');
+    const schemasDir = join(projectRoot, '.claude', 'specflow', 'schemas');
+    const templatesDir = join(projectRoot, '.claude', 'specflow', 'templates');
+    const supported = [];
+    const skillContentsByCommand = {};
+    for (const command of COMMAND_CATALOG) {
+        try {
+            const stat = await fs.stat(join(commandDir, `${command.id}.md`));
+            if (stat.isFile()) {
+                supported.push(command.id);
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            skillContentsByCommand[command.id] = await fs.readFile(join(skillDir, `specflow-${command.id}`, 'SKILL.md'), 'utf-8');
+        }
+        catch {
+            skillContentsByCommand[command.id] = '';
+        }
+    }
+    return {
+        ide: 'claude',
+        supportedCommandIds: supported,
+        supportedCapabilityIds: deriveCapabilityIds(supported, skillContentsByCommand),
+        assets: {
+            commandsDir: { exists: await directoryExists(commandDir), hash: await hashDirectoryTree(commandDir) },
+            skillsDir: { exists: await directoryExists(skillDir), hash: await hashDirectoryTree(skillDir) },
+            runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
+            runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
+            runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+        },
+    };
+}
+export const claudeAdapter = {
+    ide: 'claude',
+    generate: generateClaude,
+    inspect: inspectClaude,
+};

package/dist/integrations/codex/adapter.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from '../shared/types.js';
+export declare const codexAdapter: Adapter;

package/dist/integrations/codex/adapter.js

@@ -0,0 +1,141 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { COMMAND_CATALOG } from '../shared/command-catalog.js';
+import { directoryExists, hashDirectoryTree, hashFile } from '../shared/asset-hash.js';
+import { deriveCapabilityIds } from '../shared/capability-evidence.js';
+import { managedBlockPresent, upsertManagedBlock } from '../shared/marker-write.js';
+import { copyRuntimeAssets } from '../shared/runtime-assets.js';
+import { renderIdeContent, validateSkillFrontmatter } from '../shared/skill-renderer.js';
+const CODEX_AGENTS_MARKER_START = '# Added by specflow init (Codex context)';
+const CODEX_AGENTS_MARKER_END = '# End specflow init (Codex context)';
+function extractSkillDescription(content, fallback) {
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+        return fallback;
+    }
+    const descMatch = frontmatterMatch[1].match(/description:\s*["']?(.+?)["']?\s*$/m);
+    return descMatch ? descMatch[1] : fallback;
+}
+function titleCaseCommandId(commandId) {
+    return commandId.charAt(0).toUpperCase() + commandId.slice(1);
+}
+function renderOpenAiYaml(commandId, description) {
+    return [
+        'interface:',
+        `  display_name: "SpecFlow: ${titleCaseCommandId(commandId)}"`,
+        `  short_description: "${description.replace(/"/g, '\\"')}"`,
+        'policy:',
+        '  allow_implicit_invocation: true',
+        '',
+    ].join('\n');
+}
+function renderCodexAgentsBlock() {
+    return [
+        '# SpecFlow Codex Context',
+        '',
+        '- Respect specflow phase gates: plan -> refined -> built -> archived',
+        '- Never bypass CLI validation and archive checks',
+        '- Use artifacts under specflow/changes/<change>/ before coding',
+        '- Workflow skills: $specflow-plan, $specflow-refine, $specflow-build, $specflow-review, $specflow-test, $specflow-verify, $specflow-done, $specflow-fix, $specflow-snap',
+        '- Runtime prompts live under .agents/specflow/prompts/',
+        '',
+    ].join('\n');
+}
+async function generateCodex(ctx) {
+    const { projectRoot, packageRoot } = ctx;
+    const skillsSourceDir = join(packageRoot, 'skills');
+    const skillsDestDir = join(projectRoot, '.agents', 'skills');
+    for (const command of COMMAND_CATALOG) {
+        const skillDirName = `specflow-${command.id}`;
+        const srcSkillMd = join(skillsSourceDir, skillDirName, 'SKILL.md');
+        const destSkillDir = join(skillsDestDir, skillDirName);
+        const agentsMetaDir = join(destSkillDir, 'agents');
+        await fs.mkdir(agentsMetaDir, { recursive: true });
+        let description = command.description;
+        try {
+            const content = await fs.readFile(srcSkillMd, 'utf-8');
+            const rendered = renderIdeContent(content, 'codex');
+            validateSkillFrontmatter(rendered, skillDirName);
+            await fs.writeFile(join(destSkillDir, 'SKILL.md'), rendered, 'utf-8');
+            description = extractSkillDescription(content, command.description);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('frontmatter')) {
+                throw error;
+            }
+            const placeholder = [
+                '---',
+                `name: ${skillDirName}`,
+                `description: "${command.description}"`,
+                '---',
+                '',
+                `# SpecFlow: ${command.id}`,
+                '',
+                'Skill content pending.',
+                '',
+            ].join('\n');
+            const rendered = renderIdeContent(placeholder, 'codex');
+            validateSkillFrontmatter(rendered, skillDirName);
+            await fs.writeFile(join(destSkillDir, 'SKILL.md'), rendered, 'utf-8');
+        }
+        await fs.writeFile(join(agentsMetaDir, 'openai.yaml'), renderOpenAiYaml(command.id, description), 'utf-8');
+    }
+    const runtimePaths = await copyRuntimeAssets(packageRoot, projectRoot, 'codex');
+    await upsertManagedBlock(join(projectRoot, 'AGENTS.md'), CODEX_AGENTS_MARKER_START, CODEX_AGENTS_MARKER_END, renderCodexAgentsBlock().split('\n'));
+    return {
+        ide: 'codex',
+        generatedPaths: ['.agents/skills', 'AGENTS.md', ...runtimePaths],
+    };
+}
+async function inspectCodex(projectRoot) {
+    const skillDir = join(projectRoot, '.agents', 'skills');
+    const agentsFile = join(projectRoot, 'AGENTS.md');
+    const promptsDir = join(projectRoot, '.agents', 'specflow', 'prompts');
+    const schemasDir = join(projectRoot, '.agents', 'specflow', 'schemas');
+    const templatesDir = join(projectRoot, '.agents', 'specflow', 'templates');
+    let agentsFileExists = false;
+    try {
+        const agentsContent = await fs.readFile(agentsFile, 'utf-8');
+        agentsFileExists = managedBlockPresent(agentsContent, CODEX_AGENTS_MARKER_START, CODEX_AGENTS_MARKER_END);
+    }
+    catch {
+        agentsFileExists = false;
+    }
+    const supported = [];
+    const skillContentsByCommand = {};
+    for (const command of COMMAND_CATALOG) {
+        const skillPath = join(skillDir, `specflow-${command.id}`, 'SKILL.md');
+        try {
+            const stat = await fs.stat(skillPath);
+            if (stat.isFile()) {
+                supported.push(command.id);
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            skillContentsByCommand[command.id] = await fs.readFile(skillPath, 'utf-8');
+        }
+        catch {
+            skillContentsByCommand[command.id] = '';
+        }
+    }
+    return {
+        ide: 'codex',
+        supportedCommandIds: supported,
+        supportedCapabilityIds: deriveCapabilityIds(supported, skillContentsByCommand),
+        assets: {
+            skillsDir: { exists: await directoryExists(skillDir), hash: await hashDirectoryTree(skillDir) },
+            agentsFile: { exists: agentsFileExists, hash: agentsFileExists ? await hashFile(agentsFile) : undefined },
+            runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
+            runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
+            runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+        },
+    };
+}
+export const codexAdapter = {
+    ide: 'codex',
+    generate: generateCodex,
+    inspect: inspectCodex,
+};

package/dist/integrations/cursor/adapter.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from '../shared/types.js';
+export declare const cursorAdapter: Adapter;