ederfmatos/claude-voice-bridge / .claude/skills/compozy
compozy
VerifiedExplains 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.1 KB |
| references/cli-reference.md | markdown | 9.7 KB |
| references/config-reference.md | markdown | 11.8 KB |
| references/skills-reference.md | markdown | 8.0 KB |
| references/workflow-guide.md | markdown | 8.8 KB |
references/workflow-guide.md
View on GitHub# Workflow Guide
End-to-end walkthrough of the Compozy development pipeline from setup through archive.
## Prerequisites
1. **Install Compozy.** Ensure the `compozy` binary is available in the system PATH.
2. **Run setup.** Execute `compozy setup` to install core skills into target agents plus setup assets from enabled extensions. For a quick start: `compozy setup --all`.
3. **Install optional ideation extension when needed.** To use `/cy-idea-factory`, run `compozy ext install --yes compozy/compozy --remote github --ref <tag> --subdir extensions/cy-idea-factory`, then `compozy ext enable cy-idea-factory`, then `compozy setup` again.
4. **Configure workspace (optional).** Create `.compozy/config.toml` to set default IDE, model, and other preferences. Read `config-reference.md` for all fields.
## Phase 1: Ideation (Optional)
**Skill:** `/cy-idea-factory [feature-idea]`
Use when a raw idea needs structured exploration before committing to a PRD.
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`
1. Invoke `/cy-idea-factory` inside an agent session with the feature idea.
2. Answer 3-6 clarifying questions (one per message, multiple-choice preferred).
3. The skill runs parallel codebase exploration and web research.
4. A business analyst persona evaluates viability with KPIs and scoring.
5. A council debate (3-5 advisors from the extension-shipped council agents) challenges scope and surfaces risks.
6. A product strategist scans for higher-leverage alternatives.
7. Review and approve the draft idea spec.
8. Output: `.compozy/tasks/<slug>/_idea.md` + ADRs.
**Skip when:** The requirements are already well-understood and a PRD can be written directly.
## Phase 2: Requirements
**Skill:** `/cy-create-prd [feature-name-or-idea] [idea-file]`
1. Invoke `/cy-create-prd` with the feature name. If `_idea.md` exists, it is used as primary context.
2. The skill runs parallel codebase and market research.
3. Answer clarifying questions focused on WHAT and WHY (not HOW).
4. The skill decides the product direction and records an ADR for the decision.
5. The PRD is written directly — request any changes afterward.
6. Output: `.compozy/tasks/<slug>/_prd.md` + ADRs.
**Key rule:** The PRD describes user capabilities and business outcomes only. No databases, APIs, frameworks, or architecture.
## Phase 3: Technical Design
**Skill:** `/cy-create-techspec [feature-name]`
1. Invoke `/cy-create-techspec` with the feature name.
2. The skill reads the existing `_prd.md` and explores the codebase architecture.
3. Answer technical clarifying questions.
4. Technical ADRs are created for architecture decisions.
5. The TechSpec is written directly — request any changes afterward.
6. Output: `.compozy/tasks/<slug>/_techspec.md` + ADRs.
**Contains:** System architecture, data models, core interfaces, API design, development sequencing.
## Phase 4: Task Decomposition
**Skill:** `/cy-create-tasks [feature-name]`
1. Invoke `/cy-create-tasks` with the feature name.
2. The skill loads the PRD and TechSpec, then breaks them into granular tasks.
3. Review the proposed task breakdown.
4. Task files are generated with YAML frontmatter: `status`, `title`, `type`, `complexity`.
5. `_tasks.md` is generated as the canonical `compozy.tasks/v2` graph manifest with `graph.nodes` and `graph.edges`.
6. Tasks are enriched with codebase patterns and implementation context.
7. Validation runs via `compozy tasks validate`.
8. Output: `task_01.md` through `task_N.md`, `_tasks.md` task graph manifest.
**Task types:** `frontend`, `backend`, `docs`, `test`, `infra`, `refactor`, `chore`, `bugfix`. Custom types can be registered in `.compozy/config.toml` under `[tasks].types`.
## Phase 5: Execution
**Command:** `compozy tasks run <slug> --ide <runtime>`
1. Compozy reads task files from `.compozy/tasks/<slug>/`. Sequential runs use task order; `--parallel-tasks` derives dependency waves from `_tasks.md` graph edges.
2. The CLI auto-starts the home-scoped daemon when needed and starts the run through daemon transport.
3. For each pending task, Compozy constructs a prompt including the task spec, PRD, TechSpec, ADRs, and workflow memory.
4. The configured ACP runtime executes the task using the `cy-execute-task` skill.
5. Each task: read spec -> implement -> validate with `cy-final-verify` -> update tracking -> optional commit.
6. Workflow memory is maintained across tasks via `cy-workflow-memory`.
**Key flags:**
- `--auto-commit` -- create a local commit after each task completes cleanly.
- `--dry-run` -- generate prompts without running the IDE tool.
- `--include-completed` -- re-process tasks already marked as completed.
- `--parallel-tasks` -- execute one workflow by dependency waves from `_tasks.md` graph edges, using isolated worktrees.
- `--parallel` -- with `--multiple`, run multiple workflow slugs concurrently.
- `--parallel-limit <N>` -- with `--multiple --parallel`, bound how many workflow children run at once.
- `--recursive` / `-r` -- discover `task_NNN.md` files in nested subdirectories (e.g., `features/auth/task_01.md`). Root tasks run first, then each subdirectory alphabetically, numerically within. Dot- and underscore-prefixed directories, `reviews-*`, `adrs/`, and `memory/` are skipped.
**Interactive mode:** In interactive terminals, `tasks run` attaches to the TUI by default; use `--ui`, `--stream`, `--detach`, or `--attach` to override that behavior.
## Phase 6: Review
Two paths are available:
### Path A: Manual AI Review
**Skill:** `/cy-review-round [feature-name]`
Invoke inside an agent session. The skill performs a comprehensive code review of the implementation and generates issue files under `.compozy/tasks/<slug>/reviews-NNN/`.
### Path B: External Provider Review
**Command:** `compozy reviews fetch <slug> --provider coderabbit --pr <N>`
Fetches review comments from an external provider (currently CodeRabbit) and writes them as issue markdown files under `reviews-NNN/`.
**Both paths produce:** `issue_*.md` files with YAML frontmatter containing round metadata (`provider`, `pr`, `round`, `round_created_at`) plus issue metadata (`status`, `severity`, `file`, `line`).
## Phase 7: Remediation
**Command:** `compozy reviews fix <slug> --ide <runtime>`
1. Compozy reads issue files from the latest (or specified) review round.
2. For each batch of issues, the configured ACP runtime executes the `cy-fix-reviews` skill.
3. Each issue is triaged (valid/invalid), fixed if valid (in severity order), and verified with `cy-final-verify`.
4. Issue file frontmatter is updated: `pending` -> `valid`/`invalid` -> `resolved`.
**Key flags:**
- `--concurrent <N>` -- process N batches in parallel.
- `--batch-size <N>` -- group N file scopes per batch.
- `--include-resolved` -- re-process already-resolved issues.
**Iterate:** Repeat phases 6-7 until all reviews are clean, then merge.
## Phase 8: Archive
**Command:** `compozy archive --name <slug>`
Moves fully completed workflows from `.compozy/tasks/<slug>/` to `.compozy/tasks/_archived/<timestamp>-<slug>/`.
**Eligibility:** Run `compozy sync` first. Archive eligibility is computed from synced daemon state: all task items must be completed and all synced review issues must be resolved.
## Ad Hoc Execution
**Command:** `compozy exec [prompt]`
Execute a single prompt outside the pipeline workflow.
- **Reusable agents:** `compozy exec --agent council "Evaluate this design"` invokes a named agent.
- **Persistence:** `--persist` saves session artifacts. Resume with `--run-id <id>`.
- **TUI mode:** `--tui` opens an interactive terminal UI.
- **Output formats:** `--format text` (default), `json` (lean JSONL), `raw-json` (full event stream).
## Workflow Memory
The `cy-workflow-memory` skill maintains two tiers of context during task execution:
| File | Purpose |
| --- | --- |
| `.compozy/tasks/<slug>/memory/MEMORY.md` | Shared cross-task memory: architecture decisions, discovered patterns, open risks, handoffs |
| `.compozy/tasks/<slug>/memory/task_NN.md` | Per-task memory: objective snapshot, files touched, errors hit, next steps |
- Memory files are scaffolded before task execution and updated during the run.
- Agents read both files as mandatory context before editing code.
- Promotion from task to shared memory requires: needed by other tasks, durable across runs, and not derivable from existing artifacts.
- Auto-compaction triggers when files exceed size limits.
## Architecture Decision Records
ADRs are created during ideation, PRD, and TechSpec phases to document significant decisions.
- **Location:** `.compozy/tasks/<slug>/adrs/adr-NNN.md` (zero-padded 3-digit numbers).
- **Structure:** Status, Date, Context, Decision, Alternatives Considered, Consequences.
- **Referenced by:** PRDs, TechSpecs, and idea specs include an "Architecture Decision Records" section linking to all ADRs.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |