Compare commits

..
7 Commits
Author SHA1 Message Date
OthmanAdi e0e7d042e8 docs: update README to v2.34.0 — add release entry to version table 2026-04-15 20:58:08 +02:00
OthmanAdi 6aa4276926 release: v2.34.0 — Codex hooks restored, spring cleaning, contributors updated
Restores .codex/hooks.json and .codex/hooks/ scripts that were wiped when
master was rewritten during v2.32.0 (closes #132, original work by @Leon-Algo
in PR #120). Codex users now have full lifecycle hook parity with Claude Code,
Cursor, and Copilot: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
and Stop hooks all active.

Also includes:
- Tessl skill-review CI from PR #131 (@popey)
- Exec bit fix from PR #122 (@Leon-Algo) + regression test
- Duplicate metadata.version key fixed in .codebuddy, .cursor, .mastracode,
  .opencode, and .codex SKILL.md files
- docs/codex.md rewritten to cover hooks installation and protocol
- CONTRIBUTORS.md: added @Leon-Algo, @YSAA1, @kevinaimonster, @wd041216-bit;
  updated @lasmarois entry to include PR #37; total now 32+
- Version bumped to 2.34.0 across all 17 SKILL.md variants, plugin.json,
  marketplace.json, and CITATION.cff
2026-04-15 20:57:07 +02:00
Leon-Algo 17791c04ee fix: restore canonical script execute bits + regression test (#122) 2026-04-15 20:51:04 +02:00
Alan Pope cb5f84cb4f ci: add Tessl skill-review-and-optimize workflow (#131) 2026-04-15 20:50:32 +02:00
OthmanAdi 32f3c1f9a9 fix: quote description fields in ar/de/es SKILL.md to fix YAML parse error
Unquoted description values containing ": " (colon + space) caused the
yaml parser to throw "Nested mappings are not allowed in compact mappings".
This silently prevented ar, de, and es from being discovered by the skills CLI.
Chinese variants were unaffected because they use fullwidth colons (:).
2026-04-09 07:24:28 +02:00
OthmanAdi a420407829 docs: consolidate badges into two clean sections
Top: 3 stat badges (issues, installs, PRs)
Body: single big block — quality + license + all platform badges
2026-04-09 00:40:56 +02:00
OthmanAdi 867f4cba3f fix: remove duplicate version key in zh and zht SKILL.md frontmatter
Both Chinese variants had two version entries (2.33.0 + stale 2.32.0) —
invalid YAML, strict parsers would resolve to 2.32.0.
2026-04-09 00:37:47 +02:00
37 changed files with 710 additions and 79 deletions
+1 -1
View File
@@ -9,7 +9,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Now with hooks integration and multi-language support (Arabic, German, Spanish, Chinese).",
"version": "2.33.0"
"version": "2.34.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "2.33.0",
"version": "2.34.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Kiro, Clawd CLI, Gemini CLI, Cursor, Continue, and 16+ AI coding assistants. Now with Arabic, German, Spanish, and Chinese (Simplified & Traditional) support.",
"author": {
"name": "OthmanAdi",
@@ -23,10 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CODEBUDDY_PLUGIN_ROOT:-$HOME/.codebuddy/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.33.0"
version: "2.34.0"
---
+61
View File
@@ -0,0 +1,61 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume",
"hooks": [
{
"type": "command",
"command": "sh .codex/hooks/session-start.sh 2>/dev/null || sh \"$HOME/.codex/hooks/session-start.sh\" 2>/dev/null || true",
"statusMessage": "Loading planning context"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "sh .codex/hooks/user-prompt-submit.sh 2>/dev/null || sh \"$HOME/.codex/hooks/user-prompt-submit.sh\" 2>/dev/null || true"
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/pre_tool_use.py 2>/dev/null || python3 \"$HOME/.codex/hooks/pre_tool_use.py\" 2>/dev/null || true",
"statusMessage": "Checking plan before Bash"
}
]
}
],
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/post_tool_use.py 2>/dev/null || python3 \"$HOME/.codex/hooks/post_tool_use.py\" 2>/dev/null || true",
"statusMessage": "Reviewing Bash against plan"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/stop.py 2>/dev/null || python3 \"$HOME/.codex/hooks/stop.py\" 2>/dev/null || true",
"timeout": 30
}
]
}
]
}
}
+66
View File
@@ -0,0 +1,66 @@
#!/usr/bin/env python3
from __future__ import annotations
import json
import subprocess
import sys
from pathlib import Path
from typing import Any
HOOK_DIR = Path(__file__).resolve().parent
def load_payload() -> dict[str, Any]:
raw = sys.stdin.read().strip()
if not raw:
return {}
try:
payload = json.loads(raw)
except json.JSONDecodeError:
return {}
return payload if isinstance(payload, dict) else {}
def cwd_from_payload(payload: dict[str, Any]) -> Path:
cwd = payload.get("cwd")
if isinstance(cwd, str) and cwd:
return Path(cwd)
return Path.cwd()
def emit_json(payload: dict[str, Any]) -> None:
if not payload:
return
json.dump(payload, sys.stdout, ensure_ascii=False)
sys.stdout.write("\n")
def parse_json(text: str) -> dict[str, Any]:
if not text.strip():
return {}
try:
payload = json.loads(text)
except json.JSONDecodeError:
return {}
return payload if isinstance(payload, dict) else {}
def run_shell_script(script_name: str, cwd: Path) -> tuple[str, str]:
result = subprocess.run(
["sh", str(HOOK_DIR / script_name)],
cwd=str(cwd),
text=True,
capture_output=True,
check=False,
)
return result.stdout.strip(), result.stderr.strip()
def main_guard(func) -> int:
try:
func()
except Exception as exc: # pragma: no cover
print(f"[planning-with-files hook] {exc}", file=sys.stderr)
return 0
return 0
+8
View File
@@ -0,0 +1,8 @@
#!/bin/bash
# planning-with-files: Post-tool-use hook for Codex
# Reused from the Cursor integration.
if [ -f task_plan.md ]; then
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
fi
exit 0
+16
View File
@@ -0,0 +1,16 @@
#!/usr/bin/env python3
from __future__ import annotations
import codex_hook_adapter as adapter
def main() -> None:
payload = adapter.load_payload()
root = adapter.cwd_from_payload(payload)
stdout, _ = adapter.run_shell_script("post-tool-use.sh", root)
if stdout:
adapter.emit_json({"systemMessage": stdout})
if __name__ == "__main__":
raise SystemExit(adapter.main_guard(main))
+13
View File
@@ -0,0 +1,13 @@
#!/bin/bash
# planning-with-files: Pre-tool-use hook for Codex
# Reused from the Cursor integration.
PLAN_FILE="task_plan.md"
if [ -f "$PLAN_FILE" ]; then
# Log plan context to stderr so the Codex adapter can surface it as systemMessage.
head -30 "$PLAN_FILE" >&2
fi
echo '{"decision": "allow"}'
exit 0
+23
View File
@@ -0,0 +1,23 @@
#!/usr/bin/env python3
from __future__ import annotations
import codex_hook_adapter as adapter
def main() -> None:
payload = adapter.load_payload()
root = adapter.cwd_from_payload(payload)
stdout, stderr = adapter.run_shell_script("pre-tool-use.sh", root)
result = adapter.parse_json(stdout)
decision = result.get("decision")
if decision and decision != "allow":
adapter.emit_json(result)
return
if stderr:
adapter.emit_json({"systemMessage": stderr})
if __name__ == "__main__":
raise SystemExit(adapter.main_guard(main))
+15
View File
@@ -0,0 +1,15 @@
#!/bin/sh
# planning-with-files: SessionStart hook for Codex
# Runs session catchup, then reuses the same prompt context hook as UserPromptSubmit.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
CODEX_ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)"
SKILL_DIR="$CODEX_ROOT/skills/planning-with-files"
PYTHON_BIN="${PYTHON_BIN:-$(command -v python3 || command -v python)}"
if [ -n "$PYTHON_BIN" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
"$PYTHON_BIN" "$SKILL_DIR/scripts/session-catchup.py" "$(pwd)"
fi
sh "$SCRIPT_DIR/user-prompt-submit.sh"
exit 0
+29
View File
@@ -0,0 +1,29 @@
#!/usr/bin/env python3
from __future__ import annotations
import codex_hook_adapter as adapter
def main() -> None:
payload = adapter.load_payload()
root = adapter.cwd_from_payload(payload)
stdout, _ = adapter.run_shell_script("stop.sh", root)
result = adapter.parse_json(stdout)
message = result.get("followup_message")
if not isinstance(message, str) or not message:
return
if "ALL PHASES COMPLETE" in message:
adapter.emit_json({"systemMessage": message})
return
if bool(payload.get("stop_hook_active")):
adapter.emit_json({"systemMessage": message})
return
adapter.emit_json({"decision": "block", "reason": message})
if __name__ == "__main__":
raise SystemExit(adapter.main_guard(main))
+33
View File
@@ -0,0 +1,33 @@
#!/bin/bash
# planning-with-files: Stop hook for Codex
# Reused from the Cursor integration; Codex adapts followup_message separately.
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
exit 0
fi
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
fi
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "{\"followup_message\": \"[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting.\"}"
exit 0
fi
echo "{\"followup_message\": \"[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Update progress.md, then read task_plan.md and continue working on the remaining phases.\"}"
exit 0
+14
View File
@@ -0,0 +1,14 @@
#!/bin/bash
# planning-with-files: User prompt submit hook for Codex
# Reused from the Cursor integration.
if [ -f task_plan.md ]; then
echo "[planning-with-files] ACTIVE PLAN — current state:"
head -50 task_plan.md
echo ""
echo "=== recent progress ==="
tail -20 progress.md 2>/dev/null
echo ""
echo "[planning-with-files] Read findings.md for research context. Continue from the current phase."
fi
exit 0
+1 -4
View File
@@ -23,10 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CODEX_SKILL_ROOT:-$HOME/.codex/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.33.0"
version: "2.34.0"
---
@@ -2,7 +2,7 @@
name: planning-with-files
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring >5 tool calls. Supports automatic session recovery after /clear.
metadata:
version: "2.33.0"
version: "2.34.0"
---
# Planning with Files
+1 -4
View File
@@ -23,10 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CURSOR_SKILL_ROOT:-.cursor/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.33.0"
version: "2.34.0"
---
+1 -1
View File
@@ -23,7 +23,7 @@ hooks:
- type: command
command: "export SD=\"${FACTORY_PROJECT_DIR:-.factory/skills/planning-with-files}/scripts\"; sh \"$SD/check-complete.sh\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.34.0"
---
# Planning with Files
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring >5 tool calls. Supports automatic session recovery after /clear.
metadata:
version: "2.33.0"
version: "2.34.0"
hooks: "Configured in .gemini/settings.json (SessionStart, BeforeTool, AfterTool, BeforeModel)"
---
@@ -0,0 +1,25 @@
# Apply Skill Optimization — triggered when a contributor comments /apply-optimize on a PR.
# Commits the AI-suggested SKILL.md improvements from the review step directly to the branch.
# Docs: https://github.com/tesslio/skill-review-and-optimize
name: Apply Skill Optimization
on:
issue_comment:
types: [created]
jobs:
apply:
if: >
github.event.issue.pull_request &&
contains(github.event.comment.body, '/apply-optimize')
runs-on: ubuntu-latest
permissions:
pull-requests: write
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: tesslio/skill-review-and-optimize@bff9490027d60847df6494fdac7dccfb3ad82948
with:
mode: apply
+26
View File
@@ -0,0 +1,26 @@
# Tessl Skill Review & Optimize — runs on PRs that change any SKILL.md.
# Posts scores and AI-suggested improvements as a single PR comment.
# Contributors can comment /apply-optimize to commit the suggestions automatically.
# Docs: https://github.com/tesslio/skill-review-and-optimize
name: Tessl Skill Review & Optimize
on:
pull_request:
branches: [master]
paths:
- "**/SKILL.md"
jobs:
review:
runs-on: ubuntu-latest
permissions:
pull-requests: write
contents: read
steps:
- uses: actions/checkout@v4
- uses: tesslio/skill-review-and-optimize@bff9490027d60847df6494fdac7dccfb3ad82948
with:
optimize: true
tessl-token: ${{ secrets.TESSL_API_TOKEN }}
# Optional quality gate (off by default):
# fail-threshold: 70
@@ -23,10 +23,7 @@ hooks:
- type: command
command: "export SD=\"$HOME/.mastracode/skills/planning-with-files/scripts\"; [ -f \"$SD/check-complete.sh\" ] || export SD=\".mastracode/skills/planning-with-files/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.33.0"
version: "2.34.0"
---
@@ -23,10 +23,7 @@ hooks:
- type: command
command: "export SD=\"${OPENCODE_SKILL_ROOT:-$HOME/.config/opencode/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.33.0"
version: "2.34.0"
---
+23
View File
@@ -2,6 +2,29 @@
All notable changes to this project will be documented in this file.
## [2.34.0] - 2026-04-15
### Added
- **Codex hooks restored** (closes #132) — `.codex/hooks.json` and `.codex/hooks/` scripts are back. Codex users now get the same full lifecycle hook automation as Claude Code, Cursor, and Copilot users: SessionStart runs session catchup and injects plan context; UserPromptSubmit re-injects on every message; PreToolUse re-reads task_plan.md before Bash; PostToolUse reminds the agent to update progress.md; Stop blocks when phases are incomplete then re-prompts. These files were present in v2.31.0 (PR #120 by @Leon-Algo) but were accidentally wiped when master was rewritten during v2.32.0 — now fully restored.
- **Codex hook regression test** (`tests/test_codex_hooks.py`) — 4 test cases covering hooks.json structure, SessionStart context injection, PreToolUse systemMessage emission, PostToolUse progress reminder, and Stop block-then-allow behavior
- **Tessl skill-review-and-optimize CI** (PR #131 by @popey) — `.github/workflows/skill-review.yml` runs on every PR that touches a SKILL.md, posts scores and AI-suggested improvements as a PR comment; `.github/workflows/skill-optimize-apply.yml` lets contributors type `/apply-optimize` to commit the suggestions directly. Non-blocking by default.
### Fixed
- **Canonical shell scripts not executable** (PR #122 by @Leon-Algo) — `skills/planning-with-files/scripts/check-complete.sh` and `init-session.sh` were tracked as `100644` instead of `100755`, breaking Codex and any Unix installer that depends on the executable bit. Fixed to `100755`. Regression test added.
- **Duplicate `version:` key in Codex SKILL.md** — `.codex/skills/planning-with-files/SKILL.md` had two `version: "2.33.0"` entries in the metadata block (same bug fixed for zh/zht in a previous commit but missed here). Deduplicated.
- **Codex docs updated** — `docs/codex.md` rewritten to cover both skills and hooks installation, hooks protocol explanation, workspace vs personal install, and troubleshooting for duplicate hook messages and Windows limitations.
### Changed
- **CONTRIBUTORS.md updated** — Added @Leon-Algo (PRs #119, #120, #122), @YSAA1 (PR #109), @kevinaimonster (PR #108), @wd041216-bit (PR #107); updated @lasmarois entry to include PR #37; bumped total count to 32+
### Thanks
- @Leon-Algo for the Codex hooks design, three separate fix PRs, and patience while the master rewrite wiped his work (PR #119, #120, #122)
- @popey (Alan Pope) for the Tessl CI workflow (PR #131)
## [2.33.0] - 2026-04-09
### Added
+1 -1
View File
@@ -7,7 +7,7 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "2.33.0"
version: "2.34.0"
date-released: "2026-04-09"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
+21 -5
View File
@@ -25,12 +25,13 @@ These amazing people have contributed code, documentation, or significant improv
- Created workflow diagram showing task lifecycle
- **Impact:** Dramatically improved beginner onboarding
- **[@lasmarois](https://github.com/lasmarois)** - [PR #33](https://github.com/OthmanAdi/planning-with-files/pull/33)
- **[@lasmarois](https://github.com/lasmarois)** - [PR #33](https://github.com/OthmanAdi/planning-with-files/pull/33), [PR #37](https://github.com/OthmanAdi/planning-with-files/pull/37)
- Created session recovery feature for context preservation after `/clear`
- Built `session-catchup.py` script to analyze previous session JSONL files
- Enhanced PreToolUse hook to include Read/Glob/Grep operations
- Restructured SKILL.md for better session recovery workflow
- **Impact:** Solves context loss problem, enables seamless work resumption
- Restructured SKILL.md for better session recovery workflow (PR #33)
- Extended catchup scanning to all sessions, not just the most recent one (PR #37)
- **Impact:** Solves context loss problem, enables seamless work resumption across any session
- **[@aimasteracc](https://github.com/aimasteracc)** - [PR #30](https://github.com/OthmanAdi/planning-with-files/pull/30)
- Added Kilocode IDE support and documentation
@@ -97,6 +98,21 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[@Leon-Algo](https://github.com/Leon-Algo)** - [PR #119](https://github.com/OthmanAdi/planning-with-files/pull/119), [PR #120](https://github.com/OthmanAdi/planning-with-files/pull/120), [PR #122](https://github.com/OthmanAdi/planning-with-files/pull/122)
- Made planning scripts executable in `.codex` skill install, fixing Codex installer breakage (PR #119)
- Added official Codex hooks.json integration with full lifecycle hooks — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop — bringing Codex to full hook parity with other IDEs (PR #120)
- Fixed canonical script execute bits for `check-complete.sh` and `init-session.sh` with regression test (PR #122)
- **Impact:** Codex users now get the same automatic context injection and lifecycle automation as Claude Code and Cursor users
- **[@YSAA1](https://github.com/YSAA1)** - [PR #109](https://github.com/OthmanAdi/planning-with-files/pull/109)
- Fixed Codex session-catchup fallback that was silently broken after the session path changes
- **[@kevinaimonster](https://github.com/kevinaimonster)** - [PR #108](https://github.com/OthmanAdi/planning-with-files/pull/108)
- Added Simplified Chinese localization support, extending the skill to Chinese-language users
- **[@wd041216-bit](https://github.com/wd041216-bit)** - [PR #107](https://github.com/OthmanAdi/planning-with-files/pull/107)
- Added openclaw-github-repo-commander to the Community Built section, expanding the ecosystem showcase
- **[@popey](https://github.com/popey)** - [PR #83](https://github.com/OthmanAdi/planning-with-files/pull/83)
- Fixed `allowed-tools` YAML list (invalid per Anthropic skill spec, silently killing discoverability)
- Fixed `metadata.version` placement and added trigger terms for better skill matching
@@ -198,6 +214,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 28+ and growing!
**Total Contributors:** 32+ and growing!
*Last updated: April 8, 2026*
*Last updated: April 15, 2026*
+8 -7
View File
@@ -9,10 +9,6 @@
[![Closed Issues](https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)
[![Skills Playground](https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg)](https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/)
[![Closed PRs](https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)
[![Benchmark](https://img.shields.io/badge/Benchmark-96.7%25_pass_rate-brightgreen)](docs/evals.md)
[![A/B Verified](https://img.shields.io/badge/A%2FB_Blind-3%2F3_wins-brightgreen)](docs/evals.md)
[![Security Verified](https://img.shields.io/badge/Security-Audited_%26_Fixed_v2.21.0-blue)](docs/evals.md)
[![Loaditout Security Grade](https://loaditout.ai/badge/OthmanAdi/planning-with-files)](https://loaditout.ai/skills/OthmanAdi/planning-with-files)
<details>
<summary><strong>💬 A Note from the Author</strong></summary>
@@ -48,10 +44,11 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v2.33.0
### Current Version: v2.34.0
| Version | Highlights |
|---------|------------|
| **v2.34.0** | **Codex hooks fully restored** (closes #132): `.codex/hooks.json` + lifecycle scripts back — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. Tessl CI for SKILL.md quality reviews. Exec bit fix. 4 missing contributors added. (thanks @Leon-Algo, @popey!) |
| **v2.33.0** | **Multi-language expansion**: Arabic, German, and Spanish skill variants added (thanks to community contributors!) |
| **v2.32.0** | Codex session catchup rewrite (thanks @ebrevdo!), Loaditout A-grade security badge, Stop hook Git Bash fix |
| **v2.31.0** | Codex hooks.json integration with full lifecycle hooks (thanks @Leon-Algo!) |
@@ -152,7 +149,13 @@ These IDEs implement the [Agent Skills](https://agentskills.io) open specificati
A Claude Code plugin that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.
[![Benchmark](https://img.shields.io/badge/Benchmark-96.7%25_pass_rate-brightgreen)](docs/evals.md)
[![A/B Verified](https://img.shields.io/badge/A%2FB_Blind-3%2F3_wins-brightgreen)](docs/evals.md)
[![Security Verified](https://img.shields.io/badge/Security-Audited_%26_Fixed_v2.21.0-blue)](docs/evals.md)
[![Loaditout Security Grade](https://loaditout.ai/badge/OthmanAdi/planning-with-files)](https://loaditout.ai/skills/OthmanAdi/planning-with-files)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-2.33.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)
[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-green)](https://code.claude.com/docs/en/skills)
[![Cursor Skills](https://img.shields.io/badge/Cursor-Skills-purple)](https://docs.cursor.com/context/skills)
@@ -165,8 +168,6 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
[![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Hooks-000000)](https://docs.github.com/en/copilot/reference/hooks-configuration)
[![Mastra Code](https://img.shields.io/badge/Mastra%20Code-Skills-00BCD4)](https://code.mastra.ai)
[![BoxLite](https://img.shields.io/badge/BoxLite-Sandbox-6C3483)](https://boxlite.ai)
[![Version](https://img.shields.io/badge/version-2.33.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
## Quick Install
+131 -28
View File
@@ -1,22 +1,35 @@
# Codex IDE Support
# Codex Setup
Using planning-with-files with [OpenAI Codex](https://developers.openai.com/codex/).
---
## Overview
planning-with-files works with Codex as a personal skill in `~/.codex/skills/`.
Codex discovers skills from `.codex/skills/` and hooks from `.codex/hooks.json` or `~/.codex/hooks.json`.
This integration includes both:
- `.codex/skills/planning-with-files/` for the skill itself
- `.codex/hooks.json` plus `.codex/hooks/` for lifecycle automation
The hook behavior reuses the same mature shell scripts as the Cursor integration, with a thin Codex adapter layer for the differences in hook protocol.
> **Important:** Codex hooks require `codex_hooks = true` in `~/.codex/config.toml`.
---
## Installation
Codex auto-discovers skills from `.codex/skills/` directories. Two installation methods:
### Method 1: Workspace Installation (Recommended)
Share the skill with your entire team by adding it to your repository:
Share the skill and hooks with your whole team by committing `.codex/` to your repository:
```bash
# In your project repository
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy the Codex skill to your repo
# Copy the Codex integration to your repo
cp -r /tmp/planning-with-files/.codex .
# Commit to share with team
@@ -28,8 +41,6 @@ git push
rm -rf /tmp/planning-with-files
```
Now everyone on your team using Codex will have access to the skill!
### Method 2: Personal Installation
Install just for yourself:
@@ -38,45 +49,137 @@ Install just for yourself:
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy to your personal Codex skills folder
# Copy the skill
mkdir -p ~/.codex/skills
cp -r /tmp/planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/
# Copy the hook scripts
mkdir -p ~/.codex/hooks
cp -r /tmp/planning-with-files/.codex/hooks/* ~/.codex/hooks/
# Copy hooks.json
# If you already have ~/.codex/hooks.json, merge the planning-with-files entries manually
cp /tmp/planning-with-files/.codex/hooks.json ~/.codex/hooks.json
# Clean up
rm -rf /tmp/planning-with-files
```
## Usage with Superpowers
> **Note:** If you already have a `~/.codex/hooks.json`, do not overwrite it blindly. Merge the `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` entries into your existing file.
If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
### Enable Hooks in `config.toml`
```bash
~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
Ensure your `~/.codex/config.toml` contains:
```toml
[features]
codex_hooks = true
```
## Usage without Superpowers
If you already have a `[features]` section, add `codex_hooks = true` under it instead of creating a duplicate section.
Add to your `~/.codex/AGENTS.md`:
```markdown
## Planning with Files
<IMPORTANT>
For complex tasks (3+ steps, research, projects):
1. Read skill: `cat ~/.codex/skills/planning-with-files/SKILL.md`
2. Create task_plan.md, findings.md, progress.md in your project directory
3. Follow 3-file pattern throughout the task
</IMPORTANT>
```
## Verification
### Verification
```bash
codex --version
codex features list | rg '^codex_hooks\s'
ls -la ~/.codex/skills/planning-with-files/SKILL.md
ls -la ~/.codex/hooks.json ~/.codex/hooks/
```
If `codex_hooks` does not appear in `codex features list`, upgrade Codex before troubleshooting the skill.
---
## How It Works
### Hooks
Codex reads hooks from:
1. `.codex/hooks.json` in your project root
2. `~/.codex/hooks.json` for your global install
This integration includes all five Codex lifecycle hooks:
| Hook | What It Does |
|------|--------------|
| **SessionStart** | Runs `session-catchup.py`, then injects active plan context |
| **UserPromptSubmit** | Re-injects plan and recent progress on every user message |
| **PreToolUse** | Re-reads the first 30 lines of `task_plan.md` before Bash |
| **PostToolUse** | Reminds the agent to update `progress.md` after Bash activity |
| **Stop** | Blocks once when phases are incomplete, then falls back to a follow-up reminder |
### The Three Files
Once activated, the skill creates and maintains:
| File | Purpose | Location |
|------|---------|----------|
| `task_plan.md` | Phases, progress, decisions | Your project root |
| `findings.md` | Research, discoveries | Your project root |
| `progress.md` | Session log, test results | Your project root |
---
## Team Workflow
### Workspace Installation
With workspace installation (`.codex/` committed to your repo):
- Everyone on the team gets the same skill and hooks
- The Codex setup is version controlled with the project
- Updates ship through normal git review
### Personal Installation
With personal installation (`~/.codex/`):
- You can use the skill across all projects
- You keep your setup even if you change repositories
- Existing global hooks may need manual merging
---
## Troubleshooting
### Hooks Not Running?
1. Check that `codex_hooks = true` is present in `~/.codex/config.toml`
2. Verify `.codex/hooks.json` or `~/.codex/hooks.json` exists
3. Restart Codex after adding or changing hooks
4. Run `codex features list | rg '^codex_hooks\s'`
### Already Using Other Global Hooks?
That is fine, but do not overwrite your existing `~/.codex/hooks.json`. Merge the planning-with-files entries instead.
### Seeing Duplicate Hook Messages?
Avoid installing the same planning-with-files hooks in both places at once:
- workspace `.codex/hooks.json`
- global `~/.codex/hooks.json`
If you enable both, Codex may run both sets of hooks and duplicate the reminders.
### Windows Support
OpenAI's current Codex hooks documentation says hooks are disabled on Windows. The skill files can still be installed there, but the hook automation is currently for macOS/Linux Codex environments.
---
## Learn More
- [Installation Guide](installation.md)
- [Quick Start](quickstart.md)
- [Workflow Diagram](workflow.md)
---
## Support
- **GitHub Issues:** https://github.com/OthmanAdi/planning-with-files/issues
- **OpenAI Codex Hooks Docs:** https://developers.openai.com/codex/hooks
- **OpenAI Codex Skills Docs:** https://developers.openai.com/codex/skills
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files-ar
description: نظام تخطيط الملفات بنمط Manus لتنظيم وتتبع تقدم المهام المعقدة. ينشئ ملفات task_plan.md و findings.md و progress.md. يُستخدم عند طلب التخطيط أو تحليل المهام أو تنظيم المشاريع أو تتبع التقدم أو الخطط متعددة الخطوات. يدعم الاستعادة التلقائية للجلسة بعد /clear. كلمات التشغيل: تخطيط المهام، إدارة المشاريع، خطة العمل، تحليل المهام، تنظيم المشروع، تتبع التقدم، خطة متعددة الخطوات، ساعدني في التخطيط، تحليل المشروع
description: "نظام تخطيط الملفات بنمط Manus لتنظيم وتتبع تقدم المهام المعقدة. ينشئ ملفات task_plan.md و findings.md و progress.md. يُستخدم عند طلب التخطيط أو تحليل المهام أو تنظيم المشاريع أو تتبع التقدم أو الخطط متعددة الخطوات. يدعم الاستعادة التلقائية للجلسة بعد /clear. كلمات التشغيل: تخطيط المهام، إدارة المشاريع، خطة العمل، تحليل المهام، تنظيم المشروع، تتبع التقدم، خطة متعددة الخطوات، ساعدني في التخطيط، تحليل المشروع"
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
hooks:
@@ -23,7 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files-ar}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.34.0"
---
# نظام تخطيط الملفات
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files-de
description: Manus-artiges Dateiplanungssystem zur Organisation und Verfolgung des Fortschritts komplexer Aufgaben. Erstellt task_plan.md, findings.md und progress.md. Wird verwendet, wenn der Benutzer plant, zerlegt oder organisiert: mehrstufige Projekte, Forschungsaufgaben oder Arbeiten mit über 5 Tool-Aufrufen. Unterstützt automatische Sitzungswiederherstellung nach /clear. Auslöser: Aufgabenplanung, Projektplanung, Arbeitsplan erstellen, Aufgaben analysieren, Projekt organisieren, Fortschritt verfolgen, Mehrstufige Planung, Hilf mir bei der Planung, Projekt zerlegen
description: "Manus-artiges Dateiplanungssystem zur Organisation und Verfolgung des Fortschritts komplexer Aufgaben. Erstellt task_plan.md, findings.md und progress.md. Wird verwendet, wenn der Benutzer plant, zerlegt oder organisiert: mehrstufige Projekte, Forschungsaufgaben oder Arbeiten mit über 5 Tool-Aufrufen. Unterstützt automatische Sitzungswiederherstellung nach /clear. Auslöser: Aufgabenplanung, Projektplanung, Arbeitsplan erstellen, Aufgaben analysieren, Projekt organisieren, Fortschritt verfolgen, Mehrstufige Planung, Hilf mir bei der Planung, Projekt zerlegen"
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
hooks:
@@ -23,7 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files-de}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.34.0"
---
# Dateiplanungssystem
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files-es
description: Sistema de planificación basado en archivos estilo Manus para organizar y rastrear el progreso de tareas complejas. Crea task_plan.md, findings.md y progress.md. Cuando el usuario solicita planificación, desglose u organización de proyectos multipaso, tareas de investigación o trabajos que requieren más de 5 llamadas a herramientas. Soporta recuperación automática de sesión tras /clear. Palabras clave: planificación de tareas, planificación de proyecto, crear plan de trabajo, analizar tareas, organizar proyecto, seguimiento de progreso, planificación multipaso, ayúdame a planificar, desglosar proyecto
description: "Sistema de planificación basado en archivos estilo Manus para organizar y rastrear el progreso de tareas complejas. Crea task_plan.md, findings.md y progress.md. Cuando el usuario solicita planificación, desglose u organización de proyectos multipaso, tareas de investigación o trabajos que requieren más de 5 llamadas a herramientas. Soporta recuperación automática de sesión tras /clear. Palabras clave: planificación de tareas, planificación de proyecto, crear plan de trabajo, analizar tareas, organizar proyecto, seguimiento de progreso, planificación multipaso, ayúdame a planificar, desglosar proyecto"
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
hooks:
@@ -23,7 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files-es}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.34.0"
---
# Sistema de Planificación con Archivos
+1 -3
View File
@@ -24,9 +24,7 @@ hooks:
command: "export SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files-zh}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.32.0"
version: "2.34.0"
---
+1 -3
View File
@@ -24,9 +24,7 @@ hooks:
command: "export SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files-zht}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.32.0"
version: "2.34.0"
---
+1 -1
View File
@@ -23,7 +23,7 @@ hooks:
- type: command
command: "export SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
metadata:
version: "2.33.0"
version: "2.34.0"
---
# Planning with Files
View File
View File
+151
View File
@@ -0,0 +1,151 @@
import json
import os
import subprocess
import sys
import tempfile
import textwrap
import unittest
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
CODEX_ROOT = REPO_ROOT / ".codex"
HOOKS_JSON = CODEX_ROOT / "hooks.json"
HOOKS_DIR = CODEX_ROOT / "hooks"
class CodexHooksTests(unittest.TestCase):
def run_python_hook(self, script_name: str, payload: dict, cwd: Path) -> subprocess.CompletedProcess[str]:
return subprocess.run(
[sys.executable, str(HOOKS_DIR / script_name)],
input=json.dumps(payload),
text=True,
capture_output=True,
cwd=str(cwd),
check=False,
)
def run_shell_hook(self, script_name: str, cwd: Path, env: dict | None = None) -> subprocess.CompletedProcess[str]:
return subprocess.run(
["sh", str(HOOKS_DIR / script_name)],
text=True,
capture_output=True,
cwd=str(cwd),
env=env,
check=False,
)
def test_hooks_json_declares_all_expected_codex_events(self) -> None:
self.assertTrue(HOOKS_JSON.exists(), ".codex/hooks.json is missing")
payload = json.loads(HOOKS_JSON.read_text(encoding="utf-8"))
self.assertEqual(
{"SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"},
set(payload["hooks"]),
)
def test_session_start_reuses_plan_context(self) -> None:
with tempfile.TemporaryDirectory() as tmpdir, tempfile.TemporaryDirectory() as home:
root = Path(tmpdir)
root.joinpath("task_plan.md").write_text(
"# Task Plan\n\n## Goal\nShip Codex hooks\n",
encoding="utf-8",
)
root.joinpath("progress.md").write_text(
"# Progress\n\nFinished adapter draft.\n",
encoding="utf-8",
)
root.joinpath("findings.md").write_text(
"# Findings\n\n- reuse cursor hooks\n",
encoding="utf-8",
)
env = os.environ.copy()
env["HOME"] = home
result = self.run_shell_hook("session-start.sh", root, env=env)
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn("ACTIVE PLAN", result.stdout)
self.assertIn("Ship Codex hooks", result.stdout)
self.assertIn("Finished adapter draft", result.stdout)
def test_pre_tool_use_adapter_emits_system_message(self) -> None:
with tempfile.TemporaryDirectory() as tmpdir:
root = Path(tmpdir)
root.joinpath("task_plan.md").write_text(
textwrap.dedent(
"""\
# Task Plan
### Phase 1: Discovery
- **Status:** complete
"""
),
encoding="utf-8",
)
result = self.run_python_hook(
"pre_tool_use.py",
{"cwd": str(root), "tool_input": {"command": "pwd"}},
root,
)
self.assertEqual(0, result.returncode, result.stderr)
payload = json.loads(result.stdout)
self.assertIn("systemMessage", payload)
self.assertIn("# Task Plan", payload["systemMessage"])
def test_post_tool_use_adapter_emits_progress_reminder(self) -> None:
with tempfile.TemporaryDirectory() as tmpdir:
root = Path(tmpdir)
root.joinpath("task_plan.md").write_text("# Task Plan\n", encoding="utf-8")
result = self.run_python_hook(
"post_tool_use.py",
{"cwd": str(root), "tool_response": "ok"},
root,
)
self.assertEqual(0, result.returncode, result.stderr)
payload = json.loads(result.stdout)
self.assertIn("progress.md", payload["systemMessage"])
def test_stop_adapter_blocks_once_then_allows_reentry(self) -> None:
with tempfile.TemporaryDirectory() as tmpdir:
root = Path(tmpdir)
root.joinpath("task_plan.md").write_text(
textwrap.dedent(
"""\
### Phase 1: Discovery
- **Status:** complete
### Phase 2: Implementation
- **Status:** pending
"""
),
encoding="utf-8",
)
first = self.run_python_hook(
"stop.py",
{"cwd": str(root), "stop_hook_active": False},
root,
)
second = self.run_python_hook(
"stop.py",
{"cwd": str(root), "stop_hook_active": True},
root,
)
self.assertEqual(0, first.returncode, first.stderr)
self.assertEqual(0, second.returncode, second.stderr)
first_payload = json.loads(first.stdout)
second_payload = json.loads(second.stdout)
self.assertEqual("block", first_payload["decision"])
self.assertIn("Task incomplete", first_payload["reason"])
self.assertIn("Task incomplete", second_payload["systemMessage"])
if __name__ == "__main__":
unittest.main()
+27
View File
@@ -0,0 +1,27 @@
import stat
import unittest
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
SCRIPTS_DIR = REPO_ROOT / "skills" / "planning-with-files" / "scripts"
class CanonicalScriptPermissionsTests(unittest.TestCase):
def assert_executable(self, path: Path) -> None:
mode = path.stat().st_mode
self.assertTrue(
mode & stat.S_IXUSR,
f"{path} is not executable (mode: {oct(mode)})",
)
def test_shell_scripts_are_executable(self) -> None:
self.assert_executable(SCRIPTS_DIR / "check-complete.sh")
self.assert_executable(SCRIPTS_DIR / "init-session.sh")
def test_session_catchup_is_executable(self) -> None:
self.assert_executable(SCRIPTS_DIR / "session-catchup.py")
if __name__ == "__main__":
unittest.main()