brainiac 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4e2a76bc43943ef2dd556f67fa2d3b4181836dc5abf04c236944fe08c2bd74
-  data.tar.gz: a26c2581219ed65257deef259809099e4c03b2ec08f7d95d4fb649f831ce6d44
+  metadata.gz: 4f17a8d317d56d8048d7f894c2c60832dd31db1feaa38a3692e566e995c54683
+  data.tar.gz: 8f9d3e551d2a6fb4e0db4bb0514a2f37ea484cabdc18e9a8232d2fc509c7aa05
 SHA512:
-  metadata.gz: 1bdfbf38d91e481e7b51b1f8701fa446bb67206989b651bcb1f7f0bd920b7c18e6f011d21f4e9e59cbab3bcb80a878808e299d4f82f054cb5fc18b1d6bc78f25
-  data.tar.gz: 2c19663ee311472f732ae4c685b0708990deaa0d1101ac52191da5d5bc751444b8b572ae72c1fb002d4ea8158fcd4c8d61557dcd440e7ad0ce0454b10f9541a9
+  metadata.gz: 6f97132829338b279fe162668705141ba70de45fbffcbc8524b3a56d1c7dd3c9143664643001b41c0c60ef9290ddfef847f7b60e01d2465ea5aec48a3cf41d9a
+  data.tar.gz: cc521e5d9ceb8c5f578b049c6b11f3b48b6f5371bbb288d0fab54f9798564d5e6940ffb7327784f3962f4f2ba858ddaee6229aa1ae304b73aec4b1f48edb4d93

data/README.md

@@ -13,6 +13,7 @@ brainiac install fizzy       # Card management
 brainiac install discord     # Conversational bots
 brainiac install github      # PR reviews, CI notifications
 brainiac install zoho        # Email notifications and triage
+brainiac install featureparity  # Agents take work from FeatureParity
 ```
 
 Because each agent maintains its own unique persona and configuration, you can deploy a specialized team—all managed through `~/.brainiac/agents.json`. Project tracking is handled via `~/.brainiac/projects.json`, and because the system reloads configurations dynamically, you can iterate on your agent workflows in real-time without ever needing a restart.
@@ -34,6 +35,7 @@ Each plugin adds its own webhook routes and event handling. Here's what's availa
 | GitHub    | Workflow run        | `brainiac-github` | Notifies on CI failures and deploys                                     |
 | Discord   | @bot mention        | `brainiac-discord` | Each agent has its own bot — @mention routes directly, conversational   |
 | Zoho Mail | Incoming email      | `brainiac-zoho` | Rule-based matching, notifies via Discord or triages to card             |
+| FeatureParity | Start work / agent tagged | `brainiac-featureparity` | Picked agent implements the requirement, or answers the comment, in an `fp-<slug>` worktree |
 
 ### Inline Tags
 
@@ -331,6 +333,16 @@ A provider without `readonly_args` can't be used read-only; the call fails inste
 
 `claude` is the only `stream_format` so far. Lines that aren't JSON pass through unchanged.
 
+`subagents` is optional and writes the "Subagents" section of the agent's prompt. `tool` is the CLI's subagent tool, `usage` lines become how-to bullets, and `models` maps each job to a cheaper model. The session's own model (the `[fable]`/`[opus]` tag) stays the orchestrator: it plans, decides and reviews, and hands research and well-specified labor down a tier. A provider without the block gets no Subagents section, so an agent is never told to call a tool its CLI doesn't have.
+
+```json
+"subagents": {
+  "tool": "Agent",
+  "models": { "research and file sweeps": "haiku", "well-specified implementation": "sonnet" },
+  "usage": ["Pass `model` (`haiku`, `sonnet`, `opus`, `fable`) to pick the tier. Omit it and the subagent runs on your model."]
+}
+```
+
 Which provider runs is decided in this order: a `[cli:X]` tag, the agent's `cli_provider` in `agents.json`, the project's `cli_provider`, then `default_cli_provider` in `brainiac.json`. With none of those set, brainiac uses the `AGENT_CLI` env var, or kiro-cli.
 
 #### Asking an agent from a plugin
@@ -396,6 +408,7 @@ brainiac install discord     # Discord bots
 brainiac install fizzy       # Fizzy card management
 brainiac install github      # GitHub webhooks
 brainiac install zoho        # Zoho Mail
+brainiac install featureparity  # FeatureParity requirements
 ```
 
 Each plugin has its own setup command (e.g. `brainiac github setup`) and documentation. See [Plugins](#plugins-gem-based-handlers) for details.
@@ -407,6 +420,7 @@ Each plugin provides its own webhook endpoint. Point your tools at your ngrok UR
 - **Fizzy:** `https://your-ngrok.ngrok-free.app/fizzy/<board-key>` (see `brainiac fizzy setup`)
 - **GitHub:** `https://your-ngrok.ngrok-free.app/github` (see `brainiac github setup`)
 - **Zoho:** `https://your-ngrok.ngrok-free.app/zoho` (see `brainiac zoho setup`)
+- **FeatureParity:** `https://your-ngrok.ngrok-free.app/featureparity`, set as each agent's wake-up address in FeatureParity (see `brainiac featureparity setup`)
 
 #### 8. Start
 
@@ -1282,7 +1296,7 @@ The `Brainiac::Plugins` namespace is defined in `lib/brainiac.rb`. Plugin module
 | github | `brainiac-github` | GitHub webhooks — PR reviews, PR comments, PR merges, CI workflow notifications, deploy tracking |
 | zoho | `brainiac-zoho` | Zoho Mail webhooks — rule-based email notifications, AI triage, OAuth for content fetching |
 | basecamp | `brainiac-basecamp` | Basecamp epic orchestration — card tables, review gates, epic branches |
-| featureparity | `brainiac-featureparity` | FeatureParity integration for Brainiac agents |
+| featureparity | `brainiac-featureparity` | FeatureParity — starts the agent picked for a requirement, answers comments that tag it, writes missing tests, reworks rejected proposals; verifies signed deliveries |
 
 ### Backward Compatibility
 

data/lib/brainiac/helpers.rb

@@ -35,7 +35,8 @@ def load_cli_provider(provider_name)
   %w[prompt_flag readonly_args list_models_command resume_flag resume_args resume_id_flag new_session_id_flag
      session_list_command session_id_field session_directory_field session_updated_field
      session_list_path session_dir output_last_message_flag cwd_flag config_override_flag
-     effort_config_key effort_map title_flag heaviness_probe settings_model_cmd stream_args stream_format].each do |key|
+     effort_config_key effort_map title_flag heaviness_probe settings_model_cmd stream_args stream_format
+     subagents].each do |key|
     next unless raw[key]
     next if raw[key].respond_to?(:empty?) && raw[key].empty?
 
@@ -935,7 +936,7 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
   log_file = File.join(chdir, "tmp/agent-#{log_name}-#{timestamp}.log")
   FileUtils.mkdir_p(File.dirname(log_file))
 
-  prompt_file = write_agent_prompt_file(prompt, log_name, timestamp)
+  prompt_file = write_agent_prompt_file(fill_subagent_prompt(prompt, resolved, model: model), log_name, timestamp)
   output_file = prepare_output_file(resolved, log_name, timestamp)
 
   cmd = build_agent_cmd(resolved, agent_config_name: agent_config_name, model: model, effort: effort,

data/lib/brainiac/intent.rb

@@ -142,7 +142,7 @@ def check_intent(message, agent_name:, channel: "conversation", context: nil)
   # Deterministic pre-check: if the message explicitly names another agent
   # and does NOT name this agent, skip without consulting the LLM.
   # This handles the common case of "Effie, tell me another" when checking Galen.
-  if intent_names_other_agent?(message, agent_name)
+  if intent_names_other_agent?(message, agent_name, context)
     LOG.info "[Intent] Deterministic skip for #{agent_name} — message addresses another agent"
     return false
   end
@@ -327,11 +327,16 @@ end
 #   - "Was Effie nice to you?" (asking about Effie)
 #   - "I liked what Effie said" (referencing Effie)
 #
+# Agents running on other machines aren't in AGENT_REGISTRY, so bot authors seen in
+# the conversation context ("Name [bot]: ...") count as agents too.
+#
 # @param message [String] The message text
 # @param agent_name [String] The agent being evaluated
+# @param context [String, nil] Conversation history
 # @return [Boolean] true if another agent is directly addressed and this one isn't
-def intent_names_other_agent?(message, agent_name)
-  return false unless defined?(AGENT_REGISTRY) && !AGENT_REGISTRY.empty?
+def intent_names_other_agent?(message, agent_name, context = nil)
+  names = intent_agent_display_names.keys | context_bot_names(context).map(&:downcase)
+  return false if names.empty?
 
   msg_lower = message.downcase.strip
   agent_lower = agent_name.downcase
@@ -340,9 +345,7 @@ def intent_names_other_agent?(message, agent_name)
   return false if directly_addressed_to?(msg_lower, agent_lower)
 
   # Check if any OTHER agent is directly addressed (not merely mentioned)
-  AGENT_REGISTRY.each do |key, entry|
-    display = entry.is_a?(Hash) ? (entry["display_name"] || key.capitalize) : key.capitalize
-    other_lower = display.downcase
+  names.each do |other_lower|
     next if other_lower == agent_lower
     next unless msg_lower.match?(/\b#{Regexp.escape(other_lower)}\b/)
 
@@ -403,64 +406,66 @@ def build_intent_agent_roster(agent_name)
   names.join(", ")
 end
 
+# Map of lowercased agent display name => display name, from the local AGENT_REGISTRY.
+def intent_agent_display_names
+  return {} unless defined?(AGENT_REGISTRY) && !AGENT_REGISTRY.empty?
+
+  AGENT_REGISTRY.each_with_object({}) do |(key, entry), names|
+    display = entry.is_a?(Hash) ? (entry["display_name"] || key.capitalize) : key.capitalize
+    names[display.downcase] = display
+  end
+end
+
+# Parse a context line ("username: message", or "username [bot]: message" when the
+# plugin knows the author is a bot). Returns [username, bot?] or nil.
+def parse_context_author(line)
+  match = line.match(/\A(\S+?)( \[bot\])?:\s/)
+  match && [match[1], !match[2].nil?]
+end
+
+# Usernames of every bot author in the context.
+def context_bot_names(context)
+  return [] if context.nil?
+
+  context.lines.filter_map do |line|
+    username, bot = parse_context_author(line)
+    username if bot
+  end.uniq
+end
+
 # Detect the last agent to respond in the conversation context.
 # Returns a prompt-friendly string telling the model who was last to respond.
 #
-# The context is formatted as "username: message\n..." lines.
-# We scan backwards to find the most recent line authored by a known agent.
-#
 # @param context [String, nil] Conversation history
 # @param agent_name [String] The current agent being evaluated
 # @return [String] Prompt block describing the last responder
 def detect_last_responder(context, _agent_name = nil)
-  return "No agent has spoken yet." if context.nil? || context.strip.empty?
-  return "No agent has spoken yet." unless defined?(AGENT_REGISTRY) && !AGENT_REGISTRY.empty?
-
-  # Build a lookup of agent display names (lowercase) to their proper display name
-  agent_names = {}
-  AGENT_REGISTRY.each do |key, entry|
-    display = entry.is_a?(Hash) ? (entry["display_name"] || key.capitalize) : key.capitalize
-    agent_names[display.downcase] = display
-  end
-
-  # Scan context lines in reverse to find the last agent message
-  lines = context.strip.lines.reverse
-  lines.each do |line|
-    # Lines are formatted as "username: message content"
-    match = line.match(/\A(\S+?):\s/)
-    next unless match
+  responder = detect_last_responder_name(context)
+  return "No agent has spoken yet." unless responder
 
-    username = match[1].downcase
-    next unless agent_names.key?(username)
-
-    responder = agent_names[username]
-    return "#{responder} was the last to speak. The human is continuing the conversation with #{responder}."
-  end
-
-  "No agent has spoken yet."
+  "#{responder} was the last to speak. The human is continuing the conversation with #{responder}."
 end
 
 # Detect the last agent to respond — returns just the display name (or nil).
 # Used for deterministic conversational-flow checks without LLM involvement.
 #
+# The context is formatted as "username: message\n..." lines. We scan backwards for
+# the most recent line from a known agent, or from any bot — an agent on another
+# machine is still the one the human is talking to.
+#
 # @param context [String, nil] Conversation history
 # @return [String, nil] Display name of last agent to speak, or nil
 def detect_last_responder_name(context)
   return nil if context.nil? || context.strip.empty?
-  return nil unless defined?(AGENT_REGISTRY) && !AGENT_REGISTRY.empty?
 
-  agent_names = {}
-  AGENT_REGISTRY.each do |key, entry|
-    display = entry.is_a?(Hash) ? (entry["display_name"] || key.capitalize) : key.capitalize
-    agent_names[display.downcase] = display
-  end
+  agent_names = intent_agent_display_names
 
   context.strip.lines.reverse_each do |line|
-    match = line.match(/\A(\S+?):\s/)
-    next unless match
+    username, bot = parse_context_author(line)
+    next unless username
 
-    username = match[1].downcase
-    return agent_names[username] if agent_names.key?(username)
+    return agent_names[username.downcase] if agent_names.key?(username.downcase)
+    return username if bot
   end
 
   nil

data/lib/brainiac/prompts.rb

@@ -112,34 +112,7 @@ PROMPT_CORE = <<~PROMPT
   If the task is ambiguous or you're uncertain about requirements, ask before starting.
   If you're 90% sure, proceed. If you're 60% sure, ask.
 
-  ## Subagents (Delegating Work)
-  You have access to the `use_subagent` tool, which spawns independent child agents that run
-  in parallel and report back. Use them to preserve your context window for implementation.
-
-  **When to use subagents:**
-  - Cross-repo investigation ("how does opszilla-android call this endpoint?")
-  - Heavy codebase research before implementation (reading many files you won't need later)
-  - Parallel tasks that don't depend on each other
-  - When your context is getting heavy and you need to offload research
-
-  **When NOT to use subagents:**
-  - Simple, directed lookups (one file, one function, one grep)
-  - Tasks that require your brain context, persona, or memory
-  - Posting comments or external communication (only you can do that)
-
-  **How to use them effectively:**
-  - Be specific in your query — tell the subagent exactly what to find and where to look
-  - Include relevant file paths and repo locations in the query
-  - Use `relevant_context` to pass information the subagent needs
-  - You can specify `agent_name` to use a specialized agent (e.g., "robin" for Android research)
-  - Run `ListAgents` first if you want to see available specialized agents
-  - Up to 4 subagents can run in parallel
-  - To discover project locations for cross-repo work, run: `brainiac list`
-
-  **Limitations:** Subagents don't get your brain context, persona, or memory.
-  They can read files and run commands, but cannot post to Discord, GitHub, or other channels.
-  They're excellent researchers — use them as such.
-
+  {{SUBAGENTS}}
   ## Image Reading Limits
   Read at most 4-5 images per tool call. Summarize what you saw before reading more.
   Loading too many images at once can exceed the API request size limit and crash your session.
@@ -251,6 +224,66 @@ def populate_prompt_vars(vars, agent_name:, board_key:)
   vars["AGENT_ROSTER"] ||= roster_lines
 end
 
+# The Subagents section of PROMPT_CORE, built from the provider's `subagents` block in
+# cli-providers/<name>.json. Rendered at dispatch time (run_agent) because that's where the
+# provider is resolved. Providers without the block get no section: telling an agent to call
+# a tool its CLI doesn't have is worse than saying nothing.
+#
+#   "subagents": {
+#     "tool": "Agent",
+#     "models": { "research": "haiku", "implement": "sonnet" },
+#     "usage": ["Pass `model` to pick the tier."]
+#   }
+def subagent_prompt_section(subagents, model: nil)
+  return "" unless subagents.is_a?(Hash) && subagents["tool"]
+
+  lines = ["## Subagents (Delegating Work)"]
+  lines << "You have the `#{subagents["tool"]}` tool, which spawns child agents that run in parallel and report back."
+  lines << "Their file dumps stay out of your context, so long sessions stay lean."
+  lines << ""
+  lines << "**Delegate when the work is big, not because of the channel.** A card or a Discord request that"
+  lines << "spans many files or repos is worth delegating. A five-tool-call answer is not: each subagent"
+  lines << "starts cold and rereads everything, so it costs more than doing it yourself."
+  lines << ""
+  lines << "**Good jobs for subagents:** cross-repo investigation, sweeping many files you won't need later,"
+  lines << "independent tasks that can run in parallel, and mechanical edits you've already specified exactly."
+  lines << ""
+  lines << "**Keep for yourself:** design and architecture decisions, judgment calls, anything that needs your"
+  lines << "brain context, persona, or memory, final review of the change, and all external communication."
+  lines << "Subagents gather facts and do well-specified labor; they don't make the call. If a subagent's"
+  lines << "report drives a decision, verify the part that matters before acting on it."
+  append_subagent_models(lines, subagents["models"], model)
+  lines << ""
+  lines << "**How to use them:**"
+  Array(subagents["usage"]).each { |line| lines << "- #{line}" }
+  lines << "- Brief each subagent like a peer: the goal, exact files and repos, and what you've ruled out."
+  lines << "- Run `brainiac list` to find project paths for cross-repo work."
+  lines << ""
+  lines << "**Limitations:** Subagents don't get your brain context, persona, or memory, and can't post to"
+  lines << "Discord, GitHub, or other channels."
+  "#{lines.join("\n")}\n\n"
+end
+
+# Model tiers: you stay on the session's model (the [fable]/[opus] tag) for planning and the
+# final word; cheaper tiers take the labor.
+def append_subagent_models(lines, models, model)
+  return unless models.is_a?(Hash) && !models.empty?
+
+  lines << ""
+  lines << "**Model tiers:** You#{" (#{model})" if model} are the orchestrator. Pick a cheaper model for each subagent's job:"
+  models.each { |job, tier| lines << "- #{job}: `#{tier}`" }
+  lines << "Never hand a design or review decision down a tier to save money; that's the expensive part you're here for."
+end
+
+# Fill the {{SUBAGENTS}} slot left in PROMPT_CORE. A no-op for prompts that don't have it
+# (resume prompts, cron prompts).
+def fill_subagent_prompt(prompt, resolved, model: nil)
+  return prompt unless prompt.include?("{{SUBAGENTS}}")
+
+  section = subagent_prompt_section(resolved["subagents"], model: model)
+  prompt.sub("{{SUBAGENTS}}\n", section).sub("{{SUBAGENTS}}", section)
+end
+
 # Lean prompt for resumed sessions. The previous session already has the full context
 # (role, persona, knowledge, core instructions, channel prompts). We only send the new
 # comment and any fresh card context so the agent knows what changed.

data/lib/brainiac/version.rb

@@ -2,5 +2,5 @@
 
 module Brainiac
   # @return [String] the current gem version
-  VERSION = "0.4.5"
+  VERSION = "0.5.0"
 end

data/templates/cli-providers/kiro.json.example

@@ -28,5 +28,14 @@
     "comment": "Optional. Lets brainiac record how 'heavy' a finished session was (context window usage + credits) in the durable session history. type selects the probe strategy; db_path points at the provider's local usage store. Omit this block to record timing/identity only.",
     "type": "kiro_sqlite",
     "db_path": "~/.local/share/kiro-cli/data.sqlite3"
+  },
+  "subagents": {
+    "comment": "Optional. Renders the Subagents section of the agent prompt. tool is the CLI's subagent tool; usage lines are appended as how-to bullets; models (job => tier) tells the agent which cheaper model to hand each job. Omit the block for CLIs with no subagent tool.",
+    "tool": "use_subagent",
+    "usage": [
+      "Use `relevant_context` to pass information the subagent needs.",
+      "Set `agent_name` for a specialized agent (e.g. \"robin\" for Android research); run `ListAgents` to see them.",
+      "Up to 4 subagents can run in parallel."
+    ]
   }
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Andy Davis