Compozy

Compozy Reference Guide

Comprehensive reference for the Compozy CLI and its AI-assisted development workflow.

What Is Compozy

Compozy is a Go CLI that orchestrates the full lifecycle of AI-assisted development. It covers product ideation, technical specification, task decomposition, automated execution via AI coding agents, and PR review remediation.

Key characteristics:

• Agent-agnostic. Supports claude, codex, copilot, cursor-agent, droid, gemini, opencode, and pi as ACP runtimes.
• Skills-based. Bundled skills (installed via compozy setup) teach agents how to execute each workflow phase.
• Artifact-driven. Planning and review artifacts live as markdown under .compozy/tasks/<slug>/, versioned alongside the codebase.
• Daemon-backed runtime. A home-scoped daemon owns run state, workspace registration, snapshots, streams, and the synced global.db catalog under ~/.compozy/.
• Single binary, local-first. The daemon is launched from the same binary; there are no external control planes.

Workflow Pipeline Overview

The standard development pipeline follows these phases in order. Each phase produces artifacts consumed by the next.

1. Setup -- compozy setup installs core skills into target agents plus any setup assets shipped by enabled extensions.
2. Ideation (optional) -- install and enable the first-party cy-idea-factory extension, run compozy setup, then use /cy-idea-factory to expand a raw idea into a structured, research-backed spec at .compozy/tasks/<slug>/_idea.md.
3. Requirements -- /cy-create-prd creates a business-focused Product Requirements Document at .compozy/tasks/<slug>/_prd.md plus the user-story catalog _user_stories.md, with ADRs.
4. Technical Design -- /cy-create-techspec translates the PRD into a technical specification at .compozy/tasks/<slug>/_techspec.md plus the test contract _tests.md, with ADRs.
5. Task Decomposition -- /cy-create-tasks breaks down the PRD and TechSpec into robust, independently implementable task files (task_01.md, task_02.md, etc.) and a canonical task graph manifest at _tasks.md, assigning every _tests.md case to a task.
6. Execution -- compozy tasks run <slug> --ide <runtime> dispatches task files to the configured AI agent for implementation. Use --parallel-tasks to run one workflow by dependency waves from _tasks.md graph edges.
7. Review -- /cy-review-round (manual AI review) or compozy reviews fetch <slug> --provider coderabbit --pr <N> (external provider) produces review issue files under reviews-NNN/.
8. Remediation -- compozy reviews fix <slug> processes review issues, triages, fixes, and verifies each one.
9. Archive -- compozy archive --name <slug> moves fully completed workflows to .compozy/tasks/_archived/.

Repeat phases 7-8 until the review is clean, then merge.

digraph compozy_pipeline {
    "compozy setup" [shape=box];
    "/cy-idea-factory (optional)" [shape=box];
    "/cy-create-prd" [shape=box];
    "/cy-create-techspec" [shape=box];
    "/cy-create-tasks" [shape=box];
    "compozy tasks run" [shape=box];
    "Review (manual or provider)" [shape=box];
    "compozy reviews fix" [shape=box];
    "Reviews clean?" [shape=diamond];
    "compozy archive" [shape=doublecircle];

    "compozy setup" -> "/cy-idea-factory (optional)";
    "/cy-idea-factory (optional)" -> "/cy-create-prd";
    "/cy-create-prd" -> "/cy-create-techspec";
    "/cy-create-techspec" -> "/cy-create-tasks";
    "/cy-create-tasks" -> "compozy tasks run";
    "compozy tasks run" -> "Review (manual or provider)";
    "Review (manual or provider)" -> "compozy reviews fix";
    "compozy reviews fix" -> "Reviews clean?";
    "Reviews clean?" -> "Review (manual or provider)" [label="no"];
    "Reviews clean?" -> "compozy archive" [label="yes"];
}

For a detailed step-by-step walkthrough of each phase, read references/workflow-guide.md.

CLI Commands Quick Reference

Common flags shared by tasks run, exec, and reviews fix: --ide, --model, --reasoning-effort, --add-dir, --auto-commit, --dry-run.

For complete flag documentation, read references/cli-reference.md.

Core Skills Summary

Optional Extension Skills

For detailed skill descriptions and inputs/outputs, read references/skills-reference.md.

Artifact Directory Structure

.compozy/
  config.toml                          # Workspace configuration
  tasks/
    <slug>/                            # One directory per workflow
      _idea.md                         # Idea spec (from cy-idea-factory)
      _prd.md                          # Product Requirements Document
      _user_stories.md                 # User-story catalog (companion to the PRD)
      _techspec.md                     # Technical Specification
      _tests.md                        # Test contract (companion to the TechSpec)
      _tasks.md                        # Task graph manifest
      task_01.md ... task_N.md         # Individual task files
      adrs/
        adr-001.md ... adr-NNN.md      # Architecture Decision Records
      reviews-NNN/
        issue_001.md ... issue_N.md    # Review issues with round metadata in frontmatter
      memory/
        MEMORY.md                      # Shared workflow memory
        task_01.md ... task_N.md       # Per-task memory
    _archived/
      <timestamp>-<slug>/             # Archived completed workflows
  agents/
    <name>/                            # Workspace-scoped reusable agents
      AGENT.md                         # Agent definition
      mcp.json                         # Optional MCP server config
  extensions/                          # Workspace-scoped extensions

Global paths:

• ~/.compozy/agents/<name>/ -- global reusable agents (workspace overrides global)
• ~/.compozy/extensions/ -- user-scoped extensions
• ~/.compozy/runs/<run-id>/ -- daemon-managed run artifacts and persisted exec sessions
• ~/.compozy/global.db -- daemon workspace, workflow, task, and review catalog

Configuration

Workspace defaults live in .compozy/config.toml. CLI flags always override config values.

[defaults]
ide = "claude"
model = "opus"
auto_commit = true
reasoning_effort = "high"
add_dirs = ["../shared-lib"]

[tasks]
types = ["frontend", "backend", "docs", "test", "infra", "refactor", "chore", "bugfix"]

[tasks.run]
include_completed = false
recursive = false

[fix_reviews]
concurrent = 2
batch_size = 3

[fetch_reviews]
provider = "coderabbit"
nitpicks = false

[exec]
verbose = false
tui = false
persist = false

For all fields, types, and defaults, read references/config-reference.md.

Reusable Agents and the Council Pattern

Reusable agents are standalone personas that can be invoked via compozy exec --agent <name> or referenced by skills through run_agent.

Discovery order: workspace (.compozy/agents/<name>/) overrides global (~/.compozy/agents/<name>/).

Agent definition: Each agent has an AGENT.md with YAML frontmatter (title, description) and optional mcp.json for MCP server configuration.

Council agents shipped by the optional cy-idea-factory extension:

Install flow: compozy ext install --yes compozy/compozy --remote github --ref <tag> --subdir extensions/cy-idea-factory -> compozy ext enable cy-idea-factory -> compozy setup.

The cy-idea-factory skill uses these agents in a council debate to challenge feature scope and surface risks.

Management commands: compozy agents list, compozy agents inspect <name>.

Extensions

Executable plugins that extend Compozy at runtime via JSON-RPC 2.0 on stdin/stdout.

• Three scopes: bundled (shipped with Compozy), user (~/.compozy/extensions/), workspace (.compozy/extensions/). Workspace overrides user overrides bundled.
• Disabled by default. Enable explicitly with compozy ext enable <name> or --extensions flag on exec.
• Capabilities: lifecycle observation, prompt decoration, plan injection, agent session modification, review provider registration.
• SDKs: TypeScript (@compozy/extension-sdk), Go (sdk/extension).
• Scaffolding: npx @compozy/create-extension generates extension boilerplate.

Management: compozy ext list, compozy ext inspect <name>, compozy ext install <source>, compozy ext uninstall <name>, compozy ext enable/disable <name>, compozy ext doctor.

Common Patterns

• Run compozy setup before starting any workflow to ensure core skills and enabled extension assets are installed.
• Follow the pipeline in order: idea (optional) -> PRD -> TechSpec -> Tasks -> Execution -> Review -> Fix.
• Configure workspace defaults in .compozy/config.toml to reduce repetitive CLI flags.
• Run compozy tasks validate --name <slug> before compozy tasks run to catch metadata issues early.
• Use compozy archive to clean up fully completed workflows and keep the tasks directory focused.
• Use compozy exec --agent <name> for ad hoc prompts with a specific advisor perspective.
• Use compozy exec --persist to save session artifacts for later resumption with --run-id.

Anti-Patterns

• Skipping pipeline stages. Running compozy tasks run without a PRD and task files produces poor results.
• Invoking cy-execute-task directly. Use compozy tasks run, which handles dispatch, sequencing, memory, and tracking.
• Mixing workflow skills out of order. Running /cy-create-tasks without a PRD and TechSpec leads to shallow task decomposition.
• Editing task file frontmatter manually. Use compozy migrate or compozy tasks validate to fix metadata issues programmatically.
• Confusing skills with CLI commands. Skills (slash commands like /cy-create-prd) run inside an agent session. CLI commands (compozy tasks run) run in the terminal.
• Skipping verification. Always use cy-final-verify before claiming task completion or creating commits.