diff --git a/.github/agents/ci-cleaner.agent.md b/.github/agents/ci-cleaner.agent.md index 458d40aa2eb..44d24b2124a 100644 --- a/.github/agents/ci-cleaner.agent.md +++ b/.github/agents/ci-cleaner.agent.md @@ -9,9 +9,23 @@ You are a specialized AI agent that **tidies up the repository CI state** in the Read the ENTIRE content of this file carefully before proceeding. Follow the instructions precisely. +## First Step: Check CI Status + +**IMPORTANT**: Before doing any work, check if the CI is currently failing or passing by examining the workflow context provided to you. + +If the workflow context indicates that **CI is passing** (e.g., `ci_status: success`): +1. **STOP immediately** - Do not run any commands +2. **Call the `noop` tool** (from the safe-outputs MCP server) with a message like: + ``` + CI is passing on main branch - no cleanup needed + ``` +3. **Exit** - Your work is done + +If the workflow context indicates that **CI is failing** (e.g., `ci_status: failure`), proceed with the cleanup tasks below. + ## Your Responsibilities -You perform the following tasks in sequence to clean up the CI state: +When CI is failing, you perform the following tasks in sequence to clean up the CI state: 1. **Format sources** (Go, JavaScript, JSON) 2. **Run linters** and fix any linting issues diff --git a/.github/workflows/hourly-ci-cleaner.lock.yml b/.github/workflows/hourly-ci-cleaner.lock.yml index 4b99a47bf2f..d98cdcd0e17 100644 --- a/.github/workflows/hourly-ci-cleaner.lock.yml +++ b/.github/workflows/hourly-ci-cleaner.lock.yml @@ -25,7 +25,7 @@ # Imports: # - ../agents/ci-cleaner.agent.md # -# frontmatter-hash: 44346eb8bced718907376c4997b4d6c2cd9c50748d1edf8f24b34fde3f84a076 +# frontmatter-hash: cf34c9ca048904e350b43974103be2dc6b03a96ca98d7459e8ce4c281e8d185e name: "CI Cleaner" "on": @@ -576,9 +576,23 @@ jobs: Read the ENTIRE content of this file carefully before proceeding. Follow the instructions precisely. + ## First Step: Check CI Status + + **IMPORTANT**: Before doing any work, check if the CI is currently failing or passing by examining the workflow context provided to you. + + If the workflow context indicates that **CI is passing** (e.g., `ci_status: success`): + 1. **STOP immediately** - Do not run any commands + 2. **Call the `noop` tool** (from the safe-outputs MCP server) with a message like: + ``` + CI is passing on main branch - no cleanup needed + ``` + 3. **Exit** - Your work is done + + If the workflow context indicates that **CI is failing** (e.g., `ci_status: failure`), proceed with the cleanup tasks below. + ## Your Responsibilities - You perform the following tasks in sequence to clean up the CI state: + When CI is failing, you perform the following tasks in sequence to clean up the CI state: 1. **Format sources** (Go, JavaScript, JSON) 2. **Run linters** and fix any linting issues @@ -864,9 +878,17 @@ jobs: - **CI Status**: __GH_AW_NEEDS_CHECK_CI_STATUS_OUTPUTS_CI_STATUS__ - **CI Run ID**: __GH_AW_NEEDS_CHECK_CI_STATUS_OUTPUTS_CI_RUN_ID__ - ## Your Task + ## First: Check CI Status - The CI workflow has failed on the main branch. Follow the instructions from the ci-cleaner agent to: + **CRITICAL**: Before starting any work, check the CI Status value above: + + - **If CI Status is "success"**: The CI is passing. **Call the `noop` tool** immediately with message "CI is passing on main branch - no cleanup needed" and **stop**. Do not run any commands or make any changes. + + - **If CI Status is "failure"** or anything else: The CI workflow has failed. Proceed with the cleanup tasks below. + + ## Your Task (Only if CI Status is "failure") + + Follow the instructions from the ci-cleaner agent to: 1. **Format sources** - Run `make fmt` to format all code 2. **Run linters** - Run `make lint` and fix any issues @@ -1124,12 +1146,15 @@ jobs: runs-on: ubuntu-latest permissions: actions: read + contents: read outputs: ci_needs_fix: ${{ steps.ci_check.outputs.ci_needs_fix }} ci_run_id: ${{ steps.ci_check.outputs.ci_run_id }} ci_status: ${{ steps.ci_check.outputs.ci_status }} steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 11bd71901bbe5b1630ceea73d27597364c9af683 - name: Check last CI workflow run status on main branch id: ci_check run: | diff --git a/.github/workflows/hourly-ci-cleaner.md b/.github/workflows/hourly-ci-cleaner.md index 9c6d9ed8f31..deac777f023 100644 --- a/.github/workflows/hourly-ci-cleaner.md +++ b/.github/workflows/hourly-ci-cleaner.md @@ -41,11 +41,14 @@ jobs: runs-on: ubuntu-latest permissions: actions: read + contents: read outputs: ci_needs_fix: ${{ steps.ci_check.outputs.ci_needs_fix }} ci_status: ${{ steps.ci_check.outputs.ci_status }} ci_run_id: ${{ steps.ci_check.outputs.ci_run_id }} steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - name: Check last CI workflow run status on main branch id: ci_check env: @@ -122,9 +125,17 @@ When CI fails on the main branch, automatically diagnose and fix the issues by: - **CI Status**: ${{ needs.check_ci_status.outputs.ci_status }} - **CI Run ID**: ${{ needs.check_ci_status.outputs.ci_run_id }} -## Your Task +## First: Check CI Status -The CI workflow has failed on the main branch. Follow the instructions from the ci-cleaner agent to: +**CRITICAL**: Before starting any work, check the CI Status value above: + +- **If CI Status is "success"**: The CI is passing. **Call the `noop` tool** immediately with message "CI is passing on main branch - no cleanup needed" and **stop**. Do not run any commands or make any changes. + +- **If CI Status is "failure"** or anything else: The CI workflow has failed. Proceed with the cleanup tasks below. + +## Your Task (Only if CI Status is "failure") + +Follow the instructions from the ci-cleaner agent to: 1. **Format sources** - Run `make fmt` to format all code 2. **Run linters** - Run `make lint` and fix any issues diff --git a/pkg/cli/templates/create-agentic-workflow.md b/pkg/cli/templates/create-agentic-workflow.md index faf93741d6f..bbe54a4a9e1 100644 --- a/pkg/cli/templates/create-agentic-workflow.md +++ b/pkg/cli/templates/create-agentic-workflow.md @@ -10,13 +10,33 @@ 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. -## Workflow File Structure +## Critical: Two-File Structure -Workflows are created as markdown files in `.github/workflows/` directory with: -- **YAML frontmatter**: Configuration (triggers, tools, permissions, etc.) -- **Markdown body**: Agent instructions, guidelines, and prompt content +**ALWAYS create workflows using a two-file structure with clear separation of concerns:** -All workflow changes require recompilation with `gh aw compile ` to update the `.lock.yml` file. +### File 1: `.github/agentics/.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/.md` (FRONTMATTER + IMPORT - Configuration) +- **Purpose**: Contains YAML frontmatter with configuration + runtime-import reference +- **Editability**: Requires recompilation with `gh aw compile ` after changes +- **Changes**: Only for configuration (triggers, tools, permissions, etc.) +- **Content**: YAML frontmatter only + `{{#runtime-import agentics/.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/.md` (no recompile) +- Configuration changes → Edit `.github/workflows/.md` (recompile required) ## Two Modes of Operation @@ -42,7 +62,7 @@ When triggered from a GitHub issue created via the "Create an Agentic Workflow" - Use a kebab-case workflow ID derived from the workflow name (e.g., "Issue Classifier" → "issue-classifier") - **CRITICAL**: Before creating, check if the file exists. If it does, append a suffix like `-v2` or a timestamp - Include complete frontmatter with all necessary configuration - - Write a clear prompt body with instructions for the AI agent in the markdown body + - Write a clear prompt body with instructions for the AI agent 4. **Compile the Workflow** using `gh aw compile ` to generate the `.lock.yml` file @@ -259,39 +279,37 @@ 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 File +### Step 3: Create the Workflow Files (Two-File Structure) -**File**: `.github/workflows/.md` +**IMPORTANT**: Always create TWO files with a clear separation of concerns: + +1. **`.github/agentics/.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 -This file contains both the YAML frontmatter configuration and the complete agent prompt in the markdown body. +2. **`.github/workflows/.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/.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 Complete Workflow File +#### Step 3.2: Create the Agentics Prompt File (Markdown Body) + +**File**: `.github/agentics/.md` + +This file contains the COMPLETE agent prompt that can be edited without recompilation. **Structure**: ```markdown ---- -description: -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 ---- + + # @@ -317,10 +335,49 @@ When you successfully complete your work: ``` **Key points**: -- Include complete YAML frontmatter with all configuration -- Follow frontmatter with the agent's complete prompt in markdown -- Put ALL agent instructions in the markdown body -- Users need to recompile the workflow after any changes +- 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/.md` + +This file contains ONLY the YAML frontmatter and a runtime-import reference. + +**Structure**: +```markdown +--- +description: +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/.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 @@ -336,16 +393,22 @@ If compilation fails with syntax errors: ### Step 5: Create a Pull Request -Create a PR with both files: -1. **`.github/workflows/.md`** - Workflow with configuration and prompt - - Contains YAML frontmatter and agent prompt in markdown body - - Requires recompilation after any changes -2. **`.github/workflows/.lock.yml`** - Compiled workflow +Create a PR with all three files: +1. **`.github/agentics/.md`** - Agent prompt (MARKDOWN BODY) + - Can be edited to change agent behavior without recompilation + - Changes take effect on next workflow run +2. **`.github/workflows/.md`** - Workflow configuration (FRONTMATTER + IMPORT) + - Contains YAML frontmatter and runtime-import reference + - Requires recompilation when frontmatter changes +3. **`.github/workflows/.lock.yml`** - Compiled workflow - Generated by `gh aw compile ` - 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/.md` (no recompilation needed) + - To modify configuration/frontmatter: Edit `.github/workflows/.md` and run `gh aw compile ` - 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 a69a0ded44e..aaa3fc4aec5 100644 --- a/pkg/cli/templates/update-agentic-workflow.md +++ b/pkg/cli/templates/update-agentic-workflow.md @@ -10,13 +10,28 @@ 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. -## Workflow File Structure +## Critical: Two-File Structure -Workflows are created as markdown files in `.github/workflows/` directory with: -- **YAML frontmatter**: Configuration (triggers, tools, permissions, etc.) -- **Markdown body**: Agent instructions, guidelines, and prompt content +**ALWAYS work with workflows using a two-file structure:** -All workflow changes require recompilation with `gh aw compile ` to update the `.lock.yml` file. +### File 1: `.github/agentics/.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/.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 ` 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/.md` (no recompile) +- **Configuration/frontmatter** → Edit `.github/workflows/.md` (recompile required) ## Scope @@ -89,12 +104,12 @@ Wait for the user to respond before proceeding. ### 🎯 Make Small, Incremental Changes -**CRITICAL**: When updating existing workflows, make **small, incremental changes** only. Do NOT rewrite the entire workflow unless absolutely necessary. +**CRITICAL**: When updating existing workflows, make **small, incremental changes** only. Do NOT rewrite the entire frontmatter unless absolutely necessary. -- ✅ **DO**: Only add/modify the specific fields or sections needed to address the user's request +- ✅ **DO**: Only add/modify the specific fields needed to address the user's request - ✅ **DO**: Preserve existing configuration patterns and style - ✅ **DO**: Keep changes minimal and focused on the goal -- ❌ **DON'T**: Rewrite entire frontmatter or markdown body sections that don't need changes +- ❌ **DON'T**: Rewrite entire frontmatter sections that don't need changes - ❌ **DON'T**: Add unnecessary fields with default values - ❌ **DON'T**: Change existing patterns unless specifically requested @@ -118,7 +133,7 @@ tools: --- # ✅ GOOD - Only adds what's needed -# Original frontmatter stays intact, just add the new tool: +# Original frontmatter stays intact, just append: tools: web-fetch: ``` @@ -191,38 +206,122 @@ 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/.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/.md`** - The workflow configuration (FRONTMATTER + IMPORT) + - Contains YAML frontmatter with configuration (triggers, tools, permissions, etc.) + - Contains a `{{#runtime-import agentics/.md}}` reference + - Edit this file to change configuration (frontmatter) + - REQUIRES recompilation with `gh aw compile ` 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/.md +│ (No recompilation needed!) +│ +└─ NO → Is it a change to configuration (triggers, tools, permissions)? + └─ YES → Edit .github/workflows/.md + (Recompilation required!) +``` + +**Examples of changes to `.github/agentics/.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/.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 workflow file: +Use the `view` tool to read BOTH files: ```bash -# View the workflow file (frontmatter + markdown body) +# View the workflow configuration (frontmatter + import) view /path/to/.github/workflows/.md + +# View the agent prompt (if it exists) +view /path/to/.github/agentics/.md ``` +**Understand the current structure**: +- Does the workflow use runtime-import? (Check for `{{#runtime-import agentics/.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 Any Changes (Edit `.github/workflows/.md`) +#### For Prompt/Behavior Changes (Edit `.github/agentics/.md`) -All changes to workflows require editing `.github/workflows/.md` which contains both the configuration frontmatter and the agent prompt in the markdown body. +**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 workflow file +# Edit the agentics prompt file directly +edit .github/agentics/.md + +# 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/.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/.md -# Make your targeted changes to either: -# - YAML frontmatter (for configuration changes) -# - Markdown body (for prompt/behavior changes) +# Modify ONLY the YAML frontmatter section +# Keep the runtime-import reference unchanged ``` **Key points**: -- Use `edit` tool to modify only the specific YAML fields or markdown sections needed +- Use `edit` tool to modify only the specific YAML fields - Preserve existing indentation and formatting - Don't rewrite sections that don't need changes -- Recompilation REQUIRED after any changes +- Keep the runtime-import reference intact +- Recompilation REQUIRED after frontmatter changes **Example - Adding a Safe Output (Configuration Change)**: ```yaml @@ -238,8 +337,8 @@ safe-outputs: **Example - Improving Prompt Instructions (Behavior Change)**: ```markdown -# Edit .github/workflows/.md -# Add or modify sections in the markdown body: +# Edit .github/agentics/.md +# Add or modify sections like: ## Guidelines @@ -247,7 +346,7 @@ safe-outputs: - Use GitHub-flavored markdown for all output - Keep issue descriptions concise but informative ``` -**After making this change**: Run `gh aw compile ` (recompilation required) +**After making this change**: No recompilation needed! Changes take effect on next run. ### Step 3: Compile and Validate @@ -272,7 +371,9 @@ After successful compilation: ## Common Update Patterns -### Adding a New Tool: +### Configuration Changes (Edit `.github/workflows/.md` + Recompile) + +**Adding a New Tool**: ```yaml # Locate the tools: section in the frontmatter and add the new tool tools: @@ -282,7 +383,7 @@ tools: ``` **After change**: Run `gh aw compile ` -### Adding Network Access: +**Adding Network Access**: ```yaml # Add or update the network: section in the frontmatter network: @@ -292,7 +393,7 @@ network: ``` **After change**: Run `gh aw compile ` -### Adding a Safe Output: +**Adding a Safe Output**: ```yaml # Locate safe-outputs: in the frontmatter and add the new type safe-outputs: @@ -302,7 +403,7 @@ safe-outputs: ``` **After change**: Run `gh aw compile ` -### Updating Permissions: +**Updating Permissions**: ```yaml # Locate permissions: in the frontmatter and add specific permission permissions: @@ -311,7 +412,7 @@ permissions: ``` **After change**: Run `gh aw compile ` -### Modifying Triggers: +**Modifying Triggers**: ```yaml # Update the on: section in the frontmatter on: @@ -322,19 +423,30 @@ on: ``` **After change**: Run `gh aw compile ` -### Improving the Prompt: +### Prompt Changes (Edit `.github/agentics/.md` - NO Recompile) + +**Improving the Prompt**: + +If the workflow uses runtime-import: +```bash +# Edit the agentics prompt file directly +edit .github/agentics/.md + +# Add clarifications, guidelines, or instructions +# NO recompilation needed! +``` -Edit the markdown body of the workflow file to add clarifications, guidelines, or instructions: +**After change**: No recompilation needed! Changes take effect on next workflow run. +If no agentics file exists: ```bash -# Edit the workflow file +# Edit the markdown body of the workflow file edit .github/workflows/.md -# Add clarifications, guidelines, or instructions in the markdown body # Make changes to the prompt content after the frontmatter ``` -**After change**: Run `gh aw compile ` +**After change**: Run `gh aw compile ` (recompilation required) ## Guidelines @@ -350,10 +462,86 @@ edit .github/workflows/.md - Always follow security best practices (least privilege, safe outputs, constrained network) - Skip verbose summaries at the end, keep it concise +## Prompt Editing Without Recompilation + +**Key Feature**: Workflows using runtime imports (e.g., `{{#runtime-import agentics/.md}}`) allow prompt editing WITHOUT recompilation. + +### File Structure Reminder + +``` +.github/ +├── agentics/ +│ └── .md ← MARKDOWN BODY (agent prompt) +│ Edit to change behavior +│ NO recompilation needed +└── workflows/ + ├── .md ← FRONTMATTER + IMPORT (configuration) + │ Edit to change configuration + │ REQUIRES recompilation + └── .lock.yml ← Compiled output +``` + +### When to Use Prompt-Only Editing + +**Edit `.github/agentics/.md` without recompilation when**: +- Improving agent instructions or guidelines +- Adding clarifications or examples +- Refining prompt engineering +- Adding security notices or warnings +- Updating task descriptions +- Modifying output format instructions +- Adding best practices or tips +- Updating documentation references + +### How to Edit Prompts Without Recompilation + +**Step 1**: Verify the workflow uses runtime-import +```bash +# Check the workflow file +view .github/workflows/.md + +# Look for: {{#runtime-import agentics/.md}} +``` + +**Step 2**: Edit the agentics file directly +```bash +# Edit the prompt file +edit .github/agentics/.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 `. +``` + +### When Recompilation IS Required + +**Edit `.github/workflows/.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 + +**After making frontmatter changes**: +```bash +# Always recompile +gh aw compile +``` + ## Final Words After completing updates: -- Inform the user which file was changed +- Inform the user which files were changed - Explain what was modified and why +- **Clarify if recompilation was needed**: + - If only `.github/agentics/.md` was edited: "No recompilation needed - changes take effect on next run" + - If `.github/workflows/.md` was edited: "Recompilation completed - `.lock.yml` file updated" - Remind them to commit and push the changes -- Note that recompilation is always required after workflow changes +- If migrating to runtime-import structure, explain the benefits of the two-file approach