@almadar/skills 2.0.0 → 2.0.2

package/dist/index.d.ts

@@ -0,0 +1,671 @@
+import { OrbitalSchema } from '@almadar/core';
+
+/**
+ * Skill Generator Types
+ *
+ * Shared types for all skill generators.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Skill frontmatter metadata.
+ */
+interface SkillFrontmatter {
+    name: string;
+    description: string;
+    allowedTools?: string[];
+    version?: string;
+}
+/**
+ * Generated skill output.
+ */
+interface GeneratedSkill {
+    name: string;
+    frontmatter: SkillFrontmatter;
+    content: string;
+    references?: Record<string, string>;
+}
+
+/**
+ * Skill Generator Utilities
+ *
+ * Shared utilities for formatting and writing skill files.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Format skill frontmatter to YAML.
+ */
+declare function formatFrontmatter(fm: SkillFrontmatter): string;
+/**
+ * Write a skill to the filesystem.
+ */
+declare function writeSkill(skill: GeneratedSkill, baseDir: string): void;
+/**
+ * Write all skills to the filesystem.
+ */
+declare function writeAllSkills(skills: GeneratedSkill[], baseDir: string): void;
+
+/**
+ * KFlow Orbitals Skill Generator
+ *
+ * Generates the kflow-orbitals skill for orbital-based schema generation.
+ * Uses the orbital skill generator from the orbitals module and adds
+ * domain classification, interaction models, and trait-driven UI guidance.
+ *
+ * v4.0: Reduced from ~49K to ~15K by cutting std dump, schema-updates,
+ * custom-traits, and half the errors. Added render-ui design guide with
+ * pattern catalog and composition recipes.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generate the kflow-orbitals skill.
+ *
+ * Uses the lean orbital skill generator with minimal defaults (~15K).
+ * The design guide, top-6 errors, and enriched example are always included.
+ *
+ * Options:
+ * - compact: false (default) - Standard ~15K generation skill
+ * - compact: true - Same (compact flag preserved for API compat, no-op now)
+ */
+declare function generateKflowOrbitalsSkill(compact?: boolean): GeneratedSkill;
+
+/**
+ * KFlow Orbital Fixing Skill Generator
+ *
+ * Generates the kflow-orbital-fixing skill for fixing validation errors
+ * using orbital understanding. Uses the LEAN fixing skill generator from the
+ * orbitals module for reduced token usage.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generate the kflow-orbital-fixing skill.
+ *
+ * Uses the lean generator which:
+ * - Shares sections with lean-orbital-skill-generator
+ * - Adds fixing-specific workflow and patterns
+ * - ~42% smaller than the original generator
+ */
+declare function generateKflowOrbitalFixingSkill(): GeneratedSkill;
+
+/**
+ * Domain Language Skill Generator
+ *
+ * Generates the domain-language skill for understanding, generating,
+ * and summarizing KFlow domain language.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generate the domain-language skill.
+ */
+declare function generateDomainLanguageSkill(): GeneratedSkill;
+
+/**
+ * Lean Orbital Skill Generator
+ *
+ * Generates kflow-lean-orbitals SKILL.md that:
+ * 1. Outputs Domain Language text with S-Expression effects
+ * 2. Uses minimal token count (~5x fewer than JSON)
+ * 3. Imports from @almadar/* packages for schema knowledge
+ *
+ * @packageDocumentation
+ */
+/**
+ * Generate the kflow-lean-orbitals SKILL.md content
+ */
+declare function generateLeanOrbitalSkill$1(): string;
+
+/**
+ * Lean Fixing Skill Generator
+ *
+ * Generates kflow-lean-fixing SKILL.md for fixing validation errors
+ * using Domain Language format.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Generate the kflow-lean-fixing SKILL.md content
+ */
+declare function generateLeanFixingSkill$1(): string;
+
+/**
+ * Lean Orbital Skill Generator
+ *
+ * Generates a minimal, focused orbital skill by:
+ * 1. Deriving type information directly from @almadar/core
+ * 2. Using focused, minimal guidance sections
+ * 3. Avoiding verbose explanations and redundancy
+ *
+ * v4: Reduced from ~49K to ~15K by:
+ * - Removing std behaviors JSON dump (21K)
+ * - Removing schema-updates (moved to fixing skill)
+ * - Removing custom-traits (moved to fixing skill)
+ * - Trimming common-errors to top 6
+ * - Replacing 380-char render-ui quickref with 2.5K design guide
+ * - Using compact decomposition and connectivity variants
+ *
+ * @packageDocumentation
+ */
+interface LeanSkillOptions {
+    /** Include example orbital */
+    includeExample?: boolean;
+    /** Include tool workflow section */
+    includeToolWorkflow?: boolean;
+    /** Include std/* library reference (operators + behaviors) */
+    includeStdLibrary?: boolean;
+    /** Use full std reference (detailed) vs minimal (compact) */
+    stdLibraryFull?: boolean;
+    /** Include expanded non-game behaviors with state machines for copying */
+    includeStdStateMachines?: boolean;
+    /** Include schema update guidance section */
+    includeSchemaUpdates?: boolean;
+    /** Include custom trait examples section */
+    includeCustomTraits?: boolean;
+    /** Error detail level: 'top6' for generation, 'full' for fixing */
+    errorLevel?: 'top6' | 'full';
+    /** Include render-ui design guide with pattern catalog and recipes */
+    includeDesignGuide?: boolean;
+}
+/**
+ * Generate a lean orbital skill.
+ *
+ * Default options produce a ~15K skill focused on generation quality.
+ * Set includeStdStateMachines/includeCustomTraits/errorLevel='full' for
+ * the larger ~49K variant used by legacy callers.
+ */
+declare function generateLeanOrbitalSkill(options?: LeanSkillOptions): string;
+/**
+ * Get subagent system prompt for orbital generation.
+ * This is used by the orbital generator subagent in @almadar/agent.
+ * Provides focused guidance on generating complete orbitals with entities.
+ */
+declare function getSubagentSystemPrompt(): string;
+
+/**
+ * Lean Fixing Skill Generator
+ *
+ * Generates a minimal, focused fixing skill by:
+ * 1. Reusing the same sections as lean-orbital-skill-generator
+ * 2. Adding fixing-specific guidance on top
+ * 3. Keeping the same modular structure
+ *
+ * @packageDocumentation
+ */
+interface LeanFixingSkillOptions {
+    /** Include over-generation detection */
+    includeOverGeneration?: boolean;
+    /** Include schema update guidance */
+    includeSchemaUpdates?: boolean;
+    /** Include efficiency guidelines */
+    includeEfficiency?: boolean;
+}
+/**
+ * Generate a lean fixing skill.
+ *
+ * This produces a fixing skill that reuses the lean orbital sections
+ * and adds fixing-specific guidance.
+ */
+declare function generateLeanFixingSkill(options?: LeanFixingSkillOptions): string;
+
+/**
+ * Skill Generators for Builder Client
+ *
+ * Re-exports the 5 core skills used by the builder client:
+ * 1. kflow-orbitals (standard JSON generation with atomic composition)
+ * 2. kflow-orbital-fixing (standard fixing)
+ * 3. kflow-lean-orbitals (lean domain language generation)
+ * 4. kflow-lean-fixing (lean fixing)
+ * 5. domain-language (ODL understanding/summarization)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generate all builder client skills.
+ * These are the 5 skills actually used by the builder UI.
+ */
+declare function generateAllBuilderSkills(): GeneratedSkill[];
+
+/**
+ * Skill Architecture Section
+ *
+ * Core orbital architecture concepts - minimal, essential information only.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the core orbital architecture section.
+ * This is the foundational understanding needed for orbital generation.
+ */
+declare function getArchitectureSection(): string;
+
+/**
+ * Common Errors Section
+ *
+ * Critical mistakes to avoid during orbital generation.
+ * Keep this focused on the most frequent errors only.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get common errors section.
+ * Supports tiered output: 'top6' for generation skill, 'full' for fixing skill.
+ */
+declare function getCommonErrorsSection(level?: 'top6' | 'full'): string;
+/**
+ * Get validation error hints section.
+ * Quick reference for common validation errors and fixes.
+ */
+declare function getValidationHintsSection(): string;
+
+/**
+ * Decomposition Protocol Section
+ *
+ * Step-by-step protocol for breaking requirements into orbital units.
+ * Keep this focused on the decision process, not verbose explanations.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the decomposition protocol section.
+ */
+declare function getDecompositionSection(): string;
+/**
+ * Get minimal decomposition checklist.
+ */
+declare function getDecompositionChecklist(): string;
+/**
+ * Get compact decomposition protocol (~1,250 chars).
+ * Steps 0-6 without verbose guard examples (guards covered in S-Expr + errors).
+ */
+declare function getDecompositionCompact(): string;
+/**
+ * Get compact orbital connectivity (~750 chars).
+ * One combined example instead of three separate examples.
+ */
+declare function getConnectivityCompact(): string;
+/**
+ * Get flow pattern selection guidance.
+ * Maps application types to appropriate user flow patterns.
+ */
+declare function getFlowPatternSection(): string;
+/**
+ * Get guidance for outputting orbitals with embedded context.
+ */
+declare function getPortableOrbitalOutputSection(): string;
+/**
+ * Get guidance for connecting orbitals together.
+ */
+declare function getOrbitalConnectivitySection(): string;
+
+/**
+ * Atomic Composition Design Guide (v5.0)
+ *
+ * Teaches the LLM to compose sophisticated views using atomic design principles.
+ * Every render-ui effect must satisfy the Five Rules of Sophisticated Composition.
+ *
+ * v5.0: Added mandatory composition rules, validation checklist, and theme enforcement.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the render-ui atomic composition guide with mandatory rules.
+ */
+declare function getRenderUIDesignGuide(): string;
+
+/**
+ * Theme Variable System Guide
+ *
+ * Teaches the LLM to use CSS theme variables for all visual properties.
+ * Enforces consistent theming across all generated schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the theme variable system guide.
+ * Covers colors, spacing, radius, and shadows with mandatory enforcement rules.
+ */
+declare function getThemeGuide(): string;
+/**
+ * Get banned properties that should never be used.
+ */
+declare function getBannedProps(): string;
+
+/**
+ * Custom Trait Guidance Section
+ *
+ * Comprehensive guidance for creating custom traits.
+ * Part of the lean orbital skill.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the custom trait guidance section.
+ */
+declare function getCustomTraitSection(): string;
+/**
+ * Get a compact version of custom trait guidance.
+ */
+declare function getCustomTraitCompact(): string;
+
+/**
+ * Schema Update Guidance
+ *
+ * Provides guidance for modifying existing orbital schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the full schema update section.
+ */
+declare function getSchemaUpdateSection(): string;
+/**
+ * Get compact schema update guidance (shorter version).
+ */
+declare function getSchemaUpdateCompact(): string;
+
+/**
+ * Context Usage Section
+ *
+ * Guidance for using embedded context when generating orbitals.
+ * Small, reusable section for skill generators.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get guidance for using embedded context during generation.
+ */
+declare function getContextUsageSection(): string;
+/**
+ * Get compact context usage for space-constrained prompts.
+ */
+declare function getContextUsageCompact(): string;
+
+/**
+ * Design-Specific Errors Section
+ *
+ * Common errors specific to the design skill that transforms
+ * wireframe schemas into polished applications.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get design-specific common errors section.
+ * These are the most frequent mistakes when beautifying schemas.
+ */
+declare function getDesignErrorsSection(): string;
+/**
+ * Get compact design errors for lean skill.
+ */
+declare function getDesignErrorsCompact(): string;
+/**
+ * Get icon library reference.
+ */
+declare function getIconLibrarySection(): string;
+/**
+ * Get compact icon reference.
+ */
+declare function getIconLibraryCompact(): string;
+
+/**
+ * Fixing Guidance Section
+ *
+ * Specialized guidance for fixing validation errors in orbital schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the fixing workflow section.
+ */
+declare function getFixingWorkflowSection(): string;
+/**
+
+/**
+ * Get common fix patterns section.
+ */
+declare function getCommonFixPatternsSection(): string;
+/**
+ * Get over-generation detection section.
+ */
+declare function getOverGenerationSection(): string;
+/**
+ * Get efficiency guidelines section.
+ */
+declare function getEfficiencySection(): string;
+/**
+ * Get completion rules section.
+ */
+declare function getCompletionRulesSection(): string;
+
+/**
+ * Game Guidance Section
+ *
+ * Specialized guidance for generating game orbital schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the game as orbitals composition section.
+ */
+declare function getGameAsOrbitalsSection(): string;
+/**
+ * Get game entity templates section.
+ */
+declare function getGameEntityTemplatesSection(): string;
+/**
+ * Get game traits section.
+ */
+declare function getGameTraitsSection(): string;
+/**
+ * Get game patterns section.
+ */
+declare function getGamePatternsSection(): string;
+/**
+ * Get asset reference section.
+ */
+declare function getAssetRefSection(): string;
+/**
+ * Get multi-file composition section.
+ */
+declare function getMultiFileSection(): string;
+/**
+ * Get game types section.
+ */
+declare function getGameTypesSection(): string;
+
+/**
+ * Uses Import System Section
+ *
+ * Guidance for using the `uses` declaration to import external orbitals.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get the uses import system section.
+ */
+declare function getUsesImportSection(): string;
+/**
+ * Get compact uses guidance.
+ */
+declare function getUsesImportCompact(): string;
+
+/**
+ * Bindings Guide
+ *
+ * Generates binding documentation from the source of truth in @almadar/core.
+ * This ensures the skill guidance matches the actual compiler validation.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Generate binding documentation for skill prompts.
+ * Derived from BINDING_DOCS in @almadar/core - single source of truth.
+ */
+declare function getBindingsGuide(): string;
+/**
+ * Get compact binding reference (one-liner for tables).
+ */
+declare function getBindingsCompact(): string;
+/**
+ * Get binding validation rules for specific contexts.
+ */
+declare function getBindingContextRules(): string;
+
+/**
+ * Generation Prompts
+ *
+ * Prompts for the generateFullOrbital() function composed from reusable skill sections.
+ * These are used by @almadar/agent for programmatic orbital generation.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get prompt for decomposing a request into orbital units.
+ * Used by the main agent before calling generateFullOrbital on each unit.
+ */
+declare function getOrbitalDecompositionPrompt(): string;
+/**
+ * Get prompt for expanding a lightweight orbital into a full orbital.
+ * This is the main prompt used by generateFullOrbital().
+ */
+declare function getFullOrbitalPrompt(): string;
+/**
+ * Get prompt for requirements-aware decomposition.
+ * Used when extracted requirements are available from analysis phase.
+ */
+declare function getRequirementsDecomposePrompt(): string;
+/**
+ * Get prompt for generating traits from requirements.
+ * Used when requirements need to be converted to trait state machines.
+ */
+declare function getRequirementsTraitPrompt(): string;
+
+/**
+ * Type References
+ *
+ * Auto-generated type reference sections from @almadar packages.
+ * Used to compose generation prompts.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get minimal type reference for orbital schemas.
+ * Covers entities, traits, pages, and basic structure.
+ */
+declare function getMinimalTypeReference(): string;
+/**
+ * Get compact pattern types listing.
+ */
+declare function getPatternTypesCompact(): string;
+/**
+ * Get S-Expression quick reference.
+ */
+declare function getSExprQuickRef(): string;
+/**
+ * Get render-ui quick reference.
+ */
+declare function getRenderUIQuickRef(): string;
+/**
+ * Get field types compact reference.
+ */
+declare function getFieldTypesCompact(): string;
+
+/**
+ * Behaviors Reference
+ *
+ * Helper for generating standard behaviors documentation from @almadar/std.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get key behaviors reference (compact).
+ * Uses @almadar/std to generate the behaviors documentation.
+ */
+declare function getKeyBehaviorsReference(): string;
+
+/**
+ * Composition Quality Evaluation Framework
+ *
+ * Evaluates LLM providers' ability to generate sophisticated render-ui effects
+ * that meet the Five Rules of Sophisticated Composition.
+ *
+ * @packageDocumentation
+ */
+
+interface EvalCase {
+    name: string;
+    description: string;
+    prompt: string;
+    expectedPatterns: string[];
+    minScore: number;
+    domain: 'general' | 'healthcare' | 'ecommerce' | 'project-management';
+    rubric?: {
+        structure: Record<string, number>;
+        composition: Record<string, number>;
+        theme: Record<string, number>;
+        quality: Record<string, number>;
+    };
+}
+interface EvalResult {
+    caseName: string;
+    provider: string;
+    score: number;
+    passed: boolean;
+    breakdown: ScoreBreakdown;
+    validationErrors: string[];
+    validationWarnings: string[];
+    schema?: OrbitalSchema;
+}
+interface ScoreBreakdown {
+    structure: number;
+    composition: number;
+    theme: number;
+    quality: number;
+}
+interface CompositionMetrics {
+    renderUICount: number;
+    atomTypes: string[];
+    moleculeTypes: string[];
+    organismTypes: string[];
+    layoutRoot: string | null;
+    nestingDepth: number;
+    sectionCount: number;
+    themeVariableUsage: number;
+    hardcodedValues: string[];
+}
+declare const EVAL_CASES: EvalCase[];
+/**
+ * Analyze the composition metrics of a schema.
+ */
+declare function analyzeComposition(schema: OrbitalSchema): CompositionMetrics;
+/**
+ * Calculate total score (0-100)
+ */
+declare function calculateTotalScore(schema: OrbitalSchema, testCase: EvalCase, validationErrors: string[]): {
+    score: number;
+    breakdown: ScoreBreakdown;
+};
+interface ProviderComparison {
+    provider: string;
+    averageScore: number;
+    cases: {
+        caseName: string;
+        score: number;
+        passed: boolean;
+    }[];
+    strengths: string[];
+    weaknesses: string[];
+}
+/**
+ * Generate comparison matrix for all providers.
+ */
+declare function generateComparisonMatrix(comparisons: ProviderComparison[]): string;
+
+export { type CompositionMetrics, EVAL_CASES, type EvalCase, type EvalResult, type GeneratedSkill, type ProviderComparison, type ScoreBreakdown, type SkillFrontmatter, analyzeComposition, calculateTotalScore, formatFrontmatter, generateAllBuilderSkills, generateComparisonMatrix, generateDomainLanguageSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill$1 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill$1 as generateLeanOrbitalSkill, generateLeanOrbitalSkill as generateLeanOrbitalSkillFull, getArchitectureSection, getAssetRefSection, getBannedProps, getBindingContextRules, getBindingsCompact, getBindingsGuide, getCommonErrorsSection, getCommonFixPatternsSection, getCompletionRulesSection, getConnectivityCompact, getContextUsageCompact, getContextUsageSection, getCustomTraitCompact, getCustomTraitSection, getDecompositionChecklist, getDecompositionCompact, getDecompositionSection, getDesignErrorsCompact, getDesignErrorsSection, getEfficiencySection, getFieldTypesCompact, getFixingWorkflowSection, getFlowPatternSection, getFullOrbitalPrompt, getGameAsOrbitalsSection, getGameEntityTemplatesSection, getGamePatternsSection, getGameTraitsSection, getGameTypesSection, getIconLibraryCompact, getIconLibrarySection, getKeyBehaviorsReference, getMinimalTypeReference, getMultiFileSection, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIDesignGuide, getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getSubagentSystemPrompt, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/skills",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "AI skill generators and prompts for Orbital schema generation",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": ">=2.0.0",
+    "@almadar/core": ">=2.1.0",
     "@almadar/llm": ">=2.0.0",
     "@almadar/patterns": ">=2.0.0",
     "@almadar/std": ">=2.0.0",
@@ -38,7 +38,8 @@
     "dotenv": "^16.4.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "@types/node": "^22.0.0"
   },
   "repository": {
     "type": "git",