Add Envoy gateway update skill

Signed-off-by: johnlanni <zty98751@alibaba-inc.com>

.agents/skills/higress-update-envoy-gateway/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: higress-update-envoy-gateway
+description: Update Higress Envoy binary and gateway image dependencies for e2e validation. Use when Codex needs to build Envoy packages from the current Higress branch, upload those packages to higress-group/proxy releases, update Makefile.core.mk ENVOY_PACKAGE_URL_PATTERN and ENVOY_LATEST_IMAGE_TAG, run make build-gateway-local, retag the generated proxy/proxyv2 image as gateway, push the gateway image, or prepare a signed-off PR that lets Higress e2e tests consume a new Envoy build.
+---
+
+# Higress Envoy Gateway Dependency Update
+
+## Core Workflow
+
+Run from the Higress repo root unless a step explicitly says otherwise.
+
+1. Verify context:
+   - Check `git status --short --branch`.
+   - Do not remove unrelated user changes or generated artifacts.
+   - Use `gh` for GitHub release/PR checks and always pass `--repo` for non-current repos.
+
+2. Build Envoy packages from the current branch:
+   ```bash
+   git submodule update --init
+   make build-envoy
+   ```
+   Expected artifacts land in `external/package/`, typically:
+   - `envoy-alpha-<proxy-sha>.tar.gz`
+   - `envoy-symbol-<proxy-sha>.tar.gz`
+   - matching `.sha256` and `.dwp` files
+
+3. Publish Envoy package release in `higress-group/proxy`:
+   - Create a new release tag by incrementing the requested RC/test tag, for example `v2.2.4-rc.2-test-cpp-host`.
+   - Match the reference release asset names, even if local filenames include SHAs:
+     - local `envoy-alpha-<sha>.tar.gz` uploads as `envoy-amd64.tar.gz`
+     - local `envoy-symbol-<sha>.tar.gz` uploads as `envoy-symbol-amd64.tar.gz`
+   - Use temporary renamed copies rather than renaming source artifacts:
+     ```bash
+     cp external/package/envoy-alpha-<sha>.tar.gz /tmp/envoy-amd64.tar.gz
+     cp external/package/envoy-symbol-<sha>.tar.gz /tmp/envoy-symbol-amd64.tar.gz
+     gh release create <release-tag> /tmp/envoy-amd64.tar.gz /tmp/envoy-symbol-amd64.tar.gz \
+       --repo higress-group/proxy --target <target-branch> --title <release-tag> --generate-notes
+     gh release view <release-tag> --repo higress-group/proxy --json tagName,targetCommitish,assets,url
+     ```
+   - If following an existing reference release, inspect it first with `gh release view`.
+
+4. Update Higress Makefile dependencies:
+   - In `Makefile.core.mk`, set:
+     ```make
+     export ENVOY_PACKAGE_URL_PATTERN?=https://github.com/higress-group/proxy/releases/download/<release-tag>/envoy-symbol-ARCH.tar.gz
+     ```
+   - After building and pushing the gateway image, set:
+     ```make
+     ENVOY_LATEST_IMAGE_TAG ?= <gateway-image-tag>
+     ```
+
+5. Build the local gateway image:
+   ```bash
+   make build-gateway-local
+   ```
+   Watch the log to confirm Envoy downloads from the new release URL. The build target may emit an image under a proxy-style repository/name, commonly:
+   - `higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/proxyv2:<tag>`
+
+6. Retag proxy image as gateway:
+   ```bash
+   docker tag higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/proxyv2:<tag> \
+     higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:<tag>
+   docker images --format '{{.Repository}}:{{.Tag}} {{.ID}} {{.CreatedSince}}' \
+     higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway
+   ```
+   Verify the `gateway:<tag>` and `proxyv2:<tag>` image IDs match.
+
+7. Push the gateway image when requested:
+   ```bash
+   docker push higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:<tag>
+   ```
+   Record the pushed digest in the final response.
+
+8. Commit and push Makefile changes:
+   - Commit only intended tracked files. Do not add `plugins/golang-filter/golang-filter_amd64.so` or other build outputs unless explicitly requested.
+   - Use DCO sign-off:
+     ```bash
+     git add Makefile.core.mk
+     git commit -s -m "Update gateway envoy dependencies"
+     git push origin <branch>
+     ```
+   - If DCO fails after a previous unsigned commit:
+     ```bash
+     git commit --amend --no-edit --signoff
+     git push --force-with-lease origin <branch>
+     gh pr checks <pr-number> --repo higress-group/higress
+     ```
+
+## Practical Notes
+
+- `make build-gateway-local` may need Docker daemon access, network access, and write access to repo/submodule state.
+- If sandboxed commands fail with read-only filesystem errors, Docker socket permission errors, or network failures, rerun the same important command with elevated permissions and a concrete justification.
+- The default local gateway tag usually comes from the current Git revision shown in the build log as `TAG=<sha>`.
+- For e2e validation, the point of this workflow is to make `install-dev`, `install-dev-wasmplugin`, and local image update targets use the newly pushed gateway image through `ENVOY_LATEST_IMAGE_TAG`.

.agents/skills/higress-update-envoy-gateway/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Higress Envoy Gateway"
+  short_description: "Update Envoy packages and gateway tag"
+  default_prompt: "Use $higress-update-envoy-gateway to update Higress Makefile Envoy dependencies and build a gateway image for e2e validation."

.agents/skills/issue-spec-apply/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: issue-spec-apply
+description: Implement PROCESS comments for an issue-spec change and keep PR traceability synchronized.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Apply
+
+Use when the user asks for /issue-spec:apply, issue-spec apply, or implementing PROCESS/TASK scopes from an issue-spec change.
+
+## Steps
+
+1. Read proposal/design/implement issue context and list typed comments with issue-spec comment list --json.
+2. Confirm issue-spec auth status --json includes the expected GitHub backend. Local gh-authenticated sessions can use the native gh backend; keep ISSUE_SPEC_TOKEN="$(gh auth token)" only as an older-version or forced-rest compatibility path.
+3. Create or update PROCESS comments with owner agent, scope, dependencies, write ownership, and status.
+4. Split non-trivial work into independent worker PROCESS nodes when file/module ownership does not overlap; execute independent workers in parallel when available.
+5. Add dedicated review PROCESS nodes for non-trivial changes. Review PROCESS nodes should own review scopes such as CLI/API behavior, workflow docs, tests, compatibility, or security-sensitive surfaces.
+6. Link each PROCESS to its TASK comments with issue-spec link.
+7. Implement the code changes for one PROCESS scope at a time, or integrate completed worker outputs by dependency order.
+8. Link every worker and review PROCESS to the PR with issue-spec pr link-process.
+9. Add PR rationale comments on key changed lines with issue-spec pr rationale, each linked to a SPEC comment.
+10. Mark PROCESS comments done only after implementation/review work and focused verification evidence exist.
+
+## Coordinator DAG Execution
+
+1. Build the ready set from PROCESS nodes whose dependencies are done.
+2. Keep immediate blocking work local when the next step depends on it.
+3. Spawn or assign independent worker agents only when their write ownership is disjoint.
+4. Spawn or assign independent review agents only when their review scopes are disjoint.
+5. Integrate completed outputs by dependency order and update PROCESS evidence before marking done.

.agents/skills/issue-spec-archive/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: issue-spec-archive
+description: Create the post-merge durable spec archive PR for an issue-spec change.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Archive
+
+Use when the user asks for /issue-spec:archive, issue-spec archive, or creating the post-merge durable spec PR.
+
+## Steps
+
+1. Confirm the implementation PR is merged.
+2. Create the durable spec PR:
+
+       issue-spec archive durable-spec --repo higress-group/higress --proposal <issue> --capability <capability> --create-pr --branch issue-spec/durable-spec-<capability> --json
+
+3. Review the durable spec PR for long-lived behavior only. Do not copy process records, review findings, or verification logs into durable specs.
+4. After durable spec PR merge, keep proposal/design/implement issues as audit history unless the project policy says to close them.

.agents/skills/issue-spec-github/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: issue-spec-github
+description: Use GitHub CLI for GitHub issues, pull requests, CI runs, and API queries that issue-spec does not wrap.
+license: MIT
+compatibility: Requires GitHub CLI (gh).
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# GitHub CLI
+
+Use the `gh` CLI to interact with GitHub repositories, issues, pull requests, CI, and API endpoints.
+
+## When To Use
+
+- Checking PR status, reviews, mergeability, or CI checks.
+- Creating, viewing, updating, closing, or commenting on GitHub issues.
+- Listing or inspecting pull requests, workflow runs, releases, labels, or repository metadata.
+- Calling GitHub API endpoints with `gh api` when issue-spec does not provide a dedicated command.
+
+## When Not To Use
+
+- Local git operations such as commit, branch, fetch, merge, or push. Use `git` directly.
+- Non-GitHub repositories. Use the matching provider CLI instead.
+- Complex code review across local diffs. Read the repository files directly and use issue-spec review commands for traceable findings.
+
+## Setup
+
+```bash
+gh auth login
+gh auth status
+```
+
+## Common Commands
+
+```bash
+gh issue list --repo owner/repo --state open
+gh issue view 42 --repo owner/repo --json number,title,state,url,body
+gh issue comment 42 --repo owner/repo --body "Comment body"
+
+gh pr list --repo owner/repo
+gh pr view 17 --repo owner/repo --json number,title,state,headRefName,baseRefName,url
+gh pr checks 17 --repo owner/repo
+
+gh run list --repo owner/repo --limit 10
+gh run view <run-id> --repo owner/repo --log-failed
+
+gh api repos/owner/repo/labels --jq '.[].name'
+```
+
+## Notes
+
+- Always pass `--repo owner/repo` when the current directory is not definitely inside the target repository.
+- Use GitHub URLs directly when convenient, for example `gh pr view https://github.com/owner/repo/pull/17`.
+- Prefer structured output with `--json` and `--jq` when another command or agent step consumes the result.
+- issue-spec owns the proposal, design, implement, typed comment, review, verify, and archive workflow state. Use `gh` for adjacent GitHub operations that are outside issue-spec's command surface.

.agents/skills/issue-spec-propose/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: issue-spec-propose
+description: Create or continue proposal, SPEC, QUESTION, design, and TASK artifacts for an issue-spec change.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Propose
+
+Use when the user asks for /issue-spec:propose, issue-spec propose, creating a change proposal, drafting SPEC comments, or preparing design/tasks after questions converge.
+
+## Steps
+
+1. Create the proposal issue:
+
+       issue-spec issue create proposal --repo higress-group/higress --change <change-name> --body-file <proposal.md>
+
+2. If the proposal body needs revision after discussion, update it in place:
+
+       issue-spec issue update --repo higress-group/higress --issue <proposal-issue> --body-file <proposal.md> --summary "<what changed>"
+
+3. Add SPEC comments with issue-spec comment upsert --type SPEC. SPEC comments must use MUST/SHALL and WHEN/THEN scenarios.
+4. Add QUESTION comments for unresolved behavior with issue-spec question create and resolve blocking questions before design.
+5. Create the design issue after SPEC/QUESTION convergence:
+
+       issue-spec issue create design --repo higress-group/higress --change <change-name> --proposal <proposal-issue-or-url> --body-file <design.md>
+
+6. Add TASK comments with issue-spec comment upsert --type TASK and link every TASK to covered SPEC comments with issue-spec link.
+7. Create the implement issue once tasks are ready:
+
+       issue-spec issue create implement --repo higress-group/higress --change <change-name> --proposal <proposal-issue-or-url> --design <design-issue-or-url> --body-file <implement.md>
+
+8. Run issue-spec verify-links and fix missing backlinks before implementation.

.agents/skills/issue-spec-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: issue-spec-review
+description: Review an issue-spec implementation PR, create PR line findings, reply after fixes, and sync REVIEW comments.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Review
+
+Use when the user asks for /issue-spec:review, issue-spec review, or a PR review gate for an issue-spec implementation.
+
+## Steps
+
+1. Run issue-spec review sync --repo higress-group/higress --pr <number> --implement <issue> --id REVIEW-<n> --json to capture current rationale comments, findings, and checks.
+2. For non-trivial PRs, spawn or assign dedicated review agents as review PROCESS owners. Multiple review agents can run in parallel when their review scopes are independent.
+3. Give each review agent a concrete scope and expected output: actionable findings only, severity, file/line, linked SPEC, owner PROCESS, and suggested fix.
+4. Create actionable PR line findings with issue-spec review finding. Use P0/P1 for blockers and P2 for non-blocking follow-up.
+5. Assign every finding to a PROCESS owner. If no findings are found, record that result in REVIEW or VERIFY evidence.
+6. After the worker fixes a finding, reply to the original thread with issue-spec review reply --status resolved.
+7. Re-run review sync. P0/P1 findings must be resolved before final verify/archive.
+
+## Review DAG Policy
+
+1. Every non-trivial PR should have at least one dedicated review PROCESS node before final verify.
+2. Use multiple review agents in parallel when scopes are independent, for example CLI/API behavior, workflow docs, tests, compatibility, or security-sensitive surfaces.
+3. A review agent reports findings only; the coordinator converts actionable line findings into issue-spec review finding comments.
+4. P0/P1 findings block final verify until the owner PROCESS fixes them and issue-spec review reply records the resolution on the original thread.
+5. If a review agent finds no issues, record that result in REVIEW or VERIFY evidence before marking the review PROCESS done.

.agents/skills/issue-spec-verify/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: issue-spec-verify
+description: Run final issue-spec verification across traceability, questions, review findings, PR rationale, PR checks, and durable spec draft.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Verify
+
+Use when the user asks for /issue-spec:verify, issue-spec verify, or final readiness evidence before merge/archive.
+
+## Steps
+
+1. Run focused project tests and record evidence in VERIFY comments.
+2. Run issue-spec verify-links --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --json.
+3. Render a durable spec draft:
+
+       issue-spec archive durable-spec --repo higress-group/higress --proposal <issue> --capability <capability> --output /tmp/<capability>-spec.md --json
+
+4. Run final verify:
+
+       issue-spec verify --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --pr <pr> --durable-spec /tmp/<capability>-spec.md --json
+
+5. Final verify must fail if blocking questions, missing links, missing PROCESS rationale, open P0/P1 findings, failed or pending PR checks, or durable spec omissions exist.

.agents/skills/issue-spec-workflow/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: issue-spec-workflow
+description: Use issue-spec to run an issue-native OpenSpec-style workflow with GitHub issues, typed comments, PR review comments, final verification, and durable spec archive PRs.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Workflow
+
+Use this skill for issue-native OpenSpec work. Active change artifacts live in GitHub issues and issue comments; durable specs are repository files created after implementation merge.
+
+## Start
+
+1. Run issue-spec auth status --json and confirm the active auth source and GitHub backend.
+2. Run issue-spec status --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --json when issues already exist.
+3. For new work, create proposal, design, and implement issues with issue-spec issue create and pass --body-file with concrete markdown content.
+4. When an issue body changes, update it in place with issue-spec issue update --body-file and include --summary for the human-readable audit trail.
+5. Store requirements, tasks, process ownership, review, and verify evidence as typed comments.
+
+## GitHub Backend
+
+- Local agents may rely on native GitHub CLI support: when no ISSUE_SPEC_TOKEN, GH_TOKEN, GITHUB_TOKEN, keyring token, or issue-spec config token is present and gh auth status --active succeeds for the target host, issue-spec auto-selects the gh backend.
+- Explicit env or stored issue-spec tokens keep the rest backend under auto selection. Set ISSUE_SPEC_GITHUB_BACKEND=rest or ISSUE_SPEC_GITHUB_BACKEND=gh only when a workflow needs deterministic backend selection.
+- The gh backend proxies GitHub API operations through gh api and uses gh --hostname for Enterprise hosts. It does not replace local git commands.
+- ISSUE_SPEC_API_URL applies to the rest backend. Forced gh mode should be used only with hosts that gh can address.
+- Use ISSUE_SPEC_TOKEN="$(gh auth token)" only for older issue-spec versions or when deliberately forcing rest while sourcing the token from gh.
+
+## Rules
+
+- Create SPEC comments before design; each SPEC must be testable and include WHEN/THEN scenarios.
+- Do not leave active proposal/design/implement issue bodies as TBD placeholders.
+- Resolve blocking QUESTION comments before design/tasks, or explicitly record accepted assumptions.
+- Link SPEC <-> TASK and TASK <-> PROCESS with issue-spec link.
+- Link every PROCESS to the implementation PR with issue-spec pr link-process.
+- For non-trivial changes, include review PROCESS nodes in the DAG; review agents are scheduled like worker agents and can run in parallel when their review scopes are independent.
+- Small changes may stay coordinator-only, but record the serial execution decision in the implement or VERIFY evidence.
+- Before human review, add PR rationale comments with issue-spec pr rationale for every active PROCESS.
+- Use issue-spec review finding for PR line findings and issue-spec review reply to close the original thread.
+- Run issue-spec review sync and issue-spec verify before declaring ready.
+- After the implementation PR merges, create the separate durable spec PR with issue-spec archive durable-spec --create-pr.
+
+## Coordinator DAG Execution
+
+1. Treat PROCESS comments as DAG nodes with explicit owner, dependencies, write or review scope, PR link, and evidence.
+2. Select ready PROCESS nodes whose dependencies are done and whose scopes do not overlap.
+3. Dispatch independent worker PROCESS nodes in parallel when their file/module ownership is disjoint.
+4. Dispatch independent review PROCESS nodes in parallel for non-trivial PRs after PR rationale exists.
+5. Integrate completed worker outputs by dependency order; route P0/P1 review findings back to the owner PROCESS.
+6. Mark PROCESS nodes done only after their implementation or review evidence is recorded and blocking findings are resolved.

.claude/commands/issue-spec/apply.md

@@ -0,0 +1,31 @@
+---
+name: "Issue Spec: Apply"
+description: "Implement PROCESS comments for an issue-spec change and keep PR traceability synchronized."
+category: "Workflow"
+tags: ["workflow", "issue-spec"]
+---
+
+# Issue Spec Apply
+
+Use when the user asks for /issue-spec:apply, issue-spec apply, or implementing PROCESS/TASK scopes from an issue-spec change.
+
+## Steps
+
+1. Read proposal/design/implement issue context and list typed comments with issue-spec comment list --json.
+2. Confirm issue-spec auth status --json includes the expected GitHub backend. Local gh-authenticated sessions can use the native gh backend; keep ISSUE_SPEC_TOKEN="$(gh auth token)" only as an older-version or forced-rest compatibility path.
+3. Create or update PROCESS comments with owner agent, scope, dependencies, write ownership, and status.
+4. Split non-trivial work into independent worker PROCESS nodes when file/module ownership does not overlap; execute independent workers in parallel when available.
+5. Add dedicated review PROCESS nodes for non-trivial changes. Review PROCESS nodes should own review scopes such as CLI/API behavior, workflow docs, tests, compatibility, or security-sensitive surfaces.
+6. Link each PROCESS to its TASK comments with issue-spec link.
+7. Implement the code changes for one PROCESS scope at a time, or integrate completed worker outputs by dependency order.
+8. Link every worker and review PROCESS to the PR with issue-spec pr link-process.
+9. Add PR rationale comments on key changed lines with issue-spec pr rationale, each linked to a SPEC comment.
+10. Mark PROCESS comments done only after implementation/review work and focused verification evidence exist.
+
+## Coordinator DAG Execution
+
+1. Build the ready set from PROCESS nodes whose dependencies are done.
+2. Keep immediate blocking work local when the next step depends on it.
+3. Spawn or assign independent worker agents only when their write ownership is disjoint.
+4. Spawn or assign independent review agents only when their review scopes are disjoint.
+5. Integrate completed outputs by dependency order and update PROCESS evidence before marking done.

.claude/commands/issue-spec/archive.md

@@ -0,0 +1,20 @@
+---
+name: "Issue Spec: Archive"
+description: "Create the post-merge durable spec archive PR for an issue-spec change."
+category: "Workflow"
+tags: ["workflow", "issue-spec"]
+---
+
+# Issue Spec Archive
+
+Use when the user asks for /issue-spec:archive, issue-spec archive, or creating the post-merge durable spec PR.
+
+## Steps
+
+1. Confirm the implementation PR is merged.
+2. Create the durable spec PR:
+
+       issue-spec archive durable-spec --repo higress-group/higress --proposal <issue> --capability <capability> --create-pr --branch issue-spec/durable-spec-<capability> --json
+
+3. Review the durable spec PR for long-lived behavior only. Do not copy process records, review findings, or verification logs into durable specs.
+4. After durable spec PR merge, keep proposal/design/implement issues as audit history unless the project policy says to close them.

.claude/commands/issue-spec/propose.md

@@ -0,0 +1,33 @@
+---
+name: "Issue Spec: Propose"
+description: "Create or continue proposal, SPEC, QUESTION, design, and TASK artifacts for an issue-spec change."
+category: "Workflow"
+tags: ["workflow", "issue-spec"]
+---
+
+# Issue Spec Propose
+
+Use when the user asks for /issue-spec:propose, issue-spec propose, creating a change proposal, drafting SPEC comments, or preparing design/tasks after questions converge.
+
+## Steps
+
+1. Create the proposal issue:
+
+       issue-spec issue create proposal --repo higress-group/higress --change <change-name> --body-file <proposal.md>
+
+2. If the proposal body needs revision after discussion, update it in place:
+
+       issue-spec issue update --repo higress-group/higress --issue <proposal-issue> --body-file <proposal.md> --summary "<what changed>"
+
+3. Add SPEC comments with issue-spec comment upsert --type SPEC. SPEC comments must use MUST/SHALL and WHEN/THEN scenarios.
+4. Add QUESTION comments for unresolved behavior with issue-spec question create and resolve blocking questions before design.
+5. Create the design issue after SPEC/QUESTION convergence:
+
+       issue-spec issue create design --repo higress-group/higress --change <change-name> --proposal <proposal-issue-or-url> --body-file <design.md>
+
+6. Add TASK comments with issue-spec comment upsert --type TASK and link every TASK to covered SPEC comments with issue-spec link.
+7. Create the implement issue once tasks are ready:
+
+       issue-spec issue create implement --repo higress-group/higress --change <change-name> --proposal <proposal-issue-or-url> --design <design-issue-or-url> --body-file <implement.md>
+
+8. Run issue-spec verify-links and fix missing backlinks before implementation.

.claude/commands/issue-spec/review.md

@@ -0,0 +1,28 @@
+---
+name: "Issue Spec: Review"
+description: "Review an issue-spec implementation PR, create PR line findings, reply after fixes, and sync REVIEW comments."
+category: "Workflow"
+tags: ["workflow", "issue-spec"]
+---
+
+# Issue Spec Review
+
+Use when the user asks for /issue-spec:review, issue-spec review, or a PR review gate for an issue-spec implementation.
+
+## Steps
+
+1. Run issue-spec review sync --repo higress-group/higress --pr <number> --implement <issue> --id REVIEW-<n> --json to capture current rationale comments, findings, and checks.
+2. For non-trivial PRs, spawn or assign dedicated review agents as review PROCESS owners. Multiple review agents can run in parallel when their review scopes are independent.
+3. Give each review agent a concrete scope and expected output: actionable findings only, severity, file/line, linked SPEC, owner PROCESS, and suggested fix.
+4. Create actionable PR line findings with issue-spec review finding. Use P0/P1 for blockers and P2 for non-blocking follow-up.
+5. Assign every finding to a PROCESS owner. If no findings are found, record that result in REVIEW or VERIFY evidence.
+6. After the worker fixes a finding, reply to the original thread with issue-spec review reply --status resolved.
+7. Re-run review sync. P0/P1 findings must be resolved before final verify/archive.
+
+## Review DAG Policy
+
+1. Every non-trivial PR should have at least one dedicated review PROCESS node before final verify.
+2. Use multiple review agents in parallel when scopes are independent, for example CLI/API behavior, workflow docs, tests, compatibility, or security-sensitive surfaces.
+3. A review agent reports findings only; the coordinator converts actionable line findings into issue-spec review finding comments.
+4. P0/P1 findings block final verify until the owner PROCESS fixes them and issue-spec review reply records the resolution on the original thread.
+5. If a review agent finds no issues, record that result in REVIEW or VERIFY evidence before marking the review PROCESS done.

.claude/commands/issue-spec/verify.md

@@ -0,0 +1,24 @@
+---
+name: "Issue Spec: Verify"
+description: "Run final issue-spec verification across traceability, questions, review findings, PR rationale, PR checks, and durable spec draft."
+category: "Workflow"
+tags: ["workflow", "issue-spec"]
+---
+
+# Issue Spec Verify
+
+Use when the user asks for /issue-spec:verify, issue-spec verify, or final readiness evidence before merge/archive.
+
+## Steps
+
+1. Run focused project tests and record evidence in VERIFY comments.
+2. Run issue-spec verify-links --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --json.
+3. Render a durable spec draft:
+
+       issue-spec archive durable-spec --repo higress-group/higress --proposal <issue> --capability <capability> --output /tmp/<capability>-spec.md --json
+
+4. Run final verify:
+
+       issue-spec verify --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --pr <pr> --durable-spec /tmp/<capability>-spec.md --json
+
+5. Final verify must fail if blocking questions, missing links, missing PROCESS rationale, open P0/P1 findings, failed or pending PR checks, or durable spec omissions exist.

.claude/skills/higress-update-envoy-gateway

@@ -0,0 +1 @@
+../../.agents/skills/higress-update-envoy-gateway

.claude/skills/issue-spec-apply/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: issue-spec-apply
+description: Implement PROCESS comments for an issue-spec change and keep PR traceability synchronized.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Apply
+
+Use when the user asks for /issue-spec:apply, issue-spec apply, or implementing PROCESS/TASK scopes from an issue-spec change.
+
+## Steps
+
+1. Read proposal/design/implement issue context and list typed comments with issue-spec comment list --json.
+2. Confirm issue-spec auth status --json includes the expected GitHub backend. Local gh-authenticated sessions can use the native gh backend; keep ISSUE_SPEC_TOKEN="$(gh auth token)" only as an older-version or forced-rest compatibility path.
+3. Create or update PROCESS comments with owner agent, scope, dependencies, write ownership, and status.
+4. Split non-trivial work into independent worker PROCESS nodes when file/module ownership does not overlap; execute independent workers in parallel when available.
+5. Add dedicated review PROCESS nodes for non-trivial changes. Review PROCESS nodes should own review scopes such as CLI/API behavior, workflow docs, tests, compatibility, or security-sensitive surfaces.
+6. Link each PROCESS to its TASK comments with issue-spec link.
+7. Implement the code changes for one PROCESS scope at a time, or integrate completed worker outputs by dependency order.
+8. Link every worker and review PROCESS to the PR with issue-spec pr link-process.
+9. Add PR rationale comments on key changed lines with issue-spec pr rationale, each linked to a SPEC comment.
+10. Mark PROCESS comments done only after implementation/review work and focused verification evidence exist.
+
+## Coordinator DAG Execution
+
+1. Build the ready set from PROCESS nodes whose dependencies are done.
+2. Keep immediate blocking work local when the next step depends on it.
+3. Spawn or assign independent worker agents only when their write ownership is disjoint.
+4. Spawn or assign independent review agents only when their review scopes are disjoint.
+5. Integrate completed outputs by dependency order and update PROCESS evidence before marking done.

.claude/skills/issue-spec-archive/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: issue-spec-archive
+description: Create the post-merge durable spec archive PR for an issue-spec change.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Archive
+
+Use when the user asks for /issue-spec:archive, issue-spec archive, or creating the post-merge durable spec PR.
+
+## Steps
+
+1. Confirm the implementation PR is merged.
+2. Create the durable spec PR:
+
+       issue-spec archive durable-spec --repo higress-group/higress --proposal <issue> --capability <capability> --create-pr --branch issue-spec/durable-spec-<capability> --json
+
+3. Review the durable spec PR for long-lived behavior only. Do not copy process records, review findings, or verification logs into durable specs.
+4. After durable spec PR merge, keep proposal/design/implement issues as audit history unless the project policy says to close them.

.claude/skills/issue-spec-github/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: issue-spec-github
+description: Use GitHub CLI for GitHub issues, pull requests, CI runs, and API queries that issue-spec does not wrap.
+license: MIT
+compatibility: Requires GitHub CLI (gh).
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# GitHub CLI
+
+Use the `gh` CLI to interact with GitHub repositories, issues, pull requests, CI, and API endpoints.
+
+## When To Use
+
+- Checking PR status, reviews, mergeability, or CI checks.
+- Creating, viewing, updating, closing, or commenting on GitHub issues.
+- Listing or inspecting pull requests, workflow runs, releases, labels, or repository metadata.
+- Calling GitHub API endpoints with `gh api` when issue-spec does not provide a dedicated command.
+
+## When Not To Use
+
+- Local git operations such as commit, branch, fetch, merge, or push. Use `git` directly.
+- Non-GitHub repositories. Use the matching provider CLI instead.
+- Complex code review across local diffs. Read the repository files directly and use issue-spec review commands for traceable findings.
+
+## Setup
+
+```bash
+gh auth login
+gh auth status
+```
+
+## Common Commands
+
+```bash
+gh issue list --repo owner/repo --state open
+gh issue view 42 --repo owner/repo --json number,title,state,url,body
+gh issue comment 42 --repo owner/repo --body "Comment body"
+
+gh pr list --repo owner/repo
+gh pr view 17 --repo owner/repo --json number,title,state,headRefName,baseRefName,url
+gh pr checks 17 --repo owner/repo
+
+gh run list --repo owner/repo --limit 10
+gh run view <run-id> --repo owner/repo --log-failed
+
+gh api repos/owner/repo/labels --jq '.[].name'
+```
+
+## Notes
+
+- Always pass `--repo owner/repo` when the current directory is not definitely inside the target repository.
+- Use GitHub URLs directly when convenient, for example `gh pr view https://github.com/owner/repo/pull/17`.
+- Prefer structured output with `--json` and `--jq` when another command or agent step consumes the result.
+- issue-spec owns the proposal, design, implement, typed comment, review, verify, and archive workflow state. Use `gh` for adjacent GitHub operations that are outside issue-spec's command surface.

.claude/skills/issue-spec-propose/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: issue-spec-propose
+description: Create or continue proposal, SPEC, QUESTION, design, and TASK artifacts for an issue-spec change.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Propose
+
+Use when the user asks for /issue-spec:propose, issue-spec propose, creating a change proposal, drafting SPEC comments, or preparing design/tasks after questions converge.
+
+## Steps
+
+1. Create the proposal issue:
+
+       issue-spec issue create proposal --repo higress-group/higress --change <change-name> --body-file <proposal.md>
+
+2. If the proposal body needs revision after discussion, update it in place:
+
+       issue-spec issue update --repo higress-group/higress --issue <proposal-issue> --body-file <proposal.md> --summary "<what changed>"
+
+3. Add SPEC comments with issue-spec comment upsert --type SPEC. SPEC comments must use MUST/SHALL and WHEN/THEN scenarios.
+4. Add QUESTION comments for unresolved behavior with issue-spec question create and resolve blocking questions before design.
+5. Create the design issue after SPEC/QUESTION convergence:
+
+       issue-spec issue create design --repo higress-group/higress --change <change-name> --proposal <proposal-issue-or-url> --body-file <design.md>
+
+6. Add TASK comments with issue-spec comment upsert --type TASK and link every TASK to covered SPEC comments with issue-spec link.
+7. Create the implement issue once tasks are ready:
+
+       issue-spec issue create implement --repo higress-group/higress --change <change-name> --proposal <proposal-issue-or-url> --design <design-issue-or-url> --body-file <implement.md>
+
+8. Run issue-spec verify-links and fix missing backlinks before implementation.

.claude/skills/issue-spec-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: issue-spec-review
+description: Review an issue-spec implementation PR, create PR line findings, reply after fixes, and sync REVIEW comments.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Review
+
+Use when the user asks for /issue-spec:review, issue-spec review, or a PR review gate for an issue-spec implementation.
+
+## Steps
+
+1. Run issue-spec review sync --repo higress-group/higress --pr <number> --implement <issue> --id REVIEW-<n> --json to capture current rationale comments, findings, and checks.
+2. For non-trivial PRs, spawn or assign dedicated review agents as review PROCESS owners. Multiple review agents can run in parallel when their review scopes are independent.
+3. Give each review agent a concrete scope and expected output: actionable findings only, severity, file/line, linked SPEC, owner PROCESS, and suggested fix.
+4. Create actionable PR line findings with issue-spec review finding. Use P0/P1 for blockers and P2 for non-blocking follow-up.
+5. Assign every finding to a PROCESS owner. If no findings are found, record that result in REVIEW or VERIFY evidence.
+6. After the worker fixes a finding, reply to the original thread with issue-spec review reply --status resolved.
+7. Re-run review sync. P0/P1 findings must be resolved before final verify/archive.
+
+## Review DAG Policy
+
+1. Every non-trivial PR should have at least one dedicated review PROCESS node before final verify.
+2. Use multiple review agents in parallel when scopes are independent, for example CLI/API behavior, workflow docs, tests, compatibility, or security-sensitive surfaces.
+3. A review agent reports findings only; the coordinator converts actionable line findings into issue-spec review finding comments.
+4. P0/P1 findings block final verify until the owner PROCESS fixes them and issue-spec review reply records the resolution on the original thread.
+5. If a review agent finds no issues, record that result in REVIEW or VERIFY evidence before marking the review PROCESS done.

.claude/skills/issue-spec-verify/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: issue-spec-verify
+description: Run final issue-spec verification across traceability, questions, review findings, PR rationale, PR checks, and durable spec draft.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Verify
+
+Use when the user asks for /issue-spec:verify, issue-spec verify, or final readiness evidence before merge/archive.
+
+## Steps
+
+1. Run focused project tests and record evidence in VERIFY comments.
+2. Run issue-spec verify-links --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --json.
+3. Render a durable spec draft:
+
+       issue-spec archive durable-spec --repo higress-group/higress --proposal <issue> --capability <capability> --output /tmp/<capability>-spec.md --json
+
+4. Run final verify:
+
+       issue-spec verify --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --pr <pr> --durable-spec /tmp/<capability>-spec.md --json
+
+5. Final verify must fail if blocking questions, missing links, missing PROCESS rationale, open P0/P1 findings, failed or pending PR checks, or durable spec omissions exist.

.claude/skills/issue-spec-workflow/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: issue-spec-workflow
+description: Use issue-spec to run an issue-native OpenSpec-style workflow with GitHub issues, typed comments, PR review comments, final verification, and durable spec archive PRs.
+license: MIT
+compatibility: Requires issue-spec CLI.
+metadata:
+  author: issue-spec
+  version: "1.0"
+  generatedBy: "issue-spec"
+---
+
+# Issue Spec Workflow
+
+Use this skill for issue-native OpenSpec work. Active change artifacts live in GitHub issues and issue comments; durable specs are repository files created after implementation merge.
+
+## Start
+
+1. Run issue-spec auth status --json and confirm the active auth source and GitHub backend.
+2. Run issue-spec status --repo higress-group/higress --proposal <issue> --design <issue> --implement <issue> --json when issues already exist.
+3. For new work, create proposal, design, and implement issues with issue-spec issue create and pass --body-file with concrete markdown content.
+4. When an issue body changes, update it in place with issue-spec issue update --body-file and include --summary for the human-readable audit trail.
+5. Store requirements, tasks, process ownership, review, and verify evidence as typed comments.
+
+## GitHub Backend
+
+- Local agents may rely on native GitHub CLI support: when no ISSUE_SPEC_TOKEN, GH_TOKEN, GITHUB_TOKEN, keyring token, or issue-spec config token is present and gh auth status --active succeeds for the target host, issue-spec auto-selects the gh backend.
+- Explicit env or stored issue-spec tokens keep the rest backend under auto selection. Set ISSUE_SPEC_GITHUB_BACKEND=rest or ISSUE_SPEC_GITHUB_BACKEND=gh only when a workflow needs deterministic backend selection.
+- The gh backend proxies GitHub API operations through gh api and uses gh --hostname for Enterprise hosts. It does not replace local git commands.
+- ISSUE_SPEC_API_URL applies to the rest backend. Forced gh mode should be used only with hosts that gh can address.
+- Use ISSUE_SPEC_TOKEN="$(gh auth token)" only for older issue-spec versions or when deliberately forcing rest while sourcing the token from gh.
+
+## Rules
+
+- Create SPEC comments before design; each SPEC must be testable and include WHEN/THEN scenarios.
+- Do not leave active proposal/design/implement issue bodies as TBD placeholders.
+- Resolve blocking QUESTION comments before design/tasks, or explicitly record accepted assumptions.
+- Link SPEC <-> TASK and TASK <-> PROCESS with issue-spec link.
+- Link every PROCESS to the implementation PR with issue-spec pr link-process.
+- For non-trivial changes, include review PROCESS nodes in the DAG; review agents are scheduled like worker agents and can run in parallel when their review scopes are independent.
+- Small changes may stay coordinator-only, but record the serial execution decision in the implement or VERIFY evidence.
+- Before human review, add PR rationale comments with issue-spec pr rationale for every active PROCESS.
+- Use issue-spec review finding for PR line findings and issue-spec review reply to close the original thread.
+- Run issue-spec review sync and issue-spec verify before declaring ready.
+- After the implementation PR merges, create the separate durable spec PR with issue-spec archive durable-spec --create-pr.
+
+## Coordinator DAG Execution
+
+1. Treat PROCESS comments as DAG nodes with explicit owner, dependencies, write or review scope, PR link, and evidence.
+2. Select ready PROCESS nodes whose dependencies are done and whose scopes do not overlap.
+3. Dispatch independent worker PROCESS nodes in parallel when their file/module ownership is disjoint.
+4. Dispatch independent review PROCESS nodes in parallel for non-trivial PRs after PR rationale exists.
+5. Integrate completed worker outputs by dependency order; route P0/P1 review findings back to the owner PROCESS.
+6. Mark PROCESS nodes done only after their implementation or review evidence is recorded and blocking findings are resolved.

.issue-spec/config.json

@@ -0,0 +1,4 @@
+{
+  "hostname": "github.com",
+  "repo": "higress-group/higress"
+}

.licenserc.yaml

@@ -36,7 +36,9 @@ header:
     - 'pkg/ingress/kube/gateway/istio/testdata'
     - 'release-notes/**'
     - '.cursor/**'
-    - '.claude/**'    
+    - '.claude/**'
+    - '.agents/**'
+    - '.issue-spec/**'
 
   comment: on-failure
 dependency:

AGENTS.md

@@ -0,0 +1,156 @@
+# AGENTS.md
+
+Guidance for AI agents working in this repository.
+
+Higress is a cloud-native API gateway built on Istio and Envoy. The control
+plane extends Istio/pilot (Go); the data plane is Envoy extended with WASM
+plugins (Go/Rust/C++/AssemblyScript) and a Go-based `golang-filter`. It supports
+Ingress/Gateway API and ships a rich plugin ecosystem (including AI gateway
+plugins).
+
+## Repository layout
+
+Top-level directories (all paths relative to repo root):
+
+- `cmd/higress/` — main entrypoint (`main.go`) for the Higress controller binary.
+- `pkg/` — core Go control-plane packages: `bootstrap/`, `cert/`, `cmd/`,
+  `common/`, `config/`, `ingress/` (Ingress/Gateway config translation),
+  `kube/`.
+- `api/` — protobuf/CRD API definitions; Higress CRDs live in
+  `api/extensions/v1alpha1` (e.g. the `WasmPlugin` type). Generated with
+  `make gen-api` / `make gen-client` (see `api/gen.sh`, `buf.*`).
+- `client/` — generated Go clientset for Higress CRDs.
+- `istio/` — git submodules of higress-group forks of Istio (`api`, `istio`,
+  `client-go`, `pkg`, `proxy`); see `.gitmodules`. Pulled via `make submodule`
+  (part of `prebuild`).
+- `envoy/` — Envoy + `go-control-plane` submodules (higress-group forks).
+- `external/` — vendored/external mirror dirs used during build (istio, envoy,
+  proxy, etc.).
+- `plugins/` — all data-plane plugins (see "Plugins" below).
+- `registry/` — service-discovery registry integrations (nacos, consul, eureka,
+  zookeeper, direct, mcp, ...).
+- `hgctl/` — the `hgctl` CLI (separate Go module) for managing Higress.
+- `helm/` — Helm charts: `helm/core` (the dev/install chart) and `helm/higress`.
+- `test/` — `test/e2e/` (conformance/e2e, see "Build & test") and
+  `test/gateway/`.
+- `tools/` — build/CI scripting: `tools/hack/` (build scripts), `tools/bin/`,
+  `tools/linter/`, `*.mk`.
+- `samples/` — example manifests (gateway-api, hello-world, wasmplugin, ...).
+- `docker/`, `docs/`, `release-notes/` — packaging, docs, and release notes.
+- `Makefile` — istio common-files wrapper (supports `BUILD_WITH_CONTAINER`);
+  real targets live in `Makefile.core.mk` (+ `Makefile.overrides.mk`).
+
+## Plugins
+
+All plugins live under `plugins/`. See `plugins/README.md` for the contributor
+overview. Prebuilt plugin images are published to
+`higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins`.
+
+### plugins/wasm-go/ (primary WASM plugin framework, Go)
+
+- `extensions/<name>/` — one directory per plugin (~59 plugins, many `ai-*`).
+  Each plugin is its own Go module: `main.go`, `go.mod`/`go.sum`, `VERSION`,
+  `README.md`(+`README_EN.md`), often `config/`, `util/`, `main_test.go`.
+  Optional `.buildrc` sets `EXTRA_TAGS`; optional `prepare.sh`/`prepare.sh`.
+  `plugin.wasm` is a build artifact and is **not** committed.
+- Shared SDK: plugins depend on external modules
+  `github.com/higress-group/wasm-go` and
+  `github.com/higress-group/proxy-wasm-go-sdk` (NOT an in-repo SDK dir).
+  In-repo, `plugins/wasm-go/pkg/mcp/` provides MCP helpers and
+  `plugins/wasm-go/mcp-servers/` holds MCP server plugins.
+- `examples/` — minimal reference plugins (custom-log, custom-span-attribute,
+  test-foreign-function).
+- Build: `plugins/wasm-go/Makefile`. `PLUGIN_NAME=<name> make build` builds a
+  wasm file (output to `extensions/<name>/plugin.wasm`) + image via
+  `Dockerfile`/`DockerfileBuilder` (uses a `wasm-go-builder` image, Go 1.24,
+  TinyGo optional). `make build-push` pushes the image; `make local-build`
+  builds locally with `GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`.
+- Conventions: `VERSION` is the image tag; the CI/e2e batch builder
+  (`tools/hack/build-wasm-plugins.sh`) only compiles a wasm-go plugin whose
+  `VERSION` ends in `-alpha` (see the section at the bottom of this file).
+
+### plugins/wasm-rust/ (Rust WASM plugins)
+
+- Workspace-style: root `Cargo.toml`/`Cargo.lock`, shared `src/`,
+  `extensions/<name>/` per plugin (e.g. `ai-data-masking`, `ai-intent`,
+  `request-block`, `say-hello`, `demo-wasm`), `example/`.
+- Build via `plugins/wasm-rust/Makefile` (`PLUGIN_NAME=<name> make build`, plus
+  `lint`/`test`); the batch builder runs it when `PLUGIN_TYPE=RUST`.
+
+### plugins/wasm-cpp/ (C++ WASM plugins, Bazel)
+
+- Bazel project: `WORKSPACE`, `BUILD`, `bazel/`, `common/`, `scripts/`,
+  `extensions/<name>/` (e.g. `basic_auth`, `jwt_auth`, `key_rate_limit`,
+  `model_router`, ...). Build via `plugins/wasm-cpp/Makefile`
+  (`PLUGIN_NAME=<name> make build`), invoked with `PLUGIN_TYPE=CPP`.
+
+### plugins/wasm-assemblyscript/ (AssemblyScript WASM plugins)
+
+- Node/AssemblyScript project: `asconfig.json`, `package.json`, `assembly/`,
+  `extensions/`.
+
+### plugins/golang-filter/ (Envoy Go HTTP filter, NOT WASM)
+
+- A native Envoy Golang HTTP filter (`main.go`, `mcp-server/`, `mcp-session/`);
+  compiled as a shared object (`.so`) independent of Envoy — no Envoy rebuild
+  needed. Requires Higress >= 2.1.0. Plugins register in `main.go`'s `init()`
+  via `RegisterHttpFilterFactoryAndConfigParser`. See
+  `plugins/golang-filter/README.md`.
+- Build: `plugins/golang-filter/Makefile` (docker build, outputs
+  `golang-filter_<arch>.so`). Wired into the gateway image build via
+  `Makefile.core.mk` targets `build-golang-filter[-amd64|-arm64]`.
+
+### How plugins are loaded
+
+`WasmPlugin` CRDs (`extensions.higress.io/v1alpha1`) reference a plugin by
+`url:` — either `oci://.../plugins/<name>:<version>` (image) or
+`file:///opt/plugins/.../plugin.wasm` (local mount used in e2e). The dev install
+`make install-dev-wasmplugin` sets Helm `global.volumeWasmPlugins=true` to mount
+locally built wasm files into the gateway.
+
+## Build & test
+
+Run targets from the repo root; `Makefile` delegates to `Makefile.core.mk`.
+Common ones:
+
+- `make build` / `make build-linux` — build the Higress controller binary
+  (`prebuild` first fetches submodules).
+- `make build-hgctl` — build the `hgctl` CLI.
+- `make build-gateway` / `make build-istio` / `make build-envoy` — data-plane
+  and control-plane images (gateway pulls in the golang-filter).
+- `make build-wasmplugins` — runs `tools/hack/build-wasm-plugins.sh` to batch
+  build WASM plugins (respects `PLUGIN_TYPE` / `PLUGIN_NAME`; Go plugins require
+  a `-alpha` VERSION).
+- `make gen-api` / `make gen-client` — regenerate API/client code.
+
+### Conformance / e2e tests (`test/e2e/`)
+
+- Entrypoint `test/e2e/e2e_test.go`, run with build tag `conformance` and
+  `--test-area` / `--execute-tests` flags.
+- Cases live in `test/e2e/conformance/tests/` as **paired `<name>.go` +
+  `<name>.yaml`** files (~68 cases; WASM cases are prefixed by language, e.g.
+  `go-wasm-*`, `cpp-wasm-*`). Support code: `conformance/base/`,
+  `conformance/utils/`, `conformance/embed.go`.
+- Key Make targets (each spins up a kind cluster):
+  - `make higress-conformance-test` — Ingress/Gateway conformance.
+  - `make higress-wasmplugin-test` — WASM plugin e2e (uses
+    `install-dev-wasmplugin`, which builds plugins and mounts them).
+  - `*-prepare` / `*-skip-docker-build` / `*-clean` variants exist for
+    iterating; `run-higress-e2e-test[-wasmplugin]` runs `go test` against an
+    already-prepared cluster (filter with `TEST_SHORTNAME`).
+- For the specifics of authoring a wasm-go e2e test, see the section below.
+
+## Writing e2e conformance tests with wasm-go plugins
+
+When adding an e2e conformance test that ships its own wasm-go plugin under
+`plugins/wasm-go/extensions/<name>/`:
+
+- The plugin's `VERSION` file **must end in `-alpha`** (e.g. `1.0.0-alpha`).
+  CI's `tools/hack/build-wasm-plugins.sh` only compiles a wasm-go plugin when
+  its version ends in `-alpha`; otherwise it silently skips it.
+- `plugin.wasm` is a build artifact and is **not** committed. If the plugin
+  isn't built, the `file:///opt/plugins/.../plugin.wasm` URL in the test's
+  `WasmPlugin` manifest resolves to a missing file, envoy rejects the wasm
+  config and fails closed, and every request on that route returns HTTP 500.
+  Locally this can be masked because a previously built `plugin.wasm` still
+  exists on disk — so a test can pass locally yet 500 in CI.

Makefile.core.mk

@@ -205,7 +205,7 @@ install: pre-install
 	helm install higress helm/higress -n higress-system --create-namespace --set 'global.local=true'
 
 HIGRESS_LATEST_IMAGE_TAG ?= latest
-ENVOY_LATEST_IMAGE_TAG ?= fcc50202f47e27f6b8391a4bd9bbc0a9127d89d7
+ENVOY_LATEST_IMAGE_TAG ?= 91244c578aef498af93cacb2cf353f3878b92fc4
 ISTIO_LATEST_IMAGE_TAG ?= de2c9628294f51b13c4a70b3a862b4372890797a
 
 install-dev: pre-install

plugins/wasm-go/extensions/test-redis-inject-spin/VERSION

@@ -0,0 +1 @@
+1.0.0-alpha

plugins/wasm-go/extensions/test-redis-inject-spin/go.mod

@@ -0,0 +1,20 @@
+module github.com/alibaba/higress/plugins/wasm-go/extensions/test-redis-inject-spin
+
+go 1.24.1
+
+toolchain go1.24.4
+
+require (
+	github.com/higress-group/proxy-wasm-go-sdk v0.0.0-20251103120604-77e9cce339d2
+	github.com/higress-group/wasm-go v1.0.10-0.20260120033417-1c84f010156d
+	github.com/tidwall/gjson v1.18.0
+	github.com/tidwall/resp v0.1.1
+	google.golang.org/protobuf v1.36.6
+)
+
+require (
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.1 // indirect
+	github.com/tidwall/sjson v1.2.5 // indirect
+)

plugins/wasm-go/extensions/test-redis-inject-spin/go.sum

@@ -0,0 +1,32 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/higress-group/proxy-wasm-go-sdk v0.0.0-20251103120604-77e9cce339d2 h1:NY33OrWCJJ+DFiLc+lsBY4Ywor2Ik61ssk6qkGF8Ypo=
+github.com/higress-group/proxy-wasm-go-sdk v0.0.0-20251103120604-77e9cce339d2/go.mod h1:tRI2LfMudSkKHhyv1uex3BWzcice2s/l8Ah8axporfA=
+github.com/higress-group/wasm-go v1.0.10-0.20260120033417-1c84f010156d h1:LgYbzEBtg0+LEqoebQeMVgAB6H5SgqG+KN+gBhNfKbM=
+github.com/higress-group/wasm-go v1.0.10-0.20260120033417-1c84f010156d/go.mod h1:uKVYICbRaxTlKqdm8E0dpjbysxM8uCPb9LV26hF3Km8=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
+github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/resp v0.1.1 h1:Ly20wkhqKTmDUPlyM1S7pWo5kk0tDu8OoC/vFArXmwE=
+github.com/tidwall/resp v0.1.1/go.mod h1:3/FrruOBAxPTPtundW0VXgmsQ4ZBA0Aw714lVYgwFa0=
+github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
+github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.36.6 h1:z1NpPI8ku2WgiWnf+t9wTPsn6eP1L7ksHUlkfLvd9xY=
+google.golang.org/protobuf v1.36.6/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

plugins/wasm-go/extensions/test-redis-inject-spin/main.go

@@ -0,0 +1,119 @@
+// Repro plugin for higress issue #4034: worker CPU spin in
+// WasmBase::doAfterVmCallActions when a deferred async callback synchronously
+// calls injectEncodedDataToFilterChain (nesting SaveRestoreContext) so that the
+// after-vm-call action re-queues itself forever.
+//
+// Repro shape (dead-Redis only, self-contained — no external HTTP dependency):
+//   1. In the response-header phase, pause the response.
+//   2. Fire N Redis commands against an UNREACHABLE redis cluster.
+//   3. Each failure callback (onRedisCallFailure) synchronously calls the
+//      inject_encoded_data_to_filter_chain foreign function. Because sibling
+//      failure callbacks are still queued as after-vm-call actions, the nested
+//      SaveRestoreContext leaves current_context_ != nullptr and the deferred
+//      action re-queues itself -> CPU spin on the pre-fix host.
+//
+// With the Layer A drain-to-local fix in place, the drain terminates over a
+// snapshot and worker CPU stays bounded.
+package main
+
+import (
+	"github.com/higress-group/proxy-wasm-go-sdk/proxywasm"
+	"github.com/higress-group/proxy-wasm-go-sdk/proxywasm/types"
+	"github.com/higress-group/wasm-go/pkg/log"
+	pb "github.com/higress-group/wasm-go/pkg/protos"
+	"github.com/higress-group/wasm-go/pkg/wrapper"
+	"github.com/tidwall/gjson"
+	"github.com/tidwall/resp"
+	"google.golang.org/protobuf/proto"
+)
+
+func main() {}
+
+type Config struct {
+	redisClient *wrapper.RedisClusterClient[wrapper.FQDNCluster]
+	redisKey    string
+	injectBody  string
+	injectCount int
+}
+
+func init() {
+	wrapper.SetCtx(
+		"test-redis-inject-spin",
+		wrapper.ParseConfig(parseConfig),
+		wrapper.ProcessResponseHeaders(onHttpResponseHeaders),
+	)
+}
+
+func parseConfig(json gjson.Result, config *Config) error {
+	serviceName := json.Get("service_name").String()
+	if serviceName == "" {
+		serviceName = "dead-redis.dead-redis.svc.cluster.local"
+	}
+	servicePort := json.Get("service_port").Int()
+	if servicePort == 0 {
+		servicePort = 6379
+	}
+	config.redisKey = json.Get("redis_key").String()
+	if config.redisKey == "" {
+		config.redisKey = "higress-4034-key"
+	}
+	config.injectBody = json.Get("inject_body").String()
+	if config.injectBody == "" {
+		config.injectBody = "injected-by-4034-repro\n"
+	}
+	config.injectCount = int(json.Get("inject_count").Int())
+	if config.injectCount == 0 {
+		config.injectCount = 16
+	}
+
+	config.redisClient = wrapper.NewRedisClusterClient(wrapper.FQDNCluster{
+		FQDN: serviceName,
+		Port: servicePort,
+	})
+	// Init never returns error for an unreachable host; commands' callbacks will
+	// fire with an error value, which is exactly the #4034 trigger path.
+	return config.redisClient.Init("", "", 1000)
+}
+
+func onHttpResponseHeaders(ctx wrapper.HttpContext, config Config) types.Action {
+	proxywasm.RemoveHttpResponseHeader("content-length")
+	ctx.DontReadResponseBody()
+
+	inject := func() {
+		d := &pb.InjectEncodedDataToFilterChainArguments{
+			Body:      config.injectBody,
+			Endstream: true,
+		}
+		s, err := proto.Marshal(d)
+		if err != nil {
+			log.Errorf("marshal inject args failed: %+v", err)
+			return
+		}
+		if _, err := proxywasm.CallForeignFunction("inject_encoded_data_to_filter_chain_on_header", s); err != nil {
+			log.Errorf("call inject_encoded_data_to_filter_chain_on_header failed: %+v", err)
+		}
+	}
+
+	scheduled := 0
+	for i := 0; i < config.injectCount; i++ {
+		err := config.redisClient.Get(config.redisKey, func(response resp.Value) {
+			// Fires on redis-unreachable failure; synchronously inject to nest
+			// SaveRestoreContext while sibling callbacks are still queued.
+			if response.Error() != nil {
+				log.Debugf("redis get failed as expected: %v", response.Error())
+			}
+			inject()
+		})
+		if err != nil {
+			log.Errorf("redis Get dispatch failed: %+v", err)
+			continue
+		}
+		scheduled++
+	}
+
+	if scheduled == 0 {
+		// Nothing dispatched (e.g. cluster missing) — don't hang the response.
+		return types.ActionContinue
+	}
+	return types.ActionPause
+}

plugins/wasm-go/extensions/transformer/main.go

@@ -39,6 +39,7 @@ func init() {
 		wrapper.ProcessRequestBodyBy(onHttpRequestBody),
 		wrapper.ProcessResponseHeadersBy(onHttpResponseHeaders),
 		wrapper.ProcessResponseBodyBy(onHttpResponseBody),
+		wrapper.WithRebuildMaxMemBytes[TransformerConfig](200*1024*1024),
 	)
 }
 
@@ -343,11 +344,12 @@ func onHttpRequestHeaders(ctx wrapper.HttpContext, config TransformerConfig, log
 	isValidRequestContent := isValidRequestContentType(contentType)
 	isBodyChange := config.reqTrans.IsBodyChange()
 	needBodyMapSource := config.reqTrans.NeedBodyMapSource()
+	hasRequestBody := ctx.HasRequestBody()
 
-	log.Debugf("contentType:%s, isValidRequestContent:%v, isBodyChange:%v, needBodyMapSource:%v",
-		contentType, isValidRequestContent, isBodyChange, needBodyMapSource)
+	log.Debugf("contentType:%s, isValidRequestContent:%v, isBodyChange:%v, needBodyMapSource:%v, hasRequestBody:%v",
+		contentType, isValidRequestContent, isBodyChange, needBodyMapSource, hasRequestBody)
 
-	if isBodyChange && isValidRequestContent {
+	if isBodyChange && isValidRequestContent && hasRequestBody {
 		delete(hs, "content-length")
 	}
 
@@ -361,7 +363,7 @@ func onHttpRequestHeaders(ctx wrapper.HttpContext, config TransformerConfig, log
 	ctx.SetContext("headers", hs)
 	ctx.SetContext("querys", qs)
 
-	if !isValidRequestContent || (!isBodyChange && !needBodyMapSource) {
+	if !hasRequestBody || !isValidRequestContent || (!isBodyChange && !needBodyMapSource) {
 		ctx.DontReadRequestBody()
 	} else if needBodyMapSource {
 		// we need do transform during body phase

plugins/wasm-go/extensions/transformer/main_test.go

@@ -424,6 +424,43 @@ func TestRequest_MapFromBody_DelaysHeaderTransform(t *testing.T) {
 	})
 }
 
+func TestRequest_MapFromBody_NoRequestBodyDoesNotPause(t *testing.T) {
+	test.RunTest(t, func(t *testing.T) {
+		host, status := test.NewTestHost(configJSON(map[string]any{
+			"reqRules": []map[string]any{
+				{
+					"operate":   "map",
+					"mapSource": "body",
+					"headers": []map[string]any{
+						{"fromKey": "user.id", "toKey": "X-User-Id"},
+					},
+				},
+				{
+					"operate": "add",
+					"headers": []map[string]any{
+						{"key": "X-Static", "value": "ok"},
+					},
+				},
+			},
+		}))
+		defer host.Reset()
+		require.Equal(t, types.OnPluginStartStatusOK, status)
+
+		action := host.CallOnHttpRequestHeaders([][2]string{
+			{":authority", "test.com"},
+			{":path", "/p"},
+			{":method", "POST"},
+			{"content-type", "application/json"},
+		}, test.WithEndOfStream(true))
+		require.Equal(t, types.ActionContinue, action, "request without body must not wait for body callback")
+
+		got := headersToMap(host.GetRequestHeaders())
+		require.Equal(t, []string{"ok"}, got["x-static"])
+		require.NotContains(t, got, "x-user-id")
+		host.CompleteHttp()
+	})
+}
+
 // --- regex template ---
 
 func TestRequest_Headers_AddWithHostPattern(t *testing.T) {

test/e2e/conformance/tests/go-wasm-test-redis-inject-spin.go

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tests
+
+import (
+	"testing"
+
+	"github.com/alibaba/higress/v2/test/e2e/conformance/utils/http"
+	"github.com/alibaba/higress/v2/test/e2e/conformance/utils/suite"
+)
+
+func init() {
+	Register(WasmPluginsRedisInjectSpin)
+}
+
+// WasmPluginsRedisInjectSpin reproduces issue #4034: a deferred async Redis
+// failure callback synchronously calls injectEncodedDataToFilterChain, which
+// (pre-fix) makes WasmBase::doAfterVmCallActions re-queue an action forever and
+// spins a worker at 100% CPU. Redis is pointed at an unroutable endpoint so the
+// failure callbacks fire under concurrency.
+//
+// With the Layer A drain-to-local fix in place, the after-vm-call drain
+// terminates over a snapshot, deferred callbacks complete, and the gateway keeps
+// serving requests. The test asserts the plugin route stays responsive (200)
+// rather than hanging — a spinning worker would fail this via timeout.
+var WasmPluginsRedisInjectSpin = suite.ConformanceTest{
+	ShortName:   "WasmPluginsRedisInjectSpin",
+	Description: "Reproduce #4034: redis-failure callback + inject must not spin the worker; gateway stays responsive.",
+	Manifests:   []string{"tests/go-wasm-test-redis-inject-spin.yaml"},
+	Features:    []suite.SupportedFeature{suite.WASMGoConformanceFeature},
+	Test: func(t *testing.T, suite *suite.ConformanceTestSuite) {
+		testcases := []http.Assertion{
+			{
+				Meta: http.AssertionMeta{
+					TargetBackend:   "infra-backend-v1",
+					TargetNamespace: "higress-conformance-infra",
+				},
+				Request: http.AssertionRequest{
+					ActualRequest: http.Request{
+						Host:             "redis-inject-spin.com",
+						Path:             "/",
+						UnfollowRedirect: true,
+					},
+				},
+				Response: http.AssertionResponse{
+					ExpectedResponse: http.Response{
+						StatusCode: 200,
+					},
+				},
+			},
+		}
+		t.Run("WasmPlugins redis-inject-spin (#4034 CPU spin repro)", func(t *testing.T) {
+			// Drive repeated requests: on the pre-fix host the deferred callback
+			// re-queues forever and a worker spins, so the route stops
+			// responding; on the fixed host every request completes.
+			for i := 0; i < 20; i++ {
+				for _, testcase := range testcases {
+					http.MakeRequestAndExpectEventuallyConsistentResponse(t, suite.RoundTripper, suite.TimeoutConfig, suite.GatewayAddress, testcase)
+				}
+			}
+		})
+	},
+}

test/e2e/conformance/tests/go-wasm-test-redis-inject-spin.yaml

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# A "dead" Redis: the Service (with manual Endpoints) makes Higress create the
+# envoy cluster so RedisInit succeeds and commands dispatch, but the endpoint IP
+# is unroutable (240.0.0.1, class-E) so every connection fails -> the plugin's
+# redis-failure callbacks fire, which is the #4034 trigger.
+apiVersion: v1
+kind: Service
+metadata:
+  name: dead-redis
+  namespace: higress-conformance-infra
+spec:
+  ports:
+    - name: redis
+      port: 6379
+      protocol: TCP
+      targetPort: 6379
+---
+apiVersion: v1
+kind: Endpoints
+metadata:
+  name: dead-redis
+  namespace: higress-conformance-infra
+subsets:
+  - addresses:
+      - ip: 240.0.0.1
+    ports:
+      - name: redis
+        port: 6379
+        protocol: TCP
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: redis-inject-spin
+  namespace: higress-conformance-infra
+spec:
+  ingressClassName: higress
+  rules:
+    - host: "redis-inject-spin.com"
+      http:
+        paths:
+          - pathType: Prefix
+            path: "/"
+            backend:
+              service:
+                name: infra-backend-v1
+                port:
+                  number: 8080
+---
+apiVersion: extensions.higress.io/v1alpha1
+kind: WasmPlugin
+metadata:
+  name: test-redis-inject-spin
+  namespace: higress-system
+spec:
+  defaultConfig:
+    service_name: "dead-redis.higress-conformance-infra.svc.cluster.local"
+    service_port: 6379
+    redis_key: "higress-4034-key"
+    inject_body: "injected-by-4034-repro\n"
+    inject_count: 16
+  url: file:///opt/plugins/wasm-go/extensions/test-redis-inject-spin/plugin.wasm