starter

Shapsha — Python Quality Plugin for Claude Code

Automatise les pratiques qualité Python en un seul pipeline : lint, sécurité, tests, docs, commit et PR — tout ça depuis Claude Code.

Chaque finding est soit corrigé automatiquement, soit corrigé avec ton consentement, soit refusé avec une raison structurée. Rien n'est ignoré silencieusement.

---

⚡ Quick Start

# 1. Lancer Claude Code
claude

# 2. Ajouter le marketplace
/plugin marketplace add NASSWIEL/Shapsha

# 3. Installer le plugin
/plugin install starter@Shapsha

# 4. Initialiser ton projet
/starter:proj-init

# 5. Valider et shipper
/starter:preflight

---

🔧 Comment ça fonctionne

Chaque skill agit sur le diff git par défaut (fichiers modifiés uniquement). Passe l'argument all pour agir sur tout le codebase.

Pipeline /starter:preflight

graph TD
    A[git staged changes] --> B{Guards}
    B -->|gh absent / pas auth| HALT1[Halted]
    B -->|rien à committer| HALT2[Halted]
    B -->|ok| C

    C[Step 1 · check-style] --> D[Step 2 · security]
    D --> E[Step 3 · gen-tests]
    E --> F[Step 4 · pytest full suite]
    F --> G[Step 5 · doc-sync]
    G --> H[Step 6 · readme-sync]
    H --> I[Step 7 · commit message gate]
    I --> J[Step 8 · commit · push · PR]
    J --> K[✅ PR URL]

    C -.->|findings refusés| C2[Step 5 consent]
    D -.->|user decline| HALT3[Halted]
    F -.->|tests fail| HALT4[Halted]

Architecture fan-out

Les skills check-style, security, gen-tests et doc-sync lancent N sous-agents en parallèle — un par fichier, tous dans un seul message. Résultat : le temps d'exécution = celui du fichier le plus lent, pas la somme de tous.

Parent skill
     │
     ├── agent fichier A  ──┐
     ├── agent fichier B  ──┤ → agrégation → résumé final
     └── agent fichier C  ──┘

---

📋 Commandes

Commande	Quand l'utiliser	Ce qu'elle fait
/starter:proj-init	Une fois, à la création du projet	Détecte l'environnement, installe les outils, dépose configs et templates
/starter:check-style	Après avoir modifié des .py	ruff (Pass 1) + LLM (Pass 2) — docstrings, renommages, sécurité, complexité
/starter:security	Après avoir modifié des .py	bandit + analyse LLM (auth, injection, secrets, crypto) — consentement unique
/starter:gen-tests	Après avoir ajouté / modifié du code	Génère les tests manquants, triage mécanique/sémantique, améliore le code source si besoin
/starter:doc-sync	Après un changement d'API publique	Met à jour docs/*.md depuis le diff git
/starter:readme-sync	Après un changement de surface utilisateur	Met à jour README.md (CLI, env vars, dépendances)
/starter:commit	Pour committer manuellement	Compose un Conventional Commit, valide via gitlint
/starter:commit-push-pr	Pour shipper une feature	Commit + push + PR (titre EN, corps FR 1–3 bullets)
/starter:preflight	Avant chaque PR	Pipeline complet, output = URL de la PR

Argument all disponible sur check-style, security et gen-tests : agit sur tout le codebase au lieu du diff.

---

🚀 Pipeline Preflight en détail

/starter:preflight est séquentiel, halt-on-failure. Output sur succès : l'URL de la PR.

#	Étape	Comportement
1	check-style	Jamais halt — tout est corrigé ou refusé avec raison
2	security	Halt si l'utilisateur refuse le consentement ou si des findings restent
3	gen-tests	Halt si collection fail ou si les tests sémantiques restent en échec après 2 itérations
4	pytest -q (full suite)	Halt si exit non-zero
5	doc-sync	Halt si le patch ne s'applique pas
6	readme-sync	Halt si le patch ne s'applique pas
7	Commit message gate	Compose + valide via gitlint. Réécrit une fois si rejeté
8	commit-push-pr	Halt si gh pr create échoue

Gardes initiales (dans l'ordre) :

1. Pas de repo git → halt
2. Aucun changement → halt
3. gh CLI absent → halt
4. gh non authentifié → halt
5. Changements uniquement unstaged → auto-stage (git add -u + .py/.md/pyproject.toml) puis continue

---

🤖 Sous-agents

Contexte isolé · périmètre UN fichier · mode silencieux · résultat en une ligne.