agentilda 1.0.3 → 2.0.0

data/lib/agentilda/agents.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "agentilda/agent"
+require "agentilda/frontmatter"
+
+module Agentilda
+  # Loads and indexes the agent definitions.
+  class Agents
+    # Where definitions live, unless told otherwise.
+    DEFAULT_DIR = File.expand_path("../../agents", __dir__)
+
+    # @param dir [String]
+    # @param roster [Array<Agentilda::Agent>, nil] a pre-selected list, used
+    #   by {#only} and {#without} to derive a narrower roster; nil (the
+    #   default) loads every definition in `dir`
+    def initialize(dir: DEFAULT_DIR, roster: nil)
+      @dir = File.expand_path(dir)
+      @all = roster
+    end
+
+    # @return [String]
+    attr_reader :dir
+
+    # @return [Array<Agentilda::Agent>] in name order
+    def all
+      @all ||= Dir.glob(File.join(dir, "*.md")).sort.filter_map { |path| parse(path) }
+    end
+
+    # @param name [String]
+    # @return [Agentilda::Agent, nil]
+    def find(name) = all.find { |a| a.name == name.to_s }
+
+    # A roster holding only the agents named — what `run --agent` hands the
+    # loop, so a restriction typed at the command line restricts assignments
+    # and not merely chaining.
+    #
+    # @param names [Array<String>]
+    # @return [Agentilda::Agents]
+    def only(*names)
+      wanted = names.flatten.map(&:to_s)
+      self.class.new(dir:, roster: all.select { |a| wanted.include?(a.name) })
+    end
+
+    # A roster without the agents named — what `run --skip` hands the loop.
+    # A plan sitting in a skipped agent's state is simply never assigned, the
+    # same way a state no agent handles is stepped around.
+    #
+    # @param names [Array<String>]
+    # @return [Agentilda::Agents]
+    def without(*names)
+      unwanted = names.flatten.map(&:to_s)
+      self.class.new(dir:, roster: all.reject { |a| unwanted.include?(a.name) })
+    end
+
+    # Every agent the query could mean. An exact name wins outright; failing
+    # that the query matches as a prefix, and failing that anywhere in the
+    # name, so `leah` finds leah-researcher and `review` finds
+    # hansolo-reviewer. A directory or a trailing `.md` is stripped first,
+    # because tab completion hands those in.
+    #
+    # @param query [String]
+    # @return [Array<Agentilda::Agent>]
+    def match(query)
+      wanted = File.basename(query.to_s, ".md")
+      exact = all.select { |a| a.name == wanted }
+      return exact unless exact.empty?
+
+      prefixed = all.select { |a| a.name.start_with?(wanted) }
+      return prefixed unless prefixed.empty?
+
+      all.select { |a| a.name.include?(wanted) }
+    end
+
+    # Every agent that will act on a plan in this state, in definition order.
+    # A read-only agent is never offered work by the loop — it has nothing to
+    # advance, so including it would make every round look productive.
+    #
+    # @param status [Agentilda::Status]
+    # @return [Array<Agentilda::Agent>]
+    def for_status(status) = all.select { |a| a.handles?(status) && !a.read_only? }
+
+    # Everyone on a plan in this state: the agents that work it, plus any
+    # agent whose `holds_at` parks the plan here after it finished its half.
+    # Rey resuming a plan at 🎨 still needs luke's messages in the mailbox.
+    #
+    # @param status [Agentilda::Status]
+    # @return [Array<Agentilda::Agent>]
+    def team_for(status) = all.select { |a| !a.read_only? && (a.handles?(status) || a.holds_at == status.key) }
+
+    private
+
+    # @param path [String]
+    # @return [Agentilda::Agent, nil]
+    def parse(path)
+      meta, body = Frontmatter.split(File.read(path, encoding: "UTF-8"))
+      return nil if meta["name"].to_s.empty?
+
+      Agent.new(
+        name:          meta["name"].to_s,
+        description:   meta["description"].to_s,
+        handles:       Array(meta["handles"]).map { |s| s.to_s.to_sym },
+        advances_to:   meta["advances_to"]&.to_s&.then { |s| s.empty? ? nil : s.to_sym },
+        model:         meta["model"],
+        allowed_tools: Array(meta["allowed_tools"]).map(&:to_s),
+        may:           Array(meta["may"]).map { |c| c.to_s.strip.squeeze(" ") },
+        network:       meta["network"] == true,
+        timeout:       meta["timeout"].to_i.then { |s| s.positive? ? s : nil },
+        prompt:        body.strip,
+        path:          path,
+        ledger:        Array(meta["ledger"]).map(&:to_s),
+        rounds:        meta["rounds"].to_i.clamp(1, Agent::MAX_ROUNDS),
+        effort:        meta["effort"]&.to_s,
+        starts_as:     symbol_or_nil(meta["starts_as"]),
+        holds_at:      symbol_or_nil(meta["holds_at"])
+      )
+    end
+
+    # @param value [Object, nil]
+    # @return [Symbol, nil]
+    def symbol_or_nil(value) = value.to_s.empty? ? nil : value.to_s.to_sym
+  end
+end

data/lib/agentilda/board.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # What the screen draws: everything about the run, as values, refreshed
+  # once a second by the dispatcher. The screen paints it and knows nothing
+  # about threads; the dispatcher builds it and knows nothing about cells.
+  #
+  # @!attribute [r] rows
+  #   @return [Array<Agentilda::Board::Row>] one per agent invocation still
+  #     worth showing: running, or finished within the last few seconds
+  Board = Data.define(:started_at,
+    :status,
+    :plans,
+    :up,
+    :down,
+    :rows,
+    :root,
+    :running,
+    :live_up,
+    :live_down,
+    :selected,
+    :dialog,
+    :help,
+    :about,
+    :hidden) do
+    def initialize(selected: nil, dialog: nil, help: false, about: nil, hidden: 0, **rest) = super
+  end
+
+  # @!attribute [r] key
+  #   @return [String] `"001.00/leah-researcher"`, what selection and the
+  #     keyboard address a row by
+  # @!attribute [r] file
+  #   @return [String] the document holding the agent's latest ledger line
+  # @!attribute [r] pr
+  #   @return [Hash, nil] `{number:, url:, rejected:}` once the plan is at
+  #     the review stage
+  # @!attribute [r] state
+  #   @return [Symbol] :running, :done, :failed or :stuck
+  # @!attribute [r] phase
+  #   @return [Symbol, nil] the clock's phase while running
+  # @!attribute [r] frame
+  #   @return [Integer] spinner frame counter
+  # @!attribute [r] history
+  #   @return [Array<String>] what the agent has said, newest first, for
+  #     `run --scroll-height` to show more than the latest line of
+  Board::Row = Data.define(:key,
+    :at,
+    :ordinal,
+    :file,
+    :agent,
+    :role,
+    :round,
+    :rounds,
+    :model,
+    :remaining,
+    :phase,
+    :up,
+    :down,
+    :message,
+    :state,
+    :pr,
+    :frame,
+    :bold,
+    :elapsed,
+    :subagents,
+    :history) do
+    def initialize(pr: nil, phase: nil, remaining: nil, frame: 0, bold: false, message: nil,
+      elapsed: 0, subagents: 0, history: [], **rest)
+      super
+    end
+
+    # @param history [Array<String>] newest first
+    # @param text [String, nil]
+    # @return [Array<String>] +text+ on top, unless it is empty or repeats
+    #   the newest line: an agent restating its activity is not news
+    def self.remember(history, text)
+      text = text.to_s.strip
+      return history if text.empty? || history.first == text
+
+      [text, *history].first(Board::Row::HISTORY)
+    end
+
+    # @return [Boolean]
+    def running? = state == :running
+  end
+
+  # Statuses a row keeps, whatever the screen shows of them. A cap, so a
+  # long-running agent's chatter cannot grow without bound. Outside the
+  # `Data.define` block, whose constants would land on Agentilda instead.
+  Board::Row::HISTORY = 50
+end

data/lib/agentilda/brief.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "tty/command"
+
 module Agentilda
   # A new plan's opening brief: four questions, and a best-effort first pass
   # at answering them from what the project already has on disk.
@@ -55,6 +57,49 @@ module Agentilda
     ALLOWED_TOOLS = %w[Read Grep Glob Edit].freeze
     DENIED_TOOLS = %w[WebFetch WebSearch Bash].freeze
 
+    # The `stdout:` and `stderr:` sections of a {TTY::Command::ExitError}
+    # message. stdout runs until stderr starts; stderr runs to the end, because
+    # what `claude` prints there is not guaranteed to be one line.
+    STDOUT_SECTION = /^[ \t]*stdout:[ \t]*(.*?)(?=\n[ \t]*stderr:|\z)/m
+    STDERR_SECTION = /^[ \t]*stderr:[ \t]*(.*)\z/m
+
+    # How much of what `claude` said survives into a one-line report.
+    REASON_LIMIT = 300
+
+    # A one-line account of a failed `claude` run, built from the error rather
+    # than its first line: that first line is the escaped prompt, several
+    # thousand characters of it, and reporting it says an invocation failed,
+    # at length, and never why.
+    #
+    # Both streams are kept because they carry different halves. `claude`
+    # reports its own failures on stdout; the line naming the *cause* of a 401
+    # (`ANTHROPIC_API_KEY ... takes precedence over your claude.ai login`) is
+    # on stderr. {Executor} used to own this; it now reads a child process
+    # directly and has no exit error to parse, so the briefer keeps it.
+    #
+    # @param error [TTY::Command::ExitError]
+    # @return [String]
+    def self.failure_reason(error)
+      status = error.message[/^[ \t]*exit status:[ \t]*(\S+)/, 1]
+      outcome = status ? "exited #{status}" : "failed"
+      said = [STDOUT_SECTION, STDERR_SECTION]
+             .filter_map { |section| tail(error.message[section, 1]) }
+             .join(" | ")
+
+      said.empty? ? "#{outcome} and said nothing" : "#{outcome}: #{said}"
+    end
+
+    # @param text [String, nil]
+    # @return [String, nil] the last few meaningful lines, on one line
+    def self.tail(text)
+      lines = text.to_s.split("\n").map(&:strip).reject { |line| line.empty? || line == "Nothing written" }
+      return nil if lines.empty?
+
+      joined = lines.last(3).join(" ")
+      joined.length > REASON_LIMIT ? "#{joined[0, REASON_LIMIT - 1]}..." : joined
+    end
+    private_class_method :tail
+
     # @param path [String] the new plan folder, absolute
     # @param title [String] the feature's proper name, e.g. "Tax Rule DSL"
     # @param root [String] repository root, for project context and `--add-dir`
@@ -121,7 +166,7 @@ module Agentilda
       rescue TTY::Command::TimeoutExceeded
         return [false, "timed out after #{@timeout}s"]
       rescue TTY::Command::ExitError => e
-        return [false, "claude #{Executor.failure_reason(e)}"]
+        return [false, "claude #{self.class.failure_reason(e)}"]
       end
 
       [true, "drafted"]
@@ -132,10 +177,10 @@ module Agentilda
     # @return [Array<String>]
     def invocation
       ["claude",
-        "-p", prompt, "--add-dir", root,
-        "--model", BRIEF_MODEL,
-        "--allowedTools", ALLOWED_TOOLS.join(","),
-        "--disallowedTools", DENIED_TOOLS.join(",")]
+       "-p", prompt, "--add-dir", root,
+       "--model", BRIEF_MODEL,
+       "--allowedTools", ALLOWED_TOOLS.join(","),
+       "--disallowedTools", DENIED_TOOLS.join(",")]
     end
 
     private
@@ -146,6 +191,10 @@ module Agentilda
         #{author_statement}A new plan folder was just created for a feature that does not exist
         yet: "#{title}".
 
+        You have 50 seconds. Explore the codebase for the first thirty and
+        write for the last twenty; the process is killed at sixty and an
+        unwritten draft is lost.
+
         #{spec_path} holds a title and four empty headings:
 
         #{HEADINGS.map { |h| "  * #{h}" }.join("\n")}

data/lib/agentilda/child.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # One `claude` process the harness started and therefore owns.
+  #
+  # `TTY::Command` never exposes the pid it spawned, so the executor used to
+  # find its child by scraping `ps` for a fresh `claude` under this process
+  # and could never safely signal it. Kill (`k`) and the sixty-second
+  # backstop after STOP both need a pid that is certainly ours, so the
+  # process is spawned here and the pid kept.
+  #
+  # stderr is folded into the same pipe as stdout: `claude` prints the cause
+  # of a failure there, and the transcript keeps non-JSON lines for exactly
+  # that reason.
+  class Child
+    # @param argv [Array<String>]
+    # @param chdir [String, nil]
+    # @return [Agentilda::Child]
+    def self.spawn(argv, chdir: nil)
+      reader, writer = IO.pipe
+      options = { out: writer, err: writer, in: File::NULL }
+      options[:chdir] = chdir if chdir
+      pid = Process.spawn(*argv, **options)
+      writer.close
+      new(pid:, reader:)
+    end
+
+    # @param pid [Integer]
+    # @param reader [IO]
+    def initialize(pid:, reader:)
+      @pid = pid
+      @reader = reader
+      @status = nil
+    end
+
+    # @return [Integer]
+    attr_reader :pid
+
+    # Read until the process closes its end. Runs on the caller's thread;
+    # the executor reads on the same thread it always did.
+    #
+    # @yieldparam text [String] whatever arrived, possibly a partial line
+    # @return [void]
+    def each_chunk
+      loop { yield @reader.readpartial(65_536) }
+    rescue IOError
+      @reader.close unless @reader.closed?
+    end
+
+    # @return [Process::Status]
+    def wait
+      @status ||= begin
+        _, status = Process.wait2(pid)
+        status
+      end
+    rescue Errno::ECHILD
+      @status
+    end
+
+    # @param signal [String]
+    # @return [void]
+    def kill(signal = "KILL")
+      Process.kill(signal, pid)
+    rescue Errno::ESRCH
+      # Already gone, which is what was wanted.
+    end
+
+    # @return [Boolean]
+    def alive?
+      return false if @status
+
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+  end
+end

data/lib/agentilda/cli/agents/subcommands/describe.rb

@@ -10,11 +10,15 @@ module Agentilda
 
         desc "Open one specialist's definition in a Markdown viewer"
 
-        argument :name, required: false,
-          desc: "Which specialist, full name or a fragment, e.g. leah (default: every one)"
+        argument :name,
+          required: false,
+          desc:     "Which specialist, full name or a fragment, e.g. leah (default: every one)"
 
-        option :mdfried, type: :boolean, default: false, aliases: ["-m"],
-          desc: "Render in the terminal through mdfried instead of the system viewer"
+        option :mdfried,
+          type:    :boolean,
+          default: false,
+          aliases: ["-m"],
+          desc:    "Render in the terminal through mdfried instead of the system viewer"
 
         example [
           "leah               # leah-researcher, in the system Markdown viewer",

data/lib/agentilda/cli/base.rb

@@ -1,17 +1,27 @@
 # frozen_string_literal: true
 
+require "dry/cli"
+
 module Agentilda
   module CLI
     # Shared flags and the plumbing every command needs.
     class Base < Dry::CLI::Command
       include UI
 
+      # Values of AGENTILDA_AUTOCOMMIT that turn it on.
+      AUTOCOMMIT = %w[true yes 1].freeze
+
       def self.inherited(klass)
         super
-        klass.option :dir, default: Agentilda::PLANS_DIR, aliases: ["-D"],
-          desc: "The .plans directory"
-        klass.option :quiet, type: :boolean, default: false, aliases: ["-q"],
-          desc: "Suppress progress output on STDERR"
+        klass.option :dir,
+          default: Agentilda::PLANS_DIR,
+          aliases: ["-D"],
+          desc:    "The .plans directory"
+        klass.option :quiet,
+          type:    :boolean,
+          default: false,
+          aliases: ["-q"],
+          desc:    "Suppress progress output on STDERR"
       end
 
       private
@@ -22,7 +32,8 @@ module Agentilda
         tree = Tree.new(dir: options.fetch(:dir, Agentilda::PLANS_DIR))
         unless tree.exist?
           refuse("No #{Agentilda::PLANS_DIR} directory at\n#{tree.dir}\n\n" \
-                 "Run this from the project root, or pass -D.", 66)
+                 "Run this from the project root, or pass -D.",
+            66)
         end
         tree
       end
@@ -47,9 +58,14 @@ module Agentilda
         quiet
       end
 
+      # `--commit`, or AGENTILDA_AUTOCOMMIT=true, which is `--commit` on every
+      # command for someone who never wants the dry run.
+      #
       # @param options [Hash]
       # @return [Boolean]
-      def commit?(options) = options.fetch(:commit, false)
+      def commit?(options)
+        options.fetch(:commit, false) || AUTOCOMMIT.include?(ENV.fetch("AGENTILDA_AUTOCOMMIT", "").strip.downcase)
+      end
 
       # `claude` prefers a credential in the environment to a claude.ai login,
       # so a project `.env` that direnv loads on `cd` can redirect every agent

data/lib/agentilda/cli/create/create.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 module Agentilda
   module CLI
     # `agentilda create <words…>` — backs /spec-create.
@@ -23,7 +25,7 @@ module Agentilda
           "Create a retroactive plan in the gap after this plan, e.g. 002"
       option :status,
         aliases: ["-s"],
-        desc: "Open in a state other than the default"
+        desc:    "Open in a state other than the default"
       option :prs,
         aliases: ["--pr"],
         desc:
@@ -46,7 +48,7 @@ module Agentilda
 
       # noinspection RubyMismatchedArgumentType
       example [
-        "tax rule dsl                        # 003.00-⚪️--tax-rule-dsl, spec.md scaffolded and drafted",
+        "tax rule dsl                        # 003.00-⚪️ → tax-rule-dsl, spec.md scaffolded and drafted",
         "tax rule dsl --no-draft --no-open   # scaffold only, nothing shelled out, nothing opened",
         "--after 002 schedule k1             # 002.01-🕰️-schedule-k1 (documented after the fact)",
         "--after 018 --prs 12,15 verify      # …and write spec.md from what those PRs did",
@@ -97,14 +99,14 @@ module Agentilda
         unless words.empty?
           refuse(
             "--from names the topic by its frontmatter title;\n" \
-              "drop the words, or drop --from",
+            "drop the words, or drop --from",
             64
           )
         end
         if options[:prs]
           refuse(
             "--prs reconstructs spec.md from the pull requests, so a seed file\n" \
-              "would be ignored; use one or the other",
+            "would be ignored; use one or the other",
             64
           )
         end
@@ -116,7 +118,7 @@ module Agentilda
         if title.to_s.strip.empty?
           refuse(
             "The seed file needs a frontmatter title, e.g.\n" \
-              "---\ntitle: Tax Rule DSL\n---",
+            "---\ntitle: Tax Rule DSL\n---",
             65
           )
         end
@@ -152,7 +154,7 @@ module Agentilda
         unless options[:after]
           refuse(
             "--prs documents work that already shipped;\n" \
-              "name the plan it landed after with --after, e.g. --after 018",
+            "name the plan it landed after with --after, e.g. --after 018",
             64
           )
         end
@@ -184,8 +186,8 @@ module Agentilda
         feature = Feature.parse(path)
         success(
           "Created #{File.basename(path)}\n\n" \
-            "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
-            "#{next_step(path, feature, from_prs:)}"
+          "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
+          "#{next_step(path, feature, from_prs:)}"
         )
       end
 
@@ -201,10 +203,14 @@ module Agentilda
           return path
         root = options[:root] || File.dirname(path, 2)
 
-        ok, note =
-          UI.spinning("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}") do
-            Executor.new(root:).call(agent, Subject.new(Feature.parse(path)))
-          end
+        feature = Feature.parse(path)
+        ok, note = on_agent_row("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}",
+          agent: agent.name,
+          plan:  feature.ordinal.to_s,
+          root:) do |line|
+          handle = line.handle if line.is_a?(Dashboard::Tracker)
+          Executor.new(root:).call(agent, Subject.new(feature), handle:, &line)
+        end
         warn_about(note) unless ok
 
         settle(path)
@@ -234,7 +240,7 @@ module Agentilda
           # half-agent reads as one of them on the terminal.
           label =
             "#{UI.paint(Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
-          ok, note = UI.spinning(label) { brief.attempt! }
+          ok, note = on_agent_row(label, agent: Brief::AGENT_NAME, plan: feature.ordinal.to_s, root:) { brief.attempt! }
           warn_about_draft(note) unless ok
         end
 
@@ -242,6 +248,27 @@ module Agentilda
         path
       end
 
+      # One agent writing spec.md, drawn as a row on the ratatui dashboard on
+      # a terminal and as a spinner line anywhere else.
+      #
+      # @param label [String] the spinner line's text
+      # @param agent [String]
+      # @param plan [String]
+      # @param root [String]
+      # @yieldparam line [Agentilda::UI::Line]
+      # @return [Object] the block's value
+      def on_agent_row(label, agent:, plan:, root:, &block)
+        Control.on_interrupt do
+          UI.concurrently([plan],
+            label,
+            jobs:   1,
+            label:  ->(_) { label },
+            fields: ->(_) { { plan:, agent: } },
+            file:   ->(_) { "spec.md" },
+            root:) { |_, line| block.call(line) }.first
+        end
+      end
+
       # @param spec_path [String]
       # @return [void]
       def open_spec(spec_path)
@@ -263,9 +290,9 @@ module Agentilda
         tree = Tree.new(dir: File.dirname(path))
         change =
           Agentilda::Resync::Dirs
-            .new(tree:)
-            .call(commit: true)
-            .find { |c| c.source == path }
+          .new(tree:)
+          .call(commit: true)
+          .find { |c| c.source == path }
         change ? change.target : path
       end
 
@@ -274,7 +301,7 @@ module Agentilda
       def warn_about(note)
         error(
           "The folder was created, but spec.md was not written:\n#{note}\n\n" \
-            "The pull requests are recorded. Run `agentilda run --commit` to retry."
+          "The pull requests are recorded. Run `agentilda run --commit` to retry."
         )
       end
 
@@ -283,7 +310,7 @@ module Agentilda
       def warn_about_draft(note)
         error(
           "spec.md was scaffolded, but the drafting attempt did not finish:\n#{note}\n\n" \
-            "The four headings are there, empty. Fill them in by hand, or hand off to leah-researcher."
+          "The four headings are there, empty. Fill them in by hand, or hand off to leah-researcher."
         )
       end
 
@@ -293,7 +320,7 @@ module Agentilda
       def next_step(path, feature, from_prs:)
         spec = File.join(File.basename(path), "spec.md")
         unless feature.status.key == :new &&
-            File.file?(File.join(path, "spec.md"))
+               File.file?(File.join(path, "spec.md"))
           return "Next: write #{spec}"
         end
         if from_prs

data/lib/agentilda/cli/docs/docs.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 module Agentilda
   module CLI
     # `agentilda docs` — regenerate the conventions document.
     class Docs < Base
       desc "Generate the conventions document from the state machine itself"
 
-      option :output, aliases: ["-o"], desc: "Write here instead of STDOUT",
-        default: "#{ENV["HOME"]}/.agents/context/workflow.md"
+      option :output,
+        aliases: ["-o"],
+        desc:    "Write here instead of STDOUT",
+        default: "#{ENV.fetch("HOME", nil)}/.agents/context/workflow.md"
 
       example ["", "-o ~/.agents/context/workflow.md"]
 

data/lib/agentilda/cli/index/index.rb

@@ -6,10 +6,12 @@ module Agentilda
     class Index < Base
       desc "Create or update .plans/INDEX.md — a global index of every plan."
 
-      option :output, aliases: ["-o"],
-        desc: "Write somewhere other than <plans>/INDEX.md; - for STDOUT"
-      option :project, aliases: ["-p"],
-        desc: "Heading for the page, default: the repository's directory name"
+      option :output,
+        aliases: ["-o"],
+        desc:    "Write somewhere other than <plans>/INDEX.md; - for STDOUT"
+      option :project,
+        aliases: ["-p"],
+        desc:    "Heading for the page, default: the repository's directory name"
 
       example [
         "                     # write .plans/INDEX.md",

data/lib/agentilda/cli/linear/linear.rb

@@ -11,8 +11,9 @@ module Agentilda
       class Team < Base
         def self.inherited(klass)
           super
-          klass.argument :team, required: true,
-            desc: "The Linear team key that prefixes its issues, e.g. TAX"
+          klass.argument :team,
+            required: true,
+            desc:     "The Linear team key that prefixes its issues, e.g. TAX"
         end
 
         private