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:

# 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

Create .github/hooks/planning-with-files.json
Copy hook scripts to .github/hooks/scripts/
Copy skills/planning-with-files/ to .github/skills/planning-with-files/ (templates, session-catchup script)
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

Session starts: The session-catchup script runs. This recovers previous context if you cleared your session.
Before tool use: The pre-tool-use hook injects task_plan.md into the context. This keeps goals visible to the agent.
After file edits: A reminder appears after any write or edit operations. This helps ensure the plan stays updated.
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)

3.8 KiB Raw Blame History