@agimon-ai/po-major-mode

Named major-mode selection for Po sessions.

A major mode is one of the four axes of a Po selection, alongside domains, the profile, and the minor modes. It names an ordered list of layers, and each layer names the packages it activates:

# .po/modes.yaml
layers:
  team:
    packages: ['@agimon-ai/po-team']
  ask-user:
    packages: ['@agimon-ai/po-user-feedback']
  task:
    packages: ['@agimon-ai/po-task']

majorMode:
  minimal:
    description: Lean mode with Team delegation and persistent tasks.
    layers: [team, task]
  copilot:
    description: General coding with delegation, persistent tasks, and structured user feedback.
    layers: [team, ask-user, task]

Default packages load before these layers. The layers array is authored activation order, not a set.

What it registers

Help guidance

This package registers help-how-to-major-mode with the session-local po/help Cordis service. Registration is inert until @agimon-ai/po-help is active. Once active, the Help skill routes the AI through this package's validated llms.txt index.

The package owns both the concise major-mode authoring prompt and the detailed modes.yaml contract, so the guidance is versioned with the parser and runtime that consume it.

Switching, and why it is not always a reload

A major-mode change alters which extensions load, and Pi freezes the CLI --extension list at construction. So the disposition depends on how the session started:

• synchronized (po, or regular pi after po sync): the session composes its own extension set on every load, so the new layers arrive with a pi-reload. If the target composition has no synchronized bundle yet, the transition reports sync-required and asks for po sync.
• launcher: the extension closure is fixed, so a mode whose layers differ needs a new process. The switch is journaled as pending and the command prints the relaunch line rather than pretending it applied.

Either way the change is planned through the session's transition coordinator first, and active minor modes are captured before the reload and restored after it. A failed apply rolls the harness state back from a snapshot and journals the transition as aborted.

The voice tool never applies a switch itself. It mints an opaque handoff token and sends /mode --voice-switch-token=… back as a follow-up, so the reload happens inside a command handler where it can be the terminal action.

Installation

Po depends on this package and activates it as fixed host core, so a Po install already has it. It is not selectable from .po/modes.yaml. It is what reads that file.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

Pi and server declarations live in src/extensions and build directly to /extensions/pi and /extensions/server. Flat root exports expose selection, status, telemetry, and schema helpers. Controllers own host integration; text and telemetry services live in named folders.

The Pi declaration installs optional Config, Transition, and Voice service bindings before its command and event declarations. Session startup awaits the runtime binding before publishing status. The shared helper owns teardown of those bindings. Picker, selection-switch, and journal modules remain lazy imports, so registering /mode does not load them eagerly.