specsmd 0.0.1

package/lib/installers/GeminiInstaller.js

@@ -0,0 +1,75 @@
+const ToolInstaller = require('./ToolInstaller');
+const fs = require('fs-extra');
+const path = require('path');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
+
+class GeminiInstaller extends ToolInstaller {
+    get key() {
+        return 'gemini';
+    }
+
+    get name() {
+        return 'Gemini CLI';
+    }
+
+    get commandsDir() {
+        return path.join('.gemini', 'commands');
+    }
+
+    get detectPath() {
+        return '.gemini';
+    }
+
+    /**
+     * Override to convert markdown to TOML format for Gemini CLI
+     */
+    async installCommands(flowPath, config) {
+        const targetDir = this.commandsDir;
+        console.log(theme.dim(`  Installing commands to ${targetDir}/...`));
+        await fs.ensureDir(targetDir);
+
+        const sourceDir = path.join(flowPath, 'commands');
+
+        if (!await fs.pathExists(sourceDir)) {
+            console.log(theme.dim(`  No commands folder found at ${sourceDir}`));
+            return [];
+        }
+
+        const files = await fs.readdir(sourceDir);
+        const installedFiles = [];
+
+        for (const file of files) {
+            if (file.endsWith('.md')) {
+                const sourcePath = path.join(sourceDir, file);
+                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+
+                // Transform .md to .toml for Gemini CLI
+                const targetFileName = `specsmd-${prefix}${file}`.replace(/\.md$/, '.toml');
+                const targetPath = path.join(targetDir, targetFileName);
+
+                // Read source content
+                const content = await fs.readFile(sourcePath, 'utf8');
+
+                // Extract description from filename (e.g., "master-agent" -> "Master Agent")
+                const agentName = file.replace(/\.md$/, '').replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+
+                // Convert to TOML format
+                const tomlContent = `description = "specsmd ${agentName}"
+prompt = """
+${content}
+"""`;
+
+                await fs.writeFile(targetPath, tomlContent);
+                installedFiles.push(targetFileName);
+            }
+        }
+
+        if (installedFiles.length > 0) {
+            CLIUtils.displayStatus('', `Installed ${installedFiles.length} commands for ${this.name}`, 'success');
+        }
+        return installedFiles;
+    }
+}
+
+module.exports = GeminiInstaller;

package/lib/installers/KiroInstaller.js

@@ -0,0 +1,22 @@
+const ToolInstaller = require('./ToolInstaller');
+const path = require('path');
+
+class KiroInstaller extends ToolInstaller {
+    get key() {
+        return 'kiro';
+    }
+
+    get name() {
+        return 'Kiro CLI';
+    }
+
+    get commandsDir() {
+        return path.join('.kiro', 'steering');
+    }
+
+    get detectPath() {
+        return '.kiro';
+    }
+}
+
+module.exports = KiroInstaller;

package/lib/installers/OpenCodeInstaller.js

@@ -0,0 +1,22 @@
+const ToolInstaller = require('./ToolInstaller');
+const path = require('path');
+
+class OpenCodeInstaller extends ToolInstaller {
+    get key() {
+        return 'opencode';
+    }
+
+    get name() {
+        return 'OpenCode';
+    }
+
+    get commandsDir() {
+        return path.join('.opencode', 'agent');
+    }
+
+    get detectPath() {
+        return '.opencode';
+    }
+}
+
+module.exports = OpenCodeInstaller;

package/lib/installers/RooInstaller.js

@@ -0,0 +1,22 @@
+const ToolInstaller = require('./ToolInstaller');
+const path = require('path');
+
+class RooInstaller extends ToolInstaller {
+    get key() {
+        return 'roo';
+    }
+
+    get name() {
+        return 'Roo Code';
+    }
+
+    get commandsDir() {
+        return path.join('.roo', 'commands');
+    }
+
+    get detectPath() {
+        return '.roo';
+    }
+}
+
+module.exports = RooInstaller;

package/lib/installers/ToolInstaller.js

@@ -0,0 +1,73 @@
+const fs = require('fs-extra');
+const path = require('path');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
+
+/**
+ * Base class for Agentic Coding Tool Installers
+ */
+class ToolInstaller {
+    constructor() {
+        if (this.constructor === ToolInstaller) {
+            throw new Error("Abstract classes can't be instantiated.");
+        }
+    }
+
+    get key() {
+        throw new Error("Method 'key' must be implemented.");
+    }
+
+    get name() {
+        throw new Error("Method 'name' must be implemented.");
+    }
+
+    get commandsDir() {
+        throw new Error("Method 'commandsDir' must be implemented.");
+    }
+
+    get detectPath() {
+        throw new Error("Method 'detectPath' must be implemented.");
+    }
+
+    async detect() {
+        return await fs.pathExists(this.detectPath);
+    }
+
+    async installCommands(flowPath, config) {
+        const targetCommandsDir = this.commandsDir;
+        console.log(theme.dim(`  Installing commands to ${targetCommandsDir}/...`));
+        await fs.ensureDir(targetCommandsDir);
+
+        const commandsSourceDir = path.join(flowPath, 'commands');
+
+        if (!await fs.pathExists(commandsSourceDir)) {
+            console.log(theme.warning(`  No commands folder found at ${commandsSourceDir}`));
+            return [];
+        }
+
+        const commandFiles = await fs.readdir(commandsSourceDir);
+        const installedFiles = [];
+
+        for (const cmdFile of commandFiles) {
+            if (cmdFile.endsWith('.md')) {
+                try {
+                    const sourcePath = path.join(commandsSourceDir, cmdFile);
+                    const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+                    const targetFileName = `specsmd-${prefix}${cmdFile}`;
+                    const targetPath = path.join(targetCommandsDir, targetFileName);
+
+                    const content = await fs.readFile(sourcePath, 'utf8');
+                    await fs.outputFile(targetPath, content, 'utf8');
+                    installedFiles.push(targetFileName);
+                } catch (err) {
+                    console.log(theme.warning(`  Failed to install ${cmdFile}: ${err.message}`));
+                }
+            }
+        }
+
+        CLIUtils.displayStatus('', `Installed ${installedFiles.length} commands for ${this.name}`, 'success');
+        return installedFiles;
+    }
+}
+
+module.exports = ToolInstaller;

package/lib/installers/WindsurfInstaller.js

@@ -0,0 +1,76 @@
+const ToolInstaller = require('./ToolInstaller');
+const fs = require('fs-extra');
+const path = require('path');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
+
+class WindsurfInstaller extends ToolInstaller {
+    get key() {
+        return 'windsurf';
+    }
+
+    get name() {
+        return 'Windsurf';
+    }
+
+    get commandsDir() {
+        return path.join('.windsurf', 'workflows');
+    }
+
+    get detectPath() {
+        return '.windsurf';
+    }
+
+    /**
+     * Override to add frontmatter for Windsurf workflows
+     */
+    async installCommands(flowPath, config) {
+        const targetCommandsDir = this.commandsDir;
+        console.log(theme.dim(`  Installing workflows to ${targetCommandsDir}/...`));
+        await fs.ensureDir(targetCommandsDir);
+
+        const commandsSourceDir = path.join(flowPath, 'commands');
+
+        if (!await fs.pathExists(commandsSourceDir)) {
+            console.log(theme.warning(`  No commands folder found at ${commandsSourceDir}`));
+            return [];
+        }
+
+        const commandFiles = await fs.readdir(commandsSourceDir);
+        const installedFiles = [];
+
+        for (const cmdFile of commandFiles) {
+            if (cmdFile.endsWith('.md')) {
+                const sourcePath = path.join(commandsSourceDir, cmdFile);
+                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+
+                const targetFileName = `specsmd-${prefix}${cmdFile}`;
+                const targetPath = path.join(targetCommandsDir, targetFileName);
+
+                // Extract agent name from target filename (e.g., "specsmd-master-agent.md" -> "specsmd-master-agent")
+                const agentName = targetFileName.replace(/\.md$/, '');
+
+                // Read source content and add Windsurf frontmatter
+                let content = await fs.readFile(sourcePath, 'utf8');
+
+                // Add Windsurf-specific frontmatter if not present
+                if (!content.startsWith('---')) {
+                    const frontmatter = `---
+description: ${agentName}
+---
+
+`;
+                    content = frontmatter + content;
+                }
+
+                await fs.writeFile(targetPath, content);
+                installedFiles.push(targetFileName);
+            }
+        }
+
+        CLIUtils.displayStatus('', `Installed ${installedFiles.length} workflows for ${this.name}`, 'success');
+        return installedFiles;
+    }
+}
+
+module.exports = WindsurfInstaller;

package/lib/markdown-validator.ts

@@ -0,0 +1,175 @@
+/**
+ * Template-based markdown validator
+ * Validates markdown files against YAML schema definitions
+ */
+
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { visit } from 'unist-util-visit';
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import type { Root, Heading, Text } from 'mdast';
+
+// Schema types
+export interface SectionRequirement {
+  heading: string;
+  children?: string[];
+}
+
+export interface MarkdownSchema {
+  name: string;
+  description: string;
+  file_pattern: string;
+  required_sections: SectionRequirement[];
+  optional_sections?: SectionRequirement[];
+  rules?: {
+    min_content_length?: number;
+    must_start_with_h1?: boolean;
+  };
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  file?: string;
+}
+
+/**
+ * Extract all headings from markdown AST
+ */
+function extractHeadings(tree: Root): { text: string; depth: number }[] {
+  const headings: { text: string; depth: number }[] = [];
+
+  visit(tree, 'heading', (node: Heading) => {
+    const text = node.children
+      .filter((child): child is Text => child.type === 'text')
+      .map(child => child.value)
+      .join('');
+    headings.push({ text, depth: node.depth });
+  });
+
+  return headings;
+}
+
+/**
+ * Normalize heading for comparison
+ */
+function normalizeHeading(heading: string): string {
+  return heading.toLowerCase().replace(/^#+\s*/, '').trim();
+}
+
+/**
+ * Check if headings contain a section
+ */
+function hasSection(
+  headings: { text: string; depth: number }[],
+  sectionPattern: string
+): boolean {
+  const normalized = normalizeHeading(sectionPattern);
+  return headings.some(h => normalizeHeading(h.text).includes(normalized));
+}
+
+/**
+ * Validate markdown content against a schema
+ */
+export function validateMarkdown(
+  content: string,
+  schema: MarkdownSchema,
+  fileName?: string
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const prefix = fileName ? `${fileName}: ` : '';
+
+  // Parse markdown
+  const tree = unified().use(remarkParse).parse(content) as Root;
+  const headings = extractHeadings(tree);
+
+  // Check required sections
+  for (const req of schema.required_sections) {
+    const sectionExists = hasSection(headings, req.heading);
+
+    if (!sectionExists) {
+      errors.push(`${prefix}Missing required section "${req.heading}"`);
+    } else if (req.children) {
+      // Check child sections
+      for (const child of req.children) {
+        if (!hasSection(headings, child)) {
+          errors.push(`${prefix}Missing required subsection "${child}"`);
+        }
+      }
+    }
+  }
+
+  // Check optional sections (warnings only)
+  if (schema.optional_sections) {
+    for (const opt of schema.optional_sections) {
+      if (!hasSection(headings, opt.heading)) {
+        warnings.push(`${prefix}Missing optional section "${opt.heading}"`);
+      }
+    }
+  }
+
+  // Check rules
+  if (schema.rules) {
+    if (schema.rules.min_content_length && content.length < schema.rules.min_content_length) {
+      errors.push(`${prefix}Content too short (${content.length} < ${schema.rules.min_content_length})`);
+    }
+
+    if (schema.rules.must_start_with_h1) {
+      const firstHeading = headings[0];
+      if (!firstHeading || firstHeading.depth !== 1) {
+        errors.push(`${prefix}Must start with H1 heading`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    file: fileName,
+  };
+}
+
+/**
+ * Load a schema from YAML file
+ */
+export function loadSchema(schemaPath: string): MarkdownSchema {
+  const content = fs.readFileSync(schemaPath, 'utf-8');
+  return yaml.load(content) as MarkdownSchema;
+}
+
+/**
+ * Validate a file against a schema
+ */
+export function validateFile(
+  filePath: string,
+  schema: MarkdownSchema
+): ValidationResult {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return validateMarkdown(content, schema, filePath);
+}
+
+/**
+ * Validate multiple files against a schema
+ */
+export function validateFiles(
+  filePaths: string[],
+  schema: MarkdownSchema
+): { results: ValidationResult[]; summary: ValidationResult } {
+  const results = filePaths.map(fp => validateFile(fp, schema));
+
+  const allErrors = results.flatMap(r => r.errors);
+  const allWarnings = results.flatMap(r => r.warnings);
+
+  return {
+    results,
+    summary: {
+      valid: allErrors.length === 0,
+      errors: allErrors,
+      warnings: allWarnings,
+    },
+  };
+}

package/lib/yaml-validator.ts

@@ -0,0 +1,99 @@
+/**
+ * Simple YAML config validator
+ * Validates required keys and structure without strict schema
+ */
+
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+
+export interface YamlSchema {
+  name: string;
+  description?: string;
+  required_keys: string[];
+  nested_required?: Record<string, string[]>;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  file?: string;
+}
+
+/**
+ * Check if an object has a key (supports dot notation)
+ */
+function hasKey(obj: Record<string, unknown>, key: string): boolean {
+  const parts = key.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return false;
+    }
+    if (!(part in (current as Record<string, unknown>))) {
+      return false;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return true;
+}
+
+/**
+ * Validate YAML content against a schema
+ */
+export function validateYaml(
+  content: Record<string, unknown>,
+  schema: YamlSchema,
+  fileName?: string
+): ValidationResult {
+  const errors: string[] = [];
+  const prefix = fileName ? `${fileName}: ` : '';
+
+  // Check required keys
+  for (const key of schema.required_keys) {
+    if (!hasKey(content, key)) {
+      errors.push(`${prefix}Missing required key "${key}"`);
+    }
+  }
+
+  // Check nested required keys
+  if (schema.nested_required) {
+    for (const [parent, children] of Object.entries(schema.nested_required)) {
+      if (hasKey(content, parent)) {
+        for (const child of children) {
+          const fullKey = `${parent}.${child}`;
+          if (!hasKey(content, fullKey)) {
+            errors.push(`${prefix}Missing required key "${fullKey}"`);
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    file: fileName,
+  };
+}
+
+/**
+ * Validate a YAML file against a schema
+ */
+export function validateYamlFile(
+  filePath: string,
+  schema: YamlSchema
+): ValidationResult {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const parsed = yaml.load(content) as Record<string, unknown>;
+  return validateYaml(parsed, schema, filePath);
+}
+
+/**
+ * Load a schema from YAML file
+ */
+export function loadYamlSchema(schemaPath: string): YamlSchema {
+  const content = fs.readFileSync(schemaPath, 'utf-8');
+  return yaml.load(content) as YamlSchema;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "specsmd",
+  "version": "0.0.1",
+  "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
+  "main": "lib/installer.js",
+  "bin": {
+    "specsmd": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:schema": "vitest run __tests__/unit/schema-validation/",
+    "lint:md": "markdownlint 'specs/**/*.md' 'flows/**/*.md' --config ../.markdownlint.yaml",
+    "lint:md:fix": "markdownlint 'specs/**/*.md' 'flows/**/*.md' --config ../.markdownlint.yaml --fix",
+    "validate": "npm run test:schema && npm run lint:md"
+  },
+  "keywords": [
+    "ai-dlc",
+    "agile",
+    "sdlc",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "ai-native",
+    "agents",
+    "workflow"
+  ],
+  "author": "specsmd team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fabriqaai/specsmd.git"
+  },
+  "files": [
+    "bin/",
+    "flows/",
+    "lib/",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "figlet": "^1.9.4",
+    "fs-extra": "^11.1.1",
+    "gradient-string": "^2.0.2",
+    "js-yaml": "^4.1.0",
+    "oh-my-logo": "^0.4.0",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.10.2",
+    "glob": "^13.0.0",
+    "markdownlint": "^0.40.0",
+    "markdownlint-cli": "^0.46.0",
+    "remark-parse": "^11.0.0",
+    "typescript": "^5.9.3",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "vitest": "^4.0.15"
+  }
+}