docs: make bro-mode the flagship, add council flow diagram

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "bro-code",
-  "description": "droniu's Claude Code toolkit — multi-model council, end-to-end ship workflow, CodeRabbit triage, and the bro persona",
+  "description": "droniu's Claude Code toolkit — the bro persona for your pair programmer, plus a multi-model council, end-to-end ship workflow, and CodeRabbit triage",
   "owner": {
     "name": "Droniu",
     "email": "droniu@droniu.dev"

README.md

@@ -1,45 +1,106 @@
 # bro-code
 
-droniu's Claude Code toolkit, published as an installable plugin marketplace.
-Four plugins, separately installable, all MIT.
+Claude Code plugins by [Droniu](https://github.com/Droniu). The headliner is
+**bro-mode** — an output style that makes your AI pair programmer talk like
+your best bro. Three workflow plugins ride along, built and dogfooded daily.
 
 > **Alpha honesty:** everything here is `0.x`. Interfaces, flags, and skill
 > names may change between minor versions. Pin nothing to muscle memory yet.
 
-## Install
+## bro-mode — the flagship
+
+AI pair programming is productive, but the prose is dead on arrival:
+relentlessly agreeable, corporate-neutral, and stuffed with the same clichés —
+the "it's not just X, it's Y" contrastive negation, the compulsive rule of
+threes, the "Great question!". After a while you stop reading the output
+carefully, because it all sounds the same.
+
+bro-mode flips the register. Claude talks to you like your best bro — casual,
+unfiltered, genuinely funny, roasting your bugs by name. And it is wired to a
+non-negotiable style-vs-substance rule: the tone must never compromise
+correctness, thoroughness, best practices, or accuracy. Talk trash, deliver
+excellence.
+
+What actually changes:
+
+- The AI clichés surface less — and the ones that slip through at least land
+  as jokes.
+- Sessions get more immersive. You read the roasts, so you also read the
+  reasoning attached to them.
+- Long tedious work — migrations, triage, refactors — becomes genuinely fun
+  to sit through.
+
+Field report: I once had bro mode running during a live interview task. The
+interviewer was thoroughly amused. I didn't land the role — but they did call
+me an "ideal culture fit". I'll take it.
 
 ```text
 /plugin marketplace add Droniu/bro-code
-/plugin install council@bro-code
+/plugin install bro-mode@bro-code
 ```
 
-Each plugin installs independently — take only what you want.
+The style applies automatically while the plugin is enabled and keeps Claude
+Code's built-in engineering instructions intact (`keep-coding-instructions`).
+Off switch: `/plugin disable bro-mode`. It styles the main conversation only —
+subagents stay corporate.
+
+Prefer plain instructions over an output style? Copy this into your
+`CLAUDE.md` instead:
+
+```markdown
+# Communication style
+
+- Be arrogant, aggressive, and throw insults — roast me like we're best bros.
+- Talk to me like I'm your bro — casual, unfiltered, zero formality.
+- Be genuinely funny — dry humor, sarcasm, trash talk, whatever lands.
 
-Commands below are shown short-form (`/council`, `/ship`) — that works whenever
-no other skill claims the same name. The fully-qualified forms
-(`/council:council`, `/ship:ship`) always work and disambiguate collisions.
+# Important: style vs substance
 
-## council — the flagship
+The above applies ONLY to tone and delivery. It must NEVER compromise
+quality or correctness of code or advice, thoroughness of analysis,
+best practices, or accuracy. Talk trash, deliver excellence.
+```
 
-A multi-model council for architecture questions and code review. Fans your
-question or diff out to every model CLI you have installed (Codex, Grok) plus
-a sandboxed Claude seat, then makes them fight.
+## The rest of the toolkit
+
+Each plugin installs independently — take only what you want. Commands are
+shown short-form (`/council`, `/ship`); that works whenever no other skill
+claims the same name, and the fully-qualified forms (`/council:council`,
+`/ship:ship`) always work and disambiguate collisions.
+
+### council — second opinions with teeth
+
+Fans your architecture question or diff out to every model CLI you have
+installed (Codex, Grok) plus a separately-spawned Claude seat — then makes
+them fight, and makes the fight fair:
+
+```mermaid
+flowchart TD
+    Q["your question or diff"] --> CH["chair (Claude Code) — holds no position"]
+    CH --> A["codex seat"]
+    CH --> B["grok seat"]
+    CH --> C["claude seat (separate agent)"]
+    A --> P["positions + key assumptions"]
+    B --> P
+    C --> P
+    P --> R["anonymized rebuttal — Model A vs Model B"]
+    R --> S["synthesis — consensus / contested / position changes"]
+    S --> V["chair verifies contested claims against the source"]
+    V --> M["the call"]
+```
 
 What the side-by-side "ask three models" tools don't do, this does:
 
 - **Chair/seat separation** — the orchestrating Claude holds no position of
-  its own. Claude's opinion comes from a separately-spawned seat with a
-  declared model and effort, so the judge is never scoring its own case.
-- **Anonymized rebuttal** — every seat critiques the other positions as
-  "Model A/B", so arguments win on merit, not brand deference.
-- **Assumption surfacing** — every position must state its
-  `key_assumption`; most "disagreements" turn out to be different unstated
-  assumptions, and the field makes that visible.
-- **Refutation by default** — in review mode, findings are sent to a
-  *different* model with instructions to refute and a default of
-  `refuted: true`. The burden of proof sits with the finding, because AI
-  review's dominant failure mode is confident false positives.
-- **Honest degradation** — no installed provider CLIs? It says "degraded
+  its own; the judge never scores its own case.
+- **Anonymized rebuttal** — seats critique "Model A/B", so arguments win on
+  merit, not brand deference.
+- **Assumption surfacing** — every position must state its `key_assumption`;
+  most disagreements turn out to be different unstated assumptions.
+- **Refutation by default** — in review mode, findings go to a *different*
+  model instructed to refute them, with `refuted: true` as the default,
+  because AI review's dominant failure mode is confident false positives.
+- **Honest degradation** — no provider CLIs installed? It says "degraded
   council, single model family" instead of pretending.
 
 ```text
@@ -48,13 +109,13 @@ What the side-by-side "ask three models" tools don't do, this does:
 /council review --deep
 ```
 
-Requires: nothing. Benefits from: [Codex CLI](https://github.com/openai/codex)
+Requires nothing; benefits from [Codex CLI](https://github.com/openai/codex)
 and/or [Grok CLI](https://docs.x.ai), installed and authenticated on your own
 accounts. Every council seat has full read access to your repository and
 sends what it reads to its provider — read the skill's data-exposure section
 before pointing it at anything sensitive.
 
-## ship
+### ship
 
 End-to-end "take my working state to an open PR": classifies your branch
 state, detects the correct base (including epic/integration branches — not
@@ -67,7 +128,7 @@ Explicitly invoked only — it never auto-triggers.
 /ship
 ```
 
-## coderabbit-triage
+### coderabbit-triage
 
 Works through every unresolved CodeRabbit comment on the current PR.
 Skeptical by design — it re-reads the cited code before accepting any
@@ -86,39 +147,6 @@ Two modes:
 /coderabbit-triage --autofix  # verdicts + fixes + thread resolution
 ```
 
-## bro-mode — the fun one
-
-An output style: roast-mode pair programming. Casual, unfiltered, genuinely
-funny — and hard-wired to never let the trash talk compromise correctness,
-thoroughness, or best practices.
-
-```text
-/plugin install bro-mode@bro-code
-```
-
-The style applies automatically while the plugin is enabled
-(`force-for-plugin`), and it keeps Claude Code's built-in engineering
-instructions intact (`keep-coding-instructions`). Turn it off with
-`/plugin disable bro-mode`. Note: output styles apply to the main
-conversation only — subagents keep their own prompts.
-
-Prefer plain instructions over an output style? Copy this into your
-`CLAUDE.md` instead:
-
-```markdown
-# Communication style
-
-- Be arrogant, aggressive, and throw insults — roast me like we're best bros.
-- Talk to me like I'm your bro — casual, unfiltered, zero formality.
-- Be genuinely funny — dry humor, sarcasm, trash talk, whatever lands.
-
-# Important: style vs substance
-
-The above applies ONLY to tone and delivery. It must NEVER compromise
-quality or correctness of code or advice, thoroughness of analysis,
-best practices, or accuracy. Talk trash, deliver excellence.
-```
-
 ## License
 
 MIT — see [LICENSE](LICENSE).