famstack-dev/famstack / .claude/skills/pr
Pull request
A PR is squash merged or rebase merged, never with a merge commit. Squashed,
the title becomes the commit subject on main and the release-notes line.
Rebased, every commit lands as it is and each subject is a release-notes line.
docs/agent/dev.md ("Commits: the subject is the changelog", "Pull requests")
holds the rules; this file is the procedure. dev.md wins.
1. Read the branch
git fetch origin
git log --reverse --format='%h %s%n%b' origin/main..HEAD
git diff --stat origin/main...HEAD
Read the diff wherever a subject does not state the user-visible change. Report a
non-empty HEAD..origin/main as "branch is behind". Do not rebase unasked.
2. Squash or rebase
Count the entries a release-notes reader sees: commits of a shown type (feat,
fix, security, perf, docs) plus any commit carrying !, Upgrade: or
BREAKING CHANGE:. Tests, refactors and chores serving one of those add no entry.
- One visible entry: squash. The title is that entry.
- Several, and every commit stands alone and passes commit-lint: rebase. Say so in the handover, and write the title as the lead change; it is not a changelog line.
- Several, but mixed with fixups or work in progress: report it. The branch needs cleaning into coherent commits, or splitting. Do not rebase unasked.
Never write a title containing "and".
3. Title
- Format:
type(scope)!: subject. Types and scopes come from the dev.md tables. - The scope names what a reader recognises, a stacklet or a bot, never a file.
- Imperative, lowercase after the colon, no full stop, no identifiers.
- Name the concrete change, not its effect:
add an install hint to restart core on the first start, notsay how to finish the agent's first start. - Limit 72 characters as commit-lint counts them; dev.md asks for under 70. The
(#N)appended at merge does not count. - Use
!only when the user must act. The description then carriesUpgrade:orBREAKING CHANGE:. - Single-commit branch whose subject passes: reuse that subject.
4. Description
## Summary
- <user-visible change, and why>
Upgrade: <required action, as markdown>
Refs: #127
- One to three bullets. Footers only when they apply.
- Start with the situation the PR answers, then what it changes: "The agent
is beta. After its first
./stack up agent, it can sign in only after a core restart." then "The hints shown after./stack up agenttell the admin to run./stack restart core, then./stack restart agent." - Plain technical English: state what the change does. No paraphrase such as "now say so" or "provide the required information".
- No "Test plan" section. Test output and measurements go in a PR comment.
- No em dashes. Use a comma, colon, period or parentheses.
- No
Co-Authored-By, no "Generated with" line, no tool link: this repository is public and commit-lint rejects all three.
4b. Read the diff as a reviewer
Check the new and touched code against docs/agent/dev.md, "Clean code:
what a reviewer checks". Fix what breaks a rule before opening the PR, or
say in the handover which rule it breaks and why.
5. Check
python3 tools/commit-lint --title "<title>"
python3 tools/commit-lint --body "<description>"
python3 tools/commit-lint --range origin/main..HEAD
CI runs the third over every commit in the PR. Fix and re-run until all three pass. Rewording a pushed commit needs a force push: request approval first.
Output: the title, the description in a code block, the three results.
6. Open
Pushing and opening a PR need explicit approval, for every push. With approval:
git push -u origin HEAD
gh pr create --base main --title "<title>" --body-file <file>
Add --draft when asked. Never merge.
Merge
State the merge mode when handing the PR over.
Squash: the repository builds the squash body from the branch's commit
messages, not from the PR description. A footer written in the description
reaches main only when the merge uses the description as the body: the merge
dialog, or gh pr merge --squash --body-file.
Rebase: gh pr merge --rebase. The commits land unchanged, so their footers
are the ones that count; one written only in the description is lost.
Issues
Work that is not done in this branch goes into a GitHub issue: something found mid-task, a follow-up, a bug to fix later. One issue per piece of work. Every issue ends with a definition of done, the checks that prove it is finished. Pick the template by kind.
Title. A short noun phrase that names the topic, the way a reader looks for it in a list of issues: "Consistent loop detection for LLM output", "Secret lookup for CLI plugins", "Paperless 500 on a first-time signup". No sentence and no imperative: the story or the summary says what becomes possible or what goes wrong. No class or function names unless a reader types them.
Feature: a story with a definition of done
## Story
As <an admin | a family member | a stacklet author>, I want <capability>,
so that <outcome>.
## Context
What exists today and why it is not enough. Point at the code
(`lib/stack/stack.py`, `stacklets/<id>/...`), ADRs and PRs.
## Proposal
The change, at the level a reviewer can argue with.
Out of scope: <what this issue does not cover>.
## Definition of done
- [ ] <an observable check: a command and its result, or a behaviour>
- [ ] <a caller-side test that states the behaviour>
- [ ] <docs updated: `docs/stack-reference.md` for framework behaviour>
Example: an admin wants the provider's "My apps" page to show an icon per
service. Done when stack up id sets a logo on every registered client
that has none, stack up id a second time uploads nothing, and a test
drives both runs against a stand-in for the provider's API.
Bug: steps to reproduce, expected and actual behaviour
## Summary
What breaks, for whom, in one sentence.
## Steps to reproduce
1. <from a known state: which stacklets are up, which mode>
2. <the action>
3. <what to look at>
## Expected behaviour
What should happen, and where that is promised (a doc, a test, a spec).
## Actual behaviour
What happens. Error text verbatim and trimmed.
## Environment
`./stack version`, macOS version, OrbStack or Docker Desktop, port or
domain mode, the stacklets involved.
## Cause
If known: the file and why. Otherwise leave the heading out.
## Definition of done
- [ ] <a test that fails before the fix and passes after it>
- [ ] <the steps above now give the expected behaviour>
Example: steps "bring up id and docs in domain mode, open the docs
login, choose the provider button as a user whose account is not linked
yet". Expected: Paperless creates the account and logs in. Actual:
500, with MultipleObjectsReturned in the Paperless log. Done when a
test pins one provider entry per client id.
Rules
- Examples and reproduction steps use the demo family and example
domains (
home.example.family), never a real instance, name, address or log excerpt with personal data. This repository is public. - No em dashes. No secrets, tokens or passwords, also not in logs.
- Opening an issue publishes it: ask first. With approval:
gh issue create --title "<title>" --body-file <file>. - A commit or PR that resolves the issue carries
Closes: #N; one that only relates to it carriesRefs: #N. - An issue closes when its fix reaches a stable release on
main, and GitHub closes it only for a PR intomain. When a PR into afeature/*base merges, give each issue it resolves the milestone of the prerelease that base leads to and leave it open:gh issue edit <N> --milestone v0.5.0-beta.1. The issue then shows that the fix is in a prerelease but not yet in a stable release.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |