Compare commits

...
13 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
26 changed files with 1136 additions and 78 deletions
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
+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
@@ -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,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()
@@ -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
+19
View File
@@ -2,6 +2,25 @@
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
+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*
+22 -4
View File
@@ -2,6 +2,9 @@
> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.
[![Closed Issues](https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)
[![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>
@@ -11,7 +14,7 @@ If this skill helps you work smarter, that's all I wanted.
</details>
<details>
<details open>
<summary><strong>🌍 See What the Community Built</strong></summary>
| Fork | Author | Features |
@@ -28,10 +31,12 @@ If this skill helps you work smarter, that's all I wanted.
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v2.15.0
### 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 |
@@ -41,6 +46,8 @@ If this skill helps you work smarter, that's all I wanted.
[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
@@ -61,7 +68,7 @@ When your context fills up and you run `/clear`, this skill **automatically reco
</details>
<details>
<summary><strong>🛠️ Supported IDEs (14 Platforms)</strong></summary>
<summary><strong>🛠️ Supported IDEs (15 Platforms)</strong></summary>
| IDE | Status | Installation Guide | Format |
|-----|--------|-------------------|--------|
@@ -79,6 +86,7 @@ When your context fills up and you run `/clear`, this skill **automatically reco
| 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.
@@ -98,7 +106,8 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
[![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)
[![Pi Agent](https://img.shields.io/badge/Pi%20Agent-Skills-FF4081)](https://pi.dev)
[![Version](https://img.shields.io/badge/version-2.15.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![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
@@ -272,6 +281,10 @@ planning-with-files/
├── .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
@@ -299,6 +312,11 @@ planning-with-files/
| [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 |
## Contributors
- [@codelyc](https://github.com/codelyc) — OpenCode scripts support
## Acknowledgments
+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)
@@ -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