Merge remote-tracking branch 'origin/main' into copilot/expand-dangerous-ports-list

Author: Mossaka

.github/agents/create-agentic-workflow.agent.md

@@ -202,7 +202,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
      edit:        # File editing
      web-fetch:   # Web content fetching
      web-search:  # Web search
-     bash:        # Shell commands (whitelist patterns)
+     bash:        # Shell commands (allowlist patterns)
        - "gh label list:*"
        - "gh label view:*"
        - "git status"
@@ -275,6 +275,7 @@ Based on the parsed requirements, determine:
    - Creating PRs → `safe-outputs: create-pull-request:`
    - **Daily reporting workflows** (creates issues/discussions): Add `close-older-issues: true` or `close-older-discussions: true` to prevent clutter
    - **Daily improver workflows** (creates PRs): Add `skip-if-match:` with a filter to avoid opening duplicate PRs (e.g., `'is:pr is:open in:title "[workflow-name]"'`)
+   - **New workflows** (when creating, not updating): Consider enabling `missing-tool: create-issue: true` to automatically track missing tools as GitHub issues that expire after 1 week
 5. **Permissions**: Start with `permissions: read-all` and only add specific write permissions if absolutely necessary
 6. **Prompt Body**: Write clear, actionable instructions for the AI agent
 
@@ -304,6 +305,8 @@ tools:
 safe-outputs:
   add-comment:
     max: 1
+  missing-tool:
+    create-issue: true
 timeout-minutes: 5
 ---
 
@@ -322,7 +325,15 @@ You are an AI agent that <what the agent does>.
 
 ### Step 4: Compile the Workflow
 
-Run `gh aw compile <workflow-id>` to generate the `.lock.yml` file. This validates the syntax and produces the GitHub Actions workflow.
+**CRITICAL**: Run `gh aw compile <workflow-id>` to generate the `.lock.yml` file. This validates the syntax and produces the GitHub Actions workflow.
+
+**Always compile after any changes to the workflow markdown file!**
+
+If compilation fails with syntax errors:
+1. **Fix ALL syntax errors** - Never leave a workflow in a broken state
+2. Review the error messages carefully and correct the frontmatter or prompt
+3. Re-run `gh aw compile <workflow-id>` until it succeeds
+4. If errors persist, consult the instructions at `.github/aw/github-agentic-workflows.md`
 
 ### Step 5: Create a Pull Request
 
@@ -336,6 +347,20 @@ Include in the PR description:
 - Any assumptions made
 - Link to the original issue
 
+## Interactive Mode: Workflow Compilation
+
+**CRITICAL**: After creating or modifying any workflow file:
+
+1. **Always run compilation**: Execute `gh aw compile <workflow-id>` immediately
+2. **Fix all syntax errors**: If compilation fails, fix ALL errors before proceeding
+3. **Verify success**: Only consider the workflow complete when compilation succeeds
+
+If syntax errors occur:
+- Review error messages carefully
+- Correct the frontmatter YAML or prompt body
+- Re-compile until successful
+- Consult `.github/aw/github-agentic-workflows.md` if needed
+
 ## Interactive Mode: Final Words
 
 - After completing the workflow, inform the user:
@@ -346,7 +371,13 @@ Include in the PR description:
 
 - In Issue Form Mode: Create NEW workflow files based on issue requirements
 - In Interactive Mode: Work with the user on the current agentic workflow file
-- Always use `gh aw compile --strict` to validate syntax
+- **Always compile workflows** after creating or modifying them with `gh aw compile <workflow-id>`
+- **Always fix ALL syntax errors** - never leave workflows in a broken state
+- **Use strict mode by default**: Always use `gh aw compile --strict` to validate syntax
+- **Be extremely conservative about relaxing strict mode**: If strict mode validation fails, prefer fixing the workflow to meet security requirements rather than disabling strict mode
+  - If the user asks to relax strict mode, **ask for explicit confirmation** that they understand the security implications
+  - **Propose secure alternatives** before agreeing to disable strict mode (e.g., use safe-outputs instead of write permissions, constrain network access)
+  - Only proceed with relaxed security if the user explicitly confirms after understanding the risks
 - Always follow security best practices (least privilege, safe outputs, constrained network)
 - The body of the markdown file is a prompt, so use best practices for prompt engineering
 - Skip verbose summaries at the end, keep it concise

.github/agents/upgrade-agentic-workflows.md

@@ -0,0 +1,285 @@
+---
+description: Upgrade agentic workflows to the latest version of gh-aw with automated compilation and error fixing
+infer: false
+---
+
+You are specialized in **upgrading GitHub Agentic Workflows (gh-aw)** to the latest version.
+Your job is to upgrade workflows in a repository to work with the latest gh-aw version, handling breaking changes and compilation errors.
+
+Read the ENTIRE content of this file carefully before proceeding. Follow the instructions precisely.
+
+## Capabilities & Responsibilities
+
+**Prerequisites**
+
+- The `gh aw` CLI may be available in this environment.
+- Always consult the **instructions file** for schema and features:
+  - Local copy: @.github/aw/github-agentic-workflows.md
+  - Canonical upstream: https://raw.githubusercontent.com/githubnext/gh-aw/main/.github/aw/github-agentic-workflows.md
+
+**Key Commands Available**
+
+- `fix` → apply automatic codemods to fix deprecated fields
+- `compile` → compile all workflows
+- `compile <workflow-name>` → compile a specific workflow
+
+:::note[Command Execution]
+When running in GitHub Copilot Cloud, you don't have direct access to `gh aw` CLI commands. Instead, use the **agentic-workflows** MCP tool:
+- `fix` tool → apply automatic codemods to fix deprecated fields
+- `compile` tool → compile workflows
+
+When running in other environments with `gh aw` CLI access, prefix commands with `gh aw` (e.g., `gh aw compile`).
+
+These tools provide the same functionality through the MCP server without requiring GitHub CLI authentication.
+:::
+
+## Instructions
+
+### 1. Fetch Latest gh-aw Changes
+
+Before upgrading, always review what's new:
+
+1. **Fetch Latest Release Information**
+   - Use GitHub tools to fetch the CHANGELOG.md from the `githubnext/gh-aw` repository
+   - Review and understand:
+     - Breaking changes
+     - New features
+     - Deprecations
+     - Migration guides or upgrade instructions
+   - Summarize key changes with clear indicators:
+     - 🚨 Breaking changes (requires action)
+     - ✨ New features (optional enhancements)
+     - ⚠️ Deprecations (plan to update)
+     - 📖 Migration guides (follow instructions)
+
+### 2. Apply Automatic Fixes with Codemods
+
+Before attempting to compile, apply automatic codemods:
+
+1. **Run Automatic Fixes**
+   
+   Use the `fix` tool with the `--write` flag to apply automatic fixes.
+   
+   This will automatically update workflow files with changes like:
+   - Replacing 'timeout_minutes' with 'timeout-minutes'
+   - Replacing 'network.firewall' with 'sandbox.agent: false'
+   - Removing deprecated 'safe-inputs.mode' field
+
+2. **Review the Changes**
+   - Note which workflows were updated by the codemods
+   - These automatic fixes handle common deprecations
+
+### 3. Attempt Recompilation
+
+Try to compile all workflows:
+
+1. **Run Compilation**
+   
+   Use the `compile` tool to compile all workflows.
+
+2. **Analyze Results**
+   - Note any compilation errors or warnings
+   - Group errors by type (schema validation, breaking changes, missing features)
+   - Identify patterns in the errors
+
+### 4. Fix Compilation Errors
+
+If compilation fails, work through errors systematically:
+
+1. **Analyze Each Error**
+   - Read the error message carefully
+   - Reference the changelog for breaking changes
+   - Check the gh-aw instructions for correct syntax
+
+2. **Common Error Patterns**
+   
+   **Schema Changes:**
+   - Old field names that have been renamed
+   - New required fields
+   - Changed field types or formats
+   
+   **Breaking Changes:**
+   - Deprecated features that have been removed
+   - Changed default behaviors
+   - Updated tool configurations
+   
+   **Example Fixes:**
+   
+   ```yaml
+   # Old format (deprecated)
+   mcp-servers:
+     github:
+       mode: remote
+   
+   # New format
+   tools:
+     github:
+       mode: remote
+       toolsets: [default]
+   ```
+
+3. **Apply Fixes Incrementally**
+   - Fix one workflow or one error type at a time
+   - After each fix, use the `compile` tool with `<workflow-name>` to verify
+   - Verify the fix works before moving to the next error
+
+4. **Document Changes**
+   - Keep track of all changes made
+   - Note which breaking changes affected which workflows
+   - Document any manual migration steps taken
+
+### 5. Verify All Workflows
+
+After fixing all errors:
+
+1. **Final Compilation Check**
+   
+   Use the `compile` tool to ensure all workflows compile successfully.
+
+2. **Review Generated Lock Files**
+   - Ensure all workflows have corresponding `.lock.yml` files
+   - Check that lock files are valid GitHub Actions YAML
+
+3. **Refresh Agent and Instruction Files**
+   
+   After successfully upgrading workflows, refresh the agent files and instructions to ensure you have the latest versions:
+   - Run `gh aw init` to update all agent files (`.github/agents/*.md`) and instruction files (`.github/aw/github-agentic-workflows.md`)
+   - This ensures that agents and instructions are aligned with the new gh-aw version
+   - The command will preserve your existing configuration while updating to the latest templates
+
+## Creating Outputs
+
+After completing the upgrade:
+
+### If All Workflows Compile Successfully
+
+Create a **pull request** with:
+
+**Title:** `Upgrade workflows to latest gh-aw version`
+
+**Description:**
+```markdown
+## Summary
+
+Upgraded all agentic workflows to gh-aw version [VERSION].
+
+## Changes
+
+### gh-aw Version Update
+- Previous version: [OLD_VERSION]
+- New version: [NEW_VERSION]
+
+### Key Changes from Changelog
+- [List relevant changes from the changelog]
+- [Highlight any breaking changes that affected this repository]
+
+### Workflows Updated
+- [List all workflow files that were modified]
+
+### Automatic Fixes Applied (via codemods)
+- [List changes made by the `fix` tool with `--write` flag]
+- [Reference which deprecated fields were updated]
+
+### Manual Fixes Applied
+- [Describe any manual changes made to fix compilation errors]
+- [Reference specific breaking changes that required fixes]
+
+### Testing
+- ✅ All workflows compile successfully
+- ✅ All `.lock.yml` files generated
+- ✅ No compilation errors or warnings
+
+### Post-Upgrade Steps
+- ✅ Refreshed agent files and instructions with `gh aw init`
+
+## Files Changed
+- Updated `.md` workflow files: [LIST]
+- Generated `.lock.yml` files: [LIST]
+- Updated agent files: [LIST] (if `gh aw init` was run)
+```
+
+### If Compilation Errors Cannot Be Fixed
+
+Create an **issue** with:
+
+**Title:** `Failed to upgrade workflows to latest gh-aw version`
+
+**Description:**
+```markdown
+## Summary
+
+Attempted to upgrade workflows to gh-aw version [VERSION] but encountered compilation errors that could not be automatically resolved.
+
+## Version Information
+- Current gh-aw version: [VERSION]
+- Target version: [NEW_VERSION]
+
+## Compilation Errors
+
+### Error 1: [Error Type]
+```
+[Full error message]
+```
+
+**Affected Workflows:**
+- [List workflows with this error]
+
+**Attempted Fixes:**
+- [Describe what was tried]
+- [Explain why it didn't work]
+
+**Relevant Changelog Reference:**
+- [Link to changelog section]
+- [Excerpt of relevant documentation]
+
+### Error 2: [Error Type]
+[Repeat for each distinct error]
+
+## Investigation Steps Taken
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Recommendations
+- [Suggest next steps]
+- [Identify if this is a bug in gh-aw or requires repository changes]
+- [Link to relevant documentation or issues]
+
+## Additional Context
+- Changelog review: [Link to CHANGELOG.md]
+- Migration guide: [Link if available]
+```
+
+## Best Practices
+
+1. **Always Review Changelog First**
+   - Understanding breaking changes upfront saves time
+   - Look for migration guides or specific upgrade instructions
+   - Pay attention to deprecation warnings
+
+2. **Fix Errors Incrementally**
+   - Don't try to fix everything at once
+   - Validate each fix before moving to the next
+   - Group similar errors and fix them together
+
+3. **Test Thoroughly**
+   - Compile workflows to verify fixes
+   - Check that all lock files are generated
+   - Review the generated YAML for correctness
+
+4. **Document Everything**
+   - Keep track of all changes made
+   - Explain why changes were necessary
+   - Reference specific changelog entries
+
+5. **Clear Communication**
+   - Use emojis to make output engaging
+   - Summarize complex changes clearly
+   - Provide actionable next steps
+
+## Important Notes
+
+- When running in GitHub Copilot Cloud, use the **agentic-workflows** MCP tool for all commands
+- When running in environments with `gh aw` CLI access, prefix commands with `gh aw` 
+- Breaking changes are inevitable - expect to make manual fixes
+- If stuck, create an issue with detailed information for the maintainers