compozy

CompozyOS

This body routes to the matching reference. When tools and skills are enabled, startup includes this router, not the full reference manuals. With tools enabled and skills disabled, capable sessions retain the two complete tool manuals inline because native skill reads are unavailable. Daemon-owned title generation omits the tool router because its role consumes supplied input and returns output; other tools-enabled sessions retain the appropriate guidance.

To read a reference in a managed session, resolve compozy__skill_view through the active harness and call the returned tool reference with {"name":"compozy","file":"references/<file>.md"} using the exact path below. Tool discovery, descriptor reads, skill reads, and retained-result reads needed to load these references are the bootstrap exception to the reading prerequisite. Inspect the live descriptor before calling other tools; discover capabilities with compozy__tool_search. Keep existing tool authorization: missing guidance does not grant or revoke access, and a denied skill read is not permission to bypass policy through CLI or filesystem access.

If a reference result is truncated and includes an artifact, resolve compozy__tool_artifact_read through the active harness. Pass the returned artifact URI unchanged as artifact_uri, start at offset: 0, and continue with each next_offset until eof. Decode and concatenate data_base64 pages to read the retained result envelope, including its full structured content; preserve any redactions in display text. Use the current workspace scope. A preview alone is not a complete reference. If the result has no usable artifact or a continuation is denied, report the reference as unavailable; do not use CLI or filesystem access to bypass it.

Required Reading Router

Match the task to the row. Read the listed files in full before producing output unless the bounded descriptor fallback in Error Handling applies. They are not appendices. Inline reminders in this file are only tripwires.

Task	MUST read
Delegate code changes on an isolated branch, inspect subagent Git/PR facts, or deliver its work	references/native-tools.md; references/worktrees.md
Start, inspect, prompt, stop, resume, compact, or debug CompozyOS sessions and daemon state	references/runtime-operations.md
Open, inspect, retry, diagnose, or recover the desktop app; update the host runtime and app	references/desktop.md
Inspect or configure daemon-owned background roles, role diagnostics, builtin identities, or role fallback routing	references/runtime-operations.md + references/agent-definitions.md
Inspect, refresh, curate, or configure provider models, runtime strategies, ACP options, reasoning, Fast, or pricing	references/runtime-operations.md + references/native-tools.md
Read or refresh provider usage (subscription limits, resets, credits, balances) or configure its collection and consent	references/runtime-operations.md + references/native-tools.md
Configure provider authentication or run provider authentication login	references/agent-definitions.md + references/native-tools.md
Expose one CompozyOS workspace to an external MCP client with compozy mcp serve	references/runtime-operations.md
Inspect, mutate, or watch virtual desktops, managed windows, or workspace layouts through native tools, CLI, HTTP, or UDS	references/window-management.md + references/native-tools.md
Open, inspect, attach to, execute in, or interact with CompozyOS terminals; answer terminal input or audit terminal commands	references/terminal.md + references/native-tools.md
Create or review CompozyOS agent definitions, provider defaults, permissions, or MCP sidecars	references/agent-definitions.md + references/tools-and-skills.md
Discover or call CompozyOS-native tools, inspect native tool IDs, view skills, or choose tools vs CLI	references/tools-and-skills.md + references/native-tools.md
List, inspect, or invoke command palette commands; inspect or cancel a pending palette approval	references/native-tools.md
Work as a coordinator, task worker, or task reviewer; block or recover a task; or wake a task creator	references/tasks-and-orchestration.md
Delegate a task to a subagent on another agent, provider, or model; read, list, or cancel subagents	references/native-tools.md + references/tasks-and-orchestration.md
Author, configure, run, observe, approve, or stop a CompozyOS Loop or Goal; use /goal; read Loop terminal outcomes or events	references/loops.md + references/native-tools.md
Install, enable, update, dev-link, build, publish, or remove an extension; manage extension kits, secrets, or hooks	references/extensions.md + references/native-tools.md
Write or scaffold extension code: manifests, permissions, provide surfaces, contributed commands, or command palette entries	references/extension-authoring.md + references/extensions.md
Create or manage Automations (jobs and triggers), read their last run, or review suggestions	references/native-tools.md + references/configuration.md
Create, inspect, bind sessions to, exit, publish, remove, or recover workspace worktrees	references/worktrees.md + references/native-tools.md
Inspect or manage Gateway posture, tier surfaces, device pairing, connection profiles, SSH forwards, or stream tickets	references/runtime-operations.md + references/configuration.md
List, select, create, update, rename, archive, unarchive, delete, or retry profile lifecycle operations	references/profiles.md + references/native-tools.md
Build an external app with the TypeScript or Go client, or create, audit, update, and revoke app tokens	references/app-sdk.md
Read or change CompozyOS configuration: config.toml keys, defaults, scopes, and the settings apply lifecycle	references/configuration.md

Reference Index

• references/runtime-operations.md - daemon, session, Gateway profile/SSH, background-role, operations, lifecycle diagnostics, and runtime troubleshooting.
• references/desktop.md - desktop app commands, attachment and ownership, runtime and app updates, diagnostics, and recovery.
• references/window-management.md - daemon-authoritative desktops, windows, layouts, revisions, clients, resources, hooks, recovery, and public surfaces.
• references/terminal.md - deliberate terminal activation, native tool IDs, approval and shared input, input requests, untrusted output, journal, profile, and platform rules.
• references/agent-definitions.md - AGENT.md structure, reserved builtin role identities, provider defaults, permissions, category paths, MCP sidecars, and safe setup workflow.
• references/tools-and-skills.md - CompozyOS-native tool discovery, skill view/search, bundled resources, marketplace and MCP install flows, and management-surface exceptions.
• references/native-tools.md - daemon-native toolsets, stable CompozyOS tool IDs, when to inspect descriptors, and CLI fallbacks for agents running inside CompozyOS.
• references/tasks-and-orchestration.md - coordinator, worker, and reviewer loops, subagents versus spawned workers, task authority boundaries, typed blocks and the unblock-loop breaker, wake-creator, completion claims, review verdict rules, and sensitive-data limits.
• references/loops.md - Loop and Goal authoring/operation, /goal commands, native tools, terminal and context states, approval/recovery semantics, reference grammar, hooks, and watch behavior.
• references/extensions.md - extension kits, install trust, the authoring and dev loop, instance scoping, dev overlays, logs, and hook management.
• references/extension-authoring.md - code-backed and resource-only extension authoring: templates, SDK declarations, static manifests, permissions, provide surfaces, contributed commands, command palette entries, and structured workflows.
• references/app-sdk.md - external TypeScript and Go apps, daemon discovery, prompt/event streams, local app-token management, browser origin boundaries, and runtime OpenAPI.
• references/configuration.md - layered config.toml desired state, profile credentials, the settings apply lifecycle, and the key reference for gateway, scheduler, Loop, Goal, automation, session rebuild, role, and window-manager settings.
• references/worktrees.md - workspace worktree lifecycle, session binding, exit plans and actions, forge integration, cleanup evidence, and public management surfaces.
• references/profiles.md - operator-profile selection, immutable session binding, lifecycle plans, local-only mutations, errors, events, and public management surfaces.

Operating Loop

1. Read every reference selected by the router before acting, or qualify for the bounded descriptor fallback below.
2. Prefer CompozyOS-native tools and structured outputs over prose, logs, or direct internal access when managing CompozyOS.
3. Keep authority with the daemon: task state, review verdicts, session lifecycle, extension lifecycle, hooks, and tool calls must use CompozyOS public surfaces. Never edit SQLite databases, process internals, or generated projections directly.
4. After a mutation, confirm the result through a structured read instead of assuming success.

Error Handling

If a required resource read fails, retry compozy__skill_view once with the exact router path. Correct tool_not_found or tool_invalid_input before retrying; retry tool_backend_failed once without changing the request. After a second failure, proceed only when one native call's live descriptor fully defines the requested operation, risk, and result handling. A visible terminal_exec qualifies for a one-command terminal demonstration; multi-step terminal interaction still requires references/terminal.md. Otherwise stop the affected operation and report the exact path. Preserve structured runtime errors, follow the diagnostic order in references/runtime-operations.md, and keep daemon-owned state authoritative.

Read references/tools-and-skills.md and references/native-tools.md in full before operational tool calls or tool/skill mutations. Discovery, descriptor inspection, reference reads, and their retained-result continuations may run first to load that guidance. The catalog in this file is only a router.

STOP. Read references/tasks-and-orchestration.md in full before acting as a coordinator, worker, or reviewer. Task authority and review verdicts are runtime contracts, not prompt conventions.