@kshuk/pi-fsm

Детерминированное управление жизненным циклом разработки для pi.dev: конечный автомат (FSM) ведёт задачу по фазам, запускает субагентов pi-subagents с изолированным контекстом, а решения пользователя принимает через ask_user_question (@juicesharp/rpiv-ask-user-question).

Модель исполняет инструкции фазы, но не выбирает переходы: следующий шаг вычисляет движок из (состояние, событие, guard). Переходы — только детерминированные гейты: ответ пользователя, вердикты/результаты субагентов, тайм-аут, аварийный стоп.

Документация: требования · архитектура.

Установка

pi install npm:@kshuk/pi-fsm

Зависимости (pi-subagents, @juicesharp/rpiv-ask-user-question) ставятся вместе с пакетом. Перезапустите pi.

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

В диалоге:

Реализуй [задача]. Веди в процессе.

Модель вызовет fsm_start с текстом задачи и процесс пойдёт:

1. Требования — уточнение с вами, утверждение.
2. Ресерч — параллельный «консилиум» субагентов, общий отчёт.
3. Редактирование отчёта — в диалоге, до утверждения.
4. План — детальный план решения.
5. Редактирование плана — можно вернуться к отчёту ресерча.
6. Реализация — без вашего участия.
7. Проверка — вердикт pass → отчёт об успехе; fail → возврат на реализацию с замечаниями (до 5 раз).

Служебные действия — в диалоге («какой мы шаг?», «поставь процесс на паузу», «останови процесс») — модель использует инструменты fsm_status / fsm_pause / fsm_resume / fsm_abort.

В терминале — информационная панель: текущая фаза, активные субагенты, «ждём вашего ответа».

Свои процессы

Определения FSM — множественные JSON-файлы. Ищутся в трёх каталогах (приоритет: проект > глобальный > пакет; одно имя — одно определение):

.мой-проект/
└── .pi/fsm/
    └── dev-lifecycle.json      # 1) проектный — версионируется с кодом

<папка настроек pi>/            # 2) глобальные — общие для всех проектов
└── fsm/                        #    ($PI_CODING_AGENT_DIR, по умолчанию ~/.pi/agent)
    └── мой-сценарий.json

@kshuk/pi-fsm/
└── definitions/                # 3) встроенные, в комплекте:
    ├── dev-lifecycle.json      #    фича: полный цикл разработки
    └── bugfix.json             #    баг-фикс: воспроизведение → диагностика → исправление ⇄ проверка

Минимальный пример (полная схема — в требованиях, раздел 5):

{
  "name": "mini",
  "version": 1,
  "initial": "work",
  "terminal": ["done"],
  "variables": { "task": "" },
  "states": {
    "work": {
      "description": "Выполнение",
      "launch": {
        "mode": "single",
        "children": [
          { "key": "writer", "agent": "worker", "task": "Сделай: {{task}}", "tools": ["read", "bash", "edit", "write"] }
        ]
      },
      "on": {
        "completed": { "to": "done" },
        "failed": { "to": "done" }
      }
    },
    "done": { "description": "Готово", "terminal": true }
  }
}

Особенности:

• description / keywords (топ-уровень, необязательно) — описание и ключевые слова конфига: видны в стартовой секции [Fsm] и fsm_status, помогают модели выбрать определение;
• guard — условие на payload события: {"field": "results[reviewer].structuredOutput.verdict", "op": "eq", "value": "pass"};
• set — передача данных следующему состоянию: {"set": {"feedback": "results[reviewer].structuredOutput.findings"}};
• max — лимит повторений перехода (защита от циклов);
• опросы question — контракт ask_user_question (2–4 опции, label → событие перехода);
• timeout — лимит состояния → событие timeout.

Данные

• Определения — .pi/fsm/*.json проекта (версионируется), глобальные <pi-config>/fsm/*.json, встроенные пакета (dev-lifecycle, bugfix); приоритет «проект > глобальный > пакет».
• Данные рантайма — вне репозитория: ~/.pi/fsm/runs/<projectId>/{state.json, history.jsonl, artifacts/}.

Ограничения v1

Один активный процесс на проект; без UI (non-interactive) состояния, ждущие пользователя, блокируются; per-state read-only режимы родителя — в планах.

Лицензия

MIT