copilot-opus-long-task-handoff

name	copilot-opus-long-task-handoff
description	Use when handling a large task that must first go through superpowers planning (brainstorming plus writing-plans) and then be executed in one GitHub Copilot CLI session with claude-opus-4.6, with live progress logs and exported session artifacts.

Copilot Opus Long Task Handoff

Overview

Use this skill for a two-phase workflow:

1. generate an approved superpowers plan for a large task, and
2. hand that plan to GitHub Copilot CLI for one autonomous execution run using claude-opus-4.6.

When to Use

• The task is long (multiple files, tests, build, verification).
• You want mandatory planning before implementation.
• You want one autonomous Copilot session without mid-task technical questions.
• You need repeatable command lines and session artifacts (.state/*.md, .state/*.log).
• You want live progress output while the job runs.

Do not use this skill for small single-file edits.

Required Workflow

Follow this order strictly.

Phase 1: Superpowers planning

1. Use superpowers brainstorming to align scope and design.
2. Use superpowers writing-plans to produce an implementation plan file.
3. Get explicit user confirmation on the plan file.
4. Do not execute Copilot before plan confirmation.

Phase 2: Copilot execution

After plan approval, run one Copilot session with:

• model: claude-opus-4.6
• autonomous mode (--no-ask-user)
• live logs and session export in .state/

Required Inputs For Execution

• Repo root path (default: current directory)
• Plan file path (for example docs/superpowers/plans/2026-03-30-xxx.md)
• Optional extra guardrails (for example: files to keep untouched)

Monitoring Modes

Choose one mode after starting Copilot.

Mode A: No Polling (lowest token cost)

• Start Copilot and return only:
  • PID
  • session file path
  • log file path
  • user-side progress commands (tail -f, watch git status)
• Do not poll progress in-chat.
• Wait for user to say completion.

Mode B: Auto Notify (low-frequency polling)

• Poll every 60 seconds.
• Check only:
  • Copilot process exit state
  • session file existence
• Do not stream long logs back into chat.
• Send one completion message with summary when done.

Quick Start

Run from repo root:

~/.codex/skills/copilot-opus-long-task-handoff/scripts/run-copilot-opus-long-task.sh \
  --plan docs/superpowers/plans/2026-03-30-vue-front-categories-readability-implementation.md \
  --extra "Keep unrelated file content/probe/_index.md untouched." \
  --stream on

This command will:

• Build a strict prompt around the plan
• Run gh copilot with --model claude-opus-4.6 (default)
• Write live logs to .state/
• Export session markdown to .state/

Direct Command Template (Without Script)

cd <repo-root>

gh copilot -- \
  --model claude-opus-4.6 \
  --reasoning-effort high \
  --prompt "Implement <plan-path> end-to-end with strict TDD. Do not ask user technical questions. Execute all verification commands and report changed files plus pass/fail outputs." \
  --allow-all \
  --no-ask-user \
  --autopilot \
  --stream on \
  --share .state/copilot-<task>-session.md \
  2>&1 | tee .state/copilot-<task>-live.log

Progress Monitoring

Use a second terminal:

cd <repo-root>
watch -n 2 'git status --short'

tail -f <repo-root>/.state/copilot-<task>-live.log

Completion Checklist

After Copilot exits, verify:

1. Session file exists (.state/*-session.md)
2. Log file exists (.state/*-live.log)
3. Copilot output includes:
   • changed files
   • behavior changes
   • verification commands with pass/fail
4. Manually re-run critical verification if task is high-risk

Common Mistakes

• Skipping superpowers planning before Copilot execution
• Forgetting --model claude-opus-4.6 (wrong model used)
• Missing --no-ask-user (session may block waiting for input)
• Not writing logs (no progress/audit trail)
• Missing explicit "untouched files" guardrail in prompt