docs: external orchestration frameworks, pr-triage skill, GitHub Actions templates
Added: - guide/third-party-tools.md: External Orchestration Frameworks section (Ruflo + Athena Flow) with architectural distinction from multi-instance tools - examples/skills/pr-triage/: 3-phase PR backlog management skill (audit, deep review via parallel agents, validated comment posting) - examples/github-actions/: claude-code-review.yml + .coderabbit.yaml + prompts/code-review.md — AI-powered PR review GitHub Actions workflow - docs/resource-evaluations/073-athena-flow-workflow-runtime.md (2/5 Watch) - docs/resource-evaluations/074-ruflo-multi-agent-orchestration.md (3/5 Pertinent) Updated: - examples/README.md + examples/github-actions/README.md: new templates indexed - machine-readable/reference.yaml: new entries for github-actions + pr-triage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
18a6e0ce5c
commit
0bdb34b2a4
12 changed files with 1079 additions and 4 deletions
|
|
@ -6,8 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Remote Control §9.22 — bugs iOS documentés et workarounds** (`guide/ultimate-guide.md:20075`) — troubleshooting enrichi suite à tests terrain (iPhone, mars 2026). Bug confirmé : scan QR code ouvre l'app Claude mais la session n'apparaît pas dans la liste (Research Preview, reproductible sur iOS, documenté par MacStories). Deux workarounds fiables ajoutés : (1) `claude.ai/code` dans Safari — session visible directement, (2) URL copiée depuis le terminal et collée dans Safari. Note explicative ajoutée dans la table de troubleshooting avec référence MacStories.
|
||||
|
||||
### Added
|
||||
|
||||
- **`pr-triage` skill** (`examples/skills/pr-triage/`) — 3-phase PR backlog management for maintainers: automated audit of all open PRs (size classification, overlap detection, cluster analysis, staleness, CI status, PR-issue linking), opt-in deep review via parallel `code-reviewer` agents, and validated comment posting with mandatory `AskUserQuestion` gate. Stack-agnostic (Node/TS, Python, Rust, Go checklists included), cross-platform clipboard (pbcopy/xclip/wl-copy/clip.exe), and cross-referenced with `/review-pr` for single-PR use cases.
|
||||
|
||||
- **External Orchestration Frameworks** (`guide/third-party-tools.md`, nouvelle section) — nouvelle catégorie architecturalement distincte des outils multi-instance existants (Gas Town, multiclaude). Distinction documentée : lancer plusieurs instances Claude Code en parallèle vs. remplacer/augmenter la couche d'orchestration interne avec un runtime complet. Deux outils couverts : (1) **Ruflo** (anciennement claude-flow, 18.9k stars) — framework le plus adopté, swarms hiérarchiques queen + workers, 60+ agents spécialisés, Q-Learning router, 42+ skills, 17 hooks, SQLite persistence. Recommandation d'install via `npx ruflo@latest` (pas curl|bash). Claims de performance (84.8% SWE-Bench, 352x WASM) marqués non vérifiés, rebrand en cours documenté. (2) **Athena Flow** — architecture différente (hooks → UDS → NDJSON → runtime Node.js → TUI), intercept les events hooks plutôt que d'augmenter la couche agent. Premier workflow : builder E2E tests Playwright autonome. Statut "Watch — not recommended yet" (projet trop récent, source audit manquant). Évaluations complètes : `docs/resource-evaluations/073-athena-flow-workflow-runtime.md` (2/5 Watch) et `074-ruflo-multi-agent-orchestration.md` (3/5 Pertinent).
|
||||
|
||||
- **For Tech Leads & Engineering Managers** (`guide/learning-with-ai.md`, nouvelle §12) — section dédiée aux tech leads et engineering managers, angle mort identifié via évaluation de ressource (Mathieu Eveillard, "Génération LLM"). Le guide couvrait uniquement la perspective individuelle ; cette section adresse la responsabilité organisationnelle. Contenu : modèle d'onboarding 4 semaines (semaine 1 sans AI pour calibration avant que l'outil masque les lacunes, validé par Create Future 2025 : training structuré → 14-42% → 35-65% time savings), 5 métriques de croissance réelle vs. vélocité, 3 modèles de mentoring scalables (pair rotations, architecture hot seat 15min/semaine, CLAUDE.md collectif), template de politique AI d'équipe pour `CLAUDE.md` partagé, 6 warning signs au niveau équipe avec réponses spécifiques, quick checklist. Nouvelle section "Team & Organizational Research" dans les sources (Create Future 2025, Stanford Digital Economy 2025, LeadDev, Stack Overflow Gen Z). Fichier d'évaluation créé : `docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md`.
|
||||
|
||||
- **Compound Engineering patterns** (`guide/ultimate-guide.md`, 4 insertions) — patterns portables issus du plugin compound-engineering d'Every.to (Kieran Klaassen, prod-tested sur Cora), absents du guide jusqu'ici. (1) **Named Perspective Agents** : distinction entre persona roleplay (anti-pattern, interdit §3.x) et named perspective (DHH = fat models + thin controllers + REST pragmatique condensé en un token), avec caveat sur le drift entre versions de Claude. (2) **Swarm vs Sequential** : tableau comparatif des deux modes de coordination multi-agents, règle de décision (Swarm = indépendant + thoroughness, Teams = dépendances séquentielles). (3) **Skill Quality Gates** : checklist 9 critères content au-delà de la validation frontmatter (`/audit-agents-skills`). (4) **Brainstorm-before-planning + hiérarchie documentaire** : workflow `docs/brainstorms/ → docs/plans/` avant de coder, tableau des 5 répertoires avec leur rôle distinct (CLAUDE.md = règles, solutions/ = problèmes résolus, brainstorms/ = réflexion, plans/ = plans actifs, todos/ = tâches éphémères). Évaluation formelle : `docs/resource-evaluations/2026-03-04-compound-engineering-every-to.md` (4/5 HIGH VALUE).
|
||||
|
|
|
|||
134
docs/resource-evaluations/073-athena-flow-workflow-runtime.md
Normal file
134
docs/resource-evaluations/073-athena-flow-workflow-runtime.md
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
# Resource Evaluation #073 — Athena Flow: Hook-Based Workflow Runtime for Claude Code
|
||||
|
||||
**Source:** [athenaflow.in](https://athenaflow.in) / [github.com/lespaceman/athena-flow](https://github.com/lespaceman/athena-flow)
|
||||
**Type:** Open source tool (MIT) — workflow runtime wrapping Claude Code via hooks
|
||||
**Author:** Nadeem M (@lespaceman)
|
||||
**Evaluated:** 2026-03-05
|
||||
**Maturity at evaluation:** Published ~same day (LinkedIn post + GitHub, hours old)
|
||||
|
||||
---
|
||||
|
||||
## Résumé du contenu
|
||||
|
||||
- **Workflow runtime for Claude Code**: wraps it via hooks, routes events through a Unix Domain Socket (NDJSON) to a persistent Node.js runtime
|
||||
- **Architecture**: Claude Code → hook-forwarder (stdin) → UDS → athena-flow runtime → TUI
|
||||
- **TUI (terminal UI)**: real-time observability of tools, permissions, results, errors; SQLite session persistence; keyboard-driven with color themes
|
||||
- **Plugin system**: supports commands, hooks, MCP servers, agents; isolation presets (strict/minimal/permissive)
|
||||
- **First workflow**: autonomous E2E test builder — navigates app like a human, generates structured test cases, produces Playwright CI-ready TypeScript
|
||||
- **Claimed**: self-healing selectors at 94% success rate (~3s repair time) — unverified, no benchmark in repo
|
||||
- **Installation**: `npm install -g athena-flow-cli` (Node.js 20+)
|
||||
- **Roadmap**: visual regression, API testing, Codex support (agent-agnostic positioning)
|
||||
- **Comparable project discovered via Perplexity**: [Ruflo](https://github.com/ruvnet/ruflo) — multi-agent orchestration platform for Claude Code, a few weeks older and more mature
|
||||
|
||||
---
|
||||
|
||||
## Score de pertinence
|
||||
|
||||
| Score | Signification |
|
||||
|-------|---------------|
|
||||
| 5 | Essentiel — Gap majeur dans le guide |
|
||||
| 4 | Tres pertinent — Amelioration significative |
|
||||
| 3 | Pertinent — Complement utile |
|
||||
| **2** | **Marginal — Watch: trop recent, claims non verifies** |
|
||||
| 1 | Hors scope — Non pertinent |
|
||||
|
||||
**Score final: 2/5 (Watch)**
|
||||
|
||||
**Justification:** Le pattern "hook-based workflow runtime" est architecturalement distinct de MCP (qui ajoute des outils), des agents (qui delegent des taches), et des hooks basiques. C'est une categorie nouvelle dans l'ecosysteme Claude Code, pas encore documentee dans le guide. La valeur conceptuelle est reelle. Mais a l'evaluation, le projet a quelques heures d'existence: aucune traction mesurable, le claim "94% self-healing selectors" n'a aucune methodologie publiee dans le repo, et l'audit source npm est absent (risque supply chain non evalue). Score 2 maintenu jusqu'a verification de maturite minimale.
|
||||
|
||||
---
|
||||
|
||||
## Comparatif
|
||||
|
||||
| Aspect | Athena Flow | Notre guide |
|
||||
|--------|-------------|-------------|
|
||||
| Hook-based workflow runtime (IPC/UDS) | Nouveau pattern non couvert | Absent de third-party-tools.md |
|
||||
| TUI observabilite Claude Code | Premiere mention de ce pattern | Absent |
|
||||
| E2E test builder Playwright | Premier dans cette categorie | Playwright MCP couvert (ligne ~11367), pas de generation autonome |
|
||||
| Plugin/workflow orchestration via hooks | Nouveau pattern | Plugins documentes, pas d'orchestrateur externe |
|
||||
| Self-healing selectors | Claim 94% non verifie | N/A |
|
||||
| Maturite / adoption | Heures d'existence | N/A |
|
||||
| Audit securite (npm install -g) | Non effectue | Guide recommande audit avant install global |
|
||||
|
||||
---
|
||||
|
||||
## Recommandations
|
||||
|
||||
**Action: Watch — Ne pas integrer maintenant, revisiter dans 3-4 semaines**
|
||||
|
||||
Ce qui debloquerait une integration a 3/5:
|
||||
1. **Source audit**: inspecter `athena-flow-cli` sur npm (meme methodologie que Straude: `npm pack`, lire le code compile, verifier l'architecture declaree)
|
||||
2. **GitHub metrics**: stars, CI actif, issues ouvertes, derniere release stable
|
||||
3. **94% claim**: soit retire de la doc, soit documente avec une methodologie reproductible
|
||||
4. **Ruflo comparaison**: evaluer Ruflo (github.com/ruvnet/ruflo) en parallele — plus mature, meme categorie. L'entree du guide devrait couvrir la *categorie* (hook-based runtime), pas juste un outil
|
||||
|
||||
Si integration future: creer une section **"Hook-Based Workflow Runtimes"** dans `guide/third-party-tools.md` — categorie inexistante aujourd'hui qui accueillerait Athena Flow + Ruflo + futurs outils du meme type.
|
||||
|
||||
**Ne pas faire:**
|
||||
- Citer le "94% success rate" sans source verifiable
|
||||
- Recommander `npm install -g athena-flow-cli` sans audit source prealable (voir section securite du guide)
|
||||
- Integrer une entree outil unique sans la categorie parente
|
||||
|
||||
---
|
||||
|
||||
## Challenge (technical-writer)
|
||||
|
||||
**Score propose initial:** 3/5
|
||||
**Score apres challenge:** 2/5 (abaisse)
|
||||
|
||||
Points souleves par l'agent:
|
||||
|
||||
**Pourquoi 3/5 etait trop genereux:**
|
||||
- Projet de quelques heures = abandonment risk eleve. Roadmap ambitieuse (visual regression, API testing, Codex) sur base d'un seul workflow livre
|
||||
- `npm install -g` recommande sans audit source = contradiction avec la section securite du guide (ref: snyk-toxicskills-evaluation.md)
|
||||
- "94% success rate" sans benchmark = erreur factuelle par association si le chiffre entre dans le guide
|
||||
- Precedent: Rippletide (eval 072) score 2/5 pour "claims non verifiables, pas de traction" — Athena Flow cumule les deux
|
||||
|
||||
**Ce qui justifie de ne pas descendre a 1/5:**
|
||||
- Pattern architecturale genuinement nouveau dans l'ecosysteme (hooks → IPC → runtime persistant)
|
||||
- Categorie absente du guide = gap reel si le pattern se generalise
|
||||
- Ruflo confirme que la categorie existe et a de la demande
|
||||
|
||||
**Risque de ne pas integrer:** negligeable a court terme. Moyen terme: si Ruflo + Athena Flow + d'autres outils emergent, le guide sera en retard sur une categorie entiere. Surveiller activement.
|
||||
|
||||
---
|
||||
|
||||
## Fact-Check
|
||||
|
||||
| Affirmation | Verifiee | Source |
|
||||
|-------------|----------|--------|
|
||||
| Open source MIT | Claimed, non verifie | LinkedIn post (LICENSE file non inspecte) |
|
||||
| `npm install -g athena-flow-cli` | Vraisemblable | README (non audite) |
|
||||
| Architecture hooks → UDS → NDJSON | Vraisemblable | README decrit le data flow explicitement |
|
||||
| TUI avec SQLite session persistence | Vraisemblable | README (feature list) |
|
||||
| Playwright output CI-ready | Vraisemblable | README + landing site |
|
||||
| "94% self-healing selector success rate" | Non verifiable | Claim marketing, aucun benchmark dans repo |
|
||||
| "~3 secondes repair time" | Non verifiable | Idem |
|
||||
| Codex support "in progress" | Claim roadmap | LinkedIn post, aucun commit visible |
|
||||
| Free / $0 | Vraisemblable | Landing site + MIT license |
|
||||
| Ruflo comme projet comparable | Confirme | Perplexity search (github.com/ruvnet/ruflo) |
|
||||
|
||||
**Corrections apportees:** Le claim "94%" n'entre pas dans le guide. La mention MIT est en attente de verification du LICENSE file.
|
||||
|
||||
---
|
||||
|
||||
## Contexte ecosysteme (Perplexity, 2026-03-05)
|
||||
|
||||
Projets similaires identifies dans la meme categorie "hook-based runtime / orchestration wrapper":
|
||||
|
||||
| Projet | Description | Maturite |
|
||||
|--------|-------------|----------|
|
||||
| **[Ruflo](https://github.com/ruvnet/ruflo)** | Multi-agent orchestration platform for Claude Code, governance layer | Quelques semaines, plus mature |
|
||||
| **Entire CLI** | Gouvernance sequentielle, approval gates, audit trails (SOC2/HIPAA) | ~1 mois, documente dans le guide |
|
||||
| **oh-my-pi** | Runtime agent terminal alternatif, decouvre hooks/MCP/rules nativement | Recent |
|
||||
|
||||
La categorie emerge. Athena Flow n'est pas isole — c'est un signal de tendance.
|
||||
|
||||
---
|
||||
|
||||
## Decision finale
|
||||
|
||||
- **Score final**: 2/5
|
||||
- **Action**: Watch — revisiter dans 3-4 semaines avec: audit npm source, GitHub metrics, verification claim 94%
|
||||
- **Confiance**: Haute sur le score, moyenne sur les facts (projet trop recent pour audit complet)
|
||||
- **Prochaine action**: Evaluer Ruflo (#074) en parallele pour avoir la comparaison de categorie complete avant toute integration
|
||||
139
docs/resource-evaluations/074-ruflo-multi-agent-orchestration.md
Normal file
139
docs/resource-evaluations/074-ruflo-multi-agent-orchestration.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
# Resource Evaluation #074 — Ruflo: Multi-Agent Orchestration Platform for Claude Code
|
||||
|
||||
**Source:** [github.com/ruvnet/ruflo](https://github.com/ruvnet/ruflo)
|
||||
**npm package:** `claude-flow` (ancien nom du projet, npm non encore migre)
|
||||
**Type:** Open source (MIT) — framework d'orchestration multi-agent pour Claude Code
|
||||
**Author:** ruvnet
|
||||
**Evaluated:** 2026-03-05
|
||||
**Traction:** 18,839 stars, 2,096 forks, 452 PRs, 5,900+ commits
|
||||
|
||||
---
|
||||
|
||||
## Contexte important
|
||||
|
||||
Ruflo etait precedemment connu sous le nom **claude-flow** (github.com/ruvnet/claude-flow). Le rebrand recient est une information structurelle a noter: le package npm reste `claude-flow`, l'URL d'install curl pointe encore sur l'ancien repo. Surveiller la stabilite de la transition.
|
||||
|
||||
---
|
||||
|
||||
## Resume du contenu
|
||||
|
||||
- **Multi-agent orchestration framework**: transforme Claude Code en plateforme multi-agent avec reine + workers hierarchiques, mesh topologies, ou swarms
|
||||
- **Architecture en couches**: CLI + MCP server → Q-Learning router → Mixture of Experts (8) → 60+ agents specialises (coders, testers, reviewers, architects, security auditors...)
|
||||
- **42+ skills, 17 hooks** integres
|
||||
- **RuVector**: composant WebAssembly, HNSW vector search, SONA self-optimization, 9 algorithmes de reinforcement learning
|
||||
- **SQLite persistence** (AgentDB, WAL mode) + 8 types de memoire incluant partage cross-agent
|
||||
- **Installation**: `npx ruflo@latest init --wizard` (voie recommandee) ou `curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/claude-flow@main/scripts/install.sh | bash` (voie a eviter)
|
||||
- **Claims de performance** (voir section Fact-Check):
|
||||
- 84.8% SWE-Bench solve rate
|
||||
- 32.3% reduction de tokens
|
||||
- 2.8-4.4x speedup en coordination parallele
|
||||
- 352x WASM transforms vs LLM calls
|
||||
- 16,400 vector queries/seconde
|
||||
- SONA self-optimization <0.05ms
|
||||
|
||||
---
|
||||
|
||||
## Score de pertinence
|
||||
|
||||
| Score | Signification |
|
||||
|-------|---------------|
|
||||
| 5 | Essentiel — Gap majeur dans le guide |
|
||||
| 4 | Tres pertinent — Amelioration significative |
|
||||
| **3** | **Pertinent — Complement utile** |
|
||||
| 2 | Marginal — Watch: trop recent, claims non verifies |
|
||||
| 1 | Hors scope — Non pertinent |
|
||||
|
||||
**Score final: 3/5**
|
||||
|
||||
**Justification:** 18.9k stars est un signal d'adoption reel pour un outil de niche. Le guide couvre l'orchestration multi-agent native (Task tool, TeammateTool) mais pas les frameworks externes qui remplacent/augmentent cette couche. Gap reel, categorie absente de `guide/third-party-tools.md`. Score abaisse de 4 a 3 suite au challenge: curl|bash install depuis CDN non audite, claims de performance non verifiables, rebrand recent = instabilite potentielle.
|
||||
|
||||
---
|
||||
|
||||
## Comparatif
|
||||
|
||||
| Aspect | Ruflo | Notre guide |
|
||||
|--------|-------|-------------|
|
||||
| Orchestration multi-agent native | Architecture supplementaire | Couvre Task tool + TeammateTool nativement |
|
||||
| Framework externe d'orchestration | Nouveau pattern | Absent de third-party-tools.md |
|
||||
| Hooks integration Claude Code | 17 hooks integres | Section hooks couverte, pas d'orchestrateur externe |
|
||||
| MCP server integration | Oui, TypeScript | MCP documente extensivement |
|
||||
| Performance claims verifiables | Non (voir fact-check) | Stats documentees avec sources |
|
||||
| Audit securite install | Non effectue | Guide recommande audit avant install |
|
||||
| Adoption / communaute | 18.9k stars, #42 repos AI | Oui pour les outils recommandes |
|
||||
|
||||
---
|
||||
|
||||
## Recommandations
|
||||
|
||||
**Action: Integrer a moyen terme — apres source audit et clarification claims**
|
||||
|
||||
**Ou integrer**: `guide/third-party-tools.md` section "Multi-Agent Orchestration" — pas en entree outil seule, mais comme exemple primaire d'une nouvelle sous-categorie **"External Orchestration Frameworks"** distincte des outils multi-instance actuels (Gas Town, multiclaude).
|
||||
|
||||
La distinction est importante: Gas Town / multiclaude = lancer plusieurs Claude Code en parallele. Ruflo = remplacer/augmenter l'orchestration interne de Claude Code avec un framework complet. Ce sont deux niveaux architecturaux differents.
|
||||
|
||||
**Ce qui doit se passer avant integration:**
|
||||
|
||||
1. **Source audit `npx ruflo@latest`** via `npm pack ruflo` — verifier absence de preinstall scripts malveillants, confirmer que le package correspond a ce que le README decrit
|
||||
2. **Clarifier le rebrand**: confirmer que `ruvnet/ruflo` est bien le repo actif et que claude-flow est archive ou redirige
|
||||
3. **Baliser tous les claims** comme "claim auteur, non verifie" — aucun chiffre (84.8%, 352x, 16,400/s) ne peut entrer dans le guide sans methodologie publiee
|
||||
4. **Exclure la voie curl|bash** des recommandations (voir section securite)
|
||||
|
||||
**Framing correct pour l'entree guide:**
|
||||
> Ruflo (anciennement claude-flow) est le framework d'orchestration externe le plus adopte pour Claude Code (18.9k stars). Il ajoute une couche multi-agent complete au-dessus de Claude Code: 60+ agents specialises, routing Q-learning, persistance SQLite. A utiliser quand les capacites natives de Claude Code (Task tool, sous-agents) ne suffisent pas pour un use case.
|
||||
|
||||
---
|
||||
|
||||
## Challenge (technical-writer)
|
||||
|
||||
**Score propose initial:** 4/5
|
||||
**Score apres challenge:** 3/5 (abaisse)
|
||||
|
||||
Points cles de l'agent:
|
||||
|
||||
**Pourquoi 4/5 etait trop genereux:**
|
||||
- 18.9k stars avec 830 en un jour = spike de trending, pas adoption soutenue. Besoin de 3-4 semaines de donnees post-spike pour valider la retention
|
||||
- Rebrand claude-flow → ruflo = evenement non trivial. L'URL curl|bash pointe encore sur l'ancien repo (`ruvnet/claude-flow`) — inconcistance qui indique une transition en cours
|
||||
- 84.8% SWE-Bench serait SOTA batant les labs fermees. Claim non credible sans paper + reproductibilite. Les autres chiffres (352x, 32.3%, <0.05ms) ont une precision artificielle sans source
|
||||
- "Byzantine fault tolerance + CRDT" dans un outil pour dev individuels = "architectural theater" (citation agent) si non documente en profondeur
|
||||
|
||||
**Pourquoi 3/5 et pas 2:**
|
||||
- Gap reel dans le guide: la categorie "external orchestration framework" n'existe pas
|
||||
- Traction verifiee independamment (Perplexity: trending #42 AI repos, communaute chinoise active)
|
||||
- TypeScript, MIT, npm disponible = plus auditable qu'un projet sans package manager
|
||||
|
||||
**Risques de recommander:**
|
||||
- Complexite elevee: un user qui saute a 60 agents + Q-learning avant de maitriser le Task tool natif prend le mauvais chemin
|
||||
- Rebrand instable: les conventions de nommage (claude-flow vs ruflo) peuvent changer encore
|
||||
- Claims agressifs: 84.8% SWE-Bench si cite sans disclaimer emprunte la credibilite du guide
|
||||
|
||||
---
|
||||
|
||||
## Fact-Check
|
||||
|
||||
| Affirmation | Verifiee | Source |
|
||||
|-------------|----------|--------|
|
||||
| 18,839 GitHub stars | Confirme | Perplexity (ranktracking #42 AI repos, 2026-03-05) |
|
||||
| 2,096 forks, 452 PRs | Confirme | Perplexity cross-reference |
|
||||
| Trending: +830 stars le 3 mars 2026 | Confirme | GitHub ranking chinois (juejin.cn) |
|
||||
| MIT license | Vraisemblable | README (non inspecte directement) |
|
||||
| npm package `claude-flow` | Confirme | npmjs.com/package/claude-flow |
|
||||
| Architecture 60+ agents, 42+ skills, 17 hooks | Vraisemblable | README (non audite) |
|
||||
| `npx ruflo@latest` disponible | A verifier | npm registry non confirme |
|
||||
| 84.8% SWE-Bench solve rate | Non verifiable | Claim sans methodologie ni paper |
|
||||
| 32.3% token reduction | Non verifiable | Precision artificielle, pas de source |
|
||||
| 352x WASM vs LLM calls | Non verifiable | Baseline de comparaison inconnue |
|
||||
| 16,400 vector queries/seconde | Non verifiable | Hardware/dataset non specifies |
|
||||
| SONA <0.05ms adaptation | Non verifiable | Claim marketing |
|
||||
| Curl CDN pointe sur ancien repo (claude-flow) | Confirme | URL: `cdn.jsdelivr.net/gh/ruvnet/claude-flow` |
|
||||
|
||||
**Corrections apportees:** Aucun des chiffres de performance n'entre dans le guide. Rebrand flagge explicitement.
|
||||
|
||||
---
|
||||
|
||||
## Decision finale
|
||||
|
||||
- **Score final**: 3/5
|
||||
- **Action**: Integrer dans 2-3 semaines, apres source audit et validation post-rebrand
|
||||
- **Confiance**: Haute sur le score (traction verifiee, claims non verifiables clairement separes), moyenne sur la stabilite du projet (rebrand en cours)
|
||||
- **Prochaine action**: `npm pack ruflo` ou `npm pack claude-flow` pour identifier le bon package, inspecter le code compile, confirmer absence de preinstall scripts
|
||||
- **Entree liee**: eval #073 (Athena Flow) — creer section "Hook-Based Runtimes / External Orchestration" dans third-party-tools.md une fois les deux valides
|
||||
|
|
@ -17,7 +17,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 9 |
|
||||
| [`commands/`](./commands/) | Slash commands (workflow automation) | 26 |
|
||||
| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 31 |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 13 |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 14 |
|
||||
| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 6 |
|
||||
| [`config/`](./config/) | Settings, MCP, git templates | 5 |
|
||||
| [`memory/`](./memory/) | CLAUDE.md memory file templates | 2 |
|
||||
|
|
@ -67,7 +67,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [implementer.md](./agents/implementer.md) | Mechanical execution — bounded scope | Haiku |
|
||||
| [architecture-reviewer.md](./agents/architecture-reviewer.md) | Architecture & design review — read-only | Opus |
|
||||
|
||||
### Skills (13) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
|
||||
### Skills (14) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
|
@ -84,6 +84,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [ccboard/](./skills/ccboard/) | Comprehensive TUI/Web dashboard for Claude Code monitoring |
|
||||
| [guide-recap/](./skills/guide-recap/) | Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Slack) |
|
||||
| [release-notes-generator/](./skills/release-notes-generator/) | Generate release notes in 3 formats from git commits |
|
||||
| [pr-triage/](./skills/pr-triage/) | 3-phase PR backlog management (audit, deep review, validated comments) |
|
||||
|
||||
### Commands (26)
|
||||
|
||||
|
|
|
|||
51
examples/github-actions/.coderabbit.yaml
Normal file
51
examples/github-actions/.coderabbit.yaml
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# CodeRabbit configuration — copy to your repo root as .coderabbit.yaml
|
||||
# Docs: https://docs.coderabbit.ai/guides/configure-coderabbit
|
||||
#
|
||||
# CodeRabbit Pro: $15/dev/month — adds Q&A, sequence diagrams, interactive walkthrough
|
||||
# Free tier: unlimited public repos
|
||||
|
||||
reviews:
|
||||
# Language for review comments (default: en)
|
||||
request_changes_workflow: false
|
||||
high_level_summary: true
|
||||
poem: false
|
||||
review_status: true
|
||||
collapse_walkthrough: false
|
||||
|
||||
# Severity labels used in CodeRabbit comments
|
||||
# Maps to: Nitpick, Minor, Major, Critical
|
||||
path_filters:
|
||||
# Ignore generated files and lockfiles
|
||||
- "!**/node_modules/**"
|
||||
- "!**/*.lock"
|
||||
- "!**/dist/**"
|
||||
- "!**/build/**"
|
||||
- "!**/__generated__/**"
|
||||
- "!**/migrations/**" # Remove this if you want DB migration reviews
|
||||
|
||||
path_instructions:
|
||||
# Focus deeper on security-sensitive paths
|
||||
- path: "src/server/api/**"
|
||||
instructions: |
|
||||
Focus on: authentication/authorization checks, input validation,
|
||||
SQL injection risks, rate limiting, and sensitive data exposure.
|
||||
- path: "src/components/**"
|
||||
instructions: |
|
||||
Focus on: React best practices, accessibility (ARIA, keyboard nav),
|
||||
performance (memo, useMemo, unnecessary re-renders), and XSS risks.
|
||||
- path: "prisma/**"
|
||||
instructions: |
|
||||
Focus on: migration safety, index coverage for queried fields,
|
||||
cascade delete risks, and data integrity constraints.
|
||||
|
||||
# Auto-approve low-risk PRs (docs, tests only)
|
||||
auto_review:
|
||||
enabled: true
|
||||
drafts: false
|
||||
base_branches:
|
||||
- main
|
||||
- develop
|
||||
|
||||
chat:
|
||||
# Allow @coderabbitai commands in PR comments
|
||||
auto_reply: true
|
||||
|
|
@ -149,6 +149,91 @@ cp examples/github-actions/claude-issue-triage.yml .github/workflows/
|
|||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Multi-Model Review Setup
|
||||
|
||||
Running Claude alongside other automated reviewers (Gemini, Greptile, CodeRabbit) surfaces issues that any single model misses. The pattern: each service reviews independently, then Claude synthesizes the consensus.
|
||||
|
||||
**Why multi-model?**
|
||||
Each model has blind spots. Points raised by 2+ independent reviewers are high-signal; unique catches from each model add coverage you'd otherwise miss.
|
||||
|
||||
### Recommended stack ($30/month flat)
|
||||
|
||||
| Service | Cost | Strength |
|
||||
|---------|------|----------|
|
||||
| **Claude Code Review** (this workflow) | Included in Anthropic plan | Deep reasoning, codebase-aware |
|
||||
| **Gemini Code Assist** | $0 (included in Google Workspace) | Independent LLM, different training data |
|
||||
| **Greptile** | ~$30/month flat | Cross-file context, dependency graphs |
|
||||
|
||||
**Alternative**: CodeRabbit Pro ($15/dev/month) adds interactive Q&A and sequence diagrams.
|
||||
|
||||
### Setup
|
||||
|
||||
**Step 1: Install Gemini Code Assist**
|
||||
|
||||
1. GitHub Marketplace → search "Gemini Code Assist"
|
||||
2. Install and authorize on your repo
|
||||
3. Gemini will automatically review new PRs (posts as `gemini-code-assist[bot]`)
|
||||
4. Optional config via `.gemini/config.yaml`:
|
||||
```yaml
|
||||
code_review:
|
||||
comment_severity_threshold: MEDIUM
|
||||
max_comments_per_review: 20
|
||||
```
|
||||
|
||||
**Step 2: Install Greptile**
|
||||
|
||||
1. [greptile.com](https://greptile.com) → connect GitHub account
|
||||
2. Select your repo — Greptile indexes the codebase (~5 min)
|
||||
3. Configure in dashboard: target branches, focus paths
|
||||
4. Reviews post as `greptile[bot]` comments on PRs
|
||||
|
||||
**Step 3: Enable synthesis job**
|
||||
|
||||
In `claude-code-review.yml`, remove `false &&` from the synthesis job condition:
|
||||
|
||||
```yaml
|
||||
# Before (disabled):
|
||||
if: |
|
||||
false &&
|
||||
(github.event_name == 'pull_request' ...
|
||||
|
||||
# After (enabled):
|
||||
if: |
|
||||
(github.event_name == 'pull_request' ...
|
||||
```
|
||||
|
||||
**Step 4: Configure CodeRabbit (optional)**
|
||||
|
||||
Copy `.coderabbit.yaml` from this directory to your repo root. Edit `path_instructions` to match your stack.
|
||||
|
||||
### How the synthesis works
|
||||
|
||||
The `multi-reviewer-synthesis` job in `claude-code-review.yml`:
|
||||
|
||||
1. Waits 5 minutes after the Claude review (external bots post within 2-3 min)
|
||||
2. Collects all reviews and comments via GitHub API
|
||||
3. Skips silently if fewer than 2 reviewers have posted
|
||||
4. Claude identifies consensus (same finding flagged by 2+ reviewers) vs. unique catches
|
||||
5. Posts a structured synthesis comment on the PR
|
||||
|
||||
### Files in this directory
|
||||
|
||||
```
|
||||
examples/github-actions/
|
||||
├── README.md # This file
|
||||
├── claude-code-review.yml # Main review + optional synthesis job
|
||||
├── .coderabbit.yaml # CodeRabbit config (copy to repo root)
|
||||
├── claude-pr-auto-review.yml # Inline prompt auto-review (alternative)
|
||||
├── claude-security-review.yml # Security-focused scan
|
||||
├── claude-issue-triage.yml # Issue triage workflow
|
||||
└── prompts/
|
||||
└── code-review.md # Externalized review prompt (copy to .github/prompts/)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
|
||||
### Model Selection
|
||||
|
|
@ -247,8 +332,9 @@ These workflows consume Anthropic API credits:
|
|||
```
|
||||
examples/github-actions/
|
||||
├── README.md # This file
|
||||
├── claude-code-review.yml # Prompt-based review (recommended)
|
||||
├── claude-pr-auto-review.yml # Inline prompt auto-review
|
||||
├── claude-code-review.yml # Prompt-based review + optional synthesis job
|
||||
├── .coderabbit.yaml # CodeRabbit config (copy to repo root)
|
||||
├── claude-pr-auto-review.yml # Inline prompt auto-review (alternative)
|
||||
├── claude-security-review.yml # Security scanning workflow
|
||||
├── claude-issue-triage.yml # Issue triage workflow
|
||||
└── prompts/
|
||||
|
|
|
|||
|
|
@ -74,3 +74,134 @@ jobs:
|
|||
body: '⚠️ **Claude review failed** — Check the Actions log for details. A human reviewer should cover this PR.'
|
||||
});
|
||||
}
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# OPTIONAL: Multi-Reviewer Synthesis
|
||||
#
|
||||
# Enable this job when you have external reviewers posting on PRs:
|
||||
# - Gemini Code Assist (free via Google Workspace)
|
||||
# - Greptile (~$30/month flat, cross-file analysis)
|
||||
# - CodeRabbit Pro ($15/dev/month)
|
||||
#
|
||||
# How it works:
|
||||
# 1. Waits 5 minutes for external reviewers to post their feedback
|
||||
# 2. Collects all reviews and comments via GitHub API
|
||||
# 3. Claude synthesizes: identifies consensus (2+ reviewers) vs. unique catches
|
||||
#
|
||||
# To enable: remove the `if: false` condition below.
|
||||
# To install external reviewers: see examples/github-actions/README.md#multi-model-review
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
multi-reviewer-synthesis:
|
||||
needs: claude-review
|
||||
if: |
|
||||
false &&
|
||||
(
|
||||
(github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
|
||||
(github.event_name == 'issue_comment' &&
|
||||
github.event.issue.pull_request != null &&
|
||||
contains(github.event.comment.body, '/claude-review'))
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Wait for external reviewers
|
||||
run: |
|
||||
echo "Waiting 5 minutes for external reviewers to post..."
|
||||
sleep 300
|
||||
|
||||
- name: Collect all PR reviews and comments
|
||||
id: collect
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const prNumber = context.payload.pull_request?.number ?? context.payload.issue?.number;
|
||||
|
||||
// Fetch structured reviews (from Greptile, CodeRabbit, Gemini bots)
|
||||
const { data: reviews } = await github.rest.pulls.listReviews({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
pull_number: prNumber,
|
||||
});
|
||||
|
||||
// Fetch issue comments (bot summaries posted as comments)
|
||||
const { data: comments } = await github.rest.issues.listComments({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: prNumber,
|
||||
});
|
||||
|
||||
const reviewData = reviews
|
||||
.filter(r => r.body && r.body.length > 20)
|
||||
.map(r => ({ reviewer: r.user.login, state: r.state, body: r.body.slice(0, 1500) }));
|
||||
|
||||
const commentData = comments
|
||||
.filter(c => c.body && c.body.length > 50)
|
||||
.map(c => ({ author: c.user.login, body: c.body.slice(0, 1500) }));
|
||||
|
||||
const uniqueReviewers = new Set([
|
||||
...reviewData.map(r => r.reviewer),
|
||||
...commentData.map(c => c.author),
|
||||
]);
|
||||
|
||||
// Skip synthesis if only 1 reviewer posted (no consensus to surface)
|
||||
if (uniqueReviewers.size < 2) {
|
||||
core.setOutput('skip', 'true');
|
||||
core.setOutput('reason', `Only ${uniqueReviewers.size} reviewer found — need 2+ for synthesis`);
|
||||
return;
|
||||
}
|
||||
|
||||
core.setOutput('skip', 'false');
|
||||
core.setOutput('pr_number', prNumber.toString());
|
||||
core.setOutput('data', JSON.stringify({ reviews: reviewData, comments: commentData }));
|
||||
|
||||
- name: Skip notice
|
||||
if: steps.collect.outputs.skip == 'true'
|
||||
run: echo "Synthesis skipped — ${{ steps.collect.outputs.reason }}"
|
||||
|
||||
- name: Claude synthesis
|
||||
if: steps.collect.outputs.skip == 'false'
|
||||
uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
model: claude-sonnet-4-6
|
||||
# mcp__github__create_issue_comment posts a plain comment (not a review)
|
||||
allowed_tools: >-
|
||||
mcp__github__create_issue_comment
|
||||
direct_prompt: |
|
||||
You are synthesizing automated code review feedback for PR #${{ steps.collect.outputs.pr_number }}.
|
||||
|
||||
All reviews and comments collected:
|
||||
|
||||
${{ steps.collect.outputs.data }}
|
||||
|
||||
Your task:
|
||||
1. Group findings by theme (security, performance, correctness, architecture)
|
||||
2. Identify consensus: any finding raised by 2+ reviewers is high-signal
|
||||
3. Surface unique catches — important issues only one reviewer flagged
|
||||
4. Post a synthesis using `mcp__github__create_issue_comment` with this structure:
|
||||
|
||||
---
|
||||
## Multi-Reviewer Synthesis
|
||||
|
||||
> Reviewed by: [comma-separated reviewer names]
|
||||
|
||||
### Consensus (raised by 2+ reviewers)
|
||||
| Finding | Reviewers | Severity |
|
||||
|---------|-----------|----------|
|
||||
| [finding] | [name1], [name2] | Must Fix / Should Fix |
|
||||
|
||||
### Unique catches
|
||||
**[Reviewer]:** [what they caught that others missed — critical items only]
|
||||
|
||||
### Recommendation
|
||||
[Overall: approve / request changes / needs discussion]
|
||||
---
|
||||
|
||||
Rules:
|
||||
- Only include consensus findings that are actionable (skip style/nitpick consensus)
|
||||
- For unique catches, only surface items of 🔴 Must Fix or 🟡 Should Fix severity
|
||||
- If all reviewers agree the PR is clean: state that directly and skip the tables
|
||||
|
|
|
|||
|
|
@ -39,6 +39,22 @@ For any file that looks non-trivial, use `Read` to see the full implementation c
|
|||
|
||||
---
|
||||
|
||||
## Step 1b — Load Stack-Specific Skills (Optional)
|
||||
|
||||
If your project has skill guides in `.claude/skills/`, load the relevant ones based on what the diff touches. Run `Read` on matching paths if they exist:
|
||||
|
||||
| If the diff contains... | Load this guide |
|
||||
|------------------------|-----------------|
|
||||
| `auth`, `session`, `token`, `password` | `.claude/skills/security-guardian/authentication/` |
|
||||
| `sql`, `query`, `prisma`, `db` | `.claude/skills/postgres-*/SKILL.md` or your DB guide |
|
||||
| `input`, `form`, `upload`, `file` | `.claude/skills/security-guardian/input-validation/` |
|
||||
| `api`, `endpoint`, `route`, `middleware` | Your API conventions doc |
|
||||
| `payment`, `stripe`, `billing` | Your payment integration guide |
|
||||
|
||||
Skip this step entirely if no matching skills exist or the diff is small.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Analyze Changes
|
||||
|
||||
Review each changed file through these lenses:
|
||||
|
|
|
|||
392
examples/skills/pr-triage/SKILL.md
Normal file
392
examples/skills/pr-triage/SKILL.md
Normal file
|
|
@ -0,0 +1,392 @@
|
|||
---
|
||||
name: pr-triage
|
||||
description: >
|
||||
3-phase PR backlog management: audit open PRs, deep review selected ones, draft and post
|
||||
review comments with mandatory validation. Args: "all" to review all, PR numbers to focus
|
||||
(e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French.
|
||||
tags: [github, pr, triage, review, maintainer, multi-agent]
|
||||
---
|
||||
|
||||
# PR Triage
|
||||
|
||||
3-phase workflow for maintainers: automated audit of all open PRs, opt-in deep review via parallel agents, and validated comment posting.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
| Skill | Usage | Output |
|
||||
|-------|-------|--------|
|
||||
| `/pr-triage` | Sort, review, and comment on a PR backlog | Triage table + reviews + posted comments |
|
||||
| `/review-pr` | Review a single PR in depth | Inline PR review |
|
||||
|
||||
**Triggers**:
|
||||
- Manually: `/pr-triage` or `/pr-triage all` or `/pr-triage 42 57`
|
||||
- Proactively: when >5 PRs open without review, or stale PR >14 days detected
|
||||
|
||||
---
|
||||
|
||||
## Language
|
||||
|
||||
- Check the argument passed to the skill
|
||||
- If `en` or `english` → tables and summary in English
|
||||
- If `fr`, `french`, or no argument → French (default)
|
||||
- Note: GitHub comments (Phase 3) are ALWAYS in English (international audience)
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Thresholds used throughout the workflow. Edit to match your project:
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `staleness_days` | 14 | Days without activity before flagging as stale |
|
||||
| `overlap_threshold` | 50% | Shared files % to flag as overlapping |
|
||||
| `cluster_min_prs` | 3 | Author PR count to trigger cluster suggestion |
|
||||
| `xl_cutoff_additions` | 1000 | Additions above which a PR is classified XL |
|
||||
| `xl_cutoff_files` | 10 | Changed files above which a PR is "too large" |
|
||||
|
||||
---
|
||||
|
||||
## Preconditions
|
||||
|
||||
```bash
|
||||
git rev-parse --is-inside-work-tree
|
||||
gh auth status
|
||||
```
|
||||
|
||||
If either fails, stop and explain what is missing.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Audit (always executed)
|
||||
|
||||
### Data Gathering (parallel commands)
|
||||
|
||||
```bash
|
||||
# Repo identity
|
||||
gh repo view --json nameWithOwner -q .nameWithOwner
|
||||
|
||||
# Open PRs with full metadata (body for cross-reference issues)
|
||||
gh pr list --state open --limit 50 \
|
||||
--json number,title,author,createdAt,updatedAt,additions,deletions,changedFiles,isDraft,mergeable,reviewDecision,statusCheckRollup,body
|
||||
|
||||
# Collaborators (to distinguish internal from external PRs)
|
||||
gh api "repos/{owner}/{repo}/collaborators" --jq '.[].login'
|
||||
```
|
||||
|
||||
**Collaborators fallback**: if `gh api .../collaborators` returns 403/404:
|
||||
```bash
|
||||
# Extract authors from last 10 merged PRs
|
||||
gh pr list --state merged --limit 10 --json author --jq '.[].author.login' | sort -u
|
||||
```
|
||||
If still ambiguous, ask via `AskUserQuestion`.
|
||||
|
||||
For each PR, fetch existing reviews AND changed files:
|
||||
|
||||
```bash
|
||||
gh api "repos/{owner}/{repo}/pulls/{num}/reviews" \
|
||||
--jq '[.[] | .user.login + ":" + .state] | join(", ")'
|
||||
|
||||
# Changed files (required for overlap detection)
|
||||
gh pr view {num} --json files --jq '[.files[].path] | join(",")'
|
||||
```
|
||||
|
||||
**Rate-limiting note**: fetching files requires N API calls (1 per PR). For repos with 20+ PRs, prioritize candidates for overlap detection (same functional domain, same author).
|
||||
|
||||
**Note**: `author` is an object `{login: "..."}` — always extract `.author.login`.
|
||||
|
||||
### Analysis
|
||||
|
||||
**Size classification**:
|
||||
| Label | Additions |
|
||||
|-------|-----------|
|
||||
| XS | < 50 |
|
||||
| S | 50–200 |
|
||||
| M | 200–500 |
|
||||
| L | 500–1000 |
|
||||
| XL | > 1000 |
|
||||
|
||||
Size format: `+{additions}/-{deletions}, {files} files ({label})`
|
||||
|
||||
**Detections**:
|
||||
- **Overlaps**: compare file lists across PRs — if >50% files in common → cross-reference
|
||||
- **Clusters**: author with 3+ open PRs → suggest review order (smallest first)
|
||||
- **Staleness**: no activity for >14 days → flag "stale"
|
||||
- **CI status**: via `statusCheckRollup` → `clean` / `unstable` / `dirty`
|
||||
- **Reviews**: approved / changes_requested / none
|
||||
|
||||
**PR ↔ Issue linking**:
|
||||
- Scan each PR `body` for `fixes #N`, `closes #N`, `resolves #N` (case-insensitive)
|
||||
- If found, display in the table: `Fixes #42` in the Action/Status column
|
||||
|
||||
**Categorization**:
|
||||
|
||||
_Internal PRs_: author in collaborators list
|
||||
|
||||
_External — Ready_: additions ≤ 1000 AND files ≤ 10 AND `mergeable` ≠ `CONFLICTING` AND CI clean/unstable
|
||||
|
||||
_External — Problematic_: any of:
|
||||
- additions > 1000 OR files > 10
|
||||
- OR `mergeable` == `CONFLICTING` (merge conflict)
|
||||
- OR CI dirty (statusCheckRollup contains failures)
|
||||
- OR overlap with another open PR (>50% shared files)
|
||||
|
||||
### Output — Triage Table
|
||||
|
||||
```
|
||||
## Open PRs ({count})
|
||||
|
||||
### Internal PRs
|
||||
| PR | Title | Size | CI | Status |
|
||||
| -- | ----- | ---- | -- | ------ |
|
||||
|
||||
### External — Ready for Review
|
||||
| PR | Author | Title | Size | CI | Reviews | Action |
|
||||
| -- | ------ | ----- | ---- | -- | ------- | ------ |
|
||||
|
||||
### External — Problematic
|
||||
| PR | Author | Title | Size | Problem | Recommended Action |
|
||||
| -- | ------ | ----- | ---- | ------- | ------------------ |
|
||||
|
||||
### Summary
|
||||
- Quick wins: {XS/S PRs ready to merge}
|
||||
- Risks: {overlaps, XL sizes, CI dirty}
|
||||
- Clusters: {authors with 3+ PRs}
|
||||
- Stale: {PRs with no activity >14d}
|
||||
- Overlaps: {PRs touching the same files}
|
||||
```
|
||||
|
||||
0 PRs → display `No open PRs.` and stop.
|
||||
|
||||
### Automatic Copy
|
||||
|
||||
After displaying the triage table, copy to clipboard using platform-appropriate command:
|
||||
|
||||
```bash
|
||||
# Detect platform and copy
|
||||
UNAME=$(uname -s)
|
||||
if [ "$UNAME" = "Darwin" ]; then
|
||||
pbcopy <<'EOF'
|
||||
{full triage table}
|
||||
EOF
|
||||
elif command -v xclip &>/dev/null; then
|
||||
echo "{full triage table}" | xclip -selection clipboard
|
||||
elif command -v wl-copy &>/dev/null; then
|
||||
echo "{full triage table}" | wl-copy
|
||||
elif command -v clip.exe &>/dev/null; then
|
||||
echo "{full triage table}" | clip.exe
|
||||
fi
|
||||
```
|
||||
|
||||
Confirm: `Triage table copied to clipboard.` (EN) / `Tableau copié dans le presse-papier.` (FR)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Deep Review (opt-in)
|
||||
|
||||
### PR Selection
|
||||
|
||||
**If argument passed**:
|
||||
- `"all"` → all external PRs
|
||||
- Numbers (`"42 57"`) → only those PRs
|
||||
- No argument → propose via `AskUserQuestion`
|
||||
|
||||
**If no argument**, display:
|
||||
|
||||
```
|
||||
question: "Which PRs do you want to review in depth?"
|
||||
header: "Deep Review"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "All external"
|
||||
description: "Review {N} external PRs with parallel code-reviewer agents"
|
||||
- label: "Problematic only"
|
||||
description: "Focus on {M} risky PRs (CI dirty, too large, overlaps)"
|
||||
- label: "Ready only"
|
||||
description: "Review {K} PRs ready to merge"
|
||||
- label: "Skip"
|
||||
description: "Stop here — audit only"
|
||||
```
|
||||
|
||||
**Draft PR behavior**:
|
||||
- Draft PRs are EXCLUDED from "All external" and "Ready only"
|
||||
- Draft PRs are INCLUDED in "Problematic only" (they need attention)
|
||||
- To review a draft: type its number explicitly (e.g. `42`)
|
||||
|
||||
If "Skip" → end workflow.
|
||||
|
||||
### Executing Reviews
|
||||
|
||||
For each selected PR, launch a `code-reviewer` agent via **Task tool in parallel**:
|
||||
|
||||
```
|
||||
subagent_type: code-reviewer
|
||||
model: sonnet
|
||||
prompt: |
|
||||
Review PR #{num}: "{title}" by @{author}
|
||||
|
||||
**Metadata**: +{additions}/-{deletions}, {changedFiles} files ({size_label})
|
||||
**CI**: {ci_status} | **Reviews**: {existing_reviews} | **Draft**: {isDraft}
|
||||
|
||||
**PR Body**:
|
||||
{body}
|
||||
|
||||
**Diff**:
|
||||
{gh pr diff {num} output}
|
||||
|
||||
Apply your security and architecture expertise. Use the project-specific checklist
|
||||
from the SKILL.md Configuration section if available.
|
||||
|
||||
Return structured review:
|
||||
### Critical Issues
|
||||
### Important Issues
|
||||
### Suggestions
|
||||
### What's Good
|
||||
|
||||
Be specific: quote file:line, explain the issue, suggest the fix.
|
||||
```
|
||||
|
||||
**Fallback if parallel agents unavailable**: run reviews sequentially, one PR at a time. Notify user: `Running sequential review (parallel agents not available).`
|
||||
|
||||
Fetch diff via:
|
||||
```bash
|
||||
gh pr diff {num}
|
||||
gh pr view {num} --json body,title,author -q '{body: .body, title: .title, author: .author.login}'
|
||||
```
|
||||
|
||||
Aggregate all reports. Display a summary after all reviews complete.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Comments (mandatory validation)
|
||||
|
||||
### Draft Generation
|
||||
|
||||
For each reviewed PR, generate a GitHub comment using the template `templates/review-comment.md`.
|
||||
|
||||
**Rules**:
|
||||
- Language: **English** (international audience)
|
||||
- Tone: professional, constructive, factual
|
||||
- Always include at least 1 positive point
|
||||
- Quote code lines when relevant (format `file:42`)
|
||||
|
||||
### Display and Validation
|
||||
|
||||
**Display ALL drafted comments** in format:
|
||||
|
||||
```
|
||||
---
|
||||
### Draft — PR #{num}: {title}
|
||||
|
||||
{full comment}
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Then request validation via `AskUserQuestion`:
|
||||
|
||||
```
|
||||
question: "These comments are ready. Which ones do you want to post?"
|
||||
header: "Post Comments"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "All ({N} comments)"
|
||||
description: "Post on all reviewed PRs"
|
||||
- label: "PR #{x} — {title_truncated}"
|
||||
description: "Post only on this PR"
|
||||
- label: "None"
|
||||
description: "Cancel — post nothing"
|
||||
```
|
||||
|
||||
(Generate one option per PR + "All" + "None")
|
||||
|
||||
### Posting
|
||||
|
||||
For each validated comment:
|
||||
|
||||
```bash
|
||||
gh pr comment {num} --body-file - <<'REVIEW_EOF'
|
||||
{comment}
|
||||
REVIEW_EOF
|
||||
```
|
||||
|
||||
Confirm each post: `Comment posted on PR #{num}: {title}`
|
||||
|
||||
If "None" → `No comments posted. Workflow complete.`
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Checklist
|
||||
|
||||
Add your stack's checklist to the agent prompt in Phase 2. Examples by stack:
|
||||
|
||||
**Node.js / TypeScript**:
|
||||
- No `any` type without explicit justification
|
||||
- `async/await` error handling (try/catch or `.catch()`)
|
||||
- No unhandled promise rejections
|
||||
- Input validation at API boundaries
|
||||
|
||||
**Python**:
|
||||
- Type hints on all public functions
|
||||
- Exception specificity (no bare `except:`)
|
||||
- Resource cleanup (`with` statements, context managers)
|
||||
- No mutable default arguments
|
||||
|
||||
**Rust**:
|
||||
- `Result<T, E>` with `.context()` for error chain (no `.unwrap()` in production code)
|
||||
- No `clone()` on hot paths without justification
|
||||
- `lazy_static!` or `once_cell` for static regex
|
||||
- Lifetime annotations where ownership is non-obvious
|
||||
|
||||
**Go**:
|
||||
- Explicit error handling (no `_` discard without comment)
|
||||
- `defer` for resource cleanup
|
||||
- Context propagation in concurrent code
|
||||
- No goroutine leaks
|
||||
|
||||
**Generic** (stack-agnostic):
|
||||
- No secrets or hardcoded credentials
|
||||
- New public functions have tests
|
||||
- Breaking changes documented in PR body
|
||||
- Dependencies added have clear justification
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
| Situation | Behavior |
|
||||
|-----------|----------|
|
||||
| 0 open PRs | Display `No open PRs.` + stop |
|
||||
| Draft PR | Show in table, skip for review unless explicitly selected |
|
||||
| Unknown CI | Display `?` in CI column |
|
||||
| Review agent timeout | Show partial error, continue with others |
|
||||
| `gh pr diff` empty | Skip this PR, notify user |
|
||||
| Very large PR (>5000 additions) | Warn: "Partial review, diff truncated" |
|
||||
| Collaborators API 403/404 | Fallback to last 10 merged PR authors |
|
||||
| Parallel agents unavailable | Run sequential reviews, notify user |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Always derive owner/repo via `gh repo view`, never hardcode
|
||||
- Use `gh` CLI (not `curl` GitHub API) except for collaborators list
|
||||
- `statusCheckRollup` can be null → treat as `?`
|
||||
- `mergeable` can be `MERGEABLE`, `CONFLICTING`, or `UNKNOWN` → treat `UNKNOWN` as `?`
|
||||
- Never post without explicit user validation in chat
|
||||
- Drafted comments must be visible BEFORE any `gh pr comment`
|
||||
|
||||
---
|
||||
|
||||
## Related: /review-pr
|
||||
|
||||
| | `/pr-triage` | `/review-pr` |
|
||||
|--|-------------|--------------|
|
||||
| **Scope** | Full PR backlog | Single PR |
|
||||
| **Use when** | Catching up after accumulation, periodic triage | Reviewing a specific incoming PR |
|
||||
| **Phases** | 3 (audit + deep review + comments) | 1 (review only) |
|
||||
| **Agents** | Parallel sub-agents per PR | Single session |
|
||||
| **Output** | Triage table + review reports + GitHub comments | Inline review |
|
||||
| **Validation** | AskUserQuestion before posting | Manual decision |
|
||||
|
||||
**Decision rule**: use `/pr-triage` for backlog triage (5+ PRs), `/review-pr` for focused review of a single PR.
|
||||
62
examples/skills/pr-triage/templates/review-comment.md
Normal file
62
examples/skills/pr-triage/templates/review-comment.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
# Review Comment Template
|
||||
|
||||
Use this template to generate GitHub PR review comments. Fill in each section based on the code-reviewer agent output. Comments are posted in **English** (international audience).
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
## Review
|
||||
|
||||
**Scope**: Security, code quality, performance, test coverage, architecture
|
||||
|
||||
### Summary
|
||||
|
||||
{1–2 sentences: overall assessment. Be direct — what's the main takeaway?}
|
||||
|
||||
### Critical Issues
|
||||
|
||||
{List blocking issues that must be fixed before merge. For each:}
|
||||
{- `file:42` — Description of the problem. Why it matters. Suggested fix.}
|
||||
|
||||
{If none: "None found."}
|
||||
|
||||
### Important Issues
|
||||
|
||||
{List significant issues that should be fixed. For each:}
|
||||
{- `file:42` — Description. Why it matters. Suggested fix.}
|
||||
|
||||
{If none: "None found."}
|
||||
|
||||
### Suggestions
|
||||
|
||||
{List nice-to-haves and minor improvements. For each:}
|
||||
{- Description. Context. Optional fix.}
|
||||
|
||||
{If none: omit this section.}
|
||||
|
||||
### What's Good
|
||||
|
||||
{Always include at least 1 positive point. Be specific — what works well and why.}
|
||||
{- Description of what's done right.}
|
||||
|
||||
---
|
||||
*Automated review via Claude Code `/pr-triage` — add your project-specific checks in SKILL.md*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Formatting Rules
|
||||
|
||||
**Citation format**: `file:42` or `` `code snippet` `` for inline references
|
||||
|
||||
**Issue severity**:
|
||||
- Critical: security vulnerability, data loss risk, broken functionality, missing test for new feature
|
||||
- Important: error handling gap, performance regression, scope creep, missing validation
|
||||
- Suggestion: naming, DRY opportunity, documentation, style
|
||||
|
||||
**Tone**: Professional, constructive, factual. Challenge the code, not the person.
|
||||
No superlatives ("great", "amazing", "perfect"). No filler ("as mentioned", "it's worth noting").
|
||||
|
||||
**Length**: Aim for 200–400 words. Long enough to be useful, short enough to be read.
|
||||
|
|
@ -404,6 +404,55 @@ This section covers tools for running **multiple Claude Code instances in parall
|
|||
|
||||
---
|
||||
|
||||
## External Orchestration Frameworks
|
||||
|
||||
> **Architectural distinction**: The tools above (Gas Town, multiclaude) run multiple Claude Code instances side by side. External orchestration frameworks go further — they replace or augment Claude Code's internal orchestration layer with their own runtime, adding swarm coordination, persistent memory, and specialized agent pools on top. Use native Claude Code capabilities (Task tool, sub-agents) first; reach for these frameworks when you've exhausted them.
|
||||
|
||||
### Ruflo (formerly claude-flow)
|
||||
|
||||
**GitHub**: [github.com/ruvnet/ruflo](https://github.com/ruvnet/ruflo) — 18.9k stars (as of March 2026)
|
||||
**npm**: `claude-flow` | **License**: MIT
|
||||
|
||||
The most adopted external orchestration framework for Claude Code. Transforms it into a multi-agent platform with hierarchical swarms (queen + workers), specialized agent pools (60+ agents: coders, testers, reviewers, architects...), and persistent memory via SQLite.
|
||||
|
||||
**Core features**:
|
||||
- Q-Learning router directing tasks to the right agent based on past patterns
|
||||
- 42+ built-in skills, 17 hooks integrating natively with Claude Code
|
||||
- MCP server support for tool extension
|
||||
- SQLite-backed session persistence with cross-agent memory sharing
|
||||
- Non-interactive CI/CD mode
|
||||
|
||||
**Install** (inspect source before running):
|
||||
```bash
|
||||
npx ruflo@latest init --wizard
|
||||
# Do NOT use the curl|bash variant — it pulls from the old repo name (claude-flow) and bypasses package manager security
|
||||
```
|
||||
|
||||
> **Note on claims**: The project publishes performance metrics (SWE-Bench scores, speed multipliers) without published methodology. Treat as unverified until independently benchmarked.
|
||||
|
||||
> **Note on maturity**: Rebranded from claude-flow in early 2026. The transition is ongoing — verify npm package name and repo continuity before adopting in production.
|
||||
|
||||
**When to use**: When Claude Code's native Task tool and sub-agents are insufficient for your use case — typically complex multi-step pipelines requiring persistent state across many sessions, or workflows needing true parallel agent coordination beyond what `--dangerously-skip-permissions` + tmux achieves.
|
||||
|
||||
---
|
||||
|
||||
### Athena Flow
|
||||
|
||||
**GitHub**: [github.com/lespaceman/athena-flow](https://github.com/lespaceman/athena-flow) | **License**: MIT (claimed)
|
||||
**Status**: Watch — published March 2026, not yet audited
|
||||
|
||||
A different architectural approach: instead of augmenting Claude Code's agent layer, Athena Flow sits at the **hooks layer**. It intercepts hook events via Unix Domain Socket (NDJSON), routes them through a persistent Node.js runtime, and provides a TUI for real-time observability and workflow control.
|
||||
|
||||
```
|
||||
Claude Code → hook-forwarder → Unix Domain Socket → Athena Flow runtime → TUI
|
||||
```
|
||||
|
||||
First shipped workflow: autonomous E2E test builder (Playwright CI-ready output). Roadmap: visual regression, API testing, Codex support.
|
||||
|
||||
**Not recommended yet** — source audit pending, project too new to assess stability. Revisit in 4-6 weeks.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Ecosystem
|
||||
|
||||
Claude Code's plugin system supports community-built extensions. For detailed documentation:
|
||||
|
|
|
|||
|
|
@ -877,6 +877,12 @@ deep_dive:
|
|||
ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:1066"
|
||||
ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:2639"
|
||||
voice_refine_skill: "examples/skills/voice-refine/SKILL.md"
|
||||
# PR Triage Skill (added 2026-03-05)
|
||||
pr_triage_skill: "examples/skills/pr-triage/SKILL.md"
|
||||
pr_triage_template: "examples/skills/pr-triage/templates/review-comment.md"
|
||||
pr_triage_phases: "3 (audit + deep review + validated comments)"
|
||||
pr_triage_when: "5+ open PRs, periodic backlog triage, post-sprint cleanup"
|
||||
pr_triage_vs_review_pr: "pr-triage = backlog N PRs | review-pr = single PR focus"
|
||||
# Cowork documentation (v1.0 - migrated to dedicated repo)
|
||||
cowork_reference: "machine-readable/cowork-reference.yaml" # Dedicated YAML index (kept local)
|
||||
cowork_hub: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/README.md"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue