# Architecture

## Fundamental Rule

Superpowers determines the process of work.

`dyslex.ia` adapts the presentation of that process.

`dyslex.ia` must not bypass Superpowers brainstorming, planning, test-driven development, debugging, code review, or verification gates.

## Components

- `.codex-plugin/plugin.json`: Codex plugin manifest for the skills bundle.
- `skills`: native Agent Skills collection and primary integration surface.
- `adapters`: thin host-specific plugin installation manifests.
- `src/profiles`: local accessibility profiles and config precedence.
- `src/readability`: local transformations, ambiguity checks, terminal summaries, diff summaries, and technical-token protection.
- `src/dependency`: blocking Superpowers resolver.
- `src/hosts`: host detection and compatibility catalog.
- `src/server`: optional stdio compatibility bridge and transport wiring.
- `src/tools`: strict optional bridge tool schemas and deterministic handlers.
- `src/resources`: versioned optional bridge resources.
- `src/prompts`: reusable optional bridge prompt templates.

## Startup Gate

`resolveSuperpowersDependency()` protects both plugin installation planning and optional bridge startup.

For bridge compatibility, it runs before `server.connect(transport)`.

If dependency validation fails:

- no bridge transport is connected;
- no tools, prompts, or resources are published to a client;
- the process returns a non-zero exit code;
- the error is short and actionable;
- no automatic Superpowers download occurs.

## Dependency Validation

A directory named `superpowers` is not enough.

Validation requires:

- resolvable real path;
- directory, not file;
- `skills/using-superpowers/SKILL.md`;
- package or plugin metadata;
- valid semver version;
- version compatible with `>=4.0.0 <7.0.0`.

## Data Flow

User text, terminal output, diffs, and code are treated as untrusted data. The tools analyze and transform text locally. They do not execute supplied content.

## Streamable HTTP

The architecture keeps transport creation isolated in `src/server/mcp.ts`. A future Streamable HTTP transport can be added beside `stdio`, but it is not enabled by default.