OthmanAdi/planning-with-files v2.38.0

v2.38.0: Claude Code turn-loop integration + OpenCode SQLite fix

on GitHub

Highlights

This release wires the planning workflow into Claude Code's May 2026 turn-loop primitives and fixes a silent regression for OpenCode users introduced by the OpenCode SQLite storage migration.

New: PreCompact hook

A new PreCompact hook fires on both /compact and autoCompact. When task_plan.md is present, it surfaces a reminder to flush in-context progress to progress.md before compaction completes, and prints the active Plan-SHA256 if an attestation is set. Stays silent without a plan. Exits cleanly on every code path; never blocks compaction. Added to the canonical SKILL.md, the five language variants (ar, de, es, zh, zht), and clawhub-upload.

New: /plan-goal slash command

Composes with Claude Code's /goal (released v2.1.139, May 12 2026). Derives a termination condition from the active plan so the agent stops when the plan file is genuinely complete, not just when the conversation looks done. /plan-goal does not replace /goal; users can still call /goal "anything" directly.

New: /plan-loop slash command

Composes with Claude Code's /loop (v2.1.72 and later). Default 10-minute tick re-reads the planning files, runs check-complete, and writes a progress.md entry if the previous tick produced no change. Override interval and prompt as usual.

New: templates/loop.md

Ships a planning-aware default prompt users can copy into .claude/loop.md (project) or ~/.claude/loop.md (user) so bare /loop runs grounded in the active plan. /loop only reads those two paths; this is a documented manual install, not deep coupling.

Fixed: OpenCode session catchup

Session-catchup script rewritten for OpenCode's SQLite storage migration. Reads ${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db read-only via SQLite URI, scopes by session.directory, and surfaces unsynced planning-file edits with the same UX as the Claude Code path. The previous JSON-tree reader had silently no-op'd for every OpenCode user since the storage change. Defensive PRAGMA table_info probe degrades cleanly on schema migrations.

New: Codex PermissionRequest adapter

Codex added a PermissionRequest hook event for tool-permission prompts. The new .codex/hooks/permission_request.py adapter surfaces a one-line reminder to review task_plan.md before approving a request, when an active plan is present. Session-attachment gated, read-only, never blocks.

Tests

Plus 19 new tests covering the PreCompact hook (silent without plan, emits reminder with plan, surfaces Plan-SHA256 when attested), command-file structure (plan-goal.md, plan-loop.md, loop.md), the OpenCode SQLite catchup path with a synthetic schema-matching DB, and the Codex PermissionRequest adapter. 98 tests passing.

Backward compatibility

All changes are additive. No file names, env vars, hook contracts, or slash commands were renamed or removed. The v2.37.0 hash attestation gate is verified intact: tamper detection still suppresses attacker content under the new hook surface.

Deliberately not changed

• No paths glob in canonical SKILL.md frontmatter (would silently restrict auto-invocation behavior).
• No wholesale !command substitution in hook bodies (would freeze the attestation hash at skill-load time and disable v2.37 tamper detection).
• No native Plan Mode panel integration (no plugin API documented at the time of this release).
• No language variant consolidation (separate breaking-change track, deferred).

Verified end to end

• Sandboxed init-session + attest-plan + PreCompact flow exercised in a fresh project directory.
• OpenCode SQLite catchup tested against a real 162 MB OpenCode database on the development machine: 94 sessions, 56 unsynced parts correctly extracted from a session that had edited planning files.
• Full pytest suite green.

Files

Install

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Claude Code plugin install:

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Full changelog: CHANGELOG.md