Compozy is an AI-assisted development workflow tool written in Go. It is not just a prompt runner. The current project is built around structured markdown artifacts, ACP-capable coding-agent runtimes, daemon-managed state, review remediation, reusable agents, and executable extensions.

That makes it a useful Go codebase to read if you are building developer tools that coordinate long-running work across local files, subprocesses, external CLIs, and review providers.

The workflow is stored as markdown

Compozy’s product model is intentionally file-based. PRDs, technical specs, tasks, review issues, ADRs, and memory live as markdown files under .compozy/. Task and review files carry YAML frontmatter for machine-readable metadata such as status, title, type, severity, dependencies, and provider references.

That is a practical choice for developer tooling. Humans can review and edit the artifacts. Git can diff them. The CLI can still parse the frontmatter and reconcile it into daemon state.

The Go lesson is that durable workflow state does not always need to start in a database. For tools that live inside a repository, files are often the right API.

ACP runtimes are the execution boundary

Compozy runs work through ACP-capable runtimes such as Claude Code, Codex, Cursor, Droid, OpenCode, Pi, Gemini, and others. The README lists the expected commands for each runtime, for example claude-agent-acp, codex-acp, cursor-agent acp, and gemini --acp.

That boundary is more accurate than saying Compozy has a direct OpenAI/Ollama completion provider abstraction. The tool delegates coding work to agent runtimes, tracks the run, and feeds those agents structured artifacts.

For Go developers, this is a good pattern: isolate the volatile integration point. Agent CLIs and editor runtimes change quickly. Keeping execution behind a runtime adapter gives the rest of the workflow a stable model.

The daemon owns runtime state

The current README describes a daemon model:

• compozy daemon start|status|stop manages lifecycle
• task, review, and exec commands can auto-start the daemon
• daemon-managed runs live under ~/.compozy/runs/<run-id>/
• runs attach and runs watch reconnect through daemon snapshots and streams
• workspace registration is handled through daemon workspace commands

That is a real architectural decision. The CLI is not just a one-shot process. Long-running agent tasks need state, logs, attachment, cancellation, and observation. A home-scoped daemon gives Compozy somewhere to keep that state without burying it in the project directory.

Reviews are provider-agnostic

Compozy normalizes review feedback from multiple sources. The README mentions CodeRabbit, GitHub, and internal AI-powered reviews. Review issue files use common metadata and can be fixed through compozy reviews fix.

In the code, extension review providers are modeled around review operations such as fetching reviews and resolving issues. That is very different from a generic llm.Provider with a Complete method. The provider boundary is about review workflows, not raw chat completions.

This is the useful design idea: model the domain operation you actually need. A “review provider” can return normalized comments and resolve provider threads. That is more helpful than forcing every integration into a lowest-common-denominator text completion API.

Extensions are subprocess-capable

Compozy supports executable extensions that can hook into workflow phases, modify prompts, observe lifecycle events, provide review data, and ship skill packs. The extension manifest describes capabilities and hooks; the runtime manages subprocess bridges and host permissions.

That is a familiar Go tooling pattern. Keep extensions out-of-process when you need isolation, version flexibility, or non-Go SDKs. Use structured messages and explicit capabilities so the host knows what an extension is allowed to do.

Setup and execution are separate

One detail worth copying is the separation between installing skills and running agents. compozy setup installs workflow skills and extension assets into supported agents/editors. Execution commands such as compozy exec, compozy tasks run, and compozy reviews fix still require an ACP runtime or adapter on PATH.

That avoids a common developer-tooling mess: setup state, runtime availability, and workflow state are related, but not the same thing. Compozy treats them as separate concerns.

What to take from Compozy

The useful Go lessons are not invented pipeline interfaces or generic LLM clients. The actual project shows a more concrete architecture:

• markdown artifacts as the human-editable workflow contract
• YAML frontmatter for machine-readable metadata
• ACP runtimes as the execution boundary
• a daemon for long-running run state and reconnects
• provider-specific review integrations normalized into one review model
• subprocess extensions with explicit capabilities
• local-first single-binary tooling around repository files

That is the shape of a serious AI developer tool: keep the workflow inspectable, keep the integrations behind boundaries, and make long-running work observable after the original terminal session disappears.