app-init

name	app-init
description	Initialize or refresh the canonical project documents `doc/app/app_prd.md` and `doc/app/app_spec.md`. These are the single source of truth that `/prd`, `/plan`, and `/visual-setup` consult before asking the user questions whose answers can be inherited from the project. Idempotent: safe to run multiple times. Detects state (empty / tracking-populated / app-already-exists) and adapts behavior accordingly. Use when the user says "app init", "init app docs", "create canonical docs", "setup project canon", or after a fresh clone before running `/prd`.
context	direct
allowed-tools	Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(pwd), Bash(realpath:*)

/app-init — Inicializa o refresca documentos canónicos del proyecto

Genera o actualiza doc/app/app_prd.md y doc/app/app_spec.md. Son la fuente de verdad que el resto del pipeline (/prd, /plan, /visual-setup) consulta para no repreguntar al usuario lo que ya está decidido a nivel de proyecto.

Uso

/app-init                       # Detecta estado y actúa
/app-init --refresh             # Reescaner stack/backend y refrescar zonas auto
/app-init --upgrade-zones       # Para docs creados manualmente sin marcadores
/app-init --migrate-freeform-data  # Reservado para PR-9 (v5.28→v5.29 con datos en VPS)

---

Paso 1 — Detectar estado del proyecto

Ejecuta esta detección antes de hacer nada:

1. ¿Estamos en un repo git?

   git rev-parse --show-toplevel
   

   Si falla → aborta con mensaje "El skill /app-init requiere un repo git inicializado. Ejecuta git init primero." Si tiene éxito → guarda el path como PROJECT_ROOT (absoluto, será el que pase a set_auth_token para FreeForm).

2. ¿Existe doc/app/?

   • Si NO → modo init.
   • Si SÍ y los archivos canónicos existen → modo refresh (no destructivo).
   • Si SÍ pero los archivos no tienen marcadores @specbox:zone → modo upgrade_zones (asistir al usuario para insertar marcadores sin destruir contenido).

3. ¿Existe doc/tracking/?

   • Si SÍ → puede inferir stack y roadmap desde items.json.
   • Si NO → /app-init también creará doc/tracking/ y configurará FreeForm como backend default.

4. ¿Existe .claude/settings.local.json?

   • Si SÍ → respeta specbox.autopilot.level y backend_type existentes; solo añade lo que falte.
   • Si NO → genera con level: "equilibrado" y backend_type: "freeform" por defecto.

---

Paso 2 — Modo init: crear desde cero

2.1 — Preguntas mínimas

Una sola pasada de 5 preguntas (no más). Las respuestas se mapean a las zonas manual de app_prd.md y app_spec.md.

1. Nombre del proyecto (corto, slug-friendly):
2. ¿Qué problema resuelve esta aplicación? (1-2 frases)
3. ¿Quién es la audiencia? Lista de targets/ICPs separados por coma.
4. Stack técnico principal: [Flutter | React | Python+FastAPI | Go | Apps Script | otro]
5. ¿Necesitas reporting externo a un cliente?
   [a] No — uso FreeForm (rápido, local, sin API)
   [b] Sí — Trello
   [c] Sí — Plane

Nota sobre la pregunta 5: con autopilot equilibrado o superior, esta pregunta se auto-confirma a freeform (decision_key: backend_selection, default canónico de v5.29.0). Si el usuario quiere otro backend, debe declararlo explícitamente.

2.2 — Generar archivos

1. Crea doc/app/ si no existe.
2. Lee templates/app_prd.md.template y templates/app_spec.md.template desde el engine.
3. Sustituye placeholders {project_name} y {date_iso} (ISO 8601 UTC).
4. Escribe doc/app/app_prd.md y doc/app/app_spec.md con las zonas pobladas según las respuestas del usuario:
   • Zona vision (manual): respuesta a la pregunta 2.
   • Zona audience (manual): respuesta a la pregunta 3, formato lista.
   • Zona scope (manual): vacío con placeholder para que el usuario rellene.
   • Zona roadmap (auto): vacío hasta primer add_uc().
   • Zona stack (auto): respuesta a pregunta 4 + auto-detección complementaria de lockfiles (pubspec.yaml, package.json, pyproject.toml, go.mod).
   • Zona tracking_backend (auto): respuesta a pregunta 5 + path absoluto resuelto.
   • Zona autopilot (auto): refleja contenido de settings.local.json.

2.3 — Crear doc/tracking/ si backend = freeform

Si la pregunta 5 = [a] FreeForm:

1. Handshake con el MCP — llama primero a detect_local_root_path(). La tool devuelve el contrato: requires_absolute_path: true, default_relative_path: "doc/tracking" y la receta exacta para resolver el absoluto del lado cliente. No escribe nada; solo declara las reglas.
2. Resolver al absoluto local — usar PROJECT_ROOT calculado en el Paso 1 (git rev-parse --show-toplevel):

   ABS_TRACKING="$PROJECT_ROOT/doc/tracking"
   

   Crear doc/tracking/ en disco (si no existe) bajo esa ruta.
3. Llamar a la tool MCP set_auth_token con la ruta absoluta:

   set_auth_token(
     api_key="freeform",
     token="",
     backend_type="freeform",
     root_path=ABS_TRACKING  # ¡absoluto, requerido por v5.29!
   )
   

4. Llamar a setup_board(board_name=PROJECT_NAME) para inicializar la estructura.

Defensa en profundidad (v5.33+): aunque por error se llamase a set_auth_token u onboard_project con una ruta relativa, el hook freeform-path-guard.mjs la reescribe automáticamente al absoluto del repo del cliente antes de que la llamada llegue al MCP, y deja traza en .quality/logs/freeform-path-rewrites.jsonl. Aun así, /app-init debe pasar el absoluto explícito — el hook es red de seguridad para clientes externos (claude.ai mobile, integraciones, otros skills), no licencia para descuidar el contrato.

2.4 — Asegurar .claude/settings.local.json

Si no existe o no tiene la sección, escribe (o fusiona, no sobreescribir lo existente):

{
  "specbox": {
    "backend_type": "freeform",
    "freeform_root_absolute": "/Users/.../doc/tracking",
    "autopilot": {
      "level": "equilibrado",
      "image_budget_eur_per_feature": 5
    }
  }
}

2.5 — Output al usuario

Resumen breve:

✅ /app-init completado.
   doc/app/app_prd.md          (6 zonas: 5 manuales + 1 auto)
   doc/app/app_spec.md         (6 zonas: 4 auto + 2 manuales/hybrid)
   doc/tracking/                (FreeForm, path absoluto: /Users/.../doc/tracking)
   .claude/settings.local.json (autopilot: equilibrado)

Próximo paso recomendado:
   /prd "tu primera feature"   — comenzar el flujo de desarrollo

---

Paso 3 — Modo refresh

Cuando los docs ya existen:

1. No tocar zonas manual ni hybrid. Son del usuario.
2. Refrescar zonas auto desde fuentes vivas:
   • stack ← detectar lockfiles + framework files.
   • tracking_backend ← leer .claude/settings.local.json.
   • autopilot ← leer .claude/settings.local.json specbox.autopilot.
   • roadmap ← inferir desde doc/tracking/items.json (FreeForm) o llamar list_us() (Trello/Plane).
3. Usar replace_zone_body(content, zone_id, new_body) del módulo server/app_docs/zones.py para que las sustituciones sean seguras.
4. Antes de escribir, calcular compute_signature del documento previo y nuevo. Si son iguales, no escribir (preserva mtime y evita ruido en git).
5. Output: lista de zonas tocadas o "Sin cambios — todo sincronizado".

---

Paso 4 — Modo upgrade_zones

Para proyectos donde el usuario creó app_prd.md/app_spec.md manualmente sin marcadores. Asistencia interactiva:

1. Lee el documento existente.
2. Detecta secciones por encabezado (## 1. Visión, ## 2. Audiencia, etc.) y propone mapping a manual / auto / hybrid según contenido.
3. Muestra diff con marcadores propuestos.
4. Pide confirmación antes de reescribir.
5. Backup del original en .quality/edits_backup/{date}_{filename} antes de aplicar.

---

Paso 5 — Validación final

Tras cualquier modo, valida los documentos resultantes:

from server.app_docs.zones import parse_document, validate_document, ZoneKind
doc = parse_document("doc/app/app_prd.md")
issues = validate_document(doc, required_zones={
    "vision": ZoneKind.MANUAL,
    "audience": ZoneKind.MANUAL,
    "scope": ZoneKind.MANUAL,
    "success_metrics": ZoneKind.HYBRID,
    "roadmap": ZoneKind.AUTO,
    "stakeholders": ZoneKind.MANUAL,
})
errors = [i for i in issues if i.severity == "error"]

Si hay errores → muestra al usuario y aborta sin commitear cambios.

---

Paso 6 — Auto-commit (opcional, no destructivo)

Si el usuario está en una rama feature/* y git status está limpio antes de la operación, el skill puede proponer un commit:

He generado los documentos canónicos. ¿Crear commit ahora?
  [s] Sí — `chore: init app_prd.md + app_spec.md (v5.29.0)`
  [n] No — los dejo sin commitear

No crear commit automáticamente sin confirmación del usuario.

---

Reglas inviolables

• Nunca borrar contenido de zonas manual.
• Nunca sobrescribir zona hybrid antes del marcador <!-- engine-entries-below -->.
• Si una operación de refresh fallaría por documento mal formado (errores del parser), abortar limpiamente y mostrar los errores — nunca dejar el documento en estado inconsistente.
• Path FreeForm SIEMPRE absoluto (validado por FreeformBackend y set_auth_token desde v5.29.0 PR-1).

---

Ejemplo de invocación end-to-end

$ /app-init

🔍 Detectando estado del proyecto...
   PROJECT_ROOT = /Users/me/myproject
   doc/app/        no existe
   doc/tracking/   no existe
   settings.local  no existe
   → modo: init (proyecto nuevo)

📝 5 preguntas mínimas:
   1. Nombre: myproject
   2. Problema: "Plataforma para gestionar X..."
   3. Audiencia: PMs, devs senior
   4. Stack: React 19
   5. Backend tracking: [a] FreeForm  ← auto-confirmado por equilibrado

⚙️  Generando...
   doc/app/app_prd.md         escrito (6 zonas)
   doc/app/app_spec.md        escrito (6 zonas)
   doc/tracking/              inicializado (board: myproject)
   .claude/settings.local.json escrito (autopilot: equilibrado)

✅ Listo. Próximo: /prd "tu primera feature"