chore: add maintainer skills for PR push and issue creation (#424)

* chore: add maintainer skills for PR push and issue creation

Add two Claude Code skills under .claude/skills/ for community
maintainers:

- pr-push: 5-phase pipeline (discovery -> branch hygiene -> commit
  -> push -> PR) that enforces dev as PR target, conventional
  commits, CHANGELOG gate, and explicit stop after gh pr create (no
  auto-merge). Phase 4 falls back to inline equivalent checks when
  the .claude/hooks/pre-push-validate.sh hook is absent (gitignored,
  not present on fresh clones).
- issue-create: 4-phase interview (type -> required fields -> code
  context -> render+confirm) wrapping gh issue create with the
  project's existing label catalog and secret redaction. Performance
  reports use a dedicated perf-report.md template with measurement
  table + reproduction harness fields.

Use chore: instead of feat: so this purely-internal tooling change
does not trigger bump-electron-beta.yml (which keys off commit type
prefix).

Adjust .gitignore to .claude/* + !.claude/skills/ so private
settings.local.json and hooks/ stay ignored while skills ship with
the repo.

* test(real): switch prompt-cache fixtures from codex to gpt-5.4

The bare 'codex' alias no longer routes through the cache-eligible
path in real-upstream tests. Pin the model to gpt-5.4 so the
cached_tokens assertions across Responses, OpenAI, Anthropic, and
Gemini formats run against a deterministic backend.

* fix: docker publish triggers and schema strictness

* fix: smart version calculation in beta and docker workflows

* test: simulate version bump to 2.1.0 for beta testing

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

Author: icebear0828

.claude/skills/issue-create/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: issue-create
+description: >-
+  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.
+  TRIGGER when: user says "open an issue", "file an issue", "create issue", "report a bug", "feature request", "提个 issue", "报 bug", "提需求".
+  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).
+allowed-tools:
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# Issue Create
+
+Gather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.
+
+## Overview
+
+Most "I have a bug" or "I want a feature" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.
+
+## When to Use
+
+- A user wants to file a new issue on the codex-proxy repository.
+- A user describes a bug or feature in conversation and asks "should we file an issue?"
+
+## Important Rules
+
+1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.
+2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write "not provided" in the field, do not fabricate.
+3. **Show the full body before submitting.** The user must explicitly say "submit" / "looks good" / equivalent. "Yes" without seeing the body is not enough — show it first.
+4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.
+5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.
+6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.
+
+## Key Workflows
+
+### Phase 1: Type classification
+
+**Goal:** Pick the right template and label.
+
+Ask the user (one consolidated question):
+
+> What type of issue is this?
+>   1. **Bug** — something is broken or behaves incorrectly
+>   2. **Feature request** — propose new functionality
+>   3. **Question** — usage / configuration / "is this expected?"
+>   4. **Performance** — measurable regression or slowness
+>   5. **Documentation** — docs are wrong, missing, or unclear
+
+Read the type spec:
+```
+Read: .claude/skills/issue-create/references/issue-types.md
+```
+
+Map answer to template path:
+
+| Type | Template asset | Default label |
+|---|---|---|
+| Bug | `assets/bug-report.md` | `bug` |
+| Feature request | `assets/feature-request.md` | `enhancement` |
+| Question | `assets/question.md` | `question` |
+| Performance | `assets/perf-report.md` | `bug` |
+| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |
+
+Do **NOT** proceed to Phase 2 until the type is confirmed.
+
+### Phase 2: Required-field interview
+
+**Goal:** Collect every field the chosen template requires.
+
+Read `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.
+
+**For bugs**, the required fields are:
+- One-line summary
+- Expected behavior
+- Actual behavior
+- Reproduction steps (numbered)
+- Codex-proxy version (`npm pkg get version` or app About dialog)
+- Deployment mode (Electron app / Docker / `npm start` / dev)
+- Relevant log lines (redact secrets)
+- Frequency (always / intermittent / once)
+
+**For feature requests**, the required fields are:
+- Problem the feature solves (user-facing motivation, not the proposed solution)
+- Proposed solution (high level)
+- Alternatives considered
+- Who benefits (single user / all users / specific deployment mode)
+
+**For questions**:
+- What you tried
+- What you expected
+- What happened
+- Relevant config (redact secrets)
+
+**For performance**:
+- All bug fields, plus:
+- Measured baseline vs current (timings, memory, request count — be specific)
+- Reproduction harness (script, steps, or `tests/bench/`)
+
+**For documentation**:
+- Which doc page / file
+- What is wrong or missing
+- Suggested fix (if any)
+
+If a field cannot be answered, the user must explicitly say "not applicable" or "unknown" — record that verbatim. Do not silently skip.
+
+Do **NOT** proceed to Phase 3 until every required field has either an answer or an explicit "not applicable".
+
+### Phase 3: Code & related-context grounding
+
+**Goal:** Help maintainers find the relevant code fast.
+
+Ask the user for:
+- File paths or `file:line` references they suspect are involved (optional but encouraged).
+- Related issues / PRs to link (`Refs #N`, `Related to #N`).
+- Whether they tried searching existing issues (`gh issue list --search "<keywords>"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.
+
+If the user provides no code locations and the bug is concrete, optionally offer:
+> "Want me to grep for the relevant code so we can include file:line in the issue?"
+
+Do not grep silently — ask first, and only do it once.
+
+### Phase 4: Render, confirm, submit
+
+**Goal:** Show the final body, get explicit approval, file the issue.
+
+1. Read the chosen template:
+   ```
+   Read: .claude/skills/issue-create/assets/<template>.md
+   ```
+2. Read the labels catalog:
+   ```
+   Read: .claude/skills/issue-create/references/labels.md
+   ```
+3. Fill the template with the collected fields. Strip secrets per Important Rule #5.
+4. Pick labels:
+   - Always include the type label (Phase 1 mapping).
+   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).
+   - Add `help wanted` if the user has no plan to fix it themselves.
+   - Add `documentation` in addition to the type label if docs need updating.
+5. Show the user the complete rendered output:
+   ```
+   Title: <title>
+   Labels: <label1>, <label2>
+   Body:
+   <full body>
+   ```
+6. Ask: "Ready to submit, or want to adjust anything?"
+7. Wait for an explicit affirmative. "Yes", "submit", "go", "looks good", "提交" all qualify. Silence or hedging does not.
+8. Submit:
+   ```bash
+   gh issue create \
+     --title "<title>" \
+     --label "<label1>,<label2>" \
+     --body "$(cat <<'EOF'
+   <body>
+   EOF
+   )"
+   ```
+9. Print the issue URL.
+10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.
+
+## Common Pitfalls
+
+- Do not call `gh issue create` before showing the body for approval.
+- Do not invent reproduction steps when the user gave a vague report — ask.
+- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.
+- Do not apply labels outside the existing catalog.
+- Do not file two issues from one report without confirming the split with the user.
+- Do not grep / search the codebase silently to "fill in" missing fields — ask first.

.claude/skills/issue-create/assets/bug-report.md

@@ -0,0 +1,49 @@
+<!--
+Bug report template for codex-proxy issues.
+The issue-create skill fills in {{placeholders}}.
+Match the language of the repo's existing issues (currently a mix of zh-CN and en).
+-->
+
+## Summary
+
+{{One sentence describing the bug.}}
+
+## Expected behavior
+
+{{What the user thought would happen.}}
+
+## Actual behavior
+
+{{What actually happened.}}
+
+## Reproduction steps
+
+1. {{step 1}}
+2. {{step 2}}
+3. {{step 3 — describe the failure}}
+
+## Environment
+
+| Field | Value |
+|---|---|
+| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |
+| Deployment mode | {{Electron / Docker / `npm start` / dev}} |
+| OS + arch | {{e.g. macOS 14.5 arm64}} |
+| Frequency | {{always / intermittent / once}} |
+| First broken version (if known) | {{version or "unknown"}} |
+| Workaround (if any) | {{description or "none"}} |
+
+## Logs / output
+
+```
+{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,
+oauth_state, API keys, account IDs.}}
+```
+
+## Additional context
+
+{{Anything else the maintainer should know. Remove this section if empty.}}
+
+## Related
+
+{{Refs #N, Related to #N — remove if none.}}

.claude/skills/issue-create/assets/feature-request.md

@@ -0,0 +1,44 @@
+<!--
+Feature request template for codex-proxy issues.
+The issue-create skill fills in {{placeholders}}.
+-->
+
+## Summary
+
+{{One sentence describing the feature.}}
+
+## Problem
+
+{{The user-facing motivation. What can the user not do today, or what is
+painful about how they have to do it? DO NOT describe the proposed
+solution here — only the problem.}}
+
+## Proposed solution
+
+{{High-level description of how the feature would work. Implementation
+detail is welcome but not required. If you have a UI in mind, sketch
+or screenshot helps.}}
+
+## Alternatives considered
+
+{{Other approaches the user thought about and why they don't fit.
+Even "I considered X but it doesn't work because Y" is useful — it
+saves the maintainer from re-deriving the same conclusion.}}
+
+## Who benefits
+
+{{single user / all users / a specific deployment mode (Electron / Docker / dev) /
+a specific upstream provider / a specific account state}}
+
+## Impact if not done
+
+{{Does the user have a workaround? Is this blocking? Nice-to-have?
+Remove this section if "no impact, just nice".}}
+
+## Additional context
+
+{{Mockups, links, related discussions. Remove if empty.}}
+
+## Related
+
+{{Refs #N, Related to #N — remove if none.}}

.claude/skills/issue-create/assets/perf-report.md

@@ -0,0 +1,60 @@
+<!--
+Performance report template for codex-proxy issues.
+The issue-create skill fills in {{placeholders}}.
+A perf report without numbers is just a bug — switch to bug-report.md if
+no measurements are available.
+-->
+
+## Summary
+
+{{One sentence describing the regression or slowness.}}
+
+## Expected behavior
+
+{{What performance was expected, and where that expectation comes from
+(prior version, docs, comparable system).}}
+
+## Actual behavior
+
+{{What is observed instead.}}
+
+## Measurements
+
+| Metric | Baseline | Current | Delta |
+|---|---|---|---|
+| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |
+| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |
+
+**Methodology:** {{How the numbers were taken — script, manual stopwatch,
+profiler, load test. Be specific enough that a maintainer can reproduce.}}
+
+## Reproduction harness
+
+```
+{{Script, `tests/bench/...` reference, or numbered steps. Must be
+deterministic enough to re-measure.}}
+```
+
+## Environment
+
+| Field | Value |
+|---|---|
+| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |
+| Deployment mode | {{Electron / Docker / `npm start` / dev}} |
+| OS + arch | {{e.g. macOS 14.5 arm64}} |
+| First slow version (if known) | {{version or "unknown"}} |
+| Resource constraint hit | {{CPU / memory / network / FDs / "none"}} |
+
+## Logs / output
+
+```
+{{Relevant log lines or profiler output. SECRETS REDACTED.}}
+```
+
+## Additional context
+
+{{Anything else. Remove if empty.}}
+
+## Related
+
+{{Refs #N, Related to #N — remove if none.}}

.claude/skills/issue-create/assets/question.md

@@ -0,0 +1,40 @@
+<!--
+Question template for codex-proxy issues.
+The issue-create skill fills in {{placeholders}}.
+Note: if it turns out to be a bug, switch to the bug-report template.
+-->
+
+## What I'm trying to accomplish
+
+{{The end goal, not the immediate confusion. e.g. "I want to route
+gpt-5.5 traffic only to my work account" — not "what does
+plan_mapping do?"}}
+
+## What I tried
+
+{{Commands, config snippets, docs read, search terms used. Be specific.}}
+
+```yaml
+# Relevant config — SECRETS REDACTED
+{{config snippet or "none"}}
+```
+
+## What I expected
+
+{{What outcome did you anticipate?}}
+
+## What happened
+
+{{What did you actually observe?}}
+
+## Environment
+
+| Field | Value |
+|---|---|
+| Codex-proxy version | {{e.g. 1.4.2}} |
+| Deployment mode | {{Electron / Docker / `npm start` / dev}} |
+| OS + arch | {{e.g. macOS 14.5 arm64}} |
+
+## Additional context
+
+{{Logs, screenshots, anything else. Remove if empty.}}