workflow: GitHub hooks automation for coding agents

.github/workflows/issue-copilot-assign.yml

@@ -0,0 +1,27 @@
+name: Auto-assign issue to Copilot
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  issues: write
+
+jobs:
+  assign-to-copilot:
+    name: Assign to Copilot
+    runs-on: ubuntu-latest
+    if: github.event.label.name == 'copilot'
+
+    steps:
+      - name: Assign issue to @copilot
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.addAssignees({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              assignees: ['copilot'],
+            });
+            console.log(`Assigned issue #${context.issue.number} to @copilot`);

.github/workflows/pr-merge-retrospective.yml

@@ -0,0 +1,71 @@
+name: Retrospective reminder on PR merge
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  retrospective-reminder:
+    name: Post retrospective reminder
+    runs-on: ubuntu-latest
+    # Only run for merged PRs on feature or fix branches
+    if: |
+      github.event.pull_request.merged == true &&
+      (startsWith(github.event.pull_request.head.ref, 'feature/') ||
+       startsWith(github.event.pull_request.head.ref, 'fix/'))
+
+    steps:
+      - name: Extract work item info
+        id: workitem
+        run: |
+          BRANCH="${{ github.event.pull_request.head.ref }}"
+
+          # Extract prefix and slug from branch name (e.g. feature/123-my-feature)
+          if [[ "$BRANCH" =~ ^feature/([0-9]+-[^/]+)$ ]]; then
+            SLUG="${BASH_REMATCH[1]}"
+            WORK_ITEM_PATH="docs/features/${SLUG}"
+            WORK_TYPE="feature"
+          elif [[ "$BRANCH" =~ ^fix/([0-9]+-[^/]+)$ ]]; then
+            SLUG="${BASH_REMATCH[1]}"
+            WORK_ITEM_PATH="docs/issues/${SLUG}"
+            WORK_TYPE="bug fix"
+          else
+            WORK_ITEM_PATH="(unknown - check branch name convention)"
+            WORK_TYPE="change"
+          fi
+
+          echo "work_item_path=${WORK_ITEM_PATH}" >> "$GITHUB_OUTPUT"
+          echo "work_type=${WORK_TYPE}" >> "$GITHUB_OUTPUT"
+
+      - name: Post retrospective reminder comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const workItemPath = '${{ steps.workitem.outputs.work_item_path }}';
+            const workType = '${{ steps.workitem.outputs.work_type }}';
+            const branch = '${{ github.event.pull_request.head.ref }}';
+
+            const body = [
+              '## 📝 Retrospective reminder',
+              '',
+              `This ${workType} PR has been merged. Don't forget to run the **Retrospective** agent to capture learnings and improvement opportunities.`,
+              '',
+              '**Work item folder:** `' + workItemPath + '/`',
+              '',
+              '**How to run:**',
+              '- **VS Code:** Start a chat with `@retrospective` and provide the work item path above',
+              '- **GitHub (automated):** Create a new issue describing the retrospective task and label it with `copilot`',
+              '',
+              '_This comment is posted automatically by the retrospective reminder workflow._',
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body,
+            });

docs/agents.md

@@ -23,7 +23,7 @@ Throughout the workflow, the Maintainer coordinates handoffs between agents and
 
 For well-defined features or bugs, use the **Workflow Orchestrator** agent to automate the complete workflow:
 
-- **GitHub (Cloud) - RECOMMENDED**: Assign a GitHub issue to `@copilot` to trigger automated orchestration from issue to release. The orchestrator runs as a coding agent with full delegation capabilities via the `task` tool.
+- **GitHub (Cloud) - RECOMMENDED**: Label a GitHub issue with `copilot` to automatically assign it to `@copilot` and trigger automated orchestration from issue to release. Alternatively, manually assign the issue to `@copilot`. The orchestrator runs as a coding agent with full delegation capabilities via the `task` tool.
 - **VS Code (Local) - LIMITED**: Use `@workflow-orchestrator` in chat for interactive orchestration. Note that full programmatic delegation is limited in VS Code context compared to GitHub.
 
 **How It Works**:
@@ -47,6 +47,40 @@ For well-defined features or bugs, use the **Workflow Orchestrator** agent to au
 
 ---
 
+## GitHub Hooks Automation
+
+Several GitHub Actions workflows automate recurring steps in the agent workflow so the Maintainer doesn't need to perform them manually.
+
+### Issue Label → Auto-assign to @copilot
+
+**Workflow:** `.github/workflows/issue-copilot-assign.yml`
+**Trigger:** `issues.labeled` — label name = `copilot`
+
+When an issue is labeled with `copilot`, GitHub Actions automatically assigns it to `@copilot`. GitHub's native @copilot assignment then creates a `copilot/*` branch and draft PR, and the Workflow Orchestrator coding agent starts running.
+
+**Usage:** Add the `copilot` label to any issue to kick off fully automated end-to-end implementation.
+
+### PR Merge → Retrospective Reminder
+
+**Workflow:** `.github/workflows/pr-merge-retrospective.yml`
+**Trigger:** `pull_request.closed` — merged = true, base branch = `main`, head branch matches `feature/*` or `fix/*`
+
+When a feature or fix PR is merged, GitHub Actions posts a comment on the PR reminding the team to run the Retrospective agent. The comment includes the work item folder path (inferred from the branch name) and instructions for both VS Code and GitHub execution modes.
+
+**Purpose:** Ensures the retrospective step is never skipped after a delivery.
+
+### Future Automation Opportunities
+
+The following GitHub events have been identified as candidates for future workflow automation (see `docs/workflow/117-github-hooks-automation/tasks.md`):
+
+| ID | Automation | Trigger | Status |
+|----|-----------|---------|--------|
+| 3 | PR review CHANGES_REQUESTED → developer notification | `pull_request_review.submitted` | ⬜ Not started |
+| 4 | CI failure → structured developer feedback | `workflow_run.completed` (failure) | ⬜ Not started |
+| 7 | Weekly agent validation health check | `schedule` | ⬜ Not started |
+
+---
+
 ## Agent Execution Contexts
 
 All agents exist in two variants optimized for their execution environment:

docs/workflow/117-github-hooks-automation/tasks.md

@@ -0,0 +1,94 @@
+# GitHub Hooks Automation — Candidate Improvements
+
+## Background
+
+This work item explores how GitHub Actions event hooks can improve and automate the agent-based development workflow. The current workflow uses GitHub Actions for CI/CD (build, test, release), but several high-value GitHub events are not yet leveraged for agent workflow automation.
+
+### Currently Used GitHub Events
+
+| Event | Workflow | Purpose |
+|-------|----------|---------|
+| `push` → `main` | `ci.yml` | Versioning after merge |
+| `pull_request` → `main` | `pr-validation.yml` | Build, test, lint, coverage |
+| `pull_request` → `main` | `uat-validate.yml` | UAT script validation |
+| `push` → `v*` tags | `release.yml` | Binary release |
+| `workflow_run` (CI) | `release.yml` | Post-CI release |
+| `workflow_dispatch` | `release.yml` | Manual release trigger |
+| `push` → `main` | `deploy-website.yml` | Website deployment |
+
+### Unused GitHub Events with Workflow Potential
+
+| Event | Trigger Condition | Agent Workflow Relevance |
+|-------|-------------------|--------------------------|
+| `issues.labeled` | Label added to issue | Trigger @copilot assignment |
+| `pull_request.closed` (merged) | PR merged to main | Trigger retrospective |
+| `pull_request_review.submitted` | Review with CHANGES_REQUESTED | Notify developer agent |
+| `issue_comment.created` | Comment on issue | Parse agent routing keywords |
+| `issues.assigned` | Issue assigned to user | Create feature branch |
+| `check_run.completed` | CI check fails on PR | Developer re-invocation |
+| `label.created` | New label added | Repository labeling maintenance |
+| `pull_request.labeled` | Label added to PR | Agent action dispatch |
+
+---
+
+## Candidate Workflow Improvements
+
+| ID | Title | Source | Status | Rationale | Impact | Effort | Risk | Notes |
+|---:|---|---|---|---|---|---|---|---|
+| 1 | Issue label → auto-assign to @copilot | exploration | ✅ Done | Eliminates the manual step of assigning an issue to @copilot after labeling. Maintainer labels issue with `copilot` and the workflow orchestrator is automatically triggered. | High | Low | Low | Adds `copilot` label + `.github/workflows/issue-copilot-assign.yml` |
+| 2 | PR merge → retrospective reminder | exploration | ✅ Done | After a feature/fix PR is merged, the workflow currently ends without a structured reminder to run the retrospective agent. Automating this comment ensures retrospective is never skipped. | Medium | Low | Low | `.github/workflows/pr-merge-retrospective.yml`; only triggers on feature/fix branches |
+| 3 | PR review CHANGES_REQUESTED → developer notification | exploration | ⬜ Not started | When a reviewer submits CHANGES_REQUESTED, the developer agent should be re-invoked. Currently this is a manual step. A structured GitHub Actions comment on the PR provides the developer coding agent the context to act on feedback. | High | Medium | Medium | Requires careful comment format to avoid false triggers |
+| 4 | CI failure → structured developer feedback | exploration | ⬜ Not started | When CI fails on a `copilot/*` branch, post a structured comment that helps the developer coding agent understand the failure and act autonomously. | High | Medium | Medium | Must parse CI failure details for agent context |
+| 5 | Issue comment keyword routing | exploration | ⬜ Not started | Parse issue/PR comments for `/assign-to:agent-name` keywords to route to specific agents. | Medium | High | High | Complex; risk of unintended triggers |
+| 6 | Release tag → close work item issues | exploration | ⬜ Not started | When a release tag is pushed, auto-close or comment on issues resolved in that release. | Low | Medium | Low | Requires convention for linking issues to releases |
+| 7 | Weekly agent workflow health check | exploration | ⬜ Not started | Scheduled workflow (`schedule` event) that validates agent definitions, checks for broken tool references, and posts a summary issue. | Medium | Medium | Low | Uses `scripts/validate-agents.py` |
+
+---
+
+## Implementation Summary (Items 1 & 2)
+
+### Item 1: Issue Label → Auto-assign to @copilot
+
+**File:** `.github/workflows/issue-copilot-assign.yml`
+
+**Trigger:** `issues.labeled` when label = `copilot`
+
+**Behavior:**
+1. When any issue is labeled with `copilot`, GitHub Actions assigns it to `@copilot`
+2. GitHub's native @copilot assignment then automatically creates a `copilot/*` branch and PR
+3. The workflow orchestrator coding agent runs automatically
+
+**Benefits:**
+- Maintainer only needs to add a label — no manual assignment step
+- Integrates seamlessly with existing @copilot orchestration
+- Zero risk to existing workflows (new independent workflow)
+
+### Item 2: PR Merge → Retrospective Reminder
+
+**File:** `.github/workflows/pr-merge-retrospective.yml`
+
+**Trigger:** `pull_request.closed` when `merged = true` and base branch = `main`
+
+**Behavior:**
+1. Detects if merged PR is a feature or fix branch (pattern: `feature/*` or `fix/*`)
+2. Posts a structured comment on the merged PR with:
+   - Link to retrospective agent instructions
+   - Work item folder path inferred from branch name
+   - Clear call-to-action for running the retrospective agent
+
+**Benefits:**
+- Ensures retrospective is never skipped after a feature/fix delivery
+- Low risk — purely informational comment on already-merged PR
+- Works with both manual (@workflow-orchestrator) and automated (@copilot) flows
+
+---
+
+## Recommendations
+
+- **Option 1 (Best balance of effort/impact):** **Items 1 + 2** — Both are low-effort, high-value automations that directly support the coding agent workflow. Implemented together in this PR.
+- **Option 2 (Next quick win):** **Item 7** — Scheduled agent validation check; reuses existing `scripts/validate-agents.py`.
+- **Option 3 (Highest impact, more work):** **Items 3 + 4** — PR review and CI failure notifications would close the feedback loop for autonomous coding agents but require more careful design.
+
+## Decision
+
+Items 1 and 2 have been implemented in this PR. Items 3–7 are documented for future workflow improvement sprints.

docs/workflow/117-github-hooks-automation/work-protocol.md

@@ -0,0 +1,21 @@
+# Work Protocol: GitHub Hooks Automation for Coding Agents
+
+**Work Item:** `docs/workflow/117-github-hooks-automation/`
+**Branch:** `copilot/explore-github-hooks-automation`
+**Workflow Type:** Workflow
+**Created:** 2026-03-17
+
+## Agent Work Log
+
+<!-- Each agent appends their entry below when they complete their work. -->
+
+### Workflow Engineer
+- **Date:** 2026-03-17
+- **Summary:** Explored GitHub Actions event hooks not currently leveraged, identified automation opportunities, created candidate task list, implemented the two highest-value automations (issue-label→copilot-assign, PR-merge→retrospective-reminder), and updated docs/agents.md to document the new workflows.
+- **Artifacts Produced:**
+  - `docs/workflow/117-github-hooks-automation/work-protocol.md` (this file)
+  - `docs/workflow/117-github-hooks-automation/tasks.md`
+  - `.github/workflows/issue-copilot-assign.yml`
+  - `.github/workflows/pr-merge-retrospective.yml`
+  - `docs/agents.md` (updated GitHub hooks automation section)
+- **Problems Encountered:** None