/kensho

10 steps principal

Le skill principal de Shingan. Kensho — méthodologie APEX (Analyze → Spec → Plan → Execute → eXamine). Aucun code n'est écrit tant que la spécification n'est pas validée.

Quand l'utiliser

• Features de toute taille
• Corrections de bugs complexes
• Refactoring important
• Tout changement nécessitant de la structure

Usage

/shingan:kensho add authentication middleware
/shingan:kensho -a -s implement user registration    # autonome + sauvegarde
/shingan:kensho -a -x -s fix login bug               # avec review adversariale
/shingan:kensho -a -x -t -s add payment processing   # pipeline complet
/shingan:kensho -r 01-auth-middleware                 # reprendre une tâche
/shingan:kensho -i add search feature                 # configurer les flags au démarrage

Flags

Flag	Description
-a	Auto — sauter les confirmations (sauf la spec, toujours validée)
-x	Examine — review adversariale après validation
-s	Save — sauvegarder les outputs dans docs/kensho/{task-id}/
-t	Test — inclure création et exécution de tests
-e	Economy — pas de subagents, économiser les tokens
-r	Resume — reprendre une tâche précédente
-i	Interactive — configurer les flags au démarrage

Délégation

Chaque step qui utilise un agent spécialisé déclare un bloc <delegation> obligatoire dans son fichier step :

Step	Agent	Tier	Délégation
00 Init	—	—	Main context
01 Analyze	architect	opus	Obligatoire
01b Spec	analyst	opus	Obligatoire
02 Plan	architect	opus	Obligatoire
03 Execute	executor	sonnet	Obligatoire
04 Validate	—	—	Main context
05 Examine	code-reviewer	opus	Obligatoire
06 Resolve	—	—	Main context
07 Tests	test-engineer	sonnet	Obligatoire
08 Run Tests	—	—	Main context
09 Finish	—	—	Main context

Mode économie

Le flag -e est la seule exception à la délégation obligatoire. Quand il est actif, tous les steps s'exécutent inline dans le contexte principal, sans dispatcher de subagents.

Pipeline

00 Init → 01 Analyze → 01b Spec → 02 Plan → 03 Execute → 04 Validate → 05 Examine → 06 Resolve → 07 Tests → 08 Run Tests → 09 Finish
                         ▲                                     ▲
                    gate obligatoire                    vérifie la spec
                   (même en mode -a)

Steps détaillés

Step 00 — Init

Parse les flags, génère le task-id, charge les profiles technologiques et la configuration des modèles. Capture les attentes initiales (les critères formels viendront au step 01b).

Output : 00-context.md

Step 01 — Analyze

Agent : architect (exploration)

Délégation obligatoire

Ce step est délégué à l'agent architect (opus). En mode économie (-e), le travail est effectué inline sans subagent.

Explore le codebase en lecture seule : structure du projet, fichiers liés, patterns existants, dépendances, conventions. Aucune proposition — uniquement de l'observation.

Output : 01-analyze.md

Step 01b — Spec (Proposal) ⭐

Agent : analyst

Délégation obligatoire

Ce step est délégué à l'agent analyst (opus). En mode économie (-e), le travail est effectué inline sans subagent.

Le coeur du spec-driven development. Génère une spécification formelle comprenant :

• Purpose — ce que le changement fait et pourquoi
• Requirements — exigences SHALL/SHOULD/MAY (style RFC 2119)
• Scenarios — Given/When/Then pour chaque cas d'usage
• Design decisions — choix techniques avec alternatives et justification
• Spec deltas — si modification d'existant, diff des requirements
• Acceptance criteria — conditions testables pour "done"
• Out of scope — ce que ça ne fait PAS (anti scope creep)

Gate obligatoire

L'utilisateur doit toujours approuver la spec, même avec le flag -a. C'est le contrat entre l'utilisateur et l'implémentation.

Output : 01b-spec.md

Step 02 — Plan

Agent : architect (design)

Délégation obligatoire

Ce step est délégué à l'agent architect (opus). En mode économie (-e), le travail est effectué inline sans subagent.

Transforme la spec approuvée en plan d'implémentation fichier par fichier, avec ordre de dépendance. Inclut un tableau de traçabilité REQ → fichiers impactés.

Output : 02-plan.md

Step 03 — Execute

Agent : executor

Délégation obligatoire

Ce step est délégué à l'agent executor (sonnet). En mode économie (-e), le travail est effectué inline sans subagent.

Implémente le plan avec un suivi todo-driven. Chaque fichier est modifié dans l'ordre défini par le plan.

Output : 03-execute.md

Step 04 — Validate

Vérification mécanique (build, tests, imports) puis vérification de la spec : chaque requirement et chaque scénario est vérifié contre l'implémentation. Les acceptance criteria sont marqués pass/fail avec preuves.

Output : 04-validate.md

Step 05 — Examine (flag -x)

Agent : code-reviewer (adversarial)

Délégation obligatoire

Ce step est délégué à l'agent code-reviewer (opus). En mode économie (-e), le travail est effectué inline sans subagent.

Review adversariale : sécurité, edge cases, performance, qualité du code. Cherche activement les failles.

Output : 05-examine.md

Step 06 — Resolve (si findings au step 05)

Agent : executor

Corrige les problèmes identifiés par la review adversariale.

Output : 06-resolve.md

Step 07 — Tests (flag -t)

Agent : test-engineer

Délégation obligatoire

Ce step est délégué à l'agent test-engineer (sonnet). En mode économie (-e), le travail est effectué inline sans subagent.

Analyse la couverture de test existante et crée les tests manquants.

Output : fichiers de tests

Step 08 — Run Tests (flag -t)

Exécute les tests en boucle jusqu'à ce qu'ils passent (max 3 itérations).

Output : 08-test-results.md

Step 09 — Finish

Résumé final, commit conventionnel, nettoyage.

Output : 09-summary.md

Outputs (flag -s)

docs/kensho/{task-id}/
├── 00-context.md       ← Init
├── 01-analyze.md       ← Analyze
├── 01b-spec.md         ← Spec proposal (le contrat)
├── 02-plan.md          ← Plan d'implémentation
├── 03-execute.md       ← Log d'exécution
├── 04-validate.md      ← Résultats validation + spec check
├── 05-examine.md       ← Review adversariale (si -x)
├── 06-resolve.md       ← Corrections (si findings)
├── 08-test-results.md  ← Résultats tests (si -t)
└── 09-summary.md       ← Résumé final

Presets

Preset	Flags	Usage
Budget	-e	Économiser les tokens
Standard	-s	Sauvegarder les outputs
Full quality	-x -s -t	Review + tests + sauvegarde
Full pipeline	-a -x -s -t	Autonome avec toute la qualité