Merge pull request #36 from Pressingly/sync/upstream-1.3.1

Sync foss-main with upstream Plane v1.3.1

Author: UsamaSadiq

.claude/skills/pr-description.md

@@ -0,0 +1,58 @@
+---
+name: pr-description
+description: Generate a PR description following the project's GitHub PR template. Analyzes the current branch's changes against the base branch to produce a complete, filled-out PR description.
+user_invocable: true
+---
+
+# PR Description Generator
+
+Generate a pull request description based on the project's PR template at `.github/pull_request_template.md`.
+
+## Steps
+
+1. **Determine the base branch**: Prefer the PR's actual `baseRefName` (via `gh pr view <PR> --json baseRefName`) when a PR exists. Otherwise default by intent — feature PRs target `preview`, release PRs target `master`. If still ambiguous, ask the user.
+
+2. **Analyze changes**: Run the following to understand what changed:
+   - `git log <base>...HEAD --oneline` to see all commits on this branch
+   - `git diff <base>...HEAD --stat` to see which files changed
+   - `git diff <base>...HEAD` to read the actual diff (use `--no-color`)
+   - If the diff is very large, focus on the most important files first
+
+3. **Fill out the PR template** with the following sections:
+
+   ### Description
+
+   Write a clear, concise summary of what the PR does and why. Focus on the "what" and "why", not line-by-line changes. Mention any important implementation decisions.
+
+   ### Type of Change
+
+   Check the appropriate box(es) based on the changes:
+   - Bug fix (non-breaking change which fixes an issue)
+   - Feature (non-breaking change which adds functionality)
+   - Improvement (non-breaking change that improves existing functionality)
+   - Code refactoring
+   - Performance improvements
+   - Documentation update
+
+   ### Screenshots and Media
+
+   Leave this section for the user to fill in, preserving the existing placeholder comment from `.github/pull_request_template.md` verbatim rather than introducing different text.
+
+   ### Test Scenarios
+
+   Based on the code changes, suggest specific test scenarios that should be verified. Be concrete (e.g., "Navigate to project settings and verify the new toggle works") rather than generic.
+
+   ### References
+   - If commit messages or branch name reference a work item identifier (e.g., `WEB-1234`), include it
+   - If the user provides a linked issue, include it
+   - If Sentry issue links or IDs (e.g., `SENTRY-ABC123`, Sentry URLs) were mentioned earlier in the conversation, include them as references
+
+4. **Output format**: Print the filled-out markdown template so the user can copy it directly. Do NOT wrap it in a code fence — output the raw markdown.
+
+## Guidelines
+
+- Keep the description concise but informative
+- Use bullet points for multiple changes
+- Focus on user-facing impact, not implementation details
+- If the branch has a Plane work item ID in its name (e.g., `WEB-1234`), reference it
+- Don't fabricate test scenarios that aren't relevant to the actual changes

.claude/skills/release-notes.md

@@ -0,0 +1,147 @@
+---
+name: release-notes
+description: "Generate release notes for a Plane release PR in `makeplane/plane` (semver, e.g. `release: vX.Y.Z`). Reads PR commits, filters out noise, categorizes by conventional-commit type, optionally enriches via Plane MCP, and writes the result as the PR description."
+user_invocable: true
+---
+
+# Release Notes Generator
+
+Generate structured release notes from a Plane release PR by parsing its commit list, then update the PR description.
+
+## Versioning
+
+Plane community uses **semver** (`vX.Y.Z`, major.minor.patch) for releases.
+
+- PR title format: `release: vX.Y.Z`
+- Source branch: `canary`
+- Target branch: `master`
+
+## When to Use
+
+- User links/mentions a Plane release PR (e.g. `release: v1.3.0`) and asks for release notes
+- User asks to "create release notes" / "update PR description" for a release PR in `makeplane/plane`
+- The branch is named `canary` or `release/x.y.z` and the base is `master`
+
+## Steps
+
+### 1. Fetch commits
+
+```bash
+gh pr view <PR_NUM> --json title,body,baseRefName,headRefName,commits \
+  --jq '.commits[] | .messageHeadline + "\n---BODY---\n" + .messageBody + "\n===END==="'
+```
+
+For a quick scan first:
+
+```bash
+gh pr view <PR_NUM> --json commits \
+  --jq '.commits[] | {oid: .oid[0:10], message: .messageHeadline}'
+```
+
+### 2. Filter out noise
+
+**Always exclude** these commits — mechanical, not user-facing:
+
+| Pattern                                      | Reason         |
+| -------------------------------------------- | -------------- |
+| `fix: merge conflicts`                       | Merge artifact |
+| `Merge branch '...' of github.com:...`       | Merge artifact |
+| `Revert "..."` (when immediately re-applied) | Internal churn |
+
+### 3. Parse work item IDs
+
+Most meaningful commits begin with a Plane work item identifier in brackets:
+
+- `[WEB-XXXX]` — web/frontend product items
+- `[SILO-XXXX]` — Silo (integrations: Slack, GitHub, GitLab, Jira/Linear)
+- `[MOBILE-XXXX]`, `[API-XXXX]`, etc.
+
+Always preserve these IDs in the release notes — they let readers click through to the source ticket.
+
+### 4. (Optional) Enrich via Plane MCP
+
+For larger features where the commit headline is terse, fetch the work item:
+
+```text
+mcp__plane__retrieve_work_item_by_identifier(project_identifier="WEB", issue_identifier=6874)
+```
+
+Use the returned `name` and `description_stripped` to flesh out the bullet. Skip this for routine fixes — commit body is usually enough. Don't enrich every item (slow + work item descriptions are often empty).
+
+### 5. Categorize by conventional-commit type
+
+| Commit prefix                    | Section             |
+| -------------------------------- | ------------------- |
+| `feat:`, `feat(scope):`          | ✨ New Features     |
+| `fix:`, `fix(scope):`            | 🐛 Bug Fixes        |
+| `refactor:`                      | 🔧 Refactor & Chore |
+| `chore:`, `chore(scope):`        | 🔧 Refactor & Chore |
+| `chore(deps):`, dependabot bumps | 📦 Dependencies     |
+
+### 6. Format
+
+```markdown
+# Release vX.Y.Z
+
+## ✨ New Features
+
+- **<Short title>** — [WEB-XXXX] (#PR_NUM)
+  Optional 1–2 sentence elaboration drawn from commit body.
+
+## 🐛 Bug Fixes
+
+- **<Short title>** — [WEB-XXXX] (#PR_NUM)
+
+## 🔧 Refactor & Chore
+
+- **<Short title>** — [WEB-XXXX] (#PR_NUM)
+
+## 📦 Dependencies
+
+- Bump `<package>` X.Y.Z → A.B.C (#PR_NUM)
+```
+
+Rules:
+
+- Lead with a bold human-readable title (rewrite the commit subject if cryptic)
+- Always include the work item ID in brackets and the merge PR number in parens
+- Add a sub-line elaboration only when the commit body has substance worth surfacing (acceptance criteria, scope notes, gotchas like "behind feature flag", "requires migration", "requires Vercel setting")
+- Drop empty sections
+
+### 7. Update the PR description
+
+```bash
+gh pr edit <PR_NUM> --body "$(cat <<'EOF'
+<release notes markdown>
+EOF
+)"
+```
+
+Always use a HEREDOC with single-quoted `'EOF'` so backticks/dollars in the notes are preserved.
+
+## Quick Reference: end-to-end
+
+```bash
+PR=2498
+gh pr view $PR --json commits --jq '.commits[] | .messageHeadline + "\n---\n" + .messageBody + "\n==="' > /tmp/commits.txt
+# read /tmp/commits.txt, filter, categorize, draft notes
+gh pr edit $PR --body "$(cat <<'EOF'
+... release notes ...
+EOF
+)"
+```
+
+## Common Mistakes
+
+- **Including `fix: merge conflicts`** — merge artifact, no functional content
+- **Dropping the work item ID** — readers rely on `[WEB-XXXX]` to navigate to the ticket
+- **Over-enriching with MCP lookups** — work item descriptions are often empty; commit body is usually richer
+- **Missing the merge PR number** — always include `(#NNNN)` from the commit subject so reviewers can audit the source PR
+- **Using `--body` without HEREDOC** — backticks/dollar signs get shell-interpreted and corrupt the notes
+- **Editing the title** — release PR titles are version markers; only edit the body
+
+## Plane-Specific Conventions
+
+- Release PRs go from `canary` → `master`
+- PR title format: `release: vX.Y.Z` semver (major.minor.patch)
+- Commits coming from feature branches always carry a work item ID; commits without one are usually infra/chores