convez.ai
SkillProdutividadeAvançado
zaytsevand

Chorus — Suite de Revisão Multi-Assessor

zaytsevand/chorus

Revisão adversarial estruturada com 10 personas especializadas para specs e código

Ver no GitHub
BomPluginScore · de 0 a 100

Skill para Claude Code que executa revisão estruturada e multi-perspectiva de specs, designs e código usando dez personas especializadas (DDD, arquitetura, produto, design, clean code, TDD, DevOps, segurança, Theory of Constraints e estratégia de testes). Oferece três modos: revisão de projeto, ciclo SDLC com gates e desafio de premissas. Gera artefatos markdown duráveis para versionamento.

Instalação

$npx convez-ai zaytsevand/chorus

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 semana
Versão
—
Issues abertas
6
Contribuidores
2

Casos de uso

  • Revisão crítica de especificações e designs antes de implementação
  • Gates de qualidade integrados ao ciclo de vida do agente (plan → tasks → implement)
  • Análise de trade-offs arquiteturais, operacionais e de segurança
  • Validação de premissas e steelman de alternativas em ideias de produto

Veredito

Skill maduro e bem arquitetado para equipes que precisam de revisão rigorosa e documentada. A composição de múltiplas personas especializadas (Evans, Richards, Cooper, Norman, Uncle Bob, Beck, etc.) oferece profundidade real em análise de design e código. Exige disciplina do usuário para aproveitar o máximo valor.

README

A tradução para o português deste README ainda está na fila.

chorus

A Claude Code skill suite that runs a structured multi-advisor review of whatever you point it at — most often a spec or a feature's design, occasionally a full-codebase sweep. Ten persona advisors, each reviewing the target through their lens:

  • Eric Evans — DDD / domain model
  • Mark Richards — architecture & evolvability
  • Alan Cooper — adversarial product
  • Don Norman — human-centred design
  • Uncle Bob — clean code / SOLID
  • Kent Beck — TDD / simple design
  • Delivery-and-Ops — synthesized (Farley · Hightower · Majors)
  • Security-and-Trust — synthesized (Schneier · Shostack · Nather)
  • Goldratt — Eliyahu M. Goldratt (Theory of Constraints; deferral / opportunity cost), modernized by Reinertsen flow economics
  • Test-Strategy — synthesized (Cohn · Fowler & Vocke · Dodds · Rainsberger · Crispin & Gregory); where each risk is checked, at what price, with the test pyramid as one tool among several

An optional Guido (Python) language lens joins only on rounds with Python in scope. Conflicts go to advisor(). Output is a durable markdown artifact you commit; the most recent artifact is the next round's baseline.

The suite — four skills over one substrate

The chorus is packaged as a composable suite of four skills. The shared mechanics, the record tools and the bindings to the outside world live once in a substrate skill; the two review modes compose it by name and never depend on each other, and a tutorial skill teaches both:

  • chorus-core — substrate (not invoked directly). The four-stage gate primitive (skill/chorus-core/GATE-PRIMITIVE.md: extract → uncapped author → real adversarial vote → deterministic tally), the decision primitive (DECISION-PRIMITIVE.md), the exploratory phase (EXPLORATORY-PHASE.md), and the conductor discipline + the single I1–I9 invariant catalog (CONDUCTOR.md). It also documents the reserved seams (extract-stage record, agent-memory layout, two-tier memory model) and the findings→memory contract future skills compose. It holds the record tools: the JSON schema for every chorus record, the zero-dependency validator and renderer every round uses (skill/chorus-core/bin/), with a drift test that fails when they stop matching the canon, and the bindings (BINDINGS.md): what serves each port when a provider is installed.
  • chorus-review — the project-state round: a multi-lens review of a scope you choose (most often a spec or a feature's design; occasionally the whole codebase). Trigger: "spawn the chorus." Output: docs/reviews/YYYY-MM-DD-chorus-review.md.
  • chorus-sdlc — the agent-SDLC lifecycle: three scoped chorus gates over a single feature as it moves through plan → tasks → implement (design review after plan, plan/tasks review after tasks, implementation review after implement). Each gate is RSVP-scoped, capped at five lenses, and blocks the pipeline only on an unresolved 🔴. Trigger: "run the agent-SDLC on feature 0NN." Output: specs/<feature>/agent-sdlc-log.json (rendered to agent-sdlc-log.md). It also exposes chorus challenge — Gate A's premise pass run standalone, grilling a target's premise (problem / necessity-now / framing / load-bearing assumptions) and steelmanning the null or an alternative, on any spec, design note, or raw idea. Same brief, fixed red-team checklist, and substantive honest-null, defined once in skill/chorus-sdlc/SKILL.md (§ Gate A — premise pass); the same pass runs first inside every Gate A. Trigger: "chorus challenge <target>."
  • chorus-learn — a guided, staged tutorial: setup (the per-project addendum, which it can scaffold on request from the template it ships at skill/chorus-learn/templates/CHORUS-PROJECT.template.md) and both review modes. Trigger: "chorus learn."

Both modes run the same gate primitive from chorus-core, so they cannot drift. Each sibling declares REQUIRED: chorus-core and carries a sibling-side guard that fails loudly if the substrate is absent. The rest of this README describes the project-state round (chorus-review).

Composition

The chorus skills name no outside skill. They declare ports — decision sink, ruling lookup, record validator, record renderer, arbiter, fixed viewpoint, memory recall (skill/chorus-core/CONDUCTOR.md § Ports). chorus-core's own validator and renderer serve the record ports. At the start of each round or gate the conductor runs bin/bindings.mjs, which looks for an installed problem-brief: if one is there, the decision sink, ruling lookup and publishing go to a brief (skill/chorus-core/BINDINGS.md); if not, each port's default applies (ask in chat, rulings kept in the record, advisor(), and so on). The records are the same either way, so installing problem-brief later loses nothing. The round record says which provider served each port. BINDINGS.md is the only file that names a provider.

Earlier releases shipped this layer as a separate coryphaeus skill. It is now part of chorus-core; re-running install.sh removes the old copy.

Why

Two patterns this skill is built to resist:

  • Findings dominated by legacy code. Without an exclusion gate, every review collapses onto the same tech-debt directory and crowds out signal from the actively-developed surface. The skill's Phase-0 scope-exclusion gate prevents this by baking the project's "do not produce findings about these paths" list into every persona brief.
  • Findings without scaffolding. The artifact is a durable baseline; the next round assumes its top-5 either closed or explicitly carried forward. Without that discipline, every chorus re-derives the same blockers.

Two design choices worth knowing about:

  • RSVP per round. Personas self-select into each round based on the since-last-chorus deltas. Quorum is odd (3 or 5) to avoid 2-vs-2 deadlocks. If too few join, the round aborts honestly rather than fake a chorus.
  • Dijkstra-grounded integration layer. The session running the skill is a thin orchestrator with explicit refusals — it routes between personas, the user, and advisor(), but never holds a lens, never adds findings of its own, never substitutes advisor() for cognitive work. See skill/chorus-core/CONDUCTOR.md.
  • Each lens asks its own questions. Every persona file lists its signature questions (SQ-1..SQ-n). The brief passes them verbatim, and the persona answers each one twice, for the project as a whole and for the work under review, in a question ledger on its report. The orchestrator writes no questions for a lens (skill/chorus-core/GATE-PRIMITIVE.md § Stage 2).

Lifecycle of a review

flowchart TD
    Start([User: &quot;spawn the chorus&quot;]) --> P0

    subgraph P0[Phase 0 — Brief]
        direction TB
        P0a[Load CHORUS-PROJECT.md addendum<br/>or interview the user inline]
        P0b[Confirm scope-exclusion list]
        P0c[Confirm roster &amp; security toggle]
        P0a --> P0b --> P0c
    end

    P0 --> P05

    subgraph P05[Phase 0.5 — RSVP]
        direction TB
        P05a[Draft round-context paragraph<br/>commits, specs, infra, incidents since last round]
        P05b[Dispatch all roster personas in parallel<br/>each replies JOIN or ABSTAIN]
        P05a --> P05b
    end

    P05 --> Quorum{Joiners?}
    Quorum -- J &lt; 3 --> Abort([Abort honestly<br/>write -chorus-abstained.md])
    Quorum -- J ≥ 3 --> P07

    subgraph P07[Phase 0.7 — Exploratory phase]
        direction TB
        P07a[Each joiner builds a persisted,<br/>lens-specific understanding — reference-first]
        P07b[Orchestrator: one batched, sessioned<br/>operator interview ≤5 Q/session]
        P07a --> P07b
    end

    P07 --> P1

    subgraph P1[Phase 1 — Round 1]
        direction TB
        P1a[Spawn joiners in parallel<br/>self-contained briefs]
        P1b[Each persona: read artefacts,<br/>chase the why-why-why chain]
        P1c[Evidence gate I8 — every finding<br/>cites file:line or principle tag]
        P1a --> P1b --> P1c
    end

    P1 --> Register[Findings register + consolidation matrix]
    Register --> P2

    subgraph P2[Phase 2 — Cross-evaluation]
        direction TB
        P2a[One Round-2 agent per joiner]
        P2b[Each reacts to others&apos; findings:<br/>sharpen, push back, overreach, retract]
        P2a --> P2b
    end

    P2 --> P3

    subgraph P3[Phase 3 — Conflict reconciliation]
        P3a[Identify Cn conflicts<br/>single advisor call arbitrates]
    end

    P3 --> P4

    subgraph P4[Phase 4 — Ranking]
        P4a[Score on Cost / Value / Convergence<br/>+ Constitutional ROI if governance doc exists<br/>→ top-5]
    end

    P4 --> P5

    subgraph P5[Phase 5 — Sign-off]
        direction TB
        P5a[TL;DR + pre-public-rollout gate<br/>+ next-chorus baseline]
        P5b[advisor sanity pass]
        P5a --> P5b
    end

    P5 --> Artifact[(docs/reviews/&lt;date&gt;-chorus-review.md<br/>commit it)]
    Artifact --> End([Round complete])

    classDef phase fill:#f5f5f5,stroke:#333,stroke-width:1px;
    class P0,P05,P07,P1,P2,P3,P4,P5 phase;

The integration layer (the calling session) is a thin orchestrator. It routes between personas, the user, and advisor(), but never holds a lens, never adds findings of its own, and never substitutes advisor() for cognitive work. The invariants enforcing that — including the I8 evidence gate the diagram references — live in skill/chorus-core/CONDUCTOR.md; the round itself is skill/chorus-review/SKILL.md.

Before Round 1, participating advisors run the exploratory phase: each builds and persists a lens-specific understanding of the target, harvested reference-first over a two-tier memory — the operator-owned CHORUS-PROJECT.md addendum as the authoritative project base, plus thin per-advisor records that may cache from it. Persisted memory is an index of locators, never a finding's evidentiary endpoint — findings re-ground in the live material. The mechanic lives in skill/chorus-core/EXPLORATORY-PHASE.md.

Principles

The chorus is a procedure for surfacing trade-offs. It is not a substitute for the engineering principles a project anchors trade-offs against. Three cross-cutting concerns recur across every lens — they aren't a separate doctrine layered on top of the personas, they're how each persona already reads code through their own vocabulary:

ConcernCooper / Norman read it asEvans reads it asRichards reads it asBeck reads it asUncle Bob reads it asDelivery-and-Ops reads it asSecurity-and-Trust reads it asGoldratt reads it asTest-Strategy reads it as
Interface contractsa promise the user can readPublished Language at a bounded-context boundarythe coupling-type decision at the seammaking the change easy before making the easy changeDependency Inversion at the architectural seamthe surface a smoke test, canary, or rollback gate can assert againstthe trust boundary — what crosses it, who's authoritative, what's enforcedthe hypothesis the work is betting on — the boundary past which a non-constraint may be subordinatedthe seam a contract test pins from both sides, so the pair is proven without booting the pair
Local purity / explicit effectshidden cost shifted onto the usera Domain Event the model refuses to acknowledgeundocumented temporal or content couplinga function that can't be cornered by a unit testSRP and the principle of least astonishment, from two anglesthree failure modes presented as one — blast radius compounds silentlya hidden grant of capability the threat model never accounted fora deferral whose downstream cost is hidden — opportunity cost that must be priced, not burieda check forced up the stack — what a unit test can't corner gets bought with a slow, vague end-to-end one
Behavioural assertionsa promise nobody is keepingan aggregate invariant nobody enforcesthe cheapest fitness functionthe red of red-green-refactora blocker, not a nitthe cheapest signal — the CI gate you can afforda threat-model claim with no test = security theatrea defer/cut claim with no settling experiment — an opinion, not a findinga risk placed at the cheapest check that can honestly catch it

Each persona carries these as their own concerns in their own voice — see the agent files under agents/. Optional language lenses carry the same three concerns in their language's grain — e.g. Guido (Python): an unsigned type-hint contract, a mutable-default side effect, an idiom claim no type or test can pin (agents/guido-python-reviewer.md). When two lenses independently judge a finding under-rated (the PRIORITIZE vote) in a chorus round, it escalates one severity level. Mere agreement at the proposed severity (the CONFIRM vote) counts as convergence for ranking but does not escalate — so popular polish stays polish. (Vote vocabulary PRIORITIZE / CONFIRM / OVER-RATE / NEED_INFO; see skill/chorus-core/GATE-PRIMITIVE.md.)

Projects with stronger or more-specific principles (layer rules, language mandates, infrastructure constraints) declare them in section 4 of skill/chorus-learn/templates/CHORUS-PROJECT.template.md under "Constitutional / governance principles." Phase 4 ranking consumes that list under "Constitutional ROI."

Findings cite either file:line (claims about the project's artefacts) or [principle] (claims grounded in a project-named principle the addendum carries). The I8 evidence gate refuses findings that do neither — see skill/chorus-core/CONDUCTOR.md.

Lens coverage

Which agent owns which axis. Each lens's remit and the seams between lenses are stated once, in skill/chorus-core/ROSTER.md; this matrix scores them. Score per cell: 3 primary remit · 2 secondary strength · 1 incidental · · none. A column with no 3 is an axis no single lens owns — structurally under-represented.

Agent (lens)DomArchCraftTestUXProdPrioDelivObsSecPerfData
Evans — DDD / domain3221·1·····2
Richards — architecture / -ilities1312··111121
Uncle Bob — clean code / SOLID1232········
Kent Beck — TDD / simple design1133·111····
Norman — human-centred UX····321·····
Cooper — adversarial product1···232·····
Delivery-and-Ops — Farley/Hightower/Majors·1·2··233·1·
Security-and-Trust — Schneier/Shostack/Nather·1·1··2113·2
Goldratt — ToC/Reinertsen·111·2321·1·
Test-Strategy — Cohn/Fowler/Dodds/Rainsberger·213··221·1·
Breadth (Σ)71311155914107455
Champion? (any 3)✓✓✓✓✓✓✓✓✓✓——

Axis key: Dom Domain modeling · Arch Architecture & evolvability · Craft Code craft & maintainability · Test Testing & correctness · UX Human / UX & usability · Prod Product value & user goals · Prio Prioritization, deferral & cost · Deliv Delivery & operability · Obs Observability & prod feedback · Sec Security & trust · Perf Performance & efficiency · Data Data integrity & persistence.

Two axes — Performance and Data integrity — have no champion: they are covered only as a side effect of other remits (Richards on performance; Evans and Security-and-Trust on data). If neither of those lenses RSVPs into a round, the axis goes dark. Optional language lenses (e.g. Guido for Python) layer their own grain on top per language and aren't scored here. The live, interactive version of this matrix — heatmap, radar, and per-axis breakdown — is at docs/reviews/2026-06-05-chorus-coverage-map.html.

Requirements

Hard:

  • speckit skills (speckit-plan, speckit-tasks, speckit-implement, …) for chorus-sdlc — its gates interleave with the speckit cycle. chorus-review and chorus-learn do not need them.
  • The advisor() tool — conflict reconciliation (Phase 3) routes disputes to it. Without it the chorus records each conflict, unresolved, for you to rule on.
  • Node 20 or later: every round runs through chorus-core's conductor loop (bin/conduct.mjs), validator and renderer. No npm dependencies. There is no round without Node; install.sh refuses to install below Node 20.

Optional:

  • spec-walkthrough — run headless, its spec-to-code reconciliation digest feeds the review (the fixed viewpoint at chorus-sdlc Gate C).
  • memsearch — recall of past-session context when the round context is drafted; the project's own memory surface works too.
  • problem-brief: the decision sink, ruling store and lookup, and publisher chorus-core routes to when it is installed. Without it each port falls back to its default (questions in chat, answers kept in the record). Install: git clone https://github.com/zaytsevand/problem-brief && cd problem-brief && ./install.sh.

Install

The suite is named chorus. Both channels below deliver the same four skills (chorus-core, chorus-review, chorus-sdlc, chorus-learn, including their subfolders such as the addendum template) and the eleven persona agents. One install covers the whole suite.

Clone + script

git clone https://github.com/zaytsevand/chorus.git
cd chorus
./install.sh

install.sh copies each skill/<name>/ directory into ~/.claude/skills/<name>/ and the persona agents into ~/.claude/agents/. Every file it writes is recorded, with a hash of what it wrote, in ~/.claude/.chorus-install-manifest. Re-running it is safe and is how you upgrade: a file still as installed is updated, a file you edited is reported as "differs, kept" and left alone, and files an earlier version shipped but this one does not are pruned unless you edited them. A copy installed before the manifest existed is recognised as ours when its content matches a version this repository once shipped, and is updated. Files it did not write are left alone. --force overwrites every shipped file. Tests and fixtures (test/, examples/) stay in the repository and are not installed.

Exit status. install.sh refuses Node older than 20 before writing anything. If any shipped file is left as it was (yours, or unrecognised), it lists each path with the fix and exits 1, because the install then mixes two versions. Exit 0 means every shipped file is current.

Its closing message reports the version it installed (also in ~/.claude/skills/chorus-core/VERSION), the Node version, and whether problem-brief is installed, with the command to install it if not. It never installs problem-brief itself. At review time chorus-core looks for problem-brief in the project's .claude/skills, then ${CLAUDE_HOME:-~/.claude}/skills; if you keep skills elsewhere, add those directories to CHORUS_SKILL_PATH (colon-separated).

Upgrading from a release with the separate coryphaeus skill: the installer never removes it. It warns that the retired skill is still installed and still loads, and prints the command to remove it; whether to run it is your choice.

Downgrade by checking out an older commit and re-running ./install.sh. A run log (<stem>.run.json) is replayed only by the version that started it; another version refuses it with exit 8 and says which version to use.

Per-project install — install into one project's .claude/ instead of your global config, by pointing CLAUDE_HOME at it (run from the project root):

CLAUDE_HOME=$PWD/.claude <repo>/install.sh

Plugin

The repo is a Claude Code plugin: the manifest is .claude-plugin/plugin.json (plugin name chorus; check it with claude plugin validate <repo>). Load it from a checkout for a session with:

claude --plugin-dir <repo>

Uninstall

./uninstall.sh                              # global install
CLAUDE_HOME=$PWD/.claude <repo>/uninstall.sh   # per-project install

Removes the files listed in the install manifest that are still as installed, then the manifest. A listed file you edited is reported as "differs, kept" and left alone. Files install.sh skipped (because they already existed) are left alone, as are your per-project addenda and chorus artifacts under docs/reviews/.

Run a round

  1. Set up the project addendum. Say "chorus learn" and accept its scaffold offer, or copy the template yourself:

    cp <repo>/skill/chorus-learn/templates/CHORUS-PROJECT.template.md \
       docs/reviews/CHORUS-PROJECT.md
    
  2. Edit it. Sections 2 (exclusions), 3 (anchor surface), and 5 (project-specific security checklist) are required before the chorus can launch. The skill will interview you inline if the file is missing or incomplete, but a filled-in addendum makes every round faster.

  3. In Claude Code, say:

    spawn the chorus

    The orchestrator will load the addendum, confirm the scope-exclusion list with you, draft the round-context paragraph (deltas since the last round), and run the RSVP gate. Each persona that joins produces a Round 1 report; cross-evaluation, conflict reconciliation via advisor(), ranking, and security follow. The final artifact lands at docs/reviews/YYYY-MM-DD-chorus-review.md. Commit it.

What you get

A markdown artifact structured as:

  • Roster (this round) — joiners, abstainers, why.
  • Findings register — every finding F1, F2, … with severity, lens, target, one-sentence summary.
  • Consolidation matrix — for ranking and scoring.
  • Round briefs — what each round produced as a whole.
  • Phase 3 conflict reconciliation — every Cn, what was disputed, how it was settled.
  • Top-5 ranked recommendations — scored on Cost / Value / Convergence (and Constitutional ROI if your project has a governance doc).
  • Pre-public-rollout gate — any 🔴 blockers tracked as a unit.
  • TL;DR — three sentences at the top.
  • Next-chorus baseline — what the next round should assume closed.

When NOT to use this

  • Single-lens questions — just spawn the relevant persona agent directly.
  • Line-by-line review of a PR diff — use a dedicated code-review tool; the chorus reviews specs and design, not diffs.
  • One-off architecture questions — invoke mark-richards-architect solo.

The chorus is usually pointed at a spec or a feature's design; a full-codebase sweep is the occasional periodic case, not the default. For the full sweep, cadence is typically quarterly or after a major release.

Reporting a problem

Open an issue at https://github.com/zaytsevand/chorus/issues. Include the installed version (cat ~/.claude/skills/chorus-core/VERSION), the full output and exit code of ./install.sh or of the failing conduct command, and, for a round, the run log (docs/reviews/<stem>.run.json) if you can share it.

License

CC BY 4.0. See LICENSE. You may copy, modify, and redistribute these skills, agents, and procedure under the terms of that license, including for commercial use — attribution required per the license text.

Contributing

See CONTRIBUTING.md. Short version: PRs welcome; do not include project-specific examples (paths, hostnames, user names, repo names) in PR'd agent descriptions or skill prose.

Ver o original no GitHub

Bom para

Relacionados