openlanes 3.0.0

data/lib/openlanes/adapters.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # The coding agents a plan can be handed to: `claude`, `codex` and `pi`.
+  #
+  # The harness decides who works which plan and checks what they did; an
+  # adapter only knows how to start one particular CLI and how to read what
+  # it prints. That is the whole seam, and it is what lets an agent
+  # definition say `adapter: codex` without the run loop noticing.
+  module Adapters
+    # Reasoning effort, in the vocabulary agent frontmatter and spec.md use.
+    # Each adapter translates it into its own CLI's words.
+    EFFORTS = %w[low medium high xhigh max].freeze
+
+    # Percent of the context window at which every agent compacts itself
+    # (W28), instead of the CLI's default near the limit: a long session's
+    # quality drops well before its window is full. Each adapter maps it to
+    # its own CLI's setting in {Base#environment}.
+    AUTOCOMPACT = 40
+
+    # Everything an adapter needs to start one agent, and nothing about why.
+    #
+    # @!attribute [r] prompt
+    #   @return [String]
+    # @!attribute [r] root
+    #   @return [String] the checkout the agent works in
+    # @!attribute [r] model
+    #   @return [String, nil] nil lets the CLI choose
+    # @!attribute [r] effort
+    #   @return [String, nil] one of {EFFORTS}
+    # @!attribute [r] allowed_tools
+    #   @return [Array<String>]
+    # @!attribute [r] denied_tools
+    #   @return [Array<String>] tool names, plus `Bash(<command>:*)` specifiers
+    # @!attribute [r] denied_commands
+    #   @return [Array<String>] the bare commands behind those specifiers
+    # @!attribute [r] network
+    #   @return [Boolean] whether the agent may reach the internet
+    # @!attribute [r] lean
+    #   @return [Boolean] start without the operator's personal plugins,
+    #     skills, hooks and MCP servers
+    # @!attribute [r] resume
+    #   @return [String, nil] a session to carry on rather than start afresh
+    # @!attribute [r] slash_commands
+    #   @return [Boolean] keep the CLI's slash commands even when lean, which
+    #     only the `/compact` sent into a resumed session needs
+    Invocation = Data.define(:prompt,
+      :root,
+      :model,
+      :effort,
+      :allowed_tools,
+      :denied_tools,
+      :denied_commands,
+      :network,
+      :lean,
+      :resume,
+      :slash_commands) do
+      def initialize(allowed_tools: [], denied_tools: [], denied_commands: [], network: false, lean: true,
+        model: nil, effort: nil, resume: nil, slash_commands: false, **rest)
+        super
+      end
+    end
+
+    # The adapter every agent gets unless its definition names another.
+    DEFAULT = "claude"
+
+    module_function
+
+    # @return [Hash{String => Class}]
+    def registry = { "claude" => Claude, "codex" => Codex, "pi" => Pi }
+
+    # @return [Array<String>]
+    def names = registry.keys
+
+    # @param name [String, Symbol, nil]
+    # @return [OpenLanes::Adapters::Base]
+    # @raise [OpenLanes::Error] for a name nothing answers to
+    def for(name)
+      key = (name || DEFAULT).to_s
+      klass = registry[key] or raise OpenLanes::Error, "unknown adapter #{key.inspect}; known: #{names.join(", ")}"
+      klass.new
+    end
+
+    # @param name [String, Symbol, nil]
+    # @return [Boolean]
+    def known?(name) = registry.key?((name || DEFAULT).to_s)
+
+    # @param level [String, Symbol, nil]
+    # @return [Boolean]
+    def effort?(level) = EFFORTS.include?(level.to_s)
+  end
+end

data/lib/openlanes/agents/agent.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Agents
+    # One specialist, loaded from `~/.agents/agents/<name>.md`.
+    #
+    # The definition files are the single source of truth for who does what: the
+    # frontmatter says which plan states this agent handles and what it may write,
+    # and the body is the prompt. Nothing about a specialty is duplicated in Ruby.
+    #
+    # @!attribute [r] name
+    #   @return [String]
+    # @!attribute [r] description
+    #   @return [String]
+    # @!attribute [r] handles
+    #   @return [Array<Symbol>] plan states this agent is offered work from
+    # @!attribute [r] advances_to
+    #   @return [Symbol, nil] the state it is expected to reach; nil = read-only
+    # @!attribute [r] model
+    #   @return [String, nil]
+    # @!attribute [r] allowed_tools
+    #   @return [Array<String>]
+    # @!attribute [r] may
+    #   @return [Array<String>] commands lifted from {Executor::FORBIDDEN_COMMANDS}
+    #     for this agent alone. Nothing in {Executor::UNGRANTABLE} can be lifted.
+    # @!attribute [r] timeout
+    #   @return [Integer, nil] seconds before this agent is abandoned; nil
+    #     defers to the executor's run-wide default
+    # @!attribute [r] ledger
+    #   @return [Array<String>] the documents this agent signs, in the order
+    #     it reaches them; the last entry it wrote is where it stands
+    # @!attribute [r] rounds
+    #   @return [Integer] how many times it may be invoked on one plan in one
+    #     state before the plan parks; a Completed never earns another
+    # @!attribute [r] effort
+    #   @return [String, nil] passed to `claude --effort`
+    # @!attribute [r] starts_as
+    #   @return [Symbol, nil] the state the harness renames the plan into the
+    #     moment this agent is dispatched, where the topology permits it
+    # @!attribute [r] holds_at
+    #   @return [Symbol, nil] the state the plan takes when this agent completes
+    #     while its partner on the same plan is still running
+    # @!attribute [r] adapter
+    #   @return [String] which coding agent runs it: `claude`, `codex` or `pi`
+    # @!attribute [r] phase
+    #   @return [String, nil] the word a spec's `phases:` map uses to reach it
+    # @!attribute [r] lanes
+    #   @return [Array<Symbol>] the lanes it works in; empty means every lane
+    # @!attribute [r] needs
+    #   @return [Array<String>] plan files that must hold at least one work-unit
+    #     heading before it is dispatched
+    # @!attribute [r] toggle
+    #   @return [String, nil] a spec.md frontmatter key that switches it off
+    #     when false and on when true
+    Agent = Data.define(:name,
+      :description,
+      :handles,
+      :advances_to,
+      :model,
+      :allowed_tools,
+      :may,
+      :network,
+      :timeout,
+      :prompt,
+      :path,
+      :ledger,
+      :rounds,
+      :effort,
+      :starts_as,
+      :holds_at,
+      :adapter,
+      :phase,
+      :lanes,
+      :needs,
+      :toggle) do
+      def initialize(ledger: [], rounds: 1, effort: nil, starts_as: nil, holds_at: nil, adapter: Adapters::DEFAULT,
+        phase: nil, lanes: [], needs: [], toggle: nil, **rest)
+        super
+      end
+
+      # @return [Boolean] whether this agent changes anything on disk
+      def read_only? = advances_to.nil?
+
+      # @param status [OpenLanes::Plans::Status]
+      # @return [Boolean]
+      def handles?(status) = handles.include?(status.key)
+
+      # @param lane [Symbol]
+      # @return [Boolean]
+      def serves?(lane) = lanes.empty? || lanes.include?(lane.to_sym)
+
+      # The word after the hyphen: `researcher`, `backend`. What the screen's
+      # agent column shows, the name being too long for it.
+      #
+      # @return [String]
+      def role = name.split("-", 2).last.to_s
+    end
+
+    # More rounds than this costs tokens and buys nothing: an agent that has
+    # not finished in five tries is not going to on the sixth.
+    Agent::MAX_ROUNDS = 5
+  end
+end

data/lib/openlanes/agents/profile.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Agents
+    # Which coding agent runs an agent on a particular plan, on which model,
+    # thinking how hard: the agent's own frontmatter, overridden by what the
+    # plan's author asked for, overridden by what the operator typed.
+    #
+    # Precedence, highest first:
+    #
+    #   1. `run --model`                       (model only)
+    #   2. spec.md `phases.<phase>`            (adapter, model, effort)
+    #   3. spec.md `depth`                     (effort only)
+    #   4. the agent's frontmatter
+    #
+    # The adapter has the last word on the model, because it is the one that
+    # knows the ceiling: a Claude agent asked for Fable runs on Opus.
+    #
+    # @!attribute [r] adapter
+    #   @return [OpenLanes::Adapters::Base]
+    # @!attribute [r] model
+    #   @return [String, nil]
+    # @!attribute [r] effort
+    #   @return [String, nil]
+    Profile = Data.define(:adapter, :model, :effort) do
+      # @return [String] e.g. `claude:opus/high`
+      def to_s = "#{adapter.name}:#{model || "default"}#{"/#{effort}" if effort}"
+
+      # What a narrow column shows: the model, prefixed by the adapter only
+      # when it is not the default one.
+      #
+      # @return [String] e.g. `opus`, `codex:gpt-5-codex`
+      def label
+        name = model || "default"
+        adapter.name == Adapters::DEFAULT ? name : "#{adapter.name}:#{name}"
+      end
+    end
+
+    class Profile
+      # @param agent [OpenLanes::Agents::Agent]
+      # @param spec [OpenLanes::Plans::Spec, nil]
+      # @param model [String, nil] what `run --model` typed
+      # @return [OpenLanes::Agents::Profile]
+      def self.resolve(agent, spec: nil, model: nil)
+        override = spec ? spec.override_for(agent.phase) : {}
+        adapter = Adapters.for(override["adapter"] || agent.adapter)
+        # A model named for one CLI means nothing to another, so switching
+        # adapters without naming a model drops the agent's own.
+        own_model = override.key?("adapter") && override["adapter"] != agent.adapter ? nil : agent.model
+        depth_effort = spec&.depth && Plans::Spec::EFFORT_FOR_DEPTH[spec.depth]
+        new(adapter:,
+          model:   adapter.model(model || override["model"] || own_model),
+          effort:  override["effort"] || depth_effort || agent.effort)
+      end
+    end
+  end
+end

data/lib/openlanes/agents/registry.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Agents
+    # Loads and indexes the agent definitions.
+    class Registry
+      # Where definitions live, unless told otherwise.
+      DEFAULT_DIR = File.expand_path("../../../agents", __dir__)
+
+      # @param dir [String]
+      # @param roster [Array<OpenLanes::Agents::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<OpenLanes::Agents::Agent>] in name order
+      def all
+        @all ||= Dir.glob(File.join(dir, "*.md")).sort.filter_map { |path| parse(path) }
+      end
+
+      # @param name [String]
+      # @return [OpenLanes::Agents::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 [OpenLanes::Agents::Registry]
+      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 [OpenLanes::Agents::Registry]
+      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<OpenLanes::Agents::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 [OpenLanes::Plans::Status]
+      # @return [Array<OpenLanes::Agents::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 [OpenLanes::Plans::Status]
+      # @return [Array<OpenLanes::Agents::Agent>]
+      def team_for(status) = all.select { |a| !a.read_only? && (a.handles?(status) || a.holds_at == status.key) }
+
+      private
+
+      # @param path [String]
+      # @return [OpenLanes::Agents::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:        effort(meta["effort"], path),
+          starts_as:     symbol_or_nil(meta["starts_as"]),
+          holds_at:      symbol_or_nil(meta["holds_at"]),
+          adapter:       adapter(meta["adapter"], path),
+          phase:         meta["phase"]&.to_s,
+          lanes:         Array(meta["lanes"]).map { |l| l.to_s.to_sym },
+          needs:         Array(meta["needs"]).map(&:to_s),
+          toggle:        meta["toggle"]&.to_s
+        )
+      end
+
+      # A definition is checked in with the code, so a bad value in one is a
+      # bug to stop on, not a preference to work around.
+      #
+      # @param value [Object, nil]
+      # @param path [String]
+      # @return [String, nil]
+      # @raise [OpenLanes::Error]
+      def effort(value, path)
+        return nil if value.nil?
+        return value.to_s if Adapters.effort?(value)
+
+        raise OpenLanes::Error, "#{File.basename(path)}: effort #{value.inspect} is not one of #{Adapters::EFFORTS.join(", ")}"
+      end
+
+      # @param value [Object, nil]
+      # @param path [String]
+      # @return [String]
+      # @raise [OpenLanes::Error]
+      def adapter(value, path)
+        return Adapters::DEFAULT if value.nil?
+        return value.to_s if Adapters.known?(value)
+
+        raise OpenLanes::Error, "#{File.basename(path)}: adapter #{value.inspect} is not one of #{Adapters.names.join(", ")}"
+      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
+end

data/lib/openlanes/agents/roster.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Agents
+    # `openlanes agents` — who the specialists are and what each is offered
+    # work from. Reading one in full is {Viewer}'s job: the definition file is
+    # already the whole truth, so `agents describe` opens it rather than
+    # restating it.
+    #
+    # {#list} returns a string and prints nothing, the same bargain {Reporter}
+    # makes, so the caller decides where the text goes and the table stays
+    # pipeable.
+    #
+    # Everything here is read from the definition files. Nothing about a
+    # specialty is restated in Ruby, because a second copy of "who does what" is
+    # a copy that drifts from the frontmatter the loop actually routes on.
+    class Roster
+      # Columns, so the header and the rows cannot drift apart.
+      HEADINGS = ["Agent", "Handles", "Advances to", "Runs on", "Lanes"].freeze
+
+      # What an agent with no `advances_to` is, in the one word that explains why
+      # `run` never offers it work.
+      READ_ONLY = "read-only"
+
+      # What an agent that handles only {StateMachine::SETTLED} states advances
+      # to. `run` never starts it; a command does, and `resync` then names the
+      # folder by what its files justify.
+      BY_CONTENTS = "by contents"
+
+      # @param agents [OpenLanes::Agents::Registry]
+      def initialize(agents: Registry.new)
+        @agents = agents
+      end
+
+      # @return [OpenLanes::Agents::Registry]
+      attr_reader :agents
+
+      # One row per agent, in name order, framed by {UI.table}.
+      #
+      # @return [String] newline-terminated
+      def list
+        all = agents.all
+        return "No agent definitions in #{agents.dir}\n" if all.empty?
+
+        UI.table(all.map { |agent| row(agent) }, header: HEADINGS)
+      end
+
+      private
+
+      # A state as its words alone, deliberately without the emoji that every
+      # other rendering of a state carries. The table widget pads a cell to a
+      # width it measures in characters, while the terminal draws a status emoji
+      # in two cells; the variation-selector ones (⭕️ 🅱️ ⚪️ ⭐️ 🕰️) are two
+      # characters drawn in two cells, so no single count is right for all of
+      # them. A row carrying one lands short or long and the frame stops lining
+      # up. The label says the same thing unambiguously, and is worth more than
+      # the emoji is. {Reporter} lays its own columns out with {UI.fit} and so
+      # keeps the emoji.
+      #
+      # @param key [Symbol]
+      # @return [String]
+      def state(key)
+        status = Plans::STATUS_BY_KEY[key] or return key.to_s
+        status.label
+      end
+
+      # @param agent [OpenLanes::Agents::Agent]
+      # @return [String]
+      def handles(agent) = agent.handles.map { |key| state(key) }.join(", ")
+
+      # @param agent [OpenLanes::Agents::Agent]
+      # @return [String]
+      def advances(agent)
+        return state(agent.advances_to) if agent.advances_to
+        return BY_CONTENTS if agent.handles.any? && agent.handles.all? { |key| Plans::StateMachine::SETTLED.include?(key) }
+
+        READ_ONLY
+      end
+
+      # The widget measures and pads the cells, so they arrive painted only.
+      #
+      # @param agent [OpenLanes::Agents::Agent]
+      # @return [Array<String>] one cell per entry in {HEADINGS}
+      def row(agent)
+        [UI.paint(agent.name, :bright_cyan),
+         handles(agent),
+         UI.paint(advances(agent), agent.read_only? ? :bright_black : :green),
+         UI.paint(runs_on(agent), :bright_black),
+         UI.paint(agent.lanes.empty? ? "all" : agent.lanes.join(", "), :bright_black)]
+      end
+
+      # The agent's own settings, before any spec.md overrides them: the
+      # model, the effort, and the adapter when it is not the default.
+      #
+      # @param agent [OpenLanes::Agents::Agent]
+      # @return [String] e.g. `opus/high`, `codex:gpt-5-codex/medium`
+      def runs_on(agent)
+        model = Agents::Profile.resolve(agent).label
+        agent.effort ? "#{model}/#{agent.effort}" : model
+      end
+    end
+  end
+end

data/lib/openlanes/agents/routing.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Agents
+    # Whether an agent that handles a plan's state should actually be given
+    # the plan. Handling the state is necessary, not sufficient: the plan's
+    # lane may route around the agent, its spec.md may switch it off, or the
+    # files it builds from may hold nothing for it to do.
+    #
+    # The front end is the case that motivated this. rey-frontend used to be
+    # started on every planned folder, and spent ten minutes and five dollars
+    # on a plan whose interface was three lines of terminal output.
+    module Routing
+      # A work unit in a plan file: a second- or third-level heading. A title
+      # line does not count, so a `plan-frontend.md` that is only a heading
+      # and "no front-end units" starts nobody.
+      UNIT_HEADING = /^[ \t]{0,3}\#{2,3}[ \t]+\S/
+
+      module_function
+
+      # @param agent [OpenLanes::Agents::Agent]
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param spec [OpenLanes::Plans::Spec]
+      # @return [Boolean]
+      def allows?(agent, subject, spec = Plans::Spec.for(subject))
+        return false unless agent.serves?(spec.lane)
+        return false unless reviewable?(agent, subject)
+
+        switch = toggled(agent, spec)
+        return switch unless switch.nil?
+
+        agent.needs.all? { |file| units?(subject, file) }
+      end
+
+      # The agents in +agents+ this plan should get, in their given order.
+      #
+      # {Agent#needs} only ever chooses between agents. When lanes and
+      # switches leave one candidate, that one runs: a plan parked at 🎨 is
+      # rey-frontend's to finish whatever `plan-frontend.md` says, and an
+      # operator who typed `--agent rey-frontend` meant it.
+      #
+      # @param agents [Array<OpenLanes::Agents::Agent>]
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<OpenLanes::Agents::Agent>]
+      def filter(agents, subject)
+        spec = Plans::Spec.for(subject)
+        routed = agents.select do |agent|
+          agent.serves?(spec.lane) && toggled(agent, spec) != false && reviewable?(agent, subject)
+        end
+        return routed if routed.size <= 1
+
+        routed.select { |agent| toggled(agent, spec) || agent.needs.all? { |file| units?(subject, file) } }
+      end
+
+      # What the spec's switch for this agent says: true forces it, false
+      # forbids it, nil leaves the decision to {Agent#needs}. A spec.md that
+      # says nothing takes the project's answer from `.openlanes.yml`, so a
+      # command-line tool can say once that no plan of it has a front end.
+      #
+      # @param config [OpenLanes::Config] the project's settings
+      # @return [Boolean, nil]
+      def toggled(agent, spec, config = OpenLanes::Config.current)
+        return nil if agent.toggle.nil?
+        return nil unless spec.respond_to?(agent.toggle)
+
+        value = spec.public_send(agent.toggle)
+        return value unless value.nil?
+
+        config.public_send(agent.toggle) if config.respond_to?(agent.toggle)
+      end
+
+      # A reviewer reviews a pull request, through `gh pr diff`. A plan that
+      # reached 🟢 with none open (a shared-tree run, or --no-git-push) would
+      # hand it nothing to read, so the plan waits at 🟢 until one exists;
+      # `resync prs` records one a human opened.
+      #
+      # @param agent [OpenLanes::Agents::Agent]
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Boolean]
+      def reviewable?(agent, subject) = agent.phase.to_s != "review" || subject.pull_requests.any?(&:open?)
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param file [String]
+      # @return [Boolean]
+      def units?(subject, file) = Plans::Ledger.stripped(subject.read(file)).match?(UNIT_HEADING)
+    end
+  end
+end

data/lib/openlanes/agents.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # The specialists: their definitions in `agents/*.md`, the registry that
+  # loads and filters them, and the roster that reports on them.
+  module Agents
+    module_function
+
+    # @param dir [String] where the definitions live
+    # @return [OpenLanes::Agents::Registry]
+    def registry(dir: Registry::DEFAULT_DIR) = Registry.new(dir:)
+
+    # @param name [String]
+    # @return [OpenLanes::Agents::Agent, nil]
+    def find(name, dir: Registry::DEFAULT_DIR) = registry(dir:).find(name)
+
+    # @return [OpenLanes::Agents::Roster]
+    def roster(**) = Roster.new(**)
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes agents …` — the specialist roster.
+    module Agents
+      # `openlanes agents describe [NAME]`
+      class Describe < Dry::CLI::Command
+        include UI
+
+        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)"
+
+        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",
+          "luke-backend -m    # the same, rendered in this terminal by mdfried",
+          "                       # every agent, one viewer window each"
+        ]
+
+        # The registry instantiates commands bare, so both collaborators
+        # default to the real thing; the suite hands in its own to keep
+        # viewers from opening on the box running it.
+        #
+        # @param agents [OpenLanes::Agents::Registry]
+        # @param viewer [OpenLanes::Presentation::Viewer]
+        def initialize(agents: OpenLanes::Agents.registry, viewer: Presentation.viewer)
+          super()
+          @agents = agents
+          @viewer = viewer
+        end
+
+        # @param name [String, nil]
+        # @param mdfried [Boolean]
+        # @return [void]
+        def call(name: nil, mdfried: false, **_options)
+          agents = @agents
+          found = name ? agents.match(name) : agents.all
+
+          if found.empty?
+            known = agents.all.map(&:name).join(", ")
+            raise Error, name ? "No agent matches #{name}. Known: #{known}" : "No agent definitions in #{agents.dir}"
+          end
+
+          # A fragment that fits several agents is a question, not an order:
+          # opening all of them would bury the one that was meant.
+          raise Error, "#{name} could be any of #{found.map(&:name).join(", ")} — say which" if name && found.size > 1
+
+          paths = found.map(&:path)
+          mdfried ? @viewer.mdfried(paths) : @viewer.open(paths)
+        rescue OpenLanes::Error => e
+          error(e.message)
+          exit 65
+        end
+      end
+    end
+  end
+end