diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx
index 988637aa90..0536fb79ba 100644
--- a/docs/src/content/docs/agent-factory-status.mdx
+++ b/docs/src/content/docs/agent-factory-status.mdx
@@ -120,6 +120,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Security Alert Burndown](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-alert-burndown.md) | copilot | [![Security Alert Burndown](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.lock.yml) | - | - |
 | [Security Compliance Campaign](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-compliance.md) | copilot | [![Security Compliance Campaign](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml) | - | - |
 | [Security Fix PR](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-fix-pr.md) | copilot | [![Security Fix PR](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml) | - | - |
+| [Security Guard Agent 🛡️](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-guard.md) | copilot | [![Security Guard Agent 🛡️](https://github.com/githubnext/gh-aw/actions/workflows/security-guard.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-guard.lock.yml) | - | - |
 | [Security Review Agent 🔒](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-review.md) | copilot | [![Security Review Agent 🔒](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml) | - | `/security` |
 | [Semantic Function Refactoring](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/semantic-function-refactor.md) | claude | [![Semantic Function Refactoring](https://github.com/githubnext/gh-aw/actions/workflows/semantic-function-refactor.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/semantic-function-refactor.lock.yml) | - | - |
 | [Sergo - Serena Go Expert](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/sergo.md) | claude | [![Sergo - Serena Go Expert](https://github.com/githubnext/gh-aw/actions/workflows/sergo.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/sergo.lock.yml) | - | - |
diff --git a/docs/src/content/docs/guides/serena.md b/docs/src/content/docs/guides/serena.md
new file mode 100644
index 0000000000..ba9f782933
--- /dev/null
+++ b/docs/src/content/docs/guides/serena.md
@@ -0,0 +1,521 @@
+---
+title: Using Serena
+description: Configure the Serena MCP server for semantic code analysis and intelligent code editing in your agentic workflows.
+sidebar:
+  order: 5
+---
+
+This guide covers using [Serena](https://github.com/oraios/serena), a powerful coding agent toolkit that provides semantic code retrieval and editing capabilities to agentic workflows.
+
+## What is Serena?
+
+Serena is an MCP server that enhances AI agents with IDE-like tools for understanding and manipulating code. Instead of reading entire files or performing text-based searches, agents can use Serena to:
+
+- **Find symbols** - Locate functions, classes, types, and variables by name
+- **Navigate relationships** - Discover references, implementations, and dependencies
+- **Edit at symbol level** - Insert, replace, or modify code entities precisely
+- **Analyze semantically** - Understand code structure using language servers
+
+Serena supports **30+ programming languages** through Language Server Protocol (LSP) integration, including Go, Python, TypeScript, JavaScript, Rust, Java, C/C++, and many more.
+
+> [!TIP]
+> Serena excels at navigating and manipulating complex codebases. It provides the greatest value when working with large, well-structured projects where precise code navigation and editing are essential.
+
+## Quick Start
+
+### Basic Configuration
+
+Add Serena to your workflow using the short syntax with a list of languages:
+
+```yaml wrap
+---
+engine: copilot
+permissions:
+  contents: read
+tools:
+  serena: ["go", "typescript", "python"]
+---
+```
+
+This enables Serena for Go, TypeScript, and Python code analysis.
+
+### Common Use Cases
+
+**Code analysis workflow:**
+
+```yaml wrap
+---
+engine: copilot
+permissions:
+  contents: read
+tools:
+  serena: ["go"]
+  github:
+    toolsets: [default]
+---
+
+# Code Quality Analyzer
+
+Analyze Go code in this repository and provide recommendations:
+
+1. Use Serena to find all exported functions
+2. Check for missing documentation
+3. Identify code patterns and suggest improvements
+```
+
+**Code refactoring workflow:**
+
+```yaml wrap
+---
+engine: claude
+permissions:
+  contents: write
+tools:
+  serena: ["typescript", "javascript"]
+  edit:
+---
+
+# Refactor TypeScript Code
+
+Refactor the codebase to use modern TypeScript features:
+
+1. Find all class declarations
+2. Convert to functional components where appropriate
+3. Update type definitions
+```
+
+## Configuration Options
+
+### Short Syntax (Array)
+
+The simplest way to configure Serena - just list the languages:
+
+```yaml wrap
+tools:
+  serena: ["go", "typescript"]
+```
+
+This uses default settings for each language server.
+
+### Long Syntax (Detailed Configuration)
+
+For fine-grained control over language servers:
+
+```yaml wrap
+tools:
+  serena:
+    version: latest
+    args: ["--verbose"]
+    languages:
+      go:
+        version: "1.21"
+        go-mod-file: "go.mod"
+        gopls-version: "v0.14.2"
+      typescript:
+      python:
+        version: "3.12"
+```
+
+**Configuration fields:**
+
+- `version` - Serena version to use (default: `latest`)
+- `args` - Additional command-line arguments (e.g., `["--verbose"]`)
+- `languages` - Language-specific configuration
+
+**Language-specific options:**
+
+For **Go**:
+- `version` - Go runtime version
+- `go-mod-file` - Path to `go.mod` (default: `"go.mod"`)
+- `gopls-version` - gopls language server version (default: `latest`)
+
+For **Python**:
+- `version` - Python runtime version
+
+For **TypeScript/JavaScript**:
+- No additional configuration required (uses default language server)
+
+### Custom Go Module Path
+
+For projects with `go.mod` in a subdirectory:
+
+```yaml wrap
+tools:
+  serena:
+    languages:
+      go:
+        go-mod-file: "backend/go.mod"
+        gopls-version: "latest"
+```
+
+## Language Support
+
+Serena supports **30+ programming languages** through Language Server Protocol (LSP):
+
+| Category | Languages |
+|----------|-----------|
+| **Systems** | C, C++, Rust, Go, Zig |
+| **JVM** | Java, Kotlin, Scala, Groovy (partial) |
+| **Web** | JavaScript, TypeScript, Dart, Elm |
+| **Dynamic** | Python, Ruby, PHP, Perl, Lua |
+| **Functional** | Haskell, Elixir, Erlang, Clojure, OCaml |
+| **Scientific** | R, Julia, MATLAB, Fortran |
+| **Shell** | Bash, PowerShell |
+| **Other** | C#, Swift, Nix, Markdown, YAML, TOML |
+
+> [!NOTE]
+> Some language servers require additional dependencies. Most are automatically installed by Serena, but check the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) documentation for specific requirements.
+
+## Available Tools
+
+When Serena is enabled, the agent has access to these semantic code tools:
+
+### Symbol Navigation
+
+- `find_symbol` - Search for functions, classes, types, and variables by name
+- `find_referencing_symbols` - Find all references to a symbol
+- `get_symbol_definition` - Get the full definition of a symbol
+- `list_symbols_in_file` - List all symbols defined in a file
+
+### Code Editing
+
+- `replace_symbol_body` - Replace the implementation of a function or method
+- `insert_after_symbol` - Add code after a specific symbol
+- `insert_before_symbol` - Add code before a specific symbol
+- `delete_symbol` - Remove a symbol definition
+
+### Project Analysis
+
+- `find_files` - Locate files matching patterns
+- `get_project_structure` - Analyze directory structure
+- `analyze_imports` - Examine import dependencies
+
+> [!TIP]
+> These tools enable agents to work at the **symbol level** rather than the file level, making code operations more precise and context-aware.
+
+## Memory Configuration
+
+Serena maintains analysis state in memory for faster operations. Configure memory location:
+
+```yaml wrap
+---
+tools:
+  serena: ["go"]
+  cache-memory:
+    key: serena-analysis
+---
+
+# In your workflow instructions:
+# Memory location: /tmp/gh-aw/cache-memory/serena/
+```
+
+The agent should create this directory before using Serena:
+
+```bash
+mkdir -p /tmp/gh-aw/cache-memory/serena
+```
+
+This caches language server indexes and analysis results for improved performance.
+
+## Practical Examples
+
+### Example 1: Finding Unused Functions
+
+```yaml wrap
+---
+engine: copilot
+tools:
+  serena: ["go"]
+  github:
+    toolsets: [default]
+---
+
+# Find Unused Code
+
+Analyze the Go codebase for unused exported functions:
+
+1. Configure Serena memory: `mkdir -p /tmp/gh-aw/cache-memory/serena`
+2. Use `find_symbol` to list all exported functions
+3. Use `find_referencing_symbols` to check usage
+4. Report functions with no references
+```
+
+### Example 2: Automated Refactoring
+
+```yaml wrap
+---
+engine: claude
+permissions:
+  contents: write
+tools:
+  serena: ["python"]
+  edit:
+---
+
+# Modernize Python Code
+
+Update Python code to use type hints:
+
+1. Find all function definitions without type hints
+2. Analyze function signatures and return types
+3. Add appropriate type annotations using `replace_symbol_body`
+4. Verify changes maintain correctness
+```
+
+### Example 3: Code Quality Analysis
+
+```yaml wrap
+---
+engine: copilot
+tools:
+  serena: ["go"]
+---
+
+# Analyze Test Coverage
+
+Review Go test files for completeness:
+
+1. List all exported functions in source files
+2. Check corresponding test files
+3. Identify functions without test coverage
+4. Generate report with missing tests
+```
+
+## Best Practices
+
+### 1. Configure Memory Early
+
+Always set up Serena's cache directory at the start of your workflow:
+
+```bash
+mkdir -p /tmp/gh-aw/cache-memory/serena
+```
+
+This enables faster analysis on subsequent operations.
+
+### 2. Use Symbol-Level Operations
+
+Prefer Serena's symbol tools over file-level edits when possible:
+
+```
+✅ Good: Use replace_symbol_body to update a function
+❌ Avoid: Read entire file, modify text, write back
+```
+
+### 3. Specify Language Versions
+
+For Go projects, explicitly configure `go-mod-file` location:
+
+```yaml wrap
+tools:
+  serena:
+    languages:
+      go:
+        go-mod-file: "go.mod"
+        gopls-version: "latest"
+```
+
+### 4. Combine with Other Tools
+
+Serena works well alongside other tools:
+
+```yaml wrap
+tools:
+  serena: ["go"]        # Semantic analysis
+  github:               # Repository access
+    toolsets: [default]
+  edit:                 # File operations
+  bash:                 # Build and test
+```
+
+### 5. Start Small
+
+For large codebases, begin with targeted analysis:
+
+```
+1. Focus on specific packages or modules
+2. Use symbol search with filters
+3. Gradually expand scope based on findings
+```
+
+## Common Workflows
+
+### Code Analysis Workflow
+
+```yaml wrap
+---
+name: Daily Code Quality Check
+on:
+  schedule:
+    - cron: daily
+permissions:
+  contents: read
+tools:
+  serena: ["go"]
+  github:
+    toolsets: [default]
+---
+
+# Mission: Analyze code quality daily
+
+1. Configure Serena cache: `/tmp/gh-aw/cache-memory/serena/`
+2. Find all exported functions
+3. Check for missing documentation
+4. Identify complex functions (high cyclomatic complexity)
+5. Create issue with findings
+```
+
+### Refactoring Workflow
+
+```yaml wrap
+---
+name: Automated Refactoring
+on: workflow_dispatch
+permissions:
+  contents: write
+tools:
+  serena: ["typescript"]
+  edit:
+safe-outputs:
+  create-pull-request:
+    title-prefix: "[refactor] "
+---
+
+# Mission: Refactor TypeScript code
+
+1. Find deprecated API usage
+2. Use Serena to locate all references
+3. Replace with modern equivalents
+4. Verify changes compile
+5. Create pull request with changes
+```
+
+### Documentation Workflow
+
+```yaml wrap
+---
+name: Documentation Check
+on: issues
+permissions:
+  contents: read
+  issues: write
+tools:
+  serena: ["go"]
+  github:
+    toolsets: [default]
+---
+
+# Mission: Verify function documentation
+
+1. Parse issue for target file
+2. Use Serena to list all exported symbols
+3. Check for missing GoDoc comments
+4. Report findings in issue comment
+```
+
+## Troubleshooting
+
+### Language Server Not Found
+
+**Problem:** Serena cannot find the language server for your language.
+
+**Solution:** Check that dependencies are installed. For Go:
+
+```bash
+go install golang.org/x/tools/gopls@latest
+```
+
+### Memory Permission Issues
+
+**Problem:** Serena cannot write to cache directory.
+
+**Solution:** Ensure cache directory exists with proper permissions:
+
+```bash
+mkdir -p /tmp/gh-aw/cache-memory/serena
+chmod 755 /tmp/gh-aw/cache-memory/serena
+```
+
+### Go Module Path Not Found
+
+**Problem:** gopls cannot find `go.mod` file.
+
+**Solution:** Explicitly configure the path:
+
+```yaml wrap
+tools:
+  serena:
+    languages:
+      go:
+        go-mod-file: "path/to/go.mod"
+```
+
+### Slow Initial Analysis
+
+**Problem:** First run takes a long time to analyze code.
+
+**Solution:** This is expected as language servers build indexes. Subsequent runs use cached data and are much faster. Consider:
+
+- Enabling cache-memory for persistence
+- Running analysis workflows on schedule (daily) to maintain warm cache
+- Limiting scope to specific packages for large codebases
+
+## Advanced Configuration
+
+### Multiple Language Support
+
+Enable Serena for multiple languages in one workflow:
+
+```yaml wrap
+tools:
+  serena:
+    languages:
+      go:
+        version: "1.21"
+        go-mod-file: "backend/go.mod"
+      typescript:
+      python:
+        version: "3.12"
+```
+
+### Custom Language Server Settings
+
+For advanced users, pass custom arguments to Serena:
+
+```yaml wrap
+tools:
+  serena:
+    version: latest
+    args: ["--verbose", "--log-level=debug"]
+    languages:
+      go:
+        gopls-version: "v0.14.2"
+```
+
+### Integrated with Repository Memory
+
+Combine Serena with repository memory for persistent state:
+
+```yaml wrap
+tools:
+  serena: ["go"]
+  repo-memory:
+    branch-name: memory/serena-analysis
+    description: "Serena analysis cache"
+    file-glob: ["memory/serena/*.json"]
+```
+
+## Related Documentation
+
+- [Using MCPs](/gh-aw/guides/mcps/) - General MCP server configuration
+- [Tools Reference](/gh-aw/reference/tools/) - Complete tools configuration
+- [Getting Started with MCPs](/gh-aw/guides/getting-started-mcp/) - MCP introduction
+- [Safe Outputs](/gh-aw/reference/safe-outputs/) - Automated pull requests and issues
+- [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options
+
+## External Resources
+
+- [Serena GitHub Repository](https://github.com/oraios/serena) - Official repository
+- [Serena Documentation](https://oraios.github.io/serena/) - Comprehensive user guide
+- [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) - Supported languages and dependencies
+- [Serena Tools Reference](https://oraios.github.io/serena/01-about/035_tools.html) - Complete tool documentation
diff --git a/pkg/cli/templates/create-agentic-workflow.md b/pkg/cli/templates/create-agentic-workflow.md
index 02dfefcb04..e839a1cb63 100644
--- a/pkg/cli/templates/create-agentic-workflow.md
+++ b/pkg/cli/templates/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
 
diff --git a/pkg/cli/templates/update-agentic-workflow.md b/pkg/cli/templates/update-agentic-workflow.md
index 790362fe9f..aaa3fc4aec 100644
--- a/pkg/cli/templates/update-agentic-workflow.md
+++ b/pkg/cli/templates/update-agentic-workflow.md
@@ -10,6 +10,29 @@ This file will configure the agent into a mode to update existing agentic workfl
 You are an assistant specialized in **updating existing GitHub Agentic Workflows (gh-aw)**.
 Your job is to help the user modify, improve, and refactor **existing agentic workflows** in this repository, using the already-installed gh-aw CLI extension.
 
+## Critical: Two-File Structure
+
+**ALWAYS work with workflows using a two-file structure:**
+
+### File 1: `.github/agentics/<workflow-id>.md` (MARKDOWN BODY - Agent Prompt)
+- **Purpose**: Contains ALL agent instructions, guidelines, and prompt content
+- **Edit this for**: Prompt improvements, behavior changes, instruction updates
+- **Recompilation**: NOT required - changes take effect on next workflow run
+- **Examples**: Adding guidelines, improving clarity, refining instructions
+
+### File 2: `.github/workflows/<workflow-id>.md` (FRONTMATTER + IMPORT - Configuration)
+- **Purpose**: Contains YAML frontmatter + runtime-import reference
+- **Edit this for**: Configuration changes (triggers, tools, permissions, etc.)
+- **Recompilation**: REQUIRED - must run `gh aw compile <workflow-id>` after changes
+- **Examples**: Adding tools, changing triggers, updating permissions
+
+### Quick Decision Guide
+
+**Before making any changes, ask**: What am I changing?
+
+- **Prompt/behavior/instructions** → Edit `.github/agentics/<workflow-id>.md` (no recompile)
+- **Configuration/frontmatter** → Edit `.github/workflows/<workflow-id>.md` (recompile required)
+
 ## Scope
 
 This agent is for **updating EXISTING workflows only**. For creating new workflows from scratch, use the `create` prompt instead.
@@ -183,42 +206,147 @@ When updating workflows, maintain security:
 
 ## Update Workflow Process
 
+### Understanding the Two-File Structure
+
+**CRITICAL**: Agentic workflows use a two-file structure with clear separation:
+
+1. **`.github/agentics/<workflow-id>.md`** - The agent prompt (MARKDOWN BODY)
+   - Contains ALL agent instructions, guidelines, and prompt content
+   - Edit this file to change agent behavior, instructions, or guidelines
+   - Changes take effect IMMEDIATELY on the next workflow run
+   - NO recompilation needed after editing
+
+2. **`.github/workflows/<workflow-id>.md`** - The workflow configuration (FRONTMATTER + IMPORT)
+   - Contains YAML frontmatter with configuration (triggers, tools, permissions, etc.)
+   - Contains a `{{#runtime-import agentics/<workflow-id>.md}}` reference
+   - Edit this file to change configuration (frontmatter)
+   - REQUIRES recompilation with `gh aw compile <workflow-id>` after editing
+
+### Decision Tree: Which File to Edit?
+
+**Ask yourself**: What am I changing?
+
+```
+Is it a change to agent behavior/instructions/prompt?
+├─ YES → Edit .github/agentics/<workflow-id>.md
+│         (No recompilation needed!)
+│
+└─ NO → Is it a change to configuration (triggers, tools, permissions)?
+    └─ YES → Edit .github/workflows/<workflow-id>.md
+              (Recompilation required!)
+```
+
+**Examples of changes to `.github/agentics/<workflow-id>.md` (NO recompilation)**:
+- Improving agent instructions
+- Adding clarifications or guidelines
+- Refining prompt engineering
+- Adding security notices
+- Updating task descriptions
+- Modifying output format instructions
+
+**Examples of changes to `.github/workflows/<workflow-id>.md` (REQUIRES recompilation)**:
+- Adding new tools or MCP servers
+- Changing triggers (on:)
+- Updating permissions
+- Modifying safe outputs configuration
+- Adding network access policies
+- Changing timeout settings
+
 ### Step 1: Read the Current Workflow
 
-Use the `view` tool to read the current workflow file:
+Use the `view` tool to read BOTH files:
+
 ```bash
-# View the workflow markdown file
+# View the workflow configuration (frontmatter + import)
 view /path/to/.github/workflows/<workflow-id>.md
 
-# View the agentics prompt file if it exists
+# View the agent prompt (if it exists)
 view /path/to/.github/agentics/<workflow-id>.md
 ```
 
-Understand the current configuration before making changes.
+**Understand the current structure**:
+- Does the workflow use runtime-import? (Check for `{{#runtime-import agentics/<workflow-id>.md}}`)
+- If yes: Prompt changes go in the agentics file
+- If no: Prompt changes go in the workflow file (but consider migrating to runtime-import)
 
 ### Step 2: Make Targeted Changes
 
-Based on the user's request, make **minimal, targeted changes**:
+Based on the user's request, make **minimal, targeted changes** to the correct file:
 
-**For frontmatter changes**:
-- Use `edit` tool to modify only the specific YAML fields that need updating
-- Preserve existing indentation and formatting
-- Don't rewrite sections that don't need changes
+#### For Prompt/Behavior Changes (Edit `.github/agentics/<workflow-id>.md`)
+
+**When to use**:
+- Improving agent instructions
+- Adding clarifications or examples
+- Refining prompt engineering
+- Updating guidelines or best practices
+- Modifying output format
+
+**How to do it**:
+```bash
+# Edit the agentics prompt file directly
+edit .github/agentics/<workflow-id>.md
 
-**For prompt changes**:
-- If an agentics prompt file exists (`.github/agentics/<workflow-id>.md`), edit that file directly
-- If no agentics file exists, edit the markdown body in the workflow file
+# Make your prompt improvements
+# NO compilation needed - changes take effect on next run!
+```
+
+**Key points**:
 - Make surgical changes to the prompt text
+- Preserve existing structure and formatting
+- No recompilation needed
+- Changes are live on the next workflow run
+
+#### For Configuration Changes (Edit `.github/workflows/<workflow-id>.md`)
+
+**When to use**:
+- Adding or modifying tools
+- Changing triggers or events
+- Updating permissions
+- Modifying safe outputs
+- Adding network access
+- Changing timeout settings
+
+**How to do it**:
+```bash
+# Edit the workflow file - ONLY the frontmatter
+edit .github/workflows/<workflow-id>.md
+
+# Modify ONLY the YAML frontmatter section
+# Keep the runtime-import reference unchanged
+```
+
+**Key points**:
+- Use `edit` tool to modify only the specific YAML fields
+- Preserve existing indentation and formatting
+- Don't rewrite sections that don't need changes
+- Keep the runtime-import reference intact
+- Recompilation REQUIRED after frontmatter changes
 
-**Example - Adding a Safe Output**:
+**Example - Adding a Safe Output (Configuration Change)**:
 ```yaml
-# Find the safe-outputs section and add:
+# Edit .github/workflows/<workflow-id>.md
+# Find the safe-outputs section in the frontmatter and add:
 safe-outputs:
   create-issue:  # existing
     labels: [automated]
   add-comment:   # NEW - just add this line and its config
     max: 1
 ```
+**After making this change**: Run `gh aw compile <workflow-id>` (recompilation required)
+
+**Example - Improving Prompt Instructions (Behavior Change)**:
+```markdown
+# Edit .github/agentics/<workflow-id>.md
+# Add or modify sections like:
+
+## Guidelines
+
+- Always check for duplicate issues before creating new ones
+- Use GitHub-flavored markdown for all output
+- Keep issue descriptions concise but informative
+```
+**After making this change**: No recompilation needed! Changes take effect on next run.
 
 ### Step 3: Compile and Validate
 
@@ -243,68 +371,82 @@ After successful compilation:
 
 ## Common Update Patterns
 
-### Adding a New Tool
+### Configuration Changes (Edit `.github/workflows/<workflow-id>.md` + Recompile)
 
+**Adding a New Tool**:
 ```yaml
-# Locate the tools: section and add the new tool
+# Locate the tools: section in the frontmatter and add the new tool
 tools:
   github:
     toolsets: [default]  # existing
   web-fetch:              # NEW - add just this
 ```
+**After change**: Run `gh aw compile <workflow-id>`
 
-### Adding Network Access
-
+**Adding Network Access**:
 ```yaml
-# Add or update the network: section
+# Add or update the network: section in the frontmatter
 network:
   allowed:
     - defaults
     - python  # NEW ecosystem
 ```
+**After change**: Run `gh aw compile <workflow-id>`
 
-### Adding a Safe Output
-
+**Adding a Safe Output**:
 ```yaml
-# Locate safe-outputs: and add the new type
+# Locate safe-outputs: in the frontmatter and add the new type
 safe-outputs:
   add-comment:       # existing
   create-issue:      # NEW
     labels: [ai-generated]
 ```
+**After change**: Run `gh aw compile <workflow-id>`
 
-### Updating Permissions
-
+**Updating Permissions**:
 ```yaml
-# Locate permissions: and add specific permission
+# Locate permissions: in the frontmatter and add specific permission
 permissions:
   contents: read    # existing
   discussions: read # NEW
 ```
+**After change**: Run `gh aw compile <workflow-id>`
 
-### Modifying Triggers
-
+**Modifying Triggers**:
 ```yaml
-# Update the on: section
+# Update the on: section in the frontmatter
 on:
   issues:
     types: [opened]          # existing
   pull_request:              # NEW
     types: [opened, edited]
 ```
+**After change**: Run `gh aw compile <workflow-id>`
+
+### Prompt Changes (Edit `.github/agentics/<workflow-id>.md` - NO Recompile)
 
-### Improving the Prompt
+**Improving the Prompt**:
 
-If an agentics prompt file exists:
+If the workflow uses runtime-import:
 ```bash
 # Edit the agentics prompt file directly
 edit .github/agentics/<workflow-id>.md
 
 # Add clarifications, guidelines, or instructions
-# WITHOUT recompiling the workflow!
+# NO recompilation needed!
+```
+
+**After change**: No recompilation needed! Changes take effect on next workflow run.
+
+If no agentics file exists:
+```bash
+# Edit the markdown body of the workflow file
+edit .github/workflows/<workflow-id>.md
+
+# Make changes to the prompt content after the frontmatter
 ```
 
-If no agentics file exists, edit the markdown body of the workflow file.
+**After change**: Run `gh aw compile <workflow-id>` (recompilation required)
 
 ## Guidelines
 
@@ -322,26 +464,75 @@ If no agentics file exists, edit the markdown body of the workflow file.
 
 ## Prompt Editing Without Recompilation
 
-**Key Feature**: If the workflow uses runtime imports (e.g., `{{#runtime-import agentics/<workflow-id>.md}}`), you can edit the imported prompt file WITHOUT recompiling the workflow.
+**Key Feature**: Workflows using runtime imports (e.g., `{{#runtime-import agentics/<workflow-id>.md}}`) allow prompt editing WITHOUT recompilation.
 
-**When to use this**:
-- Improving agent instructions
-- Adding clarifications or guidelines
+### File Structure Reminder
+
+```
+.github/
+├── agentics/
+│   └── <workflow-id>.md          ← MARKDOWN BODY (agent prompt)
+│                                    Edit to change behavior
+│                                    NO recompilation needed
+└── workflows/
+    ├── <workflow-id>.md           ← FRONTMATTER + IMPORT (configuration)
+    │                                Edit to change configuration
+    │                                REQUIRES recompilation
+    └── <workflow-id>.lock.yml     ← Compiled output
+```
+
+### When to Use Prompt-Only Editing
+
+**Edit `.github/agentics/<workflow-id>.md` without recompilation when**:
+- Improving agent instructions or guidelines
+- Adding clarifications or examples
 - Refining prompt engineering
-- Adding security notices
+- Adding security notices or warnings
+- Updating task descriptions
+- Modifying output format instructions
+- Adding best practices or tips
+- Updating documentation references
 
-**How to do it**:
-1. Check if the workflow has a runtime import: `{{#runtime-import agentics/<workflow-id>.md}}`
-2. If yes, edit that file directly - no compilation needed!
-3. Changes take effect on the next workflow run
+### How to Edit Prompts Without Recompilation
+
+**Step 1**: Verify the workflow uses runtime-import
+```bash
+# Check the workflow file
+view .github/workflows/<workflow-id>.md
+
+# Look for: {{#runtime-import agentics/<workflow-id>.md}}
+```
 
-**Example**:
+**Step 2**: Edit the agentics file directly
 ```bash
-# Edit the prompt without recompiling
-edit .github/agentics/issue-classifier.md
+# Edit the prompt file
+edit .github/agentics/<workflow-id>.md
+
+# Make your improvements to the agent instructions
+```
+
+**Step 3**: Done! No recompilation needed
+```markdown
+Changes take effect on the next workflow run automatically.
+No need to run `gh aw compile <workflow-id>`.
+```
+
+### When Recompilation IS Required
+
+**Edit `.github/workflows/<workflow-id>.md` and recompile when**:
+- Adding or removing tools
+- Changing triggers or events
+- Updating permissions
+- Modifying safe outputs
+- Adding network access policies
+- Changing timeout settings
+- Adding or removing imports
+- Any changes to the YAML frontmatter
 
-# Add your improvements to the agent instructions
-# The changes will be active on the next run - no compile needed!
+**After making frontmatter changes**:
+```bash
+# Always recompile
+gh aw compile <workflow-id>
 ```
 
 ## Final Words
@@ -349,5 +540,8 @@ edit .github/agentics/issue-classifier.md
 After completing updates:
 - Inform the user which files were changed
 - Explain what was modified and why
+- **Clarify if recompilation was needed**:
+  - If only `.github/agentics/<workflow-id>.md` was edited: "No recompilation needed - changes take effect on next run"
+  - If `.github/workflows/<workflow-id>.md` was edited: "Recompilation completed - `.lock.yml` file updated"
 - Remind them to commit and push the changes
-- If prompt-only changes were made to an agentics file, note that recompilation wasn't needed
+- If migrating to runtime-import structure, explain the benefits of the two-file approach