codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete and you need to decide how to integrate the work - merge, PR, or cleanup
+disable-model-invocation: true
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide the completion of development work on a branch — decide how to integrate, verify readiness, execute the choice, and clean up.
+
+**Core principle:** Verify before you ship. Present options, don't assume. Clean up after yourself.
+
+## The Iron Law
+
+```
+NO MERGE WITHOUT GREEN TESTS AND CLEAN STATUS
+```
+
+If tests fail or uncommitted changes exist, STOP. Fix first. No exceptions.
+
+**Corollary:** Never push directly to main/master. Always use a PR for protected branches.
+
+## When to Use
+
+- Implementation is complete on a feature branch
+- All planned tasks are done (or intentionally deferred)
+- Ready to integrate work back to base branch
+- Need to decide: merge, PR, or abandon
+- End of an executing-plans or subagent-driven-development session
+- Wrapping up work in a git worktree
+
+## When NOT to Use
+
+- Work is still in progress (keep working)
+- You haven't run tests yet (run them first)
+- You're on the main/master branch (nothing to finish)
+
+## Phase 1: Pre-Completion Checklist
+
+**MANDATORY. Complete every item before proceeding.**
+
+### Must Pass (blocking)
+
+```bash
+# 1. All tests pass
+npm test                    # or: yarn test, pytest, go test ./...
+
+# 2. No type errors
+npx tsc --noEmit            # or equivalent for your language
+
+# 3. No uncommitted changes
+git status                  # must be clean
+
+# 4. Branch is up to date with base
+git fetch origin
+git merge-base --is-ancestor origin/<base> HEAD  # exit 0 = up to date
+```
+
+- [ ] All tests pass (zero failures)
+- [ ] No type errors (`tsc --noEmit` or equivalent)
+- [ ] Working directory clean (`git status` shows nothing)
+- [ ] No untracked files that should be committed
+- [ ] Branch is up to date with base branch
+
+### Should Check (non-blocking)
+
+- [ ] Linting passes (eslint/prettier or equivalent)
+- [ ] No TODO/FIXME left in new code
+- [ ] Commits are logically grouped (not a mess of WIP)
+- [ ] Commit messages follow project conventions
+
+### Context-Dependent
+
+- [ ] If in worktree: confirmed correct worktree
+- [ ] If linked to issue: issue number in branch name or commits
+- [ ] If PR already exists: PR is up to date with latest commits
+
+**Any blocking item fails? STOP. Fix it. Re-run the checklist.**
+
+## Phase 2: Decision Tree
+
+```dot
+digraph decision {
+    rankdir=TB;
+    node [shape=diamond, style=filled, fillcolor="#ffffcc"];
+
+    start [label="Pre-completion\nchecklist passed?", shape=diamond];
+    keep [label="Work worth\nkeeping?"];
+    protected [label="Target branch\nprotected?"];
+    review [label="Changes need\nreview?"];
+    simple [label="Single commit,\npersonal branch?"];
+
+    stop [label="STOP\nFix issues first", fillcolor="#ffcccc", shape=box];
+    abandon [label="PATH C\nCleanup / Abandon", fillcolor="#ffcccc", shape=box];
+    pr [label="PATH B\nCreate PR", fillcolor="#ccffcc", shape=box];
+    merge [label="PATH A\nMerge Directly", fillcolor="#ccccff", shape=box];
+
+    start -> keep [label="yes"];
+    start -> stop [label="no"];
+    keep -> abandon [label="no"];
+    keep -> protected [label="yes"];
+    protected -> pr [label="yes"];
+    protected -> review [label="no"];
+    review -> pr [label="yes"];
+    review -> simple [label="no"];
+    simple -> merge [label="yes"];
+    simple -> pr [label="no"];
+}
+```
+
+### Quick Reference
+
+| Condition | Path |
+|-----------|------|
+| Checklist fails | **STOP** — fix first |
+| Work not worth keeping | **PATH C** — Cleanup/Abandon |
+| Target branch is protected | **PATH B** — Create PR |
+| Changes need review | **PATH B** — Create PR |
+| Simple change, personal branch | **PATH A** — Merge Directly |
+| Unsure which path | **PATH B** — Create PR (safe default) |
+
+## Phase 3: Execute Choice
+
+### PATH A: Merge Directly
+
+For simple, single-commit changes on unprotected personal branches.
+
+```bash
+# 1. Update base branch
+git checkout <base>
+git pull origin <base>
+
+# 2. Merge feature branch
+git merge <feature-branch>
+
+# 3. Push
+git push origin <base>
+```
+
+**WARNING:** Never use PATH A if `<base>` is main/master or any protected branch. Use PATH B instead.
+
+**When to use:** Solo work, unprotected branch, trivial change, no review needed.
+
+**If merge conflicts arise:** Resolve conflicts, run tests again, then commit. If conflicts are complex, abort with `git merge --abort` and switch to PATH B.
+
+### PATH B: Create PR (Recommended Default)
+
+The safe default for most workflows. Use the `pr-all-in-one` skill if available.
+
+```bash
+# 1. Push feature branch
+git push -u origin <feature-branch>
+
+# 2. Create PR (adjust title and body as needed)
+gh pr create \
+  --title "feat: description of change" \
+  --body "## Summary
+- What changed and why
+
+## Test plan
+- [ ] Tests pass
+- [ ] Manual verification done
+
+Closes #<issue-number>"
+```
+
+**Squash before PR (if commits are messy):**
+```bash
+# Clean up commits (use interactive rebase for manual control,
+# or --autosquash for automated fixup commits)
+git rebase -i origin/<base>
+# Then force-push (ALWAYS use --force-with-lease, NEVER --force)
+git push --force-with-lease
+```
+
+**When to use:** Team projects, protected branches, changes needing review, anything non-trivial.
+
+### PATH C: Cleanup / Abandon
+
+For experimental, superseded, or failed work.
+
+**Before abandoning, check for salvageable work:**
+```bash
+# Review what would be lost
+git log origin/<base>..HEAD --oneline
+git diff origin/<base>..HEAD --stat
+
+# Cherry-pick specific commits if needed
+git checkout <base>
+git cherry-pick <commit-hash>
+```
+
+Then proceed to Phase 4 cleanup.
+
+## Phase 4: Post-Completion Cleanup
+
+### After Merge or PR Creation
+
+```bash
+# 1. Switch to base branch
+git checkout <base>
+git pull origin <base>
+
+# 2. Delete local branch (-d is safe; use -D only if unmerged and intentional)
+git branch -d <feature-branch>
+
+# 3. Delete remote branch (if merged or abandoned)
+git push origin --delete <feature-branch>
+```
+
+### If in a Git Worktree
+
+**IMPORTANT: Remove worktree BEFORE deleting the branch.**
+
+```bash
+# 1. Leave the worktree directory
+cd <main-repo-path>
+
+# 2. Remove the worktree
+git worktree remove <worktree-path>
+
+# 3. Prune stale worktree references
+git worktree prune
+
+# 4. NOW delete the branch (-d is safe; use -D only if unmerged and intentional)
+git branch -d <feature-branch>
+```
+
+**Why this order matters:** You cannot delete a branch that is checked out in a worktree. Attempting to do so will fail. Always remove the worktree first.
+
+### Verification
+
+```bash
+# Confirm cleanup
+git branch                    # feature branch should be gone
+git branch -r                 # remote branch should be gone
+git worktree list             # no stale worktrees
+```
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests mostly pass" | Mostly ≠ all. Fix the failures. |
+| "I'll clean up commits later" | Later never comes. Squash now. |
+| "Direct push is faster" | Fast now, broken later. Use a PR. |
+| "It's just a small change" | Small changes break things too. Follow the checklist. |
+| "I'll delete the branch later" | Stale branches accumulate. Clean up now. |
+| "The worktree is fine to leave" | Orphaned worktrees waste disk and cause confusion. Remove it. |
+| "Force push is fine here" | Use `--force-with-lease`. Always. No exceptions. |
+| "No one reviews my PRs anyway" | The PR is the review record. Create it anyway. |
+| "I'll rebase after merge" | Rebase before. Conflicts after merge are worse. |
+
+## Red Flags — STOP
+
+- Tests failing or skipped
+- Uncommitted changes in working directory
+- Pushing directly to main/master
+- Using `git push --force` (use `--force-with-lease`)
+- Deleting a branch before removing its worktree
+- Merging without updating base branch first
+- Skipping the pre-completion checklist
+- "Just this once" thinking
+
+**Any red flag means: STOP. Go back to Phase 1.**
+
+## Verification Checklist
+
+Before marking branch work as complete:
+
+- [ ] Pre-completion checklist passed (Phase 1)
+- [ ] Decision made and executed (Phase 2 + 3)
+- [ ] Local branch deleted
+- [ ] Remote branch deleted (if applicable)
+- [ ] Worktree removed (if applicable)
+- [ ] On base branch with latest changes
+- [ ] No stale worktree references
+
+Can't check all boxes? You're not done yet.

package/.ai-rules/skills/frontend-design/SKILL.md

@@ -40,3 +40,8 @@ Interpret creatively and make unexpected choices that feel genuinely designed fo
 **IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
 
 Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+## Additional resources
+
+- [CSS design patterns](references/css-patterns.md) — Typography systems, color tokens, layout patterns, animations, and texture techniques
+- [Component template](examples/component-template.tsx) — Production-grade React component with staggered animations, CSS variables, and accessibility

package/.ai-rules/skills/frontend-design/examples/component-template.tsx

@@ -0,0 +1,203 @@
+/**
+ * Distinctive React Component Template
+ *
+ * This template demonstrates a production-grade React component
+ * with intentional design choices that avoid generic AI aesthetics.
+ *
+ * Key patterns:
+ * - CSS variables for theming consistency
+ * - Staggered reveal animations
+ * - Fluid typography with clamp()
+ * - Accessible focus management
+ * - Motion library integration (optional)
+ */
+
+import { type ReactNode, type HTMLAttributes, forwardRef } from 'react';
+
+// ─── Types ───────────────────────────────────────────────
+
+interface FeatureCardProps extends HTMLAttributes<HTMLDivElement> {
+  /** Card title — displayed as the main heading */
+  title: string;
+  /** Supporting description text */
+  description: string;
+  /** Icon or visual element displayed above the title */
+  icon?: ReactNode;
+  /** Visual variant controlling the color scheme */
+  variant?: 'default' | 'accent' | 'muted';
+  /** Stagger delay index for entrance animation (0-based) */
+  staggerIndex?: number;
+}
+
+// ─── Component ───────────────────────────────────────────
+
+export const FeatureCard = forwardRef<HTMLDivElement, FeatureCardProps>(
+  function FeatureCard(
+    {
+      title,
+      description,
+      icon,
+      variant = 'default',
+      staggerIndex = 0,
+      className = '',
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        className={`feature-card feature-card--${variant} ${className}`}
+        style={{
+          '--stagger-delay': `${staggerIndex * 0.1}s`,
+          ...style,
+        } as React.CSSProperties}
+        {...rest}
+      >
+        {icon && <div className="feature-card__icon">{icon}</div>}
+        <h3 className="feature-card__title">{title}</h3>
+        <p className="feature-card__description">{description}</p>
+      </div>
+    );
+  },
+);
+
+// ─── Styles (CSS Module or global stylesheet) ────────────
+
+/*
+Use a separate .module.css file in production. Inline styles shown
+here for template completeness.
+
+.feature-card {
+  --card-bg: var(--color-surface-raised, hsl(0 0% 98%));
+  --card-border: var(--color-border, hsl(0 0% 90%));
+  --card-radius: 1rem;
+
+  position: relative;
+  padding: clamp(1.5rem, 3vw, 2.5rem);
+  background: var(--card-bg);
+  border: 1px solid var(--card-border);
+  border-radius: var(--card-radius);
+
+  /* Staggered entrance animation */
+  opacity: 0;
+  animation: card-reveal 0.6s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+  animation-delay: var(--stagger-delay);
+
+  /* Hover interaction */
+  transition:
+    transform 0.25s cubic-bezier(0.33, 1, 0.68, 1),
+    box-shadow 0.25s ease,
+    border-color 0.25s ease;
+}
+
+.feature-card:hover {
+  transform: translateY(-4px);
+  border-color: var(--color-primary, hsl(230 65% 50%));
+  box-shadow:
+    0 4px 6px -1px rgba(0, 0, 0, 0.05),
+    0 10px 15px -3px rgba(0, 0, 0, 0.07);
+}
+
+.feature-card:active {
+  transform: translateY(-1px);
+  transition-duration: 0.1s;
+}
+
+.feature-card:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 3px;
+}
+
+/* --- Variants --- */
+
+.feature-card--accent {
+  --card-bg: hsl(var(--hue-accent, 350) 80% 97%);
+  --card-border: hsl(var(--hue-accent, 350) 60% 85%);
+}
+
+.feature-card--muted {
+  --card-bg: hsl(0 0% 96%);
+  --card-border: transparent;
+}
+
+/* --- Children --- */
+
+.feature-card__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 3rem;
+  height: 3rem;
+  margin-bottom: 1rem;
+  border-radius: 0.75rem;
+  background: var(--color-primary-light, hsl(230 65% 95%));
+  color: var(--color-primary, hsl(230 65% 50%));
+  font-size: 1.25rem;
+}
+
+.feature-card__title {
+  margin: 0 0 0.5rem;
+  font-family: var(--font-display, 'Playfair Display', serif);
+  font-size: clamp(1.125rem, 0.9rem + 0.5vw, 1.375rem);
+  font-weight: 700;
+  line-height: 1.2;
+  letter-spacing: -0.01em;
+  color: var(--color-text, hsl(0 0% 12%));
+}
+
+.feature-card__description {
+  margin: 0;
+  font-family: var(--font-body, 'Source Sans 3', sans-serif);
+  font-size: var(--text-base, 1rem);
+  line-height: 1.6;
+  color: var(--color-text-muted, hsl(0 0% 45%));
+}
+
+/* --- Animation --- */
+
+@keyframes card-reveal {
+  from {
+    opacity: 0;
+    transform: translateY(1.5rem);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .feature-card {
+    animation: none;
+    opacity: 1;
+  }
+  .feature-card:hover {
+    transform: none;
+  }
+}
+*/
+
+// ─── Usage Example ───────────────────────────────────────
+
+/*
+import { FeatureCard } from './FeatureCard';
+import { Zap, Shield, Palette } from 'lucide-react';
+
+export function FeaturesSection() {
+  const features = [
+    { icon: <Zap />, title: 'Lightning Fast', description: 'Sub-100ms response times.' },
+    { icon: <Shield />, title: 'Secure by Default', description: 'Zero-trust architecture.' },
+    { icon: <Palette />, title: 'Fully Themeable', description: 'CSS variable driven.' },
+  ];
+
+  return (
+    <section className="features-grid">
+      {features.map((f, i) => (
+        <FeatureCard key={f.title} {...f} staggerIndex={i} />
+      ))}
+    </section>
+  );
+}
+*/