OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard.

Агенты⭐ 27 031Pythonпоследний релиз: v3.20.4
Открыть на GitHub ↗

Что это за инструмент

planning-with-files — это инструмент для persistent-планирования на основе файлов, который сохраняет состояние задач в markdown-файлах, позволяя AI-агентам переживать потерю контекста, перезагрузки сессий и краши.

Зачем нужен

Инструмент решает проблему потери прогресса при работе длинных агентов (long-running agentic tasks) и сброса контекста (context loss, /clear). Он полезен тем, что обеспечивает детерминированное завершение через completion gate и позволяет нескольким агентам (multi-agent) использовать общее состояние на диске, имитируя подход Manus.

Что можно реализовать

  • Работа с Claude Code, Codex CLI, Cursor, Kiro, OpenCode и 60+ другими агентами через стандарт SKILL.md
  • Долгосрочные задачи, требующие сохранения плана (task_plan.md), находок (findings.md) и прогресса (progress.md) между сессиями
  • Многоагентное взаимодействие с общим состоянием на диске
  • Автоматическое восстановление контекста после крашей или ручного сброса сессии

Ключевые возможности

  • Устойчивость к потере контекста и перезагрузкам благодаря файловому хранению состояния
  • Опциональный gate завершения, удерживающий агента до полного выполнения плана
  • Поддержка 60+ AI-агентов через стандарт SKILL.md
  • Валидированная безопасность и высокая точность (96.7% pass rate в бенчмарках)
  • Активное сообщество с форками и расширениями (multi-agent, interview-first workflow и др.)

👤 Кому подойдёт: разработчики, использующие AI-агентов для кодирования, особенно те, кто работает с длинными задачами или многоагентными системами

Релизы

v3.20.4patch
🕐 вчера · релиз на GitHub ↗

Исправлены ошибки в PowerShell-скриптах для OneDrive и защита тестов от случайных файлов.

  • Fixed: Исправлена работа с файлами OneDrive Files On-Demand в скриптах PowerShell.
  • Fixed: Устранена уязвимость в тестах, когда они загружали случайные файлы из репозитория.
  • Fixed: Исправлена логика проверки репозиторных точек в модуле аттестации планов.
v3.20.3patch
🕐 2 дн назад · релиз на GitHub ↗

Исправлена ошибка подсчёта планов при использовании симлинков и джункций в директории .planning.

  • Fixed: Симлинкованные и джункционные директории больше не учитываются как отдельные планы при проверке неоднозначности.
  • Fixed: Исправлено расхождение между shell-скриптами и плагином Hermes, из-за которого возникала ложная ошибка 'Multiple plans are available'.
  • Fixed: Скрипты set-active-plan.sh и set-active-plan.ps1 теперь запрещают установку активного плана на симлинк.
  • Fixed: Адаптер Codex и плагины OpenCode и DeepSeek Harness исключают симлинки из подсчёта планов.
  • Fixed: Проверка на симлинк теперь корректно отличает их от реальных директорий OneDrive Files On-Demand.
v3.20.2patch
🕐 2 дн назад · релиз на GitHub ↗

Исправлена ошибка в Hermes 0.21.3, из-за которой плагин не мог найти план из-за подмены рабочей директории.

  • Fixed: Исправлена проблема в Hermes 0.21.3, когда хост подменял TERMINAL_CWD на домашнюю директорию, из-за чего плагин не находил план.
  • Fixed: В CLI-сессиях теперь выводится уведомление о подмене директории и использовании PWF_PLAN_ROOT, если план найден не в рабочей папке.
  • Added: Команды /pwf и /pwf-status теперь корректно учитывают PWF_PLAN_ROOT и сообщают об ошибках резолвинга пина.
  • Added: Обновлена документация docs/hermes.md с описанием механизма, воспроизведения проблемы и использования пина.
v3.20.1patch
🕐 2 дн назад · релиз на GitHub ↗

Исправлены критические ошибки в инициализации сессий, обработке данных OpenCode и выборе плана в Hermes.

  • Fixed: init-session.sh и PowerShell-скрипт теперь корректно обрабатывают переносы строк в имени плана, создавая валидный slug.
  • Fixed: Исправлено наследование переменной PWF_PLAN_ROOT: инициализаторы теперь временно привязывают её к текущему проекту для аттестации.
  • Fixed: OpenCode-адаптер (session-catchup.py) стал устойчивым к некорректным данным: невалидный JSON фильтруется, а ошибки атрибутов больше не ломают сессию.
  • Fixed: Hermes-плагин предотвращает смешивание планов: при наличии нескольких планов выводится уведомление, а не выбирается случайный.
v3.20.0major
🕐 3 дн назад · релиз на GitHub ↗

DeepSeek Harness получил нативную поддержку планирования, улучшена работа с именованными планами в Cursor на Windows.

  • Added: DeepSeek Harness теперь поддерживает планирование через нативный плагин dsh-planning-with-files.
  • Added: В Cursor на Windows улучшено разрешение именованных планов через PowerShell-хуки.
  • Fixed: Исправлена работа PWF_PLAN_ROOT на PowerShell 5.1 и устранены ошибки при некорректных путях.
  • Fixed: Улучшена стабильность хуков Cursor: поддержка ConstrainedLanguage, UTF-8 и корректные уведомления.
  • Added: Обновлен README: упрощена структура и добавлены таблицы команд для хостов.
v3.18.3minor
🕐 5 дн назад · релиз на GitHub ↗

Планы больше не выводят уведомления об успешном завершении через общие шлюзы Stop.

  • Fixed: Отключено автоматическое уведомление об успешном завершении через шлюз Stop и Codex Stop hook.
  • Added: Плагин Claude Code и standalone skill hooks теперь используют тихий режим успешного завершения.
  • Fixed: Явные команды check-complete без флага gate по-прежнему корректно сообщают о завершении.
  • Синхронизированы изменения shell и PowerShell в поддерживаемых канонических зеркалах.
  • Механизмы защиты от бесконечной рекурсии, блокировки шлюзов и диагностики зависаний остались без изменений.
v3.18.1patch
🕐 6 дн назад · релиз на GitHub ↗

Исправлено отображение активного плана при наличии BOM в файле .active_plan, созданном редакторами Windows.

  • Fixed: Устранена ошибка отображения и списка планов, если файл .planning/.active_plan начинается с UTF-8 BOM.
  • Fixed: Обновлены все 18 копий shell-хелперов для корректного распознавания имени плана с BOM.
  • Fixed: Добавлено покрытие регрессионными тестами для файлов без новой строки, а также с LF и CRLF.
v3.18.0minor
🕐 8 дн назад · релиз на GitHub ↗

Добавлена возможность просмотра списка сохранённых планов через скрипты с подсчётом фаз и проверкой границ проекта.

  • Added: Появилась команда --list для вывода списка сохранённых планов с ID, количеством фаз и указателем по умолчанию.
  • Added: Поддержка скриптов для Bash и PowerShell, интегрированных в OpenCode, Mastracode и Hermes.
  • Fixed: Улучшена точность подсчёта фаз: корректная обработка смешанных статусов, дубликатов и многоязычных шаблонов.
  • Fixed: Обновление указателя теперь выполняется атомарно, что сохраняет жёсткие ссылки и точно сообщает об ошибках записи.
  • Fixed: Добавлена проверка границ файловой системы проекта при чтении директорий, файлов планов и указателей.
v3.17.2patch
🕐 12 дн назад · релиз на GitHub ↗

Исправлена ошибка с дублированием команд в Codex: теперь legacy-команды не мигрируют, создавая лишние навыки.

  • Fixed: Codex плагин теперь явно отключает миграцию устаревших команд через пустой список commands в манифесте.
  • Fixed: Устранено создание 13 избыточных навыков source-command-* из топ-команд Claude, которые появлялись ранее.
  • Канонический планирующий навык и нативные хуки Codex остались настроенными, команды Claude сохранены.
  • Проверено стабильность: пройдены все CI-джобы, локальный тест-сьюит (755 тестов) и проверки npm-пакета.
v3.17.1patch
🕐 13 дн назад · релиз на GitHub ↗

Исправлено перенаправление сессий при наличии нескольких именованных планов: теперь обязателен PLAN_ID.

  • Fixed: Исправлена ошибка #240: теперь для проектов с несколькими именованными планами обязательно указывать PLAN_ID, что предотвращает перенаправление сессий Codex.
  • Fixed: Улучшена диагностика: UserPromptSubmit теперь объясняет причину отсутствия привязки, а Stop и attestation отказываются использовать несвязанные корневые планы.
  • Added: Переменная PLAN_ID должна задаваться в среде запуска хоста, так как установка внутри подпроцесса инструмента не обновляет уже работающий хост.
  • Все 5 CI-джобов успешно пройдены на Ubuntu, macOS, Windows, Pi и OpenCode; обновлен тег v3.17.1 для корректных тестовых ожиданий.
v3.17.0major
🕐 14 дн назад · релиз на GitHub ↗

Исправлено критическое замедление на Windows за счёт перехода на Python, устранена уязвимость импорта модулей из текущей директории.

  • Fixed: Устранено зависание хуков на Windows (Git Bash): события теперь выполняются в одном процессе Python, что сокращает задержку с 8–10 секунд до 0,3 с.
  • Fixed: Исправлено обнаружение интерпретатора Python: исключены относительные пути и алиасы Microsoft Store, приоритет у `python3`.
  • Устранена уязвимость: интерпретаторы теперь запускаются в изолированном режиме (`-I`), предотвращая случайный импорт вредоносных модулей из корня репозитория.
  • Fixed: Исправлена обработка символов вне базовой многоязычной плоскости (BMP) и байтовая обработка `awk` для корректной работы на Windows.
  • Стандартный маршрут (standalone skill) теперь использует тот же оптимизированный путь без форков, что и основной планировщик.
v3.16.1patchbreaking
🕐 15 дн назад · релиз на GitHub ↗

Исправления в плагинах Claude, Codex и standalone-хуках, новые требования к PLAN_ID для сессий.

  • Breaking: Сессии Attached Codex, Hermes и Pi теперь требуют PLAN_ID при наличии нескольких планов в проекте.
  • Fixed: Плагин Claude и standalone-хук JSON корректно сохраняют обратные слеши в путях Windows под POSIX awk.
  • Added: Standalone skill hooks теперь передают инструкции PreToolUse и PostToolUse через additionalContext и контролируют напоминания.
  • Fixed: Встроенное напоминание прогресса Codex теперь использует единый ID сессии для записи и сброса кэша.
  • Added: Документация уточняет ограничения локальной хэш-аттестации, вывода PreCompact и защитных мер записи.
v3.16.0patch
🕐 18 дн назад · релиз на GitHub ↗

Исправлено: напоминание PostToolUse теперь доходит до модели, а не пользователя, и работает раз за ход.

  • Fixed: Исправлено: сообщение PostToolUse теперь корректно передаётся модели через additionalContext, а не выводится пользователю.
  • Fixed: Напоминание теперь срабатывает один раз за ход, а не при каждом вызове инструмента, с использованием маркера в кэше.
  • Fixed: Инструмент Bash удалён из триггеров PostToolUse, чтобы избежать ложных срабатываний при командах вроде ls или git status.
  • Fixed: Удалён устаревший fallback на task_plan.md в plugin dispatcher, приведённый к общему стандарту v3.15.0.
v3.14.0major
🕐 19 дн назад · релиз на GitHub ↗

OpenCode: полноценный плагин, паритет с shell-скриптами, исправления и документация.

  • Added: Добавлен нативный плагин opencode-planning-with-files для OpenCode с поддержкой инструментов, команд и автоматического внедрения плана.
  • Added: Достигнут паритет с shell-скриптами: реализована валидация slug, защита от BOM, проверка завершённости и маркеры сессий на TypeScript.
  • Fixed: Исправлена ошибка в документации по установке (issue #235), обновлены таблицы совместимости и исправлен резолвер PLAN_ID для Hermes.
  • Added: Добавлены команды pwf и pwf-status, а также 27 Vitest-тестов для CI и dogfood-режима.
v3.13.0major
🕐 19 дн назад · релиз на GitHub ↗

Полноценная интеграция Hermes Agent с поддержкой CLI, Desktop, команд и гейтов завершения.

  • Added: Hermes Agent стал полноценным хостом: добавлена поддержка CLI, Desktop и встроенных команд.
  • Added: Реализован гейт завершения через pre_verify-хук с учетом лимитов и состояния файлов.
  • Added: Добавлены новые команды /pwf, /pwf-status, /plan-status и улучшена регистрация навыков.
  • Fixed: Исправлена загрузка команд и путей для пользователей Windows в среде Hermes.
  • Fixed: Обновлена документация и исправлены ошибки в описании хуков и сканирования навыков.
v3.12.1patch
🕐 21 дн назад · релиз на GitHub ↗

Исправлено поведение attestation helper и обеспечена консистентность работы с путями и интерпретаторами на разных ОС.

  • Fixed: Запуск attestation helper в .planning/<slug>/ теперь обновляет файл .attestation вместо создания устаревшего файла.
  • Fixed: Обеспечено единообразное поведение системных алиасов macOS, указателей активных планов Windows и отказов PowerShell в Unix.
  • Fixed: Исправлена работа резервных механизмов доверенных интерпретаторов в поддерживаемой матрице окружений.
v3.12.0majorbreaking
🕐 22 дн назад · релиз на GitHub ↗

Важные изменения в обработке метаданных, блокировках и плагинах; ломает обратную совместимость.

  • Breaking: Автоматическое восстановление теперь читает только файлы планирования; для метаданных и воспроизведения нужны явные флаги.
  • Added: Полностью добавлена поддержка жизненного цикла плагинов Claude и Codex.
  • Fixed: Обновления статусов фаз используют общую блокировку директории и предотвращают мутации при её отсутствии.
  • Added: Скрытые инструкции шаблонов заменены на видимые рекомендации, а описания раскрывают детали инъекции контекста.
  • Fixed: Прямой вызов помощи больше не инициализирует план, а пакет npm проверяет отсутствие CRLF в скриптах.
v3.11.2patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлено размещение файлов навыков: теперь они копируются корректно, без ошибок в структуре директорий.

  • Fixed: Команды установки только навыков теперь копируют только папку skills/planning-with-files, исключая попадание i18n в неправильную директорию.
  • Fixed: Инструкции для Unix и PowerShell теперь создают папку ~/.claude/skills перед копированием, предотвращая размещение SKILL.md не там.
  • Fixed: Регрессионные тесты теперь проверяют Markdown-файлы на наличие копий целых директорий и блокируют создание лишних папок.
v3.11.1patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлена ошибка парсинга хука error-occurred.sh в POSIX-оболочках (dash), улучшена переносимость CI.

  • Fixed: Исправлен синтаксический error-occurred.sh, несовместимый с POSIX shell (dash), из-за использования bash-специфичного here-string.
  • Fixed: Заменена передача данных через here-string на printf для обеспечения корректной работы в CI и других POSIX-средах.
  • Fixed: Устранена ошибка в changelog v3.11.0, содержавшем лишние символы новой строки внутри кодовых блоков.
  • Исправление не затрагивает пользователей напрямую, так как хуки вызываются через bash, но критично для стабильности CI.
v3.11.0minorbreaking
🕐 1 мес назад · релиз на GitHub ↗

Оптимизация плагина Claude Code: объединение 6 скиллов в 1, снижение потребления памяти и исправление багов macOS.

  • Fixed: Структура плагина переделана: вместо 6 скиллов теперь регистрируется 1, что сократило объем токенов в сессии почти вдвое.
  • Fixed: Исправлена ошибка в macOS, когда shell-хуки могли выводить некорректный JSON из-за неэкранированных управляющих символов.
  • Added: Добавлен документ docs/languages.md, описывающий поддержку языков, которой не хватало в документации.
  • Breaking: Существующие установки локальных вариантов требуют переустановки для корректной работы команды npx skills update.
v3.10.2patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлены баги в хуках Copilot и Cursor, связанные с игнорированием отключения планирования и ошибками в PowerShell-скриптах.

  • Fixed: Все хуки Copilot и Cursor теперь корректно учитывают переменную PLANNING_DISABLED, позволяя отключать планирование.
  • Fixed: Исправлено некорректное поведение PreToolUse в Copilot, которое ранее выдавало разрешение на все инструменты при отключении планирования.
  • Fixed: Устранены ошибки в PowerShell-скриптах Copilot: исправлен вывод статуса фаз и логирование ошибок на Windows.
  • Fixed: Hermes determinism probe теперь работает без алиаса python, используя sys.executable.
v3.10.1patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлены ошибки JSON в хуках Codex, синхронизированы манифесты пакетов и улучшена документация.

  • Fixed: Исправлены сбои невалидного JSON в хуках Codex (SessionStart, UserPromptSubmit, PreCompact) на Linux и macOS.
  • Fixed: Синхронизированы источник npm-пакета и манифест синхронизации с архивом v3.10.0 для корректной провенанса.
  • Added: В документации добавлено различие между прямым подключением npm и автоматической маршрутизацией для Pi.
  • Added: README обновлен: добавлены SVG-иллюстрации терминала для сравнения /clear и подписана таблица статистики.
  • Fixed: Версионный скрипт теперь корректно обрабатывает отсутствующий gitignored ClawHub staging без сбоев.
v3.10.0major
🕐 1 мес назад · релиз на GitHub ↗

Исправлена критическая потеря данных при параллельном редактировании плана, добавлена защита прогресса и локализованы скрипты.

  • Fixed: Устранена критическая уязвимость: теперь при одновременной работе двух сессий в одном каталоге плана их изменения не перезаписываются молча.
  • Added: Включена по умолчанию защита на основе отслеживания прогресса (а не хешей), которая предотвращает запись устаревших данных и потерю выполненных фаз.
  • Fixed: Полностью локализованы все скрипты: добавлены недостающие модули (attestation, Stop gate, ledger) и исправлена поддержка UTF-8 для Windows.
  • Fixed: Исправлен формат README для корректного отображения на мобильных устройствах и улучшена читаемость статистики.
  • Fixed: Обновлен pin для `tesslio/skill-review-and-optimize`, что восстанавливает корректную работу обзоров навыков и закрывает уязвимость подделки маркеров.
v3.9.0majorbreaking
🕐 1 мес назад · релиз на GitHub ↗

Исправлена привязка планов к корню проекта, устранены критические баги установки и PowerShell, улучшена обработка ошибок провайдеров.

  • Breaking: Планы теперь привязываются к корню проекта через PWF_PLAN_ROOT, а не определяются по текущей директории, что предотвращает подмену контекста.
  • Fixed: Исправлено игнорирование PLANNING_DISABLED=1 на 11 маршрутах установки и устранены ошибки поиска скриптов Stop hook на шести хостах.
  • Fixed: Решена проблема парсинга PowerShell 5.1 из-за кодировки UTF-8, позволяющая создавать планы на Windows.
  • Fixed: Исправлена бесконечная цикличность запросов при ошибках провайдера и обновлена панель статуса для корректного отображения фаз.
  • Added: Внедрено явное информирование о отказах валидации и улучшена стабильность кэширования промптов.
v3.4.0minor
🕐 2 мес назад · релиз на GitHub ↗

Добавлена опция PLANNING_DISABLED=1 для отключения хуков планирования в отдельных сессиях Codex.

  • Added: Введена переменная PLANNING_DISABLED=1, позволяющая отключить инъекцию контекста и запись в файлы плана для отдельных вызовов.
  • Fixed: Исправлена проблема, когда хуки перехватывали однократные сессии, перенаправляя вывод в progress.md и создавая ложные записи в task_plan.md.
  • Fixed: Обновлена документация codex.md, которая ошибочно описывала блокирующий Stop hook, актуальный для версий старше v3.1.0.
  • Added: Защита от перехвата охватывает все точки входа Codex, включая Python-адаптер и скрипты dispatchers для разных языков.
v3.2.0minor
🕐 2 мес назад · релиз на GitHub ↗

Исправлены критические баги Windows, ошибки фаз планирования и аналитики шаблонов; добавлена поддержка безопасности.

  • Fixed: Исправлена работа session-catchup.py и inject-plan.sh на Windows: теперь корректно обрабатываются пути, кодировки и 8.3-имена файлов.
  • Fixed: Устранена ошибка, из-за которой файлы task_plan.md без заголовков Phase ошибочно считались пустыми (0/0 фаз).
  • Fixed: Исправлен флаг --template analytics: шаблоны теперь правильно подключаются к init-session.sh.
  • Added: Добавлен SECURITY.md и включена функция приватного сообщения об уязвимостях в GitHub.
  • Fixed: Исправлена документация AGENTS.md (убрано некорректное требование squash-merge) и обновлены гайды по установке.
v3.1.3patch
🕐 3 мес назад · релиз на GitHub ↗

Исправлена ошибка в YAML-фронтмате SKILL.md из-за неэкранированного двоеточия в описании.

  • Fixed: Исправлено невалидное YAML-оформление в canonical файле и семи английских IDE-вариантах (.codebuddy, .codex, .cursor, .factory, .hermes, .mastracode, .opencode).
  • Fixed: Поле description теперь корректно обернуто в двойные кавычки, что предотвращает ошибки парсинга и сбивает триггеры моделей.
  • Added: Добавлен тест tests/test_skill_frontmatter_valid.py для автоматической проверки валидности YAML-фронтмата всех SKILL.md файлов.
  • Версия обновлена до 3.1.3 во всех 17 файлах паритета; тестовый прогон: 184 пройдено, 4 пропущено.