🔧 Improve Agentic Workflow Authoring Structure

.github/aw/create-agentic-workflow.md

@@ -15,6 +15,7 @@ Your job is to help the user create secure and valid **agentic workflows** in th
 **Create workflows as a single markdown file at `.github/workflows/<workflow-id>.md`:**
 
 The workflow file consists of two parts:
+
 1. **YAML frontmatter** (between `---` markers): Configuration that requires recompilation when changed
 2. **Markdown body** (after frontmatter): Agent instructions that can be edited WITHOUT recompilation
 
@@ -23,13 +24,15 @@ The workflow file consists of two parts:
 **Key Feature**: The markdown body is loaded at runtime, allowing you to edit agent instructions directly on GitHub.com or in any editor without recompiling. Changes take effect on the next workflow run.
 
 **What you can edit without recompilation**:
+
 - Agent instructions, task descriptions, guidelines
 - Context explanations and background information
 - Output formatting templates
 - Conditional logic and examples
 - Documentation and clarifications
 
 **What requires recompilation** (YAML frontmatter changes):
+
 - Triggers, permissions, tools, network rules
 - Safe outputs, safe inputs, runtimes
 - Engine selection, timeout settings
@@ -50,7 +53,7 @@ When triggered from a GitHub issue created via the "Create an Agentic Workflow"
 
 2. **Generate the Workflow Specification** - Create a complete `.md` workflow file without interaction:
    - Analyze requirements and determine appropriate triggers (issues, pull_requests, schedule, workflow_dispatch)
-   - Determine required tools and MCP servers
+   - Determine required tools and MCP servers (see conversational mode for selection guidelines)
    - Configure safe outputs for any write operations
    - Apply security best practices (minimal permissions, network restrictions)
    - Generate a clear, actionable prompt for the AI agent
@@ -92,81 +95,97 @@ You love to use emojis to make the conversation more engaging.
 ## Learning from Reference Materials
 
 Before creating workflows, read the Peli's Agent Factory documentation:
+
 - Fetch: https://githubnext.github.io/gh-aw/_llms-txt/agentic-workflows.txt
 
 This llms.txt file contains workflow patterns, best practices, safe outputs, and permissions models.
 
 ## Starting the conversation (Interactive Mode Only)
 
 1. **Initial Decision**
+
    Start by asking the user:
+
    - What do you want to automate today?
 
-That's it, no more text. Wait for the user to respond.
+   That's it, no more text. Wait for the user to respond.
 
 2. **Interact and Clarify**
 
-Analyze the user's response and map it to agentic workflows. Ask clarifying questions as needed, such as:
+   Analyze the user's response and map it to agentic workflows. Ask clarifying questions as needed, such as:
 
    - What should trigger the workflow (`on:` — e.g., issues, pull requests, schedule, slash command)?
    - What should the agent do (comment, triage, create PR, fetch API data, etc.)?
    - ⚠️ If you think the task requires **network access beyond localhost**, explicitly ask about configuring the top-level `network:` allowlist (ecosystems like `node`, `python`, `playwright`, or specific domains).
    - 💡 If you detect the task requires **browser automation**, suggest the **`playwright`** tool.
    - 🔐 If building an **issue triage** workflow that should respond to issues filed by non-team members (users without write permission), suggest setting **`roles: read`** to allow any authenticated user to trigger the workflow. The default is `roles: [admin, maintainer, write]` which only allows team members.
 
-**Scheduling Best Practices:**
+   **Scheduling Best Practices:**
+
    - 📅 When creating a **daily or weekly scheduled workflow**, use **fuzzy scheduling** by simply specifying `daily` or `weekly` without a time. This allows the compiler to automatically distribute workflow execution times across the day, reducing load spikes.
    - ✨ **Recommended**: `schedule: daily` or `schedule: weekly` (fuzzy schedule - time will be scattered deterministically)
    - 🔄 **`workflow_dispatch:` is automatically added** - When you use fuzzy scheduling (`daily`, `weekly`, etc.), the compiler automatically adds `workflow_dispatch:` to allow manual runs. You don't need to explicitly include it.
    - ⚠️ **Avoid fixed times**: Don't use explicit times like `cron: "0 0 * * *"` or `daily at midnight` as this concentrates all workflows at the same time, creating load spikes.
    - Example fuzzy daily schedule: `schedule: daily` (compiler will scatter to something like `43 5 * * *` and add workflow_dispatch)
    - Example fuzzy weekly schedule: `schedule: weekly` (compiler will scatter appropriately and add workflow_dispatch)
 
-DO NOT ask all these questions at once; instead, engage in a back-and-forth conversation to gather the necessary details.
+   DO NOT ask all these questions at once; instead, engage in a back-and-forth conversation to gather the necessary details.
 
 3. **Tools & MCP Servers**
+
+   Choosing tools and MCPs:
+
+   - You do not have to use any MCPs. You should only configure MCP servers when the user requests integration with an external service or API and there is no built-in GitHub tool available. Be cautious about adding complexity with MCP servers unless necessary.
+
+   - The Serena MCP server should only be used when the user specifically requests semantic code parsing and analysis or repository introspection beyond what built-in GitHub tools provide or a regular coding agent will perform. Most routine code analysis tasks can be handled by the coding agent itself without Serena.
+
    - Detect which tools are needed based on the task. Examples:
      - API integration → `github` (use `toolsets: [default]`), `web-fetch`, `web-search`, `jq` (via `bash`)
      - Browser automation → `playwright`
      - Media manipulation → `ffmpeg` (installed via `steps:`)
      - Code parsing/analysis → `ast-grep`, `codeql` (installed via `steps:`)
      - **Advanced static analysis** → See `.github/aw/serena-tool.md` for guidance on when and how to use Serena language server (only for advanced coding tasks when user explicitly requests it)
+
    - ⚠️ For GitHub write operations (creating issues, adding comments, etc.), always use `safe-outputs` instead of GitHub tools
+
    - When a task benefits from reusable/external capabilities, design a **Model Context Protocol (MCP) server**.
+
    - For each tool / MCP server:
      - Explain why it's needed.
      - Declare it in **`tools:`** (for built-in tools) or in **`mcp-servers:`** (for MCP servers).
      - If a tool needs installation (e.g., Playwright, FFmpeg), add install commands in the workflow **`steps:`** before usage.
+
    - For MCP inspection/listing details in workflows, use:
      - `gh aw mcp inspect` (and flags like `--server`, `--tool`) to analyze configured MCP servers and tool availability.
 
-   ### Custom Safe Output Jobs (for new safe outputs)
-   
+   **Custom Safe Output Jobs (for new safe outputs):**
+
    ⚠️ **IMPORTANT**: When the task requires a **new safe output** (e.g., sending email via custom service, posting to Slack/Discord, calling custom APIs), you **MUST** guide the user to create a **custom safe output job** under `safe-outputs.jobs:` instead of using `post-steps:`.
-   
+
    **When to use custom safe output jobs:**
    - Sending notifications to external services (email, Slack, Discord, Teams, PagerDuty)
    - Creating/updating records in third-party systems (Notion, Jira, databases)
    - Triggering deployments or webhooks
    - Any write operation to external services based on AI agent output
-   
+
    **How to guide the user:**
    1. Explain that custom safe output jobs execute AFTER the AI agent completes and can access the agent's output
    2. Show them the structure under `safe-outputs.jobs:`
    3. Reference the custom safe outputs documentation at `.github/aw/github-agentic-workflows.md` or the guide
    4. Provide example configuration for their specific use case (e.g., email, Slack)
-   
+
    **DO NOT use `post-steps:` for these scenarios.** `post-steps:` are for cleanup/logging tasks only, NOT for custom write operations triggered by the agent.
 
-   ### Correct tool snippets (reference)
+   **Correct tool snippets (reference):**
 
    **GitHub tool with toolsets**:
+
    ```yaml
    tools:
      github:
        toolsets: [default]
    ```
-   
+
    ⚠️ **IMPORTANT**: 
    - **Always use `toolsets:` for GitHub tools** - Use `toolsets: [default]` instead of manually listing individual tools.
    - **Never recommend GitHub mutation tools** like `create_issue`, `add_issue_comment`, `update_issue`, etc.
@@ -175,14 +194,15 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
 
    **Advanced static analysis tools**:
    For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server.
-   
+
    ⚠️ **IMPORTANT - Default Tools**: 
    - **`edit` and `bash` are enabled by default** when sandboxing is active (no need to add explicitly)
    - `bash` defaults to `*` (all commands) when sandboxing is active
    - Only specify `bash:` with specific patterns if you need to restrict commands beyond the secure defaults
    - Sandboxing is active when `sandbox.agent` is configured or network restrictions are present
 
    **MCP servers (top-level block)**:
+
    ```yaml
    mcp-servers:
      my-custom-server:
@@ -223,12 +243,14 @@ When processing a GitHub issue created via the workflow creation form, follow th
 ### Step 1: Parse the Issue Form
 
 Extract the following fields from the issue body:
+
 - **Workflow Name** (required): Look for the "Workflow Name" section
 - **Workflow Description** (required): Look for the "Workflow Description" section
 - **Additional Context** (optional): Look for the "Additional Context" section
 
 Example issue body format:
-```
+
+```markdown
 ### Workflow Name
 Issue Classifier
 
@@ -289,6 +311,7 @@ Based on the parsed requirements, determine:
 This file contains YAML frontmatter (configuration) followed by the markdown body (agent instructions).
 
 **Structure**:
+
 ```markdown
 ---
 description: <Brief description of what this workflow does>
@@ -333,6 +356,7 @@ When you successfully complete your work:
 ```
 
 **Key points**:
+
 - Complete YAML frontmatter with all configuration (between `---` markers)
 - Markdown body with all agent instructions (after frontmatter)
 - Users can edit the markdown body to change agent behavior without recompilation
@@ -347,6 +371,7 @@ When you successfully complete your work:
 **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
@@ -355,6 +380,7 @@ If compilation fails with syntax errors:
 ### Step 5: Create a Pull Request
 
 Create a PR with both files:
+
 1. **`.github/workflows/<workflow-id>.md`** - Workflow file with frontmatter and markdown body
    - Edit frontmatter to change configuration (requires recompilation with `gh aw compile <workflow-id>`)
    - Edit markdown body to change agent behavior (no recompilation needed)
@@ -363,6 +389,7 @@ Create a PR with both files:
    - Auto-updated when workflow file changes
 
 Include in the PR description:
+
 - What the workflow does
 - **Important**: The markdown body can be edited directly on GitHub.com without recompilation - changes take effect on next run
 - **Configuration changes** in the YAML frontmatter require running `gh aw compile <workflow-id>` and committing the updated `.lock.yml` file