clawthor 0.3.0

data/lib/clawthor/dsl.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Clawthor
+  module DSL
+    # ─── Top-level DSL methods ─────────────────────────────────
+    # These are mixed into the scope where the DSL file is evaluated.
+
+    module Methods
+      def workspace(name, &block)
+        ws = Workspace.new(name)
+        ws.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.set_workspace(ws)
+      end
+
+      def skill(name, &block)
+        s = Skill.new(name)
+        s.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.skills[name] = s
+      end
+
+      def hook(name, &block)
+        h = Hook.new(name)
+        h.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.hooks[name] = h
+      end
+
+      def agent(name, &block)
+        a = Agent.new(name)
+        a.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.agents[name] = a
+      end
+
+      def task(name, &block)
+        t = Task.new(name)
+        t.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.tasks[name] = t
+      end
+
+      def command(name, &block)
+        c = Command.new(name)
+        c.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.commands[name] = c
+      end
+
+      def service(name, &block)
+        s = Service.new(name)
+        s.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.services[name] = s
+      end
+
+      # ─── Module support ──────────────────────────────────────
+
+      # Define a reusable module. The block receives the module-scoped
+      # DSL (skill, hook, agent, command, task, service).
+      def define_module(name, &block)
+        mod = Clawthor::DSL::Module.new(name)
+        mod.instance_eval(&block) if block
+        Clawthor::DSL::REGISTRY.modules[name] = mod
+      end
+
+      # Include a module's primitives into the top-level registry.
+      # The module must have been defined (via define_module) or
+      # loaded (via require_module) before this point.
+      def use(name)
+        mod = Clawthor::DSL::REGISTRY.modules[name]
+        raise "Module :#{name} not found. Define it with define_module or load it with require_module." unless mod
+        Clawthor::DSL::REGISTRY.merge_module!(mod)
+        puts "  [module] :#{name} included (#{mod_summary(mod)})"
+      end
+
+      # Load a module definition from an external file, then include it.
+      # This lets you ship reusable modules as separate .rb files.
+      def require_module(path)
+        resolved = File.expand_path(path)
+        raise "Module file not found: #{resolved}" unless File.exist?(resolved)
+
+        # Evaluate the file in our DSL context so define_module works
+        instance_eval(File.read(resolved), resolved)
+      end
+
+      private
+
+      def mod_summary(mod)
+        parts = []
+        parts << "#{mod.skills.length} skills" unless mod.skills.empty?
+        parts << "#{mod.hooks.length} hooks" unless mod.hooks.empty?
+        parts << "#{mod.agents.length} agents" unless mod.agents.empty?
+        parts << "#{mod.commands.length} commands" unless mod.commands.empty?
+        parts << "#{mod.tasks.length} tasks" unless mod.tasks.empty?
+        parts << "#{mod.services.length} services" unless mod.services.empty?
+        parts.empty? ? "empty" : parts.join(", ")
+      end
+    end
+  end
+end

data/lib/clawthor/orchestrator.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+# ═══════════════════════════════════════════════════════════════
+#  Claude Code DSL - Orchestration Layer
+#
+#  Write declarations → run compiler → get a working plugin.
+#
+#  Primitives:
+#    skill    — knowledge unit with progressive disclosure
+#    hook     — lifecycle interceptor
+#    agent    — specialised sub-instance with a contract
+#    task     — persistent working memory template
+#    command  — prompt expansion template
+#    service  — managed background process
+# ═══════════════════════════════════════════════════════════════
+
+module Clawthor
+  module DSL
+    # Require all primitive classes
+    require_relative "registry"
+    require_relative "primitives/workspace"
+    require_relative "primitives/skill"
+    require_relative "primitives/hook"
+    require_relative "primitives/agent"
+    require_relative "primitives/task"
+    require_relative "primitives/command"
+    require_relative "primitives/service"
+    require_relative "primitives/module"
+    require_relative "dsl"
+
+    # Create global registry instance
+    REGISTRY = Registry.new
+  end
+end

data/lib/clawthor/primitives/agent.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Agent ─────────────────────────────────────────────────
+
+  class Agent
+    attr_accessor :name, :description, :role, :model, :tools, :skills_list
+    attr_reader :receives_fields, :returns_fields, :rules, :prompt_body
+
+    def initialize(name)
+      @name           = name
+      @description    = ""
+      @role           = ""
+      @model          = "inherit"
+      @tools          = nil
+      @skills_list    = []
+      @receives_fields = []
+      @returns_fields  = []
+      @rules          = []
+      @prompt_body    = nil
+    end
+
+    def receives(&block)
+      b = FieldBuilder.new
+      b.instance_eval(&block)
+      @receives_fields = b.fields
+    end
+
+    def returns(&block)
+      b = FieldBuilder.new
+      b.instance_eval(&block)
+      @returns_fields = b.fields
+    end
+
+    def constraints(&block)
+      b = ConstraintBuilder.new
+      b.instance_eval(&block)
+      @rules = b.rules
+    end
+
+    def prompt(text)
+      @prompt_body = text
+    end
+
+    def uses_skills(*names)
+      @skills_list = names
+    end
+  end
+
+  class FieldBuilder
+    attr_reader :fields
+
+    def initialize
+      @fields = []
+    end
+
+    def required(name, type: :string, desc: "")
+      @fields << { name: name, required: true, type: type, desc: desc }
+    end
+
+    def optional(name, type: :string, desc: "")
+      @fields << { name: name, required: false, type: type, desc: desc }
+    end
+  end
+
+  class ConstraintBuilder
+    attr_reader :rules
+
+    def initialize
+      @rules = []
+    end
+
+    def rule(text)
+      @rules << text
+    end
+  end
+end; end

data/lib/clawthor/primitives/command.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Command ───────────────────────────────────────────────
+
+  class Command
+    attr_accessor :name, :description, :hint, :body
+    attr_accessor :disable_model_invocation, :context, :agent_name
+
+    def initialize(name)
+      @name                    = name
+      @description             = ""
+      @hint                    = nil
+      @body                    = ""
+      @disable_model_invocation = true
+      @context                 = nil
+      @agent_name              = nil
+    end
+  end
+end; end

data/lib/clawthor/primitives/hook.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Hook ──────────────────────────────────────────────────
+
+  class Hook
+    EVENTS = %i[
+      session_start user_prompt_submit pre_tool_use post_tool_use
+      post_tool_use_failure stop notification
+      subagent_start subagent_stop pre_compact session_end
+    ].freeze
+
+    EVENT_MAP = {
+      session_start:          "SessionStart",
+      user_prompt_submit:     "UserPromptSubmit",
+      pre_tool_use:           "PreToolUse",
+      post_tool_use:          "PostToolUse",
+      post_tool_use_failure:  "PostToolUseFailure",
+      stop:                   "Stop",
+      notification:           "Notification",
+      subagent_start:         "SubagentStart",
+      subagent_stop:          "SubagentStop",
+      pre_compact:            "PreCompact",
+      session_end:            "SessionEnd"
+    }.freeze
+
+    attr_accessor :name, :event, :matcher, :type, :command, :prompt, :timeout
+    attr_reader :script_content
+
+    def initialize(name)
+      @name           = name
+      @event          = nil
+      @matcher        = nil
+      @type           = "command"
+      @command        = nil
+      @prompt         = nil
+      @timeout        = nil
+      @script_content = nil
+    end
+
+    def event_key
+      EVENT_MAP[@event] || @event.to_s
+    end
+
+    def runs(script_content)
+      @script_content = script_content
+      @command = "bash \"$CLAUDE_PROJECT_DIR/scripts/#{@name}.sh\""
+    end
+  end
+end; end

data/lib/clawthor/primitives/module.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Module ─────────────────────────────────────────────────
+  # A reusable bundle of primitives. Define once, include anywhere.
+  #
+  # Modules can contain any combination of skills, hooks, agents,
+  # commands, tasks, and services. When you `use :module_name`
+  # in a definition, all the module's primitives merge into the
+  # top-level registry.
+  #
+  # Example:
+  #   define_module :services_setup do
+  #     skill :services do ... end
+  #     command :svc_setup do ... end
+  #     hook :check_services do ... end
+  #   end
+  #
+  #   # In your definition:
+  #   use :services_setup
+
+  class Module
+    attr_reader :name, :description, :skills, :hooks, :agents, :tasks, :commands, :services
+
+    def initialize(name)
+      @name        = name
+      @description = ""
+      @skills      = {}
+      @hooks       = {}
+      @agents      = {}
+      @tasks       = {}
+      @commands    = {}
+      @services    = {}
+    end
+
+    # Module-scoped DSL methods — same API as top-level,
+    # but primitives are collected into the module, not the registry.
+
+    def skill(sname, &block)
+      s = Skill.new(sname)
+      s.instance_eval(&block) if block
+      @skills[sname] = s
+    end
+
+    def hook(hname, &block)
+      h = Hook.new(hname)
+      h.instance_eval(&block) if block
+      @hooks[hname] = h
+    end
+
+    def agent(aname, &block)
+      a = Agent.new(aname)
+      a.instance_eval(&block) if block
+      @agents[aname] = a
+    end
+
+    def task(tname, &block)
+      t = Task.new(tname)
+      t.instance_eval(&block) if block
+      @tasks[tname] = t
+    end
+
+    def command(cname, &block)
+      c = Command.new(cname)
+      c.instance_eval(&block) if block
+      @commands[cname] = c
+    end
+
+    def service(sname, &block)
+      s = Service.new(sname)
+      s.instance_eval(&block) if block
+      @services[sname] = s
+    end
+  end
+end; end

data/lib/clawthor/primitives/service.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Service ───────────────────────────────────────────────
+  # Compiles to a supervisord [program:name] block.
+  #
+  # The observability loop:
+  #   Claude edits code -> service auto-restarts -> Claude reads logs
+  #   -> Claude sees the error -> Claude fixes it
+  #
+  # Without this, Claude writes backend code into a black hole.
+
+  class Service
+    attr_accessor :name, :command, :cwd, :user
+    attr_accessor :auto_restart, :start_retries
+    attr_accessor :stop_signal, :stop_wait, :kill_as_group
+    attr_reader   :env_vars, :log_config
+
+    def initialize(name)
+      @name          = name
+      @command       = ""
+      @cwd           = "."
+      @user          = nil
+      @auto_restart  = true
+      @start_retries = 3
+      @stop_signal   = "TERM"
+      @stop_wait     = 15
+      @kill_as_group = true
+      @env_vars      = {}
+      @log_config    = LogConfig.new(name)
+    end
+
+    def logs(&block)
+      @log_config.instance_eval(&block) if block
+    end
+
+    def env(&block)
+      b = EnvBuilder.new
+      b.instance_eval(&block)
+      @env_vars = b.vars
+    end
+  end
+
+  class LogConfig
+    attr_accessor :dir, :max_bytes, :backups
+
+    def initialize(service_name)
+      @dir       = "logs"
+      @max_bytes = "50MB"
+      @backups   = 5
+    end
+
+    def dir(path = nil)
+      return @dir if path.nil?
+      @dir = path
+    end
+
+    def max_bytes(val = nil)
+      return @max_bytes if val.nil?
+      @max_bytes = val
+    end
+
+    def backups(count = nil)
+      return @backups if count.nil?
+      @backups = count
+    end
+  end
+
+  class EnvBuilder
+    attr_reader :vars
+
+    def initialize
+      @vars = {}
+    end
+
+    def set(key, value: nil, from: nil)
+      @vars[key] = value || "(from #{from})"
+    end
+  end
+end; end

data/lib/clawthor/primitives/skill.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Skill ─────────────────────────────────────────────────
+  # Skills have temporal awareness:
+  #   - version/since/status: when and what era this skill belongs to
+  #   - deprecated blocks: patterns Claude should not introduce
+  #   - forbidden blocks: patterns Claude must never use
+  #
+  # This prevents "averaging" between old and new patterns.
+  # Claude sees: current standard, what's legacy, what's banned.
+
+  class Skill
+    attr_accessor :name, :description, :model_invocable, :user_invocable
+    attr_accessor :skill_version, :since, :status, :applies_to
+    attr_reader :sections, :resources, :scripts, :deprecated_patterns, :forbidden_patterns
+
+    def initialize(name)
+      @name                = name
+      @description         = ""
+      @model_invocable     = true
+      @user_invocable      = true
+      @skill_version       = nil
+      @since               = nil
+      @status              = :active    # :active, :deprecated, :experimental
+      @applies_to          = nil        # e.g. "all repos", "backend services"
+      @sections            = []
+      @resources           = []
+      @scripts             = []
+      @deprecated_patterns = []
+      @forbidden_patterns  = []
+    end
+
+    def section(title, &block)
+      s = Section.new(title)
+      s.instance_eval(&block) if block
+      @sections << s
+    end
+
+    def resource(name, path)
+      @resources << { name: name, path: path }
+    end
+
+    def script(name, &block)
+      s = ScriptDef.new(name)
+      s.instance_eval(&block) if block
+      @scripts << s
+    end
+
+    # Deprecated patterns: Claude should not introduce these in new code.
+    # Legacy code using them is acceptable until touched.
+    def deprecated(pattern_name, &block)
+      d = PatternBlock.new(pattern_name, :deprecated)
+      d.instance_eval(&block) if block
+      @deprecated_patterns << d
+    end
+
+    # Forbidden patterns: Claude must never use these, period.
+    def forbidden(pattern_name, &block)
+      f = PatternBlock.new(pattern_name, :forbidden)
+      f.instance_eval(&block) if block
+      @forbidden_patterns << f
+    end
+  end
+
+  # Used for both deprecated and forbidden pattern declarations
+  class PatternBlock
+    attr_reader :name, :severity, :notes, :migration_hint
+
+    def initialize(name, severity)
+      @name           = name
+      @severity       = severity  # :deprecated or :forbidden
+      @notes          = []
+      @migration_hint = nil
+    end
+
+    def note(text)
+      @notes << text
+    end
+
+    def migrate(hint)
+      @migration_hint = hint
+    end
+  end
+
+  class Section
+    attr_reader :title, :guidelines, :references
+
+    def initialize(title)
+      @title      = title
+      @guidelines = []
+      @references = []
+    end
+
+    def guideline(text)
+      @guidelines << text
+    end
+
+    def reference(name, text)
+      @references << { name: name, text: text }
+    end
+  end
+
+  class ScriptDef
+    attr_accessor :name, :file, :usage, :purpose, :content
+
+    def initialize(name)
+      @name    = name
+      @file    = nil
+      @usage   = ""
+      @purpose = ""
+      @content = nil
+    end
+
+    def file(path = nil)
+      return @file if path.nil?
+      @file = path
+    end
+
+    def usage(text = nil)
+      return @usage if text.nil?
+      @usage = text
+    end
+
+    def purpose(text = nil)
+      return @purpose if text.nil?
+      @purpose = text
+    end
+
+    def content(text = nil)
+      return @content if text.nil?
+      @content = text
+    end
+  end
+end; end

data/lib/clawthor/primitives/task.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Task (DevDoc template) ────────────────────────────────
+
+  class Task
+    attr_accessor :name, :directory_pattern
+    attr_reader :files, :states, :transitions
+
+    def initialize(name)
+      @name              = name
+      @directory_pattern = "dev/active/{task_name}/"
+      @files             = []
+      @states            = []
+      @transitions       = []
+    end
+
+    def creates(&block)
+      b = TaskFileBuilder.new
+      b.instance_eval(&block)
+      @files = b.files
+    end
+
+    def lifecycle(&block)
+      b = LifecycleBuilder.new
+      b.instance_eval(&block)
+      @states      = b.states
+      @transitions = b.transitions
+    end
+  end
+
+  class TaskFileBuilder
+    attr_reader :files
+
+    def initialize
+      @files = []
+    end
+
+    def file(name, filename, sections: [], format: nil)
+      @files << { name: name, filename: filename, sections: sections, format: format }
+    end
+  end
+
+  class LifecycleBuilder
+    attr_reader :states, :transitions
+
+    def initialize
+      @states      = []
+      @transitions = []
+    end
+
+    def states(*names)
+      @states = names
+    end
+
+    def transition(from, to:, when: nil)
+      @transitions << { from: from, to: to, condition: binding.local_variable_get(:when) }
+    end
+  end
+end; end

data/lib/clawthor/primitives/workspace.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Clawthor; module DSL
+  # ─── Workspace ──────────────────────────────────────────────
+
+  class Workspace
+    attr_accessor :name, :root, :plugin_name, :description, :version, :author
+    attr_accessor :marketplace_name, :marketplace_description, :marketplace_owner_url
+    attr_reader :defaults, :authority_ladder
+
+    def initialize(name)
+      @name             = name
+      @plugin_name      = name.to_s.tr("_", "-")
+      @root             = "."
+      @description      = "Plugin for Claude workflows."
+      @version          = "0.1.0"
+      @author           = "James"
+      @marketplace_name = nil
+      @marketplace_description = "Claude plugins for Pants projects."
+      @marketplace_owner_url = nil
+      @defaults         = { skill_max_lines: 500, task_dir: "dev/active", archive_dir: "dev/completed" }
+      @authority_ladder  = []
+    end
+
+    def defaults_block(&block)
+      b = DefaultsBuilder.new(@defaults)
+      b.instance_eval(&block)
+    end
+
+    # Declare the conflict resolution hierarchy.
+    # Higher entries win over lower entries.
+    def authority(&block)
+      b = AuthorityBuilder.new
+      b.instance_eval(&block)
+      @authority_ladder = b.levels
+    end
+  end
+
+  class AuthorityBuilder
+    attr_reader :levels
+
+    def initialize
+      @levels = []
+    end
+
+    # Declare an authority level. Order of declaration = rank (highest first).
+    def level(code, name, description: "", examples: [])
+      @levels << {
+        code: code.to_s,
+        name: name,
+        description: description,
+        examples: examples,
+        rank: @levels.length
+      }
+    end
+  end
+
+  class DefaultsBuilder
+    def initialize(hash)
+      @hash = hash
+    end
+
+    def method_missing(name, value = nil, **_kw)
+      @hash[name] = value if value
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+  end
+end; end