Flujos de Inicialización de Proyecto

Planu tiene dos caminos de inicio distintos:

1. Proyecto existente — Planu debe inspeccionar lo que ya existe antes de pedirte elegir lenguaje o framework.
2. Proyecto nuevo — Planu debe preguntar qué quieres construir y dónde debe vivir la app antes de inicializar nada.

Esta separación evita el error de setup más común: iniciar tu asistente de IA desde una carpeta padre como Documents/desarrollo e inicializar Planu por accidente en esa carpeta padre, en vez de hacerlo dentro de la carpeta real de la app.

Proyecto Existente

Cuando el proyecto ya existe, Planu debe empezar por evidencia. Escanea manifests, lockfiles, archivos de configuración, estructura de código e instrucciones de agentes existentes. Si el stack es claro, sugiere lo detectado. Si hay ambigüedad, pregunta cuál es el lenguaje/framework principal.

flowchart TD
  A["User asks Planu to work in an existing repo"] --> B["Scan project evidence"]
  B --> C{"Language/framework clear?"}
  C -- "Yes" --> D["Suggest detected stack with evidence"]
  C -- "No or ambiguous" --> E["Ask user to confirm primary stack"]
  D --> F["Verify official docs and versions"]
  E --> F
  F --> G["Persist stack decision in spec"]
  G --> H["Agents implement only the approved contract"]

El resultado debería sentirse así:

Planu detectó TypeScript, Node y un MCP SDK desde package.json, tsconfig.json y el lockfile. Confirma que este es el stack principal antes de crear la spec.

Planu no debe cambiar frameworks en silencio, elegir el default más popular ni dejar que el modelo escoja un stack porque le gusta.

Proyecto Nuevo

Cuando empiezas desde una carpeta padre, Planu no debe inicializar esa carpeta padre. Primero debe confirmar la carpeta de la app y luego inicializar Planu solo dentro de esa carpeta.

flowchart TD
  A["User starts from parent workspace"] --> B["Detect new project request"]
  B --> C["Ask app name and target folder"]
  C --> D["Ask language/framework or suggest from goal"]
  D --> E["Verify official docs and versions"]
  E --> F["Create or confirm project folder"]
  F --> G["Run init_project inside project folder only"]
  G --> H["Create initial spec before production code"]

Ejemplo:

Carpeta actual:
/workspace/Documents/desarrollo

Solicitud del usuario:
"Use Planu and create an appointments API"

Carpeta correcta del proyecto:
/workspace/Documents/desarrollo/citas-api

Planu debe inicializar citas-api, no desarrollo.

Technology Selection Contract

Planu debe pasar las decisiones de stack a los agentes como un contrato, no como una preferencia hardcodeada del producto.

Situación	Comportamiento de Planu
Proyecto existente con evidencia clara	Detecta primero y luego sugiere con evidencia
Proyecto existente con conflictos	Pregunta cuál lenguaje/framework es principal
Proyecto nuevo	Pregunta nombre de app, carpeta, lenguaje, framework y plataforma
El usuario no está seguro	Sugiere opciones según el objetivo y fuentes oficiales
Versiones o APIs importan	Verifica contra docs oficiales antes de aprobar
Empieza la implementación del agente	Usa solo la decisión de stack aprobada

Comportamiento prohibido:

• elegir un framework porque al LLM le gusta;
• hardcodear un stack por defecto en el código de Planu;
• inicializar una carpeta padre cuando el usuario quiere una app nueva;
• tratar un fallback o una suposición como decisión oficial.

Qué Crea Planu

Cuando init_project corre dentro de la carpeta correcta del proyecto, Planu puede crear:

Estado canónico de Planu

Path	Propósito
planu.json	Configuración de Planu para el proyecto
planu/conventions.json	Convenciones detectadas y resumen del escaneo
planu/context.md	Contexto portable del proyecto para que los agentes retomen rápido
planu/project.json	Identidad lógica portable; el estado operativo de sesión permanece externo
planu/releases/pending.json	Metadata de release pendiente cuando se prepara una release
planu/specs/SPEC-XXX-slug/spec.md	Spec unificada creada por create_spec

Adaptadores nativos por host

Planu no guarda agents, skills o rules como archivos primarios bajo planu/. Esos archivos se generan donde cada host realmente los lee.

Path	Propósito
.planu/skill-registry.json	Metadata local del registro de skills
AGENTS.md	Instrucciones universales para agentes que leen AGENTS.md
.cursorrules / .windsurfrules	Hints de workflow para Cursor y Windsurf
.openai/config.toml	Config de workspace Codex cuando Codex es detectado
.agents/skills/*	Skills de Codex cuando Codex es detectado
.codex/agents/*	Role agents de Codex cuando Codex soporta archivos locales de roles
.cursor/rules/planu.mdc	Regla de proyecto Cursor cuando Cursor es detectado
.claude/rules/*	Rules de Claude Code cuando Claude Code es detectado
.claude/skills/*	Skills de workflow para Claude Code cuando Claude Code es detectado
.claude/agents/*	Subagents de Claude Code cuando Claude Code es detectado
.claude/hooks/*	Hooks de Claude Code cuando Claude Code es detectado
GEMINI.md / .gemini/skills/*	Instrucciones y skills de Gemini cuando Gemini es detectado

La memoria runtime del proyecto se guarda fuera del repo en el directorio de datos de Planu del usuario, indexada por el path del proyecto. Los archivos versionados del proyecto se mantienen enfocados en specs, config, rules, skills e instrucciones para hosts.

Regla Práctica

Si estás en una carpeta padre y pides una app nueva, espera que Planu pregunte:

• ¿Cómo se debe llamar la carpeta de la app?
• ¿Qué lenguaje y framework quieres usar?
• ¿Planu debe crear la carpeta ahora?
• ¿Planu debe inicializar specs dentro de esa carpeta?

Si estás dentro de un repo existente, espera que Planu inspeccione primero y pregunte solo cuando el stack detectado esté incompleto o sea ambiguo.

Siguiente: lee el Flujo SDD para ver cómo la spec aprobada avanza por implementación y validación.