swe-workflow-skills 0.1.0

package/skills/dependency-impact-analysis/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: dependency-impact-analysis
+description: "Map the blast radius of a change before implementing — find dependents, classify breaking vs additive, identify coordination needs, produce a propagation plan. Triggers: what will break if I change this, blast radius, impact analysis, breaking change, who depends on this, downstream impact, safe to rename, shared schema change, dependency graph."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Dependency Impact Analysis
+
+Understand what will break before breaking it. Changing a shared component without mapping its dependents leads to cascading failures — often discovered in production.
+
+## Step 1: Define the Change
+
+Be precise about what is changing:
+
+- **What is the component?** (API endpoint, database table/column, library function, event schema, shared module)
+- **What specifically is changing?** (Field renamed, parameter added, type changed, behavior changed, endpoint removed)
+- **What is the deployment boundary?** (Single service, multiple services, public API accessible by external clients)
+
+A vague "I'm changing the user model" is too broad. "I'm renaming the `email` field to `email_address` in the users table and the User API response" is specific enough to analyze.
+
+## Step 2: Map All Dependents
+
+Find everything that depends on the component being changed.
+
+**For API endpoints:**
+- Search for the endpoint path across all service repositories
+- Check API gateway logs for callers (especially for public APIs)
+- Review API documentation and SDKs for external consumers
+- Check internal service-to-service call graphs or service mesh metrics
+
+**For database tables/columns:**
+- Search all codebases for table name and column name references
+- Check ORM models, raw SQL queries, stored procedures, migration files
+- Look for database views, triggers, or materialized views that reference the column
+- Check reporting tools and data pipelines that read from the table directly
+
+**For shared libraries/packages:**
+- Check the package registry or dependency graph for what imports this library
+- Search for the specific function/class/type being changed across all consumers
+- Check version constraints — which consumers would receive this change automatically?
+
+**For event schemas:**
+- Find all producers of this event type
+- Find all consumers (subscribers) of this event type
+- Check event replay systems or data warehouses that store these events
+
+**For shared modules/types:**
+- Search the codebase for all import statements referencing the module
+- Check generated clients (OpenAPI codegen, gRPC stubs) that depend on the schema
+
+## Step 3: Classify Impact by Dependent
+
+For each dependent found, classify the impact:
+
+| Impact type | Definition | Action required |
+|-------------|-----------|----------------|
+| **Breaking** | Dependent will fail or produce wrong results without modification | Must coordinate: update before or simultaneously |
+| **Additive** | Change adds capability but doesn't break existing behavior | No action required; dependent can opt in |
+| **Internal** | Change is within a single service, no external interface changes | No coordination needed |
+| **Latent** | Dependent doesn't use the changed part yet, but may assume current behavior | Monitor; communicate the change |
+
+**Breaking change examples:**
+- Renaming a required request field
+- Changing a field type
+- Removing an endpoint
+- Adding a required (non-nullable, no default) column to a table
+- Changing event schema to remove a field
+
+**Additive change examples:**
+- Adding a new optional field to a response
+- Adding a new endpoint
+- Adding a nullable column with a default
+- Deprecating (but not removing) a field
+
+## Step 4: Produce the Change Propagation Plan
+
+For each breaking change, define the coordination plan:
+
+**Option A: Simultaneous deploy** (for small, closely-coupled services under one team)
+- Update all dependents in the same deployment window
+- Risk: all services must be deployed together — failure in one blocks all
+
+**Option B: Versioned transition** (recommended for shared APIs)
+1. Deploy v2 of the interface alongside v1 (both exist simultaneously)
+2. Migrate consumers to v2 one by one
+3. Remove v1 once all consumers have migrated
+
+**Option C: Expand-contract** (recommended for database and event schema changes)
+1. Expand: add new field/column alongside old (both exist, old still works)
+2. Migrate: update consumers to use new field
+3. Contract: remove old field after all consumers are migrated
+
+**Communication plan:**
+- Which teams own dependent services?
+- How will they be notified?
+- What is the migration deadline?
+- Is there a deprecation period?
+
+## Principles Applied
+
+- **Functional independence**: Minimize blast radius — prefer additive changes over breaking changes when both achieve the same goal
+- **KISS**: The simplest propagation plan is the one with the fewest simultaneous moving parts. Prefer sequential migration over big-bang deploys.
+- **YAGNI**: Don't change more than necessary. If the change can be made additive (old behavior still works), prefer that over a breaking change.
+- **Explicit over implicit**: Undocumented contracts are the most dangerous dependencies — they're discovered when broken, not before
+
+## Cross-Skill References
+
+- `api-design` — design the new API contract after impact is understood
+- `feature-planning` — incorporate the dependency coordination into the implementation plan
+- `architecture-design` — if analysis reveals excessive coupling, document an ADR for reducing it
+- `data-modeling` — use for schema change design once impact is mapped
+- `deployment-repo` — when impact crosses repo boundaries in a polyrepo, use the deployment repo's compatibility matrix and contract tests to validate migration paths

package/skills/dependency-impact-analysis/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "dependency-impact-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to rename the 'user_id' field to 'account_id' in our REST API response for GET /api/users. We have a mobile app, a web app, and two internal microservices that call this endpoint. What's the impact?",
+      "expected_output": "Dependency impact analysis identifying all four consumers, classifying the rename as breaking for all of them, recommending a versioning strategy, and producing a migration plan with coordination steps",
+      "assertions": [
+        "Identifies all four consumers (mobile app, web app, two microservices) as affected",
+        "Classifies this as a breaking change for all consumers (field rename, not additive)",
+        "Flags mobile app as highest risk (users may not update; old app versions still call the API)",
+        "Recommends API versioning (v1 keeps user_id, v2 uses account_id) for the mobile app case",
+        "Produces a migration sequence: add v2, migrate internal consumers, migrate web, sunset v1 after mobile migration window",
+        "Does not suggest a simultaneous big-bang rename as the only option"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I'm adding a new optional 'metadata' JSON column to the orders table. Is this safe to deploy?",
+      "expected_output": "Classifies this as an additive/backwards-compatible change requiring minimal coordination, confirms it's safe to deploy without consumer updates, and notes any edge cases",
+      "assertions": [
+        "Confirms this is a backwards-compatible (additive) change",
+        "Notes that existing code ignores the new column and remains safe",
+        "May mention that ORM models should be updated to avoid unexpected behavior when they serialize full rows",
+        "Does not require complex coordination or versioning",
+        "Gives a clear 'safe to proceed' verdict with any minor caveats"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "How do I add authentication to this endpoint?",
+      "expected_output": "Recognizes this is an API design or security question, not a dependency impact analysis request — redirects to the appropriate skill",
+      "assertions": [
+        "Recognizes this is not a dependency impact analysis request",
+        "Does not perform a blast radius analysis for adding auth",
+        "May note that adding required auth to an existing endpoint is a breaking change for current consumers (brief impact observation)",
+        "Directs to security-audit or api-design skill for the actual implementation guidance"
+      ]
+    }
+  ]
+}

package/skills/dependency-impact-analysis/references/impact-patterns.md

@@ -0,0 +1,150 @@
+# Impact Patterns
+
+## API Versioning Strategies
+
+### URL versioning
+```
+/api/v1/users/{id}
+/api/v2/users/{id}
+```
+Simplest to implement. Consumers explicitly opt into the new version. Old version remains accessible until deprecated.
+
+**When to use**: Public APIs with external consumers. Breaking changes are unavoidable.
+
+**Deprecation process**:
+1. Announce deprecation with sunset date (minimum 6 months for external consumers)
+2. Add `Deprecation` header to responses: `Deprecation: Sat, 01 Jan 2026 00:00:00 GMT`
+3. Monitor v1 traffic to track migration progress
+4. Sunset v1 after deadline
+
+### Header versioning
+```
+Accept: application/vnd.myapi.v2+json
+```
+Cleaner URLs. More complex routing. Use when URL versioning breaks REST resource semantics.
+
+### Query parameter versioning
+```
+GET /api/users/{id}?version=2
+```
+Easy to test in browser. Explicit but verbose. Common for internal APIs with few consumers.
+
+### No versioning (evolve in place)
+Only works if all changes are additive. Works well for internal services where you control all consumers and can coordinate deploys.
+
+---
+
+## Database Migration Coordination
+
+### Single-service database
+All reads and writes go through one service that owns the schema. Migration coordination is just within that service.
+
+**Safe upgrade sequence**:
+1. Deploy migration (schema change)
+2. Deploy application code that uses new schema
+
+**Rollback**: reverse migration + revert code deploy.
+
+### Shared database (multiple services read the same tables)
+The most dangerous architecture for migrations. Any schema change can break other services.
+
+**Rules for shared database migrations**:
+1. **Never drop a column** without verifying no other service reads it
+2. **Never rename a column** without an expand-contract migration
+3. **Adding NOT NULL constraints** on existing columns requires a default value or coordinated deploy
+4. Always search all service codebases for references to the table/column before migrating
+
+**Migrate shared tables using expand-contract**:
+```
+Step 1: Add new_column alongside old_column (both present)
+Step 2: Deploy service A to write to both columns, read from old_column
+Step 3: Deploy all other services to read from new_column
+Step 4: Deploy service A to write only to new_column
+Step 5: Drop old_column
+```
+
+### Zero-downtime migrations
+For large tables where schema changes lock the table:
+
+**Postgres**: Use `ALTER TABLE ... ADD COLUMN ... DEFAULT NULL` (instant) then backfill asynchronously. Adding a default value to a new column in Postgres 11+ is instant.
+
+**Avoid in production**:
+- `ALTER TABLE ... ADD COLUMN ... NOT NULL` (requires table scan + lock pre-Postgres 11)
+- `CREATE INDEX` without `CONCURRENTLY` (locks entire table)
+- `ALTER TABLE ... SET NOT NULL` on a column that may contain nulls
+
+---
+
+## Event Schema Evolution
+
+### Backwards-compatible event changes
+- Adding new optional fields
+- Adding new event types (consumers ignore unknown types)
+- Loosening validation (accepting more values)
+
+### Breaking event changes
+- Removing fields consumers depend on
+- Changing field semantics (same name, different meaning)
+- Tightening validation (rejecting previously-valid values)
+- Changing the primary identifier field
+
+### Schema registry approach (for Kafka/event streaming)
+Use a schema registry (Confluent Schema Registry, AWS Glue) to enforce compatibility:
+
+- **BACKWARD**: New schema can read data written by old schema (consumer can be updated first)
+- **FORWARD**: Old schema can read data written by new schema (producer can be updated first)
+- **FULL**: Both backward and forward compatible (safest; most restrictive)
+
+### Consumer-first pattern (no schema registry)
+For breaking changes without a schema registry:
+1. Deploy consumers that handle both old and new schema (check for field presence before using it)
+2. Deploy producers using new schema
+3. Remove old schema handling from consumers once all producers are updated
+
+---
+
+## Shared Library Change Coordination
+
+### Semantic versioning
+- **PATCH** (1.0.x): Bug fixes, no API changes. Consumers upgrade safely.
+- **MINOR** (1.x.0): New additive features. Old code still works. Consumers can upgrade when ready.
+- **MAJOR** (x.0.0): Breaking changes. Consumers must update their code to use the new version.
+
+### Monorepo vs. multi-repo impact
+**Monorepo**: All dependents are visible. Tooling (Nx, Turborepo, Bazel) can identify which services are affected. Breaking library change requires updating all consumers in the same PR/release.
+
+**Multi-repo**: Consumers are on different release cycles. Use semantic versioning + deprecation period. Old major version must be maintained until all consumers migrate.
+
+### Lock files and version pinning
+Consumers with pinned versions won't receive the change automatically. Must explicitly update their dependency. This provides safety (can choose when to migrate) but also means old versions can persist indefinitely.
+
+---
+
+## Finding Dependents Quickly
+
+### Grep patterns for common dependency types
+
+**REST endpoint consumers:**
+```bash
+grep -r "GET /api/users" --include="*.{ts,js,py,go,rb}" .
+grep -r "POST /api/orders" --include="*.{ts,js,py,go,rb}" .
+```
+
+**Database column references:**
+```bash
+grep -r "\.email\b" --include="*.{ts,js,py,go}" .
+grep -r "\"email\"" --include="*.{ts,js,py,go}" .
+grep -r "users\.email" --include="*.{sql}" .
+```
+
+**Function/class references (TypeScript/JavaScript):**
+```bash
+grep -r "import.*UserService" --include="*.ts" .
+grep -r "from.*user-service" --include="*.ts" .
+```
+
+**Package imports:**
+```bash
+grep -r "require.*my-shared-lib" --include="*.js" .
+grep -r "from my_shared_lib" --include="*.py" .
+```

package/skills/dependency-management/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: dependency-management
+description: "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts. Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, WebFetch, WebSearch
+---
+
+# Dependency Management
+
+Help make disciplined decisions about project dependencies. Every dependency is a trade-off: functionality gained vs. maintenance burden, security surface, and coupling accepted.
+
+## Core Rule
+
+**Every dependency should earn its place.** Before adding a dependency, ask: "Is this worth the ongoing cost of maintaining, updating, and trusting someone else's code in my project?"
+
+## Workflow: Evaluating a New Dependency
+
+### Step 1: Do You Need It?
+
+Before evaluating any library, check if the need can be met without one:
+
+- **Is this a few lines of code?** Writing `leftPad` yourself is better than importing it.
+- **Does the language/framework already provide this?** Check built-in APIs first.
+- **Is this a one-time use?** Copy-paste a small utility function instead of adding a dependency.
+
+A dependency is justified when it provides substantial, maintained functionality that would be costly and error-prone to build yourself (e.g., cryptography, date handling with timezones, database drivers, authentication).
+
+### Step 2: Evaluate the Library
+
+For any library under consideration, assess these dimensions:
+
+**Maintenance health:**
+- Last commit date (stale > 1 year is a yellow flag)
+- Open issues and PR response time
+- Number of maintainers (bus factor — 1 maintainer is risky)
+- Release frequency and changelog quality
+
+**Adoption signals:**
+- Weekly downloads / GitHub stars (not definitive, but signals community trust)
+- Used by known projects (check dependents)
+- Ecosystem maturity (plugins, integrations, documentation)
+
+**Technical fit:**
+- TypeScript support (if applicable)
+- Bundle size impact — check on bundlephobia.com or similar
+- API quality — is it intuitive, well-documented, consistent?
+- Compatibility with your runtime, framework version, and other dependencies
+
+**Security and legal:**
+- License compatibility with your project (MIT, Apache-2.0 are permissive; GPL is viral)
+- Known vulnerabilities (check npm audit advisory, Snyk, or GitHub advisories)
+- Does it have excessive transitive dependencies?
+
+**Alternatives comparison:**
+- Identify 2-3 alternatives and compare on the dimensions above
+- A slightly less popular library that's better maintained may be the better choice
+
+See [references/evaluation-checklist.md](references/evaluation-checklist.md) for the structured assessment template.
+
+### Step 3: Present the Recommendation
+
+For the user, summarize:
+- **Recommendation**: Use / Don't use / Consider alternative
+- **Primary reason**: The most compelling argument
+- **Risks accepted**: What you're trading off
+- **Alternatives considered**: Brief comparison
+
+## Workflow: Auditing Existing Dependencies
+
+### Step 1: Run Vulnerability Scanners
+
+```bash
+# JavaScript/TypeScript
+npm audit
+# For more detail:
+npx better-npm-audit audit
+
+# Python
+pip audit
+# or
+safety check
+
+# Go
+govulncheck ./...
+
+# Ruby
+bundle audit check --update
+```
+
+### Step 2: Triage Results
+
+Not all vulnerabilities require action. For each finding:
+
+1. **Is the vulnerable code path actually used in your project?** Many CVEs affect specific features you may not use.
+2. **What's the severity?** Critical and High need immediate action. Medium within a sprint. Low can be tracked.
+3. **Is a patched version available?** If yes, upgrade. If no, assess mitigation or replacement.
+4. **Is it a transitive dependency?** You may need to upgrade the parent package, or use overrides/resolutions.
+
+### Step 3: Find Unused Dependencies
+
+Dead dependencies add attack surface and bloat for zero value.
+
+```bash
+# JavaScript — find unused packages
+npx depcheck
+
+# Python — find unused imports (suggests unused packages)
+pip install vulture
+vulture src/ --min-confidence 80
+```
+
+Remove unused dependencies. If unsure, comment it out, run tests, and deploy to staging.
+
+### Step 4: Produce the Report
+
+Summarize: N vulnerabilities found (X critical, Y high), N unused packages, N significantly outdated.
+
+## Workflow: Major Version Upgrades
+
+### Step 1: Read the Changelog
+
+Read the changelog and migration guide for the new major version. Identify:
+- **Breaking changes**: What will break in your code?
+- **Deprecations resolved**: What deprecated APIs were removed?
+- **New features**: Anything that simplifies your code?
+- **Peer dependency changes**: Does this force other upgrades?
+
+### Step 2: Plan the Upgrade
+
+For low-risk upgrades (well-documented, small surface area):
+- Create a branch, bump the version, run tests, fix failures.
+
+For high-risk upgrades (framework major version, ORM, auth library):
+- Create a detailed task list of changes needed
+- Test in isolation first if possible
+- Consider running old and new versions in parallel temporarily (expand-contract)
+- Suggest using the `feature-planning` skill to break the upgrade into tasks
+
+### Step 3: Validate
+
+- [ ] All tests pass
+- [ ] No deprecation warnings from the upgraded package
+- [ ] No new vulnerabilities introduced by the upgrade
+- [ ] Lock file is committed and clean
+- [ ] Bundle size has not increased unexpectedly
+
+## Quick Reference: Lock File Hygiene
+
+- **Always commit lock files** (`package-lock.json`, `yarn.lock`, `poetry.lock`, `go.sum`)
+- **Never edit lock files manually** — let the package manager manage them
+- **Use `npm ci` (not `npm install`) in CI** — installs from lock file exactly
+- **Review lock file diffs in PRs** — large unexpected changes signal problems
+- **Regenerate periodically** if the lock file becomes stale or conflicted
+
+## Principles Applied
+
+- **YAGNI**: Don't add a library for a feature you *might* need. Add it when the need is real and proven.
+- **KISS**: Prefer libraries with small, focused APIs over Swiss-army-knife frameworks.
+- **DRY**: A well-chosen dependency eliminates duplication across projects — but a bad choice creates maintenance debt across projects.
+- **Functional Independence**: Prefer libraries that don't deeply couple to your application architecture. You should be able to swap them out.
+- **Boundaries**: Wrap third-party APIs with thin adapter layers — depend on your own abstractions, not on library specifics. This limits blast radius when a dependency changes or is replaced, and keeps your business logic free of third-party types. Only skip wrapping for pervasive infrastructure (e.g., your web framework, your ORM) where the cost of wrapping exceeds the cost of coupling.

package/skills/dependency-management/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "skill_name": "dependency-management",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building a Node.js API and need a validation library. I'm considering zod, joi, yup, and ajv. Which should I use? Our stack is TypeScript, Express, and Prisma.",
+      "expected_output": "Should evaluate all four libraries across the standard dimensions (maintenance, TS support, bundle size, API quality) and make a clear recommendation based on the TypeScript stack.",
+      "assertions": [
+        "Evaluates all four options, not just recommends one without comparison",
+        "Considers TypeScript integration as a key differentiator",
+        "Notes zod's TypeScript-native schema-to-type inference as a strong fit",
+        "Compares bundle sizes",
+        "Compares API ergonomics with brief examples",
+        "Makes a clear recommendation with primary reason",
+        "Does not dismiss alternatives without explanation"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "npm audit shows 47 vulnerabilities: 3 critical, 8 high, 15 moderate, 21 low. I don't know where to start. Help me triage this.",
+      "expected_output": "Should guide triage by severity, distinguish direct vs transitive dependencies, check if vulnerable code paths are actually used, and produce an action plan.",
+      "assertions": [
+        "Starts with critical vulnerabilities, not the full list",
+        "Distinguishes between direct and transitive dependencies",
+        "Asks about or checks whether vulnerable code paths are actually exercised",
+        "Suggests npm audit fix --force ONLY with caution (can introduce breaking changes)",
+        "Recommends overrides/resolutions for transitive deps when parent hasn't updated",
+        "Identifies that many moderate/low findings may be acceptable risk",
+        "Produces a prioritized action plan, not just 'fix everything'"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need to upgrade React from v17 to v19. We have a large codebase with 200+ components. Some use class components and legacy context API. How should we approach this?",
+      "expected_output": "Should recommend a phased approach (17→18→19), identify the major breaking changes at each step, suggest using the feature-planning skill to break this into tasks, and warn about class component and legacy API issues.",
+      "assertions": [
+        "Recommends incremental upgrade (17→18 first, then 18→19), not direct 17→19",
+        "Identifies class components and legacy context as migration blockers",
+        "Lists the key breaking changes at each major version boundary",
+        "Suggests codemods for automated migration where available",
+        "Recommends comprehensive test coverage before starting",
+        "Suggests feature-planning skill to break into manageable tasks",
+        "Warns about the scope and risk — this is not a one-afternoon task",
+        "Recommends testing in isolation before merging to main"
+      ]
+    }
+  ]
+}

package/skills/dependency-management/references/evaluation-checklist.md

@@ -0,0 +1,127 @@
+# Dependency Evaluation Checklist
+
+## Contents
+- Structured assessment template
+- License compatibility guide
+- Red flags to watch for
+- Bundle size guidelines
+- Common decisions by category
+
+## Structured Assessment Template
+
+Use this template when evaluating a library for adoption:
+
+```markdown
+## Dependency Evaluation: [library-name]
+
+**Purpose**: [What does it do? Why do we need it?]
+**Alternative to**: [What we're using now, or "nothing — new capability"]
+**Evaluated on**: [Date]
+
+### Maintenance Health
+- Last release: [date]
+- Commits in last 6 months: [number]
+- Open issues / total issues: [ratio]
+- Maintainers: [number, names if notable]
+- Bus factor concern? [Yes/No]
+
+### Adoption
+- Weekly downloads: [number]
+- GitHub stars: [number]
+- Notable dependents: [projects]
+- Stack Overflow questions: [rough count]
+
+### Technical Fit
+- TypeScript types: [built-in / @types / none]
+- Bundle size (minified + gzipped): [KB]
+- Transitive dependencies: [count]
+- Compatible with our [framework] version? [Yes/No]
+- API quality: [Good / Acceptable / Poor]
+
+### Security & Legal
+- License: [license type]
+- Compatible with our project? [Yes/No]
+- Known vulnerabilities: [count / none]
+- Security advisory history: [clean / concerning]
+
+### Alternatives Considered
+| Criteria | [Library A] | [Library B] | [Library C] |
+|----------|-------------|-------------|-------------|
+| Bundle size | | | |
+| TypeScript | | | |
+| Maintenance | | | |
+| API quality | | | |
+| Adoption | | | |
+
+### Decision
+**Recommendation**: [Adopt / Don't adopt / Adopt alternative X]
+**Rationale**: [1-2 sentences]
+**Risks accepted**: [What we're giving up]
+```
+
+## License Compatibility Guide
+
+| License | Commercial Use | Can Modify | Must Disclose Source | Viral |
+|---------|---------------|------------|---------------------|-------|
+| MIT | ✓ | ✓ | No | No |
+| Apache 2.0 | ✓ | ✓ | No (but must include license) | No |
+| BSD 2/3 | ✓ | ✓ | No | No |
+| ISC | ✓ | ✓ | No | No |
+| GPL 2/3 | ✓ | ✓ | Yes — your code must also be GPL | **Yes** |
+| LGPL | ✓ | ✓ | Only for modifications to the library | Partially |
+| AGPL | ✓ | ✓ | Yes — even for SaaS/network use | **Yes** |
+| BSL | Varies | ✓ | After time period | Varies |
+| Unlicense | ✓ | ✓ | No | No |
+
+**Safe for most projects**: MIT, Apache 2.0, BSD, ISC, Unlicense
+**Requires legal review**: GPL, LGPL, AGPL, BSL, any custom license
+**Red flag**: No license file at all — technically you have no right to use it
+
+## Red Flags
+
+**Maintenance red flags:**
+- No commits in 12+ months with open issues
+- Single maintainer who has gone silent
+- Repository archived or marked as deprecated
+- No changelog or release notes for major versions
+
+**Quality red flags:**
+- No tests in the repository
+- Many open issues with the "bug" label and no response
+- Breaking changes in minor/patch versions (doesn't follow semver)
+- Excessive transitive dependencies (a utility library with 50+ deps)
+
+**Security red flags:**
+- Known unpatched vulnerabilities
+- History of supply chain attacks on this package
+- Maintainer account compromise history
+- Obfuscated or minified source code in the published package
+
+## Bundle Size Guidelines
+
+Context for JavaScript frontend projects:
+
+| Category | Acceptable | Concerning | Excessive |
+|----------|-----------|------------|-----------|
+| Utility (lodash-like) | < 5 KB | 5-20 KB | > 20 KB |
+| UI component | < 15 KB | 15-50 KB | > 50 KB |
+| State management | < 10 KB | 10-30 KB | > 30 KB |
+| Date library | < 10 KB | 10-30 KB | > 30 KB |
+| Charting | < 50 KB | 50-150 KB | > 150 KB |
+| Full framework | < 50 KB | 50-100 KB | > 100 KB |
+
+Check with: `bundlephobia.com` or `npm pack && tar -tzf *.tgz | wc -l`
+
+For backend projects, bundle size matters less — focus on transitive dependency count and startup time impact.
+
+## Common Decisions by Category
+
+| Need | Recommended Approach |
+|------|---------------------|
+| **Date handling** | Use `Intl.DateTimeFormat` (built-in) for formatting. Add `date-fns` only for complex date math. Avoid `moment` (deprecated, huge). |
+| **HTTP client** | Use built-in `fetch` (Node 18+, all browsers). Add `ky` or `ofetch` for convenience wrappers only if needed. |
+| **Validation** | `zod` for TypeScript (schema + types). `joi` for JavaScript. Built-in validators for simple cases. |
+| **UUID generation** | `crypto.randomUUID()` (built-in Node 19+, all browsers). Add `uuid` only for v1/v5 or older runtimes. |
+| **Cryptography** | Always use built-in `crypto` module or `bcrypt`/`argon2`. Never implement your own. |
+| **Testing** | `vitest` for Vite projects, `jest` for everything else. Both are comprehensive enough to avoid extra test utilities. |
+| **Linting** | `eslint` with `typescript-eslint`. `biome` as a faster alternative. Avoid stacking too many plugins. |