electron-rare/Kill_LIFE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add workflows and templates for design reviews, release processes, and compliance checks

Browse Source 
- Introduced new documentation for design reviews (DR0/DR1) and release rituals.
- Created templates for Architecture Decision Records (ADR), Design Reviews, Playtest Reports, and Validation Plans.
- Established workflows for consulting, creative processes, systems engineering, R&D spikes, and compliance/QA.
- Implemented GitHub Actions workflows for firmware and hardware CI with required checks strategy.
- Added setup script for repository configuration, including label creation and branch protection.
- Developed installation script for Kill_LIFE with system updates and environment setup.
This commit is contained in:
Clément SAILLANT
2026-02-19 01:35:10 +01:00
parent dda793c0ef
commit d7ffbf14cf
56 changed files with 2413 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/copilot-instructions.md
View File
INSTALL.md
+31
View File
@@ -0,0 +1,31 @@
# Installation
Voir la version détaillée : `docs/INSTALL.md`.
## Prérequis
- Git
- Python 3.10+
- (optionnel) PlatformIO pour compiler le firmware
- (optionnel) KiCad pour le hardware
## Setup local (minimal)
```bash
python -m venv .venv
source .venv/bin/activate
pip install platformio
cd firmware
pio run -e esp32s3_idf || true
pio test -e native || true
```
## Setup GitHub (indispensable)
1. Créer les labels `ai:*` : `ai:spec ai:plan ai:tasks ai:impl ai:qa ai:docs ai:hold`
2. (Optionnel) Créer les labels `type:*` : `type:consulting type:systems type:design type:creative type:spike type:compliance`
3. Ajouter les secrets si utilisés (ex : `OPENAI_API_KEY`, `COPILOT_GITHUB_TOKEN`)
4. Vérifier que GitHub Actions est activé
## Démarrer
- Ouvrir une issue via un template (dans `.github/ISSUE_TEMPLATE/`)
- Triage (prio/risque/scope)
- Ajouter un label `ai:*` pour déclencher l’automatisation
README.md
+229 -55
View File
@@ -1,64 +1,238 @@
# Kill\_LIFE — AI‑Native Embedded Project Template
Bienvenue dans **Kill\_LIFE**, un modèle de dépôt pensé pour développer des systèmes embarqués à l’ère des agents. L’objectif est simple : offrir une structure prête à l’emploi qui combine spécifications formalisées, automatisation via agents, gestion multi‑cibles (ESP32/STM32/Linux), et pratiques de sécurité adaptées au développement assisté par IA.
# Kill_LIFE 🚀 — AI-Native Embedded Project Template
## ✨ Inspirations et principes
![Kill_LIFE Banner](https://raw.githubusercontent.com/electron-rare/Kill_LIFE/main/docs/assets/banner_kill_life.png)
Ce projet s’inspire de plusieurs initiatives et bonnes pratiques :
Bienvenue dans **Kill_LIFE**, le template open source pour systèmes embarqués IA, où les specs rêvent d’électron-ironique, les agents QA se prennent pour des réplicants (voir [Le Réplicant](https://fr.wikipedia.org/wiki/Blade_Runner)), et le pipeline ne panique jamais grâce à sa serviette (voir [Don’t Panic](https://hitchhikers.fandom.com/wiki/Don%27t_Panic)), même en cas d’apocalypse. Ici, chaque commit est validé, chaque gate est passé, et chaque evidence pack est rangé comme dans [le meilleur des mondes](https://fr.wikipedia.org/wiki/Le_Meilleur_des_mondes). Si tu cherches la réponse à la question ultime du développement embarqué IA, c’est probablement [42](https://fr.wikipedia.org/wiki/42_(nombre))… ou un bulk edit réussi ([Bulk Edit Party FX](https://www.youtube.com/watch?v=dQw4w9WgXcQ)).
- **GitHub Agentic Workflows** : les workflows agentiques de GitHub, qui introduisent une chaîne de sanitisation de l’input (neutralisation des mentions, filtrage des URLs, limitation de taille) et l’utilisation de *safe outputs* pour limiter les privilèges des agents. Ces principes guident notre pipeline d’automatisation【420659683624566†L747-L857】【11582546369719†L160-L168】.
- **Alertes sur l’injection de prompt** : des rapports comme celui d’Aikido Security détaillent comment des contenus d’issues non fiables peuvent détourner un agent et recommandent d’éviter d’injecter du texte non filtré dans les prompts, de restreindre les outils disponibles et de traiter toute sortie de l’agent comme non fiable【885973626346785†L218-L231】.
- **Réduction du rayon d’explosion** : le guide *prompt‑injection‑defenses* rappelle qu’il faut concevoir en assumant que les injections ne seront jamais totalement éliminées. Cela implique de limiter les privilèges, de vérifier et de sanitariser systématiquement les entrées et sorties et de séparer les rôles【408877418785616†L277-L304】.
- **Enforcement des labels PR** : pour forcer les PR à respecter un flux précis, nous nous appuyons sur l’idée de l’action GitHub *enforce‑pr‑labels*, qui permet d’exiger qu’une PR contienne certains labels ou d’en bloquer d’autres【613342446189111†L283-L299】.
- **Licences open source** : le code source est sous licence MIT, les fichiers matériels sous licence **CERN OHL v2** (promouvant la liberté d’utiliser, d’étudier, de modifier et de partager des conceptions matérielles【572981070514051†L86-L91】) et la documentation sous **CC‑BY 4.0**, qui autorise le partage et l’adaptation avec attribution【335439356583797†L59-L75】.
> "La réponse à la question ultime de la vie, de l’univers et du développement embarqué IA : 42 specs, 7 agents, et un pipeline qui ne panique jamais."
> — H2G2, version Kill_LIFE
## 🔧 Fonctionnalités clés
> "Kill_LIFE, c’est l’open source embarqué version IA, mais aussi un clin d’œil à la fin du monde : ici, on ne craint ni l’apocalypse, ni les bugs, ni les injections de prompt. On rêve, on code, on documente, et on fait des bulk edits comme des réplicants en quête de compliance."
> — Le README qui ne panique jamais
- **Développement guidé par la spécification** : écrivez votre spécification (user stories, contraintes, architecture) dans `specs/`. C’est la source de vérité. Des scripts de validation et un schéma garantissent la cohérence.
- **Multi‑agents** : des prompts prédéfinis pour les rôles PM, Architecte, Firmware, QA, Doc et Hardware (BMAD/AgentOS) orchestrent les étapes de la conception et de la mise en œuvre.
- **Automation L3 avec sécurité intégrée** : les workflows GitHub Agentic Workflows (Option A) transforment une issue en Pull Request en appliquant une sanitisation stricte et en créant la PR via un *safe output*. Un fallback sur `ai:impl` est possible si aucune étiquette n’est présente, mais vous pouvez activer l’option label obligatoire pour renforcer la gouvernance.
- **Sanitisation renforcée des issues** : un script Python élimine balises HTML, blocs de code, URLs externes, mentions et commandes potentiellement dangereuses avant que le texte ne soit injecté dans un prompt (voir `tools/ai/sanitize_issue.py`).
- **Contrôle des étiquettes** : un workflow impose qu’une PR contienne au moins un label `ai:*` (`ai:spec`, `ai:plan`, `ai:tasks`, `ai:impl`, `ai:qa`, `ai:docs`). Sans label, la PR est annotée par défaut avec `ai:impl` ou rejetée selon votre politique.
- **Scope guard par label** : chaque label détermine les dossiers modifiables (par exemple, `ai:spec` autorise `specs/` et `docs/` ; `ai:impl` autorise `firmware/`). Si un fichier en dehors de la liste est modifié, le gate échoue.
- **Multi‑cibles et firmware portable** : le dossier `firmware/` contient des environnements PlatformIO pour ESP32 (ESP‑IDF) et STM32, ainsi que des tests `native` pour valider la logique côté hôte. Ajoutez vos cibles personnalisées dans `firmware/targets/`.
- **Pipeline matériel** : `hardware/` propose des projets KiCad et des scripts pour générer le schéma, valider les règles (DRC/ERC) et exporter la nomenclature. Les profils de conformité (ex : `iot_wifi_eu`) s’appuient sur les standards dans `standards/`.
- **OpenClaw en mode observateur** : OpenClaw peut appliquer des labels ou laisser des commentaires sanitisés sur les issues/PR sans jamais écrire dans le code. Son exécution doit se faire en bac à sable, sans secrets【57263998884462†L355-L419】.
## 🚀 Prise en main rapide
1. **Créer votre spécification** : copiez/complétez un modèle dans `specs/` ou utilisez `python tools/ai/specify_init.py --name votre-feature` pour générer un squelette.
2. **Définir votre profil** (prototype ou iot\_wifi\_eu) via `python tools/compliance/use_profile.py`.
3. **Développement firmware** : installez PlatformIO (`pip install platformio`), puis :
```bash
cd firmware
pio run -e esp32s3_idf # build
pio test -e native # tests unitaires hôte
```
4. **Lancer un agent** : ouvrez une issue et ajoutez l’étiquette appropriée (`ai:spec`, `ai:plan`, etc.). Le workflow agentique crée une PR avec un diff minimal, les tests et un résumé humain.
5. **Contrôler les PR** : la CI exécute des gates (build/tests/validation spec). Un scope guard vérifie que les modifications respectent le label.
6. **Lire la documentation** : les dossiers `docs/` et `standards/` contiennent des guides (setup KiCad, sécurité, compliance) et des standards versionnés injectés par AgentOS.
## 🗂 Arborescence principale
- `specs/` : spécifications, architectures, plans et tâches.
- `standards/` : standards globaux (firmware, hardware, tests), profils de conformité.
- `bmad/` : rôles, rituels et gabarits de handoff pour orchestrer les agents.
- `agents/` : prompts pour chaque rôle.
- `tools/` : scripts AI (sanitisation, prompts), cockpit de génération, gates et validateurs.
- `firmware/` : projet PlatformIO (targets + tests).
- `hardware/` : projets KiCad et scripts de génération.
- `.github/` : workflows CI (build/test, scope guard, enforcement labels) et agents markdown (Option A).
- `openclaw/` : configuration et règles pour OpenClaw en mode observateur.
- `licenses/` : copies/summaries des licences MIT, CERN OHL v2 et CC BY 4.0.
## 📄 Licences
Le code source est diffusé sous **MIT**. Les fichiers matériels (KiCad, mécaniques, BOM) sont sous **CERN OHL v2 Permissive**, encourageant la collaboration et la liberté d’étudier et partager les designs【572981070514051†L86-L91】. La documentation et les spécifications sont sous **Creative Commons BY 4.0**, permettant la réutilisation et l’adaptation avec attribution【335439356583797†L59-L75】.
## 🤝 Contribuer
Les contributions sont les bienvenues ! Vous pouvez proposer de nouveaux profils cibles, améliorer les scripts de gating ou enrichir les standards. N’oubliez pas de suivre la politique anti‑injection décrite dans `docs/security/anti_prompt_injection_policy.md` et d’ajouter des tests avec vos changements.
le meilleur des fin de monde ?
---
## 🧩 Architecture & Principes
- **Spec-first** : Chaque évolution commence par une définition claire dans `specs/` ([Spec Generator FX](https://www.youtube.com/watch?v=9bZkp7q19f0)).
- **Standards injection** : Standards versionnés + profils injectés (Agent OS).
- **BMAD / BMAD-METHOD** : Agents par rôles (PM, Architect, Firmware, QA, Doc, HW), rituels, gates, handoffs ([agents/](agents/), [bmad/](bmad/)).
- **Tool-first** : Scripts reproductibles ([tools/](tools/)), evidence pack dans `artifacts/`.
- **Pipeline hardware/firmware** : Bulk edits, exports, tests, compliance, snapshots ([Les particules font-elles l’amour ?](https://lelectron-fou.bandcamp.com/album/les-particules-font-elles-l-amour-la-physique)).
- **Sécurité & conformité** : Sanitisation, safe outputs, sandboxing, scope guard, anti-prompt injection ([OpenClaw Sandbox](https://www.openclaw.io/)).
> "Les particules rêvent-elles d’électron-ironique ? Peut-être font-elles l’amour dans le dossier hardware, pendant que les agents QA se demandent si la conformité est un rêve ou une réalité."
> — Inspiré par Le Réplicant de K. Dick & Les particules font-elles l’amour
> "Bienvenue dans le meilleur des mondes : ici, chaque commit est validé, chaque gate est passé, et chaque agent sait que la vraie liberté, c’est d’avoir un evidence pack bien rangé."
> — Aldous Huxley, version CI/CD
---
## ✨ Fonctionnalités principales
- **Développement guidé par la spec** : User stories, contraintes, archi, plans, backlog.
- **Automatisation** : Issue → PR avec tests unitaires, sanitisation, evidence pack.
- **Multi-cibles** : ESP32, STM32, Linux, tests natifs.
- **Pipeline matériel** : KiCad, exports SVG/ERC/DRC/BOM/netlist, bulk edits.
- **Compliance** : Profils injectés, validation automatique.
- **OpenClaw** : Labels & commentaires sanitisés, jamais de commit/push, sandbox obligatoire.
---
## 🖥️ Arborescence graphique
```mermaid
flowchart TD
A[📄 specs/ — Source de vérité] --> B[⚙️ standards/ — Standards & profils]
A --> C[🧑‍🤝‍🧑 bmad/ — Rituels, gates, handoffs]
A --> D[🤖 agents/ — Prompts par rôle]
A --> E[🛠️ tools/ — Scripts AI, cockpit, compliance]
A --> F[💾 firmware/ — PlatformIO, tests, multi-cibles]
A --> G[🔩 hardware/ — KiCad, bulk edits, exports]
A --> H[🦞 openclaw/ — Sandbox, labels, commentaires]
A --> I[📜 licenses/ — MIT, CERN OHL v2, CC-BY 4.0]
A --> J[🛡️ .github/ — CI, scope guard, enforcement labels]
F --> K[🧪 tests natifs]
G --> L[📊 exports ERC/DRC/BOM/netlist]
E --> M[🦾 Evidence pack]
H --> N[🔒 Sanitisation, safe outputs]
```
---
## 🚀 Installation & initialisation
### Prérequis
- Python ≥ 3.8
- PlatformIO
- KiCad 9
- mkdocs
- Docker (optionnel)
### 1. Cloner le repo
```bash
git clone https://github.com/electron-rare/Kill_LIFE.git
cd Kill_LIFE
```
### 2. Initialiser la spec
```bash
python tools/ai/specify_init.py --name <feature-or-epic>
```
### 3. Choisir le profil compliance
```bash
python tools/compliance/use_profile.py --profile prototype
```
### 4. Installer les dépendances firmware
```bash
cd firmware
python -m pip install -U platformio
```
### 5. Build & tests firmware
```bash
pio run -e esp32s3_arduino
pio test -e native
```
### 6. Pipeline hardware (KiCad)
```bash
bash tools/hw/hw_gate.sh hardware/kicad
python tools/watch/watch_hw.py
```
### 7. Générer la documentation
```bash
python -m pip install -U mkdocs
mkdocs build --strict
```
### 8. Docker (optionnel)
Si un fichier docker-compose.yml est présent :
```bash
sudo docker-compose up -d
```
---
## 🛠️ Fonctions clés
- **specs/** : Source de vérité, plans, backlog.
- **standards/** : Standards globaux, profils injectés.
- **bmad/** : Gates, rituels, templates.
- **agents/** : Prompts pour chaque rôle.
- **tools/** : Scripts AI, cockpit, compliance, watch.
- **firmware/** : PlatformIO, tests Unity, multi-cibles.
- **hardware/** : KiCad, bulk edits, exports.
- **openclaw/** : Labels, commentaires, sandbox.
- **.github/** : Workflows CI, scope guard, enforcement labels.
- **licenses/** : MIT, CERN OHL v2, CC-BY 4.0.
---
## 🦾 Workflows agents
- **Issue → PR** : Label `ai:*` obligatoire, sanitisation, diff minimal, tests auto. (Ne panique jamais et garde ta serviette !)
- **Scope guard** : Label détermine les dossiers modifiables.
- **Evidence pack** : Tous les rapports dans `artifacts/<domain>/<timestamp>/` (rangé comme dans une dystopie bien organisée).
- **Compliance** : Validation stricte via scripts.
### Exemples de workflows
#### 1. Spécification → Implémentation Firmware
1. Rédige la spec dans `specs/` (mode Gangnam Style https://www.youtube.com/watch?v=9bZkp7q19f0 !).
2. Ouvre une issue avec le label `ai:spec`.
3. L’agent PM/Architect génère le plan et l’architecture.
4. L’agent Firmware implémente le code dans `firmware/`.
5. L’agent QA ajoute des tests Unity.
6. Evidence pack généré automatiquement.
#### 2. Bulk Edit Hardware KiCad
1. Ouvre une issue avec le label `ai:hw`.
2. L’agent HW effectue un bulk edit via `tools/hw/schops` (fête le bulk edit avec [Bulk Edit Party FX](https://www.youtube.com/watch?v=dQw4w9WgXcQ)).
3. Exporte ERC/DRC, BOM, netlist.
4. Snapshot avant/après dans `artifacts/hw/<timestamp>/`.
#### 3. Documentation & Compliance
1. Ouvre une issue avec le label `ai:docs` ou `ai:qa`.
2. L’agent Doc met à jour `docs/` et le README.
3. L’agent Compliance valide le profil et génère le rapport.
---
## 📝 Installation & Sécurité
- Un guide d’installation détaillé ([INSTALL.md](INSTALL.md)) explique comment installer le projet, configurer les environnements, sécuriser OpenClaw, lancer les tests hardware, générer la documentation, et utiliser Docker.
- Un script d’installation unique ([install_kill_life.sh](install_kill_life.sh)) automatise tout : dépendances, spec, profil compliance, environnement Python, modules AI/hardware/firmware, tests, doc, Docker, et vérification de la sécurité OpenClaw.
- Sécurité OpenClaw : sandbox obligatoire, jamais d’accès aux secrets ou au code source.
- Tests hardware reproductibles via scripts documentés.
---
## 🧬 Architecture agentique avancée
- Structure multi-agent (BMAD) : rôles PM, Architect, Firmware, QA, Doc, HW, orchestrés par rituels, gates et handoffs.
- Développement spec-first : chaque évolution commence par une spécification, standards versionnés et profils injectés.
- Automatisation & sécurité : workflows CI, sanitisation, safe outputs, scope guard, anti-prompt injection, OpenClaw sandbox.
- Multi-cibles & pipelines reproductibles : ESP32, STM32, Linux, tests natifs, bulk edits hardware KiCad, exports automatisés.
- Documentation claire & onboarding : README détaillé, FAQ, workflows, arborescence graphique, guides d’installation, politique de contribution.
---
## 🚀 Conventions, contribution & cross-platform
- Toutes les conventions, instructions d’installation, sécurité, multi-agents, compliance, workflows, et support cross-platform (Docker inclus) sont synthétisées.
- Architecture, étapes d’initialisation, fonctions clés, sécurité OpenClaw, contribution.
---
## ❓ FAQ
**Q : Comment démarrer rapidement ?**
A : Suis la section "Installation & initialisation" ou le guide INSTALL.md.
**Q : Comment installer tout automatiquement ?**
A : Utilise le script `install_kill_life.sh`.
**Q : Comment sécuriser OpenClaw ?**
A : Sandbox obligatoire, jamais d’accès aux secrets ou au code source.
**Q : Comment lancer les tests hardware ?**
A : Suis les scripts documentés dans le README et INSTALL.md.
**Q : Comment contribuer ?**
A : Ajoute des profils, améliore les scripts, enrichis les standards, et suis la politique anti-injection.
---
## 🦾 Workflows détaillés
### 1. Spécification → Implémentation Firmware
1. Rédige la spec dans `specs/`.
2. Ouvre une issue avec le label `ai:spec`.
3. L’agent PM/Architect génère le plan et l’architecture.
4. L’agent Firmware implémente le code dans `firmware/`.
5. L’agent QA ajoute des tests Unity.
6. Evidence pack généré automatiquement.
### 2. Bulk Edit Hardware KiCad
1. Ouvre une issue avec le label `ai:hw`.
2. L’agent HW effectue un bulk edit via `tools/hw/schops`.
3. Exporte ERC/DRC, BOM, netlist.
4. Snapshot avant/après dans `artifacts/hw/<timestamp>/`.
### 3. Documentation & Compliance
1. Ouvre une issue avec le label `ai:docs` ou `ai:qa`.
2. L’agent Doc met à jour `docs/` et le README.
3. L’agent Compliance valide le profil et génère le rapport.
---
Ce dépôt vise à offrir un point de départ moderne pour des projets embarqués assistés par IA, en conciliant innovation et sécurité. Explorez, adaptez et bâtissez votre prochain projet en toute confiance !
RUNBOOK.md
+21
View File
@@ -0,0 +1,21 @@
# Runbook opérateur
Voir la version détaillée : `docs/RUNBOOK.md`.
## Flux standard (Issue → PR)
1. Créer une issue (idéalement via un template)
2. Ajouter les labels de triage : `type:*`, `prio:*`, `risk:*`, `scope:*`
3. Ajouter le label `ai:*` adapté :
- `ai:spec` → spec RFC2119 + AC
- `ai:plan` → architecture + ADR
- `ai:tasks` → backlog exécutable
- `ai:impl` → impl + tests
- `ai:qa` → durcissement
- `ai:docs` → docs
4. La CI applique : label enforcement + scope guard + build/tests
## Stop
- Ajouter `ai:hold` sur l’issue/PR
## Workflows métiers
Voir `docs/workflows/README.md`.
docs/FAQ.md
+24
View File
@@ -0,0 +1,24 @@
# FAQ
## Pourquoi des labels `ai:*` ?
Ils servent à deux choses :
1) déclencher des étapes agentiques (spec/plan/tasks/impl/qa/docs)
2) définir le **scope autorisé** via le scope guard (allowlist par label).
## Comment arrêter l’automation ?
Ajoute le label `ai:hold` sur l’issue ou la PR. Traite ensuite le ticket manuellement.
## Pourquoi le sanitizer est “agressif” ?
Les issues/PR contiennent du texte non fiable (copié/collé, URLs, snippets). Le sanitizer retire ces zones à risque avant injection dans un prompt.
## Pourquoi OpenClaw est en “observateur” ?
Pour réduire la surface d’attaque : OpenClaw ne fait que labels/commentaires. Les actions d’écriture passent par les workflows GitHub (audités) et leurs gates.
## Le scope guard bloque ma PR, que faire ?
Soit :
- change le label `ai:*` vers celui qui correspond à tes modifications
- ou découpe en deux PRs (ex: docs vs firmware)
## Je ne veux pas que les templates d’issues déclenchent l’automation
Les templates Feature/Bug/Compliance/Agentics ajoutent maintenant des labels `ai:*` par défaut.
Si tu veux un mode “triage d’abord”, enlève le label `ai:*` après création, ou ajuste les templates.
docs/INSTALL.md
+86
View File
@@ -0,0 +1,86 @@
# INSTALL — Setup local + GitHub
## 0) Pré-requis
### Outils
- Git
- Python 3.10+ (3.11 recommandé)
- (Firmware) PlatformIO
- (Hardware) KiCad (optionnel)
- (Optionnel) GitHub CLI `gh`
### Accès GitHub
- Droits pour créer labels et secrets (ou admin)
- GitHub Actions activé
---
## 1) Installation locale
### 1.1 Cloner / initialiser
```bash
git clone <repo>
cd <repo>
```
### 1.2 Environnement Python
```bash
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install platformio
```
> Si le repo fournit `tools/requirements.txt`, installe-le en priorité.
### 1.3 Build & tests firmware (exemples)
```bash
cd firmware
pio run -e esp32s3_idf
pio test -e native
```
---
## 2) Setup GitHub (obligatoire pour l’automation)
### 2.1 Labels
Crée ces labels (exactement ces noms) :
**Automation**
- `ai:spec` `ai:plan` `ai:tasks` `ai:impl` `ai:qa` `ai:docs` `ai:hold`
**Workflows métiers (recommandé)**
- `type:consulting` `type:systems` `type:design` `type:creative` `type:spike` `type:compliance`
Optionnel : `prio:p0..p3`, `risk:low|med|high`, `scope:hardware|firmware|docs|ux|content`.
### 2.2 Secrets
Selon ta stack agentique, configure :
- `OPENAI_API_KEY`
- `COPILOT_GITHUB_TOKEN`
### 2.3 Branch protection (recommandé)
- Exiger que la CI soit verte avant merge
- Interdire le bypass (ou au minimum sur `.github/workflows/*`)
- 1 review obligatoire
---
## 3) Démarrer avec les templates
- Templates d’issues : `.github/ISSUE_TEMPLATE/`
- Workflows métiers : `docs/workflows/README.md`
- Evidence packs : `docs/evidence/evidence_pack.md`
---
## 4) Vérification “ça marche”
1. Ouvre une issue via un template (ex : “Cabinet — Intake / Cadrage”).
2. Vérifie qu’elle a le label `type:*` + `needs:triage`.
3. Ajoute `ai:spec`.
4. Vérifie qu’une PR est créée et que la CI passe (label enforcement + scope guard).
docs/LABELS.md
+25
View File
@@ -0,0 +1,25 @@
# Labels — taxonomie
## `ai:*` (automation)
- `ai:spec` : produire/mettre à jour specs (RFC2119, AC)
- `ai:plan` : architecture, options, ADR
- `ai:tasks` : backlog (WBS)
- `ai:impl` : impl + tests minimaux
- `ai:qa` : durcissement tests/edge
- `ai:docs` : documentation
- `ai:hold` : stop automation / incident
## `type:*` (workflow métier)
- `type:consulting` : cadrage cabinet
- `type:systems` : bureau d’études
- `type:design` : UX/UI produit
- `type:creative` : narration / contenu
- `type:spike` : R&D time‑boxed
- `type:compliance` : QA / release
## `scope:*` (zone)
- `scope:hardware` `scope:firmware` `scope:docs` `scope:ux` `scope:content` `scope:ci`
## `risk:*` / `prio:*`
- `risk:low|med|high`
- `prio:p0|p1|p2|p3`
docs/RUNBOOK.md
+47
View File
@@ -0,0 +1,47 @@
# RUNBOOK — Opérer les workflows agentiques
## 1) Règles d’or
- Le texte d’issue est **non fiable** → il est sanitisé avant prompt.
- **Un label `ai:*` = un scope** (le scope guard contrôle les fichiers modifiables).
- En cas de doute : `ai:hold`.
## 2) Flux standard (Issue → PR)
### 2.1 Créer une issue
Utilise un template : `.github/ISSUE_TEMPLATE/`.
### 2.2 Triage (humain)
Ajoute :
- `prio:*` (urgence)
- `risk:*` (risque)
- `scope:*` (zone)
- garde un `type:*`
### 2.3 Déclencher une étape d’automation
Ajoute un label `ai:*` :
- `ai:spec` → écrit/normalise la spec RFC2119 + AC
- `ai:plan` → architecture, options, ADR
- `ai:tasks` → backlog WBS exécutable
- `ai:impl` → impl minimal + tests
- `ai:qa` → durcit tests, edge cases
- `ai:docs` → docs, runbooks
> Si la PR n’a pas de label `ai:*`, le workflow ajoute `ai:impl` (fallback). Tu peux activer “label obligatoire” selon ta gouvernance.
### 2.4 CI (automatique)
- Label enforcement
- Scope guard
- Build/tests
- Compliance gates (si profil)
## 3) Stop / Incident
- Ajouter `ai:hold` sur issue/PR
- Revoir contenu + logs
- Vérifier que scope guard n’est pas contourné
## 4) Evidence pack
Voir `docs/evidence/evidence_pack.md`.
## 5) Workflows métiers
Voir `docs/workflows/README.md`.
docs/evidence/creative_pack.md
+14
View File
@@ -0,0 +1,14 @@
# Evidence pack — Créatif / contenu
## À inclure
- Manifests (liste des assets, IDs, durées)
- Liste des assets produits (fichiers)
- Checksums (sha256) ou hashes de build
- Notes de playtest (si applicable)
## Checklist
- [ ] Manifests valides (schema)
- [ ] Chaque ID référencé existe
- [ ] Formats respectés (mp3 mono/stéréo, bitrate)
- [ ] Taille totale compatible stockage
- [ ] Notes d’intégration (où c’est utilisé)
docs/evidence/evidence_pack.md
+34
View File
@@ -0,0 +1,34 @@
# Evidence pack (preuve) — standard
Un **evidence pack** est un ensemble d’artefacts qui rend une PR vérifiable et auditable.
## Objectif
- Prouver que la modification respecte la spec
- Prouver que les tests/gates ont tourné
- Permettre une review rapide
## Structure recommandée
Dans CI :
- `artifacts/<run-id>/ci/` : logs build/tests
- `artifacts/<run-id>/spec/` : spec/ADR exports
- `artifacts/<run-id>/hw/` : exports KiCad (pdf/png), BOM
- `artifacts/<run-id>/fw/` : bins, map files, size reports
- `artifacts/<run-id>/measures/` : conso/latence, protocoles
Dans le repo (docs) :
- `docs/adr/` : décisions
- `docs/reviews/` : DR0/DR1, checklists
## Checklist minimum PR
- [ ] Le label `ai:*` est présent et cohérent avec le contenu
- [ ] Scope guard passe
- [ ] Build + tests passent
- [ ] Spec/AC référencés
- [ ] Logs/artifacts attachés (ou links internes)
## “Red flags”
- Modifs de `.github/workflows/*` via agents
- Liens externes ajoutés dans le prompt / issue
- PR trop large, pas de tests
- Tentatives de modifier les scripts de sécurité
docs/evidence/spike_pack.md
+14
View File
@@ -0,0 +1,14 @@
# Evidence pack — Spike R&D
## À inclure
- Hypothèse + timebox
- Protocole de test (instrumentation)
- Données brutes (logs)
- Résultats (tableau / graph)
- Conclusion + décision
## Checklist
- [ ] Critères de succès explicités
- [ ] Protocole reproductible
- [ ] Résultats chiffrés
- [ ] Décision prise (industrialiser / re‑spike / abandon)
docs/handoffs/handoff_creative.md
+14
View File
@@ -0,0 +1,14 @@
# Handoff — Créatif / Contenu
## Bible / règles
## Scènes & triggers
## Assets
- Liste :
- Formats :
- Durées :
## Manifests
## Notes d’intégration
docs/handoffs/handoff_design.md
+19
View File
@@ -0,0 +1,19 @@
# Handoff — Design / UX
## Direction
## Parcours
## États
- Nominal :
- Erreurs :
- Loading :
## Mapping inputs
- Boutons :
- Gestes :
## Assets & naming
- Icônes :
- Fonts :
- Couleurs :
docs/handoffs/handoff_firmware.md
+23
View File
@@ -0,0 +1,23 @@
# Handoff — Firmware
## Contexte
## Interfaces
- GPIO :
- Bus (UART/SPI/I2C) :
- Protocoles :
## Contraintes
- Latence :
- Conso :
- Mémoire :
## Tests
- Unit :
- Integration :
- HIL :
## Artefacts
- Binaire :
- Logs :
- Evidence pack :
docs/handoffs/handoff_hardware.md
+23
View File
@@ -0,0 +1,23 @@
# Handoff — Hardware (KiCad)
## Contexte
## Design
- Schéma :
- PCB :
- BOM :
## Contraintes
- Power budget :
- Encombrement :
- Thermal :
## Tests
- ERC/DRC :
- Testpoints :
- Plan de bring-up :
## Exports
- PDFs :
- Gerbers :
- BOM/PNP :
docs/index.md
+26 -5
View File
@@ -1,12 +1,33 @@
# AI Agentic Embedded Base
Ce repo est un “socle” :
- specs d’abord
- standards injectés
- agents + gates
- exécution transparente via outils (cockpit)
Ce repo est un **socle** :
- **specs d’abord** (spec-driven)
- **standards injectés** (qualité & conformité)
- **agents + gates** (automation contrôlée)
- **exécution transparente** via outils (cockpit)
## Démarrer
- Installation : `docs/INSTALL.md`
- Runbook opérateur : `docs/RUNBOOK.md`
- FAQ : `docs/FAQ.md`
## Workflows professionnels (opérationnels)
- `docs/workflows/README.md` (menu)
- Templates d’issues : `.github/ISSUE_TEMPLATE/`
## Plans (runbooks)
- Série complète : `docs/plans/README.md`
## Labels
- Taxonomie : `docs/LABELS.md`
## Evidence packs, templates et rituels
- Evidence pack : `docs/evidence/evidence_pack.md`
- Templates : `docs/templates/`
- Handoffs : `docs/handoffs/`
- Rituels : `docs/rituals/`
docs/plans/01_plan_premiere_entree.md
+69
View File
@@ -0,0 +1,69 @@
# 1) Plan première entrée
## Objectif
Permettre à une personne nouvelle sur le repo de :
1. comprendre le système (spec‑driven + agentics)
2. faire tourner un cycle complet **Issue → PR → CI → merge**
3. produire un premier **evidence pack**.
## Quand l’utiliser
- Onboarding d’un dev / designer / ingénieur
- Après un gros refactor de workflows
- Avant une démo / un kick‑off projet
## Labels recommandés
- Issue : `type:feature`, `prio:p1`, `risk:low`
- Automation : `ai:spec` puis `ai:impl`
## Étapes
### 1. Setup GitHub (10 min)
- [ ] Créer les labels `ai:*` et `type:*` (voir `docs/LABELS.md`)
- [ ] Vérifier que les Actions sont activées
- [ ] Vérifier les secrets nécessaires (si utilisés) : `OPENAI_API_KEY`, `COPILOT_GITHUB_TOKEN`
### 2. Setup local (5–10 min)
- [ ] Créer un venv Python
- [ ] Installer PlatformIO
- [ ] Vérifier que `pio` fonctionne
Commandes :
```bash
python -m venv .venv
source .venv/bin/activate
pip install platformio
cd firmware
pio run -e esp32s3_idf || true
pio test -e native || true
```
### 3. Déclencher un flux agentique (10–15 min)
- [ ] Ouvrir une issue “Hello World” (ex : “Ajouter un heartbeat LED + log boot”) via template Feature
- [ ] Ajouter `ai:spec` → attendre la PR
- [ ] Relire la PR (spec RFC2119 + critères d’acceptation)
- [ ] Ajouter `ai:impl` sur la PR (ou sur l’issue, selon votre config) → attendre mise à jour
### 4. Vérifier CI / sécurité
- [ ] Label enforcement passe (PR contient au moins un `ai:*`)
- [ ] Scope guard passe (pas de fichiers hors scope)
- [ ] Build/test passent (ou sont “SKIP” justifié)
### 5. Evidence pack minimal
- [ ] La PR contient :
- [ ] lien vers l’issue
- [ ] logs CI pertinents (artefacts)
- [ ] capture du comportement (si UI/hardware)
## Gates
- `PR Label Enforcement` : label `ai:*` obligatoire
- `Scope Guard` : les fichiers modifiés doivent correspondre au label
- `Firmware build` + `native tests`
## Critère de sortie
✅ 1 PR mergée, CI verte, evidence pack attaché, et une personne capable de répéter le cycle seule.
## Références
- `docs/INSTALL.md`
- `docs/RUNBOOK.md`
- `docs/evidence/evidence_pack.md`
docs/plans/02_plan_brainstorming.md
+49
View File
@@ -0,0 +1,49 @@
# 2) Plan brainstorming
## Objectif
Capturer des idées, options et risques **sans déclencher trop tôt** de génération agentique ni d’implémentation.
## Quand l’utiliser
- Le besoin est flou
- Plusieurs options possibles
- Tu veux un output “cabinet” : options + tradeoffs + recommandation
## Labels recommandés
- `type:brainstorm` + `needs:decision` + `risk:low|med`
- ⚠️ Ne pas mettre `ai:*` tant que la question n’est pas cadrée.
## Étapes
### 1. Créer une issue “Brainstorm”
Structure recommandée :
- Problème (1–3 phrases)
- Contexte / contraintes
- Hypothèses
- Options (2–5)
- Tradeoffs
- Risques & inconnues
- Décision attendue
### 2. Timebox
- [ ] Fixer une durée (30/60/90 min)
- [ ] Définir un “owner” de la décision
### 3. Sortie attendue
- [ ] Une recommandation claire
- [ ] Une décision explicite (ADR léger)
- [ ] Une issue “Feature” créée à partir de la décision
### 4. Transition vers agentics
Quand prêt :
- [ ] Ajouter `ai:spec` sur l’issue Feature issue (pas sur Brainstorm)
## Gates
- Pas de gate CI ici
- Gate humain : décision écrite + création de l’issue Feature
## Critère de sortie
✅ Une décision (ADR) + une issue Feature “spec‑ready”.
## Références
- `docs/templates/ADR.md`
- `docs/workflows/consulting.md`
docs/plans/03_plan_specification.md
+60
View File
@@ -0,0 +1,60 @@
# 3) Plan de specification
## Objectif
Produire une spec **RFC2119** testable, injectable dans le workflow agentique, et reliée à des critères d’acceptation.
## Labels recommandés
- Issue : `type:feature` + `ai:spec`
- PR : `ai:spec` (doit être présent pour scope guard)
## Entrées
- Problème à résoudre
- Contraintes : coût, consommation, temps, perf, compliance
- Contexte d’usage
## Sorties
- Spec versionnée sous `specs/<id>-<slug>/`
- Critères d’acceptation
- Plan de vérification (tests/mesures)
## Étapes
### 1. Créer la structure spec
- [ ] Créer `specs/<id>-<slug>/README.md`
- [ ] Ajouter `requirements.md` (RFC2119)
- [ ] Ajouter `verification.md` (tests/mesures)
### 2. Écrire les exigences RFC2119
Checklist :
- [ ] MUST/SHOULD/MAY, phrases courtes
- [ ] Pas d’ambiguïté (“rapide”, “simple”) sans métrique
- [ ] Chaque exigence doit être vérifiable
### 3. Critères d’acceptation
- [ ] AC fonctionnels
- [ ] AC non‑fonctionnels (latence, conso, stabilité)
### 4. Plan de vérification
- [ ] Unit tests (native)
- [ ] Tests intégration (HIL si hardware)
- [ ] Mesures (power profiling, timing)
### 5. Validation
- [ ] Lancer la validation specs (si script dispo)
Exemple :
```bash
python tools/validate_specs.py || true
```
## Gates
- Gate humain : review de la spec
- Gate CI : `spec lint` (si activé)
- Scope guard : `ai:spec` ne doit modifier que `specs/` et `docs/`
## Critère de sortie
✅ Spec validée, sans TODOs, avec plan de vérification et critères d’acceptation.
## Références
- `docs/AI_WORKFLOWS.md`
- `docs/templates/ValidationPlan.md`
docs/plans/04_plan_mise_a_jour_agentics.md
+45
View File
@@ -0,0 +1,45 @@
# 4) Plan mise à jour agentics
## Objectif
Mettre à jour les composants agentiques (workflows CI, prompts, policies) **sans élargir la surface d’attaque**.
## Labels recommandés
- Issue : `type:agentics` + `ai:plan` (ou `ai:docs` si pure doc)
- PR : `ai:plan`
## Étapes
### 1. Inventaire
- [ ] Versionner l’état actuel : workflows, scripts `tools/ai/*`, policies, prompts
- [ ] Lister les changements souhaités (ex : nouveaux agents, nouvelles gates)
### 2. Threat model minimal
- [ ] Qu’est‑ce qui augmente les privilèges ?
- [ ] Qu’est‑ce qui ajoute du réseau/outillage ?
- [ ] Qu’est‑ce qui touche aux secrets ?
### 3. Plan de rollout
- [ ] Feature flag / mode dry‑run (si possible)
- [ ] Déploiement en 2 PRs :
- PR1 docs + tests
- PR2 activation
### 4. Tests de non‑régression
- [ ] Label enforcement fonctionne
- [ ] Scope guard bloque bien les chemins interdits
- [ ] Sanitizer supprime toujours les patterns dangereux
### 5. Evidence pack
- [ ] Logs CI des gates
- [ ] Exemple d’issue test + PR générée
## Gates
- `Scope Guard` (bloque notamment `.github/workflows/` si denylist)
- `PR Label Enforcement`
## Critère de sortie
✅ Les nouveautés sont activées, CI verte, surface de privilèges inchangée ou réduite.
## Références
- `docs/security/anti_prompt_injection_policy.md`
- `docs/INTEGRATIONS.md`
docs/plans/05_plan_roadmap_hw_fw.md
+45
View File
@@ -0,0 +1,45 @@
# 5) Plan de roadmap hardware/firmware
## Objectif
Définir une roadmap synchronisée entre **hardware** et **firmware** : analyse → design → proto → tests → validation → release.
## Labels recommandés
- `type:systems` + `ai:plan`
## Étapes (HW)
1. **Analyse** : contraintes mécaniques/électriques, BOM cible, profils compliance
2. **Schéma** (KiCad) : ERC, choix composants, interfaces
3. **PCB** : placement, routage, DRC
4. **BOM & supply** : alternatives, risque de pénurie
5. **Proto V0** : bring‑up électrique, tests de base
6. **Proto V1** : corrections, robustesse, ESD/EMC préliminaire
7. **Pré‑série** : endurance, tolérances, doc fabrication
## Étapes (FW)
1. **Skeleton** : architecture tasks/modules, logs, erreurs, watchdog
2. **Drivers** : GPIO/I2C/SPI/UART, HAL propre
3. **Comms** : protocoles + framing + retry
4. **Tests unitaires** : `native`
5. **Intégration** : test sur cible, HIL si possible
6. **Profil conso** : deep sleep, wake sources, budget énergétique
7. **RC** : freeze, bugfix only, release
## Points de synchronisation (gates “co-design”)
- Interface freeze (pinout, protocoles)
- Bring‑up checklist (V0)
- Validation conso (FW + HW)
- Test matrix release
## Evidence pack
- Exports KiCad (PDF, renders)
- BOM export + versions
- Logs bring‑up
- Mesures (courant, timing)
## Critère de sortie
✅ Roadmap publiée + jalons versionnés + critères “go/no‑go” définis.
## Références
- `docs/HARDWARE_QUICKSTART.md`
- `docs/COMPLIANCE.md`
- `docs/evidence/evidence_pack.md`
docs/plans/06_plan_integration_cicd.md
+47
View File
@@ -0,0 +1,47 @@
# 6) Plan d’intégration CI/CD
## Objectif
Automatiser build, tests, compliance, scope guard, evidence pack — et rendre la fusion impossible sans preuves.
## Labels recommandés
- `type:agentics` + `ai:plan`
## Pipelines minimales
### 1. Gates “repo sécurité”
- [ ] PR label enforcement (`ai:*` obligatoire)
- [ ] scope guard (label → allowlist)
- [ ] sanitizer check (tests unitaires sur `sanitize_issue.py` si ajoutés)
### 2. Gates “spec-driven”
- [ ] lint specs (format, RFC2119)
- [ ] génération docs (si applicable)
### 3. Gates “firmware”
- [ ] build PlatformIO (matrix envs)
- [ ] tests `native`
- [ ] format/lint (clang-format, etc.)
### 4. Gates “hardware” (optionnels)
- [ ] exports KiCad (PDF/renders)
- [ ] ERC/DRC (si outillage intégré)
- [ ] BOM export
## Evidence pack
Standardiser un dossier artefacts par run :
- `artifacts/<run-id>/logs/*`
- `artifacts/<run-id>/exports/*`
- `artifacts/<run-id>/reports/*`
## Étapes d’implémentation
- [ ] Définir la matrice de build (envs PIO)
- [ ] Ajouter upload d’artefacts (logs)
- [ ] Branch protection : checks requis
- [ ] (Option) Environnements protégés pour étapes sensibles
## Critère de sortie
✅ Merge impossible sans CI verte, et chaque PR produit un evidence pack minimum.
## Références
- `docs/evidence/evidence_pack.md`
- `.github/workflows/*`
docs/plans/07_plan_gestion_specs.md
+44
View File
@@ -0,0 +1,44 @@
# 7) Plan de gestion des specs
## Objectif
Mettre en place un process stable pour rédiger, valider et injecter les specs dans le workflow (sans dérive).
## Principes
- La spec est la **source de vérité**
- Toute implémentation doit référencer une spec
- Chaque exigence doit être **vérifiable**
## Labels recommandés
- `ai:spec` → produire/normaliser la spec
- `ai:plan` → architecture + verification plan
- `ai:tasks` → découpage exécutable
- `ai:impl` → code + tests
## Process
### 1. Rédaction
- [ ] Créer `specs/<id>-<slug>/`
- [ ] Écrire RFC2119 + AC + NFR
### 2. Validation
- [ ] Review humaine
- [ ] Lint spec (CI)
### 3. Injection dans l’exécution
- [ ] `ai:plan` génère architecture + ADR
- [ ] `ai:tasks` produit une checklist
### 4. Traçabilité
- [ ] Table “Requirement → Tests → Modules” (dans `verification.md`)
- [ ] Dans la PR d’impl : lien vers la spec + AC cochés
## Gates
- Gate spec lint (bloque `ai:impl` si spec invalide)
- Scope guard `ai:spec` (limite fichiers)
## Critère de sortie
✅ Specs versionnées, validées, reliées aux tests et aux PR.
## Références
- `docs/AI_WORKFLOWS.md`
- `docs/templates/ValidationPlan.md`
docs/plans/08_plan_conformite_securite.md
+44
View File
@@ -0,0 +1,44 @@
# 8) Plan de conformité & sécurité
## Objectif
Valider les profils, auditer les scripts/workflows, appliquer la politique anti‑prompt‑injection, et définir le sandboxing.
## Labels recommandés
- `type:compliance` + `ai:plan`
## Étapes
### 1. Profils conformité
- [ ] Choisir un profil (ex : `iot_wifi_eu`)
- [ ] Vérifier les exigences : radio, EMC, LVD, étiquetage
### 2. Audit CI & secrets
- [ ] Vérifier permissions des workflows (`permissions:` minimales)
- [ ] Vérifier usage secrets (pas d’echo, pas de logs)
- [ ] Activer branch protection + checks requis
### 3. Anti prompt injection
- [ ] Sanitizer activé avant injection prompt
- [ ] Scope guard par label `ai:*`
- [ ] Denylist pour chemins sensibles
- [ ] Procédure incident (`ai:hold`)
### 4. Sandboxing
- [ ] Les agents write‑capable passent via safe outputs
- [ ] OpenClaw : VM/Docker isolé, actions non destructives
### 5. Evidence pack
- [ ] Checklists remplies
- [ ] Export du profil compliance
- [ ] Résultats gates CI
## Gates
- Label enforcement + scope guard
- Compliance checks (si activés)
## Critère de sortie
✅ Profil choisi, politiques en place, CI verrouillée, et runbook incident validé.
## Références
- `docs/COMPLIANCE.md`
- `docs/security/anti_prompt_injection_policy.md`
docs/plans/09_plan_bulk_edit_hardware.md
+45
View File
@@ -0,0 +1,45 @@
# 9) Plan de bulk edit hardware
## Objectif
Orchestrer des modifications massives (KiCad, exports, snapshots, artefacts) de manière sûre, reproductible et reviewable.
## Labels recommandés
- Issue : `type:hardware` + `risk:med` + `ai:plan`
- PR : `ai:impl` (ou `ai:plan` si c’est uniquement scripts/process)
## Étapes
### 1. Définir le scope du batch
- [ ] Liste exacte des transformations (ex : rename nets, swap footprints)
- [ ] Répertoires concernés (`hardware/` uniquement)
- [ ] Mode dry‑run si script
### 2. Snapshots “avant”
- [ ] Export schéma PDF
- [ ] Export PCB renders
- [ ] Export BOM
- [ ] Version des libs/footprints
### 3. Exécution du bulk edit
- [ ] Dry‑run
- [ ] Apply
- [ ] Vérifier ERC/DRC
### 4. Snapshots “après”
- [ ] Exports identiques à “avant”
- [ ] Diff visuel (captures)
### 5. Evidence pack
- [ ] Artefacts avant/après attachés à la PR
- [ ] Logs du script
## Gates
- DRC/ERC (si pipeline)
- Scope guard (doit rester dans `hardware/`)
## Critère de sortie
✅ Modif massive réalisée, vérifiée, et diff visuel clair.
## Références
- `docs/KICAD_AI_LOCAL.md`
- `docs/KICAD_PREVIEWS.md`
docs/plans/10_plan_documentation_onboarding.md
+39
View File
@@ -0,0 +1,39 @@
# 10) Plan de documentation & onboarding
## Objectif
Maintenir une documentation simple, à jour, orientée exécution (pas marketing) avec exemples.
## Labels recommandés
- `type:docs` + `ai:docs`
## Étapes
### 1. Pages indispensables
- [ ] `README.md` (pitch + quickstart)
- [ ] `docs/INSTALL.md`
- [ ] `docs/RUNBOOK.md`
- [ ] `docs/FAQ.md`
### 2. Exemples
- [ ] “Minimal project” (spec + firmware stub + test native)
- [ ] “Issue → PR” walkthrough
### 3. Docs auto-générées
- [ ] Référencer ce qui est généré et ce qui est manuel
- [ ] Garder la nav cohérente
### 4. Qualité docs
- [ ] Liens internes OK
- [ ] Commandes testées
- [ ] Aucune info sensible
## Gates
- Lint markdown (si activé)
- Review humaine
## Critère de sortie
✅ Un nouveau peut exécuter le workflow en 15 minutes sans aide.
## Références
- `docs/index.md`
- `docs/workflows/README.md`
docs/plans/11_plan_contribution_feedback.md
+37
View File
@@ -0,0 +1,37 @@
# 11) Plan de contribution & feedback
## Objectif
Canaliser issues/PR, proposer des profils, enrichir les standards, et intégrer le feedback sans casser la sécurité.
## Labels recommandés
- `type:process` + `ai:docs` (ou `ai:plan` si changements structure)
## Étapes
### 1. Templates d’issues
- [ ] Feature
- [ ] Bug
- [ ] Compliance/Release
- [ ] Agentics update
### 2. Process PR
- [ ] Labels `ai:*` obligatoires
- [ ] Scope guard doit passer
- [ ] Evidence pack minimal
- [ ] Review obligatoire sur paths sensibles
### 3. Proposer un profil compliance
- [ ] Ouvrir issue `type:compliance`
- [ ] Fournir exigences et sources
- [ ] Ajouter tests/gates
### 4. Boucle feedback
- [ ] Triage hebdo
- [ ] “Decision log” (ADR)
## Critère de sortie
✅ Contributions fluides, règles claires, aucun élargissement accidentel des privilèges.
## Références
- `.github/ISSUE_TEMPLATE/*`
- `docs/LABELS.md`
docs/plans/12_plan_gestion_des_agents.md
+48
View File
@@ -0,0 +1,48 @@
# 12) Plan de gestion des agents
## Objectif
Définir rôles, prompts, rituels, gates, handoffs et evidence pack pour garder un système agentique stable.
## Labels recommandés
- `type:agentics` + `ai:plan`
## Étapes
### 1. Rôles
- [ ] PM
- [ ] Architect
- [ ] Firmware
- [ ] Hardware
- [ ] QA
- [ ] Doc
### 2. Prompts standard
Chaque prompt doit définir :
- Entrées (sanitisées)
- Sorties attendues (artefacts)
- Contraintes (scope, denylist)
- Format de rapport
### 3. Handoffs
- [ ] Handoff Firmware
- [ ] Handoff Hardware
- [ ] Handoff Design
- [ ] Handoff Creative
### 4. Gates
- [ ] Label enforcement
- [ ] Scope guard
- [ ] Build/test
- [ ] Compliance (si applicable)
### 5. Evidence pack
- [ ] Logs CI
- [ ] Diffs
- [ ] Décisions (ADR)
## Critère de sortie
✅ Les agents sont utiles, prédictibles, et “safe by default”.
## Références
- `docs/handoffs/*`
- `docs/rituals/*`
docs/plans/13_plan_troubleshooting.md
+49
View File
@@ -0,0 +1,49 @@
# 13) Plan de troubleshooting
## Objectif
Résoudre rapidement les erreurs courantes (build, tests, CI, hardware) avec une démarche standard.
## Approche
1) Identifier le gate qui échoue
2) Lire le log complet
3) Reproduire localement
4) Corriger avec une PR minimale
## Cas fréquents
### PR sans label `ai:*`
- Symptôme : job “PR Label Enforcement” échoue
- Fix : ajouter un label `ai:*` (ou attendre fallback `ai:impl`)
### Scope guard échoue
- Symptôme : fichier hors allowlist
- Fix :
- changer le label `ai:*` vers celui adapté
- ou déplacer la modification dans une PR séparée
### Build PlatformIO échoue
- Vérifier versions toolchain
- Lancer :
```bash
cd firmware
pio run -e <env>
```
### Tests `native` échouent
- Lancer :
```bash
cd firmware
pio test -e native -v
```
### Suspicion prompt injection
- Ajouter `ai:hold`
- Ne pas merger
- Revue manuelle + rotation tokens si nécessaire
## Critère de sortie
✅ Root cause documentée + fix minimal + CI verte.
## Références
- `docs/RUNBOOK.md`
- `docs/security/anti_prompt_injection_policy.md`
docs/plans/14_plan_release_versioning.md
+42
View File
@@ -0,0 +1,42 @@
# 14) Plan de release & versioning
## Objectif
Mettre en place un versioning clair et des releases reproductibles (firmware + hardware + specs + evidence pack).
## Recommandation versioning
- Firmware : SemVer (`vMAJOR.MINOR.PATCH`)
- Hardware : `HW-V0`, `HW-V1` + révisions PCB
- Specs : version interne (rev) ou tag repo
## Étapes release
### 1. Préparer la RC
- [ ] “Freeze” features, bugfix only
- [ ] Test matrix complète
- [ ] Evidence pack complet
### 2. Tag & artefacts
- [ ] Tag git
- [ ] Générer binaires firmware (CI)
- [ ] Publier artefacts (hash, size)
### 3. Release notes
- [ ] Liste des AC couverts
- [ ] Changements incompatibles
- [ ] Profil compliance
### 4. Post‑release
- [ ] Backport policy
- [ ] Hotfix process
## Gates
- CI verte
- Evidence pack présent
- Review finale
## Critère de sortie
✅ Release publiée, reproductible, avec preuves et notes claires.
## Références
- `docs/workflows/compliance_release.md`
- `docs/evidence/evidence_pack.md`
docs/plans/README.md
+28
View File
@@ -0,0 +1,28 @@
# Plans opérationnels
Ces plans sont des **runbooks** : tu peux les suivre tels quels, ou les transformer en issues/epics. Ils sont pensés pour fonctionner avec :
- Labels `ai:*` + scope guard
- Evidence pack (preuves CI/HW)
- Sécurité anti‑prompt‑injection
## Table des matières
1. [Plan première entrée](01_plan_premiere_entree.md)
2. [Plan brainstorming](02_plan_brainstorming.md)
3. [Plan de specification](03_plan_specification.md)
4. [Plan mise à jour agentics](04_plan_mise_a_jour_agentics.md)
5. [Plan de roadmap hardware/firmware](05_plan_roadmap_hw_fw.md)
6. [Plan d’intégration CI/CD](06_plan_integration_cicd.md)
7. [Plan de gestion des specs](07_plan_gestion_specs.md)
8. [Plan de conformité & sécurité](08_plan_conformite_securite.md)
9. [Plan de bulk edit hardware](09_plan_bulk_edit_hardware.md)
10. [Plan de documentation & onboarding](10_plan_documentation_onboarding.md)
11. [Plan de contribution & feedback](11_plan_contribution_feedback.md)
12. [Plan de gestion des agents](12_plan_gestion_des_agents.md)
13. [Plan de troubleshooting](13_plan_troubleshooting.md)
14. [Plan de release & versioning](14_plan_release_versioning.md)
---
Astuce : si tu veux exécuter ces plans “à la chaîne” en mode agentique, commence par créer une issue “Program” et découpe en sous‑issues (ou en checklists), puis applique les labels `ai:*` progressivement.
docs/rituals/design_reviews.md
+12
View File
@@ -0,0 +1,12 @@
# Rituel — Design Reviews (DR0/DR1)
## DR0 (début arch)
- Objectif : vérifier qu’on peut réussir (pas de dead-end)
- Sortie : liste de risques + décisions à prendre
## DR1 (budget + validation)
- Objectif : figer budgets et plan de validation
- Sortie : validation plan + test matrix + evidence pack
## Checklist
Utiliser `docs/templates/DesignReview.md`.
docs/rituals/release.md
+16
View File
@@ -0,0 +1,16 @@
# Rituel — Release
## Pré-requis
- Tous gates CI OK
- Evidence pack complet
- Notes de release prêtes
## Étapes
- Bump version
- Tag
- Publier artifacts
- Changelog
## Post-release
- Retours terrain
- Bugs P0 → hotfix
docs/rituals/steering_committee.md
+19
View File
@@ -0,0 +1,19 @@
# Rituel — Steering (cabinet) (hebdo, 45–60 min)
## Objectif
Valider décisions structurantes, arbitrer options, ajuster roadmap.
## Entrées
- ADR en attente
- Risques majeurs
- Roadmap / jalons
## Agenda
- Décisions (ADR) : accepter/refuser
- Risques : mitigations
- Roadmap : ajustements
## Sortie
- ADR acceptés
- Roadmap mise à jour
- Priorités clarifiées
docs/rituals/triage.md
+13
View File
@@ -0,0 +1,13 @@
# Rituel — Triage (hebdo, 30 min)
## Objectif
Nettoyer le backlog, attribuer priorité/risque/scope, décider quoi automatiser.
## Agenda
- Revue des nouvelles issues
- Appliquer labels : `type:*` `prio:*` `risk:*` `scope:*`
- Décider du prochain `ai:*` à appliquer (spec/plan/tasks/impl)
## Sortie
- 5 issues max “prêtes” (spec/plan)
- `ai:hold` sur ce qui est suspect ou pas prêt
docs/templates/ADR.md
Vendored
+24
View File
@@ -0,0 +1,24 @@
# ADR — Architecture Decision Record
- **ID**: ADR-YYYYMMDD-XX
- **Statut**: Proposed / Accepted / Deprecated
- **Contexte**:
## Décision
## Options considérées
1) Option A
2) Option B
## Trade-offs
- Coût :
- Risque :
- Temps :
- Complexité :
- Conso / perf :
## Conséquences
## Validation
- Tests/mesures :
- Critères :
docs/templates/DesignReview.md
Vendored
+33
View File
@@ -0,0 +1,33 @@
# Design Review (DR0/DR1)
- **Type**: DR0 / DR1
- **Date**:
- **Scope**:
## Checklist
### Architecture
- [ ] Interfaces listées
- [ ] Modes de panne identifiés
- [ ] ADR écrits pour décisions clés
### Budgets
- [ ] Power budget
- [ ] Mémoire/flash budget
- [ ] Latence/throughput
### Tests & validation
- [ ] Plan de validation
- [ ] Test matrix
- [ ] Evidence pack défini
### Sécurité / conformité
- [ ] Profil conformité choisi
- [ ] Politique anti-injection respectée
- [ ] Scope guard applicable
## Décisions
## Actions
- [ ] Action 1
- [ ] Action 2
docs/templates/PlaytestReport.md
Vendored
+18
View File
@@ -0,0 +1,18 @@
# Playtest report
- **Date**:
- **Version**:
- **Participants**:
## Hypothèses testées
## Observations
## Problèmes rencontrés
## Améliorations
## Décision
- [ ] Itérer
- [ ] Valider
- [ ] Repenser
docs/templates/ValidationPlan.md
Vendored
+25
View File
@@ -0,0 +1,25 @@
# Plan de validation
## Objectif
## Périmètre
## Matrice de tests
| Niveau | Tests | Outils | Critères de succès | Evidence |
|---|---|---|---|---|
| Unit | | | | |
| Integration | | | | |
| HIL | | | | |
| Endurance | | | | |
| Power | | | | |
## Environnements
- CI :
- Local :
- Banc :
## Critères de release
- [ ] Tous gates OK
- [ ] Evidence pack complet
- [ ] Notes de release
docs/workflows/README.md
+35
View File
@@ -0,0 +1,35 @@
# Workflows professionnels (opérationnels)
Ces workflows sont conçus pour ressembler aux pratiques **cabinet de conseil**, **bureau d’études**, **design produit**, **studio créatif**, **R&D**, **industrialisation / compliance** — tout en restant compatibles avec le pipeline agentique du repo :
- labels `type:*` pour classer l’intention métier,
- labels `ai:*` pour déclencher l’automatisation (Issue → PR),
- **scope guard** et **label enforcement** pour sécuriser les actions,
- **evidence pack** pour tracer les décisions et résultats.
## Menu
- 🧑‍💼 [Cabinet de conseil](consulting.md)
- 🏗 [Bureau d’études / Ingénierie système](systems_engineering.md)
- 🎨 [Design produit / UX](design.md)
- 🎭 [Créatif / narration / contenu](creative.md)
- 🧪 [R&D / spikes time-boxés](rnd_spikes.md)
- 🛡 [Compliance / QA / Release](compliance_release.md)
## Règle simple (anti-chaos)
1) **Crée une issue** avec un template (`.github/ISSUE_TEMPLATE/`).
2) **Triage** : ajoute `prio:*`, `risk:*`, `scope:*`, et garde seulement un `type:*`.
3) **Déclenche l’automatisation** en ajoutant le bon label `ai:*` :
- `ai:spec` → formaliser exigences (RFC2119 + critères d’acceptation)
- `ai:plan` → architecture + options + ADR
- `ai:tasks` → backlog exécutable
- `ai:impl` → impl + tests minimaux
- `ai:qa` → durcissement tests/edge
- `ai:docs` → docs + runbooks
⚠️ Si tu suspects une injection / comportement bizarre : ajoute `ai:hold`.
## Evidence pack
Voir : `docs/evidence/evidence_pack.md`.
docs/workflows/compliance_release.md
+29
View File
@@ -0,0 +1,29 @@
# Workflow — Compliance / QA / Release
## But
Fiabiliser, prouver, livrer : test matrix, evidence pack, versioning et release reproductible.
## Phases
### 1) Validation plan
- Profil conformité (pays/zone)
- Test matrix (unit/integration/HIL/endurance/power)
- Label : `ai:plan`
### 2) Impl tests & gates
- Ajout/renforcement tests
- Packaging artifacts
- Label : `ai:qa`
### 3) Release
- Notes de release, versioning
- Artifacts (bins, exports, rapports)
- Label : `ai:docs`
## Gates
- Tous status checks requis (CI)
- Scope guard OK
- Evidence pack complet
## Evidence pack
Voir `docs/evidence/evidence_pack.md`.
docs/workflows/consulting.md
+59
View File
@@ -0,0 +1,59 @@
# Workflow — Cabinet de conseil (stratégie → décision → roadmap)
## But
Transformer une demande floue en **décision actionnable** + **plan exécutable** (roadmap/backlog) avec risques cadrés.
## Entrées
- Brief client / demande interne
- Contraintes (délai, budget, compliance, supply)
- Contexte produit
## Sorties
- Spec RFC2119 (exigences)
- Options + tradeoffs + recommandation
- Roadmap + backlog (WBS)
- ADR (decision record)
## Phases (opérationnel)
### 0) Intake (30–60 min)
- Clarifier : problème, objectifs, contraintes, “definition of done”
- Output : **problem statement** + **outcomes**
- Labels : `type:consulting` + `needs:triage`
### 1) Diagnostic (0.5–2 j)
- Analyse existant (repo, arch, contraintes)
- Lister hypothèses et risques
- Output : *assumptions log* + risques + questions ouvertes
- Label conseillé : `ai:plan` (si tu veux produire un diagnostic structuré en PR docs)
### 2) Options & arbitrage (0.5–2 j)
- 2–4 options max
- Tradeoffs : coût/temps/risque/perf/conso
- Output : recommandation + ADR
- Label : `ai:plan`
### 3) Roadmap & backlog (0.5–2 j)
- Roadmap jalonnée (V0/V1/RC)
- Backlog : epics + stories + AC
- Output : `ai:tasks`
### 4) Kickoff exécution (selon besoin)
- Impl minimal / prototype
- Output : PR d’impl + tests minimaux
- Label : `ai:impl`
## Gates
- Spec lint OK
- ADR présent pour les décisions structurantes
- Scope guard OK (pas de modifications hors scope)
- Evidence pack joint
## Evidence pack (minimum)
- `docs/evidence/` : notes, ADR, comparatif options, backlog
## Comment l’utiliser dans ce repo
1. Ouvre une issue avec le template **Cabinet — Intake / Cadrage**.
2. Triage : ajoute `prio:*` `risk:*` `scope:*`.
3. Quand l’intake est validé : ajoute `ai:spec` ou `ai:plan`.
4. La PR créée doit contenir : spec/plan/ADR/backlog.
docs/workflows/creative.md
+31
View File
@@ -0,0 +1,31 @@
# Workflow — Créatif / narration / contenu
## But
Produire une expérience (narration, scripts, audio/texte, triggers) **versionnée** et intégrable dans le firmware/hardware.
## Phases
### 1) Bible / règles
- Ton, univers, règles, contraintes de production
- Label : `ai:spec`
### 2) Scénarisation
- Structure : scènes, progression, graph (triggers → actions)
- Label : `ai:plan`
### 3) Production assets
- Scripts + manifests + placeholders
- Formats : mp3 mono/stéréo, durées, langues, voix
- Label : `ai:impl` (contenu) + `ai:docs` (guide d’intégration)
### 4) Playtest & itération
- Notes, corrections, versioning
- Label : `ai:qa` (si tu ajoutes tests/validateurs sur manifests)
## Gates
- Manifests valides
- Assets référencés existent
- Evidence pack (liste assets + checksums)
## Evidence pack
Voir `docs/evidence/creative_pack.md`.
docs/workflows/design.md
+42
View File
@@ -0,0 +1,42 @@
# Workflow — Design produit / UX
## But
Définir l’expérience utilisateur, les états UI, les contraintes physiques (écran/boutons), et produire un handoff exploitable.
## Phases
### 1) Brief & contraintes
- Personas, contexte d’usage, objectifs UX
- Contraintes hardware (écran, boutons, feedback)
- Livrable : spec UX (règles + mapping inputs)
- Label : `ai:spec`
### 2) Exploration
- 3–5 directions (pas plus)
- Critères : lisibilité, erreurs, temps d’apprentissage, robustesse
- Livrable : “direction choisie” + rationale
- Label : `ai:plan` (docs)
### 3) Prototypage
- Wireframes → prototype (low → mid → hi)
- États : nominal, loading, erreur, offline
- Livrable : matrice états + mapping boutons/gestes
- Label : `ai:docs` (ou `ai:impl` si tu ajoutes un prototype UI)
### 4) Design system & handoff
- Composants + états
- Guidelines + naming assets
- Handoff vers firmware/hardware
- Label : `ai:docs`
## Gates
- Mapping inputs complet (boutons/écran)
- États d’erreur spécifiés
- Handoff : assets + conventions
## Evidence pack
- Captures/export (ou liens internes)
- Checklist de validation UX
## Tips
- Si l’UI doit toucher le firmware : sépare UI logique (testable `native`) et rendu HW (drivers).
docs/workflows/rnd_spikes.md
+27
View File
@@ -0,0 +1,27 @@
# Workflow — R&D / Spikes time‑boxés
## But
Apprendre vite, mesurer, décider. Un spike doit produire un **rapport**, pas du code permanent.
## Règles
- Timebox obligatoire
- Critères de succès explicites
- Evidence pack (mesures, logs, protocole)
## Phases
### 1) Protocole
- Méthode de mesure (instrumentation)
- Critères d’arrêt
- Label : `ai:plan`
### 2) Prototype minimal
- Code minimal + scripts de mesure
- Label : `ai:impl`
### 3) Rapport & décision
- Décision : industrialiser / re‑spike / abandonner
- Label : `ai:docs`
## Evidence pack
Voir `docs/evidence/spike_pack.md`.
docs/workflows/systems_engineering.md
+44
View File
@@ -0,0 +1,44 @@
# Workflow — Bureau d’études / Ingénierie système (HW/FW)
## But
Produire une architecture end‑to‑end : interfaces, budgets, risques, plan de validation, puis backlog.
## Phases
### 1) Requirements engineering (requirements → spec)
- Livrables : RFC2119 + NFR + AC + matrice traçabilité (AC → tests)
- Label : `ai:spec`
### 2) Architecture système (design → ADR)
- Livrables : diagrammes blocs, interfaces, budgets (power/memory/latency), modes de panne, ADR
- Label : `ai:plan`
### 3) Design review (DR0/DR1)
- DR0 : cohérence + risques (pas de “dead ends”)
- DR1 : budgets + plan de validation + BOM
- Livrables : checklist review + décisions (ADR)
- Labels : `ai:plan` puis `ai:qa` (si tu veux injecter la test matrix)
### 4) Backlog (WBS)
- Livrables : epics/stories, tâches, critères d’acceptation
- Label : `ai:tasks`
### 5) Exécution (impl + tests)
- Firmware : drivers + tasks + logs + watchdog
- Hardware : schéma/PCB + DRC/ERC
- Labels : `ai:impl` / `ai:qa`
## Gates
- Budgets explicités (power, mémoire, latence)
- Plan de validation (unit/integration/HIL/endurance)
- Scope guard :
- `ai:spec` doit rester dans `specs/` + `docs/`
- `ai:impl` ne touche pas aux workflows
## Evidence pack
Voir `docs/evidence/evidence_pack.md` + exports (KiCad + BOM + logs CI).
## Mode “BE” recommandé (cadence)
- Triage hebdo (30 min)
- DR0 et DR1 (60–90 min)
- ADR obligatoire pour : MCU/RTOS, bus, power architecture, radio stack
gh_setup_and_patches/REQUIRED_CHECKS_STRATEGY.md
+42
View File
@@ -0,0 +1,42 @@
# Required checks friendly CI (economical + never blocks merges)
If you make a GitHub Actions check **required** in branch protection, GitHub expects that check to exist on **every** pull request.
A common failure mode is using `on: pull_request: paths:` filters (or similar) on a required workflow:
- the workflow is **skipped**,
- the required check never appears (or stays pending),
- and merges are blocked.
## The clean pattern used by the patches in this pack
1) Trigger required workflows on **all PRs** (remove `paths:` from `pull_request`).
2) Keep it **economical** by skipping heavy work **inside the job**:
- Run a fast path detector step (changed files filter)
- Gate heavy steps (`install`, `build`, `test`) behind `if:` conditions
- If nothing relevant changed, the job still completes **successfully**, but quickly.
This guarantees:
- The required check exists on every PR
- It reports success when irrelevant
- It still runs full builds/tests when relevant
## Apply the patches
From repo root:
```bash
git apply patches/firmware_ci_required_checks.patch
git apply patches/hardware_ci_required_checks.patch
git apply patches/compliance_gate_required_checks.patch
```
Then commit.
## Verify required check contexts
After your first PR, open **PR → Checks** and note the exact names, e.g.
- `Firmware CI / pio (native)`
- `Scope Guard / guard`
Use those exact names in branch protection (the provided `setup_repo.sh` uses the defaults from the template).
gh_setup_and_patches/patched_workflows/compliance_gate.yml
+48
View File
@@ -0,0 +1,48 @@
name: Compliance Gate
on:
push:
paths:
- "compliance/**"
- "tools/compliance/**"
- ".github/workflows/compliance_gate.yml"
pull_request:
workflow_dispatch:
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Detect relevant changes
id: changes
uses: dorny/paths-filter@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
filters: |
comp:
- 'compliance/**'
- 'tools/compliance/**'
- '.github/workflows/compliance_gate.yml'
- name: No relevant changes (fast pass)
if: steps.changes.outputs.comp != 'true'
run: |
echo "No compliance/tools-compliance changes detected. Skipping compliance validation."
- uses: actions/setup-python@v5
if: steps.changes.outputs.comp == 'true'
with:
python-version: "3.11"
- name: Install deps
if: steps.changes.outputs.comp == 'true'
run: |
python -m pip install -U pip
python -m pip install -r tools/compliance/requirements.txt
- name: Validate compliance
if: steps.changes.outputs.comp == 'true'
run: |
python tools/compliance/validate.py --strict
gh_setup_and_patches/patched_workflows/firmware_ci.yml
+64
View File
@@ -0,0 +1,64 @@
name: Firmware CI
on:
push:
paths: ["firmware/**", "specs/**", "standards/**", ".github/workflows/firmware_ci.yml"]
pull_request:
workflow_dispatch:
jobs:
pio:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
env: [esp32s3_arduino, esp32_arduino, native]
steps:
- uses: actions/checkout@v6
# Required-check friendly: always run on PR, but skip heavy work when irrelevant.
- name: Detect relevant changes
id: changes
uses: dorny/paths-filter@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
filters: |
fw:
- 'firmware/**'
- 'specs/**'
- 'standards/**'
- '.github/workflows/firmware_ci.yml'
- name: No relevant changes (fast pass)
if: steps.changes.outputs.fw != 'true'
run: |
echo "No firmware/spec/standards changes detected. Skipping build/test for ${{ matrix.env }}."
- uses: actions/setup-python@v5
if: steps.changes.outputs.fw == 'true'
with:
python-version: "3.11"
- uses: actions/cache@v4
if: steps.changes.outputs.fw == 'true'
with:
path: |
~/.cache/pip
~/.platformio
key: pio-${{ runner.os }}-${{ matrix.env }}-${{ hashFiles('firmware/platformio.ini') }}
- name: Install PlatformIO
if: steps.changes.outputs.fw == 'true'
run: |
python -m pip install -U pip
python -m pip install -U platformio
- name: Build
if: steps.changes.outputs.fw == 'true'
working-directory: firmware
run: pio run -e ${{ matrix.env }}
- name: Test
if: steps.changes.outputs.fw == 'true' && matrix.env == 'native'
working-directory: firmware
run: pio test -e native
gh_setup_and_patches/patched_workflows/hardware_ci.yml
+50
View File
@@ -0,0 +1,50 @@
name: Hardware CI (KiCad)
on:
push:
paths: ["hardware/**", "tools/hw/**", ".github/workflows/hardware_ci.yml"]
pull_request:
workflow_dispatch:
jobs:
hw:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Detect relevant changes
id: changes
uses: dorny/paths-filter@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
filters: |
hw:
- 'hardware/**'
- 'tools/hw/**'
- '.github/workflows/hardware_ci.yml'
- name: No relevant changes (fast pass)
if: steps.changes.outputs.hw != 'true'
run: |
echo "No hardware/tools-hw changes detected. Skipping hardware checks."
- uses: actions/setup-python@v5
if: steps.changes.outputs.hw == 'true'
with:
python-version: "3.11"
- name: Install deps (schops)
if: steps.changes.outputs.hw == 'true'
run: |
python -m pip install -U pip
python -m pip install -r tools/hw/schops/requirements.txt
- name: Unit tests (rules engine)
if: steps.changes.outputs.hw == 'true'
run: |
python -m unittest discover -s tools/hw/schops/tests -p "test_*.py"
- name: Template note
run: |
echo "Template CI: install KiCad on runner or use a KiCad docker image, then run:"
echo " bash tools/hw/hw_check.sh <path/to.kicad_sch>"
gh_setup_and_patches/patches/compliance_gate_required_checks.patch
+49
View File
@@ -0,0 +1,49 @@
--- /mnt/data/tmp_unpack/.github/workflows/compliance_gate.yml 2026-02-18 20:45:52.000000000 +0000
+++ /mnt/data/gh_setup_pack/patched_workflows/compliance_gate.yml 2026-02-19 00:08:57.341825782 +0000
@@ -7,10 +7,6 @@
- "tools/compliance/**"
- ".github/workflows/compliance_gate.yml"
pull_request:
- paths:
- - "compliance/**"
- - "tools/compliance/**"
- - ".github/workflows/compliance_gate.yml"
workflow_dispatch:
jobs:
@@ -18,13 +14,35 @@
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
+
+ - name: Detect relevant changes
+ id: changes
+ uses: dorny/paths-filter@v3
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ filters: |
+ comp:
+ - 'compliance/**'
+ - 'tools/compliance/**'
+ - '.github/workflows/compliance_gate.yml'
+
+ - name: No relevant changes (fast pass)
+ if: steps.changes.outputs.comp != 'true'
+ run: |
+ echo "No compliance/tools-compliance changes detected. Skipping compliance validation."
+
- uses: actions/setup-python@v5
+ if: steps.changes.outputs.comp == 'true'
with:
python-version: "3.11"
+
- name: Install deps
+ if: steps.changes.outputs.comp == 'true'
run: |
python -m pip install -U pip
python -m pip install -r tools/compliance/requirements.txt
+
- name: Validate compliance
+ if: steps.changes.outputs.comp == 'true'
run: |
python tools/compliance/validate.py --strict
gh_setup_and_patches/patches/firmware_ci_required_checks.patch
+63
View File
@@ -0,0 +1,63 @@
--- /mnt/data/tmp_unpack/.github/workflows/firmware_ci.yml 2026-02-18 20:39:44.000000000 +0000
+++ /mnt/data/gh_setup_pack/patched_workflows/firmware_ci.yml 2026-02-19 00:08:25.371562765 +0000
@@ -4,7 +4,7 @@
push:
paths: ["firmware/**", "specs/**", "standards/**", ".github/workflows/firmware_ci.yml"]
pull_request:
- paths: ["firmware/**", "specs/**", "standards/**", ".github/workflows/firmware_ci.yml"]
+ workflow_dispatch:
jobs:
pio:
@@ -15,23 +15,50 @@
env: [esp32s3_arduino, esp32_arduino, native]
steps:
- uses: actions/checkout@v6
+
+ # Required-check friendly: always run on PR, but skip heavy work when irrelevant.
+ - name: Detect relevant changes
+ id: changes
+ uses: dorny/paths-filter@v3
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ filters: |
+ fw:
+ - 'firmware/**'
+ - 'specs/**'
+ - 'standards/**'
+ - '.github/workflows/firmware_ci.yml'
+
+ - name: No relevant changes (fast pass)
+ if: steps.changes.outputs.fw != 'true'
+ run: |
+ echo "No firmware/spec/standards changes detected. Skipping build/test for ${{ matrix.env }}."
+
- uses: actions/setup-python@v5
+ if: steps.changes.outputs.fw == 'true'
with:
python-version: "3.11"
+
- uses: actions/cache@v4
+ if: steps.changes.outputs.fw == 'true'
with:
path: |
~/.cache/pip
~/.platformio
key: pio-${{ runner.os }}-${{ matrix.env }}-${{ hashFiles('firmware/platformio.ini') }}
+
- name: Install PlatformIO
+ if: steps.changes.outputs.fw == 'true'
run: |
python -m pip install -U pip
python -m pip install -U platformio
+
- name: Build
+ if: steps.changes.outputs.fw == 'true'
working-directory: firmware
run: pio run -e ${{ matrix.env }}
+
- name: Test
- if: matrix.env == 'native'
+ if: steps.changes.outputs.fw == 'true' && matrix.env == 'native'
working-directory: firmware
run: pio test -e native
gh_setup_and_patches/patches/hardware_ci_required_checks.patch
+50
View File
@@ -0,0 +1,50 @@
--- /mnt/data/tmp_unpack/.github/workflows/hardware_ci.yml 2026-02-18 20:39:44.000000000 +0000
+++ /mnt/data/gh_setup_pack/patched_workflows/hardware_ci.yml 2026-02-19 00:08:43.535750401 +0000
@@ -4,7 +4,6 @@
push:
paths: ["hardware/**", "tools/hw/**", ".github/workflows/hardware_ci.yml"]
pull_request:
- paths: ["hardware/**", "tools/hw/**", ".github/workflows/hardware_ci.yml"]
workflow_dispatch:
jobs:
@@ -12,16 +11,39 @@
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
+
+ - name: Detect relevant changes
+ id: changes
+ uses: dorny/paths-filter@v3
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ filters: |
+ hw:
+ - 'hardware/**'
+ - 'tools/hw/**'
+ - '.github/workflows/hardware_ci.yml'
+
+ - name: No relevant changes (fast pass)
+ if: steps.changes.outputs.hw != 'true'
+ run: |
+ echo "No hardware/tools-hw changes detected. Skipping hardware checks."
+
- uses: actions/setup-python@v5
+ if: steps.changes.outputs.hw == 'true'
with:
python-version: "3.11"
+
- name: Install deps (schops)
+ if: steps.changes.outputs.hw == 'true'
run: |
python -m pip install -U pip
python -m pip install -r tools/hw/schops/requirements.txt
+
- name: Unit tests (rules engine)
+ if: steps.changes.outputs.hw == 'true'
run: |
python -m unittest discover -s tools/hw/schops/tests -p "test_*.py"
+
- name: Template note
run: |
echo "Template CI: install KiCad on runner or use a KiCad docker image, then run:"
gh_setup_and_patches/setup_repo.sh
Executable
+206
View File
@@ -0,0 +1,206 @@
#!/usr/bin/env bash
set -euo pipefail
# -----------------------------------------------------------------------------
# setup_repo.sh — GitHub CLI bootstrap for this template
#
# What it does:
# 1) Creates/updates all recommended labels (ai:*, type:*, scope:*, prio:*, risk:*, needs:*).
# 2) Optionally enables Discussions.
# 3) Configures branch protection on the target branch with required checks.
#
# Usage:
# bash setup_repo.sh owner/repo
#
# Env:
# BRANCH=main
# ENABLE_DISCUSSIONS=0|1
# REQUIRE_BUILD_CHECKS=0|1
# DRY_RUN=0|1
#
# Notes:
# - Requires: gh >= 2.x, authenticated (gh auth login)
# - Branch protection requires admin rights.
# -----------------------------------------------------------------------------
REPO_FULL="${1:-}"
BRANCH="${BRANCH:-main}"
ENABLE_DISCUSSIONS="${ENABLE_DISCUSSIONS:-0}"
REQUIRE_BUILD_CHECKS="${REQUIRE_BUILD_CHECKS:-1}"
DRY_RUN="${DRY_RUN:-0}"
if [[ -z "${REPO_FULL}" ]]; then
echo "Usage: $0 <owner/repo>" >&2
exit 2
fi
OWNER="${REPO_FULL%/*}"
REPO="${REPO_FULL#*/}"
run() {
if [[ "${DRY_RUN}" == "1" ]]; then
echo "[dry-run] $*"
else
eval "$@"
fi
}
need_gh() {
command -v gh >/dev/null 2>&1 || { echo "gh not found. Install GitHub CLI first." >&2; exit 1; }
gh auth status -h github.com >/dev/null 2>&1 || { echo "Not authenticated. Run: gh auth login" >&2; exit 1; }
}
create_label() {
local name="$1"; local color="$2"; local desc="$3"
run "gh label create \"${name}\" -R \"${REPO_FULL}\" --color \"${color}\" --description \"${desc}\" --force >/dev/null"
}
setup_labels() {
echo "==> Creating/updating labels in ${REPO_FULL} ..."
# ai:*
create_label "ai:spec" "0E8A16" "Agent scope: generate/normalize specification (RFC2119)."
create_label "ai:plan" "1D76DB" "Agent scope: architecture/plan/ADR/test strategy."
create_label "ai:tasks" "5319E7" "Agent scope: task breakdown, checklists, backlog."
create_label "ai:impl" "FBCA04" "Agent scope: implementation within allowed directories."
create_label "ai:qa" "D93F0B" "Agent scope: tests, edge cases, validation, hardening."
create_label "ai:docs" "0B4F6C" "Agent scope: documentation only."
create_label "ai:hold" "B60205" "STOP automation. Human review required."
# type:*
create_label "type:feature" "C2E0C6" "Feature request."
create_label "type:bug" "B60205" "Bug report."
create_label "type:consulting" "D4C5F9" "Consulting-style intake/cadrage."
create_label "type:systems" "A2EEEF" "Systems/engineering/architecture."
create_label "type:design" "F9D0C4" "UX/UI/industrial design."
create_label "type:creative" "FAD8C7" "Creative/narrative/content production."
create_label "type:spike" "FEF2C0" "R&D spike, time-boxed."
create_label "type:compliance" "0052CC" "Compliance / release readiness."
create_label "type:agentics" "6F42C1" "Agentic workflow updates."
# scope:*
create_label "scope:firmware" "1F6FEB" "Firmware scope."
create_label "scope:hardware" "0E8A16" "Hardware scope."
create_label "scope:docs" "0B4F6C" "Docs scope."
create_label "scope:ux" "FBCA04" "UX/UI scope."
create_label "scope:content" "FAD8C7" "Creative content scope."
create_label "scope:infra" "5319E7" "CI/CD & repo infrastructure scope."
# risk:*
create_label "risk:low" "C2E0C6" "Low risk."
create_label "risk:med" "FBCA04" "Medium risk."
create_label "risk:high" "B60205" "High risk."
# prio:*
create_label "prio:p0" "B60205" "P0 urgent."
create_label "prio:p1" "D93F0B" "P1 high."
create_label "prio:p2" "FBCA04" "P2 normal."
create_label "prio:p3" "C2E0C6" "P3 low."
# needs:*
create_label "needs:triage" "EDEDED" "Needs triage."
create_label "needs:decision" "EDEDED" "Needs decision / arbitration."
create_label "needs:review" "EDEDED" "Needs review."
create_label "needs:assets" "EDEDED" "Needs assets (design/content)."
echo "==> Labels done."
}
enable_discussions() {
if [[ "${ENABLE_DISCUSSIONS}" != "1" ]]; then
echo "==> Discussions: skipped (ENABLE_DISCUSSIONS=0)."
return 0
fi
echo "==> Enabling Discussions on ${REPO_FULL} ..."
local repo_id
repo_id="$(gh api graphql -f owner="${OWNER}" -f name="${REPO}" -f query='
query($owner:String!, $name:String!) {
repository(owner:$owner, name:$name) { id hasDiscussionsEnabled }
}' --jq '.data.repository.id')"
run "gh api graphql -f repositoryId=\"${repo_id}\" -F enabled=true -f query='\
mutation($repositoryId:ID!, $enabled:Boolean!) {\
updateRepository(input:{repositoryId:$repositoryId, hasDiscussionsEnabled:$enabled}) {\
repository { name hasDiscussionsEnabled }\
}\
}' >/dev/null"
echo "==> Discussions enabled."
}
setup_branch_protection() {
echo "==> Configuring branch protection for ${REPO_FULL}:${BRANCH} ..."
# Required check contexts (GitHub Actions job names):
# These MUST match the check names you see in PR -> Checks.
# If you change workflow/job names, update this list.
local -a contexts
contexts+=("PR Label Enforcement / label-enforcement")
contexts+=("Scope Guard / guard")
if [[ "${REQUIRE_BUILD_CHECKS}" == "1" ]]; then
contexts+=("Firmware CI / pio (esp32s3_arduino)")
contexts+=("Firmware CI / pio (esp32_arduino)")
contexts+=("Firmware CI / pio (native)")
contexts+=("Hardware CI (KiCad) / hw")
contexts+=("Compliance Gate / validate")
fi
# JSON array for contexts
local contexts_json
contexts_json="$(printf '%s\n' "${contexts[@]}" | python3 - <<'PY'
import sys, json
print(json.dumps([l.rstrip('\n') for l in sys.stdin if l.strip()]))
PY
)"
local body
body="$(cat <<JSON
{
"required_status_checks": {
"strict": true,
"contexts": ${contexts_json}
},
"enforce_admins": true,
"required_pull_request_reviews": {
"dismiss_stale_reviews": true,
"require_code_owner_reviews": false,
"required_approving_review_count": 1
},
"restrictions": null,
"required_linear_history": true,
"allow_force_pushes": false,
"allow_deletions": false,
"required_conversation_resolution": true
}
JSON
)"
if [[ "${DRY_RUN}" == "1" ]]; then
echo "[dry-run] Would PUT /repos/${OWNER}/${REPO}/branches/${BRANCH}/protection with body:"
echo "${body}"
return 0
fi
gh api \
--method PUT \
-H "Accept: application/vnd.github+json" \
"/repos/${OWNER}/${REPO}/branches/${BRANCH}/protection" \
--input - <<<"${body}" >/dev/null
echo "==> Branch protection enabled."
echo " Required checks:"
printf ' - %s\n' "${contexts[@]}"
}
main() {
need_gh
setup_labels
enable_discussions
setup_branch_protection
echo "✅ Done."
}
main
install_kill_life.sh
+91
View File
@@ -0,0 +1,91 @@
#!/bin/bash
# install_kill_life.sh — Installation complète pour Kill_LIFE
# Usage : ./install_kill_life.sh [feature-or-epic] [profile]
set -e
FEATURE=${1:-demo-feature}
PROFILE=${2:-prototype}
# 1. Mise à jour du système
if command -v apt-get &> /dev/null; then
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv git docker.io docker-compose
elif command -v brew &> /dev/null; then
brew update
brew install python git docker docker-compose
fi
# 2. Cloner le repo
if [ ! -d Kill_LIFE ]; then
git clone https://github.com/electron-rare/Kill_LIFE.git
fi
cd Kill_LIFE
# 3. Initialiser la spec
if [ ! -d specs ]; then
echo "[INFO] Initialisation du dossier specs..."
python3 tools/ai/specify_init.py --name "$FEATURE"
else
echo "[INFO] Dossier specs déjà présent."
fi
# 4. Profil compliance
echo "[INFO] Activation du profil compliance ($PROFILE)..."
python3 tools/compliance/use_profile.py --profile "$PROFILE"
# 5. Environnement Python
if [ ! -d .venv ]; then
python3 -m venv .venv
fi
source .venv/bin/activate
python3 -m pip install -U pip
# 6. Dépendances AI & hardware
if [ -f tools/ai/requirements.txt ]; then
pip install -r tools/ai/requirements.txt
fi
if [ -f tools/hw/schops/requirements.txt ]; then
pip install -r tools/hw/schops/requirements.txt
fi
pip install kicad-sch-api kicad-sch-mcp
# 7. Dépendances firmware
cd firmware || exit 1
python3 -m pip install -U platformio
pio run -e esp32s3_arduino
pio test -e native
cd ..
# 8. Pipeline hardware (KiCad)
bash tools/hw/hw_gate.sh hardware/kicad
python3 tools/watch/watch_hw.py
# 9. Documentation
python3 -m pip install -U mkdocs
mkdocs build --strict
# 10. Docker (optionnel)
if [ -f docker-compose.yml ]; then
echo "[INFO] Installation et lancement des containers Docker..."
sudo docker-compose up -d
fi
# 11. OpenClaw & agents
if [ -f openclaw/README.md ]; then
echo "[INFO] Sécurité OpenClaw : sandbox obligatoire, jamais d'accès aux secrets ou au code source."
fi
for agent in agents/*.md; do
echo "[INFO] Prompt agent disponible : $agent"
done
# 12. Fin
echo "\n✅ Installation complète terminée !\n"
echo "- Dossier specs : specs/$FEATURE"
echo "- Profil compliance : $PROFILE"
echo "- Firmware build & tests : OK"
echo "- Pipeline hardware : OK"
echo "- Documentation générée dans site/"
echo "- Docker containers : lancés (si docker-compose.yml présent)"
echo "- OpenClaw & agents : setup OK"
mkdocs.yml
+2
View File
@@ -5,6 +5,8 @@ nav:
- Home: docs/index.md
- Install: docs/INSTALL.md
- Runbook: docs/RUNBOOK.md
- FAQ: docs/FAQ.md
- Plans: docs/plans/README.md
- Specs:
- Overview: specs/README.md
- Intake: specs/00_intake.md