Skill Builder

#!/usr/bin/env -S deno run --allow-read --allow-write

/**
 * Skill Scaffolder
 *
 * Generates skill directory structure and template files.
 * Creates SKILL.md, scripts/, and data/ directories with templates.
 *
 * Usage:
 *   deno run --allow-read --allow-write scaffold.ts skill-name
 *   deno run --allow-read --allow-write scaffold.ts skill-name --type diagnostic
 *   deno run --allow-read --allow-write scaffold.ts skill-name --dry-run
 */

interface ScaffoldConfig {
  skillName: string;
  skillType: "diagnostic" | "generator" | "utility";
  statePrefix: string;
  stateCount: number;
  includeScript: boolean;
  includeData: boolean;
  domain: string;
  cluster: string | null;
  outputDir: string;
}

const SKILL_TYPES = ["diagnostic", "generator", "utility"];

function toTitleCase(str: string): string {
  return str
    .split("-")
    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
    .join(" ");
}

function toPrefix(str: string): string {
  // First letter of each word, uppercase
  const words = str.split("-");
  if (words.length === 1) {
    return str.charAt(0).toUpperCase();
  }
  return words.map((w) => w.charAt(0).toUpperCase()).join("");
}

function generateSkillMd(config: ScaffoldConfig): string {
  const title = toTitleCase(config.skillName);
  const prefix = config.statePrefix;

  let content = `---
name: ${config.skillName}
description: [TODO: One sentence starting with action verb - "Diagnose...", "Generate...", "Transform..."]
license: MIT
metadata:
  author: [TODO: your-name]
  version: "1.0"
  domain: ${config.domain}
`;

  if (config.cluster) {
    content += `  cluster: ${config.cluster}\n`;
  }

  if (config.skillType === "utility") {
    content += `  type: utility\n`;
  }

  content += `---

# ${title}: [Subtitle]

You [TODO: role description]. Your role is to [TODO: specific function].

## Core Principle

**[TODO: Bold statement capturing the diagnostic/functional essence]**

## The States

`;

  // Generate state templates
  for (let i = 1; i <= config.stateCount; i++) {
    content += `### State ${prefix}${i}: [State Name]
**Symptoms:** [What the user notices]
**Key Questions:** [What to ask to diagnose]
**Interventions:** [What framework/tool to apply]

`;
  }

  content += `## Diagnostic Process

When a writer presents a ${config.skillName.replace("-", " ")} problem:

1. **Listen for symptoms** - What specifically feels wrong?
2. **Identify the state** - Match symptoms to states above
3. **Ask key questions** - Gather information needed for diagnosis
4. **Recommend intervention** - Point to specific framework/tool
5. **Suggest first step** - What's the minimal viable fix?

## Key Questions

### For [Category A]
- [Question 1]?
- [Question 2]?
- [Question 3]?

### For [Category B]
- [Question 4]?
- [Question 5]?
- [Question 6]?

## Anti-Patterns

### The [Anti-Pattern Name]
**Problem:** [What goes wrong]
**Fix:** [How to fix it]

### The [Another Anti-Pattern]
**Problem:** [What goes wrong]
**Fix:** [How to fix it]

`;

  if (config.includeScript) {
    content += `## Available Tools

### ${config.skillName.replace(/-/g, "_")}.ts
[TODO: Description of what this script does]

\`\`\`bash
deno run --allow-read scripts/${config.skillName.replace(/-/g, "_")}.ts
deno run --allow-read scripts/${config.skillName.replace(/-/g, "_")}.ts --option value
\`\`\`

**Output:** [What the script produces]

`;
  }

  content += `## Example Interaction

**Writer:** "[Example problem statement]"

**Your approach:**
1. Identify State ${prefix}[N] ([State Name])
2. Ask: "[Clarifying question]"
3. [Action you take]
4. Suggest: "[Specific recommendation]"

## What You Do NOT Do

- You do not [boundary 1]
- You do not [boundary 2]
- You diagnose, recommend, and explain—the writer decides

## Integration with story-sense

| story-sense State | May Lead to ${title} |
|-------------------|${"-".repeat(title.length + 14)}|
| State [N] | ${prefix}[N] when [condition] |

## Integration with [Other Skill]

[TODO: How this skill connects to other skills in the cluster]
`;

  return content;
}

function generateScriptTemplate(skillName: string): string {
  const scriptName = skillName.replace(/-/g, "_");
  const resultType = toTitleCase(skillName).replace(/ /g, "") + "Result";

  return `#!/usr/bin/env -S deno run --allow-read

/**
 * ${toTitleCase(skillName)} Generator
 *
 * [TODO: Description of what this script does]
 *
 * Usage:
 *   deno run --allow-read ${scriptName}.ts
 *   deno run --allow-read ${scriptName}.ts --option value
 *   deno run --allow-read ${scriptName}.ts "input" --json
 */

// === INTERFACES ===

interface ${resultType} {
  name: string;
  // TODO: Add result fields
}

// === DATA ===

const DATA: Record<string, string[]> = {
  category_one: [
    "Item with specific detail",
    "Another concrete item",
    // TODO: Add more items (target 30+ for functional, 75+ for production)
  ],
};

// === UTILITIES ===

function randomFrom<T>(arr: T[], count: number = 1): T[] {
  const shuffled = [...arr].sort(() => Math.random() - 0.5);
  return shuffled.slice(0, Math.min(count, arr.length));
}

// === CORE LOGIC ===

function generate(
  input: string | null,
  option: string | null
): ${resultType} {
  // TODO: Implement generation logic

  return {
    name: input || "Default",
  };
}

// === FORMATTING ===

function formatResult(result: ${resultType}): string {
  const lines: string[] = [];

  lines.push(\`# ${toTitleCase(skillName)}: \${result.name}\\n\`);
  lines.push("## Section\\n");
  lines.push("[TODO: Format output]");
  lines.push("");

  return lines.join("\\n");
}

// === MAIN ===

function main(): void {
  const args = Deno.args;

  if (args.includes("--help") || args.includes("-h")) {
    console.log(\`${toTitleCase(skillName)} Generator

[TODO: Description]

Usage:
  deno run --allow-read ${scriptName}.ts [options] [input]

Options:
  --option S    [Description]
  --json        Output as JSON

Examples:
  deno run --allow-read ${scriptName}.ts
  deno run --allow-read ${scriptName}.ts "Custom Input"
\`);
    Deno.exit(0);
  }

  // Parse arguments
  const optionIndex = args.indexOf("--option");
  const jsonOutput = args.includes("--json");

  const option = optionIndex !== -1 && args[optionIndex + 1]
    ? args[optionIndex + 1]
    : null;

  // Find positional argument
  const skipIndices = new Set<number>();
  if (optionIndex !== -1) {
    skipIndices.add(optionIndex);
    skipIndices.add(optionIndex + 1);
  }

  let positionalArg: string | null = null;
  for (let i = 0; i < args.length; i++) {
    if (!args[i].startsWith("--") && !skipIndices.has(i)) {
      positionalArg = args[i];
      break;
    }
  }

  // Generate
  const result = generate(positionalArg, option);

  // Output
  if (jsonOutput) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log(formatResult(result));
  }
}

main();
`;
}

function generateDataTemplate(skillName: string): string {
  return JSON.stringify(
    {
      _meta: {
        description: `Data for ${toTitleCase(skillName)} skill`,
        usage: "Load with Deno.readTextFile and JSON.parse",
      },
      category_one: [
        "Specific item with enough detail to spark ideas",
        "Another item that is 20-60 characters ideally",
        "Items should be concrete not vague",
      ],
      category_two: [
        "Different category of items",
        "Organized by type for easier selection",
      ],
    },
    null,
    2
  );
}

async function createDirectory(path: string, dryRun: boolean): Promise<void> {
  if (dryRun) {
    console.log(`  [dry-run] Would create directory: ${path}`);
    return;
  }

  try {
    await Deno.mkdir(path, { recursive: true });
    console.log(`  Created directory: ${path}`);
  } catch (e) {
    if (!(e instanceof Deno.errors.AlreadyExists)) {
      throw e;
    }
  }
}

async function writeFile(
  path: string,
  content: string,
  dryRun: boolean
): Promise<void> {
  if (dryRun) {
    console.log(`  [dry-run] Would create file: ${path}`);
    console.log(`  [dry-run] Content preview: ${content.slice(0, 100)}...`);
    return;
  }

  // Check if file exists
  try {
    await Deno.stat(path);
    console.log(`  Skipped (exists): ${path}`);
    return;
  } catch {
    // File doesn't exist, create it
  }

  await Deno.writeTextFile(path, content);
  console.log(`  Created file: ${path}`);
}

async function scaffold(config: ScaffoldConfig, dryRun: boolean): Promise<void> {
  const skillDir = `${config.outputDir}/${config.skillName}`;

  console.log(`\nScaffolding skill: ${config.skillName}`);
  console.log(`Type: ${config.skillType}`);
  console.log(`Domain: ${config.domain}`);
  if (config.cluster) {
    console.log(`Cluster: ${config.cluster}`);
  }
  console.log(`Location: ${skillDir}\n`);

  // Create directories
  await createDirectory(skillDir, dryRun);
  await createDirectory(`${skillDir}/scripts`, dryRun);

  if (config.includeData) {
    await createDirectory(`${skillDir}/data`, dryRun);
  }

  // Create SKILL.md
  const skillMd = generateSkillMd(config);
  await writeFile(`${skillDir}/SKILL.md`, skillMd, dryRun);

  // Create script template
  if (config.includeScript) {
    const scriptName = config.skillName.replace(/-/g, "_");
    const script = generateScriptTemplate(config.skillName);
    await writeFile(`${skillDir}/scripts/${scriptName}.ts`, script, dryRun);
  }

  // Create data template
  if (config.includeData) {
    const data = generateDataTemplate(config.skillName);
    await writeFile(`${skillDir}/data/${config.skillName.replace(/-/g, "-")}-data.json`, data, dryRun);
  }

  console.log("\nScaffolding complete!");
  console.log("\nNext steps:");
  console.log("1. Edit SKILL.md - fill in [TODO] sections");
  console.log("2. Define your states with symptoms/questions/interventions");
  console.log("3. Implement script logic if applicable");
  console.log("4. Run validate-skill.ts to check completeness");
}

function main(): void {
  const args = Deno.args;

  if (args.includes("--help") || args.includes("-h")) {
    console.log(`Skill Scaffolder

Generates skill directory structure and template files.

Usage:
  deno run --allow-read --allow-write scaffold.ts <skill-name> [options]

Options:
  --type T      Skill type: diagnostic, generator, utility
                Default: diagnostic

  --domain D    Domain for the skill (fiction, research, agile-software, etc.)
                Default: custom

  --cluster C   Parent skill if part of a cluster (optional)

  --out O       Output directory for the skill
                Default: current directory

  --states N    Number of state templates to generate
                Default: 5

  --no-script   Don't create script template
  --no-data     Don't create data directory/template

  --dry-run     Preview without creating files

Examples:
  deno run --allow-read --allow-write scaffold.ts dialogue --domain fiction --cluster story-sense
  deno run --allow-read --allow-write scaffold.ts sprint-health --domain agile-software
  deno run --allow-read --allow-write scaffold.ts my-skill --dry-run
`);
    Deno.exit(0);
  }

  // Parse arguments
  const typeIndex = args.indexOf("--type");
  const statesIndex = args.indexOf("--states");
  const domainIndex = args.indexOf("--domain");
  const clusterIndex = args.indexOf("--cluster");
  const outIndex = args.indexOf("--out");
  const dryRun = args.includes("--dry-run");
  const noScript = args.includes("--no-script");
  const noData = args.includes("--no-data");

  const skillType = typeIndex !== -1 && args[typeIndex + 1]
    ? args[typeIndex + 1] as "diagnostic" | "generator" | "utility"
    : "diagnostic";

  const stateCount = statesIndex !== -1 && args[statesIndex + 1]
    ? parseInt(args[statesIndex + 1]) || 5
    : 5;

  const domain = domainIndex !== -1 && args[domainIndex + 1]
    ? args[domainIndex + 1]
    : "custom";

  const cluster = clusterIndex !== -1 && args[clusterIndex + 1]
    ? args[clusterIndex + 1]
    : null;

  const scriptDir = new URL(".", import.meta.url).pathname;
  const defaultOutDir = Deno.cwd();
  const outputDir = outIndex !== -1 && args[outIndex + 1]
    ? (args[outIndex + 1].startsWith("/") ? args[outIndex + 1] : `${scriptDir}${args[outIndex + 1]}`)
    : defaultOutDir;

  if (!SKILL_TYPES.includes(skillType)) {
    console.error(`Error: Invalid skill type '${skillType}'`);
    console.error(`Valid types: ${SKILL_TYPES.join(", ")}`);
    Deno.exit(1);
  }

  // Find skill name (first positional argument)
  const skipIndices = new Set<number>();
  if (typeIndex !== -1) {
    skipIndices.add(typeIndex);
    skipIndices.add(typeIndex + 1);
  }
  if (statesIndex !== -1) {
    skipIndices.add(statesIndex);
    skipIndices.add(statesIndex + 1);
  }
  if (domainIndex !== -1) {
    skipIndices.add(domainIndex);
    skipIndices.add(domainIndex + 1);
  }
  if (clusterIndex !== -1) {
    skipIndices.add(clusterIndex);
    skipIndices.add(clusterIndex + 1);
  }
  if (outIndex !== -1) {
    skipIndices.add(outIndex);
    skipIndices.add(outIndex + 1);
  }

  let skillName: string | null = null;
  for (let i = 0; i < args.length; i++) {
    if (!args[i].startsWith("--") && !skipIndices.has(i)) {
      skillName = args[i];
      break;
    }
  }

  if (!skillName) {
    console.error("Error: No skill name specified");
    console.error("Usage: scaffold.ts <skill-name>");
    Deno.exit(1);
  }

  // Validate skill name
  if (!/^[a-z][a-z0-9-]*$/.test(skillName)) {
    console.error("Error: Skill name must be lowercase with hyphens only");
    console.error("Example: my-skill-name");
    Deno.exit(1);
  }

  const config: ScaffoldConfig = {
    skillName,
    skillType,
    statePrefix: toPrefix(skillName),
    stateCount,
    includeScript: !noScript,
    includeData: !noData && skillType !== "utility",
    domain,
    cluster,
    outputDir,
  };

  scaffold(config, dryRun);
}

main();

#!/usr/bin/env -S deno run --allow-read

/**
 * Skill Validator
 *
 * Validates skill completeness and pattern conformance.
 * Checks for required frontmatter, state definitions, script docs, and integrations.
 *
 * Usage:
 *   deno run --allow-read validate-skill.ts ../worldbuilding
 *   deno run --allow-read validate-skill.ts --all
 *   deno run --allow-read validate-skill.ts ../conlang --json
 */

interface ValidationResult {
  skillPath: string;
  skillName: string;
  valid: boolean;
  score: number;
  maxScore: number;
  maturityScore: MaturityScore;
  maturityLevel: string;
  checks: CheckResult[];
  summary: string;
}

interface CheckResult {
  category: string;
  check: string;
  passed: boolean;
  message: string;
  weight: number;
  dimension?: "completeness" | "quality" | "usability";
}

interface MaturityScore {
  completeness: { score: number; max: number };
  quality: { score: number; max: number };
  usability: { score: number; max: number };
  total: number;
}

// Required frontmatter fields
const REQUIRED_FRONTMATTER = ["name", "description", "license"];
const REQUIRED_METADATA = ["author", "version", "domain"];
const REQUIRED_METADATA_NEW = ["type", "mode"]; // New required fields

// Valid type and mode values
const VALID_TYPES = ["diagnostic", "generator", "utility"];
const VALID_MODES = ["diagnostic", "assistive", "collaborative", "evaluative", "application", "generative"];

// Skill types detected from frontmatter
type SkillType = "diagnostic" | "generator" | "utility";

function detectSkillType(frontmatter: Record<string, unknown>): SkillType {
  const metadata = frontmatter.metadata as Record<string, string> | undefined;

  // Check for explicit type in metadata
  if (metadata?.type === "utility") return "utility";
  if (metadata?.type === "generator") return "generator";
  if (metadata?.type === "diagnostic") return "diagnostic";

  // Fallback detection based on mode
  if (metadata?.mode === "generative") return "generator";

  // Default to diagnostic
  return "diagnostic";
}

// Required sections vary by skill type
const REQUIRED_SECTIONS: Record<SkillType, string[]> = {
  diagnostic: [
    "Core Principle",
    "State",
    "Diagnostic Process",
    "What You Do NOT Do",
    "Integration",
  ],
  generator: [
    "Core Principle",
    "What You Do NOT Do",
  ],
  utility: [
    "Core Principle",
  ],
};

const RECOMMENDED_SECTIONS: Record<SkillType, string[]> = {
  diagnostic: [
    "Available Tools",
    "Anti-Pattern",
    "Example",
    "Key Question",
  ],
  generator: [
    "Available Tools",
    "Example",
    "Integration",
  ],
  utility: [
    "Available Tools",
    "Example",
    "Integration",
  ],
};

async function fileExists(path: string): Promise<boolean> {
  try {
    await Deno.stat(path);
    return true;
  } catch {
    return false;
  }
}

async function readSkillMd(skillPath: string): Promise<string | null> {
  const path = `${skillPath}/SKILL.md`;
  try {
    return await Deno.readTextFile(path);
  } catch {
    return null;
  }
}

function parseFrontmatter(content: string): Record<string, unknown> | null {
  const match = content.match(/^---\n([\s\S]*?)\n---/);
  if (!match) return null;

  const frontmatter: Record<string, unknown> = {};
  const lines = match[1].split("\n");

  let currentKey = "";
  let inMetadata = false;
  const metadata: Record<string, string> = {};

  for (const line of lines) {
    if (line.startsWith("metadata:")) {
      inMetadata = true;
      continue;
    }

    if (inMetadata && line.startsWith("  ")) {
      const metaMatch = line.match(/^\s+(\w+):\s*"?([^"]*)"?$/);
      if (metaMatch) {
        metadata[metaMatch[1]] = metaMatch[2];
      }
    } else if (!line.startsWith(" ")) {
      inMetadata = false;
      const keyMatch = line.match(/^(\w+):\s*(.*)$/);
      if (keyMatch) {
        currentKey = keyMatch[1];
        frontmatter[currentKey] = keyMatch[2].replace(/^"(.*)"$/, "$1");
      }
    }
  }

  if (Object.keys(metadata).length > 0) {
    frontmatter.metadata = metadata;
  }

  return frontmatter;
}

function checkSection(content: string, sectionName: string): boolean {
  // Look for ## Section or # Section patterns
  const pattern = new RegExp(`^##?\\s+.*${sectionName}`, "im");
  return pattern.test(content);
}

function countStates(content: string): number {
  // Count ### State patterns
  const matches = content.match(/^###\s+State\s+\w+\d+/gim);
  return matches ? matches.length : 0;
}

function hasStateComponents(content: string): {
  hasSymptoms: boolean;
  hasQuestions: boolean;
  hasInterventions: boolean;
} {
  return {
    hasSymptoms: /\*\*Symptoms:\*\*/i.test(content),
    hasQuestions: /\*\*Key Questions:\*\*/i.test(content),
    hasInterventions: /\*\*Interventions:\*\*/i.test(content),
  };
}

function countAntiPatterns(content: string): number {
  // Count ### The [Name] patterns in Anti-Patterns section
  const antiPatternSection = content.match(/## Anti-Patterns[\s\S]*?(?=\n## |$)/i);
  if (!antiPatternSection) return 0;

  const matches = antiPatternSection[0].match(/^###\s+The\s+/gim);
  return matches ? matches.length : 0;
}

function checkStateNamingConvention(content: string): {
  consistent: boolean;
  prefix: string | null;
  issues: string[];
} {
  const stateMatches = content.match(/^###\s+State\s+([A-Z]+)(\d+(?:\.\d+)?)/gim);
  if (!stateMatches || stateMatches.length === 0) {
    return { consistent: true, prefix: null, issues: [] };
  }

  const prefixes = new Set<string>();
  const issues: string[] = [];

  for (const match of stateMatches) {
    const prefixMatch = match.match(/State\s+([A-Z]+)\d/i);
    if (prefixMatch) {
      prefixes.add(prefixMatch[1].toUpperCase());
    }
  }

  if (prefixes.size > 1) {
    issues.push(`Multiple prefixes found: ${[...prefixes].join(", ")}`);
  }

  const prefix = prefixes.size === 1 ? [...prefixes][0] : null;
  return {
    consistent: prefixes.size <= 1,
    prefix,
    issues,
  };
}

function hasIntegrationGraph(content: string): {
  hasInbound: boolean;
  hasOutbound: boolean;
  hasComplementary: boolean;
} {
  const integrationSection = content.match(/## Integration[\s\S]*?(?=\n## |$)/i);
  if (!integrationSection) {
    return { hasInbound: false, hasOutbound: false, hasComplementary: false };
  }

  const section = integrationSection[0];
  return {
    hasInbound: /### Inbound/i.test(section) || /From Other Skills/i.test(section),
    hasOutbound: /### Outbound/i.test(section) || /To Other Skills/i.test(section),
    hasComplementary: /### Complementary/i.test(section) || /Complementary Skills/i.test(section),
  };
}

function hasOutputPersistence(content: string): boolean {
  return /## Output Persistence/i.test(content);
}

function hasQuickReference(content: string): boolean {
  return /## Quick Reference/i.test(content) || /### Quick Reference/i.test(content);
}

function hasDecisionTree(content: string): boolean {
  return /decision tree/i.test(content) || /routing logic/i.test(content) || /when to use/i.test(content);
}

function calculateMaturityLevel(score: number): string {
  if (score >= 18) return "Battle-Tested";
  if (score >= 13) return "Stable";
  if (score >= 8) return "Developing";
  return "Draft";
}

async function getScripts(skillPath: string): Promise<string[]> {
  const scriptsPath = `${skillPath}/scripts`;
  const scripts: string[] = [];

  try {
    for await (const entry of Deno.readDir(scriptsPath)) {
      if (entry.isFile && entry.name.endsWith(".ts")) {
        scripts.push(entry.name);
      }
    }
  } catch {
    // No scripts directory
  }

  return scripts;
}

async function getDataFiles(skillPath: string): Promise<string[]> {
  const dataPath = `${skillPath}/data`;
  const files: string[] = [];

  try {
    for await (const entry of Deno.readDir(dataPath)) {
      if (entry.isFile && entry.name.endsWith(".json")) {
        files.push(entry.name);
      }
    }
  } catch {
    // No data directory
  }

  return files;
}

function scriptDocumented(content: string, scriptName: string): boolean {
  const baseName = scriptName.replace(".ts", "");
  return content.includes(`${baseName}.ts`) || content.includes(`### ${baseName}`);
}

async function validateSkill(skillPath: string): Promise<ValidationResult> {
  const checks: CheckResult[] = [];
  const skillName = skillPath.split("/").pop() || "unknown";

  // Check SKILL.md exists
  const content = await readSkillMd(skillPath);
  if (!content) {
    return {
      skillPath,
      skillName,
      valid: false,
      score: 0,
      maxScore: 100,
      checks: [
        {
          category: "Structure",
          check: "SKILL.md exists",
          passed: false,
          message: "SKILL.md not found",
          weight: 20,
        },
      ],
      summary: "SKILL.md not found - cannot validate",
    };
  }

  checks.push({
    category: "Structure",
    check: "SKILL.md exists",
    passed: true,
    message: "SKILL.md found",
    weight: 5,
  });

  // Check frontmatter
  const frontmatter = parseFrontmatter(content);
  if (!frontmatter) {
    checks.push({
      category: "Frontmatter",
      check: "Valid frontmatter",
      passed: false,
      message: "Could not parse frontmatter",
      weight: 10,
    });
  } else {
    checks.push({
      category: "Frontmatter",
      check: "Valid frontmatter",
      passed: true,
      message: "Frontmatter parsed successfully",
      weight: 5,
    });

    // Check required fields
    for (const field of REQUIRED_FRONTMATTER) {
      const has = field in frontmatter;
      checks.push({
        category: "Frontmatter",
        check: `Has ${field}`,
        passed: has,
        message: has ? `${field} present` : `Missing ${field}`,
        weight: 3,
      });
    }

    // Check metadata
    const metadata = frontmatter.metadata as Record<string, string> | undefined;
    for (const field of REQUIRED_METADATA) {
      const has = metadata && field in metadata;
      checks.push({
        category: "Frontmatter",
        check: `Has metadata.${field}`,
        passed: !!has,
        message: has ? `metadata.${field} present` : `Missing metadata.${field}`,
        weight: 2,
      });
    }

    // Check new required metadata: type and mode
    for (const field of REQUIRED_METADATA_NEW) {
      const has = metadata && field in metadata;
      const value = metadata?.[field];
      let valid = false;
      let message = "";

      if (!has) {
        message = `Missing metadata.${field} (REQUIRED)`;
      } else if (field === "type") {
        valid = VALID_TYPES.includes(value);
        message = valid
          ? `type: ${value}`
          : `Invalid type: ${value}. Must be: ${VALID_TYPES.join(" | ")}`;
      } else if (field === "mode") {
        // Mode can be compound (e.g., "diagnostic+generative")
        const modes = value.split("+").map((m: string) => m.trim());
        valid = modes.every((m: string) => VALID_MODES.includes(m));
        message = valid
          ? `mode: ${value}`
          : `Invalid mode: ${value}. Must be: ${VALID_MODES.join(" | ")}`;
      }

      checks.push({
        category: "Frontmatter",
        check: `Has valid metadata.${field}`,
        passed: has && valid,
        message,
        weight: 3,
        dimension: "quality",
      });
    }
  }

  // Detect skill type for appropriate validation
  const skillType = frontmatter ? detectSkillType(frontmatter) : "diagnostic";

  checks.push({
    category: "Type",
    check: "Skill type detected",
    passed: true,
    message: `Detected as ${skillType} skill`,
    weight: 0, // Informational only
  });

  // Check required sections for this skill type
  for (const section of REQUIRED_SECTIONS[skillType]) {
    const has = checkSection(content, section);
    checks.push({
      category: "Structure",
      check: `Has ${section} section`,
      passed: has,
      message: has ? `${section} section found` : `Missing ${section} section`,
      weight: 5,
    });
  }

  // Check recommended sections for this skill type
  for (const section of RECOMMENDED_SECTIONS[skillType]) {
    const has = checkSection(content, section);
    checks.push({
      category: "Recommended",
      check: `Has ${section} section`,
      passed: has,
      message: has ? `${section} section found` : `Could add ${section} section`,
      weight: 2,
    });
  }

  // Only check states for diagnostic skills
  if (skillType === "diagnostic") {
    const stateCount = countStates(content);
    checks.push({
      category: "Diagnostic",
      check: "Has defined states",
      passed: stateCount >= 3,
      message:
        stateCount >= 3
          ? `${stateCount} states defined`
          : `Only ${stateCount} states (recommend 3-7)`,
      weight: 5,
    });

    // Check state components
    const components = hasStateComponents(content);
    checks.push({
      category: "Diagnostic",
      check: "States have symptoms",
      passed: components.hasSymptoms,
      message: components.hasSymptoms
        ? "States include symptoms"
        : "States missing symptoms",
      weight: 3,
    });
    checks.push({
      category: "Diagnostic",
      check: "States have key questions",
      passed: components.hasQuestions,
      message: components.hasQuestions
        ? "States include key questions"
        : "States missing key questions",
      weight: 3,
    });
    checks.push({
      category: "Diagnostic",
      check: "States have interventions",
      passed: components.hasInterventions,
      message: components.hasInterventions
        ? "States include interventions"
        : "States missing interventions",
      weight: 3,
      dimension: "completeness",
    });

    // Check state naming convention
    const stateNaming = checkStateNamingConvention(content);
    checks.push({
      category: "Quality",
      check: "Consistent state naming",
      passed: stateNaming.consistent,
      message: stateNaming.consistent
        ? stateNaming.prefix
          ? `Consistent prefix: ${stateNaming.prefix}`
          : "No states to check"
        : stateNaming.issues.join(", "),
      weight: 2,
      dimension: "quality",
    });
  }

  // Check anti-patterns (all skill types)
  const antiPatternCount = countAntiPatterns(content);
  const minAntiPatterns = skillType === "diagnostic" ? 3 : 2;
  checks.push({
    category: "Completeness",
    check: "Has anti-patterns",
    passed: antiPatternCount >= minAntiPatterns,
    message: antiPatternCount >= minAntiPatterns
      ? `${antiPatternCount} anti-patterns documented`
      : `Only ${antiPatternCount} anti-patterns (minimum: ${minAntiPatterns})`,
    weight: 4,
    dimension: "completeness",
  });

  // Check integration graph structure
  const integration = hasIntegrationGraph(content);
  const hasAnyIntegration = integration.hasInbound || integration.hasOutbound;
  checks.push({
    category: "Quality",
    check: "Has integration connections",
    passed: hasAnyIntegration,
    message: hasAnyIntegration
      ? `Integration: ${[
          integration.hasInbound ? "inbound" : "",
          integration.hasOutbound ? "outbound" : "",
          integration.hasComplementary ? "complementary" : "",
        ]
          .filter(Boolean)
          .join(", ")}`
      : "Missing integration connections (need inbound OR outbound)",
    weight: 2,
    dimension: "quality",
  });

  // Check usability features
  const hasOutput = hasOutputPersistence(content);
  checks.push({
    category: "Usability",
    check: "Has output persistence",
    passed: hasOutput,
    message: hasOutput
      ? "Output persistence section present"
      : "Missing output persistence section",
    weight: 2,
    dimension: "usability",
  });

  const hasQuickRef = hasQuickReference(content);
  checks.push({
    category: "Usability",
    check: "Has quick reference",
    passed: hasQuickRef,
    message: hasQuickRef
      ? "Quick reference section present"
      : "No quick reference section",
    weight: 2,
    dimension: "usability",
  });

  const hasRouting = hasDecisionTree(content);
  checks.push({
    category: "Usability",
    check: "Has decision guidance",
    passed: hasRouting,
    message: hasRouting
      ? "Decision/routing logic present"
      : "No decision tree or routing logic",
    weight: 2,
    dimension: "usability",
  });

  // Check scripts
  const scripts = await getScripts(skillPath);
  checks.push({
    category: "Tools",
    check: "Has scripts",
    passed: scripts.length > 0,
    message:
      scripts.length > 0
        ? `${scripts.length} script(s): ${scripts.join(", ")}`
        : "No scripts found",
    weight: 3,
  });

  // Check script documentation
  for (const script of scripts) {
    const documented = scriptDocumented(content, script);
    checks.push({
      category: "Tools",
      check: `${script} documented`,
      passed: documented,
      message: documented
        ? `${script} documented in SKILL.md`
        : `${script} not documented in SKILL.md`,
      weight: 2,
    });
  }

  // Check data files
  const dataFiles = await getDataFiles(skillPath);
  if (dataFiles.length > 0) {
    checks.push({
      category: "Data",
      check: "Has data files",
      passed: true,
      message: `${dataFiles.length} data file(s): ${dataFiles.join(", ")}`,
      weight: 2,
    });
  }

  // Calculate legacy score
  let score = 0;
  let maxScore = 0;
  for (const check of checks) {
    maxScore += check.weight;
    if (check.passed) {
      score += check.weight;
    }
  }

  // Calculate 20-point maturity score by dimension
  const maturityScore: MaturityScore = {
    completeness: { score: 0, max: 11 },
    quality: { score: 0, max: 5 },
    usability: { score: 0, max: 4 },
    total: 0,
  };

  // Count dimension scores based on passed checks
  for (const check of checks) {
    if (check.dimension && check.passed) {
      // Map weight to maturity points (simplified: passed = 1 point per check)
      if (check.dimension === "completeness") {
        maturityScore.completeness.score = Math.min(
          maturityScore.completeness.score + 1,
          maturityScore.completeness.max
        );
      } else if (check.dimension === "quality") {
        maturityScore.quality.score = Math.min(
          maturityScore.quality.score + 1,
          maturityScore.quality.max
        );
      } else if (check.dimension === "usability") {
        maturityScore.usability.score = Math.min(
          maturityScore.usability.score + 1,
          maturityScore.usability.max
        );
      }
    }
  }

  // Also count core sections toward completeness
  const hasCorePrinciple = checks.some(c => c.check.includes("Core Principle") && c.passed);
  const hasStates = checks.some(c => c.check.includes("defined states") && c.passed);
  const hasProcess = checks.some(c => c.check.includes("Diagnostic Process") && c.passed);
  const hasBoundaries = checks.some(c => c.check.includes("What You Do NOT Do") && c.passed);
  const hasExamples = checks.some(c => c.check.includes("Example") && c.passed);

  if (hasCorePrinciple) maturityScore.completeness.score = Math.min(maturityScore.completeness.score + 1, 11);
  if (hasStates) maturityScore.completeness.score = Math.min(maturityScore.completeness.score + 2, 11);
  if (hasProcess) maturityScore.completeness.score = Math.min(maturityScore.completeness.score + 1, 11);
  if (hasBoundaries) maturityScore.completeness.score = Math.min(maturityScore.completeness.score + 1, 11);
  if (hasExamples) maturityScore.completeness.score = Math.min(maturityScore.completeness.score + 2, 11);

  // Quality: self-contained (assumed if SKILL.md exists), type+mode, state naming, integration, tools documented
  const hasTypeMode = checks.filter(c => c.check.includes("metadata.type") || c.check.includes("metadata.mode")).every(c => c.passed);
  const hasToolsDocs = checks.filter(c => c.check.includes("documented")).every(c => c.passed);

  maturityScore.quality.score = Math.min(maturityScore.quality.score + 1, 5); // Self-contained baseline
  if (hasTypeMode) maturityScore.quality.score = Math.min(maturityScore.quality.score + 1, 5);
  if (hasToolsDocs) maturityScore.quality.score = Math.min(maturityScore.quality.score + 1, 5);

  maturityScore.total =
    maturityScore.completeness.score +
    maturityScore.quality.score +
    maturityScore.usability.score;

  const maturityLevel = calculateMaturityLevel(maturityScore.total);

  const percentage = Math.round((score / maxScore) * 100);
  const valid = percentage >= 70;

  let summary: string;
  if (maturityScore.total >= 18) {
    summary = "Battle-Tested - production proven";
  } else if (maturityScore.total >= 13) {
    summary = "Stable - production ready";
  } else if (maturityScore.total >= 8) {
    summary = "Developing - functional but incomplete";
  } else {
    summary = "Draft - needs significant work";
  }

  return {
    skillPath,
    skillName,
    valid,
    score,
    maxScore,
    maturityScore,
    maturityLevel,
    checks,
    summary: `${maturityScore.total}/20 ${maturityLevel} - ${summary}`,
  };
}

function formatResult(result: ValidationResult): string {
  const lines: string[] = [];

  const statusIcon = result.valid ? "✓" : "⚠";
  lines.push(`# Skill Validation: ${result.skillName}\n`);
  lines.push(`${statusIcon} **${result.summary}**\n`);

  // Maturity score breakdown
  lines.push(`## Maturity Score: ${result.maturityScore.total}/20 (${result.maturityLevel})\n`);
  lines.push(`| Dimension | Score |`);
  lines.push(`|-----------|-------|`);
  lines.push(`| Completeness | ${result.maturityScore.completeness.score}/${result.maturityScore.completeness.max} |`);
  lines.push(`| Quality | ${result.maturityScore.quality.score}/${result.maturityScore.quality.max} |`);
  lines.push(`| Usability | ${result.maturityScore.usability.score}/${result.maturityScore.usability.max} |`);
  lines.push("");

  // Group by category
  const categories = new Map<string, CheckResult[]>();
  for (const check of result.checks) {
    if (!categories.has(check.category)) {
      categories.set(check.category, []);
    }
    categories.get(check.category)!.push(check);
  }

  for (const [category, checks] of categories) {
    const passed = checks.filter((c) => c.passed).length;
    const total = checks.length;
    lines.push(`## ${category} (${passed}/${total})\n`);

    for (const check of checks) {
      const icon = check.passed ? "✓" : "✗";
      lines.push(`${icon} ${check.check}: ${check.message}`);
    }
    lines.push("");
  }

  // Failed checks summary
  const failed = result.checks.filter((c) => !c.passed);
  if (failed.length > 0) {
    lines.push("## To Fix\n");
    for (const check of failed) {
      if (check.weight >= 3) {
        lines.push(`- [ ] ${check.check}`);
      }
    }
  }

  return lines.join("\n");
}

async function getAllSkills(basePath: string): Promise<string[]> {
  const skills: string[] = [];

  try {
    for await (const entry of Deno.readDir(basePath)) {
      if (entry.isDirectory && !entry.name.startsWith(".")) {
        const skillMdPath = `${basePath}/${entry.name}/SKILL.md`;
        if (await fileExists(skillMdPath)) {
          skills.push(`${basePath}/${entry.name}`);
        }
      }
    }
  } catch {
    // Directory doesn't exist
  }

  return skills;
}

async function main(): Promise<void> {
  const args = Deno.args;

  if (args.includes("--help") || args.includes("-h")) {
    console.log(`Skill Validator

Validates skill completeness and pattern conformance.

Usage:
  deno run --allow-read validate-skill.ts <skill-path>
  deno run --allow-read validate-skill.ts --all
  deno run --allow-read validate-skill.ts <skill-path> --json

Options:
  --all       Validate all skills in a directory
  --dir D     Directory to scan for skills (default: ../fiction or ..)
  --json      Output as JSON

Examples:
  deno run --allow-read validate-skill.ts /path/to/skill
  deno run --allow-read validate-skill.ts --all --dir ../fiction
  deno run --allow-read validate-skill.ts skill-name --json
`);
    Deno.exit(0);
  }

  const jsonOutput = args.includes("--json");
  const validateAll = args.includes("--all");

  // Parse --dir option
  const dirIndex = args.indexOf("--dir");
  const scriptDir = new URL(".", import.meta.url).pathname;
  const skillsDir = `${scriptDir}../..`; // skills/ directory

  let targetDir: string;
  if (dirIndex !== -1 && args[dirIndex + 1]) {
    const dirArg = args[dirIndex + 1];
    targetDir = dirArg.startsWith("/") ? dirArg : `${scriptDir}${dirArg}`;
  } else {
    // Default: look in parent skills/ directory
    targetDir = skillsDir;
  }

  let skillPaths: string[] = [];

  if (validateAll) {
    // Find all skills in target directory (recursively check subdirs)
    skillPaths = await getAllSkills(targetDir);

    // Also check subdirectories (like fiction/, research/, etc.)
    try {
      for await (const entry of Deno.readDir(targetDir)) {
        if (entry.isDirectory && !entry.name.startsWith(".") && entry.name !== "skill-builder") {
          const subSkills = await getAllSkills(`${targetDir}/${entry.name}`);
          skillPaths.push(...subSkills);
        }
      }
    } catch {
      // Directory doesn't exist or not readable
    }
  } else {
    // Find skill path argument (skip flags and their values)
    const skipIndices = new Set<number>();
    if (dirIndex !== -1) {
      skipIndices.add(dirIndex);
      skipIndices.add(dirIndex + 1);
    }

    let skillPath: string | null = null;
    for (let i = 0; i < args.length; i++) {
      if (!args[i].startsWith("--") && !skipIndices.has(i)) {
        skillPath = args[i];
        break;
      }
    }

    if (!skillPath) {
      console.error("Error: No skill path specified");
      console.error("Usage: validate-skill.ts <skill-path> or --all");
      Deno.exit(1);
    }

    // Resolve path - try multiple strategies
    if (skillPath.startsWith("/")) {
      // Absolute path
      skillPaths = [skillPath];
    } else if (skillPath.startsWith("..") || skillPath.startsWith("./")) {
      // Relative to script location
      skillPaths = [`${scriptDir}${skillPath}`];
    } else {
      // Try to find skill by name in skills directory tree
      // First check direct child
      let found = false;
      if (await fileExists(`${skillsDir}/${skillPath}/SKILL.md`)) {
        skillPaths = [`${skillsDir}/${skillPath}`];
        found = true;
      } else {
        // Check in subdirectories (fiction/skillname, research/skillname, etc.)
        try {
          for await (const entry of Deno.readDir(skillsDir)) {
            if (entry.isDirectory && !entry.name.startsWith(".")) {
              if (await fileExists(`${skillsDir}/${entry.name}/${skillPath}/SKILL.md`)) {
                skillPaths = [`${skillsDir}/${entry.name}/${skillPath}`];
                found = true;
                break;
              }
            }
          }
        } catch {
          // Directory not readable
        }
      }

      if (!found) {
        console.error(`Error: Could not find skill '${skillPath}'`);
        Deno.exit(1);
      }
    }
  }

  const results: ValidationResult[] = [];
  for (const path of skillPaths) {
    results.push(await validateSkill(path));
  }

  if (jsonOutput) {
    console.log(JSON.stringify(results.length === 1 ? results[0] : results, null, 2));
  } else {
    for (const result of results) {
      console.log(formatResult(result));
      if (results.length > 1) {
        console.log("\n---\n");
      }
    }

    // Summary if multiple
    if (results.length > 1) {
      const valid = results.filter((r) => r.valid).length;
      console.log(`\n## Summary: ${valid}/${results.length} skills valid`);
    }
  }
}

main();

#!/usr/bin/env -S deno run --allow-read

/**
 * {{SCRIPT_TITLE}}
 *
 * {{SCRIPT_DESCRIPTION}}
 *
 * Usage:
 *   deno run --allow-read {{SCRIPT_NAME}}.ts                    # Default behavior
 *   deno run --allow-read {{SCRIPT_NAME}}.ts --option value     # With options
 *   deno run --allow-read {{SCRIPT_NAME}}.ts "input"            # With positional arg
 *   deno run --allow-read {{SCRIPT_NAME}}.ts --json             # JSON output
 */

// === INTERFACES ===

interface {{RESULT_TYPE}} {
  name: string;
  // Add result fields
}

// === DATA ===
// Inline data for simple cases, or load from ../data/ for complex cases

const DATA: Record<string, string[]> = {
  category_one: [
    "Item with specific detail",
    "Another concrete item",
    "Third item for variety",
  ],
  category_two: [
    "Different category item",
    "Second item here",
  ],
};

// === UTILITIES ===

function randomFrom<T>(arr: T[], count: number = 1): T[] {
  const shuffled = [...arr].sort(() => Math.random() - 0.5);
  return shuffled.slice(0, Math.min(count, arr.length));
}

// For loading external data files
async function loadData<T>(filename: string): Promise<T> {
  const scriptDir = new URL(".", import.meta.url).pathname;
  const dataPath = `${scriptDir}../data/${filename}`;
  try {
    const text = await Deno.readTextFile(dataPath);
    return JSON.parse(text);
  } catch (e) {
    console.error(`Error loading ${dataPath}: ${e}`);
    Deno.exit(1);
  }
}

// === CORE LOGIC ===

function generate(
  input: string | null,
  option: string | null
): {{RESULT_TYPE}} {
  // Generation logic here

  return {
    name: input || "Default",
    // Populate result
  };
}

// === FORMATTING ===

function formatResult(result: {{RESULT_TYPE}}): string {
  const lines: string[] = [];

  lines.push(`# {{OUTPUT_TITLE}}: ${result.name}\n`);

  // Format sections
  lines.push("## Section\n");
  lines.push("Content here");
  lines.push("");

  return lines.join("\n");
}

function formatBrief(result: {{RESULT_TYPE}}): string {
  return `${result.name} [brief output]`;
}

// === MAIN ===

function main(): void {
  const args = Deno.args;

  // Help
  if (args.includes("--help") || args.includes("-h")) {
    console.log(`{{SCRIPT_TITLE}}

{{SCRIPT_DESCRIPTION}}

Usage:
  deno run --allow-read {{SCRIPT_NAME}}.ts [options] [input]

Options:
  --option S    Description of option
                Available: value1, value2, value3
                Default: value1

  --count N     Number of results to generate
                Default: 1

  --brief       Short output format
  --json        Output as JSON

Examples:
  deno run --allow-read {{SCRIPT_NAME}}.ts
  deno run --allow-read {{SCRIPT_NAME}}.ts --option value2
  deno run --allow-read {{SCRIPT_NAME}}.ts "Custom Input" --json
`);
    Deno.exit(0);
  }

  // Parse arguments
  const optionIndex = args.indexOf("--option");
  const countIndex = args.indexOf("--count");
  const jsonOutput = args.includes("--json");
  const briefOutput = args.includes("--brief");

  const option = optionIndex !== -1 && args[optionIndex + 1]
    ? args[optionIndex + 1]
    : null;

  const count = countIndex !== -1 && args[countIndex + 1]
    ? parseInt(args[countIndex + 1]) || 1
    : 1;

  // Build skip indices for positional arg detection
  const skipIndices = new Set<number>();
  if (optionIndex !== -1) {
    skipIndices.add(optionIndex);
    skipIndices.add(optionIndex + 1);
  }
  if (countIndex !== -1) {
    skipIndices.add(countIndex);
    skipIndices.add(countIndex + 1);
  }

  // Find positional argument (first arg that's not a flag)
  let positionalArg: string | null = null;
  for (let i = 0; i < args.length; i++) {
    if (!args[i].startsWith("--") && !skipIndices.has(i)) {
      positionalArg = args[i];
      break;
    }
  }

  // Generate results
  const results: {{RESULT_TYPE}}[] = [];
  for (let i = 0; i < count; i++) {
    results.push(generate(positionalArg, option));
  }

  // Output
  if (jsonOutput) {
    console.log(JSON.stringify(count === 1 ? results[0] : results, null, 2));
  } else if (briefOutput) {
    for (const result of results) {
      console.log(formatBrief(result));
    }
  } else {
    for (const result of results) {
      console.log(formatResult(result));
      if (results.length > 1) {
        console.log("---\n");
      }
    }
  }
}

main();