agents: improve bug-fix-workflow and template rules

.agents/knowledge/index.md

@@ -57,6 +57,10 @@ Read this index at decision points; open only the source the task needs. Format
 
 - **enums-vs-strings** — Model an API enum as Enum (strict, plan-time) or String (forward-compatible): the deliberate trade-off. — [field/enums-vs-strings.md](field/enums-vs-strings.md)
 
+### Template (`template/`)
+
+- **template-modifications** — Safety rules and blast radius precautions for modifying Magic Modules engine templates (mmv1/templates/). — [template/template-modifications.md](template/template-modifications.md)
+
 ### Bugs (`bug/`)
 
 *(No entries yet)*

.agents/knowledge/template/template-modifications.md

@@ -0,0 +1,26 @@
+---
+name: template-modifications
+description: Safety rules and blast radius precautions for modifying Magic Modules engine templates (mmv1/templates/).
+topics: [template]
+task_types: [bug-fix, field-add, new-resource]
+source: authored
+status: draft
+last_verified: 2026-08-06
+---
+
+# Template Modifications & Blast Radius
+
+Templates in `mmv1/templates/terraform/` control code generation globally across hundreds of resources in both `terraform-provider-google` and `terraform-provider-google-beta`. Modifications to these files have provider-wide impact.
+
+## Rules for Template Edits
+
+### 1. Human-in-the-Loop Approval Before Editing Templates
+* **Rule:** If a fix or feature requires altering an engine template rather than product YAML files, halt and obtain explicit user approval before making the change.
+* **Why:** Engine templates alter generated code across multiple unrelated services. A change intended for one resource can unintentionally break or alter dozens of others.
+
+### 2. Mandatory Provider-Wide Generation & Build Verification
+* **Rule:** Whenever modifying any file in `mmv1/templates/`, you must run full downstream generation (`make provider`), full provider compilation (`make build`), and inspect `git diff --stat` across downstream services.
+* **Why:** Running acceptance tests or compiling an individual package only validates that specific service. Broken code or syntax regressions in unrelated services will only be caught by generating and building the entire provider binary.
+
+## Do NOT Use For
+* Resource-specific customizations that can be achieved via standard custom code hooks (`custom_code: ...` in product YAMLs such as `pre_create`, `pre_update`, `encoder`, `flattener`). Only modify core templates when the underlying generation engine itself lacks support for the required pattern.

.agents/skills/operations/create-pr/SKILL.md

@@ -29,7 +29,10 @@ Before creating a branch or opening a PR, verify all of the following rules:
 2. **No Downstream Artifacts in Magic Modules:**
    - Do NOT commit generated downstream provider code (e.g. `$GOPATH/src/github.com/hashicorp/terraform-provider-google`) into `magic-modules`.
 3. **Plan Completeness:** Verify that every file listed in the implementation plan (including any necessary documentation) has been generated and staged.
-4. **Workspace Cleanup:** Run `git status --porcelain` and remove any untracked `.log`, `.test`, or temporary test artifacts across both `magic-modules` and downstream repositories before opening the PR.
+4. **Formatting & Static Checks:**
+   - Run `gofmt -s -w` on all modified or new `.go` files in `mmv1/third_party/terraform/`.
+   - Run `./.agents/skills/utils/run-pre-gen-checks/scripts/run_pre_gen_checks.sh` to ensure YAML linting, Go formatting, template validation, and unit tests pass.
+5. **Workspace Cleanup:** Run `git status --porcelain` and remove any untracked `.log`, `.test`, or temporary test artifacts across both `magic-modules` and downstream repositories before opening the PR.
 
 ---
 
@@ -97,6 +100,7 @@ CONTENT
 ```markdown
 Summary of what changed and why in a few concise sentences.
 
+Modeled after: https://github.com/GoogleCloudPlatform/magic-modules/pull/12344
 Fixes https://github.com/hashicorp/terraform-provider-google/issues/12345
 
 ```release-note:enhancement
@@ -113,11 +117,12 @@ compute: added `foo` field to `google_compute_instance` resource
 > Enclosing triple backticks (` ```release-note:type ``` `) in double quotes causes `zsh`/`bash` to execute `` `release-note:type` `` as a live shell command substitution. The command fails, silently stripping the release note block from the published PR body!
 
 *   **Upstream Target:** Most likely target `--repo GoogleCloudPlatform/magic-modules` (upstream magic modules), and when in doubt ask the user.
+*   **PR Title Length:** Keep the PR title strictly under 60 characters, ideally < 50 characters (format: `<product>: <concise description>`).
 
 Always write the body to a temporary file via a single-quoted HEREDOC (`cat <<'EOF'`) and invoke `gh pr create` with `--body-file`:
 
 ```bash
-PR_TITLE="<product>: <short description>" # e.g. compute: add foo field to google_compute_instance
+PR_TITLE="<product>: <short description>" # e.g. compute: add foo field to google_compute_instance (under 60 chars)
 
 cat <<'EOF' > /tmp/pr_body.txt
 <summary of what changed and why>

.agents/skills/workflows/bug_fix/SKILL.md

@@ -18,9 +18,9 @@ This document outlines the structured 6-step lifecycle for investigating, planni
 *   Execute the `repo-sync` skill (located in `.agents/skills/operations/repo-sync/`). This skill handles checking the sync status and prompting for action if needed to establish a clean sync baseline.
 
 ### 2. Triage & Context Gathering
-*   **External context:** Read the target GitHub issue description, related bug reports, and external API documentation (e.g., REST API references) to understand GCP service behavior and parameters.
+*   **External context:** Read the target issue description, related bug reports, and external API documentation (e.g., REST API references) to understand service behavior and parameters.
 *   **Internal context:** Consult the Knowledge Index (`.agents/knowledge/index.md`) for any relevant topics, patterns, or repository-specific instructions. Then search the codebase to locate where the affected fields, schemas, expanders, or flatteners are defined.
-*   **Historical context:** Trace Git logs, tags, and PRs in downstream provider repositories to identify the lifecycle of the affected code (e.g., when it was introduced, deprecated, or modified).
+*   **Historical context:** Trace Git logs, tags, and past PRs in the repository and downstream provider repositories to identify the lifecycle of the affected code, related fixes, or similar resource implementations (`Modeled after:` / `Based on:`).
 
 ### 3. Remediation Planning (Proposal)
 *   Analyze the triage findings and identify the root cause.
@@ -36,6 +36,7 @@ This document outlines the structured 6-step lifecycle for investigating, planni
 
 ### 4. Implementation & Code Generation (Only if code changes are required)
 *   Apply the approved schema or logic changes in Magic Modules (`mmv1/`).
+*   **Template Modifications:** If the fix requires modifying engine templates (`mmv1/templates/terraform/`), consult the Knowledge Index entry on [Template Modifications & Blast Radius](../../../knowledge/template/template-modifications.md). Obtain explicit user approval before modifying engine templates.
 *   Execute code generation to compile the downstream provider (using the `generate-provider` skill located in `.agents/skills/operations/generate-provider/`).
 
 
@@ -46,14 +47,23 @@ This document outlines the structured 6-step lifecycle for investigating, planni
 
 ### 6. Resolution & Issue Reporting
 *   **Plan Completeness:** Verify that every file listed in the remediation plan (including any necessary documentation) has been generated and staged.
+*   **Pre-PR Quality & Verification Gate:** Before opening a PR or finalizing the branch, run the following verification pipeline:
+    1. **Build Verification:** Run `make build` in downstream provider repository to ensure full compilation passes without syntax errors.
+    2. **Acceptance Test Verification:** Confirm target acceptance tests pass (`PASS`).
+    3. **Go Formatting:** Run `gofmt -s -w` on all modified or newly created `.go` files under `mmv1/third_party/terraform/`.
+    4. **Pre-Gen Static Checks:** Run `./.agents/skills/utils/run-pre-gen-checks/scripts/run_pre_gen_checks.sh` to ensure Go formatting, YAML linting, template validation, and MMv1 unit tests pass.
+    5. **Breaking Change Validation:** Run `./.agents/skills/utils/validate-provider-changes/scripts/validate_provider_changes.sh` if schemas or properties were modified.
 *   **Workspace Cleanup:** Run `git status --porcelain` and remove any untracked `.log`, `.test`, or temporary test artifacts across both repositories before reporting resolution or creating a PR.
-*   If code changes or verification tests were performed, compile these results into a separate verification/test report artifact.
-*   Draft a final, succinct GitHub response containing verified PR/commit links.
-    *   **Succinct Public Communication:** GitHub issue responses should be concise (2–3 sentences preferred): state what changed, why, and refer readers to the PR or documentation for technical deep-dives.
+*   **Artifact Report:** If code changes or verification tests were performed, compile these results into a separate verification/test report artifact.
+*   **PR Creation:** When opening a PR, execute the `create-pr` skill (`.agents/skills/operations/create-pr/`), which governs branch creation, PR title length, release notes, and reference linking (`Modeled after:` / `Based on:`).
+*   **GitHub Response Draft:** Draft a final, succinct public response containing verified PR/commit links.
+    *   **Succinct Public Communication:** Responses should be concise (2–3 sentences preferred): state what changed, why, and refer readers to the PR or documentation for technical deep-dives.
 *   **HIL steering checkpoint:** Present the final response draft and any new verification reports to the user for sign-off and issue closure.
 
 
 ---
 
 ## The Loop
-If verification fails during Step 5, repeat steps 3-5 as needed. Reset to Step 4 (Implementation & Code Generation) after applying any approved fix changes to compile and re-test.
+If verification fails during Step 5, repeat steps 3-5 as needed.
+*   **Scope Expansion Guardrail:** If debugging reveals that resolving the root cause requires expanding scope beyond the approved plan (such as modifying engine templates in `mmv1/templates/` or altering additional fields/resources), do NOT apply changes silently. Loop back to Step 3, update the investigation report artifact, and obtain explicit user approval.
+*   Reset to Step 4 (Implementation & Code Generation) after applying any approved fix changes to compile and re-test.