compozy

Files (5)

• SKILL.md
• cli-reference.md · references/
• config-reference.md · references/
• skills-reference.md · references/
• workflow-guide.md · references/

SKILL.md (first lines)

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

```dot
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

| Command | Purpose | Key Flags |
| --- | --- | --- |
| **Setup & Config** | | |
| `compozy setup` | Install core skills and enabled extension assets | `--agent`, `--skill`, `--global`, `--copy`, `--list`, `--all`, `--yes` |
| `compozy upgrade` | Update CLI to latest release | |
| **Workflow Execution** | | |
| `compozy daemon` | Manage the home-scoped daemon lifecycle | `start`, `status`, `stop` |
| `compozy workspaces` | Inspect and manage daemon workspace registrations | `list`, `show`, `register`, `unregister`, `resolve` |
| `compozy tasks run` | Execute PRD task files through the daemon | `--name`, `--multiple`, `--parallel`, `--parallel-limit`, `--parallel-tasks`, `--recursive` / `-r`, `--attach`, `--ui`, `--stream`, `--detach`, `--task-runtime` |
| `compozy exec` | Execute an ad hoc prompt | `--agent`, `--format`, `--prompt-file`, `--tui`, `--persist`, `--run-id` |
| `compozy runs` | Attach, watch, and purge daemon-managed runs | `attach`, `watch`, `purge` |
| **Review** | | |
| `compozy reviews fetch` | Fetch provider review comments | `--provider`, `--pr`, `--name`, `--round` |
| `compozy reviews fix` | Process review issue files | `--name`, `--round`, `--concurrent`, `--batch-size`, `--ide` |
| **Utilities** | | |
| `compozy tasks validate` | Validate task file metadata | `--name`, `--tasks-dir`, `--format` |
| `compozy sync` | Reconcile workflow artifacts into daemon `global.db` | `--name`, `--root-dir`, `--tasks-dir` |
| `compozy archive` | Move daemon-eligible completed workflows to archive | `--name`, `--root-dir`, `--tasks-dir` |
| `compozy migrate` | Convert legacy artifacts to frontmatter | `--name`, `--dry-run`, `--reviews-dir` |
| **Agent Management** | | |
| `compozy agents list` | List resolved reusable agents | |
| `compozy agents inspect` | View agent definition and defaults | `<name>` |
| **Extensions** | | |
| `compozy ext list` | List extensions | |
| `compozy ext inspect` | View extension details | `<name>` |
| `compozy ext install` | Install an extension from a local path or GitHub repo archive | `<source>`, `--remote`, `--ref`, `--subdir` |
| `compozy ext uninstall` | Remove an extension | `<name>` |
| `compozy ext enable/disable` | Toggle extension | `<name>` |
| `compozy ext doctor` | Diagnose extension issues | |

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

| Skill | Trigger | When To Use | Do Not Use For |
| --- | --- | --- | --- |
| `cy-create-prd` | `/cy-create-prd` | Building a Product Requirements Document | TechSpec, task breakdown, coding |
| `cy-create-techspec` | `/cy-create-techspec` | Translating PRD into technical design | PRD creation, task execution |
| `cy-create-tasks` | `/cy-create-tasks` | Decomposing PRD+TechSpec into task files | Execution, review |
| `cy-execute-task` | (internal) | Executing a single PRD task (called by `compozy tasks run`) | Direct invocation, review work |
| `cy-review-round` | `/cy-review-round` | Performing comprehensive code review | Fetching external reviews, fixing |
| `cy-fix-reviews` | (internal) | Remediating review issues (called by `compozy reviews fix`) | Fetching reviews, task execution |
| `cy-final-verify` | `/cy-final-verify` | Enforcing verification before completion claims | Early planning, brainstorming |
| `cy-workflow-memory` | (internal) | Maintaining cross-task workflow memory | PR reviews, user preferences |
| `compozy` | `/compozy` | Learning how to use Compozy | Executing workflow steps |

## Optional Extension Skills

| Skill | Trigger | When To Use | Install Flow |
| --- | --- | --- | --- |
| `cy-idea-factory` | `/cy-idea-factory` | Raw feature idea needs structured exploration before a PRD | `compozy ext install --yes compozy/compozy --remote github --ref <tag> --subdir extensions/cy-idea-factory` -> `compozy ext enable cy-idea-factory` -> `compozy setup` |

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

## Artifact Directory Structure

From haryelramalho/skills, MIT.

More from haryelramalho/skills