schwarm-cli 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fda5a7c0a0a68a6e07573a5509cadb8ea7ff600f94a3feabf065317c332a9b40
-  data.tar.gz: bfd4c31bca63d5862c9df68514c8ab3bdeefb0a1ebbd944c316aeed4522a626d
+  metadata.gz: cb4e9030ccc6a70a2d35c94e5c2db414bae4b56550ae21128b2e3f612b56b6cf
+  data.tar.gz: 4c4bfd79d9b120f01764b4b482200757a5a3f4d1a1e8dba5c344486befebf48d
 SHA512:
-  metadata.gz: cf2aac68753184cd3ef7fcd28ff24eb75010b84237f2b661e76a00e1582ead6ad07b0789941f9d3c518bd40eadc34bea14d463bc83e7d69dfb62f68f165920a3
-  data.tar.gz: 9bdf3cbb26adecc1f40e90d681e9cb722bd2ae477cd7faa1ac258f3bf690cc77aa1374cb2744a8fe9bb6583b7b328b242f81e80f19ab79afa2dedad23c5d6b55
+  metadata.gz: 326c318ea026081fb23c05cd552e5a78204af6f35dc96e2ff7d5da6c838d0b48646534ab914cc1bc6afa250844e6a6d2ab3895cf2da37fee44f671308c10fbc4
+  data.tar.gz: c15ba6b8d00b97e44e8b0642ab88753423043cbb4eafad9593fc8fdba0a22bc3a67168576fe76f5165386316bfe14e505411471d08dca4eb6e474ddea25a9d97

data/lib/schwarm_cli/commands/base.rb

@@ -32,6 +32,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)

data/lib/schwarm_cli/commands/tasks.rb

@@ -32,10 +32,9 @@ module SchwarmCli
       desc "create", "Create a new task"
       option :name, type: :string, required: true, desc: "Task name"
       option :prompt, type: :string, desc: "Task prompt"
-      option :prompt_file, type: :string, desc: "Read prompt from file"
       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
@@ -47,7 +46,6 @@ module SchwarmCli
       desc "update ID", "Update a task"
       option :name, type: :string, desc: "Task name"
       option :prompt, type: :string, desc: "Task prompt"
-      option :prompt_file, type: :string, desc: "Read prompt from file"
       option :repo, type: :string, desc: "Repository ID, owner/repo, or GitHub URL"
       option :depends_on, type: :array, desc: "Dependency task IDs"
       def update(id)
@@ -116,17 +114,15 @@ module SchwarmCli
 
       desc "handoff", "Hand off the current local branch to schwarm as a ready task"
       option :prompt, type: :string, desc: "Task prompt"
-      option :prompt_file, type: :string, desc: "Read prompt from file"
       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 = read_prompt
-        abort "Error: --prompt or --prompt-file is required." if prompt.nil? || prompt.strip.empty?
+        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
@@ -151,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: read_prompt,
+          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
 
@@ -164,17 +167,7 @@ module SchwarmCli
           name: options[:name], github_repository_id: resolve_repo(options[:repo]),
           dependency_ids: options[:depends_on]
         }.compact.tap do |attrs|
-          attrs[:prompt] = read_prompt if options[:prompt] || options[:prompt_file]
-        end
-      end
-
-      def read_prompt
-        if options[:prompt_file]
-          file_path = File.expand_path(options[:prompt_file])
-          abort "Error: File not found: #{file_path}" unless File.exist?(file_path)
-          File.read(file_path)
-        else
-          options[:prompt]
+          attrs[:prompt] = options[:prompt] if options[:prompt]
         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.4"
+  VERSION = "0.1.6"
 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

@@ -32,7 +32,14 @@ The `schwarm` CLI is installed and configured (`schwarm configure`).
    ```bash
    schwarm tasks create --repo <REPO_ID> --name "Fix login bug" --prompt "The login form crashes when email is empty. Fix the validation in app/models/user.rb" --status ready
    ```
-   Use `--prompt-file ./prompt.md` for long prompts.
+   For a multi-line prompt, pipe via HEREDOC:
+   ```bash
+   schwarm tasks create --repo <REPO_ID> --name "Fix login bug" --status ready --prompt "$(cat <<'EOF'
+   The login form crashes when empty. Fix validation in app/models/user.rb
+   and add a regression test.
+   EOF
+   )"
+   ```
 3. Check the created task:
    ```bash
    schwarm tasks show <TASK_ID>
@@ -53,10 +60,24 @@ continues committing to it.
    ```bash
    schwarm tasks handoff --prompt "continue the validation logic, add tests"
    ```
-   Use `--prompt-file ./handoff.md` for long prompts.
 3. Take note of the task ID printed on success; you can monitor it like any
    other task.
 
+**Keep the prompt short.** The prompt is a pointer, not a spec. Before handing
+off, commit any detailed instructions, design notes, or TODOs into the repo
+(e.g. a `HANDOFF.md`, `AGENTS.md`, or inline comments) so the next agent reads
+them from the working tree. Then the `--prompt` just needs to say what to do
+next and where to look, e.g. `"continue per HANDOFF.md"`.
+
+For a multi-line prompt, use a HEREDOC rather than a file flag:
+```bash
+schwarm tasks handoff --prompt "$(cat <<'EOF'
+Continue the validation work. Start from the TODOs in app/models/user.rb
+and follow the plan in HANDOFF.md.
+EOF
+)"
+```
+
 **Watch for:**
 - The command refuses to hand off the base branch (`main`). Create a feature
   branch first.
@@ -65,6 +86,42 @@ continues committing to it.
   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
 
@@ -171,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
@@ -223,7 +281,9 @@ for tasks in a repository.
 - Check task status before taking actions (e.g., only `retry` works on `error`
   tasks, only `start` works on `draft` tasks).
 - When building a DAG, create all tasks as drafts first, then start them all.
-- For long prompts, write them to a file and use `--prompt-file`.
+- Keep `--prompt` short — commit long-form instructions (plans, TODOs,
+  `HANDOFF.md`) into the repo and point the prompt at them. For multi-line
+  prompts, pipe via HEREDOC: `--prompt "$(cat <<'EOF' ... EOF)"`.
 - Run `schwarm <command> help` for full flag documentation on any command.
 - `schwarm tasks list` excludes archived tasks by default. Use `--all` to
   include them or `--status archived` to see only archived.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schwarm-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 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