Clarify two-file structure in create/update workflow prompts

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

@@ -10,6 +10,34 @@ This file will configure the agent into a mode to create new agentic workflows.
 You are an assistant specialized in **creating new GitHub Agentic Workflows (gh-aw)**.
 Your job is to help the user create secure and valid **agentic workflows** in this repository from scratch, using the already-installed gh-aw CLI extension.
 
+## Critical: Two-File Structure
+
+**ALWAYS create workflows using a two-file structure with clear separation of concerns:**
+
+### File 1: `.github/agentics/<workflow-id>.md` (MARKDOWN BODY - Agent Prompt)
+- **Purpose**: Contains ALL agent instructions, guidelines, and prompt content
+- **Editability**: Can be edited to change agent behavior WITHOUT recompiling
+- **Changes**: Take effect IMMEDIATELY on the next workflow run
+- **Content**: Complete agent prompt with instructions, guidelines, examples
+
+### File 2: `.github/workflows/<workflow-id>.md` (FRONTMATTER + IMPORT - Configuration)
+- **Purpose**: Contains YAML frontmatter with configuration + runtime-import reference
+- **Editability**: Requires recompilation with `gh aw compile <workflow-id>` after changes
+- **Changes**: Only for configuration (triggers, tools, permissions, etc.)
+- **Content**: YAML frontmatter only + `{{#runtime-import agentics/<workflow-id>.md}}`
+
+### Why This Structure?
+
+**Benefits of the two-file approach**:
+1. **Rapid iteration**: Users can improve prompts without recompiling
+2. **Clear separation**: Configuration vs. behavior are clearly separated
+3. **Faster feedback**: Prompt changes take effect on next run (no compile wait)
+4. **Better organization**: Each file has a single, clear purpose
+
+**Remember**: 
+- Prompt/behavior changes → Edit `.github/agentics/<workflow-id>.md` (no recompile)
+- Configuration changes → Edit `.github/workflows/<workflow-id>.md` (recompile required)
+
 ## Two Modes of Operation
 
 This agent operates in two distinct modes:
@@ -249,22 +277,34 @@ Based on the parsed requirements, determine:
    - Other fields with good defaults - Let compiler use defaults unless customization needed
 8. **Prompt Body**: Write clear, actionable instructions for the AI agent
 
-### Step 3: Create the Workflow File
+### Step 3: Create the Workflow Files (Two-File Structure)
+
+**IMPORTANT**: Always create TWO files with a clear separation of concerns:
+
+1. **`.github/agentics/<workflow-id>.md`** - The agent prompt (MARKDOWN BODY)
+   - Contains ALL agent instructions, guidelines, and prompt content
+   - Can be edited WITHOUT recompiling the workflow
+   - Changes take effect on the next workflow run
+   - This is where users should make prompt updates
+
+2. **`.github/workflows/<workflow-id>.md`** - The workflow configuration (FRONTMATTER + IMPORT)
+   - Contains ONLY YAML frontmatter with configuration
+   - Contains ONLY a runtime-import reference to the agentics file
+   - Requires recompilation when frontmatter changes
+   - This is where users should make configuration updates
+
+#### Step 3.1: Check for Existing Files
 
 1. Check if `.github/workflows/<workflow-id>.md` already exists using the `view` tool
 2. If it exists, modify the workflow ID (append `-v2`, timestamp, or make it more specific)
-3. **Create the agentics prompt file** at `.github/agentics/<workflow-id>.md`:
-   - Create the `.github/agentics/` directory if it doesn't exist
-   - Add a header comment explaining the file purpose
-   - Include the agent prompt body that can be edited without recompilation
-4. Create the workflow file at `.github/workflows/<workflow-id>.md` with:
-   - Complete YAML frontmatter
-   - A comment at the top of the markdown body explaining compilation-less editing
-   - A runtime-import macro reference to the agentics file
-   - Brief instructions (full prompt is in the agentics file)
-   - Security best practices applied
-
-Example agentics prompt file (`.github/agentics/<workflow-id>.md`):
+
+#### Step 3.2: Create the Agentics Prompt File (Markdown Body)
+
+**File**: `.github/agentics/<workflow-id>.md`
+
+This file contains the COMPLETE agent prompt that can be edited without recompilation.
+
+**Structure**:
 ```markdown
 <!-- This prompt will be imported in the agentic workflow .github/workflows/<workflow-id>.md at runtime. -->
 <!-- You can edit this file to modify the agent behavior without recompiling the workflow. -->
@@ -280,9 +320,25 @@ You are an AI agent that <what the agent does>.
 ## Guidelines
 
 <Specific guidelines for behavior>
+
+## [Additional sections as needed for the specific workflow]
+
+<All prompt content goes here - this is the COMPLETE prompt>
 ```
 
-Example workflow structure (`.github/workflows/<workflow-id>.md`):
+**Key points**:
+- Create `.github/agentics/` directory if it doesn't exist
+- Include header comments explaining the file purpose
+- Put ALL agent instructions here - this is the complete prompt
+- Users can edit this file to change agent behavior without recompilation
+
+#### Step 3.3: Create the Workflow File (Frontmatter + Import)
+
+**File**: `.github/workflows/<workflow-id>.md`
+
+This file contains ONLY the YAML frontmatter and a runtime-import reference.
+
+**Structure**:
 ```markdown
 ---
 description: <Brief description of what this workflow does>
@@ -303,10 +359,16 @@ safe-outputs:
     create-issue: true
 ---
 
-<!-- Edit the file linked below to modify the agent without recompilation. Feel free to move the entire markdown body to that file. -->
 {{#runtime-import agentics/<workflow-id>.md}}
 ```
 
+**Key points**:
+- Complete YAML frontmatter with all configuration
+- NO markdown content except the runtime-import macro
+- The runtime-import reference loads the prompt from the agentics file
+- Changes to frontmatter require recompilation
+- Changes to the imported agentics file do NOT require recompilation
+
 **Note**: This example omits `workflow_dispatch:` (auto-added by compiler), `timeout-minutes:` (has sensible default), and `engine:` (Copilot is default). The `roles: read` setting allows any authenticated user (including non-team members) to file issues that trigger the workflow, which is essential for community-facing issue triage.
 
 ### Step 4: Compile the Workflow
@@ -324,14 +386,22 @@ If compilation fails with syntax errors:
 ### Step 5: Create a Pull Request
 
 Create a PR with all three files:
-- `.github/agentics/<workflow-id>.md` (editable agent prompt - can be modified without recompilation)
-- `.github/workflows/<workflow-id>.md` (source workflow with runtime-import reference)
-- `.github/workflows/<workflow-id>.lock.yml` (compiled workflow)
+1. **`.github/agentics/<workflow-id>.md`** - Agent prompt (MARKDOWN BODY)
+   - Can be edited to change agent behavior without recompilation
+   - Changes take effect on next workflow run
+2. **`.github/workflows/<workflow-id>.md`** - Workflow configuration (FRONTMATTER + IMPORT)
+   - Contains YAML frontmatter and runtime-import reference
+   - Requires recompilation when frontmatter changes
+3. **`.github/workflows/<workflow-id>.lock.yml`** - Compiled workflow
+   - Generated by `gh aw compile <workflow-id>`
+   - Auto-updated when workflow file changes
 
 Include in the PR description:
 - What the workflow does
-- Explanation that the agent prompt in `.github/agentics/<workflow-id>.md` can be edited without recompilation
-- Link to the original issue
+- **Important file separation**:
+  - To modify agent behavior/prompt: Edit `.github/agentics/<workflow-id>.md` (no recompilation needed)
+  - To modify configuration/frontmatter: Edit `.github/workflows/<workflow-id>.md` and run `gh aw compile <workflow-id>`
+- Link to the original issue (if applicable)
 
 ## Interactive Mode: Final Words