IdeaClyst

★Guide pas à pas

Le chemin le plus rapide depuis un dépôt fraîchement cloné jusqu'à un dossier de planification complet. Le mode simulation est activé par défaut — aucun CLI n'est nécessaire pour tout tester de bout en bout.

01Ce que c'est

IdeaClyst est une application Next.js locale qui transforme une idée de produit brute en un dossier de planification complet pour fondateur. Il ne s'agit pas d'une simple invite, mais de l'orchestration d'un conseil structuré — une délibération en cinq étapes entre deux outils d'IA en ligne de commande qui adoptent des rôles opposés et se critiquent mutuellement avant de rendre un verdict.

Imaginez une petite salle de conseil : un fondateur SaaS sceptique (Claude) et un CTO pragmatique (Codex) débattent de votre idée jusqu'à la mettre en forme. Le résultat est divisé en Résumé, Backlog MVP, Risques, Tests de validation, et Prochaines invites prêtes à coller.

02Fonctionnalités en bref

03Architecture

IdeaClyst comporte quatre couches, et la discipline de conception est que une seule d'entre elles sait si vous êtes en mode simulation ou en mode CLI réel.

// la seule branche qui connaît le mode — agents/index.ts
export async function runAgent(agent, prompt, ctx) {
  if (agentMode() === "mock")
    return runMock(ctx.run, ctx.stepKey);   // ignore le prompt, utilise la session structurée
  return agent === "claude"
    ? runClaude(prompt, runDir)            // vrai `claude` (sans -p), dans le répertoire de session
    : runCodex(prompt);                    // vrai `codex exec`
}

04Le conseil en 5 étapes

C'est le cœur de l'application. Les deux agents alternent, et le détail crucial se trouve dans la ligne « voit » de chaque étape — chaque agent lit des sorties précédentes spécifiques, ce qui en fait une délibération plutôt que cinq invites isolées.

◆Découverte d'idées

La majeure partie d'IdeaClyst évalue une idée que vous apportez. La Découverte d'idées (la route /discover) fait l'inverse — elle trouve des idées pour vous, ancrées dans ce avec quoi les gens luttent réellement sur le web. La page blanche est la partie la plus difficile de la construction ; la Découverte la remplace par de véritables signaux de demande.

Les découvertes persistent sur disque sous .ideaclyst/discoveries/<id>/ (un discovery.json, MARKET_READ.md, OPPORTUNITY_MAP.md, CANDIDATES.md, et des artifacts de rapport/version), et la page de découverte actualise en direct, tout comme une session. Le radar de tendances écrit dans .ideaclyst/trends ; insights, moniteurs, décisions, exports, couloirs de sources, imports de validation, et entretiens s'écrivent dans leurs propres dossiers locaux sous .ideaclyst/. L'en-tête de l'application reste épuré : Explorer ouvre /discover, /today, et /trends ; Espace de travail ouvre sessions, bibliothèque, et validation. Comparer, preuves, décisions, insights, moniteurs, entretiens, clusters, et paramètres de recherche sont liés contextuellement depuis ces pages.

◆Intelligence de feuille de route

IdeaClyst peut lire la feuille de route d'un projet Threlmark — un gestionnaire de feuille de route local-first distinct — et la transformer en suggestions de croissance ancrées dans la réalité. Pointez-le vers un projet (la route /roadmap) et il propose de nouvelles fonctionnalités, produits dérivés, et services, chacun noté comme une carte de feuille de route et appuyé par de vraies preuves web. Examinez-les, puis renvoyez les meilleurs dans la Boîte de réception de Threlmark.

Les analyses persistent sous .ideaclyst/roadmap/<id>/ et la page actualise en direct, tout comme une session. La source de données et tout URL de base REST sont définis dans /settings ; voir les nouvelles variables dans Configuration. L'intelligence de feuille de route est soumise au mode comme le reste de la recherche — elle s'exécute en mode réel + strict et affiche uniquement des données réelles.

05Cycle de vie d'une requête

Depuis le moment où vous appuyez sur soumettre, voici le chemin exact — notez que le serveur répond avant que le conseil ait terminé :

// api/runs/route.ts — le transfert déclencher-et-oublier
const run = await createRun(input);
void startRun(run.id);              // PAS attendu — s'exécute en arrière-plan
return NextResponse.json({ runId: run.id }, { status: 201 });

06Mode simulation vs. CLI

Une seule variable d'environnement, IDEACLYST_AGENT_MODE, sélectionne le backend. L'orchestrateur et l'interface sont identiques dans les deux modes — seul agents/ se comporte différemment.

07Fonctionnement des appels CLI

En mode CLI, chaque étape du conseil lance un vrai processus. Les deux backends utilisent des arguments en tableau + stdin (jamais une chaîne shell), donc une invite ne peut pas casser l'échappement ou injecter de la syntaxe shell, et tous deux appliquent un délai d'attente par appel (défaut 180 s).

Backend Claude

Sans -p / --print. Quand la sortie standard de claude n'est pas un TTY (ici c'est un pipe), le CLI s'exécute de manière non-interactive et affiche une réponse unique, puis se termine. Donc IdeaClyst envoie simplement l'invite sur stdin et lit stdout — aucun drapeau d'impression nécessaire. --tools "" en fait une complétion de texte pure (sans actions de fichiers agentiques), et il s'exécute dans le répertoire de session propre de l'idée (spawn cwd) :

// agents/claude.ts — s'exécute dans le répertoire propre de la session
claude --tools ""                  // invite sur stdin, stdout pipé (non-TTY)
       [--model <model>]            // optionnel IDEACLYST_CLAUDE_MODEL

Retourne la sortie standard nettoyée. Un binaire manquant (ENOENT), une sortie non-nulle sans sortie, ou une sortie vide rejettent chacun avec un message clair « revenir au mode simulation ».

Backend Codex

Exécute Codex de manière non-interactive, en lecture seule, dans un répertoire de travail temporaire jetable pour qu'il ne puisse pas toucher votre système de fichiers — nous voulons uniquement la complétion de texte :

// agents/codex.ts
codex exec --json --skip-git-repo-check --ephemeral \
  -s read-only --color never \
  -C <temp-dir> -o last-message.txt -    // invite sur stdin

Le message final propre est lu depuis le fichier de sortie -o ; le flux d'événements --json est analysé comme solution de repli (et pour faire remonter une erreur d'API propre). Le répertoire temporaire est toujours supprimé ensuite. Un IDEACLYST_CODEX_MODEL optionnel ajoute -m <model>, sinon il s'en remet à ~/.codex/config.toml.

08Modèle de données & stockage

IdeaClyst est local-first : il n'y a ni base de données ni état en mémoire. Chaque session est un répertoire, et run.json est l'unique source de vérité — l'orchestrateur le réécrit après chaque étape, l'API de polling le relit simplement.

Structure sur disque

L'enregistrement de session

Une session contient le brief (titre, idée, objectif, client cible optionnel / contraintes / pile préférée), un status de queued → running → completed | failed, une étiquette currentStep lisible par l'humain pour l'interface, et un objet outputs qui commence vide et se remplit. Les identifiants de session sont des slugs préfixés par horodatage, de sorte qu'un tri inversé de chaînes donne le plus récent en premier gratuitement.

09Référence API

Liste toutes les sessions, les plus récentes en premier. Retourne { runs: Run[] }.

Valide le brief, crée une session en file d'attente, déclenche le conseil en arrière-plan, et retourne { runId } (201). Validation : titre requis ; idée ≥ 10 caractères ; objectif ∈ validate · plan · build · pitch · refine.

// corps de la requête
{
  "title": "...",            // requis
  "idea": "...",             // requis, 10+ caractères
  "goal": "validate",        // requis, l'un des cinq
  "targetCustomer": "...",   // optionnel
  "constraints": "...",      // optionnel
  "preferredStack": "..."    // optionnel
}

Retourne une session unique sous forme de { run: Run } — c'est ce que la page de détail interroge toutes les 1,5 s.

Piloter une session depuis le terminal

L'interface n'est qu'un client de cette API — tout ce que vous pouvez faire dans le navigateur, vous pouvez le faire depuis un script. Créez une session, interrogez-la jusqu'à ce qu'elle se termine, puis lisez le dossier sur disque :

# 1. Créer une session → retourne { "runId": "..." }
curl -s -X POST http://localhost:5417/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"title":"StandupScribe","idea":"A Slack bot that posts a daily standup digest.","goal":"plan"}'

# 2. Interroger le statut jusqu'à complétion (toutes les quelques secondes)
curl -s http://localhost:5417/api/runs/<runId> | jq '.run.status, .run.currentStep'

# 3. Lire le dossier terminé
cat .ideaclyst/runs/<runId>/FINAL_PLAN.md

10Plan des fichiers

11Configuration

Toute la configuration se trouve dans .env.local (copié depuis .env.example). Aucun secret n'est requis.

Recherche & découverte

Tout au mieux-effort ; le chemin réel nécessite une installation Chrome/Chromium. La recherche suit le mode agent sauf si elle est surchargée.

Intelligence de feuille de route (Threlmark)

Indique à IdeaClyst d'où lire les projets Threlmark. La page /settings les modifie également ; les variables d'environnement ont la priorité.

12Lancer l'application

# démarrage rapide — mode simulation, aucun CLI requis
npm install
cp .env.example .env.local
npm run dev          # → http://localhost:5417

# ensuite : ouvrir l'app → « Démarrer une session d'idée » → soumettre → observer l'assemblage

13Limites & résolution de problèmes