mirror of
https://github.com/duthaho/claudekit.git
synced 2026-08-02 09:47:44 +03:00
feat: improved the Claude Kit as a plugin
This commit is contained in:
duthaho
@@ -0,0 +1,338 @@
|
||||
---
|
||||
name: finishing-a-development-branch
|
||||
description: >
|
||||
Use when implementation is complete and all tests pass, when ready to merge a feature branch, create a PR, or clean up after development. Use whenever you hear "ship it," "ready to merge," "branch is done," or "create a PR." Activate at the end of any feature, bugfix, or chore branch lifecycle to ensure proper verification, option presentation, and worktree cleanup.
|
||||
---
|
||||
|
||||
# Finishing a Development Branch
|
||||
|
||||
## When to Use
|
||||
|
||||
- After implementing a feature
|
||||
- After all tests pass
|
||||
- Ready to merge or create PR
|
||||
- Cleaning up after development
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Work is still in progress and not all planned changes have been implemented
|
||||
- Tests are failing and need to be fixed before the branch can be finalized
|
||||
- Uncommitted changes remain that have not been staged or committed yet
|
||||
|
||||
---
|
||||
|
||||
## The 5-Step Workflow
|
||||
|
||||
### Step 1: Verify Tests
|
||||
|
||||
Run the project's test suite:
|
||||
|
||||
```bash
|
||||
npm test
|
||||
# or
|
||||
pytest
|
||||
# or
|
||||
go test ./...
|
||||
```
|
||||
|
||||
**Decision point**:
|
||||
- Tests PASS → Continue to Step 2
|
||||
- Tests FAIL → STOP. Cannot proceed with failing tests.
|
||||
|
||||
```markdown
|
||||
⚠️ STOP: Tests failing
|
||||
|
||||
Cannot proceed with merge/PR until tests pass.
|
||||
Fix failing tests first, then restart this workflow.
|
||||
```
|
||||
|
||||
### Step 2: Determine Base Branch
|
||||
|
||||
Identify which branch this feature branch originated from:
|
||||
|
||||
```bash
|
||||
# Check tracking branch
|
||||
git branch -vv
|
||||
|
||||
# Or check common bases
|
||||
git merge-base main feature-branch
|
||||
git merge-base develop feature-branch
|
||||
```
|
||||
|
||||
Common base branches:
|
||||
- `main` or `master` - Production
|
||||
- `develop` - Development
|
||||
- `release/*` - Release branches
|
||||
|
||||
### Step 3: Present Options
|
||||
|
||||
Offer exactly four choices:
|
||||
|
||||
```markdown
|
||||
## Branch Completion Options
|
||||
|
||||
Your feature branch `feature/email-verification` is ready.
|
||||
All tests pass (42/42).
|
||||
|
||||
Choose how to proceed:
|
||||
|
||||
1. **Merge locally** - Merge into [base] on your machine
|
||||
2. **Create Pull Request** - Push and open PR for review
|
||||
3. **Keep as-is** - Leave branch for later work
|
||||
4. **Discard** - Delete this branch and all changes
|
||||
|
||||
Enter your choice (1-4):
|
||||
```
|
||||
|
||||
### Step 4: Execute Choice
|
||||
|
||||
#### Option 1: Merge Locally
|
||||
|
||||
```bash
|
||||
# Switch to base branch
|
||||
git checkout main
|
||||
|
||||
# Pull latest
|
||||
git pull origin main
|
||||
|
||||
# Merge feature branch
|
||||
git merge feature/email-verification
|
||||
|
||||
# Verify tests still pass
|
||||
npm test
|
||||
|
||||
# Delete feature branch
|
||||
git branch -d feature/email-verification
|
||||
```
|
||||
|
||||
#### Option 2: Create Pull Request
|
||||
|
||||
```bash
|
||||
# Push branch to remote
|
||||
git push -u origin feature/email-verification
|
||||
|
||||
# Create PR (using gh CLI)
|
||||
gh pr create \
|
||||
--title "Add email verification" \
|
||||
--body "## Summary
|
||||
- Implements email verification flow
|
||||
- Adds verification token generation
|
||||
- Includes tests for all scenarios
|
||||
|
||||
## Test Plan
|
||||
- [x] Unit tests pass
|
||||
- [x] Integration tests pass
|
||||
- [x] Manual testing complete"
|
||||
```
|
||||
|
||||
#### Option 3: Keep As-Is
|
||||
|
||||
```markdown
|
||||
Branch preserved: feature/email-verification
|
||||
|
||||
Note: Remember to return to this branch later.
|
||||
Current state: All tests passing, ready for merge.
|
||||
```
|
||||
|
||||
#### Option 4: Discard
|
||||
|
||||
```markdown
|
||||
⚠️ WARNING: This will delete all work on this branch.
|
||||
|
||||
Type "discard" to confirm: _______
|
||||
```
|
||||
|
||||
If confirmed:
|
||||
```bash
|
||||
# Switch away from branch
|
||||
git checkout main
|
||||
|
||||
# Force delete branch
|
||||
git branch -D feature/email-verification
|
||||
|
||||
# If pushed to remote, delete there too
|
||||
git push origin --delete feature/email-verification
|
||||
```
|
||||
|
||||
### Step 5: Cleanup Worktree (if applicable)
|
||||
|
||||
For options 1, 2, and 4, cleanup the worktree environment:
|
||||
|
||||
```bash
|
||||
# Remove worktree
|
||||
git worktree remove ../feature-email-verification
|
||||
|
||||
# Or if worktree is in special location
|
||||
git worktree remove /path/to/worktree
|
||||
```
|
||||
|
||||
For option 3 (keep), preserve the worktree.
|
||||
|
||||
---
|
||||
|
||||
## Decision Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ Tests Passing? │
|
||||
└───────────┬─────────────┘
|
||||
│
|
||||
┌────┴────┐
|
||||
│ NO │──────► STOP: Fix tests first
|
||||
└─────────┘
|
||||
│
|
||||
YES
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ Present 4 Options │
|
||||
└───────────┬─────────────┘
|
||||
│
|
||||
┌───────┼───────┬───────┐
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
Merge PR Keep Discard
|
||||
│ │ │ │
|
||||
▼ ▼ │ ▼
|
||||
Cleanup Cleanup │ Confirm
|
||||
│ │ │ │
|
||||
▼ ▼ │ ▼
|
||||
Done Done Done Cleanup
|
||||
│
|
||||
▼
|
||||
Done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Template
|
||||
|
||||
When choosing Option 2:
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
|
||||
[Brief description of changes]
|
||||
|
||||
## Changes
|
||||
|
||||
- [Change 1]
|
||||
- [Change 2]
|
||||
- [Change 3]
|
||||
|
||||
## Test Plan
|
||||
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tests pass
|
||||
- [ ] Manual testing scenarios:
|
||||
- [ ] Scenario 1
|
||||
- [ ] Scenario 2
|
||||
|
||||
## Screenshots (if applicable)
|
||||
|
||||
[Add screenshots here]
|
||||
|
||||
## Related Issues
|
||||
|
||||
Closes #[issue number]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Before Each Option
|
||||
|
||||
### Before Merge
|
||||
|
||||
```markdown
|
||||
- [ ] Tests pass on feature branch
|
||||
- [ ] Base branch is up to date
|
||||
- [ ] No merge conflicts
|
||||
- [ ] Tests pass after merge
|
||||
```
|
||||
|
||||
### Before PR
|
||||
|
||||
```markdown
|
||||
- [ ] Tests pass
|
||||
- [ ] Branch pushed to remote
|
||||
- [ ] PR description complete
|
||||
- [ ] Reviewers assigned (if required)
|
||||
```
|
||||
|
||||
### Before Discard
|
||||
|
||||
```markdown
|
||||
- [ ] Confirmed with user (typed "discard")
|
||||
- [ ] No valuable uncommitted changes
|
||||
- [ ] Branch deleted locally
|
||||
- [ ] Branch deleted from remote (if pushed)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stack-Specific Pre-Merge Checklist
|
||||
|
||||
### Python/FastAPI
|
||||
|
||||
```bash
|
||||
pytest -v --cov=src # Full test suite
|
||||
ruff check . && ruff format --check . # Lint + format
|
||||
mypy src/ --strict # Type check
|
||||
pip-audit # Security audit
|
||||
alembic upgrade head && alembic check # Verify migrations
|
||||
```
|
||||
|
||||
### TypeScript/NestJS
|
||||
|
||||
```bash
|
||||
npm test # Full test suite
|
||||
npm run lint # Lint
|
||||
npm run build # Build (catches type errors)
|
||||
npm audit --production # Security audit
|
||||
npx prisma migrate status # Verify migrations
|
||||
```
|
||||
|
||||
### Next.js
|
||||
|
||||
```bash
|
||||
npm test # Tests
|
||||
next lint # Lint
|
||||
next build # Build (catches SSR/RSC issues)
|
||||
```
|
||||
|
||||
### Stack-Specific PR Description Extras
|
||||
|
||||
**Python/FastAPI PRs** — include:
|
||||
- Migration included? (alembic revision)
|
||||
- New dependencies? (requirements.txt changes)
|
||||
- Async patterns verified? (no blocking calls in async)
|
||||
|
||||
**NestJS PRs** — include:
|
||||
- New modules registered in AppModule?
|
||||
- DTOs have class-validator decorators?
|
||||
- Prisma schema changed? (migration included)
|
||||
|
||||
**Next.js PRs** — include:
|
||||
- Server vs Client components correct?
|
||||
- Bundle size impact?
|
||||
- `'use client'` directives where needed?
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**"Verify tests → Present options → Execute choice → Clean up"**
|
||||
|
||||
Never:
|
||||
- Merge with failing tests
|
||||
- Delete work without confirmation
|
||||
- Skip the verification step
|
||||
- Leave orphaned worktrees
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `requesting-code-review` - Use before finishing the branch to get review feedback, especially for Option 2 (Create PR)
|
||||
- `verification-before-completion` - Run verification checks before claiming the branch is ready to finish
|
||||
- `executing-plans` - If the branch was created from an execution plan, return to the plan to mark tasks complete
|
||||
@@ -0,0 +1,197 @@
|
||||
# Branch Completion Checklist
|
||||
|
||||
Checklist and reference for completing a development branch and integrating work.
|
||||
|
||||
## Pre-Merge Checklist
|
||||
|
||||
### Code Quality
|
||||
|
||||
- [ ] All tests pass on the branch (`pytest -v` / `pnpm test`)
|
||||
- [ ] No linting errors (`ruff check` / `eslint .`)
|
||||
- [ ] Type checking passes (`mypy` / `tsc --noEmit`)
|
||||
- [ ] No TODO/FIXME without a ticket reference
|
||||
- [ ] No debugging artifacts (print statements, console.log, commented-out code)
|
||||
- [ ] No hardcoded secrets, API keys, or credentials
|
||||
|
||||
### Review
|
||||
|
||||
- [ ] Code review requested and approved
|
||||
- [ ] All review comments addressed (fixed, deferred with ticket, or discussed)
|
||||
- [ ] No unresolved conversations in the PR
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Unit tests added for new behavior
|
||||
- [ ] Integration tests added for new endpoints/services
|
||||
- [ ] Edge cases covered (empty input, max size, unauthorized, concurrent)
|
||||
- [ ] Test coverage meets minimum threshold (80% overall, 95% critical paths)
|
||||
- [ ] Manual testing completed for UI/UX changes
|
||||
|
||||
### Documentation
|
||||
|
||||
- [ ] Public API documentation updated (docstrings, OpenAPI spec)
|
||||
- [ ] README updated (if setup steps changed)
|
||||
- [ ] CHANGELOG entry added (if applicable)
|
||||
- [ ] Migration guide written (if breaking changes)
|
||||
- [ ] Architecture/design docs updated (if structural changes)
|
||||
|
||||
### Branch Hygiene
|
||||
|
||||
- [ ] Branch is up to date with main (rebase or merge)
|
||||
- [ ] No merge conflicts
|
||||
- [ ] Commit history is clean and meaningful
|
||||
- [ ] Branch name follows convention (`feature/`, `fix/`, `hotfix/`, `chore/`)
|
||||
|
||||
### CI/CD
|
||||
|
||||
- [ ] CI pipeline is green (all checks pass)
|
||||
- [ ] Build succeeds
|
||||
- [ ] No new warnings introduced
|
||||
- [ ] Performance benchmarks pass (if applicable)
|
||||
- [ ] Security scan passes (if applicable)
|
||||
|
||||
### Database/Infrastructure
|
||||
|
||||
- [ ] Migrations are reversible
|
||||
- [ ] Migrations have been tested (up and down)
|
||||
- [ ] No destructive schema changes without a migration plan
|
||||
- [ ] Environment variables documented (if new ones added)
|
||||
- [ ] Feature flags configured (if using progressive rollout)
|
||||
|
||||
## Merge Strategy Decision
|
||||
|
||||
### Merge Commit (`git merge --no-ff`)
|
||||
|
||||
**When to use:**
|
||||
- Feature branch with multiple meaningful commits
|
||||
- You want to preserve the full development history
|
||||
- Team convention requires merge commits
|
||||
|
||||
**Result:** Preserves all commits plus a merge commit. Creates a clear merge point in history.
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git merge --no-ff feature/TICKET-123-description
|
||||
```
|
||||
|
||||
### Squash Merge (`git merge --squash`)
|
||||
|
||||
**When to use:**
|
||||
- Feature branch has messy/WIP commits
|
||||
- The feature is a single logical unit
|
||||
- You want a clean linear history on main
|
||||
|
||||
**Result:** All commits become one commit on main.
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git merge --squash feature/TICKET-123-description
|
||||
git commit -m "feat(orders): add bulk order cancellation (#123)"
|
||||
```
|
||||
|
||||
### Rebase (`git rebase main` + fast-forward merge)
|
||||
|
||||
**When to use:**
|
||||
- Small number of clean, atomic commits
|
||||
- You want linear history without merge commits
|
||||
- Each commit builds on the previous logically
|
||||
|
||||
**Result:** Commits are replayed on top of main. No merge commit.
|
||||
|
||||
```bash
|
||||
git checkout feature/TICKET-123-description
|
||||
git rebase main
|
||||
git checkout main
|
||||
git merge --ff-only feature/TICKET-123-description
|
||||
```
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Situation | Strategy |
|
||||
|---|---|
|
||||
| Feature with messy WIP commits | Squash |
|
||||
| Feature with clean, meaningful commits | Merge commit or rebase |
|
||||
| Single commit fix | Fast-forward (rebase) |
|
||||
| Long-lived branch, multiple contributors | Merge commit |
|
||||
| Team prefers linear history | Squash or rebase |
|
||||
| Need to bisect individual changes later | Merge commit or rebase (not squash) |
|
||||
|
||||
## Update Branch Before Merging
|
||||
|
||||
### Option A: Rebase onto main
|
||||
|
||||
```bash
|
||||
git checkout feature/TICKET-123-description
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
# Resolve conflicts if any
|
||||
git push --force-with-lease # update remote branch
|
||||
```
|
||||
|
||||
**Pros:** Clean linear history.
|
||||
**Cons:** Rewrites history (don't use if others are working on the branch).
|
||||
|
||||
### Option B: Merge main into branch
|
||||
|
||||
```bash
|
||||
git checkout feature/TICKET-123-description
|
||||
git fetch origin
|
||||
git merge origin/main
|
||||
# Resolve conflicts if any
|
||||
git push
|
||||
```
|
||||
|
||||
**Pros:** Safe, preserves history, works with shared branches.
|
||||
**Cons:** Adds merge commits to the feature branch.
|
||||
|
||||
## Post-Merge Steps
|
||||
|
||||
### Immediate
|
||||
|
||||
- [ ] Delete the feature branch (local and remote)
|
||||
```bash
|
||||
git branch -d feature/TICKET-123-description
|
||||
git push origin --delete feature/TICKET-123-description
|
||||
```
|
||||
- [ ] Verify main branch builds and tests pass
|
||||
- [ ] Verify deployment to staging/preview environment succeeds
|
||||
|
||||
### Follow-Up
|
||||
|
||||
- [ ] Close the associated ticket/issue
|
||||
- [ ] Notify the team (if significant change)
|
||||
- [ ] Monitor logs and error rates after deployment
|
||||
- [ ] Verify the feature works in the deployed environment
|
||||
- [ ] Update project board/tracker
|
||||
|
||||
### If Something Goes Wrong
|
||||
|
||||
| Problem | Action |
|
||||
|---|---|
|
||||
| Tests fail on main after merge | Revert the merge commit immediately, investigate on a new branch |
|
||||
| Deployment fails | Roll back deployment, investigate, do not push fixes to main under pressure |
|
||||
| Bug found in production | Create a hotfix branch from main, fix, test, deploy |
|
||||
| Need to undo a squash merge | `git revert <squash-commit-sha>` |
|
||||
| Need to undo a merge commit | `git revert -m 1 <merge-commit-sha>` |
|
||||
|
||||
## Quick Reference: Common Commands
|
||||
|
||||
```bash
|
||||
# Check if branch is up to date with main
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
|
||||
# See what will be merged
|
||||
git log main..HEAD --oneline
|
||||
|
||||
# See the full diff against main
|
||||
git diff main...HEAD
|
||||
|
||||
# Check CI status (GitHub CLI)
|
||||
gh pr checks
|
||||
|
||||
# Merge via GitHub CLI
|
||||
gh pr merge --squash # or --merge, --rebase
|
||||
|
||||
# Delete branch after merge
|
||||
gh pr merge --squash --delete-branch
|
||||
```
|
||||
Reference in New Issue
Block a user