agy-superpowers 5.1.2 → 5.1.4

package/template/agent/skills/frontend-design/reference/responsive-design.md

@@ -0,0 +1,161 @@
+# Responsive Design
+
+## Mobile-First: Write It Right
+
+Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
+
+```css
+/* Mobile-first (correct) */
+.container { padding: 1rem; }
+
+@media (min-width: 768px) {
+  .container { padding: 2rem; }
+}
+
+/* Desktop-first (wrong way) */
+.container { padding: 2rem; }
+
+@media (max-width: 768px) {
+  .container { padding: 1rem; }
+}
+```
+
+---
+
+## Breakpoints: Content-Driven
+
+Don't chase device sizes — let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice: 640, 768, 1024px. Use `clamp()` for fluid values without breakpoints.
+
+---
+
+## Detect Input Method, Not Just Screen Size
+
+Screen size doesn't tell you input method. A laptop with touchscreen, a tablet with keyboard — use pointer and hover queries:
+
+```css
+/* Fine pointer (mouse, trackpad) */
+@media (pointer: fine) {
+  .button { padding: 8px 16px; }
+}
+
+/* Coarse pointer (touch, stylus) */
+@media (pointer: coarse) {
+  .button { padding: 12px 20px; }
+}
+
+/* Device supports hover */
+@media (hover: hover) {
+  .card:hover { transform: translateY(-2px); }
+}
+
+/* Device doesn't support hover (touch) */
+@media (hover: none) {
+  .card { /* No hover state — use active instead */ }
+}
+```
+
+**Critical**: Don't rely on hover for functionality. Touch users can't hover.
+
+---
+
+## Safe Areas: Handle the Notch
+
+Modern phones have notches, rounded corners, and home indicators:
+
+```css
+body {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+/* With fallback */
+.footer {
+  padding-bottom: max(1rem, env(safe-area-inset-bottom));
+}
+```
+
+Enable viewport-fit in your meta tag:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+---
+
+## Responsive Images
+
+### srcset with Width Descriptors
+
+```html
+<img
+  src="hero-800.jpg"
+  srcset="
+    hero-400.jpg 400w,
+    hero-800.jpg 800w,
+    hero-1200.jpg 1200w
+  "
+  sizes="(max-width: 768px) 100vw, 50vw"
+  alt="Hero image"
+>
+```
+
+- `srcset` lists available images with their actual widths
+- `sizes` tells the browser how wide the image will display
+- Browser picks the best file based on viewport width AND device pixel ratio
+
+### Picture Element for Art Direction
+
+When you need different crops/compositions (not just resolutions):
+
+```html
+<picture>
+  <source media="(min-width: 768px)" srcset="wide.jpg">
+  <source media="(max-width: 767px)" srcset="tall.jpg">
+  <img src="fallback.jpg" alt="...">
+</picture>
+```
+
+---
+
+## Layout Adaptation Patterns
+
+**Navigation** — three stages:
+- Mobile: hamburger + drawer
+- Tablet: horizontal compact
+- Desktop: full with labels
+
+**Tables** — transform to cards on mobile:
+```css
+@media (max-width: 640px) {
+  table, thead, tbody, tr, td {
+    display: block;
+  }
+  
+  td::before {
+    content: attr(data-label) ": ";
+    font-weight: bold;
+  }
+  
+  thead { display: none; }
+}
+```
+
+**Progressive disclosure** — use `<details>/<summary>` for content that can collapse on mobile.
+
+---
+
+## Testing: Don't Trust DevTools Alone
+
+DevTools device emulation is useful for layout but misses:
+- Actual touch interactions
+- Real CPU/memory constraints
+- Network latency patterns
+- Font rendering differences
+- Browser chrome/keyboard appearances
+
+**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
+
+---
+
+**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

package/template/agent/skills/frontend-design/reference/spatial-design.md

@@ -0,0 +1,122 @@
+# Spatial Design
+
+## Spacing Systems
+
+### Use 4pt Base, Not 8pt
+8pt systems are too coarse — you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+
+### Name Tokens Semantically
+Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing — it eliminates margin collapse and cleanup hacks.
+
+---
+
+## Grid Systems
+
+### The Self-Adjusting Grid
+Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch.
+
+For complex layouts, use named grid areas (`grid-template-areas`) and redefine them at breakpoints.
+
+---
+
+## Visual Hierarchy
+
+### The Squint Test
+Blur your eyes (or screenshot and blur). Can you still identify:
+- The most important element?
+- The second most important?
+- Clear groupings?
+
+If everything looks the same weight blurred, you have a hierarchy problem.
+
+### Hierarchy Through Multiple Dimensions
+Don't rely on size alone. Combine:
+
+| Tool | Strong Hierarchy | Weak Hierarchy |
+|------|------------------|----------------|
+| **Size** | 3:1 ratio or more | <2:1 ratio |
+| **Weight** | Bold vs Regular | Medium vs Regular |
+| **Color** | High contrast | Similar tones |
+| **Position** | Top/left (primary) | Bottom/right |
+| **Space** | Surrounded by white space | Crowded |
+
+**The best hierarchy uses 2–3 dimensions at once**: A heading that's larger, bolder, AND has more space above it.
+
+### Cards Are Not Required
+Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when:
+- Content is truly distinct and actionable
+- Items need visual comparison in a grid
+- Content needs clear interaction boundaries
+
+**Never nest cards inside cards** — use spacing, typography, and subtle dividers for hierarchy within a card.
+
+---
+
+## Container Queries
+
+Viewport queries are for page layouts. **Container queries are for components**:
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+
+.card {
+  display: grid;
+  gap: var(--space-md);
+}
+
+/* Card layout changes based on its container, not viewport */
+@container (min-width: 400px) {
+  .card {
+    grid-template-columns: 120px 1fr;
+  }
+}
+```
+
+**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands — automatically, without viewport hacks.
+
+---
+
+## Optical Adjustments
+
+- Text at `margin-left: 0` looks indented due to letterform whitespace — use negative margin (`-0.05em`) to optically align
+- Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction
+
+### Touch Targets vs Visual Size
+Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:
+
+```css
+.icon-button {
+  width: 24px;
+  height: 24px;
+  position: relative;
+}
+
+.icon-button::before {
+  content: '';
+  position: absolute;
+  inset: -10px;  /* Expand tap target to 44px */
+}
+```
+
+---
+
+## Depth & Elevation
+
+Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers.
+
+For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle — if you can clearly see it, it's probably too strong.
+
+```css
+:root {
+  --shadow-sm: 0 1px 2px oklch(0% 0 0 / 0.05);
+  --shadow-md: 0 4px 6px oklch(0% 0 0 / 0.07);
+  --shadow-lg: 0 10px 15px oklch(0% 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px oklch(0% 0 0 / 0.12);
+}
+```
+
+---
+
+**Avoid**: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone. Nesting cards in cards.

package/template/agent/skills/frontend-design/reference/typography.md

@@ -0,0 +1,124 @@
+# Typography
+
+## Classic Typography Principles
+
+### Vertical Rhythm
+Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony — text and space share a mathematical foundation.
+
+### Modular Scale & Hierarchy
+The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.
+
+**Use fewer sizes with more contrast.** A 5-size system covers most needs:
+
+| Role | Typical Ratio | Use Case |
+|------|---------------|----------|
+| xs | 0.75rem | Captions, legal |
+| sm | 0.875rem | Secondary UI, metadata |
+| base | 1rem | Body text |
+| lg | 1.25–1.5rem | Subheadings, lead text |
+| xl+ | 2–4rem | Headlines, hero text |
+
+Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
+
+### Readability & Measure
+Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length — narrow columns need tighter leading, wide columns need more.
+
+**Non-obvious**: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05–0.1 to your normal line-height.
+
+---
+
+## Font Selection & Pairing
+
+### Choosing Distinctive Fonts
+**Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal — but if you want distinctive design, look elsewhere.
+
+**Better Google Fonts alternatives**:
+- Instead of Inter → **Instrument Sans**, **Plus Jakarta Sans**, **Outfit**
+- Instead of Roboto → **Onest**, **Figtree**, **Urbanist**
+- Instead of Open Sans → **Source Sans 3**, **Nunito Sans**, **DM Sans**
+- For editorial/premium feel → **Fraunces**, **Newsreader**, **Lora**
+
+**System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider for apps where performance > personality.
+
+### Pairing Principles
+**The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces.
+
+When pairing, contrast on multiple axes:
+- Serif + Sans (structure contrast)
+- Geometric + Humanist (personality contrast)
+- Condensed display + Wide body (proportion contrast)
+
+**Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.
+
+### Web Font Loading
+The layout shift problem: fonts load late, text reflows, users see content jump. The fix:
+
+```css
+/* 1. Use font-display: swap for visibility */
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap;
+}
+
+/* 2. Match fallback metrics to minimize shift */
+@font-face {
+  font-family: 'CustomFont-Fallback';
+  src: local('Arial');
+  size-adjust: 105%;
+  ascent-override: 90%;
+  descent-override: 20%;
+  line-gap-override: 10%;
+}
+
+body {
+  font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
+}
+```
+
+---
+
+## Modern Web Typography
+
+### Fluid Type
+Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport.
+
+**Use fluid type for**: Headings and display text on marketing/content pages.
+**Use fixed `rem` scales for**: App UIs, dashboards, data-dense interfaces. Body text should also be fixed.
+
+### OpenType Features
+Use these for polish — most developers don't know they exist:
+
+```css
+/* Tabular numbers for data alignment */
+.data-table { font-variant-numeric: tabular-nums; }
+
+/* Proper fractions */
+.recipe-amount { font-variant-numeric: diagonal-fractions; }
+
+/* Small caps for abbreviations */
+abbr { font-variant-caps: all-small-caps; }
+
+/* Disable ligatures in code */
+code { font-variant-ligatures: none; }
+
+/* Enable kerning */
+body { font-kerning: normal; }
+```
+
+---
+
+## Typography System Architecture
+
+Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
+
+## Accessibility
+
+- **Never disable zoom**: `user-scalable=no` breaks accessibility
+- **Use rem/em for font sizes**: Respects user browser settings. Never `px` for body text
+- **Minimum 16px body text**: Smaller strains eyes and fails WCAG on mobile
+- **Adequate touch targets**: Text links need padding creating 44px+ tap targets
+
+---
+
+**Avoid**: More than 2–3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.

package/template/agent/skills/frontend-design/reference/ux-writing.md

@@ -0,0 +1,127 @@
+# UX Writing
+
+## The Button Label Problem
+
+**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
+
+| Bad | Good | Why |
+|-----|------|-----|
+| OK | Save changes | Says what will happen |
+| Submit | Create account | Outcome-focused |
+| Yes | Delete message | Confirms the action |
+| Cancel | Keep editing | Clarifies what "cancel" means |
+| Click here | Download PDF | Describes the destination |
+
+**For destructive actions**, name the destruction:
+- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
+- "Delete 5 items" not "Delete selected" (show the count)
+
+---
+
+## Error Messages: The Formula
+
+Every error should answer: (1) What happened? (2) Why? (3) How to fix it?
+
+- ✅ `"Email address isn't valid. Please include an @ symbol."`
+- ❌ `"Invalid input"`
+
+### Templates per Situation
+
+| Situation | Template |
+|-----------|----------|
+| **Format error** | "[Field] needs to be [format]. Example: [example]" |
+| **Missing required** | "Please enter [what's missing]" |
+| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
+| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
+| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
+
+### Don't Blame the User
+Reframe errors:
+- ✅ `"Please enter a date in MM/DD/YYYY format"`
+- ❌ `"You entered an invalid date"`
+
+---
+
+## Empty States Are Opportunities
+
+Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value, (3) Provide a clear action.
+
+- ✅ "No projects yet. Create your first one to get started."
+- ❌ "No items"
+
+---
+
+## Voice vs Tone
+
+**Voice** is your brand's personality — consistent everywhere.
+**Tone** adapts to the moment:
+
+| Moment | Tone Shift |
+|--------|------------|
+| Success | Celebratory, brief: "Done! Your changes are live." |
+| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
+| Loading | Reassuring: "Saving your work..." |
+| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
+
+**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
+
+---
+
+## Writing for Accessibility
+
+- **Link text** must have standalone meaning — "View pricing plans" not "Click here"
+- **Alt text** describes information, not the image — "Revenue increased 40% in Q4" not "Chart"
+- Use `alt=""` for decorative images
+- **Icon buttons** need `aria-label`
+
+---
+
+## Writing for Translation
+
+### Plan for Expansion
+
+| Language | Expansion |
+|----------|-----------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30–40% |
+| Chinese | −30% (fewer chars, same width) |
+
+### Translation-Friendly Patterns
+- Keep numbers separate ("New messages: 3" not "You have 3 new messages")
+- Use full sentences as single strings (word order varies by language)
+- Avoid abbreviations ("5 minutes ago" not "5 mins ago")
+- Give translators context about where strings appear
+
+---
+
+## Consistency: The Terminology Problem
+
+Pick one term and stick with it:
+
+| Inconsistent | Consistent |
+|--------------|------------|
+| Delete / Remove / Trash | Delete |
+| Settings / Preferences / Options | Settings |
+| Sign in / Log in / Enter | Sign in |
+| Create / Add / New | Create |
+
+Build a terminology glossary and enforce it. Variety creates confusion.
+
+---
+
+## Avoid Redundant Copy
+
+If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
+
+## Loading States
+
+Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
+
+## Confirmation Dialogs: Use Sparingly
+
+Most confirmation dialogs are design failures — **consider undo instead**. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
+
+---
+
+**Avoid**: Jargon without explanation. Blaming users ("Invalid input" → "Please include @"). Vague errors. Varying terminology for variety. Humor for error states.

package/template/agent/skills/mobile-uiux-promax/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: mobile-uiux-promax
+description: Use when designing or building mobile app UI for iOS, Android, React Native, Flutter, SwiftUI, or Jetpack Compose
+---
+
+# Mobile UI/UX Pro Max
+
+Data-grounded mobile design intelligence. Every design decision is backed by platform-authoritative data from Apple HIG, Material Design 3, and stack-specific best practices.
+
+## When to Activate
+
+Activate this skill when the request involves:
+- Designing any mobile screen, flow, or component
+- Reviewing mobile UI for platform-appropriateness
+- Choosing between navigation patterns for mobile apps
+- Implementing gesture-driven or haptic-rich interactions
+- Advising on iOS vs Android design conventions
+- Building onboarding flows or paywall timing
+- Animation and motion design for mobile
+
+## Workflow
+
+Run the 4-step search sequence from: `.agent/workflows/mobile-uiux-promax.md`
+
+**Read the workflow file before responding.** It contains the exact search commands to run.
+
+## Core Design Principles (Memorize These)
+
+### 1. Platform-First, Not Platform-Only
+- Follow platform conventions by default
+- Deviate only when there's clear UX benefit to users
+- Cross-platform apps must feel native on each platform, not identical
+- iOS users expect swipe-back + tab bar at bottom; Android users expect system back + nav structure
+
+### 2. Thumb Zone Above All
+- Primary actions belong in the bottom 60% of the screen
+- Top-left corner = hardest to reach one-handed
+- Platform back buttons (iOS top-left) are the only justified exception
+
+### 3. Gesture + Haptic + Visual = One Interaction
+- Every interaction should engage all three senses when appropriate
+- Swipe reveals → haptic at threshold + visual action button
+- Toggle → haptic on state change + visual state update simultaneously
+- Pull-to-refresh → haptic on trigger + spinner animation + announce to screen readers
+
+### 4. Accessibility Is Not Optional
+- Minimum touch target: 44pt (iOS) / 48dp (Android)
+- Every tappable element without visible text needs `accessibilityLabel`
+- Every gesture needs an accessible alternative action
+- Test with VoiceOver (iOS) and TalkBack (Android) before shipping
+- Support Dynamic Type / sp font scaling (never lock font size)
+
+### 5. Reduce Motion Is a Hard Requirement
+- Check `UIAccessibility.isReduceMotionEnabled` (iOS) and `LocalReduceMotion` (Compose) everywhere you animate
+- Replace slides with fades; replace springs with eases; reduce or eliminate particle effects
+- Haptics are NOT animation — keep them even when reducing motion
+
+### 6. Safe Area = Non-Negotiable
+- Never hardcode padding for device-specific areas
+- Always use `safeAreaInsets` / `SafeAreaView` / `WindowInsets` APIs
+- Test on iPhone SE (small), iPhone 14 Pro (Dynamic Island), and latest iPad
+
+## Pre-Delivery Checklist
+
+Before presenting any design decision, implementation, or code:
+
+**Layout & Ergonomics**
+- [ ] Touch targets ≥ 44pt / 48dp everywhere
+- [ ] Safe area insets respected on all edges
+- [ ] Primary actions in thumb-reachable zone (bottom 60%)
+- [ ] Content not hidden behind notch / Dynamic Island / home indicator
+- [ ] Keyboard avoidance implemented for any screen with text inputs
+
+**Platform Conventions**
+- [ ] Back navigation: iOS swipe-back enabled + button; Android system back handled
+- [ ] Navigation pattern matches platform idiom (tab bar on iOS; nav bar or drawer on Android)
+- [ ] Status bar style contrasts with content behind it
+- [ ] Haptic feedback added for primary interactions (where hardware supports)
+
+**Accessibility**
+- [ ] VoiceOver/TalkBack labels on all interactive elements
+- [ ] Heading traits applied to screen titles and section headers
+- [ ] Custom gesture actions available via accessibility Actions menu
+- [ ] Dynamic Type / sp units used (no fixed font sizes)
+- [ ] Color contrast ≥ 4.5:1 for body text; ≥ 3:1 for large text / UI
+- [ ] Color information supplemented with shape/icon/text
+
+**Motion**
+- [ ] `reduceMotion` check before every animation
+- [ ] Animation duration appropriate (200-400ms for most; <200ms for micro)
+- [ ] Spring used for natural feel on expand/appear; ease-out for dismiss/collapse
+
+**Dark Mode**
+- [ ] All colors defined as adaptive (no hardcoded hex for any UI color)
+- [ ] Test on OLED (true black matters for pure black backgrounds)
+- [ ] Images and media contrast tested in both appearances
+
+## Stack-Specific Reminders
+
+### React Native
+- Use `react-native-safe-area-context` not built-in SafeAreaView
+- Use `react-native-reanimated` for gesture-driven animations
+- Use `react-native-gesture-handler` for complex touch interactions
+- FlatList not ScrollView for lists with 20+ items
+- `useNativeDriver: true` on every `Animated.timing()`
+
+### Flutter
+- `ListView.builder` not `Column + ForEach` for long lists
+- `const` constructors everywhere possible
+- `GoRouter` for navigation with deep link support
+- `Riverpod` for state management
+- `cached_network_image` for network images
+
+### SwiftUI
+- `NavigationStack` not deprecated `NavigationView` (iOS 16+)
+- `@StateObject` not `@ObservedObject` for own ViewModels
+- `LazyVStack` not `VStack` for long lists
+- `matchedGeometryEffect` for hero-like shared element transitions
+- `@Environment(\.accessibilityReduceMotion)` before any animation
+
+### Jetpack Compose
+- `LazyColumn` with `key = { it.id }` for lists
+- `derivedStateOf` for computed state values
+- `StatefulShellRoute` for tab persistence in GoRouter
+- `collectAsStateWithLifecycle()` in all state collection
+- `WindowCompat.setDecorFitsSystemWindows(window, false)` for edge-to-edge
+
+## Key Data Sources Baked Into Database
+
+| Domain | Authority |
+|--------|-----------|
+| iOS conventions | Apple Human Interface Guidelines |
+| Android conventions | Material Design 3 |
+| React Native patterns | React Navigation docs + RN official docs |
+| Flutter patterns | Flutter official docs + pub.dev best packages |
+| SwiftUI patterns | Apple developer documentation |
+| Compose patterns | Android Jetpack documentation |
+| Accessibility | WCAG 2.1 + iOS Accessibility + Android Accessibility |
+| Animation timing | Platform-standard specs (iOS spring / MD3 motion) |

package/template/agent/skills/using-git-worktrees/SKILL.md

@@ -63,7 +63,9 @@ git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/d
 
 Per Jesse's rule "Fix broken things immediately":
 1. Add appropriate line to .gitignore
-2. Commit the change
+2. Commit the change (if auto_commit enabled)
+   - Read `.agent/config.yml` — if `auto_commit: false`: skip commit, print "Skipping git operation (auto_commit: false)."
+   - If `auto_commit: true` (or absent): `git add .gitignore && git commit -m "chore: ignore worktree directory"`
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.