copilot

DEPRECATED: This skill is replaced by the copilot-operator agent. Use Agent(subagent_type="htmlgraph:copilot-operator", prompt="...") instead. The copilot-operator agent tries Copilot CLI first with hook-based compliance verification.

GitHub Copilot & GitHub CLI (gh) Operations

⚠️ IMPORTANT: This skill provides TWO EXECUTION PATTERNS

1. GitHub CLI (gh) - Documentation for command syntax. Execute via Bash tool.
2. CopilotSpawner - AI-powered code generation. Invoke via Python SDK with parent event context.

This skill teaches HOW to use both. See "EXECUTION PATTERNS" below for when to use each.

---

🚀 CopilotSpawner Pattern: Full Event Tracking

What is CopilotSpawner?

CopilotSpawner is the HtmlGraph-integrated way to invoke external CLIs (Copilot, Gemini, Codex) with full parent event context and subprocess tracking.

Key distinction: CopilotSpawner is invoked directly via Python SDK - NOT wrapped in Task(). Task() is only for Claude subagents (Haiku, Sonnet, Opus).

Instead of running CLI commands directly (which creates "black boxes"), CopilotSpawner:

• ✅ Invokes external Copilot CLI directly
• ✅ Creates parent event context in database
• ✅ Links to parent Task delegation event
• ✅ Records subprocess invocations as child events
• ✅ Tracks all activities in HtmlGraph event hierarchy
• ✅ Provides full observability of external tool execution

When to Use CopilotSpawner

Use CopilotSpawner when:

• You need to invoke external CLIs (copilot, gemini, codex)
• You want full event tracking in HtmlGraph
• Parent event context is available (from hooks)
• You need subprocess event recording
• You're in a Claude Code session with hook system

Use Bash directly when:

• Running simple one-off commands
• No tracking needed
• Testing/debugging
• Not in Claude Code environment

How to Use CopilotSpawner

import os
import sys
from pathlib import Path
from datetime import datetime, timezone
import uuid

# Add plugin agents directory to path
PLUGIN_AGENTS_DIR = Path("/path/to/htmlgraph/packages/claude-plugin/.claude-plugin/agents")
sys.path.insert(0, str(PLUGIN_AGENTS_DIR))

from htmlgraph import SDK
from htmlgraph.orchestration.spawners import CopilotSpawner
from htmlgraph.db.schema import HtmlGraphDB
from htmlgraph.config import get_database_path
from spawner_event_tracker import SpawnerEventTracker

# Initialize
sdk = SDK(agent='claude')
db = HtmlGraphDB(str(get_database_path()))
session_id = f"sess-{uuid.uuid4().hex[:8]}"
db._ensure_session_exists(session_id, "claude")

# Create parent event context (like PreToolUse hook does)
user_query_event_id = f"event-query-{uuid.uuid4().hex[:8]}"
parent_event_id = f"event-{uuid.uuid4().hex[:8]}"
start_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")

# Insert UserQuery event
db.connection.cursor().execute(
    """INSERT INTO agent_events
       (event_id, agent_id, event_type, session_id, tool_name, input_summary, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
    (user_query_event_id, "claude-code", "tool_call", session_id, "UserPromptSubmit",
     "Test git workflow", "completed", start_time)
)

# Insert Task delegation event
db.connection.cursor().execute(
    """INSERT INTO agent_events
       (event_id, agent_id, event_type, session_id, tool_name, input_summary,
        context, parent_event_id, subagent_type, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
    (parent_event_id, "claude-code", "task_delegation", session_id, "Task",
     "Guide git workflow", '{"subagent_type":"general-purpose"}',
     user_query_event_id, "general-purpose", "started", start_time)
)
db.connection.commit()

# Export parent context (like PreToolUse hook does)
os.environ["HTMLGRAPH_PARENT_EVENT"] = parent_event_id
os.environ["HTMLGRAPH_PARENT_SESSION"] = session_id
os.environ["HTMLGRAPH_SESSION_ID"] = session_id

# Create tracker with parent context
tracker = SpawnerEventTracker(
    delegation_event_id=parent_event_id,
    parent_agent="claude",
    spawner_type="copilot",
    session_id=session_id
)
tracker.db = db

# Invoke CopilotSpawner with FULL tracking
spawner = CopilotSpawner()
result = spawner.spawn(
    prompt="Recommend next semantic version and git workflow commands",
    track_in_htmlgraph=True,      # Enable SDK activity tracking
    tracker=tracker,               # Enable subprocess event tracking
    parent_event_id=parent_event_id,  # Link to parent event
    allow_all_tools=True,
    timeout=120
)

# Check results
print(f"Success: {result.success}")
print(f"Response: {result.response}")
if result.tracked_events:
    print(f"Tracked {len(result.tracked_events)} events in HtmlGraph")

Key Parameters for CopilotSpawner.spawn()

Parameter	Type	Required	Description
prompt	str	✅	Task description for Copilot
track_in_htmlgraph	bool	❌	Enable SDK activity tracking (default: True)
tracker	SpawnerEventTracker	❌	Tracker instance for subprocess events
parent_event_id	str	❌	Parent event ID for event hierarchy
allow_tools	list[str]	❌	Tools to auto-approve (e.g., ["shell(git)"])
allow_all_tools	bool	❌	Auto-approve all tools (default: False)
deny_tools	list[str]	❌	Tools to deny
timeout	int	❌	Max seconds to wait (default: 120)

Event Tracking Hierarchy

With CopilotSpawner, you get this event hierarchy in HtmlGraph:

UserQuery Event (from UserPromptSubmit hook)
├── Task Delegation Event (from PreToolUse hook)
    ├── CopilotSpawner Start (activity tracking)
    ├── Subprocess Invocation (subprocess event)
    │   └── subprocess.copilot tool call
    ├── CopilotSpawner Result (activity tracking)
    └── All activities linked with parent_event_id

This provides complete observability - no "black boxes" for external tool execution.

Real Example: Version Update Workflow

# See above code example + this prompt:
result = spawner.spawn(
    prompt="""HtmlGraph project status:
    - Completed CLI module refactoring (all tests passing)
    - Completed skill documentation clarification
    - Completed spawner architecture modularization
    - Current version: ~0.26.x

    Please recommend:
    1. Next semantic version (MAJOR.MINOR.PATCH)
    2. Version update git workflow including all necessary files
    3. Tag and push commands
    """,
    track_in_htmlgraph=True,
    tracker=tracker,
    parent_event_id=parent_event_id,
    allow_all_tools=True,
    timeout=120
)

# Result: Full tracking with Copilot's version recommendation (0.27.0)
# All subprocess invocations recorded in HtmlGraph

Fallback & Error Handling Pattern

CRITICAL: If external spawner fails, delegate to Claude sub-agent (NOT direct execution).

# Try external spawner first
try:
    spawner = CopilotSpawner()
    result = spawner.spawn(
        prompt="Your task",
        tracker=tracker,
        parent_event_id=parent_event_id,
        allow_all_tools=True,
        timeout=120
    )

    if result.success:
        return result  # Success, use spawner result
    else:
        # Spawner returned error result
        raise Exception(f"Spawner failed: {result.error}")

except Exception as e:
    # External spawner failed (CLI not installed, timeout, permission denied, etc.)
    # FALLBACK to Claude sub-agent - do NOT attempt direct execution
    print(f"⚠️ CopilotSpawner failed: {e}")
    print("📌 Falling back to Claude sub-agent...")

    return Task(
        subagent_type="general-purpose",
        prompt="Your task here"
    )
    # Task() guarantees execution via Claude

Why fallback to Task()?

• ✅ External CLI may not be installed on user's system
• ✅ Network/permissions issues may affect external tools
• ✅ Claude sub-agent provides guaranteed execution fallback
• ✅ Never attempt direct execution as fallback (violates orchestration principles)
• ✅ Task() handles all retries, error recovery, and parent context automatically

Pattern Summary:

1. Try external spawner first (Copilot CLI)
2. If spawner succeeds → return result
3. If spawner fails → delegate to Claude sub-agent via Task()
4. Never try direct execution as fallback

---

What is GitHub CLI (gh)?

GitHub CLI (gh) is a command-line tool for GitHub operations:

• Pull Requests - Create, view, merge, and manage PRs
• Issues - Create, list, and manage GitHub issues
• Repositories - Clone, fork, and manage repos
• Authentication - Manage GitHub credentials and tokens
• Workflows - Trigger and view GitHub Actions

Works in your terminal with the gh command.

Skill vs Execution Model

CRITICAL DISTINCTION:

What	Description
This Skill	Documentation teaching HOW to use gh CLI
Bash Tool	ACTUAL execution of gh commands

Workflow:

1. Read this skill to learn gh CLI syntax and options
2. Use Bash tool to execute the actual commands
3. Use SDK to track results in HtmlGraph

Installation

# Install GitHub CLI
# macOS
brew install gh

# Ubuntu/Debian
sudo apt update && sudo apt install gh

# Windows
choco install gh

# Authenticate with GitHub
gh auth login

# Verify installation
gh --version

EXECUTION - Real Commands to Use in Bash Tool

⚠️ To actually execute GitHub operations, use these commands via the Bash tool:

Create Pull Request

# Basic PR creation
gh pr create --title "Feature: Add authentication" --body "Implements JWT auth"

# PR with multiple options
gh pr create --title "Fix bug" --body "Description" --base main --head feature-branch

# Interactive PR creation
gh pr create --web

Manage Issues

# Create issue
gh issue create --title "Bug: Login fails" --body "Steps to reproduce..."

# List issues
gh issue list --state open

# View issue
gh issue view 123

Repository Operations

# Clone repository
gh repo clone owner/repo

# Fork repository
gh repo fork owner/repo --clone

# Create repository
gh repo create my-new-repo --public

Git Operations via gh

# Check status and create commit
git add . && git commit -m "feat: add new feature"

# Push and create PR in one command
git push && gh pr create --fill

# View PR status
gh pr status

How to Use This Skill

STEP 1: Read this skill to learn gh CLI syntax

# This loads the documentation (this file)
Skill(skill=".claude-plugin:copilot")

STEP 2: Execute commands via Bash tool

# This ACTUALLY creates a PR
Bash("gh pr create --title 'Feature' --body 'Description'")

# This ACTUALLY creates an issue
Bash("gh issue create --title 'Bug' --body 'Details'")

# This ACTUALLY clones a repo
Bash("gh repo clone user/repo")

What this skill does:

• ✅ Provides documentation and examples
• ✅ Teaches gh CLI syntax and options
• ✅ Shows common workflows and patterns
• ❌ Does NOT execute commands
• ❌ Does NOT create PRs or issues
• ❌ Does NOT run git operations

To execute: Use Bash tool with the commands shown in "EXECUTION" section.

Example Use Cases (Execute via Bash)

1. Pull Request Workflows

# Create PR after committing changes
Bash("gh pr create --title 'Add feature X' --body 'Implements X with tests'")

# Create draft PR
Bash("gh pr create --draft --title 'WIP: Feature Y'")

# List your PRs
Bash("gh pr list --author @me")

# Merge PR
Bash("gh pr merge 123 --squash")

2. Issue Management

# Create bug report
Bash("gh issue create --title 'Bug: Auth fails' --body 'Steps: 1. Login 2. Error'")

# List open issues
Bash("gh issue list --state open")

# Close issue
Bash("gh issue close 456")

3. Repository Operations

# Clone repo
Bash("gh repo clone anthropics/claude-code")

# Fork and clone
Bash("gh repo fork user/repo --clone")

# View repo details
Bash("gh repo view")

4. Commit and Push Workflows

# Commit all changes and create PR
Bash("git add . && git commit -m 'feat: new feature' && git push && gh pr create --fill")

# Amend last commit and force push
Bash("git commit --amend --no-edit && git push --force-with-lease")

# Check PR status
Bash("gh pr status")

5. GitHub Actions

# List workflow runs
Bash("gh run list")

# View specific run
Bash("gh run view 123")

# Re-run failed jobs
Bash("gh run rerun 123 --failed")

Use Cases

• Pull Requests - Create, manage, and merge PRs via command line
• Issues - Create and track GitHub issues efficiently
• Repository Management - Clone, fork, and configure repos
• Authentication - Manage GitHub credentials and tokens
• CI/CD - Trigger and monitor GitHub Actions workflows
• Code Review - View and comment on PRs from terminal

Requirements

• GitHub account
• gh CLI installed
• Authenticated via gh auth login
• Git configured (for git operations)

Integration with HtmlGraph

Track GitHub operations in features:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Document PR creation
feature = sdk.features.create(
    title="Authentication Feature PR",
    description="""
    Created PR via gh CLI:
    - Title: Add JWT authentication
    - Branch: feature/jwt-auth
    - Status: Ready for review

    Command used:
    gh pr create --title "Add JWT auth" --body "Full implementation with tests"
    """
).save()

When to Use

✅ Use GitHub CLI (gh) for:

• Creating and managing pull requests
• Creating and tracking issues
• Cloning and forking repositories
• GitHub authentication
• Viewing and managing workflows
• Command-line GitHub operations

❌ Don't use gh CLI for:

• Code generation (use Task() delegation or direct implementation)
• Exploring codebases (use /gemini skill instead)
• Complex git operations (use git commands directly)
• Local file operations (use standard bash/python)

Tips for Best Results

1. Use --fill flag - Auto-populate PR details from commits: gh pr create --fill
2. Check status first - Run gh pr status or gh issue list before creating new items
3. Use templates - Leverage repository issue/PR templates when available
4. Authenticate early - Run gh auth login at start of session
5. Combine with git - Chain git and gh commands: git push && gh pr create
6. Use --web flag - Open operations in browser when needed: gh pr create --web

Common Patterns (Execute via Bash)

Pattern 1: Feature Development Workflow

# 1. Create feature branch
Bash("git checkout -b feature/new-feature")

# 2. Make changes, commit
Bash("git add . && git commit -m 'feat: implement feature'")

# 3. Push and create PR
Bash("git push -u origin feature/new-feature && gh pr create --fill")

Pattern 2: Bug Fix Workflow

# 1. Create issue for bug
Bash("gh issue create --title 'Bug: Description' --body 'Steps to reproduce'")

# 2. Create branch from issue
Bash("git checkout -b fix/issue-123")

# 3. Fix, commit, and create PR
Bash("git add . && git commit -m 'fix: resolve issue #123' && gh pr create --fill")

Pattern 3: Quick PR Creation

# 1. Commit all changes
Bash("git add . && git commit -m 'feat: quick feature'")

# 2. Push and create PR in one command
Bash("git push && gh pr create --title 'Quick Feature' --body 'Description'")

Limitations

• Requires GitHub account and authentication
• Internet connection required for GitHub API
• Rate limits apply to API calls
• Some operations require repository permissions
• Cannot execute local git operations (use git directly)

Related Skills

• /gemini - For exploring repository structure and large codebases
• /codex - For code generation and implementation
• /code-quality - For validating code quality before creating PR
• Git commands - For local repository operations (use Bash directly)

When NOT to Use

Avoid GitHub CLI for:

• Code generation (use Task() delegation)
• Exploratory research (use /gemini skill)
• Local file operations (use standard bash commands)
• Operations not related to GitHub (use appropriate tool)

Error Handling (Use Bash for Diagnostics)

GitHub CLI Not Installed

Error: "gh: command not found"

Solution (via Bash):
# macOS
Bash("brew install gh")

# Verify
Bash("gh --version")

Authentication Required

Error: "authentication required"

Solution (via Bash):
Bash("gh auth login")
# Follow prompts in terminal

Permission Denied

Error: "permission denied to repository"

Solution (via Bash):
# Check authentication status
Bash("gh auth status")

# Re-authenticate if needed
Bash("gh auth login --force")

Advanced Usage (Execute via Bash)

PR with Reviewers and Labels

Bash("gh pr create --title 'Feature' --body 'Desc' --reviewer user1,user2 --label bug,enhancement")

Create Issue from Template

Bash("gh issue create --template bug_report.md")

Batch Operations

# Close multiple issues
Bash("gh issue list --state open --json number --jq '.[].number' | xargs -I {} gh issue close {}")

Integration with Git Workflows

# Rebase and force push
Bash("git rebase main && git push --force-with-lease && gh pr ready")

# Squash commits and update PR
Bash("git rebase -i HEAD~3 && git push --force-with-lease")

Key Features

Feature	GitHub CLI (gh)	Description
Pull Requests	✅	Create, merge, review, comment
Issues	✅	Create, list, close, assign
Repositories	✅	Clone, fork, create, view
Authentication	✅	Login, status, token management
GitHub Actions	✅	List, view, re-run workflows
API Access	✅	Direct GitHub API calls via gh api