You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(skills): add unified team-review-fix skill with communication protocols
Replaces the separate review-team + review-fix handoff with a single
persistent-team skill that reviews, debates, and fixes within one session.
Addresses audit findings: debate protocol now executes via architect-as-
teammate, fresh agent spawning eliminated, graceful shutdown sequence added.
New files:
- skills/team-review-fix/SKILL.md — unified review+fix lifecycle
- process/team-communication-protocol.md — reusable message envelope and
findings registry for team-based skills
- process/debate-protocol.md — rewritten to organic broadcast + architect
tiebreaker (no formal rounds)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: process/agent-selection.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Agent Selection & Lenses
2
2
3
-
Shared reference for all skills that dispatch domain agents by file scope (`review-diff`, `review-commit`, `review-team`, `sdlc-tests-create`, `sdlc-plan`, `sdlc-create-agent`, `sdlc-initialize`). Defines which domain agents to dispatch and which analytical lenses they apply. Each skill specifies which lenses are relevant to its context — see the Lenses section.
3
+
Shared reference for all skills that dispatch domain agents by file scope (`review-diff`, `review-commit`, `team-review-fix`, `sdlc-tests-create`, `sdlc-plan`, `sdlc-create-agent`, `sdlc-initialize`). Defines which domain agents to dispatch and which analytical lenses they apply. Each skill specifies which lenses are relevant to its context — see the Lenses section.
4
4
5
5
## Agent Selection
6
6
@@ -84,7 +84,7 @@ Lenses are the perspectives agents apply when analyzing code. Each consuming ski
84
84
85
85
| Skill Context | Applicable Lenses |
86
86
|--------------|-------------------|
87
-
| Code review (`review-commit`, `review-diff`, `review-team`) | All lenses |
87
+
| Code review (`review-commit`, `review-diff`, `team-review-fix`) | All lenses |
88
88
| Test gap analysis (`sdlc-tests-create`) | Coverage, security at boundaries, contract safety, performance, data integrity, standard |
89
89
| Agent/skill creation (`sdlc-create-agent`, `sdlc-initialize`) | Standard only |
Defines how the `review-team` skill resolves conflicting findings between domain agents. Grounded in multi-agent debate research — citations at the end.
3
+
Defines how team-based review skills resolve conflicting findings between domain agents. Grounded in multi-agent debate research — citations at the end.
4
+
5
+
This protocol uses the **organic broadcast + architect tiebreaker** model. There are no formal debate rounds. Reviewers broadcast findings, challenge or agree organically, and the architect breaks ties in real-time. For message format and envelope structure, see `[sdlc-root]/process/team-communication-protocol.md`.
4
6
5
7
## Design Principles
6
8
7
9
1.**Independent review is the primary value driver.** Most gains attributed to debate are actually attributable to ensembling — agents reviewing independently without seeing each other's work (Du et al. 2023, "Should We Be Going MAD?" ICLR Blog 2025).
8
10
2.**Debate resolves conflicts, not consensus.** The goal is not agreement — it's evidence-based resolution of contradictions.
9
-
3.**Fewer rounds is better.** Additional rounds beyond 2-3 decrease performance through conformity pressure and problem drift (FREE-MAD, "Voting or Consensus?" ACL 2025).
10
-
4.**Judge-managed adaptive breaking outperforms fixed rounds.** The lead decides when evidence is sufficient, rather than always running a fixed number of rounds (Liang et al. EMNLP 2024).
11
-
12
-
## Protocol Phases
13
-
14
-
### Phase 1 — Independent Review
15
-
16
-
All teammates review the diff in parallel with **no inter-agent communication**. This preserves confirmation-bias prevention — each agent forms an independent opinion before seeing others' findings.
11
+
3.**Judge-managed adaptive breaking outperforms fixed rounds.** The architect decides when evidence is sufficient, rather than running a fixed number of rounds (Liang et al. EMNLP 2024).
12
+
4.**Organic convergence over structured rounds.** No Round 1/Round 2 structure. Reviewers challenge or agree naturally. The architect breaks ties immediately when they arise. This converges faster and avoids the conformity pressure that accumulates over multiple forced rounds.
17
13
18
-
Each teammate posts findings as task completions with these required fields:
-`evidence` — specific code or guarantee that supports the finding
24
-
-`recommendation` — what should change
14
+
## Review Phase — Broadcast and Converge
25
15
26
-
### Phase 2 — Conflict Detection
16
+
Reviewers work independently but send findings to the architect AND to reviewers whose domain overlaps (direct messages, not broadcast). Claude Code docs warn "broadcast: use sparingly, as costs scale with team size." Direct messages to relevant reviewers + architect avoids inflating every teammate's context with every finding. The architect can broadcast selectively when cross-domain input is needed.
27
17
28
-
The software-architect subagent scans all Phase 1 findings for conflicts:
18
+
When a reviewer finds an issue:
19
+
1. Send the finding (FINDING message) to the architect AND domain-relevant reviewers
20
+
2. Other reviewers who receive the finding can:
21
+
-**CHALLENGE** it with counter-evidence (direct message to finder + architect)
-**Ignore** — outside their domain, no response required
24
+
3. The architect receives every finding and every challenge/agreement
25
+
4. The architect creates a task for the finding via TaskCreate (see `team-communication-protocol.md` for task schema)
29
26
30
-
| Conflict type | Detection rule |
31
-
|---------------|---------------|
32
-
| Contradictory assessment | Same file+line range, opposite conclusions (e.g., "remove this" vs "this is correct") |
33
-
| Severity disagreement | Same issue identified by multiple agents, different severity ratings |
34
-
| Contradictory recommendation | Different agents recommend incompatible changes to the same code |
27
+
This preserves the independent-review value (research: most gains from ensembling, ICLR Blog 2025) while enabling organic conflict resolution.
35
28
36
-
Non-conflicting findings pass through directly to synthesis.
29
+
## Architect as Real-Time Tiebreaker
37
30
38
-
### Phase 3 — Round 1: Targeted Exchange
31
+
When two reviewers disagree (CHALLENGE exchange), the architect reads both positions and breaks the tie immediately:
39
32
40
-
For each detected conflict, the lead creates debate tasks for the conflicting agents:
33
+
| Situation | Architect Action |
34
+
|-----------|-----------------|
35
+
| Evidence clearly favors one side | Resolve in favor of the supported position, cite evidence |
36
+
| Both sides have merit | Merge into a nuanced finding that captures both concerns |
37
+
| Both sides speculative | Classify as INVESTIGATE or DECIDE (user resolves) |
38
+
| Same finding, different severity | Calibrate — use higher severity, note the disagreement |
41
39
42
-
- Each agent receives: the other agent's finding + evidence
43
-
- Each agent posts **one response**: agree, disagree with evidence, or propose compromise
44
-
- Responses must cite specific code, type guarantees, or framework behavior — not general reasoning
40
+
**Research basis:** "Judge-managed adaptive breaking outperforms fixed-round approaches" (Liang et al. EMNLP 2024). The architect's judgment is final for reviewer-reviewer disputes. If the architect is genuinely uncertain — DECIDE classification (user resolves).
45
41
46
-
### Phase 4 — Lead Judgment (Adaptive Break)
42
+
##Anti-Conformity Safeguard
47
43
48
-
The software-architect subagent reads both Round 1 positions for each conflict:
44
+
The architect tracks which reviewers originally held which positions. If a reviewer flips position after seeing a challenge, the architect:
49
45
50
-
-**If evidence clearly resolves the conflict** → mark as resolved, use the supported finding (early termination)
51
-
-**If not resolvable from Round 1 evidence** → formulate a specific question for Round 2, explaining what evidence would resolve it
46
+
1. Notes the flip explicitly
47
+
2. Evaluates whether the original position had merit
48
+
3. If the flip looks like social pressure rather than genuine evidence-based reconsideration, retains the original finding with a note
52
49
53
-
This is the adaptive break point. Research shows judge-managed adaptive breaking outperforms fixed-round approaches (Liang et al. EMNLP 2024).
50
+
**Research:** LLMs exhibit conformity bias — initially correct agents update toward incorrect majorities under social pressure (FREE-MAD, arXiv:2509.11035).
54
51
55
-
### Phase 5 — Round 2: Conditional Rebuttal
52
+
##Deduplication (Architect, Continuous)
56
53
57
-
Only fires for conflicts not resolved in Round 1. For each:
54
+
The architect deduplicates as findings arrive:
58
55
59
-
- Each conflicting agent gets: the lead's specific question + the other agent's Round 1 response
60
-
- Each posts **one response** — no further rounds
56
+
| Situation | Dedup Rule |
57
+
|-----------|-----------|
58
+
| Multiple reviewers find the same issue | Merge into one finding, cite all agents, mark high confidence |
59
+
| Same file+line, different categories | Separate findings — different concerns deserve separate tracking |
60
+
| Overlapping findings with different scopes | Merge if root cause is the same; keep separate if different fixes needed |
5.**"Voting or Consensus? A Study of Multi-LLM Agent Debate Strategies" (2025)** — ACL 2025. Key finding: additional debate rounds beyond 2-3 often decrease performance by causing problem drift or error propagation through conformity pressure. Validates the 2-round maximum.
127
+
5.**"Voting or Consensus? A Study of Multi-LLM Agent Debate Strategies" (2025)** — ACL 2025. Key finding: additional debate rounds beyond 2-3 often decrease performance by causing problem drift or error propagation through conformity pressure.
128
+
129
+
6.**"Can LLM Agents Really Debate?" (2025)** — arXiv:2511.07784. Analyzed actual debate dynamics in multi-agent LLM systems.
130
+
131
+
7.**S2-MAD (2025)** — arXiv:2502.04790. Structured approaches to multi-agent debate with improved convergence properties.
Copy file name to clipboardExpand all lines: process/sdlc_changelog.md
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,36 @@ Each entry contains:
34
34
35
35
---
36
36
37
+
## 2026-04-14: Add Unified Team Review-Fix Skill and Communication Protocols
38
+
39
+
**Origin:** Real-world audit (2026-04-14, Endless Galaxy Studios) exposed critical gaps in the review-team + review-fix workflow: debate protocol never executed, review-fix spawned 17 fresh agents instead of reusing teammates (63% of total token cost), team cleanup failed.
40
+
41
+
**What happened:** The existing review workflow used separate skills (`review-team` for review, `review-fix` for fixes) with subagents — isolated contexts with no inter-agent communication. The handoff between skills lost all team context, forcing fresh agent spawns. The debate protocol existed on paper but was never executed because the architect did solo synthesis instead of mediating real-time debate.
42
+
43
+
**Changes made:**
44
+
45
+
1.**`skills/team-review-fix/SKILL.md`** — New unified skill that reviews any target (commit, diff, files, directory), runs organic debate with an architect mediator, and fixes all findings using persistent teammates. Eliminates fresh agent spawning between review and fix phases. Includes environment gate, flexible target resolution, reviewer/fixer separation, collaborative fix model, verification gate, protocol compliance checklist, and graceful team shutdown.
46
+
47
+
2.**`process/team-communication-protocol.md`** — New process doc defining the inter-agent communication protocol for team skills. Hybrid message envelope format (structured routing fields + natural language body), 9 message types (FINDING, CHALLENGE, FIX_REQUEST, FIX_COMPLETE, REVIEW_REQUEST, CLARIFICATION, STEER, ESCALATION, STATUS), findings registry using built-in task list, fixer-reviewer collaborative protocol, cross-fixer coordination rules, and escalation path. Reusable by future team-based skills.
48
+
49
+
3.**`process/debate-protocol.md`** — Rewritten from formal round-based protocol to organic broadcast + architect tiebreaker model. No formal debate rounds — reviewers broadcast findings, challenge or agree naturally, architect breaks ties in real-time. Includes architect prompt template (prevents audit failure where mediator did solo synthesis), anti-conformity safeguard, continuous deduplication, and convergence criteria. References `team-communication-protocol.md` for message format.
50
+
51
+
4.**`process/agent-selection.md`** — Added `team-review-fix` to the list of consuming skills and lenses applicability table.
52
+
53
+
5.**`skills/review-diff/SKILL.md`** — Updated Integration section: replaced `sdlc-review-team` sibling with `sdlc-team-review-fix`.
54
+
55
+
6.**`skills/review-commit/SKILL.md`** — Updated Integration section: replaced `sdlc-review-team` sibling with `sdlc-team-review-fix`.
56
+
57
+
7.**`skills/review-fix/SKILL.md`** — Updated Integration section: added `sdlc-team-review-fix` as sibling for team-based review-fix with persistent teammates.
58
+
59
+
8.**`skeleton/manifest.json`** — Added `skills/team-review-fix/SKILL.md` to skills, `process/team-communication-protocol.md` to process.
60
+
61
+
9.**`CLAUDE-SDLC.md`** — Added `/sdlc-team-review-fix` command row to SDLC Commands table.
62
+
63
+
**Rationale:** The unified skill addresses all audit findings: persistent teammates eliminate the 63% cost overhead from fresh spawning, the architect-as-teammate model ensures debate actually executes (it can't be skipped when the architect is receiving findings in real-time), collaborative fix eliminates discrete re-review rounds, and explicit shutdown sequence prevents cleanup failures. The communication and debate protocols are extracted as reusable process docs for future team-based skills.
64
+
65
+
---
66
+
37
67
## 2026-04-14: Add Multi-Layer Gradient Template to Brand Asset Skill
38
68
39
69
**Origin:** User feedback during asset spec generation — gradient positions were specified as percentages instead of pixel coordinates.
0 commit comments