compozy

package module
v0.1.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 5, 2026 License: MIT Imports: 2 Imported by: 0

README ΒΆ

Compozy

Orchestrate AI coding agents from idea to shipped code β€” in a single pipeline.

CI Go Reference Go Report Card Release

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.

Compozy Agent Loop

✨ Highlights

  • One command, 40+ agents. Install bundled skills into Claude Code, Codex, Cursor, Droid, OpenCode, Pi, Gemini, and 40+ other agents and editors with compozy setup.
  • Idea to code in a structured pipeline. Optional Issue β†’ PRD β†’ TechSpec β†’ Tasks β†’ Execution β†’ Review. Each phase produces plain markdown artifacts that feed into the next. Start from an issue for full research and debate, or jump straight to PRD if you already have a clear scope.
  • 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 ACP-capable runtimes like Claude Code, Codex, Cursor, Droid, OpenCode, Pi, or Gemini β€” 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

Execution runtimes are separate from skill installation. To run compozy start or compozy fix-reviews, install an ACP-capable runtime or adapter on PATH for the --ide you choose:

Runtime --ide flag Expected ACP command
Claude Agent claude claude-agent-acp
Codex CLI codex codex-acp
Cursor cursor-agent cursor-agent acp
Droid droid droid exec --output-format acp
OpenCode opencode opencode acp
pi ACP pi pi-acp
Gemini CLI gemini gemini --acp

When the direct ACP command is not installed, Compozy can also fall back to supported launchers such as npx @zed-industries/codex-acp when the launcher is available locally.

πŸ”„ How It Works

Compozy workflow from setup to ship with markdown artifacts at each step

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, title, type, severity, and provider_ref. Task workflow _meta.md files can be refreshed explicitly with compozy sync. Fully completed workflows can be moved out of the active task root with compozy archive. If you have an older project with XML-tagged artifacts, run compozy migrate once before using start or fix-reviews.

Task Schema v2

Task files now use the v2 frontmatter shape: status, title, type, complexity, and dependencies. Legacy v1 task-only keys are no longer part of the schema. type must come from the workspace task type registry: either [tasks].types in .compozy/config.toml or the built-in defaults frontend, backend, docs, test, infra, refactor, chore, bugfix.

---
status: pending
title: Add validate-tasks preflight to start
type: backend
complexity: medium
dependencies:
  - task_02
---

Validate task files at any time with compozy validate-tasks --name <feature>. compozy start runs the same preflight automatically; use --skip-validation only when tasks were validated elsewhere, or --force to continue after validation failures in non-interactive runs.

βš™οΈ Workspace Config

Compozy can load project defaults from .compozy/config.toml.

  • The CLI discovers the nearest .compozy/ directory by walking upward from the current working directory.
  • If .compozy/config.toml exists, Compozy loads it once at command startup.
  • Interactive forms for compozy start, compozy fix-reviews, and compozy fetch-reviews are prefilled from the resolved config.
  • Explicit CLI flags always win over config values.

Precedence is:

explicit flags > command section > [defaults] > built-in defaults

Example:

[defaults]
ide = "codex"
model = "gpt-5.4"
reasoning_effort = "medium"
access_mode = "full"
timeout = "10m"
tail_lines = 0
add_dirs = ["../shared"]
auto_commit = false
max_retries = 0
retry_backoff_multiplier = 1.5

[start]
include_completed = false

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

[fix_reviews]
concurrent = 2
batch_size = 3
include_resolved = false

[fetch_reviews]
provider = "coderabbit"

Supported sections:

  • [defaults] for shared execution defaults such as ide, model, reasoning_effort, access_mode, timeout, tail_lines, add_dirs, auto_commit, max_retries, and retry_backoff_multiplier
  • [start] for include_completed
  • [tasks] for the allowed task type list used by cy-create-tasks and compozy validate-tasks
  • [fix_reviews] for concurrent, batch_size, and include_resolved
  • [fetch_reviews] for provider

Notes:

  • .compozy/config.toml is optional. If it is absent, Compozy keeps the current built-in defaults.
  • .compozy/tasks remains the fixed workflow root in this version; the config file does not change the workflow root path.
  • Unknown keys and invalid value types are rejected during config loading.
  • max_retries applies to execution-stage ACP failures and inactivity timeouts for both compozy start and compozy fix-reviews.
  • retry_backoff_multiplier only increases the next attempt timeout; retries restart immediately and do not add a sleep delay.

πŸš€ Quick Start

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

1. Install skills

compozy setup

Auto-detects installed agents and copies (or symlinks) skills into their configuration directories. compozy start and compozy fix-reviews now verify that bundled Compozy skills are installed for the selected agent before running. Missing installs block the run, and outdated installs prompt for refresh in interactive terminals.

2. (Optional) Create an Issue

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

/cy-idea-factory user-auth

Transforms a raw idea into a structured issue spec β€” asks targeted questions, researches market and codebase in parallel, runs business analysis and council debate, suggests high-leverage alternatives, and produces a research-backed issue. Skip this step if you already have a clear feature scope.

3. Create a PRD

/cy-create-prd user-auth

Interactive brainstorming session β€” reads the issue if one exists, asks clarifying questions, spawns parallel agents to research your codebase and the web, produces a business-focused PRD with ADRs.

4. 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.

5. 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. Generated task files use task schema v2 (status, title, type, complexity, dependencies). Validate them any time with compozy validate-tasks --name user-auth.

6. 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. compozy start validates task metadata before execution. Use --skip-validation when validation already ran elsewhere, or --force to continue after validation failures in non-interactive environments.

7. 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

8. 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.

9. Iterate and ship

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

🧩 Skills

Compozy bundles 9 skills that its workflows depend on. They run inside your AI agent β€” no context switching to external tools.

Skill Purpose
cy-idea-factory Raw idea β†’ structured issue spec with market research, business analysis, and council debate
cy-create-prd Issue/idea β†’ 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) β€” ACP-capable runtimes that can run tasks:

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

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 archive β€” Move fully completed workflows into the archive root
compozy archive [flags]
Flag Default Description
--root-dir .compozy/tasks Workflow root to scan
--name Restrict archiving to one workflow name
--tasks-dir Restrict archiving 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. When present, .compozy/config.toml can provide defaults for runtime flags such as --ide, --model, --reasoning-effort, --access-mode, --timeout, --add-dir, and --auto-commit.

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
--access-mode full default or full runtime access policy
--timeout 10m Activity timeout per job
--max-retries 0 Retry execution-stage ACP failures or timeouts N times
--retry-backoff-multiplier 1.5 Multiplier applied to the next timeout after each 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. When present, .compozy/config.toml can provide defaults such as --provider.

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. When present, .compozy/config.toml can provide runtime defaults as well as review workflow defaults such as --concurrent, --batch-size, and --include-resolved.

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
--include-resolved false Re-process resolved issues
--reasoning-effort medium low, medium, high, xhigh
--access-mode full default or full runtime access policy
--timeout 10m Activity timeout per job
--max-retries 0 Retry execution-stage ACP failures or timeouts N times
--retry-backoff-multiplier 1.5 Multiplier applied to the next timeout after each 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/config.toml     Optional workspace defaults for CLI execution
.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

Documentation ΒΆ

Overview ΒΆ

Package compozy provides a reusable API for preparing and executing markdown-driven AI work loops plus a public Cobra wrapper in package command.

Index ΒΆ

Constants ΒΆ

View Source
const (
	// ModePRReview processes PR review issue markdown files.
	ModePRReview = core.ModePRReview
	// ModePRDTasks processes PRD task markdown files.
	ModePRDTasks = core.ModePRDTasks
)
View Source
const (
	// IDECodex runs Codex jobs.
	IDECodex = core.IDECodex
	// IDEClaude runs Claude Code jobs.
	IDEClaude = core.IDEClaude
	// IDEDroid runs Droid jobs.
	IDEDroid = core.IDEDroid
	// IDECursor runs Cursor Agent jobs.
	IDECursor = core.IDECursor
	// IDEOpenCode runs OpenCode jobs.
	IDEOpenCode = core.IDEOpenCode
	// IDEPi runs Pi jobs.
	IDEPi = core.IDEPi
)

Variables ΒΆ

View Source
var ErrNoWork = core.ErrNoWork

ErrNoWork indicates that no unresolved issues or pending PRD tasks were found.

Functions ΒΆ

func Run ΒΆ

func Run(ctx context.Context, cfg Config) error

Run executes compozy end to end for the provided configuration.

Types ΒΆ

type ArchiveConfig ΒΆ added in v0.1.3

type ArchiveConfig = core.ArchiveConfig

ArchiveConfig configures a completed workflow archive run.

type ArchiveResult ΒΆ added in v0.1.3

type ArchiveResult = core.ArchiveResult

ArchiveResult contains the output of a workflow archive run.

func Archive ΒΆ added in v0.1.3

func Archive(ctx context.Context, cfg ArchiveConfig) (*ArchiveResult, error)

Archive moves fully completed workflows into the archive root.

type Config ΒΆ

type Config = core.Config

Config configures compozy preparation and execution.

type FetchResult ΒΆ

type FetchResult = core.FetchResult

FetchResult contains the output of a fetch-reviews operation.

func FetchReviews ΒΆ

func FetchReviews(ctx context.Context, cfg Config) (*FetchResult, error)

FetchReviews fetches provider review comments into a PRD review round.

type IDE ΒΆ

type IDE = core.IDE

IDE identifies the downstream coding tool that compozy should invoke.

type Job ΒΆ

type Job = core.Job

Job is a prepared execution unit with its generated artifacts.

type MigrationConfig ΒΆ

type MigrationConfig = core.MigrationConfig

MigrationConfig configures a repository artifact migration run.

type MigrationResult ΒΆ

type MigrationResult = core.MigrationResult

MigrationResult contains the output of a migration run.

func Migrate ΒΆ

func Migrate(ctx context.Context, cfg MigrationConfig) (*MigrationResult, error)

Migrate converts legacy workflow artifacts to frontmatter.

type Mode ΒΆ

type Mode = core.Mode

Mode identifies the execution flow used by compozy.

type Preparation ΒΆ

type Preparation = core.Preparation

Preparation contains the resolved execution plan for a compozy run.

func Prepare ΒΆ

func Prepare(ctx context.Context, cfg Config) (*Preparation, error)

Prepare resolves inputs, validates the environment, and generates batch artifacts.

type SyncConfig ΒΆ

type SyncConfig = core.SyncConfig

SyncConfig configures a task metadata sync run.

type SyncResult ΒΆ

type SyncResult = core.SyncResult

SyncResult contains the output of a task metadata sync run.

func Sync ΒΆ

func Sync(ctx context.Context, cfg SyncConfig) (*SyncResult, error)

Sync refreshes task workflow metadata files.

Directories ΒΆ

Path Synopsis
cmd
compozy command
Package command exposes compozy as a reusable Cobra command for embedding inside other Go CLIs.
Package command exposes compozy as a reusable Cobra command for embedding inside other Go CLIs.
internal
cli
sdk
go module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL