B — Some risk signals Graded October 16, 2026Minor concerns worth a quick check.Based on public adoption and transparency signals as of October 16, 2026. Our opinion, not a code audit or security guarantee.
AI agent skill · Developer tools, Files & documents
planning-with-files
Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.
Bottom line: Signal-based grade (5/7 points): very widely starred on GitHub, listed in several sources, public source code. This reflects adoption and transparency, not a code review.
- Popularity score
- 56/100
- Rank
- #46 of 500
- GitHub stars
- 27.5k
What it does
Maintains persistent, markdown-based task plans for AI coding agents that survive crashes, context resets, and long sessions. Automatically re-injects plans per turn to prevent drift, includes deterministic completion gates, and supports session recovery after /clear commands.
Who it’s for
Builders deploying long-running AI agents in Codex, Cursor, OpenCode, and 60+ compatible platforms who need reliable state management without external databases. Useful for teams running multi-hour coding tasks that must tolerate interruptions and model context window resets.
Copy-paste setup
Check these steps against the project’s own instructions before running anything.
Verify against the repo README at https://github.com/OthmanAdi/planning-with-files (opens external site) for exact instructions. Likely paths:
npm install:
npm install planning-with-files
Direct use via npx:
npx planning-with-files
Claude Desktop plugin (if available in marketplace):
Add to claude_desktop_config.json mcpServers section per plugin docs.
Risks
- File system access scope: Skill reads/writes markdown files locally; confirm permission boundaries to prevent unintended file overwrites or disclosure of sensitive plans stored on disk.
- Plan content leakage: Plans injected per turn may contain credentials, API keys, or proprietary task details—review what gets logged in plan files.
- Deterministic gate bypass: Completion logic runs locally without external validation; malformed plans or prompt injection could trigger false completions.
- Session recovery trust: Recovery after /clear assumes file integrity; corrupted or tampered markdown could cause agent to skip steps or restart incorrectly.
- No built-in encryption: Plans stored as plain markdown; protect files via OS-level access controls if they contain sensitive context.
How to stay secure
Least-privilege permissions
- Restrict skill's file system scope to a dedicated
.plans/directory; deny access to parent directories, config files, or credential stores via OS ACLs or containerization. - Run the agent process under a dedicated low-privilege user account with read-write access only to the plan directory; reject root/admin execution.
- Use file masks (umask 0077) to ensure plan files are created with user-only read/write permissions; audit existing plan files for world-readable exposure.
- If integrating with secrets management, never embed credentials in plan markdown; use external vault references or environment variables instead.
Network isolation
- Run planning-with-files in an air-gapped or restricted network zone if plans contain proprietary logic; disable outbound connections from the agent process unless explicitly required.
- Do not expose plan files via HTTP endpoints, shared drives, or cloud sync services (Dropbox, iCloud) without encryption-at-rest.
- If using remote agents (Codex, Cursor, OpenCode, etc.), enforce TLS for any plan transmission and validate certificate pinning.
Monitoring
- Log all file read/write events to the
.plans/directory with timestamps and agent action; alert on unexpected deletions or modifications outside normal completion cycles. - Audit plan file size growth per session; flag sudden inflation that may indicate prompt injection or accidental data dumping.
- Monitor
/clearrecovery operations; verify recovered plans match expected step sequences and flag skipped or out-of-order steps. - Periodically scan plan markdown for embedded secrets (API keys, tokens, passwords) using static analysis; fail-safe if sensitive patterns are detected.
Red flags to watch for
- Plan files with timestamps older than expected session start, or recovery of corrupted/truncated markdown suggesting tampering or disk corruption.
- Deterministic gate triggering without corresponding task completion markers, or agent resuming with step indices that skip critical prerequisites.
- Plan injection attempts via prompt payloads containing markdown syntax (e.g.,
# COMPLETED) aimed at bypassing completion validation. - Unauthorized plan file access detected via ACL/audit logs, or discrepancies between logged plan content and files on disk.
Alternatives
- OpenAI Assistants / Files API – Managed, versioned file storage with built-in session recovery, but requires vendor lock-in.
- LangChain Memory modules – Structured state management (buffer, entity, graph) with pluggable backends; more abstraction, less file-native.
- Mem0 (formerly MemGPT) – Purpose-built persistent memory layer with tiering; adds external dependency but handles compaction automatically.
- Local SQLite + agent framework – Custom solution with full control; requires more engineering, lacks crash-proof markdown guarantee.