Cacophony runs adversarial pull request reviews from prompt-defined agent lenses. One action invocation runs one Markdown prompt, inspects the checked-out pull request with bounded read-only tools, and writes:
- a canonical JSON report;
- a human-readable Markdown report;
- action outputs for verdict, severity, report paths, and agent ID.
The consuming repository owns orchestration. Run multiple prompts as sequential steps, matrix jobs, or separate workflows.
- A GitHub Actions workflow triggered by
pull_requestby default, or apull_request_targetworkflow that follows the documented trusted-base pattern. - An Azure AI Foundry model deployment that supports the Responses API and function tools.
- The project endpoint, such as
https://<resource>.services.ai.azure.com/api/projects/<project>, or an OpenAI-compatible endpoint ending in/openai/v1. - An API key stored as the repository secret
CACOPHONY_AZURE_API_KEY.
Cacophony itself has no runtime package dependencies, install step, build step, or generated distribution bundle.
Every successful Continuous Integration (CI) run for the current main commit
triggers .github/workflows/publish-marketplace.yml. The workflow creates the
next patch release from the stable semantic version in package.json, generates
release notes, and advances the matching floating major and minor tags. It skips
successful runs for stale main commits and reuses an existing release tag when
the same commit is retried.
GitHub does not expose the initial Marketplace enrollment through its API. The repository owner must therefore perform one bootstrap step after the first automated release:
- Open the generated release on GitHub and choose Edit.
- Accept the GitHub Marketplace Developer Agreement if prompted.
- Select Publish this Action to the GitHub Marketplace.
- Choose the Code quality primary category and publish the update.
After that one-time enrollment, each GitHub release created from a successful
main commit updates the existing Marketplace listing automatically. Consumers
can pin an immutable release such as jdylanmc/cacophony@v0.1.0, or follow the
latest compatible release with jdylanmc/cacophony@v0 or
jdylanmc/cacophony@v0.1.
The repository dogfoods Cacophony through its six canonical adversarial
reviewers: Gilfoyle, Solid Snake, GLaDOS, Master Chief, Fletcher, and Delamain.
Their prompts live under .cacophony/agents/, and their workflows run
independently on pull requests.
The built-in dogfood workflows require CACOPHONY_AZURE_API_KEY,
CACOPHONY_AZURE_ENDPOINT, and an endpoint deployment named gpt-5.4-mini
for all six reviewers.
This repository's pull-request dogfood personas are thin
pull_request_target callers of .github/workflows/cacophony-review.yml. For
pull-request review, that reusable worker owns the pinned Cacophony invocation,
authorization, trusted merge-ref checkout, base-prompt check, secret scope, and
artifact upload. Each caller owns its pull_request_target trigger, read-only
permissions, and per-pull-request concurrency. The reusable worker reads
authoritative pull-request metadata from the inherited GitHub event context.
Before checkout, it rejects any other event, allows a same-repository pull
request, and allows a fork only when GitHub's author_association is OWNER,
MEMBER, or COLLABORATOR. It inspects pull-request content without executing
it.
Repository-wide audit does not use that pull-request worker or its thin persona
callers. .github/workflows/repository-audit.yml is a separate,
repository-owned direct-action mode with its own action pin, default-branch
checkout, secret mapping, and per-agent artifacts.
This quick start is the simple mode for pull requests whose branches are in the
same repository. Its first step is an unsupported-mode guard: it fails if a
fork attempts to use this simple workflow, but it does not authorize or review
the fork. All actual fork review uses the trusted-base pull_request_target
pattern in
docs/creating-agents.md, including its author
authorization and concurrency controls. The checked-in
examples/basic directory mirrors this simple mode; it is
not a trusted-base fork-review template. The simple workflow never calls
.github/workflows/cacophony-review.yml; that reusable worker is callable only
from a pull_request_target trusted-base persona workflow and is never a direct
event trigger.
-
In the target repository, open Settings > Secrets and variables > Actions.
-
Create the secret
CACOPHONY_AZURE_API_KEY. -
Create the repository variable
CACOPHONY_AZURE_ENDPOINTwith the Azure AI Foundry project or OpenAI-compatible endpoint. The workflow below declaresdeployment: gpt-5.4-minidirectly; edit that literal to select a different deployment. It also setsrate-limit-retries: 2, meaning two retries after the initial request, for three total attempts. -
Create
.cacophony/agents/reviewer.md:Review this pull request for correctness defects. Focus on behavior changed by the pull request. Report only actionable defects introduced by the change. Cite exact files and lines, explain the impact, and recommend the smallest safe correction. If no defect is supported by evidence, return a passing report with no findings.
-
Create
.github/workflows/cacophony.yml:name: Cacophony on: pull_request: permissions: contents: read jobs: correctness: runs-on: ubuntu-latest steps: - name: Reject fork use of simple mode if: github.event.pull_request.head.repo.full_name != github.repository run: | echo "::error::This same-repository-only workflow does not review forks. Install the documented trusted-base workflow." exit 1 - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 with: fetch-depth: 0 - name: Run correctness review id: review uses: jdylanmc/cacophony@2ab5ef5d3556d52ffddef891305ab1ddfe8b7412 with: prompt-file: .cacophony/agents/reviewer.md endpoint: ${{ vars.CACOPHONY_AZURE_ENDPOINT }} deployment: gpt-5.4-mini rate-limit-retries: 2 fail-on: high env: CACOPHONY_AZURE_API_KEY: ${{ secrets.CACOPHONY_AZURE_API_KEY }} - name: Upload Cacophony report if: always() && steps.review.outcome != 'skipped' uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5 with: name: cacophony-correctness path: .cacophony/out/
-
Open or update a pull request from a branch in the same repository. The workflow produces the
cacophony-correctnessartifact.
These pull-request contracts are mutually exclusive. Repository-wide audit has the separate direct-action contract documented below.
| Mode | Caller wiring | Action environment |
|---|---|---|
Simple same-repository pull_request |
The job invokes jdylanmc/cacophony directly. Do not use secrets.azure-api-key. |
That action step maps CACOPHONY_AZURE_API_KEY: ${{ secrets.CACOPHONY_AZURE_API_KEY }}. |
| Trusted-base persona caller | The job calls .github/workflows/cacophony-review.yml and passes azure-api-key: ${{ secrets.CACOPHONY_AZURE_API_KEY }} under secrets:. Do not put an action env mapping in the caller. |
Only the reusable workflow maps secrets.azure-api-key to CACOPHONY_AZURE_API_KEY on its pinned action step. |
Do not combine the simple direct-action secret mapping with the trusted-base reusable-workflow secret handoff. A trusted-base caller also passes the event reusable-workflow secret handoff. A trusted-base caller must not restate event identity, pull-request coordinates, repository origin, or author association; the reusable worker reads those authoritative values from the inherited GitHub event context.
A prompt is the review lens, not a workflow script. It should describe:
- the risks or quality dimension to examine;
- what evidence is required;
- what should not be reported;
- any repository-specific invariants.
Cacophony adds trusted framework instructions requiring tool-based inspection,
evidence, and a final structured submit_report call. Pull request text and
repository content are explicitly treated as untrusted data.
Earlier workflow steps or jobs can supply analyzer, test, or build output
through the optional multiline evidence-files input. Each entry is a
workspace-relative file that must already exist when Cacophony starts:
with:
evidence-files: |
.cacophony/evidence/codeql.sarif
.cacophony/evidence/unit-tests.junit.xmlCacophony inventories declared evidence in the initial reviewer context and
adds bounded list_evidence, search_evidence, and chunked read_evidence
tools. A file is limited to 10 MB, all declared evidence is limited to 20 MB,
and at most 20 files may be declared. Evidence is read-only and treated as
untrusted analyzer output; prompts should require findings to be corroborated
against repository source and pull request changes.
For evidence produced in another job, upload the files as an artifact, download
them into the checked-out workspace, and pass their resulting paths to
evidence-files. The trusted-base reusable workflow supports this with its
optional evidence-artifact and evidence-files inputs. Gilfoyle demonstrates
the pattern with CodeQL Static Analysis Results Interchange Format (SARIF)
output, while GLaDOS consumes verbose and JUnit unit-test reports. Their
producer jobs have no Azure secret; only the reusable review job receives the
provider key.
Both supported workflow modes load the prompt from the pull request's base
commit, so a pull request cannot weaken its own review instructions and a newly
added prompt begins running only after its setup change is merged. The modes
differ elsewhere: the quick start uses pull_request, rejects forks because
repository secrets are unavailable, and reviews same-repository changes; the
trusted-base pull_request_target pattern authorizes fork authors before its
secret-backed step and inspects the merge ref without executing pull-request
code.
.github/workflows/repository-audit.yml is a separate repository-owned
direct-action workflow with both workflow_dispatch and workflow_call. It
does not call .github/workflows/cacophony-review.yml or use thin persona
callers. It audits the full checked-out commit rather than a pull request diff
and runs the complete shipped example-agent suite sequentially on the same
default-branch SHA to reduce Azure throttling. The full suite is exactly:
- Gilfoyle with
gpt-5.4-mini; - Solid Snake with
gpt-5.4-mini; - GLaDOS with
gpt-5.4-mini. - Master Chief with
gpt-5.4-mini; - Fletcher with
gpt-5.4-mini; - Delamain with
gpt-5.4-mini.
Leave agent-filter empty to run all six. Before the final full suite, dispatch
Fletcher alone to audit every canonical prompt:
gh workflow run repository-audit.yml \
--ref main \
-f agent-filter=fletcher-prompt-conductorTo explicitly dispatch the complete suite:
gh workflow run repository-audit.yml --ref main -f agent-filter=''agent-filter accepts only one of the six canonical slugs. An unknown
non-empty value fails validation before any audit job executes or receives a
secret. The empty value expands to all six matrix entries; an exact slug
expands to only that entry.
The workflow owns its repository-scope security boundary directly: it accepts
only the default branch, performs its own checkout into audit-target, maps its
own declared or repository API-key secret only on the audit action step, runs an
independently pinned Cacophony action implementation, and uploads its own
per-agent artifacts. Reviewer prompts come from that pinned action revision,
not from the audited checkout. The Azure key is never exposed to code from the
commit under audit. Each reviewer receives read and search tools for
working-tree source files; Git metadata and generated dependency directories
such as node_modules are excluded. Any finding severity fails its matrix job,
while fail-fast: false ensures all six reports are uploaded as separate
artifacts. Run it from the Actions tab with Run workflow, or call it from
another workflow in this repository:
jobs:
repository-audit:
uses: ./.github/workflows/repository-audit.yml
with:
agent-filter: "" # Empty runs the complete six-agent suite.
secrets:
azure-api-key: ${{ secrets.CACOPHONY_AZURE_API_KEY }}The manual dispatch reads the repository's existing
CACOPHONY_AZURE_ENDPOINT variable and CACOPHONY_AZURE_API_KEY secret.
Repository audit mode checks out the trusted default-branch commit and executes
only the repository-local read-only agent-selection script before invoking the
independently pinned Cacophony action. It does not execute code from an
untrusted audited checkout or pull-request content.
| Input | Required | Default | Description |
|---|---|---|---|
prompt-file |
Yes | Markdown prompt under .cacophony/. |
|
endpoint |
Yes | Azure AI Foundry project or OpenAI-compatible endpoint. | |
deployment |
Yes | Model deployment name. | |
provider |
No | azure-foundry |
Provider adapter. |
review-scope |
No | pull-request |
pull-request for event review or repository for a full checked-out repository audit. |
workspace-directory |
No | . |
Repository-relative checkout directory to inspect. |
evidence-files |
No | Multiline workspace-relative paths to structured evidence produced before the review. | |
max-turns |
No | 8 |
Model turns, from 1 through 40. Cacophony tells the reviewer its exact and remaining budget, provides request_more_turns to emit a workflow warning when the budget is insufficient, directs finalization during the last three turns, and reserves the final turn for submit_report. |
timeout-seconds |
No | 300 |
Total deadline, including retry waits, from 30 through 1800 seconds. |
rate-limit-retries |
No | 2 |
Retries after the initial HTTP 429 request, from 0 through 10; 2 means three total attempts. |
fail-on |
No | high |
low, medium, high, critical, or never. |
output-directory |
No | .cacophony/out |
Repository-relative report root. |
The action accepts the API key only through the CACOPHONY_AZURE_API_KEY
environment variable. Use the mode-specific table above to determine which
workflow owns that mapping.
| Output | Description |
|---|---|
verdict |
pass, warn, and fail are findings-derived values. inconclusive is a terminal value meaning no reviewer decision completed; it always exits nonzero and should be retried when quota is available. error is the terminal framework-failure value. |
max-severity |
none, low, medium, high, or critical. |
report-json |
Repository-relative JSON report path. |
report-markdown |
Repository-relative Markdown report path. |
agent-id |
ID derived from the prompt filename. |
Reports and outputs are written before findings-based failure is applied. Use
if: always() on artifact upload steps. The complete Markdown report is also
appended to the GitHub job summary, where findings and remediation render
directly without downloading the artifact. Failure annotations include the
agent's submitted summary instead of only a generic severity message.
Completed reviews use pass, warn, or fail, derived from their findings.
fail-on is an inclusive severity threshold for those completed reviews. For
example, high fails on high and critical findings; never prevents
findings from failing the step.
inconclusive is a terminal verdict/output value: the provider did not
complete a reviewer decision. It is neither approval nor a findings-derived
block, and it always fails the step closed regardless of fail-on; retry after
the provider is available. error is the terminal verdict/output value for a
framework failure such as authentication failure, timeout, invalid model
output, or exhausted turn budget and also always fails.
Azure AI Foundry HTTP 429 throttling produces an inconclusive report and a
workflow warning, then fails the step closed after rate-limit-retries is
exhausted. rate-limit-retries: 2 means two retries after the initial request,
for three total attempts. Retry delays use
Azure's retry-after-ms,
x-ms-retry-after-ms, or Retry-After value as the base and multiply it by
2^retryIndex. If Azure provides no delay, the base is one second. The total
timeout-seconds deadline remains the hard ceiling. Inconclusive is not
approval or a findings-based verdict; retry the run after quota is available.
The JSON report is the canonical artifact. Markdown is rendered from it.
{
"schemaVersion": "1.0",
"status": "completed",
"agent": {
"id": "reviewer",
"promptFile": ".cacophony/agents/reviewer.md"
},
"provider": {
"name": "azure-foundry",
"deployment": "review-model"
},
"reviewScope": "pull-request",
"pullRequest": {},
"repository": null,
"startedAt": "2026-08-13T14:00:00.000Z",
"completedAt": "2026-08-13T14:01:00.000Z",
"execution": {
"turns": 2,
"toolCalls": 4
},
"verdict": "fail",
"maxSeverity": "high",
"summary": "One correctness defect was found.",
"findings": [
{
"id": "finding-1",
"severity": "high",
"title": "Incorrect arithmetic",
"explanation": "The changed implementation subtracts instead of adding.",
"recommendation": "Restore addition.",
"evidence": [
{
"path": "src/math.js",
"line": 12,
"detail": "The function returns a - b."
}
]
}
]
}The agent proposes a verdict, but Cacophony derives the canonical report
verdict from validated findings: no findings is pass, low or medium findings
is warn, and high or critical findings is fail.
Terminal reports without a reviewer decision use the same envelope with no findings. An exhausted provider retry budget produces:
{
"schemaVersion": "1.0",
"status": "inconclusive",
"execution": {
"turns": 0,
"toolCalls": 0
},
"verdict": "inconclusive",
"maxSeverity": "none",
"summary": "Azure AI Foundry rate limit exceeded (429); review is inconclusive",
"findings": []
}No reviewer decision exists in that report. inconclusive is nevertheless the
terminal value of the public verdict field. It always fails closed and should
be retried when quota is available. Framework failures use the same empty
findings shape with both status and verdict set to error.
For pull request scope, the agent can use get_pull_request,
list_changed_files, get_diff, read_file, list_files, and search_text.
Repository scope exposes only read_file, list_files, and search_text.
When evidence is declared, either scope also receives list_evidence,
search_evidence, and read_evidence. Neither scope can execute commands or
write repository files.
Each checked-in or copied example declares its selected Azure deployment directly in workflow YAML. Edit that literal when choosing a different model; the examples require only the endpoint variable and API key secret.
For a small sequential workflow, repeat the action step with a different
prompt-file and step ID. For parallel reviews, use a matrix:
strategy:
fail-fast: false
matrix:
include:
- agent: correctness
deployment: gpt-5.4-mini
- agent: security
deployment: gpt-5.4-mini
- agent: maintainability
deployment: gpt-5.4-mini
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
with:
fetch-depth: 0
- id: review
uses: jdylanmc/cacophony@2ab5ef5d3556d52ffddef891305ab1ddfe8b7412
with:
prompt-file: .cacophony/agents/${{ matrix.agent }}.md
endpoint: ${{ vars.CACOPHONY_AZURE_ENDPOINT }}
deployment: ${{ matrix.deployment }}
rate-limit-retries: 2
env:
CACOPHONY_AZURE_API_KEY: ${{ secrets.CACOPHONY_AZURE_API_KEY }}
- if: always()
uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
with:
name: cacophony-${{ matrix.agent }}
path: .cacophony/out/See Creating Cacophony agents for the complete
prompt, workflow, validation, and stacked-rollout process. The repository-shared
create-cacophony-agent skill
walks Copilot through either adding a sample persona here or installing a
reviewer in another repository. Reviewer contracts live only under
.cacophony/agents/.
.cacophony/agents/gilfoyle-security-architect.md
is a persona-driven application security reviewer. It reports only concrete
exploitation paths, requires exact evidence and numbered remediation, and uses
[BLOCK: SECURITY] or [APPROVED] summaries.
This repository dogfoods the reviewer through
.github/workflows/gilfoyle-security-architect.yml. The thin caller declares
gpt-5.4-mini and delegates the shared trusted-base review sequence to
.github/workflows/cacophony-review.yml.
.cacophony/agents/solid-snake-architecture.md
reviews Single Responsibility Principle (SRP), dependency boundaries,
interface segregation, and open/closed extension points without demanding
abstractions for their own sake. Findings use [BLOCK: ARCHITECTURE] and
numbered code-comms extraction steps; clean changes use [APPROVED].
.github/workflows/solid-snake-architecture.yml runs independently from
Gilfoyle on the same pull request event, so GitHub schedules both reviews in
parallel and uploads separate artifacts. Snake's thin caller declares
gpt-5.4-mini; the shared reusable workflow owns the trusted checkout, pinned
action, and base-commit prompt loading.
.cacophony/agents/glados-documentation-sentinel.md
cross-references changed behavior with untouched documentation, examples,
configuration references, names, and inline comments. Supported mismatches use
[BLOCK: TESTING_ANOMALY] with numbered synchronization steps; globally
consistent changes use [APPROVED]. Standalone link and navigation mechanics
belong to Delamain; GLaDOS intervenes only when changed implementation or
configuration moves or removes a documented public entry point and leaves a
factually stale reference.
.github/workflows/glados-documentation-sentinel.yml runs independently from
Gilfoyle and Solid Snake. Once merged, all three reviewers execute in parallel
on subsequent pull requests and upload separate artifacts. Her thin caller
declares gpt-5.4-mini directly.
.cacophony/agents/delamain-documentation-custodian.md
reviews documentation information architecture, progressive disclosure,
heading/list/table structure, Markdown rendering, navigation and discoverability,
links, anchors, and path casing. It requires evidence of a real onboarding or
rendering hazard before proposing a collapsed machine-facing compartment.
Factual implementation and configuration synchronization remains GLaDOS's
exclusive route, including stale references caused by a changed public entry
point. Delamain alone owns standalone broken links, anchors, path casing, and
navigation mechanics. Findings use [BLOCK: SERVICE_DISRUPTION]; an
unobstructed route uses [APPROVED].
.github/workflows/delamain-documentation-custodian.yml is an independent thin
trusted-base caller. It uses gpt-5.4-mini with the standard 20-turn,
600-second budget and delegates authorization, trusted checkout, retry policy,
prompt loading, secret scope, and artifact upload to the shared reusable
workflow.
.cacophony/agents/master-chief-domain-commander.md
reviews Domain-Driven Design (DDD) boundaries, You Aren't Gonna Need It
(YAGNI), Keep It Simple, Stupid (KISS), and Code Complete mechanics. It blocks
only evidence-backed overengineering, opaque control flow, and misplaced domain
rules. Findings use [BLOCK: OVERENGINEERED] with numbered mechanical
remediation orders; mission-essential changes use [APPROVED].
.github/workflows/master-chief-domain-commander.yml is an independent thin
caller, so the persona reviewers run in parallel and upload separate artifacts.
Master Chief declares gpt-5.4-mini with the established 20-turn, 600-second
pull-request budget.
.cacophony/agents/fletcher-prompt-conductor.md
audits Cacophony agent prompts for domain isolation, forceful directives, exact
structured-report contracts, persona preservation, evidence boundaries, and
material token waste. In pull-request scope it reviews only changed prompt
files. In repository-audit scope it reads all six canonical prompts and also
checks domain overlap and cross-prompt ownership. Supported defects use
[BLOCK: PROMPT] with numbered, copy-pasteable corrections; a clean score uses
[APPROVED].
.github/workflows/fletcher-prompt-conductor.yml is a thin trusted-base caller
using gpt-5.4-mini, the standard 20-turn pull-request budget, and the shared
reusable review workflow. Its top-level pull_request_target.paths filter is
exactly .cacophony/agents/**, so GitHub schedules Fletcher only when the pull
request adds, changes, renames, or deletes an agent-prompt path. Code-only and
unrelated pull requests never reach the reusable workflow, model, or secret.
- The simple
pull_requestconsumer pattern must use an always-running job with an unsupported-mode guard that fails fork use before any secret-bearing step. That guard does not authorize or review forks. Never put the only review job behind a same-repository condition because GitHub treats a skipped required job as successful. - A
pull_request_targetpersona caller may review forks only through a trusted-base reusable workflow that owns the pull-request action pin, base-commit prompt, authorization, checkout, secret scope, and artifacts. Each caller owns read-only permissions and per-pull-request concurrency. The reusable workflow rejects non-pull_request_targetevents, accepts same-repository pull requests, and accepts forks only forOWNER,MEMBER, orCOLLABORATORauthor_associationvalues before checkout. It executes no head-controlled code. Code-execution safety does not authorize strangers to spend provider quota. - Repository-wide audit is a distinct repository-owned direct-action mode. Its workflow independently pins the action, checks out only the default branch, scopes the API key to the audit action step, and uploads repository-audit artifacts; it does not route through the pull-request reusable worker.
- Repository secrets are unavailable to
pull_requestworkflows from forks. The quick-start workflow fails those pull requests explicitly rather than silently passing a skipped gate. - Cacophony rejects absolute paths, traversal,
.gitaccess, and symlinks that resolve outside the workspace. - Tool outputs are bounded. There is no arbitrary command tool.
- Keep prompts under review like any other code. They determine what is sent to the configured model endpoint.
- Keep Cacophony pinned to a reviewed full commit SHA. Update the pin through a normal dependency review when adopting a newer release.
- Missing API key, simple mode: verify the secret is named exactly
CACOPHONY_AZURE_API_KEYand the direct Cacophony action step maps it throughenv. Do not usesecrets.azure-api-key. - Missing API key, trusted-base mode: the persona caller must pass
azure-api-key: ${{ secrets.CACOPHONY_AZURE_API_KEY }}undersecrets:. Only the reusable workflow mapssecrets.azure-api-keyto the action'sCACOPHONY_AZURE_API_KEYenvironment variable. - Azure 404: verify the project endpoint and deployment. Cacophony appends
/openai/v1/responsesunless the endpoint already ends in/responses. - Azure 429:
rate-limit-retries: 2means two retries after the initial request, for three total attempts, with header-based exponential backoff withintimeout-seconds. Persistent throttling writes aninconclusivereport and fails the step because no reviewer decision was completed. - Git diff failure: use
actions/checkoutwithfetch-depth: 0. - No report submission: Cacophony announces the remaining turn budget,
directs the reviewer to finalize during the last three turns, and exposes
only
submit_reporton the final turn. If submission still fails, tighten the review lens or reduce the amount of repository context it must traverse. - Reviewer requests more turns:
request_more_turnsemits a GitHub Actions warning containing the requested capacity and reason. It does not extend the current run; use the warning to tune a later run or narrow the review lens. - Fork pull request rejected: the simple workflow fails closed because GitHub does not expose repository secrets to fork workflows. Use the documented trusted-base pattern when fork reviews are required.
- Report exists but step failed: inspect the artifact. Reports are written before severity policy is applied.
When asked to install Cacophony in a repository, perform these steps exactly:
-
Confirm the repository uses GitHub Actions and identify whether it already has a pull request workflow that should be extended.
-
Create
.cacophony/agents/reviewer.mdusing the starter prompt from Quick start unless the user supplied a specific review lens. -
Create or update
.github/workflows/cacophony.ymlusing the Quick start workflow. Preserve unrelated existing workflow behavior. -
Keep
permissions: contents: read, pin Checkout to the documented full commit SHA, andfetch-depth: 0. -
Reference
jdylanmc/cacophony@2ab5ef5d3556d52ffddef891305ab1ddfe8b7412; do not copy Cacophony source into the consumer repository. -
Use the repository variable
CACOPHONY_AZURE_ENDPOINTand declare the reviewer's model deployment directly in its workflow. -
In the default simple workflow, map the repository secret
CACOPHONY_AZURE_API_KEYinto the review step's environment. In a trusted-base thin caller, pass it assecrets.azure-api-keyand let the reusable workflow map it to the action environment. Never place the key in a committed file. -
Add Upload Artifact pinned to the documented full commit SHA with
if: always()and path.cacophony/out/. -
Default to
pull_requestwith an always-running job whose unsupported-mode guard fails fork use before checkout or review. The guard is not a fork authorization path. Usepull_request_targetonly for the documented trusted-base pattern with one repository-owned reusable workflow holding every pull-request review action pin, the base-commit prompt, read-only permissions, authorization before checkout, no execution of head-controlled code, and API-key mapping. Keep persona callers narrow and give each per-pull-request concurrency. Do not apply that caller/worker topology to repository-wide audit, which is a separate repository-owned direct-action workflow with independent pinning, checkout, secret scoping, and artifacts. -
Confirm the workflow passes
rate-limit-retriesexplicitly or relies on the documented default of2, and that exhausted HTTP 429 retries produce aninconclusivereport that fails closed. -
Validate the resulting YAML syntax and report this expected tree:
.cacophony/ agents/ reviewer.md .github/ workflows/ cacophony.yml -
Tell the user to create the secret and variables in repository settings if the current tooling cannot create them securely.
Copy-paste request for a new chat:
Set up Cacophony in this repository. Follow the installation contract at https://github.com/jdylanmc/cacophony#instructions-for-copilot-or-another-coding-agent and use the correctness starter prompt unless this repository already documents a more appropriate review lens.
Node.js 24 is the only prerequisite:
node --test
node --check src/index.jsNo npm install is required.
Use the small report helper to validate model-style submission JSON or render a complete report:
node scripts/report.js validate submission.json
node scripts/report.js render report.json report.mdSee CONTRIBUTING.md for release expectations.