Introduction

Shingan (心眼) est un framework léger et réutilisable pour orchestrer le développement assisté par IA. Inspiré de BMAD Method.

Pourquoi ce framework ?

Travailler avec un AI coding agent (Claude Code, Cursor, Copilot...) est puissant, mais sans structure :

• L'IA fait des choix architecturaux incohérents
• Les reviews de code sont superficielles
• Les bugs sont patchés sans comprendre la root cause
• Le contexte se perd entre les sessions

Ce framework résout ces problèmes en fournissant :

1. Des agents — rôles IA spécialisés avec identité et contraintes claires
2. Des skills — workflows réutilisables invocables via /commande
3. Des agents — sous-agents ciblés pour des tâches spécifiques
4. Des profiles — contexte technologique par stack (Rust, Python, Java...)
5. Des modèles configurables — opus, sonnet ou haiku selon le rôle
6. Des workflows — pipelines orchestrant le tout avec des gates

Architecture

framework/
├── agents/              ← 9 agents (analyst, architect, executor, code-reviewer...)
├── skills/              ← 20 skills (structure plate)
│   ├── kensho/          ← Pipeline principal (APEX methodology)
│   ├── bugfix/          ← Diagnostic + correction
│   ├── commit/          ← Commit conventionnel
│   └── ...              ← review-code, debug, brainstorm, oneshot, etc.
├── profiles/            ← Contexte technologique (rust, tauri, vue...)
├── models.md            ← Configuration centralisée des modèles
├── scripts/             ← Hooks d'automatisation
├── workflows/           ← Pipelines visuels
└── templates/           ← Documents standardisés (PRD, ADR)

Concepts clés

Progressive Disclosure

Le framework charge le contexte progressivement pour ne pas saturer la fenêtre de l'IA :

Niveau	Contenu	Quand
1 — Découverte	Frontmatter YAML (nom, description)	L'IA sait quand utiliser le skill
2 — Activation	Corps du SKILL.md	Instructions étape par étape
3 — Détails	REFERENCE.md + resources/	Contexte approfondi si nécessaire

Steps avec Gates

Chaque skill a des étapes numérotées. On passe à la suivante en tapant next. Chaque step produit un output (fichier) que le step suivant consomme.

Step 01 → [Gate: output validé?] → Step 02 → [Gate] → Step 03 → ...

State Management via Fichiers

L'état est géré par les fichiers produits — pas de base de données :

docs/
├── specs/       ← Output analyst (PRD)
├── plans/       ← Output architect (ADR)
├── reviews/     ← Output reviewer
├── bugs/        ← Output bugfix
└── kensho/      ← Output Kensho

Pour qui ?

Ce framework est conçu pour le développeur qui utilise un AI coding agent au quotidien et veut :

• Structurer ses interactions avec l'IA
• Avoir des workflows reproductibles
• Garder une trace des décisions
• Maintenir la qualité du code

Profiles technologiques

Les profiles injectent des conventions spécifiques à votre stack dans tous les agents. Un agent architect avec le profil rust propose des patterns Tauri et tokio. Sans profil, il propose des solutions génériques.

# Dans CLAUDE.md
profile: rust, tauri, vue-typescript

Modèles configurables

La configuration des modèles permet de choisir quel modèle (opus, sonnet, haiku) utilise chaque agent. Trois presets sont disponibles : budget, standard, quality.

# Dans CLAUDE.md
models:
  preset: standard
  override:
    executor: opus

Prêt à commencer ?

La méthode la plus simple est l'installation via plugin — une seule commande et Shingan est disponible. Pour personnaliser le framework, voir l'installation manuelle.