AIKraft Agents

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 914Pythonпоследний релиз: v3.28.0
Открыть на 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.28.0minor
🕐 3 дн назад · релиз на GitHub ↗

Добавлена архивация и восстановление именованных планов, исправлены ошибки PowerShell и JSON-инвентаризации.

  • Added: Реализована опциональная архивация и восстановление именованных планов через скрипты set-active-plan с перемещением директорий и их сайдкаров.
  • Added: Улучшена логика работы с несколькими планами: при отсутствии PLAN_ID хуки ничего не инжектят, а уведомление теперь указывает команду архивации.
  • Fixed: Исправлено смещение значений modified_at в инвентаре PowerShell из-за локального UTC-смещения.
  • Fixed: Устранена генерация невалидного JSON при чтении заблокированных файлов плана в shell-инвентаре.
  • Fixed: PowerShell 7 теперь корректно обрабатывает пути длиной более 260 символов и директории с атрибутом Hidden.
v3.27.0minor
🕐 6 дн назад · релиз на GitHub ↗

Планирующие агенты теперь могут запрашивать JSON-инвентарь; команды плагина Claude адаптированы под выбранный план.

  • Added: Планирующие агенты могут запрашивать ограниченный JSON-инвентарь через флаги --list --json или PowerShell -List -Json, включая метаданные фаз и неопределенность выбора.
  • Added: Команды плагина Claude теперь следуют контрактам выбранного плана и инициализатора, сохраняя легальные зафиксированные корни и делегируя аттестацию.
  • Added: Обновлен README: добавлены портреты контрибьюторов, сворачиваемая витрина сообщества и ссылки на расширения, порты и SDK.
  • Опубликован пакет planning-with-files@3.27.0 в npm, архив которого полностью совпадает с проверенным исходным кодом Git.
v3.26.0minor
🕐 8 дн назад · релиз на GitHub ↗

Добавлена опция PWF_SKIP_SUBAGENTS для Claude Code, исправлены хуки для Codex, Copilot и Gemini.

  • Added: Добавлена переменная PWF_SKIP_SUBAGENTS=1 для подавления контекста плана в вызовах подагентов Claude Code.
  • Fixed: Исправлено сохранение существующих регистраций хуков Codex и устранено создание вложенных директорий.
  • Fixed: Обеспечен нейтральный вывод Copilot PreToolUse при использовании поддерживаемых событий контекста.
  • Fixed: Переменная PLANNING_DISABLED=1 теперь корректно работает во всех хуках жизненного цикла Gemini, включая SessionEnd.
v3.25.2minorbreaking
🕐 12 дн назад · релиз на GitHub ↗

Добавлена строгая валидация планов, исправлен контекст Copilot и улучшена установка Cursor.

  • Breaking: Создание планов теперь требует обязательной валидации формата; скрипты отклоняют планы без распознанных фаз или с неясным статусом.
  • Added: Инструмент plan-doctor.sh теперь сообщает о проблемах с фазами, а валидация работает без перезаписи плана.
  • Fixed: Исправлено использование контекста Copilot: теперь применяется текущий вывод additionalContext, а не устаревший.
  • Added: Хуки Bash в Cursor теперь корректно выбирают именованные планы и отказываются от неоднозначных выборов.
  • Fixed: Обновлена документация по установке Cursor: сохранены регистрации и исключены вложенные директории адаптеров.
v3.25.1patch
🕐 13 дн назад · релиз на GitHub ↗

Исправлена логика аттестации планов в OpenCode, улучшено отображение статуса DSH и добавлена оценка навыка.

  • Fixed: OpenCode: разделены маркеры аттестации и проверка дайджеста, исправлена ложная валидность для старых планов.
  • Fixed: DSH: сохранено уведомление о выборе плана при их наличии и добавлено сообщение об инициализации для проектов без плана.
  • Added: Добавлена оценка skill-lens с руководством по измерению эффективности создания файлов планирования.
  • Added: Обновлены версии исходников: OpenCode plugin — 1.2.1, DSH plugin — 1.0.2.
v3.25.0minor
🕐 17 дн назад · релиз на GitHub ↗

Hermes adapter 0.3.0: выбор именованных планов для бесед на общем бэкенде, локальные селекторы и улучшенная валидация.

  • Added: Появилась функция `planning_with_files_select` для выбора или очистки плана беседы, включая планы из других проектов.
  • Added: Профильные записи сохраняются после перезапуска бэкенда, а хуки и инструменты применяют локальные селекторы без изменения окружения процесса.
  • Fixed: Отсутствующие или некорректные планы теперь вызывают безопасный отказ, а конфликтующие аргументы директорий возвращают ошибку.
  • Added: Добавлена поддержка переключения на однозначный план при успешных записях и патчах, с сохранением текущей выборки при ошибках.
v3.24.3patch
🕐 19 дн назад · релиз на GitHub ↗

Pi extension 1.2.8: усиление проверки аттестации плана, защита от подмены файлов, уточнение правил перепроверки.

  • Fixed: Pi extension 1.2.8 теперь проверяет тот же снимок плана, что и для вставленного текста, исключая подмену файла между чтением и проверкой.
  • Fixed: Отсутствие или недоступность выбранных утверждений теперь являются блокирующими ошибками.
  • Added: Руководство по аттестации уточняет, что изменения чекбоксов, статусов фаз и следующего шага требуют явной повторной аттестации.
  • Обсуждение политики чекбоксов (#326) остается открытым; автоматическая повторная аттестация или подсистема прогресса не добавлены.
v3.24.2minor
🕐 20 дн назад · релиз на GitHub ↗

Pi parity mode теперь подавляет неизменные планы после вставки контекста; обновлен бандл расширения и список контрибьюторов.

  • Fixed: Pi parity mode подавляет неизменные pre-tool планы после подтверждения вставки контекста начала хода.
  • Added: Обновлено встроенное расширение Pi до версии 1.2.7 без добавления зависимостей.
  • Added: В статистику контрибьюторов добавлены репортеры и тестировщики, портреты охватывают 104 участника.
  • Added: Параметр PWF_PRETOOL=always восстанавливает старое поведение напоминаний для каждого листа.
v3.24.1minor
🕐 21 дн назад · релиз на GitHub ↗

Улучшена валидация frontmatter для всех навыков, обновлены ссылки в документации KiloCode и добавлены фикстуры для проверки скрытых адаптеров.

  • Added: Валидация frontmatter теперь охватывает все 18 отслеживаемых навыков, включая 12 скрытых копий адаптеров.
  • Added: Добавлены изолированные фикстуры для проверки валидного и некорректного YAML, а также исключенных директорий и псевдонимов путей Windows.
  • Added: Введен инвентарь отслеживаемых файлов для защиты будущих адаптеров, а архивы исходного кода сохраняют проверку файловой системы.
  • Fixed: Исправлены ссылки в руководстве KiloCode: шесть ресурсов теперь открывают канонические файлы репозитория.
  • Added: Файл CONTRIBUTING.md обновлен: документация Python 3.12, Node 22, PyYAML, Windows sh и шести CI-пакетов с защищенными командами.
v3.24.0minor
🕐 27 дн назад · релиз на GitHub ↗

Добавлена нативная поддержка Qoder CLI и улучшена логика подавления повторного внедрения контекста в Claude Code.

  • Added: Добавлена поддержка Qoder CLI: установлен плагин, семь хуков жизненного цикла и адаптер для кодов выхода.
  • Fixed: Claude Code теперь подавляет повторное внедрение контекста при успешной инъекции, обновляя интерфейс только при изменениях.
  • Fixed: Исправлено восстановление SessionStart: дочерний процесс запускается с изолированным Python, исключая загрузку PYTHONPATH.
  • Added: Введена переменная PWF_PRETOOL=always для принудительного запроса контекста при каждом совпадении вызова инструмента.
v3.23.0minor
🕐 1 мес назад · релиз на GitHub ↗

Добавлен публичный фикстур восстановления через файлы и исправлена совместимость DSH V4 с источниками сообщений.

  • Added: Публичный фикстур file-only recovery с контрольной точкой, шаблонами и градатором.
  • Fixed: DSH V4 теперь использует источник plugin:planning-with-files для всех маршрутов инъекции.
  • Added: Обновлены руководства по ручному планированию и передаче тем с учетом установленного резолвера.
  • Fixed: Исправлено описание silent opt-out для зарегистрированного Python-адаптера в руководстве Codex.
v3.22.0minor
🕐 1 мес назад · релиз на GitHub ↗

OpenCode 2 теперь поддерживает нативную инъекцию планов и новые инструменты планирования, сохраняя обратную совместимость с OpenCode 1.

  • Added: Добавлена поддержка OpenCode 2 с нативной инъекцией планов, напоминаниями, контекстом компактизации и инструментами планирования.
  • Added: Реализован шлюз завершения работы в режиме простоя (idle completion gate).
  • Fixed: Исправлена загрузка плагина в OpenCode 2, ранее приводившая к ошибкам.
  • Added: Обновлены инструкции по установке с учетом ключа v2 plugins и требований к экспорту для локальных обёрток.
  • Added: Сохранена полная поддержка OpenCode 1.
v3.21.0minor
🕐 1 мес назад · релиз на GitHub ↗

attest-plan.sh теперь поддерживает аттестацию корневого плана, а инициализация PowerShell добавила обработку ошибок при конкурентном доступе.

  • Added: attest-plan.sh теперь может аттестовать корневой план (root roadmap) при активном именованном плане; добавлены флаги --target root и --target <plan-id> с валидацией и выводом путей.
  • Added: Скрипт корректно обрабатывает пустые цели и неподдерживаемые аргументы, завершаясь без изменения других планов.
  • Fixed: Инициализация именованных планов в PowerShell теперь повторяет проверку активного указателя при конкурентном доступе, сохраняя валидацию корня и указателя с фиксированным лимитом повторов.
  • Added: Закрыты issues #294 и #296 через PR #295 и #297.
v3.20.8patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлены хуки для Cursor и Gemini, устранены лишние уведомления и ошибки очистки файлов.

  • Fixed: Claude Code больше не выводит уведомления после каждого ответа, если план не задан.
  • Fixed: PowerShell-скрипт корректно управляет бэкапами указателей, исключая утечки и ложные ошибки.
  • Fixed: Хуки Cursor переписаны под актуальную схему, контекст плана теперь корректно подается через sessionStart.
  • Fixed: Хуки Gemini используют правильные поля для передачи контекста и напоминаний.
  • Fixed: Скрипты хуков стали исполняемыми, что исправляет запуск на macOS и Linux.
v3.20.7patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлены ошибки CI, обновлены ссылки в README и данные контрибьюторов, а также устранены проблемы с блокировками и путями.

  • Fixed: Устранён сбой CI, связанный с метаданными публичных возможностей, за счёт уточнения описания пакета.
  • Fixed: Обновлены ссылки в README и данные контрибьюторов, включая стабильные идентификаторы и архивные кредиты.
  • Fixed: Исправлена блокировка статуса фазы (phase-status locking) благодаря вкладу @kuei51307-hub.
  • Fixed: Устранены ошибки в путях к OpenCode, DSH, Hermes и PowerShell благодаря вкладу @TayfurYldz.
v3.20.5patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлены ошибки воспроизведения OpenCode, отчётности аттестации, шаблонов аналитики и обработки ошибок записи в PowerShell.

  • Fixed: OpenCode session replay теперь корректно обрабатывает некорректные данные (null, массивы, нестроковые типы) без прерывания сессии.
  • Fixed: Shell и PowerShell теперь явно сообщают об ошибках аттестации с причиной и командой восстановления, не маскируя их как успех.
  • Fixed: Исправлен регресс в шаблонах аналитики: добавлен обязательный раздел Next Step для совместимости с жизненным циклом.
  • Fixed: PowerShell-планирование теперь корректно обрабатывает ошибки записи (Access Denied), сохраняя предыдущий активный указатель плана.
v3.20.4patch
🕐 1 мес назад · релиз на GitHub ↗

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

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

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

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

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

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

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

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

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

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

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

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

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

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