compozy

AGH runtime and contribution guide. Use for sessions, agents, native tools, skills, memory, network, tasks, capabilities, bundles, QA, docs, and repo work. Do not use for unrelated projects.

Auto Review closeout. Codex review is the default when no engine is set and is the recommended reviewer.

Drives end-to-end execution of a Compozy techspec across many agent restarts by detecting the current phase from state.yaml plus .compozy/tasks/<slug>/, then activating the correct cy-* skill chain or the Compozy -> Claude Opus delegation lane for one iteration before stopping. Each Phase B iteration ends with an atomic checkpoint commit so every completed task or slice becomes a restorable git snapshot. Use when running a Compozy techspec under the codex-loop-plugin in goal mode, or when manually iterating through tasks, qa-report, and qa-execution with persistent memory and state. Do not use for one-off tasks without a .compozy/tasks/<slug>/ directory, for techspec authoring (use cy-create-techspec), or for any work that does not require iteration tracking across agent restarts.

Runs an optional cross-LLM peer review of an implemented change via compozy exec --ide claude --model opus --reasoning-effort xhigh and requires the reviewer to write a scoped Markdown findings artifact for user-directed remediation. Use after any implementation pass (feature, bug fix, refactor) when the user explicitly asks for an external Opus review of the diff before commit or PR. Do not use for TechSpec review (use cy-spec-peer-review), automatic remediation, batched provider review fetching (use cy-fix-reviews), manual self-review without an external LLM (use cy-review-round), or auto-looped review cycles.

Runs an optional cross-LLM peer review of a TechSpec via compozy exec --ide claude --model opus --reasoning-effort xhigh and requires the reviewer to write a scoped Markdown findings artifact for user-directed incorporation. Use when a TechSpec draft has already been approved by the user and they want an external review round, especially for autonomy/network/memory-impacting designs. Do not use for PRDs, automatic approval gates, code review batches, or auto-looped review cycles.

Executes real-user QA sessions through public interfaces using personas, journeys, exploratory charters, test tours, edge-case probes, CFR checks, and browser evidence. Reads qa-report artifacts from <qa-output-path>/qa/ when present, captures issues/screenshots/reports under the same output tree, and classifies bugs by user impact. Use when validating a release candidate, migration, refactor, or user-facing change against production-like behavior. Do not use for AI implementation audits, task-status reconciliation, CI gate runs, integration/security/performance templates, or flaky-test triage; use agent-output-audit for those.

Audits Go functions with multi-step setup or teardown for cleanup discipline on every error return: cancel any context created or extended, close every opened resource, release every claim or lease, stop every spawned subprocess, drain every HTTP body. Forbids http.DefaultClient in production code paths. Use when editing functions in internal/acp, internal/session, internal/scheduler, internal/coordinator, internal/extension, internal/automation, internal/store, internal/memory, internal/api, or any subprocess or registry handler. Do not use for read-only helpers, pure data structures, or tests.

Enforces AGH Go code style and concurrency patterns before writing or editing any production Go file: error wrapping with %w, errors.Is/As only (no strings.Contains on err.Error), no underscore-discarded errors, slog over log/fmt, context.Context as first arg, compile-time interface assertions, no hardcoded config, CLI flag presence detection, whitespace normalization at CLI boundary, no comments restating WHAT, goroutine ownership and shutdown via context, no fire-and-forget, no time.Sleep in orchestration. Use whenever creating or modifying any *.go file under cmd/ or internal/ that is not a test file. Do not use for *_test.go (use agh-test-conventions), schema migrations (use agh-schema-migration), or contract changes (use agh-contract-codegen-coship).

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.

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.

Runs an optional cross-LLM peer review of an implemented change via compozy exec --ide claude --model opus --reasoning-effort xhigh and packages findings for user-directed remediation. Use after any implementation pass (feature, bug fix, refactor) when the user explicitly asks for an external Opus review of the diff before commit or PR. Do not use for TechSpec review (use cy-spec-peer-review), automatic remediation, batched provider review fetching (use cy-fix-reviews), manual self-review without an external LLM (use cy-review-round), or auto-looped review cycles.

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.

Creates a Product Requirements Document through interactive brainstorming with parallel codebase and web research. Use when starting a new feature or product, building a PRD, or brainstorming requirements. Do not use for technical specifications, task breakdowns, or code implementation.

Decomposes PRDs and TechSpecs into detailed, independently implementable task files with enrichment from codebase exploration. Use when a PRD or TechSpec exists and needs to be broken down into executable tasks, or when task files need enrichment with implementation context. Do not use for PRD creation, TechSpec generation, or direct task execution.

Creates a Technical Specification by translating PRD business requirements into implementation designs through interactive technical clarification. Use when a PRD exists and needs a technical plan, or when technical architecture decisions need documentation. Do not use for PRD creation, task breakdown, or direct code implementation.

Enforces fresh verification evidence before any completion, fix, or passing claim, and before commits or PR creation. Use when an agent is about to report success, hand off work, or commit code. Do not use for early planning, brainstorming, or tasks that have not yet reached a concrete verification step.

Create comprehensive technical specs for SDK gaps, feature modules, or system centralization efforts. Use when writing specs, PRDs, gap analysis documents, or planning centralization of scattered functionality into a single module. Triggers on "create spec", "write spec", "gap spec", "centralize", "fill the gap".

Adversarial code review using the opposite model. Spawns 1–3 reviewers on the opposing model (Claude spawns Codex, Codex spawns Claude) to challenge work from distinct critical lenses. Triggers: "adversarial review".

Perform comprehensive research and analysis using multiple discovery and analysis tools to provide a solid foundation for complex tasks.

Discover and understand project rules, coding standards, and architectural guidelines before starting a task. Use when you need to know the constraints, patterns, or compliance requirements for a feature, file, or technology.

Intelligently handle git rebase operations and resolve merge conflicts while preserving features and maintaining code quality. Use when rebasing feature branches, resolving conflicts across commits, and ensuring clean linear history without losing changes.

Enforce root-cause fixes over workarounds, hacks, and symptom patches in all software engineering tasks. Use when debugging issues, fixing bugs, resolving test failures, planning solutions, making architectural decisions, or reviewing code changes. Activates gate functions that detect and reject common workaround patterns such as type assertions, lint suppressions, error swallowing, timing hacks, and monkey patches. Don't use for trivial formatting changes or documentation-only edits.

Use when asking about Rust code style or best practices. Keywords: naming, formatting, comment, clippy, rustfmt, lint, code style, best practice, P.NAM, G.FMT, code review, naming convention, variable naming, function naming, type naming, 命名规范, 代码风格, 格式化, 最佳实践, 代码审查, 怎么命名

Search external libraries and frameworks using Sourcebot MCP. Use when researching external code patterns, library APIs, framework examples, or documentation from repositories like Effect-TS/effect, vercel/ai, tanstack/query. NEVER use for local project code.

Decomposes PRDs and TechSpecs into detailed, independently implementable task files with enrichment from codebase exploration. Use when a PRD or TechSpec exists and needs to be broken down into executable tasks, or when task files need enrichment with implementation context. Do not use for PRD creation, TechSpec generation, or direct task execution.

Executes provider-agnostic PR review remediation using existing review round files under .compozy/tasks/<name>/reviews-NNN/. Use when resolving batched review issues, updating issue markdown files, implementing fixes, and verifying the result. Do not use for PRD task execution, review export/fetch, or generic coding tasks without review issue files.

Expands a raw idea into a structured, research-backed spec in .compozy/tasks/<slug>/_idea.md through interactive brainstorming, web research, business analysis, and multi-advisor debate. Use when the user has a feature idea and wants to explore and structure it before creating a PRD. Do not use for PRD creation, technical specifications, task breakdown, or code implementation.

Performs a comprehensive code review of a PRD implementation and generates a review round directory with issue files compatible with cy-fix-reviews. Use when reviewing implemented PRD tasks, creating a manual review round without an external provider, or performing a quality audit of code changes. Do not use for fetching reviews from external providers, fixing existing review issues, executing PRD tasks, or editing source code.

Explains how to use skeeper to keep spec artifacts (SPEC.md, ADRs, RFCs, plan/PRD/TechSpec markdown, custom globs) next to the code they describe without polluting main-repo history. Covers strict hooks, the tracked skeeper.lock file, namespaces, Git-like status/pull/push/sync/restore workflows, track/untrack, repair, SKEEPER_SKIP, and the GitHub Action. Use when setting up skeeper, configuring a sidecar, syncing or checking a lockfile, recovering drift or failed syncs, auditing bypasses, or wiring CI. Do not use for general Git hook questions, repos with no .skeeper.yml and no intent to add one, or editing skeeper internals.

Runs an optional cross-LLM peer review of a TechSpec via compozy exec --ide claude --model opus --reasoning-effort xhigh and packages findings for user-directed incorporation. Use when a TechSpec draft has already been approved by the user and they want an external review round, especially for autonomy/network/memory-impacting designs. Do not use for PRDs, automatic approval gates, code review batches, or auto-looped review cycles.

Find and fix concurrency bugs - deadlocks, races, livelocks, await-holding-lock, database locks, LD_PRELOAD init, swarm races. Use when processes hang, tests flake, or auditing concurrency.

Free AI search via Exa MCP. Web search for news/info, code search for docs/examples from GitHub/StackOverflow, company research for business intel. No API key needed.

Executes full-project QA like a real user by discovering the repository verification and E2E contracts, running build, lint, test, and startup commands, exercising core workflows end-to-end through CLI, HTTP, and browser interfaces, requiring automated regression coverage for supported critical flows, fixing root-cause regressions, and rerunning the full gate. Uses the agent-browser companion skill for Web UI validation when a web surface exists. Use when validating a branch, release candidate, migration, refactor, or risky commit. Do not use for static code review only, one-off unit test edits, planning test cases, or architecture brainstorming without execution — use qa-report for planning and documentation.

Install or refresh the CC Loop runtime for structured [[CC_LOOP ...]] activation with min="...", rounds="...", or goal="...". Use only for cc-loop setup, status, uninstall, or activation guidance.

Comprehensive skill for the `kb` CLI and the Karpathy Knowledge Base pattern. Covers the full KB lifecycle — topic scaffolding, multi-source ingestion (URLs, files, YouTube, bookmarks, codebases), wiki article compilation, cross-article querying with file-back, lint-and-heal passes, QMD indexing, and hybrid search. Also covers codebase-specific analysis via inspect commands for complexity, coupling, blast radius, dead code, circular dependencies, symbol/file lookups, backlinks, and code smells. Use when working with kb CLI commands, knowledge base workflows, code vault generation, code graph analysis, code metrics inspection, wiki compilation, or the ingest-compile-query-lint cycle. Do not use for general code review, linting, formatting, building Go projects, or writing application code.

Executes full-project QA like a real user by discovering the repository verification contract, running build, lint, test, and startup commands, exercising core workflows end-to-end, creating realistic fixtures when needed, fixing root-cause regressions, and rerunning the full gate. Use when validating a branch, release candidate, migration, refactor, or risky commit. Do not use for static code review only, one-off unit test edits, or architecture brainstorming without execution.

Dispatches scoped-write explorer subagents in parallel for general research and exploration of any codebase, topic, or domain. The operator passes --path (output directory), --agents (parallel count), and --prompt (research question). The parent scouts the territory first to divide work, dispatches N explorer subagents that each write one analysis file at <path>/analysis/NN_analysis_<slug>.md following a seven-section schema, then synthesizes <path>/analysis/summary.md. The skill self-contains the explorer subagent definition and prompts the operator to install it at .claude/agents/explorer.md when absent. Use when running parallel multi-area research that must produce written artifacts. Do not use for competitor-only research already covered by cy-research-competitors, single-file lookups answerable by Explore, or edits to existing code.

Guides Codex Loop setup and long-running tracked execution by installing or refreshing the runtime, explaining activation headers, bootstrapping durable tracking artifacts, decomposing broad requests into tasks, and maintaining per-iteration memory and state. Use for Codex Loop installation, status, activation, or tracked restart-safe implementation, QA, review, and remediation loops. Do not use for one-off coding tasks that do not need Codex Loop or persistent tracking.

Authors and structures professional-grade agent skills following the agentskills.io spec. Use when creating new skill directories, drafting procedural instructions, or optimizing metadata for discoverability. Don't use for general documentation, non-agentic library code, or README files.

Guides adoption and day-to-day use of the pr-release CLI in a consuming GitHub repository: installing the binary, wiring the release GitHub Actions workflow, authoring .pr-release.yaml, following conventional commits for semantic versioning, adding custom release notes with add-note, validating with dry-run, and understanding the release-PR then merge then production-release lifecycle. Use when a project depends on compozy/releasepr (pr-release) and needs to configure, run, or troubleshoot its release automation. Not for editing the pr-release Go source itself, and not a general changelog or semantic-versioning tutorial.