schwarm-cli 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f86723cf9675bb0de813b11efa16be17bd2b8bfa74bd9af1203130cdf7fda0f0
-  data.tar.gz: 479a9e83426d1fb675b79dd5780b14264d7a6c8454ee30404c104743aed30fdd
+  metadata.gz: 601a7ca203a5837a47d4bd0348300054e07fe3577a57c99865a64c282e310d8f
+  data.tar.gz: 857487dd8fa4d92e575466ebe1ed63c70fd3b1c744c6b041eb3d4c675c4657fc
 SHA512:
-  metadata.gz: 9e473284f4c066af2f5ed3a77cc365448574acd73a55e1f72e5d2eb94d1b11db5a95fc4fdaf23c498ecb721ef0f2f596ff753c1c869726446a66d6ae622cf167
-  data.tar.gz: b3d2498b0dcea13e9ed75ea1ee865fdf25658a31a5552059cfb617efcead48600f46008fbd4f580766250daa6b99f38619412a4c4cfa32175f6736b7f45e7c3e
+  metadata.gz: 899c50f55a6b91d9a8690603de5cbf7dc429b022f18198d205c3679eb6a97911e1fb5afe6bc96cb8ae76f852bb38edf9ca7ef82df245249e5ef1fc5e8188ccc9
+  data.tar.gz: 506dd09f7f837606a154cd61f0e2f79e7b231af0daa1e495115ba16b2e7c6fc5290dc101fd0c30ca8370132bc08178e39158295100a68c3a36a0e21e2079ca58

data/lib/schwarm_cli/commands/agents.rb

@@ -22,18 +22,23 @@ module SchwarmCli
         handle_errors do
           data = client.agents.find(id)
           output_record(data, fields: {
-                          "ID" => "id", "Name" => "name", "Repository" => "github_repository_id",
-                          "Enabled" => "enabled", "Schedule" => "schedule", "Prompt" => "prompt",
+                          "ID" => "id", "Name" => "name", "Repository" => "github_repository_name",
+                          "Shared Agent" => "shared_agent_id", "Enabled" => "enabled",
+                          "Schedule" => "schedule",
+                          "Additional Instructions" => "additional_instructions",
                           "Created" => "created_at", "Updated" => "updated_at"
                         })
         end
       end
 
-      desc "create", "Create a repository agent"
-      option :name, type: :string, required: true, desc: "Agent name"
+      desc "create", "Create a repository agent (subscribe a shared agent to a repo)"
       option :repo, type: :string, required: true, desc: "Repository ID, owner/repo, or GitHub URL"
-      option :prompt, type: :string, required: true, desc: "Agent prompt"
-      option :schedule, type: :string, desc: "Cron schedule"
+      option :shared_agent, type: :string, required: true,
+                            desc: "Shared agent ID to subscribe to this repository"
+      option :additional_instructions, type: :string,
+                                       desc: "Per-repository additional instructions appended to the shared prompt"
+      option :enabled, type: :boolean, default: true,
+                       desc: "Whether the agent runs (default: true)"
       def create
         handle_errors do
           data = client.agents.create(**create_attrs)
@@ -42,9 +47,9 @@ module SchwarmCli
       end
 
       desc "update ID", "Update a repository agent"
-      option :name, type: :string, desc: "Agent name"
-      option :prompt, type: :string, desc: "Agent prompt"
-      option :schedule, type: :string, desc: "Cron schedule"
+      option :additional_instructions, type: :string,
+                                       desc: "Per-repository additional instructions"
+      option :enabled, type: :boolean, desc: "Whether the agent runs"
       def update(id)
         handle_errors do
           data = client.agents.update(id, **update_attrs)
@@ -82,18 +87,18 @@ module SchwarmCli
 
       def create_attrs
         attrs = {
-          name: options[:name], github_repository_id: resolve_repo(options[:repo]),
-          prompt: options[:prompt]
+          shared_agent_id: options[:shared_agent],
+          github_repository_id: resolve_repo(options[:repo]),
+          enabled: options[:enabled]
         }
-        attrs[:schedule] = options[:schedule] if options[:schedule]
+        attrs[:additional_instructions] = options[:additional_instructions] if options[:additional_instructions]
         attrs
       end
 
       def update_attrs
         {}.tap do |attrs|
-          attrs[:name] = options[:name] if options[:name]
-          attrs[:prompt] = options[:prompt] if options[:prompt]
-          attrs[:schedule] = options[:schedule] if options[:schedule]
+          attrs[:additional_instructions] = options[:additional_instructions] if options[:additional_instructions]
+          attrs[:enabled] = options[:enabled] unless options[:enabled].nil?
         end
       end
     end

data/lib/schwarm_cli/commands/base.rb

@@ -9,6 +9,8 @@ module SchwarmCli
       class_option :url, type: :string, desc: "Schwarm server URL (overrides config)"
       class_option :token, type: :string, desc: "API key (overrides config)"
 
+      def self.exit_on_failure? = true
+
       DEFAULT_LIST_LIMIT = 20
 
       # Declares --limit, --page, --all options for the next method.
@@ -32,6 +34,13 @@ module SchwarmCli
         abort "Error: #{e.message}"
       end
 
+      # Resolves --template input (ID or exact name) to a schwarm template ID.
+      def resolve_template(ref)
+        SchwarmCli::TemplateResolver.new(client: client).resolve(ref)
+      rescue SchwarmCli::TemplateResolver::ResolutionError => e
+        abort "Error: #{e.message}"
+      end
+
       def output_list(data, columns:)
         if options[:json]
           Formatters::Json.format(data)
@@ -80,12 +89,12 @@ module SchwarmCli
         yield
       rescue Faraday::UnauthorizedError
         abort "Error: Unauthorized. Check your API key or run `schwarm configure`."
-      rescue Faraday::ResourceNotFound
-        abort "Error: Not found."
+      rescue Faraday::ResourceNotFound => e
+        abort "Error: #{parse_error_body(e, fallback: 'Not found.')}"
       rescue Faraday::UnprocessableEntityError => e
-        abort "Error: #{parse_error_body(e)}"
+        abort "Error: #{parse_error_body(e, fallback: 'Validation failed')}"
       rescue Faraday::ClientError => e
-        abort "Error: #{e.message}"
+        abort "Error: #{parse_error_body(e, fallback: e.message)}"
       rescue Faraday::ServerError
         abort "Error: Server error. Try again later."
       rescue Faraday::ConnectionFailed
@@ -94,14 +103,14 @@ module SchwarmCli
         abort "Error: Request timed out."
       end
 
-      def parse_error_body(error)
+      def parse_error_body(error, fallback:)
         body = error.response&.dig(:body)
-        return "Validation failed" unless body.is_a?(String)
+        return fallback unless body.is_a?(String) && !body.empty?
 
         parsed = JSON.parse(body)
-        parsed.dig("error", "message") || "Validation failed"
+        parsed.dig("error", "message") || fallback
       rescue JSON::ParserError
-        "Validation failed"
+        fallback
       end
     end
   end

data/lib/schwarm_cli/commands/main.rb

@@ -17,6 +17,8 @@ require_relative "configure"
 module SchwarmCli
   module Commands
     class Main < Thor
+      def self.exit_on_failure? = true
+
       desc "tasks SUBCOMMAND", "Manage tasks"
       subcommand "tasks", Tasks
 
@@ -30,13 +32,13 @@ module SchwarmCli
       subcommand "skills", SkillsCmd
 
       desc "skill-files SUBCOMMAND", "Manage skill files"
-      subcommand "skill-files", SkillFilesCmd
+      subcommand "skill_files", SkillFilesCmd
 
       desc "agents SUBCOMMAND", "Manage repository agents"
       subcommand "agents", Agents
 
       desc "shared-agents SUBCOMMAND", "Manage shared agents"
-      subcommand "shared-agents", SharedAgentsCmd
+      subcommand "shared_agents", SharedAgentsCmd
 
       desc "recurring SUBCOMMAND", "Manage recurring tasks"
       subcommand "recurring", Recurring
@@ -48,7 +50,7 @@ module SchwarmCli
       subcommand "sessions", Sessions
 
       desc "repo-skills SUBCOMMAND", "Manage repository-skill associations"
-      subcommand "repo-skills", RepoSkills
+      subcommand "repo_skills", RepoSkills
 
       desc "configure", "Set up Schwarm CLI configuration"
       subcommand "configure", Configure

data/lib/schwarm_cli/commands/recurring.rb

@@ -13,7 +13,7 @@ module SchwarmCli
             client.recurring.list(repository_id: resolve_repo(options[:repo]), query: options[:query], **page_params)
           end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
-                                      %w[ENABLED enabled], %w[SCHEDULE schedule]])
+                                      %w[ENABLED enabled], %w[SCHEDULE cron_expression]])
         end
       end
 
@@ -23,7 +23,7 @@ module SchwarmCli
           data = client.recurring.find(id)
           output_record(data, fields: {
                           "ID" => "id", "Name" => "name", "Repository" => "github_repository_id",
-                          "Enabled" => "enabled", "Schedule" => "schedule", "Prompt" => "prompt",
+                          "Enabled" => "enabled", "Schedule" => "cron_expression", "Prompt" => "prompt",
                           "Created" => "created_at", "Updated" => "updated_at"
                         })
         end
@@ -38,11 +38,11 @@ module SchwarmCli
         handle_errors do
           attrs = {
             name: options[:name], github_repository_id: resolve_repo(options[:repo]),
-            prompt: options[:prompt], schedule: options[:schedule]
+            prompt: options[:prompt], cron_expression: options[:schedule]
           }
 
           data = client.recurring.create(**attrs)
-          output_record(data, fields: { "ID" => "id", "Name" => "name", "Schedule" => "schedule" })
+          output_record(data, fields: { "ID" => "id", "Name" => "name", "Schedule" => "cron_expression" })
         end
       end
 
@@ -53,7 +53,7 @@ module SchwarmCli
       def update(id)
         handle_errors do
           data = client.recurring.update(id, **update_attrs)
-          output_record(data, fields: { "ID" => "id", "Name" => "name", "Schedule" => "schedule" })
+          output_record(data, fields: { "ID" => "id", "Name" => "name", "Schedule" => "cron_expression" })
         end
       end
 
@@ -80,7 +80,7 @@ module SchwarmCli
         {}.tap do |attrs|
           attrs[:name] = options[:name] if options[:name]
           attrs[:prompt] = options[:prompt] if options[:prompt]
-          attrs[:schedule] = options[:schedule] if options[:schedule]
+          attrs[:cron_expression] = options[:schedule] if options[:schedule]
         end
       end
     end

data/lib/schwarm_cli/commands/repos.rb

@@ -64,7 +64,11 @@ module SchwarmCli
       def pause(id)
         handle_errors do
           data = client.repositories.pause(id)
-          puts "Repository #{id} paused (#{data.dig('data', 'status')})."
+          if options[:json]
+            output_record(data, fields: {})
+          else
+            puts "Repository #{id} paused (#{data.dig('data', 'status')})."
+          end
         end
       end
 
@@ -72,7 +76,11 @@ module SchwarmCli
       def resume(id)
         handle_errors do
           data = client.repositories.resume(id)
-          puts "Repository #{id} resumed (#{data.dig('data', 'status')})."
+          if options[:json]
+            output_record(data, fields: {})
+          else
+            puts "Repository #{id} resumed (#{data.dig('data', 'status')})."
+          end
         end
       end
 

data/lib/schwarm_cli/commands/secrets.rb

@@ -11,50 +11,46 @@ module SchwarmCli
           data = fetch_paged do |page_params|
             client.secrets.list(repository_id: resolve_repo(options[:repo]), **page_params)
           end
-          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
-                                      %w[PATH path]])
+          output_list(data, columns: [%w[ID id], %w[REPO github_repository_name], %w[PATH path]])
         end
       end
 
-      desc "show ID", "Show secret file details"
+      desc "show ID", "Show secret file details (metadata only — content is never returned)"
       def show(id)
         handle_errors do
           data = client.secrets.find(id)
           output_record(data, fields: {
-                          "ID" => "id", "Name" => "name", "Repository" => "github_repository_id",
+                          "ID" => "id", "Repository" => "github_repository_name",
                           "Path" => "path", "Created" => "created_at", "Updated" => "updated_at"
                         })
         end
       end
 
       desc "create", "Create a secret file"
-      option :name, type: :string, required: true, desc: "Secret name"
       option :repo, type: :string, required: true, desc: "Repository ID, owner/repo, or GitHub URL"
       option :path, type: :string, required: true, desc: "File path in workspace"
-      option :content, type: :string, desc: "Secret content"
-      option :file, type: :string, desc: "Read content from file"
+      option :content, type: :string, desc: "Secret content (mutually exclusive with --file)"
+      option :file, type: :string, desc: "Read content from file (mutually exclusive with --content)"
       def create
         handle_errors do
-          content = read_content
           attrs = {
-            name: options[:name], github_repository_id: resolve_repo(options[:repo]),
-            path: options[:path], content:
+            github_repository_id: resolve_repo(options[:repo]),
+            path: options[:path], content: read_content(required: true)
           }
 
           data = client.secrets.create(**attrs)
-          output_record(data, fields: { "ID" => "id", "Name" => "name", "Path" => "path" })
+          output_record(data, fields: { "ID" => "id", "Path" => "path" })
         end
       end
 
       desc "update ID", "Update a secret file"
-      option :name, type: :string, desc: "Secret name"
       option :path, type: :string, desc: "File path in workspace"
-      option :content, type: :string, desc: "Secret content"
-      option :file, type: :string, desc: "Read content from file"
+      option :content, type: :string, desc: "Secret content (mutually exclusive with --file)"
+      option :file, type: :string, desc: "Read content from file (mutually exclusive with --content)"
       def update(id)
         handle_errors do
           data = client.secrets.update(id, **update_attrs)
-          output_record(data, fields: { "ID" => "id", "Name" => "name", "Path" => "path" })
+          output_record(data, fields: { "ID" => "id", "Path" => "path" })
         end
       end
 
@@ -69,19 +65,24 @@ module SchwarmCli
       private
 
       def update_attrs
-        { name: options[:name], path: options[:path] }.compact.tap do |attrs|
-          attrs[:content] = read_content if options[:content] || options[:file]
+        { path: options[:path] }.compact.tap do |attrs|
+          content = read_content(required: false)
+          attrs[:content] = content if content
         end
       end
 
-      def read_content
-        if options[:file]
-          file_path = File.expand_path(options[:file])
-          abort "Error: File not found: #{file_path}" unless File.exist?(file_path)
-          File.read(file_path)
-        else
-          options[:content]
-        end
+      def read_content(required:)
+        abort "Error: --content and --file are mutually exclusive." if options[:content] && options[:file]
+        return options[:content] if options[:content]
+        return read_file(options[:file]) if options[:file]
+
+        abort "Error: one of --content or --file is required." if required
+      end
+
+      def read_file(path)
+        expanded = File.expand_path(path)
+        abort "Error: File not found: #{expanded}" unless File.exist?(expanded)
+        File.read(expanded)
       end
     end
   end

data/lib/schwarm_cli/commands/sessions.rb

@@ -27,7 +27,8 @@ module SchwarmCli
           data = client.sessions.find(id)
           output_record(data, fields: {
                           "ID" => "id", "Source" => "source", "Status" => "status",
-                          "Prompt" => "prompt", "Result" => "result",
+                          "External ID" => "external_id", "Model" => "model_id",
+                          "Error" => "error_message",
                           "Created" => "created_at", "Updated" => "updated_at"
                         })
         end

data/lib/schwarm_cli/commands/skills.rb

@@ -21,19 +21,24 @@ module SchwarmCli
           data = client.skills.find(id)
           output_record(data, fields: {
                           "ID" => "id", "Name" => "name", "Description" => "description",
-                          "Global" => "global", "Created" => "created_at"
+                          "Instructions" => "instructions", "Global" => "global",
+                          "Created" => "created_at"
                         })
         end
       end
 
       desc "create", "Create a skill"
       option :name, type: :string, required: true, desc: "Skill name"
-      option :description, type: :string, desc: "Skill description"
+      option :description, type: :string, required: true, desc: "Skill description"
+      option :instructions, type: :string, desc: "Skill instructions (inline)"
+      option :instructions_file, type: :string, desc: "Read instructions from file"
       option :global, type: :boolean, default: false, desc: "Make skill global"
       def create
         handle_errors do
-          attrs = { name: options[:name], global: options[:global] }
-          attrs[:description] = options[:description] if options[:description]
+          attrs = {
+            name: options[:name], description: options[:description],
+            instructions: read_instructions, global: options[:global]
+          }
 
           data = client.skills.create(**attrs)
           output_record(data, fields: { "ID" => "id", "Name" => "name", "Global" => "global" })
@@ -43,6 +48,8 @@ module SchwarmCli
       desc "update ID", "Update a skill"
       option :name, type: :string, desc: "Skill name"
       option :description, type: :string, desc: "Skill description"
+      option :instructions, type: :string, desc: "Skill instructions (inline)"
+      option :instructions_file, type: :string, desc: "Read instructions from file"
       option :global, type: :boolean, desc: "Make skill global"
       def update(id)
         handle_errors do
@@ -62,10 +69,24 @@ module SchwarmCli
       private
 
       def update_attrs
+        instructions = read_instructions
         { name: options[:name], description: options[:description] }.compact.tap do |attrs|
+          attrs[:instructions] = instructions if instructions
           attrs[:global] = options[:global] unless options[:global].nil?
         end
       end
+
+      def read_instructions
+        if options[:instructions] && options[:instructions_file]
+          abort "Error: --instructions and --instructions-file are mutually exclusive."
+        elsif options[:instructions_file]
+          file_path = File.expand_path(options[:instructions_file])
+          abort "Error: File not found: #{file_path}" unless File.exist?(file_path)
+          File.read(file_path)
+        else
+          options[:instructions]
+        end
+      end
     end
   end
 end

data/lib/schwarm_cli/commands/tasks.rb

@@ -34,7 +34,7 @@ module SchwarmCli
       option :prompt, type: :string, desc: "Task prompt"
       option :repo, type: :string, desc: "Repository ID, owner/repo, or GitHub URL"
       option :status, type: :string, desc: "Initial status (draft/waiting)"
-      option :template, type: :string, desc: "Template ID"
+      option :template, type: :string, desc: "Template ID or name"
       option :depends_on, type: :array, desc: "Dependency task IDs"
       def create
         handle_errors do
@@ -116,14 +116,13 @@ module SchwarmCli
       option :prompt, type: :string, desc: "Task prompt"
       option :repo, type: :string, desc: "Repository ID, owner/repo, or GitHub URL (skips origin auto-detect)"
       option :name, type: :string, desc: "Task name (defaults to the branch name)"
+      option :template, type: :string, desc: "Task template ID or name"
       def handoff
         prompt = options[:prompt]
         abort "Error: --prompt is required." if prompt.nil? || prompt.strip.empty?
 
         handle_errors do
-          result = SchwarmCli::HandsOffTask.new(client: client).call(
-            prompt: prompt, repo_override: resolve_repo(options[:repo]), name_override: options[:name]
-          )
+          result = SchwarmCli::HandsOffTask.new(client: client).call(**handoff_attrs(prompt))
           print_handoff_result(result)
         end
       end
@@ -148,11 +147,18 @@ module SchwarmCli
         end
       end
 
+      def handoff_attrs(prompt)
+        {
+          prompt: prompt, repo_override: resolve_repo(options[:repo]),
+          name_override: options[:name], template_override: options[:template]
+        }
+      end
+
       def create_attrs
         {
           name: options[:name], prompt: options[:prompt],
           github_repository_id: resolve_repo(options[:repo]), status: options[:status],
-          task_template_id: options[:template], dependency_ids: options[:depends_on]
+          task_template_id: resolve_template(options[:template]), dependency_ids: options[:depends_on]
         }.compact
       end
 

data/lib/schwarm_cli/commands/templates.rb

@@ -20,7 +20,8 @@ module SchwarmCli
         handle_errors do
           data = client.templates.find(id)
           output_record(data, fields: {
-                          "ID" => "id", "Name" => "name", "Prompt" => "prompt", "Created" => "created_at"
+                          "ID" => "id", "Name" => "name", "Description" => "description",
+                          "Prompt" => "prompt_prefix", "Created" => "created_at"
                         })
         end
       end
@@ -28,9 +29,13 @@ module SchwarmCli
       desc "create", "Create a task template"
       option :name, type: :string, required: true, desc: "Template name"
       option :prompt, type: :string, required: true, desc: "Template prompt"
+      option :description, type: :string, desc: "Template description"
       def create
         handle_errors do
-          data = client.templates.create(name: options[:name], prompt: options[:prompt])
+          attrs = { name: options[:name], prompt_prefix: options[:prompt] }
+          attrs[:description] = options[:description] if options[:description]
+
+          data = client.templates.create(**attrs)
           output_record(data, fields: { "ID" => "id", "Name" => "name" })
         end
       end
@@ -38,13 +43,10 @@ module SchwarmCli
       desc "update ID", "Update a task template"
       option :name, type: :string, desc: "Template name"
       option :prompt, type: :string, desc: "Template prompt"
+      option :description, type: :string, desc: "Template description"
       def update(id)
         handle_errors do
-          attrs = {}
-          attrs[:name] = options[:name] if options[:name]
-          attrs[:prompt] = options[:prompt] if options[:prompt]
-
-          data = client.templates.update(id, **attrs)
+          data = client.templates.update(id, **update_attrs)
           output_record(data, fields: { "ID" => "id", "Name" => "name" })
         end
       end
@@ -56,6 +58,16 @@ module SchwarmCli
           puts "Template #{id} deleted."
         end
       end
+
+      private
+
+      def update_attrs
+        {}.tap do |attrs|
+          attrs[:name] = options[:name] if options[:name]
+          attrs[:prompt_prefix] = options[:prompt] if options[:prompt]
+          attrs[:description] = options[:description] if options[:description]
+        end
+      end
     end
   end
 end

data/lib/schwarm_cli/hands_off_task.rb

@@ -12,14 +12,18 @@ module SchwarmCli
       @client = client
     end
 
-    def call(prompt:, repo_override:, name_override:)
+    def call(prompt:, repo_override:, name_override:, template_override: nil)
       repo, branch, error = run_preflight(repo_override)
       return error if error
 
+      template_id, template_error = resolve_template_id(template_override)
+      return template_error if template_error
+
       push_result = @git.run("push", "-u", "origin", "HEAD")
       return failure(push_result.stderr.strip) unless push_result.success?
 
-      create_task(repo: repo, branch: branch, prompt: prompt, name_override: name_override)
+      create_task(repo: repo, branch: branch, prompt: prompt, name_override: name_override,
+                  template_id: template_id)
     rescue Faraday::Error => e
       failure(parse_api_error(e))
     end
@@ -97,13 +101,22 @@ module SchwarmCli
       nil
     end
 
-    def create_task(repo:, branch:, prompt:, name_override:)
+    def resolve_template_id(ref)
+      [TemplateResolver.new(client: @client).resolve(ref), nil]
+    rescue TemplateResolver::ResolutionError => e
+      [nil, failure(e.message)]
+    end
+
+    def create_task(repo:, branch:, prompt:, name_override:, template_id:)
       response = @client.tasks.create(
-        name: name_override || branch,
-        branch_name: branch,
-        prompt: prompt,
-        status: "ready",
-        github_repository_id: repo["id"]
+        **{
+          name: name_override || branch,
+          branch_name: branch,
+          prompt: prompt,
+          status: "ready",
+          github_repository_id: repo["id"],
+          task_template_id: template_id
+        }.compact
       )
       data = response["data"]
       Result.new(

data/lib/schwarm_cli/template_resolver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SchwarmCli
+  # Turns a user-provided `--template` reference into a task template ID.
+  #
+  # Accepted inputs:
+  #   - a numeric template ID (looked up directly)
+  #   - an exact template name (resolved via search + exact match)
+  class TemplateResolver
+    class ResolutionError < StandardError; end
+
+    def initialize(client:)
+      @client = client
+    end
+
+    def resolve(ref)
+      return nil if blank?(ref)
+
+      ref = ref.to_s.strip
+      template = ref.match?(/\A\d+\z/) ? find_by_id(ref) : find_by_name(ref)
+      raise ResolutionError, "no schwarm task template matches `#{ref}`." if template.nil?
+
+      template["id"]
+    end
+
+    private
+
+    def blank?(ref)
+      ref.nil? || ref.to_s.strip.empty?
+    end
+
+    def find_by_id(id)
+      @client.templates.find(id)["data"]
+    rescue Faraday::ResourceNotFound
+      nil
+    end
+
+    def find_by_name(name)
+      response = @client.templates.list(query: name)
+      Array(response["data"]).find { |t| t["name"] == name }
+    end
+  end
+end

data/lib/schwarm_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SchwarmCli
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/schwarm_cli.rb

@@ -5,6 +5,7 @@ require_relative "schwarm_cli/config"
 require_relative "schwarm_cli/client"
 require_relative "schwarm_cli/git"
 require_relative "schwarm_cli/repository_resolver"
+require_relative "schwarm_cli/template_resolver"
 require_relative "schwarm_cli/hands_off_task"
 require_relative "schwarm_cli/formatters/json"
 require_relative "schwarm_cli/formatters/table"

data/schwarm-skill.md

@@ -86,6 +86,42 @@ EOF
   will print the conflicting task ID. Archive or reset it first.
 - The repository is auto-detected from `git remote get-url origin`. Use
   `--repo <id>` if you need to override it (e.g. in a fork).
+- Pass `--template <id-or-name>` to apply a task template to the handoff. The
+  value can be a template ID or its exact name.
+
+### 1c. Hand off a WIP branch with follow-up tasks
+
+**When:** You're handing off a WIP branch and want other tasks to run after it
+on the same repo (e.g. add docs, cut a release PR, update a dashboard). The
+handoff task starts immediately; the follow-ups wait until it's archived.
+
+**Steps:**
+1. Hand off the current branch first and note the task ID it prints:
+   ```bash
+   schwarm tasks handoff --prompt "continue per HANDOFF.md"
+   # => Task a1b2c3 created (status: ready).
+   ```
+2. Create follow-up tasks as drafts depending on the handoff task ID:
+   ```bash
+   schwarm tasks create --repo <REPO_ID> --name "Update docs" \
+     --prompt "Update README and CHANGELOG once the branch lands" --depends-on a1b2c3
+   schwarm tasks create --repo <REPO_ID> --name "Announce in #releases" \
+     --prompt "Post the summary to Slack" --depends-on a1b2c3
+   ```
+3. Start each follow-up — it will move to `waiting` until the handoff archives:
+   ```bash
+   schwarm tasks start <FOLLOWUP_ID>
+   ```
+
+**Watch for:**
+- The handoff task is created with `status: ready` and runs immediately. You
+  don't need to start it.
+- Follow-ups run on fresh worktrees off the repo's base branch by default, not
+  off the handoff branch. `--depends-on` keeps them in `waiting` until the
+  handoff task is archived, so by the time they start the handoff's changes are
+  already on the base branch.
+- Pass `--repo <id>` on `tasks create` (handoff auto-detects it from `origin`,
+  but `create` does not).
 
 ### 2. Dispatch a DAG of tasks
 
@@ -192,9 +228,10 @@ must `start` again.
    schwarm templates list
    schwarm templates show <TEMPLATE_ID>
    ```
-3. Create a task from a template:
+3. Create a task from a template. `--template` accepts either the template ID or
+   its exact name:
    ```bash
-   schwarm tasks create --repo <REPO_ID> --name "Apply template" --template <TEMPLATE_ID> --status ready
+   schwarm tasks create --repo <REPO_ID> --name "Apply template" --template <TEMPLATE_ID_OR_NAME> --status ready
    ```
 
 ### 7. Manage recurring tasks

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schwarm-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Vincent Garrigues
@@ -123,6 +123,7 @@ files:
 - lib/schwarm_cli/git.rb
 - lib/schwarm_cli/hands_off_task.rb
 - lib/schwarm_cli/repository_resolver.rb
+- lib/schwarm_cli/template_resolver.rb
 - lib/schwarm_cli/version.rb
 - schwarm-skill.md
 homepage: https://github.com/getdexter/schwarm