@oyolincc/create 0.5.0 → 0.5.1

package/templates/hono-fullstack/.agents/skills/ship-ci-cd-and-automation/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: ship-ci-cd-and-automation
+description: Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.
+---
+
+# CI/CD and Automation
+
+## Overview
+
+Automate quality gates so that no change reaches production without passing tests, lint, type checking, and build. CI/CD is the enforcement mechanism for every other skill — it catches what humans and agents miss, and it does so consistently on every single change.
+
+**Shift Left:** Catch problems as early in the pipeline as possible. A bug caught in linting costs minutes; the same bug caught in production costs hours. Move checks upstream — static analysis before tests, tests before staging, staging before production.
+
+**Faster is Safer:** Smaller batches and more frequent releases reduce risk, not increase it. A deployment with 3 changes is easier to debug than one with 30. Frequent releases build confidence in the release process itself.
+
+## When to Use
+
+- Setting up a new project's CI pipeline
+- Adding or modifying automated checks
+- Configuring deployment pipelines
+- When a change should trigger automated verification
+- Debugging CI failures
+
+## The Quality Gate Pipeline
+
+Every change goes through these gates before merge:
+
+```
+Pull Request Opened
+    │
+    ▼
+┌─────────────────┐
+│   LINT CHECK     │  eslint, prettier
+│   ↓ pass         │
+│   TYPE CHECK     │  tsc --noEmit
+│   ↓ pass         │
+│   UNIT TESTS     │  jest/vitest
+│   ↓ pass         │
+│   BUILD          │  npm run build
+│   ↓ pass         │
+│   INTEGRATION    │  API/DB tests
+│   ↓ pass         │
+│   E2E (optional) │  Playwright/Cypress
+│   ↓ pass         │
+│   SECURITY AUDIT │  npm audit
+│   ↓ pass         │
+│   BUNDLE SIZE    │  bundlesize check
+└─────────────────┘
+    │
+    ▼
+  Ready for review
+```
+
+**No gate can be skipped.** If lint fails, fix lint — don't disable the rule. If a test fails, fix the code — don't skip the test.
+
+## GitHub Actions Configuration
+
+### Basic CI Pipeline
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npm test -- --coverage
+
+      - name: Build
+        run: npm run build
+
+      - name: Security audit
+        run: npm audit --audit-level=high
+```
+
+### With Database Integration Tests
+
+```yaml
+  integration:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: testdb
+          POSTGRES_USER: ci_user
+          POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - name: Run migrations
+        run: npx prisma migrate deploy
+        env:
+          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
+      - name: Integration tests
+        run: npm run test:integration
+        env:
+          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
+```
+
+> **Note:** Even for CI-only test databases, use GitHub Secrets for credentials rather than hardcoding values. This builds good habits and prevents accidental reuse of test credentials in other contexts.
+
+### E2E Tests
+
+```yaml
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+      - name: Build
+        run: npm run build
+      - name: Run E2E tests
+        run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+## Feeding CI Failures Back to Agents
+
+The power of CI with AI agents is the feedback loop. When CI fails:
+
+```
+CI fails
+    │
+    ▼
+Copy the failure output
+    │
+    ▼
+Feed it to the agent:
+"The CI pipeline failed with this error:
+[paste specific error]
+Fix the issue and verify locally before pushing again."
+    │
+    ▼
+Agent fixes → pushes → CI runs again
+```
+
+**Key patterns:**
+
+```
+Lint failure → Agent runs `npm run lint -- --fix` and commits
+Type error  → Agent reads the error location and fixes the type
+Test failure → Agent follows test-debugging-and-error-recovery skill
+Build error → Agent checks config and dependencies
+```
+
+## Deployment Strategies
+
+### Preview Deployments
+
+Every PR gets a preview deployment for manual testing:
+
+```yaml
+# Deploy preview on PR (Vercel/Netlify/etc.)
+deploy-preview:
+  runs-on: ubuntu-latest
+  if: github.event_name == 'pull_request'
+  steps:
+    - uses: actions/checkout@v4
+    - name: Deploy preview
+      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}
+```
+
+### Feature Flags
+
+Feature flags decouple deployment from release. Deploy incomplete or risky features behind flags so you can:
+
+- **Ship code without enabling it.** Merge to main early, enable when ready.
+- **Roll back without redeploying.** Disable the flag instead of reverting code.
+- **Canary new features.** Enable for 1% of users, then 10%, then 100%.
+- **Run A/B tests.** Compare behavior with and without the feature.
+
+```typescript
+// Simple feature flag pattern
+if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
+  return renderNewCheckout();
+}
+return renderLegacyCheckout();
+```
+
+**Flag lifecycle:** Create → Enable for testing → Canary → Full rollout → Remove the flag and dead code. Flags that live forever become technical debt — set a cleanup date when you create them.
+
+### Staged Rollouts
+
+```
+PR merged to main
+    │
+    ▼
+  Staging deployment (auto)
+    │ Manual verification
+    ▼
+  Production deployment (manual trigger or auto after staging)
+    │
+    ▼
+  Monitor for errors (15-minute window)
+    │
+    ├── Errors detected → Rollback
+    └── Clean → Done
+```
+
+### Rollback Plan
+
+Every deployment should be reversible:
+
+```yaml
+# Manual rollback workflow
+name: Rollback
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to rollback to'
+        required: true
+
+jobs:
+  rollback:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Rollback deployment
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          # Deploy the specified previous version. Pass the input through env,
+          # never interpolate it into the script (shell injection).
+          npx vercel rollback "$VERSION"
+```
+
+## Environment Management
+
+```
+.env.example       → Committed (template for developers)
+.env                → NOT committed (local development)
+.env.test           → Committed (test environment, no real secrets)
+CI secrets          → Stored in GitHub Secrets / vault
+Production secrets  → Stored in deployment platform / vault
+```
+
+CI should never have production secrets. Use separate secrets for CI testing.
+
+## Automation Beyond CI
+
+### Dependabot / Renovate
+
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+```
+
+### Build Cop Role
+
+Designate someone responsible for keeping CI green. When the build breaks, the Build Cop's job is to fix or revert — not the person whose change caused the break. This prevents broken builds from accumulating while everyone assumes someone else will fix it.
+
+### PR Checks
+
+- **Required reviews:** At least 1 approval before merge
+- **Required status checks:** CI must pass before merge
+- **Branch protection:** No force-pushes to main
+- **Auto-merge:** If all checks pass and approved, merge automatically
+
+## CI Optimization
+
+When the pipeline exceeds 10 minutes, apply these strategies in order of impact:
+
+```
+Slow CI pipeline?
+├── Cache dependencies
+│   └── Use the setup-node cache option (or actions/cache) for the package manager cache, not node_modules
+├── Run jobs in parallel
+│   └── Split lint, typecheck, test, build into separate parallel jobs
+├── Only run what changed
+│   └── Use path filters to skip unrelated jobs (e.g., skip e2e for docs-only PRs)
+├── Use matrix builds
+│   └── Shard test suites across multiple runners
+├── Optimize the test suite
+│   └── Remove slow tests from the critical path, run them on a schedule instead
+└── Use larger runners
+    └── GitHub-hosted larger runners or self-hosted for CPU-heavy builds
+```
+
+**Example: caching and parallelism**
+```yaml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm' }
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm' }
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm' }
+      - run: npm ci
+      - run: npm test -- --coverage
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "CI is too slow" | Optimize the pipeline (see CI Optimization below), don't skip it. A 5-minute pipeline prevents hours of debugging. |
+| "This change is trivial, skip CI" | Trivial changes break builds. CI is fast for trivial changes anyway. |
+| "The test is flaky, just re-run" | Flaky tests mask real bugs and waste everyone's time. Fix the flakiness. |
+| "We'll add CI later" | Projects without CI accumulate broken states. Set it up on day one. |
+| "Manual testing is enough" | Manual testing doesn't scale and isn't repeatable. Automate what you can. |
+
+## Red Flags
+
+- No CI pipeline in the project
+- CI failures ignored or silenced
+- Tests disabled in CI to make the pipeline pass
+- Production deploys without staging verification
+- No rollback mechanism
+- Secrets stored in code or CI config files (not secrets manager)
+- Long CI times with no optimization effort
+
+## Verification
+
+After setting up or modifying CI:
+
+- [ ] All quality gates are present (lint, types, tests, build, audit)
+- [ ] Pipeline runs on every PR and push to main
+- [ ] Failures block merge (branch protection configured)
+- [ ] CI results feed back into the development loop
+- [ ] Secrets are stored in the secrets manager, not in code
+- [ ] Deployment has a rollback mechanism
+- [ ] Pipeline runs in under 10 minutes for the test suite

package/templates/hono-fullstack/.agents/skills/ship-deprecation-and-migration/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: ship-deprecation-and-migration
+description: Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.
+---
+
+# Deprecation and Migration
+
+## Overview
+
+Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new.
+
+Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.
+
+## When to Use
+
+- Replacing an old system, API, or library with a new one
+- Sunsetting a feature that's no longer needed
+- Consolidating duplicate implementations
+- Removing dead code that nobody owns but everybody depends on
+- Planning the lifecycle of a new system (deprecation planning starts at design time)
+- Deciding whether to maintain a legacy system or invest in migration
+
+## Core Principles
+
+### Code Is a Liability
+
+Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
+
+### Hyrum's Law Makes Removal Hard
+
+With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.
+
+### Deprecation Planning Starts at Design Time
+
+When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.
+
+## The Deprecation Decision
+
+Before deprecating anything, answer these questions:
+
+```
+1. Does this system still provide unique value?
+   → If yes, maintain it. If no, proceed.
+
+2. How many users/consumers depend on it?
+   → Quantify the migration scope.
+
+3. Does a replacement exist?
+   → If no, build the replacement first. Don't deprecate without an alternative.
+
+4. What's the migration cost for each consumer?
+   → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
+
+5. What's the ongoing maintenance cost of NOT deprecating?
+   → Security risk, engineer time, opportunity cost of complexity.
+```
+
+## Compulsory vs Advisory Deprecation
+
+| Type | When to Use | Mechanism |
+|------|-------------|-----------|
+| **Advisory** | Migration is optional, old system is stable | Warnings, documentation, nudges. Users migrate on their own timeline. |
+| **Compulsory** | Old system has security issues, blocks progress, or maintenance cost is unsustainable | Hard deadline. Old system will be removed by date X. Provide migration tooling. |
+
+**Default to advisory.** Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.
+
+## The Migration Process
+
+### Step 1: Build the Replacement
+
+Don't deprecate without a working alternative. The replacement must:
+
+- Cover all critical use cases of the old system
+- Have documentation and migration guides
+- Be proven in production (not just "theoretically better")
+
+### Step 2: Announce and Document
+
+```markdown
+## Deprecation Notice: OldService
+
+**Status:** Deprecated as of 2025-03-01
+**Replacement:** NewService (see migration guide below)
+**Removal date:** Advisory — no hard deadline yet
+**Reason:** OldService requires manual scaling and lacks observability.
+            NewService handles both automatically.
+
+### Migration Guide
+1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
+2. Update configuration (see examples below)
+3. Run the migration verification script: `npx migrate-check`
+```
+
+### Step 3: Migrate Incrementally
+
+Migrate consumers one at a time, not all at once. For each consumer:
+
+```
+1. Identify all touchpoints with the deprecated system
+2. Update to use the replacement
+3. Verify behavior matches (tests, integration checks)
+4. Remove references to the old system
+5. Confirm no regressions
+```
+
+**The Churn Rule:** If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.
+
+### Step 4: Remove the Old System
+
+Only after all consumers have migrated:
+
+```
+1. Verify zero active usage (metrics, logs, dependency analysis)
+2. Remove the code
+3. Remove associated tests, documentation, and configuration
+4. Remove the deprecation notices
+5. Celebrate — removing code is an achievement
+```
+
+## Migration Patterns
+
+### Strangler Pattern
+
+Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.
+
+```
+Phase 1: New system handles 0%, old handles 100%
+Phase 2: New system handles 10% (canary)
+Phase 3: New system handles 50%
+Phase 4: New system handles 100%, old system idle
+Phase 5: Remove old system
+```
+
+### Adapter Pattern
+
+Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.
+
+```typescript
+// Adapter: old interface, new implementation
+class LegacyTaskService implements OldTaskAPI {
+  constructor(private newService: NewTaskService) {}
+
+  // Old method signature, delegates to new implementation
+  getTask(id: number): OldTask {
+    const task = this.newService.findById(String(id));
+    return this.toOldFormat(task);
+  }
+
+  // Translate the new shape back into what old consumers expect
+  private toOldFormat(task: Task): OldTask {
+    return { id: Number(task.id), title: task.title, done: task.status === 'done' };
+  }
+}
+```
+
+### Feature Flag Migration
+
+Use feature flags to switch consumers from old to new system one at a time:
+
+```typescript
+function getTaskService(userId: string): TaskService {
+  if (featureFlags.isEnabled('new-task-service', { userId })) {
+    return new NewTaskService();
+  }
+  return new OldTaskService();
+}
+```
+
+### Database Schema Migrations (Expand/Contract)
+
+A schema change is the riskiest migration because the data is the one thing you cannot roll back by reverting a deploy. The failure mode is coupling the schema change to the code change: rename a column in the same release that starts using the new name, and during the rollout window — when old and new code run at once — one of them is querying a column that doesn't exist. The fix is to **never change a column in place**. Migrate in additive phases so old and new code are both valid at every step.
+
+```
+EXPAND ──────────────→ MIGRATE ──────────────→ CONTRACT
+add the new column,    backfill existing rows,  once no code reads the
+nullable, alongside    dual-write old+new from  old column, drop it in
+the old one            the app                  a later, separate deploy
+```
+
+**Worked example — renaming `name` to `full_name`:**
+
+1. **Expand.** Add `full_name` as nullable. Deploy. (Old code ignores it; nothing breaks.)
+2. **Dual-write.** App writes both `name` and `full_name` on every insert/update. Deploy.
+3. **Backfill.** Copy `name → full_name` for existing rows, in batches, so you don't lock the table.
+4. **Switch reads.** Point the app at `full_name`, keep writing both. Deploy and bake.
+5. **Contract.** Stop writing `name`, then — in a *separate, later* deploy — drop the column.
+
+Each step is independently deployable and reversible: if step 4 misbehaves, roll the code back and `full_name` is still being populated. Treat each phase as a thin vertical slice — see the `build-incremental-implementation` skill.
+
+**Rules:**
+- **Additive first, destructive last and alone.** Adds (new nullable column, new table, new index) are safe in any deploy; drops and renames get their own deploy *after* no code references the old shape.
+- **Every migration has a tested down path.** A migration you can't reverse is a deploy you can't roll back. Write and run the `down` before merging.
+- **Backfill in batches, off the hot path.** A single `UPDATE` over millions of rows locks the table; chunk it and throttle.
+- **Build large indexes without blocking writes** (e.g. Postgres `CREATE INDEX CONCURRENTLY`).
+- **Decouple from code by feature flag** when the cutover is risky, exactly as in the Feature Flag Migration pattern above.
+
+## Zombie Code
+
+Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:
+
+- No commits in 6+ months but active consumers exist
+- No assigned maintainer or team
+- Failing tests that nobody fixes
+- Dependencies with known vulnerabilities that nobody updates
+- Documentation that references systems that no longer exist
+
+**Response:** Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It still works, why remove it?" | Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently. |
+| "Someone might need it later" | If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding. |
+| "The migration is too expensive" | Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term. |
+| "We'll deprecate it after we finish the new system" | Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now. |
+| "Users will migrate on their own" | They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule). |
+| "We can maintain both systems indefinitely" | Two systems doing the same thing is double the maintenance, testing, documentation, and onboarding cost. |
+| "Just rename the column, it's one line" | During the rollout, old and new code run together — one will query a column that no longer exists. Expand/contract, never rename in place. |
+| "I'll add the column and drop the old one in the same migration" | That couples a safe add to a destructive drop. Drops get their own deploy, after no code references the old shape. |
+| "We'll write the rollback if we need it" | A migration with no down path is a deploy you can't reverse. Write and run the `down` before merging. |
+
+## Red Flags
+
+- Deprecated systems with no replacement available
+- Deprecation announcements with no migration tooling or documentation
+- "Soft" deprecation that's been advisory for years with no progress
+- Zombie code with no owner and active consumers
+- New features added to a deprecated system (invest in the replacement instead)
+- Deprecation without measuring current usage
+- Removing code without verifying zero active consumers
+- A schema change and the code that depends on it shipped in the same deploy
+- A column renamed or dropped in place rather than via expand/contract
+- A migration merged with no tested down path, or a backfill that locks the table
+
+## Verification
+
+After completing a deprecation:
+
+- [ ] Replacement is production-proven and covers all critical use cases
+- [ ] Migration guide exists with concrete steps and examples
+- [ ] All active consumers have been migrated (verified by metrics/logs)
+- [ ] Old code, tests, documentation, and configuration are fully removed
+- [ ] No references to the deprecated system remain in the codebase
+- [ ] Deprecation notices are removed (they served their purpose)
+
+After a database schema migration:
+
+- [ ] The change ships in additive phases (expand → backfill → contract), not a single in-place edit
+- [ ] Old and new code are both valid against the schema at every deploy step
+- [ ] Each migration has a tested down path; backfills run in throttled batches
+- [ ] Destructive steps (drop/rename) ship in their own deploy after no code references the old shape