0036: Make Optional Companion Skills Explicit-Only

Status: Accepted; dedicated visual-skill portion superseded by ADR 0048

Date: 2026-07-22

Context

STAGE's primary workflow delivers a requested game change through the existing project. Project mapping and dedicated visual diagnosis are optional specializations. Their skill descriptions necessarily mention broad game-work vocabulary such as architecture, assets, animation, VFX, UI, environments, and procedural content.

When those skills remained eligible for implicit invocation, their broad vocabulary could intercept ordinary delivery. Mapping could manufacture durable orientation artifacts before they were needed. Visual diagnosis could turn a normal see-change-replay loop into a separate rehearsal, capture, or gallery project. The Circussy visual-rehearsal experiment demonstrated the cost: STAGE built an off-engine evidence surface while the useful long-term opportunity was either direct engine inspection or a real game/editor gallery with independent product or authoring value.

Written warnings inside a skill are too late if that skill has already been injected for the wrong task. Routing policy must match the method policy.

Decision

• Keep stage-deliver-change eligible for implicit invocation as STAGE's ordinary game-work route.
• Set policy.allow_implicit_invocation: false for stage-map-project and stage-visual-review.
• Require explicit $stage-game-engineering:stage-map-project invocation for adoption, onboarding, external audit, or durable map maintenance.
• Require explicit $stage-game-engineering:stage-visual-review invocation for a deliberately bounded visual diagnosis beyond ordinary implementation.
• Keep the complete Visual Review method in docs/visual-review.md; keep the skill as a concise operating procedure rather than a duplicate guide.
• When repeated visual inspection earns persistence, prefer a useful native game or editor surface that reuses canonical content and production rendering. Detached capture or evidence infrastructure still requires its own named remote, comparison, retention, CI, milestone, or audit consumer.

Explicit-only is an agent-routing choice, not a claim that the capabilities are unimportant. A user can invoke either specialization directly at any time.

Consequences

• Installing STAGE does not make ordinary visible work enter a second visual workflow or make an unmapped project produce mapping artifacts.
• The primary skill remains the shortest path from request to accepted game change.
• Optional specialization is discoverable but intentional.
• A useful player, author, or developer gallery may still be built when its own recurring job earns the maintenance cost.
• Detached evidence remains available when portability or retention is the actual requirement, rather than an assumed definition of visual quality.

Evidence Boundary

This decision is based on routing analysis and same-owner dogfood. It shows that implicit companion workflows caused unnecessary ceremony in these cases. It does not establish that every optional skill in every plugin should be explicit-only.