--- name: standardize-github-repo description: "Automatic GitHub repo standardization at publication checkpoints with bilingual READMEs (EN/FR), CI linting, badges, and About configuration" --- # GitHub Repository Standardization Process Processus automatique de standardisation des repositories GitHub, déclenché aux checkpoints de publication. **Why:** L'utilisateur veut une standardisation professionnelle et pédagogique de tous ses repos GitHub sans avoir à répéter les instructions à chaque fois. Ce processus s'applique automatiquement ou via skill manuelle. **How to apply:** Détecter les triggers et proposer le processus complet si le repo n'est pas déjà standardisé. ## Critical Rule: Separate Language Files **IMPORTANT**: Documentation MUST use separate files per language: - `README.md` → English only (EN/US) - `README.fr.md` → French only (FR/FR) - **NO mixed languages within a single file** This applies to ALL documentation standardization work. ## Automatic Triggers ### Phase 1: Pré-création du repo GitHub Détecter ces phrases et proposer le processus AVANT git init : - "on va (en) faire un repo GitHub de ce projet" - "créons un repo GitHub" - "je veux publier ça sur GitHub" - "transformons ça en repo GitHub" ### Phase 2: Pré-publication (checkpoint) Détecter ces phrases et vérifier la checklist de standardisation : - "je vais publier sur GitHub" - "push vers GitHub" - "créer une PR" - "git push origin" **Action :** Vérifier automatiquement : - ✅ README.md existe et suit le template standard ? - ✅ README.fr.md existe ? - ✅ `.github/workflows/markdown-lint.yml` existe ? - ✅ `.markdownlint.json` configuré ? - ✅ Zéro violations MarkdownLint ? Si manquant → Proposer : "Ce repo n'est pas encore standardisé. Voulez-vous appliquer le processus de standardisation GitHub maintenant ?" ## Opt-Out Mechanism Si l'utilisateur dit : - "pas besoin du processus de standardisation ici" - "skip la standardisation pour ce repo" - "nul besoin du processus ici" **Action :** Enregistrer l'exception en mémoire de **session uniquement** (ne plus proposer dans cette conversation, mais reproposer dans les futures sessions sur ce repo). ## Process Overview ```text Phase 0: Pre-Flight Check (silent) ↓ Phase 1: Repository Analysis (automatic) ↓ Phase 2: README.md EN (interactive collaboration) → Badges proposal & validation → About description (3 versions → choice) → 20 Topics (proposal → validation) → 13 Sections (one-by-one → validation) → Visual content (adaptive: CLI/library/app) ↓ Phase 3: README.fr.md (translation & validation) ↓ Phase 4: CI Markdown Linting → .markdownlint.json → .github/workflows/markdown-lint.yml → Local validation & fixes ↓ Phase 5: Finalization → Commit READMEs → GitHub About instructions → Push & verify CI ```text ## Phase 0: Pre-Flight Check **Si trigger détecté, vérifier silencieusement :** 1. Est-ce un repo Git ? (`git rev-parse --git-dir`) 2. README.md existe et suit le standard ? 3. README.fr.md existe ? 4. `.github/workflows/markdown-lint.yml` existe ? 5. `.markdownlint.json` existe ? 6. Violations MarkdownLint présentes ? **Si tous les checks passent :** Skip (déjà standardisé) **Si au moins un check échoue :** Proposer le processus ## Phase 1: Repository Analysis (Automatic, Silent) Scanner le repo pour détecter : **Languages :** - Extensions de fichiers (`.py`, `.go`, `.js`, `.rs`, etc.) - Manifestes : `package.json`, `go.mod`, `Cargo.toml`, `requirements.txt` **Frameworks & Dependencies :** - Node.js : `package.json` → dependencies - Python : `requirements.txt`, `pyproject.toml` - Go : `go.mod` - Rust : `Cargo.toml` **Project Type :** - CLI tool : `bin/`, `cmd/`, `main.go`, `__main__.py`, shebangs - Library : `lib/`, `src/`, `index.js`, `__init__.py` - Application : `app/`, `public/`, `templates/` - Documentation : principalement `.md`, répertoire `docs/` **Testing :** - Fichiers tests : `*_test.go`, `test_*.py`, `*.spec.js` - Frameworks : Jest, pytest, Go testing - Coverage : `coverage/`, `.coverage`, `c.out` **Containerization :** - `Dockerfile`, `docker-compose.yml` présents ? **CI/CD :** - `.github/workflows/*.yml` présent ? **License :** - Détecter depuis `LICENSE`, `LICENSE.md` - Type : MIT, Apache 2.0, GPL, etc. **Output :** Base de connaissances interne pour les phases suivantes ## Phase 2: README.md (English) - Interactive ### Step 2.1: Badges Proposal Générer une liste de badges contextuels basée sur l'analyse Phase 1 : **Categories :** - **Mandatory :** License, Primary Language - **Contextual :** CI Status (si workflows), Docker (si Dockerfile), Tests (si suite détectée) - **Optional :** Coverage, Platform, Version **Format Shield.io :** ```markdown [![Label](https://img.shields.io/badge/Label-Value-Color)](URL) ```text **Présentation :** ```text 📛 Badges suggérés pour [Project Name]: ✓ License: MIT ✓ Language: Python 3.12+ ✓ CI Status: GitHub Actions ✓ Docker: Ready ✓ Tests: 47 passed ? Coverage: 92% ? Version: v1.0.0 Voulez-vous garder tous ces badges ? Modifications ? ```text **User response :** Valider/ajuster ### Step 2.2: GitHub About Description (<350 chars) Proposer **3 versions** optimisées : **Version A - Technical :** Focus sur stack et fonctionnalités précises **Version B - Marketing :** Focus sur valeur ajoutée et problème résolu **Version C - Pedagogical :** Focus sur apprentissage et accessibilité **Exemple :** ```text Version A (Technical) - 248 chars: "High-performance CLI tool for automated Docker container security scanning using Trivy and Grype. Supports multi-arch builds, parallel scanning, SARIF output, GitHub Actions integration. Written in Go 1.23+." Version B (Marketing) - 234 chars: "Secure your Docker containers effortlessly. Automated vulnerability scanning with instant reports, CI/CD integration, and zero-config setup. Perfect for DevOps teams who value security without complexity." Version C (Pedagogical) - 285 chars: "Learn Docker security by doing. Beginner-friendly CLI tool that guides you through container vulnerability scanning step-by-step, explains CVEs in plain language, and teaches best practices. No prior security knowledge required." Choisissez une version ou mixez des éléments. ```text **User response :** Sélectionner/mixer/custom **Output :** Description finalisée <350 chars (idéalement 330-349) ### Step 2.3: 20 GitHub Topics Générer 20 topics groupés par catégorie : **Categories :** - Languages (3-4 topics) - Technologies (4-5 topics) - Domain (4-5 topics) - Ecosystem (3-4 topics) - Audience/Purpose (2-3 topics) **Exemple :** ```text 🏷️ Topics suggérés (20 total): [Languages] python, bash, powershell [Technologies] docker, github-actions, cli, automation, security [Domain] vulnerability-scanning, devops, container-security, trivy, grype [Ecosystem] docker-security, ci-cd, sarif, sbom [Audience] beginner-friendly, tutorial, learning Validez-vous cette liste ? Modifications ? ```text **Rules :** - Lowercase uniquement - Hyphens (pas spaces/underscores) - Max 50 chars par topic - Aligné avec taxonomie GitHub **User response :** Valider/modifier ### Step 2.4: README Sections (13 Standard Sections) **Template standardisé (ordre fixe) :** 1. **Badges** (validés en 2.1) 2. **Description courte + contexte** (2-3 paragraphes) 3. **Table des matières** (auto-générée) 4. **Pourquoi ce projet ?** (Problem statement + motivation) 5. **Fonctionnalités** (Feature list avec descriptions) 6. **Prérequis** (System requirements, dependencies, versions) 7. **Installation** (Instructions step-by-step) 8. **Usage/Exemples** (Cas d'usage communs avec code) 9. **Configuration** (Variables d'environnement, fichiers config) 10. **Tests** (Comment lancer la suite de tests) 11. **Contribution** (Comment contribuer, standards) 12. **License** (Type + lien vers LICENSE file) 13. **Auteur** (valorisa + lien GitHub) **Workflow collaboratif :** Pour chaque section : 1. Claude propose un draft basé sur l'analyse Phase 1 2. User valide/ajuste 3. Claude passe à la section suivante **Questions clés :** - Section 4 : "Quel problème résout ce projet ?" - Section 5 : "Fonctionnalités manquantes dans l'analyse ?" - Section 7 : "Étapes spéciales d'installation ?" - Section 8 : "3 cas d'usage les plus courants ?" - Section 9 : "Variables d'environnement importantes ?" - Section 10 : "Comment lancer les tests ?" ### Step 2.5: Visual Content (Mix Adaptatif) **Basé sur le type de projet détecté :** **CLI Tool :** - Screenshots de terminal (commandes + résultats) - Optionnel : Asciinema recordings **Library :** - Exemples de code exhaustifs avec commentaires ligne par ligne - API documentation (signatures, paramètres) **Application :** - Screenshots UI (écrans clés, workflows) - Exemples de code (intégration) - Optionnel : Diagrammes d'architecture **Action :** Demander assets visuels si applicable **Organisation images :** - Stockage : `docs/images/` ou `assets/images/` - Noms descriptifs : `installation-output.png`, `scan-results.png` - Références : `![Alt](docs/images/file.png)` ### Step 2.6: Finalization README.md 1. Compiler toutes les sections validées 2. Générer table des matières avec anchor links 3. Valider liens internes 4. Ajouter language switcher en haut : ```markdown 🇺🇸 [English](README.md) | 🇫🇷 [Français](README.fr.md) ``` 1. Présenter README.md complet pour revue finale **User response :** Approuver ou ajuster ## Phase 3: README.fr.md (French) - Translation ### Step 3.1: Full Translation Traduire README.md en français en préservant : - Structure (mêmes sections, même ordre) - Formatting (headers, listes, code blocks, liens) - Termes techniques en anglais (code, commandes, noms d'outils) **Keep in English :** - Code snippets, commands, variable names - URLs, GitHub usernames - Acronymes techniques (CLI, API, CI/CD) - Noms d'outils (Docker, npm, pip) **Translate to French :** - Prose, descriptions, explications - Headers de sections - Items de listes (sauf code) - Alt text d'images **Tone :** Maintenir le ton pédagogique en français ### Step 3.2: French README Review Présenter README.fr.md complet avec highlights sur sections ambiguës **User response :** Valider ou ajuster ### Step 3.3: Cross-Language Links Ajouter switcher dans les deux fichiers : ```markdown 🇺🇸 [English](README.md) | 🇫🇷 [Français](README.fr.md) ```text ## Phase 4: CI Markdown Linting ### Step 4.1: Create `.markdownlint.json` **Configuration stricte + exceptions courantes :** ```json { "default": true, "MD013": false, "MD033": false } ```text **Rationale :** - `MD013`: Disable line length (URLs longues, code blocks) - `MD033`: Allow inline HTML (badges Shield.io, image sizing) ### Step 4.2: Create GitHub Actions Workflow **File :** `.github/workflows/markdown-lint.yml` ```yaml name: Markdown Lint on: push: paths: - '**.md' pull_request: paths: - '**.md' jobs: markdown-lint: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Run MarkdownLint uses: DavidAnson/markdownlint-cli2-action@v16 with: globs: '**/*.md' ```text **Behavior :** - Triggers : push/PR sur `*.md` - Scope : Tous les `*.md` du repo - Failure : Pipeline fail si violations - Success : Green checkmark si zéro violations ### Step 4.3: Local Validation & Correction **Action :** 1. Lancer MarkdownLint localement sur tous `*.md` 2. Reporter les violations catégorisées **Classification :** **Simple (Auto-Fix) :** - MD009: Trailing spaces → Strip - MD010: Hard tabs → Convert to spaces - MD012: Multiple blank lines → Reduce to 1 - MD022: Header spacing → Add blank lines - MD032: List spacing → Add blank lines **Delicate (Consult User) :** - MD001: Header level skip → Structural issue ? - MD025: Multiple H1 → Quel H1 garder ? - MD033: Inline HTML in prose → Rewrite as Markdown ? **Process :** 1. Auto-fix simple violations 2. Présenter delicate violations avec options 3. User choisit action 4. Re-run linter 5. Répéter jusqu'à zéro violations ### Step 4.4: Commit Linting Config ```bash git add .markdownlint.json .github/workflows/markdown-lint.yml git commit -m "Add Markdown linting CI with strict rules - Configure MarkdownLint with exceptions for MD013/MD033 - Add GitHub Actions workflow for automated validation - Validate on push/PR for any *.md file changes Co-Authored-By: Claude Sonnet 4.5 (1M context) " ```text ## Phase 5: Finalization ### Step 5.1: Commit README Files ```bash git add README.md README.fr.md git commit -m "Add comprehensive bilingual README (EN/FR) - Pedagogical documentation for novice users - 13 standard sections (badges, installation, usage, etc.) - Visual content adapted to project type - Cross-language navigation links - Zero MarkdownLint violations Co-Authored-By: Claude Sonnet 4.5 (1M context) " ```text ### Step 5.2: GitHub About Configuration Instructions Fournir instructions step-by-step pour configurer About section : ```text 📝 GitHub About Section Configuration: 1. Navigate to: https://github.com/valorisa/[repo-name] 2. Click ⚙️ icon next to "About" 3. Fill in: Description (XXX/350 chars): [texte optimisé] Website: [URL du repo] Topics (20): [liste comma-separated] 4. Check boxes: ☑ Releases ☑ Packages 5. Save changes ✅ GitHub About configured! ```text ### Step 5.3: Push & Verify CI ```bash git push origin main ```text Vérifier workflow CI passe : ```bash gh run list --workflow=markdown-lint.yml --limit 1 ```text **Expected :** ✓ Markdown Lint (green checkmark) **Si CI fail :** Investiguer et corriger **User notification :** ```text ✅ Standardization Complete! Files committed: - README.md (English) - README.fr.md (French) - .markdownlint.json - .github/workflows/markdown-lint.yml Pushed to: https://github.com/valorisa/[repo-name] CI Status: ✅ Passing Next steps: 1. Configure GitHub About section (instructions above) 2. Review README rendering on GitHub ```text ## Manual Invocation via Skill L'utilisateur peut aussi invoquer manuellement : `/standardize-github-repo` **Action :** Lancer immédiatement le processus complet (Phases 0-5) sur le repo courant, sans attendre les triggers. ## Related Memory Lié à [[feedback_github_repo_standards]] qui définit les standards obligatoires. ## Implementation Notes - Process documentation complète : [[../../docs/superpowers/specs/2026-05-27-github-standardization-process-design.md]] - Skill Claude Code disponible : valorisa/Claude-Skills/skills/standardize-github-repo/