Compare commits

..
5 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
13 changed files with 448 additions and 6 deletions
+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
+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*
+13 -4
View File
@@ -31,10 +31,11 @@ If this skill helps you work smarter, that's all I wanted.
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v2.15.1
### 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 |
@@ -45,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
@@ -65,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 |
|-----|--------|-------------------|--------|
@@ -83,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.
@@ -102,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.1-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
@@ -276,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
@@ -303,11 +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
- [@gydx6](https://github.com/gydx6) — Session catchup false-positive fix
## 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)