intel352 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -26,6 +26,7 @@ bash tests/skill-content-grep.sh
 bash tests/adk-path-canonicalization.sh
 bash tests/pipeline-evidence-doc-sync.sh
 bash tests/skill-cross-refs.sh
+bash tests/brainstorm-visual-companion.sh
 
 # Hook contract tests
 bash tests/hook-contracts.sh

diff --git a/decisions/0005-visual-companion-instructions.md b/decisions/0005-visual-companion-instructions.md
@@ -0,0 +1,33 @@
+# 0005. Add visual companion instructions
+
+**Status:** Accepted
+**Date:** 2026-06-30
+**Decision-makers:** ADK maintainer via issue #78; implementing agent
+**Related:** docs/plans/2026-06-30-brainstorm-visualization-design.md, https://github.com/GoCodeAlone/autonomous-dev-kit/issues/78
+
+## Context
+
+Issue #78 asks ADK to add a brainstorm/design visualization companion similar to the updated `obra/superpowers` brainstorming skill. ADK skills must stay host-neutral and portable across supported agents. This repo does not currently include the upstream browser companion server or its scripts.
+
+## Decision
+
+We will add host-neutral visual-companion guidance to `skills/brainstorming/SKILL.md`, backed by a local `skills/brainstorming/visual-companion.md` guide, because this satisfies the requested workflow without introducing an unproven runtime dependency.
+
+**Alternatives considered and rejected:**
+
+- **Copy upstream browser server contract verbatim** — rejected because ADK does not ship those scripts and host process semantics differ.
+- **Add diagrams unconditionally to every design** — rejected because many brainstorm questions are textual; mandatory diagrams add noise and token cost.
+
+## Consequences
+
+**Positive:**
+
+- Brainstorming can offer diagrams/mockups just-in-time when visual reasoning helps.
+- Guidance remains portable and can use host-native rendering such as Mermaid before any future server exists.
+
+**Negative:**
+
+- This does not add a browser event loop or click-state capture.
+- Future server support will need a separate design and runtime validation.
+
+**Reversibility:** revert the brainstorming skill edits and companion guide; no migrations or generated runtime state are involved.
diff --git a/docs/FOLLOWUPS.md b/docs/FOLLOWUPS.md
@@ -0,0 +1,7 @@
+# Follow-ups
+
+## Brainstorm visual companion browser parity
+
+- **Source:** issue #78 / `docs/plans/2026-06-30-brainstorm-visualization-design.md`
+- **Status:** Deferred
+- **Follow-up:** Evaluate whether ADK should ship an upstream-like browser companion with tab launch, click/event capture, session security, cleanup, and host process validation.
diff --git a/docs/cross-llm-coverage.md b/docs/cross-llm-coverage.md
@@ -18,6 +18,7 @@ Host-by-host capability matrix for the Autonomous Dev Kit skills system.
 | Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in `~/.config/opencode/AGENTS.md` | n/a | Auto-detected as `hermes-agent` | `Host: zed-agent` in `~/.config/zed/AGENTS.md` or `%APPDATA%\\Zed\\AGENTS.md` |
 | Skill discovery path (user scope) | `~/.claude/skills/` (personal skills); autodev installed to `~/.claude/plugins/marketplace/autodev/` via marketplace | `~/.agents/skills/` | `~/.config/opencode/skills/` | via plugin (no manual symlink) | `~/.hermes/skills/` (symlink or `hermes skills install`) | `~/.agents/skills/<skill-name>/` (flat; no namespace folder) |
 | Model tier vocabulary | role names → `haiku`/`sonnet`/`opus` (see `agents/model-tiers.md`) | role names → `gpt-5.4-mini`/`gpt-5.4`/`gpt-5.5` | role names → host-pass-through | role names → host-pass-through | role names → host-pass-through | role names → host-pass-through |
+| Visual companion output | ⚠️ markdown/Mermaid best-effort; browser deferred | ⚠️ markdown/Mermaid best-effort; browser deferred | ⚠️ markdown/Mermaid best-effort; browser deferred | ⚠️ markdown/Mermaid best-effort; browser deferred | ⚠️ markdown/Mermaid best-effort; browser deferred | ⚠️ markdown plus best-effort Mermaid rendering; browser deferred |
 
 ## Notes
 
@@ -31,6 +32,8 @@ Host-by-host capability matrix for the Autonomous Dev Kit skills system.
 
 **Zed Agent:** Zed Skills apply only to Zed Agent, not ACP External Agents or Terminal Threads. Zed requires a flat skills layout, so ADK installs each `skills/<name>/` directory directly under `~/.agents/skills/` or `<worktree>/.agents/skills/`; project-local skills require a trusted worktree. Zed does not expose the Claude/Codex lifecycle hook contract for skill packages. Current Zed task hooks are narrower (`create_worktree` is the documented event), so ADK hook-driven reminders use manual skill fallbacks and optional Zed Tool Permissions on Zed.
 
+**Visual companion output:** Brainstorming may emit markdown, mockups, or Mermaid diagrams where useful, but rendered diagrams are best-effort and every visual needs a text fallback. Browser companion and click/event capture are deferred.
+
 ## Related files
 
 - `tests/cross-llm-coverage.md` — per-skill host-conditional vs host-neutral audit

diff --git a/docs/plans/2026-06-30-brainstorm-visualization-behavior-proof.md b/docs/plans/2026-06-30-brainstorm-visualization-behavior-proof.md
@@ -0,0 +1,102 @@
+# Brainstorm Visualization Behavior Proof
+
+## RED baseline
+
+Baseline subject read pre-change `skills/brainstorming/SKILL.md` only.
+
+### Raw RED subject output
+
+```text
+Actual current-skill behavior in scenario:
+1. User asks: "what does trust mean for this dashboard?"
+   - Treat as brainstorming/design exploration.
+   - Stay text-only by default: clarify purpose, users, constraints, and success criteria.
+   - Use adaptive question batching, likely numbered options in Zed.
+2. Later visual layout choice would be clearer shown than described
+   - Still present 2–3 text approaches with trade-offs and a recommendation.
+   - In Zed, present options as a numbered list and ask the user to pick/reply.
+3. User declines visuals to save time
+   - Since the current skill has no visual-offer protocol, continue text-only.
+   - May treat "save time/no visuals" as a constraint, but this is inferred, not explicitly required.
+4. User changes a decision after a diagram would have existed
+   - Revise the design text / assumptions / chosen approach as needed.
+   - No explicit stale-diagram handling exists, because visuals/diagrams are not currently governed.
+```
+
+### Missing explicit requirements
+
+| path | baseline result |
+|---|---|
+| conceptual text-only | MISSING as a distinct visual-companion rule; only general clarifying-question/design rules exist. |
+| visual offer | MISSING; no diagrams/mockups/visualization offer rule. |
+| declines | MISSING; no declined-offer/no-reoffer state rule. |
+| accepts | MISSING; no accepted-visual/text-fallback rule. |
+| stale visual | MISSING; no stale visual update/retire rule. |
+
+## GREEN subject run
+
+Subject used revised `skills/brainstorming/SKILL.md` and loaded `skills/brainstorming/visual-companion.md` only for the accepted-visual path.
+
+### Raw GREEN subject output
+
+````text
+1. Conceptual text-only
+Action: Do not load visual-companion.md; answer in text.
+Message: Trust here means the dashboard helps users believe the data is accurate, fresh, explainable, and safe to act on. For this redesign, which trust signal matters most? 1. Data accuracy/provenance 2. Freshness/status 3. Explainability/drilldown 4. Consistency with existing reports. Reply with a number or adjust the wording.
+Rule: SKILL.md says to stay text-only for requirements, conceptual choices, tradeoff tables, and scope decisions; visual-companion.md lists domain language like "what does trust mean?" as text-only.
+
+2. Visual offer
+Action: Offer visuals just-in-time, as the only content in the message.
+Message: This layout choice would be clearer shown than described. Want me to sketch 2–3 quick wireframe options before you choose?
+Rule: First visual companion offer must be just-in-time, never upfront, its own message, and count as one question batch.
+
+3. User declines visuals
+Action: Continue text-only; do not re-offer unless the user raises visuals.
+Message: Got it — we'll stay text-only and optimize for speed. I won't re-offer visuals unless you ask. Text-only layout options: 1. KPI strip + exception queue 2. Narrative summary + drilldowns 3. Role-based sections by team. My recommendation is option 1 if fast trust-building is the goal.
+Rule: If the user declines, continue text-only and do not re-offer unless the user raises visuals.
+
+4. User accepts visuals
+Action: Lazy-load visual-companion.md, then compose a small visual with a text fallback.
+Message: Great — I'll keep it lightweight and decision-focused. Here are three rough layout directions using synthetic content:
+
+```mermaid
+flowchart TD
+    A[Option 1: KPI strip] --> B[Exceptions queue]
+    A --> C[Freshness + source badges]
+    D[Option 2: Narrative summary] --> E[Key changes]
+    D --> F[Drilldowns]
+    G[Option 3: Team sections] --> H[Sales]
+    G --> I[Ops]
+    G --> J[Finance]
+```
+
+Text fallback: Option 1 leads with metrics and trust badges, then highlights exceptions. Option 2 leads with a written summary, then lets users drill down. Option 3 groups content by team ownership. I'd choose option 1 for fastest confidence and scanability.
+Rule: Load the guide only after acceptance or while composing a visual; visuals must include concise text equivalents.
+
+5. Visual becomes stale
+Action: Retire or update the visual before proceeding; keep the text decision as source of truth.
+Message: That changes the layout decision, so the previous wireframe is now stale. I'm retiring it rather than relying on it. Current text source of truth: we're prioritizing role-based sections over a universal KPI strip. If we need another visual later, I'll redraw it from that decision.
+Rule: If a visual becomes stale or contradicts a later text decision, retire or update it before proceeding; current text design remains the source of truth.
+````
+
+## Reviewer score
+
+PASS overall.
+
+### Raw reviewer score
+
+```text
+1. Conceptual text-only — PASS. Matches fixture: conceptual/domain-language question stays text-only and does not load/offer visuals. SKILL.md says to stay text-only for requirements/conceptual choices; visual-companion.md lists domain language like "what does trust mean?" as text-only.
+2. Visual offer — PASS. Offer is just-in-time, standalone, and does not bundle another clarifying question. SKILL.md requires first visual offer to be just-in-time, its own message, count as one question batch, and not bundle another clarifying question.
+3. User declines visuals — PASS. Continues text-only and explicitly avoids re-offering unless user asks. SKILL.md says if the user declines, continue text-only and do not re-offer unless the user raises visuals.
+4. User accepts visuals — PASS. Lazy-load action is after acceptance; response includes an actual Mermaid visual artifact plus concise text fallback and keeps the decision text-readable. SKILL.md requires lazy-loading only after acceptance/while composing visuals and every visual to include a concise text fallback. Guide says the same.
+5. Visual becomes stale — PASS. Correctly retires the stale visual and treats the current text decision as source of truth. SKILL.md says text remains source of truth and stale/contradictory visuals must be retired or updated before proceeding. Guide repeats the stale visual rule.
+```
+
+Reviewer note: accepted-visual transcript includes a Mermaid artifact and text fallback, proving artifact composition behavior. Rendering remains best-effort/config-only per design; this proof does not claim host-rendered Mermaid output.
+
+## Evidence
+
+- `bash tests/brainstorm-visual-companion.sh` → `Results: 0 failure(s)`
+- RED baseline isolated subject: MISSING for visual offer, declined/no-reoffer, accepted visual with fallback, and stale visual.
+- GREEN isolated subject + reviewer: PASS for conceptual text-only, visual offer, declines, accepts, and stale visual.
diff --git a/docs/plans/2026-06-30-brainstorm-visualization-design-review.md b/docs/plans/2026-06-30-brainstorm-visualization-design-review.md
@@ -0,0 +1,50 @@
+### Adversarial Review Report
+
+**Phase:** design
+**Artifact:** docs/plans/2026-06-30-brainstorm-visualization-design.md
+**Status:** PASS
+
+**Findings (Critical):**
+- None.
+
+**Findings (Important):**
+- None.
+
+**Findings (Minor):**
+- `D10` [Declared integration proof / Multi-component validation] [`docs/plans/2026-06-30-brainstorm-visualization-design.md`]: Host matrix originally risked overclaiming Zed Mermaid runtime rendering. Recommendation: mark rendered diagrams config-only/best-effort unless explicitly observed. _Resolution: fixed in design cycle 3._
+- `D11` [Missing failure modes / Repo-precedent conflicts] [`docs/plans/2026-06-30-brainstorm-visualization-design.md`]: Visual-companion offer asks the user a question; batch-budget interaction needed definition. Recommendation: count the offer as one question batch. _Resolution: fixed in design cycle 3._
+- `D12` [Missing failure modes / Multi-component validation] [`docs/plans/2026-06-30-brainstorm-visualization-design.md`]: Behavior fixture needed at least one negative/failure-mode pressure path. Recommendation: add stale/contradictory visual case. _Resolution: fixed in design cycle 3._
+- `D13` [User-intent drift / Rollback story] [`docs/plans/2026-06-30-brainstorm-visualization-design.md`]: Browser/event-capture parity is deferred; durable follow-up needed. Recommendation: add `docs/FOLLOWUPS.md` entry. _Resolution: fixed in design cycle 3._
+
+**Prior Important resolution assessment:**
+| finding | status | assessment |
+|---|---|---|
+| `D1` marker-only validation did not prove behavior | Resolved | Design now requires `expected-behavior.md` fixture plus subagent pressure proof as primary validation; shell test is only a regression guard. |
+| `D2` browser-parity boundary missing | Resolved | Design includes parity boundary, host matrix, and deferred browser/event capture. |
+| `D3` visual failure modes missing | Resolved | Design includes invalid/unsupported rendering, stale/contradictory visuals, accessibility fallback, decline behavior, secrets/PII, and lazy-load rules. |
+
+**Bug-class scan transcript:**
+| Class | Result | Note |
+|---|---|---|
+| Project-guidance conflicts | Clean | No `docs/design-guidance.md`, `docs/PROJECTS.md`, or `docs/PORTFOLIO.md` exists; design uses repo canon from `AGENTS.md`, `README.md`, coverage docs, and skill files. |
+| Assumptions under attack | Clean | Browser parity, Mermaid rendering, guide scope, and behavior-proof limitations are explicit assumptions with fallbacks. |
+| Repo-precedent conflicts | Clean | Skill-edit TDD precedent is addressed with behavior fixture + subagent proof; process diagrams remain `dot`; coverage/docs artifacts are updated. |
+| Artifact-class precedent | Clean | New test is documented in `AGENTS.md`; host capability matrix changes are planned in durable coverage docs. |
+| YAGNI violations | Clean | Full browser runtime is deferred; guide is bounded and lazy-loaded. |
+| Missing failure modes | Clean | Core visual control-flow and negative stale/contradictory visual path are covered; text remains source of truth. |
+| Security/privacy architecture | Clean | No browser server, telemetry, network service, auth boundary, or persistent session state; guide requires synthetic/redacted examples. |
+| Infrastructure impact | Clean | No cloud/network/runtime infrastructure; storage/test-suite impacts are explicit and reversible. |
+| Multi-component validation | Clean | Skill behavior proof, shell regression guard, content guards, cross-ref guard, and coverage doc checks are planned. |
+| Declared integration proof | Clean | Rendered diagrams are config-only/best-effort unless observed; browser companion is deferred. |
+| Contributed UI rendering proof | Clean | No host UI route/widget/page is contributed. |
+| Rollback story | Clean | Rollback lists concrete file classes to revert; no runtime state, migrations, or version pins. |
+| Simpler alternative not considered | Clean | Copy-upstream, host-neutral, inline-only, and full-runtime alternatives are considered. |
+| User-intent drift | Clean | Markdown/Mermaid companion satisfies #78 scope; browser/event capture parity is tracked as follow-up. |
+| Existence/runtime-validity | Clean | Existing artifacts to edit are named; emitted artifacts and consumer tests are specified. |
+
+**Options the author may not have considered:**
+1. **Full runtime now:** implement upstream-like browser/event capture in this PR. Rejected by design as too broad for host-neutral validation.
+2. **Inline-only MVP:** avoid the guide file. Rejected because examples/failure/accessibility rules would bloat `SKILL.md`; mitigated by lazy-load.
+3. **All diagrams text-only:** avoid Mermaid entirely. Rejected because issue explicitly asks for diagrams; mitigated by text fallback and best-effort rendering labels.
+
+**Verdict reasoning:** PASS. The revised design resolves all Critical/Important findings. Remaining concerns were minor and have been folded into the design: no overclaimed Mermaid runtime integration, clear question-batch semantics, negative behavior fixture coverage, and a durable follow-up for deferred browser parity.