coding-agent-workflow

name	coding-agent-workflow
description	Standard workflow for GitHub Copilot coding agents including report_progress usage, delegation handling, and PR communication patterns.

Coding Agent Workflow Skill

Purpose

Provides the standard operational workflow that all GitHub Copilot coding agents must follow when executing tasks in pull requests.

When to Use

This skill is automatically loaded by all coding agents. It defines the core workflow for:

• Handling questions (direct vs delegated contexts)
• Reporting progress with the report_progress tool
• Creating summary comments after work completion

Workflow

You are running as a GitHub Copilot coding agent. Follow this workflow:

CRITICAL: Branch and PR Management

GitHub Copilot automatically creates branches and PRs - you do NOT create them:

• When an issue is assigned to @copilot, GitHub automatically creates a copilot/* branch and draft PR
• When you start working, you're already on the correct branch with an active PR
• NEVER run git checkout, git switch, or git branch commands - you're already on the right branch
• NEVER attempt to create a new PR - one already exists for your work
• Your job is to commit work to the existing branch using report_progress (which handles git push automatically)

Why this fails:

• Manual git checkout -b commands will fail (permission denied)
• Attempting to create PRs will fail or create duplicate PRs
• These operations are GitHub's responsibility, not yours

1. For Direct Questions (When Running as Primary Agent): If you are the primary agent on a PR (not delegated via task tool), you can create PR comments to ask the Maintainer questions. Wait for a response before proceeding.

2. For Delegated Execution (When Invoked via task Tool): If you were invoked by the Workflow Orchestrator via the task tool, you run in an isolated context. In this case:

   • DO NOT attempt to create PR comments - you cannot access the parent PR from your isolated context
   • Include questions in your response - return them as part of your output text
   • The orchestrator will forward your questions to the maintainer and resume you with answers
   • Wait for the orchestrator to re-invoke you with the maintainer's answer
   • You MUST use edit/create tools to apply all file changes - do not just describe changes; actually apply them
   • You MUST use git commit to commit your changes — report_progress is NOT available to subagents; use git add <files> && git commit -m "type: message" instead (see step 4 for details)

3. Complete Your Work: Implement the requested changes following your role's guidelines. Use edit/create tools to apply all file modifications — never just describe or list changes without applying them.

4. Commit and Push Changes:

   • Primary agent (running the top-level PR): Use the report_progress tool. It handles git add, git commit, and git push automatically with the GitHub Actions token. Manual git push fails (no personal credentials). Call it with:

     • commitMessage: Conventional commit message (e.g., "feat: add feature X")
     • prDescription: Markdown checklist showing completed and remaining work

     report_progress(
       commitMessage="feat: implement user authentication",
       prDescription="""
       - [x] Add authentication service
       - [ ] Add authorization middleware
       """
     )
     

   • Delegated subagent (spawned via task tool): report_progress is NOT available — it exists only in the primary agent's tool context. Use git commit instead:

     git add <changed files>
     git commit -m "type: description of changes"
     # Do NOT run git push — it will fail with HTTP 403
     

     Your commits accumulate in the local branch. When the parent agent calls report_progress, ALL local commits (including yours) are pushed to the remote PR branch.

5. Create Summary Comment (After Progress Reported): Post a PR comment with:

   • Summary: Brief description of what you completed
   • Changes: List of key files/features modified
   • Next Agent: Recommend which agent should continue the workflow (see docs/agents.md for workflow sequence)
   • Status: Ready for next step, or Blocked (with reason)

   Note: If you're running in delegated mode (via task tool), include this summary in your response text instead of creating a PR comment.

Example Summary Comment:

✅ Implementation complete

**Summary:** Implemented feature X with tests and documentation

**Changes:**
- Added FeatureX.cs with core logic
- Added FeatureXTests.cs with 15 test cases
- Updated README.md

**Next Agent:** Technical Writer (to review documentation)
**Status:** Ready

Key Principles

• GitHub creates branches/PRs automatically - never attempt to create them yourself
• report_progress is only available to the primary agent - subagents spawned via task tool must use git commit instead
• Always use report_progress for commits and pushes (primary agent) - never use manual git push commands
• Subagents MUST git commit before completing - uncommitted changes will be lost if only in memory; the parent's report_progress can pick up uncommitted files via git add . but this is a fallback, not the primary mechanism
• Always use edit/create tools to apply file changes - never just describe changes in your response without applying them
• Respect execution context - behave differently when delegated vs primary agent
• Communicate clearly - provide complete summaries with status and next steps
• Track progress - use markdown checklists in PR descriptions to show work completed and remaining