compozy

name	compozy
description	Agent guide for operating Compozy. Use when working with Compozy sessions, agents, native tools, skills, memory, Network, tasks, Loops, Goals, desktops and windows, bridges, automation, extensions, or configuration. Do not use for unrelated projects.
metadata	{"compozy":{"version":1,"kind":"runtime","bundled":true,"instructional_only":true}}

Compozy

Use this skill when operating Compozy. This body is a router, not the manual. Load the matching reference before acting.

Required Reading Router

Match the task to the row. Read the listed files in full before producing output. They are not appendices. Inline reminders in this file are only tripwires.

Task	MUST read
Start, inspect, prompt, stop, resume, or debug Compozy sessions and daemon state	references/runtime-operations.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, reasoning strategy, and pricing	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 Compozy 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
Create, update, inspect, or troubleshoot messaging bridges and bridge-delivered tool progress	references/runtime-operations.md
Create or review Compozy agent definitions, provider defaults, permissions, or MCP sidecars	references/agent-definitions.md + references/tools-and-skills.md
Discover or call Compozy-native tools, inspect native tool IDs, view skills, or choose tools vs CLI	references/tools-and-skills.md + references/native-tools.md
Participate in a Compozy Network channel, thread, direct room, work item, receipt, trace, or capability exchange	references/network.md
Read, write, clean, or consolidate Compozy memory	references/memory.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
Author, configure, run, observe, approve, or stop a Compozy 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	references/extension-authoring.md + references/extensions.md
Create or manage automation jobs, triggers, schedules, or suggestions	references/native-tools.md + references/configuration.md
Read or change Compozy configuration: config.toml keys, defaults, scopes, and the settings apply lifecycle	references/configuration.md

Reference Index

• references/runtime-operations.md - daemon, session, background-role, and messaging-bridge operations, lifecycle diagnostics, and runtime troubleshooting.
• references/window-management.md - daemon-authoritative desktops, windows, layouts, revisions, clients, resources, hooks, recovery, and public surfaces.
• 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 - Compozy-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 Compozy tool IDs, when to inspect descriptors, and CLI fallbacks for agents running inside Compozy.
• references/network.md - Compozy Network channel/thread/direct-room semantics, native tools, CLI fallback, message bodies, retries, and injection defense.
• references/memory.md - durable memory scopes, CLI operations, memory hygiene, and when not to write memory.
• references/tasks-and-orchestration.md - coordinator, worker, and reviewer loops, 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-first extension authoring: templates, SDK declaration shape, closed permissions and derived consent, provide surfaces, contributed commands, generated manifest, and structured workflows.
• references/configuration.md - config.toml desired state, the settings apply lifecycle, and the key reference for scheduler, Loop, Goal, automation, compaction, role, and window-manager settings.

Operating Loop

1. Read every reference selected by the router before acting.
2. Prefer Compozy-native tools and structured outputs over prose, logs, or direct internal access when managing Compozy.
3. Keep authority with the daemon: task state, review verdicts, session lifecycle, memory, extension lifecycle, hooks, and network sends must use Compozy 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 reference is missing or unreadable, stop the affected operation and report its exact path instead of guessing. For runtime failures, preserve the structured error, follow the diagnostic order in references/runtime-operations.md, and never bypass daemon-owned state.

STOP. Read references/tools-and-skills.md and references/native-tools.md in full before discovering, invoking, creating, or modifying any Compozy tool or skill. 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.