language-operator 0.1.81 → 0.1.82

data/.claude/hooks/skill-activation-prompt.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { readFileSync } from "fs";
+import { join } from "path";
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  permission_mode: string;
+  prompt: string;
+}
+
+interface PromptTriggers {
+  keywords?: string[];
+  intentPatterns?: string[];
+}
+
+interface FileTriggers {
+  pathPatterns?: string[];
+  pathExclusions?: string[];
+  contentPatterns?: string[];
+}
+
+interface SkillRule {
+  type: "guardrail" | "domain";
+  enforcement: "block" | "suggest" | "warn";
+  priority: "critical" | "high" | "medium" | "low";
+  description?: string;
+  promptTriggers?: PromptTriggers;
+  fileTriggers?: FileTriggers;
+}
+
+interface SkillRules {
+  version: string;
+  description?: string;
+  skills: Record<string, SkillRule>;
+}
+
+interface MatchedSkill {
+  name: string;
+  matchType: "keyword" | "intent" | "file";
+  config: SkillRule;
+  matchDetails?: string;
+}
+
+async function main() {
+  try {
+    // Read input from stdin
+    const input = readFileSync(0, "utf-8");
+    const data: HookInput = JSON.parse(input);
+    const prompt = data.prompt.toLowerCase();
+
+    // Load skill rules - go up two levels from hooks directory to project root
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || join(process.cwd(), "..", "..");
+    const rulesPath = join(projectDir, ".claude", "skills", "skill-rules.json");
+    
+    let rules: SkillRules;
+    try {
+      rules = JSON.parse(readFileSync(rulesPath, "utf-8"));
+    } catch (error) {
+      // If skill rules file doesn't exist, exit silently
+      process.exit(0);
+    }
+
+    const matchedSkills: MatchedSkill[] = [];
+
+    // Check each skill for matches
+    for (const [skillName, config] of Object.entries(rules.skills)) {
+      const triggers = config.promptTriggers;
+      if (!triggers) continue;
+
+      // Keyword matching
+      if (triggers.keywords) {
+        const matchedKeywords: string[] = [];
+        for (const keyword of triggers.keywords) {
+          if (prompt.includes(keyword.toLowerCase())) {
+            matchedKeywords.push(keyword);
+          }
+        }
+        
+        if (matchedKeywords.length > 0) {
+          matchedSkills.push({
+            name: skillName,
+            matchType: "keyword",
+            config,
+            matchDetails: `Keywords: ${matchedKeywords.join(", ")}`
+          });
+          continue;
+        }
+      }
+
+      // Intent pattern matching
+      if (triggers.intentPatterns) {
+        for (const pattern of triggers.intentPatterns) {
+          try {
+            const regex = new RegExp(pattern, "i");
+            if (regex.test(prompt)) {
+              matchedSkills.push({
+                name: skillName,
+                matchType: "intent",
+                config,
+                matchDetails: `Pattern: ${pattern}`
+              });
+              break;
+            }
+          } catch (error) {
+            // Skip invalid regex patterns
+            console.error(`Invalid regex pattern: ${pattern}`, error);
+          }
+        }
+      }
+    }
+
+    // Generate output if matches found
+    if (matchedSkills.length > 0) {
+      let output = "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n";
+      output += "🎯 SKILL ACTIVATION CHECK\n";
+      output += "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n";
+
+      // Group by priority
+      const critical = matchedSkills.filter((s) => s.config.priority === "critical");
+      const high = matchedSkills.filter((s) => s.config.priority === "high");
+      const medium = matchedSkills.filter((s) => s.config.priority === "medium");
+      const low = matchedSkills.filter((s) => s.config.priority === "low");
+
+      if (critical.length > 0) {
+        output += "⚠️  CRITICAL SKILLS (REQUIRED):\n";
+        critical.forEach((s) => {
+          output += `   → ${s.name}`;
+          if (s.config.description) output += ` - ${s.config.description}`;
+          output += "\n";
+        });
+        output += "\n";
+      }
+
+      if (high.length > 0) {
+        output += "📚 RECOMMENDED SKILLS:\n";
+        high.forEach((s) => {
+          output += `   → ${s.name}`;
+          if (s.config.description) output += ` - ${s.config.description}`;
+          output += "\n";
+        });
+        output += "\n";
+      }
+
+      if (medium.length > 0) {
+        output += "💡 SUGGESTED SKILLS:\n";
+        medium.forEach((s) => {
+          output += `   → ${s.name}`;
+          if (s.config.description) output += ` - ${s.config.description}`;
+          output += "\n";
+        });
+        output += "\n";
+      }
+
+      if (low.length > 0) {
+        output += "ℹ️  OPTIONAL SKILLS:\n";
+        low.forEach((s) => {
+          output += `   → ${s.name}`;
+          if (s.config.description) output += ` - ${s.config.description}`;
+          output += "\n";
+        });
+        output += "\n";
+      }
+
+      // Add call to action
+      if (critical.length > 0) {
+        output += "⚠️  ACTION: You MUST use the critical skills before proceeding\n";
+      } else if (high.length > 0) {
+        output += "💡 ACTION: Consider using the Skill tool to activate relevant skills\n";
+      }
+      
+      output += "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n";
+
+      process.stdout.write(output);
+    }
+  } catch (error) {
+    // Silent fail - don't break Claude if hook fails
+    // Only log to stderr for debugging, but exit successfully
+    console.error("Skill activation hook error:", error);
+    process.exit(0);
+  }
+}
+
+main();

data/.claude/hooks/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  }
+}

data/.claude/settings.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(rg:*)", 
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(bundle exec rspec:*)",
+      "Bash(bundle exec rubocop:*)",
+      "Bash(make test:*)",
+      "Bash(bundle exec rake:*)",
+      "Bash(gem build:*)",
+      "Bash(bundle install:*)"
+    ],
+    "deny": []
+  },
+  "enableAllProjectMcpServers": true,
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.claude/skills/README.md

@@ -0,0 +1,29 @@
+# Language Operator Skills
+
+Domain-specific knowledge modules for Language Operator Ruby gem development.
+
+## Available Skills
+
+- [ruby-gem-development](ruby-gem-development/SKILL.md) - Ruby gem development patterns with bundler, RSpec, RuboCop, and Language Operator conventions
+- [thor-cli-development](thor-cli-development/SKILL.md) - Thor-based CLI development patterns for the aictl command-line interface
+
+## Skill Activation
+
+Skills are automatically activated based on:
+- **Keywords** in your prompts (e.g., "gem", "CLI", "Thor", "RSpec")
+- **File patterns** when editing relevant files
+- **Content patterns** when working with specific code structures
+
+See [skill-rules.json](skill-rules.json) for detailed trigger configuration.
+
+## Usage
+
+To manually activate a skill:
+```
+Use the ruby-gem-development skill to help me implement a new feature
+```
+
+To see all available skills:
+```
+What skills are available for this project?
+```

data/.claude/skills/ruby-gem-development/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: ruby-gem-development
+description: Ruby gem development patterns with bundler, RSpec, RuboCop, and Language Operator conventions
+---
+
+# Ruby Gem Development Patterns
+
+## Purpose
+
+Provides consistent patterns for developing the Language Operator Ruby gem, including testing, linting, packaging, and release practices.
+
+## When to Use This Skill
+
+Automatically activates when:
+- Working with gem specification files (*.gemspec)
+- Creating or modifying RSpec tests
+- Running bundler commands
+- Implementing new library features in `lib/`
+- Working with Rakefile tasks
+- Preparing releases or version bumps
+
+## Quick Start
+
+### New Feature Checklist
+
+- [ ] Create feature code in `lib/language_operator/`
+- [ ] Add comprehensive RSpec tests in `spec/`
+- [ ] Update CHANGELOG.md with change
+- [ ] Run `make lint` to check code style
+- [ ] Run `make test` to verify functionality
+- [ ] Update documentation if needed
+- [ ] Bump version in `lib/language_operator/version.rb` (if needed)
+
+### Testing Checklist
+
+- [ ] Unit tests cover all public methods
+- [ ] Integration tests for complex workflows
+- [ ] Mock external dependencies (HTTP, Kubernetes)
+- [ ] Use `let` blocks for test setup
+- [ ] Follow `describe`/`context`/`it` hierarchy
+- [ ] Test both success and failure paths
+
+## Core Principles
+
+### 1. Layered Architecture
+
+```ruby
+# lib/language_operator/
+#   ├── cli/           # Command-line interface (Thor)
+#   ├── dsl/           # Domain-specific language
+#   ├── agent/         # Agent runtime
+#   ├── client/        # LLM + MCP client
+#   └── kubernetes/    # K8s integration
+
+# Each layer has clear responsibilities:
+# CLI → DSL → Agent → Client → External APIs
+```
+
+### 2. RSpec Testing Patterns
+
+```ruby
+# Good: Descriptive hierarchy
+RSpec.describe LanguageOperator::Agent::Base do
+  describe '#execute_goal' do
+    context 'when goal is valid' do
+      it 'executes successfully' do
+        # Test implementation
+      end
+    end
+    
+    context 'when goal is invalid' do
+      it 'raises TaskValidationError' do
+        expect { agent.execute_goal('') }.to raise_error(
+          LanguageOperator::Agent::TaskValidationError
+        )
+      end
+    end
+  end
+end
+
+# Use let blocks for setup
+let(:agent) { described_class.new(config) }
+let(:config) { instance_double(LanguageOperator::Client::Config) }
+```
+
+### 3. Error Handling Standards
+
+```ruby
+# Custom error hierarchy
+module LanguageOperator
+  class Error < StandardError; end
+  class NetworkError < Error; end
+  class ValidationError < Error; end
+  class SecurityError < Error; end
+end
+
+# Raise with context
+raise LanguageOperator::ValidationError, 
+  "Invalid schedule format: #{schedule}"
+
+# Handle gracefully
+rescue LanguageOperator::NetworkError => e
+  Logger.warn("Network issue, retrying: #{e.message}")
+  retry_with_backoff
+end
+```
+
+### 4. Gem Configuration
+
+```ruby
+# language-operator.gemspec
+Gem::Specification.new do |spec|
+  spec.name = 'language-operator'
+  spec.version = LanguageOperator::VERSION
+  spec.required_ruby_version = '>= 3.2.0'
+  
+  # Dependencies
+  spec.add_dependency 'ruby_llm', '~> 1.8'
+  spec.add_dependency 'thor', '~> 1.3'
+  
+  # Development dependencies
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+end
+```
+
+## Common Patterns
+
+### Pattern 1: CLI Command Structure
+
+```ruby
+module LanguageOperator::CLI::Commands
+  class Agent < Thor
+    desc 'create NAME', 'Create a new agent'
+    option :mode, type: :string, default: 'autonomous'
+    
+    def create(name)
+      # Validation
+      validate_agent_name!(name)
+      
+      # Wizard for interactive setup
+      wizard = Wizards::AgentWizard.new
+      config = wizard.run(name, options)
+      
+      # Resource creation
+      builder = Kubernetes::ResourceBuilder.new
+      manifest = builder.build_agent(config)
+      
+      # Apply to cluster
+      client = Kubernetes::Client.new
+      client.apply_resource(manifest)
+      
+      say "Agent '#{name}' created successfully", :green
+    end
+    
+    private
+    
+    def validate_agent_name!(name)
+      return if name.match?(/\A[a-z0-9-]+\z/)
+      raise ValidationError, "Invalid agent name: #{name}"
+    end
+  end
+end
+```
+
+### Pattern 2: DSL Definition Pattern
+
+```ruby
+module LanguageOperator::Dsl
+  class AgentDefinition
+    attr_reader :name, :mode, :schedule, :tools
+    
+    def initialize(name)
+      @name = name
+      @tools = []
+      yield(self) if block_given?
+    end
+    
+    def mode(value)
+      @mode = validate_mode!(value)
+    end
+    
+    def schedule(expression)
+      @schedule = validate_cron!(expression)
+    end
+    
+    def tool(name, &block)
+      @tools << ToolDefinition.new(name, &block)
+    end
+    
+    private
+    
+    def validate_mode!(mode)
+      valid_modes = %i[autonomous scheduled reactive]
+      return mode if valid_modes.include?(mode)
+      raise ValidationError, "Invalid mode: #{mode}"
+    end
+  end
+end
+```
+
+### Pattern 3: Test Organization
+
+```ruby
+# spec/language_operator/agent/base_spec.rb
+RSpec.describe LanguageOperator::Agent::Base do
+  subject(:agent) { described_class.new(config) }
+  
+  let(:config) do
+    instance_double(
+      LanguageOperator::Client::Config,
+      agent_name: 'test-agent',
+      mode: :autonomous
+    )
+  end
+  
+  describe '.new' do
+    it 'initializes with config' do
+      expect(agent.config).to eq(config)
+    end
+  end
+  
+  describe '#run' do
+    context 'in autonomous mode' do
+      before { allow(config).to receive(:mode).and_return(:autonomous) }
+      
+      it 'starts executor loop' do
+        executor = instance_double(LanguageOperator::Agent::Executor)
+        allow(LanguageOperator::Agent::Executor).to receive(:new).and_return(executor)
+        expect(executor).to receive(:run_loop)
+        
+        agent.run
+      end
+    end
+  end
+end
+```
+
+## Resource Files
+
+For detailed information, see:
+- [Testing Patterns](resources/testing-patterns.md) - Comprehensive RSpec guidelines
+- [Release Process](resources/release-process.md) - Version bumps and gem publishing
+- [Code Style](resources/code-style.md) - RuboCop configuration and standards
+
+## Anti-Patterns to Avoid
+
+❌ **Mixing layers** - Don't put business logic in CLI classes
+❌ **Missing tests** - No production code without corresponding specs  
+❌ **Hardcoded values** - Use configuration and environment variables
+❌ **Silent failures** - Always log and raise meaningful errors
+❌ **Coupling to external services** - Use dependency injection and mocking
+❌ **Inconsistent naming** - Follow Ruby conventions (snake_case, descriptive names)
+
+## Quick Reference
+
+| Need to... | Use this |
+|-----------|----------|
+| Run all tests | `make test` |
+| Run integration tests | `make test-integration` |
+| Check code style | `make lint` |
+| Auto-fix style issues | `make lint-fix` |
+| Build gem | `make build` |
+| Install locally | `make install` |
+| Generate docs | `make yard-docs` |
+| Open console | `make console` |
+
+## Version Management
+
+```ruby
+# lib/language_operator/version.rb
+module LanguageOperator
+  VERSION = '0.1.81'
+end
+
+# Follow semantic versioning:
+# MAJOR.MINOR.PATCH
+# - MAJOR: Breaking changes
+# - MINOR: New features, backward compatible
+# - PATCH: Bug fixes, backward compatible
+```
+
+## Release Checklist
+
+- [ ] Update `VERSION` in `lib/language_operator/version.rb`
+- [ ] Update `CHANGELOG.md` with changes
+- [ ] Run full test suite: `make test-all`
+- [ ] Check code style: `make lint`
+- [ ] Build gem: `make build`
+- [ ] Test installation: `make install`
+- [ ] Commit and tag: `git tag v0.1.X`
+- [ ] Push with tags: `git push --tags`
+- [ ] Publish to RubyGems: `gem push language-operator-X.gem`

data/.claude/skills/skill-rules.json

@@ -0,0 +1,117 @@
+{
+  "version": "1.0",
+  "description": "Skill activation triggers for Language Operator Ruby gem development",
+  "skills": {
+    "ruby-gem-development": {
+      "type": "domain",
+      "enforcement": "suggest", 
+      "priority": "high",
+      "description": "Ruby gem development patterns with bundler, RSpec, and RuboCop",
+      "promptTriggers": {
+        "keywords": [
+          "gem", "gemspec", "bundler", "bundle",
+          "RSpec", "rspec", "test", "spec",
+          "RuboCop", "rubocop", "lint", 
+          "Rakefile", "rake task",
+          "version", "release", "publish"
+        ],
+        "intentPatterns": [
+          "(create|add|implement|build).*?(gem|library)",
+          "(test|spec).*?(pattern|structure)",
+          "(fix|improve).*?(test|spec)", 
+          "(lint|format).*?(code|ruby)",
+          "(build|release|publish).*?(gem)",
+          "(add|create).*?(rake task)"
+        ]
+      },
+      "fileTriggers": {
+        "pathPatterns": [
+          "*.gemspec",
+          "Gemfile",
+          "Gemfile.lock", 
+          "Rakefile",
+          "lib/**/*.rb",
+          "spec/**/*_spec.rb"
+        ],
+        "pathExclusions": [
+          "vendor/**",
+          ".bundle/**"
+        ],
+        "contentPatterns": [
+          "require.*language_operator",
+          "describe.*do",
+          "it.*do",
+          "RSpec\\.describe",
+          "Gem::Specification",
+          "spec\\.add_"
+        ]
+      }
+    },
+    "thor-cli-development": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "high", 
+      "description": "Thor-based CLI development patterns for aictl",
+      "promptTriggers": {
+        "keywords": [
+          "CLI", "command", "Thor", "aictl",
+          "subcommand", "argument", "option",
+          "wizard", "interactive"
+        ],
+        "intentPatterns": [
+          "(create|add|implement).*?(command|CLI)",
+          "(add|create).*?(subcommand|option)",
+          "(implement|build).*?(wizard|interactive)",
+          "(format|display).*?(output|table)"
+        ]
+      },
+      "fileTriggers": {
+        "pathPatterns": [
+          "lib/language_operator/cli/**/*.rb",
+          "bin/aictl"
+        ],
+        "contentPatterns": [
+          "class.*< Thor",
+          "desc.*,",
+          "option.*:",
+          "Commands::",
+          "Wizards::"
+        ]
+      }
+    },
+    "language-operator-dsl": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "high",
+      "description": "Language Operator DSL patterns for agents, tools, and workflows",
+      "promptTriggers": {
+        "keywords": [
+          "DSL", "agent", "tool", "workflow", 
+          "MCP", "server", "schema",
+          "execution", "kubernetes", "deployment"
+        ],
+        "intentPatterns": [
+          "(create|define|implement).*?(agent|tool|workflow)",
+          "(add|modify).*?(DSL|schema)",
+          "(deploy|run).*?(agent|kubernetes)",
+          "(test|validate).*?(DSL|schema)"
+        ]
+      },
+      "fileTriggers": {
+        "pathPatterns": [
+          "lib/language_operator/dsl/**/*.rb",
+          "lib/language_operator/agent/**/*.rb",
+          "lib/language_operator/kubernetes/**/*.rb"
+        ],
+        "contentPatterns": [
+          "LanguageOperator::Dsl",
+          "agent.*do",
+          "tool.*do", 
+          "workflow.*do",
+          "execute.*do",
+          "kubernetes.*apply"
+        ]
+      }
+    }
+  }
+}