storybloq

Проблема

ИИ-ассистенты для кодинга не имеют состояния. Каждая новая сессия начинается с нуля. Модель не знает, что было построено вчера, что сломано, какие решения были приняты и над чем работать дальше. Разработчики компенсируют это файлами CLAUDE.md и разрозненными заметками, но нет ни стандартной структуры, ни непрерывности сессий, ни инструментов.

Настоящая цена — не потраченное время на настройку. Это повторяющиеся ошибки, пересмотренные дизайн-решения, галлюцинированный контекст и линейная работа вместо накопительной.

Related MCP server: AI Conversation Logger

Идея

Каждый проект получает каталог .story/ с JSON и markdown-файлами. Тикеты, задачи, фазы дорожной карты, передача сессий и извлеченные уроки — всё это хранится там, отслеживается git и читается любым ИИ.

• CLI: storybloq — просмотр и изменение .story/ из терминала.

• MCP-сервер: структурированные инструменты, которые Claude Code и Codex могут вызывать напрямую, с пятью дополнительными инструментами при включенном локальном Bus. Без порождения подпроцессов.

• Навык: /story в Claude Code или $story в Codex загружает состояние проекта в начале каждой сессии.

• Mac-приложение: нативная боковая панель, которая следит за .story/ и обновляется в реальном времени, пока ваш ИИ-клиент работает (отдельный продукт, бесплатно в App Store).

Установка

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

Требуется Node.js 20+ и хотя бы один ИИ-клиент: Claude Code или Codex CLI 0.130.0+. Пакет находится на npm по адресу @storybloq/storybloq; релизы помечены в этом репозитории на github.com/Storybloq/storybloq/releases.

setup --client all устанавливает навык Storybloq для Claude и Codex, регистрирует этот пакет как MCP-сервер и настраивает доступные хуки клиента. Повторный запуск безопасен. Codex сообщает об установленных хуках с доверием unknown; откройте /hooks в Codex, чтобы просмотреть и довериться им. setup-skill остаётся псевдонимом совместимости для установки только для Claude.

Обновление

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

Те же две команды, что и при новой установке: @latest загружает последнюю версию, а повторный запуск setup обновляет файлы навыка Storybloq, повторно регистрирует MCP-сервер и удаляет устаревшие записи хуков от предыдущих установок.

Обычно вы увидите однострочный баннер при следующем вызове storybloq, когда на npm появится более новая версия:

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

CLI также незаметно обновляет каталог навыков и переносит устаревшие записи хуков (например, из пакета @anthropologies/claudestory до переименования) при первом запуске после обновления — ручная очистка не требуется.

Альтернативная установка через систему плагинов Claude Code: см. Storybloq/plugin-archive (устаревший путь; рекомендуемая установка — storybloq setup --client all).

Инициализация проекта

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

Для проектов с несколькими репозиториями см. Федерация ниже.

Это создаёт структуру:

.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)

Закоммитьте всё, кроме .story/snapshots/.

Повседневное использование

Внутри Claude Code или Codex:

• /story в Claude Code или $story в Codex — загружает статус проекта, читает последнюю передачу, показывает открытые тикеты и задачи, перечисляет заблокированную работу, обобщает недавние изменения. Когда клиент может запускать фоновые агенты и бэклог действий велик, он также проактивно показывает рабочий стиль orchestrate (рекомендация, по-прежнему ограниченная явным согласием).

• /story auto T-001 T-002 ISS-013 / $story auto T-001 T-002 ISS-013 — автономный режим, ограниченный этими элементами. Проводит тикет через план -> ревью плана -> реализацию -> тесты -> ревью кода -> коммит с передачей на каждом этапе.

• /story review T-001 / $story review T-001 — запускает многолинзовое ревью (см. Storybloq/lenses) для диффа тикета.

• /story orchestrate / $story orchestrate — управляет бэклогом нескольких репозиториев (или большого одного репозитория), когда клиент предоставляет точные вызываемые инструменты workflow/субагентов. Codex использует multi_agent_v1.spawn_agent, его нормализованный идентификатор multi_agent_v1__spawn_agent или точный инструмент spawn_agent. Команда storybloq dispatch на основе Claude Agent View поставляется; управляемый продуктом бэкенд Codex dispatch не поставляется.

• /story triage / $story triage — триаж открытого бэклога задач в режиме только для чтения: проверяет каждое замечание относительно закреплённого текущего HEAD, помечает уже исправленные и дублирующиеся задачи, группирует задачи с одной подтверждённой первопричиной и рекомендует приоритизированный план тикетов. Не изменяет ни задачу, ни тикет.

• /story bus / $story bus — опрашивает локальную конечную точку Bus, привязанную к задаче, чтобы исполнитель и независимый рецензент могли обмениваться рекомендательными замечаниями без копирования и вставки.

• /story handover / $story handover — записывает передачу сессии, фиксируя решения, блокеры и следующие шаги.

Оба клиента поддерживают загрузку контекста, автономный режим, MCP и хуки сжатия/статуса. Codex Desktop может открыть задачу-владельца автономной сессии и передать ей точный ответ владельца; Codex CLI безопасно переключается на ручное переключение задач. Автономное ревью кода по умолчанию имеет лимит в 12 раундов (увеличивается в зависимости от риска тикета): нерешённые критические замечания и отклонения по-прежнему блокируют, а некритичные замечания становятся последующими задачами при достижении лимита. Установите recipeOverrides.stages.CODE_REVIEW.maxReviewRounds в 0, чтобы явно отключить лимит.

recipeOverrides.compactThreshold принимает medium, high (по умолчанию) или critical. Значение выбирает как пределы давления, так и триггер ротации: medium использует более низкие пределы и ротацию при среднем давлении, а critical использует более высокие пределы и ждёт критического давления. На чистой границе COMPLETE пороговое давление завершает ограниченную сессию через HANDOVER, потому что Storybloq не может вызвать команду сжатия клиента. Когда клиент сам выполняет сжатие, хуки PreCompact и SessionStart сохраняют ту же сессию; давление сбрасывается только после того, как SessionStart подтвердит source: compact.

Вне ИИ-клиента то же состояние доступно одним вызовом storybloq.

Автопродолжение при лимите использования

Сессии Claude Code останавливаются при достижении лимита использования («Вы достигли лимита использования»), и ночная автономная работа молча умирает вместе с ними. Storybloq обнаруживает остановку через хук StopFailure Claude Code, извлекает время сброса из транскрипта сессии, записывает остановку в глобальный реестр (~/.claude/storybloq/limit-ledger.json) и возобновляет сессию, когда лимит сбрасывается. Включено по умолчанию после установки хуков.

• Автономные сессии помещаются на ту же полосу восстановления, что и сжатие, и пробуждаются безголово через полный конечный автомат — повторная привязка владельца, проверка git-HEAD и сопоставление восстановления применяются, поэтому пробуждение после изменения рабочего пространства проверяется, а не слепо воспроизводится. Сессии, остановленные на середине FINALIZE, никогда не возобновляются автоматически (повторное воспроизведение коммита не доказано безопасным); вместо этого вы получаете уведомление с шагами ручного восстановления.

• Обычные сессии получают уведомление на рабочем столе при сбросе с точной командой claude --resume. Включение на уровне проекта (limitResume.plainMode: "headless") вместо этого пробуждает их безголово.

• Права доступа никогда не повышаются. Сессия, запущенная с --dangerously-skip-permissions, пробуждается с этим флагом только в том случае, если проект явно соглашается (limitResume.inheritBypass: true); в противном случае она уведомляет.

Пробуждение выполняется временным отсоединённым процессом-пробуждателем, а не демоном: он опрашивает реестр каждые 30 секунд, возобновляет то, что должно быть возобновлено (с ограничением попыток, с разнесением по времени, с ограничением параллелизма), и завершается, когда ничего не ожидает. Он переживает сон ноутбука, но не перезагрузку или выход из системы — после перезагрузки следующий вызов storybloq или срабатывание хука в любом проекте перезапускает его, так что ожидание в недельном масштабе восстанавливается при вашей следующей активности. Это компромисс — цена за «без демона».

Просматривайте и управляйте очередью с помощью storybloq limit-status (--cancel <key> уничтожает ожидающее автопродолжение, --requeue <key> повторяет отложенную запись). Отключите глобально с помощью {"limitResume": {"enabled": false}} в ~/.claude/storybloq/config.json или на уровне проекта через limitResume в .story/config.json (также maxAttempts, staggerMs, maxConcurrent, notify и другие).

Предшествующая работа: подход обнаружения и повторного анализа смоделирован на основе unsnooze (MIT), который первым применил обнаружение лимита на основе транскрипта и анализ времени сброса для сессий, размещённых в tmux. Версия Storybloq отбрасывает слой tmux в пользу документированной поверхности хуков и возобновляет автономные сессии через собственный конечный автомат, а не через нажатие клавиши.

Storybloq Bus

Storybloq Bus — это опциональный локальный протокол координации для одной задачи исполнителя и одной задачи рецензента. Состояние выполнения хранится в игнорируемом git каталоге .story/bus/; подтверждённые замечания по-прежнему становятся каноническими задачами Storybloq с долговечным происхождением источника, прежде чем они будут отправлены как уведомления о задачах.

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

Среда выполнения Bus локальна и игнорируется git, поэтому запустите storybloq bus init один раз в каждом клоне, который будет участвовать. Status и doctor сообщают о свежем клоне как о включённом, но не инициализированном; это здоровое неактивное состояние не блокирует коммиты или автономный FINALIZE. Другие команды Bus и MCP-инструменты никогда не инициализируют среду выполнения неявно. Инициализация отклоняет симлинкованные файлы игнорирования и шаблоны отрицания, потому что она не может безопасно доказать, что Git исключит полную среду выполнения в противном случае.

Протокол переднего плана включает отправку, опрос, подтверждение, состояние потока, статус, doctor, экспорт и проверки ship. Сообщения хэш-связаны, идемпотентны, ограничены, привязаны к задаче, проверяются на секреты и доставляются через почтовые ящики получателей, восстанавливаемые после сбоев. Критические сообщения по умолчанию требуют соответствующей нерешённой критической задачи. Текст Bus всегда является советом агента-коллеги: он никогда не даёт одобрения владельца и не авторизует слияние, push, подпись, развёртывание, учётные данные, расходы или деструктивные действия.

V1 не включает демон, порождение процессов, безголовое возобновление или автоматическое пробуждение в офлайне как пути доставки Bus. Естественные хуки SessionStart/Stop и явный опрос являются путями доставки. Codex Desktop остаётся непробуждаемым. (Автопродолжение при лимите использования, описанное выше, является ограниченным исключением вне Bus: его временный пробуждатель восстанавливает сессии, остановленные лимитом, и не является путём доставки сообщений.)

Федерация

Federation координирует работу AI-агентов в нескольких репозиториях. Один проект становится оркестратором. Он объявляет, какие репозитории (узлы) входят в систему, как они зависят друг от друга и как взаимодействуют во время выполнения. Каждый узел хранит собственный .story/ со своими тикетами, задачами и передачами. Оркестратор читает их все.

# 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

Три типа связей соединяют узлы:

• dependsOn в конфигурации узла: рёбра порядка сборки. Веб-приложение зависит от API.

• links в конфигурации узла: интеграция во время выполнения. Веб-приложение вызывает API по HTTP.

• crossNodeBlockedBy в тикетах: тикет в одном репозитории заблокирован, пока не завершён тикет в другом. Пример: "crossNodeBlockedBy": ["api:T-012"].

Из каталога оркестратора:

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

Механизм рекомендаций генерирует предложения, специфичные для федерации: узлы, блокирующие нижестоящую работу, узлы-узкие места, от которых зависят многие другие, узлы без передачи за две недели. Тикеты со ссылками crossNodeBlockedBy никогда не появляются в рекомендациях, пока блокирующий тикет не завершён.

Справочник CLI

Все команды принимают --format json|md (по умолчанию md). Передавайте JSON через jq для скриптов, читайте markdown-вариант напрямую.

Проект

Фазы

Тикеты

Задачи

Заметки и уроки

Передачи, блокировки, снимки

Storybloq Bus (по желанию)

Federation (проекты-оркестраторы)

Команда (проекты в командном режиме)

Модель слияния, на которой работают эти команды, описана в разделе Team mode.

| Команда | Описание | | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- --- | | storybloq team init [--id-allocator local\|git-refs] [--claim-staleness-hours N] | Включить командный режим для этого проекта | | storybloq team setup | Установить git merge driver в этом клоне (каждый участник, один раз на каждый checkout) | | storybloq team doctor [--ci] | Проверки состояния команды; с --ci при обнаружении ошибок завершается с ненулевым кодом | | storybloq team config show · team config set <key> <value> | Просмотр или изменение конфигурации команды | | storybloq team reserve <type> --count N | Зарезервировать display-идентификаторы через удалённые refs (только аллокатор git-refs) | | storybloq reconcile [--dry-run] [--ci] | Обнаружить и перенумеровать дублирующиеся display-идентификаторы | | storybloq conflicts list · conflicts show <id> | Просмотр нерешённых конфликтов слияния | | storybloq resolve <id> [--field <f>] [--use ours\|theirs] [--value <json>] | Разрешить конфликты (также resolve config, resolve roadmap) | | storybloq gc [--apply] [--retention-days N] | Вычистить tombstones удалённых элементов за пределами срока хранения; без --apply выполняется сухой прогон (по умолчанию срок хранения — 30 дней) |

Справочник по MCP-серверу

Регистрируется в Claude Code или Codex (выполняется автоматически при настройке):

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

Сервер напрямую импортирует те же TypeScript-модули, что и CLI, поэтому затрат на запуск вспомогательных процессов нет. Он автоматически находит корень проекта, поднимаясь от рабочего каталога до ближайшего каталога, содержащего .story/.

Базовые инструменты сгруппированы по назначению. Проекты с включённой шиной регистрируют пять дополнительных инструментов при запуске MCP-процесса; после storybloq bus init перезапустите подключённых клиентов.

Чтение (без побочных эффектов)

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_loson_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

Запись (изменяет .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

Автономный режим + ревью + возврастность

storybloq_autonomous_guide управляет машиной состояний автономного режима (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 организуют конвейер ревью с несколькими линзами (требуется @storybloq/lenses).

storybloq_session_report · storybloq_register_subprocess · storybloq_unregister_subprocess показывают состояние сессии в приложении Mac.

Storybot Bus (feature-window)

storybloq_bus_send · storybloq_bus_poll · storybloq_bus_ack · storybloq_bus_thread_get · storybloq_bus_thread_update

Каждый вызов требует стабильный id конечной точки и актуальный проверенный id клиентской задачи. Результаты poll и thread помечают содержимое, полученное от других клиентов, как рекомендательный (advisory authority). storybloq_bus_poll и storybloq_bus_thread_get доступны только на чтение относительно канонического отслеживаемого состояния проекта; poll может согласовывать рантайм-метаданые .story/bus/, исключённые из git. Остальные три инструмента сохраняют обычные разрешения MCP на запись.

Федерация (проекты-оркестраторы)

storybloq_node_init разворачивает .story/ в репозиториях узла из контекста оркестратора.

storybloq_node_add · storybloq_node_list · storybloq_node_update управляют реестром узлов оркестратора.

Хуки

PreCompact (подготовка к компакции, выполняется настройкой)

Запускает storybloq session compact-prepare перед уплотнение контекста, чтобы снимки и возобновления оставались актуальными в клиентах, поддерживающих PreCompact-хуки. Настройка под Codex использует storybloq session compact-prepare --client codex с матчером manual|auto, чтобы хук Codex не мог закрыть задачу, принадлежащую Claude; настройка под Claude Code оставляет матчер пустым.

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

Пропустить можно через storybloq setup --client all --skip-hooks.ка.

SessionStart (внедрение промпта для возобновления)

Вставляет промпт возобновления, учитывающий компакцию. Настройка для Codex использует эту же команду с --codex-hook-json и матчером startup|resume|clear|compact; в hook-json также передаётся текущий id задачи, чтобы восстановление после COMPACT той же задачи могло продолжиться без скопированного Resume-TOKEN. Настройка не может проверить крайнюю достоверность хука, поэтому после установки проверьте /hooks в Codex.

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

storybloq bus hooks status — отдельное организация проекта, опирающая на опт-ин. Добавляет endpoint-метаданные и количество uint в SessionStart, а также позволяет синхронному Stop-хуку останавливаться один раз на каждый новый курсор почтового ящика. Байты других-процессов никогда не вызываются в вывод хука. собирается общая структура хуков Claude по умолчанию (при обновлении остаётся защищённой правилами проекта); для Codex используется storybloq hook-status --client codex.

Stop (живое состояние для приложения Mac)

В конце каждого хода запускается storybloq hook-status, обновляя файл .story/status.json (не отслеживается git), который приложение Mac и iOS-компаньон используют для отображения актуального состояния сессии.

Запись с условной обработкой контента: если содержимое равно тому, что уже файл содержит (игнорируя временную метку и того, кто записал), ничего не записывается, а временная метка и строка в index остаются сохранными. Таким образом, простые бездействия оставляют рабочее дерево без изменений. Реальные изменения — смена workflow, новый вызов MCP, изменение health или expiry — записываются сразу же.

Проекты, тестовые сценарии которых считают любую запись во время прогона ошибкой, могут вовсе выключить функцию записи writer по завершении хода:

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

в .story/config.json. Хук тогда не выполняет работы по состоянию вообще: без сканирования сессии, без сборки payload, без самовосстановления gitignore, без записи. Автономные сессии продолжают обновлять статус на собственных MCP-переходах, поэтому приложение Mac в работе сессии по-прежнему показывает live-состояние — просто оно прекращает обновляции между обычными интерактивными ходами. Флаг по умолчанию включён, а если конфигурацию прочитать невозможно офъ повреждённая, то тоже остаётся включённым.

StopFailure (сообщение об исчерпании лимитов использования)

Запускается storybloq session-compact-stop? Уточните как storybloq stopper عند... (textarea operates only English).

Так, попробуем ещё раз.

При остановке сессии Claude Code по rate limit выполняется storybloq session limit-stop, что фиксирует остановку для автовосстановления (см. выше раздел про автоматическое возобновление при исчерпании лимита). Настройка добавляет также вторую группу матчеров SessionStart ("resume") с той же командой session resume-prompt, чтобы при повторном ручном открытии сессии, остановленной из-за лимита, клиент получал рекомендации с учётом лимита. Обе записи свойственны только для Claude, на каждом обновлении они согласуются и автоматически удаляются при активации глобального "kill switch".

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

Использование библиотеки

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

Всеми типами определений являются частью пакета (exports.types).

Примеры форматов файлов

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": []
}

Каждая запись является отдельным файлом. Идентификаторы подстригованы внутри каждого типа (T-001, T-002, ...). Отношение сущностей имеет одного ответственного: поле blockedBy тикета перечисляет блокирующие тикеты, а обратная связь ("что меня блокирует") производится перебором файлов.

Операции создания можно безопасно выполнять параллельно. Уникальный id и запись создаются одновременно под единой блокировкой проекта, то есть параллельные создатели сериализуются и каждый из них получает уникальный индивидуальный ID. Операция создания не вызовет молча затереть существующую запись; при одновременной высокой конкуренции создатель прервётся с документированной ошибкой, а не "столкуется".

Записи issue: сохраняется sourceRefs независимо от изменяющихся строк (пути) path:line при показе. Storybloq хэширут только нормализованный диапазон строк и никогда не сохраняет выдержки исходного текста. Переданная ревизия сопоставляется с коммитом Git; в противном случае Storybloq фиксирует диапазон в рабочем дереве и записывает HEAD только если текущее содержимое совпадает с этими байтами. storybloq validate выводит ошибку, если исходное доказательство найти не удаётся; предупреждение — когда исторический источник существует but перемещён или изменён в HEAD; никаких замечаний, если всё ещё соответствует.

Используйте storybloq validate --integrity-only, если повреждённый config.json или roadmap.json блокирует обычную загрузку. Этот чтене-предварительный префлайн делает однократное сканиров. .story/**/*.json всех файлов, по возможности показывает позиции парсера и отделяет критические singleton-офки от пропускаемых проавочек типов items and auxiliary на отдельные файлы. Он никогда не меняет повреждённые файлы.

Подтверждённые результаты ручной или внешней ревизии следует заносить прямо в открытые issue. Сначала выполните поиск; указывайте автора ревью в поле createdBy; прикрепите id ревью и версию через sourceRefs; используйте стабильный dedupeKey вида <review-id>:<finding-id> для идемпотентности повторения. Неопределенные вопросы дизайна остаются в заметках или в вопросах владельцу; работу с деfects(статусом) ведёт реализующий агент.

Записи типа "тикет" и "issue" сохраняют неизвестные JSON-поля. Для чтения и изменения этих избыточных полей используйте bloq ticket meta и bloq issue meta — они не затрагивают основные поля Storybloq. Значения хранятся в JSON, адресация осуществляется по ним через точечный путь, например bloq ticket meta set T-001 integration.linear '"ABC-123"'.

Глубина автономного ревью плана может задаваться для каждой карточки через метаданные reviewRisk (low, medium или high). Например, storybloq ticket meta set T-001 reviewRisk '"high"' требует как минимум три раунда ревью плана. Устаревшие метаданные risk также распознаются, но reviewRisk — канонический ключ. Эта настройка меняет только глубину ревью; она никогда не пропускает этап ревью.

Пример рабочего процесса

# 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.

Командный режим

.story/ — это обычный JSON под управлением git, поэтому команда, работающая с ним совместно, сталкивается с теми же двумя проблемами, что и с любым общим состоянием: параллельные правки одной записи и параллельное создание новых записей. Командный режим решает обе.

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

team init настраивает проект для командной работы (версия схемы, устаревание заявок, аллокатор идентификаторов, требуемые возможности клиента) и выполняет настройку для вашего клона. team setup устанавливает git merge driver storybloq-json в локальный git-конфиг клона и записывает .story/.gitattributes, чтобы JSON-файлы из .story/ обрабатывались через него. Git-конфиг привязан к клону, поэтому каждый участник команды запускает setup один раз в каждом checkout. storybloq team doctor проверяет всю конфигурацию (дублирующиеся отображаемые идентификаторы, неразрешённые конфликты, устаревшие заявки, установленный merge driver) и завершается с ненулевым кодом при ошибках с флагом --ci; см. раздел Командный CI ниже для описания рабочего процесса с merge-gate.

Параллельные правки: модель слияния

Когда git объединяет две ветки, в которых обе затрагивали одну и ту же запись в .story/, merge driver выполняет структурированное трёхстороннее слияние для каждой записи вместо построчного текстового слияния. Поля объединяются независимо: если один участник меняет status карточки, а другой правит её description, оба изменения сохраняются. Когда одно и то же поле расходится на обеих сторонах, driver не выбирает ни одно из значений. Он фиксирует расхождение как структурированный блок _conflicts внутри записи, так что файл остаётся валидным JSON без маркеров конфликтов; git всё равно сообщает о конфликте по этому пути, поэтому выполните git add файла и commit, чтобы завершить слияние, а затем разрешайте записанные конфликты в своём темпе (они переносятся через последующие слияния, пока не будут разрешены). Проект с неразрешёнными _conflicts блокируется на запись, пока каждый конфликт не будет разрешён:

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

Параллельное создание: коллизии отображаемых идентификаторов

Создание двумя участниками элементов на параллельных ветках — это другой сценарий отказа. Новые записи хранятся под случайным каноническим именем файла (например, t-8f2kq0v3n1xw9d4e.json), поэтому независимо созданные элементы никогда не сталкиваются на уровне файлов; только устаревшие последовательные имена файлов (ISS-041.json, из проектов, созданных до появления канонических идентификаторов) всё ещё могут конфликтовать по пути. Что может конфликтовать — это человекочитаемый отображаемый идентификатор: обе ветки вычисляют «следующий свободный номер» локально, и обе создают T-042. Это не конфликт слияния, это дубликат, и для него есть отдельный инструмент:

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

Перенумерованные элементы сохраняют свой старый отображаемый идентификатор в previousDisplayIds, поэтому существующие ссылки на старый номер по-прежнему разрешаются.

Выбор аллокатора идентификаторов

team init --id-allocator local|git-refs определяет, как выделяются отображаемые идентификаторы. Компромисс:

С git-refs team init также добавляет remote-ref-reservations в team.requiredFeatures, поэтому клиенты, не объявляющие эту возможность, отказываются создавать элементы вместо локального выделения против git-refs-команды и коллизий. Одна оговорка: текущие версии Mac-приложения предшествуют резервированию, но при этом объявляют эту возможность, поэтому до выхода обновления для Mac избегайте создания элементов из Mac-приложения в командах с git-refs. storybloq team reserve tickets --count 5 резервирует пакет идентификаторов заранее.

Версия схемы и старые клиенты

team init проставляет schemaVersion: 3 в .story/config.json. Релизы CLI до 1.5.0 корректно отказываются от проекта со schemaVersion-3 — и при чтении, и при записи — с сообщением об обновлении (Config schemaVersion 3 exceeds max supported 2. Run: npm update -g @storybloq/storybloq). Жёсткий отказ намеренный: эти клиенты не понимают данные командного режима, и в командах со смешанными версиями они ранее выдавали тихие частичные чтения вместо ошибки.

Репозитории команд, созданные до этого ограничения, несут schemaVersion: 2. Чтобы обновить существующий командный репозиторий: дождитесь, пока каждый участник запустит CLI 1.5.0+, затем установите schemaVersion в 3 вручную (или повторно запустите storybloq team init, который выполняет то же обновление). Старые сборки Mac-приложения показывают проект со schemaVersion-3 как доступный только для чтения до обновления; данные не теряются.

Обновление репозитория, созданного до .story/.gitignore

team init и team setup записывают .story/.gitignore, покрывающий локальные для машины файлы (sessions/, snapshots/, status.json, federation-cache.json, channel-inbox/). Gitignore не снимает с отслеживания уже отслеживаемые файлы, поэтому проект, принявший storybloq до появления gitignore, может уже содержать эфемерные файлы в истории git. Проверьте один раз и снимите их с отслеживания:

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

Закоммитьте удаление. Состояние сессии хранит абсолютные пути (включая ваше имя пользователя), так что это стоит сделать до первого общего push.

Удаление оставляет tombstone

Удаление карточки, задачи, заметки или урока в командном режиме не удаляет их из общего репозитория. Файл остаётся, сохраняя полное исходное содержимое, плюс маркер жизненного цикла: lifecycle: "deleted", временная метка deletedAt и deletedBy, установленный в git user.email удалившего. Разрешение конфликта «удаление против правки» также может проставить email разрешающего как deletedBy на синтезированном tombstone. Tombstone остаются в репозитории, пока кто-то не запустит storybloq gc --apply (срок хранения по умолчанию — 30 дней).

Вывод: удаление элемента скрывает его из обычных представлений, но не удаляет содержимое или отметку вашей личности из клонов участников команды. Запустите storybloq gc, чтобы просмотреть подходящие tombstone, затем storybloq gc --apply, чтобы очистить их после истечения срока хранения.

Что видит ваша команда

Командный режим разделяет состояние через репозиторий, поэтому всё, что закоммичено в .story/, видно всем, у кого есть доступ к репозиторию:

• Карточки, задачи, заметки и уроки, включая все поля свободного текста.

• Handover-документы: повествовательные документы сессий, часто самая подробная запись о том, что произошло и почему.

• Блоки заявок на элементах в работе: git-идентичность заявившего участника (user.email), имя ветки и временная метка заявки, плюс UUID claimedBySession, пока автономная сессия работает над элементом.

• Неразрешённые конфликты слияния: после расходящегося слияния затронутая запись несёт конфликтующие значения с обеих сторон (base, ours и theirs) внутри своего блока _conflicts, пока кто-то не разрешит его. Текст, написанный участником, но позже потерянный при арбитраже, остаётся видимым в файле до разрешения.

Локальные для машины файлы остаются вне репозитория после установки gitignore: sessions/ (состояние автономных сессий, включая events.log каждой сессии), snapshots/, status.json, federation-cache.json и channel-inbox/. Относитесь к закоммиченному содержимому .story/ с той же осторожностью, что и к сообщениям коммитов и комментариям в коде; оно путешествует вместе с репозиторием.

Командный CI

Для проектов в командном режиме добавьте CI-валидацию, чтобы ловить дублирующиеся displayId и устаревшие ссылки до слияния. См. TEAM_CI.md для готового рабочего процесса GitHub Actions.

Связанные проекты

• @storybloq/lenses — MCP-сервер и библиотека для многолинзового ревью кода. 9 специализированных ревьюеров работают параллельно и возвращают структурированные вердикты; автономный бэкенд линз storybloq потребляет его напрямую.

• Storybloq для Mac — нативное macOS-приложение, которое следит за .story/ и обновляется в реальном времени, пока работает ваш AI-клиент. Бесплатно в Mac App Store.

Поддержка

Пишите на shayegh@me.com по любому вопросу: проблемы с настройкой, вопросы, запросы функций или просто чтобы рассказать, что вы строите. Отчёты об ошибках также приветствуются в виде GitHub issues.

Участие в разработке

Приветствуются issues и PR. Для нетривиальных изменений сначала откройте issue, чтобы мы согласовали направление.

Настройка разработки:

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

Лицензия

PolyForm Shield 1.0.0 — лицензия с доступным исходным кодом и запретом конкуренции (не OSI open source).

Вы можете использовать storybloq для любых целей, включая:

• личные и хобби-проекты

• проекты с открытым исходным кодом

• внутреннее использование в компании

• коммерческое ПО, которое вы разрабатываете

Вы не можете без отдельной лицензии использовать storybloq для создания продукта, конкурирующего с ним: переупаковка, перепродажа, хостинг как управляемый сервис или white-labeling. Для этого свяжитесь с shayegh@me.com.

Полный текст см. в LICENSE, а NOTICE содержит требуемое уведомление об авторских правах, которое вы обязаны распространять при редистрибуции.