Compare commits

..
12 Commits
Author SHA1 Message Date
OthmanAdi ae2e389bb7 fix: Stop hook broken on Windows Git Bash (closes #133)
Two separate bugs, both reported by @nazeshinjite with a really
thorough diagnosis (the Claude output they included nailed it).

First: `export SD=` was failing as a shell builtin in Windows Git
Bash when invoked from Command Prompt — bash treated it like an
external command and threw "No such file or directory". Removed
`export` across all IDE variants.

Second, the real problem for Claude Code users: the fallback path
`$HOME/.claude/plugins/planning-with-files` doesn't exist. The
actual install is under `~/.claude/plugins/cache/`. The Claude Code
variants now use PowerShell's own `Get-ChildItem -Recurse` with `~`
expansion to find the script without relying on any path variable,
and a glob-based sh fallback for Unix. No hardcoded path, no
CLAUDE_PLUGIN_ROOT dependency.

Fixed across all 13 SKILL.md variants.
2026-04-17 22:28:37 +02:00
OthmanAdi 9f158bf620 fix: SkillCheck critical — >5 → 5+ in description, comma → space in allowed-tools; restructure README badges with credibility row first, version bump to 2.34.0 in badge 2026-04-15 22:23:12 +02:00
OthmanAdi 42976c99be docs: update community section title to 'What the community shipped' 2026-04-15 22:15:54 +02:00
OthmanAdi ba6bb03cfc docs: collapse community section, add Used in the Wild repos, improve section title 2026-04-15 21:29:20 +02:00
OthmanAdi fcf0522291 fix: correct openclaw.md install paths — .openclaw/ dir never existed, use clawhub-upload/ source 2026-04-15 21:09:37 +02:00
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
39 changed files with 789 additions and 125 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",
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,9 @@ hooks:
Stop:
- 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\""
command: "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.1"
---
+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
+4 -7
View File
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,9 @@ hooks:
Stop:
- 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\""
command: "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.1"
---
@@ -1,8 +1,8 @@
---
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.
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
+4 -7
View File
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,9 @@ hooks:
Stop:
- 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\""
command: "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.1"
---
+4 -4
View File
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,9 +21,9 @@ hooks:
Stop:
- hooks:
- type: command
command: "export SD=\"${FACTORY_PROJECT_DIR:-.factory/skills/planning-with-files}/scripts\"; sh \"$SD/check-complete.sh\" 2>/dev/null || true"
command: "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.1"
---
# Planning with Files
+2 -2
View File
@@ -1,8 +1,8 @@
---
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.
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
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,9 @@ hooks:
Stop:
- 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\""
command: "SD=\"$HOME/.mastracode/skills/planning-with-files/scripts\"; [ -f \"$SD/check-complete.sh\" ] || 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.1"
---
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,9 @@ hooks:
Stop:
- 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\""
command: "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.1"
---
+1 -1
View File
@@ -1,6 +1,6 @@
---
name: pi-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.
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.
---
# Planning with Files
+29
View File
@@ -2,6 +2,35 @@
All notable changes to this project will be documented in this file.
## [2.34.1] - 2026-04-17
### Fixed
- **Stop hook portability failure on Windows Git Bash** (closes #133, reported by @nazeshinjite) — Two independent bugs caused the Stop hook to silently fail on Windows 11 with Git Bash inside Command Prompt: (1) `export SD=` was treated as an external command rather than a shell builtin in certain Windows Git Bash invocation contexts, producing `bash: export: No such file or directory`; (2) the fallback path `$HOME/.claude/plugins/planning-with-files` never exists — the actual install location is `~/.claude/plugins/cache/planning-with-files/planning-with-files/VERSION/`. Fixed across all 13 SKILL.md variants (Claude Code, Codex, CodeBuddy, Cursor, Factory, Mastra Code, OpenCode, all language variants). Claude Code variants now use PowerShell self-discovery via `Get-ChildItem -Recurse` with `~` home expansion (no bash variable needed) and a glob-based sh fallback against the correct cache path. All other IDE variants have `export SD=` replaced with `SD=`.
## [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"
+22 -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
@@ -170,6 +186,7 @@ These developers have created forks that extend the functionality:
Thank you to everyone who reported issues, provided feedback, and helped test fixes:
- [@nazeshinjite](https://github.com/nazeshinjite) - Issue #133 (Stop hook portability failure on Windows Git Bash — two-root-cause diagnosis with full Claude output, fixed in v2.34.1)
- [@msuadOf](https://github.com/msuadOf) - Issue #93 (TMPDIR environment fix for plugin install)
- [@DorianZheng](https://github.com/DorianZheng) - Issue #84 (BoxLite sandbox integration proposal)
- [@mtuwei](https://github.com/mtuwei) - Issue #32 (Windows hook error)
@@ -198,6 +215,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:** 33+ and growing!
*Last updated: April 8, 2026*
*Last updated: April 17, 2026*
+26 -12
View File
@@ -6,13 +6,17 @@
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
[![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)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
[![Security Verified](https://img.shields.io/badge/Security-Audited_%26_Fixed_v2.21.0-blue)](docs/evals.md)
[![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/)
[![Version](https://img.shields.io/badge/version-2.34.1-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![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)
[![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)
<details>
<summary><strong>💬 A Note from the Author</strong></summary>
@@ -23,17 +27,28 @@ If this skill helps you work smarter, that's all I wanted.
</details>
<details open>
<summary><strong>🌍 See What the Community Built</strong></summary>
<details>
<summary><strong>🌍 What the community shipped</strong></summary>
| Fork | Author | Features |
|------|--------|----------|
### Forks & Extensions
| Fork | Author | What They Built |
|------|--------|-----------------|
| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation |
| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | Multi-project support, SessionStart git sync |
| [plan-cascade](https://github.com/Taoidle/plan-cascade) | [@Taoidle](https://github.com/Taoidle) | Multi-level task orchestration, parallel execution, multi-agent collaboration |
| [agentfund-skill](https://github.com/RioTheGreat-ai/agentfund-skill) | [@RioTheGreat-ai](https://github.com/RioTheGreat-ai) | Crowdfunding for AI agents with milestone-based escrow on Base |
| [openclaw-github-repo-commander](https://github.com/wd041216-bit/openclaw-github-repo-commander) | [@wd041216-bit](https://github.com/wd041216-bit) | 7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw |
### Used in the Wild
| Project | What It Is |
|---------|-----------|
| [lincolnwan/Planning-with-files-copilot-agent](https://github.com/lincolnwan/Planning-with-files-copilot-agent) | Entire Copilot agent repo built around the planning-with-files skill |
| [cooragent/ClarityFinance](https://github.com/cooragent/ClarityFinance) | AI finance agent framework — Planning-with-Files approach directly credited |
| [oeftimie/vv-claude-harness](https://github.com/oeftimie/vv-claude-harness) | Claude Code harness built on Manus-style persistent markdown planning |
| [jessepwj/CCteam-creator](https://github.com/jessepwj/CCteam-creator) | Multi-agent team orchestration skill using file-based planning |
*Built something? [Open an issue](https://github.com/OthmanAdi/planning-with-files/issues) to get listed!*
</details>
@@ -48,10 +63,12 @@ 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.1
| Version | Highlights |
|---------|------------|
| **v2.34.1** | **Stop hook Windows portability fix** (closes #133): `export SD=` failed in Windows Git Bash hook context; fallback path was wrong for plugin cache structure. Fixed across all 13 SKILL.md variants. (thanks @nazeshinjite!) |
| **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 +169,6 @@ 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.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![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 +181,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
+20 -7
View File
@@ -6,7 +6,7 @@ How to use planning-with-files with [OpenClaw](https://openclaw.ai).
## What This Integration Adds
- Workspace skill: `.openclaw/skills/planning-with-files/`
- Workspace skill: `skills/planning-with-files/` in your project root
- Full templates, scripts, and reference documentation
- Cross-platform support (macOS, Linux, Windows)
@@ -17,16 +17,29 @@ OpenClaw supports three skill locations (in precedence order):
---
## Installation (Workspace, recommended)
## Installation (via ClawHub — recommended)
Copy the skill to your project:
Install directly from the ClawHub marketplace:
```bash
claw install othmanadi/planning-with-files
```
Or download the zip from [clawhub.ai/othmanadi/planning-with-files](https://clawhub.ai/othmanadi/planning-with-files) and extract to your workspace `skills/` folder.
---
## Installation (Workspace, manual)
Copy from the GitHub repo to your project:
```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the OpenClaw skill to your workspace
cp -r planning-with-files/.openclaw/skills/planning-with-files skills/
# Copy the skill files to your workspace
mkdir -p skills/planning-with-files
cp -r planning-with-files/clawhub-upload/* skills/planning-with-files/
# Clean up
rm -rf planning-with-files
@@ -43,8 +56,8 @@ Install to your local OpenClaw skills directory:
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy to global OpenClaw skills
mkdir -p ~/.openclaw/skills
cp -r planning-with-files/.openclaw/skills/planning-with-files ~/.openclaw/skills/
mkdir -p ~/.openclaw/skills/planning-with-files
cp -r planning-with-files/clawhub-upload/* ~/.openclaw/skills/planning-with-files/
# Clean up
rm -rf planning-with-files
+4 -4
View File
@@ -1,8 +1,8 @@
---
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"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,9 +21,9 @@ hooks:
Stop:
- 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\""
command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.34.1"
---
# نظام تخطيط الملفات
+4 -4
View File
@@ -1,8 +1,8 @@
---
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"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,9 +21,9 @@ hooks:
Stop:
- 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\""
command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.34.1"
---
# Dateiplanungssystem
+4 -4
View File
@@ -1,8 +1,8 @@
---
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"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,9 +21,9 @@ hooks:
Stop:
- 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\""
command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.34.1"
---
# Sistema de Planificación con Archivos
+3 -5
View File
@@ -2,7 +2,7 @@
name: planning-with-files-zh
description: 基于 Manus 风格的文件规划系统,用于组织和跟踪复杂任务的进度。创建 task_plan.md、findings.md 和 progress.md 三个文件。当用户要求规划、拆解或组织多步骤项目、研究任务或需要超过5次工具调用的工作时使用。支持 /clear 后的自动会话恢复。触发词:任务规划、项目计划、制定计划、分解任务、多步骤规划、进度跟踪、文件规划、帮我规划、拆解项目
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,10 @@ hooks:
Stop:
- hooks:
- type: command
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\""
command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.32.0"
version: "2.34.1"
---
+3 -5
View File
@@ -2,7 +2,7 @@
name: planning-with-files-zht
description: 基於 Manus 風格的檔案規劃系統,用於組織和追蹤複雜任務的進度。建立 task_plan.md、findings.md 和 progress.md 三個檔案。當使用者要求規劃、拆解或組織多步驟專案、研究任務或需要超過5次工具呼叫的工作時使用。支援 /clear 後的自動會話恢復。觸發詞:任務規劃、專案計畫、制定計畫、分解任務、多步驟規劃、進度追蹤、檔案規劃、幫我規劃、拆解專案
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,12 +21,10 @@ hooks:
Stop:
- hooks:
- type: command
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\""
command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.32.0"
version: "2.34.1"
---
+4 -4
View File
@@ -1,8 +1,8 @@
---
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.
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.
user-invocable: true
allowed-tools: "Read, Write, Edit, Bash, Glob, Grep"
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
UserPromptSubmit:
- hooks:
@@ -21,9 +21,9 @@ hooks:
Stop:
- 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\""
command: "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
metadata:
version: "2.33.0"
version: "2.34.1"
---
# 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()