Merge branch 'raykao/act-2'

Author: raykao

.github/prompts/write-docs.prompt.md

@@ -0,0 +1,42 @@
+# Analyze Commit and Create Documentation Issue
+
+Analyze commit `{COMMIT_SHA}` in repository `{REPOSITORY}` using the GitHub MCP server.
+
+## Your Task
+
+1. **Examine the commit** using MCP to access:
+   - Commit diff and changed files
+   - Current documentation structure
+   - Project context
+
+2. **Decide if documentation is needed** based on these criteria:
+
+   ### ✅ Document These:
+   - Public APIs/Interfaces (functions, classes, endpoints)
+   - Complex logic requiring explanation
+   - Architectural or workflow changes
+   - Breaking changes
+   - New dependencies or integrations
+   - Security/performance changes
+   - Database schemas or data models
+   - Unit tests
+
+   ### ❌ Skip These:
+   - Minor refactoring or formatting
+   - Internal helpers
+   - Trivial typo fixes
+   - Code moves without logic changes
+   - Patch dependency updates
+in the current repository
+   - Add labels: `documentation`, `automated`
+3. **If documentation is needed:**
+   - Use the GitHub MCP server to create a GitHub issue with title: "📚 Documentation needed for commit test" 
+   - Use assign_copilot_to_issue tool to assign @copilot to issue.
+   - In the issue body, explain:
+     - What changed and why it needs documentation
+     - Which documentation files should be updated
+     - Any breaking changes or migration notes needed
+   - Confirm if all steps succeeded or not.
+
+4. **If documentation is NOT needed:**
+   - Simply explain why in a brief response (no issue needed)

.github/workflows/copilot.generate-docs.yml

@@ -0,0 +1,52 @@
+name: Generate Documentation with Copilot
+
+# Modified from @sitoader's workflow at: https://github.com/sitoader/AgenticWorkflows/blob/main/.github/workflows/generate-docs.yml
+
+on:
+  workflow_dispatch:
+  push:
+    paths-ignore:
+      - 'docs/**'
+      - '**.md'
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read    # Required to read repository content and commit diffs
+      issues: write     # Required to create GitHub issues for documentation recommendations
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: Install GitHub Copilot CLI
+        run: |
+          curl -fsSL https://gh.io/copilot-install | bash
+          echo "Installed Copilot CLI version:"
+          copilot --version
+                    
+      - name: Analyze and delegate to Copilot
+        env:
+          GITHUB_MCP_TOKEN: ${{ secrets.GITHUB_TOKEN }}        # Workflow token for MCP GitHub operations (issues)
+          GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}       # Personal PAT for Copilot API authentication
+        run: |
+          echo "Analyzing commit ${{ github.sha }}"
+          echo "Loading documentation criteria from prompt..."
+          
+          PROMPT=$(cat .github/prompts/analyze-for-docs.prompt.md)
+          PROMPT="${PROMPT//\{COMMIT_SHA\}/${{ github.sha }}}"
+          PROMPT="${PROMPT//\{REPOSITORY\}/${{ github.repository }}}"
+          
+          echo "Delegating to GitHub Copilot..."
+          echo "- Copilot will use MCP to examine the commit"
+          echo "- Copilot will decide if documentation is needed"
+          echo "- Copilot will create an issue and assign it to itself if needed"
+          echo ""
+
+          copilot -p "$PROMPT" \
+            --allow-all-tools
+
+      # Todo: Add the step to commit generated docs back to the repo if desired

Act-2/README.md

@@ -0,0 +1,34 @@
+# Act-2: Standards Exist, but They’re Not Enforced
+
+Problem:
+You are part of a team that is busy doing the things you love: create solutions to problems (e.g. write code), but you do not consistently do the things you dislike (e.g. write documentation).  No blame, no shame...you're only human.
+
+Answer:
+Let the non-human do the things you dislike.
+
+## Crawl
+
+Create a reusable prompt (or agent) for the team to run arbitrarily when you have new code or new things to document.  In GitHub Copilot in VSCode you can call a reusable prompt via "Slash Commands" if you follow the folder/naming convension set out by GitHub/VScode (i.e. `<repo-root>/.github/prompts/<prompt-name>.prompt.md`).
+
+Execute this prompt locally:
+
+![write-prompt](images/write-prompt.png)
+
+## Walk/Run
+
+Create a GitHub Action Workflow that will be called upon for each push to the repo.  For this example it will be just for the main branch, but you can set up the triggers/rules for when the workflow gets run.  See the docs about [Events That Trigger Workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows).
+
+> [!NOTE]
+> We will use the GitHub Copilot CLI to automate the execution of our custom prompt in a scripted CI Runner - GitHub Actions.
+
+We have an example of this in [Act-2 .github/workflows](../.github/workflows/copilot.generate-docs.yml).
+
+### What does this do?
+
+- The GitHub Action Workflow triggers on each push to the main branch - this ensures that documentation is created, if and when needed regardless if you remembered or not.  This ensures that all team members have docs created for them, even if they did not run the `/write-docs` prompt manually before committing their changes.  It also can be run manually in GitHub Actions since it also has the `workflow_dispatch` trigger enabled...this is optional of course but we have it here as an example anyways.
+- It installs the GitHub Copilot CLI
+- It ensures that we provide it credentials to call GitHub Copilot
+> [!NOTE]
+> Currently calling GitHub Copilot is a User only ability - meaning that GitHub Copilot is licensed to and therefore only callable by a human user account. In this example we have stored a Fine-Grained GitHub Personal Access Token (PAT -> a user bound API Key) that has been scoped with the `Copilot-Requests: Read-only` Permission.  As such this will consume GitHub Copilot PRUs (Premium Request Units) from the tied user account.  Today this is the only billing model to consume GitHub Copilot.
+- Store the required prompt file contents as an environment variable
+- Pass in the prompt and call GitHub Copilot CLI to generate docs