Add pr_docs_update workflow job for automated documentation sync from merged PRs

.deepwork/jobs/pr_docs_update/AGENTS.md

@@ -0,0 +1,70 @@
+# Project Context for pr_docs_update
+
+This job automatically updates documentation by analyzing recently merged pull requests.
+
+## Purpose
+
+The `pr_docs_update` job helps maintain up-to-date AGENTS.md files and copilot-specific instructions by:
+- Fetching recently merged PRs from the GitHub repository
+- Analyzing PR content for documentation-relevant changes
+- Updating appropriate documentation files
+- Tracking processed PRs to enable incremental updates
+
+## Dual Location Maintenance
+
+**Important**: This is an example job that can be used in any repository. If you're working on the DeepWork repository itself and want to make this a standard job, follow the dual location pattern:
+
+1. **Source of truth**: `src/deepwork/standard_jobs/pr_docs_update/`
+   - Make changes here first
+   - Tracked in version control
+
+2. **Working copy**: `.deepwork/jobs/pr_docs_update/`
+   - Updated from source using `deepwork install`
+   - Used by `deepwork sync` to generate commands
+
+## File Organization
+
+```
+pr_docs_update/
+├── AGENTS.md              # This file
+├── job.yml                # Job definition
+└── steps/
+    ├── fetch_prs.md       # Fetch merged PRs from GitHub
+    ├── analyze_prs.md     # Analyze PR content
+    └── update_docs.md     # Update documentation files
+```
+
+## How It Works
+
+1. **State Tracking**: Uses `.deepwork/pr_docs_state.json` to track processed PRs
+2. **Incremental Processing**: Only processes new PRs, skips already-processed ones
+3. **Flexible Configuration**: Can specify PR count and state file location
+4. **Multiple Runs**: Can be run repeatedly to go deeper into PR history
+
+## Usage Notes
+
+- Run periodically (e.g., weekly) to keep documentation current
+- Increase `pr_count` parameter to process more PRs at once
+- State file prevents duplicate processing across runs
+- Can be used in any repository with GitHub PRs
+
+## State File Format
+
+```json
+{
+  "processed_prs": [123, 456, 789],
+  "last_update": "2026-01-19T07:00:00Z",
+  "total_processed": 3
+}
+```
+
+## Requirements
+
+- GitHub API access (uses GitHub MCP tools)
+- Write access to documentation files
+- Git repository with GitHub remote
+
+## Last Updated
+
+- Date: 2026-01-19
+- From: Initial job creation

.deepwork/jobs/pr_docs_update/USAGE.md

@@ -0,0 +1,162 @@
+# PR Documentation Update Job - Example Usage
+
+This document provides example usage scenarios for the `pr_docs_update` job.
+
+## Overview
+
+The `pr_docs_update` job automatically updates documentation by analyzing recently merged pull requests. It's designed to:
+- Keep AGENTS.md files up to date with code changes
+- Update copilot-specific instructions when relevant
+- Track processed PRs to avoid duplicates
+- Enable incremental processing across multiple runs
+
+## Basic Usage
+
+### First Run - Process Last 10 PRs
+
+```bash
+# Run all steps to process the 10 most recent merged PRs
+/pr_docs_update.fetch_prs
+/pr_docs_update.analyze_prs
+/pr_docs_update.update_docs
+```
+
+The job will:
+1. Fetch the 10 most recent merged PRs
+2. Filter out any already processed (from state file)
+3. Analyze each PR for documentation relevance
+4. Update appropriate documentation files
+5. Save processed PR numbers to state file
+
+### Subsequent Runs - Process More PRs
+
+```bash
+# Run with a higher count to go deeper into history
+# The state file automatically skips already-processed PRs
+/pr_docs_update.fetch_prs pr_count=20
+/pr_docs_update.analyze_prs
+/pr_docs_update.update_docs
+```
+
+## Advanced Usage
+
+### Custom State File Location
+
+If you want to track state separately for different purposes:
+
+```bash
+/pr_docs_update.fetch_prs state_file=".deepwork/pr_docs_copilot_state.json"
+/pr_docs_update.analyze_prs
+/pr_docs_update.update_docs state_file=".deepwork/pr_docs_copilot_state.json"
+```
+
+### Reprocessing Specific PRs
+
+To reprocess specific PRs, edit the state file:
+
+```bash
+# View current state
+cat .deepwork/pr_docs_state.json
+
+# Remove specific PR numbers you want to reprocess
+# Edit the file and remove those numbers from the "processed_prs" array
+```
+
+### Processing Large Batches
+
+For initial setup or catching up after a long time:
+
+```bash
+# Process 50 PRs at once
+/pr_docs_update.fetch_prs pr_count=50
+/pr_docs_update.analyze_prs
+/pr_docs_update.update_docs
+```
+
+## State File Structure
+
+The state file (`.deepwork/pr_docs_state.json`) tracks processed PRs:
+
+```json
+{
+  "processed_prs": [123, 456, 789],
+  "last_update": "2026-01-19T07:00:00Z",
+  "total_processed": 3
+}
+```
+
+## What Gets Updated?
+
+### AGENTS.md Files
+
+For general code changes that all agents should know about:
+- New jobs or workflows
+- Codebase structure changes
+- New conventions or patterns
+- Important context for working with the code
+
+Located at: `.deepwork/jobs/[job_name]/AGENTS.md`
+
+### Copilot-Specific Instructions
+
+For changes specific to GitHub Copilot integration:
+- Copilot-specific features
+- Copilot workflow changes
+- Copilot tool usage patterns
+
+Located at: `.github/copilot/` or similar copilot instruction locations
+
+## Scheduling Recommendations
+
+- **Weekly**: Run with default settings (10 PRs) to stay current
+- **After Major Releases**: Run with higher count (30-50 PRs)
+- **Initial Setup**: Process all recent PRs in batches
+
+## Integration with Existing Workflows
+
+This job can be combined with other DeepWork jobs:
+
+```bash
+# Update docs from PRs, then commit the changes
+/pr_docs_update.fetch_prs
+/pr_docs_update.analyze_prs
+/pr_docs_update.update_docs
+
+# Review and commit
+/commit.test
+/commit.lint
+/commit.commit_and_push
+```
+
+## Troubleshooting
+
+### No New PRs Found
+
+If all fetched PRs have been processed:
+- Increase the `pr_count` parameter
+- Check the state file to see what's been processed
+- Consider clearing the state file to reprocess all PRs
+
+### GitHub API Rate Limiting
+
+If you hit rate limits:
+- Reduce the `pr_count` parameter
+- Wait for the rate limit to reset
+- Use authenticated GitHub API access if available
+
+### Documentation Files Not Found
+
+If expected documentation files don't exist:
+- The job will notify you about missing files
+- Create the necessary AGENTS.md or instruction files
+- Re-run the update step
+
+## Example Output
+
+After running the job, you'll have:
+
+1. **pr_list.json**: List of fetched PRs (filtered by state)
+2. **pr_analysis.md**: Analysis of each PR with recommendations
+3. **updated_files_list.md**: Summary of what was updated
+4. **Updated documentation files**: AGENTS.md or copilot instructions with new content
+5. **Updated state file**: Tracking newly processed PRs

.deepwork/jobs/pr_docs_update/job.yml

@@ -0,0 +1,68 @@
+name: pr_docs_update
+version: "1.0.0"
+summary: "Update documentation from recently merged PRs"
+description: |
+  A workflow that analyzes recently merged pull requests and updates either AGENTS.md
+  or copilot-specific instructions based on the PR content. Tracks processed PRs to
+  avoid duplicates and can be run multiple times to go further back in PR history.
+
+  This job helps maintain up-to-date documentation by:
+  1. Fetching recently merged PRs from GitHub
+  2. Analyzing PR content to identify documentation-relevant changes
+  3. Updating AGENTS.md (for general context) or copilot instructions (for copilot-specific changes)
+  4. Tracking which PRs have been processed to enable incremental updates
+
+  Use this job periodically to keep documentation in sync with code changes.
+
+changelog:
+  - version: "1.0.0"
+    changes: "Initial job creation"
+
+steps:
+  - id: fetch_prs
+    name: "Fetch Recently Merged PRs"
+    description: "Retrieve list of recently merged pull requests from GitHub"
+    instructions_file: steps/fetch_prs.md
+    inputs:
+      - name: pr_count
+        description: "Number of recent PRs to fetch (default: 10)"
+      - name: state_file
+        description: "Path to state file tracking processed PRs (default: .deepwork/pr_docs_state.json)"
+    outputs:
+      - pr_list.json
+    dependencies: []
+
+  - id: analyze_prs
+    name: "Analyze PR Content"
+    description: "Analyze PR content to identify documentation-relevant changes"
+    instructions_file: steps/analyze_prs.md
+    inputs:
+      - file: pr_list.json
+        from_step: fetch_prs
+    outputs:
+      - pr_analysis.md
+    dependencies:
+      - fetch_prs
+
+  - id: update_docs
+    name: "Update Documentation"
+    description: "Update AGENTS.md or copilot instructions based on PR analysis"
+    instructions_file: steps/update_docs.md
+    inputs:
+      - file: pr_analysis.md
+        from_step: analyze_prs
+      - name: state_file
+        description: "Path to state file tracking processed PRs (default: .deepwork/pr_docs_state.json)"
+    outputs:
+      - updated_files_list.md
+    dependencies:
+      - analyze_prs
+    hooks:
+      after_agent:
+        - prompt: |
+            Verify the documentation update is complete:
+            1. Relevant documentation files (AGENTS.md or copilot instructions) were identified
+            2. Documentation was updated with insights from analyzed PRs
+            3. State file was updated with processed PR numbers
+            4. Changes are ready to be committed
+            If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.