From 6862b038216b792d53f38f988e0801d80cf4582a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 7 Nov 2025 13:13:51 +0000 Subject: [PATCH 1/2] Initial plan From d4b97cc11394ee33aab0649985bd207d81f4196c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 7 Nov 2025 13:19:42 +0000 Subject: [PATCH 2/2] Apply patch: Enable direct file editing in developer-docs-consolidator workflow Enhanced the workflow to explicitly inform the AI agent that it can: - Directly edit files using edit tools - Create pull requests automatically via safe-outputs Key changes: - Updated Mission statement to clarify agent can apply changes directly - Added prominent note about direct file editing capabilities - Updated Phase 3 to emphasize using edit tools to apply changes - Rewrote Phase 5 to explain two-step process (edit files, then auto-PR) - Updated Success Criteria to emphasize making actual file changes Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../developer-docs-consolidator.lock.yml | 80 ++++++++++++++----- .../workflows/developer-docs-consolidator.md | 68 ++++++++++++---- 2 files changed, 114 insertions(+), 34 deletions(-) diff --git a/.github/workflows/developer-docs-consolidator.lock.yml b/.github/workflows/developer-docs-consolidator.lock.yml index 0ee6e50bee5..58b593a9429 100644 --- a/.github/workflows/developer-docs-consolidator.lock.yml +++ b/.github/workflows/developer-docs-consolidator.lock.yml @@ -1342,7 +1342,9 @@ jobs: ## Mission - Analyze markdown files in the specs directory, standardize their tone and formatting, consolidate them into a single instructions file, and report on the changes made. + Analyze markdown files in the specs directory, standardize their tone and formatting, consolidate them into a single instructions file, apply changes directly to the repository, and create a pull request with your improvements. + + **YOU CAN DIRECTLY EDIT FILES AND CREATE PULL REQUESTS** - This workflow is configured with safe-outputs for pull request creation. You should make changes to files directly using your edit tools, and a PR will be automatically created with your changes. ## Current Context @@ -1475,9 +1477,11 @@ jobs: ## Phase 3: Content Adjustment + **Apply changes directly to files** - Don't just identify issues, fix them using your edit tools. + ### 1. Fix Tone Issues - For each file with tone issues, use the edit tool to: + For each file with tone issues, **use the edit tool to make the changes directly**: **Replace marketing language:** ```markdown @@ -1497,14 +1501,18 @@ jobs: NEW: "Configure the workflow by specifying the following YAML fields:" ``` + **Action**: Use `edit` tool to make these changes in the spec files directly. + ### 2. Standardize Formatting - Apply consistent formatting: + Apply consistent formatting **by editing the files**: - Convert bold headings to proper markdown headings - Add language tags to code blocks (```yaml, ```go, ```bash) - Break up long bullet lists into prose or tables - Ensure consistent heading levels + **Action**: Use `edit` tool to apply formatting fixes directly. + ### 3. Add Mermaid Diagrams Where concepts need visual clarification, add Mermaid diagrams: @@ -1576,7 +1584,7 @@ jobs: ### 3. Create the Consolidated File - Write the consolidated content to `.github/instructions/developer.instructions.md` using the edit tool. + **You have direct file editing capabilities** - Write the consolidated content directly to `.github/instructions/developer.instructions.md` using Serena's edit tools. The file should: - Start with frontmatter (description and applyTo) @@ -1586,6 +1594,11 @@ jobs: - Provide actionable guidance - Reference specific files/code where relevant + **Use Serena's tools to make the changes:** + - If the file exists: Use `serena-replace_symbol_body` or standard edit tools to update sections + - If the file doesn't exist: Use `create` tool to create the new file + - Make all necessary edits directly - don't just report what should change + ## Phase 5: Validation and Reporting ### 1. Validate Consolidated File @@ -1748,13 +1761,41 @@ jobs: ### 5. Create Pull Request (If Changes Made) - If you made any changes to files: + **Pull requests are created automatically via safe-outputs** - When you make file changes, the workflow will automatically create a PR with those changes. + + #### Step 1: Apply Changes Directly to Files - Use safe-outputs to create a pull request with: + Before the PR is created, you need to make the actual file changes: - **PR Title**: `[docs] Consolidate developer specifications into instructions file` + 1. **Update `.github/instructions/developer.instructions.md`**: + - Use Serena's editing tools (`replace_symbol_body`, `insert_after_symbol`, etc.) + - Or use the standard `edit` tool to modify sections + - Make all consolidation changes directly to the file - **PR Description**: + 2. **Optionally update spec files** (if tone fixes are needed): + - Fix marketing language in spec files + - Standardize formatting issues + - Add Mermaid diagrams to spec sources + + **Tools available for editing:** + - `serena-replace_symbol_body` - Replace sections in structured files + - `serena-insert_after_symbol` - Add new sections + - Standard `edit` tool - Make targeted changes + - Standard `create` tool - Create new files + + #### Step 2: PR Created Automatically + + After you've made file changes, a pull request will be created automatically with: + + **PR Title**: `[docs] Consolidate developer specifications into instructions file` (automatically prefixed) + + PROMPT_EOF + - name: Append prompt (part 2) + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + run: | + cat >> "$GH_AW_PROMPT" << 'PROMPT_EOF' + **PR Description** (you should output this for the safe-output processor): ```markdown ## Developer Documentation Consolidation @@ -1770,7 +1811,7 @@ jobs: ### Files Modified - - Created: `.github/instructions/developer.instructions.md` + - Created/Updated: `.github/instructions/developer.instructions.md` - [List any spec files that were modified] ### Validation @@ -1791,6 +1832,11 @@ jobs: See the discussion [link to discussion] for detailed consolidation report. ``` + **Remember**: + - Make all file changes BEFORE outputting the PR description + - The PR will be created automatically with your changes + - You don't need to manually create the PR - safe-outputs handles it + ## Guidelines ### Technical Tone Standards @@ -1830,12 +1876,6 @@ jobs: ### Mermaid Diagram Guidelines - PROMPT_EOF - - name: Append prompt (part 2) - env: - GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt - run: | - cat >> "$GH_AW_PROMPT" << 'PROMPT_EOF' **Graph Types:** - `graph TD` - Top-down flowchart - `graph LR` - Left-right flowchart @@ -1862,15 +1902,15 @@ jobs: A successful consolidation run: - ✅ Analyzes all markdown files in specs/ - ✅ Uses Serena for static analysis - - ✅ Fixes tone issues (marketing → technical) - - ✅ Adds Mermaid diagrams where beneficial - - ✅ Creates consolidated instructions file + - ✅ Fixes tone issues (marketing → technical) **by directly editing files** + - ✅ Adds Mermaid diagrams where beneficial **by directly editing files** + - ✅ Creates/updates consolidated instructions file **using edit tools** - ✅ Stores metadata in cache-memory - ✅ Generates comprehensive report - ✅ Creates discussion with findings - - ✅ Creates PR with changes + - ✅ **Makes actual file changes that will be included in the automatic PR** - Begin the consolidation process now. Use Serena for analysis, adjust tone and formatting, add helpful Mermaid diagrams, consolidate into the instructions file, and report your findings through both a discussion and pull request. + Begin the consolidation process now. Use Serena for analysis, **directly apply changes** to adjust tone and formatting, add helpful Mermaid diagrams, consolidate into the instructions file, and report your findings through both a discussion and pull request. PROMPT_EOF - name: Append XPIA security instructions to prompt diff --git a/.github/workflows/developer-docs-consolidator.md b/.github/workflows/developer-docs-consolidator.md index f49beef0e14..bb95377652d 100644 --- a/.github/workflows/developer-docs-consolidator.md +++ b/.github/workflows/developer-docs-consolidator.md @@ -55,7 +55,9 @@ You are an AI documentation consistency agent that daily reviews markdown files ## Mission -Analyze markdown files in the specs directory, standardize their tone and formatting, consolidate them into a single instructions file, and report on the changes made. +Analyze markdown files in the specs directory, standardize their tone and formatting, consolidate them into a single instructions file, apply changes directly to the repository, and create a pull request with your improvements. + +**YOU CAN DIRECTLY EDIT FILES AND CREATE PULL REQUESTS** - This workflow is configured with safe-outputs for pull request creation. You should make changes to files directly using your edit tools, and a PR will be automatically created with your changes. ## Current Context @@ -188,9 +190,11 @@ Identify concepts that would benefit from Mermaid diagrams: ## Phase 3: Content Adjustment +**Apply changes directly to files** - Don't just identify issues, fix them using your edit tools. + ### 1. Fix Tone Issues -For each file with tone issues, use the edit tool to: +For each file with tone issues, **use the edit tool to make the changes directly**: **Replace marketing language:** ```markdown @@ -210,14 +214,18 @@ OLD: "Simply configure the workflow and you're done!" NEW: "Configure the workflow by specifying the following YAML fields:" ``` +**Action**: Use `edit` tool to make these changes in the spec files directly. + ### 2. Standardize Formatting -Apply consistent formatting: +Apply consistent formatting **by editing the files**: - Convert bold headings to proper markdown headings - Add language tags to code blocks (```yaml, ```go, ```bash) - Break up long bullet lists into prose or tables - Ensure consistent heading levels +**Action**: Use `edit` tool to apply formatting fixes directly. + ### 3. Add Mermaid Diagrams Where concepts need visual clarification, add Mermaid diagrams: @@ -289,7 +297,7 @@ For each topic: ### 3. Create the Consolidated File -Write the consolidated content to `.github/instructions/developer.instructions.md` using the edit tool. +**You have direct file editing capabilities** - Write the consolidated content directly to `.github/instructions/developer.instructions.md` using Serena's edit tools. The file should: - Start with frontmatter (description and applyTo) @@ -299,6 +307,11 @@ The file should: - Provide actionable guidance - Reference specific files/code where relevant +**Use Serena's tools to make the changes:** +- If the file exists: Use `serena-replace_symbol_body` or standard edit tools to update sections +- If the file doesn't exist: Use `create` tool to create the new file +- Make all necessary edits directly - don't just report what should change + ## Phase 5: Validation and Reporting ### 1. Validate Consolidated File @@ -461,13 +474,35 @@ The discussion should: ### 5. Create Pull Request (If Changes Made) -If you made any changes to files: +**Pull requests are created automatically via safe-outputs** - When you make file changes, the workflow will automatically create a PR with those changes. + +#### Step 1: Apply Changes Directly to Files -Use safe-outputs to create a pull request with: +Before the PR is created, you need to make the actual file changes: -**PR Title**: `[docs] Consolidate developer specifications into instructions file` +1. **Update `.github/instructions/developer.instructions.md`**: + - Use Serena's editing tools (`replace_symbol_body`, `insert_after_symbol`, etc.) + - Or use the standard `edit` tool to modify sections + - Make all consolidation changes directly to the file -**PR Description**: +2. **Optionally update spec files** (if tone fixes are needed): + - Fix marketing language in spec files + - Standardize formatting issues + - Add Mermaid diagrams to spec sources + +**Tools available for editing:** +- `serena-replace_symbol_body` - Replace sections in structured files +- `serena-insert_after_symbol` - Add new sections +- Standard `edit` tool - Make targeted changes +- Standard `create` tool - Create new files + +#### Step 2: PR Created Automatically + +After you've made file changes, a pull request will be created automatically with: + +**PR Title**: `[docs] Consolidate developer specifications into instructions file` (automatically prefixed) + +**PR Description** (you should output this for the safe-output processor): ```markdown ## Developer Documentation Consolidation @@ -483,7 +518,7 @@ This PR consolidates markdown specifications from the `specs/` directory into a ### Files Modified -- Created: `.github/instructions/developer.instructions.md` +- Created/Updated: `.github/instructions/developer.instructions.md` - [List any spec files that were modified] ### Validation @@ -504,6 +539,11 @@ Please review: See the discussion [link to discussion] for detailed consolidation report. ``` +**Remember**: +- Make all file changes BEFORE outputting the PR description +- The PR will be created automatically with your changes +- You don't need to manually create the PR - safe-outputs handles it + ## Guidelines ### Technical Tone Standards @@ -569,12 +609,12 @@ on: push A successful consolidation run: - ✅ Analyzes all markdown files in specs/ - ✅ Uses Serena for static analysis -- ✅ Fixes tone issues (marketing → technical) -- ✅ Adds Mermaid diagrams where beneficial -- ✅ Creates consolidated instructions file +- ✅ Fixes tone issues (marketing → technical) **by directly editing files** +- ✅ Adds Mermaid diagrams where beneficial **by directly editing files** +- ✅ Creates/updates consolidated instructions file **using edit tools** - ✅ Stores metadata in cache-memory - ✅ Generates comprehensive report - ✅ Creates discussion with findings -- ✅ Creates PR with changes +- ✅ **Makes actual file changes that will be included in the automatic PR** -Begin the consolidation process now. Use Serena for analysis, adjust tone and formatting, add helpful Mermaid diagrams, consolidate into the instructions file, and report your findings through both a discussion and pull request. +Begin the consolidation process now. Use Serena for analysis, **directly apply changes** to adjust tone and formatting, add helpful Mermaid diagrams, consolidate into the instructions file, and report your findings through both a discussion and pull request.