feat: add /ghcp-handoff skill for bounded copilot delegation

[bminier]

Summary

Adds a new sibling skill /ghcp-handoff next to /codex. Where /codex pulls a second opinion in, /ghcp-handoff pushes bounded mechanical work out — scaffolds, CI wiring, mechanical refactors, test generation — to the GitHub Copilot CLI (copilot) while the user keeps judgment calls in Claude.

Three modes:

• Guided (default) — interactive AskUserQuestion flow collects task summary, target branch, context files, streams, hard boundaries, NOT-in-scope paths, forbidden deps, and PR sections, renders a prompt from templates/prompt-template.md, and invokes copilot -p non-interactively with a 30-minute timeout.
• --from-plan <path> — extracts the ## The GHCP prompt section from a plan file, wraps it with a worktree instruction and embedded metadata block, then invokes copilot.
• verify <pr> — resolves the PR to a branch via gh pr view, locates the matching prompt file under .gstack/ghcp-handoff/, parses the <!-- ghcp-handoff:metadata --> YAML, and runs three checks: boundary diff (changed files vs NOT-in-scope globs), dependency deviation (new deps flagged, forbidden deps blocked), and PR body contract (required sections present). Writes a gstack-review-log JSONL entry so results surface in the Plan Status Footer. Exit code 2 is reserved for metadata parse failures so they're distinct from violations found.

Safety:

• Target branch auto-derives ghcp/<slug> and hard-rejects main, master, dev, develop, production, staging.
• Prompt instructs copilot to use a clean git worktree so parallel agents don't collide.
• Degrades gracefully if copilot isn't installed — writes the prompt file, tells the user where to paste it.

Structure follows the /browse pattern (co-located TS + tests):

ghcp-handoff/
├── SKILL.md               (generated via bun run gen:skill-docs)
├── SKILL.md.tmpl          (uses {{PREAMBLE}} + {{BASE_BRANCH_DETECT}} resolvers)
├── bin/
│   ├── ghcp-detect.sh
│   ├── ghcp-extract-plan.ts
│   ├── ghcp-verify-boundaries.ts
│   └── ghcp-verify-pr-body.ts
├── templates/
│   └── prompt-template.md
└── test/
    ├── fixtures/
    │   ├── sample-scaffold-plan.md
    │   └── sample-scaffold-expected.md
    ├── ghcp-extract-plan.test.ts
    ├── ghcp-verify-boundaries.test.ts
    └── ghcp-verify-pr-body.test.ts

Uses preamble-tier: 3 (same as /codex).

Manual followups required

1. Run ./setup after merge to register /ghcp-handoff with Claude Code (and any other configured hosts).
2. Uninstall any older standalone copy at ~/.claude/skills/ghcp-handoff/ — the fork's ./setup replaces it.
3. Upstream PR to garrytan/gstack when ready — this PR is scoped to the personal fork only.

Deviations from plan

None of substance. Minor adaptations during migration:

• Dropped the pre-migration custom gen-skill.sh + fallback files — gstack's native scripts/gen-skill-docs.ts (with {{PREAMBLE}} resolver) handles it.
• Dropped the pre-migration setup.sh, package.json, VERSION, CHANGELOG.md, tsconfig.json — gstack's root equivalents serve these.
• Test fixture paths switched from CWD-relative to import.meta.dir-based so they resolve when bun test runs from gstack root.
• Frontmatter converted to gstack's format (explicit triggers: and voice-triggers: lists).

Flagged uncertainties

• Pre-existing Windows test flakes. test/gen-skill-docs.test.ts freshness tests and test/skill-validation.test.ts gstack-slug tests fail on Windows for reasons unrelated to this PR (backslash path separators, unbuilt binaries). ghcp-handoff appears cleanly in every FRESH: list the generator produces.
• Token ceiling not exceeded. ghcp-handoff/SKILL.md is ~916 lines / ~11K tokens, well under the 100KB / 25K-token ceiling that currently flags office-hours, plan-ceo-review, and ship.
• End-to-end dogfood validated pre-migration. A real copilot invocation (Phase 1 CI-workflow scaffold task) produced a conforming PR that the verifier rated CLEAN. Not yet re-verified from inside the fork — planned as a followup after ./setup runs.
• --from-plan heading list is strict. Only ## The GHCP prompt is recognized; other variants fall through to the fallback round (guided / paste / abort). Intentional in v0.1.0 to keep the contract crisp.

Test plan

• bun run gen:skill-docs --host all generates ghcp-handoff/SKILL.md + all host variants without warnings
• bun test ghcp-handoff/test/ — 27/27 pass
• bun test test/audit-compliance.test.ts — 9/9 pass (frontmatter + style audit clean)
• bun test test/openclaw-native-skills.test.ts — 1/1 pass
• ./setup registers /ghcp-handoff with Claude Code
• Post-merge: re-run end-to-end dogfood from inside the fork

[Copilot]

Pull request overview

Adds a new /ghcp-handoff skill to delegate bounded mechanical work to the GitHub Copilot CLI, including prompt generation and post-handoff verification utilities.

Changes:

• Introduces the ghcp-handoff/ skill (template + generated SKILL.md) and a prompt template with embedded YAML metadata.
• Adds Bun-executable verification/extraction utilities (ghcp-extract-plan, ghcp-verify-boundaries, ghcp-verify-pr-body) plus tests and fixtures.
• Wires the new test suite into npm test and adds runtime deps (minimatch, yaml) needed by the verification scripts.

Reviewed changes

Copilot reviewed 10 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
package.json	Runs ghcp-handoff tests in the default test script; adds minimatch + yaml deps.
bun.lock	Locks the newly-added dependencies and their transitive deps.
CHANGELOG.md	Documents the new /ghcp-handoff skill addition.
ghcp-handoff/SKILL.md.tmpl	Skill template describing guided/from-plan/verify flows and CLI invocation/verification contracts.
ghcp-handoff/SKILL.md	Generated skill doc shipped to users/hosts.
ghcp-handoff/templates/prompt-template.md	Prompt scaffold with embedded metadata block used by verifiers.
ghcp-handoff/bin/ghcp-detect.sh	Detects copilot CLI availability/version.
ghcp-handoff/bin/ghcp-extract-plan.ts	Extracts ## The GHCP prompt content (and optional target branch) from a plan file.
ghcp-handoff/bin/ghcp-verify-boundaries.ts	Parses metadata, checks NOT-in-scope boundary violations, and detects dependency additions.
ghcp-handoff/bin/ghcp-verify-pr-body.ts	Checks PR body for required sections listed in metadata.
ghcp-handoff/test/ghcp-extract-plan.test.ts	Unit tests for plan section extraction and branch parsing.
ghcp-handoff/test/ghcp-verify-boundaries.test.ts	Unit tests for metadata parsing, boundary checks, and dep detection.
ghcp-handoff/test/ghcp-verify-pr-body.test.ts	Unit tests for PR body contract checks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.