AGENT SKILL

compozy

Explains Compozy capabilities, CLI commands, core workflow skills, optional extension skills, configuration, artifact structure, reusable agents, and extensions. Use when the user asks how to use Compozy, what commands are available, how the workflow pipeline works, or how to configure a workspace. Do not use for executing workflow steps — use the specific cy- skills instead.

License 许可
MIT
最近更新
2026-07-16
Stars
★ 0
Forks
0

01 前言 Front Matter

name
compozy
description
Explains Compozy capabilities, CLI commands, core workflow skills, optional extension skills, configuration, artifact structure, reusable agents, and extensions. Use when the user asks how to use Compozy, what commands are available, how the workflow pipeline works, or how to configure a workspace. Do not use for executing workflow steps — use the specific cy- skills instead.

02 资源文件 4

03 SKILL.md 正文

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

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

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

Agent Perspective
pragmatic-engineer Execution-focused, delivery speed, maintenance burden
architect-advisor Long-term system coherence, boundaries, coupling
security-advocate Attack vectors, compliance, data protection
product-mind User impact, business value, opportunity cost
devils-advocate Challenges assumptions, surfaces risks, stress-tests
the-thinker Cross-domain patterns, structural reframing

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. The council skill can also orchestrate multi-advisor debates on demand.

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.

04 同仓库更多 Skills

haryelramalho
haryelramalho/skills

to-prompt-opus

Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend/design tasks, or model-specific prompt optimization. Do not use for GPT/OpenAI prompts or raw context packaging without Opus-specific tuning.

★ 0
haryelramalho
haryelramalho/skills

to-prompt-gpt

Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude/Opus prompts or raw context packaging without GPT-specific tuning.

★ 0
haryelramalho
haryelramalho/skills

plan-refactor-qa

Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy/tasks directory, related PRD/TechSpec/ADR/task artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.

★ 0
haryelramalho
haryelramalho/skills

multi-tool-branch-review

Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.

★ 0
haryelramalho
haryelramalho/skills

create-pr-with-template

Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open/create a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.

★ 0
haryelramalho
haryelramalho/skills

ui-craft

Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading/empty/error states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI/TUI design, or pure documentation editing.

★ 0