OthmanAdi/planning-with-files

Selection

Select when

• The task will span many tool calls, phases, or context windows.
• Work must resume after /clear, compaction, a crash, or a fresh session.
• You want planning state in plain project-local Markdown rather than an external memory service.
• Premature agent completion is a recurring problem and an opt-in bounded gate is acceptable.
• Several hosts or agents need to hand off one task through shared files.
• Concurrent tasks in one repository need separately selected plan directories.
• You need an auditable record of findings, decisions, errors, tests, and progress.
• You want a native Claude Code plugin rather than only a prompt template.
• You need a planning workflow that also has adapters for Codex, Pi, Hermes, OpenCode, and other agents.

Boundaries

Avoid when

• The task is short enough that three planning files and hooks would add unnecessary overhead.
• You need transactional locking or automatic merge resolution for concurrent writers.
• You require completed plans to be automatically archived as tracked deliverables.
• You cannot allow project planning content to enter the configured model provider's context.
• You need compatibility with a specific older Claude Code release because no older minimum is claimed.
• You want npm installation alone to activate lifecycle hooks automatically.
• You need automatic cross-project or unrestricted transcript recovery.
• You cannot review or trust project-local planning text that hooks may inject.
• You require independently audited security or independently reproduced performance benchmarks.

Strengths

Capabilities

Risk profile

Risks and limitations

• Uncertainty: only selected first-party files were supplied, so hook implementations, manifests, tests, CI, installers, and the reported 706-test suite were not directly inspected.
• Uncertainty: repository metadata and documentation dates extend into 2026 relative to this analysis context, so release recency, adoption, and reported host versions cannot be independently reconciled.
• Uncertainty: repository-reported 96.7% assertion pass rate, three blind A/B wins, 5.0-versus-13.3-turn recovery result, and 289 ms hook latency were not independently reproduced.
• The historical recovery benchmark used an earlier transcript-catchup default, while current automatic recovery reads project files only.
• Skill descriptions trigger probabilistically, and the repository reports only 60–67% unforced engagement in one internal benchmark.
• Standalone or project-local skill installs can remain silently hook-less until project trust is accepted and the skill is invoked.
• The repository supports only the latest release and claims no minimum compatible older Claude Code version.
• Repeated plan injection consumes model context and may overconstrain short or rapidly changing work.
• Planning files can contain untrusted text that reaches model context, although framing, attestation, and documented trust boundaries mitigate rather than eliminate prompt-injection risk.
• The parallel-write guard is advisory and cannot detect or merge every overwritten plan, findings file, or progress file.
• Gated completion depends on host capabilities, phase-marker correctness, configured caps, and ledger activity rather than proving task correctness.
• Explicit replay can expose bounded same-project session excerpts to model context, and the configured host may send them to its model provider.

First-party security documentation identifies prompt injection, path traversal, symlink escape, and supply-chain risks. The project describes nonce or explicit framing, SHA-256 plan attestation, containment checks, safe selector validation, fail-closed ambiguity handling, atomic attestation writes with optional flock, private vulnerability reporting, and a completion gate that never executes commands declared in Markdown. These controls were documented but their implementations were not directly inspected in the supplied files.