Skip to content

armgit / plane

Public Imported from GitHub
0

πŸ”₯πŸ”₯πŸ”₯ Open-source Jira, Linear, Monday, and ClickUp alternative. Plane is a modern project management platform to manage tasks, sprints, docs, and triage.

chore: add Claude Code skills for PR descriptions and release notes (#8920)

sriram veeraghantaf1d567accc5e
diff --git a/.claude/skills/pr-description.md b/.claude/skills/pr-description.md
new file mode 100644
index 0000000000..bfbfa78ba9
--- /dev/null
+++ b/.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
diff --git a/.claude/skills/release-notes.md b/.claude/skills/release-notes.md
new file mode 100644
index 0000000000..af8a7680e7
--- /dev/null
+++ b/.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