# Architecture

## Two layers

The bundle and the preset deliberately live on different Cordis planes.

1. The bundle patch inserts lib/index.js into the host composition. Its provider is shared and makes the packaged skills visible through the host skill registry.
2. The preset template contributes session-facing tools and prompt behavior. It is copied into the user agent-preset root and mounted under an agent scope.

Keeping the provider host-side follows DSH registry ownership rules. Keeping bootstrap and sandbox compatibility behavior in the preset prevents an install from silently changing unrelated presets.

## Bootstrap lifecycle

The bootstrap is a system-prompt section. It gives the fresh model the using-superpowers entry rule and DSH tool vocabulary. It does not register an agent/pre-step listener; that earlier approach could feed incomplete decisions into plan mode and block turns.

## Sandbox compatibility

The normal DSH tool packages register pwsh and filesystem tools. The preset listens for agent creation, identifies every visible tool whose schema carries sandbox escalation fields, and shadows it in the child agent scope while preserving the real executor. The wrapper cleans incomplete or same-mode escalation fields. A system-prompt assembly transform hides those optional fields when the session's effective mode is danger-full-access. Lower modes retain the genuine escalation interface.

## UI/UX Pro Max Phase A boundary

The optional UI/UX Pro Max integration is isolated in `lib/ui-ux-pro-max`, with a lazy Host service exposed only by the `superpowers-dsh-uiux` preset. The normal preset remains unchanged. The pinned upstream revision is `e4f45473691e4b389519ee4bc359a3d6df666c26`; provenance envelopes carry bounded source identifiers, and persistence sanitizes paths relative to the configured workspace. Python packages are never auto-installed. Phase A uses the local core only; external MCP support is deferred to Phase B. The portable test runner discovers `.test.mjs` modules and supports `all`, `uiux`, `mcp`, and `visual` scopes.

## Porting boundary

The upstream workflow bodies are vendored without behavioral rewrites; `using-superpowers` receives one explicit DSH platform-reference link. DSH-specific behavior belongs in the provider, preset modules, and the DSH tool reference. This keeps upstream workflow philosophy reviewable and makes future upstream syncs mechanical.