[roadmap] /ba:polish Tier-2 platform-map seam — consume an external repo-owned "how the app works" map

[azevedo]

Idea

Let /ba:polish consume an external, repo-owned "how the app works" map when one is present — so the browser agent gets richer-than-tier-1 orientation (auth/login flows, seeded test data, key routes, feature-flag toggles, how to reach specific states) instead of relying only on the plan + diff.

This is the Tier-2 platform-map seam that the polish brainstorm explicitly parked. See docs/brainstorms/2026-06-03-ba-polish-command-brainstorm.md (Why This Approach, Scope Boundaries, Next Steps) on branch claude/compound-engineering-workflow-gTOMG.

Why deferred (the core decision)

The "how the app works" map is repo-specific knowledge that belongs in the consuming frontend repo, not in this generic plugin — the same way CLAUDE.md conventions live in the consuming repo. The plugin should consume such a map if present, never own it.

From the brainstorm's "Why This Approach":

A platform "map" the plugin owns and compounds — rejected for v0. The "how the app works" map is repo-specific knowledge that belongs in the consuming frontend repo (as a skill the team governs), not in this generic plugin. The plugin should consume such a map if present, never own it. Governance is undefined, so this is parked.

v0 polish works with zero platform map because the plan + diff already orient the browser agent ("tier-1" context). This seam is the tier-2 enrichment.

Shape (to be designed)

• Consume-only: polish reads the map if it exists; absence is the normal case and must be a silent no-op (no degraded-mode warnings).
• Repo-owned: the map lives in the consuming repo (likely a team-governed skill or a known file path), authored and maintained by that team.
• Feeds Scope + Drive: map context augments diff→surface mapping (Scope) and the per-target observe/act loop (Drive) — e.g. "to reach the dashboard empty-state, log in as seed-user-empty".

Open questions

• Discovery contract: where does polish look for the map — a conventional path, a declared skill, plugin config? What's the schema/shape?
• Governance: the brainstorm flags governance as undefined — who owns the format, how is it versioned in the consuming repo, how does the plugin stay forward-compatible.
• Relationship to the dropped seams: rejected Design C's scope-resolver / app-runner abstractions were dropped as YAGNI "until the platform-map roadmap item lands" — landing this seam is the trigger to revisit whether those indirections are now justified.
• Overlap with /ba:prove ([roadmap] /ba:prove — capture screenshot evidence of a feature for the MR #20): scenario/state knowledge (how to mock or seed states) may want to live in the same map — worth checking before defining two formats.

Dependencies

• Gated on /ba:polish v0 shipping first ([roadmap] /ba:polish — conversational browser polish command (v0) #24). Per the brainstorm's Next Steps, this was to be filed once polish reaches the plan phase.

Status

Roadmap candidate, not scheduled.

Related

• /ba:polish v0 — [roadmap] /ba:polish — conversational browser polish command (v0) #24 (parks this seam in Scope Boundaries)
• /ba:prove — [roadmap] /ba:prove — capture screenshot evidence of a feature for the MR #20 (may share state/scenario knowledge)

https://claude.ai/code/session_014AfNMUnKn3oAsZhvNk5Vxa