Compozy

Orchestrate AI coding agents from idea to shipped code — in a single pipeline.

One CLI to replace scattered prompts, manual task tracking, and copy-paste review cycles. Compozy drives the full lifecycle of AI-assisted development: product ideation, technical specification, task breakdown with codebase-informed enrichment, concurrent execution across agents, and automated PR review remediation.

✨ Highlights

• One command, 40+ agents. Install bundled skills into Claude Code, Codex, Cursor, Droid, OpenCode, Pi, and 40+ other agents and editors with compozy setup — no npm, pipx, or external tools required.
• Idea to code in 5 steps. Structured pipeline: PRD → TechSpec → Tasks → Execution → Review. Each phase produces plain markdown artifacts that feed into the next.
• Codebase-aware enrichment. Tasks aren't generic prompts. Compozy spawns parallel agents to explore your codebase, discover patterns, and ground every task in real project context.
• Multi-agent execution. Run tasks through Claude Code, Codex, Cursor, Droid, OpenCode, or Pi — just change --ide. Concurrent batch processing with configurable timeouts, retries, and exponential backoff, all with a live terminal UI.
• Workflow memory between runs. Agents inherit context from every previous task — decisions, learnings, errors, and handoffs. Two-tier markdown memory with automatic compaction keeps context fresh without manual bookkeeping.
• Provider-agnostic reviews. Fetch review comments from CodeRabbit, GitHub, or run AI-powered reviews internally. All normalize to the same format. Provider threads resolve automatically after fixes.
• Markdown everywhere. PRDs, specs, tasks, reviews, and ADRs are human-readable markdown files. Version-controlled, diffable, editable between steps. No vendor lock-in.
• Frontmatter for machine-readable metadata. Tasks and review issues keep parseable metadata in standard YAML frontmatter instead of custom XML tags.
• Single binary, local-first. Compiles to one Go binary with zero runtime dependencies. Your code and data stay on your machine.
• Embeddable. Use as a standalone CLI or import as a Go package into your own tools.

📦 Installation

Homebrew

brew tap compozy/compozy
brew install --cask compozy

NPM

npm install -g @compozy/cli

Go

go install github.com/compozy/compozy/cmd/compozy@latest

From Source

git clone git@github.com:compozy/compozy.git
cd compozy && make verify && go build ./cmd/compozy

Then install bundled skills into your AI agents:

compozy setup          # interactive — pick agents and skills
compozy setup --all    # install everything to every detected agent

🔄 How It Works

compozy setup                           Install skills (once per project)
   │
   ▼
/cy-create-prd user-auth               .compozy/tasks/user-auth/_prd.md
   │                                    + Architecture Decision Records
   ▼
/cy-create-techspec user-auth          .compozy/tasks/user-auth/_techspec.md
   │
   ▼
/cy-create-tasks user-auth             .compozy/tasks/user-auth/task_01.md … task_N.md
   │
   ▼
compozy sync --name user-auth          Refresh task workflow _meta.md
   │
   ▼
compozy start --name user-auth         AI agents execute each task
   │                                    ↕ .compozy/tasks/user-auth/memory/
   │
   ▼
compozy fetch-reviews / /cy-review-round  .compozy/tasks/user-auth/reviews-001/
   │
   ▼
compozy fix-reviews --name user-auth   Issues triaged, fixed, resolved
   │
   ▼
Repeat until clean → Ship

Every artifact is a plain markdown file in .compozy/tasks/<name>/. You can read, edit, or version-control any of them between steps.

Task and review issue files use YAML frontmatter for parseable metadata such as status, domain, severity, and provider_ref. Task workflow _meta.md files can be refreshed explicitly with compozy sync. If you have an older project with XML-tagged artifacts, run compozy migrate once before using start or fix-reviews.

🚀 Quick Start

This walkthrough builds a feature called user-auth from idea to shipped code.

1. Install skills

compozy setup --all --yes

Auto-detects installed agents and copies (or symlinks) skills into their configuration directories.

2. Create a PRD

Inside your AI agent (Claude Code, Codex, Cursor, OpenCode, Pi, etc.):

/cy-create-prd user-auth

Interactive brainstorming session — asks clarifying questions, spawns parallel agents to research your codebase and the web, produces a business-focused PRD with ADRs.

3. Create a TechSpec

/cy-create-techspec user-auth

Reads your PRD, explores the codebase architecture, asks technical clarification questions. Produces architecture specs, API designs, and data models.

4. Break down into tasks

/cy-create-tasks user-auth

Analyzes both documents, explores your codebase for relevant files and patterns, produces individually executable task files with status tracking, context, and acceptance criteria.

5. Execute tasks

compozy start --name user-auth --ide claude

Each pending task is processed sequentially — the agent reads the spec, implements the code, validates it, and updates the task status. Use --dry-run to preview prompts without executing.

6. Review

Option A — AI-powered review inside your agent:

/cy-review-round user-auth

Option B — Fetch from an external provider:

compozy fetch-reviews --provider coderabbit --pr 42 --name user-auth

Both produce the same output: .compozy/tasks/user-auth/reviews-001/issue_*.md

7. Fix review issues

compozy fix-reviews --name user-auth --ide claude --concurrent 2 --batch-size 3

Agents triage each issue as valid or invalid, implement fixes for valid issues, and update statuses. Provider threads are resolved automatically.

8. Iterate and ship

Repeat steps 6–7. Each cycle creates a new review round (reviews-002/, reviews-003/), preserving full history. When clean — merge and ship.

🧩 Skills

Compozy bundles 8 skills that its workflows depend on. They run inside your AI agent — no context switching to external tools.

Skill	Purpose
cy-create-prd	Interactive brainstorming → Product Requirements Document with ADRs
cy-create-techspec	PRD → Technical Specification with architecture exploration
cy-create-tasks	PRD + TechSpec → Independently implementable task files
cy-execute-task	Executes one task end-to-end: implement, validate, track, commit
cy-workflow-memory	Maintains cross-task context so agents pick up where the last one left off
cy-review-round	Comprehensive code review → structured issue files
cy-fix-reviews	Triage, fix, verify, and resolve review issues
cy-final-verify	Enforces verification evidence before any completion claim

🧠 Workflow Memory

When agents execute tasks, context gets lost between runs — decisions made, errors hit, patterns discovered. Compozy solves this with a two-tier memory system that gives each agent a running history of the workflow.

Every task execution automatically bootstraps two markdown files inside .compozy/tasks/<name>/memory/:

File	Scope	What goes here
MEMORY.md	Cross-task, shared	Architecture decisions, discovered patterns, open risks, handoffs between tasks
task_01.md	Single task	Objective snapshot, files touched, errors hit, what's ready for the next run

How it works:

1. Before a task runs, Compozy creates the memory directory and scaffolds both files with section templates if they don't exist yet.
2. The agent reads both memory files before writing any code — treating them as mandatory context, not optional notes.
3. During execution, the agent keeps task memory current: decisions, learnings, errors, and corrections.
4. Only durable, cross-task context gets promoted to shared memory. Task-local details stay in the task file.
5. Before completion, the agent updates memory with anything that helps the next run start faster.

Automatic compaction. Memory files have soft limits (150 lines / 12 KB for shared, 200 lines / 16 KB per task). When a file exceeds its threshold, Compozy flags it for compaction — the agent trims noise and repetition while preserving active risks, decisions, and handoffs.

No duplication. Memory files don't copy what's already in the repo, git history, PRD, or task specs. They capture only what would otherwise be lost between runs: the why behind decisions, surprising findings, and context that makes the next agent immediately productive.

The cy-workflow-memory skill handles all of this automatically when referenced in task prompts. No manual setup required — just run compozy start and agents inherit context from every previous run.

🤖 Supported Agents

Execution (compozy start, compozy fix-reviews) — 6 agents that can run tasks:

Agent	--ide flag
Claude Code	claude
Codex	codex
Cursor	cursor
Droid	droid
OpenCode	opencode
Pi	pi

Skill installation (compozy setup) — 40+ agents and editors, including Claude Code, Codex, Cursor, Droid, OpenCode, Pi, Gemini CLI, GitHub Copilot, Windsurf, Amp, Continue, Goose, Roo Code, Augment, Kiro CLI, Cline, and many more. Run compozy setup to see all detected agents on your system.

When installing to multiple agents, Compozy offers two modes:

• Symlink (default) — One canonical copy with symlinks from each agent directory. All agents stay in sync.
• Copy — Independent copies per agent. Use --copy when symlinks are not supported.

📖 CLI Reference

compozy setup — Install bundled skills for supported agents

compozy setup [flags]

Flag	Default	Description
--agent, -a		Target agent name (repeatable)
--skill, -s		Skill name to install (repeatable)
--global, -g	false	Install to user directory instead of project
--copy	false	Copy files instead of symlinking
--list, -l	false	List bundled skills without installing
--yes, -y	false	Skip confirmation prompts
--all	false	Install all skills to all agents

compozy migrate — Convert legacy XML-tagged artifacts to frontmatter

compozy migrate [flags]

Flag	Default	Description
--root-dir	.compozy/tasks	Workflow root to scan recursively
--name		Restrict migration to one workflow name
--tasks-dir		Restrict migration to one task workflow directory
--reviews-dir		Restrict migration to one review round directory
--dry-run	false	Preview migrations without writing files

compozy sync — Refresh task workflow metadata files

compozy sync [flags]

Flag	Default	Description
--root-dir	.compozy/tasks	Workflow root to scan
--name		Restrict sync to one workflow name
--tasks-dir		Restrict sync to one task workflow directory

compozy start — Execute PRD task files

compozy start [flags]

Running compozy start with no flags opens the interactive form automatically.

Flag	Default	Description
--name		Workflow name (.compozy/tasks/<name>)
--tasks-dir		Path to tasks directory
--ide	codex	Agent: claude, codex, cursor, droid, opencode, pi
--model	(per IDE)	Model override
--reasoning-effort	medium	low, medium, high, xhigh
--timeout	10m	Activity timeout per job
--max-retries	0	Retry failed jobs N times
--retry-backoff-multiplier	1.5	Timeout multiplier per retry
--tail-lines	30	Log lines shown per job in UI
--add-dir		Additional directories to allow (repeatable)
--auto-commit	false	Auto-commit after each task
--include-completed	false	Re-run completed tasks
--dry-run	false	Preview prompts without executing

compozy fetch-reviews — Fetch review comments into a review round

compozy fetch-reviews [flags]

Running compozy fetch-reviews with no flags opens the interactive form automatically.

Flag	Default	Description
--provider		Review provider (coderabbit, etc.)
--pr		Pull request number
--name		Workflow name
--round	0	Round number (auto-increments if omitted)

compozy fix-reviews — Dispatch AI agents to remediate review issues

compozy fix-reviews [flags]

Running compozy fix-reviews with no flags opens the interactive form automatically.

Flag	Default	Description
--name		Workflow name
--round	0	Round number (latest if omitted)
--reviews-dir		Override review directory path
--ide	codex	Agent: claude, codex, cursor, droid, opencode, pi
--model	(per IDE)	Model override
--batch-size	1	Issues per batch
--concurrent	1	Parallel batches
--grouped	false	Generate grouped issue summaries
--include-resolved	false	Re-process resolved issues
--reasoning-effort	medium	low, medium, high, xhigh
--timeout	10m	Activity timeout per job
--max-retries	0	Retry failed jobs N times
--retry-backoff-multiplier	1.5	Timeout multiplier per retry
--tail-lines	30	Log lines shown per job in UI
--add-dir		Additional directories to allow (repeatable)
--auto-commit	false	Auto-commit after each batch
--dry-run	false	Preview prompts without executing

Go Package Usage — Use Compozy as a library in your own tools

// Prepare work without executing
prep, err := compozy.Prepare(context.Background(), compozy.Config{
    Name:     "multi-repo",
    TasksDir: ".compozy/tasks/multi-repo",
    Mode:     compozy.ModePRDTasks,
    DryRun:   true,
})

// Fetch reviews and run remediation
_, _ = compozy.FetchReviews(context.Background(), compozy.Config{
    Name:     "my-feature",
    Provider: "coderabbit",
    PR:       "259",
})

// Preview a legacy artifact migration
_, _ = compozy.Migrate(context.Background(), compozy.MigrationConfig{
    DryRun: true,
})

_ = compozy.Run(context.Background(), compozy.Config{
    Name:            "my-feature",
    Mode:            compozy.ModePRReview,
    IDE:             compozy.IDECodex,
    ReasoningEffort: "medium",
})

// Embed the Cobra command in another CLI
root := command.New()
_ = root.Execute()

Project Layout

cmd/compozy/             CLI entry point
command/                 Public Cobra wrapper for embedding
internal/cli/            Cobra flags, interactive form, CLI glue
internal/core/           Internal facade for preparation and execution
  agent/                 IDE command validation and process construction
  memory/                Workflow memory bootstrapping, inspection, and compaction detection
  model/                 Shared runtime data structures
  plan/                  Input discovery, filtering, grouping, batch prep
  prompt/                Prompt builders emitting runtime context + skill names
  run/                   Execution pipeline, logging, shutdown, Bubble Tea UI
internal/setup/          Bundled skill installer (agent detection, symlink/copy)
internal/version/        Build metadata
skills/                  Bundled installable skills
.compozy/tasks/          Default workflow artifact root (PRDs, TechSpecs, tasks, ADRs, reviews)

🛠️ Development

make verify    # Full pipeline: fmt → lint → test → build
make fmt       # Format code
make lint      # Lint (zero tolerance)
make test      # Tests with race detector
make build     # Compile binary
make deps      # Tidy and verify modules

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

📄 License

MIT