clawthor 0.3.0

data/lib/clawthor/compiler.rb

@@ -0,0 +1,1258 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Clawthor
+  class Compiler
+    DEFAULT_PLUGIN_DESCRIPTION = "Plugin for Claude workflows."
+    DEFAULT_PLUGIN_AUTHOR = "James"
+    DEFAULT_MARKETPLACE_DESCRIPTION = "Claude plugins for Pants projects."
+    DEFAULT_MARKETPLACE_KEYWORDS = %w[claude plugin].freeze
+
+    def initialize(registry, output_dir, mode: :plugin)
+      @reg = registry
+      @out = output_dir
+      @mode = mode.to_sym
+    end
+
+    def compile!
+      ws = @reg.workspace || default_workspace
+      puts "Compiling workspace: #{ws.name}"
+      puts "  Output: #{@out}"
+
+      case @mode
+      when :plugin
+        compile_plugin_bundle!(ws, @out, clean: true)
+      when :marketplace
+        compile_marketplace_bundle!(ws)
+      else
+        raise "Unknown compile mode: #{@mode}"
+      end
+
+      puts "Done. #{count_files(@out)} files generated."
+    end
+
+    private
+
+    def compile_plugin_bundle!(ws, output_dir, clean:)
+      previous_out = @out
+      @out = output_dir
+      FileUtils.rm_rf(@out) if clean
+
+      compile_manifest(ws)
+      compile_config(ws)
+      compile_authority(ws)
+      compile_skills
+      compile_agents
+      compile_commands
+      compile_hooks(ws)
+      compile_services
+      compile_readme(ws)
+    ensure
+      @out = previous_out
+    end
+
+    def compile_marketplace_bundle!(ws)
+      marketplace_root = @out
+      plugin_id = ws.plugin_name
+      plugin_dir = File.join(marketplace_root, "plugins", plugin_id)
+
+      FileUtils.rm_rf(marketplace_root)
+      compile_plugin_bundle!(ws, plugin_dir, clean: false)
+      compile_marketplace_manifest(ws, marketplace_root, plugin_id)
+    end
+
+    # ─── Manifest ──────────────────────────────────────────
+
+    def compile_manifest(ws)
+      dir = File.join(@out, ".claude-plugin")
+      FileUtils.mkdir_p(dir)
+
+      manifest = {
+        "name"        => ws.plugin_name,
+        "description" => plugin_description(ws.description),
+        "version"     => ws.version,
+        "author"      => { "name" => plugin_author(ws.author) }
+      }
+
+      write_json(File.join(dir, "plugin.json"), manifest)
+      puts "  ✓ .claude-plugin/plugin.json"
+    end
+
+    def plugin_description(description)
+      value = description.to_s.strip
+      value.empty? ? DEFAULT_PLUGIN_DESCRIPTION : value
+    end
+
+    def plugin_author(author)
+      value = author.to_s.strip
+      value.empty? ? DEFAULT_PLUGIN_AUTHOR : value
+    end
+
+    def compile_marketplace_manifest(ws, marketplace_root, plugin_id)
+      dir = File.join(marketplace_root, ".claude-plugin")
+      FileUtils.mkdir_p(dir)
+
+      owner = { "name" => plugin_author(ws.author) }
+      owner_url = ws.marketplace_owner_url.to_s.strip
+      owner["url"] = owner_url unless owner_url.empty?
+
+      manifest = {
+        "name" => marketplace_name(ws),
+        "description" => marketplace_description(ws),
+        "metadata" => { "description" => marketplace_description(ws) },
+        "owner" => owner,
+        "plugins" => [
+          {
+            "name" => plugin_id,
+            "source" => "./plugins/#{plugin_id}",
+            "description" => plugin_description(ws.description),
+            "version" => ws.version,
+            "keywords" => DEFAULT_MARKETPLACE_KEYWORDS
+          }
+        ]
+      }
+
+      write_json(File.join(dir, "marketplace.json"), manifest)
+      puts "  ✓ .claude-plugin/marketplace.json"
+    end
+
+    def marketplace_name(ws)
+      value = ws.marketplace_name.to_s.strip
+      value.empty? ? ws.plugin_name : value
+    end
+
+    def marketplace_description(ws)
+      value = ws.marketplace_description.to_s.strip
+      value.empty? ? DEFAULT_MARKETPLACE_DESCRIPTION : value
+    end
+
+    # ─── Config ────────────────────────────────────────────
+
+    def compile_config(ws)
+      config = {
+        "build" => {
+          "command"         => "",
+          "directory"       => ".",
+          "error_threshold" => 5,
+          "_comment"        => "Set 'command' to your build/typecheck command."
+        },
+        "risky_patterns" => {
+          "patterns" => %w[try catch except rescue async await exec eval subprocess],
+          "reminder" => "⚠️  Risky patterns detected in {count} file(s).\n" \
+                        "❓ Are exceptions logged with context?\n" \
+                        "❓ Are database operations wrapped in transactions?\n" \
+                        "❓ Are async operations using timeout/retry logic?"
+        },
+        "tasks" => {
+          "active_dir"  => ws.defaults[:task_dir] || "dev/active",
+          "archive_dir" => ws.defaults[:archive_dir] || "dev/completed"
+        }
+      }
+
+      write_json(File.join(@out, "config.json"), config)
+      puts "  ✓ config.json"
+    end
+
+    # ─── Authority ──────────────────────────────────────────
+    # Generates two artefacts from the authority ladder:
+    #   1. CLAUDE.md fragment — for embedding in repo-level CLAUDE.md
+    #   2. authority skill — so Claude can resolve conflicts at runtime
+
+    def compile_authority(ws)
+      return if ws.authority_ladder.empty?
+
+      # 1. CLAUDE.md fragment
+      fragment = []
+      fragment << "## Authority Ladder"
+      fragment << ""
+      fragment << "When sources conflict, follow the higher authority."
+      fragment << "If conflict is found, fix the lower source."
+      fragment << ""
+      fragment << "| Rank | Code | Source | Description |"
+      fragment << "|------|------|--------|-------------|"
+
+      ws.authority_ladder.each do |level|
+        fragment << "| #{level[:rank]} | #{level[:code]} | #{level[:name]} | #{level[:description]} |"
+      end
+
+      fragment << ""
+      fragment << "### Conflict Resolution Algorithm"
+      fragment << ""
+      fragment << "1. Identify which sources disagree"
+      fragment << "2. Prefer the higher-ranked authority"
+      fragment << "3. Record the conflict:"
+      fragment << "   - If skills conflict with repo docs: update the skill"
+      fragment << "   - If root CLAUDE.md conflicts with repo docs: add a repo exception"
+      fragment << "   - If the task plan conflicts with repo invariants: revise the plan"
+      fragment << "4. Add an exception note if a lower layer intentionally differs"
+      fragment << ""
+
+      File.write(File.join(@out, "CLAUDE.md"), fragment.join("\n"))
+      puts "  ✓ CLAUDE.md (authority ladder)"
+
+      # 2. Auto-generate authority skill
+      skill_dir = File.join(@out, "skills", "authority")
+      FileUtils.mkdir_p(skill_dir)
+
+      skill_md = []
+      skill_md << "---"
+      skill_md << "name: authority"
+      skill_md << "description: >"
+      skill_md << "  Conflict resolution between sources. Use when you encounter"
+      skill_md << "  contradictory guidance, when docs disagree with code, when"
+      skill_md << "  skills conflict with repo-specific rules, or when unsure"
+      skill_md << "  which source of truth to follow."
+      skill_md << "user-invocable: false"
+      skill_md << "---"
+      skill_md << ""
+      skill_md << "# Authority Ladder"
+      skill_md << ""
+      skill_md << "When sources of truth conflict, follow the higher authority."
+      skill_md << ""
+
+      ws.authority_ladder.each do |level|
+        skill_md << "## #{level[:code]}. #{level[:name]} (Rank #{level[:rank]})"
+        skill_md << ""
+        skill_md << level[:description] unless level[:description].empty?
+        unless level[:examples].empty?
+          level[:examples].each { |ex| skill_md << "- #{ex}" }
+        end
+        skill_md << ""
+      end
+
+      skill_md << "## Resolution Rules"
+      skill_md << ""
+      skill_md << "- Always prefer the higher-ranked source"
+      skill_md << "- If you override a lower source, note WHY"
+      skill_md << "- If a skill contradicts repo docs, the repo docs win (A3 > A5)"
+      skill_md << "- If runtime behavior contradicts docs, reality wins (A0 > everything)"
+      skill_md << "- Task-specific plans (A2) can override general skills (A5) for that task only"
+      skill_md << "- Never silently average between contradictory sources"
+      skill_md << ""
+
+      File.write(File.join(skill_dir, "SKILL.md"), skill_md.join("\n"))
+      puts "  ✓ skills/authority/ (auto-generated from authority ladder)"
+    end
+
+    # ─── Skills ────────────────────────────────────────────
+
+    def compile_skills
+      @reg.skills.each do |name, skill|
+        skill_dir = File.join(@out, "skills", name.to_s.tr("_", "-"))
+        FileUtils.mkdir_p(skill_dir)
+
+        # Main SKILL.md
+        md = skill_to_markdown(skill)
+        File.write(File.join(skill_dir, "SKILL.md"), md)
+
+        # Resources
+        skill.resources.each do |res|
+          res_dir = File.join(skill_dir, File.dirname(res[:path]))
+          FileUtils.mkdir_p(res_dir)
+          # Create a placeholder if the resource doesn't exist yet
+          res_path = File.join(skill_dir, res[:path])
+          unless File.exist?(res_path)
+            File.write(res_path, "# #{res[:name]}\n\nAdd detailed reference content here.\n")
+          end
+        end
+
+        # Scripts
+        skill.scripts.each do |sc|
+          sc_dir = File.join(skill_dir, "scripts")
+          FileUtils.mkdir_p(sc_dir)
+          sc_path = File.join(skill_dir, sc.file || "scripts/#{sc.name}.sh")
+          content = sc.content || "#!/bin/bash\n# #{sc.name}\n# #{sc.purpose}\n# Usage: #{sc.usage}\n\necho 'TODO: implement'\n"
+          File.write(sc_path, content)
+          FileUtils.chmod(0o755, sc_path)
+        end
+
+        puts "  ✓ skills/#{name}/ (#{skill.sections.length} sections, #{skill.resources.length} refs, #{skill.scripts.length} scripts)"
+      end
+    end
+
+    def skill_to_markdown(skill)
+      frontmatter = {
+        "name"        => skill.name.to_s.tr("_", "-"),
+        "description" => skill.description
+      }
+      frontmatter["disable-model-invocation"] = true unless skill.model_invocable
+      frontmatter["user-invocable"] = false unless skill.user_invocable
+
+      lines = ["---"]
+      frontmatter.each { |k, v| lines << "#{k}: #{yaml_value(v)}" }
+      lines << "---"
+      lines << ""
+
+      # Version header — gives Claude temporal awareness
+      if skill.skill_version || skill.since || skill.status != :active
+        lines << "| Field | Value |"
+        lines << "|-------|-------|"
+        lines << "| Version | #{skill.skill_version || '-'} |" if skill.skill_version
+        lines << "| Status | #{skill.status} |"
+        lines << "| Since | #{skill.since || '-'} |" if skill.since
+        lines << "| Applies to | #{skill.applies_to} |" if skill.applies_to
+        lines << ""
+      end
+
+      # Current standard sections
+      skill.sections.each do |section|
+        lines << "## #{section.title}"
+        lines << ""
+        section.guidelines.each do |g|
+          lines << "- #{g}"
+        end
+        section.references.each do |r|
+          lines << "- #{r[:text]}"
+        end
+        lines << ""
+      end
+
+      # Deprecated patterns — Claude should not introduce these
+      unless skill.deprecated_patterns.empty?
+        lines << "## Deprecated Patterns (do NOT introduce in new code)"
+        lines << ""
+        lines << "These patterns exist in legacy code. Do not add them to new files."
+        lines << "When editing a file that uses a deprecated pattern, migrate it"
+        lines << "opportunistically if the change is small and safe."
+        lines << ""
+        skill.deprecated_patterns.each do |d|
+          lines << "### #{d.name}"
+          d.notes.each { |n| lines << "- #{n}" }
+          lines << "- **Migrate**: #{d.migration_hint}" if d.migration_hint
+          lines << ""
+        end
+      end
+
+      # Forbidden patterns — Claude must never use these
+      unless skill.forbidden_patterns.empty?
+        lines << "## Forbidden Patterns (NEVER use)"
+        lines << ""
+        lines << "These patterns are banned. Do not introduce them under any circumstances."
+        lines << "If you encounter them in existing code, flag them for removal."
+        lines << ""
+        skill.forbidden_patterns.each do |f|
+          lines << "### #{f.name}"
+          f.notes.each { |n| lines << "- #{n}" }
+          lines << "- **Replace with**: #{f.migration_hint}" if f.migration_hint
+          lines << ""
+        end
+      end
+
+      lines.join("\n")
+    end
+
+    # ─── Agents ────────────────────────────────────────────
+
+    def compile_agents
+      @reg.agents.each do |name, agent|
+        dir = File.join(@out, "agents")
+        FileUtils.mkdir_p(dir)
+
+        md = agent_to_markdown(agent)
+        File.write(File.join(dir, "#{name.to_s.tr('_', '-')}.md"), md)
+
+        puts "  ✓ agents/#{name}.md"
+      end
+    end
+
+    def agent_to_markdown(agent)
+      frontmatter = {
+        "name"        => agent.name.to_s.tr("_", "-"),
+        "description" => agent.description
+      }
+      frontmatter["tools"] = agent.tools if agent.tools
+      frontmatter["model"] = agent.model if agent.model
+      frontmatter["skills"] = agent.skills_list.map { |s| s.to_s.tr("_", "-") } unless agent.skills_list.empty?
+
+      lines = ["---"]
+      frontmatter.each { |k, v| lines << "#{k}: #{yaml_value(v)}" }
+      lines << "---"
+      lines << ""
+
+      # Role / description
+      lines << agent.role unless agent.role.empty?
+      lines << ""
+
+      # Prompt body if provided
+      if agent.prompt_body
+        lines << agent.prompt_body
+        lines << ""
+      end
+
+      # Input contract
+      unless agent.receives_fields.empty?
+        lines << "## Input"
+        lines << ""
+        agent.receives_fields.each do |f|
+          req = f[:required] ? "**required**" : "optional"
+          lines << "- `#{f[:name]}` (#{f[:type]}, #{req}): #{f[:desc]}"
+        end
+        lines << ""
+      end
+
+      # Output contract
+      unless agent.returns_fields.empty?
+        lines << "## Output Contract"
+        lines << ""
+        lines << "You MUST return results containing these fields:"
+        lines << ""
+        agent.returns_fields.each do |f|
+          req = f[:required] ? "**required**" : "optional"
+          lines << "- `#{f[:name]}` (#{f[:type]}, #{req}): #{f[:desc]}"
+        end
+        lines << ""
+      end
+
+      # Rules
+      unless agent.rules.empty?
+        lines << "## Rules"
+        lines << ""
+        agent.rules.each { |r| lines << "- #{r}" }
+        lines << ""
+      end
+
+      lines.join("\n")
+    end
+
+    # ─── Commands ──────────────────────────────────────────
+
+    def compile_commands
+      @reg.commands.each do |name, cmd|
+        dir = File.join(@out, "commands")
+        FileUtils.mkdir_p(dir)
+
+        md = command_to_markdown(cmd)
+        File.write(File.join(dir, "#{name.to_s.tr('_', '-')}.md"), md)
+
+        puts "  ✓ commands/#{name}.md"
+      end
+
+      # Also generate task-related commands from task definitions
+      @reg.tasks.each do |name, task|
+        generate_task_commands(task)
+      end
+    end
+
+    def command_to_markdown(cmd)
+      frontmatter = {
+        "name"        => cmd.name.to_s.tr("_", "-"),
+        "description" => cmd.description
+      }
+      frontmatter["argument-hint"] = cmd.hint if cmd.hint
+      frontmatter["disable-model-invocation"] = true if cmd.disable_model_invocation
+      frontmatter["context"] = cmd.context if cmd.context
+      frontmatter["agent"]   = cmd.agent_name.to_s.tr("_", "-") if cmd.agent_name
+
+      lines = ["---"]
+      frontmatter.each { |k, v| lines << "#{k}: #{yaml_value(v)}" }
+      lines << "---"
+      lines << ""
+      lines << cmd.body
+      lines << ""
+
+      lines.join("\n")
+    end
+
+    def generate_task_commands(task)
+      dir = File.join(@out, "commands")
+      FileUtils.mkdir_p(dir)
+
+      # Generate a 'start-task' command if none exists for this task pattern
+      return if @reg.commands.key?(:plan) || @reg.commands.key?(:start)
+
+      # Auto-generate checkpoint command from task definition
+      unless @reg.commands.key?(:checkpoint)
+        checkpoint_body = "Update the active dev docs:\n\n"
+        task.files.each do |f|
+          checkpoint_body += "- Update `#{f[:filename]}`: mark completed items, add new items, update timestamps\n"
+        end
+        checkpoint_body += "\nWrite a resumption note in the context file so a fresh session can continue.\n"
+
+        lines = [
+          "---",
+          "name: checkpoint",
+          "description: Save working state to dev docs before compaction",
+          "disable-model-invocation: true",
+          "---",
+          "",
+          checkpoint_body
+        ]
+        File.write(File.join(dir, "checkpoint.md"), lines.join("\n"))
+        puts "  ✓ commands/checkpoint.md (auto-generated from task :#{task.name})"
+      end
+
+      # Auto-generate resume command
+      unless @reg.commands.key?(:resume)
+        task_dir = task.directory_pattern.gsub("{task_name}", "*").gsub(/\/+$/, "")
+        lines = [
+          "---",
+          "name: resume",
+          "description: Resume work from the last checkpoint",
+          "disable-model-invocation: true",
+          "---",
+          "",
+          "Resume work from active dev docs:",
+          "",
+          "1. List directories in `#{File.dirname(task_dir)}/`",
+          "2. Read all task files",
+          "3. Check for a resumption note",
+          "4. Report progress and next steps",
+          "5. Continue implementing",
+          ""
+        ]
+        File.write(File.join(dir, "resume.md"), lines.join("\n"))
+        puts "  ✓ commands/resume.md (auto-generated from task :#{task.name})"
+      end
+    end
+
+    # ─── Hooks ─────────────────────────────────────────────
+
+    def compile_hooks(ws)
+      hooks_dir = File.join(@out, "hooks")
+      scripts_dir = File.join(@out, "scripts")
+      FileUtils.mkdir_p(hooks_dir)
+      FileUtils.mkdir_p(scripts_dir)
+
+      hooks_json = {}
+
+      @reg.hooks.each do |name, hook|
+        event_key = hook.event_key
+
+        hooks_json[event_key] ||= []
+
+        entry = { "hooks" => [] }
+        entry["matcher"] = hook.matcher if hook.matcher
+
+        if hook.script_content
+          # Write the script file
+          script_path = File.join(scripts_dir, "#{name}.sh")
+          File.write(script_path, hook.script_content)
+          FileUtils.chmod(0o755, script_path)
+
+          hook_def = {
+            "type"    => "command",
+            "command" => "bash \"$CLAUDE_PROJECT_DIR/scripts/#{name}.sh\""
+          }
+          puts "  ✓ scripts/#{name}.sh"
+        elsif hook.type == "prompt"
+          hook_def = { "type" => "prompt", "prompt" => hook.prompt }
+          hook_def["model"] = hook.model if hook.model
+        elsif hook.type == "agent"
+          hook_def = { "type" => "agent", "prompt" => hook.prompt }
+          hook_def["timeout"] = hook.timeout if hook.timeout
+        else
+          hook_def = {
+            "type"    => hook.type || "command",
+            "command" => hook.command
+          }
+        end
+
+        hook_def["timeout"] = hook.timeout if hook.timeout && hook_def["type"] == "command"
+        entry["hooks"] << hook_def
+        hooks_json[event_key] << entry
+      end
+
+      # Add auto-generated hooks from task definitions
+      inject_task_hooks(hooks_json)
+
+      write_json(File.join(hooks_dir, "hooks.json"), { "hooks" => hooks_json })
+      puts "  ✓ hooks/hooks.json (#{@reg.hooks.length} hooks)"
+    end
+
+    def inject_task_hooks(hooks_json)
+      return if @reg.tasks.empty?
+
+      # Auto-generate a SessionStart/compact hook to re-inject task context
+      return if @reg.hooks.values.any? { |h| h.event == :session_start && h.matcher == "compact" }
+
+      task = @reg.tasks.values.first
+      task_dir = task.directory_pattern.gsub("{task_name}", "*").gsub(/\/+$/, "")
+      base_dir = File.dirname(task_dir)
+
+      script = <<~BASH
+        #!/bin/bash
+        # Auto-generated: re-inject active task context after compaction
+        set -euo pipefail
+
+        ACTIVE_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/#{base_dir}"
+
+        if [ ! -d "$ACTIVE_DIR" ]; then
+          exit 0
+        fi
+
+        TASKS=$(ls -d "$ACTIVE_DIR"/*/ 2>/dev/null || true)
+        if [ -z "$TASKS" ]; then
+          exit 0
+        fi
+
+        echo ""
+        echo "═══════════════════════════════════════════"
+        echo "📌 ACTIVE TASKS (restored after compaction)"
+        echo "═══════════════════════════════════════════"
+
+        for TASK_PATH in $TASKS; do
+          TASK_NAME=$(basename "$TASK_PATH")
+          echo ""
+          echo "── Task: $TASK_NAME ──"
+
+          for F in "$TASK_PATH"/*; do
+            [ -f "$F" ] || continue
+            echo ""
+            echo "### $(basename "$F")"
+            head -40 "$F"
+            LINES=$(wc -l < "$F" | tr -d ' ')
+            [ "$LINES" -gt 40 ] && echo "... ($LINES total lines)"
+          done
+        done
+
+        echo ""
+        echo "═══════════════════════════════════════════"
+        exit 0
+      BASH
+
+      scripts_dir = File.join(@out, "scripts")
+      FileUtils.mkdir_p(scripts_dir)
+      script_path = File.join(scripts_dir, "inject-context.sh")
+      File.write(script_path, script)
+      FileUtils.chmod(0o755, script_path)
+
+      hooks_json["SessionStart"] ||= []
+      hooks_json["SessionStart"] << {
+        "matcher" => "compact",
+        "hooks"   => [{ "type" => "command", "command" => 'bash "$CLAUDE_PROJECT_DIR/scripts/inject-context.sh"' }]
+      }
+
+      puts "  ✓ scripts/inject-context.sh (auto-generated from task definition)"
+    end
+
+    # ─── Services (supervisord) ──────────────────────────────
+
+    def compile_services
+      return if @reg.services.empty?
+
+      ws = @reg.workspace || default_workspace
+      scripts_dir = File.join(@out, "scripts")
+      FileUtils.mkdir_p(scripts_dir)
+
+      compile_supervisord_conf(ws)
+      compile_svc_script(ws)
+      compile_setup_guide(ws)
+      compile_services_skill(ws)
+      compile_svc_command
+
+      puts "  ✓ services/ (#{@reg.services.length} programs)"
+    end
+
+    # Generate the supervisord .conf with one [program:] per service
+    def compile_supervisord_conf(ws)
+      services_dir = File.join(@out, "services")
+      FileUtils.mkdir_p(services_dir)
+
+      lines = []
+      lines << "; ==================================================================="
+      lines << "; Generated by Clawthor DSL - do not edit by hand"
+      lines << "; Regenerate with: ruby generate.rb"
+      lines << "; ==================================================================="
+      lines << ""
+
+      @reg.services.each do |name, svc|
+        prog_name = name.to_s.tr("_", "-")
+        log_dir = resolve_log_dir(ws, svc)
+
+        lines << "[program:#{prog_name}]"
+        lines << "command=#{svc.command}"
+        lines << "directory=#{resolve_cwd(ws, svc)}"
+        lines << "autostart=true"
+        lines << "autorestart=#{svc.auto_restart}"
+        lines << "startretries=#{svc.start_retries}"
+        lines << "stopsignal=#{svc.stop_signal}"
+        lines << "stopwaitsecs=#{svc.stop_wait}"
+        lines << "killasgroup=#{svc.kill_as_group}"
+        lines << "stopasgroup=#{svc.kill_as_group}"
+        lines << "user=#{svc.user}" if svc.user
+        lines << "stdout_logfile=#{log_dir}/#{prog_name}.out.log"
+        lines << "stderr_logfile=#{log_dir}/#{prog_name}.err.log"
+        lines << "stdout_logfile_maxbytes=#{svc.log_config.max_bytes}"
+        lines << "stderr_logfile_maxbytes=#{svc.log_config.max_bytes}"
+        lines << "stdout_logfile_backups=#{svc.log_config.backups}"
+        lines << "stderr_logfile_backups=#{svc.log_config.backups}"
+
+        unless svc.env_vars.empty?
+          env_str = svc.env_vars.map { |k, v| "#{k}=\"#{v}\"" }.join(",")
+          lines << "environment=#{env_str}"
+        end
+
+        lines << ""
+      end
+
+      File.write(File.join(services_dir, "supervisord.conf"), lines.join("\n"))
+      puts "  ✓ services/supervisord.conf"
+    end
+
+    # Generate the svc wrapper script that Claude (and you) call
+    def compile_svc_script(ws)
+      log_dirs = @reg.services.map { |_, svc| resolve_log_dir(ws, svc) }.uniq
+      default_log_dir = log_dirs.first || "logs"
+
+      script = <<~'BASH'
+        #!/usr/bin/env bash
+        # svc - service control wrapper for supervisord
+        # Generated by Clawthor DSL
+        #
+        # This script is how Claude interacts with your services.
+        # It wraps supervisorctl so Claude can check status, read logs,
+        # restart services, and close the observe-debug-fix loop.
+
+        set -euo pipefail
+
+        LOG_DIR="__LOG_DIR__"
+
+        usage() {
+          cat <<EOF
+        Usage: svc <command> [service] [options]
+
+        Commands:
+          status              Show status of all services
+          logs <svc> [N]      Show last N lines of stderr (default: 200)
+          out  <svc> [N]      Show last N lines of stdout (default: 200)
+          tail <svc>          Follow stderr in real-time (Ctrl-C to stop)
+          restart <svc>       Restart a single service
+          restart-all         Restart all services
+          start               Start all services
+          stop                Stop all services
+          reload              Reread config and update (after config changes)
+
+        Services:
+      EOF
+          # List available services from log directory
+          if [ -d "$LOG_DIR" ]; then
+            for f in "$LOG_DIR"/*.err.log; do
+              [ -f "$f" ] || continue
+              svc=$(basename "$f" .err.log)
+              echo "    $svc"
+            done
+          fi
+        }
+
+        case "${1:-}" in
+          status)
+            supervisorctl status
+            ;;
+
+          logs)
+            svc="${2:?service name required}"
+            lines="${3:-200}"
+            logfile="$LOG_DIR/${svc}.err.log"
+            if [ -f "$logfile" ]; then
+              tail -n "$lines" "$logfile"
+            else
+              echo "No log file at: $logfile" >&2
+              echo "Available:" >&2
+              ls "$LOG_DIR"/*.err.log 2>/dev/null | xargs -I{} basename {} .err.log >&2
+              exit 1
+            fi
+            ;;
+
+          out)
+            svc="${2:?service name required}"
+            lines="${3:-200}"
+            logfile="$LOG_DIR/${svc}.out.log"
+            if [ -f "$logfile" ]; then
+              tail -n "$lines" "$logfile"
+            else
+              echo "No log file at: $logfile" >&2
+              exit 1
+            fi
+            ;;
+
+          tail)
+            svc="${2:?service name required}"
+            logfile="$LOG_DIR/${svc}.err.log"
+            if [ -f "$logfile" ]; then
+              tail -f "$logfile"
+            else
+              echo "No log file at: $logfile" >&2
+              exit 1
+            fi
+            ;;
+
+          restart)
+            svc="${2:?service name required}"
+            supervisorctl restart "$svc"
+            echo "Waiting 2s for startup..."
+            sleep 2
+            # Show last 10 lines of log so Claude can see if it came up clean
+            logfile="$LOG_DIR/${svc}.err.log"
+            [ -f "$logfile" ] && echo "--- last 10 lines of stderr ---" && tail -n 10 "$logfile"
+            ;;
+
+          restart-all)
+            supervisorctl restart all
+            sleep 2
+            supervisorctl status
+            ;;
+
+          start)
+            supervisorctl start all
+            sleep 2
+            supervisorctl status
+            ;;
+
+          stop)
+            supervisorctl stop all
+            ;;
+
+          reload)
+            supervisorctl reread
+            supervisorctl update
+            supervisorctl status
+            ;;
+
+          *)
+            usage
+            exit 2
+            ;;
+        esac
+      BASH
+
+      script = script.gsub("__LOG_DIR__", default_log_dir)
+
+      script_path = File.join(@out, "scripts", "svc")
+      File.write(script_path, script)
+      FileUtils.chmod(0o755, script_path)
+      puts "  ✓ scripts/svc"
+    end
+
+    # Generate the setup guide
+    def compile_setup_guide(ws)
+      services_dir = File.join(@out, "services")
+      log_dirs = @reg.services.map { |_, svc| resolve_log_dir(ws, svc) }.uniq
+      conf_name = ws.plugin_name
+
+      guide = <<~MD
+        # Services Setup Guide
+
+        This project uses supervisord to manage background services.
+        Claude can read logs, restart services, and check status via
+        the `svc` wrapper script or the `/orchestrator:svc` command.
+
+        ## Why services matter
+
+        Without managed services, Claude writes code into a black hole.
+        The service primitive closes the observability loop:
+
+        ```
+        Claude edits code
+            |
+            v
+        supervisord auto-restarts the service
+            |
+            v
+        Claude reads logs (via svc or /orchestrator:svc)
+            |
+            v
+        Claude sees the error
+            |
+            v
+        Claude fixes it
+        ```
+
+        ## Prerequisites
+
+        Install supervisord:
+
+        ```bash
+        # Ubuntu/Debian
+        sudo apt-get update && sudo apt-get install -y supervisor
+
+        # Fedora/RHEL
+        sudo dnf install supervisor
+
+        # macOS (via Homebrew)
+        brew install supervisor
+        ```
+
+        Verify it's running:
+
+        ```bash
+        sudo systemctl status supervisor   # Linux (systemd)
+        brew services info supervisor       # macOS
+        ```
+
+        ## Install the config
+
+        1. Create the log directory:
+        ```bash
+        #{log_dirs.map { |d| "mkdir -p #{d}" }.join("\n")}
+        ```
+
+        2. Copy the generated config to supervisord's config directory:
+        ```bash
+        # Linux (typical)
+        sudo cp services/supervisord.conf /etc/supervisor/conf.d/#{conf_name}.conf
+
+        # macOS (Homebrew)
+        cp services/supervisord.conf /usr/local/etc/supervisor.d/#{conf_name}.ini
+        ```
+
+        3. Load and start:
+        ```bash
+        sudo supervisorctl reread
+        sudo supervisorctl update
+        sudo supervisorctl start all
+        ```
+
+        4. Verify:
+        ```bash
+        sudo supervisorctl status
+        # or
+        ./scripts/svc status
+        ```
+
+        ## The `svc` script
+
+        The `svc` script wraps supervisorctl into a simple interface that
+        both you and Claude can use:
+
+        | Command                    | What it does                              |
+        |----------------------------|-------------------------------------------|
+        | `svc status`               | Show all services and their state         |
+        | `svc logs <name> [lines]`  | Last N lines of stderr (default 200)      |
+        | `svc out <name> [lines]`   | Last N lines of stdout (default 200)      |
+        | `svc tail <name>`          | Follow stderr in real-time                |
+        | `svc restart <name>`       | Restart one service + show startup log    |
+        | `svc restart-all`          | Restart everything                        |
+        | `svc start`                | Start all services                        |
+        | `svc stop`                 | Stop all services                         |
+        | `svc reload`               | Reread config after changes               |
+
+        The `restart` command deliberately waits 2 seconds then prints the
+        last 10 lines of stderr -- this way Claude immediately sees whether
+        the service came up clean or crashed.
+
+        ## How Claude uses it
+
+        When Claude is implementing a backend feature, the typical loop is:
+
+        1. Claude edits a source file
+        2. The Stop hook runs `svc logs <name> 50` to check for errors
+        3. If errors are found, Claude reads the full log and fixes the issue
+        4. If clean, Claude moves to the next task
+
+        You can also ask Claude directly:
+
+        ```
+        Check the api-service logs for errors
+        Restart the email-service and show me the startup log
+        What's the status of all services?
+        ```
+
+        ## Services defined
+
+        | Service | Command | Working Directory |
+        |---------|---------|-------------------|
+      MD
+
+      @reg.services.each do |name, svc|
+        prog_name = name.to_s.tr("_", "-")
+        guide += "| #{prog_name} | `#{svc.command}` | `#{svc.cwd}` |\n"
+      end
+
+      guide += <<~MD
+
+        ## Log locations
+
+        All logs are written to `#{log_dirs.first || 'logs'}/`:
+
+        | File | Content |
+        |------|---------|
+      MD
+
+      @reg.services.each do |name, svc|
+        prog_name = name.to_s.tr("_", "-")
+        log_dir = resolve_log_dir(ws, svc)
+        guide += "| `#{log_dir}/#{prog_name}.out.log` | stdout |\n"
+        guide += "| `#{log_dir}/#{prog_name}.err.log` | stderr (errors, warnings) |\n"
+      end
+
+      guide += <<~MD
+
+        Logs rotate automatically at #{@reg.services.values.first&.log_config&.max_bytes || '50MB'}
+        with #{@reg.services.values.first&.log_config&.backups || 5} backups kept.
+
+        ## Troubleshooting
+
+        **Service won't start**: Check `svc logs <name>` for the error.
+        The most common cause is a missing dependency or wrong working directory.
+
+        **"unix:///var/run/supervisor.sock no such file"**: supervisord isn't
+        running. Start it with `sudo systemctl start supervisor` (Linux)
+        or `brew services start supervisor` (macOS).
+
+        **Permission denied on logs**: The log directory must be writable by
+        the user running supervisord. Either `chown` the directory or run
+        services as your user (set `user=` in the conf).
+
+        **Config changes not applied**: After editing `supervisord.conf`,
+        run `svc reload` to pick up changes.
+      MD
+
+      File.write(File.join(services_dir, "SETUP.md"), guide)
+      puts "  ✓ services/SETUP.md"
+    end
+
+    # Generate a skill that teaches Claude how to use the svc wrapper
+    def compile_services_skill(ws)
+      skill_dir = File.join(@out, "skills", "services")
+      FileUtils.mkdir_p(skill_dir)
+
+      log_dirs = @reg.services.map { |_, svc| resolve_log_dir(ws, svc) }.uniq
+      default_log_dir = log_dirs.first || "logs"
+
+      service_names = @reg.services.keys.map { |n| n.to_s.tr("_", "-") }
+
+      md = <<~SKILL
+        ---
+        name: services
+        description: >
+          Service management and log inspection. Use when the user mentions
+          services, logs, errors, crashes, restarts, or debugging backend
+          issues. Also use when checking if code changes broke a running
+          service, or when implementing features that affect backend services.
+        user-invocable: false
+        ---
+
+        # Service Management
+
+        This project runs #{service_names.length} background service(s) managed by
+        supervisord: #{service_names.join(', ')}.
+
+        ## Checking status
+
+        ```bash
+        ./scripts/svc status
+        ```
+
+        ## Reading logs (most common)
+
+        When debugging or verifying code changes, check stderr first:
+
+        ```bash
+        ./scripts/svc logs <service-name> 200    # last 200 lines of stderr
+        ./scripts/svc out <service-name> 200     # last 200 lines of stdout
+        ```
+
+        ## After editing code
+
+        After modifying source files for a service, the service auto-restarts.
+        Wait 2-3 seconds, then check the logs:
+
+        ```bash
+        sleep 2 && ./scripts/svc logs <service-name> 50
+        ```
+
+        If the service crashed, the last lines of stderr will show why.
+
+        ## Restarting
+
+        ```bash
+        ./scripts/svc restart <service-name>     # restart one (shows startup log)
+        ./scripts/svc restart-all                 # restart everything
+        ```
+
+        ## Available services
+
+      SKILL
+
+      @reg.services.each do |name, svc|
+        prog_name = name.to_s.tr("_", "-")
+        log_dir = resolve_log_dir(ws, svc)
+        md += "- **#{prog_name}**: `#{svc.command}` (logs: `#{log_dir}/#{prog_name}.err.log`)\n"
+      end
+
+      md += <<~SKILL
+
+        ## The observe-debug-fix loop
+
+        1. Edit code that affects a service
+        2. Check logs: `./scripts/svc logs <name> 50`
+        3. If errors, read more: `./scripts/svc logs <name> 200`
+        4. Fix the error
+        5. Verify: `./scripts/svc logs <name> 20`
+        6. Repeat until clean
+
+        Never move on to the next task without checking that affected
+        services are running cleanly.
+      SKILL
+
+      File.write(File.join(skill_dir, "SKILL.md"), md)
+      puts "  ✓ skills/services/ (auto-generated)"
+    end
+
+    # Generate the /svc command for manual invocation
+    def compile_svc_command
+      dir = File.join(@out, "commands")
+      FileUtils.mkdir_p(dir)
+
+      md = <<~CMD
+        ---
+        name: svc
+        description: Inspect service status and logs. Use to check if services are healthy.
+        argument-hint: "[status|logs|restart] [service-name] [lines]"
+        disable-model-invocation: true
+        ---
+
+        Run the service control command:
+
+        ```bash
+        ./scripts/svc $ARGUMENTS
+        ```
+
+        If no arguments provided, show status of all services:
+
+        ```bash
+        ./scripts/svc status
+        ```
+
+        After any restart, check the logs to verify the service came up clean.
+        If you see errors, read more log lines and diagnose the issue.
+      CMD
+
+      File.write(File.join(dir, "svc.md"), md)
+      puts "  ✓ commands/svc.md"
+    end
+
+    def resolve_log_dir(ws, svc)
+      base = svc.log_config.dir
+      return base if base.start_with?("/")
+      base
+    end
+
+    def resolve_cwd(ws, svc)
+      svc.cwd
+    end
+
+    # ─── README ────────────────────────────────────────────
+
+    def compile_readme(ws)
+      lines = []
+      lines << "# #{ws.plugin_name}"
+      lines << ""
+      lines << ws.description unless ws.description.empty?
+      lines << ""
+      lines << "Generated by Clawthor DSL."
+      lines << ""
+
+      lines << "## Skills"
+      @reg.skills.each do |name, s|
+        lines << "- **#{name}**: #{s.description}"
+      end
+      lines << ""
+
+      unless @reg.agents.empty?
+        lines << "## Agents"
+        @reg.agents.each do |name, a|
+          lines << "- **#{name}**: #{a.description}"
+        end
+        lines << ""
+      end
+
+      unless @reg.commands.empty?
+        lines << "## Commands"
+        @reg.commands.each do |name, c|
+          ns = ws.plugin_name
+          lines << "- `/#{ns}:#{name.to_s.tr('_', '-')}`: #{c.description}"
+        end
+        lines << ""
+      end
+
+      unless @reg.hooks.empty?
+        lines << "## Hooks"
+        @reg.hooks.each do |name, h|
+          lines << "- **#{name}** (#{h.event_key}): #{h.matcher || 'all'}"
+        end
+        lines << ""
+      end
+
+      unless @reg.services.empty?
+        lines << "## Services"
+        lines << ""
+        lines << "Managed by supervisord. See `services/SETUP.md` for installation."
+        lines << ""
+        lines << "Quick start:"
+        lines << "```bash"
+        lines << "sudo cp services/supervisord.conf /etc/supervisor/conf.d/#{ws.plugin_name}.conf"
+        lines << "sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start all"
+        lines << "```"
+        lines << ""
+        lines << "| Service | Command | Logs |"
+        lines << "|---------|---------|------|"
+        @reg.services.each do |name, s|
+          prog = name.to_s.tr("_", "-")
+          log_dir = s.log_config.dir
+          lines << "| #{prog} | `#{s.command}` | `./scripts/svc logs #{prog}` |"
+        end
+        lines << ""
+        lines << "Control: `./scripts/svc status`, `./scripts/svc restart <name>`, `./scripts/svc logs <name> [lines]`"
+        lines << ""
+      end
+
+      # File tree
+      lines << "## File Structure"
+      lines << ""
+      lines << "```"
+      lines.concat(generate_tree(@out, ""))
+      lines << "```"
+
+      File.write(File.join(@out, "README.md"), lines.join("\n"))
+      puts "  ✓ README.md"
+    end
+
+    # ─── Helpers ───────────────────────────────────────────
+
+    def yaml_value(v)
+      case v
+      when true, false then v.to_s
+      when Array then v.inspect.tr('"', "'")
+        # Simple inline for short strings, block for multiline
+      when String
+        v.include?("\n") ? ">\n  #{v.gsub("\n", "\n  ")}" : v
+      else v.to_s
+      end
+    end
+
+    def write_json(path, data)
+      File.write(path, JSON.pretty_generate(data) + "\n")
+    end
+
+    def count_files(path = @out)
+      Dir.glob(File.join(path, "**", "*")).count { |f| File.file?(f) }
+    end
+
+    def generate_tree(dir, prefix)
+      lines = []
+      entries = Dir.entries(dir).reject { |e| e.start_with?(".") }.sort
+      entries.each_with_index do |entry, idx|
+        path = File.join(dir, entry)
+        is_last = idx == entries.length - 1
+        connector = is_last ? "└── " : "├── "
+        lines << "#{prefix}#{connector}#{entry}#{'/' if File.directory?(path)}"
+        if File.directory?(path)
+          extension = is_last ? "    " : "│   "
+          lines.concat(generate_tree(path, prefix + extension))
+        end
+      end
+      lines
+    end
+
+    def default_workspace
+      ws = Workspace.new(:default)
+      ws.plugin_name  = "orchestrator"
+      ws.description  = DEFAULT_PLUGIN_DESCRIPTION
+      ws
+    end
+  end
+end