IdeaClyst

★Guía paso a paso

El camino más rápido desde un clon reciente hasta un paquete de planificación completo. El modo simulado es el predeterminado, por lo que no necesitas ninguna CLI para probarlo de principio a fin.

01Qué es

IdeaClyst es una aplicación Next.js local-first que convierte una idea de producto en bruto en un completo paquete de planificación para fundadores. Lo hace no con un solo prompt, sino orquestando un consejo estructurado — una deliberación de cinco pasos entre dos herramientas de línea de comandos de IA que adoptan roles opuestos y se critican mutuamente antes de llegar a un veredicto.

Imagínalo como una pequeña sala de juntas: un fundador de SaaS escéptico (Claude) y un CTO pragmático (Codex) debaten tu idea hasta darle forma. El resultado se divide en Resumen, Backlog MVP, Riesgos, Pruebas de validación y Próximos prompts listos para pegar.

02Funciones de un vistazo

03Arquitectura

IdeaClyst tiene cuatro capas, y la disciplina de diseño es que solo una de ellas sabe si estás en modo simulado o en modo CLI real.

// la única rama que conoce el modo — agents/index.ts
export async function runAgent(agent, prompt, ctx) {
  if (agentMode() === "mock")
    return runMock(ctx.run, ctx.stepKey);   // ignora el prompt, usa la ejecución estructurada
  return agent === "claude"
    ? runClaude(prompt, runDir)            // `claude` real (sin -p), en directorio de ejecución
    : runCodex(prompt);                    // `codex exec` real
}

04El consejo de 5 pasos

Este es el corazón de la aplicación. Los dos agentes se alternan, y el detalle crucial está en la línea "ve" de cada paso — cada agente lee resultados previos específicos, lo que lo convierte en una deliberación en lugar de cinco prompts aislados.

◆Descubrimiento de ideas

La mayor parte de IdeaClyst evalúa una idea que tú aportas. El Descubrimiento de ideas (la ruta /discover) hace lo contrario — encuentra ideas para ti, fundamentadas en lo que la gente está luchando realmente en la web. La página en blanco es la parte más difícil de construir; Descubrimiento la reemplaza con señales de demanda real.

Los descubrimientos persisten en disco bajo .ideaclyst/discoveries/<id>/ (un discovery.json, MARKET_READ.md, OPPORTUNITY_MAP.md, CANDIDATES.md y artefactos de informe/versión), y la página de descubrimiento sondea en vivo, igual que una ejecución. El radar de tendencias escribe en .ideaclyst/trends; perspectivas, monitores, decisiones, exportaciones, carriles de fuente, importaciones de validación y entrevistas escriben en sus propias carpetas locales bajo .ideaclyst/. La cabecera de la aplicación permanece ligera: Explorar abre /discover, /today y /trends; Espacio de trabajo abre sesiones, biblioteca y validación. Comparar, evidencia, decisiones, perspectivas, monitores, entrevistas, clústeres y configuración de investigación se enlazan contextualmente desde esas páginas.

◆Inteligencia de hoja de ruta

IdeaClyst puede leer la hoja de ruta de un proyecto de Threlmark — un gestor de hojas de ruta local-first independiente — y convertirla en sugerencias de crecimiento fundamentadas. Apúntalo a un proyecto (la ruta /roadmap) y propone nuevas funciones, productos derivados y servicios, cada uno puntuado como una tarjeta de hoja de ruta y respaldado por evidencia web real. Revísalos y luego envía los mejores de vuelta al Inbox de Threlmark.

Los análisis persisten bajo .ideaclyst/roadmap/<id>/ y la página sondea en vivo, igual que una ejecución. La fuente de datos y cualquier URL base REST se configuran en /settings; consulta las nuevas variables en Configuración. La inteligencia de hoja de ruta está controlada por modo como el resto de la investigación — se ejecuta en vivo + estricto y muestra solo datos reales.

05Ciclo de vida de la solicitud

Desde el momento en que pulsas enviar, este es el camino exacto — ten en cuenta que el servidor responde antes de que el consejo termine:

// api/runs/route.ts — la entrega de disparar y olvidar
const run = await createRun(input);
void startRun(run.id);              // NO se espera — se ejecuta en segundo plano
return NextResponse.json({ runId: run.id }, { status: 201 });

06Modo simulado vs. CLI

Una variable de entorno, IDEACLYST_AGENT_MODE, selecciona el backend. El orquestador y la interfaz son idénticos en ambos modos — solo agents/ se comporta de forma diferente.

07Cómo funcionan las llamadas CLI

En modo CLI, cada paso del consejo lanza un proceso real. Ambos backends usan args en array + stdin (nunca una cadena de shell), de modo que un prompt no puede romper el escape ni inyectar sintaxis de shell, y ambos aplican un tiempo de espera por llamada (predeterminado 180 s).

Backend Claude

Sin -p / --print. Cuando la salida estándar de claude no es un TTY (aquí es una tubería), la CLI se ejecuta de forma no interactiva e imprime una única respuesta y luego sale. Así que IdeaClyst simplemente envía el prompt por stdin y lee stdout — no se necesita ninguna flag de impresión. --tools "" lo mantiene como una completación de texto puro (sin acciones agénticas sobre archivos), y se ejecuta dentro del directorio de ejecución propio de la idea (cwd del proceso spawneado):

// agents/claude.ts — se ejecuta en el directorio propio de la ejecución
claude --tools ""                  // prompt por stdin, stdout en tubería (no TTY)
       [--model <model>]            // opcional IDEACLYST_CLAUDE_MODEL

Devuelve stdout recortado. Un binario faltante (ENOENT), una salida no nula sin salida o una salida vacía rechazan con un mensaje claro de "vuelve al modo simulado".

Backend Codex

Ejecuta Codex de forma no interactiva, en modo de solo lectura, dentro de un directorio de trabajo temporal desechable para que no pueda tocar tu sistema de archivos — solo queremos la completación de texto:

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

El mensaje final limpio se lee del archivo de salida -o; el flujo de eventos --json se analiza como alternativa (y para mostrar un error de API limpio). El directorio temporal siempre se elimina después. Un IDEACLYST_CODEX_MODEL opcional añade -m <model>, de lo contrario se delega en ~/.codex/config.toml.

08Modelo de datos y almacenamiento

IdeaClyst es local-first: no hay base de datos ni estado en memoria. Cada ejecución es un directorio, y run.json es la única fuente de verdad — el orquestador lo reescribe después de cada paso, la API de sondeo simplemente lo lee de vuelta.

Estructura en disco

El registro de ejecución

Una ejecución lleva el briefing (título, idea, objetivo, cliente objetivo opcional / restricciones / pila preferida), un status de queued → running → completed | failed, una etiqueta currentStep legible por humanos para la interfaz, y un objeto outputs que comienza vacío y se rellena. Los IDs de ejecución son slugs con prefijo de marca de tiempo, por lo que un ordenamiento inverso de cadenas produce las más recientes primero de forma gratuita.

09Referencia de la API

Lista todas las ejecuciones, las más recientes primero. Devuelve { runs: Run[] }.

Valida el briefing, crea una ejecución en cola, lanza el consejo en segundo plano y devuelve { runId } (201). Validación: título requerido; idea ≥ 10 caracteres; objetivo ∈ validate · plan · build · pitch · refine.

// cuerpo de la solicitud
{
  "title": "...",            // requerido
  "idea": "...",             // requerido, 10+ caracteres
  "goal": "validate",        // requerido, uno de los cinco
  "targetCustomer": "...",   // opcional
  "constraints": "...",      // opcional
  "preferredStack": "..."    // opcional
}

Devuelve una sola ejecución como { run: Run } — esto es lo que sondea la página de detalle cada 1,5 s.

Controlar una ejecución desde el terminal

La interfaz es solo un cliente de esta API — todo lo que puedes hacer en el navegador lo puedes hacer desde un script. Crea una ejecución, sondea hasta que se complete y luego lee el paquete del disco:

# 1. Crear una ejecución → devuelve { "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. Sondear el estado hasta completado (cada pocos segundos)
curl -s http://localhost:5417/api/runs/<runId> | jq '.run.status, .run.currentStep'

# 3. Leer el paquete terminado
cat .ideaclyst/runs/<runId>/FINAL_PLAN.md

10Mapa de archivos

11Configuración

Toda la configuración vive en .env.local (copia desde .env.example). No se requieren secretos.

Investigación y descubrimiento

Todo de mejor esfuerzo; la ruta en vivo necesita una instalación de Chrome/Chromium. La investigación sigue el modo del agente a menos que se sobreescriba.

Inteligencia de hoja de ruta (Threlmark)

Desde dónde IdeaClyst lee los proyectos Threlmark. La página /settings también edita estos valores; las variables de entorno tienen precedencia.

12Ejecución

# inicio rápido — modo simulado, sin CLIs necesarias
npm install
cp .env.example .env.local
npm run dev          # → http://localhost:5417

# luego: abre la app → "Start an Idea Session" → envía → observa cómo se ensambla

13Límites y solución de problemas