brainiac 0.4.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31251e710a5798457b27ce451afac8416c61581a3c5e443766baac9523ecc2b6
-  data.tar.gz: 78519e9435feed9506750c3556f4ea9b2ea31a34bdc25bf1a1282cb9fb7f27a5
+  metadata.gz: 4f17a8d317d56d8048d7f894c2c60832dd31db1feaa38a3692e566e995c54683
+  data.tar.gz: 8f9d3e551d2a6fb4e0db4bb0514a2f37ea484cabdc18e9a8232d2fc509c7aa05
 SHA512:
-  metadata.gz: e57de5ea8715a63a478bfba62af31f691f9f89948dfa82dd8d1a2cd1a4a81b9c743a6edd316c02a8ee00ede53893729dc1f955f43b1736fc339890a01cb6ed15
-  data.tar.gz: 7b3a815f89bbdad976f5db659d4e0f82ae2b0862a29814ed4394a713c94a25ebe3cf7f8b705197163ddc13f4166ce54c729435b8ddbeb63fea690a7a12b83390
+  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/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.6"
+  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.6
+  version: 0.5.0
 platform: ruby
 authors:
 - Andy Davis