Initial commit: Flutter 无书应用项目

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

@@ -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)