OthmanAdi/planning-with-files

This system is a cross-platform, file-based planning infrastructure designed to maintain persistent context for multi-step AI agent workflows. It enforces a structured three-file pattern (task plan, findings, and progress) to prevent context drift across diverse coding environments. The system integrates with various AI agents through native plugins and lifecycle hooks, ensuring plan context is injected and updated automatically. It also includes security hardening features like plan attestation and completion gating to verify integrity and enforce workflow discipline.

A new prompt named 'planning-with-files' has been added to the Continue integration. This feature introduces a structured 3-file workflow (task\_plan.md, findings.md, progress.md) designed to prevent context drift by persisting plans, findings, and progress. Users invoking this prompt will be guided to initialize these files via provided shell scripts and follow a strict process of logging decisions, errors, and verification results to maintain project focus.

.continue/prompts · high confidence

Introduces a new \claude-hook.sh\ script that serves as the central dispatcher for the planning-with-files plugin, handling events like session start, user prompts, and tool usage. The script optimizes performance by executing Python logic in a single process instead of forking multiple times, and includes fixes for consistent JSON encoding across different \awk\ variants and a throttle to send the PostToolUse nudge only once per turn. These hooks are registered in \hooks/hooks.json\ for Claude Code and \hooks/codex-hooks.json\ for Codex, enabling the plugin to inject planning context and manage plan resolution during the AI session.

hooks · high confidence

Introduces a set of shell hooks (before-model, before-tool, after-tool, session-start, session-end) for the Gemini CLI to integrate with the 'planning-with-files' skill. These hooks inject context from task\_plan.md into the agent's workflow: before-tool and before-model pass plan snippets or current phase info, after-tool reminds the agent to update progress, and session-start/session-end handle context restoration and completion checks. The implementation uses Python for safe JSON serialization and UTF-8 handling, and relies on printf for output to ensure POSIX compatibility.

.gemini/hooks · high confidence

Introduces the 'planning-with-files' skill, which uses persistent markdown files (task\_plan.md, findings.md, progress.md) as external memory for multi-step AI agent work. This includes a native OpenCode plugin (opencode-planning-with-files) that injects plan context, handles compaction, and supports gated/autonomous modes, along with CLI commands (/pwf, /pwf-status) and lifecycle hooks for session catchup, plan injection, and completion gating across POSIX and Windows environments.

.opencode · high confidence

This change introduces the core assets for the 'planning-with-files' Kiro skill, including Markdown templates for task plans, progress logs, and findings, as well as shell and PowerShell scripts to bootstrap these files into a workspace. It also adds a session-catchup script to help agents re-orient after context resets and a check-complete script to report phase status, addressing issues with phase counting and providing an opt-out mechanism for CI environments.

.kiro/skills/planning-with-files/assets · high confidence

Added the Arabic variant of the planning-with-files skill (planning-with-files-ar), including the SKILL.md definition, lifecycle hook dispatchers, and supporting scripts (init-session, inject-plan, attest-plan, check-complete, gate-stop, ledger-append). This provides a fully localized planning workflow for Arabic-speaking users, mirroring the functionality of the English skill with Arabic-language instructions, templates, and status reporting.

skills/i18n · high confidence

This change adds a new set of Python and shell scripts under .codex/hooks to integrate the planning-with-files system with the Codex agent. It includes a central adapter (codex\_hook\_adapter.py) and specific event handlers (pre\_tool\_use, post\_tool\_use, permission\_request, stop, session-start, user-prompt-submit, pre-compact) that inject plan context, manage session isolation, and handle tool-use decisions. The update also introduces a Windows-specific hook launcher (pwf-hook.cmd) and a dispatcher (plugin\_dispatch.py) to ensure these hooks run reliably across different operating systems and shell environments.

.codex/hooks · high confidence

The new \planning-with-files\ plugin enables persistent, file-based project planning within Hermes. It registers slash commands (\/pwf\, \/pwf-status\) and tools (\planning\_with\_files\_init\, \planning\_with\_files\_status\) to create and manage \task\_plan.md\, \findings.md\, and \progress.md\ files in the project root or isolated \.planning/\<slug\>/\ directories. The plugin supports multiple plans with explicit selectors, v3 modes (\autonomous\, \gated\) with attestation, and template selection. It injects the active plan context into LLM calls via hooks, ensuring bounded, verified context frames and cross-platform compatibility.

.hermes/plugins/planning-with-files · high confidence

The new planning-with-files extension adds lifecycle automation for the Pi coding agent, mapping events like session start and tool calls to plan reminders, recitations, and auto-continuation. It introduces plan attestation to detect tampered plan files via SHA-256 hashing and resolves plan paths by anchoring to the nearest ancestor directory with planning state, preventing loss of context when the agent changes directories. The extension supports multiple modes (auto, parity, cache-safe, notify) and includes security measures to ensure plan paths remain within the project root.

.pi/skills/planning-with-files/extensions/planning-with-files · high confidence

The planning-with-files skill now supports v3 modes that enhance security and control. Users can opt into autonomous or gated planning via init-session, which automatically generates a cryptographic SHA-256 attestation for the plan file to detect tampering and writes a nonce for secure delimiter framing. A new completion gate (check-complete) allows plans to be configured as 'gated' via a .mode file, preventing the agent from stopping until all phases are marked complete and specific ledger conditions are met. The skill also introduces a plan-doctor diagnostic script to verify hook injection, attestation status, and path canonicalization across different operating systems.

.continue/skills/planning-with-files/scripts · high confidence

The scripts in this location now support a v3 planning workflow that adds security and reliability features. Plans can be attested with a SHA-256 hash to detect tampering, and sessions are isolated using slugs and nonces to prevent cross-project interference. A new completion gate allows plans to opt-in to a stop-blocking mode that ensures all phases are finished before the agent halts. Additionally, the skill now includes a diagnostic script (plan-doctor) to verify that plan resolution, injection, and attestation are working correctly.

.gemini/skills/planning-with-files/scripts · high confidence

Added PowerShell and Bash hook scripts in .cursor/hooks to integrate planning-with-files with Cursor. The pre-tool-use hooks inject the first 30 lines of task\_plan.md to keep goals in context, while user-prompt-submit hooks inject full plan and progress context on every message (including after /clear) with nested-root conflict detection. The post-tool-use hooks remind the agent to update progress.md and task\_plan.md after file modifications. The stop hooks check phase completion status and provide follow-up messages, including a fix for non-phase-structured files to prevent false auto-continue prompts. All hooks support PLANNING\_DISABLED opt-out and handle UTF-8 encoding for Windows PowerShell.

.cursor/hooks · high confidence

Introduces the \opencode-planning-with-files\ plugin for OpenCode, which keeps a disk-based plan (task\_plan.md, progress.md, findings.md) in the model's context on every turn. The plugin injects the active plan into user messages, appends progress reminders after write-like tool executions, preserves plan pointers during session compaction, and enforces a completion gate that re-prompts idle sessions until phases are done. It resolves plans via explicit PLAN\_ID, the .active\_plan pointer, or the newest slug, refuses ambiguous multi-plan states without a selector, and provides pwf\_init, pwf\_status, and pwf\_check tools for the model.

.opencode/packages/opencode-planning-with-files · high confidence

The \.hermes\ area now includes a new 'planning-with-files' skill that enables persistent, file-based planning for multi-step AI-agent work. This skill introduces a structured workflow using \task\_plan.md\, \findings.md\, and \progress.md\ to maintain context across sessions. It includes lifecycle hooks for automatic recovery, a completion gate for gated/autonomous modes, and scripts for session catch-up and active plan management. The skill supports multiple IDEs (Claude Code, OpenCode, etc.) and provides templates for both general and analytics-focused planning.

.hermes · high confidence

The \dsh-planning-with-files\ package introduces a native plugin for the DeepSeek Harness that integrates with the \planning-with-files\ system to keep persistent, disk-based plans (stored in \task\_plan.md\, \progress.md\, and \findings.md\) in the model's context. The plugin automatically injects the active plan into agent prompts, attaches progress reminders after file-editing tool calls, and supports a gated mode that holds the agent open until the plan is marked complete. It also includes commands (\/pwf\, \/pwf-status\) and tools (\pwf\_init\, \pwf\_status\, \pwf\_check\) for managing plans, along with logic to handle multiple plans via \PLAN\_ID\ and to resume context after session compaction.

.dsh/packages/dsh-planning-with-files · high confidence

Added an examples directory containing documentation and code samples. The main README demonstrates the 3-file planning pattern (task\_plan.md, findings.md, progress.md) using a Python CLI todo app as a walkthrough. Additionally, a new BoxLite subdirectory provides a quickstart script and documentation for running the planning-with-files skill inside a BoxLite micro-VM via ClaudeBox, including examples for both single and multi-session workflows.

examples · high confidence

The \skills/planning-with-files/scripts\ directory has been replaced with a comprehensive suite of new scripts (\init-session\, \inject-plan\, \check-complete\, \attest-plan\, and \gate-stop\) for both Bash and PowerShell. These scripts introduce v3 features including isolated slug-mode planning, plan attestation (SHA-256 hashing) to detect tampering, and an opt-in completion gate that can block autonomous stops. The implementation adds strict security containment guards (realpath validation, symlink/junction rejection, and nonce-based delimiter framing) and ensures byte-identical behavior across Windows (PowerShell/Git Bash) and POSIX environments.

skills/planning-with-files/scripts · high confidence

The planning scripts (init-session, inject-plan, check-complete, attest-plan) have been rewritten to support v3 autonomous and gated modes, which opt-in via a .mode file to enable plan attestation (SHA-256 hashing to detect tampering), a completion gate (blocking the Stop hook unless specific conditions are met), and secure nonce-based delimiter framing. These changes improve cross-platform reliability by introducing a Python twin for inject-plan to avoid Git Bash fork overhead on Windows, standardizing plan resolution to slug-mode directories under .planning/\<slug\>/, and hardening security by validating file types, isolating cross-project data, and ensuring constant-time verification of planning roots.

.agents/skills/planning-with-files/scripts · high confidence

The planning-with-files scripts have been completely rewritten to support v3 features while maintaining byte-identical behavior for legacy v2 usage. New capabilities include plan attestation (SHA-256 hashing with tamper detection via attest-plan.sh/ps1), a completion gate system (check-complete.sh/ps1 with --gate mode that can block autonomous stops based on phase status and ledger activity), and v3 opt-in modes (--autonomous/--gated in init-session.sh/ps1 that enable autonomous operation with nonce-based delimiter framing). The scripts now support slug-mode planning under .planning/\<slug\>/ directories with proper cross-platform path resolution for Windows/PowerShell and POSIX/shell environments. A new inject-plan.py provides a single-process Python implementation that mirrors the shell reference for improved performance on Windows Git Bash. All scripts include proper error handling, explicit selector binding (PLAN\_ID/PWF\_PLAN\_ROOT), and security hardening against cross-project data leakage.

.factory/skills/planning-with-files/scripts, .pi/skills/planning-with-files/scripts · high confidence

The planning scripts in this location have been rewritten to support v3 features while maintaining byte-identical parity with legacy v2 behavior. Key changes include: (1) Cross-platform support with PowerShell equivalents (attest-plan.ps1, check-complete.ps1, init-session.ps1) alongside shell scripts, ensuring Windows users get native hook execution without Git Bash overhead. (2) Security hardening through plan attestation (SHA-256 hashing with tamper detection), nonce-based delimiter framing, and strict path validation that rejects symlinks, reparse points, and cross-project recovery data. (3) New completion gate system (check-complete --gate) that can block autonomous session stops when phases are incomplete, with opt-in gating via .mode files and configurable block caps. (4) Slug-mode planning with isolated .planning/\<slug\>/ directories, explicit PLAN\_ID/PWF\_PLAN\_ROOT selectors that act as bindings (not hints), and automatic attestation for autonomous/gated modes. (5) Performance improvements via inject-plan.py, a Python twin that eliminates shell fork overhead (reducing hook latency from seconds to \~60ms on Windows). (6) Per-invocation opt-out via PLANNING\_DISABLED=1 for CI/one-shot sessions.

.codex/skills/planning-with-files/scripts, .cursor/skills/planning-with-files/scripts · high confidence

The scripts in .codebuddy/skills/planning-with-files/scripts have been replaced with a new v3 implementation that introduces opt-in autonomous and gated planning modes (init-session), plan attestation to detect tampering (attest-plan), and a completion gate that can block the Stop hook until all phases are done (check-complete, gate-stop). The new check-complete logic correctly handles mixed status formats and avoids false positives for unstructured plans, while the PowerShell scripts are fixed to parse named plans and handle special characters correctly. A new Python twin (inject-plan.py) replaces the heavy shell chain for hook events to eliminate Git Bash fork overhead on Windows, and the entire script set is hardened for cross-platform compatibility, secure path resolution, and parallel session isolation.

.codebuddy/skills/planning-with-files/scripts · high confidence

This release introduces v2.40 with several key changes to the planning workflow. Plan directory resolution is now inverted to prioritize explicit slug-mode plans (via PLAN\_ID or .active\_plan) over the legacy root task\_plan.md, preventing silent fallbacks. SHA-256 attestation checks are now mtime-keyed and cached under $TMPDIR/pwf-sha, significantly reducing hook latency on Windows Git Bash. The completion gate logic in check-complete.sh and check-complete.ps1 has been hardened to support opt-in gating via .mode files, with improved handling of mixed phase status formats and stdin-based stop hook signals. Additionally, new scripts like attest-plan.sh/ps1 and \_v240\_update\_hook\_bodies.py support these changes, and version parity is enforced across all IDE skill variants via bump-version.py.

scripts · high confidence

A new .gitattributes file enforces LF line endings for shell, Python, PowerShell, and SVG files, while requiring CRLF for Windows batch files. This ensures scripts reach disk with the correct line endings on every platform, preventing silent hook failures caused by CRLF shebangs on POSIX systems and ensuring correct label/goto parsing in cmd.exe batch files.

(repo-wide) · high confidence

The planning-with-files scripts have been rewritten to ensure consistent behavior across Windows (Git Bash/PowerShell) and POSIX environments, replacing fragile shell chains with a single-process Python implementation (inject-plan.py) to eliminate fork timeouts. This update introduces a per-invocation opt-out via the PLANNING\_DISABLED environment variable, allowing CI or one-shot sessions to bypass planning injection. Security is strengthened by enforcing strict plan-root containment, validating plan IDs against ambiguous paths, and quarantining cross-project recovery data. Additionally, the Stop hook now uses a dedicated gate script to report accurate task completion status, and session catchup logic has been hardened to correctly resolve project paths containing special characters.

.mastracode/skills/planning-with-files/scripts · high confidence

Added tests for Pi extension plan attestation, anchor resolution, and runtime handlers; Expanded test coverage for planning system reliability and security.

This change introduces three new npm packages that provide native integrations for the planning-with-files capability across different AI agent platforms. The DeepSeek Harness plugin (dsh-planning-with-files) adds per-turn plan injection, write reminders, compaction recovery, and a turn-stopping completion gate, depending on the @deepseek-ai/dsh-\* suite. The OpenCode plugin (opencode-planning-with-files) provides similar per-turn injection, write reminders, compaction flush, and a session-idle completion gate, built on the @opencode-ai/plugin. The Pi Coding Agent extension (planning-with-files-pi-extension) extends the existing Pi skill to support these planning features within the Pi environment. All three packages are new additions to the repository, establishing the plugin infrastructure for these specific hosts.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 71.

• Code Health 66
• Architecture 100
• Maturity 74
• Readiness 67
• Security 87

• 300 commits — 167 feature/other, 133 fixes

• (root) — 99 commits
• skills/i18n — 41 commits
• .agents/skills — 19 commits
• .pi/skills — 15 commits
• .codebuddy/skills — 13 commits
• .codex/hooks — 11 commits
• skills/planning-with-files — 11 commits
• (repo) — 8 commits
• .github/hooks — 6 commits
• .github/workflows — 5 commits
• .cursor/hooks — 4 commits
• .hermes/plugins — 4 commits
• .dsh/packages — 3 commits
• .gemini/hooks — 3 commits
• .opencode/packages — 3 commits
• skills/planning-with-files-ar — 3 commits
• .claude-plugin/marketplace.json — 2 commits
• docs/cursor.md — 2 commits
• docs/deepseek-harness.md — 2 commits
• docs/installation.md — 2 commits

• fix: Merge pull request #126 from OthmanAdi/fix/123-125-badge-and-windows-hook
• fix: Merge pull request #145 from Emin017/fix-shebang
• fix: fix(catchup): require exact planning filenames
• fix: fix(catchup): skip malformed OpenCode parts
• fix: fix(codex): skip the WSL bash launcher and harden Windows Python discovery
• fix: fix(cursor): keep the PowerShell hooks on the canonical fall-through and fail-open contract
• fix: fix(cursor): resolve named plans in PowerShell hooks
• fix: fix(docs): align SHA-cache notes with v3 XDG cache path (follow-up to #174)
• fix: fix(docs): pin the current 653-test suite size in llms.txt and its guard
• fix: fix(dsh): re-inject the plan after compaction from the compaction/end session event
• fix: fix(hermes): require selector for multiple plans
• fix: fix(hooks): send the PostToolUse nudge to the model, once per turn, off read-only tools
• fix: fix(init): bind the attest selectors in slug mode only, clear them in root mode
• fix: fix(init): replace active pointers safely
• fix: fix(inject): apply realpath containment to inject-plan resolver
• fix: fix(opencode, hermes): second-model review fixes for the plan resolvers and the OpenCode plugin
• fix: fix(pi): anchor plan resolution on the nearest planning ancestor (closes #208)
• fix: fix(pi-tests): align parity-mode assertion with runtime source casing
• fix: fix(plans): accept BOM-prefixed active pointers
• fix: fix(plugins): require PLAN_ID when several named plans exist, in the shared OpenCode and DSH core
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

OthmanAdi/planning-with-files was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.