clawthor 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6985fc3b3cab8dd71f374358ff84a42372eb2f2d21e6cd8e85977d46872b45e4
+  data.tar.gz: 89406b5bf06098b8ab948e420f68e0be3348869bd789b2ad97dea5e09b242d5f
+SHA512:
+  metadata.gz: e346098784576ed8394bfca1a835242d3872daa79fa5341173c58b90f4070794460e04debd7f6c240b2d7990162fd212736277e9830a639cfc079d8f88d46048
+  data.tar.gz: d00b4ac51010bbe2a7caa93cb4728b12cc84aa2879eb774a4bc65d0a1c05f3206eb8136f63a9b40af3f0121bb49dae05e0f8da87e505cb9890bdc6c65f9c267d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthropic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,365 @@
+# Clawthor Gem
+
+The **compiler** that transforms declarative plugin definitions into fully-functional Claude Code plugins.
+
+## What This Does
+
+You write a simple Ruby file describing your plugin (skills, commands, agents). Clawthor compiles it into:
+- Plugin manifest (JSON)
+- Markdown documentation
+- YAML configuration files
+- Ready to use!
+
+## Installation
+
+### Option 1: From RubyGems (recommended)
+
+```bash
+gem install clawthor
+clawthor --version
+```
+
+### Option 2: Build locally
+
+```bash
+git clone <repo>
+cd clawthor
+gem build clawthor.gemspec
+gem install ./clawthor-*.gem
+```
+
+## 5-Minute Example
+
+### 1. Create a definition file
+
+```ruby
+# my_plugin.rb
+workspace :my_plugin do
+  author "Your Name"
+  version "1.0.0"
+
+  skill :code_review do
+    description "Code review guidelines"
+    section "Python" do
+      guideline "Check for type hints"
+      guideline "Verify docstrings"
+    end
+  end
+
+  command :review do
+    description "Review Python code"
+    template do
+      prompt "Review the following code with Python guidelines"
+    end
+  end
+end
+```
+
+### 2. Compile it
+
+```bash
+clawthor compile my_plugin.rb output/
+```
+
+### 3. Use it
+
+```bash
+claude --plugin-dir ./output
+```
+
+Done! You now have a working Claude Code plugin.
+
+## CLI Usage
+
+```bash
+# Compile with defaults
+clawthor compile
+
+# Specify files
+clawthor compile definition.rb output/
+
+# Marketplace format (for distribution)
+clawthor compile definition.rb output/ --marketplace
+
+# Get help
+clawthor compile --help
+```
+
+## Programmatic Usage
+
+```ruby
+require "clawthor"
+
+# Compile a plugin
+Clawthor.compile(
+  definition_file: "my_plugin.rb",
+  output_dir: "dist/",
+  mode: :plugin  # :plugin or :marketplace
+)
+```
+
+## DSL Basics
+
+### The Six Primitives
+
+```ruby
+workspace :my_plugin do
+  # Metadata
+  author "Your Name"
+  version "1.0.0"
+
+  # 1. Skill — A knowledge area with sections and guidelines
+  skill :best_practices do
+    description "Development best practices"
+    section "Testing" do
+      guideline "Write tests first"
+      guideline "Aim for 80%+ coverage"
+    end
+  end
+
+  # 2. Command — A user-runnable slash command
+  command :review do
+    description "Review code"
+    template do
+      prompt "Review this code"
+    end
+  end
+
+  # 3. Agent — A specialized role
+  agent :reviewer do
+    description "Code reviewer"
+    contract "Review code thoroughly"
+    instruction "Be constructive"
+  end
+
+  # 4. Task — Persistent working memory
+  task :planning do
+    description "Project plan"
+    template "# Project Plan\n\n## Goals\n"
+  end
+
+  # 5. Hook — Lifecycle interceptor (advanced)
+  hook :on_start do
+    description "Initialize plugin"
+    handler "initialize_plugin()"
+  end
+
+  # 6. Service — Background process (advanced)
+  service :health_check do
+    description "Monitor plugin health"
+    command "health-check.sh"
+  end
+end
+```
+
+### Modules (Reusable Blocks)
+
+Define reusable modules and include them in multiple plugins:
+
+```ruby
+# Define a module
+define_module :testing_module do
+  skill :testing do
+    description "Testing best practices"
+    section "Pytest" do
+      guideline "Use fixtures for setup"
+    end
+  end
+
+  command :test do
+    description "Run tests"
+    template { prompt "Run the tests" }
+  end
+end
+
+# Use in your plugin
+workspace :my_plugin do
+  version "1.0.0"
+  use :testing_module  # Includes all definitions from module
+
+  # Add your own definitions
+  skill :custom do
+    description "My custom skill"
+  end
+end
+```
+
+## Common Patterns
+
+### Organize Skills by Topic
+
+```ruby
+skill :python do
+  description "Python development"
+
+  section "Type Hints" do
+    guideline "Use type hints on all functions"
+    guideline "Check with mypy"
+  end
+
+  section "Testing" do
+    guideline "Write pytest tests"
+    guideline "Cover edge cases"
+  end
+end
+```
+
+### Create Actionable Commands
+
+```ruby
+command :refactor do
+  description "Refactor Python code"
+  template do
+    prompt "Refactor this code to be more Pythonic"
+  end
+end
+
+command :test do
+  description "Run test suite"
+  template do
+    prompt "Run: pytest tests/"
+  end
+end
+```
+
+### Build Custom Agents
+
+```ruby
+agent :code_reviewer do
+  description "Expert code reviewer"
+
+  contract "Review code against best practices"
+  instruction "Identify improvements"
+  instruction "Explain reasoning"
+  instruction "Be constructive and helpful"
+end
+```
+
+## Real Example: Baseline Plugin
+
+See [../baseline/](../baseline/) for a production-ready plugin with:
+- 5 reusable modules
+- Multiple skills and agents
+- Real commands and tasks
+- Full documentation
+
+```bash
+cd ../baseline
+rake build          # Compile
+claude --plugin-dir ./output  # Use it
+```
+
+## Testing Your Plugin
+
+### Validate the manifest
+
+```bash
+clawthor compile my_plugin.rb output/
+claude plugin validate output/
+```
+
+### Test with Claude Code
+
+```bash
+claude --plugin-dir ./output
+```
+
+Then try your commands in a session.
+
+## Development
+
+### Run tests
+
+```bash
+rake test        # All tests (unit + integration)
+rake test_fast   # Unit tests only (~1 sec)
+```
+
+### Build locally
+
+```bash
+gem build clawthor.gemspec
+gem install ./clawthor-*.gem
+clawthor --version
+```
+
+### Debug compilation
+
+```bash
+# Verbose output
+clawthor compile my_plugin.rb output/ --debug
+
+# Check generated files
+ls -la output/
+cat output/plugin.json | jq
+```
+
+## Troubleshooting
+
+### "No such file or directory" error
+
+Make sure your definition file exists and the path is correct:
+```bash
+ls my_plugin.rb
+clawthor compile my_plugin.rb output/
+```
+
+### Plugin doesn't appear in Claude Code
+
+1. Validate: `claude plugin validate output/`
+2. Check the path: `claude --plugin-dir ./output`
+3. Restart Claude Code
+
+### Ruby version issues
+
+Clawthor requires Ruby 3.0+:
+```bash
+ruby --version
+```
+
+## Advanced
+
+### Two Output Modes
+
+```bash
+# Standard plugin layout
+clawthor compile my_plugin.rb output/
+
+# Marketplace layout (for distribution)
+clawthor compile my_plugin.rb dist/ --marketplace
+```
+
+The marketplace format includes additional files for publishing.
+
+### Custom Modules
+
+Create `.rb` files with module definitions and require them:
+
+```ruby
+require_relative './my_module'
+
+workspace :my_plugin do
+  use :my_module
+end
+```
+
+## Migration from Older Systems
+
+Using `ruby generate.rb` or an old Clawthor version? See [MIGRATION.md](MIGRATION.md).
+
+## Resources
+
+- [Baseline Plugin](../baseline/README.md) — Production-ready reference
+- [CHANGELOG](CHANGELOG.md) — Version history
+- [MIGRATION](MIGRATION.md) — Upgrading guide
+
+## License
+
+MIT License
+
+## Next Steps
+
+1. [Write your first plugin](#5-minute-example)
+2. [Explore the baseline plugin](../baseline/README.md)
+3. [Copy modules to reuse](../baseline/modules/)
+4. [Run tests](#run-tests)

data/exe/clawthor

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "clawthor"
+
+exit Clawthor::CLI.start(ARGV)

data/lib/clawthor/cli.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Clawthor
+  class CLI
+    def self.start(argv)
+      cli = new
+      cli.run(argv)
+    end
+
+    def run(argv)
+      # Parse arguments
+      args = argv.dup
+
+      # Remove 'compile' subcommand if present
+      args.shift if args[0] == "compile"
+
+      mode = args.delete("--marketplace") ? :marketplace : :plugin
+
+      # Handle help
+      if args.any? { |arg| arg.start_with?("--") && arg != "--marketplace" }
+        help_arg = args.find { |arg| arg.start_with?("--") }
+        if %w[--help -h].include?(help_arg)
+          puts usage
+          return 0
+        end
+        if %w[--version -v].include?(help_arg)
+          puts "clawthor #{Clawthor::VERSION}"
+          return 0
+        end
+        puts "Error: Unknown option(s): #{args.select { |arg| arg.start_with?("--") }.join(', ')}"
+        puts usage
+        return 2
+      end
+
+      # Validate argument count
+      if args.length > 2
+        puts "Error: Too many positional arguments."
+        puts usage
+        return 1
+      end
+
+      # Get definition and output paths
+      definition_file = args[0] || File.join(Dir.pwd, "definition.rb")
+      output_dir      = args[1] || File.join(Dir.pwd, "output")
+
+      # Validate definition file exists
+      unless File.exist?(definition_file)
+        puts "Error: Definition file not found: #{definition_file}"
+        puts usage
+        return 1
+      end
+
+      # Print header
+      puts "╔══════════════════════════════════════════════╗"
+      puts "║  Claude Code Orchestration DSL Compiler      ║"
+      puts "╚══════════════════════════════════════════════╝"
+      puts ""
+      puts "Definition: #{definition_file}"
+      puts "Output:     #{output_dir}"
+      puts "Mode:       #{mode}"
+      puts ""
+
+      # Compile
+      registry = compile(definition_file, output_dir, mode)
+
+      # Print summary
+      puts ""
+      if mode == :marketplace
+        plugin_name = registry.workspace ? registry.workspace.plugin_name : "orchestrator"
+        plugin_dir = File.join(output_dir, "plugins", plugin_name)
+        marketplace_manifest = File.join(output_dir, ".claude-plugin", "marketplace.json")
+        puts "To validate:"
+        puts "  claude plugin validate #{marketplace_manifest}"
+        puts "  claude plugin validate #{plugin_dir}"
+      else
+        puts "To test:"
+        puts "  claude --plugin-dir #{output_dir}"
+        puts ""
+        puts "To install into a project:"
+        plugin_name = registry.workspace ? registry.workspace.plugin_name : "orchestrator"
+        puts "  cp -r #{output_dir}/ .claude-plugins/#{plugin_name}/"
+      end
+      puts ""
+      puts "Commands available (namespaced):"
+      registry.commands.each do |name, _cmd|
+        ns = registry.workspace ? registry.workspace.plugin_name : "orchestrator"
+        puts "  /#{ns}:#{name.to_s.tr('_', '-')}"
+      end
+      puts ""
+
+      0
+    rescue => e
+      puts "Error: #{e.message}"
+      puts e.backtrace.join("\n") if ENV["DEBUG"]
+      1
+    end
+
+    private
+
+    def compile(definition_file, output_dir, mode)
+      # Reset registry for fresh compilation
+      registry = Clawthor::DSL::Registry.new
+      Clawthor::DSL.send(:remove_const, :REGISTRY) if Clawthor::DSL.const_defined?(:REGISTRY)
+      Clawthor::DSL.const_set(:REGISTRY, registry)
+
+      # Evaluate the definition file in DSL context
+      context = Object.new
+      context.extend(Clawthor::DSL::Methods)
+      context.instance_eval(File.read(definition_file), definition_file)
+
+      # Compile to output
+      compiler = Clawthor::Compiler.new(Clawthor::DSL::REGISTRY, output_dir, mode: mode)
+      compiler.compile!
+
+      Clawthor::DSL::REGISTRY
+    end
+
+    def usage
+      <<~USAGE
+        Usage: clawthor compile [OPTIONS] [DEFINITION] [OUTPUT]
+
+        OPTIONS:
+          --marketplace       Generate marketplace layout
+          --help, -h          Show help
+          --version, -v       Show version
+
+        ARGUMENTS:
+          DEFINITION          Path to definition file (default: ./definition.rb)
+          OUTPUT              Output directory (default: ./output)
+
+        EXAMPLES:
+          clawthor compile
+          clawthor compile definition.rb output/
+          clawthor compile definition.rb output/ --marketplace
+      USAGE
+    end
+  end
+end