Compare commits

...
41 Commits
Author SHA1 Message Date
OthmanAdi d4b699ccf1 Release v2.16.0: GitHub Copilot hooks support
Added GitHub Copilot hooks integration (PR #80 by @lincolnwan)
Updated version badge and changelog
2026-02-22 21:36:20 +01:00
Ahmad Othman Ammar Adi. dde2a69913 Merge pull request #80 from lincolnwan/feature/add-copilot-hooks
Create github copilot plugin with hooks
2026-02-22 21:34:40 +01:00
Lin Wan d69eda6b31 create github copilot plugin 2026-02-22 15:03:55 +01:00
OthmanAdi 6a9effe7d7 docs: add link to experimental isolated-planning branch 2026-02-21 01:17:05 +01:00
OthmanAdi bc642b9bf6 docs: move @gydx6 to CONTRIBUTORS.md (proper location) 2026-02-21 00:37:04 +01:00
OthmanAdi f3c07ea4c7 docs: add @gydx6 to contributors, bump version to v2.15.1 2026-02-21 00:28:13 +01:00
Noob_996 3a8547ff24 fix: prevent false-positive catchup in skill-distributed scripts
Fixes session-catchup false positives in all 9 skill-distributed copies.

Changes:
- Added early return when no planning files exist in project
- Added early return when no planning update found in session
- Removed fallback branch that emitted unsynced context incorrectly

Thank you @gydx6 for the thorough bug report, detailed analysis, and clean fix across all affected files.

Fixes #78
2026-02-21 00:25:44 +01:00
Ahmad Othman Ammar Adi. 4292f000a1 Update README.md 2026-02-09 22:15:26 +01:00
OthmanAdi 245726ee5b Move closed issues/PRs badges to top section 2026-02-09 22:13:13 +01:00
OthmanAdi 70fc70b682 Add closed issues and PRs badges 2026-02-09 22:11:50 +01:00
OthmanAdi ec84b78408 Add contributors section with @codelyc 2026-02-09 22:10:13 +01:00
shmilyu e18d267d24 Add opencode scripts for planning-with-files skill (#76)
Change-Id: Id10167a8d7496f9abe615ec8038143d5d8f558a4
2026-02-09 22:07:14 +01:00
OthmanAdi cb5f10ba5f Make community builds section open by default
Show community forks and contributions immediately without requiring click to expand
2026-02-08 16:14:44 +01:00
OthmanAdi 9fc3f3ff28 Update README for v2.15.0 release
- Added /plan:status command to commands table
- Updated version badge and release table
- Listed v2.15.0 highlights: status command + OpenCode fix
2026-02-08 16:06:50 +01:00
OthmanAdi 0c1ddd21c3 Fix OpenCode compatibility - detect IDE and show helpful message
OpenCode uses different session storage (.json at ~/.local/share/opencode/) than Claude Code (.jsonl at ~/.claude/projects/). Session catchup now detects the IDE and provides a clear workaround message instead of silently failing.

- Added IDE detection (checks env vars and directory structure)
- OpenCode users get helpful message to manually read planning files
- Claude Code functionality unchanged
- Updated OpenCode docs with known limitations section

Fixes #74
2026-02-08 16:05:59 +01:00
jonthebeef a233b1b430 Add /plan:status command for quick progress check
Adds visual status display with emoji icons, phase progress tracking, and error logging count. Thanks @jonthebeef for this thoughtful contribution!
2026-02-08 16:03:28 +01:00
OthmanAdi 61e6165e2f Move Supported IDEs to top collapsible section
- Moved to top with other collapsible sections
- Removed duplicate from original location
2026-02-06 15:17:32 +01:00
OthmanAdi 4e5084cde4 Make Supported IDEs section collapsible
- Added collapsible details/summary wrapper
- Header shows platform count (14 Platforms)
- Full table and legacy note preserved inside
2026-02-06 15:14:26 +01:00
OthmanAdi 0361bf17c4 Fix IDE-specific path references in SKILL.md files
- OpenCode: Replace CLAUDE_PLUGIN_ROOT with OPENCODE_SKILL_ROOT
- Kilocode: Replace CLAUDE_PLUGIN_ROOT with KILOCODE_SKILL_ROOT
- Cursor: Replace CLAUDE_PLUGIN_ROOT with CURSOR_SKILL_ROOT
- Update docs/opencode.md with oh-my-opencode configuration guide
- Add troubleshooting section for skill loading conflicts

Fixes #73
2026-02-06 15:10:12 +01:00
OthmanAdi abc11dd858 Consolidate Versions and Session Recovery into collapsible section
- New collapsible 'Releases & Session Recovery' section at top
- Shows key version highlights in compact table
- Session recovery info condensed with pro tip
- Removed duplicate sections from bottom of README
- Cleaner, more scannable layout
2026-02-06 14:57:01 +01:00
OthmanAdi c7e3b71bb8 Move Community Forks up and make both sections collapsible
- Thank You section now collapsible with attention-grabbing header
- Community Forks moved to top, collapsible with engaging header
- Added @ mention for RioTheGreat-ai
- Linked 'Open an issue' directly to issues page
2026-02-06 14:53:27 +01:00
Ahmad Othman Ammar Adi. 8adf37c6f8 Merge pull request #72 from RioTheGreat-ai/master 2026-02-06 13:35:16 +01:00
Ahmad Othman Ammar Adi. eb27664be1 Merge pull request #70 from codelyc/master 2026-02-06 13:34:36 +01:00
RioLabs ab208d9d92 Add AgentFund to community forks/extensions 2026-02-06 04:13:27 +00:00
codelyc 7082c7f41f fix: update codebuddy paths and codex usage docs
Change-Id: I28fb0e5f6a88427370ff1bd079c4951311be5815
2026-02-05 10:59:44 +08:00
OthmanAdi 8a49fdb03a Reorder README: prioritize value proposition and core concepts
Move Why This Skill, The Problem, The Solution, Manus Principles,
Usage, Key Rules, and When to Use sections above the fold.
Move IDE tables, Documentation, Session Recovery, and Versions
to the reference section at the bottom.
Remove redundant Kilo Code Support section (already in Supported IDEs table).
2026-02-04 23:40:44 +01:00
OthmanAdi 7f73508511 Add sync script for IDE folders, fix drift across 6 IDEs (fixes #53, #47)
Added scripts/sync-ide-folders.py — a maintainer tool that syncs shared
files (templates, scripts, references) from the canonical source
(skills/planning-with-files/) to all 13 IDE-specific folders.

Features:
- Preserves each IDE's unique structure and SKILL.md frontmatter
- Handles all structural variations (flat refs, subdir refs, asset dirs)
- Supports --dry-run (preview) and --verify (CI drift detection)
- Covers .cursor, .gemini, .codex, .openclaw, .kilocode, .adal, .pi,
  .continue, .codebuddy, .factory, .agent, .opencode, .kiro

First sync fixed drift in 6 IDE folders:
- .adal, .continue, .pi: updated session-catchup.py
- .continue: updated examples.md, reference.md
- .codebuddy: added missing templates/
- .gemini, .openclaw: added missing session-catchup.py

Thanks to @back1ply for proposing the deduplication approach (#53)
and @snowbedding for requesting Anthropic-style structure (#47).
2026-02-04 23:22:44 +01:00
OthmanAdi 0225360606 Rename .moltbot/ to .openclaw/, fix clawdhub-publish leak, add .gitignore entries
- Renamed .moltbot/ directory to .openclaw/ to match the OpenClaw rebrand
  (PR #65 only renamed docs/moltbot.md but missed the IDE directory)
- Updated SKILL.md metadata from moltbot to openclaw
- Removed accidentally committed clawdhub-publish/scripts/ from tracking
- Added clawdhub-publish/ and .claude/ to .gitignore
- Added .openclaw/ to README directory tree
2026-02-04 22:16:31 +01:00
OthmanAdi 0b033eb025 Add Cursor hooks support — preToolUse, postToolUse, stop (fixes #61)
Cursor now supports hooks natively via .cursor/hooks.json. Added:
- hooks.json config with preToolUse, postToolUse, and stop hooks
- Hook scripts in bash (.sh) and PowerShell (.ps1)
- hooks.windows.json for native PowerShell users
- Rewrote docs/cursor.md — removed "hooks don't work" limitation,
  documented full hook support including auto-continuation via stop hook
- Updated README Cursor format from "Skills" to "Skills + Hooks"

The stop hook is the highlight: it checks task_plan.md completion and
uses Cursor's followup_message to auto-continue the agent if phases
are incomplete (capped at 3 retries via loop_limit).

Thanks to @sulsDotK for reporting that Cursor now supports hooks.
2026-02-04 22:03:37 +01:00
OthmanAdi 9ec4d413b6 Fix incorrect plugin install command in README (fixes #59)
Changed from the non-existent `claude plugins install` command to the
correct slash command format: `/plugin marketplace add` followed by
`/plugin install`. Matches docs/installation.md and docs/troubleshooting.md.
2026-02-04 21:37:09 +01:00
OthmanAdi b96b42a9e5 Fix stop hook error, docs inconsistency, add Plan Cascade (fixes #68, #69)
- check-complete.sh/.ps1: Always exit 0 — incomplete task is a normal
  state, not an error. Uses stdout for informational status reporting.
  Fixes stop hook error in Claude Code. (#68)
- README.md, docs/quickstart.md: Clarify that the AI creates planning
  files (not the user manually). Align all docs on workflow. (#69)
- README.md: Add Plan Cascade by @Taoidle to Community Forks (#63)
- Updated all 21 check-complete script copies across IDE folders
2026-02-04 21:30:07 +01:00
OthmanAdi 16fd096f4f Fix check-complete scripts and kilocode docs (fixes #45, #62)
- check-complete.sh/.ps1: Add fallback for [complete] inline bracket
  status format in addition to existing **Status:** bold format
- Updated all 21 script copies across IDE folders
- docs/kilocode.md: Remove all references to non-existent
  .kilocode/rules/ directory (migrated to skills/ in v2.10.0)
- README.md: Update Kilo Code section to reference .kilocode/skills/
2026-02-04 21:22:53 +01:00
OthmanAdi 727fdfb72c Release v2.14.0 - Pi Agent support, Codex fix, OpenClaw docs
- Add Pi Agent integration (PR #67 by @ttttmr)
- Fix Codex skill path references (PR #66 by @codelyc)
- Update Moltbot docs to OpenClaw (PR #65 by @AZLabsAI, fixes #64)
- Update version badge to v2.14.0
- Update README: OpenClaw branding, version table
- Update CHANGELOG with v2.14.0 entry
2026-02-04 20:31:07 +01:00
Ahmad Othman Ammar Adi. b8274d23f8 Merge pull request #67 from ttttmr/master
Add Pi Agent support
2026-02-04 17:44:48 +01:00
Ahmad Othman Ammar Adi. 60e06093be Merge pull request #66 from codelyc/master
Fix codex skill path references
2026-02-04 17:40:52 +01:00
Ahmad Othman Ammar Adi. 7230d7f9d3 Merge pull request #65 from AZLabsAI/fix/moltbot-docs-openclaw-rename
docs: update moltbot.md to use OpenClaw naming and paths
2026-02-04 17:38:58 +01:00
linyuchiandClaude Sonnet 4.5 672e2515c2 Fix codex skill path references
- Update SKILL.md to use correct paths (~/.codex/skills/planning-with-files/)
- Replace CLAUDE_PLUGIN_ROOT references with absolute paths
- Add missing template files (findings.md, progress.md, task_plan.md)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Change-Id: I5b59bc1f54473f8af8c884b7c0cc1683de93a7ad
2026-02-04 19:32:31 +08:00
ttttmr 1089d65c60 Add Pi Agent support 2026-02-04 19:26:21 +08:00
TH33_ORACL3andCursor 28e89aae11 docs: rename moltbot.md to openclaw.md
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 19:21:37 +02:00
TH33_ORACL3andCursor cbf393a516 docs: update moltbot.md to use OpenClaw naming and paths
The product has been renamed from Moltbot to OpenClaw. This commit updates:

- Title and website link (molt.bot → openclaw.ai)
- Skills directory paths (~/.clawdbot/ → ~/.openclaw/)
- Config file path (moltbot.json → openclaw.json)
- CLI commands (moltbot → openclaw)
- All references to the product name

Fixes #64

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 19:20:33 +02:00
OthmanAdi c1a24568cd Update version badge to v2.13.0 2026-01-27 22:22:58 +01:00
98 changed files with 5582 additions and 1040 deletions
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -2,9 +2,8 @@
"""
Session Catchup Script for planning-with-files
Session-agnostic scanning: finds the most recent planning file update across
ALL sessions, then collects all conversation from that point forward through
all subsequent sessions until now.
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
@@ -14,6 +13,7 @@ import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
@@ -34,147 +34,106 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def get_session_first_timestamp(session_file: Path) -> Optional[str]:
"""Get the timestamp of the first message in a session."""
try:
with open(session_file, 'r') as f:
for line in f:
try:
data = json.loads(line)
ts = data.get('timestamp')
if ts:
return ts
except:
continue
except:
pass
return None
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Quickly scan a session file for planning file updates.
Returns (line_number, filename) of last update, or (-1, None) if none found.
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
try:
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
if '"Write"' not in line and '"Edit"' not in line:
continue
for msg in messages:
msg_type = msg.get('type')
try:
data = json.loads(line)
if data.get('type') != 'assistant':
continue
content = data.get('message', {}).get('content', [])
if not isinstance(content, list):
continue
for item in content:
if item.get('type') != 'tool_use':
continue
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
if tool_name not in ('Write', 'Edit'):
continue
tool_input = item.get('input', {})
file_path = item.get('input', {}).get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = line_num
last_update_file = pf
break
except json.JSONDecodeError:
continue
except Exception:
pass
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_from_session(session_file: Path, after_line: int = -1) -> List[Dict]:
"""
Extract conversation messages from a session file.
If after_line >= 0, only extract messages after that line.
If after_line < 0, extract all messages.
"""
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
try:
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
if after_line >= 0 and line_num <= after_line:
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
try:
msg = json.loads(line)
except json.JSONDecodeError:
continue
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
content = ''
tool_uses.append(f"{tool_name}")
if content and isinstance(content, str):
# Skip system/command messages
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({
'role': 'user',
'content': content,
'line': line_num,
'session': session_file.stem[:8]
})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
elif tool_name == 'AskUserQuestion':
tool_uses.append("AskUserQuestion")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': line_num,
'session': session_file.stem[:8]
})
except Exception:
pass
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
@@ -183,82 +142,54 @@ def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 2:
if len(sessions) < 1:
return
# Skip the current session (most recently modified = index 0)
previous_sessions = sessions[1:]
# Find the most recent planning file update across ALL previous sessions
# Sessions are sorted newest first, so we scan in order
update_session = None
update_line = -1
update_file = None
update_session_idx = -1
for idx, session in enumerate(previous_sessions):
line, filename = scan_for_planning_update(session)
if line >= 0:
update_session = session
update_line = line
update_file = filename
update_session_idx = idx
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not update_session:
# No planning file updates found in any previous session
if not target_session:
return
# Collect ALL messages from the update point forward, across all sessions
all_messages = []
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# 1. Get messages from the session with the update (after the update line)
messages_from_update_session = extract_messages_from_session(update_session, after_line=update_line)
all_messages.extend(messages_from_update_session)
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
return
# 2. Get ALL messages from sessions between update_session and current
# These are sessions[1:update_session_idx] (newer than update_session)
intermediate_sessions = previous_sessions[:update_session_idx]
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
# Process from oldest to newest for correct chronological order
for session in reversed(intermediate_sessions):
messages = extract_messages_from_session(session, after_line=-1) # Get all messages
all_messages.extend(messages)
if not all_messages:
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")
print(f"Previous session: {target_session.stem}")
sessions_covered = update_session_idx + 1
if sessions_covered > 1:
print(f"Scanning {sessions_covered} sessions for unsynced context")
print(f"Unsynced messages: {len(all_messages)}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
# Show up to 100 messages
MAX_MESSAGES = 100
if len(all_messages) > MAX_MESSAGES:
print(f"(Showing last {MAX_MESSAGES} of {len(all_messages)} messages)\n")
messages_to_show = all_messages[-MAX_MESSAGES:]
else:
messages_to_show = all_messages
current_session = None
for msg in messages_to_show:
# Show session marker when it changes
if msg.get('session') != current_session:
current_session = msg.get('session')
print(f"\n[Session: {current_session}...]")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
@@ -27,7 +27,7 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
SCRIPT_DIR="${CODEBUDDY_PLUGIN_ROOT:-$HOME/.codebuddy/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
@@ -63,7 +63,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
$(command -v python3 || command -v python) ${CODEBUDDY_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```
```powershell
@@ -79,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `${CODEBUDDY_PLUGIN_ROOT}/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`${CODEBUDDY_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -19,12 +19,12 @@ PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
"""Convert project path to CodeBuddy's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
return Path.home() / '.codebuddy' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
@@ -146,6 +146,9 @@ def main():
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
@@ -168,11 +171,12 @@ def main():
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# Only output if there's unsynced content
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
@@ -181,11 +185,8 @@ def main():
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
@@ -193,7 +194,7 @@ def main():
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
print(f"CODEBUDDY: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
+4 -4
View File
@@ -27,7 +27,7 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
SCRIPT_DIR="${CODEX_SKILL_ROOT:-$HOME/.codex/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
@@ -63,7 +63,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
$(command -v python3 || command -v python) ~/.codex/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
@@ -79,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `~/.codex/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`~/.codex/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -146,6 +146,9 @@ def main():
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
@@ -168,11 +171,12 @@ def main():
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# Only output if there's unsynced content
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
@@ -181,11 +185,8 @@ def main():
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -188,7 +188,7 @@ Success!
## The Read-Before-Decide Pattern
Always read your plan before major decisions:
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
@@ -170,7 +170,7 @@ Manus operates in a continuous 7-step loop:
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After any discovery | After viewing images/PDFs |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
@@ -178,11 +178,11 @@ Manus operates in a continuous 7-step loop:
## Critical Constraints
- Single-action execution: one tool call per turn
- Plan is required: always know goal, current phase, remaining phases
- Files are memory: context is volatile; filesystem is persistent
- Never repeat failures: if action failed, next action must be different
- Communication is a tool: message types include info, ask, result
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -142,17 +142,23 @@ def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
@@ -165,25 +171,25 @@ def main():
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]:
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
+26
View File
@@ -0,0 +1,26 @@
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": ".cursor/hooks/pre-tool-use.sh",
"matcher": "Write|Edit|Shell|Read",
"timeout": 5
}
],
"postToolUse": [
{
"command": ".cursor/hooks/post-tool-use.sh",
"matcher": "Write|Edit",
"timeout": 5
}
],
"stop": [
{
"command": ".cursor/hooks/stop.sh",
"timeout": 10,
"loop_limit": 3
}
]
}
}
+26
View File
@@ -0,0 +1,26 @@
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "powershell -ExecutionPolicy Bypass -File .cursor/hooks/pre-tool-use.ps1",
"matcher": "Write|Edit|Shell|Read",
"timeout": 5
}
],
"postToolUse": [
{
"command": "powershell -ExecutionPolicy Bypass -File .cursor/hooks/post-tool-use.ps1",
"matcher": "Write|Edit",
"timeout": 5
}
],
"stop": [
{
"command": "powershell -ExecutionPolicy Bypass -File .cursor/hooks/stop.ps1",
"timeout": 10,
"loop_limit": 3
}
]
}
}
+5
View File
@@ -0,0 +1,5 @@
# planning-with-files: Post-tool-use hook for Cursor (PowerShell)
# Reminds the agent to update task_plan.md after file modifications.
Write-Output "[planning-with-files] File updated. If this completes a phase, update task_plan.md status."
exit 0
+6
View File
@@ -0,0 +1,6 @@
#!/bin/bash
# planning-with-files: Post-tool-use hook for Cursor
# Reminds the agent to update task_plan.md after file modifications.
echo "[planning-with-files] File updated. If this completes a phase, update task_plan.md status."
exit 0
+12
View File
@@ -0,0 +1,12 @@
# planning-with-files: Pre-tool-use hook for Cursor (PowerShell)
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Returns {"decision": "allow"} — this hook never blocks tools.
$PlanFile = "task_plan.md"
if (Test-Path $PlanFile) {
Get-Content $PlanFile -TotalCount 30 | Write-Host
}
Write-Output '{"decision": "allow"}'
exit 0
+14
View File
@@ -0,0 +1,14 @@
#!/bin/bash
# planning-with-files: Pre-tool-use hook for Cursor
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Returns {"decision": "allow"} — this hook never blocks tools.
PLAN_FILE="task_plan.md"
if [ -f "$PLAN_FILE" ]; then
# Log plan context to stderr (visible in Cursor's hook logs)
head -30 "$PLAN_FILE" >&2
fi
echo '{"decision": "allow"}'
exit 0
+33
View File
@@ -0,0 +1,33 @@
# planning-with-files: Stop hook for Cursor (PowerShell)
# Checks if all phases in task_plan.md are complete.
# Returns followup_message to auto-continue if phases are incomplete.
# Always exits 0 — uses JSON stdout for control.
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
exit 0
}
$content = Get-Content $PlanFile -Raw
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
exit 0
} else {
Write-Host "{`"followup_message`": `"[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Read task_plan.md and continue working on the remaining phases.`"}"
exit 0
}
+42
View File
@@ -0,0 +1,42 @@
#!/bin/bash
# planning-with-files: Stop hook for Cursor
# Checks if all phases in task_plan.md are complete.
# Returns followup_message to auto-continue if phases are incomplete.
# Always exits 0 — uses JSON stdout for control.
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
# No plan file = no planning session, allow stop
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
# All phases complete, allow stop
exit 0
else
# Phases incomplete — auto-continue via followup_message
echo "{\"followup_message\": \"[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Read task_plan.md and continue working on the remaining phases.\"}"
exit 0
fi
+4 -4
View File
@@ -27,7 +27,7 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
SCRIPT_DIR="${CURSOR_SKILL_ROOT:-.cursor/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
@@ -63,7 +63,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
$(command -v python3 || command -v python) .cursor/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
@@ -79,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `.cursor/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`.cursor/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,209 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
+37
View File
@@ -0,0 +1,37 @@
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": ".github/hooks/scripts/session-start.sh",
"powershell": ".github/hooks/scripts/session-start.ps1",
"timeout": 15
}
],
"preToolUse": [
{
"type": "command",
"bash": ".github/hooks/scripts/pre-tool-use.sh",
"powershell": ".github/hooks/scripts/pre-tool-use.ps1",
"timeout": 5
}
],
"postToolUse": [
{
"type": "command",
"bash": ".github/hooks/scripts/post-tool-use.sh",
"powershell": ".github/hooks/scripts/post-tool-use.ps1",
"timeout": 5
}
],
"agentStop": [
{
"type": "command",
"bash": ".github/hooks/scripts/agent-stop.sh",
"powershell": ".github/hooks/scripts/agent-stop.ps1",
"timeout": 10
}
]
}
}
+46
View File
@@ -0,0 +1,46 @@
# planning-with-files: Agent stop hook for GitHub Copilot (PowerShell)
# Checks if all phases in task_plan.md are complete.
# Injects continuation context if phases are incomplete.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
$InputData = [Console]::In.ReadToEnd()
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
Write-Output '{}'
exit 0
}
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Output '{}'
exit 0
}
$msg = "[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Read task_plan.md and continue working on the remaining phases."
$output = @{
hookSpecificOutput = @{
hookEventName = "AgentStop"
additionalContext = $msg
}
}
$output | ConvertTo-Json -Depth 3 -Compress
exit 0
+45
View File
@@ -0,0 +1,45 @@
#!/bin/bash
# planning-with-files: Agent stop hook for GitHub Copilot
# Checks if all phases in task_plan.md are complete.
# Injects continuation context if phases are incomplete.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
echo '{}'
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo '{}'
exit 0
fi
MSG="[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Read task_plan.md and continue working on the remaining phases."
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"AgentStop\",\"additionalContext\":\"$MSG\"}}"
exit 0
+15
View File
@@ -0,0 +1,15 @@
# planning-with-files: Post-tool-use hook for GitHub Copilot (PowerShell)
# Reminds the agent to update task_plan.md after tool use.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
$InputData = [Console]::In.ReadToEnd()
$output = @{
hookSpecificOutput = @{
hookEventName = "PostToolUse"
additionalContext = "[planning-with-files] File updated. If this completes a phase, update task_plan.md status."
}
}
$output | ConvertTo-Json -Depth 3 -Compress
exit 0
+10
View File
@@ -0,0 +1,10 @@
#!/bin/bash
# planning-with-files: Post-tool-use hook for GitHub Copilot
# Reminds the agent to update task_plan.md after tool use.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"[planning-with-files] File updated. If this completes a phase, update task_plan.md status."}}'
exit 0
+31
View File
@@ -0,0 +1,31 @@
# planning-with-files: Pre-tool-use hook for GitHub Copilot (PowerShell)
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Always allows tool execution — this hook never blocks tools.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
$InputData = [Console]::In.ReadToEnd()
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
Write-Output '{}'
exit 0
}
$Context = (Get-Content $PlanFile -TotalCount 30 -ErrorAction SilentlyContinue) -join "`n"
if (-not $Context) {
Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
exit 0
}
$output = @{
hookSpecificOutput = @{
hookEventName = "PreToolUse"
permissionDecision = "allow"
additionalContext = $Context
}
}
$output | ConvertTo-Json -Depth 3 -Compress
exit 0
+29
View File
@@ -0,0 +1,29 @@
#!/bin/bash
# planning-with-files: Pre-tool-use hook for GitHub Copilot
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Always allows tool execution — this hook never blocks tools.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
echo '{}'
exit 0
fi
CONTEXT=$(head -30 "$PLAN_FILE" 2>/dev/null || echo "")
if [ -z "$CONTEXT" ]; then
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
exit 0
fi
# Escape context for JSON
PYTHON=$(command -v python3 || command -v python)
ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo "\"\"")
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":$ESCAPED}}"
exit 0
+48
View File
@@ -0,0 +1,48 @@
# planning-with-files: Session start hook for GitHub Copilot (PowerShell)
# When task_plan.md exists: runs session-catchup or reads plan header.
# When task_plan.md doesn't exist: injects SKILL.md so Copilot knows the planning workflow.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
$InputData = [Console]::In.ReadToEnd()
$PlanFile = "task_plan.md"
$SkillDir = ".github/skills/planning-with-files"
if (Test-Path $PlanFile) {
# Plan exists — try session catchup, fall back to reading plan header
$Catchup = ""
if (Test-Path "$SkillDir/scripts/session-catchup.py") {
try {
$PythonCmd = if (Get-Command python3 -ErrorAction SilentlyContinue) { "python3" } else { "python" }
$Catchup = & $PythonCmd "$SkillDir/scripts/session-catchup.py" (Get-Location).Path 2>$null
} catch {
$Catchup = ""
}
}
if ($Catchup) {
$Context = $Catchup -join "`n"
} else {
$Context = (Get-Content $PlanFile -TotalCount 5 -ErrorAction SilentlyContinue) -join "`n"
}
} else {
# No plan yet — inject SKILL.md so Copilot knows the planning workflow and templates
if (Test-Path "$SkillDir/SKILL.md") {
$Context = Get-Content "$SkillDir/SKILL.md" -Raw -ErrorAction SilentlyContinue
}
}
if (-not $Context) {
Write-Output '{}'
exit 0
}
$output = @{
hookSpecificOutput = @{
hookEventName = "SessionStart"
additionalContext = $Context
}
}
$output | ConvertTo-Json -Depth 3 -Compress
exit 0
+42
View File
@@ -0,0 +1,42 @@
#!/bin/bash
# planning-with-files: Session start hook for GitHub Copilot
# When task_plan.md exists: runs session-catchup or reads plan header.
# When task_plan.md doesn't exist: injects SKILL.md so Copilot knows the planning workflow.
# Always exits 0 — outputs JSON to stdout.
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
PLAN_FILE="task_plan.md"
SKILL_DIR=".github/skills/planning-with-files"
PYTHON=$(command -v python3 || command -v python)
if [ -f "$PLAN_FILE" ]; then
# Plan exists — try session catchup, fall back to reading plan header
CATCHUP=""
if [ -n "$PYTHON" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
CATCHUP=$($PYTHON "$SKILL_DIR/scripts/session-catchup.py" "$(pwd)" 2>/dev/null)
fi
if [ -n "$CATCHUP" ]; then
CONTEXT="$CATCHUP"
else
CONTEXT=$(head -5 "$PLAN_FILE" 2>/dev/null || echo "")
fi
else
# No plan yet — inject SKILL.md so Copilot knows the planning workflow and templates
if [ -f "$SKILL_DIR/SKILL.md" ]; then
CONTEXT=$(cat "$SKILL_DIR/SKILL.md" 2>/dev/null || echo "")
fi
fi
if [ -z "$CONTEXT" ]; then
echo '{}'
exit 0
fi
# Escape context for JSON
ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo "\"\"")
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$ESCAPED}}"
exit 0
+6
View File
@@ -21,6 +21,12 @@ notes.md
!examples/**/*.md
!**/templates/*.md
# ClawdHub publish folder (managed separately)
clawdhub-publish/
# Claude session files
.claude/
# Keep the skill folder clean
*.log
*.tmp
@@ -27,7 +27,7 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
SCRIPT_DIR="${KILOCODE_SKILL_ROOT:-$HOME/.kilocode/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
@@ -63,7 +63,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
$(command -v python3 || command -v python) ~/.kilocode/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
@@ -79,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `~/.kilocode/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`~/.kilocode/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
+26 -24
View File
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
+24 -22
View File
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -1,42 +0,0 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
@@ -1,44 +0,0 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
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)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
@@ -4,7 +4,7 @@ version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
homepage: https://github.com/OthmanAdi/planning-with-files
user-invocable: true
metadata: {"moltbot":{"os":["darwin","linux","win32"]}}
metadata: {"openclaw":{"os":["darwin","linux","win32"]}}
---
# Planning with Files
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,209 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
@@ -27,7 +27,7 @@ hooks:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
SCRIPT_DIR="${OPENCODE_SKILL_ROOT:-$HOME/.config/opencode/skills/planning-with-files}/scripts"
IS_WINDOWS=0
if [ "${OS-}" = "Windows_NT" ]; then
@@ -63,7 +63,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
```bash
# Linux/macOS (auto-detects python3 or python)
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
$(command -v python3 || command -v python) ~/.config/opencode/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"
```
```powershell
@@ -79,12 +79,12 @@ If catchup report shows unsynced context:
## Important: Where Files Go
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
- **Templates** are in `~/.config/opencode/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
| Skill directory (`~/.config/opencode/skills/planning-with-files/`) | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,269 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to OpenCode's storage path format."""
# Normalize to an absolute path to ensure a stable representation
# .as_posix() handles '\' -> '/' conversion on Windows automatically
resolved_str = Path(project_path).resolve().as_posix()
# Sanitize path: replace separators with '-', remove ':' (Windows drives)
sanitized = resolved_str.replace('/', '-').replace(':', '')
# Apply legacy naming convention: leading '-' and '_' -> '-'
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized_name = sanitized.replace('_', '-')
# 1. Check Legacy Location first (~/.opencode/sessions/...)
legacy_dir = Path.home() / '.opencode' / 'sessions' / sanitized_name
if legacy_dir.is_dir():
return legacy_dir
# 2. Standard Layout
data_root_env = os.getenv('OPENCODE_DATA_DIR')
if data_root_env:
data_root = Path(data_root_env)
else:
# Respect XDG_DATA_HOME if set, otherwise use default
xdg_root = os.getenv('XDG_DATA_HOME')
if xdg_root:
data_root = Path(xdg_root) / 'opencode' / 'storage'
else:
data_root = Path.home() / '.local' / 'share' / 'opencode' / 'storage'
return data_root / 'session' / sanitized_name
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
# Support both legacy JSONL (*.jsonl) and standard JSON (*.json) session files.
sessions = list(project_dir.glob('*.jsonl')) + list(project_dir.glob('*.json'))
# Deduplicate in case of overlaps and filter out agent-specific sessions.
unique_sessions = {s for s in sessions}
main_sessions = [s for s in unique_sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages: List[Dict] = []
# First, try to parse the entire file as JSON (for *.json session files).
try:
with open(session_file, 'r') as f:
content = f.read()
if content.strip():
data = json.loads(content)
if isinstance(data, list):
for idx, item in enumerate(data):
if isinstance(item, dict):
item['_line_num'] = idx
messages.append(item)
elif isinstance(data, dict):
# Some formats may wrap messages in a top-level object.
msg_list = data.get('messages')
if isinstance(msg_list, list):
for idx, item in enumerate(msg_list):
if isinstance(item, dict):
item['_line_num'] = idx
messages.append(item)
except json.JSONDecodeError:
# Fall through to JSONL parsing if full-file JSON parsing fails.
messages = []
if messages:
return messages
# Fallback: treat file as JSONL (one JSON object per line), the original behavior.
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
if isinstance(data, dict):
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
# Ignore malformed lines to be resilient to partial writes.
# Some session log lines may be incomplete or non-JSON; skip them
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"OPENCODE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
+81
View File
@@ -0,0 +1,81 @@
# Pi Planning With Files
> **Work like Manus** — Use persistent markdown files as your "working memory on disk."
A [Pi Coding Agent](https://pi.dev) skill that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage.
## The Problem
Most AI agents suffer from:
- **Volatile memory** — Context resets lose history
- **Goal drift** — Long tasks lose focus
- **Hidden errors** — Failures aren't tracked
## The Solution
For every complex task, create THREE files:
- `task_plan.md` (Phases & Progress)
- `findings.md` (Research & Notes)
- `progress.md` (Session Log)
---
## Installation
### Pi Install
```bash
pi install npm:pi-planning-with-files
```
### Manual Install
1. Navigate to your project root.
2. Create the `.pi/skills` directory if it doesn't exist.
3. Copy the `planning-with-files` skill folder into `.pi/skills/`.
---
## Usage
Pi Agent automatically discovers skills in `.pi/skills` or installed via NPM.
### Start Planning
Ask Pi:
```
Use the planning-with-files skill to help me with this task.
```
Or:
```
Start by creating task_plan.md.
```
## Important Limitations
> **Note:** Hooks (PreToolUse, PostToolUse, Stop) are **Claude Code specific** and are not currently supported in Pi Agent.
### What works in Pi Agent:
- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- All planning rules and guidelines
- The 2-Action Rule
- The 3-Strike Error Protocol
- Session Recovery (via `session-catchup.py`)
### Session Recovery
If you clear context, recover your state:
```bash
python3 .pi/skills/planning-with-files/scripts/session-catchup.py .
```
## File Structure
When installed, the skill provides templates to create:
```
your-project/
├── task_plan.md
├── findings.md
├── progress.md
```
+204
View File
@@ -0,0 +1,204 @@
---
name: pi-planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls
---
# Planning with Files
Work like Manus: Use persistent markdown files as your "working memory on disk."
## FIRST: Check for Previous Session
**Before starting work**, check for unsynced context from a previous session:
> **Note:** The `scripts/` directory is inside this skill's installation folder.
```bash
# Linux/macOS
python scripts/session-catchup.py "$(pwd)"
```
```powershell
# Windows PowerShell
python scripts\session-catchup.py" (Get-Location)
```
**If you cannot find the script:**
Ask Pi to locate it for you:
`Run the session-catchup.py script from the planning-with-files skill`
If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task
## Important: Where Files Go
- **Templates** are in `templates/` inside this skill
- **Your planning files** go in **your project directory**
| Location | What Goes There |
|----------|-----------------|
| Skill directory | Templates, scripts, reference docs |
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
## Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## File Purposes
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Critical Rules
### 1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
### 2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
### 6. Never Repeat Failures
```
if action_failed:
next_action != same_action
```
Track what you tried. Mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
## The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source |
|----------|---------------|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
- Anything requiring organization
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Templates
Copy these templates to start:
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
- [templates/findings.md](templates/findings.md) — Research storage
- [templates/progress.md](templates/progress.md) — Session logging
## Scripts
Helper scripts for automation:
- `scripts/init-session.sh` — Initialize all planning files
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
- **Real Examples:** See [examples.md](examples.md)
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create task_plan.md file |
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in skill directory | Create files in your project |
+202
View File
@@ -0,0 +1,202 @@
# Examples: Planning with Files in Action
## Example 1: Research Task
**User Request:** "Research the benefits of morning exercise and write a summary"
### Loop 1: Create Plan
```bash
Write task_plan.md
```
```markdown
# Task Plan: Morning Exercise Benefits Research
## Goal
Create a research summary on the benefits of morning exercise.
## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary
## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?
## Status
**Currently in Phase 1** - Creating plan
```
### Loop 2: Research
```bash
Read task_plan.md # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md # Store findings
Edit task_plan.md # Mark Phase 2 complete
```
### Loop 3: Synthesize
```bash
Read task_plan.md # Refresh goals
Read notes.md # Get findings
Write morning_exercise_summary.md
Edit task_plan.md # Mark Phase 3 complete
```
### Loop 4: Deliver
```bash
Read task_plan.md # Verify complete
Deliver morning_exercise_summary.md
```
---
## Example 2: Bug Fix Task
**User Request:** "Fix the login bug in the authentication module"
### task_plan.md
```markdown
# Task Plan: Fix Login Bug
## Goal
Identify and fix the bug preventing successful login.
## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify
## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?
## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function
## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
→ Root cause: user object not awaited properly
## Status
**Currently in Phase 3** - Found root cause, preparing fix
```
---
## Example 3: Feature Development
**User Request:** "Add a dark mode toggle to the settings page"
### The 3-File Pattern in Action
**task_plan.md:**
```markdown
# Task Plan: Dark Mode Toggle
## Goal
Add functional dark mode toggle to settings.
## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish
## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx
## Status
**Currently in Phase 3** - Building toggle component
```
**notes.md:**
```markdown
# Notes: Dark Mode Implementation
## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only
## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider
## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea
```
**dark_mode_implementation.md:** (deliverable)
```markdown
# Dark Mode Implementation
## Changes Made
### 1. Added dark theme colors
File: src/styles/theme.ts
...
### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...
```
---
## Example 4: Error Recovery Pattern
When something fails, DON'T hide it:
### Before (Wrong)
```
Action: Read config.json
Error: File not found
Action: Read config.json # Silent retry
Action: Read config.json # Another retry
```
### After (Correct)
```
Action: Read config.json
Error: File not found
# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config
Action: Write config.json (default config)
Action: Read config.json
Success!
```
---
## The Read-Before-Decide Pattern
**Always read your plan before major decisions:**
```
[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]
→ Read task_plan.md # This brings goals back into attention!
→ Now make the decision # Goals are fresh in context
```
This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.
@@ -0,0 +1,35 @@
{
"name": "pi-planning-with-files",
"version": "1.0.1",
"description": "Manus-style file-based planning for Pi Coding Agent",
"keywords": [
"pi-package",
"planning",
"manus",
"agent",
"pi-skill"
],
"pi": {
"skills": [
"SKILL.md"
]
},
"files": [
"README.md",
"SKILL.md",
"examples.md",
"reference.md",
"scripts/",
"templates/"
],
"repository": {
"type": "git",
"url": "git+https://github.com/ttttmr/planning-with-files.git"
},
"author": "",
"license": "MIT",
"bugs": {
"url": "https://github.com/ttttmr/planning-with-files/issues"
},
"homepage": "https://github.com/ttttmr/planning-with-files#readme"
}
+218
View File
@@ -0,0 +1,218 @@
# Reference: Manus Context Engineering Principles
This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
## The 6 Manus Principles
### Principle 1: Design Around KV-Cache
> "KV-cache hit rate is THE single most important metric for production AI agents."
**Statistics:**
- ~100:1 input-to-output token ratio
- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
- 10x cost difference!
**Implementation:**
- Keep prompt prefixes STABLE (single-token change invalidates cache)
- NO timestamps in system prompts
- Make context APPEND-ONLY with deterministic serialization
### Principle 2: Mask, Don't Remove
Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
### Principle 3: Filesystem as External Memory
> "Markdown is my 'working memory' on disk."
**The Formula:**
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
```
**Compression Must Be Restorable:**
- Keep URLs even if web content is dropped
- Keep file paths when dropping document contents
- Never lose the pointer to full data
### Principle 4: Manipulate Attention Through Recitation
> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
```
Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]
```
### Principle 5: Keep the Wrong Stuff In
> "Leave the wrong turns in the context."
**Why:**
- Failed actions with stack traces let model implicitly update beliefs
- Reduces mistake repetition
- Error recovery is "one of the clearest signals of TRUE agentic behavior"
### Principle 6: Don't Get Few-Shotted
> "Uniformity breeds fragility."
**Problem:** Repetitive action-observation pairs cause drift and hallucination.
**Solution:** Introduce controlled variation:
- Vary phrasings slightly
- Don't copy-paste patterns blindly
- Recalibrate on repetitive tasks
---
## The 3 Context Engineering Strategies
Based on Lance Martin's analysis of Manus architecture.
### Strategy 1: Context Reduction
**Compaction:**
```
Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only
RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)
```
**Summarization:**
- Applied when compaction reaches diminishing returns
- Generated using full tool results
- Creates standardized summary objects
### Strategy 2: Context Isolation (Multi-Agent)
**Architecture:**
```
┌─────────────────────────────────┐
│ PLANNER AGENT │
│ └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│ KNOWLEDGE MANAGER │
│ └─ Reviews conversations │
│ └─ Determines filesystem store │
├─────────────────────────────────┤
│ EXECUTOR SUB-AGENTS │
│ └─ Perform assigned tasks │
│ └─ Have own context windows │
└─────────────────────────────────┘
```
**Key Insight:** Manus originally used `todo.md` for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.
### Strategy 3: Context Offloading
**Tool Design:**
- Use <20 atomic functions total
- Store full results in filesystem, not context
- Use `glob` and `grep` for searching
- Progressive disclosure: load information only as needed
---
## The Agent Loop
Manus operates in a continuous 7-step loop:
```
┌─────────────────────────────────────────┐
│ 1. ANALYZE CONTEXT │
│ - Understand user intent │
│ - Assess current state │
│ - Review recent observations │
├─────────────────────────────────────────┤
│ 2. THINK │
│ - Should I update the plan? │
│ - What's the next logical action? │
│ - Are there blockers? │
├─────────────────────────────────────────┤
│ 3. SELECT TOOL │
│ - Choose ONE tool │
│ - Ensure parameters available │
├─────────────────────────────────────────┤
│ 4. EXECUTE ACTION │
│ - Tool runs in sandbox │
├─────────────────────────────────────────┤
│ 5. RECEIVE OBSERVATION │
│ - Result appended to context │
├─────────────────────────────────────────┤
│ 6. ITERATE │
│ - Return to step 1 │
│ - Continue until complete │
├─────────────────────────────────────────┤
│ 7. DELIVER OUTCOME │
│ - Send results to user │
│ - Attach all relevant files │
└─────────────────────────────────────────┘
```
---
## File Types Manus Creates
| File | Purpose | When Created | When Updated |
|------|---------|--------------|--------------|
| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
| Code files | Implementation | Before execution | After errors |
---
## Critical Constraints
- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
- **Files are Memory:** Context = volatile. Filesystem = persistent.
- **Never Repeat Failures:** If action failed, next action MUST be different
- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
---
## Manus Statistics
| Metric | Value |
|--------|-------|
| Average tool calls per task | ~50 |
| Input-to-output token ratio | 100:1 |
| Acquisition price | $2 billion |
| Time to $100M revenue | 8 months |
| Framework refactors since launch | 5 times |
---
## Key Quotes
> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
> "Error recovery is one of the clearest signals of TRUE agentic behavior."
> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
> "Leave the wrong turns in the context."
---
## Source
Based on Manus's official context engineering documentation:
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
@@ -0,0 +1,44 @@
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
# Read file content
$content = Get-Content $PlanFile -Raw
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -0,0 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
+209
View File
@@ -0,0 +1,209 @@
#!/usr/bin/env python3
"""
Session Catchup Script for planning-with-files
Analyzes the previous session to find unsynced context after the last
planning file update. Designed to run on SessionStart.
Usage: python3 session-catchup.py [project-path]
"""
import json
import sys
import os
from pathlib import Path
from typing import List, Dict, Optional, Tuple
from datetime import datetime
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
sanitized = '-' + sanitized
sanitized = sanitized.replace('_', '-')
return Path.home() / '.claude' / 'projects' / sanitized
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
data['_line_num'] = line_num
messages.append(data)
except json.JSONDecodeError:
pass
return messages
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
Find the last time a planning file was written/edited.
Returns (line_number, filename) or (-1, None) if not found.
"""
last_update_line = -1
last_update_file = None
for msg in messages:
msg_type = msg.get('type')
if msg_type == 'assistant':
content = msg.get('message', {}).get('content', [])
if isinstance(content, list):
for item in content:
if item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
return last_update_line, last_update_file
def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
"""Extract conversation messages after a certain line number."""
result = []
for msg in messages:
if msg['_line_num'] <= after_line:
continue
msg_type = msg.get('type')
is_meta = msg.get('isMeta', False)
if msg_type == 'user' and not is_meta:
content = msg.get('message', {}).get('content', '')
if isinstance(content, list):
for item in content:
if isinstance(item, dict) and item.get('type') == 'text':
content = item.get('text', '')
break
else:
content = ''
if content and isinstance(content, str):
if content.startswith(('<local-command', '<command-', '<task-notification')):
continue
if len(content) > 20:
result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
elif msg_type == 'assistant':
msg_content = msg.get('message', {}).get('content', '')
text_content = ''
tool_uses = []
if isinstance(msg_content, str):
text_content = msg_content
elif isinstance(msg_content, list):
for item in msg_content:
if item.get('type') == 'text':
text_content = item.get('text', '')
elif item.get('type') == 'tool_use':
tool_name = item.get('name', '')
tool_input = item.get('input', {})
if tool_name == 'Edit':
tool_uses.append(f"Edit: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Write':
tool_uses.append(f"Write: {tool_input.get('file_path', 'unknown')}")
elif tool_name == 'Bash':
cmd = tool_input.get('command', '')[:80]
tool_uses.append(f"Bash: {cmd}")
else:
tool_uses.append(f"{tool_name}")
if text_content or tool_uses:
result.append({
'role': 'assistant',
'content': text_content[:600] if text_content else '',
'tools': tool_uses,
'line': msg['_line_num']
})
return result
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Check if planning files exist (indicates active task)
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
return
sessions = get_sessions_sorted(project_dir)
if len(sessions) < 1:
return
# Find a substantial previous session
target_session = None
for session in sessions:
if session.stat().st_size > 5000:
target_session = session
break
if not target_session:
return
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages
if msg['role'] == 'user':
print(f"USER: {msg['content'][:300]}")
else:
if msg.get('content'):
print(f"CLAUDE: {msg['content'][:300]}")
if msg.get('tools'):
print(f" Tools: {', '.join(msg['tools'][:4])}")
print("\n--- RECOMMENDED ---")
print("1. Run: git diff --stat")
print("2. Read: task_plan.md, progress.md, findings.md")
print("3. Update planning files based on above context")
print("4. Continue with task")
if __name__ == '__main__':
main()
@@ -0,0 +1,95 @@
# Findings & Decisions
<!--
WHAT: Your knowledge base for the task. Stores everything you discover and decide.
WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
-->
## Requirements
<!--
WHAT: What the user asked for, broken down into specific requirements.
WHY: Keeps requirements visible so you don't forget what you're building.
WHEN: Fill this in during Phase 1 (Requirements & Discovery).
EXAMPLE:
- Command-line interface
- Add tasks
- List all tasks
- Delete tasks
- Python implementation
-->
<!-- Captured from user request -->
-
## Research Findings
<!--
WHAT: Key discoveries from web searches, documentation reading, or exploration.
WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
EXAMPLE:
- Python's argparse module supports subcommands for clean CLI design
- JSON module handles file persistence easily
- Standard pattern: python script.py <command> [args]
-->
<!-- Key discoveries during exploration -->
-
## Technical Decisions
<!--
WHAT: Architecture and implementation choices you've made, with reasoning.
WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
WHEN: Update whenever you make a significant technical choice.
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
| argparse with subcommands | Clean CLI: python todo.py add "task" |
-->
<!-- Decisions made with rationale -->
| Decision | Rationale |
|----------|-----------|
| | |
## Issues Encountered
<!--
WHAT: Problems you ran into and how you solved them.
WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
WHEN: Document when you encounter blockers or unexpected challenges.
EXAMPLE:
| Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
-->
<!-- Errors and how they were resolved -->
| Issue | Resolution |
|-------|------------|
| | |
## Resources
<!--
WHAT: URLs, file paths, API references, documentation links you've found useful.
WHY: Easy reference for later. Don't lose important links in context.
WHEN: Add as you discover useful resources.
EXAMPLE:
- Python argparse docs: https://docs.python.org/3/library/argparse.html
- Project structure: src/main.py, src/utils.py
-->
<!-- URLs, file paths, API references -->
-
## Visual/Browser Findings
<!--
WHAT: Information you learned from viewing images, PDFs, or browser results.
WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
EXAMPLE:
- Screenshot shows login form has email and password fields
- Browser shows API returns JSON with "status" and "data" keys
-->
<!-- CRITICAL: Update after every 2 view/browser operations -->
<!-- Multimodal content must be captured as text immediately -->
-
---
<!--
REMINDER: The 2-Action Rule
After every 2 view/browser/search operations, you MUST update this file.
This prevents visual information from being lost when context resets.
-->
*Update this file after every 2 view/browser/search operations*
*This prevents visual information from being lost*
@@ -0,0 +1,114 @@
# Progress Log
<!--
WHAT: Your session log - a chronological record of what you did, when, and what happened.
WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
-->
## Session: [DATE]
<!--
WHAT: The date of this work session.
WHY: Helps track when work happened, useful for resuming after time gaps.
EXAMPLE: 2026-01-15
-->
### Phase 1: [Title]
<!--
WHAT: Detailed log of actions taken during this phase.
WHY: Provides context for what was done, making it easier to resume or debug.
WHEN: Update as you work through the phase, or at least when you complete it.
-->
- **Status:** in_progress
- **Started:** [timestamp]
<!--
STATUS: Same as task_plan.md (pending, in_progress, complete)
TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
-->
- Actions taken:
<!--
WHAT: List of specific actions you performed.
EXAMPLE:
- Created todo.py with basic structure
- Implemented add functionality
- Fixed FileNotFoundError
-->
-
- Files created/modified:
<!--
WHAT: Which files you created or changed.
WHY: Quick reference for what was touched. Helps with debugging and review.
EXAMPLE:
- todo.py (created)
- todos.json (created by app)
- task_plan.md (updated)
-->
-
### Phase 2: [Title]
<!--
WHAT: Same structure as Phase 1, for the next phase.
WHY: Keep a separate log entry for each phase to track progress clearly.
-->
- **Status:** pending
- Actions taken:
-
- Files created/modified:
-
## Test Results
<!--
WHAT: Table of tests you ran, what you expected, what actually happened.
WHY: Documents verification of functionality. Helps catch regressions.
WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
EXAMPLE:
| Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
| List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
-->
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
| | | | | |
## Error Log
<!--
WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
| 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
-->
<!-- Keep ALL errors - they help avoid repetition -->
| Timestamp | Error | Attempt | Resolution |
|-----------|-------|---------|------------|
| | | 1 | |
## 5-Question Reboot Check
<!--
WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
WHEN: Update periodically, especially when resuming after a break or context reset.
THE 5 QUESTIONS:
1. Where am I? → Current phase in task_plan.md
2. Where am I going? → Remaining phases
3. What's the goal? → Goal statement in task_plan.md
4. What have I learned? → See findings.md
5. What have I done? → See progress.md (this file)
-->
<!-- If you can answer these, context is solid -->
| Question | Answer |
|----------|--------|
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
---
<!--
REMINDER:
- Update after completing each phase or encountering errors
- Be detailed - this is your "what happened" log
- Include timestamps for errors to track when issues occurred
-->
*Update after completing each phase or encountering errors*
@@ -0,0 +1,132 @@
# Task Plan: [Brief Description]
<!--
WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk."
WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh.
WHEN: Create this FIRST, before starting any work. Update after each phase completes.
-->
## Goal
<!--
WHAT: One clear sentence describing what you're trying to achieve.
WHY: This is your north star. Re-reading this keeps you focused on the end state.
EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality."
-->
[One sentence describing the end state]
## Current Phase
<!--
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
WHY: Quick reference for where you are in the task. Update this as you progress.
-->
Phase 1
## Phases
<!--
WHAT: Break your task into 3-7 logical phases. Each phase should be completable.
WHY: Breaking work into phases prevents overwhelm and makes progress visible.
WHEN: Update status after completing each phase: pending → in_progress → complete
-->
### Phase 1: Requirements & Discovery
<!--
WHAT: Understand what needs to be done and gather initial information.
WHY: Starting without understanding leads to wasted effort. This phase prevents that.
-->
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
<!--
STATUS VALUES:
- pending: Not started yet
- in_progress: Currently working on this
- complete: Finished this phase
-->
### Phase 2: Planning & Structure
<!--
WHAT: Decide how you'll approach the problem and what structure you'll use.
WHY: Good planning prevents rework. Document decisions so you remember why you chose them.
-->
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
<!--
WHAT: Actually build/create/write the solution.
WHY: This is where the work happens. Break into smaller sub-tasks if needed.
-->
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
<!--
WHAT: Verify everything works and meets requirements.
WHY: Catching issues early saves time. Document test results in progress.md.
-->
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
<!--
WHAT: Final review and handoff to user.
WHY: Ensures nothing is forgotten and deliverables are complete.
-->
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
<!--
WHAT: Important questions you need to answer during the task.
WHY: These guide your research and decision-making. Answer them as you go.
EXAMPLE:
1. Should tasks persist between sessions? (Yes - need file storage)
2. What format for storing tasks? (JSON file)
-->
1. [Question to answer]
2. [Question to answer]
## Decisions Made
<!--
WHAT: Technical and design decisions you've made, with the reasoning behind them.
WHY: You'll forget why you made choices. This table helps you remember and justify decisions.
WHEN: Update whenever you make a significant choice (technology, approach, structure).
EXAMPLE:
| Use JSON for storage | Simple, human-readable, built-in Python support |
-->
| Decision | Rationale |
|----------|-----------|
| | |
## Errors Encountered
<!--
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
WHY: Logging errors prevents repeating the same mistakes. This is critical for learning.
WHEN: Add immediately when an error occurs, even if you fix it quickly.
EXAMPLE:
| FileNotFoundError | 1 | Check if file exists, create empty list if not |
| JSONDecodeError | 2 | Handle empty file case explicitly |
-->
| Error | Attempt | Resolution |
|-------|---------|------------|
| | 1 | |
## Notes
<!--
REMINDERS:
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
- Never repeat a failed action - mutate your approach instead
-->
- Update phase status as you progress: pending → in_progress → complete
- Re-read this plan before major decisions (attention manipulation)
- Log ALL errors - they help avoid repetition
+57
View File
@@ -2,6 +2,63 @@
All notable changes to this project will be documented in this file.
## [2.16.0] - 2026-02-22
### Added
- **GitHub Copilot Support** (PR #80 by @lincolnwan)
- Native GitHub Copilot hooks integration (early 2026 hooks feature)
- Created `.github/hooks/planning-with-files.json` configuration
- Added full hook scripts in `.github/hooks/scripts/`
- Cross-platform support (bash + PowerShell)
- Added `docs/copilot.md` installation guide
- Added GitHub Copilot badge to README
- This brings total supported platforms to 15
### Thanks
- @lincolnwan for GitHub Copilot hooks support (PR #80)
---
## [2.14.0] - 2026-02-04
### Added
- **Pi Agent Support** (PR #67 by @ttttmr)
- Full Pi Agent (pi.dev) integration
- Created `.pi/skills/planning-with-files/` skill bundle
- Added `package.json` for NPM installation (`pi install npm:pi-planning-with-files`)
- Full templates, scripts, and references included
- Cross-platform support (macOS, Linux, Windows)
- Added `docs/pi-agent.md` installation guide
- Added Pi Agent badge to README
- Note: Hooks are Claude Code-specific and not supported in Pi Agent
### Fixed
- **Codex Skill Path References** (PR #66 by @codelyc)
- Replaced broken `CLAUDE_PLUGIN_ROOT` references with correct Codex paths (`~/.codex/skills/planning-with-files/`)
- Added missing template files to `.codex/skills/planning-with-files/templates/`
### Changed
- **OpenClaw Docs Update** (PR #65 by @AZLabsAI, fixes #64)
- Renamed `docs/moltbot.md` to `docs/openclaw.md`
- Updated all paths from `~/.clawdbot/` to `~/.openclaw/`
- Updated CLI commands from `moltbot` to `openclaw`
- Updated website link from `molt.bot` to `openclaw.ai`
- Updated README: Moltbot badge and references updated to OpenClaw
- Version badge updated to v2.14.0
### Thanks
- @ttttmr for Pi Agent integration (PR #67)
- @codelyc for Codex path fix (PR #66)
- @AZLabsAI for OpenClaw docs update (PR #65)
---
## [2.11.0] - 2026-01-26
### Added
+8 -2
View File
@@ -61,6 +61,12 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[@gydx6](https://github.com/gydx6)** - [PR #79](https://github.com/OthmanAdi/planning-with-files/pull/79)
- Fixed session-catchup false positives in all 9 skill-distributed copies
- Added early return guards for non-planning projects
- Thorough bug report with root cause analysis
- **Impact:** Eliminates noise from false catchup reports
- **[@tobrun](https://github.com/tobrun)** - [PR #3](https://github.com/OthmanAdi/planning-with-files/pull/3)
- Early directory structure improvements
- Helped identify optimal repository layout
@@ -112,6 +118,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 11+ and growing!
**Total Contributors:** 12+ and growing!
*Last updated: January 27, 2026*
*Last updated: February 21, 2026*
+166 -165
View File
@@ -2,12 +2,96 @@
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
## Thank You
[![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>
To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.
If this skill helps you work smarter, that's all I wanted.
</details>
<details open>
<summary><strong>🌍 See What the Community Built</strong></summary>
| Fork | Author | Features |
|------|--------|----------|
| [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 |
*Built something? [Open an issue](https://github.com/OthmanAdi/planning-with-files/issues) to get listed!*
</details>
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v2.16.0
| Version | Highlights |
|---------|------------|
| **v2.16.0** | GitHub Copilot hooks support (thanks @lincolnwan!) |
| **v2.15.1** | Session catchup false-positive fix (thanks @gydx6!) |
| **v2.15.0** | `/plan:status` command, OpenCode compatibility fix |
| **v2.14.0** | Pi Agent support, OpenClaw docs update, Codex path fix |
| **v2.11.0** | `/plan` command for easier autocomplete |
| **v2.10.0** | Kiro steering files support |
| **v2.7.0** | Gemini CLI support |
| **v2.2.0** | Session recovery, Windows PowerShell, OS-aware hooks |
[View all releases](https://github.com/OthmanAdi/planning-with-files/releases) · [CHANGELOG](CHANGELOG.md)
> 🧪 **Experimental:** Isolated parallel planning (`.planning/{uuid}/` folders) is being tested on [`experimental/isolated-planning`](https://github.com/OthmanAdi/planning-with-files/tree/experimental/isolated-planning). Try it and share feedback!
---
### Session Recovery
When your context fills up and you run `/clear`, this skill **automatically recovers** your previous session.
**How it works:**
1. Checks for previous session data in `~/.claude/projects/`
2. Finds when planning files were last updated
3. Extracts conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync
**Pro tip:** Disable auto-compact to maximize context before clearing:
```json
{ "autoCompact": false }
```
</details>
<details>
<summary><strong>🛠️ Supported IDEs (15 Platforms)</strong></summary>
| IDE | Status | Installation Guide | Format |
|-----|--------|-------------------|--------|
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
| Gemini CLI | ✅ Full Support | [Gemini Setup](docs/gemini.md) | Agent Skills |
| OpenClaw | ✅ Full Support | [OpenClaw Setup](docs/openclaw.md) | Workspace/Local Skills |
| Kiro | ✅ Full Support | [Kiro Setup](docs/kiro.md) | Steering Files |
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Skills + Hooks |
| Continue | ✅ Full Support | [Continue Setup](docs/continue.md) | Skills + Prompt files |
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Skills |
| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
| FactoryAI Droid | ✅ Full Support | [Factory Setup](docs/factory.md) | Workspace/Personal Skill |
| Antigravity | ✅ Full Support | [Antigravity Setup](docs/antigravity.md) | Workspace/Personal Skill |
| CodeBuddy | ✅ Full Support | [CodeBuddy Setup](docs/codebuddy.md) | Workspace/Personal Skill |
| AdaL CLI (Sylph AI) | ✅ Full Support | [AdaL Setup](docs/adal.md) | Personal/Project Skills |
| Pi Agent | ✅ Full Support | [Pi Agent Setup](docs/pi-agent.md) | Agent Skills |
| GitHub Copilot | ✅ Full Support | [Copilot Setup](docs/copilot.md) | Hooks |
> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.
</details>
---
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.
@@ -18,110 +102,45 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
[![Cursor Skills](https://img.shields.io/badge/Cursor-Skills-purple)](https://docs.cursor.com/context/skills)
[![Kilocode Skills](https://img.shields.io/badge/Kilocode-Skills-orange)](https://kilo.ai/docs/agent-behavior/skills)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Skills-4285F4)](https://geminicli.com/docs/cli/skills/)
[![Moltbot](https://img.shields.io/badge/Moltbot-Skills-FF6B6B)](https://docs.molt.bot/tools/skills)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skills-FF6B6B)](https://openclaw.ai)
[![Kiro](https://img.shields.io/badge/Kiro-Steering-00D4AA)](https://kiro.dev/docs/cli/steering/)
[![AdaL CLI](https://img.shields.io/badge/AdaL%20CLI-Skills-9B59B6)](https://docs.sylph.ai/features/plugins-and-skills)
[![Version](https://img.shields.io/badge/version-2.12.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![Pi Agent](https://img.shields.io/badge/Pi%20Agent-Skills-FF4081)](https://pi.dev)
[![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Hooks-000000)](https://docs.github.com/en/copilot/reference/hooks-configuration)
[![Version](https://img.shields.io/badge/version-2.16.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
```bash
# Install the plugin
claude plugins install OthmanAdi/planning-with-files
In Claude Code, run:
```
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```
That's it! Now use one of these commands in Claude Code:
| Command | Autocomplete | Description |
|---------|--------------|-------------|
| `/planning-with-files:plan` | Type `/plan` | Shorter command (v2.11.0+) |
| `/planning-with-files:start` | Type `/planning` | Original command |
| `/planning-with-files:plan` | Type `/plan` | Start planning session (v2.11.0+) |
| `/planning-with-files:status` | Type `/plan:status` | Show planning progress at a glance (v2.15.0+) |
| `/planning-with-files:start` | Type `/planning` | Original start command |
**Alternative:** If you want `/planning-with-files` (without prefix), copy skills to your local folder:
**macOS/Linux:**
```bash
# Optional: Copy skills for /planning-with-files command
cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
```
**Windows (PowerShell):**
```powershell
# Install the plugin
claude plugins install OthmanAdi/planning-with-files
# Optional: Copy skills for /planning-with-files command
Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
```
See [docs/installation.md](docs/installation.md) for all installation methods.
## Supported IDEs
| IDE | Status | Installation Guide | Format |
|-----|--------|-------------------|--------|
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
| Gemini CLI | ✅ Full Support | [Gemini Setup](docs/gemini.md) | Agent Skills |
| Moltbot | ✅ Full Support | [Moltbot Setup](docs/moltbot.md) | Workspace/Local Skills |
| Kiro | ✅ Full Support | [Kiro Setup](docs/kiro.md) | Steering Files |
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Skills |
| Continue | ✅ Full Support | [Continue Setup](docs/continue.md) | Skills + Prompt files |
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Skills |
| OpenCode | ✅ Full Support | [OpenCode Setup](docs/opencode.md) | Personal/Project Skill |
| Codex | ✅ Full Support | [Codex Setup](docs/codex.md) | Personal Skill |
| FactoryAI Droid | ✅ Full Support | [Factory Setup](docs/factory.md) | Workspace/Personal Skill |
| Antigravity | ✅ Full Support | [Antigravity Setup](docs/antigravity.md) | Workspace/Personal Skill |
| CodeBuddy | ✅ Full Support | [CodeBuddy Setup](docs/codebuddy.md) | Workspace/Personal Skill |
| AdaL CLI (Sylph AI) | ✅ Full Support | [AdaL Setup](docs/adal.md) | Personal/Project Skills |
> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.
## Documentation
| Document | Description |
|----------|-------------|
| [Installation Guide](docs/installation.md) | All installation methods (plugin, manual, Cursor, Windows) |
| [Quick Start](docs/quickstart.md) | 5-step guide to using the pattern |
| [Workflow Diagram](docs/workflow.md) | Visual diagram of how files and hooks interact |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Gemini CLI Setup](docs/gemini.md) | Google Gemini CLI integration guide |
| [Moltbot Setup](docs/moltbot.md) | Moltbot integration guide |
| [Kiro Setup](docs/kiro.md) | Kiro steering files integration |
| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
| [Continue Setup](docs/continue.md) | Continue integration guide (skills + slash prompt) |
| [Windows Setup](docs/windows.md) | Windows-specific notes |
| [Kilo Code Support](docs/kilocode.md) | Kilo Code integration guide |
| [Codex Setup](docs/codex.md) | Codex IDE installation and usage |
| [OpenCode Setup](docs/opencode.md) | OpenCode IDE installation, oh-my-opencode config |
| [FactoryAI Droid Setup](docs/factory.md) | FactoryAI Droid integration guide |
| [Antigravity Setup](docs/antigravity.md) | Antigravity IDE integration guide |
| [CodeBuddy Setup](docs/codebuddy.md) | CodeBuddy IDE integration guide |
| [AdaL CLI Setup](docs/adal.md) | AdaL CLI / Sylph AI integration guide |
## Versions
| Version | Features | Install |
|---------|----------|---------|
| **v2.12.0** (current) | AdaL CLI / Sylph AI support | `claude plugins install OthmanAdi/planning-with-files` |
| **v2.11.0** | `/plan` command for easier autocomplete | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.10.0** | Kiro steering files support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.9.0** | Moltbot (formerly Clawd CLI) support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.8.0** | Continue IDE support, POSIX sh compatibility fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.7.1** | Dynamic Python detection fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.7.0** | Gemini CLI support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.6.0** | Start command (`/planning-with-files:start`), path resolution fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.5.0** | Fixed autocomplete - SKILL.md matches Anthropic format | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.3.0** | Codex & OpenCode IDE support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.2** | Restored skill activation language | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.1** | Session recovery after /clear, enhanced PreToolUse hook | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.2.0** | Kilo Code IDE support, Windows PowerShell support, OS-aware hooks | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.1.2** | Fix template cache issue (Issue #18) | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.1.0** | Claude Code v2.1 compatible, PostToolUse hook, user-invocable | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.0.x** | Hooks, templates, scripts | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v1.0.0** (legacy) | Core 3-file pattern | `git clone -b legacy` |
See [CHANGELOG.md](CHANGELOG.md) for details.
## Why This Skill?
On December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.
@@ -157,63 +176,35 @@ Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## The Manus Principles
| Principle | Implementation |
|-----------|----------------|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions (hooks) |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Completion verification | Stop hook checks all phases |
## Usage
Once installed, Claude will automatically:
Once installed, the AI agent will:
1. **Create `task_plan.md`** before starting complex tasks
2. **Re-read plan** before major decisions (via PreToolUse hook)
3. **Remind you** to update status after file writes (via PostToolUse hook)
4. **Store findings** in `findings.md` instead of stuffing context
5. **Log errors** for future reference
6. **Verify completion** before stopping (via Stop hook)
1. **Ask for your task** if no description is provided
2. **Create `task_plan.md`, `findings.md`, and `progress.md`** in your project directory
3. **Re-read plan** before major decisions (via PreToolUse hook)
4. **Remind you** to update status after file writes (via PostToolUse hook)
5. **Store findings** in `findings.md` instead of stuffing context
6. **Log errors** for future reference
7. **Verify completion** before stopping (via Stop hook)
Or invoke manually:
Invoke with:
- `/planning-with-files:plan` - Type `/plan` to find in autocomplete (v2.11.0+)
- `/planning-with-files:start` - Type `/planning` to find in autocomplete
- `/planning-with-files` - Only if you copied skills to `~/.claude/skills/`
See [docs/quickstart.md](docs/quickstart.md) for the full 5-step guide.
## Session Recovery (NEW in v2.2.0)
When your context window fills up and you run `/clear`, this skill automatically recovers unsynced work from your previous session.
### Optimal Workflow
For the best experience, we recommend:
1. **Disable auto-compact** in Claude Code settings (use full context window)
2. **Start a fresh session** in your project
3. **Run `/planning-with-files`** when ready to work on a complex task
4. **Work until context fills up** (Claude will warn you)
5. **Run `/clear`** to start fresh
6. **Run `/planning-with-files`** again — it will automatically recover where you left off
### How Recovery Works
When you invoke `/planning-with-files`, the skill:
1. Checks for previous session data (stored in `~/.claude/projects/`)
2. Finds the last time planning files were updated
3. Extracts conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync planning files
This means even if context filled up before you could update your planning files, the skill will recover that context in your next session.
### Disabling Auto-Compact
To use the full context window without automatic compaction:
```bash
# In your Claude Code settings or .claude/settings.json
{
"autoCompact": false
}
```
This lets you maximize context usage before manually clearing with `/clear`.
## Key Rules
1. **Create Plan First** — Never start without `task_plan.md`
@@ -221,6 +212,19 @@ This lets you maximize context usage before manually clearing with `/clear`.
3. **Log ALL Errors** — They help avoid repetition
4. **Never Repeat Failures** — Track attempts, mutate approach
## When to Use
**Use this pattern for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## File Structure
```
@@ -264,58 +268,55 @@ planning-with-files/
├── .opencode/ # OpenCode IDE skills
│ └── skills/
├── .claude-plugin/ # Plugin manifest
├── .cursor/ # Cursor skills
├── .cursor/ # Cursor skills + hooks
│ ├── hooks.json # Hook configuration
│ ├── hooks/ # Hook scripts (bash + PowerShell)
│ └── skills/
├── .kilocode/ # Kilo Code skills
│ └── skills/
├── .openclaw/ # OpenClaw skills
│ └── skills/
├── .adal/ # AdaL CLI / Sylph AI skills
│ └── skills/
├── .pi/ # Pi Agent skills
│ └── skills/
│ └── planning-with-files/
├── .github/ # GitHub Copilot hooks
│ └── hooks/
│ ├── planning-with-files.json # Hook configuration
│ └── scripts/ # Hook scripts (bash + PowerShell)
├── CHANGELOG.md
├── LICENSE
└── README.md
```
## The Manus Principles
## Documentation
| Principle | Implementation |
|-----------|----------------|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions (hooks) |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Completion verification | Stop hook checks all phases |
| Document | Description |
|----------|-------------|
| [Installation Guide](docs/installation.md) | All installation methods (plugin, manual, Cursor, Windows) |
| [Quick Start](docs/quickstart.md) | 5-step guide to using the pattern |
| [Workflow Diagram](docs/workflow.md) | Visual diagram of how files and hooks interact |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Gemini CLI Setup](docs/gemini.md) | Google Gemini CLI integration guide |
| [OpenClaw Setup](docs/openclaw.md) | OpenClaw integration guide |
| [Kiro Setup](docs/kiro.md) | Kiro steering files integration |
| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
| [Continue Setup](docs/continue.md) | Continue integration guide (skills + slash prompt) |
| [Windows Setup](docs/windows.md) | Windows-specific notes |
| [Kilo Code Support](docs/kilocode.md) | Kilo Code integration guide |
| [Codex Setup](docs/codex.md) | Codex IDE installation and usage |
| [OpenCode Setup](docs/opencode.md) | OpenCode IDE installation, oh-my-opencode config |
| [FactoryAI Droid Setup](docs/factory.md) | FactoryAI Droid integration guide |
| [Antigravity Setup](docs/antigravity.md) | Antigravity IDE integration guide |
| [CodeBuddy Setup](docs/codebuddy.md) | CodeBuddy IDE integration guide |
| [AdaL CLI Setup](docs/adal.md) | AdaL CLI / Sylph AI integration guide |
| [Pi Agent Setup](docs/pi-agent.md) | Pi Agent integration guide |
| [Copilot Setup](docs/copilot.md) | GitHub Copilot hooks integration guide |
## When to Use
## Contributors
**Use this pattern for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
## Kilo Code Support
This skill also supports Kilo Code AI through the `.kilocode/rules/` directory.
The [`.kilocode/rules/planning-with-files.md`](.kilocode/rules/planning-with-files.md) file contains all the planning guidelines formatted for Kilo Code's rules system, providing the same Manus-style planning workflow for Kilo Code users.
**Windows users:** The skill now includes PowerShell scripts ([`init-session.ps1`](skills/planning-with-files/scripts/init-session.ps1) and [`check-complete.ps1`](skills/planning-with-files/scripts/check-complete.ps1)) for native Windows support.
See [docs/kilocode.md](docs/kilocode.md) for detailed Kilo Code integration guide.
## Community Forks
| Fork | Author | Features |
|------|--------|----------|
| [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 |
*Built something? Open an issue to get listed!*
- [@codelyc](https://github.com/codelyc) — OpenCode scripts support
## Acknowledgments
+49
View File
@@ -0,0 +1,49 @@
---
description: "Show current planning status at a glance - phases, progress, and any logged errors."
---
Read task_plan.md from the current project directory and display a compact status summary.
## What to Show
1. **Current Phase**: Extract from "## Current Phase" section
2. **Phase Progress**: Count phases and their status (pending/in_progress/complete)
3. **Phase List**: Show each phase with status icon
4. **Errors**: Count entries in "## Errors Encountered" table if present
5. **Files Check**: Confirm which planning files exist
## Status Icons
- `[ ]` or "pending" → ⏸️
- "in_progress" → 🔄
- `[x]` or "complete" → ✅
- "failed" or "blocked" → ❌
## Output Format
```
📋 Planning Status
Current: Phase {N} of {total} ({percent}%)
Status: {status_icon} {status_text}
{icon} Phase 1: {name}
{icon} Phase 2: {name} ← you are here
{icon} Phase 3: {name}
...
Files: task_plan.md {✓|✗} | findings.md {✓|✗} | progress.md {✓|✗}
Errors logged: {count}
```
## If No Planning Files Exist
```
📋 No planning files found
Run /plan to start a new planning session.
```
## Keep It Brief
This is a quick status check, not a full report. Show just enough to answer "where am I?" without re-reading all the files.
+36 -6
View File
@@ -6,14 +6,44 @@ planning-with-files works with Codex as a personal skill in `~/.codex/skills/`.
## Installation
See [.codex/INSTALL.md](../.codex/INSTALL.md) for detailed installation instructions.
Codex auto-discovers skills from `.codex/skills/` directories. Two installation methods:
### Quick Install
### Method 1: Workspace Installation (Recommended)
Share the skill with your entire team by adding it 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
cp -r /tmp/planning-with-files/.codex .
# Commit to share with team
git add .codex/
git commit -m "Add planning-with-files skill for Codex"
git push
# Clean up
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:
```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
# Copy to your personal Codex skills folder
mkdir -p ~/.codex/skills
cd ~/.codex/skills
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r /tmp/planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/
# Clean up
rm -rf /tmp/planning-with-files
```
## Usage with Superpowers
@@ -33,7 +63,7 @@ Add to your `~/.codex/AGENTS.md`:
<IMPORTANT>
For complex tasks (3+ steps, research, projects):
1. Read skill: `cat ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md`
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>
@@ -42,7 +72,7 @@ For complex tasks (3+ steps, research, projects):
## Verification
```bash
ls -la ~/.codex/skills/planning-with-files/planning-with-files/SKILL.md
ls -la ~/.codex/skills/planning-with-files/SKILL.md
```
## Learn More
+105
View File
@@ -0,0 +1,105 @@
# GitHub Copilot Setup
Setting up planning-with-files for GitHub Copilot (CLI, VS Code, and Coding Agent).
---
## Prerequisites
- GitHub Copilot with hooks support enabled
- For VS Code: Copilot Chat extension v1.109.3+
- For CLI: GitHub Copilot CLI with agent mode
- For Coding Agent: Works automatically with `.github/hooks/`
---
## Installation Methods
### Method 1: Repository-Level (Recommended)
Copy both the `.github/hooks/` directory and the `skills/planning-with-files/` directory into your project:
```bash
# Copy hooks (required — Copilot hook configuration and scripts)
cp -r .github/hooks/ your-project/.github/hooks/
# Copy skills (required — templates, session-catchup script, and SKILL.md)
cp -r skills/planning-with-files/ your-project/.github/skills/planning-with-files/
# Make scripts executable (macOS/Linux)
chmod +x your-project/.github/hooks/scripts/*.sh
```
Hooks will auto-activate for all team members. This works across Copilot CLI, VS Code, and the Coding Agent.
### Method 2: Manual Setup
1. Create `.github/hooks/planning-with-files.json`
2. Copy hook scripts to `.github/hooks/scripts/`
3. Copy `skills/planning-with-files/` to `.github/skills/planning-with-files/` (templates, session-catchup script)
4. Ensure all scripts are executable (`chmod +x .github/hooks/scripts/*.sh`)
---
## What the Hooks Do
| Hook | Purpose | Behavior |
|------|---------|----------|
| `sessionStart` | Initialization | Recovers previous context via session-catchup |
| `preToolUse` | Context injection | Reads `task_plan.md` before tool operations |
| `postToolUse` | Update reminders | Prompts to update plan after file edits |
| `agentStop` | Completion check | Verifies if all phases are complete before stopping |
---
## File Structure
```
.github/
└── hooks/
├── planning-with-files.json # Hook configuration
└── scripts/
├── session-start.sh # Session initialization
├── session-start.ps1
├── pre-tool-use.sh # Plan context injection
├── pre-tool-use.ps1
├── post-tool-use.sh # Update reminders
├── post-tool-use.ps1
├── agent-stop.sh # Completion verification
└── agent-stop.ps1
```
---
## How It Works
1. **Session starts**: The `session-catchup` script runs. This recovers previous context if you cleared your session.
2. **Before tool use**: The `pre-tool-use` hook injects `task_plan.md` into the context. This keeps goals visible to the agent.
3. **After file edits**: A reminder appears after any write or edit operations. This helps ensure the plan stays updated.
4. **Agent tries to stop**: The `agent-stop` hook checks the phase status in `task_plan.md`. It prevents stopping if tasks remain.
---
## Differences from Claude Code Plugin
- **Hook Configuration**: Claude Code uses `SKILL.md` frontmatter hooks. Copilot uses the `.github/hooks/` JSON configuration file.
- **Stop Hook**: Claude's `Stop` hook corresponds to Copilot's `agentStop`.
- **Planning Files**: Both use the same core files (task_plan.md, findings.md, progress.md).
- **Protocol**: Hook scripts are adapted for Copilot's stdin JSON and stdout JSON protocol.
---
## Troubleshooting
- **Hooks not running**: Check file permissions. Ensure the `.github/hooks/` directory is committed to your repository.
- **Scripts failing**: Verify that `bash` and `python3` are available in your system PATH.
- **Windows**: PowerShell scripts (.ps1) are used automatically on Windows systems.
- **VS Code**: You might need to enable hooks in your Copilot Chat extension settings.
---
## Compatibility
This setup works across the entire GitHub Copilot ecosystem:
- GitHub Copilot CLI (terminal)
- VS Code Copilot Chat (agent mode)
- GitHub Copilot Coding Agent (github.com)
+105 -76
View File
@@ -1,113 +1,148 @@
# Cursor IDE Setup
How to use planning-with-files with Cursor IDE.
How to use planning-with-files with Cursor IDE — now with full hook support.
---
## Installation
### Option 1: Copy rules directory
### Option 1: Copy .cursor directory (Recommended)
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.cursor .cursor
```
This copies the skill files, hooks config, and hook scripts to your project.
### Option 2: Manual setup
Create `.cursor/rules/planning-with-files.mdc` in your project with the content from this repo.
1. Copy `.cursor/skills/planning-with-files/` to your project
2. Copy `.cursor/hooks.json` to your project
3. Copy `.cursor/hooks/` directory to your project
---
## Important Limitations
## Hooks Support
> **Note:** Hooks (PreToolUse, PostToolUse, Stop, SessionStart) are **Claude Code specific** and will NOT work in Cursor.
Cursor now supports hooks natively via `.cursor/hooks.json`. This skill includes three hooks that mirror the Claude Code experience:
### What works in Cursor:
| Hook | Purpose | Cursor Feature |
|------|---------|----------------|
| `preToolUse` | Re-reads task_plan.md before tool operations | Keeps goals in context |
| `postToolUse` | Reminds to update plan after file edits | Prevents forgetting updates |
| `stop` | Checks if all phases are complete | **Auto-continues** if incomplete |
- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- All planning rules and guidelines
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix
### How the Stop Hook Works
### What doesn't work in Cursor:
The stop hook is the most powerful feature. When the agent tries to stop:
- SessionStart hook (no startup notification)
- PreToolUse hook (no automatic plan re-reading)
- PostToolUse hook (no automatic reminders)
- Stop hook (no automatic completion verification)
1. It checks `task_plan.md` for phase completion status
2. If all phases are complete → allows the agent to stop
3. If phases are incomplete → sends a `followup_message` that auto-prompts the agent to keep working
---
This means the agent **cannot stop until all phases are done** (up to `loop_limit` of 3 retries).
## Manual Workflow for Cursor
Since hooks don't work in Cursor, you'll need to follow the pattern manually:
### 1. Create planning files first
Before any complex task:
```
Create task_plan.md, findings.md, and progress.md using the planning-with-files templates.
```
### 2. Re-read plan before decisions
Periodically ask:
```
Please read task_plan.md to refresh the goals before continuing.
```
### 3. Update files after phases
After completing work:
```
Update task_plan.md to mark this phase complete.
Update progress.md with what was done.
```
### 4. Verify completion manually
Before finishing:
```
Check task_plan.md - are all phases marked complete?
```
---
## Cursor Rules File
The `.cursor/rules/planning-with-files.mdc` file contains all the planning guidelines formatted for Cursor's rules system.
### File location
### Hook Files
```
your-project/
├── .cursor/
│ └── rules/
│ └── planning-with-files.mdc
├── task_plan.md
│ ├── hooks.json ← Hook configuration
│ ├── hooks/
│ │ ├── pre-tool-use.sh ← Pre-tool-use script
│ │ ├── post-tool-use.sh ← Post-tool-use script
│ │ ├── stop.sh ← Completion check script
│ │ ├── pre-tool-use.ps1 ← PowerShell versions
│ │ ├── post-tool-use.ps1
│ │ └── stop.ps1
│ └── skills/
│ └── planning-with-files/
│ ├── SKILL.md
│ ├── examples.md
│ ├── reference.md
│ └── templates/
├── task_plan.md ← Your planning files (created per task)
├── findings.md
├── progress.md
└── ...
```
### Activating rules
---
Cursor automatically loads rules from `.cursor/rules/` when you open a project.
## Windows Setup
The default `hooks.json` uses bash scripts (works on macOS, Linux, and Windows with Git Bash).
**If you need native PowerShell**, rename the config files:
```powershell
# Back up the default config
Rename-Item .cursor\hooks.json hooks.unix.json
# Use the PowerShell config
Rename-Item .cursor\hooks.windows.json hooks.json
```
The `.cursor/hooks.windows.json` file uses PowerShell to execute the `.ps1` hook scripts directly.
---
## What Each Hook Does
### PreToolUse Hook
**Triggers:** Before Write, Edit, Shell, or Read operations
**What it does:** Reads the first 30 lines of `task_plan.md` and logs them to stderr for context. Always returns `{"decision": "allow"}` — it never blocks tools.
**Claude Code equivalent:** `cat task_plan.md 2>/dev/null | head -30 || true`
### PostToolUse Hook
**Triggers:** After Write or Edit operations
**What it does:** Outputs a reminder to update `task_plan.md` if a phase was completed.
**Claude Code equivalent:** `echo '[planning-with-files] File updated...'`
### Stop Hook
**Triggers:** When the agent tries to stop working
**What it does:**
1. Counts total phases (`### Phase` headers) in `task_plan.md`
2. Counts completed phases (supports both `**Status:** complete` and `[complete]` formats)
3. If incomplete, returns `followup_message` to auto-continue
4. Capped at 3 retries via `loop_limit` to prevent infinite loops
**Claude Code equivalent:** `scripts/check-complete.sh` — but Cursor's version is **more powerful** because it can auto-continue the agent instead of just reporting status.
---
## Skill Files
The `.cursor/skills/planning-with-files/SKILL.md` file contains all the planning guidelines:
- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix
Cursor automatically loads skills from `.cursor/skills/` when you open a project.
---
## Templates
The templates in `skills/planning-with-files/templates/` work in Cursor:
The templates in `.cursor/skills/planning-with-files/templates/` are used when starting a new task:
- `task_plan.md` - Phase tracking template
- `findings.md` - Research storage template
- `progress.md` - Session logging template
Copy them to your project root when starting a new task.
The agent copies these to your project root when starting a new planning session.
---
@@ -115,27 +150,21 @@ Copy them to your project root when starting a new task.
1. **Pin the planning files:** Keep task_plan.md open in a split view for easy reference.
2. **Add to .cursorrules:** You can also add planning guidelines to your project's `.cursorrules` file.
2. **Trust the hooks:** The stop hook will prevent premature completion — you don't need to manually verify phase status.
3. **Use explicit prompts:** Since there's no auto-detection, be explicit:
3. **Use explicit prompts for complex tasks:**
```
This is a complex task. Let's use the planning-with-files pattern.
Start by creating task_plan.md with the goal and phases.
```
4. **Check status regularly:** Without the Stop hook, manually verify completion before finishing.
4. **Check hook logs:** If hooks aren't working, check Cursor's output panel for hook execution logs.
---
## Migrating from Cursor to Claude Code
## Compatibility with Claude Code
If you want full hook support, consider using Claude Code CLI:
1. Install Claude Code
2. Run `/plugin install planning-with-files@planning-with-files`
3. All hooks will work automatically
Your existing planning files (task_plan.md, etc.) are compatible with both.
Your planning files (task_plan.md, findings.md, progress.md) are fully compatible between Cursor and Claude Code. You can switch between them without any changes to your planning files.
---
+7 -57
View File
@@ -5,7 +5,7 @@ Planning with Files is fully supported on Kilo Code through native integration.
## Quick Start
1. Open your project in Kilo Code
2. Rules load automatically from global (`~/.kilocode/rules/`) or project (`.kilocode/rules/`) directories
2. Skills load automatically from global (`~/.kilocode/skills/`) or project (`.kilocode/skills/`) directories
3. Start a complex task — Kilo Code will automatically create planning files
## Installation
@@ -21,11 +21,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill to Kilo Code's skills directory
mkdir -p .kilocode/skills
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
# Copy the rules file (optional, but recommended)
mkdir -p .kilocode/rules
cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
cp -r planning-with-files/.kilocode/skills/planning-with-files .kilocode/skills/planning-with-files
```
**Windows (PowerShell):**
@@ -35,15 +31,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill to Kilo Code's skills directory
New-Item -ItemType Directory -Force -Path .kilocode\skills
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
# Copy the rules file (optional, but recommended)
New-Item -ItemType Directory -Force -Path .kilocode\rules
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
# Copy PowerShell scripts (optional, but recommended)
Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files .kilocode\skills\planning-with-files
```
### Manual Installation (Project-Level)
@@ -54,26 +42,14 @@ Copy the skill directory to your project:
```bash
# From the cloned repository
mkdir -p .kilocode/skills
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/planning-with-files
# Copy the rules file (optional, but recommended)
mkdir -p .kilocode/rules
cp planning-with-files/.kilocode/rules/planning-with-files.md .kilocode/rules/planning-with-files.md
cp -r planning-with-files/.kilocode/skills/planning-with-files .kilocode/skills/planning-with-files
```
**Windows (PowerShell):**
```powershell
# From the cloned repository
New-Item -ItemType Directory -Force -Path .kilocode\skills
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\planning-with-files
# Copy the rules file (optional, but recommended)
New-Item -ItemType Directory -Force -Path .kilocode\rules
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md .kilocode\rules\planning-with-files.md
# Copy PowerShell scripts (optional, but recommended)
Copy-Item -Force planning-with-files\scripts\init-session.ps1 .kilocode\skills\planning-with-files\scripts\init-session.ps1
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 .kilocode\skills\planning-with-files\scripts\check-complete.ps1
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files .kilocode\skills\planning-with-files
```
### Global Installation (User-Level)
@@ -84,26 +60,14 @@ To make the skill available across all projects:
```bash
# Copy to global skills directory
mkdir -p ~/.kilocode/skills
cp -r planning-with-files/skills/planning-with-files ~/.kilocode/skills/planning-with-files
# Copy the rules file (optional, but recommended)
mkdir -p ~/.kilocode/rules
cp planning-with-files/.kilocode/rules/planning-with-files.md ~/.kilocode/rules/planning-with-files.md
cp -r planning-with-files/.kilocode/skills/planning-with-files ~/.kilocode/skills/planning-with-files
```
**Windows (PowerShell):**
```powershell
# Copy to global skills directory (replace YourUsername with your actual username)
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\skills
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
# Copy the rules file (optional, but recommended)
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\rules
Copy-Item -Force planning-with-files\.kilocode\rules\planning-with-files.md C:\Users\YourUsername\.kilocode\rules\planning-with-files.md
# Copy PowerShell scripts (optional, but recommended)
Copy-Item -Force planning-with-files\scripts\init-session.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\init-session.ps1
Copy-Item -Force planning-with-files\scripts\check-complete.ps1 C:\Users\YourUsername\.kilocode\skills\planning-with-files\scripts\check-complete.ps1
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
```
### Verifying Installation
@@ -113,7 +77,6 @@ After installation, verify the skill is loaded:
1. **Restart Kilo Code** (if needed)
2. Ask the agent: "Do you have access to the planning-with-files skill?"
3. The agent should confirm the skill is loaded
4. Rules also load automatically from `~/.kilocode/rules/planning-with-files.md` (global) or `.kilocode/rules/planning-with-files.md` (project)
**Testing PowerShell Scripts (Windows):**
@@ -131,10 +94,6 @@ The scripts should create `task_plan.md`, `findings.md`, and `progress.md` files
### File Structure
The installation consists of the skill directory and the rules file:
**Skill Directory:**
```
~/.kilocode/skills/planning-with-files/ (Global)
OR
@@ -153,21 +112,12 @@ OR
└── check-complete.ps1 # Windows (PowerShell)
```
**Rules File:**
```
~/.kilocode/rules/planning-with-files.md (Global)
OR
.kilocode/rules/planning-with-files.md (Project)
```
**Important**: The `name` field in `SKILL.md` must match the directory name (`planning-with-files`).
## File Locations
| Type | Global Location | Project Location |
|------|-----------------|------------------|
| **Rules** | `~/.kilocode/rules/planning-with-files.md` | `.kilocode/rules/planning-with-files.md` |
| **Skill** | `~/.kilocode/skills/planning-with-files/SKILL.md` | `.kilocode/skills/planning-with-files/SKILL.md` |
| **Templates** | `~/.kilocode/skills/planning-with-files/templates/` | `.kilocode/skills/planning-with-files/templates/` |
| **Scripts (Unix/Linux/macOS)** | `~/.kilocode/skills/planning-with-files/scripts/*.sh` | `.kilocode/skills/planning-with-files/scripts/*.sh` |
+16 -19
View File
@@ -1,18 +1,18 @@
# Moltbot Setup
# OpenClaw Setup
How to use planning-with-files with [Moltbot](https://molt.bot).
How to use planning-with-files with [OpenClaw](https://openclaw.ai).
---
## What This Integration Adds
- Workspace skill: `.moltbot/skills/planning-with-files/`
- Workspace skill: `.openclaw/skills/planning-with-files/`
- Full templates, scripts, and reference documentation
- Cross-platform support (macOS, Linux, Windows)
Moltbot supports three skill locations (in precedence order):
OpenClaw supports three skill locations (in precedence order):
1. **Workspace skills** (highest priority): `<workspace>/skills/`
2. **Managed/local skills**: `~/.clawdbot/skills/`
2. **Managed/local skills**: `~/.openclaw/skills/`
3. **Bundled skills** (lowest priority): shipped with install
---
@@ -25,8 +25,8 @@ Copy the skill to your project:
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the Moltbot skill to your workspace
cp -r planning-with-files/.moltbot/skills/planning-with-files skills/
# Copy the OpenClaw skill to your workspace
cp -r planning-with-files/.openclaw/skills/planning-with-files skills/
# Clean up
rm -rf planning-with-files
@@ -36,15 +36,15 @@ rm -rf planning-with-files
## Installation (Global)
Install to your local Moltbot skills directory:
Install to your local OpenClaw skills directory:
```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy to global Moltbot skills
mkdir -p ~/.clawdbot/skills
cp -r planning-with-files/.moltbot/skills/planning-with-files ~/.clawdbot/skills/
# Copy to global OpenClaw skills
mkdir -p ~/.openclaw/skills
cp -r planning-with-files/.openclaw/skills/planning-with-files ~/.openclaw/skills/
# Clean up
rm -rf planning-with-files
@@ -55,18 +55,15 @@ rm -rf planning-with-files
## Verify Installation
```bash
# List all skills
moltbot skills list
# Check if planning-with-files is loaded
moltbot skills info planning-with-files
# Check OpenClaw status and loaded skills
openclaw status
```
---
## Usage
1. Start a Moltbot session in your project directory
1. Start an OpenClaw session in your project directory
2. For complex tasks, the skill will guide you to create:
- `task_plan.md` — Phase tracking and decisions
- `findings.md` — Research and discoveries
@@ -94,7 +91,7 @@ bash skills/planning-with-files/scripts/check-complete.sh
## Configuration (Optional)
Configure the skill in `~/.clawdbot/moltbot.json`:
Configure the skill in `~/.openclaw/openclaw.json`:
```json5
{
@@ -112,7 +109,7 @@ Configure the skill in `~/.clawdbot/moltbot.json`:
## Notes
- Moltbot snapshots eligible skills when a session starts
- OpenClaw snapshots eligible skills when a session starts
- Workspace skills take precedence over bundled skills
- The skill works on all platforms: macOS, Linux, and Windows
- Planning files are tool-agnostic and work across Claude Code, Cursor, and other IDEs
+45 -2
View File
@@ -42,15 +42,58 @@ cat ~/.config/opencode/skills/planning-with-files/planning-with-files/SKILL.md
## oh-my-opencode Compatibility
If using oh-my-opencode, ensure planning-with-files is not in the `disabled_skills` array:
oh-my-opencode has Claude Code compatibility for skills. To use planning-with-files with oh-my-opencode:
### Step 1: Install the skill
```bash
mkdir -p ~/.config/opencode/skills/planning-with-files
cp -r .opencode/skills/planning-with-files/* ~/.config/opencode/skills/planning-with-files/
```
### Step 2: Configure oh-my-opencode
Add the skill to your `~/.config/opencode/oh-my-opencode.json` (or `.opencode/oh-my-opencode.json` for project-level):
**~/.config/opencode/oh-my-opencode.json:**
```json
{
"skills": {
"sources": [
{ "path": "~/.config/opencode/skills/planning-with-files", "recursive": false }
],
"enable": ["planning-with-files"]
},
"disabled_skills": []
}
```
### Step 3: Verify loading
Ask the agent: "Do you have access to the planning-with-files skill? Can you create task_plan.md?"
### Troubleshooting
If the agent forgets the planning rules:
1. **Check skill is loaded**: The skill should appear in oh-my-opencode's recognized skills
2. **Explicit invocation**: Tell the agent "Use the planning-with-files skill for this task"
3. **Check for conflicts**: If using superpowers plugin alongside oh-my-opencode, choose one method:
- Use oh-my-opencode's native skill loading (recommended)
- OR use superpowers' `use_skill` tool, but not both
## Known Limitations
### Session Catchup
The `session-catchup.py` script currently has limited support for OpenCode due to different session storage formats:
- **Claude Code**: Uses `.jsonl` files at `~/.claude/projects/`
- **OpenCode**: Uses `.json` files at `~/.local/share/opencode/storage/session/`
When you run `/clear` in OpenCode, session catchup will detect OpenCode and show a message. **Workaround**: Manually read `task_plan.md`, `progress.md`, and `findings.md` to catch up after clearing context.
Full OpenCode session parsing support is planned for a future release.
## Verification
**Global:**
+128
View File
@@ -0,0 +1,128 @@
# Pi Agent Setup
How to use planning-with-files with [Pi Coding Agent](https://pi.dev).
---
## Installation
### Pi Install
```bash
pi install npm:pi-planning-with-files
```
### Manual Install
1. Navigate to your project root.
2. Create the `.pi/skills` directory if it doesn't exist.
3. Copy the `planning-with-files` skill.
```bash
# Clone the repo
git clone https://github.com/OthmanAdi/planning-with-files.git
# Copy the skill
mkdir -p ~/.pi/agent/skills
cp -r planning-with-files/.pi/skills/planning-with-files .pi/skills/
```
---
## Usage
Pi Agent automatically discovers skills in `.pi/skills`.
To use the skill, you can explicitly invoke it or let Pi discover it based on the task description.
### Explicit Invocation
```bash
/skill:planning-with-files
```
Or just ask Pi:
```
Use the planning-with-files skill to help me with this task.
```
---
## Important Limitations
> **Note:** Hooks (PreToolUse, PostToolUse, Stop) are **Claude Code specific** and are not currently supported in Pi Agent.
### What works in Pi Agent:
- Core 3-file planning pattern
- Templates (task_plan.md, findings.md, progress.md)
- All planning rules and guidelines
- The 2-Action Rule
- The 3-Strike Error Protocol
- Read vs Write Decision Matrix
- Helper scripts (via explicit invocation or skill instructions)
### What works differently:
- **Session Recovery:** You must manually run the catchup script if needed:
```bash
python3 .pi/skills/planning-with-files/scripts/session-catchup.py .
```
(The skill provides instructions for this)
---
## Manual Workflow
Since hooks don't run automatically, follow the pattern:
### 1. Create planning files first
The skill instructions will guide Pi to create these files.
If not, ask:
```
Start by creating task_plan.md, findings.md, and progress.md using the planning-with-files templates.
```
### 2. Re-read plan before decisions
Periodically ask:
```
Read task_plan.md to refresh our context.
```
### 3. Update files after phases
After completing a phase:
```
Update task_plan.md to mark this phase complete.
Update progress.md with what was done.
```
---
## File Structure
```
your-project/
├── .pi/
│ └── skills/
│ └── planning-with-files/
│ ├── SKILL.md
│ ├── templates/
│ ├── scripts/
│ └── ...
├── task_plan.md
├── findings.md
├── progress.md
└── ...
```
---
## Troubleshooting
If Pi doesn't seem to follow the planning rules:
1. Ensure the skill is loaded (ask "What skills do you have available?").
2. Explicitly ask it to read the `SKILL.md` file: `Read .pi/skills/planning-with-files/SKILL.md`.
3. Use the `/skill:planning-with-files` command if enabled.
+11 -10
View File
@@ -4,24 +4,25 @@ Follow these 5 steps to use the planning-with-files pattern.
---
## Step 1: Create Your Planning Files
## Step 1: Invoke the Skill and Describe Your Task
**When:** Before starting any work on a complex task
**Action:** Create all three files using the templates:
**Action:** Invoke the skill (e.g., `/plan` or `/planning-with-files:start`) and describe what you want to accomplish. The AI will create all three planning files in your project directory:
- `task_plan.md` — Phases and progress tracking
- `findings.md` — Research and discoveries
- `progress.md` — Session log and test results
If you invoke the skill without a task description, the AI will ask you what you'd like to plan.
**Manual alternative:** If you prefer to create files yourself:
```bash
# Option 1: Use the init script (if available)
# Use the init script
./scripts/init-session.sh
# Option 2: Copy templates manually
cp templates/task_plan.md task_plan.md
cp templates/findings.md findings.md
cp templates/progress.md progress.md
# Then fill in the Goal section in task_plan.md
```
**Update:** Fill in the Goal section in `task_plan.md` with your task description.
---
## Step 2: Plan Your Phases
+26 -24
View File
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
+24 -22
View File
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
+77 -3
View File
@@ -6,6 +6,10 @@ Session-agnostic scanning: finds the most recent planning file update across
ALL sessions, then collects all conversation from that point forward through
all subsequent sessions until now.
Supports multiple AI IDEs:
- Claude Code (.claude/projects/)
- OpenCode (.local/share/opencode/storage/)
Usage: python3 session-catchup.py [project-path]
"""
@@ -18,7 +22,29 @@ from typing import List, Dict, Optional, Tuple
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def get_project_dir(project_path: str) -> Path:
def detect_ide() -> str:
"""
Detect which IDE is being used based on environment and file structure.
Returns 'claude-code', 'opencode', or 'unknown'.
"""
# Check for OpenCode environment
if os.environ.get('OPENCODE_DATA_DIR'):
return 'opencode'
# Check for Claude Code directory
claude_dir = Path.home() / '.claude'
if claude_dir.exists():
return 'claude-code'
# Check for OpenCode directory
opencode_dir = Path.home() / '.local' / 'share' / 'opencode'
if opencode_dir.exists():
return 'opencode'
return 'unknown'
def get_project_dir_claude(project_path: str) -> Path:
"""Convert project path to Claude's storage path format."""
sanitized = project_path.replace('/', '-')
if not sanitized.startswith('-'):
@@ -27,6 +53,24 @@ def get_project_dir(project_path: str) -> Path:
return Path.home() / '.claude' / 'projects' / sanitized
def get_project_dir_opencode(project_path: str) -> Optional[Path]:
"""
Get OpenCode session storage directory.
OpenCode uses: ~/.local/share/opencode/storage/session/{projectHash}/
Note: OpenCode's structure is different - this function returns the storage root.
Session discovery happens differently in OpenCode.
"""
data_dir = os.environ.get('OPENCODE_DATA_DIR',
str(Path.home() / '.local' / 'share' / 'opencode'))
storage_dir = Path(data_dir) / 'storage'
if not storage_dir.exists():
return None
return storage_dir
def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
@@ -34,6 +78,24 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
"""
Get all OpenCode session files sorted by modification time.
OpenCode stores sessions at: storage/session/{projectHash}/{sessionID}.json
"""
session_dir = storage_dir / 'session'
if not session_dir.exists():
return []
sessions = []
for project_hash_dir in session_dir.iterdir():
if project_hash_dir.is_dir():
for session_file in project_hash_dir.glob('*.json'):
sessions.append(session_file)
return sorted(sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def get_session_first_timestamp(session_file: Path) -> Optional[str]:
"""Get the timestamp of the first message in a session."""
try:
@@ -181,7 +243,19 @@ def extract_messages_from_session(session_file: Path, after_line: int = -1) -> L
def main():
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
project_dir = get_project_dir(project_path)
# Detect IDE
ide = detect_ide()
if ide == 'opencode':
print("\n[planning-with-files] OpenCode session catchup is not yet fully supported")
print("OpenCode uses a different session storage format (.json) than Claude Code (.jsonl)")
print("Session catchup requires parsing OpenCode's message storage structure.")
print("\nWorkaround: Manually read task_plan.md, progress.md, and findings.md to catch up.")
return
# Claude Code path
project_dir = get_project_dir_claude(project_path)
if not project_dir.exists():
return
@@ -233,7 +307,7 @@ def main():
return
# Output catchup report
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"\n[planning-with-files] SESSION CATCHUP DETECTED (IDE: {ide})")
print(f"Last planning update: {update_file} in session {update_session.stem[:8]}...")
sessions_covered = update_session_idx + 1
+304
View File
@@ -0,0 +1,304 @@
#!/usr/bin/env python3
"""
sync-ide-folders.py — Syncs shared files from the canonical source
(skills/planning-with-files/) to all IDE-specific folders.
Run this from the repo root before releases:
python scripts/sync-ide-folders.py
What it syncs:
- Templates (findings.md, progress.md, task_plan.md)
- References (examples.md, reference.md)
- Scripts (check-complete.sh/.ps1, init-session.sh/.ps1, session-catchup.py)
What it NEVER touches:
- SKILL.md (IDE-specific frontmatter differs per IDE)
- IDE-specific files (hooks, prompts, package.json, steering files)
Use --dry-run to preview changes without writing anything.
Use --verify to check for drift without making changes (exits 1 if drift found).
"""
import os
import shutil
import sys
import hashlib
from pathlib import Path
# ─── Canonical source ──────────────────────────────────────────────
CANONICAL = Path("skills/planning-with-files")
# ─── Shared source files (relative to CANONICAL) ──────────────────
TEMPLATES = [
"templates/findings.md",
"templates/progress.md",
"templates/task_plan.md",
]
REFERENCES = [
"examples.md",
"reference.md",
]
SCRIPTS = [
"scripts/check-complete.sh",
"scripts/check-complete.ps1",
"scripts/init-session.sh",
"scripts/init-session.ps1",
"scripts/session-catchup.py",
]
# ─── IDE sync manifests ───────────────────────────────────────────
# Each IDE maps: canonical_source_file -> target_path (relative to repo root)
# Only files listed here are synced. Everything else is untouched.
def _build_manifest(base, *, ref_style="flat", template_dirs=None,
include_scripts=True, extra_template_dirs=None):
"""Build a sync manifest for an IDE folder.
Args:
base: IDE skill folder path (e.g. ".gemini/skills/planning-with-files")
ref_style: "flat" = examples.md at root, "subdir" = references/examples.md
template_dirs: list of template subdirs (default: ["templates/"])
include_scripts: whether to sync scripts
extra_template_dirs: additional dirs to also receive template copies
"""
manifest = {}
b = Path(base)
# Templates
if template_dirs is None:
template_dirs = ["templates/"]
for tdir in template_dirs:
for t in TEMPLATES:
filename = Path(t).name # e.g. "findings.md"
manifest[t] = str(b / tdir / filename)
# Extra template locations (e.g. assets/templates/ in codex, codebuddy)
if extra_template_dirs:
for tdir in extra_template_dirs:
for t in TEMPLATES:
filename = Path(t).name
manifest[f"{t}__extra_{tdir}"] = str(b / tdir / filename)
# References
if ref_style == "flat":
for r in REFERENCES:
manifest[r] = str(b / r)
elif ref_style == "subdir":
for r in REFERENCES:
manifest[r] = str(b / "references" / r)
# ref_style == "skip" means don't sync references (IDE uses custom format)
# Scripts
if include_scripts:
for s in SCRIPTS:
manifest[s] = str(b / s)
return manifest
IDE_MANIFESTS = {
".cursor": _build_manifest(
".cursor/skills/planning-with-files",
ref_style="flat",
include_scripts=False,
# Cursor hooks are IDE-specific, not synced
),
".gemini": _build_manifest(
".gemini/skills/planning-with-files",
ref_style="subdir",
include_scripts=True,
),
".codex": _build_manifest(
".codex/skills/planning-with-files",
ref_style="subdir",
include_scripts=True,
extra_template_dirs=["assets/templates/"],
),
".openclaw": _build_manifest(
".openclaw/skills/planning-with-files",
ref_style="subdir",
include_scripts=True,
),
".kilocode": _build_manifest(
".kilocode/skills/planning-with-files",
ref_style="flat",
include_scripts=False,
),
".adal": _build_manifest(
".adal/skills/planning-with-files",
ref_style="subdir",
include_scripts=True,
# .adal also has check-continue.sh — not synced (IDE-specific)
),
".pi": _build_manifest(
".pi/skills/planning-with-files",
ref_style="flat",
include_scripts=True,
# package.json and README.md are IDE-specific, not synced
),
".continue": _build_manifest(
".continue/skills/planning-with-files",
ref_style="flat",
template_dirs=[], # Continue has no templates dir
include_scripts=True,
# .continue/prompts/ is IDE-specific, not synced
),
".codebuddy": _build_manifest(
".codebuddy/skills/planning-with-files",
ref_style="subdir",
include_scripts=True,
extra_template_dirs=["assets/templates/"],
),
".factory": _build_manifest(
".factory/skills/planning-with-files",
ref_style="skip", # Uses combined references.md, not synced
include_scripts=False,
),
".agent": _build_manifest(
".agent/skills/planning-with-files",
ref_style="skip", # Uses combined references.md, not synced
template_dirs=[], # Templates in references/ — custom layout, not synced
include_scripts=False,
),
".opencode": _build_manifest(
".opencode/skills/planning-with-files",
ref_style="flat",
include_scripts=False,
),
".kiro": {
# Kiro has a completely different structure (steering files, not SKILL.md)
# Only sync the scripts which live at .kiro/scripts/ (not under skills/)
"scripts/check-complete.sh": ".kiro/scripts/check-complete.sh",
"scripts/check-complete.ps1": ".kiro/scripts/check-complete.ps1",
"scripts/init-session.sh": ".kiro/scripts/init-session.sh",
"scripts/init-session.ps1": ".kiro/scripts/init-session.ps1",
# Steering files are IDE-specific, not synced
},
}
# ─── Utility functions ─────────────────────────────────────────────
def file_hash(path):
"""Return SHA-256 hash of a file, or None if it doesn't exist."""
try:
return hashlib.sha256(Path(path).read_bytes()).hexdigest()
except FileNotFoundError:
return None
def sync_file(src, dst, *, dry_run=False):
"""Copy src to dst. Returns (action, detail) tuple.
Actions: "updated", "created", "skipped" (already identical), "missing_src"
"""
if not src.exists():
return "missing_src", f"Canonical file not found: {src}"
src_hash = file_hash(src)
dst_hash = file_hash(dst)
if src_hash == dst_hash:
return "skipped", "Already up to date"
action = "created" if dst_hash is None else "updated"
if not dry_run:
dst.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(src, dst)
return action, f"{'Would ' if dry_run else ''}{action}: {dst}"
# ─── Main ──────────────────────────────────────────────────────────
def main():
dry_run = "--dry-run" in sys.argv
verify = "--verify" in sys.argv
# Must run from repo root
if not CANONICAL.exists():
print(f"Error: Canonical source not found at {CANONICAL}/")
print("Run this script from the repo root.")
sys.exit(1)
print(f"{'[DRY RUN] ' if dry_run else ''}{'[VERIFY] ' if verify else ''}"
f"Syncing from {CANONICAL}/\n")
stats = {"updated": 0, "created": 0, "skipped": 0, "missing_src": 0, "drift": 0}
for ide_name, manifest in sorted(IDE_MANIFESTS.items()):
# Skip IDEs whose base directory doesn't exist
ide_root = Path(ide_name)
if not ide_root.exists():
continue
print(f" {ide_name}/")
ide_changes = 0
for canonical_key, target_path in sorted(manifest.items()):
# Handle __extra_ keys (canonical key contains __extra_ suffix)
canonical_rel = canonical_key.split("__extra_")[0]
src = CANONICAL / canonical_rel
dst = Path(target_path)
if verify:
# Verify mode: just check for drift
src_hash = file_hash(src)
dst_hash = file_hash(dst)
if src_hash and dst_hash and src_hash != dst_hash:
print(f" DRIFT: {dst}")
stats["drift"] += 1
ide_changes += 1
elif src_hash and not dst_hash:
print(f" MISSING: {dst}")
stats["drift"] += 1
ide_changes += 1
else:
action, detail = sync_file(src, dst, dry_run=dry_run)
stats[action] += 1
if action in ("updated", "created"):
print(f" {action.upper()}: {dst}")
ide_changes += 1
if ide_changes == 0:
print(" (up to date)")
# Summary
print(f"\n{'-' * 50}")
if verify:
total_drift = stats["drift"]
if total_drift > 0:
print(f"DRIFT DETECTED: {total_drift} file(s) out of sync.")
print("Run 'python scripts/sync-ide-folders.py' to fix.")
sys.exit(1)
else:
print("All IDE folders are in sync.")
sys.exit(0)
else:
print(f" Updated: {stats['updated']}")
print(f" Created: {stats['created']}")
print(f" Skipped: {stats['skipped']} (already up to date)")
if stats["missing_src"] > 0:
print(f" Missing: {stats['missing_src']} (canonical source not found)")
if dry_run:
print("\n This was a dry run. No files were modified.")
print(" Run without --dry-run to apply changes.")
if __name__ == "__main__":
main()
@@ -1,42 +1,44 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
Write-Host "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
# Count total phases
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
# Check for **Status:** format first
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
# Fallback: check for [complete] inline format if **Status:** not found
if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$COMPLETE = ([regex]::Matches($content, "\[complete\]")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\[in_progress\]")).Count
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# Report status (always exit 0 — incomplete task is a normal state)
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
} else {
Write-Host "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if ($IN_PROGRESS -gt 0) {
Write-Host "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
}
if ($PENDING -gt 0) {
Write-Host "[planning-with-files] $PENDING phase(s) pending."
}
}
exit 0
@@ -1,44 +1,46 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
echo "[planning-with-files] No task_plan.md found — no active planning session."
exit 0
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
# Count total phases
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
# Check for **Status:** format first
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)
# Fallback: check for [complete] inline format if **Status:** not found
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
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
# Report status (always exit 0 — incomplete task is a normal state)
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)"
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete)"
if [ "$IN_PROGRESS" -gt 0 ]; then
echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
fi
if [ "$PENDING" -gt 0 ]; then
echo "[planning-with-files] $PENDING phase(s) pending."
fi
fi
exit 0
@@ -146,6 +146,9 @@ def main():
has_planning_files = any(
Path(project_path, f).exists() for f in PLANNING_FILES
)
if not has_planning_files:
# No planning files in this project; skip catchup to avoid noise.
return
if not project_dir.exists():
# No previous sessions, nothing to catch up on
@@ -168,11 +171,12 @@ def main():
messages = parse_session_messages(target_session)
last_update_line, last_update_file = find_last_planning_update(messages)
# Only output if there's unsynced content
# No planning updates in the target session; skip catchup output.
if last_update_line < 0:
messages_after = extract_messages_after(messages, len(messages) - 30)
else:
messages_after = extract_messages_after(messages, last_update_line)
return
# Only output if there's unsynced content
messages_after = extract_messages_after(messages, last_update_line)
if not messages_after:
return
@@ -181,11 +185,8 @@ def main():
print("\n[planning-with-files] SESSION CATCHUP DETECTED")
print(f"Previous session: {target_session.stem}")
if last_update_line >= 0:
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
else:
print("No planning file updates found in previous session")
print(f"Last planning update: {last_update_file} at message #{last_update_line}")
print(f"Unsynced messages: {len(messages_after)}")
print("\n--- UNSYNCED CONTEXT ---")
for msg in messages_after[-15:]: # Last 15 messages