storybloq

El problema

Los asistentes de programación con IA no tienen estado. Cada nueva sesión empieza de cero. El modelo no sabe qué se construyó ayer, qué está roto, qué decisiones se tomaron ni en qué trabajar a continuación. Los desarrolladores lo compensan con archivos CLAUDE.md y notas dispersas, pero no existe una estructura estándar, ni continuidad entre sesiones, ni herramientas.

El coste real no es el tiempo de preparación desperdiciado. Son los errores repetidos, las decisiones de diseño que se vuelven a discutir, el contexto imaginado y un trabajo lineal en lugar de un trabajo que se acumula.

Related MCP server: AI Conversation Logger

The idea

Cada proyecto recibe un directorio .story/ con archivos JSON y markdown. Los tickets, las incidencias, las fases del roadmap, los traspasos de sesión y las lecciones aprendidas viven ahí, bajo el control de git, legibles para cualquier IA.

• CLI: storybloq - inspeccion y modifica .story/ desde la terminal.

• Servidor MCP: herramientas estructuradas que Claude Code y Codex pueden llamar directamente, con otras cinco cuando el Bus local está habilitado. Sin lanzamiento de subprocesos.

• Skill: /story en Claude Code o $story en Codex carga el estado del proyecto al inicio de cada sesión.

• App para Mac: panel lateral nativo que observa .story/ y se actualiza en vivo mientras tu cliente de IA trabaja (producto de pago, gratis para usuarios en App Store).

Instalación

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

Requiere Node.js 20+ y al menos un cliente de IA: Claude Code o Codex CLI 0.130.0+. El paquete vive en npm como @storybloq/storybloq; han sido publicadas en este repositorio mediante tags en github.com/Storybloq/storybloq/releases.

setup --client all instala el skill de Storybloq para Claude y Codex, registra este paquete como servidor MCP y configura los hooks de cliente. Re-ejecutarlo es seguro. Codex informa de los hooks instalados con confianza unknown; abre /hooks en Codex para revisarlos y confirmar que confías en ellos. setup-skill se mantiene como alias de compatibilidad para una instalación solo con Claude.

Actualización

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

Los mismos dos comandos que en una instalación nueva: @latest trae la versión más alta, y volver a ejecutar el setup actualiza los archivos del skill de Storybloq, vuelve a registrar el servidor MCP y barrese cualquier entrada de hook residual de instalaciones anteriores.

Normalmente verás un banner de una línea en la próxima invocación de storybloq cuando haya una versión nueva en npm:

storybloq v1.2.0 is available (you have v1.1.6).
Update: npm install -g @storybloq/storybloq@latest

La CLI también actualiza en silencio el directorio del skill y migra cualquier entrada huérfana de hooks (por ejemplo, las de @anthropologies/claudestory, anterior a su renombrado) en la primera ejecución tras una actualización; no hace falta limpiar nada manualmente.

Instalación alternativa a través del sistema de plugins de Claude Code: consulta Storybloq/plugin-archive (vía heredada; storybloq setup --client all es la instalación recomendada).

Preparar un proyecto

cd your-project
storybloq init --name "your-project"

Para proyectos con varios repos todos, ver Federación más abajo.

Eso crea la estructura:

.story/
├── config.json         project config + recipe overrides
├── roadmap.json        phase ordering + metadata
├── tickets/            T-001.json, T-002.json, ...
├── issues/             ISS-001.json, ISS-002.json, ...
├── notes/              N-001.json, N-002.json, ...
├── lessons/            L-001.json, ...
├── handovers/          YYYY-MM-DD-<slug>.md
└── snapshots/          state snapshots (gitignored)

Haz commit de todo excepto .story/snapshots/.

Uso diario

Dentro de Claude Code o Codex:

• /story en Claude Code o $story en Codex - carga el estado del proyecto, lee el último traspaso, muestra los tickets y los problemas abiertos, lista el trabajo bloqueado y resume el resumen de changes últimos. Cuando el cliente puede ejecutar agentes en segundo plano y el backlog accionable es grande, también sugiere de forma proactiva el estilo de trabajo "orchestrate" (una recomendación y, siempre, bajo un opt-in explícito).

• /story auto T-001 T-002 ISS-013 / $story auto T-001 T-002 ISS-013 - el autónomo delimitado a esos elementos. Lleva un ticket desde plan → revisión del plan → implementación → pruebas → revisión de código → hasta el fin, con una entrega en cada hito.

• /story review T-001 / $story review T-001 - ejecuta la revisión de los lentes múltiples (ver Storybloq/lenses) comparada contra el diff de un ticket.

• /story orchestrate / $story orchestrate - mueve un backlog multi-repo (o un repositorio único grande) cuando el cliente expone herramientas exactas de flujo de trabajo/subagentes. Codex usa multi_agent_v1.spawn_agent, su identificador normalizado multi_agent_v1__spawn_agent o una herramienta spawn_agent exacta. El comando storybloq dispatch respaldado por Claude Agent View se despliega; no se despliega un backend de Codex gestionado por producto.

• /story triage / $story triage - triaje de solo lectura del backlog de problemas abiertos: verifica cada hallazgo contra el HEAD actual, marca como ya corregidos los problemas duplicados, agrupa los que comparten una misma causa concedida y recomienda un plan de tickets priorizado. No altera ningún item ni ticket.

• /story bus / $story bus - consulta un endpoint local del Bus vinculado a la tarea para poder intercambiar hallazgos de asesoramiento entre implementador y revisor independiente, sin copiar y pegar.

• /story handover / $story handover - escribe un traspaso de sesión con las decisiones, los bloqueadores y los siguientes pasos.

Ambos clientes admiten carga de contexto, autónomo, MCP y hooks de compactación/estado. Codex Desktop puede abrir la tarea propietaria de una sesión autónoma y hacer llegar una respuesta, mientras que Codex CLI recurre de forma segura a un cambio manual de tarea. La revisión de código predeterminada es un tope de aterrizaje de 12 rondas (ampliado hacia arriba según el riesgo del ticket): los hallazgos críticos no resueltos y los rechazos siguen bloqueando, mientras que los hallazgos no bloqueantes se convierten en problemas de seguimiento al llegar al tope. Coloca recipeOverrides.stages.CODE_REVIEW.maxReviewRounds en 0 para desactivar el tope explícitamente.

recipeOverrides.compactThreshold acepta medium, high (default) o critical. El valor selecciona tanto los límites de presión como el gatillo de rotación: medium usa límites más bajos y rota con presión media, mientras que critical usa límites más altos y espera la presión crítica. En un límite COMPLETE con el estado limpio, la presión en el umbral termina la sesión acotada mediante HANDOVER porque Storybloq no puede invocar un comando de compactación del cliente por sí solo. Cuando el cliente mismo compacta, los hooks PreCompact y SessionStart preservan la misma sesión; la presión se resetea solo después de que SessionStart confirma source: compact.

Fuera del cliente de IA, ese mismo estado está a solo una invocación de storybloq.

Reactivación automática al superar el límite de uso

Las sesiones de Claude Code se detienen al alcanzar el límite ("Has alcanzado tu límite de uso"), y el trabajo autónomo que se ejecuta durmiendo muere silenciosamente con ellas. Storybloq detecta la parada mediante el hook StopFailure de Claude Code, extrae la hora de restablecimiento del acta de sesión, registra la parada en un registro global (~/.claude/storybloq/limit-ledger.json) y reanuda que la sesión cuando el límite se restablece. Activado por defecto una vez que los hooks están instalados.

• Sesiones autónomas Mientras se reanudan en el mismo carril de recuperación que la compactación y se despiertan sin cabeza a través de la máquina de estado completa -- rebinde de propiedad, validación del HEAD de git y mapeo de recuperación; todo se aplica, así que despertar después de que el workspace cambió se valida, no se vuelve a reproducir ciegamente. Las sesiones detenidas a mitad de FINALIZE nunca se reanuden automáticamente (la reproducción de commits no se demuestra segura); recibirás una notificación con pasos de recuperación manual en su lugar.

• Sesiones normales reciben una notificación de autoridad al restablecerse con el comando exacto claude --resume. La opción por proyecto (limitResume.plainMode: "headless") las despierta headlessly.

• La postura de permisos nunca se escala. Una sesión que se ejecutó con --dangerously-skip-permissions solo se despierta con esa flag si el proyecto explícitamente participa (limitResume.inheritBypass: true); en caso contrario, se notifica.

La ola la maneja un proceso desatendido transitorio, no un demonio: hace encuesta al registro cada 30 segundos, los procesos que están listos (límite de intentos por mar, espaciado y límites de concurrencia) y se omite cuando no hay nada pendiente. Sobrevive al sueño de la laptop pero no al reinicio ni a la sesión cerrada -- después de un reinicio, la siguiente ejecución de storybloq o de un hook en cualquier proyecto lo vuelve a crear, por lo que esperas de escala semanal se recuperan con tu próxima actividad. Ese es el coste de "no daemon".

Inspecciona y gestiona la inicialización con storybloq limit-status (--cancel <key> elimina un reanudamiento pendiente, --requeue <key> reintenta un registro aparcado). Para desactivarla globalmente, usa {"limitResume": {"enabled": false}} en ~/.claude/storybloq/config.json, o por proyecto mediante limitResumeen.story/config.json(tambiénmaxAttempts, staggerMs, maxConcurrent, notify`, y más) .

Modelo ante mal: el enfoque de detección y reéchado está inspirado en unsnooze (MIT), que fue pionero en la detección de límites basada en transcripciones y el parser de tiempos de reset para sesiones de tmux. La versión de Storybloq elimina la capa de tmux y usa la superficie de hooks documentada, y reanuda las sesiones del autónomo con su propia máquina de estados en lugar de un envío de pulsaciones.

Bus de Storybloq

El Bus de Storybloq es un protocolo local de coordinación opcional parauna tarea de implementación y una de revisión. El estado en ejecución vive en .story/bus/ que está bajo .gitignore; los hallazgos confirmados todavía se convierten en issues canónicos of Storybloq con procedencia de fuente persistente antes de enviarse como notificaciones de issue.

storybloq bus init
storybloq bus join implementer --client codex
storybloq bus join reviewer --client claude
storybloq bus hooks enable --client codex
storybloq bus hooks enable --client claude

El runtime del Bus es local y en gitignore, así que ejecuta storybloq bus init una vez en cada checkout que vaya a participar. status y `" doctor missionan un checkout nuevo como habilitado pero no inicializado; ese estado de inactividad saludable no bloquea los commits ni el FINALIZE autónomo. El resto de comandos del Bus y las herramientas MCP nunca inician el runtime implícitamente. La inicialización rechaza symlinks en ignore files y patrones de negación porque no se puede probar con seuridad que Git excluirá el runtime completo de otra manera.

El protocolo en primer plano incluye envío, sondeo, confirmación de recepción, estado de hilo, status, doctor, export y comprobaciones de envío. Los mensajes están encadenados por hash, son idempotentes, acotados, vinculados a task, checkeados de secretos y introduced en buzones de recipiente con recuperación ante crash. Los mensajes críticos exigen una issue crítica no resuelta correspondiente, por defecto. El texto de Bus siempre es una recomendación entre agentes pares: nunca concede la aprobación de propietario ni autorizado merge, push, firma, despliegue, permisos, gasto ni acciones destructivas.

La V1 no incluye daemon, ni proceso de spawn, ni reanudación headless, ni wakeups automático de línea, como vías de entrega del Bus. Los hooks naturales de inicio/fin de sesión y el sondeo explícito son las vías de envío. Codex Desktop sigue siendo un no despertable. (La reanudación automática de límite de uso, anterior, es excepción acotada fuera del Bus: su despertador transitorio se recupera de sesiones pause, no es un camino de entrega de mensaje).

Federación

La federación coordina el trabajo de los agentes de IA en múltiples repos. Un proyecto se convierte en el orquestador. Declara qué repos (nodos) forman parte del sistema, cómo dependen entre sí y cómo se comunican en tiempo de ejecución. Cada nodo mantiene su propio .story/ con sus propios tickets, incidencias y traspasos. El orquestador lee a través de todos ellos.

# Create an orchestrator
storybloq init --type orchestrator --name "my-platform"

# Register nodes
storybloq node add api --path ../api --stack typescript --role "REST backend"
storybloq node add web --path ../web --stack nextjs --depends-on api
storybloq node add sdk --path ../sdk --stack typescript

Tres tipos de relación conectan nodos:

• dependsOn en la configuración del nodo: aristas de orden de compilación. La aplicación web depende de la API.

• links en la configuración del nodo: integración en tiempo de ejecución. La aplicación web llama a la API por HTTP.

• crossNodeBlockedBy en tickets: un ticket en un repo está bloqueado hasta que un ticket en otro repo esté completo. Ejemplo: "crossNodeBlockedBy": ["api:T-012"].

Desde el directorio del orquestador:

storybloq status              # aggregated view across all nodes
storybloq recommend           # federation-aware suggestions (bottlenecks, stale nodes, blockers)
storybloq ticket list --node api   # list tickets in the api node without cd-ing

El motor de recomendaciones genera sugerencias específicas de federación: nodos que bloquean trabajo posterior, nodos cuello de botella de los que dependen muchos otros, nodos sin traspaso en dos semanas. Los tickets con referencias crossNodeBlockedBy nunca aparecen en las recomendaciones hasta que el ticket bloqueante esté completo.

Referencia de CLI

Todos los comandos aceptan --format json|md (por defecto md). Canaliza el JSON a través de jq para scripting, lee la variante markdown directamente.

Proyecto

Fases

Tickets

Incidencias

Notas y lecciones

Traspasos, bloqueadores, snapshots

Storybloq Bus (opt-in)

Federación (proyectos orquestadores)

Equipo (proyectos en modo equipo)

Consulta modo equipo para conocer el modelo de fusión sobre el que operan estos comandos.

Referencia del servidor MCP

Regístralo con Claude Code o Codex (lo hace automáticamente la configuración):

claude mcp add storybloq -s user -- storybloq --mcp
codex mcp add storybloq --env STORYBLOQ_CLIENT=codex -- storybloq --mcp

El servidor importa directamente los mismos módulos TypeScript que la CLI, por lo que no hay sobrecarga de subprocesos. Descubre automáticamente la raíz del proyecto ascendiendo desde el directorio de trabajo hasta el .story/ padre más cercano.

Las herramientas base se agrupan por responsabilidad. Los proyectos con bus habilitado registran cinco herramientas adicionales al iniciar el proceso MCP; reinicia los clientes conectados después de storybloq bus init.

Lectura (sin efectos secundarios)

storybloq_status · storybloq_phase_list · storybloq_phase_current · storybloq_phase_tickets · storybloq_ticket_list · storybloq_ticket_get · storybloq_ticket_meta_get · storybloq_ticket_next · storybloq_ticket_blocked · storybloq_issue_list · storybloq_issue_get · storybloq_issue_meta_get · storybloq_note_list · storybloq_note_get · storybloq_lesson_list · storybloq_lesson_get · storybloq_lesson_digest · storybloq_handover_list · storybloq_handover_latest · storybloq_handover_get · storybloq_blocker_list · storybloq_validate · storybloq_recap · storybloq_recommend · storybloq_export · storybloq_selftest

Escritura (modifica .story/)

storybloq_snapshot · storybloq_handover_create · storybloq_ticket_create · storybloq_ticket_update · storybloq_ticket_meta_set · storybloq_ticket_meta_unset · storybloq_issue_create · storybloq_issue_update · storybloq_issue_meta_set · storybloq_issue_meta_unset · storybloq_note_create · storybloq_note_update · storybloq_lesson_create · storybloq_lesson_update · storybloq_lesson_reinforce · storybloq_phase_create

Modo autónomo + revisión + observabilidad

storybloq_autonomous_guide impulsa la máquina de estados autónoma (PICK_TICKET -> PLAN -> PLAN_REVIEW -> WRITE_TESTS -> IMPLEMENT -> TEST -> CODE_REVIEW -> FINALIZE -> COMPLETE).

storybloq_review_lenses_prepare · storybloq_review_lenses_judge · storybloq_review_lenses_synthesize orquestan el bucle de revisión multi-lente (requiere @storybloq/lenses).

storybloq_session_report · storybloq_register_subprocess · storybloq_unregister_subprocess exponen el estado de salud de la sesión a la app de Mac.

Storybloq Bus (activado por funcionalidad)

storybloq_bus_send · storybloq_bus_poll · storybloq_bus_ack · storybloq_bus_thread_get · storybloq_bus_thread_update

Cada llamada requiere un ID de endpoint estable y el ID de tarea de cliente validado actual. Las salidas de sondeo y de hilo marcan el contenido de los pares como autoridad consultiva. storybloq_bus_poll y storybloq_bus_thread_get son de solo lectura con respecto al estado canónico del proyecto rastreado; el sondeo puede conciliar los metadatos de ejecución de .story/bus/ ignorados por git. Las otras tres conservan las aprobaciones normales de escritura de MCP.

Federación (proyectos de orquestador)

storybloq_node_init inicializa .story/ en un repositorio de nodo desde el contexto del orquestador.

storybloq_node_add · storybloq_node_list · storybloq_node_update gestionan el registro de nodos del orquestador.

Hooks

PreCompact (preparación de la compactación, configurado por setup)

Ejecuta storybloq session compact-prepare antes de la compactación de contexto para que las instantáneas y las migas de reanudación se mantengan actualizadas donde el cliente admita hooks PreCompact. La configuración de Codex usa storybloq session compact-prepare --client codex con un comparador manual|auto para que un hook de Codex no pueda compactar una sesión propiedad de Claude; la configuración de Claude Code deja el comparador vacío.

{
  "hooks": {
    "PreCompact": [{
      "matcher": "manual|auto",
      "hooks": [{ "type": "command", "command": "storybloq session compact-prepare" }]
    }]
  }
}

Omítelo con storybloq setup --client all --skip-hooks.

SessionStart (inyección de prompt de reanudación)

Inyecta un prompt de reanudación consciente de la compactación. La configuración de Codex usa el mismo comando con --codex-hook-json y el comparador startup|resume|clear|compact; su JSON de hook también lleva el ID de tarea actual para que la recuperación COMPACT de la misma tarea pueda continuar sin un token Resume copiado y pegado. La configuración no puede verificar la confianza del hook, así que revisa /hooks en Codex después de la instalación.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "compact",
      "hooks": [{ "type": "command", "command": "storybloq session resume-prompt" }]
    }]
  }
}

storybloq bus hooks enable es una activación opcional separada del proyecto. Añade metadatos de endpoint y recuentos pendientes a SessionStart, y permite que el hook Stop síncrono se bloquee una vez por cada nuevo cursor de buzón. Los bytes de carga útil de los pares nunca aparecen en la salida del hook. La estructura de hook compartida de Claude se actualiza una vez y permanece protegida por la política local del proyecto; Codex usa storybloq hook-status --client codex.

Stop (estado en vivo para la app de Mac)

Ejecuta storybloq hook-status al final de cada turno, actualizando el .story/status.json ignorado por git que la app de Mac y el acompañante de iOS leen para conocer el estado en vivo de la sesión.

La escritura está controlada por contenido: cuando la carga útil es idéntica a lo que ya dice el archivo (ignorando la marca de tiempo de observación y qué escritor la produjo), no se escribe nada y se dejan intactos las marcas de tiempo y el inodo del archivo. Por lo tanto, los turnos inactivos dejan el árbol de trabajo completamente intacto. Los cambios reales -- una transición de flujo de trabajo, una nueva llamada MCP, un cambio de salud o de concesión -- siguen escribiendo de inmediato.

Los proyectos cuyo arnés de pruebas trate cualquier escritura durante una ejecución como un fallo pueden desactivar por completo el escritor de fin de turno:

{ "statusWriter": { "stopHook": false } }

en .story/config.json. El hook entonces no realiza ningún trabajo de estado: ni escaneo de sesión, ni construcción de carga útil, ni autocuración de gitignore, ni escritura. Las sesiones autónomas siguen actualizando el estado en sus propias transiciones MCP, por lo que la app de Mac aún muestra el estado en vivo mientras una sesión se está ejecutando -- solo deja de actualizarse entre turnos de trabajo interactivo normal. El indicador está activado por defecto, y cualquier configuración ilegible o malformada lo deja activado.

StopFailure (detección de límite de uso)

Ejecuta storybloq session limit-stop cuando una sesión de Claude Code se detiene por un límite de uso, registrando la detención para la reanudación automática (consulta Reanudación automática por límite de uso más arriba). La configuración también añade un segundo grupo de comparadores de SessionStart ("resume") que lleva el mismo comando session resume-prompt para que la reapertura manual de una sesión detenida por límite reciba orientación consciente del límite. Ambas entradas son solo de Claude, se reconcilian en cada actualización y se eliminan automáticamente cuando se activa el interruptor global de apagado.

{
  "hooks": {
    "StopFailure": [{
      "matcher": "rate_limit",
      "hooks": [{ "type": "command", "command": "storybloq session limit-stop" }]
    }]
  }
}

Uso de la biblioteca

import { loadProject } from "@storybloq/storybloq";

const { state, warnings } = await loadProject("/path/to/project");
console.log(state.tickets.length);           // all tickets
console.log(state.phaseTickets("p1"));       // leaf tickets in phase p1
console.log(state.umbrellaChildren("T-014")); // children of an umbrella

Las definiciones de tipos completas se incluyen con el paquete (exports.types).

Ejemplos de formato de archivo

Ticket (.story/tickets/T-001.json):

{
  "id": "T-001",
  "title": "Add search to sidebar",
  "type": "task",
  "status": "inprogress",
  "phase": "p2",
  "order": 10,
  "description": "Fuzzy match over ticket title + description.",
  "createdDate": "2026-04-12",
  "completedDate": null,
  "blockedBy": [],
  "parentTicket": null,
  "crossNodeBlockedBy": []
}

Issue (.story/issues/ISS-001.json):

{
  "id": "ISS-001",
  "title": "Drag handle hit target too small on trackpad",
  "status": "open",
  "severity": "medium",
  "components": ["mac-app"],
  "impact": "Dragging tickets on trackpad requires multiple tries.",
  "location": ["macos/Views/KanbanCard.swift:42"],
  "sourceRefs": [{
    "path": "macos/Views/KanbanCard.swift",
    "startLine": 42,
    "revision": "5ac37f94f7023b18f72d8e3fcf43dd64f54c11d7",
    "contentHash": "f5b1b1b65dca3d9d86adf7c5d49082aa4dc09e7903ab46ce50e8cc6b4812e4cf",
    "reviewId": "review-2026-04-15"
  }],
  "dedupeKey": "review-2026-04-15:finding-3",
  "createdBy": "external-reviewer",
  "discoveredDate": "2026-04-15",
  "resolvedDate": null,
  "relatedTickets": []
}

Cada registro es su propio archivo. Los IDs son secuenciales dentro del tipo (T-001, T-002, ...). Las relaciones son de propietario canónico único: el campo blockedBy de un ticket apunta a los tickets bloqueantes, y la inversa (quién me bloquea) se obtiene mediante escaneo.

Las operaciones de creación se pueden ejecutar en paralelo de forma segura. La asignación de ID y la escritura de creación ocurren juntas bajo un bloqueo de proyecto, por lo que los creadores concurrentes se serializan y cada uno recibe un ID secuencial distinto. Una creación nunca puede sobrescribir silenciosamente un registro existente; bajo una contención simultánea intensa, un creador falla ruidosamente con un error en lugar de colisionar.

Los sourceRefs de Issue conservan la evidencia de revisión independientemente de las cadenas de visualización mutables path:line. Storybloq solo aplica hash al rango de líneas referenciado normalizado y nunca almacena extractos del código fuente. Una revisión proporcionada se resuelve a un commit de Git; de lo contrario, Storybloq captura el rango del árbol de trabajo y registra HEAD solo cuando esos bytes coinciden. storybloq validate informa de un error cuando no se puede resolver la evidencia original, de una advertencia cuando la evidencia histórica válida se movió o cambió en HEAD, y de ningún hallazgo cuando todavía coincide.

Usa storybloq validate --integrity-only cuando un config.json o roadmap.json dañado impida la carga normal. Esta comprobación previa de solo lectura escanea todos los archivos .story/**/*.json en una sola pasada, informa de las posiciones del analizador cuando están disponibles y separa los fallos críticos de singleton de los fallos omitibles de elementos y archivos auxiliares. Nunca reescribe archivos dañados.

Los hallazgos confirmados de revisiones manuales o externas deben registrarse directamente como issues abiertos. Busca primero, pasa la atribución del revisor en createdBy, adjunta el ID de revisión y la revisión mediante sourceRefs, y usa una dedupeKey estable como <review-id>:<finding-id> para que los reintentos sean idempotentes. Mantén las preguntas de diseño inciertas como notas o preguntas del propietario; el agente implementador es el dueño del estado y la resolución del issue.

Los registros de ticket e issue conservan los campos JSON desconocidos. Usa storybloq ticket meta y storybloq issue meta para leer o modificar esos campos personalizados de paso directo sin tocar los campos centrales de Storybloq. Los valores son JSON, y las rutas de puntos direccionan objetos anidados, por ejemplo storybloq ticket meta set T-001 integration.linear '"ABC-123"'.

La profundidad de la revisión autónoma del plan se puede establecer por ticket con los metadatos reviewRisk (low, medium o high). Por ejemplo, storybloq ticket meta set T-001 reviewRisk '"high"' requiere al menos tres rondas de revisión del plan. Los metadatos heredados risk también se reconocen, pero reviewRisk es la clave canónica. Este ajuste solo cambia la profundidad de la revisión; nunca se salta una fase de revisión.

Flujo de trabajo de ejemplo

# Initialize
storybloq init --name "my-app"

# Add the first phase
storybloq phase create --id bootstrap --name "Bootstrap" --label "PHASE 1" \
  --description "Get the app running end-to-end"

# Add a ticket
storybloq ticket create --title "Scaffold Next.js" --type task --phase bootstrap

# Start Claude Code and type /story, or invoke $story in Codex, then work on it
# (or go autonomous: /story auto T-001 / $story auto T-001)

# At the end of a session, commit your changes including .story/
git add .
git commit -m "T-001: scaffold Next.js"

# Session ends. Next session starts with /story or $story and picks up with full context.

Modo equipo

.story/ es JSON plano rastreado por git, por lo que un equipo que lo comparte se encuentra con los mismos dos problemas que cualquier estado compartido: ediciones concurrentes del mismo registro y creación concurrente de nuevos registros. El modo equipo aborda ambos.

storybloq team init     # once per project; commit the result
storybloq team setup    # once per clone, by every teammate

team init configura el proyecto para el trabajo en equipo (versión de esquema, caducidad de reclamaciones, asignador de ids, funciones de cliente requeridas) y ejecuta la configuración para tu propio clon. team setup instala el controlador de fusión de git storybloq-json en la configuración de git local del clon y escribe .story/.gitattributes para que los archivos JSON de .story/ pasen por él. La configuración de git es por clon, por lo que cada compañero de equipo ejecuta la configuración una vez en cada checkout. storybloq team doctor comprueba toda la configuración (ids de visualización duplicados, conflictos sin resolver, reclamaciones caducadas, controlador de fusión instalado) y sale con código distinto de cero en caso de errores con --ci; consulta Team CI a continuación para el flujo de trabajo de la puerta de fusión.

Ediciones concurrentes: el modelo de fusión

Cuando git fusiona dos ramas que ambas han tocado el mismo registro de .story/, el controlador de fusión ejecuta una fusión estructurada de tres vías por registro en lugar de una fusión de texto por líneas. Los campos se fusionan de forma independiente: si un compañero cambia el status de un ticket mientras otro edita su description, ambos cambios se aplican. Cuando el mismo campo diverge en ambos lados, el controlador no elige ninguno. Registra la divergencia como un bloque estructurado _conflicts dentro del registro, de modo que el archivo sigue siendo JSON válido sin marcadores de conflicto; git sigue marcando la ruta como en conflicto, así que haz git add del archivo y haz commit para concluir la fusión, y luego resuelve los conflictos registrados a tu ritmo (se mantienen en fusiones posteriores hasta que se resuelven). Un proyecto con _conflicts sin resolver queda bloqueado para escritura hasta que se resuelva cada conflicto:

storybloq conflicts list                     # every item with unresolved conflicts
storybloq conflicts show T-042               # field-level detail: base, ours, theirs
storybloq resolve T-042 --field status --use theirs
storybloq resolve T-042 --field title --value '"Merged title"'
storybloq resolve config                     # config.json merges the same way
storybloq resolve roadmap                    # so does roadmap.json

Creaciones concurrentes: colisiones de ids de visualización

Que dos compañeros creen elementos en ramas paralelas es un modo de fallo distinto. Los nuevos registros se almacenan bajo un nombre de archivo de id canónico aleatorio (por ejemplo t-8f2kq0v3n1xw9d4e.json), por lo que los elementos creados de forma independiente nunca colisionan a nivel de archivo; solo los nombres de archivo secuenciales heredados (ISS-041.json, de proyectos anteriores a los ids canónicos) pueden seguir colisionando en la ruta. Lo que sí puede colisionar es el id de visualización orientado a humanos: ambas ramas calculan localmente el "siguiente número libre" y ambas acuñan T-042. Eso no es un conflicto de fusión, es un duplicado, y tiene su propia herramienta:

storybloq reconcile          # renumber duplicates; the copy already on the protected ref, else the earlier one, keeps the number
storybloq reconcile --ci     # detect only: exit non-zero if duplicates exist, mutate nothing

Los elementos renumerados conservan su antiguo id de visualización en previousDisplayIds, de modo que las referencias existentes al número antiguo siguen resolviéndose.

Elegir un asignador de ids

team init --id-allocator local|git-refs elige cómo se asignan los ids de visualización. La disyuntiva:

Con git-refs, team init también añade remote-ref-reservations a team.requiredFeatures, de modo que los clientes que no declaren esa capacidad se niegan a crear elementos en lugar de asignar localmente contra un equipo git-refs y colisionar. Una advertencia: las versiones actuales de la app de Mac son anteriores a las reservas aunque declaran la capacidad, así que hasta que se publique la actualización del lado de Mac, evita crear elementos desde la app de Mac en equipos git-refs. storybloq team reserve tickets --count 5 reserva un lote de ids por adelantado.

Versión de esquema y clientes antiguos

team init sella schemaVersion: 3 en .story/config.json. Las versiones de la CLI anteriores a 1.5.0 rechazan limpiamente un proyecto con schemaVersion 3, tanto para lecturas como para escrituras, con un mensaje de actualización (Config schemaVersion 3 exceeds max supported 2. Run: npm update -g @storybloq/storybloq). El fallo duro es deliberado: esos clientes no entienden los datos del modo equipo, y en equipos con versiones mixtas antes producían lecturas parciales silenciosas en lugar de un error.

Los repos de equipo creados antes de la barrera llevan schemaVersion: 2. Para actualizar un repo de equipo existente: espera a que cada compañero ejecute una CLI 1.5.0+, y luego establece schemaVersion a 3 manualmente (o vuelve a ejecutar storybloq team init, que realiza la misma actualización). Las builds antiguas de la app de Mac muestran un proyecto con schemaVersion 3 como solo lectura hasta que se actualizan; no se pierde ningún dato.

Actualizar un repo anterior a .story/.gitignore

team init y team setup escriben .story/.gitignore que cubre los archivos locales de la máquina (sessions/, snapshots/, status.json, federation-cache.json, channel-inbox/). Un gitignore no deja de rastrear archivos que ya están rastreados, por lo que un proyecto que adoptó storybloq antes de que existiera el gitignore puede tener ya archivos efímeros en el historial de git. Compruébalo una vez y deja de rastrearlos:

git ls-files .story/ | grep -E 'sessions/|snapshots/|status\.json|federation-cache\.json|channel-inbox/'
git rm -r --cached --ignore-unmatch .story/sessions .story/snapshots .story/status.json .story/federation-cache.json .story/channel-inbox

Haz commit de la eliminación. El estado de la sesión registra rutas absolutas (incluido tu nombre de usuario), por lo que merece la pena hacerlo antes del primer push al repositorio compartido.

Las eliminaciones dejan tombstones

Eliminar un ticket, issue, nota o lección en modo equipo no lo elimina del repo compartido. El archivo permanece, conservando todo su contenido original, más un marcador de ciclo de vida: lifecycle: "deleted", una marca de tiempo deletedAt y deletedBy establecido con el user.email de git de quien elimina. Resolver un conflicto entre eliminación y edición también puede sellar el email de quien resuelve como deletedBy en un tombstone sintetizado. Los tombstones permanecen en el repo hasta que alguien ejecuta storybloq gc --apply (retención predeterminada de 30 días).

La conclusión: eliminar un elemento lo oculta de las vistas normales, pero no elimina el contenido ni tu sello de identidad de los clones de tus compañeros. Ejecuta storybloq gc para previsualizar los tombstones elegibles y luego storybloq gc --apply para purgarlos una vez superen la retención.

Lo que ve tu equipo

El modo equipo comparte el estado a través del repo, por lo que todo lo confirmado bajo .story/ es visible para cualquiera con acceso al repo:

• Tickets, issues, notas y lecciones, incluidos todos los campos de texto libre.

• Handovers: documentos narrativos de sesión, a menudo el registro más detallado de qué ocurrió y por qué.

• Bloques de reclamación en elementos en curso: la identidad git del compañero que reclama (user.email), el nombre de la rama y la marca de tiempo de la reclamación, más un UUID claimedBySession mientras una sesión autónoma trabaja en el elemento.

• Conflictos de fusión sin resolver: después de una fusión divergente, el registro afectado lleva los valores en conflicto de ambos lados (base, ours y theirs) dentro de su bloque _conflicts hasta que alguien lo resuelve. El texto que escribió un compañero pero que se perdió después en el arbitraje permanece visible en el archivo hasta la resolución.

Los archivos locales de la máquina quedan fuera del repo una vez que el gitignore está en su sitio: sessions/ (estado de la sesión autónoma, incluido el events.log de cada sesión), snapshots/, status.json, federation-cache.json y channel-inbox/. Trata el contenido de .story/ confirmado con el mismo cuidado que los mensajes de commit y los comentarios de código; viaja con el repo.

Team CI

Para proyectos en modo equipo, añade validación de CI para detectar displayIds duplicados y referencias obsoletas antes de la fusión. Consulta TEAM_CI.md para un flujo de trabajo de GitHub Actions listo para usar.

Proyectos relacionados

• @storybloq/lenses - servidor MCP y biblioteca de revisión de código multi-lens. 9 revisores especializados se ejecutan en paralelo y devuelven veredictos estructurados; el backend de lentes autónomas de storybloq lo consume directamente.

• Storybloq for Mac - app nativa de macOS que observa .story/ y se actualiza en vivo mientras tu cliente de IA trabaja. Gratuita en la Mac App Store.

Soporte

Envía un correo a shayegh@me.com para cualquier cosa: problemas de configuración, preguntas, solicitudes de funciones o simplemente para contar qué estás construyendo. Los informes de errores también son bienvenidos como GitHub issues.

Contribuciones

Issues y PRs bienvenidos. Para cambios no triviales, abre un issue primero para que podamos alinearnos en la dirección.

Configuración de desarrollo:

git clone https://github.com/Storybloq/storybloq.git
cd storybloq
npm install
npm test
npm run build

Licencia

PolyForm Shield 1.0.0 - una licencia de código fuente disponible y de no competencia (no es código abierto OSI).

Puedes usar storybloq para cualquier propósito, incluidos:

• proyectos personales y de hobby

• proyectos de código abierto

• uso interno en empresas

• software comercial que estés construyendo

No puedes, sin una licencia aparte, usar storybloq para construir un producto que compita con él: reempaquetarlo, revenderlo, alojarlo como servicio gestionado o convertirlo en marca blanca. Para eso, contacta con shayegh@me.com.

Consulta LICENSE para el texto completo y NOTICE para el aviso de copyright requerido que debes propagar si redistribuyes.