Remove two-file structure from workflow documentation

.github/aw/actions-lock.json

@@ -100,7 +100,7 @@
       "version": "v5.6.0",
       "sha": "a26af69be951a213d495a4c3e4e4022e16d87065"
     },
-    "actions/upload-artifact@v4": {
+    "actions/upload-artifact@v4.6.2": {
       "repo": "actions/upload-artifact",
       "version": "v4.6.2",
       "sha": "ea165f8d65b6e75b540449e92b4886f43607fa02"

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

@@ -10,33 +10,30 @@ 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
+## Workflow File Structure
 
-**ALWAYS create workflows using a two-file structure with clear separation of concerns:**
+**Create workflows as a single markdown file at `.github/workflows/<workflow-id>.md`:**
 
-### 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
+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
 
-### 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}}`
+### Editing Without Recompilation
 
-### Why This Structure?
+**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.
 
-**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
+**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
 
-**Remember**: 
-- Prompt/behavior changes → Edit `.github/agentics/<workflow-id>.md` (no recompile)
-- Configuration changes → Edit `.github/workflows/<workflow-id>.md` (recompile required)
+**What requires recompilation** (YAML frontmatter changes):
+- Triggers, permissions, tools, network rules
+- Safe outputs, safe inputs, runtimes
+- Engine selection, timeout settings
+- Any configuration between `---` markers
 
 ## Two Modes of Operation
 
@@ -276,37 +273,41 @@ Based on the parsed requirements, determine:
 8. **Prompt Body**: Write clear, actionable instructions for the AI agent
    - **IMPORTANT**: Include guidance for agents to call the `noop` safe output when they successfully complete work but there's nothing to be done (e.g., no issues to triage, no PRs to create, no changes needed). This is essential for transparency—it proves the agent worked and consciously determined no action was necessary.
 
-### Step 3: Create the Workflow Files (Two-File Structure)
+### Step 3: Create the Workflow File
 
-**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
+**Create a single file at `.github/workflows/<workflow-id>.md`:**
 
 #### 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)
 
-#### Step 3.2: Create the Agentics Prompt File (Markdown Body)
+#### Step 3.2: Create the Workflow File
 
-**File**: `.github/agentics/<workflow-id>.md`
+**File**: `.github/workflows/<workflow-id>.md`
 
-This file contains the COMPLETE agent prompt that can be edited without recompilation.
+This file contains YAML frontmatter (configuration) followed by the markdown body (agent instructions).
 
 **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. -->
+---
+description: <Brief description of what this workflow does>
+on:
+  issues:
+    types: [opened, edited]
+roles: read  # Allow any authenticated user to trigger (important for issue triage)
+permissions:
+  contents: read
+  issues: read
+tools:
+  github:
+    toolsets: [default]
+safe-outputs:
+  add-comment:
+    max: 1
+  missing-tool:
+    create-issue: true
+---
 
 # <Workflow Name>
 
@@ -332,47 +333,10 @@ When you successfully complete your work:
 ```
 
 **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>
-on:
-  issues:
-    types: [opened, edited]
-roles: read  # Allow any authenticated user to trigger (important for issue triage)
-permissions:
-  contents: read
-  issues: read
-tools:
-  github:
-    toolsets: [default]
-safe-outputs:
-  add-comment:
-    max: 1
-  missing-tool:
-    create-issue: true
----
-
-{{#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
+- 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
+- Changes to frontmatter require recompilation with `gh aw compile <workflow-id>`
 
 **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.
 
@@ -390,22 +354,18 @@ If compilation fails with syntax errors:
 
 ### Step 5: Create a Pull Request
 
-Create a PR with all three files:
-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
+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)
+2. **`.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
-- **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>`
+- **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
 - Link to the original issue (if applicable)
 
 ## Interactive Mode: Final Words