chore: add issue forms and PR template

[ericjypark]

What changed

Adds structured GitHub templates so incoming bugs and PRs arrive with the info needed to triage and review them.

• .github/ISSUE_TEMPLATE/bug_report.yml — required fields for app version, macOS version, install method, repro steps, area dropdown, plus optional settings/log dumps.
• .github/ISSUE_TEMPLATE/feature_request.yml — problem-first framing, alternatives, scope estimate.
• .github/ISSUE_TEMPLATE/api_regression.yml — dedicated form for the undocumented Claude/Codex usage endpoints; asks for the raw response (token redacted) so the parser can be updated quickly.
• .github/ISSUE_TEMPLATE/config.yml — disables blank issues; routes open-ended questions to Discussions and security reports to private advisories.
• .github/PULL_REQUEST_TEMPLATE.md — forces a "how to verify" section, a screenshot for UI changes, a release-impact dropdown, and a Sparkle pre-flight that mirrors the hard rules in CLAUDE.md (monotonic semver, never touch SU_PUBLIC_KEY, no hand-edits to the cask or appcast, sync the landing repo's VERSION).

Why

Issues and PRs from outside contributors have been arriving without the basics — version, repro, what to actually click on to verify the change. The templates enforce that up front and surface the bricking-risk gotchas (Sparkle key, version monotonicity, cask drift) right next to the checkbox that would otherwise miss them.

How to verify

1. After merge, visit https://github.com/ericjypark/codex-island/issues/new/choose and confirm the three forms render with the expected required fields and dropdowns.
2. Open a draft PR against any branch and confirm the PR body is pre-filled from PULL_REQUEST_TEMPLATE.md.
3. Confirm "blank issue" is no longer an option from the chooser, and that the Discussions/security links appear.

Risk

Repo-metadata only — no code paths or build scripts touched. Worst case is a typo in a template, fixable in a follow-up.

---

Generated by Claude Code

Summary by CodeRabbit

• Chores
  • Added standardized GitHub issue templates for bug reports, feature requests, and API regression reporting to improve issue submission clarity and categorization.
  • Added issue template configuration to disable blank issues and direct users to appropriate channels for questions and security disclosures.
  • Added pull request template to standardize contribution guidelines and verification procedures.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7c31bf7d-3390-4eb5-b01f-cceb133cbf4e

📥 Commits

Reviewing files that changed from the base of the PR and between 1716fbb and 0ca20fd.

📒 Files selected for processing (5)

• .github/ISSUE_TEMPLATE/api_regression.yml
• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/PULL_REQUEST_TEMPLATE.md

---

📝 Walkthrough

Walkthrough

This PR introduces GitHub templates to standardize issue reporting and pull request submissions. Five new template files are added: a configuration file that disables blank issues and routes questions/security reports, three issue templates for bugs, API regressions, and feature requests with guided forms, and a PR template enforcing Conventional Commits conventions with required narrative and release verification sections.

Changes

GitHub Templates Configuration

Layer / File(s)	Summary
Template Configuration Framework .github/ISSUE_TEMPLATE/config.yml	Disables blank issues and adds two contact links: one for discussions/questions and one for security advisories.
Bug Report Template .github/ISSUE_TEMPLATE/bug_report.yml	Collects app/macOS version, installation method, bug narrative (what happened/expected/steps), affected app area (multi-select), usage state confirmation, and optional debugging artifacts (settings dump, console logs, additional details).
API Regression Template .github/ISSUE_TEMPLATE/api_regression.yml	Captures endpoint selection (Claude /api/oauth/usage or Codex /wham/usage), CodexIsland version, symptom description, token-redacted response JSON with Claude header guidance, and approximate issue start time.
Feature Request Template .github/ISSUE_TEMPLATE/feature_request.yml	Gathers problem statement, proposed solution, considered alternatives, rough scope (Small/Medium/Large/Not sure), and willingness to help (test/open PR).
Pull Request Template .github/PULL_REQUEST_TEMPLATE.md	Enforces lowercase Conventional Commits, disallows Co-Authored-By and specific AI-style vocabulary. Includes sections for narrative (what changed/why/how to verify), optional screenshots, risk assessment, release impact options, pre-flight checklist (build/smoke/commit compliance), and sparkle-release constraints (VERSION monotonicity, SU_PUBLIC_KEY unchanged, cross-repo sync check).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A rabbit hops through GitHub's door,
With templates neat forevermore,
Bug reports, features, PRs aligned,
Conventions checked, no chaos to find! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chore: add issue forms and PR template' directly and accurately describes the main changes: it specifies that issue forms and a PR template are being added as repository metadata.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/add-issue-pr-templates-5NMp0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ericjypark]

@claude review

[claude]

Claude finished @ericjypark's task in 1m 29s —— View job

---

PR Review

• Read changed files
• Analyze templates for correctness, completeness, and alignment with CLAUDE.md
• Post review feedback

---

This is a solid, well-considered set of templates. A few observations:

What's working well

• bug_report.yml — the usage-state field (line 92–96) that pre-filters HTTP 4xx errors before filing is a nice design touch. It directly encodes the most common false alarm (stale token → re-login) from CLAUDE.md's incidents table, which will save triage time.
• api_regression.yml — correctly captures the undocumented endpoint details: the required claude-code/X.Y.Z User-Agent, the oauth-2025-04-20 beta header, and the refresh token endpoint at platform.claude.com (not the old console.anthropic.com). All three of these are tripping hazards documented in CLAUDE.md.
• PULL_REQUEST_TEMPLATE.md — the Sparkle pre-flight section faithfully mirrors every hard rule from CLAUDE.md: monotonic semver, SU_PUBLIC_KEY immutability, no hand-edits to the cask or appcast, and the landing repo VERSION sync. Cross-referencing these in the checklist is exactly where they need to be.
• scripts/verify.sh exists and does what the template claims (1-second smoke launch), so the ./scripts/verify.sh checkbox in the pre-flight is not a dead reference.
• The CONTRIBUTING.md#things-that-need-work anchor referenced in feature_request.yml (line 9) exists in the file.

Minor issues

1. Discussions dependency — both config.yml (contact link) and the feature_request.yml preamble route users to github.com/ericjypark/codex-island/discussions. If GitHub Discussions isn't enabled in the repo settings, both links 404. Worth confirming the feature is on before merging. Fix this →

2. verify.sh is macOS-only — the PR pre-flight checkbox ./scripts/verify.sh passes locally will fail silently for any contributor on Linux or Windows (the script builds and launches .app). The checkbox wording could be ./scripts/verify.sh passes (macOS only) to avoid confusion. Low stakes, but cleaner. Fix this →

3. AI vocab ban in PR template — banning "comprehensive, delve, crucial, robust, seamless" in commit messages/docs is the kind of thing that silently confuses contributors who don't read the full template. The list is borrowed from CLAUDE.md but CLAUDE.md is a private maintainer doc; putting it in a public-facing PR template without any explanation of why it exists may generate friction. Not blocking, but consider adding a one-liner like ``.

Verdict: Ready to merge. Item 1 (Discussions) is the only thing worth double-checking before the templates go live — everything else is stylistic.

[ericjypark]

Self-review pass on the diff. Things worth flagging before merge:

Pre-flight caveats

• .github/ISSUE_TEMPLATE/config.yml links to Discussions and to a private security advisory. Both 404 if those features aren't enabled on the repo. Worth confirming both are turned on under Settings → General → Features and Settings → Security → Private vulnerability reporting — otherwise either remove the link or enable the feature.
• The bug-report form asks for defaults read dev.codexisland.CodexIsland CFBundleShortVersionString. That actually reads the running app's bundle, not user defaults — it works because the app writes its Info.plist keys into the prefs domain on first launch, but if a user has never launched the app it returns nothing. Acceptable, but the "About" menu reference in the same field is the more reliable instruction.
• bug_report.yml "Which part of the app?" uses multiple: true. GitHub's form schema supports it; just noting it so the dropdown isn't unexpectedly multi-select.

Things I deliberately did not include

• No CODEOWNERS — the repo is single-maintainer right now, so auto-assigning reviews is noise. Add later if more maintainers come on.
• No funding.yml — CONTRIBUTING.md already links GitHub Sponsors. Skipping the extra surface.
• No dependabot.yml — there are no package manifests to watch (Swift sources + shell scripts only). Sparkle is vendored fresh by CI on each build.

Risk

Metadata only. Worst case: a typo in a template, fixable in one commit. Nothing here can affect Sparkle, the build, or auto-update.

Recommend merging once Discussions + private security reporting are confirmed enabled.

---

Generated by Claude Code