From 586dafd812bc26b779c087ac777446e616caeef5 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 30 Jul 2026 06:52:30 +0200 Subject: [PATCH 01/16] docs(framework): simplify contribution to one issue-first path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the role-differentiated entry table with a single flow: any contributor opens a Rapide or Détaillée issue, a Certifié or Habilité validates it (board Status Ideation -> Todo), then anyone opens the PR. Drops the Certifié-only PR gate and the 7-day roadmap vote for these issues; adds a Principles section (anti-slop, token economy, skill structure, memory upkeep). Closes phase-1 of aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md --- .github/ISSUE_TEMPLATE/feature_request.yml | 9 +-- .github/ISSUE_TEMPLATE/roadmap.yml | 8 +- CONTRIBUTING.md | 30 ++++---- GOVERNANCE.md | 6 +- .../brainstorm.md | 26 +++++++ .../phase-1.md | 77 +++++++++++++++++++ .../plan.md | 40 ++++++++++ 7 files changed, 172 insertions(+), 24 deletions(-) create mode 100644 aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/brainstorm.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/phase-1.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 032f07747..7ca3d2bb8 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,14 +1,13 @@ -name: ✨ Feature Request -description: Propose new content or an improvement to the framework +name: 🌱 Contribution Rapide +description: Propose a change or new content for the framework, minimal form title: "feat(): " type: Feature body: - type: markdown attributes: value: | - Have an idea? You can also post and upvote it in - [Discussions](https://github.com/ai-driven-dev/framework/discussions) - - popular ideas get promoted to a roadmap vote (see [ROADMAP.md](https://github.com/ai-driven-dev/framework/blob/main/ROADMAP.md)). + Issue-first: a maintainer validates this before any PR is opened (see [CONTRIBUTING.md](https://github.com/ai-driven-dev/framework/blob/main/CONTRIBUTING.md)). + Want to discuss an idea first? Post it in [Discussions](https://github.com/ai-driven-dev/framework/discussions). - type: textarea id: problem attributes: diff --git a/.github/ISSUE_TEMPLATE/roadmap.yml b/.github/ISSUE_TEMPLATE/roadmap.yml index e4fde1f25..fdcb6b49b 100644 --- a/.github/ISSUE_TEMPLATE/roadmap.yml +++ b/.github/ISSUE_TEMPLATE/roadmap.yml @@ -1,13 +1,13 @@ -name: 🗺️ Roadmap item -description: "Maintainer-authored work: a skill, a refactor, a rule to enforce" +name: 📋 Contribution Détaillée +description: "Propose a cadré change: a skill, a refactor, a rule to enforce" title: "(): " type: Task body: - type: markdown attributes: value: | - For maintainers planning framework work. Reporting a bug or asking for a feature as a user? - Use the **Bug Report** or **Feature Request** form instead. + Issue-first: a maintainer validates this before any PR is opened (see [CONTRIBUTING.md](https://github.com/ai-driven-dev/framework/blob/main/CONTRIBUTING.md)). + Reporting a bug? Use the **Bug Report** form instead. The title carries its own scope, matching `commitlint.config.cjs`: `feat(aidd-pm):`, `fix(framework):`, `refactor(aidd-context):`. - type: textarea diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b28d4c1d7..8b8c83e71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,21 +4,18 @@ Source of truth for AIDD skills, agents, rules, and templates — authored in Cl ```mermaid flowchart LR - Issue["💡 Issue / idea"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Habilité review"] --> Merge["✅ Squash-merge → next"] --> Release["🚀 Weekly promote → release-please ships"] + Issue["💡 Issue: Rapide ou Détaillée"] --> Validate["✅ Certifié/Habilité valide"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Habilité review"] --> Merge["✅ Squash-merge → next"] --> Release["🚀 Weekly promote → release-please ships"] ``` -## 👥 Who can contribute +## 👥 Comment contribuer -Roles and their rights are defined in [`GOVERNANCE.md`](./GOVERNANCE.md#-roles). Where each starts: +Un seul chemin, ouvert à tous, quel que soit ton rôle ([`GOVERNANCE.md`](./GOVERNANCE.md#-roles)) : -| Role | Start here | -| --- | --- | -| 👤 **Public** | [Open an issue](https://github.com/ai-driven-dev/framework/issues) or [discussion](https://github.com/ai-driven-dev/framework/discussions) | -| 🗳️ **Core Team** | Vote on roadmap priority | -| 🌱 **Certifié** | Open a pull request → [Set up](#-1-set-up) | -| 🛡️ **Habilité** | Review and merge | +1. **Ouvre une issue** — [🌱 Contribution Rapide](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) (rapide) ou [📋 Contribution Détaillée](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml) (cadrée), selon ce que tu veux poser sur la table. Ça cadre le sujet en amont — pas de code écrit pour rien, pas de mauvaise direction sur nos principes. +2. **Attends la validation** — un Certifié ou un Habilité bascule l'issue de `Ideation` à `Todo` sur le [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). C'est le feu vert. +3. **Ouvre ta PR** — n'importe qui peut, une fois l'issue validée → [Set up](#-1-set-up). -The rest of this guide is the *how* for those opening PRs. +Pas de vote, pas de délai d'attente formel pour ce feu vert — c'est un geste de triage, pas un scrutin (ça, c'est réservé à la priorité roadmap, voir [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting)). ## 🔧 1. Set up @@ -35,20 +32,27 @@ make setup # deps + git hooks, registers a local marketplace, installs plugins - **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill. - **Commit** — `(): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md). +## 📜 Principes + +- **Pas de slop** — relis chaque ligne avant de la proposer ; pas de contenu généré et jamais vérifié. +- **Économise le token** — réponses et prompts concis, pas de remplissage. +- **Suis la structure des skills** — anatomie dans [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), scaffold via `/aidd-context:04-skill-generate`. +- **Fais évoluer la memory** — ta PR change une convention ? Mets à jour [`aidd_docs/memory/`](aidd_docs/memory/) avec. + ## 🔀 3. Open a pull request - **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). - **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). - **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. -- **A Habilité review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — Certifié contributors cannot self-merge. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). +- **A Habilité review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). ## 🚀 Releases The `main`/`next` model, weekly cadence, and hotfix flow → [`RELEASE.md`](./RELEASE.md). A release ships **8 independently-versioned packages** (root `aidd-framework` + the 7 plugins; `aidd-ui` is alpha) plus per-tool archives; full breakdown → [`MAINTAINERS.md`](docs/MAINTAINERS.md#-releases). -## 🐛 Reporting issues +## 🐛 Reporting a bug -[Open an issue](https://github.com/ai-driven-dev/framework/issues/new/choose) (🐛 Bug or ✨ Feature) — auto-added to the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). For usage questions use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)). +[Open a Bug report](https://github.com/ai-driven-dev/framework/issues/new/choose) — auto-added to the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). Want to contribute a change instead? Use the flow above. For usage questions use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)). ## 📚 Reference diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 6f96c4ba7..8b950645b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -22,9 +22,9 @@ flowchart LR | Tier | How you get there | Adds (on top of the rung below) | Team | | ---- | ----------------- | ------------------------------- | ---- | -| **Public** | Free, any GitHub account | Open issues, comment, react / upvote ideas (signal only) | - | +| **Public** | Free, any GitHub account | Open issues, comment, react / upvote ideas (signal only), **open a pull request** once its issue is validated | - | | **Core Team** | Active [AIDD programme](https://www.ai-driven-dev.fr/) member (training, community, coaching) | A **counted roadmap vote** + voice on direction | [`core-team`](https://github.com/orgs/ai-driven-dev/teams/core-team) | -| **Certifié AIDD** | Pass the [AIDD certification](https://www.ai-driven-dev.fr/) | Open **pull requests** (framework + courses) | [`certified`](https://github.com/orgs/ai-driven-dev/teams/certified) | +| **Certifié AIDD** | Pass the [AIDD certification](https://www.ai-driven-dev.fr/) | **Validate contribution issues** (triage: move `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8)) | [`certified`](https://github.com/orgs/ai-driven-dev/teams/certified) | | **Habilité AIDD** | Promoted by a majority of Habilité | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`habilitated`](https://github.com/orgs/ai-driven-dev/teams/habilitated) | **Plugin owners** are Habilité scoped to one plugin (`aidd-context`, `aidd-dev`, @@ -40,6 +40,8 @@ flowchart LR - **Habilité** holds the tiebreak and a **quality veto** as the top rung. - A poll runs **≥ 7 days**. Accepted items land on the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). +- This vote decides **roadmap priority**, not whether a contribution issue can + move to a PR — that validation is immediate, see [`CONTRIBUTING.md`](CONTRIBUTING.md). ## ✅ Code decisions (merging) diff --git a/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/brainstorm.md b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/brainstorm.md new file mode 100644 index 000000000..83e1b2dff --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/brainstorm.md @@ -0,0 +1,26 @@ +# Simplifier la contribution — un seul chemin, issue-first + +Aujourd'hui le guide de contribution différencie l'entrée par rôle (Public/Core Team/Certifié/Habilité) et réserve l'ouverture de PR au Certifié. Objectif : un seul chemin pour tout le monde, sans distinction de rôle. Seule règle dure : une issue avant toute PR, pour cadrer le sujet en amont et éviter du dev hors-sujet ou contraire aux principes. + +## Ce qui est clair + +- Un seul flux, ouvert à tous, plus de tableau d'entrée par rôle. +- Issue obligatoire avant PR — deux templates au choix du contributeur : minimal, full. Formulaires structurés GitHub (comme `bug_report.yml`/`feature_request.yml`), pas de texte libre. +- Feu vert = un mainteneur bascule le Status de l'issue `Ideation → Todo` sur le Roadmap board existant (`ai-driven-dev` project #8). Pas de nouveau label, pas de nouveau mécanisme. +- Pas de vote roadmap (≥7 jours) pour ces issues — supprimé. +- N'importe qui peut ensuite ouvrir la PR — le gate "Certifié requis" (`GOVERNANCE.md`) est supprimé. Vérifié : ça ne touche que ce droit-là (Certifié garde son vote roadmap et son chemin de promotion vers Habilité, intacts). +- Nouvelle section **Principes** dans `CONTRIBUTING.md` (pas un fichier à part, pas dans `CLAUDE.md` qui est IA-facing) : anti AI-slop, éviter le gaspillage de token, suivre la structure des skills, faire évoluer la memory. La relecture ligne-à-ligne existe déjà (case à cocher PR template) — pas à réécrire. +- Format final attendu : ultra concis, bullet points, un flow mermaid si ça aide à visualiser le chemin (issue → validation → PR). Le contributeur doit pouvoir suivre en cliquant, ou coller la section telle quelle à une IA qui exécute pour lui. + +## Encore ouvert + +- Champs exacts des deux templates (minimal vs full) — détail d'implémentation, tranché à l'écriture. +- Formulation exacte de la section Principes — les exemples sont posés, la prose reste à écrire. + +## Suivi séparé (pas dans ce brief) + +- Challenger l'ensemble des docs root + `docs/` (12 + 7 fichiers à la main) — sujet distinct, à ouvrir comme sa propre idée si besoin. + +## Next move + +Écrire les changements : `CONTRIBUTING.md` (flux + section Principes), `GOVERNANCE.md` (retrait du gate Certifié sur l'ouverture de PR), les 2 templates d'issue. diff --git a/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/phase-1.md b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/phase-1.md new file mode 100644 index 000000000..f8df7c50f --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/phase-1.md @@ -0,0 +1,77 @@ +--- +status: done +--- + + + +# Instruction: Flux, gouvernance et templates + +## Architecture projection + +> Tree of the final files. ✅ create · ✏️ modify · ❌ delete + +```txt +. +├── CONTRIBUTING.md ✏️ +├── GOVERNANCE.md ✏️ +└── .github/ + └── ISSUE_TEMPLATE/ + ├── feature_request.yml ✏️ (→ template minimal) + └── roadmap.yml ✏️ (→ template full) +``` + +## User Journey + +```mermaid +flowchart LR + A["Contributeur ouvre une issue"] -->|"minimal ou full"| B{"Mainteneur valide ?"} + B -->|"Status: Ideation → Todo"| C["N'importe qui ouvre la PR"] + B -->|"reste en Ideation"| D["Ajustement / discussion"] + C --> E["Review Habilité"] --> F["Merge"] +``` + +## Tasks to do + +### `1)` Réécrire CONTRIBUTING.md + +> Remplacer le tableau d'entrée par rôle par le flux unique issue-first, ajouter la section Principes. + +1. Remplacer la section "👥 Who can contribute" par le flux unique : issue (minimal ou full) → mainteneur valide (bascule Status `Ideation → Todo` sur le Roadmap board) → n'importe qui ouvre la PR. +2. Insérer le mermaid flow ci-dessus (ou équivalent), pensé pour être suivi en cliquant ou collé tel quel à une IA. +3. Ajouter une section "📜 Principes" : anti AI-slop, éviter le gaspillage de token, suivre la structure des skills, faire évoluer la memory. Ne pas réécrire la relecture ligne-à-ligne (déjà couverte par la case à cocher du `PULL_REQUEST_TEMPLATE.md`). +4. Retirer toute mention du vote roadmap (≥7 jours) pour ces issues. + +### `2)` Réécrire GOVERNANCE.md + +> Aligner les droits Certifié/Habilité sur le nouveau flux. + +1. Dans la table des rôles, remplacer "Open pull requests (framework + courses)" par "Valider les issues de contribution (triage)" sur la ligne Certifié. +2. Laisser la ligne Habilité inchangée (merge, veto qualité, nomination). +3. Vérifier que § Roadmap voting ne laisse pas croire qu'un vote est requis pour valider une issue de contribution. + +### `3)` Repurposer feature_request.yml en template minimal + +> Un template court, ouvert à tout contributeur, plus lié au vote supprimé. + +1. Retirer le texte d'intro qui annonce "popular ideas get promoted to a roadmap vote". +2. Recadrer l'intro pour tout contributeur (pas seulement une proposition de contenu). +3. Garder les champs `problem`/`solution` existants tels quels. + +### `4)` Repurposer roadmap.yml en template full + +> Le même formulaire détaillé, ouvert à tous au lieu de réservé aux mainteneurs. + +1. Retirer "For maintainers planning framework work" et toute formulation réservant le template. +2. Garder les champs `problem`/`scope`/`acceptance`/`prior-art`/`out-of-scope` tels quels. +3. Nom et description du template : libres, à choisir à l'écriture. + +## Test acceptance criteria + + + +| Task | Acceptance criteria | +| ---- | -------------------------------- | +| 1 | `CONTRIBUTING.md` n'a plus de tableau d'entrée par rôle ; le flux issue-first et la section Principes sont visibles | +| 2 | La ligne Certifié de `GOVERNANCE.md` ne mentionne plus l'ouverture de PR, mentionne la validation d'issue | +| 3 | `feature_request.yml` ne référence plus de vote roadmap, reste utilisable par n'importe quel contributeur | +| 4 | `roadmap.yml` ne se présente plus comme réservé aux mainteneurs, ses champs sont intacts | diff --git a/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md new file mode 100644 index 000000000..c6ae1fc15 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md @@ -0,0 +1,40 @@ +--- +objective: "Tout contributeur suit un seul chemin issue-first, validé par un Certifié ou un Habilité, avant d'ouvrir sa PR." +status: in-progress +--- + + + +# Plan: Simplifier la contribution — un seul chemin, issue-first + +## Overview + +| Field | Value | +| ---------- | ----------------------- | +| **Goal** | Remplacer le flux de contribution par rôle par un flux unique, ouvert à tous, gardé par une issue validée avant PR | +| **Source** | [`aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/brainstorm.md`](./brainstorm.md) | + +## Phases + +| # | Phase | File | +| --- | ------------ | ----------------------------- | +| 1 | Flux, gouvernance et templates | [`phase-1.md`](./phase-1.md) | + +## Resources + +| Source | Verified | +| ------ | ----------------- | +| GitHub GraphQL API — `ai-driven-dev` `projectV2(number: 8)` | Le champ Status existe déjà : `Ideation → Todo → In Progress → In review → Done` | +| GitHub REST API — `repos/ai-driven-dev/framework/teams` | `certified-members` a déjà `triage: true` sur le repo (push+triage+pull), hérité par `trusted-partners` (Habilité) | +| `.github/rulesets/next.json` (in-repo) | L'ouverture de PR n'est jamais techniquement gatée par équipe — seule la review/merge l'est | + +## Decisions + + + +| Decision | Why | +| ---------- | ----- | +| Supprimer le gate "Certifié requis" pour ouvrir une PR (`GOVERNANCE.md`) | Décision produit confirmée par l'utilisateur, malgré l'impact sur le programme de certification payant | +| Réutiliser le champ Status existant du Roadmap board (`Ideation → Todo`) comme signal de validation | Évite d'inventer un nouveau label/mécanisme parallèle | +| Repurposer `feature_request.yml` et `roadmap.yml` en templates minimal/full plutôt que créer 2 nouveaux fichiers | Les champs existants couvrent déjà le besoin — pas de doublon | +| Le droit Certifié devient "valider les issues de contribution (triage)" à la place de "ouvrir une PR" | Permission déjà réelle (`triage: true` sur l'équipe), garde la ligne Certifié distincte de Core Team sans toucher la pipeline de nomination Habilité | From a89b36a6b8d5c88ae5c5ddf8c7a7d4f8d2d374fa Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 30 Jul 2026 06:52:49 +0200 Subject: [PATCH 02/16] docs(framework): mark contribution simplification plan implemented --- .../tasks/2026_07/2026_07_29_simplifier-contribution/plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md index c6ae1fc15..3ddc2c5f0 100644 --- a/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md +++ b/aidd_docs/tasks/2026_07/2026_07_29_simplifier-contribution/plan.md @@ -1,6 +1,6 @@ --- objective: "Tout contributeur suit un seul chemin issue-first, validé par un Certifié ou un Habilité, avant d'ouvrir sa PR." -status: in-progress +status: implemented --- From 8b5aa6d3b253a07420faf6c2f2a571a4e4afe58c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 30 Jul 2026 10:02:16 +0200 Subject: [PATCH 03/16] docs(framework): tighten contribution flow, sync renamed roles CONTRIBUTING.md: translate the how-to-contribute and Principles sections to English (repo convention), compress to a plain 1-2-3-4 list up top, drop the sub-numbering that clashed with it, and trim Releases to a pointer (detail already lives in RELEASE.md/MAINTAINERS.md). GOVERNANCE.md: finish the Habilite/Certifie -> Trusted Partner/ Certified Member rename started earlier, and fix the team links, which pointed at stale slugs (habilitated/certified instead of the real trusted-partners/certified-members). Propagate the same rename to CONTRIBUTORS.md and docs/MAINTAINERS.md to remove the duplication/drift risk. Trim ROADMAP.md's "How to influence" section and add the missing Thursday 10:30 Discord sync. --- CONTRIBUTING.md | 35 ++++++++++++------------ CONTRIBUTORS.md | 4 +-- GOVERNANCE.md | 65 ++++++++++++++++++++++----------------------- ROADMAP.md | 14 +++++----- docs/MAINTAINERS.md | 8 +++--- 5 files changed, 64 insertions(+), 62 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b8c83e71..3013adc87 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,20 +4,21 @@ Source of truth for AIDD skills, agents, rules, and templates — authored in Cl ```mermaid flowchart LR - Issue["💡 Issue: Rapide ou Détaillée"] --> Validate["✅ Certifié/Habilité valide"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Habilité review"] --> Merge["✅ Squash-merge → next"] --> Release["🚀 Weekly promote → release-please ships"] + Issue["💡 Open an issue"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] ``` -## 👥 Comment contribuer +## 👥 How to contribute -Un seul chemin, ouvert à tous, quel que soit ton rôle ([`GOVERNANCE.md`](./GOVERNANCE.md#-roles)) : +One path, open to everyone, whatever your role ([`GOVERNANCE.md`](./GOVERNANCE.md#-roles)): -1. **Ouvre une issue** — [🌱 Contribution Rapide](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) (rapide) ou [📋 Contribution Détaillée](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml) (cadrée), selon ce que tu veux poser sur la table. Ça cadre le sujet en amont — pas de code écrit pour rien, pas de mauvaise direction sur nos principes. -2. **Attends la validation** — un Certifié ou un Habilité bascule l'issue de `Ideation` à `Todo` sur le [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). C'est le feu vert. -3. **Ouvre ta PR** — n'importe qui peut, une fois l'issue validée → [Set up](#-1-set-up). +1. **Open an issue** — [🌱 Contribution Rapide](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Contribution Détaillée](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Frames the topic upfront — no code written for nothing, no direction fighting our principles. +2. **Get it validated** — a Certified Member or Trusted Partner moves it `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). That's the green light. +3. **Open your PR** — anyone can, once validated → [Set up](#-set-up). +4. **Get reviewed and merged** — see [Open a pull request](#-open-a-pull-request). -Pas de vote, pas de délai d'attente formel pour ce feu vert — c'est un geste de triage, pas un scrutin (ça, c'est réservé à la priorité roadmap, voir [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting)). +No vote, no waiting period for this green light — it's a triage gesture, not a ballot (that's roadmap priority, see [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting)). -## 🔧 1. Set up +## 🔧 Set up Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). @@ -27,28 +28,28 @@ make setup # deps + git hooks, registers a local marketplace, installs plugins `make` lists every target; `make doctor` and `make check` verify the environment and run the pre-commit checks (including the Markdown link checker). -## ✏️ 2. Make your change +## ✏️ Make your change - **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill. - **Commit** — `(): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md). -## 📜 Principes +## 📜 Principles -- **Pas de slop** — relis chaque ligne avant de la proposer ; pas de contenu généré et jamais vérifié. -- **Économise le token** — réponses et prompts concis, pas de remplissage. -- **Suis la structure des skills** — anatomie dans [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), scaffold via `/aidd-context:04-skill-generate`. -- **Fais évoluer la memory** — ta PR change une convention ? Mets à jour [`aidd_docs/memory/`](aidd_docs/memory/) avec. +- **No slop** — read every line before proposing it; no generated content that was never checked. +- **Spend tokens like they cost something** — concise prompts and answers, no filler. +- **Follow the skill structure** — anatomy in [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), scaffold with `/aidd-context:04-skill-generate`. +- **Evolve the memory** — your PR changes a convention? Update [`aidd_docs/memory/`](aidd_docs/memory/) with it. -## 🔀 3. Open a pull request +## 🔀 Open a pull request - **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). - **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). - **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. -- **A Habilité review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). +- **A Trusted Partner review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). ## 🚀 Releases -The `main`/`next` model, weekly cadence, and hotfix flow → [`RELEASE.md`](./RELEASE.md). A release ships **8 independently-versioned packages** (root `aidd-framework` + the 7 plugins; `aidd-ui` is alpha) plus per-tool archives; full breakdown → [`MAINTAINERS.md`](docs/MAINTAINERS.md#-releases). +Weekly `main`/`next` cadence and hotfix flow → [`RELEASE.md`](./RELEASE.md). ## 🐛 Reporting a bug diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index b65551f5d..0ed9cef84 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -14,10 +14,10 @@ list to maintain. The mosaic is generated from the GitHub > contrib.rocks image API needs public access). Until then, see the graph link > above. -## Maintainers (Habilité AIDD) +## Maintainers (Trusted Partner AIDD) Live source of truth: the -[`@ai-driven-dev/habilitated`](https://github.com/orgs/ai-driven-dev/teams/habilitated) +[`@ai-driven-dev/trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) team. - [@blafourcade](https://github.com/blafourcade) (lead) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 8b950645b..8217b40f9 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,7 +1,8 @@ # Governance -How decisions get made in the AI-Driven Dev Framework. Four roles form a -**ladder** - each rung keeps every right of the rungs below and adds its own. +How decisions get made in the AI-Driven Dev Framework. + +Four roles form a **ladder**, each rung keeps every right of the rungs below and adds its own. ```mermaid --- @@ -9,13 +10,13 @@ title: AIDD roles ladder --- flowchart LR Public["Public - free"] - CoreTeam["Core Team - AIDD member"] - Certifie["Certifie AIDD - certified"] - Habilite["Habilite AIDD - maintainer"] + CoreTeam["Core Team AIDD"] + Certified["Certified Members AIDD"] + Maintainer["Trusted Partner & Staff AIDD"] Public -- join programme --> CoreTeam - CoreTeam -- pass certification --> Certifie - Certifie -- promoted --> Habilite + CoreTeam -- pass certification --> Certified + Certified -- promoted --> Trusted Partner ``` ## 👥 Roles @@ -24,59 +25,57 @@ flowchart LR | ---- | ----------------- | ------------------------------- | ---- | | **Public** | Free, any GitHub account | Open issues, comment, react / upvote ideas (signal only), **open a pull request** once its issue is validated | - | | **Core Team** | Active [AIDD programme](https://www.ai-driven-dev.fr/) member (training, community, coaching) | A **counted roadmap vote** + voice on direction | [`core-team`](https://github.com/orgs/ai-driven-dev/teams/core-team) | -| **Certifié AIDD** | Pass the [AIDD certification](https://www.ai-driven-dev.fr/) | **Validate contribution issues** (triage: move `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8)) | [`certified`](https://github.com/orgs/ai-driven-dev/teams/certified) | -| **Habilité AIDD** | Promoted by a majority of Habilité | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`habilitated`](https://github.com/orgs/ai-driven-dev/teams/habilitated) | - -**Plugin owners** are Habilité scoped to one plugin (`aidd-context`, `aidd-dev`, -…): they merge and triage for that plugin only. +| **Certified Members** | Pass the [AIDD certification](https://www.ai-driven-dev.fr/) | **Validate contribution issues** (triage: move `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8)) | [`certified-members`](https://github.com/orgs/ai-driven-dev/teams/certified-members) | +| **Trusted Partner** | Certified members promoted to give AIDD Trainings | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) | ## 📊 Roadmap voting - **Public** reacts (👍 / upvote). This is a **signal**, not a counted vote; it promotes an item to a formal vote. -- **Core Team, Certifié, Habilité** each cast **one equal vote**. The vote is a +- **Core Team, Certified, Trusted Partner** each cast **one equal vote**. The vote is a benefit of AIDD membership (the programme is a paid training / community / - coaching offering) - that is what turns a signal into a counted vote. -- **Habilité** holds the tiebreak and a **quality veto** as the top rung. + coaching offering), that is what turns a signal into a counted vote. +- **Trusted Partner** holds the tiebreak and a **quality veto** as the top rung. - A poll runs **≥ 7 days**. Accepted items land on the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). - This vote decides **roadmap priority**, not whether a contribution issue can - move to a PR — that validation is immediate, see [`CONTRIBUTING.md`](CONTRIBUTING.md). + move to a PR, that validation is immediate, see [`CONTRIBUTING.md`](CONTRIBUTING.md). ## ✅ Code decisions (merging) -- Merge authority is **Habilité only**. -- **Lazy consensus** (default): a Habilité may merge if no other Habilité objects within 72h, there is ≥1 Habilité approval, and CI passes. -- **Quality veto**: any Habilité can block with a `request-changes` review until resolved. -- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Habilité approve, none object. +- Merge authority is **Trusted Partner only**. +- **Lazy consensus** (default): a Trusted Partner may merge if no other Trusted Partner objects within 72h, there is ≥1 Trusted Partner approval, and CI passes. +- **Quality veto**: any Trusted Partner can block with a `request-changes` review until resolved. +- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Trusted Partner approve, none object. ## 📈 Promotion and inactivity -- **→ Certifié**: pass the AIDD certification → added to `certified`. -- **→ Habilité**: a Habilité nominates a Certifié with a track record of merged, - standard-consistent work; a majority of Habilité approves → added to - `habilitated` and `CODEOWNERS`. -- A Core Team / Habilité member inactive **6 months** may be moved to **emeritus** - by a Habilité majority (keeps recognition, loses vote/merge until they return). +- **→ Certified Member**: pass the AIDD certification → added to `certified-members`. +- **→ Trusted Partner**: a Trusted Partner nominates a Certified Member with a + track record of merged, standard-consistent work; a majority of Trusted + Partners approves → added to `trusted-partners` and `CODEOWNERS`. +- A Core Team / Trusted Partner member inactive **6 months** may be moved to + **emeritus** by a Trusted Partner majority (keeps recognition, loses + vote/merge until they return). ## 🧩 Plugins, breaking changes, conflicts - **New plugin**: lands via PR following [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) (description on every skill, registered in - `marketplace.json` + `release-please-config.json`, a Habilité owner). Starts - `experimental` → `release candidate` (one external success) → `stable` (Habilité - review). -- **Deprecate/remove**: any Habilité, with a rationale + migration path; stays + `marketplace.json` + `release-please-config.json`, a Trusted Partner owner). Starts + `experimental` → `release candidate` (one external success) → `stable` (Trusted + Partner review). +- **Deprecate/remove**: any Trusted Partner, with a rationale + migration path; stays installable 90 days. - **Breaking changes**: Conventional Commits `!` suffix; document the migration path. Prompt-only behaviour changes also count - flag in the PR and announce on Discord. -- **Conflict of interest**: a Habilité with a stake in a PR discloses it and is - not the sole approver (a second Habilité approval becomes mandatory). +- **Conflict of interest**: a Trusted Partner with a stake in a PR discloses it and is + not the sole approver (a second Trusted Partner approval becomes mandatory). ## 🔒 Branch protection on `main` and `next` -- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Habilité (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan). +- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Trusted Partner (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan). - **`next`** (integration): PRs with ≥1 review and passing checks, no direct push or deletion. The release bot bypasses to push the automated back-merge; the `admin` team may merge without a second review. Rules: [`.github/rulesets/next.json`](.github/rulesets/next.json). Release flow: [`RELEASE.md`](RELEASE.md). ## 📜 Code of Conduct & amendments diff --git a/ROADMAP.md b/ROADMAP.md index c979ef24f..ac20410fd 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,13 +1,15 @@ # Roadmap -The live roadmap is the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8): a milestone is a theme, due on a Friday, and everything without one is the backlog, ordered by priority. That board is the single source of truth; this file deliberately does not duplicate it. Shipped reality lives in [`CHANGELOG.md`](./CHANGELOG.md). +The live roadmap is the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8): a milestone is a theme, due on a Thursday, and everything without one is the backlog, ordered by priority. That board is the single source of truth. + +Shipped reality lives in [`CHANGELOG.md`](./CHANGELOG.md). ## How to influence -Priority is set by a community vote - full mechanism (who votes, weighting, polls) in [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting). To influence it: +Priority is set by a community vote — mechanism (who votes, weighting, polls) in [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting). -- Open a `feat:` issue or an idea in [GitHub Discussions](https://github.com/ai-driven-dev/framework/discussions), and 👍 / upvote what you want - the signal that promotes an item to a vote. -- Discuss on [Discord](https://discord.gg/EWySJSpjWs). -- Sponsored work: see [`.github/FUNDING.yml`](./.github/FUNDING.yml). +To influence it: -Accepted items land on the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). +- Open an issue or an idea in [GitHub Discussions](https://github.com/ai-driven-dev/framework/discussions) and 👍 / upvote what you want. +- Weekly sync: Thursdays 10:30 on the [Framework channel on Discord](https://discord.com/channels/1173363373115723796/1512081578858119238) decides what the next milestone contains. +- Sponsored work: see [`.github/FUNDING.yml`](./.github/FUNDING.yml). diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index ffbde9642..bc68896e2 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -1,6 +1,6 @@ # Maintainers guide -How to operate this repository day to day. This file is the **Habilité** (maintainer) playbook — it does not restate the others: +How to operate this repository day to day. This file is the **Trusted Partner** (maintainer) playbook — it does not restate the others: - **Who** may do what + decision rules → [`GOVERNANCE.md`](../GOVERNANCE.md). - **How contributors work** → [`CONTRIBUTING.md`](../CONTRIBUTING.md). @@ -11,7 +11,7 @@ How to operate this repository day to day. This file is the **Habilité** (maint | ----- | ----- | ---- | | Published plugins | `.claude-plugin/marketplace.json` + `plugins/` | the only thing shipped in a release | | Live backlog & roadmap | [Project board #8](https://github.com/orgs/ai-driven-dev/projects/8) | single source of truth | -| Roles → access | GitHub teams `habilitated` / `certified` / `core-team` | mapped to the role ladder | +| Roles → access | GitHub teams `trusted-partners` / `certified-members` / `core-team` | mapped to the role ladder | | Branch protection | ruleset "main protection" + `.github/rulesets/main.json` | `main` is PR-only | | Releases | release-please (`ci.yml`) + `release-please-config.json` | 8 packages (root + 7 plugins), auto | | Pre-commit checks | `lefthook.yml` + `scripts/` | json/yaml/schema/frontmatter/catalogs/counts | @@ -119,8 +119,8 @@ Keep the file and the live ruleset in sync. Roles, promotion, and inactivity rules → [`GOVERNANCE.md`](../GOVERNANCE.md#-roles). Team mechanics only: -- Habilité ↔ `habilitated` team + `CODEOWNERS`. -- Core Team / Certifié ↔ `core-team` / `certified` teams. +- Trusted Partner ↔ `trusted-partners` team + `CODEOWNERS`. +- Core Team / Certified Member ↔ `core-team` / `certified-members` teams. ## 🛡️ Security From 5e42f7cd0eb128064475b3bfdf48205e90717cd5 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 30 Jul 2026 10:08:25 +0200 Subject: [PATCH 04/16] docs(framework): fold CONTRIBUTORS.md into README, unify on Maintainer CONTRIBUTORS.md wasn't a GitHub-special file and was linked from nowhere but MAINTAINERS.md; its only real content (the contrib.rocks mosaic) now lives in README.md's existing Contributing section. Rights language (merge, veto, review, CODEOWNERS) now says Maintainer throughout instead of Trusted Partner, matching the roles ladder's own top rung: Trusted Partner and AIDD Staff are the two paths into one Maintainer tier, not two different rights holders. Trusted Partner is kept only as the promotion-path name. Also fixes CODEOWNERS, which still pointed at the stale @ai-driven-dev/habilitated team/comment - real merge-review assignment would have silently broken. --- .github/CODEOWNERS | 4 ++-- CONTRIBUTING.md | 4 ++-- CONTRIBUTORS.md | 28 ---------------------------- GOVERNANCE.md | 43 ++++++++++++++++++++++--------------------- README.md | 4 ++++ docs/MAINTAINERS.md | 6 +++--- 6 files changed, 33 insertions(+), 56 deletions(-) delete mode 100644 CONTRIBUTORS.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 6d0b2fc7b..49c99c89d 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,5 +1,5 @@ # Default reviewers for every change in this repository. # GitHub assigns these reviewers automatically when a pull request is opened. -# Only Habilité AIDD maintainers can approve and merge - see GOVERNANCE.md. +# Only AIDD Maintainers can approve and merge - see GOVERNANCE.md. # See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners -* @ai-driven-dev/habilitated +* @ai-driven-dev/trusted-partners diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3013adc87..d98ccd3d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ flowchart LR One path, open to everyone, whatever your role ([`GOVERNANCE.md`](./GOVERNANCE.md#-roles)): 1. **Open an issue** — [🌱 Contribution Rapide](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Contribution Détaillée](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Frames the topic upfront — no code written for nothing, no direction fighting our principles. -2. **Get it validated** — a Certified Member or Trusted Partner moves it `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). That's the green light. +2. **Get it validated** — a Certified Member or Maintainer moves it `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). That's the green light. 3. **Open your PR** — anyone can, once validated → [Set up](#-set-up). 4. **Get reviewed and merged** — see [Open a pull request](#-open-a-pull-request). @@ -45,7 +45,7 @@ make setup # deps + git hooks, registers a local marketplace, installs plugins - **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). - **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). - **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. -- **A Trusted Partner review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). +- **A Maintainer review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). ## 🚀 Releases diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md deleted file mode 100644 index 0ed9cef84..000000000 --- a/CONTRIBUTORS.md +++ /dev/null @@ -1,28 +0,0 @@ -# Contributors - -Roles are defined in [`GOVERNANCE.md`](./GOVERNANCE.md). - -## Everyone who contributes - -Open a PR, get it merged, and your avatar appears below automatically - no manual -list to maintain. The mosaic is generated from the GitHub -[contributors graph](https://github.com/ai-driven-dev/framework/graphs/contributors). - -[![Contributors](https://contrib.rocks/image?repo=ai-driven-dev/framework)](https://github.com/ai-driven-dev/framework/graphs/contributors) - -> The avatar mosaic renders only once the repository is **public** (the -> contrib.rocks image API needs public access). Until then, see the graph link -> above. - -## Maintainers (Trusted Partner AIDD) - -Live source of truth: the -[`@ai-driven-dev/trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) -team. - -- [@blafourcade](https://github.com/blafourcade) (lead) -- [@alexsoyes](https://github.com/alexsoyes) -- [@Conrardy](https://github.com/Conrardy) -- [@jdm-web](https://github.com/jdm-web) -- [@GregoireAMATO](https://github.com/GregoireAMATO) -- [@victor-langlois](https://github.com/victor-langlois) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 8217b40f9..8d2afe519 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -16,7 +16,7 @@ flowchart LR Public -- join programme --> CoreTeam CoreTeam -- pass certification --> Certified - Certified -- promoted --> Trusted Partner + Certified -- promoted --> Maintainer ``` ## 👥 Roles @@ -26,16 +26,16 @@ flowchart LR | **Public** | Free, any GitHub account | Open issues, comment, react / upvote ideas (signal only), **open a pull request** once its issue is validated | - | | **Core Team** | Active [AIDD programme](https://www.ai-driven-dev.fr/) member (training, community, coaching) | A **counted roadmap vote** + voice on direction | [`core-team`](https://github.com/orgs/ai-driven-dev/teams/core-team) | | **Certified Members** | Pass the [AIDD certification](https://www.ai-driven-dev.fr/) | **Validate contribution issues** (triage: move `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8)) | [`certified-members`](https://github.com/orgs/ai-driven-dev/teams/certified-members) | -| **Trusted Partner** | Certified members promoted to give AIDD Trainings | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) | +| **Maintainer** | Certified member promoted to give AIDD Trainings (**Trusted Partner**), or joining as **AIDD Staff** | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) | ## 📊 Roadmap voting - **Public** reacts (👍 / upvote). This is a **signal**, not a counted vote; it promotes an item to a formal vote. -- **Core Team, Certified, Trusted Partner** each cast **one equal vote**. The vote is a +- **Core Team, Certified, Maintainer** each cast **one equal vote**. The vote is a benefit of AIDD membership (the programme is a paid training / community / coaching offering), that is what turns a signal into a counted vote. -- **Trusted Partner** holds the tiebreak and a **quality veto** as the top rung. +- **Maintainer** holds the tiebreak and a **quality veto** as the top rung. - A poll runs **≥ 7 days**. Accepted items land on the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). - This vote decides **roadmap priority**, not whether a contribution issue can @@ -43,39 +43,40 @@ flowchart LR ## ✅ Code decisions (merging) -- Merge authority is **Trusted Partner only**. -- **Lazy consensus** (default): a Trusted Partner may merge if no other Trusted Partner objects within 72h, there is ≥1 Trusted Partner approval, and CI passes. -- **Quality veto**: any Trusted Partner can block with a `request-changes` review until resolved. -- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Trusted Partner approve, none object. +- Merge authority is **Maintainer only**. +- **Lazy consensus** (default): a Maintainer may merge if no other Maintainer objects within 72h, there is ≥1 Maintainer approval, and CI passes. +- **Quality veto**: any Maintainer can block with a `request-changes` review until resolved. +- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Maintainer approve, none object. ## 📈 Promotion and inactivity - **→ Certified Member**: pass the AIDD certification → added to `certified-members`. -- **→ Trusted Partner**: a Trusted Partner nominates a Certified Member with a - track record of merged, standard-consistent work; a majority of Trusted - Partners approves → added to `trusted-partners` and `CODEOWNERS`. -- A Core Team / Trusted Partner member inactive **6 months** may be moved to - **emeritus** by a Trusted Partner majority (keeps recognition, loses - vote/merge until they return). +- **→ Maintainer (Trusted Partner)**: a Maintainer nominates a Certified Member + with a track record of merged, standard-consistent work; a majority of + Maintainers approves → added to `trusted-partners` and `CODEOWNERS`. + Joining as AIDD Staff skips this nomination step. +- A Core Team / Maintainer member inactive **6 months** may be moved to + **emeritus** by a Maintainer majority (keeps recognition, loses vote/merge + until they return). ## 🧩 Plugins, breaking changes, conflicts - **New plugin**: lands via PR following [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) (description on every skill, registered in - `marketplace.json` + `release-please-config.json`, a Trusted Partner owner). Starts - `experimental` → `release candidate` (one external success) → `stable` (Trusted - Partner review). -- **Deprecate/remove**: any Trusted Partner, with a rationale + migration path; stays + `marketplace.json` + `release-please-config.json`, a Maintainer owner). Starts + `experimental` → `release candidate` (one external success) → `stable` (Maintainer + review). +- **Deprecate/remove**: any Maintainer, with a rationale + migration path; stays installable 90 days. - **Breaking changes**: Conventional Commits `!` suffix; document the migration path. Prompt-only behaviour changes also count - flag in the PR and announce on Discord. -- **Conflict of interest**: a Trusted Partner with a stake in a PR discloses it and is - not the sole approver (a second Trusted Partner approval becomes mandatory). +- **Conflict of interest**: a Maintainer with a stake in a PR discloses it and is + not the sole approver (a second Maintainer approval becomes mandatory). ## 🔒 Branch protection on `main` and `next` -- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Trusted Partner (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan). +- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Maintainer (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan). - **`next`** (integration): PRs with ≥1 review and passing checks, no direct push or deletion. The release bot bypasses to push the automated back-merge; the `admin` team may merge without a second review. Rules: [`.github/rulesets/next.json`](.github/rulesets/next.json). Release flow: [`RELEASE.md`](RELEASE.md). ## 📜 Code of Conduct & amendments diff --git a/README.md b/README.md index eba3b8ff7..0881c4afa 100644 --- a/README.md +++ b/README.md @@ -315,6 +315,10 @@ Free and open-source (MIT). If it saves you time, [a ⭐](https://github.com/ai- - **Idea or bug?** [Open an issue](https://github.com/ai-driven-dev/framework/issues) or [start a discussion](https://github.com/ai-driven-dev/framework/discussions). - **Contribute code** → [`CONTRIBUTING.md`](CONTRIBUTING.md). +[![Contributors](https://contrib.rocks/image?repo=ai-driven-dev/framework)](https://github.com/ai-driven-dev/framework/graphs/contributors) + +> Renders once the repo is **public** (contrib.rocks needs public access). Until then, see the [contributors graph](https://github.com/ai-driven-dev/framework/graphs/contributors). + ---
diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index bc68896e2..dc1692190 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -1,6 +1,6 @@ # Maintainers guide -How to operate this repository day to day. This file is the **Trusted Partner** (maintainer) playbook — it does not restate the others: +How to operate this repository day to day. This file is the **Maintainer** playbook — it does not restate the others: - **Who** may do what + decision rules → [`GOVERNANCE.md`](../GOVERNANCE.md). - **How contributors work** → [`CONTRIBUTING.md`](../CONTRIBUTING.md). @@ -119,7 +119,7 @@ Keep the file and the live ruleset in sync. Roles, promotion, and inactivity rules → [`GOVERNANCE.md`](../GOVERNANCE.md#-roles). Team mechanics only: -- Trusted Partner ↔ `trusted-partners` team + `CODEOWNERS`. +- Maintainer ↔ `trusted-partners` team + `CODEOWNERS`. - Core Team / Certified Member ↔ `core-team` / `certified-members` teams. ## 🛡️ Security @@ -132,7 +132,7 @@ Roles, promotion, and inactivity rules → [`GOVERNANCE.md`](../GOVERNANCE.md#-r - **README counts** — the hero `N plugins · N skills · N agents` block (between the `counts:start`/`counts:end` markers) and each per-plugin `N skills` span — auto-generated by `scripts/sync-readme-counts.mjs` via lefthook. - **Per-plugin `CATALOG.md`** — auto-generated by `scripts/summarize-markdown.js` via lefthook. -- **`CONTRIBUTORS.md` mosaic** — the contrib.rocks image updates itself. +- **README contributors mosaic** — the contrib.rocks image updates itself. ## 🛠️ Multi-tool From e37c677e1fee9f68ebabfc300a98c3c530d14c5c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:35:06 +0200 Subject: [PATCH 05/16] docs(framework): translate template names, fix anchors and links Issue templates and their CONTRIBUTING.md links were half-English half-French (Contribution Rapide/Detaillee) - now Quick/Detailed Contribution throughout. Fixes two breaks from the terminology rename: CONTRIBUTING.md linked to GOVERNANCE.md#-code-decisions-merging, a heading that no longer exists after the section was retitled; GOVERNANCE.md's Maintainer row listed the same team link twice in the Team column. --- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- .github/ISSUE_TEMPLATE/roadmap.yml | 4 +- CONTRIBUTING.md | 22 +++++---- GOVERNANCE.md | 52 ++-------------------- README.md | 2 - 5 files changed, 16 insertions(+), 66 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 7ca3d2bb8..6ec0dc20a 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,4 +1,4 @@ -name: 🌱 Contribution Rapide +name: 🌱 Quick Contribution description: Propose a change or new content for the framework, minimal form title: "feat(): " type: Feature diff --git a/.github/ISSUE_TEMPLATE/roadmap.yml b/.github/ISSUE_TEMPLATE/roadmap.yml index fdcb6b49b..290f042d6 100644 --- a/.github/ISSUE_TEMPLATE/roadmap.yml +++ b/.github/ISSUE_TEMPLATE/roadmap.yml @@ -1,5 +1,5 @@ -name: 📋 Contribution Détaillée -description: "Propose a cadré change: a skill, a refactor, a rule to enforce" +name: 📋 Detailed Contribution +description: "Propose a scoped change: a skill, a refactor, a rule to enforce" title: "(): " type: Task body: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d98ccd3d3..df4bcfdcb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,20 @@ # Contributing to the AIDD Framework -Source of truth for AIDD skills, agents, rules, and templates — authored in Claude Code syntax; the CLI adapts an archive per tool at release. This file covers contributing to **this repository**; the wider community, roles, and training programme live at [ai-driven-dev.fr](https://www.ai-driven-dev.fr/). - -```mermaid -flowchart LR - Issue["💡 Open an issue"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] -``` +This file covers contributing to **this repository**. ## 👥 How to contribute One path, open to everyone, whatever your role ([`GOVERNANCE.md`](./GOVERNANCE.md#-roles)): -1. **Open an issue** — [🌱 Contribution Rapide](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Contribution Détaillée](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Frames the topic upfront — no code written for nothing, no direction fighting our principles. -2. **Get it validated** — a Certified Member or Maintainer moves it `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). That's the green light. -3. **Open your PR** — anyone can, once validated → [Set up](#-set-up). -4. **Get reviewed and merged** — see [Open a pull request](#-open-a-pull-request). +```mermaid +flowchart LR + Issue["💡 Open an issue"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next
type/description"] --> Commit["💬 Commit
type(scope): msg"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] +``` -No vote, no waiting period for this green light — it's a triage gesture, not a ballot (that's roadmap priority, see [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting)). +1. **Open an issue** — fill a template: [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). +2. **Get it validated** — exchange with Certified Member or Maintainer to be sure to go in right direction. When all it is good, someone moves it status from `Ideation` to`Todo`. That's the green light. +3. **Make your changes** — once validated, make your work from `next` → [Set up](#-set-up). +4. **Get reviewed and merged** — see [Open a pull request](#-open-a-pull-request). ## 🔧 Set up @@ -45,7 +43,7 @@ make setup # deps + git hooks, registers a local marketplace, installs plugins - **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). - **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). - **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. -- **A Maintainer review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). +- **A Maintainer review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). ## 🚀 Releases diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 8d2afe519..037653211 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -4,21 +4,6 @@ How decisions get made in the AI-Driven Dev Framework. Four roles form a **ladder**, each rung keeps every right of the rungs below and adds its own. -```mermaid ---- -title: AIDD roles ladder ---- -flowchart LR - Public["Public - free"] - CoreTeam["Core Team AIDD"] - Certified["Certified Members AIDD"] - Maintainer["Trusted Partner & Staff AIDD"] - - Public -- join programme --> CoreTeam - CoreTeam -- pass certification --> Certified - Certified -- promoted --> Maintainer -``` - ## 👥 Roles | Tier | How you get there | Adds (on top of the rung below) | Team | @@ -26,7 +11,7 @@ flowchart LR | **Public** | Free, any GitHub account | Open issues, comment, react / upvote ideas (signal only), **open a pull request** once its issue is validated | - | | **Core Team** | Active [AIDD programme](https://www.ai-driven-dev.fr/) member (training, community, coaching) | A **counted roadmap vote** + voice on direction | [`core-team`](https://github.com/orgs/ai-driven-dev/teams/core-team) | | **Certified Members** | Pass the [AIDD certification](https://www.ai-driven-dev.fr/) | **Validate contribution issues** (triage: move `Ideation` → `Todo` on the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8)) | [`certified-members`](https://github.com/orgs/ai-driven-dev/teams/certified-members) | -| **Maintainer** | Certified member promoted to give AIDD Trainings (**Trusted Partner**), or joining as **AIDD Staff** | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) | +| **Maintainer** | Certified member promoted to give AIDD Trainings (**Trusted Partner**), or **AIDD Staff** | **Approve & merge** PRs, **quality veto**, appoint/promote, guard the standard | [`trusted-partners`](https://github.com/orgs/ai-driven-dev/teams/trusted-partners) | ## 📊 Roadmap voting @@ -41,43 +26,12 @@ flowchart LR - This vote decides **roadmap priority**, not whether a contribution issue can move to a PR, that validation is immediate, see [`CONTRIBUTING.md`](CONTRIBUTING.md). -## ✅ Code decisions (merging) +## ✅ Code decisions - Merge authority is **Maintainer only**. - **Lazy consensus** (default): a Maintainer may merge if no other Maintainer objects within 72h, there is ≥1 Maintainer approval, and CI passes. - **Quality veto**: any Maintainer can block with a `request-changes` review until resolved. -- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Maintainer approve, none object. - -## 📈 Promotion and inactivity - -- **→ Certified Member**: pass the AIDD certification → added to `certified-members`. -- **→ Maintainer (Trusted Partner)**: a Maintainer nominates a Certified Member - with a track record of merged, standard-consistent work; a majority of - Maintainers approves → added to `trusted-partners` and `CODEOWNERS`. - Joining as AIDD Staff skips this nomination step. -- A Core Team / Maintainer member inactive **6 months** may be moved to - **emeritus** by a Maintainer majority (keeps recognition, loses vote/merge - until they return). - -## 🧩 Plugins, breaking changes, conflicts - -- **New plugin**: lands via PR following [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) - (description on every skill, registered in - `marketplace.json` + `release-please-config.json`, a Maintainer owner). Starts - `experimental` → `release candidate` (one external success) → `stable` (Maintainer - review). -- **Deprecate/remove**: any Maintainer, with a rationale + migration path; stays - installable 90 days. -- **Breaking changes**: Conventional Commits `!` suffix; document the migration - path. Prompt-only behaviour changes also count - flag in the PR and announce on - Discord. -- **Conflict of interest**: a Maintainer with a stake in a PR discloses it and is - not the sole approver (a second Maintainer approval becomes mandatory). - -## 🔒 Branch protection on `main` and `next` - -- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Maintainer (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan). -- **`next`** (integration): PRs with ≥1 review and passing checks, no direct push or deletion. The release bot bypasses to push the automated back-merge; the `admin` team may merge without a second review. Rules: [`.github/rulesets/next.json`](.github/rulesets/next.json). Release flow: [`RELEASE.md`](RELEASE.md). +- **Explicit consensus** : for cross-plugin changes, contract changes, or licensing/governance changes: ≥2 Maintainer approve. ## 📜 Code of Conduct & amendments diff --git a/README.md b/README.md index 0881c4afa..1539cad72 100644 --- a/README.md +++ b/README.md @@ -317,8 +317,6 @@ Free and open-source (MIT). If it saves you time, [a ⭐](https://github.com/ai- [![Contributors](https://contrib.rocks/image?repo=ai-driven-dev/framework)](https://github.com/ai-driven-dev/framework/graphs/contributors) -> Renders once the repo is **public** (contrib.rocks needs public access). Until then, see the [contributors graph](https://github.com/ai-driven-dev/framework/graphs/contributors). - ---
From ba259036796328ce46b5359d3b7cc788d8d0f4e2 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:39:26 +0200 Subject: [PATCH 06/16] docs(framework): cut repeated branch/merge facts in CONTRIBUTING.md Branch-off-next was said three times (mermaid, step 3, PR section); "no one merges their own PR" restated what GOVERNANCE.md#-code-decisions already covers. Kept one mention of each. --- CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df4bcfdcb..d4b3f214b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ flowchart LR 1. **Open an issue** — fill a template: [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). 2. **Get it validated** — exchange with Certified Member or Maintainer to be sure to go in right direction. When all it is good, someone moves it status from `Ideation` to`Todo`. That's the green light. -3. **Make your changes** — once validated, make your work from `next` → [Set up](#-set-up). +3. **Make your changes** — once validated → [Set up](#-set-up). 4. **Get reviewed and merged** — see [Open a pull request](#-open-a-pull-request). ## 🔧 Set up @@ -24,12 +24,7 @@ Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and make setup # deps + git hooks, registers a local marketplace, installs plugins into Claude + Codex ``` -`make` lists every target; `make doctor` and `make check` verify the environment and run the pre-commit checks (including the Markdown link checker). - -## ✏️ Make your change - -- **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill. -- **Commit** — `(): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md). +`make` lists every target; `make doctor` checks your environment, `make check` runs the pre-commit checks. ## 📜 Principles @@ -38,12 +33,17 @@ make setup # deps + git hooks, registers a local marketplace, installs plugins - **Follow the skill structure** — anatomy in [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), scaffold with `/aidd-context:04-skill-generate`. - **Evolve the memory** — your PR changes a convention? Update [`aidd_docs/memory/`](aidd_docs/memory/) with it. +## ✏️ Make your change + +- **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill. +- **Commit** — `(): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md). + ## 🔀 Open a pull request - **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). - **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). - **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. -- **A Maintainer review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — no one merges their own PR. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). +- **A Maintainer review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)); PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). ## 🚀 Releases From 6ea0bf3049a9e390ef1a918d49d3e99902a6eb8b Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:40:40 +0200 Subject: [PATCH 07/16] docs(framework): cut CONTRIBUTING.md to what a newcomer needs Dropped the Releases section (pure restatement of the Commit bullet's RELEASE.md link), the hotfix/* edge case, the label-automation and squash-merge trivia, and two Reference bullets aimed at plugin authors rather than a first-time contributor. Every remaining line is one clause, no nested asides. --- CONTRIBUTING.md | 48 +++++++++++++++++++----------------------------- 1 file changed, 19 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4b3f214b..ec3460b30 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,64 +1,54 @@ # Contributing to the AIDD Framework -This file covers contributing to **this repository**. - ## 👥 How to contribute -One path, open to everyone, whatever your role ([`GOVERNANCE.md`](./GOVERNANCE.md#-roles)): +One path, open to everyone ([roles](./GOVERNANCE.md#-roles)): ```mermaid flowchart LR Issue["💡 Open an issue"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next
type/description"] --> Commit["💬 Commit
type(scope): msg"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] ``` -1. **Open an issue** — fill a template: [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). -2. **Get it validated** — exchange with Certified Member or Maintainer to be sure to go in right direction. When all it is good, someone moves it status from `Ideation` to`Todo`. That's the green light. -3. **Make your changes** — once validated → [Set up](#-set-up). -4. **Get reviewed and merged** — see [Open a pull request](#-open-a-pull-request). +1. **Open an issue** — [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). +2. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. +3. **Make your change** → [Set up](#-set-up). +4. **Open your PR** → [Open a pull request](#-open-a-pull-request). ## 🔧 Set up -Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). +Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, **pipx**. ```bash -make setup # deps + git hooks, registers a local marketplace, installs plugins into Claude + Codex +make setup ``` `make` lists every target; `make doctor` checks your environment, `make check` runs the pre-commit checks. -## 📜 Principles - -- **No slop** — read every line before proposing it; no generated content that was never checked. -- **Spend tokens like they cost something** — concise prompts and answers, no filler. -- **Follow the skill structure** — anatomy in [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), scaffold with `/aidd-context:04-skill-generate`. -- **Evolve the memory** — your PR changes a convention? Update [`aidd_docs/memory/`](aidd_docs/memory/) with it. - ## ✏️ Make your change -- **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill. -- **Commit** — `(): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md). +- **Test** — run `make reload`, then restart your session. +- **Commit** — `(): description` → [convention](aidd_docs/memory/vcs.md#commit-convention). ## 🔀 Open a pull request -- **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). -- **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). -- **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. -- **A Maintainer review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)); PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). +- **Branch off `next`, target `next`** → [routing table](aidd_docs/memory/vcs.md#types). +- **Fill the PR template.** +- **A Maintainer review gates every merge** → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). -## 🚀 Releases +## 📜 Principles -Weekly `main`/`next` cadence and hotfix flow → [`RELEASE.md`](./RELEASE.md). +- **No slop** — read every line before proposing it. +- **Spend tokens like they cost something.** +- **Follow the skill structure** → [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), `/aidd-context:04-skill-generate`. +- **Evolve the memory** → [`aidd_docs/memory/`](aidd_docs/memory/). ## 🐛 Reporting a bug -[Open a Bug report](https://github.com/ai-driven-dev/framework/issues/new/choose) — auto-added to the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). Want to contribute a change instead? Use the flow above. For usage questions use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)). +[Open a Bug report](https://github.com/ai-driven-dev/framework/issues/new/choose). Usage question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. ## 📚 Reference -- **Build a plugin** → [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) -- **Architecture & terms** → [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/GLOSSARY.md`](docs/GLOSSARY.md) -- **Patterns to follow** → a minimal plugin [`aidd-refine`](plugins/aidd-refine/), a router skill [`00-onboard`](plugins/aidd-context/skills/00-onboard/), agents [`aidd-dev/agents`](plugins/aidd-dev/agents/) -- **Per-tool builds** → source files use Claude Code syntax; the `aidd-cli` maps each surface to its per-tool equivalent at release. `name` / `description` / `argument-hint` are universal; other frontmatter keys (`model`, `color`, `paths`, …) are tool-specific and ignored where unsupported. +[`ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) · [`GLOSSARY.md`](docs/GLOSSARY.md) --- From 85d292ca112171cf67e4c36ada2090fc2a3c3716 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:44:47 +0200 Subject: [PATCH 08/16] docs(framework): clarify report-vs-build split, restore cut facts Step 1 (open an issue) now reads as its own stopping point - reporting or proposing doesn't commit you to building it, and step 3 says anyone can pick up a validated issue, not just its opener. Moved Principles right after the flow (was buried after Set up), and added back "Claude Code syntax only" - present in the file before this branch's rewrite, dropped by accident. Set up and Make your change were cut too hard: restored what `make setup` actually does and the reload/session-restart + one-scope- per-commit facts. Open a pull request now links the PR template directly, it only named it before. --- CONTRIBUTING.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec3460b30..bff4bb85b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,39 +9,40 @@ flowchart LR Issue["💡 Open an issue"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next
type/description"] --> Commit["💬 Commit
type(scope): msg"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] ``` -1. **Open an issue** — [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). +1. **Open an issue** — [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Just reporting or proposing? Stop here. 2. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. -3. **Make your change** → [Set up](#-set-up). +3. **Want to build it yourself?** → [Set up](#-set-up). Anyone can pick up a validated issue, not just the person who opened it. 4. **Open your PR** → [Open a pull request](#-open-a-pull-request). +## 📜 Principles + +- **No slop** — read every line before proposing it. +- **Spend tokens like they cost something.** +- **Claude Code syntax only** — skills, agents, and rules are authored in Claude Code syntax; the CLI adapts a per-tool archive at release. Don't hand-author a Cursor/Copilot/Codex variant. +- **Follow the skill structure** → [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), `/aidd-context:04-skill-generate`. +- **Evolve the memory** → [`aidd_docs/memory/`](aidd_docs/memory/). + ## 🔧 Set up Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, **pipx**. ```bash -make setup +make setup # deps, git hooks, registers the marketplace, installs plugins into Claude + Codex ``` `make` lists every target; `make doctor` checks your environment, `make check` runs the pre-commit checks. ## ✏️ Make your change -- **Test** — run `make reload`, then restart your session. -- **Commit** — `(): description` → [convention](aidd_docs/memory/vcs.md#commit-convention). +- **Test locally** — neither tool hot-reloads the checkout; run `make reload`, then restart your session. +- **Commit** — `(): description`, one scope per commit → [convention](aidd_docs/memory/vcs.md#commit-convention). ## 🔀 Open a pull request - **Branch off `next`, target `next`** → [routing table](aidd_docs/memory/vcs.md#types). -- **Fill the PR template.** +- **Fill the [PR template](.github/PULL_REQUEST_TEMPLATE.md)** — what changed, how you solved it. - **A Maintainer review gates every merge** → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). -## 📜 Principles - -- **No slop** — read every line before proposing it. -- **Spend tokens like they cost something.** -- **Follow the skill structure** → [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), `/aidd-context:04-skill-generate`. -- **Evolve the memory** → [`aidd_docs/memory/`](aidd_docs/memory/). - ## 🐛 Reporting a bug [Open a Bug report](https://github.com/ai-driven-dev/framework/issues/new/choose). Usage question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. From 62bdc3e87d297d07422c8cde350336a70c84b639 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:49:53 +0200 Subject: [PATCH 09/16] docs(framework): flesh out Make your change with principles + multi-tool test Points back to Principles, and testing now says what "locally" means concretely: Claude plus at least one other tool, since the CLI's Claude-to-per-tool translation is the part most likely to break. --- CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bff4bb85b..d5b50ff67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,8 @@ flowchart LR - **No slop** — read every line before proposing it. - **Spend tokens like they cost something.** -- **Claude Code syntax only** — skills, agents, and rules are authored in Claude Code syntax; the CLI adapts a per-tool archive at release. Don't hand-author a Cursor/Copilot/Codex variant. -- **Follow the skill structure** → [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), `/aidd-context:04-skill-generate`. +- **Claude Code syntax only** — skills, agents, and rules are authored in Claude Code syntax (the [CLI](./cli/) adapts a per-tool archive at release). +- **Follow the skill structure** → [`ARCHITECTURE.md`](docs/ARCHITECTURE.md), use the `/aidd-context:04-skill-generate`. - **Evolve the memory** → [`aidd_docs/memory/`](aidd_docs/memory/). ## 🔧 Set up @@ -34,7 +34,8 @@ make setup # deps, git hooks, registers the marketplace, installs plugins into ## ✏️ Make your change -- **Test locally** — neither tool hot-reloads the checkout; run `make reload`, then restart your session. +- **Follow the [Principles](#-principles).** +- **Test locally** — run `make reload`, restart your session(s). Test in Claude *and* one other tool (e.g. Codex) — the CLI translates your Claude syntax into each tool's format, and that's exactly what can break. - **Commit** — `(): description`, one scope per commit → [convention](aidd_docs/memory/vcs.md#commit-convention). ## 🔀 Open a pull request From 15af329acdce10444709a6568dbe44b04521a4ac Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:51:21 +0200 Subject: [PATCH 10/16] docs(framework): fold bug reports into the template list Bug Report is the same mechanism as Quick/Detailed Contribution - one issue template, same board, same validation gate. Listing it as a separate "Reporting a bug" section duplicated the concept; it's now a third choice in step 1, mermaid updated to match. The Discussions caveat moved up alongside it since that section is gone. --- CONTRIBUTING.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d5b50ff67..475d8569a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,10 +6,10 @@ One path, open to everyone ([roles](./GOVERNANCE.md#-roles)): ```mermaid flowchart LR - Issue["💡 Open an issue"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next
type/description"] --> Commit["💬 Commit
type(scope): msg"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] + Issue["💡 Bug · Quick · Detailed"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next
type/description"] --> Commit["💬 Commit
type(scope): msg"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] ``` -1. **Open an issue** — [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml) or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Just reporting or proposing? Stop here. +1. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Just reporting or proposing? Stop here. Usage question instead? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. 2. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. 3. **Want to build it yourself?** → [Set up](#-set-up). Anyone can pick up a validated issue, not just the person who opened it. 4. **Open your PR** → [Open a pull request](#-open-a-pull-request). @@ -44,10 +44,6 @@ make setup # deps, git hooks, registers the marketplace, installs plugins into - **Fill the [PR template](.github/PULL_REQUEST_TEMPLATE.md)** — what changed, how you solved it. - **A Maintainer review gates every merge** → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions). -## 🐛 Reporting a bug - -[Open a Bug report](https://github.com/ai-driven-dev/framework/issues/new/choose). Usage question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. - ## 📚 Reference [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) · [`GLOSSARY.md`](docs/GLOSSARY.md) From 164bb9881182ab83ac146dbdf0f68aadad2fb61f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:54:11 +0200 Subject: [PATCH 11/16] docs(framework): mermaid shows the 3 template branches, Principles intro Bug/Quick/Detailed now render as three parallel entries converging on validation, then the linear dev tail: Set up, Changes, PR, Review, Merged - matching the section order below instead of restating branch/commit patterns already linked there. Principles gets one line of framing before the bullets. --- CONTRIBUTING.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 475d8569a..162ebaa79 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,10 @@ One path, open to everyone ([roles](./GOVERNANCE.md#-roles)): ```mermaid flowchart LR - Issue["💡 Bug · Quick · Detailed"] --> Validate["✅ Get validated"] --> Branch["🌿 Branch off next
type/description"] --> Commit["💬 Commit
type(scope): msg"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Squash-merge → next"] + Bug["🐛 Bug"] --> Validate["✅ Get validated"] + Quick["🌱 Quick"] --> Validate + Detailed["📋 Detailed"] --> Validate + Validate --> Setup["🔧 Set up"] --> Changes["✏️ Changes"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Merged"] ``` 1. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Just reporting or proposing? Stop here. Usage question instead? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. @@ -16,6 +19,8 @@ flowchart LR ## 📜 Principles +What holds for every contribution, whatever you're building: + - **No slop** — read every line before proposing it. - **Spend tokens like they cost something.** - **Claude Code syntax only** — skills, agents, and rules are authored in Claude Code syntax (the [CLI](./cli/) adapts a per-tool archive at release). @@ -35,7 +40,7 @@ make setup # deps, git hooks, registers the marketplace, installs plugins into ## ✏️ Make your change - **Follow the [Principles](#-principles).** -- **Test locally** — run `make reload`, restart your session(s). Test in Claude *and* one other tool (e.g. Codex) — the CLI translates your Claude syntax into each tool's format, and that's exactly what can break. +- **Test locally** — run `make reload`, restart your session(s). Test in Claude *and* one other tool (e.g. Codex). - **Commit** — `(): description`, one scope per commit → [convention](aidd_docs/memory/vcs.md#commit-convention). ## 🔀 Open a pull request From acb274e5d50349ae1c5592fd634f644b68b9b935 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:56:26 +0200 Subject: [PATCH 12/16] docs(framework): split Discussions from the issue templates line Step 1 crammed three template links plus a stop-here note plus a Discussions redirect into one line. Discussions now gets its own sentence before the mermaid; step 1 just lists the three templates. --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 162ebaa79..2fefc1800 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,9 @@ ## 👥 How to contribute -One path, open to everyone ([roles](./GOVERNANCE.md#-roles)): +One path, open to everyone ([roles](./GOVERNANCE.md#-roles)). + +Just a question or idea? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. Reporting or proposing something concrete? Open an issue: ```mermaid flowchart LR @@ -12,7 +14,7 @@ flowchart LR Validate --> Setup["🔧 Set up"] --> Changes["✏️ Changes"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Merged"] ``` -1. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). Just reporting or proposing? Stop here. Usage question instead? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. +1. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). 2. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. 3. **Want to build it yourself?** → [Set up](#-set-up). Anyone can pick up a validated issue, not just the person who opened it. 4. **Open your PR** → [Open a pull request](#-open-a-pull-request). From ecdf5e4b08c13ef5de5d4e258e685f919d6354b1 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 04:59:34 +0200 Subject: [PATCH 13/16] docs(framework): show the discussion-vs-issue fork in the mermaid itself The question/exchange vs bug/improvement/feature split was only in prose above the diagram. Added a Start node that branches to Discussions or the three issue templates, so the diagram carries the fork instead of the sentence above it. --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fefc1800..9f88ff888 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,15 +2,17 @@ ## 👥 How to contribute -One path, open to everyone ([roles](./GOVERNANCE.md#-roles)). - -Just a question or idea? → [Discussions](https://github.com/ai-driven-dev/framework/discussions), not an issue. Reporting or proposing something concrete? Open an issue: +One path, open to everyone ([roles](./GOVERNANCE.md#-roles)). Just a question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions). ```mermaid flowchart LR - Bug["🐛 Bug"] --> Validate["✅ Get validated"] - Quick["🌱 Quick"] --> Validate - Detailed["📋 Detailed"] --> Validate + Start(["Something to share?"]) -->|"just a question"| Discussion["💬 Discussions"] + Start --> Bug["🐛 Bug"] + Start --> Quick["🌱 Quick"] + Start --> Detailed["📋 Detailed"] + Bug --> Validate["✅ Get validated"] + Quick --> Validate + Detailed --> Validate Validate --> Setup["🔧 Set up"] --> Changes["✏️ Changes"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Merged"] ``` From 5e280e3fd957858c6f4cdc207345f4a05611e8b7 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 05:04:32 +0200 Subject: [PATCH 14/16] docs(framework): distinguish Quick vs Detailed in the diagram Both nodes just said their name with no hint of what separates them. Added the field difference (problem+solution vs scope+acceptance criteria) that actually distinguishes the two templates. Also fixed the source list numbering (two "1." items) now that Discussions is its own bullet. --- CONTRIBUTING.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f88ff888..7af791698 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,24 +2,25 @@ ## 👥 How to contribute -One path, open to everyone ([roles](./GOVERNANCE.md#-roles)). Just a question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions). +One path, open to everyone ([roles](./GOVERNANCE.md#-roles)). ```mermaid flowchart LR Start(["Something to share?"]) -->|"just a question"| Discussion["💬 Discussions"] Start --> Bug["🐛 Bug"] - Start --> Quick["🌱 Quick"] - Start --> Detailed["📋 Detailed"] + Start --> Quick["🌱 Quick
problem + solution"] + Start --> Detailed["📋 Detailed
scope + acceptance criteria"] Bug --> Validate["✅ Get validated"] Quick --> Validate Detailed --> Validate Validate --> Setup["🔧 Set up"] --> Changes["✏️ Changes"] --> PR["🔀 Open PR"] --> Review["🛡️ Review"] --> Merge["✅ Merged"] ``` -1. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). -2. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. -3. **Want to build it yourself?** → [Set up](#-set-up). Anyone can pick up a validated issue, not just the person who opened it. -4. **Open your PR** → [Open a pull request](#-open-a-pull-request). +1. Just a question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions). +2. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). +3. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. +4. **Want to build it yourself?** → [Set up](#-set-up). Anyone can pick up a validated issue, not just the person who opened it. +5. **Open your PR** → [Open a pull request](#-open-a-pull-request). ## 📜 Principles From 0f6b03b5c55dcdf3be1cc936c518dd4ab9c50138 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 05:06:45 +0200 Subject: [PATCH 15/16] docs(framework): trim the issue picker's contact links Dropped the explicit "Report a security vulnerability" contact link - GitHub already auto-adds its own shield-icon tile for that once SECURITY.md + advisories are enabled, ours was a dead ringer. Dropped "Website" too, not an actionable choice at the point someone's about to open an issue. --- .github/ISSUE_TEMPLATE/config.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index fc964fff5..1f5531ee2 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -6,9 +6,3 @@ contact_links: - name: Discord community url: https://discord.gg/EWySJSpjWs about: Ask questions, get help, or chat with the AI-Driven Dev community in real time. - - name: Website - url: https://www.ai-driven-dev.fr/ - about: Read the AI-Driven Dev methodology, guides, and announcements. - - name: Report a security vulnerability - url: https://github.com/ai-driven-dev/framework/security/advisories/new - about: Disclose a vulnerability privately via GitHub Security Advisories. Do not open a public issue. From 998c803d1ca472ed2ca249ee082969ca59525427 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 05:15:26 +0200 Subject: [PATCH 16/16] docs(framework): actually rename the issue template files Only the display name: field changed to Quick/Detailed Contribution - the files themselves stayed feature_request.yml/roadmap.yml, a filename/purpose mismatch for anyone editing them later. Renamed to quick_contribution.yml/detailed_contribution.yml and updated the ?template= links in CONTRIBUTING.md to match. Checked every other in-repo mention first - only two historical plan docs reference the old names, left as records of what existed at the time. --- .../ISSUE_TEMPLATE/{roadmap.yml => detailed_contribution.yml} | 0 .../{feature_request.yml => quick_contribution.yml} | 0 CONTRIBUTING.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) rename .github/ISSUE_TEMPLATE/{roadmap.yml => detailed_contribution.yml} (100%) rename .github/ISSUE_TEMPLATE/{feature_request.yml => quick_contribution.yml} (100%) diff --git a/.github/ISSUE_TEMPLATE/roadmap.yml b/.github/ISSUE_TEMPLATE/detailed_contribution.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/roadmap.yml rename to .github/ISSUE_TEMPLATE/detailed_contribution.yml diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/quick_contribution.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/feature_request.yml rename to .github/ISSUE_TEMPLATE/quick_contribution.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7af791698..ef455db66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ flowchart LR ``` 1. Just a question? → [Discussions](https://github.com/ai-driven-dev/framework/discussions). -2. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=feature_request.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=roadmap.yml). +2. **Open an issue** — [🐛 Bug Report](https://github.com/ai-driven-dev/framework/issues/new?template=bug_report.yml), [🌱 Quick Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=quick_contribution.yml), or [📋 Detailed Contribution](https://github.com/ai-driven-dev/framework/issues/new?template=detailed_contribution.yml). 3. **Get it validated** — a Certified Member or Maintainer moves it to `Todo`. Green light. 4. **Want to build it yourself?** → [Set up](#-set-up). Anyone can pick up a validated issue, not just the person who opened it. 5. **Open your PR** → [Open a pull request](#-open-a-pull-request).