wushu/.trae/skills/planning-with-files/docs/copilot.md

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

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)