add git-workflow-and-versioning and shipping-and-launch skills

Ship phase skills covering atomic commits, branch strategy, pre-launch checklists, and staged rollout procedures. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-08-12 18:07:26 +02:00 · 2026-02-15 14:36:47 -08:00
parent 46f377adde
commit 9434558fd4
2 changed files with 562 additions and 0 deletions
@@ -0,0 +1,270 @@
+---
+name: git-workflow-and-versioning
+description: Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.
+---
+
+# Git Workflow and Versioning
+
+## Overview
+
+Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation. With AI agents generating code at high speed, disciplined version control is the mechanism that keeps changes manageable, reviewable, and reversible.
+
+## When to Use
+
+Always. Every code change flows through git.
+
+## Core Principles
+
+### 1. Commit Early, Commit Often
+
+Each successful increment gets its own commit. Don't accumulate large uncommitted changes.
+
+```
+Work pattern:
+  Implement slice → Test → Verify → Commit → Next slice
+
+Not this:
+  Implement everything → Hope it works → Giant commit
+```
+
+Commits are save points. If the next change breaks something, you can revert to the last known-good state instantly.
+
+### 2. Atomic Commits
+
+Each commit does one logical thing:
+
+```
+# Good: Each commit is self-contained
+git log --oneline
+a1b2c3d Add task creation endpoint with validation
+d4e5f6g Add task creation form component
+h7i8j9k Connect form to API and add loading state
+m1n2o3p Add task creation tests (unit + integration)
+
+# Bad: Everything mixed together
+git log --oneline
+x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
+```
+
+### 3. Descriptive Messages
+
+Commit messages explain the *why*, not just the *what*:
+
+```
+# Good: Explains intent
+feat: add email validation to registration endpoint
+
+Prevents invalid email formats from reaching the database.
+Uses Zod schema validation at the route handler level,
+consistent with existing validation patterns in auth.ts.
+
+# Bad: Describes what's obvious from the diff
+update auth.ts
+```
+
+**Format:**
+```
+<type>: <short description>
+
+<optional body explaining why, not what>
+```
+
+**Types:**
+- `feat` — New feature
+- `fix` — Bug fix
+- `refactor` — Code change that neither fixes a bug nor adds a feature
+- `test` — Adding or updating tests
+- `docs` — Documentation only
+- `chore` — Tooling, dependencies, config
+
+### 4. Never Mix Concerns
+
+Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit:
+
+```
+# Good: Separate concerns
+git commit -m "refactor: extract validation logic to shared utility"
+git commit -m "feat: add phone number validation to registration"
+
+# Bad: Mixed concerns
+git commit -m "refactor validation and add phone number field"
+```
+
+## Branching Strategy
+
+### Feature Branches
+
+```
+main (always deployable)
+  │
+  ├── feature/task-creation    ← One feature per branch
+  ├── feature/user-settings    ← Parallel work
+  └── fix/duplicate-tasks      ← Bug fixes
+```
+
+- Branch from `main` (or the team's default branch)
+- Keep branches short-lived (merge within 1-3 days)
+- Delete branches after merge
+
+### Branch Naming
+
+```
+feature/<short-description>   → feature/task-creation
+fix/<short-description>       → fix/duplicate-tasks
+chore/<short-description>     → chore/update-deps
+refactor/<short-description>  → refactor/auth-module
+```
+
+## Working with Worktrees
+
+For parallel AI agent work, use git worktrees to run multiple branches simultaneously:
+
+```bash
+# Create a worktree for a feature branch
+git worktree add ../project-feature-a feature/task-creation
+git worktree add ../project-feature-b feature/user-settings
+
+# Each worktree is a separate directory with its own branch
+# Agents can work in parallel without interfering
+ls ../
+  project/              ← main branch
+  project-feature-a/    ← task-creation branch
+  project-feature-b/    ← user-settings branch
+
+# When done, merge and clean up
+git worktree remove ../project-feature-a
+```
+
+Benefits:
+- Multiple agents can work on different features simultaneously
+- No branch switching needed (each directory has its own branch)
+- If one experiment fails, delete the worktree — nothing is lost
+- Changes are isolated until explicitly merged
+
+## The Save Point Pattern
+
+```
+Agent starts work
+    │
+    ├── Makes a change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    ├── Makes another change
+    │   ├── Test passes? → Commit → Continue
+    │   └── Test fails? → Revert to last commit → Investigate
+    │
+    └── Feature complete → All commits form a clean history
+```
+
+This pattern means you never lose more than one increment of work. If an agent goes off the rails, `git reset --hard HEAD` takes you back to the last successful state.
+
+## Change Summaries
+
+After any modification, provide a structured summary. This makes review easier, documents scope discipline, and surfaces unintended changes:
+
+```
+CHANGES MADE:
+- src/routes/tasks.ts: Added validation middleware to POST endpoint
+- src/lib/validation.ts: Added TaskCreateSchema using Zod
+
+THINGS I DIDN'T TOUCH (intentionally):
+- src/routes/auth.ts: Has similar validation gap but out of scope
+- src/middleware/error.ts: Error format could be improved (separate task)
+
+POTENTIAL CONCERNS:
+- The Zod schema is strict — rejects extra fields. Confirm this is desired.
+- Added zod as a dependency (72KB gzipped) — already in package.json
+```
+
+This pattern catches wrong assumptions early and gives reviewers a clear map of the change. The "DIDN'T TOUCH" section is especially important — it shows you exercised scope discipline and didn't go on an unsolicited renovation.
+
+## Pre-Commit Hygiene
+
+Before every commit:
+
+```bash
+# 1. Check what you're about to commit
+git diff --staged
+
+# 2. Ensure no secrets
+git diff --staged | grep -i "password\|secret\|api_key\|token"
+
+# 3. Run tests
+npm test
+
+# 4. Run linting
+npm run lint
+
+# 5. Run type checking
+npx tsc --noEmit
+```
+
+Automate this with git hooks:
+
+```json
+// package.json (using lint-staged + husky)
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md}": ["prettier --write"]
+  }
+}
+```
+
+## Handling Generated Files
+
+- **Commit generated files** only if the project expects them (e.g., `package-lock.json`, Prisma migrations)
+- **Don't commit** build output (`dist/`, `.next/`), environment files (`.env`), or IDE config (`.vscode/settings.json` unless shared)
+- **Always have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem`
+
+## Using Git for Debugging
+
+```bash
+# Find which commit introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-commit>
+# Git checkouts midpoints; run your test at each to narrow down
+
+# View what changed recently
+git log --oneline -20
+git diff HEAD~5..HEAD -- src/
+
+# Find who last changed a specific line
+git blame src/services/task.ts
+
+# Search commit messages for a keyword
+git log --grep="validation" --oneline
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll commit when the feature is done" | One giant commit is impossible to review, debug, or revert. Commit each slice. |
+| "The message doesn't matter" | Messages are documentation. Future you (and future agents) will need to understand what changed and why. |
+| "I'll squash it all later" | Squashing destroys the development narrative. Prefer clean incremental commits from the start. |
+| "Branches add overhead" | Branches are free and prevent conflicting work from colliding. Use them. |
+| "I don't need a .gitignore" | Until `.env` with production secrets gets committed. Set it up immediately. |
+
+## Red Flags
+
+- Large uncommitted changes accumulating
+- Commit messages like "fix", "update", "misc"
+- Formatting changes mixed with behavior changes
+- No `.gitignore` in the project
+- Committing `node_modules/`, `.env`, or build artifacts
+- Long-lived branches that diverge significantly from main
+- Force-pushing to shared branches
+
+## Verification
+
+For every commit:
+
+- [ ] Commit does one logical thing
+- [ ] Message explains the why, follows type conventions
+- [ ] Tests pass before committing
+- [ ] No secrets in the diff
+- [ ] No formatting-only changes mixed with behavior changes
+- [ ] `.gitignore` covers standard exclusions
@@ -0,0 +1,292 @@
+---
+name: shipping-and-launch
+description: Use when preparing to deploy to production. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.
+---
+
+# Shipping and Launch
+
+## Overview
+
+Ship with confidence. The goal is not just to deploy — it's to deploy safely, with monitoring in place, a rollback plan ready, and a clear understanding of what success looks like. Every launch should be reversible, observable, and incremental.
+
+## When to Use
+
+- Deploying a feature to production for the first time
+- Releasing a significant change to users
+- Migrating data or infrastructure
+- Opening a beta or early access program
+- Any deployment that carries risk (all of them)
+
+## The Pre-Launch Checklist
+
+### Code Quality
+
+- [ ] All tests pass (unit, integration, e2e)
+- [ ] Build succeeds with no warnings
+- [ ] Lint and type checking pass
+- [ ] Code reviewed and approved
+- [ ] No TODO comments that should be resolved before launch
+- [ ] No `console.log` debugging statements in production code
+- [ ] Error handling covers expected failure modes
+
+### Security
+
+- [ ] No secrets in code or version control
+- [ ] `npm audit` shows no critical or high vulnerabilities
+- [ ] Input validation on all user-facing endpoints
+- [ ] Authentication and authorization checks in place
+- [ ] Security headers configured (CSP, HSTS, etc.)
+- [ ] Rate limiting on authentication endpoints
+- [ ] CORS configured to specific origins (not wildcard)
+
+### Performance
+
+- [ ] Core Web Vitals within "Good" thresholds
+- [ ] No N+1 queries in critical paths
+- [ ] Images optimized (compression, responsive sizes, lazy loading)
+- [ ] Bundle size within budget
+- [ ] Database queries have appropriate indexes
+- [ ] Caching configured for static assets and repeated queries
+
+### Accessibility
+
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Screen reader can convey page content and structure
+- [ ] Color contrast meets WCAG 2.1 AA (4.5:1 for text)
+- [ ] Focus management correct for modals and dynamic content
+- [ ] Error messages are descriptive and associated with form fields
+- [ ] No accessibility warnings in axe-core or Lighthouse
+
+### Infrastructure
+
+- [ ] Environment variables set in production
+- [ ] Database migrations applied (or ready to apply)
+- [ ] DNS and SSL configured
+- [ ] CDN configured for static assets
+- [ ] Logging and error reporting configured
+- [ ] Health check endpoint exists and responds
+
+### Documentation
+
+- [ ] README updated with any new setup requirements
+- [ ] API documentation current
+- [ ] ADRs written for any architectural decisions
+- [ ] Changelog updated
+- [ ] User-facing documentation updated (if applicable)
+
+## Feature Flag Strategy
+
+Ship behind feature flags to decouple deployment from release:
+
+```typescript
+// Feature flag check
+const flags = await getFeatureFlags(userId);
+
+if (flags.taskSharing) {
+  // New feature: task sharing
+  return <TaskSharingPanel task={task} />;
+}
+
+// Default: existing behavior
+return null;
+```
+
+**Feature flag lifecycle:**
+
+```
+1. DEPLOY with flag OFF     → Code is in production but inactive
+2. ENABLE for team/beta     → Internal testing in production environment
+3. GRADUAL ROLLOUT          → 5% → 25% → 50% → 100% of users
+4. MONITOR at each stage    → Watch error rates, performance, user feedback
+5. CLEAN UP                 → Remove flag and dead code path after full rollout
+```
+
+**Rules:**
+- Every feature flag has an owner and an expiration date
+- Clean up flags within 2 weeks of full rollout
+- Don't nest feature flags (creates exponential combinations)
+- Test both flag states (on and off) in CI
+
+## Staged Rollout
+
+### The Rollout Sequence
+
+```
+1. DEPLOY to staging
+   └── Full test suite in staging environment
+   └── Manual smoke test of critical flows
+
+2. DEPLOY to production (feature flag OFF)
+   └── Verify deployment succeeded (health check)
+   └── Check error monitoring (no new errors)
+
+3. ENABLE for team (flag ON for internal users)
+   └── Team uses the feature in production
+   └── 24-hour monitoring window
+
+4. CANARY rollout (flag ON for 5% of users)
+   └── Monitor error rates, latency, user behavior
+   └── Compare metrics: canary vs. baseline
+   └── 24-48 hour monitoring window
+
+5. GRADUAL increase (25% → 50% → 100%)
+   └── Same monitoring at each step
+   └── Ability to roll back to previous percentage at any point
+
+6. FULL rollout (flag ON for all users)
+   └── Monitor for 1 week
+   └── Clean up feature flag
+```
+
+### When to Roll Back
+
+Roll back immediately if:
+- Error rate increases by more than 2x baseline
+- P95 latency increases by more than 50%
+- User-reported issues spike
+- Data integrity issues detected
+- Security vulnerability discovered
+
+## Monitoring and Observability
+
+### What to Monitor
+
+```
+Application metrics:
+├── Error rate (total and by endpoint)
+├── Response time (p50, p95, p99)
+├── Request volume
+├── Active users
+└── Key business metrics (conversion, engagement)
+
+Infrastructure metrics:
+├── CPU and memory utilization
+├── Database connection pool usage
+├── Disk space
+├── Network latency
+└── Queue depth (if applicable)
+
+Client metrics:
+├── Core Web Vitals (LCP, INP, CLS)
+├── JavaScript errors
+├── API error rates from client perspective
+└── Page load time
+```
+
+### Error Reporting
+
+```typescript
+// Set up error boundary with reporting
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    // Report to error tracking service
+    reportError(error, {
+      componentStack: info.componentStack,
+      userId: getCurrentUser()?.id,
+      page: window.location.pathname,
+    });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
+    }
+    return this.props.children;
+  }
+}
+
+// Server-side error reporting
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  reportError(err, {
+    method: req.method,
+    url: req.url,
+    userId: req.user?.id,
+  });
+
+  // Don't expose internals to users
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  });
+});
+```
+
+### Post-Launch Verification
+
+In the first hour after launch:
+
+```
+1. Check health endpoint returns 200
+2. Check error monitoring dashboard (no new error types)
+3. Check latency dashboard (no regression)
+4. Test the critical user flow manually
+5. Verify logs are flowing and readable
+6. Confirm rollback mechanism works (dry run if possible)
+```
+
+## Rollback Strategy
+
+Every deployment needs a rollback plan before it happens:
+
+```markdown
+## Rollback Plan for [Feature/Release]
+
+### Trigger Conditions
+- Error rate > 2x baseline
+- P95 latency > [X]ms
+- User reports of [specific issue]
+
+### Rollback Steps
+1. Disable feature flag (if applicable)
+   OR
+1. Deploy previous version: `git revert <commit> && git push`
+2. Verify rollback: health check, error monitoring
+3. Communicate: notify team of rollback
+
+### Database Considerations
+- Migration [X] has a rollback: `npx prisma migrate rollback`
+- Data inserted by new feature: [preserved / cleaned up]
+
+### Time to Rollback
+- Feature flag: < 1 minute
+- Redeploy previous version: < 5 minutes
+- Database rollback: < 15 minutes
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It works in staging, it'll work in production" | Production has different data, traffic patterns, and edge cases. Monitor after deploy. |
+| "We don't need feature flags for this" | Every feature benefits from a kill switch. Even "simple" changes can break things. |
+| "Monitoring is overhead" | Not having monitoring means you discover problems from user complaints instead of dashboards. |
+| "We'll add monitoring later" | Add it before launch. You can't debug what you can't see. |
+| "Rolling back is admitting failure" | Rolling back is responsible engineering. Shipping a broken feature is the failure. |
+
+## Red Flags
+
+- Deploying without a rollback plan
+- No monitoring or error reporting in production
+- Big-bang releases (everything at once, no staging)
+- Feature flags with no expiration or owner
+- No one monitoring the deploy for the first hour
+- Production environment configuration done by memory, not code
+- "It's Friday afternoon, let's ship it"
+
+## Verification
+
+Before deploying:
+
+- [ ] Pre-launch checklist completed (all sections green)
+- [ ] Feature flag configured (if applicable)
+- [ ] Rollback plan documented
+- [ ] Monitoring dashboards set up
+- [ ] Team notified of deployment
+
+After deploying:
+
+- [ ] Health check returns 200
+- [ ] Error rate is normal
+- [ ] Latency is normal
+- [ ] Critical user flow works
+- [ ] Logs are flowing
+- [ ] Rollback tested or verified ready